appconfig

Documentation

Overview

Package appconfig manages the configuration of the agent.

Package appconfig manages the configuration of the agent.

Package appconfig manages the configuration of the agent.

Package appconfig manages the configuration of the agent.

Index

• Constants
• Variables
• type AgentInfo
• type AppConstants
• type BirdwatcherCfg
• type CredentialProfile
• type CustomIdentity
• type IdentityCfg
• type KmsConfig
• type MdsCfg
• type MgsConfig
• type OsInfo
• type S3Cfg
• type SsmCfg
• type SsmagentConfig
  • func Config(reload bool) (SsmagentConfig, error)
  • func DefaultConfig() SsmagentConfig

Constants

const (
	// Agent defaults
	DefaultAgentName      = "amazon-ssm-agent"
	SSMAgentWorkerName    = "ssm-agent-worker"
	SSMDocumentWorkerName = "ssm-document-worker"
	SSMSessionWorkerName  = "ssm-session-worker"

	DefaultTelemetryNamespace = "amazon-ssm-agent-telemetry"

	DefaultCommandWorkersLimit    = 5
	DefaultCommandWorkersLimitMin = 1

	// DefaultCommandWorkerBufferLimit represents the default job pool buffer limit for run commands
	DefaultCommandWorkerBufferLimit = 5
	// DefaultCommandWorkersBufferLimitMin represents the minimum job pool buffer limit for run commands
	DefaultCommandWorkersBufferLimitMin = 1

	// DefaultSessionWorkerBufferLimit represents the default job pool buffer limit for session documents
	DefaultSessionWorkerBufferLimit = 1
	// DefaultSessionWorkersBufferLimitMin represents the minimum job pool buffer limit for session documents
	DefaultSessionWorkersBufferLimitMin = 1

	DefaultCommandRetryLimit    = 15
	DefaultCommandRetryLimitMin = 1
	DefaultCommandRetryLimitMax = 100

	// DefaultCancelWorkersLimit represents default cancel worker limit
	DefaultCancelWorkersLimit = 3

	DefaultStopTimeoutMillis    = 20000
	DefaultStopTimeoutMillisMin = 10000
	DefaultStopTimeoutMillisMax = 1000000

	// SSM defaults
	DefaultSsmHealthFrequencyMinutes    = 5
	DefaultSsmHealthFrequencyMinutesMin = 5
	DefaultSsmHealthFrequencyMinutesMax = 60

	DefaultSsmAssociationFrequencyMinutes    = 10
	DefaultSsmAssociationFrequencyMinutesMin = 5
	DefaultSsmAssociationFrequencyMinutesMax = 60

	DefaultSsmSelfUpdateFrequencyDays    = 7
	DefaultSsmSelfUpdateFrequencyDaysMin = 1 //Minimum frequency is 1 day
	DefaultSsmSelfUpdateFrequencyDaysMax = 7 //Maximum frequency is 7 day

	//aws-ssm-agent bookkeeping constants
	DefaultLocationOfPending     = "pending"
	DefaultLocationOfCurrent     = "current"
	DefaultLocationOfCompleted   = "completed"
	DefaultLocationOfCorrupt     = "corrupt"
	DefaultLocationOfState       = "state"
	DefaultLocationOfAssociation = "association"

	// PluginLocalOutputCleanup
	// Delete plugin output file locally after plugin execution
	PluginLocalOutputCleanupAfterExecution = "after-execution"
	// Delete plugin output locally after successful s3 or cloudWatch upload
	PluginLocalOutputCleanupAfterUpload = "after-upload"

	// OrchestrationDirCleanup
	// Deletes the orchestration folder for successful and failed document execution.
	OrchestrationDirCleanupForSuccessFailedCommand = "clean-success-failed"
	// Deletes the orchestration folder only for successful document execution.
	OrchestrationDirCleanupForSuccessCommand = "clean-success"
	// Don't delete orchestration folder after execution
	DefaultOrchestrationDirCleanup = "default"

	// Don't delete logs immediately after execution. Fall back to AssociationLogsRetentionDurationHours,
	// RunCommandLogsRetentionDurationHours, and SessionLogsRetentionDurationHours
	DefaultPluginOutputRetention = "default"

	//aws-ssm-agent state and orchestration logs duration for Run Command and Association
	DefaultAssociationLogsRetentionDurationHours           = 24  // 1 day default retention
	DefaultRunCommandLogsRetentionDurationHours            = 336 // 14 days default retention
	DefaultSessionLogsRetentionDurationHours               = 336 // 14 days default retention
	DefaultStateOrchestrationLogsRetentionDurationHoursMin = 8   // Min retention of 8hrs as some processes may not timeout before this and don't want logs to be deleted before the process completes

	DefaultAuditExpirationDay    = 7  // 7 days default audit files count
	DefaultAuditExpirationDayMax = 30 // 30 days max audit files count
	DefaultAuditExpirationDayMin = 3  // 3 days min audit files count

	// log destination for session manager
	SessionLogsDestinationDisk = "disk"
	SessionLogsDestinationNone = "none"

	//aws-ssm-agent bookkeeping constants for long running plugins
	LongRunningPluginsLocation         = "longrunningplugins"
	LongRunningPluginsHealthCheck      = "healthcheck"
	LongRunningPluginDataStoreLocation = "datastore"
	LongRunningPluginDataStoreFileName = "store"
	PluginNameLongRunningPluginInvoker = "lrpminvoker"

	//aws-ssm-agent bookkeeping constants for inventory plugin
	InventoryRootDirName         = "inventory"
	CustomInventoryRootDirName   = "custom"
	FileInventoryRootDirName     = "file"
	RoleInventoryRootDirName     = "role"
	InventoryContentHashFileName = "contentHash"

	//aws-ssm-agent bookkeeping constants for failed sent replies
	RepliesRootDirName = "replies"
	//amazon-ssm-agent bookkeeping constants for failed sent replies
	RepliesMGSRootDirName = "replies_mgs"
	//amazon-ssm-agent bookkeeping constants for storing received commands
	IdempotencyDirName = "idempotency"

	//aws-ssm-agent bookkeeping constants for compliance
	ComplianceRootDirName         = "compliance"
	ComplianceContentHashFileName = "contentHash"

	// DefaultDocumentRootDirName is the root directory for storing command states
	DefaultDocumentRootDirName = "document"

	// DefaultSessionRootDirName is the root directory for storing session manager data
	DefaultSessionRootDirName = "session"

	// ConfigurationRootDirName - the configuration folder used in ec2 config
	ConfigurationRootDirName = "Configuration"

	// WorkersRootDirName  - the worker folder used in ec2 config
	WorkersRootDirName = "Workers"

	// Permissions defaults
	//NOTE: Limit READ, WRITE and EXECUTE access to administrators/root.
	ReadWriteAccess        = 0600
	ReadWriteExecuteAccess = 0700

	// Common file flags when opening/creating files
	FileFlagsCreateOrAppend          = os.O_APPEND | os.O_WRONLY | os.O_CREATE
	FileFlagsCreateOrTruncate        = os.O_TRUNC | os.O_WRONLY | os.O_CREATE
	FileFlagsCreateOrAppendReadWrite = os.O_APPEND | os.O_RDWR | os.O_CREATE

	// ExitCodes
	SuccessExitCode = 0
	ErrorExitCode   = 1

	// DefaultPluginConfig is a default config with which the plugins are initialized
	DefaultPluginConfig = "aws:defaultPluginConfig"

	// PluginNameAwsConfigureDaemon is the name for configure daemon plugin
	PluginNameAwsConfigureDaemon = "aws:configureDaemon"

	// PluginNameAwsConfigurePackage is the name for configure package plugin
	PluginNameAwsConfigurePackage = "aws:configurePackage"

	// PluginNameAwsRunShellScript is the name for run shell script plugin
	PluginNameAwsRunShellScript = "aws:runShellScript"

	// PluginNameAwsRunPowerShellScript is the name of the run powershell script plugin
	PluginNameAwsRunPowerShellScript = "aws:runPowerShellScript"

	// PluginNameAwsAgentUpdate is the name for agent update plugin
	PluginNameAwsAgentUpdate = "aws:updateSsmAgent"

	// PluginEC2ConfigUpdate is the name for ec2 config update plugin
	PluginEC2ConfigUpdate = "aws:updateAgent"

	// PluginDownloadContent is the name for downloadContent plugin
	PluginDownloadContent = "aws:downloadContent"

	// PluginRunDocument is the name of the run document plugin
	PluginRunDocument = "aws:runDocument"

	// PluginNameAwsSoftwareInventory is the name for inventory plugin
	PluginNameAwsSoftwareInventory = "aws:softwareInventory"

	// PluginNameDomainJoin is the name of domain join plugin
	PluginNameDomainJoin = "aws:domainJoin"

	// PluginNameCloudWatch is the name of cloud watch plugin
	PluginNameCloudWatch = "aws:cloudWatch"

	// PluginNameRunDockerAction is the name of the docker container plugin
	PluginNameDockerContainer = "aws:runDockerAction"

	// PluginNameConfigureDocker is the name of the configure Docker plugin
	PluginNameConfigureDocker = "aws:configureDocker"

	// PluginNameRefreshAssociation is the name of refresh association plugin
	PluginNameRefreshAssociation = "aws:refreshAssociation"

	// PluginNameAwsPowerShellModule is the name of the PowerShell Module
	PluginNameAwsPowerShellModule = "aws:psModule"

	// PluginNameAwsApplications is the name of the Applications plugin
	PluginNameAwsApplications = "aws:applications"

	AppConfigFileName = "amazon-ssm-agent.json"

	SeelogConfigFileName = "seelog.xml"

	// Output truncation limits
	MaxStdoutLength = 24000
	MaxStderrLength = 8000

	// Session worker defaults
	DefaultSessionWorkersLimit    = 1000
	DefaultSessionWorkersLimitMin = 1

	// PluginNameStandardStream is the name for session manager standard stream plugin aka shell.
	PluginNameStandardStream = "Standard_Stream"

	// PluginNameInteractiveCommands is the name for session manager interactive commands plugin.
	PluginNameInteractiveCommands = "InteractiveCommands"

	// PluginNameNonInteractiveCommands is the name for session manager non-interactive commands plugin.
	PluginNameNonInteractiveCommands = "NonInteractiveCommands"

	// PluginNamePort is the name for session manager port plugin.
	PluginNamePort = "Port"

	// Session default RunAs user name
	DefaultRunAsUserName = "ssm-user"

	// Permit excluding RandomChallenge from KMS encryption context for backward compatibility with older clients
	DefaultRequireKMSChallengeResponse = false
)

Variables

var (

	// AgentExtensions specified the root folder for various kinds of downloaded content
	AgentData = "/var/lib/amazon/ssm/"

	// PackageRoot specifies the directory under which packages will be downloaded and installed
	PackageRoot = AgentData + "packages"

	// PackageLockRoot specifies the directory under which package lock files will reside
	PackageLockRoot = AgentData + "locks/packages"

	// PackagePlatform is the platform name to use when looking for packages
	PackagePlatform = "linux"

	// DaemonRoot specifies the directory where daemon registration information is stored
	DaemonRoot = AgentData + "daemons"

	// LocalCommandRoot specifies the directory where users can submit command documents offline
	LocalCommandRoot = AgentData + "localcommands"

	// LocalCommandRootSubmitted is the directory where locally submitted command documents
	// are moved when they have been picked up
	LocalCommandRootSubmitted = AgentData + "localcommands/submitted"
	LocalCommandRootCompleted = AgentData + "localcommands/completed"

	// LocalCommandRootInvalid is the directory where locally submitted command documents
	// are moved if the service cannot validate the document (generally impossible via cli)
	LocalCommandRootInvalid = AgentData + "localcommands/invalid"

	// DownloadRoot specifies the directory under which files will be downloaded
	DownloadRoot = AgentData + "download/"

	// DefaultDataStorePath represents the directory for storing system data
	DefaultDataStorePath = AgentData

	// EC2ConfigDataStorePath represents the directory for storing ec2 config data
	EC2ConfigDataStorePath = "/var/lib/amazon/ec2config/"

	// EC2ConfigSettingPath represents the directory for storing ec2 config settings
	EC2ConfigSettingPath = "/var/lib/amazon/ec2configservice/"

	// UpdaterArtifactsRoot represents the directory for storing update related information
	UpdaterArtifactsRoot = AgentData + "update/"

	// UpdaterPidLockfile represents the location of the updater lockfile
	UpdaterPidLockfile = AgentData + "update.lock"

	// DefaultPluginPath represents the directory for storing plugins in SSM
	DefaultPluginPath = AgentData + "plugins"

	// ManifestCacheDirectory represents the directory for storing all downloaded manifest files
	ManifestCacheDirectory = AgentData + "manifests"

	// RebootExitCode that would trigger a Soft Reboot
	RebootExitCode = 194

	// Default Custom Inventory Inventory Folder
	DefaultCustomInventoryFolder = AgentData + "inventory/custom"

	// Default Session files Folder
	SessionFilesPath = AgentData + "session"

	// PowerShellPluginCommandArgs is the arguments of powershell.exe to be used by the runPowerShellScript plugin
	PowerShellPluginCommandArgs = "-f"

	// Exit Code for a command that exits before completion (generally due to timeout or cancel)
	CommandStoppedPreemptivelyExitCode = 137 // Fatal error (128) + signal for SIGKILL (9) = 137

	// RunCommandScriptName is the script name where all downloaded or provided commands will be stored
	RunCommandScriptName = "_script.sh"

	NecessaryAgentBinaryPermissionMask  os.FileMode = 0511 // Require read/execute for root, execute for all
	DisallowedAgentBinaryPermissionMask os.FileMode = 0022 // Disallow write for group and user

	// SSM Agent Update download legacy path
	LegacyUpdateDownloadFolder = "/var/log/amazon/ssm/download"

	// DefaultEC2SharedCredentialsFilePath represents the filepath for storing credentials for ec2 identity
	DefaultEC2SharedCredentialsFilePath = DefaultDataStorePath + "credentials"
)

