Installare e gestire i GroundRunner

I GroundRunner consentono ai comandi a catena di interagire con sistemi on-premises o fonti di dati remote non altrimenti accessibili via internet. In genere vengono installati su un server dedicato, come quello che ospita la fonte di dati collegata, da un professionista IT o da qualcuno che conosce le impostazioni di rete della tua organizzazione.

Prima di configurare un GroundRunner, ti consigliamo di consultare l'architettura di sicurezza di Chain Builder.

Requisiti

È necessario un sistema operativo compatibile e se il GroundRunner accede a risorse condivise come un percorso Windows Universal Naming Convention (UNC), è necessario un account utente con privilegi sufficienti.

Un Java Runtime Environment (JRE) non viene installato con GroundRunner durante l'installazione iniziale di GroundRunner.

Al termine della configurazione e con GroundRunner in esecuzione, scaricherà automaticamente un JRE quando necessario per eseguire comandi che dipendono da Java. Non è richiesta alcuna installazione o intervento dell'amministratore e il JRE recuperato non influisce sulle installazioni JRE esistenti se presenti sull'host.

In alternativa, se hai dei requisiti organizzativi che richiedono l'uso di una particolare JRE, la variabile d'ambiente SHARED_LIBRARY_OVERRIDES può essere impostata in modo da puntare all'installazione del sistema. In questo caso, GroundRunner non scaricherà automaticamente la JRE standard di Workiva e utilizzerà l'installazione della JRE di sistema fornita.

I JRE forniti da Workiva sono concessi in licenza GPL v2 e sono coperti dall'eccezione classpath.

Nota: Per utilizzare certificati personalizzati con la tua installazione di Java, vedi Utilizzare certificati personalizzati con GroundRunners.

Al momento, GroundRunner può essere installato sulle seguenti famiglie di sistemi operativi senza dipendenze da librerie esterne:

Windows e Windows Server
Distribuzioni Linux e derivate:
- RedHat, Fedora, AmazonLinux
- Debian/Ubuntu
macOS (solo per i test)

Workiva si impegna a supportare tutte le versioni moderne delle famiglie di sistemi operativi sopra elencate. Tuttavia, non possiamo supportare alcun sistema operativo che sia stato definito "a fine vita" dal suo fornitore. Questi sistemi operativi più vecchi presentano potenziali rischi per la sicurezza e dovrebbero essere aggiornati a una versione attuale il prima possibile. Per saperne di più sulla nostra politica di fine vita.

Nota: il programma di supporto di ogni sistema operativo è stabilito dal singolo fornitore. Ad esempio, il supporto Microsoft per Windows 7 è terminato il 14 gennaio 2020; il supporto Workiva per Windows 7 è terminato alla stessa data.

Requisiti hardware

Sebbene GroundRunner richieda risorse server limitate, consigliamo almeno:

512 MB di memoria ad accesso casuale (RAM) disponibile
100GB di spazio su disco disponibile

Nota: Per calcolare lo spazio su disco necessario, sappi che una catena di cinque comandi che producono ciascuno 10MB di output effimeri richiede 50MB per essere completata.

La configurazione host consigliata comprende una macchina virtuale configurata con:

Da due a quattro processori

Nota: I processori basati su ARM non sono compatibili con i GroundRunner.
8GB di memoria di sistema
Un'unità SSD (Solid State Drive) per l'archiviazione

Questo server deve essere disponibile 24 ore su 24 e 7 giorni su 7 per comunicare con GroundRunner.

Per impostazione predefinita, i GroundRunner utilizzano un account amministrativo locale senza accedere a risorse remote come i drive condivisi.

Per accedere a una risorsa condivisa come un percorso UNC di Windows, avvia il GroundRunner con un account utente con privilegi adeguati alla risorsa. Se utilizzi un account utente diverso dall'amministratore di sistema locale predefinito, concedigli i permessi per gestire la directory di installazione di GroundRunner per abilitare gli aggiornamenti automatici.

Requisiti di ruolo

Sulla piattaforma Workiva

Sulla piattaforma Workiva, hai bisogno di un ruolo che conceda l'accesso alle impostazioni di Chain Builder e la capacità di gestire i Runner. Ce ne sono due:

Chain Owner: questo è il ruolo principale richiesto. Gli utenti con questo ruolo possono accedere alla sezione "Download" in Chain Builder per recuperare gli ultimi file di installazione di GroundRunner e gestire la scheda "Runner" per attivare o monitorare il servizio.
Org Chain Security Admin: questo ruolo a livello organizzativo ha anche l'autorità di gestire connessioni e runner su più spazi di lavoro.

Sul server

Poiché un "aggiornamento manuale" comporta l'arresto dei servizi e la sostituzione dei file eseguibili sulla macchina fisica o virtuale su cui è installato GroundRunner, l'utente deve disporre di privilegi amministrativi sul server host.

Windows: devi avere la capacità di eseguire il Prompt dei comandi come amministratore e accedere al Gestore dei servizi di Windows (per arrestare e riavviare il servizio GroundRunner).
Linux/macOS: devi avere accesso sudo o root per spostare i file nella directory di installazione e riavviare il processo in background.

Scarica il GroundRunner

Per scaricare un GroundRunner da installare o aggiornare manualmente:

Nella barra laterale di Workiva Home, clicca su Chains.
Nella barra laterale del Chain Builder (questa è una nuova scheda), clicca su Connections.

In alternativa, puoi fare clic sull'icona del profilo utente in alto a destra, selezionare Chains admin, quindi Impostazioni workplace.
Clicca su Downloads nella barra dei menu in alto.
Trova il GroundRunner per il tuo sistema operativo e clicca su Download.
Una volta che il download è andato a buon fine, seleziona le istruzioni appropriate dal set sottostante e seguile per installare GroundRunner.

Installa GroundRunner

Il programma di installazione Microsoft (MSI) richiede .NET 3.5 o superiore.
Se non riesci a soddisfare questo requisito, dovrai installare GroundRunner usando invece l'interfaccia a riga di comando.

Per installare GroundRunner:

Decomprimi GroundRunner.zip in una nuova cartella e aprila.
Esegui GroundRunner.msi per aprire la procedura guidata di installazione di GroundRunner.
Fare clic su Avanti.
Leggi e accetta i termini dell'accordo di licenza e clicca su Avanti.
Per la cartella di destinazione, inserisci il percorso in cui verrà installato GroundRunner (ad esempio: C:\Program Files\GroundRunner\) e fai clic su Avanti.
In Platform company token, inserisci il tuo company token.
In Platform auth host:
- Per l'APAC, inserisci h.apac.wdesk.com/s/chains-reaper.
- Per il Canada, inserisci h.ca.wdesk.com/s/chains-reaper.
- Per l'EMEA, inserisci h.eu.wdesk.com/s/chains-reaper.
- Per gli Stati Uniti, l'America Centrale e l'America Meridionale, inserisci h.app.wdesk.com/s/chains-reaper.
Se usi un server proxy, inserisci il suo URL e la porta in Proxy host.
(Ad esempio, http://yourproxy:3000.)
Per bypassare il server proxy, inserisci un elenco separato da virgole di host in No proxy host.
Clicca su Next, Install e Finish.
Una volta installato, fai clic con il pulsante destro del mouse su GroundRunner nel Gestore dei servizi di Windows e seleziona Avvia.

Il GroundRunner è stato installato ed è pronto per essere attivato.

Per installare tramite interfaccia a riga di comando, devi scaricare il file di installazione di GroundRunner nella sua directory dedicata all'interno dei tuoi file di programma (ad esempio c:\Program Files (x86)\wdata). Puoi quindi decomprimere il file di installazione ed estrarlo nella radice di quella directory.

Puoi quindi installare GroundRunner:

Nella finestra dei comandi di Windows, inserisci
```
c:\Program Files (x86)\wdata\installer.exe install
```
e accetta tutte le impostazioni predefinite.
- Seleziona "windows" per il sistema di init.
  
  Devi specificare che GroundRunner deve operare come servizio Windows affinché sia supportato con aggiornamenti automatici. I GroundRunner dovrebbero essere eseguiti solo come servizio, tranne che a scopo di test.
- Per il percorso, crea una cartella Files all'interno della nuova directory
  (ad esempio, C:\Program Files (x86)\Wdata\Files).
- Per il nome dell'host di autorizzazione (AUTH_HOST):
  - Per l'APAC, inserisci h.apac.wdesk.com/s/chains-reaper.
  - Per il Canada, inserisci h.ca.wdesk.com/s/chains-reaper.
  - Per l'EMEA, inserisci h.eu.wdesk.com/s/chains-reaper.
  - Per gli Stati Uniti, l'America Centrale e l'America Meridionale, inserisci h.app.wdesk.com/s/chains-reaper.
- Inserisci il tuo company token.
Elimina tutti i file dalla directory tranne la directory eseguibile di GroundRunner.
Seleziona se eseguire GroundRunner come servizio o come processo in primo piano.
- Se viene eseguito come servizio, esegui una delle seguenti operazioni:
  - Nella finestra di dialogo dei comandi, inserisci sc start GroundRunner.
  - In Gestore dei servizi di Windows, avvia il servizio GroundRunner.
- Se in esecuzione come processo in primo piano, nella finestra di dialogo dei comandi inserisci:
```
cd c:\Program Files (x86)\wdata GroundRunner.exe
```

Il tuo GroundRunner è ora installato e pronto per l'attivazione.

Passo 1. Installare GroundRunner

Scarica il file di installazione di GroundRunner nella sua directory dedicata,
ad esempio: /home/user_name/wdata/.

Nota: "/home/user_name/wdata" è fornito come esempio. Segui la policy della tua organizzazione per le posizioni di installazione dei servizi.
In una finestra di dialogo dei comandi, decomprimi il file di installazione usando:
```
unzip GroundRunner.zip
```
Inserisci i dettagli di GroundRunner.
1. Inserisci ./installer install
2. Per il nome dell'host di autorizzazione (AUTH_HOST):
  - Per l'APAC, inserisci h.apac.wdesk.com/s/chains-reaper.
  - Per il Canada, inserisci h.ca.wdesk.com/s/chains-reaper.
  - Per l'EMEA, inserisci h.eu.wdesk.com/s/chains-reaper.
  - Per gli Stati Uniti, l'America Centrale e l'America Meridionale, inserisci h.app.wdesk.com/s/chains-reaper.
3. Inserisci il tuo company token.
Elimina tutti i file dalla directory tranne la cartella creata durante il processo di installazione.

Passaggio 2. Configura il tuo GroundRunner come servizio systemd (Linux)

Per garantire il funzionamento degli aggiornamenti automatici di GroundRunner, e per una buona igiene di GroundRunner, GroundRunner deve essere installato come servizio systemd abilitato e riavviabile. Fai riferimento alla documentazione del tuo sistema operativo e alla policy della tua organizzazione su come eseguire GroundRunner come servizio systemd.

Per configurazioni di base, abbiamo i seguenti requisiti per il file unit systemd affinché gli aggiornamenti automatici funzionino correttamente:

Assicurati che l'eseguibile ExecStart punti al file binario GroundRunnerMonitor e NON a
GroundRunner.
Imposta Restart=always.
Non impostare StartLimitBurst o StartLimitIntervalSec, poiché potrebbero impedire a GroundRunner di riavviarsi a causa di errori transitori. Se desideri che GroundRunner non entri in un ciclo di riavvio rapido, puoi configurare RestartSec.
Inserisci systemctl enable per abilitare l'unità di servizio systemd di GroundRunner in modo che GroundRunner sopravviva a un riavvio.

Workiva non supporta ufficialmente l'esecuzione di GroundRunner come processo in primo piano. Questo può essere utile per testare una configurazione, ma, una volta configurato GroundRunner, dovrebbe essere impostato come processo in background di lunga durata.

Utilizzo di GroundRunner su macOS (solo per test)

Workiva supporta GroundRunner su macOS solo a scopo di test. Sebbene GroundRunner su macOS sia in grado di eseguire gli stessi comandi delle versioni Linux e Windows, Workiva non supporta ufficialmente launchd come gestore di servizi valido. Questo perché Apple ha interrotto il supporto per il proprio software macOS server nel 2022. I laptop e i computer desktop Apple non sono adatti per eseguire GroundRunner.

Attiva il GroundRunner

Dopo aver installato il GroundRunner, devi attivarlo all'interno di Chain Builder.

Nella barra laterale di Chain Builder, clicca su Connections.
Clicca su Runners in alto e poi su Pending Registration.
Inserisci un nome breve e descrittivo per il runner.
Ad esempio "<datasource>-GroundRunner".
Se desideri ricevere notifiche quando GroundRunner diventa non integro, attiva l'interruttore Notificami quando questo runner diventa non integro impostandolo su "On" (diventa blu).
Clicca su Attiva.

Checklist di configurazione GR

Stai eseguendo l'eseguibile GroundRunnerMonitor (e non l'eseguibile GroundRunner)?
Hai configurato il tuo GroundRunnerMonitor come servizio riavviabile a livello di sistema?
- Per Linux: Systemd.
- Per Windows: Servizi di Windows.
Il tuo servizio si riavvia al riavvio del sistema?
- Su Linux: systemctl enable.
- Su Windows: Tipo di avvio impostato su Automatico.
Stai eseguendo su un sistema operativo server supportato?
Hai abilitato le notifiche di GroundRunner?

Aggiornare manualmente un GroundRunner

