Commit 924a3907 authored by Mike Hibler's avatar Mike Hibler

Better document the options for setting up IP routing:

 - describe new tb-set-ip-routing command in extensions section
 - move bulk of FAQ text to tutorial and replace with simple answer

Also, added a "Troubleshooting" section to the FAQ.  Only entry currently
is that to do if a link doesn't work.
parent 566075ee
......@@ -72,6 +72,12 @@
<ul>
<li> <a href="#SEC-1">Is Emulab Firewalled?</a>
</ul>
<li> <a href="#TR">Troubleshooting</a>
<ul>
<li> <a href="#TR-1">My experiment is setup, but I cannot
send packets between some of the nodes, why?</a>
</ul>
</ul>
<hr>
......@@ -551,114 +557,23 @@
<h3>How can I turn on routing or set up routes automatically
in my nodes?</h3>
<p>
You can use command mentioned above (<tt>tb-set-node-startup</tt>)
in your NS file to specify a simple script in your home directory
that will do this.
</p>
<h4>Simple Topologies</h4>
<p>
For instance, if I had a node called router,
and wanted to turn on routing in it, I would add this line
to my NS file:
By default, we do not setup any static routes or run any routing daemon
on nodes in an experiment. However, we do provide an option for
those experimentors who do not want to manage routing themselves and
who are using one of our provided FreeBSD or Linux disk images.
Simply adding:
<pre>
tb-set-node-startup $router /users/myname/router-startup
tb-set-ip-routing ospf
</pre>
That would cause router to run my
router-startup script, which should look like this for FreeBSD:
<pre>
#!/bin/sh
sudo sysctl -w net.inet.ip.forwarding=1
sudo sysctl -w net.inet.ip.fastforwarding=1
exit 0
</pre>
Or this, for Linux:
<pre>
#!/bin/sh
sudo sysctl -w net.ipv4.conf.all.forwarding=1
</pre>
That will make sure that routing gets turned on when my router
node boots. Now say I have a client on one side of the router,
and a server on the other side, and I want to establish a route
from the client to the server through the router, and vice
versa. I would add these lines to my NS file:
<pre>
tb-set-node-startup $client /users/myname/clientroutecmd
tb-set-node-startup $server /users/myname/serverroutecmd
</pre>
This will have the client and the server each call a small script
to set up routes. To add a route (on client) to interface 0 of the
server through router, I would run a script called clientroutecmd
that looks like this (for a node running FreeBSD):
<pre>
#!/bin/sh
sudo route add server-0 router
exit 0
</pre>
Or, for Linux:
<pre>
#!/bin/sh
sudo route add server-0 gw router
exit 0
</pre>
Similarly, to add a route (on server) to interface 0 of the client
through router, I would use this serverroutecmd script:
<pre>
#!/bin/sh
sudo route add client-0 router
exit 0
</pre>
That should do it. We now will have a router node that really
routes and forwards packets, and a client and a server that know
how to talk to each other through a gateway router.
to your NS file will enable <code>gated</code> running the OSPF
protocol on all nodes in the experiment.
</p>
<h4>Complex Topologies</h4>
<p>
In complex topologies with multiple routers, each end node will need
a route to the entire experimental network, through its local router.
For FreeBSD, this is done with:
<pre>
#!/bin/sh
sudo route add -net 192.168.0.0 -netmask 255.255.0.0 myrouter
exit 0
</pre>
Or, for Linux,
<pre>
#!/bin/sh
sudo route add -net 192.168.0.0 netmask 255.255.0.0 gw myrouter
exit 0
</pre>
</p>
<p>
You can make a single script that will handle all end nodes, by replacing
"myrouter" in the above commands with "$1", and specifying the router in
your NS file:
<pre>
tb-set-node-startup $clientA {/users/myname/router-startup router0}
tb-set-node-startup $clientB {/users/myname/router-startup router1}
</pre>
</p>
<p>
For multiple routers, the startup script for each router will need to
contain a set of routes for all subnets it is not directly connected
to. This will differ, depending on the topology you are using. To make
this task easier, you can use the <tt>tb-set-ip</tt> command in your NS
file, so that you know which subnets will be assigned to which nodes.
</p>
<p>
Please see the
<a href="tutorial/docwrapper.php3?docname=nscommands.html">Extensions</a>
page for a summary of all Emulab NS extensions, and the
<a href = "tutorial/tutorial.php3">Emulab Tutorial</a> for an
example.
Please see
"Setting up IP routing between nodes"
in the
<a href="tutorial/tutorial.php3">Emulab Tutorial</a>
for more information about IP routing setup options.
</p>
<li><a NAME="SWS-6"></a>
......@@ -719,3 +634,25 @@ tb-set-node-startup $clientB {/users/myname/router-startup router1}
arrangements.
</p>
</ul>
<hr>
<a NAME="TR"></a>
<h3>Troubleshooting</h3>
<ul>
<li><a NAME="TR-1"></a>
<h3>My experiment is setup, but I cannot
send packets between some of the nodes, why?</h3>
<p>
The most common reason is that your topology
includes nodes which are not directly connected, and you have
not setup any routing. Refer to
"<a href="#SWS-5">How can I turn on routing or set up routes
automatically in my nodes?</a>" for details. If you cannot
send packets between two machines which are directly connected
(via a link or a lan), then there are two possibilities:
either the nodes did not properly negotiate their speed and
duplex with the Cisco switch, or the physical wire is loose
or bad. In these cases, you should contact us for help.
</p>
</ul>
......@@ -17,7 +17,8 @@
<li><a href="#TCL">TCL, NS, and node names</a>
<li><a href="#ORDER">Ordering issues</a>
<li><a href="#HARD">Hardware Commands</a>
<li><a href="#IP">IP Commands</a>
<li><a href="#IP">IP Address Commands</a>
<li><a href="#ROUTE">IP Routing Commands</a>
<li><a href="#OS">OS Commands</a>
<li><a href="#LOSS">Link Loss Commands</a>
</ul>
......@@ -151,11 +152,11 @@ tb-set-hardware $node4 shark
<code>pc850</code>, and <code>shark</code> are
supported types. <code>pc</code> is the default type.
<li>No current types have any additional arguments.
</dl>
</ul>
<hr>
<a name="IP"></a><h3>IP Commands</h3>
<a name="IP"></a><h3>IP Address Commands</h3>
<p>Each node will be assigned an IP address for each interface that is
in use. The following commands will allow you to explicitly set those
......@@ -274,6 +275,36 @@ tb-set-ip-interface $node2 $node1 142.3.4.6
either of those commands instead of tb-set-ip-interface.
</ul>
<hr>
<a name="ROUTE"></a><h3>IP Routing Commands</h3>
We currently provide a simple mechanism for setting up default IP routes
between nodes in an experiment.
<h4>tb-set-ip-routing</h4>
<pre>
tb-set-ip-routing <i>protocol</i>.
tb-set-ip-routing none
tb-set-ip-routing ospf
</pre>
<dl>
<dt><i>protocol</i> - The routing protocol to use.
</dl>
<p>Notes:
<ul>
<li><code>none</code> is the default protocol;
i.e., no default routing is setup.
<li><code>ospf</code> is implemented by running <tt>gated</tt>
on all nodes in the experiment.
</ul>
<hr>
<a name="OS"></a><h3>OS Commands</h3>
......@@ -555,5 +586,3 @@ tb-set-node-lan-params $node0 $lan0 40ms 20Mb 0.05
three commands appropriately. See above for more information.
</li>
</ul>
......@@ -33,6 +33,8 @@
How do I know when all my nodes are ready?</a>
<li> <a href="#Delta">
Customizing an OS (How to create a <i>delta</i>)</a>
<li> <a href="#Routing">
Setting up IP routing between nodes</a>
</ul>
<li> <a href="#BatchMode">Batch Mode Experiments</a>
<li> <a href="#CustomOS">Creating your own disk image</a>
......@@ -445,6 +447,7 @@ not work as you expect. Again, please feel free to contact us.
<li> <a href="#Startupcmd">Starting your application automatically</a>
<li> <a href="#ReadyBits">How do I know when all my nodes are ready?</a>
<li> <a href="#Delta">Customizing an OS (How to create a <i>delta</i>)</a>
<li> <a href="#Routing">Setting up IP routing between nodes</a>
</ul>
<p>
......@@ -666,6 +669,179 @@ $ns run </code></pre>
create a complete snapshot of your system.
</ul>
<li> <a NAME="Routing"></a>
<h3>Setting up IP routing between nodes</h3>
<p>
As Emulab strives to make all aspects of the network controllable by the
user, we do not attempt to impose any IP routing architecture or protocol
by default.
However, many users are more interested in end-to-end aspects and don't
want to be bothered with setting up routes. For those users we provide
an option to automatically set up routes on nodes which run one of our
provided FreeBSD or Linux disk images.
<p>
You can use the <tt>tb-set-ip-routing</tt> command in your NS file to
enable automatic routing:
<code><pre>
tb-set-ip-routing <i>protocol</i>
</pre></code>
where <i>protocol</i> is either <code>none</code>, the default for no
automatic routing, or <code>ospf</code> to enable <code>gated</code>
running the OSPF protocol on all nodes in the experiment.
In the future we may add support for automatic pre-computation of static
routes as well as the ability for users to specify per-node routing
information in the NS file.
<p>
If you do want to setup and manage routing yourself, you can use the
<tt>tb-set-node-startup</tt> command in your NS file to specify a
per-node script in your home directory to set up routing at boot time.
You can use this startup script to setup either static routes or to
fire up a routing daemon, as the following examples illustrate.
<p>
The simplest topology requiring routing is one in which two nodes,
<i>client</i> and <i>server</i> are each connected via a single link
to <i>router</i>. In order to get router to correctly forward packets
between client and server, you would add this line to your NS file:
<code><pre>
tb-set-node-startup $router /proj/pid/router-startup
</pre></code>
This will make router run the <code>router-startup</code> script
from you project directory. That script looks like:
<code><pre>
#!/bin/sh
if [ `uname` = "FreeBSD" ]
then
sudo sysctl -w net.inet.ip.forwarding=1
sudo sysctl -w net.inet.ip.fastforwarding=1
else
sudo sysctl -w net.ipv4.conf.all.forwarding=1
fi
exit 0
</pre></code>
These commands ensure that the router node will forward IP packets.
Note the use of <code>sudo</code> which is necessary since startup scripts
run as you and not as root.
Now to get client and server to talk to each other through this router,
you would add these lines to your NS file:
<code><pre>
tb-set-node-startup $client /proj/pid/clientroutecmd
tb-set-node-startup $server /proj/pid/serverroutecmd
</pre></code>
This will have the client and the server each call a small script
to set up routes. To add a route (on client) to interface 0 of the
server through router, you would run a script called
<code>clientroutecmd</code> that looks like this:
<code><pre>
#!/bin/sh
if [ `uname` = "FreeBSD" ]
then
sudo route add server-0 router
else
sudo route add server-0 gw router
fi
exit 0
</pre></code>
Similarly, to add a route (on server) to interface 0 of the client
through router, you would use this <code>serverroutecmd</code> script:
<code><pre>
#!/bin/sh
if [ `uname` = "FreeBSD" ]
then
sudo route add client-0 router
else
sudo route add client-0 gw router
fi
exit 0
</pre></code>
That should do it. You will now have a router node that really
routes and forwards packets, and a client and a server that know
how to talk to each other through a gateway router.
Note that this setup can be generalized to work for any topology
where all nodes are directly connected to a single router node.
However, every node would need a custom script with a route add command
for every other node or you would need to use a subnet route as in
the next example.
<p>
In complex topologies with multiple routers, each end node will need
a route to the entire experimental network, through its local router.
For FreeBSD, this is done with:
<code><pre>
#!/bin/sh
if [ `uname` = "FreeBSD" ]
then
sudo route add -net 192.168.0.0 -netmask 255.255.0.0 myrouter
else
sudo route add -net 192.168.0.0 netmask 255.255.0.0 gw myrouter
fi
exit 0
</pre></code>
You might be tempted to just set the default route for each node to
<code>myrouter</code>, but be aware that such a route would prevent
you from contacting the outside world. The default route <em>must</em>
be set to use the control network interface.
<p>
You can make a single script that will handle all end nodes, by replacing
<code>myrouter</code> in the above commands with <code>$1</code>,
and specifying the router in your NS file:
<code><pre>
tb-set-node-startup $clientA {/proj/pid/router-startup router0}
tb-set-node-startup $clientB {/proj/pid/router-startup router1}
</pre></code>
For multiple routers, the startup script for each router will need to
contain a set of routes for all subnets it is not directly connected
to. This will differ, depending on the topology you are using. To make
this task easier, you can use the <code>tb-set-ip</code> command in your NS
file, so that you know which subnets will be assigned to which nodes.
<p>
If you want to enable dynamic routing,
you can also use the startup script to fire off a routing daemon.
A startup script might look like:
<code><pre>
#!/bin/sh
if [ `uname` = "FreeBSD" ]
then
sudo sysctl -w net.inet.ip.forwarding=1
sudo sysctl -w net.inet.ip.fastforwarding=1
else
sudo sysctl -w net.ipv4.conf.all.forwarding=1
fi
sudo gated -f /proj/pid/gated.conf
exit 0
</pre></code>
One complication of using a routing daemon, is that you need to
avoid using the control network interface in the configuration.
Since every node in the testbed is directly connected to the
control network LAN, a naive routing daemon configuration will
discover that any node is just one hop away via the control
network and <em>all</em> inter-node traffic will be routed via
that interface.
See one of the installed <tt>/etc/testbed/gated*.conf</tt>
files for an example of how to avoid this pitfall.
<!-- This ends the Advanced Tutorial Section -->
</ul>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment