.. highlight:: bat .. index:: Common Attributes/Options .. _common_properties: Common Options and Properties ============================= There are a number of attributes/options that are common to all DPBuddy tasks/commands. Any common attribute/option has a corresponding property that can be used to specify a default value in the configuration file or in a build file. This keeps you from having to repeat the same attribute for every task. A value from the attribute/option overrides a value from the property. For example, ``dp.domain=test`` property can be overridden using the ``domain="test1"`` attribute set at a task level. Every common property has two aliases, one using dots as a word separator (following Ant naming conventions) and the second one using lower camel case. The second alias should be used when running DPBuddy from Groovy or Gradle (or any other scripting language) since Ant naming conventions conflict with the commonly used dot notation for accessing object properties. .. _connection_options: DataPower Connection Attributes/Options --------------------------------------- DPBuddy needs to know the URL of the SOAP interface (XML Management interface) and a user name and a password in order to be able to connect to a device. Following is the list of common connection properties/attributes: .. list-table:: :widths: 15 15 70 8 :header-rows: 1 * - Property name - Attribute/Option - Description - Required * - | dp.url | dpUrl | dp.host | dpHost - | url | host - URL of the SOAP interface (XML Management interface). The path defaults to ``/service/mgmt/current``, which always corresponds to the most up-to-date DataPower schema. If the port is not specified, DPBuddy will attempt to use the port 5550. You can specify just the host name of the appliance, in which case DPBuddy will default to "https:" and the default port. - Yes * - | dp.username | dpUsername - | user | CLI alias: ``-u`` - Valid username with administrative privileges. - Yes * - | dp.password | dpPassword - | password | CLI alias: ``-p`` - Password. - Yes * - | dp.domain | dpDomain - domain - Target domain for DPBuddy tasks. - Yes * - | dp.trust.all.certs | dpTrustAllCerts - trustAllCerts - If this property/option is set to ``true`` DPBuddy will ignore SSL certificates' validation errors when connecting to a device. If this property is not set, or set to ``false``, you will need to add the DataPower certificate to your JDK's keystore. You can obtain the DataPower certificate from the browser when you access Web GUI. Defaults to ``true``. - No .. _environment_options: Environment Attributes/Options ------------------------------ Environment name is used to point to different sets of properties belonging to different environments. Please refer to :ref:`managing_env_vars` for more details. .. list-table:: :widths: 15 15 70 8 :header-rows: 1 * - Property name - Attribute/Option - Description - Required * - | dp.env | dpEnv | dp.device | dpDevice - | env | device - Sets the environment name which is used to determine what properties to use. - No * - | DPBUDDY_CONFIG environment variable - | configFile | CLI: confFile - Path to the :ref:`config file `. - No .. _multi_env_options: Attributes/Options for Running Commands against Multiple Devices ---------------------------------------------------------------- Any DPBuddy command can be executed against multiple devices and/or domains. This is done by providing a comma-delimited list of environment names using "env" option/attribute or "dp.env" property. Please refer to :ref:`multi_device` for more details. .. list-table:: :widths: 15 15 70 8 :header-rows: 1 * - Property name - Attribute/Option - Description - Required * - | dp.continue.on.error | dpContinueOnError - continueOnError - If this property/option is set to ``true``, DPBuddy will attempt to execute the command against all of the devices in the list regardless of errors with other devices. Defaults to ``false``. - No * - - rollbackAllOnError - If this option is set to ``true`` DPBuddy will rollback all the devices where the command succeeded if one or multiple devices failed. Note that in order for the rollback to work, the affected domains must have a checkpoint defined. DPBuddy always rolls backs to the latest checkpoint. Defaults to ``false``. - No .. _schema_options: Schema Validation Attributes/Options ------------------------------------ DPBuddy can optionally validate SOMA XML requests against the DataPower SOMA XML schema. Several DPBuddy tasks, such as ``action``, ``request`` and ``modify`` allow the user to specify free-form XML as part of the request. DataPower itself validates all XML requests, but for security reasons, it does not return validation errors to the client. Instead, it returns the "internal error" message, which is not very helpful for troubleshooting. Validation errors can then be found in the device's logs, but scanning the logs takes time. DPBuddy, on the other hand, validates XML on the client so that validation error messages are displayed right away The following DPBuddy properties and attributes control schema validation: .. list-table:: :widths: 15 15 70 8 :header-rows: 1 * - Property name - Attribute/Option - Description - Required * - | dp.validate | dpValidate - validate - If set to ``true`` validate all XML SOMA requests. Note that enabling this setting globally (using ``dp.validate`` property) will result in slower performance for ``import`` and some other tasks. Defaults to ``false`` except for the tasks ``modifyConfig`` and ``somaRequest``. - No * - | dp.schema | dpSchema - schemaFile - Full path to "xml-mgmt-ops.xsd" or the directory containing all DataPower schema files. DataPower schema files can be downloaded from the "store" filesystem of the device. The schema files include "xml-mgmt-ops.xsd", "xml-mgmt.xsd", "xml-mgmt-base.xsd" and, starting with firmware version 6, "xml-mgmt-b2b.xsd". DPBuddy comes bundled with the schema files for 6.0.1 firmware. When schema validation is enabled, DPBuddy will default to this schema. You may want to download the schemas from your device and specify the ``dp.schema`` property if you have a different firmware version. - No Examples ^^^^^^^^ .. code-block:: bat dp.validate=true dp.schema=./schemas .. _save_option: ``Save`` Attribute/Option ------------------------- DPBuddy is capable of automatically saving domain configuration after a change. This is equivalent to clicking "Save Config" in WebGUI. Most of DPBuddy's configuration changing tasks support the ``save`` attribute/option. If this attribute is set to ``true``, the configuration will be saved after successful completion of the task. You can also enforce auto-saving globally by setting the ``dp.auto.save`` property. If this property is set, all the configuration-changing tasks will save domain configuration upon completion. The ``save`` attribute/option takes the precedence over ``dp.auto.save`` property. The ``save`` attribute and ``dp.auto.save`` property are supported by the following tasks: ``import``, ``modifyConfig``, ``delConfig``, ``resetDomain``, ``assertStatus``, ``assertState``, ``action``, ``somaRequest``, ``checkpoint`` and ``rollback``. You must explicitly invoke the save :ref:`save task ` task to persist domain configuration if ``dp.auto.save`` or ``save`` attribute are not set or are set to ``false``. .. list-table:: :widths: 15 15 70 8 :header-rows: 1 * - Property name - Attribute/Option - Description - Required * - | dp.auto.save | dpAutoSave - save - If set to ``true``, saves the domain configuration. Defaults to ``false``. - No .. _license_option: License File Attribute/Option ----------------------------- Please see the :ref:`DPBuddy License section ` for more information about the license file. This setting can be ignored if you're using a trial version of DPBuddy. .. list-table:: :widths: 15 15 70 8 :header-rows: 1 * - Property name - Attribute/Option - Description - Required * - | dpbuddy.license.file | dpbuddyLicenseFile | DPBUDDY_LICENSE_FILE environment variable - license - Location of the license file. - No