Instalar e gerenciar GroundRunners

Os GroundRunners permitem que os comandos em cadeia interajam com sistemas locais ou fontes de dados remotas não acessíveis de outra forma pela Internet. Normalmente, eles são instalados em um servidor dedicado, como o que hospeda a fonte de dados conectada, por um profissional de TI ou alguém familiarizado com as configurações de rede da sua organização.

Antes de configurar um GroundRunner, recomendamos que você consulte a arquitetura de segurança do Chain Builder .

Requisitos

É necessário um sistema operacional compatível e, se o seu GroundRunner acessar recursos compartilhados, como um caminho UNC (Windows Universal Naming Convention), também será necessária uma conta de usuário com privilégios suficientes.

Se você estiver usando o GroundRunner, o JRE não será instalado com o GroundRunner durante a instalação inicial do GroundRunner.

Após a conclusão da configuração e com o GroundRunner em execução, ele baixará automaticamente um JRE, conforme necessário, para executar comandos que dependem do Java. Não é necessária nenhuma instalação ou intervenção do administrador, e o JRE recuperado não afetará as instalações de JRE existentes, se elas existirem no host.

Como alternativa, se você tiver requisitos organizacionais que exijam o uso de um JRE específico, a variável de ambiente SHARED_LIBRARY_OVERRIDES poderá ser definida para apontar para a instalação do sistema. Nesse caso, o GroundRunner não fará o download automático do JRE padrão da Workiva e usará o JRE instalado no sistema provedor.

Os JREs fornecidos pela Workiva são licenciados sob a GPL v2 e são cobertos pela exceção de classpath .

Nota: Para usar certificados personalizados com o Java instalado, consulte Usando certificados personalizados com o GroundRunners.

No momento, o GroundRunners pode ser instalado nas seguintes famílias de sistemas operacionais, sem dependências de bibliotecas externas:

Windows e Windows Server
Distribuições e derivadas do Linux:
- RedHat, Fedora, AmazonLinux
- Debian/Ubuntu
macOS (apenas para testes)

A Workiva se esforça para oferecer suporte a todas as versões modernas das famílias de sistemas operacionais listadas acima. No entanto, não podemos oferecer suporte a nenhum sistema operacional que tenha sido designado como "fim de vida útil" por seu fornecedor. Esses sistemas operacionais mais antigos apresentam riscos potenciais à segurança e devem ser atualizados para uma versão mais recente o mais rápido possível. Saiba mais sobre nossa política de fim de vida útil.

Observação: O cronograma de suporte de cada sistema operacional é definido pelo fornecedor individual. Por exemplo, o suporte da Microsoft ao Windows 7 terminou em 14 de janeiro de 2020; o suporte da Workiva ao Windows 7 terminou na mesma data.

Requisitos de hardware

Embora o GroundRunners exija poucos recursos do servidor, recomendamos, no mínimo:

512 MB de memória de acesso aleatório (RAM) disponível
100 GB de espaço disponível em disco

Observação: Para ajudar a calcular o espaço em disco necessário, saiba que uma cadeia com cinco comandos, cada um produzindo saídas efêmeras de 10 MB, requer 50 MB para ser concluída.

A configuração de host recomendada inclui uma máquina virtual configurada com:

Dois a quatro processadores

Nota: Os processadores baseados em ARM não são compatíveis com o GroundRunners.
8 GB de memória do sistema
Um dispositivo de armazenamento de unidade de estado sólido (SSD)

Esse servidor deve estar disponível 24 horas por dia, 7 dias por semana, para que você possa se comunicar com o GroundRunner.

Por padrão, os GroundRunners usam uma conta administrativa local sem acesso a recursos remotos, como unidades compartilhadas.

Para acessar um recurso compartilhado, como um caminho UNC do Windows, inicie o GroundRunner em uma conta de usuário com privilégios adequados para o recurso. Se você estiver usando uma conta de usuário que não seja o administrador do sistema local padrão, conceda a ele permissões para gerenciar o diretório de instalação do GroundRunner para ativar as atualizações automáticas.

Requisitos do cargo

Na plataforma Workiva

Na plataforma Workiva, você precisa de uma função que conceda acesso às configurações do Chain Builder e a capacidade de gerenciar Runners. São dois:

Proprietário da cadeia: Essa é a função principal exigida. Os usuários com essa função podem acessar a seção “Downloads” no Chain Builder para baixar os arquivos de instalação mais recentes do GroundRunner e gerenciar a aba “Runners” para ativar ou monitorar o serviço.
Administrador de Segurança da Cadeia Organizacional: Essa função em nível organizacional também tem autoridade para gerenciar conexões e executores em vários espaços de trabalho.

