docker-docs/docs/reference/server-config.md

Notary server configuration file

This document is for those who are running their own service who want to facilitate CLI interaction or specify custom options.

For full specific configuration information, see the common configuration file for the Notary server and signer.

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.

The configuration file consists of the following sections:

server	HTTPS configuration	(required)
trust_service	signing service configuration	(required)
storage	TUF metadata storage configuration	(required)
auth	server authentication configuration	(optional)
logging	logging configuration	(optional)
reporting	ops/reporting configuration	(optional)

An example (full) server configuration file.

{
  "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"
    }
  }
}

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 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" or "memory". If "memory" is selected, the db_url is ignored.
db_url	yes if not memory	The the Data Source Name used to access the DB. (note: please include parseTime=true as part of the 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 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.

Related information

• Notary Client Configuration File
• Notary Signer Configuration File
• Configuration sections common to the Notary Server and Signer