You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

opConfig Concepts

The main concepts to bear in mind are nodes, credential sets, commands, changes and revisions:

  • NODES:

    • Nodes are devices/computers that opConfig knows about, and which it is configured to run commands for.

    • As opConfig needs to connect to the node in question and execute commands on that node, the node needs to be configured with access credentials. In opConfig these are stored independent from the nodes in what opConfig calls credential sets.

  • CREDENTIAL SETS:

    • Credential sets are a combination of usernames, passwords, access protocols (ssh, telnet), privilege modes etc. allowing access to the devices CLI.
    • Once the credential set has been used to create a working CLI access then "commands" can be issued and the results recorded.

  • COMMAND SETS

    • Commands are normally command line constructs which will be executed on the node in question. 

      • (Some are "passive commands" like "audit-import" which are not actually run on the node but the result is associated with node.

      • Commands can be grouped and collected into what opConfig calls a "command set". Command sets are configured to apply only to particular OS and maybe versions or platforms.

    • The command output is captured and stored by opConfig.

    •  Command outputs are compared against the previous revision, and if different it's saved as a new revision in opConfig.  It could also be a one-shot command which is not analyzed in great detail (e.g. a process listing or some other diagnostic command)

    • A command can be marked for change detection in which case more detailed analysis occurs for changes.

  • CHANGES / REVISIONS:

    • Command outputs can be marked for change detection (e.g. a listing of installed software), in which case opConfig creates detailed records of what the changes are - again only if there are differences between the current command output and the most recent revision for this command.

    • Revisions are  the time series of the command outputs and there changes.

Adding Credential Sets, Managing Credential Sets

Credentials for all connections made by opConfig are configurable from the opConfig GUI ONLY.  Before anything else you need to create sets of credentials to access you devices.  At this point in time, opConfig supports only Telnet and SSH, and for SSH only password-based authentication is supported.

Select the menu "System", then "Edit Credential Sets". Credential sets can be shared by any number of nodes.

Each credential set has to have a unique name, by which it is referenced in the nodes' connection settings. The description field is self-explanatory and optional.

A credential set has to specify a User Name property, which is used when logging in to the nodes the set applies to. At this time, opConfig supports only password-based authentication at the node, and the Password property of the credential  set establishes the primary password for this user name. Future versions will support SSH Key-based authentication, as well as other mechanisms.

Some commands cannot be performed by an unprivileged user, which is why opConfig also supports elevating the privileges on demand. To control this, a credential set can optionally include a Superuser/Privileged/Enable Password. Depending on the node's platform and personality, different mechanisms will be used to gain increased privileges:

  • On Cisco IOS devices, this password  is used with the enable command.
  • With personality bash (the default for Unix-like systems), the command sudo is used to become the superuser. Sudo therefore needs to be installed and configured on such nodes, and the User Name in question needs to be authorized for sudo.

Naturally not all commands require elevated privileges; see the section on Command Sets for how to determine and configure those.

Please note that the Credential  Set editing dialogs do never show existing passwords (or their legth or existence); You can only overwrite password entries. All credential sets are stored in the database in encrypted form.

Adding or Modifying Nodes

To tell opConfig to run commands for a node it needs to be told about the node's existence and what properties the node has (e.g. what platform, what OS, what credential set, what protocol to use to contact the node ). Adding a node for opConfig can be done using the GUI or the command line tools opconfig-cli.pl and opnode_admin.pl. You can add node information manually to opConfig, or you can import node's info from NMIS or OpenAudit.

opConfig can connect to any node (and run commands for it) as long as it has valid connection settings for it (and as long as it is not disabled for opConfig).

Add a node Using the GUI

Add or Import

  • System menu
    • Edit Nodes.

      • "Import new Nodes from NMIS" or  "Add Node"   -  These let you create new node records either automatically or manually.  

If you successfully import the node from NMIS you should only need to add the credential set and the transport protocol (which are in the connection tab).  Import works for "bash" like devices and for Cisco devices.  For all other device types you simply need to add some details by hand.  You will see what configuration you MUST still add displayed as part of the "Edit Node" screen.  

The problem reports are fairly self-explanatory (and clickable).

  • The following is a breakdown on the information opConfig uses about the device.

  1. General TAB - This is generic information about the device and is the information imported from NMIS / OpenAudit.   Only the host entry needs to be correct here, and it must be a usable FQDN or IP address.
  2. Connection TAB -  To connect to a node, opConfig needs to know some information about it
    1.  Personality this is the CLI Parsing to use to enable the issuing of commands e.g. line endings, prompts etc.  The Personality includes information about the prompts, line-ending conventions etc. a node is subject to; for example, the 'ios' personality handles understanding the > prompt and  "enable" command and "bash" understands shell prompts.  The personalities supported are available in the drop down.
    2.  CredentialSet - NOT automatic and needs to be set - authentication and authorization in the form of the access credential set created earlier.
    3. Transport (Telnet or SSH) - NOT automatic and needs to be set
  3. OS info TAB -  Once connected to a node we need to know the OS and maybe version, subversion, platform in use to select the right commands to issue and how to parse the command results.  This where COMMAND SETS ("command_sets.nmis" file) that opConfig uses, makes association between the OS and maybe a  version and maybe a major release or train and the command to issue and how to parse it. 
    1. These fields should be automatically populated if your device was discovered by NMIS or OpenAudit if they are Cisco IOS or Linux devices
    2. The OS field and potentially the version and other fields must match the 'os' => and any 'version' => fields in the command_sets.nmis file.  

Import (and discovery) from the Command Line

opConfig CLI tools are found in /usr/local/omk/bin

opconfig-cli.pl can import nodes from NMIS, and offers a credential set and transport discovery option. Simply run opconfig-cli.pl without options to see a brief usage help.

To import you'd run opconfig-cli.pl act=import_from_nmis (optionally limited to the names of known nodes with an argument of nodes=nodeX,nodeY). If you have already setup credential sets, then you can let opConfig guess which to use for your node using opconfig-cli.pl act=discover node=TheNewNodeName - if none of the Transport+Credential Set combinations work for the node, opconfig-cli.pl will print an error message.

General Node management from the Command Line

The tool opnode_admin.pl lets you list, export, create, modify or delete nodes from the command line. Editing operations involve an export to a JSON file, which you then modify using an editor or other tool of choice, followed by an update of the node using that JSON file. The opnode_admin.pl tool is pretty self-explanatory, and behaves almost identically to the NMIS node_admin.pl tool which is documented extensively here.

Managing Command Sets

As mentioned above opConfig lets you organize whatever commands you'd like it to run into an arbitrary number of groups which we call command sets.

A command set definition consists of these types of information:

  • meta-information like the command set's name,
  • optional control information like scheduling constraints and an expiration policy for the commands in that set,
  • filters for selecting which devices/nodes the command set should apply to,
  • and finally the list of the actual commands to be run.

Here is an excerpt from the default command set that  ships with opConfig:

  'IOS_HOURLY' => {
    'os_info' => {
      'version' => '/12.2|12.4|15.\d+/',
      'os' => 'IOS'
    },
        'purging_policy' => {
            'keep_last' => 1000,
            'purge_older_than' => 2592000, # 30 days
            'autoprotect_first_revision' => 'true', 
        },    
        
        'scheduling_info' => {
      'run_commands_on_separate_connection' => 'false',
    },    
    'commands' => [
      {
        'multipage' => 'true',
        'privileged' => 'false',
        'command' => 'show interfaces',
        'tags' => [ 'HOURLY', 'performance', 'interfaces' ],
      },
      {
        'multipage' => 'true',
        'privileged' => 'false',
        'command' => 'show ip interface',
        'tags' => [ 'HOURLY', 'detect-change', 'configuration' ],
      },
... and lots more

Defining which nodes a command set applies to

This is normally done by filtering by OS info:

#filter using both regular expression and string equality checks:
'os_info' => {
 'version' => '/12.2|12.4|15.0/',
 'os' => 'IOS'
},
# or just the specific os family/type and that's all:
'os_info' => { 
 'os' => '/(Linux|CentOS|Ubuntu)/'
},

The examples above specify that the node in question must have an os_info property set, with sub-properties  os and version in the first example and just os in the second.

Plain string values indicate string comparison, but regular expressions can be given too. A node is only considered for this particular command set if all filtering expressions match. You can filter on any node property, not just properties from os_info (but the default command sets only use os_info).

Grouping commands into sessions

By default all commands for a node will be run sequentially, one after another within the same session/connection to that device.  This can save time as connecting to the device often takes longer than running all the commands one by one.  But this is not always the case,  and there are certain commands that run for a longer period of time (for example system statistics gatherers like vmstat or top). These commands would cause long delays in a sequential run, therefore opConfig lets you specify which commands should have their own separate connections. Separate connections can be opened in parallel.

If you would like to change the default behaviour and have opConfig run all commands in all command set in separate session/connection, simply modify opCommon.nmis like this:

# to run each command in it's own session, change this to true
 'opconfig_run_commands_on_separate_connection' => 'false',

It makes a lot more sense to tell opConfig to run a set of commands on their own or, in most cases, just a single command on its own.  Here is how to make a command or command set have their own sessions/connections:

# for all commands in a set, define this in the command set - note the S in run_commandS_...!
'scheduling_info' => {
 'run_commands_on_separate_connection' => 'true'
},

# for just a specific command, set this for the command in question - no S in run_command_...!
commands => [
 {
 'command' => 'show version',
 'run_command_on_separate_connection' => 'true',
 }]

In addition to session grouping, a command can also be marked with te privileged property, in which case opConfig will attempt to gain elevated/superuser privileges before attempting to run the command.

How long should captured command output be kept

opConfig 2.2. (and newer) have a flexible purging subsystem which is described in detail on a separate page here. The example above shows roughly how it's controlled: a command or command set can have a  section called purging_policy which controls whether and when a revision should be removed from the database.

What constitutes a change, and when should opConfig create new revisions

Not all output is worthy of change detection; configuration information generally is while performance information generally is not. The configuration for a router, for example, is - but the usage counters on an interface likely are not. As mentioned above, opConfig can deal with both of these types of commands, the "one-shot" ones as well as the change-indicating ones.

In a command set you tell opConfig which commands belong to what class by setting (or omitting) the tag detect-change.

If the tag is present, then change detection is run on this command's output: If and only if  the output is different from the previously stored revision, a new revision is stored along with detailed information of what the changes were. If the tag is not defined, then a new revision is created if the output is different - but no detailed changes are tracked, and the opConfig GUI will only report the command's revision in the list of "commands" but not in the list of "configuration changes".

'tags' => ['detect-change'],

Related to this is the question of what changes that were found should be considered important or relevant.  opConfig can "ignore" unimportant differences in a command's output if you provide it with a set of command filters for a command:

'privileged' => 'false',
'command' => 'ifconfig -a',
'tags' => [ 'DAILY', 'configuration', 'detect-change' ],
  'command_filters' => [
    '/RX packets/',
    '/TX packets/',
    '/RX bytes/',
    '/TX bytes/'
  ]

In the example above, the output of the "ifconfig -a" command would be checked and any changed lines that match TX/RX packets or TX/RX bytes (i.e. the interface counters) are ignored. Any other changes that remain after applying the filters are used to figure out whether to create a new revision or not.

Please note that command filters are possible for both one-shot commands and commands with change-detect enabled,  and behave the same for both.

How to categorize command sets (and why)

As seen in the examples above, commands can have a number of pre-defined tags like detect-change or report-change; but you are encouraged to set your own custom tags to characterize the commands according to your preferences.

The default command set shipped with opConfig uses two primary tags for categorization, DAILY and HOURLY.These are used in the example cron invocations of "opconfig-cli.pl act=run_command_sets" so that all commands with tag DAILY are run only once a day, whereas the HOURLY ones run once an hour. Commands with neither tag will not run periodically, for example there are numerous commands tagged with troubleshooting which will only be run in reaction to an event detected in opEvents.

Using tags in this fashion for categorization is much more convenient than having to tell opconfig-cli.pl which command sets to run by name (which is also possible).

Raising Events when changes are detected

opConfig 2.2 and newer can raise an event with NMIS if a change was detected for a node and a particular command. To activate this feature you have to  give the command in question both the tags detect-change and report-change. You may also give a fixed event severity (values as defined in NMIS), like in this example:

'privileged' => 'false',
'command' => 'chkconfig',
'tags' => [ 'DAILY', 'configuration', 'detect-change', 'report-change' ],
'report_level' => 'Minor',

In this case, the Redhat/Centos command chkconfig (= list of system services to automatically start on boot) will be checked for changes, and if any are found then a "Node Configuration Change" event with the context node in question, the element "chkconfig" and the serverity "Minor" will be raised in the local NMIS.

If you want a more dynamic event severity, then you can use report_level_min_changes which selects a severity based on the number of changes that were found:

{        
 'privileged' => 'true',
 'command' => 'vgdisplay',
 'tags' => [ 'DAILY', 'configuration', 'detect-change', 'report-change' ],
 'report_level_min_changes' => {
   1 => "Normal",
   3 => "Minor",
   10 => "Major" },
}

In this example, changes in the vgdisplay command output would result in an event of severity Normal if there are 1 or 2 changes, Minor for 3 to 9 changes, and Major for 10 or more.

General Usage of opconfig-cli.pl

opconfig-cli

Information on what commands are supported is printed when no options are specified.  All options support debug=true for debug output and debug=9 for extremely verbose output.  

Listed below are the possible options for the act=X argument:

import_from_nmis

Grabs one or more nodes from NMIS. Identical in function to "Refresh" or "Import Nodes from NMIS" in the GUI.

discover

Tests a single given node (argument node=nodeX) and attempts to determine its Transport and Credential Set configuration. The node must already have a Personality set.

test_connect

opconfig-cli can be used to test connections to help debug situations that don't make any sense. 

An example of how it can be used:

bin/opconfig-cli.pl act=test_connect host=192.168.88.254 transport=Telnet personality=ios username=testuser password=testpass

The options for transport and personality are given above.

It is also possible to test an existing connection from the connections.nmis file by specifying node=node_name , if any options are specified on the command line along with the node they will override the settings loaded from the connections.nmis file.

command="some command" can also be specified to test the output of a specific command.

run_command_sets, Running commands on devices

This command will run all applicable command sets for all nodes (by default).

Options:

  • nodes=node1,node2,etc -- only command sets that apply to the specified nodes will be run.
  • names=command_set1,command_set2,etc – only run the specified command sets (and of course only for nodes matching the command sets' criteria)
  • tags=tag1,tag2,etc –  The candidate commands are filtered by the tags specified. If one or more tags given on the command line is present in the list of a command's tags, then the command will be run.

get_command_output, Get the last output from a command for a node

Requries node=node_name command="command name" and returns output collected from the last run of this command

diff_command_outputs, Diff two revisions 

Shows the diff from the output of 2 revisions of stored output (does not run them, only queries).  The command line would look similar to get_command_output with the edition of revision_1= and revision_2=

eg. act=diff_command_outputs node=node1 command="show run" revision_1=10 revision_2=13

import_audit

This action imports audit information from Open-AudIT Enterprise, for all devices known to Open-AudIT.

This requires a licensed Version 1.4 of Open-AudIT Enterprise or newer. The audit information will show up in opConfig as command "audit", and the command output  will be the full audit data set in JSON format. Nodes will be consolidated as much as possible with your currently existing node definitions.


To enable this functionality, set the necessary options in conf/opCommon.nmis and run opconfig-cli.pl act=import_audit periodically or as a one-off. The required config settings are as follows:

'opconfig_audit_import' => 1, # to enable this altogether
'opconfig_audit_import_url_base' => "http://my.oae.system.com/omk/oae/",
'opconfig_audit_import_user' => "nmis",         # needs ro-access
'opconfig_audit_import_password' => "somepassword",

list_policies, import_policy, export_policy; update_config_status, export_config_status  and check_compliance

These operations are documented on the separate page about Compliance Management.

  • No labels