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
The phrase 'using a custom image' is awkward because it makes it sound
as if the image plays an important role in 'enter' and 'run'. That's
not true.
Also, titles are sweeter when they are shorter.
https://github.com/containers/toolbox/pull/1281
Signed-off-by: Nils Lindemann <nilslindemann@tutanota.com>
When a specific Toolbx container is selected by name for 'enter' and
'run', it's not necessary that the container was created using a custom
image. The container could have also been created using one of the
built-in images.
Secondly, the phrase 'using a custom image' is awkward because it makes
it sound as if the image plays an important role in 'enter' and 'run'.
That's not true.
Finally, titles are sweeter when they are shorter.
https://github.com/containers/toolbox/pull/1281
Signed-off-by: Nils Lindemann <nilslindemann@tutanota.com>
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
CentOS Stream 9 has codespell-2.2.1, while so far the 'unit tests' were
being run on Fedora 36, which only has codespell-2.1.0.
This is a step towards testing on CentOS Stream 9.
Fallout from 708fa593e2https://github.com/containers/toolbox/pull/1199
This mirrors the --preserve-fds option of Podman.
Converting an unsigned 'uint', which is what Podman uses for its
--preserve-fds option, to a string is surprisingly annoying.
strconv.Itoa [1] takes a signed 'int', which would require a cast, and
there's no unsigned counterpart. There's strconv.FormatUint [2] which
takes an unsigned 'uint64', which is better, but would still require a
cast.
So, fmt.Sprint [3] it is, if the cast is to be avoided. It's more
expensive than the other two functions, but there's no need to worry
unless it's proven to be a performance bottle neck.
Some changes by Debarshi Ray.
[1] https://pkg.go.dev/strconv#Itoa
[2] https://pkg.go.dev/strconv#FormatUint
[3] https://pkg.go.dev/fmt#Sprinthttps://github.com/containers/toolbox/issues/1066
Signed-off-by: Allison Karlitskaya <allison.karlitskaya@redhat.com>
When describing the --authfile option, the word 'private' is used to
refer to images needing authentication. Using the same word shortens
the text so that the word 'custom' can be used in the same way as in the
other examples.
https://github.com/containers/toolbox/pull/1107
When a command is executed with toolbox run and it returns a non-zero
exit code, it is just ignored if that exit code is not handled. This
prevents users to identify errors when executing commands in toolbox.
With this fix, the exit codes of the invoked command are propagated
and returned by 'toolbox run'. This includes even exit codes returned
by Podman on error.
https://github.com/containers/toolbox/pull/1013
Co-authored-by: Ondřej Míchal <harrymichal@seznam.cz>
This will be used by the subsequent commit to add a page to document
the configuration file, which should go into section 5 of the manual.
https://github.com/containers/toolbox/pull/963
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
This builds upon commit ea452d7ced.
The configuration of a toolbox container is a higher level topic than
the entry point, and the entry point is mentioned as one part of it.
Therefore, putting the section on toolbox set-up earlier in the text
makes it nicely flow from the DESCRIPTION section into the Entry Point
sub-section.
Emphasize the user-visible features of a toolbox container, and not
the underlying implementation details, and avoid using too much jargon
about container technology.
https://github.com/containers/toolbox/pull/814
It was a deliberate decision to have entry point documented in both
toolbox-create(1) and toolbox-init-container(1). For technical
documentation it's sometimes good to repeat the same thing if it's
sufficiently important. Either to refresh the user's memory or to draw
their attention to it. Having to traverse too many references can get
disorienting. eg., parts of README.md are already repeated in
toolbox(1).
In this case, the entry point is very directly related to the create
command because the command sets it up, and unlike HTML documents,
it's awkward to follow links from manuals.
This reverts parts of commit ea452d7ced.
https://github.com/containers/toolbox/pull/814
The DESCRIPTION already explains the details of the set-up on Fedora,
so there's no need to be so specific here. Plus, conceptually, it's not
meant to be Fedora-specific. Fedora is just an example and happens to
be the most well-supported one at the moment, but that will change.
https://github.com/containers/toolbox/pull/814
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
Debarshi Ray