VNUML Offline Installer Ver 1.8.3-1 (22.04.2008) ============================================= Frank Bohdanowicz - bohdan@uni-koblenz.de Based on VNUML Offline Installer Ver 1.6.1 by Andre Volk - avolk@uni-koblenz.de 0. QUICK-INSTALL-GUIDE for experienced Linux Users ================================================== - You need root privileges to start the installation. - Decompress the "VNUML-Offline-X.X.X.tar.gz" Archive. - Type "./install" to start the installation ("./install --debug" starts the installer in debugging mode. The installation then pauses after every single step.) - Re-Login to your Linux machine after the installation! For Debian-Linux Users (e.g. Ubuntu, Knoppix, etc...): ------------------------------------------------------ You can also install VNUML 1.8 via apt-get. Just insert the following line into /etc/apt/sources.list: deb http://jungla.dit.upm.es/~vnuml/debian binary/ Now you can install VNUML with the following commands (internet connection needed!): apt-get update apt-get install vnuml apt-get install linux-um Visit http://www.dit.upm.es/vnumlwiki/index.php/Download for further information. 1. About VNUML ============== VNUML is an open source network simulator, written in Perl and based on UML (User Mode Linux). With the XML based VNUML language. The user defines an arbitrary network topology in a XML based VNUML language. The official VNUML project homepage can be found under: http://jungla.dit.upm.es/vnuml/ 2. System Requirements ======================== VNUML starts a virtual machine with a real linux kernel and a real filesystem for every node in your virtual network (like a router, server or host). Because all this will reside in your system's memory, your computer must have a reasonably fast processor and of course enough main memory (more than 256MB). You will also need about 900MB of free space on your hard disk. Eventually you'll have to deactivate your linux desktop firewall (see 7.3) while you are working with VNUML!!! 3. Notice about the Installation ================================ In the past the installation of VNUML was a difficult and tedious task. The OfflineInstaller (hopefully) provides you with all the packages and perl modules, VNUML needs to run and installs them also in the correct order. But if you experience problems anyway, please contact us per e-mail to bohdan@uni-koblenz.de, to help us improve the OfflineInstaller. Of course we also happily hear about successful installations ;-) 4. Prerequisites for the installation ========================================= - The following essential linux packages must be installed on your computer (Woefully, the existence of these tools is NOT a matter of course on some standard linux installations...) Don't care about these prerequisites. The OfflineInstaller will automatically check the availability of these tools, when it starts to run. If a tool is missing the installer halts and tells you what is missing. - gcc (C-Compiler) - make (The GNU Make Command) - perl (Perl Interpreter) (eventually also perl-modules) - tar (The Compressing Tool tar) - bzip2 (A Compressing Tool) - gzip (A Compressing Tool) - g++ (C++-Compiler, gcc-c++) - ssh (Secure Shell SSH, openssh) - lsof (Analyzer-Tool LiSt Open Files) - flex (the Fast LEXical analyzer) - bison (GNU Parser Generator) - cpp (C-Preprocessor) - screen (Window-Manager GNU Screen) (optional, if xterms shall be used) If you're using SuSE Linux, you can install these tools with YAST. Probably you'll need your linux installation medium or you can use an online-repository: Computer -> Install Software -> Filter: Repositories -> oss (z.B. 10.3-oss) With Debian (or Knoppix, Ubuntu,...) you can install the package with: "apt-get install NAME-OF-PACKAGE" 5 Installation under Linux (Longer version) ================================================ 5.1 Installation Instructions for most users: =============================================== - Decompress "VNUML-Offline-X.X.X.tar.gz" (- You can also burn the decompressed files to a CD and delete them from your harddisk to run the installation from the CD.) - Open the Linux Shell (command line) - Change to the directory (or the CD-ROM device) where you have decompressed the OfflineInstaller files. - For Non-Ubuntu Users: Type "su" to gain root privileges. - Type "./install" (please take note of the correct spelling) and follow the instructions on your screen. (Ubuntu users type: "sudo ./install") - Please log-off from your linux system after the installation and log-in again. That will help to refresh the user management. - Now you should have a fully functional VNUML installation on your system :-) 5.2 Installation Instructions for OpenSuse 10.3 =============================================== You'll need to have at least 2GB of free disk space on your system. Installation of required software: (SuSE menu)->Computer->Install Software Filter: Repositories 10.3-oss Check, if the following software is installed on your computer: make, gcc, gcc-c++, cpp, bison, flex, lsof, screen, openssh, perl, perl-base, bzip2, gzip, tar Open the shell Type "su" Decompress the OfflineInstaller: tar xfzpv VNUML-OFFLINE-1.8.3-1.tar.gz cd VNUML-OFFLINE-1.8.3-1 ./install (takes about 5 minutes) 6. First steps in VNUML ================================ To take advantage of the full VNUML funcionality you'll need root privileges on your linux system while you're working with VNUML. For this you'll have to type "su" (or "sudo -s" on Ubuntu) before you start the VNUML Parser. Since VNUML 1.6 it is also possible to run VNUML only with user privileges. We recommend you to read the documentation and tutorials on the official VNUML homepage. The heart of VNUML is the perl script "vnumlparser.pl". You'll find it at "/usr/local/bin", but you can also run the vnumlparser from within any other directory. The example-files can be found here: "/usr/local/share/vnuml/examples" To start a simulation, first change into the directory where the desired XML file is located, e.g. "cd /usr/local/share/vnuml/examples" To start the scenario, type: "vnumlparser.pl -t tutorial_root2.xml -vB -u root" (tutorial.xml should be your desired XML file) You only need the parameter "-u root" if you really want to start the scenaio with root privileges. When all the virtual machines have finished booting up, you can log into the virtual machines via SSH with the following command: "ssh NAME_OF_THE_VIRTUAL_MACHINE" If your're asked for a password, just type: "xxxx" You can get rid of the password-requests by using: "ssh -1 NAME_OF_THE_VIRTUAL_MACHINE" every time you want to connect to a virtual machine via SSH. Now, you will be asked, if you want to accept the RSA fingerprint of the virtual machine. The message on your screen will look like this: "RSA1 key fingerprint is 7e:3d:7e:73:22:85:b8:03:ff:0f:b0:07:5b:41:d8:ba. Are you sure you want to continue connecting (yes/no)? " Type "yes". This question will probably be asked for every virtual machine, when you shut down the scenario. But you'll have to answer it only once. The command "exit" will close the SSH connection. You can shut the VNUML scenario down with the following command: "vnumlparser.pl -d tutorial.xml -vB" 7. PROBLEMS / IMPORTANT NOTICES / TROUBLESHOOTING ================================================== 7.0 Finding errors during the installation ========================================== To observe the installation progress in more detail (probably to find an error message), you can start the OfflineInstaller with the following command: "./install --debug" The installer halts after every single step so you'll have enough time to examine the output messages. If you find an error you should stop the Installer (Ctrl+C), try to fix the problem (e.g. with the help of the solutions and hints at the end of this readme file) and restart the Installer with "./install" at the end. The installation can only be successfull when the Installer congratulates you for this ;-) 7.1 Documentation ================== Please take a look at the documentation under http://www.uni-koblenz.de/vnuml/ or http://dit.upm.es/vnuml Here you'll find a lot of information about the usage of VNUML and a detailed troubleshooting guide. 7.3 VNUML and the Linux Firewall ================================= If your virtual machines aren't able to ping each other, try to deactivate your desktop firewall (Under SuSE you can do this with YAST). 7.4 After the Installation =========================== Please re-login to your linux system after the installation of VNUML. Version History ================= - Ver 1.8.3-1 (28.04.2008) installs VNUML 1.8.3 - Ver 1.6.1 (27.04.2006) installs VNUML 1.6