Backup destinations
-------------------

.. index:: backup;backup list
.. index:: backup;backup add
.. index:: backup;backup default
.. index:: cluster;cluster run

Backups can be made to the local file system or a remote destination.
Off-site (non-local) backups are recommended to reduce the risk of
the loss of information.

* Display available backup destinations with **backup list**.
* Add a new backup destination with **backup add <location-name> <URI>**.  

  See :ref:`network-uri-specification`.

Local backups are stored on a separate backup volume and the ``localbackup``
destination is pre-configured. 

* Display the list of localbackups with **backup list localbackup**,
  for example:

  ::

     $ backup list localbackup
        localbackup:
           URI: file:///backups
           Backups:
              2016-06-21 13:33
              2016-06-21 13:16

If the backup volume is too small, it can be increased - see: :ref:`backup-size-considerations`.
If the ``localbackup`` destination is removed or renamed, an ISO file upgrade will 
no longer function. Therefore, it is imperative that this destination is not removed.

Example:

:: 
   
   backup add myserverbackup sftp://user:password@server/path

Azure example:

::
   
   backup add myserverbackup sftp://<storage_account_name>.<sftp_local_user>[:password]@<storage_account_name>/path

* ``<storage_acct_name>`` is set up on Azure. The name of the Storage Account.
* ``<sftp_local_user>`` is set up on Azure if you enable SFTP and add a local user within the Storage Account settings.

.. note::

   During Azure host key rotation, in order to allow for a smooth transition when the rotation occurs,
   both the existing and new key should be available as trusted hosts. This can be carried out and verified 
   with the ``keys add <host>``, ``keys send <user>@<host>`` and ``keys show`` commands. See: :ref:`SSH_key_management`.



Backups to sftp can require either:

* ssh key-based authentication to be setup.
  Refer to :ref:`SSH_key_management` for further details.
  If you select ssh key-based authentication that was set up
  without a password, you will be prompted to input the password.

  ::

    platform@VOSS-UN-6:~$ backup add remote sftp://dan@182.59.31.201/sftp
    No password found. Do you want to use sshkeys? [y/N]: y


  .. important::
  
     If the username or password contains any of the following characters:
  
     ::
  
        ;|\\$&`!
  
     then use the backup setup command interactively by choosing "No"  at the prompts
     if SSH Keys are being used and then add the username and password directly.
* Non ssh key-based: ``Do you want to use sshkeys? [y/N]: n``

  Username needs to match the regex:
  
  ::
          
     [A-Za-z0-9_%%\-\.]+    

  If your username contains a backslash ``\``, the character needs to be escaped and URL-encoded,
  for example:  ``VOSS\backup`` needs to be entered as ``VOSS%5C%5Cbackup``.

If a common remote backup point is to be used by all nodes in the
cluster, the backup destination needs to be added to each node.  This can be
automated by using cluster remote execution, for example:

:: 
   
   cluster run all backup add myserverbackup sftp://user:password@server/path

The creation of scheduled backups of all nodes is done for failover reasons. 

.. note::

   In a multinode configuration, while only the highest priority secondary node backup contains data,
   in a failover scenario, the new primary node will contain the restored backup data.