1 Objective

This exercise will get ansible up and running, to the point where it is able to run commands on all the remote systems you are managing.

2 Initial setup

2.1 Connect

You need to connect to your first host: this is the master machine which you are going to use to administer the others.

Make sure you connect to this as your normal ("sysadm") user. You will use "sudo" where specific commands need to be run as root. It is good practice to do this.

2.2 Install ansible package

Ubuntu 14.04 already has a sufficiently-recent version of ansible for our purposes, so you can just install it directly. Type the following:

sudo apt-get install ansible cowsay

There are a number of settings in /etc/ansible/ansible.cfg which you can review, but you don't need to change any of them.

2.3 Create inventory

Now you need to list all your other hosts in the inventory: that is, the machines you are going to manage using ansible.

You need to edit the file /etc/ansible/hosts as root, for example:

sudo editor /etc/ansible/hosts

(replace "editor" with whichever editor you prefer, e.g. vi or nano)

Add the full hostnames of the other hosts you have, not including the master host where you are running ansible.

hostXXX.ws.nsrc.org
hostYYY.ws.nsrc.org
hostZZZ.ws.nsrc.org

This file contains plenty of comments. It's up to you whether to add these lines above or below the comments, or even remove the comments entirely.

3 Getting ansible to connect

Probably the hardest part of working with ansible is getting it to connect to your hosts. After that it's plain sailing :-)

There is a module called "ping" which you can use to test the connections. It does nothing but respond with a "pong".

So now try the following command:

ansible all -m ping

What this means is:

Very likely you are going to see an error like this:

hostXXX.ws.nsrc.org | FAILED => SSH encountered an unknown error during the
connection. We recommend you re-run the command using -vvvv, which will
enable SSH debugging output to help diagnose the issue

So let's do as it suggests, and see if that gives some more information. To make the output easier to read, you can tell ansible to connect to only a single host instead of "all".

ansible hostXXX.ws.nsrc.org -m ping -vvvv

3.1 Key problems

Do you see an error like this?

...
debug1: No more authentication methods to try.
Permission denied (publickey,password).

Then it means that it tried to use public key authentication, but failed.

Are you able to use ssh directly at the command line to login to the other host?

hostNNN:~$ ssh hostXXX.ws.nsrc.org

If not, then you need to debug this problem.

3.2 The shell module

The "shell" module gives you a simple way to run commands on a remote host or hosts. Try it:

ansible all -m shell -a 'ls /'

Did it connect to all hosts? Did it give a directory listing from each host?

Don't move on until the "ping" and "shell" modules are working. Ask for help from an instructor if you need it.

4 Running commands as root

The commands you have tried so far don't need to run with root privileges on the target system, but most system adminstration commands do.

Try the following command, which shows the content of a protected file containing password hashes:

ansible all -m shell -a 'cat /etc/shadow'

You should get responses like this (in red, if your terminal supports it):

hostXXX.ws.nsrc.org | FAILED | rc=1 >>
cat: /etc/shadow: Permission denied

So really, we want to run this command as the "root" user. Try it:

ansible all -m shell -a 'cat /etc/shadow' -u root

Did it work? If so, great! It means you already put your ssh public key in /root/.ssh/authorized_keys. You can skip to the next section.

If not: there is a workaround, because you can get ansible to use "sudo" on the remote system to get root. Try this:

ansible all -m shell -a 'cat /etc/shadow' -sK

Be careful of letter case in the flags: small "s" means use sudo, large "K" means prompt for the password which sudo requires.

Did that work? If not, again ask for help.

However this is still pretty inconvenient because we don't want to be prompted for a password every time we connect. Really we want to put our ssh public key in /root/.ssh/authorized_keys on every target system, so that we can login directly as the "root" user, bypassing sudo.

You can do this by hand, but this is the sort of system administration task which ansible is perfectly suited for, so let's get ansible to make the change for us!

First, we need to ensure the /root/.ssh directory exists, and create it if not. Run the following:

ansible all -m file -a 'path=/root/.ssh state=directory owner=root group=root mode=700' -sK

This means:

Did it complete successfully? This is an idempotent operation, so you can run it more than once and the subsequent runs won't change anything.

Now we need to copy your public key across:

ansible all -m copy -a 'src=/home/sysadm/.ssh/authorized_keys dest=/root/.ssh/authorized_keys owner=root group=root mode=644' -sK

You are using a new module: the copy module copies a file from the local system (the one running ansible) to the remote system(s).

Finally, check you can login directly as "root":

ansible all -m shell -a 'cat /etc/shadow' -u root

If this works, you have sorted out all your ansible authentication and are good to continue.

5 Further steps

5.1 Inventory variables

It's still a bit inconvenient to have to type -u root every time we connect, so let's make ansible remember that.

Here's one way to do it. Edit the inventory file (remember it's /etc/ansible/hosts) and add a setting to every host like this:

hostXXX.ws.nsrc.org ansible_ssh_user=root
hostYYY.ws.nsrc.org ansible_ssh_user=root
hostZZZ.ws.nsrc.org ansible_ssh_user=root

Now see that you can run commands as root without the -u root flag:

ansible all -m shell -a 'cat /etc/shadow'

5.2 Ansible documentation

It's important to be able to locate the ansible documentation. You can find it at docs.ansible.com; there may be a local mirror of this at http://www.ws.nsrc.org/mirrors/docs.ansible.com/ or elsewhere as given by the instructors.

Find your way to the Module Index and look for documentation for the "file" and "copy" modules which you have already used.

You have now completed this exercise!

6 Additional information

THIS SECTION IS FOR INFORMATION ONLY - you don't need to do the following.

6.1 Newer versions of ansible

The ansible PPA provides a more recent version of ansible. If you need it, install as follows:

sudo apt-get install software-properties-common  # (12.04: python-software-properties)
sudo add-apt-repository ppa:rquillo/ansible
sudo apt-get update
sudo apt-get install ansible

If you are using Debian Wheezy, add the backports repository then

sudo apt-get update
sudo apt-get install ansible/wheezy-backports

6.2 Password authentication

It is possible to use ansible without ssh keys. This may be useful if you are unable to use keys in your environment for some reason.

You need the -k flag to prompt for the password, and to install the sshpass helper program.

$ ansible all -m ping -k
SSH password: <type the password here>
hostXXX.ws.nsrc.org | FAILED => to use the 'ssh' connection type with
passwords, you must install the sshpass program

$ sudo apt-get install sshpass
...
$ ansible all -m ping -k
SSH password: <type the password here>
hostXXX.ws.nsrc.org | success >> {
    "changed": false,
    "ping": "pong"
}

You can also combine the sudo flags (so you get -skK), and give -u <username> to give the username to login as, if this is not the same as the local user name.

However this is inconvenient because every time you run ansible you need to provide the flags and the passwords. It is much better to set up SSH key authentication with agent forwarding, so that your user is able to login directly as "root" on the target systems.