To use PHPBU and create your backups you first have to create a configuration file.
The configuration of PHPBU is done with a simple XML file. You can validate your config files with the respective PHPBU schema definition found at schema.phpbu.de.
You should name your configuration file phpbu.xml
or phpbu.xml.dist
so you don't have to specify the path with the --configuration
option.
The following skeleton is a good point to start and get into detail from here.
Example 2.1: XML-Configuration
<?xml version="1.0" encoding="UTF-8"?> <phpbu xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.phpbu.de/6.0/phpbu.xsd"> <backups> <backup name="MyDatabase"> <!-- backup source --> <source type="mysqldump"> <option name="databases" value="mydbname"/> <option name="user" value="user.name"/> <option name="password" value="topsecret"/> </source> <!-- where should the backup be stored --> <target dirname="backup/mysql" filename="mysqldump-%Y%m%d-%H%i.sql" compress="bzip2"/> <!-- check the created backup --> <check type="SizeMin" value="10M"/> <!-- cleanup the backup location as soon as all created backups exceed 500MB remove oldest backups --> <cleanup type="Capacity"> <option name="size" value="500M"/> </cleanup> </backup> </backups> </phpbu>
The XML root element with at least xmlns:xsi and xsi:noNamespaceSchemaLocation.
Table 2.1. <phpbu> attributes
Name | Values | Required | Default | Description |
---|---|---|---|---|
bootstrap | filename | no | null | Include a PHP file to extend PHPBU |
verbose | true | false | no | false | Controls the output verbosity |
debug | true | false | no | false | Controls the debug output |
Configures a backup process. You can have as many of these as you need.
Table 2.2. <backup> attributes
Name | Values | Required | Default | Description |
---|---|---|---|---|
name | string | yes | null | A custom name for your backup used in the PHPBU output. |
stopOnError | true | false | no | false | Indicates if the execution of PHPBU should be stopped if this backup fails. |
Defines the data that is backed up.
Table 2.3. <source> attributes
Name | Values | Required | Default | Description |
---|---|---|---|---|
type | string | yes | - | Type of backup, Chapter 5 has a list of all supported source types. |
Defines where the backup is stored.
Table 2.4. <target> attributes
Name | Values | Required | Default | Description |
---|---|---|---|---|
dirname | string | yes | - | Path to the directory where the backup is stored, absolute or relative to the config file. |
filename | string | yes | - | Filename of the stored backup. |
compress | string | no | null | Type of compressor to use to compress the backup. |
Specifies what kind of tests should be performed to validate the backup.
Table 2.5. <check> attributes
Name | Values | Required | Default | Description |
---|---|---|---|---|
type | string | yes | - | Type of check, Chapter 6 has a list of all supported check types. |
value | string | yes | - | Value the backup is getting checked against. |
Specifies what type of encryption should be used to encrypt the backup.
Table 2.6. <crypt> attributes
Name | Values | Required | Default | Description |
---|---|---|---|---|
type | string | yes | - | Type of encryption, Chapter 7 has a list of all supported crypt types. |
skipOnFailure | true | false | no | false | You can still execute the encryption, even if failure(s) occurred. |
Copy the created backup to another location.
Table 2.7. <sync> attributes
Name | Values | Required | Default | Description |
---|---|---|---|---|
type | string | yes | - | Type of sync, Chapter 8 has a list of all supported sync types. |
skipOnFailure | true | false | no | false | You can still execute the sync, even if failure(s) occurred. |
Tells phpbu which files to delete after a successful backup.
Table 2.8. <cleanup> attributes
Name | Values | Required | Default | Description |
---|---|---|---|---|
type | string | yes | - | Type of cleanup, Chapter 9 has a list of all supported cleanup types. |
skipOnFailure | true | false | no | - | You can still execute the cleanup, even if failure(s) occurred. |
This is roughly the same skeleton as shown above at the XML-Section.
Example 2.2: JSON-Configuration
{ "verbose": true, "logging": [ { "type": "json", "target": "backup/json.log" } ], "backups": [ { "name": "MyDatabase", "source": { "type": "mysqldump", "options": { "databases": "mydbname", "user": "user.name", "password": "topsecret" } }, "target": { "dirname": "backup", "filename": "mysql-%Y%m%d-%H%i.sql", "compress": "bzip2" }, "checks": [ { "type": "sizemin", "value": "10M" } ], "syncs": [ { "type": "sftp", "options": { "host": "backup.example.com", "user": "user.name", "password": "topsecret", "path": "backup/someName" } } ], "cleanup": { "type": "Capacity", "options": { "size": "200M" } } } ] }
Adapters are used to include configuration settings from other configuration sources.
So with adapters you don't have to put your passwords into your PHPBU configuration file. Instead you can use environment variables or .env configuration files.
And this is how it works:
You add an adapter to your phpbu configuration like shown in the examples below.
You have to choose a type
and a name
. The name is completely up to you, but you are not allowed
to use colons.
With this done you can now reference your configured adapter for any option value in your PHPBU configuration like this.
:adapter:my-chosen-adapter-name:path.to.value:
The keyword adapter
tells PHPBU that this option value should be received from an adapter,
followed by a colon
, followed by your chosen adapter name
so PHPBU knows which adapter to use,
followed by a colon
, followed by the identifier for your value.
The identifier could be the name of a environment variable or a "path" through an configuration array like this
"db.mysql.username" completely depending on the adapter implementation.
You can use adapter values for whole configuration values, in that case you can skip the leading and trailing colons. If you want to use multiple adapter values in a single configuration value you have to use the leading and trailing colons.
Example 2.3: Adapter examples
<option name="singleValue" value="adapter:myAdp:foo"/> <option name="multipleValues" value="/foo/:adapter:myAdp:dir:/bar/:adapter:myAdp:file:.zip"/>
{"singleValue": "adapter:myAdp:foo"} {"multipleValues": "/foo/:adapter:myAdp:dir:/bar/:adapter:myAdp:file:.zip"}
For a list of available adapters and detailed documentation check out the adapter section.
Example 2.4: XML-Configuration
<?xml version="1.0" encoding="UTF-8"?> <phpbu xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.phpbu.de/6.0/phpbu.xsd"> <adapters> <adapter type="dotenv" name="environment"> <option name="file" value=".env" /> </adapter> <adapters> <backups> <backup> <!-- backup source --> <source type="mysqldump"> <option name="databases" value="mydbname"/> <option name="user" value="adapter:environment:DB_USER"/> <option name="password" value="adapter:environment:DB_PASSWORD"/> </source> <!-- where should the backup be stored --> <target dirname="backup/mysql" filename="mysqldump-%Y%m%d-%H%i.sql"/> </backup> </backups> </phpbu>
Example 2.5: JSON-Configuration
{ "verbose": true, "adapters": [ { "type": "dotenv", "name": "environment", "options": { "file": ".env" } } ], "backups": [ { "source": { "type": "mysqldump", "options": { "databases": "mydbname", "user": "adapter:environment:DB_USER", "password": "adapter:environment:DB_PASSWORD" } }, "target": { "dirname": "backup", "filename": "mysql-%Y%m%d-%H%i.sql" } } ] }
Scheduling your backups is not part of PHPBU. Nevertheless here is an example how to do it with Cron. Adding one of the following lines to your crontab will execute your backup every morning at 3:10 AM.
Example 2.6: Crontab example
# +------------------------- min (0 - 59) # | +-------------------- hour (0 - 23) # | | +--------------- day of month (1 - 31) # | | | +---------- month (1 - 12) # | | | | +----- day of week (0 - 7) (Sunday=0 or 7) # | | | | | # * * * * * # this requires phpbu to be in the cron users path 10 3 * * * phpbu --configuration=/var/www/my-backup/phpbu.xml # alternatively you can specify the full path #10 3 * * * /home/user/bin/phpbu.phar --configuration=/var/www/my-backup/phpbu.xml # some systems require the full path to the PHP CLI binary #10 3 * * * /etc/php/sbin/php /home/user/bin/phpbu.phar --configuration=/var/www/my-backup/phpbu.xml