AWS AmazonS3 documentation change
Summary
Updated documentation for Mountpoint for Amazon S3 with expanded configuration details, including automatic mounting via /etc/fstab, cache configuration options, and security recommendations for local/shared caching.
Security assessment
The changes add security-focused documentation about mount options (nosuid, nodev) to prevent privilege escalation via SUID binaries or device files, warnings about unencrypted local cache data protection, and guidance to secure shared S3 directory buckets. However, there is no evidence of addressing a specific disclosed vulnerability.
Diff
diff --git a/AmazonS3/latest/userguide/mountpoint-usage.md b/AmazonS3/latest/userguide/mountpoint-usage.md index 7ca1cba3a..168afbf7c 100644 --- a//AmazonS3/latest/userguide/mountpoint-usage.md +++ b//AmazonS3/latest/userguide/mountpoint-usage.md @@ -9 +9 @@ Using Mountpoint for Amazon S3Configuring caching in Mountpoint -To use Mountpoint for Amazon S3, your host needs valid AWS credentials with access to the general purpose bucket or buckets that you would like to mount. For different ways to authenticate, see Mountpoint [AWS Credentials](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md#aws-credentials) on GitHub. +To use Mountpoint for Amazon S3, your host needs valid AWS credentials with access to the Amazon S3 bucket or buckets that you would like to mount. For different ways to authenticate, see Mountpoint [AWS Credentials](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md#aws-credentials) on GitHub. @@ -26 +26 @@ Use Mountpoint for Amazon S3 to do the following: - 1. Mount general purpose buckets with the `mount-s3` command. + 1. Mount your Amazon S3 buckets. @@ -28 +28,3 @@ Use Mountpoint for Amazon S3 to do the following: -In the following example, replace ```amzn-s3-demo-bucket``` with the name of your S3 general purpose bucket, and replace ``~/mnt`` with the directory on your host where you want your S3 bucket to be mounted. + 1. You can mount Amazon S3 buckets manually by using the `mount-s3` command. + +In the following example, replace ```amzn-s3-demo-bucket``` with the name of your S3 bucket, and replace ``~/mnt`` with the directory on your host where you want your S3 bucket to be mounted. @@ -33 +35,33 @@ In the following example, replace ```amzn-s3-demo-bucket``` with the name of you -Because the Mountpoint client runs in the background by default, the ``~/mnt`` directory now gives you access to the objects in your S3 bucket. +Because the Mountpoint client runs in the background by default, the ``~/mnt`` directory now gives you access to the objects in your Amazon S3 bucket. + + 2. Alternatively, you can configure automatic mounting of Amazon S3 buckets when an instance starts up or reboots. + +For existing or running Amazon EC2 instances, find the `fstab` file in the `/etc/fstab` directory of your Linux system. Then, add a line to your `fstab` file. For example, to mount `amzn-s3-demo-bucket` using the prefix `example-prefix/` to your sytem path `/mnt/mountpoint`, see the following. To use the following example, replace the `user input placeholders` with your own information. + + s3://amzn-s3-demo-bucket/example-prefix/ /mnt/mountpoint mount-s3 _netdev,nosuid,nodev,nofail,rw 0 0 + +See the following table for an explanation of the options used in the example. + +Option | Description +---|--- +`_netdev` | Specifies that the filesystem requires networking to mount. +`nosuid` | Specifies that the filesystem cannot contain set user ID files. +`nodev` | Specifies that the filesystem cannot contain special devices. +`nofail` | Specifies that failure to mount the filesystem should still allow the system to boot. +`rw` | Specifies that the mount point is created with read and write permissions. Alternatively, use `ro` for read only. + +For new Amazon EC2 instances, you can modify user data on an Amazon EC2 template and set up the `fstab` file as follows. To use the following example, replace the `user input placeholders` with your own information. + + #!/bin/bash -e + MP_RPM=$(mktemp --suffix=.rpm) + curl https://s3.amazonaws.com/mountpoint-s3-release/latest/x86_64/mount-s3.rpm > $MP_RPM + yum install -y $MP_RPM + rm $MP_RPM + + MNT_PATH=/mnt/mountpoint + echo "s3://amzn-s3-demo-bucket/ ${MNT_PATH} mount-s3 _netdev,nosuid,nodev,rw,allow-other,nofail" >> /etc/fstab + mkdir $MNT_PATH + + systemctl daemon-reload + mount -a + @@ -35 +69 @@ Because the Mountpoint client runs in the background by default, the ``~/mnt`` d - 2. Access the objects in your general purpose bucket through Mountpoint. + 2. Access the objects in your Amazon S3 bucket through Mountpoint. @@ -37 +71 @@ Because the Mountpoint client runs in the background by default, the ``~/mnt`` d -After you mount your bucket locally, you can use common Linux commands, such as `cat` or `ls`, to work with your S3 objects. Mountpoint for Amazon S3 interprets keys in your S3 bucket as file system paths by splitting them on the forward slash (`/`) character. For example, if you have the object key `Data/2023-01-01.csv` in your bucket, you will have a directory named `Data` in your Mountpoint file system, with a file named `2023-01-01.csv` inside it. +After you mount your bucket locally, you can use common Linux commands, such as `cat` or `ls`, to work with your S3 objects. Mountpoint for Amazon S3 interprets keys in your Amazon S3 bucket as file system paths by splitting them on the forward slash (`/`) character. For example, if you have the object key `Data/2023-01-01.csv` in your bucket, you will have a directory named `Data` in your Mountpoint file system, with a file named `2023-01-01.csv` inside it. @@ -41 +75 @@ Mountpoint for Amazon S3 intentionally does not implement the full [POSIX](https - 3. Unmount your bucket by using the `umount` command. This command unmounts your S3 bucket and exits Mountpoint. + 3. Unmount your Amazon S3 bucket by using the `umount` command. This command unmounts your S3 bucket and exits Mountpoint. @@ -54 +88 @@ To get a list of options for this command, run `umount --help`. -For additional Mountpoint configuration details, see [S3 bucket configuration](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md#s3-bucket-configuration), and [file system configuration](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md#file-system-configuration) on GitHub. +For additional Mountpoint configuration details, see [Amazon S3 bucket configuration](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md#s3-bucket-configuration), and [file system configuration](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md#file-system-configuration) on GitHub. @@ -86 +120 @@ For more information about how to configure caching in Mountpoint, see the follo -You can opt in to a local cache with the `--cache `CACHE_PATH`` flag. In the following example, replace ``CACHE_PATH`` with the filepath to the directory that you want to cache your data in. Replace ```amzn-s3-demo-bucket``` with the name of your S3 bucket, and replace ``~/mnt`` with the directory on your host where you want your S3 bucket to be mounted. +You can opt in to a local cache with the `--cache `CACHE_PATH`` flag. In the following example, replace ``CACHE_PATH`` with the filepath to the directory that you want to cache your data in. Replace ```amzn-s3-demo-bucket``` with the name of your Amazon S3 bucket, and replace ``~/mnt`` with the directory on your host where you want your S3 bucket to be mounted. @@ -92 +126 @@ You can opt in to a local cache with the `--cache `CACHE_PATH`` flag. In the fol -When you opt in to local caching while mounting an S3 bucket, Mountpoint creates an empty sub-directory at the configured cache location, if that sub-directory doesn’t already exist. When you first mount a bucket and when you unmount, Mountpoint deletes the contents of the local cache. +When you opt in to local caching while mounting an Amazon S3 bucket, Mountpoint creates an empty sub-directory at the configured cache location, if that sub-directory doesn’t already exist. When you first mount a bucket and when you unmount, Mountpoint deletes the contents of the local cache. @@ -96 +130 @@ When you opt in to local caching while mounting an S3 bucket, Mountpoint creates -If you enable local caching, Mountpoint will persist unencrypted object content from your mounted S3 bucket at the local cache location provided at mount. In order to protect your data, you should restrict access to the data cache location by using file system access control mechanisms. +If you enable local caching, Mountpoint will persist unencrypted object content from your mounted Amazon S3 bucket at the local cache location provided at mount. In order to protect your data, you should restrict access to the data cache location by using file system access control mechanisms. @@ -100 +134 @@ If you enable local caching, Mountpoint will persist unencrypted object content -If you repeatedly read small objects (up to 1 MB) from multiple compute instances or the size of the dataset that you repeatedly read often exceeds the size of your local cache, you should use a shared cache in [S3 Express One Zone](https://aws.amazon.com/s3/storage-classes/express-one-zone/). When you read the same data repeatedly from multiple instances, this improves latency by avoiding redundant requests to your mounted S3 bucket. +If you repeatedly read small objects (up to 1 MB) from multiple compute instances or the size of the dataset that you repeatedly read often exceeds the size of your local cache, you should use a shared cache in [S3 Express One Zone](https://aws.amazon.com/s3/storage-classes/express-one-zone/). When you read the same data repeatedly from multiple instances, this improves latency by avoiding redundant requests to your mounted Amazon S3 bucket. @@ -104 +138 @@ Once you opt in to the shared cache, you pay for the data cached in your directo -To opt in to caching in S3 Express One Zone when you mount a general purpose bucket to your compute instance, use the `--cache-xz` flag and specify a directory bucket as your cache location. In the following example, replace the `user input placeholders`. +To opt in to caching in S3 Express One Zone when you mount an Amazon S3 bucket to your compute instance, use the `--cache-xz` flag and specify a directory bucket as your cache location. In the following example, replace the `user input placeholders`. @@ -113 +147 @@ If you have unused space on your instance but you also want to use a shared cach -To opt in to both a local cache and shared cache when you mount an S3 bucket, you specify both cache locations by using the `--cache` and `--cache-xz` flags. To use the following example to opt into both a local and shared cache, replace the `user input placeholders`. +To opt in to both a local cache and shared cache when you mount an Amazon S3 bucket, you specify both cache locations by using the `--cache` and `--cache-xz` flags. To use the following example to opt into both a local and shared cache, replace the `user input placeholders`. @@ -122 +156 @@ For more information, [Mountpoint for Amazon S3 caching configuration](https://g -If you enable shared caching, Mountpoint will copy object content from your mounted S3 bucket into the S3 directory bucket that you provide as your shared cache location, making it accessible to any caller with access to the S3 directory bucket. To protect your cached data, you should follow the [Security best practices for Amazon S3](./security-best-practices.html) to ensure that your buckets use the correct policies and are not publicly accessible. You should use a directory bucket dedicated to Mountpoint shared caching and grant access only to Mountpoint clients. +If you enable shared caching, Mountpoint will copy object content from your mounted Amazon S3 bucket into the S3 directory bucket that you provide as your shared cache location, making it accessible to any caller with access to the S3 directory bucket. To protect your cached data, you should follow the [Security best practices for Amazon S3](./security-best-practices.html) to ensure that your buckets use the correct policies and are not publicly accessible. You should use a directory bucket dedicated to Mountpoint shared caching and grant access only to Mountpoint clients.