volant adhoc
Run one module on every host that matches a pattern, with the options and the output of ansible.
volant adhoc is ansible: it runs one module on every host that matches a pattern.
volant adhoc <PATTERN> [-m MODULE] [-a ARGS] [-i INV] [-e VARS] [-l SUBSET] [-f N] [-u USER] [-c CONN] [-T SECS] [-b --become-user --become-method -K --become-password-file] [-k --connection-password-file] [--private-key --ssh-common-args --ssh-extra-args] [-J --vault-id --vault-password-file] [-M PATH] [--list-hosts] [--flush-cache] [--playbook-dir DIR] [-C] [-D] [-o] [-t DIR] [-B SECONDS] [-P SECONDS] [--task-timeout SECONDS] [--version] [-v]The module to run. Default: command.
The module’s arguments: key=value words, or a JSON object when the value starts with { and ends with }. For command, shell, raw and script, words that are not one of the module’s options make up the command line. The arguments are templated with each host’s variables and -e. A value that starts with {, ends with } and is not valid JSON stops the command with exit code 250; an unbalanced quote stops it with exit code 4.
Run the task in check mode. A module that cannot check reports SKIPPED.
Print the differences a task makes to files and templates before its result. With -C the file is not changed.
Print one line per host, the way ansible’s oneline callback does. ansible-core 2.19.12 deprecates this option and warns on standard error; see below.
Also write each host’s result to a file of DIR named by the host, the way ansible’s tree callback does. ansible-core 2.19.12 deprecates this option and warns on standard error; see below.
Run the module as an async job that has this many seconds to finish, and poll it. The result carries ansible_job_id, started, finished and results_file, and the async_val of the Origin: dictionary is this value. Without -B, -P is ignored.
Seconds between two looks at the job of -B. Default: 15. With 0 the job is only started, and the result has "finished": false. The poll of the Origin: dictionary is this value.
Fail a task that runs longer than this many seconds, with exit code 2 and the message Task failed: Timed out after N second(s).. 0 is no limit, and a value above 100000000 fails the task with Timeout N is invalid, it must be between 0 and 100000000.. The timeout of the Origin: dictionary is this value.
Print ansible [core 2.19.12], the configuration file, the module search path, the collection location and the executable location, then stop. The executable location follows argv[0]: a relative argv[0], or one set with exec -a, can name a different file than the one that runs. When Volant finds an interpreter with ansible-core, the module location and the Python, Jinja and PyYAML versions follow, in the reference’s lines. Without one, those lines are left out: --version installs nothing. The search paths read the environment and the defaults, not library or collections_path of ansible.cfg.
Print the hosts the pattern matches, as hosts (2): and one name line for each host, and run nothing. The exit code is 0.
Read group_vars/, host_vars/, relative paths and roles from DIR, and set playbook_dir to it, where a playbook would have supplied its own directory. Default: the working directory.
The other options mean what they mean for volant playbook, --flush-cache and -M included. -f 1 runs one host at a time, in inventory order.
A pattern that matches no host prints [WARNING]: Could not match supplied host pattern, ignoring: PATTERN and [WARNING]: No hosts matched, nothing to do on standard error and exits with 0. A -l that leaves no host prints [ERROR]: Specified inventory, host pattern and/or --limit leaves us with no hosts to target. and exits with 1, --list-hosts or not. A warning that the -l pattern could not be matched comes first only when that pattern matches nothing. An inventory with no host at all warns once and runs nothing. With no inventory, the implicit localhost is the only host that exists, and only a pattern that names it matches. A command, shell or raw run with no -a stops with [ERROR]: No argument passed to command module and exit code 5.
A usage error exits with 2. Standard error carries the usage: block of ansible, then ansible: error: and the reason. A missing pattern or a -f that is not a number is followed by the complete help of ansible; a -f below 1 is not.
Each host prints one result, the way ansible’s minimal callback prints it. A command, shell or raw result is h1 | CHANGED | rc=0 >>, then its stdout, stderr and msg joined with nothing between. Any other result is h1 | SUCCESS => followed by the result as JSON, indented four spaces, keys sorted. The statuses are SUCCESS, CHANGED, FAILED (command form), FAILED! (JSON form), SKIPPED and UNREACHABLE!. Before a failed or unreachable result, standard output carries the same [ERROR] block a playbook prints. Its Origin: is <adhoc 'MODULE' task>, followed by the task as ansible shows it, cut down to 120 characters.
The exit code is 0 when every host succeeded or was skipped, 2 when a host failed, and 4 when a host could not be reached, failed hosts or not. ANSIBLE_STDOUT_CALLBACK changes the output only when bin_ansible_callbacks is on (ANSIBLE_LOAD_CALLBACK_PLUGINS=true) and it names a callback other than default: oneline then prints as -o does, and a name Volant does not have stops the command with Could not load. -o wins over it. With ANSIBLE_CALLBACK_RESULT_FORMAT=yaml, or callback_result_format = yaml under [defaults] in ansible.cfg, a JSON-form result is printed as YAML instead, on the lines after =>, indented four spaces. A string with line breaks becomes a literal block. Any other value, the empty one included, stops the command with exit code 5.
One line per host
Section titled “One line per host”With -o a command, shell or raw result is h1 | CHANGED | rc=0 | (stdout) hi, its line breaks written \n, and (stderr) text follows when there is some. Any other result is h1 | SUCCESS => and the result as JSON on one line, keys sorted and separated by , with no space after it. A result that asks for the indented form, such as debug, or any result at -vvv, keeps its four spaces with the line breaks taken out. A host that fails prints the same two kinds of line, with FAILED, and for a command the command form comes first, then the FAILED! line. Where the failure carries an exception, a line An exception occurred during task execution. To see the full traceback, use -vvv. The error was: ... comes first; at -vvv it holds the full text. A host that cannot be reached prints h1 | UNREACHABLE!: and its message. -o prints no [ERROR] block, no warnings from a result, no diff, and it does not read callback_result_format. The exit codes are the same as without it.
With -t DIR the output is unchanged. DIR is made when the first result arrives, ~ is expanded, and a relative path starts from the working directory. Each result that is not a skip is written to DIR/HOST as JSON on one line, keys sorted, with no line break at the end, over what the host’s previous result left; an unreachable host gets a file too. A debug result, and any result at -vvv, is written indented. The file is replaced, not written through: a link planted at its place is replaced, and the mode is 0600. A host name that is not one plain file name (empty, ., .., or with a /) prints a [WARNING] and gets no file, where ansible-core writes wherever the name points, ../x and absolute paths included. A directory that cannot be made, or a file that cannot be written, prints a [WARNING] and the run goes on. A $ in DIR, or ~ followed by a user name, stops the command with exit code 4 and says it is not supported yet.
Both options print these lines on standard error before the first result, in this order: the [WARNING] that says how to turn deprecation warnings off, one [DEPRECATION WARNING] for each option, spelled and ordered as the command line gave it (-o and -t in one group of short options count as two), the warnings of the host pattern, and one [DEPRECATION WARNING] for the oneline callback and one for the tree callback. A run that ends before the callbacks load (--list-hosts, a -l that leaves no host) prints the first two groups only. deprecation_warnings = False or ANSIBLE_DEPRECATION_WARNINGS=false silences them all. At -vv, -o sets minimal aside, where the default output sets oneline aside; at -vvvv -t adds a line for the tree callback.
Actions that are not modules
Section titled “Actions that are not modules”set_fact prints its ansible_facts as any module result. meta with noop, flush_handlers, clear_facts, refresh_inventory, reset_connection or end_host prints nothing and exits with 0, and with end_play it stops with Unexpected Exception, this is probably a bug: 0 and exit code 250, as in the reference, without its traceback. These differences from ansible-core 2.19.12 remain:
metawith an unknown action, or with no-a, stops with exit code 1 as the reference does, but its[ERROR]block does not end with the blank line the reference prints, and without-ait names the argument differently.- The
[ERROR]of aninclude_roleorinclude_tasksthat cannot load its role or file words it differently. The exit codes agree: 2 for these two, 1 forimport_roleandimport_tasks. group_byreportsSUCCESSwith"changed": falsewhere the reference reportsCHANGED.
Verbose output
Section titled “Verbose output”-vv opens with the block --version prints, then Using PATH as config file (or No config file found; using defaults), and the lines Skipping callback 'default', as we already have a stdout callback. and Skipping callback 'oneline', as we already have a stdout callback. (minimal instead of oneline with -o). -vvv and above add the inventory plugin lines and the lines volant playbook prints; the reference’s own ESTABLISH LOCAL CONNECTION and EXEC lines describe its module upload, which Volant does not do, so they are not printed.
A negative -B, -P or --task-timeout, and -C together with -B, stop the command with exit code 4 and say what is not supported yet. -B, -P and --task-timeout take a whole number; anything else is a usage error.