wbrawner/toolbox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
toolbox/doc/toolbox-init-container.1.md

123 lines
3.6 KiB
Markdown
Raw Normal View History

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-10 18:38:46 +00:00
% toolbox-init-container(1)
## NAME
toolbox\-init\-container - Initialize a running container
## SYNOPSIS
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-01-22 11:09:42 +00:00
**toolbox init-container** *--gid GID*
*--home HOME*
Unbreak setting up /home as a symbolic link The whole idea behind commit 66e982af729a4b7 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 8b84b5e4604921fad818ede5267591de7f0993e6 https://github.com/debarshiray/toolbox/issues/185
2019-06-07 11:55:42 +00:00
*--home-link*
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-21 17:33:12 +00:00
*--media-link*
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 18:15:35 +00:00
*--mnt-link*
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-10 18:38:46 +00:00
*--monitor-host*
*--shell SHELL*
*--uid UID*
*--user USER*
## DESCRIPTION
Initializes a newly created container that's running. 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.
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 10:05:22 +00:00
A key feature of toolbox containers is their entry point, the `toolbox
init-container` command.
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 8b84b5e4604921fa https://github.com/containers/toolbox/pull/160 [2] Commit 9dc52814301c5a3f https://github.com/containers/toolbox/pull/336 https://github.com/containers/toolbox/pull/677
2021-01-22 16:15:23 +00:00
OCI containers are inherently immutable. Configuration options passed through
`podman create` are baked into the definition of the OCI container, and can't
be changed later. This means that changes and improvements made in newer
versions of Toolbox can't be applied to pre-existing toolbox containers
created by older versions of Toolbox. This is avoided by using the entry point
to configure the container at runtime.
The entry point of a toolbox container customizes the container to fit the
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 10:05:22 +00:00
current user by ensuring that it has a user that matches the one on the host,
and grants it `sudo` and `root` access.
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-03-04 19:36:22 +00:00
Crucial configuration files, such as `/etc/host.conf`, `/etc/hosts`,
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 8b84b5e4604921fa https://github.com/containers/toolbox/pull/160 [2] Commit 9dc52814301c5a3f https://github.com/containers/toolbox/pull/336 https://github.com/containers/toolbox/pull/677
2021-01-22 16:15:23 +00:00
`/etc/localtime`, `/etc/resolv.conf` and `/etc/timezone`, inside the container
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 10:05:22 +00:00
are kept synchronized with the host. The entry point also bind mounts various
subsets of the host's filesystem hierarchy to their corresponding locations
inside the container to provide seamless integration with the host. This
includes `/run/libvirt`, `/run/systemd/journal`, `/run/udev/data`,
`/var/lib/libvirt`, `/var/lib/systemd/coredump`, `/var/log/journal` and others.
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 8b84b5e4604921fa https://github.com/containers/toolbox/pull/160 [2] Commit 9dc52814301c5a3f https://github.com/containers/toolbox/pull/336 https://github.com/containers/toolbox/pull/677
2021-01-22 16:15:23 +00:00
On some host operating systems, important paths like `/home`, `/media` or
`/mnt` are symbolic links to other locations. The entry point ensures that
paths inside the container match those on the host, to avoid needless
confusion.
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-10 18:38:46 +00:00
## OPTIONS ##
The following options are understood:
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-01-22 11:09:42 +00:00
**--gid** GID
Pass GID as the user's numerical group ID from the host to the toolbox
container.
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-10 18:38:46 +00:00
**--home** HOME
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-03-04 19:36:22 +00:00
Create a user inside the toolbox container whose login directory is HOME. This
option is required.
Unbreak setting up /home as a symbolic link The whole idea behind commit 66e982af729a4b7 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 8b84b5e4604921fad818ede5267591de7f0993e6 https://github.com/debarshiray/toolbox/issues/185
2019-06-07 11:55:42 +00:00
**--home-link**
Make `/home` a symbolic link to `/var/home`.
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-21 17:33:12 +00:00
**--media-link**
Make `/media` a symbolic link to `/run/media`.
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 18:15:35 +00:00
**--mnt-link**
Make `/mnt` a symbolic link to `/var/mnt`.
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-10 18:38:46 +00:00
**--monitor-host**
doc/toolbox-init-container: Style fixes https://github.com/containers/toolbox/pull/814
2021-06-26 10:55:55 +00:00
Ensures that certain configuration files inside the toolbox container are kept
synchronized with their counterparts on the host, and bind mounts some paths
from the host's file system into the container.
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-03-04 19:36:22 +00:00
The synchronized files are:
- `/etc/host.conf`
- `/etc/hosts`
- `/etc/localtime`
- `/etc/resolv.conf`
- `/etc/timezone`
doc/toolbox-init-container: Style fixes https://github.com/containers/toolbox/pull/814
2021-06-26 10:55:55 +00:00
The bind mounted paths are:
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-03-04 19:36:22 +00:00
- `/etc/machine-id`
- `/run/libvirt`
- `/run/systemd/journal`
- `/run/systemd/resolve`
- `/run/udev/data`
- `/tmp`
- `/var/lib/flatpak`
- `/var/lib/libvirt`
- `/var/lib/systemd/coredump`
- `/var/log/journal`
- `/var/mnt`
doc/toolbox-init-container: Style fixes https://github.com/containers/toolbox/pull/814
2021-06-26 10:55:55 +00:00
**--shell** SHELL
Create a user inside the toolbox container whose login shell is SHELL. This
option is required.
**--uid** UID
Create a user inside the toolbox container whose numerical user ID is UID. This
option is required.
**--user** USER
Create a user inside the toolbox container whose login name is LOGIN. This
option is required.
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-10 18:38:46 +00:00
## SEE ALSO
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-03-04 19:36:22 +00:00
`toolbox(1)`, `podman(1)`, `podman-create(1)`, `podman-start(1)`
Reference in a new issue Copy permalink