Documento de comando do SSM para a aplicação de patches: AWS-RunPatchBaselineWithHooks

O AWS Systems Manager é compatível com o AWS-RunPatchBaselineWithHooks, um documento do Systems Manager (documento SSM) para o Patch Manager, uma ferramenta do AWS Systems Manager. Este documento do SSM executa operações de aplicação de patches em nós gerenciados para atualizações de segurança e outros tipos de atualizações.

O AWS-RunPatchBaselineWithHooks difere do AWS-RunPatchBaseline das seguintes maneiras:

• Um documento do wrapper, AWS-RunPatchBaselineWithHooks, é um wrapper para AWS-RunPatchBaseline e depende do AWS-RunPatchBaseline para algumas de suas operações.

• A operação Install: o AWS-RunPatchBaselineWithHooks oferece suporte a hooks de ciclo de vida executados em pontos designados durante a aplicação de patches do nó gerenciado. Como as instalações de patches às vezes exigem nós gerenciados para reinicializar, a operação de aplicação patches é dividida em dois eventos, para um total de três hooks que oferecem suporte à funcionalidade personalizada. O primeiro hook é antes da operação Install with NoReboot. O segundo hook é depois da operação Install with NoReboot. O terceiro hook está disponível após a reinicialização do nó gerenciado.

• Sem suporte à lista de patches personalizada–AWS-RunPatchBaselineWithHooksnão é compatível com oInstallOverrideListparâmetro .

• Suporte ao SSM Agent: o AWS-RunPatchBaselineWithHooks exige que o SSM Agent 3.0.502 ou posterior seja instalado em um nó gerenciado para a aplicação de patches.

Quando o documento é executado, ele usa a linha de base do patch atualmente especificada como “padrão” para um tipo de sistema operacional se nenhum grupo de patches for especificado. Caso contrário, ele usa as linhas de base do patch associadas ao grupo de patches. Para obter mais informações sobre grupos de patches, consulte Grupos de patches.

Você pode usar o documento AWS-RunPatchBaselineWithHooks para aplicar patches aos sistemas operacionais e aplicações. (No Windows Server, o suporte a aplicações é limitado a atualizações de aplicações da Microsoft.)

Este documento oferece suporte a nós gerenciados do Linux e Windows Server. O documento executará as ações adequadas a cada plataforma.

nota

AWS-RunPatchBaselineWithHooks não é compatível com macOS.

Linux

Em nós gerenciados do Linux, o documento AWS-RunPatchBaselineWithHooks invoca um módulo do Python, que, por sua vez, baixa um snapshot da lista de referência de patches que se aplica ao nó gerenciado. Esse snapshot da lista de referência de patches usa regras e listas de patches aprovados e bloqueados para conduzir o gerenciador de pacotes apropriado para cada tipo de nó:

• Nós gerenciados do Amazon Linux 1, Amazon Linux 2, CentOS, Oracle Linux e RHEL 7 usam YUM. Para operações YUM, o Patch Manager requer o Python 2.6 ou uma versão posterior compatível (2.6-3.10).

• Os nós gerenciados do RHEL 8 usam o DNF. Para operações DNF, o Patch Manager requer uma versão compatível do Python 2 ou Python 3 (2.6-3.10). (Nenhuma versão é instalada por padrão no RHEL 8. É necessário instalar um deles manualmente.)

• As instâncias do Debian Server, do Raspberry Pi OS e do Ubuntu Server usam o APT. Para operações APT, o Patch Manager requer uma versão compatível do Python 3 (3.0-3.10).

• Os nós gerenciados do SUSE Linux Enterprise Server usam o Zypper. Para operações Zypper, o Patch Manager requer o Python 2.6 ou uma versão posterior compatível (2.6-3.10).

Windows Server

Em nós gerenciados do Windows Server, o documento AWS-RunPatchBaselineWithHooks baixa e invoca um módulo do PowerShell, que, por sua vez, baixa um snapshot da lista de referência de patches que se aplica ao nó gerenciado. Esse snapshot da lista de referência de patches contém uma lista de patches aprovados que é compilada consultando a lista de referência de patches em um servidor Windows Server Update Service (WSUS). Esse snapshot da lista de referência de patches é passado para a API do Windows Update, que controla o download e a instalação de patches aprovados, conforme apropriado.

