mirror of https://github.com/docker/docs.git
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
parent
4d696a0187
commit
54c7de5bd6
|
|
@ -244,8 +244,8 @@ func usage() {
|
|||
// 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.
|
||||
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 {
|
||||
logrus.Fatal("error listening on debug interface: ", err)
|
||||
logrus.Fatalf("error listening on debug interface: %v", err)
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -240,8 +240,8 @@ func usage() {
|
|||
// 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.
|
||||
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 {
|
||||
log.Fatalf("error listening on debug interface: %v", err)
|
||||
logrus.Fatalf("error listening on debug interface: %v", err)
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -15,18 +15,9 @@ An example (full) server configuration file.
|
|||
```json
|
||||
{
|
||||
"server": {
|
||||
"addr": ":4443",
|
||||
"http_addr": ":4443",
|
||||
"tls_key_file": "./fixtures/notary-server.key",
|
||||
"tls_cert_file": "./fixtures/notary-server.crt",
|
||||
"auth": {
|
||||
"type": "token",
|
||||
"options": {
|
||||
"realm": "https://auth.docker.io/token",
|
||||
"service": "notary-server",
|
||||
"issuer": "auth.docker.io",
|
||||
"rootcertbundle": "/path/to/auth.docker.io/cert"
|
||||
}
|
||||
}
|
||||
},
|
||||
"trust_service": {
|
||||
"type": "remote",
|
||||
|
|
@ -37,17 +28,27 @@ An example (full) server configuration file.
|
|||
"tls_client_cert": "./fixtures/notary-server.crt",
|
||||
"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": {
|
||||
"level": "debug"
|
||||
},
|
||||
"storage": {
|
||||
"backend": "mysql",
|
||||
"db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo"
|
||||
},
|
||||
"reporting": {
|
||||
"bugsnag": "yes",
|
||||
"bugsnag_api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
|
||||
"bugsnag_release_stage": "notary-server"
|
||||
"bugsnag": {
|
||||
"api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
|
||||
"release_stage": "production"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -58,7 +59,7 @@ Example:
|
|||
|
||||
```json
|
||||
"server": {
|
||||
"addr": ":4443",
|
||||
"http_addr": ":4443",
|
||||
"tls_key_file": "./fixtures/notary-server.key",
|
||||
"tls_cert_file": "./fixtures/notary-server.crt"
|
||||
}
|
||||
|
|
@ -70,7 +71,7 @@ Example:
|
|||
<th>Description</th>
|
||||
</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">The TCP address (IP and port) to listen on. Examples:
|
||||
<ul>
|
||||
|
|
@ -90,8 +91,8 @@ Example:
|
|||
<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>
|
||||
instead of HTTPS. The path is relative to the directory of the
|
||||
configuration file.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<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.
|
||||
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>
|
||||
of HTTPS. The path is relative to the directory of the
|
||||
configuration file.</td>
|
||||
</tr>
|
||||
</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.
|
||||
Currently, we only support token authentication.
|
||||
|
|
@ -155,87 +274,6 @@ authentication post login.)
|
|||
</tr>
|
||||
</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)
|
||||
|
||||
The logging section sets the log level of the server. If it is not provided
|
||||
|
|
@ -268,46 +306,6 @@ below to configure it.
|
|||
</tr>
|
||||
</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)
|
||||
|
||||
The reporting section contains any configuration for useful for running the
|
||||
|
|
@ -319,15 +317,18 @@ about these configuration parameters.
|
|||
|
||||
```json
|
||||
"reporting": {
|
||||
"bugsnag": "yes",
|
||||
"bugsnag_api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
|
||||
"bugsnag_release_stage": "notary-server"
|
||||
"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 the required parameters below to
|
||||
configure it.
|
||||
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>
|
||||
|
|
@ -336,18 +337,12 @@ configure it.
|
|||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>bugsnag</code></td>
|
||||
<td valign="top"><code>api_key</code></td>
|
||||
<td valign="top">yes</td>
|
||||
<td>Any string value. If this value is not set, no errors will be
|
||||
reported to Bugsnag (all other parameters will be ignored)</td>
|
||||
<td>The BugSnag API key to use to report errors.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>bugsnag_api_key</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"><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>
|
||||
|
|
|
|||
|
|
@ -77,6 +77,7 @@ for more details about the format of the configuration file.
|
|||
|
||||
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.
|
||||
|
||||
|
|
@ -93,45 +94,58 @@ configuration:
|
|||
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`.
|
||||
|
||||
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.
|
||||
For instance, setting `NOTARY_SERVER_STORAGE=""` will not disable the
|
||||
MySQL storage. You can only override keys whose values are strings or numbers.
|
||||
For instance, setting
|
||||
`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.
|
||||
For example, if you wanted to run it with just a local signing service and
|
||||
memory store (not recommended for production):
|
||||
For example, if you wanted to run it with just a local signing service instead
|
||||
(not recommended for production):
|
||||
|
||||
```
|
||||
$ docker pull docker.io/docker/notary-server
|
||||
$ docker run -p "4443:4443" \
|
||||
-e NOTARY_SERVER_TRUST_SERVICE_TYPE=local \
|
||||
-e NOTARY_SERVER_STORAGE_BACKEND=""
|
||||
-e NOTARY_SERVER_STORAGE_DB_URL=""
|
||||
-e NOTARY_SERVER_TRUST_SERVICE_TYPE=local
|
||||
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`:
|
||||
You just need to mount your configuration directory, and then pass the path to
|
||||
that configuration file as an argument to the `docker run` command:
|
||||
|
||||
```
|
||||
$ 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
|
||||
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. For example:
|
||||
|
||||
```
|
||||
$ export NOTARY_SERVER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname
|
||||
$ NOTARY_SERVER_LOGGING_LEVEL=info notary-server -config /path/to/config.json
|
||||
```
|
||||
You can also pass the `-debug` flag to the container in addition to the
|
||||
configuration file, but the debug server port is not exposed by the container.
|
||||
In order to view the debug endpoints, you will have to `docker exec` into
|
||||
your container.
|
||||
|
||||
### What happens if the server is compromised
|
||||
|
||||
|
|
@ -157,7 +171,7 @@ know that something is wrong.
|
|||
|
||||
### 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
|
||||
body of `{}` if the server is healthy, and a 500 with a map of
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ An example (full) server configuration file.
|
|||
"server": {
|
||||
"http_addr": ":4444",
|
||||
"grpc_addr": ":7899",
|
||||
"cert_file": "./fixtures/notary-signer.crt",
|
||||
"key_file": "./fixtures/notary-signer.key",
|
||||
"tls_cert_file": "./fixtures/notary-signer.crt",
|
||||
"tls_key_file": "./fixtures/notary-signer.key",
|
||||
"client_ca_file": "./fixtures/notary-server.crt"
|
||||
},
|
||||
"logging": {
|
||||
|
|
@ -26,21 +26,31 @@ An example (full) server configuration file.
|
|||
},
|
||||
"storage": {
|
||||
"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" in this case refers to Notary Signer's HTTP/GRPC server, not
|
||||
"Notary Server".
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
"server": {
|
||||
"http_addr": ":4444",
|
||||
"grpc_addr": ":7899",
|
||||
"cert_file": "./fixtures/notary-signer.crt",
|
||||
"key_file": "./fixtures/notary-signer.key",
|
||||
"tls_cert_file": "./fixtures/notary-signer.crt",
|
||||
"tls_key_file": "./fixtures/notary-signer.key",
|
||||
"client_ca_file": "./fixtures/notary-server.crt"
|
||||
}
|
||||
```
|
||||
|
|
@ -83,18 +93,18 @@ Example:
|
|||
</td>
|
||||
</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">The path to the private key to use for
|
||||
HTTPS. The path is relative to the directory where
|
||||
notary-signer is run.</td>
|
||||
HTTPS. The path is relative to the directory of the
|
||||
configuration file.</td>
|
||||
</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">The path to the certificate to use for
|
||||
HTTPS. The path is relative to the directory where
|
||||
notary-signer is run.</td>
|
||||
HTTPS. The path is relative to the directory of the
|
||||
configuration file.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>client_ca_file</code></td>
|
||||
|
|
@ -103,21 +113,23 @@ Example:
|
|||
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>
|
||||
required. The path is relative to the directory of the
|
||||
configuration file.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## `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:
|
||||
|
||||
```json
|
||||
"storage": {
|
||||
"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>
|
||||
<td valign="top"><code>backend</code></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>
|
||||
<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>
|
||||
<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>
|
||||
<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_<default_alias_value></code>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
**Required environment variable:**
|
||||
<code>NOTARY_SIGNER_<default_alias_value></code>
|
||||
|
||||
**Optional environment variables:**
|
||||
<code>NOTARY_SIGNER_<old_alias_value></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)
|
||||
|
||||
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 signer defaults to an ERROR logging level.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
"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>
|
||||
<tr>
|
||||
<th>Parameter</th>
|
||||
|
|
@ -164,9 +198,52 @@ Example:
|
|||
<tr>
|
||||
<td valign="top"><code>level</code></td>
|
||||
<td valign="top">yes</td>
|
||||
<td valign="top">An integer between 0 and 5, representing values
|
||||
<code>"debug"</code> (5), <code>"info"</code> (4),
|
||||
<code>"warning"</code> (3), <code>"error"</code>(2),
|
||||
<code>"fatal"</code> (1), or <code>"panic"</code>(0)</td>
|
||||
<td valign="top">One of <code>"debug"</code>, <code>"info"</code>,
|
||||
<code>"warning"</code>, <code>"error"</code>, <code>"fatal"</code>,
|
||||
or <code>"panic"</code></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>
|
||||
</table>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
|
|
@ -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
|
||||
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.
|
||||
For example, if you wanted to run it with your own MySQL DB and a different
|
||||
logging level:
|
||||
For example, if you wanted to run it with your own DB
|
||||
(recommended for production):
|
||||
|
||||
```
|
||||
$ docker pull docker.io/docker/notary-signer
|
||||
$ docker run -p "4443:4443" \
|
||||
-e NOTARY_SIGNER_LOGGING_LEVEL=info \
|
||||
$ docker run -p "4444:4444" \
|
||||
-e NOTARY_SIGNER_STORAGE_DB_BACKEND="mysql" \
|
||||
-e NOTARY_SIGNER_STORAGE_DB_URL="myuser:mypass@tcp(my-db)/dbName"
|
||||
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`:
|
||||
You just need to mount your configuration directory, and then pass the path to
|
||||
that configuration file as an argument to the `docker run` command:
|
||||
|
||||
```
|
||||
$ 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
|
||||
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. For example:
|
||||
|
||||
```
|
||||
$ export NOTARY_SIGNER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname
|
||||
$ NOTARY_SIGNER_LOGGING_LEVEL=info notary-signer -config /path/to/config.json
|
||||
```
|
||||
You can also pass the `-debug` flag to the container in addition to the
|
||||
configuration file, but the debug server port is not exposed by the container.
|
||||
In order to view the debug endpoints, you will have to `docker exec` into
|
||||
your container.
|
||||
|
||||
### 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
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue