Merge pull request #897 from dmp42/5.all-ur-proxy-are-belong-to-us

Starting with recipes

docs/apache.md

@@ -0,0 +1,234 @@
+<!--[metadata]>
++++
+title = "Authenticating proxy with apache"
+description = "Restricting access to your registry using a proxy"
+keywords = ["registry, service, images, repository, authentication"]
++++
+<![end-metadata]-->
+
+# Authenticating proxy with apache
+
+## Use-case
+
+People already relying on an apache proxy to authenticate their users to other services might want to leverage it and have Registry communications tunneled through the same pipeline.
+
+Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO mechanism fronting their internal http portal.
+
+### Alternatives
+
+If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](deploying.md#native-basic-auth). 
+
+### Solution
+
+With the method presented here, you implement basic authentication for docker engines in a reverse proxy that sits in front of your registry.
+
+While we use a simple htpasswd file as an example, any other apache authentication backend should be fairly easy to implement once you are done with the exemple.
+
+We also implement push restriction (to a limited user group) for the sake of the exemple. Again, you should modify this to fit your mileage. 
+
+### Gotchas
+
+While this model gives you the ability to use whatever authentication backend you want through the secondary authentication mechanism implemented inside your proxy, it also requires that you move TLS termination from the Registry to the proxy itself.
+
+Furthermore, introducing an extra http layer in your communication pipeline will make it more complex to deploy, maintain, and debug, and will possibly create issues.
+
+## Setting things up
+
+Read again [the requirements](recipes.md#requirements).
+
+Ready?
+
+Run the following script:
+
+```
+mkdir -p auth
+mkdir -p data
+
+# This is the main apache configuration you will use
+cat <<EOF > auth/httpd.conf
+LoadModule headers_module modules/mod_headers.so
+
+LoadModule authn_file_module modules/mod_authn_file.so
+LoadModule authn_core_module modules/mod_authn_core.so
+LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
+LoadModule authz_user_module modules/mod_authz_user.so
+LoadModule authz_core_module modules/mod_authz_core.so
+LoadModule auth_basic_module modules/mod_auth_basic.so
+LoadModule access_compat_module modules/mod_access_compat.so
+
+LoadModule log_config_module modules/mod_log_config.so
+
+LoadModule ssl_module modules/mod_ssl.so
+
+LoadModule proxy_module modules/mod_proxy.so
+LoadModule proxy_http_module modules/mod_proxy_http.so
+
+LoadModule unixd_module modules/mod_unixd.so
+
+<IfModule ssl_module>
+    SSLRandomSeed startup builtin
+    SSLRandomSeed connect builtin
+</IfModule>
+
+<IfModule unixd_module>
+    User daemon
+    Group daemon
+</IfModule>
+
+ServerAdmin you@example.com
+
+ErrorLog /proc/self/fd/2
+
+LogLevel warn
+
+<IfModule log_config_module>
+    LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
+    LogFormat "%h %l %u %t \"%r\" %>s %b" common
+
+    <IfModule logio_module>
+      LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio
+    </IfModule>
+
+    CustomLog /proc/self/fd/1 common
+</IfModule>
+
+ServerRoot "/usr/local/apache2"
+
+Listen 5043
+
+<Directory />
+    AllowOverride none
+    Require all denied
+</Directory>
+
+<VirtualHost *:5043>
+
+  ServerName myregistrydomain.com
+
+  SSLEngine on
+  SSLCertificateFile /usr/local/apache2/conf/domain.crt
+  SSLCertificateKeyFile /usr/local/apache2/conf/domain.key
+
+  ## SSL settings recommandation from: https://raymii.org/s/tutorials/Strong_SSL_Security_On_Apache2.html
+  # Anti CRIME
+  SSLCompression off
+
+  # POODLE and other stuff
+  SSLProtocol all -SSLv2 -SSLv3 -TLSv1
+
+  # Secure cypher suites
+  SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
+  SSLHonorCipherOrder on
+
+  Header always set "Docker-Distribution-Api-Version" "registry/2.0"
+  Header onsuccess set "Docker-Distribution-Api-Version" "registry/2.0"
+  RequestHeader set X-Forwarded-Proto "https"
+
+  ProxyRequests     off
+  ProxyPreserveHost on
+
+  # no proxy for /error/ (Apache HTTPd errors messages)
+  ProxyPass /error/ !
+
+  ProxyPass        /v2 http://registry:5000/v2
+  ProxyPassReverse /v2 http://registry:5000/v2
+
+  <Location /v2>
+    Order deny,allow
+    Allow from all
+    AuthName "Registry Authentication"
+    AuthType basic
+    AuthUserFile "/usr/local/apache2/conf/httpd.htpasswd"
+    AuthGroupFile "/usr/local/apache2/conf/httpd.groups"
+
+    # Read access to authentified users
+    <Limit GET HEAD>
+      Require valid-user
+    </Limit>
+
+    # Write access to docker-deployer only
+    <Limit POST PUT DELETE PATCH>
+      Require group pusher
+    </Limit>
+
+  </Location>
+
+</VirtualHost>
+EOF
+
+# Now, create a password file for "testuser" and "testpassword"
+docker run --entrypoint htpasswd httpd:2.4 -Bbn testuser testpassword > auth/httpd.htpasswd
+# Create another one for "testuserpush" and "testpasswordpush"
+docker run --entrypoint htpasswd httpd:2.4 -Bbn testuserpush testpasswordpush >> auth/httpd.htpasswd
+
+# Create your group file
+echo "pusher: testuserpush" > auth/httpd.groups
+
+# Copy over your certificate files
+cp domain.crt auth
+cp domain.key auth
+
+# Now create your compose file
+
+cat <<EOF > docker-compose.yml
+apache:
+  image: "httpd:2.4"
+  hostname: myregistrydomain.com
+  ports:
+    - 5043:5043
+  links:
+    - registry:registry
+  volumes:
+    - `pwd`/auth:/usr/local/apache2/conf
+
+registry:
+  image: registry:2
+  ports:
+    - 127.0.0.1:5000:5000
+  volumes:
+    - `pwd`/data:/var/lib/registry
+
+EOF
+```
+
+## Starting and stopping
+
+Now, start your stack:
+
+    docker-compose up -d
+
+Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image: 
+
+    docker login myregistrydomain.com:5043
+    docker tag ubuntu myregistrydomain.com:5043/test
+    docker push myregistrydomain.com:5043/test
+
+Now, login with a "pull-only" user (using `testuser` and `testpassword`), then pull back the image:
+
+    docker login myregistrydomain.com:5043
+    docker pull myregistrydomain.com:5043/test
+
+Verify that the "pull-only" can NOT push:
+
+    docker push myregistrydomain.com:5043/test
+
+### Docker still complains about the certificate?
+
+That's certainly because you are using a self-signed certificate, despite the warnings.
+
+If you really insist on using these, you have to trust it at the OS level.
+
+Usually, on Ubuntu this is done with:
+
+    cp auth/domain.crt /usr/local/share/ca-certificates/myregistrydomain.com.crt
+    update-ca-certificates
+
+... and on RedHat with:
+
+    cp auth/domain.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt
+    update-ca-trust
+
+Now:
+
+ * `service docker stop && service docker start` (or any other way you use to restart docker)
+ * `docker-compose up -d` to bring your registry up

docs/deploying.md

@@ -166,7 +166,7 @@ And then push and pull images as an authenticated user.
 
 ### Alternatives
 
-1. You may want to leverage more advanced basic auth implementations through a proxy design, in front of the registry. You will find an example of such design in the [nginx proxy documentation](nginx.md).
+1. You may want to leverage more advanced basic auth implementations through a proxy design, in front of the registry. You will find examples of such patterns in the [recipes list](recipes.md).
 
 2. Alternatively, the Registry also supports delegated authentication, redirecting users to a specific, trusted token server. That approach requires significantly more investment, and only make sense if you want to fully configure ACLs and more control over the Registry integration into your global authorization and authentication systems.
 
@@ -192,6 +192,7 @@ registry:
     REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
     REGISTRY_HTTP_TLS_KEY: /certs/domain.key
     REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /var/lib/registry
+    REGISTRY_AUTH: htpasswd
     REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
     REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
   volumes:
@@ -212,6 +213,7 @@ You will find more specific and advanced informations in the following sections:
 
  - [Configuration reference](configuration.md)
  - [Working with notifications](notifications.md)
+ - [Advanced "recipes"](recipes.md)
  - [Registry API](spec/api.md)
  - [Storage driver model](storagedrivers.md)
 

docs/nginx.md

@@ -8,29 +8,34 @@ keywords = ["registry, service, images, repository, authentication"]
 
 # Authenticating proxy with nginx
 
-With this method, you implement basic authentication in a reverse proxy that sits in front of your registry.
 
-While this model gives you the ability to use whatever authentication backend you want through a secondary authentication mechanism implemented inside your proxy, it also requires that you move TLS termination from the Registry to the proxy itself.
+## Use-case
 
-Furthermore, introducing an extra http layer in your communication pipeline will make it more complex to deploy, maintain, and debug, and will possibly create issues (typically, nginx does buffer client requests to disk, opening the door to a host of problems if you are dealing with huge images and a lot of traffic).
+People already relying on a nginx proxy to authenticate their users to other services might want to leverage it and have Registry communications tunneled through the same pipeline.
 
-### Requirements
+Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO mechanism fronting their internal http portal.
 
-You should have followed entirely the basic [deployment guide](deploying.md).
+### Alternatives
 
-If you have not, please take the time to do so.
+If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](deploying.md#native-basic-auth). 
 
-At this point, it's assumed that:
+### Solution
 
- * you understand Docker security requirements, and how to configure your docker engines properly
+With the method presented here, you implement basic authentication for docker engines in a reverse proxy that sits in front of your registry.
- * you have installed Docker Compose
- * it's HIGHLY recommended that you get a certificate from a known CA instead of self-signed certificates
- * inside the current directory, you have a X509 `domain.crt` and `domain.key`, for the CN `myregistrydomain.com` (or whatever domain name you want to use)
- * be sure you have stopped and removed any previously running registry (typically `docker stop registry && docker rm -v registry`)
 
-### Setting things up
+While we use a simple htpasswd file as an example, any other nginx authentication backend should be fairly easy to implement once you are done with the exemple.
 
-Read again the requirements.
+We also implement push restriction (to a limited user group) for the sake of the exemple. Again, you should modify this to fit your mileage. 
+
+### Gotchas
+
+While this model gives you the ability to use whatever authentication backend you want through the secondary authentication mechanism implemented inside your proxy, it also requires that you move TLS termination from the Registry to the proxy itself.
+
+Furthermore, introducing an extra http layer in your communication pipeline will make it more complex to deploy, maintain, and debug, and will possibly create issues.
+
+## Setting things up
+
+Read again [the requirements](recipes.md#requirements).
 
 Ready?
 
@@ -41,7 +46,7 @@ mkdir -p auth
 mkdir -p data
 
 # This is the main nginx configuration you will use
-cat <<EOF > auth/registry.conf
+cat <<EOF > auth/nginx.conf
 upstream docker-registry {
   server registry:5000;
 }
@@ -54,6 +59,12 @@ server {
   ssl_certificate /etc/nginx/conf.d/domain.crt;
   ssl_certificate_key /etc/nginx/conf.d/domain.key;
 
+  # Recommandations from https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html
+  ssl_protocols TLSv1.1 TLSv1.2;
+  ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
+  ssl_prefer_server_ciphers on;
+  ssl_session_cache shared:SSL:10m;
+
   # disable any limits to avoid HTTP 413 for large image uploads
   client_max_body_size 0;
 
@@ -69,7 +80,7 @@ server {
 
     # To add basic authentication to v2 use auth_basic setting plus add_header
     auth_basic "Registry realm";
-    auth_basic_user_file /etc/nginx/conf.d/htpasswd;
+    auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd;
     add_header 'Docker-Distribution-Api-Version' 'registry/2.0' always;
 
     proxy_pass                          http://docker-registry;
@@ -83,7 +94,7 @@ server {
 EOF
 
 # Now, create a password file for "testuser" and "testpassword"
-htpasswd -bn testuser testpassword > auth/htpasswd
+docker run --entrypoint htpasswd httpd:2.4 -bn testuser testpassword > auth/nginx.htpasswd
 
 # Copy over your certificate files
 cp domain.crt auth
@@ -105,23 +116,25 @@ registry:
   image: registry:2
   ports:
     - 127.0.0.1:5000:5000
-  environment:
-    REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
   volumes:
-    - `pwd`/data:/data
+    - `pwd`/data:/var/lib/registry
 EOF
 ```
 
-### Starting and stopping
+## Starting and stopping
 
-That's it. You can now:
+Now, start your stack:
 
- * `docker-compose up -d` to start your registry
+    docker-compose up -d
- * `docker login myregistrydomain.com:5043` (using `testuser` and `testpassword`)
- * `docker tag ubuntu myregistrydomain.com:5043/toto`
- * `docker push myregistrydomain.com:5043/toto`
 
-### Docker still complains about the certificate?
+Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image: 
+
+    docker login myregistrydomain.com:5043
+    docker tag ubuntu myregistrydomain.com:5043/test
+    docker push myregistrydomain.com:5043/test
+    docker pull myregistrydomain.com:5043/test
+
+## Docker still complains about the certificate?
 
 That's certainly because you are using a self-signed certificate, despite the warnings.
 

docs/recipes.md

@@ -0,0 +1,32 @@
+<!--[metadata]>
++++
+title = "Recipes for Registry"
+description = "Fun stuff to do with your registry"
+keywords = ["registry, service, images, repository, recipe"]
++++
+<![end-metadata]-->
+
+# Recipes
+
+You will find here a list of "recipes", end-to-end scenarios for exotic or otherwise advanced use-cases.
+
+Most users are not expected to have a use for these.
+
+## Requirements
+
+You should have followed entirely the basic [deployment guide](deploying.md).
+
+If you have not, please take the time to do so.
+
+At this point, it's assumed that:
+
+ * you understand Docker security requirements, and how to configure your docker engines properly
+ * you have installed Docker Compose
+ * it's HIGHLY recommended that you get a certificate from a known CA instead of self-signed certificates
+ * inside the current directory, you have a X509 `domain.crt` and `domain.key`, for the CN `myregistrydomain.com`
+ * be sure you have stopped and removed any previously running registry (typically `docker stop registry && docker rm -v registry`)
+
+## The List
+
+ * [using Apache as an authenticating proxy](apache.md)
+ * [using Nginx as an authenticating proxy](nginx.md)