vast.yaml.example

# This is an example configuration file for VAST that shows all available
# options. Options in angle brackets have their default value determined at
# runtime.

# Options that concern VAST.
vast:

  # The host and port to listen at and connect to.
  endpoint: "localhost:42000"

  # The timeout for connecting to a VAST server. Set to 0 seconds to wait
  # indefinitely.
  connection-timeout: 10s

  # The file system path used for persistent state.
  db-directory: "vast.db"

  # The file system path used for log files.
  log-file: "<db-directory>/server.log"

  # The file system path used for client log files relative to the current
  # working directory of the client. Note that this is disabled by default.
  # If not specified no log files are written for clients at all.
  client-log-file: "client.log"

  # Format for printing individual log entries to the log-file.
  # For a list of valid format specifiers, see spdlog format specification
  # at https://github.com/gabime/spdlog/wiki/3.-Custom-formatting.
  file-format: "[%Y-%m-%dT%T.%e%z] [%n] [%l] [%s:%#] %v"

  # Configures the minimum severity of messages written to the log file.
  # Possible values: quiet, error, warning, info, verbose, debug, trace.
  # File logging is only available for commands that start a node (e.g., vast
  # start). The levels above 'verbose' are usually not available in release
  # builds.
  file-verbosity: debug

  # Whether to enable automatic log rotation. If set to false, a new log file
  # will be created when the size of the current log file exceeds 10 MiB.
  disable-log-rotation: false

  # The size limit when a log file should be rotated.
  log-rotation-threshold: 10MiB

  # Maximum number of log messages in the logger queue.
  log-queue-size: 1000000

  # The sink type to use for console logging. Possible values: stderr,
  # syslog, journald. Note that 'journald' can only be selected on linux
  # systems, and only if VAST was built with journald support.
  # The journald sink is used as default if VAST is started as a systemd
  # service and the service is configured to use the journal for stderr,
  # otherwise the default is the unstructured stderr sink.
  #console-sink: stderr/journald

  # Mode for console log output generation. Automatic renders color only when
  # writing to a tty.
  # Possible values: always, automatic, never. (default automatic)
  console: automatic

  # Format for printing individual log entries to the console. For a list
  # of valid format specifiers, see spdlog format specification at
  # https://github.com/gabime/spdlog/wiki/3.-Custom-formatting.
  console-format: "%^[%T.%e] %v%$"

  # Configures the minimum severity of messages written to the console.
  # For a list of valid log levels, see file-verbosity.
  console-verbosity: info

  # List of directories to look for schema files in ascending order of
  # priority.
  schema-dirs: []

  # Additional directories to load plugins specified using `vast.plugins`
  # from.
  plugin-dirs: []

  # The plugins to load at startup. For relative paths, VAST tries to find
  # the files in the specified `vast.plugin-dirs`. The special values
  # 'bundled' and 'all' enable autoloading of bundled and all plugins
  # respectively. Note: Add `example` or `/path/to/libvast-plugin-example.so`
  # to load the example plugin.
  plugins: []

  # The unique ID of this node.
  node-id: "node"

  # Spawn a node instead of connecting to one.
  node: false

  # The size of an index shard, expressed in number of events. This should
  # be a power of 2.
  max-partition-size: 4194304

  # Timeout after which an active partition is forcibly flushed, regardless of
  # its size.
  active-partition-timeout: 5 min

  # Automatically rebuild undersized and outdated partitions in the background.
  # The given number controls how much resources to spend on it. Set to 0 to
  # disable.
  automatic-rebuild: 1

  # The number of index shards that can be cached in memory.
  max-resident-partitions: 10

  # The number of index shards that are considered for the first evaluation
  # round of a query.
  max-taste-partitions: 5

  # The amount of queries that can be executed in parallel.
  max-queries: 10

  # Opt-in to the legacy query scheduling algorithm. This is offered as a safety
  # mechanism for users that have trouble with the new scheduler. The option
  # will be removed before the release of VAST v2.1.0
  use-legacy-query-scheduler: false

  # The directory to use for the partition synopses of the catalog.
  #catalog-dir: <dbdir>/index

  # The store backend to use. Can be 'segment-store', or the name of a
  # user-provided store plugin.
  store-backend: segment-store

  # Interval between two aging cycles.
  aging-frequency: 24h

  # Query for aging out obsolete data.
  aging-query:

  # Keep track of performance metrics.
  enable-metrics: false

  # The configuration of the metrics reporting component.
  metrics:
    # Configures if and how metrics should be ingested back into VAST.
    self-sink:
      enable: true
      slice-size: 128
    # Configures if and where metrics should be written to a file.
    file-sink:
      enable: false
      real-time: false
      path: /tmp/vast-metrics.log
    # Configures if and where metrics should be written to a socket.
    uds-sink:
      enable: false
      real-time: false
      path: /tmp/vast-metrics.sock
      type: datagram

  # The period to wait until a shutdown sequence finishes cleanly. After the
  # period elapses, the shutdown procedure escalates into a "hard kill". A
  # value of "0x", where "x" is any duration unit, means an infinite grace
  # period without escalation into a hard kill.
  shutdown-grace-period: 3m

  # The `index` key is used to adjust the false-positive rate of
  # the first-level lookup data structures (called synopses) in the
  # catalog. The lower the false-positive rate the more space will be
  # required, so this setting can be used to manually tune the trade-off
  # of performance vs. space.
  index:
    # The default false-positive rate for type synopses.
    default-fp-rate: 0.01
    # rules:
    #   Every rule adjusts the behaviour of VAST for a set of targets.
    #   VAST creates one synopsis per target. Targets can be either types
    #   or field names.
    #
    #   fp-rate - false positive rate. Has effect on string and address type
    #             targets
    #
    #   create-dense-index - VAST will not create dense index when set to false
    #   - targets: [:string, :address]
    #     fp-rate: 0.01
    #     create-dense-index: false

  # The `vast start` command starts a new VAST server process.
  start:

    # Prints the endpoint for clients when the server is ready to accept
    # connections. This comes in handy when letting the OS choose an
    # available random port, i.e., when specifying 0 as port value.
    print-endpoint: false

    # An ordered list of commands to run inside the node after starting.
    # As an example, to configure an auto-starting PCAP source that listens
    # on the interface 'en0' and lives inside the VAST node, add `spawn
    # source pcap -i en0`.
    commands: []

    # Triggers removal of old data when the disk budget is exceeded.
    disk-budget-high: 0GiB

    # When the budget was exceeded, data is erased until the disk space is
    # below this value.
    disk-budget-low: 0GiB

    # Seconds between successive disk space checks.
    disk-budget-check-interval: 90

    # When erasing, how many partitions to erase in one go before rechecking
    # the size of the database directory.
    disk-budget-step-size: 1

    # Binary to use for checking the size of the database directory. If left
    # unset, VAST will recursively add up the size of all files in the
    # database directory to compute the size. Mainly useful for e.g.
    # compressed filesystem where raw file size is not the correct metric.
    # Must be the absolute path to an executable file, which will get passed
    # the database directory as its first and only argument.
    #disk-budget-check-binary:


  # The `vast count` command counts hits for a query without exporting data.
  count:

    # Estimate an upper bound by skipping candidate checks.
    estimate: false

  # The `vast dump` command prints configuration objects as JSON.
  dump:
    # Format output as YAML.
    yaml: false

  # The `vast export` command exports query results to stdout or a file.
  export:
    # Mark a query as continuous.
    continuous: false

    # Mark a query as unified.
    unified: false

    # Mark a query as low priority.
    low-priority: false

    # Dont substitute taxonomy identifiers.
    disable-taxonomies: false

    # Timeout to stop the export after.
    #timeout: <infinite>

    # The maximum number of events to export.
    #max-events: <infinity>

    # Path for reading the query or "-" for reading from stdin.
    # Note: Setting this option in the config file creates a conflict with
    # `vast export` with a positional query argument. This option is only
    # listed here for completeness.
    #read: '-'

    # Path to write events to or "-" for writing to stdout.
    write: '-'

    # Treat the write option as a UNIX domain socket to connect to.
    uds: false

    # The `vast export json` command exports events formatted as JSONL (line-
    # delimited JSON).
    json:

      # Flatten nested objects into the top-level object.
      flatten: false

      # Render durations as numbers as opposed to human-readable strings.
      numeric-durations: false

      # Omit null fields in JSON objects.
      omit-nulls: false

    # The `vast export pcap` command exports events in the PCAP format.
    pcap:
      # Flush to disk after this many packets.
      flush-interval: 10000

  # The `vast infer` command tries to infer the schema from data.
  infer:

    # Path to read events from or "-" for reading from stdin.
    read: '-'

    # Maximum number of bytes to buffer.
    buffer: 8192

  # The `vast explore` command explore context around query results.
  explore:

    # The output format.
    format: json

    # Include all records up to this much time after each result.
    after:

    # Include all records up to this much time before each result.
    before:

    # Perform an equijoin on the given field.
    by:

    # Maximum number of results.
    #max-events: <infinity>

    # Maximum number of results for initial query.
    max-events-query: 100

    # Maximum number of results per exploration.
    max-events-context: 100

  # The `vast import` command imports data from stdin, files or over the
  # network.
  import:

    # The maximum number of events to import.
    #max-events: <infinity>

    # Timeout after which buffered table slices are forwarded to the node.
    batch-timeout: 10s

    # Upper bound for the size of a table slice. A value of 0 causes the
    # batch-size to be unbounded, leaving control of batching to the
    # vast.import.read-timeout option only. This should be a power of 2.
    batch-size: 65536

    # Block until the importer forwarded all data.
    blocking: false

    # The amount of time that each read iteration waits for new input.
    read-timeout: 20ms

    # The endpoint to listen on ("[host]:port/type").
    #listen: <none>

    # Path to file to read events from or "-" for stdin.
    read: '-'

    # Treat the read option as a UNIX domain socket to connect to.
    uds: false

    # Path to an alternate schema.
    #schema-file: <none>

    # An alternate schema as a string.
    #schema: <none>

    # The `vast import csv` command imports comma-separated values.
    csv:
      # The single-character separator. Set this to ' ' to parse space-separated
      # values, or '\t' to parse tab-separated values.
      separator: ','

    # The `vast import json` command imports JSONL data.
    json:
      # Read the event type from the given field (specify as
      # '<field>[:<prefix>]').
      #selector= <none>

    # The `vast import pcap` command imports PCAP logs.
    pcap:
      # Network interface to read packets from.
      #interface: <none>

      # Skip flow packets after this many bytes.
      #cutoff: <infinity>

      # Number of concurrent flows to track.
      max-flows: 1048576

      # Maximum flow lifetime before eviction.
      max-flow-age: 60

      # Flow table expiration interval.
      flow-expiry: 10

      # Inverse factor by which to delay packets. For example, if 5, then for
      # two packets spaced *t* seconds apart, the source will sleep for *t/5*
      # seconds.
      pseudo-realtime-factor: 0

      # Snapshot length in bytes.
      snaplen: 65535

      # Disable computation of community id for every packet.
      disable-community-id: false

    # The `vast import test` command imports randomly generated events. Used for
    # debugging and benchmarking only.
    test:
      # The PRNG seed.
      seed: 0

    # The `vast import zeek` command imports Zeek logs.
    zeek:
      # Flag to indicate whether the output should contain #open/#close tags.
      # Zeek writes these tags in its logs such that users can gain insight
      # when Zeek processed the corresponding data. By default, VAST
      # does the same. Settings this flag to true skips printing these tags,
      # which may help when fully deterministic output is desired.
      disable-timestamp-tags: false

  # The `vast pivot` command extracts related events of a given type.
  # For additionally available options, see export.pcap.
  pivot:

    # The output format.
    format: json

  # The `vast status` command prints a JSON-formatted status summary of the
  # node.
  status:

    # Add more information to the output
    detailed: false

    # Include extra debug information
    debug: false

