Configuring Containers on Independent Nodes to Read-Only

Scenarios

For containers deployed on independent nodes (single-node containers), HSS does not configure them to read-only. To further improve the container web tamper protection, you can configure your containers to read-only mode by following instructions in this topic.

Notes and Constraints

This topic is applicable to Docker and containerd containers. For other runtime containers, refer to the corresponding official documents.

Configuring a Docker File System to Read-Only

In Docker, you can configure the container file system to read-only in the following ways:

• Single-container scenario: Configure the root file system to read-only using the --read-only parameter in the docker run command.
• Multi-container scenario: Configure the container file systems to read-only using Docker Compose.

Precautions

• Temporary write check: Check whether your application needs to write data in read-only mode. If your application needs to write temporary files, logs, or other data, you can mount writable directories into the container using --tmpfs or -v.
• Modification disallowed in read-only file systems: If your application attempts to create files or directories in a read-only file system, the error message "Read-only file system" is displayed.
• Special paths: Directories managed by the Linux kernel, such as /proc, /sys, and /dev, are not affected by the --read-only parameter. So you need to configure read-only mode for these directories separately. You can mount additional read-only directories, for example, /proc/sys or /dev/shm.

Procedure

• Configuring the root file system to read-only using the --read-only parameter of the docker run command
  1. Configure the basic read-only mode.

     Use the --read-only parameter to start the container and make its root file system read-only. The command is as follows:

     docker run --read-only -d --name my-readonly-container nginx:alpine

  2. Use --tmpfs to allow temporary writes.

     Many applications need to create temporary files in directories such as /tmp and /run. You can use the --tmpfs parameter to mount writable directories. The command is as follows:

     docker run --read-only \
     --tmpfs /tmp \
     --tmpfs /run \
     -d --name nginx-tmpfs nginx:alpine

  3. Use -v to mount writable volumes and allow writes to specific paths.

     If an application needs to write to specific directories, such as log and data directories, you mount them as writable volumes or bind mounts. The command is as follows:

     • Using a named volume to mount the log directory

     docker volume create nginx-logs
     docker run --read-only \
     --tmpfs /tmp \
     --tmpfs /var/lib/nginx/tmp \
     -v nginx-logs:/var/log/nginx \
     -d --name nginx-with-logs nginx:alpine

     • Using bind mounts to mount directories to host machine directories

     mkdir -p /host/path/nginx/logs
     docker run --read-only \
     --tmpfs /tmp \
     -v /host/path/nginx/logs:/var/log/nginx \
     -d --name nginx-bind-logs nginx:alpine

  For details, see Docker Configuration Example: Running a Read-only Nginx Container.

• Configuring a read-only file system using Docker Compose

  In the docker-compose.yml file, refer to the following to configure a read-only file system and tmpfs:

   ```yaml
      version: '3.8'
      services:
        my-app:
          image: nginx:alpine
          read_only: true
          tmpfs:
            - /tmp
            - /run
          volumes:
            - nginx-logs:/var/log/nginx
      volumes:
        nginx-logs:
      ```

Configuring a containerd File System to Read-Only

In containerd, you can configure a read-only root file system using client tools, such as ctr and nerdctl.

Constraints

The parameters for configuring a read-only file system may vary depending on the containerd and ctr versions. The parameters are subject to the actual environment.

Procedure

• Using ctr to configure a read-only file system

  When running a container through ctr, you can use the --rootfs-readonly parameter to configure the root file system to read-only. The command is as follows:

  # Pull the image to the local host.
  ctr images pull docker.io/library/nginx:alpine
  # Run the container using the --rootfs-readonly parameter.
  ctr run --rm \
  --read-only \ # This parameter is used to configure the root file system to read-only.
  --mount type=tmpfs,destination=/tmp,tmpfs-size=16777216 \
    docker.io/library/nginx:alpine \
    nginx-readonly

  

  The parameters and functions of the ctr command may vary depending on the version. Check your containerd version to determine whether to use --read-only or --rootfs-readonly. If necessary, refer to the official documentation.

• Using nerdctl to configure a read-only file system

  nerdctl is a containerd client compatible with Docker CLI. You can use nerdctl to start a read-only container. The syntax is similar to that of Docker. The command is as follows:

  nerdctl run --read-only \
  --tmpfs /tmp \
  -d --name nginx-nerdctl nginx:alpine

  For details, see containerd Configuration Example: Running a Read-only Container Using nerdctl.

Docker Configuration Example: Running a Read-only Nginx Container

The following example shows how to run a read-only Nginx container using --read-only and configure the directories that Nginx needs to write:

# Create a volume for storing Nginx logs and temporary files.
docker volume create nginx-logs
docker volume create nginx-cache
# Start a read-only Nginx container.
docker run -d \
  --name nginx-readonly \
  --read-only \
  --tmpfs /tmp \
  --tmpfs /var/cache/nginx:mode=755,uid=101,gid=101 \  # The UID of the Nginx user is usually 101.
  -v nginx-logs:/var/log/nginx \
  -v nginx-cache:/var/cache/nginx \
  -p 80:80 \
  nginx:alpine
# Check container logs to confirm that Nginx is started properly.
docker logs nginx-readonly

containerd Configuration Example: Running a Read-only Container Using nerdctl

The following example shows how to run a read-only Nginx container using nerdctl:

# Pull the image.
nerdctl pull nginx:alpine
# Run the read-only container and mount tmpfs and volumes.
nerdctl run -d \
  --name nginx-readonly-nerdctl \
  --read-only \
  --tmpfs /tmp \
  --tmpfs /run \
  --mount type=volume,source=nginx-logs,destination=/var/log/nginx \
  -p 8080:80 \
  nginx:alpine
# Check the container status.
nerdctl ps