README
¶
Amazon SSM Agent
The Amazon EC2 Simple Systems Manager (SSM) Agent is software developed for the Simple Systems Manager Service. The SSM Agent is the primary component of a feature called Run Command.
Overview
The SSM Agent runs on EC2 instances and enables you to quickly and easily execute remote commands or scripts against one or more instances. The agent uses SSM documents. When you execute a command, the agent on the instance processes the document and configures the instance as specified. Currently, the SSM Agent and Run Command enable you to quickly run Shell scripts on an instance using the AWS-RunShellScript SSM document.
Verify Requirements
Setup
Executing Commands
SSM Run Command Walkthrough Using the AWS CLI
Troubleshooting
Troubleshooting SSM Run Command
Feedback
Thank you for helping us to improve SSM and Run Command. Please send your questions or comments to: ec2-ssm-feedback@amazon.com
Building and Running from source
-
Install go Getting started
-
Install rpm-build
sudo yum install -y rpmdevtools rpm-build
-
Run
make buildto build the SSM Agent for Linux, Debian, Windows environment. -
Run
make releaseto build the agent and also packages it into a RPM, DEB and ZIP package.
The following folders are generated when the build completes:
bin/debian_386
bin/debian_amd64
bin/linux_386
bin/linux_amd64
bin/windows_386
bin/windows_amd64
Please follow the user guide to copy and install the SSM Agent
Code Layout
- Source code is under agent/
- Vendor package source code is under vendor/src
- rpm and dpkg artifacts are under packaging
- build scripts are under Tools/src
GOPATH
To use vendor dependencies, the suggested GOPATH format is :<packagesource>/vendor:<packagesource>
Make Targets
The following targets are available. Each may be run with make <target>.
| Make Target | Description |
|---|---|
build |
(Default) build builds the agent for Linux, Debian and Windows amd64 and 386 environment |
release |
release checks code style and coverage, builds the agent and also packages it into a RPM, DEB and ZIP package |
package |
package packages build result into a RPM, DEB and ZIP package |
pre-build |
pre-build goes through Tools/src folder to make sure all the script files are executable |
checkstyle |
checkstyle runs the checkstyle script |
quick-integtest |
quick-integtest runs all tests tagged with integration using go test |
quick-test |
quick-test runs all the tests including integration and unit tests using go test` |
coverage |
coverage runs all tests and calculate code coverage |
build-linux |
build-linux builds the agent for execution in the Linux amd64 environment |
build-windows |
build-windows builds the agent for execution in the Windows amd64 environment |
build-darwin |
build-darwin builds the agent for execution in the Darwin amd64 environment |
build-linux-386 |
build-linux-386 builds the agent for execution in the Linux 386 environment |
build-windows-386 |
build-windows-386 builds the agent for execution in the Windows 386 environment |
build-darwin-386 |
build-darwin-386 builds the agent for execution in the Darwin 386 environment |
create-rpm |
create-rpm builds the agent and packages it into a RPM package for Linux amd64 based distributions |
create-deb |
create-deb builds the agent and packages it into a DEB package Debian amd64 based distributions |
create-win |
create-win builds the agent and packages it into a ZIP package Windows amd64 based distributions |
create-rpm-386 |
create-rpm-386 builds the agent and packages it into a RPM package for Linux 386 based distributions |
create-deb-386 |
create-deb-386 builds the agent and packages it into a DEB package Debian 386 based distributions |
create-win-386 |
create-win-386 builds the agent and packages it into a ZIP package Windows 386 based distributions |
create-linux-package |
create-linux-package create update packages for Linux and Debian based distributions |
create-windows-package |
create-windows-package create update packages for Windows based distributions |
get-tools |
get-tools gets gocode and oracle using go get |
clean |
clean removes build artifacts. |
Contributing
Contributions and feedback are welcome! Proposals and Pull Requests will be considered and responded to. Please see the CONTRIBUTING.md file for more information.
Amazon Web Services does not currently provide support for modified copies of this software.
License
The Amazon SSM Agent is licensed under the Apache 2.0 License.
Directories
¶
| Path | Synopsis |
|---|---|
|
Tools
|
|
|
Package main represents the entry point of the agent.
|
Package main represents the entry point of the agent. |
|
agentlogstocloudwatch/cloudwatchlogspublisher
Package cloudwatchlogspublisher is responsible for pulling logs from the log queue and publishing them to cloudwatch
|
Package cloudwatchlogspublisher is responsible for pulling logs from the log queue and publishing them to cloudwatch |
|
appconfig
Package appconfig manages the configuration of the agent.
|
Package appconfig manages the configuration of the agent. |
|
association/converter
Package converter converts the plugin information from version 1.0 and 1.2 to version 2.0
|
Package converter converts the plugin information from version 1.0 and 1.2 to version 2.0 |
|
association/model
Package model provides model definition for association
|
Package model provides model definition for association |
|
association/parser
Package parser contains utilities for parsing and encoding MDS/SSM messages.
|
Package parser contains utilities for parsing and encoding MDS/SSM messages. |
|
association/processor
Package processor manage polling of associations, dispatching association to processor
|
Package processor manage polling of associations, dispatching association to processor |
|
association/rateexpr
Package rateexpr provides logic for parsing and scheduling rate expressions
|
Package rateexpr provides logic for parsing and scheduling rate expressions |
|
association/recorder
Package recorder records the association name of the last executed association to avoid duplicate execution
|
Package recorder records the association name of the last executed association to avoid duplicate execution |
|
association/scheduleexpression
Package scheduleexpression provides interface for schedule expression and factory for constructing generic parsed schedule expression
|
Package scheduleexpression provides interface for schedule expression and factory for constructing generic parsed schedule expression |
|
association/schedulemanager
Package schedulemanager schedules association and submits the association to the task pool schedulemanager is a singleton so it can be access at the plugin level
|
Package schedulemanager schedules association and submits the association to the task pool schedulemanager is a singleton so it can be access at the plugin level |
|
association/schedulemanager/signal
Package signal manages signal channel required by sending/receiving request for executing scheduled association
|
Package signal manages signal channel required by sending/receiving request for executing scheduled association |
|
association/scheduler
Package scheduler provides ability to create scheduled job
|
Package scheduler provides ability to create scheduled job |
|
association/service
Package service wraps SSM service
|
Package service wraps SSM service |
|
cli
Package cli represents the entry point of the ssm agent cli.
|
Package cli represents the entry point of the ssm agent cli. |
|
cli-main
Package main represents the entry point of the ssm agent cli.
|
Package main represents the entry point of the ssm agent cli. |
|
cli/clicommand
Package clicommand contains the implementation of all commands for the ssm agent cli
|
Package clicommand contains the implementation of all commands for the ssm agent cli |
|
cli/cliutil
Package cliutil contains helper functions for cli and clicommand
|
Package cliutil contains helper functions for cli and clicommand |
|
context
Package context defines a type that carries context specific data such as the logger.
|
Package context defines a type that carries context specific data such as the logger. |
|
contracts
Package contracts helps persist documents state to disk
|
Package contracts helps persist documents state to disk |
|
docparser
Package docparser contains methods for parsing and encoding any type of document, i.e.
|
Package docparser contains methods for parsing and encoding any type of document, i.e. |
|
executers
Package executers contains general purpose (shell) command executing objects.
|
Package executers contains general purpose (shell) command executing objects. |
|
fileutil
Package fileutil contains utilities for working with the file system.
|
Package fileutil contains utilities for working with the file system. |
|
fileutil/artifact
Package artifact contains utilities for working downloading files.
|
Package artifact contains utilities for working downloading files. |
|
fileutil/filemanager
TODO: meloniam@ https://sim.amazon.com/issues/SSM-3322 TODO: This package is a start to migration of the fileutil code to be inside an interface for better mocking.
|
TODO: meloniam@ https://sim.amazon.com/issues/SSM-3322 TODO: This package is a start to migration of the fileutil code to be inside an interface for better mocking. |
|
fileutil/filemanager/mock
Package fileutil_mock has mock functions for filemanager package
|
Package fileutil_mock has mock functions for filemanager package |
|
fingerprint
Package fingerprint contains functions that helps identify an instance this is done to protect customers from launching two instances with the same instance identifier and thus running commands intended for one on the other
|
Package fingerprint contains functions that helps identify an instance this is done to protect customers from launching two instances with the same instance identifier and thus running commands intended for one on the other |
|
framework/coremanager
Package coremanager encapsulates the logic for configuring, starting and stopping core modules
|
Package coremanager encapsulates the logic for configuring, starting and stopping core modules |
|
framework/coremodules
Package coremodules contains a list of implemented core modules.
|
Package coremodules contains a list of implemented core modules. |
|
framework/docmanager
Package docmanager helps persist documents state to disk
|
Package docmanager helps persist documents state to disk |
|
framework/processor
Package processor defines the document processing unit interface
|
Package processor defines the document processing unit interface |
|
framework/processor/executer
Package executer provides interfaces as document execution logic
|
Package executer provides interfaces as document execution logic |
|
framework/processor/executer/basicexecuter
Package basicexecuter provides interfaces as document execution logic
|
Package basicexecuter provides interfaces as document execution logic |
|
framework/processor/executer/iohandler
Package iohandler implements the iohandler for the plugins
|
Package iohandler implements the iohandler for the plugins |
|
framework/processor/executer/iohandler/iomodule
Package iomodule implements the output modules
|
Package iomodule implements the output modules |
|
framework/processor/executer/iohandler/iomodule/mock
Package iomodulemock implements the mock iomodule
|
Package iomodulemock implements the mock iomodule |
|
framework/processor/executer/iohandler/mock
Package iohandlermocks implements the mock iohandler
|
Package iohandlermocks implements the mock iohandler |
|
framework/processor/executer/iohandler/multiwriter
Package multiwriter implements a multi-writer
|
Package multiwriter implements a multi-writer |
|
framework/processor/executer/iohandler/multiwriter/mock
Package multiwritermock creates the mock mulitwriter
|
Package multiwritermock creates the mock mulitwriter |
|
framework/processor/executer/mock
Package executer provides interfaces as document execution logic
|
Package executer provides interfaces as document execution logic |
|
framework/processor/executer/outofproc/proc
Package process wraps up the os.Process interface and also provides os-specific process lookup functions
|
Package process wraps up the os.Process interface and also provides os-specific process lookup functions |
|
framework/processor/executer/plugin
Package plugin contains general interfaces and types relevant to plugins.
|
Package plugin contains general interfaces and types relevant to plugins. |
|
framework/runpluginutil
Package runpluginutil run plugin utility functions without referencing the actually plugin impl packages
|
Package runpluginutil run plugin utility functions without referencing the actually plugin impl packages |
|
githubclient
Package githubclient contains methods for interacting with git
|
Package githubclient contains methods for interacting with git |
|
githubclient/mock
Package mock_githubclient contains methods to mock githubclient package
|
Package mock_githubclient contains methods to mock githubclient package |
|
health
Package health contains routines that periodically reports health information of the agent
|
Package health contains routines that periodically reports health information of the agent |
|
hibernation
Package hibernation is responsible for the agent in hibernate mode.
|
Package hibernation is responsible for the agent in hibernate mode. |
|
hummingbird/module
Package module implements the core module to start connection with HummingBird.
|
Package module implements the core module to start connection with HummingBird. |
|
hummingbird/service
Package service is a wrapper for the new Service
|
Package service is a wrapper for the new Service |
|
jobobject
Package JobObject allows creation of job object for SSM agent process.
|
Package JobObject allows creation of job object for SSM agent process. |
|
jsonutil
Package jsonutil contains various utilities for dealing with json data.
|
Package jsonutil contains various utilities for dealing with json data. |
|
log
Package ssmlog is used to initialize ssm functional logger
|
Package ssmlog is used to initialize ssm functional logger |
|
log/ssmlog
Package ssmlog is used to initialize ssm functional logger
|
Package ssmlog is used to initialize ssm functional logger |
|
longrunning
Package longrunning implements longrunning plugins
|
Package longrunning implements longrunning plugins |
|
longrunning/datastore
Package datastore has utilites to read and write from long running plugins data-store
|
Package datastore has utilites to read and write from long running plugins data-store |
|
longrunning/manager
Package manager encapsulates everything related to long running plugin manager that starts, stops & configures long running plugins
|
Package manager encapsulates everything related to long running plugin manager that starts, stops & configures long running plugins |
|
longrunning/plugin
Package plugin contains all essential structs/interfaces for long running plugins
|
Package plugin contains all essential structs/interfaces for long running plugins |
|
longrunning/plugin/cloudwatch
Package cloudwatch implements cloudwatch plugin and its configuration
|
Package cloudwatch implements cloudwatch plugin and its configuration |
|
longrunning/plugin/rundaemon
Package rundaemon implements rundaemon plugin and its configuration
|
Package rundaemon implements rundaemon plugin and its configuration |
|
managedInstances/auth
package auth provides methods to implement managed instances auth support
|
package auth provides methods to implement managed instances auth support |
|
managedInstances/registration
package registration provides managed instance information
|
package registration provides managed instance information |
|
managedInstances/rolecreds
package rolecreds contains functions that help procure the managed instance auth credentials dependencies
|
package rolecreds contains functions that help procure the managed instance auth credentials dependencies |
|
managedInstances/sharedCredentials
package sharedCredentials provides access to the aws shared credentials file.
|
package sharedCredentials provides access to the aws shared credentials file. |
|
parameters
Package parameters provides utilities to parse ssm document parameters
|
Package parameters provides utilities to parse ssm document parameters |
|
parameterstore
Package parameterstore contains modules to resolve ssm parameters present in the document.
|
Package parameterstore contains modules to resolve ssm parameters present in the document. |
|
platform
Package platform provides instance information
|
Package platform provides instance information |
|
plugins/configurecontainers/windowscontainerutil
Package windowscontainerutil implements the the install and uninstall steps for windows for the configurecontainers plugin.
|
Package windowscontainerutil implements the the install and uninstall steps for windows for the configurecontainers plugin. |
|
plugins/configuredaemon
Package configuredaemon implements the ConfigureDaemon plugin.
|
Package configuredaemon implements the ConfigureDaemon plugin. |
|
plugins/configurepackage
Package configurepackage implements the ConfigurePackage plugin.
|
Package configurepackage implements the ConfigurePackage plugin. |
|
plugins/configurepackage/birdwatcher/facade
This interface is created manally based on the ssmiface.SSMAPI.
|
This interface is created manally based on the ssmiface.SSMAPI. |
|
plugins/configurepackage/installer
Package installer implements interfaces for installing and uninstalling packages
|
Package installer implements interfaces for installing and uninstalling packages |
|
plugins/configurepackage/installer/mock
Package installer_mock implements the mock for the installer package
|
Package installer_mock implements the mock for the installer package |
|
plugins/configurepackage/localpackages
Package localpackages implements the local storage for packages managed by the ConfigurePackage plugin.
|
Package localpackages implements the local storage for packages managed by the ConfigurePackage plugin. |
|
plugins/configurepackage/localpackages/mock
Package repository_mock implements the mock for Repository.
|
Package repository_mock implements the mock for Repository. |
|
plugins/configurepackage/ssminstaller
Package ssminstaller implements the installer for ssm packages that use documents or scripts to install and uninstall.
|
Package ssminstaller implements the installer for ssm packages that use documents or scripts to install and uninstall. |
|
plugins/domainjoin
Package domainjoin implements the domainjoin plugin.
|
Package domainjoin implements the domainjoin plugin. |
|
plugins/downloadcontent
Package downloadcontent implements the aws:downloadContent plugin
|
Package downloadcontent implements the aws:downloadContent plugin |
|
plugins/downloadcontent/gitresource
Package gitresource implements the methods to access resources from git
|
Package gitresource implements the methods to access resources from git |
|
plugins/downloadcontent/gitresource/privategithub
Package privategithub deals with all the authorization invocations to access private github
|
Package privategithub deals with all the authorization invocations to access private github |
|
plugins/downloadcontent/remoteresource
Package remoteresource is the factory for creating and developing on multiple remote resources
|
Package remoteresource is the factory for creating and developing on multiple remote resources |
|
plugins/downloadcontent/remoteresource/mock
Package remoteresource_mock has mock functions for remoteresource package
|
Package remoteresource_mock has mock functions for remoteresource package |
|
plugins/downloadcontent/s3resource
Package s3resource implements the methods to access resources from s3
|
Package s3resource implements the methods to access resources from s3 |
|
plugins/downloadcontent/ssmdocresource
Package ssmdocresource implements the methods to access resources from ssm
|
Package ssmdocresource implements the methods to access resources from ssm |
|
plugins/downloadcontent/system
Package system have all the files related dependencies used by the copy package
|
Package system have all the files related dependencies used by the copy package |
|
plugins/inventory
Package inventory contains implementation of aws:softwareInventory plugin
|
Package inventory contains implementation of aws:softwareInventory plugin |
|
plugins/inventory/datauploader
Package datauploader contains routines upload inventory data to SSM - Inventory service
|
Package datauploader contains routines upload inventory data to SSM - Inventory service |
|
plugins/inventory/gatherers
Package gatherers contains routines for different types of inventory gatherers
|
Package gatherers contains routines for different types of inventory gatherers |
|
plugins/inventory/gatherers/application
Package application contains a application gatherer.
|
Package application contains a application gatherer. |
|
plugins/inventory/gatherers/awscomponent
Package awscomponent contains a aws component gatherer.
|
Package awscomponent contains a aws component gatherer. |
|
plugins/inventory/gatherers/custom
Package custom contains a gatherer for collecting custom inventory items
|
Package custom contains a gatherer for collecting custom inventory items |
|
plugins/inventory/gatherers/file
Package file contains file gatherer.
|
Package file contains file gatherer. |
|
plugins/inventory/gatherers/instancedetailedinformation
Package instancedetailedinformation contains a gatherer for the AWS:InstanceDetailedInformation inventory type.
|
Package instancedetailedinformation contains a gatherer for the AWS:InstanceDetailedInformation inventory type. |
|
plugins/inventory/gatherers/network
Package network contains a network gatherer.
|
Package network contains a network gatherer. |
|
plugins/inventory/gatherers/registry
Package registry collects information about windows registry
|
Package registry collects information about windows registry |
|
plugins/inventory/gatherers/role
Package role contains a role gatherer.
|
Package role contains a role gatherer. |
|
plugins/inventory/gatherers/service
Package service contains a service gatherer.
|
Package service contains a service gatherer. |
|
plugins/inventory/model
Package model contains contracts for inventory
|
Package model contains contracts for inventory |
|
plugins/lrpminvoker
Package lrpminvoker contains implementation of lrpm-invoker plugin.
|
Package lrpminvoker contains implementation of lrpm-invoker plugin. |
|
plugins/pluginutil
Package pluginutil implements some common functions shared by multiple plugins.
|
Package pluginutil implements some common functions shared by multiple plugins. |
|
plugins/refreshassociation
Package refreshassociation implements the refreshassociation plugin.
|
Package refreshassociation implements the refreshassociation plugin. |
|
plugins/rundocument
Package rundocument implements the aws:runDocument plugin
|
Package rundocument implements the aws:runDocument plugin |
|
plugins/runscript
Package runscript implements the RunScript plugin.
|
Package runscript implements the RunScript plugin. |
|
plugins/updateec2config
Package updateec2config implements the UpdateEC2Config plugin.
|
Package updateec2config implements the UpdateEC2Config plugin. |
|
plugins/updatessmagent
Package updatessmagent implements the UpdateSsmAgent plugin.
|
Package updatessmagent implements the UpdateSsmAgent plugin. |
|
proxyconfig
Package proxy config to handle set/get functions of the Windows proxy settings
|
Package proxy config to handle set/get functions of the Windows proxy settings |
|
rebooter
Package rebooter provides utilities used to reboot a machine.
|
Package rebooter provides utilities used to reboot a machine. |
|
runcommand
Package runcommand implements runcommand core processing module
|
Package runcommand implements runcommand core processing module |
|
runcommand/contracts
Package model contains message struct for MDS/SSM messages.
|
Package model contains message struct for MDS/SSM messages. |
|
runcommand/mds
Package service is a wrapper for the SSM Message Delivery Service and Offline Command Service
|
Package service is a wrapper for the SSM Message Delivery Service and Offline Command Service |
|
s3util
Package s3util contains methods for interacting with S3.
|
Package s3util contains methods for interacting with S3. |
|
s3util/generator
Usage: go run riputil-gen.go
|
Usage: go run riputil-gen.go |
|
sdkutil
Package sdkutil provides utilities used to call awssdk.
|
Package sdkutil provides utilities used to call awssdk. |
|
sdkutil/retryer
Package retryer overrides the default aws sdk retryer delay logic to better suit the mds needs
|
Package retryer overrides the default aws sdk retryer delay logic to better suit the mds needs |
|
ssm/anonauth
Package anonauth is an interface to the anonymous methods of the SSM service.
|
Package anonauth is an interface to the anonymous methods of the SSM service. |
|
ssm/rsaauth
Package rsaauth is an interface to the RSA signed methods of the SSM service.
|
Package rsaauth is an interface to the RSA signed methods of the SSM service. |
|
ssm/util
Package util contains helper function common for ssm service
|
Package util contains helper function common for ssm service |
|
ssmparameterresolver
Package ssmparameterresolver contains types and methods for resolving SSM Parameter references.
|
Package ssmparameterresolver contains types and methods for resolving SSM Parameter references. |
|
startup
Package startup implements startup plugin processor
|
Package startup implements startup plugin processor |
|
startup/model
Package model provides model definition for startup processor
|
Package model provides model definition for startup processor |
|
startup/serialport
Package serialport implements serial port capabilities
|
Package serialport implements serial port capabilities |
|
task
Package task contains a default implementation of the interfaces in the task package.
|
Package task contains a default implementation of the interfaces in the task package. |
|
times
Package times provides a set of utilities related to processing time.
|
Package times provides a set of utilities related to processing time. |
|
update/processor
Package processor contains the methods for update ssm agent.
|
Package processor contains the methods for update ssm agent. |
|
update/updater
Package main represents the entry point of the ssm agent updater.
|
Package main represents the entry point of the ssm agent updater. |
|
updateutil
Package updateutil contains updater specific utilities.
|
Package updateutil contains updater specific utilities. |
|
user
package user re-implements os/user functions without the use of cgo
|
package user re-implements os/user functions without the use of cgo |
|
vault
Package vault provide interface for data storage.
|
Package vault provide interface for data storage. |
|
vault/fsvault
Package fsvault implements vault with file system storage.
|
Package fsvault implements vault with file system storage. |
|
version
Package version contains constants to indicate the current version of the agent.
|
Package version contains constants to indicate the current version of the agent. |
|
websocketutil
Package websocketutil contains methods for interacting with websocket connections.
|
Package websocketutil contains methods for interacting with websocket connections. |
Click to show internal directories.
Click to hide internal directories.