Skip to content

help.adoc

Latest commit

 

History

History
288 lines (192 loc) · 10.9 KB

help.adoc

File metadata and controls

288 lines (192 loc) · 10.9 KB

You can provide a man-like help file with your images that allows for users to have a deeper understanding of your image. This function now allows you to provide a:

  • more verbose description of the what the image is and does

  • understanding of how the image should be run

  • description of the security implications inherent in running the image

  • requirement if the image needs to be installed

You can use the atomic application to display this help file trivially like so:

# atomic help <image or container name>

Location

For the atomic tool to be able to parse your help file, it must be located in the image as /help.1 and in the 'man' format.

Required headings

The following headings are strongly encouraged in the help file for an image.

NAME

Image name with short description.

DESCRIPTION

Describe in greater detail the role or purpose of the image (application, service, base image, builder image, etc.).

USAGE

Describe how to run the image as a container and what factors might influence the behavior of the image itself. Provide specific command lines that are appropriate for how the container should be run.

ENVIRONMENT VARIABLES

Explain all environment variables available to run the image in different ways without the need of rebuilding the image.

HISTORY

Similar to a Changelog of sorts which can be as detailed as the maintainer desires.

Optional Headings

Use the following sections in your help file when applicable.

LABELS

Describe LABEL settings (from the Dockerfile that created the image) that contain pertinent information. For containers run by atomic, that could include INSTALL, RUN, UNINSTALL, and UPDATE LABELS. For more information see Container Application Generic Labels.

SECURITY IMPLICATIONS

If your image uses any privileges that you want to make the user aware of, be sure to document which ones are used and optionally why.

Sample Template

We recommend writing the help file in the markdown language and then converting it to the man format. This is handy because github can natively display markdown, so the help file can be used in multiple ways. For a template, see the example help file below and the template markdown file that can also be obtained at here.

Sample help template in markdown format
% IMAGE_NAME (1) Container Image Pages
% MAINTAINER
% DATE

# NAME
Image_name - short description

# DESCRIPTION
Describe how image is used (user app, service, base image, builder image, etc.), the services or features it provides, and environment it is intended to run in (stand-alone docker, atomic super-privileged, oc multi-container app, etc.).

# USAGE
Describe how to run the image as a container and what factors might influence the behavior of the image itself. Provide specific command lines that are appropriate for how the container should be run. Here is an example for a container image meant to be run by the atomic command:

To pull the container and set up the host system for use by the XYZ container, run:

    # atomic install XYZimage

To run the XYZ container (after it is installed), run:

    # atomic run XYZimage

To remove the XYZ container (not the image) from your system, run:

    # atomic uninstall XYZimage

Also, describe the default configuration options (when defined): default user, exposed ports, volumes, working directory, default command, etc.

# ENVIRONMENT VARIABLES
Explain all the environment variables available to run the image in different ways without the need of rebuilding the image. Change variables on the docker command line with -e option. For example:

MYSQL_PASSWORD=mypass
                The password set for the current MySQL user.

# LABELS
Describe LABEL settings (from the Dockerfile that created the image) that contains pertinent information.
For containers run by atomic, that could include INSTALL, RUN, UNINSTALL, and UPDATE LABELS.


# SECURITY IMPLICATIONS
If you expose ports or run with privileges, note those and provide an explanation. For example:

Root privileges
    Container is running as root. Explain why is it necessary.

-p 3306:3306
    Opens container port 3306 and maps it to the same port on the Host.

--net=host --cap_add=net_admin
     Network devices of the host are visible inside the container and can be configured.

# HISTORY
Similar to a Changelog of sorts which can be as detailed as the maintainer wishes.

# SEE ALSO
References to documentation or other sources. For example:

Does Red Hat provide MariaDB technical support on RHEL 7? https://access.redhat.com/solutions/1247193
Install and Deploy a Mariadb Container Image https://access.redhat.com/documentation/en/red-hat-enterprise-linux-atomic-host/7/single/getting-started-guide/#install_and_deploy_a_mariadb_container

Example Help File for the rsyslog Container

% RSYSLOG (1) Container Image Pages
% Stephen Tweedie
% January 27, 2016

# NAME
rsyslog \- rsyslog container image

# DESCRIPTION
The rsyslog image provides a containerized packaging of the rsyslogd daemon. The rsyslogd daemon is a
utility that supports system message logging. With the rsyslog container installed and running, you
can configure the rsyslogd service directly on the host computer as you would if the daemon were
not containerized.

You can find more information on the rsyslog project from the project Web site (http://www.rsyslog.com/doc).

The rsyslog image is designed to be run by the atomic command with one of these options:

`install`

Sets up the container to access directories and files from the host system to use for rsyslogd configuration,
logging, log rotation, and credentials.

`run`

Starts the installed container with selected privileges to the host and with logging-related files and
directories bind mounted inside the container. If the container stops, it is set to always restart.

`uninstall`

Removes the container from the system. This removes the syslog logrotate file, leave all other files
and directories associated with rsyslogd on the host system.

Because privileges are opened to the host system, the running rsyslog container can gather log messages
from the host and save them to the filesystem on the host.

The container itself consists of:
    - rhel7/rhel base image
    - rsyslog RPM package

Files added to the container during docker build include: /bin/install.sh, /bin/rsyslog.sh, and /bin/uninstall.sh.

# USAGE
To use the rsyslog container, you can run the atomic command with install, run, or uninstall options:

To set up the host system for use by the rsyslog container, run:

  atomic install rhel7/rsyslog

To run the rsyslog container (after it is installed), run:

  atomic run rhel7/rsyslog

To remove the rsyslog container (not the image) from your system, run:

  atomic uninstall rhel7/rsyslog

# LABELS
The rsyslog container includes the following LABEL settings:

That atomic command runs the docker command set in this label:

`INSTALL=`

  LABEL INSTALL="docker run --rm --privileged -v /:/host \
  -e HOST=/host -e IMAGE=IMAGE -e NAME=NAME \
  IMAGE /bin/install.sh"

  The contents of the INSTALL label tells an `atomic install rhel7/rsyslog` command to remove the container
  after it exits (--rm), run with root privileges open to the host, mount the root directory (/) from the hos on
  the /host directory within the container, set the location of the host file system to /host, set the name of
  the image and run the install.sh script.

`RUN=`

  LABEL RUN="docker run -d --privileged --name NAME \
  --net=host --pid=host \
  -v /etc/pki/rsyslog:/etc/pki/rsyslog \
  -v /etc/rsyslog.conf:/etc/rsyslog.conf \
  -v /etc/sysconfig/rsyslog:/etc/sysconfig/rsyslog \
  -v /etc/rsyslog.d:/etc/rsyslog.d \
  -v /var/log:/var/log \
  -v /var/lib/rsyslog:/var/lib/rsyslog \
  -v /run:/run \
  -v /etc/machine-id:/etc/machine-id:ro \
  -v /etc/localtime:/etc/localtime:ro \
  -e IMAGE=IMAGE -e NAME=NAME \
  --restart=always IMAGE /bin/rsyslog.sh"

  The contents of the RUN label tells an `atomic run rhel7/rsyslog` command to open various privileges to the host
  (described later), mount a variety of host files and directories into the container, set the name of the container,
  set the container to restart automatically if it stops, and run the rsyslog.sh script.

`UNINSTALL=`

  LABEL UNINSTALL="docker run --rm --privileged -v /:/host \
  -e HOST=/host -e IMAGE=IMAGE -e NAME=NAME \
  IMAGE /bin/uninstall.sh"

  The contents of the UNINSTALL label tells an `atomic uninstall rhel7/rsyslog` command to uninstall the rsyslog
  container. Stopping the container in this way removes the container, but not the rsyslog image from your system.
  Also, uninstalling leaves all rsyslog configuration files and log files intact on the host (only removing the
  syslog logrotate file).

`BZComponent=`

The bugzilla component for this container. For example, "BZComponent="rsyslog-docker".

`Name=`

The registry location and name of the image. For example, "Name="rhel7/rsyslog":

`Version=`

The Red Hat Enterprise Linux version from which the container was built. For example, "Version="7.2".

`Release=`

The specific release number of the container Release="12.1.a":

`Architecture=`

The machine architecture associated with the Red Hat Enterprise Linux release. For example, "Architecture="x86_64"

When the atomic command runs the rsyslog container, it reads the command line associated with the selected option
from a LABEL set within the Docker container itself. It then runs that command. The following sections detail
each option and associated LABEL:

# SECURITY IMPLICATIONS
The rsyslog container is what is referred to as a super-privileged container. It is designed to have almost complete
access to the host system as root user. The following docker command options open selected privileges to the host:

`-d`

Runs continuously as a daemon process in the background

`--privileged`

Turns off security separation, so a process running as root in the container would have the same access to the
host as it would if it were run directly on the host.

`--net=host`

Allows processes run inside the container to directly access host network interfaces

`--pid=host`

Allows processes run inside the container to see and work with all processes in the host process table

`--restart=always`

If the container should fail or otherwise stop, it would be restarted

# HISTORY
Similar to a Changelog of sorts which can be as detailed as the maintainer wishes.

# AUTHORS
Stephen Tweedie

Converting Markdown to man Format

There are several methods for converting markdown format to man format. One prevalent method is to use go-md2man supplied by the golang-github-cpuguy83-go-md2man package. To convert from markdown to man using this utility, you do as follows:

go-md2man -in path_to_man_file -out output_file