src/cmd/cos_dkms_runner/README.md

# cos-dkms for Container-Optimized OS

`cos-dkms` is a tool used in
[Container-Optimized OS](https://cloud.google.com/container-optimized-os/) to
manage, install, and distribute kernel modules.

cos-dkms is based on [Dell DKMS](https://github.com/dell/dkms), and is intended
to largely be a drop-in replacement on COS instances. It additionally supports
uploading/downloading modules to/from a GCS bucket in order to simplify module
distribution. If modules need to be built from source, cos-dkms will
automatically download the correct compiler toolchain and kernel sources for the
running COS instance.

This repository provides a convenient wrapper to download and call the
[cos-dkms container](https://cos.googlesource.com/cos/tools/+/refs/heads/master/src/cmd/cos_dkms/),
which will do the real work of managing modules.

This script will pass `--gcs-bucket=cos-default` to the container. This bucket
will have signed modules compiled by the COS team which can be installed and
loaded for the running COS instance.

The script will mount the following paths into the container:

Name                  | Host path                     | Guest path         | Note
--------------------- | ----------------------------- | ------------------ | ----
`SOURCE_TREE`         | `/var/lib/google/dkms/source` | `/usr/src`         | This is the directory containing user-managed module sources.
`DKMS_TREE`           | `/var/lib/google/dkms/dkms`   | `/var/lib/dkms`    | This is the tree where modules will be added and built.
`KERNEL_TREE`         | `/var/lib/google/dkms/kernel` | `/lib/modules`     | This is the set of directories where kernel modules can be installed after they are built. cos-dkms installs to /var/lib/google/kernel/modules/updates by default.
`KERNEL_MODULES_TREE` | `/lib/modules`                | `/host_modules`    | This maps the host kernel modules to the guest as read-only so that the correct module dependency graph can be constructed when inserting modules into the kernel.
`LSB_RELEASE`         | `/etc/lsb-release`            | `/etc/lsb-release` | This file contains OS information, such as the COS build id and board.

Each of these paths can be overridden by setting the `HOST_*` or `GUEST_*`
variables, e.g., `HOST_SOURCE_TREE=/home/my-source-tree/ GUEST_DKMS_TREE=/dkms
cos-dkms ...`

The following variables can also be overridden to change the behavior of the
wrapper script:

*   `IMAGE_NAME`: The name of the cos-dkms container image to use. Defaults to
    gcr.io/cos-cloud/cos-dkms:latest.
*   `CONTAINER_NAME`: The name to use for the cos-dkms container. Defaults to
    `cos-dkms-<random integer>`.
*   `CONTAINER_NAMESPACE`: The namespace to use for container-related options,
    including the image download. Defaults to `cos-dkms`.
*   `CONTAINERD_SOCK`: The containerd socket file to use when connecting to the
    containerd service. Defaults to `/run/containerd/containerd.sock`.