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.1</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-project/">Documentation</a> > <a href="../">Version 2.1</a> > <a href="./">SSL/TLS</a></div><div id="page-content"><div id="preamble"><h1>SSL/TLS Strong Encryption: FAQ</h1>
21 <p>The wise man doesn't give the right answers,
22 he poses the right questions.</p>
23 <p class="cite">-- <cite>Claude Levi-Strauss</cite></p>
26 <p>This chapter is a collection of frequently asked questions (FAQ) and
27 corresponding answers following the popular USENET tradition. Most of these
28 questions occured on the Newsgroup <code><a href="news:comp.infosystems.www.servers.unix">comp.infosystems.www.servers.unix</a></code> or the mod_ssl Support
29 Mailing List <code><a href="mailto:modssl-users@modssl.org">modssl-users@modssl.org</a></code>. They are collected at this place
30 to avoid answering the same questions over and over.</p>
32 <p>Please read this chapter at least once when installing mod_ssl or at least
33 search for your problem here before submitting a problem report to the
36 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#about">About The Module</a></li>
37 <li><img alt="" src="../images/down.gif" /> <a href="#installation">About Installation</a></li>
38 <li><img alt="" src="../images/down.gif" /> <a href="#aboutconfig">About Configuration</a></li>
39 <li><img alt="" src="../images/down.gif" /> <a href="#aboutcerts">About Certificates</a></li>
40 <li><img alt="" src="../images/down.gif" /> <a href="#aboutssl">About SSL Protocol</a></li>
41 <li><img alt="" src="../images/down.gif" /> <a href="#support">About Support</a></li>
43 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
45 <h2><a name="about" id="about">About The Module</a></h2>
47 <li><a href="#history">What is the history of mod_ssl?</a></li>
48 <li><a href="#y2k">mod_ssl and Year 2000?</a></li>
49 <li><a href="#wassenaar">mod_ssl and Wassenaar Arrangement?</a></li>
52 <h3><a name="history" id="history">What is the history of mod_ssl?</a></h3>
53 <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
54 Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben
55 Laurie's development cycle it then was re-assembled from scratch for
56 Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL
57 1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The
58 first publically released version was mod_ssl 2.0.0 from August 10th,
59 1998. As of this writing (August 1999) the current mod_ssl version
63 <p>After one year of very active development with over 1000 working hours and
64 over 40 releases mod_ssl reached its current state. The result is an
65 already very clean source base implementing a very rich functionality.
66 The code size increased by a factor of 4 to currently a total of over
67 10.000 lines of ANSI C consisting of approx. 70% code and 30% code
68 documentation. From the original Apache-SSL code currently approx. 5% is
71 <p>After the US export restrictions for cryptographic software were
72 opened, mod_ssl was integrated into the code base of Apache V2 in 2001.</p>
75 <h3><a name="y2k" id="y2k">Is mod_ssl Year 2000 compliant?</a></h3>
76 <p>Yes, mod_ssl is Year 2000 compliant.</p>
78 <p>Because first mod_ssl internally never stores years as two digits.
79 Instead it always uses the ANSI C & POSIX numerical data type
80 <code>time_t</code> type, which on almost all Unix platforms at the moment
81 is a <code>signed long</code> (usually 32-bits) representing seconds since
82 epoch of January 1st, 1970, 00:00 UTC. This signed value overflows in
83 early January 2038 and not in the year 2000. Second, date and time
84 presentations (for instance the variable ``<code>%{TIME_YEAR}</code>'')
85 are done with full year value instead of abbreviating to two digits.</p>
88 <p>Additionally according to a <a href="http://www.apache.org/docs/misc/FAQ.html#year2000">Year 2000
89 statement</a> from the Apache Group, the Apache webserver is Year 2000
90 compliant, too. But whether OpenSSL or the underlaying Operating System
91 (either a Unix or Win32 platform) is Year 2000 compliant is a different
92 question which cannot be answered here.</p>
95 <h3><a name="wassenaar" id="wassenaar">What about mod_ssl and the Wassenaar Arrangement?</a></h3>
96 <p>First, let us explain what <dfn>Wassenaar</dfn> and its <dfn>Arrangement on
97 Export Controls for Conventional Arms and Dual-Use Goods and
98 Technologies</dfn> is: This is a international regime, established 1995, to
99 control trade in conventional arms and dual-use goods and technology. It
100 replaced the previous <dfn>CoCom</dfn> regime. 33 countries are signatories:
101 Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic,
102 Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan,
103 Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Republic
104 of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden,
105 Switzerland, Turkey, Ukraine, United Kingdom and United States. For more
106 details look at <a href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>.</p>
109 <p>In short: The aim of the Wassenaar Arrangement is to prevent the build up
110 of military capabilities that threaten regional and international security
111 and stability. The Wassenaar Arrangement controls the export of
112 cryptography as a dual-use good, i.e., one that has both military and
113 civilian applications. However, the Wassenaar Arrangement also provides an
114 exemption from export controls for mass-market software and free software.</p>
116 <p>In the current Wassenaar <cite>List of Dual Use Goods and Technologies And
117 Munitions</cite>, under <q>GENERAL SOFTWARE NOTE (GSN)</q> it says
118 <q>The Lists do not control "software" which is either: 1. [...] 2. "in
119 the public domain".</q> And under <q>DEFINITIONS OF TERMS USED IN
120 THESE LISTS</q> one can find the definition: <q>In the public
121 domain": This means "technology" or "software" which has been made
122 available without restrictions upon its further dissemination. N.B.
123 Copyright restrictions do not remove "technology" or "software" from being
124 "in the public domain".</q></p>
126 <p>So, both mod_ssl and OpenSSL are <q>in the public domain</q> for the purposes
127 of the Wassenaar Agreement and its <q>List of Dual Use Goods and
128 Technologies And Munitions List</q>.</p>
131 <p>Additionally the Wassenaar Agreement itself has no direct consequence for
132 exporting cryptography software. What is actually allowed or forbidden to
133 be exported from the countries has still to be defined in the local laws
134 of each country. And at least according to official press releases from
135 the German BMWi (see <a href="http://www.bmwi.de/presse/1998/1208prm2.html">here</a>) and the
136 Switzerland Bawi (see <a href="http://jya.com/wass-ch.htm">here</a>) there
137 will be no forthcoming export restriction for free cryptography software
138 for their countries. Remember that mod_ssl is created in Germany and
139 distributed from Switzerland.</p>
141 <p>So, mod_ssl and OpenSSL are not affected by the Wassenaar Agreement.</p>
143 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
144 <div class="section">
145 <h2><a name="installation" id="installation">About Installation</a></h2>
147 <li><a href="#coredump">Core dumps for HTTPS requests?</a></li>
148 <li><a href="#mutex">Permission problem on SSLMutex</a></li>
149 <li><a href="#mm">Shared memory and process size?</a></li>
150 <li><a href="#entropy">PRNG and not enough entropy?</a></li>
153 <h3><a name="coredump" id="coredump">When I access my website the first time via HTTPS I get a core dump?</a></h3>
154 <p>There can be a lot of reasons why a core dump can occur, of course.
155 Ranging from buggy third-party modules, over buggy vendor libraries up to
156 a buggy mod_ssl version. But the above situation is often caused by old or
157 broken vendor DBM libraries. To solve it either build mod_ssl with the
158 built-in SDBM library (specify <code>--enable-rule=SSL_SDBM</code> at the
159 APACI command line) or switch from <code>SSLSessionCache dbm:</code> to the
160 newer <code>SSLSessionCache shm:</code>'' variant (after you have rebuilt
161 Apache with MM, of course).</p>
164 <h3><a name="mutex" id="mutex">When I startup Apache I get permission errors related to SSLMutex?</a></h3>
165 <p>When you receive entries like ``<code>mod_ssl: Child could not open
166 SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows)
167 [...] System: Permission denied (errno: 13)</code>'' this is usually
168 caused by to restrictive permissions on the <em>parent</em> directories.
169 Make sure that all parent directories (here <code>/opt</code>,
170 <code>/opt/apache</code> and <code>/opt/apache/logs</code>) have the x-bit
171 set at least for the UID under which Apache's children are running (see
172 the <code class="directive"><a href="../mod/mpm_common.html#user">User</a></code> directive of Apache).</p>
175 <h3><a name="mm" id="mm">When I use the MM library and the shared memory cache each process grows
176 1.5MB according to `top' although I specified 512000 as the cache size?</a></h3>
177 <p>The additional 1MB are caused by the global shared memory pool Apache
178 allocates for all modules and which is not used by mod_ssl for
179 various reasons. So the actually allocated shared memory is always
180 1MB more than what you specify on <code class="directive"><a href="../mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code>.
181 But don't be confused by the display of `top': although is
182 indicates that <em>each</em> process grow, this is not reality, of
183 course. Instead the additional memory consumption is shared by
184 all processes, i.e. the 1.5MB are allocated only once per Apache
185 instance and not once per Apache server process.</p>
188 <h3><a name="entropy" id="entropy">When I fire up the server, mod_ssl stops with the error
189 "Failed to generate temporary 512 bit RSA private key", why?</a></h3>
190 <p>Cryptographic software needs a source of unpredictable data
191 to work correctly. Many open source operating systems provide
192 a "randomness device" that serves this purpose (usually named
193 <code>/dev/random</code>). On other systems, applications have to
194 seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with
195 appropriate data before generating keys or performing public key
196 encryption. As of version 0.9.5, the OpenSSL functions that need
197 randomness report an error if the PRNG has not been seeded with
198 at least 128 bits of randomness. So mod_ssl has to provide enough
199 entropy to the PRNG to work correctly. For this one has to use the
200 <code>SSLRandomSeed</code> directives.</p>
202 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
203 <div class="section">
204 <h2><a name="aboutconfig" id="aboutconfig">About Configuration</a></h2>
206 <li><a href="#parallel">HTTP and HTTPS with a single server?</a></li>
207 <li><a href="#ports">Where is the HTTPS port?</a></li>
208 <li><a href="#httpstest">How to test HTTPS manually?</a></li>
209 <li><a href="#hang">Why does my connection hang?</a></li>
210 <li><a href="#refused">Why do I get connection refused?</a></li>
211 <li><a href="#envvars">Why are the <code>SSL_XXX</code> variables missing?</a></li>
212 <li><a href="#relative">How to switch with relative hyperlinks?</a></li>
215 <h3><a name="parallel" id="parallel">Is it possible to provide HTTP and HTTPS with a single server?</a></h3>
216 <p>Yes, HTTP and HTTPS use different server ports, so there is no direct
217 conflict between them. Either run two separate server instances (one binds
218 to port 80, the other to port 443) or even use Apache's elegant virtual
219 hosting facility where you can easily create two virtual servers which
220 Apache dispatches: one responding to port 80 and speaking HTTP and one
221 responding to port 443 speaking HTTPS.</p>
224 <h3><a name="ports" id="ports">I know that HTTP is on port 80, but where is HTTPS?</a></h3>
225 <p>You can run HTTPS on any port, but the standards specify port 443, which
226 is where any HTTPS compliant browser will look by default. You can force
227 your browser to look on a different port by specifying it in the URL like
228 this (for port 666): <code>https://secure.server.dom:666/</code></p>
231 <h3><a name="httpstest" id="httpstest">How can I speak HTTPS manually for testing purposes?</a></h3>
232 <p>While you usually just use</p>
234 <div class="example"><p><code>$ telnet localhost 80<br />
235 GET / HTTP/1.0</code></p></div>
238 <p>for simple testing the HTTP protocol of Apache, it's not so easy for
239 HTTPS because of the SSL protocol between TCP and HTTP. But with the
240 help of OpenSSL's <code>s_client</code> command you can do a similar
241 check even for HTTPS:</p>
243 <div class="example"><p><code>$ openssl s_client -connect localhost:443 -state -debug<br />
244 GET / HTTP/1.0</code></p></div>
246 <p>Before the actual HTTP response you receive detailed information about the
247 SSL handshake. For a more general command line client which directly
248 understands both the HTTP and HTTPS scheme, can perform GET and POST
249 methods, can use a proxy, supports byte ranges, etc. you should have a
250 look at nifty <a href="http://curl.haxx.se/">cURL</a>
251 tool. With it you can directly check if your Apache is running fine on
252 Port 80 and 443 as following:</p>
254 <div class="example"><p><code>$ curl http://localhost/<br />
255 $ curl https://localhost/</code></p></div>
258 <h3><a name="hang" id="hang">Why does the connection hang when I connect to my SSL-aware Apache server?</a></h3>
259 <p>Because you connected with HTTP to the HTTPS port, i.e. you used an URL of
260 the form ``<code>http://</code>'' instead of ``<code>https://</code>''.
261 This also happens the other way round when you connect via HTTPS to a HTTP
262 port, i.e. when you try to use ``<code>https://</code>'' on a server that
263 doesn't support SSL (on this port). Make sure you are connecting to a
264 virtual server that supports SSL, which is probably the IP associated with
265 your hostname, not localhost (127.0.0.1).</p>
268 <h3><a name="refused" id="refused">Why do I get ``Connection Refused'' messages when trying to access my freshly
269 installed Apache+mod_ssl server via HTTPS?</a></h3>
270 <p>There can be various reasons. Some of the common mistakes is that people
271 start Apache with just ``<code>apachectl start</code>'' (or
272 ``<code>httpd</code>'') instead of ``<code>apachectl startssl</code>'' (or
273 ``<code>httpd -DSSL</code>''. Or you're configuration is not correct. At
274 least make sure that your <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code>
275 directives match your <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>
276 directives. And if all fails, please do yourself a favor and start over with the
277 default configuration mod_ssl provides you.</p>
280 <h3><a name="envvars" id="envvars">In my CGI programs and SSI scripts the various documented
281 <code>SSL_XXX</code> variables do not exist. Why?</a></h3>
282 <p>Just make sure you have ``<code>SSLOptions +StdEnvVars</code>''
283 enabled for the context of your CGI/SSI requests.</p>
286 <h3><a name="relative" id="relative">How can I use relative hyperlinks to switch between HTTP and
289 <p>Usually you have to use fully-qualified hyperlinks because
290 you have to change the URL scheme. But with the help of some URL
291 manipulations through mod_rewrite you can achieve the same effect while
292 you still can use relative URLs:</p>
293 <div class="example"><p><code>
294 RewriteEngine on<br />
295 RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L]<br />
296 RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L]
299 <p>This rewrite ruleset lets you use hyperlinks of the form
300 <code><a href="document.html:SSL"></code></p>
302 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
303 <div class="section">
304 <h2><a name="aboutcerts" id="aboutcerts">About Certificates</a></h2>
306 <li><a href="#keyscerts">What are Keys, CSRs and Certs?</a></li>
307 <li><a href="#startup">Difference on startup?</a></li>
308 <li><a href="#realcert">How to create a real cert?</a></li>
309 <li><a href="#ownca">How to create my own CA?</a></li>
310 <li><a href="#passphrase">How to change a pass phrase?</a></li>
311 <li><a href="#removepassphrase">How to remove a pass phrase?</a></li>
312 <li><a href="#verify">How to verify a key/cert pair?</a></li>
313 <li><a href="#badcert">Bad Certificate Error?</a></li>
314 <li><a href="#keysize">Why does a 2048-bit key not work?</a></li>
315 <li><a href="#hashsymlinks">Why is client auth broken?</a></li>
316 <li><a href="#pemder">How to convert from PEM to DER?</a></li>
317 <li><a href="#verisign">Verisign and the magic getca program?</a></li>
318 <li><a href="#sgc">Global IDs or SGC?</a></li>
319 <li><a href="#gid">Global IDs and Cert Chain?</a></li>
322 <h3><a name="keyscerts" id="keyscerts">What are RSA Private Keys, CSRs and Certificates?</a></h3>
323 <p>The RSA private key file is a digital file that you can use to decrypt
324 messages sent to you. It has a public component which you distribute (via
325 your Certificate file) which allows people to encrypt those messages to
326 you. A Certificate Signing Request (CSR) is a digital file which contains
327 your public key and your name. You send the CSR to a Certifying Authority
328 (CA) to be converted into a real Certificate. A Certificate contains your
329 RSA public key, your name, the name of the CA, and is digitally signed by
330 your CA. Browsers that know the CA can verify the signature on that
331 Certificate, thereby obtaining your RSA public key. That enables them to
332 send messages which only you can decrypt.
333 See the <a href="ssl_intro.html">Introduction</a> chapter for a general
334 description of the SSL protocol.</p>
337 <h3><a name="startup" id="startup">Seems like there is a difference on startup between the original Apache and an SSL-aware Apache?</a></h3>
338 <p>Yes, in general, starting Apache with a built-in mod_ssl is just like
339 starting an unencumbered Apache, except for the fact that when you have a
340 pass phrase on your SSL private key file. Then a startup dialog pops up
341 asking you to enter the pass phrase.</p>
343 <p>To type in the pass phrase manually when starting the server can be
344 problematic, for instance when starting the server from the system boot
345 scripts. As an alternative to this situation you can follow the steps
346 below under ``How can I get rid of the pass-phrase dialog at Apache
350 <h3><a name="realcert" id="realcert">Ok, I've got my server installed and want to create a real SSL
351 server Certificate for it. How do I do it?</a></h3>
352 <p>Here is a step-by-step description:</p>
355 <li>Make sure OpenSSL is really installed and in your <code>PATH</code>.
356 But some commands even work ok when you just run the
357 ``<code>openssl</code>'' program from within the OpenSSL source tree as
358 ``<code>./apps/openssl</code>''.<br />
362 <li>Create a RSA private key for your Apache server
363 (will be Triple-DES encrypted and PEM formatted):<br />
365 <code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code><br />
367 Please backup this <code>server.key</code> file and remember the
368 pass-phrase you had to enter at a secure location.
369 You can see the details of this RSA private key via the command:<br />
372 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br />
374 And you could create a decrypted PEM version (not recommended)
375 of this RSA private key via:<br />
377 <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br />
381 <li>Create a Certificate Signing Request (CSR) with the server RSA private
382 key (output will be PEM formatted):<br />
384 <code><strong>$ openssl req -new -key server.key -out server.csr</strong></code><br />
386 Make sure you enter the FQDN ("Fully Qualified Domain Name") of the
387 server when OpenSSL prompts you for the "CommonName", i.e. when you
388 generate a CSR for a website which will be later accessed via
389 <code>https://www.foo.dom/</code>, enter "www.foo.dom" here.
390 You can see the details of this CSR via the command<br />
393 <code><strong>$ openssl req -noout -text -in server.csr</strong></code><br />
396 <li>You now have to send this Certificate Signing Request (CSR) to
397 a Certifying Authority (CA) for signing. The result is then a real
398 Certificate which can be used for Apache. Here you have two options:
399 First you can let the CSR sign by a commercial CA like Verisign or
400 Thawte. Then you usually have to post the CSR into a web form, pay for
401 the signing and await the signed Certificate you then can store into a
402 server.crt file. For more information about commercial CAs have a look
403 at the following locations:<br />
408 <a href="http://digitalid.verisign.com/server/apacheNotice.htm">
409 http://digitalid.verisign.com/server/apacheNotice.htm
412 <li> Thawte Consulting<br />
413 <a href="http://www.thawte.com/certs/server/request.html">
414 http://www.thawte.com/certs/server/request.html
418 <li> CertiSign Certificadora Digital Ltda.<br />
419 <a href="http://www.certisign.com.br">
420 http://www.certisign.com.br
424 <a href="http://www.iks-jena.de/produkte/ca/">
426 http://www.iks-jena.de/produkte/ca/
429 <li> Uptime Commerce Ltd.<br />
430 <a href="http://www.uptimecommerce.com">
431 http://www.uptimecommerce.com
434 <li> BelSign NV/SA<br />
436 <a href="http://www.belsign.be">
437 http://www.belsign.be
442 Second you can use your own CA and now have to sign the CSR yourself by
443 this CA. Read the next answer in this FAQ on how to sign a CSR with
445 You can see the details of the received Certificate via the command:<br />
447 <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
450 <li>Now you have two files: <code>server.key</code> and
451 <code>server.crt</code>. These now can be used as following inside your
452 Apache's <code>httpd.conf</code> file:
454 SSLCertificateFile /path/to/this/server.crt
455 SSLCertificateKeyFile /path/to/this/server.key
457 The <code>server.csr</code> file is no longer needed.
463 <h3><a name="ownca" id="ownca">How can I create and use my own Certificate Authority (CA)?</a></h3>
464 <p>The short answer is to use the <code>CA.sh</code> or <code>CA.pl</code>
466 script provided by OpenSSL. The long and manual answer is this:</p>
469 <li>Create a RSA private key for your CA
470 (will be Triple-DES encrypted and PEM formatted):<br />
472 <code><strong>$ openssl genrsa -des3 -out ca.key 1024</strong></code><br />
474 Please backup this <code>ca.key</code> file and remember the
475 pass-phrase you currently entered at a secure location.
476 You can see the details of this RSA private key via the command<br />
479 <code><strong>$ openssl rsa -noout -text -in ca.key</strong></code><br />
481 And you can create a decrypted PEM version (not recommended) of this
482 private key via:<br />
484 <code><strong>$ openssl rsa -in ca.key -out ca.key.unsecure</strong></code><br />
488 <li>Create a self-signed CA Certificate (X509 structure)
489 with the RSA key of the CA (output will be PEM formatted):<br />
491 <code><strong>$ openssl req -new -x509 -days 365 -key ca.key -out ca.crt</strong></code><br />
493 You can see the details of this Certificate via the command:<br />
496 <code><strong>$ openssl x509 -noout -text -in ca.crt</strong></code><br />
499 <li>Prepare a script for signing which is needed because
500 the ``<code>openssl ca</code>'' command has some strange requirements
501 and the default OpenSSL config doesn't allow one easily to use
502 ``<code>openssl ca</code>'' directly. So a script named
503 <code>sign.sh</code> is distributed with the mod_ssl distribution
504 (subdir <code>pkg.contrib/</code>). Use this script for signing.
507 <li>Now you can use this CA to sign server CSR's in order to create real
508 SSL Certificates for use inside an Apache webserver (assuming
509 you already have a <code>server.csr</code> at hand):<br />
511 <code><strong>$ ./sign.sh server.csr</strong></code><br />
513 This signs the server CSR and results in a <code>server.crt</code> file.<br />
520 <h3><a name="passphrase" id="passphrase">How can I change the pass-phrase on my private key file?</a></h3>
521 <p>You simply have to read it with the old pass-phrase and write it again
522 by specifying the new pass-phrase. You can accomplish this with the following
526 <p><code><strong>$ openssl rsa -des3 -in server.key -out server.key.new</strong></code><br />
527 <code><strong>$ mv server.key.new server.key</strong></code><br /></p>
529 <p>Here you're asked two times for a PEM pass-phrase. At the first
530 prompt enter the old pass-phrase and at the second prompt
531 enter the new pass-phrase.</p>
534 <h3><a name="removepassphrase" id="removepassphrase">How can I get rid of the pass-phrase dialog at Apache startup time?</a></h3>
535 <p>The reason why this dialog pops up at startup and every re-start
536 is that the RSA private key inside your server.key file is stored in
537 encrypted format for security reasons. The pass-phrase is needed to be
538 able to read and parse this file. When you can be sure that your server is
539 secure enough you perform two steps:</p>
542 <li>Remove the encryption from the RSA private key (while
543 preserving the original file):<br />
545 <code><strong>$ cp server.key server.key.org</strong></code><br />
546 <code><strong>$ openssl rsa -in server.key.org -out server.key</strong></code><br />
550 <li>Make sure the server.key file is now only readable by root:<br />
552 <code><strong>$ chmod 400 server.key</strong></code><br />
557 <p>Now <code>server.key</code> will contain an unencrypted copy of the key.
558 If you point your server at this file it will not prompt you for a
559 pass-phrase. HOWEVER, if anyone gets this key they will be able to
560 impersonate you on the net. PLEASE make sure that the permissions on that
561 file are really such that only root or the web server user can read it
562 (preferably get your web server to start as root but run as another
563 server, and have the key readable only by root).</p>
565 <p>As an alternative approach you can use the ``<code>SSLPassPhraseDialog
566 exec:/path/to/program</code>'' facility. But keep in mind that this is
567 neither more nor less secure, of course.</p>
570 <h3><a name="verify" id="verify">How do I verify that a private key matches its Certificate?</a></h3>
571 <p>The private key contains a series of numbers. Two of those numbers form
572 the "public key", the others are part of your "private key". The "public
573 key" bits are also embedded in your Certificate (we get them from your
574 CSR). To check that the public key in your cert matches the public
575 portion of your private key, you need to view the cert and the key and
576 compare the numbers. To view the Certificate and the key run the
579 <p><code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
580 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code></p>
582 <p>The `modulus' and the `public exponent' portions in the key and the
583 Certificate must match. But since the public exponent is usually 65537
584 and it's bothering comparing long modulus you can use the following
588 <p><code><strong>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br />
589 <code><strong>$ openssl rsa -noout -modulus -in server.key | openssl md5</strong></code></p>
591 <p>And then compare these really shorter numbers. With overwhelming
592 probability they will differ if the keys are different. BTW, if I want to
593 check to which key or certificate a particular CSR belongs you can compute</p>
595 <p><code><strong>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code></p>
598 <h3><a name="badcert" id="badcert">What does it mean when my connections fail with an "alert bad certificate"
600 <p>Usually when you see errors like <code>OpenSSL: error:14094412: SSL
601 routines:SSL3_READ_BYTES:sslv3 alert bad certificate</code> in the SSL
602 logfile, this means that the browser was unable to handle the server
603 certificate/private-key which perhaps contain a RSA-key not equal to 1024
604 bits. For instance Netscape Navigator 3.x is one of those browsers.</p>
607 <h3><a name="keysize" id="keysize">Why does my 2048-bit private key not work?</a></h3>
608 <p>The private key sizes for SSL must be either 512 or 1024 for compatibility
609 with certain web browsers. A keysize of 1024 bits is recommended because
610 keys larger than 1024 bits are incompatible with some versions of Netscape
611 Navigator and Microsoft Internet Explorer, and with other browsers that
612 use RSA's BSAFE cryptography toolkit.</p>
615 <h3><a name="hashsymlinks" id="hashsymlinks">Why is client authentication broken after upgrading from
616 SSLeay version 0.8 to 0.9?</a></h3>
617 <p>The CA certificates under the path you configured with
618 <code>SSLCACertificatePath</code> are found by SSLeay through hash
619 symlinks. These hash values are generated by the `<code>openssl x509 -noout
620 -hash</code>' command. But the algorithm used to calculate the hash for a
621 certificate has changed between SSLeay 0.8 and 0.9. So you have to remove
622 all old hash symlinks and re-create new ones after upgrading. Use the
623 <code>Makefile</code> mod_ssl placed into this directory.</p>
626 <h3><a name="pemder" id="pemder">How can I convert a certificate from PEM to DER format?</a></h3>
627 <p>The default certificate format for SSLeay/OpenSSL is PEM, which actually
628 is Base64 encoded DER with header and footer lines. For some applications
629 (e.g. Microsoft Internet Explorer) you need the certificate in plain DER
630 format. You can convert a PEM file <code>cert.pem</code> into the
631 corresponding DER file <code>cert.der</code> with the following command:
632 <code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code></p>
635 <h3><a name="verisign" id="verisign">I try to install a Verisign certificate. Why can't I find neither the
636 <code>getca</code> nor <code>getverisign</code> programs Verisign mentions?</a></h3>
637 <p>This is because Verisign has never provided specific instructions
638 for Apache+mod_ssl. Rather they tell you what you should do
639 if you were using C2Net's Stronghold (a commercial Apache
640 based server with SSL support). The only thing you have to do
641 is to save the certificate into a file and give the name of
642 that file to the <code>SSLCertificateFile</code> directive.
643 Remember that you need to give the key file in as well (see
644 <code>SSLCertificateKeyFile</code> directive). For a better
645 CA-related overview on SSL certificate fiddling you can look at <a href="http://www.thawte.com/certs/server/keygen/mod_ssl.html">Thawte's mod_ssl instructions</a>.</p>
648 <h3><a name="sgc" id="sgc">Can I use the Server Gated Cryptography (SGC) facility (aka Verisign Global
649 ID) also with mod_ssl?</a></h3>
650 <p>Yes, mod_ssl since version 2.1 supports the SGC facility. You don't have
651 to configure anything special for this, just use a Global ID as your
652 server certificate. The <em>step up</em> of the clients are then
653 automatically handled by mod_ssl under run-time. For details please read
654 the <code>README.GlobalID</code> document in the mod_ssl distribution.</p>
657 <h3><a name="gid" id="gid">After I have installed my new Verisign Global ID server certificate, the
658 browsers complain that they cannot verify the server certificate?</a></h3>
659 <p>That is because Verisign uses an intermediate CA certificate between
660 the root CA certificate (which is installed in the browsers) and
661 the server certificate (which you installed in the server). You
662 should have received this additional CA certificate from Verisign.
663 If not, complain to them. Then configure this certificate with the
664 <code>SSLCertificateChainFile</code> directive in the server. This
665 makes sure the intermediate CA certificate is send to the browser
666 and this way fills the gap in the certificate chain.</p>
668 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
669 <div class="section">
670 <h2><a name="aboutssl" id="aboutssl">About SSL Protocol</a></h2>
672 <li><a href="#random">Random SSL errors under heavy load?</a></li>
673 <li><a href="#load">Why has the server a higher load?</a></li>
674 <li><a href="#establishing">Why are connections horribly slow?</a></li>
675 <li><a href="#ciphers">Which ciphers are supported?</a></li>
676 <li><a href="#adh">How to use Anonymous-DH ciphers</a></li>
677 <li><a href="#sharedciphers">Why do I get 'no shared ciphers'?</a></li>
678 <li><a href="#vhosts">HTTPS and name-based vhosts</a></li>
679 <li><a href="#vhosts2">Why is it not possible to use Name-Based Virtual Hosting to identify different SSL virtual hosts?</a></li>
680 <li><a href="#lockicon">The lock icon in Netscape locks very late</a></li>
681 <li><a href="#msie">Why do I get I/O errors with MSIE clients?</a></li>
682 <li><a href="#nn">Why do I get I/O errors with NS clients?</a></li>
685 <h3><a name="random" id="random">Why do I get lots of random SSL protocol errors under heavy server load?</a></h3>
686 <p>There can be a number of reasons for this, but the main one
687 is problems with the SSL session Cache specified by the
688 <code class="directive"><a href="../mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code> directive. The DBM session
689 cache is most likely the source of the problem, so trying the SHM session cache or
690 no cache at all may help.</p>
693 <h3><a name="load" id="load">Why has my webserver a higher load now that I run SSL there?</a></h3>
694 <p>Because SSL uses strong cryptographic encryption and this needs a lot of
695 number crunching. And because when you request a webpage via HTTPS even
696 the images are transfered encrypted. So, when you have a lot of HTTPS
697 traffic the load increases.</p>
700 <h3><a name="establishing" id="establishing">Often HTTPS connections to my server require up to 30 seconds for establishing
701 the connection, although sometimes it works faster?</a></h3>
702 <p>Usually this is caused by using a <code>/dev/random</code> device for
703 <code>SSLRandomSeed</code> which is blocking in read(2) calls if not
704 enough entropy is available. Read more about this problem in the refernce
705 chapter under <code>SSLRandomSeed</code>.</p>
708 <h3><a name="ciphers" id="ciphers">What SSL Ciphers are supported by mod_ssl?</a></h3>
709 <p>Usually just all SSL ciphers which are supported by the
710 version of OpenSSL in use (can depend on the way you built
711 OpenSSL). Typically this at least includes the following:</p>
714 <li>RC4 with MD5</li>
716 <li>RC4 with MD5 (export version restricted to 40-bit key)</li>
717 <li>RC2 with MD5</li>
718 <li>RC2 with MD5 (export version restricted to 40-bit key)</li>
719 <li>IDEA with MD5</li>
720 <li>DES with MD5</li>
721 <li>Triple-DES with MD5</li>
725 <p>To determine the actual list of supported ciphers you can
726 run the following command:</p>
727 <div class="example"><p><code>$ openssl ciphers -v</code></p></div>
730 <h3><a name="adh" id="adh">I want to use Anonymous Diffie-Hellman (ADH) ciphers, but I always get ``no
731 shared cipher'' errors?</a></h3>
732 <p>In order to use Anonymous Diffie-Hellman (ADH) ciphers, it is not enough
733 to just put ``<code>ADH</code>'' into your <code>SSLCipherSuite</code>.
734 Additionally you have to build OpenSSL with
735 ``<code>-DSSL_ALLOW_ADH</code>''. Because per default OpenSSL does not
736 allow ADH ciphers for security reasons. So if you are actually enabling
737 these ciphers make sure you are informed about the side-effects.</p>
740 <h3><a name="sharedciphers" id="sharedciphers">I always just get a 'no shared ciphers' error if
741 I try to connect to my freshly installed server?</a></h3>
742 <p>Either you have messed up your <code>SSLCipherSuite</code>
743 directive (compare it with the pre-configured example in
744 <code>httpd.conf-dist</code>) or you have choosen the DSA/DH
745 algorithms instead of RSA when you generated your private key
746 and ignored or overlooked the warnings. If you have choosen
747 DSA/DH, then your server no longer speaks RSA-based SSL ciphers
748 (at least not until you also configure an additional RSA-based
749 certificate/key pair). But current browsers like NS or IE only speak
750 RSA ciphers. The result is the "no shared ciphers" error. To fix
751 this, regenerate your server certificate/key pair and this time
752 choose the RSA algorithm.</p>
755 <h3><a name="vhosts" id="vhosts">Why can't I use SSL with name-based/non-IP-based virtual hosts?</a></h3>
756 <p>The reason is very technical. Actually it's some sort of a chicken and
757 egg problem: The SSL protocol layer stays below the HTTP protocol layer
758 and encapsulates HTTP. When an SSL connection (HTTPS) is established
759 Apache/mod_ssl has to negotiate the SSL protocol parameters with the
760 client. For this mod_ssl has to consult the configuration of the virtual
761 server (for instance it has to look for the cipher suite, the server
762 certificate, etc.). But in order to dispatch to the correct virtual server
763 Apache has to know the <code>Host</code> HTTP header field. For this the
764 HTTP request header has to be read. This cannot be done before the SSL
765 handshake is finished. But the information is already needed at the SSL
766 handshake phase. Bingo!</p>
769 <h3><a name="vhosts2" id="vhosts2">Why is it not possible to use Name-Based Virtual Hosting to identify
770 different SSL virtual hosts?</a></h3>
771 <p>Name-Based Virtual Hosting is a very popular method of identifying
772 different virtual = hosts. It allows you to use the same IP address and
773 the same port number for many different sites. When people move on to
774 SSL, it seems natural to assume that the same method can be used to have
775 lots of different SSL virtual hosts on the same server.</p>
777 <p>It comes as rather a shock to learn that it is impossible.</p>
779 <p>The reason is that the SSL protocol is a separate layer which
780 encapsulates the HTTP protocol. So the problem is that the SSL session
781 is a separate transaction that takes place before the HTTP session even
782 starts. Therefore all the server receives is an SSL request on IP
783 address X and port Y (usually 443). Since the SSL request does not
784 contain any Host: field, the server has no way to decide which SSL
785 virtual host to use. Usually, it will just use the first one it finds
786 that matches the port and IP address.</p>
788 <p>You can, of course, use Name-Based Virtual Hosting to identify many
789 non-SSL virtual hosts (all on port 80, for example) and then you can
790 have no more than 1 SSL virtual host (on port 443). But if you do this,
791 you must make sure to put the non-SSL port number on the NameVirtualHost
794 <div class="example"><p>NameVirtualHost 192.168.1.1:80</p><p>Other workaround solutions are: </p><p>Use separate IP addresses for different SSL hosts.
795 Use different port numbers for different SSL hosts.</p></div>
798 <h3><a name="lockicon" id="lockicon">When I use Basic Authentication over HTTPS the lock icon in Netscape browsers
799 still shows the unlocked state when the dialog pops up. Does this mean the
800 username/password is still transmitted unencrypted?</a></h3>
801 <p>No, the username/password is already transmitted encrypted. The icon in
802 Netscape browsers is just not really synchronized with the SSL/TLS layer
803 (it toggles to the locked state when the first part of the actual webpage
804 data is transferred which is not quite correct) and this way confuses
805 people. The Basic Authentication facility is part of the HTTP layer and
806 this layer is above the SSL/TLS layer in HTTPS. And before any HTTP data
807 communication takes place in HTTPS the SSL/TLS layer has already done the
808 handshake phase and switched to encrypted communication. So, don't get
809 confused by this icon.</p>
812 <h3><a name="msie" id="msie">When I connect via HTTPS to an Apache+mod_ssl+OpenSSL server with Microsoft Internet
813 Explorer (MSIE) I get various I/O errors. What is the reason?</a></h3>
814 <p>The first reason is that the SSL implementation in some MSIE versions has
815 some subtle bugs related to the HTTP keep-alive facility and the SSL close
816 notify alerts on socket connection close. Additionally the interaction
817 between SSL and HTTP/1.1 features are problematic with some MSIE versions,
818 too. You've to work-around these problems by forcing
819 Apache+mod_ssl+OpenSSL to not use HTTP/1.1, keep-alive connections or
820 sending the SSL close notify messages to MSIE clients. This can be done by
821 using the following directive in your SSL-aware virtual host section:</p>
822 <div class="example"><p><code>
823 SetEnvIf User-Agent ".*MSIE.*" \<br />
824 nokeepalive ssl-unclean-shutdown \<br />
825 downgrade-1.0 force-response-1.0
827 <p>Additionally it is known some MSIE versions have also problems
828 with particular ciphers. Unfortunately one cannot workaround these
829 bugs only for those MSIE particular clients, because the ciphers
830 are already used in the SSL handshake phase. So a MSIE-specific
831 <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> doesn't work
832 to solve these problems. Instead one has to do more drastic
833 adjustments to the global parameters. But before you decide to do
834 this, make sure your clients really have problems. If not, do not
835 do this, because it affects all(!) your clients, i.e., also your
836 non-MSIE clients.</p>
838 <p>The next problem is that 56bit export versions of MSIE 5.x browsers have a
839 broken SSLv3 implementation which badly interacts with OpenSSL versions
840 greater than 0.9.4. You can either accept this and force your clients to
841 upgrade their browsers, or you downgrade to OpenSSL 0.9.4 (hmmm), or you
842 can decide to workaround it by accepting the drawback that your workaround
843 will horribly affect also other browsers:</p>
844 <div class="example"><p><code>SSLProtocol all -SSLv3</code></p></div>
845 <p>This completely disables the SSLv3 protocol and lets those browsers work.
846 But usually this is an even less acceptable workaround. A more reasonable
847 workaround is to address the problem more closely and disable only the
848 ciphers which cause trouble.</p>
849 <div class="example"><p><code>SSLCipherSuite
850 ALL:!ADH:<strong>!EXPORT56</strong>:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>
853 <p>This also lets the broken MSIE versions work, but only removes the
854 newer 56bit TLS ciphers.</p>
856 <p>Another problem with MSIE 5.x clients is that they refuse to connect to
857 URLs of the form <code>https://12.34.56.78/</code> (IP-addresses are used
858 instead of the hostname), if the server is using the Server Gated
859 Cryptography (SGC) facility. This can only be avoided by using the fully
860 qualified domain name (FQDN) of the website in hyperlinks instead, because
861 MSIE 5.x has an error in the way it handles the SGC negotiation.</p>
863 <p>And finally there are versions of MSIE which seem to require that
864 an SSL session can be reused (a totally non standard-conforming
865 behaviour, of course). Connection with those MSIE versions only work
866 if a SSL session cache is used. So, as a work-around, make sure you
867 are using a session cache (see <code class="directive"><a href="../mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code> directive).</p>
870 <h3><a name="nn" id="nn">When I connect via HTTPS to an Apache+mod_ssl server with Netscape Navigator I
871 get I/O errors and the message "Netscape has encountered bad data from the
872 server" What's the reason?</a></h3>
874 The problem usually is that you had created a new server certificate with
875 the same DN, but you had told your browser to accept forever the old
876 server certificate. Once you clear the entry in your browser for the old
877 certificate, everything usually will work fine. Netscape's SSL
878 implementation is correct, so when you encounter I/O errors with Netscape
879 Navigator it is most of the time caused by the configured certificates.</p>
881 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
882 <div class="section">
883 <h2><a name="support" id="support">About Support</a></h2>
885 <li><a href="#resources">Resources in case of problems?</a></li>
886 <li><a href="#contact">Support in case of problems?</a></li>
887 <li><a href="#reportdetails">How to write a problem report?</a></li>
888 <li><a href="#coredumphelp">I got a core dump, can you help me?</a></li>
889 <li><a href="#backtrace">How to get a backtrace?</a></li>
892 <h3><a name="resources" id="resources">What information resources are available in case of mod_ssl problems?</a></h3>
893 <p>The following information resources are available.
894 In case of problems you should search here first.</p>
897 <dt>Answers in the User Manual's F.A.Q. List (this)</dt>
898 <dd><a href="http://httpd.apache.org/docs-2.1/ssl/ssl_faq.html">
899 http://httpd.apache.org/docs-2.1/ssl/ssl_faq.html</a><br />
900 First look inside the F.A.Q. (this text), perhaps your problem is such
901 popular that it was already answered a lot of times in the past.
903 <dt>Postings from the modssl-users Support Mailing List
904 <a href="http://www.modssl.org/support/">
905 http://www.modssl.org/support/</a></dt>
906 <dd>Second search for your problem in one of the existing archives of the
907 modssl-users mailing list. Perhaps your problem popped up at least once for
910 <dt>Problem Reports in the Bug Database
911 <a href="http://www.modssl.org/support/bugdb/">
912 http://www.modssl.org/support/bugdb/</a></dt>
913 <dd>Third look inside the mod_ssl Bug Database. Perhaps
914 someone else already has reported the problem.
920 <h3><a name="contact" id="contact">What support contacts are available in case of mod_ssl problems?</a></h3>
921 <p>The following lists all support possibilities for mod_ssl, in order of
922 preference, i.e. start in this order and do not pick the support possibility
923 you just like most, please.</p>
926 <li><em>Write a Problem Report into the Bug Database</em><br />
927 <a href="http://www.modssl.org/support/bugdb/">
928 http://www.modssl.org/support/bugdb/</a><br />
929 This is the preferred way of submitting your problem report, because this
930 way it gets filed into the bug database (it cannot be lost) <em>and</em>
931 send to the modssl-users mailing list (others see the current problems and
935 <li><em>Write 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 second way of submitting your problem report. You have to
939 subscribe to the list first, but then you can easily discuss your problem
940 with both the author and the whole mod_ssl user community.
945 <h3><a name="reportdetails" id="reportdetails">What information and details should I
946 provide when writing a bug report?</a></h3>
947 <p>You have to at least always provide the following information:</p>
950 <dt>Apache and OpenSSL version information</dt>
951 <dd>The Apache version can be determined
952 by running ``<code>httpd -v</code>''. The OpenSSL version can be
953 determined by running ``<code>openssl version</code>''. Alternatively when
954 you have Lynx installed you can run the command ``<code>lynx -mime_header
955 http://localhost/ | grep Server</code>'' to determine all information in a
959 <dt>The details on how you built and installed Apache+mod_ssl+OpenSSL</dt>
960 <dd>For this you can provide a logfile of your terminal session which shows
961 the configuration and install steps. Alternatively you can at least
962 provide the <code>configure</code> command line you used.
965 <dt>In case of core dumps please include a Backtrace</dt>
966 <dd>In case your Apache+mod_ssl+OpenSSL should really dump core please attach
967 a stack-frame ``backtrace'' (see the next question on how to get it).
968 Without this information the reason for your core dump cannot be found.
969 So you have to provide the backtrace, please.
972 <dt>A detailed description of your problem</dt>
973 <dd>Don't laugh, I'm totally serious. I already got a lot of problem reports
974 where the people not really said what's the actual problem is. So, in your
975 own interest (you want the problem be solved, don't you?) include as much
976 details as possible, please. But start with the essentials first, of
982 <h3><a name="coredumphelp" id="coredumphelp">I got a core dump, can you help me?</a></h3>
983 <p>In general no, at least not unless you provide more details about the code
984 location where Apache dumped core. What is usually always required in
985 order to help you is a backtrace (see next question). Without this
986 information it is mostly impossible to find the problem and help you in
990 <h3><a name="backtrace" id="backtrace">Ok, I got a core dump but how do I get a backtrace to find out the reason for it?</a></h3>
991 <p>Follow the following steps:</p>
993 <li>Make sure you have debugging symbols available in at least
994 Apache. On platforms where you use GCC/GDB you have to build
995 Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to achieve this. On
996 other platforms at least ``<code>OPTIM="-g"</code>'' is needed.
999 <li>Startup the server and try to produce the core-dump. For this you perhaps
1000 want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to
1001 make sure that the core-dump file can be written. You then should get a
1002 <code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. When you
1003 don't get this, try to run your server under an UID != 0 (root), because
1004 most "current" kernels do not allow a process to dump core after it has
1005 done a <code>setuid()</code> (unless it does an <code>exec()</code>) for
1006 security reasons (there can be privileged information left over in
1007 memory). Additionally you can run ``<code>/path/to/httpd -X</code>''
1008 manually to force Apache to not fork.
1011 <li>Analyze the core-dump. For this run <code>gdb /path/to/httpd
1012 /tmp/httpd.core</code> or a similar command has to run. In GDB you then
1013 just have to enter the <code>bt</code> command and, voila, you get the
1014 backtrace. For other debuggers consult your local debugger manual. Send
1015 this backtrace to the author.
1021 <p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
1022 <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>
projects / apache / blob