Editing the Hosting Description File

The hosting description file can be written in the YAML or JSON format, and contains the list of clients, subscriptions, addon domains, mailboxes, etc. to be transferred from the source server. You can find sample hosting description files here. This topic describes how to configure a number of commonly used parameters to ensure that the migration is successful.

Specifying the path to the web content data

To specify the path to the web content data, both on the source server and the destination server, use the following parameters in the subscriptions section:

  • source_webspace_root - The absolute path to the directory containing all files available to the customer on the source server. Can be specified on the subscription level only (e.g., /home/vhosts/example.com).
  • source_document_root - The absolute path to the directory containing only the files served via HTTP. Can be specified on the subscription, addon domain, or subdomain levels (e.g., /home/vhosts/example.com/httpdocs).
  • target_document_root - The directory that will contain the files served via HTTP on the destination server. The path is relative to subscription's root directory on the destination server. Can be specified on the subscription, addon domain, or subdomain levels (e.g., data/www. If the domain name is example.com, and the virtual hosts directory in Plesk is /var/www/vhosts, the absolute path to the document root directory on the destination will be /var/www/vhosts/example.com/data/www). If left unspecified, the Plesk default value will be used.

Note: If the configuration file does not contain the access information for the source server, the source_webspace_root and source_document_root paths will be treated as local on the destination server.

If you need to prevent specific directories or files from being migrated, use the exclude directive with the source_webspace_root and source_document_root parameters. For example:

subscriptions:
    -
        name: example.com
        source_webspace_root:           
                path: /home/vhosts/example.com
                exclude:
                    -
                        /bin
                    -   
                        /logs

The syntax for writing the exclude rules is identical to that used by the rsync tool. Refer to the rsync documentation - see the Include/Exclude Pattern Rules section for more information.

If you need to specify exactly in which directory on the destination server the web content from a specific directory on the source server will be placed, use web file mapping. For example:

subscriptions:
    -
        name: example.com
        target_document_root: data/www
        web_files:
            -
                source: /home/vhosts/example.com
                target: "{webspace_root}"
            -
                source: /home/vhosts/example.com/httpdocs
                target: "{document_root}"

The target directive is used to specify either an absolute path on the destination server, or a format string containing one or more template variables from one of the tables below.

Template variables and their meaning for subscription - i.e., when the web_files node is directly under a subscription node:

Template variable Details Applicable to

{anon_ftp_incoming}

Path to directory available for upload by anonymous FTP

Linux only

{anon_ftp_pub}

Path to directory available for reading by anonymous FTP

Linux only

{cgi_bin}

Path to cgi-bin directory of subscription

Unix only

{document_root}

Path to document root of subscription - directory available by HTTP

Linux and Windows

{logs}

Path to directory with logs (Apache access and error logs, etc)

Linux and Windows

{main_domain_private}

Private directory of main domain

Windows only

{main_domain_statistics}

Statistics directory of main domain (AWStats/Webalizer/etc)

Windows only

{protected_dirs}

Path to directory with settings of protected directories

Linux only

{ssl_document_root}

Path to secure document root of subscription - directory available by HTTPS

Windows only

{statistics}

Path to directory with statistics files (AWStats/Webalizer/etc)

Linux only

{webspace_idn}

Name of subscription encoded in punycode

Linux and Windows

{webspace_root}

Path to subscription root

Linux and Windows

{webspace}

Name of subscription

Linux and Windows

Template variables and their meaning for addon domains and subdomains - i.e., when the web_files node is under an addon domain or subdomain node:

Template variable Details Applicable to

{cgi_bin}

Path to cgi-bin directory of addon domain/subdomain

Linux only

{document_root}

Path to document root of addon domain/subdomain

Linux and Windows

{logs}

Path to directory with logs (Apache access and error logs, etc) of addon domain/subdomain

Linux only

{protected_dirs}

Path to directory with settings of protected directories of addon domain/subdomain

Linux only

{site_idn}

Name of addon domain/subdomain encoded in punycode

Linux and Windows

{site}

Name of addon domain/subdomain

Linux and Windows

{statistics}

Path to directory with statistics files (AWStats/Webalizer/etc) of addon domain/subdomain

Linux and Windows

{webspace_anon_ftp_incoming}

Path to directory available for upload by anonymous FTP of parent subscription

Linux only

{webspace_anon_ftp_pub}

Path to directory available for read by anonymous FTP of parent subscription

Linux only

{webspace_cgi_bin}

Path to cgi-bin directory of parent subscription

Linux only

{webspace_document_root}

Path to document root of parent subscription

Linux and Windows

{webspace_idn}

Name of parent subscription encoded in punycode

Linux and Windows

{webspace_logs}

Path to directory with logs (Apache access and error logs, etc) of parent subscription

Linux and Windows

{webspace_protected_dirs}

Path to directory with settings of protected directories of parent subscription

Linux only

{webspace_root}

Path to subscription root

Linux and Windows

{webspace_ssl_document_root}

Path to secure document root of parent subscription - directory available by HTTPS

Windows only

{webspace_statistics}

Path to directory with statistics files (AWStats/Webalizer/etc) of parent subscription

Linux only

{webspace}

Name of parent subscription

Linux and Windows

Specifying the path to the mail content data

The mechanism of transferring the mail content from the source to the destination server works differently on Linux and on Windows.

On Linux, you need to specify the information about the mailboxes to be migrated in the mail_users section:

mail_users:
  -
    name: johndoe
    password: 123qwe
    directory: /var/qmail/mailnames/johndoe

where "directory" specifies an absolute path to where the mailbox content is stored on the source server, or where it was placed after being manually moved to the destination server.

On Windows, nothing needs to be specified in the hosting description file. All mail content will be migrated using the Plesk backup and restore mechanisms.

Note: On Windows, Plesk Migrator does not have the ability to import mail content that has been manually moved to the destination server. For mail content to be migrated, access to the source server is necessary.

Specifying the path to the databases

Plesk Migrator is able to copy MySQL and Microsoft SQL Server databases when migrating from other panels. There are two ways to copy database content:

  • Copy the content directly if access to the database server is provided.
  • Restore the content from a database dump file.

To copy the content directly from a database server, it must be listed in the Plesk Migrator configuration file, and access information for the server must be provided. Use the server parameter in the databases section:

databases:
  -
    server: mysql-db
    name: wordpress_9
    users:
      -
        login: exdbuser1
        password: 123qwe
  -
    server: mssql-db
    name: drupal_2
    users:
      -
        login: exdbuser2
        password: 123qwe

or

-
    name: wordpress_9
    dump: wordpress_9.sql
    users:
      -
        login: exdbuser1

For restoring the content from a database dump file, the dump must be created in a specific format:

  • For MySQL, the dump can be created, for example, with mysqldump utility.
  • For Microsoft SQL Server, use the T-SQL construct "BACKUP".

To restore a dump, specify the dump option, like this:

-
  name: wordpress_9
  dump: wordpress_9.sql
  user:
    login: exdbuser1

Note: Migrating Microsoft SQL Server databases is only possible if the hostname of the Microsoft SQL Server instance on the source server can be resolved from the destination server.

 

Leave your comments on this page

Leave your feedback or question on this documentation topic below. For technical assistance, contact your hosting service provider or submit a request to Plesk support. Suggest new features for Plesk here. Discuss general questions on the Plesk forum. All offtopic comments will be removed.