= [wiki:GENIExperimenter/Tutorials/GENI-SAVI Get to Know GENI and SAVI] =
{{{
#!html
}}}
----
= STEPS FOR SETTING UP =
----
== 0. Prerequisites: Get a SAVI account and an Omni bundle ==
* Make sure you have SSH keys and SSL certificates in the GENI Portal. You can verify this by browsing to the [https://portal.geni.net/secure/profile.php Profile tab] on the Portal and looking under ''SSH Keys'' and ''SSL''.
* Getting a SAVI account:
* On the GENI Portal, scroll down on the [https://portal.geni.net/secure/home.php Home] page until you see ''Tools''. Press the '''SAVI''' button.
* Proceed through the remaining prompts until you get an email with your SAVI username and password.
* Finally, go to [http://portal.savitestbed.ca/] and login to verify that your credentials work.
* Getting an Omni bundle:
* In the GENI portal, browse to the [https://portal.geni.net/secure/profile.php Profile tab] and then select ''Configure Omni''. If necessary, follow the prompts to generate an SSL certificate. Then, click the '''Download your omni data''' button.
== 1.Use the SAVI Client and the Federation Tool to Create a GENI Slice OMNI Bundle ==
* Use `scp` to transfer the `omni.bundle` you downloaded in the pre-work from your local machine to the `Downloads` folder on `client1.savitestbed.ca`.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
From the folder containing `omni.bundle`, run:
{{{
$ scp omni.bundle @client1.savitestbed.ca:Downloads
}}}
When prompted, enter the SAVI username and password.
|| [[Image(wiki:GENIExperimenter/Tutorials/Graphics:tip.png, nolink, 50px, bottom)]] || '''Tip:''' Windows users should use an SCP client of their choice (such as `winscp`) ||
}}}
* Using your SAVI credentials, log in to `client1.savitestbed.ca` using `ssh`.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
|| [[Image(wiki:GENIExperimenter/Tutorials/Graphics:tip.png, nolink, 50px, bottom)]] || '''Tip:''' Any SSH tool can be used for this, including the built-in terminal tools on any Unix- or Linux-based system, or the Putty and cygwin ssh on Windows. ||
On UNIX-like systems do:
{{{
$ ssh @client1.savitestbed.ca
}}}
}}}
* Once you are logged in, configure omni.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
Run:
{{{
$ omni-configure
}}}
}}}
* `omni-configure` should place your SSH keys (`geni_key_portal` and `geni_key_portal.pub`) in your `~/.ssh` folder on `client1.savitestbed.ca`.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
Check to make sure that the keys are there:
{{{
$ ls ~/.ssh
geni_cert_portal_key geni_cert_portal_key.pub geni_key_portal geni_key_portal.pub id_rsa.pub known_hosts
}}}
}}}
* Now download and unpack the GENI-SAVI Federation Tool
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
{{{
$ wget http://web.uvic.ca/~sushilb/federation/tutorial.tar
$ tar xvf tutorial.tar
}}}
}}}
== 2. Create a slice on GENI and reserve some virtual machines in it ==
* We will now create a slice on GENI. Use `gs-` as the slice name.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
* Change into the tutorial directory:
{{{
cd tutorial
}}}
* In the tutorial directory, run:
{{{
$ ./tutorial.sh createslice geni
}}}
}}}
* The general form of the command to create a VM on GENI is:
{{{
$ ./tutorial.sh createvm geni
}}}
* Now add a VM running Ubuntu 14 at the '''InstaGENI Rack''' assigned to you.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
{{{
$ ./tutorial.sh createvm geni Ubuntu-14-04
}}}
This will take about a minute. It will then come back with a response of the form
{{{
Result Summary: Got Reserved resources RSpec from ...
To connect to the created VM please use the hostname="."
}}}
The machine will now be in a booting state. It will take about 5-10 minutes before you can log in. We'll use the time productively and create a SAVI VM while we wait.
}}}
== 3. Create virtual machines on SAVI at Toronto or Victoria ==
* The general form of the command to create a VM on SAVI is
{{{
$ ./tutorial.sh createvm savi
}}}
* Each group will be given a specific site and values for all parameters. The `vm-name` should be your GENI username, followed by the `sitename`. e.g., for `rickmcg`, the name at Toronto will be `rickmcg-toronto`
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
Use the following command to reserve your SAVI node:
{{{
$ ./tutorial.sh createvm savi geniUsers Ubuntu-14-04-64 small geni_key_portal -
}}}
}}}
* You should now have one VM on a GENI rack and one VM at a SAVI site.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
Check the status of your resources on both GENI and SAVI:
{{{
$ ./tutorial.sh listinstance geni
$ ./tutorial.sh listinstance savi
}}}
}}}
* Make note of the hostname for your GENI VM and the public IP address listed for your SAVI VM as these will be used in the next step. ''Notice that access to the SAVI machines are by IP address.''
== 4. Set up Ansible for your experiment ==
{{{
#!comment
Ansible (http://docs.ansible.com) is a free, open-source, intuitive IT automation tool that is well-suited to the tasks in this tutorial. Ansible commands can be run from the command line or put in a YAML file called a ''playbook''. We will be creating an Ansible playbook to run the parameterized HTTP query described earlier.
Two basic concepts in Ansible are ''inventories'' and ''modules''. An inventory is a list of hosts to be managed by Ansible, organized into groups. When you run Ansible commands, either from the command-line or in a playbook, you specify the host group that the command should operate on. In this way Ansible commands can operate on many hosts in parallel. Take a look at the Ansible inventory in your '''ansible-hosts''' file. This is basically the equivalent of the '''ssh-config''' except it's specialized for Ansible.
A ''task'' in Ansible consists of a module and some arguments for the module. A module provides a declarative abstraction on top of standard shell commands. So for example, in the shell on an Ubuntu machine you might install package “foo” like this:
{{{
$ sudo apt-get update
$ sudo apt-get install foo
}}}
An equivalent Ansible task in a playbook would look like:
{{{
- apt: name=foo state=latest update_cache=yes
}}}
Or the same Ansible task could be invoked directly on the command line like this:
{{{
$ ansible remote-machine -m apt -a "name=foo state=latest update_cache=yes"
}}}
The task uses the '''apt''' module, and tells Ansible: “Make sure the latest version of package foo is installed”. There are many other modules which are well-documented at http://docs.ansible.com.
Here are a few Ansible tasks to run, to get some experience with the command-line interface.
}}}
=== (a) Create an Ansible inventory file ===
{{{
#!div style="background: #E6D8F0; border: 3px ridge; width: 800px;"
An Ansible inventory file is of the form
{{{
[group_name]
server1_spec
server2_spec
}}}
where `group_name` is a name for a group of nodes, and a server spec contains login information for a node. An example of a server specification is:
{{{
ansible_ssh_host=142.150.208.146 ansible_ssh_port=22 ansible_ssh_user=rickmcg_geni ansible_ssh_private_key=~/.ssh/geni_key_portal
}}}
}}}
* Create an Ansible inventory file named `ansible-hosts` for your slice.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
Your ansible inventory file should look like this:
{{{
[nodes]
ansible_ssh_port=22 ansible_ssh_user= ansible_ssh_key=~/.ssh/geni_key_portal
ansible_ssh_port=22 ansible_ssh_user=ubuntu ansible_ssh_key=~/.ssh/geni_key_portal
}}}
Where `geni_resource_name` and `savi_resource_ip` are what you found from the `listinstance` commands from step 3.
}}}
=== (b) Add private key to SSH agent ===
In the next step, Ansible will try to SSH into multiple nodes.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
To save time entering the passphrase for your private key multiple times, add your private key to your ssh agent as follows:
{{{
$ ssh-agent bash
$ ssh-add ~/.ssh/geni_key_portal
}}}
}}}
=== (c) The ping module ===
The '''ping''' module simply tries to do a SSH login to a node and reports success or failure.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
Run the following command on your controller:
{{{
$ ansible nodes -i ansible-hosts -m ping
}}}
If you don’t see success everywhere then there is something wrong with your setup. Ask one of the tutorial leaders for help.
}}}
=== (d) The shell module ===
The '''shell''' module lets you run arbitrary SSH commands in parallel across a set of hosts. It’s useful for poking around, or if there is no Ansible module with the functionality you need.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
Try it out:
{{{
$ ansible nodes -i ansible-hosts -m shell -a "hostname"
}}}
You can replace ''hostname'' above with any other Linux command.
}}}
=== (e) The setup module ===
The '''setup''' module gathers a bunch of information about each node and saves it in variables that you can reference in your Ansible playbook. This will be really useful to do the tutorial!
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
Try it out on a node to see what it collects (replace `` with your hostname):
{{{
$ ansible -i ansible-hosts -m setup
}}}
}}}
{{{
#!comment
=== (f) A simple playbook ===
Next, we will look at a simple Ansible playbook. An Ansible playbook is a YAML file containing a list of Ansible tasks. Copy the playbook below into a file called test.yaml:
{{{
#!python
---
- hosts: nodes
remote_user: root
tasks:
- name: An example of a debug statement
debug: var=ansible_hostname
}}}
Run the playbook as:
{{{
$ ansible-playbook -i ansible-hosts test.yaml
}}}
The '''setup''' module is run automatically at the beginning of a playbook to populate variables for each node. The above playbook will dump the value of each node’s ''ansible_hostname'' variable. To run the playbook on a single node, replace ''nodes'' with the name of one of your slice nodes (e.g., slice338.pcvm3-7.instageni.nps.edu).
----
}}}
== 5. Create and run an Ansible playbook to install the software you will need ==
Now you will use a playbook to install the software you will need on all the nodes.
{{{
#!div style="background: #ffd; border: 3px ridge; width: 800px;"
The ansible playbook you will need:
{{{
---
- hosts: nodes
remote_user: root
sudo: yes
tasks:
- name: Update apt cache
apt: update_cache=yes
- name: Install dnsutils (for dig)
apt: name=dnsutils
- name: Install geoip-bin (for geoiplookup)
apt: name=geoip-bin
- name: Install curl
apt: name=curl
}}}
* To download this playbook to your client machine, type:
{{{
wget http://groups.geni.net/geni/raw-attachment/wiki/GENIExperimenter/Tutorials/GENI-SAVI/DesignSetup/software-install-solution.yaml
}}}
* Run this playbook on your Ansible control machine against all the nodes in your slice.
{{{
ansible-playbook -i ansible-hosts software-install-solution.yaml
}}}
|| [[Image(wiki:GENIExperimenter/Tutorials/Graphics:tip.png, nolink, 50px, bottom)]] || '''Pro Tip:''' use the `-f` argument to `ansible-playbook` to speed things up -- it lets you control the number of nodes to operate on in parallel, and the default is 5. Specifying `-f 20` will run the playbook's tasks against all your nodes in parallel. ||
}}}
----
= [wiki:GENIExperimenter/Tutorials/GENI-SAVI/Execute Next: Run Experiment] =
