Conheça os detalhes técnicos sobre o SSM Agent

Use as informações contidas neste tópico para implementar o AWS Systems ManagerAgente (SSM Agent) e entender como ele funciona.

Tópicos

• Comportamento da credencial do SSM Agent versão 3.2.x.x
• Precedência de credenciais do SSM Agent
• Sobre a conta local ssm-user
• SSM Agent e Instance Metadata Service (IMDS)
• Manter o SSM Agent atualizado
• Garantir que o diretório de instalação do SSM Agent não seja modificado, movido ou excluído
• Atualizações contínuas do SSM Agent nas Regiões da AWS
• Comunicações do SSM Agent com os buckets do S3 gerenciados pela AWS
• Encontrar AMIs com o SSM Agent pré-instalado
• Trabalhar com o SSM Agent em instâncias do EC2 para Linux
• Trabalhar com o SSM Agent em instâncias do EC2 para macOS
• Trabalhar com o SSM Agent em instâncias do EC2 para Windows Server
• Verificar o status do SSM Agent e iniciar o agente
• Verificar o número de versão do SSM Agent
• Visualizar logs do SSM Agent
• Restringir o acesso aos comandos em nível raiz por meio do SSM Agent
• Automatizar atualizações do SSM Agent
• Assinar as notificações do SSM Agent

Comportamento da credencial do SSM Agent versão 3.2.x.x

O SSM Agent armazena um conjunto de credenciais temporárias em /var/lib/amazon/ssm/credentials (para Linux e macOS) ou em %PROGRAMFILES%\Amazon\SSM\credentials (para Windows Server) quando uma instância é integrada usando a configuração de gerenciamento do host padrão na Quick Setup. As credenciais temporárias têm as permissões que você especifica para o perfil do IAM escolhido para a configuração de gerenciamento do host padrão. No Linux, só a conta raiz pode acessar essas credenciais. No Windows Server, somente a conta SYSTEM e os administradores locais podem acessar essas credenciais.

Precedência de credenciais do SSM Agent

Este tópico descreve informações importantes sobre como o SSM Agent recebe permissão para executar ações em seus recursos.

nota

A compatibilidade com dispositivos de borda é um pouco diferente. Você deve configurar seus dispositivos de borda para usar o software principal do AWS IoT Greengrass, configurar um perfil de serviço do AWS Identity and Access Management (IAM) e implantar o SSM Agent para seus dispositivos usando o AWS IoT Greengrass. Para ter mais informações, consulte Gerenciar dispositivos de borda com o Systems Manager.

Quando o SSM Agent está instalado em uma máquina, ele requer permissões para se comunicar com o serviço Systems Manager. Nas instâncias do Amazon Elastic Compute Cloud (Amazon EC2), essas permissões são fornecidas em um perfil de instância que está anexado à instância. Em uma máquina que não é do EC2, o SSM Agent normalmente obtém as permissões necessárias do arquivo de credenciais compartilhadas, localizado em /root/.aws/credentials (Linux e macOS) ou em %USERPROFILE%\.aws\credentials (Windows Server). As permissões necessárias são adicionadas a este arquivo durante o processo de ativação híbrida.

Porém, em casos raros, uma máquina pode acabar com permissões adicionadas a mais de um dos locais em que o SSM Agent verifica se há permissões para executar suas tarefas.

Por exemplo, digamos que você tenha configurado uma instância do EC2 para ser gerenciada pelo Systems Manager. Essa configuração inclui anexar um perfil de instância. Mas então você também decide usar essa instância para tarefas de desenvolvedor ou usuário final e instalar o AWS Command Line Interface (AWS CLI) nele. Esta instalação resulta em permissões adicionais sendo adicionadas a um arquivo de credenciais na instância.

Quando você executa um comando do Systems Manager na instância, o SSM Agent pode tentar usar credenciais diferentes daquelas que você espera que ele use, como de um arquivo de credenciais em vez de um perfil de instância. Isto é porque o SSM Agent procura credenciais na ordem prescrita para a Cadeia de fornecedores de credenciais padrão.

nota

No Linux e no macOS, o SSM Agent é executado como usuário raiz. Portanto, as variáveis ​​de ambiente e o arquivo de credenciais que o SSM Agent procura neste processo são somente do usuário raiz (/root/.aws/credentials). O SSM Agent não verifica as variáveis ​​de ambiente ou o arquivo de credenciais para quaisquer outros usuários na instância durante a pesquisa de credenciais.

A cadeia de fornecedores procura e usa credenciais nesta ordem:

1. Variáveis de ambiente, se configuradas (AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY).

2. Arquivo de credenciais compartilhado ($HOME/.aws/credentials para Linux e macOS ou %USERPROFILE%\.aws\credentials para Windows Server) com permissões fornecidas por, por exemplo, uma ativação híbrida ou uma instalação da AWS CLI.

3. Uma função do AWS Identity and Access Management (IAM) para tarefas se houver uma aplicação que usa uma definição de tarefa do Amazon Elastic Container Service (Amazon ECS) ou operação da API RunTask.

4. Um perfil de instância anexado a uma instância do Amazon EC2.

5. O perfil do IAM escolhido para a configuração de gerenciamento do host padrão.

Para obter informações mais detalhadas, consulte os seguintes tópicos relacionados:

• Perfis de instância para instâncias do EC2: Configurar permissões de instância obrigatórias para o Systems Manager

• Ativações híbridas: crie uma ativação híbrida para registrar nós no Systems Manager

• Credenciais da AWS CLI: Configuração e definições do arquivo de credenciais no Guia do usuário do AWS Command Line Interface

• Cadeia de provedores de credenciais padrão – Especificação de credenciais no Manual do desenvolvedor do AWS SDK for Go

  nota

  Este tópico no Guia do desenvolvedor do AWS SDK for Go descreve a cadeia de provedores padrão em termos do SDK para Go. No entanto, os mesmos princípios se aplicam à avaliação de credenciais para o SSM Agent.

Sobre a conta local ssm-user

Começando na versão 2.3.50.0 do SSM Agent, o agente cria uma conta de usuário local chamada ssm-user e a adiciona ao diretório /etc/sudoers.d (Linux e macOS) ou ao grupo de Administradores (Windows Server). Em versões do agente anteriores a 2.3.612.0, a conta é criada na primeira vez que o SSM Agent é iniciado ou reiniciado após a instalação. Na versão 2.3.612.0 e posteriores, a conta ssm-user é criada na primeira vez que uma sessão é iniciada em uma instância. Esse ssm-user é o usuário padrão do sistema operacional quando uma sessão do é iniciada no Session Manager, um recurso do AWS Systems Manager. É possível alterar as permissões movendo ssm-user para um grupo com menos privilégios ou alterando o arquivo sudoers. A conta ssm-user não é removida do sistema quando o SSM Agent é desinstalado.

No Windows Server, o SSM Agent lida com a configuração de uma nova senha para a conta ssm-user quando cada sessão começa. Nenhuma senha é definida para ssm-user em instâncias gerenciadas do Linux.

Começando com o SSM Agent versão 2.3.612.0, a conta ssm-user não é criada automaticamente em máquinas Windows Server usadas como controladores de domínio. Para usar o Session Manager em um controlador de domínio do Windows Server, crie a conta ssm-user manualmente, caso ela ainda não esteja presente, e atribua permissões de Administrador do Domínio ao usuário.

Importante

Para que a conta ssm-user seja criada, o perfil de instância anexado à instância deve fornecer as permissões necessárias. Para obter informações, consulte Etapa 2: verificar ou adicionar permissões de instância para o Session Manager.

SSM Agent e Instance Metadata Service (IMDS)

