<commit_before><!--
   EMULAB-COPYRIGHT
   Copyright (c) 2000-2002 University of Utah and the Flux Group.
   All rights reserved.
  -->
<center>
<h1>
    Wide-area Tutorial
</h1>
</center>

<a href=../docwrapper.php3?docname=widearea.html>Wide-area nodes</a> are
used in a somewhat different manner than local nodes. Wide-area nodes
are shared amongst experimentors and projects, and while you have
exclusive use of your local nodes, you are most likely sharing your
wide-area nodes with others. For that reason, there are a number of
features that are not available on wide-area nodes. <b>Note:</b> many of
these restrictions will be lifted when we switch to Unix virtual
machines on wide-are nodes (eg: jail on Freebsd and vservers on Linux).

<ul>
<li> You may not reboot or power cycle a wide-area node.

<li> There is no root access for experimentors. 

<li> You may not select the OS; all wide-area nodes run the
     same version of FreeBSD (currently 4.6 or later).

<li> RPM and tarball installs are not supported; you need to copy over
     and install your software on your own.

<li> There is no NFS access to your files on <tt>users.emulab.net</tt>. 
     Instead, we provide access via the
     <a href=http://www.fs.net>Self-certifying File System.</a>

</ul>

On the other hand, many testbed features <em>are</em> available on
wide-area nodes:

<ul>
<li> Wide-area nodes are requested via your NS file, much like local
     nodes. The difference is that you request <em>virtual</em> nodes
     on wide-area nodes, not the actual wide-area nodes themselves.
     This allows the wide-area node to be shared amongst several
     different experiments. There are several ways to select which
     wide-area nodes are assigned to your experiment:

     <ul>
     <li> You can let the system choose a completely random set:
	<code><pre>
	tb-set-hardware $nodea pcRemote		</code></pre>
     
     <li> You can select a particular node by choosing a virtual node
     on that node. To aid in that selection, you can use our
     <a href="https://www.emulab.net/widearea_info.php3">wide-area
     info</a> table to determine the bandwidth and latency
     characteristics of the widearea nodes. For example:
	<code><pre>
	tb-fix-node $nodea vwa35-4		</code></pre>

     At present there is a fixed number of virtual nodes per wide-area
     node. To determine which virtual nodes are free for use, please
     consult the
     <a href="https://www.emulab.net/nodecontrol_list.php3?showtype=virtnodes">
     reservations table</a>.

     <li> Lastly, you can let the system choose the most approriate
     set of virtual nodes for your toplogy. The system will look at
     the bandwidth and delay characteristics you have specifed in your
     link statements, and attempt to match them based on the most
     recent information that is available. For example:
	<code><pre>
	set v0 [$ns node]
	set v1 [$ns node]
	tb-set-hardware $v0 pcRemote
	tb-set-hardware $v1 pcRemote
	set l0 [$ns duplex-link $v0 $v1 10Mb 45ms DropTail] </code></pre>

     If you use this method, an overlay network will be created for
     you so that you can treat your wide-area nodes just like local
     nodes with respect to network interfaces. In the above example,
     IP addresses 10.1.1.1 and 10.1.1.2 will be assigned to ends of
     the link, and an overlay will be created between the physical
     nodes so that things like "ping 10.1.1.2" will work normally.
     Or, you can elect to ignore the overlays we have created for you
     and use the IP addresses of the physical nodes. You can also
     create a link between a wide-area node and a local node; an
     overlay link will be established for this connections as
     well. Note that overlays are currently implemented using the <a
     href=http://vtun.sourceforge.net>vtun package</a> (UDP mode, no
     compression, no encryption). We plan to switch to ipsec in the
     future.
     </ul>

<li> Traffic generation via the TG tool set is available on wide-area
     nodes just like it is on local nodes. You may also set up traffic
     generators between local and wide-area nodes. Traffic generation
     is discussed in more detail in the
     <a href="docwrapper.php3?docname=advanced.html">advanced
     tutorial</a>. 

<li> Routing support within experiments that use wide-area nodes with
     overlay links (see above) is also available. While we do not
     support NS' <code>Session</code> option when your experiment uses
     wide-area nodes, we do support the <code>Static</code> and
     <code>Manual</code> options, although we strongly recommend that
     you use the <code>Static</code> option so that system sets up all
     the routes for you. Routing is discussed in more detail in the
     <a href=docwrapper.php3?docname=tutorial.html#Routing> Emulab
     Tutorial</a>.

     <br>
     <br>
     Note: If you did not establish overlay links (see above) for your
     wide-area node links, connections between wide-area nodes, and
     between wide-area nodes and local Emulab nodes, must be to their
     external network interface. For example, if you set up an
     experiment called "wa" in project "testbed" using this NS file:
	<code><pre>
	set v0 [$ns node]
	set n0 [$ns node]
	tb-set-hardware $v0 pcRemote			</code></pre>

     Then you will be assigned one local node and one wide-area node.
     If you want to establish network connections between these two nodes,
     then you should use these names (which are mailed to you when the
     experiment has completed setting up).
	<code><pre>
	ping v0.wa.testbed.emulab.net
	ping n0.wa.testbed.emulab.net			</code></pre>

