Merge pull request #15102 from moxiegirl/fix-run-headings

Several fixes in formatting

docs/reference/logging/fluentd.md

@@ -25,8 +25,16 @@ driver sends the following metadata in the structured log message:
 | `container_name` | The container name at the time it was started. If you use `docker rename` to rename a container, the new name is not reflected in the journal entries.                                         |
 | `source`         | `stdout` or `stderr`                |
 
+The `docker logs` command is not available for this logging driver.
+
 ## Usage
 
+Some options are supported by specifying `--log-opt` as many times as needed:
+
+ - `fluentd-address`: specify `host:port` to connect `localhost:24224`
+ - `fluentd-tag`: specify tag for fluentd message, which interpret some markup, ex `{{.ID}}`, `{{.FullID}}` or `{{.Name}}` `docker.{{.ID}}`
+
+
 Configure the default logging driver by passing the
 `--log-driver` option to the Docker daemon:
 

docs/reference/logging/index.md

@@ -1,129 +1,18 @@
 <!--[metadata]>
 +++
-title = "Configure logging drivers"
-description = "Configure logging driver."
-keywords = ["Fluentd, docker, logging, driver"]
+title = "Logging Drivers"
+description = "Logging Drivers"
+keywords = [" docker, logging, driver"]
 [menu.main]
-parent = "smn_logging"
+parent = "smn_administrate"
+identifier = "smn_logging"
+weight=8
 +++
 <![end-metadata]-->
 
 
-# Configure logging drivers
+# Logging Drivers
 
-The container can have a different logging driver than the Docker daemon. Use
-the `--log-driver=VALUE` with the `docker run` command to configure the
-container's logging driver. The following options are supported:
-
-| `none`      | Disables any logging for the container. `docker logs` won't be available with this driver.                                    |
-|-------------|-------------------------------------------------------------------------------------------------------------------------------|
-| `json-file` | Default logging driver for Docker. Writes JSON messages to file.                                                              |
-| `syslog`    | Syslog logging driver for Docker. Writes log messages to syslog.                                                              |
-| `journald`  | Journald logging driver for Docker. Writes log messages to `journald`.                                                        |
-| `gelf`      | Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash. |
-| `fluentd`   | Fluentd logging driver for Docker. Writes log messages to `fluentd` (forward input).                                          |
-
-The `docker logs`command is available only for the `json-file` logging driver.  
-
-### The json-file options
-
-The following logging options are supported for the `json-file` logging driver:
-
-    --log-opt max-size=[0-9+][k|m|g]
-    --log-opt max-file=[0-9+]
-
-Logs that reach `max-size` are rolled over. You can set the size in kilobytes(k), megabytes(m), or gigabytes(g). eg `--log-opt max-size=50m`. If `max-size` is not set, then logs are not rolled over.
-
-
-`max-file` specifies the maximum number of files that a log is rolled over before being discarded. eg `--log-opt max-file=100`. If `max-size` is not set, then `max-file` is not honored.
-
-If `max-size` and `max-file` are set, `docker logs` only returns the log lines from the newest log file. 
-
-### The syslog options
-
-The following logging options are supported for the `syslog` logging driver:
-
-    --log-opt syslog-address=[tcp|udp]://host:port
-    --log-opt syslog-address=unix://path
-    --log-opt syslog-facility=daemon
-    --log-opt syslog-tag="mailer"
-
-`syslog-address` specifies the remote syslog server address where the driver connects to.
-If not specified it defaults to the local unix socket of the running system.
-If transport is either `tcp` or `udp` and `port` is not specified it defaults to `514`
-The following example shows how to have the `syslog` driver connect to a `syslog`
-remote server at `192.168.0.42` on port `123`
-
-    $ docker run --log-driver=syslog --log-opt syslog-address=tcp://192.168.0.42:123
-
-The `syslog-facility` option configures the syslog facility. By default, the system uses the
-`daemon` value. To override this behavior, you can provide an integer of 0 to 23 or any of
-the following named facilities:
-
-* `kern`
-* `user`
-* `mail`
-* `daemon`
-* `auth`
-* `syslog`
-* `lpr`
-* `news`
-* `uucp`
-* `cron`
-* `authpriv`
-* `ftp`
-* `local0`
-* `local1`
-* `local2`
-* `local3`
-* `local4`
-* `local5`
-* `local6`
-* `local7`
-
-The `syslog-tag` specifies a tag that identifies the container's syslog messages. By default,
-the system uses the first 12 characters of the container id. To override this behavior, specify
-a `syslog-tag` option
-
-## Specify journald options
-
-The `journald` logging driver stores the container id in the journal's `CONTAINER_ID` field. For detailed information on
-working with this logging driver, see [the journald logging driver](/reference/logging/journald/)
-reference documentation.
-
-## Specify gelf options
-
-The GELF logging driver supports the following options:
-
-    --log-opt gelf-address=udp://host:port
-    --log-opt gelf-tag="database"
-
-The `gelf-address` option specifies the remote GELF server address that the
-driver connects to. Currently, only `udp` is supported as the transport and you must
-specify a `port` value. The following example shows how to connect the `gelf`
-driver to a GELF remote server at `192.168.0.42` on port `12201`
-
-    $ docker run --log-driver=gelf --log-opt gelf-address=udp://192.168.0.42:12201
-
-The `gelf-tag` option specifies a tag for easy container identification.
-
-## Specify fluentd options
-
-You can use the `--log-opt NAME=VALUE` flag to specify these additional Fluentd logging driver options.
-
- - `fluentd-address`: specify `host:port` to connect [localhost:24224]
- - `fluentd-tag`: specify tag for `fluentd` message, 
-
-When specifying a `fluentd-tag` value, you can use the following markup tags:
-
- - `{{.ID}}`: short container id (12 characters)
- - `{{.FullID}}`: full container id
- - `{{.Name}}`: container name
-
-For example, to specify both additional options:
-
-`docker run --log-driver=fluentd --log-opt fluentd-address=localhost:24224 --log-opt fluentd-tag=docker.{{.Name}}`
-
-If container cannot connect to the Fluentd daemon on the specified address,
-the container stops immediately. For detailed information on working with this
-logging driver, see [the fluentd logging driver](/reference/logging/fluentd/)
+* [Configuring logging drivers](overview)
+* [Fluentd logging driver](fluentd)
+* [Journald logging driver](journald)

