Solução de problemas do Session Manager - AWS Systems Manager
O processo do documento falhou inesperadamente: o operador do documento excedeu o tempo limiteO Session Manager não consegue se conectar pelo console do Amazon EC2Sem permissão para iniciar uma sessãoSSM Agent não está onlineSem permissão para alterar as preferências da sessãoNó gerenciado não disponível ou não está configurado para o Session ManagerO plugin Session Manager não foi encontradoO plug-in Session Manager não é adicionado automaticamente ao caminho de linha de comando (Windows)O plugin Session Manager não respondeTargetNotConnectedTela em branco exibida após iniciar uma sessãoO nó gerenciado deixa de responder durante sessões de execução longaOcorreu um erro (InvalidDocument) ao chamar a operação StartSession

Solução de problemas do Session Manager

Use as informações a seguir para ajudar a solucionar problemas com o Session Manager do AWS Systems Manager.

O processo do documento falhou inesperadamente: o operador do documento excedeu o tempo limite

Problema: ao iniciar uma sessão em um host Linux, o Systems Manager retorna o seguinte erro:

document process failed unexpectedly: document worker timed out, 
check [ssm-document-worker]/[ssm-session-worker] log for crash reason

Se você configurou o log do SSM Agent conforme descrito em Visualizar logs do SSM Agent, você poderá visualizar mais detalhes no registro de depuração. Para esse problema, o Session Manager mostra a seguinte entrada de log:

failed to create channel: too many open files

Esse erro normalmente indica que há muitos processos de operador do Session Manager em execução e que o sistema operacional subjacente atingiu um limite. Há duas opções para resolver o problema.

Solução A: aumentar o limite de notificação de arquivos do sistema operacional

É possível aumentar o limite executando o comando a seguir em um host Linux separado. Esse comando usa o Run Command do Systems Manager. O valor especificado aumenta max_user_instances para 8192. Esse valor é consideravelmente maior do que o valor padrão de 128, mas não sobrecarregará os recursos do host:

aws ssm send-command --document-name AWS-RunShellScript \
--instance-id i-02573cafcfEXAMPLE  --parameters \
"commands=sudo sysctl fs.inotify.max_user_instances=8192"

Solução B: diminua as notificações de arquivo usadas pelo Session Manager no host de destino

Execute o comando a seguir em um host Linux separado para listar as sessões em execução no host de destino:

aws ssm describe-sessions --state Active --filters key=Target,value=i-02573cafcfEXAMPLE

Revise a saída do comando para identificar as sessões que não são mais necessárias. É possível encerrar essas sessões executando o seguinte comando em um host Linux separado:

aws ssm terminate-session —session-id session ID

Opcionalmente, quando não houver mais sessões em execução no servidor remoto, você poderá liberar recursos adicionais executando o comando a seguir em um host Linux separado. Este comando encerra todos os processos do Session Manager em execução no host remoto e, consequentemente, todas as sessões no host remoto. Antes de executá-lo, verifique se não há sessões em andamento que você gostaria de manter:

aws ssm send-command --document-name AWS-RunShellScript \
            --instance-id i-02573cafcfEXAMPLE --parameters \
'{"commands":["sudo kill $(ps aux | grep ssm-session-worker | grep -v grep | awk '"'"'{print $2}'"'"')"]}'

O Session Manager não consegue se conectar pelo console do Amazon EC2

Problema: depois de criar uma nova instância, a guia Gerenciador de Sessões no console do Amazon Elastic Compute Cloud (Amazon EC2) não oferece a opção de conexão.

Solução A: crie um perfil de instância: se você ainda não tiver feito isso (conforme instruído pelas informações na guia Gerenciador de sessões no console do EC2), crie um perfil de instância do AWS Identity and Access Management (IAM) usando a Quick Setup. A Quick Setup é um recurso do AWS Systems Manager.

O Session Manager requer um perfil de instância do IAM para se conectar à instância. É possível criar um perfil de instância e atribuí-lo à instância criando uma configuração de gerenciamento de host com a Quick Setup. Uma configuração de gerenciamento de host cria um perfil de instância com as permissões necessárias e o atribui à instância. Uma configuração de gerenciamento de host também habilita outros recursos do Systems Manager e cria perfis do IAM para executar esses recursos. Não há cobrança pelo uso da Quick Setup ou pelos recursos habilitados pela configuração de gerenciamento do host. Abra a Quick Setup e crie uma configuração de gerenciamento de host.

Importante

Depois de criar a configuração de gerenciamento do host, o Amazon EC2 pode levar vários minutos para registrar a alteração e atualizar a guia Gerenciador de Sessões. Se a guia não exibir o botão Conectar após dois ou três minutos, reinicialize a instância. Após a reinicialização, caso ainda não veja a opção de se conectar, abra a Configuração Rápida e verifique se você tem apenas uma configuração de gerenciamento de host. Se houver duas, exclua a configuração mais antiga e espere alguns minutos.

Se mesmo assim você não conseguir se conectar depois de criar uma configuração de gerenciamento de host ou se receber um erro, incluindo um erro sobre o SSM Agent, consulte uma destas soluções:

Solução B: não há erro, mas ainda não consigo conectar

Se você criou a configuração de gerenciamento de host, esperou alguns minutos antes de tentar se conectar e ainda não consegue se conectar, talvez seja necessário aplicar a configuração de gerenciamento de host à instância manualmente. Use o procedimento a seguir para atualizar uma configuração de gerenciamento de host da Quick Setup e aplicar alterações em uma instância.

Para atualizar uma configuração de gerenciamento de host usando a Quick Setup

  1. Abra o console do AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.

  2. No painel de navegação, escolha Quick Setup.

  3. Na lista Configurações, escolha a configuração do Gerenciamento de host que você criou.

  4. Escolha Ações e depois Editar configuração.

  5. Na parte inferior da seção Targets, em Choose how you want to target instances, escolha Manual.

  6. Na seção Instâncias, escolha a instância que você criou.

  7. Selecione Atualizar.

Aguarde alguns minutos para que o EC2 atualize a guia Gerenciador de Sessões. Se você ainda não conseguir se conectar ou receber um erro, revise as soluções restantes para o problema.

Solução C: erro de SSM Agent ausente

Se você não conseguiu criar uma configuração de gerenciamento de host usando a Quick Setup, ou se recebeu um erro sobre o SSM Agent não estar instalado, talvez seja necessário instalar o SSM Agent manualmente em sua instância. O SSM Agent é um software da Amazon que possibilita que o Systems Manager se conecte à sua instância usando o Session Manager. O SSM Agent é instalado por padrão na maioria das imagens de máquina da Amazon (AMI) (AMIs). Se sua instância foi criada com base em uma AMI não padrão ou em uma AMI mais antiga, talvez seja necessário instalar o agente manualmente. Para o procedimento de instalação do SSM Agent, consulte o tópico a seguir que corresponde ao sistema operacional da instância.

Para problemas com o SSM Agent, consulte Solução de problemas de SSM Agent.

Sem permissão para iniciar uma sessão

Problema: você tenta iniciar uma sessão, mas o sistema informa que você não tem as permissões necessárias.

SSM Agent não está online

Problema: Você vê uma mensagem na guia de instância do Amazon EC2 Session Manager que diz: SSM Agent não está online. O SSM Agent ñão consegue se conectar a um endpoint do Systems Manager para se registrar no serviço.

Solução: SSM Agent é um software da Amazon executado em instâncias do Amazon EC2 para que o Session Manager possa se conectar a elas. Se você vir esse erro, SSM Agent não consegue estabelecer uma conexão com o endpoint do Systems Manager. A origem do problema pode ser restrições de firewall, problemas de roteamento ou falta de conectividade com a Internet. Para solucionar esse problema, investigue os problemas de conectividade de rede.

Sem permissão para alterar as preferências da sessão

Problema: você tenta atualizar as preferências de sessões globais para sua organização, mas o sistema informa que você não tem as permissões necessárias.

Nó gerenciado não disponível ou não está configurado para o Session Manager

Problema 1: você quer iniciar uma sessão na página do console Start a session (Iniciar uma sessão), mas um nó gerenciado não está na lista.

  • Solução A: o nó gerenciado ao qual você quer se conectar pode não ter sido configurado para o AWS Systems Manager. Para ter mais informações, consulte Configurar o AWS Systems Manager.

    nota

    Se o SSM Agent do AWS Systems Manager já estiver em execução em um nó gerenciado ao associar o perfil da instância do IAM, talvez seja necessário reiniciar o agente antes que a instância seja listada na página do console Start a session (Iniciar uma sessão).

  • Solução B: a configuração de proxy que você aplicou ao SSM Agent em seu nó gerenciado pode estar incorreta. Se a configuração do proxy estiver incorreta, o nó gerenciado não conseguirá alcançar os endpoints de serviço necessários ou o poderá ser relatado como um sistema operacional diferente para o Systems Manager. Para ter mais informações, consulte Configurar o SSM Agent para usar um proxy em nós do Linux e Configurar o SSM Agent para usar um proxy para instâncias do Windows Server.

Problema 2: um nó gerenciado ao qual você quer se conectar está na lista da página do console Start a session (Iniciar uma sessão), mas a página informa que "A instância que você selecionou não está configurada para usar o Session Manager".

O plugin Session Manager não foi encontrado

Para usar a AWS CLI para executar comandos de sessão, o plugin do Session Manager também deve ser instalado em sua máquina local. Para ter mais informações, consulte Instalar o plug-in do Session Manager para a AWS CLI.

O plug-in Session Manager não é adicionado automaticamente ao caminho de linha de comando (Windows)

Quando você instalar o plug-in do Session Manager no Windows, o session-manager-plugin executável deverá ser adicionado automaticamente à variável de ambiente PATH do sistema operacional. Se o comando falhou depois que você o executou para verificar se o plugin do Session Manager foi instalado corretamente (aws ssm start-session --target instance-id), pode ser necessário configurá-lo manualmente usando o procedimento a seguir.

Para modificar sua variável PATH (Windows)

  1. Pressione a tecla Windows e digite environment variables.

  2. Escolha Edit environment variables for your account (Editar variáveis de ambiente para sua conta).

  3. Selecione PATH e, em seguida, Editar.

  4. Adicione caminhos ao campo Variable value (Valor da variável) separados por ponto e vírgula, conforme este exemplo: C:\existing\path;C:\new\path

    C:\existing\path representa o valor já no campo. C:\new\path representa o caminho que você deseja adicionar, como nestes exemplos.

    • Máquinas 64-bit: C:\Program Files\Amazon\SessionManagerPlugin\bin\

    • Máquinas 32-bit: C:\Program Files (x86)\Amazon\SessionManagerPlugin\bin\

  5. Escolha OK duas vezes para aplicar as novas configurações.

  6. Feche todas as solicitações de comando em execução e abra novamente.

O plugin Session Manager não responde

Durante uma sessão de encaminhamento de porta, o tráfego poderá interromper o encaminhamento se você tiver um software antivírus instalado em sua máquina local. Em alguns casos, o software antivírus interfere com o plugin Session Manager causando bloqueios de processo. Para resolver esse problema, permita ou exclua o plugin do Session Manager do software antivírus. Para obter informações sobre o caminho de instalação padrão para o plugin Session Manager, consulte Instalar o plug-in do Session Manager para a AWS CLI.

TargetNotConnected

Problema: você tenta iniciar uma sessão, mas o sistema retorna a mensagem de erro "Ocorreu um erro (TargetNotConnected) ao chamar a operação StartSession: InstanceID não está conectado".

  • Solução A: esse erro é retornado quando o nó gerenciado de destino especificado para a sessão não estiver totalmente configurado para uso com o Session Manager. Para ter mais informações, consulte Configurar o Session Manager.

  • Solução B: esse erro também ocorre se você tentar iniciar uma sessão em um nó gerenciado localizado em uma Conta da AWS ou Região da AWS diferente.

Tela em branco exibida após iniciar uma sessão

