Custom images

Custom toolbox images

By default, Toolbox creates the container using an OCI image called <ID>-toolbox:<VERSION-ID>, where <ID> and <VERSION-ID> are taken from the host's /usr/lib/os-release. For example, the default image on a Fedora 33 host would be fedora-toolbox:33.

This default can be overridden by the --image option in toolbox create, but operating system distributors should provide an adequately configured default image to ensure a smooth user experience.

You can create your custom toolbox images like any other container image as long as it meet some requirements.

Image requirements

Toolbox customizes newly created containers in a certain way. This requires certain tools and paths to be present and have certain characteristics inside the OCI image.

Tools:

• getent(1)
• id(1)
• ln(1)
• mkdir(1): for hosts where /home is a symbolic link to /var/home
• passwd(1)
• readlink(1)
• rm(1)
• rmdir(1): for hosts where /home is a symbolic link to /var/home
• sleep(1)
• test(1)
• touch(1)
• unlink(1)
• useradd(8)
• usermod(8)

Paths:

• /etc/host.conf: optional, if present not a bind mount
• /etc/hosts: optional, if present not a bind mount
• /etc/krb5.conf.d: directory, not a bind mount
• /etc/localtime: optional, if present not a bind mount
• /etc/machine-id: optional, not a bind mount
• /etc/resolv.conf: optional, if present not a bind mount
• /etc/timezone: optional, if present not a bind mount

Toolbox enables sudo(8) access inside containers. The following is necessary for that to work:

• The image should have sudo(8) enabled for users belonging to either the sudo or wheel groups, and the group itself should exist. File an issue if you really need support for a different group. However, it's preferable to keep this list as short as possible.

• The image should allow empty passwords for sudo(8). This can be achieved by either adding the nullok option to the PAM(8) configuration, or by add the NOPASSWD tag to the sudoers(5) configuration.

Since Toolbox only works with OCI images that fulfill certain requirements, it will refuse images that aren't tagged with com.github.containers.toolbox="true" and com.github.debarshiray.toolbox="true" labels. These labels are meant to be used by the maintainer of the image to indicate that they have read this document and tested that the image works with Toolbox. You can use the following snippet in a Dockerfile for this:

LABEL com.github.containers.toolbox="true"

The label com.github.debarshiray.toolbox="true" was used in previous versions of toolbox but is currently deprecated.