Subject: Issue 11.2.13: rollback capability

From: Andy Bierman <[email-masked]>
Date: Fri, 16 Jul 2004 16:18:39 -0700

Hi,

I don't think the WG has fully addressed the strong request
made at the last IETF to add some rollback support.
Initially, XMLCONF had <checkpoint> and <rollback> operations
but they were taken out because of disagreements related to
the application of other protocol operations (e.g., get-config
or copy-config) on the "snapshot config". I think this feature was 
dropped too soon.

We really need checkpoint and rollback to support coordinated 
commit (or undo) procedures across multiple devices.
(E.g., a network change requires some config changes on 10
boxes: 9 succeed and the 10th fails : the manager needs
a way to easily revert the 9 boxes that accepted the
config changes).  This feature makes it easy for 
a manager to undo committed configuration changes on a 
network device.

X.1) Rollback Capability

X.1.1) Overview

The rollback capability allows an application to easily revert
the <running> configuration to a previously saved state.
The saved state is maintained in an implementation-specific
manner, and cannot be retrieved, copied, edited, or validated
by the application.  This feature is complex to implement
and resource-intensive, so it is optional, and its support
is indicated by this capability.

Conceptually, the agent maintains a ring buffer of
saved configuration data for each session.  At least
one saved configuration (per-session) must be supported 
by an agent that supports the #rollback capability.

The application uses the <checkpoint> operation to
add a new saved configuration to the ring-buffer.
If the buffer is full, then the oldest existing entry 
will be over-written by the new entry.  The <rollback>
operation is used to revert the <running> configuration
to the most recent saved state in the ring-buffer.
A saved configuration is removed automatically from the 
ring-buffer after it is reverted (with the <rollback> 
operation.  Saved configurations can be discarded
manually with the <discard-checkpoint> operation.
Even though the <running> configuration is global, a separate 
rollback ring-buffer is maintained for each NETCONF session.
The agent MUST NOT change the size of this ring-buffer (for 
a particular session) while that session is active.  When a 
session terminates for any reason, all internal resources related 
to rollback are released by the agent.   

X.1.2) Dependencies

None

X.1.3) Capability and Namespace

The rollback capability is identified by the string "rollback",
and is named as follows:

   urn:ietf:params:xml:ns:netconf:base:1.0#rollback

If the #rollback capability is advertised, it means the <checkpoint>, 
<discard-checkpoint> and <rollback> operations are supported. 
The <rollback-depth> parameter value in the netconf-state data model
must be equal to a value greater than zero.

X.1.4) New Operations

X.1.4.1)  <checkpoint>

This protocol operation causes the agent to take whatever steps required
to capture the current state of the <running> configuration, so
a subsequent <rollback> operation will cause the <running> 
configuration to revert to this state.  This operation has no
parameters.

X.1.4.2) <rollback>

This protocol operation causes the agent to take whatever steps required
to revert the <running> configuration to the state captured at the
time of the last <checkpoint> operation.  The checkpoint data
is removed from the session's rollback ring buffer after this
operation is completed.  The agent SHOULD revert the configuration
in a manner that causes the least amount of disruption to the
running network.   

If complete restoration of the running configuration requires a 
system or module restart, then the agent will return a 
RESTART_REQUIRED error.  In this case, some restoration 
of the <running> configuration may already be completed, but 
the manager must initiate an  appropriate restart sequence 
in order to complete the <rollback> operation.  This operation 
has no parameters.

X.1.4.3) <discard-checkpoint>
     
This protocol operation causes the agent to remove a specified
number (or all) of configurations previously saved with the 
<checkpoint> operation.  
     
Parameter:  <count> : NonNegativeInteger

  The number of saved configurations to discard.  The value zero
  indicates that all saved rollback configurations for this session
  should be discarded.  If this value is greater than the current
  number of saved rollback configurations, then a BAD_ELEMENT error
  will be returned, with the <bad-element> value set to "count".

  This parameter is optional.  The default value of one is used
  if this parameter is not present in the <discard-checkpoint>
  operation.

X.1.5) Modifications to Existing Operations

None

X.1.6) Interactions with Other Capabilities

Although similar in implementation requirements, the #rollback
capability is independent of the #rollback-on-error capability.
An agent which supports #rollback SHOULD support the
#rollback-on-error capability as well.

X.1.7) Additions to the netconf-state Data Model

X.1.7.1) <rollback-depth>

A read-only parameter to indicate the maximum number 
of saved rollback configurations the agent will support for
a single NETCONF session.  If the #rollback capability
is not supported, then the value zero MUST be returned.

A positive integer value indicates the maximum depth of the 
rollback ring-buffer that the agent supports for any NETCONF 
session.  When this depth is reached, a subsequent <checkpoint> 
operation will cause the oldest saved rollback configuration data 
to be deleted.  

[TBD -- update XSD to include this parameter]

X.1.8) Additions to the NETCONF Error Code Set

X.1.3.1) RESTART_REQUIRED

  Tag:         RESTART_REQUIRED
  Severity:    warning 
  Error-info:  none  [ed. - TBD]
  Description: The requested protocol operation will require
               a system or module restart in order to be completed.
               The system may not operate properly until this restart
               is performed.

X.1.9) Usage Examples

X.1.9.1) High level edit operation sequences for target==<running>

start_edit:
  lock(running)
  lock(startup)
  checkpoint
prepare:
  edit-config(running, rollback-on-error) +
commit:
  N/A
persist_changes:
  copy-config(running, startup)
rollback:
  rollback
end_edit:
  discard-checkpoint(0)
  unlock(running)
  unlock(startup)

X.1.9.1) High level edit operation sequences for target==<candidate>

start_edit:
  lock(candidate)
  lock(running)
  lock(startup)                    // if #distinct-startup is true
  checkpoint
prepare:
  edit-config(candidate, stop-on-error) +
commit:
  commit                
persist_changes:
  copy-config(running, startup)
rollback:
  discard-changes                  // if commit has not been done
         OR
  rollback                         // if commit has been done
end_edit:
  discard-checkpoint(0)
  unlock(candidate)
  unlock(running)
  unlock(startup)                  

--
to unsubscribe send a message to [email-masked] with
the word 'unsubscribe' in a single line as the message text body.
archive: <http://ops.ietf.org/lists/netconf/>