From dc3cd787870e10c7c94d47322e44fb5f58adacfa Mon Sep 17 00:00:00 2001
From: "Zak B. Elep" <zakame@zakame.net>
Date: Sat, 10 Aug 2019 11:59:48 +0800
Subject: [PATCH] perl: Document PID 1 signal handling behavior

Describe how Perl behaves when being run as PID 1 under containers,
particularly on receiving SIGTERM/SIGINT, showing example for explicit
signal handling.

Ref Perl/docker-perl#44
---
 perl/content.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/perl/content.md b/perl/content.md
index 35b1c95fe4e49..9b9c3d5fd1ed3 100644
--- a/perl/content.md
+++ b/perl/content.md
@@ -32,6 +32,32 @@ For many simple, single file projects, you may find it inconvenient to write a c
 $ docker run -it --rm --name my-running-script -v "$PWD":/usr/src/myapp -w /usr/src/myapp %%IMAGE%%:5.20 perl your-daemon-or-script.pl
 ```
 
+## Signal handling behavior notice
+
+As Perl will run as PID 1 by default in containers (unless an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) is set,) special care needs to be considered when expecting to send signals (particularly SIGINT or SIGTERM) to it. For example, running
+
+```console
+$ docker run -it --name sleeping_beauty --rm %%IMAGE%%:5.20 perl -E 'sleep 300'
+```
+
+and doing on another terminal,
+
+```console
+$ docker exec sleeping_beauty kill 1
+```
+
+will *not* stop the perl running on the `sleeping_beauty` container (it will keep running until the `sleep 300` finishes.) To do so, one must set a signal handler like this:
+
+```console
+$ docker run -it --name quick_nap --rm %%IMAGE%%:5.20 perl -E '$SIG{TERM} = sub { say "recv TERM" }; sleep 300'
+```
+
+so doing `docker exec quick_nap kill 1` (or the simpler `docker stop quick_nap`) will immediately stop the container, and print `recv TERM` in the other terminal.
+
+If your Perl program is expected to handle signals and fork child processes, it is encouraged to use an init-like program for ENTRYPOINT, such as [dumb-init](https://github.com/Yelp/dumb-init) or [tini](https://github.com/krallin/tini) (the latter is available since Docker 1.13 via the `docker run --init` flag.)
+
+See also [Signals in perlipc](https://perldoc.pl/perlipc#Signals) as well as [Perl/docker-perl#44](https://github.com/Perl/docker-perl/issues/44).
+
 ## Example: Creating a reusable Carton image for Perl projects
 
 Suppose you have a project that uses [Carton](https://metacpan.org/pod/Carton) to manage Perl dependencies. You can create a `%%IMAGE%%:carton` image that makes use of the [ONBUILD](https://docs.docker.com/engine/reference/builder/#onbuild) instruction in its `Dockerfile`, like this: