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é, il téléchargera automatiquement un JRE si nécessaire pour exécuter les commandes qui dépendent de 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
Distros Linux et dérivés :
- RedHat, Fedora, AmazonLinux
- Debian/Ubuntu
macOS (uniquement pour les tests)

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 ; le support de Workiva pour Windows 7 a pris fin à la même date.

Exigences en matière de matériel

Bien que les GroundRunners requièrent des ressources limitées sur le serveur, nous recommandons au moins :

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 rôle

Sur la plateforme Workiva

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

Propriétaire de la chaîne : Il s'agit du rôle principal requis. Les utilisateurs ayant 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" pour activer ou surveiller le service.
Org Chain Security Admin : Ce rôle de niveau organisationnel a également le pouvoir de gérer les connexions et les coureurs 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ù le GroundRunner est installé, l'utilisateur doit disposer de privilèges administratifs 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 avoir sudo ou root pour déplacer les 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 du profil d'utilisateur en haut à droite, sélectionner Chains admin, puis Workplace Settings.
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 satisfaire à cette exigence, vous devrez installer le GroundRunner à l'aide de l'interface de ligne de commande.

Pour installer le GroundRunner :

Dézippez GroundRunner.zip dans un nouveau dossier et ouvrez-le.
Exécutez 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.
Pour le dossier de destination, entrez le chemin où le GroundRunner sera installé (par exemple : C:\Program Files\GroundRunner\) et cliquez sur Next.
Dans Platform company token, entrez votre company token.
Dans Platform auth host:
- Pour l'APAC, entrez h.apac.wdesk.com/s/chains-reaper.
- Pour le Canada, entrez h.ca.wdesk.com/s/chains-reaper.
- Pour la région EMEA, entrez h.eu.wdesk.com/s/chains-reaper.
- Pour les États-Unis, l'Amérique centrale et l'Amérique du Sud, entrez h.app.wdesk.com/s/chains-reaper.
Si vous utilisez un serveur proxy, entrez son URL et son port dans Proxy host.
(Par exemple, http://yourproxy:3000.)
Pour contourner le serveur proxy, entrez une liste d'hôtes séparés par des virgules sous No proxy host.
Cliquez sur Next, Install, et Finish.
Une fois installé, cliquez avec le bouton droit de la souris sur le GroundRunner dans le gestionnaire de services Windows et sélectionnez Start.

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 l'installation du GroundRunner dans son propre répertoire au sein de vos fichiers de programme (par exemple c:\NProgram Files (x86)\Nwdata). Vous pouvez ensuite décompresser le fichier d'installation et l'extraire à la racine de ce répertoire.

Vous pouvez ensuite installer le GroundRunner :

Dans la fenêtre de commande Windows, entrez
```
c:\NProgram Files (x86)\Nwdata\Ninstaller.exe install
```
et acceptez toutes les valeurs par défaut.
- Sélectionnez "windows" comme système d'initialisation.
  
  Vous devez spécifier que le GroundRunner doit fonctionner comme un service Windows pour qu'il soit pris en charge par les mises à jour automatiques. Les GroundRunners ne doivent être exécutés 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 l'APAC, entrez h.apac.wdesk.com/s/chains-reaper.
  - Pour le Canada, entrez h.ca.wdesk.com/s/chains-reaper.
  - Pour la région EMEA, entrez h.eu.wdesk.com/s/chains-reaper.
  - Pour les États-Unis, l'Amérique centrale et l'Amérique du Sud, entrez h.app.wdesk.com/s/chains-reaper.
- Saisissez le code 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, entrez sc start GroundRunner.
  - Dans le gestionnaire de services Windows, démarrez le service GroundRunner.
- S'il s'agit d'un processus d'avant-plan, entrez dans la boîte de dialogue de commande :
```
cd c:\NProgram Files (x86)\Nwdata GroundRunner.exe
```

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

Etape 1. Installer le GroundRunner

Téléchargez le fichier d'installation du GroundRunner dans son propre répertoire,
par exemple : /home/nom_utilisateur/wdata/.

Remarque : "/home/nom_utilisateur/wdata" est fourni à titre d'exemple. Respectez la politique de votre organisation en ce qui concerne les lieux d'installation des services.
Dans une boîte de dialogue, décompressez le fichier d'installation en utilisant :
```
unzip GroundRunner.zip
```
Saisir les coordonnées du coureur de fond.
1. Entrez ./installer install
2. Pour le nom d'hôte d'autorisation (AUTH_HOST) :
  - Pour l'APAC, entrez h.apac.wdesk.com/s/chains-reaper.
  - Pour le Canada, entrez h.ca.wdesk.com/s/chains-reaper.
  - Pour la région EMEA, entrez h.eu.wdesk.com/s/chains-reaper.
  - Pour les États-Unis, l'Amérique centrale et l'Amérique du Sud, entrez h.app.wdesk.com/s/chains-reaper.
3. Saisissez le code de votre entreprise .
Supprimez tous les fichiers du répertoire à l'exception du dossier qui a été créé lors de la procédure d'installation.

Etape 2. Configurer votre GroundRunner en tant que service systemd (Linux)

Pour que les mises à jour automatiques du GroundRunner fonctionnent, et pour une bonne hygiène du GroundRunner, le GroundRunner doit être installé en tant que service systemd activé et redémarrable. Veuillez vous référer à la documentation de votre système d'exploitation et à la politique de votre organisation pour savoir comment faire fonctionner le GroundRunner en tant que service systemd.

Pour les configurations de base, nous avons les exigences suivantes en matière de fichiers unitaires systemd pour que les mises à jour automatiques fonctionnent correctement :

Assurez-vous que l'exécutable ExecStart pointe vers le binaire GroundRunnerMonitor et NON vers le binaire
GroundRunner.
Set Restart=always.
Ne pas définir StartLimitBurst ou StartLimitIntervalSec, car cela pourrait empêcher le GroundRunner de redémarrer en raison d'erreurs transitoires. Si vous souhaitez que le GroundRunner n'entre pas dans une boucle de redémarrage rapide, vous pouvez configurer RestartSec.
Entrez systemctl enable pour activer l'unité de service Systemd GroundRunner afin que le GroundRunner survive à un redémarrage.

Workiva ne prend pas officiellement en charge l'exécution d'un GroundRunner en tant que processus de premier plan. Cela peut être utile pour tester une configuration, mais une fois qu'un GroundRunner est configuré, il doit être configuré comme un processus d'arrière-plan de longue durée.

Faire fonctionner GroundRunners sur macOS (test uniquement)

Workiva prend en charge GroundRunners sur macOS à des fins de test uniquement. Bien que les GroundRunners macOS soient capables d'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 mis fin à la prise en charge de son logiciel serveur macOS en 2022. Les ordinateurs portables et les ordinateurs de bureau Apple ne sont pas adaptés à l'utilisation des 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 coureur.
Par exemple "<datasource>-GroundRunner".
Cliquez sur Activer.

Mise à jour manuelle d'un GroundRunner

Bien que cela soit rarement nécessaire, il se peut que vous deviez mettre à niveau manuellement un GroundRunner.
Reportez-vous à la page d'assistance Workiva Mise à jour du manuel GroundRunner pour obtenir des instructions sur la manière de procéder.

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 est exécuté en tant que service, utilisez le gestionnaire de services Windows ou entrez
  sc stop GroundRunner dans une fenêtre de commande.
- S'il s'agit d'un processus d'avant-plan, appuyez sur Ctrl+C.
Dans la boîte de dialogue de commande, en tant qu'administrateur, entrez
installer.exe uninstall.
Supprimez le répertoire exécutable GroundRunner.

Dans la boîte de dialogue de commande, arrêtez le service GroundRunner et supprimez son répertoire 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 plus d’informations sur l’installation d’un JRE personnalisé, voir Désactiver les bibliothèques partagées de Workiva.

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.apac.wdesk.com` `h.app.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 un tableau.

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