add httpd.service(5) and httpd.socket(5) man pages

5 files changed, 198 insertions, 1 deletions

diff --git a/.gitignore b/.gitignore
index c4c6257..62a3130 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,3 +24,5 @@ x86_64
 /httpd-2.4.18.tar.bz2
 /httpd-2.4.23.tar.bz2
 /httpd-2.4.25.tar.bz2
+/httpd.socket.5
+/httpd.service.5
diff --git a/httpd.service b/httpd.service
index 65048d2..5875d9c 100644
--- a/httpd.service
+++ b/httpd.service
@@ -1,3 +1,5 @@
+# See httpd.service(5) for more information on using the httpd service.
+
 # Modifying this file in-place is not recommended, because changes
 # will be overwritten during package upgrades.  If you want to
 # customize the behaviour, the best way is to use "systemctl edit"
diff --git a/httpd.service.xml b/httpd.service.xml
new file mode 100644
index 0000000..9524045
--- /dev/null
+++ b/httpd.service.xml
@@ -0,0 +1,180 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<refentry>
+  <refentryinfo>
+    <title>httpd systemd units</title>
+    <productname>httpd</productname>
+    <author><contrib>Author</contrib><surname>Orton</surname><firstname>Joe</firstname><email>jorton@redhat.com</email></author>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>httpd.service</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+  
+  <refnamediv>
+    <refname>httpd.service</refname>
+    <refname>httpd.socket</refname>
+    <refpurpose>httpd unit files for systemd</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para>
+      <filename>/usr/lib/systemd/system/httpd.service</filename>, 
+      <filename>/usr/lib/systemd/system/httpd.socket</filename>
+    </para>
+  </refsynopsisdiv>
+  
+  <refsect1>
+    <title>Description</title>
+
+    <para>This manual page describes the <command>systemd</command>
+    unit files used to integrate the <command>httpd</command> daemon
+    with <command>systemd</command>. Two unit files are available:
+    <command>httpd.service</command> allows the
+    <command>httpd</command> daemon to be run as a system service, and
+    <command>httpd.socket</command> allows httpd to be started via
+    socket-based activation. Most systems will use
+    <command>httpd.service</command>.</para>
+
+    <refsect2>
+      <title>Changing default behaviour</title>
+
+      <para>To change the default behaviour of the httpd service, an
+      <emphasis>over-ride</emphasis> file should be created, rather
+      than changing
+      <filename>/usr/lib/systemd/system/httpd.service</filename>
+      directly, since such changes would be lost over package
+      upgrades. Running <command>systemctl edit
+      httpd.service</command> or <command>systemctl edit
+      httpd.socket</command> as root will create a drop-in file in
+      <filename>/etc/systemd/system/httpd.service.d</filename> which
+      over-rides the system defaults.</para>
+
+      <para>For example, to set the <literal>LD_LIBRARY_PATH</literal>
+      environment variable for the daemon, run <command>systemctl edit
+      httpd.service</command> and enter:
+
+      <programlisting>[Service]
+Environment=LD_LIBRARY_PATH=/opt/vendor/lib</programlisting></para>
+
+    </refsect2>
+    
+    <refsect2>
+      <title>Starting the service at boot time</title>
+
+      <para>The httpd.service and httpd.socket units are
+      <emphasis>disabled</emphasis> by default. To start the httpd
+      service at boot time, run: <command>systemctl enable
+      httpd.service</command>. In the default configuration, the
+      httpd daemon will accept connections on port 80 (and, if mod_ssl
+      is installed, TLS connections on port 443) for any configured
+      IPv4 or IPv6 address.</para>
+
+      <para>If httpd is configured to depend on any specific IP
+      address (for example, with a "Listen" directive), which may only
+      become available during startup, or if httpd depends on other
+      services (such as a database daemon), the service
+      <emphasis>must</emphasis> be configured to ensure correct
+      startup ordering.</para>
+
+      <para>For example, to ensure httpd is only running after all
+      configured network interfaces are configured, create a drop-in
+      file (as described above) with the following:
+
+      <programlisting>[Unit]
+After=network-online.target
+Wants=network-online.target</programlisting>
+
+      See <ulink
+      url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget/"/>
+      for more information on startup ordering with systemd.</para>
+
+    </refsect2>
+
+    <refsect2>
+      <title>Reloading and stopping the service</title>
+
+      <para>When running <command>systemctl reload
+      httpd.service</command>, a "<emphasis>graceful</emphasis>"
+      restart is used, which sends a signal to the httpd parent
+      process to reload the configuration and re-open log files. Any
+      children with open connections at the time of reload will
+      terminate only once they have completed serving requests. This
+      prevents users of the server seeing errors (or potentially
+      losing data) due to the reload, but means some there is some
+      delay before any configuration changes take effect for all
+      users.</para>
+
+      <para>Similarly, a "<emphasis>graceful stop</emphasis>" is used
+      when <command>systemctl stop httpd.service</command> is run,
+      which terminates the server only once active connections have
+      been processed.</para>
+
+    </refsect2>
+
+    <refsect2>
+      <title>systemd integration and mod_systemd</title>
+
+      <para>httpd.service uses the "<option>notify</option>" systemd
+      service type. The <literal>mod_systemd</literal> module must be
+      loaded (as in the default configuration) for this to work
+      correctly - the service will fail if this module is not
+      loaded. <literal>mod_systemd</literal> also makes worker and
+      request statistics available when running <command>systemctl status
+      httpd</command>. See
+      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      for more information on systemd service types.</para>
+    </refsect2>
+    
+    <refsect2>
+      <title>Security and SELinux</title>
+
+      <para>The default SELinux policy restricts the httpd service in
+      various ways. The ports to which httpd can bind (using the
+      <literal>Listen</literal> directive), which parts of the
+      filesystem can be accessed, whether outgoing TCP connections are
+      possible, are limited by default, for example. Many of these
+      restrictions can be lifted using SELinux booleans and port
+      types. See
+      <citerefentry><refentrytitle>httpd_selinux</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      for more information.</para>
+
+      <para>The httpd service enables <emphasis>PrivateTmp</emphasis>
+      by default. The <filename>/tmp</filename> and
+      <filename>/var/tmp</filename> directories available within the
+      httpd process (and CGI scripts, etc) are not shared by other
+      processes. See
+      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      for more information.</para>
+
+    </refsect2>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Files</title>
+
+    <para><filename>/usr/lib/systemd/system/httpd.service</filename>,
+    <filename>/usr/lib/systemd/system/httpd.socket</filename>,
+    <filename>/etc/systemd/systemd/httpd.service.d</filename></para>
+  </refsect1>
+  
+  <refsect1>
+    <title>See also</title>
+
+    <para>
+    <citerefentry><refentrytitle>httpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 
+    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 
+    <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>httpd_selinux</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/httpd.socket b/httpd.socket
index 705c4e5..a75779c 100644
--- a/httpd.socket
+++ b/httpd.socket
@@ -1,3 +1,5 @@
+# See httpd.socket(5) for more information on using the httpd service.
+
 [Unit]
 Description=Apache httpd Server Socket
 
diff --git a/httpd.spec b/httpd.spec
index ccae88e..3066ea3 100644
--- a/httpd.spec
+++ b/httpd.spec
@@ -8,7 +8,7 @@
 Summary: Apache HTTP Server
 Name: httpd
 Version: 2.4.25
-Release: 8%{?dist}
+Release: 9%{?dist}
 URL: http://httpd.apache.org/
 Source0: http://www.apache.org/dist/httpd/httpd-%{version}.tar.bz2
 Source1: index.html
@@ -234,6 +234,8 @@ if test "x${vmmn}" != "x%{mmn}"; then
    exit 1
 fi
 
+xmlto man $RPM_SOURCE_DIR/httpd.service.xml
+
 : Building with MMN %{mmn}, MMN-ISA %{mmnisa} and vendor string '%{vstring}'
 
 %build
@@ -435,6 +437,11 @@ mkdir -p $RPM_BUILD_ROOT/etc/logrotate.d
 install -m 644 -p $RPM_SOURCE_DIR/httpd.logrotate \
 	$RPM_BUILD_ROOT/etc/logrotate.d/httpd
 
+# Install systemd service man pages
+mkdir -p $RPM_BUILD_ROOT%{_mandir}/man5
+install -m 644 -p httpd.service.5 httpd.socket.5 \
+        $RPM_BUILD_ROOT%{_mandir}/man5
+
 # fix man page paths
 sed -e "s|/usr/local/apache2/conf/httpd.conf|/etc/httpd/conf/httpd.conf|" \
     -e "s|/usr/local/apache2/conf/mime.types|/etc/mime.types|" \
@@ -625,6 +632,7 @@ rm -rf $RPM_BUILD_ROOT
 %attr(0700,apache,apache) %dir %{_localstatedir}/cache/httpd/proxy
 
 %{_mandir}/man8/*
+%{_mandir}/man5/*
 
 %{_unitdir}/*.service
 %{_unitdir}/*.socket
@@ -691,6 +699,9 @@ rm -rf $RPM_BUILD_ROOT
 %{_rpmconfigdir}/macros.d/macros.httpd
 
 %changelog
+* Fri May 19 2017 Joe Orton <jorton@redhat.com> - 2.4.25-9
+- add httpd.service(5) and httpd.socket(5) man pages
+
 * Tue May 16 2017 Joe Orton <jorton@redhat.com> - 2.4.25-8
 - require mod_http2, now packaged separately