> For the complete documentation index, see [llms.txt](https://wiki.datadike.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.datadike.com/pt/sonar/deploy-operate/troubleshooting.md).

# Solucionar problemas dos agentes

Diagnostique agentes em Offline, Overdue ou Remote Offline, ações pendentes travadas e erros de instalador, com os locais de log e os comandos de serviço por sistema.

## O que é e quando usar

Use esta página quando um dispositivo não reporta, reporta com atraso, não pode ser alcançado para controle remoto, ou quando uma instalação falha. Ela parte do que o console mostra e depois passa ao dispositivo: os serviços dele, o log e o caminho de rede até o SONAR.

## Antes de começar

* O seu papel permite ver o dispositivo em **Dashboard › Sysadmin**. A aba **Debug** exige **View Debug Logs**; **Agents › Pending Actions** exige **List Pending Actions**, e cancelar uma ação exige **Manage Pending Actions**; **Restart Remote Service** exige **Use Mesh**.
* Para verificações no próprio dispositivo, você precisa de direitos de administrador no Windows ou de `root` no Linux e no macOS.

## Como o console decide o status de um dispositivo

O agente envia um sinal de vida (heartbeat) ao SONAR a cada 30 a 60 segundos, pela conexão com o endereço da API. **Last Response**, na lista de dispositivos, é a hora em que o SONAR recebeu o último sinal. A hora é marcada pelo SONAR na chegada, então o relógio do próprio dispositivo não afeta o status.

**Agent Status** compara **Last Response** com dois limiares definidos por dispositivo em **Edit** (menu de ações do dispositivo):

| Status      | Significado                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| **Online**  | Último contato mais recente que **Offline after (minutes)**                                                       |
| **Offline** | Sem contato há mais tempo que **Offline after (minutes)**                                                         |
| **Overdue** | Sem contato há mais tempo que **Overdue after (minutes)**. Os alertas de atraso são gerados a partir deste status |

Os limiares podem ser longos, por isso **Last Response** é o sinal mais rápido: um **Last Response** de mais de alguns minutos atrás significa que o agente não está conectado neste momento, seja qual for o status exibido.

O painel **Filters** da lista de dispositivos agrupa os dispositivos por janelas fixas em **Availability**: **Online**, **Offline 12+ hours**, **Offline 24+ hours**, **Offline 7+ days**, **Overdue** e **Maintenance Mode**.

O painel de detalhes acrescenta o estado do agente de acesso remoto: **Remote Online**, **Remote Offline** ou **Remote Unknown**.

## Passos

### Um dispositivo aparece como Offline ou Overdue

1. **O dispositivo está ligado e conectado?** Confira se ele está ligado e em uma rede. Um dispositivo desligado ou em suspensão aparece como **Offline** e depois como **Overdue**, e esse é o comportamento previsto.
2. **O serviço do agente está em execução?** No dispositivo:

   | Plataforma | Verificar                                                              | Iniciar ou reiniciar                                                       |
   | ---------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |
   | Windows    | `sc query sonarrmm`, ou **Sonar Agent Service** no console de Serviços | `net start sonarrmm`, ou `net stop sonarrmm` e depois `net start sonarrmm` |
   | Linux      | `systemctl status sonaragent`                                          | `sudo systemctl restart sonaragent`                                        |
   | macOS      | `sudo launchctl print system/sonaragent`                               | `sudo launchctl kickstart -k system/sonaragent`                            |

   Se o serviço não existir, o agente foi desinstalado: instale-o de novo.
3. **O dispositivo alcança o SONAR?** A partir do dispositivo, teste a porta 443/tcp até o endereço da API: `Test-NetConnection api.example.com -Port 443` no Windows, `curl` no Linux e no macOS. Um proxy ou uma inspeção de TLS no caminho pode deixar o HTTPS passar e, ainda assim, quebrar a conexão WebSocket de longa duração. Veja [Requisitos de rede](https://wiki.datadike.com/pt/sonar/deploy-operate/network-requirements.md).
4. **O que diz o log do agente?** Leia as últimas linhas do log (veja [Logs do agente](#logs-do-agente)). Erros de conexão com o endereço da API apontam para a rede; erros logo após a inicialização apontam para a configuração local.
5. Depois de corrigir, reinicie o serviço do agente. **Last Response** é atualizado em até um minuto e **Agent Status** volta a **Online**.

### Um dispositivo aparece como Remote Offline

**Remote Offline** significa que o agente SONAR está conectado, mas o agente de acesso remoto não está. **Take Control** fica desabilitado até o agente de acesso remoto se reconectar.

1. Selecione o dispositivo. Enquanto o agente está **Online** e o agente de acesso remoto está offline, o cabeçalho do painel de detalhes oferece **Restart Remote Service**.
2. Clique nele. O SONAR pede ao agente que reinicie o agente de acesso remoto no dispositivo (*Attempting to repair Mesh Agent*) e informa *Repaired mesh agent on \<hostname>* ao terminar.
3. Se o indicador não mudar para **Remote Online** em alguns minutos, reinicie o agente de acesso remoto no dispositivo:

   | Plataforma | Comando                                                   |
   | ---------- | --------------------------------------------------------- |
   | Windows    | `net stop "Mesh Agent"` e depois `net start "Mesh Agent"` |
   | Linux      | `sudo systemctl restart meshagent`                        |
   | macOS      | `sudo launchctl kickstart -k system/meshagent`            |
4. Se ele continuar offline, confira se o dispositivo alcança o endereço de acesso remoto em 443/tcp, com os upgrades de WebSocket permitidos.
5. Se o agente de acesso remoto não estiver no dispositivo, reinstale o agente SONAR (veja [Reinstalar sobre um agente existente](#reinstalar-sobre-um-agente-existente)).

No macOS, *Operation not permitted* em **Terminal** ou **File Browser** dentro das pastas Desktop, Documents ou Downloads de um usuário é uma questão de permissões, não de conexão. Veja [Instalar o agente no macOS](https://wiki.datadike.com/pt/sonar/deploy-operate/install-agent-macos.md#pastas-que-o-macos-protege).

### Ações pendentes não são concluídas

**Agents › Pending Actions** (**All Pending Actions**) lista o trabalho que o SONAR mantém em espera para os dispositivos: atualizações do agente (*Agent update to \<version>*), reinicializações agendadas (*Device pending reboot*), instalações de software (*\<name> software install*) e outros trabalhos em fila. Para um único dispositivo, use **Pending Agent Actions** no menu de ações dele, ou veja a coluna **Pending Actions** da lista de dispositivos.

1. Abra a lista e encontre o dispositivo.
2. Confira a coluna **Due**. Uma atualização do agente está prevista para o próximo ciclo de atualização, aos 35 minutos da hora; uma reinicialização agendada, para a hora em que foi marcada.
3. Uma ação pendente continua pendente enquanto o dispositivo está offline. Primeiro, traga o dispositivo de volta ao estado online (veja acima).
4. Para uma instalação de software concluída, **View output** mostra o que o instalador imprimiu (**Pending Action Output Details**).
5. Para descartar uma ação, clique com o botão direito na linha dela, escolha **Cancel Action** e confirme **Delete this pending action?**. Cancelar uma reinicialização agendada também a remove do dispositivo.
6. **Show N Completed** e **Hide N Completed** mostram e ocultam as ações concluídas na lista.

Veja [Atualizar agentes](https://wiki.datadike.com/pt/sonar/deploy-operate/agent-updates.md) para saber como as atualizações do agente são encerradas.

### Ler a aba Debug

A aba **Debug** do painel de detalhes mostra o que o SONAR registrou sobre o dispositivo, das entradas mais recentes para as mais antigas, até as últimas 1000 entradas.

1. Selecione o dispositivo e abra **Debug**.
2. Escolha um **Log Level**: **Info** (o padrão), **Warning**, **Error** ou **Critical**.
3. Se quiser, escolha um **Log Type**: **Agent Update**, **Agent Issues**, **Windows Updates**, **System Issues** ou **Scripting**.
4. Use **Search** para filtrar as linhas, ou **CSV** para exportá-las.

É nas entradas do tipo **Agent Update** e **Agent Issues** que ficam registrados, do lado do SONAR, os problemas de atualização e de conexão do dispositivo.

### Logs do agente

| Plataforma | Arquivo de log                                                                                                                   |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Windows    | `C:\Program Files\Sonar\agent.log` (`C:\Program Files (x86)\Sonar\agent.log` para um agente de 32 bits em um Windows de 64 bits) |
| Linux      | `/var/log/sonaragent.log`                                                                                                        |
| macOS      | `/var/log/sonaragent.log`                                                                                                        |

Para uma saída detalhada, pare o serviço e execute o agente em primeiro plano com log de depuração; depois, interrompa-o com Ctrl+C e inicie o serviço de novo:

| Plataforma               | Comandos                                                                                                                                                                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Windows (prompt elevado) | `net stop sonarrmm`, depois `"C:\Program Files\Sonar\sonarrmm.exe" -m rpc -log debug -logto stdout`, depois `net start sonarrmm`                                                                                                    |
| Linux                    | `sudo systemctl stop sonaragent`, depois `sudo /usr/local/bin/sonaragent -m svc -log debug -logto stdout`, depois `sudo systemctl start sonaragent`                                                                                 |
| macOS                    | `sudo launchctl bootout system /Library/LaunchDaemons/sonaragent.plist`, depois `sudo /opt/sonaragent/sonaragent -m svc -log debug -logto stdout`, depois `sudo launchctl bootstrap system /Library/LaunchDaemons/sonaragent.plist` |

No Windows, executar `"C:\Program Files\Sonar\sonarrmm.exe"` sem argumentos mostra uma caixa **Sonar RMM** com a versão do agente e o estado dos serviços do agente e do agente de acesso remoto.

### Reinstalar sobre um agente existente

| Plataforma | O que fazer                                                                                                                                                                                                                              |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Windows    | Desinstale primeiro com `"C:\Program Files\Sonar\uninstall.exe" /S` e depois execute um novo instalador. Um instalador executado sobre um agente existente oferece removê-lo (modo interativo) ou encerra sem instalar (modo silencioso) |
| Linux      | Execute o script de instalação de novo. Ele remove o agente anterior e o agente de acesso remoto antes de instalar                                                                                                                       |
| macOS      | Execute o comando de instalação de novo. Ele remove o agente anterior e o agente de acesso remoto antes de instalar                                                                                                                      |

Um dispositivo reinstalado entra como um novo registro de dispositivo. Remova o registro antigo, agora offline, com **Remove Agent**. Veja [Remover agentes](https://wiki.datadike.com/pt/sonar/deploy-operate/remove-agents.md).

Reinstalar é também a forma de alterar os recursos opcionais em um dispositivo Windows: gere um instalador com a nova seleção.

## Como verificar se funcionou

* Em **Dashboard › Sysadmin**, confira se o dispositivo mostra **Agent Status** **Online** e um **Last Response** de instantes atrás.
* No painel de detalhes, confira se o indicador mostra **Remote Online** e se **Take Control** está habilitado.
* Em **Agents › Pending Actions**, confira se as ações do dispositivo passaram a concluídas.
* No dispositivo, confira se o log do agente não mostra novos erros de conexão depois da reinicialização.

## Erros comuns

| Sintoma ou mensagem                                                                                                                                       | Causa                                                                                        | Correção                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| *Installer token has expired. Please generate a new one.*                                                                                                 | O instalador ou o link de implantação passou da validade, ou a implantação dele foi excluída | Gere um novo instalador ou uma nova implantação                                                                                 |
| *Old installer detected (version …). Latest version is … Please generate a new installer from the RMM*                                                    | O instalador foi gerado antes da versão atual do agente                                      | Gere um novo instalador                                                                                                         |
| *This application requires a 64-bit Windows operating system.*                                                                                            | Instalador de 64 bits em um Windows de 32 bits                                               | Use um instalador **32-bit**                                                                                                    |
| *Existing installation found* (caixa de mensagem), ou *Existing installation found and must be removed before attempting to reinstall.* (modo silencioso) | Um agente, ou o que restou de um, já está no dispositivo Windows                             | Desinstale com `uninstall.exe /S` e instale de novo                                                                             |
| *Sonar RMM Is Already Installed*                                                                                                                          | O instalador PowerShell encontrou o serviço `sonarrmm`                                       | Desinstale primeiro, ou deixe o dispositivo como está                                                                           |
| *Waiting for network* repetido, depois *Unable to connect to server*                                                                                      | O instalador PowerShell não consegue alcançar o endereço da API em 443/tcp                   | Corrija o caminho de rede; veja [Requisitos de rede](https://wiki.datadike.com/pt/sonar/deploy-operate/network-requirements.md) |
| *Unable to download the mesh agent from the RMM.* / *Failed to download mesh agent*                                                                       | O instalador não conseguiu obter o agente de acesso remoto pelo endereço da API              | Confira a conectividade com o endereço da API e execute o instalador de novo                                                    |
| *Invalid URL (must contain https or http)*                                                                                                                | O valor de `-api` de um comando manual foi editado ou truncado                               | Copie o comando de novo no console                                                                                              |
| *ERROR: Must be run as root* / *must run as root*                                                                                                         | Script do Linux ou agente do macOS executado sem root                                        | Execute com `sudo`                                                                                                              |
| *This install script only supports systemd*                                                                                                               | Distribuição Linux sem systemd                                                               | Não suportado; veja [Requisitos dos dispositivos](https://wiki.datadike.com/pt/sonar/deploy-operate/requirements.md)            |
| *ERROR: Display detected. Installer only supports running headless, i.e from ssh.*                                                                        | Script do Linux iniciado a partir de uma sessão gráfica                                      | Execute por SSH, a partir de um console de texto, ou depois de `unset DISPLAY`                                                  |
| *ERROR: Unable to download sonar agent*                                                                                                                   | O dispositivo Linux não consegue baixar do endereço da API                                   | Confira a porta 443/tcp e a resolução de nomes                                                                                  |
| Caixa de diálogo **Agent offline**, *… cannot be contacted*                                                                                               | O dispositivo não respondeu quando você escolheu **Remove Agent**                            | Veja [Remover agentes](https://wiki.datadike.com/pt/sonar/deploy-operate/remove-agents.md)                                      |
| *Unable to contact the agent*                                                                                                                             | Uma ação precisava de uma resposta do dispositivo e nenhuma chegou                           | Confira **Agent Status** e **Last Response**; traga o dispositivo de volta ao estado online                                     |
| Dispositivo **Online**, mas **Remote Offline**                                                                                                            | O agente de acesso remoto está parado ou não consegue alcançar o endereço de acesso remoto   | Use **Restart Remote Service** e depois confira o caminho de rede                                                               |
| O dispositivo aparece duas vezes na lista                                                                                                                 | Ele foi reinstalado e o registro antigo foi mantido                                          | Remova o registro offline com **Remove Agent**                                                                                  |

## Páginas relacionadas

* [Requisitos de rede](https://wiki.datadike.com/pt/sonar/deploy-operate/network-requirements.md)
* [Atualizar agentes](https://wiki.datadike.com/pt/sonar/deploy-operate/agent-updates.md)
* [Remover agentes](https://wiki.datadike.com/pt/sonar/deploy-operate/remove-agents.md)
* [Detalhes do dispositivo](https://wiki.datadike.com/pt/sonar/administration/devices/device-details.md)
* [A lista de dispositivos](https://wiki.datadike.com/pt/sonar/administration/devices/device-list.md)