var AppConfigPath = DefaultProgramFolder + AppConfigFileName

AppConfigPath is the path of the AppConfig

var ByteControlSignalsLinux = map[byte]os.Signal{
	'\003': syscall.SIGINT,
	'\x1c': syscall.SIGQUIT,
}

All the control signals to handles interrupt input from SSM CLI SIGINT captures Ctrl+C SIGQUIT captures Ctrl+\

var ByteControlSignalsWindows = map[byte]os.Signal{
	'\003': syscall.SIGKILL,
	'\x1c': syscall.SIGKILL,
}

All the input control messages that can be transformed to SIGKILL signal on Windows platforms Windows platforms do not support SIGINT or SIGQUIT signals. It only processes SIGKILL signal, which is translated to taskkill command on the process.

var CustomCertificatePath = ""

CustomCertificatePath is the path of the custom certificate

var DefaultCustomIdentityCredentialsProvider = "DEFAULT"

var DefaultDeniedPortForwardingRemoteIPs = []string{"169.254.169.254", "fd00:ec2::254", "169.254.169.253", "fd00:ec2::253", "169.254.169.123", "fd00:ec2::123", "169.254.169.250", "169.254.169.251", "fd00:ec2::240"}

Default deny list IP addresses for remote host port forwarding: IMDS (ipv4, ipv6); VPC (ipv4, ipv6); Amazon Time Sync (ipv4, ipv6); Amazon Windows license activation (2x ipv4, ipv6)

