How it works Getting support logs Prerequisites Mounting multiple EC2 instances Mounting from another account or VPC

Using EFS mount helper to mount EFS file systems

The EFS mount helper helps you mount your EFS file systems on your EC2 Linux and Mac instances running the supported distributions listed in Overview.

The Amazon EFS mount helper simplifies mounting your file systems. It includes the Amazon EFS recommended mount options by default. Additionally, the mount helper has built-in logging for troubleshooting purposes. If you encounter an issue with your Amazon EFS file system, you can share these logs with AWS Support. For more information about mounting your file system, see Mounting EFS file systems.

Note

Amazon EFS does not support mounting from Amazon EC2 Windows instances.

Topics

How it works

The mount helper defines a new network file system type, called efs, which is fully compatible with the standard mount command in Linux. The mount helper also supports mounting an Amazon EFS file system at instance boot time automatically by using entries in the /etc/fstab configuration file on EC2 Linux instances.

Warning

Use the _netdev option, used to identify network file systems, when mounting your file system automatically. If _netdev is missing, your EC2 instance might stop responding. This result is because network file systems need to be initialized after the compute instance starts its networking. For more information, see Automatic mounting fails and the instance is unresponsive.

You can mount a file system by specifying one of the following properties:

File system DNS name – If you use the file system DNS name, and the mount helper cannot resolve it, for example when you are mounting a file system in a different VPC, it will fall back to using the mount target IP address. For more information, see Mounting EFS file systems from another AWS account or VPC.
File system ID – If you use the file system ID, the mount helper resolves it to the local IP address of the mount target elastic network interface (ENI) without calling external resources.
Mount target IP address – You can use the IP address of one of the file systems mount targets.

You can find the value for all of these properties in the Amazon EFS console. The file system DNS name is found in the Attach screen.

When encryption of data in transit is declared as a mount option for your Amazon EFS file system, the mount helper initializes a client stunnel process, and a supervisor process called amazon-efs-mount-watchdog. The amazon-efs-mount-watchdog process monitors the health of TLS mounts, and is started automatically the first time an EFS file system is mounted over TLS. This process is managed by either upstart or systemd depending on your Linux distribution, and by launchd on the macOS Big Sur distribution

Stunnel is an open-source multipurpose network relay. The client stunnel process listens on a local port for inbound traffic, and the mount helper redirects NFS client traffic to this local port.

The mount helper uses TLS version 1.2 to communicate with your file system. Using TLS requires certificates, and these certificates are signed by a trusted Amazon Certificate Authority. For more information on how encryption works, see Data encryption in Amazon EFS.

Mount options used by Amazon EFS client

The Amazon EFS client uses the following mount options that are optimized for Amazon EFS:

nfsvers=4.1 – used when mounting on EC2 Linux instances

nfsvers=4.0 – used when mounting on an EC2 Mac instance running MacOS Big Sur
rsize=1048576
wsize=1048576
hard
timeo=600
retrans=2
noresvport
mountport=2049 – only used when mounting on EC2 Mac instances running macOS Big Sur

Getting support logs

The mount helper has built-in logging for your Amazon EFS file system. You can share these logs with AWS Support for troubleshooting purposes.

You can find the logs stored in /var/log/amazon/efs for systems with the mount helper installed. These logs are for the mount helper, the stunnel process itself, and for the amazon-efs-mount-watchdog process that monitors the stunnel process.

Note

The watchdog process ensures that each mount's stunnel process is running, and stops the stunnel when the Amazon EFS file system is unmounted. If for some reason a stunnel process is terminated unexpectedly, the watchdog process restarts it.

You can change the configuration of your logs in /etc/amazon/efs/efs-utils.conf. However, doing so requires unmounting and then remounting the file system with the mount helper for the changes to take effect. Log capacity for the mount helper and watchdog logs is limited to 20 MiB. Logs for the stunnel process are disabled by default.

Important

You can enable logging for the stunnel process logs. However, enabling the stunnel logs can use up a nontrivial amount of space on your file system.

Prerequisites for using the EFS mount helper

You can mount an Amazon EFS file system on an Amazon EC2 instance using the Amazon EFS mount helper. To use the mount helper, you need the following:

File system ID of the file system to mount - The EFS mount helper resolves the file system ID to the local IP address of the mount target elastic network interface (ENI) without calling external resources.
An Amazon EFS mount target – You create mount targets in your virtual private cloud (VPC). If you create your file system in the console using the service recommended settings, a mount target is created in each availability zone in the AWS Region that the file system is in. For instructions to create mount targets, see Creating and managing mount targets and security groups.