O agente do Systems Manager depende dos metadados da instância do EC2 para funcionar corretamente. O Systems Manager pode acessar metadados de instância usando a versão 1 ou a versão 2 do Instance Metadata Service (IMDSv1 e IMDSv2). Sua instância deve poder acessar o endereço IPv4 do serviço de metadados da instância: 169.254.169.254. Para obter mais informações, consulte Metadados da instância e dados do usuário no Manual do usuário do Amazon EC2.

Manter o SSM Agent atualizado

Uma versão atualizada do SSM Agent é lançada sempre que novos recursos são adicionados ao Systems Manager ou sempre que atualizações forem feitas nos recursos existentes. Deixar de usar a versão mais recente do agente pode impedir que seu nó gerenciado use vários recursos do Systems Manager. Por isso, recomendamos automatizar o processo de manter o SSM Agent atualizado em suas máquinas. Para ter mais informações, consulte Automatizar atualizações do SSM Agent. Inscreva-se na página Notas de versão do SSM Agent no GitHub para receber notificações sobre atualizações do SSM Agent.

nota

Uma versão atualizada do SSM Agent é lançada sempre que novos recursos são adicionados ao Systems Manager ou sempre que atualizações forem feitas nos recursos existentes. Deixar de usar a versão mais recente do agente pode impedir que seu nó gerenciado use vários recursos do Systems Manager. Por isso, recomendamos automatizar o processo de manter o SSM Agent atualizado em suas máquinas. Para ter mais informações, consulte Automatizar atualizações do SSM Agent. Inscreva-se na página Notas de versão do SSM Agent no GitHub para receber notificações sobre atualizações do SSM Agent.

As Amazon Machine Images (AMIs), que incluem o SSM Agent por padrão, podem demorar até duas semanas para serem atualizadas com a versão mais recente do SSM Agent. Recomendamos que você configure atualizações automatizadas ainda mais frequentes para o SSM Agent.

Garantir que o diretório de instalação do SSM Agent não seja modificado, movido ou excluído

O SSM Agent está instalado em /var/lib/amazon/ssm/ (Linux e macOS) e em %PROGRAMFILES%\Amazon\SSM\ (Windows Server). Esses diretórios de instalação contêm arquivos e pastas essenciais usados pelo SSM Agent, como um arquivo de credenciais, recursos para comunicação entre processos (IPC) e pastas de orquestração. Nada no diretório de instalação deve ser modificado, movido ou excluído. Caso contrário, o SSM Agent poderá parar de funcionar corretamente.

Atualizações contínuas do SSM Agent nas Regiões da AWS

Quando uma atualização do SSM Agent estiver disponível em seu repositório do GitHub, até duas semanas poderão ser necessárias para que a versão atualizada seja lançada para todos as Regiões da AWS em momentos diferentes. Por esse motivo, você pode receber o erro “Não compatível com a plataforma atual” ou “atualizando o amazon-ssm-agent para uma versão mais antiga, ative a permissão de downgrade para continuar” ao tentar implantar uma nova versão do SSM Agent em uma região.

Para determinar a versão do SSM Agent disponível para você, você pode executar um comando curl.

Para visualizar a versão do agente disponível no bucket de download global, execute o comando a seguir.

curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/VERSION

Para visualizar a versão do agente disponível em uma região específica, execute o comando a seguir, substituindo region pela região em que você está trabalhando, como us-east-2 para a região Leste dos EUA (Ohio).

curl https://s3.region.amazonaws.com/amazon-ssm-region/latest/VERSION

Também é possível abrir o arquivo VERSION diretamente no seu navegador sem um comando curl.

Comunicações do SSM Agent com os buckets do S3 gerenciados pela AWS

Durante a execução de várias operações do Systems Manager, o AWS Systems Manager Agent (SSM Agent) acessa uma série de buckets do Amazon Simple Storage Service (Amazon S3). Esses buckets do S3 são acessíveis publicamente e, por padrão, SSM Agent se conecta a eles usando chamadas HTTP.

No entanto, se você estiver usando um endpoint da nuvem privada virtual (VPC) nas operações do Systems Manager, deverá fornecer permissão explícita em um perfil de instância do Amazon Elastic Compute Cloud (Amazon EC2) para o Systems Manager ou em um perfil de serviço para máquinas que não são do EC2 em um ambiente híbrido e multinuvem. Caso contrário, seus recursos não poderão acessar esses buckets públicos.

Para conceder acesso dos nós gerenciados a esses buckets quando você estiver usando um endpoint da VPC, crie uma política de permissões personalizada do Amazon S3 e anexe-a ao perfil de instância (para instâncias do EC2) ou aos perfil de serviço (para servidores nós gerenciados que não são do EC2).

Para obter informações sobre como usar um endpoint da nuvem privada virtual (VPC) em suas operações do Systems Manager, consulte Melhorar a segurança das instâncias do EC2 usando endpoints da VPC para o Systems Manager.

nota

Essas permissões fornecem acesso somente aos buckets gerenciados da AWS exigidos pelo SSM Agent. Elas não fornecem as permissões que são necessárias para outras operações do Amazon S3. Elas também não fornecem permissão para seus próprios buckets do S3.

Para obter mais informações, consulte os tópicos a seguir.

• Configurar permissões de instância obrigatórias para o Systems Manager

• Criar o perfil de serviço do IAM obrigatório para o Systems Manager em ambientes híbridos e multinuvem

Permissões obrigatórias do bucket

A tabela a seguir descreve cada um dos S3 que o SSM Agent pode precisar acessar as operações do Systems Manager.

nota

A região representa o identificador da região para uma região da Região da AWS compatível com o AWS Systems Manager, como us-east-2 para a região Leste dos EUA (Ohio). Para ver uma lista dos valores de região com suporte, consulte a coluna Region em Systems Manager service endpoints no Referência geral da Amazon Web Services.

Permissões do Amazon S3 exigidas pelo SSM Agent