docs/reference/logging/overview.md

@@ -0,0 +1,130 @@
+<!--[metadata]>
++++
+title = "Configuring Logging Drivers"
+description = "Configure logging driver."
+keywords = ["Fluentd, docker, logging, driver"]
+[menu.main]
+parent = "smn_logging"
+weight=-1
++++
+<![end-metadata]-->
+
+
+# Configure logging drivers
+
+The container can have a different logging driver than the Docker daemon. Use
+the `--log-driver=VALUE` with the `docker run` command to configure the
+container's logging driver. The following options are supported:
+
+| `none`      | Disables any logging for the container. `docker logs` won't be available with this driver.                                    |
+|-------------|-------------------------------------------------------------------------------------------------------------------------------|
+| `json-file` | Default logging driver for Docker. Writes JSON messages to file.                                                              |
+| `syslog`    | Syslog logging driver for Docker. Writes log messages to syslog.                                                              |
+| `journald`  | Journald logging driver for Docker. Writes log messages to `journald`.                                                        |
+| `gelf`      | Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash. |
+| `fluentd`   | Fluentd logging driver for Docker. Writes log messages to `fluentd` (forward input).                                          |
+
+The `docker logs`command is available only for the `json-file` logging driver.  
+
+### The json-file options
+
+The following logging options are supported for the `json-file` logging driver:
+
+    --log-opt max-size=[0-9+][k|m|g]
+    --log-opt max-file=[0-9+]
+
+Logs that reach `max-size` are rolled over. You can set the size in kilobytes(k), megabytes(m), or gigabytes(g). eg `--log-opt max-size=50m`. If `max-size` is not set, then logs are not rolled over.
+
+
+`max-file` specifies the maximum number of files that a log is rolled over before being discarded. eg `--log-opt max-file=100`. If `max-size` is not set, then `max-file` is not honored.
+
+If `max-size` and `max-file` are set, `docker logs` only returns the log lines from the newest log file. 
+
+### The syslog options
+
+The following logging options are supported for the `syslog` logging driver:
+
+    --log-opt syslog-address=[tcp|udp]://host:port
+    --log-opt syslog-address=unix://path
+    --log-opt syslog-facility=daemon
+    --log-opt syslog-tag="mailer"
+
+`syslog-address` specifies the remote syslog server address where the driver connects to.
+If not specified it defaults to the local unix socket of the running system.
+If transport is either `tcp` or `udp` and `port` is not specified it defaults to `514`
+The following example shows how to have the `syslog` driver connect to a `syslog`
+remote server at `192.168.0.42` on port `123`
+
+    $ docker run --log-driver=syslog --log-opt syslog-address=tcp://192.168.0.42:123
+
+The `syslog-facility` option configures the syslog facility. By default, the system uses the
+`daemon` value. To override this behavior, you can provide an integer of 0 to 23 or any of
+the following named facilities:
+
+* `kern`
+* `user`
+* `mail`
+* `daemon`
+* `auth`
+* `syslog`
+* `lpr`
+* `news`
+* `uucp`
+* `cron`
+* `authpriv`
+* `ftp`
+* `local0`
+* `local1`
+* `local2`
+* `local3`
+* `local4`
+* `local5`
+* `local6`
+* `local7`
+
+The `syslog-tag` specifies a tag that identifies the container's syslog messages. By default,
+the system uses the first 12 characters of the container id. To override this behavior, specify
+a `syslog-tag` option
+
+## Specify journald options
+
+The `journald` logging driver stores the container id in the journal's `CONTAINER_ID` field. For detailed information on
+working with this logging driver, see [the journald logging driver](/reference/logging/journald/)
+reference documentation.
+
+## Specify gelf options
+
+The GELF logging driver supports the following options:
+
+    --log-opt gelf-address=udp://host:port
+    --log-opt gelf-tag="database"
+
+The `gelf-address` option specifies the remote GELF server address that the
+driver connects to. Currently, only `udp` is supported as the transport and you must
+specify a `port` value. The following example shows how to connect the `gelf`
+driver to a GELF remote server at `192.168.0.42` on port `12201`
+
+    $ docker run --log-driver=gelf --log-opt gelf-address=udp://192.168.0.42:12201
+
+The `gelf-tag` option specifies a tag for easy container identification.
+
+## Specify fluentd options
+
+You can use the `--log-opt NAME=VALUE` flag to specify these additional Fluentd logging driver options.
+
+ - `fluentd-address`: specify `host:port` to connect [localhost:24224]
+ - `fluentd-tag`: specify tag for `fluentd` message, 
+
+When specifying a `fluentd-tag` value, you can use the following markup tags:
+
+ - `{{.ID}}`: short container id (12 characters)
+ - `{{.FullID}}`: full container id
+ - `{{.Name}}`: container name
+
+For example, to specify both additional options:
+
+`docker run --log-driver=fluentd --log-opt fluentd-address=localhost:24224 --log-opt fluentd-tag=docker.{{.Name}}`
+
+If container cannot connect to the Fluentd daemon on the specified address,
+the container stops immediately. For detailed information on working with this
+logging driver, see [the fluentd logging driver](/reference/logging/fluentd/)

