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

Grammar/spelling/formatting/readability fixes. 

Signed-off-by: Ying Li <ying.li@docker.com>
This commit is contained in:
Ying Li 2015-11-20 10:48:32 -08:00
parent 7ee1173084
commit 4d696a0187
4 changed files with 219 additions and 254 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -87,27 +87,27 @@ Example:
<tr> <tr>
<td valign="top"><code>tls_key_file</code></td> <td valign="top"><code>tls_key_file</code></td>
<td valign="top">no</td> <td valign="top">no</td>
<td valign="top">Specifies the private key to use for HTTPS. Must be <td valign="top">The path to the private key to use for
provided together with <code>tls_cert_file</code>, or not at all. HTTPS. Must be provided together with <code>tls_cert_file</code>,
If neither are provided, the server will use HTTP instead of HTTPS. or not at all. If neither are provided, the server will use HTTP
The path is relative to the current working directory where instead of HTTPS. The path is relative to the directory where
notary-server is run.</td> notary-server is run.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>tls_cert_file</code></td> <td valign="top"><code>tls_cert_file</code></td>
<td valign="top">no</td> <td valign="top">no</td>
<td valign="top">Specifies the certificate to use for HTTPS. Must be <td valign="top">The path to the certificate to use for HTTPS.
provided together with <code>tls_key_file</code>, or not at all. Must be provided together with <code>tls_key_file</code>, or not
If neither are provided, the server will use HTTP instead of HTTPS. at all. If neither are provided, the server will use HTTP instead
The path is relative to the current working directory where of HTTPS. The path is relative to the directory where notary-server
notary-server is run.</td> is run.</td>
</tr> </tr>
</table> </table>
### `auth` subsection (optional) ### `auth` subsection (optional)
This sections specifies the authentication options for the server. This sections specifies the authentication options for the server.
Currently, the only authentication scheme supported is token authentication. Currently, we only support token authentication.
Example: Example:
@ -123,8 +123,9 @@ Example:
} }
``` ```
Note that this entire section is optional. However, you would like Note that this entire section is optional. However, if you would like
authentication, then then the required parameters below are needed configure it. authentication for your server, then you need the required parameters below to
configure it.
**Token authentication:** **Token authentication:**
@ -154,11 +155,11 @@ authentication post login.)
</tr> </tr>
</table> </table>
## `trust service` section (optional) ## `trust service` section (optional but recommended)
The trust service section must be included in order to specify a remote trust This section is required to specify a remote trust service, such as
service. If it is left out, a local in-memory ED25519 trust service will be [Notary Signer](notary-signer.md). If it is left out or invalid, a local
used. in-memory ED25519 trust service will be used instead.
Remote trust service example: Remote trust service example:
@ -174,9 +175,9 @@ Remote trust service example:
} }
``` ```
Note that this entire section is optional. However, you would like to use a Note that this entire section is optional. However, if you would like to use a
separate trust service (recommended), then then the required parameters below separate trust service (recommended), then you need the required parameters
are needed configure it. below to configure it.
<table> <table>
<tr> <tr>
@ -187,8 +188,9 @@ are needed configure it.
<tr> <tr>
<td valign="top"><code>type</code></td> <td valign="top"><code>type</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top">Must be `"remote"`; all other values will result in a <td valign="top">Must be <code>"remote"</code>; all other values
local trust service (and the rest of the parameters will be ignored)</td> will result in a local trust service (and the rest of the
parameters will be ignored)</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>hostname</code></td> <td valign="top"><code>hostname</code></td>
@ -203,42 +205,41 @@ are needed configure it.
<tr> <tr>
<td valign="top"><code>key_algorithm</code></td> <td valign="top"><code>key_algorithm</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top">The key algorithm/type that will be generated and <td valign="top">Algorithm to use to generate keys stored on the
stored on the signing service. Valid values are `ecdsa`, `rsa`, signing service. Valid values are <code>"ecdsa"</code>,
and `ed25519`.</td> <code>"rsa"</code>, and <code>"ed25519"</code>.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>tls_ca_file</code></td> <td valign="top"><code>tls_ca_file</code></td>
<td valign="top">no</td> <td valign="top">no</td>
<td valign="top">The root CA or TLS cert of the remote service, if it is <td valign="top">The path to the root CA that signed the TLS
self-signed or otherwise not in the system's default trust roots. certificate of the remote service. This parameter if said root
The path is relative to the current working directory where CA is not in the system's default trust roots. The path is
notary-server is run.</td> relative to the directory where notary-server is run.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>tls_client_key</code></td> <td valign="top"><code>tls_client_key</code></td>
<td valign="top">no</td> <td valign="top">no</td>
<td valign="top">The private key to use for TLS mutual authentication. <td valign="top">The path to the private key to use for TLS mutual
Must be provided together with <code>tls_client_cert</code> or not authentication. This must be provided together with
at all. The path is relative to the current working directory where <code>tls_client_cert</code> or not at all. The path is relative
notary-server is run.</td> to the directory where notary-server is run.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>tls_client_cert</code></td> <td valign="top"><code>tls_client_cert</code></td>
<td valign="top">optional</td> <td valign="top">no</td>
<td valign="top">The certificate to use for TLS mutual authentication. <td valign="top">The path to the certificate to use for TLS mutual
Must be provided together with <code>tls_client_key</code> or not authentication. This must be provided together with
at all. The path is relative to the current working directory where <code>tls_client_key</code> or not at all. The path is relative
notary-server is run.</td> to the directory where notary-server is run.</td>
</tr> </tr>
</table> </table>
## `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 server defaults to an ERROR logging level.
level.
Example: Example:
@ -248,9 +249,9 @@ Example:
} }
``` ```
Note that this entire section is optional. However, you would like to Note that this entire section is optional. However, if you would like to
specify a different log level, then then the required parameters below specify a different log level, then you need the required parameters
are needed configure it. below to configure it.
<table> <table>
<tr> <tr>
@ -267,10 +268,11 @@ are needed configure it.
</tr> </tr>
</table> </table>
## `storage` section (optional) ## `storage` section (optional but recommended)
The storage section sets the storage options for the server. If not provided, The storage section specifies which storage backend the server should use to
an in-memory store will be used. Currently, the only DB supported is MySQL. 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: DB storage example:
@ -281,9 +283,9 @@ DB storage example:
} }
``` ```
Note that this entire section is optional. However, you would like to Note that this entire section is optional. However, if you would like to
use a database backend (recommended), then then the required parameters below use a database backend (recommended), then you need the required parameters
are needed configure it. below to configure it.
<table> <table>
<tr> <tr>
@ -302,17 +304,18 @@ are needed configure it.
<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</td>
<td valign="top">The URL used to access the DB, which includes both the <td valign="top">The URL used to access the DB, which includes both the
endpoint anusername/credentials</td> endpoint the username/credentials</td>
</tr> </tr>
</table> </table>
## `reporting` section (optional) ## `reporting` section (optional)
The reporting section contains any configuration for reporting errors, etc. to The reporting section contains any configuration for useful for running the
services via [logrus hooks](https://github.com/Sirupsen/logrus). Currently the service, such as reporting errors. Currently, we only support reporting errors
only supported services is [Bugsnag](https://bugsnag.com). (See to [Bugsnag](https://bugsnag.com).
[bugsnag-go](https://github.com/bugsnag/bugsnag-go/) for more information about
configuration. See [bugsnag-go](https://github.com/bugsnag/bugsnag-go/) for more information
about these configuration parameters.
```json ```json
"reporting": { "reporting": {
@ -322,8 +325,8 @@ configuration.
} }
``` ```
Note that this entire section is optional. However, you would like to Note that this entire section is optional. However, if you would like to
use Bugsnag reporting, then then the required parameters below are needed report errors to Bugsnag, then you need the required parameters below to
configure it. configure it.
<table> <table>
@ -341,13 +344,12 @@ configure it.
<tr> <tr>
<td valign="top"><code>bugsnag_api_key</code></td> <td valign="top"><code>bugsnag_api_key</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td>The API key to use to report errors - if this value is not set, <td>The API key to use to report errors.</td>
no errors will be reported to Bugsnag.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>bugsnag_release_stage</code></td> <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" (which is the <td>The current release stage, such as "production". You can
default), used to filter errors in the Bugsnag dashboard.</td> use this value to filter errors in the Bugsnag dashboard.</td>
</tr> </tr>
</table> </table>

128
docs/notary-server.md
View File

@ -10,11 +10,22 @@ parent="mn_notary"
# Notary Server # Notary Server
The notary server is a remote store for, and coordinates updates to, the signed The Notary Server stores and updates the signed
metadata files for a repository (which are created by clients). The server is [TUF metadata files](
also responsible for creating and keeping track of timestamp keys for each repo, https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L348)
and signing a timestamp file for each repo whenever a client sends updates, for a repository. The root, snapshot, and targets metadata files are generated
after verifying the root, target, and snapshot signatures on the client update. and signed by clients, and the timestamp metadata file is generated and signed
by the server.
The server creates and stores timestamp keys for each repository (preferably
using a remote key storage/signing service such as
[Notary Signer](notary-signer.md)).
When clients upload metadata files, the server checks them for conflicts and
verifies the signatures and key references in the files. If everything
checks out, the server then signs the timestamp metadata file for the
repository, which certifies that the files the client uploaded are the most
recent for that repository.
### Authentication ### Authentication
@ -23,49 +34,54 @@ tokens. This requires an authorization server that manages access controls,
and a cert bundle from this authorization server containing the public key it and a cert bundle from this authorization server containing the public key it
uses to sign tokens. uses to sign tokens.
The client will log into the server (it gets redirected by Notary Server if If token authentication is enabled on Notary Server, then any client that
authentication is configured), obtain a token, and present the token to Notary does not have a token will be redirected to the authoriziation server.
Server, which should be configured to trust signatures from that authorization The client will log in, obtain a token, and then present the token to
Notary Server on future requests.
Notary Server should be configured to trust signatures from that authorization
server. server.
See the docs for [Docker Registry v2 authentication]( Please see the docs for [Docker Registry v2 authentication](
https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md) https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md)
for more information. for more information.
### Server storage ### Server storage
Currently Notary Server uses MySQL as a backend for storing the timestamp Notary Server uses MySQL as a backend for storing the timestamp
*public* keys and the TUF metadata for each repository. public keys and the TUF metadata for each repository. It relies on a signing
service to store the private keys.
### Signing service ### Signing service
The recommended usage of the server is with a separate signing service: We recommend deploying Notary Server with a separate, remote signing
[Notary Signer](notary-signer.md). The signing service actually service: [Notary Signer](notary-signer.md). This signing service generates
stores the timestamp *private* keys and performs signing for the server. and stores the timestamp private keys and performs signing for the server.
By using a signing service, the private keys then would never be stored on the By using remote a signing service, the private keys would never need to be
server itself. stored on the server itself.
Notary Signer supports mutual authentication - when you generate client Notary Signer supports mutual authentication - when you generate client
certificates for Notary Server to authenticate with Notary Signer, please make certificates for your deployment of Notary Server, please make
sure that the certificates **are not CAs**. Otherwise any server that is sure that the certificates **are not CAs**. Otherwise if the server is
compromised can sign any number of other client certs. compromised, it 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.
### How to configure and run notary server ### How to configure and run Notary Server
A JSON configuration file is used to configure Notary Server. Please see the A JSON configuration file is used to configure Notary Server. Please see the
[Notary Server configuration document](notary-server-config.md) [Notary Server configuration document](notary-server-config.md)
for more details about the format of the configuration file. for more details about the format of the configuration file.
The parameters of the configuration file can also be overwritten using You can also override the parameters of the configuration by
environment variables of the form `NOTARY_SERVER_var`, where `var` is the setting environment variables of the form `NOTARY_SERVER_var`.
full path from the top level of the configuration file to the variable you want `var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the
to override, in all caps. A change in level is denoted with a `_`. configuration JSON.
For instance, one part of the configuration file might look like: For instance, if you wanted to override the storage URL of the Notary Server
configuration:
```json ```json
"storage": { "storage": {
@ -74,19 +90,20 @@ For instance, one part of the configuration file might look like:
} }
``` ```
If you would like to specify a different `db_url`, the full path from the top the full path of keys is `storage -> db_url`. So the environment variable you'd
of the configuration tree is `storage -> db_url`, so the environment variable need to set would be `NOTARY_SERVER_STORAGE_DB_URL`.
to set would be `NOTARY_SERVER_STORAGE_DB_URL`.
Note that you cannot override an intermediate level name. Setting Note that you cannot override a key whose value is another map.
`NOTARY_SERVER_STORAGE=""` will not disable the MySQL storage. Each leaf For instance, setting `NOTARY_SERVER_STORAGE=""` will not disable the
parameter value must be set indepedently. MySQL storage. You can only override keys whose values are strings or numbers.
#### Running a Docker image #### Running a Docker image
Get the official Docker image, which comes with some sane defaults. You can Get the official Docker image, which comes with [some defaults](
run it with your own signer service and mysql DB, or in the example below, with https://github.com/docker/notary/blob/master/cmd/notary-server/config.json).
just a local signing service and memory store: You can override the default configuration with environment variables.
For example, if you wanted to run it with just a local signing service and
memory store (not recommended for production):
``` ```
$ docker pull docker.io/docker/notary-server $ docker pull docker.io/docker/notary-server
@ -97,9 +114,10 @@ $ docker run -p "4443:4443" \
notary-server notary-server
``` ```
Alternately, you can run with your own configuration file entirely. The Alternately, you can run the image with your own configuration file entirely.
docker image loads the config file from `/opt/notary-server/config.json`, so The docker image loads the config file from `/opt/notary-server/config.json`,
you can mount your config file at `/opt/notary-server`: so you can mount a directory with your config file (named `config.json`)
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:/opt/notary-server notary-server
@ -108,7 +126,7 @@ $ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-server notary-ser
#### Running the binary #### Running the binary
A JSON configuration file needs to be passed as a parameter/flag when starting A JSON configuration file needs to be passed as a parameter/flag when starting
up the Notary Server binary. Environment variables can also be set in addition up the Notary Server binary. Environment variables can also be set in addition
to the configuration file, but the configuration file is required. to the configuration file, but the configuration file is required. For example:
``` ```
$ export NOTARY_SERVER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname $ export NOTARY_SERVER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname
@ -117,35 +135,37 @@ $ 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
The server does not hold any keys for the repository except the timestamp key, The server does not hold any keys for repositories, except the for timestamp
so the attacker cannot modify the root, targets, or snapshots metadata. keys if you are using a local signing service, so the attacker cannot modify
the root, targets, or snapshots metadata.
If using a signer service, an attacker cannot get access to the timestamp key. If you are using a signer service, an attacker cannot get access to the
They can use the server to make calls to the signer service to sign arbitrary timestamp key either. They can use the server's credentials to get the signer
data, such as an empty timestamp, an invalid timestamp, or an old timestamp. service to sign arbitrary data, such as an empty timestamp,
an invalid timestamp, or an old timestamp.
TOFU (trust on first use) would prevent the attacker from being able to make However, TOFU (trust on first use) would prevent the attacker from tricking
existing clients for existing repositories download arbitrary data. They would existing clients for existing repositories to download arbitrary data.
need the original root/target/snapshots keys. The attacker could, by signing They would need the original root/target/snapshots keys to do that. The
bad timestamps, prevent the user from seeing any updated metadata. attacker could only, by signing bad timestamps, prevent the such a user from
seeing any updated metadata.
The attacker can also make all new keys, and simply replace the repository The attacker can also make all new keys, and simply replace the repository
metadata with metadata signed with these new keys. New clients who have not metadata with metadata signed with these new keys. New clients who have not
seen this repository before will trust this bad data, but older clients will seen the repository before will trust this bad data, but older clients will
know that something is wrong. know that something is wrong.
### Ops features ### Ops features
Notary server provides the following endpoints for ops friendliness: Notary server provides the following endpoints 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 list of body of `{}` if the server is healthy, and a 500 with a map of
failed services if the server cannot access its storage backend. failed services if the server cannot access its storage backend.
If it cannot contact the signing service (in which case service is degraded, If it cannot contact the signing service, an error will be logged but the
but not down, since the server can still serve metadata, but not accept service will still be considered healthy, because it can still serve
updates), an error will be logged, but the service will still be considered existing metadata. It cannot accept updates, so the service is degraded.
healthy.
1. A [Bugsnag](https://bugsnag.com) hook for error logs, if a Bugsnag 1. A [Bugsnag](https://bugsnag.com) hook for error logs, if a Bugsnag
configuration is provided. configuration is provided.

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

@ -27,13 +27,6 @@ An example (full) server configuration file.
"storage": { "storage": {
"backend": "mysql", "backend": "mysql",
"db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo" "db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo"
},
"reporting": {
"bugsnag": {
"api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"release_stage": "staging",
"endpoint": "https://bugsnag.internal:49000/"
}
} }
} }
``` ```
@ -77,7 +70,7 @@ Example:
<td valign="top"><code>grpc_addr</code></td> <td valign="top"><code>grpc_addr</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top">The TCP address (IP and port) to listen for GRPC <td valign="top">The TCP address (IP and port) to listen for GRPC
traffic (which Notary Server uses) on. Examples: traffic. Examples:
<ul> <ul>
<li><code>":7899"</code> means listen on port 7899 on all IPs (and <li><code>":7899"</code> means listen on port 7899 on all IPs (and
hence all interfaces, such as those listed when you run hence all interfaces, such as those listed when you run
@ -92,29 +85,61 @@ Example:
<tr> <tr>
<td valign="top"><code>key_file</code></td> <td valign="top"><code>key_file</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top"> Specifies the private key to use for HTTPS. The path <td valign="top">The path to the private key to use for
is relative to the current working directory where notary-signer HTTPS. The path is relative to the directory where
is run.</td> notary-signer is run.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>cert_file</code></td> <td valign="top"><code>cert_file</code></td>
<td valign="top">yes</td> <td valign="top">yes</td>
<td valign="top"> Specifies the certificate to use for HTTPS. The path <td valign="top">The path to the certificate to use for
is relative to the current working directory where notary-signer HTTPS. The path is relative to the directory where
is run.</td> notary-signer is run.</td>
</tr> </tr>
<tr> <tr>
<td valign="top"><code>client_ca_file</code></td> <td valign="top"><code>client_ca_file</code></td>
<td valign="top">no</td> <td valign="top">no</td>
<td valign="top">The root cert (or just the public cert) to trust for <td valign="top">The root certificate to trust for
mutual authentication. If provided, a client certificate will be mutual authentication. If provided, any clients connecting to
required for any client certificates connecting to Notary Signer. Notary Signer will have to have a client certificate signed by
If not provided, mutual authentication will not be required. The this root. If not provided, mutual authentication will not be
path is relative to the current working directory where required. The path is relative to the directory where
notary-signer is run.</td> notary-signer is run.</td>
</tr> </tr>
</table> </table>
## `storage` section (required)
We only support MySQL, currently, and it must be provided.
Example:
```json
"storage": {
"backend": "mysql",
"db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo"
}
```
<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></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>
## `logging` section (optional) ## `logging` section (optional)
@ -145,86 +170,3 @@ Example:
<code>"fatal"</code> (1), or <code>"panic"</code>(0)</td> <code>"fatal"</code> (1), or <code>"panic"</code>(0)</td>
</tr> </tr>
</table> </table>
## `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"
}
```
<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 anusername/credentials</td>
</tr>
</table>
## `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": {
"api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"release_stage": "staging",
"endpoint": "https://bugsnag.internal:49000/"
}
}
```
### `bugsnag` subsection (optional)
This section specifies parameters for 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 API key to use to report errors - if this value is not set,
no errors will be reported to Bugsnag.</td>
</tr>
<tr>
<td valign="top"><code>release_stage</code></td>
<td valign="top">no</td>
<td>The current release stage, such as "production" (which is the
default), used to filter errors in the Bugsnag dashboard.</td>
</tr>
<tr>
<td valign="top"><code>endpoint</code></td>
<td valign="top">no</td>
<td>The current release stage, such as "production" (which is the
default), used to filter errors in the Bugsnag dashboard.</td>
</tr>
</table>

75
docs/notary-signer.md
View File

@ -10,8 +10,8 @@ parent="mn_notary"
# Notary Signer # Notary Signer
The Notary Signer is a remote store for private keys. It will create and delete The Notary Signer is a remote store for private keys. It creates and delete
keys, signs data, and return public key information on demand via its HTTP or keys, signs data, and returns public key information on demand via its HTTP or
RPC api. RPC api.
It is intended to be used as a remote RPC service for a It is intended to be used as a remote RPC service for a
@ -19,11 +19,11 @@ It is intended to be used as a remote RPC service for a
### Authentication ### Authentication
Notary Signer supports mutual TLS authentication from clients (the only client Notary Signer supports mutual TLS authentication from
it supports so far is the [Notary Server](notary-server.md). [Notary Server](notary-server.md).
Note that when you generate client certificates to be used with Notary Signer, Note that when you generate client certificates to be used with Notary Signer,
please make sure that the certificates **are not CAs**. Otherwise any server please make sure that the certificates **are not CAs**. Otherwise any client
that is compromised can sign any number of other client certs. 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
@ -35,12 +35,13 @@ A JSON configuration file is used to configure Notary Signer. Please see the
[Notary Signer configuration document](notary-signer-config.md) [Notary Signer configuration document](notary-signer-config.md)
for more details about the format of the configuration file. for more details about the format of the configuration file.
The parameters of the configuration file can also be overwritten using You can also override the parameters of the configuration by
environment variables of the form `NOTARY_SIGNER_var`, where `var` is the setting environment variables of the form `NOTARY_SIGNER_var`.
full path from the top level of the configuration file to the variable you want `var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the
to override, in all caps. A change in level is denoted with a `_`. configuration JSON.
For instance, one part of the configuration file might look like: For instance, if you wanted to override the storage URL of the Notary Signer
configuration:
```json ```json
"storage": { "storage": {
@ -49,29 +50,33 @@ For instance, one part of the configuration file might look like:
} }
``` ```
If you would like to specify a different `db_url`, the full path from the top the full path of keys is `storage -> db_url`. So the environment variable you'd
of the configuration tree is `storage -> db_url`, so the environment variable need to set would be `NOTARY_SIGNER_STORAGE_DB_URL`.
to set would be `NOTARY_SIGNER_STORAGE_DB_URL`.
Note that you cannot override an intermediate level name. Setting Note that you cannot override a key whose value is another map.
`NOTARY_SIGNER_STORAGE=""` will not disable the MySQL storage. Each leaf For instance, setting `NOTARY_SIGNER_STORAGE=""` will not disable the
parameter value must be set indepedently. MySQL storage. You can only override keys whose values are strings or numbers.
#### Running a Docker image #### Running a Docker image
Get the official Docker image, which comes with some sane defaults. You can Get the official Docker image, which comes with [some defaults](
run it with your own MySQL DB: https://github.com/docker/notary/blob/master/cmd/notary-signer/config.json).
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
logging level:
``` ```
$ docker pull docker.io/docker/notary-signer $ docker pull docker.io/docker/notary-signer
$ docker run -p "4443:4443" \ $ docker run -p "4443:4443" \
-e NOTARY_SIGNER_STORAGE_DB_URL="myuse@mypass:tcp(mydb)/dbNname" \ -e NOTARY_SIGNER_LOGGING_LEVEL=info \
-e NOTARY_SIGNER_STORAGE_DB_URL="myuser:mypass@tcp(my-db)/dbName"
notary-signer notary-signer
``` ```
Alternately, you can run with your own configuration file entirely. The Alternately, you can run the image with your own configuration file entirely.
docker image loads the config file from `/opt/notary-signer/config.json`, so The docker image loads the config file from `/opt/notary-signer/config.json`,
you can mount your config file at `/opt/notary-signer`: so you can mount a directory with your config file (named `config.json`)
at `/opt/notary-signer`:
``` ```
$ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-signer notary-signer $ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-signer notary-signer
@ -80,27 +85,23 @@ $ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-signer notary-sig
#### Running the binary #### Running the binary
A JSON configuration file needs to be passed as a parameter/flag when starting A JSON configuration file needs to be passed as a parameter/flag when starting
up the Notary Signer binary. Environment variables can also be set in addition up the Notary Signer binary. Environment variables can also be set in addition
to the configuration file, but the configuration file is required. to the configuration file, but the configuration file is required. For example:
``` ```
$ export NOTARY_SIGNER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname $ export NOTARY_SIGNER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname
$ NOTARY_SIGNER_LOGGING_LEVEL=5 notary-signer -config /path/to/config.json $ 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
If using a DB backend, then all the timestamp private keys stored on the signer All the timestamp private keys stored on the signer will be compromised, and
will be compromised. The attacker cannot do anything with the timestamp keys an attacker can sign anything they wish with the timestamp key.
unless they also compromise the Notary Server, though.
The attacker can prevent Notary Signer from signing any Notary Server metadata, However, the attacker cannot do anything useful with the timestamp keys unless
and return invalid public key IDs when the Notary Server requests it, and this they also [compromise the Notary Server](
execute a denial of service attack, which would prevent the Notary Server from notary-server.md#what-happens-if-the-server-is-compromised)
being able to update any metadata.
### Ops features The attacker can prevent Notary Signer from signing timestap metadata from
Notary Server and return invalid public key IDs when the Notary Server
Notary signer provides the following endpoints for ops friendliness: 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.
1. A [Bugsnag](https://bugsnag.com) hook for error logs, if a Bugsnag
configuration is provided.