Overview

InCenter maintains a revision history which stores all the changes made to the nodes under its control as well as InCenter itself. This history allows the administrator to view the changes made with each deployment and to also undo changes by restoring the node configuration to a particular point in the history. The CLI command revision is used to interact with the revision history.

InCenter User Database Change History is not Kept

It should be noted that there is one exception to the statement that the revision history stores all InCenter configuration changes. Changes to the InCenter user database and to the User objects in the database are not kept in the revision history and therefore cannot be reverted using the feature. User changes are also applied immediately when they are made and do not require activation.

Revision Command Options

The following are the revision command options for different actions:

Note that changes become part of the revision history only when they are committed.

Listing the Revision History

The revision command with no parameters or with the -list option will list the entire revision history:

admin@InCenter:/> revision -list
ID Date                User   Comment                 Nodes
-- ------------------- ------ ----------------------- --------
1  2017-05-10 15:35:48 System System created revision

The above output shows the revision history before adding any nodes or deploying any configuration changes. Each revision gets a unique ID number to identify it and the first (ID 1) represents the initial InCenter configuration after installation.

Suppose a new node is added to InCenter and this change is committed. This history might now look like the following, with the latest revision appearing at the top of the list:

admin@InCenter:/> revision -list 
ID Date                User    Comment                 Nodes
-- ------------------- ------  ----------------------- --------
2  2017-05-11 09:16:03 admin   Adding a node           my-node1
1  2017-05-10 15:35:48 System  System created revision

To list the revisions for only a selection of nodes, the -nodes option can be used followed by a comma separated list:

admin@InCenter:/> revision -list -nodes=my-node1,my-node2

Restricting Command Output

To restrict the number of entries displayed when listing the history, the -num option can be used:

admin@InCenter:/> revision -list -num=10

To restrict the entries displayed to a particular user, the -user option can be used:

admin@InCenter:/> revision -list -user=admin

The -comment option can be used to list only items with matching comments. The string match can be a partial match anywhere within the comment for the history item to be listed. For example:

admin@InCenter:/> revision -list -comment=ing 
ID Date                User    Comment                 Nodes
-- ------------------- ------  ----------------------- --------
2  2017-05-11 09:16:03 admin   Adding a node           my-node1

Applying Commands to a Single Node

When using the revision command, the action specified can be applied to a single node by changing the CLI context to be that node. For example:

admin@InCenter:/> cc StandaloneNode my-node1 
admin@InCenter:/my-node1> revision -list 
ID Date                User    Comment                 Nodes
-- ------------------- ------  ----------------------- --------
2  2017-05-11 09:16:03 admin   Adding a node           my-node1

Using the Revision ID Number

Each revision in the history has a unique ID number and this can be used to apply an action only to a specific revision. One example of usage is when listing the details of an individual revision in conjunction with the -show option. To list the details of the revision with an ID of 2, the command would be the following:

admin@InCenter:/> revision -show 2
Property          Value
----------------  ---------------------------
       Revision:  2
       Username:  admin
           Date:  2017-05-11 09:16:03 (+0000)
        Comment:  Adding a node
          Nodes:  my-node1
		

The following shortened form of the command will display the same output:

admin@InCenter:/> revision 2

Note that the ID of a history entry stays the same, regardless of the CLI context.

Reverting to a Previous Entry

It is possible to undo the last committed InCenter change by reverting to the previous entry in the history. For example, suppose the last action was to add a new node. To undo this action, the option -revert previous can be used. Like other configuration changes, this must be followed by an activate and commit sequence to save the change:

admin@InCenter:/> revision -revert previous
Revert action was successful
admin@InCenter:/> activate
Activate successful
admin@InCenter:/> commit
Commit successful
admin@InCenter:/> revision
ID Date                User   Comment                     Nodes
-- ------------------- ------ --------------------------- --------
4  2017-05-11 09:20:03 admin  Reverting node add          my-node2
3  2017-05-11 09:18:15 admin  Adding a node               my-node2
2  2017-05-11 09:16:03 admin  Adding a node               my-node1
1  2017-05-10 15:35:48 System System created revision

Note that the revert does not delete any history entries. Instead it adds a new entry to indicate that a revert was performed.

A revert action can be applied to only a specific node:

admin@InCenter:/> revision –revert previous
			StandaloneNode my-node1

This action could also be applied to an HAPair:

admin@InCenter:/> revision –revert previous
			HAPair my-hapair1

Reverting to a Given Entry

To revert to a specific point in the history, the ID number is used with the -revert option. For example, to revert to the initial configuration then the command would be:

admin@InCenter:/> revision -revert 1
Revert action was successful

Reverting a Node Deletion

If a node has been removed from InCenter using the delete StandaloneNode command, the deletion can be undone by using the revision -revert -node command. For example:

admin@InCenter:/> revision -revert -node=my-node1

When a deleted node is restored in this way, it is the original configuration held by InCenter that is pushed to the node. An import of the node's configuration does not take place.

Note that the -node= parameter cannot take a list of nodes. However, the -node= parameter can specify an HAPair object.

Applying Actions to a Specific Object

It is possible to apply the actions of the revision command to a specific object within a node configuration or within the InCenter system by changing the CLI context to be that object. Suppose that the administrator wants to revert to the previous version of the OSPFProcess object called my-proc in the configuration for the node called my-node1. The CLI commands would be the following:

