Skip to content

Configure an Orb Agent Using Configuration File

Orb Agent Configuration

As you can see here configuration files are needed if you want to customize your orb agent. Follow the lines below to understand how to use them and make Orb more versatile and powerful to your needs. The configuration file is written in YAML and can be used to make Orb agent to auto-provision or to configure an already connected Orb agent. 

orb:
  cloud:
    api:
      address: https://orb.live
      token: TOKEN
    config:
      agent_name: agent_name
      auto_provision: true
    mqtt:
      address: tls://agents.orb.live:8883
  backends:
    pktvisor:
      api_port: 10853
      binary: /usr/local/sbin/pktvisord
      config_file: "/path/pktvisor.yaml"
  tags:
    key_1: value_1
    key_2: value_2
  tls:
    verify: true
  db:
    file: "/orb-agent.db"
  debug:
    enable: true
visor:
  # this section is used by pktvisor. Check Pktvisor configuration to more information.

orb:
  cloud:
    api:
      address: https://orb.live
    config:
      auto_provision: false
    mqtt:
      address: tls://agents.orb.live:8883
      channel_id: "AGENT_KEY_UUID"
      id: "AGENT_UUID"
      key: "AGENT_KEY_UUID"
  backends:
    pktvisor:
      api_port: 10853
      binary: /usr/local/sbin/pktvisord
      config_file: "/path/pktvisor.yaml"
  tags:
    key_1: value_1
    key_2: value_2
  tls:
    verify: true
  db:
    file: "/orb-agent.db"
  debug:
    enable: true
visor:
 # this section is used by pktvisor. Check Pktvisor configuration to more information.

Cloud

Cloud section has three subsections: api, config and mqtt and it establishes all the necessary configurations for the agent connection.

Subsection Configurations Type Required Default Extra
api address str ❌ https://orb.live -
api token str It's required if you want the agent to auto provision None Check here to how to create a token
config agent_name str ❌ hostname It will only be used if auto_provision: True
config auto_provision Bool ❌ True -
mqtt address str ❌ tls://agents.orb.live:8883 -
mqtt id UUID It's required if you DON'T want the agent to auto provision None Check here to understand how to get an agent id
mqtt channel_id UUID It's required if you DON'T want the agent to auto provision None Check here to understand how to get an agent id
mqtt key UUID It's required if you DON'T want the agent to auto provision None Check here to understand how to get an agent id

Backends

It is worth emphasizing that no extra installation is necessary, since the orb-agent docker container already includes the available backends. The subsections here are related to each backend supported by Orb agents. See below for configuration options:

Pktvisor:

Check pktvisor configurations for more information on available options to this backend.

Subsection Configurations Type Required Default
Meaning
pktvisor binary str ❌ /usr/local/sbin/pktvisord It specifies the path on orb container where the pktvisor binary is located
pktvisor config_file str ❌ /opt/orb/agent.yaml It specifies the path in orb container where the pktvisor configuration file is located and assumes that you are using the same agent file, named agent.yaml, to configure both the agent itself and pktvisor. If your pktvisor configuration file has another name/path, you must replace it with the proper one.
pktvisor api_host str ❌ localhost Host where pktvisor web server will run.
pktvisor api_port int ❌ 10853 Port in which pktvisor web server will run.

Tags

  • Tags are intended to dynamically define a group of agents by matching against agent group tags and are a dict type.

  • Warning

    Agent tags defined on the edge (configuration files) CAN NOT be removed/edited through API or orb-website and they are not required.

TLS verification

It verifies the identity of the server and must be set to False if you want to use self-hosted versions.

  • Not Required

  • Default: True

  • Type: Bool

Debug

If True, this will cause more agent logs (debug type) to be provided.

  • Not Required

  • Default: False

  • Type: Bool

Pktvisor Configuration

For configure pktvisor you could specify taps. It's defined under visor top level key (check an example).
The tap section specifies what data the agent should be listening in on and the goal of Taps is to abstract away host level details such as ethernet interface or dnstap socket location so that collection policies can apply to a broad set of pktvisor agents without worrying about these details. See here for more information.
Single or multiple taps can be configured in the same agent.

visor:
  taps:
    first_tap_name:
      input_type: type
      config: ...
      filter: ...
      tags:
        key1: value1
        key2: value2
    second_tap_name:
      input_type: type
      config: ...
      filter: ...
      tags:
        key1: value1
        key3: value3

The following inputs are supported: pcap, flow, dnstap and netprobe. For each input type, specific configuration, filters and tags can be defined.

Packet Capture (pcap)

Example: Pktvisor PCAP Tap Configuration

visor:
  taps:
    my_pcap_tap:
      input_type: pcap
      config:
        pcap_source: "libpcap"
        debug: true
        iface: auto
        host_spec: "192.168.0.1/24"
      filter:
        bpf: "port 53"
      tags:
        pcap: true


Configurations

There are 5 configurations for pcap input: pcap_file, pcap_source, iface, host_spec and debug.

Config Type
pcap_file str
pcap_source str
iface str
host_spec str
debug bool
tcp_packet_reassembly_cache_limit int

pcap_file: str
Back to pcap configurations list

One option of using pktvisor is for reading existing network data files. In this case, the path to the file must be passed. This variable is dominant, so if a file is passed, pktvisor will do the entire process based on the file. 

pcap_file: "path/to/file"


pcap_source: str
Back to pcap configurations list

pcap_source specifies the type of library to use. Default: libpcap. Options: libpcap or af_packet (linux).

