Menu
AWS Storage Gateway
User Guide (API Version 2013-06-30)

Managing Your File Gateway

Following, you can find information about how to manage your file gateway resources.

Adding a File Share

After your file gateway is activated and is running, you can add additional file shares. For information about how to add a file share, see Creating a File Share.

Granting Access to an Amazon S3 Bucket

When you create a file share, file gateway requires access to upload files into your Amazon S3 bucket. To grant this access, file gateway assumes an IAM role that is associated with an IAM policy that grants this access. The role requires this IAM policy and a security token service trust (STS) relationship on it. The policy determines which actions the role can perform. In addition, your S3 bucket must have an access policy that allows the IAM role to access the S3 bucket. You can create the role and access policy yourself or file gateway can create them for you. If file gateway creates the policy for you, the policy will contain a list of S3 actions. For information about roles and permissions, see Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide.

The following example trust policy allows file gateway to assume the role.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "storagegateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

If you don’t want file gateway to create a policy on your behalf, you create your own and attach it to your file share. For more information, see Creating a File Share.

The following example policy allows file gateway to perform all the Amazon S3 actions listed in the policy. The first part of the statement allows all the actions listed to be performed on the S3 bucket named TestBucket. The second part allows the listed action on all objects in TestBucket.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "s3:GetAccelerateConfiguration", "s3:GetBucketLocation", "s3:GetBucketVersioning", "s3:ListBucket", "s3:ListBucketVersions", "s3:ListBucketMultipartUploads" ], "Resource": "arn:aws:s3:::TestBucket", "Effect": "Allow" }, { "Action": [ "s3:AbortMultipartUpload", "s3:DeleteObject", "s3:DeleteObjectVersion", "s3:GetObject", "s3:GetObjectVersion", "s3:ListMultipartUploadParts", "s3:PutObject" ], "Resource": "arn:aws:s3:::TestBucket/*", "Effect": "Allow" } ] }

Deleting a File Share

If you no longer need a file share, you can delete it from the AWS Storage Gateway Management Console. When you delete a file share, the gateway is detached from the Amazon S3 bucket that the file share maps to. However, the S3 bucket and its contents are not deleted.

If your gateway is uploading data to a S3 bucket when you delete a file share, the delete process doesn't complete until all the data is uploaded. The file share has the DELETING status until the data is completely uploaded.

If you want your data to be completely uploaded, use the To delete a file share procedure directly following. If you don't want to wait for your data to be completely uploaded, see the To forcibly delete a file share procedure later in the topic.

To delete a file share

  1. Open the AWS Storage Gateway console at https://console.aws.amazon.com/storagegateway/home.

  2. Choose File shares, and choose the file share you want to delete.

  3. For Actions, choose Delete file share. The following confirmation dialog box appears.

  4. In the confirmation dialog box, select the check box for the file share or shares that you want to delete, and then choose Delete.

In certain cases, you might not want to wait until all the data written to files on the NFS file share is uploaded before deleting the file share. For example, you might want to intentionally discard data that was written but has not yet been uploaded. In another example, the Amazon S3 bucket or objects that back the file share might have already been deleted, meaning that uploading the specified data is no longer possible.

In these cases, you can forcibly delete the file share by using the AWS Management Console or the DeleteFileShare API operation. This operation aborts the data upload process. When it does, the file share enters the FORCE_DELETING status. To forcibly delete a file share from the console, see procedure following.

To forcibly delete a file share

  1. Open the AWS Storage Gateway console at https://console.aws.amazon.com/storagegateway/home.

  2. Choose File shares, and choose the file share you want to forcibly delete and wait for a few seconds. A delete message is displayed in the Details tab.

    Note

    You cannot undo the force delete operation.

  3. In the message that appears in Details tab, verify the ID of the file share you want to forcibly delete, select the confirmation box, and choose Force delete now.

You can also use the DeleteFileShare API operation to forcibly delete the file share.

Updating a File Share

You can update the default file share settings, the clients allowed to connect to your file share, and the metadata defaults for your file share.

Editing the File Share Settings

You can edit the default storage class for your Amazon S3 bucket, and also the squash level setting and the Export as option for your file share. Possible Export as options include, for example, Read-write.

To edit the file share settings

  1. Open the AWS Storage Gateway console at https://console.aws.amazon.com/storagegateway/home.

  2. Choose File shares, and then choose the file share that you want to update.

  3. For Actions, choose Edit file share settings.

  4. Do one or more of the following:

    • For Storage class for new objects, choose a default storage class for your S3 bucket, and choose Save.

      Possible values for the storage class for new objects are S3 Standard or S3 Standard-Infrequent Access. The default value is S3 Standard.

    • Choose Guess MIME type to enable guessing of the MIME type for uploaded objects based on file extensions.

    • For Squash level, choose the squash level setting you want for your file share, and then choose Save. Possible values are the following:

      • Root squash (default) – Access for the remote superuser (root) is mapped to the specified UID and GID.

      • No root squash – Remote superuser (root) receives access as root.

      • All squash – All user access is mapped to the specified UID and GID.

      The default value for squash level is Root squash.

    • For Export as, choose an option for your file share, and then choose Save. The default value is Read-write.

      Note

      For file shares mounted on a Windows client, if you select Read-only for Export as, you might see an error message about an unexpected error keeping you from creating the folder. This error message is a known issue with NFS version 3. You can ignore the message.

Editing Metadata Defaults

If you don't set metadata values for your files or directories in your bucket, file gateway sets metadata default values. These values include Unix permissions for file and folders. You can edit the metadata defaults on the AWS Storage Gateway Management Console. When file gateway stores files and folders in Amazon S3, the Unix file permissions are stored in object metadata. When file gateway discovers objects that were not stored by file gateway, they are assigned default Unix file permissions. The following table describes the default Unix permissions.

Metadata Description
Directory permissions

The Unix directory mode in the form "nnnn". For example, "0666" represents the access mode for all directories inside the file share. The default value is 0777.

File permissions

The Unix file mode in the form "nnnn". For example, "0666" represents the file mode inside the file share. The default value is 0666.

User ID

The default owner ID for files in the file share. The default value is 65534.

Group ID The default group ID for the file share. The default value is 65534.

To edit metadata defaults

  1. Open the AWS Storage Gateway console at https://console.aws.amazon.com/storagegateway/home.

  2. Choose File shares, and then choose the file share you want to update.

  3. For Actions, choose Edit file metadata defaults.

  4. In the Edit file metadata defaults dialog box, provide the metadata information and choose Save.

Editing Allowed NFS Clients

We recommend changing the allowed NFS client settings for your file share. If you don't, any client on your network can mount to your file share.

To edit allowed NFS clients

  1. Open the AWS Storage Gateway console at https://console.aws.amazon.com/storagegateway/home.

  2. Choose File shares, and then choose the file share you want to update.

  3. For Actions, choose Edit allowed clients.

  4. In the Edit allowed clients dialog box, choose Add entry, provide the IP address or CIDR for the client, and then choose Save.

Refreshing Objects in Your Amazon S3 Bucket

As your NFS client performs file system operations, your gateway maintains an inventory of the objects in the Amazon S3 bucket associated with your file share. Your gateway uses this cached inventory to reduce the latency and frequency of S3 requests.

To refresh the S3 bucket for your file share, you can use the AWS Storage Gateway console or the RefreshCache operation in the AWS Storage Gateway API.

To refresh objects in a S3 bucket from the console

  1. Open the AWS Storage Gateway console at https://console.aws.amazon.com/storagegateway/home.

  2. Choose File shares, and then choose the file share associated with the S3 bucket that you want to refresh.

  3. For Actions, choose Refresh cache. The time it takes to refresh depends on the number of objects that the S3 bucket contains.

Understanding File Share Status

Each file share has an associated status that tells you at a glance what the health of the file share is. Most of the time, the status indicates that the file share is functioning normally and that no action is needed on your part. In some cases, the status indicates a problem that might or might not require action on your part.

You can see file share status on the AWS Storage Gateway console. File share status appears in the Status column for each file share in your gateway. A file share that is functioning normally has status as AVAILABLE.

The following table describes each file share status, and if and when you should take action based on the status. A file share should have AVAILABLE status all or most of the time it is in use.

Status Meaning
AVAILABLE

The file share is configured properly and is available to use. The AVAILABLE status is the normal running status for a file share.

CREATING

The file share is being created and is not ready to be used. The CREATING status is transitional. No action is required. If file share is stuck in this status, it's probably because the gateway VM lost connection to AWS.

UPDATING

The file share configuration is being updated. If a file share is stuck in this status, it's probably because the gateway VM lost connection to AWS.

DELETING

The file share is being deleted. The file share is not deleted until all data is uploaded to AWS. The DELETING status is transitional, and no action is required.

FORCE_DELETING

The file share is being deleted forcibly. The file share is deleted immediately and uploaded to AWS is aborted. The FORCE_DELETING status is transitional, and no action is required.

UNAVAILABLE

The file share is in an unhealthy state. Certain issues can cause the file share to go into an unhealthy state, such as role policy errors or if a Amazon S3 bucket that the file share maps to doesn't exist. When the issue that caused the unhealthy state is resolved, the file returns to AVAILABLE state.

File Share Best Practices

In this section, you can find information about best practices for creating file shares.

Preventing Multiple File Shares Writing to Your Amazon S3 Bucket

When you create a file share, we recommend that you configure your Amazon S3 bucket so that only one file share can write to it. If you configure your S3 bucket to be written to by multiple file shares, unpredictable results might occur. To prevent this, you can create an S3 bucket policy that denies all roles except the role used for the file share to put or delete objects in the bucket, and attach the policy to the S3 bucket.

The following example policy denies all roles except the role that created the bucket to write to the S3 bucket. The s3:DeleteObject and s3:PutObject actions are denied for all roles except "TestUser". The policy applies to all objects in the "arn:aws:s3:::test-bucket/*" bucket.

Copy
{ "Version":"2012-10-17", "Statement":[ { "Sid":"DenyMultiWrite", "Effect":"Deny", "Principal":"*", "Action":[ "s3:DeleteObject", "s3:PutObject" ], "Resource":"arn:aws:s3:::TestBucket/*", "Condition":{ "StringNotLike":{ "aws:userid":"TestUser:*" } } } ] }

Allowing Specific NFS Clients to Mount Your File Share

We recommend that you change the allowed NFS client settings for your file share. If you don't, any client on your network can mount your file share. For information about how to edit your NFS client settings, see Editing Allowed NFS Clients.