Ir para o conteúdo principal

Agente CtrlStation - MacOS

CtrlStationAgent — MacOS

Está página refere-se ao CtrlStationCtrlStationAgent Agentem paraestaçõ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 CtrlStation AgentCtrlStationAgent é um serviç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 segundotrabalho planoem paranome macOSdo projetadobackend parado monitorarCtrlStation. 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 atividadecada da30 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 e interagir com um servidor de gerenciamento remoto.

      Suas principais funções são:

      • Monitorar Eventos(logout): Detecta e reporta quando o usuário realiza as seguintes ações:

        • Logon (início da sessão)

        • Logout (fim da sessão)

        • Bloqueio de Tela

        • Desbloqueio de Tela

          .

      • Controle de Jornada: A cada 30 segundos, contataReaplica o servidorbloqueio CtrlStationao desbloquear. para verificar se há comandos remotos para:

        • Bloquear a tela ou efetuar logout do usuário.

        • Exibir notificações de aviso em popup

      O agente é configurado comoSe um serviço de usuário (LaunchAgent),bloqueado desbloquear a tela, o queagente significareconsulta queo elebackend; inicia automaticamente quandose 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 paraé reiniciado automaticamente caso pare.

    Atenção ao impacto no usuário: quando ele faz logout.

    Requisitos

    • Sistema Operacional: macOS Ventura (versão 13.0)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.

    2. Requisitos

    RequisitoDetalhe
    Versão do macOSmacOS 26.0 ou superior (deployment target do build). Macs mais recente.

    antigos não executarão

    Download

    o agente, a menos que o app seja recompilado com um target menor.
    PrivilégiosDireitos de administrador para instalar (o pacote grava em /Applications e /Library).
    RedeHTTPS de saída para o backend configurado https://[cliente].ctrlstation.com/api.
    PermissõesAutomação (Apple Events) e Acessibilidade — ver Seção 4.
    AssinaturaO pacote é assinado com um Developer ID da LAB3 e notarizado, portanto instala sem avisos do Gatekeeper.

    3. Instalação

    O agenteentregável é distribuído como um pacote deinstalador instalaçãoassinado e notarizado, por exemplo .CtrlStationAgent-v1.3.3.pkg. através de umO link para download é fornecido pela LAB3 ou pelo seu parceiro de revenda

    Instalação

    A instalaçOpção éA simples— eInterativa guiada.(máquina Siga os passos abaixo:

    única)

    1. Execute o Instalador Dê um duplo duplo-clique no arquivo.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 CtrlStationAgent-v1.2.1..pkg que você baixou.

  • Siga as Instruções Prossiga pelas telas do instalador. Ele copiará os arquivos necessários para aso pastasseu corretasMDM (Jamf, Kandji, Mosyle, Intune, etc.) e configurarádirecione-o às máquinas-alvo. Envie também o serviço.

  • Aprove a Permissãoperfil de Automaçprivacidade (PPPC) descrito na Seção Ao final da instalação, o sistema solicitará permissão4 para que o agente possafuncione controlarsem eventosprompts de permissão por usuário.

    O que o instalador faz

    O script postinstall do sistemapacote automaticamente:

    • Instala o app em /Applications/CtrlStationAgent.app.
    • Grava o arquivo de configuração (necessárioURL 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 bloqueiousuário logado no console naquele momento. Os demais usuários recebem o agente automaticamente no próximo login.

    Não é necessário reiniciar.

    4. Permissões (importante para implantação silenciosa)

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

    PermissãoPor 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".
    AcessibilidadeMecanismo 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"). VocêO deveusuário precisa clicar em "OK"OK / ativar a opção em Ajustes do Sistema → Privacidade e Segurança.

  • CriePara o Arquivo de Configuraçimplantação em frota, pré-aprove essas permissões com um perfil PPPC (PassoPrivacy Obrigatório)Preferences Policy Control) via MDM, Opara agenteque nãos usuários nunca vejam prompts e a aplicação funcionaráda sempolítica asnunca informaçõesseja do servidor. Você precisa criar este arquivo manualmente:bloqueada:

    • Caminho ExatoIdentificador:: ~/.config/CtrlStationAgent/config.jsoncom.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"

    • (O instalador abriráServiços a pastapermitir:

      • ~/.config/CtrlStationAgentSystemPolicyAllFiles para você. Se— não,o crie-aé manualmente).

        necessário.
      • Apple

        Conteúdo do ArquivoEvents (use— o template abaixo, substituindopermitir, com seusdestino dados

        com.apple.systemevents.

      • Acessibilidade

        — 
        {
    "apiURL": "https://[empresa].ctrlstation.com/api",
    "accessToken": "[disponivel em configurações - licença]"
}
        JSON
        permitir.

    ApósEm criaralgumas 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á.

    5. Verificar se está em execução

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

    config.json,# O processo está ativo?
pgrep -lf CtrlStationAgent

# Status do LaunchAgent (procure por "state = running" e o serviço, que já está rodando, o detectará e começará a funcionar normalmente.
    

    Desinstalação
    

    Para remover o agente, basta apagarcaminho do menuprograma)
launchctl print "Apps"gui/$(id ou-u)/com.lab3dvlp.CtrlStationAgent" apagar| ogrep diretório-E /Applications/CtrlStationAgent.app
    "state|program"

    Funcionamento e Logs

    Como Funciona

    • O agente iniciaestá juntorodando comse state = running e um caminho de programa /Applications/CtrlStationAgent.app/Contents/MacOS/CtrlStationAgent.

      Confirme se a suaconfiguração sessãofoi aplicada corretamente (admin):

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

      6. Verificar os logs

      O agente registra através do sistema de usuário.

      logs
      • unificado
    • do

      ElemacOS permanece ativo em segundo plano, consumindo (não mínimo de recursos.

    • Toda a comunicação com a API é registrada noshá arquivos de log paraseparados). fins de depuração.

    Verificando os Logs

    Para verificar os logs, utilizeUse o comando:

    Console.app

    Daou últimao hora: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.

    7. Solução de problemas

    SintomaVerificação
    Agente não está em execuçãopgrep -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 encerraConfiguraçã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 backendAcessibilidade 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 nadaPermissão de Apple Events (Automação) não concedida. Ver Seção 4. Verifique as categorias action/session.
    A tela não bloqueiaRaro — verifique a categoria session; o mecanismo alternativo por tecla requer Acessibilidade (Seção 4).
    Mensagens do servidor não aparecemCada 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á.

    8. 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.

    9. 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.

    10. Referência

    ItemValor
    Bundle do app/Applications/CtrlStationAgent.app
    Identificador do bundle / label do LaunchAgentcom.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 backendhttps://picpay.ctrlstation.com/api (definida no config.json)
    Subsistema de logcom.lab3dvlp.CtrlStationAgent
    Time (team) do Developer IDS9DE935KXJ (LAB3 Desenvolvimento de Software Ltda ME)
    Intervalo do heartbeat30 segundos
    Início/reinício automáticoLaunchAgent RunAtLoad + KeepAlive
Voltar ao topo