# Notary signer configuration file

This document is for those who are [running their own Notary service](../running_a_service.md) who
want to specify custom options.

## Overview

Notary signer [requires environment variables](#environment-variables-required-if-using-mysql)
to encrypt private keys at rest. It also requires a configuration file, the path to which is
specified on the command line using the `-config` flag.

Here is a full signer configuration file example; please click on the top level JSON keys to
learn more about the configuration section corresponding to that key:

{
  "server": {
    "grpc_addr": ":7899",
    "tls_cert_file": "./fixtures/notary-signer.crt",
    "tls_key_file": "./fixtures/notary-signer.key",
    "client_ca_file": "./fixtures/notary-server.crt"
  },
  "logging": {
    "level": 2
  },
  "storage": {
    "backend": "mysql",
    "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true",
    "default_alias": "passwordalias1"
  },
  "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": {
  "grpc_addr": ":7899",
  "tls_cert_file": "./fixtures/notary-signer.crt",
  "tls_key_file": "./fixtures/notary-signer.key",
  "client_ca_file": "./fixtures/notary-server.crt"
}
```


		 Parameter
		 Required
		 Description

		 grpc_addr
		 yes
		 The TCP address (IP and port) to listen for GRPC
			traffic.  Examples:

- ":7899" means listen on port 7899 on all IPs (and
				hence all interfaces, such as those listed when you run
				ifconfig)
			
- "127.0.0.1:7899" means listen on port 7899 on
				localhost only.  That means that the server will not be
				accessible except locally (via SSH tunnel, or just on a local
				terminal)

		 tls_key_file
		 yes
		 The path to the private key to use for
			GRPC TLS. The path is relative to the directory of the
			configuration file.

		 tls_cert_file
		 yes
		 The path to the certificate to use for
			GRPC TLS. The path is relative to the directory of the
			configuration file.

		 client_ca_file
		 no
		 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 of the
			configuration file.

## storage section (required)

This is used to store encrypted private keys.  We only support MySQL, PostgreSQL
or an in-memory store, currently.

Example:

```json
"storage": {
  "backend": "mysql",
  "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true",
  "default_alias": "passwordalias1"
}
```


		 Parameter
		 Required
		 Description

		 backend
		 yes
		 Must be "mysql", "postgres" or "memory".
			If "memory" is selected, the db_url
			is ignored.

		 db_url
		 yes if not memory
		 The 
			the Data Source Name used to access the DB. (https://github.com/go-sql-driver/mysql)
			(note: please include parseTime=true as part of the DSN)

		 default_alias
		 yes if not memory
		 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
			NOTARY_SIGNER_<DEFAULT_ALIAS_VALUE>.
			Please see the environment variable
			section for more information.

## Environment variables (required if using MySQL)

Notary signer stores the private keys in encrypted form.
The alias of the passphrase used to encrypt the keys is also stored.  In order
to encrypt the keys for storage and decrypt the keys for signing, the
passphrase must be passed in as an environment variable.

For example, the configuration above specifies the default password alias to be
`passwordalias1`.

If this configuration is used, then you must:

`export NOTARY_SIGNER_PASSWORDALIAS1=mypassword`

so that the Notary signer knows to encrypt all keys with the passphrase
`mypassword`, and to decrypt any private key stored with password alias
`passwordalias1` with the passphrase `mypassword`.

Older passwords may also be provided as environment variables.

Let's say that you wanted to change the password that is used to create new
keys (rotating the passphrase and re-encrypting all the private keys is not
supported yet).

You could change the config to look like:

```json
"storage": {
  "backend": "mysql",
  "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true",
  "default_alias": "passwordalias2"
}
```

Then you can set:

```bash
export NOTARY_SIGNER_PASSWORDALIAS1=mypassword
export NOTARY_SIGNER_PASSWORDALIAS2=mynewfancypassword
```

That way, all new keys will be encrypted and decrypted using the passphrase
`mynewfancypassword`, but old keys that were encrypted using the passphrase
`mypassword` can still be decrypted.

The environment variables for the older passwords are optional, but Notary
Signer will not be able to decrypt older keys if they are not provided, and
attempts to sign data using those keys will fail.

## Hot logging level reload
We don't support completely reloading notary signer configuration files yet at present. What we support for Linux and OSX now is:
- increase logging level by signaling `SIGUSR1`
- decrease logging level by signaling `SIGUSR2`

No signals and no dynamic logging level changes are supported for Windows yet.

Example:

To increase logging level
```
$ kill -s SIGUSR1 PID

or

$ docker exec -i CONTAINER_ID kill -s SIGUSR1 PID
```

To decrease logging level
```
$ kill -s SIGUSR2 PID

or

$ docker exec -i CONTAINER_ID kill -s SIGUSR2 PID
```
PID is the process id of `notary-signer` and it may not the PID 1 process if you are running
the container with some kind of wrapper startup script or something.

You can get the PID of `notary-signer` through
```
$ docker exec CONTAINER_ID ps aux

or

$ ps aux | grep "notary-signer -config" | grep -v "grep"
```


## Related information

* [Notary Server Configuration File](server-config.md)
* [Configuration sections common to the Notary server and signer](common-configs.md)
