1toolbox-create(1) General Commands Manual toolbox-create(1)
2
6 toolbox-create - Create a new toolbox container
7
10 toolbox create [--authfile FILE]
11 [--distro DISTRO | -d DISTRO]
12 [--image NAME | -i NAME]
13 [--release RELEASE | -r RELEASE]
14 [CONTAINER]
15
18 Creates a new toolbox container. You can then use the toolbox enter
19 command to interact with the container at any point.
20 A toolbox container is an OCI container created from an OCI image. On
23 Fedora, the default image is known as fedora-toolbox:N, where N is the
24 release of the host. If the image is not present locally, then it is
25 pulled from a well-known registry like registry.fedoraproject.org.
26 Other images may be used on other host operating systems. If the host
27 is not recognized, then the Fedora image will be used.
28 The container is created with podman create, and its entry point is set
31 to toolbox init-container.
32 By default, a toolbox container is named after its corresponding image.
35 If the image had a tag, then the tag is included in the name of the
36 container, but it's separated by a hyphen, not a colon. A different
37 name can be assigned by using the CONTAINER argument.
38 Container Configuration
41 A toolbox container seamlessly integrates with the rest of the operat‐
42 ing system by providing access to the user's home directory, the Way‐
43 land and X11 sockets, networking (including Avahi), removable devices
44 (like USB sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and
45 the udev database, etc..
46 The user ID and account details from the host is propagated into the
49 toolbox container, SELinux label separation is disabled, and the host
50 file system can be accessed by the container at /run/host. The con‐
51 tainer has access to the host's Kerberos credentials cache if it's con‐
52 figured to use KCM caches.
53 A toolbox container can be identified by the com.github.contain‐
56 ers.toolbox label or the /run/.toolboxenv file.
57 The entry point of a toolbox container is the toolbox init-container
60 command which plays a role in setting up the container, along with the
61 options passed to podman create.
62 Entry Point
65 A key feature of toolbox containers is their entry point, the toolbox
66 init-container command.
67 OCI containers are inherently immutable. Configuration options passed
70 through podman create are baked into the definition of the OCI con‐
71 tainer, and can't be changed later. This means that changes and im‐
72 provements made in newer versions of Toolbox can't be applied to pre-
73 existing toolbox containers created by older versions of Toolbox. This
74 is avoided by using the entry point to configure the container at run‐
75 time.
76 The entry point of a toolbox container customizes the container to fit
79 the current user by ensuring that it has a user that matches the one on
80 the host, and grants it sudo and root access.
81 Crucial configuration files, such as /etc/host.conf, /etc/hosts,
84 /etc/localtime, /etc/resolv.conf and /etc/timezone, inside the con‐
85 tainer are kept synchronized with the host. The entry point also bind
86 mounts various subsets of the host's filesystem hierarchy to their cor‐
87 responding locations inside the container to provide seamless integra‐
88 tion with the host. This includes /run/libvirt, /run/systemd/journal,
89 /run/udev/data, /var/lib/libvirt, /var/lib/systemd/coredump,
90 /var/log/journal and others.
91 On some host operating systems, important paths like /home, /media or
94 /mnt are symbolic links to other locations. The entry point ensures
95 that paths inside the container match those on the host, to avoid need‐
96 less confusion.
97
100 --authfile FILE
101 Path to a FILE with credentials for authenticating to the registry for
104 private images. The FILE is usually set using podman login, and will be
105 used by podman pull to get the image.
106 The default location for FILE is $XDG_RUNTIME_DIR/containers/auth.json
109 and its format is specified in containers-auth.json(5).
110 --distro DISTRO, -d DISTRO
113 Create a toolbox container for a different operating system DISTRO than
116 the host. Cannot be used with --image. Has to be coupled with --release
117 unless the selected DISTRO matches the host.
118 --image NAME, -i NAME
121 Change the NAME of the image used to create the toolbox container. This
124 is useful for creating containers from custom-built images. Cannot be
125 used with --distro and --release.
126 If NAME does not contain a registry, the local image storage will be
129 consulted, and if it's not present there then it will be pulled from a
130 suitable remote registry.
131 --release RELEASE, -r RELEASE
134 Create a toolbox container for a different operating system RELEASE
137 than the host. Cannot be used with --image.
138
141 Create a toolbox container using the default image matching the host OS
142 $ toolbox create
143 Create a toolbox container using the default image for Fedora 36
147 $ toolbox create --distro fedora --release f36
148 Create a custom toolbox container from a custom image
152 $ toolbox create --image bar foo
153 Create a custom toolbox container from a custom image that's private
157 $ toolbox create --authfile ~/auth.json --image registry.example.com/bar
158
162 toolbox(1), toolbox-init-container(1), podman(1), podman-create(1),
163 podman-login(1), podman-pull(1), containers-auth.json(5)
164 toolbox-create(1)