Raphaël Hertzog: Como escolher seu agente SSH com Wayland e systemd

Raphaël Hertzog: Como escolher seu agente SSH com Wayland e systemd aborda um problema prático e atual: a integração entre agentes SSH, Wayland e o systemd –user. Se você migrou do X11 para o Wayland, já percebeu que scripts de sessão tradicionais não executam mais as mesmas rotinas, e isso afeta diretamente a descoberta do socket do agente SSH.

Neste artigo você aprenderá – passo a passo – como identificar qual agente ssh está definindo a variável SSH_AUTH_SOCK no seu ambiente, como garantir comportamento previsível usando systemd, e quando optar por gpg-agent, ssh-agent ou gcr-ssh-agent. Adote uma mentalidade de ação: ao final você terá instruções claras para aplicar no seu sistema.

Vantagens de entender a integração entre Wayland, agentes SSH e systemd

Compreender essa integração traz vantagens práticas para administradores e usuários avançados. Wayland delega a inicialização de sessão gráfica ao gerenciador de sessão que normalmente é controlado pelo systemd em modo usuário. Isso significa que os mecanismos antigos baseados em /etc/X11/Xsession.d não são acionados – e a variável SSH_AUTH_SOCK fica sem configuração centralizada.

• – Previsibilidade: saber qual agente SSH definir para toda a sessão evita conflitos entre agentes concorrentes.
• – Segurança: escolher um agente apropriado (por exemplo, gpg-agent com subchaves GPG) reduz riscos operacionais e centraliza o gerenciamento de chaves.
• – Simplicidade de suporte: um único agente ativo facilita scripts, integração com IDEs e autenticação remota.

Como funciona hoje – o mecanismo usado pelos agentes SSH com systemd

Atualmente, os agentes SSH empacotados adotam uma solução comum: suas unidades .socket para systemd utilizam ExecStartPost para executar um comando que define a variável de ambiente do systemd: systemctl –user set-environment SSH_AUTH_SOCK=valor. Assim, o daemon systemd passa a exportar SSH_AUTH_SOCK para as unidades iniciadas posteriormente.

Fluxo padrão

• – O gerenciador de sessão inicia e ativa sockets antes da maioria das aplicações – por isso .socket é um bom ponto de ação.
• – A unidade de socket define SSH_AUTH_SOCK via systemctl –user set-environment no ExecStartPost.
• – A última unidade a executar esse comando “vence”, pois sobrescreve o valor no ambiente do systemd.

Exemplo prático

Se você tem ssh-agent.socket, gpg-agent.socket e gcr-ssh-agent.socket presentes, cada uma pode ter ExecStartPost que define SSH_AUTH_SOCK. Quem executar por último determina qual socket as aplicações irão usar. Isso causa comportamento indesejado quando múltiplos agentes estão instalados.

Processo passo a passo – como escolher e forçar um agente SSH

Abaixo está um procedimento prático para garantir um único agente por sessão, aplicável a usuários em sistemas com Wayland e systemd –user.

• – Passo 1: Identifique sockets habilitados e ativos

  Execute systemctl –user list-unit-files | grep ‘-agent.socket’ e systemctl –user status nome-da-unidade.socket para ver o estado.

• – Passo 2: Escolha o agente preferido

  Se você usa subchaves GPG e deseja integração, prefira gpg-agent e habilite enable-ssh-support em ~/.gnupg/gpg-agent.conf.

• – Passo 3: Masque agentes indesejados

  Execute systemctl –user mask ssh-agent.socket gcr-ssh-agent.socket para impedir que esses sockets sejam ativados automaticamente.

• – Passo 4: Aplicar globalmente (opcional)

  Para todos os usuários do sistema, use sudo systemctl –global mask ssh-agent.socket gcr-ssh-agent.socket.

• – Passo 5: Reinicie a sessão de usuário

  Efetue logout/login ou reinicie o daemon de sessão para garantir que o systemd –user adote as novas definições de ambiente.

Nota técnica: desabilitar com systemctl –user disable pode não ser suficiente porque unidades socket podem ser ativadas por demanda. O masking cria um link simbólico para /dev/null e impede qualquer ativação subsequente, tornando a solução robusta.

Leia também: Emmanuel Kasper: Solucionando o inesperado: tela preta em Quake devido a botão do mouse oculto

Melhores práticas ao escolher seu agente SSH

Adotar uma abordagem consistente evita problemas futuros. Abaixo estão recomendações práticas e exemplos de configuração.

• – Escolha com base no seu fluxo de trabalho

  – Se suas chaves SSH são subchaves GPG, use gpg-agent com enable-ssh-support.

• – Torne a escolha explícita

  – Masque os sockets dos agentes que não serão usados: systemctl –user mask nome.socket.

• – Valide o ambiente

  – Após login, cheque systemctl –user show-environment e echo $SSH_AUTH_SOCK em um terminal para confirmar.

• – Documente a configuração

  – Registre quais unidades você mascarou e por quê, para facilitar manutenção e auditoria.

