Using the CLI¶

The command line interface allows you to interact with the database in a number of ways.

Location of the CLI Script¶

The CLI script is located in the bin/ directory and is called bin/pattoo_cli.py.

Running the CLI script without any parameters will display the usage options as seen below.

$ bin/pattoo_cli.py
usage: pattoo_cli.py [-h] {show,create,set,import,assign} ...

This program is the CLI interface to configuring pattoo

positional arguments:
  {show,create,set,import,assign}
    show                Show contents of pattoo DB.
    create              Create entries in pattoo DB.
    set                 Show contents of pattoo DB.
    import              Import data into the pattoo DB.
    assign              Assign contents of pattoo DB.

optional arguments:
  -h, --help            show this help message and exit

Language¶

pattoo is meant to support multiple languages. The default language is English with a language code of en. Agents do not post language specific data, but the keys used to define the data will need to be translated to descriptions that are meaningful to the end user.

Language translation files should be provided with any pattoo agent you install. You may have to create your own translation files for agents that poll data from non-standard data sources.

Viewing Languages¶

To view languages configured in the pattoo database use the bin/pattoo_cli.py show language command.

$ bin/pattoo_cli.py show language

idx_language  code  name

1             en    English

Upadating Language Names¶

You can update the name of a language using the bin/pattoo_cli.py set language command. You must specify the language code and provide a name using the --name qualifier

$ bin/pattoo_cli.py set language --code 'en' --name 'English (Jamaican)'

In this example we have changed the name to ‘English (Jamaican)’

Creating Languages¶

To create a new language use the bin/pattoo_cli.py create language command.

$ bin/pattoo_cli.py create language --code 'es' --name 'Spanish'

In this case we create a new language with the name “Spanish” and identifying code “es”

Agents¶

As stated before, pattoo agents report data to the central pattoo server.

Viewing Agents¶

To view the agents posting data to the pattoo server use the bin/pattoo_cli.py show agent command.

$ bin/pattoo_cli.py show agent

idx_agent  agent_program                agent_target  enabled

1          pattoo_agent_snmp_ifmibd     localhost     1
2          pattoo_agent_snmpd           localhost     1
3          pattoo_agent_os_autonomousd  nada          1
4          pattoo_agent_os_spoked       nada          1

Assigning Agents to Key-Pair Translations Groups¶

There are some important things to know first.

1. Each agent has an idx_agent number that can be seen in the first column of the bin/pattoo_cli.py show agent command. 1. Each agent group has an idx_pair_xlate_group number that can be seen in the first column of the bin/pattoo_cli.py show key_translation command.

To assign an agent to an agent group use the bin/pattoo_cli.py assign agent command.

$ bin/pattoo_cli.py assign agent --idx_agent 2 --idx_pair_xlate_group 4

In this case we have assigned agent with an idx_agent agent number of 2 to the idx_pair_xlate_group group number 4

Key-Pair Translations¶

Agents only post key-value pairs to the pattoo server. Translations are short descriptions of what each key means. The aim is for you to see these descriptions instead of the keys when you look at pattoo data with the pattoo-web UI.

When a translation for a key reported by an agent is installed, the translation is seen in pattoo-web instead of the key itself. This makes pattoo data more meaningful.

You don’t have to install translations for every agent that reports data. You just have to assign agents to agent groups, then you assign a single set of translations to the agent group.

Viewing Agent Group Key-Pair Translation Assignments¶

You can view these agent group to translation group assignments using the bin/pattoo_cli.py show key_translation_group command.

$ bin/pattoo_cli.py show key_translation_group

idx_pair_xlate_group  translation_group_name         enabled

1                     Pattoo Default                 1

2                     IfMIB Agents                   1

3                     OS Agents                      1

Creating Translation Groups¶

To create a new translation group use the bin/pattoo_cli.py create key_translation command.

$ bin/pattoo_cli.py create key_translation --name "Stock Market Symbol Translations"

In this case we create a new translation group with the name “Stock Market Symbol Translations”

Upadating Translation Group Names¶

You can update the name of a translation group using the bin/pattoo_cli.py set key_translation_group command. You must specify the group’s idx_pair_xlate_group value and a name.

$ bin/pattoo_cli.py set key_translation_group --idx_pair_xlate_group 20 --name 'New Translation Group Name'

In this example we have changed the name to ‘New Translation Group Name’ for idx_pair_xlate_group 20.

Viewing Agent Key-Pair Translation Groups¶

To view translation groups use the bin/pattoo_cli.py show key_translation command.

$ bin/pattoo_cli.py show key_translation

idx_pair_xlate_group  name            language  key                                                     translation                                units                   enabled

1                     Pattoo Default                                                                                                                                              1

2                     IfMIB Agents    en        pattoo_agent_snmp_ifmibd_ifalias                        Interface Alias                                                    1
                                      en        pattoo_agent_snmp_ifmibd_ifdescr                        Interface Description
                                      en        pattoo_agent_snmp_ifmibd_ifhcinbroadcastpkts            Interface Broadcast Packets (HC inbound)   Packets / Second
                                      en        pattoo_agent_snmp_ifmibd_ifhcinmulticastpkts            Interface Multicast Packets (HC inbound)   Packets / Second
...
...
...

