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>
<td valign="top"><code>tls_key_file</code></td>
<td valign="top">no</td>
<td valign="top">Specifies the private key to use for HTTPS. Must be
provided together with <code>tls_cert_file</code>, or not at all.
If neither are provided, the server will use HTTP instead of HTTPS.
The path is relative to the current working directory where
<td valign="top">The path to the private key to use for
HTTPS. Must be provided together with <code>tls_cert_file</code>,
or not at all. If neither are provided, the server will use HTTP
instead of HTTPS. The path is relative to the directory where
notary-server is run.</td>
</tr>
<tr>
<td valign="top"><code>tls_cert_file</code></td>
<td valign="top">no</td>
<td valign="top">Specifies the certificate to use for HTTPS. Must be
provided together with <code>tls_key_file</code>, or not at all.
If neither are provided, the server will use HTTP instead of HTTPS.
The path is relative to the current working directory where
notary-server is run.</td>
<td valign="top">The path to the certificate to use for HTTPS.
Must be provided together with <code>tls_key_file</code>, or not
at all. If neither are provided, the server will use HTTP instead
of HTTPS. The path is relative to the directory where notary-server
is run.</td>
</tr>
</table>
### `auth` subsection (optional)
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:
@ -123,8 +123,9 @@ Example:
}
```
Note that this entire section is optional. However, you would like
authentication, then then the required parameters below are needed configure it.
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:**
@ -154,11 +155,11 @@ authentication post login.)
</tr>
</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
service. If it is left out, a local in-memory ED25519 trust service will be
used.
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:
@ -174,9 +175,9 @@ Remote trust service example:
}
```
Note that this entire section is optional. However, you would like to use a
separate trust service (recommended), then then the required parameters below
are needed configure it.
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>
@ -187,8 +188,9 @@ are needed configure it.
<tr>
<td valign="top"><code>type</code></td>
<td valign="top">yes</td>
<td valign="top">Must be `"remote"`; all other values will result in a
local trust service (and the rest of the parameters will be ignored)</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>
@ -203,42 +205,41 @@ are needed configure it.
<tr>
<td valign="top"><code>key_algorithm</code></td>
<td valign="top">yes</td>
<td valign="top">The key algorithm/type that will be generated and
stored on the signing service. Valid values are `ecdsa`, `rsa`,
and `ed25519`.</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 root CA or TLS cert of the remote service, if it is
self-signed or otherwise not in the system's default trust roots.
The path is relative to the current working directory where
notary-server is run.</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 private key to use for TLS mutual authentication.
Must be provided together with <code>tls_client_cert</code> or not
at all. The path is relative to the current working directory where
notary-server is run.</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">optional</td>
<td valign="top">The certificate to use for TLS mutual authentication.
Must be provided together with <code>tls_client_key</code> or not
at all. The path is relative to the current working directory where
notary-server is run.</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)
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.
The logging section sets the log level of the server. If it is not provided
or invalid, the server defaults to an ERROR logging level.
Example:
@ -248,9 +249,9 @@ Example:
}
```
Note that this entire section is optional. However, you would like to
specify a different log level, then then the required parameters below
are needed configure it.
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>
<tr>
@ -267,10 +268,11 @@ are needed configure it.
</tr>
</table>
## `storage` section (optional)
## `storage` section (optional but recommended)
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.
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:
@ -281,9 +283,9 @@ DB storage example:
}
```
Note that this entire section is optional. However, you would like to
use a database backend (recommended), then then the required parameters below
are needed configure it.
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>
@ -302,17 +304,18 @@ are needed configure it.
<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>
endpoint the username/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.
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": {
@ -322,8 +325,8 @@ configuration.
}
```
Note that this entire section is optional. However, you would like to
use Bugsnag reporting, then then the required parameters below are needed
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
configure it.
<table>
@ -341,13 +344,12 @@ configure it.
<tr>
<td valign="top"><code>bugsnag_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>
<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>The current release stage, such as "production" (which is the
default), used to filter errors in the Bugsnag dashboard.</td>
<td>The current release stage, such as "production". You can
use this value to filter errors in the Bugsnag dashboard.</td>
</tr>
</table>

128
docs/notary-server.md
View File

@ -10,11 +10,22 @@ parent="mn_notary"
# Notary Server
The notary server is a remote store for, and coordinates updates to, the signed
metadata files for a repository (which are created by clients). The server is
also responsible for creating and keeping track of timestamp keys for each repo,
and signing a timestamp file for each repo whenever a client sends updates,
after verifying the root, target, and snapshot signatures on the client update.
The Notary Server stores and updates the signed
[TUF metadata files](
https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L348)
for a repository. The root, snapshot, and targets metadata files are generated
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
@ -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
uses to sign tokens.
The client will log into the server (it gets redirected by Notary Server if
authentication is configured), obtain a token, and present the token to Notary
Server, which should be configured to trust signatures from that authorization
If token authentication is enabled on Notary Server, then any client that
does not have a token will be redirected to the authoriziation server.
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.
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)
for more information.
### Server storage
Currently Notary Server uses MySQL as a backend for storing the timestamp
*public* keys and the TUF metadata for each repository.
Notary Server uses MySQL as a backend for storing the timestamp
public keys and the TUF metadata for each repository. It relies on a signing
service to store the private keys.
### Signing service
The recommended usage of the server is with a separate signing service:
[Notary Signer](notary-signer.md). The signing service actually
stores the timestamp *private* keys and performs signing for the server.
We recommend deploying Notary Server with a separate, remote signing
service: [Notary Signer](notary-signer.md). This signing service generates
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
server itself.
By using remote a signing service, the private keys would never need to be
stored on the server itself.
Notary Signer supports mutual authentication - when you generate client
certificates for Notary Server to authenticate with Notary Signer, please make
sure that the certificates **are not CAs**. Otherwise any server that is
compromised can sign any number of other client certs.
certificates for your deployment of Notary Server, please make
sure that the certificates **are not CAs**. Otherwise if the server is
compromised, it can sign any number of other client certs.
As an example, please see [this script](opensslCertGen.sh) to see how to
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
[Notary Server configuration document](notary-server-config.md)
for more details about the format of the configuration file.
The parameters of the configuration file can also be overwritten using
environment variables of the form `NOTARY_SERVER_var`, where `var` is the
full path from the top level of the configuration file to the variable you want
to override, in all caps. A change in level is denoted with a `_`.
You can also override the parameters of the configuration by
setting environment variables of the form `NOTARY_SERVER_var`.
`var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the
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
"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
of the configuration tree is `storage -> db_url`, so the environment variable
to set would be `NOTARY_SERVER_STORAGE_DB_URL`.
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`.
Note that you cannot override an intermediate level name. Setting
`NOTARY_SERVER_STORAGE=""` will not disable the MySQL storage. Each leaf
parameter value must be set indepedently.
Note that you cannot override a key whose value is another map.
For instance, setting `NOTARY_SERVER_STORAGE=""` will not disable the
MySQL storage. You can only override keys whose values are strings or numbers.
#### Running a Docker image
Get the official Docker image, which comes with some sane defaults. You can
run it with your own signer service and mysql DB, or in the example below, with
just a local signing service and memory 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.
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
@ -97,9 +114,10 @@ $ docker run -p "4443:4443" \
notary-server
```
Alternately, you can run with your own configuration file entirely. The
docker image loads the config file from `/opt/notary-server/config.json`, so
you can mount your config file at `/opt/notary-server`:
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`,
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
@ -108,7 +126,7 @@ $ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-server notary-ser
#### Running the binary
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
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
@ -117,35 +135,37 @@ $ NOTARY_SERVER_LOGGING_LEVEL=info notary-server -config /path/to/config.json
### What happens if the server is compromised
The server does not hold any keys for the repository except the timestamp key,
so the attacker cannot modify the root, targets, or snapshots metadata.
The server does not hold any keys for repositories, except the for timestamp
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.
They can use the server to make calls to the signer service to sign arbitrary
data, such as an empty timestamp, an invalid timestamp, or an old timestamp.
If you are using a signer service, an attacker cannot get access to the
timestamp key either. They can use the server's credentials to get the signer
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
existing clients for existing repositories download arbitrary data. They would
need the original root/target/snapshots keys. The attacker could, by signing
bad timestamps, prevent the user from seeing any updated metadata.
However, TOFU (trust on first use) would prevent the attacker from tricking
existing clients for existing repositories to download arbitrary data.
They would need the original root/target/snapshots keys to do that. The
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
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.
### 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
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.
If it cannot contact the signing service (in which case service is degraded,
but not down, since the server can still serve metadata, but not accept
updates), an error will be logged, but the service will still be considered
healthy.
If it cannot contact the signing service, an error will be logged but the
service will still be considered healthy, because it can still serve
existing metadata. It cannot accept updates, so the service is degraded.
1. A [Bugsnag](https://bugsnag.com) hook for error logs, if a Bugsnag
configuration is provided.

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

@ -27,13 +27,6 @@ An example (full) server configuration file.
"storage": {
"backend": "mysql",
"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">yes</td>
<td valign="top">The TCP address (IP and port) to listen for GRPC
traffic (which Notary Server uses) on. Examples:
traffic. Examples:
<ul>
<li><code>":7899"</code> means listen on port 7899 on all IPs (and
hence all interfaces, such as those listed when you run
@ -92,29 +85,61 @@ Example:
<tr>
<td valign="top"><code>key_file</code></td>
<td valign="top">yes</td>
<td valign="top"> Specifies the private key to use for HTTPS. The path
is relative to the current working directory where notary-signer
is run.</td>
<td valign="top">The path to the private key to use for
HTTPS. The path is relative to the directory where
notary-signer is run.</td>
</tr>
<tr>
<td valign="top"><code>cert_file</code></td>
<td valign="top">yes</td>
<td valign="top"> Specifies the certificate to use for HTTPS. The path
is relative to the current working directory where notary-signer
is run.</td>
<td valign="top">The path to the certificate to use for
HTTPS. The path is relative to the directory where
notary-signer is run.</td>
</tr>
<tr>
<td valign="top"><code>client_ca_file</code></td>
<td valign="top">no</td>
<td valign="top">The root cert (or just the public cert) to trust for
mutual authentication. If provided, a client certificate will be
required for any client certificates connecting to Notary Signer.
If not provided, mutual authentication will not be required. The
path is relative to the current working directory where
<td valign="top">The root certificate to trust for
mutual authentication. If provided, any clients connecting to
Notary Signer will have to have a client certificate signed by
this root. If not provided, mutual authentication will not be
required. The path is relative to the directory where
notary-signer is run.</td>
</tr>
</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)
@ -145,86 +170,3 @@ Example:
<code>"fatal"</code> (1), or <code>"panic"</code>(0)</td>
</tr>
</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
The Notary Signer is a remote store for private keys. It will create and delete
keys, signs data, and return public key information on demand via its HTTP or
The Notary Signer is a remote store for private keys. It creates and delete
keys, signs data, and returns public key information on demand via its HTTP or
RPC api.
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
Notary Signer supports mutual TLS authentication from clients (the only client
it supports so far is the [Notary Server](notary-server.md).
Notary Signer supports mutual TLS authentication from
[Notary Server](notary-server.md).
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.
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)
for more details about the format of the configuration file.
The parameters of the configuration file can also be overwritten using
environment variables of the form `NOTARY_SIGNER_var`, where `var` is the
full path from the top level of the configuration file to the variable you want
to override, in all caps. A change in level is denoted with a `_`.
You can also override the parameters of the configuration by
setting environment variables of the form `NOTARY_SIGNER_var`.
`var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the
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
"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
of the configuration tree is `storage -> db_url`, so the environment variable
to set would be `NOTARY_SIGNER_STORAGE_DB_URL`.
the full path of keys is `storage -> db_url`. So the environment variable you'd
need to set would be `NOTARY_SIGNER_STORAGE_DB_URL`.
Note that you cannot override an intermediate level name. Setting
`NOTARY_SIGNER_STORAGE=""` will not disable the MySQL storage. Each leaf
parameter value must be set indepedently.
Note that you cannot override a key whose value is another map.
For instance, setting `NOTARY_SIGNER_STORAGE=""` will not disable the
MySQL storage. You can only override keys whose values are strings or numbers.
#### Running a Docker image
Get the official Docker image, which comes with some sane defaults. You can
run it with your own MySQL DB:
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.
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 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
```
Alternately, you can run with your own configuration file entirely. The
docker image loads the config file from `/opt/notary-signer/config.json`, so
you can mount your config file at `/opt/notary-signer`:
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`,
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
@ -80,27 +85,23 @@ $ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-signer notary-sig
#### Running the binary
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
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
$ 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
If using a DB backend, then all the timestamp private keys stored on the signer
will be compromised. The attacker cannot do anything with the timestamp keys
unless they also compromise the Notary Server, though.
All the timestamp private keys stored on the signer will be compromised, and
an attacker can sign anything they wish with the timestamp key.
The attacker can prevent Notary Signer from signing any Notary Server metadata,
and return invalid public key IDs when the Notary Server requests it, and this
execute a denial of service attack, which would prevent the Notary Server from
being able to update any metadata.
However, the attacker cannot do anything useful with the timestamp keys unless
they also [compromise the Notary Server](
notary-server.md#what-happens-if-the-server-is-compromised)
### Ops features
Notary signer provides the following endpoints for ops friendliness:
1. A [Bugsnag](https://bugsnag.com) hook for error logs, if a Bugsnag
configuration is provided.
The attacker can prevent Notary Signer from signing timestap metadata from
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
that prevents the Notary Server from being able to update any metadata.