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

89 lines
3 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
**toolbox init-container** *--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-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
A key feature of toolbox containers is their entry point, the `toolbox
init-container` command.
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
current user by ensuring that it has a user that matches the one on the host.
It ensures that configuration files, such as `/etc/host.conf`, `/etc/hosts`,
`/etc/localtime`, `/etc/resolv.conf` and `/etc/timezone`, inside the container
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.
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:
**--home** HOME
Create a user inside the toolbox container whose login directory is 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**
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**
Ensure that certain configuration files inside the toolbox container are kept
synchronized with their counterparts on the host. Currently, these files are
`/etc/hosts` and `/etc/resolv.conf`.
**--shell** SHELL
Create a user inside the toolbox container whose login shell is SHELL.
**--uid** UID
Create a user inside the toolbox container whose numerical user ID is UID.
**--user** USER
Create a user inside the toolbox container whose login name is LOGIN.
## SEE ALSO
`podman(1)`, `podman-create(1)`, `podman-start(1)`
Reference in a new issue Copy permalink