Capsule8 Docs
Capsule8 Docs

Sensor Configuration

After you have installed the Capsule8 sensor, you can configure the sensor’s functionality as well as optionally pair the sensor with the Capsule8 server. By default, the Capsule8 sensor looks in /etc/capsule8 for a capsule8-sensor.yaml file.

Configuring the Sensor

The following table describes the environment variables and configuration file values used by the Capsule8 sensor. [Need to insert why a customer would want to change this]

Variable Name Configuration File Value Type Meaning Default Example
CAPSULE8_CONFIG N/A string Alternate location and name of the capsule8-sensor.yaml file /etc/capsule8/capsule8-sensor.yaml CAPSULE8_CONFIG=/var/run/myconfig.yaml
CAPSULE8_LABELS service.labels string a string of key value pairs separated by = metadata about the sensor host “” CAPSULE8_LABELS=“mtahost=true”
CAPSULE8_DEBUG debug boolean whether or not to enable debugging / profiling features and logging false CAPSULE8_DEBUG=true
CAPSULE8_NATS_URL nats.url string The address of the Capsule8 Server’s NATS instance nats://localhost:4222
CAPSULE8_NATS_MAX_RECONNECTS nats.max_reconnects integer number of times the client should attempt to reconnect after it’s already been connected 10000 CAPSULE8_NATS_MAX_RECONNECTS=3
CAPSULE8_NATS_RECONNECT_BUF_SIZE_IN_MB nats.reconnect_buf_size_in_mb integer amount of data to buffer in the event of a disconnection in megabytes 10 CAPSULE8_NATS_RECONNECT_BUF_SIZE_IN_MB=1
CAPSULE8_NATS_RECONNECT_WAIT nats.reconnect_wait integer number of seconds the the NATS client should wait between connection attempts 10 CAPSULE8_NATS_RECONNECT_WAIT=3
CAPSULE8_NATS_CLIENT_CERT_FILE nats.client_cert_file string path to x509 certifate A TLS client certificate to present to the Capsule8 Server NATS instance ( must be used with CAPSULE8_NATS_CLIENT_CERT_KEY_FILE) “” CAPSULE8_NATS_CLIENT_CERT_FILE=/home/user/client.crt
CAPSULE8_NATS_CLIENT_CERT_KEY_FILE nats.client_cert_key_file string path to x509 certifate key The path to the key for the certificate in CAPSULE8_NATS_CLIENT_CERT_FILE ( must be used with CAPSULE8_NATS_CLIENT_CERT_FILE) “” CAPSULE8_NATS_CLIENT_CERT_KEY_FILE=/home/user/client.crt
CAPSULE8_NATS_CLIENT_CA_CERT nats.client_ca_cert string path to x509 CA certifcate An additional TLS CA certificate to use to verify the client. By default the system CAs are used “” CAPSULE8_NATS_CLIENT_CA_CERT=/usr/local/cas/myCA.crt
CAPSULE8_INITIAL_RECONNECT_ATTEMPTS initial_reconnect_attempts integer the number of times the sensor attempts to connect to the server before giving up at startup 3 CAPSULE8_INITIAL_RECONNECT_ATTEMPTS=8
CAPSULE8_MONITOR_PORT monitor_port integer TCP port to serve health checks, version, varz and profiling endpoints 9010 CAPSULE8_MONITOR_PORT=9999
CAPSULE8_LISTEN_ADDR listen_addr string socket address for the sensor telemetry service to listen on (can be a unix socket) unix://var/run/capsule8/sensor.sock CAPSULE8_LISTEN_ADDR=localhost:8443
CAPSULE8_EVENTS_PER_MESSAGE bundler.events_per_message integer number of telemetry events to send to the server at a time, useful for microbatching / controlling network impact of the sensor 1 CAPSULE8_EVENTS_PER_MESSAGE=250
CAPSULE8_EVENTS_FLUSH_TIMEOUT bundler.flush_timeout duration string maxmium amount of time Telemetry Events can stay buffered in the sensor before being sent to the Capsule8 Server “100ms” CAPSULE8_EVENTS_FLUSH_TIMEOUT=“250ms”
CAPSULE8_OPENTRACING_TRACER_TYPE opentracing.tracer_type string a supported open tracing implementation right now only jaeger is supported “” CAPSULE8_OPENTRACING_TRACER_TYPE=jaeger
CAPSULE8_OPENTRACING_TRACER_LOG opentracing.tracer_log boolean log opentracing information to standard out false CAPSULE8_OPENTRACING_TRACER_LOG=true
CAPSULE8_USE_ANALYTICS use_analytics boolean activate embedded analytics package (activate’s further configuration for analytics) true CAPSULE8_USE_ANALYTICS=false
CAPSULE8_FLIGHT_RECORDER_ENABLED flight_recorder.enabled boolean activate the embedded flight recorder (and enable investigations) false CAPSULE8_FLIGHT_RECORDER_ENABLED=true
CAPSULE8_FLIGHT_RECORDER_DB_DIR flight_recorder.db_dir string the directory that the flight recorder will use to store data “/var/run/capsule8/” CAPSULE8_FLIGHT_RECORDER_DB_DIR=/tmp/data
CAPSULE8_FLIGHT_RECORDER_SPACE_LIMIT flight_recorder.db_size_limit int the maximum size of the flight recorder’s database in megabytes 100 CAPSULE8_FLIGHT_RECORDER_SPACE_LIMIT=512
CAPSULE8_FLIGHT_RECORDER_METAEVENTS_WHITELIST flight_recorder.metaevents_whitelist list the list of metaevents to include in the flight recorder data “” CAPSULE8_FLIGHT_RECORDER_METAEVENTS_WHITELIST=“shell_command terminal_write”
N/A investigations.sinks list the sinks to use when flushing data “” (see below)
N/A investigations.reporting_interval string the time duration that describes the flusher’s intervals between reports “” investigations.reporting_interval: “30s”
CAPSULE8_FLUSHER_SERVER_MAX_PAYLOAD_SIZE investigations.max_payload_size int maximum number of bytes for a single flushed payload 4194304 CAPSULE8_FLUSHER_SERVER_MAX_PAYLOAD_SIZE=true
CAPSULE8_FLUSHER_SERVER_TIMEOUT investigations.timeout string the time duration string that sets the flusher’s timeour 5s CAPSULE8_FLUSHER_SERVER_TIMEOUT=“2h45m”
CAPSULE8_TRIGGER_ON trigger_on boolean enable the event trigger true CAPSULE8_TRIGGER_ON=false
CAPSULE8_TRIGGER_INTERVAL trigger_interval time.Duration set the event trigger interval 10s CAPSULE8_TRIGGER_INTERVAL=1s
CAPSULE8_TRIGGER_SYSCALL trigger_syscall enum string set the event trigger syscall “setxattr” CAPSULE8_TRIGGER_SYSCALL=setxattr
CAPSULE8_RUN_WITHOUT_SERVER run_without_server boolean Run the sensor standalone without the server true CAPSULE8_RUN_WITHOUT_SERVER=false

