Instalar o agente Windows

O agente é o que transforma um PC em um dispositivo gerenciado. Sem ele não há monitoramento, nem aplicação de patches, nem acesso remoto, nem inventário.

Este guia cobre o caminho inteiro: gerar o instalador, levá-lo até a máquina, confirmar o cadastro e, acima de tudo, saber o que olhar quando o dispositivo não aparece.

Gerar o instalador

Vá em Clientes, abra o cliente, aba Dispositivos, seção Instalador, botão + Criar instalador. Você precisa da permissão Gerenciar computadores.

Abre uma caixa de diálogo com duas abas, Windows e Linux. Na aba Windows você preenche:

Depois Gerar. A geração leva entre 30 e 90 segundos, e a tela avisa isso.

Não feche a caixa de diálogo enquanto ela está gerando. Fechar no meio da geração descarta o instalador e você tem que começar de novo. Quando aparecer Instalador pronto, você pode fechar com segurança: ele fica na lista de instaladores do cliente.

As três etiquetas opcionais viajam dentro do MSI e se preenchem sozinhas na ficha do dispositivo quando ele é cadastrado. Se você gerar o instalador sem elas, esses campos ficam vazios.

O que é esse arquivo

Um MSI de uns 17 MB, chamado kairoslink-installer-{number}.msi.

O instalador é por cliente, não por organização. Ele carrega dentro a credencial de cadastro desse cliente, e é por isso que o MSI de um cliente não funciona para outro.

Um MSI funciona em vários dispositivos do mesmo cliente por 7 dias. Você não precisa de um por máquina: gere um e use no lote inteiro.

O que o instalador não carrega é a senha da área de trabalho remota. A própria máquina a gera, aplica com hash e a informa ao painel no cadastro. Ela nunca fica armazenada em texto puro no instalador nem no disco.

Levar o instalador até a máquina

São quatro caminhos, e você escolhe pela escala.

Download direto

Na caixa de diálogo que você acabou de usar, ou no menu da linha na lista de instaladores, Baixar. Você precisa estar logado.

Link público, sem login

Botão Copiar link. Ele produz um endereço que qualquer pessoa abre sem usuário e sem senha: envie para quem está na máquina e essa pessoa mesma baixa o MSI.

É o caminho mais rápido para instalar em uma máquina distante. O link vence em 7 dias, igual ao instalador, e a tela mostra a data exata.

Esse link é uma credencial: quem o tiver pode adicionar dispositivos a esse cliente enquanto ele valer.

Instalação silenciosa

Com o MSI na máquina, em um console elevado:

msiexec /i "C:\path\kairoslink-installer-123.msi" /qn /norestart /L*v "C:\ProgramData\KairosLink\deploy\msi.log"

/qn instala sem interface, /norestart evita a reinicialização e /L*v deixa um log detalhado que é útil para o diagnóstico depois.

Não há propriedades de linha de comando para passar. Não existe TOKEN= nem SERVER=: a credencial já viaja dentro do MSI, então o comando é sempre o mesmo.

Este é o comando que você usa se implanta com seu próprio script ou com outra ferramenta.

Implantação em massa via GPO

Se o cliente tem um domínio e você já tem o agente instalado no Domain Controller, o KairosLink monta a GPO para você.

Em Monitoramento, Active Directory, opção de implantação: Instalar o agente nos computadores do domínio. Isso exige a permissão de implantação de agentes, que por padrão só o Proprietário e o Admin têm.

O Domain Controller copia o MSI para o SYSVOL e cria uma política com uma tarefa imediata que roda em cada computador escolhido como SYSTEM. Você escolhe entre a entrega Automática, que cria e vincula a GPO, ou Manual, que deixa um backup para importar com o GPMC.

Duas coisas determinam o resultado:

• Quando ele instala. O caminho que instala com certeza é a reinicialização. Se a tarefa imediata também rodar, a instalação acontece antes, na próxima atualização de política, aproximadamente de 90 minutos a 2 horas.
• Com a entrega Manual a GPO não fica vinculada. Enquanto você mesmo não vinculá-la com o GPMC, nenhum computador instala nada, por mais criada que a campanha pareça.

O limite é de 500 dispositivos por campanha. Se um computador já tem o KairosLink instalado, o script não o reinstala.

O que a máquina precisa

Privilégios de administrador local. O MSI instala um serviço, então o console tem que estar elevado. Na implantação via GPO isso já está resolvido, porque ela roda como SYSTEM.

Internet de saída na 443. O agente precisa alcançar o painel por HTTPS para se cadastrar, enviar heartbeats e receber comandos, além de relay.kairoslink.io por WSS para o acesso remoto quando não há caminho direto.

Nenhum IP público e nenhuma porta de entrada. Todas as conexões são iniciadas pelo agente, para fora. O acesso remoto negocia o caminho em três etapas: LAN, conexão direta entre pares e relay como último recurso, quando o NAT ou o firewall bloqueiam a rota direta.

A máquina não precisa alcançar o GitHub. O painel faz proxy do binário, então o download sempre vem de um domínio do KairosLink.

