1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 4<html xmlns="http://www.w3.org/1999/xhtml"> 5 <head> 6 <meta name="generator" content="HTML Tidy, see www.w3.org" /> 7 8 <title>Apache 1.3 Dynamic Shared Object (DSO) support</title> 9 </head> 10 <!-- Background white, links blue (unvisited), navy (visited), red (active) --> 11 12 <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" 13 vlink="#000080" alink="#FF0000"> 14 <blockquote> 15 <div align="CENTER"> 16 <img src="images/sub.gif" alt="[APACHE DOCUMENTATION]" /> 17 18 <h3>Apache HTTP Server</h3> 19 </div> 20 21 22 23 <div align="CENTER"> 24 <h1>Apache 1.3<br /> 25 Dynamic Shared Object (DSO)<br /> 26 Support</h1> 27 28 <address> 29 Originally written by<br /> 30 Ralf S. Engelschall <rse@apache.org>, April 1998 31 </address> 32 </div> 33 34 <h3>Background</h3> 35 36 <p>On modern Unix derivatives there exists a nifty mechanism 37 usually called dynamic linking/loading of <em>Dynamic Shared 38 Objects</em> (DSO) which provides a way to build a piece of 39 program code in a special format for loading it at run-time 40 into the address space of an executable program.</p> 41 42 <p>This loading can usually be done in two ways: 43 Automatically by a system program called <code>ld.so</code> 44 when an executable program is started or manually from within 45 the executing program via a programmatic system interface to 46 the Unix loader through the system calls 47 <code>dlopen()/dlsym()</code>.</p> 48 49 <p>In the first way the DSO's are usually called <em>shared 50 libraries</em> or <em>DSO libraries</em> and named 51 <code>libfoo.so</code> or <code>libfoo.so.1.2</code>. They 52 reside in a system directory (usually <code>/usr/lib</code>) 53 and the link to the executable program is established at 54 build-time by specifying <code>-lfoo</code> to the linker 55 command. This hard-codes library references into the 56 executable program file so that at start-time the Unix loader 57 is able to locate <code>libfoo.so</code> in 58 <code>/usr/lib</code>, in paths hard-coded via linker-options 59 like <code>-R</code> or in paths configured via the 60 environment variable <code>LD_LIBRARY_PATH</code>. It then 61 resolves any (yet unresolved) symbols in the executable 62 program which are available in the DSO.</p> 63 64 <p>Symbols in the executable program are usually not 65 referenced by the DSO (because it's a reusable library of 66 general code) and hence no further resolving has to be done. 67 The executable program has no need to do anything on its own 68 to use the symbols from the DSO because the complete 69 resolving is done by the Unix loader. (In fact, the code to 70 invoke <code>ld.so</code> is part of the run-time startup 71 code which is linked into every executable program which has 72 been bound non-static). The advantage of dynamic loading of 73 common library code is obvious: the library code needs to be 74 stored only once, in a system library like 75 <code>libc.so</code>, saving disk space for every 76 program.</p> 77 78 <p>In the second way the DSO's are usually called <em>shared 79 objects</em> or <em>DSO files</em> and can be named with an 80 arbitrary extension (although the canonical name is 81 <code>foo.so</code>). These files usually stay inside a 82 program-specific directory and there is no automatically 83 established link to the executable program where they are 84 used. Instead the executable program manually loads the DSO 85 at run-time into its address space via <code>dlopen()</code>. 86 At this time no resolving of symbols from the DSO for the 87 executable program is done. But instead the Unix loader 88 automatically resolves any (yet unresolved) symbols in the 89 DSO from the set of symbols exported by the executable 90 program and its already loaded DSO libraries (especially all 91 symbols from the ubiquitous <code>libc.so</code>). This way 92 the DSO gets knowledge of the executable program's symbol set 93 as if it had been statically linked with it in the first 94 place.</p> 95 96 <p>Finally, to take advantage of the DSO's API the executable 97 program has to resolve particular symbols from the DSO via 98 <code>dlsym()</code> for later use inside dispatch tables 99 <em>etc.</em> In other words: The executable program has to 100 manually resolve every symbol it needs to be able to use it. 101 The advantage of such a mechanism is that optional program 102 parts need not be loaded (and thus do not spend memory) until 103 they are needed by the program in question. When required, 104 these program parts can be loaded dynamically to extend the 105 base program's functionality.</p> 106 107 <p>Although this DSO mechanism sounds straightforward there 108 is at least one difficult step here: The resolving of symbols 109 from the executable program for the DSO when using a DSO to 110 extend a program (the second way). Why? Because "reverse 111 resolving" DSO symbols from the executable program's symbol 112 set is against the library design (where the library has no 113 knowledge about the programs it is used by) and is neither 114 available under all platforms nor standardized. In practice 115 the executable program's global symbols are often not 116 re-exported and thus not available for use in a DSO. Finding 117 a way to force the linker to export all global symbols is the 118 main problem one has to solve when using DSO for extending a 119 program at run-time.</p> 120 121 <p>Windows and NetWare provide similar facilities, although 122 they are implemented somewhat differently than the 123 description of Unix DSO throughout this document. In 124 particular, DSO modules (DLL's and NLM's, respectively) are 125 built quite differently than their Unix cousins. This 126 document does not attempt to explore the topic of building 127 DSO modules on these platforms. The description of mod_so and 128 its configuration, however, are similar.</p> 129 130 <h3>Practical Usage</h3> 131 132 <p>The shared library approach is the typical one, because it 133 is what the DSO mechanism was designed for, hence it is used 134 for nearly all types of libraries the operating system 135 provides. On the other hand using shared objects for 136 extending a program is not used by a lot of programs.</p> 137 138 <p>As of 1998 there are only a few software packages 139 available which use the DSO mechanism to actually extend 140 their functionality at run-time: Perl 5 (via its XS mechanism 141 and the DynaLoader module), Netscape Server, <em>etc.</em> 142 Starting with version 1.3, Apache joined the crew, because 143 Apache already uses a module concept to extend its 144 functionality and internally uses a dispatch-list-based 145 approach to link external modules into the Apache core 146 functionality. So, Apache is really predestined for using DSO 147 to load its modules at run-time.</p> 148 149 <p>As of Apache 1.3, the configuration system supports two 150 optional features for taking advantage of the modular DSO 151 approach: compilation of the Apache core program into a DSO 152 library for shared usage and compilation of the Apache 153 modules into DSO files for explicit loading at run-time.</p> 154 155 <h3>Implementation</h3> 156 157 <p>The DSO support for loading individual Apache modules is 158 based on a module named <a 159 href="mod/mod_so.html"><code>mod_so.c</code></a> which has to 160 be statically compiled into the Apache core. It is the only 161 module besides <code>http_core.c</code> which cannot be put 162 into a DSO itself (bootstrapping!). Practically all other 163 distributed Apache modules can then be placed into a DSO 164 by individually enabling the DSO build for them via 165 <code>configure</code>'s <code>--enable-shared</code> option 166 (see top-level <code>INSTALL</code> file) or by changing the 167 <code>AddModule</code> command in your 168 <code>src/Configuration</code> into a 169 <code>SharedModule</code> command (see 170 <code>src/INSTALL</code> file). After a module is compiled 171 into a DSO named <code>mod_foo.so</code> you can use <a 172 href="mod/mod_so.html"><code>mod_so</code></a>'s <a 173 href="mod/mod_so.html#loadmodule"><code>LoadModule</code></a> 174 command in your <code>httpd.conf</code> file to load this 175 module at server startup or restart.</p> 176 177 <p>To simplify this creation of DSO files for Apache modules 178 (especially for third-party modules) a new support program 179 named <a href="programs/apxs.html">apxs</a> (<em>APache 180 eXtenSion</em>) is available. It can be used to build DSO 181 based modules <em>outside of</em> the Apache source tree. The 182 idea is simple: When installing Apache the 183 <code>configure</code>'s <code>make install</code> procedure 184 installs the Apache C header files and puts the 185 platform-dependent compiler and linker flags for building DSO 186 files into the <code>apxs</code> program. This way the user 187 can use <code>apxs</code> to compile his Apache module 188 sources without the Apache distribution source tree and 189 without having to fiddle with the platform-dependent compiler 190 and linker flags for DSO support.</p> 191 192 <p>To place the complete Apache core program into a DSO 193 library (only required on some of the supported platforms to 194 force the linker to export the apache core symbols -- a 195 prerequisite for the DSO modularization) the rule 196 <code>SHARED_CORE</code> has to be enabled via 197 <code>configure</code>'s 198 <code>--enable-rule=SHARED_CORE</code> option (see top-level 199 <code>INSTALL</code> file) or by changing the 200 <code>Rule</code> command in your <code>Configuration</code> 201 file to <code>Rule SHARED_CORE=yes</code> (see 202 <code>src/INSTALL</code> file). The Apache core code is then 203 placed into a DSO library named <code>libhttpd.so</code>. 204 Because one cannot link a DSO against static libraries on all 205 platforms, an additional executable program named 206 <code>libhttpd.ep</code> is created which both binds this 207 static code and provides a stub for the <code>main()</code> 208 function. Finally the <code>httpd</code> executable program 209 itself is replaced by a bootstrapping code which 210 automatically makes sure the Unix loader is able to load and 211 start <code>libhttpd.ep</code> by providing the 212 <code>LD_LIBRARY_PATH</code> to <code>libhttpd.so</code>.</p> 213 214 <h3>Supported Platforms</h3> 215 216 <p>Apache's <code>src/Configure</code> script currently has 217 only limited but adequate built-in knowledge on how to 218 compile DSO files, because as already mentioned this is 219 heavily platform-dependent. Nevertheless all major Unix 220 platforms are supported. The definitive current state (May 221 1999) is this:</p> 222 223 <ul> 224 <li> 225 Out-of-the-box supported platforms:<br /> 226 (actually tested versions in parenthesis) 227<pre> 228o FreeBSD (2.1.5, 2.2.x, 3.x, 4.x) 229o OpenBSD (2.x) 230o NetBSD (1.3.1) 231o BSDI (3.x, 4.x) 232o Linux (Debian/1.3.1, RedHat/4.2) 233o Solaris (2.4, 2.5, 2.6, 2.7) 234o SunOS (4.1.3) 235o Digital UNIX (4.0) 236o IRIX (5.3, 6.2) 237o HP/UX (10.20) 238o UnixWare (2.01, 2.1.2) 239o SCO (5.0.4) 240o AIX (3.2, 4.1.5, 4.2, 4.3) 241o ReliantUNIX/SINIX (5.43) 242o SVR4 (-) 243o Mac OS X Server (1.0) 244o Mac OS (10.0 preview 1) 245o OpenStep/Mach (4.2) 246o DGUX (??) 247o NetWare (5.1) 248o Windows (95, 98, NT 4.0, 2000) 249</pre> 250 </li> 251 252 <li> 253 Explicitly unsupported platforms: 254<pre> 255o Ultrix (no dlopen-style interface under this platform) 256</pre> 257 </li> 258 </ul> 259 260 <h3>Usage Summary</h3> 261 262 <p>To give you an overview of the DSO features of Apache 1.3, 263 here is a short and concise summary:</p> 264 265 <ol> 266 <li> 267 Placing the Apache core code (all the stuff which usually 268 forms the <code>httpd</code> binary) into a DSO 269 <code>libhttpd.so</code>, an executable program 270 <code>libhttpd.ep</code> and a bootstrapping executable 271 program <code>httpd</code> (Notice: this is only required 272 on some of the supported platforms to force the linker to 273 export the Apache core symbols, which in turn is a 274 prerequisite for the DSO modularization): 275 276 <ul> 277 <li> 278 Build and install via <code>configure</code> 279 (preferred): 280 281 <table bgcolor="#f0f0f0" cellpadding="10"> 282 <tr> 283 <td> 284<pre> 285$ ./configure --prefix=/path/to/install 286 --enable-rule=SHARED_CORE ... 287$ make install 288</pre> 289 </td> 290 </tr> 291 </table> 292 </li> 293 294 <li> 295 Build and install manually: 296 297 <table bgcolor="#f0f0f0" cellpadding="10"> 298 <tr> 299 <td> 300<pre> 301- Edit src/Configuration: 302 << Rule SHARED_CORE=default 303 >> Rule SHARED_CORE=yes 304 << EXTRA_CFLAGS= 305 >> EXTRA_CFLAGS= -DSHARED_CORE_DIR=\"/path/to/install/libexec\" 306$ make 307$ cp src/libhttpd.so* /path/to/install/libexec/ 308$ cp src/libhttpd.ep /path/to/install/libexec/ 309$ cp src/httpd /path/to/install/bin/ 310</pre> 311 </td> 312 </tr> 313 </table> 314 </li> 315 </ul> 316 </li> 317 318 <li> 319 Build and install a <em>distributed</em> Apache module, 320 say <code>mod_foo.c</code>, into its own DSO 321 <code>mod_foo.so</code>: 322 323 <ul> 324 <li> 325 Build and install via <code>configure</code> 326 (preferred): 327 328 <table bgcolor="#f0f0f0" cellpadding="10"> 329 <tr> 330 <td> 331<pre> 332$ ./configure --prefix=/path/to/install 333 --enable-shared=foo 334$ make install 335</pre> 336 </td> 337 </tr> 338 </table> 339 </li> 340 341 <li> 342 Build and install manually: 343 344 <table bgcolor="#f0f0f0" cellpadding="10"> 345 <tr> 346 <td> 347<pre> 348- Edit src/Configuration: 349 << AddModule modules/xxxx/mod_foo.o 350 >> SharedModule modules/xxxx/mod_foo.so 351$ make 352$ cp src/xxxx/mod_foo.so /path/to/install/libexec 353- Edit /path/to/install/etc/httpd.conf 354 >> LoadModule foo_module /path/to/install/libexec/mod_foo.so 355</pre> 356 </td> 357 </tr> 358 </table> 359 </li> 360 </ul> 361 </li> 362 363 <li> 364 Build and install a <em>third-party</em> Apache module, 365 say <code>mod_foo.c</code>, into its own DSO 366 <code>mod_foo.so</code> 367 368 <ul> 369 <li> 370 Build and install via <code>configure</code> 371 (preferred): 372 373 <table bgcolor="#f0f0f0" cellpadding="10"> 374 <tr> 375 <td> 376<pre> 377$ ./configure --add-module=/path/to/3rdparty/mod_foo.c 378 --enable-shared=foo 379$ make install 380</pre> 381 </td> 382 </tr> 383 </table> 384 </li> 385 386 <li> 387 Build and install manually: 388 389 <table bgcolor="#f0f0f0" cellpadding="10"> 390 <tr> 391 <td> 392<pre> 393$ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/ 394- Edit src/Configuration: 395 >> SharedModule modules/extra/mod_foo.so 396$ make 397$ cp src/xxxx/mod_foo.so /path/to/install/libexec 398- Edit /path/to/install/etc/httpd.conf 399 >> LoadModule foo_module /path/to/install/libexec/mod_foo.so 400</pre> 401 </td> 402 </tr> 403 </table> 404 </li> 405 </ul> 406 </li> 407 408 <li> 409 Build and install a <em>third-party</em> Apache module, 410 say <code>mod_foo.c</code>, into its own DSO 411 <code>mod_foo.so</code> <em>outside of</em> the Apache 412 source tree: 413 414 <ul> 415 <li> 416 Build and install via <a 417 href="programs/apxs.html">apxs</a>: 418 419 <table bgcolor="#f0f0f0" cellpadding="10"> 420 <tr> 421 <td> 422<pre> 423$ cd /path/to/3rdparty 424$ apxs -c mod_foo.c 425$ apxs -i -a -n foo mod_foo.so 426</pre> 427 </td> 428 </tr> 429 </table> 430 </li> 431 </ul> 432 </li> 433 </ol> 434 435 <h3>Advantages & Disadvantages</h3> 436 437 <p>The above DSO based features of Apache 1.3 have the 438 following advantages:</p> 439 440 <ul> 441 <li>The server package is more flexible at run-time because 442 the actual server process can be assembled at run-time via 443 <a 444 href="mod/mod_so.html#loadmodule"><code>LoadModule</code></a> 445 <code>httpd.conf</code> configuration commands instead of 446 <code>Configuration</code> <code>AddModule</code> commands 447 at build-time. For instance this way one is able to run 448 different server instances (standard & SSL version, 449 minimalistic & powered up version [mod_perl, PHP3], 450 <em>etc.</em>) with only one Apache installation.</li> 451 452 <li>The server package can be easily extended with 453 third-party modules even after installation. This is at 454 least a great benefit for vendor package maintainers who 455 can create a Apache core package and additional packages 456 containing extensions like PHP3, mod_perl, mod_fastcgi, 457 <em>etc.</em></li> 458 459 <li>Easier Apache module prototyping because with the 460 DSO/<code>apxs</code> pair you can both work outside the 461 Apache source tree and only need an <code>apxs -i</code> 462 command followed by an <code>apachectl restart</code> to 463 bring a new version of your currently developed module into 464 the running Apache server.</li> 465 </ul> 466 467 <p>DSO has the following disadvantages:</p> 468 469 <ul> 470 <li>The DSO mechanism cannot be used on every platform 471 because not all operating systems support dynamic loading 472 of code into the address space of a program.</li> 473 474 <li>The server is approximately 20% slower at startup time 475 because of the symbol resolving overhead the Unix loader 476 now has to do.</li> 477 478 <li>The server is approximately 5% slower at execution time 479 under some platforms because position independent code 480 (PIC) sometimes needs complicated assembler tricks for 481 relative addressing which are not necessarily as fast as 482 absolute addressing.</li> 483 484 <li>Because DSO modules cannot be linked against other 485 DSO-based libraries (<code>ld -lfoo</code>) on all 486 platforms (for instance a.out-based platforms usually don't 487 provide this functionality while ELF-based platforms do) 488 you cannot use the DSO mechanism for all types of modules. 489 Or in other words, modules compiled as DSO files are 490 restricted to only use symbols from the Apache core, from 491 the C library (<code>libc</code>) and all other dynamic or 492 static libraries used by the Apache core, or from static 493 library archives (<code>libfoo.a</code>) containing 494 position independent code. The only chances to use other 495 code is to either make sure the Apache core itself already 496 contains a reference to it, loading the code yourself via 497 <code>dlopen()</code> or enabling the 498 <code>SHARED_CHAIN</code> rule while building Apache when 499 your platform supports linking DSO files against DSO 500 libraries.</li> 501 502 <li>Under some platforms (many SVR4 systems) there is no 503 way to force the linker to export all global symbols for 504 use in DSO's when linking the Apache httpd executable 505 program. But without the visibility of the Apache core 506 symbols no standard Apache module could be used as a DSO. 507 The only chance here is to use the <code>SHARED_CORE</code> 508 feature because this way the global symbols are forced to 509 be exported. As a consequence the Apache 510 <code>src/Configure</code> script automatically enforces 511 <code>SHARED_CORE</code> on these platforms when DSO 512 features are used in the <code>Configuration</code> file or 513 on the configure command line.</li> 514 </ul> 515 <hr /> 516 517 <h3 align="CENTER">Apache HTTP Server</h3> 518 <a href="./"><img src="images/index.gif" alt="Index" /></a> 519 520 </blockquote> 521 </body> 522</html> 523 524
