= Appendix: Installing software using the Ansible Configuration Management tool =
== Tools: ==

To run this exercise, you will need two pieces of software.  If you haven't already, get or install these now:
   i. `omni` installed on your local machine ([http://trac.gpolab.bbn.com/gcf/wiki#GettingStarted instructions]), and
   i. `ansible` installed on your local machine ([http://docs.ansible.com/intro_installation.html#latest-release-via-yum find the instructions for your package manager here]).

== Resources: ==
   * Ansible Resources:
     - A third party [https://serversforhackers.com/an-ansible-tutorial Getting Started with Ansible walk through]
     - [http://docs.ansible.com/modules_by_category.html Ansible Module Documentation]

== Instructions ==
=== 2.  Establish the Environment ===
   a. To run this exercise, you will need an account and two pieces of software.  If you haven't already, get or install these now:
      i. a GENI Portal account ([SignMeUp instructions]),
      ii. `omni` installed and configured on your local machine ([http://trac.gpolab.bbn.com/gcf/wiki#GettingStarted instructions]), and
      iii. `ansible` installed on your local machine ([http://docs.ansible.com/intro_installation.html#latest-release-via-yum find the instructions for your package manager here]).
{{{
#!div style="background: #fdd; border: 3px ridge; width: 800px;"

Windows users should do the following steps

{{{
#!html

<table id="Table_03" border="0" cellpadding="5" cellspacing="0">
	<tr>
		<td>
			<img src="http://groups.geni.net/geni/attachment/wiki/GENIExperimenter/Tutorials/Graphics/Symbols-Tips-icon.png?format=raw" width="50" height="50" alt="Tip">
               </td>
               <td>
                   Windows users should follow the instructions for setting up a <a href="http://groups.geni.net/geni/wiki/GENIExperimenter/Tutorials/AnsibleHelloGENI/StandaloneSetup">separate GENI node for running Ansible</a>.
               </td>
        </tr>
</table>
}}}
}}}  
   a. Download the webpages and scripts needed for the HelloGENI exercise.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
Use `wget` to download the tarball of files onto your local machine and use `tar` to uncompress it:
   {{{
#!sh
wget http://www.gpolab.bbn.com/experiment-support/HelloGENI/hellogeni-install.tar.gz
tar zxvf hellogeni-install.tar.gz
   }}}
}}}


== 4.  Configure and Initialize ==

`omni` comes with a script, `readyToLogin` which finds the login information for nodes in your slice.  As of `omni` version 2.8, `readyToLogin` has an `--ansible-inventory` flag which generates the Ansible inventory, which is a flat file which tells Ansible the name and login information for your nodes.

 a. Create your Ansible inventory file:
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
On your local machine:

   {{{
#!sh
$ readyToLogin MYSLICE --useSliceAggregates --ansible-inventory -o
$ cat inventory
   }}}

Example output of running these commands:
   {{{
#!sh
$ readyToLogin MYSLICE --useSliceAggregates --ansible-inventory -o
Host info saved in inventory file: /Users/jdoe/projects/GENI/hellogeni/inventory

$ cat inventory
client  ansible_ssh_host=pc3.instageni.clemson.edu  ansible_ssh_port=33850
server  ansible_ssh_host=pcvm3-6.instageni.clemson.edu
   }}}

{{{
#!html

<table id="Table_03" border="0" cellpadding="5" cellspacing="0">
	<tr>
		<td>
			<img src="http://groups.geni.net/geni/attachment/wiki/GENIExperimenter/Tutorials/Graphics/Symbols-Tips-icon.png?format=raw" width="50" height="50" alt="Tip">
               </td>
               <td>
                   If your GENI Username is different than your username on your local machine, append the following information to each line of the `inventory` file:
<pre>
ansible_ssh_user = GENIUSERNAME
</pre>
Your GENIUSERNAME is shown in the header of the GENI Portal in the upper right hand corner.
               </td>
        </tr>
</table>
}}}
}}}
{{{
#!div style="background: #fdd; border: 3px ridge; width: 800px;"

{{{
#!html

<table id="Table_03" border="0" cellpadding="5" cellspacing="0">
	<tr>
		<td>
			<img src="http://groups.geni.net/geni/attachment/wiki/GENIExperimenter/Tutorials/Graphics/Symbols-Tips-icon.png?format=raw" width="50" height="50" alt="Tip">
               </td>
               <td>
                   Windows users should copy their 'inventory' file onto their node running the ansible client.
               </td>
        </tr>
</table>
}}}
}}}  
 b. Be sure your private key has been added to your SSH agent:
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
   {{{
ssh-add /path/to/your/private/key
   }}}
}}}
 c. Check to see if your nodes are up and ready.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
This command uses the `ping` module to ping the specified nodes (in this case `all`) listed in the inventory file:
   {{{
#!sh
$ ansible -i inventory all -m ping 
   }}}

Example output showing all of the nodes responding to ping:
   {{{
#!sh
$ ansible -i inventory all -m ping 
client | success >> {
    "changed": false,
    "ping": "pong"
}

server | success >> {
    "changed": false,
    "ping": "pong"
}
   }}}
}}}
 c. Try using the ping module in Ansible to only ping `server` or `client` by replacing `all` in the above with `server` or `client`.

{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"

{{{
#!html

<table id="Table_03" border="0" cellpadding="5" cellspacing="0">
	<tr>
		<td>
			<img src="http://groups.geni.net/geni/attachment/wiki/GENIExperimenter/Tutorials/Graphics/Symbols-Tips-icon.png?format=raw" width="50" height="50" alt="Tip">
               </td>
               <td>
                   Ansible commands can be collected into files called <i>Playbooks</i>.  Playbooks are in a configuration file format called <i>YAML</i> which is very straightforward.   In particular, Ansible Ad Hoc commands easily map to commands used in an Ansible Playbook.  
               </td>
        </tr>
</table>
}}}
}}}