---
obj: application
website: https://www.ansible.com
repo: https://github.com/ansible/ansible
---

# Ansible
Ansible is an open-source automation tool that simplifies configuration management, application deployment, and task automation.

## Inventory
The inventory contains all the host. The simplest inventory is a single file with a list of hosts and groups. The default location for this file is `/etc/ansible/hosts`. You can specify a different inventory file at the command line using the `-i <path>` option or in configuration using `inventory`.

Example:
```toml
mail.example.com

[webservers]
foo.example.com
bar.example.com

[dbservers]
one.example.com
two.example.com
three.example.com
```

You can specify variables for the hosts:
```toml
[atlanta]
host1
host2

[atlanta:vars]
ntp_server=ntp.atlanta.example.com
proxy=proxy.atlanta.example.com
```

## Command Line Tools
### ansible
Define and run a single task ‘playbook’ against a set of hosts

#### Options
| Option                                                                                     | Description                                                                                                                                                          |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--become-method <BECOME_METHOD>`                                                          | privilege escalation method to use (default=sudo), use ansible-doc -t become -l to list valid choices.                                                               |
| `--become-password-file <BECOME_PASSWORD_FILE>, --become-pass-file <BECOME_PASSWORD_FILE>` | Become password file                                                                                                                                                 |
| `--become-user <BECOME_USER>`                                                              | run operations as this user (default=root)                                                                                                                           |
| `--list-hosts`                                                                             | outputs a list of matching hosts; does not execute anything else                                                                                                     |
| `--playbook-dir <BASEDIR>`                                                                | Since this tool does not use playbooks, use this as a substitute playbook directory. This sets the relative path for many features including roles/ group_vars/ etc. |
| `--private-key <PRIVATE_KEY_FILE>, --key-file <PRIVATE_KEY_FILE>`                          | use this file to authenticate the connection                                                                                                                         |
| `--vault-password-file, --vault-pass-file`                                                 | vault password file                                                                                                                                                  |
| `-J, --ask-vault-password, --ask-vault-pass`                                              | ask for vault password                                                                                                                                               |
| `-K, --ask-become-pass`                                                                    | ask for privilege escalation password                                                                                                                                |
| `-b, --become`                                                                             | run operations with become (does not imply password prompting)                                                                                                       |
| `-e, --extra-vars`                                                                         | set additional variables as key=value                                                                                                                                |
| `-i, --inventory`                                                                          | specify inventory host path or comma separated host list                                                                                                             |
| `-k, --ask-pass`                                                                           | ask for connection password                                                                                                                                          |
| `-l <SUBSET>, --limit <SUBSET>`                                                            | further limit selected hosts to an additional pattern                                                                                                                |
| `-m <MODULE_NAME>, --module-name <MODULE_NAME>`                                            | Name of the action to execute (default=command)                                                                                                                      |
| `-t <TREE>, --tree <TREE>`                                                                 | log output to this directory                                                                                                                                         |
| `-u <REMOTE_USER>, --user <REMOTE_USER>`                                                   | connect as this user (default=None)                                                                                                                                                                     |

### ansible-playbook
Runs Ansible playbooks, executing the defined tasks on the targeted hosts.
Usage: `ansible-playbook [option]... [playbook]`

#### Options
| Option                                                                                     | Description                                                                                            |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `--become-method <BECOME_METHOD>`                                                          | privilege escalation method to use (default=sudo), use ansible-doc -t become -l to list valid choices. |
| `--become-password-file <BECOME_PASSWORD_FILE>, --become-pass-file <BECOME_PASSWORD_FILE>` | Become password file                                                                                   |
| `--become-user <BECOME_USER>`                                                              | run operations as this user (default=root)                                                             |
| `--list-hosts`                                                                             | outputs a list of matching hosts; does not execute anything else                                       |
| `--list-tasks`                                                                             | list all tasks that would be executed                                                                  |
| `--private-key <PRIVATE_KEY_FILE>, --key-file <PRIVATE_KEY_FILE>`                          | use this file to authenticate the connection                                                           |
| `--vault-password-file, --vault-pass-file`                                                 | vault password file                                                                                    |
| ` -J, --ask-vault-password, --ask-vault-pass`                                              | ask for vault password                                                                                 |
| `-K, --ask-become-pass`                                                                    | ask for privilege escalation password                                                                  |
| `-b, --become`                                                                             | run operations with become (does not imply password prompting)                                         |
| `-e, --extra-vars`                                                                         | set additional variables as key=value                                                                  |
| `-i, --inventory`                                                                          | specify inventory host path or comma separated host list                                               |
| `-k, --ask-pass`                                                                           | ask for connection password                                                                            |
| `-l <SUBSET>, --limit <SUBSET>`                                                            | further limit selected hosts to an additional pattern                                                  |
| `-t <TREE>, --tree <TREE>`                                                                 | log output to this directory                                                                           |
| `-u <REMOTE_USER>, --user <REMOTE_USER>`                                                   | connect as this user (default=None)                                                                    |
| ` --syntax-check`                                                                          | perform a syntax check on the playbook, but do not execute it                                          |

### ansible-vault
encryption/decryption utility for Ansible data files.
Ansible vault gives you the ability to securely store sensitive information besides your playbooks and use them normally as variables if you have the encryption key.
Usage: `ansible-vault [action] [options]...`

#### create
This command creates a new ansible vault file.
Usage: `ansible-vault create [--vault-password-file, --vault-pass-file] vault.yml`

#### decrypt
decrypt the supplied file using the provided vault secret.
Usage: `ansible-vault decrypt [--vault-password-file, --vault-pass-file] --output out.yml vault.yml`

#### encrypt
encrypt the supplied file using the provided vault secret.
Usage: `ansible-vault encrypt [--vault-password-file, --vault-pass-file] --output vault.yml in.yml`

#### edit
open and decrypt an existing vaulted file in an editor, that will be encrypted again when closed.
Usage: `ansible-vault edit [--vault-password-file, --vault-pass-file] vault.yml`

#### view
open, decrypt and view an existing vaulted file using a pager using the supplied vault secret.
Usage: `ansible-vault view [--vault-password-file, --vault-pass-file] vault.yml`

## Playbooks
Playbooks are automation blueprints, in [YAML](../../files/YAML.md) format, that Ansible uses to deploy and configure nodes in an inventory. You can use variables with this syntax `{{ result.stdout | from_json }}`.

Example playbook:
```yml
- name: GPU Passthrough
  hosts: pve
  become: true
  vars_prompt:
    - name: pcie_hw_ids
      prompt: "Enter PCIE Hardware IDs"
      private: false

  tasks:
    - name: Enable iommu (amd)
      ansible.builtin.lineinfile:
        dest: /etc/default/grub
        regexp: .*GRUB_CMDLINE_LINUX_DEFAULT.*
        line: |
          GRUB_CMDLINE_LINUX_DEFAULT="quiet amd_iommu=on iommu=pt pcie_acs_override=downstream,multifunction nofb nomodeset video=vesafb:off video=efifb:off"
      register: grub_cfg

    - name: Enable vfio modules
      ansible.builtin.blockinfile:
        dest: /etc/modules
        block: |
            vfio
            vfio_iommu_type1
            vfio_pci
            vfio_virqfd

    - name: Set vfio configuration
      ansible.builtin.copy:
        dest: /etc/modprobe.d/vfio.conf
        owner: root
        mode: "0644"
        content: |
            options vfio-pci ids={{ pcie_hw_ids }}

    - name: Blacklist drivers
      become: true
      ansible.builtin.copy:
        dest: /etc/modprobe.d/gpu-blacklist.conf
        content: |
          blacklist radeon
          blacklist nouveau
          blacklist nvidia
          blacklist amdgpu
          blacklist snd_hda_intel

    - name: Update grub
      ansible.builtin.shell:
        cmd: grub-mkconfig -o /boot/grub/grub.cfg
      when: grub_cfg.changed
```

### Playbook fields

- **`name`**: A human-readable description for the task.
```yml
- name: My Playbook  
  hosts: all
  tasks:
    - name: My Task
  ...
```    
- **`hosts`**: Specifies the target hosts or groups from inventory on which the tasks should be executed.
```yml
- name: My Playbook
  hosts: web_servers
  tasks:
  ...
```
- **`gather_facts`**: A boolean indicating whether Ansible should gather facts about the target hosts before executing tasks.
```yml
- name: My Playbook
  hosts: all
  gather_facts: true
  tasks:
  ...
```
- **`become`**: Indicate that tasks should be executed with escalated privileges (sudo).
```yml
- name: My Playbook
  hosts: all
  become: true
  tasks:
  ...
```
- **`become_user`**: Specify the user to become when using privilege escalation.
```yml
- name: My Playbook
  hosts: all
  become: true
  become_user: someuser
  tasks:
  ...
```
- **`vars`**: Define variables that can be used in the playbook.
```yml
- name: My Playbook
  hosts: all
  vars:
    my_variable: "value"
  tasks:
  ...
```
- **`vars_files`**: Include external variable files.
```yml
- name: My Playbook
  hosts: all
  vars_files:
    - my_vars.yml
  tasks:
  ...
```
- **`vars_prompt`**: Get info from user.
```yml
- hosts: all
  vars_prompt:
    - name: username
      prompt: What is your username?
      private: false

    - name: password
      prompt: What is your password?

  tasks:
    - name: Print a message
      ansible.builtin.debug:
        msg: 'Logging in as {{ username }}'
```
- **`include`** or **`import`**: Include or import other playbooks.
```yml
- name: My Playbook
  hosts: all
  tasks:
    - include: other_playbook.yml
```
- **`include_vars`**: Include external variable files dynamically.
```yml
- name: Include external variables
  include_vars:
    file: external_vars.yml
```
- **`tasks`**: A list of tasks to be executed. Each task is defined as a dictionary.
```yml
- name: My Playbook
  hosts: all
  tasks:
    - name: Task 1
	...
	  - name: Task 2
	...
```
- **`environment`**: Set environment variables for a task.
```yml
- name: Run a command with a specific environment
  command: echo $MY_VARIABLE
  environment:
    MY_VARIABLE: "some_value"
```
- **`when`**: Specifies a condition for executing a task.
```yml
  tasks:
    - name: Shut down Debian flavored systems
      ansible.builtin.command: /sbin/shutdown -t now
      when: ansible_facts['os_family'] == "Debian"
```
- **`register`**: Save the result of a task into a variable for later use.
```yml
- name: Execute a command and register the output
  command: echo "Hello, World!"
  register: command_output
  
- name: Display the registered output
  debug:
    var: command_output.stdout
```
- **`loop`**: Execute module multiple times
```yml
- name: Add several users
  ansible.builtin.user:
    name: "{{ item }}"
    state: present
    groups: "wheel"
  loop:
     - testuser1
     - testuser2
```

See these pages for usage in your playbooks.:
- [Ansible Filters](filters/Ansible%20Filters.md),
- [Ansible Lookup Plugins](lookups/Ansible%20Lookup%20Plugins.md)
- [Ansible Modules](modules/Ansible%20Modules.md)
- [Ansible Test Plugins](tests/Ansible%20Test%20Plugins.md)