Commit graph

11 commits

Author SHA1 Message Date
Debarshi Ray
936a157117 doc, test/system: Fix the titles of the manuals
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/15621

https://github.com/containers/toolbox/pull/1210
2023-01-12 18:45:00 +01:00
Debarshi Ray
2b317b94b5 doc/toolbox-init-container: Style fixes
https://github.com/containers/toolbox/pull/814
2021-06-26 13:16:42 +02:00
Debarshi Ray
23256cb443 doc/toolbox-init-container: Avoid mentioning an implementation detail
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
2021-06-26 13:16:42 +02:00
Debarshi Ray
52880eefc9 doc/toolbox-init-container: Synchronize with doc/toolbox-create
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
2021-06-26 13:16:42 +02:00
Ondřej Míchal
ea452d7ced doc: Update to match current state & extend docs
- 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/617

https://github.com/containers/toolbox/pull/512
2021-05-24 17:15:50 +02:00
Michael Lingelbach
31d63e9511 Don't assume that the user's GID is the same as the UID
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
2021-03-10 16:23:50 +01:00
Ondřej Míchal
6543ff6a06 doc/toolbox-create, doc/toolbox-init-container: Mention the entry point
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 8b84b5e460
    https://github.com/containers/toolbox/pull/160

[2] Commit 9dc5281430
    https://github.com/containers/toolbox/pull/336

https://github.com/containers/toolbox/pull/677
2021-01-22 17:21:49 +01:00
Debarshi Ray
47c32712f4 Set up /mnt to match the host
On Silverblue /mnt is a symbolic link to /var/mnt. Matching what the
host does will reduce weird side-effects.

https://github.com/containers/toolbox/issues/92
2020-01-06 19:16:17 +01:00
Debarshi Ray
65e3eec06e Set up /media to match the host
On Silverblue /media is a symbolic link to /run/media. Matching what
the host does will reduce weird side-effects.

https://github.com/containers/toolbox/issues/330
2019-11-22 16:31:50 +01:00
Casey Jao
c2e41553db Unbreak setting up /home as a symbolic link
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 8b84b5e460

https://github.com/debarshiray/toolbox/issues/185
2019-06-17 23:28:34 +02:00
Debarshi Ray
8b84b5e460 Drop the Buildah dependency and the user-specific customized image
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
2019-05-16 15:47:33 +02:00