1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>SSL/TLS Strong Encryption: FAQ - Apache HTTP Server</title>
9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
13 <body id="manual-page"><div id="page-header">
14 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
15 <p class="apache">Apache HTTP Server Version 2.0</p>
16 <img alt="" src="../images/feather.gif" /></div>
17 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
19 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">SSL/TLS</a></div><div id="page-content"><div id="preamble"><h1>SSL/TLS Strong Encryption: FAQ</h1>
21 <p><span>Available Languages: </span><a href="../en/ssl/ssl_faq.html" title="English"> en </a></p>
25 <p>The wise man doesn't give the right answers,
26 he poses the right questions.</p>
27 <p class="cite">-- <cite>Claude Levi-Strauss</cite></p>
30 <p>This chapter is a collection of frequently asked questions (FAQ) and
31 corresponding answers following the popular USENET tradition. Most of these
32 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
33 Mailing List <code><a href="mailto:modssl-users@modssl.org">modssl-users@modssl.org</a></code>. They are collected at this place
34 to avoid answering the same questions over and over.</p>
36 <p>Please read this chapter at least once when installing mod_ssl or at least
37 search for your problem here before submitting a problem report to the
40 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#about">About The Module</a></li>
41 <li><img alt="" src="../images/down.gif" /> <a href="#installation">Installation</a></li>
42 <li><img alt="" src="../images/down.gif" /> <a href="#aboutconfig">Configuration</a></li>
43 <li><img alt="" src="../images/down.gif" /> <a href="#aboutcerts">Certificates</a></li>
44 <li><img alt="" src="../images/down.gif" /> <a href="#aboutssl">The SSL Protocol</a></li>
45 <li><img alt="" src="../images/down.gif" /> <a href="#support">mod_ssl Support</a></li>
47 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
49 <h2><a name="about" id="about">About The Module</a></h2>
51 <li><a href="#history">What is the history of mod_ssl?</a></li>
52 <li><a href="#wassenaar">mod_ssl and Wassenaar Arrangement?</a></li>
55 <h3><a name="history" id="history">What is the history of mod_ssl?</a></h3>
56 <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
57 Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben
58 Laurie's development cycle it then was re-assembled from scratch for
59 Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL
60 1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The
61 first publicly released version was mod_ssl 2.0.0 from August 10th,
64 <p>After US export restrictions on cryptographic software were
65 loosened, <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> became part of the Apache HTTP
66 Server with the release of Apache httpd 2.</p>
69 <h3><a name="wassenaar" id="wassenaar">Is mod_ssl affected by the Wassenaar Arrangement?</a></h3>
70 <p>First, let us explain what <dfn>Wassenaar</dfn> and its <dfn>Arrangement on
71 Export Controls for Conventional Arms and Dual-Use Goods and
72 Technologies</dfn> is: This is a international regime, established in 1995, to
73 control trade in conventional arms and dual-use goods and technology. It
74 replaced the previous <dfn>CoCom</dfn> regime. Further details on
75 both the Arrangement and its signatories are available at <a href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>.</p>
77 <p>In short, the aim of the Wassenaar Arrangement is to prevent the build up
78 of military capabilities that threaten regional and international security
79 and stability. The Wassenaar Arrangement controls the export of
80 cryptography as a dual-use good, that is, something that has both military and
81 civilian applications. However, the Wassenaar Arrangement also provides an
82 exemption from export controls for mass-market software and free software.</p>
84 <p>In the current Wassenaar <cite>List of Dual Use Goods and Technologies And
85 Munitions</cite>, under <q>GENERAL SOFTWARE NOTE (GSN)</q> it says
86 <q>The Lists do not control "software" which is either: 1. [...] 2. "in
87 the public domain".</q> And under <q>DEFINITIONS OF TERMS USED IN
88 THESE LISTS</q> we find <q>In the public
89 domain</q> defined as <q>"technology" or "software" which has been made
90 available without restrictions upon its further dissemination. Note:
91 Copyright restrictions do not remove "technology" or "software" from being
92 "in the public domain".</q></p>
94 <p>So, both mod_ssl and OpenSSL are <q>in the public domain</q> for the purposes
95 of the Wassenaar Arrangement and its <q>List of Dual Use Goods and
96 Technologies And Munitions List</q>, and thus not affected by its provisions.</p>
99 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
100 <div class="section">
101 <h2><a name="installation" id="installation">Installation</a></h2>
103 <li><a href="#mutex">Why do I get permission errors related to
104 SSLMutex when I start Apache?</a></li>
105 <li><a href="#entropy">Why does mod_ssl stop with the error "Failed to
106 generate temporary 512 bit RSA private key" when I start Apache?</a></li>
109 <h3><a name="mutex" id="mutex">Why do I get permission errors related to
110 SSLMutex when I start Apache?</a></h3>
111 <p>Errors such as ``<code>mod_ssl: Child could not open
112 SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows)
113 [...] System: Permission denied (errno: 13)</code>'' are usually
114 caused by overly restrictive permissions on the <em>parent</em> directories.
115 Make sure that all parent directories (here <code>/opt</code>,
116 <code>/opt/apache</code> and <code>/opt/apache/logs</code>) have the x-bit
117 set for, at minimum, the UID under which Apache's children are running (see
118 the <code class="directive"><a href="../mod/mpm_common.html#user">User</a></code> directive).</p>
121 <h3><a name="entropy" id="entropy">Why does mod_ssl stop with the error
122 "Failed to generate temporary 512 bit RSA private key" when I start
124 <p>Cryptographic software needs a source of unpredictable data
125 to work correctly. Many open source operating systems provide
126 a "randomness device" that serves this purpose (usually named
127 <code>/dev/random</code>). On other systems, applications have to
128 seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with
129 appropriate data before generating keys or performing public key
130 encryption. As of version 0.9.5, the OpenSSL functions that need
131 randomness report an error if the PRNG has not been seeded with
132 at least 128 bits of randomness.</p>
133 <p>To prevent this error, <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> has to provide
134 enough entropy to the PRNG to allow it to work correctly. This can
135 be done via the <code class="directive"><a href="../mod/mod_ssl.html#sslrandomseed">SSLRandomSeed</a></code>
138 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
139 <div class="section">
140 <h2><a name="aboutconfig" id="aboutconfig">Configuration</a></h2>
142 <li><a href="#parallel">Is it possible to provide HTTP and HTTPS from
143 the same server?</a></li>
144 <li><a href="#ports">Which port does HTTPS use?</a></li>
145 <li><a href="#httpstest">How do I speak HTTPS manually for testing
147 <li><a href="#hang">Why does the connection hang when I connect to my
148 SSL-aware Apache server?</a></li>
149 <li><a href="#refused">Why do I get ``Connection Refused'' errors, when
150 trying to access my newly installed Apache+mod_ssl server via HTTPS?</a></li>
151 <li><a href="#envvars">Why are the <code>SSL_XXX</code> variables not
152 available to my CGI & SSI scripts?</a></li>
153 <li><a href="#relative">How can I switch between HTTP and HTTPS in
154 relative hyperlinks?</a></li>
157 <h3><a name="parallel" id="parallel">Is it possible to provide HTTP and HTTPS
158 from the same server?</a></h3>
159 <p>Yes. HTTP and HTTPS use different server ports (HTTP binds to
160 port 80, HTTPS to port 443), so there is no direct conflict between
161 them. You can either run two separate server instances bound to
162 these ports, or use Apache's elegant virtual hosting facility to
163 create two virtual servers, both served by the same instance of Apache
164 - one responding over HTTP to requests on port 80, and the other
165 responding over HTTPS to requests on port 443.</p>
168 <h3><a name="ports" id="ports">Which port does HTTPS use?</a></h3>
169 <p>You can run HTTPS on any port, but the standards specify port 443, which
170 is where any HTTPS compliant browser will look by default. You can force
171 your browser to look on a different port by specifying it in the URL. For
172 example, if your server is set up to serve pages over HTTPS on port 8080,
173 you can access them at <code>https://example.com:8080/</code></p>
176 <h3><a name="httpstest" id="httpstest">How do I speak HTTPS manually for testing purposes?</a></h3>
177 <p>While you usually just use</p>
179 <div class="example"><p><code>$ telnet localhost 80<br />
180 GET / HTTP/1.0</code></p></div>
182 <p>for simple testing of Apache via HTTP, it's not so easy for
183 HTTPS because of the SSL protocol between TCP and HTTP. With the
184 help of OpenSSL's <code>s_client</code> command, however, you can
185 do a similar check via HTTPS:</p>
187 <div class="example"><p><code>$ openssl s_client -connect localhost:443 -state -debug<br />
188 GET / HTTP/1.0</code></p></div>
190 <p>Before the actual HTTP response you will receive detailed
191 information about the SSL handshake. For a more general command
192 line client which directly understands both HTTP and HTTPS, can
193 perform GET and POST operations, can use a proxy, supports byte
194 ranges, etc. you should have a look at the nifty
195 <a href="http://curl.haxx.se/">cURL</a> tool. Using this, you can
196 check that Apache is responding correctly to requests via HTTP and
197 HTTPS as follows:</p>
199 <div class="example"><p><code>$ curl http://localhost/<br />
200 $ curl https://localhost/</code></p></div>
203 <h3><a name="hang" id="hang">Why does the connection hang when I connect
204 to my SSL-aware Apache server?</a></h3>
206 <p>This can happen when you try to connect to a HTTPS server (or virtual
207 server) via HTTP (eg, using <code>http://example.com/</code> instead of
208 <code>https://example.com</code>). It can also happen when trying to
209 connect via HTTPS to a HTTP server (eg, using
210 <code>https://example.com/</code> on a server which doesn't support HTTPS,
211 or which supports it on a non-standard port). Make sure that you're
212 connecting to a (virtual) server that supports SSL.</p>
214 <h3><a name="refused" id="refused">Why do I get ``Connection Refused'' messages,
215 when trying to access my newly installed Apache+mod_ssl server via HTTPS?</a></h3>
217 This error can be caused by an incorrect configuration.
218 Please make sure that your <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code> directives match your
219 <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>
220 directives. If all else fails, please start afresh, using the default
221 configuration provided by <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>.</p>
224 <h3><a name="envvars" id="envvars">Why are the <code>SSL_XXX</code> variables
225 not available to my CGI & SSI scripts?</a></h3>
226 <p>Please make sure you have ``<code>SSLOptions +StdEnvVars</code>''
227 enabled for the context of your CGI/SSI requests.</p>
230 <h3><a name="relative" id="relative">How can I switch between HTTP and HTTPS in relative
233 <p>Usually, to switch between HTTP and HTTPS, you have to use
234 fully-qualified hyperlinks (because you have to change the URL
235 scheme). Using <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> however, you can
236 manipulate relative hyperlinks, to achieve the same effect.</p>
237 <div class="example"><p><code>
238 RewriteEngine on<br />
239 RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L]<br />
240 RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L]
243 <p>This rewrite ruleset lets you use hyperlinks of the form
244 <code><a href="document.html:SSL"></code>, to switch to HTTPS
245 in a relative link. (Replace SSL with NOSSL to switch to HTTP.)</p>
247 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
248 <div class="section">
249 <h2><a name="aboutcerts" id="aboutcerts">Certificates</a></h2>
251 <li><a href="#keyscerts">What are RSA Private Keys, CSRs and
252 Certificates?</a></li>
253 <li><a href="#startup">Is there a difference on startup between
254 a non-SSL-aware Apache and an SSL-aware Apache?</a></li>
255 <li><a href="#selfcert">How do I create a self-signed SSL
256 Certificate for testing purposes?</a></li>
257 <li><a href="#realcert">How do I create a real SSL Certificate?</a></li>
258 <li><a href="#ownca">How do I create and use my own Certificate
259 Authority (CA)?</a></li>
260 <li><a href="#passphrase">How can I change the pass-phrase on my private
262 <li><a href="#removepassphrase">How can I get rid of the pass-phrase
263 dialog at Apache startup time?</a></li>
264 <li><a href="#verify">How do I verify that a private key matches its
265 Certificate?</a></li>
266 <li><a href="#badcert">Why do connections fail with an "alert bad
267 certificate" error?</a></li>
268 <li><a href="#keysize">Why does my 2048-bit private key not work?</a></li>
269 <li><a href="#hashsymlinks">Why is client authentication broken after
270 upgrading from SSLeay version 0.8 to 0.9?</a></li>
271 <li><a href="#pemder">How can I convert a certificate from PEM to DER
273 <li><a href="#verisign">Why can't I find the
274 <code>getca</code> or <code>getverisign</code> programs mentioned by
275 Verisign, for installing my Verisign certificate?</a></li>
276 <li><a href="#sgc">Can I use the Server Gated Cryptography (SGC)
277 facility (aka Verisign Global ID) with mod_ssl?</a></li>
278 <li><a href="#gid">Why do browsers complain that they cannot
279 verify my Verisign Global ID server certificate?</a></li>
282 <h3><a name="keyscerts" id="keyscerts">What are RSA Private Keys, CSRs and Certificates?</a></h3>
283 <p>An RSA private key file is a digital file that you can use to decrypt
284 messages sent to you. It has a public component which you distribute (via
285 your Certificate file) which allows people to encrypt those messages to
287 <p>A Certificate Signing Request (CSR) is a digital file which contains
288 your public key and your name. You send the CSR to a Certifying Authority
289 (CA), who will convert it into a real Certificate, by signing it.</p>
290 <p>A Certificate contains your
291 RSA public key, your name, the name of the CA, and is digitally signed by
292 the CA. Browsers that know the CA can verify the signature on that
293 Certificate, thereby obtaining your RSA public key. That enables them to
294 send messages which only you can decrypt.</p>
295 <p>See the <a href="ssl_intro.html">Introduction</a> chapter for a general
296 description of the SSL protocol.</p>
299 <h3><a name="startup" id="startup">Is there a difference on startup between
300 a non-SSL-aware Apache and an SSL-aware Apache?</a></h3>
301 <p>Yes. In general, starting Apache with
302 <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> built-in is just like starting Apache
303 without it. However, if you have a passphrase on your SSL private
304 key file, a startup dialog will pop up which asks you to enter the
307 <p>Having to manually enter the passphrase when starting the server
308 can be problematic - for example, when starting the server from the
309 system boot scripts. In this case, you can follow the steps
310 <a href="#removepassphrase">below</a> to remove the passphrase from
311 your private key. Bear in mind that doing so brings additional security
312 risks - proceed with caution!</p>
315 <h3><a name="selfcert" id="selfcert">How do I create a self-signed SSL
316 Certificate for testing purposes?</a></h3>
318 <li>Make sure OpenSSL is installed and in your <code>PATH</code>.<br />
321 <li>Run the following command, to create <code>server.key</code> and
322 <code>server.crt</code> files:<br />
323 <code><strong>$ openssl req -new -x509 -nodes -out server.crt
324 -keyout server.key</strong></code><br />
325 These can be used as follows in your <code>httpd.conf</code>
328 SSLCertificateFile /path/to/this/server.crt
329 SSLCertificateKeyFile /path/to/this/server.key
332 <li>It is important that you are aware that this
333 <code>server.key</code> does <em>not</em> have any passphrase.
334 To add a passphrase to the key, you should run the following
335 command, and enter & verify the passphrase as requested.<br />
336 <p><code><strong>$ openssl rsa -des3 -in server.key -out
337 server.key.new</strong></code><br />
338 <code><strong>$ mv server.key.new server.key</strong></code><br /></p>
339 Please backup the <code>server.key</code> file, and the passphrase
340 you entered, in a secure location.
345 <h3><a name="realcert" id="realcert">How do I create a real SSL Certificate?</a></h3>
346 <p>Here is a step-by-step description:</p>
348 <li>Make sure OpenSSL is installed and in your <code>PATH</code>.
352 <li>Create a RSA private key for your Apache server
353 (will be Triple-DES encrypted and PEM formatted):<br />
355 <code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code><br />
357 Please backup this <code>server.key</code> file and the
358 pass-phrase you entered in a secure location.
359 You can see the details of this RSA private key by using the command:<br />
362 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br />
364 If necessary, you can also create a decrypted PEM version (not
365 recommended) of this RSA private key with:<br />
367 <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br />
371 <li>Create a Certificate Signing Request (CSR) with the server RSA private
372 key (output will be PEM formatted):<br />
374 <code><strong>$ openssl req -new -key server.key -out server.csr</strong></code><br />
376 Make sure you enter the FQDN ("Fully Qualified Domain Name") of the
377 server when OpenSSL prompts you for the "CommonName", i.e. when you
378 generate a CSR for a website which will be later accessed via
379 <code>https://www.foo.dom/</code>, enter "www.foo.dom" here.
380 You can see the details of this CSR by using<br />
383 <code><strong>$ openssl req -noout -text -in server.csr</strong></code><br />
386 <li>You now have to send this Certificate Signing Request (CSR) to
387 a Certifying Authority (CA) to be signed. Once the CSR has been
388 signed, you will have a real Certificate, which can be used by
389 Apache. You can have a CSR signed by a commercial CA, or you can
390 create your own CA to sign it.<br />
391 Commercial CAs usually ask you to post the CSR into a web form,
392 pay for the signing, and then send a signed Certificate, which
393 you can store in a server.crt file. For more information about
394 commercial CAs see the following locations:<br />
398 <a href="http://digitalid.verisign.com/server/apacheNotice.htm">
399 http://digitalid.verisign.com/server/apacheNotice.htm
403 <a href="http://www.thawte.com/">http://www.thawte.com/</a>
405 <li> CertiSign Certificadora Digital Ltda.<br />
406 <a href="http://www.certisign.com.br">
407 http://www.certisign.com.br
411 <a href="http://www.iks-jena.de/leistungen/ca/">
412 http://www.iks-jena.de/leistungen/ca/
415 <li> Uptime Commerce Ltd.<br />
416 <a href="http://www.uptimecommerce.com">
417 http://www.uptimecommerce.com
420 <li> BelSign NV/SA<br />
421 <a href="http://www.belsign.be">
422 http://www.belsign.be
427 For details on how to create your own CA, and use this to sign
428 a CSR, see <a href="#ownca">below</a>.<br />
430 Once your CSR has been signed, you can see the details of the
431 Certificate as follows:<br />
433 <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
436 <li>You should now have two files: <code>server.key</code> and
437 <code>server.crt</code>. These can be used as follows in your
438 <code>httpd.conf</code> file:
440 SSLCertificateFile /path/to/this/server.crt
441 SSLCertificateKeyFile /path/to/this/server.key
443 The <code>server.csr</code> file is no longer needed.
449 <h3><a name="ownca" id="ownca">How do I create and use my own Certificate Authority (CA)?</a></h3>
450 <p>The short answer is to use the <code>CA.sh</code> or <code>CA.pl</code>
451 script provided by OpenSSL. Unless you have a good reason not to,
452 you should use these for preference. If you cannot, you can create a
453 self-signed Certificate as follows:</p>
456 <li>Create a RSA private key for your server
457 (will be Triple-DES encrypted and PEM formatted):<br />
459 <code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code><br />
461 Please backup this <code>host.key</code> file and the
462 pass-phrase you entered in a secure location.
463 You can see the details of this RSA private key by using the
465 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br />
467 If necessary, you can also create a decrypted PEM version (not
468 recommended) of this RSA private key with:<br />
470 <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br />
473 <li>Create a self-signed Certificate (X509 structure)
474 with the RSA key you just created (output will be PEM formatted):<br />
476 <code><strong>$ openssl req -new -x509 -nodes -sha1 -days 365
477 -key server.key -out server.crt</strong></code><br />
479 This signs the server CSR and results in a <code>server.crt</code> file.<br />
480 You can see the details of this Certificate using:<br />
482 <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
488 <h3><a name="passphrase" id="passphrase">How can I change the pass-phrase on my private key file?</a></h3>
489 <p>You simply have to read it with the old pass-phrase and write it again,
490 specifying the new pass-phrase. You can accomplish this with the following
494 <p><code><strong>$ openssl rsa -des3 -in server.key -out server.key.new</strong></code><br />
495 <code><strong>$ mv server.key.new server.key</strong></code><br /></p>
497 <p>The first time you're asked for a PEM pass-phrase, you should
498 enter the old pass-phrase. After that, you'll be asked again to
499 enter a pass-phrase - this time, use the new pass-phrase. If you
500 are asked to verify the pass-phrase, you'll need to enter the new
501 pass-phrase a second time.</p>
504 <h3><a name="removepassphrase" id="removepassphrase">How can I get rid of the pass-phrase dialog at Apache startup time?</a></h3>
505 <p>The reason this dialog pops up at startup and every re-start
506 is that the RSA private key inside your server.key file is stored in
507 encrypted format for security reasons. The pass-phrase is needed to decrypt
508 this file, so it can be read and parsed. Removing the pass-phrase
509 removes a layer of security from your server - proceed with caution!</p>
511 <li>Remove the encryption from the RSA private key (while
512 keeping a backup copy of the original file):<br />
514 <code><strong>$ cp server.key server.key.org</strong></code><br />
515 <code><strong>$ openssl rsa -in server.key.org -out server.key</strong></code><br />
519 <li>Make sure the server.key file is only readable by root:<br />
521 <code><strong>$ chmod 400 server.key</strong></code><br />
526 <p>Now <code>server.key</code> contains an unencrypted copy of the key.
527 If you point your server at this file, it will not prompt you for a
528 pass-phrase. HOWEVER, if anyone gets this key they will be able to
529 impersonate you on the net. PLEASE make sure that the permissions on this
530 file are such that only root or the web server user can read it
531 (preferably get your web server to start as root but run as another
532 user, and have the key readable only by root).</p>
534 <p>As an alternative approach you can use the ``<code>SSLPassPhraseDialog
535 exec:/path/to/program</code>'' facility. Bear in mind that this is
536 neither more nor less secure, of course.</p>
539 <h3><a name="verify" id="verify">How do I verify that a private key matches its Certificate?</a></h3>
540 <p>A private key contains a series of numbers. Two of these numbers form
541 the "public key", the others are part of the "private key". The "public
542 key" bits are included when you generate a CSR, and subsequently form
543 part of the associated Certificate.</p>
544 <p>To check that the public key in your Certificate matches the public
545 portion of your private key, you simply need to compare these numbers.
546 To view the Certificate and the key run the commands:</p>
548 <p><code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
549 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code></p>
551 <p>The `modulus' and the `public exponent' portions in the key and the
552 Certificate must match. As the public exponent is usually 65537
553 and it's difficult to visually check that the long modulus numbers
554 are the same, you can use the following approach:</p>
556 <p><code><strong>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br />
557 <code><strong>$ openssl rsa -noout -modulus -in server.key | openssl md5</strong></code></p>
559 <p>This leaves you with two rather shorter numbers to compare. It is,
560 in theory, possible that these numbers may be the same, without the
561 modulus numbers being the same, but the chances of this are
562 overwhelmingly remote.</p>
563 <p>Should you wish to check to which key or certificate a particular
564 CSR belongs you can perform the same calculation on the CSR as
567 <p><code><strong>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code></p>
570 <h3><a name="badcert" id="badcert">Why do connections fail with an "alert
571 bad certificate" error?</a></h3>
572 <p>Errors such as <code>OpenSSL: error:14094412: SSL
573 routines:SSL3_READ_BYTES:sslv3 alert bad certificate</code> in the SSL
574 logfile, are usually caused by a browser which is unable to handle the server
575 certificate/private-key. For example, Netscape Navigator 3.x is
576 unable to handle RSA key lengths not equal to 1024 bits.</p>
579 <h3><a name="keysize" id="keysize">Why does my 2048-bit private key not work?</a></h3>
580 <p>The private key sizes for SSL must be either 512 or 1024 bits, for compatibility
581 with certain web browsers. A keysize of 1024 bits is recommended because
582 keys larger than 1024 bits are incompatible with some versions of Netscape
583 Navigator and Microsoft Internet Explorer, and with other browsers that
584 use RSA's BSAFE cryptography toolkit.</p>
587 <h3><a name="hashsymlinks" id="hashsymlinks">Why is client authentication broken after upgrading from
588 SSLeay version 0.8 to 0.9?</a></h3>
589 <p>The CA certificates under the path you configured with
590 <code>SSLCACertificatePath</code> are found by SSLeay through hash
591 symlinks. These hash values are generated by the `<code>openssl x509 -noout
592 -hash</code>' command. However, the algorithm used to calculate the hash for a
593 certificate changed between SSLeay 0.8 and 0.9. You will need to remove
594 all old hash symlinks and create new ones after upgrading. Use the
595 <code>Makefile</code> provided by <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>.</p>
598 <h3><a name="pemder" id="pemder">How can I convert a certificate from PEM to DER format?</a></h3>
599 <p>The default certificate format for SSLeay/OpenSSL is PEM, which is simply
600 Base64 encoded DER, with header and footer lines. For some applications
601 (e.g. Microsoft Internet Explorer) you need the certificate in plain DER
602 format. You can convert a PEM file <code>cert.pem</code> into the
603 corresponding DER file <code>cert.der</code> using the following command:
604 <code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code></p>
607 <h3><a name="verisign" id="verisign">Why can't I find the
608 <code>getca</code> or <code>getverisign</code> programs mentioned by
609 Verisign, for installing my Verisign certificate?</a></h3>
610 <p>Verisign has never provided specific instructions
611 for Apache+mod_ssl. The instructions provided are for C2Net's
612 Stronghold (a commercial Apache based server with SSL support).</p>
613 <p>To install your certificate, all you need to do is to save the
614 certificate to a file, and give the name of that file to the
615 <code class="directive"><a href="../mod/mod_ssl.html#sslcertificatefile">SSLCertificateFile</a></code> directive.
616 You will also need to give it the key file. For more information,
617 see the <code class="directive"><a href="../mod/mod_ssl.html#sslcertificatekeyfile">SSLCertificateKeyFile</a></code>
621 <h3><a name="sgc" id="sgc">Can I use the Server Gated Cryptography (SGC)
622 facility (aka Verisign Global ID) with mod_ssl?</a></h3>
623 <p>Yes. <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> has included support for the SGC
624 facility since version 2.1. No special configuration is required -
625 just use the Global ID as your server certificate. The
626 <em>step up</em> of the clients is then automatically handled by
627 <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> at run-time.</p>
630 <h3><a name="gid" id="gid">Why do browsers complain that they cannot
631 verify my Verisign Global ID server certificate?</a></h3>
632 <p>Verisign uses an intermediate CA certificate between the root CA
633 certificate (which is installed in the browsers) and the server
634 certificate (which you installed on the server). You should have
635 received this additional CA certificate from Verisign.
636 If not, complain to them. Then, configure this certificate with the
637 <code class="directive"><a href="../mod/mod_ssl.html#sslcertificatechainfile">SSLCertificateChainFile</a></code>
638 directive. This ensures that the intermediate CA certificate is
639 sent to the browser, filling the gap in the certificate chain.</p>
641 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
642 <div class="section">
643 <h2><a name="aboutssl" id="aboutssl">The SSL Protocol</a></h2>
645 <li><a href="#random">Why do I get lots of random SSL protocol
646 errors under heavy server load?</a></li>
647 <li><a href="#load">Why does my webserver have a higher load, now
648 that it serves SSL encrypted traffic?</a></li>
649 <li><a href="#establishing">Why do HTTPS connections to my server
650 sometimes take up to 30 seconds to establish a connection?</a></li>
651 <li><a href="#ciphers">What SSL Ciphers are supported by mod_ssl?</a></li>
652 <li><a href="#adh">Why do I get ``no shared cipher'' errors, when
653 trying to use Anonymous Diffie-Hellman (ADH) ciphers?</a></li>
654 <li><a href="#sharedciphers">Why do I get a 'no shared ciphers'
655 error when connecting to my newly installed server?</a></li>
656 <li><a href="#vhosts">Why can't I use SSL with name-based/non-IP-based
657 virtual hosts?</a></li>
658 <li><a href="#vhosts2">Why is it not possible to use Name-Based Virtual
659 Hosting to identify different SSL virtual hosts?</a></li>
660 <li><a href="#comp">How do I get SSL compression working?</a></li>
661 <li><a href="#lockicon">When I use Basic Authentication over HTTPS
662 the lock icon in Netscape browsers stays unlocked when the dialog pops up.
663 Does this mean the username/password is being sent unencrypted?</a></li>
664 <li><a href="#msie">Why do I get I/O errors when connecting via
665 HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer
667 <li><a href="#nn">Why do I get I/O errors, or the message "Netscape has
668 encountered bad data from the server", when connecting via
669 HTTPS to an Apache+mod_ssl server with Netscape Navigator?</a></li>
672 <h3><a name="random" id="random">Why do I get lots of random SSL protocol
673 errors under heavy server load?</a></h3>
674 <p>There can be a number of reasons for this, but the main one
675 is problems with the SSL session Cache specified by the
676 <code class="directive"><a href="../mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code> directive. The DBM session
677 cache is the most likely source of the problem, so using the SHM session cache (or
678 no cache at all) may help.</p>
681 <h3><a name="load" id="load">Why does my webserver have a higher load, now
682 that it serves SSL encrypted traffic?</a></h3>
683 <p>SSL uses strong cryptographic encryption, which necessitates a lot of
684 number crunching. When you request a webpage via HTTPS, everything (even
685 the images) is encrypted before it is transferred. So increased HTTPS
686 traffic leads to load increases.</p>
689 <h3><a name="establishing" id="establishing">Why do HTTPS connections to my server
690 sometimes take up to 30 seconds to establish a connection?</a></h3>
691 <p>This is usually caused by a <code>/dev/random</code> device for
692 <code class="directive"><a href="../mod/mod_ssl.html#sslrandomseed">SSLRandomSeed</a></code> which blocks the
693 read(2) call until enough entropy is available to service the
694 request. More information is available in the reference
695 manual for the <code class="directive"><a href="../mod/mod_ssl.html#sslrandomseed">SSLRandomSeed</a></code>
699 <h3><a name="ciphers" id="ciphers">What SSL Ciphers are supported by mod_ssl?</a></h3>
700 <p>Usually, any SSL ciphers supported by the version of OpenSSL in use,
701 are also supported by <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>. Which ciphers are
702 available can depend on the way you built OpenSSL. Typically, at
703 least the following ciphers are supported:</p>
706 <li>RC4 with MD5</li>
707 <li>RC4 with MD5 (export version restricted to 40-bit key)</li>
708 <li>RC2 with MD5</li>
709 <li>RC2 with MD5 (export version restricted to 40-bit key)</li>
710 <li>IDEA with MD5</li>
711 <li>DES with MD5</li>
712 <li>Triple-DES with MD5</li>
715 <p>To determine the actual list of ciphers available, you should run
717 <div class="example"><p><code>$ openssl ciphers -v</code></p></div>
720 <h3><a name="adh" id="adh">Why do I get ``no shared cipher'' errors, when
721 trying to use Anonymous Diffie-Hellman (ADH) ciphers?</a></h3>
722 <p>By default, OpenSSL does <em>not</em> allow ADH ciphers, for security
723 reasons. Please be sure you are aware of the potential side-effects
724 if you choose to enable these ciphers.</p>
725 <p>In order to use Anonymous Diffie-Hellman (ADH) ciphers, you must
726 build OpenSSL with ``<code>-DSSL_ALLOW_ADH</code>'', and then add
727 ``<code>ADH</code>'' into your <code class="directive"><a href="../mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code>.</p>
730 <h3><a name="sharedciphers" id="sharedciphers">Why do I get a 'no shared ciphers'
731 error when connecting to my newly installed server?</a></h3>
732 <p>Either you have made a mistake with your
733 <code class="directive"><a href="../mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code>
734 directive (compare it with the pre-configured example in
735 <code>httpd.conf-dist</code>) or you chose to use DSA/DH
736 algorithms instead of RSA when you generated your private key
737 and ignored or overlooked the warnings. If you have chosen
738 DSA/DH, then your server cannot communicate using RSA-based SSL
739 ciphers (at least until you configure an additional RSA-based
740 certificate/key pair). Modern browsers like NS or IE can only
741 communicate over SSL using RSA ciphers. The result is the
742 "no shared ciphers" error. To fix this, regenerate your server
743 certificate/key pair, using the RSA algorithm.</p>
746 <h3><a name="vhosts" id="vhosts">Why can't I use SSL with name-based/non-IP-based virtual hosts?</a></h3>
747 <p>The reason is very technical, and a somewhat "chicken and egg" problem.
748 The SSL protocol layer stays below the HTTP protocol layer and
749 encapsulates HTTP. When an SSL connection (HTTPS) is established
750 Apache/mod_ssl has to negotiate the SSL protocol parameters with the
751 client. For this, mod_ssl has to consult the configuration of the virtual
752 server (for instance it has to look for the cipher suite, the server
753 certificate, etc.). But in order to go to the correct virtual server
754 Apache has to know the <code>Host</code> HTTP header field. To do this, the
755 HTTP request header has to be read. This cannot be done before the SSL
756 handshake is finished, but the information is needed in order to
757 complete the SSL handshake phase. Bingo!</p>
760 <h3><a name="vhosts2" id="vhosts2">Why is it not possible to use Name-Based
761 Virtual Hosting to identify different SSL virtual hosts?</a></h3>
762 <p>Name-Based Virtual Hosting is a very popular method of identifying
763 different virtual hosts. It allows you to use the same IP address and
764 the same port number for many different sites. When people move on to
765 SSL, it seems natural to assume that the same method can be used to have
766 lots of different SSL virtual hosts on the same server.</p>
768 <p>It comes as rather a shock to learn that it is impossible.</p>
770 <p>The reason is that the SSL protocol is a separate layer which
771 encapsulates the HTTP protocol. So the SSL session is a separate
772 transaction, that takes place before the HTTP session has begun.
773 The server receives an SSL request on IP address X and port Y
774 (usually 443). Since the SSL request does not contain any Host:
775 field, the server has no way to decide which SSL virtual host to use.
776 Usually, it will just use the first one it finds, which matches the
777 port and IP address specified.</p>
779 <p>You can, of course, use Name-Based Virtual Hosting to identify many
780 non-SSL virtual hosts (all on port 80, for example) and then
781 have a single SSL virtual host (on port 443). But if you do this,
782 you must make sure to put the non-SSL port number on the NameVirtualHost
785 <div class="example"><p><code>
786 NameVirtualHost 192.168.1.1:80
789 <p>Other workaround solutions include: </p>
791 <p>Using separate IP addresses for different SSL hosts.
792 Using different port numbers for different SSL hosts.</p>
795 <h3><a name="comp" id="comp">How do I get SSL compression working?</a></h3>
796 <p>Although SSL compression negotiation was defined in the specification
797 of SSLv2 and TLS, it took until May 2004 for RFC 3749 to define DEFLATE as
798 a negotiable standard compression method.
800 <p>OpenSSL 0.9.8 started to support this by default when compiled with the
801 <code>zlib</code> option. If both the client and the server support compression,
802 it will be used. However, most clients still try to initially connect with an
803 SSLv2 Hello. As SSLv2 did not include an array of prefered compression algorithms
804 in its handshake, compression cannot be negotiated with these clients.
805 If the client disables support for SSLv2, either an SSLv3 or TLS Hello
806 may be sent, depending on which SSL library is used, and compression may
807 be set up. You can verify whether clients make use of SSL compression by
808 logging the <code>%{SSL_COMPRESS_METHOD}x</code> variable.
812 <h3><a name="lockicon" id="lockicon">When I use Basic Authentication over HTTPS
813 the lock icon in Netscape browsers stays unlocked when the dialog pops up.
814 Does this mean the username/password is being sent unencrypted?</a></h3>
815 <p>No, the username/password is transmitted encrypted. The icon in
816 Netscape browsers is not actually synchronized with the SSL/TLS layer.
817 It only toggles to the locked state when the first part of the actual
818 webpage data is transferred, which may confuse people. The Basic
819 Authentication facility is part of the HTTP layer, which is above
820 the SSL/TLS layer in HTTPS. Before any HTTP data communication takes
821 place in HTTPS, the SSL/TLS layer has already completed its handshake
822 phase, and switched to encrypted communication. So don't be
823 confused by this icon.</p>
826 <h3><a name="msie" id="msie">Why do I get I/O errors when connecting via
827 HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer (MSIE)?</a></h3>
828 <p>The first reason is that the SSL implementation in some MSIE versions has
829 some subtle bugs related to the HTTP keep-alive facility and the SSL close
830 notify alerts on socket connection close. Additionally the interaction
831 between SSL and HTTP/1.1 features are problematic in some MSIE versions.
832 You can work around these problems by forcing Apache not to use HTTP/1.1,
833 keep-alive connections or send the SSL close notify messages to MSIE clients.
834 This can be done by using the following directive in your SSL-aware
835 virtual host section:</p>
836 <div class="example"><p><code>
837 SetEnvIf User-Agent ".*MSIE.*" \<br />
838 nokeepalive ssl-unclean-shutdown \<br />
839 downgrade-1.0 force-response-1.0
841 <p>Further, some MSIE versions have problems with particular ciphers.
842 Unfortunately, it is not possible to implement a MSIE-specific
843 workaround for this, because the ciphers are needed as early as the
844 SSL handshake phase. So a MSIE-specific
845 <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> won't solve these
846 problems. Instead, you will have to make more drastic
847 adjustments to the global parameters. Before you decide to do
848 this, make sure your clients really have problems. If not, do not
849 make these changes - they will affect <em>all</em> your clients, MSIE
852 <p>The next problem is that 56bit export versions of MSIE 5.x
853 browsers have a broken SSLv3 implementation, which interacts badly
854 with OpenSSL versions greater than 0.9.4. You can accept this and
855 require your clients to upgrade their browsers, you can downgrade to
856 OpenSSL 0.9.4 (not advised), or you can work around this, accepting
857 that your workaround will affect other browsers too:</p>
858 <div class="example"><p><code>SSLProtocol all -SSLv3</code></p></div>
859 <p>will completely disables the SSLv3 protocol and allow those
860 browsers to work. A better workaround is to disable only those
861 ciphers which cause trouble.</p>
862 <div class="example"><p><code>SSLCipherSuite
863 ALL:!ADH:<strong>!EXPORT56</strong>:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>
866 <p>This also allows the broken MSIE versions to work, but only removes the
867 newer 56bit TLS ciphers.</p>
869 <p>Another problem with MSIE 5.x clients is that they refuse to connect to
870 URLs of the form <code>https://12.34.56.78/</code> (where IP-addresses are used
871 instead of the hostname), if the server is using the Server Gated
872 Cryptography (SGC) facility. This can only be avoided by using the fully
873 qualified domain name (FQDN) of the website in hyperlinks instead, because
874 MSIE 5.x has an error in the way it handles the SGC negotiation.</p>
876 <p>And finally there are versions of MSIE which seem to require that
877 an SSL session can be reused (a totally non standard-conforming
878 behaviour, of course). Connecting with those MSIE versions only work
879 if a SSL session cache is used. So, as a work-around, make sure you
880 are using a session cache (see the <code class="directive"><a href="../mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code> directive).</p>
883 <h3><a name="nn" id="nn">Why do I get I/O errors, or the message "Netscape has
884 encountered bad data from the server", when connecting via
885 HTTPS to an Apache+mod_ssl server with Netscape Navigator?</a></h3>
887 This usually occurs when you have created a new server certificate for
888 a given domain, but had previously told your browser to always accept
889 the old server certificate. Once you clear the entry for the old
890 certificate from your browser, everything should be fine. Netscape's SSL
891 implementation is correct, so when you encounter I/O errors with Netscape
892 Navigator it is usually caused by the configured certificates.</p>
894 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
895 <div class="section">
896 <h2><a name="support" id="support">mod_ssl Support</a></h2>
898 <li><a href="#resources">What information resources are available in
899 case of mod_ssl problems?</a></li>
900 <li><a href="#contact">What support contacts are available in case of
901 mod_ssl problems?</a></li>
902 <li><a href="#reportdetails">What information should I
903 provide when writing a bug report?</a></li>
904 <li><a href="#coredumphelp">I had a core dump, can you help me?</a></li>
905 <li><a href="#backtrace">How do I get a backtrace, to help find the reason
906 for my core dump?</a></li>
909 <h3><a name="resources" id="resources">What information resources are available in case of mod_ssl problems?</a></h3>
910 <p>The following information resources are available.
911 In case of problems you should search here first.</p>
914 <dt>Answers in the User Manual's F.A.Q. List (this)</dt>
915 <dd><a href="http://httpd.apache.org/docs/2.0/ssl/ssl_faq.html">
916 http://httpd.apache.org/docs/2.0/ssl/ssl_faq.html</a><br />
917 First check the F.A.Q. (this text). If your problem is a common
918 one, it may have been answered several times before, and been included
921 <dt>Postings from the modssl-users Support Mailing List
922 <a href="http://www.modssl.org/support/">http://www.modssl.org/support/</a></dt>
923 <dd>Search for your problem in the archives of the modssl-users mailing list.
924 You're probably not the first person to have had this problem!
929 <h3><a name="contact" id="contact">What support contacts are available in case
930 of mod_ssl problems?</a></h3>
931 <p>The following lists all support possibilities for mod_ssl, in order of
932 preference. Please go through these possibilities
933 <em>in this order</em> - don't just pick the one you like the look of. </p>
935 <li><em>Send a Problem Report to the modssl-users Support Mailing List</em><br />
936 <a href="mailto:modssl-users@modssl.org">
937 modssl-users@modssl.org</a><br />
938 This is the preferred way of submitting your problem report, because this way,
939 others can see the problem, and learn from any answers. You must subscribe to
940 the list first, but you can then easily discuss your problem with both the
941 author and the whole mod_ssl user community.
944 <li><em>Send a Problem Report to the Apache httpd Users Support Mailing List</em><br />
945 <a href="mailto:users@httpd.apache.org">
946 users@httpd.apache.org</a><br />
947 This is the second way of submitting your problem report. Again, you must
948 subscribe to the list first, but you can then easily discuss your problem
949 with the whole Apache httpd user community.
952 <li><em>Write a Problem Report in the Bug Database</em><br />
953 <a href="http://httpd.apache.org/bug_report.html">
954 http://httpd.apache.org/bug_report.html</a><br />
955 This is the last way of submitting your problem report. You should only
956 do this if you've already posted to the mailing lists, and had no success.
957 Please follow the instructions on the above page <em>carefully</em>.
962 <h3><a name="reportdetails" id="reportdetails">What information should I
963 provide when writing a bug report?</a></h3>
964 <p>You should always provide at least the following information:</p>
967 <dt>Apache and OpenSSL version information</dt>
968 <dd>The Apache version can be determined
969 by running <code>httpd -v</code>. The OpenSSL version can be
970 determined by running <code>openssl version</code>. Alternatively, if
971 you have Lynx installed, you can run the command <code>lynx -mime_header
972 http://localhost/ | grep Server</code> to gather this information in a
976 <dt>The details on how you built and installed Apache+mod_ssl+OpenSSL</dt>
977 <dd>For this you can provide a logfile of your terminal session which shows
978 the configuration and install steps. If this is not possible, you
979 should at least provide the <code class="program"><a href="../programs/configure.html">configure</a></code> command line you used.
982 <dt>In case of core dumps please include a Backtrace</dt>
983 <dd>If your Apache+mod_ssl+OpenSSL dumps its core, please attach
984 a stack-frame ``backtrace'' (see <a href="#backtrace">below</a>
985 for information on how to get this). This information is required
986 in order to find a reason for your core dump.
989 <dt>A detailed description of your problem</dt>
990 <dd>Don't laugh, we really mean it! Many problem reports don't
991 include a description of what the actual problem is. Without this,
992 it's very difficult for anyone to help you. So, it's in your own
993 interest (you want the problem be solved, don't you?) to include as
994 much detail as possible, please. Of course, you should still include
995 all the essentials above too.
1000 <h3><a name="coredumphelp" id="coredumphelp">I had a core dump, can you help me?</a></h3>
1001 <p>In general no, at least not unless you provide more details about the code
1002 location where Apache dumped core. What is usually always required in
1003 order to help you is a backtrace (see next question). Without this
1004 information it is mostly impossible to find the problem and help you in
1008 <h3><a name="backtrace" id="backtrace">How do I get a backtrace, to help find
1009 the reason for my core dump?</a></h3>
1010 <p>Following are the steps you will need to complete, to get a backtrace:</p>
1012 <li>Make sure you have debugging symbols available, at least
1013 in Apache. On platforms where you use GCC/GDB, you will have to build
1014 Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to get this. On
1015 other platforms at least ``<code>OPTIM="-g"</code>'' is needed.
1018 <li>Start the server and try to reproduce the core-dump. For this you may
1019 want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to
1020 make sure that the core-dump file can be written. This should result
1021 in a <code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. If you
1022 don't get one of these, try running your server under a non-root UID.
1023 Many modern kernels do not allow a process to dump core after it has
1024 done a <code>setuid()</code> (unless it does an <code>exec()</code>) for
1025 security reasons (there can be privileged information left over in
1026 memory). If necessary, you can run <code>/path/to/httpd -X</code>
1027 manually to force Apache to not fork.
1030 <li>Analyze the core-dump. For this, run <code>gdb /path/to/httpd
1031 /tmp/httpd.core</code> or a similar command. In GDB, all you
1032 have to do then is to enter <code>bt</code>, and voila, you get the
1033 backtrace. For other debuggers consult your local debugger manual.
1038 <div class="bottomlang">
1039 <p><span>Available Languages: </span><a href="../en/ssl/ssl_faq.html" title="English"> en </a></p>
1040 </div><div id="footer">
1041 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
1042 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
Code Review / bottlenecks.git / blob