.TH VDENS 1 "November 26, 2016" "VirtualSquare Labs"
.SH NAME
vdens \- create a user namespace connected to a vde network
.SH SYNOPSIS
.B vdens
[ options ]
[
.I vde_network
[
.I command
[
.I args
]
]
]

.B vdens
.B -m
[ options ]
.I vde_network
[
.I vde_network ...
]
[
.B --
.I command
[
.I args
]
]

.B vdens
.B --multi
[ options ]
.I vde_network
[
.I vde_network ...
]
[
.B --
.I command
[
.I args
]
]

.SH DESCRIPTION

vdens creates a user namespace with a private network namespace.

Vdens launches the command indicated as a parameter ($SHELL if omitted) in a private network namespace.

If the vde_network parameter is present (and it does not match one of the
strings "-" or "no") the virtual private network namespace will have a virtual
interface connected to the specified vde network. 

Vdens grants the capabilities CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_ADMIN and CAP_NET_RAW to the command to
permit the configuration of the virtual interface. The scope of these
capabilities is limited to the user namespace created by vdens. Once the network has been
configured, the capabilities can be dropped (e.g. using csdrop(1)) in order to
increase the security (obeying to the principle of least privilege).

.SH OPTIONS
OPTIONS
.I vdens
accepts the following options.

.TP
\fB\-m
.TQ
\fB\-\-multi
connect the vde namespace to one or more vde networks. A virtual interface is defined
for each \fIvde_network\fR: \fBvde0\fR is connected to the first \fIvde_network\fR,
\fBvde1\fR is connected to the second and so on. (It is possible to use a different
prefix for the interface names instead of "vde", see -i or --iface below).

.TP
\fB\-i \fI interface_prefix
.TQ
\fB\-\-iface \fI interface_prefix
define the prefix of the interface name. For example use \fB--iface eth\fR to
name the interfaces "eth0", "eth1", etc.  (the default value is "vde")

.TP
\fB\-R \fI ip_addr(s)
.TQ
\fB\-\-resolvaddr \fI ip_addr(s)
define the address (or addresses) of the domain name servers for the namespace.
(multiple IPv4 or IPv6 addresses can be separated by commas, e.g. "-R 9.9.9.9,9.9.8.8")

.TP
\fB\-r \fI pathname
.TQ
\fB\-\-resolvconf \fI pathname
define the pathname of the file which will appear as /etc/config.sys in the user namespace.
(it is ignored if used together with \fB\-R\fR or \fB\-\-resolvaddr\fR) 

.TP
\fB\-s
.TQ
\fB\-\-sysadm
grant also CAP_SYS_ADMIN in the namespace so that it is possible to bind mount files and
directories.

.TP
\fB\-c
.TQ
\fB\-\-clone
Use clone(2) to create the private network namespace. Vdens needs one more thread to manage
the vde communication.

.TP
\fB\-u
.TQ
\fB\-\-unshare
Use unshare(2) to create the private network namespace. It may not work if the vde plugin in use
is multithreaded (e.g. slirp). If neither -c/--clone nor -u/--unshare is set, vdens tries
unshare first and then it uses clone if unshare fails. (If both are set vdens uses clone).

.SH ENVIRONMENT VARIABLES
.TP
\fBVDE_RESOLVCONF
define the default value for the \fB\-\-resolvconf \fR option

.TP
\fBVDE_RESOLVADDR
define the default value for the \fB\-\-resolvaddr \fR option

.SH NOTES
Use of user namespaces requires a kernel that is configured with the CONFIG_USER_NS option.
In some distributions (e.g. Debian) user namespaces must be enabled by writing 1 to
/proc/sys/kernel/unprivileged_userns_clone.
.SH SEE ALSO
\fBvde_plug\fR(1),
\fBcadrop\fR(1),
\fBcado\fR(1),
\fBcapabilities\fR(7)
.SH AUTHORS
Renzo Davoli <renzo@cs.unibo.it>, Davide Berardi <berardi.dav@gmail.com>.