|
|
| (28 intermediate revisions by one other user not shown) |
| Line 1: |
Line 1: |
| − | <h1>Installing VNUML 1.7</h1>
| + | #REDIRECT [[Installation 1.8]] |
| − | | |
| − | <h2 style="text-align: center;">VNUML Installation Guide<br>
| |
| − | <small>version 1.7</small></h2>
| |
| − | | |
| − | <h3 style="text-align: center;">Authors:<br>
| |
| − | Fermin Galan (<a href=
| |
| − | "mailto:galan at dit.upm.es">galan at dit.upm.es</a>)<br>
| |
| − | David Fernández (<a href=
| |
| − | "mailto:david at dit.upm.es">david at dit.upm.es</a>)</h3>
| |
| − | | |
| − | <h4 style="text-align: center;">July 27th, 2006</h4><br>
| |
| − | | |
| − | | |
| − | == Introduction ==
| |
| − | | |
| − | | |
| − | <p>There are two ways of installing VNUML:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li>From APT package in deb-based distribution (Debian, Ubuntu, Kubuntu, MEPIS,...).</li>
| |
| − | <li>From source .tgz</li>
| |
| − | </ul>
| |
| − |
| |
| − | <p>The recommended installation procedure is the former, due to it is much easier than
| |
| − | the later (for example, dependencies are calculated and installed automaticly). However, this
| |
| − | manual describes also the source based installation for users not using .deb based
| |
| − | distributions (like Fedora or SuSE).</p>
| |
| − |
| |
| − | <p>Note the installation prefix in both cases is different: /usr/share for the
| |
| − | .deb package and /usr/local/share for the source .tgz installation (except if you
| |
| − | use a differente PREFIX when <code>./configure</code>).</p>
| |
| − |
| |
| − | <p>UML simulations generally consume a lot of physical
| |
| − | host resources (CPU, disk storage, RAM, etc). As a minimum, you
| |
| − | need a standard Pentium III 500 Mhz with 128 Mb RAM to perform the
| |
| − | tutorial included in the documentation. However, at least 256 Mb
| |
| − | (better 512 Mb) and a faster CPU are recomended to execute more complex scenarios.</p>
| |
| − | | |
| − | == Installing from .deb package ==
| |
| − |
| |
| − | <p>An APT respository has been set up for VNUML related packages. The installation
| |
| − | procedure is as follows:</p>
| |
| − | | |
| − | <ol>
| |
| − | <li>Add the following line to the /etc/apt/sources.list file:</li>
| |
| − | | |
| − | <pre class="box">
| |
| − | deb http://jungla.dit.upm.es/~vnuml/debian binary/
| |
| − | </pre>
| |
| − | | |
| − | <li>Update package list:</li>
| |
| − | | |
| − | <pre class="box">
| |
| − | apt-get update
| |
| − | </pre>
| |
| − | | |
| − | <li>Install VNUML along the packages it depends on</li>
| |
| − | | |
| − | <pre class="box">
| |
| − | apt-get install vnuml
| |
| − | </pre>
| |
| − | | |
| − | </ol>
| |
| − | | |
| − | <p>In addition, although they are not mandatory packages to work with
| |
| − | VNUML, it is <strong>strongly</strong> recommended you install the following:</p>
| |
| − | | |
| − | <pre class="box">
| |
| − | apt-get install vlan xterm bridge-utils screen
| |
| − | </pre>
| |
| − | | |
| − | <p>That's all! :)</p>
| |
| − |
| |
| − | == Installing from source .tgz ==
| |
| − |
| |
| − | <p>VNUML 1.7 source package includes an easy to use installer thanks to Tony Prug and
| |
| − | Casey T. Deccio contributions.</p>
| |
| − |
| |
| − | <p>The most of the cases, all you need to install VNUML is untar the package in your
| |
| − | GNU/Linux box (the package is quite distribution agnostic, but specific issues
| |
| − | for <a href="#mandrake">Mandrake</a> can be found later
| |
| − | in this document) and perform the following operations. A Internet connection is needed,
| |
| − | in order the installation scripts connect to CPAN (and other places) to get Perl modules
| |
| − | and other libraries.</p>
| |
| − | | |
| − | <pre class="box">
| |
| − | ./configure
| |
| − | make
| |
| − | make install
| |
| − | </pre>
| |
| − | | |
| − | <p>(The lastest command needs root privileges in the host)</p>
| |
| − |
| |
| − | <p>Several options can be configured using <code>configure</code> script (for example,
| |
| − | the installation prefix). The <code>./configure --help</code> give the list of the
| |
| − | available options.</p>
| |
| − |
| |
| − | <p>Host kernel needs include tun and loop support in order to work properly. Skas
| |
| − | support is also very desirable. 8012q is also required if you plan to use the
| |
| − | VLAN features of VNUML.</p>
| |
| − |
| |
| − | <p>Please read the INSTALL file that comes with the package in order to get futher
| |
| − | information and details.</p>
| |
| − | | |
| − | <h3><a name="libxml_expat">3. 1. Libxml and expat installation</a></h3>
| |
| − |
| |
| − | <p>VNUML needs libxml2 and expat2 to work. By default, the VNUML install program doesn't
| |
| − | perform special actions about it, assuming the libraries are installed in your system
| |
| − | (for example, as RPM or .deb packages). This is the recomended procedure.</p>
| |
| − |
| |
| − | <p>However, if you want VNUML installer to install libxml2 and/or expat2 being installed
| |
| − | from the source (downloading the packages through Internet) use <code>--with-libxml=yes</code>
| |
| − | and/or <code>--with-expat=yes</code> ./configure options, respectively.</p>
| |
| − | | |
| − | <h3><a name="modules_manual_install">3. 2. External Perl modules</a></h3>
| |
| − |
| |
| − | <p>The VNUML tool requires some external Perl modules to work. By default, the installer (./configure)
| |
| − | check if the required modules are installed. If not, the installer will report the
| |
| − | user about the missing modules, in order he can install them before running again the
| |
| − | installer.</p>
| |
| − |
| |
| − | <p>The list of required modules is (newest versions can be found in
| |
| − | <a href="http://search.cpan.org">CPAN</a>):</p>
| |
| − |
| |
| − | <ul>
| |
| − | | |
| − | <li>Error</li>
| |
| − | <li>Exception::Class</li>
| |
| − | <li>XML::DOM, XML::Checker (these modules usually require some others: XML::RegExp, XML::Parser, XML::Parser::PerlSAX)</li>
| |
| − | <li>NetAddr::IP</li>
| |
| − | <li>Net::Pcap</li>
| |
| − | <li>IO::Socket</li>
| |
| − | <li>Term::ReadKey</li>
| |
| − | <li>Net::IPv6Addr (this module usually requires some others: Math::Base85, Net::IPv4Addr)
| |
| − | <li>File::Glob</li>
| |
| − |
| |
| − | <!-- These two modules appear in the old documentation, but I think it only
| |
| − | the modification in 1.6.0 makes them unecessary
| |
| − | <!--li>Module::Build</li-->
| |
| − | <!--li>LWP</li-->
| |
| − |
| |
| − |
| |
| − | </ul>
| |
| − | | |
| − | <!--p>Some required Perl modules can be found in VNUML web page local storage (note that the they
| |
| − | may be old of date, we recommend you to find always the newest stable version of
| |
| − | this modules in <a href="http://search.cpan.org/">CPAN</a>):</p-->
| |
| − |
| |
| − | <!--ul>
| |
| − | <li>XML-Parser (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/XML-Parser-2.31.tar.gz">2.31</a>)</li>
| |
| − | | |
| − | <li>XML-RegExp (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/XML-RegExp-0.03.tar.gz">0.03</a>)</li>
| |
| − | | |
| − | <li>libxml-perl (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/libxml-perl-0.07.tar.gz">0.07</a>)</li>
| |
| − | | |
| − | <li>XML-DOM (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/XML-DOM-1.42.tar.gz">1.42</a>)</li>
| |
| − | | |
| − | <li>XML-Checker (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/XML-Checker-0.13.tar.gz">0.13</a>)</li>
| |
| − | | |
| − | <li>TermReadKey (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/TermReadKey-2.21.tar.gz">2.21</a>)</li>
| |
| − | | |
| − | <li>Math-Base85 (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/Math-Base85-0.2.tar.gz">0.2</a>)</li>
| |
| − | | |
| − | <li>Net-IPv4Addr (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/Net-IPv4Addr-0.10.tar.gz">0.10</a>)</li>
| |
| − | | |
| − | <li>Net-IPv6Addr (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/Net-IPv6Addr-0.2.tar.gz">0.2</a>)</li>
| |
| − |
| |
| − | <li>Exception-Class (<a href="
| |
| − | http://www.dit.upm.es/vnuml/download/perl-modules/Exception-Class-1.20.tar.gz">1.20</a>)</li>
| |
| − | </ul-->
| |
| − | | |
| − | <p>If you find some required module is missing in the list
| |
| − | before, please, <a href="mailto:vnuml@dit.upm.es">tell us</a> in order to
| |
| − | add it.</p>
| |
| − |
| |
| − | <p>Perl modules are distributed as .tar.gz files. The
| |
| − | standarized way to install them is the following:</p>
| |
| − | | |
| − | <ol>
| |
| − | <li>Uncompress file.</li>
| |
| − | | |
| − | <li>Execute 'perl Makefile.PL'. This checks
| |
| − | dependencies and tell you if another required module have
| |
| − | to be installed previously.</li>
| |
| − | | |
| − | <li>Execute 'make'.</li>
| |
| − | | |
| − | <li>Execute 'make test'. Note that (curiously!)
| |
| − | not getting 100% success doesn't mean always that the
| |
| − | module is not going to work.</li>
| |
| − | | |
| − | <li>Install the module with 'make install' (root
| |
| − | privilegies are needed).</li>
| |
| − |
| |
| − | </ol>
| |
| − | | |
| − | <p>In addition to manual installation, the VNUML installer can automate the missing modules
| |
| − | installation using <code>--with-build_modules=yes</code> configure option. This is done throught
| |
| − | the CPAN public repository and requires Internet connection.</p>
| |
| − | | |
| − | === Required binaries ===
| |
| − |
| |
| − | <p>The vnumparser.pl program needs some external binaries in order to work. The parser is
| |
| − | able to check if the required binaries are in the command path (configure your PATH enviroment
| |
| − | variable properly!) and report to the user if some required binary is missing.</p>
| |
| − |
| |
| − | <p>The most of this binaries are common things, like cp, mv, rm and the like. However, some
| |
| − | others may be difficult to find, in particular the following:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li><strong>brctl</strong> (only if you plan tu use virtual bridge based virtual networks). It can be found in the bridge-utils package (Debian .deb or SuSE .rpm)
| |
| − | <li><strong>vconfig</strong> (only if you plan tu use VLAN features). It can be found in the vlan package (Debian .deb or SuSE .rpm)
| |
| − | <li><strong>tunctl, uml_mconsole, uml_switch</strong>. In Debian, it can be found in the
| |
| − | uml-utilities package (just use 'apt-get install uml-utilities' to install). In other distribution
| |
| − | you can use the RPM in the <a href="http://user-mode-linux.sourceforge.net/dl-sf.html">UML download page</a>
| |
| − | or compile from the sources .tar.bz2 at the same URL (we recommend you the second option).
| |
| − | </ul>
| |
| − | | |
| − | == General Troubleshooting ==
| |
| − | | |
| − | <ul>
| |
| − |
| |
| − | <li>(Installation from source package)
| |
| − | The usual './configure ; make ; make install' may fail in the last step if
| |
| − | the perl-devel package is not installed. In particular, the problem seems
| |
| − | not finding the /usr/lib/perl5/5.8.3/i386-linux-thread-multi/CORE/config.h
| |
| − | file, that is included in that package.
| |
| − | </li>
| |
| − | | |
| − | <li>(Installation from source package)
| |
| − | In order to compile the UML tools you maybe need install previously the readline-devel and ncurses-level
| |
| − | packages (at least in SuSE 9.0 and Mandrake 10.0, see this <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1173967&group_id=113582&atid=665579">bug report</a> for details).
| |
| − | </li>
| |
| − | | |
| − | <li>
| |
| − | The installation procedure of VNUML may create new users and/or group. To avoid permission
| |
| − | problems accesing some resources (for example, socket files), it is recommended
| |
| − | logging completely out and logging back in (see <a href="https://lists.dit.upm.es/pipermail/vnuml-devel/2005-July/000227.html">this posting</a> in the vnuml-devel
| |
| − | list for some more detail).
| |
| − | </li>
| |
| − |
| |
| − | </ul>
| |
| − | | |
| − | == Mandrake specific issues ==
| |
| − | | |
| − | <p>From <a href="https://lists.dit.upm.es/pipermail/vnuml-users/2004-November/000115.html">https://lists.dit.upm.es/pipermail/vnuml-users/2004-November/000115.html</a>.</p>
| |
| − | | |
| − | <ul>
| |
| − |
| |
| − | <li>perl-devel RPM package seems not being installed in
| |
| − | the default Mandrake 10.0 installation
| |
| − | </li>
| |
| − | | |
| − | <li>
| |
| − | The libreadline4-devel RPM package (required to compile UML tools) seems not being installed in the default Mandrake 10.0
| |
| − | installation).
| |
| − | </li>
| |
| − | | |
| − | <li>
| |
| − | The /dev/net/tun device file only seems to exist when tun module is loaded.
| |
| − | So, you need to 'modprobe tun' before running vnumparser.pl in order to
| |
| − | avoid the '/dev/net/tun is not a valid character device file' error message.
| |
| − | </li>
| |
| − | | |
| − | </ul>
| |
| − |
| |
| − | == Contributed software ==
| |
| − |
| |
| − | <p>The contrib/ directory in the source package after untaring contains contributed software that can
| |
| − | be used with VNUML. For example, the contrib/uml_router is a uml_switch modification for
| |
| − | traffic capture. Each contribution has its own README or INSTALL file, with installation steps
| |
| − | and brief how-to descriptions (if you find this information insufficient the
| |
| − | <a href="https://lists.dit.upm.es/mailman/listinfo/vnuml-users">vnuml-user</a> maillist is
| |
| − | the right place to ask for :)</a>
| |
| − |
| |
| − | <p>We strongly recommend you to review the contrib/ directory. Maybe you find something
| |
| − | useful!</p>
| |
