This is the second article in the OpenBSD and SSM series. Use case, we want to execute any scripts on our target systems with SSM. Here using the example of the OpenBSD package update with pkg_add(1).

You can quickly get the idea that it feels like Ansible, Puppet, Salt … you name it. However, we don’t need a centralised instance. AWS takes care of that for us, with the advantage that we have identity and access management with IAM. This saves us costs for a VM that we have to manage. As a bonus, we have a long-term archive with all the logs.

Create SSM OpenBSD system packages upgrade task

#

1. Create the SSM Document

An AWS Systems Manager document (SSM document) defines the actions that Systems Manager performs on your managed instances. … read more

Save the SSM Document as a JSON (or YAML) file, for example: update_openbsd_packages.yaml. Here is a simple example to upgrade packages depending on -stable or -current OpenBSD.

{
  "schemaVersion": "2.2",
  "description": "Update OpenBSD system packages.",
  "mainSteps": [
  {
    "action": "aws:runShellScript",
    "name": "updateOpenBSDPackages",
    "inputs": {
      "runCommand": [
          "echo 'Determining OpenBSD version'",
          "VERSION=$(sysctl -n kern.version)",
          "ARCH=$(uname -m)",
          "if echo \"$VERSION\" | grep -q '-current'; then",
          "  echo 'Updating OpenBSD -current packages'",
          "  pkg_add -u -Dsnap",
          "else",
          "  OPENBSD_VERSION=$(echo \"$VERSION\" | awk '{print $1}' | sed 's/OpenBSD //')",
          "  echo 'Setting PKG_PATH for OpenBSD -stable'",
          "  export PKG_PATH=https://ftp.openbsd.org/pub/OpenBSD/$OPENBSD_VERSION/packages-stable/$ARCH/",
          "  echo 'Updating OpenBSD -stable packages'",
          "  pkg_add -u",
          "fi"
        ]
      }
    }
  ]
}

2. Creating SSM document content

aws ssm create-document \
    --name "UpdateOpenBSDPackages" \
    --document-type "Command" \
    --content file://update_openbsd_packages.json \
    --region <your-region>

3. Run a test

You should take a look at your logs to see if a corresponding call is made by SSM.

aws ssm send-command \
    --document-name "UpdateOpenBSDPackages" \
    --document-version <your-version> \ # try 1 if it's your first verison
    --targets "Key=instanceIds,Values=mi-00fXXXXXXXXXXXXXX" \
    --comment "Testing OpenBSD update script" \
    --region <your-region>

If everything works as intended, you can, for example, look for the process. There is an exmaple with htop:

$ htop output
`- /usr/local/bin/amazon-ssm-agent
|  `- /usr/local/bin/ssm-agent-worker
|  |  `- /usr/local/bin/ssm-document-worker 4d7c525c-7b44-4454-8d8d-dad5f923a445
|  |  |  `- sh -c /var/db/amazon/ssm/mi-00fXXXXXXXXXXXXXX/document/orchestration/4d7c525c-7b44-4454-8d8d-dad5f923a445/updateOpenBSDPackages/_script.sh
|  |  |  |  `- /bin/sh /var/db/amazon/ssm/mi-00fXXXXXXXXXXXXXX/document/orchestration/4d7c525c-7b44-4454-8d8d-dad5f923a445/updateOpenBSDPackages/_script.sh
|  |  |  |     `- /usr/bin/perl /usr/sbin/pkg_add -u -Dsnap
|  |  |  |        `- /usr/bin/ftp -S session -o - https://ftp.openbsd.org/pub/OpenBSD/snapshots/packages/amd64/py3-urllib3-1.26.18p1.tgz

$ doas cat /var/db/amazon/ssm/mi-00fXXXXXXXXXXXXXX/document/orchestration/4d7c525c-7b44-4454-8d8d-dad5f923a445/updateOpenBSDPackages/_script.sh
echo 'Determining OpenBSD version using sysctl'
VERSION=$(sysctl -n kern.version)
ARCH=$(uname -m)
if echo "$VERSION" | grep -q '-current'; then
  echo 'Updating OpenBSD -current packages using pkg_add -u -Dsnap'
  pkg_add -u -Dsnap
else
  OPENBSD_VERSION=$(echo "$VERSION" | awk '{print $1}' | sed 's/OpenBSD //')
  echo 'Setting PKG_PATH for OpenBSD -stable'
  export PKG_PATH=https://ftp.openbsd.org/pub/OpenBSD/$OPENBSD_VERSION/packages-stable/$ARCH/
  echo 'Updating OpenBSD -stable packages using pkg_add -u'
  pkg_add -u
fi

Using SSM State Manager Association

#

You can use the State Manager to create an association that automatically applies the UpdateOpenBSDPackages document on a scheduled basis (using either a cron or rate expression) to your target instances.

Suppose you want to run the UpdateOpenBSDPackages document every Sunday evening (for example, at 22:00 UTC) on an instance with the ID mi-00fXXXXXXXXXXXXXX. You can create an association with the following AWS CLI command:

aws ssm create-association \
  --name "UpdateOpenBSDPackages" \
  --targets "Key=instanceIds,Values=mi-00fXXXXXXXXXXXXXX" \
  --schedule-expression "cron(0 22 ? * SUN *)" \
  --region eu-central-1

Once the association is created, State Manager will automatically execute your document according to the specified schedule. You can view the execution details and outputs in the AWS Systems Manager Console under State Manager Associations.

For further reading, check out the AWS Systems Manager Documentation. I’ll be adding more useful use-cases in future blog posts.

Happy managing!