.\ .\" .\" Define V font for inline verbatim, using C font in formats .\" that render this, and otherwise B font. .ie "\f[CB]x\f[]"x" \{\ . ftr V B . ftr VI BI . ftr VB B . ftr VBI BI .\} .el \{\ . ftr V CR . ftr VI CI . ftr VB CB . ftr VBI CBI .\} .TH "DISTROBOX-CREATE" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox create distrobox-create \f[R] .fi .SH DESCRIPTION .PP distrobox-create takes care of creating the container with input name and image. The created container will be tightly integrated with the host, allowing sharing of the HOME directory of the user, external storage, external usb devices and graphical apps (X11/Wayland), and audio. .SH SYNOPSIS .PP \f[B]distrobox create\f[R] .IP .nf \f[C] --image/-i: image to use for the container default: registry.fedoraproject.org/fedora-toolbox:36 --name/-n: name for the distrobox default: my-distrobox --pull/-p: pull latest image unconditionally without asking --yes/-Y: non-interactive, pull images without asking --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred way over \[dq]sudo distrobox\[dq] (note: if using a program other than \[aq]sudo\[aq] for root privileges is necessary, specify it through the DBX_SUDO_PROGRAM env variable, or \[aq]distrobox_sudo_program\[aq] config variable) --clone/-c: name of the distrobox container to use as base for a new container this will be useful to either rename an existing distrobox or have multiple copies of the same environment. --home/-H select a custom HOME directory for the container. Useful to avoid host\[aq]s home littering with temp files. --volume additional volumes to add to the container --additional-flags/-a: additional flags to pass to the container manager command --init-hooks additional commands to execute during container initialization --pre-init-hooks additional commands to execute prior to container initialization --init/-I use init system (like systemd) inside the container. this will make host\[aq]s processes not visible from within the container. --compatibility/-C: show list of compatible images --help/-h: show this message --no-entry: do not generate a container entry in the application list --dry-run/-d: only print the container manager command generated --verbose/-v: show more verbosity --version/-V: show version \f[R] .fi .SH COMPATIBILITY .IP .nf \f[C] for a list of compatible images and container managers, please consult the man page: man distrobox man distrobox-compatibility or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox create --image alpine:latest --name test --init-hooks \[dq]touch /var/tmp/test1 && touch /var/tmp/test2\[dq] distrobox create --image fedora:35 --name test --additional-flags \[dq]--env MY_VAR-value\[dq] distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags \[dq]--pids-limit -1\[dq] distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks \[dq]dnf config-manager --enable powertools && dnf -y install epel-release\[dq] distrobox create --clone fedora-35 --name fedora-35-copy distrobox create --image alpine my-alpine-container distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35 distrobox create --pull --image centos:stream9 --home \[ti]/distrobox/centos9 \f[R] .fi .PP You can also use environment variables to specify container name, image and container manager: .IP .nf \f[C] DBX_CONTAINER_MANAGER=\[dq]docker\[dq] DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create \f[R] .fi .PP Supported environment variables: .IP .nf \f[C] DBX_CONTAINER_ALWAYS_PULL DBX_CONTAINER_CUSTOM_HOME DBX_CONTAINER_HOME_PREFIX DBX_CONTAINER_IMAGE DBX_CONTAINER_MANAGER DBX_CONTAINER_NAME DBX_NON_INTERACTIVE DBX_SUDO_PROGRAM \f[R] .fi .PP DBX_CONTAINER_HOME_PREFIX defines where containers\[cq] home directories will be located. If you define it as \[ti]/dbx then all future containers\[cq] home directories will be \[ti]/dbx/$container_name .PP The \f[V]--additional-flags\f[R] or \f[V]-a\f[R] is useful to modify defaults in the container creations. For example: .IP .nf \f[C] distrobox create -i docker.io/library/archlinux -n dev-arch podman container inspect dev-arch | jq \[aq].[0].HostConfig.PidsLimit\[aq] 2048 distrobox rm -f dev-arch distrobox create -i docker.io/library/archlinux -n dev-arch --volume $CBL_TC:/tc --additional-flags \[dq]--pids-limit -1\[dq] podman container inspect dev-arch | jq \[aq].[0].HostConfig,.PidsLimit\[aq] 0 \f[R] .fi .PP Additional volumes can be specified using the \f[V]--volume\f[R] flag. This flag follows the same standard as \f[V]docker\f[R] and \f[V]podman\f[R] to specify the mount point so \f[V]--volume SOURCE_PATH:DEST_PATH:MODE\f[R]. .IP .nf \f[C] distrobox create --image docker.io/library/archlinux --name dev-arch --volume /usr/share/:/var/test:ro \f[R] .fi .PP During container creation, it is possible to specify (using the additional-flags) some environment variables that will persist in the container and be independent from your environment: .IP .nf \f[C] distrobox create --image fedora:35 --name test --additional-flags \[dq]--env MY_VAR-value\[dq] \f[R] .fi .PP The \f[V]--init-hooks\f[R] is useful to add commands to the entrypoint (init) of the container. This could be useful to create containers with a set of programs already installed, add users, groups. .IP .nf \f[C] distrobox create --image fedora:35 --name test --init-hooks \[dq]dnf groupinstall -y \[rs]\[dq]C Development Tools and Libraries\[rs]\[dq]\[dq] \f[R] .fi .PP The \f[V]--init\f[R] is useful to create a container that will use its own separate init system within. For example using: .IP .nf \f[C] distrobox create -i docker.io/almalinux/8-init --init-hooks \[dq]dnf install -y openssh-server\[dq] --init --name test \f[R] .fi .PP Inside the container we will be able to use normal systemd units: .IP .nf \f[C] \[ti]$ distrobox enter test user\[at]test:\[ti]$ sudo systemctl enable --now sshd user\[at]test:\[ti]$ sudo systemctl status sshd \[u25CF] sshd.service - OpenSSH server daemon Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled) Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago Docs: man:sshd(8) man:sshd_config(5) Main PID: 291 (sshd) \f[R] .fi .PP Note that enabling \f[V]--init\f[R] \f[B]will disable host\[cq]s process integration\f[R]. From within the container you will not be able to see and manage host\[cq]s processes. This is needed because \f[V]/sbin/init\f[R] must be pid 1. .PP The \f[V]--home\f[R] flag let\[cq]s you specify a custom HOME for the container. Note that this will NOT prevent the mount of the host\[cq]s home directory, but will ensure that configs and dotfiles will not litter it. .PP From version 1.4.0 of distrobox, when you create a new container, it will also generate an entry in the applications list.