1VIRT-SANDBOX.C(1)           Virtualization Support           VIRT-SANDBOX.C(1)
2
3
4

NAME

6       virt-sandbox - Run cmd under a virtual machine sandbox
7

SYNOPSIS

9       virt-sandbox [OPTIONS...] COMMAND
10
11       virt-sandbox [OPTIONS...] -- COMMAND [CMDARG1 [CMDARG2 [...]]]
12

DESCRIPTION

14       Run the "cmd"  application within a tightly confined virtual machine.
15       The default sandbox domain only allows applications the ability to read
16       and write stdin, stdout and any other file descriptors handed to it. It
17       is not allowed to open any other files.
18

OPTIONS

20       -c URI, --connect=URI
21               Set the libvirt connection URI, defaults to qemu:///session if
22               omitted. Alternatively the "LIBVIRT_DEFAULT_URI" environment
23               variable can be set, or the config file
24               "/etc/libvirt/libvirt.conf" can have a default URI set.
25               Currently only the QEMU and LXC drivers are supported.
26
27       -n NAME, --name=NAME
28               Set the unique name for the sandbox. This defaults to sandbox
29               but this will need to be changed if more than one sandbox is to
30               be run concurrently. This is used as the name of the libvirt
31               virtual machine or container.
32
33       -r DIR, --root DIR
34               Use DIR as the root directory of the sandbox, instead of
35               inheriting the host's root filesystem.
36
37               NB. "DIR" must contain a matching install of the libvirt-
38               sandbox package. This restriction may be lifted in a future
39               version.
40
41       --env key=value
42               Sets up a custom environment variable on a running sandbox.
43
44       --disk TYPE:TAGNAME=SOURCE,format=FORMAT
45               Sets up a disk inside the sandbox by using SOURCE with a
46               symlink named as TAGNAME and type TYPE and format FORMAT.
47               Example:
48               file:cache=/var/lib/sandbox/demo/tmp.qcow2,format=qcow2 Format
49               is an optional parameter.
50
51               TYPE
52                   Type parameter can be set to "file".
53
54               TAGNAME
55                   TAGNAME will be created under /dev/disk/by-tag/TAGNAME. It
56                   will be linked to the device under /dev
57
58               SOURCE
59                   Source parameter needs to point a file which must be a one
60                   of the valid domain disk formats supported by qemu.
61
62               FORMAT
63                   Format parameter must be set to the same disk format as the
64                   file passed on source parameter.  This parameter is
65                   optional and the format can be guessed from the image
66                   extension
67
68       -m TYPE:DST=SRC, --mount TYPE:DST=SRC
69               Sets up a mount inside the sandbox at DST backed by SRC. The
70               meaning of SRC depends on the value of "TYPE" specified:
71
72               host-bind
73                   If TYPE is host-bind, then SRC is interpreted as the path
74                   to a directory on the host filesystem. If "SRC" is the
75                   empty string, then a temporary (empty) directory is created
76                   on the host before starting the sandbox and deleted
77                   afterwards. The "--include" option is useful for populating
78                   these temporary directories with copies of host files.
79
80               host-image
81                   If TYPE is host-image, then SRC is interpreted as the path
82                   to a disk image file on the host filesystem. The image
83                   should be formatted with a filesystem that can be auto-
84                   detected by the sandbox, such as ext3, ext4, etc. The disk
85                   image itself should be a raw file, not qcow2 or any other
86                   special format
87
88               guest-bind
89                   If TYPE is guest-bind, then SRC is interpreted as the path
90                   to another directory in the container filesystem.
91
92               ram If TYPE is ram, then SRC is interpreted as specifying the
93                   size of the RAM disk in bytes. The suffix K, KiB, M, MiB,
94                   G, GiB can used to alter the units from bytes to a coarser
95                   level.
96
97               Some examples
98
99                -m host-bind:/tmp=/var/lib/sandbox/demo/tmp
100                -m host-image:/=/var/lib/sandbox/demo.img
101                -m guest-bind:/home=/tmp/home
102                -m ram:/tmp=500M
103
104       -I HOST-PATH, --includefile=HOST-PATH
105               Copy all files listed in inputfile into the appropriate
106               temporary sandbox directories.
107
108       -N NETWORK-OPTIONS, --network NETWORK-OPTIONS
109               Add a network interface to the sandbox. NETWORK-OPTIONS is a
110               set of key=val pairs, separated by commas. The following
111               options are valid
112
113               dhcp
114                   Configure the network interface using dhcp. This key takes
115                   no value.  No other keys may be specified. eg
116
117                     -N dhcp,source=default
118                     --network dhcp,source=lan
119
120                   where 'source' is the name of any libvirt virtual network.
121
122               source=NETWORK
123                   Set the name of the network to connect the interface to.
124                   "NETWORK" is the name of any libvirt virtual network. See
125                   also virsh net-list
126
127               mac=NN:NN:NN:NN:NN:NN
128                   Set the MAC address of the network interface, where each NN
129                   is a pair of hex digits.
130
131               address=IP-ADDRESS/PREFIX%BROADCAST
132                   Configure the network interface with the static IPv4 or
133                   IPv6 address IP-ADDRESS. The PREFIX value is the length of
134                   the network prefix in IP-ADDRESS. The optional BROADCAST
135                   parameter specifies the broadcast address. Some examples
136
137                     address=192.168.122.1/24
138                     address=192.168.122.1/24%192.168.122.255
139                     address=2001:212::204:2/64
140
141               route=IP-NETWORK/PREFIX%GATEWAY
142                   Configure the network interface with the static IPv4 or
143                   IPv6 route IP-NETWORK. The PREFIX value is the length of
144                   the network prefix in IP-NETWORK. The GATEWAY parameter
145                   specifies the address of the gateway for the route. Some
146                   examples
147
148                     route=192.168.122.255/24%192.168.1.1
149
150       -s SECURITY-OPTIONS, --security=SECURITY-OPTIONS
151               Use alternative security options. SECURITY-OPTIONS is a set of
152               key=val pairs, separated by commas. The following options are
153               valid for SELinux
154
155               dynamic
156                   Dynamically allocate an SELinux label, using the default
157                   base context.  The default base context is
158                   system_u:system_r:svirt_lxc_net_t:s0 for LXC,
159                   system_u:system_r:svirt_t:s0 for KVM,
160                   system_u:system_r:svirt_tcg_t:s0 for QEMU.
161
162               dynamic,label=USER:ROLE:TYPE:LEVEL
163                   Dynamically allocate an SELinux label, using the base
164                   context USER:ROLE:TYPE:LEVEL, instead of the default base
165                   context.
166
167               static,label=USER:ROLE:TYPE:LEVEL
168                   To set a completely static label. For example,
169                   static,label=system_u:system_r:svirt_t:s0:c412,c355
170
171               inherit
172                   Inherit the context from the process that is executing
173                   virt-sandbox.
174
175       --kernver=VERSION
176               Specify the kernel version to run for machine based sandboxes.
177               If omitted, defaults to match the current running host version.
178
179       --kernpath=FILE-PATH
180               Specify the path to the kernel binary. If omitted, defaults to
181               "/boot/vmlinuz-$KERNEL-VERSION".
182
183       --kmodpath=DIR-PATH
184               Specify the path to the kernel module base directory. If
185               omitted, defaults to "/lib/modules". The suffix
186               "$KERNEL-VERSION/kernel" will be appended to this path to
187               locate the modules.
188
189       -p, --privileged
190               Retain root privileges inside the sandbox, rather than dropping
191               privileges to match the current user identity.
192
193       -S USER, --switchto=USER
194               Switch to the given user inside the sandbox and setup $HOME
195               accordingly.
196
197       -l, --shell
198               Launch an interactive shell on a secondary console device
199
200       -V, --version
201               Display the version number and exit
202
203       -v, --verbose
204               Display verbose progress information
205
206       -d, --debug
207               Display debugging information
208
209       -h, --help
210               Display help information
211

EXAMPLES

213       Run an interactive shell under LXC, replace $HOME with the contents of
214       $HOME/scratch
215
216         # mkdir $HOME/scratch
217         # echo "hello" > $HOME/scratch/foo
218         # echo "sandbox" > $HOME/scratch/bar
219         # virt-sandbox -c lxc:/// -m host-bind:$HOME=$HOME/scratch -i $HOME/scratch/foo -i $HOME/scratch/bar /bin/sh
220
221       Convert an OGG file to WAV inside QEMU
222
223         # virt-sandbox -c qemu:///session  -- /usr/bin/oggdec -Q -o - - < somefile.ogg > somefile.wav
224

SEE ALSO

226       sandbox(8), virsh(1)
227

AUTHORS

229       Daniel P. Berrange <dan@berrange.com>
230
232       Copyright (C) 2011 Daniel P. Berrange <dan@berrange.com> Copyright (C)
233       2011-2012 Red Hat, Inc.
234

LICENSE

236       virt-sandbox is distributed under the terms of the GNU LGPL v2+.  This
237       is free software; see the source for copying conditions.  There is NO
238       warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
239       PURPOSE
240
241
242
243libvirt-sandbox-0.8.0             2023-01-19                 VIRT-SANDBOX.C(1)
Impressum