From a70d6da906aaaf53839b693f10c66a040c58da19 Mon Sep 17 00:00:00 2001
From: Steve Langasek <steve.langasek@canonical.com>
Date: Sun, 9 Jan 2011 19:58:58 -0600
Subject: [PATCH] Document generic and upstart-specific init-system
 requirements

Add a new section on alternative init systems that outlines the
compatibility requirements for both init replacements and packages shipping
upstart jobs.  Closes: #591791
---
 policy.sgml | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/policy.sgml b/policy.sgml
index 73d5d8f..3a2e7e1 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -7866,6 +7866,74 @@ Reloading <var>description</var> configuration...done.
 	</p>
       </sect>
 
+      <sect id="alternateinit">
+        <heading>Alternate init systems</heading>
+        <p>
+          A number of other init systems are available now in Debian that
+          can be used in place of <package>sysvinit</package>.  Alternative
+          init implementations must support running SysV init scripts as
+          described at <ref id="sysvinit"> for compatibility.
+        </p>
+        <p>
+          Packages may integrate with these replacement init systems by
+          providing implementation-specific configuration information about
+          how and when to start a service or in what order to run certain
+          tasks at boot time.  However, any package integrating with other
+          init systems must also be backwards-compatible with
+          <package>sysvinit</package> by providing a SysV-style init script
+          with the same name as and equivalent functionality to any
+          init-specific job, as this is the only start-up configuration
+          method guaranteed to be supported by all init implementations.  An
+          exception to this rule is scripts or jobs provided by the init
+          implementation itself; such jobs may be required for an
+          implementation-specific equivalent of the <file>/etc/rcS.d/</file>
+          scripts and may not have a one-to-one correspondence with the init
+          scripts.
+        </p>
+        <sect1 id="upstart">
+          <heading>Event-based boot with upstart</heading>
+
+	  <p>
+            Packages may integrate with the <prgn>upstart</prgn> event-based
+            boot system by installing job files in the
+            <file>/etc/init</file> directory.  SysV init scripts for which
+            an equivalent upstart job is available must query the output of
+            the command <prgn>initctl version</prgn> for the string
+            <tt>upstart</tt> and avoid running in favor of the native
+            upstart job, using a test such as this:
+	    <example compact="compact">
+if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart
+then
+	exit 1
+fi
+	    </example>
+          </p>
+          <p>
+            Because packages shipping upstart jobs may be installed on
+            systems that are not using upstart, maintainer scripts must
+            still use the common <prgn>update-rc.d</prgn> and
+            <prgn>invoke-rc.d</prgn> interfaces for configuring runlevels
+            and for starting and stopping services.  These maintainer
+            scripts must not call the upstart <prgn>start</prgn>,
+            <prgn>restart</prgn>, <prgn>reload</prgn>, or <prgn>stop</prgn>
+            interfaces directly.  Instead, implementations of
+            <prgn>invoke-rc.d</prgn> must detect when upstart is running and
+            when an upstart job with the same name as an init script is
+            present, and perform the requested action using the upstart job
+            instead of the init script.
+          </p>
+          <p>
+            Dependency-based boot managers for SysV init scripts, such as
+            <prgn>startpar</prgn>, may avoid running a given init script
+            entirely when an equivalent upstart job is present, to avoid
+            unnecessary forking of no-op init scripts.  In this case, the
+            boot manager should integrate with upstart to detect when the
+            upstart job in question is started or stopped to know when the
+            dependency has been satisfied.
+          </p>
+         </sect1>
+      </sect>
+
       <sect id="cron-jobs">
 	<heading>Cron jobs</heading>
 
-- 
2.39.2