doc: Document the configuration file

containers#963

doc/meson.build

@@ -16,6 +16,9 @@ manuals = {
     'toolbox-rmi',
     'toolbox-run',
   ],
+  '5': [
+    'toolbox.conf',
+  ]
 }
 
 foreach section, pages: manuals

doc/toolbox.1.md

@@ -102,6 +102,12 @@ Remove one or more toolbox images.
 
 Run a command in an existing toolbox container.
 
+## FILES ##
+
+**toolbox.conf(5)**
+
+Toolbox configuration file.
+
 ## SEE ALSO
 
 `podman(1)`, https://github.com/containers/toolbox

doc/toolbox.conf.5.md

@@ -0,0 +1,67 @@
+% toolbox.conf(5)
+
+## NAME
+toolbox.conf - Toolbox configuration file
+
+## DESCRIPTION
+
+Persistently overrides the default behaviour of `toolbox(1)`. The sytax is TOML
+and the names of the options match their command line counterparts. Currently,
+the only supported section is *general*.
+
+## OPTIONS
+
+**distro** = "DISTRO"
+
+Create a toolbox container for a different operating system DISTRO than the
+host. Cannot be used with `image`.
+
+**image** = "NAME"
+
+Change the NAME of the image used to create the toolbox container. This is
+useful for creating containers from custom-built images. Cannot be used with
+`distro` and `release`.
+
+If NAME does not contain a registry, the local image storage will be
+consulted, and if it's not present there then it will be pulled from a suitable
+remote registry.
+
+**release** = "RELEASE"
+
+Create a toolbox container for a different operating system RELEASE than the
+host. Cannot be used with `image`.
+
+## FILES
+
+The following locations are looked up in increasing order of priority:
+
+**/etc/containers/toolbox.conf**
+
+This is meant to be provided by the operating system distributor or the system
+administrator, and affects all users on the host.
+
+Fields specified here can be overridden by any of the files below.
+
+**$XDG_CONFIG_HOME/containers/toolbox.conf**
+
+This is meant for user-specific changes. Fields specified here override any of
+the files above.
+
+## EXAMPLES
+
+### Override the default operating system distro:
+```
+[general]
+distro = "fedora"
+release = "36"
+```
+
+### Override the default image:
+```
+[general]
+image = "registry.fedoraproject.org/fedora-toolbox:36"
+```
+
+## SEE ALSO
+
+`toolbox(1)`, `toolbox-create(1)`