3                     OS Agents       en        pattoo_agent_os_autonomousd_cpu_frequency               CPU Frequency                              Frequency               1
                                      en        pattoo_agent_os_autonomousd_cpu_stats_ctx_switches      CPU (Context Switches)                     Events / Second
                                      en        pattoo_agent_os_autonomousd_cpu_stats_interrupts        CPU (Context Switches)                     Events / Second
                                      en        pattoo_agent_os_autonomousd_cpu_stats_soft_interrupts   CPU (Soft Interrupts)                      Events / Second
                                      en        pattoo_agent_os_autonomousd_cpu_stats_syscalls          CPU (System Calls)                         Events / Second

Creating Agent Key-Pair Translation Group CSV Files¶

Creating a CSV key-pair translation file is easy. Follow these steps.

Make sure the first row has the following headings separated by commas.
language,key,translation,units

Each subsequent row must have values that correspond to the headings. Each value must be separated by a comma.
1. The language must correspond to the language configured in your pattoo.yaml configuration file. pattoo-web will only evaluate translation entries that match to the configured language. 1. The key value must correspond to any expected keys from key-value pairs reported by an agent. 1. The translation must correspond to the brief text you want to use to describe the key 1. The units value is used to let users know the unit of measure to be used for the data being tracked by the key
language,key,translation,units en,pattoo_agent_os_spoked_disk_io_write_bytes,Disk I/O (Bytes Written),Bytes / Second en,pattoo_agent_os_spoked_disk_io_write_count,Disk I/O (Write Count),Writes / Second en,pattoo_agent_os_spoked_disk_io_write_merged_count,Disk I/O (Write Merged Count),Writes / Second en,pattoo_agent_os_spoked_disk_io_write_time,Disk I/O (Write Time), en,pattoo_agent_os_spoked_disk_partition,Disk Partition, en,pattoo_agent_os_spoked_disk_partition_device,Disk Partition,

Not all key-value pairs will need units. For example, agent metadata won’t have them. In this case don’t put a value for units and end the line with a comma (,). The previous example shows three lines of translations including units followed by three without units.

Importing Agent Key-Pair Translation Group Files¶

There are some important things to know first.

1. Each translation group has an idx_pair_xlate_group number that can be seen in the first column of the bin/pattoo_cli.py show key_translation_group command. 1. The translations for the translation group must be in a CSV file formatted according to the guidelines mentioned previously.

To import a translation file’s data and assign it to a translation group use the bin/pattoo_cli.py import key_translation command.

$ bin/pattoo_cli.py import key_translation --idx_pair_xlate_group 7 --filename agent_name_1_english.csv

In this case we have imported translations from a file named agent_name_1_english.csv and assigned it to a translation group with an idx_pair_xlate_group number of 7.

You only need to import translations for the key-pairs you require. Any previously existing translation for an key-pair configured in the file will be updated. key-pairs not in the file will not be updated.

Agent Translations¶

Not only do an agent’s key-pairs need translations, but the agents themselves need translations too. This is because an agent only reports its name when posting which, through translations, allows pattoo to be more flexible in supporting many different spoken languages.

Without translations, all references to a pattoo agent will just be by its name, which could be confusing.

Viewing Agent Translations¶

To view agent translations use the bin/pattoo_cli.py show agent_translation command.

$ bin/pattoo_cli.py show agent_translation

language  agent_program                translation                          enabled

en        pattoo_agent_os_autonomousd  Pattoo Standard OS Autonomous Agent  1
          pattoo_agent_os_spoked       Pattoo Standard OS Spoked Agent
          pattoo_agent_snmpd           Pattoo Standard SNMP Agent
          pattoo_agent_snmp_ifmibd     Pattoo Standard IfMIB SNMP Agent
          pattoo_agent_modbustcpd      Pattoo Standard Modbus TCP Agent
          pattoo_agent_bacnetipd       Pattoo Standard BACnet IP Agent

Creating Agent Translation CSV Files¶

Creating a CSV agent translation file is easy. Follow these steps.

Make sure the first row has the following headings separated by commas.
language,key,translation

Each subsequent row must have values that correspond to the headings. Each value must be separated by a comma.

1. The language must correspond to the language configured in your pattoo.yaml configuration file. pattoo-web will only evaluate translation entries that match to the configured language. 1. The key value must correspond to the name of an agent. 1. The translation must correspond to the brief text you want to use to describe the key

language,key,translation
en,pattoo_agent_os_autonomousd,Pattoo Standard OS Autonomous Agent
en,pattoo_agent_os_spoked,Pattoo Standard OS Spoked Agent
en,pattoo_agent_snmpd,Pattoo Standard SNMP Agent
en,pattoo_agent_snmp_ifmibd,Pattoo Standard IfMIB SNMP Agent
en,pattoo_agent_modbustcpd,Pattoo Standard Modbus TCP Agent
en,pattoo_agent_bacnetipd,Pattoo Standard BACnet IP Agent

Importing Agent Translation Files¶

To import an agent translation file’s data use the bin/pattoo_cli.py import agent_translation command.

$ bin/pattoo_cli.py import agent_translation --filename agent_name_translation_english.csv

In this case we have imported translations from a file named agent_name_translation_english.csv.

You only need to import translations for the agents you require. Any previously existing translation for an agent configured in the file will be updated. agents not in the file will not be updated.