Agent Configuration File

While the Agent can be run using command line parameters, it can also be fully configured with a configuration file.

While there is no default location for the configuration, /etc/evebox/agent.yaml is recommended.

The EveBox Agent must also be told where to find the configuration file, for example:

evebox agent -c /etc/evebox/agent.yaml

Command line arguments will always override the configuration file.

See Agent Environment Variables for the supported environment settings and configuration equivalents.

The example below includes the optional server.key, pcap, and filestore settings used to serve full packet captures and extracted files from the sensor. Extracted file serving requires EveBox 0.30.0 or newer; see Extracted Files for preview and download details. The key's name, set when it is created on the server, is the agent's identity; the agent-id option used before EveBox 0.29.0 is ignored.

Set elasticsearch.enabled to false when enabling pcap or filestore; both use a control channel connected to the EveBox Server and require an agent key created there. input.paths may be omitted for an agent that only serves captures, files, or both.

# EveBox Agent configuration file - subject to change.

# Server information.
server:
  url: http://127.0.0.1:5636

  # Agent key. Its server-side name identifies submitted events and the
  # packet-capture and file source; it is also required for their control
  # channel (see pcap and filestore below). Create one on the server with:
  #     evebox config agents add <name>
  # Also available as the EVEBOX_SERVER_KEY environment variable. Keep
  # this file's permissions restrictive when a key is set.
  #key: eba_...

# Enable output to Elasticsearch. If enabled, the above server section
# will not be used. Set enabled to false to serve packet captures or files.
elasticsearch:
  enabled: true
  url: http://127.0.0.1:9200
  index: logstash

  # Set to true if the index is a datastream.
  #nodate: false

  #username: username
  #password: password

# Directory to store data and state information required by the agent. This
# isn't always required. If the agent has write access to the log directory it
# can store bookmark information alongside the eve log files.
#data-directory: "/var/lib/evebox"

# If the EveBox server is running behind TLS and the certificate is
# self signed, certificate validation can be disabled.
#disable-certificate-check: true

# Path to Suricata Eve log files.
input:
  paths:
    - "/var/log/suricata/eve.json"
    - "/var/log/suricata/eve.*.json"

    # Timestamped spools such as eve.json.%s and eve.json.%n.%s. EveBox
    # automatically uses one processor for each optional thread index.
    #- "/var/log/suricata/eve.json.[0-9]*"

  # Delete timestamped spool files after their events are committed and the
  # bookmark advances to a newer file. Requires a writable bookmark.
  #delete-spool-files: false

  # Unix sockets that EveBox creates for Suricata EVE output. Set Suricata's
  # eve-log filetype and filename to the same type and path. Supported types
  # are unix_stream and unix_dgram. A plain path is shorthand for unix_stream.
  #sockets:
  #  - path: /run/evebox/eve.sock
  #    type: unix_stream
  #    # Optional octal permissions; ensure Suricata can connect after it
  #    # drops privileges. The socket remains owned by the EveBox user/group.
  #    mode: "0660"
  #  - path: /run/evebox/eve-dgram.sock
  #    type: unix_dgram

# Keep a persistent control connection to the EveBox server and serve packet
# capture requests from this host's Suricata pcap-log spool. Setting a
# directory enables packet capture. The control channel requires an agent
# key (server.key above) unless the server sets
# agents.allow-unauthenticated. This requires EveBox server output;
# it is ignored when direct Elasticsearch output above is enabled. On
# Windows, Npcap must be installed (EveBox 0.30.0 and newer).
#
# The --pcap-directory and --pcap-prefix command line options can be used
# instead.
#pcap:
#  directory: /var/log/suricata/pcap
#  # Matches the recommended threaded filename log.%n.%t.pcap.
#  prefix: log.

# Serve previews and downloads from a local Suricata file-store v2 directory
# (EveBox 0.30.0 and newer). Setting the directory enables file serving over
# the same control channel as packet capture; pcap need not be configured.
# Requires server output (elasticsearch.enabled: false) and normally an agent
# key (server.key above). Omit input.paths for a file-only agent.
# The --filestore-directory option can be used instead; there is no equivalent
# environment variable for the agent. File serving also works on Windows
# and does not need Npcap.
#filestore:
#  directory: /var/log/suricata/filestore

# Additional fields that will be added to each event. This is currently limited
# to strings.
additional-fields:
  #sensor-name: "my super secret sensor"

# The event reader can also add the rule to alert events. Do not enable
# if you already have Suricata logging the rule.
#rules:
#  - /var/lib/suricata/rules/*.rules
#  - /usr/share/suricata/rules/*.rules
#  - /etc/suricata/rules/*.rules