Working with configurations and settings
Using the REST interface, you can work with the configurations that were created for Web Gateway individual appliances and appliance clusters. You can also work with the settings for the filter modules on the appliances.
Identifying configurations and settings
When working with configuration and settings, you must identify them in the commands to complete particular activities.
The cfgID parameter serves as an identifier. Its value is usually the name of a file that contains an xml representation of a configuration or settings, for example, com.scur.engine.coaching.configuration.
You can look up the identifiers in the feed that you receive when retrieving a configuration or settings. In the entries of the feed, identifiers are tagged differently for configurations and settings.
- Identifier for a configuration — Last string of the section tagged as <id> in an entry, immediately following the /cfg/ section.
For example, com.scur.engine.cmclusternode.configuration is the identifier for a cluster configuration in this entry:
<entry><id>7284F2DE-BE26-0CC9-E825-000000468CBE/cfg/com.scur.engine.cmclusternode .configuration</id><title>Central Management</title><type>com.scur.engine.cmclusternode</ type> <link href="http://localhost:4711/Konfigurator/REST/appliances/7284F2DE-BE26-0CC9 -E825-000000468CBE/configuration/com.scur.engine.cmclusternode.configuration" rel="self"/></entry>
The <title> section serves as an alternative identifier. In the above example, com.scur.engine.cmclusternode also identifies the cluster configuration.
- Identifier for settings — Tagged as <id> in an entry.
For example, com.scur.mainaction.block.11376 is an identifier for settings in this entry:
<entry><id>com.scur.mainaction.block.11376</id><title>Unknown Certificate Authorities</title><type>com.scur.mainaction.block</type><link href="http://localhost:4711 Konfigurator/REST/setting/com.scur.mainaction.block.11376" rel="self"/></entry>
The filter module that the settings belong to is tagged as <title>.
In this example, the com.scur.mainaction.block.11376 settings are configured for the module that filters unknown certificate authorities.
Retrieving a configuration or settings
Request formats
<URL>/appliances/<UUID>/configuration
<URL>/appliances/<UUID>/configuration?page=<int>&pageSize=<int>
<URL>/appliances/<UUID>/configuration?type=<string>&name=<string>
<URL>/appliances/<UUID>/configuration?type=<string>&name=<string>&page=<int>&pageSize=<int>
<URL>/cluster/configuration
<URL>/cluster/configuration?type=<string>&name=<string>&page=<int>&pageSize=<int>
<URL>/setting
<URL>/setting?type=<string>&name=<string>
You can retrieve these configurations and settings:
- Configuration for an appliance that is connected to the appliance where you are currently working
- Configuration for a cluster of appliances including the appliance where you are currently working
- Settings of the appliance where you are currently working
You can also retrieve configurations and settings for filter modules. You can retrieve all configurations and settings that exist for a module or only particular configurations and settings.
The response to this request is a feed with the configuration or settings in xml format. You can request a particular page of the feed and specify the page size.
Sample commands
Retrieve the configuration of an appliance:
curl -i -b cookies.txt -X GET "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC /configuration"
Retrieve a cluster configuration:
curl -i -b cookies.txt -X GET "$REST/cluster/configuration"
Retrieve the settings of the appliance where you are currently working:
curl -i -b cookies.txt -X GET "$REST/setting"
Retrieve all settings that exist for a filter:
curl -i -b cookies.txt -X GET "$REST/setting?type=com.scur.engine.antivirus"
Retrieve particular filter settings:
curl -i -b cookies.txt -X GET "$REST /setting?type=com.scur.engine.antivirus&name=Gateway%20Anti-Malware"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an appliance Default: None |
| page | Integer | Number of a page in a feed with a configuration or settings Default: 1 |
| pageSize | Integer | Size of a page in a feed Default: –1 |
| type | String | Name of a filter module on an appliance, for example, com.scur.engine.antivirus You can look up the names of the filter modules in the feed that you receive when retrieving a configuration or settings. In this feed, filter names are tagged as <type>. Default: None |
| name | String |
Name of particular settings for a filter module Default: None Spaces in the settings names must be filled with %20, for example, Gateway |
Retrieving an xml representation
Request formats
<URL>/appliances/<UUID>/configuration/<cfgID>
<URL>/cluster/configuration/<cfgID>
<URL>/setting/<cfgID>
You can retrieve a file in xml format that has been created on a Web Gateway appliance to represent a configuration or settings.
When retrieving an xml representation, you use an identifying string, also known as cfgID, to identify a configuration or settings.
The response to this request includes the xml representation in the response body.
Sample commands
Retrieve the xml representation of a configuration for an appliance:
curl -i -b cookies.txt -X GET "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC /configuration/com.scur.engine.coaching.configuration"
Retrieve the xml representation of a cluster configuration:
curl -i -b cookies.txt -X GET "$REST/cluster/configuration /com.scur.cm_cluster_global.internal.configuration"
Retrieve the xml representation of the settings for the appliance where you are currently working:
curl -i -b cookies.txt -X GET "$REST/setting/com.scur.mainaction.block.11376"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an appliance Default: None |
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
Modifying a configuration or settings
Request formats
<URL>/appliances/<UUID>/configuration/<cfgID>
<URL>/cluster/configuration/<cfgID>
<URL>/setting/<cfgID>
You can modify a configuration or settings by applying changes to the file that contains an xml representation of them.
When specifying the changes, you provide the name of the file that is to be changed and the name of the file that contains the changes. You must also specify a Content-Type header.
After specifying the changes, you must commit them using a separate command. The response to this request includes the modified configuration or settings in the response body.
Sample commands
Modify the xml representation of a configuration for an appliance:
curl -i -b cookies.txt -H "Content-Type: application/xml" -d @changesToModifyConfiguration.xml -X PUT "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC /configuration/com.scur.engine.coaching.configuration"
Modify the xml representation of a cluster configuration:
curl -i -b cookies.txt -X PUT -d @changesToModifyClusterConfiguration.xml -H "Content-Type: application/xml" "$REST/cluster/configuration /com.scur.cm_cluster_global.internal.configuration"
Modify the xml representation of the settings for the appliance where you are currently working:
curl -i -b cookies.txt -H "Content-Type: application/xml" -d @changesToModifySettings.xml -X PUT "$REST/setting/com.scur.mainaction.block.11376"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an appliance Default: None |
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
Retrieving a list of properties
Request formats
<URL>/appliances/<UUID>/configuration/<cfgID>/property
<URL>/appliances/<UUID>/configuration/<cfgID>/property?page=<int>&pageSize=<int>
<URL>/cluster/configuration/<cfgID>/property
<URL>/cluster/configuration/<cfgID>/property?page=<int>&pageSize=<int>
<URL>/setting/<cfgID>/property
<URL>/setting/<cfgID>/property?page=<int>&pageSize=<int>
You can retrieve a list with the properties of a configuration or settings.
When retrieving this list, you provide the name of the file with the xml representation that includes the properties.
The response to this request is a feed that includes the list in xml format. You can retrieve a particular page of this feed and specify the page size.
Sample commands
Retrieve a list of the properties in the configuration for an appliance:
curl -i -b cookies.txt -X GET "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC /configuration/com.scur.engine.coaching.configuration/property"
Retrieve a list of the properties in a cluster configuration:
curl -i -b cookies.txt -X GET "$REST/cluster/configuration /com.scur.cm_cluster_global.internal.configuration/property"
Retrieve a list of the properties in the settings of the appliance where you are currently working:
curl -i -b cookies.txt -X GET "$REST/setting/com.scur.mainaction.block.11376/property"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an appliance Default: None |
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
| page | Integer | Number of a page in a feed for a configuration or settings Default: 1 |
| pageSize | Integer | Size of a page in a feed Default: -1 |
Retrieving a property
Request formats
<URL>/appliances/<UUID>/configuration/<cfgID>/property/<propertyname>
<URL>/cluster/configuration/<cfgID>/property/<propertyname>
<URL>/setting/<cfgID>/property/<propertyname>
You can retrieve a property from a configuration or settings.
When retrieving this property, you provide its name and the name of the file with the xml representation that includes the property.
The response to this request includes the property in xml format.
Sample commands
Retrieve a property from a configuration for an appliance:
curl -i -b cookies.txt -X GET "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC /configuration/com.scur.engine.coaching.configuration/property/sendsync"
Retrieve a property from a cluster configuration:
curl -i -b cookies.txt -X GET "$REST/cluster/configuration /com.scur.cm_cluster_global.internal.configuration/property/ DataUsageStatementVersionAccepted"
Retrieve a property from the settings of the appliance where you are currently working:
curl -i -b cookies.txt -X GET "$REST/setting/com.scur.mainaction.block.11376/property /TemplateName"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an appliance Default: None |
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
| propertyname | String | Name of a property in a configuration or settings Default: None |
Modifying a property value
Request formats
<URL>/appliances/<UUID>/configuration/<cfgID>/property/<propertyname>
<URL>/cluster/configuration/<cfgID>/property/<propertyname>
<URL>/setting/<cfgID>/property/<propertyname>
You can modify the value of a property in a configuration or settings.
When modifying this value, you provide the name of the file with the property that has its value changed and the name of the file with the new value. You must also specify a Content-Type header.
After modifying the value, you must commit this change using a separate command.
The response to this request includes the modified property value in xml format.
Sample commands
Modify the value of a property in a configuration for an appliance:
curl -i -b cookies.txt -H "Content-Type: application/xml" -d @changesToModifyProperty.xml -X PUT "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC/configuration /com.scur.engine.coaching.configuration/property/sendsync"
Modify the value of a property in a cluster configuration:
curl -i -b cookies.txt -H "Content-Type: application/xml" -d @changesToModifyProperty.xml -X PUT "$REST/cluster/configuration/com.scur.cm_cluster_global.internal.configuration /property/DataUsageStatementVersionAccepted"
Modify the value of a property in the settings of the appliance where you are currently working:
curl -i -b cookies.txt -H "Content-Type: application/xml" -d @changesToModifyProperty.xml -X PUT "$REST/setting/com.scur.mainaction.block.11376/property/TemplateName"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an appliance Default: None |
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
| propertyname | String | Name of a property in a configuration or settings Default: None |
Retrieving the default value of a property
Request formats
<URL>/appliances/<UUID>/configuration/<cfgID>/property/<propertyname>/default
<URL>/cluster/configuration/<cfgID>/property/<propertyname>/default
<URL>/setting/<cfgID>/property/<propertyname>/default
You can retrieve the default value of a property from a configuration or settings.
When retrieving this value, you provide the property name and the name of the file with the xml representation that includes the property.
The response to this request includes the default value in xml format.
Sample commands
Retrieve the default value of an individual property in a configuration for an individual appliance.
curl -i -b cookies.txt -X GET "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC/ configuration /com.scur.engine.coaching.configuration/property/sendsync/default"
Retrieve the default value of a property in a cluster configuration.
curl -i -b cookies.txt -X GET "$REST/cluster/configuration /com.scur.cm_cluster_global.internal.configuration/property/DataUsageStatementVersionAccepted /default"
Retrieve the default value of a property in the settings of the appliance where you are currently working.
curl -i -b cookies.txt -X GET "$REST/setting/com.scur.mainaction.block.11376/property /TemplateName/default"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an appliance Default: None |
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
| propertyname | String | Name of a property in a configuration or settings Default: None |
Setting a property to its default value
Request formats
<URL>/appliances/<UUID>/configuration/<cfgID>/property/<propertyname>/default
<URL>/cluster/configuration/<cfgID>/property/<propertyname>/default
<URL>/setting/<cfgID>/property/<propertyname>/default
You can set a property to its default value in a configuration or settings.
When setting this value, you provide the property name and the name of the file with the xml representation that includes the property.
The response to this request includes the property set to its default value in xml format.
Sample commands
Set a property to its default value in a configuration for an appliance:
curl -i -b cookies.txt -X POST "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC /configuration/com.scur.engine.coaching.configuration/property/sendsync/default"
Set a property to its default value in a cluster configuration:
curl -i -b cookies.txt -X POST "$REST/cluster/configuration /com.scur.cm_cluster_global.internal.configuration /property/DataUsageStatementVersionAccepted/default"
Set a property to its default value in the settings of the appliance where you are currently working:
curl -i -b cookies.txt -X POST "$REST/setting/com.scur.mainaction.block.11376/property /TemplateName/default"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an appliance Default: None |
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
| propertyname | String | Name of a property in a configuration or settings Default: None |
Retrieving a list with the actions of a configuration
Request format
<URL>/appliances/<UUID>/configuration/<cfgID>/action
You can retrieve a list with the actions that are executed according to the rules of a configuration for an appliance.
When retrieving this list, you provide the name of the file with the xml representation that includes the actions.
The response to this request is a feed that includes the list in xml format.
Sample command
Retrieve a list with the actions in a configuration for an appliance:
curl -i -b cookies.txt -X GET "$REST/appliances/7284F2DE-BE26-0CC9-E825-0000004A637C /configuration/com.scur.engine.cmclusternode.configuration/action"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an individual appliance |
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
Triggering an action
Request format
<URL>/appliances/<UUID>/configuration/<cfgID>/action/actionname
You can trigger an action that is included in a configuration for an appliance.
When triggering this action, you provide its name and the name of the file with the xml representation that includes the action.
Sample command
Trigger an action in a configuration for an appliance:
curl -i -b cookies.txt -X POST "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC /configuration/com.scur.engine.cmclusternode/action/update_engines_all_standalone
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| UUID | String | Universally unique identifier for an individual appliance |
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
| actionname | String | Name of an action that is included in the xml representation of a configuration or settings Default: None |
Deleting settings
Request format
<URL>/setting/<cfgID>
You can delete settings for the appliance where you are currently working.
When deleting these settings, you provide the name of the file with the xml representation that includes these settings.
After deleting the settings, you must commit this change using a separate command.
The response to this request includes the deleted settings in xml format.
Sample command
Delete settings for the appliance where you are currently working:
curl -i -b cookies.txt -X DELETE "$REST/setting/com.scur.mainaction.block.11376"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| cfgID | String | String used as an identifier for a configuration or settings This string is usually the name of a file that contains an xml representation of the configuration or settings, for example, com.scur.engine.coaching.configuration. Default: None |
Adding settings with content
Request format
<URL>/setting?type=<string>&name=<string>
You can add new settings for a filter module on the appliance where you are currently working.
When adding these settings, you provide the names of the filter module and the settings.
You must also specify a Content-Type header and append a file in xml format that provides the content of the settings.
After adding the settings, you must commit this change using a separate command.
The response to this request includes the added settings in xml format.
Sample command
Add new settings for a filter module on the appliance where you are currently working:
curl -i -b cookies.txt -H "Content-Type: application/xml" -d @newSettingwithoutNameAndType.xml -X POST "$REST/setting?type=com.scur.mainaction.block&name=Malware%20Detected"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| type | String | Name of a filter module on an appliance, for example, com.scur.engine.antivirus You can look up the names of the filter modules in the feed that you receive when retrieving a configuration or settings. In this feed, filter names are tagged as <type>. Default: None |
| name | String |
Name of new settings that are added for a filter module. Spaces in the settings names must be filled with %20, for example, Gateway%20New Default: None |
Adding settings with content including type and name
Request format
<URL>/setting
You can add new settings for a filter module on the appliance where you are currently working with the names of the filter module and the settings already included in the settings content.
When adding settings in this way, you do not provide the names of the filter module and the settings as request parameters. You specify a Content-Type header and append a file in xml format that provides the content of the settings.
After adding the settings, you must commit this change using a separate command.
The response to this request includes the added filter settings in xml format.
Sample command
Add new settings for a filter module on the appliance where you are currently working with content including the filter and settings names:
curl -i -b cookies.txt -H "Content-Type: application/xml" -d @newSettingWithNameAndType.xml -X POST "$REST/setting"
Variable request parameters
None
Adding new default settings
Request format
<URL>/setting?type=<string>&name=<string>
You can add new settings for a filter module on the appliance where you are currently working with default values configured for all settings options.
When adding these settings, you provide the name of the filter module and a name for the new default settings.
After adding the settings, you must commit this change using a separate command.
The response to this request includes the new settings with their default values in xml format.
Sample command
Add new settings with default values for a filter module on the appliance where you are currently working:
curl -i -b cookies.txt -X POST "$REST /setting?type=com.scur.mainaction.block&name=New%20Blocking"
Variable request parameters
| Parameter | Type | Description |
|---|---|---|
| type | String | Name of a filter module on an appliance, for example, com.scur.engine.antivirus You can look up the names of the filter modules in the feed that you receive when retrieving a configuration or settings. In this feed, filter names are tagged as <type>. Default: None |
| name | String |
Name of new settings that are added for a filter module. Spaces in the settings names must be filled with %20, for example, Gateway%20New Default: None |
Sample script for working with configurations and settings
The following bash script modifies the value of a property in a configuration for an appliance.
Before performing this operation, the script sets a URL variable for accessing the REST interface.
Some of the operations performed with configurations and settings require running still another command to commit a change that you requested, for example, modifying a property value. When a commit is required, this is mentioned in the description of the operation.
#!/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" ## Modify property value curl -i -b cookies.txt -H "Content-Type: application/xml" -d @changesToModifyProperty.xml -X PUT "$REST/appliances/081EEDBC-7978-4611-9B96-CB388EEFC4BC/configuration /com.scur.engine.coaching.configuration/property/sendsync" ## Commit modification curl -b cookies.txt -X POST "$REST/commit" ## Log off curl -b cookies.txt -X POST "$REST/logout"