.. highlight:: xml
.. index:: download

.. _download:

``download``
------------

This task downloads files from the device to the local file system.

The task downloads all files that matched the provided regexp pattern.  Unless the ``flatten`` attribute is set to ``true``, the task will recreate the remote directories containing the files locally. Empty directories will not be created.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - cleanToDir
     - If set to ``true``, remove all files and subdirectories in ``toDir`` prior to downloading the files.

       Defaults to ``false``.
     - No
   * - createHostDir
     - If set to ``true``, create subdirectory under 'toDir' with the name matching DataPower host name. If the files are downloaded from the "default" domain, the domain subdirectories will be created automatically. This is convenient when ``download`` runs against multiple DataPower instances.
       Defaults to ``false``.
     - No
   * - downloadIfChanged
     - If set to ``true``, download only the files that are newer on DataPower than the ones that exist locally.

       Defaults to ``false``.
     - No
   * - dryRun
     - If set to ``true``, print the files that will be downloaded without downloading anything.

       Defaults to ``false``.
     - No
   * - flatten
     - If set to ``true``, download all files into ``toDir`` instead of creating the directory tree replicating remote directory structure.

       Defaults to ``false``.
     - No
   * - include
     - Regular expression pattern defining what files to download.

       The match is done against the entire path of a file, including the filesystem (e.g., ``local:/.*``). Note that the filesystem is separated by a single slash, i.e., the pattern ``local://.*xsd`` will not match anything.
     - Yes
   * - matchRequired
     - If set to ``true``, fail if no files matched the ``include`` pattern.

       Defaults to ``true``.
     - No
   * - preserveTimestamp
     - If set to ``true``, preserve the modified timestamp of the downloaded file.

       Defaults to ``true``.
     - No
   * - toDir
     - Local directory where to save the files.
     - Yes

Examples
^^^^^^^^

Download all "\*.xsd" files from "local:/":

.. code-block:: bat

   dpbuddy download -include "local:/.*xsd" -toDir download
   dpbuddy download -domain default -include "logtemp:/.*-log" -toDir logs -downloadIfChanged


.. code-block:: xml

   <dp:download include="local:/.*xsd" toDir="download"/>

You can find more examples under ``samples`` in your distribution or `online <http://myarch.com/dpbuddy-examples-files/>`_.