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
- changePassword — Change a user password
- 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, backup file will include the MAS configuration. 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 or URL/restore?fullrestore=boolean or URL/restore?fullrestore=boolean&restoreMAS=boolean or 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. |
Changing a User Password
Request Format: URL/changePassword or URL/changePassword?newPassword=string or URL/changePassword?newPassword=string&targetLoginName=string
To change the password for the currently authenticated user or another user (requires Superadmin rights), use the changePassword parameter. The appliance accepts plain text passwords from the client and hashes them server-side before persisting them. Authentication and authorization are provided by your active REST session.
Parameters are accepted from both the POST body (form-data) and URL query parameters. Form-data takes priority when both are supplied. It is highly recommended to use the POST body format to keep passwords secure and out of server access logs.
Sample Commands:
Preferred Method: POST body (password is not logged by the server)
curl -i -b cookies.txt -X POST "$REST/changePassword" -d "newPassword=yournewpassword"
or (Legacy via query parameters):
curl -i -b cookies.txt -X POST "$REST/changePassword?newPassword=yournewpassword"
or (Changing the password of another user account as a Superadmin):
curl -i -b cookies.txt -X POST "$REST/changePassword" -d "newPassword=yournewpassword&targetLoginName=targetusername"
Request Parameters:
| Parameter | Type | Description |
|---|---|---|
| newPassword | String | The new password for the account. Supplying this in the POST body is preferred to prevent it from being logged. Default: None |
| targetLoginName | String | The login name of the target user to be modified. If omitted, the engine changes the authenticated user's own password. Modifying another user requires full Superadmin rights. Default: None |
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"