No servidor

Como uma “atualização manual” envolve interromper serviços e substituir arquivos executáveis na máquina física ou virtual onde o GroundRunner está instalado, o usuário deve ter privilégios administrativos no servidor host.

Windows: É necessário ter permissão para executar o Prompt de Comando como administrador e acessar o Gerenciador de Serviços do Windows (para interromper e reiniciar o serviço GroundRunner).
Linux/macOS: É necessário ter sudo ou acesso como root para mover arquivos para o diretório de instalação e reiniciar o processo em segundo plano.

Faça o download do GroundRunner

Para fazer o download de um GroundRunner para instalação ou atualização manual, você deve procurar o GroundRunner do seu sistema operacional e clicar em Download no lado direito:

Na barra lateral da página inicial da Workiva, clique em Cadeias.
Na barra lateral do Construtor de Cadeias (essa é uma nova guia), clique em Conexões.

Como alternativa, você pode clicar no ícone do perfil do usuário no canto superior direito, selecionar “ ” (Cadeias de Chains) “admin” e, em seguida, “ ” (Configurações do Workplace).
Clique em Downloads na barra de menu superior.
Localize o GroundRunner para o seu sistema operacional e clique em Download para obtê-lo.
Depois de fazer o download com sucesso para o seu computador, selecione as instruções apropriadas do conjunto abaixo e siga-as para instalar o GroundRunner.

Instale o GroundRunner

O Microsoft Installer (MSI) requer o .NET 3.5 ou superior.
Caso não seja possível atender a esse requisito, você terá que instalar o GroundRunner usando a interface de linha de comando.

Para instalar o GroundRunner:

