Content-type: text/html Man page of VCONFIG

VCONFIG

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

NAME

vconfig - attach network interfaces to running netkit virtual machines

SYNOPSIS

vconfig [options] MACHINE-ID

DESCRIPTION

The vconfig command can be used to attach network interfaces to running virtual machines ``on the fly''. The affected machine is identified by a MACHINE-ID, which is either the PID or the name of a running virtual machine.

One or more interfaces can be attached or detached on a running virtual machine by using the following option an arbitrary number of times.

--ethN=DOMAIN

The syntax for this option is exactly the same as for the corresponding option of vstart (see vstart(1)). It is also possible to provide an empty DOMAIN, in which case the network interface ethN will be no longer available on the virtual machine.
Please read the vstart documentation before using this option to setup ``tap'' collision domains.

Attaching an already existing interface to a virtual machine causes an error.

The following options are also supported by vconfig.

-h

--help

Show usage information. This option also reports information about the range of allowed interface numbers, configured inside netkit.conf (see netkit.conf(5)).

-p

--print

Instead of actually starting virtual hubs and configuring network interfaces, just show which commands would be executed.

-q

--quiet

This option suppresses any kind of output, except errors and warnings.

-u USERNAME

--user=USERNAME

This option tells vconfig to only work on virtual machines owned by USERNAME. By default, vconfig only allows to attach interfaces to virtual machines started by the current user (i.e., the one who launched vconfig). By using this option it is possible to attach interfaces to someone else's virtual machines (this requires administrative privileges). The special user name `-' is reserved and allows to consider all virtual machines, regardless of their owner.

Consider that different users may be running virtual machines having the same name. Hence, using the `--user=-' option when MACHINE-ID is a virtual machine name may arise ambiguities. In such a case, vconfig only works on the virtual machine reported by issuing the command `vlist -u - MACHINE-ID'.

--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).

Important notes

Support for detaching network interfaces from running virtual machines may still be buggy. In particular, in some cases it may not be possible to reattach a previously detached network interface.

Due to the mechanism by which they are configured, network interfaces attached by using this command are not shown by the vlist command, even when requesting complete details about the virtual machine.
As a side effect of this, virtual hubs (collision domains) started by vconfig are not automatically stopped when all the connected machines are shut down. In order to do this, you should use the vclean command with the option -H (see vclean(1)).

An important difference with respect to attaching interfaces with vstart (see vstart(1)) is that, when using ``tap'' collision domains, the configuration of the virtual machine is not automatically updated. In particular, assume that interface eth0 has been set up using vconfig with the following option:

--eth0=tap,TAP-ADDRESS,GUEST-ADDRESS

After doing so, the following operations must be performed inside the virtual machine in order to make the interface operational:

1)

Interface eth0 must be assigned IP address GUEST-ADDRESS. You can do this by using the following command:

ifconfig eth0 GUEST-ADDRESS up

Notice that vconfig does not consider the GUEST-ADDRESS parameter, even if the command syntax requires it. Hence, you are free to use any IP address in configuring interface eth0 (provided that it is on the same (sub)network as TAP-ADDRESS). Nevertheless, it is a good rule to be coherent with the GUEST-ADDRESS provided on the vconfig command line.

2)

A default route must be configured to point to the host side of the ``tap'' interface. This can be achieved by issuing the following command:

route add default gw TAP-ADDRESS dev eth0

Once this is done, the interface is ready for use.

Please make sure you run `vclean -H' (see vclean(1)) when a ``tap'' collision domain is no more used. Not doing so may result in the impossibility to correctly configure new ``tap'' collision domains. For example, this may prevent from correctly setting the TAP-ADDRESS for a new ``tap'' domain.

ENVIRONMENT VARIABLES

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

Apart from this, vconfig supports no other environment variables.

EXAMPLES

vconfig --eth0=A pc1
Equip virtual machine pc1 with a new interface (eth0) which is attached to the virtual collision domain A.: vconfig --eth0=A pc1
vconfig --eth1=tap,10.0.0.1,10.0.0.2 -u foo pc2
Configure a new interface (eth1) on virtual machine pc2 owned by user foo. The host side of the interface will be automatically configured to have IP address 10.0.0.1. The interface inside the virtual machine will have to be configured by issuing the following commands:

ifconfig eth1 10.0.0.2 up route add default gw 10.0.0.1 dev eth1

Running this example requires administrative privileges. The vconfig command will take care of asking you for the root 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).: vconfig --eth1=tap,10.0.0.1,10.0.0.2 -u foo pc2

AUTHOR

vconfig 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.

Index

NAME

SYNOPSIS

DESCRIPTION

Important notes

ENVIRONMENT VARIABLES

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