README.md 4.37 KB
Newer Older
1
2
[![CircleCI](https://circleci.com/gh/aws/efs-utils.svg?style=svg)](https://circleci.com/gh/aws/efs-utils)

Max Beckett's avatar
Max Beckett committed
3
4
5
6
7
8
9
10
11
12
13
14
# efs-utils

Utilities for Amazon Elastic File System (EFS)

The `efs-utils` package has been verified against the following Linux distributions:

| Distribution | Package Type | `init` System |
| ------------ | ------------ | ------------- |
| Amazon Linux 2017.09 | `rpm` | `upstart` |
| Amazon Linux 2 | `rpm` | `systemd` |
| CentOS 7 | `rpm` | `systemd` |
| RHEL 7 | `rpm`| `systemd` |
Max Beckett's avatar
Max Beckett committed
15
| RHEL 8 | `rpm`| `systemd` |
16
17
| Fedora 28 | `rpm` | `systemd` |
| Fedora 29 | `rpm` | `systemd` |
18
19
20
| Fedora 30 | `rpm` | `systemd` |
| Fedora 31 | `rpm` | `systemd` |
| Fedora 32 | `rpm` | `systemd` |
Max Beckett's avatar
Max Beckett committed
21
| Debian 9 | `deb` | `systemd` |
Yuan Gao's avatar
Yuan Gao committed
22
| Debian 10 | `deb` | `systemd` |
Max Beckett's avatar
Max Beckett committed
23
| Ubuntu 16.04 | `deb` | `systemd` |
24
| Ubuntu 18.04 | `deb` | `systemd` |
25
| Ubuntu 20.04 | `deb` | `systemd` |
Max Beckett's avatar
Max Beckett committed
26

Ian Patel's avatar
Ian Patel committed
27
28
## Prerequisites

29
* `nfs-utils` (RHEL/CentOS/Amazon Linux/Fedora) or `nfs-common` (Debian/Ubuntu)
Ian Patel's avatar
Ian Patel committed
30
31
32
33
* OpenSSL 1.0.2+
* Python 2.7+
* `stunnel` 4.56+

Max Beckett's avatar
Max Beckett committed
34
35
36
37
38
39
40
41
42
43
44
45
46
47
## Installation

### On Amazon Linux distributions

For those using Amazon Linux or Amazon Linux 2, the easiest way to install `efs-utils` is from Amazon's repositories:

```
$ sudo yum -y install amazon-efs-utils
```

### On other Linux distributions

Other distributions require building the package from source and installing it.

48
- To build and install an RPM:
Max Beckett's avatar
Max Beckett committed
49
50

```
51
$ sudo yum -y install git rpm-build make
Max Beckett's avatar
Max Beckett committed
52
53
54
55
56
57
58
59
60
61
$ git clone https://github.com/aws/efs-utils
$ cd efs-utils
$ make rpm
$ sudo yum -y install build/amazon-efs-utils*rpm
```

- To build and install a Debian package:

```
$ sudo apt-get update
62
63
64
$ sudo apt-get -y install git binutils
$ git clone https://github.com/aws/efs-utils
$ cd efs-utils
Max Beckett's avatar
Max Beckett committed
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
$ ./build-deb.sh
$ sudo apt-get -y install ./build/amazon-efs-utils*deb
```

#### Run tests

- [Set up a virtualenv](http://libzx.so/main/learning/2016/03/13/best-practice-for-virtualenv-and-git-repos.html) for efs-utils

```
$ virtualenv ~/.envs/efs-utils
$ source ~/.envs/efs-utils/bin/activate
$ pip install -r requirements.txt
```

- Run tests

```
$ make test
```

## Usage

### mount.efs

`efs-utils` includes a mount helper utility to simplify mounting and using EFS file systems.

To mount with the recommended default options, simply run:

```
$ sudo mount -t efs file-system-id efs-mount-point/
```

97
98
99
100
101
102
To mount file system within a given network namespace, run:

```
$ sudo mount -t efs -o netns=netns-path file-system-id efs-mount-point/
```

103
To mount over TLS, simply add the `tls` option:
Max Beckett's avatar
Max Beckett committed
104
105

```
106
$ sudo mount -t efs -o tls file-system-id efs-mount-point/
Max Beckett's avatar
Max Beckett committed
107
108
```

109
To authenticate with EFS using the system’s IAM identity, add the `iam` option. This option requires the `tls` option.
Max Beckett's avatar
Max Beckett committed
110
111

```
112
113
114
115
$ sudo mount -t efs -o tls,iam file-system-id efs-mount-point/
```

To mount using an access point, use the `accesspoint=` option. This option requires the `tls` option.
116
The access point must be in the "available" state before it can be used to mount EFS.
117
118
119
120
121
122
123
124
125

```
$ sudo mount -t efs -o tls,accesspoint=access-point-id file-system-id efs-mount-point/
```

To mount your file system automatically with any of the options above, you can add entries to `/efs/fstab` like:

```
file-system-id efs-mount-point efs _netdev,tls,iam,accesspoint=access-point-id 0 0
Max Beckett's avatar
Max Beckett committed
126
127
```

128
For more information on mounting with the mount helper, see the manual page:
Max Beckett's avatar
Max Beckett committed
129
130

```
131
man mount.efs
Max Beckett's avatar
Max Beckett committed
132
133
```

134
or refer to the [documentation](https://docs.aws.amazon.com/efs/latest/ug/using-amazon-efs-utils.html).
Max Beckett's avatar
Max Beckett committed
135

136
### amazon-efs-mount-watchdog
Max Beckett's avatar
Max Beckett committed
137
138
139

`efs-utils` contains a watchdog process to monitor the health of TLS mounts. This process is managed by either `upstart` or `systemd` depending on your Linux distribution, and is started automatically the first time an EFS file system is mounted over TLS.

Ian Patel's avatar
Ian Patel committed
140
141
## Upgrading stunnel for RHEL/CentOS

Max Beckett's avatar
Max Beckett committed
142
By default, when using the EFS mount helper with TLS, it enforces certificate hostname checking. The EFS mount helper uses the `stunnel` program for its TLS functionality. Please note that some versions of Linux do not include a version of `stunnel` that supports TLS features by default. When using such a Linux version, mounting an EFS file system using TLS will fail. 
Ian Patel's avatar
Ian Patel committed
143
144
145

Once you’ve installed the `amazon-efs-utils` package, to upgrade your system’s version of `stunnel`, see [Upgrading Stunnel](https://docs.aws.amazon.com/efs/latest/ug/using-amazon-efs-utils.html#upgrading-stunnel).

Max Beckett's avatar
Max Beckett committed
146
147
148
149
## License Summary

This code is made available under the MIT license.