=head1 NAME

virt-sandbox-service create - Create a Security container

=head1 SYNOPSIS

  virt-sandbox-service [-c URI] create [-h] [-C] [-f FILE_TYPE]
                                   [--homedir HOMEDIR] [-G GID] [-i IMAGESIZE]
                                   [[-m TYPE:DST=SRC ] ...]
                                   [-N NETWORK] [-p PATH] [-s SECURITY]
                                   [[-u UNITFILES] ...] [--username USERNAME]
                                   [-U UID] [[-P package] ... ]
                                   NAME -- COMMAND [ARG1 [ARG2...]]

=head1 DESCRIPTION

virt-sandbox-service is used to manage secure sandboxed system services.
These applications will be launched via libvirt and run within a virtualization
technology such as LinuX Containers (LXC), or optionally QEMU/KVM. The
container / virtual machines will be secured by SELinux and resource
separated using cgroups.

The create command can setup a sandbox for running one or more systemd unit files.
It can also setup a sandbox for running a command in an GenericContainer.
Specify a unit file to create the SystemdContainer and the command to create an
GenericContainer.

=head1 OPTIONS

=over 4

=item B<-h>, B<--help>

Display help message

=item B<-c URI>, B<--connect URI>

The connection URI for the hypervisor (currently only LXC URIs are
supported).

=item B<-u UNIT_FILE>, B<--unitfile UNIT_FILE>

Name of the systemd unit file to be to run within the Systemd Container.
Can be repeated if multiple unit files are required within the sandbox.
Cannot be specified if you are using a COMMAND. If the unit file end
with @, this will be considered as a template, and a instantiated
systemd unit will be created, using the name of the container as a
instance identifier.

=item B<-C>, B<--copy>

Copy content from /etc and /var directories that will be mounted within the container.

=item B<-G GID>, B<--gid GID>

Set login gid to use within the container.

Default: C<Login GID of UID>.

=item B<-f FILETYPE>, B<--filetype FILETYPE>

Set SELinux file type to use within container.

Default: C<svirt_lxc_file_t>.

=item B<-p PATH>, B<--path PATH>

Set path to store container content. NB if this argument is used when creating
a container, the exact same argument must also be used when later cloning or
deleting the container.

Default: C</var/lib/libvirt/filesystems>.

=item B<--homedir HOMEDIR>

Set homedir path to use within container.

Default: C<UID's Homedir>.

=item B<-m TYPE:DST=SRC>, B<--mount TYPE:DST=SRC>

Sets up a mount inside the sandbox at B<DST> backed by B<SRC>. The
meaning of B<SRC> depends on the value of C<TYPE> specified:

=over 4

=item B<host-bind>

If B<TYPE> is B<host-bind>, then B<SRC> is interpreted as the path
to a directory on the host filesystem. If C<SRC> is the empty string,
then a temporary (empty) directory is created on the host before
starting the sandbox and deleted afterwards. The C<--include> option
is useful for populating these temporary directories with copies of host
files.

=item B<host-image>

If B<TYPE> is B<host-image>, then B<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 B<ext3>, B<ext4>, etc. The disk image itself should be a raw
file, not qcow2 or any other special format

=item B<guest-bind>

If B<TYPE> is B<guest-bind>, then B<SRC> is interpreted as the path
to another directory in the container filesystem.

=item B<ram>

If B<TYPE> is B<ram>, then B<SRC> is interpreted as specifying the
size of the RAM disk in bytes. The suffix B<K>, B<KiB>, B<M>,
B<MiB>, B<G>, B<GiB> can used to alter the units from bytes to a
coarser level.

=back

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

=item B<-N NETWORK-OPTIONS>, B<--network NETWORK-OPTIONS>

Add a network interface to the sandbox. By default the sandbox will
only have a loopback interface. This option allows for connectivity
to the LAN in some manner. NETWORK-OPTIONS is a set of
key=val pairs, separated by commas. The following options are valid

=over 4

=item 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.

=item source=NETWORK

Set the name of the network to connect the interface to. C<NETWORK>
is the name of any libvirt virtual network. See also B<virsh net-list>

=item mac=NN:NN:NN:NN:NN:NN

Set the MAC address of the network interface, where each NN is a pair
of hex digits.

=item address=IP-ADDRESS/PREFIX%BROADCAST

Configure the network interface with the static IPv4 or IPv6 address
B<IP-ADDRESS>. The B<PREFIX> value is the length of the network
prefix in B<IP-ADDRESS>. The optional B<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

=item route=IP-NETWORK/PREFIX%GATEWAY

Configure the network interface with the static IPv4 or IPv6 route
B<IP-NETWORK>. The B<PREFIX> value is the length of the network
prefix in B<IP-NETWORK>. The B<GATEWAY> parameter specifies the
address of the gateway for the route. Some examples

  route=192.168.122.255/24%192.168.1.1

=back

=item B<-s SECURITY-OPTIONS>, B<--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

=over 4

=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 LXC,
system_u:system_r:svirt_t:s0 for KVM, system_u:system_r:svirt_tcg_t:s0
for QEMU.

=item 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.

=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

=back

=item B<-i SIZE>, B<--image SIZE>

Create file system image file of this size to store container content.

=item B<-P PACKAGE>, B<--package PACKAGE>

Package(s) to be used within the container.

=item B<-U UID>, B<--uid UID>

Set uid to use within container.

Default: C<CURRENT UID>.

=item B<--username USERNAME>

Set username to use within container.

Default: C<UID's Username>.

=back

=head1 EXAMPLE

Create httpd1 Systemd container

 # virt-sandbox-service create -C -u httpd.service httpd1
 Created container dir /var/lib/libvirt/filesystems/httpd1
 Created sandbox config /etc/libvirt-sandbox/services/httpd1/config/sandbox.cfg
 Created unit file /etc/systemd/system/httpd@httpd1.service

Create foobar1 Generic container

 # virt-sandbox-service create -U 1234 foobar1 -- /usr/bin/foobar -a -b
 Created container dir /var/lib/libvirt/filesystems/foobar1
 Created sandbox config /etc/libvirt-sandbox/services/foobar1/config/sandbox.cfg

=head1 SEE ALSO

C<libvirt(8)>, C<selinux(8)>, C<systemd(8)>, C<virt-sandbox-service(1)>

=head1 FILES

Container content will be stored in subdirectories of
C</var/lib/libvirt/filesystems>, by default.  You can manage the
content in these directories outside of the container and
processes within the container will see the content.

=head1 AUTHORS

Daniel Walsh <dwalsh@redhat.com>
Daniel P. Berrange <dan@berrange.com>

=head1 COPYRIGHT

Copyright (C) 2011-2013 Red Hat, Inc.

=head1 LICENSE

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