admin@InCenter:/> cc StandaloneNode my-node1 
admin@InCenter:/my-node1> cc OSPFProcess my-proc 
admin@InCenter:/my-node1/OSPFProcess/my-proc>
				revision -revert previous

Now consider reverting the last change to an object within the InCenter system. For example, it might be desirable to revert the last change made to the system settings:

admin@InCenter:/> revision -revert previous Settings

Note that this will revert all the children of Settings to the value they had before the last activate and commit that affected the settings.

It is important to understand that the revert action will affect not only the target object but all the children of the object (but any parent is left unaffected). In the OSPF example above, the OSPFProcess object will probably have one or more OSPFArea objects and these too will be reverted as well as their own child objects.

Comparing History Entries

The -diff option can be used to show the changes between two points in the revision history. For example, to show the difference between the current configuration and the history at ID number 5:

admin@InCenter:/> revision -diff 5
Identifier                   Old Value  New Value
---------------------------  ---------  ------------
|- StandaloneNode testDev
|  |- System
|  |  |- Comments                       My comment
|  |- IPAddress my_ip1                  <added>

The difference between two IDs in the history can be displayed. For example, to show the difference between the entries with IDs 5 and 6:

admin@InCenter:/> revision -diff 5 6
Identifier                   Old Value  New Value
---------------------------  ---------  ------------
|- StandaloneNode testDev
|  |- System
|  |  |- Comments                       My comment
|  |- IPAddress my_ip1                  <added>

Deleting History Entries

It is possible to use the -delete option to delete a specific entry in the history. Whenever this is done, all earlier entries before the targeted entry are also deleted. In other words, all entries with a lower ID number are also deleted. This deletion will also include the initial default system entry that exists before any other history entries are added.

Suppose the current history is the following:

admin@InCenter:/> revision
ID Date                User   Comment                     Nodes
-- ------------------- ------ --------------------------- --------
3  2017-05-11 09:20:10 admin  Adding a node               my-node2
2  2017-05-11 09:16:03 admin  Adding a node               my-node1
1  2017-05-10 15:35:48 System System created revision

Now apply a delete operation from ID 2:

admin@InCenter:/> revision -delete 2 
Warning: Revision 2 and all older revisions will be deleted
Are you sure? Yes/[No]: Yes 
Delete action was successful

Relisting shows what remains after the delete:

admin@InCenter:/> revision
ID Date                User   Comment                     Nodes
-- ------------------- ------ --------------------------- --------
3  2017-05-11 09:20:10 admin  Adding a node               my-node2

Note that the delete operation always requires confirmation from the administrator before continuing.

Automatic Cleanup

It is possible to enable an automatic cleanup feature for the revision history using the following command in the Settings context:

admin@InCenter:/> cc Settings 
admin@InCenter:/Settings> set RevisionHistory
			CleanupEnabled=Yes

Once enabled, the revision history will be automatically cleaned up after each activate and commit sequence. This cleanup consists of both deleting older entries before a given cutoff date (the default is 30 days) as well as making sure that the deletions do not reduce the history to less than a minimum number of history entries (the default is 30 revisions).

The default values for the cleanup can be changed. For example, if any entry older than 60 days is to be deleted but deletions cannot reduce the history to less than 10 entries, the command would be:

admin@InCenter:/Settings> set RevisionHistory
			MaximumDaysToKeep=60
			MinimumRevisionsToKeep=10

Automatic cleanups are performed after a commit operation completes so the history entry added by the commit will be included in the calculation to determine which entries should be deleted.

The lowest value that can be entered for both the property MaximumDaysToKeep and the property MinimumRevisionsToKeep is zero. If both are set to zero then no revision history will be retained.

Note that the cleanup process applies to the entire revision history and it is not possible to apply the cleanup to just one node.

The Software Version in History Entries

Each entry in the revision history has associated with it the software version number associated with the node to which the change was applied. Whenever a configuration change is committed, the version number is stored with the entry.

If a committed change causes the node version number to be changed (because the software version on the firewall was higher) then it is this updated version number that is stored with the history entry for the commit.

In some cases, the history entry may just be for such a node version change. Performing an import of a node where the software version was higher in the actual firewall is an example of when this happens.

Reverting to a Different Software Version

The software version associated with a history entry becomes important when a revert operation is performed to a previous history entry with a different (usually lower) software version.

In this case, the version number of the original history entry is ignored. The current version number will remain unchanged and an object or an entire configuration in the revision history will be upgraded to the current version number. For a single object, this upgrade is performed during the revert operation. For an entire configuration, the upgrade is done after the activate operation and a message is generated to indicate this. An example of this is shown below:

admin@InCenter:/> revision -revert 3 
Revert action was successful
admin@InCenter:/> activate 
Operation in progress...
Activate successful
Notices:
-StandaloneNode my-node1: Configuration upgraded
from version 3.20.02.06 to 3.30.00.02
Run the "commit" command to keep the new configuration

Note that it is not possible to revert to a lower version of the software directly using InCenter. However, one way to do this would be to install the lower version on the firewall directly and then re-import the node into VFM. Another way would be to use the following steps: