Make locate(1) opt-in by default

Currently, the entry point of a Toolbox container runs updatedb(8) on
start-up, which can be very I/O intensive. This might be a hindrance
when troubleshooting performance problems on a host, or when
re-creating containers somewhat more frequently.

Users can install the mlocate RPM and restart their containers to
enable locate(1).

https://github.com/containers/toolbox/pull/938

Dockerfile

@@ -13,6 +13,7 @@ LABEL com.github.containers.toolbox="true" \
 COPY README.md /
 
 RUN sed -i '/tsflags=nodocs/d' /etc/dnf/dnf.conf
+RUN dnf -y swap coreutils-single coreutils-full
 
 COPY missing-docs /
 RUN dnf -y reinstall $(<missing-docs)
@@ -23,5 +24,3 @@ RUN dnf -y install $(<extra-packages)
 RUN rm /extra-packages
 
 RUN dnf clean all
-
-CMD /bin/sh

README.md

@@ -1,41 +1,158 @@
-# Toolbox — Unprivileged development environment
-
-[Toolbox](https://github.com/debarshiray/toolbox) is a tool that offers a
-familiar RPM based environment for developing and debugging software that runs
-fully unprivileged using [Podman](https://podman.io/).
-
-The toolbox container is a fully *mutable* container; when you see
-`yum install ansible` for example, that's something you can do inside your
-toolbox container, without affecting the base operating system.
+[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/).
 
 This is particularly useful on
-[OSTree](https://ostree.readthedocs.io/en/latest/) based Fedora systems like
-[Silverblue](https://silverblue.fedoraproject.org/).  The intention of these
+[OSTree](https://ostree.readthedocs.io/en/latest/) based operating systems like
+[Fedora CoreOS](https://coreos.fedoraproject.org/) and
+[Silverblue](https://silverblue.fedoraproject.org/). The intention of these
 systems is to discourage installation of software on the host, and instead
-install software as (or in) containers.
+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.
 
-However, this tool doesn't *require* using an OSTree based system — it
-works equally well if you're running e.g. existing Fedora Workstation or
-Server, and that's a useful way to incrementally adopt containerization.
+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.
+
+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
+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 then
-customized for the current user to create a toolbox container that seamlessly
-integrates with the rest of the operating system.
+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..
+
+
+## Installation
+
+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, and an image, called
-`fedora-toolbox-<your-username>:<version-id>` that's specifically customised
-for your host user.
+This will create a container called `fedora-toolbox-<version-id>`.
 
 ### Enter the toolbox:
-```
+```console
 [user@hostname ~]$ toolbox enter
-🔹[user@toolbox ~]$
+⬢[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"
 ```

extra-packages

@@ -1,4 +1,5 @@
 bash-completion
+bc
 bzip2
 diffutils
 dnf-plugins-core
@@ -10,6 +11,7 @@ gnupg
 gnupg2-smime
 gvfs-client
 hostname
+iproute
 iputils
 jwhois
 keyutils
@@ -18,8 +20,8 @@ less
 lsof
 man-db
 man-pages
-mlocate
 mtr
+nano-default-editor
 nss-mdns
 openssh-clients
 passwd
@@ -33,6 +35,7 @@ time
 traceroute
 tree
 unzip
+util-linux
 vte-profile
 wget
 which