Table of Contents
psarestore -f <dumpfile> [-L] [-t] -m <ip_map_file> -s <shells_map_file> [-c <clients_map_file>] [--clients-logins=<client-logins-file> | --domains-names=<domain-names-file>] [-V {conf | dump} | --vhosts-dir={conf | dump}] [--restore-bu-cert] [--force]
psarestore --version
psarestore -h
The argument -f serves for specifying the dump-file. The psarestore utility uses this file to read the configuration information and server content data when restoring the Plesk server.
The -f argument is a required argument.
There are three options available:
<dumpfile> = /fullpath/filename - you can specify the exact name of the dump-file
For example, execute psarestore -f /root/psa_backup/my_psa_backup_file to restore the Plesk server based on the configuration and content information stored in the file /root/psa_backup/my_psa_backup_file
<dumpfile> = - - you can specify stdin as the dump-file. This can be very useful if you are executing the distributed backup/restore (backing up Plesk at one machine and restoring it at another machine) or if you are restoring from the chunked dump-file.
For example, execute cat dump.* | ./psarestore -f - to direct the listing of the files of format dump.* as the input for psarestore.
For examples and instructions on distributed backup/restore see chapter Distributed backup and restore.
To restore a backup file stored on an FTP server, use the command ./psarestore -f ftp://<login>:<password>@<server>/<dump_file_path>
Usually, there can be found no two identical servers for restoring Plesk. The mapping mechanism serves for associating various entities between the backed up server and the restored server. The example of this is mapping the IP addresses: the set of available IP addresses at the restored server may differ from the like set at the backed up server, some of the IP addresses could be used on domains at the backed up server. In order to have such domains restored properly and functional, one needs to ‘map’ the corresponding IP addresses so that when Plesk is restored, the appropriate IP addresses are substituted in place of the ones, used at the backed up server. The psarestore utility allows mapping of the IP addresses, shells and client accounts.
The -m and -s arguments, responsible for mapping the IP addresses and shells, are required arguments. Note that the further examples may not contain some of them, this is only done so as not to overload the perception of the important information with the details.
The most important aspects of mapping IP addresses are:
The type and belonging to a specific client's IP pool are significant. This must be taken into account when mapping IP addresses
Each separate IP address should only be mapped to a separate IP address
The types of the source IP address and destination IP address must coincide if the new IP address already exists in the system
The accounts of clients - owners of the source IP address and destination IP address - must coincide if the new IP address belongs to some client's IP pool
To have psarestore map the IP addresses, use the -m argument. The corresponding file of mapped IP addresses must contain the set of strings that describe how to map the IP addresses.
If a client, whose account was backed up and is being restored, has domains using certain IP addresses, these addresses are required to be mapped. Otherwise Plesk will not be restored.
For example, execute psarestore -f /root/psa_backup/my_psa_backup_file -m /root/psa_backup/my_ip_map_file to restore the Plesk server mapping the IP addresses according to the instructions contained in the file /root/psa_backup/my_ip_map_file. See chapter Configuration file examples section IP mapping file for an example of the IP addresses mapping file.
When restoring at a non-clean Plesk installation there may appear the IP address collisions if an already used IP address appears in the IP address mapping file. Such situations can be resolved by either removing the troublemaking strings from the IP address mapping file or by modifying the conflicting IP address.
To have psarestore map the shells, use the -s argument. The corresponding file of mapped shells must contain the set of strings that describe how to map the shells.
For example, execute psarestore -f /root/psa_backup/my_psa_backup_file -s /root/psa_backup/my_shells_map_file to restore the Plesk server mapping the shells according to the instructions contained in the file /root/psa_backup/my_ip_map_file. See chapter Configuration file examples section Shell mapping file for an example of the shells mapping file.
This may come useful when restoring at a non-clean Plesk installation. It may happen so that the client accounts you are trying to restore already “exist” at the Plesk server. Such client collision means that a client with such login name or personal name already exists. Situations like this can be resolved either by mapping client accounts or by ignoring the colliding client accounts.
To have psarestore map the client accounts, use the -c argument. The corresponding file of mapped clients must contain the set of strings that describe how to map the client accounts.
For example, execute psarestore -f /root/psa_backup/my_psa_backup_file -c /root/psa_backup/my_clients_map_file to restore the Plesk server mapping the client accounts according to the instructions contained in the file /root/psa_backup/my_clients_map_file. See chapter Configuration file examples section Client mapping file for an example of the client accounts mapping file.
Should none of the arguments be supplied and collisions encountered, psarestore will warn you of the fact and exit, generating a default client account mapping file named clients.rej. This file will contain the list of clients you need to map to avoid collisions. What you will need to do is to edit this file, providing where necessary new login names and/or personal names. After that you will have to try executing psarestore again specifying this file as the client account mapping file.
If a client account in the dump file and a client account that already exists at the server, where the restore is executed, have the same login name and personal name, the two such accounts are considered the same and the data are merged.
If the limits of the latter account cannot be observed at the restore, the restore fails. In this case, you may want to restore this account separately, by mapping it.
If only the login name or only the personal name is the same, this situation is considered a collision and the restore will not be performed.
You can choose to restore only the data associated with certain clients, or certain domains. The psarestore utility allows you to supply the list of clients or domains for executing the selective restore of data.
To specify the client accounts you wish to restore use the --clients-logins argument. The corresponding file of client logins must contain the logins of the clients, whose account data you wish to restore, one login per line, no other separators.
For example, execute psarestore -f /root/psa_backup/my_psa_backup_file --clients-logins=/root/psa_backup/my_client_logins_file to restore only the data belonging to the client accounts listed in the file /root/psa_backup/my_client_logins_file. See chapter Configuration file examples section Client logins file for an example of the client logins file.
To specify the domains you wish to restore use the --domains-names argument. The corresponding file of domain names must contain the logins of the domains that you wish to restore, one domain name per line, no other separators.
For example, execute psarestore -f /root/psa_backup/my_psa_backup_file --domains-names=/root/psa_backup/my_domain_names_file to restore only the content of the domains listed in the file /root/psa_backup/my_domain_names_file. See chapter Configuration file examples section Domain names file for an example of the domain names file.
During the domains restoring process the respective client accounts, these domains are related to, will be also restored.
The psarestore utility allows specifying the location for placing the restored virtual hosts directory at the moment of performing the restore operation. You can choose to either use the location specified in the /etc/psa/psa.conf of the server, at which the restore is being performed, or the location used at the backed up server.
To restore the virtual hosts directory at the location specified in the psa.conf file of the server, at which the restore is being performed, use the -V conf argument.
To restore the virtual hosts directory at the location used at the backed up server use the -V dump argument.
If the virtual hosts directory locations are not the same, the virtual hosts directory of the server, at which the restore is performed, will be relocated according to the information stored in the dump-file.
If you specify neither of these options the psarestore utility will request whether you agree to place the virtual hosts directory in the location specified in the dump-file.
When restoring at a non-clean Plesk installation it is impossible to restore the virtual hosts directory at a location other than the one specified in the psa.conf file of the server, at which the restore is being performed. All the virtual hosts will be restored in the virtual hosts directory of that server.
The backup/restore utilities are installed along with a special certificate, which is then used to sign the data backed up through the Plesk control panel by various users. This is done in order to ensure the security of the saved data.
See the Plesk 7.5 Reloaded User's Manual chapter Managing Domains for details on performing backup and restore of data through the Plesk control panel.
In order to enable users restore their data through the control panel at the restored server from the dumps they made before the full system backup, you should retrieve the previous certificate from the system dump. This can be done with the help of the --restore-bu-cert argument.
If this action is not taken, the user data saved and signed by the previous certificate will be considered invalid and will not be restored.
To restore the server configuration, such as action log preferences, server's SSL certificate, mail server preferences, DNS templates, Spamassassin preferences, etc., use the --restore-server option.
To restore administrator's profile and control panel preferences, such as skin, custom buttons, logo, locale, etc., use the --restore-admin option.
Use the --force argument to use default options when requested by the utility.
To run psarestore in the test mode use the -t argument. The actual restore will not be performed but should any errors or collisions appear, you will be notified of them. This is a very useful means of setting up the restore process. It allows you to make necessary modifications in the mapping files before committing the restore.
If you are restoring accounts of clients who used a specific language that is not currently supported by your Plesk (the respective language pack is not installed), employing the -L <language_code> option will allow to restore such client accounts associating it with any other supported language that you specify. To view a list of language packs currently installed in your Plesk, you may use the -L list option. The language code is a four letter notation that is comprised of hyphenated two-letter lower-case language code (ISO 639) and two-letter upper-case country code (ISO 3166), for example, en-US.
To view the version of the Backup/Restore Utilities, execute psarestore with the --version argument.
Executing psarestore with -h will display a brief help to remind you of the available options.
The non-clean Plesk installation is the situation when the restore process is performed at the Plesk server, which is already in use, i.e. it has been configured and there are client accounts, domains, etc. created and functioning. This situation is very delicate and therefore requires a special mentioning.
Two consequent psarestore runs even with the very same dump-file are always considered two completely independent restore attempts with completely different backup information.
The server settings and the Administrator information of the non-clean Plesk server are not changed in the process of restore.
All the restored client accounts and domains are considered different from those at the non-clean Plesk server a priori. This can result in encountering collisions.
Collisions in client accounts - these can be resolved in any of the two ways: by either mapping the colliding client accounts to other accounts or by ignoring the colliding client accounts. See section Mapping client accounts for detailed instructions.
Collisions in IP addresses - these can also be resolved by adjusting the IP address mapping. See section Mapping IP addresses for detailed instructions.
Collisions in domains, hosting accounts, web users, etc. - should such a collision occur, the corresponding object and all of the dependent objects will not be restored. For example, if there is a collision when restoring a domain, the domain itself as well as all of its databases, web users, protected directories, hosting accounts, etc. will not be restored.
Use the argument -t to run psarestore in the test mode to make sure the backed up information can be restored completely and without any complications.
The situations of restoring selected client accounts and domains are handled absolutely the same as they are for the clean Plesk installation.
It is impossible to restore selected domains for the client, whose account already exists at the server. You may have to either restore such domains under a different client using mapping mechanism or remove the existing client account and restore it from the dump, in which case, all the existing client’s data will be lost.
No settings in psa.conf file can be changed in the process of restoring at a non-clean installation. This file is used in the ‘read only’ mode. This fact especially influences the process of restoring the virtual hosts directories. In this situation the restored virtual hosts are always placed at the location used by the server, at which the restore is being performed (the one specified in psa.conf).
Plesk allows clients and domain administrators to individually back up particular domain's data from the control panel. In order to ensure security of the system such dump-files are digitally signed. This prevents illegal modification of the dump-file contents and thus protects the system from possible misuses.
The digitally signed user backups can be restored through the control panel only at the same server. This is due to the fact that a key, which is used for signing, is generated when the backup/restore utilities are installed on the server. User dump-files can be restored on different servers only by administrator using the command line tools.
See the Plesk 7.5 Reloaded User's Manual for instructions on creating and restoring domain data from the control panel.
The administrator can restore any dump-file at any server.
When a dump-file is restored by the admin the digital signature is not verified. Restoring "insecure" dump-files can cause system security breaches.
The following options are to be used with the psarestore utility in order to restore a user's backup:
--single-domain-mode - this option specifies that a user backup (as opposed to regular server backup) is being restored, user's dump-file contains data of a single domain
--domain-name - the name of the domain where the data from the dump-file will be restored
Presently the name of the domain stored in the dump-file and the value of this parameter must be the same.
--domain-ip - the IP address at which the domain from the dump-file will be restored
The IP address must be available in the client IP pool
--client-login - the login of the client for whom the domain from the client dump-file will be restored
If a domain with the same name already exists, either the data will be merged or the dump-file will not be restored due to some irresoluble collisions
For example, execute psarestore -f /root/psa_backup/client_backup --single-domain-mode --domain-name=client.domain.com --domain-ip=1.2.3.4 --clien-login=client to restore a domain named 'client.domain.com' from the client dump-file /root/psa_backup/client_backup for the client with login name 'client' at the IP address '1.2.3.4'.