From 7abd99b022ba7c58a0d09845934ed9d00cb6a88b Mon Sep 17 00:00:00 2001 From: Maciej Pijanowski Date: Thu, 31 Jan 2019 16:23:02 +0100 Subject: [PATCH 1/5] README.md: remove extra spaces Signed-off-by: Maciej Pijanowski --- README.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index fb5c96c..9d3ebdc 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ This is the only containerized NFS server that offers **all** of the following f - `nfs` - `nfsd` - `rpcsec_gss_krb5` (*only if Kerberos is used*) - + 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, files baked into a custom image, or virtually any other means of supplying files to a Docker container. @@ -56,13 +56,13 @@ Starting the `erichough/nfs-server` image will launch an NFS server. You'll need --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. 1. **Provide the files to be shared over NFS** 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:/some/container/path`) * [volumes](https://docs.docker.com/storage/volumes/) (`-v some_volume:/some/container/path`) * files [baked into](https://docs.docker.com/engine/reference/builder/#copy) custom image (e.g. in a `Dockerfile`: `COPY /host/files /some/container/path`) @@ -79,7 +79,7 @@ Let's break that command down into its individual pieces to see what's required -v /host/path/to/exports.txt:/etc/exports:ro \ ... \ erichough/nfs-server - + 1. provide each line of `/etc/exports` as an environment variable 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. @@ -102,25 +102,26 @@ Let's break that command down into its individual pieces to see what's required 1. **Use `--cap-add SYS_ADMIN` or `--privileged`** 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 \ @@ -128,9 +129,9 @@ Let's break that command down into its individual pieces to see what's required -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 # mount :/some/export /some/local/path @@ -140,7 +141,7 @@ If you pay close attention to each of the items in this section, the server shou * [Kerberos security](doc/feature/kerberos.md) * [NFSv4 user ID mapping](doc/feature/nfs4-user-id-mapping.md) * [AppArmor integration](doc/feature/apparmor.md) - + ## Advanced * [customizing which ports are used](doc/advanced/ports.md) From d45496d1641bdb6495d928aec21b5bb3a2e976d3 Mon Sep 17 00:00:00 2001 From: Maciej Pijanowski Date: Thu, 31 Jan 2019 16:31:26 +0100 Subject: [PATCH 2/5] doc/examples: add docker-compose example Signed-off-by: Maciej Pijanowski --- README.md | 4 ++ doc/examples/docker-compose.md | 71 +++++++++++++++++++++++++++++++++ doc/examples/docker-compose.yml | 18 +++++++++ 3 files changed, 93 insertions(+) create mode 100644 doc/examples/docker-compose.md create mode 100644 doc/examples/docker-compose.yml diff --git a/README.md b/README.md index 9d3ebdc..6dec45d 100644 --- a/README.md +++ b/README.md @@ -148,6 +148,10 @@ If you pay close attention to each of the items in this section, the server shou * [customizing NFS versions offered](doc/advanced/nfs-versions.md) * [performance tuning](doc/advanced/performance-tuning.md) +## Examples + + * [docker-compose](doc/examples/docker-compose.md) + ## Help! 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. diff --git a/doc/examples/docker-compose.md b/doc/examples/docker-compose.md new file mode 100644 index 0000000..a71b78e --- /dev/null +++ b/doc/examples/docker-compose.md @@ -0,0 +1,71 @@ +# docker-compose example + +## Introduction + +The example provided [docker-compose file](docker-compose.yml) allows for: +* building the container, +* running the container in `NFS v4` mode only (`NFS v3` is disabled) - see more + in the + [customize NFS versions](../advanced/nfs-versions.md#customize-nfs-versions-offered) + +Following stuff gets mounted into the contianer: + +* `nfs-export` directory: + +``` +nfs-export +└── debian + ├── a + ├── b + ├── c + └── d +``` + +* `exports.txt` file: + +``` +/export *(rw,fsid=0,no_subtree_check,sync) +/export/debian *(rw,nohide,insecure,no_subtree_check,sync) +``` + +## Build + +In order to build the container: + +``` +docker-compose build +``` + +## Run + +In order to run the container: + +``` +docker-compose up +``` + +## Test + +Check if we can mount the directory: + +``` +sudo mount LOCAL_IP:/ /mnt -v +``` + +In the command output we can inspect which `NFS` version was used: + +``` +mount.nfs: timeout set for Thu Jan 31 16:16:20 2019 +mount.nfs: trying text-based options 'vers=4.2,addr=LOCAL_IP,clientaddr=LOCAL_IP' +``` + +Inspect mounted directory content: + +``` +/mnt +└── debian + ├── a + ├── b + ├── c + └── d +``` diff --git a/doc/examples/docker-compose.yml b/doc/examples/docker-compose.yml new file mode 100644 index 0000000..cca04b9 --- /dev/null +++ b/doc/examples/docker-compose.yml @@ -0,0 +1,18 @@ +version: '3' + +services: + nfs-server: + build: + context: ../../ + dockerfile: Dockerfile + image: "erichough/nfs-server" + container_name: "nfs-server" + privileged: true + ports: + - "2049:2049" + volumes: + - "$PWD/exports.txt:/etc/exports:ro" + - "$PWD/nfs-export:/export" + environment: + NFS_VERSION: 4.2 + NFS_DISABLE_VERSION_3: 1 From 597213f6b98b0df3d87c2b800603929c0796fe51 Mon Sep 17 00:00:00 2001 From: Maciej Pijanowski Date: Thu, 31 Jan 2019 16:33:50 +0100 Subject: [PATCH 3/5] doc/examples/docker-compose.md: fix typo Signed-off-by: Maciej Pijanowski --- doc/examples/docker-compose.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/examples/docker-compose.md b/doc/examples/docker-compose.md index a71b78e..28c57b6 100644 --- a/doc/examples/docker-compose.md +++ b/doc/examples/docker-compose.md @@ -8,7 +8,7 @@ The example provided [docker-compose file](docker-compose.yml) allows for: in the [customize NFS versions](../advanced/nfs-versions.md#customize-nfs-versions-offered) -Following stuff gets mounted into the contianer: +Following stuff gets mounted into the container: * `nfs-export` directory: From 8f05c9d8498fd428cc717a21d5479b89414956cd Mon Sep 17 00:00:00 2001 From: Maciej Pijanowski Date: Thu, 31 Jan 2019 16:44:52 +0100 Subject: [PATCH 4/5] docker-compose.md: add issues section Signed-off-by: Maciej Pijanowski --- doc/examples/docker-compose.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/doc/examples/docker-compose.md b/doc/examples/docker-compose.md index 28c57b6..fe87ce8 100644 --- a/doc/examples/docker-compose.md +++ b/doc/examples/docker-compose.md @@ -69,3 +69,20 @@ Inspect mounted directory content: ├── c └── d ``` + +## Possible issues + +In case of the: + +``` +nfs-server | ================================================================== +nfs-server | STARTING SERVICES ... +nfs-server | ================================================================== +nfs-server | ----> mounting rpc_pipefs filesystem onto /var/lib/nfs/rpc_pipefs +nfs-server | mount: mounting rpc_pipefs on /var/lib/nfs/rpc_pipefs failed: Permission denied +nfs-server | ----> +nfs-server | ----> ERROR: unable to mount rpc_pipefs filesystem onto /var/lib/nfs/rpc_pipefs +nfs-server | ----> +``` + +Please refer to the [apparmor document](../feature/apparmor.md#apparmor). From 6cef2478b085278582417c325ff604150a85d729 Mon Sep 17 00:00:00 2001 From: Maciej Pijanowski Date: Thu, 31 Jan 2019 16:45:29 +0100 Subject: [PATCH 5/5] examples/docker-compose.yml: use SYS_ADMIN capp instead of privileged Signed-off-by: Maciej Pijanowski --- doc/examples/docker-compose.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/examples/docker-compose.yml b/doc/examples/docker-compose.yml index cca04b9..a121d4c 100644 --- a/doc/examples/docker-compose.yml +++ b/doc/examples/docker-compose.yml @@ -7,7 +7,8 @@ services: dockerfile: Dockerfile image: "erichough/nfs-server" container_name: "nfs-server" - privileged: true + cap_add: + - SYS_ADMIN ports: - "2049:2049" volumes: