Content Comparison

...

Once the data source is configured, you can either send us the required information if you want us to host and manage the collector for you (Cloud collector), or deploy and host the collector in your own machine using a Docker image (On-premise collector).

This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running.

Structure

{
  "global_overrides": {
    "debug": false
  },
"inputs": {
  "firewalla_msp": {
    "id": "<short_unique_id>",
    "enabled": true,
    "credentials": {
      "msp_domain": "<msp_domain>",
      "api_token": "<api_token>"
    },
    "services": {
       

"boxes": {
        

 "request_period_in_seconds" : "<request_period_in_seconds>",
          

Devo credentials

In Devo, go to Administration → Credentials → X.509 Certificates, download the Certificate, Private key and Chain CA and save them in <product_name>/certs/. Learn more about security credentials in Devo here.

Image Removed

Editing the config.yaml file

 "override_devo_tag": "<override_devo_tag>"
       },
       "alarms": {
    

"request_period_in_seconds" : "<request_period_in_seconds>",
         

  "start_time_in_utc": "<start_time_in_utc>",
  

"include_alarm_details": 

"<include_alarm_details>",
           

"override_devo_tag": "<override_devo_tag>",
        

  "override_detail_devo_tag": "<override_detail_devo_tag>"
     

 },
       

"devices": 

{
         

 "request_period_in_seconds" : "<request_period_in_seconds>",
    

"include_device_details": "<include_device_details>",
     

"override_devo_tag": "<override_devo_tag>",
    

"override_detail_devo_tag": "<override_detail_devo_tag>"
      

 },
    

   "flows": 

{
 

         "request_period_in_seconds" : "<request_period_in_seconds>",

"start_time_in_utc": "<start_time_in_utc>",
       

"override_devo_tag": "<override_devo_tag>"

}
     }
   }
 

Replace the placeholders with your required values following the description table below:

Parameter

Data type

Type

Value range / Format

Details

<devo_address>

str

Mandatory

collector-us.devo.io, collector-eu.devo.io

Use this param to identify the Devo Cloud where the events will be sent

<chain_filename>

str

Mandatory

Minimum length: 4, Maximum length: 20

Use this param to identify the chain.cert file downloaded from your Devo domain. Usually this file's name is: chain.crt

<cert_filename>

str

Mandatory

Minimum length: 4, Maximum length: 20

Use this param to identify the file.cert downloaded from your Devo domain.

<key_filename>

str

Mandatory

Minimum length: 4, Maximum length: 20

}
}

The following table outlines the parameters available for configuring the collector. Each parameter is categorized by its necessity (mandatory or optional), data type, acceptable values or formats, and a brief description.

Download the Docker image

The collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table:

Collector Docker image

SHA-256 hash

collector-firewalla_msp_if-docker-image-1.0.0

c79ca79b3b94b3b0f8fb22ca2c90153c702571b8e6f175486a51975e678e9f50

Use the following command to add the Docker image to the system:

gunzip -c <image_file>-<version>.tgz | docker load

The Docker image can be deployed on the following services:

Docker

Execute the following command on the root directory <any_directory>/devo-collectors/<product_name>/

docker run 
--name collector-<product_name> 
--volume $PWD/certs:/devo-collector/certs 
--volume $PWD/config:/devo-collector/config 
--volume $PWD/state:/devo-collector/state 
--env CONFIG_FILE=config.yaml 
--rm 
--interactive 
--tty 
<image_name>:<version>

Docker Compose

The following Docker Compose file can be used to execute the Docker container. It must be created in the <any_directory>/devo-collectors/<product_name>/ directory.

version: '3'
services:
  collector-<product_name>:
    image: <image_name>:${IMAGE_VERSION:-latest}
    container_name: collector-<product_name>
    volumes:
      - ./certs:/devo-collector/certs
      - ./config:/devo-collector/config
      - ./credentials:/devo-collector/credentials
      - ./state:/devo-collector/state
    environment:
      - CONFIG_FILE=${CONFIG_FILE:-config.yaml}

To run the container using docker-compose, execute the following command from the <any_directory>/devo-collectors/<product_name>/ directory:

IMAGE_VERSION=<version> docker-compose up -d

We use a piece of software called Collector Server to host and manage all our available collectors. If you want us to host this collector for you, get in touch with us and we will guide you through the configuration.

This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running.

Structure

The following directory structure should be created for being used when running the collector:

<any_directory>
└── devo-collectors/
    └── <product_name>/
        ├── certs/
        │   ├── chain.crt
        │   ├── <your_domain>.key
        │   └── <your_domain>.crt
        ├── state/
        └── config/ 
            └── config.yaml 

Devo credentials

In Devo, go to Administration → Credentials → X.509 Certificates, download the Certificate, Private key and Chain CA and save them in <product_name>/certs/. Learn more about security credentials in Devo here.