Problema: você inicia uma sessão e o Session Manager exibe uma tela em branco.

  • Solução A: esse problema pode ocorrer quando o volume raiz em seu nó gerenciado estiver cheio. Devido à falta de espaço em disco, o SSM Agent do nó para de funcionar. Para resolver esse problema, use o Amazon CloudWatch para coletar métricas e logs dos sistemas operacionais. Para obter informações, consulte Coletar métricas, logs e rastreamentos com o agente do CloudWatch no Guia do usuário do Amazon CloudWatch.

  • Solução B: uma tela em branco pode ser exibida se você acessou o console usando um link que inclui um par de endpoint e região incompatíveis. Por exemplo, no URL do console a seguir, us-west-2 é o endpoint especificado, mas us-west-1 é a região da Região da AWS especificada.

    https://us-west-2.console.aws.amazon.com/systems-manager/session-manager/sessions?region=us-west-1

  • Solução C: o nó gerenciado está se conectando ao Systems Manager usando endpoints da VPC, e suas preferências do Session Manager gravam a saída da sessão em um bucket do Amazon S3 ou grupo de logs do Amazon CloudWatch Logs, mas um endpoint de gateway do s3 ou endpoint de interface do logs não existe na VPC. Um endpoint do s3 no formato com.amazonaws.region.s3 será necessário se os nós gerenciados estiverem conectados ao Systems Manager usando endpoints da VPC e suas preferências do Session Manager gravarem o resultado da sessão em um bucket do Amazon S3. Como alternativa, um endpoint do logs no formato com.amazonaws.region.logs será necessário, se os nós gerenciados estiverem se conectando ao Systems Manager usando endpoints da VPC, e as preferências do Session Manager gravarem a saída da sessão em um grupo de logs do CloudWatch Logs. Para ter mais informações, consulte Criar endpoints da VPC para o Systems Manager.

  • Solução D: o grupo de logs ou bucket do Amazon S3 que você especificou nas preferências de sessão foi excluído. Para resolver esse problema, atualize suas preferências de sessão com um grupo de logs válido ou um bucket S3.

  • Solução E: o grupo de logs ou bucket do Amazon S3 que você especificou em suas preferências de sessão não está criptografado, mas você definiu a entrada cloudWatchEncryptionEnabled ou s3EncryptionEnabled como true. Para resolver esse problema, atualize suas preferências de sessão com um grupo de logs ou bucket do Amazon S3 criptografado ou defina a entrada cloudWatchEncryptionEnabled ou s3EncryptionEnabled como false. Esse cenário só é aplicável aos clientes que criam preferências de sessão usando ferramentas da linha de comando.

O nó gerenciado deixa de responder durante sessões de execução longa

Problema: seu nó gerenciado deixa de responder ou falha durante uma sessão de execução longa.

Solução: diminuir a duração da retenção de logs do SSM Agent para Session Manager.

Para diminuir a duração da retenção de logs do SSM Agent para sessões

  1. Localize amazon-ssm-agent.json.template no diretório /etc/amazon/ssm/ no Linux, ou em C:\Program Files\Amazon\SSM no Windows.

  2. Copie o conteúdo do amazon-ssm-agent.json.template em um novo arquivo no mesmo diretório chamado amazon-ssm-agent.json.

  3. Reduza o valor padrão do valor SessionLogsRetentionDurationHours na propriedade SSM e salve o arquivo.

  4. Reinicie o SSM Agent.

Ocorreu um erro (InvalidDocument) ao chamar a operação StartSession

Problema: você recebe o seguinte erro ao iniciar uma sessão usando o AWS CLI.

An error occurred (InvalidDocument) when calling the StartSession operation: Document type: 'Command' is not supported. Only type: 'Session' is supported for Session Manager.

Solução: o documento SSM que você especificou para o --document-name parâmetro não é um documento de sessão. Use o procedimento a seguir para visualizar uma lista de documentos da sessão no AWS Management Console.

Para visualizar uma lista de documentos da sessão

  1. Abra o console do AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.

  2. No painel de navegação, escolha Documents.

  3. Na lista Categorias, escolha Documentos da sessão.