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.
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 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.
mainUnused. Corresponds to the main page. Since that's an information page there is nothing to configure, therefore you can skip this property.
databaseJoomla, WordPress, Miscellaneous. Corresponds to the database restoration pages. There is a property for each database to restore.
publicfolderJoomla. Corresponds to the Public Folder page. Only necessary when the site had a public folder which is different to Joomla's installation root.
offsitedirsJoomla, WordPress, Miscellaneous. Corresponds to the off-site directory restoration pages. There is a property for each directory to restore.
setupJoomla, WordPress. Corresponds to the respective Site Setup page (Joomla, WordPress). This is where you can (re-)configure your site.
replacedataWordPress. Corresponds to the Replace Data page.
finaliseUnused. 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 of the configuration file corresponds to the database restoration pages. There is a property for each database to restore.
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:
The database type, one of mysqli or pdomysql.
The name of the database to restore into.
The database server's hostname or IP address.
The database server's TCP/IP port. If left blank, 3306 will be used unless a dbsocket is specified, or the dbhost is localhost.
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.
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.
The database username you will be using to connect to the database server into which you are restoring the data.
The password you will be using to connect to the database server into which you are restoring the data.
The prefix of the database tables, including the trailing underscore, e.g. foo1_.
Boolean. Do you want to use SSL/TLS certificates to connect to your database?
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
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.
SSL Key file. The absolute filesystem path to the client key file in PEM format.
SSL Certificate file. The absolute filesystem path to the client certificate file in PEM format.
Boolean. Verify Server Certificate. Should BRS verify the server response against the Certification Authority (CA) file?
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.
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.
No auto value on zero. Allows you to restore tables with auto-incrementing fields whose value is zero.
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.
Boolean. Force UTF-8 collation on database. See the Database page's documentation.
Boolean. Force UTF-8 collation on tables. See the Database page's documentation.
Boolean. Allow UTF8MB4 auto-detection. See the Database page's documentation.
Normalise character set. See the Database page's documentation.
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?
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?
Ignored.
Ignored.
Boolean. Skip Restoration. Set to true to skip over the restoration of this database.
Skipping the restoration of the main site database WILL cause restoration issues when using BRS for Joomla, or BRS for WordPress.
Array. Optional. List the names of the database tables to restore. Only these tables will be restored. Leave blank to restore everything.
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.
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.
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:
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).
The restoration cases refer to what is documented under the Public Folder page.
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.
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:
Boolean. True to skip the restoration of this off-site folder.
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.
The absolute filesystem path where these files will be copied into.
Corresponds to the respective Site Setup page (Joomla, WordPress). This is where you can (re-)configure your site.
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.
The following properties are available for Joomla! sites:
Optional. The user ID of a Super User account you want to modify.
Only if superuserid is a non-zero integer corresponding to a Super User account. The new email address for the Super User account.
Only if superuserid is a non-zero integer corresponding to a Super User account. The new password for the Super User account.
Only if superuserid is a non-zero integer corresponding to a Super User account. Enter the new password for the Super User account again.
Should the .user.ini and php.ini files be removed from the site's root and the site's administrator directories, if present?
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?
Boolean. Should the .htpassword and .htaccess files be removed from the administrator directory, if present?
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.
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.
Site name. The name of your site, for use in the site's HTML pages among other things.
Site e-mail address. The email address where your site's emails will appear to be originating from.
Site e-mail sender name. The name of the sender used for all emails sent out by your site.
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.
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.
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).
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 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.
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. 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.
Boolean. Turn on mail sending?
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.
Reset caching options? If true, it will reset Joomla's caching options to use file caching. Use this when moving a site between hosts.
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.
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.
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!
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.
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.
Only for Joomla! 1.x, 2.5, and 3.x sites. The username you use to connect to FTP. If unsure ask your host.
Only for Joomla! 1.x, 2.5, and 3.x sites. The password you use to connect to FTP. If unsure ask your host.
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.
The following properties are available for WordPress sites:
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.
Only if superuserid is a non-zero integer corresponding to an Administrator account. The new email address for the Administrator account.
Only if superuserid is a non-zero integer corresponding to an Administrator account. The new password for the Administrator account.
Only if superuserid is a non-zero integer corresponding to an Administrator account. Enter the new password for the Administrator account again.
The name of your site, for use in the site's HTML pages among other things.
Tagline. In a few words, explain what your site is about.
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.
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.
Database charset. Set the character set for the database connection. The recommended setting is utf8.
Database collation. Set the database collation for the database connection. Should be left blank for most sites.
Should the .user.ini and php.ini files be removed from the site's root and the site's wp-admin directories, if present?
Boolean. Should the .htpassword and .htaccess files be removed from the wp-admin directory, if present?
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.
Boolean. Should any PHP “auto-prepend” scripts be disabled in the .htaccess, php.ini, and .user.ini files of your site?
This only applies to WordPress sites being restored using BRS for WordPress. Corresponds to the Replace Data page.
The available properties are:
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.
An array of tables beyond the core WordPress tables where the replacement should also take place.
Boolean. Should BRS replace the GUID of posts and media files?
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.
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.