1toolbox-create(1)() toolbox-create(1)()
2
6 toolbox-create - Create a new toolbox container
7
10 toolbox create [--distro DISTRO | -d DISTRO]
11 [--image NAME | -i NAME]
12 [--release RELEASE | -r RELEASE]
13 [CONTAINER]
14
17 Creates a new toolbox container. You can then use the toolbox enter
18 command to interact with the container at any point.
19 A toolbox container is an OCI container created from an OCI image. On
22 Fedora, the default image is known as fedora-toolbox:N, where N is the
23 release of the host. If the image is not present locally, then it is
24 pulled from a well-known registry like registry.fedoraproject.org. The
25 container is created with podman create, and its entry point is set to
26 toolbox init-container.
27 By default, toolbox containers are named after their corresponding
30 images. If the image had a tag, then the tag is included in the name of
31 the container, but it's separated by a hyphen, not a colon. A different
32 name can be assigned by using the CONTAINER argument.
33 Entry Point
36 A key feature of toolbox containers is their entry point, the toolbox
37 init-container command.
38 OCI containers are inherently immutable. Configuration options passed
41 through podman create are baked into the definition of the OCI con‐
42 tainer, and can't be changed later. This means that changes and
43 improvements made in newer versions of Toolbox can't be applied to
44 pre-existing toolbox containers created by older versions of Toolbox.
45 This is avoided by using the entry point to configure the container at
46 runtime.
47 The entry point of a toolbox container customizes the container to fit
50 the current user by ensuring that it has a user that matches the one on
51 the host. It ensures that configuration files, such as /etc/host.conf,
52 /etc/hosts, /etc/localtime, /etc/resolv.conf and /etc/timezone, inside
53 the container are kept synchronized with the host. The entry point also
54 bind mounts various subsets of the host's filesystem hierarchy to their
55 corresponding locations inside the container to provide seamless inte‐
56 gration with the host. This includes /run/libvirt, /run/systemd/jour‐
57 nal, /run/udev/data, /var/lib/libvirt, /var/lib/systemd/coredump,
58 /var/log/journal and others.
59 On some host operating systems, important paths like /home, /media or
62 /mnt are symbolic links to other locations. The entry point ensures
63 that paths inside the container match those on the host, to avoid need‐
64 less confusion.
65
68 The following options are understood:
69 --distro DISTRO, -d DISTRO
72 Create a toolbox container for a different operating system DISTRO than
75 the host. Cannot be used with --image.
76 --image NAME, -i NAME
79 Change the NAME of the base image used to create the toolbox container.
82 This is useful for creating containers from custom-built base images.
83 Cannot be used used with --release.
84 --release RELEASE, -r RELEASE
87 Create a toolbox container for a different operating system RELEASE
90 than the host. Cannot be used with --image.
91
94 Create a toolbox container using the default image matching the host OS
95 $ toolbox create
96 Create a toolbox container using the default image for Fedora 30
100 $ toolbox create --distro fedora --release f30
101 Create a custom toolbox container from a custom image
105 $ toolbox create --image bar foo
106
110 buildah(1), podman(1)
111 toolbox-create(1)()