Symbolic link handling

When transferring files by using FASP (the Aspera GUI, ascp, ascp4, or async), you can configure how the server and client handle symbolic links.

Note: Symbolic links are not supported on Windows. Server settings are ignored on Windows servers. If the transfer destination is a Windows computer, the only supported option that the client can use is skip.

Symbolic link-handling options and their behavior

  • Follow: Follow a symbolic link and transfer the contents of the linked file or directory when the link target is in the user's docroot.
  • Follow_wide (Server only): For downloads, follow a symbolic link and transfer the contents of the linked file or directory even if the link target is outside of the user's docroot. Use caution with this setting because it might allow transfer users to access sensitive files on the server.
  • Create (Server only): If the client requests to copy symbolic links in an upload, create the symbolic links on the server.
  • None (Server only): Prohibit clients from creating symbolic links on the server. With this setting, clients can request only to follow or skip symbolic links.
  • Copy (Client only): Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link does not replace the file.
  • Copy+force (Client only): Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link replaces the file. If the file of the same name at the destination is a symbolic link to a directory, it is not replaced.
    Note: Ascp4 and Sync do not support the copy+force option.
  • Skip (Client only): Skip-symbolic links. The link or the file to which it points are not transferred.

Symbolic link handling depends on the server configuration, the client-handling request, and the direction of transfer, as described in the following tables. Multiple values can be set on the server as a comma-delimited list, such as the default follow,create. In this case, the options are logically ordered based on the client's handling request.

Send from client to Server (Upload)

  Server setting = create, follow (default) Server setting = create Server setting = follow Server setting = follow_wide Server setting = none
Client setting = follow

(default for ascp and ascp4)

Follow Follow Follow Follow Follow
Client setting = copy

(default for async)

Copy Copy Skip Skip Skip
Client setting = copy+force Copy and replace any existing files. Copy and replace any existing files. Skip Skip Skip
Client setting = skip Skip Skip Skip Skip Skip

Receive to client from Server (Download)

  Server setting = create, follow (default) Server setting = create Server setting = follow Server setting = follow_wide Server setting = none
Client setting = follow

(default for ascp and ascp4)

Follow Skip Follow Follow even if the target is outside the user's docroot. Skip
Client setting = copy

(default for async)

Copy Copy Copy Copy Copy
Client setting = copy+force Copy and replace any existing files. Copy and replace any existing files. Copy and replace any existing files. Copy and replace any existing files. Copy and replace any existing files.
Client setting = skip Skip Skip Skip Skip Skip

Server and client configuration

Server configuration

In the GUI, go to Configuration > File Handling and set a value for Symbolic Link Actions (see also File handling configuration). Combinations of actions must be set from the command line by using asconfigurator or manually editing aspera.conf.

To set symbolic link handling globally or per user, run the appropriate command:

> asconfigurator -x "set_node_data;symbolic_links,value"
> asconfigurator -x "set_user_data;user_name,username;symbolic_links,value"

Client configuration

Transfers initiated in the GUI request that symbolic links be followed, which cannot be adjusted. To specify symbolic link handling on the command line (with ascp, ascp4, or async), use --symbolic-links=option.