Debian Codegraph @

images/fedora/f32/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, SSH agent, etc..
37
38 ## Installation
39
40 Toolbox is installed by default on Fedora Silverblue. On other operating
41 systems it's just a matter of installing the `toolbox` package.
42
43 ## Usage
44
45 ### Create your toolbox container:
46 ```console
47 [user@hostname ~]$ toolbox create
48 Created container: fedora-toolbox-33
49 Enter with: toolbox enter
50 [user@hostname ~]$
51 ```
52 This will create a container called `fedora-toolbox-<version-id>`.
53
54 ### Enter the toolbox:
55 ```console
56 [user@hostname ~]$ toolbox enter
57 ⬢[user@toolbox ~]$
58 ```
59
60 ### Remove a toolbox container:
61 ```console
62 [user@hostname ~]$ toolbox rm fedora-toolbox-33
63 [user@hostname ~]$
64 ```
65
66 ## Dependencies and Building
67
68 Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build
69 system.
70
71 The following dependencies are required to build it:
72 - meson
73 - go-md2man
74 - systemd
75 - go
76 - ninja
77
78 The following dependencies enable various optional features:
79 - bash-completion
80
81 It can be built and installed as any other typical Meson-based project:
82 ```console
83 [user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir
84 [user@hostname toolbox]$ ninja -C builddir
85 [user@hostname toolbox]$ sudo ninja -C builddir install
86 ```
87
88 Toolbox is written in Go. Consult the
89 [src/go.mod](https://github.com/containers/toolbox/blob/main/src/go.mod) file
90 for a full list of all the Go dependencies.
91
92 By default, Toolbox uses Go modules and all the required Go packages are
93 automatically downloaded as part of the build. There's no need to worry about
94 the Go dependencies, unless the build environment doesn't have network access
95 or any such peculiarities.
96
97 ## Distro support
98
99 By default, Toolbox creates the container using an
100 [OCI](https://www.opencontainers.org/) image called
101 `<ID>-toolbox:<VERSION-ID>`, where `<ID>` and `<VERSION-ID>` are taken from the
102 host's `/usr/lib/os-release`. For example, the default image on a Fedora 33
103 host would be `fedora-toolbox:33`.
104
105 This default can be overridden by the `--image` option in `toolbox create`,
106 but operating system distributors should provide an adequately configured
107 default image to ensure a smooth user experience.
108
109 ## Image requirements
110
111 Toolbox customizes newly created containers in a certain way. This requires
112 certain tools and paths to be present and have certain characteristics inside
113 the OCI image.
114
115 Tools:
116 * `getent(1)`
117 * `id(1)`
118 * `ln(1)`
119 * `mkdir(1)`: for hosts where `/home` is a symbolic link to `/var/home`
120 * `passwd(1)`
121 * `readlink(1)`
122 * `rm(1)`
123 * `rmdir(1)`: for hosts where `/home` is a symbolic link to `/var/home`
124 * `sleep(1)`
125 * `test(1)`
126 * `touch(1)`
127 * `unlink(1)`
128 * `useradd(8)`
129 * `usermod(8)`
130
131 Paths:
132 * `/etc/host.conf`: optional, if present not a bind mount
133 * `/etc/hosts`: optional, if present not a bind mount
134 * `/etc/krb5.conf.d`: directory, not a bind mount
135 * `/etc/localtime`: optional, if present not a bind mount
136 * `/etc/resolv.conf`: optional, if present not a bind mount
137 * `/etc/timezone`: optional, if present not a bind mount
138
139 Toolbox enables `sudo(8)` access inside containers. The following is necessary
140 for that to work:
141
142 * The image should have `sudo(8)` enabled for users belonging to either the
143 `sudo` or `wheel` groups, and the group itself should exist. File an
144 [issue](https://github.com/containers/toolbox/issues/new) if you really need
145 support for a different group. However, it's preferable to keep this list as
146 short as possible.
147
148 * The image should allow empty passwords for `sudo(8)`. This can be achieved
149 by either adding the `nullok` option to the `PAM(8)` configuration, or by
150 add the `NOPASSWD` tag to the `sudoers(5)` configuration.
151
152 Since Toolbox only works with OCI images that fulfill certain requirements,
153 it will refuse images that aren't tagged with
154 `com.github.containers.toolbox="true"` and
155 `com.github.debarshiray.toolbox="true"` labels. These labels are meant to be
156 used by the maintainer of the image to indicate that they have read this
157 document and tested that the image works with Toolbox. You can use the
158 following snippet in a Dockerfile for this:
159 ```Dockerfile
160 LABEL com.github.containers.toolbox="true"
161 ```
162 The label `com.github.debarshiray.toolbox="true"` was used in previous versions
163 of toolbox but is currently deprecated.