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
Without a sufficient buffer size the discard function does not read
fast/efficiently enough causing multiple lines indicating "passed and
discarded input" to show up.
I used an already defined constant[0] for the buffer size to prevent
the use of a yet-another magical constant.
[0] https://pkg.go.dev/bytes#pkg-constantshttps://github.com/containers/toolbox/pull/1427
A subsequent commit will use this to ensure that the user can still
interact with the image download prompt while 'skopeo inspect' fetches
the image size from the remote registry.
Initially, the prompt will be shown without the image size. Once the
size has been fetched, the older prompt will be cancelled and a new one
will be shown that includes the size. While the prompt is getting
updated, the terminal device will be put into non-canonical mode input
and the echoing of input characters will be disabled to retain full
control of the cursor position. Once the new prompt is in place, the
previous state of the terminal will be restored. However, anything that
was typed in the interim will be discarded to avoid surprising the user
with invisible input.
Even though this code is only expected to be used to read from the
standard input stream when it's connected to a terminal device, the use
of poll(2) here was tested with FIFOs or named pipes and regular files
as well, in case they might be necessary in future.
https://github.com/containers/toolbox/issues/752https://github.com/containers/toolbox/issues/1263
A subsequent commit will use this to ensure that the user can still
interact with the image download prompt while 'skopeo inspect' fetches
the image size from the remote registry. Initially, the prompt will be
shown without the image size. Once the size has been fetched, the older
prompt will be cancelled and a new one will be shown that includes the
size.
Even though this code is only expected to be used to read from the
standard input stream when it's connected to a terminal device, the use
of poll(2) here was tested with FIFOs or named pipes and regular files
as well, in case they might be necessary in future.
An eventfd(2) file descriptor expects a 8-byte or 64-bit integer value
to be given to write(2) to increase its counter by that amount [1]. In
C, it could be phrased as:
uint64_t one = 1;
write (eventfd, &one, sizeof (one));
However, Go's wrapper for write(2) expects a sequence of bytes (ie.,
[]byte), and not an arbitrary memory address [2]. Therefore, the
'encoding/binary' package [3] is used to encode the integer into a byte
sequence as a varint.
Even though a varint-encoded 64-bit integer takes a maximum of 10
bytes, as defined by binary.MaxVarintLen64, 1 byte is enough to encode
the number 1 as an unsigned 64-bit integer [4]. That's enough to fit
into a byte sequence of length 8 to satisfy what an eventfd(2) file
descriptor expects. Ultimately, it doesn't matter exactly what value
the receiving end assigns to the number given to write(2), as long as
it's not zero.
[1] https://man7.org/linux/man-pages/man2/eventfd.2.html
[2] https://pkg.go.dev/golang.org/x/sys/unix#Write
[3] https://pkg.go.dev/encoding/binary
[4] https://protobuf.dev/programming-guides/encoding/https://github.com/containers/toolbox/issues/752https://github.com/containers/toolbox/issues/1263
fmt.Scanf [1] is fragile when it comes to space-separated input. It
stores successive space-separated values into successive arguments as
determined by the format string. This breaks with untrusted input that
can have an unknown number of space-separated values.
Here are some examples:
$ toolbox create
Image required to create toolbox container.
Download registry.fedoraproject.org/fedora-toolbox:39 (294.8MB)?
[y/N]: no no not at all
$ no not at all
bash: no: command not found...
$ toolbox create
Image required to create toolbox container.
Download registry.fedoraproject.org/fedora-toolbox:39 (294.8MB)?
[y/N]: foo bar
Download registry.fedoraproject.org/fedora-toolbox:39 (294.8MB)?
[y/N]: Download registry.fedoraproject.org/fedora-toolbox:39
(294.8MB)? [y/N]:
Instead this is what should happen:
$ toolbox create
Image required to create toolbox container.
Download registry.fedoraproject.org/fedora-toolbox:39 (294.8MB)?
[y/N]: no no not at all
Download registry.fedoraproject.org/fedora-toolbox:39 (294.8MB)?
[y/N]: foo bar
Download registry.fedoraproject.org/fedora-toolbox:39 (294.8MB)?
[y/N]:
Fallout from 936f22ff15
[1] https://pkg.go.dev/fmt#Scanfhttps://github.com/containers/toolbox/pull/1279
Currently, the container name and release are only validated if they
were specified as command line options. Neither the value of release
in the configuration file nor the container name generated from an
image are validated.
There's also a lot of repeated code in the command front-ends to
validate the container name and release. This opens the door for
mistakes. Any adjustment to the code must be repeated elsewhere, and
there are subtle interactions and overlaps between the validation code
and the code to resolve container and image names.
It's worth noting that the container and image name resolution happens
for both the command line and configuration file options, and generates
the container name from the image when necessary.
Therefore, validating everything while resolving cleans up the command
front-ends and increases the coverage of the validation.
This introduces the use of sentinel error values and custom error
implementations to identify the different errors that can occur while
resolving the container and images, so that they can be appropriately
shown to the user.
https://github.com/containers/toolbox/pull/1101
Using a non-supported distribution via `--distro` resulted in a silent
fallback to the Fedora image which confuses users. When a faulty release
format was used with `--release` a message without any hint about the
correct format was shown to the user.
This separates distro and release parsing into two chunks that have
greater control over error reporting and provides more accurate error
reports for the user.
Fixes https://github.com/containers/toolbox/issues/937https://github.com/containers/toolbox/pull/977
This will be used by the subsequent commit to highlight some of the
more common commands that new user is likely to be interested in, when
none has been specified.
https://github.com/containers/toolbox/pull/951
Fedora CoreOS systems do not have the man command installed. Running
toolbox --help on such a system results in a "man(1) not found" error.
As a compromise for systems without man, we added a simple help text
showing the most commonly used toolbox commands and an URL that direct
users to the Toolbox website where they can find the manuals in Markdown
format.
Fixes#713https://github.com/containers/toolbox/pull/837
pkg/utils has been in Go Toolbox since its birth. Along the way it
accumulated a number of functions where a few of them are purely CLI
related. Since the majority of functions in the package are related to
some "deeper" functionality in Toolbox, it makes more sense to move the
selected few to package cmd. This will make pkg/utils a bit leaner and
create a dedicated space for cmd utility functions to live in.
In the process the error creation functions no longer require the
executableBase argument to be passed to them.
https://github.com/containers/toolbox/pull/819
Debarshi Ray
Ondřej Míchal
Oliver Gutierrez