Image Added

Editing the config.yaml file

globals:
  debug: false
  id: not_used
  name: firewalla_msp
  persistence:
    type: filesystem
    config:
      directory_name: state

outputs:
  devo_1:
    type: devo_platform
    config:
        address: <devo_address>
        port: 443
        type: SSL
        chain: <chain_filename>
        cert: <cert_filename>
        key: <key_filename>
  console_1:
    type: console

inputs:
  firewalla_msp:
    id: <short_unique_id>
    enabled: true
    credentials:
      api_token: <api_token>
      msp_domain: <msp_domain>
    services:
      boxes:
        request_period_in_seconds : <request_period_in_seconds> #optional
        override_devo_tag: <override_devo_tag> #optional
      alarms:
        request_period_in_seconds: <request_period_in_seconds> #optional
        start_time_in_utc: <start_time_in_utc>
        override_devo_tag: <override_devo_tag> #optional
        include_alarm_details: <include_alarm_details> #optional
        override_detail_devo_tag: <override_detail_devo_tag> #optional
      devices:
        

request_period_in_seconds

: 

<request_period_in_seconds>

 #optional
        include_device_details: <include_device_details> #optional
    

    override_devo_tag

: 

<override_devo_tag>

 #optional
      

  override_detail_devo_tag: <override_detail_devo_tag> #optional
  

  flows:
        

request_period_in_seconds

: 

<request_period_in_seconds>

#optional
        

start_time_in_utc

The following table outlines the parameters available for configuring the collector. Each parameter is categorized by its necessity (mandatory or optional), data type, acceptable values or formats, and a brief description.

Parameter

Data type

Requirement

Value range / Format

Description

<short_unique_id>

int

Mandatory

Minimum Length 5

Use this param to give a unique id to this input service.

This parameter is used to build the persistence address, do not use the same value for multiple collectors. It could cause a collision.

<input_status>

bool

Mandatory

false / true

Use this param to enable or disable the given input logic when running the collector. If the value is true, the input will be run. If the value is false, it will be ignored.

<api_token>

str

Mandatory

Minimum Length 1

api_token for firewalla_msp API

<msp_domain>

str

Mandatory

Minimum Length 1

msp_domain for firewalla_msp API Ex:- https://{msp_domain}.firewalla.net

<start_time_in_utc>

str

Mandatory

start time in utc format: %Y-%m-%dT%H:%M:%SZ

Only applicable for flows and alarms service. This parameter allows to get the data from provided start time. Ex:- 2024-01-01T01:50:00Z

<override_devo_tag>

str

Optional

A devo tag

This parameter allows defining a custom devo tag.

<request_period_in_seconds>

int

Optional

Minimum Length 1

Period in seconds used between each data pulling, this value will override the value. The default value is 60 seconds

<include_device_details>

boolean

Optional

false / true

if true collector will fetch data from endpoint /v1/device/{gid}/{mac}

<include_alarm_details>

boolean

Optional

false / true

if true collector will fetch data from endpoint /v2/alarms/{gid}/{aid}

<override_detail_devo_tag>

str

Optional

A devo tag

It will override the devo tag for the alarm detail and device details if provided in those services

: <start_time_in_utc>
        override_devo_tag: <override_devo_tag> #optional

Replace the placeholders with your required values following the description table below:

Download the Docker image

The collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table:

Use the following command to add the Docker image to the system:

gunzip -c <image_file>-<version>.tgz | docker load

The Docker image can be deployed on the following services:

Docker

Execute the following command on the root directory <any_directory>/devo-collectors/<product_name>/

docker run 
--name collector-<product_name> 
--volume $PWD/certs:/devo-collector/certs 
--volume $PWD/config:/devo-collector/config 
--volume $PWD/state:/devo-collector/state 
--env CONFIG_FILE=config.yaml 
--rm 
--interactive 
--tty 
<image_name>:<version>

Docker Compose

The following Docker Compose file can be used to execute the Docker container. It must be created in the <any_directory>/devo-collectors/<product_name>/ directory.

version: '3'
services:
  collector-<product_name>:
    image: <image_name>:${IMAGE_VERSION:-latest}
    container_name: collector-<product_name>
    volumes:
      - ./certs:/devo-collector/certs
      - ./config:/devo-collector/config
      - ./credentials:/devo-collector/credentials
      - ./state:/devo-collector/state
    environment:
      - CONFIG_FILE=${CONFIG_FILE:-config.yaml}

To run the container using docker-compose, execute the following command from the <any_directory>/devo-collectors/<product_name>/ directory:

IMAGE_VERSION=<version> docker-compose up -d

Collector services detail

This section is intended to explain how to proceed with specific actions for services.

...

.

Common Setup outpur for all services

...