Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The Create Symbolic Link operation creates a new symbolic link to an existing file. This operation is supported in version 2025-07-05 and later only for File Shares with NFS protocol enabled.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS |  |
Request
The Create Symbolic Link request is constructed as follows. We recommend that you use HTTPS.
| Method | Request URI | HTTP version |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/mysymboliclink?restype=symboliclink |
HTTP/1.1 |
Replace the path components that are shown in the request URI with your own, as described in the following table:
| Path component | Description |
|---|---|
myaccount |
The name of your storage account. |
myshare |
The name of your file share. |
mydirectorypath |
Optional. The path to the directory where the symbolic link is to be created. If the directory path is omitted, the symbolic link will be created within the specified share. If the directory is specified, it must already exist within the share before you can create the symbolic link. |
mysymboliclink |
The name of the symbolic link to create. |
For information about path-naming restrictions, see Name and reference shares, directories, files, and metadata.
URI parameters
You can specify the following additional parameters on the request URI:
| Parameter | Description |
|---|---|
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Set timeouts for file service operations. |
Request headers
The required and optional request headers are described in the following table:
| Request header | Description |
|---|---|
Authorization |
Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage. |
Date or x-ms-date |
Required. Specifies the Coordinated Universal Time (UTC) time for the request. For more information, see Authorize requests to Azure Storage. |
x-ms-version |
Required for all authorized requests. Specifies the version of the operation to use for this request. This operation is supported in version 2025-05-05 and later for File Shares with NFS protocol enabled. For more information, see Versioning for the Azure Storage services. |
Content-Length |
Optional. Must be zero if present. |
x-ms-content-length |
Optional. Must be zero if present. |
x-ms-meta-name:value |
Optional. Name-value pairs that are associated with the file as metadata. Metadata names must adhere to the naming rules for C# identifiers. |
x-ms-file-creation-time: { now ¦ <DateTime> } |
Optional. The Coordinated Universal Time (UTC) creation time property for the file. A value of now may be used to indicate the time of the request. The default value is now. |
x-ms-file-last-write-time: { now ¦ <DateTime> } |
Optional. The Coordinated Universal Time (UTC) last write property for the file. You can use a value of now to indicate the time of the request. The default value is now. |
x-ms-owner |
Optional. The user identifier (UID) of the file owner to be set on the file. The default value is 0 (root). |
x-ms-group |
Optional. The group identifier (GID) of the file owner to be set on the file. The default value is 0 (root group). |
x-ms-link-text |
Required. Specifies the path to the target file to which symbolic link will be created. The path, whether absolute from the root of the share or relative to the symbolic link being created, is stored as provided, without being resolved. The value should be percent encoded. |
x-ms-client-request-id |
Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Files. |
x-ms-file-request-intent |
Required if Authorization header specifies an OAuth token. Acceptable value is backup. This header specifies that the Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action or Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action should be granted if they are included in the RBAC policy assigned to the identity that is authorized using the Authorization header. Available for version 2022-11-02 and later. |
x-ms-allow-trailing-dot: { <Boolean> } |
Optional. Version 2022-11-02 and later. The Boolean value specifies if a trailing dot present in request url should be trimmed or not. This header is ignored if the target is located on a File Share with NFS protocol enabled, which supports trailing dot by default. For more information, see Naming and referencing shares, directories, files, and metadata. |
Request body
None.
Sample request
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/mysymboliclink?restype=symboliclink HTTP/1.1
Request Headers:
x-ms-version: 2025-07-05
x-ms-date: Thu, 13 Mar 2025 06:58:30 GMT
x-ms-link-text: myfile
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=
Response
The response includes an HTTP status code and a set of response headers.
Status code
A successful operation returns status code 201 (Created). For information about status codes, see Status and error codes.
Response headers
The response for this operation includes the headers in the following table:
Common response headers
| Response header | Description |
|---|---|
Date |
A UTC date/time value that's generated by the service, which indicates the time when the response was initiated. |
ETag |
The ETag contains a value that represents the version of the file. The value is enclosed in quotation marks. |
Last-Modified |
Returns the date and time when the file was last modified. The date format follows RFC 1123. For more information, see Represent date/time values in headers. Any operation that modifies the directory or its properties updates the last modified time. Operations on files don't affect the last modified time of the directory. |
x-ms-request-id |
Uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshoot API operations |
x-ms-version |
Indicates the Azure Files version that's used to execute the request. |
x-ms-file-creation-time |
The UTC date/time value that represents the creation time property for the symbolic link. |
x-ms-file-last-write-time |
The UTC date/time value that represents the last write time property for the symbolic link. |
x-ms-file-change-time |
The UTC date/time that value that represents the change time property for the symbolic link. |
x-ms-file-file-id |
The file ID of the the newly created symbolic link. |
x-ms-file-parent-id |
The parent file ID of the newly created symbolic link. |
x-ms-client-request-id |
Used to troubleshoot requests and their corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header if it's present in the request and the value contains no more than 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it isn't present in the response. |
x-ms-mode |
The mode of the symbolic link. See POSIX file permissions (mode). |
x-ms-owner |
The user identifier (UID) of the symbolic link owner. |
x-ms-group |
The group identifier (GID) of the symbolic link owner. |
x-ms-file-file-type |
The type of the file. The value will be: 'SymLink'. |
Response body
None.
Sample response
Response Status:
HTTP/1.1 201 Created
Response Headers:
Date: Thu, 13 Mar 2025 06:58:31 GMT
ETag: "0x8DD61FC7700E64D"
Last-Modified: Thu, 13 Mar 2025 06:58:31 GMT
x-ms-version: 2025-07-05
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Authorization
Only the account owner may call this operation.
POSIX file permissions (mode)
POSIX file permissions can be specified either numerically in a 12-bit numeric octal format or in a symbolic "rwx" format. Examples:
- "0644" or "rw-r--r--": User (file owner) has read, write permission, Group has read permission, Others have read permission.
- "0755" or "rwxr-xr-x": User (file owner) has read, write and execute permission, Group has read and execute permission, Others have read and execute permission.
Numeric octal format
The three lowest order octal numbers represent the permissions for owner/user, group and others and is indicated using an octal number (0-7), formed using a bitwise combination of '4' (Read), '2' (Write), '1' (Execute). The highest order octal number (0-7) is used to indicate a combination of '4' (SetUID), '2' (SetGID), '1' (StickyBit) permissions.
| Format | Permission |
|---|---|
| 0700 | User (file owner) has read, write and execute permission. |
| 0400 | User has read permission. |
| 0200 | User has write permission. |
| 0100 | User has execute permission. |
| 0070 | Group has read, write and execute permission. |
| 0040 | Group has read permission. |
| 0020 | Group has write permission. |
| 0010 | Group has execute permission. |
| 0007 | Others have read, write and execute permission. |
| 0004 | Others have read permission. |
| 0002 | Others have write permission. |
| 0001 | Others have execute permission. |
| 4000 | Set effective user ID on file. |
| 2000 | Set effective group ID on file. |
| 1000 | Set to indicate that the file can be deleted or renamed only by file owner, directory owner or root user. |
Symbolic "rwx" format
Permissions for owner/user, group and others is indicated using a combination of 'r' (Read), 'w' (Write) and 'x' (Execute) characters.
| Format | Permission |
|---|---|
| rwx------ | User (file owner) has read, write and execute permission. |
| r-------- | User has read permission. |
| -w------- | User has write permission. |
| --x------ | User has execute permission. |
| ---rwx--- | Group has read, write and execute permission. |
| ---r----- | Group has read permission. |
| ----w---- | Group has write permission. |
| -----x--- | Group has execute permission. |
| ------rwx | Others have read, write and execute permission. |
| ------r-- | Others have read permission. |
| -------w- | Others have write permission. |
| --------x | Others have execute permission. |
Remarks
If the share does not exist, then the operation fails with the status code 404/'Not Found' (ShareNotFound).
If the parent directory of the symbolic link does not exist, then the operation fails with the status code 404/'Not Found' (ParentNotFound).
If the symbolic link to be created already exists, then the operation fails with the status code 409/'Conflict' (ResourceAlreadyExists).
Create Symbolic Link isn't supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot fails with the status code 400/'Bad Request' (InvalidQueryParameterValue).