ARN do bucket do S3	Descrição
arn:aws:s3:::aws-windows-downloads-region/*	Obrigatório para alguns documentos SSM que oferecem suporte somente a sistemas operacionais Windows Server, além de alguns para suporte multiplataforma, como AWSEC2-ConfigureSTIG.
arn:aws:s3:::amazon-ssm-region/*	Obrigatório para atualizar instalações do SSM Agent. Esses buckets contêm os pacotes de instalação do SSM Agent e os manifestos de instalação referenciados pelo documento e plugin do AWS-UpdateSSMAgent. Se essas permissões não forem fornecidas, o SSM Agent fará uma chamada HTTP para fazer download da atualização.
arn:aws:s3:::amazon-ssm-packages-region/*	Necessário para usar versões do SSM Agent anteriores à 2.2.45.0 para executar o documento AWS-ConfigureAWSPackage.
arn:aws:s3:::region-birdwatcher-prod/*	Fornece acesso ao serviço de distribuição usado pela versão 2.2.45.0 e posterior do SSM Agent. Esse serviço é usado para executar o documento AWS-ConfigureAWSPackage. Esta permissão é necessária para todas as Regiões da AWS, exceto sa regiões da África (Cidade do Cabo) (af-south-1) e da Europa (Milão) (eu-south-1).
arn:aws:s3:::aws-ssm-distributor-file-region/*	Fornece acesso ao serviço de distribuição usado pela versão 2.2.45.0 e posterior do SSM Agent. Esse serviço é usado para executar o documento AWS-ConfigureAWSPackage. Esta permissão é necessária somente para as regiões da África (Cidade do Cabo) (af-south-1) e da Europa (Milão) (eu-south-1).
arn:aws:s3:::aws-ssm-document-attachments-region/*	Fornece acesso ao bucket do S3 que contém os pacotes do Distributor, um recurso do AWS Systems Manager, que são propriedade da AWS.
arn:aws:s3:::patch-baseline-snapshot-region/*	Fornece acesso ao bucket do S3 que contém snapshots de linha de base de patches. Isso será necessário se você usar qualquer um dos seguintes documentos do SSM: AWS-RunPatchBaseline AWS-RunPatchBaselineAssociation AWS-RunPatchBaselineWithHooks AWS-ApplyPatchBaseline um documentos do SSM legado) nota Somente na região Oriente Médio (Bahrein) (me-south-1), esse bucket do S3 usa uma convenção de nomenclatura diferente. Somente para esta Região da AWS, use o seguinte bucket: patch-baseline-snapshot-me-south-1-uduvl7q8 Somente na região África (Cidade do Cabo) (af-south-1), esse bucket do S3 usa uma convenção de nomenclatura diferente. Somente para esta Região da AWS, use o seguinte bucket: patch-baseline-snapshot-af-south-1-tbxdb5b9
Para nós gerenciados do Linux e do Windows Server: arn:aws:s3:::aws-ssm-region/* Em instâncias do Amazon EC2 para macOS: arn:aws:s3:::aws-patchmanager-macos-region/*	Fornece acesso ao bucket do S3 que contém os módulos necessários para usar com alguns documentos do Systems Manager (documentos SSM). Por exemplo: arn:aws:s3:::aws-ssm-us-east-2/* aws-patchmanager-macos-us-east-2/* Exceções Os nomes de um bucket do S3 em algumas Regiões da AWS usam uma convenção de nomenclatura estendida, conforme mostrado por seus ARNs. Para essas regiões, use os seguintes ARNs como alternativa: Região do Oriente Médio (Bahrein) (me-south-1): aws-patch-manager-me-south-1-a53fc9dce Região da África (Cidade do Cabo) (af-south-1): aws-patch-manager-af-south-1-bdd5f65a9 Região da Europa (Milão) (eu-south-1): aws-patch-manager-eu-south-1-c52f3f594 Região da Ásia-Pacífico (Osaka) (ap-northeast-3): aws-patch-manager-ap-northeast-3-67373598a Documentos do SSM Veja a seguir alguns documentos SSM comumente usados armazenados nesses buckets. Em arn:aws:s3:::aws-ssm-region/: AWS-RunPatchBaseline AWS-RunPatchBaselineAssociation AWS-RunPatchBaselineWithHooks AWS-InstanceRebootWithHooks AWS-ConfigureWindowsUpdate AWS-FindWindowsUpdates AWS-PatchAsgInstance AWS-PatchInstanceWithRollback AWS-UpdateSSMAgent AWS-UpdateEC2Config Em arn:aws:s3:::aws-patchmanager-macos-region/: AWS-RunPatchBaseline AWS-RunPatchBaselineAssociation AWS-RunPatchBaselineWithHooks AWS-InstanceRebootWithHooks AWS-PatchAsgInstance AWS-PatchInstanceWithRollback

Exemplo

O exemplo a seguir ilustra como fornecer acesso aos buckets do S3 necessários para as operações do Systems Manager na região Leste dos EUA (Ohio) (us-east-2). Na maioria dos casos, você precisa fornecer essas permissões explicitamente em um perfil de instância ou função de serviço somente ao usar um endpoint da VPC.

Importante

Recomendamos que você evite usar caracteres curinga (*) no lugar das regiões específicas nessa política. Por exemplo, use arn:aws:s3:::aws-ssm-us-east-2/* e não use arn:aws:s3:::aws-ssm-*/*. O uso de curingas pode fornecer acesso a buckets do S3 aos quais você não pretende conceder acesso. Se você quiser usar o perfil de instância para mais de uma região, recomendamos repetir o primeiro bloco Statement para cada região.

