Configuration Guide

After installation, you will need to create a configuration file in a directory dedicated to pattoo.

Setting the Configuration Directory Location

Currently the configuration directory is automatically set when the installationscript is run

Configuration Options

There are two ways to configure pattoo. These are the:

  1. Quick Method
  2. Expert Method

Quick Method

Use the quick method if you are new to pattoo.

$ sudo setup/pattoo_installation.py install configuration

The above command will set the most optimal defaults for your system for pattoo.

Additionally, the pattoo user and group will be created with the home directory for the pattoo user being /home/pattoo All related directories and their subdirectories will be owned by the pattoo user

To guarantee success you will need to know the following beforehand.

  1. db_name: Database name
  2. db_username: Database username
  3. db_password: Database password
  4. db_hostname: Database hostname

Expert Method

This section goes into configuration parameters in great detail.

Copy the Templates to Your Configuration Directory

Follow the steps in this section if you don’t already have a valid configuration files in your PATTOO_CONFIGDIR directory.

Copy the template files in the examples/etc directory to the PATTOO_CONFIGDIR location.

NOTE: If a /path/to/configuration/directory/pattoo_server.yaml or /path/to/configuration/directory/pattoo.yaml file already exists in the directory then skip this step and edit the file according to the steps in following sections.

$ cp examples/etc/pattoo_server.yaml.template \
    /path/to/configuration/directory/pattoo_server.yaml

$ cp examples/etc/pattoo.yaml.template \
    /path/to/configuration/directory/pattoo.yaml

The next step is to edit the contents of both files.

Edit Your Configuration Files

The pattoo server uses two configuration files:

  1. pattoo.yaml: Provides general configuration information for all pattoo related applications. pattoo.yaml also defines how pattoo agents should connect to the pattoo server APIs.
  2. pattoo_server.yaml: Provides configuration details for all the pattoo server’s API daemons. These APIs accept data from pattoo agents and also provide data to pattoo related applications through your browser.

Take some time to read up on YAML formatted files if you are not familiar with them. A background knowledge is always helpful.

Server Configuration File

The pattoo_server.yaml file created from the template will have sections that you will need to edit with custom values. Don’t worry, these sections are easily identifiable as they all start with PATTOO_

NOTE: The indentations in the YAML configuration are important. Make sure indentations line up. Dashes ‘-‘ indicate one item in a list of items (if applicable).

pattoo_api_agentd:

    ip_bind_port: 20201
    ip_listen_address: 0.0.0.0

pattoo_apid:

    ip_bind_port: 20202
    ip_listen_address: 0.0.0.0

pattoo_ingesterd:

    ingester_interval: 3600
    batch_size: 500
    graceful_timeout: 10

pattoo_db:
    db_pool_size: 10
    db_max_overflow: 10
    db_hostname: PATTOO_DB_HOSTNAME
    db_name: PATTOO_DB_NAME
    db_password: PATTOO_DB_PASSWORD
    db_username: PATTOO_DB_USERNAME
Server Configuration Explanation

This table outlines the purpose of each configuration parameter.

Section Configuration Parameters Description
pattoo_api_agentd    
  ip_listen_address IP address used by the pattoo_api_agentd daemon for accepting data from remote pattoo agents. Default of ‘0.0.0.0’ which indicates listening on all available network interfaces. You can also use IPv6 nomenclature such as ::. The pattoo APIs don’t support IPv6 and IPv4 at the same time.
  ip_bind_port TCP port of used by the pattoo_api_agentd daemon for accepting data from remote pattoo agents. Default of 20201.
pattoo_apid    
  ip_listen_address IP address used by the pattoo_apid daemon for providing data to remote clients. Default of ‘0.0.0.0’ which indicates listening on all available network interfaces. You can also use IPv6 nomenclature such as ::. The pattoo APIs don’t support IPv6 and IPv4 at the same time.
  ip_bind_port TCP port of used by the pattoo_apid daemon for providing data to remote clients. Default of 20202.
pattoo_ingesterd    
  ingester_interval The interval between checking for new agent files in the cache directory. Only valid if using the pattoo_ingesterd daemon.
  batch_size The number of files to read per processing batch until all files are processed.
  graceful_timeout The amount of time required for the ingester to finish processing data when the stop or restart command is excuted before it is forcefully stopped or restarted.
pattoo_db    
  db_hostname Hostname of the database server
  db_username Username required for database access
  db_password Password required for database access
  db_name Name of database
  db_pool_size This is the largest number of connections that will be keep persistently with the database
  db_max_overflow Maximum overflow size. When the number of connections reaches the size set in db_pool_size, additional connections will be returned up to this limit. This is the floating number of additional database connections to be made available.
Client Configuration File

The pattoo.yaml file created from the template will have sections that you will need to edit with custom values. Don’t worry, these sections are easily identifiable as they all start with PATTOO_

NOTE: The indentations in the YAML configuration are important. Make sure indentations line up. Dashes ‘-‘ indicate one item in a list of items (if applicable).

pattoo:
    log_level: debug
    log_directory: PATTOO_LOG_DIRECTORY
    cache_directory: PATTOO_CACHE_DIRECTORY
    daemon_directory: PATTOO_DAEMON_DIRECTORY
    system_daemon_directory: PATTOO_SYSTEM_DAEMON_DIRECTORY
Client Configuration Explanation

This table outlines the purpose of each configuration parameter.

Section Configuration Parameters Description
pattoo    
  log_directory Path to logging directory. Make sure the username running the daemons have RW access to files there.
  log_level Default level of logging. debug is best for troubleshooting.
  cache_directory Directory that will temporarily store data data from agents prior to be added to the pattoo database.
  daemon_directory Directory used to store daemon related data that needs to be maintained between reboots
  system_daemon_directory Directory used to store daemon related data that should be deleted between reboots. This should only be configured if you are running pattoo daemons as systemd daemons. The systemd daemon installation procedure automatically adjusts this configuration. This parameter defaults to the daemon_directory value if it is not configured.