refactor(docker): allow r/w access in mounted volumes (#9281)

* Switch to a non-privileged user in tests * Change test env setup * Remove unneeded ARGs * Simplify UID & GID handling in `runtime` target * Simplify docs * refactor(docker): Improve user and permission handling in Dockerfiles - Add gosu for flexible non-root user execution - Enhance user and group creation with configurable UID/GID - Modify entrypoint script to support dynamic user switching - Improve cache and log directory permission management - Update comments to clarify user and permission strategies * refactor(docker): Improve Zebra config file handling in entrypoint script - Enhance error handling for missing config file (now exits with error) - Simplify config preparation logic by removing redundant file copying - Update comments to reflect new config file handling approach - Ensure consistent use of ZEBRA_CONF_PATH throughout the script * refactor(docker): Enhance container user security and configuration - Increase UID/GID to 10001 to minimize host system user conflicts - Remove `--system` flag from user and group creation to prevent potential issues - Add detailed comments explaining UID/GID selection rationale - Improve security by using high UID/GID values to reduce namespace collision risks - Remove redundant `chmod` for entrypoint script Co-authored-by: Marek <mail@marek.onl> --------- Co-authored-by: Gustavo Valverde <g.valverde02@gmail.com> Co-authored-by: Gustavo Valverde <gustavo@iterativo.do>
2025-03-03 19:21:03 +01:00 · 2025-03-03 19:21:03 +01:00 · de7e5b547f
parent 797ba62977
commit de7e5b547f
3 changed files with 130 additions and 86 deletions
--- a/book/src/user/docker.md
+++ b/book/src/user/docker.md
@ -21,7 +21,7 @@ And mount it before you start the container:

 ```shell
 docker run \
-  --mount type=volume,source=zebrad-cache,target=/home/zebra/.cache/zebra \
+  --mount source=zebrad-cache,target=/home/zebra/.cache/zebra \
  --name zebra \
  zfnd/zebra
 ```
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@ -1,5 +1,5 @@
 # syntax=docker/dockerfile:1
-# check=skip=UndefinedVar
+# check=skip=UndefinedVar,UserExist # We use gosu in the entrypoint instead of USER directive

 # If you want to include a file in the Docker image, add it to .dockerignore.
 #
@ -13,8 +13,18 @@
 # We first set default values for build arguments used across the stages.
 # Each stage must define the build arguments (ARGs) it uses.

-ARG RUST_VERSION=1.85.0
+# Build zebrad with these features
+#
+# Keep these argument defaults in sync with GitHub vars.RUST_PROD_FEATURES
+# https://github.com/ZcashFoundation/zebra/settings/variables/actions
+ARG FEATURES="default-release-binaries"

+ARG USER="zebra"
+ARG UID=10001
+ARG GID=10001
+ARG HOME="/home/${USER}"
+
+ARG RUST_VERSION=1.85.0
 # In this stage we download all system requirements to build the project
 #
 # It also captures all the build arguments to be used as environment variables.
@ -47,6 +57,14 @@ ARG SHORT_SHA
 # https://github.com/ZcashFoundation/zebra/blob/9ebd56092bcdfc1a09062e15a0574c94af37f389/zebrad/src/application.rs#L179-L182
 ENV SHORT_SHA=${SHORT_SHA:-}

+# Set the working directory for the build.
+ARG HOME
+WORKDIR ${HOME}
+ENV HOME=${HOME}
+ENV CARGO_HOME="${HOME}/.cargo/"
+
+ENV USER=${USER}
+
 # This stage builds tests without running them.
 #
 # We also download needed dependencies for tests to work, from other images.
@ -60,19 +78,17 @@ ENV FEATURES=${FEATURES}
 ARG ZEBRA_SKIP_IPV6_TESTS
 ENV ZEBRA_SKIP_IPV6_TESTS=${ZEBRA_SKIP_IPV6_TESTS:-1}

-# Set up the test environment the same way the production environment is. This
-# is not very DRY as the same code repeats for the `runtime` target below, but I
-# didn't find a suitable way to share the setup between the two targets.
+# This environment setup is almost identical to the `runtime` target so that the
+# `tests` target differs minimally. In fact, a subset of this setup is used for
+# the `runtime` target.

-ENV UID=101
-ENV GID=${UID}
-ENV USER="zebra"
-ENV HOME="/home/${USER}"
-ENV CARGO_HOME="${HOME}/.cargo/"
+ARG UID
+ARG GID
+ARG HOME
+ARG USER

-RUN adduser --system --gid ${GID} --uid ${UID} --home ${HOME} ${USER}
-
-WORKDIR ${HOME}
+RUN addgroup --gid ${GID} ${USER} && \
+    adduser --gid ${GID} --uid ${UID} --home ${HOME} ${USER}

 # Build Zebra test binaries, but don't run them

@ -110,25 +126,27 @@ RUN --mount=type=bind,source=zebrad,target=zebrad \
 # Copy the lightwalletd binary and source files to be able to run tests
 COPY --from=electriccoinco/lightwalletd:latest /usr/local/bin/lightwalletd /usr/local/bin/

+# Copy the gosu binary to be able to run the entrypoint as non-root user
+# and allow to change permissions for mounted cache directories
+COPY --from=tianon/gosu:bookworm /gosu /usr/local/bin/
+
 # Use the same default config as in the production environment.
 ENV ZEBRA_CONF_PATH="${HOME}/.config/zebrad.toml"
 COPY --chown=${UID}:${GID} ./docker/default-zebra-config.toml ${ZEBRA_CONF_PATH}

-ARG LWD_CACHE_DIR
 ENV LWD_CACHE_DIR="${HOME}/.cache/lwd"
-RUN mkdir -p ${LWD_CACHE_DIR}
-RUN chown -R ${UID}:${GID} ${LWD_CACHE_DIR}
+RUN mkdir -p ${LWD_CACHE_DIR} && \
+    chown -R ${UID}:${GID} ${LWD_CACHE_DIR}

 # Use the same cache dir as in the production environment.
-ARG ZEBRA_CACHE_DIR
 ENV ZEBRA_CACHE_DIR="${HOME}/.cache/zebra"
-RUN mkdir -p ${ZEBRA_CACHE_DIR}
-RUN chown -R ${UID}:${GID} ${ZEBRA_CACHE_DIR}
+RUN mkdir -p ${ZEBRA_CACHE_DIR} && \
+    chown -R ${UID}:${GID} ${ZEBRA_CACHE_DIR}
+
+COPY ./ ${HOME}
+RUN chown -R ${UID}:${GID} ${HOME}

 COPY ./docker/entrypoint.sh /usr/local/bin/entrypoint.sh
-COPY ./ ${HOME}
-
-RUN chown -R ${UID}:${GID} ${HOME}

 ENTRYPOINT [ "entrypoint.sh", "test" ]

@ -140,6 +158,7 @@ ENTRYPOINT [ "entrypoint.sh", "test" ]
 FROM deps AS release

 ARG FEATURES
+ARG HOME

 RUN --mount=type=bind,source=tower-batch-control,target=tower-batch-control \
    --mount=type=bind,source=tower-fallback,target=tower-fallback \
@ -157,47 +176,46 @@ RUN --mount=type=bind,source=tower-batch-control,target=tower-batch-control \
    --mount=type=bind,source=zebrad,target=zebrad \
    --mount=type=bind,source=Cargo.toml,target=Cargo.toml \
    --mount=type=bind,source=Cargo.lock,target=Cargo.lock \
-    --mount=type=cache,target=${APP_HOME}/target/ \
+    --mount=type=cache,target=${HOME}/target/ \
    --mount=type=cache,target=/usr/local/cargo/git/db \
    --mount=type=cache,target=/usr/local/cargo/registry/ \
    cargo build --locked --release --features "${FEATURES}" --package zebrad --bin zebrad && \
-    cp ${APP_HOME}/target/release/zebrad /usr/local/bin
+    cp ${HOME}/target/release/zebrad /usr/local/bin

 # This step starts from scratch using Debian and only adds the resulting binary
 # from the `release` stage.
 FROM debian:bookworm-slim AS runtime

-COPY --from=release /usr/local/bin/zebrad /usr/local/bin/
-COPY ./docker/entrypoint.sh /usr/local/bin/entrypoint.sh
-
 ARG FEATURES
 ENV FEATURES=${FEATURES}

 # Create a non-privileged system user for running `zebrad`.
-ARG USER="zebra"
+ARG USER
 ENV USER=${USER}

 # System users have no home dirs, but we set one for users' convenience.
-ARG HOME="/home/zebra"
+ARG HOME
 WORKDIR ${HOME}

-# System UIDs should be set according to
-# https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/uidrange.html.
+# We use a high UID/GID (10001) to avoid overlap with host system users.
+# This reduces the risk of container user namespace conflicts with host accounts,
+# which could potentially lead to privilege escalation if a container escape occurs.
 #
-# In Debian, the default dynamic range for system UIDs is defined by
-# [FIRST_SYSTEM_UID, LAST_SYSTEM_UID], which is set to [100, 999] in
-# `etc/adduser.conf`:
-# https://manpages.debian.org/bullseye/adduser/adduser.8.en.html
+# We do not use the `--system` flag for user creation since:
+# 1. System user ranges (100-999) can collide with host system users
+#   (see: https://github.com/nginxinc/docker-nginx/issues/490)
+# 2. There's no value added and warning messages can be raised at build time
+#   (see: https://github.com/dotnet/dotnet-docker/issues/4624)
 #
-# Debian assigns GID 100 to group `users`, so we set UID = GID = 101 as the
-# default value.
-ARG UID=101
+# The high UID/GID values provide an additional security boundary in containers
+# where user namespaces are shared with the host.
+ARG UID
 ENV UID=${UID}
-ARG GID=${UID}
+ARG GID
 ENV GID=${GID}

-RUN addgroup --system --gid ${GID} ${USER}
-RUN adduser --system --gid ${GID} --uid ${UID} --home ${HOME} ${USER}
+RUN addgroup --gid ${GID} ${USER} && \
+    adduser --gid ${GID} --uid ${UID} --home ${HOME} ${USER}

 # We set the default locations of the conf and cache dirs according to the XDG
 # spec: https://specifications.freedesktop.org/basedir-spec/latest/
@ -211,7 +229,18 @@ ENV ZEBRA_CACHE_DIR=${ZEBRA_CACHE_DIR}
 RUN mkdir -p ${ZEBRA_CACHE_DIR} && chown -R ${UID}:${GID} ${ZEBRA_CACHE_DIR}

 RUN chown -R ${UID}:${GID} ${HOME}
-USER $USER
+
+# We're explicitly NOT using the USER directive here.
+# Instead, we run as root initially and use gosu in the entrypoint.sh
+# to step down to the non-privileged user. This allows us to change permissions
+# on mounted volumes before running the application as a non-root user.
+# User with UID=${UID} is created above and used via gosu in entrypoint.sh.
+
+# Copy the gosu binary to be able to run the entrypoint as non-root user
+COPY --from=tianon/gosu:bookworm /gosu /usr/local/bin/
+
+COPY --from=release /usr/local/bin/zebrad /usr/local/bin/
+COPY ./docker/entrypoint.sh /usr/local/bin/entrypoint.sh

 ENTRYPOINT [ "entrypoint.sh" ]
 CMD ["zebrad"]
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@ -12,36 +12,42 @@ set -eo pipefail

 # Exit early if `ZEBRA_CONF_PATH` does not point to a file.
 if [[ ! -f "${ZEBRA_CONF_PATH}" ]]; then
-  echo "the ZEBRA_CONF_PATH env var does not point to a Zebra conf file"
+  echo "ERROR: No Zebra config file found at ZEBRA_CONF_PATH (${ZEBRA_CONF_PATH})."
+  echo "Please ensure the file exists or mount your custom config file and set ZEBRA_CONF_PATH accordingly."
  exit 1
 fi

-# Generates a config file for Zebra using env vars set in "docker/.env" and
-# prints the location of the generated config file.
+# Define function to execute commands as the specified user
+exec_as_user() {
+  if [[ "$(id -u)" = '0' ]]; then
+    exec gosu "${USER}" "$@"
+  else
+    exec "$@"
+  fi
+}
+
+# Modifies the existing Zebra config file at ZEBRA_CONF_PATH using environment variables.
 #
-# ## Positional Parameters
+# The config options this function supports are also listed in the "docker/.env" file.
 #
-# - "$1": the file to read the default config from
+# This function modifies the existing file in-place and prints its location.
 prepare_conf_file() {
-  # Copy the default config to a new location for writing.
-  CONF=~/zebrad.toml
-  cp "${1}" "${CONF}"

  # Set a custom network.
-  if [[ "${NETWORK}" ]]; then
-    sed -i '/network = ".*"/s/".*"/"'"${NETWORK//\"/}"'"/' "${CONF}"
+  if [[ -n "${NETWORK}" ]]; then
+    sed -i '/network = ".*"/s/".*"/"'"${NETWORK//\"/}"'"/' "${ZEBRA_CONF_PATH}"
  fi

  # Enable the RPC server by setting its port.
-  if [[ "${ZEBRA_RPC_PORT}" ]]; then
-    sed -i '/# listen_addr = "0.0.0.0:18232" # Testnet/d' "${CONF}"
-    sed -i 's/ *# Mainnet$//' "${CONF}"
-    sed -i '/# listen_addr = "0.0.0.0:8232"/s/^# //; s/8232/'"${ZEBRA_RPC_PORT//\"/}"'/' "${CONF}"
+  if [[ -n "${ZEBRA_RPC_PORT}" ]]; then
+    sed -i '/# listen_addr = "0.0.0.0:18232" # Testnet/d' "${ZEBRA_CONF_PATH}"
+    sed -i 's/ *# Mainnet$//' "${ZEBRA_CONF_PATH}"
+    sed -i '/# listen_addr = "0.0.0.0:8232"/s/^# //; s/8232/'"${ZEBRA_RPC_PORT//\"/}"'/' "${ZEBRA_CONF_PATH}"
  fi

  # Disable or enable cookie authentication.
-  if [[ "${ENABLE_COOKIE_AUTH}" ]]; then
-    sed -i '/# enable_cookie_auth = true/s/^# //; s/true/'"${ENABLE_COOKIE_AUTH//\"/}"'/' "${CONF}"
+  if [[ -n "${ENABLE_COOKIE_AUTH}" ]]; then
+    sed -i '/# enable_cookie_auth = true/s/^# //; s/true/'"${ENABLE_COOKIE_AUTH//\"/}"'/' "${ZEBRA_CONF_PATH}"
  fi

  # Set a custom state, network and cookie cache dirs.
@ -49,42 +55,52 @@ prepare_conf_file() {
  # We're pointing all three cache dirs at the same location, so users will find
  # all cached data in that single location. We can introduce more env vars and
  # use them to set the cache dirs separately if needed.
-  if [[ "${ZEBRA_CACHE_DIR}" ]]; then
+  if [[ -n "${ZEBRA_CACHE_DIR}" ]]; then
    mkdir -p "${ZEBRA_CACHE_DIR//\"/}"
-    sed -i 's|_dir = ".*"|_dir = "'"${ZEBRA_CACHE_DIR//\"/}"'"|' "${CONF}"
+    sed -i 's|_dir = ".*"|_dir = "'"${ZEBRA_CACHE_DIR//\"/}"'"|' "${ZEBRA_CONF_PATH}"
+    # Fix permissions right after creating/configuring the directory
+    if [[ "$(id -u)" = '0' ]]; then
+      # "Setting permissions for the cache directory
+      chown -R "${USER}:${USER}" "${ZEBRA_CACHE_DIR//\"/}"
+    fi
  fi

  # Enable the Prometheus metrics endpoint.
  if [[ "${FEATURES}" == *"prometheus"* ]]; then
-    sed -i '/# endpoint_addr = "0.0.0.0:9999" # Prometheus/s/^# //' "${CONF}"
+    sed -i '/# endpoint_addr = "0.0.0.0:9999" # Prometheus/s/^# //' "${ZEBRA_CONF_PATH}"
  fi

  # Enable logging to a file by setting a custom log file path.
-  if [[ "${LOG_FILE}" ]]; then
+  if [[ -n "${LOG_FILE}" ]]; then
    mkdir -p "$(dirname "${LOG_FILE//\"/}")"
-    sed -i 's|# log_file = ".*"|log_file = "'"${LOG_FILE//\"/}"'"|' "${CONF}"
+    sed -i 's|# log_file = ".*"|log_file = "'"${LOG_FILE//\"/}"'"|' "${ZEBRA_CONF_PATH}"
+    # Fix permissions right after creating/configuring the log directory
+    if [[ "$(id -u)" = '0' ]]; then
+      # "Setting permissions for the log directory
+      chown -R "${USER}:${USER}" "$(dirname "${LOG_FILE//\"/}")"
+    fi
  fi

  # Enable or disable colored logs.
-  if [[ "${LOG_COLOR}" ]]; then
-    sed -i '/# force_use_color = true/s/^# //' "${CONF}"
-    sed -i '/use_color = true/s/true/'"${LOG_COLOR//\"/}"'/' "${CONF}"
+  if [[ -n "${LOG_COLOR}" ]]; then
+    sed -i '/# force_use_color = true/s/^# //' "${ZEBRA_CONF_PATH}"
+    sed -i '/use_color = true/s/true/'"${LOG_COLOR//\"/}"'/' "${ZEBRA_CONF_PATH}"
  fi

  # Enable or disable logging to systemd-journald.
-  if [[ "${USE_JOURNALD}" ]]; then
-    sed -i '/# use_journald = true/s/^# //; s/true/'"${USE_JOURNALD//\"/}"'/' "${CONF}"
+  if [[ -n "${USE_JOURNALD}" ]]; then
+    sed -i '/# use_journald = true/s/^# //; s/true/'"${USE_JOURNALD//\"/}"'/' "${ZEBRA_CONF_PATH}"
  fi

  # Set a mining address.
-  if [[ "${MINER_ADDRESS}" ]]; then
-    sed -i '/# miner_address = ".*"/{s/^# //; s/".*"/"'"${MINER_ADDRESS//\"/}"'"/}' "${CONF}"
+  if [[ -n "${MINER_ADDRESS}" ]]; then
+    sed -i '/# miner_address = ".*"/{s/^# //; s/".*"/"'"${MINER_ADDRESS//\"/}"'"/}' "${ZEBRA_CONF_PATH}"
  fi

  # Trim all comments and empty lines.
-  sed -i '/^#/d; /^$/d' "${CONF}"
+  sed -i '/^#/d; /^$/d' "${ZEBRA_CONF_PATH}"

-  echo "${CONF}"
+  echo "${ZEBRA_CONF_PATH}"
 }

 # Checks if a directory contains subdirectories
@ -116,11 +132,11 @@ check_directory_files() {
 #     https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options,
 #   - or be empty.
 # - The remaining params will be appended to a command starting with
-#   `exec cargo test ... -- ...`
+#   `exec_as_user cargo test ... -- ...`
 run_cargo_test() {
  # Start constructing the command, ensuring that $1 is enclosed in single
  # quotes as it's a feature list
-  local cmd="exec cargo test --locked --release --features '$1' --package zebrad --test acceptance -- --nocapture --include-ignored"
+  local cmd="exec_as_user cargo test --locked --release --features '$1' --package zebrad --test acceptance -- --nocapture --include-ignored"

  # Shift the first argument, as it's already included in the cmd
  shift
@ -153,23 +169,23 @@ run_tests() {
    # Run unit, basic acceptance tests, and ignored tests, only showing command
    # output if the test fails. If the lightwalletd environment variables are
    # set, we will also run those tests.
-    exec cargo test --locked --release --workspace --features "${FEATURES}" \
+    exec_as_user cargo test --locked --release --workspace --features "${FEATURES}" \
      -- --nocapture --include-ignored --skip check_no_git_refs_in_cargo_lock

  elif [[ "${RUN_CHECK_NO_GIT_REFS}" -eq "1" ]]; then
    # Run the check_no_git_refs_in_cargo_lock test.
-    exec cargo test --locked --release --workspace --features "${FEATURES}" \
+    exec_as_user cargo test --locked --release --workspace --features "${FEATURES}" \
      -- --nocapture --include-ignored check_no_git_refs_in_cargo_lock

  elif [[ "${TEST_FAKE_ACTIVATION_HEIGHTS}" -eq "1" ]]; then
    # Run state tests with fake activation heights.
-    exec cargo test --locked --release --lib --features "zebra-test" \
+    exec_as_user cargo test --locked --release --lib --features "zebra-test" \
      --package zebra-state \
      -- --nocapture --include-ignored with_fake_activation_heights

  elif [[ "${TEST_SCANNER}" -eq "1" ]]; then
    # Test the scanner.
-    exec cargo test --locked --release --package zebra-scan \
+    exec_as_user cargo test --locked --release --package zebra-scan \
      -- --nocapture --include-ignored scan_task_commands scan_start_where_left

  elif [[ "${TEST_ZEBRA_EMPTY_SYNC}" -eq "1" ]]; then
@ -257,16 +273,15 @@ run_tests() {
    run_cargo_test "${FEATURES}" "submit_block"

  else
-    exec "$@"
+    exec_as_user "$@"
  fi
 }

 # Main Script Logic

+prepare_conf_file "${ZEBRA_CONF_PATH}"
 echo "Prepared the following Zebra config:"
-
-CONF_PATH=$(prepare_conf_file "${ZEBRA_CONF_PATH}")
-cat "${CONF_PATH}"
+cat "${ZEBRA_CONF_PATH}"

 # - If "$1" is "--", "-", or "zebrad", run `zebrad` with the remaining params.
 # - If "$1" is "tests":
@ -277,13 +292,13 @@ cat "${CONF_PATH}"
 case "$1" in
 --* | -* | zebrad)
  shift
-  exec zebrad --config "${CONF_PATH}" "$@"
+  exec_as_user zebrad --config "${ZEBRA_CONF_PATH}" "$@"
  ;;
 test)
  shift
  if [[ "$1" == "zebrad" ]]; then
    shift
-    exec zebrad --config "${CONF_PATH}" "$@"
+    exec_as_user zebrad --config "${ZEBRA_CONF_PATH}" "$@"
  else
    run_tests "$@"
  fi
@ -293,6 +308,6 @@ monitoring)
  :
  ;;
 *)
-  exec "$@"
+  exec_as_user "$@"
  ;;
 esac