docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

container config section: various markdown fixes 

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2020-04-08 10:43:27 +02:00
parent f8347be151
commit 727941ffdd
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
17 changed files with 383 additions and 307 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
config/containers/live-restore.md
View File

@ -12,8 +12,10 @@ containers remain running if the daemon becomes unavailable. This functionality
is called _live restore_. The live restore option helps reduce container
downtime due to daemon crashes, planned outages, or upgrades.
> **Note**: Live restore is not supported on Windows containers, but it does work
for Linux containers running on Docker Desktop for Windows.
> **Note**
>
> Live restore is not supported on Windows containers, but it does work for
> Linux containers running on Docker Desktop for Windows.
## Enable live restore
@ -21,8 +23,8 @@ There are two ways to enable the live restore setting to keep containers alive
when the daemon becomes unavailable. **Only do one of the following**.
* Add the configuration to the daemon configuration file. On Linux, this
defaults to `/etc/docker/daemon.json`. On Docker Desktop for Mac or Docker Desktop for Windows,
select the Docker icon from the task bar, then click
defaults to `/etc/docker/daemon.json`. On Docker Desktop for Mac or Docker
Desktop for Windows, select the Docker icon from the task bar, then click
**Preferences** -> **Daemon** -> **Advanced**.
- Use the following JSON to enable `live-restore`.
@ -46,7 +48,9 @@ when the daemon becomes unavailable. **Only do one of the following**.
## Live restore during upgrades
Live restore supports keeping containers running across Docker daemon upgrades, though this is limited to patch releases and does not support minor or major daemon upgrades.
Live restore allows you to keep containers running across Docker daemon updates,
but is only supported when installing patch releases (`YY.MM.x`), not for
major (`YY.MM`) daemon upgrades.
If you skip releases during an upgrade, the daemon may not restore its
connection to the containers. If the daemon can't restore the connection, it
@ -76,5 +80,3 @@ The live restore option only pertains to standalone containers, and not to swarm
services. Swarm services are managed by swarm managers. If swarm managers are
not available, swarm services continue to run on worker nodes but cannot be
managed until enough swarm managers are available to maintain a quorum.

74
config/containers/logging/awslogs.md
View File