Cada snapshot é específico para uma Conta da AWS, um grupo de patches, um sistema operacional e um ID de snapshot. O snapshot é entregue por meio de um URL pré-assinado do Amazon Simple Storage Service (Amazon S3), que expira 24 horas após a criação do snapshot. No entanto, depois que o URL expirar, se você quiser aplicar o mesmo conteúdo de snapshot a outros nós gerenciados, você poderá gerar um novo URL pré-assinado do Amazon S3 até três dias após a criação do snapshot. Para fazer isso, use o comando get-deployable-patch-snapshot-for-instance.

Depois que todas as atualizações aprovadas e aplicáveis forem instaladas, e as reinicializações realizadas conforme a necessidade, as informações de conformidade do patch serão geradas em um nó gerenciado e relatadas ao Patch Manager.

nota

Se o parâmetro RebootOption estiver definido como NoReboot no documento AWS-RunPatchBaselineWithHooks, o nó gerenciado não será reinicializado após a execução do Patch Manager. Para ter mais informações, consulte Nome do parâmetro: RebootOption.

Para obter informações sobre como visualizar dados de conformidade de patches, consulte Sobre a conformidade de patches.

Etapas operacionais do AWS-RunPatchBaselineWithHooks

Quando oAWS-RunPatchBaselineWithHooksé executado, as seguintes etapas são executadas:

1. Scan - Uma operação Scan que usa o AWS-RunPatchBaseline é executada em um nó gerenciado, e um relatório de conformidade é gerado e carregado.

2. Verificar estados de patch locais- Um script é executado para determinar quais etapas serão executadas com base na operação selecionada eScanResultado da Etapa 1.

   1. Se a operação selecionada for Scan, ela será marcada como concluída. A operação termina.

   2. Se a operação selecionada for Install, o Patch Manager avalia o resultado Scan da Etapa 1 para determinar o que executar a seguir:

      1. Se nenhum patch ausente for detectado e nenhuma reinicialização pendente for necessária, a operação prosseguirá diretamente para a etapa final (Etapa 8), que inclui um hook fornecido por você. Todas as etapas entre elas são ignoradas.

      2. Se nenhum patch ausente for detectado, mas houver reinicializações pendentes necessárias e a opção de reinicialização selecionada forNoReboot, a operação prossegue diretamente para a etapa final (Etapa 8), que inclui um hook fornecido por você. Todas as etapas entre elas são ignoradas.

      3. Caso contrário, a operação prossegue para a próxima etapa.

3. Operação do hook pré-patch: o documento do SSM que você forneceu para o primeiro hook do ciclo de vida, PreInstallHookDocName, é executado no seu nó gerenciado.

4. Instalar com NoReboot - Uma operação Install com a opção de reinicialização do NoReboot usando AWS-RunPatchBaseline é executada em seu nó gerenciado, e um relatório de conformidade é gerado e carregado.

5. Operação do hook pós-instalação: o documento do SSM que você forneceu para o segundo hook do ciclo de vida, PostInstallHookDocName, é executado em seu nó gerenciado.

6. Verificar reinicializações - Um script é executado para determinar se uma reinicialização é necessária para o nó gerenciado e quais etapas executar:

   1. Se a opção de reinicialização selecionada for NoReboot, a operação prosseguirá diretamente para a etapa final (Etapa 8), que inclui um hook fornecido por você. Todas as etapas entre elas são ignoradas.

   2. Se a opção de reinicialização selecionada for RebootIfNeeded, o Patch Manager verifica se há reinicializações pendentes necessárias do inventário coletado na Etapa 4. Isso significa que a operação continua na etapa 7 e o nó gerenciado é reinicializado em um dos seguintes casos:

      1. O Patch Manager instalou um ou mais patches. (O Patch Manager não avalia se o patch exige uma reinicialização. O sistema é reinicializado mesmo que o patch não exija uma reinicialização.)

      2. O Patch Manager detecta um ou mais patches com um status de INSTALLED_PENDING_REBOOT durante a operação de instalação. O status INSTALLED_PENDING_REBOOT pode significar que a opção NoReboot foi selecionada na última vez em que a operação Instalar foi executada ou que um patch foi instalado fora do Patch Manager na última vez que o nó gerenciado foi reinicializado.

      Se nenhum patch que atenda a esses critérios for encontrado, a operação de aplicação de patch no nó gerenciado será concluída e a operação prosseguirá diretamente para a etapa final (etapa 8), que inclui um hook fornecido por você. Todas as etapas entre elas são ignoradas.

7. Reinicializações e relatórios - Uma operação de instalação com a opção de reinicialização do RebootIfNeeded é executado em seu nó gerenciado usando o AWS-RunPatchBaseline e um relatório de conformidade é gerado e carregado.

