Skip to content

Running Orb Agent

An Orb agent needs to run on all the infrastructure (computers, servers, switches, VMs, k8s, etc.) to be monitored. It is a small, lightweight Docker process with an embedded pktvisor agent which connects into the Orb control plane to receive policies and send its metric output.

To run an agent, you will need:

  1. Docker, to run the agent image (ns1labs/orb-agent:develop)
  2. Agent Credentials, which are provided to you by the Orb UI or REST API after creating an agent
  3. The Orb Control Plane host address (e.g. localhost or orb.live)
  4. The network interface to monitor (e.g. eth0)

Tip

If you are unsure which network interface to monitor, you may list the available interfaces on your host. Note that to allow the agent access to these interfaces, you must run the container with --net=host

ip -stats -color -human addr
ifconfig

Agent credentials

The agent credentials include three pieces of information, each of which is a UUID in the form 5dc34ded-6a53-44c0-8d15-7e9c8c95391a.

  1. Agent ID, which uniquely identifies the agent.
  2. Agent Channel ID, which uniquely identifies the agent's communication channel.
  3. Agent Key, which is a private access token for the agent. Note you will only be shown the key once upon creation!

Sample provisioning commands

Example

Use this command as a template by substituting in the appropriate values:

docker run -d --net=host
-e ORB_CLOUD_ADDRESS=<HOST>
-e ORB_CLOUD_MQTT_ID=<AGENTID>
-e ORB_CLOUD_MQTT_CHANNEL_ID=<CHANNELID>
-e ORB_CLOUD_MQTT_KEY=<AGENTKEY>
-e PKTVISOR_PCAP_IFACE_DEFAULT=mock
ns1labs/orb-agent:develop

This command is useful for connecting to a local develop environment, perhaps running on Docker compose. Note that the "mock" interface will generate random traffic rather than observe real traffic.

docker run -d --net=host
-e ORB_CLOUD_ADDRESS=localhost
-e ORB_CLOUD_MQTT_ID=7fb96f61-5de1-4f56-99d6-4eb8b43f8bad
-e ORB_CLOUD_MQTT_CHANNEL_ID=3e60e85d-4414-44d9-b564-0c1874898a4d
-e ORB_CLOUD_MQTT_KEY=44e42d90-aaef-45de-9bc2-2b2581eb30b3
-e PKTVISOR_PCAP_IFACE_DEFAULT=mock
-e ORB_TLS_VERIFY=false
ns1labs/orb-agent:develop

This command is similar to one you would use on the orb.live SaaS platform

docker run -d --net=host
-e ORB_CLOUD_ADDRESS=orb.live
-e ORB_CLOUD_MQTT_ID=7fb96f61-5de1-4f56-99d6-4eb8b43f8bad
-e ORB_CLOUD_MQTT_CHANNEL_ID=3e60e85d-4414-44d9-b564-0c1874898a4d
-e ORB_CLOUD_MQTT_KEY=44e42d90-aaef-45de-9bc2-2b2581eb30b3
-e PKTVISOR_PCAP_IFACE_DEFAULT=eth0
ns1labs/orb-agent:develop
docker run -d --net=host
-e ORB_CLOUD_ADDRESS=orb.live
-e ORB_CLOUD_MQTT_ID=7fb96f61-5de1-4f56-99d6-4eb8b43f8bad
-e ORB_CLOUD_MQTT_CHANNEL_ID=3e60e85d-4414-44d9-b564-0c1874898a4d
-e ORB_CLOUD_MQTT_KEY=44e42d90-aaef-45de-9bc2-2b2581eb30b3
-e PKTVISOR_PCAP_IFACE_DEFAULT=eth0
-e ORB_BACKENDS_PKTVISOR_API_PORT=10854
ns1labs/orb-agent:develop
docker run -d --net=host
-e ORB_CLOUD_ADDRESS=orb.live
-e ORB_CLOUD_MQTT_ID=7fb96f61-5de1-4f56-99d6-4eb8b43f8bad
-e ORB_CLOUD_MQTT_CHANNEL_ID=3e60e85d-4414-44d9-b564-0c1874898a4d
-e ORB_CLOUD_MQTT_KEY=44e42d90-aaef-45de-9bc2-2b2581eb30b3
-e PKTVISOR_PCAP_IFACE_DEFAULT=eth0
ns1labs/orb-agent:develop run -d

Question

Is the agent Docker image not starting correctly? Do you have a specific use case? Have you found a bug? Come talk to us live on Slack, or file a GitHub issue here.

Configuration files

Most configuration options can be passed to the container as environment variables, but there are some situations that require a configuration file.

