Agente

Informações sobre o agente CtrlStation

Requisitos Agente CtrlStation - Windows

Agente CtrlStation - Windows

O agente CtrlStation para Windows é uma aplicação que é executada como serviço do sistema e faz o monitoramento de eventos e aplica o bloqueio de tela o logoff às sessões do usuário de acordo com as regras configuradas na plataforma CtrlStation

Versões Suportadas

O agente CtrlStation Windows tem suporte às versões:

Comunicação 

O agente ser comunica através de HTTPS com a plataforma CtrlStation.

Instalação Agente - Windows

Versão

A versão mais recente do agente é a v1.6.7 lançada em 12/12/2024

Link para download: https://files.lab3dvlp.com/ul/ctrl-station-agent-v.1.6.7msi

Instalação Manual

Para instalar o agente de forma manual basta clicar duas vezes no arquivo MSI e será inicializado o assistente de instalação:

image.png

Clique em "Próximo" e selecione o local de instalação (é recomendado manter o padrão):

image.png

Clique em "Próximo" e em seguida preencha os dados do servidor:

image.png

O campo "URL Servidor" deve ser https://[seu dominio ctrlstation]/api e o Token Acesso é o código disponível dentro da plataforma no menu "Configurações - Licença"

Em seguida clique em "Próximo" e então em "Instalar". Será solicitada o aumento de privilégio do Windows, aceite e a instalação deve ser finalizada.

Após a instalação o serviço do CtrlStation Agent será inicializado automaticamente.

Instalação Automatizada - Linha de Comando

Caso deseje efetuar a instalação utilizando ferramentas automatizada, é possível utilizar a linha de comando (Prompt de Comando ou PowerShell) para instalar. Para isto utilize a linha a seguir:

msiexec -i ctrl-station-agent-v1.6.7.msi SERVER_URL=https://[ambiente].ctrlstation.com/api SERVER_TOKEN=[TOKEN] /qb

Agente CtrlStation - MacOS

CtrlStationAgent - MacOS

Este documento é voltado ao CtrlStationAgent em estações de trabalho macOS gerenciadas. Ele explica o que o agente faz, como instalá-lo e desinstalá-lo, como conceder as permissões necessárias e como ler os logs em caso de problemas.

O que o agente faz

O CtrlStationAgent é um pequeno agente em segundo plano (sem ícone no Dock e sem janela principal) que aplica a política de sessão da estação de trabalho em nome do backend do CtrlStation. No Mac de cada usuário, ele:

Ele é executado uma vez por usuário logado, inicia automaticamente no login e é reiniciado automaticamente caso pare.

Atenção ao impacto no usuário: quando o backend bloqueia um usuário, a tela dele será bloqueada ou ele será deslogado — possivelmente de forma repetida até que o backend remova o bloqueio. Certifique-se de que a política do backend esteja correta antes de uma implantação ampla.

Requisitos

Requisito Detalhe
Versão do macOS macOS 26.0 ou superior (deployment target do build). Macs mais antigos não executarão o agente, a menos que o app seja recompilado com um target menor.
Privilégios Direitos de administrador para instalar (o pacote grava em /Applications e /Library).
Rede HTTPS de saída para o backend configurado, atualmente https://[cliente].ctrlstation.com/api.
Permissões Automação (Apple Events) e Acessibilidade — ver Seção 4.
Assinatura O pacote é assinado com um Developer ID da LAB3 e notarizado, portanto instala sem avisos do Gatekeeper.

Instalação

O entregável é um pacote instalador assinado e notarizado, por exemplo CtrlStationAgent-v1.3.3.pkg. O link para download é fornecido pela LAB3 ou pelo seu parceiro de revenda

Opção A — Interativa (máquina única)

  1. Dê um duplo-clique no .pkg.
  2. Siga o instalador e autentique-se como administrador quando solicitado.

Opção B — Linha de comando / script

sudo installer -pkg /caminho/para/CtrlStationAgent-v1.3.3.pkg -target /

Opção C — MDM (implantação em frota)

Envie o .pkg para o seu MDM (Jamf, Kandji, Mosyle, Intune, etc.) e direcione-o às máquinas-alvo. Envie também o perfil de privacidade (PPPC) descrito na Seção 4 para que o agente funcione sem prompts de permissão por usuário.

O que o instalador faz

O script postinstall do pacote automaticamente:

Não é necessário reiniciar.

Permissões 

Sob a proteção de privacidade do macOS (TCC), o agente precisa de duas permissões para executar todas as suas ações:

Permissão Por quê Quando é necessária
Automação → System Events (Apple Events) Usada para encerrar a sessão do usuário de forma controlada. Quando a ação do backend é "logout".
Acessibilidade Mecanismo alternativo para bloquear a tela via simulação de tecla, caso o método principal de bloqueio não esteja disponível em determinada versão do macOS. Raramente — apenas se o método de bloqueio silencioso preferencial falhar.

Em um Mac não gerenciado, o macOS exibirá um prompt único na primeira vez que o agente tentar essas ações (por exemplo, "CtrlStationAgent deseja controlar o System Events"). O usuário precisa clicar em OK / ativar a opção em Ajustes do Sistema → Privacidade e Segurança.

Para implantação em frota, pré-aprove essas permissões com um perfil PPPC (Privacy Preferences Policy Control) via MDM, para que os usuários nunca vejam prompts e a aplicação da política nunca seja bloqueada:

Em algumas versões do macOS, a Acessibilidade não pode ser concedida por um payload PPPC isolado; a maioria dos MDMs oferece um controle dedicado de "Acessibilidade" no editor de PPPC. Conceda por lá.

Verificar se está em execução

Execute na máquina-alvo (como o usuário logado):

# O processo está ativo?
pgrep -lf CtrlStationAgent

# Status do LaunchAgent (procure por "state = running" e o caminho do programa)
launchctl print "gui/$(id -u)/com.lab3dvlp.CtrlStationAgent" | grep -E "state|program"

Um agente saudável reporta state = running e um caminho de programa /Applications/CtrlStationAgent.app/Contents/MacOS/CtrlStationAgent.

Confirme se a configuração foi aplicada corretamente (admin):

sudo cat "/Library/Application Support/CtrlStationAgent/config.json"

Verificar os logs

O agente registra através do sistema de logs unificado do macOS (não há arquivos de log separados). Use o Console.app ou o comando log, filtrando pelo subsistema do agente.

# Acompanhamento ao vivo — deixe rodando e então bloqueie/desbloqueie ou aguarde um heartbeat:
log stream --predicate 'subsystem == "com.lab3dvlp.CtrlStationAgent"'

# Histórico recente (última hora). Adicione --debug para incluir as linhas de nível
# debug (heartbeats, etc.), que NÃO são persistidas por padrão:
log show --debug --predicate 'subsystem == "com.lab3dvlp.CtrlStationAgent"' --last 1h

Você pode restringir a uma área usando o campo category. Categorias disponíveis: app, api, events, heartbeat, session, notifications, action, config.

# Apenas eventos de sessão e atividade de aplicação de política:
log stream --predicate 'subsystem == "com.lab3dvlp.CtrlStationAgent" AND (category == "events" OR category == "action")'

No Console.app: abra-o, inicie o streaming e digite o subsistema com.lab3dvlp.CtrlStationAgent na barra de busca (defina o filtro como "Subsistema").

O que você normalmente verá: Evento detectado: Tela Bloqueada/Desbloqueada, Executando heartbeat..., API confirmou bloqueio; reaplicando em 2s e Exibindo notificação customizada: … para mensagens do servidor.

Solução de problemas

Sintoma Verificação
Agente não está em execução pgrep -lf CtrlStationAgent. Se vazio, confirme que o plist existe em /Library/LaunchAgents/com.lab3dvlp.CtrlStationAgent.plist e o app em /Applications/CtrlStationAgent.app. Peça ao usuário para sair/entrar novamente, ou inicie manualmente (Seção 8).
Agente inicia e encerra Configuração ausente/inválida. O agente encerra se o config.json estiver ausente ou malformado. Verifique /Library/Application Support/CtrlStationAgent/config.json. Consulte a categoria de log config.
Eventos não chegam ao backend Acessibilidade de rede/API. Verifique as categorias de log api e events em busca de erros; confirme o HTTPS de saída para a URL do backend.
Ação de logout não faz nada Permissão de Apple Events (Automação) não concedida. Ver Seção 4. Verifique as categorias action/session.
A tela não bloqueia Raro — verifique a categoria session; o mecanismo alternativo por tecla requer Acessibilidade (Seção 4).
Mensagens do servidor não aparecem Cada mensagem é exibida apenas uma vez por máquina (registrada no arquivo por usuário da Seção 9). Uma mensagem já vista não reaparecerá.

Iniciar / parar / reiniciar o agente manualmente

Execute como o usuário logado (estes comandos atuam na sessão GUI desse usuário):

# Parar (descarregar)
launchctl bootout "gui/$(id -u)/com.lab3dvlp.CtrlStationAgent"

# Iniciar (carregar)
launchctl bootstrap "gui/$(id -u)" /Library/LaunchAgents/com.lab3dvlp.CtrlStationAgent.plist

# Reiniciar = bootout e depois bootstrap

Para atuar na sessão de outro usuário, substitua $(id -u) pelo UID numérico daquele usuário (descubra-o com id -u <nome_do_usuario>); esses comandos exigem admin/root.

Desinstalação

Não há pacote desinstalador; remova os componentes manualmente ou via script no MDM.

# 1. Pare o agente para o usuário logado (repita por usuário logado / UID)
launchctl bootout "gui/$(id -u)/com.lab3dvlp.CtrlStationAgent" 2>/dev/null

# 2. Remova a definição do LaunchAgent (admin)
sudo rm -f /Library/LaunchAgents/com.lab3dvlp.CtrlStationAgent.plist

# 3. Remova o aplicativo (admin)
sudo rm -rf /Applications/CtrlStationAgent.app

# 4. Remova a configuração do sistema (admin) — isto apaga o token do backend
sudo rm -rf "/Library/Application Support/CtrlStationAgent"

# 5. Esqueça o recibo do instalador (admin)
sudo pkgutil --forget com.lab3dvlp.CtrlStationAgent

# 6. Remova os dados por usuário (execute para CADA conta que tenha feito login)
rm -rf "$HOME/Library/Application Support/CtrlStationAgent"

Após a remoção, opcionalmente remova o perfil PPPC do MDM, caso tenha enviado um.

Remover o plist do LaunchAgent e o app e, em seguida, fazer o usuário sair/entrar novamente já é suficiente para interromper a aplicação da política. Os passos 4 a 6 são limpeza.

Referência

Item Valor
Bundle do app /Applications/CtrlStationAgent.app
Identificador do bundle / label do LaunchAgent com.lab3dvlp.CtrlStationAgent
Plist do LaunchAgent /Library/LaunchAgents/com.lab3dvlp.CtrlStationAgent.plist
Arquivo de configuração /Library/Application Support/CtrlStationAgent/config.json
Dados por usuário (mensagens já vistas) ~/Library/Application Support/CtrlStationAgent/
API do backend https://[cliente].ctrlstation.com/api (definida no config.json)
Subsistema de log com.lab3dvlp.CtrlStationAgent
Time (team) do Developer ID S9DE935KXJ (LAB3 Desenvolvimento de Software Ltda ME)
Intervalo do heartbeat 30 segundos
Início/reinício automático LaunchAgent RunAtLoad + KeepAlive

Agente CtrlStation - Linux

Agente CtrlStation - Linux

O Agente CtrlStation é um daemon de sistema projetado para ambientes que necessitam de monitoramento e gerenciamento remoto de estações de trabalho Linux.

O que é o Agente CtrlStation?

O Agente é um serviço que roda em segundo plano no computador do usuário e executa as seguintes funções:

Como Baixar

A versão mais recente do pacote de instalação (.deb) pode ser baixada do link a seguir:

Será solicitado usuário e senha que são fornecidos pela LAB3 ou seu parceiro de revenda.

Requisitos de Sistema

Instalação via Pacote (.deb)

A instalação é simples e deve ser feita através do terminal. O uso do comando apt é recomendado pois ele instala automaticamente todas as dependências necessárias.

  1. Abra um terminal.

  2. Navegue até o diretório onde você baixou o arquivo .deb.

  3. Execute o comando a seguir, substituindo o nome do arquivo pelo que você baixou:

sudo apt install ./ctrl-station-agent_1.2.0-1_amd64.deb

O terminal solicitará sua senha de administrador. Após a confirmação, o apt instalará o agente, suas dependências (como Python e Zenity) e configurará o serviço para iniciar automaticamente.

Desinstalação

Para remover completamente o Agente CtrlStation do sistema, utilize o seguinte comando no terminal:

sudo apt remove ctrl-station-agent

Isso removerá a aplicação. Se você também desejar remover os arquivos de configuração, utilize o comando purge:

sudo apt purge agente-ctrlstation

Funcionamento e Logs

Como Funciona

Verificando a Atividade (Logs)

Para monitorar a atividade do agente ou diagnosticar problemas, você pode visualizar seus logs em tempo real. Como o serviço roda no contexto do usuário, utilize o seguinte comando no terminal do usuário logado:

journalctl --user -u monitor-daemon.service -f