Apache HTTP Server Troubleshooting Notes
Field notes from working with the Apache HTTP Server: the commands to validate
a configuration before restarting, a common SSLSessionCache
misplacement error and its fix, how to read the error log, and the full
OpenSSL workflow for installing an SSL certificate and verifying it.
Common Commands
Syntax Check
- Command:
./httpd -t - Purpose: Validates the syntax of Apache configuration files without restarting the server.
- Benefits:
- Quickly identifies errors in configuration.
- Pinpoints the exact file and line number of the issue.
Additional Options
- Dump Virtual Hosts:
Lists all configured virtual hosts and their respective settings../httpd -t -D DUMP_VHOSTS - Dump Modules:
Displays all loaded Apache modules../httpd -t -D DUMP_MODULES - Dump Runtime Configuration:
Outputs the runtime configuration, useful for debugging../httpd -t -D DUMP_RUN_CFG
Issue Encountered: SSLSessionCache cannot occur within <VirtualHost>
Error Description
AH00526: Syntax error on line 209 of /path/to/httpd.conf:
SSLSessionCache cannot occur within <VirtualHost> section
Cause: The SSLSessionCache directive was placed
inside a <VirtualHost> block, which is not allowed. This
directive should be in the global context.
Resolution Steps
- Open the Apache configuration file for editing:
vim /path/to/httpd.conf - Locate the
SSLSessionCachedirective. - Move the directive outside of any
<VirtualHost>blocks, typically near the top of the configuration file. - Save and close the file.
- Validate the syntax:
./httpd -t - Restart the Apache server:
./httpd -k restart
Debugging Logs
Check the Error Log
- Command:
cat /path/to/apache/logs/error_log - Purpose: Provides detailed error messages and logs related to server operations.
Example logs:
[Fri Jan 10 11:42:11.283516 2025] [ssl:warn] [pid 21313:tid 21313] AH01873: Init: Session Cache is not configured [hint: SSLSessionCache]
[Fri Jan 10 12:27:21.218230 2025] [mpm_event:notice] [pid 21414:tid 21414] AH00491: caught SIGTERM, shutting down
Key Warnings and Notices
- AH01873: Warning — Session Cache is not configured. Hint: ensure
SSLSessionCacheis configured in the global context. - AH00491: Notice — the server received a signal to terminate (e.g.,
SIGTERM).
Tips for Future Troubleshooting
- Always use
httpd -tafter making configuration changes. - Check logs regularly for warnings or errors.
- Keep configuration directives in the appropriate context (global vs.
<VirtualHost>).
SSL Certificate Creation and Validation
1. Generate a New Private Key
To generate a new private key using OpenSSL:
openssl genrsa -out /opt/apache/key/enum_example_com.key 2048
2. Create a New CSR (Certificate Signing Request)
openssl req -new -key /opt/apache/key/enum_example_com.key -out /opt/apache/key/enum_example_com.csr
3. Submit the CSR to a Certificate Authority (CA)
Once the CSR is generated, submit it to your Certificate Authority (CA) of choice (e.g., Let's Encrypt, DigiCert) to obtain a signed certificate. The CA will provide:
.crtfile: this is the signed certificate..chainor.intermediatecertificate file (optional): this is the intermediate certificate that links your certificate to the CA's root certificate.
Example — after submitting the CSR you receive files like:
enum_example_com.crt(signed certificate)enum_example_com_chain.crt(intermediate certificate)
4. Install the SSL Certificate
Edit the Apache configuration to include the following:
SSLEngine On
SSLCertificateFile /opt/apache/key/enum_example_com.crt
SSLCertificateKeyFile /opt/apache/key/enum_example_com.key
SSLCertificateChainFile /opt/apache/key/enum_example_com_chain.crt
Steps to Verify HTTPS Certificate and Redirection
- Verify the HTTPS certificate. Run the following command to check the HTTPS certificate:
curl -ikv https://localhostNote: replace
localhostwith the correct endpoint based on your environment (development or production). curl -ikv http://localhostchecks how the server responds to HTTP requests.curl -L http://localhostfollows any HTTP-to-HTTPS redirections.
Expected Results
- The certificate details (Subject, Issuer, Validity period) should be displayed.
- A warning might appear if using a self-signed certificate, which is acceptable if intentional.
- The server should respond with a "301 Moved Permanently" or "302 Found" status code, indicating a redirection to HTTPS.
- The request should follow the redirection to the HTTPS URL.