Notary server configuration file
Estimated reading time: 9 minutesThis document is for those who are running their own Notary service who 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; click on the top level JSON keys to learn more about the configuration section corresponding to that key:
{
<a href="server-config.md#server-section-required">"server"</a>: {
"http_addr": ":4443",
"tls_key_file": "./fixtures/notary-server.key",
"tls_cert_file": "./fixtures/notary-server.crt"
},
<a href="server-config.md#trust-service-section-required">"trust_service"</a>: {
"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"
},
<a href="server-config.md#storage-section-required">"storage"</a>: {
"backend": "mysql",
"db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true"
},
<a href="server-config.md#auth-section-optional">"auth"</a>: {
"type": "token",
"options": {
"realm": "https://auth.docker.io/token",
"service": "notary-server",
"issuer": "auth.docker.io",
"rootcertbundle": "/path/to/auth.docker.io/cert"
}
},
<a href="../common-configs/#logging-section-optional">"logging"</a>: {
"level": "debug"
},
<a href="../common-configs/#reporting-section-optional">"reporting"</a>: {
"bugsnag": {
"api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"release_stage": "production"
}
},
<a href="server-config.md#caching-section-optional">"caching"</a>: {
"max_age": {
"current_metadata": 300,
"consistent_metadata": 31536000,
}
},
<a href="server-config.md#repositories-section-optional">"repositories"</a>: {
"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:
|
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 uses 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 uses 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.
( 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"
}
}
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.
Parameter | Required | Description |
---|---|---|
type |
yes | Must be "token" ; all other values result in no
authentication (and the rest of the parameters are ignored) |
options |
yes | The options for token auth. 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 is set on the cache control headers for GET-ting metadata. `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. |
repositories section (optional)
Example:
"repositories": {
"gun_prefixes": ["docker.io/", "my-own-registry.com/"]
}
Parameter | Required | Description |
---|---|---|
gun_prefixes |
no | A list of GUN prefixes accepted by this server. POST operations on an image beginning with any other prefix are rejected with a 400, and GET/DELETE operations are rejected with a 404. |
Hot logging level reload
We don’t support completely reloading notary configuration files yet at present. What we support for now is:
- increase logging level by signaling
SIGUSR1
- decrease logging level by signaling
SIGUSR2
Example:
To increase logging level
$ kill -s SIGUSR1 PID
or
$ docker container exec -i CONTAINER_ID kill -s SIGUSR1 PID
To decrease logging level
$ kill -s SIGUSR2 PID
or
$ docker container 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 container exec CONTAINER_ID ps aux
or
$ ps aux | grep "notary-server -config" | grep -v "grep"