Inventory file reference
This page lists every field of an inventory file, the rules for node and
group names, and how a command chooses its inventory. A node is a Linux
server that MMX manages. An inventory is a file in inventories/, such
as inventories/example.yml, that lists the nodes, how MMX logs in to each
node, and the groups of nodes. A group is
a name for several nodes, such as web_servers, that a playbook can select
instead of each node. The controller machine is the computer where you
run mmx. To write an inventory step by step, see
Describe your servers. To prepare a
server for MMX's first login, see
Connect to your servers.
The inventory file
An inventory that uses every field:
# inventories/example.yml
vault_file: secrets/example.age # the vault for this inventory
vars: # inventory variables: every node in this inventory
log_level: info
nodes:
web01: # a node name you choose
address: 203.0.113.11
ssh_user: root
web02:
address: 203.0.113.12
ssh_user: deploy
ssh_port: 2222
ssh_identity_file: ~/.ssh/web02_ed25519
ssh_known_hosts: ssh/known_hosts
ssh_config: ssh/config
ssh_password: "{{ .secrets.deploy_ssh_password }}"
sudo_password: "{{ .secrets.deploy_sudo_password }}"
connection: https_with_ssh_fallback
https_address: https://203.0.113.5:17443
mmx_runner_download_url: http://203.0.113.40:18473/mmx
vars: # node variables: this node only
worker_count: 8
groups:
web_servers: # a group name you choose
nodes: [web01, web02]
vars: # group variables: every node in the group
worker_count: 4
Top-level fields:
| Field | Type | Required | What the field holds |
|---|---|---|---|
nodes |
mapping of node name to node fields | Yes, at least one node | The nodes and how MMX reaches each node |
groups |
mapping of group name to nodes and vars |
No | Named sets of nodes |
vars |
mapping | No | Variables for every node in the inventory |
vault_file |
path | No | The vault for the commands that use this inventory |
Fields of each node, under nodes:
| Field | Type | Default |
|---|---|---|
address |
IP address, host name, or Host name from your SSH configuration |
Required |
ssh_user |
account name | OpenSSH chooses |
ssh_port |
integer from 1 to 65535 | OpenSSH chooses, usually 22 |
ssh_identity_file |
path on the controller machine | Your SSH agent and your usual keys |
ssh_known_hosts |
path on the controller machine | ~/.ssh/known_hosts |
ssh_config |
path on the controller machine | ~/.ssh/config |
ssh_password |
one secret reference | MMX asks at a terminal when the server needs a password |
sudo_password |
one secret reference | MMX asks at a terminal when sudo needs a password |
connection |
https_with_ssh_fallback or ssh_only |
https_with_ssh_fallback |
https_address |
https:// and a host name, with an optional port |
https://<the node's host name>:7443 |
mmx_runner_download_url |
HTTP or HTTPS URL | MMX sends mmx-runner over SSH |
vars |
mapping | No node variables |
The file's name is the inventory's name. inventories/staging.yml is
the inventory staging. A name starts with a letter or underscore and
contains only letters, digits, underscores, or hyphens. Another .yml file
in inventories/, such as my.prod.yml, stops mmx validate with
invalid inventories name "my.prod".
One inventory for each environment. A command uses exactly one inventory, and MMX never merges two inventory files. Node and group names may repeat between inventories, so one playbook works with each inventory.
The YAML rules of the settings file apply. An unknown field, such as
ssh_host, fails with
inventories/example.yml: line 4 column 5 (nodes.web01.ssh_host): unknown field.
The settings file lists the other
rules, such as true and false for booleans.
Checks without a server. mmx nodes lists the nodes and groups of an
inventory, and mmx validate checks every inventory of the project. mmx nodes and
mmx validate read only your files:
$ mmx nodes
Inventory: example (inventories/example.yml, 2 nodes)
Nodes
web01 203.0.113.11 root web_servers
web02 203.0.113.12 deploy web_servers
Groups
web_servers web01, web02
mmx validate does not check that a file named in ssh_identity_file,
ssh_known_hosts, or ssh_config exists. A missing file shows at the
first connection to the node.
nodes
nodes lists the servers of the inventory. Each key is a node name that
you choose, and the fields below the key say how MMX reaches the node.
nodes:
web01: # the node name
address: 203.0.113.11
ssh_user: root
- A node name starts with a letter or underscore and contains only
letters, digits, underscores, or hyphens. Playbooks,
--limit, and the output use the node name. The node name need not match the server's host name. A name such asweb.01fails withinvalid node name "web.01". allis not a node name, because a selection ofallmeans every node of the inventory. A node namedallfails withnode name "all" is reserved: selecting all selects every node of the inventory; give the node another name.- At least one node. An inventory without nodes fails with
inventory requires at least one node. - Two node names for one machine: each node name must reach a different machine. The When something fails page lists the error for two names that reach one machine.
address
address is where MMX connects to the node: an IP address, a host name, or
a Host name from your SSH configuration.
address: 203.0.113.11
- Required. An empty address, an address that starts with
-, or an address with a space, a tab, or a line break fails withnode address must not be empty, start with '-', or contain spaces, tabs, line breaks, or a NUL byte. - A
Hostname from~/.ssh/configmakes MMX use that entry's settings, assshdoes. HTTPS then goes to the entry'sHostName. A Host name from your SSH configuration shows an example.
ssh_user
ssh_user is the account that MMX logs in as over SSH.
ssh_user: deploy
- The account must be
root, or an account that can run any command withsudo, because MMX installs software and changes system files. Otherwise the first connection fails withaccount deploy does not have unrestricted root sudo access. - Allowed names start with a letter or underscore and contain only
letters, digits, underscores, or hyphens. Otherwise the inventory fails
with
ssh_user must start with a letter or underscore and contain only letters, digits, underscores, or hyphens. - Default: OpenSSH chooses the account, as plain
sshdoes: from aUserline in your SSH configuration, or else your own user name on the controller machine.mmx nodesthen shows-in the account column. ssh_userdoes not choose the account that node tasks run as. MMX's program on the node runs as root.
ssh_port
ssh_port is the node's SSH port, as ssh -p gives it.
ssh_port: 2222
- Type: an integer from 1 to 65535. A number outside the range fails
with
ssh_port must be a port number from 1 to 65535, and a quoted number, such as"2222", fails withexpected int, got !!str. - Default: OpenSSH chooses the port: a
Portline in your SSH configuration, or else 22. - After you change
ssh_porton a node that MMX already manages, read Other SSH settings for what the next run does and which key MMX logs in with. - To change the port that sshd listens on, follow Change SSH or network settings safely, so that MMX does not lock itself out.
ssh_identity_file
ssh_identity_file is the SSH private key that MMX logs in to the node
with, as ssh -i FILE -o IdentitiesOnly=yes uses the key.
ssh_identity_file: ~/.ssh/web02_ed25519
- Type: a path on the controller machine. See Paths on the controller machine.
- Default: MMX offers the keys that plain
sshoffers: the keys of your SSH agent and your usual key files. - With the field set, MMX offers only the key in
ssh_identity_file. So the field helps when the server answersToo many authentication failures, because your SSH agent offered other keys first. - A key with a passphrase: MMX asks for the passphrase at a terminal, only for a key file that MMX found for this node.
ssh_known_hosts
ssh_known_hosts is the file of trusted SSH host keys that MMX checks the
node's host key against, as ssh -o UserKnownHostsFile=FILE does.
ssh_known_hosts: ssh/known_hosts
- Type: a path on the controller machine. See Paths on the controller machine.
- Default:
~/.ssh/known_hosts, as for plainssh. - A file in the project, such as
ssh/known_hosts, can go into Git, so every member of the team trusts the same host keys. - MMX connects only to a server whose host key the file already trusts, and never accepts a new host key.
ssh_config
ssh_config is the SSH configuration file that MMX reads for the node
instead of ~/.ssh/config and the system's /etc/ssh/ssh_config, as
ssh -F FILE does.
ssh_config: ssh/config
- Type: a path on the controller machine. See Paths on the controller machine.
- Default:
~/.ssh/configand the system's/etc/ssh/ssh_config, as for plainssh. With the field set, a system-wide setting no longer applies to the node. - Use: settings that the inventory has no field for, such as a jump host: A server behind a jump host.
- A file that OpenSSH cannot read fails the connection to the node, and the error gives OpenSSH's own message.
Paths on the controller machine
ssh_identity_file, ssh_known_hosts, and ssh_config name files on the
controller machine:
| Written as | Starts at | Example |
|---|---|---|
~/ and a path |
Your home directory, as for OpenSSH | ~/.ssh/web02_ed25519 is /home/you/.ssh/web02_ed25519 |
| An absolute path | The root directory | /home/you/.ssh/web02_ed25519 |
| Another relative path | The project directory, where mmx_project_settings.yml is |
ssh/known_hosts is <project>/ssh/known_hosts |
Only ~/ is expanded. ~bob/.ssh/key is a relative path in the project
directory, not a path in Bob's home directory.
ssh_password
ssh_password gives MMX the node's SSH password from a secret, for a run
without a terminal, such as a CI job.
ssh_password: "{{ .secrets.deploy_ssh_password }}"
- Type: exactly one secret reference, in quotes, with no text before or
after the reference. A plain password fails with
must be a whole-value secret reference such as "{{ .secrets.ssh_password }}". - Default: MMX asks for the password at a terminal when the server
needs one. Without a terminal, the command fails with
SSH password for deploy@203.0.113.12:22 is required; configure an environment variable for the credential or use an SSH key or ssh-agent (prompts are disabled). - The secret comes from
secrets_from_envor from the vault, as any secret does: secrets reference. - MMX keeps the password in memory only, and reads the password only when a connection over SSH needs the password. Passwords for automation shows the whole setup.
sudo_password
sudo_password gives MMX the sudo password of ssh_user from a secret,
for a run without a terminal.
sudo_password: "{{ .secrets.deploy_sudo_password }}"
- Type and default: as for
ssh_password. - When MMX needs the password: at the first contact, and at each
connection over SSH when the account's
sudoasks for a password. A run over HTTPS needs nosudopassword.root, or an account whosesudoasks for no password, needs nosudo_password.
connection
connection chooses how MMX connects to the node after the first contact.
connection: ssh_only
| Value | What MMX does |
|---|---|
https_with_ssh_fallback (default) |
MMX connects over HTTPS to MMX's service on the node, on port 7443. When port 7443 cannot be reached, MMX does the same work over SSH and prints a notice. |
ssh_only |
MMX connects over SSH for every request, with no attempt at HTTPS and no notice. |
- Another value fails with
connection must be https_with_ssh_fallback or ssh_only. - For one command only, without a change to the shared inventory,
pass
--connection ssh_onlytommx dryrun,mmx run,mmx run-command,mmx check-one-time-playbooks, ormmx complete-one-time-playbook.mmx resumekeeps the run's choice and refuses--connection. - When to choose
ssh_only: a firewall closes port 7443, or sshd uses login rules that only OpenSSH can check. A server whose port 7443 is closed and Login rules that only OpenSSH can check explain each case.
https_address
https_address is where MMX reaches MMX's HTTPS service on the node, when
the service is reachable at another address or port than the node's own
port 7443, such as through a NAT port mapping.
https_address: https://203.0.113.5:17443
- Type:
https://, a host name or IP address, an optional port, and an optional trailing/. Anything else, such as a missinghttps://, a user name, a path, a query, or a fragment, fails withhttps_address must contain https:// and a host name, with an optional port and trailing slash, but no credentials, other path, query, or fragment. - Default:
https://<host>:7443, where<host>is the host that OpenSSH connects to foraddress. For aHostname from your SSH configuration,<host>is the entry'sHostName. - Without a port, such as
https://203.0.113.5, MMX connects to port 443, the standard HTTPS port. - HTTPS through a port mapping has the setup.
mmx_runner_download_url
mmx_runner_download_url is a web server from which the node downloads
mmx-runner, MMX's program for the node, instead of receiving the file
over SSH. The setting helps a large fleet with a web server near the nodes.
mmx_runner_download_url: http://203.0.113.40:18473/mmx
- Type: an
http://orhttps://URL, without a user name, password, query, or fragment. Otherwise the inventory fails withmmx_runner_download_url must be an HTTP or HTTPS URL without credentials, query, or fragment. - Default: none. MMX sends
mmx-runnerover the node's SSH connection. - What the node downloads: the URL, then
/mmx-runner-and the SHA-256 hash of the file, such ashttp://203.0.113.40:18473/mmx/mmx-runner-8bf9a38b.... The node downloads the file withcurl, socurlmust be installed on the node. - Plain HTTP is safe for the download, because MMX sends the expected hash over verified SSH and installs only a file with that hash.
- Runner downloads for a large fleet sets up the web server, and says what happens when a download fails.
groups
groups gives names to sets of nodes, so that a playbook, --limit, and
the output can name the set instead of each node.
groups:
web_servers: # a group name you choose
nodes: [web01, web02]
vars:
http_port: 8080
database_servers:
nodes: [db01]
A group has two fields, both optional: nodes, the list of node names,
and vars. A group without nodes is empty. Connection
settings, such as ssh_user, are written on each node, not on a group.
| Rule | What a break of the rule shows |
|---|---|
| A group name starts with a letter or underscore and contains only letters, digits, underscores, or hyphens. | inventory group "web.servers" must start with a letter or underscore and contain only letters, digits, underscores, or hyphens; the group name must differ from 'all' and every node name |
A group name differs from all and from every node name of the inventory. |
The same message as the rule above, such as for a group web01 |
nodes lists node names of the same inventory, each name once. A group cannot list another group: MMX has no groups of groups. |
group all_servers: unknown or repeated node web_servers |
| Two groups of one node must not set the same variable, even to the same value, because MMX never chooses between groups. | node web02 belongs to groups small_servers and web_servers, which set the same variable worker_count; define the variable in inventory vars, in only one group, or in each node's vars |
- A node can be in several groups, such as
web01inweb_serversand inbacked_up. - An empty group,
nodes: [], is valid. A fleet stage that selects only an empty group fails, unless the fleet stage setsskip_when_no_nodes_are_selected: true: Choose which servers a run touches. - To select two groups together, a playbook lists both groups, such as
nodes: [web_servers, database_servers].
vars
vars sets variables, which node tasks read as {{ .vars.NAME }}. An
inventory can set vars in three places:
| Where | Which nodes get the variables |
|---|---|
| At the top of the inventory file | Every node in the inventory |
| In a group | Every node in the group |
| On a node | The node only |
vars: # every node in this inventory
log_level: info
nodes:
web01:
address: 203.0.113.11
web02:
address: 203.0.113.12
vars: # web02 only
worker_count: 8
groups:
web_servers:
nodes: [web01, web02]
vars: # every node in web_servers
worker_count: 4
- Type: a mapping. A value can be text, a number, a boolean, a list, or a mapping.
- Order: the project's
varsinmmx_project_settings.ymlcome first, then the inventory'svars, then thevarsof the node's groups, then the node's ownvars. A later place replaces an earlier value of the same name, and a list or a mapping is replaced as a whole. In the example,web02getsworker_count: 8. Describe your servers, step 3, walks through the order. - A command-line variable that a playbook declares in
command_line_varsmust not be in anyvars. - The variables of another node's groups and of that node itself are
readable as
{{ .inventory.nodes.NAME.vars.VARIABLE }}. Project and inventory variables are the same for every node: read them through.vars. Values about other servers shows both.
vault_file
vault_file names the vault that the commands with this inventory use: the
encrypted file of secrets. So a staging inventory can use a vault without
production's secrets.
# inventories/staging.yml
vault_file: secrets/staging.age
- Type: a path. A relative path starts at the directory of the
inventory file, in the example
inventories/, sosecrets/staging.ageisinventories/secrets/staging.age. - Default: the project's
vault_fileinmmx_project_settings.yml, or elsesecrets_vault.agein the project directory. - Which vault file lists the order in which MMX chooses the vault, and A vault for each inventory sets up one vault for each inventory.
Choosing the inventory on the command line
A command uses the inventory that --inventory NAME names, or else the
project's default_inventory from mmx_project_settings.yml:
mmx nodes --inventory staging
mmx run set_up_web_servers --inventory staging
--inventorytakes the inventory's name, not a path. A path fails with--inventory must be a name, not a path: "inventories/example.yml".- A name without a file fails with
there is no inventory staging: inventories/staging.yml does not exist; the project's inventories are: example. mmx validatewithout a playbook name checks every inventory, each inventory on its own, with every playbook.- The
mmx secretscommands take--inventory NAMEto use the inventory'svault_file. - Commands that pick a saved run, such as
mmx resultswithout a run ID, pick the latest run of the inventory: Selecting saved runs. - A run saves the inventory with the run, so
mmx resumeuses the inventory as the run read the inventory, even after you edit the file. - Choose which servers a run touches
covers
--limitand the other ways to run on only some of the inventory's nodes.
This page is docs/reference/inventory-file.md in the MMX repository.