Note
We recommend that you wait 90 seconds after creating a mount target before you mount your file system. This wait lets the DNS records propagate fully in the AWS Region where the file system is.

If you use a mount target in an Availability Zone different from that of your Amazon EC2 instance, you incur standard EC2 charges for data sent across Availability Zones. You also might see increased latencies for file system operations.
For mounting file systems with One Zone storage classes from a different Availability Zone:
- The name of the file system's Availability Zone – If you are mounting an EFS file system using One Zone storage classes that is located in a different Availability Zone than the EC2 instance.
- Mount target DNS name – Alternatively, you can specify the mount target's DNS name instead of the Availability Zone.
An Amazon EC2 instance running one of the supported Linux or macOS distributions – The supported distributions for mounting your file system with the mount helper are the following:
- Amazon Linux 2
- Amazon Linux 2017.09 and newer
- macOS Big Sur
- Red Hat Enterprise Linux (and derivatives such as CentOS) version 7 and newer
- Ubuntu 16.04 LTS and newer
Note
EC2 Mac instances running macOS Big Sur support NFS 4.0 only.
The Amazon EFS mount helper is installed on the EC2 instance – The mount helper is a tool in the amazon-efs-utils package of utilities. For information about installing amazon-efs-utils, see Using AWS Systems Manager to install amazon-efs-utils and Manually installing amazon-efs-utils.
The EC2 instance is in a VPC – The connecting EC2 instance must be in a virtual private cloud (VPC) based on the Amazon VPC service. It also must be configured to use the DNS server provided by AWS. For information about the Amazon DNS server, see DHCP Options Sets in the Amazon VPC User Guide.
VPC has DNS hostnames enabled – The VPC of the connecting EC2 instance must have DNS hostnames enabled. For more information, see Viewing DNS Hostnames for Your EC2 Instance in the Amazon VPC User Guide.
For EC2 instances and file systems in different AWS Regions – If the EC2 instance and the file system you are mounting are located in different AWS Regions, you will need to edit the region property in the efs-utils.conf file. For more information, see Mounting Amazon EFS file systems from a different AWS Region.

Mounting EFS to multiple EC2 instances using AWS Systems Manager

You can mount EFS file systems to multiple Amazon EC2 instances remotely and securely without having to log in to the instances by using the AWS Systems Manager Run Command. For more information about AWS Systems Manager Run Command, see AWS Systems Manager run command in the AWS Systems Manager User Guide. The following prerequisites are required before mounting EFS file systems using this method:

The EC2 instances are launched with an instance profile that includes the AmazonElasticFileSystemsUtils permissions policy. For more information, see Step 1: Configure an IAM instance profile with the required permissions.
Version 1.28.1 or later of the Amazon EFS client (amazon-efs-utils package) is installed on the EC2 instances. You can use AWS Systems Manager to automatically install the package on your instances. For more information, see Step 2: Configure an Association used by State Manager for installing or updating the Amazon EFS client.

To mount multiple EFS file systems to multiple EC2 instances using the console

Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.
In the navigation pane, choose Run Command.
Choose Run a command.
Enter AWS-RunShellScript in the Commands search field.
Select AWS-RunShellScript.
In Command parameters enter the mount command to use for each EFS file system that you want to mount. For example:
```
sudo mount -t efs -o tls fs-12345678:/ /mnt/efs
sudo mount -t efs -o tls,accesspoint=fsap-12345678 fs-01233210 /mnt/efs
```
For more information about EFS mount commands using the Amazon EFS client, see Mounting on Amazon EC2 Linux instances using the EFS mount helper or Mounting on Amazon EC2 Mac instances using the EFS mount helper.
Select the target AWS Systems Manager managed EC2 instances that you want the command to run on.
Make any other additional settings you would like. Then choose Run to run the command and mount the EFS file systems specified in the command.

Once you run the command, you can see its status in the command history.

Mounting EFS file systems from another AWS account or VPC

You can mount your Amazon EFS file system using IAM authorization for NFS clients and EFS Access Points using the EFS mount helper. By default, the EFS mount helper uses domain name service (DNS) to resolve the IP address of your EFS mount target. If you are mounting the file system from a different account or virtual private cloud (VPC), you need to resolve the EFS mount target manually.

Following, you can find instructions for determining the correct EFS mount target IP address to use for your NFS client. You can also find instructions for configuring the client to mount the EFS file system using that IP address.

Mounting using IAM or access points from another VPC

When you use a VPC peering connection or transit gateway to connect VPCs, Amazon EC2 instances that are in one VPC can access EFS file systems in another VPC, even if the VPCs belong to different accounts.

Prerequisites

Before using the following the procedure, take these steps:

Install the Amazon EFS client, part of the amazon-efs-utils set of utilities on the compute instance you're mounting the EFS file system on. You use the EFS mount helper, which is included in amazon-efs-utils, to mount the file system. For instructions on installing amazon-efs-utils, see Using the amazon-efs-utils Tools.
Allow the ec2:DescribeAvailabilityZones action in the IAM policy for the IAM role you attached to the instance. We recommend that you attach the AWS managed policy AmazonElasticFileSystemsUtils to an IAM entity to provide the necessary permissions for the entity.

When mounting from another AWS account, update the file system resource policy to allow the elasticfilesystem:DescribeMountTarget action for the principal ARN of other AWS account. For example:


{
    "Id": "access-point-example03",
    "Statement": [
        {
            "Sid": "access-point-statement-example03",
            "Effect": "Allow",
            "Principal": {"AWS": "arn:aws:iam::555555555555"},
            "Action": "elasticfilesystem:DescribeMountTargets",
            "Resource": "arn:aws:elasticfilesystem:us-east-2:111122223333:file-system/fs-12345678",
        }
    ]
}

For more information about EFS file system resource policies, see Resource-based policies.

Install botocore. The EFS client uses botocore to retrieve the mount target IP address when the file system DNS name cannot be resolved when mounting a file system in another VPC. For more information, see Install botocore in the amazon-efs-utils README file.
Set up either a VPC peering connection or a VPC transit gateway.

You connect the client's VPC and your EFS file system's VPC using either a VPC peering connection or a VPC transit gateway. When you use a VPC peering connection or transit gateway to connect VPCs, Amazon EC2 instances that are in one VPC can access EFS file systems in another VPC, even if the VPCs belong to different accounts.

A transit gateway is a network transit hub that you can use to interconnect your VPCs and on-premises networks. For more information about using VPC transit gateways, see Getting Started with transit gateways in the Amazon VPC Transit Gateways Guide.

A VPC peering connection is a networking connection between two VPCs. This type of connection enables you to route traffic between them using private Internet Protocol version 4 (IPv4) or Internet Protocol version 6 (IPv6) addresses. You can use VPC peering to connect VPCs within the same AWS Region or between AWS Regions. For more information on VPC peering, see What is VPC Peering? in the Amazon VPC Peering Guide.

To ensure high availability of your file system, we recommend that you always use an EFS mount target IP address that is in the same availability zone as your NFS client. If you're mounting an EFS file system that is in another account, ensure that the NFS client and EFS mount target are in the same availability zone ID. This requirement applies because AZ names can differ from one account to another.

To mount an EFS file system in another VPC using IAM or an access point

Connect to your EC2 instance:
- To connect to your instance from a computer running macOS or Linux, specify the .pem file for your SSH command. To do this, use the -i option and the path to your private key.
- To connect to your instance from a computer running Windows, you can use either MindTerm or PuTTY. To use PuTTY, install it and convert the .pem file to a .ppk file.
For more information, see the following topics in the Amazon EC2 User Guide for Linux Instances:
- Connecting to Your Linux Instance from Windows Using PuTTY
- Connecting to Your Linux Instance Using SSH
Create a directory for mounting the file system using the following command.
```
$ sudo mkdir /mnt/efs
```
To mount the file system using IAM authorization, use the following command:
```
$ sudo mount -t efs -o tls,iam file-system-dns-name /mnt/efs/
```
For more information about using IAM authorization with EFS, see Using IAM to control file system data access.

To mount the file system using an EFS access point, use the following command:
```
$ sudo mount -t efs -o tls,accesspoint=access-point-id file-system-dns-name /mnt/efs/
```
For more information about EFS access points, see Working with Amazon EFS access points.

Mounting Amazon EFS file systems from a different AWS Region

If you are mounting your EFS file system from another VPC that is in a different AWS Region than the file system, you will need to edit the efs-utils.conf file. In /dist/efs-utils.conf, locate the following lines:


#region = us-east-1

Uncomment the line, and replace the value for the ID of the region in which the file system is located, if it is not in us-east-1.

Mounting from another AWS account in the same VPC

Using shared VPCs, you can mount an Amazon EFS file system that is owned by one AWS account from Amazon EC2 instances that are owned by a different AWS account. For more information about setting up a shared VPC, see Working with shared VPCs in the Amazon VPC Peering Guide.

After you set up VPC sharing, the EC2 instances can mount the EFS file system using Domain Name System (DNS) name resolution or the EFS mount helper. We recommend using the EFS mount helper to mount your EFS file systems.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Mounting file systems

Mounting on EC2 Linux