.. _backup-import-to-new-environment:

Backup and import to a new environment 
--------------------------------------

.. index:: backup;backup add
.. index:: backup;backup create
.. index:: system;system id

The steps below show how to backup and import to a new environment.

1. Export:

   a. On the source system, create a remote backup location,
      for example location name ``sftpbackup``:
   
      **backup add sftpbackup <URI>**
      
      For example: 
      
      ::
      
         backup add sftpbackup sftp://sftpusr:sftpw@172.29.41.107/home/sftp

      If a directory is specified in the <URI>, this will be created during the backup.
      Backups to sftp require ssh key-based authentication to be set up.
      Refer to :ref:`SSH_key_management` for further details.

      Alternatively, enter the password at the prompt, for example:

      ::

         $ backup add sftpbackup sftp://sftpusr:sftpw@172.29.41.107/home/sftp
         
          No password found. Do you want to use sshkeys? no
          What is the host ssh password? 
          
          <type password here>
          
          Location has been added


   b. Create a local backup:


      .. important::

         Backups should be created and restored in a ``tmux`` session - see: :ref:`tmux-command`.
   
      **backup create localbackup**

      In a multi-node configuration, the database backup will be created on the secondary node with the
      highest priority. Use **database config** to check the priority.
   c. List backups to get the date:
   
      **backup list**


      For example:

      ::

         $ backup list
          localbackup:
             URI: file:///backups
             Backups:
                1 backups have been created - most recently 2020-03-19 08:21
          sftpbackup:
             URI: sftp://sftpusr:********@172.29.41.107:home/sftp
             Backups:
                No backups created yet

   d. Export the local backup to the remote destination
      created by **backup add <remote_name>**. 
  
      * The system ID is appended as a directory to the backup ``<URI>`` destination path.
        This can be checked locally by running **system id**.

      * The backup file is called ``<hostname>_<timestamp>.tar.gz``. 

      Example output:
   
      ::
      
          platform@VOSS:~$ backup export localbackup sftpbackup 2020-04-02 11:34
          This operation could take a while if the backup is sizeable. Do you wish to continue? y
          Compressing backup files for date 2020-04-02 11:34
          Backup files successfully compressed to 202004021134.tar.gz
          Backup files successfully compressed to /backups/49940d3feaa39a6a9f36cb5ff533202157c3b77a/VOSS_202004021348.tar.gz
          platform@10.120.1.246's password:
          platform@10.120.1.246's password:
          Export successfully created at platform@10.120.1.246:media/49940d3feaa39a6a9f36cb5ff533202157c3b77a/VOSS_202004021348.tar.gz

         
2. Import:

   .. note::

      For large backup files that cannot be imported due to space limitations, see: :ref:`restore-backup-files-too-large`.

   a. From the SFTP server, **scp** the ``VOSS_202004021348.tar.gz`` file to the new box (for example, ``platform@172.29.21.97``).
      If the file on the SFTP server is in the directory ``/backups/49940d3feaa39a6a9f36cb5ff533202157c3b77a``, 
      change to the directory, then:

      ::

         $ ls

          VOSS_202004021348.tar.gz

         $ scp VOSS_202004021348.tar.gz platform@172.29.21.97:/opt/platform/admin/home/media/
   b. Import the file as a local backup, for example:
   
      ::
        
         $ backup import localbackup media/VOSS_202004021348.tar.gz
   c. Get the file timestamp of the imported backup with **backup list**
      and restore the backup, for example:
  
      .. important::

         Backups should be created and restored in a ``tmux`` session - see: :ref:`tmux-command`.


      ::
      
         $  backup restore localbackup 2020-04-02 15:41

.. _restore-backup-files-too-large:

Restoring backup files too large for import
.............................................

If a backup file is available and is too large to copy into the local system ``/home/media/`` directory,
the following procedure can be followed. (Available space on ``home/media`` can be checked using **diag disk**.)

1. On the system where the backup is to be restored, add the remote SFTP site, for example:

   ::

      backup add sftpbackup sftp://sftpusr:sftpw@172.29.41.107/home/sftp
      
2. Obtain the system UUID by running **system id**. It should look like this:

   ::
   
      49940d3feaa39a6a9f36cb5ff533202157c3b77a

3. Given an available backup file, e.g. ``VOSS_202004021348.tar.gz``, (with timestamp reference: ``2020-04-02 15:41``)
   this file can be extracted to the *remote* SFTP site configured above as follows:

   a. On the remote SFTP site, locate the sub-directory with the name of the UUID,
      for example

      ::

         /home/sftp/49940d3feaa39a6a9f36cb5ff533202157c3b77a

   #. Extract the backup file in this directory. Ensure that the extracted backup files
      are listed in the root of this directory (not all in a subdirectory).

4. On the system where the backup is to be restored, run the remote restore, for example:

   ::

      $  backup restore sftpbackup 2020-04-02 15:41