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