Menu Close
Chapter 1. Setting up the Apache HTTP web server
1.1. Introduction to the Apache HTTP web server
A web server is a network service that serves content to a client over the web. This typically means web pages, but any other documents can be served as well. Web servers are also known as HTTP servers, as they use the hypertext transport protocol (HTTP).
The Apache HTTP Server, httpd
, is an open source web server developed by the Apache Software Foundation.
If you are upgrading from a previous release of Red Hat Enterprise Linux, you have to update the httpd
service configuration accordingly. This section reviews some of the newly added features, and guides you through the update of prior configuration files.
1.2. Notable changes in the Apache HTTP Server
RHEL 9 provides version 2.4.48 of the Apache HTTP Server. Notable changes over version 2.4.37 distributed with RHEL 8 include:
Apache HTTP Server Control Interface (
apachectl
):-
The
systemctl
pager is now disabled forapachectl status
output. -
The
apachectl
command now fails instead of giving a warning if you pass additional arguments. -
The
apachectl graceful-stop
command now returns immediately. -
The
apachectl configtest
command now executes thehttpd -t
command without changing the SELinux context. -
The
apachectl(8)
man page in RHEL now fully documents differences from upstreamapachectl
.
-
The
Apache eXtenSion tool (
apxs
):-
The
/usr/bin/apxs
command no longer uses or exposes compiler optimisation flags as applied when building thehttpd
package. You can now use the/usr/lib64/httpd/build/vendor-apxs
command to apply the same compiler flags as used to buildhttpd
. To use thevendor-apxs
command, you must install theredhat-rpm-config
package first.
-
The
Apache modules:
-
The
mod_lua
module is now provided in a separate package.
-
The
Configuration syntax changes:
-
In the deprecated
Allow
directive provided by themod_access_compat
module, a comment (the#
character) now triggers a syntax error instead of being silently ignored.
-
In the deprecated
Other changes:
- Kernel thread IDs are now used directly in error log messages, making them both accurate and more concise.
- Many minor enhancements and bug fixes.
- A number of new interfaces are available to module authors.
There are no backwards-incompatible changes to the httpd
module API since RHEL 8.
Apache HTTP Server 2.4 is the initial version of this Application Stream, which you can install easily as an RPM package.
1.3. The Apache configuration files
When the httpd
service is started, by default, it reads the configuration from locations that are listed in Table 1.1, “The httpd service configuration files”.
Table 1.1. The httpd service configuration files
Path | Description |
---|---|
| The main configuration file. |
| An auxiliary directory for configuration files that are included in the main configuration file. |
| An auxiliary directory for configuration files which load installed dynamic modules packaged in Red Hat Enterprise Linux. In the default configuration, these configuration files are processed first. |
Although the default configuration is suitable for most situations, you can use also other configuration options. For any configuration changes to take effect, restart the web server. See Section 1.4, “Managing the httpd service” for more information on how to restart the httpd
service.
To check the configuration for possible errors, type the following at a shell prompt:
# apachectl configtest
Syntax OK
To make the recovery from mistakes easier, make a copy of the original file before editing it.
1.4. Managing the httpd service
This section describes how to start, stop, and restart the httpd
service.
Prerequisites
- The Apache HTTP Server is installed.
Procedure
To start the
httpd
service, enter:# systemctl start httpd
To stop the
httpd
service, enter:# systemctl stop httpd
To restart the
httpd
service, enter:# systemctl restart httpd
1.5. Setting up a single-instance Apache HTTP Server
This section describes how to set up a single-instance Apache HTTP Server to serve static HTML content.
Follow the procedure in this section if the web server should provide the same content for all domains associated with the server. If you want to provide different content for different domains, set up name-based virtual hosts. For details, see Configuring Apache name-based virtual hosts.
Procedure
Install the
httpd
package:# dnf install httpd
Open the TCP port
80
in the local firewall:# firewall-cmd --permanent --add-port=80/tcp # firewall-cmd --reload
Enable and start the
httpd
service:# systemctl enable --now httpd
Optional: Add HTML files to the
/var/www/html/
directory.NoteWhen adding content to
/var/www/html/
, files and directories must be readable by the user under whichhttpd
runs by default. The content owner can be the either theroot
user androot
user group, or another user or group of the administrator’s choice. If the content owner is theroot
user androot
user group, the files must be readable by other users. The SELinux context for all the files and directories must behttpd_sys_content_t
, which is applied by default to all content within the/var/www
directory.
Verification steps
Connect with a web browser to
http://server_IP_or_host_name/
.If the
/var/www/html/
directory is empty or does not contain anindex.html
orindex.htm
file, Apache displays theRed Hat Enterprise Linux Test Page
. If/var/www/html/
contains HTML files with a different name, you can load them by entering the URL to that file, such ashttp://server_IP_or_host_name/example.html
.
Additional resources
- Refer to the Apache manual. See Installing the Apache HTTP Server manual.
-
See the
httpd.service(8)
man page.
1.6. Configuring Apache name-based virtual hosts
Name-based virtual hosts enable Apache to serve different content for different domains that resolve to the IP address of the server.
The procedure in this section describes setting up a virtual host for both the example.com
and example.net
domain with separate document root directories. Both virtual hosts serve static HTML content.
Prerequisites
Clients and the web server resolve the
example.com
andexample.net
domain to the IP address of the web server.Note that you must manually add these entries to your DNS server.
Procedure
Install the
httpd
package:# dnf install httpd
Edit the
/etc/httpd/conf/httpd.conf
file:Append the following virtual host configuration for the
example.com
domain:<VirtualHost *:80> DocumentRoot "/var/www/example.com/" ServerName example.com CustomLog /var/log/httpd/example.com_access.log combined ErrorLog /var/log/httpd/example.com_error.log </VirtualHost>
These settings configure the following:
-
All settings in the
<VirtualHost *:80>
directive are specific for this virtual host. -
DocumentRoot
sets the path to the web content of the virtual host. ServerName
sets the domains for which this virtual host serves content.To set multiple domains, add the
ServerAlias
parameter to the configuration and specify the additional domains separated with a space in this parameter.-
CustomLog
sets the path to the access log of the virtual host. ErrorLog
sets the path to the error log of the virtual host.NoteApache uses the first virtual host found in the configuration also for requests that do not match any domain set in the
ServerName
andServerAlias
parameters. This also includes requests sent to the IP address of the server.
-
All settings in the
Append a similar virtual host configuration for the
example.net
domain:<VirtualHost *:80> DocumentRoot "/var/www/example.net/" ServerName example.net CustomLog /var/log/httpd/example.net_access.log combined ErrorLog /var/log/httpd/example.net_error.log </VirtualHost>
Create the document roots for both virtual hosts:
# mkdir /var/www/example.com/ # mkdir /var/www/example.net/
If you set paths in the
DocumentRoot
parameters that are not within/var/www/
, set thehttpd_sys_content_t
context on both document roots:# semanage fcontext -a -t httpd_sys_content_t "/srv/example.com(/.*)?" # restorecon -Rv /srv/example.com/ # semanage fcontext -a -t httpd_sys_content_t "/srv/example.net(/.\*)?" # restorecon -Rv /srv/example.net/
These commands set the
httpd_sys_content_t
context on the/srv/example.com/
and/srv/example.net/
directory.Note that you must install the
policycoreutils-python-utils
package to run therestorecon
command.Open port
80
in the local firewall:# firewall-cmd --permanent --add-port=80/tcp # firewall-cmd --reload
Enable and start the
httpd
service:# systemctl enable --now httpd
Verification steps
Create a different example file in each virtual host’s document root:
# echo "vHost example.com" > /var/www/example.com/index.html # echo "vHost example.net" > /var/www/example.net/index.html
-
Use a browser and connect to
http://example.com
. The web server shows the example file from theexample.com
virtual host. -
Use a browser and connect to
http://example.net
. The web server shows the example file from theexample.net
virtual host.
Additional resources
-
For further details about configuring Apache virtual hosts, refer to the
Virtual Hosts
documentation in the Apache manual. For details about installing the manual, see Section 1.10, “Installing the Apache HTTP Server manual”.
1.7. Configuring Kerberos authentication for the Apache HTTP web server
To perform Kerberos authentication in the Apache HTTP web server, RHEL 9 uses the mod_auth_gssapi
Apache module. The Generic Security Services API (GSSAPI
) is an interface for applications that make requests to use security libraries, such as Kerberos. The gssproxy
service allows to implement privilege separation for the httpd
server, which optimizes this process from the security point of view.
The mod_auth_gssapi
module replaces the removed mod_auth_kerb
module.
Prerequisites
-
The
httpd
,mod_auth_gssapi
andgssproxy
packages are installed. -
The Apache web server is set up and the
httpd
service is running.
1.7.1. Setting up GSS-Proxy in an IdM environment
This procedure describes how to set up GSS-Proxy
to perform Kerberos authentication in the Apache HTTP web server.
Procedure
Enable access to the
keytab
file of HTTP/<SERVER_NAME>@realm principal by creating the service principal:# ipa service-add HTTP/<SERVER_NAME>
Retrieve the
keytab
for the principal stored in the/etc/gssproxy/http.keytab
file:# ipa-getkeytab -s $(awk '/^server =/ {print $3}' /etc/ipa/default.conf) -k /etc/gssproxy/http.keytab -p HTTP/$(hostname -f)
This step sets permissions to 400, thus only the
root
user has access to thekeytab
file. Theapache
user does not.Create the
/etc/gssproxy/80-httpd.conf
file with the following content:[service/HTTP] mechs = krb5 cred_store = keytab:/etc/gssproxy/http.keytab cred_store = ccache:/var/lib/gssproxy/clients/krb5cc_%U euid = apache
Restart and enable the
gssproxy
service:# systemctl restart gssproxy.service # systemctl enable gssproxy.service
Additional resources
-
For details about using or adjusting
GSS-Proxy
, see thegssproxy(8)
,gssproxy-mech(8)
andgssproxy.conf(5)
man pages.
1.7.2. Configuring Kerberos authentication for a directory shared by the Apache HTTP web server
This procedure describes how to configure Kerberos authentication for the /var/www/html/private/
directory.
Prerequisites
-
The
gssproxy
service is configured and running.
Procedure
Configure the
mod_auth_gssapi
module to protect the/var/www/html/private/
directory:<Location /var/www/html/private> AuthType GSSAPI AuthName "GSSAPI Login" Require valid-user </Location>
Create the
/etc/systemd/system/httpd.service
file with the following content:.include /lib/systemd/system/httpd.service [Service] Environment=GSS_USE_PROXY=1
Reload the
systemd
configuration:# systemctl daemon-reload
Restart the
httpd
service:# systemctl restart httpd.service
Verification steps
Obtain a Kerberos ticket:
# kinit
- Open the URL to the protected directory in a browser.
1.8. Configuring TLS encryption on an Apache HTTP Server
By default, Apache provides content to clients using an unencrypted HTTP connection. This section describes how to enable TLS encryption and configure frequently used encryption-related settings on an Apache HTTP Server.
Prerequisites
- The Apache HTTP Server is installed and running.
1.8.1. Adding TLS encryption to an Apache HTTP Server
This section describes how to enable TLS encryption on an Apache HTTP Server for the example.com
domain.
Prerequisites
- The Apache HTTP Server is installed and running.
The private key is stored in the
/etc/pki/tls/private/example.com.key
file.For details about creating a private key and certificate signing request (CSR), as well as how to request a certificate from a certificate authority (CA), see your CA’s documentation. Alternatively, if your CA supports the ACME protocol, you can use the
mod_md
module to automate retrieving and provisioning TLS certificates.-
The TLS certificate is stored in the
/etc/pki/tls/certs/example.com.crt
file. If you use a different path, adapt the corresponding steps of the procedure. -
The CA certificate is stored in the
/etc/pki/tls/certs/ca.crt
file. If you use a different path, adapt the corresponding steps of the procedure. - Clients and the web server resolve the host name of the server to the IP address of the web server.
Procedure
Install the
mod_ssl
package:# dnf install mod_ssl
Edit the
/etc/httpd/conf.d/ssl.conf
file and add the following settings to the<VirtualHost _default_:443>
directive:Set the server name:
ServerName example.com
ImportantThe server name must match the entry set in the
Common Name
field of the certificate.Optional: If the certificate contains additional host names in the
Subject Alt Names
(SAN) field, you can configuremod_ssl
to provide TLS encryption also for these host names. To configure this, add theServerAliases
parameter with corresponding names:ServerAlias www.example.com server.example.com
Set the paths to the private key, the server certificate, and the CA certificate:
SSLCertificateKeyFile "/etc/pki/tls/private/example.com.key" SSLCertificateFile "/etc/pki/tls/certs/example.com.crt" SSLCACertificateFile "/etc/pki/tls/certs/ca.crt"
For security reasons, configure that only the
root
user can access the private key file:# chown root:root /etc/pki/tls/private/example.com.key # chmod 600 /etc/pki/tls/private/example.com.key
WarningIf the private key was accessed by unauthorized users, revoke the certificate, create a new private key, and request a new certificate. Otherwise, the TLS connection is no longer secure.
Open port
443
in the local firewall:# firewall-cmd --permanent --add-port=443/tcp # firewall-cmd --reload
Restart the
httpd
service:# systemctl restart httpd
NoteIf you protected the private key file with a password, you must enter this password each time when the
httpd
service starts.
Verification steps
-
Use a browser and connect to
https://example.com
.
Additional resources
-
Refer to the
SSL/TLS Encryption
documentation in the Apache manual. - See Installing the Apache HTTP Server manual.
- Security considerations for TLS in RHEL 9
1.8.2. Setting the supported TLS protocol versions on an Apache HTTP Server
By default, the Apache HTTP Server on RHEL uses the system-wide crypto policy that defines safe default values, which are also compatible with recent browsers. For example, the DEFAULT
policy defines that only the TLSv1.2
and TLSv1.3
protocol versions are enabled in apache.
This section describes how to manually configure which TLS protocol versions your Apache HTTP Server supports. Follow the procedure if your environment requires to enable only specific TLS protocol versions, for example:
-
If your environment requires that clients can also use the weak
TLS1
(TLSv1.0) orTLS1.1
protocol. -
If you want to configure that Apache only supports the
TLSv1.2
orTLSv1.3
protocol.
Prerequisites
- TLS encryption is enabled on the server as described in Adding TLS encryption to an Apache HTTP Server.
Procedure
Edit the
/etc/httpd/conf/httpd.conf
file, and add the following setting to the<VirtualHost>
directive for which you want to set the TLS protocol version. For example, to enable only theTLSv1.3
protocol:SSLProtocol -All TLSv1.3
Restart the
httpd
service:# systemctl restart httpd
Verification steps
Use the following command to verify that the server supports
TLSv1.3
:# openssl s_client -connect example.com:443 -tls1_3
Use the following command to verify that the server does not support
TLSv1.2
:# openssl s_client -connect example.com:443 -tls1_2
If the server does not support the protocol, the command returns an error:
140111600609088:error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version:ssl/record/rec_layer_s3.c:1543:SSL alert number 70
- Optional: Repeat the command for other TLS protocol versions.
Additional resources
-
See the
update-crypto-policies(8)
man page. - See Using system-wide cryptographic policies.
-
For details about the
SSLProtocol
parameter, see themod_ssl
documentation in the Apache manual. - See Installing the Apache HTTP Server manual.
1.8.3. Setting the supported ciphers on an Apache HTTP Server
By default, the Apache HTTP Server uses the system-wide crypto policy that defines safe default values, which are also compatible with recent browsers. For the list of ciphers the system-wide crypto allows, see the /etc/crypto-policies/back-ends/openssl.config
file.
This section describes how to manually configure which ciphers your Apache HTTP Server supports. Follow the procedure if your environment requires specific ciphers.
Prerequisites
- TLS encryption is enabled on the server as described in Adding TLS encryption to an Apache HTTP Server.
Procedure
Edit the
/etc/httpd/conf/httpd.conf
file, and add theSSLCipherSuite
parameter to the<VirtualHost>
directive for which you want to set the TLS ciphers:SSLCipherSuite "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH:!SHA1:!SHA256"
This example enables only the
EECDH+AESGCM
,EDH+AESGCM
,AES256+EECDH
, andAES256+EDH
ciphers and disables all ciphers which use theSHA1
andSHA256
message authentication code (MAC).Restart the
httpd
service:# systemctl restart httpd
Verification steps
To display the list of ciphers the Apache HTTP Server supports:
Install the
nmap
package:# dnf install nmap
Use the
nmap
utility to display the supported ciphers:# nmap --script ssl-enum-ciphers -p 443 example.com ... PORT STATE SERVICE 443/tcp open https | ssl-enum-ciphers: | TLSv1.2: | ciphers: | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (ecdh_x25519) - A | TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 (dh 2048) - A | TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (ecdh_x25519) - A ...
Additional resources
-
See the
update-crypto-policies(8)
man page. - See Using system-wide cryptographic policies.
-
For details about the
SSLCipherSuite
parameter, see themod_ssl
documentation in the Apache manual. - See Installing the Apache HTTP Server manual.
1.9. Configuring TLS client certificate authentication
Client certificate authentication enables administrators to allow only users who authenticate using a certificate to access resources on the web server. This section describes how to configure client certificate authentication for the /var/www/html/Example/
directory.
If the Apache HTTP Server uses the TLS 1.3 protocol, certain clients require additional configuration. For example, in Firefox, set the security.tls.enable_post_handshake_auth
parameter in the about:config
menu to true
. For further details, see Transport Layer Security version 1.3 in Red Hat Enterprise Linux 8.
Prerequisites
- TLS encryption is enabled on the server as described in Adding TLS encryption to an Apache HTTP Server.
Procedure
Edit the
/etc/httpd/conf/httpd.conf
file and add the following settings to the<VirtualHost>
directive for which you want to configure client authentication:<Directory "/var/www/html/Example/"> SSLVerifyClient require </Directory>
The
SSLVerifyClient require
setting defines that the server must successfully validate the client certificate before the client can access the content in the/var/www/html/Example/
directory.Restart the
httpd
service:# systemctl restart httpd
Verification steps
Use the
curl
utility to access thehttps://example.com/Example/
URL without client authentication:$ curl https://example.com/Example/ curl: (56) OpenSSL SSL_read: error:1409445C:SSL routines:ssl3_read_bytes:tlsv13 **alert certificate required**, errno 0
The error indicates that the web server requires a client certificate authentication.
Pass the client private key and certificate, as well as the CA certificate to
curl
to access the same URL with client authentication:$ curl --cacert ca.crt --key client.key --cert client.crt https://example.com/Example/
If the request succeeds,
curl
displays theindex.html
file stored in the/var/www/html/Example/
directory.
Additional resources
-
See the
mod_ssl Configuration How-To
documentation in the Apache manual. - See Installing the Apache HTTP Server manual.
1.10. Installing the Apache HTTP Server manual
This section describes how to install the Apache HTTP Server manual. This manual provides a detailed documentation of, for example:
- Configuration parameters and directives
- Performance tuning
- Authentication settings
- Modules
- Content caching
- Security tips
- Configuring TLS encryption
After installing the manual, you can display it using a web browser.
Prerequisites
- The Apache HTTP Server is installed and running.
Procedure
Install the
httpd-manual
package:# dnf install httpd-manual
Optional: By default, all clients connecting to the Apache HTTP Server can display the manual. To restrict access to a specific IP range, such as the
192.0.2.0/24
subnet, edit the/etc/httpd/conf.d/manual.conf
file and add theRequire ip 192.0.2.0/24
setting to the<Directory "/usr/share/httpd/manual">
directive:<Directory "/usr/share/httpd/manual"> ... **Require ip 192.0.2.0/24** ... </Directory>
Restart the
httpd
service:# systemctl restart httpd
Verification steps
-
To display the Apache HTTP Server manual, connect with a web browser to
http://host_name_or_IP_address/manual/
1.11. Working with modules
Being a modular application, the httpd
service is distributed along with a number of Dynamic Shared Objects (DSOs), which can be dynamically loaded or unloaded at runtime as necessary. These modules are located in the /usr/lib64/httpd/modules/
directory.
1.11.1. Loading a module
To load a particular DSO module, use the LoadModule
directive. Note that modules provided by a separate package often have their own configuration file in the /etc/httpd/conf.modules.d/
directory.
Loading the mod_ssl DSO
LoadModule ssl_module modules/mod_ssl.so
After loading the module, restart the web server to reload the configuration. See Section 1.4, “Managing the httpd service” for more information on how to restart the httpd
service.
1.11.2. Writing a module
To create a new DSO module, make sure you have the httpd-devel
package installed. To do so, enter the following command as root
:
# dnf install httpd-devel
This package contains the include files, the header files, and the APache eXtenSion (apxs
) utility required to compile a module.
Once written, you can build the module with the following command:
# apxs -i -a -c module_name.c
If the build was successful, you should be able to load the module the same way as any other module that is distributed with the Apache HTTP Server.
1.12. Exporting a private key and certificates from an NSS database to use them in an Apache web server configuration
Since RHEL 8 we no longer provide the mod_nss
module for the Apache web server, and Red Hat recommends using the mod_ssl
module. If you store your private key and certificates in a Network Security Services (NSS) database, follow this procedure to extract the key and certificates in Privacy Enhanced Mail (PEM) format.
1.13. Additional resources
-
httpd(8)
— The manual page for thehttpd
service containing the complete list of its command-line options. -
httpd.service(8)
— The manual page for thehttpd.service
unit file, describing how to customize and enhance the service. -
httpd.conf(5)
— The manual page forhttpd
configuration, describing the structure and location of thehttpd
configuration files. -
apachectl(8)
— The manual page for the Apache HTTP Server Control Interface. - For information on how to configure Kerberos authentication on an Apache HTTP server, see Using GSS-Proxy for Apache httpd operation. Using Kerberos is an alternative way to enforce client authorization on an Apache HTTP Server.
- Configuring applications to use cryptographic hardware through PKCS #11.