Sebbene sia raramente richiesto, potrebbe essere necessario aggiornare manualmente un GroundRunner.
Fai riferimento alla pagina di supporto Workiva Aggiornamento manuale di GroundRunner per istruzioni su come farlo.

Disinstallare un GroundRunner

Se non hai più bisogno di GroundRunner, puoi disinstallarlo.

Dalle impostazioni di Windows, vai su Apps & features, seleziona GroundRunner (64 bit), e clicca su Disinstalla.

Arresta il servizio GroundRunner.
- Se è in esecuzione come servizio, usa Gestore dei servizi di Windows, o inserisci
  sc stop GroundRunner in una finestra dei comandi.
- Se è in esecuzione come processo in primo piano, premi Ctrl+C.
Nella finestra di dialogo dei comandi, come amministratore, inserisci
installer.exe uninstall.
Elimina la directory eseguibile di GroundRunner.

Nella finestra di dialogo dei comandi, arresta il servizio GroundRunner ed elimina la sua directory eseguibile (ad esempio, /home/<username>/wdata/Contents).

Installare un JRE personalizzato

Se necessario, puoi installare una JRE personalizzata per supportare un GroundRunner. La versione di Java di questo JRE deve corrispondere a quella richiesta per il Groundrunner. Ad eccezione dei GroundRunner Oracle Essbase e Oracle Hyperion Financial Management (HFM), tutti i GroundRunner utilizzano la stessa versione JRE.

Per informazioni su come installare un JRE personalizzato, vedi Disabilita le librerie condivise Workiva.

Impostazioni di configurazione di GroundRunner e domini in uscita

Per consentire la comunicazione con la fonte dei dati, potrebbe essere necessario aprire le porte del firewall sul server in cui è installato il GroundRunner. Per modificare le impostazioni di configurazione di alcuni GroundRunner, puoi modificare il file GroundRunner.config nella directory in cui sono installati i binari.

Configurazione	Impostazioni
PORTA	0 a 65535. Per impostazione predefinita, i GroundRunner utilizzano la porta 8821 per comunicare tra loro. Tuttavia, una porta è necessaria solo se i GroundRunner su server diversi condividono le uscite di comando all'interno della tua rete.
NOME_AZIENDA	Lasciare l'impostazione predefinita, a meno che GroundRunner non sia configurato per un altro tenant.
LOG_LEVEL	Info o debug
PROTOCOLLO	Lasciare l'impostazione predefinita.
HTTP_PROXY_URL	Se si utilizza un server proxy, inserisci l'URL e la porta (se necessario). Ad esempio, `http://yourproxy:3000` Nota: I GroundRunner possono utilizzare server proxy, ma non quelli autenticati tramite New Technology LAN Manager (NTLM). Consenti invece l'indirizzo IP del server.
LONG_POLL	Se si utilizza un server proxy, imposta true per indicare al runner di utilizzare il long-polling per recuperare i comandi. Per garantire le prestazioni, usa il long-polling solo se i web socket non sono supportati dal tuo server proxy o firewall.
NO_PROXY	Per bypassare il server proxy, fornisci un elenco separato da virgole di host da raggiungere direttamente. Per includere più host basati su uno schema comune, usa il carattere jolly *.
GROUNDRUNNER_CERT	Necessario se si utilizza più di un GroundRunner e si desidera inviare informazioni criptate al secondo GroundRunner. Questo deve essere utilizzato insieme a PORT. Devi specificare anche il campo PROTOCOLLO come HTTPS quando attivi il runner.
GROUNDRUNNER_CERT_KEY	Necessario se si utilizza più di un GroundRunner e si desidera ricevere informazioni criptate da un secondo GroundRunner. Deve essere utilizzato insieme a PORT.
DISABLE_WEBSOCKETS	Le websocket sono necessarie per eseguire le trasformazioni. Se disabilitato, tutti i comandi che utilizzano le trasformazioni saranno completamente ignorati.

Nota: il tuo certificato autofirmato deve avere un Subject Alternative Name (SAN). In caso contrario, quando il GroundRunner tenta di scaricare i file, viene visualizzato un messaggio di errore che fa riferimento alla SAN mancante.

Se la tua rete deve consentire i domini in uscita, questi si applicano ai GroundRunner:

Dominio	Scopo
`h.app.wdesk.com` `h.apac.wdesk.com` `h.ca.wdesk.com` `h.eu.wdesk.com`	I principali sottodomini dei servizi Workiva più comuni, tra cui Wdata.
`*.wdesk.com`	Il dominio principale della piattaforma Workiva di produzione.
`..wdesk.com`	I sottodomini dei componenti di supporto della piattaforma Workiva.