• – Automatize em máquinas gerenciadas

  – Para ambientes corporativos, aplique masking global com sudo systemctl –global mask e automatize via ferramenta de gerenciamento de configuração.

Dicas avançadas

• – Se precisar alterar prioridade sem masking, considere sobreposições do systemd – mas isso é frágil e menos recomendável.
• – Quando usar gpg-agent, lembre-se de atualizar ~/.gnupg/gpg-agent.conf com enable-ssh-support e reiniciar o serviço de usuário.

Erros comuns a evitar ao configurar agentes SSH com Wayland e systemd

Conhecer os enganos mais frequentes evita perda de tempo e problemas de segurança.

• – Confiar apenas em ~/.bashrc para definir SSH_AUTH_SOCK

  – Isso funciona apenas para shells interativos. Aplicativos iniciados pelo gerenciador de sessão não verão essa variável.

• – Pensar que systemctl –user disable é suficiente

  – disable pode não impedir ativação por demanda. Use mask para bloquear completamente a unidade.

• – Ter várias unidades tentando definir SSH_AUTH_SOCK sem coordenação

  – Resultado: o agente usado será o que rodou por último. Evite conflito escolhendo e mascarando os outros.

• – Ignorar o escopo user vs global

  – Se pretende aplicar a todos os usuários, use sudo systemctl –global mask. Caso contrário, o masking apenas afeta seu usuário.

• – Não verificar After/Before nas unidades

  – Alguns pacotes tentam forçar ordem com After. Mas a solução mais robusta é masking quando necessário.

FAQ – Perguntas frequentes

1. Qual a diferença entre desabilitar e mascarar uma unidade socket?

Desabilitar (systemctl –user disable) remove links que habilitam uma unidade por padrão, mas a unidade ainda pode ser ativada por demanda. Mascarar (systemctl –user mask) cria um link para /dev/null, impedindo qualquer ativação da unidade. Para garantir que um agente SSH não seja iniciado, sempre prefira mask.

2. Por que meu SSH_AUTH_SOCK não é configurado automaticamente no Wayland?

Com Wayland, os scripts de sessão do X11 como /etc/X11/Xsession.d não são executados. O correto agora é que unidades .socket do systemd definam SSH_AUTH_SOCK via systemctl –user set-environment. Se múltiplos agentes fazem isso, o valor pode ser sobrescrito. Solução: escolher um agente e mascarar os demais.

3. Devo usar gpg-agent ou ssh-agent?

A escolha depende do seu uso. Se suas chaves SSH são subchaves GPG – ou você já gerencia chaves GPG extensivamente – gpg-agent com enable-ssh-support é conveniente. Caso prefira isolamento entre GPG e SSH, mantenha ssh-agent. O importante é ter um único agente ativo por sessão.

4. Como verifico qual agente está definindo SSH_AUTH_SOCK?

Verifique o ambiente do systemd com systemctl –user show-environment; o SSH_AUTH_SOCK listado é o valor atual. Além disso, inspecione as unidades .socket: systemctl –user status gpg-agent.socket ssh-agent.socket gcr-ssh-agent.socket para ver atividades recentes e ExecStartPost se presente.

5. Posso aplicar essa configuração para todos os usuários da máquina?

Sim. Use sudo systemctl –global mask nome-da-unidade.socket. Isso cria o masking a nível global, afetando todos os logins no sistema. Para reversão, use sudo systemctl –global unmask nome-da-unidade.socket e, se necessário, reabilite com enable.

6. O que fazer se um aplicativo ainda não encontra o agente após masking?

Confirme que o agente desejado está ativo e que SSH_AUTH_SOCK está definido no ambiente do systemd. Reinicie a sessão de usuário. Verifique também se a aplicação é iniciada por outro processo que não herda o ambiente do systemd –user. Se necessário, ajuste arquivos de unidade do systemd para que dependam do socket correto.

Conclusão

Em resumo, Raphaël Hertzog: Como escolher seu agente SSH com Wayland e systemd enfatiza que a migração para Wayland traz a necessidade de gerenciar agentes SSH via systemd –user. Mascarar unidades socket dos agentes indesejados é a forma mais confiável de garantir um único agente por sessão, tornando SSH_AUTH_SOCK previsível e reduzindo conflitos.

Principais ações recomendadas:
– Escolha o agente que corresponde ao seu fluxo de trabalho (gpg-agent se usar subchaves GPG).
– Masque os sockets dos agentes concorrentes com systemctl –user mask.
– Valide o ambiente com systemctl –user show-environment e verifique SSH_AUTH_SOCK.

Próximo passo: aplique as instruções no seu sistema agora – verifique unidades .socket, masque o que for necessário e reinicie sua sessão. Se gerencia máquinas para outros usuários, considere aplicar o masking global. Se precisar, documente a configuração para facilitar suporte futuro.

Fonte Original

Este artigo foi baseado em informações de: https://raphaelhertzog.com/2025/11/10/how-to-choose-your-ssh-agent-with-wayland-and-systemd/