Configuration (part 2 – Snapshots)
In part 2 we’re looking at how to use the API to write some code. We’ll also look at some setup steps that are helpful in our overall solution. In this article we’ll focus on the most common uses of the API, but you will find there are more options when you look into the manuals.
Snapshot Save and Load
The NA_Configuration interface provides the save/load functionality.
Save
Saving a snapshot captures the server’s configuration in-full and stores it to the registry under the path /netacq/server/configurations. The save occurs synchronously and typically short. Saving a snapshot is also relatively simple.
// C#
NA_Configuration root = server.GetConfiguration("");
root.SaveSnapshot("my snapshot name", "description of the snapshot");When saving programmatically, it’s best to either add some date/time information to the name to make the name unique, or check the names that exist already and provide some unique name. If you use an existing name, the call will overwrite the existing snapshot.
Factory Default
The default snapshot was created at the factory as a way to provide a “clean” snapshot that can be rolled back to. We encourage users to take snapshots in order to capture the setup of their systems. Checkpointing from time to time, especially when developing, can help return to known states.
Configure and Save using MissionView
You can also save snapshots using our page. If you are planning to use partial snapshots to apply a smaller set of configuration, you will use our save and load page. Here are some steps you may choose to follow.
- Configure the system to the setup you want to capture
- Take a snapshot, providing a useful name and description, then press Save Snapshot
- Optionally create a partial snapshot by selecting the source snapshot from which you would like to extract portions. Click on Advanced and use the tree-selection control to select the parts you want to break out.
- For instance, if I want only data flows 1 and 2:
- Click Save Partial Snapshot and then provide a useful name and description
Programmatic Partial Snapshots
You can also programmatically save partial snapshots by asking for the NA_Configuration of a specific entity. For instance, if we wanted all data flows (and nothing else), we would code this,
NA_Configuration config = server.GetConfiguration("/device/dfe");
config.SaveSnapshot("dfe", "just the data flows");Loading
Snapshots load asynchronously. When you request a load, you pass in arguments and receive a status object that you can poll until it indicates completion. For a full snapshot, we call:
NA_LoadCommandStatus LoadSnapshot(string snapshot_name, NA_LoadStrategy strategy, bool apply_changes);The strategy will be one of,
- replace_complete_configuration – overwrite existing (full replace of the scope of the XML)
- replace_partial_configuration – overlay existing (append, no removals)
- Two advanced options exist that we won’t go into here
For apply_changes, pass true.
NA_LoadCommandStatus
When you receive this value from the LoadSnapshot call, you should poll the object to see when the load is complete and check for any extra actions that need to occur. For instance,
string message; // captures the current state as of the poll
while (!status.CommandIsComplete(out message))
{
// wait around - this polling could occur asynchronously
}
if (!status.AllChangesApplied())
{
// system requires restart
}