Hotdog

Hotdog is a set of OCI hooks used to inject the Log4j Hot Patch into containers.

How it works

When runc sets up the container, it invokes hotdog-cc-hook. hotdog-cc-hook bind-mounts the hotpatch files into the container's filesystem at /dev/shm/.hotdog. After the main container process starts, runc invokes hotdog-poststart-hook, which uses nsenter to enter the container's namespaces and fork off a hotdog-hotpatch process. hotdog-hotpatch runs several times with decreasing frequency (currently 1s, 5s, 10s, 30s) to detect and hotpatch JVMs inside the container.

Limitations

Hotdog only provides hotpatching support for Java 8, 11, 15, and 17.
Hotdog only runs for a short time at the beginning of a container's lifetime. If new Java processes are started after the hotdog-hotpatch process exits, they will not be hot patched.
Hotdog only patches processes named "java". If your Java application has a different process name, hotdog will not patch it.
Hotdog works best when the container has its own pid namespace. If hotdog is used with a container that has a shared pid namespace, the hotdog-hotpatch might remain for a short time after the container exits.
Hotdog injects its components into /dev/shm/.hotdog inside the container. If /dev/shm does not exist (such as in the case of Docker containers launched with --ipc=none), hotdog will not be injected into the container and will not provide hotpatching.

Installation

Bottlerocket

Hotdog is included by default in Bottlerocket 1.5.0.

Hotpatching can be enabled for new launches of Bottlerocket by including the following settings in user data.

[settings.oci-hooks]
log4j-hotpatch-enabled = true

For existing hosts running the latest version of Bottlerocket, hotpatching can be enabled using the API client.

apiclient set oci-hooks.log4j-hotpatch-enabled=true

Enabling the setting at runtime has no effect on running containers. Newly-launched containers will be hotpatched.

Other Linux distributions

To install Hotdog, you need to copy the following files to the right location and set the appropriate configuration.

Copy Log4jHotPatch.jar to /usr/share/hotdog (if you build the hotpatch from source, you'll find it in build/libs)
Run make && sudo make install to install hotdog-cc-hook and hotdog-poststart-hook to /usr/libexec/hotdog and hotdog-hotpatch to /usr/share/hotdog
Install oci-add-hooks

Configure oci-add-hooks with the hotdog hooks by writing the following contents to /etc/hotdog/config.json:

{
  "hooks": {
    "prestart": [{
      "path": "/usr/libexec/hotdog/hotdog-cc-hook"
    }],
    "poststart": [{
      "path": "/usr/libexec/hotdog/hotdog-poststart-hook"
    }]
  }
}

Configure Docker to use the hooks by writing the following contents into /etc/docker/daemon.json:

{
  "runtimes": {
    "hotdog": {
      "path": "oci-add-hooks",
      "runtimeArgs": [
        "--hook-config-path", "/etc/hotdog/config.json",
        "--runtime-path", "/usr/sbin/runc"
      ]
    }
  }
}

To run a container with hotpatching enabled, specify docker run --runtime hotdog. To run with hotpatching enabled by default in all containers, add the following contents to /etc/docker/daemon.json:

"default-runtime": "hotdog"

If you wish to opt-out of hotdog even when it is enabled by default, specify --runtime runc.

Troubleshooting

hotdog will add several files to the /dev/shm/.hotdog directory in each container. You can find the log from hotdog-hotpatch in /dev/shm/hotdog.log.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

yffud/hotdog