docs/reference/run.md

@@ -491,9 +491,7 @@ command:
 
     $ docker run --security-opt label:type:svirt_apache_t -i -t centos bash
 
-Note:
-
-You would have to write policy defining a `svirt_apache_t` type.
+> **Note**: You would have to write policy defining a `svirt_apache_t` type.
 
 ## Specifying custom cgroups
 
@@ -507,16 +505,18 @@ parent group.
 The operator can also adjust the performance parameters of the
 container:
 
-    -m, --memory="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
-    --memory-swap="": Total memory limit (memory + swap, format: <number><optional unit>, where unit = b, k, m or g)
-    -c, --cpu-shares=0: CPU shares (relative weight)
-    --cpu-period=0: Limit the CPU CFS (Completely Fair Scheduler) period
-    --cpuset-cpus="": CPUs in which to allow execution (0-3, 0,1)
-    --cpuset-mems="": Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
-    --cpu-quota=0: Limit the CPU CFS (Completely Fair Scheduler) quota
-    --blkio-weight=0: Block IO weight (relative weight) accepts a weight value between 10 and 1000.
-    --oom-kill-disable=true|false: Whether to disable OOM Killer for the container or not.
-    --memory-swappiness="": Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
+| Option                               |  Description                                                                                      |
+|--------------------------------------|---------------------------------------------------------------------------------------------|
+| `-m`, `--memory="" `                 | Memory limit (format: , where unit = b, k, m or g)                                          |
+| `--memory-swap=""`                   | Total memory limit (memory + swap, format: , where unit = b, k, m or g)                     |
+| `-c`, `--cpu-shares=0`               | CPU shares (relative weight)                                                                |
+| `--cpu-period=0`                     | Limit the CPU CFS (Completely Fair Scheduler) period                                        |
+| `--cpuset-cpus="" `                  | CPUs in which to allow execution (0-3, 0,1)                                                 |
+| `--cpuset-mems=""`                   | Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. |
+| `--cpu-quota=0`                      | Limit the CPU CFS (Completely Fair Scheduler) quota                                         |
+| `--blkio-weight=0`                   | Block IO weight (relative weight) accepts a weight value between 10 and 1000.               |
+| `--oom-kill-disable=true` or `false` | Whether to disable OOM Killer for the container or not.                                     |
+| `--memory-swappiness=""  `           | Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.        |
 
 ### Memory constraints
 
