From 8e8f0fa59a884c7dc7c54d0711861e479981ed1a Mon Sep 17 00:00:00 2001
From: Niklas Hambüchen
Date: Tue, 19 Sep 2017 20:39:00 +0200
Subject: unshare: Add --kill-child option.

This allows to conveniently kill the entire process tree
below the forked program, a common problem when scripting
tasks that need to reliably fully terminate without leaving
reparented subprocesses behind.

The example added to the man page shows the most common use.

Implemented using prctl(PR_SET_PDEATHSIG, ...).
---
 sys-utils/unshare.1 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'sys-utils/unshare.1')

diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index 79ab96a1b..420b48b73 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -138,6 +138,12 @@ by bind mount.
 Fork the specified \fIprogram\fR as a child process of \fBunshare\fR rather than
 running it directly.  This is useful when creating a new PID namespace.
 .TP
+.BR \-\-kill\-child
+When \fBunshare\fR terminates, have \fBSIGKILL\fR be sent to the forked child process.
+Combined with \fB--pid\fR this allows for an easy and realiable killing of the entire
+process tree below \fBunshare\fR.
+This option implies \fB--fork\fR.
+.TP
 .BR \-\-mount\-proc [ =\fImountpoint ]
 Just before running the program, mount the proc filesystem at \fImountpoint\fP
 (default is /proc).  This is useful when creating a new PID namespace.  It also
@@ -229,6 +235,17 @@ the bind reference.
 Establish a persistent mount namespace referenced by the bind mount
 /root/namespaces/mnt.  This example shows a portable solution, because it
 makes sure that the bind mount is created on a shared filesystem.
+.TP
+.B # unshare -pf --kill-child -- bash -c "(sleep 999 &) && sleep 1000" &
+.TQ
+.B # pid=$!
+.TQ
+.B # kill $pid
+.br
+Reliable killing of subprocesses of the \fIprogram\fR.
+When \fBunshare\fR gets killed, everything below it gets killed as well.
+Without it, the children of \fIprogram\fR would have orphaned and
+been re-parented to PID 1.
 
 .SH SEE ALSO
 .BR clone (2),
-- 
cgit v1.2.3-55-g7522