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: 

 

 Windows 7 

 Windows 8 

 Windows 8.1 

 Windows 10 

 Windows 11 

 

 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: 

 

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

 

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

 

 

 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: 

 

 Reporta eventos de sessão ao backend: logon, bloqueio de tela, desbloqueio de tela e logout. 

 Consulta o backend a cada 30 segundos ( /user/status ). Se o backend marcar o usuário como bloqueado , o agente aplica a ação configurada:

 

 Bloquear a tela , ou 

 Encerrar a sessão do usuário (logout) . 

 

 

 Reaplica o bloqueio ao desbloquear. Se um usuário bloqueado desbloquear a tela, o agente reconsulta o backend; se o usuário continuar bloqueado, exibe o aviso "Acesso Bloqueado" e bloqueia novamente (ou faz logout) após ~2 segundos. Se o backend estiver inacessível nesse momento, o usuário permanece desbloqueado (comportamento "fail-open"). 

 Exibe mensagens enviadas pelo servidor ao usuário em pequenas janelas pop-up não bloqueantes. Cada mensagem é exibida apenas uma vez por máquina. 

 

 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) 

 

 Dê um duplo-clique no .pkg . 

 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: 

 

 Instala o app em /Applications/CtrlStationAgent.app . 

 Grava o arquivo de configuração (URL do backend + token de acesso) em /Library/Application Support/CtrlStationAgent/config.json e restringe sua propriedade/permissões ( root:wheel , 644 ). 

 Instala o LaunchAgent em /Library/LaunchAgents/com.lab3dvlp.CtrlStationAgent.plist . 

 Inicia o agente imediatamente para o usuário logado no console naquele momento. Os demais usuários recebem o agente automaticamente no próximo login. 

 

 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: 

 

 Identificador: com.lab3dvlp.CtrlStationAgent (Bundle ID) 

 Tipo de identificador: Bundle ID 

 Requisito de código (code requirement): 

 identifier "com.lab3dvlp.CtrlStationAgent" and anchor apple generic and certificate leaf[subject.OU] = "S9DE935KXJ"

 

 

 Serviços a permitir: 

 

 SystemPolicyAllFiles — não é necessário. 

 Apple Events — permitir, com destino com.apple.systemevents . 

 Acessibilidade — permitir. 

 

 

 

 

 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: 

 

 

 Monitoramento de Sessão : Envia notificações para um servidor central quando eventos de sessão ocorrem (Logon, Logout, Bloqueio e Desbloqueio de tela). 

 

 

 Comunicação Periódica : Efetua uma chamada de "heartbeat" a cada 30 segundos para o servidor, informando que a estação está ativa. 

 

 

 Execução de Ações Remotas : Recebe comandos do servidor para executar ações na máquina local, como: 

 

 

 Bloquear a sessão do usuário. 

 

 

 Encerrar a sessão do usuário (logoff). 

 

 

 Exibir notificações e avisos em formato de popup. 

 

 

 

 

 Como Baixar 

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

 

 

 https://download.ctrlstation.com/ctrl-station-agent_1.2.0-1_amd64.deb 

 

 

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

 Requisitos de Sistema 

 

 

 Sistema Operacional : Ubuntu 20.04 LTS (ou superior) ou Debian 11 (ou superior). 

 

 

 Arquitetura : amd64 (x86_64). 

 

 

 Ambiente Gráfico : Necessário para a exibição de notificações (ex: GNOME, KDE, XFCE). 

 

 

 Conexão de Rede : Conectividade via porta 443 (HTTPS) com o servidor do CtrlStation 

 

 

 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. 

 

 

 Abra um terminal. 

 

 

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

 

 

 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 

 

 

 O Agente é instalado como um serviço de usuário global do systemd . 

 

 

 Isso significa que uma instância do serviço será iniciada automaticamente para cada usuário que fizer login no sistema. 

 

 

 O processo roda com as permissões do próprio usuário, garantindo a segurança e a integração com o ambiente gráfico. 

 

 

 O arquivo de configuração principal, que contém a URL do servidor e o token de acesso, está localizado em: 

 

 

 

 

 

 

 /etc/ctrl-station/config.ini 

 

 

 

 

 

 

 

 Nota para Administradores: Após a instalação, este arquivo deve ser editado para inserir as informações corretas do seu ambiente. 

 

 

 

 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