| 1 | = '''!NetServ tutorial: step-by-step instruction''' = |
| 2 | |
| 3 | == Preparation == |
| 4 | |
| 5 | 1. Start the provided VM and login as the "GENI User". |
| 6 | |
| 7 | 2. Open Firefox and point it to the following URL: |
| 8 | |
| 9 | [http://pc519.emulab.net/visual/index.html?id=50] |
| 10 | |
| 11 | ''Please note that you must replace "'''50'''" with your own user number throughout this tutorial.'' |
| 12 | |
| 13 | 3. You will see the traffic visualization in your browser as follows: |
| 14 | |
| 15 | [[Image(traffic.jpg, 300px)]] |
| 16 | |
| 17 | == Install !NetServ module == |
| 18 | |
| 19 | 1. Open a terminal window, update !NetServ software, and go to your !NetServ user directory. |
| 20 | |
| 21 | {{{ |
| 22 | cd /netserv-root |
| 23 | svn up |
| 24 | |
| 25 | cd tutorial/user50 |
| 26 | ls -l |
| 27 | }}} |
| 28 | |
| 29 | 2. The following files have been prepared for each user: |
| 30 | |
| 31 | {{{ |
| 32 | Makefile |
| 33 | NetServ/Example.java |
| 34 | example.mf |
| 35 | |
| 36 | upload.sh |
| 37 | setup.sh |
| 38 | remove.sh |
| 39 | |
| 40 | setup-request-1.txt |
| 41 | setup-request-2.txt |
| 42 | setup-request-3.txt |
| 43 | remove-request.txt |
| 44 | |
| 45 | request-signer |
| 46 | private-key-50.pem |
| 47 | public-key-50.pem |
| 48 | }}} |
| 49 | |
| 50 | 3. Build the Example module and upload it to the !NetServ repository. |
| 51 | |
| 52 | {{{ |
| 53 | make |
| 54 | ./upload.sh |
| 55 | }}} |
| 56 | |
| 57 | 4. Send a SETUP message to the !NetServ router to install the module. |
| 58 | |
| 59 | While you are watching the browser window type the following command into the terminal window. |
| 60 | |
| 61 | {{{ |
| 62 | ./setup.sh 1 |
| 63 | }}} |
| 64 | |
| 65 | The traffic will be redirected to D2 (the node on the lower right) and !NetServ.Example will be added to the list of !NetServ modules currently installed. |
| 66 | |
| 67 | 5. The SETUP message looks like this: |
| 68 | |
| 69 | {{{ |
| 70 | $ cat setup-request-1.txt |
| 71 | SETUP NetServ.Example_1.0.0 NETSERV/0.1 |
| 72 | url: http://pc487.emulab.net/modules/user50/example.jar |
| 73 | user: user50 |
| 74 | ttl: 600 |
| 75 | filter-ipv4: 10.10.2.2 |
| 76 | filter-proto: udp |
| 77 | filter-port: 20050 |
| 78 | properties: debug = false, ip = 10.10.3.2 |
| 79 | |
| 80 | }}} |
| 81 | |
| 82 | 6. Send a REMOVE message to the !NetServ router to remove the module. |
| 83 | |
| 84 | {{{ |
| 85 | ./remove.sh |
| 86 | }}} |
| 87 | |
| 88 | 7. The REMOVE message looks like this: |
| 89 | |
| 90 | {{{ |
| 91 | $ cat remove-request.txt |
| 92 | REMOVE NetServ.Example_1.0.0 NETSERV/0.1 |
| 93 | user: user50 |
| 94 | |
| 95 | }}} |
| 96 | |
| 97 | == Develop !NetServ module == |
| 98 | |
| 99 | 1. Open {{{Example.java}}} with gedit or your favorite editor. |
| 100 | |
| 101 | {{{ |
| 102 | gedit NetServ/Example.java & |
| 103 | }}} |
| 104 | |
| 105 | {{{Example.java}}} is a typical !NetServ packet processing module and it extends the !NetServ.!BuildingBlock.service.!PktProcessorActivator class. |
| 106 | |
| 107 | 2. Modify {{{Example.java}}}. |
| 108 | |
| 109 | Comment out processPkt() marked as scenario !#1, and uncomment processPkt() scenario !#2. |
| 110 | |
| 111 | 3. Compile and upload the new version of the module. |
| 112 | |
| 113 | {{{ |
| 114 | make |
| 115 | ./upload.sh |
| 116 | }}} |
| 117 | |
| 118 | 4. While you're watching the browser screen, install the module into the !NetServ router with the following command. |
| 119 | |
| 120 | {{{ |
| 121 | ./setup.sh 2 |
| 122 | }}} |
| 123 | |
| 124 | Note that the "2" argument will make the script send {{{setup-request-2.txt}}}, which includes two IP addresses in the properties header. |
| 125 | |
| 126 | {{{ |
| 127 | $ cat setup-request-2.txt |
| 128 | SETUP NetServ.Example_1.0.0 NETSERV/0.1 |
| 129 | url: http://pc487.emulab.net/modules/user50/example.jar |
| 130 | user: user50 |
| 131 | ttl: 600 |
| 132 | filter-ipv4: 10.10.2.2 |
| 133 | filter-proto: udp |
| 134 | filter-port: 20050 |
| 135 | properties: debug = false, ip = 10.10.2.2 10.10.3.2 |
| 136 | |
| 137 | }}} |
| 138 | |
| 139 | 5. Update the module properties by sending another SETUP message. |
| 140 | |
| 141 | By sending a SETUP message for a module that is already installed, you can update its properties and refresh its TTL. |
| 142 | |
| 143 | Try sending {{{setup-request-3.txt}}} to the !NetServ router: |
| 144 | |
| 145 | {{{ |
| 146 | ./setup.sh 3 |
| 147 | }}} |
| 148 | |
| 149 | This SETUP request contains a non-existing IP address as the packet destination, which will make the !NetServ node drop the incoming packets. |
| 150 | |
| 151 | == (Optional) Run !NetServ node locally == |
| 152 | |
| 153 | 1. Open another terminal window and start the !NetServ router. |
| 154 | |
| 155 | Type the "GENI User" password when asked. |
| 156 | |
| 157 | {{{ |
| 158 | cd /netserv-root/core/linux/ |
| 159 | sudo su |
| 160 | . setenv-i386-ubuntu |
| 161 | ./run-controller.sh conf-default.xml |
| 162 | }}} |
| 163 | |
| 164 | The {{{conf-default.xml}}} file specifies a sample configuration for a single container. |
| 165 | |
| 166 | 2. Open two more terminal windows (they don't have to be big). |
| 167 | |
| 168 | On one window, start Netcat in server mode, listening on UDP port 22222: |
| 169 | |
| 170 | {{{ |
| 171 | nc -u -l 22222 |
| 172 | }}} |
| 173 | |
| 174 | On the other window, start Netcat in client mode, connecting to the UDP port 22222 on the localhost: |
| 175 | |
| 176 | {{{ |
| 177 | nc -u 127.0.0.1 22222 |
| 178 | }}} |
| 179 | |
| 180 | Test the chat-like connection by typing something in the Netcat client window. You should see the same characters appear on the server window. |
| 181 | |
| 182 | 3. Open another terminal window and build the UDPEcho module. |
| 183 | |
| 184 | {{{ |
| 185 | cd /netserv-root/apps/udpecho/modules |
| 186 | make |
| 187 | }}} |
| 188 | |
| 189 | 4. Install the UDPEcho module into the local !NetServ router. |
| 190 | |
| 191 | {{{ |
| 192 | cd test |
| 193 | ./setup.sh |
| 194 | }}} |
| 195 | |
| 196 | You can switch to the !NetServ router window and see the log output of the installation process. |
| 197 | |
| 198 | 5. See UDPEcho in action! |
| 199 | |
| 200 | Type something in the Netcat client window and see what happens. |
| 201 | See also the debugging output from the UDPEcho module in the !NetServ router window. |
| 202 | |
| 203 | 6. Remove the UDPEcho module. |
| 204 | |
| 205 | {{{ |
| 206 | ./remove.sh |
| 207 | }}} |
| 208 | |
| 209 | Type something again in the Netcat client window and see what happens. |
| 210 | |
| 211 | == Please take a quick survey == |
| 212 | |
| 213 | A ''very'' quick survey. :-) |
| 214 | |
| 215 | [https://spreadsheets.google.com/spreadsheet/viewform?formkey=dGxxWFA1ckwxdWxaYlR5M3NvdjA2REE6MQ] |
| 216 | |
| 217 | == Further information == |
| 218 | |
| 219 | !NetServ home page: |
| 220 | |
| 221 | [http://www.cs.columbia.edu/irt/project/netserv/] |
| 222 | |
| 223 | Mailing list: |
| 224 | |
| 225 | [https://lists.cs.columbia.edu/cucslists/listinfo/netserv-users] |
| 226 | |
| 227 | Feedback or questions: |
| 228 | |
| 229 | Jae Woo Lee <jae@cs.columbia.edu> |
| 230 | |
| 231 | Roberto Francescangeli <francescangeli@diei.unipg.it> |
| 232 | |