# Run Your First Command and Playbook

Put the concepts you learned to work with this quick tutorial. Install Ansible, execute a network configuration command manually, execute the same command with Ansible, then create a playbook so you can execute the command any time on multiple network devices.

Topics

- Run Your First Command and Playbook
  - Prerequisites
  - Install Ansible
  - Establish a Manual Connection to a Managed Node
  - Run Your First Network Ansible Command
  - Create and Run Your First Network Ansible Playbook

## Prerequisites

Before you work through this tutorial you need:

- Ansible 2.5 (or higher) installed
- One or more network devices that are compatible with Ansible
- Basic Linux command line knowledge
- Basic knowledge of network switch & router configuration

## Install Ansible

Install Ansible using your preferred method. See Installation Guide. Then return to this tutorial.

Confirm the version of Ansible (must be >= 2.5):

    ansible --version

## Establish a Manual Connection to a Managed Node

To confirm your credentials, connect to a network device manually and retrieve its configuration. Replace the sample user and device name with your real credentials. For example, for a VyOS router:

    ssh my_vyos_user@vyos.example.net
    show config
    exit

This manual connection also establishes the authenticity of the network device, adding its RSA key fingerprint to your list of known hosts. (If you have connected to the device before, you have already established its authenticity.)

## Run Your First Network Ansible Command

Instead of manually connecting and running a command on the network device, you can retrieve its configuration with a single, stripped-down Ansible command:

    ansible all -i vyos.example.net, -c network_cli -u my_vyos_user -k -m vyos_facts -e ansible_network_os=vyos

The flags in this command set seven values:
  - the host group(s) to which the command should apply (in this case, all)
  - the inventory (-i, the device or devices to target - without the trailing comma -i points to an inventory file)
  - the connection method (-c, the method for connecting and executing ansible)
  - the user (-u, the username for the SSH connection)
  - the SSH connection method (-k, please prompt for the password)
  - the module (-m, the ansible module to run)
  - an extra variable ( -e, in this case, setting the network OS value)

NOTE: If you use `ssh-agent` with ssh keys, Ansible loads them automatically. You can omit `-k` flag.

## Create and Run Your First Network Ansible Playbook

If you want to run this command every day, you can save it in a playbook and run it with ansible-playbook instead of ansible. The playbook can store a lot of the parameters you provided with flags at the command line, leaving less to type at the command line. You need two files for this - a playbook and an inventory file.

1. Download `first_playbook.yml`, which looks like this:

    ---

    - name: Network Getting Started First Playbook
      connection: network_cli
      gather_facts: false
      hosts: all
      tasks:

        - name: Get config for VyOS devices
          vyos_facts:
            gather_subset: all

        - name: Display the config
          debug:
            msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}"

The playbook sets three of the seven values from the command line above: the group (`hosts: all`), the connection method (`connection: network_cli`) and the module (in each task). With those values set in the playbook, you can omit them on the command line. The playbook also adds a second task to show the config output. When a module runs in a playbook, the output is held in memory for use by future tasks instead of written to the console. The debug task here lets you see the results in your shell.

2. Run the playbook with the command:

    ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos first_playbook.yml

The playbook contains one play with two tasks, and should generate output like this:

    $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos first_playbook.yml

    PLAY [First Playbook]
    ***************************************************************************************************************************

    TASK [Get config for VyOS devices]
    ***************************************************************************************************************************
    ok: [vyos.example.net]

    TASK [Display the config]
    ***************************************************************************************************************************
    ok: [vyos.example.net] => {
        "msg": "The hostname is vyos and the OS is VyOS"
    }

3. Now that you can retrieve the device config, try updating it with Ansible. Download `first_playbook_ext.yml`, which is an extended version of the first playbook:

    ---

    - name: Network Getting Started First Playbook Extended
      connection: network_cli
      gather_facts: false
      hosts: all
      tasks:

        - name: Get config for VyOS devices
          vyos_facts:
            gather_subset: all

        - name: Display the config
          debug:
            msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}"

        - name: Update the hostname
          vyos_config:
            backup: yes
            lines:
              - set system host-name vyos-changed

        - name: Get changed config for VyOS devices
          vyos_facts:
            gather_subset: all

        - name: Display the changed config
          debug:
            msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}"

The extended first playbook has four tasks in a single play. Run it with the same command you used above. The output shows you the change Ansible made to the config:

    $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos first_playbook_ext.yml

    PLAY [First Playbook]
    ************************************************************************************************************************************

    TASK [Get config for VyOS devices]
    **********************************************************************************************************************************
    ok: [vyos.example.net]

    TASK [Display the config]
    *************************************************************************************************************************************
    ok: [vyos.example.net] => {
        "msg": "The hostname is vyos and the OS is VyOS"
    }

    TASK [Update the hostname]
    *************************************************************************************************************************************
    changed: [vyos.example.net]

    TASK [Get changed config for VyOS devices]
    *************************************************************************************************************************************
    ok: [vyos.example.net]

    TASK [Display the changed config]
    *************************************************************************************************************************************
    ok: [vyos.example.net] => {
        "msg": "The hostname is vyos-changed and the OS is VyOS"
    }

    PLAY RECAP
    ************************************************************************************************************************************
    vyos.example.net           : ok=6    changed=1    unreachable=0    failed=0

This playbook is useful. However, running it still requires several command-line flags. Also, running a playbook against a single device is not a huge efficiency gain over making the same change manually. The next step to harnessing the full power of Ansible is to use an inventory file to organize your managed nodes into groups with information like the `ansible_network_os` and the SSH user.