@ -38,7 +38,9 @@ Restart Docker for the changes to take effect.
You can set the logging driver for a specific container by using the
`--log-driver` option to `docker run`:
docker run --log-driver=awslogs ...
```bash
$ docker run --log-driver=awslogs ...
```
If you are using Docker Compose, set `awslogs` using the following declaration example:
@ -63,7 +65,9 @@ the `awslogs-region` log option or the `AWS_REGION` environment variable to set
the region. By default, if your Docker daemon is running on an EC2 instance
and no region is set, the driver uses the instance's region.
docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 ...
```bash
$ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 ...
```
### awslogs-group
@ -72,7 +76,9 @@ You must specify a
for the `awslogs` logging driver. You can specify the log group with the
`awslogs-group` log option:
docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 --log-opt awslogs-group=myLogGroup ...
```bash
$ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 --log-opt awslogs-group=myLogGroup ...
```
### awslogs-stream
@ -81,7 +87,8 @@ To configure which
should be used, you can specify the `awslogs-stream` log option. If not
specified, the container ID is used as the log stream.
> **Note**:
> **Note**
>
> Log streams within a given log group should only be used by one container
> at a time. Using the same log stream for multiple containers concurrently
> can cause reduced logging performance.
@ -93,15 +100,18 @@ Log driver returns an error by default if the log group does not exist. However,
The `awslogs-create-group` option defaults to `false`.
```bash
$ docker run --log-driver=awslogs \
$ docker run \
--log-driver=awslogs \
--log-opt awslogs-region=us-east-1 \
--log-opt awslogs-group=myLogGroup \
--log-opt awslogs-create-group=true \
...
```
> **Note**:
> Your AWS IAM policy must include the `logs:CreateLogGroup` permission before you attempt to use `awslogs-create-group`.
> **Note**
>
> Your AWS IAM policy must include the `logs:CreateLogGroup` permission before
> you attempt to use `awslogs-create-group`.
### awslogs-datetime-format
@ -119,14 +129,15 @@ This option always takes precedence if both `awslogs-datetime-format` and
`awslogs-multiline-pattern` are configured.
> **Note**:
> **Note**
>
> Multiline logging performs regular expression parsing and matching of all log
> messages, which may have a negative impact on logging performance.
Consider the following log stream, where new log messages start with a
timestamp:
```none
```console
[May 01, 2017 19:00:01] A message was logged
[May 01, 2017 19:00:04] Another multiline message was logged
Some random message
@ -139,7 +150,8 @@ The format can be expressed as a `strftime` expression of
that expression:
```bash
$ docker run --log-driver=awslogs \
$ docker run \
--log-driver=awslogs \
--log-opt awslogs-region=us-east-1 \
--log-opt awslogs-group=myLogGroup \
--log-opt awslogs-datetime-format='\[%b %d, %Y %H:%M:%S\]' \
@ -148,7 +160,7 @@ $ docker run --log-driver=awslogs \
This parses the logs into the following CloudWatch log events:
```none
```console
# First event
[May 01, 2017 19:00:01] A message was logged
@ -203,7 +215,7 @@ For example, to process the following log stream where new log messages start wi
Consider the following log stream, where each log message should start with the
patther `INFO`:
```none
```console
INFO A message was logged
INFO Another multiline message was logged
Some random message
@ -213,7 +225,8 @@ INFO Another message was logged
You can use the regular expression of `^INFO`:
```bash
$ docker run --log-driver=awslogs \
$ docker run \
--log-driver=awslogs \
--log-opt awslogs-region=us-east-1 \
--log-opt awslogs-group=myLogGroup \
--log-opt awslogs-multiline-pattern='^INFO' \
@ -222,7 +235,7 @@ $ docker run --log-driver=awslogs \
This parses the logs into the following CloudWatch log events:
```none
```console
# First event
INFO A message was logged
@ -236,20 +249,31 @@ INFO Another message was logged
### tag
Specify `tag` as an alternative to the `awslogs-stream` option. `tag` interprets Go template markup, such as `{% raw %}{{.ID}}{% endraw %}`, `{% raw %}{{.FullID}}{% endraw %}` or `{% raw %}{{.Name}}{% endraw %}` `{% raw %}docker.{{.ID}}{% endraw %}`.
See the [tag option documentation](log_tags.md) for details on all supported template substitutions.
Specify `tag` as an alternative to the `awslogs-stream` option. `tag` interprets
Go template markup, such as `{% raw %}{{.ID}}{% endraw %}`, `{% raw %}{{.FullID}}{% endraw %}`
or `{% raw %}{{.Name}}{% endraw %}` `{% raw %}docker.{{.ID}}{% endraw %}`. See
the [tag option documentation](log_tags.md) for details on supported template
substitutions.
When both `awslogs-stream` and `tag` are specified, the value supplied for `awslogs-stream` overrides the template specified with `tag`.
When both `awslogs-stream` and `tag` are specified, the value supplied for
`awslogs-stream` overrides the template specified with `tag`.
If not specified, the container ID is used as the log stream.
{% raw %}
> **Note**:
> The CloudWatch log API doesn't support `:` in the log name. This can cause some issues when using the `{{ .ImageName }}` as a tag, since a docker image has a format of `IMAGE:TAG`, such as `alpine:latest`.
> Template markup can be used to get the proper format.
> To get the image name and the first 12 characters of the container ID, you can use: `--log-opt tag='{{ with split .ImageName ":" }}{{join . "_"}}{{end}}-{{.ID}}'`
> **Note**
>
> The CloudWatch log API does not support `:` in the log name. This can cause
> some issues when using the {% raw %}`{{ .ImageName }}`{% endraw %} as a tag,
> since a docker image has a format of `IMAGE:TAG`, such as `alpine:latest`.
> Template markup can be used to get the proper format. To get the image name
> and the first 12 characters of the container ID, you can use:
>
> {% raw %}
> ```bash
> --log-opt tag='{{ with split .ImageName ":" }}{{join . "_"}}{{end}}-{{.ID}}'
> ```
> {% endraw %}
> the output is something like: `alpine_latest-bf0072049c76`
{% endraw %}
## Credentials
@ -258,12 +282,13 @@ You must provide AWS credentials to the Docker daemon to use the `awslogs`
logging driver. You can provide these credentials with the `AWS_ACCESS_KEY_ID`,
`AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables, the
default AWS shared credentials file (`~/.aws/credentials` of the root user), or
(if you are running the Docker daemon on an Amazon EC2 instance) the Amazon EC2
if you are running the Docker daemon on an Amazon EC2 instance, the Amazon EC2
instance profile.
Credentials must have a policy applied that allows the `logs:CreateLogStream`
and `logs:PutLogEvents` actions, as shown in the following example.
```json
{
"Version": "2012-10-17",
"Statement": [
@ -277,3 +302,4 @@ and `logs:PutLogEvents` actions, as shown in the following example.
}
]
}
```

78
config/containers/logging/configure.md
View File

@ -10,14 +10,14 @@ title: Configure logging drivers
---
Docker includes multiple logging mechanisms to help you
[get information from running containers and services](/engine/admin/logging/view_container_logs.md).
[get information from running containers and services](index.md).
These mechanisms are called logging drivers.
Each Docker daemon has a default logging driver, which each container uses
unless you configure it to use a different logging driver.
In addition to using the logging drivers included with Docker, you can also
implement and use [logging driver plugins](/engine/admin/logging/plugins.md).
implement and use [logging driver plugins](plugins.md).
## Configure the default logging driver
@ -50,9 +50,11 @@ example sets two configurable options on the `json-file` logging driver:
}
```
> **Note**: `log-opts` configuration options in the `daemon.json` configuration
> file must be provided as strings. Boolean and numeric values (such as the value
> for `max-file` in the example above) must therefore be enclosed in quotes (`"`).
> **Note**
>
> `log-opts` configuration options in the `daemon.json` configuration file must
> be provided as strings. Boolean and numeric values (such as the value for
> `max-file` in the example above) must therefore be enclosed in quotes (`"`).
If you do not specify a logging driver, the default is `json-file`. Thus,
the default output for commands such as `docker inspect <CONTAINER>` is JSON.
@ -97,21 +99,32 @@ json-file
## Configure the delivery mode of log messages from container to log driver
Docker provides two modes for delivering messages from the container to the log driver:
Docker provides two modes for delivering messages from the container to the log
driver:
* (default) direct, blocking delivery from container to driver
* non-blocking delivery that stores log messages in an intermediate per-container ring buffer for consumption by driver
* non-blocking delivery that stores log messages in an intermediate per-container
ring buffer for consumption by driver
The `non-blocking` message delivery mode prevents applications from blocking due to logging back pressure. Applications are likely to fail in unexpected ways when STDERR or STDOUT streams block.
The `non-blocking` message delivery mode prevents applications from blocking due
to logging back pressure. Applications are likely to fail in unexpected ways when
STDERR or STDOUT streams block.
> **WARNING**: When the buffer is full and a new message is enqueued, the oldest message in memory is dropped. Dropping messages is often preferred to blocking the log-writing process of an application.
> **WARNING**
> When the buffer is full and a new message is enqueued, the oldest message in
> memory is dropped. Dropping messages is often preferred to blocking the
> log-writing process of an application.
{: .warning}
The `mode` log option controls whether to use the `blocking` (default) or `non-blocking` message delivery.
The `mode` log option controls whether to use the `blocking` (default) or
`non-blocking` message delivery.
The `max-buffer-size` log option controls the size of the ring buffer used for intermediate message storage when `mode` is set to `non-blocking`. `max-buffer-size` defaults to 1 megabyte.
The `max-buffer-size` log option controls the size of the ring buffer used for
intermediate message storage when `mode` is set to `non-blocking`. `max-buffer-size`
defaults to 1 megabyte.
The following example starts an Alpine container with log output in non-blocking mode and a 4 megabyte buffer:
The following example starts an Alpine container with log output in non-blocking
mode and a 4 megabyte buffer:
```bash
$ docker run -it --log-opt mode=non-blocking --log-opt max-buffer-size=4m alpine ping 127.0.0.1
@ -139,7 +152,7 @@ output. The following output is generated by the `json-file` logging driver:
The following logging drivers are supported. See the link to each driver's
documentation for its configurable options, if applicable. If you are using
[logging driver plugins](/engine/admin/logging/plugins.md), you may
[logging driver plugins](plugins.md), you may
see more options.
| Driver | Description |
@ -159,25 +172,26 @@ see more options.
## Limitations of logging drivers
- Users of Docker Enterprise can make use of "dual logging", which enables you to use the `docker logs`
command for any logging driver. Refer to
[Reading logs when using remote logging drivers](/config/containers/logging/dual-logging/) for information about
using `docker logs` to read container logs locally for many third party logging solutions, including:
- syslog
- gelf
- fluentd
- awslogs
- splunk
- etwlogs
- gcplogs
- Logentries
- When using Docker Community Engine, the `docker logs` command is only available on the following drivers:
- Users of Docker Enterprise can make use of "dual logging", which enables you
to use the `docker logs` command for any logging driver. Refer to
[reading logs when using remote logging drivers](dual-logging.md) for
information about using `docker logs` to read container logs locally for many
third party logging solutions, including:
- `syslog`
- `gelf`
- `fluentd`
- `awslogs`
- `splunk`
- `etwlogs`
- `gcplogs`
- `Logentries`
- When using Docker Community Engine, the `docker logs` command is only available
on the following drivers:
- `local`
- `json-file`
- `journald`
- Reading log information requires decompressing rotated log files, which causes a temporary increase in disk usage (until the log entries from the rotated files are read) and an increased CPU usage while decompressing.
- The capacity of the host storage where docker’s data directory resides determines the maximum size of the log file information.
- Reading log information requires decompressing rotated log files, which causes
a temporary increase in disk usage (until the log entries from the rotated
files are read) and an increased CPU usage while decompressing.
- The capacity of the host storage where the Docker data directory resides
determines the maximum size of the log file information.

98
config/containers/logging/dual-logging.md
View File

@ -6,47 +6,57 @@ title: Use docker logs to read container logs for remote logging drivers
## Overview
Prior to Docker Engine Enterprise 18.03, the `jsonfile` and `journald` log drivers supported reading
container logs using `docker logs`. However, many third party logging drivers had no
support for locally reading logs using `docker logs`, including:
Prior to Docker Engine Enterprise 18.03, the `jsonfile` and `journald` log
drivers supported reading container logs using `docker logs`. However, many
third party logging drivers had no support for locally reading logs using
`docker logs`, including:
- syslog
- gelf
- fluentd
- awslogs
- splunk
- etwlogs
- gcplogs
- Logentries
- `syslog`
- `gelf`
- `fluentd`
- `awslogs`
- `splunk`
- `etwlogs`
- `gcplogs`
- `logentries`
This created multiple problems, especially with UCP, when attempting to gather log data in an
automated and standard way. Log information could only be accessed and viewed through the
third-party solution in the format specified by that third-party tool.
This created multiple problems when attempting to gather log data in an
automated and standard way. Log information could only be accessed and viewed
through the third-party solution in the format specified by that
third-party tool.
Starting with Docker Engine Enterprise 18.03.1-ee-1, you can use `docker logs` to read container
logs regardless of the configured logging driver or plugin. This capability, sometimes referred to
as dual logging, allows you to use `docker logs` to read container logs locally in a consistent format,
regardless of the remote log driver used, because the engine is configured to log information to the “local”
logging driver. Refer to [Configure the default logging driver](/config/containers/logging/configure) for additional information.
Starting with Docker Engine Enterprise 18.03.1-ee-1, you can use `docker logs`
to read container logs regardless of the configured logging driver or plugin.
This capability, sometimes referred to as dual logging, allows you to use
`docker logs` to read container logs locally in a consistent format, regardless
of the remote log driver used, because the engine is configured to log
information to the “local” logging driver. Refer to
[Configure the default logging driver](/config/containers/logging/configure) for
additional information.
## Prerequisites
- Docker Enterprise - Dual logging is only supported for Docker Enterprise, and is enabled by default starting with
Engine Enterprise 18.03.1-ee-1.
Dual logging is only supported for Docker Enterprise, and is enabled by default
starting with Engine Enterprise 18.03.1-ee-1.
## Usage
Dual logging is enabled by default. You must configure either the docker daemon or the container with remote logging driver.
The following example shows the results of running a `docker logs` command with and without dual logging availability:
Dual logging is enabled by default. You must configure either the docker daemon
or the container with remote logging driver.
The following example shows the results of running a `docker logs` command with
and without dual logging availability:
### Without dual logging capability:
When a container or `dockerd` was configured with a remote logging driver such as splunk, an error was
displayed when attempting to read container logs locally:
When a container or `dockerd` was configured with a remote logging driver such
as `splunk`, an error was displayed when attempting to read container logs
locally:
- Step 1: Configure Docker daemon
```
```bash
$ cat /etc/docker/daemon.json
{
"log-driver": "splunk",
@ -58,12 +68,13 @@ displayed when attempting to read container logs locally:
- Step 2: Start the container
```
```bash
$ docker run -d busybox --name testlog top
```
- Step 3: Read the container logs
```
```bash
$ docker logs 7d6ac83a89a0
The docker logs command was not available for drivers other than json-file and journald.
```
@ -72,7 +83,8 @@ displayed when attempting to read container logs locally:
To configure a container or docker with a remote logging driver such as splunk:
- Step 1: Configure Docker daemon
```
```bash
$ cat /etc/docker/daemon.json
{
"log-driver": "splunk",
@ -83,12 +95,14 @@ To configure a container or docker with a remote logging driver such as splunk:
```
- Step 2: Start the container
```
```bash
$ docker run -d busybox --name testlog top
```
- Step 3: Read the container logs
```
```bash
$ docker logs 7d6ac83a89a0
2019-02-04T19:48:15.423Z [INFO] core: marked as sealed
2019-02-04T19:48:15.423Z [INFO] core: pre-seal teardown starting
@ -99,17 +113,21 @@ To configure a container or docker with a remote logging driver such as splunk:
2019-02-04T19:48:15.599Z [INFO] core: cluster listeners successfully shut down
```
Note:
For a local driver, such as json-file and journald, there is no difference in functionality
before or after the dual logging capability became available. The log is locally visible in both scenarios.
> **Note**
>
> For a local driver, such as json-file and journald, there is no difference in
> functionality before or after the dual logging capability became available.
> The log is locally visible in both scenarios.
## Limitations
- You cannot specify more than one log driver.
- If a container using a logging driver or plugin that sends logs remotely suddenly has a "network" issue,
no ‘write’ to the local cache occurs.
- If a write to `logdriver` fails for any reason (file system full, write permissions removed),
the cache write fails and is logged in the daemon log. The log entry to the cache is not retried.
- Some logs might be lost from the cache in the default configuration because a ring buffer is used to
prevent blocking the stdio of the container in case of slow file writes. An admin must repair these while the daemon is shut down.
- If a container using a logging driver or plugin that sends logs remotely
suddenly has a "network" issue, no ‘write’ to the local cache occurs.
- If a write to `logdriver` fails for any reason (file system full, write
permissions removed), the cache write fails and is logged in the daemon log.
The log entry to the cache is not retried.
- Some logs might be lost from the cache in the default configuration because a
ring buffer is used to prevent blocking the stdio of the container in case of
slow file writes. An admin must repair these while the daemon is shut down.

20
config/containers/logging/etwlogs.md
View File

@ -25,11 +25,11 @@ Here is an example of how to listen to these events using the logman utility pro
included in most installations of Windows:
1. `logman start -ets DockerContainerLogs -p {a3693192-9ed6-46d2-a981-f8226c8363bd} 0 0 -o trace.etl`
2. Run your container(s) with the etwlogs driver, by adding `--log-driver=etwlogs`
to the Docker run command, and generate log messages.
2. Run your container(s) with the etwlogs driver, by adding
`--log-driver=etwlogs` to the Docker run command, and generate log messages.
3. `logman stop -ets DockerContainerLogs`
4. This generates an etl file that contains the events. One way to convert this file into
human-readable form is to run: `tracerpt -y trace.etl`.
4. This generates an etl file that contains the events. One way to convert this
file into human-readable form is to run: `tracerpt -y trace.etl`.
Each ETW event contains a structured message string in this format:
@ -46,18 +46,22 @@ Details on each item in the message can be found below:
| `source` | `stdout` or `stderr`. |
| `log` | The container log message. |
Here is an example event message:
Here is an example event message (output formatted for readability):
```yaml
container_name: backstabbing_spence,
image_name: windowsservercore,
container_id: f14bb55aa862d7596b03a33251c1be7dbbec8056bbdead1da8ec5ecebbe29731,
image_id: sha256:2f9e19bd998d3565b4f345ac9aaf6e3fc555406239a4fb1b1ba879673713824b,
source: stdout,
log: Hello world!
```
A client can parse this message string to get both the log message, as well as its
context information. The timestamp is also available within the ETW event.
> **Note**: This ETW provider emits only a message string, and not a specially
> structured ETW event. Therefore, it is not required to register a manifest file
> with the system to read and interpret its ETW events.
> **Note**
>
> This ETW provider emits only a message string, and not a specially structured
> ETW event. Therefore, it is not required to register a manifest file with the
> system to read and interpret its ETW events.