Example /etc/capsule8/capsule8-sensor.yaml file

Below is an example config file containing all of the config options.

# port
monitor_port: 9010
# number of times to connect to nats on boot
initial_reconnect_attempts: 3

listen_addr: "unix://var/run/capsule8/sensor.sock"

  # arbitrary metadata as a string of key value pairs separated by an equal
  labels: "region=US-EAST-1 az=US-EAST-1A"

  url: nats://capsule8-server:4222
  client_cert_file: /etc/capsule8/client.crt
  client_cert_key_file: /etc/capsule8/client.key
  client_ca_cert: /etc/capsule8/nats_ca.crt
  # number of seconds to wait between reconnection attempts
  reconnect_wait: 5
  # number of reconnection attempts to try
  max_reconnects: 120
  # amount of telemetry data to buffer before droping events when disconnected
  # from the server in megabytes
  reconnect_buf_size_in_mb: 10

  # number of telemetry events to bundle together into a single message that is
  # sent to the server
  events_per_message: 250
  # largest amount of latency
  flush_timeout: 100ms

  # log spans to a jaeger instance (note we expect the agent to be configured locally)
  tracer_type: jaeger
  # log tracer information to standard out
  tracer_log: false

debug: false

# embedded analytics package (must be coordinated with server)
use_analytics: true

# embedded flight recorder
  # required true for flight recorder to me enabled
  enabled: true
  db_dir: /var/run/capsule8
  db_size_limit: 100
  - shell_command

# investigations are enabled by the flight recorder's enabled variable
  reporting_interval: 10s
    # sink names are the bucket name or directory path for the data to be flushed
    # (eg. metaevents flushes to s3://metaevents)
    - name: metaevents
      # valid backends are aws, gcp and local
      # credentials for the backend must be configured for access to any cloud
      backend: aws
      automated: true

# optionally change alert timestamp format
alert_timestamp_format: RFC3339

Pairing with the Capsule8 Server

The sensor configuration should include a list of API servers used by the Capsule8 server so the two components can be paired. For test installations where the sensor is running on the same host as the API server, a sensor configuration deployment is not required.

Ask your Capsule8 representative for your sensor configuration file. Then, install the capsule8-sensor.yaml file to /etc/capsule8 to finish installation. An example configuration is as follows:

  #url of the capsule8-server with nats prefix, note: can use tls:// to use
  #tls and validate the server.
  url: nats://localhost:4222
  #client_cert_file: /etc/capsule8/client.crt
  #client_cert_key_file: /etc/capsule8/client.key
  #ca_cert: /etc/capsule8/ca.crt