'\" t .\ .\" .\" 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" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH COMPATIBILITY .PP This project \f[B]does not need a dedicated image\f[R]. It can use any OCI images from docker-hub, quay.io, or any registry of your choice. .PP Many cloud images are stripped down on purpose to save size and may not include commands such as \f[V]which\f[R], \f[V]mount\f[R], \f[V]less\f[R] or \f[V]vi\f[R]). Additional packages can be installed once inside the container. We recommend using your preferred automation tool inside the container if you find yourself having to repeatedly create new containers. Maintaining your own custom image is also an option. .PP The main concern is having basic Linux utilities (\f[V]mount\f[R]), basic user management utilities (\f[V]usermod, passwd\f[R]), and \f[V]sudo\f[R] correctly set. .SS SUPPORTED CONTAINER MANAGERS .PP \f[V]distrobox\f[R] can run on either \f[V]podman\f[R] or \f[V]docker\f[R] .PP It depends either on \f[V]podman\f[R] configured in \f[V]rootless mode\f[R] or on \f[V]docker\f[R] configured without sudo (follow THESE instructions (https://docs.docker.com/engine/install/linux-postinstall/)) .IP \[bu] 2 Minimum podman version: \f[B]2.1.0\f[R] .IP \[bu] 2 Minimum docker version: \f[B]18.06.1\f[R] .PP Follow the official installation guide here: .IP \[bu] 2 .IP \[bu] 2 .IP \[bu] 2 .SS CONTAINERS DISTROS .PP Distrobox guests tested successfully with the following container images: .PP .TS tab(@); lw(23.3n) lw(23.3n) lw(23.3n). T{ Distro T}@T{ Version T}@T{ Images T} _ T{ AlmaLinux (UBI) T}@T{ 8 T}@T{ quay.io/almalinux/8-base:8 quay.io/almalinux/8-init:8 T} T{ AlmaLinux T}@T{ 8 8-minimal 9 9-minimal T}@T{ quay.io/almalinux/almalinux:8 quay.io/almalinux/almalinux:9 quay.io/almalinux/almalinux:9-minimal T} T{ Alpine Linux T}@T{ 3.15 3.16 T}@T{ docker.io/library/alpine:3.15 docker.io/library/alpine:3.16 docker.io/library/alpine:latest T} T{ AmazonLinux T}@T{ 1 2 2022 T}@T{ public.ecr.aws/amazonlinux/amazonlinux:1 public.ecr.aws/amazonlinux/amazonlinux:2 public.ecr.aws/amazonlinux/amazonlinux:2022.0.20220531.0 T} T{ Archlinux T}@T{ T}@T{ docker.io/library/archlinux:latest T} T{ CentOS Stream T}@T{ 8 9 T}@T{ quay.io/centos/centos:stream8 quay.io/centos/centos:stream9 T} T{ CentOS T}@T{ 7 T}@T{ quay.io/centos/centos:7 T} T{ ClearLinux T}@T{ T}@T{ docker.io/library/clearlinux:latest docker.io/library/clearlinux:base T} T{ Debian T}@T{ 7 8 9 10 11 T}@T{ docker.io/debian/eol:wheezy docker.io/debian/eol:jessie docker.io/library/debian:9 docker.io/library/debian:10 docker.io/library/debian:stable docker.io/library/debian:stable-backports T} T{ Debian T}@T{ Testing T}@T{ docker.io/library/debian:testing docker.io/library/debian:testing-backports T} T{ Debian T}@T{ Unstable T}@T{ docker.io/library/debian:unstable T} T{ Fedora T}@T{ 35 36 37 38 Rawhide T}@T{ registry.fedoraproject.org/fedora-toolbox:37 quay.io/fedora/fedora:35 quay.io/fedora/fedora:36 registry.fedoraproject.org/fedora:37 quay.io/fedora/fedora:38 T} T{ Gentoo Linux T}@T{ rolling T}@T{ docker.io/gentoo/stage3:latest T} T{ Kali Linux T}@T{ rolling T}@T{ docker.io/kalilinux/kali-rolling:latest T} T{ Mageia T}@T{ 8 T}@T{ docker.io/library/mageia T} T{ Neurodebian T}@T{ nd100 T}@T{ docker.io/library/neurodebian:nd100 T} T{ Opensuse T}@T{ Leap T}@T{ registry.opensuse.org/opensuse/leap:latest T} T{ Opensuse T}@T{ Tumbleweed T}@T{ registry.opensuse.org/opensuse/tumbleweed:latest registry.opensuse.org/opensuse/toolbox:latest T} T{ Oracle Linux T}@T{ 7 7-slim 8 8-slim 9 9-slim T}@T{ container-registry.oracle.com/os/oraclelinux:7 container-registry.oracle.com/os/oraclelinux:7-slim container-registry.oracle.com/os/oraclelinux:8 container-registry.oracle.com/os/oraclelinux:8-slim container-registry.oracle.com/os/oraclelinux:9 container-registry.oracle.com/os/oraclelinux:9-slim T} T{ RedHat (UBI) T}@T{ 7 8 9 T}@T{ registry.access.redhat.com/ubi7/ubi registry.access.redhat.com/ubi7/ubi-init registry.access.redhat.com/ubi8/ubi registry.access.redhat.com/ubi8/ubi-init registry.access.redhat.com/ubi8/ubi-minimal registry.access.redhat.com/ubi9/ubi registry.access.redhat.com/ubi9/ubi-init registry.access.redhat.com/ubi9/ubi-minimal T} T{ Rocky Linux T}@T{ 8 8-minimal 9 T}@T{ quay.io/rockylinux/rockylinux:8 quay.io/rockylinux/rockylinux:8-minimal quay.io/rockylinux/rockylinux:9 quay.io/rockylinux/rockylinux:latest T} T{ Scientific Linux T}@T{ 7 T}@T{ docker.io/library/sl:7 T} T{ Slackware T}@T{ 14.2 T}@T{ docker.io/vbatts/slackware:14.2 T} T{ Ubuntu T}@T{ 14.04 16.04 18.04 20.04 22.04 22.10 T}@T{ docker.io/library/ubuntu:14.04 docker.io/library/ubuntu:16.04 docker.io/library/ubuntu:18.04 docker.io/library/ubuntu:20.04 docker.io/library/ubuntu:22.04 T} T{ Void Linux T}@T{ T}@T{ ghcr.io/void-linux/void-linux:latest-full-x86_64 ghcr.io/void-linux/void-linux:latest-full-x86_64-musl T} .TE .PP Note however that if you use a non-toolbox preconfigured image (e.g. images pre-baked to work with ), the \f[B]first\f[R] \f[V]distrobox-enter\f[R] you\[cq]ll perform can take a while as it will download and install the missing dependencies. .PP A small time tax to pay for the ability to use any type of image. This will \f[B]not\f[R] occur after the first time, \f[B]subsequent enters will be much faster.\f[R] .PP NixOS is not a supported container distro, and there are currently no plans to bring support to it. If you are looking for unprivlaged NixOS environments, we suggest you look into nix-shell (https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html). .SS NEW DISTRO SUPPORT .PP If your distro of choice is not on the list, open an issue requesting support for it, we can work together to check if it is possible to add support for it. .PP Or just try using it anyway, if it works, open an issue and it will be added to the list! .SS OLDER DISTRIBUTIONS .PP For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu 12.04, compatibility is not assured. .PP Their \f[V]libc\f[R] version is incompatible with kernel releases after \f[V]>=4.11\f[R]. A work around this is to use the \f[V]vsyscall=emulate\f[R] flag in the bootloader of the host. .PP Keep also in mind that mirrors could be down for such old releases, so you will need to build a custom distrobox image to ensure basic dependencies are met. .\ .\" .\" 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. .\ .\" .\" 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-ENTER" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox enter distrobox-enter \f[R] .fi .SH DESCRIPTION .PP distrobox-enter takes care of entering the container with the name specified. Default command executed is your SHELL, but you can specify different shells or entire commands to execute. If using it inside a script, an application, or a service, you can specify the \[en]headless mode to disable tty and interactivity. .SH SYNOPSIS .PP \f[B]distrobox enter\f[R] .IP .nf \f[C] --name/-n: name for the distrobox default: my-distrobox --/-e: end arguments execute the rest as command to execute at login default: bash -l --no-tty/-T: do not instantiate a tty --no-workdir/-nw: always start the container from container\[aq]s home directory --additional-flags/-a: additional flags to pass to the container manager command --help/-h: show this message --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) --dry-run/-d: only print the container manager command generated --verbose/-v: show more verbosity --version/-V: show version \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox-enter --name fedora-toolbox-35 -- bash -l distrobox-enter my-alpine-container -- sh -l distrobox-enter --additional-flags \[dq]--preserve-fds\[dq] --name test -- bash -l distrobox-enter --additional-flags \[dq]--env MY_VAR=value\[dq] --name test -- bash -l MY_VAR=value distrobox-enter --additional-flags \[dq]--preserve-fds\[dq] --name test -- bash -l \f[R] .fi .PP You can also use environment variables to specify container manager and container name: .IP .nf \f[C] DBX_CONTAINER_MANAGER=\[dq]docker\[dq] DBX_CONTAINER_NAME=test-alpine distrobox-enter \f[R] .fi .PP Supported environment variables: .IP .nf \f[C] DBX_CONTAINER_NAME DBX_CONTAINER_MANAGER DBX_SKIP_WORKDIR DBX_SUDO_PROGRAM \f[R] .fi .PP This is used to enter the distrobox itself. Personally, I just create multiple profiles in my \f[V]gnome-terminal\f[R] to have multiple distros accessible. .PP The \f[V]--additional-flags\f[R] or \f[V]-a\f[R] is useful to modify default command when executing in the container. For example: .IP .nf \f[C] distrobox enter -n dev-arch --additional-flags \[dq]--env my_var=test\[dq] -- printenv &| grep my_var my_var=test \f[R] .fi .PP This is possible also using normal env variables: .IP .nf \f[C] my_var=test distrobox enter -n dev-arch --additional-flags -- printenv &| grep my_var my_var=test \f[R] .fi .PP If you\[cq]d like to enter a rootful container having distrobox use a program other than `sudo' to run podman/docker as root, such as `pkexec' or `doas', you may specify it with the \f[V]DBX_SUDO_PROGRAM\f[R] environment variable. For example, to use `doas' to enter a rootful container: .IP .nf \f[C] DBX_SUDO_PROGRAM=\[dq]doas\[dq] distrobox enter -n container --root \f[R] .fi .PP Additionally, in one of the config file paths that distrobox supports, such as \f[V]\[ti]/.distroboxrc\f[R], you can also append the line \f[V]distrobox_sudo_program=\[dq]doas\[dq]\f[R] (for example) to always run distrobox commands involving rootful containers using `doas'. .\ .\" .\" 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-EPHEMERAL" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox ephemeral distrobox-ephemeral \f[R] .fi .SH DESCRIPTION .PP distrobox-ephemeral creates a temporary distrobox that is automatically destroyed when the command is terminated. .SH SYNOPSIS .PP \f[B]distrobox ephemeral\f[R] .IP .nf \f[C] --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) --verbose/-v: show more verbosity --help/-h: show this message --/-e: end arguments execute the rest as command to execute at login default: bash -l --version/-V: show version \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox-ephemeral --image alpine:latest -- cat /etc/os-release distrobox-ephemeral --root --verbose --image alpine:latest --volume /opt:/opt \f[R] .fi .PP You can also use flags from \f[B]distrobox-create\f[R] to customize the ephemeral container to run. .PP Refer to .IP .nf \f[C] man distrobox-create \f[R] .fi .PP or .IP .nf \f[C] distrobox-create --help \f[R] .fi .PP Supported environment variables: .IP .nf \f[C] distrobox-ephemeral calls distrobox-create, SEE ALSO distrobox-create(1) for a list of supported environment variables to use. \f[R] .fi .\ .\" .\" 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-EXPORT" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox-export \f[R] .fi .SH DESCRIPTION .PP \f[B]Application and service exporting\f[R] .PP distrobox-export takes care of exporting an app a binary or a service from the container to the host. .PP The exported app will be easily available in your normal launcher and it will automatically be launched from the container it is exported from. .SH SYNOPSIS .PP \f[B]distrobox-export\f[R] .IP .nf \f[C] --app/-a: name of the application to export --bin/-b: absolute path of the binary to export --service/-s: name of the service to export --delete/-d: delete exported application or service --export-label/-el: label to add to exported application name. Defaults to (on \[rs]$container_name) --export-path/-ep: path where to export the binary --extra-flags/-ef: extra flags to add to the command --sudo/-S: specify if the exported item should be run as sudo --help/-h: show this message --verbose/-v: show more verbosity --version/-V: show version \f[R] .fi .PP You may want to install graphical applications or user services in your distrobox. Using \f[V]distrobox-export\f[R] from \f[B]inside\f[R] the container will let you use them from the host itself. .SH EXAMPLES .IP .nf \f[C] distrobox-export --app mpv [--extra-flags \[dq]flags\[dq]] [--delete] [--sudo] distrobox-export --service syncthing [--extra-flags \[dq]flags\[dq]] [--delete] [--sudo] distrobox-export --bin /path/to/bin --export-path \[ti]/.local/bin [--extra-flags \[dq]flags\[dq]] [--delete] [--sudo] \f[R] .fi .PP \f[B]App export example\f[R] .IP .nf \f[C] distrobox-export --app abiword \f[R] .fi .PP This tool will simply copy the original \f[V].desktop\f[R] files along with needed icons, add the prefix \f[V]/usr/local/bin/distrobox-enter -n distrobox_name -e ...\f[R] to the commands to run, and save them in your home to be used directly from the host as a normal app. .PP \f[B]Service export example\f[R] .IP .nf \f[C] distrobox-export --service syncthing --extra-flags \[dq]--allow-newer-config\[dq] distrobox-export --service nginx --sudo \f[R] .fi .PP For services, it will similarly export the systemd unit inside the container to a \f[V]systemctl --user\f[R] service, prefixing the various \f[V]ExecStart ExecStartPre ExecStartPost ExecReload ExecStop ExecStopPost\f[R] with the \f[V]distrobox-enter\f[R] command prefix. .PP The exported services will be available in the host\[cq]s user\[cq]s systemd session, so .IP .nf \f[C] systemctl --user status exported_service_name \f[R] .fi .PP will show the status of the service exported. .PP \f[B]Binary export example\f[R] .IP .nf \f[C] distrobox-export --bin /usr/bin/code --extra-flags \[dq]--foreground\[dq] --export-path $HOME/.local/bin \f[R] .fi .PP In the case of exporting binaries, you will have to specify \f[B]where\f[R] to export it (\f[V]--export-path\f[R]) and the tool will create a little wrapper script that will \f[V]distrobox-enter -e\f[R] from the host, the desired binary. This can be handy with the use of \f[V]direnv\f[R] to have different versions of the same binary based on your \f[V]env\f[R] or project. .PP The exported binaries will be exported in the \[lq]\[en]export-path\[rq] of choice as a wrapper script that acts naturally both on the host and in the container. Note that \[lq]\[en]export-path\[rq] is NOT OPTIONAL, you have to explicitly set it. .PP \f[B]Additional flags\f[R] .PP You can specify additional flags to add to the command, for example if you want to export an electron app, you could add the \[lq]\[en]foreground\[rq] flag to the command: .IP .nf \f[C] distrobox-export --app atom --extra-flags \[dq]--foreground\[dq] distrobox-export --bin /usr/bin/vim --export-path \[ti]/.local/bin --extra-flags \[dq]-p\[dq] distrobox-export --service syncthing --extra-flags \[dq]-allow-newer-config\[dq] \f[R] .fi .PP This works for services, binaries, and apps. Extra flags are only used then the exported app, binary, or service is used from the host, using them inside the container will not include them. .PP \f[B]Unexport\f[R] .PP The option \[lq]\[en]delete\[rq] will un-export an app, binary, or service. .IP .nf \f[C] distrobox-export --app atom --delete distrobox-export --bin /usr/bin/vim --export-path \[ti]/.local/bin --delete distrobox-export --service syncthing --delete distrobox-export --service nginx --delete \f[R] .fi .PP \f[B]Run as root in the container\f[R] .PP The option \[lq]\[en]sudo\[rq] will launch the exported item as root inside the distrobox. .PP \f[B]Exporting apps from rootful containers\f[R] .PP It is worth noting that, when exporting any item - which includes graphical apps - from rootful containers (created with \f[V]distrobox create --root\f[R]), root privileges will be needed every time the item is launched (in order to enter the rootful container), which, by default, is done using \f[V]sudo\f[R] (see docs for \f[V]distrobox-enter\f[R] on how to customize that). However, for graphical apps in specific, since they launch without a terminal, the usage of \f[V]sudo\f[R] might, at first, make it impossible to launch them. .PP To fix this without needing to customize the sudo program, one can define a global \f[V]SUDO_ASKPASS\f[R] environment variable on their machine, which is a PATH to an executable that is run by \f[V]sudo\f[R] when no terminal is available (or when it is given the \f[V]--askpass\f[R] or \f[V]-A\f[R] option), and the output of that executable to stdout is used as the password input. The executable is called as many times is needed for authentication as root to succeed (unless a limit of amount of attempts is reached). .PP To do this, pick a program to ask the user for graphical password input. In this example, we will use \f[V]zenity --password\f[R], which should be present for GNOME users (and can also be installed in other DEs) - there are other options, such as \f[V]kdialog --password \[dq]Message\[dq]\f[R] for KDE users. .PP Write the call to the desired program to a script file, for example to \f[V]/usr/bin/my-password-prompt\f[R] (sample contents below): .IP .nf \f[C] #!/bin/sh zenity --password \[dq]Authentication as root is required\[dq] \f[R] .fi .PP (You may save the script under, for example, \f[V]\[ti]/.local/bin\f[R] if you want to keep it fully local to your user.) .PP Afterwards, make it executable (e.g.\ run \f[V]sudo chmod +x /usr/bin/my-password-prompt\f[R]). Then, make sure to set \f[V]SUDO_ASKPASS\f[R] to \f[V]\[dq]/usr/bin/my-password-prompt\[dq]\f[R] (replace with your script\[cq]s path) in a global profile file, so that it is picked up by sudo when running graphical apps (and, therefore, sudo will run the script you created to ask for a password). This is done with the shell line \f[V]export SUDO_ASKPASS=\[dq]/path/to/script/goes/here\[dq]\f[R]. You can do this for your user only by running the command below (replace the script path as needed): .IP .nf \f[C] echo \[aq]export SUDO_ASKPASS=\[dq]/usr/bin/my-password-prompt\[dq]\[aq] >> \[ti]/.profile \f[R] .fi .PP Which appends the appropriate line to the end of your \f[V]\[ti]/.profile\f[R] file, thus making the change local to your user. Alternatively, to set it system-wide (for all users), you may create a file in \f[V]/etc/profile.d/\f[R] (or equivalent for your system) with that line. .PP Now just log out and log back in, and graphical apps exported from rootful containers should now be properly asking for root\[cq]s password before launching (instead of not opening, if that was the case before). .PP \f[B]Notes\f[R] .PP Note you can use \[en]app OR \[en]bin OR \[en]service but not together. .IP .nf \f[C] distrobox-export --service nginx --sudo \f[R] .fi .PP [IMAGE: app-export (https://user-images.githubusercontent.com/598882/144294795-c7785620-bf68-4d1b-b251-1e1f0a32a08d.png)] .PP [IMAGE: service-export (https://user-images.githubusercontent.com/598882/144294314-29a8921f-4511-453d-bf8e-d0d1e336db91.png)] .PP NOTE: some electron apps such as vscode and atom need additional flags to work from inside the container, use the \f[V]--extra-flags\f[R] option to provide a series of flags, for example: .PP \f[V]distrobox-export --app atom --extra-flags \[dq]--foreground\[dq]\f[R] .\ .\" .\" 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-GENERATE-ENTRY" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox generate-entry \f[R] .fi .SH DESCRIPTION .PP distrobox-generate-entry will create a desktop icon for one of the available distroboxes. This will be then deleted when you remove the matching distrobox. .SH SYNOPSIS .PP \f[B]distrobox generate-entry\f[R] .IP .nf \f[C] --help/-h: show this message --all/-a: perform for all distroboxes --delete/-d: delete the entry --icon/-i: specify a custom icon [/path/to/icon] (default auto) --verbose/-v: show more verbosity --version/-V: show version \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox-generate-entry container-name [--delete] [--icon [auto,/path/to/icon]] \f[R] .fi .\ .\" .\" 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-HOST-EXEC" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox-host-exec \f[R] .fi .SH DESCRIPTION .PP distrobox-host-exec lets one execute command on the host, while inside of a container. .PP Under the hood, distrobox-host-exec uses \f[V]host-spawn\f[R] a project that let\[cq]s us execute commands back on the host. If the tool is not found the user will be prompted to install it. .SH SYNOPSIS .PP Just pass to \[lq]distrobox-host-exec\[rq] any command and all its arguments, if any. .IP .nf \f[C] distrobox-host-exec [command [arguments]] --help/-h: show this message --verbose/-v: show more verbosity --version/-V: show version \f[R] .fi .PP If no command is provided, it will execute \[lq]$SHELL\[rq]. .PP Alternatively, use symlinks to make \f[V]distrobox-host-exec\f[R] execute as that command: .IP .nf \f[C] \[ti]$: ln -s /usr/bin/distrobox-host-exec /usr/local/bin/podman \[ti]$: ls -l /usr/local/bin/podman lrwxrwxrwx. 1 root root 51 Jul 11 19:26 /usr/local/bin/podman -> /usr/bin/distrobox-host-exec \[ti]$: podman version \&...this is executed on host... \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox-host-exec ls distrobox-host-exec bash -l distrobox-host-exec flatpak run org.mozilla.firefox distrobox-host-exec podman ps -a \f[R] .fi .\ .\" .\" 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-INIT" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox-init \f[R] .fi .SH DESCRIPTION .PP \f[B]Init the distrobox (not to be launched manually)\f[R] .PP distrobox-init is the entrypoint of a created distrobox. Note that this HAS to run from inside a distrobox, will not work if you run it from your host. .PP \f[B]This is not intended to be used manually, but instead used by distrobox-create to set up the container\[cq]s entrypoint.\f[R] .PP distrobox-init will take care of installing missing dependencies (eg. sudo), set up the user and groups, mount directories from the host to ensure the tight integration. .SH SYNOPSIS .PP \f[B]distrobox-init\f[R] .IP .nf \f[C] --name/-n: user name --user/-u: uid of the user --group/-g: gid of the user --home/-d: path/to/home of the user --help/-h: show this message --init/-I: whether to use or not init --pre-init-hooks: commands to execute prior to init --upgrade/-U: run init in upgrade mode --verbose/-v: show more verbosity --version/-V: show version --: end arguments execute the rest as command to execute during init \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox-init --name test-user --user 1000 --group 1000 --home /home/test-user distrobox-init --upgrade \f[R] .fi .\ .\" .\" 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-LIST" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox list distrobox-list \f[R] .fi .SH DESCRIPTION .PP distrobox-list lists available distroboxes. It detects them and lists them separately from the rest of normal podman or docker containers. .SH SYNOPSIS .PP \f[B]distrobox list\f[R] .IP .nf \f[C] --help/-h: show this message --no-color: disable color formatting --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) --size/-s: show also container size --verbose/-v: show more verbosity --version/-V: show version \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox-list \f[R] .fi .PP You can also use environment variables to specify container manager .IP .nf \f[C] DBX_CONTAINER_MANAGER=\[dq]docker\[dq] distrobox-list \f[R] .fi .PP Supported environment variables: .IP .nf \f[C] DBX_CONTAINER_MANAGER DBX_SUDO_PROGRAM \f[R] .fi .PP [IMAGE: image (https://user-images.githubusercontent.com/598882/147831082-24b5bc2e-b47e-49ac-9b1a-a209478c9705.png)] .\ .\" .\" 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-RM" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox rm distrobox-rm \f[R] .fi .SH DESCRIPTION .PP distrobox-rm delete one of the available distroboxes. .SH SYNOPSIS .PP \f[B]distrobox rm\f[R] .IP .nf \f[C] --name/-n: name for the distrobox --force/-f: force deletion --rm-home: remove the mounted home if it differs from the host user\[aq]s one --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) --help/-h: show this message --verbose/-v: show more verbosity --version/-V: show version \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox-rm --name container-name [--force] distrobox-rm container-name [-f] \f[R] .fi .PP You can also use environment variables to specify container manager and name: .IP .nf \f[C] DBX_CONTAINER_MANAGER=\[dq]docker\[dq] DBX_CONTAINER_NAME=test-alpine distrobox-rm \f[R] .fi .PP Supported environment variables: .IP .nf \f[C] DBX_CONTAINER_MANAGER DBX_CONTAINER_NAME DBX_NON_INTERACTIVE DBX_SUDO_PROGRAM \f[R] .fi .\ .\" .\" 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-STOP" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox stop distrobox-stop \f[R] .fi .SH DESCRIPTION .PP distrobox-stop stop a running distrobox. .PP Distroboxes are left running, even after exiting out of them, so that subsequent enters are really quick. This is how they can be stopped. .SH SYNOPSIS .PP \f[B]distrobox stop\f[R] .IP .nf \f[C] --name/-n: name for the distrobox --yes/-Y: non-interactive, stop without asking --help/-h: show this message --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) --verbose/-v: show more verbosity --version/-V: show version \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox-stop --name container-name distrobox-stop container-name \f[R] .fi .PP You can also use environment variables to specify container manager and name: .IP .nf \f[C] DBX_CONTAINER_MANAGER=\[dq]docker\[dq] DBX_CONTAINER_NAME=test-alpine distrobox-stop \f[R] .fi .PP Supported environment variables: .IP .nf \f[C] DBX_CONTAINER_MANAGER DBX_CONTAINER_NAME DBX_NON_INTERACTIVE DBX_SUDO_PROGRAM \f[R] .fi .\ .\" .\" 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-UPGRADE" "1" "Dec 2022" "Distrobox" "User Manual" .hy .SH NAME .IP .nf \f[C] distrobox-upgrade \f[R] .fi .SH DESCRIPTION .PP distrobox-upgrade will enter the specified list of containers and will perform an upgrade using the container\[cq]s package manager. .SH SYNOPSIS .PP \f[B]distrobox upgrade\f[R] .IP .nf \f[C] --help/-h: show this message --all/-a: perform for all distroboxes --verbose/-v: show more verbosity --version/-V: show version \f[R] .fi .SH EXAMPLES .IP .nf \f[C] distrobox-upgrade --all distrobox-upgrade alpine-linux ubuntu22 my-distrobox123 distrobox upgrade CONTAINER_NAME [CONTAINER_NAME1 CONTAINER_NAME2 ...] \f[R] .fi