├── .github └── workflows │ ├── alpine.yml │ ├── archlinux.yml │ ├── centos.yml │ ├── kalilinux.yml │ ├── tumbleweed.yml │ └── ubuntu.yml ├── .gitignore ├── README.md ├── build-all.sh ├── docs └── sample.png ├── images ├── alpine │ ├── 3.15 │ │ ├── Containerfile │ │ └── toolbox-sudo │ └── 3.16 │ │ ├── Containerfile │ │ └── toolbox-sudo ├── archlinux │ └── latest │ │ ├── Containerfile │ │ ├── README.md │ │ ├── extra-packages │ │ └── missing-docs ├── centos │ └── 8 │ │ ├── Containerfile │ │ └── toolbox-sudo ├── gentoo │ └── latest │ │ ├── Containerfile │ │ └── README.md ├── kalilinux │ └── latest │ │ ├── Containerfile │ │ ├── README.md │ │ ├── extra-packages │ │ └── missing-docs ├── tumbleweed │ └── latest │ │ ├── Containerfile │ │ └── README.md └── ubuntu │ ├── 20.04 │ ├── Containerfile │ ├── README.md │ ├── extra-packages │ ├── missing-docs │ └── nsswitch.conf │ └── 22.04 │ ├── Containerfile │ ├── README.md │ ├── extra-packages │ ├── missing-docs │ └── nsswitch.conf ├── publish-all.sh └── util ├── build.sh └── publish.sh /.github/workflows/alpine.yml: -------------------------------------------------------------------------------- 1 | name: build alpine toolbox container images 2 | 3 | on: 4 | schedule: 5 | - cron: '45 5 * * *' 6 | push: 7 | branches: [ "master" ] 8 | 9 | env: 10 | REGISTRY_USER: ${{ github.actor }} 11 | REGISTRY_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }} 12 | TOOLBOX_REPO: registry.hub.docker.com/${{ github.repository_owner }} 13 | 14 | jobs: 15 | publish: 16 | strategy: 17 | matrix: 18 | version: [3.15, 3.16] 19 | runs-on: ubuntu-latest 20 | steps: 21 | - uses: actions/checkout@v3 22 | - name: Log in to ghcr.io 23 | uses: redhat-actions/podman-login@v1 24 | with: 25 | username: ${{ env.REGISTRY_USER }} 26 | password: ${{ env.REGISTRY_PASSWORD }} 27 | registry: ${{ env.TOOLBOX_REPO }} 28 | 29 | - name: publish toolbox container images 30 | run: ./util/publish.sh alpine/${{ matrix.version }} 31 | -------------------------------------------------------------------------------- /.github/workflows/archlinux.yml: -------------------------------------------------------------------------------- 1 | name: build archlinux-toolbox container image 2 | 3 | on: 4 | schedule: 5 | - cron: '45 5 * * *' 6 | push: 7 | branches: [ "master" ] 8 | 9 | env: 10 | REGISTRY_USER: ${{ github.actor }} 11 | REGISTRY_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }} 12 | TOOLBOX_REPO: registry.hub.docker.com/${{ github.repository_owner }} 13 | 14 | jobs: 15 | publish-latest: 16 | runs-on: ubuntu-latest 17 | steps: 18 | - uses: actions/checkout@v3 19 | - name: Log in to ghcr.io 20 | uses: redhat-actions/podman-login@v1 21 | with: 22 | username: ${{ env.REGISTRY_USER }} 23 | password: ${{ env.REGISTRY_PASSWORD }} 24 | registry: ${{ env.TOOLBOX_REPO }} 25 | 26 | - name: publish toolbox container images 27 | run: ./util/publish.sh archlinux/latest 28 | -------------------------------------------------------------------------------- /.github/workflows/centos.yml: -------------------------------------------------------------------------------- 1 | name: build centos toolbox container images 2 | 3 | on: 4 | schedule: 5 | - cron: '45 5 * * *' 6 | push: 7 | branches: [ "master" ] 8 | 9 | env: 10 | REGISTRY_USER: ${{ github.actor }} 11 | REGISTRY_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }} 12 | TOOLBOX_REPO: registry.hub.docker.com/${{ github.repository_owner }} 13 | 14 | jobs: 15 | publish: 16 | strategy: 17 | matrix: 18 | version: [8] 19 | runs-on: ubuntu-latest 20 | steps: 21 | - uses: actions/checkout@v3 22 | - name: Log in to ghcr.io 23 | uses: redhat-actions/podman-login@v1 24 | with: 25 | username: ${{ env.REGISTRY_USER }} 26 | password: ${{ env.REGISTRY_PASSWORD }} 27 | registry: ${{ env.TOOLBOX_REPO }} 28 | 29 | - name: publish toolbox container images 30 | run: ./util/publish.sh centos/${{ matrix.version }} 31 | -------------------------------------------------------------------------------- /.github/workflows/kalilinux.yml: -------------------------------------------------------------------------------- 1 | name: build kalilinux toolbox container images 2 | 3 | on: 4 | schedule: 5 | - cron: '45 5 * * *' 6 | push: 7 | branches: [ "master" ] 8 | 9 | env: 10 | REGISTRY_USER: ${{ github.actor }} 11 | REGISTRY_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }} 12 | TOOLBOX_REPO: registry.hub.docker.com/${{ github.repository_owner }} 13 | 14 | jobs: 15 | publish: 16 | strategy: 17 | matrix: 18 | version: [latest] 19 | runs-on: ubuntu-latest 20 | steps: 21 | - uses: actions/checkout@v3 22 | - name: Log in to ghcr.io 23 | uses: redhat-actions/podman-login@v1 24 | with: 25 | username: ${{ env.REGISTRY_USER }} 26 | password: ${{ env.REGISTRY_PASSWORD }} 27 | registry: ${{ env.TOOLBOX_REPO }} 28 | 29 | - name: publish toolbox container images 30 | run: ./util/publish.sh kalilinux/${{ matrix.version }} 31 | -------------------------------------------------------------------------------- /.github/workflows/tumbleweed.yml: -------------------------------------------------------------------------------- 1 | name: build tumbleweed-toolbox container image 2 | 3 | on: 4 | schedule: 5 | - cron: '45 5 * * *' 6 | push: 7 | branches: [ "master" ] 8 | 9 | env: 10 | REGISTRY_USER: ${{ github.actor }} 11 | REGISTRY_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }} 12 | TOOLBOX_REPO: registry.hub.docker.com/${{ github.repository_owner }} 13 | 14 | jobs: 15 | publish-latest: 16 | runs-on: ubuntu-latest 17 | steps: 18 | - uses: actions/checkout@v3 19 | - name: Log in to ghcr.io 20 | uses: redhat-actions/podman-login@v1 21 | with: 22 | username: ${{ env.REGISTRY_USER }} 23 | password: ${{ env.REGISTRY_PASSWORD }} 24 | registry: ${{ env.TOOLBOX_REPO }} 25 | 26 | - name: publish toolbox container images 27 | run: ./util/publish.sh tumbleweed/latest 28 | -------------------------------------------------------------------------------- /.github/workflows/ubuntu.yml: -------------------------------------------------------------------------------- 1 | name: build ubuntu toolbox container images 2 | 3 | on: 4 | schedule: 5 | - cron: '45 5 * * *' 6 | push: 7 | branches: [ "master" ] 8 | 9 | env: 10 | REGISTRY_USER: ${{ github.actor }} 11 | REGISTRY_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }} 12 | TOOLBOX_REPO: registry.hub.docker.com/${{ github.repository_owner }} 13 | 14 | jobs: 15 | publish: 16 | strategy: 17 | matrix: 18 | version: [22.04, 20.04] 19 | runs-on: ubuntu-latest 20 | steps: 21 | - uses: actions/checkout@v3 22 | - name: Log in to ghcr.io 23 | uses: redhat-actions/podman-login@v1 24 | with: 25 | username: ${{ env.REGISTRY_USER }} 26 | password: ${{ env.REGISTRY_PASSWORD }} 27 | registry: ${{ env.TOOLBOX_REPO }} 28 | 29 | - name: publish toolbox container images 30 | run: ./util/publish.sh ubuntu/${{ matrix.version }} 31 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.sw[opqrstuvwxyz] 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | #### Toolbox Images: Container Images for usage with [toolbox](https://github.com/containers/toolbox) 2 | 3 | Here we have a collection of container images for usage with the `toolbox` command. This is an attempt at providing more 4 | feature parity with regard to toolboxes for distributions other than Fedora. 5 | 6 | ### Supported Distributions 7 | 8 | ``` 9 | . 10 | ├── alpine 11 | │   ├── 3.15 12 | │   └── 3.16 13 | ├── archlinux 14 | │   └── latest 15 | ├── centos 16 | │   └── 8 17 | ├── kalilinux 18 | │   └── latest 19 | ├── tumbleweed 20 | │   └── latest 21 | └── ubuntu 22 | ├── 20.04 23 | └── 22.04 24 | ``` 25 | 26 | ![screenshot of toolboxes of different distros](docs/sample.png) 27 | 28 | 29 | ### How do I use this? 30 | 31 | You can use the images by doing `toolbox create -i docker.io/akdev1l/${distro}-toolbox:${version}`, for example: 32 | 33 | ``` 34 | [akdev@canzuk toolbox-images]$ toolbox create -i docker.io/akdev1l/ubuntu-toolbox:22.04 35 | Created container: ubuntu-toolbox-22.04 36 | Enter with: toolbox enter ubuntu-toolbox-22.04 37 | [akdev@canzuk toolbox-images]$ toolbox enter ubuntu-toolbox-22.04 38 | ``` 39 | 40 | **Note: For Rolling Release distributions like Arch Linux and OpenSuSE Tumbleweed the version is always `latest`.** 41 | 42 | ### Prior Work 43 | 44 | 1. [Original Containerfiles](https://github.com/MainKt/toolbox/tree/main/images) Thanks to [Main.kt](https://github.com/MainKt). 45 | 46 | -------------------------------------------------------------------------------- /build-all.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | find images -type f -name 'Containerfile' | while read container_file; do 4 | image_name="$(dirname "${container_file}")" 5 | image_name="${image_name/images\//}" 6 | ./util/build.sh "${image_name}" 7 | done 8 | -------------------------------------------------------------------------------- /docs/sample.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/akdev1l/toolbox-images/82bb3fdabf2a78c6f8b33957852b8b6d5da7a43a/docs/sample.png -------------------------------------------------------------------------------- /images/alpine/3.15/Containerfile: -------------------------------------------------------------------------------- 1 | FROM alpine:3.15 2 | 3 | ENV NAME=alpine-toolbox VERSION=3.15 4 | LABEL com.github.containers.toolbox="true" 5 | 6 | RUN apk add sudo libcap shadow bash ncurses-terminfo && ln -s /etc/os-release /usr/lib/os-release 7 | COPY ./toolbox-sudo /etc/sudoers.d/toolbox-sudo 8 | -------------------------------------------------------------------------------- /images/alpine/3.15/toolbox-sudo: -------------------------------------------------------------------------------- 1 | %wheel ALL=(ALL) NOPASSWD: ALL 2 | -------------------------------------------------------------------------------- /images/alpine/3.16/Containerfile: -------------------------------------------------------------------------------- 1 | FROM alpine:3.16 2 | 3 | ENV NAME=alpine-toolbox VERSION=3.16 4 | LABEL com.github.containers.toolbox="true" 5 | 6 | RUN apk add sudo libcap shadow bash ncurses-terminfo && ln -s /etc/os-release /usr/lib/os-release 7 | COPY ./toolbox-sudo /etc/sudoers.d/toolbox-sudo 8 | -------------------------------------------------------------------------------- /images/alpine/3.16/toolbox-sudo: -------------------------------------------------------------------------------- 1 | %wheel ALL=(ALL) NOPASSWD: ALL 2 | -------------------------------------------------------------------------------- /images/archlinux/latest/Containerfile: -------------------------------------------------------------------------------- 1 | FROM archlinux 2 | 3 | ENV NAME=archlinux-toolbox VERSION=latest 4 | LABEL com.github.containers.toolbox="true" 5 | 6 | COPY README.md / 7 | 8 | RUN pacman --noconfirm -Syu 9 | 10 | COPY missing-docs / 11 | RUN pacman --noconfirm -Syu $( /etc/sudoers.d/toolbox 21 | -------------------------------------------------------------------------------- /images/archlinux/latest/README.md: -------------------------------------------------------------------------------- 1 | Toolbox logo landscape 2 | 3 | [![Zuul](https://zuul-ci.org/gated.svg)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers/toolbox) 4 | [![Daily Pipeline](https://softwarefactory-project.io/zuul/api/tenant/local/badge?project=containers/toolbox&pipeline=periodic)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers%2Ftoolbox&pipeline=periodic) 5 | 6 | [![Arch Linux package](https://img.shields.io/archlinux/v/community/x86_64/toolbox)](https://www.archlinux.org/packages/community/x86_64/toolbox/) 7 | [![Fedora package](https://img.shields.io/fedora/v/toolbox/rawhide)](https://src.fedoraproject.org/rpms/toolbox/) 8 | 9 | [Toolbox](https://github.com/containers/toolbox) is a tool for Linux operating 10 | systems, which allows the use of containerized command line environments. It is 11 | built on top of [Podman](https://podman.io/) and other standard container 12 | technologies from [OCI](https://opencontainers.org/). 13 | 14 | This is particularly useful on 15 | [OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like 16 | [Fedora CoreOS](https://coreos.fedoraproject.org/) and 17 | [Silverblue](https://silverblue.fedoraproject.org/). The intention of these 18 | systems is to discourage installation of software on the host, and instead 19 | install software as (or in) containers — they mostly don't even have package 20 | managers like DNF or YUM. This makes it difficult to set up a development 21 | environment or install tools for debugging in the usual way. 22 | 23 | Toolbox solves this problem by providing a fully mutable container within 24 | which one can install their favourite development and debugging tools, editors 25 | and SDKs. For example, it's possible to do `yum install ansible` without 26 | affecting the base operating system. 27 | 28 | However, this tool doesn't *require* using an OSTree based system. It works 29 | equally well on Fedora Workstation and Server, and that's a useful way to 30 | incrementally adopt containerization. 31 | 32 | The toolbox environment is based on an [OCI](https://www.opencontainers.org/) 33 | image. On Fedora this is the `fedora-toolbox` image. This image is used to 34 | create a toolbox container that seamlessly integrates with the rest of the 35 | operating system by providing access to the user's home directory, the Wayland 36 | and X11 sockets, networking (including Avahi), removable devices (like USB 37 | sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev 38 | database, etc.. 39 | 40 | 41 | ## Installation 42 | 43 | Toolbox is installed by default on Fedora Silverblue. On other operating 44 | systems it's just a matter of installing the `toolbox` package. 45 | 46 | ## Usage 47 | 48 | ### Create your toolbox container: 49 | ```console 50 | [user@hostname ~]$ toolbox create 51 | Created container: fedora-toolbox-33 52 | Enter with: toolbox enter 53 | [user@hostname ~]$ 54 | ``` 55 | This will create a container called `fedora-toolbox-`. 56 | 57 | ### Enter the toolbox: 58 | ```console 59 | [user@hostname ~]$ toolbox enter 60 | ⬢[user@toolbox ~]$ 61 | ``` 62 | 63 | ### Remove a toolbox container: 64 | ```console 65 | [user@hostname ~]$ toolbox rm fedora-toolbox-33 66 | [user@hostname ~]$ 67 | ``` 68 | 69 | ## Dependencies and Building 70 | 71 | Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build 72 | system. 73 | 74 | The following dependencies are required to build it: 75 | - meson 76 | - go-md2man 77 | - systemd 78 | - go 79 | - ninja 80 | 81 | The following dependencies enable various optional features: 82 | - bash-completion 83 | 84 | It can be built and installed as any other typical Meson-based project: 85 | ```console 86 | [user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir 87 | [user@hostname toolbox]$ ninja -C builddir 88 | [user@hostname toolbox]$ sudo ninja -C builddir install 89 | ``` 90 | 91 | Toolbox is written in Go. Consult the 92 | [src/go.mod](https://github.com/containers/toolbox/blob/main/src/go.mod) file 93 | for a full list of all the Go dependencies. 94 | 95 | By default, Toolbox uses Go modules and all the required Go packages are 96 | automatically downloaded as part of the build. There's no need to worry about 97 | the Go dependencies, unless the build environment doesn't have network access 98 | or any such peculiarities. 99 | 100 | ## Distro support 101 | 102 | By default, Toolbox creates the container using an 103 | [OCI](https://www.opencontainers.org/) image called 104 | `-toolbox:`, where `` and `` are taken from the 105 | host's `/usr/lib/os-release`. For example, the default image on a Fedora 33 106 | host would be `fedora-toolbox:33`. 107 | 108 | This default can be overridden by the `--image` option in `toolbox create`, 109 | but operating system distributors should provide an adequately configured 110 | default image to ensure a smooth user experience. 111 | 112 | ## Image requirements 113 | 114 | Toolbox customizes newly created containers in a certain way. This requires 115 | certain tools and paths to be present and have certain characteristics inside 116 | the OCI image. 117 | 118 | Tools: 119 | * `getent(1)` 120 | * `id(1)` 121 | * `ln(1)` 122 | * `mkdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 123 | * `passwd(1)` 124 | * `readlink(1)` 125 | * `rm(1)` 126 | * `rmdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 127 | * `sleep(1)` 128 | * `test(1)` 129 | * `touch(1)` 130 | * `unlink(1)` 131 | * `useradd(8)` 132 | * `usermod(8)` 133 | 134 | Paths: 135 | * `/etc/host.conf`: optional, if present not a bind mount 136 | * `/etc/hosts`: optional, if present not a bind mount 137 | * `/etc/krb5.conf.d`: directory, not a bind mount 138 | * `/etc/localtime`: optional, if present not a bind mount 139 | * `/etc/machine-id`: optional, not a bind mount 140 | * `/etc/resolv.conf`: optional, if present not a bind mount 141 | * `/etc/timezone`: optional, if present not a bind mount 142 | 143 | Toolbox enables `sudo(8)` access inside containers. The following is necessary 144 | for that to work: 145 | 146 | * The image should have `sudo(8)` enabled for users belonging to either the 147 | `sudo` or `wheel` groups, and the group itself should exist. File an 148 | [issue](https://github.com/containers/toolbox/issues/new) if you really need 149 | support for a different group. However, it's preferable to keep this list as 150 | short as possible. 151 | 152 | * The image should allow empty passwords for `sudo(8)`. This can be achieved 153 | by either adding the `nullok` option to the `PAM(8)` configuration, or by 154 | add the `NOPASSWD` tag to the `sudoers(5)` configuration. 155 | 156 | Since Toolbox only works with OCI images that fulfill certain requirements, 157 | it will refuse images that aren't tagged with 158 | `com.github.containers.toolbox="true"` and 159 | `com.github.debarshiray.toolbox="true"` labels. These labels are meant to be 160 | used by the maintainer of the image to indicate that they have read this 161 | document and tested that the image works with Toolbox. You can use the 162 | following snippet in a Dockerfile for this: 163 | ```Dockerfile 164 | LABEL com.github.containers.toolbox="true" 165 | ``` 166 | The label `com.github.debarshiray.toolbox="true"` was used in previous versions 167 | of toolbox but is currently deprecated. 168 | -------------------------------------------------------------------------------- /images/archlinux/latest/extra-packages: -------------------------------------------------------------------------------- 1 | bash-completion 2 | bc 3 | bzip2 4 | diffutils 5 | findutils 6 | git 7 | gnupg 8 | iproute 9 | iputils 10 | keyutils 11 | less 12 | lsof 13 | man-db 14 | man-pages 15 | mtr 16 | nss-mdns 17 | nano 18 | pigz 19 | procps-ng 20 | rsync 21 | sudo 22 | tcpdump 23 | time 24 | traceroute 25 | tree 26 | unzip 27 | util-linux 28 | vim 29 | wget 30 | which 31 | words 32 | xorg-xauth 33 | xz 34 | zip -------------------------------------------------------------------------------- /images/archlinux/latest/missing-docs: -------------------------------------------------------------------------------- 1 | acl 2 | bash 3 | curl 4 | gawk 5 | grep 6 | gzip 7 | libcap 8 | openssl 9 | p11-kit 10 | pam 11 | python3 12 | rpm 13 | sed 14 | systemd 15 | tar -------------------------------------------------------------------------------- /images/centos/8/Containerfile: -------------------------------------------------------------------------------- 1 | FROM quay.io/centos/centos:stream8 2 | 3 | ENV NAME=centos-toolbox VERSION=8 4 | LABEL com.github.containers.toolbox="true" 5 | 6 | RUN dnf install -y sudo /usr/sbin/capsh /usr/sbin/usermod bash 7 | COPY ./toolbox-sudo /etc/sudoers.d/toolbox-sudo 8 | -------------------------------------------------------------------------------- /images/centos/8/toolbox-sudo: -------------------------------------------------------------------------------- 1 | %wheel ALL=(ALL) NOPASSWD: ALL 2 | -------------------------------------------------------------------------------- /images/gentoo/latest/Containerfile: -------------------------------------------------------------------------------- 1 | FROM registry.hub.docker.com/gentoo/portage:latest 2 | FROM registry.hub.docker.com/gentoo/stage3:systemd 3 | COPY --from=portage /var/db/repos/gentoo /var/db/repos/gentoo 4 | 5 | ENV NAME=gentoo-toolbox VERSION=latest 6 | LABEL com.github.containers.toolbox="true" 7 | 8 | COPY README.md / 9 | 10 | RUN emerge -qv sudo 11 | 12 | RUN rm -rf rm -f /var/tmp/portage/* /var/cache/distfiles/* /var/cache/binpkgs/* 13 | 14 | RUN echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/toolbox-sudo 15 | -------------------------------------------------------------------------------- /images/gentoo/latest/README.md: -------------------------------------------------------------------------------- 1 | Toolbox logo landscape 2 | 3 | [![Zuul](https://zuul-ci.org/gated.svg)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers/toolbox) 4 | [![Daily Pipeline](https://softwarefactory-project.io/zuul/api/tenant/local/badge?project=containers/toolbox&pipeline=periodic)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers%2Ftoolbox&pipeline=periodic) 5 | 6 | [![Arch Linux package](https://img.shields.io/archlinux/v/community/x86_64/toolbox)](https://www.archlinux.org/packages/community/x86_64/toolbox/) 7 | [![Fedora package](https://img.shields.io/fedora/v/toolbox/rawhide)](https://src.fedoraproject.org/rpms/toolbox/) 8 | 9 | [Toolbox](https://github.com/containers/toolbox) is a tool for Linux operating 10 | systems, which allows the use of containerized command line environments. It is 11 | built on top of [Podman](https://podman.io/) and other standard container 12 | technologies from [OCI](https://opencontainers.org/). 13 | 14 | This is particularly useful on 15 | [OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like 16 | [Fedora CoreOS](https://coreos.fedoraproject.org/) and 17 | [Silverblue](https://silverblue.fedoraproject.org/). The intention of these 18 | systems is to discourage installation of software on the host, and instead 19 | install software as (or in) containers — they mostly don't even have package 20 | managers like DNF or YUM. This makes it difficult to set up a development 21 | environment or install tools for debugging in the usual way. 22 | 23 | Toolbox solves this problem by providing a fully mutable container within 24 | which one can install their favourite development and debugging tools, editors 25 | and SDKs. For example, it's possible to do `yum install ansible` without 26 | affecting the base operating system. 27 | 28 | However, this tool doesn't *require* using an OSTree based system. It works 29 | equally well on Fedora Workstation and Server, and that's a useful way to 30 | incrementally adopt containerization. 31 | 32 | The toolbox environment is based on an [OCI](https://www.opencontainers.org/) 33 | image. On Fedora this is the `fedora-toolbox` image. This image is used to 34 | create a toolbox container that seamlessly integrates with the rest of the 35 | operating system by providing access to the user's home directory, the Wayland 36 | and X11 sockets, networking (including Avahi), removable devices (like USB 37 | sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev 38 | database, etc.. 39 | 40 | 41 | ## Installation 42 | 43 | Toolbox is installed by default on Fedora Silverblue. On other operating 44 | systems it's just a matter of installing the `toolbox` package. 45 | 46 | ## Usage 47 | 48 | ### Create your toolbox container: 49 | ```console 50 | [user@hostname ~]$ toolbox create 51 | Created container: fedora-toolbox-33 52 | Enter with: toolbox enter 53 | [user@hostname ~]$ 54 | ``` 55 | This will create a container called `fedora-toolbox-`. 56 | 57 | ### Enter the toolbox: 58 | ```console 59 | [user@hostname ~]$ toolbox enter 60 | ⬢[user@toolbox ~]$ 61 | ``` 62 | 63 | ### Remove a toolbox container: 64 | ```console 65 | [user@hostname ~]$ toolbox rm fedora-toolbox-33 66 | [user@hostname ~]$ 67 | ``` 68 | 69 | ## Dependencies and Building 70 | 71 | Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build 72 | system. 73 | 74 | The following dependencies are required to build it: 75 | - meson 76 | - go-md2man 77 | - systemd 78 | - go 79 | - ninja 80 | 81 | The following dependencies enable various optional features: 82 | - bash-completion 83 | 84 | It can be built and installed as any other typical Meson-based project: 85 | ```console 86 | [user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir 87 | [user@hostname toolbox]$ ninja -C builddir 88 | [user@hostname toolbox]$ sudo ninja -C builddir install 89 | ``` 90 | 91 | Toolbox is written in Go. Consult the 92 | [src/go.mod](https://github.com/containers/toolbox/blob/main/src/go.mod) file 93 | for a full list of all the Go dependencies. 94 | 95 | By default, Toolbox uses Go modules and all the required Go packages are 96 | automatically downloaded as part of the build. There's no need to worry about 97 | the Go dependencies, unless the build environment doesn't have network access 98 | or any such peculiarities. 99 | 100 | ## Distro support 101 | 102 | By default, Toolbox creates the container using an 103 | [OCI](https://www.opencontainers.org/) image called 104 | `-toolbox:`, where `` and `` are taken from the 105 | host's `/usr/lib/os-release`. For example, the default image on a Fedora 33 106 | host would be `fedora-toolbox:33`. 107 | 108 | This default can be overridden by the `--image` option in `toolbox create`, 109 | but operating system distributors should provide an adequately configured 110 | default image to ensure a smooth user experience. 111 | 112 | ## Image requirements 113 | 114 | Toolbox customizes newly created containers in a certain way. This requires 115 | certain tools and paths to be present and have certain characteristics inside 116 | the OCI image. 117 | 118 | Tools: 119 | * `getent(1)` 120 | * `id(1)` 121 | * `ln(1)` 122 | * `mkdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 123 | * `passwd(1)` 124 | * `readlink(1)` 125 | * `rm(1)` 126 | * `rmdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 127 | * `sleep(1)` 128 | * `test(1)` 129 | * `touch(1)` 130 | * `unlink(1)` 131 | * `useradd(8)` 132 | * `usermod(8)` 133 | 134 | Paths: 135 | * `/etc/host.conf`: optional, if present not a bind mount 136 | * `/etc/hosts`: optional, if present not a bind mount 137 | * `/etc/krb5.conf.d`: directory, not a bind mount 138 | * `/etc/localtime`: optional, if present not a bind mount 139 | * `/etc/machine-id`: optional, not a bind mount 140 | * `/etc/resolv.conf`: optional, if present not a bind mount 141 | * `/etc/timezone`: optional, if present not a bind mount 142 | 143 | Toolbox enables `sudo(8)` access inside containers. The following is necessary 144 | for that to work: 145 | 146 | * The image should have `sudo(8)` enabled for users belonging to either the 147 | `sudo` or `wheel` groups, and the group itself should exist. File an 148 | [issue](https://github.com/containers/toolbox/issues/new) if you really need 149 | support for a different group. However, it's preferable to keep this list as 150 | short as possible. 151 | 152 | * The image should allow empty passwords for `sudo(8)`. This can be achieved 153 | by either adding the `nullok` option to the `PAM(8)` configuration, or by 154 | add the `NOPASSWD` tag to the `sudoers(5)` configuration. 155 | 156 | Since Toolbox only works with OCI images that fulfill certain requirements, 157 | it will refuse images that aren't tagged with 158 | `com.github.containers.toolbox="true"` and 159 | `com.github.debarshiray.toolbox="true"` labels. These labels are meant to be 160 | used by the maintainer of the image to indicate that they have read this 161 | document and tested that the image works with Toolbox. You can use the 162 | following snippet in a Dockerfile for this: 163 | ```Dockerfile 164 | LABEL com.github.containers.toolbox="true" 165 | ``` 166 | The label `com.github.debarshiray.toolbox="true"` was used in previous versions 167 | of toolbox but is currently deprecated. 168 | -------------------------------------------------------------------------------- /images/kalilinux/latest/Containerfile: -------------------------------------------------------------------------------- 1 | FROM docker.io/kalilinux/kali-rolling:latest 2 | 3 | ENV NAME=kalilinux-toolbox VERSION=latest 4 | LABEL com.github.containers.toolbox="true" 5 | 6 | COPY README.md / 7 | 8 | COPY missing-docs / 9 | RUN apt-get update -qy && xargs -a missing-docs apt-get -qy install 10 | RUN rm /missing-docs 11 | 12 | COPY extra-packages / 13 | RUN apt-get update -qy && xargs -a extra-packages apt-get -qy install 14 | RUN rm /extra-packages 15 | 16 | RUN apt-get -y clean 17 | -------------------------------------------------------------------------------- /images/kalilinux/latest/README.md: -------------------------------------------------------------------------------- 1 | Toolbox logo landscape 2 | 3 | [![Zuul](https://zuul-ci.org/gated.svg)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers/toolbox) 4 | [![Daily Pipeline](https://softwarefactory-project.io/zuul/api/tenant/local/badge?project=containers/toolbox&pipeline=periodic)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers%2Ftoolbox&pipeline=periodic) 5 | 6 | [![Arch Linux package](https://img.shields.io/archlinux/v/community/x86_64/toolbox)](https://www.archlinux.org/packages/community/x86_64/toolbox/) 7 | [![Fedora package](https://img.shields.io/fedora/v/toolbox/rawhide)](https://src.fedoraproject.org/rpms/toolbox/) 8 | 9 | [Toolbox](https://github.com/containers/toolbox) is a tool for Linux operating 10 | systems, which allows the use of containerized command line environments. It is 11 | built on top of [Podman](https://podman.io/) and other standard container 12 | technologies from [OCI](https://opencontainers.org/). 13 | 14 | This is particularly useful on 15 | [OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like 16 | [Fedora CoreOS](https://coreos.fedoraproject.org/) and 17 | [Silverblue](https://silverblue.fedoraproject.org/). The intention of these 18 | systems is to discourage installation of software on the host, and instead 19 | install software as (or in) containers — they mostly don't even have package 20 | managers like DNF or YUM. This makes it difficult to set up a development 21 | environment or install tools for debugging in the usual way. 22 | 23 | Toolbox solves this problem by providing a fully mutable container within 24 | which one can install their favourite development and debugging tools, editors 25 | and SDKs. For example, it's possible to do `yum install ansible` without 26 | affecting the base operating system. 27 | 28 | However, this tool doesn't *require* using an OSTree based system. It works 29 | equally well on Fedora Workstation and Server, and that's a useful way to 30 | incrementally adopt containerization. 31 | 32 | The toolbox environment is based on an [OCI](https://www.opencontainers.org/) 33 | image. On Fedora this is the `fedora-toolbox` image. This image is used to 34 | create a toolbox container that seamlessly integrates with the rest of the 35 | operating system by providing access to the user's home directory, the Wayland 36 | and X11 sockets, networking (including Avahi), removable devices (like USB 37 | sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev 38 | database, etc.. 39 | 40 | 41 | ## Installation 42 | 43 | Toolbox is installed by default on Fedora Silverblue. On other operating 44 | systems it's just a matter of installing the `toolbox` package. 45 | 46 | ## Usage 47 | 48 | ### Create your toolbox container: 49 | ```console 50 | [user@hostname ~]$ toolbox create 51 | Created container: fedora-toolbox-33 52 | Enter with: toolbox enter 53 | [user@hostname ~]$ 54 | ``` 55 | This will create a container called `fedora-toolbox-`. 56 | 57 | ### Enter the toolbox: 58 | ```console 59 | [user@hostname ~]$ toolbox enter 60 | ⬢[user@toolbox ~]$ 61 | ``` 62 | 63 | ### Remove a toolbox container: 64 | ```console 65 | [user@hostname ~]$ toolbox rm fedora-toolbox-33 66 | [user@hostname ~]$ 67 | ``` 68 | 69 | ## Dependencies and Building 70 | 71 | Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build 72 | system. 73 | 74 | The following dependencies are required to build it: 75 | - meson 76 | - go-md2man 77 | - systemd 78 | - go 79 | - ninja 80 | 81 | The following dependencies enable various optional features: 82 | - bash-completion 83 | 84 | It can be built and installed as any other typical Meson-based project: 85 | ```console 86 | [user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir 87 | [user@hostname toolbox]$ ninja -C builddir 88 | [user@hostname toolbox]$ sudo ninja -C builddir install 89 | ``` 90 | 91 | Toolbox is written in Go. Consult the 92 | [src/go.mod](https://github.com/containers/toolbox/blob/main/src/go.mod) file 93 | for a full list of all the Go dependencies. 94 | 95 | By default, Toolbox uses Go modules and all the required Go packages are 96 | automatically downloaded as part of the build. There's no need to worry about 97 | the Go dependencies, unless the build environment doesn't have network access 98 | or any such peculiarities. 99 | 100 | ## Distro support 101 | 102 | By default, Toolbox creates the container using an 103 | [OCI](https://www.opencontainers.org/) image called 104 | `-toolbox:`, where `` and `` are taken from the 105 | host's `/usr/lib/os-release`. For example, the default image on a Fedora 33 106 | host would be `fedora-toolbox:33`. 107 | 108 | This default can be overridden by the `--image` option in `toolbox create`, 109 | but operating system distributors should provide an adequately configured 110 | default image to ensure a smooth user experience. 111 | 112 | ## Image requirements 113 | 114 | Toolbox customizes newly created containers in a certain way. This requires 115 | certain tools and paths to be present and have certain characteristics inside 116 | the OCI image. 117 | 118 | Tools: 119 | * `getent(1)` 120 | * `id(1)` 121 | * `ln(1)` 122 | * `mkdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 123 | * `passwd(1)` 124 | * `readlink(1)` 125 | * `rm(1)` 126 | * `rmdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 127 | * `sleep(1)` 128 | * `test(1)` 129 | * `touch(1)` 130 | * `unlink(1)` 131 | * `useradd(8)` 132 | * `usermod(8)` 133 | 134 | Paths: 135 | * `/etc/host.conf`: optional, if present not a bind mount 136 | * `/etc/hosts`: optional, if present not a bind mount 137 | * `/etc/krb5.conf.d`: directory, not a bind mount 138 | * `/etc/localtime`: optional, if present not a bind mount 139 | * `/etc/machine-id`: optional, not a bind mount 140 | * `/etc/resolv.conf`: optional, if present not a bind mount 141 | * `/etc/timezone`: optional, if present not a bind mount 142 | 143 | Toolbox enables `sudo(8)` access inside containers. The following is necessary 144 | for that to work: 145 | 146 | * The image should have `sudo(8)` enabled for users belonging to either the 147 | `sudo` or `wheel` groups, and the group itself should exist. File an 148 | [issue](https://github.com/containers/toolbox/issues/new) if you really need 149 | support for a different group. However, it's preferable to keep this list as 150 | short as possible. 151 | 152 | * The image should allow empty passwords for `sudo(8)`. This can be achieved 153 | by either adding the `nullok` option to the `PAM(8)` configuration, or by 154 | add the `NOPASSWD` tag to the `sudoers(5)` configuration. 155 | 156 | Since Toolbox only works with OCI images that fulfill certain requirements, 157 | it will refuse images that aren't tagged with 158 | `com.github.containers.toolbox="true"` and 159 | `com.github.debarshiray.toolbox="true"` labels. These labels are meant to be 160 | used by the maintainer of the image to indicate that they have read this 161 | document and tested that the image works with Toolbox. You can use the 162 | following snippet in a Dockerfile for this: 163 | ```Dockerfile 164 | LABEL com.github.containers.toolbox="true" 165 | ``` 166 | The label `com.github.debarshiray.toolbox="true"` was used in previous versions 167 | of toolbox but is currently deprecated. 168 | -------------------------------------------------------------------------------- /images/kalilinux/latest/extra-packages: -------------------------------------------------------------------------------- 1 | bash-completion 2 | bc 3 | bzip2 4 | diffutils 5 | findutils 6 | git 7 | gnupg 8 | gnupg2 9 | gvfs-backends 10 | hostname 11 | iproute2 12 | keyutils 13 | libkrb5-3 14 | less 15 | lsof 16 | man-db 17 | mtr 18 | nano 19 | libnss-mdns 20 | openssh-client 21 | passwd 22 | pigz 23 | procps 24 | rsync 25 | sudo 26 | tcpdump 27 | time 28 | traceroute 29 | tree 30 | unzip 31 | util-linux 32 | vim 33 | wget 34 | xauth 35 | xz-utils 36 | zip 37 | -------------------------------------------------------------------------------- /images/kalilinux/latest/missing-docs: -------------------------------------------------------------------------------- 1 | acl 2 | bash 3 | curl 4 | gawk 5 | grep 6 | gzip 7 | libcap2 8 | openssl 9 | p11-kit 10 | python3 11 | rpm 12 | sed 13 | systemd 14 | tar 15 | -------------------------------------------------------------------------------- /images/tumbleweed/latest/Containerfile: -------------------------------------------------------------------------------- 1 | FROM registry.opensuse.org/opensuse/toolbox:latest 2 | 3 | ENV NAME=tumbleweed-toolbox VERSION=latest 4 | 5 | RUN echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/toolbox 6 | -------------------------------------------------------------------------------- /images/tumbleweed/latest/README.md: -------------------------------------------------------------------------------- 1 | Toolbox logo landscape 2 | 3 | [![Zuul](https://zuul-ci.org/gated.svg)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers/toolbox) 4 | [![Daily Pipeline](https://softwarefactory-project.io/zuul/api/tenant/local/badge?project=containers/toolbox&pipeline=periodic)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers%2Ftoolbox&pipeline=periodic) 5 | 6 | [![Arch Linux package](https://img.shields.io/archlinux/v/community/x86_64/toolbox)](https://www.archlinux.org/packages/community/x86_64/toolbox/) 7 | [![Fedora package](https://img.shields.io/fedora/v/toolbox/rawhide)](https://src.fedoraproject.org/rpms/toolbox/) 8 | 9 | [Toolbox](https://github.com/containers/toolbox) is a tool for Linux operating 10 | systems, which allows the use of containerized command line environments. It is 11 | built on top of [Podman](https://podman.io/) and other standard container 12 | technologies from [OCI](https://opencontainers.org/). 13 | 14 | This is particularly useful on 15 | [OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like 16 | [Fedora CoreOS](https://coreos.fedoraproject.org/) and 17 | [Silverblue](https://silverblue.fedoraproject.org/). The intention of these 18 | systems is to discourage installation of software on the host, and instead 19 | install software as (or in) containers — they mostly don't even have package 20 | managers like DNF or YUM. This makes it difficult to set up a development 21 | environment or install tools for debugging in the usual way. 22 | 23 | Toolbox solves this problem by providing a fully mutable container within 24 | which one can install their favourite development and debugging tools, editors 25 | and SDKs. For example, it's possible to do `yum install ansible` without 26 | affecting the base operating system. 27 | 28 | However, this tool doesn't *require* using an OSTree based system. It works 29 | equally well on Fedora Workstation and Server, and that's a useful way to 30 | incrementally adopt containerization. 31 | 32 | The toolbox environment is based on an [OCI](https://www.opencontainers.org/) 33 | image. On Fedora this is the `fedora-toolbox` image. This image is used to 34 | create a toolbox container that seamlessly integrates with the rest of the 35 | operating system by providing access to the user's home directory, the Wayland 36 | and X11 sockets, networking (including Avahi), removable devices (like USB 37 | sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev 38 | database, etc.. 39 | 40 | 41 | ## Installation 42 | 43 | Toolbox is installed by default on Fedora Silverblue. On other operating 44 | systems it's just a matter of installing the `toolbox` package. 45 | 46 | ## Usage 47 | 48 | ### Create your toolbox container: 49 | ```console 50 | [user@hostname ~]$ toolbox create 51 | Created container: fedora-toolbox-33 52 | Enter with: toolbox enter 53 | [user@hostname ~]$ 54 | ``` 55 | This will create a container called `fedora-toolbox-`. 56 | 57 | ### Enter the toolbox: 58 | ```console 59 | [user@hostname ~]$ toolbox enter 60 | ⬢[user@toolbox ~]$ 61 | ``` 62 | 63 | ### Remove a toolbox container: 64 | ```console 65 | [user@hostname ~]$ toolbox rm fedora-toolbox-33 66 | [user@hostname ~]$ 67 | ``` 68 | 69 | ## Dependencies and Building 70 | 71 | Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build 72 | system. 73 | 74 | The following dependencies are required to build it: 75 | - meson 76 | - go-md2man 77 | - systemd 78 | - go 79 | - ninja 80 | 81 | The following dependencies enable various optional features: 82 | - bash-completion 83 | 84 | It can be built and installed as any other typical Meson-based project: 85 | ```console 86 | [user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir 87 | [user@hostname toolbox]$ ninja -C builddir 88 | [user@hostname toolbox]$ sudo ninja -C builddir install 89 | ``` 90 | 91 | Toolbox is written in Go. Consult the 92 | [src/go.mod](https://github.com/containers/toolbox/blob/main/src/go.mod) file 93 | for a full list of all the Go dependencies. 94 | 95 | By default, Toolbox uses Go modules and all the required Go packages are 96 | automatically downloaded as part of the build. There's no need to worry about 97 | the Go dependencies, unless the build environment doesn't have network access 98 | or any such peculiarities. 99 | 100 | ## Distro support 101 | 102 | By default, Toolbox creates the container using an 103 | [OCI](https://www.opencontainers.org/) image called 104 | `-toolbox:`, where `` and `` are taken from the 105 | host's `/usr/lib/os-release`. For example, the default image on a Fedora 33 106 | host would be `fedora-toolbox:33`. 107 | 108 | This default can be overridden by the `--image` option in `toolbox create`, 109 | but operating system distributors should provide an adequately configured 110 | default image to ensure a smooth user experience. 111 | 112 | ## Image requirements 113 | 114 | Toolbox customizes newly created containers in a certain way. This requires 115 | certain tools and paths to be present and have certain characteristics inside 116 | the OCI image. 117 | 118 | Tools: 119 | * `getent(1)` 120 | * `id(1)` 121 | * `ln(1)` 122 | * `mkdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 123 | * `passwd(1)` 124 | * `readlink(1)` 125 | * `rm(1)` 126 | * `rmdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 127 | * `sleep(1)` 128 | * `test(1)` 129 | * `touch(1)` 130 | * `unlink(1)` 131 | * `useradd(8)` 132 | * `usermod(8)` 133 | 134 | Paths: 135 | * `/etc/host.conf`: optional, if present not a bind mount 136 | * `/etc/hosts`: optional, if present not a bind mount 137 | * `/etc/krb5.conf.d`: directory, not a bind mount 138 | * `/etc/localtime`: optional, if present not a bind mount 139 | * `/etc/machine-id`: optional, not a bind mount 140 | * `/etc/resolv.conf`: optional, if present not a bind mount 141 | * `/etc/timezone`: optional, if present not a bind mount 142 | 143 | Toolbox enables `sudo(8)` access inside containers. The following is necessary 144 | for that to work: 145 | 146 | * The image should have `sudo(8)` enabled for users belonging to either the 147 | `sudo` or `wheel` groups, and the group itself should exist. File an 148 | [issue](https://github.com/containers/toolbox/issues/new) if you really need 149 | support for a different group. However, it's preferable to keep this list as 150 | short as possible. 151 | 152 | * The image should allow empty passwords for `sudo(8)`. This can be achieved 153 | by either adding the `nullok` option to the `PAM(8)` configuration, or by 154 | add the `NOPASSWD` tag to the `sudoers(5)` configuration. 155 | 156 | Since Toolbox only works with OCI images that fulfill certain requirements, 157 | it will refuse images that aren't tagged with 158 | `com.github.containers.toolbox="true"` and 159 | `com.github.debarshiray.toolbox="true"` labels. These labels are meant to be 160 | used by the maintainer of the image to indicate that they have read this 161 | document and tested that the image works with Toolbox. You can use the 162 | following snippet in a Dockerfile for this: 163 | ```Dockerfile 164 | LABEL com.github.containers.toolbox="true" 165 | ``` 166 | The label `com.github.debarshiray.toolbox="true"` was used in previous versions 167 | of toolbox but is currently deprecated. 168 | -------------------------------------------------------------------------------- /images/ubuntu/20.04/Containerfile: -------------------------------------------------------------------------------- 1 | FROM ubuntu:20.04 2 | 3 | ENV NAME=ubuntu-toolbox VERSION=20.04 4 | LABEL com.github.containers.toolbox="true" 5 | 6 | COPY README.md / 7 | 8 | COPY missing-docs / 9 | RUN DEBIAN_FRONTEND=noninteractive apt-get update -qy && DEBIAN_FRONTEND=noninteractive xargs -a missing-docs apt-get -qy install 10 | RUN rm /missing-docs 11 | 12 | COPY extra-packages / 13 | RUN DEBIAN_FRONTEND=noninteractive apt-get update -qy && DEBIAN_FRONTEND=noninteractive xargs -a extra-packages apt-get -qy install 14 | RUN rm /extra-packages 15 | 16 | COPY nsswitch.conf /etc/nsswitch.conf 17 | 18 | RUN apt-get -y clean 19 | -------------------------------------------------------------------------------- /images/ubuntu/20.04/README.md: -------------------------------------------------------------------------------- 1 | Toolbox logo landscape 2 | 3 | [![Zuul](https://zuul-ci.org/gated.svg)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers/toolbox) 4 | [![Daily Pipeline](https://softwarefactory-project.io/zuul/api/tenant/local/badge?project=containers/toolbox&pipeline=periodic)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers%2Ftoolbox&pipeline=periodic) 5 | 6 | [![Arch Linux package](https://img.shields.io/archlinux/v/community/x86_64/toolbox)](https://www.archlinux.org/packages/community/x86_64/toolbox/) 7 | [![Fedora package](https://img.shields.io/fedora/v/toolbox/rawhide)](https://src.fedoraproject.org/rpms/toolbox/) 8 | 9 | [Toolbox](https://github.com/containers/toolbox) is a tool for Linux operating 10 | systems, which allows the use of containerized command line environments. It is 11 | built on top of [Podman](https://podman.io/) and other standard container 12 | technologies from [OCI](https://opencontainers.org/). 13 | 14 | This is particularly useful on 15 | [OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like 16 | [Fedora CoreOS](https://coreos.fedoraproject.org/) and 17 | [Silverblue](https://silverblue.fedoraproject.org/). The intention of these 18 | systems is to discourage installation of software on the host, and instead 19 | install software as (or in) containers — they mostly don't even have package 20 | managers like DNF or YUM. This makes it difficult to set up a development 21 | environment or install tools for debugging in the usual way. 22 | 23 | Toolbox solves this problem by providing a fully mutable container within 24 | which one can install their favourite development and debugging tools, editors 25 | and SDKs. For example, it's possible to do `yum install ansible` without 26 | affecting the base operating system. 27 | 28 | However, this tool doesn't *require* using an OSTree based system. It works 29 | equally well on Fedora Workstation and Server, and that's a useful way to 30 | incrementally adopt containerization. 31 | 32 | The toolbox environment is based on an [OCI](https://www.opencontainers.org/) 33 | image. On Fedora this is the `fedora-toolbox` image. This image is used to 34 | create a toolbox container that seamlessly integrates with the rest of the 35 | operating system by providing access to the user's home directory, the Wayland 36 | and X11 sockets, networking (including Avahi), removable devices (like USB 37 | sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev 38 | database, etc.. 39 | 40 | 41 | ## Installation 42 | 43 | Toolbox is installed by default on Fedora Silverblue. On other operating 44 | systems it's just a matter of installing the `toolbox` package. 45 | 46 | ## Usage 47 | 48 | ### Create your toolbox container: 49 | ```console 50 | [user@hostname ~]$ toolbox create 51 | Created container: fedora-toolbox-33 52 | Enter with: toolbox enter 53 | [user@hostname ~]$ 54 | ``` 55 | This will create a container called `fedora-toolbox-`. 56 | 57 | ### Enter the toolbox: 58 | ```console 59 | [user@hostname ~]$ toolbox enter 60 | ⬢[user@toolbox ~]$ 61 | ``` 62 | 63 | ### Remove a toolbox container: 64 | ```console 65 | [user@hostname ~]$ toolbox rm fedora-toolbox-33 66 | [user@hostname ~]$ 67 | ``` 68 | 69 | ## Dependencies and Building 70 | 71 | Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build 72 | system. 73 | 74 | The following dependencies are required to build it: 75 | - meson 76 | - go-md2man 77 | - systemd 78 | - go 79 | - ninja 80 | 81 | The following dependencies enable various optional features: 82 | - bash-completion 83 | 84 | It can be built and installed as any other typical Meson-based project: 85 | ```console 86 | [user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir 87 | [user@hostname toolbox]$ ninja -C builddir 88 | [user@hostname toolbox]$ sudo ninja -C builddir install 89 | ``` 90 | 91 | Toolbox is written in Go. Consult the 92 | [src/go.mod](https://github.com/containers/toolbox/blob/main/src/go.mod) file 93 | for a full list of all the Go dependencies. 94 | 95 | By default, Toolbox uses Go modules and all the required Go packages are 96 | automatically downloaded as part of the build. There's no need to worry about 97 | the Go dependencies, unless the build environment doesn't have network access 98 | or any such peculiarities. 99 | 100 | ## Distro support 101 | 102 | By default, Toolbox creates the container using an 103 | [OCI](https://www.opencontainers.org/) image called 104 | `-toolbox:`, where `` and `` are taken from the 105 | host's `/usr/lib/os-release`. For example, the default image on a Fedora 33 106 | host would be `fedora-toolbox:33`. 107 | 108 | This default can be overridden by the `--image` option in `toolbox create`, 109 | but operating system distributors should provide an adequately configured 110 | default image to ensure a smooth user experience. 111 | 112 | ## Image requirements 113 | 114 | Toolbox customizes newly created containers in a certain way. This requires 115 | certain tools and paths to be present and have certain characteristics inside 116 | the OCI image. 117 | 118 | Tools: 119 | * `getent(1)` 120 | * `id(1)` 121 | * `ln(1)` 122 | * `mkdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 123 | * `passwd(1)` 124 | * `readlink(1)` 125 | * `rm(1)` 126 | * `rmdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 127 | * `sleep(1)` 128 | * `test(1)` 129 | * `touch(1)` 130 | * `unlink(1)` 131 | * `useradd(8)` 132 | * `usermod(8)` 133 | 134 | Paths: 135 | * `/etc/host.conf`: optional, if present not a bind mount 136 | * `/etc/hosts`: optional, if present not a bind mount 137 | * `/etc/krb5.conf.d`: directory, not a bind mount 138 | * `/etc/localtime`: optional, if present not a bind mount 139 | * `/etc/machine-id`: optional, not a bind mount 140 | * `/etc/resolv.conf`: optional, if present not a bind mount 141 | * `/etc/timezone`: optional, if present not a bind mount 142 | 143 | Toolbox enables `sudo(8)` access inside containers. The following is necessary 144 | for that to work: 145 | 146 | * The image should have `sudo(8)` enabled for users belonging to either the 147 | `sudo` or `wheel` groups, and the group itself should exist. File an 148 | [issue](https://github.com/containers/toolbox/issues/new) if you really need 149 | support for a different group. However, it's preferable to keep this list as 150 | short as possible. 151 | 152 | * The image should allow empty passwords for `sudo(8)`. This can be achieved 153 | by either adding the `nullok` option to the `PAM(8)` configuration, or by 154 | add the `NOPASSWD` tag to the `sudoers(5)` configuration. 155 | 156 | Since Toolbox only works with OCI images that fulfill certain requirements, 157 | it will refuse images that aren't tagged with 158 | `com.github.containers.toolbox="true"` and 159 | `com.github.debarshiray.toolbox="true"` labels. These labels are meant to be 160 | used by the maintainer of the image to indicate that they have read this 161 | document and tested that the image works with Toolbox. You can use the 162 | following snippet in a Dockerfile for this: 163 | ```Dockerfile 164 | LABEL com.github.containers.toolbox="true" 165 | ``` 166 | The label `com.github.debarshiray.toolbox="true"` was used in previous versions 167 | of toolbox but is currently deprecated. 168 | -------------------------------------------------------------------------------- /images/ubuntu/20.04/extra-packages: -------------------------------------------------------------------------------- 1 | bash-completion 2 | bc 3 | bzip2 4 | diffutils 5 | findutils 6 | git 7 | gnupg 8 | gnupg2 9 | gvfs-backends 10 | hostname 11 | iproute2 12 | keyutils 13 | libkrb5-3 14 | less 15 | lsof 16 | man-db 17 | mtr 18 | nano 19 | libnss-mdns 20 | openssh-client 21 | passwd 22 | pigz 23 | procps 24 | rsync 25 | sudo 26 | tcpdump 27 | time 28 | traceroute 29 | tree 30 | unzip 31 | util-linux 32 | vim 33 | wget 34 | xauth 35 | xz-utils 36 | zip 37 | libnss-myhostname 38 | -------------------------------------------------------------------------------- /images/ubuntu/20.04/missing-docs: -------------------------------------------------------------------------------- 1 | acl 2 | bash 3 | curl 4 | gawk 5 | grep 6 | gzip 7 | libcap2 8 | openssl 9 | p11-kit 10 | python3 11 | rpm 12 | sed 13 | systemd 14 | tar 15 | -------------------------------------------------------------------------------- /images/ubuntu/20.04/nsswitch.conf: -------------------------------------------------------------------------------- 1 | # /etc/nsswitch.conf 2 | # 3 | # Example configuration of GNU Name Service Switch functionality. 4 | # If you have the `glibc-doc-reference' and `info' packages installed, try: 5 | # `info libc "Name Service Switch"' for information about this file. 6 | 7 | passwd: files systemd 8 | group: files systemd 9 | shadow: files 10 | gshadow: files 11 | 12 | hosts: files myhostname mdns4_minimal [NOTFOUND=return] dns 13 | networks: files 14 | 15 | protocols: db files 16 | services: db files 17 | ethers: db files 18 | rpc: db files 19 | 20 | netgroup: nis 21 | -------------------------------------------------------------------------------- /images/ubuntu/22.04/Containerfile: -------------------------------------------------------------------------------- 1 | FROM ubuntu:22.04 2 | 3 | ENV NAME=ubuntu-toolbox VERSION=22.04 4 | LABEL com.github.containers.toolbox="true" 5 | 6 | COPY README.md / 7 | 8 | COPY missing-docs / 9 | RUN apt-get update -qy && xargs -a missing-docs apt-get -qy install 10 | RUN rm /missing-docs 11 | 12 | COPY extra-packages / 13 | RUN apt-get update -qy && xargs -a extra-packages apt-get -qy install 14 | RUN rm /extra-packages 15 | 16 | COPY nsswitch.conf /etc/nsswitch.conf 17 | 18 | RUN apt-get -y clean 19 | -------------------------------------------------------------------------------- /images/ubuntu/22.04/README.md: -------------------------------------------------------------------------------- 1 | Toolbox logo landscape 2 | 3 | [![Zuul](https://zuul-ci.org/gated.svg)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers/toolbox) 4 | [![Daily Pipeline](https://softwarefactory-project.io/zuul/api/tenant/local/badge?project=containers/toolbox&pipeline=periodic)](https://softwarefactory-project.io/zuul/t/local/builds?project=containers%2Ftoolbox&pipeline=periodic) 5 | 6 | [![Arch Linux package](https://img.shields.io/archlinux/v/community/x86_64/toolbox)](https://www.archlinux.org/packages/community/x86_64/toolbox/) 7 | [![Fedora package](https://img.shields.io/fedora/v/toolbox/rawhide)](https://src.fedoraproject.org/rpms/toolbox/) 8 | 9 | [Toolbox](https://github.com/containers/toolbox) is a tool for Linux operating 10 | systems, which allows the use of containerized command line environments. It is 11 | built on top of [Podman](https://podman.io/) and other standard container 12 | technologies from [OCI](https://opencontainers.org/). 13 | 14 | This is particularly useful on 15 | [OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like 16 | [Fedora CoreOS](https://coreos.fedoraproject.org/) and 17 | [Silverblue](https://silverblue.fedoraproject.org/). The intention of these 18 | systems is to discourage installation of software on the host, and instead 19 | install software as (or in) containers — they mostly don't even have package 20 | managers like DNF or YUM. This makes it difficult to set up a development 21 | environment or install tools for debugging in the usual way. 22 | 23 | Toolbox solves this problem by providing a fully mutable container within 24 | which one can install their favourite development and debugging tools, editors 25 | and SDKs. For example, it's possible to do `yum install ansible` without 26 | affecting the base operating system. 27 | 28 | However, this tool doesn't *require* using an OSTree based system. It works 29 | equally well on Fedora Workstation and Server, and that's a useful way to 30 | incrementally adopt containerization. 31 | 32 | The toolbox environment is based on an [OCI](https://www.opencontainers.org/) 33 | image. On Fedora this is the `fedora-toolbox` image. This image is used to 34 | create a toolbox container that seamlessly integrates with the rest of the 35 | operating system by providing access to the user's home directory, the Wayland 36 | and X11 sockets, networking (including Avahi), removable devices (like USB 37 | sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev 38 | database, etc.. 39 | 40 | 41 | ## Installation 42 | 43 | Toolbox is installed by default on Fedora Silverblue. On other operating 44 | systems it's just a matter of installing the `toolbox` package. 45 | 46 | ## Usage 47 | 48 | ### Create your toolbox container: 49 | ```console 50 | [user@hostname ~]$ toolbox create 51 | Created container: fedora-toolbox-33 52 | Enter with: toolbox enter 53 | [user@hostname ~]$ 54 | ``` 55 | This will create a container called `fedora-toolbox-`. 56 | 57 | ### Enter the toolbox: 58 | ```console 59 | [user@hostname ~]$ toolbox enter 60 | ⬢[user@toolbox ~]$ 61 | ``` 62 | 63 | ### Remove a toolbox container: 64 | ```console 65 | [user@hostname ~]$ toolbox rm fedora-toolbox-33 66 | [user@hostname ~]$ 67 | ``` 68 | 69 | ## Dependencies and Building 70 | 71 | Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build 72 | system. 73 | 74 | The following dependencies are required to build it: 75 | - meson 76 | - go-md2man 77 | - systemd 78 | - go 79 | - ninja 80 | 81 | The following dependencies enable various optional features: 82 | - bash-completion 83 | 84 | It can be built and installed as any other typical Meson-based project: 85 | ```console 86 | [user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir 87 | [user@hostname toolbox]$ ninja -C builddir 88 | [user@hostname toolbox]$ sudo ninja -C builddir install 89 | ``` 90 | 91 | Toolbox is written in Go. Consult the 92 | [src/go.mod](https://github.com/containers/toolbox/blob/main/src/go.mod) file 93 | for a full list of all the Go dependencies. 94 | 95 | By default, Toolbox uses Go modules and all the required Go packages are 96 | automatically downloaded as part of the build. There's no need to worry about 97 | the Go dependencies, unless the build environment doesn't have network access 98 | or any such peculiarities. 99 | 100 | ## Distro support 101 | 102 | By default, Toolbox creates the container using an 103 | [OCI](https://www.opencontainers.org/) image called 104 | `-toolbox:`, where `` and `` are taken from the 105 | host's `/usr/lib/os-release`. For example, the default image on a Fedora 33 106 | host would be `fedora-toolbox:33`. 107 | 108 | This default can be overridden by the `--image` option in `toolbox create`, 109 | but operating system distributors should provide an adequately configured 110 | default image to ensure a smooth user experience. 111 | 112 | ## Image requirements 113 | 114 | Toolbox customizes newly created containers in a certain way. This requires 115 | certain tools and paths to be present and have certain characteristics inside 116 | the OCI image. 117 | 118 | Tools: 119 | * `getent(1)` 120 | * `id(1)` 121 | * `ln(1)` 122 | * `mkdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 123 | * `passwd(1)` 124 | * `readlink(1)` 125 | * `rm(1)` 126 | * `rmdir(1)`: for hosts where `/home` is a symbolic link to `/var/home` 127 | * `sleep(1)` 128 | * `test(1)` 129 | * `touch(1)` 130 | * `unlink(1)` 131 | * `useradd(8)` 132 | * `usermod(8)` 133 | 134 | Paths: 135 | * `/etc/host.conf`: optional, if present not a bind mount 136 | * `/etc/hosts`: optional, if present not a bind mount 137 | * `/etc/krb5.conf.d`: directory, not a bind mount 138 | * `/etc/localtime`: optional, if present not a bind mount 139 | * `/etc/machine-id`: optional, not a bind mount 140 | * `/etc/resolv.conf`: optional, if present not a bind mount 141 | * `/etc/timezone`: optional, if present not a bind mount 142 | 143 | Toolbox enables `sudo(8)` access inside containers. The following is necessary 144 | for that to work: 145 | 146 | * The image should have `sudo(8)` enabled for users belonging to either the 147 | `sudo` or `wheel` groups, and the group itself should exist. File an 148 | [issue](https://github.com/containers/toolbox/issues/new) if you really need 149 | support for a different group. However, it's preferable to keep this list as 150 | short as possible. 151 | 152 | * The image should allow empty passwords for `sudo(8)`. This can be achieved 153 | by either adding the `nullok` option to the `PAM(8)` configuration, or by 154 | add the `NOPASSWD` tag to the `sudoers(5)` configuration. 155 | 156 | Since Toolbox only works with OCI images that fulfill certain requirements, 157 | it will refuse images that aren't tagged with 158 | `com.github.containers.toolbox="true"` and 159 | `com.github.debarshiray.toolbox="true"` labels. These labels are meant to be 160 | used by the maintainer of the image to indicate that they have read this 161 | document and tested that the image works with Toolbox. You can use the 162 | following snippet in a Dockerfile for this: 163 | ```Dockerfile 164 | LABEL com.github.containers.toolbox="true" 165 | ``` 166 | The label `com.github.debarshiray.toolbox="true"` was used in previous versions 167 | of toolbox but is currently deprecated. 168 | -------------------------------------------------------------------------------- /images/ubuntu/22.04/extra-packages: -------------------------------------------------------------------------------- 1 | bash-completion 2 | bc 3 | bzip2 4 | diffutils 5 | findutils 6 | git 7 | gnupg 8 | gnupg2 9 | gvfs-backends 10 | hostname 11 | iproute2 12 | keyutils 13 | libkrb5-3 14 | less 15 | lsof 16 | man-db 17 | mtr 18 | nano 19 | libnss-mdns 20 | openssh-client 21 | passwd 22 | pigz 23 | procps 24 | rsync 25 | sudo 26 | tcpdump 27 | time 28 | traceroute 29 | tree 30 | unzip 31 | util-linux 32 | vim 33 | wget 34 | xauth 35 | xz-utils 36 | zip 37 | libnss-myhostname 38 | -------------------------------------------------------------------------------- /images/ubuntu/22.04/missing-docs: -------------------------------------------------------------------------------- 1 | acl 2 | bash 3 | curl 4 | gawk 5 | grep 6 | gzip 7 | libcap2 8 | openssl 9 | p11-kit 10 | python3 11 | rpm 12 | sed 13 | systemd 14 | tar 15 | -------------------------------------------------------------------------------- /images/ubuntu/22.04/nsswitch.conf: -------------------------------------------------------------------------------- 1 | # /etc/nsswitch.conf 2 | # 3 | # Example configuration of GNU Name Service Switch functionality. 4 | # If you have the `glibc-doc-reference' and `info' packages installed, try: 5 | # `info libc "Name Service Switch"' for information about this file. 6 | 7 | passwd: files systemd 8 | group: files systemd 9 | shadow: files 10 | gshadow: files 11 | 12 | hosts: files myhostname mdns4_minimal [NOTFOUND=return] dns 13 | networks: files 14 | 15 | protocols: db files 16 | services: db files 17 | ethers: db files 18 | rpc: db files 19 | 20 | netgroup: nis 21 | -------------------------------------------------------------------------------- /publish-all.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | ./build-all.sh | awk '{print $2}' | while read image_tag; do 4 | ./util/publish.sh "${image_tag}" 5 | done 6 | 7 | 8 | -------------------------------------------------------------------------------- /util/build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | 4 | main() { 5 | image_name="$1" 6 | image_builddir="$PWD/images/${image_name}" 7 | 8 | if [ ! -d "images/${image_name}" ]; then 9 | printf 'could not find image "%s"\n"' "${image_name}" 10 | return 1 11 | fi 12 | 13 | 14 | image_id="$(podman build "${image_builddir}" | tail -1)" 15 | image_tag="$(podman image inspect "${image_id}" | jq -r '[.[].Config.Env[] | select(test("(NAME|VERSION)")) | split("=")| .[1]] | { name: .[0], version: .[1] } | "\(.name):\(.version)"')" 16 | 17 | podman tag "${image_id}" "localhost/${image_tag}" 18 | 19 | printf 'created: %s\n' "${image_tag}" 20 | } 21 | 22 | main "$@" 23 | -------------------------------------------------------------------------------- /util/publish.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -x 3 | 4 | main() { 5 | image_name="$(./util/build.sh "${1}" | awk '{print $2}')" 6 | 7 | podman tag "localhost/${image_name}" "${TOOLBOX_REPO}/${image_name}" 8 | podman push "${image_name}" "${TOOLBOX_REPO}/${image_name}" 9 | } 10 | 11 | main "$@" 12 | --------------------------------------------------------------------------------