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:
- the file named by
ANSIBLE_CONFIG ./ansible.cfg~/.ansible.cfg/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.
[defaults]
Section titled “[defaults]”The inventory sources, as a comma-separated list. See Inventories.
Seconds to wait for a connection. It becomes ConnectTimeout on the ssh command line.
The user to log in as. Without it, ssh picks one.
The private key ssh authenticates with.
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.
The directory on each host that holds the agent cache.
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.
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.
The directory on each host that holds the status files of async tasks. ansible_async_dir overrides it.
Open the debugger after every failed or unreachable task.
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.
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.
Never colour the output. force_color wins over it.
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).
Print the [DEPRECATION WARNING] notices and the line that tells how to stop them. Set to False to print neither.
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].
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].
The number of -vs up to which a line goes to log_path even when the run does not show it.
Warn when the inventory holds no host, so that only the implicit localhost is left. all does not match that host.
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.
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.
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.
Run notified handlers even on hosts that failed.
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.
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.
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.
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.
Print the statistics that set_stats collected after the recap.
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.
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.
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.
Spaces per level of the json callback’s document. Zero or less writes it on one line.
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.
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.
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.
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.
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.
The vault id volant vault encrypt uses when --encrypt-vault-id is not given. See Vault.
The editor volant vault create and edit run. The last variable set wins, then the file, then vi. See Vault.
Where volant vault create and edit keep the private copy the editor works on.
The program volant vault view pipes through on a terminal. The last variable set wins, then the file.
Where roles are looked for, after <playbook_dir>/roles and before <playbook_dir> itself. See Roles.
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.
implicit, explicit or smart. See The fact cache.
memory keeps facts for the run, jsonfile keeps them between runs, and any other name is a Python plugin. See The fact cache.
The directory of the jsonfile cache.
Seconds a cached entry stays fresh. 0 never expires.
Put in front of each cache file name.
[inventory]
Section titled “[inventory]”The inventory plugins to try, in order. See the plugin chain.
File extensions skipped when a directory is read. A value replaces the default list. [defaults] inventory_ignore_extensions is read too.
Regular expressions for file names skipped when a directory is read. [defaults] inventory_ignore_patterns is read too.
Fail the run when no source could be read.
Fail the run at the first source no plugin could read.
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.
[inventory_plugin_script]
Section titled “[inventory_plugin_script]”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.
[privilege_escalation]
Section titled “[privilege_escalation]”Escalate by default. Playbook keywords and host variables take priority, see Privilege escalation.
The user to escalate to.
The escalation method: sudo or su. Other methods stop the run before it starts.
The program to run instead of sudo or su.
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.
[ssh_connection]
Section titled “[ssh_connection]”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.
[tags]
Section titled “[tags]”Tags selected by default. --tags adds to this list rather than replacing it.
Tags skipped by default. --skip-tags adds to this list.
[volant]
Section titled “[volant]”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.
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.
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.
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.
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.
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.
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].
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.
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.