mirror of https://github.com/docker/docs.git
engine-freshness (#18953)
* engine-freshness * review edits * review edits * review edits
This commit is contained in:
Allie Sadler
GitHub
parent
937041314e
commit
02dbedab22
|
|
@ -11,12 +11,12 @@ aliases:
|
|||
|
||||
There are four major areas to consider when reviewing Docker security:
|
||||
|
||||
- the intrinsic security of the kernel and its support for
|
||||
namespaces and cgroups;
|
||||
- the attack surface of the Docker daemon itself;
|
||||
- loopholes in the container configuration profile, either by default,
|
||||
- The intrinsic security of the kernel and its support for
|
||||
namespaces and cgroups
|
||||
- The attack surface of the Docker daemon itself
|
||||
- Loopholes in the container configuration profile, either by default,
|
||||
or when customized by users.
|
||||
- the "hardening" security features of the kernel and how they
|
||||
- The "hardening" security features of the kernel and how they
|
||||
interact with containers.
|
||||
|
||||
## Kernel namespaces
|
||||
|
|
@ -26,18 +26,18 @@ similar security features. When you start a container with
|
|||
`docker run`, behind the scenes Docker creates a set of namespaces and control
|
||||
groups for the container.
|
||||
|
||||
**Namespaces provide the first and most straightforward form of
|
||||
isolation**: processes running within a container cannot see, and even
|
||||
Namespaces provide the first and most straightforward form of
|
||||
isolation. Processes running within a container cannot see, and even
|
||||
less affect, processes running in another container, or in the host
|
||||
system.
|
||||
|
||||
**Each container also gets its own network stack**, meaning that a
|
||||
Each container also gets its own network stack, meaning that a
|
||||
container doesn't get privileged access to the sockets or interfaces
|
||||
of another container. Of course, if the host system is setup
|
||||
accordingly, containers can interact with each other through their
|
||||
respective network interfaces — just like they can interact with
|
||||
external hosts. When you specify public ports for your containers or use
|
||||
[*links*](../../network/links.md)
|
||||
[links](../../network/links.md)
|
||||
then IP traffic is allowed between containers. They can ping each other,
|
||||
send/receive UDP packets, and establish TCP connections, but that can be
|
||||
restricted if necessary. From a network architecture point of view, all
|
||||
|
|
@ -60,7 +60,7 @@ in 2005, so both the design and the implementation are pretty mature.
|
|||
|
||||
## Control groups
|
||||
|
||||
Control Groups are another key component of Linux Containers. They
|
||||
Control Groups are another key component of Linux containers. They
|
||||
implement resource accounting and limiting. They provide many
|
||||
useful metrics, but they also help ensure that each container gets
|
||||
its fair share of memory, CPU, disk I/O; and, more importantly, that a
|
||||
|
|
@ -84,8 +84,8 @@ Docker daemon. This daemon requires `root` privileges unless you opt-in
|
|||
to [Rootless mode](rootless.md), and you should therefore be aware of
|
||||
some important details.
|
||||
|
||||
First of all, **only trusted users should be allowed to control your
|
||||
Docker daemon**. This is a direct consequence of some powerful Docker
|
||||
First of all, only trusted users should be allowed to control your
|
||||
Docker daemon. This is a direct consequence of some powerful Docker
|
||||
features. Specifically, Docker allows you to share a directory between
|
||||
the Docker host and a guest container; and it allows you to do so
|
||||
without limiting the access rights of the container. This means that you
|
||||
|
|
@ -147,9 +147,7 @@ fine-grained access control system. Processes (like web servers) that
|
|||
just need to bind on a port below 1024 do not need to run as root: they
|
||||
can just be granted the `net_bind_service` capability instead. And there
|
||||
are many other capabilities, for almost all the specific areas where root
|
||||
privileges are usually needed.
|
||||
|
||||
This means a lot for container security; let's see why!
|
||||
privileges are usually needed. This means a lot for container security.
|
||||
|
||||
Typical servers run several processes as `root`, including the SSH daemon,
|
||||
`cron` daemon, logging daemons, kernel modules, network configuration tools,
|
||||
|
|
@ -157,34 +155,33 @@ and more. A container is different, because almost all of those tasks are
|
|||
handled by the infrastructure around the container:
|
||||
|
||||
- SSH access are typically managed by a single server running on
|
||||
the Docker host;
|
||||
the Docker host
|
||||
- `cron`, when necessary, should run as a user
|
||||
process, dedicated and tailored for the app that needs its
|
||||
scheduling service, rather than as a platform-wide facility;
|
||||
- log management is also typically handed to Docker, or to
|
||||
third-party services like Loggly or Splunk;
|
||||
- hardware management is irrelevant, meaning that you never need to
|
||||
scheduling service, rather than as a platform-wide facility
|
||||
- Log management is also typically handed to Docker, or to
|
||||
third-party services like Loggly or Splunk
|
||||
- Hardware management is irrelevant, meaning that you never need to
|
||||
run `udevd` or equivalent daemons within
|
||||
containers;
|
||||
- network management happens outside of the containers, enforcing
|
||||
containers
|
||||
- Network management happens outside of the containers, enforcing
|
||||
separation of concerns as much as possible, meaning that a container
|
||||
should never need to perform `ifconfig`,
|
||||
`route`, or ip commands (except when a container
|
||||
is specifically engineered to behave like a router or firewall, of
|
||||
course).
|
||||
course)
|
||||
|
||||
This means that in most cases, containers do not need "real" root
|
||||
privileges *at all*. And therefore, containers can run with a reduced
|
||||
privileges at all* And therefore, containers can run with a reduced
|
||||
capability set; meaning that "root" within a container has much less
|
||||
privileges than the real "root". For instance, it is possible to:
|
||||
|
||||
- deny all "mount" operations;
|
||||
- deny access to raw sockets (to prevent packet spoofing);
|
||||
- deny access to some filesystem operations, like creating new device
|
||||
- Deny all "mount" operations
|
||||
- Deny access to raw sockets (to prevent packet spoofing)
|
||||
- Deny access to some filesystem operations, like creating new device
|
||||
nodes, changing the owner of files, or altering attributes (including
|
||||
the immutable flag);
|
||||
- deny module loading;
|
||||
- and many others.
|
||||
the immutable flag)
|
||||
- Deny module loading
|
||||
|
||||
This means that even if an intruder manages to escalate to root within a
|
||||
container, it is much harder to do serious damage, or to escalate
|
||||
|
|
@ -209,9 +206,9 @@ capability removal, or less secure through the addition of capabilities.
|
|||
The best practice for users would be to remove all capabilities except
|
||||
those explicitly required for their processes.
|
||||
|
||||
## Docker Content Trust Signature Verification
|
||||
## Docker Content Trust signature verification
|
||||
|
||||
The Docker Engine can be configured to only run signed images. The Docker Content
|
||||
Docker Engine can be configured to only run signed images. The Docker Content
|
||||
Trust signature verification feature is built directly into the `dockerd` binary.
|
||||
This is configured in the Dockerd configuration file.
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,9 @@ Docker automatically generates and loads a default profile for containers named
|
|||
`docker-default`. The Docker binary generates this profile in `tmpfs` and then
|
||||
loads it into the kernel.
|
||||
|
||||
> **Note**: This profile is used on containers, _not_ on the Docker Daemon.
|
||||
> **Note**
|
||||
>
|
||||
> This profile is used on containers, not on the Docker daemon.
|
||||
|
||||
A profile for the Docker Engine daemon exists but it is not currently installed
|
||||
with the `deb` packages. If you are interested in the source for the daemon
|
||||
|
|
@ -44,7 +46,7 @@ To load a new profile into AppArmor for use with containers:
|
|||
$ apparmor_parser -r -W /path/to/your_profile
|
||||
```
|
||||
|
||||
Then, run the custom profile with `--security-opt` like so:
|
||||
Then, run the custom profile with `--security-opt`:
|
||||
|
||||
```console
|
||||
$ docker run --rm -it --security-opt apparmor=your_profile hello-world
|
||||
|
|
@ -193,7 +195,7 @@ profile docker-nginx flags=(attach_disconnected,mediate_deleted) {
|
|||
```
|
||||
|
||||
|
||||
Congrats! You just deployed a container secured with a custom apparmor profile!
|
||||
You just deployed a container secured with a custom apparmor profile.
|
||||
|
||||
|
||||
## Debug AppArmor
|
||||
|
|
@ -213,7 +215,7 @@ looks like the following:
|
|||
```
|
||||
|
||||
In the above example, you can see `profile=/usr/bin/docker`. This means the
|
||||
user has the `docker-engine` (Docker Engine Daemon) profile loaded.
|
||||
user has the `docker-engine` (Docker Engine daemon) profile loaded.
|
||||
|
||||
Look at another log line:
|
||||
|
||||
|
|
@ -266,14 +268,14 @@ and auditing in `dmesg` anything outside the bounds of the `docker-default`
|
|||
profile.
|
||||
|
||||
The output above also shows the `/usr/bin/docker` (Docker Engine daemon) profile
|
||||
is running in `complain` mode. This means AppArmor _only_ logs to `dmesg`
|
||||
is running in `complain` mode. This means AppArmor only logs to `dmesg`
|
||||
activity outside the bounds of the profile. (Except in the case of Ubuntu
|
||||
Trusty, where some interesting behaviors are enforced.)
|
||||
|
||||
## Contribute Docker's AppArmor code
|
||||
## Contribute to Docker's AppArmor code
|
||||
|
||||
Advanced users and package managers can find a profile for `/usr/bin/docker`
|
||||
(Docker Engine Daemon) underneath
|
||||
(Docker Engine daemon) underneath
|
||||
[contrib/apparmor](https://github.com/moby/moby/tree/master/contrib/apparmor)
|
||||
in the Docker Engine source repository.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ to have the Docker client and the daemon communicate securely over HTTPS. TLS e
|
|||
|
||||
This article demonstrates how to ensure the traffic between the Docker registry
|
||||
server and the Docker daemon (a client of the registry server) is encrypted and
|
||||
properly authenticated using *certificate-based client-server authentication*.
|
||||
properly authenticated using certificate-based client-server authentication.
|
||||
|
||||
We show you how to install a Certificate Authority (CA) root certificate
|
||||
for the registry and how to set the client TLS certificate for verification.
|
||||
|
|
@ -36,7 +36,8 @@ The presence of one or more `<filename>.key/cert` pairs indicates to Docker
|
|||
that there are custom certificates required for access to the desired
|
||||
repository.
|
||||
|
||||
> **Note**:
|
||||
> **Note**
|
||||
>
|
||||
> If multiple certificates exist, each is tried in alphabetical
|
||||
> order. If there is a 4xx-level or 5xx-level authentication error, Docker
|
||||
> continues to try with the next certificate.
|
||||
|
|
@ -67,7 +68,8 @@ $ openssl genrsa -out client.key 4096
|
|||
$ openssl req -new -x509 -text -key client.key -out client.cert
|
||||
```
|
||||
|
||||
> **Note**:
|
||||
> **Note**
|
||||
>
|
||||
> These TLS commands only generate a working set of certificates on Linux.
|
||||
> The version of OpenSSL in macOS is incompatible with the type of
|
||||
> certificate Docker requires.
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ These arguments are blocked by `CAP_NET_ADMIN`, which Docker does not allow by
|
|||
default.
|
||||
|
||||
|
||||
Bugs *not* mitigated:
|
||||
Bugs not mitigated:
|
||||
|
||||
* [CVE-2015-3290](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-3290),
|
||||
[5157](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-5157): Bugs in
|
||||
|
|
|
|||
|
|
@ -85,18 +85,20 @@ In the daemon mode, it only allows connections from clients
|
|||
authenticated by a certificate signed by that CA. In the client mode,
|
||||
it only connects to servers with a certificate signed by that CA.
|
||||
|
||||
> Advanced topic
|
||||
> **Important**
|
||||
>
|
||||
> Using TLS and managing a CA is an advanced topic. Please familiarize yourself
|
||||
> Using TLS and managing a CA is an advanced topic. Familiarize yourself
|
||||
> with OpenSSL, x509, and TLS before using it in production.
|
||||
{ .important }
|
||||
|
||||
### Create a CA, server and client keys with OpenSSL
|
||||
|
||||
> **Note**: Replace all instances of `$HOST` in the following example with the
|
||||
> **Note**
|
||||
>
|
||||
> Replace all instances of `$HOST` in the following example with the
|
||||
> DNS name of your Docker daemon's host.
|
||||
|
||||
First, on the **Docker daemon's host machine**, generate CA private and public keys:
|
||||
First, on the Docker daemon's host machine, generate CA private and public keys:
|
||||
|
||||
```console
|
||||
$ openssl genrsa -aes256 -out ca-key.pem 4096
|
||||
|
|
@ -129,7 +131,9 @@ Now that you have a CA, you can create a server key and certificate
|
|||
signing request (CSR). Make sure that "Common Name" matches the hostname you use
|
||||
to connect to Docker:
|
||||
|
||||
> **Note**: Replace all instances of `$HOST` in the following example with the
|
||||
> **Note**
|
||||
>
|
||||
> Replace all instances of `$HOST` in the following example with the
|
||||
> DNS name of your Docker daemon's host.
|
||||
|
||||
```console
|
||||
|
|
@ -177,7 +181,9 @@ Docker clients.
|
|||
For client authentication, create a client key and certificate signing
|
||||
request:
|
||||
|
||||
> **Note**: For simplicity of the next couple of steps, you may perform this
|
||||
> **Note**
|
||||
>
|
||||
> For simplicity of the next couple of steps, you may perform this
|
||||
> step on the Docker daemon's host machine as well.
|
||||
|
||||
```console
|
||||
|
|
@ -245,13 +251,16 @@ $ dockerd \
|
|||
To connect to Docker and validate its certificate, provide your client keys,
|
||||
certificates and trusted CA:
|
||||
|
||||
> Run it on the client machine
|
||||
> **Tip**
|
||||
>
|
||||
> This step should be run on your Docker client machine. As such, you
|
||||
> need to copy your CA certificate, your server certificate, and your client
|
||||
> certificate to that machine.
|
||||
{ .tip }
|
||||
|
||||
> **Note**: Replace all instances of `$HOST` in the following example with the
|
||||
> **Note**
|
||||
>
|
||||
> Replace all instances of `$HOST` in the following example with the
|
||||
> DNS name of your Docker daemon's host.
|
||||
|
||||
```console
|
||||
|
|
@ -262,10 +271,12 @@ $ docker --tlsverify \
|
|||
-H=$HOST:2376 version
|
||||
```
|
||||
|
||||
> **Note**:
|
||||
> **Note**
|
||||
>
|
||||
> Docker over TLS should run on TCP port 2376.
|
||||
|
||||
> **Warning**:
|
||||
> **Warning**
|
||||
>
|
||||
> As shown in the example above, you don't need to run the `docker` client
|
||||
> with `sudo` or the `docker` group when you use certificate authentication.
|
||||
> That means anyone with the keys can give any instructions to your Docker
|
||||
|
|
|
|||
|
|
@ -45,7 +45,10 @@ testuser:231072:65536
|
|||
|
||||
### Distribution-specific hint
|
||||
|
||||
> Note: We recommend that you use the Ubuntu kernel.
|
||||
> **Tip**
|
||||
>
|
||||
> We recommend that you use the Ubuntu kernel.
|
||||
{ .tip }
|
||||
|
||||
{{< tabs >}}
|
||||
{{< tab name="Ubuntu" >}}
|
||||
|
|
@ -431,7 +434,8 @@ $ mkdir -p $XDG_RUNTIME_DIR
|
|||
$ dockerd-rootless.sh
|
||||
```
|
||||
|
||||
> **Note**:
|
||||
> **Note**
|
||||
>
|
||||
> You must remove the directory every time you log out.
|
||||
|
||||
On a systemd host, log into the host using `pam_systemd` (see below).
|
||||
|
|
|
|||
|
|
@ -15,10 +15,10 @@ aliases:
|
|||
- /notary/reference/common-configs/
|
||||
---
|
||||
|
||||
When transferring data among networked systems, *trust* is a central concern. In
|
||||
When transferring data among networked systems, trust is a central concern. In
|
||||
particular, when communicating over an untrusted medium such as the internet, it
|
||||
is critical to ensure the integrity and the publisher of all the data a system
|
||||
operates on. You use the Docker Engine to push and pull images (data) to a
|
||||
operates on. You use Docker Engine to push and pull images (data) to a
|
||||
public or private registry. Content trust gives you the ability to verify both
|
||||
the integrity and the publisher of all the data received from a registry over
|
||||
any channel.
|
||||
|
|
@ -86,16 +86,16 @@ Trust for an image tag is managed through the use of signing keys. A key set is
|
|||
created when an operation using DCT is first invoked. A key set consists
|
||||
of the following classes of keys:
|
||||
|
||||
- an offline key that is the root of DCT for an image tag
|
||||
- repository or tagging keys that sign tags
|
||||
- server-managed keys such as the timestamp key, which provides freshness
|
||||
- An offline key that is the root of DCT for an image tag
|
||||
- Repository or tagging keys that sign tags
|
||||
- Server-managed keys such as the timestamp key, which provides freshness
|
||||
security guarantees for your repository
|
||||
|
||||
The following image depicts the various signing keys and their relationships:
|
||||
|
||||
|
||||
|
||||
> **WARNING**
|
||||
> **Warning**
|
||||
>
|
||||
>The root key once lost is not recoverable. If you lose any other key, send an email to [Docker Hub Support](mailto:hub-support@docker.com). This loss also requires manual intervention from every
|
||||
consumer that used a signed tag from this repository prior to the loss.
|
||||
|
|
@ -106,7 +106,7 @@ to create new repositories, it is a good idea to store it offline in hardware.
|
|||
For details on securing, and backing up your keys, make sure you
|
||||
read how to [manage keys for DCT](trust_key_mng.md).
|
||||
|
||||
## Signing Images with Docker Content Trust
|
||||
## Signing images with Docker Content Trust
|
||||
|
||||
Within the Docker CLI we can sign and push a container image with the
|
||||
`$ docker trust` command syntax. This is built on top of the Notary feature
|
||||
|
|
@ -218,7 +218,7 @@ Enter passphrase for signer key with ID 8ae710e:
|
|||
Successfully deleted signature for registry.example.com/admin/demo:1
|
||||
```
|
||||
|
||||
## Client Enforcement with Docker Content Trust
|
||||
## Client enforcement with Docker Content Trust
|
||||
|
||||
Content trust is disabled by default in the Docker Client. To enable
|
||||
it, set the `DOCKER_CONTENT_TRUST` environment variable to `1`. This prevents
|
||||
|
|
|
|||
|
|
@ -8,14 +8,18 @@ The easiest way to deploy Notary Server is by using Docker Compose. To follow th
|
|||
|
||||
1. Clone the Notary repository.
|
||||
|
||||
git clone https://github.com/theupdateframework/notary.git
|
||||
```consolse
|
||||
$ git clone https://github.com/theupdateframework/notary.git
|
||||
```
|
||||
|
||||
2. Build and start Notary Server with the sample certificates.
|
||||
|
||||
docker compose up -d
|
||||
```consolse
|
||||
$ docker compose up -d
|
||||
```
|
||||
|
||||
For more detailed documentation about how to deploy Notary Server, see the [instructions to run a Notary service](https://github.com/theupdateframework/notary/blob/master/docs/running_a_service.md) as well as [the Notary repository](https://github.com/theupdateframework/notary) for more information.
|
||||
|
||||
For more detailed documentation about how to deploy Notary Server, see the [instructions to run a Notary service](https://github.com/theupdateframework/notary/blob/master/docs/running_a_service.md) as well as [the Notary repository](https://github.com/theupdateframework/notary) for more information.
|
||||
3. Make sure that your Docker or Notary client trusts Notary Server's certificate before you try to interact with the Notary server.
|
||||
|
||||
See the instructions for [Docker](../../reference/commandline/cli.md#notary) or
|
||||
|
|
|
|||
|
|
@ -8,9 +8,8 @@ It is very common for Docker Content Trust to be built into existing automation
|
|||
systems. To allow tools to wrap Docker and push trusted content, there are
|
||||
environment variables that can be passed through to the client.
|
||||
|
||||
This guide follows the steps as described
|
||||
[here](index.md#signing-images-with-docker-content-trust) so please read
|
||||
that and understand its prerequisites.
|
||||
This guide follows the steps as described in
|
||||
[Signing images with Docker Content Trust](index.md#signing-images-with-docker-content-trust). Make sure you understand and follow the prerequisites.
|
||||
|
||||
When working directly with the Notary client, it uses its [own set of environment variables](https://github.com/theupdateframework/notary/blob/master/docs/reference/client-config.md#environment-variables-optional).
|
||||
|
||||
|
|
@ -30,7 +29,7 @@ Successfully imported key from delegation.key
|
|||
|
||||
## Add a delegation public key
|
||||
|
||||
If you initialising a repository at the same time as adding a Delegation
|
||||
If you initialize a repository at the same time as adding a delegation
|
||||
public key, then you will need to use the local Notary Canonical Root Key's
|
||||
passphrase to create the repositories trust data. If the repository has already
|
||||
been initiated then you only need the repositories passphrase.
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ Fortunately when using the `$ docker trust` commands, we will automatically
|
|||
initialize a repository, manage the repository keys, and add a collaborator's key to the
|
||||
`targets/releases` delegation via `docker trust signer add`.
|
||||
|
||||
## Configuring the Docker Client
|
||||
## Configuring the Docker client
|
||||
|
||||
By default, the `$ docker trust` commands expect the notary server URL to be the
|
||||
same as the registry URL specified in the image tag (following a similar logic to
|
||||
|
|
@ -74,7 +74,7 @@ you are not authorized to perform this operation: server returned 401.
|
|||
Failed to add signer to: registry.example.com/user/repo
|
||||
```
|
||||
|
||||
## Configuring the Notary Client
|
||||
## Configuring the Notary client
|
||||
|
||||
Some of the more advanced features of DCT require the Notary CLI. To install and
|
||||
configure the Notary CLI:
|
||||
|
|
@ -99,13 +99,13 @@ For more detailed information about how to use notary outside of the
|
|||
Docker Content Trust use cases, refer to the Notary CLI documentation
|
||||
[here](https://github.com/theupdateframework/notary/blob/master/docs/command_reference.md)
|
||||
|
||||
## Creating Delegation Keys
|
||||
## Creating delegation keys
|
||||
|
||||
A prerequisite to adding your first contributor is a pair of delegation keys.
|
||||
These keys can either be generated locally using `$ docker trust`, generated by
|
||||
a certificate authority.
|
||||
|
||||
### Using Docker Trust to Generate Keys
|
||||
### Using Docker Trust to generate keys
|
||||
|
||||
Docker trust has a built-in generator for a delegation key pair,
|
||||
`$ docker trust generate <name>`. Running this command will automatically load
|
||||
|
|
@ -120,7 +120,7 @@ Repeat passphrase for new jeff key with ID 9deed25:
|
|||
Successfully generated and loaded private key. Corresponding public key available: /home/ubuntu/Documents/mytrustdir/jeff.pub
|
||||
```
|
||||
|
||||
### Manually Generating Keys
|
||||
### Manually generating keys
|
||||
|
||||
If you need to manually generate a private key (either RSA or ECDSA) and a x509
|
||||
certificate containing the public key, you can use local tools like openssl or
|
||||
|
|
@ -170,7 +170,7 @@ Repeat passphrase for new jeff key with ID 8ae710e:
|
|||
Successfully imported key from delegation.key
|
||||
```
|
||||
|
||||
### Viewing local Delegation keys
|
||||
### Viewing local delegation keys
|
||||
|
||||
To list the keys that have been imported in to the local Docker trust store we
|
||||
can use the Notary CLI.
|
||||
|
|
@ -184,9 +184,9 @@ root f6c6a4b00fefd8751f86194c7d87a3bede444540
|
|||
jeff 9deed251daa1aa6f9d5f9b752847647cf8d705da0763aa5467650d0987ed5306 /home/ubuntu/.docker/trust/private
|
||||
```
|
||||
|
||||
## Managing Delegations in a Notary Server
|
||||
## Managing delegations in a Notary Server
|
||||
|
||||
When the first Delegation is added to the Notary Server using `$ docker trust`,
|
||||
When the first delegation is added to the Notary Server using `$ docker trust`,
|
||||
we automatically initiate trust data for the repository. This includes creating
|
||||
the notary target and snapshots keys, and rotating the snapshot key to be
|
||||
managed by the notary server. More information on these keys can be found
|
||||
|
|
@ -196,9 +196,12 @@ When initiating a repository, you will need the key and the passphrase of a loca
|
|||
Notary Canonical Root Key. If you have not initiated a repository before, and
|
||||
therefore don't have a Notary root key, `$ docker trust` will create one for you.
|
||||
|
||||
> Be sure to protect and back up your [Notary Canonical Root Key](trust_key_mng.md)
|
||||
> **Important**
|
||||
>
|
||||
> Be sure to protect and back up your [Notary Canonical Root Key](trust_key_mng.md).
|
||||
{ .important }
|
||||
|
||||
### Initiating the Repository
|
||||
### Initiating the repository
|
||||
|
||||
To upload the first key to a delegation, at the same time initiating a
|
||||
repository, you can use the `$ docker trust signer add` command. This will add
|
||||
|
|
@ -254,7 +257,7 @@ targets/jeff "" <all paths> 1091060d7bfd938dfa5be703fa057974f9322a4fae
|
|||
targets/releases "" <all paths> 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 1
|
||||
```
|
||||
|
||||
### Adding Additional Signers
|
||||
### Adding additional signers
|
||||
|
||||
Docker Trust allows you to configure multiple delegations per repository,
|
||||
allowing you to manage the lifecycle of delegations. When adding additional
|
||||
|
|
@ -291,14 +294,16 @@ Administrative keys for registry.example.com/admin/demo
|
|||
Root Key: 64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7
|
||||
```
|
||||
|
||||
### Adding Keys to an Existing Delegation
|
||||
### Adding keys to an existing delegation
|
||||
|
||||
To support things like key rotation and expiring / retiring keys you can publish
|
||||
multiple contributor keys per delegation. The only prerequisite here is to make
|
||||
sure you use the same the delegation name, in this case `jeff`. Docker trust
|
||||
will automatically handle adding this new key to `targets/releases`.
|
||||
|
||||
> Note you will need the passphrase for the repository key; this would have been
|
||||
> **Note**
|
||||
>
|
||||
> You will need the passphrase for the repository key; this would have been
|
||||
> configured when you first initiated the repository.
|
||||
|
||||
```console
|
||||
|
|
@ -328,13 +333,15 @@ Administrative keys for registry.example.com/admin/demo
|
|||
Root Key: 64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7
|
||||
```
|
||||
|
||||
### Removing a Delegation
|
||||
### Removing a delegation
|
||||
|
||||
If you need to remove a delegation, including the contributor keys that are
|
||||
attached to the `targets/releases` role, you can use the
|
||||
`$ docker trust signer remove` command.
|
||||
|
||||
> Note tags that were signed by the removed delegation will need to be resigned
|
||||
> **Note**
|
||||
>
|
||||
> Tags that were signed by the removed delegation will need to be resigned
|
||||
> by an active delegation
|
||||
|
||||
```console
|
||||
|
|
@ -362,16 +369,16 @@ Successfully removed ben from registry.example.com/admin/demo
|
|||
WARN[0000] Error getting targets/releases: valid signatures did not meet threshold for targets/releases
|
||||
```
|
||||
|
||||
Resigning the delegation file is done with the `$ notary witness` command
|
||||
Resigning the delegation file is done with the `$ notary witness` command
|
||||
|
||||
```console
|
||||
$ notary witness registry.example.com/admin/demo targets/releases --publish
|
||||
```
|
||||
```console
|
||||
$ notary witness registry.example.com/admin/demo targets/releases --publish
|
||||
```
|
||||
|
||||
More information on the `$ notary witness` command can be found
|
||||
[here](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#recovering-a-delegation)
|
||||
More information on the `$ notary witness` command can be found
|
||||
[here](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#recovering-a-delegation)
|
||||
|
||||
### Removing a Contributor's Key from a Delegation
|
||||
### Removing a contributor's key from a delegation
|
||||
|
||||
As part of rotating keys for a delegation, you may want to remove an individual
|
||||
key but retain the delegation. This can be done with the Notary CLI.
|
||||
|
|
@ -429,7 +436,7 @@ and the role specific to that signer `targets/<name>`.
|
|||
targets/releases "" <all paths> 8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9 1
|
||||
```
|
||||
|
||||
### Removing a local Delegation Private Key
|
||||
### Removing a local delegation private key
|
||||
|
||||
As part of rotating delegation keys, you may need to remove a local delegation
|
||||
key from the local Docker trust store. This is done with the Notary CLI, using
|
||||
|
|
@ -458,7 +465,7 @@ the `$ notary key remove` command.
|
|||
Deleted 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private.
|
||||
```
|
||||
|
||||
## Removing all trust data from a Repository
|
||||
## Removing all trust data from a repository
|
||||
|
||||
You can remove all trust data from a repository, including repository, target,
|
||||
snapshot and all delegations keys using the Notary CLI.
|
||||
|
|
|
|||
|
|
@ -23,16 +23,12 @@ the image repository:
|
|||
|
||||
- The timestamp and snapshot keys are safely generated and stored in a signing server
|
||||
that is deployed alongside the Docker registry. These keys are generated in a backend
|
||||
service that isn't directly exposed to the internet and are encrypted at rest.
|
||||
service that isn't directly exposed to the internet and are encrypted at rest. Use the Notary CLI to [manage your snapshot key locally](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#rotate-keys).
|
||||
|
||||
Delegation keys are optional, and not generated as part of the normal `docker`
|
||||
workflow. They need to be
|
||||
workflow. They need to be
|
||||
[manually generated and added to the repository](trust_delegation.md#creating-delegation-keys).
|
||||
|
||||
**Note**: Prior to Docker Engine 1.11, the snapshot key was also generated and stored
|
||||
locally client-side.
|
||||
Use the Notary CLI to [manage your snapshot key locally again](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#rotate-keys) for repositories created with newer versions of Docker.
|
||||
|
||||
## Choose a passphrase
|
||||
|
||||
The passphrases you chose for both the root key and your repository key should
|
||||
|
|
@ -47,9 +43,9 @@ All the Docker trust keys are stored encrypted using the passphrase you provide
|
|||
on creation. Even so, you should still take care of the location where you back them up.
|
||||
Good practice is to create two encrypted USB keys.
|
||||
|
||||
> **WARNING**
|
||||
> **Warning**
|
||||
>
|
||||
> It is **very important** that you back up your keys to a safe, secure location.
|
||||
> It is very important that you back up your keys to a safe, secure location.
|
||||
The loss of the repository key is recoverable, but the loss of the root key is not.
|
||||
{ .warning }
|
||||
|
||||
|
|
@ -73,14 +69,14 @@ Prior to Docker Engine 1.11, this feature was only in the experimental branch.
|
|||
|
||||
## Key loss
|
||||
|
||||
> **WARNING**
|
||||
> **Warning**
|
||||
>
|
||||
> If a publisher loses keys it means losing the ability to sign images for the repositories in
|
||||
question. If you lose a key, send an email to [Docker Hub Support](mailto:hub-support@docker.com).
|
||||
As a reminder, the loss of a root key is not recoverable.
|
||||
{ .warning }
|
||||
|
||||
This loss also requires **manual intervention** from every consumer that used a signed
|
||||
This loss also requires manual intervention from every consumer that used a signed
|
||||
tag from this repository prior to the loss.
|
||||
Image consumers get the following error for content previously downloaded from the affected repo(s):
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ impacting your production images.
|
|||
Before working through this sandbox, you should have read through the
|
||||
[trust overview](index.md).
|
||||
|
||||
### Prerequisites
|
||||
## Prerequisites
|
||||
|
||||
These instructions assume you are running in Linux or macOS. You can run
|
||||
this sandbox on a local machine or on a virtual machine. You need to
|
||||
|
|
@ -67,10 +67,10 @@ the `trustsandbox` container, the Notary server, and the Registry server.
|
|||
$ mkdir trustsandbox
|
||||
$ cd trustsandbox
|
||||
|
||||
2. Create a file called `docker-compose.yml` with your favorite editor. For example, using vim:
|
||||
2. Create a file called `compose.yml` with your favorite editor. For example, using vim:
|
||||
|
||||
$ touch docker-compose.yml
|
||||
$ vim docker-compose.yml
|
||||
$ touch compose.yml
|
||||
$ vim compose.yml
|
||||
|
||||
3. Add the following to the new file.
|
||||
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ outside of the namespace, the process is running as an unprivileged high-number
|
|||
UID on the host, which does not even map to a real user. This means the process
|
||||
has no privileges on the host system at all.
|
||||
|
||||
> Multiple ranges
|
||||
> **Note**
|
||||
>
|
||||
> It is possible to assign multiple subordinate ranges for a given user or group
|
||||
> by adding multiple non-overlapping mappings for the same user or group in the
|
||||
|
|
@ -47,7 +47,9 @@ specify an existing user and/or group, or you can specify `default`. If you
|
|||
specify `default`, a user and group `dockremap` is created and used for this
|
||||
purpose.
|
||||
|
||||
> **Warning**: Some distributions, such as RHEL and CentOS 7.3, do not
|
||||
> **Warning**
|
||||
>
|
||||
> Some distributions, such as RHEL and CentOS 7.3, do not
|
||||
> automatically add the new group to the `/etc/subuid` and `/etc/subgid` files.
|
||||
> You are responsible for editing these files and assigning non-overlapping
|
||||
> ranges, in this case. This step is covered in [Prerequisites](#prerequisites).
|
||||
|
|
@ -107,7 +109,7 @@ avoid these situations.
|
|||
avoid overlap.
|
||||
|
||||
If you want to use the `dockremap` user automatically created by Docker,
|
||||
check for the `dockremap` entry in these files **after**
|
||||
check for the `dockremap` entry in these files after
|
||||
configuring and restarting Docker.
|
||||
|
||||
3. If there are any locations on the Docker host where the unprivileged
|
||||
|
|
@ -160,7 +162,9 @@ $ dockerd --userns-remap="testuser:testuser"
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: To use the `dockremap` user and have Docker create it for you,
|
||||
> **Note**
|
||||
>
|
||||
> To use the `dockremap` user and have Docker create it for you,
|
||||
> set the value to `default` rather than `testuser`.
|
||||
|
||||
Save the file and restart Docker.
|
||||
|
|
@ -254,8 +258,8 @@ What this means is that the whole container filesystem will belong to the user s
|
|||
The following standard Docker features are incompatible with running a Docker
|
||||
daemon with user namespaces enabled:
|
||||
|
||||
- sharing PID or NET namespaces with the host (`--pid=host` or `--network=host`).
|
||||
- external (volume or storage) drivers which are unaware or incapable of using
|
||||
- Sharing PID or NET namespaces with the host (`--pid=host` or `--network=host`).
|
||||
- External (volume or storage) drivers which are unaware or incapable of using
|
||||
daemon user mappings.
|
||||
- Using the `--privileged` mode flag on `docker run` without also specifying
|
||||
`--userns=host`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue