Capsule Shield
Lightweight Containers for Capsule
A caplet that launches a capsule in lightweight container.
At present capsule-shield
supports LXC on Linux.
Requirements
In addition to Capsule's:
- LXC tools correctly installed, including extras for unprivileged support (for Ubuntu see e.g. here)
- Other (rather basic) tools such as
dhclient
,tar
,cat
,sh
,bash
,id
,ifconfig
,route
,kill
,test
correctly installed - Only for unprivileged containers: the regular user running the capsule must have been assigned a range of subordinate uids and gids through e.g.
sudo usermod -v 100000-165536 -w 100000-165536
Usage
The Gradle-style dependency you need to explode or embed in your Capsule JAR, which you can generate with the tool you prefer (f.e. with plain Maven/Gradle as in Photon and capsule-gui-demo
or higher-level Capsule build plugins), is co.paralleluniverse:capsule-shield:0.2.0
. Also include the caplet in your Capsule manifest, for example if the caplet is exploded:
Caplets: MavenCapsule ShieldedCapsule
if it's embedded as a JAR:
Caplets: MavenCapsule co.paralleluniverse:capsule-shield:0.2.0
capsule-shield
can also be run as a wrapper capsule:
$ java -Dcapsule.log=verbose -jar capsule-shield-0.2.0.jar my-capsule.jar my-capsule-arg1 ...
It can be both run against (or embedded in) plain (e.g. "fat") capsules and Maven-based ones.
Features
- JMX forwarding: just connect to your host capsule process to manage your application running in the container.
- Log forwarding: by default all your application logs will be sent to the host capsule process.
- Links: assign IDs to your capsule containers and refer them from your applications running inside them.
See the next section for information about enabling, disabling and configuring capsule-shield
features.
Configuration
The following additional manifest entries (attributes) and options can be used to customize the container environment:
-
Option
capsule.id
: the runtime Shield ID of the container to be used in links (default = app ID). -
Options
capsule.link.<hostname>
: allows referring to the running container with a Shield ID equal to the option value with<hostname>
. -
Option
capsule.jmx
: whether JMX will be proxied from the capsule parent process to the container (default:true
). -
Option
capsule.redirectLog
: whether logging events should be redirected to the capsule process (default:true
, requirescapsule.jmx
). -
Option
capsule.destroyOnly
: if present ortrue
, the container will be forcibly destroyed without re-creating and booting it afterwards. -
Option
capsule.privileged
: whether the container will be a privileged one or not; unprivileged containers build upon Linux User Namespaces and are safer (default:false
). -
Valid for both privileged and unprivileged containers:
- Option
capsule.sysShareDir
: the location of the system-wideshare
directory where container toolchains can be found; the location is installation / distro-dependent but the default should work in most cases (default:/usr/share
). - Attribute
Network-Bridge
: the name of the host bridge adapter for LXC networking (default:lxcbr0
). Thecapsule.networkBridge
option can override it. - Attribute
Hostname
: the host name assigned to the container (default: none). Thecapsule.hostname
option can override it. Set-Default-GW
attribute: whether the default gateway should be set in order to grant internet access to the container (default:true
). Thecapsule.setDefaultGW
option can override it.IP
attribute: whether the default gateway should be set in order to grant internet access to the container (default:true
). Thecapsule.ip
option can override it.Memory-Limit
attribute:cgroup
memory limit (default: none). Thecapsule.memoryLimit
option can override it.CPU-Shares
attribute:cgroup
cpu shares (default: none). Thecapsule.cpuShares
option can override it.
- Option
-
Valid only for unprivileged containers (some insight about user namespaces and user mappings can be useful):
- Option
capsule.uidMapStart
: the first user ID in an unprivileged container (default:100000
) - Option
capsule.uidMapSize
: the size of the consecutive user ID map in an unprivileged container (default:65536
) - Option
capsule.gidMapStart
: the first group ID in an unprivileged container (default:100000
) - Option
capsule.gidMapSize
: the size of the consecutive group ID map in an unprivileged container (default:65536
) - Attribute
Allowed-Devices
: a comma-separated list of additional allowed devices in an unprivileged container (example:c 136:* rwm,c 1:5 rwm
, default: none). Thecapsule.allowedDevices
option can override it.
- Option
Container locations
The LXC container (both configuration file and a minimal root disk containing mostly mount points) will be created in ${HOME}/.capsule-shield/<Shield ID, default = app ID>/lxc
and managed automatically.
Notes
Please note that an unprivileged container's root disk is owned by a subuid of the user launching the capsule and cannot be destroyed without user mapping; you can destroy the container by launching the capsule with the capsule.destroyOnly
option set. The removal can also be performed manually with lxc-destroy -n lxc -P ${HOME}/.capsule-shield/<Shield ID, default = app ID>
.
License
Copyright (c) 2015, Parallel Universe Software Co. and Contributors. All rights reserved.
This program and the accompanying materials are licensed under the terms
of the Eclipse Public License v1.0 as published by the Eclipse Foundation.
http://www.eclipse.org/legal/epl-v10.html