Using the word 'containerized' gives the false impression of heightened
security. As if it's a mechanism to run untrusted software in a
sandboxed environment without access to the user's private data (such as
$HOME), hardware peripherals (such as cameras and microphones), etc..
That's not what Toolbx is for.
Toolbx aims to offer an interactive command line environment for
development and troubleshooting the host operating system, without
having to install software on the host. That's all. It makes no
promise about security beyond what's already available in the usual
command line environment on the host that everybody is familiar with.
https://github.com/containers/toolbox/issues/1020
Mention that Toolbx is meant for system administrators to troubleshoot
the host operating system. The word 'debugging' is often used in the
context of software development, and hence most readers might not
interpret it as 'troubleshooting'.
https://github.com/containers/toolbox/pull/1549
This is meant to make the project more searchable on the Internet. More
and more people have been pointing out that "toolbox" is terribly
difficult to search for, and it's impossible to find any decent
Internet real estate by that name.
Some exceptions:
* The code repository is still https://github.com/containers/toolbox.
It will be renamed after giving a heads-up to other contributors.
* The name of the binary is still 'toolbox'. The name is embedded
into existing Toolbx containers as their entry point, which is bind
mounted from the host operating system when the containers are
started. Trivially renaming the binary will prevent these
containers from starting.
* For similar reasons, the TOOLBOX_PATH environment variable is still
the same.
* For similar reasons, the profile.d file to be read by the shell on
start-up is still called toolbox.sh.
* The label used to identify Toolbx containers and images is still
called com.github.containers.toolbox. There are many existing
Toolbx containers, and many Toolbx images beyond the control of the
Toolbx project that use this label to identity themselves. Simply
renaming the label will prevent these containers and images from
being recognized.
* The names of the built-in Toolbx images still retain the word
'toolbox'. Images under the new name need to be published on the
OCI registries and the toolbox(1) binary needs to be taught to
handle both old and new names, wherever necessary, for backwards
compatibility.
* The stamp file used to identify Toolbx containers is still called
/run/.toolboxenv because it's used by various external programs and
users to identify Toolbx containers.
* The OSC 777 escape sequence to track and preserve the user's current
Toolbx container [1] still emits 'toolbox' as the name of the
container runtime. Changing the escape sequence can break terminal
emulation applications, like Prompt [2], that consume it. Hence, it
needs to be done carefully.
* The runtime directories at /run/toolbox, when used as root, and
$XDG_RUNTIME_DIR/toolbox, when used rootless, weren't renamed.
When used as root, /run/toolbox is embedded into existing Toolbx
containers as a bind mount from the host. Trivially renaming the
path will prevent these containers from starting.
Secondly, both these paths are used to synchronize container
start-up. If the paths are trivially renamed, and the toolbox(1)
binary is updated and used without stopping all existing containers,
then it won't be able to enter containers that were already started.
Strictly speaking, this scenario isn't supported, since updates are
always expected to be "offline" [3]. However, it's worth noting
because solving the previous problem might also address this.
* The configuration file for RPM is still called
/usr/lib/rpm/macros.d/macros.toolbox.
[1] https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/17
[2] https://gitlab.gnome.org/chergert/prompt
[3] https://www.freedesktop.org/software/systemd/man/latest/systemd.offline-updates.htmlhttps://github.com/containers/toolbox/issues/1399
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
Some aspects of the Fedora image are described in toolbox-create(1),
but the exact URL of the image is an implementation detail. As Toolbox
grows, it will become unwieldy to describe these details in the
top-level manual.
https://github.com/containers/toolbox/pull/814
The manuals for the individual commands were already listed above.
The entry point of toolbox containers is prominently documented in
toolbox-create(1) and toolbox-init-container(1). It's not clear why
someone who has just come across toolbox(1) would want to know about
the entry point. It's, after all, an implementation detail. They
probably don't even know what's an entry point to begin with. The
top-level manual should give the reader an overall view of the tool
from a user's perspective, and let the other manuals draw them into the
finer details of things.
https://github.com/containers/toolbox/pull/814
It's good to document the --log-level and --log-podman flags because
they can give us some flexibility with the logging in future, but it's
still desirable to keep --verbose (and the -vv trick) in the manual.
Toolbox is still a small enough code base that not too many log levels
are actually needed, yet. The complexity of remembering which log
level reveals which detail soon starts to outweigh the simplicity of
dumping as much as possible, since there aren't that many log messages
to begin with. It's a lot easier to type and remember things like
--verbose, -v and -vv, than their newer counterparts, and they are a
reasonably widely used convention (eg., flatpak, nmap, ssh, etc.).
If some day Toolbox grows to have a significantly larger number of log
messages, then it's possible that --verbose would be of less use, but
that's not the case today.
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
The Go implementation had deprecated the reset command, right from the
beginning, in favour of 'podman system reset'. It's time to finally
remove it.
https://github.com/containers/toolbox/pull/668
Currently, toolbox(1) offers a --verbose option that only shows debug
information from toolbox(1) itself and the error stream of internal
commands. There's no way to further increase the log level of the
internal commands. It's sometimes very useful to be able to get more
detailed logs from Podman.
This adds a new --very-verbose or -vv option that makes this possible.
This should have been implemented as '--verbose --verbose', which
could be conveniently shortened to '-vv'. This is what flatpak(1)
does. However, due to the lack of built-in command line parsing
facilities in POSIX shell, there's no support for multiple short
options expressed as one single argument. eg., '-vy' doesn't expand to
'-v -y'.
Therefore, a separate --very-verbose or -vv option was added to make
things convenient for the user. It's expected that most people will
refer to this as -vv.
If this option is used, every Podman command in the code is run with
'--log-level debug'. Use wisely, Podman can be 'very verbose'.
https://github.com/containers/toolbox/pull/289
The 'reset' command is meant to factory reset the local Podman and
Toolbox installations. Every now and then early adopters and testers of
Toolbox have to do this when their local Podman state has gotten
irrecoverably broken due to some Podman bug.
It's useful to have a command that encapsulates all the steps to do a
factory reset, as opposed to having to spell them out separately. It's
easier to document, helps with user support, and can enable less opaque
error messages that suggest a way forward when nothing is working.
Since this command is meant to be used when the Podman installation is
completely broken, it must avoid using any Podman commands at all
costs. This is why it cannot use 'podman stop' to stop any running
containers, nor can it use 'podman unshare' to delete
~/.local/share/containers when running rootless. Instead, it relies on
the user rebooting the machine for the former, and uses newgidmap(1),
newuidmap(1) and unshare(1) to reimplement 'podman unshare' for the
latter.
Note that when running as root, some care has been taken to avoid
removing directories that might be owned by the operating system. eg.,
on Fedora /var/lib/containers/sigstore is owned by the
containers-common RPM.
https://github.com/containers/toolbox/pull/295
A new help command has been added which either shows the toolbox(1)
manual or a manual page for a specific command. The '--help' flag is
now identical to the help command and can be placed after the COMMAND
segment in the list of command line arguments.
Due to a bizarre quirk in less(1) [1], the default pager used to render
manuals on most systems, the man(1) invocations need the standard error
stream to point to the controlling terminal, if any, to work. This
interferes with the global redirection of standard error to /dev/null
in the absence of the '--verbose' flag, and is worked around by
redirecting to standard output instead.
[1] It turns out that less(1) tries to open the controlling terminal
device /dev/tty to get to the keyboard for accepting input.
However, it doesn't have a controlling terminal when invoked via
D-Bus to render a manual on the host. It then strangely falls back
to using the standard error stream to get to the keyboard.
https://github.com/debarshiray/toolbox/pull/200
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
Currently, there's no easy way to get the size of the impending
download. Skopeo doesn't offer the size of the OCI image [1] and it's
debatable whether another 23 MB binary ought to be pulled in as a
dependency just for this.
Given that the default fedora-toolbox images are the only base images
available via a public repository, the size of the download is hard
coded to reflect the approximate size of the fedora-toolbox images.
These images are between 451 MB and 483 MB, so 500 MB should be a
reasonably suggestive approximate that shouldn't negatively surprise
users.
[1] https://github.com/containers/skopeo/issues/641https://github.com/debarshiray/toolbox/issues/134
Debarshi Ray
Ondřej Míchal
Ondřej Zoder