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
- 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
The Go implementation prefers a newer syntax for assigning a custom
name to a toolbox container. The --container option is still supported
for backwards compatibility, but the manuals should show the new
workflow.
https://github.com/containers/toolbox/pull/681
The Go implementation prefers a newer syntax for assigning a custom
name to a toolbox container. The --container option is still supported
for backwards compatibility, but the manuals should show the new
workflow.
https://github.com/containers/toolbox/pull/678
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 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
This is meant to allow the user to create toolbox containers of
operating system distributions that are different from that of the
host and isn't Fedora.
https://github.com/containers/toolbox/pull/667
The --candidate-registry is a lesser known option only supported by
the POSIX shell implementation. The Go never implementation never
offered it, and nobody has felt its absence so far. So, it's safe to
assume that there's no urgent need to port it to Go, and it's better to
not confuse users by mentioning it.
https://github.com/containers/toolbox/pull/662
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
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
This makes 'toolbox enter' similar to 'toolbox run $SHELL'.
The 'run' command is meant to spawn arbitrary binaries present inside
the toolbox container. Therefore it doesn't make sense for it to fall
back to /bin/bash, like it does for 'enter' if $SHELL is absent.
It's expected that users might use 'run' to create ad-hoc *.desktop
files. That's why it neither offers to create nor falls back to an
existing container like 'enter' does, because such interactions can't
happen when used in a *.desktop file. It's also a more advanced command
that new users are less likely to be interested in. Hence, this
shouldn't affect usability.
Some changes by Debarshi Ray.
https://github.com/debarshiray/toolbox/pull/76
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
The manuals shouldn't be installed in the top-level directory, but in
one of the sub-directories corresponding to the relevant section.
Fallout from 0a972dfccc
It's useful to know things like a running toolbox container has to be
stopped before removal or 'rm --force' needs to be used, etc.. This is
implicitly tied to the fact that entering a toolbox container is
equivalent to a 'podman start' followed by a 'podman exec'.
