<?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 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>8</manvolnum>
  </refmeta>
  
  <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>
  </refnamediv>

  <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>
  </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 main 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>

    <para>The <command>apachectl</command> command has been modified
    to invoke <command>systemctl</command> for most uses, so for
    example, running <command>apachectl start</command> is equivalent
    to running <command>systemctl start httpd.service</command>.  This
    ensures that the running httpd daemon is tracked and managed by
    <command>systemd</command>.  In contrast, running
    <command>httpd</command> directly from a root shell will start the
    service outside of <command>systemd</command>; in this case,
    default security restrictions described below (including, but not
    limited to, SELinux) will not be enforced.</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
      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>
      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 start-up, or if httpd depends on other
      services (such as a database daemon), the service
      <emphasis>must</emphasis> be configured to ensure correct
      start-up 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 section:

      <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 start-up ordering with systemd.</para>

    </refsect2>

    <refsect2>
      <title>SSL/TLS certificate generation</title>

      <para>The <command>httpd-init.service</command> unit is provided
      with the mod_ssl package. This oneshot unit automatically
      creates a TLS server certificate and key (using a generated
      self-signed CA certificate and key) for testing purposes before
      httpd is started. To inhibit certificate generation, use
      <command>systemctl mask httpd-init.service</command> after
      installing mod_ssl, and adjust the mod_ssl configuration to use
      an appropriate certificate and key.</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>

      <para>To "ungracefully" stop the server without waiting for
      requests to complete, use <command>systemctl kill
      --kill-who=main httpd</command>; similarly to "ungracefully"
      reload the configuration, use <command>systemctl kill
      --kill-who=main --signal=HUP httpd</command>.</para>
    </refsect2>

    <refsect2>
      <title>Automated service restarts</title>

      <para>System packages (including the httpd package itself) may
      restart the httpd service automatically after packages are
      upgraded, installed, or removed. This is done using the
      <command>systemctl reload httpd.service</command>, which
      produces a <emphasis>graceful</emphasis> restart by default as
      described above.</para>

      <para>To suppress automatic reloads entirely, create the file
      <filename>/etc/sysconfig/httpd-disable-posttrans</filename>.</para>
    </refsect2>

    <refsect2>
      <title>Changing the default MPM (Multi-Processing Module)</title>

      <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
      default is to use the <emphasis>@MPM@</emphasis> MPM.</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>systemd integration and mod_systemd</title>

      <para>The 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. For example, the default policy limits the ports
      to which httpd can bind (using the <literal>Listen</literal>
      directive), which parts of the filesystem can be accessed, and
      whether outgoing TCP connections are possible. Many of these
      restrictions can be relaxed or adjusted by using
      <command>semanage</command> to change booleans or other
      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>

    <refsect2>
      <title>Socket activation</title>

      <para>Socket activation (see
      <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
      for more information) can be used with <command>httpd</command>
      by enabling the <command>httpd.socket</command> unit.  The
      <command>httpd</command> listener configuration must exactly
      match the <literal>ListenStream</literal> options configured for
      the <command>httpd.socket</command> unit.  The default
      <command>httpd.socket</command> has a
      <literal>ListenStream=80</literal> and, if mod_ssl is installed,
      <literal>ListenStream=443</literal> by a drop-in file. If
      additional <literal>Listen</literal> directives are added to the
      httpd configuration, corresponding
      <literal>ListenStream</literal> options should be added via
      drop-in files, for example via <command>systemctl edit
      httpd.socket</command>.</para>

      <para>If using socket activation with httpd, only one listener
      on any given TCP port is supported; a configuration with both
      "<literal>Listen 127.0.0.1:80</literal>" and "<literal>Listen
      192.168.1.2:80</literal>" will not work.</para>
    </refsect2>

    <refsect2>
      <title>Instantiated services</title>

      <para>The <command>httpd@.service</command> unit is an
      instantiated 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 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-conflicting
      paths, and <command>Listen</command> to choose different 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>
    <title>Files</title>

    <para><filename>/usr/lib/systemd/system/httpd.service</filename>,
    <filename>/usr/lib/systemd/system/httpd.socket</filename>,
    <filename>/usr/lib/systemd/system/httpd@.service</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>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>httpd_selinux</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>semanage</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>

<!-- LocalWords:  systemd PidFile
-->