.. highlight:: bat .. index:: Executing DPBuddy's Commands against Multiple Devices/Domains .. _multi_device: Support for Multiple Devices ============================ Any DPBuddy command can be executed against multiple devices and/or domains. This is done by specifying a comma-delimited list of :ref:`environment names ` 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 environment names to update multiple domains within the same device (or across multiple devices). This can be done by defining `HOCON variables `_ or hierarchical property prefixes: .. 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 names: .. 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 settings as part of any attribute/option. DPBuddy resolves variables right before the task/command is executed for each environment name (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 checkOld certain DataPower ports: .. code-block:: xml "fw.port" can be defined in multiple environments, e.g., "dev.fw.port", "test.fw.port". When you run this task with the "dev, test" 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 settings 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. .. _multiDomains: Multi-Domain Execution ---------------------- Many DPBuddy commands support ``domainPatterns`` (``domains``) option accepting a comma-separated list of domain regexps. If multiple domains are specified, the command will be serially executed against all the domains, one by one: .. code-block:: bash # import sslSettings.xml into all domains for the default environment dpbuddy import -file sslSettings.xml -domains ".*" The ``default`` domain is excluded by default. To apply the command to the default domain, explicitly add it to the list: .. code-block:: bash dpbuddy import -file sslSettings.xml -domains ".*, default" The list of commands supporting this option includes ``assertStatus``, ``updateConfig``, ``import``, ``copy``, ``deleteMutlipleFiles``, ``delConfig``, ``save``, ``quiesce``. .. _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