cfffb72fb0
There's no need to specify a CMD in a Toolbox image because it's specified by 'toolbox create', through 'podman create', when creating a container. A CMD was specified [1] because the Fedora Container Guidelines requires it [2]. The idea behind the guidelines is that the right thing should happen when one runs: $ podman run <image> However, that only makes sense for images targeting single service containers. Toolbox containers and images are different - they are not meant to be used like that to run a single one-off service. Conceptually, 'running' a Toolbox container is expected to provide the user with a reasonable interactive command line experience. Arguably, that means offering something like /bin/bash, not /bin/sh. Also, note that when the CMD was introduced [1], Toolbox containers were actually created, through 'podman create', with /bin/sh as their entry points. So, it did make some sense. However, things have changed since then [3]. The entry point is now 'toolbox init-container'. It's not possible to mention it in the Toolbox image because the /usr/bin/toolbox binary isn't present in the image, and it's not meant to be present. Therefore, today, /bin/sh is simply not the right fit for a Toolbox image's CMD. A better option would be /bin/bash. Note that the fedora base images have their CMD set to /bin/bash, which is inherited by the fedora-toolbox images. So, there are two options. Either repeat the same CMD in the fedora-toolbox images and satisfy the guidelines, or take some liberties and let the CMD be inherited from the fedora base images. This commit takes the latter option. People tend to use the fedora-toolbox images as the starting point for other custom Toolbox images, sometimes for other operating system distributions. It's better to keep them minimal to avoid implying extra requirements. In this case, the CMD is an abstract concept, and the actual entry point is 'toolbox init-container' as specified by 'toolbox create'. Specifying /bin/bash might discourage people from creating custom images that are only meant to have /bin/zsh. Also, note that the current CMD was actually '/bin/sh -c /bin/sh', not /bin/sh. Unless a CMD is specified as an array of command line arguments, it's passed as a single argument to '/bin/sh -c' [4]. So, this: CMD foo bar ... is the same as: CMD [ "/bin/sh", "-c", "foo bar" ] Only the images for currently maintained Fedoras (ie., 34 and 35) were updated. This reverts commit |
||
|---|---|---|
| .. | ||
| Containerfile | ||
| extra-packages | ||
| missing-docs | ||
| README.md | ||
Toolbox is a tool for Linux operating systems, which allows the use of containerized command line environments. It is built on top of Podman and other standard container technologies from OCI.
This is particularly useful on OSTree based operating systems like Fedora CoreOS and Silverblue. The intention of these systems is to discourage installation of software on the host, and instead install software as (or in) containers — they mostly don't even have package managers like DNF or YUM. This makes it difficult to set up a development environment or install tools for debugging in the usual way.
Toolbox solves this problem by providing a fully mutable container within
which one can install their favourite development and debugging tools, editors
and SDKs. For example, it's possible to do yum install ansible without
affecting the base operating system.
However, this tool doesn't require using an OSTree based system. It works equally well on Fedora Workstation and Server, and that's a useful way to incrementally adopt containerization.
The toolbox environment is based on an OCI
image. On Fedora this is the fedora-toolbox image. This image is used to
create a toolbox container that seamlessly integrates with the rest of the
operating system by providing access to the user's home directory, the Wayland
and X11 sockets, networking (including Avahi), removable devices (like USB
sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev
database, etc..
Installation
Toolbox is installed by default on Fedora Silverblue. On other operating
systems it's just a matter of installing the toolbox package.
Usage
Create your toolbox container:
[user@hostname ~]$ toolbox create
Created container: fedora-toolbox-33
Enter with: toolbox enter
[user@hostname ~]$
This will create a container called fedora-toolbox-<version-id>.
Enter the toolbox:
[user@hostname ~]$ toolbox enter
⬢[user@toolbox ~]$
Remove a toolbox container:
[user@hostname ~]$ toolbox rm fedora-toolbox-33
[user@hostname ~]$
Dependencies and Building
Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build system.
The following dependencies are required to build it:
- meson
- go-md2man
- systemd
- go
- ninja
The following dependencies enable various optional features:
- bash-completion
It can be built and installed as any other typical Meson-based project:
[user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir
[user@hostname toolbox]$ ninja -C builddir
[user@hostname toolbox]$ sudo ninja -C builddir install
Toolbox is written in Go. Consult the src/go.mod file for a full list of all the Go dependencies.
By default, Toolbox uses Go modules and all the required Go packages are automatically downloaded as part of the build. There's no need to worry about the Go dependencies, unless the build environment doesn't have network access or any such peculiarities.
Distro support
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.
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/homeis a symbolic link to/var/homepasswd(1)readlink(1)rm(1)rmdir(1): for hosts where/homeis a symbolic link to/var/homesleep(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 thesudoorwheelgroups, 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 thenullokoption to thePAM(8)configuration, or by add theNOPASSWDtag to thesudoers(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.