| <?xml version='1.0' encoding='UTF-8' ?> |
| <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Copyright 2002-2005 The Apache Software Foundation or its licensors, as |
| applicable. |
| |
| Licensed 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. |
| --> |
| |
| <manualpage metafile="ssl_faq.xml.meta"> |
| <parentdocument href="./">SSL/TLS</parentdocument> |
| |
| <title>SSL/TLS Strong Encryption: FAQ</title> |
| |
| <summary> |
| <blockquote> |
| <p>The wise man doesn't give the right answers, |
| he poses the right questions.</p> |
| <p class="cite">-- <cite>Claude Levi-Strauss</cite></p> |
| |
| </blockquote> |
| <p>This chapter is a collection of frequently asked questions (FAQ) and |
| corresponding answers following the popular USENET tradition. Most of these |
| questions occurred on the Newsgroup <code><a href="news:comp.infosystems.www.servers.unix" |
| >comp.infosystems.www.servers.unix</a></code> or the mod_ssl Support |
| Mailing List <code><a href="mailto:modssl-users@modssl.org" |
| >modssl-users@modssl.org</a></code>. They are collected at this place |
| to avoid answering the same questions over and over.</p> |
| |
| <p>Please read this chapter at least once when installing mod_ssl or at least |
| search for your problem here before submitting a problem report to the |
| author.</p> |
| </summary> |
| |
| <section id="about"><title>About The Module</title> |
| <ul> |
| <li><a href="#history">What is the history of mod_ssl?</a></li> |
| <li><a href="#y2k">mod_ssl and Year 2000?</a></li> |
| <li><a href="#wassenaar">mod_ssl and Wassenaar Arrangement?</a></li> |
| </ul> |
| |
| <section id="history"><title>What is the history of mod_ssl?</title> |
| <p>The mod_ssl v1 package was initially created in April 1998 by <a |
| href="mailto:rse@engelschall.com">Ralf S. Engelschall</a> via porting <a |
| href="mailto:ben@algroup.co.uk">Ben Laurie</a>'s <a |
| href="http://www.apache-ssl.org/">Apache-SSL</a> 1.17 source patches for |
| Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben |
| Laurie's development cycle it then was re-assembled from scratch for |
| Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL |
| 1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The |
| first publicly released version was mod_ssl 2.0.0 from August 10th, |
| 1998. </p> |
| |
| <p>After US export restrictions on cryptographic software were |
| loosened, <module>mod_ssl</module> became part of the Apache HTTP |
| Server with the release of Apache httpd 2.</p> |
| </section> |
| |
| <section id="wassenaar"><title>Is mod_ssl affected by the Wassenaar Arrangement?</title> |
| <p>First, let us explain what <dfn>Wassenaar</dfn> and its <dfn>Arrangement on |
| Export Controls for Conventional Arms and Dual-Use Goods and |
| Technologies</dfn> is: This is a international regime, established in 1995, to |
| control trade in conventional arms and dual-use goods and technology. It |
| replaced the previous <dfn>CoCom</dfn> regime. Further details on |
| both the Arrangement and its signatories are available at <a |
| href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>.</p> |
| |
| <p>In short, the aim of the Wassenaar Arrangement is to prevent the build up |
| of military capabilities that threaten regional and international security |
| and stability. The Wassenaar Arrangement controls the export of |
| cryptography as a dual-use good, that is, something that has both military and |
| civilian applications. However, the Wassenaar Arrangement also provides an |
| exemption from export controls for mass-market software and free software.</p> |
| |
| <p>In the current Wassenaar <cite>List of Dual Use Goods and Technologies And |
| Munitions</cite>, under <q>GENERAL SOFTWARE NOTE (GSN)</q> it says |
| <q>The Lists do not control "software" which is either: 1. [...] 2. "in |
| the public domain".</q> And under <q>DEFINITIONS OF TERMS USED IN |
| THESE LISTS</q> we find <q>In the public |
| domain</q> defined as <q>"technology" or "software" which has been made |
| available without restrictions upon its further dissemination. Note: |
| Copyright restrictions do not remove "technology" or "software" from being |
| "in the public domain".</q></p> |
| |
| <p>So, both mod_ssl and OpenSSL are <q>in the public domain</q> for the purposes |
| of the Wassenaar Arrangement and its <q>List of Dual Use Goods and |
| Technologies And Munitions List</q>, and thus not affected by its provisions.</p> |
| |
| </section> |
| </section> |
| <!-- /about --> |
| |
| <section id="installation"><title>Installation</title> |
| <ul> |
| <li><a href="#mutex">Why do I get permission errors related to |
| SSLMutex when I start Apache?</a></li> |
| <li><a href="#entropy">Why does mod_ssl stop with the error "Failed to |
| generate temporary 512 bit RSA private key", when I start Apache?</a></li> |
| </ul> |
| |
| <section id="mutex"><title>Why do I get permission errors related to |
| SSLMutex when I start Apache?</title> |
| <p>Errors such as ``<code>mod_ssl: Child could not open |
| SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows) |
| [...] System: Permission denied (errno: 13)</code>'' are usually |
| caused by overly restrictive permissions on the <em>parent</em> directories. |
| Make sure that all parent directories (here <code>/opt</code>, |
| <code>/opt/apache</code> and <code>/opt/apache/logs</code>) have the x-bit |
| set for, at minimum, the UID under which Apache's children are running (see |
| the <directive module="mpm_common">User</directive> directive).</p> |
| </section> |
| |
| <section id="entropy"><title>Why does mod_ssl stop with the error |
| "Failed to generate temporary 512 bit RSA private key", when I start |
| Apache?</title> |
| <p>Cryptographic software needs a source of unpredictable data |
| to work correctly. Many open source operating systems provide |
| a "randomness device" that serves this purpose (usually named |
| <code>/dev/random</code>). On other systems, applications have to |
| seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with |
| appropriate data before generating keys or performing public key |
| encryption. As of version 0.9.5, the OpenSSL functions that need |
| randomness report an error if the PRNG has not been seeded with |
| at least 128 bits of randomness.</p> |
| <p>To prevent this error, <module>mod_ssl</module> has to provide |
| enough entropy to the PRNG to allow it to work correctly. This can |
| be done via the <directive module="mod_ssl">SSLRandomSeed</directive> |
| directives.</p> |
| </section> |
| </section> |
| <!-- /installation --> |
| |
| <section id="aboutconfig"><title>Configuration</title> |
| <ul> |
| <li><a href="#parallel">Is it possible to provide HTTP and HTTPS from |
| the same server?</a></li> |
| <li><a href="#ports">Which port does HTTPS use?</a></li> |
| <li><a href="#httpstest">How do I speak HTTPS manually for testing |
| purposes?</a></li> |
| <li><a href="#hang">Why does the connection hang when I connect to my |
| SSL-aware Apache server</a></li> |
| <li><a href="#refused">Why do I get ``Connection Refused'' errors, when |
| trying to access my newly installed Apache+mod_ssl server via HTTPS?</a></li> |
| <li><a href="#envvars">Why are the <code>SSL_XXX</code> variables not |
| available to my CGI & SSI scripts?</a></li> |
| <li><a href="#relative">How can I switch between HTTP and HTTPS in |
| relative hyperlinks?</a></li> |
| </ul> |
| |
| <section id="parallel"><title>Is it possible to provide HTTP and HTTPS |
| from the same server?</title> |
| <p>Yes. HTTP and HTTPS use different server ports (HTTP binds to |
| port 80, HTTPS to port 443), so there is no direct conflict between |
| them. You can either run two separate server instances bound to |
| these ports, or use Apache's elegant virtual hosting facility to |
| create two virtual servers over one instance of Apache - one |
| responding to requests on port 80 and speaking HTTP and the other |
| responding to requests on port 443 speaking HTTPS.</p> |
| </section> |
| |
| <section id="ports"><title>Which port does HTTPS use?</title> |
| <p>You can run HTTPS on any port, but the standards specify port 443, which |
| is where any HTTPS compliant browser will look by default. You can force |
| your browser to look on a different port by specifying it in the URL like |
| this (for port 666): <code>https://secure.server.dom:666/</code></p> |
| </section> |
| |
| <section id="httpstest"><title>How do I speak HTTPS manually for testing purposes?</title> |
| <p>While you usually just use</p> |
| |
| <example>$ telnet localhost 80<br /> |
| GET / HTTP/1.0</example> |
| |
| <p>for simple testing of Apache via HTTP, it's not so easy for |
| HTTPS because of the SSL protocol between TCP and HTTP. With the |
| help of OpenSSL's <code>s_client</code> command, however, you can |
| do a similar check for HTTPS:</p> |
| |
| <example>$ openssl s_client -connect localhost:443 -state -debug<br /> |
| GET / HTTP/1.0</example> |
| |
| <p>Before the actual HTTP response you will receive detailed |
| information about the SSL handshake. For a more general command |
| line client which directly understands both HTTP and HTTPS, can |
| perform GET and POST operations, can use a proxy, supports byte |
| ranges, etc. you should have a look at the nifty |
| <a href="http://curl.haxx.se/">cURL</a> tool. Using this, you can |
| check that Apache is responding correctly on ports 80 and 443 as |
| follows:</p> |
| |
| <example>$ curl http://localhost/<br /> |
| $ curl https://localhost/</example> |
| </section> |
| |
| <section id="hang"><title>Why does the connection hang when I connect |
| to my SSL-aware Apache server?</title> |
| <p>Because you connected with HTTP to the HTTPS port, i.e. you used an URL of |
| the form ``<code>http://</code>'' instead of ``<code>https://</code>''. |
| This also happens the other way round when you connect via HTTPS to a HTTP |
| port, i.e. when you try to use ``<code>https://</code>'' on a server that |
| doesn't support SSL (on this port). Make sure you are connecting to a |
| virtual server that supports SSL, which is probably the IP associated with |
| your hostname, not localhost (127.0.0.1).</p> |
| </section> |
| |
| <section id="refused"><title>Why do I get ``Connection Refused'' messages, |
| when trying to access my newly installed Apache+mod_ssl server via HTTPS?</title> |
| <p>This can happen for various reasons. The most common mistakes |
| include starting Apache with just <code>apachectl start</code> (or |
| <program>httpd</program>) instead of <code>apachectl startssl</code> (or |
| <code>httpd -DSSL</code>). Your configuration may also be incorrect. |
| Please make sure that your <directive module="mpm_common" |
| >Listen</directive> directives match your |
| <directive type="section" module="core">VirtualHost</directive> |
| directives. If all else fails, please start afresh, using the default |
| configuration provided by <module>mod_ssl</module>.</p> |
| </section> |
| |
| <section id="envvars"><title>Why are the <code>SSL_XXX</code> variables |
| not available to my CGI & SSI scripts?</title> |
| <p>Please make sure you have ``<code>SSLOptions +StdEnvVars</code>'' |
| enabled for the context of your CGI/SSI requests.</p> |
| </section> |
| |
| <section id="relative"> |
| <title>How can I switch between HTTP and HTTPS in relative |
| hyperlinks?</title> |
| <p>Usually, to switch between HTTP and HTTPS, you have to use |
| fully-qualified hyperlinks (because you have to change the URL |
| scheme). Using <module>mod_rewrite</module> however, you can |
| manipulate relative hyperlinks, to achieve the same effect.</p> |
| <example> |
| RewriteEngine on<br /> |
| RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L]<br /> |
| RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L] |
| </example> |
| |
| <p>This rewrite ruleset lets you use hyperlinks of the form |
| <code><a href="document.html:SSL"></code>, to switch to HTTPS |
| in a relative link.</p> |
| </section> |
| </section> |
| <!-- configuration --> |
| |
| <section id="aboutcerts"><title>Certificates</title> |
| <ul> |
| <li><a href="#keyscerts">What are RSA Private Keys, CSRs and |
| Certificates?</a></li> |
| <li><a href="#startup">Is there a difference on startup between |
| the original Apache and an SSL-aware Apache?</a></li> |
| <li><a href="#selfcert">How do I create a self-signed SSL |
| Certificate for testing purposes?</a></li> |
| <li><a href="#realcert">How do I create a real SSL Certificate?</a></li> |
| <li><a href="#ownca">How do I create and use my own Certificate |
| Authority (CA)?</a></li> |
| <li><a href="#passphrase">How can I change the pass-phrase on my private |
| key file?</a></li> |
| <li><a href="#removepassphrase">How can I get rid of the pass-phrase |
| dialog at Apache startup time?</a></li> |
| <li><a href="#verify">How do I verify that a private key matches its |
| Certificate?</a></li> |
| <li><a href="#badcert">Why do connections fail with an "alert bad |
| certificate" error?</a></li> |
| <li><a href="#keysize">Why does my 2048-bit private key not work?</a></li> |
| <li><a href="#hashsymlinks">Why is client authentication broken after |
| upgrading from SSLeay version 0.8 to 0.9?</a></li> |
| <li><a href="#pemder">How can I convert a certificate from PEM to DER |
| format?</a></li> |
| <li><a href="#verisign">Why can't I find the |
| <code>getca</code> or <code>getverisign</code> programs mentioned by |
| Verisign, for installing my Verisign certificate?</a></li> |
| <li><a href="#sgc">Can I use the Server Gated Cryptography (SGC) |
| facility (aka Verisign Global ID) with mod_ssl?</a></li> |
| <li><a href="#gid">Why do browsers complain that they cannot |
| verify my Verisign Global ID server certificate?</a></li> |
| </ul> |
| |
| <section id="keyscerts"><title>What are RSA Private Keys, CSRs and Certificates?</title> |
| <p>An RSA private key file is a digital file that you can use to decrypt |
| messages sent to you. It has a public component which you distribute (via |
| your Certificate file) which allows people to encrypt those messages to |
| you.</p> |
| <p>A Certificate Signing Request (CSR) is a digital file which contains |
| your public key and your name. You send the CSR to a Certifying Authority |
| (CA), who will convert it into a real Certificate, by signing it.</p> |
| <p>A Certificate contains your |
| RSA public key, your name, the name of the CA, and is digitally signed by |
| the CA. Browsers that know the CA can verify the signature on that |
| Certificate, thereby obtaining your RSA public key. That enables them to |
| send messages which only you can decrypt.</p> |
| <p>See the <a href="ssl_intro.html">Introduction</a> chapter for a general |
| description of the SSL protocol.</p> |
| </section> |
| |
| <section id="startup"><title>Is there a difference on startup between |
| the original Apache and an SSL-aware Apache?</title> |
| <p>Yes. In general, starting Apache with |
| <module>mod_ssl</module> built-in is just like starting Apache |
| without it. However, if you have a passphrase on your SSL private |
| key file, a startup dialog will pop up which asks you to enter the |
| pass phrase.</p> |
| |
| <p>Having to manually enter the passphrase when starting the server |
| can be problematic - for example, when starting the server from the |
| system boot scripts. In this case, you can follow the steps |
| <a href="#removepassphrase">below</a> to remove the passphrase from |
| your private key.</p> |
| </section> |
| |
| <section id="selfcert"><title>How do I create a self-signed SSL |
| Certificate for testing purposes?</title> |
| <ol> |
| <li>Make sure OpenSSL is installed and in your <code>PATH</code>.<br /> |
| <br /> |
| </li> |
| <li>Run the following command, to create <code>server.key</code> and |
| <code>server.crt</code> files:<br /> |
| <code><strong>$ openssl req -new -x509 -nodes -out server.crt |
| -keyout server.key</strong></code><br /> |
| These can be used as follows in your <code>httpd.conf</code> |
| file: |
| <pre> |
| SSLCertificateFile /path/to/this/server.crt |
| SSLCertificateKeyFile /path/to/this/server.key |
| </pre> |
| </li> |
| <li>It is important that you are aware that this |
| <code>server.key</code> does <em>not</em> have any passphrase. |
| To add a passphrase to the key, you should run the following |
| command, and enter & verify the passphrase as requested.<br /> |
| <p><code><strong>$ openssl rsa -des3 -in server.key -out |
| server.key.new</strong></code><br /> |
| <code><strong>$ mv server.key.new server.key</strong></code><br /></p> |
| Please backup the <code>server.key</code> file, and the passphrase |
| you entered, in a secure location. |
| </li> |
| </ol> |
| </section> |
| |
| <section id="realcert"><title>How do I create a real SSL Certificate?</title> |
| <p>Here is a step-by-step description:</p> |
| <ol> |
| <li>Make sure OpenSSL is installed and in your <code>PATH</code>. |
| <br /> |
| <br /> |
| </li> |
| <li>Create a RSA private key for your Apache server |
| (will be Triple-DES encrypted and PEM formatted):<br /> |
| <br /> |
| <code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code><br /> |
| <br /> |
| Please backup this <code>server.key</code> file and the |
| pass-phrase you entered in a secure location. |
| You can see the details of this RSA private key by using the command:<br /> |
| |
| <br /> |
| <code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br /> |
| <br /> |
| If necessary, you can also create a decrypted PEM version (not |
| recommended) of this RSA private key with:<br /> |
| <br /> |
| <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br /> |
| <br /> |
| |
| </li> |
| <li>Create a Certificate Signing Request (CSR) with the server RSA private |
| key (output will be PEM formatted):<br /> |
| <br /> |
| <code><strong>$ openssl req -new -key server.key -out server.csr</strong></code><br /> |
| <br /> |
| Make sure you enter the FQDN ("Fully Qualified Domain Name") of the |
| server when OpenSSL prompts you for the "CommonName", i.e. when you |
| generate a CSR for a website which will be later accessed via |
| <code>https://www.foo.dom/</code>, enter "www.foo.dom" here. |
| You can see the details of this CSR by using<br /> |
| |
| <br /> |
| <code><strong>$ openssl req -noout -text -in server.csr</strong></code><br /> |
| <br /> |
| </li> |
| <li>You now have to send this Certificate Signing Request (CSR) to |
| a Certifying Authority (CA) to be signed. Once the CSR has been |
| signed, you will have a real Certificate, which can be used by |
| Apache. You can have a CSR signed by a commercial CA, or you can |
| create your own CA to sign it.<br /> |
| Commercial CAs usually ask you to post the CSR into a web form, |
| pay for the signing, and then send a signed Certificate, which |
| you can store in a server.crt file. For more information about |
| commercial CAs see the following locations:<br /> |
| <br /> |
| <ol> |
| <li> Verisign<br /> |
| <a href="http://digitalid.verisign.com/server/apacheNotice.htm"> |
| http://digitalid.verisign.com/server/apacheNotice.htm |
| </a> |
| </li> |
| <li> Thawte<br /> |
| <a href="http://www.thawte.com/">http://www.thawte.com/</a> |
| </li> |
| <li> CertiSign Certificadora Digital Ltda.<br /> |
| <a href="http://www.certisign.com.br"> |
| http://www.certisign.com.br |
| </a> |
| </li> |
| <li> IKS GmbH<br /> |
| <a href="http://www.iks-jena.de/leistungen/ca/"> |
| http://www.iks-jena.de/leistungen/ca/ |
| </a> |
| </li> |
| <li> Uptime Commerce Ltd.<br /> |
| <a href="http://www.uptimecommerce.com"> |
| http://www.uptimecommerce.com |
| </a> |
| </li> |
| <li> BelSign NV/SA<br /> |
| <a href="http://www.belsign.be"> |
| http://www.belsign.be |
| </a> |
| </li> |
| </ol> |
| |
| For details on how to create your own CA, and use this to sign |
| a CSR, see <a href="#ownca">below</a>.<br /> |
| |
| Once your CSR has been signed, you can see the details of the |
| Certificate as follows:<br /> |
| <br /> |
| <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br /> |
| |
| </li> |
| <li>You should now have two files: <code>server.key</code> and |
| <code>server.crt</code>. These can be used as follows in your |
| <code>httpd.conf</code> file: |
| <pre> |
| SSLCertificateFile /path/to/this/server.crt |
| SSLCertificateKeyFile /path/to/this/server.key |
| </pre> |
| The <code>server.csr</code> file is no longer needed. |
| </li> |
| |
| </ol> |
| </section> |
| |
| <section id="ownca"><title>How do I create and use my own Certificate Authority (CA)?</title> |
| <p>The short answer is to use the <code>CA.sh</code> or <code>CA.pl</code> |
| script provided by OpenSSL. Unless you have a good reason not to, |
| you should use these for preference. If you cannot, you can create a |
| self-signed Certificate as follows:</p> |
| |
| <ol> |
| <li>Create a RSA private key for your server |
| (will be Triple-DES encrypted and PEM formatted):<br /> |
| <br /> |
| <code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code><br /> |
| <br /> |
| Please backup this <code>host.key</code> file and the |
| pass-phrase you entered in a secure location. |
| You can see the details of this RSA private key by using the |
| command:<br /> |
| <code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br /> |
| <br /> |
| If necessary, you can also create a decrypted PEM version (not |
| recommended) of this RSA private key with:<br /> |
| <br /> |
| <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br /> |
| <br /> |
| </li> |
| <li>Create a self-signed Certificate (X509 structure) |
| with the RSA key you just created (output will be PEM formatted):<br /> |
| <br /> |
| <code><strong>$ openssl req -new -x509 -nodes -sha1 -days 365 |
| -key server.key -out server.crt</strong></code><br /> |
| <br /> |
| This signs the server CSR and results in a <code>server.crt</code> file.<br /> |
| You can see the details of this Certificate using:<br /> |
| <br /> |
| <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br /> |
| <br /> |
| </li> |
| </ol> |
| </section> |
| |
| <section id="passphrase"><title>How can I change the pass-phrase on my private key file?</title> |
| <p>You simply have to read it with the old pass-phrase and write it again, |
| specifying the new pass-phrase. You can accomplish this with the following |
| commands:</p> |
| |
| |
| <p><code><strong>$ openssl rsa -des3 -in server.key -out server.key.new</strong></code><br /> |
| <code><strong>$ mv server.key.new server.key</strong></code><br /></p> |
| |
| <p>The first time you're asked for a PEM pass-phrase, you should |
| enter the old pass-phrase. After that, you'll be asked again to |
| enter a pass-phrase - this time, use the new pass-phrase. If you |
| are asked to verify the pass-phrase, you'll need to enter the new |
| pass-phrase a second time.</p> |
| </section> |
| |
| <section id="removepassphrase"><title>How can I get rid of the pass-phrase dialog at Apache startup time?</title> |
| <p>The reason this dialog pops up at startup and every re-start |
| is that the RSA private key inside your server.key file is stored in |
| encrypted format for security reasons. The pass-phrase is needed decrypt |
| this file, so it can be read and parsed. Removing the pass-phrase |
| removes a layer of security from your server - proceed with caution!</p> |
| <ol> |
| <li>Remove the encryption from the RSA private key (while |
| keeping a backup copy of the original file):<br /> |
| <br /> |
| <code><strong>$ cp server.key server.key.org</strong></code><br /> |
| <code><strong>$ openssl rsa -in server.key.org -out server.key</strong></code><br /> |
| |
| <br /> |
| </li> |
| <li>Make sure the server.key file is only readable by root:<br /> |
| <br /> |
| <code><strong>$ chmod 400 server.key</strong></code><br /> |
| <br /> |
| </li> |
| </ol> |
| |
| <p>Now <code>server.key</code> contains an unencrypted copy of the key. |
| If you point your server at this file, it will not prompt you for a |
| pass-phrase. HOWEVER, if anyone gets this key they will be able to |
| impersonate you on the net. PLEASE make sure that the permissions on this |
| file are such that only root or the web server user can read it |
| (preferably get your web server to start as root but run as another |
| user, and have the key readable only by root).</p> |
| |
| <p>As an alternative approach you can use the ``<code>SSLPassPhraseDialog |
| exec:/path/to/program</code>'' facility. Bear in mind that this is |
| neither more nor less secure, of course.</p> |
| </section> |
| |
| <section id="verify"><title>How do I verify that a private key matches its Certificate?</title> |
| <p>A private key contains a series of numbers. Two of these numbers form |
| the "public key", the others are part of the "private key". The "public |
| key" bits are included when you generate a CSR, and subsequently form |
| part of the associated Certificate.</p> |
| <p>To check that the public key in your Certificate matches the public |
| portion of your private key, you simply need to compare these numbers. |
| To view the Certificate and the key run the commands:</p> |
| |
| <p><code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br /> |
| <code><strong>$ openssl rsa -noout -text -in server.key</strong></code></p> |
| |
| <p>The `modulus' and the `public exponent' portions in the key and the |
| Certificate must match. As the public exponent is usually 65537 |
| and it's difficult to visually check that the long modulus numbers |
| are the same, you can use the following approach:</p> |
| |
| <p><code><strong>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br /> |
| <code><strong>$ openssl rsa -noout -modulus -in server.key | openssl md5</strong></code></p> |
| |
| <p>This leaves you with two rather shorter numbers to compare. It is, |
| in theory, possible that these numbers may be the same, without the |
| modulus numbers being the same, but the chances of this are |
| overwhelmingly remote.</p> |
| <p>Should you wish to check to which key or certificate a particular |
| CSR belongs you can perform the same calculation on the CSR as |
| follows:</p> |
| |
| <p><code><strong>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code></p> |
| </section> |
| |
| <section id="badcert"><title>Why do connections fail with an "alert |
| bad certificate" error?</title> |
| <p>Errors such as <code>OpenSSL: error:14094412: SSL |
| routines:SSL3_READ_BYTES:sslv3 alert bad certificate</code> in the SSL |
| logfile, are usually caused a browser which is unable to handle the server |
| certificate/private-key. For example, Netscape Navigator 3.x is |
| unable to handle RSA key lengths not equal to 1024 bits.</p> |
| </section> |
| |
| <section id="keysize"><title>Why does my 2048-bit private key not work?</title> |
| <p>The private key sizes for SSL must be either 512 or 1024 bits, for compatibility |
| with certain web browsers. A keysize of 1024 bits is recommended because |
| keys larger than 1024 bits are incompatible with some versions of Netscape |
| Navigator and Microsoft Internet Explorer, and with other browsers that |
| use RSA's BSAFE cryptography toolkit.</p> |
| </section> |
| |
| <section id="hashsymlinks"><title>Why is client authentication broken after upgrading from |
| SSLeay version 0.8 to 0.9?</title> |
| <p>The CA certificates under the path you configured with |
| <code>SSLCACertificatePath</code> are found by SSLeay through hash |
| symlinks. These hash values are generated by the `<code>openssl x509 -noout |
| -hash</code>' command. However, the algorithm used to calculate the hash for a |
| certificate changed between SSLeay 0.8 and 0.9. You will need to remove |
| all old hash symlinks and create new ones after upgrading. Use the |
| <code>Makefile</code> provided by <module>mod_ssl</module>.</p> |
| </section> |
| |
| <section id="pemder"><title>How can I convert a certificate from PEM to DER format?</title> |
| <p>The default certificate format for SSLeay/OpenSSL is PEM, which is simply |
| Base64 encoded DER, with header and footer lines. For some applications |
| (e.g. Microsoft Internet Explorer) you need the certificate in plain DER |
| format. You can convert a PEM file <code>cert.pem</code> into the |
| corresponding DER file <code>cert.der</code> using the following command: |
| <code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code></p> |
| </section> |
| |
| <section id="verisign"><title>Why can't I find the |
| <code>getca</code> or <code>getverisign</code> programs mentioned by |
| Verisign, for installing my Verisign certificate?</title> |
| <p>Verisign has never provided specific instructions |
| for Apache+mod_ssl. The instructions provided are for C2Net's |
| Stronghold (a commercial Apache based server with SSL support).</p> |
| <p>To install your certificate, all you need to do is to save the |
| certificate to a file, and give the name of that file to the |
| <directive module="mod_ssl">SSLCertificateFile</directive> directive. |
| You will also need to give it the key file. For more information, |
| see the <directive module="mod_ssl">SSLCertificateKeyFile</directive> |
| directive.</p> |
| </section> |
| |
| <section id="sgc"><title>Can I use the Server Gated Cryptography (SGC) |
| facility (aka Verisign Global ID) with mod_ssl?</title> |
| <p>Yes. <module>mod_ssl</module> has included support for the SGC |
| facility since version 2.1. No special configuration is required - |
| just use the Global ID as your server certificate. The |
| <em>step up</em> of the clients is then automatically handled by |
| <module>mod_ssl</module> at run-time.</p> |
| </section> |
| |
| <section id="gid"><title>Why do browsers complain that they cannot |
| verify my Verisign Global ID server certificate?</title> |
| <p>Verisign uses an intermediate CA certificate between the root CA |
| certificate (which is installed in the browsers) and the server |
| certificate (which you installed on the server). You should have |
| received this additional CA certificate from Verisign. |
| If not, complain to them. Then, configure this certificate with the |
| <directive module="mod_ssl">SSLCertificateChainFile</directive> |
| directive. This ensures that the intermediate CA certificate is |
| sent to the browser, filling the gap in the certificate chain.</p> |
| </section> |
| </section> |
| <!-- /certs --> |
| |
| <section id="aboutssl"><title>The SSL Protocol</title> |
| <ul> |
| <li><a href="#random">Why do I get lots of random SSL protocol |
| errors under heavy server load?</a></li> |
| <li><a href="#load">Why does my webserver have a higher load, now |
| that it serves SSL encrypted traffic?</a></li> |
| <li><a href="#establishing">Why do HTTPS connections to my server |
| sometimes take up to 30 seconds to establish a connection?</a></li> |
| <li><a href="#ciphers">What SSL Ciphers are supported by mod_ssl?</a></li> |
| <li><a href="#adh">Why do I get ``no shared cipher'' errors, when |
| trying to use Anonymous Diffie-Hellman (ADH) ciphers?</a></li> |
| <li><a href="#sharedciphers">Why do I get a 'no shared ciphers' |
| error when connecting to my newly installed server?</a></li> |
| <li><a href="#vhosts">Why can't I use SSL with name-based/non-IP-based |
| virtual hosts?</a></li> |
| <li><a href="#vhosts2">Why is it not possible to use Name-Based Virtual |
| Hosting to identify different SSL virtual hosts?</a></li> |
| <li><a href="#lockicon">When I use Basic Authentication over HTTPS |
| the lock icon in Netscape browsers stays unlocked when the dialog pops up. |
| Does this mean the username/password is being sent unencrypted?</a></li> |
| <li><a href="#msie">Why do I get I/O errors when connecting via |
| HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer |
| (MSIE)?</a></li> |
| <li><a href="#nn">Why do I get I/O errors, or the message "Netscape has |
| encountered bad data from the server", when connecting via |
| HTTPS to an Apache+mod_ssl server with Netscape Navigator?</a></li> |
| </ul> |
| |
| <section id="random"><title>Why do I get lots of random SSL protocol |
| errors under heavy server load?</title> |
| <p>There can be a number of reasons for this, but the main one |
| is problems with the SSL session Cache specified by the |
| <directive module="mod_ssl">SSLSessionCache</directive> directive. The DBM session |
| cache is the most likely source of the problem, so using the SHM session cache (or |
| no cache at all) may help.</p> |
| </section> |
| |
| <section id="load"><title>Why does my webserver have a higher load, now |
| that it serves SSL encrypted traffic?</title> |
| <p>SSL uses strong cryptographic encryption, which necessitates a lot of |
| number crunching. When you request a webpage via HTTPS, everything (even |
| the images) is encrypted before it is transferred. So increased HTTPS |
| traffic leads to load increases.</p> |
| </section> |
| |
| <section id="establishing"><title>Why do HTTPS connections to my server |
| sometimes take up to 30 seconds to establish a connection?</title> |
| <p>This is usually caused by a <code>/dev/random</code> device for |
| <directive module="mod_ssl">SSLRandomSeed</directive> which blocks the |
| read(2) call until enough entropy is available to service the |
| request. More information is available in the reference |
| manual for the <directive module="mod_ssl">SSLRandomSeed</directive> |
| directive.</p> |
| </section> |
| |
| <section id="ciphers"><title>What SSL Ciphers are supported by mod_ssl?</title> |
| <p>Usually, any SSL ciphers supported by the version of OpenSSL in use, |
| are also supported by <module>mod_ssl</module>. Which ciphers are |
| available can depend on the way you built OpenSSL. Typically, at |
| least the following ciphers are supported:</p> |
| |
| <ol> |
| <li>RC4 with MD5</li> |
| <li>RC4 with MD5 (export version restricted to 40-bit key)</li> |
| <li>RC2 with MD5</li> |
| <li>RC2 with MD5 (export version restricted to 40-bit key)</li> |
| <li>IDEA with MD5</li> |
| <li>DES with MD5</li> |
| <li>Triple-DES with MD5</li> |
| </ol> |
| |
| <p>To determine the actual list of ciphers available, you should run |
| the following:</p> |
| <example>$ openssl ciphers -v</example> |
| </section> |
| |
| <section id="adh"><title>Why do I get ``no shared cipher'' errors, when |
| trying to use Anonymous Diffie-Hellman (ADH) ciphers?</title> |
| <p>By default, OpenSSL does <em>not</em> allow ADH ciphers, for security |
| reasons. Please be sure you are aware of the potential side-effects |
| if you choose to enable these ciphers.</p> |
| <p>In order to use Anonymous Diffie-Hellman (ADH) ciphers, you must |
| build OpenSSL with ``<code>-DSSL_ALLOW_ADH</code>'', and then add |
| ``<code>ADH</code>'' into your <directive module="mod_ssl" |
| >SSLCipherSuite</directive>.</p> |
| </section> |
| |
| <section id="sharedciphers"><title>Why do I get a 'no shared ciphers' |
| error when connecting to my newly installed server?</title> |
| <p>Either you have made a mistake with your |
| <directive module="mod_ssl">>SSLCipherSuite</directive> |
| directive (compare it with the pre-configured example in |
| <code>httpd.conf-dist</code>) or you chose to use DSA/DH |
| algorithms instead of RSA when you generated your private key |
| and ignored or overlooked the warnings. If you have chosen |
| DSA/DH, then your server cannot communicate using RSA-based SSL |
| ciphers (at least until you configure an additional RSA-based |
| certificate/key pair). Modern browsers like NS or IE can only |
| communicate over SSL using RSA ciphers. The result is the |
| "no shared ciphers" error. To fix this, regenerate your server |
| certificate/key pair, using the RSA algorithm.</p> |
| </section> |
| |
| <section id="vhosts"><title>Why can't I use SSL with name-based/non-IP-based virtual hosts?</title> |
| <p>The reason is very technical, and a somewhat "chicken and egg" problem. |
| The SSL protocol layer stays below the HTTP protocol layer and |
| encapsulates HTTP. When an SSL connection (HTTPS) is established |
| Apache/mod_ssl has to negotiate the SSL protocol parameters with the |
| client. For this, mod_ssl has to consult the configuration of the virtual |
| server (for instance it has to look for the cipher suite, the server |
| certificate, etc.). But in order to go to the correct virtual server |
| Apache has to know the <code>Host</code> HTTP header field. To do this, the |
| HTTP request header has to be read. This cannot be done before the SSL |
| handshake is finished, but the information is needed in order to |
| complete the SSL handshake phase. Bingo!</p> |
| </section> |
| |
| <section id="vhosts2"><title>Why is it not possible to use Name-Based |
| Virtual Hosting to identify different SSL virtual hosts?</title> |
| <p>Name-Based Virtual Hosting is a very popular method of identifying |
| different virtual hosts. It allows you to use the same IP address and |
| the same port number for many different sites. When people move on to |
| SSL, it seems natural to assume that the same method can be used to have |
| lots of different SSL virtual hosts on the same server.</p> |
| |
| <p>It comes as rather a shock to learn that it is impossible.</p> |
| |
| <p>The reason is that the SSL protocol is a separate layer which |
| encapsulates the HTTP protocol. So the SSL session is a separate |
| transaction, that takes place before the HTTP session has begun. |
| The server receives an SSL request on IP address X and port Y |
| (usually 443). Since the SSL request does not contain any Host: |
| field, the server has no way to decide which SSL virtual host to use. |
| Usually, it will just use the first one it finds, which matches the |
| port and IP address specified.</p> |
| |
| <p>You can, of course, use Name-Based Virtual Hosting to identify many |
| non-SSL virtual hosts (all on port 80, for example) and then |
| have a single SSL virtual host (on port 443). But if you do this, |
| you must make sure to put the non-SSL port number on the NameVirtualHost |
| directive, e.g.</p> |
| |
| <example> |
| NameVirtualHost 192.168.1.1:80 |
| </example> |
| |
| <p>Other workaround solutions include: </p> |
| |
| <p>Using separate IP addresses for different SSL hosts. |
| Using different port numbers for different SSL hosts.</p> |
| </section> |
| |
| <section id="comp"><title>How do I get SSL compression working?</title> |
| <p>Although SSL compression negotiation was defined in the specification |
| of SSLv2 and TLS, it took until May 2004 for RFC 3749 to define DEFLATE as |
| a negotiable standard compression method. |
| </p> |
| <p>OpenSSL 0.9.8 started to support this by default when compiled with the |
| <code>zlib</code> option. If both the client and the server support compression, |
| it will be used. However, most clients still try to initially connect with an |
| SSLv2 Hello. As SSLv2 did not include an array of prefered compression algorithms |
| in its handshake, compression cannot be negotiated with these clients. |
| If the client disables support for SSLv2, either an SSLv3 or TLS Hello |
| may be sent, depending on which SSL library is used, and compression may |
| be set up. You can verify whether clients make use of SSL compression by |
| logging the <code>%{SSL_COMPRESS_METHOD}x</code> variable. |
| </p> |
| </section> |
| |
| <section id="lockicon"><title>When I use Basic Authentication over HTTPS |
| the lock icon in Netscape browsers stays unlocked when the dialog pops up. |
| Does this mean the username/password is being sent unencrypted?</title> |
| <p>No, the username/password is transmitted encrypted. The icon in |
| Netscape browsers is not actually synchronized with the SSL/TLS layer. |
| It only toggles to the locked state when the first part of the actual |
| webpage data is transferred, which may confuse people. The Basic |
| Authentication facility is part of the HTTP layer, which is above |
| the SSL/TLS layer in HTTPS. Before any HTTP data communication takes |
| place in HTTPS, the SSL/TLS layer has already completed its handshake |
| phase, and switched to encrypted communication. So don't be |
| confused by this icon.</p> |
| </section> |
| |
| <section id="msie"><title>Why do I get I/O errors when connecting via |
| HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer (MSIE)?</title> |
| <p>The first reason is that the SSL implementation in some MSIE versions has |
| some subtle bugs related to the HTTP keep-alive facility and the SSL close |
| notify alerts on socket connection close. Additionally the interaction |
| between SSL and HTTP/1.1 features are problematic in some MSIE versions. |
| You can work around these problems by forcing Apache not to use HTTP/1.1, |
| keep-alive connections or send the SSL close notify messages to MSIE clients. |
| This can be done by using the following directive in your SSL-aware |
| virtual host section:</p> |
| <example> |
| SetEnvIf User-Agent ".*MSIE.*" \<br /> |
| nokeepalive ssl-unclean-shutdown \<br /> |
| downgrade-1.0 force-response-1.0 |
| </example> |
| <p>Further, some MSIE versions have problems with particular ciphers. |
| Unfortunately, it is not possible to implement a MSIE-specific |
| workaround for this, because the ciphers are needed as early as the |
| SSL handshake phase. So a MSIE-specific |
| <directive module="mod_setenvif">SetEnvIf</directive> won't solve these |
| problems. Instead, you will have to make more drastic |
| adjustments to the global parameters. Before you decide to do |
| this, make sure your clients really have problems. If not, do not |
| make these changes - they will affect <em>all</em> your clients, MSIE |
| or otherwise.</p> |
| |
| <p>The next problem is that 56bit export versions of MSIE 5.x |
| browsers have a broken SSLv3 implementation, which interacts badly |
| with OpenSSL versions greater than 0.9.4. You can accept this and |
| require your clients to upgrade their browsers, you can downgrade to |
| OpenSSL 0.9.4 (not advised), or you can work around this, accepting |
| that your workaround will affect other browsers too:</p> |
| <example>SSLProtocol all -SSLv3</example> |
| <p>will completely disables the SSLv3 protocol and allow those |
| browsers to work. A better workaround is to disable only those |
| ciphers which cause trouble.</p> |
| <example><p><code>SSLCipherSuite |
| ALL:!ADH:<strong>!EXPORT56</strong>:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code> |
| </p></example> |
| |
| <p>This also allows the broken MSIE versions to work, but only removes the |
| newer 56bit TLS ciphers.</p> |
| |
| <p>Another problem with MSIE 5.x clients is that they refuse to connect to |
| URLs of the form <code>https://12.34.56.78/</code> (where IP-addresses are used |
| instead of the hostname), if the server is using the Server Gated |
| Cryptography (SGC) facility. This can only be avoided by using the fully |
| qualified domain name (FQDN) of the website in hyperlinks instead, because |
| MSIE 5.x has an error in the way it handles the SGC negotiation.</p> |
| |
| <p>And finally there are versions of MSIE which seem to require that |
| an SSL session can be reused (a totally non standard-conforming |
| behaviour, of course). Connecting with those MSIE versions only work |
| if a SSL session cache is used. So, as a work-around, make sure you |
| are using a session cache (see the <directive module="mod_ssl" |
| >SSLSessionCache</directive> directive).</p> |
| </section> |
| |
| <section id="nn"><title>Why do I get I/O errors, or the message "Netscape has |
| encountered bad data from the server", when connecting via |
| HTTPS to an Apache+mod_ssl server with Netscape Navigator?</title> |
| <p> |
| This usually occurs when you have created a new server certificate for |
| a given domain, but had previously told your browser to always accept |
| the old server certificate. Once you clear the entry for the old |
| certificate from your browser, everything should be fine. Netscape's SSL |
| implementation is correct, so when you encounter I/O errors with Netscape |
| Navigator it is usually caused by the configured certificates.</p> |
| </section> |
| </section> |
| <!-- /aboutssl --> |
| |
| <section id="support"><title>mod_ssl Support</title> |
| <ul> |
| <li><a href="#resources">What information resources are available in |
| case of mod_ssl problems?</a></li> |
| <li><a href="#contact">What support contacts are available in case of |
| mod_ssl problems?</a></li> |
| <li><a href="#reportdetails">What information should I |
| provide when writing a bug report?</a></li> |
| <li><a href="#coredumphelp">I had a core dump, can you help me?</a></li> |
| <li><a href="#backtrace">How do I get a backtrace, to help find the reason |
| for my core dump?</a></li> |
| </ul> |
| |
| <section id="resources"><title>What information resources are available in case of mod_ssl problems?</title> |
| <p>The following information resources are available. |
| In case of problems you should search here first.</p> |
| |
| <dl> |
| <dt>Answers in the User Manual's F.A.Q. List (this)</dt> |
| <dd><a href="http://httpd.apache.org/docs/2.1/ssl/ssl_faq.html"> |
| http://httpd.apache.org/docs/2.1/ssl/ssl_faq.html</a><br /> |
| First check the F.A.Q. (this text). If your problem is a common |
| one, it may have been answered several times before, and been included |
| in this doc. |
| </dd> |
| <dt>Postings from the modssl-users Support Mailing List |
| <a href="http://www.modssl.org/support/" |
| >http://www.modssl.org/support/</a></dt> |
| <dd>Search for your problem in the archives of the modssl-users mailing list. |
| You're probably not the first person to have had this problem! |
| </dd> |
| </dl> |
| </section> |
| |
| <section id="contact"><title>What support contacts are available in case |
| of mod_ssl problems?</title> |
| <p>The following lists all support possibilities for mod_ssl, in order of |
| preference. Please go through these possibilities |
| <em>in this order</em> - don't just pick the one you like the look of. </p> |
| <ol> |
| <li><em>Send a Problem Report to the modssl-users Support Mailing List</em><br /> |
| <a href="mailto:modssl-users@modssl.org"> |
| modssl-users@modssl.org</a><br /> |
| This is the preferred way of submitting your problem report, because this way, |
| others can see the problem, and learn from any answers. You must subscribe to |
| the list first, but you can then easily discuss your problem with both the |
| author and the whole mod_ssl user community. |
| </li> |
| |
| <li><em>Send a Problem Report to the Apache httpd Users Support Mailing List</em><br /> |
| <a href="mailto:users@httpd.apache.org"> |
| users@httpd.apache.org</a><br /> |
| This is the second way of submitting your problem report. Again, you must |
| subscribe to the list first, but you can then easily discuss your problem |
| with the whole Apache httpd user community. |
| </li> |
| |
| <li><em>Write a Problem Report in the Bug Database</em><br /> |
| <a href="http://httpd.apache.org/bug_report.html"> |
| http://httpd.apache.org/bug_report.html</a><br /> |
| This is the last way of submitting your problem report. You should only |
| do this if you've already posted to the mailing lists, and had no success. |
| Please follow the instructions on the above page <em>carefully</em>. |
| </li> |
| </ol> |
| </section> |
| |
| <section id="reportdetails"><title>What information should I |
| provide when writing a bug report?</title> |
| <p>You should always provide at least the following information:</p> |
| |
| <dl> |
| <dt>Apache and OpenSSL version information</dt> |
| <dd>The Apache version can be determined |
| by running <code>httpd -v</code>. The OpenSSL version can be |
| determined by running <code>openssl version</code>. Alternatively, if |
| you have Lynx installed, you can run the command <code>lynx -mime_header |
| http://localhost/ | grep Server</code> to gather this information in a |
| single step. |
| </dd> |
| |
| <dt>The details on how you built and installed Apache+mod_ssl+OpenSSL</dt> |
| <dd>For this you can provide a logfile of your terminal session which shows |
| the configuration and install steps. If this is not possible, you |
| should at least provide the <program>configure</program> command line you used. |
| </dd> |
| |
| <dt>In case of core dumps please include a Backtrace</dt> |
| <dd>If your Apache+mod_ssl+OpenSSL dumps its core, please attach |
| a stack-frame ``backtrace'' (see <a href="#backtrace">below</a> |
| for information on how to get this). Without this information, the |
| reason for your core dump cannot be found |
| </dd> |
| |
| <dt>A detailed description of your problem</dt> |
| <dd>Don't laugh, we really mean it! Many problem reports don't |
| include a description of what the actual problem is. Without this, |
| it's very difficult for anyone to help you. So, it's in your own |
| interest (you want the problem be solved, don't you?) to include as |
| much detail as possible, please. Of course, you should still include |
| all the essentials above too. |
| </dd> |
| </dl> |
| </section> |
| |
| <section id="coredumphelp"><title>I had a core dump, can you help me?</title> |
| <p>In general no, at least not unless you provide more details about the code |
| location where Apache dumped core. What is usually always required in |
| order to help you is a backtrace (see next question). Without this |
| information it is mostly impossible to find the problem and help you in |
| fixing it.</p> |
| </section> |
| |
| <section id="backtrace"><title>How do I get a backtrace, to help find |
| the reason for my core dump?</title> |
| <p>Following are the steps you will need to complete, to get a backtrace:</p> |
| <ol> |
| <li>Make sure you have debugging symbols available, at least |
| in Apache. On platforms where you use GCC/GDB, you will have to build |
| Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to get this. On |
| other platforms at least ``<code>OPTIM="-g"</code>'' is needed. |
| </li> |
| |
| <li>Start the server and try to reproduce the core-dump. For this you may |
| want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to |
| make sure that the core-dump file can be written. This should result |
| in a <code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. If you |
| don't get one of these, try running your server under a non-root UID. |
| Many modern kernels do not allow a process to dump core after it has |
| done a <code>setuid()</code> (unless it does an <code>exec()</code>) for |
| security reasons (there can be privileged information left over in |
| memory). If necessary, you can run <code>/path/to/httpd -X</code> |
| manually to force Apache to not fork. |
| </li> |
| |
| <li>Analyze the core-dump. For this, run <code>gdb /path/to/httpd |
| /tmp/httpd.core</code> or a similar command. In GDB, all you |
| have to do then is to enter <code>bt</code>, and voila, you get the |
| backtrace. For other debuggers consult your local debugger manual. |
| </li> |
| </ol> |
| </section> |
| </section> |
| </manualpage> |