Backing Up the Configuration

The configuration interfaces allow you to work with parts or the whole configuration at any time. This is quite handy when it comes to backing up the system or migrating configuration from one environment to another.

Tip

Using a backup is a simple way to migrate the configuration from one environment to another.

Using the idsvr Command

The easy way to dump and restore the configuration is using the idsvr command. To do this, login to the machine where the admin node is running, and execute this command:

Listing 380 Dumping the running configuration database as XML
$ idsvr --dump-config

This will output the entire running configuration on standard out.

Using the idsh Command

You can create a backup using the idsh command as well. This can be done in operational and configuration mode. In operational mode (the default mode after starting the shell), a complete back-up can be made using a command such as this:

$ idsh
$ admin@localhost> show configuration | display xml | save /tmp/backup.xml
$ exit

Alternatively, this an done without user invention using just this command: idsh -s <<< "show configuration | display xml | save /tmp/backup.xml".

Using the Web UI

A backup can also be made using the admin UI. To do this, login in the UI and click Download from the changes menu:

../_images/download-config.png

Fig. 202 Downloading configuration from the admin UI

If there are pending changes and Download is selected from this menu, then you will be asked if the running configuration should be downloaded or if the pending configuration (which may or may not be valid) should be downloaded.

../_images/download-pending-config-modal.png

Using the RESTCONF API

The configuration is hierarchically structured under the top node in the configuration tree. In the REST interface, this is represented under:

/admin/api/restconf/data

The scheme, host, and port are the same as the admin UI (https://localhost:6749 by default).

To make a complete configuration backup, simply make a GET request on that endpoint. Basic authentication should used; the username and password are the same other management interfaces, like the UI. An example of fetching the entire non-operational data using curl and saving the result in a file is shown in Listing 381:

Listing 381 Backing up all configuration using curl
$ curl -s -u admin:Password1 "https://localhost:6749/admin/api/restconf/data?depth=unbounded&content=config" > backup.xml

It is also possible to backup subsystems by simply targeting a sub-path in the URI as shown in the following example:

$ curl -s -u "admin:Password1" \
    "https://localhost:6749/admin/api/restconf/data/profiles/profile=authentication,authentication-service?depth=unbounded&content=config" \
    > backup.xml

Using the Old REST API

The old REST API is accessible from /admin/api/rest. To download the entire running configuration using this management interface, a request such as the following can be used:

GET /admin/api/running

Get the currently running configuration

Example request

GET /api/running?deep&operations=false HTTP/1.1
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Host: localhost

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.yang.datastore+xml

<data>
    <environments xmlns="https://curity.se/ns/conf/base">
        <environment>
          <name>DefaultName</name>
          <services>
            <zones>
              <default-zone>
                <authentication-service>
                ...
Query Parameters:
 
  • deep – Optional flag indicating that the entire configuration tree should be returned from the requested location (e.g., the root) down.
  • operations – Optional Boolean flag indicating that operational data (e.g., uptime) should be included in the response or not. By default, it is.
Request Headers:
 
  • Accept – The content type that is acceptable. The values should be */*, application/vnd.yang.data+json, or application/vnd.yang.data+xml.
  • Authorization – required HTTP basic authentication header

Restoring a Saved Configuration

Instead of replacing the running configuration with the initial factory settings, a server can be reloaded with an entire new configuration. This can be done using any of the management interfaces described above (except the Web UI). Each is described below.

Using the idsvr Command

The idsvr command supports a flag, --load-config or -l, that replaces the running configuration with that of a backup file.

$ idsvr --load-config backup.xml

Warning

Using the --load-config flag will replace the current configuration with the contents of the given file. Also, it will not update the files in $IDSVR_HOME/etc/init; instead, it will update the running configuration database.

Using the old REST API

It is also possible to restore the entire configuration remotely using the REST API. It has this API:

PUT /admin/api/rest/running

Example request

PUT /admin/api/rest/running?force-put HTTP/1.1
Host: localhost
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Content-Type: application/vnd.yang.datastore+xml

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.yang.datastore+xml
Query Parameters:
 
  • force-put – Required flag that indicates that the entire configuration should be replaced
Request Headers:
 
  • Content-Type – The content type of the data being put; the value must be application/vnd.yang.datastore+xml.
Status Codes:
  • 415 Unsupported Media Type – If the Content-Type header is omitted or does not contain the value application/vnd.yang.datastore+xml
  • 400 Bad Request – If the force-put query string parameter is not included in the request or the content of the request was invalid for some reason.
  • 401 Unauthorized – If the user name/password are not provided in the Authorization or are incorrect or some other type of authentication scheme is used besides basic.
  • 204 No Content – If the configuration was successfully restored.

Warning

If the configuration being restored changes the certificate, port or listening address of the admin node, the request may be closed before the client receives the entire response.

If you would like restore the configuration using the curl command (or the like), you would do so as follows:

$ curl -k \
    -X PUT \
    -u admin:Password1 \
    -H 'content-type: application/vnd.yang.datastore+xml' \
    -d @backup.xml \
    'https://localhost:6749/admin/api/rest/running?force-put'