# 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.