Set File Properties
The Set File Properties operation sets system properties on the file. This operation is supported in version 2025-05-05 and later for File Shares with NFS protocol enabled.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS | |
Request
The Set File Properties 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/myfile?comp=properties |
HTTP/1.1 |
Replace the path components shown in the request URI with your own, as follows:
| Path component | Description |
|---|---|
myaccount |
The name of your storage account. |
myshare |
The name of your file share. |
mydirectorypath |
Optional. The path to the parent directory. |
myfile |
The name of the file. |
For information about path naming restrictions, see Name and reference shares, directories, files, and metadata.
URI parameters
You can specify the following additional parameters in the request URI:
| Parameter | Description |
|---|---|
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs for File service operations. |
Request headers
The required and optional request headers are described in the following tables:
Common request headers
| 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) 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. |
x-ms-cache-control |
Optional. Modifies the cache control string for the file. If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties won't return this property, unless it's explicitly set on the file again. |
x-ms-content-type |
Optional. Sets the file's content type. If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties won't return this property, unless it's explicitly set on the file again. |
x-ms-content-md5 |
Optional. Sets the file's MD5 hash. If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties won't return this property, unless it's explicitly set on the file again. |
x-ms-content-encoding |
Optional. Sets the file's content encoding. If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties won't return this property, unless it's explicitly set on the file again. |
x-ms-content-language |
Optional. Sets the file's content language. If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties won't return this property, unless it's explicitly set on the file again. |
x-ms-content-disposition |
Optional. Sets the file's Content-Disposition header.If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties won't return this property, unless it's explicitly set on the file again. |
x-ms-content-length: bytes |
Optional. Resizes a file to the specified size. If the specified byte value is less than the current size of the file, all ranges above the specified byte value are cleared. |
x-ms-file-creation-time: { preserve ¦ <DateTime> } |
Required, version 2019-02-02 to 2021-04-10. Optional, version 2021-06-08 and later. The Coordinated Universal Time (UTC) creation time property for a file. A value of preserve can be passed to keep an existing value unchanged. The default value is preserve. |
x-ms-file-last-write-time: { preserve ¦ <DateTime> } |
Required, version 2019-02-02 to 2021-04-10. Optional, version 2021-06-08 and later. The Coordinated Universal Time (UTC) last write property for a file. A value of preserve can be passed to keep an existing value unchanged. If preserve is specified and the size of the file is changed, the last write time is updated to the current time. If the size of the file is changed, but an explicit timestamp is provided, the explicit timestamp is used. The default value is preserve. |
x-ms-lease-id:<ID> |
Required if the file has an active lease. Available for version 2019-02-02 and later. This header is ignored if the file is located on a File Share with NFS protocol enabled, which doesn't support file leases. |
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're 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. |
SMB only request headers
| Request header | Description |
|---|---|
x-ms-file-change-time: { now ¦ <DateTime> } |
Optional. Version 2021-06-08 and later. The Coordinated Universal Time (UTC) change time property for the file, formatted in the ISO 8601 format. You can use a value of now to indicate the time of the request. The default value is now. |
x-ms-file-permission: { preserve ¦ <SDDL> ¦ <binary> } |
In versions 2019-02-02 to 2021-04-10, this header is required if x-ms-file-permission-key isn't specified. As of version 2021-06-08, both headers are optional. This permission is the security descriptor for the file specified in the Security Descriptor Definition Language (SDDL) or (version 2024-11-04 or later) in base64-encoded binary security descriptor format. You can specify which format to use with the x-ms-file-permission-format header. You can use this header if the permissions size is 8 kibibytes (KiB) or less. Otherwise, you can use x-ms-file-permission-key. If specified, it must have an owner, group, and discretionary access control list (DACL). A value of preserve can be passed to keep an existing value unchanged.Note: You can specify either x-ms-file-permission or x-ms-file-permission-key. If neither header is specified, the default value of preserve is used. |
x-ms-file-permission-format: { sddl ¦ binary } |
Optional. Version 2024-11-04 or later. Specifies whether the value passed in x-ms-file-permission is in SDDL or in binary format. If x-ms-file-permission-key is set to preserve, this header shouldn't be set. If x-ms-file-permission-key is set to any other value than preserve, and if this header isn't set, the default value of sddl is used. |
x-ms-file-permission-key: <PermissionKey> |
In versions 2019-02-02 to 2021-04-10, this header is required if x-ms-file-permission isn't specified. As of version 2021-06-08, both headers are optional. The key of the permission to be set for the file. This can be created using the Create-Permission API.Note: You can specify either x-ms-file-permission or x-ms-file-permission-key. If neither header is specified, the default value of preserve is used for the x-ms-file-permission header. |
x-ms-file-attributes: { preserve ¦ <FileAttributeList> } |
Required, version 2019-02-02 to 2021-04-10. Optional, version 2021-06-08 and later. The file system attributes to be set on the file. See the list of available attributes. A value of preserve can be passed to keep an existing value unchanged. The default value is preserve. |
NFS only request headers
| Request header | Description |
|---|---|
x-ms-mode |
Version 2025-05-05 and later. The mode bits to be set on the file. Mode is represented in the 12-bit numeric octal format or the symbolic 'rwx' format. See POSIX file permissions (mode). |
x-ms-owner |
Version 2025-05-05 and later. The user identifier (UID) of the file owner to be set on the file. |
x-ms-group |
Version 2025-05-05 and later. The group identifier (GID) of the file owner to be set on the file. |
Request body
None.
Response
The response includes an HTTP status code and a set of response headers.
Status code
A successful operation returns status code 200 (OK). For information about status codes, see Status and error codes. For information about status codes, see Status and error codes.
Response headers
The response for this operation includes the headers in the following tables. The response can also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
Common response headers
| Response header | Description |
|---|---|
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 to troubleshoot the request. For more information, see Troubleshoot API operations. |
x-ms-version |
Indicates the version of the File service used to execute the request. |
Date or x-ms-date |
A UTC date/time value that's generated by the service, which indicates the time when the response was initiated. |
x-ms-request-server-encrypted: true/false |
Version 2017-04-17 and later. The value of this header is set to true if the contents of the request are successfully encrypted using the specified algorithm. Otherwise, the value is set to false. |
x-ms-file-creation-time |
Version 2019-02-02 and later. The UTC date/time value that represents the creation time property for the file. |
x-ms-file-last-write-time |
Version 2019-02-02 and later. The UTC date/time value that represents the last write time property for the file. |
x-ms-file-change-time |
Version 2019-02-02 and later. The UTC date/time value that represents the change time property for the file. |
x-ms-client-request-id |
Can be used to troubleshoot requests and 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 won't be present in the response. |
SMB only response headers
| Response header | Description |
|---|---|
x-ms-file-permission-key |
Version 2019-02-02 and later. The key of the permission of the file. |
x-ms-file-attributes |
Version 2019-02-02 and later. The file system attributes of the file. For more information, see the list of available attributes. |
NFS only response headers
| Response header | Description |
|---|---|
x-ms-mode |
Version 2025-05-05 and later. The mode of the file. See POSIX file permissions (mode). |
x-ms-owner |
Version 2025-05-05 and later. The user identifier (UID) of the file owner. |
x-ms-group |
Version 2025-05-05 and later. The group identifier (GID) of the file owner. |
x-ms-link-count |
Version 2025-05-05 and later. The link count of the file. |
Response body
None.
Authorization
Only the account owner can call this operation.
File system attributes
| Attribute | Win32 file attribute | Definition |
|---|---|---|
| ReadOnly | FILE_ATTRIBUTE_READONLY | A file that's read-only. Applications can read the file, but can't write to it or delete it. |
| Hidden | FILE_ATTRIBUTE_HIDDEN | The file is hidden. It isn't included in an ordinary directory listing. |
| System | FILE_ATTRIBUTE_SYSTEM | A file that the operating system uses a part of, or uses exclusively. |
| None | FILE_ATTRIBUTE_NORMAL | A file that doesn't have other attributes set. This attribute is valid only when it's used alone. |
| Archive | FILE_ATTRIBUTE_ARCHIVE | A file that's an archive file. Applications ordinarily use this attribute to mark files for backup or removal. |
| Temporary | FILE_ATTRIBUTE_TEMPORARY | A file that's being used for temporary storage. |
| Offline | FILE_ATTRIBUTE_OFFLINE | The data of a file isn't available immediately. This file system attribute is presented primarily to provide compatibility with Windows. Azure Files doesn't support offline storage options. |
| NotContentIndexed | FILE_ATTRIBUTE_NOT_CONTENT_INDEXED | The file isn't to be indexed by the content indexing service. |
| NoScrubData | FILE_ATTRIBUTE_NO_SCRUB_DATA | The user data stream isn't to be read by the background data integrity scanner. This file system attribute is presented primarily to provide compatibility with Windows. |
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 are 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
The semantics for updating a file's properties are as follows:
A file's size is modified only if the request specifies a value for the
x-ms-content-lengthheader.If a request sets only
x-ms-content-lengthand no other properties:- If the file is located on a File Share with SMB protocol enabled, then none of the file's other properties are modified.
- If the file is located on a File Share with NFS protocol enabled, then the file's change time and last write time are modified.
If any one or more of the following properties is set in the request, all these properties are set together. If a value isn't provided for a specified property when at least one of the following properties is set, that property is cleared for the file.
x-ms-cache-controlx-ms-content-typex-ms-content-md5x-ms-content-encodingx-ms-content-language
Note
The preceding file properties are separate from the file system properties that are available to SMB clients. SMB clients can't read, write, or modify these property values.
Set File properties 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 400 (InvalidQueryParameterValue).
If the file has an active lease, the client must specify a valid lease ID on the request to write properties to the file. If the client doesn't specify a lease ID or it specifies an invalid lease ID, the File service returns status code 412 (Precondition Failed). If the client specifies a lease ID but the file doesn't have an active lease, the File service also returns status code 412 (Precondition Failed).