Commit 699ba950 authored by Leigh Stoller's avatar Leigh Stoller

Redo section on setting up routes to reflect recently added manual

routing via NS syntax.
parent 6c2ab00b
......@@ -49,6 +49,7 @@ DOCFILES += $(wildcard $(SRCDIR)/doc/*.php3)
TUTFILES = $(wildcard $(SRCDIR)/tutorial/*.html)
TUTFILES += $(wildcard $(SRCDIR)/tutorial/*.jpg)
TUTFILES += $(wildcard $(SRCDIR)/tutorial/*.gif)
TUTFILES += $(wildcard $(SRCDIR)/tutorial/*.png)
TUTFILES += $(wildcard $(SRCDIR)/tutorial/*.php3)
TUTFILES += $(wildcard $(SRCDIR)/tutorial/*.ns)
TUTFILES += $(SRCDIR)/tutorial/tb_compat.tcl
......
......@@ -616,22 +616,11 @@
in my nodes?</h3>
<p>
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>
$ns rtproto Session
</pre>
to your NS file will enable <code>gated</code> running the OSPF
protocol on all nodes in the experiment.
</p>
<p>
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.
on nodes in an experiment. However, we do provide several options for
experimentors, which are described in the
<a href="tutorial/tutorial.php3#Routing">"Setting up IP routing
between nodes"</a> section of the
<a href="tutorial/tutorial.php3">Emulab Tutorial.</a>
</p>
<li><a NAME="SWS-6"></a>
......
<center>
<h1>Do It Yourself Routing Tutorial</h1>
</center>
If you <em>really</em> want to setup and manage routing entirely by
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. We do not recommend this
approach anymore, but it is there if you need more control over your
routing than we provide. The following examples illustrate this
approach.
<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.
......@@ -712,165 +712,110 @@ automatic routing:
<code><pre>
$ns rtproto <i>protocol</i>
</pre></code>
where <i>protocol</i> is currently limited to <code>Session</code>.
The implementation of <code>Session</code> routing is to enable
<code>gated</code> running the OSPF protocol on all nodes in the
experiment. The default is no automatic routing (or routing of any
kind). 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.
where the <i>protocol</i> option for automated routing is currently
limited to <code>Session</code>. The implementation of
<code>Session</code> routing is to enable <code>gated</code> running
the OSPF protocol on all nodes in the experiment. The default is no
automatic routing (or routing of any kind). 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:
We also support the <tt>Manual</tt> routing option to <tt>rtproto<tt>:
<code><pre>
tb-set-node-startup $router /proj/pid/router-startup
$ns rtproto Manual
</pre></code>
This will make router run the <code>router-startup</code> script
from you project directory. That script looks like:
followed by a list of routes using the <tt>add-route</tt> command:
<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
$node add-route $dst $nexthop
</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:
where the <tt>dst</tt> can be either a node, a link, or a lan. For
eaxmple:
<code><pre>
tb-set-node-startup $client /proj/pid/clientroutecmd
tb-set-node-startup $server /proj/pid/serverroutecmd
$client add-route $server $router
$client add-route [$ns link $server $router] $router
$client add-route $serverlan $router
</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:
You of course need to specify the reverse routes; this allows you to
specify different reverse routes if that is what you wanted to do.
These statements are then converted into appropriate <tt>route(8)</tt>
commands on your experimental nodes when they bootup. In the above
examples, the first form says to set up a manual route between
<tt>$client</tt> and <tt>$server</tt>, using <tt>$router</tt> as the
nexthop; <tt>$client</tt> and <tt>$router</tt> should be directly
connected, and the interface on <tt>$server</tt> should be
unambiguous; either directly connected to the router, or an edge node
that has just a single interface.
<p>
<img src=routing.png align=right>
If the destination has multiple interfaces configured, and it is not
connected directly to the nexthop, the interface that you are
intending to route to is ambiguous; we cannot determine it by
inspection. In the topology shown to the right,
<tt>$nodeD</tt> has two interfaces configured. If you attempted to
set up a route 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
$nodeA add-route $nodeD $nodeB
</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:
you would receive an error since it cannot be determined (easily, with
little programmer effort by Emulab staff!) which of the two links on
<tt>$nodeD</tt> you are referring to. Fortunately, there is an easy
solution (ie: an Emulab "extension"). Instead of a node, specify the
link directly:
<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
$nodeA add-route [$ns link $nodeD $nodeC] $nodeB
</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.
This tells us exactly which link you mean, which enables us to convert
that into a proper <tt>route(8)</tt> command on <tt>$nodeA</tt>.
<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:
The last form of <tt>add-route</tt> command is used when adding a
route to an entire lan. It would be tedious and error prone to specify
a route to each node in a lan by hand. Instead, just route to the
entire network:
<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
set clientlan [$ns make-lan "nodeE nodeF nodeG" 100Mb 0ms]
$nodeA add-route $clientlan $nodeB
</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.
While all this sounds really nifty, its probably a good idea to use
<tt>Session</tt> routing instead. Setting up all the routes in a
moderately sized experiment is terribly error prone. Consider this; a
recently created experiment with 17 nodes required 140 hand created
routes. Yow!
<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.
Another (even less desirable approach) is to manage the routing setup
entirely yourself by using the <tt>tb-set-node-startup</tt> command in
your NS file to specify a per-node script in your home directory to
run at boot time. You can use this startup script to setup either
static routes or to fire up a routing daemon. We do not recommend this
approach anymore, but it is there if you need more control over your
routing than we provide. We have moved the description of this
approach to a <a href="docwrapper.php3?docname=routing.html"> separate
page.</a>
<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 -->
A few cautionary notes:
<ul>
<li> You might be tempted to set the default routes on your nodes by hand.
but that would prevent you from contacting the outside world.
The default route <em>must</em> be set to use the control network
interface.
<li> If you use your own routing daemon, you must 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.
</ul>
</ul>
<!-- Batch Mode -->
......
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