doc: Update to match current state & extend docs
- Update "See also" sections Toolbox does not use Buildah for a considerable time now[0]. We can stop referencing it in the "See also" sections of the documentation. In some places mention podman command man pages where they are relevant. - Add section about toolbox images/containers Toolbox only supports certain OCI images. These should be documented. Also, document the change of fedora-toolbox image name. - Add a section about toolbox container setup Toolbox containers are specifically configured OCI containers. This should be documented so that users know what they're using. - Remove redundant part documentation The description of what `toolbox init-container` does is already in toolbox-init-container(1). There's no need to have it in toolbox-create(1). Instead, replace the text with a hint to visit the other part of documentation. - Clarify behaviour of --image option The fact that Toolbox by default tries to pull from the Fedora registry[1] should be noted. - Update synopsis & description of commands Mention options passed to `podman exec`. Remove redundant paragraph about container names (is already dealt with in toolbox-create(1)). There's no need to mention the name of the default container on Fedora since Toolbox now also supports RHEL. Mention the default used image on unrecognised systems. Emphasize the fact that toolboxes are not a fully sandboxed environment. Update the wording of the description and splits it into a few subsections. The description of the --monitor-host was inaccurate and while the option will go away in the future[2], it is currently in and should be more documented. [0] https://github.com/containers/toolbox/pull/160 [1] https://registry.fedoraproject.org [2] https://github.com/containers/toolbox/pull/617 https://github.com/containers/toolbox/pull/512
This commit is contained in:
Ondřej Míchal
parent
3db59abf2a
commit
ea452d7ced
|
|
@ -26,37 +26,43 @@ the 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.
|
||||
|
||||
If the host system is not recognized the used image will be `fedora-toolbox`.
|
||||
|
||||
Toolbox containers are primarily created in a way to be tightly integrated with
|
||||
the host system. They are not meant to be secure.
|
||||
|
||||
### 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.
|
||||
Read more about the entry-point in `toolbox-init-container(1)`.
|
||||
|
||||
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.
|
||||
### Toolbox setup
|
||||
|
||||
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.
|
||||
`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 ##
|
||||
|
||||
The following options are understood:
|
||||
|
||||
**--distro** DISTRO, **-d** DISTRO
|
||||
|
||||
Create a toolbox container for a different operating system DISTRO than the
|
||||
|
|
@ -68,6 +74,9 @@ Change the NAME of the base image used to create the toolbox container. This
|
|||
is useful for creating containers from custom-built base images. Cannot be used
|
||||
used with `--release`.
|
||||
|
||||
If NAME does not contain a domain, the image will be pulled from
|
||||
`registry.fedoraproject.org`.
|
||||
|
||||
**--release** RELEASE, **-r** RELEASE
|
||||
|
||||
Create a toolbox container for a different operating system RELEASE than the
|
||||
|
|
@ -95,4 +104,4 @@ $ toolbox create --image bar foo
|
|||
|
||||
## SEE ALSO
|
||||
|
||||
`buildah(1)`, `podman(1)`
|
||||
`toolbox(1)`, `toolbox-init-container(1)`, `podman(1)`, `podman-create(1)`
|
||||
|
|
|
|||
|
|
@ -16,9 +16,8 @@ if it's not available inside the container then it falls back to `/bin/bash`.
|
|||
|
||||
When invoked without any options, `toolbox enter` will try to enter the default
|
||||
toolbox container for the host, or if there's only one container available then
|
||||
it will use it. On Fedora, the default container is known as
|
||||
`fedora-toolbox-N`, where N is the release of the host. If there aren't any
|
||||
containers, `toolbox enter` will offer to create the default one for you.
|
||||
it will use it. If there aren't any containers, `toolbox enter` will offer to
|
||||
create one for you.
|
||||
|
||||
A specific container can be selected using the CONTAINER argument.
|
||||
|
||||
|
|
@ -61,4 +60,5 @@ $ toolbox enter foo
|
|||
|
||||
## SEE ALSO
|
||||
|
||||
`buildah(1)`, `podman(1)`, `podman-exec(1)`, `podman-start(1)`
|
||||
`toolbox(1)`, `toolbox-run(1)`, `podman(1)`, `podman-exec(1)`,
|
||||
`podman-start(1)`
|
||||
|
|
|
|||
|
|
@ -29,3 +29,7 @@ $ toolbox help
|
|||
```
|
||||
$ toolbox help create
|
||||
```
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
`toolbox(1)`
|
||||
|
|
|
|||
|
|
@ -21,8 +21,7 @@ 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
|
||||
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.
|
||||
### Shortcoming of container configuration
|
||||
|
||||
OCI containers are inherently immutable. Configuration options passed through
|
||||
`podman create` are baked into the definition of the OCI container, and can't
|
||||
|
|
@ -31,21 +30,35 @@ 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.
|
||||
|
||||
### Entry point utilization
|
||||
|
||||
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`,
|
||||
The passwords of the current user and root in the container are deleted.
|
||||
|
||||
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
|
||||
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.
|
||||
are kept synchronized with the host. This is something not very common in
|
||||
classic containers where the configuration is permanently baked in.
|
||||
|
||||
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.
|
||||
|
||||
If KCM is used as the default Kerberos credentials cache, it is also set up
|
||||
inside of a toolbox container.
|
||||
|
||||
To give users the ability to tell programatically if they are in a toolbox, the
|
||||
entry point creates `/run/.toolboxenv` which is an empty file analogous to
|
||||
`/run/.containerenv`.
|
||||
|
||||
## OPTIONS ##
|
||||
|
||||
The following options are understood:
|
||||
|
|
@ -57,7 +70,23 @@ container.
|
|||
|
||||
**--home** HOME
|
||||
|
||||
Create a user inside the toolbox container whose login directory is HOME.
|
||||
Create a user inside the toolbox container whose login directory is HOME. This
|
||||
option is required.
|
||||
|
||||
**--shell** SHELL
|
||||
|
||||
Create a user inside the toolbox container whose login shell is SHELL. This
|
||||
option is required.
|
||||
|
||||
**--uid** UID
|
||||
|
||||
Create a user inside the toolbox container whose numerical user ID is UID. This
|
||||
option is required.
|
||||
|
||||
**--user** USER
|
||||
|
||||
Create a user inside the toolbox container whose login name is LOGIN. This
|
||||
option is required.
|
||||
|
||||
**--home-link**
|
||||
|
||||
|
|
@ -74,21 +103,34 @@ Make `/mnt` a symbolic link to `/var/mnt`.
|
|||
**--monitor-host**
|
||||
|
||||
Ensure that certain configuration files inside the toolbox container are kept
|
||||
synchronized with their counterparts on the host. Currently, these files are
|
||||
`/etc/hosts` and `/etc/resolv.conf`.
|
||||
synchronized with their counterparts on the host.
|
||||
|
||||
**--shell** SHELL
|
||||
The synchronized files are:
|
||||
|
||||
Create a user inside the toolbox container whose login shell is SHELL.
|
||||
- `/etc/host.conf`
|
||||
- `/etc/hosts`
|
||||
- `/etc/localtime`
|
||||
- `/etc/resolv.conf`
|
||||
- `/etc/timezone`
|
||||
|
||||
**--uid** UID
|
||||
The following paths are bind mounted to paths from the host's filesystem
|
||||
available in the container:
|
||||
|
||||
Create a user inside the toolbox container whose numerical user ID is UID.
|
||||
- `/etc/machine-id`
|
||||
- `/run/libvirt`
|
||||
- `/run/systemd/journal`
|
||||
- `/run/systemd/resolve`
|
||||
- `/run/udev/data`
|
||||
- `/tmp`
|
||||
- `/var/lib/flatpak`
|
||||
- `/var/lib/libvirt`
|
||||
- `/var/lib/systemd/coredump`
|
||||
- `/var/log/journal`
|
||||
- `/var/mnt`
|
||||
|
||||
**--user** USER
|
||||
|
||||
Create a user inside the toolbox container whose login name is LOGIN.
|
||||
If path `/sys/fs/selinux` is found in the container, path `/usr/share/empty` is
|
||||
bind-mounted to that location to suppress SELinux.
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
`podman(1)`, `podman-create(1)`, `podman-start(1)`
|
||||
`toolbox(1)`, `podman(1)`, `podman-create(1)`, `podman-start(1)`
|
||||
|
|
|
|||
|
|
@ -45,4 +45,4 @@ $ toolbox list --images
|
|||
|
||||
## SEE ALSO
|
||||
|
||||
`buildah(1)`, `podman(1)`
|
||||
`toolbox(1)`, `podman(1)`, `podman-ps(1)`, `podman-images(1)`
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
toolbox\-rm - Remove one or more toolbox containers
|
||||
|
||||
## SYNOPSIS
|
||||
**toolbox rm** [*--all*] [*--force*] [*CONTAINER*...]
|
||||
**toolbox rm** [*--all* | *-a*] [*--force* | *-f*] [*CONTAINER*...]
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
|
|
@ -49,4 +49,4 @@ $ toolbox rm --all --force
|
|||
|
||||
## SEE ALSO
|
||||
|
||||
`buildah(1)`, `podman(1)`, `podman-rm(1)`
|
||||
`toolbox(1)`, `podman(1)`, `podman-rm(1)`
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
toolbox\-rmi - Remove one or more toolbox images
|
||||
|
||||
## SYNOPSIS
|
||||
**toolbox rmi** [*--all*] [*--force*] [*IMAGE*...]
|
||||
**toolbox rmi** [*--all* | *-a*] [*--force* | *-f*] [*IMAGE*...]
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
|
|
@ -49,4 +49,4 @@ $ toolbox rmi --all --force
|
|||
|
||||
## SEE ALSO
|
||||
|
||||
`buildah(1)`, `podman(1)`, `podman-rmi(1)`
|
||||
`toolbox(1)`, `podman(1)`, `podman-rmi(1)`
|
||||
|
|
|
|||
|
|
@ -13,13 +13,17 @@ toolbox\-run - Run a command in an existing toolbox container
|
|||
Runs a command inside an existing toolbox container. The container should have
|
||||
been created using the `toolbox create` command.
|
||||
|
||||
`toolbox run` wraps around `podman exec` and by default passes several options
|
||||
to it. It allocates a tty, connects to stdin, runs the passed command as the
|
||||
current user in the current directory and shares common environmental
|
||||
variables.
|
||||
|
||||
The executed command is wrapped in `capsh` that gets rid of all extra
|
||||
capabilities that could negatively affect the experience.
|
||||
|
||||
A toolbox container is an OCI container. Therefore, `toolbox run` is analogous
|
||||
to a `podman start` followed by a `podman exec`.
|
||||
|
||||
By default, the toolbox containers are tagged with the version of the OS that
|
||||
corresponds to the content inside them. Their names are prefixed with the name
|
||||
of the base image and suffixed with the current user name.
|
||||
|
||||
## OPTIONS ##
|
||||
|
||||
The following options are understood:
|
||||
|
|
@ -62,4 +66,5 @@ $ toolbox run --container foo uptime
|
|||
|
||||
## SEE ALSO
|
||||
|
||||
`buildah(1)`, `podman(1)`, `podman-exec(1)`, `podman-start(1)`
|
||||
`toolbox(1)`, `podman(1)`, `podman-exec(1)`, `podman-start(1)`, `capsh(1)`,
|
||||
`sh(1)`
|
||||
|
|
|
|||
|
|
@ -4,7 +4,11 @@
|
|||
toolbox - Unprivileged development environment
|
||||
|
||||
## SYNOPSIS
|
||||
**toolbox** [*--verbose* | *-v*] *COMMAND* [*ARGS*]
|
||||
**toolbox** [*--assumeyes* | *-y*]
|
||||
[*--help* | *-h*]
|
||||
[*--log-level LEVEL*]
|
||||
[*--log-podman*]
|
||||
*COMMAND* [*ARGS*...]
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
|
|
@ -34,7 +38,7 @@ 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..
|
||||
|
||||
## OPTIONS ##
|
||||
## GLOBAL OPTIONS ##
|
||||
|
||||
The following options are understood:
|
||||
|
||||
|
|
@ -46,10 +50,15 @@ Automatically answer yes for all questions.
|
|||
|
||||
Print a synopsis of this manual and exit.
|
||||
|
||||
**--verbose, -v**
|
||||
**--log-level**=*level*
|
||||
|
||||
Print debug information including standard error stream of internal commands.
|
||||
Use `-vv` for more detail.
|
||||
Log messages above specified level: debug, info, warn, error, fatal or panic
|
||||
(default: error)
|
||||
|
||||
**--log-podman**
|
||||
|
||||
Show log messages of invocations of Podman based on the logging level specified
|
||||
by option **log-level**.
|
||||
|
||||
## COMMANDS
|
||||
|
||||
|
|
@ -87,6 +96,37 @@ Remove one or more toolbox images.
|
|||
|
||||
Run a command in an existing toolbox container.
|
||||
|
||||
## Toolbox images
|
||||
|
||||
Toolbox currently supports these images:
|
||||
|
||||
registry.fedoraproject.org/fedora-toolbox
|
||||
: default image on Fedora
|
||||
|
||||
registry.access.redhat.com/ubi8
|
||||
: default image on RHEL
|
||||
|
||||
Images in this list are tested to be working with Toolbox. Any other image may
|
||||
work as well, but it is not guaranteed.
|
||||
|
||||
### NOTE: Name change of default Fedora image
|
||||
|
||||
Since version 0.0.99.1 Toolbox started to use registry.fedoraproject.org/fedora-toolbox
|
||||
instead of registry.fedoraproject.org/f{version}/fedora-toolbox. The image is
|
||||
still the same, only the name has changed.
|
||||
|
||||
Existing containers are not affected by this change, only new ones.
|
||||
|
||||
## Toolbox containers
|
||||
|
||||
Information about how toolbox containers are created can be found in
|
||||
`toolbox-create(1)`.
|
||||
|
||||
Information about the entry-point of toolbox containers can be found in
|
||||
`toolbox-init-container(1)`.
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
`buildah(1)`, `podman(1)`
|
||||
`podman(1)`, `toolbox-create(1)`, `toolbox-enter(1)`, `toolbox-run(1)`,
|
||||
`toolbox-init-container(1)`, `toolbox-list(1)`, `toolbox-rm(1)`,
|
||||
`toolbox-rmi(1)` `toolbox-help(1)`, https://github.com/containers/toolbox
|
||||
|
|
|
|||
Loading…
Reference in New Issue