.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "VIRT-SANDBOX.C 1"
.TH VIRT-SANDBOX.C 1 "2017-05-28" "libvirt-sandbox-0.6.1" "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
virt\-sandbox \- Run cmd under a virtual machine sandbox
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
virt-sandbox [\s-1OPTIONS...\s0] \s-1COMMAND\s0
.PP
virt-sandbox [\s-1OPTIONS...\s0] \*(-- \s-1COMMAND\s0 [\s-1CMDARG1\s0 [\s-1CMDARG2\s0 [...]]]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Run the \f(CW\*(C`cmd\*(C'\fR  application within a tightly confined virtual machine. The
default sandbox domain only allows applications the ability to read and
write stdin, stdout and any other file descriptors handed to it. It is
not allowed to open any other files.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-c \s-1URI\s0\fR, \fB\-\-connect=URI\fR" 8
.IX Item "-c URI, --connect=URI"
Set the libvirt connection \s-1URI,\s0 defaults to qemu:///session if
omitted. Alternatively the \f(CW\*(C`LIBVIRT_DEFAULT_URI\*(C'\fR environment
variable can be set, or the config file \f(CW\*(C`/etc/libvirt/libvirt.conf\*(C'\fR
can have a default \s-1URI\s0 set.  Currently only the \s-1QEMU\s0 and \s-1LXC\s0 drivers
are supported.
.IP "\fB\-n \s-1NAME\s0\fR, \fB\-\-name=NAME\fR" 8
.IX Item "-n NAME, --name=NAME"
Set the unique name for the sandbox. This defaults to \fBsandbox\fR
but this will need to be changed if more than one sandbox is to
be run concurrently. This is used as the name of the libvirt
virtual machine or container.
.IP "\fB\-r \s-1DIR\s0\fR, \fB\-\-root \s-1DIR\s0\fR" 8
.IX Item "-r DIR, --root DIR"
Use \fB\s-1DIR\s0\fR as the root directory of the sandbox, instead of
inheriting the host's root filesystem.
.Sp
\&\s-1NB. \s0\f(CW\*(C`DIR\*(C'\fR must contain a matching install of the libvirt-sandbox
package. This restriction may be lifted in a future version.
.IP "\fB\-\-env key=value\fR" 8
.IX Item "--env key=value"
Sets up a custom environment variable on a running sandbox.
.IP "\fB\-\-disk TYPE:TAGNAME=SOURCE,format=FORMAT\fR" 8
.IX Item "--disk TYPE:TAGNAME=SOURCE,format=FORMAT"
Sets up a disk inside the sandbox by using \fB\s-1SOURCE\s0\fR with a symlink named as \fB\s-1TAGNAME\s0\fR
and type \fB\s-1TYPE\s0\fR and format \fB\s-1FORMAT\s0\fR. Example: file:cache=/var/lib/sandbox/demo/tmp.qcow2,format=qcow2
Format is an optional parameter.
.RS 8
.IP "\fB\s-1TYPE\s0\fR" 4
.IX Item "TYPE"
Type parameter can be set to \*(L"file\*(R".
.IP "\fB\s-1TAGNAME\s0\fR" 4
.IX Item "TAGNAME"
\&\s-1TAGNAME\s0 will be created under /dev/disk/by\-tag/TAGNAME. It will be linked to the device under /dev
.IP "\fB\s-1SOURCE\s0\fR" 4
.IX Item "SOURCE"
Source parameter needs to point a file which must be a one of the valid domain disk formats supported by qemu.
.IP "\fB\s-1FORMAT\s0\fR" 4
.IX Item "FORMAT"
Format parameter must be set to the same disk format as the file passed on source parameter.
This parameter is optional and the format can be guessed from the image extension
.RE
.RS 8
.RE
.IP "\fB\-m TYPE:DST=SRC\fR, \fB\-\-mount TYPE:DST=SRC\fR" 8
.IX Item "-m TYPE:DST=SRC, --mount TYPE:DST=SRC"
Sets up a mount inside the sandbox at \fB\s-1DST\s0\fR backed by \fB\s-1SRC\s0\fR. The
meaning of \fB\s-1SRC\s0\fR depends on the value of \f(CW\*(C`TYPE\*(C'\fR specified:
.RS 8
.IP "\fBhost-bind\fR" 4
.IX Item "host-bind"
If \fB\s-1TYPE\s0\fR is \fBhost-bind\fR, then \fB\s-1SRC\s0\fR is interpreted as the path
to a directory on the host filesystem. If \f(CW\*(C`SRC\*(C'\fR is the empty string,
then a temporary (empty) directory is created on the host before
starting the sandbox and deleted afterwards. The \f(CW\*(C`\-\-include\*(C'\fR option
is useful for populating these temporary directories with copies of host
files.
.IP "\fBhost-image\fR" 4
.IX Item "host-image"
If \fB\s-1TYPE\s0\fR is \fBhost-image\fR, then \fB\s-1SRC\s0\fR is interpreted as the path
to a disk image file on the host filesystem. The image should be
formatted with a filesystem that can be auto-detected by the sandbox,
such as \fBext3\fR, \fBext4\fR, etc. The disk image itself should be a raw
file, not qcow2 or any other special format
.IP "\fBguest-bind\fR" 4
.IX Item "guest-bind"
If \fB\s-1TYPE\s0\fR is \fBguest-bind\fR, then \fB\s-1SRC\s0\fR is interpreted as the path
to another directory in the container filesystem.
.IP "\fBram\fR" 4
.IX Item "ram"
If \fB\s-1TYPE\s0\fR is \fBram\fR, then \fB\s-1SRC\s0\fR is interpreted as specifying the
size of the \s-1RAM\s0 disk in bytes. The suffix \fBK\fR, \fBKiB\fR, \fBM\fR,
\&\fBMiB\fR, \fBG\fR, \fBGiB\fR can used to alter the units from bytes to a
coarser level.
.RE
.RS 8
.Sp
Some examples
.Sp
.Vb 4
\& \-m host\-bind:/tmp=/var/lib/sandbox/demo/tmp
\& \-m host\-image:/=/var/lib/sandbox/demo.img
\& \-m guest\-bind:/home=/tmp/home
\& \-m ram:/tmp=500M
.Ve
.RE
.IP "\fB\-I HOST-PATH\fR, \fB\-\-includefile=HOST\-PATH\fR" 8
.IX Item "-I HOST-PATH, --includefile=HOST-PATH"
Copy all files listed in inputfile into the
appropriate temporary sandbox directories.
.IP "\fB\-N NETWORK-OPTIONS\fR, \fB\-\-network NETWORK-OPTIONS\fR" 8
.IX Item "-N NETWORK-OPTIONS, --network NETWORK-OPTIONS"
Add a network interface to the sandbox. NETWORK-OPTIONS is a set of
key=val pairs, separated by commas. The following options are valid
.RS 8
.IP "dhcp" 4
.IX Item "dhcp"
Configure the network interface using dhcp. This key takes no value.
No other keys may be specified. eg
.Sp
.Vb 2
\&  \-N dhcp,source=default
\&  \-\-network dhcp,source=lan
.Ve
.Sp
where 'source' is the name of any libvirt virtual network.
.IP "source=NETWORK" 4
.IX Item "source=NETWORK"
Set the name of the network to connect the interface to. \f(CW\*(C`NETWORK\*(C'\fR
is the name of any libvirt virtual network. See also \fBvirsh net-list\fR
.IP "mac=NN:NN:NN:NN:NN:NN" 4
.IX Item "mac=NN:NN:NN:NN:NN:NN"
Set the \s-1MAC\s0 address of the network interface, where each \s-1NN\s0 is a pair
of hex digits.
.IP "address=IP\-ADDRESS/PREFIX%BROADCAST" 4
.IX Item "address=IP-ADDRESS/PREFIX%BROADCAST"
Configure the network interface with the static IPv4 or IPv6 address
\&\fBIP-ADDRESS\fR. The \fB\s-1PREFIX\s0\fR value is the length of the network
prefix in \fBIP-ADDRESS\fR. The optional \fB\s-1BROADCAST\s0\fR parameter
specifies the broadcast address. Some examples
.Sp
.Vb 3
\&  address=192.168.122.1/24
\&  address=192.168.122.1/24%192.168.122.255
\&  address=2001:212::204:2/64
.Ve
.IP "route=IP\-NETWORK/PREFIX%GATEWAY" 4
.IX Item "route=IP-NETWORK/PREFIX%GATEWAY"
Configure the network interface with the static IPv4 or IPv6 route
\&\fBIP-NETWORK\fR. The \fB\s-1PREFIX\s0\fR value is the length of the network
prefix in \fBIP-NETWORK\fR. The \fB\s-1GATEWAY\s0\fR parameter specifies the
address of the gateway for the route. Some examples
.Sp
.Vb 1
\&  route=192.168.122.255/24%192.168.1.1
.Ve
.RE
.RS 8
.RE
.IP "\fB\-s SECURITY-OPTIONS\fR, \fB\-\-security=SECURITY\-OPTIONS\fR" 8
.IX Item "-s SECURITY-OPTIONS, --security=SECURITY-OPTIONS"
Use alternative security options. SECURITY-OPTIONS is a set of key=val pairs,
separated by commas. The following options are valid for SELinux
.RS 8
.IP "dynamic" 4
.IX Item "dynamic"
Dynamically allocate an SELinux label, using the default base context.
The default base context is system_u:system_r:svirt_lxc_net_t:s0 for \s-1LXC,\s0
system_u:system_r:svirt_t:s0 for \s-1KVM,\s0 system_u:system_r:svirt_tcg_t:s0
for \s-1QEMU.\s0
.IP "dynamic,label=USER:ROLE:TYPE:LEVEL" 4
.IX Item "dynamic,label=USER:ROLE:TYPE:LEVEL"
Dynamically allocate an SELinux label, using the base context
\&\s-1USER:ROLE:TYPE:LEVEL,\s0 instead of the default base context.
.IP "static,label=USER:ROLE:TYPE:LEVEL" 4
.IX Item "static,label=USER:ROLE:TYPE:LEVEL"
To set a completely static label. For example,
static,label=system_u:system_r:svirt_t:s0:c412,c355
.IP "inherit" 4
.IX Item "inherit"
Inherit the context from the process that is executing virt-sandbox.
.RE
.RS 8
.RE
.IP "\fB\-\-kernver=VERSION\fR" 8
.IX Item "--kernver=VERSION"
Specify the kernel version to run for machine based sandboxes. If
omitted, defaults to match the current running host version.
.IP "\fB\-\-kernpath=FILE\-PATH\fR" 8
.IX Item "--kernpath=FILE-PATH"
Specify the path to the kernel binary. If omitted, defaults
to \f(CW\*(C`/boot/vmlinuz\-$KERNEL\-VERSION\*(C'\fR.
.IP "\fB\-\-kmodpath=DIR\-PATH\fR" 8
.IX Item "--kmodpath=DIR-PATH"
Specify the path to the kernel module base directory. If omitted, defaults
to \f(CW\*(C`/lib/modules\*(C'\fR. The suffix \f(CW\*(C`$KERNEL\-VERSION/kernel\*(C'\fR will be appended
to this path to locate the modules.
.IP "\fB\-p\fR, \fB\-\-privileged\fR" 8
.IX Item "-p, --privileged"
Retain root privileges inside the sandbox, rather than dropping privileges
to match the current user identity.
.IP "\fB\-S \s-1USER\s0\fR, \fB\-\-switchto=USER\fR" 8
.IX Item "-S USER, --switchto=USER"
Switch to the given user inside the sandbox and setup \f(CW$HOME\fR
accordingly.
.IP "\fB\-l\fR, \fB\-\-shell\fR" 8
.IX Item "-l, --shell"
Launch an interactive shell on a secondary console device
.IP "\fB\-V\fR, \fB\-\-version\fR" 8
.IX Item "-V, --version"
Display the version number and exit
.IP "\fB\-v\fR, \fB\-\-verbose\fR" 8
.IX Item "-v, --verbose"
Display verbose progress information
.IP "\fB\-d\fR, \fB\-\-debug\fR" 8
.IX Item "-d, --debug"
Display debugging information
.IP "\fB\-h\fR, \fB\-\-help\fR" 8
.IX Item "-h, --help"
Display help information
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Run an interactive shell under \s-1LXC,\s0 replace \f(CW$HOME\fR with the contents
of \f(CW$HOME\fR/scratch
.PP
.Vb 4
\&  # mkdir $HOME/scratch
\&  # echo "hello" > $HOME/scratch/foo
\&  # echo "sandbox" > $HOME/scratch/bar
\&  # virt\-sandbox \-c lxc:/// \-m host\-bind:$HOME=$HOME/scratch \-i $HOME/scratch/foo \-i $HOME/scratch/bar /bin/sh
.Ve
.PP
Convert an \s-1OGG\s0 file to \s-1WAV\s0 inside \s-1QEMU\s0
.PP
.Vb 1
\&  # virt\-sandbox \-c qemu:///session  \-\- /usr/bin/oggdec \-Q \-o \- \- < somefile.ogg > somefile.wav
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CWsandbox(8)\fR, \f(CWvirsh(1)\fR
.SH "AUTHORS"
.IX Header "AUTHORS"
Daniel P. Berrange <dan@berrange.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2011 Daniel P. Berrange <dan@berrange.com>
Copyright (C) 2011\-2012 Red Hat, Inc.
.SH "LICENSE"
.IX Header "LICENSE"
virt-sandbox is distributed under the terms of the \s-1GNU LGPL\s0 v2+.
This is free software; see the source for copying conditions.
There is \s-1NO\s0 warranty; not even for \s-1MERCHANTABILITY\s0 or \s-1FITNESS
FOR A PARTICULAR PURPOSE\s0