Statistics
| Branch: | Revision:

iof-tools / README.md @ b9954290

History | View | Annotate | Download (5.02 KB)

1
Internet on FIRE Scripts Repo
2
===
3

    
4
## ASSUMPTIONS
5

    
6
This `README` assumes that:
7
* you are working on a Unix-like system, so the variable `$HOME` is available;
8
* all the software will be in the `$HOME/src` folder;
9
* this repository has been cloned to `$HOME/src/iof-tools`;
10

    
11
Please execute the following beforehand:
12
```
13
mkdir -p $HOME/src
14
```
15

    
16
## Omni tool
17

    
18
The [Omni](https://github.com/GENI-NSF/geni-tools/wiki/Omni) command line tool is
19
required to perform operations on the remote testbeds. Supported operations
20
include querying for testbed status/available resources, allocating/releasing
21
resources (slices) and creating/deleting experiments.
22

    
23
### Omni software dependencies
24

    
25
`omni` only works with Python version 2, so you should either switch your system
26
wide installation of Python to version 2 or install Python 2 and then change the
27
first line of the `omni` tool source code (see Omni installation).
28
On ubuntu, in order to install the `omni`'s software dependencies run the
29
following command:
30

    
31
```
32
sudo apt install python-m2crypto python-dateutil python-openssl libxmlsec1 \
33
    xmlsec1 libxmlsec1-openssl libxmlsec1-dev autoconf
34
```
35

    
36
For other operating systems take a look at the official [wiki
37
page](https://github.com/GENI-NSF/geni-tools/wiki/QuickStart#debian--ubuntu)
38

    
39
### Omni installation
40

    
41
In order to install `omni` executes the following commands:
42

    
43
```
44
cd $HOME/src
45
git clone https://github.com/GENI-NSF/geni-tools omni
46
cd omni
47
./autogen.sh
48
./configure
49
make
50
cd $HOME/src/iof-tools
51
ln -s $HOME/src/omni/src/omni omni
52
```
53

    
54
If you are using Python version 3 and you don't want to switch system-wide to
55
Python 2, edit the first line of the `omni` source file and change it to
56
```
57
#!/usr/bin/env python2
58
```
59

    
60
Verify that `omni` has been installed correctly by executing `omni --version`.
61
This command should print something that resembles the following:
62

    
63
```
64
omni: GENI Omni Command Line Aggregate Manager Tool Version 2.11
65
Copyright (c) 2011-2016 Raytheon BBN Technologies
66
```
67

    
68
## RSPEC generation
69

    
70
RSPEC files (extension .rspec) are XML files that describes which nodes to
71
allocate in a given testbed. For the TWIST and w.iLab1 testbeds the .rspec files
72
can be generated automatically using the `gen-rspec.py` script. The script
73
supports the following command line parameters:
74

    
75
* `-t` (`--testbed`): specifies which testbed the RSPEC will be generated for.
76
  Use twist for the TWIST testbed and wilab for w.iLab1;
77

    
78
* `-f` (`--filter`): comma separated list of node name prefixes. Only the
79
  available nodes whose name starts with one of the specified prefixes are
80
  inserted in the generated RSPEC. By default all the available nodes are used for
81
  generating the RSPEC file.
82

    
83
* `-n` (`--nodes`): comma separated list of node names. Only the available nodes
84
  whose name is listed with the `-n` option are inserted in the RSPEC file. By
85
  default all the available nodes are used. The `-n` option takes precedence over
86
  `-f`.
87

    
88
* `-w` (`--hardware`): comma separated list of hardware types (e.g., `pcgen05`)
89

    
90
For example, an RSPEC containing all the available nodes in the TWIST testbed
91
can be generated with the following command:
92

    
93
```
94
./gen-rspec.py -t twist > twist_all.rspec
95
```
96

    
97
Instead, an RSPEC containing all the nuc nodes in the TWIST testbed can be
98
generated with the following command:
99

    
100
```
101
./gen-rspec.py -t twist -f nuc > twist_nuc.rspec
102
```
103

    
104
An RSPEC containing only nuc4 and nuc6 from the TWIST testbed can be
105
generated with the following command:
106

    
107
```
108
./gen-rspec.py -t twist -n nuc4,nuc6 > twist_nuc_4_6.rspec
109
```
110

    
111
An RSPEC containing nodes of hardware type `pcgen05` from both the
112
VirtualWall1 and the VirtualWall2 testbeds can be generated with the following
113
command:
114

    
115
```
116
./gen-rspec.py -t wall1,wall2 -w pcgen05 > iof.rspec
117
```
118

    
119
Note that, in any case, a node is inserted in the RSPEC only if it is available
120
in the moment the `gen-rspec.py` command is executed. For this reason the
121
suggested best practice is to execute `gen-rspec.py` just before allocating the
122
resources using the `reserve.py` command.
123

    
124
## Generating SSH and Ansible config
125

    
126
After generating the `rspec` file, the `gen-config.py` script can generate
127
the SSH and the ansible configuration files to access the nodes of the
128
testbeds. To do so, simply run:
129

    
130
```
131
./gen-config.py -r <rspec file> -k <identity file>
132
```
133

    
134
The identity file is the private key or the certificate obtained after getting
135
an account from the [iMinds authority](https://authority.ilabt.iminds.be/).
136

    
137
This will generate:
138
* `ssh-config`: the configuration file to be given to the SSH command (e.g.,
139
  `ssh -F ssh-config ...`). This defines the names of the hosts as `node<i>`,
140
  for `i` going from 0 to N-1. To connect to one host, you can thus run
141
  `ssh -F ssh-config node0`.
142
* `ansible.cfg`: the Ansible configuration file.
143
* `ansible-hosts`: the Ansible inventory (list of nodes). In this file the
144
  group of nodes reserved for the experiments is named `nodes`. To test that
145
  this is properly working, try with `ansible nodes -m shell -a "uptime"`.
146

    
147
The filename of the configuration files can be changed via command line
148
arguments (see `./gen-config.py --help`).