| 69 | |
| 70 | == Sliver approval workflow == |
| 71 | |
| 72 | This section describes our workflow for approving slivers at BBN. |
| 73 | |
| 74 | FOAM sends e-mail about new slivers to the FOAM admin e-mail address that you configured when you set up FOAM. If further communication about a sliver request is needed, we copy that address on the e-mail, so that everyone will see it. We also send mail to to that address when we approve or reject the sliver (or if we review the request and we're not sure whether to approve or reject it), so everyone knows who did it. |
| 75 | |
| 76 | Using the commands below, decide whether to approve it: |
| 77 | |
| 78 | * Get a list of pending slivers, and look for the new sliver in that list. |
| 79 | * Get the sliver URN from the slicename. |
| 80 | * Show the sliver's basic info, to confirm that we've got the right sliver URN: |
| 81 | * Verify that the email field is valid, so that we and FOAM can contact the experimenter later about the sliver. |
| 82 | * Show the sliver's rspec, to confirm that it matches the owner's description of what they're asking for: |
| 83 | * Public information about common requests is on [ggw:GeniAggregate/GpoLabOpenFlow the GPO Lab OpenFlow aggregate info page]. |
| 84 | * For more complicated requests: |
| 85 | * Look up the DPID in our inventory and find out what switch/VLAN it is. |
| 86 | * Look up the hosts the experimenter asked for in our inventory, and make sure the ports the experimenter requested make sense. |
| 87 | * Show the sliver's flowspace, and confirm that it matches the rspec, and doesn't contain anything dangerous, such as: |
| 88 | * Look for flowspace rules that match '''any''' packet -- the third field in each rule -- as these might indicate a subtle error in the rspec. |
| 89 | * Check to make sure the rspec and flowspace don't include multiple cross-connects, unless the experimenter has convinced us that they understand the risks and will be careful. |
| 90 | * Check to make sure the rspec and flowspace don't include I2 plnodes (ganel, gardil, sardis) and NLR VLANs/cross-connects, or NLR plnodes (bain, navis) and I2 VLANs/cross-connects. |
| 91 | |
| 92 | If we conclude that the sliver is ok, approve it: |
| 93 | |
| 94 | {{{ |
| 95 | foamctl approve-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 96 | }}} |
| 97 | |
| 98 | If we conclude that we should definitely not approve the sliver, reject it: |
| 99 | |
| 100 | {{{ |
| 101 | foamctl reject-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 102 | }}} |
| 103 | |
| 104 | If we're not sure, do nothing, which will leave the sliver as Pending while we get more information. |
| 105 | |
| 106 | Regardless, send e-mail to the admin address saying what we did, so everyone's in the loop. (One convenient way is to reply to the notification message about the sliver.) |
| 107 | |
| 108 | == Managing FOAM slivers == |
| 109 | |
| 110 | https://openflow.stanford.edu/display/FOAM/foamctl+Guide is the official guide to foamctl, and describes in detail everything that it can do. Here are some specific commands that we've found useful for performing common tasks. |
| 111 | |
| 112 | These commands all assume that you're running them on the FOAM server, and that you have a file /opt/foam/etc/foampasswd, containing the FOAM admin password. |
| 113 | |
| 114 | === Get a list of slivers === |
| 115 | |
| 116 | Pending ones: |
| 117 | |
| 118 | {{{ |
| 119 | foamctl list-slivers -s Pending --passwd-file=/opt/foam/etc/foampasswd |
| 120 | }}} |
| 121 | |
| 122 | All active ones: |
| 123 | |
| 124 | {{{ |
| 125 | foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd |
| 126 | }}} |
| 127 | |
| 128 | Either of these will give you a sliver URN; if you do |
| 129 | |
| 130 | {{{ |
| 131 | sliver_urn=urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+jbsstghosts:678fc69b-76e1-4a50-9fb2-ab5c4a5298d6 |
| 132 | }}} |
| 133 | |
| 134 | (with the actual URN of course), the rest of these commands will then work as-is. |
| 135 | |
| 136 | Deleted ones: |
| 137 | |
| 138 | {{{ |
| 139 | foamctl list-slivers -d --passwd-file=/opt/foam/etc/foampasswd |
| 140 | }}} |
| 141 | |
| 142 | === Find a sliver from a slice name === |
| 143 | |
| 144 | If you know a user's slice name, you can grep for it: |
| 145 | |
| 146 | {{{ |
| 147 | foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd | egrep sliver_urn.+exampleslice |
| 148 | }}} |
| 149 | |
| 150 | You can use this to get a sliver URN and/or an FV slice name from a GENI slice name, assigned to $sliver_urn and $flowvisor_slice: |
| 151 | |
| 152 | {{{ |
| 153 | slicename=exampleslice ; sliver_urn=$(foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd | egrep sliver_urn.+$slicename | sed -e 's/ *"sliver_urn": "\(.*\)".*/\1/') ; flowvisor_slice=$(echo $sliver_urn | awk -F : '{print $NF}') |
| 154 | }}} |
| 155 | |
| 156 | The rest of these commands assume that you've used that (or something similar) to set $sliver_urn. |
| 157 | |
| 158 | === Show a sliver's basic info === |
| 159 | |
| 160 | {{{ |
| 161 | foamctl show-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 162 | }}} |
| 163 | |
| 164 | === Show a sliver's rspec === |
| 165 | |
| 166 | {{{ |
| 167 | foamctl show-sliver -r -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 168 | }}} |
| 169 | |
| 170 | === Show a sliver's flowspec === |
| 171 | |
| 172 | {{{ |
| 173 | foamctl show-sliver -s -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 174 | }}} |
| 175 | |
| 176 | === Show a sliver's flowspace === |
| 177 | |
| 178 | {{{ |
| 179 | foamctl show-sliver -f -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 180 | }}} |
| 181 | |
| 182 | === Approve a sliver === |
| 183 | |
| 184 | This marks a sliver in FOAM as Approved, and adds a FV slice and flowspace rules for it to the !FlowVisor. |
| 185 | |
| 186 | {{{ |
| 187 | foamctl approve-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 188 | }}} |
| 189 | |
| 190 | === Disable a sliver === |
| 191 | |
| 192 | This marks a sliver in FOAM as Pending, and removes a FV slice and flowspace rules for it from the !FlowVisor. |
| 193 | |
| 194 | {{{ |
| 195 | foamctl disable-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 196 | }}} |
| 197 | |
| 198 | === Reject a sliver === |
| 199 | |
| 200 | This marks a sliver in FOAM as Rejected, and removes a FV slice and flowspace rules for it from the !FlowVisor. |
| 201 | |
| 202 | {{{ |
| 203 | foamctl reject-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 204 | }}} |
| 205 | |
| 206 | === Delete a sliver === |
| 207 | |
| 208 | This disables a sliver, and marks it as deleted, just like the GENI AM API !DeleteSliver call. |
| 209 | |
| 210 | {{{ |
| 211 | foamctl delete-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
| 212 | }}} |
| 213 | |
| 214 | You should generally only do this with the experimenter's permission, and if the experimenter can't delete their own sliver for some reason, so they're not confused about where their sliver went. (If you disable or reject it, they can still see it; if you delete it, it's essentially gone forever from their point of view.) |
| 215 | |
| 216 | == Slice Authority trust configuration == |
| 217 | |
| 218 | You may want to configure FOAM to trust user certificates signed by additional Slice Authorities. To do that, install the CA cert for the Slice Authority in a file in /opt/foam/etc/gcf-ca-certs, and then rebuild the nginx CA cert bundle and restart FOAM and nginx: |
| 219 | |
| 220 | {{{ |
| 221 | sudo foamctl bundle-certs |
| 222 | sudo service foam restart |
| 223 | sudo service nginx restart |
| 224 | }}} |
| 225 | |
| 226 | In particular, GENI mesoscale deployments should trust the pgeni.gpolab.bbn.com SA; the official FOAM installation guide includes this step, or you can get the cert from http://www.pgeni.gpolab.bbn.com/ca-cert/pgeni.gpolab.bbn.com.pem if you need it. |
117 | | |
118 | | == Managing FOAM slivers == |
119 | | |
120 | | https://openflow.stanford.edu/display/FOAM/foamctl+Guide is the official guide to foamctl, and describes in detail everything that it can do. Here are some specific commands that we've found useful for performing common tasks. |
121 | | |
122 | | These commands all assume that you're running them on the FOAM server, and that you have a file /opt/foam/etc/foampasswd, containing the FOAM admin password. |
123 | | |
124 | | === Get a list of slivers === |
125 | | |
126 | | Pending ones: |
127 | | |
128 | | {{{ |
129 | | foamctl list-slivers -s Pending --passwd-file=/opt/foam/etc/foampasswd |
130 | | }}} |
131 | | |
132 | | All active ones: |
133 | | |
134 | | {{{ |
135 | | foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd |
136 | | }}} |
137 | | |
138 | | Either of these will give you a sliver URN; if you do |
139 | | |
140 | | {{{ |
141 | | sliver_urn=urn:publicid:IDN+pgeni.gpolab.bbn.com+slice+jbsstghosts:678fc69b-76e1-4a50-9fb2-ab5c4a5298d6 |
142 | | }}} |
143 | | |
144 | | (with the actual URN of course), the rest of these commands will then work as-is. |
145 | | |
146 | | Deleted ones: |
147 | | |
148 | | {{{ |
149 | | foamctl list-slivers -d --passwd-file=/opt/foam/etc/foampasswd |
150 | | }}} |
151 | | |
152 | | === Find a sliver from a slice name === |
153 | | |
154 | | If you know a user's slice name, you can grep for it: |
155 | | |
156 | | {{{ |
157 | | foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd | egrep sliver_urn.+exampleslice |
158 | | }}} |
159 | | |
160 | | You can use this to get a sliver URN and/or an FV slice name from a GENI slice name, assigned to $sliver_urn and $flowvisor_slice: |
161 | | |
162 | | {{{ |
163 | | slicename=exampleslice ; sliver_urn=$(foamctl list-slivers --passwd-file=/opt/foam/etc/foampasswd | egrep sliver_urn.+$slicename | sed -e 's/ *"sliver_urn": "\(.*\)".*/\1/') ; flowvisor_slice=$(echo $sliver_urn | awk -F : '{print $NF}') |
164 | | }}} |
165 | | |
166 | | The rest of these commands assume that you've used that (or something similar) to set $sliver_urn. |
167 | | |
168 | | === Show a sliver's basic info === |
169 | | |
170 | | {{{ |
171 | | foamctl show-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
172 | | }}} |
173 | | |
174 | | === Show a sliver's rspec === |
175 | | |
176 | | {{{ |
177 | | foamctl show-sliver -r -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
178 | | }}} |
179 | | |
180 | | === Show a sliver's flowspec === |
181 | | |
182 | | {{{ |
183 | | foamctl show-sliver -s -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
184 | | }}} |
185 | | |
186 | | === Show a sliver's flowspace === |
187 | | |
188 | | {{{ |
189 | | foamctl show-sliver -f -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
190 | | }}} |
191 | | |
192 | | === Approve a sliver === |
193 | | |
194 | | This marks a sliver in FOAM as Approved, and adds a FV slice and flowspace rules for it to the !FlowVisor. |
195 | | |
196 | | {{{ |
197 | | foamctl approve-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
198 | | }}} |
199 | | |
200 | | === Disable a sliver === |
201 | | |
202 | | This marks a sliver in FOAM as Pending, and removes a FV slice and flowspace rules for it from the !FlowVisor. |
203 | | |
204 | | {{{ |
205 | | foamctl disable-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
206 | | }}} |
207 | | |
208 | | === Reject a sliver === |
209 | | |
210 | | This marks a sliver in FOAM as Rejected, and removes a FV slice and flowspace rules for it from the !FlowVisor. |
211 | | |
212 | | {{{ |
213 | | foamctl reject-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
214 | | }}} |
215 | | |
216 | | === Delete a sliver === |
217 | | |
218 | | This disables a sliver, and marks it as deleted, just like the GENI AM API !DeleteSliver call. |
219 | | |
220 | | {{{ |
221 | | foamctl delete-sliver -u $sliver_urn --passwd-file=/opt/foam/etc/foampasswd |
222 | | }}} |
223 | | |
224 | | You should generally only do this with the experimenter's permission, and if the experimenter can't delete their own sliver for some reason, so they're not confused about where their sliver went. (If you disable or reject it, they can still see it; if you delete it, it's essentially gone forever from their point of view.) |