Rename

Renames a file or directory in a backup to match a corresponding name change in the filesystem.

$ hb rename [-c backupdir] origpath newpath

If dedup is activated, rename is not that important because HashBackup will usually save renamed objects without using much new backup space, but it will have to read every renamed file. Rename changes the path in the backup to match the path in the filesystem so the next backup will not have to read renamed files again. This might be necessary for a structural change in a huge filesystem migration.

Rename is limited to:

  • changing the last pathname component

  • moving a path to one of its parent directories

  • moving a path to a different existing directory

  • a combination of these

  • it does not work on sharded backups

Examples of renames that work:

/home/jim -> /home/fred
/mnt/data -> /mnt/storage
/home/jim -> /jim
/Users    -> /home
/Users/ab -> /xy

Examples of renames that may fail:

/Users/jim -> /home/jim         fails if /home/jim already exists
/Users/jim -> /Users/fred/jim   fails if /Users/fred doesn't already exist

The original path is renamed in ALL versions. If a directory is renamed, all files in it are also renamed.

Unlike the Unix mv command, rename requiers the complete new pathname, ie, to move /home/jim to /, use /jim as the newpath, not just /.

It is a good idea to run hb compare after a rename to make sure that the backup matches the filesystem. If compare shows a lot of changed files with inodes changing, it means that the next backup will have to read the renamed files after all. Enable dedup to minimize the amount of data that has to be re-saved.

If rename can’t do what you need to make pathnames match, a bind mount on Linux or nullfs mount on FreeBSD might work to make your filesystem tree appear with a new name:

$ mount --bind /nfs/snapshot.N /targetpath (Linux)

$ mount_nullfs /targetpath /nfs/snapshot.N (FreeBSD)

Then backup /targetpath with HashBackup.

Example #1

In this example, a file abc is created under /mnt/tank/files and backed up with HashBackup. The filesystem layout is changed by moving /mnt/tank to /tank, and the hb rename command is used to adjust the backup to reflect the new filesystem layout. When /tank is backed up again, no new files are saved.

[jim@mb ~]$ hb init -c hb
HashBackup build #1926 Copyright 2009-2017 HashBackup, LLC
Backup directory: /Users/jim/hb
Permissions set for owner access only
Created key file /Users/jim/hb/key.conf
Key file set to read-only
Setting include/exclude defaults: /Users/jim/hb/inex.conf

VERY IMPORTANT: your backup is encrypted and can only be accessed with
the encryption key, stored in the file:
    /Users/jim/hb/key.conf

You MUST make copies of this file and store them in a secure location,
separate from your computer and backup data.  If your hard drive fails,
you will need this key to restore your files.  If you setup any
remote destinations in dest.conf, that file should be copied too.

Backup directory initialized

[jim@mb ~]$ ls /mnt

[jim@mb ~]$ sudo sh
Password:

sh-3.2# mkdir /mnt/tank

sh-3.2# mkdir /mnt/tank/files

sh-3.2# echo abc >/mnt/tank/files/abc

sh-3.2# hb backup -c hb /mnt
HashBackup build #1926 Copyright 2009-2017 HashBackup, LLC
Backup directory: /Users/jim/hb
Backup start: 2017-08-08 11:41:12
Copied HB program to /Users/jim/hb/hb#1926
This is backup version: 0
Dedup not enabled; use -Dmemsize to enable
/mnt
/mnt/tank
/mnt/tank/files
/mnt/tank/files/abc
/Users/jim/hb/inex.conf`

Time: 0.4s
CPU:  0.1s, 30%
Mem:  54 MB
Checked: 9 paths, 515 bytes, 515 bytes
Saved: 9 paths, 515 bytes, 515 bytes
Excluded: 0
Dupbytes: 0
Compression: 40%, 1.7:1
Efficiency: 0.00 MB reduced/cpusec
Space: 304 bytes, 139 KB total
No errors

sh-3.2# hb rename -c hb /mnt/tank /tank
HashBackup build #1926 Copyright 2009-2017 HashBackup, LLC
Backup directory: /Users/jim/hb
New path doesn't exist in your filesystem.  Rename anyway? yes
Renaming path /mnt/tank to /tank

sh-3.2# mv /mnt/tank /tank

sh-3.2# hb backup -c hb /tank
HashBackup build #1926 Copyright 2009-2017 HashBackup, LLC
Backup directory: /Users/jim/hb
Backup start: 2017-08-08 11:42:01
This is backup version: 1
Dedup not enabled; use -Dmemsize to enable

Time: 0.1s
CPU:  0.1s, 57%
Mem:  53 MB
Checked: 8 paths, 515 bytes, 515 bytes
Saved: 4 paths, 0 bytes, 0 bytes
Excluded: 0
No errors

Example #2

This example is similar, but instead of changing the filesystem tree with the Unix mv command, the Unix cp command is used instead. The big difference is that the mv command preserves the inode and ctime fields of each file, while the cp command does not. Because the inode and ctime fields have changed, HashBackup will re-read each file to verify that the data is identical to the backup. If dedup is enabled on both backups, very little new data will be saved. If dedup was not enabled, HashBackup will have to save all files again.

sh-3.2# mkdir /mnt/tank

sh-3.2# mkdir /mnt/tank/files

sh-3.2# dd if=/dev/urandom of=/mnt/tank/files/bigfile bs=1m count=500
500+0 records in
500+0 records out
524288000 bytes transferred in 36.657870 secs (14302195 bytes/sec)

sh-3.2# hb init -c hb
HashBackup build #1926 Copyright 2009-2017 HashBackup, LLC
Backup directory: /Users/jim/hb
Permissions set for owner access only
Created key file /Users/jim/hb/key.conf
Key file set to read-only
Setting include/exclude defaults: /Users/jim/hb/inex.conf

VERY IMPORTANT: your backup is encrypted and can only be accessed with
the encryption key, stored in the file:
    /Users/jim/hb/key.conf

You MUST make copies of this file and store them in a secure location,
separate from your computer and backup data.  If your hard drive fails,
you will need this key to restore your files.  If you setup any
remote destinations in dest.conf, that file should be copied too.

Backup directory initialized

sh-3.2# hb backup -c hb /mnt -D1g
HashBackup build #1926 Copyright 2009-2017 HashBackup, LLC
Backup directory: /Users/jim/hb
Backup start: 2017-08-08 16:56:18
Copied HB program to /Users/jim/hb/hb#1926
This is backup version: 0
Dedup enabled, 0% of current, 0% of max
/mnt
/mnt/tank
/mnt/tank/files
/mnt/tank/files/bigfile
/Users/jim/hb/inex.conf

Time: 7.8s
CPU:  10.9s, 138%
Mem:  99 MB
Checked: 9 paths, 524288511 bytes, 524 MB
Saved: 9 paths, 524288511 bytes, 524 MB
Excluded: 0
Dupbytes: 0
Space: 524 MB, 524 MB total
No errors

sh-3.2# cp -rp /mnt/tank /tank

sh-3.2# hb rename -c hb /mnt/tank /tank
HashBackup build #1926 Copyright 2009-2017 HashBackup, LLC
Backup directory: /Users/jim/hb
Renaming path /mnt/tank to /tank
sh-3.2# *hb backup -c hb /tank -D1g*
HashBackup build #1926 Copyright 2009-2017 HashBackup, LLC
Backup directory: /Users/jim/hb
Backup start: 2017-08-08 16:57:33
This is backup version: 1
Dedup enabled, 5% of current, 0% of max
/tank
/tank/files
/tank/files/bigfile    <==  file is saved again because inode has changed

Time: 4.2s
CPU:  5.0s, 118%
Mem:  79 MB
Checked: 8 paths, 524288511 bytes, 524 MB
Saved: 7 paths, 524288000 bytes, 524 MB
Excluded: 0
Dupbytes: 524288000, 524 MB, 100%    <== dedup is on so no new data is saved
Space: 0 bytes, 525 MB total
No errors