pcap_source: "af_packet"


iface: str
Back to pcap configurations list

Name of the interface to bind.

iface: str
Example: 
iface: eth0

Tip

You can use auto as iface. In this way, the network with the highest data flow will be analyzed.

iface: auto

host_spec: str
Back to pcap configurations list The host_spec setting is useful to determine the direction of observed packets, once knowing the host ip, it is possible to determine the data flow direction, ie if they are being sent by the observed host (from host) or received (to host). 

host_spec: str
Example: 
host_spec: "192.168.0.1/24"


debug: bool
Back to pcap configurations list

When true activate debug logs

debug: true

tcp_packet_reassembly_cache_limit: int
Back to pcap configurations list

Sets the limit of cached packets to be reassembled. Default value: 300000.
To remove limit set tcp_packet_reassembly_cache_limit to 0.

tcp_packet_reassembly_cache_limit: 300000

Filters

Filter Type
bpf str

bpf: str
Back to pcap filters list

bpf filter data based on Berkeley Packet Filters (BPF).

bpf: str
Example: 
bpf: "port 53"

sFlow/Netflow (flow)

Example: Pktvisor FLOW Tap Configuration

visor:
  taps:
    my_flow_tap:
      input_type: flow
      config:
        port: 6343
        bind: 192.168.1.1
        flow_type: sflow
      tags:
        flow: true


Configurations

There are 3 configs for flow inputs: port, bind and flow_type.

Config Type
port int
bind str
flow_type str

port: int and bind: str
Back to sFlow/Netflow filters list

The other option for using flow is specifying a port AND an ip to bind (only udp bind is supported). Note that, in this case, both variables must be set.

port: int
bind: str
Example: 
port: 6343
bind: 192.168.1.1


flow_type: str
Back to sFlow/Netflow filters list

Default: sflow. options: sflow or netflow (ipfix is supported on netflow). 

flow_type: str
Example: 
flow_type: netflow

Filters

There are no specific filters for the FLOW input.

dnstap

Example: Pktvisor DNSTAP Tap Configuration

visor:
  taps:
    my_dnstap_tap:
      input_type: dnstap
      config:
        socket: path/to/file.sock
        tcp: 192.168.8.2:235
      filter:
        only_hosts: 192.168.1.4/32
      tags:
        dnstap: true


Configurations

The 3 existing DNSTAP configurations (dnstap_file, socket and tcp) are mutually exclusive, that is, only one can be used in each input and one of them must exist. They are arranged in order of priority.

Config Type
dnstap_file str
socket int
tcp str

dnstap_file: str
Back to dnstap configurations list

One option of using pktvisor is for reading existing network data files. In this case, the path to the file must be passed. This variable is dominant, so if a file is passed, pktvisor will do the entire process based on the file. 

dnstap_file: path/to/file


socket: str
Back to dnstap configurations list

Path to socket file containing port and ip to bind

socket: path/to/file.sock


tcp: str
Back to dnstap configurations list

The other way to inform the ip and port to be monitored is through the 'tcp' configuration. Usage syntax is a string with port:ip (only ipv4 is supported for now). 

tcp: ip:port
Example: 
tcp: 192.168.8.2:235


Filters

Filter Type
only_hosts str

only_hosts: str
Back to dnstap filters list

only_hosts filters data from a specific host.

only_hosts: str
Example: 
only_hosts: 192.168.1.4/32

Netprobe

Example: Pktvisor Netprobe Tap Configuration

visor:
  taps:
    default_netprobe:
      input_type: netprobe
      config:
        test_type: ping
        interval_msec: 2000
        timeout_msec: 1000
        packets_per_test: 10
        packets_interval_msec: 25
        packet_payload_size: 56
      tags:
        netprobe: true


Configurations

The following configs are available for netprobe inputs:

Config Type Required Default
test_type str ✅ -
interval_msec int ❌ 5000
timeout_msec int ❌ 2000
packets_per_test int ❌ 1
packets_interval_msec int ❌ 25
packet_payload_size int ❌ 48
port int Required if test_type=tcp -

test_type: str
Back to netprobe configurations list

Defines the type of the test to be performed. Type options are listed below:

  • ping: implements a ping prober that can probe multiple targets. The test will run against the targets to verify if the systems are working fine.
  • tcp: TCP probe sets up a TCP connection to the configured targets using the defined port.

test_type: str
Example: 
test_type: ping


interval_msec: int
Back to netprobe configurations list

How often to run the probe (in milliseconds). 

interval_msec: int
Example: 
interval_msec: 5000


timeout_msec: int
Back to netprobe configurations list

Probe timeout (in milliseconds). 

timeout_msec: int
Example: 
timeout_msec: 2000


packets_per_test: int
Back to netprobe configurations list

Number of packets to be sent in each test.

packets_per_test: int
Example: 
packets_per_test: 1


packets_interval_msec: int
Back to netprobe configurations list

Time interval between packets per test (in milliseconds).

packets_interval_msec: int
Example: 
packets_interval_msec: 25


packet_payload_size: int
Back to netprobe configurations list

Defines the payload of the packets sent in the tests.

packet_payload_size: int
Example: 
packet_payload_size: 48


port: int
Back to netprobe configurations list

Specifies the port on which the TCP test will run (It is only used if the test_type is TCP. Otherwise, is ignored if set).

port: int
Example: 
port: 80

Filters

There are no specific filters for Netprobe input.