.. highlight:: xml .. index:: updateConfig .. _updateConfig: ``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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 ^^^^^^^^ .. code-block:: bash # 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: ``disable``/``enable`` ---------------------- These commands allow for quickly disabling or enabling DataPower objects. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 ^^^^^^^^ .. code-block:: bash # Disable a web proxy dpbuddy disable -objects ",WSG.*:test-proxy" # Enable all XML firewalls and web proxies dpbuddy enable -objects "XMLFire.*,WSG.*" .. _modifyConfig: ``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 :ref:`import`, you can use DataPower export facility or DPBuddy's :ref:`export` task to produce an initial version of the configuration file. Also similar to ``import``, the configuration can be transformed using DPBuddy's :ref:`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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 :ref:`transform`. 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: .. code-block:: xml ${server.name} 1 0 0 disable