<li> Once your experiment is running, you can log into your wide-area
     nodes using ssh. As a security precaution, your account will not
     accept a password. Instead, your ssh public keys are distributed
     for you. As long as you have an agent running, and you have added
     to the agent at least one private key that corresponds to one of
     the public keys that we have in your
     <a href="https://www.emulab.net/showpubkeys.php3">
     ssh key profile</a>, you will be able to log in without needing a
     password. As mentioned above, you will not have root access on
     wide-area nodes (although you will have that access on local
     nodes if your project leader has approved you with root
     permissions).

<li> Remote file access to your account on <tt>users.emulab.net</tt>
     is currently provided via the <a href=http://www.fs.net>Self-certifying
     File System (SFS).</a> Much like ssh, SFS requires distribution
     of your <a href="https://www.emulab.net/showsfskeys.php3">sfs
     public keys</a>,and an agent that forwards your private
     keys. Once you have checked out the SFS web site and are familiar
     enough with SFS to use it, you can use the <tt>rex</tt> client to
     log into your nodes, which will forward your private keys and
     allow you to access files on <tt>users.emulab.net</tt>. Rex can
     be used from any machine that supports SFS, including
     <tt>users.emulab.net</tt> or even your desktop machine if SFS is
     installed on it. 

</ul><commit_msg>Minor updates to widearea usage page, including some planetlab specific notes. Also convert examples to use physical nodes in tb-fix-node, and fix the types using in tb-set-hardware statements.<commit_after><!--
   EMULAB-COPYRIGHT
   Copyright (c) 2000-2003 University of Utah and the Flux Group.
   All rights reserved.
  -->
<center>
<h1>
    Wide-area Tutorial
</h1>
</center>

<a href=../docwrapper.php3?docname=widearea.html>Wide-area nodes</a> are
used in a somewhat different manner than local nodes. Wide-area nodes
are shared amongst experimentors and projects, and while you have
exclusive use of your local nodes, you are most likely sharing your
wide-area nodes with others. For that reason, there are a number of
features that are not available on wide-area nodes. <b>Note:</b> many of
these restrictions will be lifted when we switch to Unix virtual
machines on wide-are nodes (eg: jail on Freebsd and vservers on
Linux).

<em> PlanetLab nodes have a slightly different set of features and
     restrictions. These differences are noted where appropriate. </em>

<ul>
<li> You may not reboot or power cycle a wide-area node. However, you
     <em>may</em> reboot the virtual node in which you are running. 

<li> There is no root access for experimentors, except when running
     inside a virtual node (jail on FreeBSD, vservers on PLab nodes). 

<li> You may not select the OS; all wide-area nodes run the
     same version of FreeBSD (currently 4.6 or later) and Linux on PLab
     nodes. 

<li> There is no NFS access to your files on <tt>users.emulab.net</tt>. 
     Instead, we provide access via the
     <a href=http://www.fs.net>Self-certifying File System on FreeBSD
     nodes. There is no remote file access on PLab nodes.

<li> Traffic generators and program objects are not available on
     widearea nodes. More generally, anything requiring the event
     system for its control plane is not available. We hope to have
     the event system working in the widearea real soon now ...

</ul>

On the other hand, many testbed features <em>are</em> available on
wide-area nodes:

