Skip to content
Install

Configuration

The ansible.cfg settings and environment variables Volant reads, section by section, with their defaults.

Volant reads the same ansible.cfg as ansible-playbook, and stops at the first file it finds:

  1. the file named by ANSIBLE_CONFIG
  2. ./ansible.cfg
  3. ~/.ansible.cfg
  4. /etc/ansible/ansible.cfg

Volant skips ./ansible.cfg when the working directory is writable by other users (mode bit o+w), as ansible-playbook does. Another local user could have put the file there. The sticky bit and the owner of the directory change nothing. Volant prints [WARNING]: Ansible is being run in a world writable directory (...), ignoring it as an ansible.cfg source. on standard error and continues with the next file. A file named by ANSIBLE_CONFIG is read whatever the mode of the working directory.

For each setting, the environment variable beats the file, and the command-line option beats both. Keys Volant does not use are ignored, as Ansible ignores the ones it does not use.

A file that exists but cannot be read is skipped, and the run continues with the defaults. Volant prints a warning first, which Ansible does not: a file you wrote that the process cannot open deserves a line, and a warning does not change the exit code.

The inventory sources, as a comma-separated list. See Inventories.

Option
-i
Environment
ANSIBLE_INVENTORY

Seconds to wait for a connection. It becomes ConnectTimeout on the ssh command line.

Default
10
Option
-T
Environment
ANSIBLE_TIMEOUT

The user to log in as. Without it, ssh picks one.

Option
-u
Environment
ANSIBLE_REMOTE_USER

The private key ssh authenticates with.

Option
--private-key
Environment
ANSIBLE_PRIVATE_KEY_FILE

With it on, an unknown host key makes the host unreachable. With it off, Volant adds StrictHostKeyChecking=no and UserKnownHostsFile=/dev/null, so an unknown key is accepted and not recorded.

Default
true
Environment
ANSIBLE_HOST_KEY_CHECKING

The directory on each host that holds the agent cache.

Default
~/.ansible/tmp
Environment
ANSIBLE_REMOTE_TMP

How many hosts a play works on at once. Zero or a value that is not a number is rejected before the run starts. Playbooks read the current value as ansible_forks.

Default
5
Option
-f
Environment
ANSIBLE_FORKS

The strategy of a play that names none: linear, free, host_pinned or debug, also under ansible.builtin.. Any other name prints ansible-core’s deprecation of strategy plugins outside ansible.builtin. A plugin that subclasses one of these and adds nothing runs as that strategy, and any other name is refused.

Default
linear
Environment
ANSIBLE_STRATEGY

The directory on each host that holds the status files of async tasks. ansible_async_dir overrides it.

Default
~/.ansible_async
Environment
ANSIBLE_ASYNC_DIR

Open the debugger after every failed or unreachable task.

Default
false
Environment
ANSIBLE_ENABLE_TASK_DEBUGGER

Print task path: <file>:<line> before the fatal: line of a failed task. From -vv the line already follows every task banner, so this changes nothing there. A loop item’s failed: line and an unreachable host get no path line. As in Ansible, y, yes, on, true, t and 1 turn it on in any case, and any other word, an empty variable included, leaves it off.

Default
false
Environment
ANSIBLE_SHOW_TASK_PATH_ON_FAILURE

Colour the output even when it is not a terminal, as CI logs need. It wins over nocolor, ANSIBLE_NOCOLOR and NO_COLOR; only --no-color wins over it. In a diff, only the lines Ansible’s difflib made from before and after are coloured.

Default
false
Environment
ANSIBLE_FORCE_COLOR

Never colour the output. force_color wins over it.

Default
false
Environment
ANSIBLE_NOCOLOR

Which events show a traceback, as a comma-separated list. With error or always, a failed Python action plugin that gathers errors, such as gather_facts running its fact modules, shows its traceback and those of its modules, and registers it as exception. Every other failure keeps (traceback unavailable).

Default
never
Environment
ANSIBLE_DISPLAY_TRACEBACK

Print the [DEPRECATION WARNING] notices and the line that tells how to stop them. Set to False to print neither.

Default
true
Environment
ANSIBLE_DEPRECATION_WARNINGS

A condition whose result is not a boolean fails by default. Set to True, it goes by the truth of its result and prints a [DEPRECATION WARNING].

Default
false
Environment
ANSIBLE_ALLOW_BROKEN_CONDITIONALS

A file every line the run displays is appended to, one record each as Ansible writes it: 2026-10-30 18:34:18,430 p=<pid> u=<user> n=ansible INFO| TASK [...] ***, WARNING for a [WARNING] and ERROR for an [ERROR].

Default
unset
Environment
ANSIBLE_LOG_PATH

The number of -vs up to which a line goes to log_path even when the run does not show it.

Default
0
Environment
ANSIBLE_LOG_VERBOSITY

Warn when the inventory holds no host, so that only the implicit localhost is left. all does not match that host.

Default
true
Environment
ANSIBLE_LOCALHOST_WARNING

A YAML file whose module_rejectlist names modules that cannot be used, relative to the configuration file. A task naming one stops the playbook before it runs, at the task, with couldn't resolve module/action, as for a misspelt module. Only the name as the list writes it is refused: copy in the list leaves ansible.builtin.copy usable. ansible-core 2.19.12 reads no environment variable for it.

Default
unset

Make a role of roles: or of an import_role that does not say public keep its defaults and vars to itself. Set to false, an include_role that does not say public lends them too. Left unset, only an include_role keeps them.

Default
unset
Environment
ANSIBLE_PRIVATE_ROLE_VARS

merge lays a mapping over a mapping of the same name key by key, between every two variable sources and between two inventory sources. replace keeps the value of the higher source whole. The option is deprecated in Ansible, which still honours it and prints no warning for it.

Default
replace
Environment
ANSIBLE_HASH_BEHAVIOUR

Run notified handlers even on hosts that failed.

Default
false
Option
--force-handlers
Environment
ANSIBLE_FORCE_HANDLERS

What a YAML key written twice in one mapping gets: warn keeps the last value and prints where the second key is, error refuses the file, ignore keeps the last value and says nothing.

Default
warn
Environment
ANSIBLE_DUPLICATE_YAML_DICT_KEY

The fact modules the play’s fact gathering runs, smart (setup) unless set. A literal list in the plays, their tasks or the inventory (ansible_facts_modules) is read too; a module named only by a template cannot be run.

Default
smart
Environment
ANSIBLE_FACTS_MODULES

The Python a module runs under on a host whose ansible_python_interpreter is not set; the host variable beats this setting. auto and auto_silent find the interpreter on the host, and auto_silent leaves out the warning that names the one it found. auto_legacy and auto_legacy_silent act as auto and auto_silent and add ansible-core’s deprecation. Any other value is the path of the interpreter.

Default
auto
Environment
ANSIBLE_PYTHON_INTERPRETER

Whether from_json refuses a string that holds a lone surrogate, such as \udc80. Off, the value keeps it and prints with ? in its place, with a warning.

Default
true
Environment
ANSIBLE_MODULE_STRICT_UTF8_RESPONSE

Print the statistics that set_stats collected after the recap.

Default
false
Environment
ANSIBLE_SHOW_CUSTOM_STATS

The callback that prints the run. default prints the banners, a line per result and the recap. minimal prints each result as the ad hoc command does, host | CHANGED | rc=0 >> and the output for a command, host | SUCCESS => and the result as JSON otherwise, with no banner, no recap and no line per loop item. oneline prints the same results on one line each; ansible-core 2.19.12 deprecates it and Volant prints its warning once on standard error. tree prints nothing on standard output. The ansible.builtin. names work too. yaml stops the run with exit code 1 and the error community.general prints since 12.0.0, which removed that plugin: callback_result_format = yaml replaces it. json and ansible.posix.json print nothing while the run goes, then the whole run as one JSON document: each play and task with its times, id and path, each host’s result as the task returned it with its action, the recap by host, and the set_stats data when show_custom_stats is on. Characters past ASCII are written as \uXXXX. Any other name, such as community.general.unixy, loads through the controller’s ansible-core; one it cannot find stops the run before the first play with [ERROR]: Could not load '<name>' callback plugin. and exit code 1.

Default
default
Environment
ANSIBLE_STDOUT_CALLBACK

How default and minimal write a result: json, or yaml, where the result follows => on the next lines, indented four spaces, and a text with line breaks is a literal block. Any other value stops the run before the first play with exit code 5. oneline always writes JSON.

Default
json
Environment
ANSIBLE_CALLBACK_RESULT_FORMAT

The pretty_results of default and minimal. Unset, a JSON result is indented only for a debug, an assert and from -vvv on, and a YAML result is pretty. On, every result is indented four spaces. Off, none is, a debug included. Pretty YAML writes stdout_lines and stderr_lines as <omitted> beside their text, nests by four spaces, and drops the trailing spaces and tabs of a block of text so it stays a block; YAML that is not pretty keeps every value as it is and nests by two. A word that is not a boolean reads as off.

Environment
ANSIBLE_CALLBACK_FORMAT_PRETTY

Spaces per level of the json callback’s document. Zero or less writes it on one line.

Default
4
Environment
ANSIBLE_JSON_INDENT

More callbacks to run beside the stdout one, as a comma-separated list. Volant runs junit, which writes a JUnit XML report per playbook to JUNIT_OUTPUT_DIR (~/.ansible.log by default) and reads the other JUNIT_* variables, tree, which writes each host’s last result to a file in [callback_tree] directory (ANSIBLE_CALLBACK_TREE_DIR, ~/.ansible/tree by default), and, when ansible.posix is installed on the controller, ansible.posix.timer and ansible.posix.profile_tasks with their options ([callback_profile_tasks], PROFILE_TASKS_*). Any other name loads through the controller’s ansible-core; one it cannot find prints [WARNING]: Skipping callback plugin '<name>', unable to load and the run goes on. volant.compat.record, which records ansible-playbook’s runs, is skipped without a warning.

Environment
ANSIBLE_CALLBACKS_ENABLED

More directories to look for callback plugins in, separated by :. A plugin found there, or in callback_plugins/ beside the playbook, runs through the controller’s ansible-core in a Python process of its own. A run with no such plugin starts no Python for this.

Environment
ANSIBLE_CALLBACK_PLUGINS

Whether the ad hoc command loads the callbacks above. Off, it prints through minimal, or oneline with -o, whatever stdout_callback says. See the ad hoc command.

Default
false
Environment
ANSIBLE_LOAD_CALLBACK_PLUGINS

A file holding the vault password, or an executable that prints it. The environment variable replaces the file’s value, and the command line adds to whichever won. See Vault.

Option
--vault-password-file
Environment
ANSIBLE_VAULT_PASSWORD_FILE

Comma-separated vault identities, each written label@source where the source is a file, an executable or prompt. The environment variable replaces the file’s list, and the command line adds to whichever won.

Option
--vault-id
Environment
ANSIBLE_VAULT_IDENTITY_LIST

The vault id volant vault encrypt uses when --encrypt-vault-id is not given. See Vault.

Option
--encrypt-vault-id
Environment
ANSIBLE_VAULT_ENCRYPT_IDENTITY

The editor volant vault create and edit run. The last variable set wins, then the file, then vi. See Vault.

Environment
ANSIBLE_EDITOR, EDITOR

Where volant vault create and edit keep the private copy the editor works on.

Default
~/.ansible/tmp
Environment
ANSIBLE_LOCAL_TEMP

The program volant vault view pipes through on a terminal. The last variable set wins, then the file.

Default
less
Environment
ANSIBLE_PAGER, PAGER

Where roles are looked for, after <playbook_dir>/roles and before <playbook_dir> itself. See Roles.

Default
~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles
Environment
ANSIBLE_ROLES_PATH

Also read as collections_paths, and from ANSIBLE_COLLECTIONS_PATHS, which wins over ANSIBLE_COLLECTIONS_PATH. Where a three-part role name such as acme.demo.hello is looked for. A collection’s modules are found by the controller’s ansible-core, in the paths it is configured with: see Modules from collections.

Default
~/.ansible/collections:/usr/share/ansible/collections
Environment
ANSIBLE_COLLECTIONS_PATH

implicit, explicit or smart. See The fact cache.

Default
implicit
Environment
ANSIBLE_GATHERING

memory keeps facts for the run, jsonfile keeps them between runs, and any other name is a Python plugin. See The fact cache.

Default
memory
Environment
ANSIBLE_CACHE_PLUGIN

The directory of the jsonfile cache.

Environment
ANSIBLE_CACHE_PLUGIN_CONNECTION

Seconds a cached entry stays fresh. 0 never expires.

Default
86400
Environment
ANSIBLE_CACHE_PLUGIN_TIMEOUT

Put in front of each cache file name.

Environment
ANSIBLE_CACHE_PLUGIN_PREFIX

The inventory plugins to try, in order. See the plugin chain.

Default
host_list, script, auto, yaml, ini, toml
Environment
ANSIBLE_INVENTORY_ENABLED

File extensions skipped when a directory is read. A value replaces the default list. [defaults] inventory_ignore_extensions is read too.

Default
.pyc, .pyo, .swp, .bak, ~, .rpm, .md, .txt, .rst, .orig, .cfg, .retry
Environment
ANSIBLE_INVENTORY_IGNORE

Regular expressions for file names skipped when a directory is read. [defaults] inventory_ignore_patterns is read too.

Environment
ANSIBLE_INVENTORY_IGNORE_REGEX

Fail the run when no source could be read.

Default
false
Environment
ANSIBLE_INVENTORY_UNPARSED_FAILED

Fail the run at the first source no plugin could read.

Default
false
Environment
ANSIBLE_INVENTORY_ANY_UNPARSED_IS_FAILED

Make volant inventory keep each variable where it is set, as --export does. --export turns it on for one run; nothing turns it off from the command line, as in ansible-inventory. See the inventory command.

Default
false
Environment
ANSIBLE_INVENTORY_EXPORT

Show what a successful inventory script wrote on standard error as an [ERROR]: line. With false, only the standard error of a script that fails is shown.

Default
true
Environment
ANSIBLE_INVENTORY_PLUGIN_SCRIPT_STDERR

Escalate by default. Playbook keywords and host variables take priority, see Privilege escalation.

Default
false
Option
-b
Environment
ANSIBLE_BECOME

The user to escalate to.

Default
root
Option
--become-user
Environment
ANSIBLE_BECOME_USER

The escalation method: sudo or su. Other methods stop the run before it starts.

Default
sudo
Option
--become-method
Environment
ANSIBLE_BECOME_METHOD

The program to run instead of sudo or su.

Environment
ANSIBLE_BECOME_EXE

The flags given to that program, in place of -H for sudo and of none for su. A blank value gives no flags at all.

Environment
ANSIBLE_BECOME_FLAGS

Give raw, script and the commands a module plugin such as reboot sends without input a terminal, as ssh -tt does. Set it to False when a sudoers rule has requiretty or a command prints control characters on a terminal. The host variable ansible_ssh_use_tty wins over the environment variable, and the environment variable over the file. A word other than y, yes, on, true, t and 1 reads as off.

Default
true
Environment
ANSIBLE_SSH_USETTY

Tags selected by default. --tags adds to this list rather than replacing it.

Option
--tags
Environment
ANSIBLE_RUN_TAGS

Tags skipped by default. --skip-tags adds to this list.

Option
--skip-tags
Environment
ANSIBLE_SKIP_TAGS

Ansible ignores this section, so one ansible.cfg can carry it and still drive both engines. ansible-config validate is the exception, see Cross-host batching.

Off by default. With batching = true, a host moves on to its next tasks without waiting for the other hosts, except in front of a task whose text reads another host (hostvars, ansible_play_hosts, delegate_to, a template or variable that does). A dependency the playbook does not spell, such as a service another host is still installing or a file on a host named literally, is not waited for. Turn it on only for plays whose hosts do not depend on each other that way. See Cross-host batching.

Default
false
Environment
VOLANT_BATCHING

Let the agent answer a task with its native version of the module, when the task’s arguments stay within what that version implements. With false, every task goes to ansible-core’s Python module, and setup too, which is how to compare the two paths on a real run. The value is read as ansible-core reads a boolean, and a word it does not know stops the run with exit code 5. See Native modules.

Default
true
Environment
VOLANT_NATIVE_MODULES

Where the controller’s Python comes from. auto uses VOLANT_PYTHON, then the managed runtime when installed, then the active virtual environment and python3, and installs the managed runtime when none of them works. managed uses VOLANT_PYTHON or the managed runtime only, and installs it when it is missing. system never uses or installs the managed runtime. Any other word stops the run with exit code 5. See The managed runtime.

Default
auto
Environment
VOLANT_RUNTIME

Share one OpenSSH connection between all the ssh runs of an inventory host. With false, each link and probe opens its own connection. See One connection per host.

Default
true
Environment
VOLANT_SSH_CONTROL_MASTER

How many clean replays in a row volant shadow status wants of a playbook before it calls it ready. A whole number of at least 1; anything else stops the run with exit code 5. See Switch without risk.

Default
5

The share of a playbook’s tasks those replays must have compared, from 0 to 1, before volant shadow status calls it ready. Anything else stops the run with exit code 5.

Default
0.9

Refuse a run that differs from volant.lock with exit code 4, as --locked does. Off, a difference is a warning and the run goes on. Ansible ignores the setting with the rest of [volant].

Default
false

Sets what template, copy, script, unarchive and assemble do with a controller src that a managed host named, and where a fetch may write a dest that a host named: allow, contained or refuse. The default is allow, which behaves as ansible-core does, and any other word stops the run with exit code 5. See A source file a managed host named for what each word does.

Default
allow
Environment
VOLANT_HOST_NAMED_PATHS

A colon-separated list of absolute controller directories under which fetch may write a dest that a managed host named. An entry that is relative, uses ~ or .., or is / stops the run with exit code 5. See A dest a managed host named for the rules.

Default
unset
Environment
VOLANT_HOST_NAMED_DEST_DIRS