TLS 1.2. Versões antigas do Windows que não o suportam podem falhar ao reportar.

Antes de cadastrar um dispositivo novo, o KairosLink verifica o limite do seu plano. Uma reinstalação sobre um dispositivo que já existe nunca esbarra nesse limite.

O que acontece no primeiro início

Assim que o agente inicia, ele se cadastra no painel: apresenta a credencial que veio no MSI, informa seu hostname e sua impressão digital de hardware, e gera a senha da área de trabalho remota que ele informa ao painel.

Se estiver tudo certo, o painel responde e emite para essa máquina uma credencial individual própria.

O dispositivo aparece na hora. Não há fila nem processo intermediário: assim que o cadastro responde, o dispositivo já está listado em Dispositivos como online.

Daí em diante ele envia um heartbeat a cada 20 segundos. Se parar, ele passa para offline depois de 70 segundos.

O que se preenche sozinho

Do agente: hostname, sistema operacional, versão, CPU, memória, IP público, IP local e o identificador da área de trabalho remota.

Do instalador: local, departamento e tipo de dispositivo, se você os definiu ao gerá-lo.

Os alertas por e-mail desse dispositivo começam desligados, de propósito. O dispositivo é monitorado desde o minuto zero, mas não envia um único e-mail até você ligar a chave no registro dele. Se você instala um agente e espera um e-mail sobre alguma coisa, ele não vem até você habilitar.

As notas do dispositivo ficam vazias: essas são preenchidas à mão.

Confirmar que funcionou

No painel, a tela Dispositivos. Encontre o dispositivo e olhe a coluna Visto por último: é isso que confirma que ele está vivo de verdade, e não apenas cadastrado. Um dispositivo que se cadastrou mas não envia heartbeats passa para Offline depois de 70 segundos.

O painel distingue Offline de Offline sem aviso. O primeiro é um desligamento que o agente anunciou; o segundo é uma queda de energia, um travamento ou uma perda de rede. Um agente que nunca falou cai na segunda categoria.

Na máquina, o produto fica registrado na desinstalação do Windows com um nome que começa com KairosLink. Se você instalou com /L*v, o log do msiexec conta exatamente o que aconteceu.

Quando o dispositivo não aparece

Esta é a parte que importa. Cada causa tem um sintoma que a distingue das outras, então a ordem do diagnóstico é esta:

Passo 1: a instalação terminou limpa?

Verifique o código de saída do msiexec, ou o log se você usou /L*v. Os códigos mais comuns:

Se o código é 0 e o dispositivo mesmo assim não aparece, a instalação não é o problema: o problema é rede ou credencial. Vá para o passo 2.

Passo 2: o dispositivo não aparece de jeito nenhum

Estas são as causas reais, em ordem de frequência:

O MSI venceu ou a credencial dele foi rotacionada. Um instalador vive 7 dias. E se alguém rotacionou a credencial de cadastro desse cliente, todo MSI gerado antes disso fica inútil para cadastrar dispositivos novos. Solução: gere um instalador novo.

O cliente do instalador foi excluído. Excluir um cliente revoga as credenciais de cadastro dele. O agente recebe uma mensagem explícita dizendo que aquele instalador pertence a um cliente que não existe mais.

O limite de dispositivos do plano foi atingido. Isso afeta apenas dispositivos novos. Se você está reinstalando sobre um que já existe, não é isso.

A máquina não tem rota até o painel. Este é o único caso silencioso: nada fica registrado do lado do servidor, porque a conexão nunca chegou. Se o dispositivo não aparece em lugar nenhum e a instalação retornou 0, tente alcançar o painel na 443 a partir dessa máquina.

Passo 3: o dispositivo aparece mas não reporta

O sistema foi reinstalado, uma imagem foi restaurada ou a placa-mãe foi trocada. O dispositivo já tinha sua credencial individual e agora apresenta uma impressão digital de hardware diferente, então o KairosLink recusa o novo cadastro por segurança. Este é o único caso em que o dispositivo está no painel, com um registro completo, e o cadastro falha mesmo assim.

Solução: na ficha do dispositivo, Revogar a credencial. O agente então se cadastra de novo sozinho.

O dispositivo foi movido entre clientes e o agente dele é antigo. Se o agente não tem credencial individual, ele depende da credencial compartilhada do cliente. Depois da mudança, essa credencial não confere mais e o dispositivo para de reportar. Solução: reinstale com o instalador do cliente novo.

A credencial do dispositivo foi revogada pelo painel. O acesso do agente é cortado na hora e ele não volta até se cadastrar de novo.

Passo 4: instala, aparece por um instante e some

Alguém apertou Desinstalar o agente nesse dispositivo e a marcação continua ativa. Reinstalar não a limpa: o agente se cadastra, recebe a ordem de desinstalação no primeiro heartbeat e vai embora.

É fácil de identificar porque o dispositivo aparece na lista e some sozinho em segundos.

Se você implantou via GPO e ninguém se cadastra

O painel tem um diagnóstico próprio na campanha, que verifica até 25 computadores por execução e diz qual destes casos aconteceu:

• O computador nunca processou a política, porque ela não chegou até ele ou porque ele não atualizou desde que ela foi criada
• O computador informa a GPO como negada
• A política não aparece na lista desse computador
• Nada pôde ser verificado porque o computador não responde na porta 135 a partir do DC
• O log do Agendador de Tarefas está desabilitado nesse computador
• A tarefa rodou e o msiexec falhou, com o código e a tradução dele
• A instalação rodou bem e o agente não fez contato, que é o caso em que o problema é rede ou credencial, não a implantação

Vale ter em mente o que o próprio painel avisa: a GPO ter sido criada e vinculada corretamente só diz o que o Domain Controller fez. O que acontece nos computadores é desconhecido até você pedir o diagnóstico.

Desinstalar

São três ações distintas e elas fazem coisas diferentes:

Desinstalar o agente é o caminho recomendado: deixa a máquina e a lista limpas.

Remover da lista serve para quando a máquina não existe mais. Se o agente continuar instalado em algum lugar, você vai ter que desinstalá-lo lá.

Se você excluir o cliente inteiro, os dispositivos dele param de aparecer e os alertas abertos são fechados, mas o agente continua instalado em cada máquina. Para deixar tudo limpo, você tem que desinstalá-lo em cada uma.

Reinstalar

Reinstalar sobre um dispositivo existente não o duplica: o KairosLink o reconhece pela impressão digital de hardware e, na falta dela, pelo hostname.

Duas coisas que a reinstalação sobrescreve, e vale conhecer:

• O nome do dispositivo. Se você o renomeou à mão no painel, ele volta para o nome do instalador ou para o hostname.
• Local, departamento e tipo de dispositivo. Eles são reescritos com o que o MSI novo carrega. Se você gerou esse MSI sem etiquetas, esses campos acabam vazios.

O que não é sobrescrito é a chave de alertas por e-mail: reinstalar o agente não liga os e-mails de novo em um dispositivo que estava com eles desligados.

Mover um dispositivo entre clientes

O caminho correto é editar o dispositivo e mudar o cliente dele pelo registro. Não reinstale.

Se esse dispositivo tem credencial individual, ele continua reportando sem que você toque em nada.

Se for um agente antigo usando a credencial compartilhada do cliente, ele para de reportar depois da mudança e tem que ser reinstalado com o instalador do cliente novo.

Atualizar o agente

O agente não se atualiza sozinho. Você despacha a atualização pelo painel: registro do cliente, aba Agentes, botão Atualizar agentes.

Só são elegíveis os dispositivos que estão online e que ainda não estão na versão atual. O despacho sai em lotes de 10 dispositivos a cada 5 minutos, para que o parque de dispositivos inteiro não seja atingido de uma vez.

O agente verifica a integridade do arquivo antes de executá-lo, e não o executa se ele não conferir. Como o agente se reinstala sozinho, a confirmação de que funcionou é o heartbeat seguinte informando a versão nova. Se nada chegar em 15 minutos, ele é marcado como falho: um dispositivo nunca fica preso em "Atualizando" para sempre.

Um agente antigo continua funcionando. Na tela de Agentes ele fica agrupado em desconhecida enquanto não informar sua versão no heartbeat.

O que ele não faz hoje

• Não há integração com Intune, SCCM, PDQ nem Chocolatey. A implantação em massa é via GPO pelo painel, ou com seu próprio script usando o link público e a linha do msiexec.
• Não há versão do agente por organização. A versão atual é uma só em toda a plataforma. Você escolhe quando atualizar e quais dispositivos, não qual versão.
• O agente nunca se atualiza sozinho. Quem despacha é sempre o painel.

Perguntas frequentes

Preciso de um instalador por dispositivo? Não. Um por cliente serve para todos os dispositivos daquele cliente por 7 dias.

O MSI de um cliente funciona para outro cliente? Não. Ele carrega dentro a credencial daquele cliente.

Quanto tempo até o dispositivo aparecer? Na hora. Assim que o agente se cadastra, ele está na lista.

Instalei e não aparece nada. Por onde eu começo? Pelo código de saída do msiexec. Se ele retornou 0, a instalação não é o problema: verifique se a máquina alcança o painel na 443 e se o instalador venceu.

Restaurei uma imagem e o dispositivo parou de reportar. A impressão digital de hardware dele mudou. Vá à ficha do dispositivo e use Revogar a credencial: o agente se cadastra de novo sozinho.

Posso instalar sem ser administrador? Não. O MSI instala um serviço e precisa de elevação.

Preciso abrir portas no firewall do cliente? De entrada não. O agente inicia todas as conexões para fora, na 443.

Desinstalei o agente à mão e o dispositivo continua na lista. Isso é esperado. Use Remover da lista para tirá-lo do painel.

Movi um dispositivo para outro cliente e ele parou de reportar. O agente dele usa a credencial compartilhada do cliente anterior. Reinstale com o instalador do cliente novo.

Instalei o agente e não chega nenhum e-mail de alerta. Os alertas por e-mail começam desligados em todo dispositivo. Ligue a chave na ficha do dispositivo.