You can find our user documentation at docs.cpanel.net.

Check out our new API beta site!

Child pages
  • UAPI Functions - Backup::restore_files
Skip to end of metadata
Go to start of metadata

Description

This function restores an account's files.

Important:

In cPanel & WHM version 88 and later, when you disable the File Storage role, the system disables this function.

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Backup/restore_files?backup=/home/cpuser/backup_cpuser_9-10-2019.tar.gz&verbose=1&timeout-3600


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Restore the user's backup file.
$Backup_restore_database = $cpanel->uapi(
    'Backup', 'restore_files',
    array(
        'backup'    => '/home/cpuser/backup_cpuser_9-10-2019.tar.gz',
        'verbose'   => '1',
        'timeout'   => '3600',
    )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Restore the user's backup file.
my $Backup_restore_files = $cpliveapi->uapi(
    'Backup', 'restore_files',
    {
        'backup'   => '/home/cpuser/backup_cpuser_9-10-2019.tar.gz',
        'verbose'  => '1',
        'timeout'  => '3600',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 Command Line
uapi --user=username Backup restore_files backup=/home/cpuser/backup_cpuser_9-10-2019.tar.gz verbose=1 timeout=3600


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
   {
          "data" : {
             "log_id" : "2019-09-11T18:30:49Z.1",
             "log_path" : "/home/cpuser/.cpanel/logs/restorefiles/2019-09-11T18:30:49Z.1.log"
          },
          "status" : 1,
          "errors" : null,
          "messages" : [
             "Created the restore directory “/home/cpuser/point2”.",
             "No virus detected in upload “”.",
             "The system is extracting the archive “/home/cpuser/backup-cpuser.tld-9-10-2019_1.tar.gz”.",
             "The system successfully restored the directory “/home/cpuser/point2” from the backup file “backup-cpuser.tld-9-10-2019_1.tar.gz”."
          ],
          "warnings" : null,
          "metadata" : {}
       }


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
backup string

Required

The backup file to upload or restore. 

Important:

  • You can only restore backup files that already exist on the server.
  • To upload a backup file, you must pass this parameter in a multipart/form-data structure. For more information about this structure, read Mozilla's POST Method documentation.

Note:

To restore multiple backup files, increment the parameter name. For example: backup-1backup-2backup-3.

A valid backup filename.

For a complete list of backup filename formats, read our Transfer or Restore a cPanel Account documentation.

Note:

For cPanel & WHM version 86 and earlier, read our Restore a Full Backup/cpmove File documentation.

 Backup filename...

backup-cpuser.tld-9-10-2019_1.tar.gz

 Form/data structure...
------WebKitFormBoundaryvb6rQ3QyCo6yC2w5
Content-Disposition: form-data; name="backup-1"; backup="backup-cpuser.tld-9-10-2019_1.tar.gz"
Content-Type: application/x-gzip

------WebKitFormBoundaryvb6rQ3QyCo6yC2w5--
verbose Boolean

Whether to return additional information from the  /usr/local/cpanel/logs/cpbackup  log file.

This parameter defaults to 0.

  • 1 — Return.
  • 0  – Don't return.
1 
directory string

The directory to which to restore the file.

This parameter defaults to the user's /home directory.

The full directory path for a cPanel account./home/user/example

Returns

ReturnTypeDescriptionPossible valuesExample
log_idstring

The log file's restoration identification (ID). 

The system uses the backup restoration's date to create this ID.

The backup restoration date, in YYYY-MM-DDTHH:mm:SS.rev human-readable format, where:

  • YYYY-MM-DD  is the file's year, month, and date timestamp.
  • HH:mm:SS is the file's hour, minute, and seconds timestamp.
  • rev is the log's revision during the current backup restoration.

2019-08-13T15:10:07Z.1

log_pathstringThe log file where the system recorded the backup restoration.A valid absolute filepath.

/home/cptest/.cpanel/logs/restorefiles/2019-08-13T15:10:07Z.1.log

messagesarray of stringsAn array of statements about the database's restoration.An array of strings that describe the restoration's status. 


 Click to view...
The system successfully restored the directory “/home/cpuser/point2” from the backup file “backup-cpuser.tld-9-10-2019_1.tar.gz”