add httpd@.service; update httpd.service(8) and add new stub

httpd.service.xml

@@ -4,7 +4,7 @@
 
 ]>
 <!--
- Copyright 2017 Red Hat, Inc.
+ Copyright 2018 Red Hat, Inc.
 
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
@@ -36,6 +36,7 @@
   
   <refnamediv>
     <refname>httpd.service</refname>
+    <refname>httpd@.service</refname>
     <refname>httpd.socket</refname>
     <refname>httpd-init.service</refname>
     <refpurpose>httpd unit files for systemd</refpurpose>
@@ -44,6 +45,7 @@
   <refsynopsisdiv>
     <para>
       <filename>/usr/lib/systemd/system/httpd.service</filename>, 
+      <filename>/usr/lib/systemd/system/httpd@.service</filename>,
       <filename>/usr/lib/systemd/system/httpd-init.service</filename>,
       <filename>/usr/lib/systemd/system/httpd.socket</filename>
     </para>
@@ -82,8 +84,9 @@
       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
+      httpd.socket</command> as root will create a drop-in file (in
-      <filename>/etc/systemd/system/httpd.service.d</filename> which
+      the former case, in
+      <filename>/etc/systemd/system/httpd.service.d</filename>) which
       over-rides the system defaults.</para>
 
       <para>For example, to set the <option>LD_LIBRARY_PATH</option>
@@ -260,6 +263,48 @@ Wants=network-online.target</programlisting>
       192.168.1.2:80</literal>" will not work.</para>
     </refsect2>
 
+    <refsect2>
+      <title>Instatiated services</title>
+
+      <para>The <command>httpd@.service</command> unit is an
+      instatiated template service. An instance of this unit will be
+      started using the configuration file
+      <filename>/etc/httpd/conf/INSTANCE.conf</filename>, where
+      <emphasis>INSTANCE</emphasis> is replaced with the instance
+      name.  For example, <command>systemctl start
+      httpd@foobar.service</command> will start httpd using the
+      configuration file
+      <filename>/etc/httpd/conf/foobar.conf</filename>.  The
+      <option>HTTPD_INSTANCE</option> environment variable is set to
+      the instance name by the unit and is available name for use
+      within the configuration file.</para>
+
+      <para>To allow multiple instances of httpd to run
+      simultaneously, a number of configuration directives must be
+      changed; such as <command>PidFile</command> and
+      <command>DefaultRuntimeDir</command> to pick non-conflict paths,
+      and <command>Listen</command> to choose ports.  The example
+      configuration file
+      <filename>/usr/share/doc/httpd/instance.conf</filename>
+      demonstrates how to make such changes using
+      <option>HTTPD_INSTANCE</option> variable.</para>
+
+      <para>It can be useful to configure instances of
+      <command>httpd@.service</command> to reload when
+      <command>httpd.service</command> is reloaded; for example,
+      <command>logrotate</command> will reload only
+      <command>httpd.service</command> when logs are rotated. If this
+      behaviour is required, create a drop-in file for the instance as
+      follows:
+
+      <programlisting>[Unit]
+ReloadPropagatedFrom=httpd.service</programlisting>
+
+      As with normal units, drop-in files for instances can be created
+      using <command>systemctl edit</command>, e.g. <command>systemctl edit
+      httpd@foobar.service</command>.</para>
+    </refsect2>
+
   </refsect1>
 
   <refsect1>

httpd.spec

@@ -13,11 +13,12 @@
 Summary: Apache HTTP Server
 Name: httpd
 Version: 2.4.33
-Release: 4%{?dist}
+Release: 5%{?dist}
 URL: https://httpd.apache.org/
 Source0: https://www.apache.org/dist/httpd/httpd-%{version}.tar.bz2
 Source1: index.html
 Source2: httpd.logrotate
+Source3: instance.conf
 Source4: httpd-ssl-pass-dialog
 Source5: httpd.tmpfiles
 Source6: httpd.service
@@ -51,6 +52,7 @@ Source40: htcacheclean.service
 Source41: htcacheclean.sysconf
 Source42: httpd-init.service
 Source43: httpd-ssl-gencerts
+Source44: httpd@.service
 # build/scripts patches
 Patch1: httpd-2.4.1-apctl.patch
 Patch2: httpd-2.4.9-apxs.patch
@@ -239,6 +241,16 @@ sed -i '/^#define PLATFORM/s/Unix/%{vstring}/' os/unix/os.h
 # Prevent use of setcap in "install-suexec-caps" target.
 sed -i '/suexec/s,setcap ,echo Skipping setcap for ,' Makefile.in
 
+# Example conf for instances
+cp $RPM_SOURCE_DIR/instance.conf .
+sed < $RPM_SOURCE_DIR/httpd.conf >> instance.conf '
+0,/^ServerRoot/d;
+/# Supplemental configuration/,$d
+/^ *CustomLog .logs/s,logs/,logs/${HTTPD_INSTANCE}_,
+/^ *ErrorLog .logs/s,logs/,logs/${HTTPD_INSTANCE}_,
+'
+touch -r $RPM_SOURCE_DIR/instance.conf instance.conf
+
 # Safety check: prevent build if defined MMN does not equal upstream MMN.
 vmmn=`echo MODULE_MAGIC_NUMBER_MAJOR | cpp -include include/ap_mmn.h | sed -n '/^2/p'`
 if test "x${vmmn}" != "x%{mmn}"; then
@@ -319,7 +331,8 @@ make DESTDIR=$RPM_BUILD_ROOT install
 
 # Install systemd service files
 mkdir -p $RPM_BUILD_ROOT%{_unitdir}
-for s in httpd.service htcacheclean.service httpd.socket httpd-init.service; do
+for s in httpd.service htcacheclean.service httpd.socket \
+         httpd@.service httpd-init.service; do
   install -p -m 644 $RPM_SOURCE_DIR/${s} \
                     $RPM_BUILD_ROOT%{_unitdir}/${s}
 done
@@ -469,6 +482,7 @@ install -m 644 -p $RPM_SOURCE_DIR/httpd.logrotate \
 
 # Install systemd service man pages
 install -m 644 -p httpd.service.8 httpd-init.service.8 httpd.socket.8 \
+        httpd@.service.8 \
         $RPM_BUILD_ROOT%{_mandir}/man8
 
 # fix man page paths
@@ -567,6 +581,7 @@ exit $rv
 
 %doc ABOUT_APACHE README CHANGES LICENSE VERSIONING NOTICE
 %doc docs/conf/extra/*.conf
+%doc instance.conf
 
 %{_sysconfdir}/httpd/modules
 %{_sysconfdir}/httpd/logs
@@ -636,6 +651,7 @@ exit $rv
 %exclude %{_mandir}/man8/httpd-init.*
 
 %{_unitdir}/httpd.service
+%{_unitdir}/httpd@.service
 %{_unitdir}/htcacheclean.service
 %{_unitdir}/*.socket
 
@@ -709,6 +725,9 @@ exit $rv
 %{_rpmconfigdir}/macros.d/macros.httpd
 
 %changelog
+* Thu Apr 19 2018 Joe Orton <jorton@redhat.com> - 2.4.33-5
+- add httpd@.service; update httpd.service(8) and add new stub
+
 * Mon Apr 16 2018 Joe Orton <jorton@redhat.com> - 2.4.33-4
 - mod_md: change hard-coded default MdStoreDir to state/md (#1563846)
 

httpd@.service

@@ -0,0 +1,23 @@
+# This is a template for httpd instances.
+# See httpd@.service(8) for more information.
+
+[Unit]
+Description=The Apache HTTP Server
+After=network.target remote-fs.target nss-lookup.target
+Documentation=man:httpd@.service(8)
+
+[Service]
+Type=notify
+Environment=LANG=C
+Environment=HTTPD_INSTANCE=%i
+ExecStartPre=/bin/mkdir -m 710 -p /run/httpd/instance-%i
+ExecStartPre=/bin/chown root.apache /run/httpd/instance-%i
+ExecStart=/usr/sbin/httpd $OPTIONS -DFOREGROUND -f conf/%i.conf
+ExecReload=/usr/sbin/httpd $OPTIONS -k graceful -f conf/%i.conf
+# Send SIGWINCH for graceful stop
+KillSignal=SIGWINCH
+KillMode=mixed
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target

instance.conf

@@ -0,0 +1,22 @@
+#
+# This is an example instance-specific configuration file.  To use
+# copy this file to e.g. /etc/httpd/conf/foobar.conf.  See the
+# httpd.service(8) man page for more information.
+#
+# This config will then used as the default configuration when
+# running:
+#
+#   # systemctl start httpd@foobar.service
+#
+# The changes compared to the default are:
+# - DefaultRuntime and Pidfile renamed to be instance-specific
+# - default logfile names are prefixed with the instance name
+# - /etc/httpd/conf.d is NOT included by default (conf.modules.d still is)
+#
+# Further customisations will be required for an instance to run
+# simultaneously to httpd.service under the default configuration,
+# e.g. changing the port used with Listen.
+#
+
+DefaultRuntimeDir /run/httpd/instance-${HTTPD_INSTANCE}
+PidFile /run/httpd/instance-${HTTPD_INSTANCE}.pid