Useful Tips
Table of Contents
- Detect If You’re in a Distrobox
- Launch a Distrobox from You Applications List
- Create a Distrobox with a Custom HOME Directory
- Mount Additional Volumes in a Distrobox
- Use a Different Shell than the Host
- Run the Container with Real Root
- Run Debian/ubuntu Container behind Proxy
- Using a Command Other than Sudo to Run a Rootful Container
- Duplicate an Existing Distrobox
- Export to the Host
- Execute Commands on the Host
- Resolve “Error cannot open display: :0”
- Using Init System inside a Distrobox
- Using Docker inside a Distrobox
- Using Podman inside a Distrobox
- Using LXC inside a Distrobox
- Using Waydroid inside a Distrobox
- Using Host’s Podman or Docker inside a Distrobox
- Using Distrobox as Main CLI
- Using a Different Architecture
- Using the GPU inside the Container
- Slow Creation on Podman and Image Size Getting Bigger with Distrobox Create
- Permission Problems When Using VirtualBox
- Container save and Restore
- Check Used Resources
- Pre-Installing Additional Package Repositories
- Apply Resource Limitation on the Fly
- Copy Text to Host Clipboard
Detect If You’re in a Distrobox
Being this tightly integrated, it may be useful to know when you’re in a container or not.
To detect you can just check the environment variable "${CONTAINER_ID}", if set, you’re in a distrobox.
Launch a Distrobox from You Applications List
Starting from distrobox 1.4.0, containers created will automatically generate a desktop entry. For contaias ners generated with older versions, you can use:
To delete it:
Create a Distrobox with a Custom HOME Directory
distrobox create supports the use of the --home flag, as specified in the
usage HERE
Simply use:
Mount Additional Volumes in a Distrobox
distrobox create supports the use of the --volume flag, as specified in the
usage HERE
Simply use:
Use a Different Shell than the Host
From version 1.4.0, distrobox enter will execute the login shell of the container’s user
by default. So, just change the default shell in the container using:
exit and log back in the container.
For version older than 1.4.0, distrobox will pick up the shell from the host and use it inside the container. If you want a different one you can use:
SHELL=/bin/zsh
SHELL=/bin/zsh
Run the Container with Real Root
When using podman, distrobox will prefer to use rootless containers. In this mode the root
user inside the container is not the real root user of the host. But it still has
the same privileges as your normal $USER.
But what if you really really need those root privileges even inside the container?
Running sudo distrobox is not supported, instead, it is better to simply use normal
command with the --root or -r flag, so that distrobox can still integrate better
with your $USER.
Another use case, what if you want or need to run distrobox with the root user, in a login shell?
Before the 1.4.3 release, it wasn’t possible. We couldn’t make a distinction between someone
running distrobox via sudo from someone logged in as the root user in a shell. Now things are
as easy as it would be if you were creating a rootless container:
And:
We trust you already know the implications of running distrobox, as well as anything else, with the root user and that with great power comes great responsibilities.
Run Debian/ubuntu Container behind Proxy
It might be that you’re trying to set-up your distrobox, but you’re stuck behind a proxy.
A simple solution can be crafted using pre-init-hooks
proxy=http://my_proxy.domain.example:3128
t="echo 'Acquire::http::Proxy \\\"""\\\";' > /etc/apt/apt.conf.d/proxy.conf; echo 'Acquire::https::Proxy \\\"""\\\";' >> /etc/apt/apt.conf.d/proxy.conf;"
http_proxy=""
This way, we’re configuring apt before using it.
Using a Command Other than Sudo to Run a Rootful Container
When using the --root option with Distrobox, internally, it uses sudo to be able to
interact with the rootful container through podman/docker, which will prompt for a valid
root password on the terminal. However, some users might prefer to use a command other
than sudo in order to authenticate as root; for example, pkexec could be used to
display a graphical authentication prompt. If you need this, make sure to specify
the desired command through the DBX_SUDO_PROGRAM environment variable
(supported by most distrobox subcommands), alongside --root. Sample usage:
DBX_SUDO_PROGRAM="pkexec"
Additionally, you may also have any further distrobox commands use pkexec (for example)
for rootful containers by appending the line distrobox_sudo_program="pkexec"
(replace pkexec with the desired program) to one of the config file paths that
distrobox supports; for example, to ‘~/.distroboxrc’.
It is also worth noting that, if your sudo program does not have persistence
(i.e., cooldown before asking for the root password again after a successful authentication)
configured, then you may have to enter the root password multiple times, as distrobox
calls multiple podman/docker commands under the hood. In order to avoid this, it is
recommended to either configure your sudo program to be persistent, or, if that’s
not feasible, use sudo whenever possible (which has persistence enabled by default).
However, if you’d like to have a graphical authentication prompt, but would also like
to benefit from sudo’s persistence (to avoid prompting for a password multiple times in a row),
you may specify sudo --askpass as the sudo program.
The --askpass option makes sudo launch the program in the path (or name, if it is in $PATH)
specified by the SUDO_ASKPASS environment variable, and uses its output (to stdout)
as the password input to authenticate as root. If unsuccessful, it launches the program again,
until either it outputs the correct password, the user cancels the operation, or
a limit of amount of authentication attempts is reached.
So, for example, assume you’d like to use zenity --password to prompt for the sudo password.
You may save a script, e.g. my-password-prompt, to somewhere in your machine - say,
to ~/.local/bin/my-password-prompt - with the following contents:
#!/bin/sh
Make it executable using, for example, chmod (in the example, by running chmod +x ~/.local/bin/my-password-prompt -
replace with the path to your script). Afterwards, make sure SUDO_ASKPASS is set to your newly-created script’s path,
and also ensure DBX_SUDO_PROGRAM is set to sudo --askpass, and you should be good to go. For example,
running the below command should only prompt the root authentication GUI once throughout the whole process:
SUDO_ASKPASS="/.local/bin/my-password-prompt" DBX_SUDO_PROGRAM="sudo --askpass"
You may make these options persist by specifying those environment variables in your shell’s rc file (such as ~/.bashrc).
Note that this will also work if distrobox_sudo_program="sudo --askpass" is specified in one of distrobox’s config files
(such as ~/.distroboxrc), alongside export SUDO_ASKPASS="/path/to/password/prompt/program" (for example - however, this
last line is usually better suited to your shell’s rc file).
Duplicate an Existing Distrobox
It can be useful to just duplicate an already set up environment, to do this,
distrobox create supports the use of the
--clone flag, as specified in the usage HERE
Simply use:
Export to the Host
Distrobox supports exporting to the host either binaries or applications. Head over the usage page to have an explanation and examples.
Execute Commands on the Host
You can check this little post about executing commands on the host.
Resolve “Error cannot open display: :0”
If your container is not able to connect to your host xserver, make sure to
install xhost on the host machine and run xhost +si:localuser:$USER.
If you wish to enable this functionality on future reboots add the above command
to your ~/.distroboxrc
Using Init System inside a Distrobox
You can use an init system inside the container. You can either use supported pre-created images, or have to add additional packages.
Example of such images are:
- docker.io/almalinux/8-init
- registry.access.redhat.com/ubi7/ubi-init
- registry.access.redhat.com/ubi8/ubi-init
- registry.access.redhat.com/ubi9/ubi-init
- registry.opensuse.org/opensuse/leap:latest
- registry.opensuse.org/opensuse/tumbleweed:latest
You can use such feature using:
If you want to use a non-pre-create image, you’ll need to add the additional package:
Note however that in this mode, you’ll not be able to access host’s processes from within the container.
Result:
Systemd running on openSUSE
OpenRC running on Alpine Linux
Example use:
; ; )
) ;
)
)
)
Using Docker inside a Distrobox
You may want to run a separate instance of docker inside your container. In order to do this, create a container with an init system using a podman rootful container or using docker using the unshare-all flag
Example:
Inside the container:
; ; )
) ;
)
Using Podman inside a Distrobox
You may want to run a separate instance of podman inside your container. In order to do this, create a container using the unshare-all flag, the container manager can be anyone of choice.
Example:
Inside it install podman, and add subuids for the user:
Then you’ll be able to use both rootful and rootless podman inside the container:
Using LXC inside a Distrobox
You may want to run an LXC instance inside your container. In order to do this, create a container with an init system using the unshare-all flag, this works with either docker, rootful podman, or rootless podman.
Example:
Inside the container we will need to first setup the lxcbr0 network and enable the services:
Then we can proceed with the LXC container creation:
[ # Here do the interactive rootfs choice, I'll use alpine:edge amd64
)
And you have a working LXC inside your Distrobox container.
Using Waydroid inside a Distrobox
Waydroid is a popular solution for running Android applications on Linux using an LXC container. Since these containers run inside a Distrobox, you can also run Waydroid.
Note: Wayland and the
binder_linuxmodule are required at the host level. You can install the DKMS from the choff/anbox-modules repository.
Manual Installation
To do this, we need a rootful container with Systemd plus some additional dependencies (tested with Vanilla OS Pico and Debian Sid):
- libpam-systemd
- curl
- kmod
- dbus-x11
- iptables
- mutter
Let’s create a rootful and unshared container as follows:
Once it’s started with distrobox enter --root waydroid, we can proceed with the Waydroid
installation from the official repository:
|
Then proceed with its initialization using:
The above environment variables must be present each time the waydroid command is used.
Automated Installation
The Waydroid image from the Vanilla OS Team is designed to streamline the entire setup process. To use it, proceed as follows:
Once started, Waydroid is automatically executed via Systemd. Check for the process to finish using
the systemctl status waydroid-init command, then start using Waydroid with:
Make sure to use the ewaydroid command each time you need to work with Waydroid. This command is a
wrapper that sets the proper environment variables to make it work with the host D-Bus.
Using Host’s Podman or Docker inside a Distrobox
You can easily control host’s instance of docker or podman, using distrobox-host-exec
You can use:
or
This will create a podman or docker command inside the distrobox that will
transparently execute the command on the host.
Using Distrobox as Main CLI
In case you want (like me) to use your container as the main CLI environment,
it comes handy to use gnome-terminal profiles to create a dedicated setup for it:
Personally, I just bind Ctrl-Alt-T to the Distrobox profile and Super+Enter
to the Host profile.
For other terminals, there are similar features (profiles) or you can set up a dedicated shortcut to launch a terminal directly in the distrobox
Using a Different Architecture
In case you want to run a container with a different architecture from your host,
you can leverage the use of qemu and support from podman/docker.
Install on your host the following dependencies:
- qemu
- qemu-user-static
- binfmt-support
Then you can easily run the image you like:
Using the GPU inside the Container
For Intel and AMD GPUs, the support is baked in, as the containers will install their latest available mesa/dri drivers.
For NVidia, you can use the --nvidia flag during create, see distrobox-create
documentation to discover how to use it.
Using nvidia-container-toolkit
Alternatively from the --nvidia flag, you can use NVidia’s own nvidia-container-toolkit.
After following the official guide to set nvidia-ctk up
you can use it from distrobox doing:
Slow Creation on Podman and Image Size Getting Bigger with Distrobox Create
For rootless podman 3.4.0 and upward, adding this to your ~/.config/containers/storage.conf
file will improve container creation speed and fix issues with images getting
bigger when using rootless containers.
[storage]
"overlay"
[storage.options.overlay]
"/usr/bin/fuse-overlayfs"
Note that this is necessary only on Kernel version older than 5.11 .
From version 5.11 onwards native overlayfs is supported and reports noticeable
gains in performance as explained HERE
Permission Problems When Using VirtualBox
If you have VirtualBox installed on your host, you may encounter some permission problems using rootless Podman:
Error: unable to start container "XYZ": runc: runc create failed: unable to start container process: error during container init: error mounting "/dev/vboxusb/002/005" to rootfs at "/dev/vboxusb/002/005": lstat /..../dev/vboxusb/002: permission denied: OCI permission denied
This is because a rootless container done with runc will not port the host’s groups
into the container.
The solution is to install crun from your package manager, and recreate your container.
crun supports the flag
run.oci.keep_original_groups=1
Which will allow porting the host’s group inside the container, thus making it possible for the rootless container to read vbox files.
Container save and Restore
To save, export and reuse an already configured container, you can leverage
podman save or docker save and podman import or docker import to
create snapshots of your environment.
To save a container to an image:
with podman:
|
with docker:
|
This will create a tar.gz of the container of your choice at that exact moment.
Now you can backup that archive or transfer it to another host, and to restore it just run
or
And create a new container based on that image:
And you’re good to go, now you can reproduce your personal environment everywhere in simple (and scriptable) steps.
Check Used Resources
- You can always check how much space a
distroboxis taking by usingpodmancommand:
podman system df -v or docker system df -v
Pre-Installing Additional Package Repositories
On Red Hat Enterprise Linux and its derivatives, the amount of packages in the base repositories is limited, and additional packages need to be brought in by enabling additional repositories such as EPEL.
You can use --init-hooks to automate this, but this does not solve the
issue for package installations done during initialization itself, e.g. if
the shell you use on the host is not available in the default repos (e.g.
fish).
Use the pre-initialization hooks for this:
Apply Resource Limitation on the Fly
Podman has --cpuset-cpus and --memory flags to apply limitation on how much resources a container can use. However,
these flags only work during container creation (podman create / podman run) and not after it’s created
(podman exec, which is used by Distrobox to execute commands inside of container), which means changing resource
limitation requires recreation of a container.
Nonetheless you can still apply resource limitation using systemd’s resource control functionality. It’s not recommended
to pass resource limitation arguments (e.g. --cpuset-cpus and --memory) to distrobox create --additional-flags
as systemd already provides much more flexible resource control functionality.
To list all distroboxes and their full IDs:
| | |
- Removing
--allflag will cause the output to only contain currently running distroboxes
To check your container status with systemctl:
-
Your distrobox needs to be running for its scope to present (e.g.
distrobox enterbefore running this command) -
Replace
$UUIDwith your container’s real full ID -
To make things easier when tweaking properties, optionally set a environment variable for the current shell:
bash/zsh:
UUID=XXXXXXXXXfish:
Everything provided by systemd.resource-control could be applied to your distrobox. For example:
To make your distrobox only run on CPU0 and CPU1:
To hard throttle your distrobox to not use above 20% of CPU:
To limit your distrobox’s maximum amount of memory:
To give your distrobox less IO bandwidth when IO is overloaded:
IOWeightaccepts value from1to10000, higher means more bandwidth.
To see all applicable properties:
Changes are transient, meaning you lose the resource limitation properties when distrobox is stopped and restarted.
To make certain changes persistent, first check the currently active properties:
Look for the Drop-In lines. Something like this should be shown:
Move the transient overrides to persistent overrides:
- Replace
$(id -u)with your real user id if it did not get expanded properly. 50-AllowedCPUs.confis only an example. Replace it with something you want to keep persistently.
Then reload systemd daemon to apply the changes:
Copy Text to Host Clipboard
To copy/yank text from the container to the host clipboard you need to install
xsel in the container for Xorg hosts or wlroots for wayland hosts.