1toolbox-create(1)           General Commands Manual          toolbox-create(1)
2
3
4

NAME

6       toolbox-create - Create a new toolbox container
7
8

SYNOPSIS

10       toolbox create [--authfile FILE]
11                      [--distro DISTRO | -d DISTRO]
12                      [--image NAME | -i NAME]
13                      [--release RELEASE | -r RELEASE]
14                      [CONTAINER]
15
16

DESCRIPTION

18       Creates  a  new  toolbox  container. You can then use the toolbox enter
19       command to interact with the container at any point.
20
21
22       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
29
30       The container is created with podman create, and its entry point is set
31       to toolbox init-container.
32
33
34       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
39
40   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
47
48       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
54
55       A  toolbox  container  can  be  identified  by  the com.github.contain‐
56       ers.toolbox label or the /run/.toolboxenv file.
57
58
59       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
63
64   Entry Point
65       A key feature of toolbox containers is their entry point,  the  toolbox
66       init-container command.
67
68
69       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
77
78       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
82
83       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
92
93       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
98

OPTIONS

100       --authfile FILE
101
102
103       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
107
108       The  default location for FILE is $XDG_RUNTIME_DIR/containers/auth.json
109       and its format is specified in containers-auth.json(5).
110
111
112       --distro DISTRO, -d DISTRO
113
114
115       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
119
120       --image NAME, -i NAME
121
122
123       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
127
128       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
132
133       --release RELEASE, -r RELEASE
134
135
136       Create a toolbox container for a  different  operating  system  RELEASE
137       than the host. Cannot be used with --image.
138
139

EXAMPLES

141   Create a toolbox container using the default image matching the host OS
142              $ toolbox create
143
144
145
146   Create a toolbox container using the default image for Fedora 36
147              $ toolbox create --distro fedora --release f36
148
149
150
151   Create a custom toolbox container from a custom image
152              $ toolbox create --image bar foo
153
154
155
156   Create a custom toolbox container from a custom image that's private
157              $ toolbox create --authfile ~/auth.json --image registry.example.com/bar
158
159
160

SEE ALSO

162       toolbox(1),   toolbox-init-container(1),  podman(1),  podman-create(1),
163       podman-login(1), podman-pull(1), containers-auth.json(5)
164
165
166
167                                                             toolbox-create(1)
Impressum