Configuration

Watchmaker is configured using a YAML file. Watchmaker’s default config.yaml file should work out-of-the-box for most systems and environments. You can also use it as an example to create your own configuration file. The default config file will install Salt and use the bundled Salt formulas to harden the system according to the DISA STIG.

The configuration is a dictionary. The parent nodes (keys) are: all, linux, or windows. The parent nodes contain a list of workers to execute, and each worker contains parameters specific to that worker. The all node is applied to every system, and linux and windows are applied only to their respective systems.

You can create a file using the above format with your own set of standard values and use that file for Watchmaker. Pass the CLI parameter --config to point to that file.

Configuration Precedence

In addition to passing values in the configuration file, watchmaker supports passing arguments on the cli. The order of precedence for arguments is, from least to most:

• configuration file

• cli argument

In other words, providing a value as a cli argument will override the same value provided in the configuration file.

config.yaml Parent Nodes

watchmaker_version

If used, this optional node constrains the version of Watchmaker that can be used with the configuration. The watchmaker_version node is recommended for all configurations used with versions of Watchmaker 0.17+.

This is an example of using the watchmaker_version node:

watchmaker_version: "== 0.17.0"

Any PEP440-compatible version specifier can be used in the watchmaker_version node. Each version clause should include a comparison operator, such as ~=, ==, !=, <=, >=, <, >, or ===. Multiple clauses can be included, separated by commas. Below are examples of version specifiers.

watchmaker_version: "~= 0.17.0"
watchmaker_version: "> 0.16.5"
watchmaker_version: ">= 0.17.0, <= 0.18.9, != 0.17.2"

Attempting to use a configuration with an incompatible version of Watchmaker will result in an error.

all

Section for Worker configurations that affect the deployment of all platforms. The all section will override parameters that are set in the OS-specific sections of config.yaml.

linux

Section for Worker configurations that should only be applied to Linux-based systems.

windows

Section for Worker configurations that should only be applied to Windows-based systems.

status

Watchmaker supports posting the watchmaker status to status providers. Watchmaker status values are one of: ‘Running’, ‘Failed’, or ‘Completed’. Each status provider defines what it means to “post the status”. Currently, the supported provider types include: ‘aws’ and ‘azure’. These status providers both post the status as a tag to the instance/VM.

Providers have the ability to detect whether the system is compatible with the provider type. In order to post status, the system running watchmaker must be compatible with the status provider type. For example, the ‘azure’ provider will be skipped when watchmaker is running on an AWS EC2 instance, and vice versa.

See the installation page for prerequisites for using this feature.

• IAM Role and Policy An AWS Role and Policy that allows the instance to create tags must be attached to the instance. The minimal policy below has been tested in commercial and govcloud.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "ec2:CreateTags",
            "Resource": "arn:<PARTITION>:ec2:<REGION>:<ACCOUNT_ID>:instance/${ec2:InstanceID}",
            "Condition": {
                "StringLike": {
                    "ec2:SourceInstanceARN": "arn:<PARTITION>:ec2:<REGION>:<ACCOUNT_ID>:instance/${ec2:InstanceID}"
                }
            }
        }
    ]
}

• Policy Policy that allows adding or replacing tag on resource see Microsoft Azure Tag Policy for more info.

Note

Note: Support for the ‘azure’ status provider is provisional. If you use it and encounter problems, please open an issue on the GitHub repository!

Parameters supported by status

• providers ((list of maps)): List of providers

  • key (string): Status key to use e.g. WatchmakerStatus

  • required (boolean): Required status, when True and provider_type is detected, watchmaker raises an error if unable to update status

  • provider_type (string): Environment provider type e.g. aws or azure

  Example:

  status:
    providers:
      - key: 'WatchmakerStatus'
        required: False
        provider_type: 'aws'
      - key: 'WatchmakerStatus'
        required: False
        provider_type: 'azure'
  

Config.yaml Worker Nodes

Watchmaker includes the workers listed below. See the corresponding sections for details on their configuration parameters.

• salt

• yum (linux-only)

salt worker

Parameters supported by the Salt Worker:

• admin_groups (list): The group(s) that you would like the admin accounts placed within.

• admin_users (list): The user(s) that would be created as admins.

• computer_name (string): The computer or hostname that should be applied.

• computer_name_pattern (string): The pattern the computer_name value must match to be considered a valid name. Pattern is used to validate computer name and fail fast on invalid names. In addition, this value will be set as the salt grain name-computer:pattern, to be used by the name-computer formula.

• environment (string): Set for the environment in which the system is being built.

• valid_environments (list): The list of environments considered valid for the environment parameter.

• ou_path (string): Specifies the full DN of the OU where the computer account will be created when joining a domain.

  ou_path: "OU=Super Cool App,DC=example,DC=com"
  

• pip_install (list): The Python package(s) that formulas require.

  pip_install:
      - hvac
      - numpy
  

• pip_args (list): Options to pass to salt pip.install when installing python packages. See the salt docs for all options.

  linux:
    - salt:
        pip_args:
          - pre_releases=True
  

• pip_index (string): Base URL of Python Package Index.

• salt_states (string, comma-separated): User-defined salt states to apply.

  salt_states: highstate,foo,bar
  

• exclude_states (string, comma-separated): States to exclude from execution of salt states.

• user_formulas (dict): Map of formula names and URLs to zip archives of salt formulas. These formulas will be downloaded, extracted, and added to the salt file roots. The zip archive must contain a top-level directory that, itself, contains the actual salt formula. To “overwrite” bundled submodule formulas, make sure the formula name matches the submodule name.

  user_formulas:
    foo-formula: https://path/to/foo.zip
  

• salt_debug_log (string): Path to the debug logfile that salt will write to.

• salt_content (string): URL to the Salt content file that contains further configuration specific to the salt install.

• salt_content_path (string): The path within the Salt content file specified using salt_content where salt files are located. Can be used to provide the path within the archive file where the Salt configuration files are located.

• install_method (string): (Linux-only) The method used to install Salt. Currently supports: yum, git

• bootstrap_source (string): (Linux-only) URL to the salt bootstrap script. This is required if install_method is set to git.

• git_repo (string): (Linux-only) URL to the salt git repo. This is required if install_method is set to git.

• salt_version (string): (Linux-only) A git reference present in git_repo, such as a commit or a tag. If not specifid, the HEAD of the default branch will be used.

• installer_url (string): (Windows-only) URL to the Salt Minion installer for Windows.

yum worker (linux-only)

Parameters supported by the Yum Worker:

• repo_map (list of maps): There be dragons here! Please be careful making changes to the default config. Thoroughly test your configuration. The default config specifies yum repos that contain the salt-minion. If the default repos are not included, and the salt-minion is not available, the Salt Worker will fail. You can add repos here that you would like enabled, but be wary of removing the default repos. Each map must contain the following keys:

  • dist (list): Distributions that would install this repo. Some repos are supported by multiple distros. (Currently supported distros are redhat, centos, and amazon.)

  • el_version (_string_): The Enterprise Linux version for this repo, as in el6 or el7. Expected values are '6' or '7'.

  • url (string): URL location of the repo file to be added to the system. This file will be copied to /etc/yum.repos.d/

    Example:

    repo_map:
      - dist:
          - redhat
          - centos
        el_version: 6
        url: http://someplace.com/my.repo
    

Downloading config files from Amazon S3

Watchmaker has support for downloading files from Amazon S3. This is useful for implementations where parts of the Watchmaker config are hosted privately. In order to use this feature, be sure the necessary prerequisites are installed (see the installation page).

This feature simply uses the “S3 URL” of the object in the S3 bucket. Such URLs take the form: s3://<bucket>/<key>. For example, if you wanted to host a custom config and custom salt content, you could include the salt-content S3 URL in your Watchmaker config:

all:
  - salt:
      salt_content: s3://path/to/salt-content.zip

And then call Watchmaker on the CLI with the --config argument:

watchmaker --config s3://path/to/config.yaml

Example config.yaml

This example can be used to construct your own config.yaml file. The Cloudarmor repo provides yum repo definitions and installers for a few salt versions.

watchmaker_version: ">= 0.24.0.dev"
all:
  - salt:
      admin_groups: null
      admin_users: null
      computer_name: null
      environment: null
      ou_path: null
      salt_content: null
      salt_states: Highstate
      user_formulas:
        # To add extra formulas, specify them as a map of
        #    <formula_name>: <archive_url>
        # The <formula_name> is the name of the directory in the salt file_root
        # where the formula will be placed. The <archive_url> must be a zip
        # file, and the zip must contain a top-level directory that, itself,
        # contains the actual salt formula. To "overwrite" submodule formulas,
        # make sure <formula_name> matches submodule names. E.g.:
        #ash-linux-formula: https://s3.amazonaws.com/salt-formulas/ash-linux-formula-master.zip
        #scap-formula: https://s3.amazonaws.com/salt-formulas/scap-formula-master.zip

linux:
  - yum:
      repo_map:
        #SaltEL6:
        - dist:
            - redhat
            - centos
          el_version: 6
          url: https://watchmaker.cloudarmor.io/yum.defs/saltstack/salt/2019.2.8/salt-reposync-el6.repo
        - dist: amazon
          el_version: 6
          url: https://watchmaker.cloudarmor.io/yum.defs/saltstack/salt/2019.2.8/salt-reposync-amzn.repo
        #SaltEL7:
        - dist:
            - redhat
            - centos
          el_version: 7
          url: https://watchmaker.cloudarmor.io/yum.defs/saltstack/salt/3004.2/salt-reposync-el7-python3.repo
  - salt:
      salt_debug_log: null
      install_method: yum
      bootstrap_source: null
      git_repo: null
      salt_version: null

windows:
  - salt:
      salt_debug_log: null
      installer_url: https://watchmaker.cloudarmor.io/repo/saltstack/salt/windows/Salt-Minion-3004.2-1-Py3-AMD64-Setup.exe

status:
  providers:
    - key: 'WatchmakerStatus'
      required: False
      provider_type: 'aws'
    - key: 'WatchmakerStatus'
      required: False
      provider_type: 'azure'