var DefaultDocumentWorker = defaultWorkerPath + "ssm-document-worker"

var DefaultIdentityConsumptionOrder = []string{
	"OnPrem", "EC2", "CustomIdentity",
}

DefaultIdentityConsumptionOrder defines the default order identities will be consumed

var DefaultProgramFolder = "/etc/amazon/ssm/"

DefaultProgramFolder is the default folder for SSM

var DefaultSSMAgentBinaryPath = defaultWorkerPath + "amazon-ssm-agent"

var DefaultSSMAgentWorker = defaultWorkerPath + "ssm-agent-worker"

var DefaultSessionLogger = defaultWorkerPath + "ssm-session-logger"

var DefaultSessionWorker = defaultWorkerPath + "ssm-session-worker"

var PowerShellPluginCommandName string

PowerShellPluginCommandName is the path of the powershell.exe to be used by the runPowerShellScript plugin

var RuntimeConfigFolderPath = AgentData + "runtimeconfig"

var SeelogFilePath = DefaultProgramFolder + SeelogConfigFileName

SeelogFilePath specifies the path to the seelog

var SupportedDocumentVersions = map[string]struct{}{
	"1.0":   {},
	"1.2":   {},
	"2.0":   {},
	"2.0.1": {},
	"2.0.2": {},
	"2.0.3": {},
	"2.2":   {},
}

Document versions that are supported by this Agent version. Note that 1.1 and 2.1 are deprecated schemas and hence are not added here. Version 2.0.1, 2.0.2, and 2.0.3 are added to support install documents for configurePackage that require capabilities that did not exist before the build where support for these versions was added

var SupportedSessionDocumentVersions = map[string]struct{}{
	"1.0": {},
}

Session Manager Document versions that are supported by this Agent version.

Types

type AgentInfo

