docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update the server and signer docs to reflect new code changes. 

Signed-off-by: Ying Li <ying.li@docker.com>
This commit is contained in:
Ying Li 2015-11-30 14:32:03 -08:00
parent 4d696a0187
commit 54c7de5bd6
6 changed files with 360 additions and 234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
cmd/notary-server/main.go
View File

@ -244,8 +244,8 @@ func usage() {
// endpoints. The addr should not be exposed externally. For most of these to // endpoints. The addr should not be exposed externally. For most of these to
// work, tls cannot be enabled on the endpoint, so it is generally separate. // work, tls cannot be enabled on the endpoint, so it is generally separate.
func debugServer(addr string) { func debugServer(addr string) {
logrus.Info("Debug server listening on", addr) logrus.Infof("Debug server listening on %s", addr)
if err := http.ListenAndServe(addr, nil); err != nil { if err := http.ListenAndServe(addr, nil); err != nil {
logrus.Fatal("error listening on debug interface: ", err) logrus.Fatalf("error listening on debug interface: %v", err)
} }
} }

4
cmd/notary-signer/main.go
View File

@ -240,8 +240,8 @@ func usage() {
// endpoints. The addr should not be exposed externally. For most of these to // endpoints. The addr should not be exposed externally. For most of these to
// work, tls cannot be enabled on the endpoint, so it is generally separate. // work, tls cannot be enabled on the endpoint, so it is generally separate.
func debugServer(addr string) { func debugServer(addr string) {
log.Println("Debug server listening on", addr) logrus.Infof("Debug server listening on %s", addr)
if err := http.ListenAndServe(addr, nil); err != nil { if err := http.ListenAndServe(addr, nil); err != nil {
log.Fatalf("error listening on debug interface: %v", err) logrus.Fatalf("error listening on debug interface: %v", err)
} }
} }

313
docs/notary-server-config.md
View File

@ -15,18 +15,9 @@ An example (full) server configuration file.
```json ```json
{ {
"server": { "server": {
"addr": ":4443", "http_addr": ":4443",
"tls_key_file": "./fixtures/notary-server.key", "tls_key_file": "./fixtures/notary-server.key",
"tls_cert_file": "./fixtures/notary-server.crt", "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": { "trust_service": {
"type": "remote", "type": "remote",
@ -37,17 +28,27 @@ An example (full) server configuration file.
"tls_client_cert": "./fixtures/notary-server.crt", "tls_client_cert": "./fixtures/notary-server.crt",
"tls_client_key": "./fixtures/notary-server.key" "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": { "logging": {
"level": "debug" "level": "debug"
}, },
"storage": {
"backend": "mysql",
"db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo"
},
"reporting": { "reporting": {
"bugsnag": "yes", "bugsnag": {
"bugsnag_api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8", "api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"bugsnag_release_stage": "notary-server" "release_stage": "production"
}
} }
} }
``` ```
@ -58,7 +59,7 @@ Example:
```json ```json
"server": { "server": {
"addr": ":4443", "http_addr": ":4443",
"tls_key_file": "./fixtures/notary-server.key", "tls_key_file": "./fixtures/notary-server.key",
"tls_cert_file": "./fixtures/notary-server.crt" "tls_cert_file": "./fixtures/notary-server.crt"
} }
@ -70,7 +71,7 @@ Example:
<th>Description</th> <th>Description</th>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>addr</code></td> <td valign="top"><code>http_addr</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top">The TCP address (IP and port) to listen on. Examples: <td valign="top">The TCP address (IP and port) to listen on. Examples:
<ul> <ul>
@ -90,8 +91,8 @@ Example:
<td valign="top">The path to the private key to use for <td valign="top">The path to the private key to use for
HTTPS. Must be provided together with <code>tls_cert_file</code>, HTTPS. Must be provided together with <code>tls_cert_file</code>,
or not at all. If neither are provided, the server will use HTTP or not at all. If neither are provided, the server will use HTTP
instead of HTTPS. The path is relative to the directory where instead of HTTPS. The path is relative to the directory of the
notary-server is run.</td> configuration file.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>tls_cert_file</code></td> <td valign="top"><code>tls_cert_file</code></td>
@ -99,12 +100,130 @@ Example:
<td valign="top">The path to the certificate to use for HTTPS. <td valign="top">The path to the certificate to use for HTTPS.
Must be provided together with <code>tls_key_file</code>, or not Must be provided together with <code>tls_key_file</code>, or not
at all. If neither are provided, the server will use HTTP instead at all. If neither are provided, the server will use HTTP instead
of HTTPS. The path is relative to the directory where notary-server of HTTPS. The path is relative to the directory of the
is run.</td> configuration file.</td>
</tr> </tr>
</table> </table>
### `auth` subsection (optional) ## `trust service` section (required)
This section configures either a remote trust service, such as
[Notary Signer](notary-signer.md) or a local in-memory ED25519 trust service.
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"
}
```
Local trust service example:
```json
"trust_service": {
"type": "local"
}
```
<table>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Description</th>
</tr>
<tr>
<td valign="top"><code>type</code></td>
<td valign="top">yes</td>
<td valign="top">Must be <code>"remote"</code> or <code>"local"</code></td>
</tr>
<tr>
<td valign="top"><code>hostname</code></td>
<td valign="top">yes if remote</td>
<td valign="top">The hostname of the remote trust service</td>
</tr>
<tr>
<td valign="top"><code>port</code></td>
<td valign="top">yes if remote</td>
<td valign="top">The GRPC port of the remote trust service</td>
</tr>
<tr>
<td valign="top"><code>key_algorithm</code></td>
<td valign="top">yes if remote</td>
<td valign="top">Algorithm to use to generate keys stored on the
signing service. Valid values are <code>"ecdsa"</code>,
<code>"rsa"</code>, and <code>"ed25519"</code>.</td>
</tr>
<tr>
<td valign="top"><code>tls_ca_file</code></td>
<td valign="top">no</td>
<td valign="top">The path to the root CA that signed the TLS
certificate of the remote service. This parameter if said root
CA is not in the system's default trust roots. The path is
relative to the directory of the configuration file.</td>
</tr>
<tr>
<td valign="top"><code>tls_client_key</code></td>
<td valign="top">no</td>
<td valign="top">The path to the private key to use for TLS mutual
authentication. This must be provided together with
<code>tls_client_cert</code> or not at all. The path is relative
to the directory of the configuration file.</td>
</tr>
<tr>
<td valign="top"><code>tls_client_cert</code></td>
<td valign="top">no</td>
<td valign="top">The path to the certificate to use for TLS mutual
authentication. This must be provided together with
<code>tls_client_key</code> or not at all. The path is relative
to the directory of the configuration file.</td>
</tr>
</table>
## `storage` section (required)
The storage section specifies which storage backend the server should use to
store TUF metadata. Currently, we only support MySQL or an in-memory store.
DB storage example:
```json
"storage": {
"backend": "mysql",
"db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true"
}
```
<table>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Description</th>
</tr>
<tr>
<td valign="top"><code>backend</code></td>
<td valign="top">yes</td>
<td valign="top">Must be <code>"mysql"</code> or <code>"memory"</code>.
If <code>"memory"</code> is selected, the <code>db_url</code>
is ignored.</td>
</tr>
<tr>
<td valign="top"><code>db_url</code></td>
<td valign="top">yes if not <code>memory</code></td>
<td valign="top">The <a href="https://github.com/go-sql-driver/mysql">
the Data Source Name used to access the DB.</a>
(note: please include "parseTime=true" as part of the the DSN)</td>
</tr>
</table>
## `auth` section (optional)
This sections specifies the authentication options for the server. This sections specifies the authentication options for the server.
Currently, we only support token authentication. Currently, we only support token authentication.
@ -155,87 +274,6 @@ authentication post login.)
</tr> </tr>
</table> </table>
## `trust service` section (optional but recommended)
This section is required to specify a remote trust service, such as
[Notary Signer](notary-signer.md). If it is left out or invalid, a local
in-memory ED25519 trust service will be used instead.
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"
}
```
Note that this entire section is optional. However, if you would like to use a
separate trust service (recommended), then you need the required parameters
below to configure it.
<table>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Description</th>
</tr>
<tr>
<td valign="top"><code>type</code></td>
<td valign="top">yes</td>
<td valign="top">Must be <code>"remote"</code>; all other values
will result in a local trust service (and the rest of the
parameters will be ignored)</td>
</tr>
<tr>
<td valign="top"><code>hostname</code></td>
<td valign="top">yes</td>
<td valign="top">The hostname of the remote trust service</td>
</tr>
<tr>
<td valign="top"><code>port</code></td>
<td valign="top">yes</td>
<td valign="top">The GRPC port of the remote trust service</td>
</tr>
<tr>
<td valign="top"><code>key_algorithm</code></td>
<td valign="top">yes</td>
<td valign="top">Algorithm to use to generate keys stored on the
signing service. Valid values are <code>"ecdsa"</code>,
<code>"rsa"</code>, and <code>"ed25519"</code>.</td>
</tr>
<tr>
<td valign="top"><code>tls_ca_file</code></td>
<td valign="top">no</td>
<td valign="top">The path to the root CA that signed the TLS
certificate of the remote service. This parameter if said root
CA is not in the system's default trust roots. The path is
relative to the directory where notary-server is run.</td>
</tr>
<tr>
<td valign="top"><code>tls_client_key</code></td>
<td valign="top">no</td>
<td valign="top">The path to the private key to use for TLS mutual
authentication. This must be provided together with
<code>tls_client_cert</code> or not at all. The path is relative
to the directory where notary-server is run.</td>
</tr>
<tr>
<td valign="top"><code>tls_client_cert</code></td>
<td valign="top">no</td>
<td valign="top">The path to the certificate to use for TLS mutual
authentication. This must be provided together with
<code>tls_client_key</code> or not at all. The path is relative
to the directory where notary-server is run.</td>
</tr>
</table>
## `logging` section (optional) ## `logging` section (optional)
The logging section sets the log level of the server. If it is not provided The logging section sets the log level of the server. If it is not provided
@ -268,46 +306,6 @@ below to configure it.
</tr> </tr>
</table> </table>
## `storage` section (optional but recommended)
The storage section specifies which storage backend the server should use to
store TUF metadata. Currently, we only support MySQL. If this
section is not provided or invalid, an in-memory store will be used instead.
DB storage example:
```json
"storage": {
"backend": "mysql",
"db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo"
}
```
Note that this entire section is optional. However, if you would like to
use a database backend (recommended), then you need the required parameters
below to configure it.
<table>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Description</th>
</tr>
<tr>
<td valign="top"><code>backend</code></td>
<td valign="top">yes</td>
<td valign="top">Must be <code>"mysql"</code>; all other values will
result in an in-memory store (and the rest of the parameters will
be ignored)</td>
</tr>
<tr>
<td valign="top"><code>db_url</code></td>
<td valign="top">yes</td>
<td valign="top">The URL used to access the DB, which includes both the
endpoint the username/credentials</td>
</tr>
</table>
## `reporting` section (optional) ## `reporting` section (optional)
The reporting section contains any configuration for useful for running the The reporting section contains any configuration for useful for running the
@ -319,15 +317,18 @@ about these configuration parameters.
```json ```json
"reporting": { "reporting": {
"bugsnag": "yes", "bugsnag": {
"bugsnag_api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8", "api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"bugsnag_release_stage": "notary-server" "release_stage": "production"
}
} }
``` ```
Note that this entire section is optional. However, if you would like to Note that this entire section is optional. However, if you would like to
report errors to Bugsnag, then you need the required parameters below to report errors to Bugsnag, then you need to include a `bugsnag` subsection,
configure it. along with the required parameters below, to configure it.
**Bugsnag reporting:**
<table> <table>
<tr> <tr>
@ -336,18 +337,12 @@ configure it.
<th>Description</th> <th>Description</th>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>bugsnag</code></td> <td valign="top"><code>api_key</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td>Any string value. If this value is not set, no errors will be <td>The BugSnag API key to use to report errors.</td>
reported to Bugsnag (all other parameters will be ignored)</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>bugsnag_api_key</code></td> <td valign="top"><code>release_stage</code></td>
<td valign="top">yes</td>
<td>The API key to use to report errors.</td>
</tr>
<tr>
<td valign="top"><code>bugsnag_release_stage</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td>The current release stage, such as "production". You can <td>The current release stage, such as "production". You can
use this value to filter errors in the Bugsnag dashboard.</td> use this value to filter errors in the Bugsnag dashboard.</td>

62
docs/notary-server.md
View File

@ -77,6 +77,7 @@ for more details about the format of the configuration file.
You can also override the parameters of the configuration by You can also override the parameters of the configuration by
setting environment variables of the form `NOTARY_SERVER_var`. setting environment variables of the form `NOTARY_SERVER_var`.
`var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the `var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the
configuration JSON. configuration JSON.
@ -93,45 +94,58 @@ configuration:
the full path of keys is `storage -> db_url`. So the environment variable you'd the full path of keys is `storage -> db_url`. So the environment variable you'd
need to set would be `NOTARY_SERVER_STORAGE_DB_URL`. need to set would be `NOTARY_SERVER_STORAGE_DB_URL`.
For example, if running the binary:
```
$ export NOTARY_SERVER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname?parseTime=true
$ NOTARY_SERVER_LOGGING_LEVEL=info notary-server -config /path/to/config.json
```
Note that you cannot override a key whose value is another map. Note that you cannot override a key whose value is another map.
For instance, setting `NOTARY_SERVER_STORAGE=""` will not disable the For instance, setting
MySQL storage. You can only override keys whose values are strings or numbers. `NOTARY_SERVER_STORAGE='{"storage": {"backend": "memory"}}'` will not
set in-memory storage. It just fails to parse. You can only override keys
whose values are strings or numbers.
#### Running a Docker image #### Running Notary Server
Configuration options:
- `-config=<config file>` - The JSON configuration file.
- `-debug` - Passing this flag enables the debugging server on `localhost:8080`.
The debugging server provides [pprof](https://golang.org/pkg/net/http/pprof/)
and [expvar](https://golang.org/pkg/expvar/) endpoints.
Get the official Docker image, which comes with [some sane defaults](
https://github.com/docker/notary/blob/master/fixtures/server-config-local.json),
which include a remote trust service but local in-memory backing store.
Get the official Docker image, which comes with [some defaults](
https://github.com/docker/notary/blob/master/cmd/notary-server/config.json).
You can override the default configuration with environment variables. You can override the default configuration with environment variables.
For example, if you wanted to run it with just a local signing service and For example, if you wanted to run it with just a local signing service instead
memory store (not recommended for production): (not recommended for production):
``` ```
$ docker pull docker.io/docker/notary-server $ docker pull docker.io/docker/notary-server
$ docker run -p "4443:4443" \ $ docker run -p "4443:4443" \
-e NOTARY_SERVER_TRUST_SERVICE_TYPE=local \ -e NOTARY_SERVER_TRUST_SERVICE_TYPE=local
-e NOTARY_SERVER_STORAGE_BACKEND=""
-e NOTARY_SERVER_STORAGE_DB_URL=""
notary-server notary-server
``` ```
Alternately, you can run the image with your own configuration file entirely. Alternately, you can run the image with your own configuration file entirely.
The docker image loads the config file from `/opt/notary-server/config.json`, You just need to mount your configuration directory, and then pass the path to
so you can mount a directory with your config file (named `config.json`) that configuration file as an argument to the `docker run` command:
at `/opt/notary-server`:
``` ```
$ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-server notary-server $ docker run -p "4443:4443" -v /path/to/config/dir/on/host:/path/in/container \
notary-server -config=/path/in/container/config.json
``` ```
#### Running the binary You can also pass the `-debug` flag to the container in addition to the
A JSON configuration file needs to be passed as a parameter/flag when starting configuration file, but the debug server port is not exposed by the container.
up the Notary Server binary. Environment variables can also be set in addition In order to view the debug endpoints, you will have to `docker exec` into
to the configuration file, but the configuration file is required. For example: your container.
```
$ export NOTARY_SERVER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname
$ NOTARY_SERVER_LOGGING_LEVEL=info notary-server -config /path/to/config.json
```
### What happens if the server is compromised ### What happens if the server is compromised
@ -157,7 +171,7 @@ know that something is wrong.
### Ops features ### Ops features
Notary server provides the following endpoints for operational friendliness: Notary Server provides the following features for operational friendliness:
1. A health endpoint at `/_notary_server/health` which returns 200 and a 1. A health endpoint at `/_notary_server/health` which returns 200 and a
body of `{}` if the server is healthy, and a 500 with a map of body of `{}` if the server is healthy, and a 500 with a map of

131
docs/notary-signer-config.md
View File

@ -17,8 +17,8 @@ An example (full) server configuration file.
"server": { "server": {
"http_addr": ":4444", "http_addr": ":4444",
"grpc_addr": ":7899", "grpc_addr": ":7899",
"cert_file": "./fixtures/notary-signer.crt", "tls_cert_file": "./fixtures/notary-signer.crt",
"key_file": "./fixtures/notary-signer.key", "tls_key_file": "./fixtures/notary-signer.key",
"client_ca_file": "./fixtures/notary-server.crt" "client_ca_file": "./fixtures/notary-server.crt"
}, },
"logging": { "logging": {
@ -26,21 +26,31 @@ An example (full) server configuration file.
}, },
"storage": { "storage": {
"backend": "mysql", "backend": "mysql",
"db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo" "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true",
"default_alias": "password1"
},
"reporting": {
"bugsnag": {
"api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"release_stage": "production"
}
} }
} }
``` ```
## `server` section (required) ## `server` section (required)
"server" in this case refers to Notary Signer's HTTP/GRPC server, not
"Notary Server".
Example: Example:
```json ```json
"server": { "server": {
"http_addr": ":4444", "http_addr": ":4444",
"grpc_addr": ":7899", "grpc_addr": ":7899",
"cert_file": "./fixtures/notary-signer.crt", "tls_cert_file": "./fixtures/notary-signer.crt",
"key_file": "./fixtures/notary-signer.key", "tls_key_file": "./fixtures/notary-signer.key",
"client_ca_file": "./fixtures/notary-server.crt" "client_ca_file": "./fixtures/notary-server.crt"
} }
``` ```
@ -83,18 +93,18 @@ Example:
</td> </td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>key_file</code></td> <td valign="top"><code>tls_key_file</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top">The path to the private key to use for <td valign="top">The path to the private key to use for
HTTPS. The path is relative to the directory where HTTPS. The path is relative to the directory of the
notary-signer is run.</td> configuration file.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>cert_file</code></td> <td valign="top"><code>tls_cert_file</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top">The path to the certificate to use for <td valign="top">The path to the certificate to use for
HTTPS. The path is relative to the directory where HTTPS. The path is relative to the directory of the
notary-signer is run.</td> configuration file.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>client_ca_file</code></td> <td valign="top"><code>client_ca_file</code></td>
@ -103,21 +113,23 @@ Example:
mutual authentication. If provided, any clients connecting to mutual authentication. If provided, any clients connecting to
Notary Signer will have to have a client certificate signed by Notary Signer will have to have a client certificate signed by
this root. If not provided, mutual authentication will not be this root. If not provided, mutual authentication will not be
required. The path is relative to the directory where required. The path is relative to the directory of the
notary-signer is run.</td> configuration file.</td>
</tr> </tr>
</table> </table>
## `storage` section (required) ## `storage` section (required)
We only support MySQL, currently, and it must be provided. This is used to store encrypted priate keys. We only support MySQL or an
in-memory store, currently.
Example: Example:
```json ```json
"storage": { "storage": {
"backend": "mysql", "backend": "mysql",
"db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo" "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true",
"default_alias": "password1"
} }
``` ```
@ -130,31 +142,53 @@ Example:
<tr> <tr>
<td valign="top"><code>backend</code></td> <td valign="top"><code>backend</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top">Must be <code>"mysql"</code></td> <td valign="top">Must be <code>"mysql"</code> or <code>"memory"</code>.
If <code>"memory"</code> is selected, the <code>db_url</code>
is ignored.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>db_url</code></td> <td valign="top"><code>db_url</code></td>
<td valign="top">yes</td> <td valign="top">yes if not <code>memory</code></td>
<td valign="top">The URL used to access the DB, which includes both the <td valign="top">The <a href="https://github.com/go-sql-driver/mysql">
endpoint the username/credentials</td> the Data Source Name used to access the DB.</a>
(note: please include "parseTime=true" as part of the the DSN)</td>
</tr>
<tr>
<td valign="top"><code>default_alias</code></td>
<td valign="top">yes if not <code>memory</code></td>
<td valign="top">This parameter specifies the alias of the current
password used to encrypt the private keys in the DB. All new
private keys will be encrypted using this password, which
must also be provided as the environment variable
<code>NOTARY_SIGNER_&lt;default_alias_value&gt;</code>.</td>
</tr> </tr>
</table> </table>
**Required environment variable:**
<code>NOTARY_SIGNER_&lt;default_alias_value&gt;</code>
**Optional environment variables:**
<code>NOTARY_SIGNER_&lt;old_alias_value&gt;</code> for as many old alias values
as needed. This will ensure that older private keys, encrypted with older
passwords, can be decrypted.
## `logging` section (optional) ## `logging` section (optional)
The logging section sets the log level of the server. If not provided, or if The logging section sets the log level of the server. If it is not provided
any part of this section is invalid, the server defaults to an ERROR logging or invalid, the signer defaults to an ERROR logging level.
level.
Example: Example:
```json ```json
"logging": { "logging": {
"level": 2 "level": "debug"
} }
``` ```
Note that this entire section is optional. However, if you would like to
specify a different log level, then you need the required parameters
below to configure it.
<table> <table>
<tr> <tr>
<th>Parameter</th> <th>Parameter</th>
@ -164,9 +198,52 @@ Example:
<tr> <tr>
<td valign="top"><code>level</code></td> <td valign="top"><code>level</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top">An integer between 0 and 5, representing values <td valign="top">One of <code>"debug"</code>, <code>"info"</code>,
<code>"debug"</code> (5), <code>"info"</code> (4), <code>"warning"</code>, <code>"error"</code>, <code>"fatal"</code>,
<code>"warning"</code> (3), <code>"error"</code>(2), or <code>"panic"</code></td>
<code>"fatal"</code> (1), or <code>"panic"</code>(0)</td> </tr>
</table>
## `reporting` section (optional)
The reporting section contains any configuration for useful for running the
service, such as reporting errors. Currently, we only support reporting errors
to [Bugsnag](https://bugsnag.com).
See [bugsnag-go](https://github.com/bugsnag/bugsnag-go/) for more information
about these configuration parameters.
```json
"reporting": {
"bugsnag": {
"api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"release_stage": "production"
}
}
```
Note that this entire section is optional. However, if you would like to
report errors to Bugsnag, then you need to include a `bugsnag` subsection,
along with the required parameters below, to configure it.
**Bugsnag reporting:**
<table>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Description</th>
</tr>
<tr>
<td valign="top"><code>api_key</code></td>
<td valign="top">yes</td>
<td>The BugSnag API key to use to report errors.</td>
</tr>
<tr>
<td valign="top"><code>release_stage</code></td>
<td valign="top">yes</td>
<td>The current release stage, such as "production". You can
use this value to filter errors in the Bugsnag dashboard.</td>
</tr> </tr>
</table> </table>

80
docs/notary-signer.md
View File

@ -29,6 +29,20 @@ that is compromised can sign any number of other client certs.
As an example, please see [this script](opensslCertGen.sh) to see how to As an example, please see [this script](opensslCertGen.sh) to see how to
generate client SSL certs with basic constraints using OpenSSL. generate client SSL certs with basic constraints using OpenSSL.
### Signer storage
Notary Signer uses MySQL as a backend for storing the encrypted private keys
that is responsible for. The private keys[wrapped](
https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.4)
and [encrypted](
https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.8)
using [Javascript Object Signing and Encryption](
https://github.com/dvsekhvalnov/jose2go).
The passphrase used to encrypt the keys is passed as an environment variable,
the name of which [is specified by the confguration file](
notary-signer-config.md#storage-section-required).
### How to configure and run Notary Signer ### How to configure and run Notary Signer
A JSON configuration file is used to configure Notary Signer. Please see the A JSON configuration file is used to configure Notary Signer. Please see the
@ -37,6 +51,7 @@ for more details about the format of the configuration file.
You can also override the parameters of the configuration by You can also override the parameters of the configuration by
setting environment variables of the form `NOTARY_SIGNER_var`. setting environment variables of the form `NOTARY_SIGNER_var`.
`var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the `var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the
configuration JSON. configuration JSON.
@ -57,40 +72,58 @@ Note that you cannot override a key whose value is another map.
For instance, setting `NOTARY_SIGNER_STORAGE=""` will not disable the For instance, setting `NOTARY_SIGNER_STORAGE=""` will not disable the
MySQL storage. You can only override keys whose values are strings or numbers. MySQL storage. You can only override keys whose values are strings or numbers.
#### Running a Docker image For example, if running the binary:
```
$ export NOTARY_SIGNER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname?parseTime=true
$ NOTARY_SIGNER_LOGGING_LEVEL=info notary-signer -config /path/to/config.json
```
Note that you cannot override a key whose value is another map.
For instance, setting
`NOTARY_SIGNER_STORAGE='{"storage": {"backend": "memory"}}'` will not
set in-memory storage. It just fails to parse. You can only override keys
whose values are strings or numbers.
#### Running Notary Signer
Configuration options:
- `-config=<config file>` - The JSON configuration file.
- `-debug` - Passing this flag enables the debugging server on `localhost:8080`.
The debugging server provides [pprof](https://golang.org/pkg/net/http/pprof/)
and [expvar](https://golang.org/pkg/expvar/) endpoints.
Get the official Docker image, which comes with [some sane defaults](
https://github.com/docker/notary/blob/master/fixtures/signer-config-local.json),
which uses a local in-memory backing store (not recommended for production).
Get the official Docker image, which comes with [some defaults](
https://github.com/docker/notary/blob/master/cmd/notary-signer/config.json).
You can override the default configuration with environment variables. You can override the default configuration with environment variables.
For example, if you wanted to run it with your own MySQL DB and a different For example, if you wanted to run it with your own DB
logging level: (recommended for production):
``` ```
$ docker pull docker.io/docker/notary-signer $ docker pull docker.io/docker/notary-signer
$ docker run -p "4443:4443" \ $ docker run -p "4444:4444" \
-e NOTARY_SIGNER_LOGGING_LEVEL=info \ -e NOTARY_SIGNER_STORAGE_DB_BACKEND="mysql" \
-e NOTARY_SIGNER_STORAGE_DB_URL="myuser:mypass@tcp(my-db)/dbName" -e NOTARY_SIGNER_STORAGE_DB_URL="myuser:mypass@tcp(my-db)/dbName"
notary-signer notary-signer
``` ```
Alternately, you can run the image with your own configuration file entirely. Alternately, you can run the image with your own configuration file entirely.
The docker image loads the config file from `/opt/notary-signer/config.json`, You just need to mount your configuration directory, and then pass the path to
so you can mount a directory with your config file (named `config.json`) that configuration file as an argument to the `docker run` command:
at `/opt/notary-signer`:
``` ```
$ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-signer notary-signer $ docker run -p "4444:4444" -v /path/to/config/dir/on/host:/path/in/container \
notary-signer -config=/path/in/container/config.json
``` ```
#### Running the binary You can also pass the `-debug` flag to the container in addition to the
A JSON configuration file needs to be passed as a parameter/flag when starting configuration file, but the debug server port is not exposed by the container.
up the Notary Signer binary. Environment variables can also be set in addition In order to view the debug endpoints, you will have to `docker exec` into
to the configuration file, but the configuration file is required. For example: your container.
```
$ export NOTARY_SIGNER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname
$ NOTARY_SIGNER_LOGGING_LEVEL=info notary-signer -config /path/to/config.json
```
### What happens if the signer is compromised ### What happens if the signer is compromised
@ -105,3 +138,10 @@ The attacker can prevent Notary Signer from signing timestap metadata from
Notary Server and return invalid public key IDs when the Notary Server Notary Server and return invalid public key IDs when the Notary Server
requests it. This means an attacker can execute a denial of service attack requests it. This means an attacker can execute a denial of service attack
that prevents the Notary Server from being able to update any metadata. that prevents the Notary Server from being able to update any metadata.
### Ops features
Notary Signer provides the following features for operational friendliness:
1. A [Bugsnag](https://bugsnag.com) hook for error logs, if a Bugsnag
configuration is provided.