Skip to main content

Check out Interactive Visual Stories to gain hands-on experience with the SSE product features. Click here.

Skyhigh Security

Performing basic REST operations

When working with the REST interface, you can perform several basic operations such as logging on and off, committing changes, and creating a configuration backup.

Use a POST request for these operations and specify each operation by a parameter that you add to the URL of the request.

For example, this is a request to log off from the REST interface on an appliance, using a curl command:

When a sample command or script with commands is shown in this documentation, a command can extend over two or more lines. When working with the REST interface, you must enter any command completely within a single line.

 curl -i -b cookies.txt -X POST "$REST/logout"

Parameters for basic REST operations include:

  • login — Log on
  • logout — Log off
  • heartbeat — Keep a session alive
  • commit — Commit changes
  • discard — Discard changes
  • backup — Back up the configuration
  • restore — Restore the configuration
  • updateEngines — Update the filter engines 
 Logging on

Request format: URL/login?userName=<user name>&pass=<password>

To log on to the REST interface on an appliance, use the login parameter. Within the request, you also submit your credentials for authentication. If authentication is successful, the response to the logon request provides a session ID.

Sample command: curl -i -X POST "$REST/login?userName=myusername&pass=mypassword"

 Request parameters:

Parameter Type Description
userName String User name submitted for authenticating to the REST interface
Default: None
pass String Password submitted for authenticating to the REST interface
Default: None
Logging off

Request format: URL/logout

To log off from the REST interface on an appliance, use the logout parameter. Logging off deletes the session information and discards the changes made in a session that have not been committed.

Sample command: curl -i -X POST "$REST/logout"

Request parameters: None 

Keeping a session alive

Request format: URL/heartbeat

Using the heartbeat parameter in a request keeps the current session alive.

Sample command: curl -i -b cookies.txt -X POST "$REST/heartbeat"

 Request parameters: None

Committing changes

Request format: URL/commit

To commit changes that have been made to items such as system files, log files, and lists on an appliance, use the commit parameter.

Sample command: curl -i -b cookies.txt -X POST "$REST/commit"

Request parameters: None

Discarding changes

Request format: URL/discard

To discard changes that have been made to items such as system files, log files, and lists on an appliance, use the discard parameter.

Sample command: curl -i -b cookies.txt -X POST "$REST/discard"

Request parameters: None

Backing up the configuration

Request format: URL/backup or URL/backup?password=string or URL/backup?backUpMAS=boolean&password=string

To create a configuration backup for the appliance where you are currently working, use the backup parameter. When backing up or restoring a configuration, no response header is required as part of the output, so the -i option is not included in the command for performing the request.

The configuration backup is stored in the file that is specified as output in the command.

Sample commands:

curl -b cookies.txt -X POST "$REST/backup" -o filename.backup
or:
curl -b cookies.txt -X POST "$REST/backup?password=yourpassword" -o filename.backup
or:
curl -b cookies.txt -X POST "$REST/backup?backUpMAS=true&password=yourpassword" -o
filename.backup

Request parameters:

Parameter Type Description
backUpMAS Boolean If true, a password is used to encrypt the backup.
Default: false
password String Password used to encrypt the backup.
If no password is specified, the backup is not encrypted.
Default: None
Restoring the configuration

Request format: URL/restore?fullrestore=boolean&restoreMAS=boolean&password=string

To restore the configuration of the appliance you are currently working on, use the restore parameter. You must also specify a Content-Type header for the type of the backup file.

Sample command: curl -b cookies.txt --data-binary @filename.backup -X POST "$REST/restore" -H "Content-Type: text/plain;charset=UTF-8"

 Request parameters:

Parameter Type Description
fullrestore Boolean If true, a configuration is restored completely. If false, only the policy is restored,
omitting the system settings for an appliance.
Default: false
restoreMAS Boolean If true, MAS is also restored if available.
Default: false
password String Password used to decrypt the backup.
If no password is specified, the backup is not decrypted.
Updating the filter engines

Request format: URL/updateEngines

To perform an update of the filter engines on an appliance with data that is provided offline, use the updateEngines parameter. You must also specify a Content-Type header for the type of the update file.

Sample command: curl -b cookies.txt --data-binary @mwg7-linux-mix-small.upd -X POST "$REST/updateEngines"-H "Content-Type: text/plain;charset=UTF-8"

Request parameters: None

Sample script for performing basic REST operations

The following bash script performs several basic operations: logging on and authenticating to the REST interface on an appliance, creating a backup file, and logging off again.

Before these operations are performed, the script sets a URL variable for accessing the REST interface.

#!/bin/bash
## Set URL variable for accessing REST interface
REST=http://localhost:4711/Konfigurator/REST
## Log on and authenticate
curl -i -c cookies.txt -X POST "$REST/login?userName=myUserName&pass=myPassword"
## Create backup file
curl -b cookies.txt -X POST "$REST/backup" -o filename.backup
## Log off again
curl -b cookies.txt -X POST "$REST/logout"

 

  • Was this article helpful?