8. Operação de hook pós-reinicialização: o documento do SSM que você forneceu para o terceiro hook do ciclo de vida, OnExitHookDocName, é executado em seu nó gerenciado.

Para uma operação de Scan, se a Etapa 1 falhar, o processo de execução do documento pára e a etapa é relatada como falha, embora as etapas subsequentes sejam relatadas como bem-sucedidas.

Para uma operação Install, se qualquer uma das etapas do aws:runDocument falharem durante a operação, essas etapas serão relatadas como falhas e a operação prosseguirá diretamente para a etapa final (Etapa 8), que inclui um hook fornecido por você. Todas as etapas entre elas são ignoradas. Esta etapa é relatada como falhou, a última etapa relata o status de seu resultado de operação e todas as etapas entre são relatadas como bem-sucedidas.

Parâmetros do AWS-RunPatchBaselineWithHooks

O AWS-RunPatchBaselineWithHooks oferece suporte a seis parâmetros.

O parâmetro Operation é obrigatório.

Os parâmetros RebootOption, PreInstallHookDocName, PostInstallHookDocName e OnExitHookDocName são opcionais.

O Snapshot-ID é tecnicamente opcional, mas recomendamos que você forneça um valor personalizado para ele quando executar o AWS-RunPatchBaselineWithHooks fora de uma janela de manutenção. Deixe o Patch Manager fornecer o valor automaticamente quando o documento é executado como parte de uma operação de janela de manutenção.

Nome do parâmetro: Operation

Uso: obrigatório.

Opções: Scan | Install.

Verificar

Quando você escolhe a opção Scan, o sistema usa o documento AWS-RunPatchBaseline para determinar o estado de conformidade dos patches do nó gerenciado e retorna essas informações para o Patch Manager. A opção Scan não solicita que atualizações sejam instaladas ou que nós gerenciados sejam reinicializados. Em vez disso, a operação identifica onde existem atualizações ausentes que estão aprovadas e são aplicáveis ao nó.

Instalar

Quando você escolhe a opção Install, o AWS-RunPatchBaselineWithHooks tenta instalar as atualizações aprovadas e aplicáveis que estiverem ausentes em seu nó gerenciado. As informações de conformidade dos patches geradas como parte de uma operação Install não listam atualizações ausentes, mas poderão indicar atualizações em estado malsucedido se, por qualquer motivo, a instalação da atualização não tiver tido êxito. Sempre que uma atualização é instalada em um nó gerenciado, o nó é reinicializado para garantir que a atualização esteja instalada e ativa. (Exceção: Se o parâmetro RebootOption estiver definido como NoReboot no documento AWS-RunPatchBaselineWithHooks, o nó gerenciado não será reinicializado depois que o Patch Manager for executado. Para obter mais informações, consulte Nome do parâmetro: RebootOption).

nota

Se um patch especificado pelas regras da lista de referência for instalado antes que o Patch Manager atualize o nó gerenciado, o sistema poderá não ser reinicializado conforme esperado. Isso pode acontecer quando um patch é instalado manualmente por um usuário ou instalado automaticamente por outro programa, como o pacote unattended-upgrades no Ubuntu Server.

Nome do parâmetro: Snapshot ID

Uso: opcional.

O Snapshot ID é um ID exclusivo (GUID) usado pelo Patch Manager para garantir que um conjunto de nós gerenciados, corrigidos em uma única operação, tenham o mesmo conjunto de patches aprovados. Embora o parâmetro seja definido como opcional, nossa recomendação baseada em práticas recomendadas depende de estar executando ou não o AWS-RunPatchBaselineWithHooks em uma janela de manutenção, conforme descrito na tabela a seguir.

Práticas recomendadas do AWS-RunPatchBaselineWithHooks

