Statistics
| Branch: | Revision:

iof-tools / README.md @ c23dc480

History | View | Annotate | Download (13.4 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
### Key pair setup
17

    
18
First of all, we assume that the user has a
19
valid [iMinds Authority account](https://authority.ilabt.iminds.be/). We also
20
assume that the user's public and private keys associated with the iMinds
21
Authority account are located in ~/.ssh/twist.pub and ~/.ssh/twist.key
22
respectively (the private key MUST NOT be encrypted).
23
If you don't have the keys already setup, you can follow these instructions:
24

    
25
Go to [iMinds Authority account management](https://authority.ilabt.iminds.be/getcert.php) and download your certificate
26
clicking on the "Download Login Cerificate" button. Save it with the name `twist.cert`.
27
Extract the public key with the following command:
28

    
29
`openssl x509 -pubkey -noout -in twist.cert > ~/.ssh/twist.pub`
30

    
31
Edit the`twist.cert` file and copy the private key part in a new file named `twist.protected.key`.
32

    
33
Remove the password from the private key:
34

    
35
`openssl rsa -in twist.protected.key -out ~/.ssh/twist.key`
36

    
37
## Omni tool
38

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

    
44
### Omni software dependencies
45

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

    
52
```
53
sudo apt install python-m2crypto python-dateutil python-openssl libxmlsec1 
54
    xmlsec1 libxmlsec1-openssl libxmlsec1-dev autoconf
55
```
56

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

    
60
### Omni installation
61

    
62
In order to install `omni` execute the following commands:
63

    
64
```
65
cd $HOME/src &&
66
git clone https://github.com/GENI-NSF/geni-tools omni &&
67
cd omni &&
68
./autogen.sh &&
69
./configure &&
70
make &&
71
make install 
72
```
73

    
74
If you are using Python version 3 and you don't want to switch system-wide to
75
Python 2, edit the first line of the `omni` source file and change it to
76
```
77
#!/usr/bin/env python2
78
```
79

    
80
Verify that `omni` has been installed correctly by executing `omni --version`.
81
This command should print something that resembles the following:
82

    
83
```
84
omni: GENI Omni Command Line Aggregate Manager Tool Version 2.11
85
Copyright (c) 2011-2016 Raytheon BBN Technologies
86
```
87

    
88
### Omni configuration file
89

    
90
The `omni_config` file provided in this repository is a template of the `omni`
91
configuration file. Before running any other `omni` command, this template file
92
must be modified in order to adapt it to the local host environment.
93

    
94

    
95
The users whose public keys will be installed on the testbed's nodes are listed
96
(comma separated list) in the value of the `users` key in the `omni` section.
97
For each user listed in the `users` key, there is a corresponding section (named
98
after the user name) containing the specific configuration for that particular
99
user. For example, in the current template configuration file one of the user
100
is `segata`, and the corresponding configuration section looks like this:
101

    
102
```
103
[segata]
104
urn = urn:publicid:IDN+wall2.ilabt.iminds.be+user+segata
105
keys = ~/.ssh/twist.pub
106
```
107

    
108
The value of the field `keys` must be modified to point to the public key of the
109
user `segata`.
110

    
111
In case you need to add a new user, these are the required steps:
112
1. append the new user name in the comma separated list of the `users` key in
113
   the `omni` section.
114
2. add to the `omni_config` file a new section for the new user.
115
3. commit and push the new `omni_config` template.
116

    
117
## RSPEC generation
118

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

    
124
* `-t` (`--testbed`): specifies which testbed the RSPEC will be generated for.
125
  Use `twist` for the TWIST testbed, `wilab` for w.iLab1, `wall1` for
126
  VirtualWall1, and `wall2` for VirtualWall2. It is possible to specify a
127
  comma-separated list of testbeds, e.g. `wall1,wall2`.
128

    
129
* `-f` (`--filter`): comma separated list of node name prefixes. Only the
130
  available nodes whose name starts with one of the specified prefixes are
131
  inserted in the generated RSPEC. By default all the available nodes are
132
  used for generating the RSPEC file.
133

    
134
* `-n` (`--nodes`): comma separated list of node names. Only the available nodes
135
  whose name is listed with the `-n` option are inserted in the RSPEC file. By
136
  default all the available nodes are used. The `-n` option takes precedence
137
  over `-f`.
138

    
139
* `-w` (`--hardware`): comma separated list of hardware types (e.g.,
140
  `pcgen05`). To know the type of hardware, look inside the [Virtual Walls
141
  webpage](https://doc.ilabt.imec.be/ilabt/virtualwall/hardware.html) or
142
  inside jFed.
143

    
144
For example, an RSPEC containing all the available nodes in the TWIST testbed
145
can be generated with the following command:
146

    
147
```
148
./gen-rspec.py -t twist > twist_all.rspec
149
```
150

    
151
Instead, an RSPEC containing all the nuc nodes in the TWIST testbed can be
152
generated with the following command:
153

    
154
```
155
./gen-rspec.py -t twist -f nuc > twist_nuc.rspec
156
```
157

    
158
An RSPEC containing only nuc4 and nuc6 from the TWIST testbed can be
159
generated with the following command:
160

    
161
```
162
./gen-rspec.py -t twist -n nuc4,nuc6 > twist_nuc_4_6.rspec
163
```
164

    
165
An RSPEC containing nodes of hardware type `pcgen05` from both the
166
VirtualWall1 and the VirtualWall2 testbeds can be generated with the following
167
command:
168

    
169
```
170
./gen-rspec.py -t wall1,wall2 -w pcgen05 > iof.rspec
171
```
172

    
173
Note that, in any case, a node is inserted in the RSPEC only if it is available
174
in the moment the `gen-rspec.py` command is executed. For this reason the
175
suggested best practice is to execute `gen-rspec.py` just before allocating the
176
resources using the `reserve.py` command.
177

    
178
## Reserving resources
179

    
180
One simple way of reserving the resource is to open the generated `.rspec`
181
file inside jFed and click on `Run`. This is also the safest option as the
182
`reserve.py` script is still under development.
183

    
184
The `reserve.py` command can be used to allocate nodes specified in an `.rspec`
185
file and to release resources previously allocated. The command supports the
186
following parameters:
187

    
188
* `-t` (`--testbed`): specifies in which testbed to allocate the nodes. The
189
  testbed specified here must match the testbed used in the .rspec file
190
  specified with the parameter `-f`. Use twist for the TWIST testbed and wilab
191
  for w.iLab1;
192

    
193
* `-d` (`--duration`): it's an integer value that specifies how many hours the
194
  nodes will be reserved for. The minimum value currently supported is 3.
195

    
196
* `-s` (`--name`): specifies the name that identify the experiment. Every
197
  experiment whose allocation time overlaps must have a unique name.
198

    
199
* `-f` (`--rspec`): specifies the path to the .rspec file generated with the
200
  `gen-rspec.py` command.
201

    
202
* `-p` (`--project`): specifies the project the experiments belongs to (by
203
default `internetonfire`).
204

    
205
By default `reserve.py` allocate the resources specified in the .rspec file. The
206
same command can be used also to release previously allocated resources using
207
the `-r` (`--release`) parameter.
208

    
209
For example, an experiment called `iofexp1` that allocates in the Wall1
210
testbed the nodes specified in the file `iof.rspec` for 4 hours can be
211
created with the following command:
212

    
213
```
214
./reserve.py -t wall1 -d 4 -n iofexp1 -f iof.rspec
215
```
216

    
217
Instead, the resources allocated in `iofexp1` can be released with the
218
following command:
219

    
220
```
221
./reserve.py -t wall1 -d 4 -n iofexp1 -f iof.rspec -r
222
```
223

    
224
The command queries for the status of the testbed every 10 seconds, and reports
225
when everything is up and running.
226

    
227
**WARNING:** the `reserve.py` script currently works only when a single
228
testbed is involved. In case of an `.rspec` files with nodes from multiple
229
testbeds, the operations needs to be performed twice. This is under development.
230

    
231
## Generating SSH and Ansible config
232

    
233
After generating the `rspec` file, the `gen-config.py` script can generate
234
the SSH and the ansible configuration files to access the nodes of the
235
testbeds. To do so, simply run:
236

    
237
```
238
./gen-config.py -r <rspec files> -u <username> -k <identity file>
239
```
240

    
241
The identity file is the private key or the certificate obtained after getting
242
an account from the [iMinds authority](https://authority.ilabt.iminds.be/).
243
This file will be copied under the current directory with the name `id.cert`. The 
244
username is your username on the Testbed.
245

    
246
The script will generate:
247
* `ssh-config`: the configuration file to be given to the SSH command (e.g.,
248
  `ssh -F ssh-config ...`). This defines the names of the hosts as `node<i>`,
249
  for `i` going from 0 to N-1. To connect to one host, you can thus run
250
  `ssh -F ssh-config node0`. To connect to the node, the configuration uses a
251
  proxy node with public IP address, which is called `proxy0`.
252
* `ssh-config-no-proxy`: the same configuration file as `ssh-config` but
253
  without the `ProxyCommand` through `proxy0`. This can be used by `ansible`
254
  when run on a testbed node.
255
* `ansible.cfg`: the Ansible configuration file.
256
* `ansible-hosts`: the Ansible inventory (list of nodes). In this file the
257
  group of nodes reserved for the experiments is named `nodes`. To test that
258
  this is properly working, try with `ansible nodes -m shell -a "uptime"`.
259

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

    
263
## Setting up the testing environment on the nodes
264

    
265
The process of setting up the testing environment on the nodes is composed by two steps.
266
The first one takes care of installing all the needed software and tweaks some system parameters.
267
```
268
ansible-playbook playbooks/setup-nodes.yaml
269
```
270
from your local machine.
271

    
272
The second step is needed to configure the node0 as the master node for the experiments and
273
will correctly setup the syslog collection system on that node.
274
```
275
ansible-playbook playbooks/setup-syslog.yaml
276
```
277
on your local machine. If you want you can automate the whole procedure executing the `setup-nodes-environment.sh`
278
script.
279

    
280
To test the installation run from your local machine (do so only if you have
281
reserved a few nodes)
282
```
283
ansible nodes -m shell -a "~/iof-bird-daemon/bird --version"
284
```
285
The result should be the version of the bird daemon for each node in the
286
testbed.
287

    
288
## Retrieving CPU and network info
289

    
290
To retrieve CPU and interface information for all the nodes in the testbed run
291
```
292
./get-node-info.sh
293
```
294
This will create a `cpu_info` containing one `json` file
295
for each node in the testbed. The information can be used within python
296
programs using the `nodes_info::NodesInfo` class. See the unit test
297
`test_nodes_info.py` for an example usage.
298

    
299
# Topologies and BGP configurations
300

    
301
This section describes the tools that are used to generate network topologies
302
to test and the corresponding `bird` configuration files.
303

    
304
## Chain gadget topology
305

    
306
This tool generates *chain gadget* topologies as described in the Fabrikant
307
and Rexford paper *There's something about MRAI: Timing diversity can
308
exponentially worsen BGP convergence*. The tool is composed by two files
309
* `chain_gadget.py`: main library that exposes the `gen_chain_gadget` method.
310
* `gen_chain_gadget.py`: script that invokes the `gen_chain_gadget` method of
311
 the library and writes the graph on a `.graphml` output file.
312

    
313
The parameters that both the method accepts as inputs are the following (the
314
parameters of the script have different names, but the same meaning):
315
* `n_rings`: the number of rings to generate in the topology. For example,
316
 the number of rings in Figs. 1 and 3 in the paper is 3. The rings connected
317
 together form the chain.
318
* `n_inner`: the number of inner nodes. Each ring as inner nodes (marked with
319
 `Y_i` in the paper). The topology in Fig. 1 in the paper has only 1 inner
320
 node per ring, while Fig. 3 has 3.
321
* `add_outer`: if set to `true`, the tool will generate outer nodes as well
322
 (nodes marked with `Z_i` in the paper). The topology in Fig. 1 in the paper
323
 has no outer nodes, while Fig. 3 has 4. The number of outer nodes is
324
 automatically derived, and it is simply the number of inner nodes plus 1.
325
* `node_type`: the node type to assign to nodes. This can either be `T`, `M`,
326
 `CP`, or `C`.
327
* `edge_type`: the edge type to assign to edges. This can either be `transit` or
328
 `peer`. By default this is set to `transit`.
329
* `set_timer`: if set to `true`, the tool will compute the `MRAI` timer for
330
 the nodes, so that the automatic BGP configuration tool can use them during
331
 the generation phase. The timer is assigned with an exponentially decreasing
332
 value, starting with the default of `30 s`. The left-most ring (according to
333
 the graphical description of the topology in the paper) has the highest
334
 timer. Each ring's timer is halved with respect to the one of its left ring.
335

    
336
## AS graph generator
337

    
338
 This [tool](https://github.com/lucabaldesi/AS_graph_generator) generates graphs
339
resembling the Internet BGP speaker topology.
340

    
341
Generation is as easy as typing:
342

    
343
'''
344
./generate.py <number_of_nodes> <number_of_graphs>
345
'''