diff --git a/doc/toolbox-create.1.md b/doc/toolbox-create.1.md index f704a02b4..6ba9f9fea 100644 --- a/doc/toolbox-create.1.md +++ b/doc/toolbox-create.1.md @@ -26,36 +26,42 @@ 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. - -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. +Read more about the entry-point in `toolbox-init-container(1)`. -## OPTIONS ## +### 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)` -The following options are understood: +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 @@ -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)` diff --git a/doc/toolbox-enter.1.md b/doc/toolbox-enter.1.md index d71be5d54..b915f512c 100644 --- a/doc/toolbox-enter.1.md +++ b/doc/toolbox-enter.1.md @@ -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)` diff --git a/doc/toolbox-help.1.md b/doc/toolbox-help.1.md index 684221f94..e68009509 100644 --- a/doc/toolbox-help.1.md +++ b/doc/toolbox-help.1.md @@ -29,3 +29,7 @@ $ toolbox help ``` $ toolbox help create ``` + +## SEE ALSO + +`toolbox(1)` diff --git a/doc/toolbox-init-container.1.md b/doc/toolbox-init-container.1.md index a73975744..8bf852151 100644 --- a/doc/toolbox-init-container.1.md +++ b/doc/toolbox-init-container.1.md @@ -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`. - -**--shell** SHELL - -Create a user inside the toolbox container whose login shell is SHELL. - -**--uid** UID - -Create a user inside the toolbox container whose numerical user ID is UID. - -**--user** USER - -Create a user inside the toolbox container whose login name is LOGIN. +synchronized with their counterparts on the host. + +The synchronized files are: + +- `/etc/host.conf` +- `/etc/hosts` +- `/etc/localtime` +- `/etc/resolv.conf` +- `/etc/timezone` + +The following paths are bind mounted to paths from the host's filesystem +available in the container: + +- `/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` + +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)` diff --git a/doc/toolbox-list.1.md b/doc/toolbox-list.1.md index 2c2a35526..a2692316b 100644 --- a/doc/toolbox-list.1.md +++ b/doc/toolbox-list.1.md @@ -45,4 +45,4 @@ $ toolbox list --images ## SEE ALSO -`buildah(1)`, `podman(1)` +`toolbox(1)`, `podman(1)`, `podman-ps(1)`, `podman-images(1)` diff --git a/doc/toolbox-rm.1.md b/doc/toolbox-rm.1.md index df98c403e..57a3a801b 100644 --- a/doc/toolbox-rm.1.md +++ b/doc/toolbox-rm.1.md @@ -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)` diff --git a/doc/toolbox-rmi.1.md b/doc/toolbox-rmi.1.md index 25113e929..41c0e6c18 100644 --- a/doc/toolbox-rmi.1.md +++ b/doc/toolbox-rmi.1.md @@ -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)` diff --git a/doc/toolbox-run.1.md b/doc/toolbox-run.1.md index ca00cc13f..e34f93b89 100644 --- a/doc/toolbox-run.1.md +++ b/doc/toolbox-run.1.md @@ -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)` diff --git a/doc/toolbox.1.md b/doc/toolbox.1.md index de1581a99..2fdedbb0a 100644 --- a/doc/toolbox.1.md +++ b/doc/toolbox.1.md @@ -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