You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -22,142 +42,124 @@ This is the only containerized NFS server that offers **all** of the following f
22
42
23
43
Usually you can enable these modules with: `modprobe {nfs,nfsd,rpcsec_gss_krb5}`
24
44
1. The container will need to run with `CAP_SYS_ADMIN` (or `--privileged`). This is necessary as the server needs to mount several filesystems inside the container to support its operation, and performing mounts from inside a container is impossible without these capabilities.
25
-
1. The container will need local access to the files you'd like to serve via NFS. You can use Docker volumes, bind mounts, or files baked into a custom image. e.g.
1. The container will need local access to the files you'd like to serve via NFS. You can use Docker volumes, bind mounts, files baked into a custom image, or virtually any other means of supplying files to a Docker container.
30
46
31
47
## Usage
32
48
33
-
### Hello, World!
34
-
35
-
You will need to provide your desired [NFS exports](https://linux.die.net/man/5/exports) (`/etc/exports`) upon container startup. You have **three choices** for doing this:
36
-
37
-
1.**Bind mount `/etc/exports` into the container**
49
+
### Starting the server
38
50
39
-
docker run \
40
-
-v /host/path/to/exports.txt:/etc/exports:ro \
41
-
-v /host/files:/nfs \
42
-
--cap-add SYS_ADMIN \
43
-
-p 2049:2049 \
44
-
erichough/nfs-server:latest
45
-
46
-
1.**Provide each line of `/etc/exports` as an environment variable**.
51
+
Starting the `erichough/nfs-server` image will launch an NFS server. You'll need to supply some information upon container startup, which we'll cover below, but briefly speaking your `docker run` command might look something like this:
47
52
48
-
The container will look for environment variables that start with `NFS_EXPORT_` and end with an integer. e.g. `NFS_EXPORT_0`, `NFS_EXPORT_1`, etc.
53
+
docker run \
54
+
-v /host/path/to/shared/files:/nfs \
55
+
-v /host/path/to/exports.txt:/etc/exports:ro \
56
+
--cap-add SYS_ADMIN \
57
+
-p 2049:2049 \
58
+
erichough/nfs-server
59
+
60
+
Let's break that command down into its individual pieces to see what's required for a successful server startup.
As noted in the [requirements](#requirements), the container will need local access to the files you'd like to share over NFS. Some ideas for supplying these files:
* files [baked into](https://docs.docker.com/engine/reference/builder/#copy) custom image (e.g. in a `Dockerfile`: `COPY /host/files /nfs`)
60
69
61
-
e.g. in a `Dockerfile`:
70
+
You may use any combination of the above, or any other means to supply files to the container.
62
71
63
-
FROM ehough/nfs-server:latest
64
-
ADD /host/path/to/exports.txt /etc/exports
72
+
1.**Provide your desired [NFS exports](https://linux.die.net/man/5/exports) (`/etc/exports`)**
65
73
66
-
### (Optional) User ID Mapping
74
+
You'll need to tell the server which container directories to export. You have *three options* for this; choose whichever one you prefer:
67
75
68
-
If you'd like to run [`idmapd`](http://man7.org/linux/man-pages/man8/idmapd.8.html) to map between NFSv4 IDs (e.g. `foo@bar.com`) and local users, simply provide [`idmapd.conf`](https://linux.die.net/man/5/idmapd.conf) and `/etc/passwd` to the container. This step is required for Kerberos.
You can enable Kerberos security by performing the following additional actions:
82
-
83
-
1. set the environment variable `NFS_ENABLE_KERBEROS` to a non-empty value (e.g. `NFS_ENABLE_KERBEROS=1`)
84
-
1. set the server's hostname via the `--hostname` flag
85
-
1. provide `/etc/krb5.keytab` which contains a principal of the form `nfs/<hostname>`, where `<hostname>` is the hostname you supplied in the previous step.
86
-
1. provide [`/etc/krb5.conf`](https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html)
87
-
1. provide [`/etc/idmapd.conf`](https://linux.die.net/man/5/idmapd.conf)
88
-
1. provide `/etc/passwd` that contains your NFS client users
The following optional environment variables allow you to adjust the server settings to your needs.
108
-
109
-
-**`NFS_VERSION`** (default is `4.2`)
83
+
1. provide each line of `/etc/exports` as an environment variable
110
84
111
-
Set to `3`, `4`, `4.1`, or `4.2` to fine tune the NFS protocol version. Enabling any version will also enable any lesser versions. e.g. `4.2` will enable versions 4.2, 4.1, 4, **and** 3.
85
+
The container will look for environment variables that start with `NFS_EXPORT_` and end with an integer. e.g. `NFS_EXPORT_0`, `NFS_EXPORT_1`, etc.
112
86
113
-
-**`NFS_DISABLE_VERSION_3`** (*not set by default*)
Set to a non-empty value (e.g. `NFS_DISABLE_VERSION_3=1`) to disable NFS version 3 and run a version-4-only server. This setting is not compatible with `NFS_VERSION=3`.
93
+
1. bake `/etc/exports` into a custom image
116
94
117
-
-**`NFS_PORT`** (default is `2049`)
95
+
e.g. in a `Dockerfile`:
118
96
119
-
Set this to any valid port number (`1` - `65535` inclusive) to change `rpc.nfsd`'s listening port.
120
-
121
-
-**`NFS_SERVER_THREAD_COUNT`** (default is *CPU core count*)
122
-
123
-
Set this to a positive integer to control how many server threads `rpc.nfsd` will use. A good minimum is one thread per CPU core, but 4 or 8 threads per core is probably better.
124
-
125
-
-**`NFS_PORT_MOUNTD`** (default is `32767`)
97
+
```Dockerfile
98
+
FROM erichough/nfs-server
99
+
ADD /host/path/to/exports.txt /etc/exports
100
+
```
126
101
127
-
*Only needed for NFS 3*. Set this to any valid port number (`1` - `65535` inclusive) to change `rpc.mountd`'s listening port.
102
+
1. **Use `--cap-add SYS_ADMIN` or `--privileged`**
128
103
129
-
-**`NFS_PORT_STATD_IN`** (default is `32765`)
104
+
As noted in the [requirements](#requirements), the container will need additional privileges. So your `run` command will need *either*:
105
+
106
+
docker run --cap-add SYS_ADMIN ... erichough/nfs-server
107
+
108
+
or
109
+
110
+
docker run --privileged ... erichough/nfs-server
111
+
112
+
Not sure which to use? Go for `--cap-add SYS_ADMIN` as it's the lesser of two evils.
113
+
114
+
1. **Expose the server ports**
115
+
116
+
You'll need to open up at least one server port for your client connections. The ports listed in the examples below are the defaults used by this image and most can be [customized](doc/ports.md).
117
+
118
+
* If your clients connect via **NFSv4 only**, you can get by with just TCP port `2049`:
119
+
120
+
docker run -p 2049:2049 ... erichough/nfs-server
121
+
122
+
* If you'd like to support **NFSv3**, you'll need to expose a lot more ports:
123
+
124
+
docker run \
125
+
-p 2049:2049 -p 2049:2049/udp \
126
+
-p 111:111 -p 111:111/udp \
127
+
-p 32765:32765 -p 32765:32765/udp \
128
+
-p 32767:32767 -p 32767:32767/udp \
129
+
... \
130
+
erichough/nfs-server
131
+
132
+
If you pay close attention to each of the items in this section, the server should start quickly and be ready to accept your NFS clients.
133
+
134
+
### Mounting filesystems from a client
130
135
131
-
*Only needed for NFS 3*. Set this to any valid port number (`1` - `65535` inclusive) to change `rpc.statd`'s listening port.
136
+
# mount <container-IP>:/some/export /some/local/path
132
137
133
-
-**`NFS_PORT_STATD_OUT`** (default is `32766`)
138
+
## Optional Features
134
139
135
-
*Only needed for NFS 3*. Set this to any valid port number (`1` - `65535` inclusive) to change `rpc.statd`'s outgoing connection port.
140
+
* [Kerberos security](doc/feature/kerberos.md)
141
+
* [NFSv4 user ID mapping](doc/feature/nfs4-user-id-mapping.md)
142
+
* [AppArmor integration](doc/feature/apparmor.md)
136
143
137
-
-**`NFS_ENABLE_KERBEROS`** (*not set by default*)
138
-
139
-
Set to a non-empty value (e.g. `NFS_ENABLE_KERBEROS=1`) to enable Kerberos on this server. See "Kerberos" section above for further details.
140
-
141
-
### Mounting filesystems from a client
142
-
143
-
# mount -o nfsvers=4 <container-IP>:/some/export /some/local/path
144
-
145
-
### Connecting to the running container
144
+
## Advanced
146
145
147
-
# docker exec -it <container-id> bash
146
+
* [customizing which ports are used](doc/advanced/ports.md)
- Running the container with `--network host`*might* improve network performance by 10% - 20% [[1](https://jtway.co/docker-network-performance-b95bce32b4b9),[2](https://www.percona.com/blog/2016/08/03/testing-docker-multi-host-network-performance/)], though this hasn't been tested.
152
+
Please [open an issue](https://github.com/ehough/docker-nfs-server/issues) if you have any questions, constructive criticism, or can't get something to work.
152
153
153
154
## Remaining tasks
154
155
155
-
- switch back to Alpine Linux once [this bug](https://bugs.alpinelinux.org/issues/8470) in `nfs-utils` is fixed
156
+
- switch to Alpine Linux once [this bug](https://bugs.alpinelinux.org/issues/8470) in `nfs-utils` is fixed
156
157
- figure out why `rpc.nfsd` takes 5 minutes to startup/timeout unless `rpcbind` is running
By default, this image provides NFS versions 3 and 4 simultaneously. Using the following environment variables, you can fine-tune which versions are offered.
|`NFS_VERSION`| Set to `3`, `4`, `4.1`, or `4.2` to fine tune the NFS protocol version. Enabling any version will also enable any lesser versions. e.g. `4.2` will enable versions 4.2, 4.1, 4, **and** 3. |`4.2`|
8
+
|`NFS_DISABLE_VERSION_3`| Set to a non-empty value (e.g. `NFS_DISABLE_VERSION_3=1`) to disable NFS version 3 and run a version-4-only server. This setting is not compatible with `NFS_VERSION=3`|*not set*|
The following tips might improve your NFS server's performance.
4
+
5
+
* Set the **`NFS_SERVER_THREAD_COUNT`** environment variable to control how many server threads `rpc.nfsd` will use. A good minimum is one thread per CPU core, but 4 or 8 threads per core is probably better. The default is one thread per CPU core.
6
+
7
+
* Running the container with `--network host`*might* improve network performance by 10% - 20% [[1](https://jtway.co/docker-network-performance-b95bce32b4b9),[2](https://www.percona.com/blog/2016/08/03/testing-docker-multi-host-network-performance/)], though this hasn't been tested.
You can customize the ports used by the NFS server via the environment variables listed below. Each environment variable can be set to an integer between `1` and `65535`.
If your Docker host has [AppArmor](https://wiki.ubuntu.com/AppArmor) activated, you'll need to perform additional steps to allow the container to start an NFS server.
4
+
5
+
1. Ensure you have the `apparmor-utils` installed package installed on the Docker host. e.g. for Debian or Ubuntu:
6
+
7
+
$ sudo apt-get install apparmor-utils
8
+
9
+
1. Create a file on the Docker host with the following contents:
0 commit comments