Support

Documentation

The configuration file
Prev Chapter 2. Using BRS over the CLI Next

The configuration file

To create a sample configuration file for your site being restored run the following in the installation directory:

php ./cli.php config:make

This will create the file config.yml.php. This is a standard YAML file whose first line is #<?php die(); ?>. This makes the file a valid YAML file, and a valid PHP executable file which only outputs # when accessed directly.

[Important]Important

For security reasons, the #<?php die(); ?> line MUST be present. If you omit this line anyone could access the /installation/config.yml.php on your site while the restoration is in progress and receive privileged information, such as your database password. This information could then be used to compromise (hack) your site. The comment line above along with the .php extension forces the server to NOT output anything beyond the hash sign (#).

The configuration file format

The configuration file is essentially a YAML-formatted object with one property for each page of the restoration script. Let's take an overview of the top-level properties.

main

Unused. Corresponds to the main page. Since that's an information page there is nothing to configure, therefore you can skip this property.

database

Joomla, WordPress, Miscellaneous. Corresponds to the database restoration pages. There is a property for each database to restore.

publicfolder

Joomla. Corresponds to the Public Folder page. Only necessary when the site had a public folder which is different to Joomla's installation root.

offsitedirs

Joomla, WordPress, Miscellaneous. Corresponds to the off-site directory restoration pages. There is a property for each directory to restore.

setup

Joomla, WordPress. Corresponds to the respective Site Setup page (Joomla, WordPress). This is where you can (re-)configure your site.

replacedata

WordPress. Corresponds to the Replace Data page.

finalise

Unused. Corresponds to the finalisation page. Since that's an information page there is nothing to configure, therefore you can skip this property.

The database section

The database section of the configuration file corresponds to the database restoration pages. There is a property for each database to restore.

[Note]Note

If you are using Akeeba Solo with BRS for Miscellaneous PHP Applications and you have not backed up a database, you do not need this section. However, if this is the case, there is no need to use BRS as its job is to restore your database, and reconfigure your site, none of which applies to your use case.

If you find yourself in a situation like this, it makes more sense to just delete the installation folder, without trying to unnecessarily configure and run BRS.

The first configured database is the site's main database, and its property name is always site. Every additional database's property name is in the format uniquePrefix-databaseName, e.g. 5118D1DD-example. You can find these names in the installation/sql/databases.json file.

The available properties for each database are:

dbtype

The database type, one of mysqli or pdomysql.

dbname

The name of the database to restore into.

dbhost

The database server's hostname or IP address.

dbport

The database server's TCP/IP port. If left blank, 3306 will be used unless a dbsocket is specified, or the dbhost is localhost.

[Note]Note

If you set dbhost to localhost and dbport to an integer between 1 and 65535 BRS will assume you meant to set dbhost to 127.0.0.1, thereby using TCP/IP to connect to your host. If you actually meant to use a socket, named pipe, or shared memory you MUST leave this option blank.

dbsocket

The absolute filesystem path to the database server's UNIX socket file (Linux, macOS, other UNIX-like Operating Systems), named pipe, or shared memory file (Windows). If left blank: the system default will be used if dbhost is localhost, otherwise the configured TCP/IP port will be used.

dbuser

The database username you will be using to connect to the database server into which you are restoring the data.

dbpass

The password you will be using to connect to the database server into which you are restoring the data.

prefix

The prefix of the database tables, including the trailing underscore, e.g. foo1_.

dbencryption

Boolean. Do you want to use SSL/TLS certificates to connect to your database?

dbsslcipher

The colon-separated list of the encryption ciphers to use for the SSL/TLS connection. If you do not know what to use a good value would be AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-CBC-SHA256:AES256-CBC-SHA384:DES-CBC3-SHA

dbsslca

SSL CA file. The absolute filesystem path to the Certification Authority (CA) file for connecting to the server, in PEM format. This is only taken into account when Validate Server Certificate is enabled.

dbsslkey

SSL Key file. The absolute filesystem path to the client key file in PEM format.

dbsslcert

SSL Certificate file. The absolute filesystem path to the client certificate file in PEM format.

dbsslverifyservercert

Boolean. Verify Server Certificate. Should BRS verify the server response against the Certification Authority (CA) file?

existing

With existing tables. Select what to do with existing tables. The options are:

  • drop Drop. Will delete existing tables with the same names as tables being restored

  • backup Backup. Will rename existing tables with the same names as tables being restored, changing their prefix to bak_.

  • dropprefix Drop Same Prefix. Will drop all tables with the same prefix, even if they are not included in the backup being restored.

  • dropall Drop All. Will drop all tables, even with a different prefix.

foreignkey

Boolean. Suppress foreign key checks. Disables MySQL's foreign key checking while the restoration is in progress. This is mandatory when you are restoring a database which uses table-level relations (foreign keys). If unsure, leave this set to true.

noautovalue

No auto value on zero. Allows you to restore tables with auto-incrementing fields whose value is zero.

replace

Boolean. Use REPLACE instead of INSERT. The restoration script will normally use INSERT commands to restore the database data. Enabling this option will use REPLACE INTO commands instead, overwriting data instead of duplicating it.

utf8db

Boolean. Force UTF-8 collation on database. See the Database page's documentation.

utf8tables

Boolean. Force UTF-8 collation on tables. See the Database page's documentation.

utf8mb4

Boolean. Allow UTF8MB4 auto-detection. See the Database page's documentation.

charset_conversion

Normalise character set. See the Database page's documentation.

break_on_failed_create

Boolean. Stop on CREATE error. Should the restoration be immediately stopped if there is an error creating a table, view, function, trigger or stored procedure?

break_on_failed_insert

Boolean. Stop on other error. Should the restoration be immediately stopped if there is an error executing any other database command, such as restoring or deleting data?

maxexectime

Ignored.

throttle

Ignored.

skip

Boolean. Skip Restoration. Set to true to skip over the restoration of this database.

[Warning]Warning

Skipping the restoration of the main site database WILL cause restoration issues when using BRS for Joomla, or BRS for WordPress.

specific_tables

Array. Optional. List the names of the database tables to restore. Only these tables will be restored. Leave blank to restore everything.

The publicfolder section

This section only applies to BRS for Joomla!. Corresponds to the Public Folder page. Only necessary when the site had a public folder which is different to Joomla's installation root.

[Note]Note

The vast majority of Joomla! sites DO NOT use a custom public folder, therefore do not need and must not even include this configuration section.

[Important]Important

For restoration to work correctly in this case, you must extract the backup archive in the non-public directory (the Joomla installation root). The idea is that BRS will copy the public folder files into the public (web root) directory, and modify them so that they point to the Joomla installation root.

The available properties are:

usepublic

Boolean. True to keep the site into a split custom / private folder configuration (restoration case A). False to convert the site into a regular installation where Joomla is installed under the public web root (restoration case B).

[Note]Note

The restoration cases refer to what is documented under the Public Folder page.

newpublic

Only applies to restoration case A; ignored in restoration case B (when usepublic is false). The absolute filesystem path of your site's public folder, e.g. /var/www/html.

The offsitedirs section

Corresponds to the off-site directory restoration pages. There is a property for each directory to restore.

Each directory's property is an object with the following properties:

skip

Boolean. True to skip the restoration of this off-site folder.

[Important]Important

Skipped off-site folders' contents remain on your server under the external_files directory under your site's root. You may need to delete that folder after the restoration is complete.

target

The absolute filesystem path where these files will be copied into.

The setup section

Corresponds to the respective Site Setup page (Joomla, WordPress). This is where you can (re-)configure your site.

[Note]Note

These sections are specific to BRS for Joomla!, and BRS for WordPress. There is no setup section, nor will putting one take effect, in BRS for Miscellaneous PHP Applications. This is true even if you have backed up a Joomla or WordPress site.

Site setup options for Joomla!

The following properties are available for Joomla! sites:

superuserid

Optional. The user ID of a Super User account you want to modify.

superuseremail

Only if superuserid is a non-zero integer corresponding to a Super User account. The new email address for the Super User account.

superuserpassword

Only if superuserid is a non-zero integer corresponding to a Super User account. The new password for the Super User account.

superuserpasswordrepeat

Only if superuserid is a non-zero integer corresponding to a Super User account. Enter the new password for the Super User account again.

removephpini

Should the .user.ini and php.ini files be removed from the site's root and the site's administrator directories, if present?

replacewebconfig

Boolean. Only for sites running on Microsoft IIS. Should the web.config file be replaced with the contents of the stock web.config.txt file shipped with Joomla?

removehtpasswd

Boolean. Should the .htpassword and .htaccess files be removed from the administrator directory, if present?

htaccessHandling

Only for sites on Apache or LiteSpeed web servers. How should I handle the .htaccess file in the site's root?

  • none No change.

  • default Replace the file with the contents of the stock htaccess.txt file shipped with Joomla.

  • removehandler Remove any AddHandler / SetHandler lines from the file.

  • replacehandler Replace the AddHandler / SetHandler lines with those detected in the current .htaccess file.

newsecret

Boolean. Generate a new secret? Enable this when moving your site between servers and/or domains. It generates new secrets in your site's configuration file to prevent session reuse from the old site. Note that third party software using the site's secrets to encrypt information may be unable to access its data when you do that.

sitename

Site name. The name of your site, for use in the site's HTML pages among other things.

siteemail

Site e-mail address. The email address where your site's emails will appear to be originating from.

emailsender

Site e-mail sender name. The name of the sender used for all emails sent out by your site.

livesite

Live site URL. Some servers have trouble figuring out the URL of your site which can lead to SEF URLs and menu items not working. On these servers you have to enter your site's URL without the trailing slash, e.g. http://www.example.com. In most cases this is not required and you can leave this field empty.

cookiedomain

Cookie domain. The Cookie domain is the domain name of your site, without the protocol and, usually, without the www part. For example, if you are restoring to http://www.example.com, the Cookie domain is example.com.

cookiepath

Cookie path. The Cookie path is the subdirectory of your site, relative to the domain's root. If you are restoring to the root of a domain, e.g. http://www.example.com, then it is / (a single forward slash). If you are restoring to a subdirectory it's a slash followed by the directory's name. For example, if you're restoring to http://www.example.com/joomla then the Cookie path is /joomla (with a leading slash, but without a trailing slash).

tmppath

Temporary directory. The absolute filesystem path to the directory where Joomla! will store temporary data. MUST be non-empty for the site to work at all.

cache_path

Cache directory. The absolute filesystem path to the directory where Joomla! will store its temporary cache files. Recommended to leave blank, in which case Joomla will use its internal JPATH_CACHE constants.

logspath

Log directory. The absolute filesystem path to the directory where Joomla! will store its log files. MUST be non-empty for the site to work at all.

force_ssl

Force SSL. The possible values are:

  • 0 None. You can access the entire site as HTTP or HTTPS. NOT RECOMMENDED; COMPLETELY INSECURE. Only acceptable when restoring to a local or Intranet web server which is not accessible from the Internet or untrusted users.

  • 1 Administrator Only. You can access the frontend and API applications as HTTP or HTTPS. You will be forced to use the administrator application (/administrator) over HTTPS. NOT RECOMMENDED. This option gives a false sense of security, as it allows privileged users to access the site in a way which can result in their login cookies being stolen, with dire consequences for your site.

  • 2 Entire Site. You can only access your site over HTTPS. This is the recommended option.

mailonline

Boolean. Turn on mail sending?

resetsessionoptions

Boolean. Reset session options? If true, it will reset Joomla's session handling options to use the database for session management. Use this when moving a site between hosts.

resetcacheoptions

Reset caching options? If true, it will reset Joomla's caching options to use file caching. Use this when moving a site between hosts.

robotHandling

Robots (Search Engine) handling. The possible options are:

  • 0 No change. Recommended when restoring onto the same site you backed up from.

  • 1 Index, and follow links. Recommended for most live sites.

  • 2 Index, but don't follow links.

  • 3 Do not index, do not follow links. Recommended for development and staging sites.

ftpenable