You will need to use a configuration file if:

  • You want to assign tags to the agent at the edge
  • You want to setup custom pktvisor Taps
  • You want the agent to auto-provision

The configuration file is written in YAML. You can use the latest template configuration file as a starting point, or start here:

version: "1.0"

# this section is used by pktvisor
# see https://github.com/ns1labs/pktvisor/blob/develop/RFCs/2021-04-16-75-taps.md
visor:
   taps:
      default_pcap:
         input_type: pcap
         config:
            iface: "eth0"
            host_spec: "192.168.0.54/32,192.168.0.55/32,127.0.0.1/32"

# this section is used orb-agent
# most sections and keys are optional
orb:
   # these are arbitrary key value pairs used for organization in the control plane and UI
   tags:
      region: EU
      pop: ams02
      node_type: dns
   cloud:
      config:
         # optionally specify an agent name to use during auto provisioning
         # hostname will be used if it's not specified here
         agent_name: my-agent1
         auto_provision: true
      api:
         address: https://orb.live
         # if auto provisioning, specify API token here (or pass on the command line)
         token: TOKEN
      mqtt:
         address: tls://orb.live:8883
         # if not auto provisioning, specify agent connection details here
         id: "AGENT_UUID"
         key: "AGENT_KEY_UUID"
         channel_id: "AGENT_CHANNEL_UUID"
   backends:
      pktvisor:
      binary: "/usr/local/sbin/pktvisord"
      # this example assumes the file is saved as agent.yaml. If your file has another name, you must replace it with the proper name
      config_file: "/usr/local/orb/etc/agent.yaml"

You must mount your configuration file into the orb-agent container. For example, if your configuration file is on the host at /local/orb/agent.yaml, you can mount it into the container with this command:

docker run -v /local/orb:/usr/local/orb/ --net=host \
      ns1labs/orb-agent:develop run -c /usr/local/orb/agent.yaml

Advanced auto-provisioning setup

Some use cases require a way to provision agents directly on edge infrastructure without creating an agent manually in the UI or REST API ahead of time. To do so, you will need to create an API key which can be used by orb-agent to provision itself.

Warning

Auto-provisioning is an advanced use case. Most users will find creating an agent in the UI easier.

  1. If you have not already done so, register a new account with an email address and password at https://HOST/auth/register.

  2. Create a SESSION_TOKEN with the EMAIL_ADDRESS and PASSWORD from registration:

    curl --location --request POST 'https://HOST/api/v1/tokens' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "email": "<EMAIL_ADDRESS>",
    "password": "<PASSWORD>"
    }'
    
  3. The output from creating a session token looks like this:

    {
        "token": "SESSION_TOKEN"
    }
    
  4. Because session tokens expire after 24 hours, you can create a permanent API token for agent provisioning by using the SESSION_TOKEN above:

    curl --location --request POST 'https://HOST/api/v1/keys' \
    --header 'Authorization: <SESSION_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "type": 2
    }'
    
  5. The output from creating a PERMANENT_TOKEN looks like the following. Please take note of the id (used later to revoke) and the value (the permanent API token):

    {
        "id": "710c6a92-b463-42ec-bf24-8ae24eb13081",
        "value": "PERMANENT_TOKEN",
        "issued_at": "2021-09-07T15:29:49.70146088Z"
    }
    
  6. Currently, the permanent token allows access to all API functionality, not just provisioning. You can revoke this permanent token at any time with the following call, using the id field above:

    curl --location --request DELETE 'HOST:80/api/v1/keys/<PERMANENT_TOKEN_ID>' \
    --header 'Authorization: <SESSION_TOKEN>'
    
  7. Create a config for Orb and pktvisor taps, for example, /local/orb/agent.yaml:

    version: "1.0"
    
    visor:
       taps:
          ethernet:
             input_type: pcap
             config:
                iface: "eth0"
    
    orb:
       db:
          file: /usr/local/orb/orb-agent.db
       tags:
          region: EU
          pop: ams02
          node_type: dns
       cloud:
          config:
             agent_name: myagent1
          api:
             address: https://HOST
          mqtt:
             address: tls://HOST:8883
    

  8. You can now pull and run ns1labs/orb-agent:develop to auto-provision, substituting in the PERMANENT_TOKEN and optionally configuring agent name and Orb tags. If you don't set the agent name, it will attempt to use a hostname. You must mount the directory to save the agent state database and the config file:

docker pull ns1labs/orb-agent:develop
docker run -v /local/orb:/usr/local/orb/ --net=host \
       -e ORB_CLOUD_API_TOKEN=<PERMANENT_TOKEN> \
      ns1labs/orb-agent:develop run -c /usr/local/orb/agent.yaml