Installer et gérer les GroundRunners

Les GroundRunners permettent aux chaînes de commandement d'interagir avec des systèmes sur site ou des sources de données distantes qui ne sont pas accessibles par l'internet. Ils sont généralement installés sur un serveur dédié, tel que celui qui héberge votre source de données connectée, par un professionnel de l'informatique ou une personne connaissant bien les paramètres du réseau de votre organisation.

Avant de configurer un GroundRunner, nous vous recommandons de consulter l'architecture de sécurité de Chain Builder.

Exigences

Un système d'exploitation compatible est nécessaire, et si votre GroundRunner doit accéder à des ressources partagées telles qu'un chemin d'accès Windows Universal Naming Convention (UNC), un compte d'utilisateur avec des privilèges suffisants est également nécessaire.

Un environnement d’exécution Java (JRE) n’est pas installé avec le GroundRunner lors de l’installation initiale du GroundRunner.

Une fois l'installation terminée et le GroundRunner lancé, celui-ci téléchargera automatiquement un JRE si nécessaire pour exécuter les commandes qui nécessitent Java. Aucune installation ou intervention de l’administrateur n’est nécessaire, et le JRE récupéré n’affectera pas les installations JRE existantes si elles existent sur l’hôte.

Par ailleurs, si vous avez des exigences organisationnelles qui requièrent l’utilisation d’un JRE particulier, la variable d’environnement SHARED_LIBRARY_OVERRIDES peut être définie de manière à pointer vers l’installation du système. Dans ce cas, le GroundRunner ne téléchargera pas automatiquement le JRE standard de Workiva, et utilisera l’installation du JRE système fourni.

Les JRE fournis par Workiva sont sous licence GPL v2, et sont couverts par l’exception classpath .

Note : Pour utiliser des certificats personnalisés avec votre installation Java, voir Utiliser des certificats personnalisés avec les GroundRunners.

À l’heure actuelle, GroundRunners peut être installé sur les familles de systèmes d’exploitation suivantes, sans aucune dépendance à l’égard de bibliothèques externes :

Windows et Windows Server
Distributions Linux et dérivés :
- RedHat, Fedora, AmazonLinux
- Debian/Ubuntu
macOS (à des fins de test uniquement)

Workiva s’efforce de prendre en charge toutes les versions modernes des familles de systèmes d’exploitation énumérées ci-dessus. Toutefois, nous ne pouvons pas prendre en charge un système d’exploitation désigné comme étant « en fin de vie » par son fournisseur. Ces anciens systèmes d’exploitation présentent des risques potentiels pour la sécurité et doivent être mis à jour dès que possible. En savoir plus sur notre politique de fin de vie.

Note : Le calendrier de support de chaque système d’exploitation est fixé par le fournisseur concerné. Par exemple, le support de Microsoft pour Windows 7 a pris fin le 14 janvier 2020 ; celui de Workiva pour Windows 7 a pris fin à la même date.

Exigences en matière de matériel

Bien que GroundRunners ne nécessite que peu de ressources serveur, nous recommandons au minimum :

512 Mo de mémoire vive (RAM) disponible
100 Go d’espace disque disponible

Note : Pour vous aider à calculer l’espace disque nécessaire, sachez qu’une chaîne de cinq commandes produisant chacune des sorties éphémères de 10 Mo nécessite 50 Mo pour être terminée.

La configuration recommandée de l’hôte comprend une machine virtuelle configurée avec :

Deux à quatre processeurs

Note : Les processeurs ARM ne sont pas compatibles avec les GroundRunners.
8 Go de mémoire système
Un dispositif de stockage de type SSD

Ce serveur doit être disponible 24 heures sur 24 et 7 jours sur 7 pour communiquer avec le GroundRunner.

Par défaut, les GroundRunners utilisent un compte administratif local sans accès aux ressources distantes telles que les lecteurs partagés.

Pour accéder à une ressource partagée telle qu'un chemin UNC Windows, démarrez le GroundRunner sous un compte d'utilisateur disposant des privilèges adéquats pour la ressource. Si vous utilisez un compte d'utilisateur autre que l'administrateur du système local par défaut, accordez-lui des autorisations pour gérer le répertoire d'installation du GroundRunner afin d'activer les mises à jour automatiques.

Exigences du poste

Sur la plateforme Workiva

Sur la plateforme Workiva, vous devez disposer d'un rôle qui vous donne accès aux paramètres de Chain Builder et vous permette de gérer les Runners. Il y en a deux :

Responsable de la chaîne : Il s'agit du rôle principal requis. Les utilisateurs disposant de ce rôle peuvent accéder à la section « Téléchargements » de Chain Builder pour récupérer les derniers fichiers d'installation de GroundRunner et gérer l'onglet « Runners » afin d'activer ou de surveiller le service.
Administrateur de la sécurité de la chaîne organisationnelle : Ce rôle au niveau organisationnel dispose également des autorisations nécessaires pour gérer les connexions et les « runners » dans plusieurs espaces de travail.

Sur le serveur

Étant donné qu'une « mise à jour manuelle » implique l'arrêt des services et le remplacement des fichiers exécutables sur la machine physique ou virtuelle où GroundRunner est installé, l'utilisateur doit disposer de droits d'administrateur sur le serveur hôte.

Windows : Vous devez pouvoir exécuter l'invite de commande en tant qu'administrateur et accéder au Gestionnaire de services Windows (pour arrêter et redémarrer le service GroundRunner).
Linux/macOS : Vous devez disposer d'un accès sudo ou root pour déplacer des fichiers dans le répertoire d'installation et redémarrer le processus d'arrière-plan.

Télécharger le GroundRunner

Pour télécharger un GroundRunner en vue d'une installation ou d'une mise à jour manuelle :

Dans la barre latérale de Workiva Home, cliquez sur Chains.
Dans la barre latérale Chain Builder (il s’agit d’un nouvel onglet), cliquez sur Connections.

Vous pouvez également cliquer sur l'icône de profil utilisateur en haut à droite, sélectionner « » (Chaînes d'administration), puis « » (Paramètres de l'espace de travail).
Cliquez sur Downloads dans la barre de menu supérieure.
Trouvez le GroundRunner correspondant à votre système d’exploitation et cliquez sur Download pour l’obtenir.
Une fois qu’il a été téléchargé avec succès sur votre ordinateur, sélectionnez les instructions appropriées dans la série ci-dessous et suivez-les pour installer le GroundRunner.

Installer le GroundRunner

Le programme d'installation Microsoft (MSI) nécessite .NET 3.5 ou une version plus récente.
Si vous ne pouvez pas respecter cette condition, vous devrez installer GroundRunner via l'interface de ligne de commande.

Pour installer le GroundRunner :

Dézippez GroundRunner.zip dans un nouveau dossier et ouvrez-le.
Exécutez le fichier « GroundRunner.msi » pour ouvrir l'assistant d'installation de GroundRunner.
Cliquez sur Suivant.
Passez en revue et acceptez les termes du contrat de licence, puis cliquez sur Next.
Dans le champ « Destination Folder », saisissez le chemin d'accès où GroundRunner sera installé (par exemple : C:\Program Files\GroundRunner\), puis cliquez sur « Next ».
Dans la section « Token de l'entreprise » de la plateforme (), saisissez le token de votre entreprise ().
Dans Platform auth host:
- Pour la région APAC, rendez-vous sur h.apac.wdesk.com/s/chains-reaper.
- Pour le Canada, saisissez h.ca.wdesk.com/s/chains-reaper.
- Pour la région EMEA, rendez-vous sur h.eu.wdesk.com/s/chains-reaper.
- Pour les États-Unis, l'Amérique centrale et l'Amérique du Sud, saisissez h.app.wdesk.com/s/chains-reaper.
Si vous utilisez un serveur proxy, saisissez son URL et son port dans Hôte proxy.
(Par exemple, http://yourproxy:3000.)
Pour contourner le serveur proxy, saisissez une liste d'hôtes séparés par des virgules sous « No proxy host ».
Cliquez sur Next, Install, et Finish.
Une fois l'installation terminée, cliquez avec le bouton droit de la souris sur « GroundRunner » dans le Gestionnaire de services Windows, puis sélectionnez « Démarrer » ( ).

Votre GroundRunner est maintenant installé et prêt à être activé.

Pour effectuer l'installation via l'interface de ligne de commande, vous devez télécharger le programme d'installation de GroundRunner dans un répertoire dédié au sein de votre dossier « Program Files » (par exemple : c:\Program Files (x86)\wdata). Vous pouvez ensuite décompresser le fichier d'installation et l'extraire à la racine de ce répertoire.

Vous pouvez ensuite installer GroundRunner :

Dans la fenêtre de commande Windows, tapez
```
c:\Program Files (x86)\wdata\installer.exe install
```
et accepter toutes les valeurs par défaut.
- Sélectionnez « Windows » comme système d'initialisation.
  
  Vous devez indiquer que GroundRunner doit fonctionner en tant que service Windows pour que les mises à jour automatiques soient prises en charge. GroundRunners ne doit être exécuté qu’en tant que service, sauf à des fins de test.
- Pour le chemin d'accès, créez un dossier « Files » dans le nouveau répertoire «
  » (par exemple, C:\Program Files (x86)\Wdata\Files).
- Pour le nom d'hôte d'autorisation (AUTH_HOST) :
  - Pour la région APAC, rendez-vous sur h.apac.wdesk.com/s/chains-reaper.
  - Pour le Canada, saisissez h.ca.wdesk.com/s/chains-reaper.
  - Pour la région EMEA, rendez-vous sur h.eu.wdesk.com/s/chains-reaper.
  - Pour les États-Unis, l'Amérique centrale et l'Amérique du Sud, saisissez h.app.wdesk.com/s/chains-reaper.
- Saisissez le jeton de votre entreprise .
Supprimer tous les fichiers du répertoire à l'exception du répertoire de l'exécutable GroundRunner.
Choisissez d'exécuter le GroundRunner en tant que service ou en tant que processus d'avant-plan.
- S'il s'agit d'un service, effectuez l'une des opérations suivantes :
  - Dans la boîte de dialogue de commande, saisissez sc start GroundRunner.
  - Dans le Gestionnaire de services Windows, démarrez le service « GroundRunner».
- Si le processus s'exécute en avant-plan, saisissez la commande suivante dans la boîte de dialogue de commande :
```
cd c:\Program Files (x86)\wdata GroundRunner.exe
```

Votre GroundRunner est désormais installé et prêt à être activé.

Etape 1. Installer le GroundRunner

Téléchargez le fichier d'installation de GroundRunner dans un répertoire dédié, par exemple «
» : /home/user_name/wdata/.

Remarque : « /home/user_name/wdata » est donné à titre d'exemple. Respectez la politique de votre organisation concernant les lieux d'installation des services.
Dans une fenêtre de commande, décompressez le fichier d'installation à l'aide de la commande suivante :
```
décompressez le fichier GroundRunner.zip
```
Saisissez les informations relatives au GroundRunner.
1. Tapez : ./installer install
2. Pour le nom d'hôte d'autorisation (AUTH_HOST) :
  - Pour la région APAC, rendez-vous sur h.apac.wdesk.com/s/chains-reaper.
  - Pour le Canada, saisissez h.ca.wdesk.com/s/chains-reaper.
  - Pour la région EMEA, rendez-vous sur h.eu.wdesk.com/s/chains-reaper.
  - Pour les États-Unis, l'Amérique centrale et l'Amérique du Sud, saisissez h.app.wdesk.com/s/chains-reaper.
3. Saisissez le jeton de votre entreprise .
Supprimez tous les fichiers du répertoire, à l'exception du dossier créé lors de l'installation.

Étape 2. Configurez votre GroundRunner en tant que service systemd (Linux)

Pour garantir le bon fonctionnement des mises à jour automatiques de GroundRunner et assurer une bonne gestion de GroundRunner, celui-ci doit être installé en tant que service systemd activé et redémarrable. Veuillez vous reporter à la documentation de votre système d'exploitation et à la politique de votre organisation pour savoir comment exécuter GroundRunner en tant que service systemd.

Pour les configurations de base, voici les exigences relatives aux fichiers d'unité systemd nécessaires au bon fonctionnement des mises à jour automatiques :

Assurez-vous que l'exécutable « ExecStart » de pointe vers le binaire « GroundRunnerMonitor » de et NON vers le binaire « GroundRunner » de
.
Définir Restart=always.
Ne définissez pas les paramètres suivants : , StartLimitBurst ou , StartLimitIntervalSec, car ceux-ci pourraient empêcher le redémarrage du GroundRunner en cas d'erreurs transitoires. Si vous souhaitez éviter que le GroundRunner ne se retrouve pris dans une boucle de redémarrage rapide, vous pouvez configurer RestartSec.
Tapez « systemctl enable » pour activer l'unité de service GroundRunner de systemd, afin que GroundRunner continue de fonctionner après un redémarrage.

Workiva ne prend pas officiellement en charge l'exécution d'un GroundRunner en tant que processus en premier plan. Cela peut s'avérer utile pour tester une configuration, mais, une fois qu'un GroundRunner est configuré, il doit être mis en place en tant que processus d'arrière-plan à exécution continue.

Utilisation de GroundRunners sous macOS (à titre d'essai uniquement)

Workiva prend en charge GroundRunners sur macOS à des fins de test uniquement. Bien que les instances macOS de GroundRunners puissent exécuter les mêmes commandes que les versions Linux et Windows, Workiva ne prend pas officiellement en charge launchd en tant que gestionnaire de services valide. En effet, Apple a cessé de prendre en charge son logiciel serveur macOS en 2022. Les ordinateurs portables et de bureau Apple ne sont pas compatibles avec GroundRunners.

Activer le GroundRunner

Après avoir installé votre GroundRunner, vous devez l'activer dans Chain Builder.

Dans la barre latérale de Chain Builder, cliquez sur Connections.
Cliquez sur Runners en haut de la page, puis cliquez sur Pending Registration.
Saisissez un nom court et descriptif pour le programme.
Par exemple, « <datasource>-GroundRunner ».
Cliquez sur Activer.

Liste de contrôle pour la configuration de GR

Utilisez-vous l'exécutable « GroundRunnerMonitor » de (et non l'exécutable « GroundRunner » de ) ?
Avez-vous configuré votre GroundRunnerMonitor d' en tant que service au niveau du système, pouvant être redémarré ?
- Pour Linux : Systemd.
- Pour Windows : Services Windows.
Votre service redémarre-t-il au redémarrage du système ?
- Sous Linux : ` systemctl enable`.
- Sous Windows : le type de démarrage doit être défini sur « Automatic ».
Utilisez-vous un système d'exploitation serveur pris en charge ?
Avez-vous activé les notifications GroundRunner ?

Mise à jour manuelle d'un GroundRunner

Bien que cela soit rarement nécessaire, il se peut que vous deviez mettre à niveau manuellement un GroundRunner.
Pour savoir comment procéder, consultez la page d'assistance de Workiva ainsi que la mise à jour du manuel GroundRunner.

Désinstaller un GroundRunner

Si vous n'avez plus besoin d'un GroundRunner, vous pouvez le désinstaller.

Dans les paramètres Windows, allez sur Apps & features, sélectionnez GroundRunner (64 bit), et cliquez sur Uninstall.

Arrêtez le service GroundRunner.
- S'il s'exécute en tant que service, utilisez le Gestionnaire de services Windows ou saisissez la commande suivante dans une fenêtre de commande : `
  sc stop GroundRunner `.
- S'il s'exécute en tant que processus au premier plan, appuyez sur Ctrl+C.
Dans la fenêtre de commande, en tant qu'administrateur, saisissez «
installer.exe uninstall ».
Supprimez le répertoire exécutable GroundRunner.

Dans la fenêtre de commande, arrêtez le service GroundRunner et supprimez le répertoire contenant son exécutable (par exemple, /home/<username>/wdata/Contents).

Installation d’un JRE personnalisé

Si nécessaire, vous pouvez installer votre propre JRE pour prendre en charge un GroundRunner. La version Java de ce JRE doit correspondre à celle requise pour le Groundrunner. À l’exception de Oracle Essbase et Oracle Hyperion Financial Management (HFM) GroundRunners, tous les GroundRunners utilisent la même version de JRE.

Pour savoir comment installer un JRE personnalisé, consultez la page . Pour désactiver les bibliothèques partagées de Workiva, consultez la page.

Paramètres de configuration du GroundRunner et domaines sortants

Pour permettre la communication avec sa source de données, il peut être nécessaire d'ouvrir les ports du pare-feu sur le serveur où le GroundRunner est installé. Pour modifier les paramètres de configuration de certains GroundRunners, vous pouvez éditer le fichier GroundRunner.config dans le répertoire où les binaires sont installés.

Configuration	Paramètres
PORT	0 à 65535. Par défaut, les GroundRunners utilisent le port 8821 pour communiquer entre eux. Toutefois, un port n'est nécessaire que si des GroundRunners situés sur des serveurs différents partagent des sorties de commande au sein de votre réseau.
COMPANY_TOKEN	Laisser par défaut, sauf si le GroundRunner est configuré pour un autre locataire.
LOG_LEVEL	Info ou debug
PROTOCOLE	Laisser par défaut.
HTTP_PROXY_URL	Si vous utilisez un serveur proxy, indiquez son URL et son port (si nécessaire). Par exemple, `http ://yourproxy :3000` Note : Les GroundRunners peuvent utiliser des serveurs proxy, mais pas ceux qui sont authentifiés via New Technology LAN Manager (NTLM). Au lieu de cela, autorisez l'adresse IP du serveur.
LONG_POLL	En cas d'utilisation d'un serveur proxy, mettre la valeur true pour indiquer au runner d'utiliser le long-polling pour récupérer les commandes. Pour garantir les performances, n'utilisez l'interrogation longue que si les sockets web ne sont pas pris en charge par votre serveur proxy ou votre pare-feu.
NO_PROXY	Pour contourner le serveur proxy, fournissez une liste d'hôtes séparés par des virgules à atteindre directement à la place. Pour inclure plusieurs hôtes sur la base d'un modèle commun, utilisez le caractère générique *.
GROUNDRUNNER_CERT	Nécessaire si l'on utilise plus d'un GroundRunner et que l'on souhaite envoyer des informations cryptées au second GroundRunner. Ceci doit être utilisé conjointement avec PORT. Vous devez également spécifier que le champ PROTOCOL est HTTPS lors de l'activation de l'unité d'exécution.
CLÉ_CERT_MARCHAND_DE_TERRE	Nécessaire si l'on utilise plus d'un GroundRunner et que l'on souhaite recevoir des informations cryptées d'un second GroundRunner. Ceci doit également être utilisé en conjonction avec PORT.
DISABLE_WEBSOCKETS	Les Websockets sont nécessaires pour exécuter les transformations. Lorsqu’elle est désactivée, toute commande utilisant des transformations sera entièrement ignorée.

Note: Votre certificat auto-signé doit avoir un Subject Alternative Name (SAN). Si ce n'est pas le cas, lorsque votre GroundRunner tentera de télécharger des fichiers, il affichera un message d'erreur faisant référence au SAN manquant.

Si votre réseau doit autoriser les domaines sortants, ceux-ci s'appliquent aux GroundRunners :

Domaine	Objectif
`h.app.wdesk.com` `h.apac.wdesk.com` `h.ca.wdesk.com` `h.eu.wdesk.com`	Les principaux sous-domaines pour les services communs de Workiva, y compris Wdata.
`*.wdesk.com`	Le domaine principal de la plateforme de production Workiva.
`..wdesk.com`	Les sous-domaines pour les composants de soutien dans la plateforme Workiva.

Sécurité

Les GroundRunners ne collectent ni n'agrègent jamais les données ; ils ne les conservent que pendant la transmission. Un certificat de validation étendue (EV) crypte et protège toujours le trafic entre un GroundRunner et sa source de données via DigiCert®.

Remarque : Pour sécuriser les données sur site, les CloudRunners peuvent partager les sorties avec les GroundRunners, mais les GroundRunners ne peuvent pas partager les sorties de fichiers avec les CloudRunners.

Dépannage des erreurs du GroundRunner

Si vous recevez ces erreurs lors de l'exécution d'une chaîne, vérifiez les GroundRunners de la commande.

Conseil : Pour faciliter le dépannage, vous pouvez créer une chaîne pour télécharger automatiquement le fichier journal d’un GroundRunner dans une table.

Message d’erreur	Cause	Résolution
Échec de la communication avec l'agent - cette commande n'a pas été exécutée	Le commandement n'a pas pu communiquer avec son GroundRunner. Si cela se produit, le GroundRunner n’a pas démarré ou une perturbation du réseau s’est produite entre le GroundRunner et Chain Builder.	Vérifier : Le service du GroundRunner fonctionne. Le serveur du GroundRunner est connecté à l'internet.
Impossible de télécharger les ressources associées à la commande. Veuillez contacter l'assistance si l'erreur persiste.	Les coureurs associés aux commandes de ces chaînes ne peuvent pas communiquer entre eux. Cela se produit souvent lorsque les commandes utilisent des runners différents et que le CloudRunner tente d'utiliser un fichier issu d'une commande basée sur le GroundRunner.	Utilisez le même runner pour toutes les commandes de la chaîne. Si les commandes de la chaîne nécessitent plusieurs exécutants, vérifiez qu'aucune commande avec des exécutants au sol ne transmet les sorties de fichiers aux commandes qui utilisent le CloudRunner.
Erreur au démarrage de la commande : `exec : \N"\N[connecteur].exe\N » : le fichier n’existe pas » commandExecutorId=[ID]`	Un logiciel malveillant ou une application antivirus a mal identifié le connecteur et a intercepté sa communication avec le GroundRunner.	Exclure le répertoire d'installation de GroundRunner des analyses de l'application.
Erreurs de certificat	Utilisation de certificats autosignés	Dans de nombreux cas, il sera pratique d'utiliser des certificats auto-signés pour crypter les communications GroundRunner. Si vous utilisez un certificat auto-signé, assurez-vous que le Common Name du certificat correspond à l’URL à laquelle le serveur est accessible. Par exemple, si votre GroundRunner écoute sur le port 8821 et que vous pouvez accéder au serveur depuis votre réseau `localhost`, le nom commun du certificat sera « `localhost` ».
Échec intermittent de la chaîne avec l'erreur suivante : "Connection reset by peer" (réinitialisation de la connexion par l'homologue)	Lorsque plusieurs programmes d'exécution sont installés sur la même machine, ils doivent tous avoir un GUID unique. Si le même GUID est utilisé, les coureurs peuvent se chevaucher et entrer dans une boucle de mise à jour, ce qui entraîne des défaillances occasionnelles de la chaîne.	Nous recommandons une réinstallation complète du GroundRunner.
Les commandes sont ignorées sur GroundRunner mais réussies sur CloudRunner	Les Websockets sont nécessaires pour exécuter les transformations. Lorsque les websockets sont désactivées, les transformations sont entièrement ignorées.	Ouvrez votre fichier de configuration et mettez `DISABLE_WEBSOCKETS=false`.
Erreur de lecture du socket. `Nouvelle tentative de connexion : read tcp <IP> :<Port>-&gt ;<IP> :<Port> : wsarecv : Une tentative de connexion a échoué parce que la partie connectée n’a pas répondu correctement après un certain temps, ou la connexion établie a échoué parce que l’hôte connecté n’a pas répondu.`	Problème de pare-feu interne ou de réseau	Demandez à votre équipe informatique ou réseau interne d’examiner les journaux et la configuration afin de résoudre l’erreur.
read <IP> :<Port>-&gt ;<IP> :<Port> : `wsarecv : Une connexion existante a été fermée de force par l’hôte distant.`	Problème de pare-feu interne ou de réseau	Demandez à votre équipe informatique ou réseau interne d’examiner les journaux et la configuration afin de résoudre l’erreur.

Ressources supplémentaires

Support

Communauté

Portail de support Workiva