375 lines
16 KiB
XML
375 lines
16 KiB
XML
<?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 try-restart httpd.service</command>, which
|
|
stops then starts the service if it is running.</para>
|
|
|
|
<para>To disable automatic restarts, create the file
|
|
<filename>/etc/sysconfig/httpd-disable-posttrans</filename>.
|
|
When <command>httpd</command> interfaces are added in an update,
|
|
it may not be safe to <emphasis>reload</emphasis> a running
|
|
service after upgrading, if updated modules require interfaces
|
|
only available in the updated httpd. It is recommended to allow
|
|
automatic restarts for this reason.</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>.
|
|
See
|
|
<citerefentry><refentrytitle>httpd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for more information on changing the MPM.</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>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Process policies and restrictions</title>
|
|
|
|
<para>The httpd service uses the following options:
|
|
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>PrivateTmp</emphasis> is enabled 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.</para></listitem>
|
|
|
|
<listitem><para><emphasis>OOMPolicy</emphasis> is set to
|
|
<emphasis>continue</emphasis> by default. Under the default
|
|
Out-of-Memory policy, the entire service will be terminated if
|
|
any process is killed by the kernel OOM killer. By setting
|
|
the policy to <emphasis>continue</emphasis>, httpd will
|
|
continue to run (and recover) if a single child is terminated
|
|
because of excess memory consumption.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
See
|
|
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
and
|
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for more information.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Logging and log file rotation</title>
|
|
|
|
<para>The <command>httpd</command> daemon is configured to log
|
|
to the <filename>/var/log/httpd</filename> directory by default,
|
|
and a drop-in for <command>logrotate</command> is provided at
|
|
<filename>/etc/logrotate.d/httpd</filename> to enable log file
|
|
rotation. The <command>httpd.service</command> systemd unit is
|
|
reloaded after a <command>logrotate</command> run.</para>
|
|
|
|
<para>Log file compression is not enabled by default; since
|
|
<command>httpd</command> can continue writing to open log files
|
|
for some time after a reload (graceful restart), if compression
|
|
is enabled the <literal>delaycompress</literal> option must be
|
|
present (as in the default) to delay compression of log files to
|
|
a later rotation run.</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 a template
|
|
for creating instantiated services. 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 the
|
|
<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>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>,
|
|
<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>,
|
|
<citerefentry><refentrytitle>logrotate</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- LocalWords: systemd PidFile
|
|
-->
|