Introduction

opConfig 3 introduces the ability to 'push' configuration changes to devices, complete with error detection, support for change rollback and complete audit trails.

...

opConfig has always supported 'command sets', which consist of (individual) commands that can be sent to devices and whose output is collected and analyzed. Command sets are expected to be idempotentindependent, safely repeatable and without side effects. Command sets don't support sequencing or error detection, and thus are not suitable (or intended!) for modifying device configurations.

...

The primary storage and exchange format for config sets is JSON; example config  sets can be find found in install/config_sets.d/ and it is recommended that you store your actively developed config sets in conf/config_sets.d/.

...

1. an explicit single value
   for example,  "os_info.platform": "x86_64" would match if the node's OS platform value is exactly equal to "x86_64".
2. a list of alternative values
   for example "name": [ "nodeA", "nodeB"] would match either of the two nodes named nodeA or nodeB. The comparison is again strict equality.
   The filter clause is considered a match if one or more choices amongst the list of alternatives do match.
   1. If you are using the GUI, just introduce a list of node names separated by commas. 
3. a regular expression
   for example "os_info.os":  "/IOS/i" would select nodes whose OS contains the string "IOS" (or "ios", "IoS" etc.) anywhere.
   Note that the regular expression must be given as a string, starting and ending with a "/" and optionally including the "i" modifier for case-insensitive matching.

...

1. Continue the config set application
   This is the default behaviour. opConfig  will keep and report a tally of successful versus failed commands, but will try to apply all of them in sequence.
2. Abort the config set application
   To select this option, the property break_on_error must be set to true. In this case, the first failed command in a set causes all other commands to be skipped.
3. Apply Rollback commands
   To revert the configuration back to a desired state, you would have to provide a sequence of rollback-commands in your error-handling section.
   Rolling back woud would generally be combined with break_on_error, but opConfig does not strictly require itthat.

Stages and their Commands

...

The "plain" post-commands stage is chosen in all cases where no rollback was performed (i.g. if error handling was disabled or if all commands succeeded; )' on the  other hand, if a rollback was performed, then only the post-rollback-commands are applied.

A common task for the  post-commands stage would be a capture of the newly changed configuration (to double-check that everything has worked), or the cancelling of a future reload on Cisco devices.

The commands Stage (required)

...

If error detection is enabled and if this stage is provided, then its commands will be applied as soon as errors are detected. The rollback commands are sent while in configuration mode, and no error handling is possible.

the five different command sections, pre, post, commands, rollback-commands and post-rollback-commands

Config Set Management

fixme tbc

import from cli only at this time; view is possible from gui

can list, export, activate and deactivate

Config Push Scheduling

fixme tbc

time formats

gui or cmdline

limitations for non-admin user, filters cannot be overridden, just refined

parallelism

limited rescheduling on failure

...

Config Set Management

As mentioned above, config set documents must be imported into opConfig to become active. Configuration sets cannot be deleted (to ensure a valid audit trail), but they can be superseded and optionally disabled and hidden from the GUI.

opConfig's opconfig-cli.pl provides full config set management, using the functions import_configset, list_configset, export_configset and enable_ and disable_configset; As of version 3.0.0, the opConfig GUI only allows to display the newest revision for a config set.

A new revision of a config  set automatically starts in "enabled" state, and scheduled operations normally use the highest enabled config set revision. To switch to an earlier revision instead you may disable the unwanted but higher numbered revision; in which case the GUI will no longer show the disabled revision, nor will scheduling of config changes pick this disabled revision.

Scheduling of Configuration Changes

Scheduling of config  set applications can be performed both from the GUI as well as using opconfig-cli.pl. When you schedule a change, you have to provide at least an execution time and a config  set (name); optionally you may also provide refinements for device selections, or additional notification recipients. A schedule is immutable once set and can only be removed entirely.

Time Formats

opConfig accepts all common time formats as described on the Supported Time Formats page. These include both absolute time and date formats like the ISO 8601 type "2016-05-20T14:40", as well as very handy relative formats like "now + 45 minutes" or "tomorrow midnight".

To enter relative formats when scheduling config changes from the GUI you'll have to use the Target Date/Time input field as the Date and Time picker only produces absolute outputs.

If you schedule a change for a time in the past, then the opConfig daemon will execute the operation immediately.

Selection Refinements

The device filters and notification recipients given in a config set cannot be overruled when scheduling a config change; they can only be refined and extended.

• If you use the Refine Node Selection options in the scheduling GUI, then all candidate devices will have to match both filters from the config set and your refinement filters in order to be targetted.
  If your refinements or the config set filters are too strict and don't meet at least a single existing node, the change will not be scheduled and you will see an error message in the scheduling GUI.
• If you add Email Notification recipients when scheduling, then these recipients  will be added to recipients from the config set.

Scheduling using the CLI Tool

To perform a configuration change operation from the command line you would be using opconfig-cli.pl act=push_configset name=<cset name>. Refinements can be given using an explicit list of desired nodes with nodes=nodeA,nodeB...; extra email recipients can be given with the optional email=a@b.c,e@f.g... argument.

If you don't provide a target time (with at=<timespec>), then opconfig-cli will execute the configuration change immediately. With an at argument in the future, the  change will be scheduled for the given date and time.

You may check the list of scheduled jobs using the command opconfig-cli.pl act=list_queue, and to delete a scheduled (but not yet active) job use the argument act=remove_queued with the job's id (shown by act=list_queue with_ids=true).

Limitations in opConfig 3.0.0

fixme tbc

pbs only primed fullly for cisco ios devices, must have config mode prompt and enter/leave macros

no config set editing from the gui, no import or export of csets from the gui eitherAs of version 3.0.0, only one-off scheduling is supported; recurring schedules are planned for a future release.

The shipped phrasebooks are not fully primed for configuration changing for device types other than Cisco IOS; more specifically most other phrasebooks do not have the  necessary macros and prompts for handling configuration mode yet.

Within the opConfig GUI, config sets can only be viewed, not edited or imported/exported; A full config set management GUI is planned for the next release.

Config Set Example

This fully functional example config  set ships with opConfig 3.0.0 as install/config_sets.d/IOS-Configuration-Best-Practices.json.

{
    "name": "IOS - Configuration Best Practices",
    "description": "A configuration set to configure the IOS device, by enabling and disabling various services and features.",
    "filter":
    {
        "os_info.os": "IOS"
    },
    "notify": { "email": "you@company.com" },
    "error_handling":
    {
        "match": [ "/Invalid input detected/" ],
        "break_on_error": false
    },
    "pre-commands":
    [
        "_reload_in 5"
    ],
    "commands":
    [
    "no ip http server",
    "no ip http secure-server",
    "no ip finger",
    "no service finger",
    "no service udp-small-servers",
    "no service tcp-small-servers",
    "no boot network",
    "no service config",
    "service password-encryption",
    "service timestamps debug datetime msec",
    "service timestamps log datetime msec",
    "service sequence-numbers",
    "service tcp-keepalives-in",
    "service tcp-keepalives-out",
    "no ip source-route",    
    "line con 0 ",
    "exec-timeout 10 0",
    "exit",
    "line vty 0 4",
    "exec-timeout 10 0",
    "exit"
    ],
    "post-commands":
    [
        "reload cancel"
    ]
}

Config Set GUI

From opConfig 4.2.6 it is possible to edit the config sets in the GUI. 

In the menu System > Manage Config Sets you can access the editor: 

Image Added

Please note, once a config set is saved, a new version will be created in the database. 

It is not possible to delete a config set, but you can export one in json format:

Image Added

Config Set Parameters

From opConfig 4.2.6 it is possible to use parameters in a config set. 

The parameters are global to commands, pre commands or post commands, and are specified with the parameter name preceded by $

Example

Image Added

Using a config set with parameters

cli Example

Using the cli tool opconfig-cli, you can specify parameters to push a config set using parameter.parametername, like:

./opconfig-cli.pl act=push_configset name="my configset" parameter.interface=Tunnel100 parameter.description="Configuration change example" debug=2

GUI Example

Using the GUI, if a config set has parameters, you will have a second modal window to specify all the needed parameters:

Image Added

Config set parameters will be introduced on a second screen: 

Image Added