The --monitor-host option was added to the 'init-container' command in
commit 8b84b5e460 to accommodate Podman versions older than 1.2.0
that didn't have the '--dns none' and '--no-hosts' options for
'podman create'. These options are necessary to keep the Toolbx
container's /etc/resolv.conf and /etc/hosts files synchronized with
those of the host.
Note that Podman 1.2.0 was already available a few months before
commit 8b84b5e460 introduced the --monitor-host option. The
chances of someone using an older Podman back then was already on the
decline, and it's very unlikely that a container created with such a
Podman has survived till this date.
Commit b6b484fa79 raised the minimum required Podman version to
1.4.0, and made the '--dns none' and '--no-hosts' options a hard
requirement. The minimum required Podman version was again raised
recently in commit 8e80dd5db1 to 1.6.4. Therefore, these days,
there's no need to separately use the --monitor-host option of
'init-container' for newly created containers to indicate that the
Podman version wasn't older than 1.2.0.
Given all this, it's time to stop using the --monitor-host option of
'init-container', and assume that it's always set. The option is still
accepted to retain compatibility with existing Toolbx containers.
For containers that were created with the --monitor-host option, a
deprecation notice will be shown as:
$ podman start --attach CONTAINER
Flag --monitor-host has been deprecated, it does nothing
...
https://github.com/containers/toolbox/pull/617
Currently, the titles of the manuals are rendered with a pair of empty
parentheses and no section title:
toolbox(1)() toolbox(1)()
NAME
toolbox - Tool for containerized command line environments...
However, they should be:
toolbox(1) General Commands Manual toolbox(1)
NAME
toolbox - Tool for containerized command line environments...
This is because the troff generated by go-md2man from Markdown has a
faulty invocation of the .TH macro [1]:
.nh
.TH toolbox(1)
.SH NAME
.PP
toolbox - Tool for containerized command line environments on Linux
It should be:
.nh
.TH toolbox 1
.SH NAME
.PP
toolbox - Tool for containerized command line environments on Linux
Original patch from Andrew Denton for Podman [2].
[1] https://www.gnu.org/software/groff/manual/groff.html
[2] Podman commit 63c779a857b55b00
https://github.com/containers/podman/pull/15621https://github.com/containers/toolbox/pull/1210
SELinux is always meant to be disabled. The exact location of the code
is a historical accident and isn't meant to imply that SELinux might
be optionally enabled.
https://github.com/containers/toolbox/pull/814
Avoid phrases like "shortcoming of container configuration", because
it makes one wonder why a known shortcoming is even being used or not
being fixed. Immutability also has its advantages for certain
use-cases, and it's beyond the scope of this manual to have a full
blown discussion about the pros and cons of OCI containers. Interested
readers can research that on their own.
https://github.com/containers/toolbox/pull/814
- 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/617https://github.com/containers/toolbox/pull/512
When taking ownership of the runtime directory or the initialization
stamp file inside it, it was assumed that the user's GID and UID were
the same. However that might not always be the case.
Note that this commit doesn't use the GID passed from the host to the
toolbox container's entry point to configure the user inside the
container. That is actually more difficult than it sounds. The manual
for useradd(8) says that the group specified by the '--gid' flag must
actually exist.
https://github.com/containers/toolbox/issues/664
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 8b84b5e460https://github.com/containers/toolbox/pull/160
[2] Commit 9dc5281430https://github.com/containers/toolbox/pull/336https://github.com/containers/toolbox/pull/677
The whole idea behind commit 66e982af72 was to set up $HOME and
/home to match the host. Therefore, it's pointless to check if /home
is a symbolic link or not inside the toolbox container. The state of
/home needs to be checked on the host, and then the toolbox container
adjusted accordingly.
One crucial difference is that the toolbox container is created before
its /home can be adjusted. Earlier, there was the user-specific
customized image, whose /home was adjusted first, and then the toolbox
container created from that. This boils down to the following
invocation happening before the symbolic link can be set up:
podman create --volume "$HOME":$HOME":rslave --workdir "$HOME" ...
As a result, on host operating systems like Fedora 29 where /home is a
symbolic link with $HOME pointing inside it, Podman populates /home
with the user's sub-directory inside the toolbox container. This
prevents the subsequent 'rmdir $HOME' from working, and consequently
kills the container's entry point.
Compare that to Fedora 30 and newer where this problem doesn't occur
because /home is a symbolic link but $HOME points inside the target
/var/home directory.
This is why $HOME is canonicalized before bind mounting it into the
container and the container's working directory is reverted back to the
default (ie. /).
Fallout from 8b84b5e460https://github.com/debarshiray/toolbox/issues/185
This works by configuring the toolbox container after it has been
created, instead of before. The toolbox script itself is mentioned as
the entry point of the container, which does 'exec sleep +Inf' once the
initialization is done.
A new command 'init-container' was added to perform the initialization.
It is primarily meant to 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.
As a result, the default name for the toolbox containers is now
fedora-toolbox-<version-id>, not fedora-toolbox-<user>-<version-id>.
For backwards compatibility, 'toolbox enter' and 'toolbox run' will
continue to work with containers using the old naming scheme.
https://github.com/debarshiray/toolbox/pull/160
