diff options
Diffstat (limited to 'httpd.service.xml')
| -rw-r--r-- | httpd.service.xml | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/httpd.service.xml b/httpd.service.xml new file mode 100644 index 0000000..4a6038d --- /dev/null +++ b/httpd.service.xml @@ -0,0 +1,338 @@ +<?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 +--> |