From 45fd8fc72beccf27ee910ae0e1bc5baa93e3502a Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Wed, 17 Feb 2021 09:34:27 +0200 Subject: [PATCH 1/7] Include the nano default editor Since Fedora 33, `nano` is the default editor[0]. It needs to be included in the fedora-toolbox image to have the standard Fedora experience inside the container. https://fedoraproject.org/wiki/Changes/UseNanoByDefault). --- extra-packages | 1 + 1 file changed, 1 insertion(+) diff --git a/extra-packages b/extra-packages index 942271c..12fe02f 100644 --- a/extra-packages +++ b/extra-packages @@ -20,6 +20,7 @@ man-db man-pages mlocate mtr +nano-default-editor nss-mdns openssh-clients passwd From ab7ad04282d83549a83bd6acfed75a7a373d8123 Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Tue, 29 Jun 2021 16:21:26 +0200 Subject: [PATCH 2/7] Add bc and update README.md --- README.md | 165 ++++++++++++++++++++++++++++++++++++++++++------- extra-packages | 1 + 2 files changed, 142 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index a602a07..117528e 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,158 @@ -# Toolbox — Unprivileged development environment - -[Toolbox](https://github.com/debarshiray/toolbox) is a tool that offers a -familiar RPM based environment for developing and debugging software that runs -fully unprivileged using [Podman](https://podman.io/). - -The toolbox container is a fully *mutable* container; when you see -`yum install ansible` for example, that's something you can do inside your -toolbox container, without affecting the base operating system. +[Toolbox](https://github.com/containers/toolbox) is a tool for Linux operating +systems, which allows the use of containerized command line environments. It is +built on top of [Podman](https://podman.io/) and other standard container +technologies from [OCI](https://opencontainers.org/). This is particularly useful on -[OSTree](https://ostree.readthedocs.io/en/latest/) based Fedora systems like -[Silverblue](https://silverblue.fedoraproject.org/). The intention of these +[OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like +[Fedora CoreOS](https://coreos.fedoraproject.org/) and +[Silverblue](https://silverblue.fedoraproject.org/). The intention of these systems is to discourage installation of software on the host, and instead -install software as (or in) containers. +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. -However, this tool doesn't *require* using an OSTree based system — it -works equally well if you're running e.g. existing Fedora Workstation or -Server, and that's a useful way to incrementally adopt containerization. +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](https://www.opencontainers.org/) -image. On Fedora this is the `fedora-toolbox` image. This image is then -customized for the current user to create a toolbox container that seamlessly -integrates with the rest of the operating system. +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: -``` +```console [user@hostname ~]$ toolbox create +Created container: fedora-toolbox-33 +Enter with: toolbox enter [user@hostname ~]$ ``` -This will create a container, and an image, called -`fedora-toolbox-:` that's specifically customised -for your host user. +This will create a container called `fedora-toolbox-`. ### Enter the toolbox: -``` +```console [user@hostname ~]$ toolbox enter -🔹[user@toolbox ~]$ +⬢[user@toolbox ~]$ +``` + +### Remove a toolbox container: +```console +[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: +```console +[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](https://github.com/containers/toolbox/blob/main/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](https://www.opencontainers.org/) image called +`-toolbox:`, where `` and `` 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 `/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](https://github.com/containers/toolbox/issues/new) 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: +```Dockerfile +LABEL com.github.containers.toolbox="true" \ + com.github.debarshiray.toolbox="true" ``` diff --git a/extra-packages b/extra-packages index 12fe02f..a639e09 100644 --- a/extra-packages +++ b/extra-packages @@ -1,4 +1,5 @@ bash-completion +bc bzip2 diffutils dnf-plugins-core From 8f2d538a4d601e4bcf3275f260441a055a0b65e4 Mon Sep 17 00:00:00 2001 From: Oliver Gutierrez Date: Fri, 9 Jul 2021 10:07:57 +0100 Subject: [PATCH 3/7] Added iproute package --- extra-packages | 1 + 1 file changed, 1 insertion(+) diff --git a/extra-packages b/extra-packages index a639e09..34ee156 100644 --- a/extra-packages +++ b/extra-packages @@ -11,6 +11,7 @@ gnupg gnupg2-smime gvfs-client hostname +iproute iputils jwhois keyutils From 76aeb34ee9d8a700478fb9076e199433212deace Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Thu, 25 Nov 2021 19:46:14 +0100 Subject: [PATCH 4/7] Ensure that coreutils-single is replaced by coreutils-full It's true that the fedora base images no longer come with coreutils-single, but they used to, and the ubi base images still do. Therefore, it's worth being extra defensive about this. It's better to make the build system execute one extra redundant command than expose users to a bug because of a change that snuck in unnoticed. This reverts commit a2171d8742b18b65e22119bf789871b97f000455. https://github.com/containers/toolbox/pull/931 --- Dockerfile | 1 + 1 file changed, 1 insertion(+) diff --git a/Dockerfile b/Dockerfile index 3d0ef8a..fae143c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,6 +13,7 @@ LABEL com.github.containers.toolbox="true" \ COPY README.md / RUN sed -i '/tsflags=nodocs/d' /etc/dnf/dnf.conf +RUN dnf -y swap coreutils-single coreutils-full COPY missing-docs / RUN dnf -y reinstall $( Date: Thu, 25 Nov 2021 19:48:38 +0100 Subject: [PATCH 5/7] extra-packages: Avoid losing mount(8) by accident The util-linux package was added to ensure the presence of the mount(8) command. Currently the package is already pulled in by various dependencies. Therefore, it doesn't increase the size of the image, but serves as a safeguard against any inadvertent changes. Note that starting from Fedora 35 onwards, the fedora base images no longer have mount(8), which increases the importance of this change. https://github.com/containers/toolbox/issues/929 --- extra-packages | 1 + 1 file changed, 1 insertion(+) diff --git a/extra-packages b/extra-packages index 34ee156..105f5b0 100644 --- a/extra-packages +++ b/extra-packages @@ -36,6 +36,7 @@ time traceroute tree unzip +util-linux vte-profile wget which From 8776977ffdde6998e249e08a86f72ced4e00dc2c Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Wed, 1 Dec 2021 15:16:13 +0100 Subject: [PATCH 6/7] Remove misleading and redundant CMD 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 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" ] [1] Toolbox commit 5cc2678a3677af44 https://github.com/containers/toolbox/commit/5cc2678a3677af44 [2] https://docs.fedoraproject.org/en-US/containers/guidelines/creation/ [3] Toolbox commit 8b84b5e4604921fa https://github.com/containers/toolbox/pull/160 [4] https://docs.docker.com/engine/reference/builder/#cmd https://github.com/containers/toolbox/issues/885 --- Dockerfile | 2 -- 1 file changed, 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index fae143c..0db3c09 100644 --- a/Dockerfile +++ b/Dockerfile @@ -24,5 +24,3 @@ RUN dnf -y install $( Date: Wed, 1 Dec 2021 16:55:15 +0100 Subject: [PATCH 7/7] Make locate(1) opt-in by default Currently, the entry point of a Toolbox container runs updatedb(8) on start-up, which can be very I/O intensive. This might be a hindrance when troubleshooting performance problems on a host, or when re-creating containers somewhat more frequently. Users can install the mlocate RPM and restart their containers to enable locate(1). https://github.com/containers/toolbox/pull/938 --- extra-packages | 1 - 1 file changed, 1 deletion(-) diff --git a/extra-packages b/extra-packages index 105f5b0..52bf3f3 100644 --- a/extra-packages +++ b/extra-packages @@ -20,7 +20,6 @@ less lsof man-db man-pages -mlocate mtr nano-default-editor nss-mdns