updateConfig

The updateConfig command updates the DataPower configuration based on the value of the “updates” option. The value is defined in HOCON format, e.g., “DoHostRewrite:on, Priority: normal, HTTPCompression: off”. The command can update multiple DataPower objects based on the provided regexp patterns.

This task can be used for quickly applying localized configuration changes to one or multiple DataPower devices with a single command. For example, it can be used for changing back-end URLs, changing ports and so on.

updateConfig will try to validate the request against the DataPower XML schema on the client (you can override this by setting the validate attribute to false). If the schema validation was turned off, the validation would still fail on the device and you would get the “Internal Error” message.

Attributes/Options

Attribute	Description	Required
objects	Comma-delimited list of regexp patterns to update in the format “class:name, class:name”. Class and name could be optional, e.g., “class, class” or “:name”.	No
exclude	Comma-delimited list of regexp patterns to exclude from the update in the format “class:name, class:name”.	No
updates	Elements to modify in HOCON format, e.g., “DoHostRewrite:on, Priority: normal, HTTPCompression: off”. Elements must match the DataPower schema, see the corresponding Modify type definition in xml-mgmt.xsd.	No
updateConfPath	Name (path) of the configuration object defined in dpbuddy.conf	No
domainPatterns CLI alias: domains	Comma-delimited list of regular expression patterns defining what domains to apply the command to. Use ‘.*’ for all domains except the default. Use ‘.*,default’ to include the default domain. Defaults to the current domain. The current domain is specified using the dpDomain property or domain attribute of the task.	No
dryRun	If set to true, do not update anything, just print the matched objects. Defaults to false.	No
matchObjects	At least one object must match provided object classes/names. Defaults to false.	No

Examples

# Various changes to the "test" XML firewall, including updating comments
dpbuddy updateConfig -objects "XMLFire.*:testFirewall" -updates 'DoHostRewrite:on, Priority: normal, HTTPCompression: off, UserSummary: "my change"'
# update the Web services proxy's back-end
dpbuddy updateConfig -objects WSEndpointRewritePolicy -updates  'WSEndpointRemoteRewriteRule:[{ServicePortMatchRegexp: "{http://personservice}PersonService$"}, {RemoteEndpointProtocol: http}, {RemoteEndpointHostname:foo1}, {RemoteEndpointPort:3040}, {RemoteEndpointURI:null},{RemoteMQQM:null},{RemoteTibcoEMS:null},{RemoteWebSphereJMS:null}]'

disable/enable

These commands allow for quickly disabling or enabling DataPower objects.

Attributes/Options

Attribute	Description	Required
objects	Comma-delimited list of regexp patterns to update in the format “class:name, class:name”. Class and name could be optional, e.g., “class, class” or “:name”.	No
exclude	Comma-delimited list of regexp patterns to exclude from the update in the format “class:name, class:name”.	No
domainPatterns CLI alias: domains	Comma-delimited list of regular expression patterns defining what domains to apply the command to. Use ‘.*’ for all domains except the default. Use ‘.*,default’ to include the default domain. Defaults to the current domain. The current domain is specified using the dpDomain property or domain attribute of the task.	No
matchObjects	At least one object must match provided object classes/names. Defaults to false.	No

Examples

# Disable a web proxy
dpbuddy disable -objects ",WSG.*:test-proxy"
# Enable all XML firewalls and web proxies
dpbuddy enable -objects "XMLFire.*,WSG.*"

modifyConfig

The modifyConfig task updates the DataPower configuration from the provided configuration file and/or the configuration information specified inline within the configuration tag. The configuration information contains DataPower object definitions in the format defined by the DataPower schema (xml-mgmt.xsd, “AnyConfigElement” type).

As with import, you can use DataPower export facility or DPBuddy’s export task to produce an initial version of the configuration file.

Also similar to import, the configuration can be transformed using DPBuddy’s transform actions.

Configuration can contain variables in any of its text nodes or attributes.

Unlike import, however, modifyConfig does not completely overwrite existing configuration objects. Instead, it updates nested elements of the configuration. For example, for a load balancer group (LBG), modifyConfig will update only the members included in the request. If an LBG member does not exist, modifyConfig will create it. It will not affect any other group members.

DataPower XML schema contains the following explanation for modifyConfig:

“Vectors with indexes (example: BaseWSDL in ModifyWSGateway) will be merged based on matching index values (example: WSDLSourceLocation for BaseWSDL). Vectors without indexes (example: DebugTrigger in ModifyConfigBase) and simple vectors (example: AcceptedConfig in ModifyConfigDeploymentPolicy) will have all their elements replaced with any new elements supplied via modifyConfig.”

You can use modifyConfig to dynamically change your configuration, for example, to disable LBG members if you need to shut down some back-end servers.

Please note that DataPower forces XML validation of “modifyConfig” requests (it does not do it for import). Unfortunately, in some cases, DataPower produces a non-compliant XML export, which causes validation to fail. Usually, removing the “Memoization”, “DebugMode” and “DebuggerType” elements is sufficient to let it pass. Also, all ports elements (e.g., “HealthPort” in “LBGroupMembers”) must have an integer value; you can enter “0” to default these values.

modifyConfig will try to validate the request against the DataPower XML schema on the client (you can override this by setting the validate attribute to false). If the schema validation was turned off, the validation would still fail on the device and you would get the “Internal Error” message.

Paying (i.e. non-trial) DPBuddy customers can contact DPBuddy support if they have questions or issues with defining their modifyConfig requests.

Attributes/Options

Attribute	Description	Required
file	Path to the configuration file. If the task contains transform element, the transformations will be applied to the content of the file. The file must be a valid DataPower configuration file. datapower-configuration must be the root element. All configuration objects must be enclosed inside the configuration element, which must be a child of datapower-configuration.	No
resolveVars	If set to true, attempts to resolve variables (${}) inside the configuration. DPBuddy will raise an exception if any variables/properties remain unresolved. Defaults to true.	No

transform Nested Element

transform contains transformation actions documented in Transforming DataPower Configuration. This element is optional.

fileset Nested Element

You can use the Ant fileset element to specify multiple config files that will be used to update DataPower configuration. DPBuddy will combine all matching files into a single request to the device. You can specify multiple fileset elements within the same task.

Each fileset could contain a nested transform element with the transformation actions. The actions will be applied to the files matched by this fileset. Note that the global transform specified as the child of the task will not be applied to the matching files.

configuration Nested Element

You can specify any valid DataPower configuration inside this element as an alternative to keeping the configuration in an external file. If the task contains transform element, the transformations will be applied to this configuration. The configuration’s text nodes and attributes can contain Ant variables.

Examples

The following example shows how to use modifyConfig to disable an LBG member:

<dp:modifyConfig>
    <configuration>
        <LoadBalancerGroup name="${lbg.name}">
            <LBGroupMembers>
                <Server>${server.name}</Server>
                <Weight>1</Weight>
                <MappedPort>0</MappedPort>
                <Activity/>
                <HealthPort>0</HealthPort>
                <LBMemberState>disable</LBMemberState>
            </LBGroupMembers>
        </LoadBalancerGroup>
    </configuration>
</dp:modifyConfig>