e71654
e71654
e71654
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
e71654
e71654
]>
e71654
e71654
 Copyright 2018 Red Hat, Inc.
e71654
e71654
 Licensed to the Apache Software Foundation (ASF) under one or more
e71654
 contributor license agreements.  See the NOTICE file distributed with
e71654
 this work for additional information regarding copyright ownership.
e71654
 The ASF licenses this file to You under the Apache License, Version 2.0
e71654
 (the "License"); you may not use this file except in compliance with
e71654
 the License.  You may obtain a copy of the License at
e71654
e71654
     http://www.apache.org/licenses/LICENSE-2.0
e71654
e71654
 Unless required by applicable law or agreed to in writing, software
e71654
 distributed under the License is distributed on an "AS IS" BASIS,
e71654
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
e71654
 See the License for the specific language governing permissions and
e71654
 limitations under the License.
e71654
-->
e71654
e71654
<refentry>
e71654
  <refentryinfo>
e71654
    <title>httpd systemd units</title>
e71654
    <productname>httpd</productname>
e71654
    <author><contrib>Author</contrib><surname>Orton</surname><firstname>Joe</firstname><email>jorton@redhat.com</email></author>
e71654
  </refentryinfo>
e71654
e71654
  <refmeta>
e71654
    <refentrytitle>httpd.service</refentrytitle>
e71654
    <manvolnum>8</manvolnum>
e71654
  </refmeta>
e71654
  
e71654
  <refnamediv>
e71654
    <refname>httpd.service</refname>
e71654
    <refname>httpd@.service</refname>
e71654
    <refname>httpd.socket</refname>
e71654
    <refname>httpd-init.service</refname>
e71654
    <refpurpose>httpd unit files for systemd</refpurpose>
e71654
  </refnamediv>
e71654
e71654
  <refsynopsisdiv>
e71654
    <para>
e71654
      <filename>/usr/lib/systemd/system/httpd.service</filename>, 
e71654
      <filename>/usr/lib/systemd/system/httpd@.service</filename>,
e71654
      <filename>/usr/lib/systemd/system/httpd-init.service</filename>,
e71654
      <filename>/usr/lib/systemd/system/httpd.socket</filename>
e71654
    </para>
e71654
  </refsynopsisdiv>
e71654
  
e71654
  <refsect1>
e71654
    <title>Description</title>
e71654
e71654
    <para>This manual page describes the <command>systemd</command>
e71654
    unit files used to integrate the <command>httpd</command> daemon
e71654
    with <command>systemd</command>. Two main unit files are
e71654
    available: <command>httpd.service</command> allows the
e71654
    <command>httpd</command> daemon to be run as a system service, and
e71654
    <command>httpd.socket</command> allows httpd to be started via
e71654
    socket-based activation. Most systems will use
e71654
    <command>httpd.service</command>.</para>
e71654
e71654
    <para>The <command>apachectl</command> command has been modified
e71654
    to invoke <command>systemctl</command> for most uses, so for
e71654
    example, running <command>apachectl start</command> is equivalent
e71654
    to running <command>systemctl start httpd.service</command>.  This
e71654
    ensures that the running httpd daemon is tracked and managed by
e71654
    <command>systemd</command>.  In contrast, running
e71654
    <command>httpd</command> directly from a root shell will start the
e71654
    service outside of <command>systemd</command>; in this case,
e71654
    default security restrictions described below (including, but not
e71654
    limited to, SELinux) will not be enforced.</para>
e71654
e71654
    <refsect2>
e71654
      <title>Changing default behaviour</title>
e71654
e71654
      <para>To change the default behaviour of the httpd service, an
e71654
      <emphasis>over-ride</emphasis> file should be created, rather
e71654
      than changing
e71654
      <filename>/usr/lib/systemd/system/httpd.service</filename>
e71654
      directly, since such changes would be lost over package
e71654
      upgrades. Running <command>systemctl edit
e71654
      httpd.service</command> or <command>systemctl edit
e71654
      httpd.socket</command> as root will create a drop-in file (in
e71654
      the former case, in
e71654
      <filename>/etc/systemd/system/httpd.service.d</filename>) which
e71654
      over-rides the system defaults.</para>
e71654
e71654
      <para>For example, to set the <option>LD_LIBRARY_PATH</option>
e71654
      environment variable for the daemon, run <command>systemctl edit
e71654
      httpd.service</command> and enter:
e71654
e71654
      <programlisting>[Service]
e71654
Environment=LD_LIBRARY_PATH=/opt/vendor/lib</programlisting></para>
e71654
    </refsect2>
e71654
    
e71654
    <refsect2>
e71654
      <title>Starting the service at boot time</title>
e71654
e71654
      <para>The httpd.service and httpd.socket units are
e71654
      <emphasis>disabled</emphasis> by default. To start the httpd
e71654
      service at boot time, run: <command>systemctl enable
e71654
      httpd.service</command>. In the default configuration, the
e71654
      httpd daemon will accept connections on port 80 (and, if mod_ssl
e71654
      is installed, TLS connections on port 443) for any configured
