borg create should follow symlinks pointed to by roots

[capi]

Have you checked borgbackup docs, FAQ, and open Github issues?

Yes

Is this a BUG / ISSUE report or a QUESTION?

Change Request

System information. For client/server mode post info for both machines.

Your borg version (borg -V).

borg 1.1.9

Operating system (distribution) and version.

Linux

Requested Change

If a specified root for borg create (either on command line or from pattern file) points to a symlink, the symlink should be followed and not the symlink as such being backed up.

Reasoning

It is unlikely that the user wants to backup the symlink and not its content. Maybe make it like rsync, where a trailing / would indicate to follow the symlink, if it's not desired as a default option.

Real-world example

I've got a server that collects backups using urbackup and for some of the clients I want to backup /var/lib/urbackup/client/current/, where this is a symlink to the latest backup.

[ThomasWaldmann]

well, you could just give the result of readlink SYMLINK to borg.

[capi]

That would be a good solution for roots specified as part of the command line, but doesn't work well with --patterns-from, which I now try to use explictly.

[capi]

An additional advantage for following the symlink in this case would be, that the paths are more stable and that change detection (urbackup uses hardlinks or btrfs subvolumes) would be way faster and not require reading the entire content.

If I specify all the subdirectories of the symlink individually, all works as I'd expect already.

[ThomasWaldmann]

It should be possible to mix patterns files and cli arguments.

And if a outside borg solution is as simple as that, that is preferable to implementing inconsistent / irregular behaviour inside borg. Or adding special command line switches. All such additional / special stuff needs to be documented and the longer the docs get, the less likely people will actually read them.

[capi]

I agree, and I understand. The mixing solution does not help with the "stable" paths, though.

[ThomasWaldmann]

If the symlink target is unstable, no, then it does not help. But a bind mount would help in that case.

[ThomasWaldmann]

Hmm, guess there is a very fundamental issue with this feature request:

If the goal is to follow given roots that are symlinks and to have "stable pathes", so that the files cache works ok even if the symlink target has a changing name, it could be done in 2 ways:

• using FOLLOW mode for operations - that is desired for the root, but not desired for everything below. as we can only FOLLOW (root path) or NO_FOLLOW (sub-path) that simply does not work.

• adding code to borg that internally manages everything related to path computations (by computing a symlink_root + subpath name as key for the files cache while using readlink(symlink_root) + subpath for all other purposes (stat, open). seems to add quite a bit of additional complexity.

[capi]

I agree that this adds complexity that's likely not desired and not warranted. Therefore I vote to close it as won't fix.

I think, the command line use-case can actually be worked around by letting the shell do the work:

borg create archive /path/with/symlink/* /path/with/symlink/.*

A similar solution could work for pattern-files, if roots could have wildcards. Would this be something that could be implemented with justifiable efforts? In that case, I'd open a new feature request for that, i.e.

R /path/with/symlink/*
R /path/with/symlink/.*

[devsr]

Stumbled across this wasn't sure if I should make a new feature request. I think it would be a nice-to-have feature if borg were consistent with cp -r on how it handles symlinks as the last element in a source path. Currently borg will already dereference a symlink in a source path as long as the symlink isn't the last element.

if as above /path/with/symlink refers to a symlink, examples follow

1. Stores only the symlink as expected.

borg create $ARCHIVE /path/with/symlink

2. Stores dereferenced symlink as a directory as expected. ("$CONTENT" can be anything except ".") .

borg create $ARCHIVE /path/with/symlink/$CONTENT

3. Stores only the symlink. Not consistent with cp -r or which would dereference the symlink.

borg create $ARCHIVE /path/with/symlink/

4. Stores only the symlink. Not consistent with cp -r which would dereference the symlink. Additionally this would cause cp -r to exclude the directory but copy the contents, but that behavior isn't applicable to borg which stores the full path anyway.

borg create $ARCHIVE /path/with/symlink/.

Arguably the fourth example not working is a bug as the last path element does not refer to a symlink and is inconsistent with the behavior exhibited in the second example.

Also providing a source path /path/with/symlink/. which forces borg to dereference the symlink would be preferable to the current workaround of using /path/with/symlink/* /path/with/symlink/.* as it would not rely on shell expansion.

[ThomasWaldmann]

@devsr thanks for the detailled analysis.

the reason why /path/with/symlink, /path/with/symlink/ and /path/with/symlink/. don't make a difference for borg is that it all is normalized there:

https://github.com/borgbackup/borg/blob/1.1.15/src/borg/archiver.py#L541

https://docs.python.org/3.8/library/os.path.html#os.path.normpath

 >>> from os.path import normpath as opn
>>> opn('/path/with/symlink')
'/path/with/symlink'
>>> opn('/path/with/symlink/')
'/path/with/symlink'
>>> opn('/path/with/symlink/.')
'/path/with/symlink'

[ThomasWaldmann]

More experiments:

lrwxrwxrwx 1 user user    6 Feb 24 17:34 symlink -> target
drwxr-xr-x 2 user user 4096 Feb 24 17:33 target

>>> import os
>>> os.stat('target', follow_symlinks=False)
os.stat_result(st_mode=16877, st_ino=230230, st_dev=51728, st_nlink=2, st_uid=1000, st_gid=1000, st_size=4096, st_atime=1614184455, st_mtime=1614184427, st_ctime=1614184427)

>>> os.stat('symlink', follow_symlinks=False)
os.stat_result(st_mode=41471, st_ino=87001, st_dev=51728, st_nlink=1, st_uid=1000, st_gid=1000, st_size=6, st_atime=1614184457, st_mtime=1614184441, st_ctime=1614184441)

>>> os.stat('symlink/', follow_symlinks=False)
os.stat_result(st_mode=16877, st_ino=230230, st_dev=51728, st_nlink=2, st_uid=1000, st_gid=1000, st_size=4096, st_atime=1614184455, st_mtime=1614184427, st_ctime=1614184427)

>>> os.stat('symlink/.', follow_symlinks=False)
os.stat_result(st_mode=16877, st_ino=230230, st_dev=51728, st_nlink=2, st_uid=1000, st_gid=1000, st_size=4096, st_atime=1614184455, st_mtime=1614184427, st_ctime=1614184427)

[ThomasWaldmann]

Hmm, i currently think that modifying behaviour to differentiate for these case is not useful.

If we just consider restoring a backup, what we want to achieve is that we can restore "symlink" as a symlink and that we also can restore "target" as a directory (+ contents). Thus, both have to be in the archive.

If we would implement special behaviour for "symlink/" (or "symlink/."), we would get this into archive:

• a directory item with path "symlink/" (or "symlink/.") with the metadata from the "target" directory
• file items contained in this directory would be archived as "symlink/file" (or "symlink/./file")
• we would not know that "symlink" was a symlink though!
• we would not have an item for "target"

So, I think if a recursion root (path given to borg create command) happens to be a symlink, then you have to call borg like this:

borg create REPO::ARCHIVE symlink target

Then all items you need for restore will be in the archive.
Also, items below target will be archived as "target/filename" (not "symlink/filename" or so).

[devsr]

@ThomasWaldmann

My use case (which I grant, maybe very specific) is I'm trying to use symlinks to make better use of borg's file cache when targeting snapshot mounts that are auto generated by ZFS on Linux.

The snaps look like so

zfs_snap=$ZFSMOUNTPOINT/.zfs/snapshot/$SNAPSHOT

and could be linked like so

ln $zfs_snap /backup/$ZFSNAME
borg create $ARCHIVE /backup/$ZFSNAME/.

It hadn't occurred to me to stat
this is what I got from bash for comparison which matches your output.

bash-4.2# mkdir target

bash-4.2# ln -s target symlink

bash-4.2# ls -ln .
total 4
lrwxrwxrwx. 1 0 0    6 Feb 24 16:02 symlink -> target
drwxr-xr-x. 2 0 0 4096 Feb 24 16:02 target

bash-4.2# stat --format="%n is a %F" target
target is a directory

bash-4.2# stat --format="%n is a %F" symlink
symlink is a symbolic link

bash-4.2# stat --format="%n is a %F" symlink/
symlink/ is a directory

bash-4.2# stat --format="%n is a %F" symlink/.
symlink/. is a directory

I appreciate that you responded to me on an issue I dug up from over a year ago, if you think this feature request is a dead end I'll leave it be and use workarounds (like bind mounting or the shell expansion mentioned earlier). I just wanted poke this issue and see if there was some merit to implementation parity with stat re: identifying a recursive root that is actually a symlink.

[devsr]

Some more experiments with tar

Setup

bash-4.2# tree -p
.
|-- [lrwxrwxrwx]  symlink -> target
`-- [drwxr-xr-x]  target
    `-- [-rw-r--r--]  hello.txt

bash-4.2# tar --version
tar (GNU tar) 1.26

bash-4.2# alias tar='tar --posix --numeric-owner'

1. archives the symlink as a symlink, no surprises here.

bash-4.2# tar -cvvf a.tar target symlink

drwxr-xr-x 0/0               0 2021-02-25 22:11 target/
-rw-r--r-- 0/0               0 2021-02-25 22:11 target/hello.txt
lrwxrwxrwx 0/0               0 2021-02-24 16:02 symlink -> target

2. Archives the symlink as a symlink same as before
   This is appears to be a departure from cp -r and stat. POSIX describes that path resolution must follow the link if it ends in a slash.

bash-4.2# tar -cvvf a.tar target/ symlink/
drwxr-xr-x 0/0               0 2021-02-25 22:11 target/
-rw-r--r-- 0/0               0 2021-02-25 22:11 target/hello.txt
lrwxrwxrwx 0/0               0 2021-02-24 16:02 symlink -> target

3. Archives the symlink as a directory. This is in keeping with POSIX.
   The symlink is now encountered as part of the dirname instead of the basename so it must be followed.
   It archives the second occurrence file hello.txt as a hardlink due to the matching inode.

bash-4.2# tar -cvvf a.tar target/. symlink/.
drwxr-xr-x 0/0               0 2021-02-25 22:11 target/./
-rw-r--r-- 0/0               0 2021-02-25 22:11 target/./hello.txt
drwxr-xr-x 0/0               0 2021-02-25 22:11 symlink/./
hrw-r--r-- 0/0               0 2021-02-25 22:11 symlink/./hello.txt link to target/./hello.txt

As an aside the linux man page for symlink(7) also discusses treamtment of symlinks when given as basename part of a path argument on the command-line.

[ThomasWaldmann]

Also using GNU tar and the same alias as above for arching only the directory pointed to by symlink:

$ tar -cvvf a.tar symlink/.
drwxr-xr-x 1000/1000         0 2021-02-27 14:12 symlink/./
-rw-r--r-- 1000/1000         0 2021-02-27 14:12 symlink/./hello.txt

This is likely how people would use it if we added this (not caring about that the symlink is not archived as symlink and that the target path does not appear at all in the archive).

But if you restore that, you do not end with the same state in the filesystem as when you archived it.