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

doc/toolbox-create: Put toolbox set-up before entry point & tweak them

Browse source 
This builds upon commit ea452d7ced.

The configuration of a toolbox container is a higher level topic than
the entry point, and the entry point is mentioned as one part of it.
Therefore, putting the section on toolbox set-up earlier in the text
makes it nicely flow from the DESCRIPTION section into the Entry Point
sub-section.

Emphasize the user-visible features of a toolbox container, and not
the underlying implementation details, and avoid using too much jargon
about container technology.

https://github.com/containers/toolbox/pull/814
This commit is contained in:
Debarshi Ray 2021-06-26 10:50:42 +02:00
parent 4b70754a24
commit 55952c8605
1 changed files with 20 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -29,9 +29,24 @@ image had a tag, then the tag is included in the name of the container, but
it's separated by a hyphen, not a colon. A different name can be assigned by
using the CONTAINER argument.
### Container Configuration
A toolbox container seamlessly integrates with the rest of the operating
system by providing access to the user's home directory, the Wayland and X11
sockets, SSH agent, etc..
sockets, networking (including Avahi), removable devices (like USB sticks),
systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev database, etc..
The user ID and account details from the host is propagated into the toolbox
container, SELinux label separation is disabled, and the host file system can
be accessed by the container at /run/host. The container has access to the
host's Kerberos credentials cache if it's configured to use KCM caches.
A toolbox container can be identified by the `com.github.containers.toolbox`
label or the `/run/.toolboxenv` file.
The entry point of a toolbox container is the `toolbox init-container` command
which plays a role in setting up the container, along with the options passed
to `podman create`.
### Entry Point
@ -46,8 +61,10 @@ 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`,
current user by ensuring that it has a user that matches the one on the host,
and grants it `sudo` and `root` access.
Crucial 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
@ -60,29 +77,6 @@ On some host operating systems, important paths like `/home`, `/media` or
paths inside the container match those on the host, to avoid needless
confusion.
### Toolbox setup
`toolbox-create(1)` passes several options to `podman-create(1)` when creating
toolbox containers to provide the needed functionality. The options have the
following effects:
- Toolboxes share with the host system:
- network stack, including dns
- IPC (shared memory, semaphores, message queues,..)
- PID namespace
- ulimits
- Toolboxes have access to cherry-picked parts of host filesystem made
available under /run/host/
- Toolboxes are privileged containers
- SELinux label separation is disabled for toolboxes
- Toolboxes use as their entry-point `toolbox-init-container(1)`
Despite being privileged, rootless containers cannot have more privileges than
the user that created them.
Thanks to these options, `toolbox-init-container(1)` can futher set up the
containers. Read more about the entry-point in `toolbox-init-container(1)`.
## OPTIONS ##
**--distro** DISTRO, **-d** DISTRO