Only for Joomla! 1.x, 2.5, and 3.x sites. Boolean. Enable the FTP layer? If true, you must set all other ftp* options.

[Warning]Warning

It is a generally bad idea using the FTP layer. If you have a site which needs it, it means that your host has misconfigured your server. There are several ways to configure a server to be perfectly secure and NOT require the FTP layer available since the late 90s and early 00s such as using chroot jails, suPHP, different PHP-FPM pools, or virtualisation. If your host hasn't gotten the memo after so many decades, you should switch over to a competent host!

ftphost

Only for Joomla! 1.x, 2.5, and 3.x sites. Host name. The host name or IP address of your FTP server without the ftp:// shema prefix. It's usually localhost or 127.0.0.1. If unsure, ask your host.

ftpport

Only for Joomla! 1.x, 2.5, and 3.x sites. The TCP port where the FTP server listens to. This is usually 21. If unsure set it to 21 or ask your host.

ftpuser

Only for Joomla! 1.x, 2.5, and 3.x sites. The username you use to connect to FTP. If unsure ask your host.

ftppass

Only for Joomla! 1.x, 2.5, and 3.x sites. The password you use to connect to FTP. If unsure ask your host.

ftpdir

Only for Joomla! 1.x, 2.5, and 3.x sites. The FTP directory where your site's files (like index.php) can be found. If unsure, ask your host.

Site setup options for WordPress

The following properties are available for WordPress sites:

superuserid

Optional. The numeric user ID of an Administrator (single-site installation) or the Super Administrator (multi-site installation) you want to change the email and password for.

superuseremail

Only if superuserid is a non-zero integer corresponding to an Administrator account. The new email address for the Administrator account.

superuserpassword

Only if superuserid is a non-zero integer corresponding to an Administrator account. The new password for the Administrator account.

superuserpasswordrepeat

Only if superuserid is a non-zero integer corresponding to an Administrator account. Enter the new password for the Administrator account again.

blogname

The name of your site, for use in the site's HTML pages among other things.

blogdescription

Tagline. In a few words, explain what your site is about.

homeurl

Site address (URL). Enter the address here if you want your site homepage to be different from the directory you installed WordPress. For most sites, that's the URL you are restoring your site to.

siteurl

WordPress address (URL). The address where WordPress' files are installed. It might be different from the URL you access your site on. For most sites, that's the URL you are restoring your site to.

dbcharset

Database charset. Set the character set for the database connection. The recommended setting is utf8.

dbcollation

Database collation. Set the database collation for the database connection. Should be left blank for most sites.

removephpini

Should the .user.ini and php.ini files be removed from the site's root and the site's wp-admin directories, if present?

removehtpasswd

Boolean. Should the .htpassword and .htaccess files be removed from the wp-admin directory, if present?

htaccessHandling

Only for sites on Apache or LiteSpeed web servers. How should I handle the .htaccess file in the site's root?

  • none No change.

  • default Replace the file with the default .htaccess file shipped with WordPress.

  • removehandler Remove any AddHandler / SetHandler lines from the file.

  • replacehandler Replace the AddHandler / SetHandler lines with those detected in the current .htaccess file.

disable_autoprepend

Boolean. Should any PHP “auto-prepend” scripts be disabled in the .htaccess, php.ini, and .user.ini files of your site?

The replacedata section

This only applies to WordPress sites being restored using BRS for WordPress. Corresponds to the Replace Data page.

The available properties are:

replacements

A hash array with the data to match on the left hand side, and the data to replace it with on the right hand side.

extraTables

An array of tables beyond the core WordPress tables where the replacement should also take place.

replaceguid

Boolean. Should BRS replace the GUID of posts and media files?

column_size

The maximum column size, in bytes, where data replacements will take place. The default value is 1048576 bytes (1 MiB). Increasing this may make the data replacement slower, or outright fail, if you have massive columns in any of your database tables.

batchSize

How many rows to process per batch. Default: 10000. The bigger this number is the faster the replacement goes, but the more memory is needed. Lower it if you get a PHP error due to lack of memory.

Prev Up Next
Chapter 2. Using BRS over the CLI Home Chapter 3. Troubleshooting