From 0298134f27436689395705416ab9ca6c758645ea Mon Sep 17 00:00:00 2001 From: Giuseppe Scrivano Date: Fri, 15 Jul 2016 13:38:46 +0200 Subject: [PATCH 1/3] docs: improve the documentation for "atomic pull" Signed-off-by: Giuseppe Scrivano --- docs/atomic-pull.1.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/atomic-pull.1.md b/docs/atomic-pull.1.md index 35ea304e..2b292c5a 100644 --- a/docs/atomic-pull.1.md +++ b/docs/atomic-pull.1.md @@ -15,12 +15,41 @@ IMAGE Use the `--ostree` option to store it into the OSTree repository. +IMAGE has the form `SOURCE:IMAGE-NAME`, where `SOURCE` can be one of +'oci', 'docker', 'dockertar', 'ostree'. If no `SOURCE` is specified +then 'oci' is assumed. + +An 'oci' image is fetched via Skopeo from a Docker registry. These +two commands are equivalent: + +`atomic pull etcd` +`atomic pull oci:etcd` + +A 'docker' image is imported from the local Docker engine, thus not +accessing the network. It is equivalent to saving the image from +docker (`docker save IMAGE`) and importing it into the OSTree +repository: + +`atomic pull docker:fedora` + +A 'dockertar' image works in a similar way to 'docker' images, except +that the saved tarball is specified: + +`atomic pull dockertar:/path/to/the/image.tar` + +An 'ostree' image refers to an image which is fetched from a remote +OSTree repository. The remote has to be already configured in the +local OSTree repository: + +`atomic pull ostree:REMOTE/branch` + # OPTIONS: **-h** **--help** - Print usage statement +Print usage statement **--storage=[ostree]** - Define the destination storage for the pulled image. +Define the destination storage for the pulled image. # HISTORY -April 2016, Originally compiled by Giuseppe Scrivano (gscrivan at redhat dot com) +April 2016, Originally compiled by Giuseppe Scrivano (gscrivan at +redhat dot com) \ No newline at end of file From 1ec0d623444590db79990851db1e3900e7422dcc Mon Sep 17 00:00:00 2001 From: Giuseppe Scrivano Date: Fri, 15 Jul 2016 15:17:16 +0200 Subject: [PATCH 2/3] docs: add system containers info to "atomic install" and don't split long lines Signed-off-by: Giuseppe Scrivano --- docs/atomic-install.1.md | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/docs/atomic-install.1.md b/docs/atomic-install.1.md index f14ea4f4..c7332907 100644 --- a/docs/atomic-install.1.md +++ b/docs/atomic-install.1.md @@ -24,40 +24,58 @@ If the container image has a LABEL INSTALL instruction like the following: `atomic install` will set the following environment variables for use in the command: **NAME** - The name specified via the command. NAME will be replaced with IMAGE if it is not specified. +The name specified via the command. NAME will be replaced with IMAGE if it is not specified. **IMAGE** - The name and image specified via the command. +The name and image specified via the command. **OPT1, OPT2, OPT3** - Additional options which can be specified via the command. +Additional options which can be specified via the command. **SUDO_UID** - The `SUDO_UID` environment variable. This is useful with the docker `-u` option for user space tools. If the environment variable is not available, the value of `/proc/self/loginuid` is used. +The `SUDO_UID` environment variable. This is useful with the docker +`-u` option for user space tools. If the environment variable is +not available, the value of `/proc/self/loginuid` is used. **SUDO_GID** - The `SUDO_GID` environment variable. This is useful with the docker `-u` option for user space tools. If the environment variable is not available, the default GID of the value for `SUDO_UID` is used. If this value is not available, the value of `/proc/self/loginuid` is used. +The `SUDO_GID` environment variable. This is useful with the docker +`-u` option for user space tools. If the environment variable is +not available, the default GID of the value for `SUDO_UID` is used. +If this value is not available, the value of `/proc/self/loginuid` +is used. Any additional arguments will be appended to the command. # OPTIONS: **-h** **--help** - Print usage statement +Print usage statement **--display** - Display the image's install options and environment variables populated into the install command. +Display the image's install options and environment variables +populated into the install command. The install command will not execute if --display is specified. If --display is not specified the install command will execute. **-n** **--name**="" - Use this name for creating installed content for the container. -NAME will default to the IMAGENAME if it is not specified. + Use this name for creating installed content for the container. + NAME will default to the IMAGENAME if it is not specified. **--set=NAME=VALUE** - Set a value that is going to be used by a system container for its configuration and can be specified multiple times. It is used only by --system. OSTree is required for this feature to be available. +Set a value that is going to be used by a system container for its +configuration and can be specified multiple times. It is used only +by --system. OSTree is required for this feature to be available. **--system** - Install a system container. A system container is a container that is executed out of an systemd unit file early in boot, using runc. OSTree is required for this feature to be available. +Install a system container. A system container is a container that +is executed out of an systemd unit file early in boot, using runc. +OSTree is required for this feature to be available. The specified +**IMAGE** must be a system image already fetched. If it is not +already present, atomic will attempt to fetch it assuming it is an +`oci` image. For more information on how images are fetched, see +also **atomic-pull(1)** +Installing a system container consists of checking it the image by +default under /var/lib/containers/atomic/ and generating the +configuration files for runc and systemd. # HISTORY January 2015, Originally compiled by Daniel Walsh (dwalsh at redhat dot com) From 26263b48c2ac55ad7038f369aca0b2562ccb5ac5 Mon Sep 17 00:00:00 2001 From: Giuseppe Scrivano Date: Fri, 15 Jul 2016 15:17:49 +0200 Subject: [PATCH 3/3] docs: add system containers info to "atomic mount" Signed-off-by: Giuseppe Scrivano --- docs/atomic-mount.1.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/atomic-mount.1.md b/docs/atomic-mount.1.md index b7a207ba..7dcd7a5b 100644 --- a/docs/atomic-mount.1.md +++ b/docs/atomic-mount.1.md @@ -20,7 +20,9 @@ temporary image and spawning a temporary container from that image. If UUID or REPO refers to an image, then *atomic mount* will simply create a temporary container from the given image. All temporary artifacts are cleaned upon *atomic unmount*. Atomic mount is *only* supported on the devicemapper and -overlayfs docker storage backends. +overlayfs docker storage backends. If an image stored on an OSTree +repository is mounted, then a temporary checkout is done, which will +be deleted by atomic unmount. # OPTIONS **-o|--options** *OPTIONS*