From c0c0a99f1c30f400ed3e4c9163857f427698f919 Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Fri, 30 Oct 2020 19:45:38 +0100 Subject: [PATCH 1/7] extra-packages: Allow X11 clients to run as root If an X11 client is started inside a 'su -' session, then xauth(1) needs to be present so that pam_xauth.so can add a new XAUTHORITY environment variable to the 'su -' session. https://github.com/containers/toolbox/pull/572 --- extra-packages | 1 + 1 file changed, 1 insertion(+) diff --git a/extra-packages b/extra-packages index a4c839e..95ecebb 100644 --- a/extra-packages +++ b/extra-packages @@ -35,5 +35,6 @@ vte-profile wget which words +xorg-x11-xauth xz zip From 66aec2fc4e62276b3fbf291dc142090deb54bcbc Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Sun, 15 Nov 2020 23:20:13 +0100 Subject: [PATCH 2/7] Make locate(1) work inside toolbox containers This reverts commit bd035973c9f49a96256951f3e2ec454a0973abfd. https://github.com/containers/toolbox/issues/391 --- extra-packages | 1 + 1 file changed, 1 insertion(+) diff --git a/extra-packages b/extra-packages index 95ecebb..0597b1b 100644 --- a/extra-packages +++ b/extra-packages @@ -18,6 +18,7 @@ less lsof man-db man-pages +mlocate mtr openssh-clients passwd From 0285e9a1ee3d494b7883f5a363f3caea64765bde Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Sun, 15 Nov 2020 23:11:40 +0100 Subject: [PATCH 3/7] Give access to Avahi to resolve the .local mDNS domain The nss-mdns plugin for the GNU Name Service Switch (or NSS) functionality of the GNU C Library is necessary to resolve the .local mDNS domain. The plugin talks to the Avahi daemon running on the host to resolve the names. https://github.com/containers/toolbox/issues/209 --- extra-packages | 1 + 1 file changed, 1 insertion(+) diff --git a/extra-packages b/extra-packages index 0597b1b..942271c 100644 --- a/extra-packages +++ b/extra-packages @@ -20,6 +20,7 @@ man-db man-pages mlocate mtr +nss-mdns openssh-clients passwd pigz From d27ac0dca03b416f225eba056054d07e81873055 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20M=C3=ADchal?= Date: Sun, 27 Sep 2020 23:58:37 +0200 Subject: [PATCH 4/7] Simplify image name Currently the images are named as "f/fedora-toolbox". This is troublesome for new users of toolbox (even those with some background to containers) because everywhere the image is advertised or talked about as "fedora-toolbox". This is taken care of by Toolbox CLI but has no effect on Podman itself (or any other tool capable of working with OCI images). Another pain point is in the Fedora registry[0] all "fedora-toolbox" images get a different entry for every version of Fedora. There is no single place for all "fedora-toolbox" images. With this change I propose to only use "fedora-toolbox" as the name of the container and make use of VERSION to distinguish between versions of Fedora. Currently when you go to the Fedora registry and find an entry for "fedora-toolbox" you'll see all previous images. I believe that with this change that "feature" will be lost. But I personally find that "feature" to be rather confusing because what usually a user wants the latest version of a container (I partially base this statement on the fact that most images are versioned this way; e.g. Ubuntu on Docker Hub[1]). [0] https://registry.fedoraproject.org/ [1] https://hub.docker.com/_/ubuntu --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index 2a296f2..151e045 100644 --- a/Dockerfile +++ b/Dockerfile @@ -4,7 +4,7 @@ ENV NAME=fedora-toolbox VERSION=33 LABEL com.github.containers.toolbox="true" \ com.github.debarshiray.toolbox="true" \ com.redhat.component="$NAME" \ - name="$FGC/$NAME" \ + name="$NAME" \ version="$VERSION" \ usage="This image is meant to be used with the toolbox command" \ summary="Base image for creating Fedora toolbox containers" \ From e01529c7b4a725d97f1f273af4ce7cd45179be5b Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Wed, 17 Feb 2021 09:34:27 +0200 Subject: [PATCH 5/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 b8e94819138d6546fb96d0431b25e12aa7af50fe Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Tue, 29 Jun 2021 16:22:47 +0200 Subject: [PATCH 6/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 2c35772d298905b9ef6bc3014fc6b512521d9f17 Mon Sep 17 00:00:00 2001 From: Oliver Gutierrez Date: Fri, 9 Jul 2021 10:07:34 +0100 Subject: [PATCH 7/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