Skip to content

Latest commit

 

History

History
406 lines (348 loc) · 11.2 KB

server-config.md

File metadata and controls

406 lines (348 loc) · 11.2 KB
Raw

Notary server configuration file

This document is for those who are running their own Notary service and want to specify custom options.

Overview

A configuration file is required by Notary server, and the path to the configuration file must be specified using the -config option on the command line.

Notary server also allows you to increase/decrease the logging level without having to restart.

Here is a full server configuration file example; please click on the top level JSON keys to learn more about the configuration section corresponding to that key:

{
  "server": {
    "http_addr": ":4443",
    "tls_key_file": "./fixtures/notary-server.key",
    "tls_cert_file": "./fixtures/notary-server.crt"
  },
  "trust_service": {
    "type": "remote",
    "hostname": "notarysigner",
    "port": "7899",
    "key_algorithm": "ecdsa",
    "tls_ca_file": "./fixtures/root-ca.crt",
    "tls_client_cert": "./fixtures/notary-server.crt",
    "tls_client_key": "./fixtures/notary-server.key"
  },
  "storage": {
    "backend": "mysql",
    "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true"
  },
  "auth": {
    "type": "token",
    "options": {
      "realm": "https://auth.docker.io/token",
      "service": "notary-server",
      "issuer": "auth.docker.io",
      "rootcertbundle": "/path/to/auth.docker.io/cert"
    }
  },
  "logging": {
    "level": "debug"
  },
  "reporting": {
    "bugsnag": {
      "api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
      "release_stage": "production"
    }
  },
  "caching": {
    "max_age": {
      "current_metadata": 300,
      "consistent_metadata": 31536000,
    }
  },
  "repositories": {
    "gun_prefixes": ["docker.io/", "my-own-registry.com/"]
  }
}

server section (required)

Example:

"server": {
  "http_addr": ":4443",
  "tls_key_file": "./fixtures/notary-server.key",
  "tls_cert_file": "./fixtures/notary-server.crt"
}
Parameter Required Description
http_addr yes The TCP address (IP and port) to listen on. Examples:
  • ":4443" means listen on port 4443 on all IPs (and hence all interfaces, such as those listed when you run ifconfig)
  • "127.0.0.1:4443" means listen on port 4443 on localhost only. That means that the server will not be accessible except locally (via SSH tunnel, or just on a local terminal)
tls_key_file no The path to the private key to use for HTTPS. Must be provided together with tls_cert_file, or not at all. If neither are provided, the server will use HTTP instead of HTTPS. The path is relative to the directory of the configuration file.
tls_cert_file no The path to the certificate to use for HTTPS. Must be provided together with tls_key_file, or not at all. If neither are provided, the server will use HTTP instead of HTTPS. The path is relative to the directory of the configuration file.

trust_service section (required)

This section configures either a remote trust service, such as Notary signer or a local in-memory ED25519 trust service.

Remote trust service example:

"trust_service": {
  "type": "remote",
  "hostname": "notarysigner",
  "port": "7899",
  "key_algorithm": "ecdsa",
  "tls_ca_file": "./fixtures/root-ca.crt",
  "tls_client_cert": "./fixtures/notary-server.crt",
  "tls_client_key": "./fixtures/notary-server.key"
}

Local trust service example:

"trust_service": {
  "type": "local"
}
Parameter Required Description
type yes Must be "remote" or "local"
hostname yes if remote The hostname of the remote trust service
port yes if remote The GRPC port of the remote trust service
key_algorithm yes if remote Algorithm to use to generate keys stored on the signing service. Valid values are "ecdsa", "rsa", and "ed25519".
tls_ca_file no The path to the root CA that signed the TLS certificate of the remote service. This parameter must be provided if said root CA is not in the system's default trust roots. The path is relative to the directory of the configuration file.
tls_client_key no The path to the private key to use for TLS mutual authentication. This must be provided together with tls_client_cert or not at all. The path is relative to the directory of the configuration file.
tls_client_cert no The path to the certificate to use for TLS mutual authentication. This must be provided together with tls_client_key or not at all. The path is relative to the directory of the configuration file.

storage section (required)

The storage section specifies which storage backend the server should use to store TUF metadata. Only MySQL, PostgreSQL or an in-memory store is supported.

DB storage example:

"storage": {
  "backend": "mysql",
  "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true"
}
Parameter Required Description
backend yes Must be "mysql", "postgres" or "memory". If "memory" is selected, the db_url is ignored.
db_url yes if not memory The Data Source Name used to access the DB. (note: please include parseTime=true as part of the DSN)

auth section (optional)

This sections specifies the authentication options for the server. Currently, we only support token authentication.

Example:

"auth": {
  "type": "token",
  "options": {
    "realm": "https://auth.docker.io",
    "service": "notary-server",
    "issuer": "auth.docker.io",
    "rootcertbundle": "/path/to/auth.docker.io/cert"
  }
}

Note that this entire section is optional. However, if you would like authentication for your server, then you need the required parameters below to configure it.

Token authentication:

This is an implementation of the same authentication used by version 2 of the Docker registry. (JWT token-based authentication post login.)

Parameter Required Description
type yes Must be "token"; all other values will result in no authentication (and the rest of the parameters will be ignored)
options yes The options for token auth. Please see the registry token configuration documentation for the parameter details.

caching section (optional)

Example:

"caching": {
  "max_age": {
    "current_metadata": 300,
    "consistent_metadata": 31536000,
  }
}
Parameter Required Description
max_age no The max age, in seconds, for caching services to cache the latest metadata for a role and the metadata by checksum for a role. This value will be set on the cache control headers for GET-ting metadata. 
		Note that `must-revalidate` is also set on the cache control headers
		for current metadata, as current metadata may change whenever new
		metadata is signed into a repo.

		Consistent metadata should never change, although it may be deleted,
		so the max age can be a higher value.
	</td>
</tr>

repositories section (optional)

Example:

"repositories": {
  "gun_prefixes": ["docker.io/", "my-own-registry.com/"]
}
Parameter Required Description
gun_prefixes no A list of GUN prefixes that will be accepted by this server. POST operations on an image beginning with any other prefix will be rejected with a 400, and GET/DELETE operations will be rejected with a 404.

Hot logging level reload

We don't support completely reloading notary configuration files yet at present. What we support for Linux and OSX now is:

  • increase logging level by signaling SIGUSR1
  • decrease logging level by signaling SIGUSR2

No signals and no dynamic logging level changes are supported for Windows yet.

Example:

To increase logging level

$ kill -s SIGUSR1 PID

or

$ docker exec -i CONTAINER_ID kill -s SIGUSR1 PID

To decrease logging level

$ kill -s SIGUSR2 PID

or

$ docker exec -i CONTAINER_ID kill -s SIGUSR2 PID

PID is the process ID of notary-server and it may not the PID 1 process if you are running the container with some kind of wrapper startup script or something.

You can get the PID of notary-server through

$ docker exec CONTAINER_ID ps aux

or

$ ps aux | grep "notary-server -config" | grep -v "grep"

Related information