diff --git a/Dockerfile b/Dockerfile index 7209890..f7c57bd 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,8 +1,8 @@ FROM registry.fedoraproject.org/fedora:37 -ENV NAME=fedora-toolbox VERSION=37 +ARG NAME=fedora-toolbox +ARG VERSION=37 LABEL com.github.containers.toolbox="true" \ - com.github.debarshiray.toolbox="true" \ com.redhat.component="$NAME" \ name="$NAME" \ version="$VERSION" \ @@ -12,8 +12,12 @@ LABEL com.github.containers.toolbox="true" \ COPY README.md / +RUN rm /etc/rpm/macros.image-language-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 glibc-minimal-langpack glibc-all-langpacks COPY missing-docs / RUN dnf -y reinstall $(/dev/null; then \ + echo "$file: No such file or directory" >&2; \ + ret_val=1; \ + break; \ + fi; \ + done &2; \ + echo "$broken_packages" >&2; \ + false; \ + fi + RUN dnf clean all diff --git a/README.md b/README.md index 117528e..6f9943b 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,13 @@ -[Toolbox](https://github.com/containers/toolbox) is a tool for Linux operating -systems, which allows the use of containerized command line environments. It is -built on top of [Podman](https://podman.io/) and other standard container -technologies from [OCI](https://opencontainers.org/). +[Toolbox](https://containertoolbx.org/) is a tool for Linux, which allows the +use of interactive command line environments for development and +troubleshooting the host operating system, without having to install software +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 [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 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 -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 -which one can install their favourite development and debugging tools, editors -and SDKs. For example, it's possible to do `yum install ansible` without -affecting the base operating system. +which one can install their favourite development and troubleshooting tools, +editors and SDKs. For example, it's possible to do `yum install ansible` +without affecting the base operating system. 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 @@ -23,136 +29,16 @@ incrementally adopt containerization. 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 -create a toolbox container that seamlessly integrates with the rest of the -operating system by providing 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.. +create a toolbox container that offers the interactive command line +environment. + +Note that Toolbox makes no promise about security beyond what's already +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 -systems it's just a matter of installing the `toolbox` package. - -## 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-`. - -### 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 -`-toolbox:`, where `` and `` 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" -``` +See our guides on +[installing & getting started](https://containertoolbx.org/install/) with +Toolbox and [Linux distro support](https://containertoolbx.org/distros/). diff --git a/ensure-files b/ensure-files new file mode 100644 index 0000000..b9227a9 --- /dev/null +++ b/ensure-files @@ -0,0 +1,46 @@ +/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/man8/dnf.8* +/usr/share/man/man5/dnf.conf.5* + +/usr/share/locale/de/LC_MESSAGES/elfutils.mo +/usr/share/locale/ja/LC_MESSAGES/elfutils.mo + +/usr/share/man/man1/gpg2.1* +/usr/share/man/man7/gnupg2.7* + +/usr/share/info/nettle.info* + +/usr/share/locale/fr/LC_MESSAGES/popt.mo +/usr/share/locale/ja/LC_MESSAGES/popt.mo + +/usr/share/man/fr/man1/pstree.1* +/usr/share/man/ru/man1/pstree.1* +/usr/share/man/man1/pstree.1* + +/usr/share/info/history.info* + +/usr/share/man/fr/man8/rpm.8* +/usr/share/man/ja/man8/rpm.8* +/usr/share/man/man8/rpm.8* + +/usr/share/man/fr/man8/useradd.8* +/usr/share/man/ja/man8/useradd.8* +/usr/share/man/man8/useradd.8* + +/usr/share/man/man1/cal.1.* +/usr/share/man/man1/getopt.1* +/usr/share/man/man1/hexdump.1* + +/usr/share/man/man1/kill.1* +/usr/share/man/man8/mount.8* + +/usr/share/man/fr/man1/xz.1* +/usr/share/man/ko/man1/xz.1* +/usr/share/man/man1/xz.1* diff --git a/extra-packages b/extra-packages index 52bf3f3..f07bf58 100644 --- a/extra-packages +++ b/extra-packages @@ -7,19 +7,20 @@ findutils flatpak-spawn fpaste git -gnupg +gnupg2 gnupg2-smime gvfs-client hostname iproute iputils -jwhois keyutils krb5-libs less lsof man-db man-pages +mesa-dri-drivers +mesa-vulkan-drivers mtr nano-default-editor nss-mdns @@ -27,6 +28,7 @@ openssh-clients passwd pigz procps-ng +psmisc rsync shadow-utils sudo @@ -37,8 +39,10 @@ tree unzip util-linux vte-profile +vulkan-loader wget which +whois words xorg-x11-xauth xz diff --git a/missing-docs b/missing-docs index cb44892..f7b041b 100644 --- a/missing-docs +++ b/missing-docs @@ -1,17 +1,91 @@ acl +alternatives +audit-libs +authselect +authselect-libs bash +ca-certificates coreutils-common +cracklib +crypto-policies curl +cyrus-sasl-lib +dnf +dnf-data +elfutils-libelf +expat +file-libs +filesystem findutils gawk +glib2 +gmp +gnupg2 +gnutls +gpgme grep gzip +ima-evm-utils +keyutils-libs +krb5-libs +libarchive +libassuan +libblkid libcap +libcap-ng +libdb +libdnf +libeconf +libevent +libffi +libgcrypt +libgomp +libgpg-error +libidn2 +libksba +libmodulemd +libpwquality +librepo +libsemanage +libsigsegv +libsolv +libssh +libtasn1 +libtirpc +libunistring +libverto +libxcrypt +libxml2 +libyaml +lz4-libs +mpfr +ncurses-base +nettle +openldap openssl p11-kit pam +pcre +pcre2-syntax +popt python3 +python3-gpg +python3-libs +python3-rpm +readline rpm sed +setup +shadow-utils +sqlite-libs +sudo systemd +systemd-libs tar +tpm2-tss +tzdata +util-linux-core +vim-minimal +yum +zchunk-libs +zlib