README
1
2 Apache HTTP Server
3
4 What is it?
5 -----------
6
7 The Apache HTTP Server is a powerful and flexible HTTP/1.1 compliant
8 web server. Originally designed as a replacement for the NCSA HTTP
9 Server, it has grown to be the most popular web server on the
10 Internet. As a project of the Apache Software Foundation, the
11 developers aim to collaboratively develop and maintain a robust,
12 commercial-grade, standards-based server with freely available
13 source code.
14
15 The Latest Version
16 ------------------
17
18 Details of the latest version can be found on the Apache HTTP
19 server project page under http://httpd.apache.org/.
20
21 Documentation
22 -------------
23
24 The documentation available as of the date of this release is
25 included in HTML format in the docs/manual/ directory. The most
26 up-to-date documentation can be found at
27 http://httpd.apache.org/docs/2.4/.
28
29 Installation
30 ------------
31
32 Please see the file called INSTALL. Platform specific notes can be
33 found in README.platforms.
34
35 Licensing
36 ---------
37
38 Please see the file called LICENSE.
39
40 Cryptographic Software Notice
41 -----------------------------
42
43 This distribution may include software that has been designed for use
44 with cryptographic software. The country in which you currently reside
45 may have restrictions on the import, possession, use, and/or re-export
46 to another country, of encryption software. BEFORE using any encryption
47 software, please check your country's laws, regulations and policies
48 concerning the import, possession, or use, and re-export of encryption
49 software, to see if this is permitted. See <http://www.wassenaar.org/>
50 for more information.
51
52 The U.S. Government Department of Commerce, Bureau of Industry and
53 Security (BIS), has classified this software as Export Commodity
54 Control Number (ECCN) 5D002.C.1, which includes information security
55 software using or performing cryptographic functions with asymmetric
56 algorithms. The form and manner of this Apache Software Foundation
57 distribution makes it eligible for export under the License Exception
58 ENC Technology Software Unrestricted (TSU) exception (see the BIS
59 Export Administration Regulations, Section 740.13) for both object
60 code and source code.
61
62 The following provides more details on the included files that
63 may be subject to export controls on cryptographic software:
64
65 Apache httpd 2.0 and later versions include the mod_ssl module under
66 modules/ssl/
67 for configuring and listening to connections over SSL encrypted
68 network sockets by performing calls to a general-purpose encryption
69 library, such as OpenSSL or the operating system's platform-specific
70 SSL facilities.
71
72 In addition, some versions of apr-util provide an abstract interface
73 for symmetrical cryptographic functions that make use of a
74 general-purpose encryption library, such as OpenSSL, NSS, or the
75 operating system's platform-specific facilities. This interface is
76 known as the apr_crypto interface, with implementation beneath the
77 /crypto directory. The apr_crypto interface is used by the
78 mod_session_crypto module available under
79 modules/session
80 for optional encryption of session information.
81
82 Some object code distributions of Apache httpd, indicated with the
83 word "crypto" in the package name, may include object code for the
84 OpenSSL encryption library as distributed in open source form from
85 <http://www.openssl.org/source/>.
86
87 The above files are optional and may be removed if the cryptographic
88 functionality is not desired or needs to be excluded from redistribution.
89 Distribution packages of Apache httpd that include the word "nossl"
90 in the package name have been created without the above files and are
91 therefore not subject to this notice.
92
93 Contacts
94 --------
95
96 o If you want to be informed about new code releases, bug fixes,
97 security fixes, general news and information about the Apache server
98 subscribe to the apache-announce mailing list as described under
99 <http://httpd.apache.org/lists.html#http-announce>
100
101 o If you want freely available support for running Apache please see the
102 resources at <http://httpd.apache.org/support.html>
103
104 o If you have a concrete bug report for Apache please see the instructions
105 for bug reporting at <http://httpd.apache.org/bug_report.html>
106
107 o If you want to participate in actively developing Apache please
108 subscribe to the `dev@httpd.apache.org' mailing list as described at
109 <http://httpd.apache.org/lists.html#http-dev>
110
111
README.cmake
1Experimental cmake-based build support for Apache httpd on Microsoft Windows
2
3Status
4------
5
6This build support is currently intended only for Microsoft Windows.
7
8This build support is experimental. Specifically,
9
10* It does not support all features of Apache httpd.
11* Some components may not be built correctly and/or in a manner
12 compatible with the previous Windows build support.
13* Build interfaces, such as the mechanisms which are used to enable
14 optional functionality or specify prerequisites, may change from
15 release to release as feedback is received from users and bugs and
16 limitations are resolved.
17
18Important: Refer to the "Known Bugs and Limitations" section for further
19 information.
20
21 It is beyond the scope of this document to document or explain
22 how to utilize the various cmake features, such as different
23 build backends or provisions for finding support libraries.
24
25 Please refer to the cmake documentation for additional information
26 that applies to building any project with cmake.
27
28Prerequisites
29-------------
30
31The following tools must be in PATH:
32
33* cmake, version 2.8 or later
34* Perl
35* If the WITH_MODULES feature is used: awk
36* If using a command-line compiler: compiler and linker and related tools
37 (Refer to the cmake documentation for more information.)
38
39The following support libraries are mandatory:
40
41* APR, built with cmake
42 + Either APR 2.0-dev (trunk) or APR 1.5.x and APR-Util 1.5.x.
43 + When building APR (but not APR-Util), specify the build option
44 APR_INSTALL_PRIVATE_H so that non-standard files required for building
45 Apache httpd are installed.
46 + Additional APR settings affect httpd but are not mandatory, such as
47 APR_HAVE_IPV6.
48* PCRE
49
50Certain optional features of APR 2.0-dev (trunk) or APR-Util 1.5.x
51allow some optional features of httpd to be enabled. For example,
52APU_HAVE_CRYPTO is required for mod_session_crypto.
53
54Additional support libraries allow some optional features of httpd to be
55enabled:
56
57* libxml2 (e.g., mod_proxy_html)
58* lua 5.1 (mod_lua)
59* openssl (mod_ssl and https support for ab)
60* zlib (mod_deflate)
61
62How to build
63------------
64
651. cd to a clean directory for building (i.e., don't build in your
66 source tree)
67
682. Make sure cmake and Perl are in PATH. Additionally, some backends
69 require compile tools in PATH. (Hint: "Visual Studio Command Prompt")
70 In the unlikely event that you use -DWITH_MODULES, described below, make
71 sure awk is in PATH.
72
733. cmake -G "some backend, like 'NMake Makefiles'"
74 -DCMAKE_INSTALL_PREFIX=d:/path/to/httpdinst
75 -DENABLE_foo=A|I|O|a|i
76 -DENABLE_MODULES=A|I|O|a|i
77 d:/path/to/httpdsource
78
79 Alternately, you can use the cmake-gui and update settings in the GUI.
80
81 PCRE_INCLUDE_DIR, PCRE_LIBRARIES, APR_INCLUDE_DIR, APR_LIBRARIES:
82
83 cmake doesn't bundle FindXXX for these packages, so the crucial
84 information has to be specified in this manner if they aren't found
85 in their default location.
86
87 -DPCRE_INCLUDE_DIR=d:/path/to/pcreinst/include
88 -DPCRE_LIBRARIES=d:/path/to/pcreinst/lib/pcre[d].lib
89
90 These will have to be specified only if PCRE is installed to a different
91 directory than httpd, or if debug *and* release builds of PCRE were
92 installed there and you want to control which is used. (Currently the
93 build will use pcred.lib (debug) if it is found in the default location
94 and not overridden with -DPCRE_LIBRARIES.)
95
96 -DAPR_INCLUDE_DIR=d:/path/to/aprinst/include
97 -DAPR_LIBRARIES="d:/path/to/aprinst/lib/libapr-1.lib;d:/path/to/aprinst/lib/libaprutil-1.lib"
98
99 These will have to be specified if APR[-Util] was installed to a
100 different directory than httpd.
101
102 When building with APR trunk (future APR 2.x, with integrated APR-Util),
103 specify just the path to libapr-2.lib:
104
105 -DAPR_LIBRARIES=d:/path/to/aprinst/lib/libapr-2.lib
106
107 APR+APR-Util 1.x vs. APR trunk will be detected automatically if they
108 are installed to the same location as httpd.
109
110 APR-Util 1.x has an optional LDAP library. If APR-Util has LDAP enabled
111 and httpd's mod_ldap and mod_authnz_ldap are being used, include the
112 path to the LDAP library in the APR_LIBRARIES setting. (If APR and
113 APR-Util are found in the default location, the LDAP library will be
114 included if it is present.
115
116 LIBXML2_ICONV_INCLUDE_DIR, LIBXML2_ICONV_LIBRARIES
117
118 If using a module that requires libxml2 *and* the build of libxml2 requires
119 iconv, set these variables to allow iconv includes and libraries to be
120 used. For example:
121
122 -DLIBXML2_ICONV_INCLUDE_DIR=c:\iconv-1.9.2.win32\include
123 -DLIBXML2_ICONV_LIBRARIES=c:\iconv-1.9.2.win32\lib\iconv.lib
124
125 CMAKE_C_FLAGS_RELEASE, _DEBUG, _RELWITHDEBINFO, _MINSIZEREL
126 CMAKE_BUILD_TYPE
127
128 For NMake Makefiles the choices are at least DEBUG, RELEASE,
129 RELWITHDEBINFO, and MINSIZEREL
130 Other backends may have other selections.
131
132 ENABLE_foo:
133
134 Each module has a default setting which can be overridden with one of
135 the following values:
136 A build and Activate module
137 a build and Activate module IFF prereqs are available; if
138 prereqs are unavailable, don't build it
139 I build module but leave it Inactive (commented-out
140 LoadModule directive)
141 i build module but leave it Inactive IFF prereqs are
142 available; if prereqs are unavailable, don't build it
143 O Omit module completely
144
145 Examples: -DENABLE_ACCESS_COMPAT=O
146 -DENABLE_PROXY_HTML=i
147
148 ENABLE_MODULES:
149
150 This changes the *minimum* enablement of all modules to the specified
151 value (one of A, a, I, i, O, as described under ENABLE_foo above).
152
153 The ranking of enablement from lowest to highest is O, i, I, a, A.
154 If a specific module has a higher rank enablement setting, either from
155 a built-in default or from -DENABLE_foo, ENABLE_MODULES won't affect
156 that module. However, if a specific module has a lower-rank enablement
157 setting, presumably from a built-in default, the value of ENABLE_MODULES
158 will be used for that module.
159
160 Explanations for possible values:
161
162 -DENABLE_MODULES=a build and activate all possible modules,
163 ignoring any with missing prereqs
164 (doesn't affect modules with A for ENABLE_foo)
165
166 -DENABLE_MODULES=i build but leave inactive all possible
167 modules, ignoring any with missing
168 prereqs
169 (doesn't affect modules with A, a, or I for
170 ENABLE_foo)
171
172 -DENABLE_MODULES=O no impact, since all modules are either
173 already disabled or have a higher setting
174
175 -DENABLE_MODULES=A build and activate all possible modules,
176 failing the build if any module is missing
177 a prereq
178
179 -DENABLE_MODULES=I similar to -DENABLE_MODULES=A
180 (doesn't affect modules with A or a for
181 ENABLE_foo)
182
183 WITH_MODULES:
184
185 Comma-separated paths to single file modules to statically linked into
186 the server, like the --with-module=modpath:/path/to/mod_foo.c with
187 the autoconf-based build. Key differences: The modpath (e.g.,
188 "generators") isn't provided or used, and the copy of the module
189 source being built is automatically updated when it changes.
190 See also EXTRA_COMPILE_FLAGS, EXTRA_INCLUDES, and EXTRA_LIBS.
191
192 EXTRA_COMPILE_FLAGS:
193
194 Space-delimited compile flags to define with the build.
195
196 EXTRA_INCLUDES:
197
198 List of additional directories to search for .h files. This may
199 be necessary when including third-party modules in the httpd build
200 via WITH_MODULES.
201
202 EXTRA_LIBS:
203
204 List of additional libraries to link with. This may be necessary when
205 including third-party modules in the httpd build via WITH_MODULES.
206
207 Port and SSLPort:
208
209 Port numbers for substitution into default .conf files. (The defaults
210 are 80 and 443.)
211
212 INSTALL_PDB:
213
214 If .pdb files are generated for debugging, install them.
215 Default: ON
216
217 The .pdb files are generally needed for debugging low-level code
218 problems. If they aren't installed, they are still available in the
219 build directory for use by alternate packaging implementations or when
220 debugging on the build machine.
221
222 INSTALL_MANUAL:
223
224 Install the Apache HTTP Server manual.
225 Default: ON
226
227 This could be turned off when developing changes in order to speed up
228 installation time.
229
2304. Build using the chosen generator (e.g., "nmake install" for cmake's "NMake
231 Makefiles" generator).
232
233Running the server and support programs
234---------------------------------------
235
236This build system does not copy binaries such as dlls from other projects
237into the httpd install location. Without taking some precautions, httpd
238and support programs can fail to start or modules can fail to load because
239a support library can't be found in PATH or in the directory of the httpd
240binary.
241
242This can be resolved in several different ways:
243
244* Install httpd and the various support libraries to a common install
245 prefix so that support libraries and httpd programs are installed in
246 the same bin directory and are found without setting PATH.
247
248* Update PATH to include the bin directories of all necessary support
249 libraries.
250
251 Depending on where PATH is set, it may not affect starting httpd as
252 a service.
253
254* Maintain a script which combines required binaries into a common
255 location, such as the httpd installion bin directory, and use that
256 script after building or otherwise installing or updating support
257 libraries.
258
259* AVOID THE USE of any unrepeatable process of copying dll files around
260 from different install locations until something starts working. The
261 result is that when you later update a support library to pick up a
262 security fix, httpd will likely continue to use the old, vulnerable
263 library file.
264
265Known Bugs and Limitations
266--------------------------
267
268* no standard script or makefile is provided to tie together the builds
269 of httpd and support libraries in a manner suitable for typical users
270* no logic to find support libraries or otherwise build these modules:
271 + mod_socache_dc (requires distcache), mod_serf (requires serf)
272 + additionally, mod_lbmethod_rr and mod_firehose don't compile on Windows
273 anyway
274* buildmark.c isn't necessarily rebuilt when httpd.exe is regenerated
275* ApacheMonitor has a build error and is disabled
276* CGI examples aren't installed
277* dbmmanage.pl and wintty aren't built/installed
278* module enablement defaults are not in sync with the autoconf-based build
279* no support for static support library builds; unclear if that is a
280 requirement; if so: taking PCRE as an example, we'd need to detect that it
281 is static and then turn on PCRE_STATIC for the libhttpd build
282
283Generally:
284
285* Many httpd features have not been tested with this build.
286* Developers need to examine the existing Windows build in great detail and see
287 what is missing from the cmake-based build, whether a feature or some build
288 nuance.
289* Any feedback you can provide on your experiences with this build will be
290 helpful.
291
README.platforms
1
2 Apache HTTP Server
3
4 Platform specific notes:
5 ------------------------
6
7================
8 Darwin (OS X):
9 Apache 2 relies heavily on the use of autoconf and libtool to
10 provide a build environment. Darwin provides these tools as part
11 of the Developers Tools package. Under Darwin, however, GNUlibtool
12 is installed as 'glibtool' to avoid conflicting with the Darwin
13 'libtool' program. Apache 2 knows about this so that's not a
14 problem.
15
16 As of OS X 10.2 (Jaguar), the bundled versions work perfectly. Partly
17 this is due to the fact that /bin/sh is now 'bash' and not 'zsh' as
18 well as the fact that the bundled versions are up-to-date:
19 autoconf 2.52 and (g)libtool 1.4.2.
20
21 Earlier versions of OS X are not so fortunate, and the bundled tools
22 are not only older versions, but also, for the most part, do not work
23 well. If you are interested in developing under Darwin, we
24 recommend that you obtain and install replacement versions of what
25 are normally installed on Darwin (and OS X, as of v10.1.5). If
26 you build your own versions of autoconf 2.52 and libtool 1.4.2, be
27 aware that there are some Darwin specific patches to the official
28 code that still must be applied for them to fully work. A useful
29 page to check out is:
30
31 http://fink.sourceforge.net/doc/porting/libtool.php
32
33 Pier Fumagalli also provides pre-built Darwin packages of the
34 patched autoconf and libtool suites, available at:
35
36 http://www.apache.org/~pier/macosx/
37
38 You will note that GNU libtool should actually be installed as
39 glibtool, to avoid conflict with a Darwin program of the same
40 name. Pier's packages have this change already. All files are
41 installed under /usr/local/ so to use these versions, and be sure
42 that /usr/local/bin is earlier in your PATH.
43
44 There have been some reports that autoconf 2.52 prevents Apache's
45 build system from correctly handling passing multi-value envvars
46 to the build system (eg: CFLAGS="-g -O3" ./configure), causing
47 errors. Use of bash does not seem to help in this situation. If
48 this affects you, downgrading to autoconf 2.13 (which is installed
49 on Darwin) will help.
50
51 With Leopard (at least up to 10.5.2), when running configure
52 you will likely see errors such as:
53
54 rm: conftest.dSYM: is a directory
55
56 This is a known issue and will be fixed in a later version of the
57 autoconf suite. These errors can be safely ignored.
58
59 With Darwin 10, the default C compiler (gcc) will try to build
60 multi-architecture bundles. This causes problems with APR, which
61 needs to know various data-type sizes which it assumes are universal
62 for platforms. Until this is fully fixed, we recommend using the
63 '-arch i386' gcc option when building both Apache and APR.
64
65==========
66 FreeBSD:
67 autoconf 2.52 creates scripts that are incompatible with the Posix
68 shell implementation (/bin/sh) on FreeBSD. Be sure to use v2.13
69 of autoconf.
70
71 Threaded MPMs are not supported on FreeBSD 4.x. Current releases of
72 FreeBSD 5.x (5.2 or later) support threaded MPMs correctly. You must pass
73 '--enable-threads=yes' to APR's configure in order to enable threads.
74 Additionally, you must use libthr or libkse via libmap.conf as the default
75 libc_r is still broken as of this writing. Please consult the man page for
76 libmap.conf for more details about configuring libthr or libkse.
77================
78 HP-UX:
79 The dlopen() system call in HP-UX has problems when loading/unloading
80 C++ modules. The problem can be resolved by using shl_load() instead
81 of dlopen(). This is fixed in the Apache 2.0.44 release.
82 To enable loading of C++ modules, the httpd binary has to be linked with
83 the following libraries :
84
85 HP-UX (11.0 / 11i):
86 When using shl_load : "cpprt0_stub.s -lcl"
87 When using dlopen : "cpprt0_stub.s -lcl -lCsup"
88
89 HP-UX (11i version 1.5 and greater):
90 When using dlopen/shl_load : "cpprt0_stub.s -lcl -lunwind"
91
92 The cpprt0_stub.s can be downloaded from the web site :
93 http://h21007.www2.hp.com/hpux-devtools/CXX/hpux-devtools.0107/0083.html
94
95 Compile cpprt0_stub.s with the PIC option
96 cc -c +z cpprt0_stub.s
97 - OR -
98 gcc -c -fPIC cpprt0_stub.s
99================
100 AIX, using the vendor C compiler with optimization:
101 There is an issue with compiling server/core.c with optimization enabled
102 which has been seen with C for AIX 5.0.2.3 and above. (5.0.2.0, 5.0.2.1,
103 and 5.0.2.2 have an additional problem with Apache 2.0.x, so either upgrade
104 the compiler or don't use optimization in order to avoid it.)
105
106 cc_r works fine with -O2 but xlc_r does not. In order to use xlc_r with
107 -O2, apply the patch at
108
109 http://www.apache.org/dist/httpd/patches/apply_to_2.0.49/aix_xlc_optimization.patch
110
111 (That patch works with many recent levels of Apache 2+.)
112
113================
114 Solaris:
115
116 On Solaris, better performance may be achieved by using the Sun Studio
117 compiler instead of gcc. As of version 11, it is now free (registration
118 required). Download the compiler from:
119
120 http://developers.sun.com/prodtech/cc/downloads/index.jsp
121
122 If you use Sun Studio, the following compiler flags (CFLAGS) are
123 recommended:
124
125 -XO4 -xchip=generic
126
127================
128 Ubuntu:
129
130 You will need to ensure that you have either libtool 1.5.6
131 or 2.2.6b, or later. Expat 2.0.1 and PCRE 8.02 are also
132 recommended to be installed. If building PCRE from source,
133 you'll also need g++.
134