Skip to content

Configuration

This page describes the configuration options and methodologies for Synse Server. It has a sane set of default configurations allowing it to run "out of the box", however a minimal configuration is required to register any plugins with it.

Synse Server has three sources of configuration:

  1. Built-in defaults
  2. Configuration file (YAML)
  3. Environment variables

Each item in the list above takes precedence over the item above it (e.g. environment variable configuration(s) would override YAML file configuration(s)).

Configuring the Server

Specifying a Custom Config File

Synse Server looks for a YAML file (.yml or .yaml extension) named config in the current working directory (./) and within the default configuration directory (/etc/synse/server). If the configuration file is not found in either of those locations, no config file is used and it will fall back to using the default configuration values.

A custom configuration specified in custom-config.yml can be used to configure a Synse Server instance by placing the config in one of the search paths, e.g.

docker run -d \
    -p 5000:5000 \
    -v $PWD/custom-config.yml:/etc/synse/server/config.yml \
    vaporio/synse-server

Assuming the configuration is valid and Synse Server can successfully load it, you can verify that the config was picked up either by looking at the server logs, or by hitting the /config endpoint.

The above may also be done in a compose file:

version: '3'
services:
  synse-server:
    image: vaporio/synse-server
    ports:
    - '5000:5000'
    volumes:
    - ./custom-config.yml:/etc/synse/server/config.yml

Specifying Environment Variables

Many configuration options may also be set via environment variable. The general rule is that each environment variable is the upper-cased configuration key path joined with underscores and prefixed with SYNSE_. That is to say, for the example config {"foo": {"bar": 20}}, the corresponding environment variable would be SYNSE_FOO_BAR.

As a more concrete example, logging and the transaction cache TTL can be set with:

docker run -d \
    -p 5000:5000 \
    -e SYNSE_LOGGING=debug \
    -e SYNSE_CACHE_TRANSACTION_TTL=500 \
    vaporio/synse-server

The above may also be done in a compose file:

version: '3'
services:
  synse-server:
    image: vaporio/synse-server
    ports:
    - '5000:5000'
    environment:
    - SYNSE_LOGGING=debug
    - SYNSE_CACHE_TRANSACTION_TTL=500

Configuration Options

This section describes the supported configuration values for Synse Server, including any restrictions on the values, any defaults, and whether or not it can be set via environment variable.


Logging

description The logging level for Synse Server. The values for this option are case-insensitive.
type string
key logging
env variable SYNSE_LOGGING
default debug
supported debug, info, warning, error, critical
logging: info
SYNSE_LOGGING=info

Pretty JSON

description Output the HTTP API response JSON in a "pretty" format by adding spaces and newlines.
type bool
key pretty_json
env variable --
default true
supported true, false
pretty_json: true

Plugin

Configuration options for registering plugins with the server instance.

TCP

description Register plugins configured for TCP-based communication. This is the preferred mode for registering plugins. This option holds list of addresses for each plugin to register.
type list[string]
key plugin.tcp
env variable SYNSE_PLUGIN_TCP
default --
plugin:
  tcp:
  - localhost:5001
  - 192.1.53.2:5002
SYNSE_PLUGIN_TCP="localhost:5001,192.1.53.2:5002"

Unix

description Register plugins configured for Unix socket based communication. Generally, plugins should prefer TCP transport over unix socket. This option holds a list of paths to the unix sockets for each plugin to register.
type list[string]
key plugin.unix
env variable SYNSE_PLUGIN_UNIX
default --
plugin:
  unix:
  - /tmp/example.sock
SYNSE_PLUGIN_UNIX="/tmp/example.sock"

Note

When registering a plugin via unix socket, Synse Server needs access to that socket. If the server is running in a docker container, this means the socket must be mounted in, e.g.

docker run \
    ...
    -v $PWD/plugin.sock:/tmp/synse/plugin.sock \
    ...

Discover

Configuration options for dynamic plugin discovery. Currently, the only mode of plugin discovery that is supported is via Kubernetes Endpoint labels. As more modes are supported, this section will be updated. Examples of using Kubernetes discovery can be found on the Advanced Usage page.

Kubernetes Namespace

