engine-freshness (#18953)

* engine-freshness

* review edits

* review edits

* review edits

content/engine/security/_index.md

@@ -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
+ - The intrinsic security of the kernel and its support for
-   namespaces and cgroups;
+   namespaces and cgroups
- - the attack surface of the Docker daemon itself;
+ - The attack surface of the Docker daemon itself
- - loopholes in the container configuration profile, either by default,
+ - 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
+Namespaces provide the first and most straightforward form of
-isolation**: processes running within a container cannot see, and even
+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
+First of all, only trusted users should be allowed to control your
-Docker daemon**. This is a direct consequence of some powerful Docker
+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.
+privileges are usually needed. This means a lot for container security.
-
-This means a lot for container security; let's see why!
 
 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;
+   scheduling service, rather than as a platform-wide facility
- - log management is also typically handed to Docker, or to
+ - Log management is also typically handed to Docker, or to
-   third-party services like Loggly or Splunk;
+   third-party services like Loggly or Splunk
- - hardware management is irrelevant, meaning that you never need to
+ - Hardware management is irrelevant, meaning that you never need to
    run `udevd` or equivalent daemons within
-   containers;
+   containers
- - network management happens outside of the containers, enforcing
+ - 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 all "mount" operations
- - deny access to raw sockets (to prevent packet spoofing);
+ - Deny access to raw sockets (to prevent packet spoofing)
- - deny access to some filesystem operations, like creating new device
+ - Deny access to some filesystem operations, like creating new device
    nodes, changing the owner of files, or altering attributes (including
-   the immutable flag);
+   the immutable flag)
- - deny module loading;
+ - Deny module loading
- - and many others.
 
 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. 
 

content/engine/security/apparmor.md

@@ -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.
 

content/engine/security/certificates.md

@@ -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.

content/engine/security/non-events.md

@@ -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

content/engine/security/protect-access.md

@@ -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

content/engine/security/rootless.md

@@ -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).

content/engine/security/trust/_index.md

@@ -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
+- An offline key that is the root of DCT for an image tag
-- repository or tagging keys that sign tags
+- Repository or tagging keys that sign tags
-- server-managed keys such as the timestamp key, which provides freshness
+- 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:
 
 ![Content Trust components](images/trust_components.png)
 
-> **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

content/engine/security/trust/deploying_notary.md

@@ -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.
+
 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

content/engine/security/trust/trust_automation.md

@@ -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 
+This guide follows the steps as described in
-[here](index.md#signing-images-with-docker-content-trust) so please read 
+[Signing images with Docker Content Trust](index.md#signing-images-with-docker-content-trust). Make sure you understand and follow the prerequisites.
-that and understand its 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. 

content/engine/security/trust/trust_delegation.md

@@ -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
+   ```console
-$ notary witness registry.example.com/admin/demo targets/releases --publish
+   $ notary witness registry.example.com/admin/demo targets/releases --publish
-```
+   ```
 
-More information on the `$ notary witness` command can be found 
+   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)
+   [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.

content/engine/security/trust/trust_key_mng.md

@@ -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
 [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):
 

content/engine/security/trust/trust_sandbox.md

@@ -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
+        $ touch compose.yml
-        $ vim docker-compose.yml
+        $ vim compose.yml
 
 3. Add the following to the new file.
 

content/engine/security/userns-remap.md

@@ -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`).
+- 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
+- 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`.