agent.sample.yml

---
host:
  # If using the docker container in an older environment, set to: iptables-legacy
  # All others, including non-docker installations, should use iptables.
  iptables-cmd: iptables
computestacks:
  host: http://localhost:3000
store:
  # Embedded SQLite data plane: control.db (node tenant/auth map) plus one
  # metadata DB per project live under this directory.
  data_dir: /var/lib/cs-agent
metadata:
  # Customer-metadata HTTP front door. The port MUST stay 8500 — it
  # is baked into customer containers via metadata.internal:8500. The provisioner
  # sets this to the node's primary_ip:8500.
  listen_addr: ":8500"
  # Hex sha256 of the per-node admin Bearer the controller authenticates with.
  # Empty disables the admin scope entirely (no admin route can authenticate).
  admin_token_hash: ""
  # Cap on a single request body (413 on exceed). The STORED value is uncapped —
  # this is only a transport limit (killing Consul's 512 KB ceiling is the point).
  max_body_bytes: 10485760 # 10 MiB
  # Dual-run proxy-to-Consul leg for un-migrated projects. DEFAULT FALSE and
  # not yet wired: leave it off until the Bearer→X-Consul-Token wire-auth is
  # resolved. With it off, an unknown tenant is 401 and an unknown path 404.
  proxy_to_consul: false
consul:
  host: 127.0.0.1:8500
  token: "" # Consul Auth Token
  ##
  # TLS Configuration
  #
  # If true, it will look for certificates here: /etc/computestacks/certs/consul
  #  * ca.crt
  #  * client.crt
  #  * client.key
  #
  tls: true
backups:
  enabled: true

  ##
  # How often to check for new volumes
  #    * * * * * *
  #    | | | | | |
  #    | | | | | +-- Year              (range: 1900-3000) (optional field)
  #    | | | | +---- Day of the Week   (range: 0-6, 0 standing for Sunday)
  #    | | | +------ Month of the Year (range: 1-12, 1 standing for Jan)
  #    | | +-------- Day of the Month  (range: 1-31)
  #    | +---------- Hour              (range: 0-23)
  #    +------------ Minute            (range: 0-59)
  #
  # (optionally) Supports built-in helpers:
  #  - @every <duration> see: https://golang.org/pkg/time/#ParseDuration
  #  - @hourly
  #  - @daily (or @midnight)
  #  - @weekly
  #  - @monthly
  #  - @yearly (or @annually)
  #
  check_freq: "*/2 * * * *" # Every 2-minutes
  prune_freq: "15 1 * * *" # Every day at 01:15

  # Borg compaction (reclaim freed space) now runs in-agent instead of as a host
  # cron on the backup server. Set to "" to disable scheduling it. Offset after
  # prune so prune (mark) runs before compact (reclaim).
  compact_freq: "45 2 * * *" # Every day at 02:45
  compact_jitter_sec: 1800 # Random 0-N sec delay before a compact sweep, to spread load across nodes

  key: changeme! # This is the encryption key
  mariadb:
    long_queries: # Kill long queries to unblock backup
      timeout: 20 # in seconds. Set to 0 to disable
      query_type: SELECT # Possible values are: ALL, SELECT, UPDATE
    lock_wait:
      query_type: ALL # Possible values are: ALL, SELECT, UPDATE
      timeout: 60 # In seconds, how long to wait while attempting to grab global lock.
  borg:
    compress: "zstd,3"
    image: "ghcr.io/computestacks/cs-docker-borg:1.5"
    lock_wait: 1 # wait at most SECONDS for acquiring a repository/cache lock
    lock_wait_create: 600 # `borg create` waits this long, so a scheduled backup rides out an in-agent compact instead of failing

    ##
    # SSH
    ssh:
      enabled: false
      user: cstacks
      host: example.com
      port: 22

      # MUST be inside the path `/etc/computestacks` on the host.
      keyfile: "/etc/computestacks/.ssh/id_ed25519"

      # Must be absolute and start with a '/', and NOT have a trailing `/`.
      host_path: "/mnt/data/backups"

    ##
    # If storing backups on an NFS server
    # Note: This is not compatible with SSH.
    nfs: false # Set `true` to use nfs server to store backup volumes.
    nfs_host: 127.0.0.1
    nfs_host_path: "/var/nfsshare/backups"
    nfs_borg_path: "borg" # Path to the borg binary ON the NFS server (agent runs `borg compact` there over SSH). Use an absolute path if borg isn't on the non-interactive SSH PATH.
    nfs_opts: ",async,noatime,rsize=32768,wsize=32768" # Ensure you include the `,`! `rw,nfsvers=4` is already included
    nfs_create_path: true # Create paths on backup server prior to mounting volume.

    # Required in order to create the data directly on the NFS Server,
    # and to clean up the data after the parent volume is destroyed.
    nfs_ssh:
      user: "root" # SSH key used to connect to NFS server
      port: "22"
      keyfile: "/root/.ssh/id_ed25519" # SSH key used to connect to NFS server
      # Must match your NFS server's squash mapping (Debian: nobody/nogroup;
      # RHEL: nfsnobody/nfsnobody). The SAME values are used for both volume
      # creation and compaction — a mismatch leaves borg files unreadable on the
      # next backup.
      fs_user: "nobody"
      fs_group: "nogroup"

  # Backup export ("download backup"): stream a chosen archive to S3 and return a
  # presigned URL. Inert until s3.bucket is set. NOTE: the exported tar is
  # PLAINTEXT (unlike the encrypted repo) — keep the bucket private, enable SSE,
  # and set a short presigned-URL TTL plus an object-expiry lifecycle rule
  # (and AbortIncompleteMultipartUpload) on the bucket.
  export:
    workers: 1 # dedicated export workers; each big export uses ~part_size*concurrency RAM
    tar_filter: "gzip" # borg --tar-filter for the exported tar; "" disables. export-tar emits the ORIGINAL (decompressed) files, so the repo's own compression does NOT carry over — without a filter the upload is full plaintext size. The object suffix tracks this (gzip -> .tar.gz).
    timeout_sec: 14400 # hard cap on a single export (seconds); a hung borg/S3 fails instead of holding the repo lock
    cleanup_freq: "*/30 * * * *" # how often to reap stale download records from Consul (the S3 lifecycle deletes the object; this removes the now-dead KV record so the UI reverts to "request download"); "" disables
    failed_retention_sec: 86400 # keep a failed export's record this long before reaping (24h)
    s3:
      endpoint: "" # empty = AWS; set an https URL for S3-compatible (MinIO/Ceph)
      region: "us-east-1"
      bucket: "" # REQUIRED to enable export
      prefix: "exports/"
      access_key: ""
      secret_key: ""
      force_path_style: false # true for MinIO / path-style endpoints
      part_size_mb: 64 # must satisfy: part_size_mb >= ceil(max_archive_GB * 1024 / 10000)
      concurrency: 4
      sse: "AES256" # server-side encryption (the exported tar is unencrypted)
      default_ttl_sec: 43200 # presigned URL lifetime when the request doesn't specify (12h)
      max_ttl_sec: 86400 # hard cap on a requested TTL (24h)
docker:
  version: "1.41"
queue:
  numworkers: 3 # Number of concurrent backup jobs to run
sentry:
  dsn: "" # Full sentry DSN for bug reports.