This repository has been archived by the owner on Jan 12, 2021. It is now read-only.
forked from maxonthegit/netkit-core
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
4 additions
and
324 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,323 +1,3 @@ | ||
| Welcome to Netkit-NG version 3.0.3 | ||
| Netkit-NG version 3.0.4 | ||
|
|
||
| WHAT IS NETKIT-NG | ||
| ----------------- | ||
|
|
||
| Netkit-NG is a fork of the netkit project to bring new functionnalities | ||
| and support for recent debian kernels and filesystems. | ||
| It includes an updated version of `netkit-core` which supports a new fs image | ||
| format and includes other contributions released by various github users. | ||
|
|
||
| WHAT IS NETKIT | ||
| -------------- | ||
|
|
||
| Netkit is a self-contained environment that makes it easy and costless to | ||
| emulate complex network configurations on a single host machine. The idea | ||
| underlying Netkit is that each network device is implemented by a virtual | ||
| machine running the appropriate software. Virtual machines can then be | ||
| interconnected as desired by configuring virtual collision domains. | ||
|
|
||
| Interconnected machines may be organized to form a laboratory (lab), which can | ||
| be used to emulate the behavior of a particular service or protocol (e.g., DNS). | ||
| The configuration of the lab can be saved to ease its distribution and | ||
| replication. | ||
|
|
||
| Netkit, in itself, is an open source project aiming at integrating different | ||
| other open source products. See the THANKS section for a brief list of the | ||
| software resources integrated into Netkit. | ||
|
|
||
| The project was born (and is still carried on) with the main purpose of | ||
| supporting teaching of networking subjects with realistic experiences. | ||
|
|
||
| SYSTEM REQUIREMENTS | ||
| ------------------- | ||
|
|
||
| Netkit virtual machines can be configured in a flexible way, so that you can | ||
| decide how many system resources on the host machine should be allocated to | ||
| them. System requirements are not very strict. Netkit can run on a personal | ||
| computer with: | ||
|
|
||
| - An i386/amd64 architecture (read: Pentiums and AMDs are fine). For best | ||
| performance, CPU frequency should be above 600MHz. Netkit works fine also on | ||
| slower systems, but this may impact usability. If your host runs a 64-bit OS, | ||
| you may need to install 32-bit compatibility libraries (most notably, | ||
| libc6-i386 and ia32-libs). | ||
| - At least 256MB of RAM (this mainly depends on the requirements of the Linux | ||
| installation you are using: Netkit virtual machines may consume slightly more | ||
| than 32MB each). | ||
| - At least 1GB of free hard disk space (this is required to install the | ||
| virtual machines filesystem that is distributed with Netkit); even if not | ||
| explicitly required, it is *strongly* recommended that Netkit is installed on | ||
| an ext2/ext3 partition. Not doing so is likely to result in performance losses | ||
| and/or malfunctions. | ||
| - A Linux operating system installation running a 2.6 kernel (2.4 kernels | ||
| may still be supported though); the installation should be capable of | ||
| running a graphical session (read: should include a configured X server); | ||
| this is not strictly required, but it eases running multiple virtual machines | ||
| a lot. | ||
|
|
||
| Due to the particular nature of the User Mode Linux kernel (which Netkit is | ||
| based on), Netkit cannot be natively run on operating systems which are | ||
| different from Linux. | ||
|
|
||
|
|
||
| DOCUMENTATION | ||
| ------------- | ||
|
|
||
| Netkit documentation is available in two separate forms: the Netkit environment | ||
| is fully described by man pages (you can start your reading from 'man netkit'), | ||
| while some other documentation and the description of the labs are provided as | ||
| slides. Standard Netkit documentation is included in the Netkit package itself. | ||
| Additional documentation can be downloaded from http://www.netkit.org/. | ||
|
|
||
|
|
||
| INSTALLATION INSTRUCTIONS for Netkit | ||
| ==================================== | ||
|
|
||
| PRECONDITIONS | ||
| ------------- | ||
|
|
||
| Netkit only runs under the Linux operating system. The toolkit is fairly | ||
| independent from of the specific Linux distribution you have. | ||
|
|
||
| It is strongly advised that you have an installed X server which provides you | ||
| with a graphical environment. Netkit virtual machines can also be started in | ||
| text only virtual terminals, but this limits considerably the flexibility when | ||
| you have to start and manage several machines simultaneously. If you choose to | ||
| start virtual machines inside windows of the graphical environment, you need to | ||
| have a terminal emulator application like xterm, konsole, or gnome-terminal | ||
| properly installed on your machine. Please refer to the documentation of your | ||
| Linux distribution for information about installing these applications. | ||
|
|
||
| In principle, there is no restriction on the host filesystem Netkit can be | ||
| installed on. However, installing it on a non-standard Linux filesystem (e.g., | ||
| FAT32) is likely to cause performance losses and malfunctions. We *strongly* | ||
| recommend to install Netkit on an ext2/ext3 filesystem. Most Linux distributions | ||
| adopt ext3 as a default choice. | ||
|
|
||
|
|
||
| INSTALLING NETKIT | ||
| ----------------- | ||
|
|
||
| Starting from Netkit version 2, a complete Netkit distribution consists of three | ||
| different packages: | ||
| - the Netkit "core", which contains commands, documentation and other stuff | ||
| which is necessary for Netkit to work; | ||
| - the Netkit filesystem, which contains the filesystem for virtual machines; | ||
| - the Netkit kernel, which contains the kernel used by virtual machines. | ||
|
|
||
| Please always make sure you are using the most recent available releases of the | ||
| three packages. Upgrading some of them while leaving others stale may cause | ||
| unpredictable malfunctions of the Netkit environment. | ||
|
|
||
| --- STEP 1: DOWNLOAD AND UNPACK --- | ||
|
|
||
| Download all the files to a directory of your choice. Then unpack them by using | ||
| the following commands: | ||
|
|
||
| tar -xjSf netkit-x.y.tar.bz2 | ||
| tar -xjSf netkit-filesystem-Fx.y.tar.bz2 | ||
| tar -xjSf netkit-kernel-Kx.y.tar.bz2 | ||
|
|
||
| Note that all the three packages must be uncompressed while staying in the same | ||
| directory. It is strongly advised to use the -S option to save space on your | ||
| disk, because this option handles sparse files (i.e., files with lots of empty | ||
| blocks) efficiently. | ||
|
|
||
| Once Netkit has been unpacked, no root privileges are required to configure it | ||
| and start working. | ||
|
|
||
| --- STEP 2: CONFIGURATION --- | ||
|
|
||
| The first step is to set the environment variable NETKIT_HOME to the name of the | ||
| directory Netkit has been installed into. Versions of Netkit prior to 2 used | ||
| variable VLAB_HOME. Such variable is supported as well, but you are encouraged | ||
| not to use it. In order to access the Netkit man pages, the MANPATH variable | ||
| must be set to ":$NETKIT_HOME/man". For example, assuming that you have | ||
| installed Netkit to /home/foo/netkit and that your shell is bash, you would use | ||
| the following commands: | ||
|
|
||
| export NETKIT_HOME=/home/foo/netkit | ||
| export MANPATH=:$NETKIT_HOME/man | ||
|
|
||
| It may also be useful to put these lines inside your shell initialization file | ||
| (`.bashrc' in case you are using the bash shell). Consult your shell | ||
| documentation for more information about this. | ||
|
|
||
| After doing this, you need to update your PATH environment variable to include | ||
| the path to the standard Netkit commands. This is required in order to make | ||
| Netkit work properly. The entry you need to add to the PATH is | ||
| "$NETKIT_HOME/bin". For example, assuming Netkit is (still) installed into | ||
| /home/foo/netkit and that your shell is (still) bash, you would type: | ||
|
|
||
| export PATH=$NETKIT_HOME/bin:$PATH | ||
|
|
||
| Again, it may be convenient to put this line inside your shell initialization | ||
| file. | ||
|
|
||
| --- STEP 3: CHECK YOUR CONFIGURATION --- | ||
|
|
||
| At this point, change the current directory to the Netkit directory: | ||
|
|
||
| cd netkit | ||
|
|
||
| Now, run the `check_configuration.sh' script by typing: | ||
|
|
||
| ./check_configuration.sh | ||
|
|
||
| This script takes care of checking whether your system is configured properly to | ||
| make Netkit run. Any misconfigurations are signalled and instructions for fixing | ||
| them are reported as well. If the script exits with success, then Netkit is | ||
| ready for use. | ||
|
|
||
| We suggest reading the documentation by starting from the man page netkit(7). | ||
|
|
||
|
|
||
| TESTING YOUR INSTALLATION | ||
| ------------------------- | ||
|
|
||
| In order to test whether Netkit is working properly, you can start a simple | ||
| virtual machine by issuing the command: | ||
|
|
||
| vstart pc1 | ||
|
|
||
| If everything is in place, you should see a new virtual machine starting up | ||
| (eventually popping up an xterm window) and the command `vlist' on the host | ||
| machine should show an output which is similar to the following: | ||
|
|
||
| vlist | ||
|
|
||
| USER VHOST PID UPTIME SIZE INTERFACES | ||
| foo pc1 24102 00:03 12376 | ||
|
|
||
| Total virtual machines: 1 (you), 1 (all users). | ||
| Total consumed memory: 12376 KB (you), 12376 KB (all users). | ||
|
|
||
| You can stop the virtual machine by typing the following command on the host | ||
| machine console: | ||
|
|
||
| vhalt -r pc1 | ||
|
|
||
| You can now delete the file pc1.log. | ||
|
|
||
|
|
||
| COMMAND AUTOCOMPLETION | ||
| ---------------------- | ||
|
|
||
| As an additional feature, users of the bash shell can take advantage of command line autocompletion for Netkit commands | ||
| (supported starting from release 2.7). | ||
| In order to activate it, first of all make sure your shell is bash: | ||
|
|
||
| readlink -f $SHELL | ||
|
|
||
| If it is, then you can safely add the following line at the end of your ~/.bashrc file: | ||
|
|
||
| . $NETKIT_HOME/bin/netkit_bash_completion | ||
|
|
||
| BUG REPORTING | ||
| ------------- | ||
|
|
||
| Being an integration of different software products, Netkit is a somewhat | ||
| complex product. We are doing our best to make it be a stable, fast, solid and | ||
| reliable product. However, due to the complex interactions between the various | ||
| components, misbehaviors or malfunctions may occur in the presence of particular | ||
| configurations. We put our effort in trying to fix these bugs as fast as | ||
| possible (remember that this is not the only activity in our lives ;) ). In | ||
| turn, we expect users to signal them so that we can improve the quality of | ||
| Netkit as time goes on. | ||
|
|
||
| Please make sure you have carefully read the documentation (including man pages | ||
| and FAQs, if available) before submitting a bug report. Instructions for doing | ||
| this are provided in the man pages. Bug reports should be sent to | ||
| <contact@netkit.org> or submitted for public discussion to | ||
| <netkit.users@list.dia.uniroma3.it>. | ||
|
|
||
|
|
||
| CREDITS AND CONTACTS | ||
| -------------------- | ||
|
|
||
| This distribution has been released by the Computer Networks (CompuNet) Research | ||
| Group at the University of Roma Tre (http://www.dia.uniroma3.it). People | ||
| involved in the project include (but are not limited to): | ||
| - Giuseppe Di Battista | ||
| - Maurizio Patrignani | ||
| - Stefano Pettini | ||
| - Maurizio Pizzonia | ||
| - Fabio Ricci | ||
| - Massimo Rimondini | ||
|
|
||
| The project has been carried on in the past with significant contributions from | ||
| the Linux User Group "LUG Roma Tre" (http://www.lugroma3.org). | ||
|
|
||
| Apart from people from CompuNet and from the LUG, another special mention is due | ||
| for contributions provided by Andrea Cecchetti, Lorenzo Colitti, Federico | ||
| Mariani, and Flavia Picard. | ||
|
|
||
| The update to Debian wheezy has been released by Julien Iguchi-Cartigny. | ||
|
|
||
| The current official Netkit site is http://www.netkit.org/. Here you can find the | ||
| Netkit distribution itself and also some additional resources (e.g., some labs). | ||
| Contact information is provided as well. You can reach the Netkit team by | ||
| writing to <contact@netkit.org> or by subscribing to the mailing list | ||
| <netkit.users@list.dia.uniroma3.it>. | ||
|
|
||
|
|
||
| THANKS | ||
| ------ | ||
|
|
||
| Netkit is a software integration project. Hence, we would like to thank at least | ||
| the following people for having made all this possible: | ||
|
|
||
| - Linus Torvalds for Linux | ||
| - All the people working on the Linux kernel | ||
| - James R. Leu and Ramon Casellas for their work on MPLS routing | ||
| - Jeff Dike, Paolo Giarrusso, and the other contributors for User Mode Linux | ||
| specific resources | ||
| - Kunihiro Ishiguro, Paul Jakma, and the other developers for the Zebra/Quagga | ||
| routing daemon | ||
| - Lennert Buytenhenk and the other people working on bridge sources and | ||
| utilities at http://bridge.sourceforge.net | ||
| - many many others... | ||
|
|
||
|
|
||
| History | ||
| ------- | ||
|
|
||
| Version 3.0.3 | ||
| * Fix #3: check-configuration script returns warning about parse file not supported on ext4 | ||
| * force LANG_C to all scripts to avoid internationalization errors | ||
| * Fix #4: Missing dynamic library dependency when calling vhalt | ||
| * Add tests to check if filesystem supports sparse file for FS and model FS | ||
|
|
||
| Version 3.0.2 | ||
| * archive name and directory start with netkit-ng to avoid clash with original netkit | ||
|
|
||
| Version 3.0.1 | ||
| * fixing error during README.mdown copy into archive during build | ||
|
|
||
| Version 3.0 | ||
| * switching to new major version, as scripts are now expecting new fs organization | ||
| * moving console profile to tools directory | ||
|
|
||
| Version 2.12 | ||
| * uml tools patches are included in git from now | ||
| * moving to new root filesystem from netkit-uml-build | ||
|
|
||
| Version 2.11 | ||
| * It is now possible to run only bin/manage_tuntap script via sudo, not /bin/sh. (sv75) | ||
|
|
||
| Version 2.10 | ||
| * support for 32 and 64 bits architecture for UML tools | ||
| * add binary check during check_configuration.d (to detect problem when the user install the wrong version of netkit in | ||
| respect of his host architecture). | ||
|
|
||
| Version 2.9 | ||
| * renaming vconfig to vconf (zioproto) | ||
| * support for connection mconsole (babazka) | ||
| * support for vdump (via uml_dump): small utility to connect wireshark or tcpdump directly to a uml_switch | ||
| * add Ktabstart, a tool to run netkit session within konsole tabs (sv75) | ||
| * for developpers: | ||
| * better looking excludes in Makefile (Markus Stenberg) | ||
| * sources of the uml tools are in src/ directory and patches are applied during build | ||
| * removing previous uml tools binaries | ||
| * removing obsolete goals in Makefile | ||
| Documentation are located here: http://netkit-ng.github.io/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1 @@ | ||
| Netkit-NG version 3.0.3 | ||
| Netkit-NG version 3.0.4 |