Usage Via GeoServer’s REST API

The Backup and Restore REST api consists of a few resources meant to used in an asynchronous fashion:

Resource Method Parameters and Notes
/rest/br/backup/ POST Post a JSON/XML document with the backup parameters, see below
/rest/br/backup/backupId GET Returns a json/xml representation of the backup operation. See below
/rest/br/backup/backupId DELETE Cancels the backup operation
/rest/br/restore POST Post a JSON/XML document with the restore parameters, see below
/rest/br/restore/restoreId GET Returns a json/xml representation of the backup operation, see below
/rest/br/restore/restoreId DELETE Cancels the restore operation

Usage Example

We are going to use the command line tool cURL to send HTTP REST requests to GeoServer.

The /rest/br/backup/ and /rest/br/restore endpoints accept an optional format suffix that allows the Backup / Restore archive to be streamed to / from the client instead of being written on / read from the file system.

Initiate a Backup

Prepare a file containing with a JSON object representing the Backup procedure configuration.

backup_post.json

{
   "backup":{
      "archiveFile":"/home/sg/BackupAndRestore/test_rest_1.zip",
      "overwrite":true,
      "options":{
      }
   }
}

In this case we did not specify any options in the backup configuration so default values will be used.

Available options are:

  1. BK_BEST_EFFORT: Skip any failing resources and proceed with the backup procedure

Also an optional Filter can be passed to restrict the scope of the restore operation to a list of workspaces.

For example

{
   "backup":{
      "archiveFile":"/home/sg/BackupAndRestore/test_rest_1.zip",
"overwrite":true,
      "options":{
        "option": ["BK_BEST_EFFORT=true"]
      },
"filter": "name IN ('topp','geosolutions-it')"
   }
}

Backup procedure will be initiated.

Here is a sample response

HTTP/1.1 201 Created
Date: Mon, 01 Aug 2016 14:35:44 GMT
Location: http://mygeoserver/geoserver/rest/br/backup/1
Server: Noelios-Restlet-Engine/1.0..8
Content-Type: application/json
Transfer-Encoding: chunked

{
   "backup":{
      "totalNumberOfSteps":9,
      "execution":{
         "id":1,
         "version":1,
         "stepExecutions":{
            "@class":"java.util.concurrent.CopyOnWriteArraySet"
         },
         "status":[
            "STARTED"
         ],
         "startTime":"2016-08-01 14:35:44.802 UTC",
         "createTime":"2016-08-01 14:35:44.798 UTC",
         "lastUpdated":"2016-08-01 14:35:44.803 UTC",
         "exitStatus":{
            "exitCode":"UNKNOWN",
            "exitDescription":""
         },
         "progress":"1\/9"
      },
      "options":{
         "@class":"synchList",
         "option":[
            "OVERWRITE=true"
         ]
      },
      "warningsList":{
         "@class":"synchList"
      },
      "archiveFile":{
         "@class":"resource",
         "$":"\/home\/sg\/BackupAndRestore\/test_rest_1.zip"
      },
      "overwrite":true
   }
}

At the end of the backup procedure you’ll be able to download the generated archive to your local file system by making an HTTP GET request to the same endpoint, using the backup ID as above and adding the .zip at the end

curl -u "admin:geoserver" -i -X GET  "http://mygeoserver/geoserver/rest/br/backup/1.zip" -o 1.zip
../../_images/usagerest001.png

Query status of Backup executions

Status of the operation can be queried making an HTTP GET request to the location listed in the response,

http://mygeoserver/geoserver/rest/br/backup/$ID.{json/xml}

Replace $ID with the ID of the backup operation you’d like to inspect.

curl -u "admin:geoserver" http://mygeoserver/geoserver/rest/br/backup/1.json

or

curl -u "admin:geoserver" http://mygeoserver/geoserver/rest/br/backup/1.xml

GeoServer will respond with the status of the backup job corresponding to that ID

../../_images/usagerest002.png
../../_images/usagerest003.png

Here you are able to see the status of all the steps involved in the backup procedure with creation time, start time, end time, exit status etc.

Cancel a Backup

Cancel an in progress Backup by sending an HTTP DELETE request with the ID of the task

curl -v -XDELETE -u "admin:geoserver" http://mygeoserver/geoserver/rest/br/backup/$ID

Replace $ID with the ID of the backup operation you’d like to cancel.

Initiate a Restore

Prepare a file with a JSON object representing the Restore procedure configuration

restore_post.json

{
   "restore":{
      "archiveFile":"/home/sg/BackupAndRestore/test_rest_1.zip",
      "options":{
      }
   }
}

In this case we did not specify any options in the restore configuration so default values will be used.

Available Options are:

  1. BK_DRY_RUN: Only test the archive do not persist the restored configuration
  2. BK_BEST_EFFORT: Skip any failing resources and proceed with the restore procedure

Also an optional Filter can be passed to restict the scope of the restore operation to a list of workspaces.

For example

{
   "restore":{
      "archiveFile":"/home/sg/BackupAndRestore/test_rest_1.zip",
      "options":{
        "option": ["BK_DRY_RUN=true"]
      },
"filter": "name IN ('topp','geosolutions-it')"
   }
}

