ansible.builtin.expect module – Executes a command and responds to prompts

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name expect even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.expect for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

  • The ansible.builtin.expect module executes a command and responds to prompts.

  • The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like $HOME and operations like "<", ">", "|", and "&" will not work.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 2.6

  • pexpect >= 3.3

Parameters

Parameter

Comments

chdir

path

Change into this directory before running the command.

command

string / required

The command module takes command to run.

creates

path

A filename, when it already exists, this step will not be run.

echo

boolean

Whether or not to echo out your response strings.

Choices:

  • false ← (default)

  • true

removes

path

A filename, when it does not exist, this step will not be run.

responses

dictionary / required

Mapping of prompt regular expressions and corresponding answer(s).

Each key in responses is a Python regex https://docs.python.org/3/library/re.html#regular-expression-syntax.

The value of each key is a string or list of strings. If the value is a string and the prompt is encountered multiple times, the answer will be repeated. Provide the value as a list to give different answers for successive matches.

timeout

any

Amount of time in seconds to wait for the expected strings. Use null to disable timeout.

Default: 30

Attributes

Attribute

Support

Description

check_mode

Support: none

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platform: posix

Target OS/families that can be operated against

Notes

Note

  • If you want to run a command through the shell (say you are using <, >, |, and so on), you must specify a shell in the command such as /bin/bash -c "/path/to/something | grep else".

  • Case insensitive searches are indicated with a prefix of (?i).

  • The pexpect library used by this module operates with a search window of 2000 bytes, and does not use a multiline regex match. To perform a start of line bound match, use a pattern like (?m^pattern).

  • The ansible.builtin.expect module is designed for simple scenarios. For more complex needs, consider the use of expect code with the ansible.builtin.shell or ansible.builtin.script modules. (An example is part of the ansible.builtin.shell module documentation).

  • If the command returns non UTF-8 data, it must be encoded to avoid issues. One option is to pipe the output through base64.

See Also

See also

ansible.builtin.script

Runs a local script on a remote node after transferring it.

ansible.builtin.shell

Execute shell commands on targets.

Examples

- name: Case insensitive password string match
  ansible.builtin.expect:
    command: passwd username
    responses:
      (?i)password: "MySekretPa$$word"
  # you don't want to show passwords in your logs
  no_log: true

- name: Match multiple regular expressions and demonstrate individual and repeated responses
  ansible.builtin.expect:
    command: /path/to/custom/command
    responses:
      Question:
        # give a unique response for each of the 3 hypothetical prompts matched
        - response1
        - response2
        - response3
      # give the same response for every matching prompt
      "^Match another prompt$": "response"

- name: Multiple questions with responses
  ansible.builtin.expect:
    command: /path/to/custom/command
    responses:
        "Please provide your name":
            - "Anna"
        "Database user":
            - "{{ db_username }}"
        "Database password":
            - "{{ db_password }}"

Authors

  • Matt Martz (@sivel)