Child pages
  • WHM API 1 Functions - restoreaccount
Skip to end of metadata
Go to start of metadata

Description

This function restores an account backup. You can use this function to restore daily, weekly, or monthly backups.

Important:

On servers with a custom Whostmgr::Transfers module, the function may not return XML output. To properly return XML output, the Whostmgr::Transfers module must allow the system to use the Cpanel::Demultiplexer module to capture output.

Note:

In cPanel & WHM version 11.50 and earlier, this function returned data after the restoration process completed. However, we changed this behavior in version 11.52 so that the function reports that it found the backup file and will attempt to restore it. Then, the function performs the restoration asynchronously in the background. We made this change to resolve issues from restorations that ran for very long times or crashed before they completed.

If you use this function to restore legacy backups to accounts, use the get_transfer_session_state and fetch_transfer_session_log  functions to check the transfer session and log file to determine whether the restoration process completed successfully.

 


Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records. CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/restoreaccount?api.version=1&user=username&type=monthly&all=1
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/restoreaccount?api.version=1&user=username&type=monthly&all=1
 Command Line
whmapi1 restoreaccount user=username type=monthly all=1


Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{  
   "metadata":{  
      "result":1,
      "reason":"OK",
      "version":1,
      "command":"restoreaccount",
      "output":{  
         "raw":"Extracting tarball...................\nDone<br />\nExtracting Domain....Done<br />\nDone<br />\n<br /><br />Restoring cpanel user config fileDone<br />\n<br />Restoring reseller privs (if any)<br />Restoring Locale Setting<br />Restoring SSL keys and CertificatesDone<br />\n<br />Restoring frontpage (if installed)Done<br />\n<br />Restoring access logs....\nDone<br />\n<br /><br />Restoring domain keys....\nDone<br />\n<br /><br />Restoring DB MAP File....\nDone<br />\n<br /><br /><span class=\"b2\">Restoring PostgreSQL databases....</span>\nRestoring PostgreSQL privs<!--\n-->\nDone<br />\n<br />Restoring Mailman listsDone<br />\n<br />Restoring Mailman ArchivesDone<br />\n<br />Restoring shell<blockquote><pre>Current shell /bin/bash is up to date.\n</pre></blockquote>Done<br />\n<br />Restoring password<blockquote><pre></pre></blockquote>Done<br />\n<br />Restoring proftpd fileDone<br />\n<br />Resyncing FTP Passwords<blockquote><pre>Updating ftp passwords for userFtp password files updated.Ftp vhost passwords synced</pre></blockquote>Done<br />\n<br />Linking old home directories<br />Parsing Domain Databases...ParkedDomains......AddonDomains...<br />Restoring Domains<br />\n<br />Restoring Bandwidth DataDone\n<br />Restoring Counter Data<pre></pre><br />Restoring Homedir....<blockquote><pre></pre></blockquote>Done<br />\n<br />Doing fileprotect conversion<br />Restoring nobody owned filesDone<br />\n<br />Restoring Mail filesDone<br />\n<br />Restoring userdata....\nDone<br />\n<br /><br />Restoring custom virtualhost templates....\nConverting email to cPanel 5+ (if needed)<blockquote><pre></pre></blockquote>Done<br />\n<br />Cleaning up filters (if needed)<blockquote><pre>vfilter converter v3.0Updating vfilter files to latest format.Running for user only (force=0) (has_spam_acl=1)Processing user......Done</pre></blockquote>Done<br />\n<br />Fixing mail permissions<blockquote><pre></pre></blockquote>Done<br />\n<br />Restoring crontabDone<br />\nConverting to maildir if needed<blockquote><pre></pre></blockquote>Done<br />\nRestoring Dns Zones<blockquote><pre>Restoring zone: user.com.db\n</pre></blockquote><br />Adding missing subdomain DNS entries (if needed)<pre></pre><br />Update Proxy subomains<blockquote><pre>Adding proxy subdomains for domain example.com.Records Installed</pre></blockquote>Done<br />\n<br />Updating SPF Records<blockquote><pre></pre></blockquote>Done<br />\n<br />Restoring quota<blockquote><pre></pre></blockquote>Done<br />\n<br /><br />Update mail routing<blockquote><pre>LOCAL MAIL EXCHANGER: This server will serve as a primary mail exchanger for example.com's mail.: This configuration has been manually selected.\n</pre></blockquote>Done<br />\n<br />Rebuilding Apache Conf<br />Restore CompleteAccount Restore Complete\nUnlocking password for user user.passwd: Success.<br />"
      }
   }
}
 Output (XML)
<result>
   <metadata>
      <result>1</result>
      <reason>OK</reason>
      <version>1</version>
      <command>restoreaccount</command>
   <output>
      <raw>
         Extracting tarball...................
         Done<br />
         Extracting Domain....Done<br />
         Done<br />
         <br /><br />Restoring cpanel user config fileDone<br />
         <br />Restoring reseller privs (if any)<br />Restoring Locale Setting<br />Restoring SSL keys and CertificatesDone<br />
         <br />Restoring frontpage (if installed)Done<br />
         <br />Restoring access logs.... Done<br />
         <br /><br />Restoring domain keys.... Done<br />
         <br /><br />Restoring DB MAP File.... Done<br />
         <br /><br /><span class="b2">Restoring PostgreSQL databases....</span>
         Restoring PostgreSQL privs<!-- --> Done<br />
         <br />Restoring Mailman listsDone<br />
         <br />Restoring Mailman ArchivesDone<br />
         <br />Restoring shell<blockquote><pre>Current shell /bin/bash is up to date.
         </pre></blockquote>Done<br />
         <br />Restoring password<blockquote><pre></pre></blockquote>Done<br />
         <br />Restoring proftpd fileDone<br />
         <br />Resyncing FTP Passwords<blockquote><pre>Updating ftp passwords for userFtp password files updated.Ftp vhost passwords synced</pre></blockquote>Done<br />
         <br />Linking old home directories<br />Parsing Domain Databases...ParkedDomains......AddonDomains...<br />Restoring Domains<br />
         <br />Restoring Bandwidth DataDone
         <br />Restoring Counter Data<pre></pre><br />Restoring Homedir....<blockquote><pre></pre></blockquote>Done<br />
         <br />Doing fileprotect conversion<br />Restoring nobody owned filesDone<br />
         <br />Restoring Mail filesDone<br />
         <br />Restoring userdata.... Done<br />
         <br /><br />Restoring custom virtualhost templates.... Converting email to cPanel 5+ (if needed)<blockquote><pre></pre></blockquote>Done<br />
         <br />Cleaning up filters (if needed)<blockquote><pre>vfilter converter v3.0Updating vfilter files to latest format.Running for user only (force=0) (has_spam_acl=1)Processing user......Done</pre></blockquote>Done<br />
         <br />Fixing mail permissions<blockquote><pre></pre></blockquote>Done<br />
         <br />Restoring crontabDone<br />
         Converting to maildir if needed<blockquote><pre></pre></blockquote>Done<br />
         Restoring Dns Zones<blockquote><pre>Restoring zone: user.com.db
         </pre></blockquote><br />Adding missing subdomain DNS entries (if needed)<pre></pre><br />Update Proxy subomains<blockquote><pre>Adding proxy subdomains for domain example.com.Records Installed</pre></blockquote>Done<br />
         <br />Updating SPF Records<blockquote><pre></pre></blockquote>Done<br />
         <br />Restoring quota<blockquote><pre></pre></blockquote>Done<br />
         <br /><br />Update mail routing<blockquote><pre>LOCAL MAIL EXCHANGER: This server will serve as a primary mail exchanger for example.com's mail.: This configuration has been manually selected.
         </pre></blockquote>Done<br />
         <br />Rebuilding Apache Conf<br />Restore CompleteAccount Restore Complete
         Unlocking password for user user.passwd: Success.<br />
      </raw>
   </output>
   </metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

   

Parameters

Note:

You must include at least one of the all, mail, subs or mysql parameters when you call this function. 


ParameterTypeDescriptionPossible valuesExample
userstring

Required

The account's username.

A valid username.username
typestring

Required

The type of backup to restore.

The function restores the most recent backup of the type that you specify.

  • monthly
  • weekly
  • daily
monthly
allBoolean

Whether to create the account before restoration.

 

  • 1 — Create and then restore the account.

    Warning:

    If you select 1 and the account already exists, the function will fail. 

  • 0 — Restore only.
1
ipBooleanWhether to assign a dedicated IP address to the restored account.
  • 1 — Assign a dedicated IP address.
  • 0 — Use the shared IP address.
1
mailBoolean

Whether to restore account-level filters (vfilters) and forwarders (valiases).

  • 1 — Restore.
  • 0 — Do not restore.
1
mysqlBoolean

Whether to restore the account's MySQL® databases.

  • 1 — Restore.
  • 0 — Do not restore.
1
subBoolean

Whether to restore the account's subdomains.

  • 1 — Restore.
  • 0 — Do not restore.
1

 

Returns

This function only returns metadata.

Note:

The function's metadata includes a long output message that may contain HTML.