```{eval-rst}
.. image:: images/cropped-plus3it-logo-cmyk.png
:width: 140px
:alt: Powered by Plus3 IT Systems
:align: right
:target: https://www.plus3it.com
```
# Configuration
Watchmaker is configured using a [YAML][0] file. Watchmaker's default
[config.yaml][1] 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](usage). 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:
```yaml
watchmaker_version: "== 0.17.0"
```
Any [PEP440-compatible version specifier](https://www.python.org/dev/peps/pep-0440/#version-specifiers) 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.
```yaml
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](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.
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "ec2:CreateTags",
"Resource": "arn::ec2:::instance/${ec2:InstanceID}",
"Condition": {
"StringLike": {
"ec2:SourceInstanceARN": "arn::ec2:::instance/${ec2:InstanceID}"
}
}
}
]
}
```
* `Policy` Policy that allows adding or replacing tag on resource see [Microsoft Azure Tag Policy](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/tag-policies) for more info.
```{eval-rst}
.. 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:
```yaml
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](#salt-worker)
* [yum (linux-only)](#yum-worker-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.
```yaml
ou_path: "OU=Super Cool App,DC=example,DC=com"
```
* `pip_install` (_list_): The Python package(s) that formulas require.
```yaml
pip_install:
- hvac
- numpy
```
* `pip_args` (_list_): Options to pass to salt `pip.install` when installing python packages. See the [salt docs][3] for all options.
```yaml
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.
```yaml
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.
```yaml
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:
```yaml
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](installation)).
This feature simply uses the "S3 URL" of the object in the S3 bucket. Such URLs
take the form: `s3:///`. 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:
```yaml
all:
- salt:
salt_content: s3://path/to/salt-content.zip
```
And then call Watchmaker on the CLI with the `--config` argument:
```console
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][2] provides yum repo definitions and installers for a few salt
versions.
```yaml
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
# :
# The is the name of the directory in the salt file_root
# where the formula will be placed. The 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 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'
```
[0]: https://yaml.org/spec/1.2/spec.html
[1]: https://github.com/plus3it/watchmaker/blob/main/src/watchmaker/static/config.yaml
[2]: https://watchmaker.cloudarmor.io/list.html
[3]: https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.pip.html#salt.modules.pip.install