virt-sandbox - Run cmd under a virtual machine sandbox
virt-sandbox [OPTIONS...] COMMAND
virt-sandbox [OPTIONS...] -- COMMAND [CMDARG1 [CMDARG2 [...]]]
Run the "cmd" 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.
- -c URI,
--connect=URI
- Set the libvirt connection URI, defaults to qemu:///session if omitted.
Alternatively the "LIBVIRT_DEFAULT_URI"
environment variable can be set, or the config file
"/etc/libvirt/libvirt.conf" can have a
default URI set. Currently only the QEMU and LXC drivers are
supported.
- -n NAME,
--name=NAME
- Set the unique name for the sandbox. This defaults to sandbox 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.
- -r DIR, --root
DIR
- Use DIR as the root directory of the sandbox, instead of inheriting
the host's root filesystem.
NB. "DIR" must contain a
matching install of the libvirt-sandbox package. This restriction may be
lifted in a future version.
- --env key=value
- Sets up a custom environment variable on a running sandbox.
- --disk
TYPE:TAGNAME=SOURCE,format=FORMAT
- Sets up a disk inside the sandbox by using SOURCE with a symlink
named as TAGNAME and type TYPE and format FORMAT.
Example: file:cache=/var/lib/sandbox/demo/tmp.qcow2,format=qcow2 Format is
an optional parameter.
- TYPE
- Type parameter can be set to "file".
- TAGNAME
- TAGNAME will be created under /dev/disk/by-tag/TAGNAME. It will be linked
to the device under /dev
- SOURCE
- Source parameter needs to point a file which must be a one of the valid
domain disk formats supported by qemu.
- 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
- -m TYPE:DST=SRC, --mount
TYPE:DST=SRC
- Sets up a mount inside the sandbox at DST backed by SRC. The
meaning of SRC depends on the value of
"TYPE" specified:
- host-bind
- If TYPE is host-bind, then SRC is interpreted as the
path to a directory on the host filesystem. If
"SRC" is the empty string, then a
temporary (empty) directory is created on the host before starting the
sandbox and deleted afterwards. The
"--include" option is useful for
populating these temporary directories with copies of host files.
- host-image
- If TYPE is host-image, then SRC 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 ext3, ext4, etc. The disk image itself should be a raw
file, not qcow2 or any other special format
- guest-bind
- If TYPE is guest-bind, then SRC is interpreted as the
path to another directory in the container filesystem.
- ram
- If TYPE is ram, then SRC is interpreted as specifying
the size of the RAM disk in bytes. The suffix K, KiB,
M, MiB, G, GiB can used to alter the units
from bytes to a coarser level.
Some examples
-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
- -I HOST-PATH,
--includefile=HOST-PATH
- Copy all files listed in inputfile into the appropriate temporary sandbox
directories.
- -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
- dhcp
- Configure the network interface using dhcp. This key takes no value. No
other keys may be specified. eg
-N dhcp,source=default
--network dhcp,source=lan
where 'source' is the name of any libvirt virtual network.
- source=NETWORK
- Set the name of the network to connect the interface to.
"NETWORK" is the name of any libvirt
virtual network. See also virsh net-list
- mac=NN:NN:NN:NN:NN:NN
- Set the MAC address of the network interface, where each NN is a pair of
hex digits.
- address=IP-ADDRESS/PREFIX%BROADCAST
- Configure the network interface with the static IPv4 or IPv6 address
IP-ADDRESS. The PREFIX value is the length of the network
prefix in IP-ADDRESS. The optional BROADCAST parameter
specifies the broadcast address. Some examples
address=192.168.122.1/24
address=192.168.122.1/24%192.168.122.255
address=2001:212::204:2/64
- route=IP-NETWORK/PREFIX%GATEWAY
- Configure the network interface with the static IPv4 or IPv6 route
IP-NETWORK. The PREFIX value is the length of the network
prefix in IP-NETWORK. The GATEWAY parameter specifies the
address of the gateway for the route. Some examples
route=192.168.122.255/24%192.168.1.1
- -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
- 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 LXC,
system_u:system_r:svirt_t:s0 for KVM, system_u:system_r:svirt_tcg_t:s0 for
QEMU.
- dynamic,label=USER:ROLE:TYPE:LEVEL
- Dynamically allocate an SELinux label, using the base context
USER:ROLE:TYPE:LEVEL, instead of the default base context.
- 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
- inherit
- Inherit the context from the process that is executing virt-sandbox.
- --kernver=VERSION
- Specify the kernel version to run for machine based sandboxes. If omitted,
defaults to match the current running host version.
- --kernpath=FILE-PATH
- Specify the path to the kernel binary. If omitted, defaults to
"/boot/vmlinuz-$KERNEL-VERSION".
- --kmodpath=DIR-PATH
- Specify the path to the kernel module base directory. If omitted, defaults
to "/lib/modules". The suffix
"$KERNEL-VERSION/kernel" will be
appended to this path to locate the modules.
- -p,
--privileged
- Retain root privileges inside the sandbox, rather than dropping privileges
to match the current user identity.
- -S USER,
--switchto=USER
- Switch to the given user inside the sandbox and setup
$HOME accordingly.
- -l, --shell
- Launch an interactive shell on a secondary console device
- -V, --version
- Display the version number and exit
- -v, --verbose
- Display verbose progress information
- -d, --debug
- Display debugging information
- -h, --help
- Display help information
Run an interactive shell under LXC, replace
$HOME with the contents of
$HOME/scratch
# 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
Convert an OGG file to WAV inside QEMU
# virt-sandbox -c qemu:///session -- /usr/bin/oggdec -Q -o - - < somefile.ogg > somefile.wav
Daniel P. Berrange <dan@berrange.com>
Copyright (C) 2011 Daniel P. Berrange <dan@berrange.com>
Copyright (C) 2011-2012 Red Hat, Inc.
virt-sandbox is distributed under the terms of the GNU LGPL v2+.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE