From 74c5c2fee4571fb2ff1dfd1daadf8f877f2aabcd Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Mon, 14 Nov 2016 14:03:01 -0800 Subject: [PATCH 01/12] Remove newlines from end of error strings Golint now checks for new lines at the end of go error strings, remove these unneeded new lines. Signed-off-by: Derek McGowan (github: dmcgowan) --- registry/storage/garbagecollect.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/registry/storage/garbagecollect.go b/registry/storage/garbagecollect.go index e982c994..7cf0298e 100644 --- a/registry/storage/garbagecollect.go +++ b/registry/storage/garbagecollect.go @@ -80,7 +80,7 @@ func MarkAndSweep(ctx context.Context, storageDriver driver.StorageDriver, regis }) if err != nil { - return fmt.Errorf("failed to mark: %v\n", err) + return fmt.Errorf("failed to mark: %v", err) } // sweep @@ -106,7 +106,7 @@ func MarkAndSweep(ctx context.Context, storageDriver driver.StorageDriver, regis } err = vacuum.RemoveBlob(string(dgst)) if err != nil { - return fmt.Errorf("failed to delete blob %s: %v\n", dgst, err) + return fmt.Errorf("failed to delete blob %s: %v", dgst, err) } } From f982e058617bfa4b3fc0c22e6af16d5971d3bad6 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Fri, 11 Nov 2016 15:38:08 -0800 Subject: [PATCH 02/12] Update scope specification for resource class Update grammar to support a resource class. Add example for plugin repository class. Signed-off-by: Derek McGowan (github: dmcgowan) --- docs/spec/auth/scope.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/spec/auth/scope.md b/docs/spec/auth/scope.md index eecb8f6f..6ef61edf 100644 --- a/docs/spec/auth/scope.md +++ b/docs/spec/auth/scope.md @@ -39,13 +39,23 @@ intended to represent. This type may be specific to a resource provider but must be understood by the authorization server in order to validate the subject is authorized for a specific resource. +#### Resource Class + +The resource type might have a resource class which further classifies the +the resource name within the resource type. A class is not required and +is specific to the resource type. + #### Example Resource Types - `repository` - represents a single repository within a registry. A repository may represent many manifest or content blobs, but the resource type is considered the collections of those items. Actions which may be performed on a `repository` are `pull` for accessing the collection and `push` for adding to -it. +it. By default the `repository` type has the class of `image`. + - `repository(plugin)` - represents a single repository of plugins within a +registry. A plugin repository has the same content and actions as a repository. + - `registry` - represents the entire registry. Used for administrative actions +or lookup operations that span an entire registry. ### Resource Name @@ -78,7 +88,8 @@ scopes. ``` scope := resourcescope [ ' ' resourcescope ]* resourcescope := resourcetype ":" resourcename ":" action [ ',' action ]* -resourcetype := /[a-z]*/ +resourcetype := resourcetypevalue [ '(' resourcetypevalue ')' ] +resourcetypevalue := /[a-z0-9]+/ resourcename := [ hostname '/' ] component [ '/' component ]* hostname := hostcomponent ['.' hostcomponent]* [':' port-number] hostcomponent := /([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])/ From 07d2f1aac75a5d4b7d3e1fb012062c69dcbcdaa0 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Tue, 15 Nov 2016 17:14:31 -0800 Subject: [PATCH 03/12] Add class to repository scope Signed-off-by: Derek McGowan (github: dmcgowan) --- registry/auth/auth.go | 5 +++-- registry/auth/token/token.go | 1 + registry/client/auth/session.go | 7 ++++++- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/registry/auth/auth.go b/registry/auth/auth.go index 0cb37235..5d40ea3d 100644 --- a/registry/auth/auth.go +++ b/registry/auth/auth.go @@ -66,8 +66,9 @@ type UserInfo struct { // Resource describes a resource by type and name. type Resource struct { - Type string - Name string + Type string + Class string + Name string } // Access describes a specific action that is diff --git a/registry/auth/token/token.go b/registry/auth/token/token.go index 634eb75b..74ce9299 100644 --- a/registry/auth/token/token.go +++ b/registry/auth/token/token.go @@ -34,6 +34,7 @@ var ( // ResourceActions stores allowed actions on a named and typed resource. type ResourceActions struct { Type string `json:"type"` + Class string `json:"class"` Name string `json:"name"` Actions []string `json:"actions"` } diff --git a/registry/client/auth/session.go b/registry/client/auth/session.go index ffc3384b..d6d884ff 100644 --- a/registry/client/auth/session.go +++ b/registry/client/auth/session.go @@ -147,13 +147,18 @@ type Scope interface { // to a repository. type RepositoryScope struct { Repository string + Class string Actions []string } // String returns the string representation of the repository // using the scope grammar func (rs RepositoryScope) String() string { - return fmt.Sprintf("repository:%s:%s", rs.Repository, strings.Join(rs.Actions, ",")) + repoType := "repository" + if rs.Class != "" { + repoType = fmt.Sprintf("%s(%s)", repoType, rs.Class) + } + return fmt.Sprintf("%s:%s:%s", repoType, rs.Repository, strings.Join(rs.Actions, ",")) } // RegistryScope represents a token scope for access From 4d0424b470228a49d74dadc945476d52f2dd5a26 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Tue, 15 Nov 2016 09:19:33 -0800 Subject: [PATCH 04/12] Update contrib token server to support repository class Signed-off-by: Derek McGowan (github: dmcgowan) --- contrib/token-server/main.go | 18 ++++++++++++++++++ contrib/token-server/token.go | 34 +++++++++++++++++++++++++++++++--- 2 files changed, 49 insertions(+), 3 deletions(-) diff --git a/contrib/token-server/main.go b/contrib/token-server/main.go index 1cebc0e1..e9d6d64f 100644 --- a/contrib/token-server/main.go +++ b/contrib/token-server/main.go @@ -18,6 +18,10 @@ import ( "github.com/gorilla/mux" ) +var ( + enforceRepoClass bool +) + func main() { var ( issuer = &TokenIssuer{} @@ -44,6 +48,8 @@ func main() { flag.StringVar(&cert, "tlscert", "", "Certificate file for TLS") flag.StringVar(&certKey, "tlskey", "", "Certificate key for TLS") + flag.BoolVar(&enforceRepoClass, "enforce-class", false, "Enforce policy for single repository class") + flag.Parse() if debug { @@ -157,6 +163,8 @@ type tokenResponse struct { ExpiresIn int `json:"expires_in,omitempty"` } +var repositoryClassCache = map[string]string{} + func filterAccessList(ctx context.Context, scope string, requestedAccessList []auth.Access) []auth.Access { if !strings.HasSuffix(scope, "/") { scope = scope + "/" @@ -168,6 +176,16 @@ func filterAccessList(ctx context.Context, scope string, requestedAccessList []a context.GetLogger(ctx).Debugf("Resource scope not allowed: %s", access.Name) continue } + if enforceRepoClass { + if class, ok := repositoryClassCache[access.Name]; ok { + if class != access.Class { + context.GetLogger(ctx).Debugf("Different repository class: %q, previously %q", access.Class, class) + continue + } + } else if strings.EqualFold(access.Action, "push") { + repositoryClassCache[access.Name] = access.Class + } + } } else if access.Type == "registry" { if access.Name != "catalog" { context.GetLogger(ctx).Debugf("Unknown registry resource: %s", access.Name) diff --git a/contrib/token-server/token.go b/contrib/token-server/token.go index e69fb9c1..b0c2abff 100644 --- a/contrib/token-server/token.go +++ b/contrib/token-server/token.go @@ -7,6 +7,7 @@ import ( "encoding/json" "fmt" "io" + "regexp" "strings" "time" @@ -32,12 +33,18 @@ func ResolveScopeSpecifiers(ctx context.Context, scopeSpecs []string) []auth.Acc resourceType, resourceName, actions := parts[0], parts[1], parts[2] + resourceType, resourceClass := splitResourceClass(resourceType) + if resourceType == "" { + continue + } + // Actions should be a comma-separated list of actions. for _, action := range strings.Split(actions, ",") { requestedAccess := auth.Access{ Resource: auth.Resource{ - Type: resourceType, - Name: resourceName, + Type: resourceType, + Class: resourceClass, + Name: resourceName, }, Action: action, } @@ -55,6 +62,19 @@ func ResolveScopeSpecifiers(ctx context.Context, scopeSpecs []string) []auth.Acc return requestedAccessList } +var typeRegexp = regexp.MustCompile(`^([a-z0-9]+)(\([a-z0-9]+\))?$`) + +func splitResourceClass(t string) (string, string) { + matches := typeRegexp.FindStringSubmatch(t) + if len(matches) < 2 { + return "", "" + } + if len(matches) == 2 || len(matches[2]) < 2 { + return matches[1], "" + } + return matches[1], matches[2][1 : len(matches[2])-1] +} + // ResolveScopeList converts a scope list from a token request's // `scope` parameter into a list of standard access objects. func ResolveScopeList(ctx context.Context, scopeList string) []auth.Access { @@ -62,12 +82,19 @@ func ResolveScopeList(ctx context.Context, scopeList string) []auth.Access { return ResolveScopeSpecifiers(ctx, scopes) } +func scopeString(a auth.Access) string { + if a.Class != "" { + return fmt.Sprintf("%s(%s):%s:%s", a.Type, a.Class, a.Name, a.Action) + } + return fmt.Sprintf("%s:%s:%s", a.Type, a.Name, a.Action) +} + // ToScopeList converts a list of access to a // scope list string func ToScopeList(access []auth.Access) string { var s []string for _, a := range access { - s = append(s, fmt.Sprintf("%s:%s:%s", a.Type, a.Name, a.Action)) + s = append(s, scopeString(a)) } return strings.Join(s, ",") } @@ -102,6 +129,7 @@ func (issuer *TokenIssuer) CreateJWT(subject string, audience string, grantedAcc accessEntries = append(accessEntries, &token.ResourceActions{ Type: resource.Type, + Class: resource.Class, Name: resource.Name, Actions: actions, }) From 438b8a1d4e4dba8f471627026e4159db60469e63 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Mon, 21 Nov 2016 16:36:36 -0800 Subject: [PATCH 05/12] Update registry server to support repository class Use whitelist of allowed repository classes to enforce. By default all repository classes are allowed. Add authorized resources to context after authorization. Signed-off-by: Derek McGowan (github: dmcgowan) --- configuration/configuration.go | 13 +++++ registry/auth/auth.go | 33 +++++++++++ registry/auth/token/accesscontroller.go | 2 + registry/auth/token/token.go | 25 ++++++++- registry/handlers/images.go | 74 +++++++++++++++++++++++++ 5 files changed, 146 insertions(+), 1 deletion(-) diff --git a/configuration/configuration.go b/configuration/configuration.go index 55b9fcba..ec50a6b1 100644 --- a/configuration/configuration.go +++ b/configuration/configuration.go @@ -203,6 +203,19 @@ type Configuration struct { } `yaml:"urls,omitempty"` } `yaml:"manifests,omitempty"` } `yaml:"validation,omitempty"` + + // Policy configures registry policy options. + Policy struct { + // Repository configures policies for repositories + Repository struct { + // Classes is a list of repository classes which the + // registry allows content for. This class is matched + // against the configuration media type inside uploaded + // manifests. When non-empty, the registry will enforce + // the class in authorized resources. + Classes []string `yaml:"classes"` + } `yaml:"repository,omitempty"` + } `yaml:"policy,omitempty"` } // LogHook is composed of hook Level and Type. diff --git a/registry/auth/auth.go b/registry/auth/auth.go index 5d40ea3d..1c9af882 100644 --- a/registry/auth/auth.go +++ b/registry/auth/auth.go @@ -136,6 +136,39 @@ func (uic userInfoContext) Value(key interface{}) interface{} { return uic.Context.Value(key) } +// WithResources returns a context with the authorized resources. +func WithResources(ctx context.Context, resources []Resource) context.Context { + return resourceContext{ + Context: ctx, + resources: resources, + } +} + +type resourceContext struct { + context.Context + resources []Resource +} + +type resourceKey struct{} + +func (rc resourceContext) Value(key interface{}) interface{} { + if key == (resourceKey{}) { + return rc.resources + } + + return rc.Context.Value(key) +} + +// AuthorizedResources returns the list of resources which have +// been authorized for this request. +func AuthorizedResources(ctx context.Context) []Resource { + if resources, ok := ctx.Value(resourceKey{}).([]Resource); ok { + return resources + } + + return nil +} + // InitFunc is the type of an AccessController factory function and is used // to register the constructor for different AccesController backends. type InitFunc func(options map[string]interface{}) (AccessController, error) diff --git a/registry/auth/token/accesscontroller.go b/registry/auth/token/accesscontroller.go index 52b7f369..4e8b7f1c 100644 --- a/registry/auth/token/accesscontroller.go +++ b/registry/auth/token/accesscontroller.go @@ -261,6 +261,8 @@ func (ac *accessController) Authorized(ctx context.Context, accessItems ...auth. } } + ctx = auth.WithResources(ctx, token.resources()) + return auth.WithUser(ctx, auth.UserInfo{Name: token.Claims.Subject}), nil } diff --git a/registry/auth/token/token.go b/registry/auth/token/token.go index 74ce9299..850f5813 100644 --- a/registry/auth/token/token.go +++ b/registry/auth/token/token.go @@ -34,7 +34,7 @@ var ( // ResourceActions stores allowed actions on a named and typed resource. type ResourceActions struct { Type string `json:"type"` - Class string `json:"class"` + Class string `json:"class,omitempty"` Name string `json:"name"` Actions []string `json:"actions"` } @@ -350,6 +350,29 @@ func (t *Token) accessSet() accessSet { return accessSet } +func (t *Token) resources() []auth.Resource { + if t.Claims == nil { + return nil + } + + resourceSet := map[auth.Resource]struct{}{} + for _, resourceActions := range t.Claims.Access { + resource := auth.Resource{ + Type: resourceActions.Type, + Class: resourceActions.Class, + Name: resourceActions.Name, + } + resourceSet[resource] = struct{}{} + } + + resources := make([]auth.Resource, 0, len(resourceSet)) + for resource := range resourceSet { + resources = append(resources, resource) + } + + return resources +} + func (t *Token) compactRaw() string { return fmt.Sprintf("%s.%s", t.Raw, joseBase64UrlEncode(t.Signature)) } diff --git a/registry/handlers/images.go b/registry/handlers/images.go index 96316348..9518f685 100644 --- a/registry/handlers/images.go +++ b/registry/handlers/images.go @@ -15,6 +15,7 @@ import ( "github.com/docker/distribution/reference" "github.com/docker/distribution/registry/api/errcode" "github.com/docker/distribution/registry/api/v2" + "github.com/docker/distribution/registry/auth" "github.com/gorilla/handlers" ) @@ -269,6 +270,12 @@ func (imh *imageManifestHandler) PutImageManifest(w http.ResponseWriter, r *http if imh.Tag != "" { options = append(options, distribution.WithTag(imh.Tag)) } + + if err := imh.applyResourcePolicy(manifest); err != nil { + imh.Errors = append(imh.Errors, err) + return + } + _, err = manifests.Put(imh, manifest, options...) if err != nil { // TODO(stevvooe): These error handling switches really need to be @@ -339,6 +346,73 @@ func (imh *imageManifestHandler) PutImageManifest(w http.ResponseWriter, r *http w.WriteHeader(http.StatusCreated) } +// applyResourcePolicy checks whether the resource class matches what has +// been authorized and allowed by the policy configuration. +func (imh *imageManifestHandler) applyResourcePolicy(manifest distribution.Manifest) error { + allowedClasses := imh.App.Config.Policy.Repository.Classes + if len(allowedClasses) == 0 { + return nil + } + + var class string + switch m := manifest.(type) { + case *schema1.SignedManifest: + class = "image" + case *schema2.DeserializedManifest: + switch m.Config.MediaType { + case schema2.MediaTypeConfig: + class = "image" + case schema2.MediaTypePluginConfig: + class = "plugin" + default: + message := fmt.Sprintf("unknown manifest class for %s", m.Config.MediaType) + return errcode.ErrorCodeDenied.WithMessage(message) + } + } + + if class == "" { + return nil + } + + // Check to see if class is allowed in registry + var allowedClass bool + for _, c := range allowedClasses { + if class == c { + allowedClass = true + break + } + } + if !allowedClass { + message := fmt.Sprintf("registry does not allow %s manifest", class) + return errcode.ErrorCodeDenied.WithMessage(message) + } + + resources := auth.AuthorizedResources(imh) + n := imh.Repository.Named().Name() + + var foundResource bool + for _, r := range resources { + if r.Name == n { + if r.Class == "" { + r.Class = "image" + } + if r.Class == class { + return nil + } + foundResource = true + } + } + + // resource was found but no matching class was found + if foundResource { + message := fmt.Sprintf("repository not authorized for %s manifest", class) + return errcode.ErrorCodeDenied.WithMessage(message) + } + + return nil + +} + // DeleteImageManifest removes the manifest with the given digest from the registry. func (imh *imageManifestHandler) DeleteImageManifest(w http.ResponseWriter, r *http.Request) { ctxu.GetLogger(imh).Debug("DeleteImageManifest") From 0241c48be550402e1ba2caa368cf8f97b89d3a21 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Tue, 20 Dec 2016 15:11:23 -0800 Subject: [PATCH 06/12] Release notes for v2.6.0-rc2 Signed-off-by: Derek McGowan (github: dmcgowan) --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index dce49207..4c07a4e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 2.6.0-rc2 (2016-12-20) + +#### Spec + - Authorization: add support for repository classes + +#### Registry + - Add policy configuration for enforcing repository classes + + ## 2.6.0-rc1 (2016-10-10) #### Storage From df1ddd8e46527c3288357336cd8da5948d88227d Mon Sep 17 00:00:00 2001 From: Joao Fernandes Date: Wed, 14 Dec 2016 18:50:40 -0800 Subject: [PATCH 07/12] Format configuration.md with code fences to avoid render issues Signed-off-by: Joao Fernandes --- docs/configuration.md | 888 +++++++++++++++++++++++------------------- 1 file changed, 487 insertions(+), 401 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index a7c3b1c8..9af73e90 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -17,13 +17,17 @@ To override a configuration option, create an environment variable named and the `_` (underscore) represents indention levels. For example, you can configure the `rootdirectory` of the `filesystem` storage backend: - storage: - filesystem: - rootdirectory: /var/lib/registry +``` +storage: + filesystem: + rootdirectory: /var/lib/registry +``` To override this value, set an environment variable like this: - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere +``` +REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere +``` This variable overrides the `/var/lib/registry` value to the `/somewhere` directory. @@ -36,9 +40,11 @@ If the default configuration is not a sound basis for your usage, or if you are Typically, create a new configuration file from scratch, and call it `config.yml`, then: - docker run -d -p 5000:5000 --restart=always --name registry \ - -v `pwd`/config.yml:/etc/docker/registry/config.yml \ - registry:2 +``` +docker run -d -p 5000:5000 --restart=always --name registry \ + -v `pwd`/config.yml:/etc/docker/registry/config.yml \ + registry:2 +``` You can (and probably should) use [this as a starting point](https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml). @@ -48,154 +54,191 @@ This section lists all the registry configuration options. Some options in the list are mutually exclusive. So, make sure to read the detailed reference information about each option that appears later in this page. - version: 0.1 - log: - accesslog: - disabled: true - level: debug - formatter: text - fields: - service: registry - environment: staging - hooks: - - type: mail - disabled: true - levels: - - panic - options: - smtp: - addr: mail.example.com:25 - username: mailuser - password: password - insecure: true - from: sender@example.com - to: - - errors@example.com - loglevel: debug # deprecated: use "log" - storage: - filesystem: - rootdirectory: /var/lib/registry - maxthreads: 100 - azure: - accountname: accountname - accountkey: base64encodedaccountkey - container: containername - gcs: - bucket: bucketname - keyfile: /path/to/keyfile - rootdirectory: /gcs/object/name/prefix - chunksize: 5242880 - s3: - accesskey: awsaccesskey - secretkey: awssecretkey - region: us-west-1 - regionendpoint: http://myobjects.local - bucket: bucketname - encrypt: true - keyid: mykeyid - secure: true - v4auth: true - chunksize: 5242880 - multipartcopychunksize: 33554432 - multipartcopymaxconcurrency: 100 - multipartcopythresholdsize: 33554432 - rootdirectory: /s3/object/name/prefix - swift: - username: username - password: password - authurl: https://storage.myprovider.com/auth/v1.0 or https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth - tenant: tenantname - tenantid: tenantid - domain: domain name for Openstack Identity v3 API - domainid: domain id for Openstack Identity v3 API - insecureskipverify: true - region: fr - container: containername - rootdirectory: /swift/object/name/prefix - oss: - accesskeyid: accesskeyid - accesskeysecret: accesskeysecret - region: OSS region name - endpoint: optional endpoints - internal: optional internal endpoint - bucket: OSS bucket - encrypt: optional data encryption setting - secure: optional ssl setting - chunksize: optional size valye - rootdirectory: optional root directory - inmemory: # This driver takes no parameters - delete: - enabled: false - redirect: - disable: false - cache: - blobdescriptor: redis - maintenance: - uploadpurging: - enabled: true - age: 168h - interval: 24h - dryrun: false - readonly: - enabled: false - auth: - silly: - realm: silly-realm - service: silly-service - token: - realm: token-realm - service: token-service - issuer: registry-token-issuer - rootcertbundle: /root/certs/bundle - htpasswd: - realm: basic-realm - path: /path/to/htpasswd - middleware: - registry: - - name: ARegistryMiddleware - options: - foo: bar - repository: - - name: ARepositoryMiddleware - options: - foo: bar - storage: - - name: cloudfront - options: - baseurl: https://my.cloudfronted.domain.com/ - privatekey: /path/to/pem - keypairid: cloudfrontkeypairid - duration: 3000s - storage: - - name: redirect - options: - baseurl: https://example.com/ - reporting: - bugsnag: - apikey: bugsnagapikey - releasestage: bugsnagreleasestage - endpoint: bugsnagendpoint - newrelic: - licensekey: newreliclicensekey - name: newrelicname - verbose: true - http: - addr: localhost:5000 - prefix: /my/nested/registry/ - host: https://myregistryaddress.org:5000 - secret: asecretforlocaldevelopment - relativeurls: false - tls: - certificate: /path/to/x509/public - key: /path/to/x509/private - clientcas: - - /path/to/ca.pem - - /path/to/another/ca.pem - letsencrypt: - cachefile: /path/to/cache-file - email: emailused@letsencrypt.com - debug: - addr: localhost:5001 +``` +version: 0.1 +log: + accesslog: + disabled: true + level: debug + formatter: text + fields: + service: registry + environment: staging + hooks: + - type: mail + disabled: true + levels: + - panic + options: + smtp: + addr: mail.example.com:25 + username: mailuser + password: password + insecure: true + from: sender@example.com + to: + - errors@example.com +loglevel: debug # deprecated: use "log" +storage: + filesystem: + rootdirectory: /var/lib/registry + maxthreads: 100 + azure: + accountname: accountname + accountkey: base64encodedaccountkey + container: containername + gcs: + bucket: bucketname + keyfile: /path/to/keyfile + rootdirectory: /gcs/object/name/prefix + chunksize: 5242880 + s3: + accesskey: awsaccesskey + secretkey: awssecretkey + region: us-west-1 + regionendpoint: http://myobjects.local + bucket: bucketname + encrypt: true + keyid: mykeyid + secure: true + v4auth: true + chunksize: 5242880 + multipartcopychunksize: 33554432 + multipartcopymaxconcurrency: 100 + multipartcopythresholdsize: 33554432 + rootdirectory: /s3/object/name/prefix + swift: + username: username + password: password + authurl: https://storage.myprovider.com/auth/v1.0 or https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth + tenant: tenantname + tenantid: tenantid + domain: domain name for Openstack Identity v3 API + domainid: domain id for Openstack Identity v3 API + insecureskipverify: true + region: fr + container: containername + rootdirectory: /swift/object/name/prefix + oss: + accesskeyid: accesskeyid + accesskeysecret: accesskeysecret + region: OSS region name + endpoint: optional endpoints + internal: optional internal endpoint + bucket: OSS bucket + encrypt: optional data encryption setting + secure: optional ssl setting + chunksize: optional size valye + rootdirectory: optional root directory + inmemory: # This driver takes no parameters + delete: + enabled: false + redirect: + disable: false + cache: + blobdescriptor: redis + maintenance: + uploadpurging: + enabled: true + age: 168h + interval: 24h + dryrun: false + readonly: + enabled: false +auth: + silly: + realm: silly-realm + service: silly-service + token: + realm: token-realm + service: token-service + issuer: registry-token-issuer + rootcertbundle: /root/certs/bundle + htpasswd: + realm: basic-realm + path: /path/to/htpasswd +middleware: + registry: + - name: ARegistryMiddleware + options: + foo: bar + repository: + - name: ARepositoryMiddleware + options: + foo: bar + storage: + - name: cloudfront + options: + baseurl: https://my.cloudfronted.domain.com/ + privatekey: /path/to/pem + keypairid: cloudfrontkeypairid + duration: 3000s + storage: + - name: redirect + options: + baseurl: https://example.com/ +reporting: + bugsnag: + apikey: bugsnagapikey + releasestage: bugsnagreleasestage + endpoint: bugsnagendpoint + newrelic: + licensekey: newreliclicensekey + name: newrelicname + verbose: true +http: + addr: localhost:5000 + prefix: /my/nested/registry/ + host: https://myregistryaddress.org:5000 + secret: asecretforlocaldevelopment + relativeurls: false + tls: + certificate: /path/to/x509/public + key: /path/to/x509/private + clientcas: + - /path/to/ca.pem + - /path/to/another/ca.pem + letsencrypt: + cachefile: /path/to/cache-file + email: emailused@letsencrypt.com + debug: + addr: localhost:5001 + headers: + X-Content-Type-Options: [nosniff] + http2: + disabled: false +notifications: + endpoints: + - name: alistener + disabled: false + url: https://my.listener.com/event + headers: + timeout: 500 + threshold: 5 + backoff: 1000 + ignoredmediatypes: + - application/octet-stream +redis: + addr: localhost:6379 + password: asecret + db: 0 + dialtimeout: 10ms + readtimeout: 10ms + writetimeout: 10ms + pool: + maxidle: 16 + maxactive: 64 + idletimeout: 300s +health: + storagedriver: + enabled: true + interval: 10s + threshold: 3 + file: + - file: /path/to/checked/file + interval: 10s + http: + - uri: http://server.to.check/must/return/200 headers: X-Content-Type-Options: [nosniff] http2: @@ -258,6 +301,8 @@ information about each option that appears later in this page. - ^https?://([^/]+\.)*example\.com/ deny: - ^https?://www\.example\.com/ +``` +>>>>>>> a24f2a6... Format configuration.md with code fences to avoid render issues In some instances a configuration option is **optional** but it contains child options marked as **required**. This indicates that you can omit the parent with @@ -266,7 +311,9 @@ the children marked **required**. ## version - version: 0.1 +``` +version: 0.1 +``` The `version` option is **required**. It specifies the configuration's version. It is expected to remain a top-level field, to allow for a consistent version @@ -278,14 +325,16 @@ The `log` subsection configures the behavior of the logging system. The logging system outputs everything to stdout. You can adjust the granularity and format with this configuration section. - log: - accesslog: - disabled: true - level: debug - formatter: text - fields: - service: registry - environment: staging +``` +log: + accesslog: + disabled: true + level: debug + formatter: text + fields: + service: registry + environment: staging +``` @@ -336,8 +385,10 @@ with this configuration section. ### accesslog - accesslog: - disabled: true +``` +accesslog: + disabled: true +``` Within `log`, `accesslog` configures the behavior of the access logging system. By default, the access logging system outputs to stdout in @@ -346,19 +397,21 @@ Access logging can be disabled by setting the boolean flag `disabled` to `true`. ## hooks - hooks: - - type: mail - levels: - - panic - options: - smtp: - addr: smtp.sendhost.com:25 - username: sendername - password: password - insecure: true - from: name@sendhost.com - to: - - name@receivehost.com +``` +hooks: + - type: mail + levels: + - panic + options: + smtp: + addr: smtp.sendhost.com:25 + username: sendername + password: password + insecure: true + from: name@sendhost.com + to: + - name@receivehost.com +``` The `hooks` subsection configures the logging hooks' behavior. This subsection includes a sequence handler which you can use for sending mail, for example. @@ -368,81 +421,85 @@ Refer to `loglevel` to configure the level of messages printed. > **DEPRECATED:** Please use [log](#log) instead. - loglevel: debug +``` +loglevel: debug +``` Permitted values are `error`, `warn`, `info` and `debug`. The default is `info`. ## storage - storage: - filesystem: - rootdirectory: /var/lib/registry - azure: - accountname: accountname - accountkey: base64encodedaccountkey - container: containername - gcs: - bucket: bucketname - keyfile: /path/to/keyfile - rootdirectory: /gcs/object/name/prefix - s3: - accesskey: awsaccesskey - secretkey: awssecretkey - region: us-west-1 - regionendpoint: http://myobjects.local - bucket: bucketname - encrypt: true - keyid: mykeyid - secure: true - v4auth: true - chunksize: 5242880 - multipartcopychunksize: 33554432 - multipartcopymaxconcurrency: 100 - multipartcopythresholdsize: 33554432 - rootdirectory: /s3/object/name/prefix - swift: - username: username - password: password - authurl: https://storage.myprovider.com/auth/v1.0 or https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth - tenant: tenantname - tenantid: tenantid - domain: domain name for Openstack Identity v3 API - domainid: domain id for Openstack Identity v3 API - insecureskipverify: true - region: fr - container: containername - rootdirectory: /swift/object/name/prefix - oss: - accesskeyid: accesskeyid - accesskeysecret: accesskeysecret - region: OSS region name - endpoint: optional endpoints - internal: optional internal endpoint - bucket: OSS bucket - encrypt: optional data encryption setting - secure: optional ssl setting - chunksize: optional size valye - rootdirectory: optional root directory - inmemory: - delete: - enabled: false - cache: - blobdescriptor: inmemory - maintenance: - uploadpurging: - enabled: true - age: 168h - interval: 24h - dryrun: false - redirect: - disable: false +``` +storage: + filesystem: + rootdirectory: /var/lib/registry + azure: + accountname: accountname + accountkey: base64encodedaccountkey + container: containername + gcs: + bucket: bucketname + keyfile: /path/to/keyfile + rootdirectory: /gcs/object/name/prefix + s3: + accesskey: awsaccesskey + secretkey: awssecretkey + region: us-west-1 + regionendpoint: http://myobjects.local + bucket: bucketname + encrypt: true + keyid: mykeyid + secure: true + v4auth: true + chunksize: 5242880 + multipartcopychunksize: 33554432 + multipartcopymaxconcurrency: 100 + multipartcopythresholdsize: 33554432 + rootdirectory: /s3/object/name/prefix + swift: + username: username + password: password + authurl: https://storage.myprovider.com/auth/v1.0 or https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth + tenant: tenantname + tenantid: tenantid + domain: domain name for Openstack Identity v3 API + domainid: domain id for Openstack Identity v3 API + insecureskipverify: true + region: fr + container: containername + rootdirectory: /swift/object/name/prefix + oss: + accesskeyid: accesskeyid + accesskeysecret: accesskeysecret + region: OSS region name + endpoint: optional endpoints + internal: optional internal endpoint + bucket: OSS bucket + encrypt: optional data encryption setting + secure: optional ssl setting + chunksize: optional size valye + rootdirectory: optional root directory + inmemory: + delete: + enabled: false + cache: + blobdescriptor: inmemory + maintenance: + uploadpurging: + enabled: true + age: 168h + interval: 24h + dryrun: false + redirect: + disable: false +``` The storage option is **required** and defines which storage backend is in use. You must configure one backend; if you configure more, the registry returns an error. You can choose any of these backend storage drivers: -| Storage driver | Description -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Storage driver | Description | +|:--------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `filesystem` | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md). | | `azure` | Uses Microsoft's Azure Blob Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/azure.md). | | `gcs` | Uses Google Cloud Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/gcs.md). | @@ -461,7 +518,9 @@ backing data-store. If you do use a Windows volume, you must ensure that the `PATH` to the mount point is within Windows' `MAX_PATH` limits (typically 255 characters). Failure to do so can result in the following error message: - mkdir /XXX protocol error and your registry will not function properly. +``` +mkdir /XXX protocol error and your registry will not function properly. +``` ### Maintenance @@ -477,12 +536,12 @@ configure upload directory purging, the following parameters must be set. -| Parameter | Required | Description - --------- | -------- | ----------- -`enabled` | yes | Set to true to enable upload purging. Default=true. | -`age` | yes | Upload directories which are older than this age will be deleted. Default=168h (1 week) -`interval` | yes | The interval between upload directory purging. Default=24h. -`dryrun` | yes | dryrun can be set to true to obtain a summary of what directories will be deleted. Default=false. +| Parameter | Required | Description | +|:-----------|:---------|:---------------------------------------------------------------------------------------------------| +| `enabled` | yes | Set to true to enable upload purging. Default=true. | +| `age` | yes | Upload directories which are older than this age will be deleted. Default=168h (1 week) | +| `interval` | yes | The interval between upload directory purging. Default=24h. | +| `dryrun` | yes | dryrun can be set to true to obtain a summary of what directories will be deleted. Default=false. | Note: `age` and `interval` are strings containing a number with optional fraction and a unit suffix: e.g. 45m, 2h10m, 168h (1 week). @@ -502,8 +561,10 @@ Use the `delete` subsection to enable the deletion of image blobs and manifests by digest. It defaults to false, but it can be enabled by writing the following on the configuration file: - delete: - enabled: true +``` +delete: + enabled: true +``` ### cache @@ -531,24 +592,27 @@ doing aggressive caching. Redirects can be disabled by adding a single flag `disable`, set to `true` under the `redirect` section: - redirect: - disable: true - +``` +redirect: + disable: true +``` ## auth - auth: - silly: - realm: silly-realm - service: silly-service - token: - realm: token-realm - service: token-service - issuer: registry-token-issuer - rootcertbundle: /root/certs/bundle - htpasswd: - realm: basic-realm - path: /path/to/htpasswd +``` +auth: + silly: + realm: silly-realm + service: silly-service + token: + realm: token-realm + service: token-service + issuer: registry-token-issuer + rootcertbundle: /root/certs/bundle + htpasswd: + realm: basic-realm + path: /path/to/htpasswd +``` The `auth` option is **optional**. There are currently 3 possible auth providers, `silly`, `token` and `htpasswd`. You can configure only @@ -713,22 +777,24 @@ object they're wrapping. This means a registry middleware must implement the An example configuration of the `cloudfront` middleware, a storage middleware: - middleware: - registry: - - name: ARegistryMiddleware - options: - foo: bar - repository: - - name: ARepositoryMiddleware - options: - foo: bar - storage: - - name: cloudfront - options: - baseurl: https://my.cloudfronted.domain.com/ - privatekey: /path/to/pem - keypairid: cloudfrontkeypairid - duration: 3000s +``` +middleware: + registry: + - name: ARegistryMiddleware + options: + foo: bar + repository: + - name: ARepositoryMiddleware + options: + foo: bar + storage: + - name: cloudfront + options: + baseurl: https://my.cloudfronted.domain.com/ + privatekey: /path/to/pem + keypairid: cloudfrontkeypairid + duration: 3000s +``` Each middleware entry has `name` and `options` entries. The `name` must correspond to the name under which the middleware registers itself. The @@ -798,21 +864,23 @@ In place of the `cloudfront` storage middleware, the `redirect` storage middleware can be used to specify a custom URL to a location of a proxy for the layer stored by the S3 storage driver. -| Parameter | Required | Description | -| --- | --- | --- | +| Parameter | Required | Description | +|:----------|:---------|:------------------------------------------------------------------------------------------------------------| | baseurl | yes | `SCHEME://HOST` at which layers are served. Can also contain port. For example, `https://example.com:5443`. | ## reporting - reporting: - bugsnag: - apikey: bugsnagapikey - releasestage: bugsnagreleasestage - endpoint: bugsnagendpoint - newrelic: - licensekey: newreliclicensekey - name: newrelicname - verbose: true +``` +reporting: + bugsnag: + apikey: bugsnagapikey + releasestage: bugsnagreleasestage + endpoint: bugsnagendpoint + newrelic: + licensekey: newreliclicensekey + name: newrelicname + verbose: true +``` The `reporting` option is **optional** and configures error and metrics reporting tools. At the moment only two services are supported, [New @@ -910,28 +978,30 @@ configuration may contain both. ## http - http: - addr: localhost:5000 - net: tcp - prefix: /my/nested/registry/ - host: https://myregistryaddress.org:5000 - secret: asecretforlocaldevelopment - relativeurls: false - tls: - certificate: /path/to/x509/public - key: /path/to/x509/private - clientcas: - - /path/to/ca.pem - - /path/to/another/ca.pem - letsencrypt: - cachefile: /path/to/cache-file - email: emailused@letsencrypt.com - debug: - addr: localhost:5001 - headers: - X-Content-Type-Options: [nosniff] - http2: - disabled: false +``` +http: + addr: localhost:5000 + net: tcp + prefix: /my/nested/registry/ + host: https://myregistryaddress.org:5000 + secret: asecretforlocaldevelopment + relativeurls: false + tls: + certificate: /path/to/x509/public + key: /path/to/x509/private + clientcas: + - /path/to/ca.pem + - /path/to/another/ca.pem + letsencrypt: + cachefile: /path/to/cache-file + email: emailused@letsencrypt.com + debug: + addr: localhost:5001 + headers: + X-Content-Type-Options: [nosniff] + http2: + disabled: false +``` The `http` option details the configuration for the HTTP server that hosts the registry. @@ -1165,17 +1235,19 @@ settings for the registry. ## notifications - notifications: - endpoints: - - name: alistener - disabled: false - url: https://my.listener.com/event - headers: - timeout: 500 - threshold: 5 - backoff: 1000 - ignoredmediatypes: - - application/octet-stream +``` +notifications: + endpoints: + - name: alistener + disabled: false + url: https://my.listener.com/event + headers: + timeout: 500 + threshold: 5 + backoff: 1000 + ignoredmediatypes: + - application/octet-stream +``` The notifications option is **optional** and currently may contain a single option, `endpoints`. @@ -1307,17 +1379,19 @@ The URL to which events should be published. ## redis - redis: - addr: localhost:6379 - password: asecret - db: 0 - dialtimeout: 10ms - readtimeout: 10ms - writetimeout: 10ms - pool: - maxidle: 16 - maxactive: 64 - idletimeout: 300s +``` +redis: + addr: localhost:6379 + password: asecret + db: 0 + dialtimeout: 10ms + readtimeout: 10ms + writetimeout: 10ms + pool: + maxidle: 16 + maxactive: 64 + idletimeout: 300s +``` Declare parameters for constructing the redis connections. Registry instances may use the Redis instance for several applications. The current purpose is @@ -1405,10 +1479,12 @@ as the registry does not set an expire value on keys. ### pool - pool: - maxidle: 16 - maxactive: 64 - idletimeout: 300s +``` +pool: + maxidle: 16 + maxactive: 64 + idletimeout: 300s +``` Configure the behavior of the Redis connection pool. @@ -1457,27 +1533,29 @@ Configure the behavior of the Redis connection pool. ## health - health: - storagedriver: - enabled: true - interval: 10s - threshold: 3 - file: - - file: /path/to/checked/file - interval: 10s - http: - - uri: http://server.to.check/must/return/200 - headers: - Authorization: [Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==] - statuscode: 200 - timeout: 3s - interval: 10s - threshold: 3 - tcp: - - addr: redis-server.domain.com:6379 - timeout: 3s - interval: 10s - threshold: 3 +``` +health: + storagedriver: + enabled: true + interval: 10s + threshold: 3 + file: + - file: /path/to/checked/file + interval: 10s + http: + - uri: http://server.to.check/must/return/200 + headers: + Authorization: [Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==] + statuscode: 200 + timeout: 3s + interval: 10s + threshold: 3 + tcp: + - addr: redis-server.domain.com:6379 + timeout: 3s + interval: 10s + threshold: 3 +``` The health option is **optional**. It may contain preferences for a periodic health check on the storage driver's backend storage, and optional periodic @@ -1786,10 +1864,12 @@ The TCP address to connect to, including a port number. ## Proxy - proxy: - remoteurl: https://registry-1.docker.io - username: [username] - password: [password] +``` +proxy: + remoteurl: https://registry-1.docker.io + username: [username] + password: [password] +``` Proxy enables a registry to be configured as a pull through cache to the official Docker Hub. See [mirror](https://github.com/docker/docker.github.io/tree/master/registry/recipes/mirror.md) for more information. Pushing to a registry configured as a pull through cache is currently unsupported. @@ -1838,9 +1918,11 @@ To enable pulling private repositories (e.g. `batman/robin`) a username and pass ## Compatibility - compatibility: - schema1: - signingkeyfile: /etc/registry/key.json +``` +compatibility: + schema1: + signingkeyfile: /etc/registry/key.json +``` Configure handling of older and deprecated features. Each subsection defines such a feature with configurable behavior. @@ -1870,14 +1952,15 @@ defines such a feature with configurable behavior. ## Validation - validation: - enabled: true - manifests: - urls: - allow: - - ^https?://([^/]+\.)*example\.com/ - deny: - - ^https?://www\.example\.com/ +```none +validation: + manifests: + urls: + allow: + - ^https?://([^/]+\.)*example\.com/ + deny: + - ^https?://www\.example\.com/ +``` ### Enabled @@ -1905,17 +1988,19 @@ one of the `allow` regular expressions and one of the following holds: The following is a simple example you can use for local development: - version: 0.1 - log: - level: debug - storage: - filesystem: - rootdirectory: /var/lib/registry - http: - addr: localhost:5000 - secret: asecretforlocaldevelopment - debug: - addr: localhost:5001 +``` +version: 0.1 +log: + level: debug +storage: + filesystem: + rootdirectory: /var/lib/registry +http: + addr: localhost:5000 + secret: asecretforlocaldevelopment + debug: + addr: localhost:5001 +``` The above configures the registry instance to run on port `5000`, binding to `localhost`, with the `debug` server enabled. Registry data storage is in the @@ -1947,7 +2032,7 @@ conjunction with the S3 storage driver. - + @@ -1966,16 +2051,17 @@ conjunction with the S3 storage driver. The following example illustrates these values: - middleware: - storage: - - name: cloudfront - disabled: false - options: - baseurl: http://d111111abcdef8.cloudfront.net - privatekey: /path/to/asecret.pem - keypairid: asecret - duration: 60 - +``` +middleware: + storage: + - name: cloudfront + disabled: false + options: + baseurl: http://d111111abcdef8.cloudfront.net + privatekey: /path/to/asecret.pem + keypairid: asecret + duration: 60 +``` >**Note**: Cloudfront keys exist separately to other AWS keys. See >[the documentation on AWS credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html) From 7f3c4b5c652614d4ee2d888a1acb519fae20e541 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Tue, 27 Dec 2016 14:51:30 -0800 Subject: [PATCH 08/12] Improve formatting of configuration.md Signed-off-by: Misty Stanley-Jones (cherry picked from commit 6ee03f5da7f6145d3fa29e18aac71db7be91f6e6) Signed-off-by: Misty Stanley-Jones --- docs/configuration.md | 1777 ++++++++++------------------------------- 1 file changed, 415 insertions(+), 1362 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 9af73e90..a1c66b21 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,23 +1,26 @@ --- title: "Configuring a registry" description: "Explains how to configure a registry" -keywords: ["registry, on-prem, images, tags, repository, distribution, configuration"] +keywords: registry, on-prem, images, tags, repository, distribution, configuration --- -# Registry Configuration Reference - -The Registry configuration is based on a YAML file, detailed below. While it comes with sane default values out of the box, you are heavily encouraged to review it exhaustively before moving your systems to production. +The Registry configuration is based on a YAML file, detailed below. While it +comes with sane default values out of the box, you should review it exhaustively +before moving your systems to production. ## Override specific configuration options -In a typical setup where you run your Registry from the official image, you can specify a configuration variable from the environment by passing `-e` arguments to your `docker run` stanza, or from within a Dockerfile using the `ENV` instruction. +In a typical setup where you run your Registry from the official image, you can +specify a configuration variable from the environment by passing `-e` arguments +to your `docker run` stanza or from within a Dockerfile using the `ENV` +instruction. To override a configuration option, create an environment variable named -`REGISTRY_variable` where *`variable`* is the name of the configuration option +`REGISTRY_variable` where `variable` is the name of the configuration option and the `_` (underscore) represents indention levels. For example, you can configure the `rootdirectory` of the `filesystem` storage backend: -``` +```none storage: filesystem: rootdirectory: /var/lib/registry @@ -25,36 +28,43 @@ storage: To override this value, set an environment variable like this: -``` +```none REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere ``` This variable overrides the `/var/lib/registry` value to the `/somewhere` directory. ->**NOTE**: It is highly recommended to create a base configuration file with which environment variables can be used to tweak individual values. Overriding configuration sections with environment variables is not recommended. +> **Note**: Create a base configuration file with environment variables that can +> be configured to tweak individual values. Overriding configuration sections +> with environment variables is not recommended. ## Overriding the entire configuration file -If the default configuration is not a sound basis for your usage, or if you are having issues overriding keys from the environment, you can specify an alternate YAML configuration file by mounting it as a volume in the container. +If the default configuration is not a sound basis for your usage, or if you are +having issues overriding keys from the environment, you can specify an alternate +YAML configuration file by mounting it as a volume in the container. -Typically, create a new configuration file from scratch, and call it `config.yml`, then: +Typically, create a new configuration file from scratch,named `config.yml`, then +specify it in the `docker run` command: -``` -docker run -d -p 5000:5000 --restart=always --name registry \ - -v `pwd`/config.yml:/etc/docker/registry/config.yml \ - registry:2 +```bash +$ docker run -d -p 5000:5000 --restart=always --name registry \ + -v `pwd`/config.yml:/etc/docker/registry/config.yml \ + registry:2 ``` -You can (and probably should) use [this as a starting point](https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml). +Use this +[example YAML file](https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml) +as a starting point. ## List of configuration options -This section lists all the registry configuration options. Some options in -the list are mutually exclusive. So, make sure to read the detailed reference -information about each option that appears later in this page. +These are all configuration options for the registry. Some options in the list +are mutually exclusive. Read the detailed reference information about each +option before finalizing your configuration. -``` +```none version: 0.1 log: accesslog: @@ -240,78 +250,41 @@ health: http: - uri: http://server.to.check/must/return/200 headers: - X-Content-Type-Options: [nosniff] - http2: - disabled: false - notifications: - endpoints: - - name: alistener - disabled: false - url: https://my.listener.com/event - headers: - timeout: 500 - threshold: 5 - backoff: 1000 - ignoredmediatypes: - - application/octet-stream - redis: - addr: localhost:6379 - password: asecret - db: 0 - dialtimeout: 10ms - readtimeout: 10ms - writetimeout: 10ms - pool: - maxidle: 16 - maxactive: 64 - idletimeout: 300s - health: - storagedriver: - enabled: true - interval: 10s - threshold: 3 - file: - - file: /path/to/checked/file - interval: 10s - http: - - uri: http://server.to.check/must/return/200 - headers: - Authorization: [Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==] - statuscode: 200 - timeout: 3s - interval: 10s - threshold: 3 - tcp: - - addr: redis-server.domain.com:6379 - timeout: 3s - interval: 10s - threshold: 3 - proxy: - remoteurl: https://registry-1.docker.io - username: [username] - password: [password] - compatibility: - schema1: - signingkeyfile: /etc/registry/key.json - validation: - enabled: true - manifests: - urls: - allow: - - ^https?://([^/]+\.)*example\.com/ - deny: - - ^https?://www\.example\.com/ + Authorization: [Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==] + statuscode: 200 + timeout: 3s + interval: 10s + threshold: 3 + tcp: + - addr: redis-server.domain.com:6379 + timeout: 3s + interval: 10s + threshold: 3 +proxy: + remoteurl: https://registry-1.docker.io + username: [username] + password: [password] +compatibility: + schema1: + signingkeyfile: /etc/registry/key.json +validation: + enabled: true + manifests: + urls: + allow: + - ^https?://([^/]+\.)*example\.com/ + deny: + - ^https?://www\.example\.com/ ``` ->>>>>>> a24f2a6... Format configuration.md with code fences to avoid render issues In some instances a configuration option is **optional** but it contains child -options marked as **required**. This indicates that you can omit the parent with +options marked as **required**. In these cases, you can omit the parent with all its children. However, if the parent is included, you must also include all the children marked **required**. -## version +## `version` -``` +```none version: 0.1 ``` @@ -319,13 +292,13 @@ The `version` option is **required**. It specifies the configuration's version. It is expected to remain a top-level field, to allow for a consistent version check before parsing the remainder of the configuration file. -## log +## `log` The `log` subsection configures the behavior of the logging system. The logging system outputs everything to stdout. You can adjust the granularity and format with this configuration section. -``` +```none log: accesslog: disabled: true @@ -336,56 +309,15 @@ log: environment: staging ``` -
The storage middleware name. Currently cloudfront is an accepted value.
disableddisabled Set to false to easily disable the middleware.
- - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- level - - no - - Sets the sensitivity of logging output. Permitted values are - error, warn, info and - debug. The default is info. -
- formatter - - no - - This selects the format of logging output. The format primarily affects how keyed - attributes for a log line are encoded. Options are text, json or - logstash. The default is text. -
- fields - - no - - A map of field names to values. These are added to every log line for - the context. This is useful for identifying log messages source after - being mixed in other systems. -
+| Parameter | Required | Description | +|-------------|----------|-------------| +| `level` | no | Sets the sensitivity of logging output. Permitted values are `error`, `warn`, `info`, and `debug`. The default is `info`. | +| `formatter` | no | This selects the format of logging output. The format primarily affects how keyed attributes for a log line are encoded. Options are `text`, `json`, and `logstash`. The default is `text`. | +| `fields` | no | A map of field names to values. These are added to every log line for the context. This is useful for identifying log messages source after being mixed in other systems. | -### accesslog +### `accesslog` -``` +```none accesslog: disabled: true ``` @@ -395,9 +327,9 @@ system. By default, the access logging system outputs to stdout in [Combined Log Format](https://httpd.apache.org/docs/2.4/logs.html#combined). Access logging can be disabled by setting the boolean flag `disabled` to `true`. -## hooks +## `hooks` -``` +```none hooks: - type: mail levels: @@ -417,20 +349,20 @@ The `hooks` subsection configures the logging hooks' behavior. This subsection includes a sequence handler which you can use for sending mail, for example. Refer to `loglevel` to configure the level of messages printed. -## loglevel +## `loglevel` > **DEPRECATED:** Please use [log](#log) instead. -``` +```none loglevel: debug ``` Permitted values are `error`, `warn`, `info` and `debug`. The default is `info`. -## storage +## `storage` -``` +```none storage: filesystem: rootdirectory: /var/lib/registry @@ -491,61 +423,65 @@ storage: age: 168h interval: 24h dryrun: false + readonly: + enabled: false redirect: disable: false ``` -The storage option is **required** and defines which storage backend is in use. -You must configure one backend; if you configure more, the registry returns an error. You can choose any of these backend storage drivers: +The `storage` option is **required** and defines which storage backend is in +use. You must configure exactly one backend. If you configure more, the registry +returns an error. You can choose any of these backend storage drivers: -| Storage driver | Description | -|:--------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Storage driver | Description | +|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `filesystem` | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md). | -| `azure` | Uses Microsoft's Azure Blob Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/azure.md). | +| `azure` | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/azure.md). | | `gcs` | Uses Google Cloud Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/gcs.md). | -| `s3` | Uses Amazon's Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/s3.md). | +| `s3` | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/s3.md). | | `swift` | Uses Openstack Swift object storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/swift.md). | | `oss` | Uses Aliyun OSS for object storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/oss.md). | -For purely tests purposes, you can use the [`inmemory` storage -driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/inmemory.md). If you would like to run a registry from -volatile memory, use the [`filesystem` driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md) on -a ramdisk. +For testing only, you can use the [`inmemory` storage +driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/inmemory.md). +If you would like to run a registry from volatile memory, use the +[`filesystem` driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md) +on a ramdisk. -If you are deploying a registry on Windows, be aware that a Windows volume -mounted from the host is not recommended. Instead, you can use a S3, or Azure, -backing data-store. If you do use a Windows volume, you must ensure that the -`PATH` to the mount point is within Windows' `MAX_PATH` limits (typically 255 -characters). Failure to do so can result in the following error message: +If you are deploying a registry on Windows, a Windows volume mounted from the +host is not recommended. Instead, you can use a S3 or Azure backing +data-store. If you do use a Windows volume, the length of the `PATH` to +the mount point must be within the `MAX_PATH` limits (typically 255 characters), +or this error will occur: -``` +```none mkdir /XXX protocol error and your registry will not function properly. ``` -### Maintenance +### `maintenance` -Currently upload purging and read-only mode are the only maintenance functions available. -These and future maintenance functions which are related to storage can be configured under -the maintenance section. +Currently, upload purging and read-only mode are the only `maintenance` +functions available. -### Upload Purging +### `uploadpurging` -Upload purging is a background process that periodically removes orphaned files from the upload -directories of the registry. Upload purging is enabled by default. To -configure upload directory purging, the following parameters -must be set. +Upload purging is a background process that periodically removes orphaned files +from the upload directories of the registry. Upload purging is enabled by +default. To configure upload directory purging, the following parameters must +be set. | Parameter | Required | Description | -|:-----------|:---------|:---------------------------------------------------------------------------------------------------| -| `enabled` | yes | Set to true to enable upload purging. Default=true. | -| `age` | yes | Upload directories which are older than this age will be deleted. Default=168h (1 week) | -| `interval` | yes | The interval between upload directory purging. Default=24h. | -| `dryrun` | yes | dryrun can be set to true to obtain a summary of what directories will be deleted. Default=false. | +|------------|----------|----------------------------------------------------------------------------------------------------| +| `enabled` | yes | Set to `true` to enable upload purging. Defaults to `true`. | +| `age` | yes | Upload directories which are older than this age will be deleted.Defaults to `168h` (1 week). | +| `interval` | yes | The interval between upload directory purging. Defaults to `24h`. | +| `dryrun` | yes | Set `dryrun` to `true` to obtain a summary of what directories will be deleted. Defaults to `false`.| -Note: `age` and `interval` are strings containing a number with optional fraction and a unit suffix: e.g. 45m, 2h10m, 168h (1 week). +> **Note**: `age` and `interval` are strings containing a number with optional +fraction and a unit suffix. Some examples: `45m`, `2h10m`, `168h`. -### Read-only mode +### `readonly` If the `readonly` section under `maintenance` has `enabled` set to `true`, clients will not be allowed to write to the registry. This mode is useful to @@ -555,51 +491,50 @@ restarted with readonly's `enabled` set to true. After the garbage collection pass finishes, the registry may be restarted again, this time with `readonly` removed from the configuration (or set to false). -### delete +### `delete` -Use the `delete` subsection to enable the deletion of image blobs and manifests +Use the `delete` structure to enable the deletion of image blobs and manifests by digest. It defaults to false, but it can be enabled by writing the following on the configuration file: -``` +```none delete: enabled: true ``` -### cache +### `cache` -Use the `cache` subsection to enable caching of data accessed in the storage +Use the `cache` structure to enable caching of data accessed in the storage backend. Currently, the only available cache provides fast access to layer -metadata. This, if configured, uses the `blobdescriptor` field. +metadata, which uses the `blobdescriptor` field if configured. -You can set `blobdescriptor` field to `redis` or `inmemory`. The `redis` value uses -a Redis pool to cache layer metadata. The `inmemory` value uses an in memory -map. +You can set `blobdescriptor` field to `redis` or `inmemory`. If set to `redis`,a +Redis pool caches layer metadata. If set to `inmemory`, an in-memory map caches +layer metadata. ->**NOTE**: Formerly, `blobdescriptor` was known as `layerinfo`. While these ->are equivalent, `layerinfo` has been deprecated, in favor or ->`blobdescriptor`. +> **NOTE**: Formerly, `blobdescriptor` was known as `layerinfo`. While these +> are equivalent, `layerinfo` has been deprecated. -### redirect +### `redirect` The `redirect` subsection provides configuration for managing redirects from content backends. For backends that support it, redirecting is enabled by -default. Certain deployment scenarios may prefer to route all data through the -Registry, rather than redirecting to the backend. This may be more efficient -when using a backend that is not co-located or when a registry instance is -doing aggressive caching. +default. In certain deployment scenarios, you may decide to route all data +through the Registry, rather than redirecting to the backend. This may be more +efficient when using a backend that is not co-located or when a registry +instance is aggressively caching. -Redirects can be disabled by adding a single flag `disable`, set to `true` +To disable redirects, add a single flag `disable`, set to `true` under the `redirect` section: -``` +```none redirect: disable: true ``` -## auth +## `auth` -``` +```none auth: silly: realm: silly-realm @@ -614,170 +549,78 @@ auth: path: /path/to/htpasswd ``` -The `auth` option is **optional**. There are -currently 3 possible auth providers, `silly`, `token` and `htpasswd`. You can configure only -one `auth` provider. +The `auth` option is **optional**. Possible auth providers include: -### silly +- [`silly`](#silly) +- [`token`](#token) +- [`htpasswd`](#token) -The `silly` auth is only for development purposes. It simply checks for the -existence of the `Authorization` header in the HTTP request. It has no regard for -the header's value. If the header does not exist, the `silly` auth responds with a -challenge response, echoing back the realm, service, and scope that access was -denied for. +You can configure only one authentication provider. + +### `silly` + +The `silly` authentication provider is only appropriate for development. It simply checks +for the existence of the `Authorization` header in the HTTP request. It does not +check the header's value. If the header does not exist, the `silly` auth +responds with a challenge response, echoing back the realm, service, and scope +for which access was denied. The following values are used to configure the response: - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- realm - - yes - - The realm in which the registry server authenticates. -
- service - - yes - - The service being authenticated. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `realm` | yes | The realm in which the registry server authenticates. | +| `service` | yes | The service being authenticated. | + +### `token` + +Token-based authentication allows you to decouple the authentication system from +the registry. It is an established authentication paradigm with a high degree of +security. + +| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `realm` | yes | The realm in which the registry server authenticates. | +| `service` | yes | The service being authenticated. | +| `issuer` | yes | The name of the token issuer. The issuer inserts this into the token so it must match the value configured for the issuer. | +| `rootcertbundle` | yes | The absolute path to the root certificate bundle. This bundle contains the public part of the certificates used to sign authentication tokens. | +For more information about Token based authentication configuration, see the +[specification](spec/auth/token.md). -### token +### `htpasswd` -Token based authentication allows the authentication system to be decoupled from -the registry. It is a well established authentication paradigm with a high -degree of security. +The _htpasswd_ authentication backed allows you to configure basic +authentication using an +[Apache htpasswd file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html). +The only supported password format is +[`bcrypt`](http://en.wikipedia.org/wiki/Bcrypt). Entries with other hash types +are ignored. The `htpasswd` file is loaded once, at startup. If the file is +invalid, the registry will display an error and will not start. - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- realm - - yes - - The realm in which the registry server authenticates. -
- service - - yes - - The service being authenticated. -
- issuer - - yes - -The name of the token issuer. The issuer inserts this into -the token so it must match the value configured for the issuer. -
- rootcertbundle - - yes - -The absolute path to the root certificate bundle. This bundle contains the -public part of the certificates that is used to sign authentication tokens. -
- -For more information about Token based authentication configuration, see the [specification](spec/auth/token.md). - -### htpasswd - -The _htpasswd_ authentication backed allows one to configure basic auth using an -[Apache htpasswd -file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html). Only -[`bcrypt`](http://en.wikipedia.org/wiki/Bcrypt) format passwords are supported. -Entries with other hash types will be ignored. The htpasswd file is loaded once, -at startup. If the file is invalid, the registry will display an error and will -not start. - -> __WARNING:__ This authentication scheme should only be used with TLS -> configured, since basic authentication sends passwords as part of the http +> **Warning**: Only use the `htpasswd` authentication scheme with TLS +> configured, since basic authentication sends passwords as part of the HTTP > header. - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- realm - - yes - - The realm in which the registry server authenticates. -
- path - - yes - - Path to htpasswd file to load at startup. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `realm` | yes | The realm in which the registry server authenticates. | +| `path` | yes | The path to the `htpasswd` file to load at startup. | -## middleware +## `middleware` -The `middleware` option is **optional**. Use this option to inject middleware at -named hook points. All middleware must implement the same interface as the -object they're wrapping. This means a registry middleware must implement the -`distribution.Namespace` interface, repository middleware must implement -`distribution.Repository`, and storage middleware must implement +The `middleware` structure is **optional**. Use this option to inject middleware at +named hook points. Each middleware must implement the same interface as the +object it is wrapping. For instance, a registry middleware must implement the +`distribution.Namespace` interface, while a repository middleware must implement +`distribution.Repository`, and a storage middleware must implement `driver.StorageDriver`. -An example configuration of the `cloudfront` middleware, a storage middleware: +This is an example configuration of the `cloudfront` middleware, a storage +middleware: -``` +```none middleware: registry: - name: ARegistryMiddleware @@ -804,71 +647,26 @@ it supports any interesting structures desired, leaving it up to the middleware initialization function to best determine how to handle the specific interpretation of the options. -### cloudfront +### `cloudfront` - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- baseurl - - yes - - SCHEME://HOST[/PATH] at which Cloudfront is served. -
- privatekey - - yes - - Private Key for Cloudfront provided by AWS. -
- keypairid - - yes - - Key pair ID provided by AWS. -
- duration - - no - - Specify a `duration` by providing an integer and a unit. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `3000s` is a valid duration; there should be no space between the integer and unit. If you do not specify a `duration` or specify an integer without a time unit, this defaults to 20 minutes. -
-### redirect +| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `baseurl` | yes | The `SCHEME://HOST[/PATH]` at which Cloudfront is served. | +| `privatekey` | yes | The private key for Cloudfront, provided by AWS. | +| `keypairid` | yes | The key pair ID provided by AWS. | +| `duration` | no | An integer and unit for the duration of the Cloudfront session. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, or `h`. For example, `3000s` is valid, but `3000 s` is not. If you do not specify a `duration` or you specify an integer without a time unit, the duration defaults to `20m` (20 minutes).| -In place of the `cloudfront` storage middleware, the `redirect` -storage middleware can be used to specify a custom URL to a location -of a proxy for the layer stored by the S3 storage driver. +### `redirect` + +You can use the `redirect` storage middleware to specify a custom URL to a +location of a proxy for the layer stored by the S3 storage driver. | Parameter | Required | Description | -|:----------|:---------|:------------------------------------------------------------------------------------------------------------| -| baseurl | yes | `SCHEME://HOST` at which layers are served. Can also contain port. For example, `https://example.com:5443`. | +|-----------|----------|-------------------------------------------------------------------------------------------------------------| +| `baseurl` | yes | `SCHEME://HOST` at which layers are served. Can also contain port. For example, `https://example.com:5443`. | -## reporting +## `reporting` ``` reporting: @@ -883,102 +681,32 @@ reporting: ``` The `reporting` option is **optional** and configures error and metrics -reporting tools. At the moment only two services are supported, [New -Relic](http://newrelic.com/) and [Bugsnag](http://bugsnag.com), a valid -configuration may contain both. +reporting tools. At the moment only two services are supported: -### bugsnag +- [Bugsnag](#bugsnag) +- [New Relic](#new-relic) - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- apikey - - yes - - API Key provided by Bugsnag -
- releasestage - - no - - Tracks where the registry is deployed, for example, - production,staging, or - development. -
- endpoint - - no - - Specify the enterprise Bugsnag endpoint. -
+A valid configuration may contain both. +### `bugsnag` -### newrelic +| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `apikey` | yes | The API Key provided by Bugsnag. | +| `releasestage` | no | Tracks where the registry is deployed, using a string like `production`, `staging`, or `development`.| +| `endpoint`| no | The enterprise Bugsnag endpoint. | - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- licensekey - - yes - - License key provided by New Relic. -
- name - - no - - New Relic application name. -
- verbose - - no - - Enable New Relic debugging output on stdout. -
+### `newrelic` -## http +| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `licensekey` | yes | License key provided by New Relic. | +| `name` | no | New Relic application name. | +| `verbose`| no | Set to `true` to enable New Relic debugging output on `stdout`. | -``` +## `http` + +```none http: addr: localhost:5000 net: tcp @@ -1003,187 +731,50 @@ http: disabled: false ``` -The `http` option details the configuration for the HTTP server that hosts the registry. +The `http` option details the configuration for the HTTP server that hosts the +registry. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- addr - - yes - - The address for which the server should accept connections. The form depends on a network type (see net option): - HOST:PORT for tcp and FILE for a unix socket. -
- net - - no - - The network which is used to create a listening socket. Known networks are unix and tcp. - The default empty value means tcp. -
- prefix - - no - -If the server does not run at the root path use this value to specify the -prefix. The root path is the section before v2. It -should have both preceding and trailing slashes, for example /path/. -
- host - - no - -This parameter specifies an externally-reachable address for the registry, as a -fully qualified URL. If present, it is used when creating generated URLs. -Otherwise, these URLs are derived from client requests. -
- secret - - yes - -A random piece of data. This is used to sign state that may be stored with the -client to protect against tampering. For production environments you should generate a -random piece of data using a cryptographically secure random generator. This -configuration parameter may be omitted, in which case the registry will automatically -generate a secret at launch. -

-WARNING: If you are building a cluster of registries behind a load balancer, you MUST -ensure the secret is the same for all registries. -

- relativeurls - - no - - Specifies that the registry should return relative URLs in Location headers. - The client is responsible for resolving the correct URL. This option is not - compatible with Docker 1.7 and earlier. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `addr` | yes | The address for which the server should accept connections. The form depends on a network type (see the `net` option). Use `HOST:PORT` for TCP and `FILE` for a UNIX socket. | +| `net` | no | The network used to create a listening socket. Known networks are `unix` and `tcp`. | +| `prefix` | no | If the server does not run at the root path, set this to the value of the prefix. The root path is the section before `v2`. It requires both preceding and trailing slashes, such as in the example `/path/`. | +| `host` | no | A fully-qualified URL for an externally-reachable address for the registry. If present, it is used when creating generated URLs. Otherwise, these URLs are derived from client requests. | +| `secret` | no | A random piece of data used to sign state that may be stored with the client to protect against tampering. For production environments you should generate a random piece of data using a cryptographically secure random generator. If you omit the secret, the registry will automatically generate a secret when it starts. **If you are building a cluster of registries behind a load balancer, you MUST ensure the secret is the same for all registries.**| +| `relativeurls`| no | If `true`, the registry returns relative URLs in Location headers. The client is responsible for resolving the correct URL. **This option is not compatible with Docker 1.7 and earlier.**| -### tls +### `tls` -The `tls` struct within `http` is **optional**. Use this to configure TLS -for the server. If you already have a server such as Nginx or Apache running on -the same host as the registry, you may prefer to configure TLS termination there +The `tls` structure within `http` is **optional**. Use this to configure TLS +for the server. If you already have a web server running on +the same host as the registry, you may prefer to configure TLS on that web server and proxy connections to the registry server. - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- certificate - - yes - - Absolute path to x509 cert file -
- key - - yes - - Absolute path to x509 private key file. -
- clientcas - - no - - An array of absolute paths to an x509 CA file -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `certificate` | yes | Absolute path to the x509 certificate file. | +| `key` | yes | Absolute path to the x509 private key file. | +| `clientcas` | no | An array of absolute paths to x509 CA files. | -### letsencrypt +### `letsencrypt` -The `letsencrypt` struct within `tls` is **optional**. Use this to configure TLS -certificates provided by [Let's Encrypt](https://letsencrypt.org/how-it-works/). +The `letsencrypt` structure within `tls` is **optional**. Use this to configure +TLS certificates provided by +[Let's Encrypt](https://letsencrypt.org/how-it-works/). ->**NOTE**: When using Let's Encrypt ensure that the outward facing address is -> accessible on port `443`. The registry defaults to listening on `5000`, if -> run as a container consider adding the flag `-p 443:5000` to the `docker run` -> command or similar setting in cloud configuration. +>**NOTE**: When using Let's Encrypt, ensure that the outward-facing address is +> accessible on port `443`. The registry defaults to listening on port `5000`. +> If you run the registry as a container, consider adding the flag `-p 443:5000` +> to the `docker run` command or using a similar setting in a cloud +> configuration. - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- cachefile - - yes - - Absolute path to a file for the Let's Encrypt agent to cache data -
- email - - yes - - Email used to register with Let's Encrypt. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `cachefile` | yes | Absolute path to a file where the Let's Encrypt agent can cache data. | +| `email` | yes | The email address used to register with Let's Encrypt. | -### debug +### `debug` The `debug` option is **optional** . Use it to configure a debug server that can be helpful in diagnosing problems. The debug endpoint can be used for @@ -1191,11 +782,10 @@ monitoring registry metrics and health, as well as profiling. Sensitive information may be available via the debug endpoint. Please be certain that access to the debug endpoint is locked down in a production environment. -The `debug` section takes a single, required `addr` parameter. This parameter -specifies the `HOST:PORT` on which the debug server should accept connections. +The `debug` section takes a single required `addr` parameter, which specifies +the `HOST:PORT` on which the debug server should accept connections. - -### headers +### `headers` The `headers` option is **optional** . Use it to specify headers that the HTTP server should include in responses. This can be used for security headers such @@ -1207,35 +797,20 @@ header's payload values. Including `X-Content-Type-Options: [nosniff]` is recommended, so that browsers will not interpret content as HTML if they are directed to load a page from the -registry. This header is included in the example configuration files. +registry. This header is included in the example configuration file. -### http2 +### `http2` -The `http2` struct within `http` is **optional**. Use this to control http2 +The `http2` structure within `http` is **optional**. Use this to control http2 settings for the registry. - - - - - - - - - - - -
ParameterRequiredDescription
- disabled - - no - - A boolean that determines if http2 support should be disabled -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `disabled` | no | If `true`, then `http2` support is disabled. | -## notifications +## `notifications` -``` +```none notifications: endpoints: - name: alistener @@ -1252,134 +827,25 @@ notifications: The notifications option is **optional** and currently may contain a single option, `endpoints`. -### endpoints +### `endpoints` -Endpoints is a list of named services (URLs) that can accept event notifications. +The `endpoints` structure contains a list of named services (URLs) that can +accept event notifications. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- name - - yes - -A human readable name for the service. -
- disabled - - no - -A boolean to enable/disable notifications for a service. -
- url - - yes - -The URL to which events should be published. -
- headers - - yes - - Static headers to add to each request. Each header's name should be a key - underneath headers, and each value is a list of payloads for that - header name. Note that values must always be lists. -
- timeout - - yes - - An HTTP timeout value. This field takes a positive integer and an optional - suffix indicating the unit of time. Possible units are: -
    -
  • ns (nanoseconds)
    • -
  • us (microseconds)
    • -
  • ms (milliseconds)
    • -
  • s (seconds)
    • -
  • m (minutes)
    • -
  • h (hours)
    • -