e71654
      IPv4 or IPv6 address.</para>
e71654
e71654
      <para>If httpd is configured to depend on any specific IP
e71654
      address (for example, with a "Listen" directive) which may only
e71654
      become available during start-up, or if httpd depends on other
e71654
      services (such as a database daemon), the service
e71654
      <emphasis>must</emphasis> be configured to ensure correct
e71654
      start-up ordering.</para>
e71654
e71654
      <para>For example, to ensure httpd is only running after all
e71654
      configured network interfaces are configured, create a drop-in
e71654
      file (as described above) with the following section:
e71654
e71654
      <programlisting>[Unit]
e71654
After=network-online.target
e71654
Wants=network-online.target</programlisting>
e71654
e71654
      See 
e71654
      url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget/"/>
e71654
      for more information on start-up ordering with systemd.</para>
e71654
e71654
    </refsect2>
e71654
e71654
    <refsect2>
e71654
      <title>SSL/TLS certificate generation</title>
e71654
e71654
      <para>The <command>httpd-init.service</command> unit is provided
e71654
      with the mod_ssl package. This oneshot unit automatically
e71654
      creates a TLS server certificate and key (using a generated
e71654
      self-signed CA certificate and key) for testing purposes before
e71654
      httpd is started. To inhibit certificate generation, use
e71654
      <command>systemctl mask httpd-init.service</command> after
e71654
      installing mod_ssl, and adjust the mod_ssl configuration to use
e71654
      an appropriate certificate and key.</para>
e71654
e71654
    </refsect2>
e71654
e71654
    <refsect2>
e71654
      <title>Reloading and stopping the service</title>
e71654
e71654
      <para>When running <command>systemctl reload
e71654
      httpd.service</command>, a <emphasis>graceful</emphasis>
e71654
      restart is used, which sends a signal to the httpd parent
e71654
      process to reload the configuration and re-open log files. Any
e71654
      children with open connections at the time of reload will
e71654
      terminate only once they have completed serving requests. This
e71654
      prevents users of the server seeing errors (or potentially
e71654
      losing data) due to the reload, but means some there is some
e71654
      delay before any configuration changes take effect for all
e71654
      users.</para>
e71654
e71654
      <para>Similarly, a <emphasis>graceful stop</emphasis> is used
e71654
      when <command>systemctl stop httpd.service</command> is run,
e71654
      which terminates the server only once active connections have
e71654
      been processed.</para>
e71654
e71654
      <para>To "ungracefully" stop the server without waiting for
e71654
      requests to complete, use <command>systemctl kill
e71654
      --kill-who=main httpd</command>; similarly to "ungracefully"
e71654
      reload the configuration, use <command>systemctl kill
e71654
      --kill-who=main --signal=HUP httpd</command>.</para>
e71654
    </refsect2>
e71654
e71654
    <refsect2>
e71654
      <title>Automated service restarts</title>
e71654
e71654
      <para>System packages (including the httpd package itself) may
e71654
      restart the httpd service automatically after packages are
e71654
      upgraded, installed, or removed. This is done using the
e71654
      <command>systemctl reload httpd.service</command>, which
e71654
      produces a <emphasis>graceful</emphasis> restart by default as
e71654
      described above.</para>
e71654
e71654
      <para>To suppress automatic reloads entirely, create the file
e71654
      <filename>/etc/sysconfig/httpd-disable-posttrans</filename>.</para>
e71654
    </refsect2>
e71654
e71654
    <refsect2>
e71654
      <title>Changing the default MPM (Multi-Processing Module)</title>
e71654
e71654
      <para>httpd offers a choice of multi-processing modules (MPMs),
e71654
      which can be configured in
e71654
      <filename>/etc/httpd/conf.modules.d/00-mpm.conf</filename>.
e71654
      See
e71654
      <citerefentry><refentrytitle>httpd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
e71654
      for more information on changing the MPM.</para>
e71654
    </refsect2>
e71654
e71654
    <refsect2>
e71654
      <title>systemd integration and mod_systemd</title>
e71654
e71654
      <para>The httpd service uses the <option>notify</option> systemd
e71654
      service type. The <literal>mod_systemd</literal> module must be
e71654
      loaded (as in the default configuration) for this to work
e71654
      correctly - the service will fail if this module is not
e71654
      loaded. <literal>mod_systemd</literal> also makes worker and
e71654
      request statistics available when running <command>systemctl status
e71654
      httpd</command>. See
e71654
      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
e71654
      for more information on systemd service types.</para>
e71654
    </refsect2>
e71654
    
e71654
    <refsect2>
e71654
      <title>Security and SELinux</title>
e71654
e71654
      <para>The default SELinux policy restricts the httpd service in
e71654
      various ways. For example, the default policy limits the ports
e71654
      to which httpd can bind (using the <literal>Listen</literal>
e71654
      directive), which parts of the filesystem can be accessed, and
e71654
      whether outgoing TCP connections are possible. Many of these
e71654
      restrictions can be relaxed or adjusted by using
e71654
      <command>semanage</command> to change booleans or other
e71654
      types. See
e71654
      <citerefentry><refentrytitle>httpd_selinux</refentrytitle><manvolnum>8</manvolnum></citerefentry>
e71654
      for more information.</para>
e71654
e71654
      <para>The httpd service enables <emphasis>PrivateTmp</emphasis>
e71654
      by default. The <filename>/tmp</filename> and
e71654
      <filename>/var/tmp</filename> directories available within the
e71654
      httpd process (and CGI scripts, etc) are not shared by other
e71654
      processes. See
e71654
      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
e71654
      for more information.</para>
e71654
e71654
    </refsect2>
e71654
e71654
    <refsect2>
e71654
      <title>Socket activation</title>
e71654
e71654
      <para>Socket activation (see
e71654
      <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
e71654
      for more information) can be used with <command>httpd</command>
e71654
      by enabling the <command>httpd.socket</command> unit.  The
e71654
      <command>httpd</command> listener configuration must exactly
e71654
      match the <literal>ListenStream</literal> options configured for
e71654
      the <command>httpd.socket</command> unit.  The default
e71654
      <command>httpd.socket</command> has a
e71654
      <literal>ListenStream=80</literal> and, if mod_ssl is installed,
e71654
      <literal>ListenStream=443</literal> by a drop-in file. If
e71654
      additional <literal>Listen</literal> directives are added to the
e71654
      httpd configuration, corresponding
e71654
      <literal>ListenStream</literal> options should be added via
e71654
      drop-in files, for example via <command>systemctl edit
e71654
      httpd.socket</command>.</para>
e71654
e71654
      <para>If using socket activation with httpd, only one listener
e71654
      on any given TCP port is supported; a configuration with both
e71654
      "<literal>Listen 127.0.0.1:80</literal>" and "<literal>Listen
e71654
      192.168.1.2:80</literal>" will not work.</para>
e71654
    </refsect2>
e71654
e71654
    <refsect2>
e71654
      <title>Instantiated services</title>
e71654
e71654
      <para>The <command>httpd@.service</command> unit is an
e71654
      instantiated template service. An instance of this unit will be
e71654
      started using the configuration file
e71654
      <filename>/etc/httpd/conf/INSTANCE.conf</filename>, where
e71654
      <emphasis>INSTANCE</emphasis> is replaced with the instance
e71654
      name.  For example, <command>systemctl start
e71654
      httpd@foobar.service</command> will start httpd using the
e71654
      configuration file
e71654
      <filename>/etc/httpd/conf/foobar.conf</filename>.  The
e71654
      <option>HTTPD_INSTANCE</option> environment variable is set to
e71654
      the instance name by the unit and is available for use within
e71654
      the configuration file.</para>
e71654
e71654
      <para>To allow multiple instances of httpd to run
e71654
      simultaneously, a number of configuration directives must be
e71654
      changed, such as <command>PidFile</command> and
e71654
      <command>DefaultRuntimeDir</command> to pick non-conflicting
e71654
      paths, and <command>Listen</command> to choose different ports.
e71654
      The example configuration file
e71654
      <filename>/usr/share/doc/httpd/instance.conf</filename>
e71654
      demonstrates how to make such changes using
e71654
      <option>HTTPD_INSTANCE</option> variable.</para>
e71654
e71654
      <para>It can be useful to configure instances of
e71654
      <command>httpd@.service</command> to reload when
e71654
      <command>httpd.service</command> is reloaded; for example,
e71654
      <command>logrotate</command> will reload only
e71654
      <command>httpd.service</command> when logs are rotated. If this
e71654
      behaviour is required, create a drop-in file for the instance as
e71654
      follows:
e71654
e71654
      <programlisting>[Unit]
e71654
ReloadPropagatedFrom=httpd.service</programlisting>
e71654
e71654
      As with normal units, drop-in files for instances can be created
e71654
      using <command>systemctl edit</command>, e.g. <command>systemctl edit
e71654
      httpd@foobar.service</command>.</para>
e71654
    </refsect2>
e71654
e71654
  </refsect1>
e71654
e71654
  <refsect1>
e71654
    <title>Files</title>
e71654
e71654
    <para><filename>/usr/lib/systemd/system/httpd.service</filename>,
e71654
    <filename>/usr/lib/systemd/system/httpd.socket</filename>,
e71654
    <filename>/usr/lib/systemd/system/httpd@.service</filename>,
e71654
    <filename>/etc/systemd/systemd/httpd.service.d</filename></para>
e71654
  </refsect1>
e71654
  
e71654
  <refsect1>
e71654
    <title>See also</title>
e71654
e71654
    <para>
e71654
    <citerefentry><refentrytitle>httpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 
e71654
    <citerefentry><refentrytitle>httpd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e71654
    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 
e71654
    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 
e71654
    <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e71654
    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e71654
    <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e71654
    <citerefentry><refentrytitle>httpd_selinux</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
e71654
    <citerefentry><refentrytitle>semanage</refentrytitle><manvolnum>8</manvolnum></citerefentry>
e71654
    </para>
e71654
  </refsect1>
e71654
e71654
</refentry>
e71654
e71654
e71654
-->