Se non puoi usare i caratteri jolly (*) per l'autorizzazione all'allowlist, usa il dominio "mothership" per la tua regione per consentire il download delle risorse di GroundRunner ed evitare potenziali problemi di blocco in futuro.

Dominio	Scopo
`mothership.app.wdesk.com` `mothership.apac.wdesk.com` `mothership.ca.wdesk.com` `mothership.eu.wdesk.com`	Il sottodominio per scaricare le risorse chain necessarie.

Sicurezza

I GroundRunner non raccolgono o aggregano mai i dati; li conservano solo durante la trasmissione. Un certificato EV (Extended Validation) cripta e protegge sempre il traffico tra un GroundRunner e la sua fonte di dati tramite DigiCert®.

Nota: Per proteggere i dati on-premises, i CloudRunner possono condividere gli output con i GroundRunner, ma i GroundRunner non possono condividere gli output dei file con CloudRunner.

Risoluzione degli errori di GroundRunner

Se ricevi questi errori durante l'esecuzione di una catena, controlla i GroundRunner del comando.

Suggerimento: Per facilitare la risoluzione dei problemi, puoi creare una catena per scaricare automaticamente il file di log di un GroundRunner in una tabella.

Messaggio di errore	Causa	Risoluzione
Comunicazione fallita con l'agente: questo comando non è stato eseguito	Il comando non è riuscito a comunicare con il suo GroundRunner. Se questo accade, il GroundRunner non si è avviato o si è verificata un'interruzione di rete tra il GroundRunner e il Chain Builder.	Verifica: Il servizio GroundRunner funziona. Il server di GroundRunner è connesso a Internet.
Impossibile scaricare le risorse associate al comando. Contatta l'assistenza se l'errore persiste.	I runner associati a questi comandi della catena non possono comunicare tra loro. Questo accade spesso quando i comandi utilizzano runner diversi e il CloudRunner sta cercando di utilizzare un file in uscita da un comando basato su GroundRunner.	Usa lo stesso runner con tutti i comandi della catena. Se i comandi della catena richiedono più runner, verifica che nessun comando con GroundRunner passi i file in uscita ai comandi che utilizzano il CloudRunner.
Errore nell'avvio del comando: `exec: \"\\[connector].exe\": il file non esiste" commandExecutorId=[ID]`	Un'applicazione malware o antivirus ha identificato erroneamente il connettore e ha intercettato la sua comunicazione con GroundRunner.	Escludi la directory di installazione di GroundRunner dalle scansioni dell'applicazione.
Errori dei certificati	Usare i certificati autofirmati	In molti casi, sarà conveniente utilizzare certificati autofirmati per criptare le comunicazioni di GroundRunner. Se utilizzi un certificato autofirmato, assicurati che il Common Name del certificato corrisponda all'URL a cui è possibile accedere al server. Ad esempio, se il GroundRunner è in ascolto sulla porta 8821 e puoi accedere al server dalla tua rete `localhost`, il Common Name del certificato sarebbe "`localhost`".
Catena intermittente con errore: "Connessione resettata dal peer"	Quando più runner sono installati sullo stesso computer, devono avere ciascuno un GUID unico. Se viene utilizzato lo stesso GUID, i runner possono sovrapporsi e creare un ciclo di aggiornamento, causando occasionali malfunzionamenti della catena.	Si consiglia di reinstallare completamente GroundRunner.
I comandi vengono saltati su GroundRunner ma hanno successo su CloudRunner	I websocket sono necessari per eseguire le trasformazioni. Quando i websockets sono disabilitati, le trasformazioni vengono completamente saltate.	Apri il tuo file di configurazione e imposta `DISABLE_WEBSOCKETS=false`.
Errore di lettura dal socket. `Riprova la connessione: read tcp <IP>:<Port>-><IP>:<Port>: wsarecv: Un tentativo di connessione è fallito perché l'utente connesso non ha risposto correttamente dopo un certo periodo di tempo o la connessione stabilita non è riuscita perché l'host connesso non ha risposto.`	Problema di firewall interno o di rete	Coinvolgi il team IT o di rete interno per esaminare i log e la configurazione al fine di risolvere l'errore.
read <IP>:<Port>-><IP>:<Port>: `wsarecv: Una connessione esistente è stata chiusa forzatamente dall'host remoto`	Problema di firewall interno o di rete	Coinvolgi il team IT o di rete interno per esaminare i log e la configurazione al fine di risolvere l'errore.

Risorse aggiuntive

Assistenza

Community

Centro assistenza di Workiva