wbrawner/toolbox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc/toolbox-create, doc/toolbox-init-container: Mention the entry point

Browse source 
Ever since version 0.0.10, all newly created toolbox containers use a
reflexive entry point [1] and don't need a user-specific customized
image. Older containers that don't use a reflexive entry point were
deprecated in version 0.0.17 [2], and aren't even supported in the Go
implementation.

Therefore, it's time to finally update the manuals to document the
current way of doing things. Since the reflexive entry point is a key
feature of toolbox containers, some text was added to explain why it's
necessary and what it does.

[1] Commit 8b84b5e460
    https://github.com/containers/toolbox/pull/160

[2] Commit 9dc5281430
    https://github.com/containers/toolbox/pull/336

https://github.com/containers/toolbox/pull/677
This commit is contained in:
Ondřej Míchal 2021-01-22 17:15:23 +01:00 committed by Debarshi Ray
parent e0267b7315
commit 6543ff6a06
2 changed files with 55 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
doc/toolbox-create.1.md
View file

@ -17,14 +17,38 @@ to interact with the container at any point.
A toolbox container is an OCI container created from an OCI image. On Fedora A toolbox container is an OCI container created from an OCI image. On Fedora
the base image is known as `fedora-toolbox`. If the image is not present the base image is known as `fedora-toolbox`. If the image is not present
locally, then it is pulled from a well-known registry like locally, then it is pulled from a well-known registry like
`registry.fedoraproject.org`. The base image is locally customized for the `registry.fedoraproject.org`. The container is created with `podman create`,
current user to create a second image, from which the container is finally and its entry point is set to `toolbox init-container`.
created.
Toolbox containers and images are tagged with the version of the OS that Toolbox containers and images are tagged with the version of the OS that
corresponds to the content inside them. The user-specific images and the corresponds to the content inside them.
toolbox containers are prefixed with the name of the base image and suffixed
with the current user name. ### Entry Point
A key feature of toolbox containers is their entry point, the `toolbox
init-container` command.
OCI containers are inherently immutable. Configuration options passed through
`podman create` are baked into the definition of the OCI container, and can't
be changed later. This means that changes and improvements made in newer
versions of Toolbox can't be applied to pre-existing toolbox containers
created by older versions of Toolbox. This is avoided by using the entry point
to configure the container at runtime.
The entry point of a toolbox container customizes the container to fit the
current user by ensuring that it has a user that matches the one on the host.
It ensures that configuration files, such as `/etc/host.conf`, `/etc/hosts`,
`/etc/localtime`, `/etc/resolv.conf` and `/etc/timezone`, inside the container
are kept synchronized with the host. The entry point also bind mounts various
subsets of the host's filesystem hierarchy to their corresponding locations
inside the container to provide seamless integration with the host. This
includes `/run/libvirt`, `/run/systemd/journal`, `/run/udev/data`,
`/var/lib/libvirt`, `/var/lib/systemd/coredump`, `/var/log/journal` and others.
On some host operating systems, important paths like `/home`, `/media` or
`/mnt` are symbolic links to other locations. The entry point ensures that
paths inside the container match those on the host, to avoid needless
confusion.
## OPTIONS ## ## OPTIONS ##

25
doc/toolbox-init-container.1.md
View file

@ -20,6 +20,31 @@ be used as the entry point for all toolbox containers, and must be run inside
the container that's to be initialized. It is not expected to be directly the container that's to be initialized. It is not expected to be directly
invoked by humans, and cannot be used on the host. invoked by humans, and cannot be used on the host.
A key feature of toolbox containers is their entry point, the `toolbox
init-container` command.
OCI containers are inherently immutable. Configuration options passed through
`podman create` are baked into the definition of the OCI container, and can't
be changed later. This means that changes and improvements made in newer
versions of Toolbox can't be applied to pre-existing toolbox containers
created by older versions of Toolbox. This is avoided by using the entry point
to configure the container at runtime.
The entry point of a toolbox container customizes the container to fit the
current user by ensuring that it has a user that matches the one on the host.
It ensures that configuration files, such as `/etc/host.conf`, `/etc/hosts`,
`/etc/localtime`, `/etc/resolv.conf` and `/etc/timezone`, inside the container
are kept synchronized with the host. The entry point also bind mounts various
subsets of the host's filesystem hierarchy to their corresponding locations
inside the container to provide seamless integration with the host. This
includes `/run/libvirt`, `/run/systemd/journal`, `/run/udev/data`,
`/var/lib/libvirt`, `/var/lib/systemd/coredump`, `/var/log/journal` and others.
On some host operating systems, important paths like `/home`, `/media` or
`/mnt` are symbolic links to other locations. The entry point ensures that
paths inside the container match those on the host, to avoid needless
confusion.
## OPTIONS ## ## OPTIONS ##
The following options are understood: The following options are understood: