From a4a19ff61539f4a6faeca23c098643da74a8b412 Mon Sep 17 00:00:00 2001 From: jakeiotechsys Date: Fri, 23 Aug 2024 10:21:30 +0100 Subject: [PATCH 1/4] feat: docker rootless Updated docs to use make run where needed Signed-off-by: jakeiotechsys --- docs_src/getting-started/Ch-GettingStartedDockerUsers.md | 9 +++------ docs_src/getting-started/Ch-GettingStartedHybrid.md | 2 +- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/docs_src/getting-started/Ch-GettingStartedDockerUsers.md b/docs_src/getting-started/Ch-GettingStartedDockerUsers.md index d78c767dc4..e4fc1b2a6f 100644 --- a/docs_src/getting-started/Ch-GettingStartedDockerUsers.md +++ b/docs_src/getting-started/Ch-GettingStartedDockerUsers.md @@ -112,10 +112,10 @@ See the README document in the compose-builder directory for details on all the Now that you have the EdgeX Docker Compose file, you are ready to run EdgeX. Follow these steps to get the container images and start EdgeX! -In a command terminal, change directories to the location of your docker-compose.yml. Run the following command in the terminal to pull (fetch) and then start the EdgeX containers. +In a command terminal, change directories root edgex-compose directory containing the file docker-compose.yml. Run the following command in the terminal to pull (fetch) and then start the EdgeX containers. ``` bash -docker-compose up -d +make run ``` !!! Warning If you are using Docker Compose Version 2, please replace `docker-compose` with `docker compose` before proceeding. This change should be applied to all the `docker-compose` in this tutorial. See: for more information. @@ -124,12 +124,9 @@ docker-compose up -d ``` bash docker-compose pull - docker-compose up -d + make run ``` -!!! Note - The -d option indicates you want Docker Compose to run the EdgeX containers in detached mode - that is to run the containers in the background. Without -d, the containers will all start in the terminal and in order to use the terminal further you have to stop the containers. - ### Verify EdgeX Foundry Running In the same terminal, run the process status command shown below to confirm that all the diff --git a/docs_src/getting-started/Ch-GettingStartedHybrid.md b/docs_src/getting-started/Ch-GettingStartedHybrid.md index 14850428cf..8e0774e5bf 100644 --- a/docs_src/getting-started/Ch-GettingStartedHybrid.md +++ b/docs_src/getting-started/Ch-GettingStartedHybrid.md @@ -21,7 +21,7 @@ EdgeX environment up and running via Docker containers. How would you set up thi *Run the EdgeX containers and then stop the service container that you are going to work on - in this case the virtual device service container.* !!! Note - These notes assume you are working with the EdgeX Minnesota or later release. It also assumes you have downloaded the appropriate Docker Compose file and have named it `docker-compose.yml` so you don't have to specify the file name each time you run a Docker Compose command. Some versions of EdgeX may require other or additional containers to run. + These notes assume you are working with the EdgeX Minnesota or later release. It also assumes you have downloaded the appropriate Docker Compose file and have named it `docker-compose.yml` so you don't have to specify the file name each time you run a Docker Compose command. Some versions of EdgeX may require other or additional containers to run. If runnig with security, you may need to manually enter the memory limits for vault in the compose file. !!! Tip You can also use the EdgeX Compose Builder tool to create a custom Docker Compose file with just the services you want. See the [Compose Builder documentation](./Ch-GettingStartedDockerUsers.md#generate-a-custom-docker-compose-file) on and checkout the [Compose Builder tool in GitHub](https://github.com/edgexfoundry/edgex-compose/tree/{{edgexversion}}/compose-builder). From cd036250312623c15a95e0c4b5ba47c7cf7b6105 Mon Sep 17 00:00:00 2001 From: jakeiotechsys Date: Fri, 23 Aug 2024 14:26:33 +0100 Subject: [PATCH 2/4] feat: docker rootless Initial stage of docs writing Signed-off-by: jakeiotechsys --- docs_src/security/Rootless-Docker.md | 41 ++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs_src/security/Rootless-Docker.md diff --git a/docs_src/security/Rootless-Docker.md b/docs_src/security/Rootless-Docker.md new file mode 100644 index 0000000000..ec5ab3067a --- /dev/null +++ b/docs_src/security/Rootless-Docker.md @@ -0,0 +1,41 @@ +# Rootless Docker Environment + +A rootless Docker environment enhances security by limiting the privileges +of the Docker daemon. This is achieved by running the Docker daemon as a non-root user. + +Some advantages of a rootless Docker environment include: +* Enhanced Security: Reduce risk of privilege escalation and provide user namespace isolation +* Non-Privileged Access: Allows users to run Docker without root or sudo access +* Flexibility: Suitable for environments without root access, such as shared servers +* Improved File System Security: Containers do not have access to any non-root space folders on the host system + +## Requirements +There are four requirements to run Edgex in a rootless Docker environment: + +1. The host docker environment must be configured to run Docker in rootless mode (see [Docker Rootless Mode](https://docs.docker.com/engine/security/rootless/)) +If docker is installed, follow the instructions in the above link to move your environment over to +a rootless docker environment. You will find that you can now run docker commands without sudo, +and that the docker socket is now located in /run/user/{USERID}/docker.sock instead of /var/run/docker.sock. + +2. Memory locking must be disabled for the Vault container +Vault locks memory by default to disable swapping to disk. While this is a more secure, it requires +access to the mlock() sys call which requires root privileges. +In order for us to run Vault in a rootless environment, we need to disable this feature. +This is done by setting memory limits in the compose file and by adding `disable_mlock = true` to the local vault config. + +3. Docker socket volume mappings must be mapped to non-root user docker installation location +In a default (rootful) docker installation, the docker socket is mapped to /var/run/docker.sock. +When the docker installation is configured to be a rootless environment the location of the docker socket +is moved to /run/user/{USERID}/docker.sock. The portainer and security-spire-agent containers both map in the +docker socket to manage containers, so must be remapped to the new location. + +4. Serial port permissions need to be set to allow non-root user access to the serial port +A container running in a rootful docker environment can easily mount in serial ports on the host system, +but this is not the case for a rootless docker environment. Serial ports are owned by the root user, +so to access them in a rootless environment, we need to set the permissions to allow the non-root user to access them. + +!!! Note: + Setting serial port permissions to 006 or 666 will allow the non-root user to access the serial port via + volume mounting. + +## Running EdgeX in a rootless Docker environment From e39d79718e595facb28ce808ef2b1cdb799ffbd2 Mon Sep 17 00:00:00 2001 From: jakeiotechsys Date: Fri, 23 Aug 2024 15:11:17 +0100 Subject: [PATCH 3/4] feat: docker rootless Added nav Signed-off-by: jakeiotechsys --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index bb474e801e..898af64228 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -337,6 +337,7 @@ nav: - security/Ch-CORS-Settings.md - security/Ch-DelayedStartServices.md - security/Ch-RemoteDeviceServices.md + - security/Rootless-Docker.md - V3 Migration: security/V3Migration.md - Threat Models: - threat-models/secret-store/README.md From 240b36fd10821598928761f8d0f7b7ec437161e0 Mon Sep 17 00:00:00 2001 From: jakeiotechsys Date: Fri, 23 Aug 2024 15:11:38 +0100 Subject: [PATCH 4/4] feat: docker rootless Added more detail and formatting nicities Signed-off-by: jakeiotechsys --- docs_src/security/Rootless-Docker.md | 76 ++++++++++++++++++---------- 1 file changed, 50 insertions(+), 26 deletions(-) diff --git a/docs_src/security/Rootless-Docker.md b/docs_src/security/Rootless-Docker.md index ec5ab3067a..4ad658463f 100644 --- a/docs_src/security/Rootless-Docker.md +++ b/docs_src/security/Rootless-Docker.md @@ -4,38 +4,62 @@ A rootless Docker environment enhances security by limiting the privileges of the Docker daemon. This is achieved by running the Docker daemon as a non-root user. Some advantages of a rootless Docker environment include: -* Enhanced Security: Reduce risk of privilege escalation and provide user namespace isolation -* Non-Privileged Access: Allows users to run Docker without root or sudo access -* Flexibility: Suitable for environments without root access, such as shared servers -* Improved File System Security: Containers do not have access to any non-root space folders on the host system + +* __Enhanced Security:__ Reduce risk of privilege escalation and provide user namespace isolation +* __Non-Privileged Access:__ Allows users to run Docker without root or sudo access +* __Flexibility:__ Suitable for environments without root access, such as shared servers +* __Improved File System Security:__ Containers do not have access to any non-root space folders on the host system ## Requirements There are four requirements to run Edgex in a rootless Docker environment: 1. The host docker environment must be configured to run Docker in rootless mode (see [Docker Rootless Mode](https://docs.docker.com/engine/security/rootless/)) -If docker is installed, follow the instructions in the above link to move your environment over to -a rootless docker environment. You will find that you can now run docker commands without sudo, -and that the docker socket is now located in /run/user/{USERID}/docker.sock instead of /var/run/docker.sock. - -2. Memory locking must be disabled for the Vault container -Vault locks memory by default to disable swapping to disk. While this is a more secure, it requires -access to the mlock() sys call which requires root privileges. -In order for us to run Vault in a rootless environment, we need to disable this feature. -This is done by setting memory limits in the compose file and by adding `disable_mlock = true` to the local vault config. - -3. Docker socket volume mappings must be mapped to non-root user docker installation location -In a default (rootful) docker installation, the docker socket is mapped to /var/run/docker.sock. -When the docker installation is configured to be a rootless environment the location of the docker socket -is moved to /run/user/{USERID}/docker.sock. The portainer and security-spire-agent containers both map in the -docker socket to manage containers, so must be remapped to the new location. - -4. Serial port permissions need to be set to allow non-root user access to the serial port -A container running in a rootful docker environment can easily mount in serial ports on the host system, -but this is not the case for a rootless docker environment. Serial ports are owned by the root user, -so to access them in a rootless environment, we need to set the permissions to allow the non-root user to access them. - -!!! Note: + + If docker is installed, follow the instructions in the above link to move your environment over to + a rootless docker environment. You will find that you can now run docker commands without sudo, + and that the docker socket is now located in /run/user/{USERID}/docker.sock instead of /var/run/docker.sock. + +2. Memory locking must be disabled for the Vault container: + + Vault locks memory by default to disable swapping to disk. While this is a more secure, it requires + access to the mlock() sys call which requires root privileges. + In order for us to run Vault in a rootless environment, we need to disable this feature. + This is done by setting memory limits in the compose file and by adding `disable_mlock = true` to the local vault config. + More can be found at the [Vault documentation](https://www.vaultproject.io/docs/configuration/storage/file). + +3. Docker socket volume mappings must be mapped to non-root user docker installation location: + + In a default (rootful) docker installation, the docker socket is mapped to /var/run/docker.sock. + When the docker installation is configured to be a rootless environment the location of the docker socket + is moved to /run/user/{USERID}/docker.sock. The portainer and security-spire-agent containers both map in the + docker socket to manage containers, so must be remapped to the new location. + +4. Serial port permissions need to be set to allow non-root user access to the serial port: + + A container running in a rootful docker environment can easily mount in serial ports on the host system, + but this is not the case for a rootless docker environment. Serial ports are owned by the root user, + so to access them in a rootless environment, we need to set the permissions to allow the non-root user to access them. + +!!! Note Setting serial port permissions to 006 or 666 will allow the non-root user to access the serial port via volume mounting. ## Running EdgeX in a rootless Docker environment + +### Install Rootless Docker Environment +Please refer to the [Docker Rootless Mode](https://docs.docker.com/engine/security/rootless/) documentation for instructions on how to configure a rootless docker environment. + +### Run EdgeX + +1. In the root edgex-compose/compose-builder directory, run `make build` with the list of services you want to run. +2. In the edgex-compose directory, run `make run`, and the rest has already been resolved for you. + +!!! Note + By default Vault has been configured to run in a rootless environment. + The compose entries for Vault's memory limits are automatically resolved for the host system when + you run `make build` in the `compose-builder` directory and written statically to the generated compose files. + The compose entries for the docker socket volume mappings are automatically resolved for the + host system when you add the `portainer` or `delayed-start` args to the `make run` command in the root edgex-compose directory. + + +