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

doc/toolbox-create.1.md

@@ -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
+Read more about the entry-point in `toolbox-init-container(1)`.
-`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
+### Toolbox setup
-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
+`toolbox-create(1)` passes several options to `podman-create(1)` when creating
-`/mnt` are symbolic links to other locations. The entry point ensures that
+toolbox containers to provide the needed functionality. The options have the
-paths inside the container match those on the host, to avoid needless
+following effects:
-confusion.
+
+- 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)`

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
+it will use it. If there aren't any containers, `toolbox enter` will offer to
-`fedora-toolbox-N`, where N is the release of the host. If there aren't any
+create one for you.
-containers, `toolbox enter` will offer to create the default 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)`

doc/toolbox-help.1.md

@@ -29,3 +29,7 @@ $ toolbox help
 ```
 $ toolbox help create
 ```
+
+## SEE ALSO
+
+`toolbox(1)`

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
+### Shortcoming of container configuration
-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
@@ -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
+are kept synchronized with the host. This is something not very common in
-subsets of the host's filesystem hierarchy to their corresponding locations
+classic containers where the configuration is permanently baked in.
-inside the container to provide seamless integration with the host. This
+
-includes `/run/libvirt`, `/run/systemd/journal`, `/run/udev/data`,
+The entry point also bind mounts various subsets of the host's filesystem
-`/var/lib/libvirt`, `/var/lib/systemd/coredump`, `/var/log/journal` and others.
+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
+synchronized with their counterparts on the host.
-`/etc/hosts` and `/etc/resolv.conf`.
 
-**--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
+If path `/sys/fs/selinux` is found in the container, path `/usr/share/empty` is
-
+bind-mounted to that location to suppress SELinux.
-Create a user inside the toolbox container whose login name is LOGIN.
 
 ## SEE ALSO
 
-`podman(1)`, `podman-create(1)`, `podman-start(1)`
+`toolbox(1)`, `podman(1)`, `podman-create(1)`, `podman-start(1)`

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)`

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)`

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)`

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)`

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.
+Log messages above specified level: debug, info, warn, error, fatal or panic
-Use `-vv` for more detail.
+(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