Docs

Torch Object Storage

FSX best practices

Recommendations for accessing symlinks in Linux

This topic explains the implementation mechanisms and usage recommendations for TOS symlinks in Linux systems, to help you correctly access and use TOS symlinks in Linux.

Implementation mechanism

After a bucket is mounted on a Linux system using FSX, the system may not be able to resolve the target object path of a symlink in the bucket, because the TOS console and standard file systems handle symlinks differently. The following explains the implementation mechanisms for symlinks in the TOS console, TOS APIs, and standard file systems:

In a standard Linux file system, resolving a path when accessing a symlink works as follows:

For absolute paths, the system starts at the root directory (/) and resolves the path step by step through directory lookups until reaching the final target object.

For relative paths, the system uses the current working directory at the time the symlink was created as its base. The system then converts the relative path into an absolute path and continues the lookup based on this absolute path.

For a symlink created via the TOS console, the target object path is relative to the bucket's root directory. Once the bucket containing the symlink is mounted on an ECS instance, the symlink appears as a symbolic link in the file system. At that point, the target object path is resolved as a file path relative to the mounted bucket's root directory.

TOS APIs allow for the creation of symlinks and support path referencing, similar to a standard file system. Once a bucket is mounted to an ECS instance, the target object path of a symlink created via a TOS API in the bucket is resolved as a relative path starting from the directory where the symlink is located.

Recommendations

Standard file systems cannot resolve the target object paths of symlinks created via the TOS console. However, symlinks created via TOS APIs can be accessed normally. To use TOS symlinks in a Linux system, create them via a TOS API so that they can be recognized and resolved correctly. For instructions on how to create a symlink via a TOS API, see PutSymlink.

When using PutSymlink to create a symlink, set the x-tos-symlink-target parameter to the relative path of the object that the symlink points to in Linux. You can use Python to calculate the target object path for the x-tos-symlink-target parameter value. A sample is shown below:

warning

If you only mount a prefix of a bucket on an ECS instance, both the symlinks and their target objects must be located under that prefix. Otherwise, accessing the symlinks in Linux will fail.

Last updated: 2025.11.25 14:05:57