docs: document system container variables and files

This might not be the best place to add this information, but it is a
starting point to get it documented.

Signed-off-by: Giuseppe Scrivano <[email protected]>

Closes: #1121
Approved by: baude

docs/atomic-install.1.md

@@ -102,6 +102,95 @@ Note: If the image being pulled contains a label of `system.type=ostree`,
 atomic will automatically substitute the storage backend to be ostree. This
 can be overridden with the --storage option.
 
+The system container template files support substition of variables.
+
+These files in the image are managed as metadata for system
+containers:
+
+**/exports/config.json.template** The OCI configuration for running
+the container.  The generated file is ultimately used by the OCI
+runtime for setting up the container.
+
+**/exports/manifest.json** Various settings for the container.
+
+**/exports/service.template** Template for the systemd unit file.
+
+**/exports/tmpfiles.template** Template for systemd-tmpfiles, if the
+container needs temporary files on the system.
+
+In **/exports/manifest.json** it is possible to setup these settings:
+
+**defaultValues** A dictionary which containers the default values
+given to variables used by the template files.  The user can override
+these values with **-set=VARIABLE=NEWVALUE**.
+
+**installedFilesTemplate** List of files that must be preprocessed
+before being copied to the host.
+
+**noContainerService** Set to True if the container is used only for
+copying files to the host but has not a systemd service.
+
+**renameFiles** Define the destination name of the files on the host.
+Variable sobstitution is supported so that it is possible to use
+variables to compose the final destination path.
+
+Every file under **/exports/hostfs** is copied to the host when the
+container is installed, and removed once the container is
+uninstalled.
+For instance, a file **/exports/hostfs/usr/local/bin/foo** in the
+image is copied to the host as **/usr/local/bin/foo**.
+The directives **installedFilesTemplate** and **renameFiles** from the
+**manifest.json** file can be used to modify the content and the final
+destination of the file.
+
+This is the list of the variables that get a value from atomic and
+cannot be overriden by the user through **--set**:
+
+**$DESTDIR** Destination on the file system for the checked out
+container.
+
+**$EXEC_STARTPRE** Command to use for the systemd directive ExecStartPre=.
+
+**$EXEC_START** Command to use for the systemd directive ExecStart=.
+
+**$EXEC_STOP** Command to use for the systemd directive ExecStop=.
+
+**$EXEC_STOPPOST** Command to use for the systemd directive ExecStopPost=.
+
+**$HOST_UID** UID of the user on the system.
+
+**$HOST_GID** GID of the user on the system.
+
+**$IMAGE_ID** ID of the image being installed.
+
+**$IMAGE_NAME** Name of the image being installed.
+
+**$NAME** Name of the container.
+
+Some other variables get a value but it is possible to override it
+through **--set**:
+
+**$ALL_PROCESS_CAPABILITIES** A list of all the kernel process
+capabilities available on the system, in the format expected in the
+OCI configuration file.
+Privileged containers that keep all capabilities should use this
+variable instead of hardcoding the list.  This simplifies the
+configuration file as well as improve images portability as the same
+image can be used on systems with a different set of capabilities.
+
+**$CONFIG_DIRECTORY** Directory where to store configuration files
+(/etc on the host, ~/.config/ for user containers).
+
+**$PIDFILE** File where to store the PID of the container main
+process.
+
+**$RUN_DIRECTORY** Directory where to store runtime files. (/run on
+the host, $XDG_RUNTIME_DIR for user containers).
+
+**$STATE_DIRECTORY** Directory where to store the state of the container.
+
+**$UUID** UUID generated for this container.
+
 **--system-package=auto|build|no|yes**
 Control how the container will be installed to the system.
 
@@ -118,7 +207,10 @@ image defines a .spec file.  This is the default.
 If running as non-root, specify to install the image from the current
 OSTree repository and manage it through systemd and bubblewrap.
 OSTree and bwrap-oci are required for this feature to be available.
+The same image format as for **--system** is supported.  Please refer
+to **--system** for more information.
 
 # HISTORY
 January 2015, Originally compiled by Daniel Walsh (dwalsh at redhat dot com)
 July 2015, edited by Sally O'Malley (somalley at redhat dot com)
+October 2017, edited by Giuseppe Scrivano (gscrivan at redhat dot com)