- If you omit the suffix, the system interprets the value as nanoseconds. -
- threshold - - yes - - An integer specifying how long to wait before backing off a failure. -
- backoff - - yes - - How long the system backs off before retrying. This field takes a positive - integer and an optional suffix indicating the unit of time. Possible units - are: -
    -
  • ns (nanoseconds)
    • -
  • us (microseconds)
    • -
  • ms (milliseconds)
    • -
  • s (seconds)
    • -
  • m (minutes)
    • -
  • h (hours)
    • -
- If you omit the suffix, the system interprets the value as nanoseconds. -
- ignoredmediatypes - - no - - List of target media types to ignore. An event whose target media type - is present in this list will not be published to the endpoint. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `name` | yes | A human-readable name for the service. | +| `disabled` | no | If `true`, notifications are disabled for the service.| +| `url` | yes | The URL to which events should be published. | +| `headers` | yes | A list of static headers to add to each request. Each header's name is a key beneath `headers`, and each value is a list of payloads for that header name. Values must always be lists. | +| `timeout` | yes | A value for the HTTP timeout. A positive integer and an optional suffix indicating the unit of time, which may be `ns`, `us`, `ms`, `s`, `m`, or `h`. If you omit the unit of time, `ns` is used. | +| `threshold` | yes | An integer specifying how long to wait before backing off a failure. | +| `backoff` | yes | How long the system backs off before retrying after a failure. A positive integer and an optional suffix indicating the unit of time, which may be `ns`, `us`, `ms`, `s`, `m`, or `h`. If you omit the unit of time, `ns` is used. | +| `ignoredmediatypes`|no| A list of target media types to ignore. Events with these target media types are not published to the endpoint. | +## `redis` -## redis - -``` +```none redis: addr: localhost:6379 password: asecret @@ -1393,147 +859,44 @@ redis: idletimeout: 300s ``` -Declare parameters for constructing the redis connections. Registry instances -may use the Redis instance for several applications. The current purpose is -caching information about immutable blobs. Most of the options below control -how the registry connects to redis. You can control the pool's behavior -with the [pool](#pool) subsection. +Declare parameters for constructing the `redis` connections. Registry instances +may use the Redis instance for several applications. Currently, it caches +information about immutable blobs. Most of the `redis` options control +how the registry connects to the `redis` instance. You can control the pool's +behavior with the [pool](#pool) subsection. -It's advisable to configure Redis itself with the **allkeys-lru** eviction policy -as the registry does not set an expire value on keys. +You should configure Redis with the **allkeys-lru** eviction policy, because the +registry does not set an expiration value on keys. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- addr - - yes - - Address (host and port) of redis instance. -
- password - - no - - A password used to authenticate to the redis instance. -
- db - - no - - Selects the db for each connection. -
- dialtimeout - - no - - Timeout for connecting to a redis instance. -
- readtimeout - - no - - Timeout for reading from redis connections. -
- writetimeout - - no - - Timeout for writing to redis connections. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `addr` | yes | The address (host and port) of the Redis instance. | +| `password`| no | A password used to authenticate to the Redis instance.| +| `db` | no | The name of the database to use for each connection. | +| `dialtimeout` | no | The timeout for connecting to the Redis instance. | +| `readtimeout` | no | The timeout for reading from the Redis instance. | +| `writetimeout` | no | The timeout for writing to the Redis instance. | +### `pool` -### pool - -``` +```none pool: maxidle: 16 maxactive: 64 idletimeout: 300s ``` -Configure the behavior of the Redis connection pool. +Use these settings to configure the behavior of the Redis connection pool. - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- maxidle - - no - - Sets the maximum number of idle connections. -
- maxactive - - no - - sets the maximum number of connections that should - be opened before blocking a connection request. -
- idletimeout - - no - - sets the amount time to wait before closing - inactive connections. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `maxidle` | no | The maximum number of idle connections in the pool. | +| `maxactive`| no | The maximum number of connections which can be open before blocking a connection request. | +| `idletimeout`| no | How long to wait before closing inactive connections. | -## health +## `health` -``` +```none health: storagedriver: enabled: true @@ -1557,312 +920,66 @@ health: threshold: 3 ``` -The health option is **optional**. It may contain preferences for a periodic -health check on the storage driver's backend storage, and optional periodic -checks on local files, HTTP URIs, and/or TCP servers. The results of the health -checks are available at /debug/health on the debug HTTP server if the debug -HTTP server is enabled (see http section). +The health option is **optional**, and contains preferences for a periodic +health check on the storage driver's backend storage, as well as optional +periodic checks on local files, HTTP URIs, and/or TCP servers. The results of +the health checks are available at the `/debug/health` endpoint on the debug +HTTP server if the debug HTTP server is enabled (see http section). -### storagedriver +### `storagedriver` -storagedriver contains options for a health check on the configured storage -driver's backend storage. enabled must be set to true for this health check to -be active. +The `storagedriver` structure contains options for a health check on the +configured storage driver's backend storage. The health check is only active +when `enabled` is set to `true`. - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- enabled - - yes - -"true" to enable the storage driver health check or "false" to disable it. -
- interval - - no - - The length of time to wait between repetitions of the check. This field - takes a positive integer and an optional suffix indicating the unit of - time. Possible units are: -
    -
  • ns (nanoseconds)
    • -
  • us (microseconds)
    • -
  • ms (milliseconds)
    • -
  • s (seconds)
    • -
  • m (minutes)
    • -
  • h (hours)
    • -
- If you omit the suffix, the system interprets the value as nanoseconds. - The default value is 10 seconds if this field is omitted. -
- threshold - - no - - An integer specifying the number of times the check must fail before the - check triggers an unhealthy state. If this filed is not specified, a - single failure will trigger an unhealthy state. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `enabled` | yes | Set to `true` to enable storage driver health checks or `false` to disable them. | +| `interval`| no | How long to wait between repetitions of the storage driver health check. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. Defaults to `10s` if the value is omitted. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. | +| `threshold`| no | A positive integer which represents the number of times the check must fail before the state is marked as unhealthy. If not specified, a single failure marks the state as unhealthy. | -### file +### `file` -file is a list of paths to be periodically checked for the existence of a file. -If a file exists at the given path, the health check will fail. This can be -used as a way of bringing a registry out of rotation by creating a file. +The `file` structure includes a list of paths to be periodically checked for the\ +existence of a file. If a file exists at the given path, the health check will +fail. You can use this mechanism to bring a registry out of rotation by creating +a file. - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- file - - yes - -The path to check for the existence of a file. -
- interval - - no - - The length of time to wait between repetitions of the check. This field - takes a positive integer and an optional suffix indicating the unit of - time. Possible units are: -
    -
  • ns (nanoseconds)
    • -
  • us (microseconds)
    • -
  • ms (milliseconds)
    • -
  • s (seconds)
    • -
  • m (minutes)
    • -
  • h (hours)
    • -
- If you omit the suffix, the system interprets the value as nanoseconds. - The default value is 10 seconds if this field is omitted. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `file` | yes | The path to check for existence of a file. | +| `interval`| no | How long to wait before repeating the check. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. Defaults to `10s` if the value is omitted. | -### http +### `http` -http is a list of HTTP URIs to be periodically checked with HEAD requests. If -a HEAD request doesn't complete or returns an unexpected status code, the -health check will fail. +The `http` structure includes a list of HTTP URIs to periodically check with +`HEAD` requests. If a `HEAD` request does not complete or returns an unexpected +status code, the health check will fail. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- uri - - yes - -The URI to check. -
- headers - - no - - Static headers to add to each request. Each header's name should be a key - underneath headers, and each value is a list of payloads for that - header name. Note that values must always be lists. -
- statuscode - - no - -Expected status code from the HTTP URI. Defaults to 200. -
- timeout - - no - - The length of time to wait before timing out the HTTP request. This field - takes a positive integer and an optional suffix indicating the unit of - time. Possible units are: -
    -
  • ns (nanoseconds)
    • -
  • us (microseconds)
    • -
  • ms (milliseconds)
    • -
  • s (seconds)
    • -
  • m (minutes)
    • -
  • h (hours)
    • -
- If you omit the suffix, the system interprets the value as nanoseconds. -
- interval - - no - - The length of time to wait between repetitions of the check. This field - takes a positive integer and an optional suffix indicating the unit of - time. Possible units are: -
    -
  • ns (nanoseconds)
    • -
  • us (microseconds)
    • -
  • ms (milliseconds)
    • -
  • s (seconds)
    • -
  • m (minutes)
    • -
  • h (hours)
    • -
- If you omit the suffix, the system interprets the value as nanoseconds. - The default value is 10 seconds if this field is omitted. -
- threshold - - no - - An integer specifying the number of times the check must fail before the - check triggers an unhealthy state. If this filed is not specified, a - single failure will trigger an unhealthy state. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `uri` | yes | The URI to check. | +| `headers` | no | Static headers to add to each request. Each header's name is a key beneath `headers`, and each value is a list of payloads for that header name. Values must always be lists. | +| `statuscode` | no | The expected status code from the HTTP URI. Defaults to `200`. | +| `timeout` | no | How long to wait before timing out the HTTP request. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. | +| `interval`| no | How long to wait before repeating the check. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. Defaults to `10s` if the value is omitted. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. | +| `threshold`| no | The number of times the check must fail before the state is marked as unhealthy. If this field is not specified, a single failure marks the state as unhealthy. | -### tcp +### `tcp` -tcp is a list of TCP addresses to be periodically checked with connection -attempts. The addresses must include port numbers. If a connection attempt -fails, the health check will fail. +The `tcp` structure includes a list of TCP addresses to periodically check using +TCP connection attempts. Addresses must include port numbers. If a connection +attempt fails, the health check will fail. - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- addr - - yes - -The TCP address to connect to, including a port number. -
- timeout - - no - - The length of time to wait before timing out the TCP connection. This - field takes a positive integer and an optional suffix indicating the unit - of time. Possible units are: -
    -
  • ns (nanoseconds)
    • -
  • us (microseconds)
    • -
  • ms (milliseconds)
    • -
  • s (seconds)
    • -
  • m (minutes)
    • -
  • h (hours)
    • -
- If you omit the suffix, the system interprets the value as nanoseconds. -
- interval - - no - - The length of time to wait between repetitions of the check. This field - takes a positive integer and an optional suffix indicating the unit of - time. Possible units are: -
    -
  • ns (nanoseconds)
    • -
  • us (microseconds)
    • -
  • ms (milliseconds)
    • -
  • s (seconds)
    • -
  • m (minutes)
    • -
  • h (hours)
    • -
- If you omit the suffix, the system interprets the value as nanoseconds. - The default value is 10 seconds if this field is omitted. -
- threshold - - no - - An integer specifying the number of times the check must fail before the - check triggers an unhealthy state. If this filed is not specified, a - single failure will trigger an unhealthy state. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `addr` | yes | The TCP address and port to connect to. | +| `timeout` | no | How long to wait before timing out the TCP connection. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. | +| `interval`| no | How long to wait between repetitions of the check. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. Defaults to `10s` if the value is omitted. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. | +| `threshold`| no | The number of times the check must fail before the state is marked as unhealthy. If this field is not specified, a single failure marks the state as unhealthy. | -## Proxy + +## `proxy` ``` proxy: @@ -1871,89 +988,47 @@ proxy: password: [password] ``` -Proxy enables a registry to be configured as a pull through cache to the official Docker Hub. See [mirror](https://github.com/docker/docker.github.io/tree/master/registry/recipes/mirror.md) for more information. Pushing to a registry configured as a pull through cache is currently unsupported. +The `proxy` structure allows a registry to be configured as a pull-through cache +to Docker Hub. See +[mirror](https://github.com/docker/docker.github.io/tree/master/registry/recipes/mirror.md) +for more information. Pushing to a registry configured as a pull-through cache +is unsupported. - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- remoteurl - - yes - - The URL of the official Docker Hub -
- username - - no - - The username of the Docker Hub account -
- password - - no - - The password for the official Docker Hub account -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `remoteurl`| yes | The URL for the repository on Docker Hub. | +| `username` | no | The username registered with Docker Hub which has access to the repository. | +| `password` | no | The password used to authenticate to Docker Hub using the username specified in `username`. | -To enable pulling private repositories (e.g. `batman/robin`) a username and password for user `batman` must be specified. Note: These private repositories will be stored in the proxy cache's storage and relevant measures should be taken to protect access to this. -## Compatibility +To enable pulling private repositories (e.g. `batman/robin`) specify the +username (such as `batman`) and the password for that username. -``` +> **Note**: These private repositories are stored in the proxy cache's storage. +> Take appropriate measures to protect access to the proxy cache. + +## `compatibility` + +```none compatibility: schema1: signingkeyfile: /etc/registry/key.json ``` -Configure handling of older and deprecated features. Each subsection -defines such a feature with configurable behavior. +Use the `compatibility` structure to configure handling of older and deprecated +features. Each subsection defines such a feature with configurable behavior. -### Schema1 +### `schema1` - - - - - - - - - - - -
ParameterRequiredDescription
- signingkeyfile - - no - - The signing private key used for adding signatures to schema1 manifests. - If no signing key is provided, a new ECDSA key will be generated on - startup. -
+| Parameter | Required | Description | +|-----------|----------|-------------------------------------------------------| +| `signingkeyfile` | no | The signing private key used to add signatures to `schema1` manifests. If no signing key is provided, a new ECDSA key is generated when the registry starts. | -## Validation +## `validation` ```none validation: + enabled: true manifests: urls: allow: @@ -1962,33 +1037,35 @@ validation: - ^https?://www\.example\.com/ ``` -### Enabled +### `enabled` Use the `enabled` flag to enable the other options in the `validation` section. They are disabled by default. -### Manifests +### `manifests` Use the `manifest` subsection to configure manifest validation. -#### URLs +#### `urls` -The `allow` and `deny` options are both lists of +The `allow` and `deny` options are each a list of [regular expressions](https://godoc.org/regexp/syntax) that restrict the URLs in pushed manifests. -If `allow` is unset, pushing a manifest containing URLs will fail. +If `allow` is unset, pushing a manifest containing URLs fails. -If `allow` is set, pushing a manifest will succeed only if all URLs within match -one of the `allow` regular expressions and one of the following holds: -1. `deny` is unset. -2. `deny` is set but no URLs within the manifest match any of the `deny` regular expressions. +If `allow` is set, pushing a manifest succeeds only if all URLs match +one of the `allow` regular expressions **and** one of the following holds: + +1. `deny` is unset. +2. `deny` is set but no URLs within the manifest match any of the `deny` regular + expressions. ## Example: Development configuration -The following is a simple example you can use for local development: +You can use this simple example for local development: -``` +```none version: 0.1 log: level: debug @@ -2002,67 +1079,43 @@ http: addr: localhost:5001 ``` -The above configures the registry instance to run on port `5000`, binding to -`localhost`, with the `debug` server enabled. Registry data storage is in the -`/var/lib/registry` directory. Logging is in `debug` mode, which is the most +This example configures the registry instance to run on port `5000`, binding to +`localhost`, with the `debug` server enabled. Registry data is stored in the +`/var/lib/registry` directory. Logging is set to `debug` mode, which is the most verbose. -A similar simple configuration is available at -[config-example.yml](https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml). -Both are generally useful for local development. +See +[config-example.yml](https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml) +for another simple configuration. Both examples are generally useful for local +development. ## Example: Middleware configuration -This example illustrates how to configure storage middleware in a registry. -Middleware allows the registry to serve layers via a content delivery network -(CDN). This is useful for reducing requests to the storage layer. +This example configures [Amazon Cloudfront](http://aws.amazon.com/cloudfront/) +as the storage middleware in a registry. Middleware allows the registry to serve +layers via a content delivery network (CDN). This reduces requests to the +storage layer. -The registry supports [Amazon -Cloudfront](http://aws.amazon.com/cloudfront/). You can only use Cloudfront in -conjunction with the S3 storage driver. +Cloudfront requires the S3 storage driver. - - - - - - - - - - - - - - - - - -
ParameterDescription
nameThe storage middleware name. Currently cloudfront is an accepted value.
disabledSet to false to easily disable the middleware.
options: - A set of key/value options to configure the middleware. -
    -
  • baseurl: The Cloudfront base URL.
    • -
  • privatekey: The location of your AWS private key on the filesystem.
    • -
  • keypairid: The ID of your Cloudfront keypair.
    • -
  • duration: The duration in minutes for which the URL is valid. Default is 20.
    • -
-
+This is the configuration expressed in YAML: -The following example illustrates these values: - -``` +```none middleware: - storage: - - name: cloudfront - disabled: false - options: - baseurl: http://d111111abcdef8.cloudfront.net - privatekey: /path/to/asecret.pem - keypairid: asecret - duration: 60 + storage: + - name: cloudfront + disabled: false + options: + baseurl: http://d111111abcdef8.cloudfront.net + privatekey: /path/to/asecret.pem + keypairid: asecret + duration: 60 ``` ->**Note**: Cloudfront keys exist separately to other AWS keys. See ->[the documentation on AWS credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html) ->for more information. +See the configuration reference for [Cloudfront](#cloudfront) for more +information about configuration options. + +> **Note**: Cloudfront keys exist separately from other AWS keys. See +> [the documentation on AWS credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html) +> for more information. From 325b0804fef3a66309d962357aac3c2ce3f4d329 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Tue, 17 Jan 2017 16:16:05 -0800 Subject: [PATCH 09/12] Update release notes for 2.6 Signed-off-by: Derek McGowan (github: dmcgowan) --- CHANGELOG.md | 103 ++++++++++++++++++++++++--------------------------- 1 file changed, 48 insertions(+), 55 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c07a4e4..e7b16b3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,76 +1,69 @@ # Changelog -## 2.6.0-rc2 (2016-12-20) - -#### Spec - - Authorization: add support for repository classes - -#### Registry - - Add policy configuration for enforcing repository classes - - -## 2.6.0-rc1 (2016-10-10) +## 2.6.0 (2017-01-18) #### Storage - - S3: fixed bug in delete due to read-after-write inconsistency - - S3: allow EC2 IAM roles to be used when authorizing region endpoints - - S3: add Object ACL Support - - S3: fix delete method's notion of subpaths - - S3: use multipart upload API in `Move` method for performance - - S3: add v2 signature signing for legacy S3 clones - - Swift: add simple heuristic to detect incomplete DLOs during read ops - - Swift: support different user and tenant domains - - Swift: bulk deletes in chunks - - Aliyun OSS: fix delete method's notion of subpaths - - Aliyun OSS: optimize data copy after upload finishes - - Azure: close leaking response body - - Fix storage drivers dropping non-EOF errors when listing repositories - - Compare path properly when listing repositories in catalog - - Add a foreign layer URL host whitelist - - Improve catalog enumerate runtime +- S3: fixed bug in delete due to read-after-write inconsistency +- S3: allow EC2 IAM roles to be used when authorizing region endpoints +- S3: add Object ACL Support +- S3: fix delete method's notion of subpaths +- S3: use multipart upload API in `Move` method for performance +- S3: add v2 signature signing for legacy S3 clones +- Swift: add simple heuristic to detect incomplete DLOs during read ops +- Swift: support different user and tenant domains +- Swift: bulk deletes in chunks +- Aliyun OSS: fix delete method's notion of subpaths +- Aliyun OSS: optimize data copy after upload finishes +- Azure: close leaking response body +- Fix storage drivers dropping non-EOF errors when listing repositories +- Compare path properly when listing repositories in catalog +- Add a foreign layer URL host whitelist +- Improve catalog enumerate runtime #### Registry - - Override media type returned from `Stat()` for existing manifests - - Export `storage.CreateOptions` in top-level package - - Enable notifications to endpoints that use self-signed certificates - - Properly validate multi-URL foreign layers - - Add control over validation of URLs in pushed manifests - - Proxy mode: fix socket leak when pull is cancelled - - Tag service: properly handle error responses on HEAD request - - Support for custom authentication URL in proxying registry - - Add configuration option to disable access logging - - Add notification filtering by target media type - - Manifest: `References()` returns all children - - Honor `X-Forwarded-Port` and Forwarded headers - - Reference: Preserve tag and digest in With* functions +- Export `storage.CreateOptions` in top-level package +- Enable notifications to endpoints that use self-signed certificates +- Properly validate multi-URL foreign layers +- Add control over validation of URLs in pushed manifests +- Proxy mode: fix socket leak when pull is cancelled +- Tag service: properly handle error responses on HEAD request +- Support for custom authentication URL in proxying registry +- Add configuration option to disable access logging +- Add notification filtering by target media type +- Manifest: `References()` returns all children +- Honor `X-Forwarded-Port` and Forwarded headers +- Reference: Preserve tag and digest in With* functions +- Add policy configuration for enforcing repository classes #### Client - - Changes the client Tags `All()` method to follow links - - Allow registry clients to connect via HTTP2 - - Better handling of OAuth errors in client +- Changes the client Tags `All()` method to follow links +- Allow registry clients to connect via HTTP2 +- Better handling of OAuth errors in client #### Spec - - Manifest: clarify relationship between urls and foreign layers +- Manifest: clarify relationship between urls and foreign layers +- Authorization: add support for repository classes #### Manifest - - Add plugin mediatype to distribution manifest +- Override media type returned from `Stat()` for existing manifests +- Add plugin mediatype to distribution manifest #### Docs - - - Document `TOOMANYREQUESTS` error code - - Document required Let's Encrypt port - - Improve documentation around implementation of OAuth2 +- Document `TOOMANYREQUESTS` error code +- Document required Let's Encrypt port +- Improve documentation around implementation of OAuth2 +- Improve documentation for configuration #### Auth - - Add support for registry type in scope - - Add support for using v2 ping challenges for v1 - - Add leeway to JWT `nbf` and `exp` checking - - htpasswd: dynamically parse htpasswd file - - Fix missing auth headers with PATCH HTTP request when pushing to default port +- Add support for registry type in scope +- Add support for using v2 ping challenges for v1 +- Add leeway to JWT `nbf` and `exp` checking +- htpasswd: dynamically parse htpasswd file +- Fix missing auth headers with PATCH HTTP request when pushing to default port #### Dockerfile - - Update to go1.7 - - Reorder Dockerfile steps for better layer caching +- Update to go1.7 +- Reorder Dockerfile steps for better layer caching #### Notes From d0b7c920040cf4b0664bb8833470b1d2b1b18ccc Mon Sep 17 00:00:00 2001 From: Troels Thomsen Date: Mon, 20 Mar 2017 16:10:36 -0700 Subject: [PATCH 10/12] Add test for precendence with standard port Signed-off-by: Troels Thomsen Signed-off-by: Derek McGowan (github: dmcgowan) --- registry/api/v2/urls_test.go | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/registry/api/v2/urls_test.go b/registry/api/v2/urls_test.go index 16f16269..52ef9ee2 100644 --- a/registry/api/v2/urls_test.go +++ b/registry/api/v2/urls_test.go @@ -236,6 +236,22 @@ func TestBuilderFromRequest(t *testing.T) { }}, base: "http://example.com:443", }, + { + name: "forwarded standard port with non-standard headers", + request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ + "X-Forwarded-Proto": []string{"https"}, + "X-Forwarded-Port": []string{"443"}, + }}, + base: "https://example.com", + }, + { + name: "forwarded standard port with non-standard headers and explicit port", + request: &http.Request{URL: u, Host: u.Host + ":443", Header: http.Header{ + "X-Forwarded-Proto": []string{"https"}, + "X-Forwarded-Port": []string{"443"}, + }}, + base: "https://example.com:443", + }, { name: "several non-standard headers", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ From 5c43c3b0ee230ca8a257dd37e0562bdaa66f04e0 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Mon, 20 Mar 2017 16:13:33 -0700 Subject: [PATCH 11/12] Remove support for X-Forwarded-Port Partially reverts change adding support for X-Forwarded-Port. Changes the logic to prefer the standard Forwarded header over X-Forwarded headers. Prefer forwarded "host" over "for" since "for" represents the client and not the client's request. Signed-off-by: Derek McGowan (github: dmcgowan) --- registry/api/v2/urls.go | 113 +++++------------ registry/api/v2/urls_test.go | 237 ++++++----------------------------- 2 files changed, 72 insertions(+), 278 deletions(-) diff --git a/registry/api/v2/urls.go b/registry/api/v2/urls.go index e2e242ea..5e24ca9b 100644 --- a/registry/api/v2/urls.go +++ b/registry/api/v2/urls.go @@ -1,10 +1,8 @@ package v2 import ( - "net" "net/http" "net/url" - "strconv" "strings" "github.com/docker/distribution/reference" @@ -48,66 +46,42 @@ func NewURLBuilderFromString(root string, relative bool) (*URLBuilder, error) { // NewURLBuilderFromRequest uses information from an *http.Request to // construct the root url. func NewURLBuilderFromRequest(r *http.Request, relative bool) *URLBuilder { - var scheme string - - forwardedProto := r.Header.Get("X-Forwarded-Proto") - // TODO: log the error - forwardedHeader, _, _ := parseForwardedHeader(r.Header.Get("Forwarded")) - - switch { - case len(forwardedProto) > 0: - scheme = forwardedProto - case len(forwardedHeader["proto"]) > 0: - scheme = forwardedHeader["proto"] - case r.TLS != nil: - scheme = "https" - case len(r.URL.Scheme) > 0: - scheme = r.URL.Scheme - default: + var ( scheme = "http" + host = r.Host + ) + + if r.TLS != nil { + scheme = "https" + } else if len(r.URL.Scheme) > 0 { + scheme = r.URL.Scheme } - host := r.Host - - if forwardedHost := r.Header.Get("X-Forwarded-Host"); len(forwardedHost) > 0 { - // According to the Apache mod_proxy docs, X-Forwarded-Host can be a - // comma-separated list of hosts, to which each proxy appends the - // requested host. We want to grab the first from this comma-separated - // list. - hosts := strings.SplitN(forwardedHost, ",", 2) - host = strings.TrimSpace(hosts[0]) - } else if addr, exists := forwardedHeader["for"]; exists { - host = addr - } else if h, exists := forwardedHeader["host"]; exists { - host = h - } - - portLessHost, port := host, "" - if !isIPv6Address(portLessHost) { - // with go 1.6, this would treat the last part of IPv6 address as a port - portLessHost, port, _ = net.SplitHostPort(host) - } - if forwardedPort := r.Header.Get("X-Forwarded-Port"); len(port) == 0 && len(forwardedPort) > 0 { - ports := strings.SplitN(forwardedPort, ",", 2) - forwardedPort = strings.TrimSpace(ports[0]) - if _, err := strconv.ParseInt(forwardedPort, 10, 32); err == nil { - port = forwardedPort + // Handle fowarded headers + // Prefer "Forwarded" header as defined by rfc7239 if given + // see https://tools.ietf.org/html/rfc7239 + if forwarded := r.Header.Get("Forwarded"); len(forwarded) > 0 { + forwardedHeader, _, err := parseForwardedHeader(forwarded) + if err == nil { + if fproto := forwardedHeader["proto"]; len(fproto) > 0 { + scheme = fproto + } + if fhost := forwardedHeader["host"]; len(fhost) > 0 { + host = fhost + } } - } - - if len(portLessHost) > 0 { - host = portLessHost - } - if len(port) > 0 { - // remove enclosing brackets of ipv6 address otherwise they will be duplicated - if len(host) > 1 && host[0] == '[' && host[len(host)-1] == ']' { - host = host[1 : len(host)-1] + } else { + if forwardedProto := r.Header.Get("X-Forwarded-Proto"); len(forwardedProto) > 0 { + scheme = forwardedProto + } + if forwardedHost := r.Header.Get("X-Forwarded-Host"); len(forwardedHost) > 0 { + // According to the Apache mod_proxy docs, X-Forwarded-Host can be a + // comma-separated list of hosts, to which each proxy appends the + // requested host. We want to grab the first from this comma-separated + // list. + hosts := strings.SplitN(forwardedHost, ",", 2) + host = strings.TrimSpace(hosts[0]) } - // JoinHostPort properly encloses ipv6 addresses in square brackets - host = net.JoinHostPort(host, port) - } else if isIPv6Address(host) && host[0] != '[' { - // ipv6 needs to be enclosed in square brackets in urls - host = "[" + host + "]" } basePath := routeDescriptorsMap[RouteNameBase].Path @@ -287,28 +261,3 @@ func appendValues(u string, values ...url.Values) string { return appendValuesURL(up, values...).String() } - -// isIPv6Address returns true if given string is a valid IPv6 address. No port is allowed. The address may be -// enclosed in square brackets. -func isIPv6Address(host string) bool { - if len(host) > 1 && host[0] == '[' && host[len(host)-1] == ']' { - host = host[1 : len(host)-1] - } - // The IPv6 scoped addressing zone identifier starts after the last percent sign. - if i := strings.LastIndexByte(host, '%'); i > 0 { - host = host[:i] - } - ip := net.ParseIP(host) - if ip == nil { - return false - } - if ip.To16() == nil { - return false - } - if ip.To4() == nil { - return true - } - // dot can be present in ipv4-mapped address, it needs to come after a colon though - i := strings.IndexAny(host, ":.") - return i >= 0 && host[i] == ':' -} diff --git a/registry/api/v2/urls_test.go b/registry/api/v2/urls_test.go index 52ef9ee2..6d8973fa 100644 --- a/registry/api/v2/urls_test.go +++ b/registry/api/v2/urls_test.go @@ -179,7 +179,7 @@ func TestBuilderFromRequest(t *testing.T) { { name: "https protocol forwarded with a non-standard header", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "X-Forwarded-Proto": []string{"https"}, + "X-Custom-Forwarded-Proto": []string{"https"}, }}, base: "http://example.com", }, @@ -225,6 +225,7 @@ func TestBuilderFromRequest(t *testing.T) { { name: "forwarded port with a non-standard header", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ + "X-Forwarded-Host": []string{"example.com:5000"}, "X-Forwarded-Port": []string{"5000"}, }}, base: "http://example.com:5000", @@ -234,12 +235,13 @@ func TestBuilderFromRequest(t *testing.T) { request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ "X-Forwarded-Port": []string{"443 , 5001"}, }}, - base: "http://example.com:443", + base: "http://example.com", }, { name: "forwarded standard port with non-standard headers", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ "X-Forwarded-Proto": []string{"https"}, + "X-Forwarded-Host": []string{"example.com"}, "X-Forwarded-Port": []string{"443"}, }}, base: "https://example.com", @@ -248,6 +250,7 @@ func TestBuilderFromRequest(t *testing.T) { name: "forwarded standard port with non-standard headers and explicit port", request: &http.Request{URL: u, Host: u.Host + ":443", Header: http.Header{ "X-Forwarded-Proto": []string{"https"}, + "X-Forwarded-Host": []string{u.Host + ":443"}, "X-Forwarded-Port": []string{"443"}, }}, base: "https://example.com:443", @@ -256,10 +259,9 @@ func TestBuilderFromRequest(t *testing.T) { name: "several non-standard headers", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ "X-Forwarded-Proto": []string{"https"}, - "X-Forwarded-Host": []string{" first.example.com "}, - "X-Forwarded-Port": []string{" 12345 \t"}, + "X-Forwarded-Host": []string{" first.example.com:12345 "}, }}, - base: "http://first.example.com:12345", + base: "https://first.example.com:12345", }, { name: "forwarded host with port supplied takes priority", @@ -280,16 +282,16 @@ func TestBuilderFromRequest(t *testing.T) { { name: "forwarded protocol and addr using standard header", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`proto=https;for="192.168.22.30:80"`}, + "Forwarded": []string{`proto=https;host="192.168.22.30:80"`}, }}, base: "https://192.168.22.30:80", }, { - name: "forwarded addr takes priority over host", + name: "forwarded host takes priority over for", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`host=reg.example.com;for="192.168.22.30:5000"`}, + "Forwarded": []string{`host="reg.example.com:5000";for="192.168.22.30"`}, }}, - base: "http://192.168.22.30:5000", + base: "http://reg.example.com:5000", }, { name: "forwarded host and protocol using standard header", @@ -308,73 +310,26 @@ func TestBuilderFromRequest(t *testing.T) { { name: "process just the first list element of standard header", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`for="reg.example.com:443";proto=https, for="reg.example.com:80";proto=http`}, + "Forwarded": []string{`host="reg.example.com:443";proto=https, host="reg.example.com:80";proto=http`}, }}, base: "https://reg.example.com:443", }, { - name: "IPv6 address override port", + name: "IPv6 address use host", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`for="2607:f0d0:1002:51::4"`}, - "X-Forwarded-Port": []string{"5001"}, + "Forwarded": []string{`for="2607:f0d0:1002:51::4";host="[2607:f0d0:1002:51::4]:5001"`}, + "X-Forwarded-Port": []string{"5002"}, }}, base: "http://[2607:f0d0:1002:51::4]:5001", }, { name: "IPv6 address with port", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`for="[2607:f0d0:1002:51::4]:4000"`}, + "Forwarded": []string{`host="[2607:f0d0:1002:51::4]:4000"`}, "X-Forwarded-Port": []string{"5001"}, }}, base: "http://[2607:f0d0:1002:51::4]:4000", }, - { - name: "IPv6 long address override port", - request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`for="2607:f0d0:1002:0051:0000:0000:0000:0004"`}, - "X-Forwarded-Port": []string{"5001"}, - }}, - base: "http://[2607:f0d0:1002:0051:0000:0000:0000:0004]:5001", - }, - { - name: "IPv6 long address enclosed in brackets - be benevolent", - request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`for="[2607:f0d0:1002:0051:0000:0000:0000:0004]"`}, - "X-Forwarded-Port": []string{"5001"}, - }}, - base: "http://[2607:f0d0:1002:0051:0000:0000:0000:0004]:5001", - }, - { - name: "IPv6 long address with port", - request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`for="[2607:f0d0:1002:0051:0000:0000:0000:0004]:4321"`}, - "X-Forwarded-Port": []string{"5001"}, - }}, - base: "http://[2607:f0d0:1002:0051:0000:0000:0000:0004]:4321", - }, - { - name: "IPv6 address with zone ID", - request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`for="fe80::bd0f:a8bc:6480:238b%11"`}, - "X-Forwarded-Port": []string{"5001"}, - }}, - base: "http://[fe80::bd0f:a8bc:6480:238b%2511]:5001", - }, - { - name: "IPv6 address with zone ID and port", - request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`for="[fe80::bd0f:a8bc:6480:238b%eth0]:12345"`}, - "X-Forwarded-Port": []string{"5001"}, - }}, - base: "http://[fe80::bd0f:a8bc:6480:238b%25eth0]:12345", - }, - { - name: "IPv6 address without port", - request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ - "Forwarded": []string{`for="::FFFF:129.144.52.38"`}, - }}, - base: "http://[::FFFF:129.144.52.38]", - }, { name: "non-standard and standard forward headers", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ @@ -386,14 +341,34 @@ func TestBuilderFromRequest(t *testing.T) { base: "https://first.example.com", }, { - name: "non-standard headers take precedence over standard one", + name: "standard header takes precedence over non-standard headers", request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ "X-Forwarded-Proto": []string{`http`}, "Forwarded": []string{`host=second.example.com; proto=https`}, "X-Forwarded-Host": []string{`first.example.com`}, "X-Forwarded-Port": []string{`4000`}, }}, - base: "http://first.example.com:4000", + base: "https://second.example.com", + }, + { + name: "incomplete standard header uses default", + request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ + "X-Forwarded-Proto": []string{`https`}, + "Forwarded": []string{`for=127.0.0.1`}, + "X-Forwarded-Host": []string{`first.example.com`}, + "X-Forwarded-Port": []string{`4000`}, + }}, + base: "http://" + u.Host, + }, + { + name: "standard with just proto", + request: &http.Request{URL: u, Host: u.Host, Header: http.Header{ + "X-Forwarded-Proto": []string{`https`}, + "Forwarded": []string{`proto=https`}, + "X-Forwarded-Host": []string{`first.example.com`}, + "X-Forwarded-Port": []string{`4000`}, + }}, + base: "https://" + u.Host, }, } @@ -412,23 +387,9 @@ func TestBuilderFromRequest(t *testing.T) { t.Fatalf("[relative=%t, request=%q, case=%q]: error building url: %v", relative, tr.name, testCase.description, err) } - var expectedURL string - proto, ok := tr.request.Header["X-Forwarded-Proto"] - if !ok { - expectedURL = testCase.expectedPath - if !relative { - expectedURL = tr.base + expectedURL - } - } else { - urlBase, err := url.Parse(tr.base) - if err != nil { - t.Fatal(err) - } - urlBase.Scheme = proto[0] - expectedURL = testCase.expectedPath - if !relative { - expectedURL = urlBase.String() + expectedURL - } + expectedURL := testCase.expectedPath + if !relative { + expectedURL = tr.base + expectedURL } if buildURL != expectedURL { @@ -521,119 +482,3 @@ func TestBuilderFromRequestWithPrefix(t *testing.T) { } } } - -func TestIsIPv6Address(t *testing.T) { - for _, tc := range []struct { - name string - address string - isIPv6 bool - }{ - { - name: "IPv6 short address", - address: `2607:f0d0:1002:51::4`, - isIPv6: true, - }, - { - name: "IPv6 short address enclosed in brackets", - address: "[2607:f0d0:1002:51::4]", - isIPv6: true, - }, - { - name: "IPv6 address", - address: `2607:f0d0:1002:0051:0000:0000:0000:0004`, - isIPv6: true, - }, - { - name: "IPv6 address with numeric zone ID", - address: `fe80::bd0f:a8bc:6480:238b%11`, - isIPv6: true, - }, - { - name: "IPv6 address with device name as zone ID", - address: `fe80::bd0f:a8bc:6480:238b%eth0`, - isIPv6: true, - }, - { - name: "IPv6 address with device name as zone ID enclosed in brackets", - address: `[fe80::bd0f:a8bc:6480:238b%eth0]`, - isIPv6: true, - }, - { - name: "IPv4-mapped address", - address: "::FFFF:129.144.52.38", - isIPv6: true, - }, - { - name: "localhost", - address: "::1", - isIPv6: true, - }, - { - name: "localhost", - address: "::1", - isIPv6: true, - }, - { - name: "long localhost address", - address: "0:0:0:0:0:0:0:1", - isIPv6: true, - }, - { - name: "IPv6 long address with port", - address: "[2607:f0d0:1002:0051:0000:0000:0000:0004]:4321", - isIPv6: false, - }, - { - name: "too many groups", - address: "2607:f0d0:1002:0051:0000:0000:0000:0004:4321", - isIPv6: false, - }, - { - name: "square brackets don't make an IPv6 address", - address: "[2607:f0d0]", - isIPv6: false, - }, - { - name: "require two consecutive colons in localhost", - address: ":1", - isIPv6: false, - }, - { - name: "more then 4 hexadecimal digits", - address: "2607:f0d0b:1002:0051:0000:0000:0000:0004", - isIPv6: false, - }, - { - name: "too short address", - address: `2607:f0d0:1002:0000:0000:0000:0004`, - isIPv6: false, - }, - { - name: "IPv4 address", - address: `192.168.100.1`, - isIPv6: false, - }, - { - name: "unclosed bracket", - address: `[2607:f0d0:1002:0051:0000:0000:0000:0004`, - isIPv6: false, - }, - { - name: "trailing bracket", - address: `2607:f0d0:1002:0051:0000:0000:0000:0004]`, - isIPv6: false, - }, - { - name: "domain name", - address: `localhost`, - isIPv6: false, - }, - } { - isIPv6 := isIPv6Address(tc.address) - if isIPv6 && !tc.isIPv6 { - t.Errorf("[%s] address %q falsely detected as IPv6 address", tc.name, tc.address) - } else if !isIPv6 && tc.isIPv6 { - t.Errorf("[%s] address %q not recognized as IPv6", tc.name, tc.address) - } - } -} From 74278cdaa6f5fd10e3b1995aebe62c98cad634f1 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Tue, 21 Mar 2017 10:49:45 -0700 Subject: [PATCH 12/12] Update release notes for 2.6.1-rc1 Release notes for forwarded header fix patch release Signed-off-by: Derek McGowan (github: dmcgowan) --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e7b16b3c..dc5167dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 2.6.1-rc1 (2017-03-21) + +#### Registry +- Fix `Forwarded` header handling, revert use of `X-Forwarded-Port` + ## 2.6.0 (2017-01-18) #### Storage