{
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": "s3:GetObject",
                "Resource": [
                    "arn:aws:s3:::aws-windows-downloads-us-east-2/*",
                    "arn:aws:s3:::amazon-ssm-us-east-2/*",
                    "arn:aws:s3:::amazon-ssm-packages-us-east-2/*",
                    "arn:aws:s3:::us-east-2-birdwatcher-prod/*",
                    "arn:aws:s3:::aws-ssm-document-attachments-us-east-2/*",
                    "arn:aws:s3:::patch-baseline-snapshot-us-east-2/*",
                    "arn:aws:s3:::aws-ssm-us-east-2/*",
                    "arn:aws:s3:::aws-patchmanager-macos-us-east-2/*"
                ]
            }
        ]
    }

Validar máquinas ativadas para ambiente híbrido usando uma impressão digital do hardware

Quando há máquinas que não são EC2 em um ambiente híbrido e multinuvem, o SSM Agent reúne uma série de atributos do sistema (referidos como hash de hardware) e usa esses atributos para computar uma impressão digital. A impressão digital é uma string opaca que o agente passa para determinadas APIs do Systems Manager. Essa impressão digital exclusiva associa o chamador a um nó gerenciado ativado para ambientes híbridos específico. O agente armazena a impressão digital e o hash de hardware no disco local em um local chamado Cofre.

O agente calcula o hash de hardware e a impressão digital quando a máquina é registrada para uso com o Systems Manager. Em seguida, a impressão digital é passada de volta para o serviço Systems Manager quando o agente envia um comando RegisterManagedInstance.

Posteriormente, ao enviar um RequestManagedInstanceRoleToken, o agente verifica a impressão digital e o hash de hardware no Cofre para se certificar de que os atributos de máquina atuais correspondam ao hash de hardware armazenado. Se os atributos atuais da máquina corresponderem ao hash de hardware armazenado no Vault, o agente passa a impressão digital do Vault para RegisterManagedInstance, resultando em uma chamada bem-sucedida.

Se os atributos de máquina atuais não corresponderem ao hash de hardware armazenado, o SSM Agent calcula uma nova impressão digital, armazena o novo hash de hardware e a impressão digital no Vault e passa a nova impressão digital para RequestManagedInstanceRoleToken. Isso faz RequestManagedInstanceRoleToken falhar e o agente não poderá obter um token de função para se conectar ao serviço do Systems Manager.

Esta falha ocorre intencionalmente e é usada como uma etapa de verificação para impedir que vários nós gerenciados se comuniquem com o serviço do Systems Manager como o mesmo nó gerenciado.

Ao comparar os atributos da máquina atual com o hash de hardware armazenado no Cofre, o agente usa a seguinte lógica para determinar se os hashes antigos e novos correspondem:

• Se o SID (ID do sistema/máquina) for diferente, não haverá nenhuma correspondência.

• Caso contrário, se o endereço IP for o mesmo, então correspondem.

• Caso contrário, a porcentagem de atributos de máquina correspondentes é calculada e comparada com o limite de similaridade configurado pelo usuário para determinar se há uma correspondência.

O limite de similaridade é armazenado no Cofre, como parte do hash de hardware.

O limite de similaridade pode ser definido depois que uma instância é registrada usando um comando como o seguinte.

Em máquinas Linux:

sudo amazon-ssm-agent -fingerprint -similarityThreshold 1

Em máquinas Windows Server que usam o PowerShell:

cd "C:\Program Files\Amazon\SSM\" `
    .\amazon-ssm-agent.exe -fingerprint -similarityThreshold 1

Importante

Se um dos componentes usados para calcular a impressão digital mudar, isso pode fazer com que o agente hiberne. Para ajudar a evitar essa hibernação, defina o limite de similaridade para um valor baixo, como 1.

SSM Agent no GitHub

O código-fonte para o SSM Agent está disponível no GitHub para que você possa adaptar o agente de acordo com suas necessidades. Incentivamos você a enviar solicitações pull sobre alterações que gostaria que fosse incluídas. Porém, a Amazon Web Services não oferece suporte à execução de cópias modificadas desse software.