Compare commits
18 commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 9ff633d04b | |||
|
|
0914617155 | ||
| 951b464d50 | |||
| 4d60442315 | |||
| 1c389e3eb4 | |||
| 63ef4ae48f | |||
| e657f2554f | |||
| 38d38e140e | |||
| 1b4486460a | |||
| a1d5815684 | |||
| 08f4699d4a | |||
| a4947a9269 | |||
| 87d7ad6a72 | |||
| bfcccc0943 | |||
| 92830d1635 | |||
|
|
85ef0e9bbe | ||
|
|
af1edb81ec | ||
|
|
8859dc0fc7 |
7 changed files with 68 additions and 145 deletions
|
|
@ -1,3 +0,0 @@
|
||||||
[autorebuild]
|
|
||||||
enabled = true
|
|
||||||
|
|
||||||
22
Dockerfile
22
Dockerfile
|
|
@ -1,8 +1,8 @@
|
||||||
FROM registry.fedoraproject.org/fedora:36
|
FROM registry.fedoraproject.org/fedora:36
|
||||||
|
|
||||||
ENV NAME=fedora-toolbox VERSION=36
|
ARG NAME=fedora-toolbox
|
||||||
|
ARG VERSION=36
|
||||||
LABEL com.github.containers.toolbox="true" \
|
LABEL com.github.containers.toolbox="true" \
|
||||||
com.github.debarshiray.toolbox="true" \
|
|
||||||
com.redhat.component="$NAME" \
|
com.redhat.component="$NAME" \
|
||||||
name="$NAME" \
|
name="$NAME" \
|
||||||
version="$VERSION" \
|
version="$VERSION" \
|
||||||
|
|
@ -12,8 +12,12 @@ LABEL com.github.containers.toolbox="true" \
|
||||||
|
|
||||||
COPY README.md /
|
COPY README.md /
|
||||||
|
|
||||||
|
RUN rm /etc/rpm/macros.image-language-conf
|
||||||
RUN sed -i '/tsflags=nodocs/d' /etc/dnf/dnf.conf
|
RUN sed -i '/tsflags=nodocs/d' /etc/dnf/dnf.conf
|
||||||
|
|
||||||
|
RUN dnf -y upgrade
|
||||||
RUN dnf -y swap coreutils-single coreutils-full
|
RUN dnf -y swap coreutils-single coreutils-full
|
||||||
|
RUN dnf -y swap glibc-minimal-langpack glibc-all-langpacks
|
||||||
|
|
||||||
COPY missing-docs /
|
COPY missing-docs /
|
||||||
RUN dnf -y reinstall $(<missing-docs)
|
RUN dnf -y reinstall $(<missing-docs)
|
||||||
|
|
@ -23,4 +27,18 @@ COPY extra-packages /
|
||||||
RUN dnf -y install $(<extra-packages)
|
RUN dnf -y install $(<extra-packages)
|
||||||
RUN rm /extra-packages
|
RUN rm /extra-packages
|
||||||
|
|
||||||
|
COPY ensure-files /
|
||||||
|
RUN ret_val=0; \
|
||||||
|
while read file; do \
|
||||||
|
if ! compgen -G "$file" >/dev/null; then \
|
||||||
|
echo "$file: No such file or directory" >&2; \
|
||||||
|
ret_val=1; \
|
||||||
|
break; \
|
||||||
|
fi; \
|
||||||
|
done <ensure-files; \
|
||||||
|
if [ "$ret_val" -ne 0 ]; then \
|
||||||
|
false; \
|
||||||
|
fi
|
||||||
|
RUN rm /ensure-files
|
||||||
|
|
||||||
RUN dnf clean all
|
RUN dnf clean all
|
||||||
|
|
|
||||||
162
README.md
162
README.md
|
|
@ -1,7 +1,13 @@
|
||||||
[Toolbox](https://github.com/containers/toolbox) is a tool for Linux operating
|
[Toolbox](https://containertoolbx.org/) is a tool for Linux, which allows the
|
||||||
systems, which allows the use of containerized command line environments. It is
|
use of interactive command line environments for development and
|
||||||
built on top of [Podman](https://podman.io/) and other standard container
|
troubleshooting the host operating system, without having to install software
|
||||||
technologies from [OCI](https://opencontainers.org/).
|
on the host. It is built on top of [Podman](https://podman.io/) and other
|
||||||
|
standard container technologies from [OCI](https://opencontainers.org/).
|
||||||
|
|
||||||
|
Toolbox environments have seamless access to the user's home directory,
|
||||||
|
the Wayland and X11 sockets, networking (including Avahi), removable devices
|
||||||
|
(like USB sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the
|
||||||
|
udev database, etc..
|
||||||
|
|
||||||
This is particularly useful on
|
This is particularly useful on
|
||||||
[OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like
|
[OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like
|
||||||
|
|
@ -10,12 +16,12 @@ This is particularly useful on
|
||||||
systems is to discourage installation of software on the host, and instead
|
systems is to discourage installation of software on the host, and instead
|
||||||
install software as (or in) containers — they mostly don't even have package
|
install software as (or in) containers — they mostly don't even have package
|
||||||
managers like DNF or YUM. This makes it difficult to set up a development
|
managers like DNF or YUM. This makes it difficult to set up a development
|
||||||
environment or install tools for debugging in the usual way.
|
environment or troubleshoot the operating system in the usual way.
|
||||||
|
|
||||||
Toolbox solves this problem by providing a fully mutable container within
|
Toolbox solves this problem by providing a fully mutable container within
|
||||||
which one can install their favourite development and debugging tools, editors
|
which one can install their favourite development and troubleshooting tools,
|
||||||
and SDKs. For example, it's possible to do `yum install ansible` without
|
editors and SDKs. For example, it's possible to do `yum install ansible`
|
||||||
affecting the base operating system.
|
without affecting the base operating system.
|
||||||
|
|
||||||
However, this tool doesn't *require* using an OSTree based system. It works
|
However, this tool doesn't *require* using an OSTree based system. It works
|
||||||
equally well on Fedora Workstation and Server, and that's a useful way to
|
equally well on Fedora Workstation and Server, and that's a useful way to
|
||||||
|
|
@ -23,136 +29,16 @@ incrementally adopt containerization.
|
||||||
|
|
||||||
The toolbox environment is based on an [OCI](https://www.opencontainers.org/)
|
The toolbox environment is based on an [OCI](https://www.opencontainers.org/)
|
||||||
image. On Fedora this is the `fedora-toolbox` image. This image is used to
|
image. On Fedora this is the `fedora-toolbox` image. This image is used to
|
||||||
create a toolbox container that seamlessly integrates with the rest of the
|
create a toolbox container that offers the interactive command line
|
||||||
operating system by providing access to the user's home directory, the Wayland
|
environment.
|
||||||
and X11 sockets, networking (including Avahi), removable devices (like USB
|
|
||||||
sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev
|
Note that Toolbox makes no promise about security beyond what's already
|
||||||
database, etc..
|
available in the usual command line environment on the host that everybody is
|
||||||
|
familiar with.
|
||||||
|
|
||||||
|
|
||||||
## Installation
|
## Installation & Use
|
||||||
|
|
||||||
Toolbox is installed by default on Fedora Silverblue. On other operating
|
See our guides on
|
||||||
systems it's just a matter of installing the `toolbox` package.
|
[installing & getting started](https://containertoolbx.org/install/) with
|
||||||
|
Toolbox and [Linux distro support](https://containertoolbx.org/distros/).
|
||||||
## Usage
|
|
||||||
|
|
||||||
### Create your toolbox container:
|
|
||||||
```console
|
|
||||||
[user@hostname ~]$ toolbox create
|
|
||||||
Created container: fedora-toolbox-33
|
|
||||||
Enter with: toolbox enter
|
|
||||||
[user@hostname ~]$
|
|
||||||
```
|
|
||||||
This will create a container called `fedora-toolbox-<version-id>`.
|
|
||||||
|
|
||||||
### Enter the toolbox:
|
|
||||||
```console
|
|
||||||
[user@hostname ~]$ toolbox enter
|
|
||||||
⬢[user@toolbox ~]$
|
|
||||||
```
|
|
||||||
|
|
||||||
### Remove a toolbox container:
|
|
||||||
```console
|
|
||||||
[user@hostname ~]$ toolbox rm fedora-toolbox-33
|
|
||||||
[user@hostname ~]$
|
|
||||||
```
|
|
||||||
|
|
||||||
## Dependencies and Building
|
|
||||||
|
|
||||||
Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build
|
|
||||||
system.
|
|
||||||
|
|
||||||
The following dependencies are required to build it:
|
|
||||||
- meson
|
|
||||||
- go-md2man
|
|
||||||
- systemd
|
|
||||||
- go
|
|
||||||
- ninja
|
|
||||||
|
|
||||||
The following dependencies enable various optional features:
|
|
||||||
- bash-completion
|
|
||||||
|
|
||||||
It can be built and installed as any other typical Meson-based project:
|
|
||||||
```console
|
|
||||||
[user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir
|
|
||||||
[user@hostname toolbox]$ ninja -C builddir
|
|
||||||
[user@hostname toolbox]$ sudo ninja -C builddir install
|
|
||||||
```
|
|
||||||
|
|
||||||
Toolbox is written in Go. Consult the
|
|
||||||
[src/go.mod](https://github.com/containers/toolbox/blob/main/src/go.mod) file
|
|
||||||
for a full list of all the Go dependencies.
|
|
||||||
|
|
||||||
By default, Toolbox uses Go modules and all the required Go packages are
|
|
||||||
automatically downloaded as part of the build. There's no need to worry about
|
|
||||||
the Go dependencies, unless the build environment doesn't have network access
|
|
||||||
or any such peculiarities.
|
|
||||||
|
|
||||||
## Distro support
|
|
||||||
|
|
||||||
By default, Toolbox creates the container using an
|
|
||||||
[OCI](https://www.opencontainers.org/) image called
|
|
||||||
`<ID>-toolbox:<VERSION-ID>`, where `<ID>` and `<VERSION-ID>` are taken from the
|
|
||||||
host's `/usr/lib/os-release`. For example, the default image on a Fedora 33
|
|
||||||
host would be `fedora-toolbox:33`.
|
|
||||||
|
|
||||||
This default can be overridden by the `--image` option in `toolbox create`,
|
|
||||||
but operating system distributors should provide an adequately configured
|
|
||||||
default image to ensure a smooth user experience.
|
|
||||||
|
|
||||||
## Image requirements
|
|
||||||
|
|
||||||
Toolbox customizes newly created containers in a certain way. This requires
|
|
||||||
certain tools and paths to be present and have certain characteristics inside
|
|
||||||
the OCI image.
|
|
||||||
|
|
||||||
Tools:
|
|
||||||
* `getent(1)`
|
|
||||||
* `id(1)`
|
|
||||||
* `ln(1)`
|
|
||||||
* `mkdir(1)`: for hosts where `/home` is a symbolic link to `/var/home`
|
|
||||||
* `passwd(1)`
|
|
||||||
* `readlink(1)`
|
|
||||||
* `rm(1)`
|
|
||||||
* `rmdir(1)`: for hosts where `/home` is a symbolic link to `/var/home`
|
|
||||||
* `sleep(1)`
|
|
||||||
* `test(1)`
|
|
||||||
* `touch(1)`
|
|
||||||
* `unlink(1)`
|
|
||||||
* `useradd(8)`
|
|
||||||
* `usermod(8)`
|
|
||||||
|
|
||||||
Paths:
|
|
||||||
* `/etc/host.conf`: optional, if present not a bind mount
|
|
||||||
* `/etc/hosts`: optional, if present not a bind mount
|
|
||||||
* `/etc/krb5.conf.d`: directory, not a bind mount
|
|
||||||
* `/etc/localtime`: optional, if present not a bind mount
|
|
||||||
* `/etc/machine-id`: optional, not a bind mount
|
|
||||||
* `/etc/resolv.conf`: optional, if present not a bind mount
|
|
||||||
* `/etc/timezone`: optional, if present not a bind mount
|
|
||||||
|
|
||||||
Toolbox enables `sudo(8)` access inside containers. The following is necessary
|
|
||||||
for that to work:
|
|
||||||
|
|
||||||
* The image should have `sudo(8)` enabled for users belonging to either the
|
|
||||||
`sudo` or `wheel` groups, and the group itself should exist. File an
|
|
||||||
[issue](https://github.com/containers/toolbox/issues/new) if you really need
|
|
||||||
support for a different group. However, it's preferable to keep this list as
|
|
||||||
short as possible.
|
|
||||||
|
|
||||||
* The image should allow empty passwords for `sudo(8)`. This can be achieved
|
|
||||||
by either adding the `nullok` option to the `PAM(8)` configuration, or by
|
|
||||||
add the `NOPASSWD` tag to the `sudoers(5)` configuration.
|
|
||||||
|
|
||||||
Since Toolbox only works with OCI images that fulfill certain requirements,
|
|
||||||
it will refuse images that aren't tagged with
|
|
||||||
`com.github.containers.toolbox="true"` and
|
|
||||||
`com.github.debarshiray.toolbox="true"` labels. These labels are meant to be
|
|
||||||
used by the maintainer of the image to indicate that they have read this
|
|
||||||
document and tested that the image works with Toolbox. You can use the
|
|
||||||
following snippet in a Dockerfile for this:
|
|
||||||
```Dockerfile
|
|
||||||
LABEL com.github.containers.toolbox="true" \
|
|
||||||
com.github.debarshiray.toolbox="true"
|
|
||||||
```
|
|
||||||
|
|
|
||||||
|
|
@ -1,2 +0,0 @@
|
||||||
autorebuild:
|
|
||||||
from_latest: true
|
|
||||||
17
ensure-files
Normal file
17
ensure-files
Normal file
|
|
@ -0,0 +1,17 @@
|
||||||
|
/usr/share/man/man1/bash.1*
|
||||||
|
/usr/share/man/man1/cd.1*
|
||||||
|
/usr/share/man/man1/export.1*
|
||||||
|
|
||||||
|
/usr/share/man/man1/cat.1*
|
||||||
|
/usr/share/man/man1/cp.1*
|
||||||
|
/usr/share/man/man1/ls.1*
|
||||||
|
|
||||||
|
/usr/share/man/man1/gpg2.1*
|
||||||
|
/usr/share/man/man7/gnupg2.7*
|
||||||
|
|
||||||
|
/usr/share/man/fr/man8/rpm.8*
|
||||||
|
/usr/share/man/ja/man8/rpm.8*
|
||||||
|
/usr/share/man/man8/rpm.8*
|
||||||
|
|
||||||
|
/usr/share/man/man1/kill.1*
|
||||||
|
/usr/share/man/man8/mount.8*
|
||||||
|
|
@ -7,7 +7,7 @@ findutils
|
||||||
flatpak-spawn
|
flatpak-spawn
|
||||||
fpaste
|
fpaste
|
||||||
git
|
git
|
||||||
gnupg
|
gnupg2
|
||||||
gnupg2-smime
|
gnupg2-smime
|
||||||
gvfs-client
|
gvfs-client
|
||||||
hostname
|
hostname
|
||||||
|
|
@ -20,6 +20,8 @@ less
|
||||||
lsof
|
lsof
|
||||||
man-db
|
man-db
|
||||||
man-pages
|
man-pages
|
||||||
|
mesa-dri-drivers
|
||||||
|
mesa-vulkan-drivers
|
||||||
mtr
|
mtr
|
||||||
nano-default-editor
|
nano-default-editor
|
||||||
nss-mdns
|
nss-mdns
|
||||||
|
|
@ -37,6 +39,7 @@ tree
|
||||||
unzip
|
unzip
|
||||||
util-linux
|
util-linux
|
||||||
vte-profile
|
vte-profile
|
||||||
|
vulkan-loader
|
||||||
wget
|
wget
|
||||||
which
|
which
|
||||||
words
|
words
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,9 @@ acl
|
||||||
bash
|
bash
|
||||||
coreutils-common
|
coreutils-common
|
||||||
curl
|
curl
|
||||||
|
findutils
|
||||||
gawk
|
gawk
|
||||||
|
gnupg2
|
||||||
grep
|
grep
|
||||||
gzip
|
gzip
|
||||||
libcap
|
libcap
|
||||||
|
|
@ -12,5 +14,7 @@ pam
|
||||||
python3
|
python3
|
||||||
rpm
|
rpm
|
||||||
sed
|
sed
|
||||||
|
sudo
|
||||||
systemd
|
systemd
|
||||||
tar
|
tar
|
||||||
|
util-linux-core
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue