Quick fixup of some of the documentation linking while adding info about...

Quick fixup of some of the documentation linking while adding info about idleness/swapping out. Added a faq question and a node usage policies document in swapping.html

www/doc.php3

@@ -13,7 +13,7 @@ PAGEHEADER("Documentation");
 	      How to get an account on the Testbed</a></b>
      <p>
 
-<li><b><a href="tutorial/tutorial.php3">
+<li><b><a href="tutorial/docwrapper.php3?docname=tutorial.html">
               Emulab "Getting Started" Tutorial</a></b>
      <p>
 
@@ -25,6 +25,10 @@ PAGEHEADER("Documentation");
 
 <h3>Reference Material</h3>
 <ul>
+<li><b><a href="tutorial/docwrapper.php3?docname=advanced.html">
+              Emulab Advanced Tutorial</a></b>
+     <p>
+
 <li><b><a href="tutorial/docwrapper.php3?docname=nscommands.html">
               Emulab-specific NS Extensions Reference Manual</a></b>
      <p>
@@ -33,6 +37,22 @@ PAGEHEADER("Documentation");
               Testbed Master Control Daemon (TMCD) Reference Manual</a></b>
      <p>
 
+<li><b><a href = "docwrapper.php3?docname=swapping.html">
+          Node Usage Policies</a></b>
+     <p>
+
+<li><b><a href = "doc/docwrapper.php3?docname=netbuilddoc.html">
+          NetBuild Reference Manual</a></b>
+     <p>
+
+<li><b><a href = "docwrapper.php3?docname=security.html">
+          Security Issues</a></b>
+     <p>
+
+<li><b><a href = "docwrapper.php3?docname=groups.html">
+          About Project Groups</a></b>
+     <p>
+
 <li><b><a href = "doc/docwrapper.php3?docname=hw-recommend.html">
           Want to build your own Testbed?</a></b>
      <p>
@@ -48,12 +68,16 @@ PAGEHEADER("Documentation");
 
 <h3>Miscellaneous</h3>
 <ul>
+<li><b><a href = "docwrapper.php3?docname=news.html">
+          Current and Past Emulab News Items</a></b>
+     <p>
+
 <li><b><a href = "docwrapper.php3?docname=policies.html">
           Administrative Policies and Disclaimer</a></b>
      <p>
 
-<li><b><a href = "docwrapper.php3?docname=security.html">
-          Security Issues</a></b>
+<li><b><a href = "docwrapper.php3?docname=pubs.html">
+          Publications</a></b>
      <p>
 
 <li><b><a href = "docwrapper.php3?docname=sponsors.html">

www/faq.html

@@ -23,6 +23,7 @@
      <li> <a href="#UTT-NETBUILD">Do you have a <b>GUI</b> to help me
                                    create experiments?</a>
      <li> <a href="#UTT-NODES">How many nodes can I ask for?</a>
+     <li> <a href="#UTT-HOWLONG">How long can I keep using my nodes?</a>
      <li> <a href="#UTT-TOOFEW">What if I need more nodes than are free?</a>
      <li> <a href="#UTT-2">Do I get root access on my nodes?</a>
      <li> <a href="#UTT-3">Do my nodes have consoles I can look at?</a>
@@ -261,6 +262,22 @@
     practical aspects of Emulab operation.</em>
     </p>
 
+<li><a NAME="UTT-HOWLONG"></a>
+    <h3>How long can I keep using my nodes?</h3>
+    <p>
+    You can keep them as long as you need them, subject to our <a
+    href="docwrapper.php3?docname=swapping.html">Node Usage
+    Policies</a>.  In general, you should do your work, and then
+    terminate your experiment as soon as you're done with it. If
+    you're not done with it, but are through for a while, you should
+    probably "swap out" your experiment (See the question <a
+    href="#UTT-Swapping">What is Swapping</a> in this FAQ). It is
+    especially important to swap out your experiment if you're through
+    with it for the weekend. Emulab usually gets heavy use on the
+    weekends by users who need to make very large experiments, so it
+    is important to leave as many nodes available as possible.
+    </p>
+
 <li><a NAME="UTT-TOOFEW"></a>
     <h3>What if I need more nodes than are free?</h3>
     <p>
@@ -394,7 +411,7 @@
     </p>
     
 <li><a NAME="UTT-Swapping"></a>
-    <h3>What is Swapping</h3>
+    <h3>What is Swapping?</h3>
     <p>
     Swapping is when you (or we) temporarily swap your experiment out,
     releasing all of the nodes in the experiment. Your experiment is
@@ -430,6 +447,11 @@
     unless you make arrangements to save and restore any state you need.
     </p>
 
+    <p>
+    Make sure to take a look at our 
+    <a href="docwrapper.php3?docname=swapping.html"> Node Usage Policies</a> 
+    as well.
+    </p>
 
     <li><a NAME="UTT-8"></a>
     <h3>How can I get switch statistics (such as packet counts) for my

www/swapping.html

