Skip to content
Install

Vault

How Volant reads Ansible Vault data, where it gets the passwords, and why they never leave the controller process.

Volant reads and writes the vault 1.1 and 1.2 formats of ansible-core 2.19.12. The results, error messages and exit codes match ansible-core.

Source Notes
-J, --ask-vault-pass Asked on the terminal, echo off.
--vault-password-file, --vault-pass-file A file, or an executable that prints the password. Repeatable.
--vault-id LABEL@SOURCE The source is a file, an executable or prompt. Repeatable.
[defaults] vault_password_file, vault_identity_list The same, from ansible.cfg.
ANSIBLE_VAULT_PASSWORD_FILE, ANSIBLE_VAULT_IDENTITY_LIST The same, from the environment.

Every password is tried on every vaulted value, whatever its label.

  • Inline !vault values in a playbook or a vars file. They load as ciphertext and decrypt when a template reads them. A decrypted value keeps the trust ansible-core gives it.
  • Whole vaulted files: vars_files, include_vars, group_vars and host_vars files. A vaulted file that cannot be read fails with ansible-core’s message.
  • The vault and unvault filters, the vault_encrypted and vaulted_file tests, and the unvault lookup.
  • A vaulted src of copy, template and script, and a vaulted archive of unarchive. The run decrypts it into a private temporary directory before the plugin reads it. decrypt: false on copy or unarchive keeps the ciphertext.

A !vault value that no secret opens fails the task that reads it, with the three blocks ansible-core prints. debug: var=x exits 2, with the cause at the line where the value is written. is vault_encrypted answers for the variables of the current host.

A vault password lives in memory in the controller process. It is never written to a command line, to the environment of a child process, to a log, to a result or to the agent link. The connection and escalation passwords follow the same rule, and Connections says how the SSH password reaches ssh.

Filters, tests and lookups that run in Python never see the vault password. The vault ones run in the controller process for that reason. See Filters, tests and lookups that need Python.

A value that came back from a managed host is never decrypted with the run’s secrets, and never templated again. See Values from hosts are never templated.

volant vault encrypt, decrypt and view work on the same files as ansible-vault: a file encrypted by one is read by the other, with the default id and with a label.

  • encrypt replaces each file with its vault text and decrypt with its plaintext. Both leave the result at mode 0600 and print nothing; on a terminal they say Encryption successful or Decryption successful on standard error. A file without a final newline comes back without one.
  • The header is $ANSIBLE_VAULT;1.1;AES256 for the default id and $ANSIBLE_VAULT;1.2;AES256;LABEL for another. --vault-id LABEL@SOURCE sets the label. With more than one --vault-id, --encrypt-vault-id (or vault_encrypt_identity, ANSIBLE_VAULT_ENCRYPT_IDENTITY) picks the one that encrypts; without it the command exits 5.
  • --output FILE writes there and leaves the source alone, --output - writes to standard output, and no file name, or -, reads standard input.
  • view prints each file’s plaintext. On a terminal it goes through the pager: PAGER, else ANSIBLE_PAGER, else [defaults] pager, else less.
  • Without any password source the command asks for it. encrypt asks twice, as New Vault password: and Confirm New Vault password: .
  • -v prints the configuration file in use and -vv the version. The extra lines of -vvvv are not printed.

volant vault create, edit and rekey work on the same files as ansible-vault.

  • create takes one file name. It refuses with exit code 5 unless standard output is a terminal or --skip-tty-check is given, and with exit code 1 when the file exists. A missing directory is created, with a warning. The editor can leave the file empty: the result is a valid vault file holding an empty text.
  • edit decrypts each file, opens the editor and encrypts the result with the secret that opened the file and the label it had. When the text did not change, the file is not rewritten. A changed file keeps its mode.
  • The editor is EDITOR, else ANSIBLE_EDITOR, else [defaults] editor, else vi, split into words as a shell would split it, with the file name added. Its exit status is not looked at, as in ansible-vault.
  • The editor works on a copy with mode 0600 in a private directory under ANSIBLE_LOCAL_TEMP ([defaults] local_tmp, else ~/.ansible/tmp). The copy is overwritten and removed on every way out, including a failing editor and SIGTERM or SIGHUP. Ctrl-C goes to the editor.
  • rekey decrypts each file with the old secrets and writes it again with the new one, keeping its mode. The new secret comes from --new-vault-password-file, from --new-vault-id LABEL@SOURCE, or from the prompts New Vault password: and Confirm New Vault password: . It prints Rekey successful on standard error, whatever standard output is.

volant vault encrypt_string turns a value into a !vault | block for a vars file. Every line of the ciphertext is indented by ten spaces, and each block ends with a newline:

mykey: !vault |
$ANSIBLE_VAULT;1.1;AES256
66313561363937653234366564623639...
  • -n NAME names the string at the same place and --stdin-name NAME names standard input. Without a name the block starts with !vault |. --vault-id LABEL@SOURCE gives a 1.2 header with the label.
  • With no string, or with -, the text is read from standard input to its end. Empty input exits 5.
  • With more than one string, standard error carries one comment line per string, and a note when there are fewer names than strings. Standard output holds only the blocks.
  • -p asks for a variable name, then the string, which is not echoed unless --show-input is given. It cannot be combined with reading standard input.
  • On a terminal, Encryption successful goes to standard error before the blocks.
  • --output FILE writes the blocks to the file, at mode 0600.
  • The wrap_object argument of the vault filter is refused as not supported yet. Its salt argument works as in Ansible: the same salt always gives the same text.
  • At -vvvvv, vault view, decrypt and rekey do not print ansible-core’s trace of each secret they try (Trying secret FileVaultSecret(...) for vault_id=...). The secrets are tried in the same order.

The command line page has the options.