# Installing the Amazon EFS client
We recommend that you install the Amazon EFS client (`amazon-efs-utils`), an open-source collection of tools for Amazon EFS. The Amazon EFS client includes a *mount helper*, which is a program that helps simplify mounting EFS file systems. The client also enables the ability to use Amazon CloudWatch to monitor an EFS file system's mount status, and it includes tooling that makes it easier to perform encryption of data in transit for Amazon EFS file systems.
You can manually install the Amazon EFS client on Amazon EC2 (EC2) instances running [supported distributions](#efs-utils-supported-distros). For certain supported operating systems, you can alternatively configure AWS Systems Manager to automatically install or update the package. For a list of distributions that you can use with AWS Systems Manager, see [Systems Manager supported operating systems](manage-efs-utils-with-aws-sys-manager.md#sys-mgr-support-matrix).
**Important**
We recommend that you always use the most current version of `amazon-efs-utils` to ensure access to its full capabilities. For example, mounting with IPv6 addresses is supported in versions 2.3 or later, but not in earlier versions.
**Topics**
+ [Dependencies for EFS tools](#utils-dependencies)
+ [Supported distributions](#efs-utils-supported-distros)
+ [Manually installing the Amazon EFS client](installing-amazon-efs-utils.md)
+ [Automatically installing or updating Amazon EFS client using AWS Systems Manager](manage-efs-utils-with-aws-sys-manager.md)
+ [Installing and upgrading `botocore`](install-botocore.md)
+ [Upgrading `stunnel`](upgrading-stunnel.md)
+ [Enabling FIPS mode](fips-enabling.md)
## Dependencies for EFS tools
The following dependencies exist for `amazon-efs-utils` and are installed when you install the `amazon-efs-utils` package:
+ NFS client
+ `nfs-utils` for RHEL, CentOS, Amazon Linux, and Fedora distributions
+ `nfs-common` for Debian and Ubuntu distributions
+ Network relay (stunnel package, version 4.56 or later)
+ Python (version 3.4 or later)
+ OpenSSL 1.0.2 or newer
**Note**
By default, when using the EFS mount helper with Transport Layer Security (TLS), the mount helper enforces certificate hostname checking. The EFS mount helper uses the `stunnel` program for its TLS functionality. Some versions of Linux don't include a version of `stunnel` that supports these TLS features by default. When using one of those Linux versions, mounting an EFS file system using TLS fails.
After you've installed the `amazon-efs-utils` package, upgrade stunnel. See [Upgrading `stunnel`](upgrading-stunnel.md).
You can use AWS Systems Manager to manage Amazon EFS clients and automate the tasks required to install or update the amazon-efs-utils package on your EC2 instances. For more information, see [Automatically installing or updating Amazon EFS client using AWS Systems Manager](manage-efs-utils-with-aws-sys-manager.md).
For issues with encryption, see [Troubleshooting encryption](troubleshooting-efs-encryption.md).
## Supported distributions
The Amazon EFS client has been verified against the following Linux and Mac distributions:
| Distribution | Package type | `init` system |
| --- | --- | --- |
| Amazon Linux 2023 (AL2023) | rpm | systemd |
| Amazon Linux 2 (AL2) | rpm | systemd |
| CentOS 8 | rpm | systemd |
| Amazon Linux 1 (AL1) 2017.09 AL1 AMI reached its end-of-life on December 31, 2023 and is not supported for `amazon-efs-utils` packages released in April 2024 or later (version 2.0 and later). | rpm | upstart |
| Debian 11 | deb | systemd |
| Fedora 29 - 32 | rpm | systemd |
| macOS Big Sur | | launchd |
| macOS Monterey | | launchd |
| macOS Ventura | | launchd |
| macOS Sonoma | | launchd |
| OpenSUSE Leap, Tumbleweed | rpm | systemd |
| Oracle8 | rpm | systemd |
| Red Hat Enterprise Linux (RHEL) 8, 9 | rpm | systemd |
| SUSE Linux Enterprise Server (SLES) 12, 15 | rpm | systemd |
| Ubuntu 16.04 LTS, 18.04 LTS, 20.04 LTS, 22.04 LTS | deb | systemd |
For a complete list of supported distributions that the package has been verified against, see the `amazon-efs-utils` [https://github.com/aws/efs-utils/blob/master/README.md](https://github.com/aws/efs-utils/blob/master/README.md) on Github.
# Manually installing the Amazon EFS client
You can manually install the Amazon EFS client on Amazon EC2 (EC2) Linux instances and on EC2 Mac instances running macOS Big Sur, macOS Monterey, and macOS Ventura. For a list of the distributions that support Amazon EFS client, see [Supported distributions](using-amazon-efs-utils.md#efs-utils-supported-distros)
The installation procedures for supported operating systems are described in the following sections.
**Topics**
+ [Installing the Amazon EFS client on Amazon EC2 Linux instances](#installing-efs-utils-amzn-linux)
+ [Installing the Amazon EFS client on other Linux distributions](#installing-other-distro)
+ [Installing the Amazon EFS client on EC2 Mac instances running macOS Big Sur, macOS Monterey, or macOS Ventura](#install-efs-utils-macOS)
## Installing the Amazon EFS client on Amazon EC2 Linux instances
The `amazon-efs-utils` package for installing on Amazon EC2 Linux instances from the following locations:
+ The Amazon Machine Images (AMI) package repositories for Amazon Linux. The following instructions are for installing the `amazon-efs-utils` package from the AMI package repositories.
+ The AWS [https://github.com/aws/efs-utils](https://github.com/aws/efs-utils) GitHub repository. For more information about installing the `amazon-efs-utils` package from GitHub, see [Installing the Amazon EFS client on other Linux distributions](#installing-other-distro).
**Note**
If you're using Direct Connect, you can find installation instructions in [Prerequisites](mounting-fs-mount-helper-direct.md#efs-onpremises).
The Amazon Linux 1 (AL1) AMI reached its end-of-life on December 31, 2023 and is not supported for `amazon-efs-utils` packages released in April 2024 and later (version 2.0 and later). We recommend that you upgrade applications to Amazon Linux 2023 (AL2023), which includes long-term support until 2028.
**To install the `amazon-efs-utils` package from the AMI package repository on EC2 Linux instances**
1. Make sure that you've created an AL2023 or Amazon Linux 2 (AL2) EC2 instance. For information on how to do this, see [Step 1: Launch an instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html#ec2-launch-instance).
1. Access the terminal for your instance through Secure Shell (SSH), and log in with the appropriate user name. For more information, see [Connect to your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect.html) in the *Amazon EC2 User Guide*.
1. Run the following command to install the `amazon-efs-utils` package.
```
sudo yum install -y amazon-efs-utils
```
## Installing the Amazon EFS client on other Linux distributions
If you don't want to get the `amazon-efs-utils` package from the Amazon Linux AMI package repositories, it is also available on GitHub.
After you clone the package, you can build and install `amazon-efs-utils` using one of the following methods, depending on the package type supported by your Linux distribution:
+ **RPM** – This package type is supported by AL2023, Amazon Linux 2, Red Hat Linux, CentOS, and similar.
+ **DEB** – This package type is supported by Ubuntu, Debian, and similar.
For instructions on installing the `amazon-efs-utils` package for other Linux distributions, see [On other Linux distributions](https://github.com/aws/efs-utils?tab=readme-ov-file#on-other-linux-distributions) in the `amazon-efs-utils` README on Github.
## Installing the Amazon EFS client on EC2 Mac instances running macOS Big Sur, macOS Monterey, or macOS Ventura
The `amazon-efs-utils` package is available for installation on EC2 Mac instances running macOS Big Sur, macOS Monterey, or macOS Ventura.
For instructions on installing the `amazon-efs-utils` package on Mac instances, see [ On MacOS Big Sur, macOS Monterey, macOS Sonoma and macOS Ventura distribution ](https://github.com/aws/efs-utils?tab=readme-ov-file#on-macos-big-sur-macos-monterey-macos-sonoma-and-macos-ventura-distribution) in the `amazon-efs-utils` README on Github.
### Next steps
After installs `amazon-efs-utils` on your EC2 instance, proceed to the next steps for mounting your file system:
+ [Install `botocore`](install-botocore.md) so that you can use Amazon CloudWatch to monitor your file system's mount status.
+ [Upgrade to the latest version of `stunnel`](upgrading-stunnel.md) to enable encryption of data in transit.
+ [Mount your file system](efs-mount-helper.md) using the EFS mount helper.
# Automatically installing or updating Amazon EFS client using AWS Systems Manager
You can use AWS Systems Manager to simplify the management of the Amazon EFS client (`amazon-efs-utils`). AWS Systems Manager is an AWS service that you can use to view and control your infrastructure on AWS. With AWS Systems Manager you can automate the tasks required to install or update the `amazon-efs-utils` package on your Amazon EC2 (EC2) instances. The Systems Manager capabilities like Distributor and State Manager enable you to automate the following processes:
+ Maintaining version control over the Amazon EFS client.
+ Centrally storing and systematically distributing the Amazon EFS client to your Amazon EC2 instances.
+ Automate the process of keeping your EC2 instances in a defined state.
For more information, see the [https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html).
## What the Amazon EFS client does during installation
You use the Amazon EFS client to automate monitoring Amazon CloudWatch logs for file system mount status and upgrade `stunnel` to the latest version for selected Linux distributions. When you install the Amazon EFS client on your Amazon EC2 instances using Systems Manager, it takes the following actions:
+ Installs the `botocore` package using the same steps described in [Installing and upgrading `botocore`](install-botocore.md). The Amazon EFS client uses `botocore` to monitor the EFS file system mount status.
+ Enables the monitoring of EFS file system mount status in CloudWatch logs by updating `efs-utils.conf`. For more information, see [Monitoring mount attempt successes and failures](how-to-monitor-mount-status.md).
+ For EC2 instances running `RHEL7` or `CentOS7`, the Amazon EFS client automatically upgrades `stunnel` as described in [Upgrading `stunnel`](upgrading-stunnel.md). Upgrading `stunnel` is required in order to successfully mount an EFS file system using TLS, and the `stunnel` version shipped with `RHEL7` and `CentOS7` does not support the Amazon EFS client (`amazon-efs-utils`).
## Systems Manager supported operating systems
Your EC2 instances must be running one of the following operating systems in order to be used with AWS Systems Manager to automatically update or install the Amazon EFS client.
| Platform | Platform version | Architecture |
| --- | --- | --- |
| Amazon Linux 2023 (AL2023) | AL2023 | x86\$164, arm64 (Graviton2 or later processors) |
| Amazon Linux 2 (AL2) | 2.0 | x86\$164, arm64 (Amazon Linux 2, A1 instance types) |
| Amazon Linux 1 (AL1) Amazon Linux 1 (AL1) AMI reached its end-of-life on December 31, 2023 and is not supported for `amazon-efs-utils` packages released in April 2024 and later (version 2.0 and later). We recommend that you upgrade applications to Amazon Linux 2023 (AL2023), which includes long-term support until 2028. | 2017.09, 2018.03 | x86\$164 |
| CentOS | 7, 8 | x86\$164 |
| Red Hat Enterprise Linux (RHEL) | 8, 9 | x86\$164, arm64 |
| SUSE Linux Enterprise Server (SLES) | 12, 15 | x86\$164 |
| Ubuntu Server | 16.04, 18.04, 20.04 | x86\$164, arm64 (Ubuntu Server 16 and later, A1 instance types) |
# Configuring AWS Systems Manager to install the EFS client
There are two one-time configurations required to set up Systems Manager to automatically install or update the `amazon-efs-utils` package.
1. Configure an AWS Identity and Access Management (IAM) instance profile with the required permissions.
1. Configure an Association (including the schedule) used for installation or updates by the State Manager.
## Step 1: Configure an IAM instance profile with the required permissions
By default, AWS Systems Manager doesn't have permission to manage your Amazon EFS clients and install or update the amazon-efs-utils package. You must grant access to Systems Manager by using an AWS Identity and Access Management (IAM) instance profile. An instance profile is a container that passes IAM role information to an Amazon EC2 (EC2) instance at launch.
Use the `AmazonElasticFileSystemsUtils` AWS managed permission policy to assign the appropriate permissions to roles. You can create a new role for your instance profile or add the `AmazonElasticFileSystemsUtils` permission policy to an existing role. You must then use this instance profile to launch your EC2 instances. For more information, see [Configure instance permissions required for Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-permissions.html).
## Step 2: Configure an association used by State Manager
The `amazon-efs-utils` package is included with Distributor and is ready for you to deploy to managed EC2 instances. To view the latest version of `amazon-efs-utils` that is available for installation, you can use the AWS Systems Manager console or your preferred AWS command line tool. To access Distributor, open the [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) and choose **Distributor** in the left navigation pane. Locate **AmazonEFSUtils** in the **Owned by Amazon** section. Choose **AmazonEFSUtils** to see the package details. For more information, see [View packages](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-view-packages.html).
Using State Manager, you can install or update the `amazon-efs-utils` package on your managed EC2 instances immediately or on a schedule. Additionally, you can ensure that `amazon-efs-utils` is automatically installed on new EC2 instances. For more information about installation or updating packages using Distributor and State Manager, see [Working with Distributor](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-working-with.html).
To automatically install or update the amazon-efs-utils package on instances using the Systems Manager console, see [Scheduling a package installation or update (console)](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-working-with-packages-deploy.html#distributor-deploy-sm-pkg-console). This will prompt you to create an association for State Manager, which defines the state you want to apply to a set of instances. Use the following inputs when you create your association:
+ For **Parameters** choose **Action** > **Install** and **Installation Type** > **In-place update**.
+ For **Targets** the recommended setting is **Choose all instances** to register all new and existing EC2 instances as targets to automatically install or update **AmazonEFSUtils**. Alternatively, you can specify instance tags, select instances manually, or choose a resource group to apply the association to a subset of instances. If you specify instance tags, you must launch your EC2 instances with the tags to allows AWS Systems Manager to automatically install or update the Amazon EFS client.
+ For **Specify schedule** the recommended setting for **AmazonEFSUtils** is every 30 days. You can use controls to create a cron or rate schedule for the association.
To use AWS Systems Manager to mount EFS file systems to multiple EC2 instances, see [Mounting EFS to multiple EC2 instances](mount-multiple-ec2-instances.md).
# Installing and upgrading `botocore`
The Amazon EFS client uses `botocore` to interact with other AWS services. It is required if you want to monitor mount attempt success or failure for your EFS file systems in CloudWatch Logs. For more information, see [Monitoring mount attempt successes and failures](how-to-monitor-mount-status.md).
For instructions on installing and upgrading `botocore`, see [ Installing `botocore`](https://github.com/aws/efs-utils/blob/master/README.md#install-botocore) in the `amazon-efs-utils` README on Github.
# Upgrading `stunnel`
Encryption of data in transit with the EFS mount helper requires `OpenSSL` version 1.0.2 or newer, and a version of `stunnel` that supports both Online Certificate Status Protocol (OCSP) and certificate hostname checking. The EFS mount helper uses the `stunnel` program for its TLS functionality. Note that some versions of Linux don't include a version of `stunnel` that supports these TLS features by default. When using one of those Linux distributions, mounting an EFS file system using TLS fails.
After installing the EFS mount helper, you can upgrade your system's version of stunnel with the following instructions.
**To upgrade `stunnel` on Amazon Linux, Amazon Linux 2, and other supported Linux distributions (except for [SLES 12](#stunnel-on-sles12))**
1. In a web browser, go to the `stunnel` downloads page [https://www.stunnel.org/downloads.html](https://www.stunnel.org/downloads.html).
1. Locate the latest `stunnel` version that is available in `tar.gz` format. Note the name of the file as you will need it in the following steps.
1. Open a terminal on your Linux client, and run the following commands in the order presented.
1. For RPM:
```
sudo yum install -y gcc openssl-devel tcp_wrappers-devel
```
For DEB:
```
sudo apt-get install build-essential libwrap0-dev libssl-dev
```
1. Replace *latest-stunnel-version* with the name of the file you noted previously in Step 2.
```
sudo curl -o latest-stunnel-version.tar.gz https://www.stunnel.org/downloads/latest-stunnel-version.tar.gz
```
1.
```
sudo tar xvfz latest-stunnel-version.tar.gz
```
1.
```
cd latest-stunnel-version/
```
1.
```
sudo ./configure
```
1.
```
sudo make
```
1. The current `stunnel` package is installed in `bin/stunnel`. So that the new version can be installed, remove that directory with the following command.
```
sudo rm /bin/stunnel
```
1. Install the latest version:
```
sudo make install
```
1. Create a symlink:
```
sudo ln -s /usr/local/bin/stunnel /bin/stunnel
```
**To upgrade stunnel on macOS**
+ Open a terminal on your EC2 Mac instance, and run the following command to upgrade to the latest version of stunnel.
```
brew upgrade stunnel
```
**Upgrading stunnel for SLES 12**
+ Run the following commands and follow the zypper package manager instructions to upgrade stunnel on your compute instance running SLES12.
```
sudo zypper addrepo https://download.opensuse.org/repositories/security:Stunnel/SLE_12_SP5/security:Stunnel.repo
sudo zypper refresh
sudo zypper install -y stunnel
```
After you've installed a version of stunnel with the required features, you can mount your file system using TLS with the Amazon EFS recommended settings.
# Resolving issues with installing stunnel
If you are unable to install stunnel, try disabling certificate hostname checking. Additionally, provide the strongest security possible by enabling Online Certificate Status Protocol (OCSP).
**Topics**
+ [Disabling Certificate Hostname Checking](#disable-cert-hn-checking)
+ [Enabling Online Certificate Status Protocol](#tls-ocsp)
## Disabling Certificate Hostname Checking
If you are unable to install the required dependencies, you can optionally disable certificate hostname checking inside the Amazon EFS mount helper configuration. We do not recommend that you disable this feature in production environments. To disable certificate host name checking, do the following:
1. Access the terminal for your EC2 instance through Secure Shell (SSH), and log in with the appropriate user name. For more information, see [Connect to your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect.html) in the *Amazon EC2 User Guide*.
1. Using your text editor of choice, open the `/etc/amazon/efs/efs-utils.conf` file.
1. Set the `stunnel_check_cert_hostname` value to false.
1. Save the changes to the file and close it.
For more information on using encryption of data in transit, see [Mounting EFS file systems](mounting-fs.md).
## Enabling Online Certificate Status Protocol
In order to maximize file system availability in the event that the CA is not reachable from your VPC, the Online Certificate Status Protocol (OCSP) is not enabled by default when you choose to encrypt data in transit. Amazon EFS uses an [Amazon certificate authority](https://www.amazontrust.com) (CA) to issue and sign its TLS certificates, and the CA instructs the client to use OCSP to check for revoked certificates. The OCSP endpoint must be accessible over the Internet from your Virtual Private Cloud in order to check a certificate's status. Within the service, Amazon EFS continuously monitors certificate status, and issues new certificates to replace any revoked certificates it detects.
In order to provide the strongest security possible, you can enable OCSP so that your Linux clients can check for revoked certificates. OCSP protects against malicious use of revoked certificates, which is unlikely to occur within your VPC. In the event that an EFS TLS certificate is revoked, Amazon publishes a security bulletin and release a new version of EFS mount helper that rejects the revoked certificate.
**To enable OCSP on your Linux client for all future TLS connections to EFS**
1. Open a terminal on your Linux client.
1. Using your text editor of choice, open the `/etc/amazon/efs/efs-utils.conf` file.
1. Set the `stunnel_check_cert_validity` value to true.
1. Save the changes to the file and close it.
**To enable OCSP as part of the `mount` command**
+ Use the following mount command to enable OCSP when mounting the file system.
```
$ sudo mount -t efs -o tls,ocsp fs-12345678:/ /mnt/efs
```
# Enabling FIPS mode
If your operating system is using Federal Information Processing Standards (FIPS) endpoints when mounting your file system, then you must enable FIPS mode in the Amazon EFS client. Enabling the FIPS mode involves modifying the `efs-utils.conf` file on the operating system.
**Note**
FIPS mode requires that the installed version of OpenSSL is compiled with FIPS. For more information on how to configure OpenSSL with FIPS see the [OpenSSL FIPS README](https://github.com/openssl/openssl/blob/master/README-FIPS.md).
**To enable FIPS mode in the Amazon EFS client**
1. Access the terminal for your Amazon EC2 instance through Secure Shell (SSH), and log in with the appropriate user name. For more information, see [Connect to your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect.html) in the *Amazon Elastic Compute Cloud User Guide*.
1. Using your text editor of choice, open the `/etc/amazon/efs/efs-utils.conf` file.
1. Find the line containing the following text:
```
"fips_mode_enabled = false"
```
1. Change the text to the following:
```
"fips_mode_enabled = true"
```
1. Save your changes.