Modo	Prática recomendada	Detalhes
RunningAWS-RunPatchBaselineWithHooksDentro de uma janela de manutenção	Não forneça um ID de snapshot. O Patch Manager fornecerá para você.	Se você usar uma janela de manutenção para executar o AWS-RunPatchBaselineWithHooks, não forneça seu próprio ID de snapshot gerado. Nesse cenário, o Systems Manager fornece um valor GUID com base no ID de execução da janela de manutenção. Isso garante que seja usado um ID correto para todas as invocações do AWS-RunPatchBaselineWithHooks nessa janela de manutenção. Se você especificar um valor nesse cenário, observe que talvez o snapshot da lista de referência de patches não permaneça vigente por mais de três dias. Depois disso, um novo snapshot será gerado, mesmo que você especificar o mesmo ID depois que o snapshot expirar.
RunningAWS-RunPatchBaselineWithHooksFora de uma janela de manutenção	Gere e especifique um valor de GUID personalizado para o ID do snapshot..¹	Quando você não estiver usando uma janela de manutenção para executar o AWS-RunPatchBaselineWithHooks, recomendamos gerar e especificar um ID de snapshot exclusivo para cada lista de referência de patches, principalmente se estiver executando o documento AWS-RunPatchBaselineWithHooks em vários nós gerenciados na mesma operação. Se você não especificar um ID nesse cenário, o Systems Manager gerará um ID de snapshot diferente para cada nó gerenciado para o qual o comando for enviado. Em consequência disso, vários conjuntos de patches podem ser especificados entre os nós. Por exemplo, digamos que você esteja executando o documento AWS-RunPatchBaselineWithHooks diretamente do Run Command, uma ferramenta do AWS Systems Manager, e visando um grupo de 50 nós gerenciados. Ao especificar um ID de snapshot personalizado, é gerado um único snapshot da lista de referência, que é usado para avaliar e corrigir todos os nós gerenciados, garantindo que eles adquiram um estado consistente.
¹ Você pode usar qualquer ferramenta capaz de gerar um GUID para gerar um valor para o parâmetro ID do snapshot. Por exemplo, no PowerShell, você pode usar o cmdlet New-Guid para gerar um GUID no formato 12345699-9405-4f69-bc5e-9315aEXAMPLE.

Nome do parâmetro: RebootOption

Uso: opcional.

Opções: RebootIfNeeded | NoReboot

Padrão: RebootIfNeeded

Atenção

A opção padrão é RebootIfNeeded. Selecione a opção correta para o seu caso de uso. Por exemplo, se os nós gerenciados precisarem reinicializar imediatamente para concluir um processo de configuração, escolha RebootIfNeeded. Ou, se você precisar manter a disponibilidade do nó gerenciado até um horário de reinicialização agendado, escolha NoReboot.

Importante

Não é recomendável usar o Patch Manager para aplicar patches em instâncias de cluster no Amazon EMR (antes chamado de Amazon Elastic MapReduce). Em particular, não selecione a opção RebootIfNeeded para o parâmetro RebootOption. (Essa opção está disponível nos documentos do SSM Command para aplicação de patches em AWS-RunPatchBaseline, AWS-RunPatchBaselineAssociation e AWS-RunPatchBaselineWithHooks.)

Os comandos subjacentes para aplicação de patches usando o Patch Manager utilizam os comandos yum e dnf. Portanto, as operações resultam em incompatibilidades por causa da forma como os pacotes são instalados. Para obter informações sobre os métodos preferenciais para atualizar o software nos clusters do Amazon EMR, consulte Using the default AMI for Amazon EMR no Guia de gerenciamento do Amazon EMR.

RebootIfNeeded

Quando você escolhe a opção RebootIfNeeded, o nó gerenciado é reinicializado em um dos seguintes casos:

• O Patch Manager instalou um ou mais patches.

  O Patch Manager não avalia se uma reinicialização é exigida pelo patch. O sistema é reinicializado mesmo que o patch não exija uma reinicialização.

• O Patch Manager detecta um ou mais patches com um status de INSTALLED_PENDING_REBOOT durante a operação Install.

  O status INSTALLED_PENDING_REBOOT pode significar que a opção NoReboot foi selecionada na última vez em que a operação Install foi executada ou que um patch foi instalado fora do Patch Manager na última vez que o nó gerenciado foi reinicializado.

A reinicialização de nós gerenciados nesses dois casos garante que os pacotes atualizados sejam liberados da memória e mantenham o comportamento da aplicação de patches e da reinicialização consistente em todos os sistemas operacionais.

NoReboot

Quando você escolhe a opção NoReboot, o Patch Manager não reinicializa um nó gerenciado, mesmo que tenha instalado patches durante a operação Install. Essa opção é útil se você souber que os nós gerenciados não exigem reinicialização após a aplicação de patches, ou se houver aplicações ou processos em execução em um nó que não devam ser interrompidos por uma reinicialização da operação de aplicação de patch. Também é útil quando você deseja mais controle sobre o tempo de reinicializações de nós gerenciados, como, por exemplo, usando uma janela de manutenção.

nota

