Create and read OSS symlinks by using a mount point

Relative and absolute symlink targets

A symlink target can be an absolute path or a relative path. An absolute target is resolved from the file system root directory / and is independent of the link's own location. A relative target is resolved from the directory that contains the link, not from the current working directory. What the path is relative to determines how a symlink behaves and is the most common source of misunderstandings.

Consider the following example. Assume that the mount point is /mnt/ossfs and the bucket contains the object oss://<bucket>/a/c/target. In the directory oss://<bucket>/a/b/, you want to create the link oss://<bucket>/a/b/link that points to that object:

ln -s ../c/target /mnt/ossfs/a/b/link

When the kernel resolves this link, it starts from the local directory that contains the link, /mnt/ossfs/a/b/, and appends the target: /mnt/ossfs/a/b/ + ../c/target = /mnt/ossfs/a/c/target. The result does not depend on the directory in which you run the command. Running cat /mnt/ossfs/a/b/link from any working directory resolves to the same object. If you assume that ../c/target is resolved from the working directory, your expectation of the link's destination will be wrong.

Note that readlink does not return the exact string that you passed when you created the link. It returns a normalized relative path, for example ../../a/c/target in the preceding example. The normalized value restates the target location from the mount point root, and following the link resolves to the same object as when you created it.

OSS Symlink objects and console compatibility

OSS natively supports Symlink objects. A Symlink object is created by using the PutSymlink operation, its target is stored in the x-oss-symlink-target header, and the target is read by using the GetSymlink operation. Note that the PutSymlink operation does not validate the target, so you can technically store any string. The requirement that "the target must be an object name in the bucket" is a parsing convention of the OSS console. When the console displays or navigates to a Symlink object, it parses the target as an object name in the bucket. If the target is stored in another form, such as an absolute path, the console cannot recognize or navigate to it, and the link becomes a dead link.

In other words, the console resolves targets from the bucket root, which differs from the POSIX rule that a relative symlink is resolved from the directory that contains the link. Using the preceding example, the same link a/b/link that points to a/c/target has different target strings depending on the perspective:

The symlink implementation of ossfs 2.0 follows this convention and converts between the two resolution bases. A link created on the mount point stores its target as a bucket-relative path (for example, a/c/target), which the console can recognize and navigate to. A Symlink object created by using an API or the console with a bucket-relative target can also be read with readlink and followed on the mount point. If the target is an absolute path that starts with /, reading the link on the mount point returns EINVAL.

Use the command line

The following example uses the mount point /mnt/ossfs. It creates a link in /mnt/ossfs/a/b/ that points to /mnt/ossfs/a/c/target. The target must be a relative path:

cd /mnt/ossfs/a/b
ln -s ../c/target link

# Or skip the cd command
ln -s ../c/target /mnt/ossfs/a/b/link

# Read the link target. The command returns the normalized relative path (../../a/c/target).
readlink /mnt/ossfs/a/b/link

# Follow the link to read the target content
cat /mnt/ossfs/a/b/link

Use a Python script

When you create links in batches, convert the target to a path that is relative to the directory that contains the link. Unlike ossfs 2.0 at run time, which cannot determine which bucket an absolute path belongs to, the script receives the mount point from you and can accept local absolute paths and convert them.

#!/usr/bin/env python3
"""Create relative symlinks on an ossfs 2.0 mountpoint.

Usage: python3 create_oss_symlink.py <mountpoint> <link_path> <target_path>
All arguments are local paths; <link_path> and <target_path> must be under
<mountpoint>. The script converts the target into a path relative to the
link's parent directory, so that ossfs 2.0 stores it as an in-bucket object
name.
"""
import os
import sys


def create_relative_symlink(mountpoint, link_path, target_path):
    mountpoint = os.path.realpath(mountpoint)

    def to_bucket_rel(p):
        # Lexical conversion, consistent with ossfs 2.0: no symlink
        # expansion, inner ".." folded literally.
        p = os.path.normpath(os.path.abspath(p))
        if not p.startswith(mountpoint + os.sep):
            raise ValueError(f"path escapes the mountpoint: {p}")
        return os.path.relpath(p, mountpoint)

    # Bucket-relative object name of the target (what OSS actually stores).
    bucket_target = to_bucket_rel(target_path)
    link_path = os.path.abspath(link_path)
    if not link_path.startswith(mountpoint + os.sep):
        raise ValueError(f"link path escapes the mountpoint: {link_path}")

    # POSIX readlink semantics: relative to the link's parent directory.
    link_parent_rel = os.path.relpath(os.path.dirname(link_path), mountpoint)
    relative_target = os.path.relpath(bucket_target, link_parent_rel)

    if os.path.lexists(link_path):
        os.remove(link_path)
    os.symlink(relative_target, link_path)
    print(f"{link_path} -> {relative_target}")


if __name__ == "__main__":
    if len(sys.argv) != 4:
        print(__doc__)
        sys.exit(1)
    create_relative_symlink(sys.argv[1], sys.argv[2], sys.argv[3])

Example:

python3 create_oss_symlink.py /mnt/ossfs /mnt/ossfs/a/b/link /mnt/ossfs/a/c/target

The script converts the target from the mount point root. If oss_bucket_prefix is configured when you mount the bucket, the object name that OSS actually stores is the prefix followed by the bucket-relative path used by the script. ossfs 2.0 performs this conversion automatically, and the way you use the script does not change.