# The below settings are internal to CAF, and are not checked by VAST directly.
# Please be careful when changing these options. Note that some CAF options may
# be in conflict with VAST options, and are only listed here for completeness.
caf:

  # Options affecting the internal scheduler.
  scheduler:

    # Accepted alternative: "sharing".
    policy: stealing

    # Configures whether the scheduler generates profiling output.
    enable-profiling: false

    # Output file for profiler data (only if profiling is enabled).
    #profiling-output-file: </dev/null>

    # Measurement resolution in milliseconds (only if profiling is enabled).
    profiling-resolution: 100ms

    # Forces a fixed number of threads if set. Defaults to the number of
    # available CPU cores if starting a VAST node, or *2* for client commands.
    #max-threads: <number of cores>

    # Maximum number of messages actors can consume in one run.
    max-throughput: 500

  # When using "stealing" as scheduler policy.
  work-stealing:

    # Number of zero-sleep-interval polling attempts.
    aggressive-poll-attempts: 100

    # Frequency of steal attempts during aggressive polling.
    aggressive-steal-interval: 10

    # Number of moderately aggressive polling attempts.
    moderate-poll-attempts: 500

    # Frequency of steal attempts during moderate polling.
    moderate-steal-interval: 5

    # Sleep interval between poll attempts.
    moderate-sleep-duration: 50us

    # Frequency of steal attempts during relaxed polling.
    relaxed-steal-interval: 1

    # Sleep interval between poll attempts.
    relaxed-sleep-duration: 10ms

  stream:
    # Processing time per batch.
    desired-batch-complexity: 50us

    # Maximum delay for partial batches.
    max-batch-delay: 15ms

    # Time between emitting credit.
    credit-round-interval: 10ms