8
config/containers/logging/fluentd.md
View File

@ -55,9 +55,11 @@ The following example sets the log driver to `fluentd` and sets the
Restart Docker for the changes to take effect.
> **Note**: `log-opt` configuration options in the `daemon.json` configuration
> file must be provided as strings. Boolean and numeric values (such as the value
> for `fluentd-async-connect` or `fluentd-max-retries`) must therefore be enclosed
> **Note**
>
> `log-opts` configuration options in the `daemon.json` configuration file must
> be provided as strings. Boolean and numeric values (such as the value for
> `fluentd-async-connect` or `fluentd-max-retries`) must therefore be enclosed
> in quotes (`"`).
To set the logging driver for a specific container, pass the

10
config/containers/logging/gcplogs.md
View File

@ -79,13 +79,16 @@ logging message.
Below is an example of the logging options required to log to the default
logging destination which is discovered by querying the GCE metadata server.
docker run --log-driver=gcplogs \
```bash
$ docker run \
--log-driver=gcplogs \
--log-opt labels=location \
--log-opt env=TEST \
--log-opt gcp-log-cmd=true \
--env "TEST=false" \
--label location=west \
your/application
```
This configuration also directs the driver to include in the payload the label
`location`, the environment variable `ENV`, and the command used to start the
@ -94,8 +97,11 @@ container.
An example of the logging options for running outside of GCE (the daemon must be
configured with GOOGLE_APPLICATION_CREDENTIALS):
docker run --log-driver=gcplogs \
```bash
$ docker run \
--log-driver=gcplogs \
--log-opt gcp-project=test-project
--log-opt gcp-meta-zone=west1 \
--log-opt gcp-meta-name=`hostname` \
your/application
```

29
config/containers/logging/gelf.md
View File

@ -41,28 +41,11 @@ option.
Restart Docker for the changes to take effect.
To use `gelf` as the default logging driver for new containers, pass the `--log-driver`
and `--log-opt` options to the Docker daemon:
```bash
dockerd
--log-driver gelf --log-opt gelf-address=udp://1.2.3.4:12201 \
```
To make the configuration permanent, you can configure it in `/etc/docker/daemon.json`:
```json
{
"log-driver": "gelf",
"log-opts": {
"gelf-address": "udp://1.2.3.4:12201"
}
}
```
> **Note**: `log-opt` configuration options in the `daemon.json` configuration
> file must be provided as strings. Boolean and numeric values (such as the value
> for `gelf-tcp-max-reconnect`) must therefore be enclosed in quotes (`"`).
> **Note**
>
> `log-opts` configuration options in the `daemon.json` configuration file must
> be provided as strings. Boolean and numeric values (such as the value for
> `gelf-tcp-max-reconnect`) must therefore be enclosed in quotes (`"`).
You can set the logging driver for a specific container by setting the
`--log-driver` flag when using `docker container create` or `docker run`:
@ -87,7 +70,7 @@ The `gelf` logging driver supports the following options:
| `tag` | optional | A string that is appended to the `APP-NAME` in the `gelf` message. By default, Docker uses the first 12 characters of the container ID to tag log messages. Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. | `--log-opt tag=mailer` |
| `labels` | optional | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon accepts. Adds additional key on the `extra` fields, prefixed by an underscore (`_`). Used for advanced [log tag options](log_tags.md). | `--log-opt labels=production_status,geo` |
| `env` | optional | Applies when starting the Docker daemon. A comma-separated list of logging-related environment variables this daemon accepts. Adds additional key on the `extra` fields, prefixed by an underscore (`_`). Used for advanced [log tag options](log_tags.md). | `--log-opt env=os,customer` |
| `env-regex` | optional | Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). | `--log-opt env-regex=^(os | customer).` |
| `env-regex` | optional | Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). | `--log-opt env-regex=^(os|customer)` |
### Examples

9
config/containers/logging/journald.md
View File

@ -55,11 +55,11 @@ Use the `--log-opt NAME=VALUE` flag to specify additional `journald` logging
driver options.
| Option | Required | Description |
|:------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `tag` | optional | Specify template to set `CONTAINER_TAG` and `SYSLOG_IDENTIFIER` value in journald logs. Refer to [log tag option documentation](/engine/admin/logging/log_tags/) to customize the log tag format. |
|:---------------|:---------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `tag` | optional | Specify template to set `CONTAINER_TAG` and `SYSLOG_IDENTIFIER` value in journald logs. Refer to [log tag option documentation](log_tags.md) to customize the log tag format. |
| `labels` | optional | Comma-separated list of keys of labels, which should be included in message, if these labels are specified for the container. |
| `env` | optional | Comma-separated list of keys of environment variables, which should be included in message, if these variables are specified for the container. |
| `env-regex` | optional | Similar to and compatible with env. A regular expression to match logging-related environment variables. Used for advanced [log tag options](/engine/admin/logging/log_tags/). |
| `env-regex` | optional | Similar to and compatible with env. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). |
If a collision occurs between label and env keys, the value of the env takes
precedence. Each option adds additional fields to the attributes of a logging
@ -68,7 +68,8 @@ message.
Below is an example of the logging options required to log to journald.
```bash
$ docker run --log-driver=journald \
$ docker run \
--log-driver=journald \
--log-opt labels=location \
--log-opt env=TEST \
--env "TEST=false" \

14
config/containers/logging/json-file.md
View File

@ -37,11 +37,15 @@ The following example sets the log driver to `json-file` and sets the `max-size`
}
}
```
**Note**: `log-opts` configuration options in the `daemon.json` configuration
file must be provided as strings. Boolean and numeric values (such as the value
for `max-file` in the example above) must therefore be enclosed in quotes (`"`).
Restart Docker for the changes to take effect for newly created containers. Existing containers do not use the new logging configuration.
> **Note**
>
> `log-opts` configuration options in the `daemon.json` configuration file must
> be provided as strings. Boolean and numeric values (such as the value for
> `max-file` in the example above) must therefore be enclosed in quotes (`"`).
Restart Docker for the changes to take effect for newly created containers.
Existing containers do not use the new logging configuration.
You can set the logging driver for a specific container by using the
`--log-driver` flag to `docker container create` or `docker run`:
@ -57,7 +61,7 @@ $ docker run \
The `json-file` logging driver supports the following logging options:
| Option | Description | Example value |
|:------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------|
|:---------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------|
| `max-size` | The maximum size of the log before it is rolled. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`). Defaults to -1 (unlimited). | `--log-opt max-size=10m` |
| `max-file` | The maximum number of log files that can be present. If rolling the logs creates excess files, the oldest file is removed. **Only effective when `max-size` is also set.** A positive integer. Defaults to 1. | `--log-opt max-file=3` |
| `labels` | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon accepts. Used for advanced [log tag options](log_tags.md). | `--log-opt labels=production_status,geo` |

12
config/containers/logging/local.md
View File

@ -15,10 +15,12 @@ By default, the `local` driver preserves 100MB of log messages per container and
uses automatic compression to reduce the size on disk. The 100MB default value is based on a 20M default size
for each file and a default count of 5 for the number of such files (to account for log rotation).
> *Note*: the `local` logging driver currently uses file-based storage. The
> file-format and storage mechanism are designed to be exclusively accessed by
> the Docker daemon, and should not be used by external tools as the
> implementation may change in future releases.
> *Note*
>
> The `local` logging driver uses file-based storage. The file-format and
> storage mechanism are designed to be exclusively accessed by the Docker
> daemon, and should not be used by external tools as the implementation may
> change in future releases.
## Usage
@ -57,7 +59,7 @@ $ docker run \
The `local` logging driver supports the following logging options:
| Option | Description | Example value |
|:------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------|
|:------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------|
| `max-size` | The maximum size of the log before it is rolled. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`). Defaults to 20m. | `--log-opt max-size=10m` |
| `max-file` | The maximum number of log files that can be present. If rolling the logs creates excess files, the oldest file is removed. A positive integer. Defaults to 5. | `--log-opt max-file=3` |
| `compress` | Toggle compression of rotated log files. Enabled by default. | `--log-opt compress=false` |

15
config/containers/logging/splunk.md
View File

@ -36,9 +36,11 @@ The daemon.json file is located in `/etc/docker/` on Linux hosts or
configuring Docker using `daemon.json`, see
[daemon.json](/engine/reference/commandline/dockerd.md#daemon-configuration-file).
> **Note**: `log-opt` configuration options in the `daemon.json` configuration
> file must be provided as strings. Boolean and numeric values (such as the value
> for `splunk-gzip` or `splunk-gzip-level`) must therefore be enclosed in quotes
> **Note**
>
> `log-opts` configuration options in the `daemon.json` configuration file must
> be provided as strings. Boolean and numeric values (such as the value for
> `splunk-gzip` or `splunk-gzip-level`) must therefore be enclosed in quotes
> (`"`).
To use the `splunk` driver for a specific container, use the commandline flags
@ -60,7 +62,7 @@ The following properties let you configure the splunk logging driver.
| Option | Required | Description |
|:----------------------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `splunk-token` | required | Splunk HTTP Event Collector token. |
| `splunk-url` | required | Path to your Splunk Enterprise, self-service Splunk Cloud instance, or Splunk Cloud managed cluster (including port and scheme used by HTTP Event Collector) in one of the following formats: `https://your_splunk_instance:8088` or `https://input-prd-p-XXXXXXX.cloud.splunk.com:8088` or `https://http-inputs-XXXXXXXX.splunkcloud.com`. |
| `splunk-url` | required | Path to your Splunk Enterprise, self-service Splunk Cloud instance, or Splunk Cloud managed cluster (including port and scheme used by HTTP Event Collector) in one of the following formats: `https://your_splunk_instance:8088`, `https://input-prd-p-XXXXXXX.cloud.splunk.com:8088`, or `https://http-inputs-XXXXXXXX.splunkcloud.com`. |
| `splunk-source` | optional | Event source. |
| `splunk-sourcetype` | optional | Event source type. |
| `splunk-index` | optional | Event index. |
@ -90,7 +92,8 @@ automatically generated by Splunk certificates.
{% raw %}
```bash
$ docker run --log-driver=splunk \
$ docker run \
--log-driver=splunk \
--log-opt splunk-token=176FCEBF-4CF5-4EDF-91BC-703796522D20 \
--log-opt splunk-url=https://splunkhost:8088 \
--log-opt splunk-capath=/path/to/cert/cacert.pem \
@ -175,7 +178,7 @@ To format messages as `raw`, set `--log-opt splunk-format=raw`. Attributes
(environment variables and labels) and tags are prefixed to the message. For
example:
```none
```console
MyImage/MyContainer env1=val1 label1=label1 my message
MyImage/MyContainer env1=val1 label1=label1 {"foo": "bar"}
```

10
config/containers/logging/syslog.md
View File

@ -55,9 +55,11 @@ this example uses UDP.
Restart Docker for the changes to take effect.
> **Note**: `log-opt` configuration options in the `daemon.json` configuration
> file must be provided as strings. Numeric and boolean values (such as the value
> for `syslog-tls-skip-verify`) must therefore be enclosed in quotes (`"`).
> **Note**
>
> `log-opts` configuration options in the `daemon.json` configuration file must
> be provided as strings. Numeric and boolean values (such as the value for
> `syslog-tls-skip-verify`) must therefore be enclosed in quotes (`"`).
You can set the logging driver for a specific container by using the
`--log-driver` flag to `docker container create` or `docker run`:
@ -77,7 +79,7 @@ container by adding a `--log-opt <key>=<value>` flag for each option when
starting the container.
| Option | Description | Example value |
|:-------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|:-------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------|
| `syslog-address` | The address of an external `syslog` server. The URI specifier may be `[tcp|udp|tcp+tls]://host:port`, `unix://path`, or `unixgram://path`. If the transport is `tcp`, `udp`, or `tcp+tls`, the default port is `514`. | `--log-opt syslog-address=tcp+tls://192.168.1.3:514`, `--log-opt syslog-address=unix:///tmp/syslog.sock` |
| `syslog-facility` | The `syslog` facility to use. Can be the number or name for any valid `syslog` facility. See the [syslog documentation](https://tools.ietf.org/html/rfc5424#section-6.2.1). | `--log-opt syslog-facility=daemon` |
| `syslog-tls-ca-cert` | The absolute path to the trust certificates signed by the CA. **Ignored if the address protocol is not `tcp+tls`.** | `--log-opt syslog-tls-ca-cert=/etc/ca-certificates/custom/ca.pem` |

23
config/containers/resource_constraints.md
View File

@ -19,7 +19,7 @@ check for support, you can use the
is disabled in your kernel, you may see a warning at the end of the output like
the following:
```none
```console
WARNING: No swap limit support
```
@ -209,11 +209,11 @@ realtime scheduler, for tasks which cannot use the CFS scheduler. You need to
before you can [configure the Docker daemon](#configure-the-docker-daemon) or
[configure individual containers](#configure-individual-containers).
>**Warning**:
>CPU scheduling and prioritization are advanced kernel-level
features. Most users do not need to change these values from their defaults.
Setting these values incorrectly can cause your host system to become unstable
or unusable.
> **Warning**
>
> CPU scheduling and prioritization are advanced kernel-level features. Most
> users do not need to change these values from their defaults. Setting these
> values incorrectly can cause your host system to become unstable or unusable.
{:.warning}
#### Configure the host machine's kernel
@ -251,7 +251,8 @@ The following example command sets each of these three flags on a `debian:jessie
container.
```bash
$ docker run -it --cpu-rt-runtime=950000 \
$ docker run -it \
--cpu-rt-runtime=950000 \
--ulimit rtprio=99 \
--cap-add=sys_nice \
debian:jessie
@ -331,15 +332,17 @@ $ docker run -it --rm --gpus device=0,2 nvidia-smi
Exposes the first and third GPUs.
> **Note**: NVIDIA GPUs can only be accessed by systems running a single engine.
> **Note**
>
> NVIDIA GPUs can only be accessed by systems running a single engine.
#### Set NVIDIA capabilities
You can set capabilities manually. For example, on Ubuntu you can run the
following:
```
docker run --gpus 'all,capabilities=utility' --rm ubuntu nvidia-smi
```bash
$ docker run --gpus 'all,capabilities=utility' --rm ubuntu nvidia-smi
```
This enables the `utility` driver capability which adds the `nvidia-smi` tool to

16
config/containers/start-containers-automatically.md
View File

@ -64,8 +64,11 @@ Docker depend on Docker containers, you can use a process manager such as
[systemd](http://freedesktop.org/wiki/Software/systemd/), or
[supervisor](http://supervisord.org/) instead.
> **Warning**: Do not try to combine Docker restart policies with host-level
> process managers, because this creates conflicts.
> **Warning**
>
> Do not try to combine Docker restart policies with host-level process managers,
> because this creates conflicts.
{:.warning}
To use a process manager, configure it to start your container or service using
the same `docker start` or `docker service` command you would normally use to
@ -77,7 +80,10 @@ process manager for more details.
Process managers can also run within the container to check whether a process is
running and starts/restart it if not.
> **Warning**: These are not Docker-aware and just monitor operating system processes within the container.
> **Warning**
>
> Docker does not recommend this approach, because it is platform-dependent and even differs within different versions of a given Linux distribution.
> These are not Docker-aware and just monitor operating system processes within
> the container. Docker does not recommend this approach, because it is
> platform-dependent and even differs within different versions of a given Linux
> distribution.
{:.warning}