Debian Codegraph @

images/fedora/f34/README.md

raw
1 <img src="data/logo/toolbox-logo-landscape.svg" alt="Toolbox logo landscape" width="800"/>
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-<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.