If archiveFile is specified, the archive specified on that path of the remote file system will be used to initiate the restore procedure. Otherwise you’re the archive needs to be uploaded from your local system.

Then make a POST HTTP request to GeoServer’s REST interface endpoint for the restore procedure

curl -u "admin:geoserver" -i -H "Content-Type: application/json" -X POST --data @restore_post.json http://mygeoserver/geoserver/rest/br/restore/

Restore procedure will be initiated.

Here is a sample response

HTTP/1.1 201 Created
Date: Mon, 01 Aug 2016 15:07:29 GMT
Location: http://mygeoserver/geoserver/rest/br/restore/2
Server: Noelios-Restlet-Engine/1.0..8
Content-Type: application/json
Transfer-Encoding: chunked

{
   "restore":{
      "totalNumberOfSteps":9,
      "execution":{
         "id":2,
         "version":1,
         "stepExecutions":{
            "@class":"java.util.concurrent.CopyOnWriteArraySet"
         },
         "status":[
            "STARTED"
         ],
         "startTime":"2016-08-01 15:07:29.398 UTC",
         "createTime":"2016-08-01 15:07:29.393 UTC",
         "lastUpdated":"2016-08-01 15:07:29.398 UTC",
         "exitStatus":{
            "exitCode":"UNKNOWN",
            "exitDescription":""
         },
         "progress":"0\/9"
      },
      "options":{
         "@class":"synchList"
      },
      "warningsList":{
         "@class":"synchList"
      },
      "archiveFile":{
         "@class":"resource",
         "$":"\/home\/sg\/BackupAndRestore\/test_rest_1.zip"
      }
   }
}
../../_images/usagerest004.png

To upload the archive from our local system instead, omit the archiveFile parameter in the JSON object and pass the --upload-file parameter to cURL:

restore_post.json

{
   "restore":{
      "options":{
      },
   }
}
curl -u "admin:geoserver" -i -H "Content-Type: application/json" --upload-file "archive_to_restore.zip" -X POST --data @restore_post.json http://localhost:8081/geoserver/rest/br/restore/

Local archive_to_restore.zip archive will be uploaded and used by the restore procedure.

../../_images/usagerest005.png

Query for status of Restore operations

http://mygeoserver/geoser/restore/$ID.{json/xml}

{
   "restore":{
      "execution":{
         "hash":2,
         "key":{
            "@class":"long",
            "$":"2"
         },
         "val":{
            "@class":"restore",
            "totalNumberOfSteps":9,
            "execution":{
               "id":2,
               "version":2,
               "stepExecutions":{
                  "@class":"java.util.concurrent.CopyOnWriteArraySet",
                  "step":[
                     {
                        "name":"restoreNamespaceInfos",
                        "status":"COMPLETED",
                        "exitStatus":{
                           "exitCode":"COMPLETED",
                           "exitDescription":""
                        },
                        "startTime":"8\/1\/16 3:07 PM",
                        "endTime":"8\/1\/16 3:07 PM",
                        "lastUpdated":"8\/1\/16 3:07 PM",
                        "parameters":{
                           "input.file.path":"file:\/\/\/opt\/tomcat-geoserver-2.9.x\/temp\/tmpbbe2388a-f26d-4f26-a20f-88c653d88aec",
                           "time":1470064049392
                        },
                        "readCount":1,
                        "writeCount":1,
                        "failureExceptions":""
                     },
                    ...
                     {
                        "name":"restoreGeoServerSecurityManager",
                        "status":"COMPLETED",
                        "exitStatus":{
                           "exitCode":"COMPLETED",
                           "exitDescription":""
                        },
                        "startTime":"8\/1\/16 3:07 PM",
                        "endTime":"8\/1\/16 3:07 PM",
                        "lastUpdated":"8\/1\/16 3:07 PM",
                        "parameters":{
                           "input.file.path":"file:\/\/\/opt\/tomcat-geoserver-2.9.x\/temp\/tmpbbe2388a-f26d-4f26-a20f-88c653d88aec",
                           "time":1470064049392
                        },
                        "readCount":0,
                        "writeCount":0,
                        "failureExceptions":""
                     }
                  ]
               },
               "status":"COMPLETED",
               "startTime":"2016-08-01 15:07:29.398 UTC",
               "createTime":"2016-08-01 15:07:29.393 UTC",
               "endTime":"2016-08-01 15:07:30.356 UTC",
               "lastUpdated":"2016-08-01 15:07:30.772 UTC",
               "exitStatus":{
                  "exitCode":"COMPLETED",
                  "exitDescription":""
               },
               "progress":"9\/9"
            },
            "options":{
               "@class":"synchList"
            },
            "warningsList":{
               "@class":"synchList"
            },
            "archiveFile":{
               "@class":"resource",
               "$":"\/home\/sg\/BackupAndRestore\/test_rest_1.zip"
            }
         }
      }
    ...

Here you are able to see the status of all the steps involved in the restore procedure with creation time, start time, end time, exit status etc.

Cancel a Restore

Cancel an in progress Restore by sending an HTTP DELETE request:

curl -v -XDELETE -u "admin:geoserver" http://mygeoserver/geoserver/rest/br/restore/$ID

Replace $ID with the ID of the restore operation you’d like to cancel.