Usage

Usage: enroot start [options] [--] NAME|IMAGE [COMMAND] [ARG...]

Start a container and invoke the command script within its root filesystem.
Command and arguments are passed to the script as input parameters.

In the absence of a command script and if a command was given, it will be executed directly.
Otherwise, an interactive shell will be started within the container.

 Options:
   -c, --conf CONFIG    Specify a configuration script to run before the container starts
   -e, --env KEY[=VAL]  Export an environment variable inside the container
       --rc SCRIPT      Override the command script inside the container
   -r, --root           Ask to be remapped to root inside the container
   -w, --rw             Make the container root filesystem writable
   -m, --mount FSTAB    Perform a mount from the host inside the container (colon-separated)
       --pid            Run the container in a new PID namespace
       --net            Run the container in a new network namespace (loopback only)
       --ipc            Run the container in a new IPC namespace
       --uts            Run the container in a new UTS namespace

Description

Start a container by invoking its command script (or entrypoint), refer to Image format (/etc/rc).

By default the root filesystem of the container is made read-only unless the --rw option has been provided.
The --root option can also be provided in order to remap the current user to be root inside the container.

A configuration script can be specified with --conf to perform specific actions before the container starts like mounting files or setting environment variables.

Mounts and environment variables can also be specified on the command line with --mount and --env. They follow the same format as described in Image format (/etc/fstab) and Image format (/etc/environment) with the exception that fstab fields are colon-separated.

The --net option runs the container in a new network namespace with only the loopback interface available.

The --pid option runs the container in a new PID namespace. No init process is injected; the container command becomes PID 1. SIGTERM and SIGINT are forwarded to it, and it is killed if the parent enroot process dies.

The --ipc option runs the container in a new IPC namespace and restricts /dev to a minimal set of devices.

The --uts option runs the container in a new UTS namespace. The hostname is inherited from the host at startup; processes inside the container may change it without affecting the host.

Configuration script

Configuration scripts are standard bash scripts called before any containerization happened with the command and arguments of the container passed as input parameters. Configuration parameters can be passed through special comment directives, for example #ENROOT_REMAP_ROOT=y.

One or more of the following functions can be defined:

Function	Description
`environ()`	Outputs environment configuration
`mounts()`	Outputs mount configuration
`hooks()`	A specific instance of pre-start hook scripts
`rc()`	Override the command script inside the container (similarly to `--rc`)

Here is an example of such configuration:

#ENROOT_REMAP_ROOT=y

environ() {
    # Keep all the environment from the host
    env
}

mounts() {
    # Mount the X11 unix-domain socket
    echo "/tmp/.X11-unix /tmp/.X11-unix none x-create=dir,bind"
    
    # Mount the current working directory to /mnt
    echo "${PWD} /mnt none bind"
}

hooks() {
    # Set the DISPLAY environment variable if not set
    [ -z "${DISPLAY-}" ] && echo "DISPLAY=:0.0" >> ${ENROOT_ENVIRON}
    
    # Record the date when the container was last started
    date > ${ENROOT_ROOTFS}/last_started
}

rc() {
    cat /last_started
    exec bash
}

Starting container images

It is possible to start container images directly without the need to create containers first.

When ENROOT_NATIVE_OVERLAYFS is enabled, enroot will use native kernel overlayfs. This requires:

squashfuse

When ENROOT_NATIVE_OVERLAYFS is disabled, enroot will use FUSE-based overlayfs. This requires:

Note that all changes will be stored in memory and will not persist after the container terminates.

Configuration

Setting	Default	Description
`ENROOT_LOGIN_SHELL`	`yes`	Use a login shell to run the container initialization
`ENROOT_ROOTFS_WRITABLE`	`no`	Make the container root filesystem writable (same as `--rw`)
`ENROOT_NATIVE_OVERLAYFS`	`yes`	Use native overlayfs when starting squashfs images directly
`ENROOT_REMAP_ROOT`	`no`	Remap the current user to root inside containers (same as `--root`)
`ENROOT_ALLOW_SUPERUSER`	`no`	Allow root to retain his superuser privileges inside containers
`ENROOT_UNSHARE_NET`	`no`	Run containers in a new network namespace (same as `--net`)
`ENROOT_UNSHARE_PID`	`no`	Run containers in a new PID namespace (same as `--pid`)
`ENROOT_UNSHARE_IPC`	`no`	Run containers in a new IPC namespace and restrict `/dev` (same as `--ipc`)
`ENROOT_UNSHARE_UTS`	`no`	Run containers in a new UTS namespace (same as `--uts`)

See also Standard Hooks for additional configuration.

Example

# Edit a file from the current directory within a CentOS container
$ echo Hello World > foo
$ enroot start --root --rw --env EDITOR --mount .:mnt centos sudoedit /mnt/foo

# Import a CUDA development image from DockerHub and compile a program locally (Linux >= 4.18)
$ enroot import docker://nvidia/cuda:10.0-devel
$ enroot start --mount .:mnt cuda+devel.sqsh nvcc /mnt/hello-world.cu

FilesExpand file tree

start.md

Latest commit

History