<ul>
<li> Wide-area nodes are requested via your NS file, much like local
     nodes. The difference is that you request <em>virtual</em> nodes
     on wide-area nodes, not the actual wide-area nodes themselves.
     This allows the wide-area node to be shared amongst several
     different experiments. There are several ways to select which
     wide-area nodes are assigned to your experiment:

     <ul>
     <li> You can let the system choose a completely random set:
	<code><pre>
	tb-set-hardware $nodea pcvwa
	tb-set-hardware $nodea pcplab		</code></pre>
     
     <li> You can select a particular node by choosing the physical
     node, and using the "fix-node" directive. A free virtual node on
     that physical node will be choosen for you. To aid in that
     selection, you can use our
     <a href="https://www.emulab.net/widearea_info.php3">wide-area 
     info</a> table to determine the bandwidth and latency
     characteristics of widearea nodes.
     <a href="https://www.emulab.net/plabmetrics.php3">PlanetLab node
     metrics</a> are also available. For example:
	<code><pre>
	tb-fix-node $nodea ron10		</code></pre>

     At present there are a fixed number of virtual nodes per wide-area
     node. If there are no free virtual nodes on the physical node you
     have choosen, the experiment will fail to map. 

     <li> Lastly, you can let the system choose the most approriate
     set of virtual nodes for your toplogy. The system will look at
     the bandwidth and delay characteristics you have specifed in your
     link statements, and attempt to match them based on the most
     recent information that is available. For example:
	<code><pre>
	set v0 [$ns node]
	set v1 [$ns node]
	tb-set-hardware $v0 pcvwa
	tb-set-hardware $v1 pcvwa
	set l0 [$ns duplex-link $v0 $v1 10Mb 45ms DropTail] </code></pre>

     If you use this method, an optional overlay network can be
     created for you so that you can treat your wide-area nodes just
     like local nodes with respect to network interfaces. However,
     this only works on the FreeBSD based pcvwa nodes. The PlanetLab
     nodes do not support overlay networks. For example:
	<code><pre>
	tb-set-usewatunnels 1			</code></pre>

     In the above example, IP addresses 10.1.1.1 and 10.1.1.2 will be
     assigned to ends of the link, and an overlay will be created
     between the physical nodes so that things like "ping 10.1.1.2"
     will work normally.  Or, you can elect to ignore the overlays we
     have created for you and use the IP addresses of the physical
     nodes. You can also create a link between a wide-area node and a
     local node; an overlay link will be established for this
     connections as well. Note that overlays are currently implemented
     using the
     <a href=http://vtun.sourceforge.net>vtun package</a> (UDP mode, no
     compression, <b>no</b> encryption). 
     </ul>

<li> Routing support within experiments that use wide-area nodes with
     overlay links (see above) is also available. While we do not
     support NS' <code>Session</code> option when your experiment uses
     wide-area nodes, we do support the <code>Static</code> and
     <code>Manual</code> options, although we strongly recommend that
     you use the <code>Static</code> option so that system sets up all
     the routes for you. Routing is discussed in more detail in the
     <a href=docwrapper.php3?docname=tutorial.html#Routing> Emulab
     Tutorial</a>.

     <br>
     <br>
     Note: If you did not establish overlay links (see above) for your
     wide-area node links, connections between wide-area nodes, and
     between wide-area nodes and local Emulab nodes, must be to their
     external network interface. For example, if you set up an
     experiment called "wa" in project "testbed" using this NS file:
	<code><pre>
	set v0 [$ns node]
	set n0 [$ns node]
	tb-set-hardware $v0 pcvwa			</code></pre>

     Then you will be assigned one local node and one wide-area node.
     If you want to establish network connections between these two nodes,
     then you should use these names (which are mailed to you when the
     experiment has completed setting up).
	<code><pre>
	ping v0.wa.testbed.emulab.net
	ping n0.wa.testbed.emulab.net			</code></pre>

<li> Once your experiment is running, you can log into your wide-area
     nodes using ssh. As a security precaution, your account will not
     accept a password. Instead, your ssh public keys are distributed
     for you. As long as you have an agent running, and you have added
     to the agent at least one private key that corresponds to one of
     the public keys that we have in your
     <a href="https://www.emulab.net/showpubkeys.php3">
     ssh key profile</a>, you will be able to log in without needing a
     password. As mentioned above, you will not have root access on
     wide-area nodes (although you will have that access on local
     nodes if your project leader has approved you with root
     permissions).

<li> Remote file access (pcvwa FreeBSD nodes only) to your account on
     <tt>users.emulab.net</tt> 
     is currently provided via the <a href=http://www.fs.net>Self-certifying
     File System (SFS).</a> Much like ssh, SFS requires distribution
     of your <a href="https://www.emulab.net/showsfskeys.php3">sfs
     public keys</a>,and an agent that forwards your private
     keys. Once you have checked out the SFS web site and are familiar
     enough with SFS to use it, you can use the <tt>rex</tt> client to
     log into your nodes, which will forward your private keys and
     allow you to access files on <tt>users.emulab.net</tt>. Rex can
     be used from any machine that supports SFS, including
     <tt>users.emulab.net</tt> or even your desktop machine if SFS is
     installed on it. 

</ul>
{'fraction_non_alphanumeric': 0.07055944980822643, 'fraction_numerical': 0.006943525988625843, 'mean_word_length': 3.190357439733998, 'pattern_counts': {'":': 0, '<': 189, '<?xml version=': 0, '>': 189, 'https://': 8, 'lorem ipsum': 0, 'www.': 12, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6314597', 'n_tokens_mistral': 4389, 'n_tokens_neox': 4241, 'n_words': 2134}