Command line
Every command and option Volant accepts, grouped by what they change, and the ansible-playbook options it does not have yet.
volant playbook [OPTIONS] <PLAYBOOK>...volant-playbook [OPTIONS] <PLAYBOOK>...volant adhoc [OPTIONS] <PATTERN>volant config [ARGS...]volant console [pattern] [OPTIONS]volant doc [ARGS...]volant galaxy [ARGS...]volant pull -U URL [OPTIONS] [PLAYBOOK...]volant inventory (--list | --host HOST) [OPTIONS]volant runtime <install|pack|status|path|remove>volant shadow replay RECORDING [--json]volant compat install [-p PATH] [-f]volant lock [--check]volant shims <install|remove>volant vault <encrypt|decrypt|view|create|edit|rekey|encrypt_string>volant --versionEach other command has its own page: volant adhoc, volant check, volant config, volant compat, volant console, volant doc, volant galaxy, volant pull, volant inventory, volant lock, volant runtime, volant shadow, volant shims, volant vault. Ansible command names ties them together. This page covers volant playbook.
volant playbook takes the same options as ansible-playbook, for the ones that exist. volant-playbook is the same program under a name that reads like the one you know. Playbooks given together run in order, and each one prints its own recap.
On Linux and macOS the volant binary also dispatches on the name it was started as (the file name of argv[0]). Started as ansible-playbook, ansible-vault, ansible-doc, ansible-config, ansible-galaxy, ansible-console, ansible-pull or ansible-inventory, through a symlink or a hard link, it behaves as volant playbook, volant vault, volant doc, volant config, volant galaxy, volant console, volant pull or volant inventory with the same arguments, output and exit codes. Started as ansible, it behaves as volant adhoc. volant doc and config run ansible-core’s own tools from Volant’s Python runtime. volant galaxy is being made native and refuses each subcommand until it is. volant pull and volant console are Volant’s own; volant pull and volant console list how they differ. A usage error exits with 2 and names the program as started. Any other name keeps the usual volant behaviour.
Where an option has an ansible.cfg key or an environment variable, the entry names it. The option wins over both; Configuration explains the order.
Hosts and connections
Section titled “Hosts and connections”An inventory source: a file, a directory, a script or a comma list of hosts. Repeat it to merge several, see Inventories. Without one, only the implicit localhost exists.
Run only on hosts matching this pattern. A limit that matches no host warns and narrows the run to what it did match.
Start at the first task named NAME; * and ? match any text. The tasks in front of it are left out, Gathering Facts apart, and so are the plays in front of the one that holds it. Only tasks written in the play are searched, as in ansible-playbook: a task an include_tasks or include_role reads while the run goes is not found. A name nothing matches prints the plays with an empty recap, then an error, and exits 0.
Ask before each task: y runs it, n or anything else skips it, c runs it and every task after it without asking. It needs a terminal; without one the run stops with exit code 250 before it touches a host.
Remove the fact cache entries of the inventory hosts before the run.
Print the Volant version and the ansible-core release it matches, then stop.
Log in to hosts as this user. Without it, ssh picks the user, from your ~/.ssh/config or your local account.
The connection plugin for hosts that name none: ssh or local. A host’s ansible_connection and a play, block or task connection keyword both win over it. Any other name fails the task with the connection plugin '<name>' was not found.
The private key ssh authenticates with, passed as ssh -i.
Arguments added to every ssh command line. Volant splits them into words as a shell would, and an unbalanced quote stops the run before it starts. The host variable ansible_ssh_common_args replaces this value for that host.
Arguments added to the ssh command line after the common ones. The host variable ansible_ssh_extra_args replaces this value for that host.
How long to wait for a connection, passed to ssh as ConnectTimeout.
How many hosts a play works on at once. Zero or a value that is not a number is rejected before the run starts.
Directories searched for modules before the configured ones. Colon-separated and repeatable. A later -M goes in front of an earlier one.
Variables and tags
Section titled “Variables and tags”Extra variables, at the top of the precedence order: key=value pairs, inline JSON or YAML, or @file. Repeatable.
Run only tasks with these tags. Comma-separated and repeatable, and added to the configured default rather than replacing it. See Tags and listings.
Skip tasks with these tags. Comma-separated and repeatable, and added to the configured default.
Look without running
Section titled “Look without running”These options read the playbooks and stop. They never connect to a host and never stop on an unsupported module, so they work on playbooks this release cannot run yet.
List the tasks the run would execute, in Ansible’s format.
List the tags the run would select.
List the hosts each play would run on, in inventory order.
Load and compile the playbooks without running anything.
Privilege escalation
Section titled “Privilege escalation”Run tasks with privilege escalation. A become keyword in the playbook still decides for its own play, block or task. See Privilege escalation.
The user to escalate to.
The escalation method: sudo or su. Other methods stop the run before it starts.
Ask for the SSH password on the terminal, with echo turned off. ssh gets it through SSH_ASKPASS, so it needs OpenSSH 8.4 or later. The password is in no command line, no environment sent to the host and no log. After -k, an empty answer to the -K prompt reuses the SSH password, as in ansible-playbook.
Read the SSH password from the first line of this file. It conflicts with -k.
Read the escalation password from the first line of this file. It conflicts with -K.
Ask for the escalation password on the terminal, with echo turned off. The password is written once to sudo and appears in no command line, log or result.
Ask for the vault password on the terminal, with echo turned off.
A file holding the vault password, or an executable that prints it. Repeatable.
A vault identity: the source is a file, an executable or prompt. Repeatable. Every password is tried on every vaulted value, whatever its label. See Vault.
Run and output
Section titled “Run and output”Run notified handlers even on hosts that failed. A force_handlers keyword on the play takes priority. See Handlers.
Report what each task would change without changing it. A task’s own check_mode keyword wins over this option, so a task with check_mode: false still runs for real. A host with no Python cannot answer apt, user, group or file under --check or --diff: those modules need it, and the task fails. See Check mode and diff.
Print the changes modules make to files, the way ansible-playbook does. A task’s own diff keyword wins over this option, so diff: false keeps a task’s changes off the screen. A host with no Python cannot answer apt, user, group or file under --diff: those modules need it, and the task fails. See Check mode and diff.
Show module results for successful tasks too. Repeatable, like Ansible’s -vvv. A result carries its invocation key, the arguments the module received, only from -vvv on. At -vvvv the run also prints every option it was given, the plugins it loads and the ssh commands it runs.
Print without colors. The option beats force_color (ANSIBLE_FORCE_COLOR), which beats nocolor. See Configuration.
Where gathered facts come from. auto uses the agent’s native setup when every fact the plays can read is one it produces, and ansible-core’s setup module otherwise. python always runs the Python module, to compare against. native always asks the agent’s collector, and facts it does not produce are then undefined. On a host other than Debian or Ubuntu the native collector hands the task back to the Python module whatever this option says. See Facts.
Refuse the run with exit code 4, before any connection, when the installed collections, roles, runtime or Volant differ from volant.lock. Without it, each difference is a warning.
After the recap, print on standard error where the run’s time went: the controller’s phases per host, then for each module the path its tasks took (native, python or fallback), their times, and why a native module handed a task back. The first line says where facts came from and why.
Environment variables
Section titled “Environment variables”Volant reads the ANSIBLE_* variables named above, plus a few of its own.
The Python interpreter the controller uses to build module payloads. It needs ansible-core. When set, Volant uses it alone and installs nothing. Which interpreter a run uses gives the full order.
Whether Volant may use and install its own Python. See The managed runtime.
A directory that holds the agent binaries. It is checked first, before the agents built into the release controller and the directory of the volant executable. Useful with a controller built from source, or to test an agent of your own.
Turns on cross-host batching.
How a controller src that a managed host named is treated. See host_named_paths.
The controller directories a fetch may write under when a managed host named its dest. See host_named_dest_dirs.
With 0, every task runs ansible-core’s Python module instead of the agent’s native version. See Native modules.
With 0, every ssh run opens its own connection instead of sharing one per inventory host.
Write the run’s profile to this file, one JSON object per line: the native modules each agent reported, then the phases, then one line per task with its module, path, hand-back reason and times in microseconds. It is written whatever became of the run, and a file that cannot be written only prints a warning.
Not there yet
Section titled “Not there yet”Every ansible-playbook option is accepted. --scp-extra-args and --sftp-extra-args have no effect, because files move over the agent link. The parity page lists each option with its status.
volant has the subcommands playbook, adhoc, check, inventory, runtime, lock, shadow, shims, compat, vault, doc, config, galaxy, console and pull. There is no volant lint. Run ansible-lint for that. volant check says whether Volant can run a playbook. --check is a different option: it runs the playbook in check mode against hosts.