Merge branch 'develop'

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [1.1.1] - 2018-08-21
+
+### Fixed
+
+* baked-in `/etc/exports` is not properly recognized ([#9](https://github.com/ehough/docker-nfs-server/issues/9))
+
 ## [1.1.0] - 2018-06-06
 
 ### Added

Dockerfile

@@ -12,8 +12,8 @@ RUN apt-get update
     apt-get clean                                                                 && \
     rm -rf /var/lib/apt/lists                                                     && \
                                                                                      \
-    # remove the default idmapd.conf
-    rm -v /etc/idmapd.conf
+    # remove the default config files
+    rm -v /etc/idmapd.conf /etc/exports
 
 # http://wiki.linux-nfs.org/wiki/index.php/Nfsv4_configuration
 RUN mkdir -p /var/lib/nfs/rpc_pipefs && \

README.md

@@ -7,11 +7,31 @@ A lightweight, robust, flexible, and containerized NFS server.
 This is the only containerized NFS server that offers **all** of the following features:
 
 - NFS versions 3, 4, or both simultaneously
-- optional Kerberos security
-- optional name/ID mapping via [`idmapd`](http://man7.org/linux/man-pages/man8/idmapd.8.html)
-- clean teardown of services upon `SIGTERM` or `SIGKILL` (no lingering `nfsd` processes on Docker host)
-- flexible construction of `/etc/exports` via a Docker bind mount *or* environment variables
+- clean teardown of services upon termination (no lingering `nfsd` processes on Docker host)
+- flexible construction of `/etc/exports`
 - extensive server configuration via environment variables
+- *optional* bonus features
+  - [Kerberos security](doc/feature/kerberos.md)
+  - [NFSv4 user ID mapping](doc/feature/nfs4-user-id-mapping.md) via [`idmapd`](http://man7.org/linux/man-pages/man8/idmapd.8.html)
+  - [AppArmor](doc/feature/apparmor.md) compatibility
+
+## Table of Contents
+
+* [Requirements](#requirements)
+* Usage
+  * [Starting the server](#starting-the-server)
+  * [Mounting filesystems from a client](#mounting-filesystems-from-a-client)
+* Optional features
+  * [Kerberos security](doc/feature/kerberos.md)
+  * [NFSv4 user ID mapping](doc/feature/nfsv4-user-id-mapping.md)
+  * [AppArmor integration](doc/feature/apparmor.md)
+* Advanced
+  * [custom server ports](doc/advanced/ports.md)
+  * [custom NFS versions offered](doc/advanced/nfs-versions.md)
+  * [performance tuning](doc/advanced/performance-tuning.md)
+* [Help!](#help!)
+* [Remaining tasks](#remaining-tasks)
+* [Acknowledgements](#acknowledgements)
 
 ## Requirements
 
@@ -22,142 +42,124 @@ This is the only containerized NFS server that offers **all** of the following f
 
    Usually you can enable these modules with: `modprobe {nfs,nfsd,rpcsec_gss_krb5}`
 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.
-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.
-
-   - `-v some_volume:/some/container/path` (Docker volume)
-   - `-v /some/path/on/host:/some/container/path` (bind mount)
-   - `ADD /some/path/on/host /some/container/path` (Dockerfile)
+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.
 
 ## Usage
 
-### Hello, World!
-
-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:
-
-1. **Bind mount `/etc/exports` into the container**
+### Starting the server
 
-       docker run                                      \
-         -v /host/path/to/exports.txt:/etc/exports:ro  \
-         -v /host/files:/nfs                           \
-         --cap-add SYS_ADMIN                           \
-         -p 2049:2049                                  \
-         erichough/nfs-server:latest
-         
-1. **Provide each line of `/etc/exports` as an environment variable**.
+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:
 
-    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.
+    docker run                                     \
+      -v /host/path/to/shared/files:/nfs           \
+      -v /host/path/to/exports.txt:/etc/exports:ro \
+      --cap-add SYS_ADMIN                          \
+      -p 2049:2049                                 \
+      erichough/nfs-server
+      
+Let's break that command down into its individual pieces to see what's required for a successful server startup.
 
-       docker run                                                            \
-         -e NFS_EXPORT_0='/nfs/foo 192.168.1.0/24(ro,no_subtree_check)'      \
-         -e NFS_EXPORT_1='/nfs/bar 123.123.123.123/32(rw,no_subtree_check)'  \
-         -v /host/path/foo:/nfs/foo                                          \
-         -v /host/path/bar:/nfs/bar                                          \
-         --cap-add SYS_ADMIN                                                 \
-         -p 2049:2049                                                        \
-         erichough/nfs-server:latest
+1. **Provide the files to be shared over NFS**
 
-1. **Bake `/etc/exports` into a custom image**
+   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:
+
+      * [bind mounts](https://docs.docker.com/storage/bind-mounts/) (`-v /host/path/to/shared/files:/nfs`)
+      * [volumes](https://docs.docker.com/storage/volumes/) (`-v some_volume:/nfs`)
+      * files [baked into](https://docs.docker.com/engine/reference/builder/#copy) custom image (e.g. in a `Dockerfile`: `COPY /host/files /nfs`)
 
-    e.g. in a `Dockerfile`:
+   You may use any combination of the above, or any other means to supply files to the container.
 
-       FROM ehough/nfs-server:latest
-       ADD /host/path/to/exports.txt /etc/exports
+1. **Provide your desired [NFS exports](https://linux.die.net/man/5/exports) (`/etc/exports`)**
 
-### (Optional) User ID Mapping
+   You'll need to tell the server which container directories to export. You have *three options* for this; choose whichever one you prefer:
 
-If you'd like to run [`idmapd`](http://man7.org/linux/man-pages/man8/idmapd.8.html) to map between NFSv4 IDs (e.g. `[email protected]`) 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.
+   1. bind mount `/etc/exports` into the container
 
-       docker run                                          \
-         -v /host/path/to/exports.txt:/etc/exports:ro      \
-         -v /host/files:/nfs                               \
-         -v /host/path/to/idmapd.conf:/etc/idmapd.conf:ro  \
-         -v /etc/passwd:/etc/passwd:ro                     \
-         --cap-add SYS_ADMIN                               \
-         -p 2049:2049                                      \
-         erichough/nfs-server:latest
+          docker run                                      \
+            -v /host/path/to/exports.txt:/etc/exports:ro  \
+            ...                                           \
+            erichough/nfs-server
          
-### (Optional) Kerberos
-
-You can enable Kerberos security by performing the following additional actions:
-
-1. set the environment variable `NFS_ENABLE_KERBEROS` to a non-empty value (e.g. `NFS_ENABLE_KERBEROS=1`)
-1. set the server's hostname via the `--hostname` flag
-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.
-1. provide [`/etc/krb5.conf`](https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html)
-1. provide [`/etc/idmapd.conf`](https://linux.die.net/man/5/idmapd.conf)
-1. provide `/etc/passwd` that contains your NFS client users
-
-Here's an example:
-
-       docker run                                            \
-         -v /host/path/to/exports.txt:/etc/exports:ro        \
-         -v /host/files:/nfs                                 \
-         -e NFS_ENABLE_KERBEROS=1                            \
-         --hostname my-nfs-server.com                        \
-         -v /host/path/to/server.keytab:/etc/krb5.keytab:ro  \
-         -v /host/path/to/server.krb5conf:/etc/krb5.conf:ro  \
-         -v /host/path/to/idmapd.conf:/etc/idmapd.conf:ro    \
-         -v /etc/passwd:/etc/passwd:ro                       \
-         --cap-add SYS_ADMIN                                 \
-         -p 2049:2049                                        \
-         erichough/nfs-server:latest
-
-### Environment Variables
-
-The following optional environment variables allow you to adjust the server settings to your needs.
-
-- **`NFS_VERSION`** (default is `4.2`)
+   1. provide each line of `/etc/exports` as an environment variable
 
-  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.
+       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.
 
-- **`NFS_DISABLE_VERSION_3`** (*not set by default*)
+          docker run                                                            \
+            -e NFS_EXPORT_0='/nfs/foo                  *(ro,no_subtree_check)'  \
+            -e NFS_EXPORT_1='/nfs/bar 123.123.123.123/32(rw,no_subtree_check)'  \
+            ...                                                                 \
+            erichough/nfs-server
 
-  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`.
+   1. bake `/etc/exports` into a custom image
 
-- **`NFS_PORT`** (default is `2049`)
+       e.g. in a `Dockerfile`:
 
-  Set this to any valid port number (`1` - `65535` inclusive) to change `rpc.nfsd`'s listening port.
-
-- **`NFS_SERVER_THREAD_COUNT`** (default is *CPU core count*)
-
-  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.
-
-- **`NFS_PORT_MOUNTD`** (default is `32767`)
+       ```Dockerfile
+       FROM erichough/nfs-server
+       ADD /host/path/to/exports.txt /etc/exports
+       ```
 
-  *Only needed for NFS 3*. Set this to any valid port number (`1` - `65535` inclusive) to change `rpc.mountd`'s listening port.
+1. **Use `--cap-add SYS_ADMIN` or `--privileged`**
 
-- **`NFS_PORT_STATD_IN`** (default is `32765`)
+   As noted in the [requirements](#requirements), the container will need additional privileges. So your `run` command will need *either*:
+
+       docker run --cap-add SYS_ADMIN ... erichough/nfs-server
+
+    or
+
+       docker run --privileged ... erichough/nfs-server
+
+    Not sure which to use? Go for `--cap-add SYS_ADMIN` as it's the lesser of two evils.
+
+1. **Expose the server ports**
+
+   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).
+
+   * If your clients connect via **NFSv4 only**, you can get by with just TCP port `2049`:
+
+         docker run -p 2049:2049 ... erichough/nfs-server
+
+   * If you'd like to support **NFSv3**, you'll need to expose a lot more ports:
+
+         docker run                          \
+           -p 2049:2049   -p 2049:2049/udp   \
+           -p 111:111     -p 111:111/udp     \
+           -p 32765:32765 -p 32765:32765/udp \
+           -p 32767:32767 -p 32767:32767/udp \
+           ...                               \
+           erichough/nfs-server
+
+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.
+
+### Mounting filesystems from a client
 
-  *Only needed for NFS 3*. Set this to any valid port number (`1` - `65535` inclusive) to change `rpc.statd`'s listening port.
+    # mount <container-IP>:/some/export /some/local/path
 
-- **`NFS_PORT_STATD_OUT`** (default is `32766`)
+## Optional Features
 
-  *Only needed for NFS 3*. Set this to any valid port number (`1` - `65535` inclusive) to change `rpc.statd`'s outgoing connection port.
+  * [Kerberos security](doc/feature/kerberos.md)
+  * [NFSv4 user ID mapping](doc/feature/nfs4-user-id-mapping.md)
+  * [AppArmor integration](doc/feature/apparmor.md)
 
-- **`NFS_ENABLE_KERBEROS`** (*not set by default*)
-
-  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.
-
-### Mounting filesystems from a client
-
-    # mount -o nfsvers=4 <container-IP>:/some/export /some/local/path
-
-### Connecting to the running container
+## Advanced
 
-    # docker exec -it <container-id> bash
+  * [customizing which ports are used](doc/advanced/ports.md)
+  * [customizing NFS versions offered](doc/advanced/nfs-versions.md)
+  * [performance tuning](doc/advanced/performance-tuning.md)
 
-## Performance considerations
+## Help!
 
-- 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.
+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.
 
 ## Remaining tasks
 
-- switch back to Alpine Linux once [this bug](https://bugs.alpinelinux.org/issues/8470) in `nfs-utils` is fixed
+- switch to Alpine Linux once [this bug](https://bugs.alpinelinux.org/issues/8470) in `nfs-utils` is fixed
 - figure out why `rpc.nfsd` takes 5 minutes to startup/timeout unless `rpcbind` is running
+- add more examples, including Docker Compose
 
 ## Acknowledgements
 
-This work was based heavily on prior projects:
+This work was based on prior projects:
 
 - [f-u-z-z-l-e/docker-nfs-server](https://github.com/f-u-z-z-l-e/docker-nfs-server)
-- [sjiveson/nfs-server-alpine](https://github.com/sjiveson/nfs-server-alpine)
+- [sjiveson/nfs-server-alpine](https://github.com/sjiveson/nfs-server-alpine)

doc/advanced/nfs-versions.md

@@ -0,0 +1,8 @@
+# Customize NFS versions offered
+
+By default, this image provides NFS versions 3 and 4 simultaneously. Using the following environment variables, you can fine-tune which versions are offered.
+
+| Environment variable    | Description                                                                                                                                                                                | Default   |
+|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
+| `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`     |
+| `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* |

doc/advanced/performance-tuning.md

@@ -0,0 +1,7 @@
+# Performance tuning
+
+The following tips might improve your NFS server's performance.
+
+* 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. 
+
+* 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.

doc/advanced/ports.md

@@ -0,0 +1,10 @@
+# Customizing ports
+
+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`.
+
+| Environment variable | Description                                 | Default |
+|----------------------|---------------------------------------------|---------|
+| `NFS_PORT`           | `rpc.nfsd`'s listening port.                | `2049`  |
+| `NFS_PORT_MOUNTD`    | *NFSv3 only*. `rpc.mountd'` listening port. | `32767` |
+| `NFS_PORT_STATD_IN`  | *NFSv3 only*. `rpc.statd`'s listening port. | `32765` |
+| `NFS_PORT_STATD_OUT` | *NFSv3 only*. `rpc.statd`'s outgoing port.  | `32766` |

doc/feature/apparmor.md

@@ -0,0 +1,48 @@
+# AppArmor
+
+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.
+
+1. Ensure you have the `apparmor-utils` installed package installed on the Docker host. e.g. for Debian or Ubuntu:
+
+       $ sudo apt-get install apparmor-utils
+
+1. Create a file on the Docker host with the following contents:
+
+       #include <tunables/global>
+       profile erichough-nfs flags=(attach_disconnected,mediate_deleted) {
+         #include <abstractions/lxc/container-base>
+         mount fstype=nfs*,
+         mount fstype=rpc_pipefs,
+       }
+       
+1. Load this profile into the kernel with [`apparmor_parser`](http://manpages.ubuntu.com/manpages/xenial/man8/apparmor_parser.8.html):
+
+       $ sudo apparmor_parser -r -W /path/to/file/from/previous/step
+
+1. Add `--security-opt apparmor=erichough-nfs` to your `docker run` command. e.g.
+
+       docker run                                \
+         -v /path/to/share:/nfs                  \
+         -v /path/to/exports.txt:/etc/exports:ro \
+         --cap-add SYS_ADMIN                     \
+         -p 2049:2049                            \
+         --security-opt apparmor=erichough-nfs   \
+         erichough/nfs-server
+         
+   or in `docker-compose.yml`:
+
+   ```YAML
+   version: 3
+   services:
+     nfs:
+       image: erichough/nfs-server
+       volumes:
+         - /path/to/share:/nfs
+         - /path/to/exports.txt:/etc/exports:ro
+       cap_add:
+         - SYS_ADMIN
+       ports:
+         - 2049:2049
+       security_opt:
+         - apparmor=erichough-nfs
+   ```