.. highlight:: bat .. index:: Executing DPBuddy's Commands against Multiple Devices/Domains .. _multi_device: Executing DPBuddy's Commands against Multiple Devices/Domains ============================================================= Any DPBuddy command can be executed against multiple devices and/or domains. This is done by specifying a comma-delimited list of :ref:`environment prefixes ` using the ``env`` option/attribute or the ``dp.env`` property, e.g.: .. code-block:: bat dpbuddy testConnection -env "dev,test" ant test.connection -Ddp.env="dev,test" DPBuddy executes a command against each of the devices listed, in order. You can also specify a device list using a property and then refer to this property using ``dp.env``/``env``. For example, you can define a property for multiple production devices: .. code-block:: bat all.prod.devices=prod1,prod2,prod3 You can then reference this property instead of the device list: .. code-block:: bat dpbuddy testConnection -env all.prod.devices This allows you to define a group of devices that are always updated together. You can also use the list of prefixes to update multiple domains within the same device (or across multiple devices). This can be done by defining hierarchical prefixes, as explained in :ref:`managing_env_vars`: .. code-block:: bat devtest.dp.username=dpbuddy devtest.dp.password=dpbuddy01 devtest.dp.url=devtest-dp devtest.dev.dp.domain=dev devtest.test.dp.domain=test To run a command against both the "dev" and "test" domains on the "devtest" device, specify the appropriate prefixes: .. code-block:: bat dpbuddy testConnection -env "devtest.dev, devtest.test" Or create a property with the pre-defined list: .. code-block:: bat devtest.all=devtest.dev, devtest.test And then use "devtest.all" as the value for ``-env``: .. code-block:: bat dpbuddy testConnection -env devtest.all You can use environment-specific properties/variables as part of any attribute/option. DPBuddy resolves the variables right before the task/command is executed for each environment prefix (as opposed to doing it once, when the Ant file loads). This allows for easy referencing of port numbers and other execution parameters. For example, you can define the following task to check certain DataPower ports: .. code-block:: xml "fw.port" can be defined with multiple prefixes, e.g., "dev.fw.port", "test.fw.port". When you run this task with the "dev, test" prefix list, DPBuddy will use the "dev" port for the first run and the "test" port for the second run. You can also use environment-specific properties/variables from the DPBuddy CLI. By default, DPBuddy will exit once a command fails on one of the devices. This behavior can be overridden using :ref:`"dp.continue.on.error" property or the "continueOnError" option/attribute `. 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 any errors with other devices. .. _multi_device_rollback: DPBuddy can also rollback all the devices for which the command succeeded, if one or multiple devices have failed. This function can be turned on by setting the "rollbackAllOnError" attribute/option. Note that in order for the rollback to work, the affected domains must have a defined checkpoint. DPBuddy always rolls back to the latest checkpoint. Note that only successful devices will be rolled back. Rollback for failed devices can be turned on by using a different attribute/option, "rollbackOnError". This option is supported by :ref:`import`, :ref:`copy`, :ref:`exec` and a few other commands which deal with updating the device configuration and files. .. _execTarget: ``execTarget`` -------------- ``execTarget`` performs the same function as the built-in `AntCall Ant task `_ in that it invokes another target in the same Ant project. It supports all the attributes of AntCall. In addition, it also handles multi-device execution. If multiple devices were specified using using the ``env`` attribute or the ``dp.env`` property, ``execTarget`` will execute the target specified by the ``target`` attribute once for each device. This allows for repeating the same sequence of targets for multiple devices. Note that you must use ``dp.env`` (or ``dpEnv``) property name with ``execTarget``, it does not support the ``dp.device`` alias. ``execTarget`` can rollback the domain if the invoked target or any of its dependent targets failed. ``execTarget`` supports all the common attributes listed in :ref:`multi_env_options`, such as ``env`` or ``continueOnError``. Examples ^^^^^^^^ Execute the ``_clean.deploy.domain`` target once for each device .. code-block:: xml