type AgentInfo struct {
	Name                                    string
	Version                                 string
	Region                                  string
	ServiceDomain                           string
	OrchestrationRootDir                    string
	DownloadRootDir                         string
	ContainerMode                           bool
	SelfUpdate                              bool
	SelfUpdateScheduleDay                   int
	TelemetryMetricsToCloudWatch            bool
	TelemetryMetricsToSSM                   bool
	TelemetryMetricsNamespace               string
	LongRunningWorkerMonitorIntervalSeconds int
	// Temp config to purge cached EC2 credentials on disk if using instance profile role
	ShouldPurgeInstanceProfileRoleCreds bool
	AuditExpirationDay                  int
	ForceFileIPC                        bool
	// denotes GOMAXPROCS value for legacy agent worker
	GoMaxProcForAgentWorker int
}

AgentInfo represents metadata for amazon-ssm-agent

type AppConstants

type AppConstants struct {
	MinHealthFrequencyMinutes int
	MaxHealthFrequencyMinutes int
}

AppConstants represents some run time constant variable for various module. Currently it only contains HealthCheck module constants for health ping frequency

type BirdwatcherCfg

type BirdwatcherCfg struct {
	ForceEnable bool
}

BirdwatcherCfg represents configuration related to ConfigurePackage Birdwatcher integration

type CredentialProfile

type CredentialProfile struct {
	ShareCreds        bool
	ShareProfile      string
	ForceUpdateCreds  bool
	KeyAutoRotateDays int
}

CredentialProfile represents configurations for aws credential profile

type CustomIdentity

type CustomIdentity struct {
	InstanceID          string
	Region              string
	AvailabilityZone    string
	AvailabilityZoneId  string
	InstanceType        string
	CredentialsProvider string
}

CustomIdentity defines a single custom identity that the agent can assume

type IdentityCfg

type IdentityCfg struct {
	Ec2SystemInfoDetectionResponse string
	ConsumptionOrder               []string
	CustomIdentities               []*CustomIdentity
}

IdentityCfg stores identity consumption order and custom identities

type KmsConfig

type KmsConfig struct {
	Endpoint                    string
	RequireKMSChallengeResponse bool
}

KmsConfig represents configuration for Key Management Service

type MdsCfg

type MdsCfg struct {
	Endpoint                 string
	CommandWorkersLimit      int
	CommandWorkerBufferLimit int
	StopTimeoutMillis        int64
	CommandRetryLimit        int
}

MdsCfg represents configuration for Message delivery service (MDS)

type MgsConfig

type MgsConfig struct {
	Region                        string
	Endpoint                      string
	StopTimeoutMillis             int64
	SessionWorkersLimit           int
	SessionWorkerBufferLimit      int
	DeniedPortForwardingRemoteIPs []string
}

MgsConfig represents configuration for Message Gateway service

type OsInfo

type OsInfo struct {
	Lang    string
	Name    string
	Version string
}

OsInfo represents os related information

type S3Cfg

type S3Cfg struct {
	Endpoint  string
	Region    string
	LogBucket string
	LogKey    string
}

S3Cfg represents configurations related to S3 bucket and key for SSM

type SsmCfg

type SsmCfg struct {
	Endpoint                       string
	HealthFrequencyMinutes         int
	AssociationFrequencyMinutes    int
	AssociationRetryLimit          int
	CustomInventoryDefaultLocation string
	// Hours to retain association logs in the orchestration folder
	AssociationLogsRetentionDurationHours int
	// Hours to retain run command logs in the orchestration folder
	RunCommandLogsRetentionDurationHours int
	// Hours to retain session logs in the orchestration folder
	SessionLogsRetentionDurationHours int
	// Configure where you want Session Manager to write session data
	SessionLogsDestination string
	// Configure when after execution it is safe to delete local plugin output files in orchestration folder
	PluginLocalOutputCleanup string
	// Configure only when it is safe to delete orchestration folder after document execution. This config overrides PluginLocalOutputCleanup when set.
	OrchestrationDirectoryCleanup string
}

SsmCfg represents configuration for Simple system manager (SSM)

type SsmagentConfig

type SsmagentConfig struct {
	Profile     CredentialProfile
	Mds         MdsCfg
	Ssm         SsmCfg
	Mgs         MgsConfig
	Agent       AgentInfo
	Os          OsInfo
	S3          S3Cfg
	Birdwatcher BirdwatcherCfg
	Kms         KmsConfig
	Identity    IdentityCfg
}

SsmagentConfig stores agent configuration values.

func Config

func Config(reload bool) (SsmagentConfig, error)

Config loads the app configuration for amazon-ssm-agent. If reload is true, it loads the config afresh, otherwise it returns a previous loaded version, if any.

func DefaultConfig

func DefaultConfig() SsmagentConfig

DefaultConfig returns default ssm agent configuration