From 37b5c372f39492b98784fd89c730270adffa40d2 Mon Sep 17 00:00:00 2001
From: Ariadne Conill <ariadne@dereferenced.org>
Date: Wed, 29 Jul 2020 02:09:28 -0600
Subject: [PATCH] doc: add ifupdown-executor(7) manpage (closes #9)

---
 Makefile                  |  5 ++-
 doc/ifupdown-executor.scd | 84 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+), 1 deletion(-)
 create mode 100644 doc/ifupdown-executor.scd

diff --git a/Makefile b/Makefile
index ccd016e..d4eab62 100644
--- a/Makefile
+++ b/Makefile
@@ -102,7 +102,10 @@ MANPAGES_8 = \
 MANPAGES_5 = \
 	doc/interfaces.5
 
-MANPAGES = ${MANPAGES_5} ${MANPAGES_8}
+MANPAGES_7 = \
+	doc/ifupdown-executor.7
+
+MANPAGES = ${MANPAGES_5} ${MANPAGES_7} ${MANPAGES_8}
 
 docs: ${MANPAGES}
 
diff --git a/doc/ifupdown-executor.scd b/doc/ifupdown-executor.scd
new file mode 100644
index 0000000..2064b4b
--- /dev/null
+++ b/doc/ifupdown-executor.scd
@@ -0,0 +1,84 @@
+ifupdown-executor(7)
+
+# NAME
+
+*/usr/libexec/ifupdown-ng/program* - ifupdown executor protocol
+
+# DESCRIPTION
+
+The ifupdown executors are programs that are typically installed
+into the ifupdown-ng executor path.  They follow a specific
+protocol documented in this man page.
+
+# PHASES
+
+Executors are run to react to seven different phases and are not
+required to take any specific action.  These phases are:
+
+*depend*
+	Called to determine if the executor wishes to change
+	the dependency graph.  The executor should write a
+	space-delimited list of interface names it is dependent
+	upon to _stdout_.  Those interface names will be merged
+	into the dependency graph.  If an executor does not have
+	any dependencies, it may simply exit 0 without doing
+	anything.
+
+*pre-up*
+	Called before the interface is going to be brought up.
+
+*up*
+	Called when the interface is being brought up.
+
+*post-up*
+	Called after the interface was successfully brought up.
+
+*pre-down*
+	Called before the interface is going to be taken down.
+
+*down*
+	Called when the interface is being taken down.
+
+*post-down*
+	Called after the interface was successfully taken down.
+
+# ENVIRONMENT
+
+Executors are guaranteed to run with a core set of environment
+variables:
+
+*IFACE*
+	The name of the interface being configured.
+
+*INTERFACES_FILE*
+	The path to the interfaces database file being used.
+
+*MODE*
+	Either _start_, _stop_ or _depend_ depending on phase.
+	This environment variable is present for compatibility
+	with legacy ifupdown scripts and should not be used in
+	ifupdown-ng executors.
+
+*PHASE*
+	The phase being executed.  See the phases section for
+	more information about phases.
+
+*VERBOSE*
+	If present, verbose output is expected from the
+	executor.
+
+Additionally, the properties associated with an interface are
+provided to executors.  The keys are rewritten to begin with
+IF_ and are capitalized with dashes converted to underscores.
+For example, the property _bridge-ports_ will be rewritten as
+_IF_BRIDGE_PORTS_.
+
+# SEE ALSO
+
+ifup(8)++
+ifdown(8)++
+interfaces(5)
+
+# AUTHORS
+
+Ariadne Conill <ariadne@dereferenced.org>