tools: improve explanation of 'wrap' options

We support 'wrap' variables in /etc/frr/daemons, but the explanation
given there doesn't touch on some of the subtleties of using these
variables.

The variables were designed for use with Valgrind, which has special
behavior when run with programs that daemonize; Valgrind will intercept
the fork()'d child process and run itself instead of the child. This
behavior allows it to follow the same forking semantics as the target
program.

For virtually every other wrapper, the wrap variables do not work as
demonstrated because the wrapper programs do not daemonize. If the
wrappers do not daemonize, they will block the init script. The examples
given with "perf" for example simply do not work, because perf remains
in the foreground even as it tracks forked children.

This patch adds an explanation of the behavior expected by the init
script and offers a solution for getting that behavior.

Signed-off-by: Quentin Young <qlyoung@nvidia.com>

diff --git a/tools/etc/frr/daemons b/tools/etc/frr/daemons
index b1526888ed813f2cac0e354e24df507edd1ac266..a27976c13783fcd925c54321fe7f8a7f81c88cf7 100644 (file)
--- a/tools/etc/frr/daemons
+++ b/tools/etc/frr/daemons
@@ -79,9 +79,29 @@ pathd_options="  -A 127.0.0.1"
 # This only has an effect in /etc/frr/<somename>/daemons, and you need to
 # start FRR with "/usr/lib/frr/frrinit.sh start <somename>".
 
-# for debugging purposes, you can specify a "wrap" command to start instead
-# of starting the daemon directly, e.g. to use valgrind on ospfd:
-#   ospfd_wrap="/usr/bin/valgrind"
-# or you can use "all_wrap" for all daemons, e.g. to use perf record:
-#   all_wrap="/usr/bin/perf record --call-graph -"
-# the normal daemon command is added to this at the end.
+# For any daemon, you can specify a "wrap" command to start instead of starting
+# the daemon directly. This will simply be prepended to the daemon invocation.
+# These variables have the form daemon_wrap, where 'daemon' is the name of the
+# daemon (the same pattern as the daemon_options variables).
+#
+# Note that when daemons are started, they are told to daemonize with the `-d`
+# option. This has several implications. For one, the init script expects that
+# when it invokes a daemon, the invocation returns immediately. If you add a
+# wrap command here, it must comply with this expectation and daemonize as
+# well, or the init script will never return. Furthermore, because daemons are
+# themselves daemonized with -d, you must ensure that your wrapper command is
+# capable of following child processes after a fork() if you need it to do so.
+#
+# If your desired wrapper does not support daemonization, you can wrap it with
+# a utility program that daemonizes programs, such as 'daemonize'. An example
+# of this might look like:
+#
+# bgpd_wrap="/usr/bin/daemonize /usr/bin/mywrapper"
+#
+# This is particularly useful for programs which record processes but lack
+# daemonization options, such as perf and rr.
+#
+# If you wish to wrap all daemons in the same way, you may set the "all_wrap"
+# variable.
+#
+#all_wrap=""