Support

Documentation

5.2.Site setup page
5.2.Site setup page
Prev5.BRS for WordPressNext

5.2.Site setup page

This page allows you to partially reconfigure your site. Changes will only be necessary when you are restoring to a new server, subdirectory, subdomain, or domain. If you are restoring into the same location you backed up from just click on Next.

The default values you see on this page are read from your wp-config.php file, and the site's database.

Site name

The name of your site, as used by WordPress and your current theme.

Tagline

The tagline / subtitle of your site, as used by WordPress and your current theme.

Site Address (URL)

The URL your visitors need to type into their browser to access your site.

Default: the URL you are restoring to, i.e. the installation script's URL with the /installation path removed from it.

WordPress Address (URL)

The URL where WordPress files are installed.

In most cases it is identical to the Site Address (URL) above. This will only be different if you are giving WordPress its own directory using “Method II (With URL Change)” described in WordPress' official documentation.

Default: derived from Site Address (URL) and the configured WP_SITEURL constant read from the wp-config.php file. If no WP_SITEURL was defined in that file, the default value is identical to Site Address (URL).

Database charset

The character set for the database. It should be either utf8 (3-byte UTF-8) or utf8mb4 (4-byte UTF-8). Corresponds to the DB_CHARSET constant in the wp-config.php file.

If this was not defined in your wp-config.php file, or if it was set to utf8 and the Database collation was left blank then the default value is:

  • utf8 if your database server only supports 3-byte UTF-8 data, or you have disabled the auto-detection of UTF8MB4 when restoring the site's main database.

    Note

    If you are restoring your site using BRS' command line interface the default value will always be calculated as if you have enabled auto-detection of UTF8MB4 in your site's main database.

  • utf8mb4 in any other case.

Database collation

The collation for the database. Typical values are utf8_general_ci when the charset is set to utf8, and utf8mb4_unicode_ci when the charset is set to utf8mb4. Corresponds to the DB_COLLATE constant in the wp-config.php file.

If this was not defined in your wp-config.php file and the Database charset is set to utf8 then the default value is:

  • utf8_general_ci if your database server only supports 3-byte UTF-8 data, or you have disabled the auto-detection of UTF8MB4 when restoring the site's main database.

    Note

    If you are restoring your site using BRS' command line interface the default value will always be calculated as if you have enabled auto-detection of UTF8MB4 in your site's main database.

  • utf8mb4_unicode_ci in any other case.

Warning

It is your responsibility to ensure that the Database charset and Database collation are valid on your server, and match with each other.

Using a utf8 charset / collation on MariaDB 10.6 may result in unexpected behavior or an error, as 3-byte UTF-8 has been renamed to utf8mb3.

Mixing character sets and collations (e.g. a cp1253 charset with utf8_general_ci collation) will result in a MySQL error.

If unsure, set the charset to utf8 and leave the collation blank. While generally safe for most uses, this combination of settings may limit your ability to use Emoji and other 4-byte characters such as Traditional Chinese, Kanji Japanese, etc.

Administrator settings

You can select exactly one administrator user to modify. You can change the user's email and password, but not their username. If you do not wish to use this feature select the “—” entry.

You may want to use this feature when you are restoring a backup taken by another person, on a site you do not normally have administrator access to. You need to somehow be able to log into the restored site as an Administrator. Pick an existing administrator, and change their password. You will be able to log into the site using the username of the administrator you modified, and the new password you selected.

Tip

This comes in very handy when you want to understand how the site works when you've sold a support contract to new client. You don't know how the site works, and you don't want to learn in production. Take a backup with Akeeba Backup, restore it on a development server, and dissect the site without worrying about breaking it.

Server-specific configuration files

When moving a site between hosts, servers, domains, subdomains, or directories it is possible that the contents of certain server-specific configuration files might cause errors with the restored site. BRS allows you to take preemptive action to prevent such issues from occurring.

Important

Not all options may be visible, or enabled. Which options you see and / or are enabled depend on whether the corresponding configuration files exist, and their contents.

If you see a disabled option you can safely ignore it. It does not apply to your site. Instead of misleading you by letting you set an option which does nothing on your site, we simply display it as disabled.

If an option is completely missing it also means that it does not apply to your site. Don't be alarmed by its absence.

The .htaccess Handling drop-down appears if BRS detects that your .htaccess file in your site's root has AddHandler or SetHandler lines. These lines tell your server which PHP version to use. Their presence means that you are probably not using your server's default PHP version, therefore BRS needs to transcribe them into your site's .htaccess files. When you read “.htaccess” below you should understand “.htaccess and / or htaccess.bak”.

Note

If no such lines are detected, the drop-down does not appear at all.

As a result, the option you select here will modify your site's main .htaccess file, stored in your site's root. Please note that if you have a file named htaccess.bak the options here apply to that file as well. The reason is that upon clicking on Clean Up at the end of the restoration this file will be renamed to .htaccess.

None

Leaves the .htaccess file as-is.

Remove PHP handler lines

Remove the AddHandler / SetHandler lines from the file.

You may want to do that if you are transferring the file across different hosts, or even different servers within the same host.

The reason is that the the AddHandler / SetHandler lines which select which PHP version you were going to be using on your site are specific to the configuration of the server. Different servers may have different configurations. Leaving the wrong AddHandler / SetHandler lines from a previous / different server will cause an error in the new server.

Do note that if you select this option and after clicking Next you might get an error, or you may find that the Clean Up button at the end of the restoration no longer works. If this is the case please log into your hosting control panel and select a newer version of PHP.

Replace PHP handler lines

This is the recommended option. BRS will transcribe the AddHandler / SetHandler lines from your current .htaccess to the final .htaccess file of your restored site.

The typical use of this feature is that you start by going to your hosting control panel and select a newer PHP version before extracting your backup. What happens in most cases is that your host modifies your .htaccess file with an AddHandler or SetHandler line which tells the server to use a newer PHP version.

When you extract your backup, your original site's .htaccess file will be extracted htaccess.bak. This is on purpose. The .htaccess file from your backup may contain different AddHandler/SetHandler lines which do not work with your current server, or no such lines which would make your new server use its default version of PHP, one which might not be compatible with the restoration script and/or the backed up site. By renaming the extracted file this issue is sidestepped.

This leaves us with the problem that once the backup is complete, the htaccess.bak file would be renamed back to .htaccess, therefore the problem with invalid lines causing a server error, or the wrong PHP version being used preventing you from accessing your site would remain. By enabling this option here you are telling BRS to transcribe the known-good AddHandler/SetHandler lines into the htaccess.bak file. Therefore, when it's renamed back to .htaccess at the end of the restoration clean-up your site will be running under the correct PHP version.

It is a bit confusing, but that's how server works. What you need to keep in mind is this:

  • Select the correct PHP version on your site before extracting your backup archive.

  • Extract the backup archive and run the restoration.

  • If you see the .htaccess Handling option, select Replace PHP handler lines. It is the default, anyway, so you don't have to think much about it!

The Remove .user.ini and / or php.ini files from the main site directories option appears if there is a .user.ini or a php.ini file in your site's root and/or your wp-admin directory. These files are used to modify PHP configuration parameters. When transferring your site between different hosts, or even different servers on the same hot they are likely to cause problems, preventing you from accessing your site. Enabling this option will remove these files, fixing the problem.

The Disable auto-prepend scripts option is always shown, and is available to be selected if BRS detects that your site's .htaccess, .user.ini, or php.ini file define an “auto-prepend” (sic) script. These are PHP scripts which are forcibly loaded and executed before your server executes any other .php file. They are typically used by security plugins to implement a web application firewall very early in WordPress' loading process. The problem is that when you are transferring a site between different hosts, servers within the same host, or even subdomains or directories within the same site the path to these scripts will no longer be valid. This will cause PHP to fail running anything at all, leading to a completely broken site (not even a simple phpinfo() script can run). Enabling this option will remove references to these “auto-prepend” scripts completely.

The Delete the .htaccess and .htpasswd files in the administrator directory option is always shown, and is available to be selected if BRS detects that your wp-admin directory has a .htaccess and/or .htpasswd file, commonly used to implement password protection of the wp-admin directory. Enabling this option will remove these files. You need to do that if you are transferring your site between hosts, servers within the same host, subdomains, domains, or directories. This is for two reasons. First problem is that the .htaccess file in the administrator folder contains an absolute filesystem path to the .htpasswd file which is different on each server, subdomain, domain, or directory. Second, .htpasswd files may require different formats on each server. Removing the administrator password protection is the best approach to ensure you can log into your site's administrator after restoration. You can use your hosting control panel or third party software, such as Admin Tools, to reapply administrator login password protection on your restored site.

Finally, click on the Next button to let ANGIE write your site's new configuration and display the Replace data page.

PrevUpNext
5.BRS for WordPressHome5.3.Replace data page