1. Intro

BackupPC v4.x uses a better way to store data as compared to v3. Performance is for example higher in v4, which in itself is quite interesting!

The conversion is seamless and the migration tool is included in all BackupPC v4-versions.

The migration tool is called BackupPC_migrateV3toV4 and can in CentOS usually be found in /usr/share/BackupPC/bin.

This guide collects the basic steps to perform the migration, as well as document some errors you may encounter (which I did).



2. Guide

Let's get on with it!


2.1. Initial check

Before starting the migration you may want to check you have enough inodes available. The recommendation is to have under 45 % inode usage in your _TOPDIR_.

Use df to find out. My _TOPDIR_ is /bak, so:

# df -i /bak
Filesystem Inodes IUsed IFree IUse% Mounted on
/dev/md0 183156736 19968199 163188537 11% /bak

Eleven percent is well below 45 %, so we're good to go.


2.2. Test run 

You may want to do a test run first on a single host and backup, without actually doing any changes. Use the -m flag for that purpose.

You also need to be the user backuppc, not root, to run the migration.

The -h flag specifies the host name as seen in /bak/pc and -n specifies the backup number.

The BackupPC daemon further needs to be stopped before running the command. Stop the daemon, check its daemon status, then run the test.

# service backuppc stop
Stopping BackupPC: [ OK ]

# service backuppc status
BackupPC is stopped

# su -s /bin/bash - backuppc
# cd /bak
# /usr/share/BackupPC/bin/BackupPC_migrateV3toV4 -h -n 542 -m

BackupPC_migrateV3toV4: migrating host backup #542 to V4 (approx 2577 files)
BackupPC_migrateV3toV4: got 0 errors

If all looks good, we're ready to do a first migration.

The BackupPC documentation suggests you do a backup of your V3 pool. Search for the phrase cautious approach here;


2.3. First migration

It might be a good idea to run the migration on a single host and backup, so we use the same host and backup as in the test run above, but omitt the -m flag.

# /usr/share/BackupPC/bin/BackupPC_migrateV3toV4 -h -n 542

BackupPC_migrateV3toV4: migrating host backup #542 to V4 (approx 2577 files)
BackupPC_migrateV3toV4: removing temp target directory /var/lib/BackupPC//pc/
substr outside of string at /usr/share/BackupPC/lib/BackupPC/ line 722.

And sure enough, we do run into a problem...

A Google search later we find a suggestion from the BackupPC creator Craig Barrat himself at

So, as root, open the file mentioned in the error description and find line 722. Edit it as suggested in the link above, save the file and exit the editor.

# nano /usr/share/BackupPC/lib/BackupPC/
# su -s /bin/bash - backuppc
# cd /bak
# /usr/share/BackupPC/bin/BackupPC_migrateV3toV4 -h -n 542

BackupPC_migrateV3toV4: migrating host backup #542 to V4 (approx 2577 files) #542: 5.7% #542: 6.0% #542: 6.3%

Depending on how big your backup is and how fast your disk array is, this may take a long while...


If you feel confident you may convert all hosts and backups at once.

The -a flag tells the tool to migrate all hosts and all backups. 

This may take even longer.

# su -s /bin/bash - backuppc
# cd /bak
# /usr/share/BackupPC/bin/BackupPC_migrateV3toV4 -a

BackupPC_migrateV3toV4: migrating host backup #542 to V4 (approx 2577 files) #542: 5.7% #542: 6.0% #542: 6.3%

The brunt of the migration is now done. I suggest you take a break now from the migration, eg $Conf{PoolSizeNightlyUpdatePeriod} days.


2.4. Disabling the V3 pools

You may now want to disable the V3 pools in either the web-GUI or directly in /etc/BackupPC/

Note! The V3 pool should now be empty, but make really sure they actually are. You can confirm this by letting BackupPC run enough times, specifically as many times as $Conf{PoolSizeNightlyUpdatePeriod} indicates. 
BackupPC_nightly defaults to 16, but you may change it as needed.


2.4.1. Web-GUI alternative

Find the web-GUI setting in Edit Config/Server/PoolV3Enabled and uncheck it. Don't forget to click the Save-button!



Finalize the change by finding the Admin Options in the left-side panel in the web-GUI, click it, then press the Reload button on Reload the server configuration.


2.4.2. CLI alternative 

You can also edit the file directly.

# cd /etc/BackupPC
# nano

Find $Conf{PoolV3Enabled} and change the 1 to 0.

Save and exit.

Restart the BackupPC daemon for good measure.

[root@server1 ~]# service backuppc restart
Shutting down BackupPC: [ OK ]
Starting BackupPC: [ OK ]
[root@server1 ~]#


3. Conclusion

That's all there is to it.

Don't forget to start your BackupPC daemon again when done!

# service backuppc start
Starting BackupPC: [OK]

# service backuppc status
BackupPC (pid 12345) is running...


4. Sources