NAME

vconf - attach network interfaces to running netkit virtual machines

SYNOPSIS

vconf [options] MACHINE-ID

DESCRIPTION

The vconf 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 vconf.

-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 vconf to only work on virtual machines owned by USERNAME. By default, vconf only allows to attach interfaces to virtual machines started by the current user (i.e., the one who launched vconf). 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, vconf 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 vconf 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 vconf 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 vconf 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 vconf 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, vconf supports no other environment variables.

EXAMPLES

vconf --eth0=A pc1

Equip virtual machine pc1 with a new interface (eth0) which is attached to the virtual collision domain A.

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

SEE ALSO

vclean(1), vcrash(1), vhalt(1), vlist(1), vstart(1), netkit.conf(5).

AUTHOR

vconf script: Massimo Rimondini
This man page: Massimo Rimondini

REPORTING BUGS

Report bugs to the Github issues page: https://github.com/netkit-jh/netkit-jh-build/issues

Please follow the recommended templates when reporting bugs.