| 1 |
<img src="data/logo/toolbox-logo-landscape.svg" alt="Toolbox logo landscape" width="800"/> |
| 2 |
|
| 3 |
[](https://softwarefactory-project.io/zuul/t/local/builds?project=containers/toolbox) |
| 4 |
[](https://softwarefactory-project.io/zuul/t/local/builds?project=containers%2Ftoolbox&pipeline=periodic) |
| 5 |
|
| 6 |
[](https://www.archlinux.org/packages/community/x86_64/toolbox/) |
| 7 |
[](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-<version-id>`. |
| 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 |
`<ID>-toolbox:<VERSION-ID>`, where `<ID>` and `<VERSION-ID>` 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. |