description The Kubernetes namespace to use for any configured plugin selectors. If there are no plugin selectors defined, this will have no effect. If plugin discovery is enabled and this field is left unspecified, the default namespace (default) is used.
type string
key plugin.discover.kubernetes.namespace
env variable SYNSE_PLUGIN_DISCOVER_KUBERNETES_NAMESPACE
default 'default'
plugin:
  discover:
    kubernetes:
      namespace: default
SYNSE_PLUGIN_DISCOVER_KUBERNETES_NAMESPACE=default

Kubernetes Endpoint Labels

description The Endpoint labels to use as selectors for Kubernetes Services belonging to plugins. This is a map where the key is the label name and the value is the value which the label should match to.
type map[string]string
key plugin.discover.kubernetes.endpoints.labels
env variable SYNSE_PLUGIN_DISCOVER_KUBERNETES_ENDPOINTS_LABELS_<KEY>
default --
plugin:
  discover:
    kubernetes:
      endpoints:
        labels:
          app: synse
          foo: bar
SYNSE_PLUGIN_DISCOVER_KUBERNETES_ENDPOINTS_LABELS_APP=synse
SYNSE_PLUGIN_DISCOVER_KUBERNETES_ENDPOINTS_LABELS_FOO=bar

Cache

Configuration options for Synse Server caches. There are two caches in the server:

  • device: A lookup cache for devices and their associated plugin and tags.
  • transaction: A lookup cache for write transactions and their associated devices.

Device

Rebuild Every

description The time interval, in seconds, to invalidate and rebuild the device cache to ensure it is up to date.
type int
key cache.device.rebuild_every
env variable --
default 180
cache:
  device:
    rebuild_every: 180  # three minutes

Plugin

Refresh Every

description The time interval, in seconds, to refresh the set of plugins (e.g. via discovery).
type int
key cache.device.refresh_every
env variable --
default 120
cache:
  plugin:
    refresh_every: 120  # two minutes

Transaction

TTL

description The time-to-live, in seconds, for a transaction in the cache. After this TTL, it will be cleared from the cache and removed from the system.
type int
key cache.transaction.ttl
env variable --
default 300
cache:
  transaction:
    ttl: 300  # five minutes

gRPC

Configuration options for requests made from the server to plugins via the internal gRPC API.

Timeout

description The timeout, in seconds, for a gRPC request.
type int
key grpc.timeout
env variable --
default 3
grpc:
  timeout: 3

TLS

TLS configurations for the internal gRPC client used to communicate with plugins.

Cert

description The path to the TLS certificate for securing the API connection.
type string
key grpc.tls.cert
env variable SYNSE_GRPC_TLS_CERT
default --
grpc:
  tls:
    cert: /path/to/cert.pem
SYNSE_GRPC_TLS_CERT="/path/to/cert.pem"

SSL

Configuration options for securing the server's HTTP/WebSocket APIs.

Cert

description The path to the SSL/TLS certificate for securing the API connection.
type string
key ssl.cert
env variable SYNSE_SSL_CERT
default --
ssl:
  cert: /path/to/cert.pem
SYNSE_SSL_CERT="/path/to/cert.pem"

Key

description The path to the SSL/TLS key for securing the API connection.
type string
key ssl.key
env variable SYNSE_SSL_KEY
default --
ssl:
  key: /path/to/key.key
SYNSE_SSL_KEY="/path/to/key.key"

Metrics

Configuration options for exposing application metrics via Prometheus exporter.

Enabled

description Enable application metrics export.
type bool
key metrics.enabled
env variable SYNSE_METRICS_ENABLED
default false
supported true, false
metrics:
  enabled: true
SYNSE_METRICS_ENABLED=true

Examples

Default Configuration

Below is what the default configuration for Synse Server looks like as YAML.

pretty_json: true
logging: debug
cache:
  device:
    rebuild_every: 180
  transaction:
    ttl: 300
grpc:
  timeout: 3
metrics:
  enabled: false

Complete Configuration

Below is a valid (if contrived) and complete example configuration file.

logging: debug
pretty_json: true
plugin:
  tcp:
    - localhost:6000
    - 54.53.52.51:5555
  unix:
    - /tmp/run/example.sock
  discover:
    kubernetes:
      endpoints:
        labels:
          app: synse
          component: plugin
cache:
  device:
    rebuild_every: 200  # seconds
  transaction:
    ttl: 300  # seconds
grpc:
  timeout: 5  # seconds
  tls:
    cert: /tmp/ssl/example.crt