.. highlight:: bat .. index:: Common Attributes/Options .. _common_properties: Common Attributes/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 - url - 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 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 prefix is used to point to different sets of properties belonging to different environments. Please refer to :ref:`Managing Environment-Specific Properties/Variables ` for more details. .. list-table :: :widths: 15 15 70 8 :header-rows: 1 * - Property name - Attribute/Option - Description - Required * - | dp.env.prefix | dpEnvPrefix - env - Sets the ``environment prefix`` which is used to determine what properties to use. Once the prefix is set, DPBuddy will attempt to pre-pend this prefix to every requested property name and check if the prefixed property is defined. - 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 ``modifyConfig`` 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 - license - Location of the license file. - No