+<a name="top">
+<center>
+<h1>Node Use Policies</h1>
+</center>
+
+<ul>
+<li><a href="#summary">
+What are your policies?</a>
+<li><a href="#active">
+What is "active use"?</a>
+<li><a href="#idle">
+How long is too long for a node to be idle?</a>
+<li><a href="#state">
+What is "node state"?</a>
+<li><a href="#email">
+I just received an email asking me to swap or terminate my
+experiment</a>
+<li><a href="#swapped">
+Someone swapped my experiment!</a>
+</ul>
+
+
+<ul>
+<p><li>
+<a name="summary">
+<h3>What are your policies?</h3>
+
+As a courtesy to other experimenters, we ask that experiments be
+swapped out or terminated when they are no longer in active use. There
+are a limited number of nodes available, and node reservations are
+exclusive, so it is important to free nodes that will be idle so that
+others may use them. By way of summary, our policy is that experiments
+should be swapped out when they are not in use. In general, if they
+are idle for 24 hours or more, we will send you mail about it and/or
+swap out the experiment for you. The actual grace period will differ
+depending on the size of the experiment and other factors. If you mark
+your experiment "unswappable" at creation time, we will contact you
+before swapping it, since local node state will be lost on
+swapout. Please see full details below.
+
+<p><li>
+<a name="active">
+<h3>What is "active use"?</h3>
+
+A node or experiment that is being actively used will be doing
+something related to your experiment. In almost all cases, someone
+will either be logged into it using it interactively, or some program
+will be running, sending and receiving packets, and performing the
+operations necessary to carry out the experiment.
+
+<p><li>
+<a name="idle">
+<h3>How long is too long for a node to be idle?</h3>
+
+Ideally, an experiment should be used nearly continuously from start
+to finish of the experiment, then swapped out or terminated. However,
+this isn't always possible. In general, the 24-hour rule is
+appropriate. If your experiment will most likely be idle for 24 hours
+or more, it should be swapped out. This is especially true on
+weekends. If you finish at the end of the day Friday, and are planning
+to come back Monday morning to use the nodes again, swap out before
+you leave for the day. Experimenters who need many nodes take
+advantage of lower usage on weekends to run their large-scale (50-100
+node) tests. If your experiment is larger than 10 nodes, it is even
+more important to release your nodes as soon as possible. Swapin and
+swapout only take a few minutes (typically 3-5 for swapin, and less
+than 1 for swapout), so you won't lose much time by doing it.
+
+<p><li>
+<a name="state">
+<h3>What is "node state"?</h3>
+
+Some experiments have state that is stored exclusively on the nodes
+themselves, saved to the local hard drive. This is state that is not
+in your NS file and files it references, and which is not preserved in
+our database across swapin/swapout. This is state you add to your
+machines "by hand" after Emulab sets up your experiment, like files
+you add or modify on filesystems local to test nodes. Local node state
+does not include any data you store in /users or /proj, since they are
+saved on a fileserver, and not on the local nodes. 
+
+<p>
+Most experiments don't have any local node state, and can be swapped
+out and in without losing any information. This is highly recommended,
+since it is more courteous to other experimenters. It allows you to
+easily free up your nodes on request without losing any of the work
+you have done on your experiment. Please make your experiments adhere
+to this guideline whenever possible.
+
+<p>
+Wherever possible it is discouraged to have local node state, since
+swapping out causes this data to be lost. An experiment that needs
+local state should be marked "unswappable" when you create it. If you
+must have node state, you can save it before you swap out by creating
+a disk image of the node in question, and later reloading it to a new
+node after you swap in again. Disk images in effect create a "custom
+OS" that can be loaded automatically based on your NS file. More
+information about disk images can be found on our <a
+href="https://www.emulab.net/newimageid_explain.php3"> Disk Image
+page</a> (you must be logged in to use it). We are currently working
+on a system that will allow you to save disk images from all the nodes
+in your experiment at swapout time, and reload them automatically when
+you swap back in.
+
+<p><li>
+<a name="email">
+<h3>I just received an email asking me to swap or terminate my
+experiment</h3>
+
+Emulab has a system for detecting node use, to help achieve more
+efficient and fair use of Emulab's limited resources. This system
+sends email messages to experiment leaders whose experiments have been
+idle for over 24 hours. If you get a message like this, your
+experiment has been inactive for too long and should free up the nodes
+it has allocated. If the experiment continues to be idle, more
+reminders will be sent. On the third reminder and subsequent messages,
+your project leader will be one of the recipients. If you feel you
+receive the message in error, please respond to <a
+href="mailto:testbed-ops@flux.cs.utah.edu"> Testbed Operations
+(testbed-ops@flux.cs.utah.edu)</a> as soon as possible, describing how
+you have used your node in the last 24 hours. There are some types of
+activity that are difficult to accurately detect, so we'd like to know
+how we can improve our activity detection system. Above all, <b>do not
+ignore these messages</b>. If you get several reminders and don't
+respond, your experiment may be swapped out, potentially causing loss
+of some of your work (see "node state" above). If there is a reason
+you need to keep your experiment running <b>tell us</b> so we don't
+inadvertently cause problems for you.
+
+<p><li>
+<a name="swapped">
+<h3>Someone swapped my experiment!</h3>
+
+As described above, we will typically try to contact you about your
+idle experiment before we swap it out. However, if the experiment has
+been idle for many hours, we may swap it out for you unless you marked
+it as "unswappable" when you created your experiment. Because of this,
+it is critical that you keep in close contact with us about an
+experiment that we may perceive as idle if you want to avoid any loss
+of your work.
+
+</ul>
+<p>
+
+<a href="#top"> Back to top of page</a>
+
+