From 41b1d57b95f094f6bda9e93266f4c2d1fa02bc91 Mon Sep 17 00:00:00 2001 From: Ying Li Date: Mon, 16 Nov 2015 16:49:57 -0800 Subject: [PATCH] Document the notary-server configuration JSON file. Signed-off-by: Ying Li --- docs/notary-server-config.md | 326 +++++++++++++++++++++++++++++++++++ 1 file changed, 326 insertions(+) create mode 100644 docs/notary-server-config.md diff --git a/docs/notary-server-config.md b/docs/notary-server-config.md new file mode 100644 index 0000000000..357bfcac10 --- /dev/null +++ b/docs/notary-server-config.md @@ -0,0 +1,326 @@ + + +# Notary Server Configuration File + +An example (full) server configuration file. + +```json +{ + "server": { + "addr": ":4443", + "tls_key_file": "./fixtures/notary-server.key", + "tls_cert_file": "./fixtures/notary-server.crt", + "auth": { + "type": "token", + "options": { + "realm": "https://auth.docker.io/token", + "service": "notary-server", + "issuer": "auth.docker.io", + "rootcertbundle": "/path/to/auth.docker.io/cert" + } + } + }, + "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" + }, + "logging": { + "level": "debug" + }, + "storage": { + "backend": "mysql", + "db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo" + }, + "reporting": { + "bugsnag": "yes", + "bugsnag_api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8", + "bugsnag_release_stage": "notary-server" + } +} +``` + +## `server` section (required) + +Example: + +```json +"server": { + "addr": ":4443", + "tls_key_file": "./fixtures/notary-server.key", + "tls_cert_file": "./fixtures/notary-server.crt" +} +``` + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
addryesThe 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 + acessible except locally (via SSH tunnel, or just on a local + terminal)
    • +
+
tls_key_fileno Specifies 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.
tls_cert_fileno Specifies the certificate to use for HTTPS. Must be + provided together with tls_cert_key, or not at all. + If neither are provided, the server will use HTTP instead of HTTPS.
+ +### `auth` subsection (optional) + +This sections specifies the authentication options for the server. +Currently, the only authentication scheme supported is token authentication. + +Example: + +```json +"auth": { + "type": "token", + "options": { + "realm": "https://auth.docker.io", + "service": "notary-server", + "issuer": "auth.docker.io", + "rootcertbundle": "/path/to/auth.docker.io/cert" + } +} +``` + +**Token authentication:** + +This is an implementation of the same authentication used by +[docker registry](https://github.com/docker/distribution). (JTW token-based +authentication post login.) + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
typeyesMust be `"token"`; all other values will result in no + authentication (and the rest of the parameters will be ignored)
optionsyesThe options for token auth. Please see + + the registry token configuration documentation + for the parameter details.
+ +## `trust service` section (optional) + +The trust service section must be included in order to specify a remote trust +service. If it is left out, a local in-memory ED25519 trust service will be +used. + +Remote trust service example: + +```json +"trust_service": { + "type": "remote", + "hostname": "notarysigner", + "port": "7899", + "key_algorithm": "ecdsa", + "tls_ca_file": "./fixtures/root-ca.crt", + "tls_client_key": "./fixtures/notary-server.key", + "tls_client_cert": "./fixtures/notary-server.crt" +} +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
typeyesMust be `"remote"`; all other values will result in a + local trust service (and the rest of the parameters will be ignored)
hostnameyesThe hostname of the remote trust service
portyesThe GRPC port of the remote trust service
key_algorithmyesThe key algorithm/type that will be generated and + stored on the signing service. Valid values are `ecdsa`, `rsa`, + and `ed25519`.
tls_ca_filenoThe root CA or TLS cert of the remote service, if it is + self-signed or otherwise not in the system's default trust roots
tls_client_keynoThe private key to use for TLS mutual authentication. + Must be provided together with tls_client_cert or not + at all.
tls_client_certoptionalThe certificate to use for TLS mutual authentication. + Must be provided together with tls_client_key or not + at all.
+ + +## `logging` section (optional) + +The logging section sets the log level of the server. If not provided, or if +any part of this section is invalid, the server defaults to an ERROR logging +level. + +Example: + +```json +"logging": { + "level": "debug" +} +``` + + + + + + + + + + + + +
ParameterRequiredDescription
levelyesOne of "debug", "info", + "warning", "error", "fatal", + or "panic"
+ +## `storage` section (optional) + +The storage section sets the storage options for the server. If not provided, +an in-memory store will be used. Currently, the only DB supported is MySQL. + +DB storage example: + +```json +"storage": { + "backend": "mysql", + "db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo" +} +``` + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
backendyesMust be "mysql"; all other values will + result in an in-memory store (and the rest of the parameters will + be ignored)
db_urlyesThe URL used to access the DB, which includes both the + endpoint anusername/credentials
+ +## `reporting` section (optional) + +The reporting section contains any configuration for reporting errors, etc. to +services via [logrus hooks](https://github.com/Sirupsen/logrus). Currently the +only supported services is [Bugsnag](https://bugsnag.com). (See +[bugsnag-go](https://github.com/bugsnag/bugsnag-go/) for more information about +configuration. + +```json +"reporting": { + "bugsnag": "yes", + "bugsnag_api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8", + "bugsnag_release_stage": "notary-server" +} +``` + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
bugsnagnoAny string value. If this value is not set, no errors will be + reported to Bugsnag (all other parameters will be ignored)
bugsnag_api_keynoThe API key to use to report errors - if this value is not set, + no errors will be reported to Bugsnag.
bugsnag_release_stagenoThe current release stage, such as "production" (which is the + default), used to filter errors in the Bugsnag dashboard.