# Use components to customize your Image Builder image Image Builder uses the AWS Task Orchestrator and Executor (AWSTOE) component management application to orchestrate complex workflows. Build and test components that work with the AWSTOE application are based on YAML documents that define the scripts to customize or test your image. For AMI images, Image Builder installs components and the AWSTOE component management application on its Amazon EC2 build and test instances. For container images, the components and AWSTOE component management application are installed inside of the running container. Image Builder uses AWSTOE to perform all on-instance activities. There is no additional setup required to interact with AWSTOE when you run Image Builder commands or use the Image Builder console. **Note** When a component that is managed by Amazon reaches the end of its support lifespan, it is no longer maintained. About four weeks before this occurs, any accounts that are using the component receive notification, and a list of the affected recipes in their account from their AWS Health Dashboard. To learn more about AWS Health, see [AWS Health User Guide](https://docs.aws.amazon.com/health/latest/ug/). **Workflow stages for building a new image** The Image Builder workflow for building new images includes the following two distinct stages. 1. **Build stage** (pre-snapshot) – During the build stage, you make changes to the Amazon EC2 build instance that's running your base image, to create the baseline for your new image. For example, your recipe can include components that install an application or modify the operating system firewall settings. The following phases from your component document run during the build stage: + build + validate After this stage completes successfully, Image Builder creates a snapshot or container image that it uses for the test stage and beyond. 1. **Test stage** (post-snapshot) – During the test stage, there are some differences between images that create AMIs and container images. For AMI workflows, Image Builder launches an EC2 instance from the snapshot that it created as the final step of the build stage. Tests run on the new instance to validate settings and ensure that the instance is functioning as expected. For container workflows, the tests run on the same instance that was used for building. The following phase from your component document runs for every component that is included in the recipe during the image build test stage: + test This component phase applies to both Build and Test component types. After this stage completes successfully, Image Builder can create and distribute your final image from the snapshot or the container image. **Note** While the AWSTOE application framework allows you to define many phases in a component document, Image Builder has strict rules about what phases it runs, and during which stages it runs them. For a component to run during the image build stage, the component document must define at least one of these phases: `build` or `validate`. For a component to run during the image test stage, the component document must define the `test` phase, and no other phases. Since Image Builder runs the stages independently, chaining references in component documents cannot cross stage boundaries. You cannot chain a value from a phase that runs in the build stage to a phase that runs in the test stage. You can, however, define input parameters to the intended target, and pass in values through the command line. For more information about setting component parameters in your Image Builder recipes, see [Tutorial: Create a custom component with input parameters](tutorial-component-parameters.md). To assist with troubleshooting on your build or test instance AWSTOE creates a log folder that contains the input document and log files to track what's happening each time a component runs. If you configured an Amazon S3 bucket in your pipeline configuration, the logs are also written there. For more information about YAML documents and log output, see [Use the AWSTOE component document framework for custom components](toe-use-documents.md). **Tip** When you have many components to keep track of, tagging helps you to identify a specific component or version based on the tags you've assigned to it. For more information about tagging your resources using Image Builder commands in the AWS CLI, see the [Tag resources](tag-resources.md) section of this guide. This section covers how to list, view, create, and import components, using the Image Builder console or commands in the AWS CLI. **Topics** + [List and view component details](component-details.md) + [Use AWS Marketplace components to customize your image](use-marketplace-components.md) + [Use managed components to customize your Image Builder image](use-managed-components.md) + [Develop custom components for your Image Builder image](create-custom-components.md) + [How Image Builder uses the AWS Task Orchestrator and Executor application to manage components](toe-component-manager.md) # List and view component details This section describes how you can find information and view details for the components that you use in your EC2 Image Builder recipes. **Topics** + [List Image Builder components](#list-components) + [List component build versions from the AWS CLI](#cli-list-component-versions) + [Get component details from the AWS CLI](#cli-get-component) + [Get component policy details from the AWS CLI](#cli-get-component-policy) ## List Image Builder components You can use one of the following methods to list and filter Image Builder components. ------ #### [ AWS Management Console ] To display a list of components in the AWS Management Console, follow these steps: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Select **Components** from the navigation pane. By default, Image Builder shows a list of components that your account owns. 1. You can optionally filter on component ownership. To see components that you don't own, but have access to, expand the owner type dropdown list and select one of the values. The owner type list is located in the search bar, next to the search text box. You can select from the following values: + **AWS Marketplace** – Components that are associated directly with an AWS Marketplace product subscription. + **Quick start (Amazon managed)** – Publicly available components that Amazon creates and maintains. + **Owned by me** – Components that you created. This is the default selection. + **Shared with me** – Components that others created and shared with you from their account. + **Third party managed** – Components that a third party owns that you subscribed to in AWS Marketplace. ------ #### [ AWS CLI ] The following example shows how to use the **[list-components](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-components.html)** command to return a list of Image Builder components that your account owns. ``` aws imagebuilder list-components ``` You can optionally filter on component ownership. The owner attribute defines who owns the components that you want to list. By default, this request returns a list of components that your account owns. To filter the results by component owner, specify one of the following values with the `--owner` parameter when you run the **list-components** command. **Component owner values** + `AWSMarketplace` + `Amazon` + `Self` + `Shared` + `ThirdParty` The following examples show the **list-components** command with the `--owner` parameter to filter results. ``` aws imagebuilder list-components --owner Self { "requestId": "012a3456-b789-01cd-e234-fa5678b9012b", "componentVersionList": [ { "arn": "arn:aws:imagebuilder:us-west-2:123456789012:component/sample-component01/1.0.0", "name": "sample-component01", "version": "1.0.0", "platform": "Linux", "type": "BUILD", "owner": "123456789012", "dateCreated": "2020-09-24T16:58:24.444Z" }, { "arn": "arn:aws:imagebuilder:us-west-2:123456789012:component/sample-component01/1.0.1", "name": "sample-component01", "version": "1.0.1", "platform": "Linux", "type": "BUILD", "owner": "123456789012", "dateCreated": "2021-07-10T03:38:46.091Z" } ] } ``` ``` aws imagebuilder list-components --owner Amazon ``` ``` aws imagebuilder list-components --owner Shared ``` ``` aws imagebuilder list-components --owner ThirdParty ``` ------ ## List component build versions from the AWS CLI The following example shows how to use the **[list-component-build-versions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-component-build-versions.html)** command to list component build versions that have a specific semantic version. To learn more about semantic versioning for Image Builder resources, see [Semantic versioning in Image Builder](ibhow-semantic-versioning.md). ``` aws imagebuilder list-component-build-versions --component-version-arn arn:aws:imagebuilder:us-west-2:123456789012:component/example-component/1.0.1 { "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "componentSummaryList": [ { "arn": "arn:aws:imagebuilder:us-west-2:123456789012:component/examplecomponent/1.0.1/1", "name": "examplecomponent", "version": "1.0.1", "platform": "Linux", "type": "BUILD", "owner": "123456789012", "description": "An example component that builds, validates and tests an image", "changeDescription": "Updated version.", "dateCreated": "2020-02-19T18:53:45.940Z", "tags": { "KeyName": "KeyValue" } } ] } ``` ## Get component details from the AWS CLI The following example shows how to use the **[get-component](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/get-component.html)** command to get component details when you specify the component's Amazon Resource Name (ARN). ``` aws imagebuilder get-component --component-build-version-arn arn:aws:imagebuilder:us-west-2:123456789012:component/example-component/1.0.1/1 { "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11112", "component": { "arn": "arn:aws:imagebuilder:us-west-2:123456789012:component/examplecomponent/1.0.1/1", "name": "examplecomponent", "version": "1.0.1", "type": "BUILD", "platform": "Linux", "owner": "123456789012", "data": "name: HelloWorldTestingDocument\ndescription: This is hello world testing document... etc.\"\n", "encrypted": true, "dateCreated": "2020-09-24T16:58:24.444Z", "tags": {} } } ``` ## Get component policy details from the AWS CLI The following example shows how to use the **[get-component-policy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/get-component-policy.html)** command to get details of a component policy when you specify the component's ARN. ``` aws imagebuilder get-component-policy --component-arn arn:aws:imagebuilder:us-west-2:123456789012:component/example-component/1.0.1 ``` # Use AWS Marketplace components to customize your image In addition to a large selection of images created by Independent Software Vendors (ISVs), the AWS Marketplace offers components that you can use to customize your own Image Builder images. You must subscribe to these AWS Marketplace components before you can use them in your image recipe to build a new image. When you specify an AWS Marketplace component in an image recipe, Image Builder validates the subscription and performs dependency checks to ensure that you have the resources that you need to use it. When validation succeeds, Image Builder creates secure downloads for the component and its artifacts for use by image pipeline builds. ## Discover AWS Marketplace components You can discover AWS Marketplace software components to use in your recipes from the **Discover products** page in the Image Builder console, as follows. 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. From the navigation pane, choose **Discover products** in the **AWS Marketplace** section. 1. Select the **Components** tab. This tab lists all of the AWS Marketplace products that use the delivery option that includes associated components in AWS Marketplace. 1. To search for specific software products that include components, you can enter part of the name in the search bar or filter by `Status`, `Operating System`, `Publisher`, or `Categories`. The search bar also contains pagination controls for your results. ### Results Each AWS Marketplace product has its own detail panel that includes the following information. **The AWS Marketplace product name and logo** The software product name is linked to the product detail in AWS Marketplace. You can select the link to learn more about the product in AWS Marketplace. Alternatively, you can view a summary of subscription options and subscribe directly from the search results with the **View subscription options** button if you've already done your research. **Version** This contains the primary version of the component. **Operating system** The operating system that the component is designed to run on. **Publisher** The publisher of the component. This is linked to the publisher detail page in AWS Marketplace. The publisher detail page opens in a new tab in your browser. **Categories** One or more AWS Marketplace product categories that apply for the component. **Status** Shows whether you are subscribed to this product. If you're not subscribed, you can choose **View subscription options** to see a summary of the subscription options for the AWS Marketplace product, and optionally subscribe directly from the Image Builder console. **Associated components** If the AWS Marketplace product has one or more versions that are included with your subscription, they are shown in the **Associated components** section. The section is collapsed initially, and displays a count of the associated components. You can expand the section to see more details. **Note** The Center for Internet Security (CIS) component that's associated with their AWS Marketplace image product is not shown in the **Discover products** results. If you subscribe to their image product, the associated component is shown in the **Subscriptions** page, and as a third-party component in the **Create image recipe** dialog. For more information about the component, see [CIS hardening components](toe-cis.md). ## Subscribe to AWS Marketplace components After you've found an AWS Marketplace product with components that you want to use in your recipes, you can subscribe to it directly from the Image Builder console, as follows, or you can subscribe from the AWS Marketplace console. 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. From the navigation pane, choose **Discover products** in the **AWS Marketplace** section. 1. Select the **Components** tab. This tab lists all of the AWS Marketplace products that use the delivery option that includes associated components in AWS Marketplace. 1. To search for a specific AWS Marketplace product, enter part of the name in the search bar. If you know the publisher, but not the exact product name or how to spell it, you can also filter by `Publisher` to get a list of products that the publisher has available. 1. Select the product that you want to subscribe to from the results list, and choose **View subscription options**. This shows a summary of subscription options for the AWS Marketplace product. 1. Select **Subscribe** to subscribe to the product without leaving the Image Builder console. You are notified that the subscription is being processed. After you're subscribed, the **Status** is updated to `Subscribed`. For more information about the AWS Marketplace products that you're currently subscribed to, see the console steps described in [AWS Marketplace subscriptions in Image Builder](integ-marketplace.md#integ-marketplace-subs). ## Use an AWS Marketplace component in an Image Builder image recipe You can use AWS Marketplace components in your Image Builder image recipes the same way that you use other types of components. For most of the components that are associated with an AWS Marketplace image product, the ownership category is `AWS Marketplace`. For example, to use a build component from an AWS Marketplace product that you've subscribed to, choose **Add build components**, and select `AWS Marketplace` from the list. This opens a selection panel on the right side of the console interface that lists AWS Marketplace components. **Note** If you're looking for the CIS hardening component, select `Third party managed`, from the ownership list instead of `AWS Marketplace`. For more information about how to select, arrange, and configure parameters for your components, see [Create a new version of an image recipe](create-image-recipes.md). # Use managed components to customize your Image Builder image Managed components are created by AWS, sometimes in partnership with a third-party organization, such as the Center for Internet Security (CIS), for example. When you use managed components in your image or container recipes, Amazon provides the latest component versions that have patches and other updates applied. To get a list of components, or to get component information, see [List and view component details](component-details.md). The following list of featured AWS managed components includes a component that's available for you to use when you subscribe to CIS hardened AMIs through the AWS Marketplace. **Topics** + [Distributor package managed component application install for Image Builder Windows images](mgdcomponent-distributor-win.md) + [CIS hardening components](toe-cis.md) + [Amazon managed STIG hardening components for Image Builder](ib-stig.md) # Distributor package managed component application install for Image Builder Windows images AWS Systems Manager Distributor helps you package and publish software to AWS Systems Manager managed nodes. You can package and publish your own software or use Distributor to find and publish AWS-provided agent software packages. For more information about Systems Manager Distributor, see [AWS Systems Manager Distributor](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor.html) in the *AWS Systems Manager User Guide*. **Managed components for Distributor** The following Image Builder managed components use AWS Systems Manager Distributor to install application packages on Windows instances. + The `distributor-package-windows` managed component uses AWS Systems Manager Distributor to install application packages that you specify on your Windows image build instance. To configure parameters when you include this component in your recipe, see [Configure `distributor-package-windows` as a standalone component](#mgdcomponent-distributor-config-standalone). + The `aws-vss-components-windows` component uses AWS Systems Manager Distributor to install the `AwsVssComponents` package on your Windows image build instance. To configure parameters when you include this component in your recipe, see [Configure `aws-vss-components-windows` as a standalone component](#mgdcomponent-vss-config-standalone). For more information about how to use managed components in your Image Builder recipe, see [Create a new version of an image recipe](create-image-recipes.md) for image recipes or [Create a new version of a container recipe](create-container-recipes.md) for container recipes. For more information about the `AwsVssComponents` package, see [Create a VSS application-consistent snapshot](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/application-consistent-snapshots.html) in the *Amazon EC2 User Guide*. ## Prerequisites Before you use Image Builder components that rely on Systems Manager Distributor to install application packages, you must ensure that the following prerequisites are met. + Image Builder components that use Systems Manager Distributor to install application packages on your instance need permission to call the Systems Manager API. Before you use the components in an Image Builder recipe, you must create the IAM policy and role that grant permission. To configure permissions, see [Configure Systems Manager Distributor permissions](#mgdcomponent-distributor-permissions). **Note** Image Builder doesn't currently support Systems Manager Distributor packages that reboot the instance. For example, the `AWSNVMe`, `AWSPVDrivers`, and `AwsEnaNetworkDriver` Distributor packages reboot the instance, and so are not allowed. ## Configure Systems Manager Distributor permissions The `distributor-package-windows` component and other components that use it, such as `aws-vss-components-windows`, require additional permission on the build instance to run. The build instance must be able to call the Systems Manager API to begin a Distributor installation and poll for the result. Follow these procedures in the AWS Management Console to create a custom IAM policy and role that grant permission for Image Builder components to install Systems Manager Distributor packages from the build instance. **Step 1: Create a policy** Create an IAM policy for Distributor permissions. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Policies**, and then choose **Create policy**. 1. On the **Create policy** page, choose the **JSON** tab, and then replace the default content with the following JSON policy, substituting partition, Region, and account ID as necessary, or using wildcards. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowDistributorSendCommand", "Effect": "Allow", "Action": "ssm:SendCommand", "Resource": [ "arn:aws:ssm:*::document/AWS-ConfigureAWSPackage", "arn:aws:ec2:*:111122223333:instance/*" ] }, { "Sid": "AllowGetCommandInvocation", "Effect": "Allow", "Action": "ssm:GetCommandInvocation", "Resource": "*" } ] } ``` ------ 1. Choose **Review policy**. 1. For **Name**, enter a name to identify the policy, such as `InvokeDistributor` or another name that you prefer. 1. (Optional) For **Description**, enter a description of the role's purpose. 1. Choose **Create policy**. **Step 2: Create a role** Create an IAM role for Distributor permissions. 1. From the IAM console navigation pane, choose **Roles**, and then choose **Create role**. 1. Under **Select type of trusted entity**, choose **AWS service**. 1. Immediately under **Choose the service that will use this role**, choose **EC2**, and then choose **Next: Permissions**. 1. Under **Select your use case**, choose **EC2**, and then choose **Next: Permissions**. 1. In the list of policies, select the check box next to **AmazonSSMManagedInstanceCore**. (Type `SSM` in the search box if you need to narrow the list.) 1. In this list of policies, choose the box next to **EC2InstanceProfileForImageBuilder**. (Type `ImageBuilder` in the search box if you need to narrow the list.) 1. Choose **Next: Tags**. 1. (Optional) Add one or more tag key value pairs to organize, track, or control access for this role, and then choose **Next: Review**. 1. For **Role name**, enter a name for the role, such as `InvokeDistributor` or another name that you prefer. 1. (Optional) For **Role description**, replace the default text with a description of this role's purpose. 1. Choose **Create role**. The system returns you to the **Roles** page. **Step 3: Attach the policy to the role** The final step to set up your Distributor permissions is to attach the IAM policy to the IAM role. 1. From the **Roles** page in the IAM console, choose the role that you just created. The role **Summary page** opens. 1. Choose **Attach policies**. 1. Search for the policy that you created in the previous procedure and select the check box next to the name. 1. Choose **Attach policy**. Use this role in the Image Builder Infrastructure Configuration resource for any image that includes components that use Systems Manager Distributor. For more information, see [Create an infrastructure configuration](create-infra-config.md). ## Configure `distributor-package-windows` as a standalone component To use the `distributor-package-windows` component in a recipe, set the following parameters that configure the package to install. **Note** Before you use the `distributor-package-windows` component in a recipe, you must ensure that all of the [Prerequisites](#mgdcomponent-distributor-prereq) are met. + **Action** (Required) – Specify whether to install or uninstall the package. Valid values include `Install` and `Uninstall`. The value defaults to `Install`. + **PackageName** (Required) – The name of the Distributor package to install or uninstall. For a list of valid package names, see [Find Distributor packages](#mgdcomponent-distributor-find-pkg). + **PackageVersion** (Optional) – The version of the Distributor package to install. PackageVersion defaults to the recommended version. + **AdditionalArguments** (Optional) – A JSON string that contains the additional parameters to provide to your script to install, uninstall, or update a package. For more information, see **additionalArguments** in the [aws:configurePackage](https://docs.aws.amazon.com/systems-manager/latest/userguide/documents-command-ssm-plugin-reference.html#aws-configurepackage) **Inputs** section of the **Systems Manager Command document plugin reference** page. ## Configure `aws-vss-components-windows` as a standalone component When you use the `aws-vss-components-windows` component in a recipe, you can optionally set the `PackageVersion` parameter to use a specific version of the `AwsVssComponents` package. When you leave out this parameter, the component defaults to use the recommended version of the `AwsVssComponents` package. **Note** Before you use the `aws-vss-components-windows` component in a recipe, you must ensure that all of the [Prerequisites](#mgdcomponent-distributor-prereq) are met. ## Find Distributor packages Amazon and third parties provide public packages that you can install with Systems Manager Distributor. To view available packages in the AWS Management Console, log into the [AWS Systems Manager console](https://console.aws.amazon.com/systems-manager/;) and choose **Distributor** from the navigation pane. The **Distributor** page shows all of the packages that are available to you. For more information about listing available packages with the AWS CLI, see [View packages (command line)](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-view-packages.html) in the *AWS Systems Manager User Guide*. You can also create your own private Systems Manager Distributor packages. For more information, see [Create a package](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-working-with-packages-create.html) in the *AWS Systems Manager User Guide*. # CIS hardening components The Center for Internet Security (CIS) is a community-driven nonprofit organization. Their cybersecurity experts work together to develop IT security guidelines that safeguard public and private organizations against cyber threats. Their globally recognized set of best practices, known as CIS Benchmarks, help IT organizations around the world to securely configure their systems. For trending articles, blog posts, podcasts, webinars, and whitepapers, see [CIS Insights](https://www.cisecurity.org/insights) on the *Center for Internet Security* website. **CIS Benchmarks** CIS creates and maintains a set of configuration guidelines, known as the CIS Benchmarks, which provide configuration best practices for specific technologies, including operating systems, cloud platforms, applications, databases, and more. CIS Benchmarks are recognized as an industry standard by organizations and standards such as PCI DSS, HIPAA, DoD Cloud Computing SRG, FISMA, DFARS, and FEDRAMP. To learn more, see [CIS Benchmarks](https://www.cisecurity.org/benchmark) on the *Center for Internet Security* website. **CIS hardening components** When you subscribe to a CIS Hardened Image in AWS Marketplace, you also get access to the associated hardening component that runs a script to enforce CIS Benchmarks Level 1 guidelines for your configuration. The CIS organization owns and maintains CIS hardening components to ensure that they reflect the latest guidelines. **Note** CIS hardening components don't follow the standard component ordering rules in Image Builder recipes. The CIS hardening components always run last to ensure that the benchmark tests run against your output image. # Amazon managed STIG hardening components for Image Builder Security Technical Implementation Guides (STIGs) are the configuration hardening standards created by the Defense Information Systems Agency (DISA) to secure information systems and software. To make your systems compliant with STIG standards, you must install, configure, and test a variety of security settings. Image Builder provides STIG hardening components to help you more efficiently build compliant images for baseline STIG standards. These STIG components scan for misconfigurations and run a remediation script. There are no additional charges for using STIG-compliant components. **Important** With few exceptions, unless specified through parameters, STIG hardening components do not install third-party packages. If third-party packages are already installed on the instance, and if there are related STIGs that Image Builder supports for that package, the hardening component applies them. This page lists all STIGs that Image Builder supports that are applied to the EC2 instances that Image Builder launches when you build and test a new image. If you want to apply additional STIG settings to your image, you can create a custom component to configure it. For more information about custom components and how to create them, see [Use components to customize your Image Builder image](manage-components.md). When you create an image, the STIG hardening components log whether supported STIGs are applied or skipped. We recommend that you review the Image Builder logs for your images that use STIG hardening components. For more information about how to access and review Image Builder logs, see [Troubleshoot pipeline builds](troubleshooting.md#troubleshooting-pipelines). **Compliance levels** + **High (Category I) ** The most severe risk. Includes any vulnerability that can result in loss of confidentiality, availability, or integrity. + **Medium (Category II) ** Includes any vulnerability that can result in loss of confidentiality, availability, or integrity, but the risks can be mitigated. + **Low (Category III) ** Any vulnerability that degrades measures to protect against loss of confidentiality, availability, or integrity. **Topics** + [Windows STIG hardening components](#windows-os-stig) + [STIG version history log for Windows](#ib-windows-version-hist) + [Linux STIG hardening components](#linux-os-stig) + [STIG version history log for Linux](#ib-linux-version-hist) + [SCAP compliance validator component](#scap-compliance) ## Windows STIG hardening components AWSTOE Windows STIG hardening components are designed for standalone servers and apply Local Group Policy. STIG-compliant hardening components install and update the Department of Defense (DoD) certificates. They also remove unnecessary certificates to maintain STIG compliance. Currently, STIG baselines are supported for the following versions of Windows Server: 2012 R2, 2016, 2019, 2022, and 2025. This section lists current settings for each of the Windows STIG hardening components, followed by a version history log. ### Windows STIG Low (Category III) The following list contains STIG settings that the hardening component applies to your infrastructure. If a supported setting isn't applicable for your infrastructure, the hardening component skips that setting, and moves on. For example, some STIG settings might not apply to standalone servers. Organization-specific policies can also affect which settings the hardening component applies, such as a requirement for administrators to review document settings. For a complete list of Windows STIGs, see the [STIGs Document Library](https://public.cyber.mil/stigs/downloads/?_dl_facet_stigs=windows). For information about how to view the complete list, see [STIG Viewing Tools](https://public.cyber.mil/stigs/srg-stig-tools/). + **Windows Server 2025 STIG Version 1 Release 1** V-278082, V-278083, V-278084, V-278085, V-278098, V-278104, V-278110, and V-278231 + **Windows Server 2022 STIG Version 2 Release 7** V-254335, V-254336, V-254337, V-254338, V-254351, V-254357, V-254363, and V-254481 + **Windows Server 2019 STIG Version 3 Release 7** V-205691, V-205819, V-205858, V-205859, V-205860, V-205870, V-205871, and V-205923 + **Windows Server 2016 STIG Version 2 Release 10** V-224916, V-224917, V-224918, V-224919, V-224931, V-224942, and V-225060 + **Windows Server 2012 R2 MS STIG Version 3 Release 5** V-225250, V-225318, V-225319, V-225324, V-225327, V-225328, V-225330, V-225331, V-225332, V-225333, V-225334, V-225335, V-225336, V-225342, V-225343, V-225355, V-225357, V-225358, V-225359, V-225360, V-225362, V-225363, V-225376, V-225392, V-225394, V-225412, V-225459, V-225460, V-225462, V-225468, V-225473, V-225476, V-225479, V-225480, V-225481, V-225482, V-225483, V-225484, V-225485, V-225487, V-225488, V-225489, V-225490, V-225511, V-225514, V-225525, V-225526, V-225536, and V-225537 + **Microsoft .NET Framework 4.0 STIG Version 2 Release 7** No STIG settings are applied to the Microsoft .NET Framework for Category III vulnerabilities. + **Windows Firewall STIG Version 2 Release 2** V-241994, V-241995, V-241996, V-241999, V-242000, V-242001, V-242006, V-242007, and V-242008 + **Internet Explorer 11 STIG Version 2 Release 6** V-223056 and V-223078 + **Microsoft Edge STIG Version 2 Release 4 (Windows Server 2022 and 2025 only)** V-235727, V-235731, V-235751, V-235752, and V-235765 + **Microsoft Defender STIG Version 2 Release 7** No STIG settings are applied to the Microsoft Antivirus for Category III vulnerabilities. ### Windows STIG Medium (Category II) The following list contains STIG settings that the hardening component applies to your infrastructure. If a supported setting isn't applicable for your infrastructure, the hardening component skips that setting, and moves on. For example, some STIG settings might not apply to standalone servers. Organization-specific policies can also affect which settings the hardening component applies, such as a requirement for administrators to review document settings. For a complete list of Windows STIGs, see the [STIGs Document Library](https://public.cyber.mil/stigs/downloads/?_dl_facet_stigs=windows). For information about how to view the complete list, see [STIG Viewing Tools](https://public.cyber.mil/stigs/srg-stig-tools/). **Note** The Windows STIG Medium hardening components include all listed STIG settings that AWSTOE applies for Windows STIG Low hardening components, in addition to the STIG settings that are listed specifically for Category II vulnerabilities. + **Windows Server 2025 STIG Version 1 Release 1** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-278015, V-278016, V-278019, V-278020, V-278021, V-278022, V-278023, V-278024, V-278025, V-278026, V-278033, V-278034, V-278035, V-278036, V-278037, V-278038, V-278039, V-278047, V-278048, V-278049, V-278050, V-278051, V-278052, V-278053, V-278054, V-278055, V-278056, V-278057, V-278058, V-278059, V-278060, V-278061, V-278062, V-278063, V-278064, V-278065, V-278066, V-278067, V-278068, V-278069, V-278070, V-278071, V-278072, V-278073, V-278074, V-278075, V-278076, V-278077, V-278078, V-278079, V-278080, V-278086, V-278088, V-278089, V-278091, V-278092, V-278093, V-278094, V-278095, V-278096, V-278097, V-278102, V-278103, V-278105, V-278106, V-278107, V-278108, V-278109, V-278111, V-278112, V-278113, V-278114, V-278115, V-278116, V-278117, V-278118, V-278119, V-278120, V-278122, V-278123, V-278124, V-278126, V-278127, V-278129, V-278130, V-278131, V-278165, V-278168, V-278169, V-278170, V-278171, V-278174, V-278180, V-278181, V-278182, V-278183, V-278184, V-278185, V-278187, V-278188, V-278189, V-278192, V-278193, V-278194, V-278195, V-278198, V-278199, V-278200, V-278201, V-278202, V-278203, V-278204, V-278205, V-278206, V-278209, V-278210, V-278211, V-278212, V-278213, V-278214, V-278218, V-278220, V-278221, V-278222, V-278223, V-278226, V-278227, V-278228, V-278229, V-278230, V-278232, V-278233, V-278234, V-278235, V-278236, V-278237, V-278238, V-278239, V-278240, V-278241, V-278243, V-278244, V-278245, V-278247, V-278248, V-278249, V-278251, V-278252, V-278253, V-278254, V-278255, V-278256, V-278257, V-278258, V-278259, V-278260, V-278261, V-278262, V-279916, V-279917, V-279918, V-279919, V-279920, V-279921, V-279922, and V-279923 + **Windows Server 2022 STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-254247, V-254269, V-254270, V-254271, V-254272, V-254273, V-254274, V-254275, V-254276, V-254277, V-254278, V-254285, V-254286, V-254287, V-254288, V-254289, V-254290, V-254291, V-254292, V-254296, V-254297, V-254298, V-254299, V-254300, V-254301, V-254302, V-254303, V-254304, V-254305, V-254307, V-254309, V-254311, V-254312, V-254313, V-254314, V-254315, V-254316, V-254319, V-254320, V-254321, V-254322, V-254323, V-254324, V-254325, V-254326, V-254327, V-254328, V-254329, V-254330, V-254331, V-254332, V-254333, V-254334, V-254339, V-254341, V-254342, V-254344, V-254345, V-254346, V-254347, V-254348, V-254349, V-254350, V-254355, V-254356, V-254358, V-254359, V-254360, V-254361, V-254362, V-254364, V-254365, V-254366, V-254367, V-254368, V-254369, V-254370, V-254371, V-254372, V-254373, V-254375, V-254376, V-254377, V-254379, V-254380, V-254382, V-254383, V-254384, V-254431, V-254433, V-254434, V-254435, V-254436, V-254438, V-254439, V-254440, V-254442, V-254443, V-254444, V-254445, V-254447, V-254448, V-254449, V-254450, V-254451, V-254452, V-254453, V-254454, V-254455, V-254456, V-254459, V-254460, V-254461, V-254462, V-254463, V-254464, V-254468, V-254470, V-254471, V-254472, V-254473, V-254476, V-254477, V-254478, V-254479, V-254480, V-254482, V-254483, V-254484, V-254485, V-254486, V-254487, V-254488, V-254489, V-254491, V-254493, V-254494, V-254495, V-254497, V-254498, V-254499, V-254501, V-254502, V-254503, V-254504, V-254505, V-254506, V-254507, V-254508, V-254509, V-254510, V-254511, V-254512, V-278942, V-278943, V-278944, V-278945, V-278946, V-278947, V-278948, and V-278949 + **Windows Server 2019 STIG Version 3 Release 7** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-205625, V-205626, V-205627, V-205629, V-205630, V-205633, V-205634, V-205635, V-205636, V-205637, V-205638, V-205639, V-205640, V-205641, V-205642, V-205643, V-205644, V-205648, V-205649, V-205650, V-205651, V-205652, V-205655, V-205656, V-205659, V-205660, V-205662, V-205671, V-205672, V-205673, V-205675, V-205676, V-205678, V-205679, V-205680, V-205681, V-205682, V-205683, V-205684, V-205685, V-205686, V-205687, V-205688, V-205689, V-205690, V-205692, V-205693, V-205694, V-205697, V-205698, V-205708, V-205709, V-205712, V-205714, V-205716, V-205717, V-205718, V-205719, V-205720, V-205722, V-205730, V-205731, V-205733, V-205747, V-205748, V-205749, V-205751, V-205752, V-205754, V-205755, V-205756, V-205758, V-205759, V-205760, V-205761, V-205762, V-205763, V-205764, V-205765, V-205766, V-205767, V-205768, V-205769, V-205770, V-205771, V-205772, V-205773, V-205774, V-205775, V-205776, V-205777, V-205778, V-205779, V-205780, V-205781, V-205782, V-205783, V-205784, V-205795, V-205796, V-205797, V-205798, V-205801, V-205808, V-205809, V-205810, V-205811, V-205812, V-205813, V-205814, V-205815, V-205816, V-205817, V-205821, V-205822, V-205823, V-205824, V-205825, V-205826, V-205827, V-205828, V-205830, V-205832, V-205833, V-205835, V-205836, V-205837, V-205838, V-205842, V-205861, V-205863, V-205865, V-205866, V-205867, V-205868, V-205869, V-205872, V-205873, V-205874, V-205909, V-205910, V-205911, V-205912, V-205915, V-205916, V-205917, V-205918, V-205920, V-205921, V-205922, V-205925, V-257503, V-278934, V-278935, V-278936, V-278937, V-278938, V-278939, V-278940, and V-278941 + **Windows Server 2016 STIG Version 2 Release 10** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-224850, V-224851, V-224852, V-224853, V-224854, V-224855, V-224856, V-224857, V-224858, V-224859, V-224866, V-224867, V-224868, V-224869, V-224870, V-224871, V-224872, V-224873, V-224877, V-224878, V-224879, V-224880, V-224881, V-224882, V-224883, V-224884, V-224885, V-224886, V-224888, V-224890, V-224892, V-224893, V-224894, V-224895, V-224896, V-224897, V-224900, V-224901, V-224902, V-224903, V-224904, V-224905, V-224906, V-224907, V-224908, V-224909, V-224910, V-224911, V-224912, V-224913, V-224914, V-224915, V-224920, V-224921, V-224922, V-224924, V-224925, V-224926, V-224927, V-224928, V-224929, V-224930, V-224935, V-224936, V-224937, V-224938, V-224939, V-224940, V-224941, V-224943, V-224944, V-224945, V-224946, V-224947, V-224948, V-224949, V-224951, V-224952, V-224953, V-224955, V-224956, V-224957, V-224959, V-224960, V-224962, V-224963, V-224965, V-224966, V-224967, V-224968, V-224969, V-224987, V-224988, V-224989, V-224995, V-224996, V-224997, V-224998, V-224999, V-225000, V-225001, V-225002, V-225003, V-225004, V-225005, V-225008, V-225009, V-225010, V-225011, V-225013, V-225014, V-225015, V-225016, V-225017, V-225018, V-225019, V-225020, V-225021, V-225022, V-225023, V-225024, V-225026, V-225027, V-225028, V-225029, V-225030, V-225031, V-225032, V-225033, V-225034, V-225035, V-225038, V-225039, V-225040, V-225041, V-225042, V-225043, V-225047, V-225049, V-225050, V-225051, V-225052, V-225055, V-225056, V-225057, V-225058, V-225059, V-225061, V-225062, V-225063, V-225064, V-225065, V-225066, V-225067, V-225068, V-225070, V-225072, V-225073, V-225074, V-225076, V-225077, V-225078, V-225080, V-225081, V-225082, V-225083, V-225084, V-225085, V-225086, V-225087, V-225088, V-225089, V-225092, V-225093, and V-257502 + **Windows Server 2012 R2 MS STIG Version 3 Release 5** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-225239, V-225259, V-225260, V-225261, V-225263, V-225264, V-225265, V-225266, V-225267, V-225268, V-225269, V-225270, V-225271, V-225272, V-225273, V-225275, V-225276, V-225277, V-225278, V-225279, V-225280, V-225281, V-225282, V-225283, V-225284, V-225285, V-225286, V-225287, V-225288, V-225289, V-225290, V-225291, V-225292, V-225293, V-225294, V-225295, V-225296, V-225297, V-225298, V-225299, V-225300, V-225301, V-225302, V-225303, V-225304, V-225305, V-225314, V-225315, V-225316, V-225317, V-225325, V-225326, V-225329, V-225337, V-225338, V-225339, V-225340, V-225341, V-225344, V-225345, V-225346, V-225347, V-225348, V-225349, V-225350, V-225351, V-225352, V-225353, V-225356, V-225367, V-225368, V-225369, V-225370, V-225371, V-225372, V-225373, V-225374, V-225375, V-225377, V-225378, V-225379, V-225380, V-225381, V-225382, V-225383, V-225384, V-225385, V-225386, V-225389, V-225391, V-225393, V-225395, V-225397, V-225398, V-225400, V-225401, V-225402, V-225404, V-225405, V-225406, V-225407, V-225408, V-225409, V-225410, V-225411, V-225413, V-225414, V-225415, V-225441, V-225442, V-225443, V-225448, V-225452, V-225453, V-225454, V-225455, V-225456, V-225457, V-225458, V-225461, V-225463, V-225464, V-225469, V-225470, V-225471, V-225472, V-225474, V-225475, V-225477, V-225478, V-225486, V-225494, V-225500, V-225501, V-225502, V-225503, V-225504, V-225506, V-225508, V-225509, V-225510, V-225513, V-225515, V-225516, V-225517, V-225518, V-225519, V-225520, V-225521, V-225522, V-225523, V-225524, V-225527, V-225528, V-225529, V-225530, V-225531, V-225532, V-225533, V-225534, V-225535, V-225538, V-225539, V-225540, V-225541, V-225542, V-225543, V-225544, V-225545, V-225546, V-225548, V-225549, V-225550, V-225551, V-225553, V-225554, V-225555, V-225557, V-225558, V-225559, V-225560, V-225561, V-225562, V-225563, V-225564, V-225565, V-225566, V-225567, V-225568, V-225569, V-225570, V-225571, V-225572, V-225573, and V-225574 + **Microsoft .NET Framework 4.0 STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-225223, V-225230, V-225235, and V-225238 + **Windows Firewall STIG Version 2 Release 2** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-241989, V-241990, V-241991, V-241993, V-241998, V-242003, V-242004, and V-242005 + **Internet Explorer 11 STIG Version 2 Release 6** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-223015, V-223017, V-223018, V-223019, V-223020, V-223021, V-223022, V-223023, V-223024, V-223025, V-223026, V-223027, V-223028, V-223029, V-223030, V-223031, V-223032, V-223033, V-223034, V-223035, V-223036, V-223037, V-223038, V-223039, V-223040, V-223041, V-223042, V-223043, V-223044, V-223045, V-223046, V-223048, V-223049, V-223050, V-223051, V-223052, V-223053, V-223054, V-223055, V-223057, V-223058, V-223059, V-223060, V-223061, V-223062, V-223063, V-223064, V-223065, V-223066, V-223067, V-223068, V-223069, V-223070, V-223071, V-223072, V-223073, V-223074, V-223075, V-223076, V-223077, V-223079, V-223080, V-223081, V-223082, V-223083, V-223084, V-223085, V-223086, V-223087, V-223088, V-223089, V-223090, V-223091, V-223092, V-223093, V-223094, V-223095, V-223096, V-223097, V-223098, V-223099, V-223100, V-223101, V-223102, V-223103, V-223104, V-223105, V-223106, V-223107, V-223108, V-223109, V-223110, V-223111, V-223112, V-223113, V-223114, V-223115, V-223116, V-223117, V-223118, V-223119, V-223120, V-223121, V-223123, V-223125, V-223126, V-223127, V-223128, V-223129, V-223130, V-223131, V-223132, V-223133, V-223134, V-223135, V-223136, V-223137, V-223138, V-223139, V-223140, V-223141, V-223142, V-223143, V-223144, V-223145, V-223146, V-223147, V-223148, V-223149, V-250540, and V-250541 + **Microsoft Edge STIG Version 2 Release 4 (Windows Server 2022 and 2025 only)** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-235720, V-235721, V-235723, V-235724, V-235725, V-235726, V-235728, V-235729, V-235730, V-235732, V-235733, V-235734, V-235735, V-235736, V-235737, V-235738, V-235739, V-235740, V-235741, V-235742, V-235743, V-235744, V-235745, V-235746, V-235747, V-235748, V-235749, V-235750, V-235754, V-235756, V-235760, V-235761, V-235763, V-235764, V-235766, V-235767, V-235768, V-235769, V-235770, V-235771, V-235772, V-235773, V-235774, and V-246736 + **Microsoft Defender STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities, plus: V-213427, V-213429, V-213430, V-213431, V-213432, V-213433, V-213434, V-213435, V-213436, V-213437, V-213438, V-213439, V-213440, V-213441, V-213442, V-213443, V-213444, V-213445, V-213446, V-213447, V-213448, V-213449, V-213450, V-213451, V-213454, V-213455, V-213456, V-213457, V-213458, V-213459, V-213460, V-213461, V-213462, V-213463, V-213464, V-213465, V-213466, V-278647, V-278648, V-278649, V-278650, V-278651, V-278652, V-278653, V-278654, V-278655, V-278656, V-278658, V-278659, V-278660, V-278661, V-278662, V-278668, V-278669, V-278672, V-278674, V-278675, V-278676, V-278677, V-278678, V-278679, V-278680, and V-278863 ### Windows STIG High (Category I) The following list contains STIG settings that the hardening component applies to your infrastructure. If a supported setting isn't applicable for your infrastructure, the hardening component skips that setting, and moves on. For example, some STIG settings might not apply to standalone servers. Organization-specific policies can also affect which settings the hardening component applies, such as a requirement for administrators to review document settings. For a complete list of Windows STIGs, see the [STIGs Document Library](https://public.cyber.mil/stigs/downloads/?_dl_facet_stigs=windows). For information about how to view the complete list, see [STIG Viewing Tools](https://public.cyber.mil/stigs/srg-stig-tools/). **Note** The Windows STIG High hardening components include all listed STIG settings that AWSTOE applies for Windows STIG Low and Windows STIG Medium hardening components, in addition to the STIG settings that are listed specifically for Category I vulnerabilities. + **Windows Server 2025 STIG Version 1 Release 1** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities, plus: V-278040, V-278099, V-278100, V-278101, V-278121, V-278125, V-278128, V-278196, V-278215, V-278216, V-278217, V-278219, V-278225, V-278242, V-278246, and V-278250 + **Windows Server 2022 STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities, plus: V-254250, V-254293, V-254352, V-254353, V-254354, V-254374, V-254378, V-254381, V-254446, V-254466, V-254467, V-254469, V-254474, V-254475, V-254492, V-254496, and V-254500 + **Windows Server 2019 STIG Version 3 Release 7** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities, plus: V-205653, V-205654, V-205663, V-205711, V-205713, V-205724, V-205725, V-205750, V-205753, V-205757, V-205802, V-205804, V-205805, V-205806, V-205849, V-205908, V-205914, and V-205919 + **Windows Server 2016 STIG Version 2 Release 10** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities, plus: V-224831, V-224874, V-224932, V-224933, V-224934, V-224954, V-224958, V-224961, V-225025, V-225045, V-225046, V-225048, V-225053, V-225054, V-225071, V-225079, and V-225091 + **Windows Server 2012 R2 MS STIG Version 3 Release 5** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities, plus: V-225274, V-225354, V-225364, V-225365, V-225366, V-225390, V-225396, V-225399, V-225444, V-225449, V-225491, V-225492, V-225493, V-225496, V-225497, V-225498, V-225505, V-225507, V-225547, V-225552, and V-225556 + **Microsoft .NET Framework 4.0 STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for the Microsoft .NET Framework. No additional STIG settings apply for Category I vulnerabilities. + **Windows Firewall STIG Version 2 Release 2** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities, plus: V-241992, V-241997, and V-242002 + **Internet Explorer 11 STIG Version 2 Release 6** V-252910 + **Microsoft Edge STIG Version 2 Release 4 (Windows Server 2022 and 2025 only)** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities, plus: V-235758 and V-235759 + **Microsoft Defender STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities, plus: V-213426, V-213428, V-213452, and V-213453 ## STIG version history log for Windows This section logs Windows hardening component version history for the quarterly STIG updates. To see the changes and published versions for a quarter, choose the title to expand the information. ### 2026 Q1 changes - 3/10/2026: Added support for Windows Server 2025 and updated all applicable STIGs to first quarter 2026. **STIG-Build-Windows** + Windows Server 2025 STIG Version 1 Release 1 + Windows Server 2022 STIG Version 2 Release 7 + Windows Server 2019 STIG Version 3 Release 7 + Windows Server 2016 STIG Version 2 Release 10 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 7 + Windows Firewall STIG Version 2 Release 2 + Internet Explorer 11 STIG Version 2 Release 8 + Microsoft Edge STIG Version 2 Release 4 (Windows Server 2022 and 2025 only) ### 2025 Q3 changes - 9/04/2025 (no changes): There were no changes for Windows component STIGS for the 2025 third quarter release. ### 2025 Q2 changes - 06/26/2025: Updated STIG versions and applied STIGS for the 2025 Q2 release as follows: **STIG-Build-Windows-Low version 2025.2.x** + Windows Server 2022 STIG Version 2 Release 4 + Windows Server 2019 STIG Version 3 Release 4 + Windows Server 2016 STIG Version 2 Release 10 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 6 + Windows Firewall STIG Version 2 Release 2 + Internet Explorer 11 STIG Version 2 Release 5 + Microsoft Edge STIG Version 2 Release 2 (Windows Server 2022 only) **STIG-Build-Windows-Medium version 2025.2.x** + Windows Server 2022 STIG Version 2 Release 4 + Windows Server 2019 STIG Version 3 Release 4 + Windows Server 2016 STIG Version 2 Release 10 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 6 + Windows Firewall STIG Version 2 Release 2 + Internet Explorer 11 STIG Version 2 Release 5 + Microsoft Edge STIG Version 2 Release 2 (Windows Server 2022 only) + Defender STIG Version 2 Release 4 **STIG-Build-Windows-High version 2025.2.x** + Windows Server 2022 STIG Version 2 Release 4 + Windows Server 2019 STIG Version 3 Release 4 + Windows Server 2016 STIG Version 2 Release 10 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 6 + Windows Firewall STIG Version 2 Release 2 + Internet Explorer 11 STIG Version 2 Release 5 + Microsoft Edge STIG Version 2 Release 2 (Windows Server 2022 only) + Defender STIG Version 2 Release 4 ### 2025 Q1 changes - 05/04/2025: Updated STIGS for Internet Explorer 11 STIG Version 2 Release 5 for all STIG components for the 2025 first quarter release. + STIG-Build-Windows-Low version 2025.1.x + STIG-Build-Windows-Medium version 2025.1.x + STIG-Build-Windows-High version 2025.1.x ### 2024 Q4 changes - 02/04/2025: Updated STIG versions and applied STIGS for the 2024 Q4 release as follows: **STIG-Build-Windows-Low version 2024.4.0** + Windows Server 2022 STIG Version 2 Release 2 + Windows Server 2019 STIG Version 3 Release 2 + Windows Server 2016 STIG Version 2 Release 9 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 2 + Windows Firewall STIG Version 2 Release 2 + Internet Explorer 11 STIG Version 2 Release 5 + Microsoft Edge STIG Version 2 Release 2 (Windows Server 2022 only) **STIG-Build-Windows-Medium version 2024.4.0** + Windows Server 2022 STIG Version 2 Release 2 + Windows Server 2019 STIG Version 3 Release 2 + Windows Server 2016 STIG Version 2 Release 9 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 2 + Windows Firewall STIG Version 2 Release 2 + Internet Explorer 11 STIG Version 2 Release 5 + Microsoft Edge STIG Version 2 Release 2 (Windows Server 2022 only) + Defender STIG Version 2 Release 4 **STIG-Build-Windows-High version 2024.4.0** + Windows Server 2022 STIG Version 2 Release 2 + Windows Server 2019 STIG Version 3 Release 2 + Windows Server 2016 STIG Version 2 Release 9 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 2 + Windows Firewall STIG Version 2 Release 2 + Internet Explorer 11 STIG Version 2 Release 5 + Microsoft Edge STIG Version 2 Release 2 (Windows Server 2022 only) + Defender STIG Version 2 Release 4 ### 2024 Q3 changes - 10/04/2023 (no changes): There were no changes for Windows component STIGS for the 2024 third quarter release. ### 2024 Q2 changes - 05/10/2024 (no changes): There were no changes for Windows component STIGS for the 2024 second quarter release. ### 2024 Q1 changes - 02/06/2024 (no changes): There were no changes for Windows component STIGS for the 2024 first quarter release. ### 2023 Q4 changes - 12/04/2023 (no changes): There were no changes for Windows component STIGS for the 2023 fourth quarter release. ### 2023 Q3 changes - 10/04/2023 (no changes): There were no changes for Windows component STIGS for the 2023 third quarter release. ### 2023 Q2 changes - 05/03/2023 (no changes): There were no changes for Windows component STIGS for the 2023 second quarter release. ### 2023 Q1 changes - 03/27/2023 (no changes): There were no changes for Windows component STIGS for the 2023 first quarter release. ### 2022 Q4 changes - 02/01/2023: Updated STIG versions and applied STIGS for the 2022 Q4 release as follows: **STIG-Build-Windows-Low version 2022.4.x** + Windows Server 2022 STIG Version 1 Release 1 + Windows Server 2019 STIG Version 2 Release 5 + Windows Server 2016 STIG Version 2 Release 5 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 2 + Windows Firewall STIG Version 2 Release 1 + Internet Explorer 11 STIG Version 2 Release 3 + Microsoft Edge STIG Version 1 Release 6 (Windows Server 2022 only) **STIG-Build-Windows-Medium version 2022.4.x** + Windows Server 2022 STIG Version 1 Release 1 + Windows Server 2019 STIG Version 2 Release 5 + Windows Server 2016 STIG Version 2 Release 5 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 2 + Windows Firewall STIG Version 2 Release 1 + Internet Explorer 11 STIG Version 2 Release 3 + Microsoft Edge STIG Version 1 Release 6 (Windows Server 2022 only) + Defender STIG Version 2 Release 4 (Windows Server 2022 only) **STIG-Build-Windows-High version 2022.4.x** + Windows Server 2022 STIG Version 1 Release 1 + Windows Server 2019 STIG Version 2 Release 5 + Windows Server 2016 STIG Version 2 Release 5 + Windows Server 2012 R2 MS STIG Version 3 Release 5 + Microsoft .NET Framework 4.0 STIG Version 2 Release 2 + Windows Firewall STIG Version 2 Release 1 + Internet Explorer 11 STIG Version 2 Release 3 + Microsoft Edge STIG Version 1 Release 6 (Windows Server 2022 only) + Defender STIG Version 2 Release 4 (Windows Server 2022 only) ### 2022 Q3 changes - 09/30/2022 (no changes): There were no changes for Windows component STIGS for the 2022 third quarter release. ### 2022 Q2 changes - 08/02/2022: Updated STIG versions and applied STIGS for the 2022 Q2 release. **STIG-Build-Windows-Low version 1.5.x** + Windows Server 2019 STIG Version 2 Release 4 + Windows Server 2016 STIG Version 2 Release 4 + Windows Server 2012 R2 MS STIG Version 3 Release 3 + Microsoft .NET Framework 4.0 STIG Version 2 Release 1 + Windows Firewall STIG Version 2 Release 1 + Internet Explorer 11 STIG Version 1 Release 19 **STIG-Build-Windows-Medium version 1.5.x** + Windows Server 2019 STIG Version 2 Release 4 + Windows Server 2016 STIG Version 2 Release 4 + Windows Server 2012 R2 MS STIG Version 3 Release 3 + Microsoft .NET Framework 4.0 STIG Version 2 Release 1 + Windows Firewall STIG Version 2 Release 1 + Internet Explorer 11 STIG Version 1 Release 19 **STIG-Build-Windows-High version 1.5.x** + Windows Server 2019 STIG Version 2 Release 4 + Windows Server 2016 STIG Version 2 Release 4 + Windows Server 2012 R2 MS STIG Version 3 Release 3 + Microsoft .NET Framework 4.0 STIG Version 2 Release 1 + Windows Firewall STIG Version 2 Release 1 + Internet Explorer 11 STIG Version 1 Release 19 ### 2022 Q1 changes - 08/02/2022 (no changes): There were no changes for Windows component STIGS for the 2022 first quarter release. ### 2021 Q4 changes - 12/20/2021: Updated STIG versions and applied STIGS for the 2021 fourth quarter release. **STIG-Build-Windows-Low version 1.5.x** + Windows Server 2019 STIG Version 2 Release 3 + Windows Server 2016 STIG Version 2 Release 3 + Windows Server 2012 R2 MS STIG Version 3 Release 3 + Microsoft .NET Framework 4.0 STIG Version 2 Release 1 + Windows Firewall STIG Version 2 Release 1 + Internet Explorer 11 STIG Version 1 Release 19 **STIG-Build-Windows-Medium version 1.5.x** + Windows Server 2019 STIG Version 2 Release 3 + Windows Server 2016 STIG Version 2 Release 3 + Windows Server 2012 R2 MS STIG Version 3 Release 3 + Microsoft .NET Framework 4.0 STIG Version 2 Release 1 + Windows Firewall STIG Version 2 Release 1 + Internet Explorer 11 STIG Version 1 Release 19 **STIG-Build-Windows-High version 1.5.x** + Windows Server 2019 STIG Version 2 Release 3 + Windows Server 2016 STIG Version 2 Release 3 + Windows Server 2012 R2 MS STIG Version 3 Release 3 + Microsoft .NET Framework 4.0 STIG Version 2 Release 1 + Windows Firewall STIG Version 2 Release 1 + Internet Explorer 11 STIG Version 1 Release 19 ### 2021 Q3 changes - 09/30/2021: Updated STIG versions and applied STIGS for the 2021 third quarter release. **STIG-Build-Windows-Low version 1.4.x** + Windows Server 2019 STIG Version 2 Release 2 + Windows Server 2016 STIG Version 2 Release 2 + Windows Server 2012 R2 MS STIG Version 3 Release 2 + Microsoft .NET Framework 4.0 STIG Version 2 Release 1 + Windows Firewall STIG Version 1 Release 7 + Internet Explorer 11 STIG Version 1 Release 19 **STIG-Build-Windows-Medium version 1.4.x** + Windows Server 2019 STIG Version 2 Release 2 + Windows Server 2016 STIG Version 2 Release 2 + Windows Server 2012 R2 MS STIG Version 3 Release 2 + Microsoft .NET Framework 4.0 STIG Version 2 Release 1 + Windows Firewall STIG Version 1 Release 7 + Internet Explorer 11 STIG Version 1 Release 19 **STIG-Build-Windows-High version 1.4.x** + Windows Server 2019 STIG Version 2 Release 2 + Windows Server 2016 STIG Version 2 Release 2 + Windows Server 2012 R2 MS STIG Version 3 Release 2 + Microsoft .NET Framework 4.0 STIG Version 2 Release 1 + Windows Firewall STIG Version 1 Release 7 + Internet Explorer 11 STIG Version 1 Release 19 ## Linux STIG hardening components This section contains information about Linux STIG hardening components, followed by a version history log. If the Linux distribution doesn’t have STIG settings of its own, the hardening component applies RHEL settings. The Linux components have optional input parameters that help you customize the following behaviors for your Linux instance. + **Level (string)**   If no value is specified, the default is `High` and will apply all aplicable Low, Medium, and High configurations. + **InstallPackages (string)**   If the value is `No`, the component does not install any additional software packages. If the value is `Yes`, the component installs additional software packages that are required for maximum compliance. The default is `No`. + **SetDoDConsentBanner (string)**   If the value is `No`, the DoD consent banner is not shown when you attach to an instance that has one of the STIG Linux components installed. If the value is `Yes`, the DoD consent banner is shown before you log in when you attach to an instance that has one of the STIG Linux components installed. You must acknowledge the banner before you can log in. The default is `No`. For an example of the consent banner, see the [Disclaimer Department of Defense Privacy and Consent Notice](https://dso.dla.mil/) that appears when you access the DLA Document Services website. The hardening component applies supported STIG settings to the infrastructure based on the Linux distribution, as follows: **Red Hat Enterprise Linux (RHEL) 7 STIG settings** + RHEL 7 + CentOS 7 + Amazon Linux 2 (AL2) **RHEL 8 STIG settings** + RHEL 8 + CentOS 8 **RHEL 9 STIG settings** + RHEL 9 + CentOS Stream 9 ### Linux STIG Low (Category III) The following list contains STIG settings that the hardening component applies to your infrastructure. If a supported setting isn't applicable for your infrastructure, the hardening component skips that setting, and moves on. For example, some STIG settings might not apply to standalone servers. Organization-specific policies can also affect which settings the hardening component applies, such as a requirement for administrators to review document settings. For a complete list, see the [STIGs Document Library](https://public.cyber.mil/stigs/downloads/?_dl_facet_stigs=operating-systems%2Cunix-linux). For information about how to view the complete list, see [STIG Viewing Tools](https://public.cyber.mil/stigs/srg-stig-tools/). **RHEL 7 STIG Version 3 Release 15** + **RHEL 7/CentOS 7/AL2** V-204452, V-204576, and V-204605 **RHEL 8 STIG Version 2 Release 6** + **RHEL 8/CentOS 8** V-230241, V-230269, V-230270, V-230281, V-230285, V-230346, V-230381, V-230395, V-230468, V-230469, V-230485, V-230486, V-230491, V-230494, V-230495, V-230496, V-230497, V-230498, V-230499, and V-244527 **RHEL 9 STIG Version 2 Release 7** + **RHEL 9/CentOS Stream 9** V-257782, V-257824, V-258138, V-258037, V-257880, V-258069, V-258076, V-258067, V-257946, V-257947, V-257795, V-257796, and V-258173 **Amazon Linux 2023 STIG Version 1 Release 2** V-274141 **SLES 12 STIG Version 3 Release 4** V-217108, V-217113, V-217140, V-217198, V-217209, V-217211, V-217212, V-217213, V-217214, V-217215, V-217216, V-217236, V-217237, V-217238, V-217239, V-217282, and V-255915 **SLES 15 STIG Version 2 Release 6** V-234811, V-234850, V-234868, V-234873, V-234905, V-234907, V-234908, V-234909, V-234933, V-234934, V-234935, V-234936, V-234955, V-234963, V-234967, and V-255921 **Ubuntu 18.04 STIG Version 2 Release 15** V-219163, V-219164, V-219165, V-219172, V-219173, V-219174, V-219175, V-219178, V-219179, V-219180, V-219210, V-219301, V-219327, V-219332, and V-219333 **Ubuntu 20.04 STIG Version 2 Release 4** V-238202, V-238203, V-238221, V-238222, V-238223, V-238224, V-238226, V-238234, V-238235, V-238237, V-238308, V-238323, V-238357, V-238362, and V-238373 **Ubuntu 22.04 STIG Version 2 Release 7** V-260472, V-260476, V-260479, V-260480, V-260481, V-260520, V-260521, V-260549, V-260550, V-260551, V-260552, V-260581, and V-260596 **Ubuntu 24.04 STIG Version 1 Release 4** V-270645, V-270646, V-270664, V-270677, V-270690, V-270695, V-270706, V-270710, V-270734, V-270749, V-270752, V-270818, and V-270820 ### Linux STIG Medium (Category II) The following list contains STIG settings that the hardening component applies to your infrastructure. If a supported setting isn't applicable for your infrastructure, the hardening component skips that setting, and moves on. For example, some STIG settings might not apply to standalone servers. Organization-specific policies can also affect which settings the hardening component applies, such as a requirement for administrators to review document settings. For a complete list, see the [STIGs Document Library](https://public.cyber.mil/stigs/downloads/?_dl_facet_stigs=operating-systems%2Cunix-linux). For information about how to view the complete list, see [STIG Viewing Tools](https://public.cyber.mil/stigs/srg-stig-tools/). **Note** The Linux STIG Medium hardening components include all listed STIG settings that AWSTOE applies for Linux STIG Low hardening components, in addition to the STIG settings that are listed specifically for Category II vulnerabilities. **RHEL 7 STIG Version 3 Release 15** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: + **RHEL 7/CentOS 7/AL2** V-204405, V-204406, V-204407, V-204408, V-204409, V-204410, V-204411, V-204412, V-204413, V-204414, V-204415, V-204416, V-204417, V-204418, V-204420, V-204422, V-204423, V-204426, V-204427, V-204431, V-204434, V-204435, V-204437, V-204449, V-204450, V-204451, V-204457, V-204466, V-204490, V-204491, V-204503, V-204507, V-204508, V-204510, V-204511, V-204512, V-204514, V-204515, V-204516, V-204517, V-204521, V-204524, V-204531, V-204536, V-204537, V-204538, V-204539, V-204540, V-204541, V-204542, V-204543, V-204544, V-204545, V-204546, V-204547, V-204548, V-204549, V-204550, V-204551, V-204552, V-204553, V-204554, V-204555, V-204556, V-204557, V-204558, V-204559, V-204560, V-204562, V-204563, V-204564, V-204565, V-204566, V-204567, V-204568, V-204572, V-204579, V-204584, V-204585, V-204587, V-204588, V-204589, V-204590, V-204591, V-204592, V-204593, V-204596, V-204597, V-204598, V-204599, V-204600, V-204601, V-204602, V-204609, V-204610, V-204611, V-204612, V-204613, V-204614, V-204615, V-204616, V-204617, V-204619, V-204622, V-204625, V-204630, V-204631, V-204633, V-233307, V-237634, V-237635, V-251703, V-255925, V-255927, V-255928, and V-256970 **RHEL 8 STIG Version 2 Release 6** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: + **RHEL 8/CentOS 8** V-230222, V-230228, V-230231, V-230233, V-230236, V-230237, V-230238, V-230239, V-230240, V-230240, V-230243, V-230244, V-230245, V-230246, V-230247, V-230248, V-230249, V-230250, V-230255, V-230256, V-230257, V-230258, V-230259, V-230260, V-230261, V-230262, V-230266, V-230267, V-230268, V-230271, V-230273, V-230275, V-230276, V-230277, V-230278, V-230279, V-230280, V-230282, V-230282, V-230286, V-230287, V-230288, V-230290, V-230291, V-230296, V-230298, V-230310, V-230311, V-230312, V-230313, V-230314, V-230315, V-230316, V-230318, V-230319, V-230320, V-230321, V-230322, V-230324, V-230325, V-230326, V-230327, V-230330, V-230332, V-230333, V-230335, V-230337, V-230339, V-230341, V-230343, V-230345, V-230347, V-230348, V-230352, V-230353, V-230354, V-230356, V-230357, V-230358, V-230359, V-230360, V-230361, V-230362, V-230363, V-230365, V-230366, V-230368, V-230369, V-230370, V-230372, V-230373, V-230375, V-230376, V-230377, V-230378, V-230380, V-230382, V-230383, V-230385, V-230386, V-230387, V-230389, V-230390, V-230392, V-230393, V-230394, V-230396, V-230397, V-230398, V-230399, V-230400, V-230401, V-230402, V-230403, V-230404, V-230405, V-230406, V-230407, V-230408, V-230409, V-230410, V-230411, V-230412, V-230413, V-230418, V-230419, V-230421, V-230422, V-230423, V-230424, V-230425, V-230426, V-230427, V-230428, V-230429, V-230430, V-230431, V-230432, V-230433, V-230434, V-230435, V-230436, V-230437, V-230438, V-230439, V-230444, V-230446, V-230447, V-230448, V-230449, V-230455, V-230456, V-230462, V-230463, V-230464, V-230465, V-230466, V-230467, V-230470, V-230471, V-230472, V-230473, V-230474, V-230475, V-230478, V-230480, V-230481, V-230482, V-230483, V-230488, V-230489, V-230493, V-230502, V-230503, V-230505, V-230506, V-230507, V-230523, V-230524, V-230525, V-230526, V-230527, V-230532, V-230535, V-230536, V-230537, V-230538, V-230539, V-230540, V-230541, V-230542, V-230543, V-230544, V-230545, V-230546, V-230547, V-230548, V-230549, V-230550, V-230555, V-230556, V-230557, V-230559, V-230560, V-230561, V-237640, V-237642, V-237643, V-244519, V-244523, V-244524, V-244525, V-244526, V-244528, V-244531, V-244533, V-244535, V-244536, V-244538, V-244539, V-244542, V-244543, V-244544, V-244545, V-244547, V-244550, V-244551, V-244552, V-244553, V-244554, V-250315, V-250315, V-250315, V-250316, V-250316, V-250317, V-251707, V-251708, V-251709, V-251710, V-251711, V-251713, V-251714, V-251715, V-251716, V-251717, V-251718, V-256974, V-257258, V-257258, V-274877, V-279929, V-279930, and V-279931 **RHEL 9 STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: + **RHEL 9/CentOS Stream 9** V-257780, V-257781, V-257783, V-257786, V-257788, V-257790, V-257791, V-257792, V-257793, V-257794, V-257797, V-257798, V-257799, V-257800, V-257801, V-257802, V-257803, V-257804, V-257805, V-257806, V-257807, V-257808, V-257809, V-257810, V-257811, V-257812, V-257813, V-257814, V-257815, V-257816, V-257817, V-257818, V-257825, V-257827, V-257828, V-257829, V-257830, V-257831, V-257832, V-257833, V-257834, V-257836, V-257838, V-257839, V-257840, V-257841, V-257842, V-257849, V-257882, V-257883, V-257884, V-257885, V-257886, V-257887, V-257888, V-257889, V-257890, V-257891, V-257892, V-257893, V-257894, V-257895, V-257896, V-257897, V-257898, V-257899, V-257900, V-257901, V-257902, V-257903, V-257904, V-257905, V-257906, V-257907, V-257908, V-257909, V-257910, V-257911, V-257912, V-257913, V-257914, V-257915, V-257916, V-257917, V-257918, V-257919, V-257920, V-257921, V-257922, V-257923, V-257924, V-257925, V-257926, V-257927, V-257928, V-257929, V-257930, V-257933, V-257934, V-257935, V-257936, V-257939, V-257940, V-257942, V-257943, V-257944, V-257948, V-257951, V-257952, V-257953, V-257954, V-257957, V-257958, V-257959, V-257960, V-257961, V-257962, V-257963, V-257964, V-257965, V-257966, V-257967, V-257968, V-257969, V-257970, V-257971, V-257972, V-257973, V-257974, V-257975, V-257976, V-257977, V-257978, V-257979, V-257980, V-257982, V-257983, V-257985, V-257987, V-257988, V-257992, V-257993, V-257994, V-257995, V-257996, V-257997, V-257998, V-257999, V-258000, V-258001, V-258002, V-258003, V-258004, V-258005, V-258006, V-258007, V-258008, V-258009, V-258010, V-258011, V-258028, V-258034, V-258035, V-258038, V-258039, V-258040, V-258041, V-258043, V-258046, V-258049, V-258052, V-258054, V-258055, V-258056, V-258057, V-258060, V-258063, V-258064, V-258065, V-258066, V-258068, V-258070, V-258071, V-258072, V-258073, V-258074, V-258075, V-258077, V-258079, V-258080, V-258081, V-258082, V-258083, V-258084, V-258085, V-258088, V-258089, V-258090, V-258091, V-258092, V-258093, V-258095, V-258097, V-258098, V-258099, V-258100, V-258101, V-258102, V-258103, V-258104, V-258105, V-258107, V-258108, V-258109, V-258110, V-258111, V-258112, V-258113, V-258114, V-258115, V-258116, V-258117, V-258118, V-258119, V-258120, V-258121, V-258122, V-258123, V-258124, V-258125, V-258126, V-258128, V-258129, V-258130, V-258133, V-258137, V-258140, V-258141, V-258142, V-258144, V-258145, V-258146, V-258147, V-258148, V-258150, V-258151, V-258152, V-258153, V-258154, V-258156, V-258157, V-258158, V-258159, V-258160, V-258161, V-258162, V-258163, V-258164, V-258165, V-258166, V-258167, V-258168, V-258169, V-258170, V-258171, V-258172, V-258175, V-258176, V-258177, V-258178, V-258179, V-258180, V-258181, V-258182, V-258183, V-258184, V-258185, V-258186, V-258187, V-258188, V-258189, V-258190, V-258191, V-258192, V-258193, V-258194, V-258195, V-258196, V-258197, V-258198, V-258199, V-258200, V-258201, V-258202, V-258203, V-258204, V-258205, V-258206, V-258207, V-258208, V-258209, V-258210, V-258211, V-258212, V-258213, V-258214, V-258215, V-258216, V-258217, V-258218, V-258219, V-258220, V-258221, V-258222, V-258223, V-258224, V-258225, V-258226, V-258227, V-258228, V-258229, V-258232, V-258233, V-258234, V-258237, V-258239, V-258240, V-270174, V-270175, V-270176, V-270177, V-272488, and V-279936 **Amazon Linux 2023 STIG Version 1 Release 2** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: V-273995, V-274000, V-274001, V-274002, V-274003, V-274004, V-274005, V-274006, V-274008, V-274009, V-274010, V-274011, V-274012, V-274013, V-274014, V-274017, V-274018, V-274019, V-274020, V-274021, V-274022, V-274023, V-274024, V-274026, V-274027, V-274028, V-274030, V-274031, V-274032, V-274033, V-274034, V-274035, V-274036, V-274037, V-274040, V-274041, V-274042, V-274044, V-274045, V-274047, V-274048, V-274049, V-274050, V-274051, V-274053, V-274054, V-274059, V-274061, V-274062, V-274069, V-274070, V-274071, V-274072, V-274073, V-274074, V-274075, V-274076, V-274077, V-274078, V-274079, V-274081, V-274082, V-274083, V-274084, V-274085, V-274086, V-274087, V-274088, V-274089, V-274090, V-274091, V-274092, V-274093, V-274094, V-274095, V-274096, V-274097, V-274098, V-274099, V-274100, V-274101, V-274102, V-274103, V-274104, V-274105, V-274106, V-274107, V-274108, V-274109, V-274110, V-274111, V-274112, V-274113, V-274114, V-274115, V-274116, V-274117, V-274119, V-274120, V-274121, V-274122, V-274123, V-274124, V-274125, V-274126, V-274127, V-274128, V-274129, V-274130, V-274131, V-274132, V-274133, V-274134, V-274135, V-274136, V-274137, V-274138, V-274139, V-274140, V-274142, V-274143, V-274144, V-274145, V-274147, V-274149, V-274151, V-274152, V-274154, V-274155, V-274156, V-274157, V-274160, V-274161, V-274162, V-274163, V-274164, V-274165, V-274166, V-274167, V-274168, V-274169, V-274170, V-274173, V-274177, V-274181, V-274182, V-274185, and V-274187 **SLES 12 STIG Version 3 Release 4** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: V-217102, V-217105, V-217105, V-217106, V-217106, V-217110, V-217116, V-217117, V-217118, V-217119, V-217120, V-217121, V-217122, V-217124, V-217125, V-217126, V-217127, V-217128, V-217130, V-217134, V-217138, V-217143, V-217147, V-217152, V-217153, V-217154, V-217155, V-217156, V-217158, V-217161, V-217163, V-217166, V-217167, V-217168, V-217169, V-217170, V-217171, V-217182, V-217183, V-217188, V-217190, V-217191, V-217194, V-217195, V-217196, V-217197, V-217200, V-217201, V-217202, V-217203, V-217204, V-217205, V-217206, V-217207, V-217208, V-217210, V-217217, V-217218, V-217223, V-217227, V-217230, V-217240, V-217241, V-217242, V-217243, V-217244, V-217245, V-217246, V-217247, V-217248, V-217249, V-217250, V-217251, V-217252, V-217253, V-217254, V-217255, V-217257, V-217258, V-217260, V-217265, V-217266, V-217267, V-217269, V-217272, V-217273, V-217274, V-217275, V-217276, V-217277, V-217278, V-217279, V-217280, V-217283, V-217284, V-217286, V-217287, V-217288, V-217289, V-217290, V-217291, V-217292, V-217293, V-217294, V-217295, V-217296, V-217299, V-217300, V-217301, V-217302, V-233308, V-237605, V-237606, V-237607, V-237608, V-237609, V-237610, V-237611, V-237612, V-237613, V-237614, V-237615, V-237616, V-237617, V-237618, V-237619, V-237620, V-237621, V-237622, V-237623, V-251720, V-251722, V-255914, and V-256981 **SLES 15 STIG Version 2 Release 6** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: V-234802, V-234807, V-234808, V-234809, V-234813, V-234815, V-234817, V-234821, V-234822, V-234823, V-234825, V-234827, V-234828, V-234829, V-234830, V-234832, V-234833, V-234834, V-234835, V-234836, V-234837, V-234838, V-234839, V-234840, V-234841, V-234842, V-234843, V-234844, V-234845, V-234848, V-234854, V-234855, V-234856, V-234857, V-234858, V-234861, V-234862, V-234863, V-234869, V-234870, V-234875, V-234878, V-234880, V-234881, V-234882, V-234883, V-234884, V-234885, V-234886, V-234887, V-234888, V-234889, V-234891, V-234895, V-234896, V-234897, V-234899, V-234900, V-234901, V-234902, V-234903, V-234904, V-234906, V-234910, V-234911, V-234912, V-234913, V-234914, V-234918, V-234924, V-234928, V-234932, V-234937, V-234938, V-234939, V-234940, V-234941, V-234942, V-234943, V-234944, V-234945, V-234946, V-234947, V-234948, V-234949, V-234950, V-234951, V-234952, V-234954, V-234956, V-234957, V-234958, V-234959, V-234961, V-234962, V-234964, V-234966, V-234969, V-234973, V-234975, V-234976, V-234977, V-234978, V-234979, V-234981, V-234982, V-234983, V-234991, V-235002, V-235003, V-235007, V-235008, V-235009, V-235010, V-235013, V-235014, V-235015, V-235016, V-235017, V-235018, V-235019, V-235020, V-235021, V-235022, V-235023, V-235024, V-235025, V-235026, V-235028, V-235029, V-235030, V-251724, V-255920, V-256983, and V-274879 **Ubuntu 18.04 STIG Version 2 Release 15** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: V-219149, V-219155, V-219156, V-219160, V-219166, V-219168, V-219176, V-219181, V-219184, V-219186, V-219188, V-219189, V-219190, V-219191, V-219192, V-219193, V-219194, V-219195, V-219196, V-219197, V-219198, V-219199, V-219200, V-219201, V-219202, V-219203, V-219204, V-219205, V-219206, V-219207, V-219208, V-219209, V-219213, V-219214, V-219215, V-219216, V-219217, V-219218, V-219219, V-219220, V-219221, V-219222, V-219223, V-219224, V-219225, V-219226, V-219227, V-219228, V-219229, V-219230, V-219231, V-219232, V-219233, V-219234, V-219235, V-219236, V-219238, V-219239, V-219240, V-219241, V-219242, V-219243, V-219244, V-219250, V-219254, V-219257, V-219263, V-219264, V-219265, V-219266, V-219267, V-219268, V-219269, V-219270, V-219271, V-219272, V-219273, V-219274, V-219275, V-219276, V-219277, V-219279, V-219281, V-219287, V-219291, V-219296, V-219297, V-219298, V-219299, V-219300, V-219303, V-219304, V-219306, V-219309, V-219310, V-219311, V-219315, V-219318, V-219319, V-219323, V-219326, V-219328, V-219330, V-219331, V-219335, V-219336, V-219337, V-219338, V-219339, V-219342, V-219344, V-233779, V-233780, and V-255906 **Ubuntu 20.04 STIG Version 2 Release 4** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: V-238200, V-238205, V-238207, V-238209, V-238210, V-238211, V-238212, V-238213, V-238220, V-238225, V-238227, V-238228, V-238229, V-238230, V-238231, V-238232, V-238236, V-238238, V-238239, V-238240, V-238241, V-238242, V-238244, V-238245, V-238246, V-238247, V-238248, V-238249, V-238250, V-238251, V-238252, V-238253, V-238254, V-238255, V-238256, V-238257, V-238258, V-238264, V-238268, V-238271, V-238277, V-238278, V-238279, V-238280, V-238281, V-238282, V-238283, V-238284, V-238285, V-238286, V-238287, V-238288, V-238289, V-238290, V-238291, V-238292, V-238293, V-238294, V-238295, V-238297, V-238298, V-238299, V-238300, V-238301, V-238302, V-238303, V-238304, V-238309, V-238310, V-238315, V-238316, V-238317, V-238318, V-238319, V-238320, V-238324, V-238325, V-238329, V-238330, V-238333, V-238334, V-238337, V-238338, V-238339, V-238340, V-238341, V-238342, V-238343, V-238344, V-238345, V-238346, V-238347, V-238348, V-238349, V-238350, V-238351, V-238352, V-238353, V-238355, V-238356, V-238359, V-238360, V-238369, V-238370, V-238371, V-238376, V-238377, V-238378, V-251505, V-255912, V-274852, and V-274853 **Ubuntu 22.04 STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: V-260471, V-260473, V-260474, V-260475, V-260475, V-260477, V-260478, V-260485, V-260486, V-260487, V-260488, V-260489, V-260490, V-260491, V-260492, V-260493, V-260494, V-260495, V-260496, V-260497, V-260498, V-260499, V-260500, V-260505, V-260506, V-260507, V-260508, V-260509, V-260510, V-260511, V-260512, V-260513, V-260514, V-260522, V-260527, V-260528, V-260530, V-260533, V-260534, V-260535, V-260537, V-260538, V-260540, V-260542, V-260543, V-260545, V-260546, V-260547, V-260553, V-260554, V-260555, V-260556, V-260557, V-260560, V-260561, V-260562, V-260563, V-260564, V-260565, V-260566, V-260567, V-260569, V-260572, V-260573, V-260574, V-260575, V-260576, V-260582, V-260584, V-260585, V-260586, V-260588, V-260589, V-260590, V-260591, V-260594, V-260597, V-260598, V-260599, V-260600, V-260601, V-260602, V-260603, V-260604, V-260605, V-260606, V-260607, V-260608, V-260609, V-260610, V-260611, V-260612, V-260613, V-260614, V-260615, V-260616, V-260617, V-260618, V-260619, V-260620, V-260621, V-260622, V-260623, V-260624, V-260625, V-260626, V-260627, V-260628, V-260629, V-260630, V-260631, V-260632, V-260633, V-260634, V-260635, V-260636, V-260637, V-260638, V-260639, V-260640, V-260641, V-260642, V-260643, V-260644, V-260645, V-260646, V-260647, V-260648, V-260649, V-274862, V-274864, and V-274866 **Ubuntu 24.04 STIG Version 1 Release 4** Includes all supported STIG settings that the hardening component applies for Category III (Low) vulnerabilities for this Linux distribution, plus: V-270649, V-270651, V-270652, V-270653, V-270654, V-270656, V-270657, V-270659, V-270660, V-270661, V-270662, V-270663, V-270669, V-270672, V-270673, V-270674, V-270676, V-270678, V-270679, V-270680, V-270681, V-270683, V-270684, V-270685, V-270686, V-270687, V-270688, V-270689, V-270692, V-270693, V-270696, V-270697, V-270698, V-270699, V-270700, V-270701, V-270702, V-270703, V-270704, V-270705, V-270709, V-270715, V-270716, V-270718, V-270720, V-270721, V-270722, V-270723, V-270724, V-270725, V-270726, V-270727, V-270728, V-270729, V-270730, V-270731, V-270732, V-270733, V-270737, V-270739, V-270740, V-270741, V-270742, V-270743, V-270746, V-270750, V-270753, V-270755, V-270756, V-270757, V-270758, V-270759, V-270760, V-270765, V-270766, V-270767, V-270768, V-270769, V-270770, V-270771, V-270772, V-270773, V-270775, V-270776, V-270777, V-270778, V-270779, V-270780, V-270781, V-270782, V-270783, V-270784, V-270785, V-270786, V-270787, V-270788, V-270789, V-270790, V-270791, V-270792, V-270793, V-270794, V-270795, V-270796, V-270797, V-270798, V-270799, V-270800, V-270801, V-270802, V-270803, V-270804, V-270805, V-270806, V-270807, V-270808, V-270809, V-270810, V-270811, V-270812, V-270813, V-270814, V-270815, V-270821, V-270822, V-270823, V-270824, V-270825, V-270826, V-270827, V-270828, V-270829, V-270830, V-270831, V-270832, V-274870, V-274871, V-274872, and V-274873 ### Linux STIG High (Category I) The following list contains STIG settings that the hardening component applies to your infrastructure. If a supported setting isn't applicable for your infrastructure, the hardening component skips that setting, and moves on. For example, some STIG settings might not apply to standalone servers. Organization-specific policies can also affect which settings the hardening component applies, such as a requirement for administrators to review document settings. For a complete list, see the [STIGs Document Library](https://public.cyber.mil/stigs/downloads/?_dl_facet_stigs=operating-systems%2Cunix-linux). For information about how to view the complete list, see [STIG Viewing Tools](https://public.cyber.mil/stigs/srg-stig-tools/). **Note** The Linux STIG High hardening components include all listed STIG settings that AWSTOE applies for Linux STIG Low and Linux STIG Medium hardening components, in addition to the listed STIG settings that apply specifically for Category I vulnerabilities. **RHEL 7 STIG Version 3 Release 15** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: + **RHEL 7/CentOS 7/AL2** V-204424, V-204425, V-204442, V-204443, V-204447, V-204448, V-204455, V-204462, V-204497, V-204497, V-204502, V-204594, V-204620, and V-204621 **RHEL 8 STIG Version 2 Release 6** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: + **RHEL 8/CentOS 8** V-230223, V-230264, V-230283, V-230284, V-230487, V-230492, V-230533, V-230558, V-244540, V-279933, V-230265, V-230226, V-230530, V-268322, V-230529, and V-230531 **RHEL 9 STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: + **RHEL 9/CentOS Stream 9** V-257820, V-257821, V-257826, V-257835, V-257955, V-257956, V-258059, V-258230, V-258238, V-257984, V-257986, V-258078, V-258094, V-258235, V-257784, and V-257785 **Amazon Linux 2023 STIG Version 1 Release 2** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: V-273996, V-273997, V-273999, V-274007, V-274038, V-274039, V-274046, V-274052, V-274057, and V-274153 **SLES 12 STIG Version 3 Release 4** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: V-217101, V-217139, V-217141, V-217142, V-217159, V-217160, V-217164, V-217264, V-217268, V-222386, and V-251721 **SLES 15 STIG Version 2 Release 6** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: V-234800, V-234804, V-234818, V-234852, V-234859, V-234860, V-234898, V-234984, V-234985, V-234988, V-234989, V-234990, V-235031, V-235032, and V-251725 **Ubuntu 18.04 STIG Version 2 Release 15** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: V-219157, V-219158, V-219177, V-219212, V-219308, V-219314, V-219316, and V-251507 **Ubuntu 20.04 STIG Version 2 Release 4** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: V-238201, V-238218, V-238219, V-238326, V-238327, V-238380, and V-251504 **Ubuntu 22.04 STIG Version 2 Release 7** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: V-260469, V-260482, V-260483, V-260523, V-260524, V-260526, V-260529, V-260539, V-260570, V-260571, V-260579, and V-279937 **Ubuntu 24.04 STIG Version 1 Release 4** Includes all supported STIG settings that the hardening component applies for Categories II and III (Medium and Low) vulnerabilities for this Linux distribution, plus: V-270647, V-270648, V-270665, V-270666, V-270708, V-270711, V-270712, V-270713, V-270714, V-270717, V-270736, V-270738, and V-279938 ## STIG version history log for Linux This section logs Linux component version history. To see the changes and published versions for a quarter, choose the title to expand the information. ### 2026 Q1 changes - 3/10/2026: Updated the following STIG versions, applied STIGs for the 2026 first quarter release for all compliance levels: **STIG-Build-Linux** + RHEL 8 STIG Version 2 Release 6 + RHEL 9 STIG Version 2 Release 7 + Amazon Linux 2023 STIG Version 1 Release 2 + SLES 12 STIG Version 3 Release 4 + SLES 15 STIG Version 2 Release 6 + Ubuntu 20.04 STIG Version 2 Release 4 + Ubuntu 22.04 STIG Version 2 Release 7 + Ubuntu 24.04 STIG Version 1 Release 4 ### 2025 Q3 changes - 09/04/2025: Added support for the SUSE Linux Enterprise Server (SLES) operating system and Amazon Linux 2023. Updated the following STIG versions and applied STIGS for the 2025 third quarter release for all compliance levels (low/medium/high): + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 4 + RHEL 9 STIG Version 2 Release 5 + Amazon Linux 2023 STIG Version 1 Release 1 + SLES 12 STIG Version 3 Release 3 + SLES 15 STIG Version 2 Release 5 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 3 + Ubuntu 22.04 STIG Version 2 Release 5 + Ubuntu 24.04 STIG Version 1 Release 2 ### 2025 Q2 changes - 06/26/2025: Updated the following STIG versions, applied STIGS for the 2025 second quarter release: **STIG-Build-Linux-Low version 2025.2.x** + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 3 + RHEL 9 STIG Version 2 Release 4 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 2 + Ubuntu 22.04 STIG Version 2 Release 4 + Ubuntu 24.04 STIG Version 1 Release 1 **STIG-Build-Linux-Medium version 2025.2.x** + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 3 + RHEL 9 STIG Version 2 Release 4 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 2 + Ubuntu 22.04 STIG Version 2 Release 4 + Ubuntu 24.04 STIG Version 1 Release 1 **STIG-Build-Linux-High version 2025.2.x** + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 3 + RHEL 9 STIG Version 2 Release 4 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 2 + Ubuntu 22.04 STIG Version 2 Release 4 + Ubuntu 24.04 STIG Version 1 Release 1 ### 2025 Q1 changes - 04/11/2025: Updated the following STIG versions, applied STIGS for the 2025 first quarter release, and added support for Ubuntu 24.04: **STIG-Build-Linux-Low version 2025.1.x** + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 2 + RHEL 9 STIG Version 2 Release 3 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 2 + Ubuntu 22.04 STIG Version 2 Release 3 + Ubuntu 24.04 STIG Version 1 Release 1 **STIG-Build-Linux-Medium version 2025.1.x** + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 2 + RHEL 9 STIG Version 2 Release 3 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 2 + Ubuntu 22.04 STIG Version 2 Release 3 + Ubuntu 24.04 STIG Version 1 Release 1 **STIG-Build-Linux-High version 2025.1.x** + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 2 + RHEL 9 STIG Version 2 Release 3 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 2 + Ubuntu 22.04 STIG Version 2 Release 3 + Ubuntu 24.04 STIG Version 1 Release 1 ### 2024 Q4 changes - 12/10/2024: Updated the following STIG versions, applied STIGS for the 2024 fourth quarter release, and added information about two new input parameters for the Linux components: **STIG-Build-Linux-Low version 2024.4.x** + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 1 + RHEL 9 STIG Version 2 Release 2 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 1 + Ubuntu 22.04 STIG Version 2 Release 2 **STIG-Build-Linux-Medium version 2024.4.x** + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 1 + RHEL 9 STIG Version 2 Release 2 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 1 + Ubuntu 22.04 STIG Version 2 Release 2 **STIG-Build-Linux-High version 2024.4.x** + RHEL 7 STIG Version 3 Release 15 + RHEL 8 STIG Version 2 Release 1 + RHEL 9 STIG Version 2 Release 2 + Ubuntu 18.04 STIG Version 2 Release 15 + Ubuntu 20.04 STIG Version 2 Release 1 + Ubuntu 22.04 STIG Version 2 Release 2 ### 2024 Q3 changes - 10/04/2024 (no changes): There were no changes for Linux component STIGS for the 2024 third quarter release. ### 2024 Q2 changes - 05/10/2024: Updated STIG versions and applied STIGS for the 2024 second quarter release. Also added support for RHEL 9, CentOS Stream 9, and Ubuntu 22.04, as follows: **STIG-Build-Linux-Low version 2024.2.x** + RHEL 7 STIG Version 3 Release 14 + RHEL 8 STIG Version 1 Release 14 + RHEL 9 STIG Version 1 Release 3 + Ubuntu 18.04 STIG Version 2 Release 14 + Ubuntu 20.04 STIG Version 1 Release 12 + Ubuntu 22.04 STIG Version 1 Release 1 **STIG-Build-Linux-Medium version 2024.2.x** + RHEL 7 STIG Version 3 Release 14 + RHEL 8 STIG Version 1 Release 14 + RHEL 9 STIG Version 1 Release 3 + Ubuntu 18.04 STIG Version 2 Release 14 + Ubuntu 20.04 STIG Version 1 Release 12 + Ubuntu 22.04 STIG Version 1 Release 1 **STIG-Build-Linux-High version 2024.2.x** + RHEL 7 STIG Version 3 Release 14 + RHEL 8 STIG Version 1 Release 14 + RHEL 9 STIG Version 1 Release 3 + Ubuntu 18.04 STIG Version 2 Release 14 + Ubuntu 20.04 STIG Version 1 Release 12 + Ubuntu 22.04 STIG Version 1 Release 1 ### 2024 Q1 changes - 02/06/2024: Updated STIG versions and applied STIGS for the 2024 first quarter release as follows: **STIG-Build-Linux-Low version 2024.1.x** + RHEL 7 STIG Version 3 Release 14 + RHEL 8 STIG Version 1 Release 13 + Ubuntu 18.04 STIG Version 2 Release 13 + Ubuntu 20.04 STIG Version 1 Release 11 **STIG-Build-Linux-Medium version 2024.1.x** + RHEL 7 STIG Version 3 Release 14 + RHEL 8 STIG Version 1 Release 13 + Ubuntu 18.04 STIG Version 2 Release 13 + Ubuntu 20.04 STIG Version 1 Release 11 **STIG-Build-Linux-High version 2024.1.x** + RHEL 7 STIG Version 3 Release 14 + RHEL 8 STIG Version 1 Release 13 + Ubuntu 18.04 STIG Version 2 Release 13 + Ubuntu 20.04 STIG Version 1 Release 11 ### 2023 Q4 changes - 12/07/2023: Updated STIG versions and applied STIGS for the 2023 fourth quarter release as follows: **STIG-Build-Linux-Low version 2023.4.x** + RHEL 7 STIG Version 3 Release 13 + RHEL 8 STIG Version 1 Release 12 + Ubuntu 18.04 STIG Version 2 Release 12 + Ubuntu 20.04 STIG Version 1 Release 10 **STIG-Build-Linux-Medium version 2023.4.x** + RHEL 7 STIG Version 3 Release 13 + RHEL 8 STIG Version 1 Release 12 + Ubuntu 18.04 STIG Version 2 Release 12 + Ubuntu 20.04 STIG Version 1 Release 10 **STIG-Build-Linux-High version 2023.4.x** + RHEL 7 STIG Version 3 Release 13 + RHEL 8 STIG Version 1 Release 12 + Ubuntu 18.04 STIG Version 2 Release 12 + Ubuntu 20.04 STIG Version 1 Release 10 ### 2023 Q3 changes - 10/04/2023: Updated STIG versions and applied STIGS for the 2023 third quarter release as follows: **STIG-Build-Linux-Low version 2023.3.x** + RHEL 7 STIG Version 3 Release 12 + RHEL 8 STIG Version 1 Release 11 + Ubuntu 18.04 STIG Version 2 Release 11 + Ubuntu 20.04 STIG Version 1 Release 9 **STIG-Build-Linux-Medium version 2023.3.x** + RHEL 7 STIG Version 3 Release 12 + RHEL 8 STIG Version 1 Release 11 + Ubuntu 18.04 STIG Version 2 Release 11 + Ubuntu 20.04 STIG Version 1 Release 9 **STIG-Build-Linux-High version 2023.3.x** + RHEL 7 STIG Version 3 Release 12 + RHEL 8 STIG Version 1 Release 11 + Ubuntu 18.04 STIG Version 2 Release 11 + Ubuntu 20.04 STIG Version 1 Release 9 ### 2023 Q2 changes - 05/03/2023: Updated STIG versions and applied STIGS for the 2023 second quarter release as follows: **STIG-Build-Linux-Low version 2023.2.x** + RHEL 7 STIG Version 3 Release 11 + RHEL 8 STIG Version 1 Release 10 + Ubuntu 18.04 STIG Version 2 Release 11 + Ubuntu 20.04 STIG Version 1 Release 8 **STIG-Build-Linux-Medium version 2023.2.x** + RHEL 7 STIG Version 3 Release 11 + RHEL 8 STIG Version 1 Release 10 + Ubuntu 18.04 STIG Version 2 Release 11 + Ubuntu 20.04 STIG Version 1 Release 8 **STIG-Build-Linux-High version 2023.2.x** + RHEL 7 STIG Version 3 Release 11 + RHEL 8 STIG Version 1 Release 10 + Ubuntu 18.04 STIG Version 2 Release 11 + Ubuntu 20.04 STIG Version 1 Release 8 ### 2023 Q1 changes - 03/27/2023: Updated STIG versions and applied STIGS for the 2023 first quarter release as follows: **STIG-Build-Linux-Low version 2023.1.x** + RHEL 7 STIG Version 3 Release 10 + RHEL 8 STIG Version 1 Release 9 + Ubuntu 18.04 STIG Version 2 Release 10 + Ubuntu 20.04 STIG Version 1 Release 7 **STIG-Build-Linux-Medium version 2023.1.x** + RHEL 7 STIG Version 3 Release 10 + RHEL 8 STIG Version 1 Release 9 + Ubuntu 18.04 STIG Version 2 Release 10 + Ubuntu 20.04 STIG Version 1 Release 7 **STIG-Build-Linux-High version 2023.1.x** + RHEL 7 STIG Version 3 Release 10 + RHEL 8 STIG Version 1 Release 9 + Ubuntu 18.04 STIG Version 2 Release 10 + Ubuntu 20.04 STIG Version 1 Release 7 ### 2022 Q4 changes - 02/01/2023: Updated STIG versions and applied STIGS for the 2022 fourth quarter release as follows: **STIG-Build-Linux-Low version 2022.4.x** + RHEL 7 STIG Version 3 Release 9 + RHEL 8 STIG Version 1 Release 8 + Ubuntu 18.04 STIG Version 2 Release 9 + Ubuntu 20.04 STIG Version 1 Release 6 **STIG-Build-Linux-Medium version 2022.4.x** + RHEL 7 STIG Version 3 Release 9 + RHEL 8 STIG Version 1 Release 8 + Ubuntu 18.04 STIG Version 2 Release 9 + Ubuntu 20.04 STIG Version 1 Release 6 **STIG-Build-Linux-High version 2022.4.x** + RHEL 7 STIG Version 3 Release 9 + RHEL 8 STIG Version 1 Release 8 + Ubuntu 18.04 STIG Version 2 Release 9 + Ubuntu 20.04 STIG Version 1 Release 6 ### 2022 Q3 changes - 09/30/2022 (no changes): There were no changes for Linux component STIGS for the 2022 third quarter release. ### 2022 Q2 changes - 08/02/2022: Introduced Ubuntu support, updated STIG versions and applied STIGS for the 2022 second quarter release as follows: **STIG-Build-Linux-Low version 2022.2.x** + RHEL 7 STIG Version 3 Release 7 + RHEL 8 STIG Version 1 Release 6 + Ubuntu 18.04 STIG Version 2 Release 6 (new) + Ubuntu 20.04 STIG Version 1 Release 4 (new) **STIG-Build-Linux-Medium version 2022.2.x** + RHEL 7 STIG Version 3 Release 7 + RHEL 8 STIG Version 1 Release 6 + Ubuntu 18.04 STIG Version 2 Release 6 (new) + Ubuntu 20.04 STIG Version 1 Release 4 (new) **STIG-Build-Linux-High version 2022.2.x** + RHEL 7 STIG Version 3 Release 7 + RHEL 8 STIG Version 1 Release 6 + Ubuntu 18.04 STIG Version 2 Release 6 (new) + Ubuntu 20.04 STIG Version 1 Release 4 (new) ### 2022 Q1 changes - 04/26/2022: Refactored to include better support for containers. Combined the previous AL2 script with RHEL 7. Updated STIG versions and applied STIGS for the 2022 first quarter release as follows: **STIG-Build-Linux-Low version 3.6.x** + RHEL 7 STIG Version 3 Release 6 + RHEL 8 STIG Version 1 Release 5 **STIG-Build-Linux-Medium version 3.6.x** + RHEL 7 STIG Version 3 Release 6 + RHEL 8 STIG Version 1 Release 5 **STIG-Build-Linux-High version 3.6.x** + RHEL 7 STIG Version 3 Release 6 + RHEL 8 STIG Version 1 Release 5 ### 2021 Q4 changes - 12/20/2021: Updated STIG versions, and applied STIGS for the 2021 fourth quarter release as follows: **STIG-Build-Linux-Low version 3.5.x** + RHEL 7 STIG Version 3 Release 5 + RHEL 8 STIG Version 1 Release 4 **STIG-Build-Linux-Medium version 3.5.x** + RHEL 7 STIG Version 3 Release 5 + RHEL 8 STIG Version 1 Release 4 **STIG-Build-Linux-High version 3.5.x** + RHEL 7 STIG Version 3 Release 5 + RHEL 8 STIG Version 1 Release 4 ### 2021 Q3 changes - 09/30/2021: Updated STIG versions, and applied STIGS for the 2021 third quarter release as follows: **STIG-Build-Linux-Low version 3.4.x** + RHEL 7 STIG Version 3 Release 4 + RHEL 8 STIG Version 1 Release 3 **STIG-Build-Linux-Medium version 3.4.x** + RHEL 7 STIG Version 3 Release 4 + RHEL 8 STIG Version 1 Release 3 **STIG-Build-Linux-High version 3.4.x** + RHEL 7 STIG Version 3 Release 4 + RHEL 8 STIG Version 1 Release 3 ## SCAP compliance validator component The Security Content Automation Protocol (SCAP) is a set of standards that IT professionals can use to identify application security vulnerabilities for compliance. The SCAP Compliance Checker (SCC) is a SCAP-validated scanning tool, released by the Naval Information Warfare Center (NIWC) Atlantic. For more information, see [Security Content Automation Protocol (SCAP) Compliance Checker (SCC)](https://www.niwcatlantic.navy.mil/Technology/SCAP/) on the *NIWC Atlantic* website. The AWSTOE `scap-compliance-checker-windows` and `scap-compliance-checker-linux` components download and install the SCC scanner on the pipeline build and test instances. When the scanner runs, it performs authenticated configuration scans using DISA SCAP Benchmarks, and provides a report that includes the following information. AWSTOE also writes the information to your application logs. + STIG settings that are applied to the instance. + An overall compliance score for the instance. We recommend that you run SCAP validation as the final step in your build process, to ensure that you report accurate compliance validation results. **Note** You can review the reports with one of the [STIG Viewing Tools](https://public.cyber.mil/stigs/srg-stig-tools/). These tools are available online via the DoD Cyber Exchange. The following sections describe the benchmarks that the SCAP validation components include. ### scap-compliance-checker-windows version 2024.03.0 The `scap-compliance-checker-windows` component runs on the EC2 instances that Image Builder creates to build and test the image. AWSTOE logs both the report and the score that the SCC application produces. The component performs the following workflow steps: 1. Downloads and installs the SCC application. 1. Imports the compliance benchmarks. 1. Runs validation using the SCC application. 1. Saves the compliance report and score locally on the build instance desktop. 1. Logs the compliance score from the local report to the AWSTOE application log files. **Note** AWSTOE currently supports SCAP compliance validation for Windows Server 2012 R2 MS, 2016, 2019, and 2022. The SCAP compliance checker component for Windows includes the following benchmarks: **SCC Version: 5.10** 2023 Q4 Benchmarks: + U\$1MS\$1Defender\$1Antivirus\$1V2R5\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1DotNet\$1Framework\$14-0\$1V2R2\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1IE11\$1V2R6\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$12012\$1and\$12012\$1R2\$1DC\$1V3R5\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$12012\$1and\$12012\$1R2\$1MS\$1V3R5\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$1Defender\$1Firewall\$1V2R3\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$1Server\$12016\$1V2R7\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$1Server\$12019\$1V3R2\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$1Server\$12022\$1V2R2\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1CAN\$1Ubuntu\$120-04\$1LTS\$1V1R10\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1RHEL\$17\$1V3R15\$1STIG\$1SCAP\$11-3\$1Benchmark + U\$1RHEL\$18\$1V1R13\$1STIG\$1SCAP\$11-3\$1Benchmark + U\$1RHEL\$19\$1V2R1\$1STIG\$1SCAP\$11-3\$1Benchmark ### scap-compliance-checker-linux version 2021.04.0 The `scap-compliance-checker-linux` component runs on the EC2 instances that Image Builder creates to build and test the image. AWSTOE logs both the report and the score that the SCC application produces. The component performs the following workflow steps: 1. Downloads and installs the SCC application. 1. Imports the compliance benchmarks. 1. Runs validation using the SCC application. 1. Saves the compliance report and score locally, in the following location on the build instance: `/opt/scc/SCCResults`. 1. Logs the compliance score from the local report to the AWSTOE application log files. **Note** AWSTOE currently supports SCAP compliance validation for RHEL 7/8 and Ubuntu 18.04/20.04. The SCC application currently supports the x86 architecture for validation. The SCAP compliance checker component for Linux includes the following benchmarks: **SCC Version: 5.10** 2023 Q4 Benchmarks: + U\$1CAN\$1Ubuntu\$120-04\$1LTS\$1V1R10\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1RHEL\$17\$1V3R15\$1STIG\$1SCAP\$11-3\$1Benchmark + U\$1RHEL\$18\$1V1R13\$1STIG\$1SCAP\$11-3\$1Benchmark + U\$1RHEL\$19\$1V2R1\$1STIG\$1SCAP\$11-3\$1Benchmark + U\$1MS\$1Defender\$1Antivirus\$1V2R5\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1DotNet\$1Framework\$14-0\$1V2R2\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1IE11\$1V2R6\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$12012\$1and\$12012\$1R2\$1DC\$1V3R5\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$12012\$1and\$12012\$1R2\$1MS\$1V3R5\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$1Defender\$1Firewall\$1V2R3\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$1Server\$12016\$1V2R7\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$1Server\$12019\$1V3R2\$1STIG\$1SCAP\$11-2\$1Benchmark + U\$1MS\$1Windows\$1Server\$12022\$1V2R2\$1STIG\$1SCAP\$11-2\$1Benchmark ### SCAP version history The following table describes important changes to the SCAP environment and settings described in this document. | Change | Description | Date | | --- | --- | --- | | 2025 Q1 SCAP Updates | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/ib-stig.html) | April 11, 2025 | | 2023 Q4 SCAP Updates | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/ib-stig.html) | December 20, 2021 | | 2023 Q3 SCAP Updates | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/ib-stig.html) | November 13, 2023 | | Added SCAP components | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/ib-stig.html) | December 20, 2021 | # Develop custom components for your Image Builder image You can create your own components to customize your Image Builder images according to your exact specifications. Use the following steps to develop custom components for your Image Builder image or container recipes. 1. If you want to develop your component document and validate it locally, you can install the AWS Task Orchestrator and Executor (AWSTOE) application and set it up on your local machine. For more information, see [Manual set up to develop custom components with AWSTOE](toe-get-started.md). 1. Create a component document that uses the AWSTOE component document framework. For more information about the document framework, see [Use the AWSTOE component document framework for custom components](toe-use-documents.md). 1. Specify your component document when you create a custom component. For more information, see [Create a custom component with Image Builder](create-component.md). **Topics** + [Create a YAML component document for custom components in Image Builder](create-component-yaml.md) + [Create a custom component with Image Builder](create-component.md) # Create a YAML component document for custom components in Image Builder To build a component, you must provide a YAML or JSON application component document. The document contains the code that runs during the phases and steps that you define to provide customization for your image. Some of the examples in this section create a build component that calls the `UpdateOS` action module in the AWSTOE component management application. The module updates the operating system. For more information about the `UpdateOS` action module, see [UpdateOS](toe-action-modules.md#action-modules-updateos). The macOS operating system example uses the `ExecuteBash` action module to install and verify the `wget` utility. The `UpdateOS` action module doesn't support macOS. For more information about the `ExecuteBash` action module, see [ExecuteBash](toe-action-modules.md#action-modules-executebash). For more information about the phases, steps, and syntax for AWSTOE application component documents, see [Use documents in AWSTOE](https://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-use-documents.html). **Note** Image Builder determines the component type from the phases that are defined in the component document as follows: **Build** – This is the default component type. Anything that is not classified as a test component, is a build component. This type of component runs during the image *Build stage*. If this build component has a `test` phase defined, that phase runs during the *Test stage*. **Test** – To qualify as a test component, the component document must include only one phase, named `test`. For tests that are related to build component configurations, we recommend that you don't use a standalone test component. Rather, use the `test` phase in the associated build component. For more information about how Image Builder uses stages and phases to manage component workflow in its build process, see [Use components to customize your Image Builder image](manage-components.md). To create a YAML application component document for a sample application, follow the steps on the tab that matches your image operating system. ------ #### [ Linux ] **Create a YAML component file** Use a file editing tool to create your component document. Documentation examples use a file named `update-linux-os.yaml`, with the following content: ``` # Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: MIT-0 # # Permission is hereby granted, free of charge, to any person obtaining a copy of this # software and associated documentation files (the "Software"), to deal in the Software # without restriction, including without limitation the rights to use, copy, modify, # merge, publish, distribute, sublicense, and/or sell copies of the Software, and to # permit persons to whom the Software is furnished to do so. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, # INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A # PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. name: update-linux-os description: Updates Linux with the latest security updates. schemaVersion: 1 phases: - name: build steps: - name: UpdateOS action: UpdateOS # Document End ``` **Tip** Use a tool like this online [YAML Validator](https://jsonformatter.org/yaml-validator), or a YAML lint extension in your code environment to verify that your YAML is well-formed. ------ #### [ Windows ] **Create a YAML component file** Use a file editing tool to create your component document. Documentation examples use a file named `update-windows-os.yaml`, with the following content: ``` # Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: MIT-0 # # Permission is hereby granted, free of charge, to any person obtaining a copy of this # software and associated documentation files (the "Software"), to deal in the Software # without restriction, including without limitation the rights to use, copy, modify, # merge, publish, distribute, sublicense, and/or sell copies of the Software, and to # permit persons to whom the Software is furnished to do so. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, # INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A # PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. name: update-windows-os description: Updates Windows with the latest security updates. schemaVersion: 1.0 phases: - name: build steps: - name: UpdateOS action: UpdateOS # Document End ``` **Tip** Use a tool like this online [YAML Validator](https://jsonformatter.org/yaml-validator), or a YAML lint extension in your code environment to verify that your YAML is well-formed. ------ #### [ macOS ] **Create a YAML component file** Use a file editing tool to create your component document. Documentation examples use a file named `wget-macos.yaml`, with the following content: ``` name: WgetInstallDocument description: This is wget installation document. schemaVersion: 1.0 phases: - name: build steps: - name: WgetBuildStep action: ExecuteBash inputs: commands: - | PATH=/usr/local/bin:$PATH sudo -u ec2-user brew install wget - name: validate steps: - name: WgetValidateStep action: ExecuteBash inputs: commands: - | function error_exit { echo $1 echo "{\"failureMessage\":\"$2\"}" exit 1 } type wget if [ $? -ne 0 ]; then error_exit "$stderr" "Wget installation failed!" fi - name: test steps: - name: WgetTestStep action: ExecuteBash inputs: commands: - wget -h ``` **Tip** Use a tool like this online [YAML Validator](https://jsonformatter.org/yaml-validator), or a YAML lint extension in your code environment to verify that your YAML is well-formed. ------ # Create a custom component with Image Builder After you've completed your component document, you can use it to create a custom component that your Image Builder recipes can use. You can create a custom component from the Image Builder console, from the API or SDKs, or from the command line. For more information about how to create a custom component with input parameters and use it in your recipes, see [Tutorial: Create a custom component with input parameters](tutorial-component-parameters.md). The following sections show you how to create components from the console or from the AWS CLI. **Topics** + [Create a custom component from the console](#create-component-ib-console) + [Create a custom component from the AWS CLI](#create-component-ib-cli) + [Import a script to create a component from the AWS CLI](#import-component-cli) + [Automatic build version management](#auto-build-version-management) + [Using version references](#using-version-references) ## Create a custom component from the console To create an AWSTOE application component from the Image Builder console, follow these steps: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Select **Components** from the navigation pane. Then select **Create component**. 1. On the **Create component** page, under **Component details**, enter the following: 1. **Image Operating system (OS)**. Specify the operating system that the component is compatible with. 1. **Component category**. From the dropdown, select the type of build or test component that you are creating. 1. **Component name**. Enter a name for the component. 1. **Component version**. Enter the version number of the component. 1. **Description**. Provide an optional description to help you identify the component. 1. **Change description**. Provide an optional description to help you understand the changes made to this version of the component. 1. In the **Definition document** section, the default option is **Define document content**. The component document defines the actions that Image Builder performs on the build and test instances to create your image. In the **Content** box, enter your YAML component document content. To start with a *Hello World* example for Linux, choose the **Use example** option. To learn more about how to create a YAML component document, or to copy and paste the *UpdateOS* example from that page, see [Create a YAML component document for custom components in Image Builder](create-component-yaml.md). 1. After you enter the component details, select **Create component**. **Note** To see your new component when you create or update a recipe, apply the **Owned by me** filter to the build or test component list. The filter is located at the top of the component list, next to the search box. 1. To delete a component, from the **Components** page, select the check box next to the component that you want to delete. From the **Actions** dropdown, select **Delete component**. **Update a component** To create a new component version, follow these steps: 1. Depending on where you start: + From the **Components** list page – Select the check box next to the component name, then select **Create new version** from the **Actions** menu. + From the component detail page – Choose the **Create new version** button in the upper right corner of the heading. 1. The component information is already populated with the current values when the **Create Component** page displays. Follow the create a component steps to update the component. This ensures that you enter a unique semantic version in the **Component version**. To learn more about semantic versioning for Image Builder resources, see [Semantic versioning in Image Builder](ibhow-semantic-versioning.md). ## Create a custom component from the AWS CLI In this section, you'll learn how to set up and use Image Builder commands in the AWS CLI to create an AWSTOE application component, as follows. + Upload your YAML component document to an S3 bucket that you can reference from the command line. + Create the AWSTOE application component with the **create-component** command. + List component versions with the **list-components** command and a name filter to see what versions already exist. You can use the output to determine what the next version should be for updates. To create an AWSTOE application component from an input YAML document, follow the steps that match your image operating system platform. ------ #### [ Linux ] **Store your application component document in Amazon S3** You can use an S3 bucket as a repository for your AWSTOE application component source document. To store your component document, follow these steps: + **Upload the document to Amazon S3** *If your document is smaller than 64 KB, you can skip this step.* Documents that are 64 KB or larger in size must be stored in Amazon S3. ``` aws s3 cp update-linux-os.yaml s3://amzn-s3-demo-destination-bucket/my-path/update-linux-os.yaml ``` **Create a component from the YAML document** To streamline the **create-component** command that you use in the AWS CLI, create a JSON file that contains all of the component parameters that you want to pass into the command. Include the location of the `update-linux-os.yaml` document that you created earlier. The `uri` key-value pair contains the file reference. **Note** The naming convention for the data values in the JSON file follows the pattern that is specified for the Image Builder API operation request parameters. To review the API command request parameters, see the [CreateComponent](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateComponent.html) command in the *EC2 Image Builder API Reference*. To provide the data values as command line parameters, refer to the parameter names specified in the *AWS CLI Command Reference*. 1. **Create a CLI input JSON file** Use a file editing tool to create a file named `create-update-linux-os-component.json`. Include the following content: ``` { "name": "update-linux-os", "semanticVersion": "1.1.2", "description": "An example component that updates the Linux operating system", "changeDescription": "Initial version.", "platform": "Linux", "uri": "s3://amzn-s3-demo-destination-bucket/my-path/update-linux-os.yaml", "kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/98765432-b123-456b-7f89-0123456f789c", "tags": { "MyTagKey-purpose": "security-updates" } } ``` 1. **Create the component** Use the following command to create the component, referencing the file name for the JSON file that you created in the prior step: ``` aws imagebuilder create-component --cli-input-json file://create-update-linux-os-component.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). ------ #### [ Windows ] **Store your application component document in Amazon S3** You can use an S3 bucket as a repository for your AWSTOE application component source document. To store your component document, follow these steps: + **Upload the document to Amazon S3** *If your document is smaller than 64 KB, you can skip this step.* Documents that are 64 KB or larger in size must be stored in Amazon S3. ``` aws s3 cp update-windows-os.yaml s3://amzn-s3-demo-destination-bucket/my-path/update-windows-os.yaml ``` **Create a component from the YAML document** To streamline the **create-component** command that you use in the AWS CLI, create a JSON file that contains all of the component parameters that you want to pass into the command. Include the location of the `update-windows-os.yaml` document that you created earlier. The `uri` key-value pair contains the file reference. **Note** The naming convention for the data values in the JSON file follows the pattern that is specified for the Image Builder API operation request parameters. To review the API command request parameters, see the [CreateComponent](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateComponent.html) command in the *EC2 Image Builder API Reference*. To provide the data values as command line parameters, refer to the parameter names specified in the *AWS CLI Command Reference*.. 1. **Create a CLI input JSON file** Use a file editing tool to create a file named `create-update-windows-os-component.json`. Include the following content: ``` { "name": "update-windows-os", "semanticVersion": "1.1.2", "description": "An example component that updates the Windows operating system.", "changeDescription": "Initial version.", "platform": "Windows", "uri": "s3://amzn-s3-demo-destination-bucket/my-path/update-windows-os.yaml", "kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/98765432-b123-456b-7f89-0123456f789c", "tags": { "MyTagKey-purpose": "security-updates" } } ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). 1. **Create the component** Use the following command to create the component, referencing the file name for the JSON file that you created in the prior step: ``` aws imagebuilder create-component --cli-input-json file://create-update-windows-os-component.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). ------ #### [ macOS ] **Store your application component document in Amazon S3** You can use an S3 bucket as a repository for your AWSTOE application component source document. To store your component document, follow these steps: + **Upload the document to Amazon S3** *If your document is smaller than 64 KB, you can skip this step.* Documents that are 64 KB or larger in size must be stored in Amazon S3. ``` aws s3 cp wget-macos.yaml s3://amzn-s3-demo-destination-bucket/my-path/wget-macos.yaml ``` **Create a component from the YAML document** To streamline the **create-component** command that you use in the AWS CLI, create a JSON file that contains all of the component parameters that you want to pass into the command. Include the location of the `wget-macos.yaml` document that you created earlier. The `uri` key-value pair contains the file reference. **Note** The naming convention for the data values in the JSON file follows the pattern that is specified for the Image Builder API operation request parameters. To review the API command request parameters, see the [CreateComponent](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateComponent.html) command in the *EC2 Image Builder API Reference*. To provide the data values as command line parameters, refer to the parameter names specified in the *AWS CLI Command Reference*. 1. **Create a CLI input JSON file** Use a file editing tool to create a file named `install-wget-macos-component.json`. Include the following content: ``` { "name": "install install-wget-macos-component", "semanticVersion": "1.1.2", "description": "An example component that installs and verifies the wget utility on macOS.", "changeDescription": "Initial version.", "platform": "macOS", "uri": "s3://amzn-s3-demo-destination-bucket/my-path/wget-macos.yaml", "kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/98765432-b123-456b-7f89-0123456f789c", "tags": { "MyTagKey-purpose": "install-software" } } ``` 1. **Create the component** Use the following command to create the component, referencing the file name for the JSON file that you created in the prior step: ``` aws imagebuilder create-component --cli-input-json file://install-wget-macos-component.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). ------ ### AWSTOE component versioning for updates from the AWS CLI AWSTOE component names and versions are embedded in the component's Amazon Resource Name (ARN), after the component prefix. Each new version of a component has its own unique ARN. The steps to create a new version are exactly the same as the steps to create a new component, as long as the semantic version is unique for that component name. To learn more about semantic versioning for Image Builder resources, see [Semantic versioning in Image Builder](ibhow-semantic-versioning.md). To ensure that you assign the next logical version, first get a list of the existing versions for the component that you want to change. Use the **list-components** command with the AWS CLI, and filter on the name. In this example, you filter on the name of the component that you created in the prior Linux examples. To list the component that you created, use the value of the `name` parameter from the JSON file that you used in the **create-component** command. ``` aws imagebuilder list-components --filters name="name",values="update-linux-os" { "requestId": "123a4567-b890-123c-45d6-ef789ab0cd1e", "componentVersionList": [ { "arn": "arn:aws:imagebuilder:us-west-2:1234560087789012:component/update-linux-os/1.0.0", "name": "update-linux-os", "version": "1.0.0", "platform": "Linux", "type": "BUILD", "owner": "123456789012", "dateCreated": "2020-09-24T16:58:24.444Z" }, { "arn": "arn:aws:imagebuilder:us-west-2:1234560087789012:component/update-linux-os/1.0.1", "name": "update-linux-os", "version": "1.0.1", "platform": "Linux", "type": "BUILD", "owner": "123456789012", "dateCreated": "2021-07-10T03:38:46.091Z" } ] } ``` Based on your results, you can determine what the next version should be. ## Import a script to create a component from the AWS CLI For some scenarios, it might be easier to start with a pre-existing script. For this scenario, you can use the following example. This example assumes that you have a file called `import-component.json` (as shown). Note that the file directly references a PowerShell script called `AdminConfig.ps1` that is already uploaded to `amzn-s3-demo-source-bucket`. Currently, `SHELL` is supported for the component `format`. ``` { "name": "MyImportedComponent", "semanticVersion": "1.0.0", "description": "An example of how to import a component", "changeDescription": "First commit message.", "format": "SHELL", "platform": "Windows", "type": "BUILD", "uri": "s3://amzn-s3-demo-source-bucket/AdminConfig.ps1", "kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/60763706-b131-418b-8f85-3420912f020c" } ``` To create the component from an imported script, run the following command. ``` aws imagebuilder import-component --cli-input-json file://import-component.json ``` ## Automatic build version management When you create a component with the same name and semantic version as an existing component, Image Builder automatically increments the build version (for example, from `/1` to `/2`, to `/3`, and so on). This allows you to make iterative updates to your components without manually managing version numbers, which is especially useful in CI/CD pipelines and infrastructure-as-code deployments. If the component content is identical to the previous build version, Image Builder returns `ResourceAlreadyExistsException` to prevent duplicate components from consuming your service quota. ## Using version references When you create or retrieve a component, Image Builder automatically provides pre-constructed ARNs with wildcard version patterns in the latestVersionReferences object. These references make it easy to use the latest versions of your components in recipes and pipelines without manually parsing ARNs. **Choosing the right version reference** + latestVersionArn (x.x.x) - Always use the absolute latest component version. + atestMajorVersionArn (1.x.x) - Use the latest minor and patch versions within a major version. + latestMinorVersionArn (1.2.x) - Use the latest patch version only. + latestPatchVersionArn (1.2.3) - Reference a specific semantic version, but get the latest build version. **Note** To avoid unexpected charges, make sure to clean up resources and pipelines that you created from the examples in this guide. For more information about deleting resources in Image Builder, see [Delete outdated or unused Image Builder resources](delete-resources.md). # How Image Builder uses the AWS Task Orchestrator and Executor application to manage components EC2 Image Builder uses the AWS Task Orchestrator and Executor (AWSTOE) application to orchestrate complex workflows, modify system configurations, and test your images without the need for additional devops scripts or code. This application manages and runs components that implement its declarative document schema. AWSTOE is a standalone application that Image Builder installs on its build and test instances when you create an image. You can also install it manually on EC2 instances to create your own custom components. It doesn't require any additional setup, and can also run on premises. **Topics** + [AWSTOE downloads](#toe-downloads) + [Supported Regions](#toe-supported-regions) + [AWSTOE command reference](#toe-commands) + [Manual set up to develop custom components with AWSTOE](toe-get-started.md) + [Use the AWSTOE component document framework for custom components](toe-use-documents.md) + [Action modules supported by AWSTOE component manager](toe-action-modules.md) + [Configure input for the AWSTOE run command](toe-run-config-input.md) ## AWSTOE downloads To install AWSTOE, choose the download link for your architecture and platform. If you attach to a VPC endpoint for your service (Image Builder, for example), it must have a custom endpoint policy attached that includes access to the S3 bucket for AWSTOE downloads. Otherwise, your build and test instances will not be able to download the bootstrap script (`bootstrap.sh`) and install the AWSTOE application. For more information see [Create a VPC endpoint policy for Image Builder](vpc-interface-endpoints.md#vpc-endpoint-policy). **Important** AWS is phasing out support for TLS versions 1.0 and 1.1. To access the S3 bucket for AWSTOE downloads, your client software must use TLS version 1.2 or later. For more information, see this [AWS Security Blog post](https://aws.amazon.com/blogs/security/tls-1-2-required-for-aws-endpoints/). | Architecture | Platform | Download link | Example | | --- | --- | --- | --- | | 386 | AL 2 and 2023 RHEL 7, 8, and 9 Ubuntu 16.04, 18.04, 20.04, 22.04, and 24.04 CentOS 7 and 8 SUSE 12 and 15 | `https://awstoe-.s3..amazonaws.com/latest/linux/386/awstoe` | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/386/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/386/awstoe) | | AMD64 | AL 2 and 2023 RHEL 7, 8, and 9 Ubuntu 16.04, 18.04, 20.04, 22.04, and 24.04 CentOS 7 and 8 CentOS Stream 8 SUSE 12 and 15 | https://awstoe-.s3..amazonaws.com/latest/linux/amd64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe) | | AMD64 | macOS 10.14.x (Mojave), 10.15.x (Catalina), 11.x (Big Sur), 12.x (Monterey) | https://awstoe-region.s3.region.amazonaws.com/latest/darwin/amd64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/darwin/amd64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/darwin/amd64/awstoe) | | AMD64 | Windows Server 2012 R2, 2016, 2019, and 2022 | `https://awstoe-.s3..amazonaws.com/latest/windows/amd64/awstoe.exe` | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/windows/amd64/awstoe.exe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/windows/amd64/awstoe.exe) | | ARM64 | AL 2 and 2023 RHEL 7, 8, and 9 Ubuntu 16.04, 18.04, 20.04, 22.04, and 24.04 CentOS 7 and 8 CentOS Stream 8 SUSE 12 and 15 | https://awstoe-.s3..amazonaws.com/latest/linux/arm64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/arm64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/arm64/awstoe) | ## Supported Regions AWSTOE is supported as a standalone application in the following Regions. | AWS Region name | AWS Region | | --- | --- | | US East (Ohio) | us-east-2 | | US East (N. Virginia) | us-east-1 | | AWS GovCloud (US-East) | us-gov-east-1 | | AWS GovCloud (US-West) | us-gov-west-1 | | US West (N. California) | us-west-1 | | US West (Oregon) | us-west-2 | | Africa (Cape Town) | af-south-1 | | Asia Pacific (Hong Kong) | ap-east-1 | | Asia Pacific (Osaka) | ap-northeast-3 | | Asia Pacific (Seoul) | ap-northeast-2 | | Asia Pacific (Mumbai) | ap-south-1 | | Asia Pacific (Hyderabad) | ap-south-2 | | Asia Pacific (Singapore) | ap-southeast-1 | | Asia Pacific (Sydney) | ap-southeast-2 | | Asia Pacific (Jakarta) | ap-southeast-3 | | Asia Pacific (Tokyo) | ap-northeast-1 | | Canada (Central) | ca-central-1 | | Europe (Frankfurt) | eu-central-1 | | Europe (Zurich) | eu-central-2 | | Europe (Stockholm) | eu-north-1 | | Europe (Milan) | eu-south-1 | | Europe (Spain) | eu-south-2 | | Europe (Ireland) | eu-west-1 | | Europe (London) | eu-west-2 | | Europe (Paris) | eu-west-3 | | Israel (Tel Aviv) | il-central-1 | | Middle East (UAE) | me-central-1 | | Middle East (Bahrain) | me-south-1 | | South America (São Paulo) | sa-east-1 | | China (Beijing) | cn-north-1 | | China (Ningxia) | cn-northwest-1 | ## AWSTOE command reference AWSTOE is a command line component management application that runs on Amazon EC2 instances. When Image Builder launches an EC2 build or test instance, it installs AWSTOE on the instance. Then it runs AWSTOE commands in the AWS CLI to install or validate the components that are specified in the image or container recipe. **Note** Some AWSTOE action modules require elevated permissions to run on a Linux server. To use elevated permissions, prefix the command syntax with **sudo**, or run the **sudo su** command one time when you log in before running the commands linked below. For more information about AWSTOE action modules, see [Action modules supported by AWSTOE component manager](toe-action-modules.md). ***[run](#cmd-run)*** Use the **run** command to run the YAML document scripts for one or more component documents. ***[validate](#cmd-validate)*** Run the **validate** command to validate the YAML document syntax for one or more component documents. ### awstoe run command This command runs the YAML component document scripts in the order in which they are included in the configuration file specified by the `--config` parameter, or the list of component documents specified by the `--documents` parameter. **Note** You must specify exactly one of the following parameters, never both: --config --documents #### Syntax ``` awstoe run [--config ] [--cw-ignore-failures ] [--cw-log-group ] [--cw-log-region us-west-2] [--cw-log-stream ] [--document-s3-bucket-owner ] [--documents ] [--execution-id ] [--log-directory ] [--log-s3-bucket-name ] [--log-s3-bucket-owner ] [--log-s3-key-prefix ] [--parameters name1=value1,name2=value2...] [--phases ] [--state-directory ] [--version ] [--help] [--trace] ``` #### Parameters and options Parameters **--config *`./config-example.json`*** Short form: -c *`./config-example.json`* The configuration file *(conditional)*. This parameter contains the file location for the JSON file that contains configuration settings for the components this command is running. If you specify **run** command settings in a configuration file, you must not specify the `--documents` parameter. For more information about input configuration, see [Configure input for the AWSTOE run command](toe-run-config-input.md). Valid locations include: + A local file path (*`./config-example.json`*) + An S3 URI (`s3://bucket/key`) **--cw-ignore-failures** Short form: N/A Ignore logging failures from the CloudWatch Logs. **--cw-log-group** Short form: N/A The `LogGroup` name for the CloudWatch Logs. **--cw-log-region** Short form: N/A The AWS Region that applies to the CloudWatch Logs. **--cw-log-stream** Short form: N/A The `LogStream` name for the CloudWatch Logs, that directs AWSTOE where to stream the `console.log` file. **--document-s3-bucket-owner** Short form: N/A The account ID of the bucket owner for S3 URI-based documents. **--documents *`./doc-1.yaml`,`./doc-n.yaml`*** Short form: -d *`./doc-1.yaml`*,*`./doc-n`* The component documents *(conditional)*. This parameter contains a comma-separated list of file locations for the YAML component documents to run. If you specify YAML documents for the **run** command using the `--documents` parameter, you must not specify the `--config` parameter. Valid locations include: + local file paths (*./component-doc-example.yaml*). + S3 URIs (`s3://bucket/key`). + Image Builder component build version ARNs (arn:aws:imagebuilder:us-west-*2:123456789012*:component/*my-example-component*/2021.12.02/1). There are no spaces between items in the list, only commas. **--execution-id** Short form: -i This is the unique ID that applies to the execution of the current **run** command. This ID is included in output and log file names, to uniquely identify those files, and link them to the current command execution. If this setting is left out, AWSTOE generates a GUID. **--log-directory** Short form: -l The destination directory where AWSTOE stores all of the log files from this command execution. By default, this directory is located inside of the following parent directory: `TOE__`. If you do not specify the log directory, AWSTOE uses the current working directory (`.`). **--log-s3-bucket-name** Short form: -b If component logs are stored in Amazon S3 (recommended), AWSTOE uploads the component application logs to the S3 bucket named in this parameter. **--log-s3-bucket-owner** Short form: N/A If component logs are stored in Amazon S3 (recommended), this is the owner account ID for the bucket where AWSTOE writes the log files. **--log-s3-key-prefix** Short form: -k If component logs are stored in Amazon S3 (recommended), this is the S3 object key prefix for the log location in the bucket. **--parameters *name1*=*value1*,*name2*=*value2*...** Short form: N/A Parameters are mutable variables that are defined in the component document, with settings that the calling application can provide at runtime. **--phases** Short form: -p A comma-separated list that specifies which phases to run from the YAML component documents. If a component document includes additional phases, those will not run. **--state-directory** Short form: -s The file path where state tracking files are stored. **--version** Short form: -v Specifies the component application version.Options **--help** Short form: -h Displays a help manual for using the component management application options. **--trace** Short form: -t Enables verbose logging to the console. ### awstoe validate command When you run this command, it validates the YAML document syntax for each of the component documents specified by the `--documents` parameter. #### Syntax ``` awstoe validate [--document-s3-bucket-owner ] --documents [--help] [--trace] ``` #### Parameters and options Parameters **--document-s3-bucket-owner** Short form: N/A Source account ID of S3 URI-based documents provided. **--documents *`./doc-1.yaml`,`./doc-n.yaml`*** Short form: -d *`./doc-1.yaml`*,*`./doc-n`* The component documents *(required)*. This parameter contains a comma-separated list of file locations for the YAML component documents to run. Valid locations include: + local file paths (*./component-doc-example.yaml*) + S3 URIs (`s3://bucket/key`) + Image Builder component build version ARNs (arn:aws:imagebuilder:us-west-*2:123456789012*:component/*my-example-component*/2021.12.02/1) There are no spaces between items in the list, only commas.Options **--help** Short form: -h Displays a help manual for using the component management application options. **--trace** Short form: -t Enables verbose logging to the console. # Manual set up to develop custom components with AWSTOE The AWS Task Orchestrator and Executor (AWSTOE) application is a standalone application that creates, validates, and runs commands within a component definition framework. AWS services can use AWSTOE to orchestrate workflows, install software, modify system configurations, and test image builds. Follow these steps to manually install the AWSTOE application and use it as a stand-alone application to develop custom components. Image Builder takes care of these steps for you, if you use the Image Builder console or AWS CLI commands to create custom components. For more information, see [Create custom components with Image Builder](create-component.md). # Verify the signature of the AWSTOE installation download This section describes the recommended process for verifying the validity of the installation download for AWSTOE on Linux, macOS and Windows based operating systems. **Topics** + [Verify the signature of the AWSTOE installation download on Linux or macOS](#awstoe-verify-sig-linux) + [Verify the signature of the AWSTOE installation download on Windows](#awstoe-verify-sig-win) ## Verify the signature of the AWSTOE installation download on Linux or macOS This topic describes the recommended process for verifying the validity of the installation download for the AWSTOE on Linux-based or macOS operating systems. Whenever you download an application from the internet, we recommend that you authenticate the identity of the software publisher. Also, check that the application is not altered or corrupted since it was published. This protects you from installing a version of the application that contains a virus or other malicious code. If, after running the steps in this topic, you determine that the software for the AWSTOE application is altered or corrupted, do not run the installation file. Instead, contact Support For more information about your support options, see [Support](https://aws.amazon.com/premiumsupport/). AWSTOE files for Linux-based and macOS operating systems are signed using `GnuPG`, an open source implementation of the Pretty Good Privacy (OpenPGP) standard for secure digital signatures. `GnuPG` (also known as `GPG`) provides authentication and integrity checking through a digital signature. Amazon EC2 publishes a public key and signatures that you can use to verify the downloaded Amazon EC2 CLI tools. For more information about `PGP` and `GnuPG` (`GPG`), see [http://www.gnupg.org](https://www.gnupg.org/). The first step is to establish trust with the software publisher. Download the public key of the software publisher, check that the owner of the public key is who they claim to be, and then add the public key to your *keyring*. Your keyring is a collection of known public keys. After you establish the authenticity of the public key, you can use it to verify the signature of the application. **Topics** + [Installing the GPG tools](#awstoe-verify-signature-of-binary-download-install-tools) + [Authenticating and importing the public key](#awstoe-verify-signature-of-binary-download-authenticate-import-public-key) + [Verify the signature of the package](#awstoe-verify-signature-of-binary-package) ### Installing the GPG tools If your operating system is Linux, Unix, or macOS, the GPG tools are likely already installed. To test whether the tools are installed on your system, type **gpg** at a command prompt. If the GPG tools are installed, you see a GPG command prompt. If the GPG tools are not installed, you see an error message stating that the command cannot be found. You can install the GnuPG package from a repository. To install GPG tools, select the operating system that matches your instance. ------ #### [ Debian-based Linux ] From a terminal, run the following command: ``` apt-get install gnupg ``` ------ #### [ Red Hat–based Linux ] From a terminal, run the following command: ``` yum install gnupg ``` ------ #### [ macOS ] From a terminal, run the following command: ``` brew install gnupg ``` ------ ### Authenticating and importing the public key The next step in the process is to authenticate the AWSTOE public key and add it as a trusted key in your `GPG` keyring. **To authenticate and import the AWSTOE public key** 1. Obtain a copy of our public `GPG` build key by doing one of the following: + Download the key from https://awstoe-****.s3.****.amazonaws.com/assets/awstoe.gpg. For example, [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/assets/awstoe.gpg](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/assets/awstoe.gpg). + Copy the key from the following text and paste it into a file called `awstoe.gpg`. Make sure to include everything that follows: ``` -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v2 mQENBF8UqwsBCACdiRF2bkZYaFSDPFC+LIkWLwFvtUCRwAHtD8KIwTJ6LVn3fHAU GhuK0ZH9mRrqRT2bq/xJjGsnF9VqTj2AJqndGJdDjz75YCZYM+ocZ+r5HSJaeW9i S5dykHj7Txti2zHe0G5+W0v7v5bPi2sPHsN7XWQ7+G2AMEPTz8PjxY//I0DvMQns Sle3l9hz6wCClz1l9LbBzTyHfSm5ucTXvNe88XX5Gmt37OCDM7vfli0Ctv8WFoLN 6jbxuA/sV71yIkPm9IYp3+GvaKeT870+sn8/JOOKE/U4sJV1ppbqmuUzDfhrZUaw 8eW8IN9A1FTIuWiZED/5L83UZuQs1S7s2PjlABEBAAG0GkFXU1RPRSA8YXdzdG9l QGFtYXpvbi5jb20+iQE5BBMBCAAjBQJfFKsLAhsDBwsJCAcDAgEGFQgCCQoLBBYC AwECHgECF4AACgkQ3r3BVvWuvFJGiwf9EVmrBR77+Qe/DUeXZJYoaFr7If/fVDZl 6V3TC6p0J0Veme7uXleRUTFOjzbh+7e5sDX19HrnPquzCnzfMiqbp4lSoeUuNdOf FcpuTCQH+M+sIEIgPno4PLl0Uj2uE1o++mxmonBl/Krk+hly8hB2L/9n/vW3L7BN OMb1Ll9PmgGPbWipcT8KRdz4SUex9TXGYzjlWb3jU3uXetdaQY1M3kVKE1siRsRN YYDtpcjmwbhjpu4xm19aFqNoAHCDctEsXJA/mkU3erwIRocPyjAZE2dnlkL9ZkFZ z9DQkcIarbCnybDM5lemBbdhXJ6hezJE/b17VA0t1fY04MoEkn6oJg== =oyze -----END PGP PUBLIC KEY BLOCK----- ``` 1. At a command prompt in the directory where you saved **awstoe.gpg**, use the following command to import the AWSTOE public key into your keyring. ``` gpg --import awstoe.gpg ``` The command returns results that are similar to the following: ``` gpg: key F5AEBC52: public key "AWSTOE " imported gpg: Total number processed: 1 gpg: imported: 1 (RSA: 1) ``` Make a note of the key value; you need it in the next step. In the preceding example, the key value is `F5AEBC52`. 1. Verify the fingerprint by running the following command, replacing *key-value* with the value from the preceding step: ``` gpg --fingerprint key-value ``` This command returns results similar to the following: ``` pub 2048R/F5AEBC52 2020-07-19 Key fingerprint = F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52 uid [ unknown] AWSTOE ``` Additionally, the fingerprint string should be identical to `F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52`, as shown in the preceding example. Compare the key fingerprint that is returned to the one published on this page. They should match. If they don't match, do not install the AWSTOE installation script, and contact Support. ### Verify the signature of the package After you install the `GPG` tools, authenticate and import the AWSTOE public key, and verify that the public key is trusted, you are ready to verify the signature of the installation script. **To verify the installation script signature** 1. At a command prompt, run the following command to download the application binary: ``` curl -O https://awstoe-.s3..amazonaws.com/latest/linux//awstoe ``` For example: ``` curl -O https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe ``` Supported values for **architecture** can be `amd64`, `386`, and `arm64`. 1. At a command prompt, run the following command to download the signature file for the corresponding application binary from the same S3 key prefix path: ``` curl -O https://awstoe-.s3..amazonaws.com/latest/linux//awstoe.sig ``` For example: ``` curl -O https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe.sig ``` Supported values for **architecture** can be `amd64`, `386`, and `arm64`. 1. Verify the signature by running the following command at a command prompt in the directory where you saved `awstoe.sig` and the AWSTOE installation file. Both files must be present. ``` gpg --verify ./awstoe.sig ~/awstoe ``` The output should look something like the following: ``` gpg: Signature made Mon 20 Jul 2020 08:54:55 AM IST using RSA key ID F5AEBC52 gpg: Good signature from "AWSTOE awstoe@amazon.com" [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52 ``` If the output contains the phrase `Good signature from "AWSTOE "`, it means that the signature has successfully been verified, and you can proceed to run the AWSTOE installation script. If the output includes the phrase `BAD signature`, check whether you performed the procedure correctly. If you continue to get this response, do not run the installation file that you downloaded previously, and contact Support. The following are details about the warnings that you might see: + **WARNING: This key is not certified with a trusted signature\$1 There is no indication that the signature belongs to the owner.** Ideally, you would visit an AWS office and receive the key in person. However, you would most likely download it from a website. In this case, the website is an AWS website. + **gpg: no ultimately trusted keys found.** This means that the specific key is not "ultimately trusted" by you, or by other people that you trust. For more information, see [http://www.gnupg.org](http://www.gnupg.org). ## Verify the signature of the AWSTOE installation download on Windows This topic describes the recommended process for verifying the validity of the installation file for the AWS Task Orchestrator and Executor application on Windows-based operating systems. Whenever you download an application from the internet, we recommend that you authenticate the identity of the software publisher and check that the application is not altered or corrupted since it was published. This protects you from installing a version of the application that contains a virus or other malicious code. If, after running the steps in this topic, you determine that the software for the AWSTOE application is altered or corrupted, do not run the installation file. Instead, contact Support. To verify the validity of the downloaded awstoe binary on Windows-based operating systems, make sure that the thumbprint of its Amazon Services LLC signer certificate is equal to this value: **9D CA 72 17 DA FF B8 2F E4 C4 67 77 36 2F A4 AA C9 08 82 15** **Note** During the roll-out window for a new binary, your signer certificate might not match the new thumbprint. If your signer certificate doesn't match, verify that the thumbprint value is: **BA 81 25 EE AC 64 2E A9 F3 C5 93 CA 6D 3E B7 93 7D 68 75 74** To verify this value, perform the following procedure: 1. Right-click the downloaded `awstoe.exe`, and open the **Properties** window. 1. Choose the **Digital Signatures** tab. 1. From the **Signature List**, choose **Amazon Services LLC**, and then choose **Details**. 1. Choose the **General** tab, if not already selected, and then choose **View Certificate**. 1. Choose the **Details** tab, and then choose **All** in the **Show** dropdown list, if not already selected. 1. Scroll down until you see the **Thumbprint** field and then choose **Thumbprint**. This displays the entire thumbprint value in the lower window. + If the thumbprint value in the lower window is identical to the following value: **9D CA 72 17 DA FF B8 2F E4 C4 67 77 36 2F A4 AA C9 08 82 15** then your downloaded AWSTOE binary is authentic and can be safely installed. + If the thumbprint value in the lower details window is not identical to the previous value, do not run `awstoe.exe`. **Topics** + [Verify the signature of the AWSTOE installation download](awstoe-verify-sig.md) + [Step 1: Install AWSTOE](#toe-start-install) + [Step 2: Set AWS credentials](#toe-start-credentials) + [Step 3: Develop component documents locally](#toe-start-develop) + [Step 4: Validate AWSTOE components](#toe-start-validate) + [Step 5: Run AWSTOE components](#toe-start-run) ## Step 1: Install AWSTOE To develop components locally, download and install the AWSTOE application. 1. **Download the AWSTOE application** To install AWSTOE, choose the appropriate download link for your architecture and platform. For the full list of application download links, see [AWSTOE downloads](toe-component-manager.md#toe-downloads) **Important** AWS is phasing out support for TLS versions 1.0 and 1.1. To access the S3 bucket for AWSTOE downloads, your client software must use TLS version 1.2 or later. For more information, see this [AWS Security Blog post](https://aws.amazon.com/blogs/security/tls-1-2-required-for-aws-endpoints/). 1. **Verify the signature** The steps for verifying your download depend on the server platform where you run the AWSTOE application after you install it. To verify your download on a Linux server, see [Verify the signature on Linux or macOS](awstoe-verify-sig.md#awstoe-verify-sig-linux). To verify your download on a Windows server, see [Verify the signature on Windows](awstoe-verify-sig.md#awstoe-verify-sig-win). **Note** AWSTOE is invoked directly from its download location. There is no need for a separate install step. This also means that AWSTOE can make changes to the local environment. To ensure that you isolate changes during component development, we recommend that you use an EC2 instance to develop and test AWSTOE components. ## Step 2: Set AWS credentials AWSTOE requires AWS credentials to connect to other AWS services, such as Amazon S3 and Amazon CloudWatch, when running tasks, such as: + Downloading AWSTOE documents from a user-provided Amazon S3 path. + Running `S3Download` or `S3Upload` action modules. + Streaming logs to CloudWatch, when enabled. If you are running AWSTOE on an EC2 instance, then running AWSTOE uses the same permissions as the IAM role attached to the EC2 instance. For more information about IAM roles for EC2, see [IAM roles for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html). The following examples show how to set AWS credentials using the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. To set these variables on Linux, macOS, or Unix, use `export`. ``` export AWS_ACCESS_KEY_ID=your_access_key_id ``` ``` export AWS_SECRET_ACCESS_KEY=your_secret_access_key ``` To set these variables on Windows using PowerShell, use `$env`. ``` $env:AWS_ACCESS_KEY_ID=your_access_key_id ``` ``` $env:AWS_SECRET_ACCESS_KEY=your_secret_access_key ``` To set these variables on Windows using the command prompt, use `set`. ``` set AWS_ACCESS_KEY_ID=your_access_key_id ``` ``` set AWS_SECRET_ACCESS_KEY=your_secret_access_key ``` ## Step 3: Develop component documents locally Components are authored with plaintext YAML documents. For more information about document syntax, see [Use the AWSTOE component document framework for custom components](toe-use-documents.md). The following are example *Hello World* component documents to help you get started. ------ #### [ Linux ] Some of the Linux component examples in this guide refer to a component document file named `hello-world-linux.yml`. You can use the following document to get started with those examples. ``` name: Hello World description: This is hello world testing document for Linux. schemaVersion: 1.0 phases: - name: build steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the build phase.' - name: validate steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the validate phase.' - name: test steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the test phase.' ``` ------ #### [ Windows ] Some of the Windows component examples in this guide refer to a component document file named `hello-world-windows.yml`. You can use the following document to get started with those examples. ``` name: Hello World description: This is Hello World testing document for Windows. schemaVersion: 1.0 phases: - name: build steps: - name: HelloWorldStep action: ExecutePowerShell inputs: commands: - Write-Host 'Hello World from the build phase.' - name: validate steps: - name: HelloWorldStep action: ExecutePowerShell inputs: commands: - Write-Host 'Hello World from the validate phase.' - name: test steps: - name: HelloWorldStep action: ExecutePowerShell inputs: commands: - Write-Host 'Hello World from the test phase.' ``` ------ #### [ macOS ] Some of the macOS component examples in this guide refer to a component document file named `hello-world-macos.yml`. You can use the following document to get started with those examples. ``` name: Hello World description: This is hello world testing document for macOS. schemaVersion: 1.0 phases: - name: build steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the build phase.' - name: validate steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the validate phase.' - name: test steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the test phase.' ``` ------ ## Step 4: Validate AWSTOE components You can validate the syntax of AWSTOE components locally with the AWSTOE application. The following examples show the AWSTOE application `validate` command to validate the syntax of a component without running it. **Note** The AWSTOE application can validate only the component syntax for the current operating system. For example, when running `awstoe.exe` on Windows, you cannot validate the syntax for a Linux document that uses the `ExecuteBash` action module. Linux or macOS ``` awstoe validate --documents /home/user/hello-world.yml ``` Windows ``` awstoe.exe validate --documents C:\Users\user\Documents\hello-world.yml ``` ## Step 5: Run AWSTOE components The AWSTOE application can run one or more phases of specified documents using the `--phases` command line argument. Supported values for `--phases` are `build`, `validate`, and `test`. Multiple phase values can be entered as comma separated values. When you provide a list of phases, the AWSTOE application sequentially runs the specified phases of each document. For example, AWSTOE runs the `build` and `validate` phases of `document1.yaml`, followed by the `build` and `validate` phases of `document2.yaml`. To ensure that your logs are stored securely and retained for troubleshooting, we recommend configuring log storage in Amazon S3. In Image Builder, the Amazon S3 location for publishing logs is specified in the infrastructure configuration. For more information about infrastructure configuration, see [Manage Image Builder infrastructure configuration](manage-infra-config.md) If a list of phases is not provided, the AWSTOE application runs all phases in the order listed in the YAML document. To run specific phases in single or multiple documents, use the following commands. Single phase ``` awstoe run --documents hello-world.yml --phases build ``` Multiple phases ``` awstoe run --documents hello-world.yml --phases build,test ``` **Document run** Run all phases in a single document ``` awstoe run --documents documentName.yaml ``` Run all phases in multiple documents ``` awstoe run --documents documentName1.yaml,documentName2.yaml ``` Enter Amazon S3 information to upload AWSTOE logs from a user-defined local path (recommended) ``` awstoe run --documents documentName.yaml --log-s3-bucket-name amzn-s3-demo-destination-bucket --log-s3-key-prefix S3KeyPrefix --log-s3-bucket-owner S3BucketOwner --log-directory local_path ``` Run all phases in a single document, and display all logs on the console ``` awstoe run --documents documentName.yaml --trace ``` Example command ``` awstoe run --documents s3://bucket/key/doc.yaml --phases build,validate ``` Run document with unique ID ``` awstoe run --documents documentName.yaml --execution-id user-provided-id --phases build,test ``` Get help with AWSTOE ``` awstoe --help ``` # Use the AWSTOE component document framework for custom components To build a component using the AWS Task Orchestrator and Executor (AWSTOE) component framework, you must provide a YAML-based document that represents the phases and steps that apply for the component you create. AWS services use your component when they create a new Amazon Machine Image (AMI) or container image. **Topics** + [Component document workflow](#component-doc-workflow) + [Component logging](#component-logging) + [Input and output chaining](#document-chaining) + [Document schema and definitions](#document-schema) + [Document examples](#document-example) + [Use variables in your custom component document](toe-user-defined-variables.md) + [Use conditional constructs in AWSTOE](toe-conditional-constructs.md) + [Use comparison operators in AWSTOE component documents](toe-comparison-operators.md) + [Use logical operators in AWSTOE component documents](toe-logical-operators.md) + [Use looping constructs in AWSTOE](toe-looping-constructs.md) ## Component document workflow The AWSTOE component document uses phases and steps to group related tasks, and organize those tasks into a logical workflow for the component. **Tip** The service that uses your component to build an image might implement rules about what phases to use for their build process, and when those phases are allowed to run. This is important to consider when you design your component. **Phases** Phases represent the progression of your workflow through the image build process. For example, the Image Builder service uses `build` and `validate` phases during its *build stage* for the images it produces. It uses the `test` and `container-host-test` phases during its *test stage* to ensure that the image snapshot or container image produces the expected results before creating the final AMI or distributing the container image. When the component runs, the associated commands for each phase are applied in the order that they appear in the component document. **Rules for phases** + Each phase name must be unique within a document. + You can define many phases in your document. + You must include at least one of the following phases in your document: + **build** – for Image Builder, this phase is generally used during the *build stage*. + **validate** – for Image Builder, this phase is generally used during the *build stage*. + **test** – for Image Builder, this phase is generally used during the *test stage*. + Phases always run in the order that they are defined in the document. The order in which they are specified for AWSTOE commands in the AWS CLI has no effect. **Steps** Steps are individual units of work that define the workflow within each phase. Steps run in sequential order. However, input or output for one step can also feed into a subsequent step as input. This is called "chaining". **Rules for steps** + The step name must be unique for the phase. + The step must use a supported action (action module) that returns an exit code. For a complete list of supported action modules, how they work, input/output values, and examples, see [Action modules supported by AWSTOE component manager](toe-action-modules.md). ## Component logging AWSTOE creates a new log folder on the EC2 instances that are used for building and testing a new image, each time your component runs. For container images, the log folder is stored in the container. To assist with troubleshooting if something goes wrong during the image creation process, the input document and all of the output files AWSTOE creates while running the component are stored in the log folder. The log folder name is comprised of the following parts: 1. **Log directory** – when a service runs a AWSTOE component, it passes in the log directory, along with other settings for the command. For the following examples, we show the log file format that Image Builder uses. + **Linux and macOS**: `/var/lib/amazon/toe/` + **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\` 1. **File prefix** – This is a standard prefix used for all components: "`TOE_`". 1. **Run time** – This is a timestamp in YYYY-MM-DD\$1HH-MM-SS\$1UTC-0 format. 1. **Execution ID** – This is the GUID that is assigned when AWSTOE runs one or more components. Example: `/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4` AWSTOE stores the following core files in the log folder: **Input files** + **document.yaml** – The document that is used as input for the command. After the component runs, this file is stored as an artifact. **Output files** + **application.log** – The application log contains timestamped debug level information from AWSTOE about what's happening as the component is running. + **detailedoutput.json** – This JSON file has detailed information about run status, inputs, outputs, and failures for all documents, phases, and steps that apply for the component as it runs. + **console.log** – The console log contains all of the standard out (stdout) and standard error (stderr) information that AWSTOE writes to the console while the component is running. + **chaining.json** – This JSON file represents optimizations that AWSTOE applied to resolve chaining expressions. **Note** The log folder might also contain other temporary files that are not covered here. ## Input and output chaining The AWSTOE configuration management application provides a feature for chaining inputs and outputs by writing references in the following formats: `{{ phase_name.step_name.inputs/outputs.variable }}` or `{{ phase_name.step_name.inputs/outputs[index].variable }}` The chaining feature allows you to recycle code and improve the maintainability of the document. **Rules for chaining** + Chaining expressions can be used only in the inputs section of each step. + Statements with chaining expressions must be enclosed in quotes. For example: + **Invalid expression**: `echo {{ phase.step.inputs.variable }}` + **Valid expression**: `"echo {{ phase.step.inputs.variable }}"` + **Valid expression**: `'echo {{ phase.step.inputs.variable }}'` + Chaining expressions can reference variables from other steps and phases in the same document. However, the calling service might have rules that require chaining expressions to operate only within the context of a single stage. For example, Image Builder does not support chaining from the *build stage* to the *test stage*, as it runs each stage independently. + Indexes in chaining expressions follow zero-based indexing. The index starts with zero (0) to reference the first element. **Examples** To refer to the source variable in the second entry of the following example step, the chaining pattern is `{{ build.SampleS3Download.inputs[1].source }}`. ``` phases: - name: 'build' steps: - name: SampleS3Download action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://sample-bucket/sample1.ps1' destination: 'C:\sample1.ps1' - source: 's3://sample-bucket/sample2.ps1' destination: 'C:\sample2.ps1' ``` To refer to the output variable (equal to "Hello") of the following example step, the chaining pattern is `{{ build.SamplePowerShellStep.outputs.stdout }}`. ``` phases: - name: 'build' steps: - name: SamplePowerShellStep action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"' ``` ## Document schema and definitions The following is the YAML schema for a document. ``` name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs: ``` The schema definitions for a document are as follows. | Field | Description | Type | Required | | --- | --- | --- | --- | | name | Name of the document. | String | No | | description | Description of the document. | String | No | | schemaVersion | Schema version of the document, currently 1.0. | String | Yes | | phases | A list of phases with their steps. | List | Yes | The schema definitions for a phase are as follows. | Field | Description | Type | Required | | --- | --- | --- | --- | | name | Name of the phase. | String | Yes | | steps | List of the steps in the phase. | List | Yes | The schema definitions for a step are as follows. | Field | Description | Type | Required | Default value | | --- | --- | --- | --- | --- | | name | User-defined name for the step. | String | | | | action | Keyword pertaining to the module that runs the step. | String | | | | timeoutSeconds | Number of seconds that the step runs before failing or retrying. Also, supports -1 value, which indicates infinite timeout. 0 and other negative values are not allowed. | Integer | No | 7,200 sec (120 mins) | | onFailure | Specifies what the step should do in case of failure. Valid values are as follows: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-use-documents.html) | String | No | Abort | | maxAttempts | Maximum number of attempts allowed before failing the step. | Integer | No | 1 | | inputs | Contains parameters required by the action module to run the step. | Dict | Yes | | ## Document examples The following examples show AWSTOE component documents that perform tasks for the target operating system. ------ #### [ Linux ] **Example 1: Run a custom binary file** The following is an example document that downloads and runs a custom binary file on a Linux instance. ``` name: LinuxBin description: Download and run a custom Linux binary file. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ Windows ] **Example 1: Install Windows updates** The following is an example document that installs all available Windows updates, runs a configuration script, validates the changes before the AMI is created, and tests the changes after the AMI is created. ``` name: RunConfig_UpdateWindows description: 'This document will install all available Windows updates and run a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.' schemaVersion: 1.0 phases: - name: build steps: - name: DownloadConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/config.ps1' destination: 'C:\config.ps1' - name: RunConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: RebootAfterConfigApplied action: Reboot inputs: delaySeconds: 60 - name: InstallWindowsUpdates action: UpdateOS - name: validate steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: test steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{test.DownloadTestConfigScript.inputs[0].destination}}' ``` **Example 2: Install the AWS CLI on a Windows instance** The following is an example document that installs the AWS CLI on a Windows instance, using the setup file. ``` name: InstallCLISetUp description: Install &CLI; using the setup file schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLISetup.exe destination: C:\Windows\temp\AWSCLISetup.exe - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '/install' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` **Example 3: Install the AWS CLI with the MSI installer** The following is an example document that installs the AWS CLI with the MSI installer. ``` name: InstallCLIMSI description: Install &CLI; using the MSI installer schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLI64PY3.msi destination: C:\Windows\temp\AWSCLI64PY3.msi - name: Install action: ExecuteBinary onFailure: Continue inputs: path: 'C:\Windows\System32\msiexec.exe' arguments: - '/i' - '{{ build.Download.inputs[0].destination }}' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ macOS ] **Example 1: Run a custom macOS binary file** The following is an example document that downloads and runs a custom binary file on a macOS instance. ``` name: macOSBin description: Download and run a binary file on macOS. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ # Use variables in your custom component document Variables provide a way to label data with meaningful names that can be used throughout an application. You can define custom variables with simple and readable formats for complex workflows, and reference them in the YAML application component document for an AWSTOE component. This section provides information to help you define variables for your AWSTOE component in the YAML application component document, including syntax, name constraints, and examples. ## Constants Constants are immutable variables that cannot be modified or overridden once defined. Constants can be defined using values in the `constants` section of an AWSTOE document. **Rules for constant names** + The name must be between 3 and 128 characters in length. + The name can only contain alphanumeric characters (a-z, A-Z, 0-9), dashes (-), or underscores (\$1). + The name must be unique within the document. + The name must be specified as a YAML string. **Syntax** ``` constants: - : type: value: ``` | Key name | Required | Description | | --- | --- | --- | | `name` | Yes | Name of the constant. Must be unique for the document (it must not be the same as any other parameter names or constants). | | `value` | Yes | Value of the constant. | | `type` | Yes | Type of the constant. Supported type is string. | **Reference constant values in a document** You can reference constants in step or loop inputs inside of your YAML document, as follows: + Constant references are case-sensitive, and the name must match exactly. + The name must be enclosed within double curly braces `{{` *MyConstant* `}}`. + Spaces are allowed within the curly braces, and are automatically trimmed. For example, all of the following references are valid: `{{ MyConstant }}`, `{{ MyConstant}}`, `{{MyConstant }}`, `{{MyConstant}}` + The reference in the YAML document must be specified as a string (enclosed in single or double quotes). For example: `- {{ MyConstant }}` is not valid, as it is not identified as a string. However, the following references are both valid: `- '{{ MyConstant }}'` and `- "{{ MyConstant }}"`. **Examples** Constant referenced in step inputs ``` name: Download AWS CLI version 2 schemaVersion: 1.0 constants: - Source: type: string value: https://awscli.amazonaws.com/AWSCLIV2.msi phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` Constant referenced in loop inputs ``` name: PingHosts schemaVersion: 1.0 constants: - Hosts: type: string value: 127.0.0.1,amazon.com phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ## Parameters Parameters are mutable variables, with settings that the calling application can provide at runtime. You can define parameters in the `Parameters` section of the YAML document. **Rules for parameter names** + The name must be between 3 and 128 characters in length. + The name can only contain alphanumeric characters (a-z, A-Z, 0-9), dashes (-), or underscores (\$1). + The name must be unique within the document. + The name must be specified as a YAML string. ### Syntax ``` parameters: - : type: default: description: ``` | Key name | Required | Description | | --- | --- | --- | | `name` | Yes | The name of the parameter. Must be unique for the document (it must not be the same as any other parameter names or constants). | | `type` | Yes | The data type of the parameter. Supported types include: `string`. | | `default` | No | The default value for the parameter. | | `description` | No | Describes the parameter. | ### Reference parameter values in a document You can reference parameters in step or loop inputs inside of your YAML document, as follows: + Parameter references are case-sensitive, and the name must match exactly. + The name must be enclosed within double curly braces `{{` *MyParameter* `}}`. + Spaces are allowed within the curly braces, and are automatically trimmed. For example, all of the following references are valid: `{{ MyParameter }}`, `{{ MyParameter}}`, `{{MyParameter }}`, `{{MyParameter}}` + The reference in the YAML document must be specified as a string (enclosed in single or double quotes). For example: `- {{ MyParameter }}` is not valid, as it is not identified as a string. However, the following references are both valid: `- '{{ MyParameter }}'` and `- "{{ MyParameter }}"`. **Examples** The following examples show how to use parameters in your YAML document: + Refer to a parameter in step inputs: ``` name: Download AWS CLI version 2 schemaVersion: 1.0 parameters: - Source: type: string default: 'https://awscli.amazonaws.com/AWSCLIV2.msi' description: The AWS CLI installer source URL. phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` + Refer to a parameter in loop inputs: ``` name: PingHosts schemaVersion: 1.0 parameters: - Hosts: type: string default: 127.0.0.1,amazon.com description: A comma separated list of hosts to ping. phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ### Override parameters at runtime You can use the `--parameters` option from the AWS CLI with a key-value pair to set a parameter value at runtime. + Specify the parameter key-value pair as the name and value, separated by an equals sign (=). + Multiple parameters must be separated by a comma. + Parameter names that are not found in the YAML component document are ignored. + The parameter name and value are both required. **Important** Component parameters are plain text values, and are logged in AWS CloudTrail. We recommend that you use AWS Secrets Manager or the AWS Systems Manager Parameter Store to store your secrets. For more information about Secrets Manager, see [What is Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*. For more information about AWS Systems Manager Parameter Store, see [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) in the *AWS Systems Manager User Guide*. #### Syntax ``` --parameters name1=value1,name2=value2... ``` | CLI option | Required | Description | | --- | --- | --- | | --parameters *name*=*value*,... | No | This option takes list of key-value pairs, with the parameter name as the key. | **Examples** The following examples show how to use parameters in your YAML document: + The parameter key-value pair specified in this `--parameter` option is not valid: ``` --parameters ntp-server= ``` + Set one parameter key-value pair with the `--parameter` option in the AWS CLI: ``` --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com ``` + Set multiple parameter key-value pairs with the `--parameter` option in the AWS CLI: ``` --parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com ``` ## Use Systems Manager Parameter Store parameters You can reference AWS Systems Manager Parameter Store parameters (SSM parameters) in your component documents by prefixing variables with `aws:ssm`. For example, `{{ aws:ssm:/my/param }}` resolves to the value of the SSM parameter `/my/param`. This feature supports the following SSM parameter types: + String – Maps to the AWSTOE string type. + StringList – Maps to the AWSTOE `stringList` type. + SecureString – Maps to the AWSTOE string type. For more information about the Parameter Store see [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) in the *AWS Systems Manager User Guide*. You can also reference AWS Secrets Manager secrets using an SSM parameter `SecureString`. For example: `{{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}`. For more information, see [Referencing AWS Secrets Manager secrets from Parameter Store parameters](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html). **Important** Image Builder excludes `SecureString` parameter resolution from its logs. However, you are also responsible for ensuring that sensitive information is not logged through commands issued in the component document. For example, if you use the `echo` command with a secure string, the command writes a plaintext value to the log. ### Required IAM permissions To use Systems Manager parameters in your components, your instance role must have the `ssm:GetParameter` permission for the parameter resource ARN. For example: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ssm:GetParameter", "Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*" } ] } ``` ------ To access encrypted values, you'll also need the following permissions: + Add `kms:Decrypt` for `SecureString` parameters or AWS Secrets Manager values that are encrypted with a customer managed AWS KMS key. + Add `secretsmanager:GetSecretValue` if you reference a Secrets Manager secret. ### Reference an SSM parameter in a component document The following example shows how to reference an Systems Manager Parameter Store parameter of Systems Manager parameters in a component: ``` name: UseSSMParameterVariable description: This is a sample component document that prints out the value of an SSM Parameter. Never do this for a SecureString parameter. schemaVersion: 1.0 phases: - name: verify steps: - name: EchoParameterValue action: ExecuteBash inputs: commands: - echo "Log SSM parameter name: /my/test/param, value {{ aws:ssm:/my/test/param }}." ``` ### Dynamic runtime variable resolution for SSM parameters AWSTOE provides the following built-in function that you can use within variable references to manipulate or transform values at runtime. #### resolve function The `resolve` function resolves a variable reference inside of another variable reference, allowing for dynamic variable name referencing. This is useful when working with SSM parameters where part of the parameter path may be variable and passed in as a document parameter. The `resolve` function only supports dynamic resolution of the name portion of an SSM parameter. ##### Syntax The `dynamic_variable` in the following example represents the name of an SSM parameter, and must be one of the following: + An SSM parameter reference (for example, `aws:ssm:/my/param`) + A component document parameter reference (for example, `parameter-name`) ``` {{ aws:ssm:resolve(dynamic_variable) }} ``` ##### Example: Resolve an SSM parameter at runtime The following example shows how to use the `resolve` function in a YAML component document: ``` name: SsmParameterTest description: This component verifies an SSM parameter variable reference with the echo command. schemaVersion: 1.0 parameters: - parameter-name: type: string description: "test" phases: - name: validate steps: - name: PrintDynamicVariable action: ExecuteBash inputs: commands: - echo "{{ aws:ssm:resolve(parameter-name) }}" ``` # Use conditional constructs in AWSTOE Conditional constructs perform different actions in your component document based on whether the specified conditional expression evaluates to `true` or `false`. You can use the `if` construct to control the flow of execution in your component document. ## if Construct You can use the `if` construct to evaluate whether a step should run or not. By default, when the `if` conditional expression evaluates to `true`, AWSTOE runs the step, and when the condition evaluates to `false`, AWSTOE skips the step. If a step is skipped, it's treated as a successful step when AWSTOE evaluates whether the phase and document ran successfully. **Note** An `if` statement is only evaluated one time, even if the step triggers a restart. If a step restarts, it recognizes that the `if` statement has already been evaluated, and continues where it left off. ### Syntax ``` if: - : [then: ] [else: ] ``` | Key name | Required | Description | | --- | --- | --- | | conditional expression | Yes | The conditional expression can contain exactly one of the following types of operators at the top level. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-conditional-constructs.html) If your expression must satisfy multiple conditions, use a logical operator to specify your conditions. | | then | No | Defines the action to take if the conditional expression evaluates to `true`. | | else | No | Defines the action to take if the conditional expression evaluates to `false`. | | step action | Conditional | When you use `then` or `else`, you must specify one of the following step actions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-conditional-constructs.html) | **Example 1: Install package** The following example steps from an AWSTOE component document use logical operators to test a parameter value and run the appropriate package manager commands to install an application if the package is unzipped. ``` - name: InstallUnzipAptGet action: ExecuteBash if: and: - binaryExists: 'apt-get' - not: binaryExists: 'unzip' inputs: commands: - sudo apt-get update - sudo apt-get install -y unzip - name: InstallUnzipYum action: ExecuteBash if: and: - binaryExists: 'yum' - not: binaryExists: 'unzip' inputs: commands: - sudo yum install -y unzip - name: InstallUnzipZypper action: ExecuteBash if: and: - binaryExists: 'zypper' - not: binaryExists: 'unzip' inputs: commands: - sudo zypper refresh - sudo zypper install -y unzip ``` **Example 2: Skip a step** The following example shows two ways to skip a step. One uses a logical operator, and one uses a comparison operator with the `Skip` step action. ``` # Creates a file if it does not exist using not - name: CreateMyConfigFile-1 action: ExecuteBash if: not: fileExists: '/etc/my_config' inputs: commands: - echo "Hello world" > '/etc/my_config' # Creates a file if it does not exist using then and else - name: CreateMyConfigFile-2 action: ExecuteBash if: fileExists: '/etc/my_config' then: Skip else: Execute inputs: commands: - echo "Hello world" > '/etc/my_config' ``` # Use comparison operators in AWSTOE component documents You can use the following comparison operators with the **[Assert](toe-action-modules.md#action-modules-assertion)** action module and with conditional expressions that use the [if ConstructSyntax](toe-conditional-constructs.md#toe-conditional-if). A comparison operator can operate on a single value, for example `stringIsEmpty`, or it can compare a baseline value to a second value (variable value) to determine whether the conditional expression evaluates to `true` or `false`. If the comparison operates on two values, the second value can be a chaining variable. When comparing values of a different type, the following value conversions can occur prior to the comparison: + For numeric comparisons, if the variable value is a string, AWSTOE converts the string to a number prior to the evaluation. If the conversion is not possible, the comparison returns `false`. For example, if the variable value is `"1.0"`, the conversion works, but if the variable value is `"a10"` the conversion fails. + For string comparisons, if the variable value is a number, AWSTOE converts it to a string prior to the evaluation. ## Compare strings The following comparison operators work with strings to compare values, to test for spaces or an empty string, or to compare an input value to a regex pattern. String comparisons are not case sensitive, and they don't trim spaces from the beginning or the end of the string inputs. **String comparison operators** + [stringIsEmpty](#stringIsEmpty) + [stringIsWhitespace](#stringIsWhitespace) + [stringEquals](#stringEquals) + [stringLessThan](#stringLessThan) + [stringLessThanEquals](#stringLessThanEquals) + [stringGreaterThan](#stringGreaterThan) + [stringGreaterThanEquals](#stringGreaterThanEquals) + [patternMatches](#patternMatches) **stringIsEmpty** The `stringIsEmpty` operator returns `true` if the specified string doesn't contain any characters. For example: ``` # Evaluates to true stringIsEmpty: "" # Evaluates to false stringIsEmpty: " " # Evaluates to false stringIsEmpty: "Hello." ``` **stringIsWhitespace** Tests if the string specified for `stringIsWhitespace` contains only spaces. For example: ``` # Evaluates to true stringIsWhitespace: " " # Evaluates to false stringIsWhitespace: "" # Evaluates to false stringIsWhitespace: " Hello?" ``` **stringEquals** Tests if the string specified for `stringEquals` is an exact match for the string specified in the `value` parameter. For example: ``` # Evaluates to true stringEquals: 'Testing, testing...' value: 'Testing, testing...' # Evaluates to false stringEquals: 'Testing, testing...' value: 'Hello again.' # Evaluates to false stringEquals: 'Testing, testing...' value: 'TESTING, TESTING....' # Evaluates to false stringEquals: 'Testing, testing...' value: ' Testing, testing...' # Evaluates to false stringEquals: 'Testing, testing...' value: 'Testing, testing... ' ``` **stringLessThan** Tests if the string specified for `stringLessThan` is less than the string specified in the `value` parameter. For example: ``` # Evaluates to true # This comparison operator isn't case sensitive stringlessThan: 'A' value: 'a' # Evaluates to true - 'a' is less than 'b' stringlessThan: 'b' value: 'a' # Evaluates to true # Numeric strings compare as less than alphabetic strings stringlessThan: 'a' value: '0' # Evaluates to false stringlessThan: '0' value: 'a' ``` **stringLessThanEquals** Tests if the string specified for `stringLessThanEquals` is less than or equal to the string specified in the `value` parameter. For example: ``` # Evaluates to true - 'a' is equal to 'a' stringLessThanEquals: 'a' value: 'a' # Evaluates to true - since the comparison isn't case sensitive, 'a' is equal to 'A' stringLessThanEquals: 'A' value: 'a' # Evaluates to true - 'a' is less than 'b' stringLessThanEquals: 'b' value: 'a' # Evaluates to true - '0' is less than 'a' stringLessThanEquals: 'a' value: '0' # Evaluates to false - 'a' is greater than '0' stringLessThanEquals: '0' value: 'a' ``` **stringGreaterThan** Tests if the string specified for `stringGreaterThan` is greater than the string specified in the `value` parameter. For example: ``` # Evaluates to false - since the comparison isn't case sensitive, 'A' is equal to 'a' stringGreaterThan: 'a' value: 'A' # Evaluates to true - 'b' is greater than 'a' stringGreaterThan: 'a' value: 'b' # Evaluates to true - 'a' is greater than '0' stringGreaterThan: '0' value: 'a' # Evaluates to false - '0' is less than 'a' stringGreaterThan: 'a' value: '0' ``` **stringGreaterThanEquals** Tests if the string specified for `stringGreaterThanEquals` is greater than or equal to the string specified in the `value` parameter. For example: ``` # Evaluates to true - 'a' is equal to 'A' stringGreaterThanEquals: 'A' value: 'a' # Evaluates to true - 'b' is greater than 'a' stringGreaterThanEquals: 'a' value: 'b' # Evaluates to true - 'a' is greater than '0' stringGreaterThanEquals: '0' value: 'a' # Evaluates to false - '0' is less than 'a' stringGreaterThanEquals: 'a' value: '0' ``` **patternMatches** Tests if the string specified in the `value` parameter matches the regex pattern specified for `patternMatches`. The comparison uses to the [Golang regexp package](https://pkg.go.dev/regexp), which conforms to the RE2 syntax. For more information about RE2 rules, see the [google / re2](https://github.com/google/re2/wiki/Syntax) repository in *GitHub*. The following example shows a pattern match that returns `true`: ``` patternMatches: '^[a-z]+$' value: 'ThisIsValue' ``` ## Compare numbers The following comparison operators work with numbers. The values provided for these operators must be one of the following types, according to the YAML specification. Support for numeric comparisons uses the golang big package comparison operator, for example: [func (\$1Float) Cmp](https://pkg.go.dev/math/big#Float.Cmp). + Integer + Float (based on float64, which supports numbers from -1.7e\$1308 to \$11.7e\$1308) + A string that matches the following regex pattern: `^[-+]?([0-9]+[.])?[0-9]+$` **Number comparison operators** + [numberEquals](#numberEquals) + [numberLessThan](#numberLessThan) + [numberLessThanEquals](#numberLessThanEquals) + [numberGreaterThan](#numberGreaterThan) + [numberGreaterThanEquals](#numberGreaterThanEquals) **numberEquals** Tests if the number specified for `numberEquals` is equal to the number specified in the `value` parameter. All of the following example comparisons return `true`: ``` # Values provided as a positive number numberEquals: 1 value: 1 # Comparison value provided as a string numberEquals: '1' value: 1 # Value provided as a string numberEquals: 1 value: '1' # Values provided as floats numberEquals: 5.0 value: 5.0 # Values provided as a negative number numberEquals: -1 value: -1 ``` **numberLessThan** Tests if the number specified for `numberLessThan` is less than the number specified in the `value` parameter. For example: ``` # Evaluates to true numberLessThan: 2 value: 1 # Evaluates to true numberLessThan: 2 value: 1.9 # Evaluates to false numberLessThan: 2 value: '2' ``` **numberLessThanEquals** Tests if the number specified for `numberLessThanEquals` is less than or equal to the number specified in the `value` parameter. For example: ``` # Evaluates to true numberLessThanEquals: 2 value: 1 # Evaluates to true numberLessThanEquals: 2 value: 1.9 # Evaluates to true numberLessThanEquals: 2 value: '2' # Evaluates to false numberLessThanEquals: 2 value: 2.1 ``` **numberGreaterThan** Tests if the number specified for `numberGreaterThan` is greater than the number specified in the `value` parameter. For example: ``` # Evaluates to true numberGreaterThan: 1 value: 2 # Evaluates to true numberGreaterThan: 1 value: 1.1 # Evaluates to false numberGreaterThan: 1 value: '1' ``` **numberGreaterThanEquals** Tests if the number specified for `numberGreaterThanEquals` is greater than or equal to the number specified in the `value` parameter. For example: ``` # Evaluates to true numberGreaterThanEquals: 1 value: 2 # Evaluates to true numberGreaterThanEquals: 1 value: 1.1 # Evaluates to true numberGreaterThanEquals: 1 value: '1' # Evaluates to false numberGreaterThanEquals: 1 value: 0.8 ``` ## Check files The following comparison operators check the file hash or check if a file or folder exists. **File and folder operators** + [binaryExists](#binaryExists) + [fileExists](#fileExists) + [folderExists](#folderExists) + [fileMD5Equals](#fileMD5Equals) + [fileSHA1Equals](#fileSHA1Equals) + [fileSHA256Equals](#fileSHA256Equals) + [fileSHA512Equals](#fileSHA512Equals) **binaryExists** Tests whether an application is available in the current path. For example: ``` binaryExists: 'foo' ``` On Linux and macOS systems, for an application named *foo*, this works the same as the following bash command: **type *foo* >/dev/null 2>&1**, where **\$1? == 0** indicates a successful comparison. On Windows systems, for an application named *foo*, this works the same as the PowerShell command **& C:\$1Windows\$1System32\$1where.exe /Q *foo*** where **\$1LASTEXITCODE = 0** indicates a successful comparison. **fileExists** Tests whether a file exists at the specified path. You can provide an absolute or relative path. If the location you specify exists and is a file, the comparison evaluates to `true`. For example: ``` fileExists: '/path/to/file' ``` On Linux and macOS systems, this works the same as the following bash command: **-d */path/to/file***, where **\$1? == 0** indicates a successful comparison. On Windows systems, this works the same as the PowerShell command **Test-Path -Path '*C:\$1path\$1to\$1file*' -PathType 'Leaf'**. **folderExists** Tests whether a folder exists at the specified path. You can provide an absolute or relative path. If the location you specify exists and is a folder, the comparison evaluates to `true`. For example: ``` folderExists: '/path/to/folder' ``` On Linux and macOS systems, this works the same as the following bash command: **-d */path/to/folder***, where **\$1? == 0** indicates a successful comparison. On Windows systems, this works the same as the PowerShell command **Test-Path -Path '*C:\$1path\$1to\$1folder*' -PathType 'Container'**. **fileMD5Equals** Tests whether a file’s MD5 hash equals a specified value. For example: ``` fileMD5Equals: '' path: '/path/to/file' ``` **fileSHA1Equals** Tests whether a file’s SHA1 hash equals a specified value. For example: ``` fileSHA1Equals: '' path: '/path/to/file' ``` **fileSHA256Equals** Tests whether a file’s SHA256 hash equals a specified value. For example: ``` fileSHA256Equals: '' path: '/path/to/file' ``` **fileSHA512Equals** Tests whether a file’s SHA512 hash equals a specified value. For example: ``` fileSHA512Equals: '' path: '/path/to/file' ``` # Use logical operators in AWSTOE component documents You can use the following logical operators to add or modify conditional expressions in your component document. AWSTOE evaluates conditional expressions in the order that the conditions are specified. For more information about comparison operators for component documents, see [Use comparison operators in AWSTOE component documents](toe-comparison-operators.md). **and** With the `and` operator, you can evaluate two or more comparisons as a single expression. The expression evaluates to `true` when all of the conditions in the list are true. Otherwise, the expression evaluates to `false`. **Examples:** The following example performs two comparisons – a string and a number. Both comparisons are true, so the expression evaluates to true. ``` and: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 1 ``` The following example also performs two comparisons. The first comparison is false, at which point evaluation stops and the second comparison is skipped. The expression evaluates to `false`. ``` and: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` **or** With the `or` operator, you can evaluate two or more comparisons as a single expression. The expression evaluates to `true` when one of the specified comparisons is true. If none of the specified comparisons evaluate to `true`, the expression evaluates to `false`. **Examples:** The following example performs two comparisons – a string and a number. The first comparison is true, so the expression evaluates to `true` and the second comparison is skipped. ``` or: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 3 ``` The following example also performs two comparisons. The first comparison is false, and evaluation continues. The second comparison is true, so the expression evaluates to `true`. ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` In the final example, both comparisons are false, so the expression evaluates to `false`. ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 3 ``` **not** With the `not` operator, you can negate a single comparison. The expression evaluates to `true` if the comparison is false. If the comparison is true, then the expression evaluates to `false`. **Examples:** The following example performs a string comparison. The comparison is false, so the expression evaluates to `true`. ``` not: - stringEquals: 'test_string' value: 'Hello world!' ``` The following example also performs a string comparison. The comparison is true, so the expression evaluates to `false`. ``` not: - stringEquals: 'test_string' value: 'test_string' ``` # Use looping constructs in AWSTOE This section provides information to help you create looping constructs in the AWSTOE. Looping constructs define a repeated sequence of instructions. You can use the following types of looping constructs in AWSTOE: + `for` constructs – Iterate over a bounded sequence of integers. + `forEach` constructs + `forEach` loop with input list – Iterates over a finite collection of strings. + `forEach` loop with delimited list – Iterates over a finite collection of strings joined by a delimiter. **Note** Looping constructs support only string data types. **Topics** + [Reference iteration variables](#toe-loop-iteration-variables) + [Types of looping constructs](#toe-loop-types) + [Step fields](#toe-loop-step-fields) + [Step and iteration outputs](#toe-loop-step-output) ## Reference iteration variables To refer to the index and value of the current iteration variable, the reference expression `{{ loop.* }}` must be used within the input body of a step that contains a looping construct. This expression cannot be used to refer to the iteration variables of the looping construct of another step. The reference expression consists of the following members: + `{{ loop.index }}` – The ordinal position of the current iteration, which is indexed at `0`. + `{{ loop.value }}` – The value associated with the current iteration variable. ### Loop names All looping constructs have an optional name field for identification. If a loop name is provided, it can be used to refer to iteration variables in the input body of the step. To refer to the iteration indices and values of a named loop, use `{{ .* }}` with `{{ loop.* }}` in the input body of the step. This expression cannot be used to refer to the named looping construct of another step. The reference expression consists of the following members: + `{{ .index }}` – The ordinal position of the current iteration of the named loop, which is indexed at `0`. + `{{ .value }}` – The value associated with the current iteration variable of the named loop. ### Resolve reference expressions The AWSTOE resolves reference expressions as follows: + `{{ .* }}` – AWSTOE resolves this expression using the following logic: + If the loop of the currently running step matches the `` value, then the reference expression resolves to the looping construct of the currently running step. + `` resolves to the named looping construct if it appears within the currently running step. + `{{ loop.* }}` – AWSTOE resolves the expression using the looping construct defined in the currently running step. If reference expressions are used within a step that does not contain a loop, then AWSTOE does not resolve the expressions and they appear in the step with no replacement. **Note** Reference expressions must be enclosed in double quotes to be correctly interpreted by the YAML compiler. ## Types of looping constructs This section provides information and examples about looping construct types that can be used in the AWSTOE. **Topics** + [`for` loop](#toe-loop-types-for) + [`forEach` loop with input list](#toe-loop-types-foreach) + [`forEach` loop with delimited list](#toe-loop-types-foreach-delimited) ### `for` loop The `for` loop iterates on a range of integers specified within a boundary outlined by the start and end of the variables. The iterating values are in the set `[start, end]` and includes boundary values. AWSTOE verifies the `start`, `end`, and `updateBy` values to ensure that the combination does not result in an infinite loop. `for` loop schema ``` - name: "StepName" action: "ActionModule" loop: name: "string" for: start: int end: int updateBy: int inputs: ... ``` **`for` loop input** | Field | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `name` | Unique name of the loop. It must be unique compared to other loop names in the same phase. | String | No | "" | | `start` | Starting value of iteration. Does not accept chaining expressions. | Integer | Yes | n/a | | `end` | Ending value of iteration. Does not accept chaining expressions. | Integer | Yes | n/a | | `updateBy` | Difference by which an iterating value is updated through addition. It must be a negative or positive non-zero value. Does not accept chaining expressions. | Integer | Yes | n/a | `for` loop input example ``` - name: "CalculateFileUploadLatencies" action: "ExecutePowerShell" loop: for: start: 100000 end: 1000000 updateBy: 100000 inputs: commands: - | $f = new-object System.IO.FileStream c:\temp\test{{ loop.index }}.txt, Create, ReadWrite $f.SetLength({{ loop.value }}MB) $f.Close() - c:\users\administrator\downloads\latencyTest.exe --file c:\temp\test{{ loop.index }}.txt - AWS s3 cp c:\users\administrator\downloads\latencyMetrics.json s3://bucket/latencyMetrics.json - | Remove-Item -Path c:\temp\test{{ loop.index }}.txt Remove-Item -Path c:\users\administrator\downloads\latencyMetrics.json ``` ### `forEach` loop with input list The `forEach` loop iterates on an explicit list of values, which can be strings and chained expressions. `forEach` loop with input list schema ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: - "string" inputs: ... ``` **`forEach` loop with input list input** | Field | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `name` | Unique name of the loop. It must be unique compared to other loop names in the same phase. | String | No | "" | | List of strings of `forEach` loop | List of strings for iteration. Accepts chained expressions as strings in the list. Chained expressions must be enclosed by double quotes for the YAML compiler to correctly interpret them. | List of strings | Yes | n/a | `forEach` loop with input list example 1 ``` - name: "ExecuteCustomScripts" action: "ExecuteBash" loop: name: BatchExecLoop forEach: - /tmp/script1.sh - /tmp/script2.sh - /tmp/script3.sh inputs: commands: - echo "Count {{ BatchExecLoop.index }}" - sh "{{ loop.value }}" - | retVal=$? if [ $retVal -ne 0 ]; then echo "Failed" else echo "Passed" fi ``` `forEach` loop with input list example 2 ``` - name: "RunMSIWithDifferentArgs" action: "ExecuteBinary" loop: name: MultiArgLoop forEach: - "ARG1=C:\Users ARG2=1" - "ARG1=C:\Users" - "ARG1=C:\Users ARG3=C:\Users\Administrator\Documents\f1.txt" inputs: commands: path: "c:\users\administrator\downloads\runner.exe" args: - "{{ MultiArgLoop.value }}" ``` `forEach` loop with input list example 3 ``` - name: "DownloadAllBinaries" action: "S3Download" loop: name: MultiArgLoop forEach: - "bin1.exe" - "bin10.exe" - "bin5.exe" inputs: - source: "s3://bucket/{{ loop.value }}" destination: "c:\temp\{{ loop.value }}" ``` ### `forEach` loop with delimited list The loop iterates over a string containing values separated by a delimiter. To iterate over the string’s constituents, AWSTOE uses the delimiter to split the string into an array suitable for iteration. `forEach` loop with delimited list schema ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: list: "string" delimiter: ".,;:\n\t -_" inputs: ... ``` **`forEach` loop with delimited list input** | Field | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `name` | Unique name given to the loop. It should be unique when compared to other loop names in the same phase. | String | No | "" | | `list` | A string that is composed of constituent strings joined by a common delimiter character. Also accepts chained expressions. In case of chained expressions, ensure that those are enclosed by double quotes for correct interpretation by the YAML compiler. | String | Yes | n/a | | `delimiter` | Character used to separate out strings within a block. Default is the comma character. Only one delimiter character is allowed from the given list: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-looping-constructs.html) Chaining expressions cannot be used. | String | No | Comma: "," | **Note** The value of `list` is treated as an immutable string. If the source of `list` is changed during runtime, it will not be reflected during the run. `forEach` loop with delimited list example 1 This example uses the following chaining expression pattern to refer to another step's output: `..[inputs | outputs].`. ``` - name: "RunMSIs" action: "ExecuteBinary" loop: forEach: list: "{{ build.GetAllMSIPathsForInstallation.outputs.stdout }}" delimiter: "\n" inputs: commands: path: "{{ loop.value }}" ``` `forEach` loop with delimited list example 2 ``` - name: "UploadMetricFiles" action: "S3Upload" loop: forEach: list: "/tmp/m1.txt,/tmp/m2.txt,/tmp/m3.txt,..." inputs: commands: - source: "{{ loop.value }}" destination: "s3://bucket/key/{{ loop.value }}" ``` ## Step fields Loops are part of a step. Any field related to the running of a step is not applied to individual iterations. Step fields apply only at the step level, as follows: + *timeoutSeconds* – All iterations of the loop must be run within the time period specified by this field. If the loop run times out, then AWSTOE runs the retry policy of the step and resets the timeout parameter for each new attempt. If the loop run exceeds the timeout value after reaching the maximum number of retries, the failure message of the step states that the loop run had timed out. + *onFailure* – Failure handling is applied to the step as follows: + If *onFailure* is set to `Abort`, AWSTOE exits the loop and retries the step according to the retry policy. After the maximum number of retry attempts, AWSTOE marks the current step as failed, and stops running the process. AWSTOE sets the status code for the parent phase and document to `Failed`. **Note** No further steps run after the failed step. + If *onFailure* is set to `Continue`, AWSTOE exits the loop and retries the step according to the retry policy. After the maximum number of retry attempts, AWSTOE marks the current step as failed, and continues on to run the next step. AWSTOE sets the status code for the parent phase and document to `Failed`. + If *onFailure* is set to `Ignore`, AWSTOE exits the loop and retries the step according to the retry policy. After the maximum number of retry attempts, AWSTOE marks the current step as `IgnoredFailure`, and continues on to run the next step. AWSTOE sets the status code for the parent phase and document to `SuccessWithIgnoredFailure`. **Note** This is still considered a successful run, but includes information to let you know that one or more steps failed and were ignored. + *maxAttempts * – For every retry, the entire step and all iterations are run from the beginning. + *status* – The overall status of the running of a step.`status` does not represent the status of individual iterations. The status of a step with loops is determined as follows: + If a single iteration fails to run, the status of a step points to a failure. + If all iterations succeed, the status of a step points to a success. + *startTime * – The overall start time of the running of a step. Does not represent the start time of individual iterations. + *endTime * – The overall end time of the running of a step. Does not represent the end time of individual iterations. + *failureMessage * – Includes the iteration indices that failed in case of non-timeout errors. In case of timeout errors, the message states that the loop run has failed. Individual error messages for each iteration are not provided to minimize the size of failure messages. ## Step and iteration outputs Every iteration contains an output. At the end of a loop run, AWSTOE consolidates all successful iteration outputs in `detailedOutput.json`. The consolidated outputs are a collation of values that belong to the corresponding output keys as defined in the output schema of the action module. The following example shows how the outputs are consolidated: **Output of `ExecuteBash` for Iteration 1** ``` { "stdout":"Hello" } ``` **Output of `ExecuteBash` for Iteration 2** ``` { "stdout":"World" } ``` **Output of `ExecuteBash` for Step** ``` { "stdout":"Hello\nWorld" } ``` For example, `ExecuteBash`, `ExecutePowerShell`, and `ExecuteBinary` are action modules which return `STDOUT` as the action module output. `STDOUT` messages are joined with the new line character to produce the overall output of the step in `detailedOutput.json`. AWSTOE will not consolidate the outputs of unsuccessful iterations. # Action modules supported by AWSTOE component manager Image building services, such as EC2 Image Builder, use AWSTOE action modules to help configure the EC2 instances that are used for building and testing customized machine images. This section describes the features of commonly used AWSTOE action modules, and how to configure them, including examples. Components are authored with plaintext YAML documents. For more information about document syntax, see [Use the AWSTOE component document framework for custom components](toe-use-documents.md). **Note** All action modules use the same account as the Systems Manager agent when they run, which is `root` on Linux, and `NT Authority\SYSTEM` on Windows. The following cross-reference categorizes action modules by the type of actions that they perform.   **General execution** + [Assert (Linux, Windows, macOS)](#action-modules-assertion) + [ExecuteBash (Linux, macOS)](#action-modules-executebash) + [ExecuteBinary (Linux, Windows, macOS)](#action-modules-executebinary) + [ExecuteDocument (Linux, Windows, macOS)](#action-modules-executedocument) + [ExecutePowerShell (Windows)](#action-modules-executepowershell)   **File download and upload** + [S3Download (Linux, Windows, macOS)](#action-modules-s3download) + [S3Upload (Linux, Windows, macOS)](#action-modules-s3upload) + [WebDownload (Linux, Windows, macOS)](#action-modules-webdownload)   **File system operations** + [AppendFile (Linux, Windows, macOS)](#action-modules-appendfile) + [CopyFile (Linux, Windows, macOS)](#action-modules-copyfile) + [CopyFolder (Linux, Windows, macOS)](#action-modules-copyfolder) + [CreateFile (Linux, Windows, macOS)](#action-modules-createfile) + [CreateFolder (Linux, Windows, macOS)](#action-modules-createfolder) + [CreateSymlink (Linux, Windows, macOS)](#action-modules-createsymlink) + [DeleteFile (Linux, Windows, macOS)](#action-modules-deletefile) + [DeleteFolder (Linux, Windows, macOS)](#action-modules-deletefolder) + [ListFiles (Linux, Windows, macOS)](#action-modules-listfiles) + [MoveFile (Linux, Windows, macOS)](#action-modules-movefile) + [MoveFolder (Linux, Windows, macOS)](#action-modules-movefolder) + [ReadFile (Linux, Windows, macOS)](#action-modules-readfile) + [SetFileEncoding (Linux, Windows, macOS)](#action-modules-setfileencoding) + [SetFileOwner (Linux, Windows, macOS)](#action-modules-setfileowner) + [SetFolderOwner (Linux, Windows, macOS)](#action-modules-setfolderowner) + [SetFilePermissions (Linux, Windows, macOS)](#action-modules-setfilepermissions) + [SetFolderPermissions (Linux, Windows, macOS)](#action-modules-setfolderpermissions)   **Software installation actions** + [InstallMSI (Windows)](#action-modules-install-msi) + [UninstallMSI (Windows)](#action-modules-uninstall-msi)   **System actions** + [Reboot (Linux, Windows)](#action-modules-reboot) + [SetRegistry (Windows)](#action-modules-setregistry) + [UpdateOS (Linux, Windows)](#action-modules-updateos) ## General execution modules The following section contains details for action modules that run commands and control execution workflow. **Topics** + [Assert (Linux, Windows, macOS)](#action-modules-assertion) + [ExecuteBash (Linux, macOS)](#action-modules-executebash) + [ExecuteBinary (Linux, Windows, macOS)](#action-modules-executebinary) + [ExecuteDocument (Linux, Windows, macOS)](#action-modules-executedocument) + [ExecutePowerShell (Windows)](#action-modules-executepowershell) ### Assert (Linux, Windows, macOS) The **Assert** action module performs value comparisons using [Comparison operators](toe-comparison-operators.md) or [Logical operators](toe-logical-operators.md) as input. The result of the operator expression (true or false) indicates the overall success or failure status for the step. If the comparison or logical operator expression evaluates to `true`, the step is marked as `Success`. Otherwise, the step is marked as `Failed`. If the step fails, the `onFailure` parameter decides the outcome of the step. **Input** | Key name | Description | Type | Required | | --- | --- | --- | --- | | input | Contains a single comparison or logical operator. Note, logical operators can contain more than one comparison operator. | This is variable, depending on the operator | Yes | **Input example: A simple comparison using the `stringEquals` comparison operator** This example evaluates to `true`. ``` - name: StringComparison action: Assert inputs: stringEquals: '2.1.1' value: '{{ validate.ApplicationVersion.outputs.stdout }}' ``` **Input example: Regex comparisons using the `patternMatches` comparison operator** These examples all evaluate to `true`. ``` - name: Letters only action: Assert inputs: patternMatches: '^[a-zA-Z]+$' value: 'ThisIsOnlyLetters' - name: Letters and spaces only action: Assert inputs: patternMatches: '^[a-zA-Z\s]+$' value: 'This text contains spaces' - name: Numbers only action: Assert inputs: patternMatches: '^[0-9]+$' value: '1234567890' ``` **Input example: Nested comparisons with logical operators and chained variables** The following example demonstrates nested comparisons with logical operators that use comparisons with chained variables. The `Assert` evaluates to `true` if either of the following are true: + The `ApplicationVersion` is greater than `2.0` and the `CPUArchitecture` equals `arm64`. + The `CPUArchitecture` equals `x86_64`. ``` - name: NestedComparisons action: Assert inputs: or: # <- first level deep - and: # <- second level deep - numberGreaterThan: 2.0 # <- third level deep value: '{{ validate.ApplicationVersion.outputs.stdout }}' - stringEquals: 'arm64' value: '{{ validate.CPUArchitecture.outputs.stdout }}' - stringEquals: 'x86_64' value: '{{ validate.CPUArchitecture.outputs.stdout }}' ``` **Output:** The output of an `Assert` is success or failure of the step. ### ExecuteBash (Linux, macOS) The **ExecuteBash** action module allows you to run bash scripts with inline shell code/commands. This module supports Linux. All of the commands and instructions that you specify in the commands block are converted into a file (for example, `input.sh`) and run with the bash shell. The result of running the shell file is the exit code of the step. The **ExecuteBash** module handles system restarts if the script exits with an exit code of `194`. When initiated, the application performs one of the following actions: + The application hands the exit code to the caller if it is run by the Systems Manager Agent. The Systems Manager Agent handles the system reboot and runs the same step that initiated the restart, as described in [Rebooting Managed Instance from Scripts](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html). + The application saves the current `executionstate`, configures a restart trigger to rerun the application, and restarts the system. After system restart, the application runs the same step that initiated the restart. If you require this functionality, you must write idempotent scripts that can handle multiple invocations of the same shell command. **Input** | Key name | Description | Type | Required | | --- | --- | --- | --- | | commands | Contains a list of instructions or commands to run as per bash syntax. Multi-line YAML is allowed. | List | Yes | **Input example: Before and after a reboot** ``` name: ExitCode194Example description: This shows how the exit code can be used to restart a system with ExecuteBash schemaVersion: 1.0 phases: - name: build steps: - name: RestartTrigger action: ExecuteBash inputs: commands: - | REBOOT_INDICATOR=/var/tmp/reboot-indicator if [ -f "${REBOOT_INDICATOR}" ]; then echo 'The reboot file exists. Deleting it and exiting with success.' rm "${REBOOT_INDICATOR}" exit 0 fi echo 'The reboot file does not exist. Creating it and triggering a restart.' touch "${REBOOT_INDICATOR}" exit 194 ``` **Output** | Field | Description | Type | | --- | --- | --- | | stdout | Standard output of command execution. | string | If you start a reboot and return exit code `194` as part of the action module, the build will resume at the same action module step that initiated the reboot. If you start a reboot without the exit code, the build process may fail. **Output example: Before reboot (first time through document)** ``` { “stdout”: “The reboot file does not exist. Creating it and triggering a restart." } ``` **Output example: After reboot, (second time through document)** ``` { “stdout”: “The reboot file exists. Deleting it and exiting with success." } ``` ### ExecuteBinary (Linux, Windows, macOS) The **ExecuteBinary** action module allows you to run binary files with a list of command-line arguments. The **ExecuteBinary** module handles system restarts if the binary file exits with an exit code of `194` (Linux) or `3010` (Windows). When this happens, the application performs one of the following actions: + The application hands the exit code to the caller if it is run by the Systems Manager Agent. The Systems Manager Agent handles restarting the system and runs the same step that initiated the restart, as described in [Rebooting Managed Instance from Scripts](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html). + The application saves the current `executionstate`, configures a restart trigger to rerun the application, and restarts the system. After the system restarts, the application runs the same step that initiated the restart. If you require this functionality, you must write idempotent scripts that can handle multiple invocations of the same shell command. **Input** | Key name | Description | Type | Required | | --- | --- | --- | --- | | path | The path to the binary file for execution. | String | Yes | | arguments | Contains a list of command-line arguments to use when running the binary. | String List | No | **Input example: install .NET** ``` - name: "InstallDotnet" action: ExecuteBinary inputs: path: C:\PathTo\dotnet_installer.exe arguments: - /qb - /norestart ``` **Output** | Field | Description | Type | | --- | --- | --- | | stdout | Standard output of command execution. | string | **Output example** ``` { "stdout": "success" } ``` ### ExecuteDocument (Linux, Windows, macOS) The **ExecuteDocument** action module adds support for nested component documents, running multiple component documents from one document. AWSTOE validates the document that is passed in the input parameter at run time. **Restrictions** + This action module runs one time, with no retries allowed, and no option to set timeout limits. **ExecuteDocument** sets the following default values, and returns an error if you try to change them. + `timeoutSeconds`: -1 + `maxAttempts`: 1 **Note** You can leave these values blank, and AWSTOE uses the default values. + Document nesting is allowed, up to three levels deep, but no more than that. Three levels of nesting translates to four document levels, as the top level isn't nested. In this scenario, the lowest level document must not call any other documents. + Cyclic execution of component documents is not allowed. Any document that calls itself outside of a looping construct, or that calls another document higher up in the current chain of execution, initiates a cycle that can result in an endless loop. When AWSTOE detects a cyclic execution, it stops the execution and records the failure. ![\[Nesting level restrictions for the ExecuteDocument action module.\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/images/toe-component-document-nesting.png) If a component document tries to run itself, or to run any of the component documents that are higher up in the current chain of execution, the execution fails. **Input** | Key name | Description | Type | Required | | --- | --- | --- | --- | | document | Path of component document. Valid options include: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) | String | Yes | | document-s3-bucket-owner | The account ID of the S3 bucket owner for the S3 bucket where component documents are stored. *(Recommended if you are using S3 URIs in your component document.)* | String | No | | phases | Phases to run in the component document, expressed as a comma-separated list. If no phases are specified, then all phases run. | String | No | | parameters | Input parameters that are passed in to the component document at runtime as key value pairs. | Parameter Map List | No | **Parameter map input** | Key name | Description | Type | Required | | --- | --- | --- | --- | | name | The name of the input parameter to pass to the component document that the **ExecuteDocument** action module is running. | String | Yes | | value | The value of the input parameter. | String | Yes | **Input examples** The following examples show variations of the inputs for your component document, depending on your installation path. **Input example: Local document path** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument inputs: document: Sample-1.yaml phases: build parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **Input example: S3 URI as a document path** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument inputs: document: s3://my-bucket/Sample-1.yaml document-s3-bucket-owner: 123456789012 phases: build,validate parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **Input example: EC2 Image Builder component ARN as a document path** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument inputs: document: arn:aws:imagebuilder:us-west-2:aws:component/Sample-Test/1.0.0 phases: test parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **Using a ForEach loop to run documents** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument loop: name: 'myForEachLoop' forEach: - Sample-1.yaml - Sample-2.yaml inputs: document: "{{myForEachLoop.value}}" phases: test parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **Using a For loop to run documents** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument loop: name: 'myForLoop' for: start: 1 end: 2 updateBy: 1 inputs: document: "Sample-{{myForLoop.value}}.yaml" phases: test parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **Output** AWSTOE creates an output file called `detailedoutput.json` every time it runs. The file contains details about every phase and step of every component document that is invoked while it's running. For the **ExecuteDocument** action module, you can find a brief runtime summary in the `outputs` field, and details about the phases, steps, and documents that it runs in the `detailedOutput`. ``` { \"executedStepCount\":1,\"executionId\":\"97054e22-06cc-11ec-9b14-acde48001122\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\" }", ``` Each component document's output summary object contains the following details, as shown here, with sample values: + executedStepCount":1 + "executionId":"12345a67-89bc-01de-2f34-abcd56789012" + "failedStepCount":0 + "failureMessage":"" + "ignoredFailedStepCount":0 + "logUrl":"" + "status":"success" **Output example** The following example shows output from the **ExecuteDocument** action module when a nested execution occurs. In this example, the `main.yaml` component document successfully runs the `Sample-1.yaml` component document. ``` { "executionId": "12345a67-89bc-01de-2f34-abcd56789012", "status": "success", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "documents": [ { "name": "", "filePath": "main.yaml", "status": "success", "description": "", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "phases": [ { "name": "build", "status": "success", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "steps": [ { "name": "ExecuteNestedDocument", "status": "success", "failureMessage": "", "timeoutSeconds": -1, "onFailure": "Abort", "maxAttempts": 1, "action": "ExecuteDocument", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "inputs": "[{\"document\":\"Sample-1.yaml\",\"document-s3-bucket-owner\":\"\",\"phases\":\"\",\"parameters\":null}]", "outputs": "[{\"executedStepCount\":1,\"executionId\":\"98765f43-21ed-09cb-8a76-fedc54321098\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\"}]", "loop": null, "detailedOutput": [ { "executionId": "98765f43-21ed-09cb-8a76-fedc54321098", "status": "success", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "documents": [ { "name": "", "filePath": "Sample-1.yaml", "status": "success", "description": "", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "phases": [ { "name": "build", "status": "success", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "steps": [ { "name": "ExecuteBashStep", "status": "success", "failureMessage": "", "timeoutSeconds": 7200, "onFailure": "Abort", "maxAttempts": 1, "action": "ExecuteBash", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "inputs": "[{\"commands\":[\"echo \\\"Hello World!\\\"\"]}]", "outputs": "[{\"stdout\":\"Hello World!\"}]", "loop": null, "detailedOutput": null }] }] }] }] }] }] }] } ``` ### ExecutePowerShell (Windows) The **ExecutePowerShell** action module allows you to run PowerShell scripts with inline shell code/commands. This module supports the Windows platform and Windows PowerShell. All of the commands/instructions specified in the commands block are converted into a script file (for example, `input.ps1`) and run using Windows PowerShell. The result of running the shell file is the exit code. The **ExecutePowerShell** module handles system restarts if the shell command exits with an exit code of `3010`. When initiated, the application performs one of the following actions: + Hands the exit code to the caller if run by the Systems Manager Agent. The Systems Manager Agent handles the system reboot and runs the same step that initiated the restart, as described in [Rebooting Managed Instance from Scripts](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html). + Saves the current `executionstate`, configures a restart trigger to rerun the application, and reboots the system. After system restart, the application runs the same step that initiated the restart. If you require this functionality, you must write idempotent scripts that can handle multiple invocations of the same shell command. **Input** | Key name | Description | Type | Required | | --- | --- | --- | --- | | commands | Contains a list of instructions or commands to run as per PowerShell syntax. Multi-line YAML is allowed. | String List | Yes. Must specify `commands` or `file`, not both. | | file | Contains the path to a PowerShell script file. PowerShell will run against this file using the -file command line argument. The path must point to a .ps1 file. | String | Yes. Must specify `commands` or `file`, not both. | **Input example: Before and after a reboot** ``` name: ExitCode3010Example description: This shows how the exit code can be used to restart a system with ExecutePowerShell schemaVersion: 1.0 phases: - name: build steps: - name: RestartTrigger action: ExecutePowerShell inputs: commands: - | $rebootIndicator = Join-Path -Path $env:SystemDrive -ChildPath 'reboot-indicator' if (Test-Path -Path $rebootIndicator) { Write-Host 'The reboot file exists. Deleting it and exiting with success.' Remove-Item -Path $rebootIndicator -Force | Out-Null [System.Environment]::Exit(0) } Write-Host 'The reboot file does not exist. Creating it and triggering a restart.' New-Item -Path $rebootIndicator -ItemType File | Out-Null [System.Environment]::Exit(3010) ``` **Output** | Field | Description | Type | | --- | --- | --- | | stdout | Standard output of command execution. | string | If you run a reboot and return exit code `3010` as part of the action module, the build will resume at the same action module step that initiated the reboot. If you run a reboot without the exit code, the build process may fail. **Output example: Before reboot (first time through document)** ``` { “stdout”: “The reboot file does not exist. Creating it and triggering a restart." } ``` **Output example: After reboot, (second time through document)** ``` { “stdout”: “The reboot file exists. Deleting it and exiting with success." } ``` ## File download and upload modules The following section contains details for action modules that upload or download files. **Topics** + [S3Download (Linux, Windows, macOS)](#action-modules-s3download) + [S3Upload (Linux, Windows, macOS)](#action-modules-s3upload) + [WebDownload (Linux, Windows, macOS)](#action-modules-webdownload) ### S3Download (Linux, Windows, macOS) With the `S3Download` action module, you can download an Amazon S3 object, or a set of objects, to a local file or folder that you specify with the `destination` path. If any file already exists in the specified location, and the `overwrite` flag is set to true, `S3Download` overwrites the file. Your `source` location can point to a specific object in Amazon S3, or you can use a key prefix with an asterisk wildcard (`*`) to download a set of objects that match the key prefix path. When you specify a key prefix in your `source` location, the `S3Download` action module downloads everything that matches the prefix (files and folders included). Make sure that the key prefix ends with a forward-slash, followed by an asterisk (`/*`), so that you download everything that matches the prefix. For example: `s3://my-bucket/my-folder/*`. If the `S3Download` action for a specified key prefix fails during a download, the folder content is not rolled back to its state prior to the failure. The destination folder remains as it was at the time of the failure. **Supported use cases** The `S3Download` action module supports the following use cases: + The Amazon S3 object is downloaded to a local folder, as specified in the download path. + Amazon S3 objects (with a key prefix in the Amazon S3 file path) are downloaded to the specified local folder, which recursively copies all Amazon S3 objects that match the key prefix to the local folder. **IAM requirements** The IAM role that you associate with your instance profile must have permissions to run the `S3Download` action module. The following IAM policies must be attached to the IAM role that is associated with the instance profile: + **Single file**: `s3:GetObject` against the bucket/object (for example, `arn:aws:s3:::BucketName/*`). + **Multiple files**: `s3:ListBucket` against the bucket/object (for example, `arn:aws:s3:::BucketName`) and `s3:GetObject` against the bucket/object (for example, `arn:aws:s3:::BucketName/*`). **Input** | Key | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `source` | The Amazon S3 bucket that is the source for your download. You can specify a path to a specific object, or use a key prefix, that ends with a forward-slash, followed by an asterisk wildcard (`/*`), to download a set of objects that match the key prefix. | String | Yes | N/A | | `destination` | The local path where the Amazon S3 objects are downloaded. To download a single file, you must specify the file name as part of the path. For example, `/myfolder/package.zip`. | String | Yes | N/A | | `expectedBucketOwner` | Expected owner account ID of the bucket provided in the `source` path. We recommend that you verify the ownership of the Amazon S3 bucket specified in the source. | String | No | N/A | | `overwrite` | When set to true, if a file of the same name already exists in the destination folder for the specified local path, the download file overwrites the local file. When set to false, the existing file on the local system is protected from being overwritten, and the action module fails with a download error. For example, `Error: S3Download: File already exists and "overwrite" property for "destination" file is set to false. Cannot download.` | Boolean | No | true | **Note** For the following examples, the Windows folder path can be replaced with a Linux path. For example, `C:\myfolder\package.zip` can be replaced with `/myfolder/package.zip`. **Input example: copy an Amazon S3 object to a local file** The following example shows how to copy an Amazon S3 object to a local file. ``` - name: DownloadMyFile action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip destination: C:\myfolder\package.zip expectedBucketOwner: 123456789022 overwrite: false - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip destination: C:\myfolder\package.zip expectedBucketOwner: 123456789022 overwrite: true - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip destination: C:\myfolder\package.zip expectedBucketOwner: 123456789022 ``` **Input example: copy all Amazon S3 objects in an Amazon S3 bucket with key prefix to a local folder** The following example shows how to copy all Amazon S3 objects in an Amazon S3 bucket with the key prefix to a local folder. Amazon S3 has no concept of a folder, therefore all objects that match the key prefix are copied. The maximum number of objects that can be downloaded is 1000. ``` - name: MyS3DownloadKeyprefix action: S3Download maxAttempts: 3 inputs: - source: s3://amzn-s3-demo-source-bucket/path/to/* destination: C:\myfolder\ expectedBucketOwner: 123456789022 overwrite: false - source: s3://amzn-s3-demo-source-bucket/path/to/* destination: C:\myfolder\ expectedBucketOwner: 123456789022 overwrite: true - source: s3://amzn-s3-demo-source-bucket/path/to/* destination: C:\myfolder\ expectedBucketOwner: 123456789022 ``` **Output** None. ### S3Upload (Linux, Windows, macOS) With the **S3Upload** action module, you can upload a file from a source file or folder to an Amazon S3 location. You can use a wildcard (`*`) in the path specified for your source location to upload all of the files whose path matches the wildcard pattern. If the recursive **S3Upload** action fails, any files that have already been uploaded will remain in the destination Amazon S3 bucket. **Supported use cases** + Local file to Amazon S3 object. + Local files in folder (with wildcard) to Amazon S3 key prefix. + Copy local folder (must have `recurse` set to `true`) to Amazon S3 key prefix. **IAM requirements** The IAM role that you associate with your instance profile must have permissions to run the `S3Upload` action module. The following IAM policy must be attached to the IAM role that is associated with the instance profile. The policy must grant `s3:PutObject` permissions to the target Amazon S3 bucket. For example, `arn:aws:s3:::BucketName/*`). **Input** | Key | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | `source` | The local path where source files/folders originate. The `source` supports an asterisk wildcard (`*`). | String | Yes | N/A | | `destination` | The path for the destination Amazon S3 bucket where source files/folders are uploaded. | String | Yes | N/A | | `recurse` | When set to `true`, performs **S3Upload** recursively. | String | No | `false` | | `expectedBucketOwner` | The expected owner account ID for the Amazon S3 bucket specified in the destination path. We recommend that you verify the ownership of the Amazon S3 bucket specified in the destination. | String | No | N/A | **Input example: copy a local file to an Amazon S3 object** The following example shows how to copy a local file to an Amazon S3 object. ``` - name: MyS3UploadFile action: S3Upload onFailure: Abort maxAttempts: 3 inputs: - source: C:\myfolder\package.zip destination: s3://amzn-s3-demo-destination-bucket/path/to/package.zip expectedBucketOwner: 123456789022 ``` **Input example: copy all files in a local folder to an Amazon S3 bucket with key prefix** The following example shows how to copy all files in the local folder to an Amazon S3 bucket with key prefix. This example does not copy sub-folders or their contents because `recurse` is not specified, and it defaults to `false`. ``` - name: MyS3UploadMultipleFiles action: S3Upload onFailure: Abort maxAttempts: 3 inputs: - source: C:\myfolder\* destination: s3://amzn-s3-demo-destination-bucket/path/to/ expectedBucketOwner: 123456789022 ``` **Input example: copy all files and folders recursively from a local folder to an Amazon S3 bucket** The following example shows how to copy all files and folders recursively from a local folder to an Amazon S3 bucket with key prefix. ``` - name: MyS3UploadFolder action: S3Upload onFailure: Abort maxAttempts: 3 inputs: - source: C:\myfolder\* destination: s3://amzn-s3-demo-destination-bucket/path/to/ recurse: true expectedBucketOwner: 123456789022 ``` **Output** None. ### WebDownload (Linux, Windows, macOS) The **WebDownload** action module allows you to download files and resources from a remote location over the HTTP/HTTPS protocol (*HTTPS is recommended*). There are no limits on the number or size of downloads. This module handles retry and exponential backoff logic. Each download operation is allocated a maximum of 5 attempts to succeed according to user inputs. These attempts differ from those specified in the `maxAttempts` field of document `steps`, which are related to action module failures. This action module implicitly handles redirects. All HTTP status codes, except for `200`, result in an error. **Input** | Key name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | source | The valid HTTP/HTTPS URL (HTTPS is recommended), which follows the RFC 3986 standard. Chaining expressions are permitted. | String | Yes | N/A | | destination | An absolute or relative file or folder path on the local system. Folder paths must end with /. If they do not end with /, they will be treated as file paths. The module creates any required file or folder for successful downloads. Chaining expressions are permitted. | String | Yes | N/A | | overwrite | When enabled, overwrites any existing files on the local system with the downloaded file or resource. When not enabled, any existing files on the local system are not overwritten, and the action module fails with an error. When overwrite is enabled and checksum and algorithm are specified, then the action module downloads the file only if the checksum and the hash of any pre-existing files do not match. | Boolean | No | true | | checksum | When you specify the checksum, it is checked against the hash of the downloaded file that is generated with the supplied algorithm. For file verification to be enabled, both the checksum and the algorithm must be provided. Chaining expressions are permitted. | String | No | N/A | | algorithm | The algorithm used to calculate the checksum. The options are MD5, SHA1, SHA256, and SHA512. For file verification to be enabled, both the checksum and the algorithm must be provided. Chaining expressions are permitted. | String | No | N/A | | ignoreCertificateErrors | SSL certificate validation is ignored when enabled. | Boolean | No | false | **Output** | Key name | Description | Type | | --- | --- | --- | | destination | Newline character-delimited string that specifies the destination path where the downloaded files or resources are stored. | String | **Input example: download remote file to local destination** ``` - name: DownloadRemoteFile action: WebDownload maxAttempts: 3 inputs: - source: https://testdomain/path/to/java14.zip destination: C:\testfolder\package.zip ``` **Output:** ``` { "destination": "C:\\testfolder\\package.zip" } ``` **Input example: download more than one remote file to more than one local destination ** ``` - name: DownloadRemoteFiles action: WebDownload maxAttempts: 3 inputs: - source: https://testdomain/path/to/java14.zip destination: /tmp/java14_renamed.zip - source: https://testdomain/path/to/java14.zip destination: /tmp/create_new_folder_and_add_java14_as_zip/ ``` **Output:** ``` { "destination": "/tmp/create_new_folder/java14_renamed.zip\n/tmp/create_new_folder_and_add_java14_as_zip/java14.zip" } ``` **Input example: download one remote file without overwriting local destination, and download another remote file with file verification** ``` - name: DownloadRemoteMultipleProperties action: WebDownload maxAttempts: 3 inputs: - source: https://testdomain/path/to/java14.zip destination: C:\create_new_folder\java14_renamed.zip overwrite: false - source: https://testdomain/path/to/java14.zip destination: C:\create_new_folder_and_add_java14_as_zip\ checksum: ac68bbf921d953d1cfab916cb6120864 algorithm: MD5 overwrite: true ``` **Output:** ``` { "destination": "C:\\create_new_folder\\java14_renamed.zip\nC:\\create_new_folder_and_add_java14_as_zip\\java14.zip" } ``` **Input example: download remote file and ignore SSL certification validation** ``` - name: DownloadRemoteIgnoreValidation action: WebDownload maxAttempts: 3 inputs: - source: https://www.bad-ssl.com/resource destination: /tmp/downloads/ ignoreCertificateErrors: true ``` **Output:** ``` { "destination": "/tmp/downloads/resource" } ``` ## File system operations modules The following section contains details for action modules that perform file system operations. **Topics** + [AppendFile (Linux, Windows, macOS)](#action-modules-appendfile) + [CopyFile (Linux, Windows, macOS)](#action-modules-copyfile) + [CopyFolder (Linux, Windows, macOS)](#action-modules-copyfolder) + [CreateFile (Linux, Windows, macOS)](#action-modules-createfile) + [CreateFolder (Linux, Windows, macOS)](#action-modules-createfolder) + [CreateSymlink (Linux, Windows, macOS)](#action-modules-createsymlink) + [DeleteFile (Linux, Windows, macOS)](#action-modules-deletefile) + [DeleteFolder (Linux, Windows, macOS)](#action-modules-deletefolder) + [ListFiles (Linux, Windows, macOS)](#action-modules-listfiles) + [MoveFile (Linux, Windows, macOS)](#action-modules-movefile) + [MoveFolder (Linux, Windows, macOS)](#action-modules-movefolder) + [ReadFile (Linux, Windows, macOS)](#action-modules-readfile) + [SetFileEncoding (Linux, Windows, macOS)](#action-modules-setfileencoding) + [SetFileOwner (Linux, Windows, macOS)](#action-modules-setfileowner) + [SetFolderOwner (Linux, Windows, macOS)](#action-modules-setfolderowner) + [SetFilePermissions (Linux, Windows, macOS)](#action-modules-setfilepermissions) + [SetFolderPermissions (Linux, Windows, macOS)](#action-modules-setfolderpermissions) ### AppendFile (Linux, Windows, macOS) The **AppendFile** action module adds specified content to the preexisting content of a file. If the file encoding value is different from the default encoding (`utf-8`) value, then you can specify the file encoding value by using the `encoding` option. By default, `utf-16` and `utf-32` are assumed to use little-endian encoding. The action module returns an error when the following occurs: + The specified file does not exist at runtime. + You don't have write permissions to modify the file content. + The module encounters an error during the file operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The file path. | String | Yes | N/A | N/A | Yes | | content | The content to be appended to the file. | String | No | Empty string | N/A | Yes | | encoding | The encoding standard. | String | No | utf8 | utf8, utf-8, utf16,utf-16, utf16-LE, utf-16-LE utf16-BE, utf-16-BE, utf32, utf-32, utf32-LE,utf-32-LE, utf32-BE, and utf-32-BE. The value of the encoding option is case insensitive. | Yes | **Input example: append file without encoding (Linux)** ``` - name: AppendingFileWithOutEncodingLinux action: AppendFile inputs: - path: ./Sample.txt content: "The string to be appended to the file" ``` **Input example: append file without encoding (Windows)** ``` - name: AppendingFileWithOutEncodingWindows action: AppendFile inputs: - path: C:\MyFolder\MyFile.txt content: "The string to be appended to the file" ``` **Input example: append file with encoding (Linux)** ``` - name: AppendingFileWithEncodingLinux action: AppendFile inputs: - path: /FolderName/SampleFile.txt content: "The string to be appended to the file" encoding: UTF-32 ``` **Input example: append file with encoding (Windows)** ``` - name: AppendingFileWithEncodingWindows action: AppendFile inputs: - path: C:\MyFolderName\SampleFile.txt content: "The string to be appended to the file" encoding: UTF-32 ``` **Input example: append file with empty string (Linux)** ``` - name: AppendingEmptyStringLinux action: AppendFile inputs: - path: /FolderName/SampleFile.txt ``` **Input example: append file with empty string (Windows)** ``` - name: AppendingEmptyStringWindows action: AppendFile inputs: - path: C:\MyFolderName\SampleFile.txt ``` **Output** None. ### CopyFile (Linux, Windows, macOS) The **CopyFile** action module copies files from the specified source to the specified destination. By default, the module recursively creates the destination folder if it does not exist at runtime. If a file with the specified name already exists in the specified folder, the action module, by default, overwrites the existing file. You can override this default behavior by setting the overwrite option to `false`. When the overwrite option is set to `false`, and there is already a file in the specified location with the specified name, the action module will return an error. This option works the same as the `cp` command in Linux, which overwrites by default. The source file name can include a wildcard (`*`). Wildcard characters are accepted only after the last file path separator (`/` or `\`). If wildcard characters are included in the source file name, all of the files that match the wildcard are copied to the destination folder. If you want to move more than one file by using a wildcard character, the input to the `destination` option must end with a file path separator (`/` or `\`), which indicates that the destination input is a folder. If the destination file name is different from the source file name, you can specify the destination file name using the `destination` option. If you do not specify a destination file name, the name of the source file is used to create the destination file. Any text that follows the last file path separator (`/` or `\`) is treated as the file name. If you want to use the same file name as the source file, then the input of the `destination` option must end with a file path separator (`/` or `\`). The action module returns an error when the following occurs: + You do not have permission to create a file in the specified folder. + The source files do not exist at runtime. + There is already a folder with the specified file name and the `overwrite` option is set to `false`. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | source | The source file path. | String | Yes | N/A | N/A | Yes | | destination | The destination file path. | String | Yes | N/A | N/A | Yes | | overwrite | When set to false, the destination files will not be replaced when there is already a file in the specified location with the specified name. | Boolean | No | true | N/A | Yes | **Input example: copy a file (Linux)** ``` - name: CopyingAFileLinux action: CopyFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/destinationFile.txt ``` **Input example: copy a file (Windows)** ``` - name: CopyingAFileWindows action: CopyFile inputs: - source: C:\MyFolder\Sample.txt destination: C:\MyFolder\destinationFile.txt ``` **Input example: copy a file using the source file name (Linux)** ``` - name: CopyingFileWithSourceFileNameLinux action: CopyFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/ ``` **Input example: copy a file using the source file name (Windows)** ``` - name: CopyingFileWithSourceFileNameWindows action: CopyFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder\ ``` **Input example: copy a file using the wildcard character (Linux)** ``` - name: CopyingFilesWithWildCardLinux action: CopyFile inputs: - source: /Sample/MyFolder/Sample* destination: /MyFolder/ ``` **Input example: copy a file using the wildcard character (Windows)** ``` - name: CopyingFilesWithWildCardWindows action: CopyFile inputs: - source: C:\Sample\MyFolder\Sample* destination: C:\MyFolder\ ``` **Input example: copy a file without overwriting (Linux)** ``` - name: CopyingFilesWithoutOverwriteLinux action: CopyFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/destinationFile.txt overwrite: false ``` **Input example: copy a file without overwriting (Windows)** ``` - name: CopyingFilesWithoutOverwriteWindows action: CopyFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder\destinationFile.txt overwrite: false ``` **Output** None. ### CopyFolder (Linux, Windows, macOS) The **CopyFolder** action module copies a folder from the specified source to the specified destination. The input for the `source` option is the folder to copy, and the input for the `destination` option is the folder where the contents of the source folder are copied. By default, the module recursively creates the destination folder if it does not exist at runtime. If a folder with the specified name already exists in the specified folder, the action module, by default, overwrites the existing folder. You can override this default behavior by setting the overwrite option to `false`. When the overwrite option is set to `false`, and there is already a folder in the specified location with the specified name, the action module will return an error. The source folder name can include a wildcard (`*`). Wildcard characters are accepted only after the last file path separator (`/` or `\`). If wildcard characters are included in the source folder name, all of the folders that match the wildcard are copied to the destination folder. If you want to copy more than one folder by using a wildcard character, the input to the `destination` option must end with a file path separator (`/` or `\`), which indicates that the destination input is a folder. If the destination folder name is different from the source folder name, you can specify the destination folder name using the `destination` option. If you do not specify a destination folder name, the name of the source folder is used to create the destination folder. Any text that follows the last file path separator (`/` or `\`) is treated as the folder name. If you want to use the same folder name as the source folder, then the input of the `destination` option must end with a file path separator (`/` or `\`). The action module returns an error when the following occurs: + You do not have permission to create a folder in the specified folder. + The source folders do not exist at runtime. + There is already a folder with the specified folder name and the `overwrite` option is set to `false`. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | source | The source folder path. | String | Yes | N/A | N/A | Yes | | destination | The destination folder path. | String | Yes | N/A | N/A | Yes | | overwrite | When set to false, the destination folders will not be replaced when there is already a folder in the specified location with the specified name. | Boolean | No | true | N/A | Yes | **Input example: copy a folder (Linux)** ``` - name: CopyingAFolderLinux action: CopyFolder inputs: - source: /Sample/MyFolder/SampleFolder destination: /MyFolder/destinationFolder ``` **Input example: copy a folder (Windows)** ``` - name: CopyingAFolderWindows action: CopyFolder inputs: - source: C:\Sample\MyFolder\SampleFolder destination: C:\MyFolder\destinationFolder ``` **Input example: copy a folder using the source folder name (Linux)** ``` - name: CopyingFolderSourceFolderNameLinux action: CopyFolder inputs: - source: /Sample/MyFolder/SourceFolder destination: /MyFolder/ ``` **Input example: copy a folder using the source folder name (Windows)** ``` - name: CopyingFolderSourceFolderNameWindows action: CopyFolder inputs: - source: C:\Sample\MyFolder\SampleFolder destination: C:\MyFolder\ ``` **Input example: copy a folder using the wildcard character (Linux)** ``` - name: CopyingFoldersWithWildCardLinux action: CopyFolder inputs: - source: /Sample/MyFolder/Sample* destination: /MyFolder/ ``` **Input example: copy a folder using the wildcard character (Windows)** ``` - name: CopyingFoldersWithWildCardWindows action: CopyFolder inputs: - source: C:\Sample\MyFolder\Sample* destination: C:\MyFolder\ ``` **Input example: copy a folder without overwriting (Linux)** ``` - name: CopyingFoldersWithoutOverwriteLinux action: CopyFolder inputs: - source: /Sample/MyFolder/SourceFolder destination: /MyFolder/destinationFolder overwrite: false ``` **Input example: copy a folder without overwriting (Windows)** ``` - name: CopyingFoldersWithoutOverwrite action: CopyFolder inputs: - source: C:\Sample\MyFolder\SourceFolder destination: C:\MyFolder\destinationFolder overwrite: false ``` **Output** None. ### CreateFile (Linux, Windows, macOS) The **CreateFile** action module creates a file in a specified location. By default, if required, the module also recursively creates the parent folders. If the file already exists in the specified folder, the action module, by default, truncates or overwrites the existing file. You can override this default behavior by setting the overwrite option to `false`. When the overwrite option is set to `false`, and there is already a file in the specified location with the specified name, the action module will return an error. If the file encoding value is different from the default encoding (`utf-8`) value, then you can specify the file encoding value by using the `encoding` option. By default, `utf-16` and `utf-32` are assumed to use little-endian encoding. `owner`, `group`, and `permissions` are optional inputs. The input for `permissions` must be a string value. Files are created with default values when not provided. These options are not supported on Windows platforms. This action module validates and returns an error if the `owner`, `group`, and `permissions` options are used on Windows platforms. This action module can create a file the with permissions defined by the default `umask` value of the operating system. You must set the `umask` value if you want to override the default value. The action module returns an error when the following occurs: + You do not have permission to create a file or a folder in the specified parent folder. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The file path. | String | Yes | N/A | N/A | Yes | | content | The text content of the file. | String | No | N/A | N/A | Yes | | encoding | The encoding standard. | String | No | utf8 | utf8, utf-8, utf16,utf-16, utf16-LE, utf-16-LE utf16-BE, utf-16-BE, utf32, utf-32, utf32-LE,utf-32-LE, utf32-BE, and utf-32-BE. The value of the encoding option is case insensitive. | Yes | | owner | The user name or ID. | String | No | N/A | N/A | Not supported on Windows. | | group | The group name or ID. | String | No | The current user. | N/A | Not supported on Windows. | | permissions | The file permissions. | String | No | 0666 | N/A | Not supported on Windows. | | overwrite | If the name of the specified file already exists, setting this value to false prevents the file from being truncated or overwritten by default. | Boolean | No | true | N/A | Yes | **Input example: create a file without overwriting (Linux)** ``` - name: CreatingFileWithoutOverwriteLinux action: CreateFile inputs: - path: /home/UserName/Sample.txt content: The text content of the sample file. overwrite: false ``` **Input example: create a file without overwriting (Windows)** ``` - name: CreatingFileWithoutOverwriteWindows action: CreateFile inputs: - path: C:\Temp\Sample.txt content: The text content of the sample file. overwrite: false ``` **Input example: create a file with file properties** ``` - name: CreatingFileWithFileProperties action: CreateFile inputs: - path: SampleFolder/Sample.txt content: The text content of the sample file. encoding: UTF-16 owner: Ubuntu group: UbuntuGroup permissions: 0777 - path: SampleFolder/SampleFile.txt permissions: 755 - path: SampleFolder/TextFile.txt encoding: UTF-16 owner: root group: rootUserGroup ``` **Input example: create a file without file properties** ``` - name: CreatingFileWithoutFileProperties action: CreateFile inputs: - path: ./Sample.txt - path: Sample1.txt ``` **Input example: create an empty file to skip a section in the Linux clean up script** ``` - name: CreateSkipCleanupfile action: CreateFile inputs: - path: ``` For more information, see [Override the Linux clean up script](security-best-practices.md#override-linux-cleanup-script) **Output** None. ### CreateFolder (Linux, Windows, macOS) The **CreateFolder** action module creates a folder in a specified location. By default, if required, the module also recursively creates the parent folders. If the folder already exists in the specified folder, the action module, by default, truncates or overwrites the existing folder. You can override this default behavior by setting the overwrite option to `false`. When the overwrite option is set to `false`, and there is already a folder in the specified location with the specified name, the action module will return an error. `owner`, `group`, and `permissions` are optional inputs. The input for `permissions` must be a string value. These options are not supported on Windows platforms. This action module validates and returns an error if the `owner`, `group`, and `permissions` options are used on Windows platforms. This action module can create a folder the with permissions defined by the default `umask` value of the operating system. You must set the `umask` value if you want to override the default value. The action module returns an error when the following occurs: + You do not have permission to create a folder in the specified location. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The folder path. | String | Yes | N/A | N/A | Yes | | owner | The user name or ID. | String | No | The current user. | N/A | Not supported on Windows. | | group | The group name or ID. | String | No | The group of the current user. | N/A | Not supported on Windows. | | permissions | The folder permissions. | String | No | 0777 | N/A | Not supported on Windows. | | overwrite | If the name of the specified file already exists, setting this value to false prevents the file from being truncated or overwritten by default. | Boolean | No | true | N/A | Yes | **Input example: create a folder (Linux)** ``` - name: CreatingFolderLinux action: CreateFolder inputs: - path: /Sample/MyFolder/ ``` **Input example: create a folder (Windows)** ``` - name: CreatingFolderWindows action: CreateFolder inputs: - path: C:\MyFolder ``` **Input example: create a folder specifying folder properties** ``` - name: CreatingFolderWithFolderProperties action: CreateFolder inputs: - path: /Sample/MyFolder/Sample/ owner: SampleOwnerName group: SampleGroupName permissions: 0777 - path: /Sample/MyFolder/SampleFoler/ permissions: 777 ``` **Input example: create a folder that overwrites the existing folder, if there is one.** ``` - name: CreatingFolderWithOverwrite action: CreateFolder inputs: - path: /Sample/MyFolder/Sample/ overwrite: true ``` **Output** None. ### CreateSymlink (Linux, Windows, macOS) The **CreateSymlink** action module creates symbolic links, or files that contain a reference to another file. This module is not supported on Windows platforms. The input for the `path` and `target` options can be either an absolute or relative path. If the input for the `path` option is a relative path, it is replaced with the absolute path when the link is created. By default, when a link with the specified name already exists in the specified folder, the action module returns an error. You can override this default behavior by setting the `force` option to `true`. When the `force` option is set to `true`, the module will overwrite the existing link. If a parent folder does not exist, the action module creates the folder recursively, by default. The action module returns an error when the following occurs: + The target file does not exist at runtime. + A nonsymbolic link file with the specified name already exists. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The file path. | String | Yes | N/A | N/A | Not supported on Windows. | | target | The target file path to which the symbolic link points. | String | Yes | N/A | N/A | Not supported on Windows. | | force | Forces the creation of a link when a link with the same name already exists. | Boolean | No | false | N/A | Not supported on Windows. | **Input example: create symbolic link that forces the creation of a link** ``` - name: CreatingSymbolicLinkWithForce action: CreateSymlink inputs: - path: /Folder2/Symboliclink.txt target: /Folder/Sample.txt force: true ``` **Input example: create a symbolic link that does not force the creation of a link** ``` - name: CreatingSymbolicLinkWithOutForce action: CreateSymlink inputs: - path: Symboliclink.txt target: /Folder/Sample.txt ``` **Output** None. ### DeleteFile (Linux, Windows, macOS) The **DeleteFile** action module deletes a file or files in a specified location. The input of `path` should be a valid file path or a file path with a wild card character (`*`) in the file name. When wildcard characters are specified in the file name, all of the files within the same folder that match the wildcard will be deleted. The action module returns an error when the following occurs: + You do not have permission to perform delete operations. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The file path. | String | Yes | N/A | N/A | Yes | **Input example: delete a single file (Linux)** ``` - name: DeletingSingleFileLinux action: DeleteFile inputs: - path: /SampleFolder/MyFolder/Sample.txt ``` **Input example: delete a single file (Windows)** ``` - name: DeletingSingleFileWindows action: DeleteFile inputs: - path: C:\SampleFolder\MyFolder\Sample.txt ``` **Input example: delete a file that ends with "log" (Linux)** ``` - name: DeletingFileEndingWithLogLinux action: DeleteFile inputs: - path: /SampleFolder/MyFolder/*log ``` **Input example: delete a file that ends with "log" (Windows)** ``` - name: DeletingFileEndingWithLogWindows action: DeleteFile inputs: - path: C:\SampleFolder\MyFolder\*log ``` **Input example: delete all files in a specified folder (Linux)** ``` - name: DeletingAllFilesInAFolderLinux action: DeleteFile inputs: - path: /SampleFolder/MyFolder/* ``` **Input example: delete all files in a specified folder (Windows)** ``` - name: DeletingAllFilesInAFolderWindows action: DeleteFile inputs: - path: C:\SampleFolder\MyFolder\* ``` **Output** None. ### DeleteFolder (Linux, Windows, macOS) The **DeleteFolder** action module deletes folders. If the folder is not empty, you must set the `force` option to `true` to remove the folder and its contents. If you do not set the `force` option to `true`, and the folder you are trying to delete is not empty, the action module returns an error. The default value of the `force` option is `false`. The action module returns an error when the following occurs: + You do not have permission to perform delete operations. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The folder path. | String | Yes | N/A | N/A | Yes | | force | Removes the folder whether or not the folder is empty. | Boolean | No | false | N/A | Yes | **Input example: delete a folder that is not empty using the `force` option (Linux)** ``` - name: DeletingFolderWithForceOptionLinux action: DeleteFolder inputs: - path: /Sample/MyFolder/Sample/ force: true ``` **Input example: delete a folder that is not empty using the `force` option (Windows)** ``` - name: DeletingFolderWithForceOptionWindows action: DeleteFolder inputs: - path: C:\Sample\MyFolder\Sample\ force: true ``` **Input example: delete a folder (Linux)** ``` - name: DeletingFolderWithOutForceLinux action: DeleteFolder inputs: - path: /Sample/MyFolder/Sample/ ``` **Input example: delete a folder (Windows)** ``` - name: DeletingFolderWithOutForce action: DeleteFolder inputs: - path: C:\Sample\MyFolder\Sample\ ``` **Output** None. ### ListFiles (Linux, Windows, macOS) The **ListFiles** action module lists the files in a specified folder. When the recursive option is set to `true`, it lists the files in subfolders. This module does not list files in subfolders by default. To list all of the files with names that match a specified pattern, use the `fileNamePattern` option to provide the pattern. The `fileNamePattern` option accepts the wildcard (`*`) value. When the `fileNamePattern` is provided, all of the files that match the specified file name format are returned. The action module returns an error when the following occurs: + The specified folder does not exist at runtime. + You do not have permission to create a file or a folder in the specified parent folder. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The folder path. | String | Yes | N/A | N/A | Yes | | fileNamePattern | The pattern to match to list all files with names that match the pattern. | String | No | N/A | N/A | Yes | | recursive | Lists files in the folder recursively. | Boolean | No | false | N/A | Yes | **Input example: list files in specified folder (Linux)** ``` - name: ListingFilesInSampleFolderLinux action: ListFiles inputs: - path: /Sample/MyFolder/Sample ``` **Input example: list files in specified folder (Windows)** ``` - name: ListingFilesInSampleFolderWindows action: ListFiles inputs: - path: C:\Sample\MyFolder\Sample ``` **Input example: list files that end with "log" (Linux)** ``` - name: ListingFilesWithEndingWithLogLinux action: ListFiles inputs: - path: /Sample/MyFolder/ fileNamePattern: *log ``` **Input example: list files that end with "log" (Windows)** ``` - name: ListingFilesWithEndingWithLogWindows action: ListFiles inputs: - path: C:\Sample\MyFolder\ fileNamePattern: *log ``` **Input example: list files recursively** ``` - name: ListingFilesRecursively action: ListFiles inputs: - path: /Sample/MyFolder/ recursive: true ``` **Output** | Key name | Description | Type | | --- | --- | --- | | files | The list of files. | String | **Output example** ``` { "files": "/sample1.txt,/sample2.txt,/sample3.txt" } ``` ### MoveFile (Linux, Windows, macOS) The **MoveFile** action module moves files from the specified source to the specified destination. If the file already exists in the specified folder, the action module, by default, overwrites the existing file. You can override this default behavior by setting the overwrite option to `false`. When the overwrite option is set to `false`, and there is already a file in the specified location with the specified name, the action module will return an error. This option works the same as the `mv` command in Linux, which overwrites by default. The source file name can include a wildcard (`*`). Wildcard characters are accepted only after the last file path separator (`/` or `\`). If wildcard characters are included in the source file name, all of the files that match the wildcard are copied to the destination folder. If you want to move more than one file by using a wildcard character, the input to the `destination` option must end with a file path separator (`/` or `\`), which indicates that the destination input is a folder. If the destination file name is different from the source file name, you can specify the destination file name using the `destination` option. If you do not specify a destination file name, the name of the source file is used to create the destination file. Any text that follows the last file path separator (`/` or `\`) is treated as the file name. If you want to use the same file name as the source file, then the input of the `destination` option must end with a file path separator (`/` or `\`). The action module returns an error when the following occurs: + You do not have permission to create a file in the specified folder. + The source files do not exist at runtime. + There is already a folder with the specified file name and the `overwrite` option is set to `false`. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | source | The source file path. | String | Yes | N/A | N/A | Yes | | destination | The destination file path. | String | Yes | N/A | N/A | Yes | | overwrite | When set to false, the destination files will not be replaced when there is already a file in the specified location with the specified name. | Boolean | No | true | N/A | Yes | **Input example: move a file (Linux)** ``` - name: MovingAFileLinux action: MoveFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/destinationFile.txt ``` **Input example: move a file (Windows)** ``` - name: MovingAFileWindows action: MoveFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder\destinationFile.txt ``` **Input example: move a file using the source file name (Linux)** ``` - name: MovingFileWithSourceFileNameLinux action: MoveFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/ ``` **Input example: move a file using the source file name (Windows)** ``` - name: MovingFileWithSourceFileNameWindows action: MoveFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder ``` **Input example: move a file using a wildcard character (Linux)** ``` - name: MovingFilesWithWildCardLinux action: MoveFile inputs: - source: /Sample/MyFolder/Sample* destination: /MyFolder/ ``` **Input example: move a file using a wildcard character (Windows)** ``` - name: MovingFilesWithWildCardWindows action: MoveFile inputs: - source: C:\Sample\MyFolder\Sample* destination: C:\MyFolder ``` **Input example: move a file without overwriting (Linux)** ``` - name: MovingFilesWithoutOverwriteLinux action: MoveFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/destinationFile.txt overwrite: false ``` **Input example: move a file without overwriting (Windows)** ``` - name: MovingFilesWithoutOverwrite action: MoveFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder\destinationFile.txt overwrite: false ``` **Output** None. ### MoveFolder (Linux, Windows, macOS) The **MoveFolder** action module moves folders from the specified source to the specified destination. The input for the `source` option is the folder to move, and the input to the `destination` option is the folder where the contents of the source folders are moved. If the destination parent folder or the input to the `destination` option does not exist at runtime, the default behavior of the module is to recursively create the folder at the specified destination. If a folder with the same as the source folder already exists in the destination folder, the action module, by default, overwrites the existing folder. You can override this default behavior by setting the overwrite option to `false`. When the overwrite option is set to `false`, and there is already a folder in the specified location with the specified name, the action module will return an error. The source folder name can include a wildcard (`*`). Wildcard characters are accepted only after the last file path separator (`/` or `\`). If wildcard characters are included in the source folder name, all of the folders that match the wildcard are copied to the destination folder. If you want to move more than one folder by using a wildcard character, the input to the `destination` option must end with a file path separator (`/` or `\`), which indicates that the destination input is a folder. If the destination folder name is different from the source folder name, you can specify the destination folder name using the `destination` option. If you do not specify a destination folder name, the name of the source folder is used to create the destination folder. Any text that follows the last file path separator (`/` or `\`) is treated as the folder name. If you want to use the same folder name as the source folder, then the input of the `destination` option must end with a file path separator (`/` or `\`). The action module returns an error when the following occurs: + You do not have permission to create a folder in the destination folder. + The source folders do not exist at runtime. + There is already a folder with the specified name and the `overwrite` option is set to `false`. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | source | The source folder path. | String | Yes | N/A | N/A | Yes | | destination | The destination folder path. | String | Yes | N/A | N/A | Yes | | overwrite | When set to false, the destination folders will not be replaced when there is already a folder in the specified location with the specified name. | Boolean | No | true | N/A | Yes | **Input example: move a folder (Linux)** ``` - name: MovingAFolderLinux action: MoveFolder inputs: - source: /Sample/MyFolder/SourceFolder destination: /MyFolder/destinationFolder ``` **Input example: move a folder (Windows)** ``` - name: MovingAFolderWindows action: MoveFolder inputs: - source: C:\Sample\MyFolder\SourceFolder destination: C:\MyFolder\destinationFolder ``` **Input example: move a folder using the source folder name (Linux)** ``` - name: MovingFolderWithSourceFolderNameLinux action: MoveFolder inputs: - source: /Sample/MyFolder/SampleFolder destination: /MyFolder/ ``` **Input example: move a folder using the source folder name (Windows)** ``` - name: MovingFolderWithSourceFolderNameWindows action: MoveFolder inputs: - source: C:\Sample\MyFolder\SampleFolder destination: C:\MyFolder\ ``` **Input example: move a folder using a wildcard character (Linux)** ``` - name: MovingFoldersWithWildCardLinux action: MoveFolder inputs: - source: /Sample/MyFolder/Sample* destination: /MyFolder/ ``` **Input example: move a folder using a wildcard character (Windows)** ``` - name: MovingFoldersWithWildCardWindows action: MoveFolder inputs: - source: C:\Sample\MyFolder\Sample* destination: C:\MyFolder\ ``` **Input example: move a folder without overwriting (Linux)** ``` - name: MovingFoldersWithoutOverwriteLinux action: MoveFolder inputs: - source: /Sample/MyFolder/SampleFolder destination: /MyFolder/destinationFolder overwrite: false ``` **Input example: move a folder without overwriting (Windows)** ``` - name: MovingFoldersWithoutOverwriteWindows action: MoveFolder inputs: - source: C:\Sample\MyFolder\SampleFolder destination: C:\MyFolder\destinationFolder overwrite: false ``` **Output** None. ### ReadFile (Linux, Windows, macOS) The **ReadFile** action module reads the content of a text file of type string. This module can be used to read the content of a file for use in subsequent steps through chaining or for reading data to the `console.log` file. If the specified path is a symbolic link, this module returns the content of the target file. This module only supports text files. If the file encoding value is different from the default encoding (`utf-8`) value, then you can specify the file encoding value by using the `encoding` option. By default, `utf-16` and `utf-32` are assumed to use little-endian encoding. By default, this module cannot print the file content to the `console.log` file. You can override this setting by setting the `printFileContent` property to `true`. This module can return only the content of a file. It cannot parse files, such as Excel or JSON files. The action module returns an error when the following occurs: + The file does not exist at runtime. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The file path. | String | Yes | N/A | N/A | Yes | | encoding | The encoding standard. | String | No | utf8 | utf8, utf-8, utf16,utf-16, utf16-LE, utf-16-LE utf16-BE, utf-16-BE, utf32, utf-32, utf32-LE,utf-32-LE, utf32-BE, and utf-32-BE. The value of the encoding option is case insensitive. | Yes | | printFileContent | Prints the file content to the console.log file. | Boolean | No | false | N/A | Yes. | **Input example: read a file (Linux)** ``` - name: ReadingFileLinux action: ReadFile inputs: - path: /home/UserName/SampleFile.txt ``` **Input example: read a file (Windows)** ``` - name: ReadingFileWindows action: ReadFile inputs: - path: C:\Windows\WindowsUpdate.log ``` **Input example: read a file and specify encoding standard** ``` - name: ReadingFileWithFileEncoding action: ReadFile inputs: - path: /FolderName/SampleFile.txt encoding: UTF-32 ``` **Input example: read a file and print to the `console.log` file** ``` - name: ReadingFileToConsole action: ReadFile inputs: - path: /home/UserName/SampleFile.txt printFileContent: true ``` **Output** | Field | Description | Type | | --- | --- | --- | | content | The file content. | string | **Output example** ``` { "content" : "The file content" } ``` ### SetFileEncoding (Linux, Windows, macOS) The **SetFileEncoding** action module modifies the encoding property of an existing file. This module can convert file encoding from `utf-8` to a specified encoding standard. By default, `utf-16` and `utf-32` are assumed to be little-endian encoding. The action module returns an error when the following occurs: + You do not have permission to perform the specified modification. + The file does not exist at runtime. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The file path. | String | Yes | N/A | N/A | Yes | | encoding | The encoding standard. | String | No | utf8 | utf8, utf-8, utf16,utf-16, utf16-LE, utf-16-LE utf16-BE, utf-16-BE, utf32, utf-32, utf32-LE,utf-32-LE, utf32-BE, and utf-32-BE. The value of the encoding option is case insensitive. | Yes | **Input example: set file encoding property** ``` - name: SettingFileEncodingProperty action: SetFileEncoding inputs: - path: /home/UserName/SampleFile.txt encoding: UTF-16 ``` **Output** None. ### SetFileOwner (Linux, Windows, macOS) The **SetFileOwner** action module modifies the `owner` and`group` owner properties of an existing file. If the specified file is a symbolic link, the module modifies the `owner` property of the source file. This module is not supported on Windows platforms. This module accepts user and group names as inputs. If the group name is not provided, the module assigns the group owner of the file to the group that the user belongs to. The action module returns an error when the following occurs: + You do not have permission to perform the specified modification. + The specified user or group name does not exist at runtime. + The file does not exist at runtime. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The file path. | String | Yes | N/A | N/A | Not supported on Windows. | | owner | The user name. | string | Yes | N/A | N/A | Not supported on Windows. | | group | The name of the user group. | String | No | The name of the group that the user belongs to. | N/A | Not supported on Windows. | **Input example: set file owner property without specifying the name of the user group** ``` - name: SettingFileOwnerPropertyNoGroup action: SetFileOwner inputs: - path: /home/UserName/SampleText.txt owner: LinuxUser ``` **Input example: set file owner property by specifying the owner and the user group** ``` - name: SettingFileOwnerProperty action: SetFileOwner inputs: - path: /home/UserName/SampleText.txt owner: LinuxUser group: LinuxUserGroup ``` **Output** None. ### SetFolderOwner (Linux, Windows, macOS) The **SetFolderOwner** action module recursively modifies the `owner` and`group` owner properties of an existing folder. By default, the module can modify ownership for all of the contents in a folder. You can set the `recursive` option to `false` to override this behavior. This module is not supported on Windows platforms. This module accepts user and group names as inputs. If the group name is not provided, the module assigns the group owner of the file to the group that the user belongs to. The action module returns an error when the following occurs: + You do not have permission to perform the specified modification. + The specified user or group name does not exist at runtime. + The folder does not exist at runtime. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The folder path. | String | Yes | N/A | N/A | Not supported on Windows. | | owner | The user name. | string | Yes | N/A | N/A | Not supported on Windows. | | group | The name of the user group. | String | No | The name of the group that the user belongs to. | N/A | Not supported on Windows. | | recursive | Overrides the default behavior of modifying ownership for all of the contents of a folder when set to false. | Boolean | No | true | N/A | Not supported on Windows. | **Input example: set folder owner property without specifying the name of the user group** ``` - name: SettingFolderPropertyWithOutGroup action: SetFolderOwner inputs: - path: /SampleFolder/ owner: LinuxUser ``` **Input example: set folder owner property without overriding the ownership of all of the contents in a folder ** ``` - name: SettingFolderPropertyWithOutRecursively action: SetFolderOwner inputs: - path: /SampleFolder/ owner: LinuxUser recursive: false ``` **Input example: set file ownership property by specifying the name of the user group** ``` - name: SettingFolderPropertyWithGroup action: SetFolderOwner inputs: - path: /SampleFolder/ owner: LinuxUser group: LinuxUserGroup ``` **Output** None. ### SetFilePermissions (Linux, Windows, macOS) The **SetFilePermissions** action module modifies the `permissions` of an existing file. This module is not supported on Windows platforms. The input for `permissions` must be a string value. This action module can create a file the with permissions defined by the default umask value of the operating system. You must set the `umask` value if you want to override the default value. The action module returns an error when the following occurs: + You do not have permission to perform the specified modification. + The file does not exist at runtime. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The file path. | String | Yes | N/A | N/A | Not supported on Windows. | | permissions | The file permissions. | String | Yes | N/A | N/A | Not supported on Windows. | **Input example: modify file permissions** ``` - name: ModifyingFilePermissions action: SetFilePermissions inputs: - path: /home/UserName/SampleFile.txt permissions: 766 ``` **Output** None. ### SetFolderPermissions (Linux, Windows, macOS) The **SetFolderPermissions** action module recursively modifies the `permissions` of an existing folder and all of its subfiles and subfolders. By default, this module can modify permissions for all of the contents of the specified folder. You can set the `recursive` option to `false` to override this behavior. This module is not supported on Windows platforms. The input for `permissions` must be a string value. This action module can modify permissions according to the default umask value of the operating system. You must set the `umask` value if you want to override the default value. The action module returns an error when the following occurs: + You do not have permission to perform the specified modification. + The folder does not exist at runtime. + The action module encounters an error while performing the operation. **Input** | Key name | Description | Type | Required | Default value | Acceptable values | Supported on all platforms | | --- | --- | --- | --- | --- | --- | --- | | path | The folder path. | String | Yes | N/A | N/A | Not supported on Windows. | | permissions | The folder permissions. | String | Yes | N/A | N/A | Not supported on Windows. | | recursive | Overrides the default behavior of modifying permissions for all of the contents of a folder when set to false. | Boolean | No | true | N/A | Not supported on Windows. | **Input example: set folder permissions** ``` - name: SettingFolderPermissions action: SetFolderPermissions inputs: - path: SampleFolder/ permissions: 0777 ``` **Input example: set folder permissions without modifying permissions for all of the contents of a folder** ``` - name: SettingFolderPermissionsNoRecursive action: SetFolderPermissions inputs: - path: /home/UserName/SampleFolder/ permissions: 777 recursive: false ``` **Output** None. ## Software installation actions The following section describes action modules that install or uninstall software. **IAM requirements** If your installation download path is an S3 URI, then the IAM role that you associate with your instance profile must have permission to run the `S3Download` action module. To grant the required permission, attach the `S3:GetObject` IAM policy to the IAM role that is associated with your instance profile, and specify the path for your bucket. For example, `arn:aws:s3:::BucketName/*`). **Complex MSI Inputs** If your input strings contain double quote characters (`"`), you must use one of the following methods to ensure that they are interpreted correctly: + You can use single quotes (') on the outside of your string, to contain it, and double quotes (") inside of your string, as shown in the following example. ``` properties: COMPANYNAME: '"Acme ""Widgets"" and ""Gizmos."""' ``` In this case, if you need to use an apostrophe inside of your string, you must escape it. This means using another single quote (') before the apostrophe. + You can use double quotes (") on the outside of your string, to contain it. And you can escape any double quotes inside of your string, using the backslash character (`\`), as shown in the following example. ``` properties: COMPANYNAME: "\"Acme \"\"Widgets\"\" and \"\"Gizmos.\"\"\"" ``` Both of these methods pass the value `COMPANYNAME="Acme ""Widgets"" and ""Gizmos."""` to the **msiexec** command. **Topics** + [InstallMSI (Windows)](#action-modules-install-msi) + [UninstallMSI (Windows)](#action-modules-uninstall-msi) ### InstallMSI (Windows) The `InstallMSI` action module installs a Windows application using an MSI file. You can specify the MSI file using a local path, an S3 object URI, or a web URL. The reboot option configures the reboot behavior of the system. AWSTOE generates the **msiexec** command based on the input parameters for the action module. Values for the `path` (MSI file location) and `logFile` (log file location) input parameters must be enclosed in quotation marks ("). The following MSI exit codes are considered successful: + 0 (Success) + 1614 (ERROR\$1PRODUCT\$1UNINSTALLED) + 1641 (Reboot Initiated) + 3010 (Reboot Required) **Input** | Key name | Description | Type | Required | Default value | Acceptable values | | --- | --- | --- | --- | --- | --- | | path | Specify the MSI file location using one of the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) Chaining expressions are allowed. | String | Yes | N/A | N/A | | reboot | Configure the system reboot behavior that follows a successful run of the action module. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) | String | No | Allow | Allow, Force, Skip | | logOptions | Specify the options to use for MSI installation logging. Specified flags are passed to the MSI installer, along with the `/L` command line parameter to enable logging. If no flags are specified, AWSTOE uses the default value. For more information about log options for MSI, see [Command Line Options](https://learn.microsoft.com/en-us/windows/win32/msi/command-line-options) in the Microsoft *Windows Installer* product documentation. | String | No | \$1VX | i,w,e,a,r,u,c,m,o,p,v,x,\$1,\$1,\$1 | | logFile | An absolute or relative path to the log file location. If the log file path does not exist, it is created. If the log file path is not provided, AWSTOE does not store the MSI installation log. | String | No | N/A | N/A | | properties | MSI logging property key-value pairs , for example: `TARGETDIR: "C:\target\location"`   Note: Modification of the following properties is not allowed: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) | Map[String]String | No | N/A | N/A | | ignoreAuthenticodeSignatureErrors | Flag to ignore authenticode signature validation errors for the installer specified in path. The **Get-AuthenticodeSignature** command is used to validate installers. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) | Boolean | No | false | true, false | | allowUnsignedInstaller | Flag to allow running the unsigned installer specified in the path. The **Get-AuthenticodeSignature** command is used to validate installers. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) | Boolean | No | false | true, false | **Examples** The following examples show variations of the input section for your component document, depending on your installation path. **Input example: local document path installation** ``` - name: local-path-install steps: - name: LocalPathInstaller action: InstallMSI inputs: path: C:\sample.msi logFile: C:\msilogs\local-path-install.log logOptions: '*VX' reboot: Allow properties: COMPANYNAME: '"Amazon Web Services"' ignoreAuthenticodeSignatureErrors: true allowUnsignedInstaller: true ``` **Input example: Amazon S3 path installation** ``` - name: s3-path-install steps: - name: S3PathInstaller action: InstallMSI inputs: path: s3:///sample.msi logFile: s3-path-install.log reboot: Force ignoreAuthenticodeSignatureErrors: false allowUnsignedInstaller: true ``` **Input example: web path installation** ``` - name: web-path-install steps: - name: WebPathInstaller action: InstallMSI inputs: path: https:///sample.msi logFile: web-path-install.log reboot: Skip ignoreAuthenticodeSignatureErrors: true allowUnsignedInstaller: false ``` **Output** The following is an example of the output from the `InstallMSI` action module. ``` { "logFile": "web-path-install.log", "msiExitCode": 0, "stdout": "" } ``` ### UninstallMSI (Windows) The `UninstallMSI` action module allows you to remove a Windows application using an MSI file. You can specify the MSI file location using a local file path, an S3 object URI, or a web URL. The reboot option configures the reboot behavior of the system. AWSTOE generates the **msiexec** command based on the input parameters for the action module. The MSI file location (`path`) and log file location (`logFile`) are explicitly enclosed in double quotes (") while generating the **msiexec** command. The following MSI exit codes are considered successful: + 0 (Success) + 1605 (ERROR\$1UNKNOWN\$1PRODUCT) + 1614 (ERROR\$1PRODUCT\$1UNINSTALLED) + 1641 (Reboot Initiated) + 3010 (Reboot Required) **Input** | Key name | Description | Type | Required | Default value | Acceptable values | | --- | --- | --- | --- | --- | --- | | path | Specify the MSI file location using one of the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) Chaining expressions are allowed. | String | Yes | N/A | N/A | | reboot | Configures the system reboot behavior that follows a successful run of the action module. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) | String | No | Allow | Allow, Force, Skip | | logOptions | Specify the options to use for MSI installation logging. Specified flags are passed to the MSI installer, along with the `/L` command line parameter to enable logging. If no flags are specified, AWSTOE uses the default value. For more information about log options for MSI, see [Command Line Options](https://docs.microsoft.com/en-us/windows/win32/msi/command-line-options) in the Microsoft *Windows Installer* product documentation. | String | No | \$1VX | i,w,e,a,r,u,c,m,o,p,v,x,\$1,\$1,\$1 | | logFile | An absolute or relative path to the log file location. If the log file path does not exist, it is created. If the log file path is not provided, AWSTOE does not store the MSI installation log. | String | No | N/A | N/A | | properties | MSI logging property key-value pairs , for example: `TARGETDIR: "C:\target\location"`   Note: Modification of the following properties is not allowed: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) | Map[String]String | No | N/A | N/A | | ignoreAuthenticodeSignatureErrors | Flag to ignore authenticode signature validation errors for the installer specified in path. The **Get-AuthenticodeSignature** command is used to validate installers. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) | Boolean | No | false | true, false | | allowUnsignedInstaller | Flag to allow running the unsigned installer specified in the path. The **Get-AuthenticodeSignature** command is used to validate installers. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) | Boolean | No | false | true, false | **Examples** The following examples show variations of the input section for your component document, depending on your installation path. **Input example: remove local document path installation** ``` - name: local-path-uninstall steps: - name: LocalPathUninstaller action: UninstallMSI inputs: path: C:\sample.msi logFile: C:\msilogs\local-path-uninstall.log logOptions: '*VX' reboot: Allow properties: COMPANYNAME: '"Amazon Web Services"' ignoreAuthenticodeSignatureErrors: true allowUnsignedInstaller: true ``` **Input example: remove Amazon S3 path installation** ``` - name: s3-path-uninstall steps: - name: S3PathUninstaller action: UninstallMSI inputs: path: s3:///sample.msi logFile: s3-path-uninstall.log reboot: Force ignoreAuthenticodeSignatureErrors: false allowUnsignedInstaller: true ``` **Input example: remove web path installation** ``` - name: web-path-uninstall steps: - name: WebPathUninstaller action: UninstallMSI inputs: path: https:///sample.msi logFile: web-path-uninstall.log reboot: Skip ignoreAuthenticodeSignatureErrors: true allowUnsignedInstaller: false ``` **Output** The following is an example of the output from the `UninstallMSI` action module. ``` { "logFile": "web-path-uninstall.log", "msiExitCode": 0, "stdout": "" } ``` ## System action modules The following section describes action modules that perform system actions or update system settings. **Topics** + [Reboot (Linux, Windows)](#action-modules-reboot) + [SetRegistry (Windows)](#action-modules-setregistry) + [UpdateOS (Linux, Windows)](#action-modules-updateos) ### Reboot (Linux, Windows) The **Reboot** action module reboots the instance. It has a configurable option to delay the start of the reboot. By default, `delaySeconds` is set to `0`, which means that there is no delay. Step timeout is not supported for the Reboot action module, as it does not apply when the instance is rebooted. If the application is invoked by the Systems Manager Agent, it hands the exit code (`3010` for Windows, `194` for Linux) to the Systems Manager Agent. The Systems Manager Agent handles the system reboot as described in [Rebooting Managed Instance from Scripts](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html). If the application is invoked on the host as a standalone process, it saves the current execution state, configures a post-reboot auto-run trigger to rerun the application after the reboot, and then reboots the system. **Post-reboot auto-run trigger:** + **Windows**. AWSTOE creates a Windows Task Scheduler entry with a trigger that runs automatically at `SystemStartup` + **Linux**. AWSTOE adds a job in crontab that runs automatically after the system reboots. ``` @reboot /download/path/awstoe run --document s3://bucket/key/doc.yaml ``` This trigger is cleaned up when the application starts. **Retries** By default, the maximum number of retries is set to the Systems Manager `CommandRetryLimit`. If the number of reboots exceeds the retry limit, the automation fails. You can change the limit by editing the Systems Manager agent config file (`Mds.CommandRetryLimit`). See [Runtime Configuration](https://github.com/aws/amazon-ssm-agent/blob/mainline/README.md#runtime-configuration) in the Systems Manager agent open source. To use the **Reboot** action module, for steps that contain reboot `exitcode` (for example, `3010`), you must run the application binary as `sudo user`. **Input** | Key name | Description | Type | Required | Default | | --- | --- | --- | --- | --- | | delaySeconds | Delays a specific amount of time before initiating a reboot. | Integer | No | `0` | **Input example: reboot step** ``` - name: RebootStep action: Reboot onFailure: Abort maxAttempts: 2 inputs: delaySeconds: 60 ``` **Output** None. When the **Reboot** module completes, Image Builder continues to the next step in the build. ### SetRegistry (Windows) The **SetRegistry** action module accepts a list of inputs and allows you to set the value for the specified registry key. If a registry key does not exist, it is created in the defined path. This feature applies only to Windows. **Input** | Key name | Description | Type | Required | | --- | --- | --- | --- | | path | Path of registry key. | String | Yes | | name | Name of registry key. | String | Yes | | value | Value of registry key. | String/Number/Array | Yes | | type | Value type of registry key. | String | Yes | **Supported path prefixes** + `HKEY_CLASSES_ROOT / HKCR:` + `HKEY_USERS / HKU:` + `HKEY_LOCAL_MACHINE / HKLM:` + `HKEY_CURRENT_CONFIG / HKCC:` + `HKEY_CURRENT_USER / HKCU:` **Supported types** + `BINARY` + `DWORD` + `QWORD` + `SZ` + `EXPAND_SZ` + `MULTI_SZ` **Input example: set registry key values** ``` - name: SetRegistryKeyValues action: SetRegistry maxAttempts: 3 inputs: - path: HKLM:\SOFTWARE\MySoftWare name: MyName value: FirstVersionSoftware type: SZ - path: HKEY_CURRENT_USER\Software\Test name: Version value: 1.1 type: DWORD ``` **Output** None. ### UpdateOS (Linux, Windows) The **UpdateOS** action module adds support for installing Windows and Linux updates. It installs all available updates by default. Alternatively, you can configure a list of one or more specific updates for the action module to install. You can also specify updates to exclude from the installation. If both "include" and "exclude" lists are provided, the resulting list of updates can include only those listed in the "include" list that are not listed in the "exclude" list. **Note** **UpdateOS** doesn't support Amazon Linux 2023 (AL2023). We recommend that you update your base AMI to the new version that comes with every release. For other alternatives, see [Control the updates received from major and minor releases](https://docs.aws.amazon.com/linux/al2023/ug/deterministic-upgrades.html#controlling-release-updates) in the *Amazon Linux 2023 User Guide*. + **Windows**. Updates are installed from the update source configured on the target machine. + **Linux**. The application checks for the supported package manager in the Linux platform and uses either `yum` or `apt-get` package manager. If neither are supported, an error is returned. You should have `sudo` permissions to run the **UpdateOS** action module. If you do not have `sudo` permissions an `error.Input` is returned. **Input** | Key name | Description | Type | Required | | --- | --- | --- | --- | | include | For Windows, you can specify the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) For Linux, you can specify one or more packages to be included in the list of updates for installation. | String List | No | | exclude | For Windows, you can specify the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-action-modules.html) For Linux, you can specify one or more packages to be excluded from the list of updates for installation. | String List | No | **Input example: add support for installing Linux updates** ``` - name: UpdateMyLinux action: UpdateOS onFailure: Abort maxAttempts: 3 inputs: exclude: - ec2-hibinit-agent ``` **Input example: add support for installing Windows updates** ``` - name: UpdateWindowsOperatingSystem action: UpdateOS onFailure: Abort maxAttempts: 3 inputs: include: - KB1234567 - '*Security*' ``` **Output** None. # Configure input for the AWSTOE run command To streamline command line input for your AWSTOE **run** command, you can include settings for command parameters and options in a JSON format input configuration file with a `.json` file extension. AWSTOE can read your file from one of the following locations: + A local file path (*./config.json*). + An S3 bucket (*s3:////config.json*). When you enter the **run** command, you can specify the input configuration file using the **--config** parameter. For example: ``` awstoe run --config /config.json ``` **Input configuration file** The input configuration JSON file includes key-value pairs for all of the settings that you can provide directly through **run** command parameters and options. If you specify a setting in both the input configuration file and the **run** command, as a parameter or option, the following rules of precedence apply: **Rules of precedence** 1. A setting that is supplied directly to the **run** command in the AWS CLI, via a parameter or option, overrides any value that is defined in the input configuration file for the same setting. 1. A setting in the input configuration file overrides a component default value. 1. If no other settings are passed into the component document, it can apply a default value, if one exists. There are two exceptions to this rule – documents and parameters. These settings work differently in the input configuration and as command parameters. If you use the input configuration file, you must not specify these parameters directly to the **run** command. Doing so will generate an error. **Component settings** The input configuration file contains the following settings. To streamline your file, you can leave out any optional settings that aren't needed. All settings are optional unless otherwise noted. + **cwIgnoreFailures** (Boolean) – Ignore logging failures from the CloudWatch Logs. + **cwLogGroup** (String) – The `LogGroup` name for the CloudWatch Logs. + **cwLogRegion** (String) – The AWS Region that applies to the CloudWatch Logs. + **cwLogStream** (String) – The `LogStream` name for the CloudWatch Logs, that directs AWSTOE where to stream the `console.log` file. + **documentS3BucketOwner** (String) – The account ID of the bucket owner for S3 URI-based documents. + **documents** (array of objects, required) – An array of JSON objects representing the YAML component documents that the AWSTOE **run** command is running. At least one component document must be specified. Each object consists of the following fields: + **path** (String, required) – The file location of the YAML component document. This must be one of the following: + A local file path (*./component-doc-example.yaml*). + An S3 URI (`s3://bucket/key`). + An Image Builder component build version ARN (arn:aws:imagebuilder:us-west-*2:123456789012*:component/*my-example-component*/2021.12.02/1). + **parameters** (array of objects) – An array of key-value pair objects, each representing a component-specific parameter that the **run** command passes in when it runs the component document. Parameters are optional for components. The component document may or may not have parameters defined. Each object consists of the following fields: + **name** (String, required) – The name of the component parameter. + **value** (String, required) – The value to pass in to the component document for the named parameter. To learn more about component parameters, see the **Parameters** section in the [Use variables in your custom component document](toe-user-defined-variables.md) page. + **executonId** (String) – This is the unique ID that applies to the execution of the current **run** command. This ID is included in output and log file names, to uniquely identify those files, and link them to the current command execution. If this setting is left out, AWSTOE generates a GUID. + **logDirectory** (String) – The destination directory where AWSTOE stores all of the log files from this command execution. By default, this directory is located inside of the following parent directory: `TOE__`. If you do not specify the log directory, AWSTOE uses the current working directory (`.`). + **logS3BucketName** (String) – If component logs are stored in Amazon S3 (recommended), AWSTOE uploads the component application logs to the S3 bucket named in this parameter. + **logS3BucketOwner** (String) – If component logs are stored in Amazon S3 (recommended), this is the owner account ID for the bucket where AWSTOE writes the log files. + **logS3KeyPrefix** (String) – If component logs are stored in Amazon S3 (recommended), this is the S3 object key prefix for the log location in the bucket. + **parameters** (array of objects) – An array of key-value pair objects that represent parameters that apply globally to all of the components that are included in the current **run** command execution. + **name** (String, required) – The name of the global parameter. + **value** (String, required) – The value to pass in to all of the component documents for the named parameter. + **phases** (String) – A comma-separated list that specifies which phases to run from the YAML component documents. If a component document includes additional phases, those will not run. + **stateDirectory** (String) – The file path where state tracking files are stored. + **trace** (Boolean) – Enables verbose logging to the console. **Examples** The following example shows an input configuration file that runs the `build` and `test` phases for two component documents: `sampledoc.yaml`, and `conversation-intro.yaml`. Each component document has a parameter that applies only to itself, and both use one shared parameter. The `project` parameter applies to both component documents. ``` { "documents": [ { "path": "/awstoe/sampledoc.yaml>", "parameters": [ { "name": "dayofweek", "value": "Monday" } ] }, { "path": "/awstoe/conversation-intro.yaml>", "parameters": [ { "name": "greeting", "value": "Hello, HAL." } ] } ], "phases": "build,test", "parameters": [ { "name": "project", "value": "examples" } ], "cwLogGroup": "", "cwLogStream": "", "documentS3BucketOwner": "", "executionId": "", "logDirectory": "", "logS3BucketName": "", "logS3KeyPrefix": "", "logS3BucketOwner": "" } ```