Descompacte o arquivo GroundRunner.zip em uma nova pasta e abra-a. Se você estiver na América do Norte, digite h.app.wdesk.com/s/chains-reaper.
Execute o arquivo “ GroundRunner.msi” para abrir o assistente de instalação do GroundRunner.
Clique em “Próximo”.
Revise e aceite os termos do contrato de licença e clique em Next.
Na opção “Pasta de destino”, insira o caminho onde o GroundRunner será instalado (por exemplo: C:\Program Files\GroundRunner\) e clique em “ ” (Próximo).
Em “ ” (Token da empresa da plataforma), insira seu “ ” (Token da empresa).
Em Platform auth host:
- Para a região da Ásia-Pacífico (APAC), acesse h.apac.wdesk.com/s/chains-reaper.
- Para o Canadá, digite h.ca.wdesk.com/s/chains-reaper.
- Para a região EMEA, acesse h.eu.wdesk.com/s/chains-reaper.
- Para os Estados Unidos, a América Central e a América do Sul, digite h.app.wdesk.com/s/chains-reaper.
Se estiver usando um servidor proxy, insira sua URL e porta em Proxy host.
(Por exemplo, http://yourproxy:3000.)
Para contornar o servidor proxy, insira uma lista de hosts separados por vírgulas em Sem host de proxy.
Clique em Next, Install e Finish.
Após a instalação, clique com o botão direito do mouse no GroundRunner no Gerenciador de Serviços do Windows e selecione “ ” (Iniciar).

Seu GroundRunner foi instalado e está pronto para ser ativado.

Para instalar por meio da interface de linha de comando, é necessário baixar o arquivo de instalação do GroundRunner em um diretório próprio dentro da pasta “Arquivos de Programas” (por exemplo, c:\Program Files (x86)\wdata). Em seguida, você pode descompactar o arquivo de instalação e extraí-lo para a raiz desse diretório.

Em seguida, você pode instalar o GroundRunner:

Na janela de comando do Windows, digite
```
c:\Arquivos de Programas (x86)\wdata\installer.exe install
```
e aceite todas as configurações padrão.
- Selecione “Windows” como sistema de inicialização.
  
  É necessário especificar que o GroundRunner deve funcionar como um serviço do Windows para que receba suporte com atualizações automáticas. O GroundRunners só deve ser executado como um serviço, exceto para fins de teste.
- Para o caminho, crie uma pasta Files dentro do novo diretório
  (por exemplo, C:\Program Files (x86)\Wdata\Files).
- Para o nome do host de autorização (AUTH_HOST):
  - Para a região da Ásia-Pacífico (APAC), acesse h.apac.wdesk.com/s/chains-reaper.
  - Para o Canadá, digite h.ca.wdesk.com/s/chains-reaper.
  - Para a região EMEA, acesse h.eu.wdesk.com/s/chains-reaper.
  - Para os Estados Unidos, a América Central e a América do Sul, digite h.app.wdesk.com/s/chains-reaper.
- Insira o token da sua empresa do :.
Exclua todos os arquivos do diretório, exceto o diretório executável do GroundRunner.
Selecione se você deseja executar o GroundRunner como um serviço ou como um processo em primeiro plano.
- Se você estiver executando como um serviço, execute uma das seguintes ações:
  - Na caixa de diálogo de comando, digite sc start GroundRunner.
  - No Gerenciador de Serviços do Windows, inicie o serviço “ GroundRunner”.
- Se estiver sendo executado como um processo em primeiro plano, digite na janela de comando:
```
cd c:\Arquivos de Programas (x86)\wdata GroundRunner.exe
```

Seu GroundRunner já está instalado e pronto para ser ativado.

Etapa 1. Instalar o GroundRunner

Baixe o arquivo de instalação do GroundRunner em um diretório próprio, como
, por exemplo: /home/user_name/wdata/.

Observação: "/home/user_name/wdata" é fornecido apenas a título de exemplo. Siga a política da sua organização quanto aos locais de instalação dos serviços.
Em uma janela de comando, descompacte o arquivo de instalação usando:
```
descompactar o arquivo GroundRunner.zip
```
Insira os dados do GroundRunner.
1. Digite ./installer install
2. Para o nome do host de autorização (AUTH_HOST):
  - Para a região da Ásia-Pacífico (APAC), acesse h.apac.wdesk.com/s/chains-reaper.
  - Para o Canadá, digite h.ca.wdesk.com/s/chains-reaper.
  - Para a região EMEA, acesse h.eu.wdesk.com/s/chains-reaper.
  - Para os Estados Unidos, a América Central e a América do Sul, digite h.app.wdesk.com/s/chains-reaper.
3. Insira o token da sua empresa do :.
Exclua todos os arquivos do diretório, exceto a pasta que foi criada durante o processo de instalação.

Etapa 2. Configure o GroundRunner como um serviço do systemd (Linux)

Para garantir que as atualizações automáticas do GroundRunner funcionem e para manter o GroundRunner em boas condições, ele precisa ser instalado como um serviço do systemd ativado e reiniciável. Consulte a documentação do seu sistema operacional e a política da sua organização para saber como executar o GroundRunner como um serviço do systemd.

Para configurações básicas, temos os seguintes requisitos para os arquivos de unidade do systemd, a fim de que as atualizações automáticas funcionem corretamente:

Certifique-se de que o executável `ExecStart` do ` ` aponte para o binário `GroundRunnerMonitor` do ` ` e NÃO para o binário `GroundRunner` do `
`.
Defina Restart=always.
Não defina StartLimitBurst ou StartLimitIntervalSec, pois isso pode impedir que o GroundRunner reinicie devido a erros transitórios. Se você quiser evitar que o GroundRunner entre em um ciclo rápido de reinicialização, é possível configurar ` RestartSec`.
Digite ` systemctl enable ` para habilitar a unidade de serviço do GroundRunner no systemd, de modo que o GroundRunner continue funcionando após uma reinicialização.

A Workiva não oferece suporte oficial à execução do GroundRunner como um processo em primeiro plano. Isso pode ser útil para testar uma configuração, mas, uma vez que o GroundRunner esteja configurado, ele deve ser configurado como um processo de longa duração em segundo plano.

Como executar o GroundRunners no macOS (apenas para testes)

O Workiva oferece suporte ao GroundRunners no macOS apenas para fins de teste. Embora os GroundRunners do macOS sejam capazes de executar os mesmos comandos que as versões para Linux e Windows, a Workiva não oferece suporte oficial ao launchd como gerenciador de serviços válido. Isso ocorre porque a Apple descontinuou o suporte ao seu software de servidor macOS em 2022. Os laptops e computadores de mesa da Apple não são adequados para rodar o GroundRunners.

Ativar o GroundRunner

Depois de instalar o GroundRunner, você deve ativá-lo no Chain Builder.

Na barra lateral do Construtor de Cadeias, clique em Conexões.
Clique em Runners na parte superior e, em seguida, clique em Pending Registration.
Digite um nome curto e descritivo para o executável.
Por exemplo, “<datasource>-GroundRunner”.
Clique em Ativar.

Lista de verificação para a configuração do GR

Você está executando o executável GroundRunnerMonitor do (em vez do executável GroundRunner do )?
Você já configurou o GroundRunnerMonitor da como um serviço no nível do sistema, que pode ser reiniciado?
- Para Linux: Systemd.
- Para Windows: Serviços do Windows.
O seu serviço é reiniciado quando o sistema é reiniciado?
- No Linux: ` systemctl enable`.
- No Windows: Tipo de inicialização definido como “ ” (Automático).
Você está executando o programa em um sistema operacional de servidor compatível?
Você ativou as notificações do GroundRunner?

Atualização manual de um GroundRunner

Embora isso raramente seja necessário, você pode precisar atualizar manualmente um GroundRunner.
Consulte a página de suporte da Workiva e a atualização do manual do GroundRunner para obter instruções sobre como fazer isso.

Desinstalar um GroundRunner

Se você não precisar mais de um GroundRunner, poderá desinstalá-lo.

Nas Configurações do Windows, acesse Apps & features, selecione GroundRunner (64 bit) e clique em Uninstall.

Interromper o serviço do GroundRunner
- Se estiver sendo executado como serviço, use o Gerenciador de Serviços do Windows ou digite “
  sc stop GroundRunner ” em uma janela de comando.
- Se estiver sendo executado como um processo em primeiro plano, pressione Ctrl+C.
Na janela de diálogo de comando, como administrador, digite
installer.exe uninstall.
Exclua o diretório executável GroundRunner.

Na janela de diálogo de comandos, interrompa o serviço GroundRunner e exclua o diretório do executável (por exemplo, /home/<username>/wdata/Contents).

Instalando um JRE personalizado

Se necessário, você pode instalar seu próprio JRE para dar suporte a um GroundRunner. A versão Java desse JRE deve corresponder à necessária para o Groundrunner. Com exceção dos GroundRunners Oracle Essbase e Oracle Hyperion Financial Management (HFM), todos os GroundRunners usam a mesma versão do JRE.

Para obter informações sobre como instalar um JRE personalizado, consulte . Desative as bibliotecas compartilhadas do Workiva:.

Definições de configuração do GroundRunner e domínios de saída

Para permitir a comunicação com a fonte de dados, talvez você precise abrir as portas do firewall no servidor em que o GroundRunner está instalado. Para alterar as definições de configuração de alguns GroundRunners, você pode editar o arquivo GroundRunner.config no diretório em que os binários estão instalados.

Configuração	Configurações
Porto	0 a 65535. Por padrão, os GroundRunners usam a porta 8821 para se comunicarem uns com os outros. No entanto, uma porta é necessária somente se os GroundRunners em servidores diferentes compartilharem saídas de comando dentro da sua rede.
COMPANY_TOKEN	Deixe como padrão, a menos que o GroundRunner esteja configurado para um locatário diferente.
LOG_LEVEL	Informações ou debug
PROTOCOLO	Deixar como padrão.
HTTP_PROXY_URL	Se você estiver usando um servidor proxy, digite o URL e a porta (se necessário). Por exemplo, `http://yourproxy:3000` Observação: Os GroundRunners podem usar servidores proxy, mas não aqueles autenticados por meio do New Technology LAN Manager (NTLM). Em vez disso, permita o endereço IP do servidor.
LONG_POLL	Se você estiver usando um servidor proxy, defina como true para instruir o executor a usar o long-polling para recuperar comandos. Para garantir o desempenho, use o rastreamento longo somente se os soquetes da Web não forem compatíveis com o seu servidor proxy ou firewall.
NO_PROXY	Para ignorar o servidor proxy, forneça uma lista separada por vírgulas de hosts a serem acessados diretamente. Para incluir vários hosts com base em um padrão comum, use o curinga *.
GROUNDRUNNER_CERT	Necessário se você estiver usando mais de um GroundRunner e quiser enviar informações criptografadas para o segundo GroundRunner. Isso deve ser usado em conjunto com PORT. Você também deve especificar o campo PROTOCOL como HTTPS ao ativar o executor.
GROUNDRUNNER_CERT_KEY	Necessário se você estiver usando mais de um GroundRunner e quiser receber informações criptografadas de um segundo GroundRunner. Também deve ser usado em conjunto com PORT.
DESATIVAR_WEBSOCKETS	Os websockets são necessários para executar as transformações. Quando desativado, todos os comandos que usam transformações serão totalmente ignorados.

Observação: Seu certificado autoassinado deve ter um Nome Alternativo de Assunto (SAN). Se não for o caso, quando o GroundRunner tentar fazer download de arquivos, você verá uma mensagem de erro fazendo referência à SAN ausente.

Se a sua rede deve permitir domínios de saída, isso se aplica aos GroundRunners:

Domínio	Finalidade
`h.app.wdesk.com` `h.apac.wdesk.com` `h.ca.wdesk.com` `h.eu.wdesk.com`	Os principais subdomínios dos serviços comuns da Workiva, incluindo o Wdata.
`*.wdesk.com`	O domínio principal da plataforma de produção da Workiva.
`..wdesk.com`	Os subdomínios dos componentes de suporte na plataforma Workiva.

Segurança

Os GroundRunners nunca coletam ou agregam dados; eles retêm dados somente durante a transmissão. Um certificado de validação estendida (EV) sempre criptografa e protege o tráfego entre um GroundRunner e sua fonte de dados por meio da DigiCert®.

Observação: Para proteger os dados locais, os CloudRunners podem compartilhar a saída com os GroundRunners, mas os GroundRunners não podem compartilhar saídas de arquivos com o CloudRunner.

Solução de problemas de erros do GroundRunner

Se você receber esses erros quando uma cadeia for executada, verifique os GroundRunners do comando.

Dica: Para facilitar a solução de problemas, você pode criar uma cadeia para baixar automaticamente o arquivo de registro do GroundRunner para uma tabela.

Mensagem de erro	Causa	Resolução
Falha ao se comunicar com o agente - este comando não foi executado	O comando não pôde se comunicar com seu GroundRunner. Se isso acontecer, o GroundRunner não foi iniciado ou ocorreu uma interrupção de rede entre o GroundRunner e o Chain Builder.	Verificar O serviço do GroundRunner está funcionando. O servidor do GroundRunner está conectado à Internet.
Não foi possível fazer o download dos recursos associados ao comando. Entre em contato com o Suporte se o erro persistir.	Os executores associados a esses comandos da cadeia não podem se comunicar uns com os outros. Isso geralmente ocorre quando os comandos usam executores diferentes e o CloudRunner está tentando usar uma saída de arquivo de um comando baseado no GroundRunner.	Use o mesmo executor com todos os comandos da cadeia. Se os comandos da cadeia exigirem vários executores, verifique se nenhum comando com GroundRunners passa as saídas de arquivo para comandos que usam o CloudRunner.
Erro ao iniciar o comando: `exec: \"\\[connector].exe\": o arquivo não existe" commandExecutorId=[ID]`	Um aplicativo de malware ou antivírus identificou incorretamente o conector e interceptou sua comunicação com o GroundRunner.	Exclua o diretório de instalação do GroundRunner das verificações do aplicativo.
Erros de certificado	Como usar certificados autoassinados	Em muitos casos, será conveniente usar certificados autoassinados para criptografar a comunicação do GroundRunner. Se você estiver usando um certificado autoassinado, certifique-se de que o Common Name do certificado corresponda ao URL no qual o servidor pode ser acessado. Por exemplo, se o seu GroundRunner estiver escutando na porta 8821 e você puder acessar o servidor da sua rede `localhost`, o nome comum do certificado seria "`localhost`".
Falha intermitente na cadeia com o erro: "Conexão redefinida pelo par"	Quando vários executores são instalados na mesma máquina, cada um deve ter um GUID exclusivo. Se o mesmo GUID for usado, os executores poderão se sobrepor e entrar em um loop de atualização, causando falhas ocasionais na cadeia.	Recomendamos que você faça uma reinstalação completa do GroundRunner.
Os comandos são ignorados no GroundRunner, mas são bem-sucedidos no CloudRunner	Os websockets são necessários para executar as transformações. Quando os websockets estiverem desativados, todas as transformações serão totalmente ignoradas.	Abra seu arquivo de configuração e defina `DISABLE_WEBSOCKETS=false`.
Erro ao ler do soquete. `Tentando novamente/repetir a conexão: read tcp <IP>:<Port>-><IP>:<Port>: wsarecv: Uma tentativa de conexão falhou porque a parte conectada não respondeu adequadamente após um tempo, ou a conexão estabelecida falhou porque o host conectado não respondeu.`	Problema de firewall interno ou de rede	Peça à sua equipe interna de TI ou de rede para revisar os logs e a configuração a fim de resolver o erro.
read <IP>:<Port>-><IP>:<Port>: `wsarecv: Uma conexão existente foi fechada à força pelo host remoto`	Problema de firewall interno ou de rede	Peça à sua equipe interna de TI ou de rede para revisar os logs e a configuração a fim de resolver o erro.

Recursos adicionais

Suporte

Comunidade

Centro de suporte da Workiva