Content-type: text/html Man page of VCLEAN

VCLEAN

Section: Netkit (1)
Updated: November 2009
Index Return to Main Contents

NAME

vclean - cleanup netkit processes and configurations

SYNOPSIS

vclean [options]

DESCRIPTION

The vclean command can be used to perform some cleanup operations on the host machine. In order to run virtual machines, Netkit launches several processes and sometimes performs some configuration changes (e.g., when setting up ``tap'' collision domains - see vstart(1) -). After stopping all the virtual machines the system is reverted to its original state. Nevertheless, sometimes it may be useful (or even necessary) to force a cleanup which stops hanging processes and removes any configuration change. In this sense, vclean can be considered as the Netkit ``panic button''.

The use of vclean becomes necessary in (at least) the following situations:

-: A network interface has been connected to a ``tap'' collision domain. After halting (or crashing) some virtual machines, the ``tap'' collision domain is not used any more and the corresponding configuration settings must be removed (see vstart(1) for a description of ``tap'' collision domains).
-: A network interface has been attached ``on the fly'' to a running virtual machine by using vconfig (see vconfig(1)). After halting (or crashing) the machine, the corresponding virtual hub is still running and must be terminated.

vclean can perform several cleanup operations. If invoked without options, it just scans for virtual hubs launched by the current user that are still running but no longer used (i.e., there is no virtual machine that is connected to them). If any of the options listed below is provided, then only the requested action is performed. It is also possible to perform several actions in a single run.

--clean-all

This option tells vclean to perform all the cleanup operations listed below. It is a shortcut for -HKT.
Please use this option with care: depending on the other command line switches you are using, this may kill virtual machines started by any user!

-H

--remove-hubs

Terminate running virtual hubs (collision domains) that are not used any more (i.e., those that have no virtual machines attached). This is the default action when vclean is invoked without options.

-K

--kill-machines

Terminate all running virtual machines and virtual hubs. Virtual machines are killed in the same way as the ``vcrash -k'' command would do (see vcrash(1)).
This is probably the most effective ``panic button''. In fact, using this option should result in getting rid of all Netkit processes, even the hanging ones (unless they are hanging so hard that only a reboot can destroy them).

-T

--remove-tunnels

When using an interface attached to a ``tap'' collision domain for the first time, vstart (or vconfig, depending on the command you have been using to configure the interface - see vstart(1), vconfig(1)) takes care of automatically configuring the necessary host-side settings and, if found, also the iptables firewall. For details about the configuration parameters being altered, see vstart(1).

This option removes any host-side configurations and restores the previous firewall settings. More precisely, the following operations are performed:

1) If the iptables firewall is found, then both masquerading and packet forwarding for data passing through tap interfaces are disabled. In particular, the following rules are removed:

*nat
-A POSTROUTING -j MASQUERADE
*filter
-A FORWARD -i nk_tap_+ -j ACCEPT

2) Kernel IP forwarding is disabled by echoing `0' to the special file `/proc/sys/net/ipv4/ip_forward'.
3) Every tap interface (on the host side) is brought down and the corresponding tap device is removed.
4) Permissions for the `/dev/net/tun' device are set to 660 (read/write for its owner and for other users in the same group; no permissions for other users).

These operations require administrative privileges. The vclean command will take care of asking you for a password if needed. For more information about how Netkit gains root privileges, see USE_SUDO and SETTING UP NETKIT FOR USE WITH SUDO in the man page of netkit.conf(5).

Notice: this action is in no way influenced by the --user option. Using --remove-tunnels or -T causes all host-side configurations to be removed, regardless of the user who had requested them.

--test

Instead of terminating virtual hubs and/or virtual machines, just show which processes would be killed. This option cannot be used together with -q (--quick, --quiet). Action --remove-tunnels is not affected by the use of --test.

-u USERNAME

--user=USERNAME

This options limits the scope of the above actions to virtual machines and hubs owned by user USERNAME. By default, vclean only terminates machines and hubs owned by the current user (i.e., the one who launched vclean). The special user name `-' is reserved, and can be used to perform cleanup actions on every machine and hub, regardless of the user who started it. Please use the `--user=-' or `-u -' option with extreme care: depending on the options you are using, this may crash ALL virtual machines that are currently running on the host machine.

Action --remove-tunnels is not affected by this option.

Other supported options are:

-h

--help

Show usage information.

-q

--quick

--quiet

By default, after killing processes vclean checks whether they have actually stopped. This option disables these checks, thus quickening the execution of vclean. It also suppresses any output, except errors and warnings.

This option cannot be used in conjunction with --test.

--version

Print information about the installed Netkit release and the host kernel version and exit. If ``<unavailable>'' is printed instead of a version number, then the corresponding information could not be retrieved (for example because a non-standard Netkit kernel or filesystem is being used).

ENVIRONMENT VARIABLES

All Netkit commands require that the NETKIT_HOME variable contains the name of the directory Netkit is installed in.

Apart from this, vclean supports no other environment variables.

NOTES

vclean has nothing to do with lclean(1). While the former works as a vacuum cleaner for unused and/or hanging Netkit processes, the latter is a tool to clean up directories containing Netkit labs. In particular, vclean works on processes (which have not necessarily been originated in a Netkit lab) and, optionally, on the system configuration (to remove tunnels and firewall settings), while lclean(1) works on the host filesystem (with the purpose of cleaning up temporary files created after running a Netkit lab).

AUTHOR

vclean script: Massimo Rimondini
This man page: Massimo Rimondini

REPORTING BUGS

Report bugs to <netkit.users@list.dia.uniroma3.it> or, alternatively, to <contact@netkit.org>.

Bug reports should always include the following information:

-: Bug description (e.g., expected and actual behaviour).
-: One or more command lines that can be used to reproduce the bug.
-: Name and version of the offending command (e.g., vstart 1.0). You can get the command version by starting it with the option --version.
-: Complete output of the offending command (any --verbose option should be used when producing this report).
-: Version of the Netkit filesystem being used.
-: Version of the Netkit kernel being used.
-: Name and release of the Linux distribution being used on the host machine (e.g., Debian, Ubuntu, Mandrake, Red Hat, Fedora, Gentoo, etc.).
-: Host kernel release and platform. You can get these information by using the `uname -a' command.
-: Description of any patch or changes applied to kernels (host and UML) and filesystems.

This document was created by man2html, using the manual pages.
Time: 11:38:54 GMT, January 29, 2010