Creating associations that run MOF files
You can run Managed Object Format (MOF) files to enforce a desired state on Windows
Server managed nodes with State Manager, a capability of Amazon Systems Manager, by using the
AWS-ApplyDSCMofs
SSM document. The AWS-ApplyDSCMofs
document has two execution modes. With the first mode, you can configure the association
to scan and report if the managed nodes are in the desired state defined in the
specified MOF files. In the second mode, you can run the MOF files and change the
configuration of your nodes based on the resources and their values defined in the MOF
files. The AWS-ApplyDSCMofs
document allows you to download and run MOF
configuration files from Amazon Simple Storage Service (Amazon S3), a local share, or from a secure website with
an HTTPS domain.
State Manager logs and reports the status of each MOF file execution during each
association run. State Manager also reports the output of each MOF file execution as a
compliance event which you can view on the Amazon Systems Manager Compliance
MOF file execution is built on Windows PowerShell Desired State Configuration
(PowerShell DSC). PowerShell DSC is a declarative platform used for configuration,
deployment, and management of Windows systems. PowerShell DSC allows administrators to
describe, in simple text documents called DSC configurations, how they want a server to
be configured. A PowerShell DSC configuration is a specialized PowerShell script that
states what to do, but not how to do it. Running the configuration produces a MOF file.
The MOF file can be applied to one or more servers to achieve the desired configuration
for those servers. PowerShell DSC resources do the actual work of enforcing
configuration. For more information, see Windows PowerShell Desired State Configuration Overview
Topics
- Using Amazon S3 to store artifacts
- Resolving credentials in MOF files
- Using tokens in MOF files
- Prerequisites for creating associations that run MOF files
- Creating an association that runs MOF files
- Troubleshooting issues when creating associations that run MOF files
- Viewing DSC resource compliance details
Using Amazon S3 to store artifacts
If you're using Amazon S3 to store PowerShell modules, MOF files, compliance reports,
or status reports, then the Amazon Identity and Access Management (IAM) role used by Amazon Systems Manager SSM Agent must
have GetObject
and ListBucket
permissions on the bucket.
If you don't provide these permissions, the system returns an Access
Denied error. Below is important information about storing artifacts
in Amazon S3.
-
If the bucket is in a different Amazon Web Services account, create a bucket resource policy that grants the account (or the IAM role)
GetObject
andListBucket
permissions. -
If you want to use custom DSC resources, you can download these resources from an Amazon S3 bucket. You can also install them automatically from the PowerShell gallery.
-
If you're using Amazon S3 as a module source, upload the module as a Zip file in the following case-sensitive format:
ModuleName
_ModuleVersion
.zip. For example: MyModule_1.0.0.zip. -
All files must be in the bucket root. Folder structures aren't supported.
Resolving credentials in MOF files
Credentials are resolved by using Amazon Secrets Manager or Amazon Systems Manager Parameter Store. This allows you to set up automatic credential rotation. This also allows DSC to automatically propagate credentials to your servers without redeploying MOFs.
To use an Amazon Secrets Manager secret in a configuration, create a PSCredential object where the Username is the SecretId or SecretARN of the secret containing the credential. You can specify any value for the password. The value is ignored. Following is an example.
Configuration MyConfig { $ss = ConvertTo-SecureString -String '
a_string
' -AsPlaintext -Force $credential = New-Object PSCredential('a_secret_or_ARN
', $ss) Node localhost { Filefile_name
{ DestinationPath = 'C:\MyFile.txt' SourcePath = '\\FileServer
\Share
\MyFile
.txt' Credential = $credential } } }
Compile your MOF using the PsAllowPlaintextPassword setting in configuration data. This is OK because the credential only contains a label.
In Secrets Manager, ensure that the node has GetSecretValue access in an IAM Managed Policy, and optionally in the Secret Resource Policy if one exists. To work with DSC, the secret must be in the following format.
{ 'Username': '
a_name
', 'Password': 'a_password
' }
The secret can have other properties (for example, properties used for rotation), but it must at least have the username and password properties.
We recommended that you use a multi-user rotation method, where you have two different usernames and passwords, and the rotation Amazon Lambda function flips between them. This method allows you to have multiple active accounts while eliminating the risk of locking out a user during rotation.
Using tokens in MOF files
Tokens give you the ability to modify resource property values after the MOF has been compiled. This allows you to reuse common MOF files on multiple servers that require similar configurations.
Token substitution only works for Resource Properties of type String
.
However, if your resource has a nested CIM node property, it also resolves tokens
from String
properties in that CIM node. You can't use token
substitution for numerals or arrays.
For example, consider a scenario where you're using the xComputerManagement
resource and you want to rename the computer using DSC. Normally you would need a
dedicated MOF file for that machine. However, with token support, you can create a
single MOF file and apply it to all your nodes. In the ComputerName
property, instead of hardcoding the computer name into the MOF, you can use an
Instance Tag type token. The value is resolved during MOF parsing. See the following
example.
Configuration
MyConfig
{ xComputer Computer { ComputerName = '{tag:ComputerName}' } }
You then set a tag on either the managed node in the Systems Manager console, or an Amazon Elastic Compute Cloud (Amazon EC2) tag in the Amazon EC2 console. When you run the document, the script substitutes the {tag:ComputerName} token for the value of the instance tag.
You can also combine multiple tags into a single property, as shown in the following example.
Configuration
MyConfig
{ File MyFile { DestinationPath = '{env:TMP}\{tag:ComputerName}' Type = 'Directory' } }
There are five different types of tokens you can use:
-
tag: Amazon EC2 or managed node tags.
-
tagb64: This is the same as tag, but the system use base64 to decode the value. This allows you to use special characters in tag values.
-
env: Resolves Environment variables.
-
ssm: Parameter Store values. Only String and Secure String types are supported.
-
tagssm: This is the same as tag, but if the tag isn't set on the node, the system tries to resolve the value from a Systems Manager parameter with the same name. This is useful in situations when you want a 'default global value' but you want to be able to override it on a single node (for example, one-box deployments).
Here is a Parameter Store example that uses the ssm
token type.
File MyFile { DestinationPath = "C:\ProgramData\ConnectionData.txt" Content = "{ssm:%servicePath%/ConnectionData}" }
Tokens play an important role in reducing redundant code by making MOF files generic and reusable. If you can avoid server-specific MOF file, then there’s no need for a MOF building service. A MOF building service increases costs, slows provisioning time, and increases the risk of configuration drift between grouped nodes due to differing module versions being installed on the build server when their MOFs were compiled.
Prerequisites for creating associations that run MOF files
Before you create an association that runs MOF files, verify that your managed nodes have the following prerequisites installed:
-
Windows PowerShell version 5.0 or later. For more information, see Windows PowerShell System Requirements
on Microsoft.com. -
Amazon Tools for Windows PowerShell
version 3.3.261.0 or later. -
SSM Agent version 2.2 or later.
Creating an association that runs MOF files
To create an association that runs MOF files
Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/
. In the navigation pane, choose State Manager.
-
Choose State Manager, and then choose Create association.
-
In the Name field, specify a name. This is optional, but recommended. A name can help you understand the purpose of the association when you created it. Spaces aren't allowed in the name.
-
In the Document list, choose
AWS-ApplyDSCMofs
. -
In the Parameters section, specify your choices for the required and optional input parameters.
-
Mofs To Apply: Specify one or more MOF files to run when this association runs. Use commas to separate a list of MOF files. You can specify the following options for locating MOF file.
-
An Amazon S3 bucket name. Bucket names must use lowercase letters. Specify this information by using the following format.
s3:
amzn-s3-demo-bucket
:MOF_file_name
.mofIf you want to specify an Amazon Web Services Region, then use the following format.
s3:
bucket_Region
:amzn-s3-demo-bucket
:MOF_file_name
.mof -
A secure website. Specify this information by using the following format.
https://
domain_name
/MOF_file_name
.mofHere is an example.
https://www.example.com/TestMOF.mof
-
A file system on a local share. Specify this information by using the following format.
\
server_name
\shared_folder_name
\MOF_file_name
.mofHere is an example.
\StateManagerAssociationsBox\MOFs_folder\MyMof.mof
-
-
Service Path: (Optional) A service path is either an Amazon S3 bucket prefix where you want to write reports and status information. Or, a service path is a path for Parameter Store parameter-based tags. When resolving parameter-based tags, the system uses {ssm:%servicePath%/
parameter_name
} to inject the servicePath value into the parameter name. For example, if your service path is "WebServers/Production" then the systems resolves the parameter as: WebServers/Production/parameter_name
. This is useful for when you're running multiple environments in the same account. -
Report Bucket Name: (Optional) Enter the name of an Amazon S3 bucket where you want to write compliance data. Reports are saved in this bucket in JSON format.
Note
You can prefix the bucket name with a Region where the bucket is located. Here's an example: us-west-2:MyMOFBucket. If you're using a proxy for Amazon S3 endpoints in a specific Region that doesn't include us-east-1, prefix the bucket name with a Region. If the bucket name isn't prefixed, it automatically discovers the bucket Region by using the us-east-1 endpoint.
-
Mof Operation Mode: Choose State Manager behavior when running the
AWS-ApplyDSCMofs
association:-
Apply: Correct node configurations that aren't compliant.
-
ReportOnly: Don't correct node configurations, but instead log all compliance data and report nodes that aren't compliant.
-
-
Status Bucket Name: (Optional) Enter the name of an Amazon S3 bucket where you want to write MOF execution status information. These status reports are singleton summaries of the most recent compliance run of a node. This means that the report is overwritten the next time the association runs MOF files.
Note
You can prefix the bucket name with a Region where the bucket is located. Here's an example:
us-west-2:amzn-s3-demo-bucket
. If you're using a proxy for Amazon S3 endpoints in a specific Region that doesn't include us-east-1, prefix the bucket name with a Region. If the bucket name isn't prefixed, it automatically discovers the bucket Region using the us-east-1 endpoint. -
Module Source Bucket Name: (Optional) Enter the name of an Amazon S3 bucket that contains PowerShell module files. If you specify None, choose True for the next option, Allow PS Gallery Module Source.
Note
You can prefix the bucket name with a Region where the bucket is located. Here's an example:
us-west-2:amzn-s3-demo-bucket
. If you're using a proxy for Amazon S3 endpoints in a specific Region that doesn't include us-east-1, prefix the bucket name with a Region. If the bucket name isn't prefixed, it automatically discovers the bucket Region using the us-east-1 endpoint. -
Allow PS Gallery Module Source: (Optional) Choose True to download PowerShell modules from https://www.powershellgallery.com/
. If you choose False, specify a source for the previous option, ModuleSourceBucketName. -
Proxy Uri: (Optional) Use this option to download MOF files from a proxy server.
-
Reboot Behavior: (Optional) Specify one of the following reboot behaviors if your MOF file execution requires rebooting:
-
AfterMof: Reboots the node after all MOF executions are complete. Even if multiple MOF executions request reboots, the system waits until all MOF executions are complete to reboot.
-
Immediately: Reboots the node whenever a MOF execution requests it. If running multiple MOF files that request reboots, then the nodes are rebooted multiple times.
-
Never: Nodes aren't rebooted, even if the MOF execution explicitly requests a reboot.
-
-
Use Computer Name For Reporting: (Optional) Turn on this option to use the name of the computer when reporting compliance information. The default value is false, which means that the system uses the node ID when reporting compliance information.
-
Turn on Verbose Logging: (Optional) We recommend that you turn on verbose logging when deploying MOF files for the first time.
Important
When allowed, verbose logging writes more data to your Amazon S3 bucket than standard association execution logging. This might result in slower performance and higher storage charges for Amazon S3. To mitigate storage size issues, we recommend that you turn on lifecycle policies on your Amazon S3 bucket. For more information, see How Do I Create a Lifecycle Policy for an S3 Bucket? in the Amazon Simple Storage Service User Guide.
-
Turn on Debug Logging: (Optional) We recommend that you turn on debug logging to troubleshoot MOF failures. We also recommend that you deactivate this option for normal use.
Important
When allowed, debug logging writes more data to your Amazon S3 bucket than standard association execution logging. This might result in slower performance and higher storage charges for Amazon S3. To mitigate storage size issues, we recommend that you turn on lifecycle policies on your Amazon S3 bucket. For more information, see How Do I Create a Lifecycle Policy for an S3 Bucket? in the Amazon Simple Storage Service User Guide.
-
Compliance Type: (Optional) Specify the compliance type to use when reporting compliance information. The default compliance type is Custom:DSC. If you create multiple associations that run MOF files, then be sure to specify a different compliance type for each association. If you don't, each additional association that uses Custom:DSC overwrites the existing compliance data.
-
Pre Reboot Script: (Optional) Specify a script to run if the configuration has indicated that a reboot is necessary. The script runs before the reboot. The script must be a single line. Separate additional lines by using semicolons.
-
-
In the Targets section, choose either Specifying tags or Manually Selecting Instance. If you choose to target resources by using tags, then enter a tag key and a tag value in the fields provided. For more information about using targets, see Understanding targets and rate controls in State Manager associations.
-
In the Specify schedule section, choose either On Schedule or No schedule. If you choose On Schedule, then use the buttons provided to create a cron or rate schedule for the association.
-
In the Advanced options section:
-
In Compliance severity, choose a severity level for the association. Compliance reporting indicates whether the association state is compliant or noncompliant, along with the severity level you indicate here. For more information, see About State Manager association compliance.
-
-
In the Rate control section, configure options for running State Manager associations across of fleet of managed nodes. For more information about these options, see Understanding targets and rate controls in State Manager associations.
In the Concurrency section, choose an option:
-
Choose targets to enter an absolute number of targets that can run the association simultaneously.
-
Choose percentage to enter a percentage of the target set that can run the association simultaneously.
In the Error threshold section, choose an option:
-
Choose errors to enter an absolute number of errors allowed before State Manager stops running associations on additional targets.
-
Choose percentage to enter a percentage of errors allowed before State Manager stops running associations on additional targets.
-
(Optional) For Output options, to save the command output to a file, select the Enable writing output to S3 box. Enter the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile assigned to the managed node, not those of the IAM user performing this task. For more information, see Configure instance permissions required for Systems Manager or Create an IAM service role for a hybrid environment. In addition, if the specified S3 bucket is in a different Amazon Web Services account, verify that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket.
-
Choose Create Association.
State Manager creates and immediately runs the association on the specified nodes or targets. After the initial execution, the association runs in intervals according to the schedule that you defined and according to the following rules:
-
State Manager runs associations on nodes that are online when the interval starts and skips offline nodes.
-
State Manager attempts to run the association on all configured nodes during an interval.
-
If an association isn't run during an interval (because, for example, a concurrency value limited the number of nodes that could process the association at one time), then State Manager attempts to run the association during the next interval.
-
State Manager records history for all skipped intervals. You can view the history on the Execution History tab.
Note
The AWS-ApplyDSCMofs
is a Systems Manager Command document. This means that
you can also run this document by using Run Command, a capability of Amazon Systems Manager. For
more information, see Amazon Systems Manager Run Command.
Troubleshooting issues when creating associations that run MOF files
This section includes information to help you troubleshoot issues creating associations that run MOF files.
Turn on enhanced logging
As a first step to troubleshooting, turn on enhanced logging. More specifically, do the following:
-
Verify that the association is configured to write command output to either Amazon S3 or Amazon CloudWatch Logs (CloudWatch).
-
Set the Enable Verbose Logging parameter to True.
-
Set the Enable Debug Logging parameter to True.
With verbose and debug logging turned on, the Stdout output file includes details about the script execution. This output file can help you identify where the script failed. The Stderr output file contains errors that occurred during the script execution.
Common problems when creating associations that run MOF files
This section includes information about common problems that can occur when creating associations that run MOF files and steps to troubleshoot these issues.
My MOF wasn't applied
If State Manager failed to apply the association to your nodes, then start by reviewing the Stderr output file. This file can help you understand the root cause of the issue. Also, verify the following:
-
The node has the required access permissions to all MOF-related Amazon S3 buckets. Specifically:
-
s3:GetObject permissions: This is required for MOF files in private Amazon S3 buckets and custom modules in Amazon S3 buckets.
-
s3:PutObject permission: This is required to write compliance reports and compliance status to Amazon S3 buckets.
-
-
If you're using tags, then ensure that the node has the required IAM policy. Using tags requires the instance IAM role to have a policy allowing the
ec2:DescribeInstances
andssm:ListTagsForResource
actions. -
Ensure that the node has the expected tags or SSM parameters assigned.
-
Ensure that the tags or SSM parameters aren't misspelled.
-
Try applying the MOF locally on the node to make sure there isn't an issue with the MOF file itself.
My MOF seemed to fail, but the Systems Manager execution was successful
If the AWS-ApplyDSCMofs
document successfully ran, then the Systems Manager
execution status shows Success. This status doesn't reflect
the compliance status of your node against the configuration requirements in the
MOF file. To view the compliance status of your nodes, view the compliance
reports. You can view a JSON report in the Amazon S3 Report Bucket. This applies to
Run Command and State Manager executions. Also, for State Manager, you can view compliance
details on the Systems Manager Compliance page.
Stderr states: Name resolution failure attempting to reach service
This error indicates that the script can't reach a remote service. Most likely, the script can't reach Amazon S3. This issue most often occurs when the script attempts to write compliance reports or compliance status to the Amazon S3 bucket supplied in the document parameters. Typically, this error occurs when a computing environment uses a firewall or transparent proxy that includes an allow list. To resolve this issue:
-
Use Region-specific bucket syntax for all Amazon S3 bucket parameters. For example, the Mofs to Apply parameter should be formatted as follows:
s3:
bucket-region
:bucket-name
:mof-file-name
.mof.Here is an example:
s3:us-west-2:amzn-s3-demo-bucket:my-mof.mof
The Report, Status, and Module Source bucket names should be formatted as follows.
bucket-region
:bucket-name
. Here is an example:us-west-1:amzn-s3-demo-bucket;
-
If Region-specific syntax doesn't fix the problem, then make sure that the targeted nodes can access Amazon S3 in the desired Region. To verify this:
-
Find the endpoint name for Amazon S3 in the appropriate Amazon S3 Region. For information, see Amazon S3 Service Endpoints in the Amazon Web Services General Reference.
-
Log on to the target node and run the following ping command.
ping s3.
s3-region
.amazonaws.com.cnIf the ping failed, it means that either Amazon S3 is down, or a firewall/transparent proxy is blocking access to the Amazon S3 Region, or the node can't access the internet.
-
Viewing DSC resource compliance details
Systems Manager captures compliance information about DSC resource failures in the Amazon S3
Status Bucket you specified when you ran the
AWS-ApplyDSCMofs
document. Searching for information about DSC
resource failures in an Amazon S3 bucket can be time consuming. Instead, you can view
this information in the Systems Manager Compliance page.
The Compliance resources summary section displays a count of resources that failed. In the following example, the ComplianceType is Custom:DSC and one resource is noncompliant.
Note
Custom:DSC is the default ComplianceType value in the
AWS-ApplyDSCMofs
document. This value is customizable.
The Details overview for resources section displays information about the Amazon resource with the noncompliant DSC resource. This section also includes the MOF name, script execution steps, and (when applicable) a View output link to view detailed status information.
The View output link displays the last 4,000 characters of the detailed status. Systems Manager starts with the exception as the first element, and then scans back through the verbose messages and prepends as many as it can until it reaches the 4,000 character quota. This process displays the log messages that were output before the exception was thrown, which are the most relevant messages for troubleshooting.
For information about how to view compliance information, see Amazon Systems Manager Compliance.
Situations that affect compliance reporting
If the State Manager association fails, then no compliance data is reported. More specifically, if a MOF fails to process, then Systems Manager doesn’t report any compliance items because the associations fails. For example, if Systems Manager attempts to download a MOF from an Amazon S3 bucket that the node doesn't have permission to access, then the association fails and no compliance data is reported.
If a resource in a second MOF fails, then Systems Manager does report
compliance data. For example, if a MOF tries to create a file on a drive that
doesn’t exist, then Systems Manager reports compliance because the
AWS-ApplyDSCMofs
document is able to process completely, which
means the association successfully runs.