README for the vn script
------------------------
Fermin Galan (galan at dit dot upm dot es)
VNUML Project Development Team

The vn script (much inspired in the xm command from Xen) is designed as
a management front-end for running VNUML scenarios. It is included in the
contrib/ directory of the VNUML from 1.8.3. The current release of vn
included is by the moment *very* experimental and could be buggy. 

If you use the script please send your feedback to the VNUML users
mailing list (more info: http://www.dit.upm.es/vnumlwiki/index.php/Forums)

The syntax to use vn is:

   ./vn <mode> <arguments>

by the momment the only mode implemented is "console", so the syntax is
actually:

   ./vn console <simulation> <vm>
   
where <simulation> is the name of a running VNUML scenario and <vm> is the 
name of the virtual machine which console we want to access. The console 
mode allow you to attach and deattach to virtual machines console sessions 
(much in the way the screen(1) command works, as a matter of fact, *screen 
must be installed in order vn to work*). This is a very interesting 
alternatve to graphical consoles (xterm) specially in the case you have a 
high number of vm (so you don't want your desktop to be invaded by xterm 
windows) or you don't have graphical environment at all (quite common 
in the case of datacenter servers).

In order vn could connect to a vm, it has to be created using 
<console ...>pts</console>.

Let's see how it works with a simple example:

1. Create an alternative version of tutorial_limited_user.xml (for example 
   tutorial_limited_user_vn.xml) changing the <console> line so it reads:
   
      <console id="0">pts</console>
   
2. Start the scenario as usual (note that, having set pts consoles,  
   no xterm window is poped-up)
   
      vnumlparser.pl -t tutorial_limited_user_vn.xml -v
      
   (Maybe you need to use -Z or press Ctrl+C each vm booting, depending of 
   your host and UML kernel versions; see http://www.dit.upm.es/vnumlwiki/index.php/FAQ)
   
3. Once the scenario has been created, you can use vn to access to any vm. 
   For example, to access to uml1:
   
      ./vn console tutotial-lu uml1
      
   Usually a blank screen appear: just press enter to get the login prompt.
   
   Login and introduce some commands (e.g., "ls /etc") so you can check
   that the console work as expected. After working a while, you can "get out"
   of the vm deattaching the console pressing "Ctrl-A D" (that means: Ctrl 
   and 'A' at the same time, then release them an press D). Note that this 
   is the same as in screen(1). Moreover, other screen key sequences can be
   used also with vn console (because of, as a matter of fact, vn implementation
   is based on screen).
   
   You can "get back" to the vm using again:
   
      ./vn console tutotial-lu uml1
      
   Note that the content on the console is preserved when deattaching and
   attaching back again.
   
Some more remarks:

*  You only can have one session attached to each virtual machine. However,
   you don't have to worry about it: if you accidentally type a second 
   "./vn console tutotial-lu uml1" once a first one has been executed, vn
   will warn you about.
   
*  Don't try to use in vm that you created using <console ...>xterm</console>,
   vn console doesn't work properly in this case.
   
*  You can safetely destroy the vn "container" (in that case the session 
   is automatically deattached). For example, if you run the vn command
   inside a xterm and you destroy the xterm, you can recover the session
   opening a new xterm and using vn again.