Skip to main content

Configuration

Both lplex and lplex-cloud support HOCON configuration files. CLI flags always override config file values.

Config file discovery​

lplex looks for config files in this order:

  1. Path specified with -config /path/to/file
  2. ./lplex.conf (current directory)
  3. /etc/lplex/lplex.conf

lplex-cloud uses the same pattern:

  1. -config /path/to/file
  2. ./lplex-cloud.conf
  3. /etc/lplex-cloud/lplex-cloud.conf

lplex (boat server)​

Full annotated config​

# CAN interface name
interface = can0

# HTTP listen port
port = 8089

# Maximum buffer duration for buffered client sessions (ISO 8601)
max-buffer-duration = PT5M

# Alert after this duration with no CAN frames (ISO 8601)
bus-silence-timeout = PT30S

health {
  # Health check reports unhealthy after this silence duration
  bus-silence-threshold = PT30S
}

send {
  # Enable /send and /query HTTP endpoints (default: false).
  # With no rules, all PGNs and destinations are allowed.
  enabled = true

  # Ordered rules evaluated top-to-bottom; first match wins.
  # No matching rule = deny. Empty list + enabled = allow all.
  #
  # Rules can be strings (DSL syntax) or native HOCON objects:
  #   String:  [!] [pgn:<spec>] [name:<hex>,...]
  #   Object:  { deny = true/false, pgn = "<spec>", name = "<hex>" or [...] }
  rules = [
    "!pgn:65280-65535"                         # string: deny proprietary PGNs
    "pgn:59904"                                # string: allow ISO Request
    { pgn = "126208", name = "001c6e4000200000" }   # object: allow command to device
    { pgn = "129025-129029", name = [               # object: PGN range + device list
      "001c6e4000200000"
      "001c6e4000200001"
    ]}
  ]
}

journal {
  # Directory for .lpj journal files (empty = disabled)
  dir = /var/log/lplex

  # Filename prefix
  prefix = nmea2k

  # Block size in bytes (power of 2, min 4096)
  block-size = 262144

  # Compression: none, zstd, zstd-dict
  compression = zstd

  rotate {
    # Rotate after this duration (ISO 8601, 0 = disabled)
    duration = PT1H

    # Rotate after this many bytes (0 = disabled)
    size = 0
  }

  retention {
    # Delete files older than this (ISO 8601, 0 = disabled)
    max-age = P30D

    # Keep at least this much data even if over max-age (ISO 8601)
    min-keep = PT24H

    # Hard cap on total journal size in bytes (0 = disabled)
    max-size = 10737418240

    # Percentage of max-size for proactive archiving (0-100)
    soft-pct = 80

    # What to do when hard cap is hit and archives failed:
    # delete-unarchived or pause-recording
    overflow-policy = delete-unarchived
  }

  archive {
    # Path to archive script (empty = disabled)
    command = /usr/local/bin/archive-to-s3

    # When to archive: on-rotate or before-expire
    trigger = on-rotate
  }
}

replication {
  # Cloud server gRPC address (empty = disabled)
  target = "cloud.example.com:9443"

  # Instance identifier (must match mTLS cert CN)
  instance-id = boat-001

  tls {
    # Client certificate for mTLS
    cert = /etc/lplex/client.crt

    # Client private key
    key = /etc/lplex/client.key

    # CA certificate to verify cloud server
    ca = /etc/lplex/ca.crt
  }
}

CLI flag reference​

FlagHOCON PathDefaultDescription
-interfaceinterfacecan0SocketCAN interface
-portport8089HTTP listen port
-max-buffer-durationmax-buffer-durationPT5MMax buffer timeout for sessions
-bus-silence-timeoutbus-silence-timeoutPT30SAlert on bus silence
-bus-silence-thresholdhealth.bus-silence-thresholdPT30SHealth check silence threshold
-send-enabledsend.enabledfalseEnable /send and /query endpoints
-send-rulessend.rules(empty)Semicolon-separated send rules (HOCON: string or object array)
-journal-dirjournal.dir(empty)Journal directory
-journal-prefixjournal.prefixnmea2kJournal file prefix
-journal-block-sizejournal.block-size262144Block size (bytes)
-journal-compressionjournal.compressionzstdCompression type
-journal-rotate-durationjournal.rotate.durationPT1HRotation interval
-journal-rotate-sizejournal.rotate.size0Rotation size
-journal-retention-max-agejournal.retention.max-ageP30DMaximum file age
-journal-retention-min-keepjournal.retention.min-keepPT24HMinimum kept data
-journal-retention-max-sizejournal.retention.max-size0Size hard cap
-journal-retention-soft-pctjournal.retention.soft-pct80Soft threshold %
-journal-retention-overflow-policyjournal.retention.overflow-policydelete-unarchivedOverflow behavior
-journal-archive-commandjournal.archive.command(empty)Archive script path
-journal-archive-triggerjournal.archive.triggeron-rotateArchive trigger
-replication-targetreplication.target(empty)Cloud gRPC address
-replication-instance-idreplication.instance-id(empty)Instance ID
-replication-tls-certreplication.tls.cert(empty)Client TLS cert
-replication-tls-keyreplication.tls.key(empty)Client TLS key
-replication-tls-careplication.tls.ca(empty)CA cert

lplex-cloud​

Full annotated config​

# --- ACME mode (recommended for public internet) ---
# Single port with automatic Let's Encrypt certificates
listen = ":443"
acme {
  domain = "lplex.dockwise.app"
  email = "admin@example.com"
}
tls {
  # CA cert for verifying client mTLS certificates
  client-ca = "/etc/lplex-cloud/ca.crt"
}

# --- OR: Dual-port mode (for private networks) ---
grpc {
  listen = ":9443"
  tls {
    cert = "/etc/lplex-cloud/server.crt"
    key = "/etc/lplex-cloud/server.key"
    client-ca = "/etc/lplex-cloud/ca.crt"
  }
}
http {
  listen = ":8080"
}

# Instance state and journal storage
data-dir = "/data/lplex"

# Same retention/archive config as lplex
journal {
  retention {
    max-age = P90D
    max-size = 107374182400
    soft-pct = 80
    overflow-policy = delete-unarchived
  }
  archive {
    command = /usr/local/bin/archive-to-s3
    trigger = on-rotate
  }
}

Cloud CLI flag reference​

FlagHOCON PathDefaultDescription
-listenlisten:443ACME mode listen address
-acme-domainacme.domain(empty)Let's Encrypt domain
-acme-emailacme.email(empty)ACME account email
-grpc-listengrpc.listen:9443gRPC listen (dual-port mode)
-http-listenhttp.listen:8080HTTP listen (dual-port mode)
-tls-certgrpc.tls.cert(empty)Server TLS cert
-tls-keygrpc.tls.key(empty)Server TLS key
-tls-client-cagrpc.tls.client-ca / tls.client-ca(empty)Client CA cert
-data-dirdata-dir/data/lplexData directory

Retention and archive flags are the same as lplex (see table above).

Systemd​

The .deb package installs a systemd unit at /lib/systemd/system/lplex.service. You can override settings via environment variables in /etc/default/lplex:

# /etc/default/lplex
LPLEX_ARGS="-interface can0 -port 8089"

Or use the config file at /etc/lplex/lplex.conf (preferred).

# Check service status
sudo systemctl status lplex

# View logs
sudo journalctl -u lplex -f

# Restart after config changes
sudo systemctl restart lplex

Duration format​

All duration values use ISO 8601 duration format:

ExampleMeaning
PT30S30 seconds
PT5M5 minutes
PT1H1 hour
PT24H24 hours
P1D1 day
P30D30 days
P90D90 days