Merge pull request #1625 from moxiegirl/fix-1598

Updated per conversation with Richard

docs/insecure.md

@@ -8,57 +8,74 @@ keywords = ["registry, on-prem, images, tags, repository, distribution, insecure
 
 # Insecure Registry
 
-While it's highly recommended to secure your registry using a TLS certificate issued by a known CA, you may alternatively decide to use self-signed certificates, or even use your registry over plain http.
+While it's highly recommended to secure your registry using a TLS certificate
+issued by a known CA, you may alternatively decide to use self-signed
+certificates, or even use your registry over plain http.
 
-You have to understand the downsides in doing so, and the extra burden in configuration.
+You have to understand the downsides in doing so, and the extra burden in
+configuration.
 
 ## Deploying a plain HTTP registry
 
-> **Warning**: it's not possible to use an insecure registry with basic authentication
+> **Warning**: it's not possible to use an insecure registry with basic authentication.
 
 This basically tells Docker to entirely disregard security for your registry.
+While this is relatively easy to configure the daemon in this way, it is
+**very** insecure. It does expose your registry to trivial MITM. Only use this
+solution for isolated testing or in a tightly controlled, air-gapped
+environment.
 
-1. edit the file `/etc/default/docker` so that there is a line that reads: `DOCKER_OPTS="--insecure-registry myregistrydomain.com:5000"` (or add that to existing `DOCKER_OPTS`)
-2. restart your Docker daemon: on ubuntu, this is usually `service docker stop && service docker start`
+1. Open the `/etc/default/docker` file or `/etc/sysconfig/docker` for editing.
 
-**Pros:**
+    Depending on your operating system, your Engine daemon start options.
 
- - relatively easy to configure
+2. Edit (or add) the `DOCKER_OPTS` line and add the `--insecure-registry` flag.
 
-**Cons:**
+    This flag takes the URL of your registry, for example.
+
+    `DOCKER_OPTS="--insecure-registry myregistrydomain.com:5000"`
+
+3. Close and save the configuration file.
+
+4. Restart your Docker daemon
+
+    The command you use to restart the daemon depends on your operating system.
+    For example, on Ubuntu, this is usually the `service docker stop` and `service
+    docker start` command.
+
+5. Repeat this configuration on every Engine host that wants to access your registry.
 
- - this is **very** insecure: you are basically exposing yourself to trivial MITM, and this solution should only be used for isolated testing or in a tightly controlled, air-gapped environment
- - you have to configure every docker daemon that wants to access your registry 
 
 ## Using self-signed certificates
 
 > **Warning**: using this along with basic authentication requires to **also** trust the certificate into the OS cert store for some versions of docker (see below)
 
-Generate your own certificate:
+This is more secure than the insecure registry solution.  You must configure every docker daemon that wants to access your registry
+
+1. Generate your own certificate:
 
     mkdir -p certs && openssl req \
       -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
       -x509 -days 365 -out certs/domain.crt
 
-Be sure to use the name `myregistrydomain.com` as a CN.
+2. Be sure to use the name `myregistrydomain.com` as a CN.
 
-Use the result to [start your registry with TLS enabled](https://github.com/docker/distribution/blob/master/docs/deploying.md#get-a-certificate)
+3. Use the result to [start your registry with TLS enabled](https://github.com/docker/distribution/blob/master/docs/deploying.md#get-a-certificate)
 
-Then you have to instruct every docker daemon to trust that certificate. This is done by copying the `domain.crt` file to `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt`.
+4. Instruct every docker daemon to trust that certificate.
 
-Don't forget to restart docker after doing so.
+    This is done by copying the `domain.crt` file to `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt`.
 
-**Pros:**
+5. Don't forget to restart the Engine daemon.
 
- - more secure than the insecure registry solution
+## Troubleshooting insecure registry
 
-**Cons:**
+This sections lists some common failures and how to recover from them.
 
- - you have to configure every docker daemon that wants to access your registry
+### Failing...
 
-## Failing...
-
-Failing to configure docker and trying to pull from a registry that is not using TLS will result in the following message:
+Failing to configure the Engine daemon and trying to pull from a registry that is not using
+TLS will results in the following message:
 
 ```
 FATA[0000] Error response from daemon: v1 ping attempt failed with error:
@@ -69,22 +86,26 @@ In the case of HTTPS, if you have access to the registry's CA certificate, no ne
 simply place the CA certificate at /etc/docker/certs.d/myregistrydomain.com:5000/ca.crt
 ```
 
-## Docker still complains about the certificate when using authentication?
+### Docker still complains about the certificate when using authentication?
 
-When using authentication, some versions of docker also require you to trust the certificate at the OS level.
+When using authentication, some versions of docker also require you to trust the certificate at the OS level. Usually, on Ubuntu this is done with:
 
-Usually, on Ubuntu this is done with:
-
-    cp certs/domain.crt /usr/local/share/ca-certificates/myregistrydomain.com.crt
-    update-ca-certificates
+```bash
+$ cp certs/domain.crt /usr/local/share/ca-certificates/myregistrydomain.com.crt
+update-ca-certificates
+```
 
 ... and on Red Hat (and its derivatives) with:
 
-    cp certs/domain.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt
-    update-ca-trust
+```bash
+cp certs/domain.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt
+update-ca-trust
+```
 
 ... On some distributions, e.g. Oracle Linux 6, the Shared System Certificates feature needs to be manually enabled:
 
-    update-ca-trust enable
+```bash
+$ update-ca-trust enable
+```
 
 Now restart docker (`service docker stop && service docker start`, or any other way you use to restart docker).

docs/spec/manifest-v2-1.md

@@ -1,6 +1,10 @@
 <!--[metadata]>
 +++
-draft = true
+title = "Image Manifest V 2, Schema 1 "
+description = "image manifest for the Registry."
+keywords = ["registry, on-prem, images, tags, repository, distribution, api, advanced, manifest"]
+[menu.main]
+parent="smn_registry_ref"
 +++
 <![end-metadata]-->
 

docs/spec/manifest-v2-2.md

@@ -1,6 +1,10 @@
 <!--[metadata]>
 +++
-draft = true
+title = "Image Manifest V 2, Schema 2 "
+description = "image manifest for the Registry."
+keywords = ["registry, on-prem, images, tags, repository, distribution, api, advanced, manifest"]
+[menu.main]
+parent="smn_registry_ref"
 +++
 <![end-metadata]-->
 
@@ -10,7 +14,7 @@ This document outlines the format of of the V2 image manifest, schema version 2.
 The original (and provisional) image manifest for V2 (schema 1), was introduced
 in the Docker daemon in the [v1.3.0
 release](https://github.com/docker/docker/commit/9f482a66ab37ec396ac61ed0c00d59122ac07453)
-and is specified in the [schema 1 manifest definition](./manifest-v2-1.md)
+and is specified in the [schema 1 manifest definition](manifest-v2-1.md)
 
 This second schema version has two primary goals. The first is to allow
 multi-architecture images, through a "fat manifest" which references image