From 255ee9aa6c619cfbab816049e649622cc5e63c4a Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Tue, 28 Jul 2015 14:02:57 -0700 Subject: [PATCH] Several fixes in formatting - fixing headings in run.md - creating a table for readability - adding index for logging - moving logging overview into logging - Updating with Seb's comments Signed-off-by: Mary Anthony Upstream-commit: 70aa63b92a1aba21a0276904c9447ac7c5114f50 Component: engine --- .../engine/docs/reference/logging/fluentd.md | 8 ++ .../engine/docs/reference/logging/index.md | 131 ++---------------- .../engine/docs/reference/logging/overview.md | 130 +++++++++++++++++ components/engine/docs/reference/run.md | 57 +++----- 4 files changed, 171 insertions(+), 155 deletions(-) create mode 100644 components/engine/docs/reference/logging/overview.md diff --git a/components/engine/docs/reference/logging/fluentd.md b/components/engine/docs/reference/logging/fluentd.md index 71af9f0b7f..cecdce4a63 100644 --- a/components/engine/docs/reference/logging/fluentd.md +++ b/components/engine/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: diff --git a/components/engine/docs/reference/logging/index.md b/components/engine/docs/reference/logging/index.md index c6b937d4fa..7fd9245dc5 100644 --- a/components/engine/docs/reference/logging/index.md +++ b/components/engine/docs/reference/logging/index.md @@ -1,129 +1,18 @@ -# 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) \ No newline at end of file diff --git a/components/engine/docs/reference/logging/overview.md b/components/engine/docs/reference/logging/overview.md new file mode 100644 index 0000000000..423fbfcafe --- /dev/null +++ b/components/engine/docs/reference/logging/overview.md @@ -0,0 +1,130 @@ + + + +# 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/) diff --git a/components/engine/docs/reference/run.md b/components/engine/docs/reference/run.md index 30740873d2..df3f656ac6 100644 --- a/components/engine/docs/reference/run.md +++ b/components/engine/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: , 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|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: -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/). +[Configure a logging driver](reference/logging/overview.md). -#### 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}}`. - - - `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