Chapter 2. Configuration

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.

XML-Configuration

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>


List of tags

<phpbu>

The XML root element with at least xmlns:xsi and xsi:noNamespaceSchemaLocation.

Table 2.1. <phpbu> attributes

NameValuesRequiredDefaultDescription
bootstrapfilenamenonullInclude a PHP file to extend PHPBU
verbosetrue | falsenofalseControls the output verbosity
debugtrue | falsenofalseControls the debug output


<backup>

Configures a backup process. You can have as many of these as you need.

Table 2.2. <backup> attributes

NameValuesRequiredDefaultDescription
namestringyesnullA custom name for your backup used in the PHPBU output.
stopOnErrortrue | falsenofalseIndicates if the execution of PHPBU should be stopped if this backup fails.


<source>

Defines the data that is backed up.

Table 2.3. <source> attributes

NameValuesRequiredDefaultDescription
typestringyes-Type of backup, Chapter 5 has a list of all supported source types.


<target>

Defines where the backup is stored.

Table 2.4. <target> attributes

NameValuesRequiredDefaultDescription
dirnamestringyes-Path to the directory where the backup is stored, absolute or relative to the config file.
filenamestringyes-Filename of the stored backup.
compressstringnonullType of compressor to use to compress the backup.


<check>

Specifies what kind of tests should be performed to validate the backup.

Table 2.5. <check> attributes

NameValuesRequiredDefaultDescription
typestringyes-Type of check, Chapter 6 has a list of all supported check types.
valuestringyes-Value the backup is getting checked against.


<crypt>

Specifies what type of encryption should be used to encrypt the backup.

Table 2.6. <crypt> attributes

NameValuesRequiredDefaultDescription
typestringyes-Type of encryption, Chapter 7 has a list of all supported crypt types.
skipOnFailuretrue | falsenofalseYou can still execute the encryption, even if failure(s) occurred.


<sync>

Copy the created backup to another location.

Table 2.7. <sync> attributes

NameValuesRequiredDefaultDescription
typestringyes-Type of sync, Chapter 8 has a list of all supported sync types.
skipOnFailuretrue | falsenofalseYou can still execute the sync, even if failure(s) occurred.


<cleanup>

Tells phpbu which files to delete after a successful backup.

Table 2.8. <cleanup> attributes

NameValuesRequiredDefaultDescription
typestringyes-Type of cleanup, Chapter 9 has a list of all supported cleanup types.
skipOnFailuretrue | falseno-You can still execute the cleanup, even if failure(s) occurred.


<option>

A simple key value tag to configure <source>, <crypt>, <sync> and <cleanup>.

Table 2.9. <option> attributes

NameValuesRequiredDefaultDescription
namestringyes-Option key.
valuestringyes-Option value.


JSON-Configuration

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

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"
      }
    }
  ]
}


Schedule backups

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

        


Please open a ticket on GitHub to suggest improvements to this page. Thanks!