Using the EFS mount helper to mount EFS file systems - Amazon Elastic File System
How it worksGetting support logsPrerequisites
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using the 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 About the Amazon EFS client.

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 Amazon 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 Amazon Web Services 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. If your client is running on Linux, this process is managed by either upstart or systemd depending on your Linux distribution. For clients running on a supported macOS, it is managed by launchd.

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 mount helper 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 supported EC2 Mac instances running macOS Big Sur, Monterey, and Ventura

  • rsize=1048576 – Sets the maximum number of bytes of data that the NFS client can receive for each network READ request to 1048576, the largest available, to avoid diminished performance.

  • wsize=1048576 – Sets the maximum number of bytes of data that the NFS client can send for each network WRITE request to 1048576, the largest available, to avoid diminished performance.

  • hard – Sets the recovery behavior of the NFS client after an NFS request times out, so that NFS requests are retried indefinitely until the server replies, to ensure data integrity.

  • timeo=600 – Sets the timeout value that the NFS client uses to wait for a response before it retries an NFS request to 600 deciseconds (60 seconds) to avoid diminished performance.

  • retrans=2 – Sets to 2 the number of times the NFS client retries a request before it attempts further recovery action.

  • noresvport – Tells the NFS client to use a new non-privileged Transmission Control Protocol (TCP) source port when a network connection is reestablished. Using the noresvport option helps to ensure that your EFS file system has uninterrupted availability after a reconnection or network recovery event.

  • mountport=2049 – only used when mounting on EC2 Mac instances running macOS Big Sur, Monterey, and Ventura.

Getting support logs

The mount helper has built-in logging for your Amazon EFS file system. You can share these logs with Amazon Support for troubleshooting purposes. You can find the logs stored in /var/log/amazon/efs on clients using the EFS mount helper. These logs are for the EFS mount helper, the stunnel process (disabled by default), and for the amazon-efs-mount-watchdog process that monitors the stunnel process.

Note

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

You can change the log configuration in /etc/amazon/efs/efs-utils.conf. In order for any log changes to take effect, you need to unmount and remount the file system using the EFS mount helper. 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 Amazon Web Services Region that the file system is in. For instructions to create mount targets, see Managing mount targets.

    Note

    We recommend that you wait 60 seconds after the newly created mount target's lifecycle state is available before mounting the file system via DNS. This wait lets the DNS records propagate fully in the Amazon Web Services Region where the file system resides.

    If you use a mount target in an Availability Zone different from that of your 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 One Zone file systems from a different Availability Zone:

    • The name of the file system's Availability Zone – If you are mounting an EFS One Zone file system 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 2023

    • 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 Automated installation of the EFS client 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 Amazon. 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 Amazon Web Services Regions – If the EC2 instance and the file system you are mounting are located in different Amazon Web Services 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 Amazon Web Services Region.