Se você escolher a opção NoReboot e um patch for instalado, o patch receberá um status de InstalledPendingReboot. O nó gerenciado em si, no entanto, é marcado como Non-Compliant. Depois que ocorre uma reinicialização e uma operação Scan é executada, o status do nó é atualizado para Compliant.

Arquivo de rastreamento de instalação de patches: para rastrear a instalação de patches, sobretudo os patches que foram instalados desde a última reinicialização do sistema, o Systems Manager mantém um arquivo em seu nó gerenciado.

Importante

Não exclua nem modifique o arquivo de monitoramento. Se esse arquivo for excluído ou corrompido, o relatório de conformidade de patch do nó gerenciado será impreciso. Se isso acontecer, reinicialize o nó e execute uma operação de verificação de patch para restaurar o arquivo.

Esse arquivo de rastreamento é armazenado nos seguintes locais em seus nós gerenciados:

• Sistemas operacionais Linux:

  • /var/log/amazon/ssm/patch-configuration/patch-states-configuration.json

  • /var/log/amazon/ssm/patch-configuration/patch-inventory-from-last-operation.json

• Sistema operacional Windows Server:

  • C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchStatesConfiguration.json

  • C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchInventoryFromLastOperation.json

Nome do parâmetro: PreInstallHookDocName

Uso: opcional.

Padrão: AWS-Noop.

O valor a ser fornecido para o parâmetro PreInstallHookDocName é o nome ou o nome do recurso da Amazon (ARN) de um documento do SSM de sua escolha. Você pode fornecer o nome de um documento gerenciado pela AWS ou o nome ou ARN de um documento SSM personalizado que você criou ou que foi compartilhado com você. (Para um documento do SSM que foi compartilhado com você de uma Conta da AWS diferente, você deve especificar o ARN completo do recurso, como arn:aws:ssm:us-east-2:123456789012:document/MySharedDocument).

O documento SSM especificado é executado antes da operação Install e executa todas as ações suportadas pelo SSM Agent, como um script shell para executar a verificação de integridade da aplicação, antes que o patch seja executado em seu nó gerenciado. Para obter uma lista de ações consulte Referência de plug-ins de documentos de comando). O nome do documento SSM padrão é AWS-Noop, que não executa nenhuma operação em um nó gerenciado.

Para obter informações sobre como criar um documento SSM personalizado, consulte Criar conteúdo de documento do SSM.

Nome do parâmetro: PostInstallHookDocName

Uso: opcional.

Padrão: AWS-Noop.

O valor a ser fornecido para o parâmetro PostInstallHookDocName é o nome ou o nome do recurso da Amazon (ARN) de um documento do SSM de sua escolha. Você pode fornecer o nome de um documento gerenciado pela AWS ou o nome ou ARN de um documento SSM personalizado que você criou ou que foi compartilhado com você. (Para um documento do SSM que foi compartilhado com você de uma Conta da AWS diferente, você deve especificar o ARN completo do recurso, como arn:aws:ssm:us-east-2:123456789012:document/MySharedDocument).

O documento SSM especificado é executado após oInstall with NoReboote executa todas as ações suportadas peloSSM Agent, como um script shell para instalar atualizações de terceiros antes da reinicialização. Para obter uma lista de ações consulte Referência de plug-ins de documentos de comando). O nome do documento SSM padrão é AWS-Noop, que não executa nenhuma operação em um nó gerenciado.

Para obter informações sobre como criar um documento SSM personalizado, consulte Criar conteúdo de documento do SSM.

Nome do parâmetro: OnExitHookDocName

Uso: opcional.

Padrão: AWS-Noop.

O valor a ser fornecido para o parâmetro OnExitHookDocName é o nome ou o nome do recurso da Amazon (ARN) de um documento do SSM de sua escolha. Você pode fornecer o nome de um documento gerenciado pela AWS ou o nome ou ARN de um documento SSM personalizado que você criou ou que foi compartilhado com você. (Para um documento do SSM que foi compartilhado com você de uma Conta da AWS diferente, você deve especificar o ARN completo do recurso, como arn:aws:ssm:us-east-2:123456789012:document/MySharedDocument).

O documento SSM especificado é executado após a operação de reinicialização do nó gerenciado e executa todas as ações suportadas pelo SSM Agent, como um script shell para verificar a integridade do nó após a conclusão da operação de aplicação do patch. Para obter uma lista de ações consulte Referência de plug-ins de documentos de comando). O nome do documento SSM padrão é AWS-Noop, que não executa nenhuma operação em um nó gerenciado.

Para obter informações sobre como criar um documento SSM personalizado, consulte Criar conteúdo de documento do SSM.