@@ -568,7 +568,7 @@ We have four ways to set memory usage:
   </tbody>
 </table>
 
-Examples:
+### Examples
 
     $ docker run -ti ubuntu:14.04 /bin/bash
 
@@ -600,8 +600,6 @@ Only disable the OOM killer on containers where you have also set the
 running out of memory and require killing the host's system processes to free
 memory.
 
-Examples:
-
 The following example limits the memory to 100M and disables the OOM killer for
 this container:
 
@@ -894,7 +892,7 @@ familiar with using LXC directly.
 > you can use `--lxc-conf` to set a container's IP address, but this will not be
 > reflected in the `/etc/hosts` file.
 
-# Logging drivers (--log-driver)
+## Logging drivers (--log-driver)
 
 The container can have a different logging driver than the Docker daemon. Use
 the `--log-driver=VALUE` with the `docker run` command to configure the
@@ -910,17 +908,8 @@ container's logging driver. The following options are supported:
 
 	The `docker logs`command is available only for the `json-file` logging
 driver.  For detailed information on working with logging drivers, see
-[Configure a logging driver](reference/logging/).
-
-#### Logging driver: fluentd
-
-Fluentd logging driver for Docker. Writes log messages to fluentd (forward input). `docker logs`
-command is not available for this logging driver.
-
-Some options are supported by specifying `--log-opt` as many as needed, like `--log-opt fluentd-address=localhost:24224 --log-opt fluentd-tag=docker.{{.Name}}`.
+[Configure a logging driver](reference/logging/overview.md).
 
- - `fluentd-address`: specify `host:port` to connect [localhost:24224]
- - `fluentd-tag`: specify tag for fluentd message, which interpret some markup, ex `{{.ID}}`, `{{.FullID}}` or `{{.Name}}` [docker.{{.ID}}]
 
 ## Overriding Dockerfile image defaults
 
@@ -942,7 +931,7 @@ Dockerfile instruction and how the operator can override that setting.
  - [USER](#user)
  - [WORKDIR](#workdir)
 
-## CMD (default command or options)
+### CMD (default command or options)
 
 Recall the optional `COMMAND` in the Docker
 commandline:
@@ -958,7 +947,7 @@ image), you can override that `CMD` instruction just by specifying a new
 If the image also specifies an `ENTRYPOINT` then the `CMD` or `COMMAND`
 get appended as arguments to the `ENTRYPOINT`.
 
-## ENTRYPOINT (default command to execute at runtime)
+### ENTRYPOINT (default command to execute at runtime)
 
     --entrypoint="": Overwrite the default entrypoint set by the image
 
@@ -981,7 +970,7 @@ or two examples of how to pass more parameters to that ENTRYPOINT:
     $ docker run -i -t --entrypoint /bin/bash example/redis -c ls -l
     $ docker run -i -t --entrypoint /usr/bin/redis-cli example/redis --help
 
-## EXPOSE (incoming ports)
+### EXPOSE (incoming ports)
 
 The Dockerfile doesn't give much control over networking, only providing
 the `EXPOSE` instruction to give a hint to the operator about what
@@ -1023,7 +1012,7 @@ then the client container can access the exposed port via a private
 networking interface.  Docker will set some environment variables in the
 client container to help indicate which interface and port to use.
 
-## ENV (environment variables)
+### ENV (environment variables)
 
 When a new container is created, Docker will set the following environment
 variables automatically:
@@ -1136,7 +1125,7 @@ container's `/etc/hosts` entry will be automatically updated.
 > restarted. We recommend using the host entries in `/etc/hosts` to resolve the
 > IP address of linked containers.
 
-## VOLUME (shared filesystems)
+### VOLUME (shared filesystems)
 
     -v=[]: Create a bind mount with: [host-dir:]container-dir[:rw|ro].
            If 'host-dir' is missing, then docker creates a new volume.
@@ -1151,7 +1140,7 @@ one or more `VOLUME`'s associated with an image, but only the operator
 can give access from one container to another (or from a container to a
 volume mounted on the host).
 
-## USER
+### USER
 
 The default user within a container is `root` (id = 0), but if the
 developer created additional users, those are accessible too. The
@@ -1162,7 +1151,7 @@ Dockerfile `USER` instruction, but the operator can override it:
 
 > **Note:** if you pass numeric uid, it must be in range 0-2147483647.
 
-## WORKDIR
+### WORKDIR
 
 The default working directory for running binaries within a container is the
 root directory (`/`), but the developer can set a different default with the