1VIRT-SANDBOX.C(1) Virtualization Support VIRT-SANDBOX.C(1)
2
6 virt-sandbox - Run cmd under a virtual machine sandbox
7
9 virt-sandbox [OPTIONS...] COMMAND
10 virt-sandbox [OPTIONS...] -- COMMAND [CMDARG1 [CMDARG2 [...]]]
12
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
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 -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 -r DIR, --root DIR
34 Use DIR as the root directory of the sandbox, instead of
35 inheriting the host's root filesystem.
36 NB. "DIR" must contain a matching install of the libvirt-
38 sandbox package. This restriction may be lifted in a future
39 version.
40 --env key=value
42 Sets up a custom environment variable on a running sandbox.
43 --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 TYPE
52 Type parameter can be set to "file".
53 TAGNAME
55 TAGNAME will be created under /dev/disk/by-tag/TAGNAME. It
56 will be linked to the device under /dev
57 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 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 -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 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 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 guest-bind
89 If TYPE is guest-bind, then SRC is interpreted as the path
90 to another directory in the container filesystem.
91 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 Some examples
98 -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 -I HOST-PATH, --includefile=HOST-PATH
105 Copy all files listed in inputfile into the appropriate
106 temporary sandbox directories.
107 -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 dhcp
114 Configure the network interface using dhcp. This key takes
115 no value. No other keys may be specified. eg
116 -N dhcp,source=default
118 --network dhcp,source=lan
119 where 'source' is the name of any libvirt virtual network.
121 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 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 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 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 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 route=192.168.122.255/24%192.168.1.1
149 -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 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 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 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 inherit
172 Inherit the context from the process that is executing
173 virt-sandbox.
174 --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 --kernpath=FILE-PATH
180 Specify the path to the kernel binary. If omitted, defaults to
181 "/boot/vmlinuz-$KERNEL-VERSION".
182 --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 -p, --privileged
190 Retain root privileges inside the sandbox, rather than dropping
191 privileges to match the current user identity.
192 -S USER, --switchto=USER
194 Switch to the given user inside the sandbox and setup $HOME
195 accordingly.
196 -l, --shell
198 Launch an interactive shell on a secondary console device
199 -V, --version
201 Display the version number and exit
202 -v, --verbose
204 Display verbose progress information
205 -d, --debug
207 Display debugging information
208 -h, --help
210 Display help information
211
213 Run an interactive shell under LXC, replace $HOME with the contents of
214 $HOME/scratch
215 # 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 Convert an OGG file to WAV inside QEMU
222 # virt-sandbox -c qemu:///session -- /usr/bin/oggdec -Q -o - - < somefile.ogg > somefile.wav
224
226 sandbox(8), virsh(1)
227
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
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
240libvirt-sandbox-0.8.0 2023-01-19 VIRT-SANDBOX.C(1)