--- title: "Using Trash Folder for S3 Objects" slug: "using-trash-folder-for-s3-objects-tg" tags: ["5.5"] updated: 2026-10-27T23:00:54Z published: 2026-10-27T23:00:54Z canonical: "docs.vastdata.com/using-trash-folder-for-s3-objects-tg" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.vastdata.com/llms.txt > Use this file to discover all available pages before exploring further. # Using Trash Folder for S3 Objects The trash folder is a hidden folder into which client users can move folders and files that they want to delete. The files and folders are automatically deleted for the user from the trash folder asynchronously. The trash folder feature is disabled by default and can be enabled on the cluster (by a cluster administrator). It is supported for use [via NFSv3 and NFSv4.1](/docs-5-5/docs/trash-folder-access-for-rapid-parallel-file-deletion-tg) as well as via S3. For S3 users, deletion to trash folder is done by adding the custom header `x-amz-delete-contents: true` to a DELETE request. The custom header can be used to move any of the following to the trash folder: - A non-versioned bucket, even if not empty, along with any objects contained in the bucket. That is, a bucket delete request that would otherwise fail if the bucket is not empty, does not fail when using the trash folder header. - An object. If the header is used with a DeleteObject request and an object key is specified which denotes an explicit object, that object is deleted. - All objects which share a specified object key prefix. Effectively, this is like deleting all files under a given hierarchical directory path. The prefix should be specified without a trailing slash. All contents under the prefix are moved to trash. When using the trash folder via S3, the user requires the same permissions as are otherwise required to delete the data if the trash folder is not used. So, for example, a user deleting a bucket by moving it to the trash folder needs the explicitly granted *delete bucket* permission that is granted to users via VMS. ## Moving Buckets and Objects to the Trash Folder To use the trash folder for an object or bucket deletion, include the following custom header in a DELETE request: ```plaintext x-amz-delete-contents: true ``` > [!NOTE] > Note > > There is no specific feature for undoing a move to the trash folder to restore data that was accidentally deleted. ### Example 1: Deleting a Bucket and its Contents Suppose we upload the object *myfile* to the bucket *mybucket* using the [S3cmd](/docs-5-5/docs/s3cmd-tg) client: ```plaintext [centos@host~]$ s3cmd put myfile s3://mybucket/ upload: 'myfile' > 's3://mybucket/myfile' [1 of 1] 10485760 of 10485760 100% in 0s 113.09 MB/s done ``` Normally, a request to delete the bucket would fail because the bucket is not empty. However, making a *DeleteBucket* request and specifying the `x-amz-delete-contents` header for the trash folder, the bucket and its content are deleted. The following client session of the [Boto3 AWS SDK for Python](/docs-5-5/docs/using-boto3-with-vast-cluster-s3-tg) connects to the cluster's S3 service over HTTP at one of the cluster's CNode virtual IPs (198.51.100.255), authenticates with a VMS generated access key pair and deletes the bucket via the trash folder: ```plaintext def set_delete_contents_header(request, **kwargs):    request.headers.add_header('x-amz-delete-contents', 'true') sess = boto3.session.Session() s3 = sess.client(service_name='s3',                 region_name='vast-1',                 use_ssl=False,                 endpoint_url='http://198.51.100.255'                 aws_access_key_id='YAUY93A7Q91SO2M07BWZ',                 aws_secret_access_key='NWzyNIqIscgVZlaHqBzBWaejMDHSHbZuXDxbE2Yp'                 config=boto3.session.Config(                      signature_version='s3v4'                      s3={'addressing_style': 'path'}                  )                ) s3.meta.events.register('before-sign.*.*', set_delete_contents_header) s3.delete_bucket(Bucket='mybucket') ``` Following the deletion, no buckets are found: ```plaintext [centos@host ~]$ s3cmd ls [centos@host ~]$ ``` ### Example 2: Deleting Objects Under a Prefix Suppose two objects *a/b/c/object1* and *a/b/d/object2* are created in an existing bucket *mybucket* using the s3cmd client: ```plaintext [centos@host ~]$ s3cmd put 1KB_random_file s3://mybucket/a/b/c/object1 upload: '1KB_random_file' -> 's3://mybucket/a/b/c/object1'  [1 of 1] 1024 of 1024   100% in    0s    15.16 KB/s  done [centos@host ~]$ s3cmd put 1KB_random_file s3://mybucket/a/b/d/object2 upload: '1KB_random_file' -> 's3://mybucketheaders/a/b/d/object2'  [1 of 1] 1024 of 1024   100% in    0s    17.13 KB/s  done ``` These objects can be moved to trash by deleting the common object key prefix *a/b*, making a *DeleteObject* request specifying the `x-amz-delete-contents` header. Using a client instance of the Boto3 AWS SDK for Python, contacting the S3 service over HTTP at one of the CNode virtual IPs (198.51.100.255), authenticating with a VMS generated access key pair, the request might look like this: ```plaintext def set_delete_contents_header(request, **kwargs):    request.headers.add_header('x-amz-delete-contents', 'true') sess = boto3.session.Session() s3 = sess.client(service_name='s3',                 region_name='vast-1',                 use_ssl=False,                 endpoint_url='http://198.51.100.255'                 aws_access_key_id='YAUY93A7Q91SO2M07BWZ',                 aws_secret_access_key='NWzyNIqIscgVZlaHqBzBWaejMDHSHbZuXDxbE2Yp'                 config=boto3.session.Config(                      signature_version='s3v4'                      s3={'addressing_style': 'path'}                  )                ) s3.meta.events.register('before-sign.*.*', set_delete_contents_header) s3.delete_object(Bucket='mybucket', Key='a/b') ``` Following the deletion, the objects can no longer be listed: ```plaintext [centos@host~]$ s3cmd ls s3://mybucket/a/b [centos@host ~]$ ```