cloudelements-petit/doc/config.md

# Cloud Elements On-Prem Config File

This document describes the On-Prem Connector
[toml](https://github.com/toml-lang/toml) config file, which lives on
both the client and server. When the On-Prem Connector starts up (either
the client or server), it will create a file with default values if one
does not already exist. The 'init' command for both `petit-server` and
`petit-client` will do nothing but create this file.

All client and server commands, and the clientd and serverd daemons
themselves, accept a `-c {path}` command-line option to specify a config
file. Otherwise, the default `{user_home}/.petit/config.toml` will be
used.

### Server

The server section of the config file is used only by `petit-server` or
`petit-serverd`, and is indicated by the section headers

    [server]
    [server.vitae]

#### Section `[server]`

The `[server]` section has only five properies:

* `proxyPort`: This is the port where the petit server will listen to
  HTTP requests, which it will then forward to the proper proxied port.
  `8090` is the default.

* `secureProxyPort`: Similar to `proxyPort`, this is the port where the
  petit server will listen to HTTPS requests, which it will then forward
  to the proper proxied port. `8453` is the default.

* `backPort`: This server port listens for client backchannel
  communication; it should match the `backPort` value in the clients
  which wish to talk to this server. `3014` is the default.

* `listenPort`: The server will listen to commands on this port
  (`petit-server` will send commands to this port on localhost). This
  should be an open port on the server: `3016` is the default.

* `registryfile`: The server maintains a table of all registered
  clients, and the keys and ports for each. This file is where the
  table is stored.

  Like all file properties, it can start with `./` or `../` to indicate
  a path relative to the config file itself. `./registry` is the
  default. The registry file is a JSON file kept up-to-date by the
  serverd process. It looks something like this:

      {
        "version": 1,
        "maxRegisteredId": 1005,
        "maxRegisteredPort": 11085,
        "registeredIds": {
          "1001": {
            "port": 11081,
            "key": "(...public key data...)",
            "vitae": {
              "ip": "::ffff:127.0.0.1"
            }
          }
        }
      }

#### Section `[server.vitae]`

The `[server.vitae]` section contains information about the server's
environment which is sent to each client. It currently has two useful
properties:

* `environment`: This is the name of the environment type. It is
  generally a simple lower-case identifying string such as `"local"`,
  `"staging"` or `"production"`, etc.

* `endpoint`: This is the http or https endpoint that would be used to
  connect to a particular client, and should be a URL that reaches
  the server. The exact string `REGID` is used in place of the client's
  registration ID. For example:
  `https://REGID.g2c-staging.cloud-elements.com` could be used on the
  staging Ground2Cloud server.

#### Additional Values

In addition to these properties, there are some values that are fixed:
they don't show up in the config file, nor can they be altered:

* `./patches`: The location where the server stores its patches. The
  `index.json` file here lists where all the patches are.

* `./server.lock` is the name of the file which is used to ensure that
  only one server daemon is running at a time. It is a zero-byte file
  whose mere existance indicates that a server is running.

* `./server.pid` is a JSON file whose contents contain the PID and
  listen port of the currently running server daemon, like this:

      {"pid":46510,"listen":3016}

  Under normal circumstances, this file will exist if and only if its
  sibling `./server.lock` also exists.

* `./logs/server.log` is the log file where logs are stored. This contains
  all logging and debugging info for particular server runs. While not
  strictly a JSON file, it is a
  [winston](https://github.com/winstonjs/winston)-style JSON log output.
  For example:

      {"address":"::","family":"IPv6","port":3016,"level":"info","message":"Command listening on","timestamp":"2016-01-22T21:09:24.295Z"}
      {"address":"::","family":"IPv6","port":3014,"level":"info","message":"Backchannel listening on","timestamp":"2016-01-22T21:09:24.298Z"}
      {"level":"info","message":"Proxy connected.","timestamp":"2016-01-22T21:09:24.299Z"}

  To minimize storage footprint, if the log exceeds 50,000 bytes, then a
  new log file is started, and the previous one will be suffixed with a
  counter (e.g. `./server1.log`), and only the last three log files will
  be kept.

* `./certificates`: only if this directory exists and contains the three
  files `server.key`, `server.crt` and `ca.bundle` (all PEM key/cert
  files) will HTTPS requests be serviced at `secureProxyPort`.

### Client

The client section of the config file is used only by `petit-client` or
`petit-clientd`, and is indicated by the section headers

    [client]
    [client.vitae]
    [client.local]

#### Section `[client]`

The `[client]` header indicates general-purpose values for the client to
start up.

* `host`: The hostname of where the server is located. `localhost` is
  a good default for testing, but this should be changed to a valid
  server host in most environments.

* `port`: The active _sshd_ port on the server. This should almost
  always be set to `22`, the default value.

* `backPort`: The active _backchannel_ port on the server. This should
  match the `backPort` value on the server: default is `3014`.

* `username`: The ssh username to connect to. In most situations, this
  should match the username the petit server is running as.

* `listenPort`: The client will listen to commands on this port
  (`petit-client` will send commands to this port on localhost). This
  should be an open port on the server: `3015` is usually a good
  default.

* `logLevel`: The startup log level, which must be one of `"warn"`,
  `"info"` or `"debug"`. This level takes effect immediately at startup.
  Runtime changes to the logging level (for example with `petit-client
  log [level]`) aren't permanent, since they don't save to the config
  file.

* `bindAddr`: This specifies the client-specified Bind Address property
  of the reverse SSH tunnel, which determines what address connections
  are allowed to connect. The default is `0.0.0.0`, which permits all
  IPv4 addresses. Other values could be `localhost`, which permits only
  local connections (useful if you want to secure access via the HTTP
  proxy only); `::` to permit any IPv6 connection; or any specific IP to
  limit connections there.

#### Section `[client.vitae]`

The `[client.vitae]` section contains information about the client's
environment which is sent to the server. It currently has two useful
properties:

* `brand`: This is the name of the brand for "branded" clients, and is
  usually set to the customer name who is using the G2C client (e.g.
  `"swiftpage"`). Evaluation or Cloud-Elements branded clients should
  use the value `"ce"`.

* `bundle`: Set to `"quickbooks"` for client applications distributed in
  the QuickBooks-bundled installer. Do not include at all for the
  unbundled version.

#### Section `[client.local]`

The `[client.local]` section has values that correspond to the local
service which a cloud element instance connects to. There are only two
properties:

* `host`: The hostname where the local service lives. `localhost` is a
  good default, since the On-Prem Connector is often installed on the
  same machine as the local service. However, any reachable hostname can
  be used, if for example, you want the On-Prem Connector to live in a
  different intranet zone.

* `port`: The port where local service is reached. The default of `8080`
  is appropriate for other Cloud Elements connection services (for
  example, the native QuickBooks connector runs on port 8080), but might
  be changed for other services.

These `[client.local]` values may be overriden per-tenant in each
tenant's own `config.toml` file, which contains its own `[local]`
section with a `host` and `port` value.

#### Additional Values

In addition to these properties, there are some values that are fixed:
they don't show up in the config file, nor can they be altered:

* `./key`: The location of the client's private key. The `register`
  command, if successful, may write the key to this path, and the
  key will be used both for the initial backchannel handshake and ssh
  login when petit starts.

* `./tenants`: The location of the tenant registration, which has a
  a list of directories, each of which has its own registration file.

* `./upgrades`: A directory where the client temporarily stores
  downloaded patches to run.

* `./client.lock` is the name of the file which is used to ensure that
  only one client daemon is running at a time. It is a zero-byte file
  whose mere existance indicates that a client is running.

* `./client.pid` is a JSON file whose contents contain the PID and
  listen port of the currently running client daemon, like this:

      {"pid":46510,"listen":3016}

  Under normal circumstances, this file will exist if and only if its
  sibling `./client.lock` also exists.

* `./client.log` is the log file where logs are stored. This contains
  all logging and debugging info for particular client runs. While not
  strictly a JSON file, it is a
  [winston](https://github.com/winstonjs/winston)-style JSON log output.
  For example:

      {"address":"::","family":"IPv6","port":3015,"level":"info","message":"Command listening on","timestamp":"2016-01-22T18:55:24.259Z"}
      {"level":"info","message":"Client listening.","timestamp":"2016-01-22T18:55:24.260Z"}
      {"level":"warn","message":"Unable to connect to server at \"localhost:3014\".","timestamp":"2016-01-22T18:55:24.266Z"}
      {"level":"info","message":"Client closed.","timestamp":"2016-01-22T18:55:24.266Z"}
      {"level":"info","message":"Backchannel closed.","timestamp":"2016-01-22T18:55:24.266Z"}

  To minimize the installation footprint, if the log exceeds 50,000
  bytes, then a new log file is started, and the previous one will be
  suffixed with a counter (e.g. `./client1.log`), and only the last
  three log files will be kept.