README 4.28 KB
Newer Older
Leigh B. Stoller's avatar
Leigh B. Stoller committed
1
2
3
4
tbsetup README

----------------------------------------------------------------------
tbprerun
5
6

Syntax:
Leigh B. Stoller's avatar
Leigh B. Stoller committed
7
	tbprerun [-nologfile] <pid> <eid> <ns-file>
8

Leigh B. Stoller's avatar
Leigh B. Stoller committed
9
10
11
tbprerun takes a brand new experiment, checks the syntax of the
ns-file, and then converts the ns-file into a virtual topology stored
in the database. 
12

Leigh B. Stoller's avatar
Leigh B. Stoller committed
13
-nologfile - Prevents creation of a logfile.
Christopher Alfeld's avatar
Christopher Alfeld committed
14

Leigh B. Stoller's avatar
Leigh B. Stoller committed
15
----------------------------------------------------------------------
16

Leigh B. Stoller's avatar
Leigh B. Stoller committed
17
tbswapin
18
19

Syntax:
Leigh B. Stoller's avatar
Leigh B. Stoller committed
20
	tbswapin [-nologfile] <pid> <eid>
21

Leigh B. Stoller's avatar
Leigh B. Stoller committed
22
23
24
25
tbswapin swaps an experiment in.  Specifically it finds and allocates
a set of resources and configures these resources to emulate the
desired experiment.  As a part of this it configures the physical
state in the DB.
26

Leigh B. Stoller's avatar
Leigh B. Stoller committed
27
-nologfile - Prevents creation/appending of a logfile.
28

Leigh B. Stoller's avatar
Leigh B. Stoller committed
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
Exit Codes:

tbswapin exits with a variety of codes to represent different error
conditions.  Almost all of these codes are actually generated by
assign_wrapper and just passed through by tbswapin.

Exit 0 : All good
2: Insufficient resources.
X: other errors
1+
        4 - Bandwidth violation
        8 - Linkusers violation  
        16 - Desires violation.  

I.e.

1 - Unspecified error
5 - Bandwidth error 
9 - Linkusers error
17 - Desires error. 
13 - Bandwidth and linkusers error.
21 - Bandwidth and desires error.
25 - Linkusers and desires error.
29 - Bandwidth, linkusers, and desires.

----------------------------------------------------------------------

tbswapout
57
58

Syntax:
Leigh B. Stoller's avatar
Leigh B. Stoller committed
59
	tbswapout [-nologfile] [-force] <pid> <eid>
60

Leigh B. Stoller's avatar
Leigh B. Stoller committed
61
62
63
64
tbswapout is the inverse of tbswapin.  It tears down the physical
state on the testbed, freeing the resources for other use.  It clears
the physical state from the DB but leaves the virtual state intact.  I.e.
it reverse tbswapin but not tbprerun.
Christopher Alfeld's avatar
Christopher Alfeld committed
65

Leigh B. Stoller's avatar
Leigh B. Stoller committed
66
67
68
69
-nologfile - Prevents creation/appending of a logfile.
-force - Does not check current experiment state.

----------------------------------------------------------------------
Christopher Alfeld's avatar
Christopher Alfeld committed
70
71
72
73

tbend

Syntax:
Leigh B. Stoller's avatar
Leigh B. Stoller committed
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
	tbend [-nologfile] [-force] <pid> <eid>

tbend is the inverse of tbprerun.  It clears the virtual state from
the DB and marks the experiment as ended.

-nologfile - Prevents creation/appending of a logfile.
-force - Does not check current experiment state.

----------------------------------------------------------------------

tbreport

Syntax:
	tbreport [-v] <pid> <eid>

tbreport displays the current state of an experiment.  It displays
both the virtual topology, and, if the experiment is currently
running, the physical mapping.

-v - Display extra information.

----------------------------------------------------------------------

Basic Operation

The basic operation of the tbsetup tools is:

1. tbprerun
2. tbswapin
3. do experiment
4. tbswapout
5. Repeat steps 2-4 as necessary.
6. tbend

It is assumed that an experiment is already entered in the DB before
tbprerun is called.  Likewise, tbend does not remove the entry.

----------------------------------------------------------------------

Experimental States

The experiment goes through the following states:

new - Before tbprerun. tbprerun requires the experiment to be in this
state before running.

prerunning - During tbprerun.

swapped - After tbprerun or tbswapout.  tbswapin requires the
experiment to be in this state before running.  tbend requires this
state unless -force is used.

activating - During tbswapin.

active - After tbswapin.  tbswapout requires this state unless -force
is used.

swapping - During tbswapout.

terminating - During tbend.

ended - After tbend.

----------------------------------------------------------------------

Non-symmetries

In general tbprerun and tbend are inverse operations and tbswapin and
tbswapout are inverse operations.  This is not completely true,
however.  tbswapout does completely reverse tbswapin, and tbend clears
some state that is set in tbswapin, rather than tbprerun.

Node state: For performance reasons tbswapout does not touch node
state.  The idea being that node state only matters for active
experiments and these experiments will reconfigure the node state when
they are swapped in.

Portmap: The portmap table in the DB is not cleared by tbswapout.
This is because the portmap table will be used the next time tbswapin
is called to try to match the portmapping of the previous swap.  The
purpose behind this is to preserve the same port mapping across swaps.
The portmap table is cleared in tbend instead.

Christopher Alfeld's avatar
Christopher Alfeld committed
157