add httpd.conf(5) (#1611361)

Resolves: rhbz#1611361

.gitignore

@@ -32,3 +32,4 @@ x86_64
 /httpd*.8
 /results_httpd
 /htcacheclean.service.8
+/httpd.conf.5

README.confd

@@ -5,5 +5,5 @@ processed as httpd configuration files.  The directory is used in
 addition to the directory /etc/httpd/conf.modules.d/, which contains
 configuration files necessary to load modules.
 
-Files are processed in alphabetical order.
+Files are processed in sorted order.  See httpd.conf(5) for more
-
+information.

README.confmod

@@ -6,4 +6,5 @@ configuration fragments necessary only to load modules.
 Administrators should use the directory "/etc/httpd/conf.d" to modify
 the configuration of httpd, or any modules.
 
-Files are processed in alphanumeric order.
+Files are processed in sorted order and should have a two digit
+numeric prefix.  See httpd.conf(5) for more information.

httpd.conf

@@ -6,6 +6,9 @@
 # <URL:http://httpd.apache.org/docs/2.4/mod/directives.html>
 # for a discussion of each configuration directive.
 #
+# See the httpd.conf(5) man page for more information on this configuration,
+# and httpd.service(8) on using and configuring the httpd service.
+#
 # Do NOT simply read the instructions in here without understanding
 # what they do.  They're here only as hints or reminders.  If you are unsure
 # consult the online docs. You have been warned.  

httpd.conf.xml

@@ -0,0 +1,260 @@
+<?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" [
+
+]>
+<!--
+ 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
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<refentry>
+  <refentryinfo>
+    <title>httpd.conf</title>
+    <productname>httpd</productname>
+    <author><contrib>Author</contrib><surname>Orton</surname><firstname>Joe</firstname><email>jorton@redhat.com</email></author>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>httpd.conf</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+  
+  <refnamediv>
+    <refname>httpd.conf</refname>
+    <refpurpose>Configuration files for httpd</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para>
+      <filename>/etc/httpd/conf/httpd.conf</filename>, 
+      <filename>/etc/httpd/conf.modules.d</filename>,
+      <filename>/etc/httpd/conf.d</filename>
+    </para>
+  </refsynopsisdiv>
+  
+  <refsect1>
+    <title>Description</title>
+
+    <para>The <command>httpd</command> daemon uses a main
+    configuration file at
+    <filename>/etc/httpd/conf/httpd.conf</filename>.  The syntax of
+    this file is described at <ulink
+    url="https://httpd.apache.org/docs/2.4/configuring.html"/>, and
+    the full set of available directives at <ulink
+    url="https://httpd.apache.org/docs/2.4/mod/directives.html"/>.
+    </para>
+
+    <refsect2>
+      <title>Configuration structure</title>
+
+      <para>The main configuration file
+      (<filename>httpd.conf</filename>) sets up various defaults and
+      includes configuration files from two directories -
+      <filename>/etc/httpd/conf.modules.d</filename> and
+      <filename>/etc/httpd/conf.d</filename>.  Packages containing
+      loadable modules (like <option>mod_ssl.so</option>) place files
+      in the <filename>conf.modules.d</filename> directory with the
+      appropriate <option>LoadModule</option> directive so that module
+      is loaded by default.</para>
+
+      <para>Some notable configured defaults are:.</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><option>DocumentRoot @DOCROOT@/html</option></term>
+          <listitem><para>The default document root from which content
+          is served.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><option>Listen 80</option></term>
+          <listitem><para>The daemon lists on TCP port 80.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><option>ErrorLog "logs/error_log"</option></term>
+          <listitem><para>Error messages are logged to
+          <filename>@LOGDIR@/error_log</filename>.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><option>ScriptAlias /cgi-bin/ "@DOCROOT@/cgi-bin/"</option></term>
+          <listitem><para>CGI scripts are served via the URL-path <option>/cgi-bin/</option>.</para></listitem>
+        </varlistentry>
+        
+      </variablelist>
+
+      <para>To remove any of the default configuration provided in
+      separate files covered below, replace that file with an empty
+      file rather than removing it from the filesystem, otherwise it
+      may be restored to the original when the package which provides
+      it is upgraded.</para>
+      
+    </refsect2>
+
+    <refsect2>
+      <title>MPM configuration</title>
+
+      <para>The configuration file at
+      <filename>/etc/httpd/conf.modules.d/00-mpm.conf</filename> is
+      used to select the multi-processing module (MPM), which governs
+      how <command>httpd</command> divides work between processes
+      and/or threads at run-time.  Exactly one
+      <option>LoadModule</option> directive must be uncommented in
+      this file; by default the <option>@MPM@</option> MPM is enabled.
+      For more information on MPMs, see <ulink
+      url="https://httpd.apache.org/docs/2.4/mpm.html"/>.</para>
+
+      <para>If using the <emphasis>prefork</emphasis> MPM, the
+      "httpd_graceful_shutdown" SELinux boolean should also be
+      enabled, since with this MPM, httpd needs to establish TCP
+      connections to local ports to successfully complete a graceful
+      restart or shutdown. This boolean can be enabled by running the
+      command: <command>semanage boolean -m --on
+      httpd_graceful_shutdown</command></para>
+    </refsect2>
+    
+    <refsect2>
+      <title>Module configuration files</title>
+      
+      <para>Module configuration files are provided in the
+      <filename>/etc/httpd/conf.modules.d/</filename> directory, with
+      names which are by convention prefixed with two digit numeric
+      prefix to ensure they are processed in the desired order.  Core
+      modules provide with the <command>httpd</command> package are
+      loaded by files with a <option>0x-</option> prefix to ensure
+      these are loaded first.  Only filenames with a
+      <option>.conf</option> suffix in this directory will be
+      processed.</para>
+
+      <para>Other provided configuration files are listed below.
+      
+      <variablelist>
+        <varlistentry>
+          <term><filename>/etc/httpd/conf.modules.d/00-base.conf</filename></term>
+          <listitem><para>The set of core modules included with
+          <command>httpd</command> which are all loaded by
+          default.</para></listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term><filename>/etc/httpd/conf.modules.d/00-optional.conf</filename></term>
+          <listitem><para>The set of non-core modules included with
+          <command>httpd</command> which are <emphasis>not</emphasis>
+          loaded by default.</para></listitem>
+        </varlistentry>
+        
+
+        <varlistentry>
+          <term><filename>/etc/httpd/conf.modules.d/00-systemd.conf</filename></term>
+          <listitem><para>This file loads <option>mod_systemd</option>
+          which is necessary for the correct operation of the
+          <command>httpd.service</command> service, and should not be
+          removed or disabled.</para></listitem>
+        </varlistentry>
+      </variablelist>
+      </para>
+    </refsect2>
+        
+    <refsect2>
+      <title>Other configuration files</title>
+
+      <para>Default module configuration files and site-specific
+      configuration files are loaded from the
+      <filename>/etc/httpd/conf.d/</filename> directory.  Only files
+      with a <option>.conf</option> suffix will be loaded.  The
+      following files are provided:
+
+      <variablelist>
+        <varlistentry>
+          <term><filename>/etc/httpd/conf.d/userdir.conf</filename></term>
+          <listitem><para>This file gives an example configuration for
+          <option>mod_userdir</option> to map URLs such as
+          <option>http://localhost/~jim/</option> to
+          <filename>/home/jim/public_html/</filename>. Userdir mapping
+          is disabled by default.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><filename>/etc/httpd/conf.d/autoindex.conf</filename></term>
+          <listitem><para>This file provides the default configuration
+          for <option>mod_autoindex</option> which generates HTML
+          directory listings when enabled.  It also makes file icon
+          image files available at the <option>/icons/</option>
+          URL-path.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><filename>/etc/httpd/conf.d/welcome.conf</filename></term>
+          <listitem><para>This file enables a "welcome page" at
+          <option>http://localhost/</option> if no content is present
+          in the default documentation root
+          <filename>/var/www/html</filename>.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><filename>/etc/httpd/conf.d/ssl.conf</filename> (present only if <option>mod_ssl</option> is installed)</term>
+          <listitem><para>This file configures a TLS
+          <option>VirtualHost</option> listening on port
+          <option>443</option>.  If the default configuration is used,
+          the referenced test certificate and private key are
+          generated the first time <command>httpd.service</command> is
+          started; see
+          <citerefentry><refentrytitle>httpd-init.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+          for more information.</para></listitem>
+        </varlistentry>
+        
+      </variablelist></para>
+    </refsect2>
+    
+    <refsect2>
+      <title>Instantiated services</title>
+
+      <para>As an alternative to (or in addition to) the
+      <command>httpd.service</command> unit, the instatiated template
+      service <command>httpd@.service</command> unit file can be used,
+      which starts <command>httpd</command> using a different
+      configuration file to the default. For example,
+      <command>systemctl start httpd@foobar.service</command> will
+      start httpd using the configuration file
+      <filename>/etc/httpd/conf/foobar.conf</filename>.  See <citerefentry><refentrytitle>httpd@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> for more information.</para>
+    </refsect2>
+      
+  </refsect1>
+  <refsect1>
+    <title>Files</title>
+
+    <para>
+      <filename>/etc/httpd/conf/httpd.conf</filename>, 
+      <filename>/etc/httpd/conf.d</filename>, 
+      <filename>/etc/httpd/conf.modules.d</filename>
+    </para>
+  </refsect1>
+  
+  <refsect1>
+    <title>See also</title>
+
+    <para>
+    <citerefentry><refentrytitle>httpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 
+    <citerefentry><refentrytitle>httpd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+    <ulink url="https://httpd.apache.org/docs/2.4/configuring.html"/>,
+    <ulink url="https://httpd.apache.org/docs/2.4/mod/directives.html"/>
+    </para>
+  </refsect1>
+
+</refentry>
+
+<!-- LocalWords:  systemd PidFile
+-->

httpd.service.xml

@@ -188,17 +188,10 @@ Wants=network-online.target</programlisting>
 
       <para>httpd offers a choice of multi-processing modules (MPMs),
       which can be configured in
-      <filename>/etc/httpd/conf.modules.d/00-mpm.conf</filename>.  The
+      <filename>/etc/httpd/conf.modules.d/00-mpm.conf</filename>.
-      default is to use the <emphasis>@MPM@</emphasis> MPM.</para>
+      See
-
+      <citerefentry><refentrytitle>httpd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-      <para>If using the <emphasis>prefork</emphasis> MPM, the
+      for more information on changing the MPM.</para>
-      "httpd_graceful_shutdown" SELinux boolean should also be
-      enabled, since with this MPM, httpd needs to establish TCP
-      connections to local ports to successfully complete a graceful
-      restart or shutdown. This boolean can be enabled by running the
-      command: <command>semanage boolean -m --on
-      httpd_graceful_shutdown</command></para>
-
     </refsect2>
 
     <refsect2>
@@ -322,6 +315,7 @@ ReloadPropagatedFrom=httpd.service</programlisting>
 
     <para>
     <citerefentry><refentrytitle>httpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 
+    <citerefentry><refentrytitle>httpd.conf</refentrytitle><manvolnum>5</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>,

httpd.spec

@@ -13,7 +13,7 @@
 Summary: Apache HTTP Server
 Name: httpd
 Version: 2.4.37
-Release: 3%{?dist}
+Release: 4%{?dist}
 URL: https://httpd.apache.org/
 Source0: https://www.apache.org/dist/httpd/httpd-%{version}.tar.bz2
 Source1: index.html
@@ -266,11 +266,16 @@ if test "x${vmmn}" != "x%{mmn}"; then
    exit 1
 fi
 
-sed 's/@MPM@/%{mpm}/' < $RPM_SOURCE_DIR/httpd.service.xml \
+sed '
-    > httpd.service.xml
+s,@MPM@,%{mpm},g
+s,@DOCROOT@,%{docroot},g
+s,@LOGDIR@,%{_localstatedir}/log/httpd,g
+' < $RPM_SOURCE_DIR/httpd.conf.xml \
+    > httpd.conf.xml
 
-xmlto man ./httpd.service.xml
+xmlto man ./httpd.conf.xml
 xmlto man $RPM_SOURCE_DIR/htcacheclean.service.xml
+xmlto man $RPM_SOURCE_DIR/httpd.service.xml
 
 : Building with MMN %{mmn}, MMN-ISA %{mmnisa}
 : Default MPM is %{mpm}, vendor string is '%{vstring}'
@@ -491,10 +496,13 @@ 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
+# Install man pages
+install -d $RPM_BUILD_ROOT%{_mandir}/man8 $RPM_BUILD_ROOT%{_mandir}/man5
 install -m 644 -p httpd.service.8 httpd-init.service.8 httpd.socket.8 \
         httpd@.service.8 htcacheclean.service.8 \
         $RPM_BUILD_ROOT%{_mandir}/man8
+install -m 644 -p httpd.conf.5 \
+        $RPM_BUILD_ROOT%{_mandir}/man5
 
 # fix man page paths
 sed -e "s|/usr/local/apache2/conf/httpd.conf|/etc/httpd/conf/httpd.conf|" \
@@ -660,6 +668,7 @@ exit $rv
 %attr(0700,apache,apache) %dir %{_localstatedir}/cache/httpd/proxy
 
 %{_mandir}/man8/*
+%{_mandir}/man5/*
 %exclude %{_mandir}/man8/httpd-init.*
 
 %{_unitdir}/httpd.service
@@ -729,6 +738,9 @@ exit $rv
 %{_rpmconfigdir}/macros.d/macros.httpd
 
 %changelog
+* Thu Nov  8 2018 Joe Orton <jorton@redhat.com> - 2.4.37-4
+- add httpd.conf(5) (#1611361)
+
 * Wed Nov 07 2018 Luboš Uhliarik <luhliari@redhat.com> - 2.4.37-3
 - Resolves: #1647241 - fix apachectl script