diff options
| author | Bob Beck <beck@cvs.openbsd.org> | 1998-10-01 17:20:20 +0000 |
|---|---|---|
| committer | Bob Beck <beck@cvs.openbsd.org> | 1998-10-01 17:20:20 +0000 |
| commit | 44becabb19680fe2222a8dbb4374ec6ca8ffa42e (patch) | |
| tree | e03a0a63c479404cec8d906cebc03ab087026655 /usr.sbin/httpd/htdocs | |
| parent | 7f834b276e9c197c47fb88f2daf16c7552648eea (diff) | |
Apache 1.3.2
Diffstat (limited to 'usr.sbin/httpd/htdocs')
38 files changed, 9603 insertions, 0 deletions
diff --git a/usr.sbin/httpd/htdocs/manual/dso.html b/usr.sbin/httpd/htdocs/manual/dso.html new file mode 100644 index 00000000000..da6d0f13978 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/dso.html @@ -0,0 +1,399 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>Apache 1.3 Dynamic Shared Object (DSO) support</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<BLOCKQUOTE> +<DIV ALIGN="CENTER"> + <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + + +<DIV ALIGN=CENTER> + +<H1> +Apache 1.3<BR> +Dynamic Shared Object (DSO)<BR> +Support +</H1> + +<ADDRESS>Originally written by<BR> +Ralf S. Engelschall <rse@apache.org>, April 1998</ADDRESS> + +</DIV> + +<H3>Background</H3> + +<P>On modern Unix derivatives there exists a nifty mechanism usually called +dynamic linking/loading of <EM>Dynamic Shared Objects</EM> (DSO) which +provides a way to build a piece of program code in a special format for +loading it at run-time into the address space of an executable program. + +<P>This loading can usually be done in two ways: Automatically by a system +program called <CODE>ld.so</CODE> when an executable program is started or +manually from within the executing program via a programmatic system interface +to the Unix loader through the system calls <CODE>dlopen()/dlsym()</CODE>. + +<P>In the first way the DSO's are usually called <EM>shared libraries</EM> or +<EM>DSO libraries</EM> and named <CODE>libfoo.so</CODE> or +<CODE>libfoo.so.1.2</CODE>. They reside in a system directory (usually +<CODE>/usr/lib</CODE>) and the link to the executable program is established +at build-time by specifying <CODE>-lfoo</CODE> to the linker command. This +hard-codes library references into the executable program file so that at +start-time the Unix loader is able to locate <CODE>libfoo.so</CODE> in +<CODE>/usr/lib</CODE>, in paths hard-coded via linker-options like +<CODE>-R</CODE> or in paths configured via the environment variable +<CODE>LD_LIBRARY_PATH</CODE>. It then resolves any (yet unresolved) symbols in +the executable program which are available in the DSO. + +<P>Symbols in the executable program are usually not referenced by the DSO +(because it's a reusable library of general code) and hence no further +resolving has to be done. The executable program has no need to do anything on +its own to use the symbols from the DSO because the complete resolving is done +by the Unix loader. (In fact, the code to invoke <CODE>ld.so</CODE> is part of +the run-time startup code which is linked into every executable program which +has been bound non-static). The advantage of dynamic loading of common library +code is obvious: the library code needs to be stored only once, in a system +library like <CODE>libc.so</CODE>, saving disk space for every program. + +<P>In the second way the DSO's are usually called <EM>shared objects</EM> or +<EM>DSO files</EM> and can be named with an arbitrary extension (although the +canonical name is <CODE>foo.so</CODE>). These files usually stay inside a +program-specific directory and there is no automatically established link to +the executable program where they are used. Instead the executable program +manually loads the DSO at run-time into its address space via +<CODE>dlopen()</CODE>. At this time no resolving of symbols from the DSO for +the executable program is done. But instead the Unix loader automatically +resolves any (yet unresolved) symbols in the DSO from the set of symbols +exported by the executable program and its already loaded DSO libraries +(especially all symbols from the ubiquitous <CODE>libc.so</CODE>). This way +the DSO gets knowledge of the executable program's symbol set as if it had +been statically linked with it in the first place. + +<P>Finally, to take advantage of the DSO's API the executable program has to +resolve particular symbols from the DSO via <CODE>dlsym()</CODE> for later use +inside dispatch tables <EM>etc.</EM> In other words: The executable program has to +manually resolve every symbol it needs to be able to use it. The advantage of +such a mechanism is that optional program parts need not be loaded (and thus +do not spend memory) until they are needed by the program in question. When +required, these program parts can be loaded dynamically to extend the base +program's functionality. + +<P>Although this DSO mechanism sounds straightforward there is at least one +difficult step here: The resolving of symbols from the executable program for +the DSO when using a DSO to extend a program (the second way). Why? Because +"reverse resolving" DSO symbols from the executable program's symbol set is +against the library design (where the library has no knowledge about the +programs it is used by) and is neither available under all platforms nor +standardized. In practice the executable program's global symbols are often +not re-exported and thus not available for use in a DSO. Finding a way to +force the linker to export all global symbols is the main problem one has to +solve when using DSO for extending a program at run-time. + +<H3>Practical Usage</H3> + +<P>The shared library approach is the typical one, because it is what the DSO +mechanism was designed for, hence it is used for nearly all types of libraries +the operating system provides. On the other hand using shared objects for +extending a program is not used by a lot of programs. + +<P>As of 1998 there are only a few software packages available which use the +DSO mechanism to actually extend their functionality at run-time: Perl 5 (via +its XS mechanism and the DynaLoader module), Netscape Server, <EM>etc.</EM> Starting +with version 1.3, Apache joined the crew, because Apache already uses a module +concept to extend its functionality and internally uses a dispatch-list-based +approach to link external modules into the Apache core functionality. So, +Apache is really predestined for using DSO to load its modules at run-time. + +<P>As of Apache 1.3, the configuration system supports two optional features +for taking advantage of the modular DSO approach: compilation of the Apache +core program into a DSO library for shared usage and compilation of the +Apache modules into DSO files for explicit loading at run-time. + +<H3>Implementation</H3> + +<P>The DSO support for loading individual Apache modules is based on a module +named <A HREF="mod/mod_so.html"><CODE>mod_so.c</CODE></A> which has to be +statically compiled into the Apache core. It is the only module besides +<CODE>http_core.c</CODE> which cannot be put into a DSO itself +(bootstrapping!). Practically all other distributed Apache modules then can +then be placed into a DSO by individually enabling the DSO build for them via +<CODE>configure</CODE>'s <CODE>--enable-shared</CODE> option (see top-level +<CODE>INSTALL</CODE> file) or by changing the <CODE>AddModule</CODE> command +in your <CODE>src/Configuration</CODE> into a <CODE>SharedModule</CODE> +command (see <CODE>src/INSTALL</CODE> file). After a module is compiled into +a DSO named <CODE>mod_foo.so</CODE> you can use <A +HREF="mod/mod_so.html"><CODE>mod_so</CODE></A>'s <A +HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> command in your +<CODE>httpd.conf</CODE> file to load this module at server startup or restart. + +<P>To simplify this creation of DSO files for Apache modules (especially for +third-party modules) a new support program named <CODE>apxs</CODE> (<EM>APache +eXtenSion</EM>) is available. It can be used to build DSO based modules +<EM>outside of</EM> the Apache source tree. The idea is simple: When +installing Apache the <CODE>configure</CODE>'s <CODE>make install</CODE> +procedure installs the Apache C header files and puts the platform-dependent +compiler and linker flags for building DSO files into the <CODE>apxs</CODE> +program. This way the user can use <CODE>apxs</CODE> to compile his Apache +module sources without the Apache distribution source tree and without having +to fiddle with the platform-dependent compiler and linker flags for DSO +support. + +<P>To place the complete Apache core program into a DSO library (only required +on some of the supported platforms to force the linker to export the apache +core symbols -- a prerequisite for the DSO modularization) the rule +<CODE>SHARED_CORE</CODE> has to be enabled via <CODE>configure</CODE>'s +<CODE>--enable-rule=SHARED_CORE</CODE> option (see top-level +<CODE>INSTALL</CODE> file) or by changing the <CODE>Rule</CODE> command in +your <CODE>Configuration</CODE> file to <CODE>Rule SHARED_CORE=yes</CODE> (see +<CODE>src/INSTALL</CODE> file). The Apache core code is then placed into a DSO +library named <CODE>libhttpd.so</CODE>. Because one cannot link a DSO against +static libraries on all platforms, an additional executable program named +<CODE>libhttpd.ep</CODE> is created which both binds this static code and +provides a stub for the <CODE>main()</CODE> function. Finally the +<CODE>httpd</CODE> executable program itself is replaced by a bootstrapping +code which automatically makes sure the Unix loader is able to load and start +<CODE>libhttpd.ep</CODE> by providing the <CODE>LD_LIBRARY_PATH</CODE> to +<CODE>libhttpd.so</CODE>. + +<H3>Supported Platforms</H3> + +<P>Apache's <CODE>src/Configure</CODE> script currently has only limited but +adequate built-in knowledge on how to compile DSO files, because as already +mentioned this is heavily platform-dependent. Nevertheless all major Unix +platforms are supported. The definitive current state (May 1998) is this: + +<P> +<UL> +<LI>Out-of-the-box supported platforms:<BR> +(actually tested versions in parenthesis) + +<PRE> +o FreeBSD (2.1.5, 2.2.5, 2.2.6) +o OpenBSD (2.x) +o NetBSD (1.3.1) +o Linux (Debian/1.3.1, RedHat/4.2) +o Solaris (2.4, 2.5.1, 2.6) +o SunOS (4.1.3) +o Digital UNIX (4.0) +o IRIX (6.2) +o HP/UX (10.20) +o UnixWare (2.01, 2.1.2) +o SCO (5.0.4) +o AIX (3.2, 4.1.5, 4.2, 4.3) +o ReliantUNIX/SINIX (5.43) +o SVR4 (-) +</PRE> + +<P> +<LI> Explicitly unsupported platforms: + +<PRE> +o Ultrix (no dlopen-style interface under this platform) +</PRE> + +</UL> + +<H3>Usage Summary</H3> + +<P>To give you an overview of the DSO features of Apache 1.3, here is a short +and concise summary: + +<OL> + +<LI>Placing the Apache core code (all the stuff which usually forms the +<CODE>httpd</CODE> binary) into a DSO <CODE>libhttpd.so</CODE>, an executable +program <CODE>libhttpd.ep</CODE> and a bootstrapping executable program +<CODE>httpd</CODE> (Notice: this is only required on some of the supported +platforms to force the linker to export the Apache core symbols, which in turn +is a prerequisite for the DSO modularization): + +<P> +<UL> +<LI>Build and install via <CODE>configure</CODE> (preferred): +<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> +<PRE> +$ ./configure --prefix=/path/to/install + --enable-rule=SHARED_CORE ... +$ make install +</PRE> +</TD></TR></TABLE> + +<LI>Build and install manually: +<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> +<PRE> +- Edit src/Configuration: + << Rule SHARED_CORE=default + >> Rule SHARED_CORE=yes + << EXTRA_CFLAGS= + >> EXTRA_CFLAGS= -DSHARED_CORE_DIR=\"/path/to/install/libexec\" +$ make +$ cp src/libhttpd.so* /path/to/install/libexec/ +$ cp src/libhttpd.ep /path/to/install/libexec/ +$ cp src/httpd /path/to/install/bin/ +</PRE> +</TD></TR></TABLE> +</UL> + +<LI>Build and install a <EM>distributed</EM> Apache module, say +<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE>: + +<P> +<UL> +<LI>Build and install via <CODE>configure</CODE> (preferred): +<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> +<PRE> +$ ./configure --prefix=/path/to/install + --enable-shared=foo +$ make install +</PRE> +</TD></TR></TABLE> + +<LI>Build and install manually: +<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> +<PRE> +- Edit src/Configuration: + << AddModule modules/xxxx/mod_foo.o + >> SharedModule modules/xxxx/mod_foo.so +$ make +$ cp src/xxxx/mod_foo.so /path/to/install/libexec +- Edit /path/to/install/etc/httpd.conf + >> LoadModule foo_module /path/to/install/libexec/mod_foo.so +</PRE> +</TD></TR></TABLE> +</UL> + +<LI>Build and install a <EM>third-party</EM> Apache module, say +<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE> + +<P> +<UL> +<LI>Build and install via <CODE>configure</CODE> (preferred): +<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> +<PRE> +$ ./configure --add-module=/path/to/3rdparty/mod_foo.c + --enable-shared=foo +$ make install +</PRE> +</TD></TR></TABLE> + +<LI>Build and install manually: +<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> +<PRE> +$ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/ +- Edit src/Configuration: + >> SharedModule modules/extra/mod_foo.so +$ make +$ cp src/xxxx/mod_foo.so /path/to/install/libexec +- Edit /path/to/install/etc/httpd.conf + >> LoadModule foo_module /path/to/install/libexec/mod_foo.so +</PRE> +</TD></TR></TABLE> +</UL> + +<P> +<LI>Build and install a <EM>third-party</EM> Apache module, say +<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE> <EM>outside +of</EM> the Apache source tree: + +<P> +<UL> +<LI>Build and install via <CODE>apxs</CODE>: +<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> +<PRE> +$ cd /path/to/3rdparty +$ apxs -c mod_foo.c +$ apxs -i -a -n foo mod_foo.so +</PRE> +</TD></TR></TABLE> +</UL> + +</OL> + +<H3>Advantages & Disadvantages</H3> + +<P>The above DSO based features of Apache 1.3 have the following advantages: + +<UL> +<LI> The server package is more flexible at run-time because the actual server + process can be assembled at run-time via <A + HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> + <CODE>httpd.conf</CODE> configuration commands instead of + <CODE>Configuration</CODE> <CODE>AddModule</CODE> commands at build-time. + For instance this way one is able to run different server instances + (standard & SSL version, minimalistic & powered up version + [mod_perl, PHP3], <EM>etc.</EM>) with only one Apache installation. +<P> +<LI> The server package can be easily extended with third-party modules even + after installation. This is at least a great benefit for vendor package + maintainers who can create a Apache core package and additional packages + containing extensions like PHP3, mod_perl, mod_fastcgi, <EM>etc.</EM> +<P> +<LI> Easier Apache module prototyping because with the DSO/<CODE>apxs</CODE> + pair you can both work outside the Apache source tree and only need an + <CODE>apxs -i</CODE> command followed by an <CODE>apachectl + restart</CODE> to bring a new version of your currently developed module + into the running Apache server. +</UL> + +<P>DSO has the following disadvantages: + +<UL> +<LI> The DSO mechanism cannot be used on every platform because not all + operating systems support dynamic loading of code into the address space + of a program. +<P> +<LI> The server is approximately 20% slower at startup time because of the + symbol resolving overhead the Unix loader now has to do. +<P> +<LI> The server is approximately 5% slower at execution time under some + platforms because position independent code (PIC) sometimes needs + complicated assembler tricks for relative addressing which are not + necessarily as fast as absolute addressing. +<P> +<LI> Because DSO modules cannot be linked against other DSO-based libraries + (<CODE>ld -lfoo</CODE>) on all platforms (for instance a.out-based + platforms usually don't provide this functionality while ELF-based + platforms do) you cannot use the DSO mechanism for all types of modules. + Or in other words, modules compiled as DSO files are restricted to only + use symbols from the Apache core, from the C library (<CODE>libc</CODE>) + and all other dynamic or static libraries used by the Apache core, or + from static library archives (<CODE>libfoo.a</CODE>) containing position + independent code. The only chances to use other code is to either make + sure the Apache core itself already contains a reference to it, loading + the code yourself via <CODE>dlopen()</CODE> or enabling the + <CODE>SHARED_CHAIN</CODE> rule while building Apache when your platform + supports linking DSO files against DSO libraries. +<P> +<LI> Under some platforms (many SVR4 systems) there is no way to force the + linker to export all global symbols for use in DSO's when linking the + Apache httpd executable program. But without the visibility of the Apache + core symbols no standard Apache module could be used as a DSO. The only + chance here is to use the <CODE>SHARED_CORE</CODE> feature because this + way the global symbols are forced to be exported. As a consequence the + Apache <CODE>src/Configure</CODE> script automatically enforces + <CODE>SHARED_CORE</CODE> on these platforms when DSO features are used in + the <CODE>Configuration</CODE> file or on the configure command line. +</UL> + +<HR> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> + +<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> + +</BLOCKQUOTE> +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/ebcdic.html b/usr.sbin/httpd/htdocs/manual/ebcdic.html new file mode 100644 index 00000000000..3ce6116c0ff --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/ebcdic.html @@ -0,0 +1,509 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>The Apache EBCDIC Port</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Overview of the Apache EBCDIC Port</H1> + + <P> + Version 1.3 of the Apache HTTP Server is the first version which + includes a port to a (non-ASCII) mainframe machine which uses + the EBCDIC character set as its native codeset.<BR> + (It is the SIEMENS NIXDORF family of mainframes running the + <A HREF="http://www.sni.de/servers/bs2osd/osdbc_us.htm">BS2000/OSD + operating system</A>. This mainframe OS nowadays features a + SVR4-derived POSIX subsystem). + </P> + + <P> + The port was started initially to + <UL> + <LI> prove the feasibility of porting + <A HREF="http://dev.apache.org/">the Apache HTTP server</A> + to this platform + <LI> find a "worthy and capable" successor for the venerable + <A HREF="http://www.w3.org/Daemon/">CERN-3.0</A> daemon + (which was ported a couple of years ago), and to + <LI> prove that Apache's preforking process model can on this platform + easily outperform the accept-fork-serve model used by CERN by a + factor of 5 or more. + </UL> + </P> + + <P> + This document serves as a rationale to describe some of the design + decisions of the port to this machine. + </P> + + <H2 ALIGN=CENTER>Design Goals</H2> + <P> + One objective of the EBCDIC port was to maintain enough backwards + compatibility with the (EBCDIC) CERN server to make the transition to + the new server attractive and easy. This required the addition of + a configurable method to define whether a HTML document was stored + in ASCII (the only format accepted by the old server) or in EBCDIC + (the native document format in the POSIX subsystem, and therefore + the only realistic format in which the other POSIX tools like grep + or sed could operate on the documents). The current solution to + this is a "pseudo-MIME-format" which is intercepted and + interpreted by the Apache server (see below). Future versions + might solve the problem by defining an "ebcdic-handler" for all + documents which must be converted. + </P> + + <H2 ALIGN=CENTER>Technical Solution</H2> + <P> + Since all Apache input and output is based upon the BUFF data type + and its methods, the easiest solution was to add the conversion to + the BUFF handling routines. The conversion must be settable at any + time, so a BUFF flag was added which defines whether a BUFF object + has currently enabled conversion or not. This flag is modified at + several points in the HTTP protocol: + <UL> + <LI><STRONG>set</STRONG> before a request is received (because the + request and the request header lines are always in ASCII + format) + + <LI><STRONG>set/unset</STRONG> when the request body is + received - depending on the content type of the request body + (because the request body may contain ASCII text or a binary file) + + <LI><STRONG>set</STRONG> before a reply header is sent (because the + response header lines are always in ASCII format) + + <LI><STRONG>set/unset</STRONG> when the response body is + sent - depending on the content type of the response body + (because the response body may contain text or a binary file) + </UL> + </P> + +<H2 ALIGN=CENTER>Porting Notes</H2> + <P> + <OL> + <LI> + The relevant changes in the source are #ifdef'ed into two + categories: + <DL> + <DT><CODE><STRONG>#ifdef CHARSET_EBCDIC</STRONG></CODE> + <DD>Code which is needed for any EBCDIC based machine. This + includes character translations, differences in + contiguity of the two character sets, flags which + indicate which part of the HTTP protocol has to be + converted and which part doesn't <EM>etc.</EM> + <DT><CODE><STRONG>#ifdef _OSD_POSIX</STRONG></CODE> + <DD>Code which is needed for the BS2000 SIEMENS NIXDORF + mainframe platform only. This deals with include file + differences and socket implementations topics which are + only required on the BS2000/OSD platform. + </DL> + </LI><BR> + + <LI> + The possibility to translate between ASCII and EBCDIC at the + socket level (on BS2000 POSIX, there is a socket option which + supports this) was intentionally <EM>not</EM> chosen, because + the byte stream at the HTTP protocol level consists of a + mixture of protocol related strings and non-protocol related + raw file data. HTTP protocol strings are always encoded in + ASCII (the GET request, any Header: lines, the chunking + information <EM>etc.</EM>) whereas the file transfer parts (<EM>i.e.</EM>, GIF + images, CGI output <EM>etc.</EM>) should usually be just "passed through" + by the server. This separation between "protocol string" and + "raw data" is reflected in the server code by functions like + bgets() or rvputs() for strings, and functions like bwrite() + for binary data. A global translation of everything would + therefore be inadequate.<BR> + (In the case of text files of course, provisions must be made so + that EBCDIC documents are always served in ASCII) + </LI><BR> + + <LI> + This port therefore features a built-in protocol level conversion + for the server-internal strings (which the compiler translated to + EBCDIC strings) and thus for all server-generated documents. + The hard coded ASCII escapes \012 and \015 which are + ubiquitous in the server code are an exception: they are + already the binary encoding of the ASCII \n and \r and must + not be converted to ASCII a second time. This exception is + only relevant for server-generated strings; and <EM>external</EM> + EBCDIC documents are not expected to contain ASCII newline characters. + </LI><BR> + + <LI> + By examining the call hierarchy for the BUFF management + routines, I added an "ebcdic/ascii conversion layer" which + would be crossed on every puts/write/get/gets, and a + conversion flag which allowed enabling/disabling the + conversions on-the-fly. Usually, a document crosses this + layer twice from its origin source (a file or CGI output) to + its destination (the requesting client): <SAMP>file -> + Apache</SAMP>, and <SAMP>Apache -> client</SAMP>.<BR> + The server can now read the header + lines of a CGI-script output in EBCDIC format, and then find + out that the remainder of the script's output is in ASCII + (like in the case of the output of a WWW Counter program: the + document body contains a GIF image). All header processing is + done in the native EBCDIC format; the server then determines, + based on the type of document being served, whether the + document body (except for the chunking information, of + course) is in ASCII already or must be converted from EBCDIC. + </LI><BR> + + <LI> + For Text documents (MIME types text/plain, text/html <EM>etc.</EM>), + an implicit translation to ASCII can be used, or (if the + users prefer to store some documents in raw ASCII form for + faster serving, or because the files reside on a NFS-mounted + directory tree) can be served without conversion. + <BR> + <STRONG>Example:</STRONG><BLOCKQUOTE> + to serve files with the suffix .ahtml as a raw ASCII text/html + document without implicit conversion (and suffix .ascii + as ASCII text/plain), use the directives:<PRE> + AddType text/x-ascii-html .ahtml + AddType text/x-ascii-plain .ascii + </PRE></BLOCKQUOTE> + Similarly, any text/XXXX MIME type can be served as "raw ASCII" by + configuring a MIME type "text/x-ascii-XXXX" for it using AddType. + </LI><BR> + + <LI> + Non-text documents are always served "binary" without conversion. + This seems to be the most sensible choice for, .<EM>e.g.</EM>, GIF/ZIP/AU + file types. This of course requires the user to copy them to the + mainframe host using the "rcp -b" binary switch. + </LI><BR> + + <LI> + Server parsed files are always assumed to be in native (<EM>i.e.</EM>, + EBCDIC) format as used on the machine, and are converted after + processing. + </LI><BR> + + <LI> + For CGI output, the CGI script determines whether a conversion is + needed or not: by setting the appropriate Content-Type, text files + can be converted, or GIF output can be passed through unmodified. + An example for the latter case is the wwwcount program which we ported + as well. + </LI><BR> + </OL> + </P> + + <H2 ALIGN=CENTER>Document Storage Notes</H2> + <H3 ALIGN=CENTER>Binary Files</H3> + <P> + All files with a <SAMP>Content-Type:</SAMP> which does not + start with <SAMP>text/</SAMP> are regarded as <EM>binary files</EM> + by the server and are not subject to any conversion. + Examples for binary files are GIF images, gzip-compressed + files and the like. + </P> + <P> + When exchanging binary files between the mainframe host and a + Unix machine or Windows PC, be sure to use the ftp "binary" + (<SAMP>TYPE I</SAMP>) command, or use the + <SAMP>rcp -b</SAMP> command from the mainframe host + (the -b switch is not supported in unix rcp's). + </P> + + <H3 ALIGN=CENTER>Text Documents</H3> + <P> + The default assumption of the server is that Text Files + (<EM>i.e.</EM>, all files whose <SAMP>Content-Type:</SAMP> starts with + <SAMP>text/</SAMP>) are stored in the native character + set of the host, EBCDIC. + </P> + + <H3 ALIGN=CENTER>Server Side Included Documents</H3> + <P> + SSI documents must currently be stored in EBCDIC only. No + provision is made to convert it from ASCII before processing. + </P> + + <H2 ALIGN=CENTER>Apache Modules' Status</H2> + <TABLE BORDER ALIGN=middle> + <TR> + <TH>Module + <TH>Status + <TH>Notes + </TR> + + <TR> + <TD ALIGN=LEFT>http_core + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_access + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_actions + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_alias + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_asis + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_auth + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_auth_anon + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_auth_db + <TD ALIGN=CENTER>? + <TD>with own libdb.a + </TR> + + <TR> + <TD ALIGN=LEFT>mod_auth_dbm + <TD ALIGN=CENTER>? + <TD>with own libdb.a + </TR> + + <TR> + <TD ALIGN=LEFT>mod_autoindex + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_cern_meta + <TD ALIGN=CENTER>? + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_cgi + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_digest + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_dir + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_so + <TD ALIGN=CENTER>- + <TD>no shared libs + </TR> + + <TR> + <TD ALIGN=LEFT>mod_env + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_example + <TD ALIGN=CENTER>- + <TD>(test bed only) + </TR> + + <TR> + <TD ALIGN=LEFT>mod_expires + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_headers + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_imap + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_include + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_info + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_log_agent + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_log_config + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_log_referer + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_mime + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_mime_magic + <TD ALIGN=CENTER>- + <TD>not ported yet + </TR> + + <TR> + <TD ALIGN=LEFT>mod_negotiation + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_proxy + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_rewrite + <TD ALIGN=CENTER>+ + <TD>untested + </TR> + + <TR> + <TD ALIGN=LEFT>mod_setenvif + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_speling + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_status + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_unique_id + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_userdir + <TD ALIGN=CENTER>+ + <TD> + </TR> + + <TR> + <TD ALIGN=LEFT>mod_usertrack + <TD ALIGN=CENTER>? + <TD>untested + </TR> + </TABLE> + + <H2 ALIGN=CENTER>Third Party Modules' Status</H2> + <TABLE BORDER ALIGN=middle> + <TR> + <TH>Module + <TH>Status + <TH>Notes + </TR> + + <TR> + <TD ALIGN=LEFT><A HREF="http://java.apache.org/">mod_jserv</A> + <TD ALIGN=CENTER>- + <TD>JAVA still being ported. + </TR> + + <TR> + <TD ALIGN=LEFT><A HREF="http://www.php.net/">mod_php3</A> + <TD ALIGN=CENTER>+ + <TD>mod_php3 runs fine, with LDAP and GD libraries + </TR> + + <TR> + <TD ALIGN=LEFT + ><A HREF="http://hpwww.ec-lyon.fr/~vincent/apache/mod_put.html">mod_put</A> + <TD ALIGN=CENTER>? + <TD>untested + </TR> + + <TR> + <TD ALIGN=LEFT + ><A HREF="ftp://hachiman.vidya.com/pub/apache/">mod_session</A> + <TD ALIGN=CENTER>- + <TD>untested + </TR> + + </TABLE> + +<HR> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> + +<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/images/custom_errordocs.gif b/usr.sbin/httpd/htdocs/manual/images/custom_errordocs.gif Binary files differnew file mode 100644 index 00000000000..d566c5d891e --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/images/custom_errordocs.gif diff --git a/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig1.fig b/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig1.fig new file mode 100644 index 00000000000..7c80fea3f1d --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig1.fig @@ -0,0 +1,60 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +0 32 #efefef +0 33 #cfcfef +0 34 #bebebe +2 1 0 4 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 6675 5250 6900 5250 6900 4650 4950 4650 4950 4050 5475 4050 +2 1 0 4 4 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 6900 4050 7650 4050 +2 1 0 4 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9375 4050 9900 4050 9900 4650 7200 4650 7200 5250 7650 5250 +2 1 0 4 9 7 0 0 -1 0.000 0 0 -1 1 0 4 + 1 1 2.00 120.00 240.00 + 9300 5250 9900 5250 9900 6300 6975 6300 +2 1 2 4 0 7 0 0 -1 7.500 1 1 -1 0 0 2 + 3900 2100 3900 1500 +2 1 2 4 0 7 0 0 -1 7.500 1 1 -1 0 0 2 + 3900 7950 3900 7350 +2 1 1 4 9 7 0 0 -1 10.000 0 0 -1 1 0 4 + 1 1 2.00 120.00 240.00 + 5625 6300 2700 6300 2700 7050 3225 7050 +2 1 0 4 9 7 0 0 -1 0.000 0 0 -1 1 0 4 + 1 1 2.00 120.00 240.00 + 5550 3000 2700 3000 2700 5250 3225 5250 +2 1 1 4 9 7 0 0 -1 10.000 0 0 -1 1 0 4 + 1 1 2.00 120.00 240.00 + 9225 2325 9900 2325 9900 3000 6975 3000 +2 1 0 4 9 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 4800 5250 5550 5250 +2 4 0 2 9 7 0 0 -1 0.000 0 0 7 0 0 5 + 6900 3300 5700 3300 5700 2700 6900 2700 6900 3300 +2 4 0 2 9 7 0 0 -1 0.000 0 0 7 0 0 5 + 6900 6600 5700 6600 5700 6000 6900 6000 6900 6600 +4 0 0 0 0 0 20 0.0000 4 195 1455 3300 5400 RewriteRule\001 +4 0 0 0 0 1 20 0.0000 4 210 1440 7800 4200 CondPattern\001 +4 0 0 0 0 1 20 0.0000 4 270 1110 5625 4200 TestString\001 +4 0 0 0 0 0 20 0.0000 4 195 1905 3300 4200 RewriteCond \001 +4 0 0 0 0 1 20 0.0000 4 210 1320 7800 5400 Substitution\001 +4 0 0 0 0 1 20 0.0000 4 195 825 5700 5400 Pattern\001 +4 0 0 0 0 0 20 0.0000 4 195 1455 3300 7200 RewriteRule\001 +4 0 0 0 0 0 20 0.0000 4 195 1455 3300 2400 RewriteRule\001 +4 0 0 0 0 1 20 0.0000 4 195 825 5700 7200 Pattern\001 +4 0 0 0 0 1 20 0.0000 4 210 1320 7800 7200 Substitution\001 +4 0 0 0 0 1 20 0.0000 4 210 1320 7800 2400 Substitution\001 +4 0 0 0 0 1 20 0.0000 4 195 825 5700 2400 Pattern\001 +4 0 9 0 0 18 12 0.0000 4 135 645 6000 2925 current\001 +4 0 9 0 0 18 12 0.0000 4 135 375 6075 3150 URL\001 +4 0 9 0 0 18 12 0.0000 4 135 825 5925 6225 rewritten\001 +4 0 9 0 0 18 12 0.0000 4 135 375 6075 6450 URL\001 diff --git a/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig1.gif b/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig1.gif Binary files differnew file mode 100644 index 00000000000..664ac1e7bb7 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig1.gif diff --git a/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig2.fig b/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig2.fig new file mode 100644 index 00000000000..facf410fc98 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig2.fig @@ -0,0 +1,50 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +0 32 #efefef +0 33 #cfcfef +0 34 #bebebe +2 1 2 4 0 7 0 0 -1 10.000 1 1 -1 0 0 2 + 4050 3750 4050 4425 +2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 4950 4800 5550 4800 +2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 4950 3600 5550 3600 +2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 6600 5700 7725 5700 +2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 6600 5550 6900 5550 6900 5100 4950 5100 4950 2850 5550 2850 +2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9525 4800 9750 4800 9750 5100 7200 5100 7200 5550 7725 5550 +2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9450 3000 9750 3000 9750 3225 5100 3225 5100 3450 5550 3450 +2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9450 3600 9750 3600 9750 3825 5100 3825 5100 4050 5550 4050 +2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9450 4200 9750 4200 9750 4425 5100 4425 5100 4650 5550 4650 +4 0 0 0 0 0 20 0.0000 4 195 1905 3300 4800 RewriteCond \001 +4 0 0 0 0 1 20 0.0000 4 210 1620 7800 4800 CondPatternN\001 +4 0 0 0 0 0 20 0.0000 4 195 1905 3300 3600 RewriteCond \001 +4 0 0 0 0 1 20 0.0000 4 210 1575 7800 3600 CondPattern2\001 +4 0 0 0 0 1 20 0.0000 4 270 1290 5625 4800 TestStringN\001 +4 0 0 0 0 1 20 0.0000 4 270 1245 5625 3600 TestString2\001 +4 0 0 0 0 0 20 0.0000 4 195 1905 3300 3000 RewriteCond \001 +4 0 0 0 0 1 20 0.0000 4 270 1245 5625 3000 TestString1\001 +4 0 0 0 0 1 20 0.0000 4 210 1575 7800 3000 CondPattern1\001 +4 0 0 0 0 1 20 0.0000 4 210 1320 7800 5700 Substitution\001 +4 0 0 0 0 1 20 0.0000 4 195 825 5700 5700 Pattern\001 +4 0 0 0 0 0 20 0.0000 4 195 1455 3300 5700 RewriteRule\001 diff --git a/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig2.gif b/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig2.gif Binary files differnew file mode 100644 index 00000000000..3ea8cb65a3f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/images/mod_rewrite_fig2.gif diff --git a/usr.sbin/httpd/htdocs/manual/misc/HTTP_Features.tsv b/usr.sbin/httpd/htdocs/manual/misc/HTTP_Features.tsv new file mode 100644 index 00000000000..893403d898f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/HTTP_Features.tsv @@ -0,0 +1,142 @@ +This tab-separated-value file is for use as a checklist +for features against <draft-ietf-http-v11-spec-rev-03.txt>, +since two independently developed and interoperable +implementations are needed for each feature. For each entry, + ? means not filled-in + - means not applicable + n means no + y means yes + Y means yes with the addition of a module that uses feature + +The contents should be placed in the form at <http://www.agranat.com:1998/> +by someone who wants to be the contact for the Apache Group. + +Section Feature Implemented Tested +8.1 Persistent Connections y y +8.2.3 Automatic retrying of requests - - +8.2.4 Use of the 100 (Continue) status n n +9.2 OPTIONS y y +9.3 GET y y +9.4 HEAD y y +9.5 POST y y +9.6 PUT Y y +9.7 DELETE Y y +9.8 TRACE y y +9.9 CONNECT y y +10.1.1 100 Continue y y +10.1.2 101 Switching Protocols Y n +10.2.1 200 OK y y +10.2.2 201 Created y y +10.2.3 202 Accepted y y +10.2.4 203 Non-Authoritative Information y y +10.2.5 204 No Content y y +10.2.6 205 Reset Content y y +10.2.7 206 Partial Content y y +10.3.1 300 Multiple Choices y y +10.3.2 301 Moved Permanently y y +10.3.3 302 Found y y +10.3.4 303 See Other y y +10.3.5 304 Not Modified y y +10.3.6 305 Use Proxy y n +10.3.7 307 Temporary Redirect n n +10.4.1 400 Bad Request y y +10.4.2 401 Unauthorized y y +10.4.3 402 Payment Required Y n +10.4.4 403 Forbidden y y +10.4.5 404 Not Found y y +10.4.6 405 Method Not Allowed y y +10.4.7 406 Not Acceptable y y +10.4.8 407 Proxy Authentication Required y y +10.4.9 408 Request Timeout y y +10.4.10 409 Conflict Y n +10.4.11 410 Gone y y +10.4.12 411 Length Required y y +10.4.13 412 Precondition Failed y y +10.4.14 413 Request Entity Too Large y y +10.4.15 414 Request-URI Too Long y y +10.4.16 415 Unsupported Media Type y n +10.4.17 416 Requested range not satisfiable n n +10.4.18 417 Expectation Failed n n +10.5.1 500 Internal Server Error y y +10.5.2 501 Not Implemented y y +10.5.3 502 Bad Gateway y y +10.5.4 503 Service Unavailable y y +10.5.5 504 Gateway Timeout y y +10.5.6 505 HTTP Version Not Supported Y n +13.3.3 Strong entity tags y y +13.3.3 Weak entity tags y y +14.1 Accept y y +14.2 Accept-Charset y y +14.3 Accept-Encoding n n +14.4 Accept-Language y y +14.5 Accept-Ranges y y +14.6 Age - - +14.7 Allow y y +14.8 Authorization y y +14.9 Cache-Control y y +14.10 Connection y y +14.11 Content-Encoding y y +14.12 Content-Language y y +14.13 Content-Length y y +14.14 Content-Location Y n +14.15 Content-MD5 y n +14.16 Content-Range y y +14.17 Content-Type y y +14.18 Date y y +14.19 ETag y y +14.20 Expect n n +14.21 Expires y y +14.22 From - - +14.23 Host y y +14.24 If-Modified-Since y y +14.25 If-Match y y +14.26 If-None-Match y y +14.27 If-Range y y +14.28 If-Unmodified-Since y y +14.29 Last-Modified y y +14.30 Location y y +14.31 Max-Forwards n n +14.32 Pragma y y +14.33 Proxy-Authenticate y y +14.34 Proxy-Authorization y y +14.35 Range y y +14.36 Referer y y +14.37 Retry-After y y +14.38 Server y y +14.39 TE n n +14.40 Trailer n n +14.41 Transfer-Encoding y y +14.42 Upgrade Y n +14.43 User-Agent - - +14.44 Vary y y +14.45 Via n n +14.46 Warning Y n +14.47 WWW-Authenticate y y +===== ===================================== +Same for <draft-ietf-http-authentication-01.txt>: + +A 2 Basic Authentication y y +A 3.2.1 WWW-Authenticate Digest y n +A 3.2.1 qop-options auth n n +A 3.2.1 qop-options auth-int n n +A 3.2.2 Authorization Digest y n +A 3.2.2 request qop auth n n +A 3.2.2 request qop auth-int n n +A 3.2.3 Authentication-Info Digest n n +A 3.2.3 response qop auth n n +A 3.2.3 response qop auth-int n n +A 4.1 Proxy-Authenticate Basic y y +A 4.2 Proxy-Authenticate Digest y n +A 4.2 Proxy qop-options auth n n +A 4.2 Proxy qop-options auth-int n n +A 4.2 Proxy Authorization Digest y n +A 4.2 Proxy request qop auth n n +A 4.2 Proxy request qop auth-int n n +A 4.2 Proxy Authentication-Info Digest n n +A 4.2 Proxy response qop auth n n +A 4.2 Proxy response qop auth-int n n + + +NOTES: +100 Continue sent on all bodied requests, as per RFC 2068. +Accept-Encoding does not allow q-values, as per RFC 2068. diff --git a/usr.sbin/httpd/htdocs/manual/misc/custom_errordocs.html b/usr.sbin/httpd/htdocs/manual/misc/custom_errordocs.html new file mode 100644 index 00000000000..6b7b953311e --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/custom_errordocs.html @@ -0,0 +1,445 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>International Customized Server Error Messages</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Using XSSI and <SAMP>ErrorDocument</SAMP> to configure +customized international server error responses</H1> +<P> +<H2>Index</H2> +<UL> + <LI><A HREF="#intro">Introduction</A> + <LI><A HREF="#createdir">Creating an ErrorDocument directory</A> + <LI><A HREF="#docnames">Naming the individual error document files</A> + <LI><A HREF="#headfoot">The common header and footer files</A> + <LI><A HREF="#createdocs">Creating ErrorDocuments in different languages</A> + <LI><A HREF="#fallback">The fallback language</A> + <LI><A HREF="#proxy">Customizing Proxy Error Messages</A> + <LI><A HREF="#listings">HTML listing of the discussed example</A> +</UL> +<HR> +<H2><A NAME="intro">Introduction</A></H2> +This document describes an easy way to provide your apache WWW server +with a set of customized error messages which take advantage of +<A HREF="../content-negotiation.html">Content Negotiation</A> +and <A HREF="../mod/mod_include.html">eXtended Server Side Includes (XSSI)</A> +to return error messages generated by the server in the client's +native language. +</P> +<P> +By using XSSI, all +<A HREF="../mod/core.html#errordocument">customized messages</A> +can share a homogenous and consistent style and layout, and maintenance work +(changing images, changing links) is kept to a minimum because all layout +information can be kept in a single file.<BR> +Error documents can be shared across different servers, or even hosts, +because all varying information is inserted at the time the error document +is returned on behalf of a failed request. +</P> +<P> +Content Negotiation then selects the appropriate language version of a +particular error message text, honoring the language preferences passed +in the client's request. (Users usually select their favorite languages +in the preferences options menu of today's browsers). When an error +document in the client's primary language version is unavailable, the +secondary languages are tried or a default (fallback) version is used. +</P> +<P> +You have full flexibility in designing your error documents to +your personal taste (or your company's conventions). For demonstration +purposes, we present a simple generic error document scheme. +For this hypothetic server, we assume that all error messages... +<UL> +<LI>possibly are served by different virtual hosts (different host name, + different IP address, or different port) on the server machine, +<LI>show a predefined company logo in the right top of the message + (selectable by virtual host), +<LI>print the error title first, followed by an explanatory text and + (depending on the error context) help on how to resolve the error, +<LI>have some kind of standardized background image, +<LI>display an apache logo and a feedback email address at the bottom + of the error message. +</UL> +</P> + +<P> +An example of a "document not found" message for a german client might +look like this:<BR> +<IMG SRC="../images/custom_errordocs.gif" + ALT="[Needs graphics capability to display]"><BR> +All links in the document as well as links to the server's administrator +mail address, and even the name and port of the serving virtual host +are inserted in the error document at "run-time", <EM>i.e.</EM>, when the error +actually occurs. +</P> + +<H2><A NAME="createdir">Creating an ErrorDocument directory</A></H2> + +For this concept to work as easily as possible, we must take advantage +of as much server support as we can get: +<OL> + <LI>By defining the <A HREF="../mod/core.html#options">MultiViews option</A>, + we enable the language selection of the most appropriate language + alternative (content negotiation). + <LI>By setting the + <A HREF="../mod/mod_negotiation.html#languagepriority" + >LanguagePriority</A> + directive we define a set of default fallback languages in the situation + where the client's browser did not express any preference at all. + <LI>By enabling <A HREF="../mod/mod_include.html">Server Side Includes</A> + (and disallowing execution of cgi scripts for security reasons), + we allow the server to include building blocks of the error message, + and to substitute the value of certain environment variables into the + generated document (dynamic HTML) or even to conditionally include + or omit parts of the text. + <LI>The <A HREF="../mod/mod_mime.html#addhandler">AddHandler</A> and + <A HREF="../mod/mod_mime.html#addtype">AddType</A> directives are useful + for automatically XSSI-expanding all files with a <SAMP>.shtml</SAMP> + suffix to <EM>text/html</EM>. + <LI>By using the <A HREF="../mod/mod_alias.html#alias">Alias</A> directive, + we keep the error document directory outside of the document tree + because it can be regarded more as a server part than part of + the document tree. + <LI>The <A HREF="../mod/core.html#directory"><Directory></A>-Block + restricts these "special" settings to the error document directory + and avoids an impact on any of the settings for the regular document tree. + <LI>For each of the error codes to be handled (see RFC2068 for an exact + description of each error code, or look at + <CODE>src/main/http_protocol.c</CODE> + if you wish to see apache's standard messages), an + <A HREF="../mod/core.html#errordocument">ErrorDocument</A> + in the aliased <SAMP>/errordocs</SAMP> directory is defined. + Note that we only define the basename of the document here + because the MultiViews option will select the best candidate + based on the language suffixes and the client's preferences. + Any error situation with an error code <EM>not</EM> handled by a + custom document will be dealt with by the server in the standard way + (<EM>i.e.</EM>, a plain error message in english). + <LI>Finally, the <A HREF="../mod/core.html#allowoverride">AllowOverride</A> + directive tells apache that it is not necessary to look for + a .htaccess file in the /errordocs directory: a minor speed + optimization. +</OL> +The resulting <SAMP>httpd.conf</SAMP> configuration would then look +similar to this: <SMALL>(Note that you can define your own error +messages using this method for only part of the document tree, +e.g., a /~user/ subtree. In this case, the configuration could as well +be put into the .htaccess file at the root of the subtree, and +the <Directory> and </Directory> directives -but not +the contained directives- must be omitted.)</SMALL> +<PRE> + LanguagePriority en fr de + Alias /errordocs /usr/local/apache/errordocs + <Directory /usr/local/apache/errordocs> + AllowOverride none + Options MultiViews IncludesNoExec FollowSymLinks + AddType text/html .shtml + AddHandler server-parsed .shtml + </Directory> + # "400 Bad Request", + ErrorDocument 400 /errordocs/400 + # "401 Authorization Required", + ErrorDocument 401 /errordocs/401 + # "403 Forbidden", + ErrorDocument 403 /errordocs/403 + # "404 Not Found", + ErrorDocument 404 /errordocs/404 + # "500 Internal Server Error", + ErrorDocument 500 /errordocs/500 +</PRE> +The directory for the error messages (here: +<SAMP>/usr/local/apache/errordocs/</SAMP>) must then be created with the +appropriate permissions (readable and executable by the server uid or gid, +only writable for the administrator). + +<H3><A NAME="docnames">Naming the individual error document files</A></H3> + +By defining the <SAMP>MultiViews</SAMP> option, the server was told to +automatically scan the directory for matching variants (looking at language +and content type suffixes) when a requested document was not found. +In the configuration, we defined the names for the error documents to be +just their error number (without any suffix). +<P> +The names of the individual error documents are now determined like this +(I'm using 403 as an example, think of it as a placeholder for any of +the configured error documents): +<UL> + <LI>No file errordocs/403 should exist. Otherwise, it would be found and + served (with the DefaultType, usually text/plain), all negotiation + would be bypassed. + <LI>For each language for which we have an internationalized version + (note that this need not be the same set of languages for each + error code - you can get by with a single language version until + you actually <EM>have</EM> translated versions), a document + <SAMP>errordocs/403.shtml.<EM>lang</EM></SAMP> is created and + filled with the error text in that language (<A HREF="#createdocs">see + below</A>). + <LI>One fallback document called <SAMP>errordocs/403.shtml</SAMP> is + created, usually by creating a symlink to the default language + variant (<A HREF="#fallback">see below</A>). +</UL> + +<H3><A NAME="headfoot">The common header and footer files</A></H3> + +By putting as much layout information in two special "include files", +the error documents can be reduced to a bare minimum. +<P> +One of these layout files defines the HTML document header +and a configurable list of paths to the icons to be shown in the resulting +error document. These paths are exported as a set of XSSI environment +variables and are later evaluated by the "footer" special file. +The title of the current error (which is +put into the TITLE tag and an H1 header) is simply passed in from the main +error document in a variable called <CODE>title</CODE>.<BR> +<STRONG>By changing this file, the layout of all generated error +messages can be changed in a second.</STRONG> +(By exploiting the features of XSSI, you can easily define different +layouts based on the current virtual host, or even based on the +client's domain name). +<P> +The second layout file describes the footer to be displayed at the bottom +of every error message. In this example, it shows an apache logo, the current +server time, the server version string and adds a mail reference to the +site's webmaster. +<P> +For simplicity, the header file is simply called <CODE>head.shtml</CODE> +because it contains server-parsed content but no language specific +information. The footer file exists once for each language translation, +plus a symlink for the default language.<P> +<STRONG>Example:</STRONG> for English, French and German versions +(default english)<BR> +<CODE>foot.shtml.en</CODE>,<BR> +<CODE>foot.shtml.fr</CODE>,<BR> +<CODE>foot.shtml.de</CODE>,<BR> +<CODE>foot.shtml</CODE> symlink to <CODE>foot.shtml.en</CODE><P> +Both files are included into the error document by using the +directives <CODE><!--#include virtual="head" --></CODE> +and <CODE><!--#include virtual="foot" --></CODE> +respectively: the rest of the magic occurs in mod_negotiation and +in mod_include. +<P> + +See <A HREF="#listings">the listings below</A> to see an actual HTML +implementation of the discussed example. + + +<H3><A NAME="createdocs">Creating ErrorDocuments in different languages</A> +</H3> + +After all this preparation work, little remains to be said about the +actual documents. They all share a simple common structure: +<PRE> +<!--#set var="title" value="<EM>error description title</EM>" --> +<!--#include virtual="head" --> + <EM>explanatory error text</EM> +<!--#include virtual="foot" --> +</PRE> +In the <A HREF="#listings">listings section</A>, you can see an example +of a [400 Bad Request] error document. Documents as simple as that +certainly cause no problems to translate or expand. + +<H3><A NAME="fallback">The fallback language</A></H3> + +Do we need a special handling for languages other than those we have +translations for? We did set the LanguagePriority, didn't we?! +<P> +Well, the LanguagePriority directive is for the case where the client does +not express any language priority at all. But what +happens in the situation where the client wants one +of the languages we do not have, and none of those we do have? +<P> +Without doing anything, the Apache server will usually return a +[406 no acceptable variant] error, listing the choices from which the client +may select. But we're in an error message already, and important error +information might get lost when the client had to choose a language +representation first. +<P> +So, in this situation it appears to be easier to define a fallback language +(by copying or linking, <EM>e.g.</EM>, the english version to a language-less version). +Because the negotiation algorithm prefers "more specialized" variants over +"more generic" variants, these generic alternatives will only be chosen +when the normal negotiation did not succeed. +<P> +A simple shell script to do it (execute within the errordocs/ dir): +<PRE> + for f in *.shtml.en + do + ln -s $f `basename $f .en` + done +</PRE> + +<P> +</P> + +<H2><A NAME="proxy">Customizing Proxy Error Messages</A></H2> + +<P> + As of Apache-1.3, it is possible to use the <CODE>ErrorDocument</CODE> + mechanism for proxy error messages as well (previous versions always + returned fixed predefined error messages). +</P> +<P> + Most proxy errors return an error code of [500 Internal Server Error]. + To find out whether a particular error document was invoked on behalf + of a proxy error or because of some other server error, and what the reason + for the failure was, you can check the contents of the new + <CODE>ERROR_NOTES</CODE> CGI environment variable: + if invoked for a proxy error, this variable will contain the actual proxy + error message text in HTML form. +</P> +<P> + The following excerpt demonstrates how to exploit the <CODE>ERROR_NOTES</CODE> + variable within an error document: +</P> +<PRE> + <!--#if expr="\"$REDIRECT_ERROR_NOTES\" = \"\"" --> + <p> + The server encountered an unexpected condition + which prevented it from fulfilling the request. + </p> + <p> + <A HREF="mailto:<!--#echo var="SERVER_ADMIN" -->" + SUBJECT="Error message [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> for <!--#echo var="REQUEST_URI" -->"> + Please forward this error screen to <!--#echo var="SERVER_NAME" -->'s + WebMaster</A>; it includes useful debugging information about + the Request which caused the error. + <pre><!--#printenv --></pre> + </p> + <!--#else --> + <!--#echo var="REDIRECT_ERROR_NOTES" --> + <!--#endif --> +</PRE> + +<H2><A NAME="listings">HTML listing of the discussed example</A></H2> + +So, to summarize our example, here's the complete listing of the +<SAMP>400.shtml.en</SAMP> document. You will notice that it contains +almost nothing but the error text (with conditional additions). +Starting with this example, you will find it easy to add more error +documents, or to translate the error documents to different languages. +<HR><PRE> +<!--#set var="title" value="Bad Request" +--><!--#include virtual="head" --><P> + Your browser sent a request that this server could not understand: + <BLOCKQUOTE> + <STRONG><!--#echo var="REQUEST_URI" --></STRONG> + </BLOCKQUOTE> + The request could not be understood by the server due to malformed + syntax. The client should not repeat the request without + modifications. + </P> + <P> + <!--#if expr="\"$HTTP_REFERER\" != \"\"" --> + Please inform the owner of + <A HREF="<!--#echo var="HTTP_REFERER" -->">the referring page</A> about + the malformed link. + <!--#else --> + Please check your request for typing errors and retry. + <!--#endif --> + </P> +<!--#include virtual="foot" --> +</PRE><HR> + +Here is the complete <SAMP>head.shtml</SAMP> file (the funny line +breaks avoid empty lines in the document after XSSI processing). Note the +configuration section at top. That's where you configure the images and logos +as well as the apache documentation directory. Look how this file displays +two different logos depending on the content of the virtual host name +($SERVER_NAME), and that an animated apache logo is shown if the browser +appears to support it (the latter requires server configuration lines +of the form <BR><CODE>BrowserMatch "^Mozilla/[2-4]" anigif</CODE><BR> +for browser types which support animated GIFs). +<HR><PRE> +<!--#if expr="\"$SERVER_NAME\" = /.*\.mycompany\.com/" +--><!--#set var="IMG_CorpLogo" + value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif" +--><!--#set var="ALT_CorpLogo" value="Powered by Linux!" +--><!--#else +--><!--#set var="IMG_CorpLogo" + value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif" +--><!--#set var="ALT_CorpLogo" value="Powered by Linux!" +--><!--#endif +--><!--#set var="IMG_BgImage" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/BgImage.gif" +--><!--#set var="DOC_Apache" value="http://$SERVER_NAME:$SERVER_PORT/Apache/" +--><!--#if expr="$anigif" +--><!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif" +--><!--#else +--><!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif" +--><!--#endif +--><!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<HTML> + <HEAD> + <TITLE> + [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> + </TITLE> + </HEAD> + <BODY BGCOLOR="white" BACKGROUND="<!--#echo var="IMG_BgImage" -->"><UL> + <H1 ALIGN="center"> + [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> + <IMG SRC="<!--#echo var="IMG_CorpLogo" -->" + ALT="<!--#echo var="ALT_CorpLogo" -->" ALIGN=right> + </H1> + <HR><!-- ======================================================== --> + <DIV> +</PRE><HR> + and this is the <SAMP>foot.shtml.en</SAMP> file: +<HR><PRE> + + </DIV> + <HR> + <DIV ALIGN="right"><SMALL><SUP>Local Server time: + <!--#echo var="DATE_LOCAL" --> + </SUP></SMALL></DIV> + <DIV ALIGN="center"> + <A HREF="<!--#echo var="DOC_Apache" -->"> + <IMG SRC="<!--#echo var="IMG_Apache" -->" BORDER=0 ALIGN="bottom" + ALT="Powered by <!--#echo var="SERVER_SOFTWARE" -->"></A><BR> + <SMALL><SUP><!--#set var="var" + value="Powered by $SERVER_SOFTWARE -- File last modified on $LAST_MODIFIED" + --><!--#echo var="var" --></SUP></SMALL> + </DIV> + <ADDRESS>If the indicated error looks like a misconfiguration, please inform + <A HREF="mailto:<!--#echo var="SERVER_ADMIN" -->" + SUBJECT="Feedback about Error message [<!--#echo var="REDIRECT_STATUS" + -->] <!--#echo var="title" -->, req=<!--#echo var="REQUEST_URI" -->"> + <!--#echo var="SERVER_NAME" -->'s WebMaster</A>. + </ADDRESS> + </UL></BODY> +</HTML> +</PRE><HR> + + +<H3>More welcome!</H3> + +If you have tips to contribute, send mail to <A +HREF="mailto:martin@apache.org">martin@apache.org</A> + + <HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/misc/perf-hp.html b/usr.sbin/httpd/htdocs/manual/misc/perf-hp.html new file mode 100644 index 00000000000..9db0a08c9ff --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/perf-hp.html @@ -0,0 +1,124 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Running a High-Performance Web Server on HPUX</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<A NAME="initial"> </A> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Running a High-Performance Web Server for HPUX</H1> + +<PRE> +Date: Wed, 05 Nov 1997 16:59:34 -0800 +From: Rick Jones <<A HREF="mailto:raj@cup.hp.com">raj@cup.hp.com</A>> +Reply-To: raj@cup.hp.com +Organization: Network Performance +Subject: HP-UX tuning tips +</PRE> + +Here are some tuning tips for HP-UX to add to the tuning page. + +<P> + +For HP-UX 9.X: Upgrade to 10.20<BR> +For HP-UX 10.[00|01|10]: Upgrade to 10.20 + +<P> + +For HP-UX 10.20: + +<P> + +Install the latest cumulative ARPA Transport Patch. This will allow you +to configure the size of the TCP connection lookup hash table. The +default is 256 buckets and must be set to a power of two. This is +accomplished with adb against the *disc* image of the kernel. The +variable name is tcp_hash_size. + +<P> + +How to pick the value? Examine the output of +<A HREF="ftp://ftp.cup.hp.com/dist/networking/tools/connhist"> +ftp://ftp.cup.hp.com/dist/networking/tools/connhist</A> and see how many +total TCP connections exist on the system. You probably want that number +divided by the hash table size to be reasonably small, say less than 10. +Folks can look at HP's SPECweb96 disclosures for some common settings. +These can be found at <A HREF="http://www.specbench.org/"> +http://www.specbench.org/</A>. If an HP-UX system was +performing at 1000 SPECweb96 connections per second, the TIME_WAIT time +of 60 seconds would mean 60,000 TCP "connections" being tracked. + +<P> + +Folks can check their listen queue depths with +<A HREF="ftp://ftp.cup.hp.com/dist/networking/misc/listenq"> +ftp://ftp.cup.hp.com/dist/networking/misc/listenq</A>. + +<P> + +If folks are running Apache on a PA-8000 based system, they should +consider "chatr'ing" the Apache executable to have a large page size. +This would be "chatr +pi L <BINARY>." The GID of the running executable +must have MLOCK privileges. Setprivgrp(1m) should be consulted for +assigning MLOCK. The change can be validated by running Glance and +examining the memory regions of the server(s) to make sure that they +show a non-trivial fraction of the text segment being locked. + +<P> + +If folks are running Apache on MP systems, they might consider writing a +small program that uses mpctl() to bind processes to processors. A +simple pid % numcpu algorithm is probably sufficient. This might even go +into the source code. + +<P> + +If folks are concerned about the number of FIN_WAIT_2 connections, they +can use nettune to shrink the value of tcp_keepstart. However, they +should be careful there - certainly do not make it less than oh two to +four minutes. If tcp_hash_size has been set well, it is probably OK to +let the FIN_WAIT_2's take longer to timeout (perhaps even the default +two hours) - they will not on average have a big impact on performance. + +<P> + +There are other things that could go into the code base, but that might +be left for another email. Feel free to drop me a message if you or +others are interested. + +<P> + +sincerely, + +<P> + +rick jones<BR> +<A HREF="http://www.cup.hp.com/netperf/NetperfPage.html"> +http://www.cup.hp.com/netperf/NetperfPage.html</A> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY></HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/misc/perf-tuning.html b/usr.sbin/httpd/htdocs/manual/misc/perf-tuning.html new file mode 100644 index 00000000000..9ab35a0340e --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/perf-tuning.html @@ -0,0 +1,871 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> + <TITLE>Apache Performance Notes</TITLE> +</HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<H1>Apache Performance Notes</H1> + +<P>Author: Dean Gaudet + +<H3>Introduction</H3> +<P>Apache is a general webserver, which is designed to be correct first, and +fast second. Even so, it's performance is quite satisfactory. Most +sites have less than 10Mbits of outgoing bandwidth, which Apache can +fill using only a low end Pentium-based webserver. In practice sites +with more bandwidth require more than one machine to fill the bandwidth +due to other constraints (such as CGI or database transaction overhead). +For these reasons the development focus has been mostly on correctness +and configurability. + +<P>Unfortunately many folks overlook these facts and cite raw performance +numbers as if they are some indication of the quality of a web server +product. There is a bare minimum performance that is acceptable, beyond +that extra speed only caters to a much smaller segment of the market. +But in order to avoid this hurdle to the acceptance of Apache in some +markets, effort was put into Apache 1.3 to bring performance up to a +point where the difference with other high-end webservers is minimal. + +<P>Finally there are the folks who just plain want to see how fast something +can go. The author falls into this category. The rest of this document +is dedicated to these folks who want to squeeze every last bit of +performance out of Apache's current model, and want to understand why +it does some things which slow it down. + +<P>Note that this is tailored towards Apache 1.3 on Unix. Some of it applies +to Apache on NT. Apache on NT has not been tuned for performance yet, +in fact it probably performs very poorly because NT performance requires +a different programming model. + +<H3>Hardware and Operating System Issues</H3> + +<P>The single biggest hardware issue affecting webserver performance +is RAM. A webserver should never ever have to swap, swapping increases +the latency of each request beyond a point that users consider "fast +enough". This causes users to hit stop and reload, further increasing +the load. You can, and should, control the <CODE>MaxClients</CODE> +setting so that your server does not spawn so many children it starts +swapping. + +<P>Beyond that the rest is mundane: get a fast enough CPU, a fast enough +network card, and fast enough disks, where "fast enough" is something +that needs to be determined by experimentation. + +<P>Operating system choice is largely a matter of local concerns. But +a general guideline is to always apply the latest vendor TCP/IP patches. +HTTP serving completely breaks many of the assumptions built into Unix +kernels up through 1994 and even 1995. Good choices include +recent FreeBSD, and Linux. + +<H3>Run-Time Configuration Issues</H3> + +<H4>HostnameLookups</H4> +<P>Prior to Apache 1.3, <CODE>HostnameLookups</CODE> defaulted to On. +This adds latency +to every request because it requires a DNS lookup to complete before +the request is finished. In Apache 1.3 this setting defaults to Off. +However (1.3 or later), if you use any <CODE>allow from domain</CODE> or +<CODE>deny from domain</CODE> directives then you will pay for a +double reverse DNS lookup (a reverse, followed by a forward to make sure +that the reverse is not being spoofed). So for the highest performance +avoid using these directives (it's fine to use IP addresses rather than +domain names). + +<P>Note that it's possible to scope the directives, such as within +a <CODE><Location /server-status></CODE> section. In this +case the DNS lookups are only performed on requests matching the +criteria. Here's an example which disables +lookups except for .html and .cgi files: + +<BLOCKQUOTE><PRE> +HostnameLookups off +<Files ~ "\.(html|cgi)$> + HostnameLookups on +</Files> +</PRE></BLOCKQUOTE> + +But even still, if you just need DNS names +in some CGIs you could consider doing the +<CODE>gethostbyname</CODE> call in the specific CGIs that need it. + +<H4>FollowSymLinks and SymLinksIfOwnerMatch</H4> +<P>Wherever in your URL-space you do not have an +<CODE>Options FollowSymLinks</CODE>, or you do have an +<CODE>Options SymLinksIfOwnerMatch</CODE> Apache will have to +issue extra system calls to check up on symlinks. One extra call per +filename component. For example, if you had: + +<BLOCKQUOTE><PRE> +DocumentRoot /www/htdocs +<Directory /> + Options SymLinksIfOwnerMatch +</Directory> +</PRE></BLOCKQUOTE> + +and a request is made for the URI <CODE>/index.html</CODE>. +Then Apache will perform <CODE>lstat(2)</CODE> on <CODE>/www</CODE>, +<CODE>/www/htdocs</CODE>, and <CODE>/www/htdocs/index.html</CODE>. The +results of these <CODE>lstats</CODE> are never cached, +so they will occur on every single request. If you really desire the +symlinks security checking you can do something like this: + +<BLOCKQUOTE><PRE> +DocumentRoot /www/htdocs +<Directory /> + Options FollowSymLinks +</Directory> +<Directory /www/htdocs> + Options -FollowSymLinks +SymLinksIfOwnerMatch +</Directory> +</PRE></BLOCKQUOTE> + +This at least avoids the extra checks for the <CODE>DocumentRoot</CODE> +path. Note that you'll need to add similar sections if you have any +<CODE>Alias</CODE> or <CODE>RewriteRule</CODE> paths outside of your +document root. For highest performance, and no symlink protection, +set <CODE>FollowSymLinks</CODE> everywhere, and never set +<CODE>SymLinksIfOwnerMatch</CODE>. + +<H4>AllowOverride</H4> + +<P>Wherever in your URL-space you allow overrides (typically +<CODE>.htaccess</CODE> files) Apache will attempt to open +<CODE>.htaccess</CODE> for each filename component. For example, + +<BLOCKQUOTE><PRE> +DocumentRoot /www/htdocs +<Directory /> + AllowOverride all +</Directory> +</PRE></BLOCKQUOTE> + +and a request is made for the URI <CODE>/index.html</CODE>. Then +Apache will attempt to open <CODE>/.htaccess</CODE>, +<CODE>/www/.htaccess</CODE>, and <CODE>/www/htdocs/.htaccess</CODE>. +The solutions are similar to the previous case of <CODE>Options +FollowSymLinks</CODE>. For highest performance use +<CODE>AllowOverride None</CODE> everywhere in your filesystem. + +<H4>Negotiation</H4> + +<P>If at all possible, avoid content-negotiation if you're really +interested in every last ounce of performance. In practice the +benefits of negotiation outweigh the performance penalties. There's +one case where you can speed up the server. Instead of using +a wildcard such as: + +<BLOCKQUOTE><PRE> +DirectoryIndex index +</PRE></BLOCKQUOTE> + +Use a complete list of options: + +<BLOCKQUOTE><PRE> +DirectoryIndex index.cgi index.pl index.shtml index.html +</PRE></BLOCKQUOTE> + +where you list the most common choice first. + +<H4>Process Creation</H4> + +<P>Prior to Apache 1.3 the <CODE>MinSpareServers</CODE>, +<CODE>MaxSpareServers</CODE>, and <CODE>StartServers</CODE> settings +all had drastic effects on benchmark results. In particular, Apache +required a "ramp-up" period in order to reach a number of children +sufficient to serve the load being applied. After the initial +spawning of <CODE>StartServers</CODE> children, only one child per +second would be created to satisfy the <CODE>MinSpareServers</CODE> +setting. So a server being accessed by 100 simultaneous clients, +using the default <CODE>StartServers</CODE> of 5 would take on +the order 95 seconds to spawn enough children to handle the load. This +works fine in practice on real-life servers, because they aren't restarted +frequently. But does really poorly on benchmarks which might only run +for ten minutes. + +<P>The one-per-second rule was implemented in an effort to avoid +swamping the machine with the startup of new children. If the machine +is busy spawning children it can't service requests. But it has such +a drastic effect on the perceived performance of Apache that it had +to be replaced. As of Apache 1.3, +the code will relax the one-per-second rule. It +will spawn one, wait a second, then spawn two, wait a second, then spawn +four, and it will continue exponentially until it is spawning 32 children +per second. It will stop whenever it satisfies the +<CODE>MinSpareServers</CODE> setting. + +<P>This appears to be responsive enough that it's +almost unnecessary to twiddle the <CODE>MinSpareServers</CODE>, +<CODE>MaxSpareServers</CODE> and <CODE>StartServers</CODE> knobs. When +more than 4 children are spawned per second, a message will be emitted +to the <CODE>ErrorLog</CODE>. If you see a lot of these errors then +consider tuning these settings. Use the <CODE>mod_status</CODE> output +as a guide. + +<P>Related to process creation is process death induced by the +<CODE>MaxRequestsPerChild</CODE> setting. By default this is 30, which +is probably far too low unless your server is using a module such as +<CODE>mod_perl</CODE> which causes children to have bloated memory +images. If your server is serving mostly static pages then consider +raising this value to something like 10000. The code is robust enough +that this shouldn't be a problem. + +<P>When keep-alives are in use, children will be kept busy +doing nothing waiting for more requests on the already open +connection. The default <CODE>KeepAliveTimeout</CODE> of +15 seconds attempts to minimize this effect. The tradeoff +here is between network bandwidth and server resources. +In no event should you raise this above about 60 seconds, as +<A HREF="http://www.research.digital.com/wrl/techreports/abstracts/95.4.html" +>most of the benefits are lost</A>. + +<H3>Compile-Time Configuration Issues</H3> + +<H4>mod_status and ExtendedStatus On</H4> + +<P>If you include <CODE>mod_status</CODE> +and you also set <CODE>ExtendedStatus On</CODE> when building and running +Apache, then on every request Apache will perform two calls to +<CODE>gettimeofday(2)</CODE> (or <CODE>times(2)</CODE> depending +on your operating system), and (pre-1.3) several extra calls to +<CODE>time(2)</CODE>. This is all done so that the status report +contains timing indications. For highest performance, set +<CODE>ExtendedStatus off</CODE> (which is the default). + +<H4>accept Serialization - multiple sockets</H4> + +<P>This discusses a shortcoming in the Unix socket API. +Suppose your +web server uses multiple <CODE>Listen</CODE> statements to listen on +either multiple ports or multiple addresses. In order to test each +socket to see if a connection is ready Apache uses <CODE>select(2)</CODE>. +<CODE>select(2)</CODE> indicates that a socket has <EM>zero</EM> or +<EM>at least one</EM> connection waiting on it. Apache's model includes +multiple children, and all the idle ones test for new connections at the +same time. A naive implementation looks something like this +(these examples do not match the code, they're contrived for +pedagogical purposes): + +<BLOCKQUOTE><PRE> + for (;;) { + for (;;) { + fd_set accept_fds; + + FD_ZERO (&accept_fds); + for (i = first_socket; i <= last_socket; ++i) { + FD_SET (i, &accept_fds); + } + rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL); + if (rc < 1) continue; + new_connection = -1; + for (i = first_socket; i <= last_socket; ++i) { + if (FD_ISSET (i, &accept_fds)) { + new_connection = accept (i, NULL, NULL); + if (new_connection != -1) break; + } + } + if (new_connection != -1) break; + } + process the new_connection; + } +</PRE></BLOCKQUOTE> + +But this naive implementation has a serious starvation problem. Recall +that multiple children execute this loop at the same time, and so multiple +children will block at <CODE>select</CODE> when they are in between +requests. All those blocked children will awaken and return from +<CODE>select</CODE> when a single request appears on any socket +(the number of children which awaken varies depending on the operating +system and timing issues). +They will all then fall down into the loop and try to <CODE>accept</CODE> +the connection. But only one will succeed (assuming there's still only +one connection ready), the rest will be <EM>blocked</EM> in +<CODE>accept</CODE>. +This effectively locks those children into serving requests from that +one socket and no other sockets, and they'll be stuck there until enough +new requests appear on that socket to wake them all up. +This starvation problem was first documented in +<A HREF="http://bugs.apache.org/index/full/467">PR#467</A>. There +are at least two solutions. + +<P>One solution is to make the sockets non-blocking. In this case the +<CODE>accept</CODE> won't block the children, and they will be allowed +to continue immediately. But this wastes CPU time. Suppose you have +ten idle children in <CODE>select</CODE>, and one connection arrives. +Then nine of those children will wake up, try to <CODE>accept</CODE> the +connection, fail, and loop back into <CODE>select</CODE>, accomplishing +nothing. Meanwhile none of those children are servicing requests that +occurred on other sockets until they get back up to the <CODE>select</CODE> +again. Overall this solution does not seem very fruitful unless you +have as many idle CPUs (in a multiprocessor box) as you have idle children, +not a very likely situation. + +<P>Another solution, the one used by Apache, is to serialize entry into +the inner loop. The loop looks like this (differences highlighted): + +<BLOCKQUOTE><PRE> + for (;;) { + <STRONG>accept_mutex_on ();</STRONG> + for (;;) { + fd_set accept_fds; + + FD_ZERO (&accept_fds); + for (i = first_socket; i <= last_socket; ++i) { + FD_SET (i, &accept_fds); + } + rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL); + if (rc < 1) continue; + new_connection = -1; + for (i = first_socket; i <= last_socket; ++i) { + if (FD_ISSET (i, &accept_fds)) { + new_connection = accept (i, NULL, NULL); + if (new_connection != -1) break; + } + } + if (new_connection != -1) break; + } + <STRONG>accept_mutex_off ();</STRONG> + process the new_connection; + } +</PRE></BLOCKQUOTE> + +<A NAME="serialize">The functions</A> +<CODE>accept_mutex_on</CODE> and <CODE>accept_mutex_off</CODE> +implement a mutual exclusion semaphore. Only one child can have the +mutex at any time. There are several choices for implementing these +mutexes. The choice is defined in <CODE>src/conf.h</CODE> (pre-1.3) or +<CODE>src/main/conf.h</CODE> (1.3 or later). Some architectures +do not have any locking choice made, on these architectures it is unsafe +to use multiple <CODE>Listen</CODE> directives. + +<DL> +<DT><CODE>USE_FLOCK_SERIALIZED_ACCEPT</CODE> +<DD>This method uses the <CODE>flock(2)</CODE> system call to lock a +lock file (located by the <CODE>LockFile</CODE> directive). + +<DT><CODE>USE_FCNTL_SERIALIZED_ACCEPT</CODE> +<DD>This method uses the <CODE>fcntl(2)</CODE> system call to lock a +lock file (located by the <CODE>LockFile</CODE> directive). + +<DT><CODE>USE_SYSVSEM_SERIALIZED_ACCEPT</CODE> +<DD>(1.3 or later) This method uses SysV-style semaphores to implement the +mutex. Unfortunately SysV-style semaphores have some bad side-effects. +One is that it's possible Apache will die without cleaning up the semaphore +(see the <CODE>ipcs(8)</CODE> man page). The other is that the semaphore +API allows for a denial of service attack by any CGIs running under the +same uid as the webserver (<EM>i.e.</EM>, all CGIs unless you use something +like suexec or cgiwrapper). For these reasons this method is not used +on any architecture except IRIX (where the previous two are prohibitively +expensive on most IRIX boxes). + +<DT><CODE>USE_USLOCK_SERIALIZED_ACCEPT</CODE> +<DD>(1.3 or later) This method is only available on IRIX, and uses +<CODE>usconfig(2)</CODE> to create a mutex. While this method avoids +the hassles of SysV-style semaphores, it is not the default for IRIX. +This is because on single processor IRIX boxes (5.3 or 6.2) the +uslock code is two orders of magnitude slower than the SysV-semaphore +code. On multi-processor IRIX boxes the uslock code is an order of magnitude +faster than the SysV-semaphore code. Kind of a messed up situation. +So if you're using a multiprocessor IRIX box then you should rebuild your +webserver with <CODE>-DUSE_USLOCK_SERIALIZED_ACCEPT</CODE> on the +<CODE>EXTRA_CFLAGS</CODE>. + +<DT><CODE>USE_PTHREAD_SERIALIZED_ACCEPT</CODE> +<DD>(1.3 or later) This method uses POSIX mutexes and should work on +any architecture implementing the full POSIX threads specification, +however appears to only work on Solaris (2.5 or later), and even then +only in certain configurations. If you experiment with this you should +watch out for your server hanging and not responding. Static content +only servers may work just fine. +</DL> + +<P>If your system has another method of serialization which isn't in the +above list then it may be worthwhile adding code for it (and submitting +a patch back to Apache). + +<P>Another solution that has been considered but never implemented is +to partially serialize the loop -- that is, let in a certain number +of processes. This would only be of interest on multiprocessor boxes +where it's possible multiple children could run simultaneously, and the +serialization actually doesn't take advantage of the full bandwidth. +This is a possible area of future investigation, but priority remains +low because highly parallel web servers are not the norm. + +<P>Ideally you should run servers without multiple <CODE>Listen</CODE> +statements if you want the highest performance. But read on. + +<H4>accept Serialization - single socket</H4> + +<P>The above is fine and dandy for multiple socket servers, but what +about single socket servers? In theory they shouldn't experience +any of these same problems because all children can just block in +<CODE>accept(2)</CODE> until a connection arrives, and no starvation +results. In practice this hides almost the same "spinning" behaviour +discussed above in the non-blocking solution. The way that most TCP +stacks are implemented, the kernel actually wakes up all processes blocked +in <CODE>accept</CODE> when a single connection arrives. One of those +processes gets the connection and returns to user-space, the rest spin in +the kernel and go back to sleep when they discover there's no connection +for them. This spinning is hidden from the user-land code, but it's +there nonetheless. This can result in the same load-spiking wasteful +behaviour that a non-blocking solution to the multiple sockets case can. + +<P>For this reason we have found that many architectures behave more +"nicely" if we serialize even the single socket case. So this is +actually the default in almost all cases. Crude experiments under +Linux (2.0.30 on a dual Pentium pro 166 w/128Mb RAM) have shown that +the serialization of the single socket case causes less than a 3% +decrease in requests per second over unserialized single-socket. +But unserialized single-socket showed an extra 100ms latency on +each request. This latency is probably a wash on long haul lines, +and only an issue on LANs. If you want to override the single socket +serialization you can define <CODE>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</CODE> +and then single-socket servers will not serialize at all. + +<H4>Lingering Close</H4> + +<P>As discussed in +<A + HREF="ftp://ds.internic.net/internet-drafts/draft-ietf-http-connection-00.txt" +>draft-ietf-http-connection-00.txt</A> section 8, +in order for an HTTP server to <STRONG>reliably</STRONG> implement the protocol +it needs to shutdown each direction of the communication independently +(recall that a TCP connection is bi-directional, each half is independent +of the other). This fact is often overlooked by other servers, but +is correctly implemented in Apache as of 1.2. + +<P>When this feature was added to Apache it caused a flurry of +problems on various versions of Unix because of a shortsightedness. +The TCP specification does not state that the FIN_WAIT_2 state has a +timeout, but it doesn't prohibit it. On systems without the timeout, +Apache 1.2 induces many sockets stuck forever in the FIN_WAIT_2 state. +In many cases this can be avoided by simply upgrading to the latest +TCP/IP patches supplied by the vendor, in cases where the vendor has +never released patches (<EM>i.e.</EM>, SunOS4 -- although folks with a source +license can patch it themselves) we have decided to disable this feature. + +<P>There are two ways of accomplishing this. One is the +socket option <CODE>SO_LINGER</CODE>. But as fate would have it, +this has never been implemented properly in most TCP/IP stacks. Even +on those stacks with a proper implementation (<EM>i.e.</EM>, Linux 2.0.31) this +method proves to be more expensive (cputime) than the next solution. + +<P>For the most part, Apache implements this in a function called +<CODE>lingering_close</CODE> (in <CODE>http_main.c</CODE>). The +function looks roughly like this: + +<BLOCKQUOTE><PRE> + void lingering_close (int s) + { + char junk_buffer[2048]; + + /* shutdown the sending side */ + shutdown (s, 1); + + signal (SIGALRM, lingering_death); + alarm (30); + + for (;;) { + select (s for reading, 2 second timeout); + if (error) break; + if (s is ready for reading) { + read (s, junk_buffer, sizeof (junk_buffer)); + /* just toss away whatever is here */ + } + } + + close (s); + } +</PRE></BLOCKQUOTE> + +This naturally adds some expense at the end of a connection, but it +is required for a reliable implementation. As HTTP/1.1 becomes more +prevalent, and all connections are persistent, this expense will be +amortized over more requests. If you want to play with fire and +disable this feature you can define <CODE>NO_LINGCLOSE</CODE>, but +this is not recommended at all. In particular, as HTTP/1.1 pipelined +persistent connections come into use <CODE>lingering_close</CODE> +is an absolute necessity (and +<A HREF="http://www.w3.org/Protocols/HTTP/Performance/Pipeline.html"> +pipelined connections are faster</A>, so you +want to support them). + +<H4>Scoreboard File</H4> + +<P>Apache's parent and children communicate with each other through +something called the scoreboard. Ideally this should be implemented +in shared memory. For those operating systems that we either have +access to, or have been given detailed ports for, it typically is +implemented using shared memory. The rest default to using an +on-disk file. The on-disk file is not only slow, but it is unreliable +(and less featured). Peruse the <CODE>src/main/conf.h</CODE> file +for your architecture and look for either <CODE>USE_MMAP_SCOREBOARD</CODE> or +<CODE>USE_SHMGET_SCOREBOARD</CODE>. Defining one of those two (as +well as their companions <CODE>HAVE_MMAP</CODE> and <CODE>HAVE_SHMGET</CODE> +respectively) enables the supplied shared memory code. If your system has +another type of shared memory, edit the file <CODE>src/main/http_main.c</CODE> +and add the hooks necessary to use it in Apache. (Send us back a patch +too please.) + +<P>Historical note: The Linux port of Apache didn't start to use +shared memory until version 1.2 of Apache. This oversight resulted +in really poor and unreliable behaviour of earlier versions of Apache +on Linux. + +<H4><CODE>DYNAMIC_MODULE_LIMIT</CODE></H4> + +<P>If you have no intention of using dynamically loaded modules +(you probably don't if you're reading this and tuning your +server for every last ounce of performance) then you should add +<CODE>-DDYNAMIC_MODULE_LIMIT=0</CODE> when building your server. +This will save RAM that's allocated only for supporting dynamically +loaded modules. + +<H3>Appendix: Detailed Analysis of a Trace</H3> + +Here is a system call trace of Apache 1.3 running on Linux. The run-time +configuration file is essentially the default plus: + +<BLOCKQUOTE><PRE> +<Directory /> + AllowOverride none + Options FollowSymLinks +</Directory> +</PRE></BLOCKQUOTE> + +The file being requested is a static 6K file of no particular content. +Traces of non-static requests or requests with content negotiation +look wildly different (and quite ugly in some cases). First the +entire trace, then we'll examine details. (This was generated by +the <CODE>strace</CODE> program, other similar programs include +<CODE>truss</CODE>, <CODE>ktrace</CODE>, and <CODE>par</CODE>.) + +<BLOCKQUOTE><PRE> +accept(15, {sin_family=AF_INET, sin_port=htons(22283), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3 +flock(18, LOCK_UN) = 0 +sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0 +getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0 +setsockopt(3, IPPROTO_TCP1, [1], 4) = 0 +read(3, "GET /6k HTTP/1.0\r\nUser-Agent: "..., 4096) = 60 +sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0 +time(NULL) = 873959960 +gettimeofday({873959960, 404935}, NULL) = 0 +stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0 +open("/home/dgaudet/ap/apachen/htdocs/6k", O_RDONLY) = 4 +mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400ee000 +writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389 +close(4) = 0 +time(NULL) = 873959960 +write(17, "127.0.0.1 - - [10/Sep/1997:23:39"..., 71) = 71 +gettimeofday({873959960, 417742}, NULL) = 0 +times({tms_utime=5, tms_stime=0, tms_cutime=0, tms_cstime=0}) = 446747 +shutdown(3, 1 /* send */) = 0 +oldselect(4, [3], NULL, [3], {2, 0}) = 1 (in [3], left {2, 0}) +read(3, "", 2048) = 0 +close(3) = 0 +sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0 +munmap(0x400ee000, 6144) = 0 +flock(18, LOCK_EX) = 0 +</PRE></BLOCKQUOTE> + +<P>Notice the accept serialization: + +<BLOCKQUOTE><PRE> +flock(18, LOCK_UN) = 0 +... +flock(18, LOCK_EX) = 0 +</PRE></BLOCKQUOTE> + +These two calls can be removed by defining +<CODE>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</CODE> as described earlier. + +<P>Notice the <CODE>SIGUSR1</CODE> manipulation: + +<BLOCKQUOTE><PRE> +sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0 +... +sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0 +... +sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0 +</PRE></BLOCKQUOTE> + +This is caused by the implementation of graceful restarts. When the +parent receives a <CODE>SIGUSR1</CODE> it sends a <CODE>SIGUSR1</CODE> +to all of its children (and it also increments a "generation counter" +in shared memory). Any children that are idle (between connections) +will immediately die +off when they receive the signal. Any children that are in keep-alive +connections, but are in between requests will die off immediately. But +any children that have a connection and are still waiting for the first +request will not die off immediately. + +<P>To see why this is necessary, consider how a browser reacts to a closed +connection. If the connection was a keep-alive connection and the request +being serviced was not the first request then the browser will quietly +reissue the request on a new connection. It has to do this because the +server is always free to close a keep-alive connection in between requests +(<EM>i.e.</EM>, due to a timeout or because of a maximum number of requests). +But, if the connection is closed before the first response has been +received the typical browser will display a "document contains no data" +dialogue (or a broken image icon). This is done on the assumption that +the server is broken in some way (or maybe too overloaded to respond +at all). So Apache tries to avoid ever deliberately closing the connection +before it has sent a single response. This is the cause of those +<CODE>SIGUSR1</CODE> manipulations. + +<P>Note that it is theoretically possible to eliminate all three of +these calls. But in rough tests the gain proved to be almost unnoticeable. + +<P>In order to implement virtual hosts, Apache needs to know the +local socket address used to accept the connection: + +<BLOCKQUOTE><PRE> +getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0 +</PRE></BLOCKQUOTE> + +It is possible to eliminate this call in many situations (such as when +there are no virtual hosts, or when <CODE>Listen</CODE> directives are +used which do not have wildcard addresses). But no effort has yet been +made to do these optimizations. + +<P>Apache turns off the Nagle algorithm: + +<BLOCKQUOTE><PRE> +setsockopt(3, IPPROTO_TCP1, [1], 4) = 0 +</PRE></BLOCKQUOTE> + +because of problems described in +<A HREF="http://www.isi.edu/~johnh/PAPERS/Heidemann97a.html">a +paper by John Heidemann</A>. + +<P>Notice the two <CODE>time</CODE> calls: + +<BLOCKQUOTE><PRE> +time(NULL) = 873959960 +... +time(NULL) = 873959960 +</PRE></BLOCKQUOTE> + +One of these occurs at the beginning of the request, and the other occurs +as a result of writing the log. At least one of these is required to +properly implement the HTTP protocol. The second occurs because the +Common Log Format dictates that the log record include a timestamp of the +end of the request. A custom logging module could eliminate one of the +calls. Or you can use a method which moves the time into shared memory, +see the <A HREF="#patches">patches section below</A>. + +<P>As described earlier, <CODE>ExtendedStatus On</CODE> causes two +<CODE>gettimeofday</CODE> calls and a call to <CODE>times</CODE>: + +<BLOCKQUOTE><PRE> +gettimeofday({873959960, 404935}, NULL) = 0 +... +gettimeofday({873959960, 417742}, NULL) = 0 +times({tms_utime=5, tms_stime=0, tms_cutime=0, tms_cstime=0}) = 446747 +</PRE></BLOCKQUOTE> + +These can be removed by setting <CODE>ExtendedStatus Off</CODE> (which +is the default). + +<P>It might seem odd to call <CODE>stat</CODE>: + +<BLOCKQUOTE><PRE> +stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0 +</PRE></BLOCKQUOTE> + +This is part of the algorithm which calculates the +<CODE>PATH_INFO</CODE> for use by CGIs. In fact if the request had been +for the URI <CODE>/cgi-bin/printenv/foobar</CODE> then there would be +two calls to <CODE>stat</CODE>. The first for +<CODE>/home/dgaudet/ap/apachen/cgi-bin/printenv/foobar</CODE> +which does not exist, and the second for +<CODE>/home/dgaudet/ap/apachen/cgi-bin/printenv</CODE>, which does exist. +Regardless, at least one <CODE>stat</CODE> call is necessary when +serving static files because the file size and modification times are +used to generate HTTP headers (such as <CODE>Content-Length</CODE>, +<CODE>Last-Modified</CODE>) and implement protocol features (such +as <CODE>If-Modified-Since</CODE>). A somewhat more clever server +could avoid the <CODE>stat</CODE> when serving non-static files, +however doing so in Apache is very difficult given the modular structure. + +<P>All static files are served using <CODE>mmap</CODE>: + +<BLOCKQUOTE><PRE> +mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400ee000 +... +munmap(0x400ee000, 6144) = 0 +</PRE></BLOCKQUOTE> + +On some architectures it's slower to <CODE>mmap</CODE> small +files than it is to simply <CODE>read</CODE> them. The define +<CODE>MMAP_THRESHOLD</CODE> can be set to the minimum +size required before using <CODE>mmap</CODE>. By default +it's set to 0 (except on SunOS4 where experimentation has +shown 8192 to be a better value). Using a tool such as <A +HREF="http://www.bitmover.com/lmbench/">lmbench</A> you +can determine the optimal setting for your environment. + +<P>You may also wish to experiment with <CODE>MMAP_SEGMENT_SIZE</CODE> +(default 32768) which determines the maximum number of bytes that +will be written at a time from mmap()d files. Apache only resets the +client's <CODE>Timeout</CODE> in between write()s. So setting this +large may lock out low bandwidth clients unless you also increase the +<CODE>Timeout</CODE>. + +<P>It may even be the case that <CODE>mmap</CODE> isn't +used on your architecture, if so then defining <CODE>USE_MMAP_FILES</CODE> +and <CODE>HAVE_MMAP</CODE> might work (if it works then report back to us). + +<P>Apache does its best to avoid copying bytes around in memory. The +first write of any request typically is turned into a <CODE>writev</CODE> +which combines both the headers and the first hunk of data: + +<BLOCKQUOTE><PRE> +writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389 +</PRE></BLOCKQUOTE> + +When doing HTTP/1.1 chunked encoding Apache will generate up to four +element <CODE>writev</CODE>s. The goal is to push the byte copying +into the kernel, where it typically has to happen anyhow (to assemble +network packets). On testing, various Unixes (BSDI 2.x, Solaris 2.5, +Linux 2.0.31+) properly combine the elements into network packets. +Pre-2.0.31 Linux will not combine, and will create a packet for +each element, so upgrading is a good idea. Defining <CODE>NO_WRITEV</CODE> +will disable this combining, but result in very poor chunked encoding +performance. + +<P>The log write: + +<BLOCKQUOTE><PRE> +write(17, "127.0.0.1 - - [10/Sep/1997:23:39"..., 71) = 71 +</PRE></BLOCKQUOTE> + +can be deferred by defining <CODE>BUFFERED_LOGS</CODE>. In this case +up to <CODE>PIPE_BUF</CODE> bytes (a POSIX defined constant) of log entries +are buffered before writing. At no time does it split a log entry +across a <CODE>PIPE_BUF</CODE> boundary because those writes may not +be atomic. (<EM>i.e.</EM>, entries from multiple children could become mixed together). +The code does it best to flush this buffer when a child dies. + +<P>The lingering close code causes four system calls: + +<BLOCKQUOTE><PRE> +shutdown(3, 1 /* send */) = 0 +oldselect(4, [3], NULL, [3], {2, 0}) = 1 (in [3], left {2, 0}) +read(3, "", 2048) = 0 +close(3) = 0 +</PRE></BLOCKQUOTE> + +which were described earlier. + +<P>Let's apply some of these optimizations: +<CODE>-DSINGLE_LISTEN_UNSERIALIZED_ACCEPT -DBUFFERED_LOGS</CODE> and +<CODE>ExtendedStatus Off</CODE>. Here's the final trace: + +<BLOCKQUOTE><PRE> +accept(15, {sin_family=AF_INET, sin_port=htons(22286), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3 +sigaction(SIGUSR1, {SIG_IGN}, {0x8058c98, [], SA_INTERRUPT}) = 0 +getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0 +setsockopt(3, IPPROTO_TCP1, [1], 4) = 0 +read(3, "GET /6k HTTP/1.0\r\nUser-Agent: "..., 4096) = 60 +sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0 +time(NULL) = 873961916 +stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0 +open("/home/dgaudet/ap/apachen/htdocs/6k", O_RDONLY) = 4 +mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400e3000 +writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389 +close(4) = 0 +time(NULL) = 873961916 +shutdown(3, 1 /* send */) = 0 +oldselect(4, [3], NULL, [3], {2, 0}) = 1 (in [3], left {2, 0}) +read(3, "", 2048) = 0 +close(3) = 0 +sigaction(SIGUSR1, {0x8058c98, [], SA_INTERRUPT}, {SIG_IGN}) = 0 +munmap(0x400e3000, 6144) = 0 +</PRE></BLOCKQUOTE> + +That's 19 system calls, of which 4 remain relatively easy to remove, +but don't seem worth the effort. + +<H3><A NAME="patches">Appendix: Patches Available</A></H3> + +There are +<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/"> +several performance patches available for 1.3.</A> But they may +be slightly out of date by the time Apache 1.3.0 has been released, +it shouldn't be difficult for someone with a little C knowledge to +update them. In particular: + +<UL> +<LI>A +<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/shared_time.patch" +>patch</A> to remove all <CODE>time(2)</CODE> system calls. +<LI>A +<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/mod_include_speedups.patch" +>patch</A> to remove various system calls from <CODE>mod_include</CODE>, +these calls are used by few sites but required for backwards compatibility. +<LI>A +<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/top_fuel.patch" +>patch</A> which integrates the above two plus a few other speedups at the +cost of removing some functionality. +</UL> + +<H3>Appendix: The Pre-Forking Model</H3> + +<P>Apache (on Unix) is a <EM>pre-forking</EM> model server. The +<EM>parent</EM> process is responsible only for forking <EM>child</EM> +processes, it does not serve any requests or service any network +sockets. The child processes actually process connections, they serve +multiple connections (one at a time) before dying. +The parent spawns new or kills off old +children in response to changes in the load on the server (it does so +by monitoring a scoreboard which the children keep up to date). + +<P>This model for servers offers a robustness that other models do +not. In particular, the parent code is very simple, and with a high +degree of confidence the parent will continue to do its job without +error. The children are complex, and when you add in third party +code via modules, you risk segmentation faults and other forms of +corruption. Even should such a thing happen, it only affects one +connection and the server continues serving requests. The parent +quickly replaces the dead child. + +<P>Pre-forking is also very portable across dialects of Unix. +Historically this has been an important goal for Apache, and it continues +to remain so. + +<P>The pre-forking model comes under criticism for various +performance aspects. Of particular concern are the overhead +of forking a process, the overhead of context switches between +processes, and the memory overhead of having multiple processes. +Furthermore it does not offer as many opportunities for data-caching +between requests (such as a pool of <CODE>mmapped</CODE> files). +Various other models exist and extensive analysis can be found in the +<A HREF="http://www.cs.wustl.edu/~jxh/research/research.html"> papers +of the JAWS project</A>. In practice all of these costs vary drastically +depending on the operating system. + +<P>Apache's core code is already multithread aware, and Apache version +1.3 is multithreaded on NT. There have been at least two other experimental +implementations of threaded Apache, one using the 1.3 code base on DCE, +and one using a custom user-level threads package and the 1.0 code base, +neither are available publically. There is also an experimental port of +Apache 1.3 to <A HREF="http://www.mozilla.org/docs/refList/refNSPR/"> +Netscape's Portable Run Time</A>, which +<A HREF="http://www.arctic.org/~dgaudet/apache/2.0/">is available</A> +(but you're encouraged to join the +<A HREF="http://dev.apache.org/mailing-lists">new-httpd mailing list</A> +if you intend to use it). +Part of our redesign for version 2.0 +of Apache will include abstractions of the server model so that we +can continue to support the pre-forking model, and also support various +threaded models. + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/directive-dict.html b/usr.sbin/httpd/htdocs/manual/mod/directive-dict.html new file mode 100644 index 00000000000..831cf838fe3 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/directive-dict.html @@ -0,0 +1,276 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Definitions of terms used to describe Apache directives + </TITLE> + </HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> + <BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" + > +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + + <H1 ALIGN="CENTER">Terms Used to Describe Apache Directives</H1> + + <P> + Each Apache configuration directive is described using a common format + that looks like this: + </P> + <DL> + <DD><A + HREF="#Syntax" + REL="Help" + ><STRONG>Syntax:</STRONG></A> <EM>directive-name</EM> <EM>some args</EM> + <BR> + <A + HREF="#Default" + REL="Help" + ><STRONG>Default:</STRONG></A> + <SAMP><EM>directive-name default-value</EM></SAMP> + <BR> + <A + HREF="#Context" + REL="Help" + ><STRONG>Context:</STRONG></A> <EM>context-list</EM> + <BR> + <A + HREF="#Override" + REL="Help" + ><STRONG>Override:</STRONG></A> <EM>override</EM> + <BR> + <A + HREF="#Status" + REL="Help" + ><STRONG>Status:</STRONG></A> <EM>status</EM> + <BR> + <A + HREF="#Module" + REL="Help" + ><STRONG>Module:</STRONG></A> <EM>module-name</EM> + <BR> + <A + HREF="#Compatibility" + REL="Help" + ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM> + </DD> + </DL> + <P> + Each of the directive's attributes, complete with possible values + where possible, are described in this document. + </P> + + <H2>Directive Terms</H2> + <UL> + <LI><A HREF="#Syntax">Syntax</A> + </LI> + <LI><A HREF="#Default">Default</A> + </LI> + <LI><A HREF="#Context">Context</A> + </LI> + <LI><A HREF="#Override">Override</A> + </LI> + <LI><A HREF="#Status">Status</A> + </LI> + <LI><A HREF="#Module">Module</A> + </LI> + <LI><A HREF="#Compatibility">Compatibility</A> + </LI> + </UL> + + <HR> + <H2><A NAME="Syntax">Syntax</A></H2> + <P> + This indicates the format of the directive as it would appear in a + configuration file. This syntax is extremely directive-specific, so + refer to the text of the directive's description for details. + </P> + + <HR> + <H2><A NAME="Default">Default</A></H2> + <P> + If the directive has a default value (<EM>i.e.</EM>, if you omit it + from your configuration entirely, the Apache Web server will behave as + though you set it to a particular value), it is described here. If + there is no default value, this section should say + "<EM>None</EM>". + </P> + + <HR> + <H2><A NAME="Context">Context</A></H2> + <P> + This indicates where in the server's configuration files the directive + is legal. It's a comma-separated list of one or more of the following + values: + </P> + <DL> + <DT><STRONG>server config</STRONG> + </DT> + <DD>This means that the directive may be used in the server + configuration files (<EM>e.g.</EM>, <SAMP>httpd.conf</SAMP>, + <SAMP>srm.conf</SAMP>, and <SAMP>access.conf</SAMP>), but + <STRONG>not</STRONG> within any <SAMP><VirtualHost></SAMP> or + <Directory> containers. It is not allowed in + <SAMP>.htaccess</SAMP> files at all. + <P> + </P> + </DD> + <DT><STRONG>virtual host</STRONG> + </DT> + <DD>This context means that the directive may appear inside + <SAMP><VirtualHost></SAMP> containers in the server + configuration files. + <P> + </P> + </DD> + <DT><STRONG>directory</STRONG> + </DT> + <DD>A directive marked as being valid in this context may be used + inside <SAMP><Directory></SAMP> containers in the server + configuration files. + <P> + </P> + </DD> + <DT><STRONG>.htaccess</STRONG> + </DT> + <DD>If a directive is valid in this context, it means that it can + appear inside <EM>per</EM>-directory <SAMP>.htaccess</SAMP> files. + It may not be processed, though depending upon the + <A + HREF="#Override" + REL="Help" + >overrides</A> + currently active. + <P> + </P> + </DD> + </DL> + <P> + The directive is <EM>only</EM> allowed within the designated context; + if you try to use it elsewhere, you'll get a configuration error that + will either prevent the server from handling requests in that context + correctly, or will keep the server from operating at all -- + <EM>i.e.</EM>, the server won't even start. + </P> + <P> + The valid locations for the directive are actually the result of a + Boolean OR of all of the listed contexts. In other words, a directive + that is marked as being valid in "<SAMP>server config, + .htaccess</SAMP>" can be used in the <SAMP>httpd.conf</SAMP> file + and in <SAMP>.htaccess</SAMP> files, but not within any + <Directory> or <VirtualHost> containers. + </P> + + <HR> + <H2><A NAME="Override">Override</A></H2> + <P> + This directive attribute indicates which configuration override must + be active in order for the directive to be processed when it appears + in a <SAMP>.htaccess</SAMP> file. If the directive's + <A + HREF="#Context" + REL="Help" + >context</A> + doesn't permit it to appear in <SAMP>.htaccess</SAMP> files, this + attribute should say "<EM>Not applicable</EM>". + </P> + <P> + Overrides are activated by the + <A + HREF="core.html#allowoverride" + REL="Help" + ><SAMP>AllowOverride</SAMP></A> + directive, and apply to a particular scope (such as a directory) and + all descendants, unless further modified by other + <SAMP>AllowOverride</SAMP> directives at lower levels. The + documentation for that directive also lists the possible override + names available. + </P> + + <HR> + <H2><A NAME="Status">Status</A></H2> + <P> + This indicates how tightly bound into the Apache Web server the + directive is; in other words, you may need to recompile the server + with an enhanced set of modules in order to gain access to the + directive and its functionality. Possible values for this attribute + are: + </P> + <DL> + <DT><STRONG>Core</STRONG> + </DT> + <DD>If a directive is listed as having "Core" status, that + means it is part of the innermost portions of the Apache Web server, + and is always available. + <P> + </P> + </DD> + <DT><STRONG>Base</STRONG> + </DT> + <DD>A directive labeled as having "Base" status is + supported by one of the standard Apache modules which is compiled + into the server by default, and is therefore normally available + unless you've taken steps to remove the module from your configuration. + <P> + </P> + </DD> + <DT><STRONG>Extension</STRONG> + </DT> + <DD>A directive with "Extension" status is provided by one + of the modules included with the Apache server kit, but the module + isn't normally compiled into the server. To enable the directive + and its functionality, you will need to change the server build + configuration files and re-compile Apache. + <P> + </P> + </DD> + <DT><STRONG>Experimental</STRONG> + </DT> + <DD>"Experimental" status indicates that the directive is + available as part of the Apache kit, but you're on your own if you + try to use it. The directive is being documented for completeness, + and is not necessarily supported. The module which provides the + directive may or may not be compiled in by default; check the top of + the page which describes the directive and its module to see if it + remarks on the availability. + <P> + </P> + </DD> + </DL> + + <HR> + <H2><A NAME="Module">Module</A></H2> + <P> + This quite simply lists the name of the source module which defines + the directive. + </P> + + <HR> + <H2><A NAME="Compatibility">Compatibility</A></H2> + <P> + If the directive wasn't part of the original Apache version 1 + distribution, the version in which it was introduced should be listed + here. If the directive has the same name as one from the NCSA HTTPd + server, any inconsistencies in behaviour between the two should also + be mentioned. Otherwise, this attribute should say "<EM>No + compatibility issues.</EM>" + </P> +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + + </BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_autoindex.html b/usr.sbin/httpd/htdocs/manual/mod/mod_autoindex.html new file mode 100644 index 00000000000..aacc963d3af --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_autoindex.html @@ -0,0 +1,648 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_autoindex</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_autoindex</H1> + +This module is contained in the <CODE>mod_autoindex.c</CODE> file, and +is compiled in by default. It provides for automatic directory indexing. + +<H2>Summary</H2> +The index of a directory can come from one of two sources: +<UL> +<LI>A file written by the user, typically called <CODE>index.html</CODE>. +The <A HREF="mod_dir.html#directoryindex">DirectoryIndex</A> directive sets +the name of this file. +This is controlled by <A HREF="mod_dir.html"><CODE>mod_dir</CODE></A>. +<LI>Otherwise, a listing generated by the server. The other directives +control the format of this listing. The <A HREF="#addicon">AddIcon</A>, +<A HREF="#addiconbyencoding">AddIconByEncoding</A> and +<A HREF="#addiconbytype">AddIconByType</A> are used to set a list of +icons to display for various file types; for each file listed, the +first icon listed that matches the file is displayed. These +are controlled by <CODE>mod_autoindex</CODE>. +</UL> +The two functions are separated so that you can completely remove +(or replace) automatic index generation should you want to. +<P> +If +<A + HREF="#fancyindexing" +><SAMP>FancyIndexing</SAMP></A> +is enabled, or the <SAMP>FancyIndexing</SAMP> keyword is present on the +<A + HREF="#indexoptions" +><SAMP>IndexOptions</SAMP></A> +directive, the column headers are links that control the +order of the display. If you select a header link, the +listing will be regenerated, sorted by the values in that +column. Selecting the same header repeatedly toggles +between ascending and descending order. +</P> +<P> +Note that when the display is sorted by "Size", +it's the <EM>actual</EM> size of the files that's used, +not the displayed value - so a 1010-byte file will +always be displayed before a 1011-byte file (if in ascending +order) even though they both are shown as "1K". +</P> + + +<H2>Directives</H2> + +<MENU> +<LI><A HREF="#addalt">AddAlt</A> +<LI><A HREF="#addaltbyencoding">AddAltByEncoding</A> +<LI><A HREF="#addaltbytype">AddAltByType</A> +<LI><A HREF="#adddescription">AddDescription</A> +<LI><A HREF="#addicon">AddIcon</A> +<LI><A HREF="#addiconbyencoding">AddIconByEncoding</A> +<LI><A HREF="#addiconbytype">AddIconByType</A> +<LI><A HREF="#defaulticon">DefaultIcon</A> +<LI><A HREF="#fancyindexing">FancyIndexing</A> +<LI><A HREF="#headername">HeaderName</A> +<LI><A HREF="#indexignore">IndexIgnore</A> +<LI><A HREF="#indexoptions">IndexOptions</A> +<LI><A HREF="#readmename">ReadmeName</A> +</MENU> +<HR> + +<H2><A NAME="addalt">AddAlt</A></H2> +<!--%plaintext <?INDEX {\tt AddAlt} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddAlt <EM>string file file...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +This sets the alternate text to display for a file, instead of an icon, for +<A HREF="#fancyindexing">FancyIndexing</A>. <EM>File</EM> is a file +extension, partial filename, wild-card expression or full filename for files +to describe. <EM>String</EM> is enclosed in double quotes +(<CODE>"</CODE>). This alternate text is displayed if the client is +image-incapable or has image loading disabled. + +<HR> +<H2><A NAME="addaltbyencoding">AddAltByEncoding</A></H2> +<!--%plaintext <?INDEX {\tt AddAltByEncoding} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddAltByEncoding <EM>string MIME-encoding + MIME-encoding...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +This sets the alternate text to display for a file, instead of an icon, for +<A HREF="#fancyindexing">FancyIndexing</A>. <EM>MIME-encoding</EM> is a +valid content-encoding, such as <SAMP>x-compress</SAMP>. +<EM>String</EM> is enclosed in double quotes +(<CODE>"</CODE>). This alternate text is displayed if the client is +image-incapable or has image loading disabled. + +<HR> +<H2><A NAME="addaltbytype">AddAltByType</A></H2> +<!--%plaintext <?INDEX {\tt AddAltByType} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddAltByType <EM>string MIME-type MIME-type + ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +This sets the alternate text to display for a file, instead of an icon, for +<A HREF="#fancyindexing">FancyIndexing</A>. <EM>MIME-type</EM> is a +valid content-type, such as <SAMP>text/html</SAMP>. +<EM>String</EM> is enclosed in double quotes +(<CODE>"</CODE>). This alternate text is displayed if the client is +image-incapable or has image loading disabled. + +<HR> + +<H2><A NAME="adddescription">AddDescription</A></H2> +<!--%plaintext <?INDEX {\tt AddDescription} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddDescription <EM>string file file...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +This sets the description to display for a file, for +<A HREF="#fancyindexing">FancyIndexing</A>. <EM>File</EM> is a file +extension, partial filename, wild-card expression or full filename for files +to describe. <EM>String</EM> is enclosed in double quotes +(<CODE>"</CODE>). Example: +<BLOCKQUOTE><CODE>AddDescription "The planet Mars" /web/pics/mars.gif +</CODE></BLOCKQUOTE><P><HR> + +<H2><A NAME="addicon">AddIcon</A></H2> +<!--%plaintext <?INDEX {\tt AddIcon} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddIcon <EM>icon name name ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +This sets the icon to display next to a file ending in <EM>name</EM> for +<A HREF="#fancyindexing">FancyIndexing</A>. <EM>Icon</EM> is either a +(%-escaped) relative URL to the icon, or of the format +(<EM>alttext</EM>,<EM>url</EM>) where <EM>alttext</EM> is the text tag given +for an icon for non-graphical browsers.<P> + +<EM>Name</EM> is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for +blank lines (to format the list correctly), a file extension, a wildcard +expression, a partial filename or a complete filename. Examples: +<BLOCKQUOTE><CODE> +AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm <BR> +AddIcon /icons/dir.xbm ^^DIRECTORY^^ <BR> +AddIcon /icons/backup.xbm *~ +</CODE></BLOCKQUOTE> +<A HREF="#addiconbytype">AddIconByType</A> should be used in preference to +AddIcon, when possible.<P><HR> + +<H2><A NAME="addiconbyencoding">AddIconByEncoding</A></H2> +<!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddIconByEncoding <EM>icon MIME-encoding + MIME-encoding ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +This sets the icon to display next to files with +<EM>MIME-encoding</EM> for <A HREF="#fancyindexing">FancyIndexing</A>. +<EM>Icon</EM> is either a (%-escaped) relative URL to the icon, or of the +format (<EM>alttext</EM>,<EM>url</EM>) where <EM>alttext</EM> is the text tag +given for an icon for non-graphical browsers.<P> + +<EM>Mime-encoding</EM> is a wildcard expression matching required the +content-encoding. Examples: +<BLOCKQUOTE><CODE> +AddIconByEncoding /icons/compress.xbm x-compress +</CODE></BLOCKQUOTE><P><HR> + +<H2><A NAME="addiconbytype">AddIconByType</A></H2> +<!--%plaintext <?INDEX {\tt AddIconByType} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddIconByType <EM>icon MIME-type MIME-type + ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +This sets the icon to display next to files of type <EM>MIME-type</EM> for +<A HREF="#fancyindexing">FancyIndexing</A>. <EM>Icon</EM> is either a +(%-escaped) relative URL to the icon, or of the format +(<EM>alttext</EM>,<EM>url</EM>) where <EM>alttext</EM> is the text tag given +for an icon for non-graphical browsers.<P> +<EM>Mime-type</EM> is a wildcard expression matching required the mime types. +Examples: +<BLOCKQUOTE><CODE> +AddIconByType (IMG,/icons/image.xbm) image/* +</CODE></BLOCKQUOTE><P><HR> + +<H2><A NAME="defaulticon">DefaultIcon</A></H2> +<!--%plaintext <?INDEX {\tt DefaultIcon} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> DefaultIcon <EM>url</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +The DefaultIcon directive sets the icon to display for files when no +specific icon is known, for <A HREF="#fancyindexing">FancyIndexing</A>. +<EM>Url</EM> is a (%-escaped) relative URL to the icon. Examples: +<BLOCKQUOTE><CODE> +DefaultIcon /icon/unknown.xbm +</CODE></BLOCKQUOTE><P><HR> + +<H2><A NAME="fancyindexing">FancyIndexing</A></H2> +<!--%plaintext <?INDEX {\tt FancyIndexing} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> FancyIndexing <EM>boolean</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex +<P> +The FancyIndexing directive sets the FancyIndexing option for a directory. +<EM>Boolean</EM> can be <CODE>on</CODE> or <CODE>off</CODE>. The +<A HREF="#indexoptions">IndexOptions</A> directive should be used in +preference. +</P> +<BLOCKQUOTE> + <STRONG>Note that in versions of Apache prior to 1.3.2, the + <SAMP>FancyIndexing</SAMP> and + <SAMP>IndexOptions</SAMP> directives will override each other. You + should use <SAMP>IndexOptions FancyIndexing</SAMP> in preference + to the standalone <SAMP>FancyIndexing</SAMP> directive. + As of Apache 1.3.2, a standalone <SAMP>FancyIndexing</SAMP> directive + is combined with any <SAMP>IndexOptions</SAMP> directive already + specified for the current scope.</STRONG> +</BLOCKQUOTE> +<HR> + +<H2><A NAME="headername">HeaderName</A></H2> +<!--%plaintext <?INDEX {\tt HeaderName} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> HeaderName <EM>filename</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +The HeaderName directive sets the name of the file that will be inserted +at the top of the index listing. <EM>Filename</EM> is the name of the file +to include, and is taken to be relative to the directory being indexed. +The server first attempts to include <EM>filename</EM><CODE>.html</CODE> +as an HTML document, otherwise it will include <EM>filename</EM> as plain +text. Example: +<BLOCKQUOTE><CODE>HeaderName HEADER</CODE></BLOCKQUOTE> +when indexing the directory <CODE>/web</CODE>, the server will first look for +the HTML file <CODE>/web/HEADER.html</CODE> and include it if found, otherwise +it will include the plain text file <CODE>/web/HEADER</CODE>, if it exists. + +<P>See also <A HREF="#readmename">ReadmeName</A>.<P><HR> + +<H2><A NAME="indexignore">IndexIgnore</A></H2> +<!--%plaintext <?INDEX {\tt IndexIgnore} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> IndexIgnore <EM>file file ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +The IndexIgnore directive adds to the list of files to hide when listing +a directory. <EM>File</EM> is a file extension, partial filename, +wildcard expression or full filename for files to ignore. Multiple +IndexIgnore directives add to the list, rather than the replacing the list +of ignored files. By default, the list contains `<CODE>.</CODE>'. Example: +<BLOCKQUOTE><CODE> +IndexIgnore README .htaccess *~ +</CODE></BLOCKQUOTE><P><HR> + +<H2><A NAME="indexoptions">IndexOptions</A></H2> +<!--%plaintext <?INDEX {\tt IndexOptions} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> IndexOptions <EM>option option ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +The IndexOptions directive specifies the behavior of the directory indexing. +<EM>Option</EM> can be one of +<DL> +<DT>FancyIndexing +<DD><!--%plaintext <?INDEX {\tt FancyIndexing} index option> --> +This turns on fancy indexing of directories. +<BLOCKQUOTE> + <STRONG>Note that in versions of Apache prior to 1.3.2, the + <SAMP>FancyIndexing</SAMP> and + <SAMP>IndexOptions</SAMP> directives will override each other. You + should use <SAMP>IndexOptions FancyIndexing</SAMP> in preference + to the standalone <SAMP>FancyIndexing</SAMP> directive. + As of Apache 1.3.2, a standalone <SAMP>FancyIndexing</SAMP> directive + is combined with any <SAMP>IndexOptions</SAMP> directive already + specified for the current scope.</STRONG> +</BLOCKQUOTE> +<DT>IconHeight[=pixels] (<EM>Apache 1.3 and later</EM>) +<DD> +<!--%plaintext <?INDEX {\tt IconHeight} index option> --> +Presence of this option, when used with IconWidth, will cause the server +to include <SAMP>HEIGHT</SAMP> and <SAMP>WIDTH</SAMP> attributes in the +<SAMP>IMG</SAMP> tag for the file icon. This allows browser to +precalculate the page layout without having to wait until all the +images have been loaded. If no value is given for the option, it +defaults to the standard height of the icons supplied with the Apache +software. +<DT>IconsAreLinks +<DD> +<!--%plaintext <?INDEX {\tt IconsAreLinks} index option> --> +This makes the icons part of the anchor for the filename, for +fancy indexing. +<DT>IconWidth[=pixels] (<EM>Apache 1.3 and later</EM>) +<DD> +<!--%plaintext <?INDEX {\tt IconWidth} index option> --> +Presence of this option, when used with IconHeight, will cause the server +to include <SAMP>HEIGHT</SAMP> and <SAMP>WIDTH</SAMP> attributes in the +<SAMP>IMG</SAMP> tag for the file icon. This allows browser to +precalculate the page layout without having to wait until all the +images have been loaded. If no value is given for the option, it +defaults to the standard width of the icons supplied with the Apache +software. +<DT>NameLength=[<EM>n</EM> | *] (<EM>Apache 1.3.2 and later</EM>) +<DD> +The NameLength keyword allows you to specify the width of the +filename column in bytes. If the keyword value is '<SAMP>*</SAMP>', +then the column is automatically sized to the length of the longest +filename in the display. +<DT>ScanHTMLTitles +<DD><!--%plaintext <?INDEX {\tt ScanHTMLTitles} index option> --> +This enables the extraction of the title from HTML documents for fancy +indexing. If the file does not have a description given by +<A HREF="#adddescription">AddDescription</A> then httpd will read the +document for the value of the TITLE tag. This is CPU and disk intensive. +<DT>SuppressColumnSorting +<DD> +<!--%plaintext <?INDEX {\tt SuppressColumnSorting} index option> --> +If specified, Apache will not make the column headings in a FancyIndexed +directory listing into links for sorting. The default behaviour is +for them to be links; selecting the column heading will sort the directory +listing by the values in that column. +<STRONG>Only available in Apache 1.3 and later.</STRONG> +<DT>SuppressDescription +<DD> +<!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> +This will suppress the file description in fancy indexing listings. +<DT>SuppressHTMLPreamble +<DD> +<!--%plaintext <?INDEX {\tt SuppressHTMLPreamble} index option> --> +If the directory actually contains a file specified by the +<A + HREF="#headername" +>HeaderName</A> +directive, the module usually includes the contents of the file +after a standard HTML preamble (<HTML>, <HEAD>, <EM>et +cetera</EM>). The SuppressHTMLPreamble option disables this behaviour, +causing the module to start the display with the header file contents. +The header file must contain appropriate HTML instructions in this case. +If there is no header file, the preamble is generated as usual. +<DT>SuppressLastModified +<DD> +<!--%plaintext <?INDEX {\tt SuppressLastModified} index option> --> +This will suppress the display of the last modification date, in fancy +indexing listings. +<DT>SuppressSize +<DD> +<!--%plaintext <?INDEX {\tt SuppressSize} index option> --> +This will suppress the file size in fancy indexing listings. +</DL> +This default is that no options are enabled. If multiple IndexOptions +could apply to a directory, then the most specific one is taken complete; +the options are not merged. For example: +<BLOCKQUOTE><CODE> +<Directory /web/docs> <BR> +IndexOptions FancyIndexing <BR> +</Directory><BR> +<Directory /web/docs/spec> <BR> +IndexOptions ScanHTMLTitles <BR> +</Directory> +</CODE></BLOCKQUOTE> +then only <CODE>ScanHTMLTitles</CODE> will be set for the /web/docs/spec +directory.<P><HR> + +<H2><A NAME="readmename">ReadmeName</A></H2> +<!--%plaintext <?INDEX {\tt ReadmeName} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> ReadmeName <EM>filename</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex<P> + +The ReadmeName directive sets the name of the file that will be appended +to the end of the index listing. <EM>Filename</EM> is the name of the file +to include, and is taken to be relative to the directory being indexed. +The server first attempts to include <EM>filename</EM><CODE>.html</CODE> +as an HTML document, otherwise it will include <EM>filename</EM> as plain +text. Example: +<BLOCKQUOTE><CODE>ReadmeName README</CODE></BLOCKQUOTE> +when indexing the directory <CODE>/web</CODE>, the server will first look for +the HTML file <CODE>/web/README.html</CODE> and include it if found, otherwise +it will include the plain text file <CODE>/web/README</CODE>, if it exists. + +<P>See also <A HREF="#headername">HeaderName</A>.<P> + + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_dll.html b/usr.sbin/httpd/htdocs/manual/mod/mod_dll.html new file mode 100644 index 00000000000..c1056cc0c67 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_dll.html @@ -0,0 +1,165 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_dll</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_dll</H1> + +<STRONG><FONT COLOR="red">This module is obsolete. As of version +1.3b6 of Apache, it has been replaced with <A HREF="mod_so.html"> +mod_so</A>. </FONT></STRONG> + +<P> +This module is contained in the <CODE>mod_dll.c</CODE> file, and is +compiled in by default for Windows. It provides for loading of executable code +and modules into the server at start-up time, when they are contained in +Win32 DLLs.</P> + +<H2>Summary</H2> + +<P>The DLL module +loads other modules into the server as it is configuring itself (the +first time only, rereading the config files cannot affect the +state of loaded modules), when these modules are compiled into DLL files.</P> + +<P>This module is included with Apache 1.3 and later, and is available + only when using Microsoft Windows.</P> + +<H2><A NAME="creating">Creating DLL Modules</A></H2> + +<P>The Apache module API is unchanged between the Unix and Windows + versions. Many modules will run on Windows with no or little change + from Unix, although others rely on aspects of the Unix architecture + which are not present in Windows, and will not work.</P> + +<P>When a module does work, it can be added to the server in one of two + ways. As with Unix, it can be compiled into the server. Because Apache + for Windows does not have the <CODE>Configure</CODE> program of Apache + for Unix, the module's source file must be added to the ApacheCore + project file, and its symbols must be added to the + <CODE>nt\modules.c</CODE> file.</P> + +<P>The second way is to compile the module as a DLL, a shared library + that can be loaded into the server at runtime, using the + <CODE><A HREF="#loadmodule">LoadModule</A></CODE> + directive. These module DLLs can be distributed and run on any Apache + for Windows installation, without recompilation of the server.</P> + +<P>To create a module DLL, a small change is necessary to the module's + source file: The module record must be exported from the DLL (which + will be created later; see below). To do this, add the + <CODE>MODULE_VAR_EXPORT</CODE> (defined in the Apache header files) to + your module's module record definition. For example, if your module + has:</P> +<PRE> + module foo_module; +</PRE> +<P>Replace the above with:</P> +<PRE> + module MODULE_VAR_EXPORT foo_module; +</PRE> +<P>Note that this will only be activated on Windows, so the module can + continue to be used, unchanged, with Unix if needed. Also, if you are + familiar with <CODE>.DEF</CODE> files, you can export the module + record with that method instead.</P> + +<P>Now, create a DLL containing your module. You will need to link this + against the ApacheCore.lib export library that is created when the + ApacheCore.dll shared library is compiled. You may also have to change + the compiler settings to ensure that the Apache header files are + correctly located.</P> + +<P>This should create a DLL version of your module. Now simply place it + in the server root, and use the <CODE><A + HREF="#loadmodule">LoadModule</A></CODE> directive to + load it.</P> + +<H2>Directives</H2> +<UL> +<LI><A HREF="#loadfile">LoadFile</A> +<LI><A HREF="#loadmodule">LoadModule</A> +</UL> +<HR> + + +<H2><A NAME="loadfile">LoadFile</A></H2> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> LoadFile <EM>filename filename ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Core (Windows)<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_dll<P> + +The LoadFile directive links in the named object files or libraries when +the server is started; this is used to load additional code which +may be required for some module to work. <EM>Filename</EM> is relative +to <A HREF="core.html#serverroot">ServerRoot</A>.<P><HR> + +<H2><A NAME="loadmodule">LoadModule</A></H2> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> LoadModule <EM>module filename</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Core (Windows)<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_dll<P> + +The LoadModule directive links in the object file or library <EM>filename</EM> +and adds the module structure named <EM>module</EM> to the list of active +modules. <EM>Module</EM> is the name of the external variable of type +<CODE>module</CODE> in the file. Example: + +<BLOCKQUOTE><CODE> +LoadModule status_module modules/ApacheModuleStatus.dll<BR> +</CODE></BLOCKQUOTE> +loads the ApacheModuleStatus.dll module in the modules subdirectory of the +ServerRoot.<P> + + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_isapi.html b/usr.sbin/httpd/htdocs/manual/mod/mod_isapi.html new file mode 100644 index 00000000000..bdc3d5f9393 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_isapi.html @@ -0,0 +1,87 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_isapi</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Module mod_isapi</H1> + +<P>This module is contained in the <CODE>mod_isapi.c</CODE> file, and is + compiled in by default. It provides support for ISAPI Extensions when + running under Microsoft Windows. Any document with a handler of + <CODE>isapi-isa</CODE> will be processed by this module. + +<H2>Purpose</H2> + +<P>This module implements the <A + HREF="http://www.microsoft.com/win32dev/apiext/isapimrg.htm">ISAPI + Extension</A> API. It allows Internet Server Applications (<EM>i.e.</EM>, ISAPI + Extensions) to be used with Apache for Windows. + +<H2>Usage</H2> + +<P>In the server configuration file, add a handler called + <CODE>isapi-isa</CODE>, and map it to files with a <CODE>.DLL</CODE> + extension. In other words:</P> +<PRE> + AddHandler isapi-isa dll +</PRE> +<P>Now simply place the ISA DLLs into your document root, and they will + be loaded when their URLs are accessed.</P> + +<P>ISAPI Extensions are governed by the same restrictions as CGI + scripts. That is, <CODE>Options ExecCGI</CODE> must be active in the + directory that contains the ISA.</P> + +<H2>Notes</H2> + +<P>Apache's ISAPI implementation conforms to all of the ISAPI 2.0 + specification, except for the "Microsoft-specific" extensions dealing + with asynchronous I/O. Apache's I/O model does not allow asynchronous + reading and writing in a manner that the ISAPI could access. If an ISA + tries to access async I/O, a message will be place in the error log, + to help with debugging. + +<P>Some servers, like Microsoft IIS, load the ISA into the server, and + keep it loaded until memory usage is too high, and it is + unloaded. Apache currently loads and unloads the ISA for each + request. This is inefficient, but Apache's request model makes this + method the only method that currently works. A future release may use + a more effective loading method. + +<P>Apache 1.3a1 currently limits POST and PUT input to 48k per + request. This is to work around a problem with the ISAPI implementation + that could result in a denial of service attack. It is expected that + support for larger uploads will be added soon. + +<P>Also, remember that while Apache supports ISAPI Extensions, it does + not support ISAPI Filters. Support for filters may be added at a later + date, but no support is planned at this time.</P> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_mime_magic.html b/usr.sbin/httpd/htdocs/manual/mod/mod_mime_magic.html new file mode 100644 index 00000000000..a85e6b46b5b --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_mime_magic.html @@ -0,0 +1,275 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Apache module mod_mime_magic</TITLE> + </HEAD> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + <BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" + > + <DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + </DIV> + + <H1 align="CENTER">Module mod_mime_magic</H1> + + This module is contained in the mod_mime_magic.c file, and is + an optional extension to the Apache HTTPD server. + It can be used to determine the MIME type of a file by looking at a + few bytes of its contents, the same way the Unix file(1) command works. + To use mod_mime_magic you have to enable the following line in the + server build <TT>Configuration</TT> file: + + <PRE> + AddModule modules/standard/mod_mime_magic.o + </PRE> + + This should be listed <EM>before</EM> mod_mime in the build + <TT>Configuration</TT> file so that it will be used after mod_mime. + mod_mime_magic is intended as a "second line of defense" for cases + mod_mime cannot resolve. + + <H2>Summary</H2> + + This module is derived from a free version of the <CODE>file(1)</CODE> + command for Unix, + which uses "magic numbers" and other hints from a file's contents to + figure out what the contents are. + In the case of this module, + it tries to figure out the MIME type of the file. + <P> + This module active only if the magic file is specified by the + <A HREF="#mimemagicfile"><CODE>MimeMagicFile</CODE></A> directive. + <P> + The contents of the file are plain ASCII text in 4-5 columns. + Blank lines are allowed but ignored. + Commented lines use a hash mark "#". + The remaining lines are parsed for the following columns: + <table border=1> + <tr valign=top> + <TH>Column</TH> + <TH>Description</TH> + </TR> + <tr valign=top> + <TD>1</TD> + <TD>byte number to begin checking from + <BR> + ">" indicates a dependency upon the previous non-">" line</TD> + </TR><tr valign=top> + <TD>2</TD> + <TD>type of data to match + <table border=1> + <TR><TD>byte</TD><TD>single character</TD></TR> + <TR><TD>short</TD><TD>machine-order 16-bit integer</TD></TR> + <TR><TD>long</TD><TD>machine-order 32-bit integer</TD></TR> + <TR><TD>string</TD><TD>arbitrary-length string</TD></TR> + <TR><TD>date</TD><TD>long integer date + (seconds since Unix epoch/1970)</TD></TR> + <TR><TD>beshort</TD><TD>big-endian 16-bit integer</TD></TR> + <TR><TD>belong</TD><TD>big-endian 32-bit integer</TD></TR> + <TR><TD>bedate</TD><TD>big-endian 32-bit integer date</TD></TR> + <TR><TD>leshort</TD><TD>little-endian 16-bit integer</TD></TR> + <TR><TD>lelong</TD><TD>little-endian 32-bit integer</TD></TR> + <TR><TD>ledate</TD><TD>little-endian 32-bit integer date</TD></TR> + </TABLE> + </TD> + </TR><tr valign=top> + <TD>3</TD> + <TD>contents of data to match</TD> + </TR><tr valign=top> + <TD>4</TD> + <TD>MIME type if matched</TD> + </TR><tr valign=top> + <TD>5</TD> + <TD>MIME encoding if matched (optional)</TD> + </TR> + </TABLE> + + <P> + For example, the following magic file lines + would recognize some audio formats. + +<PRE> +# Sun/NeXT audio data +0 string .snd +>12 belong 1 audio/basic +>12 belong 2 audio/basic +>12 belong 3 audio/basic +>12 belong 4 audio/basic +>12 belong 5 audio/basic +>12 belong 6 audio/basic +>12 belong 7 audio/basic +>12 belong 23 audio/x-adpcm +</PRE> + + Or these would recognize the difference between "*.doc" files containing + Microsoft Word or FrameMaker documents. (These are incompatible file + formats which use the same file suffix.) + +<PRE> +# Frame +0 string \<MakerFile application/x-frame +0 string \<MIFFile application/x-frame +0 string \<MakerDictionary application/x-frame +0 string \<MakerScreenFon application/x-frame +0 string \<MML application/x-frame +0 string \<Book application/x-frame +0 string \<Maker application/x-frame + +# MS-Word +0 string \376\067\0\043 application/msword +0 string \320\317\021\340\241\261 application/msword +0 string \333\245-\0\0\0 application/msword +</PRE> + + An optional MIME encoding can be included as a fifth column. + For example, this can recognize gzipped files and set the encoding + for them. + +<PRE> +# gzip (GNU zip, not to be confused with [Info-ZIP/PKWARE] zip archiver) +0 string \037\213 application/octet-stream x-gzip +</PRE> + + <H3>Performance Issues</H3> + + This module is not for every system. If your system is barely keeping + up with its load or if you're performing a web server benchmark, + you may not want to enable this because the processing is not free. + <P> + However, an effort was made to improve the performance of the original + file(1) code to make it fit in a busy web server. + It was designed for a server where there are thousands of users who + publish their own documents. + This is probably very common on intranets. + Many times, it's helpful + if the server can make more intelligent decisions about a file's + contents than the file name allows + ...even if just to reduce the "why doesn't my page work" calls + when users improperly name their own files. + You have to decide if the extra work suits your environment. + <P> + When compiling an Apache server, this module should be at or near the + top of the list of modules in the Configuration file. The modules are + listed in increasing priority so that will mean this one is used only + as a last resort, just like it was designed to. + + <H2>Directives</H2> + <P> + <UL> + <LI><A HREF="#mimemagicfile">MimeMagicFile</A> + </LI> + </UL> + </P> + <HR> + <H2><A NAME="mimemagicfile"> + MimeMagicFile + </A></H2> + <P> + <A + HREF="directive-dict.html#Syntax" + REL="Help" + ><STRONG>Syntax:</STRONG></A> MimeMagicFile <EM>magic-file-name</EM> + <BR> + <A + HREF="directive-dict.html#Default" + REL="Help" + ><STRONG>Default:</STRONG></A> none + <BR> + <A + HREF="directive-dict.html#Context" + REL="Help" + ><STRONG>Context:</STRONG></A> server config, virtual host + <BR> + <A + HREF="directive-dict.html#Status" + REL="Help" + ><STRONG>Status:</STRONG></A> Extension + <BR> + <A + HREF="directive-dict.html#Module" + REL="Help" + ><STRONG>Module:</STRONG></A> mod_mime_magic + <P> + + The <CODE>MimeMagicFile</CODE> directive can be used to enable this module, + the default file is distributed at <CODE>conf/magic</CODE>. + Non-rooted paths are relative to the ServerRoot. Virtual hosts + will use the same file as the main server unless a more specific setting + is used, in which case the more specific setting overrides the main server's + file. + <P> + <HR> + + <H2><A NAME="notes">Notes</A></H2> + + The following notes apply to the mod_mime_magic module and are + included here for compliance with contributors' copyright restrictions + that require their acknowledgment. + +<PRE> +/* + * mod_mime_magic: MIME type lookup via file magic numbers + * Copyright (c) 1996-1997 Cisco Systems, Inc. + * + * This software was submitted by Cisco Systems to the Apache Group in July + * 1997. Future revisions and derivatives of this source code must + * acknowledge Cisco Systems as the original contributor of this module. + * All other licensing and usage conditions are those of the Apache Group. + * + * Some of this code is derived from the free version of the file command + * originally posted to comp.sources.unix. Copyright info for that program + * is included below as required. + * --------------------------------------------------------------------------- + * - Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin. + * + * This software is not subject to any license of the American Telephone and + * Telegraph Company or of the Regents of the University of California. + * + * Permission is granted to anyone to use this software for any purpose on any + * computer system, and to alter it and redistribute it freely, subject to + * the following restrictions: + * + * 1. The author is not responsible for the consequences of use of this + * software, no matter how awful, even if they arise from flaws in it. + * + * 2. The origin of this software must not be misrepresented, either by + * explicit claim or by omission. Since few users ever read sources, credits + * must appear in the documentation. + * + * 3. Altered versions must be plainly marked as such, and must not be + * misrepresented as being the original software. Since few users ever read + * sources, credits must appear in the documentation. + * + * 4. This notice may not be removed or altered. + * ------------------------------------------------------------------------- + * + * For compliance with Mr Darwin's terms: this has been very significantly + * modified from the free "file" command. + * - all-in-one file for compilation convenience when moving from one + * version of Apache to the next. + * - Memory allocation is done through the Apache API's pool structure. + * - All functions have had necessary Apache API request or server + * structures passed to them where necessary to call other Apache API + * routines. (<EM>i.e.</EM>, usually for logging, files, or memory allocation in + * itself or a called function.) + * - struct magic has been converted from an array to a single-ended linked + * list because it only grows one record at a time, it's only accessed + * sequentially, and the Apache API has no equivalent of realloc(). + * - Functions have been changed to get their parameters from the server + * configuration instead of globals. (It should be reentrant now but has + * not been tested in a threaded environment.) + * - Places where it used to print results to stdout now saves them in a + * list where they're used to set the MIME type in the Apache request + * record. + * - Command-line flags have been removed since they will never be used here. + * + */ +</PRE> + + </BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_mmap_static.html b/usr.sbin/httpd/htdocs/manual/mod/mod_mmap_static.html new file mode 100644 index 00000000000..1459de95aa5 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_mmap_static.html @@ -0,0 +1,156 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Apache module mod_mmap_static</TITLE> + </HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> + <BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" + > +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + + <H1 ALIGN="CENTER">Module mod_mmap_static</H1> + + <P> + This module is contained in the <CODE>mod_mmap_static.c</CODE> file, with + Apache 1.3 and later. It provides mmap()ing of a statically configured list + of frequently requested but not changed files. It is not compiled into the + server by default. To use <CODE>mod_mmap_static</CODE> you have to enable + the following line in the server build <CODE>Configuration</CODE> file: + <PRE> + AddModule modules/experimental/mod_mmap_static.o + </PRE> + </P> + + <H2>Summary</H2> + <P> + This is an <STRONG>experimental</STRONG> module and should be used with + care. You can easily create a broken site using this module, read this + document carefully. + <CODE>mod_mmap_static</CODE> maps a list of statically configured files (via + <CODE>MMapFile</CODE> directives in the main server configuration) into + memory through the system call <CODE>mmap()</CODE>. This system + call is available on most modern Unix derivates, but not on all. There + are sometimes system-specific limits on the size and number of files that + can be mmap()d, experimentation is probably the easiest way to find out. + </P> + <P> + This mmap()ing is done once at server start or restart, only. So whenever + one of the mapped files changes on the filesystem you <EM>have</EM> to + restart the server by at least sending it a HUP or USR1 signal (see the + <A HREF="../stopping.html">Stopping and Restarting</A> documentation). To + reiterate that point: if the files are modified <EM>in place</EM> without + restarting the server you may end up serving requests that are completely + bogus. You should update files by unlinking the old copy and putting a new + copy in place. Most tools such as <CODE>rdist</CODE> and <CODE>mv</CODE> do + this. The reason why this modules doesn't take care of changes to the files + is that this check would need an extra <CODE>stat()</CODE> every time which + is a waste and against the intent of I/O reduction. + </P> + + <H2>Directives</H2> + <UL> + <LI><A HREF="#mmapfile">MMapFile</A> + </LI> + </UL> + + <HR> + + <H2><A NAME="mmapfile">MMapFile</A></H2> + <P> + <A + HREF="directive-dict.html#Syntax" + REL="Help" + ><STRONG>Syntax:</STRONG></A> MMapFile <EM>filename ...</EM> + <BR> + <A + HREF="directive-dict.html#Default" + REL="Help" + ><STRONG>Default:</STRONG></A> <EM>None</EM> + <BR> + <A + HREF="directive-dict.html#Context" + REL="Help" + ><STRONG>Context:</STRONG></A> server-config + <BR> + <A + HREF="directive-dict.html#Override" + REL="Help" + ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM> + <BR> + <A + HREF="directive-dict.html#Status" + REL="Help" + ><STRONG>Status:</STRONG></A> Experimental + <BR> + <A + HREF="directive-dict.html#Module" + REL="Help" + ><STRONG>Module:</STRONG></A> mod_mmap_static + <BR> + <A + HREF="directive-dict.html#Compatibility" + REL="Help" + ><STRONG>Compatibility:</STRONG></A> Only available in Apache 1.3 or later + + <P> + The <CODE>MMapFile</CODE> directive maps one or more files (given as + whitespace separated arguments) into memory at server startup time. They + are automatically unmapped on a server shutdown. When the files have changed + on the filesystem at least a HUP or USR1 signal should be send to the server + to re-mmap them. + </P> + + <P> + Be careful with the <EM>filename</EM> arguments: They have to literally + match the filesystem path Apache's URL-to-filename translation handlers + create. We cannot compare inodes or other stuff to match paths through + symbolic links <EM>etc.</EM> because that again would cost extra <CODE>stat()</CODE> + system calls which is not acceptable. This module may or may not work + with filenames rewritten by <CODE>mod_alias</CODE> or + <CODE>mod_rewrite</CODE>... it is an experiment after all. + </P> + + <P> + Notice: You cannot use this for speeding up CGI programs or other files + which are served by special content handlers. It can only be used for + regular files which are usually served by the Apache core content handler. + </P> + + Example: + + <PRE> + MMapFile /usr/local/apache/htdocs/index.html + </PRE> + + <P> + <STRONG>Note</STRONG>: don't bother asking for a for a <CODE>MMapDir</CODE> + directive which + recursively maps all the files in a directory. Use Unix the way it was + meant to be used. For example, see the + <A HREF="core.html#include">Include</A> directive, and consider this command: + <PRE> + find /www/htdocs -type f -print \ + | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf + </PRE> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + + </BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html b/usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html new file mode 100644 index 00000000000..507845a8e54 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html @@ -0,0 +1,387 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Apache module mod_setenvif</TITLE> + </HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> + <BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" + > +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + + <H1 ALIGN="CENTER">Module mod_setenvif</H1> + <P> + This module is contained in the <SAMP>mod_setenvif.c</SAMP> file, and + <STRONG>is</STRONG> compiled in by default. It provides for + the ability to set environment variables based upon attributes of the + request. + </P> + <H2>Summary</H2> + <P> + The <SAMP>mod_setenvif</SAMP> module allows you to set environment + variables according to whether different aspects of the request match + regular expressions you specify. These envariables can be used by + other parts of the server to make decisions about actions to be taken. + </P> + <P>The directives are considered in the order they appear in the + configuration files. So more complex sequences can be used, such + as this example, which sets <CODE>netscape</CODE> if the browser + is mozilla but not MSIE. + <BLOCKQUOTE><PRE> + BrowserMatch ^Mozilla netscape + BrowserMatch MSIE !netscape + </PRE></BLOCKQUOTE> + </P> + + <H2>Directives</H2> + <UL> + <LI><A HREF="#BrowserMatch">BrowserMatch</A> + </LI> + <LI><A HREF="#BrowserMatchNoCase">BrowserMatchNoCase</A> + </LI> + <LI><A HREF="#SetEnvIf">SetEnvIf</A> + </LI> + <LI><A HREF="#SetEnvIfNoCase">SetEnvIfNoCase</A> + </LI> + </UL> + + <HR> <!-- the HR is part of the directive description --> + <H2><A NAME="BrowserMatch">The <SAMP>BrowserMatch</SAMP> Directive</A></H2> + <P> + <A + HREF="directive-dict.html#Syntax" + REL="Help" + ><STRONG>Syntax:</STRONG></A> BrowserMatch <EM>regex envar[=value] [...]</EM> + <BR> + <A + HREF="directive-dict.html#Default" + REL="Help" + ><STRONG>Default:</STRONG></A> <EM>none</EM> + <BR> + <A + HREF="directive-dict.html#Context" + REL="Help" + ><STRONG>Context:</STRONG></A> server config + <BR> + <A + HREF="directive-dict.html#Override" + REL="Help" + ><STRONG>Override:</STRONG></A> <EM>none</EM> + <BR> + <A + HREF="directive-dict.html#Status" + REL="Help" + ><STRONG>Status:</STRONG></A> Base + <BR> + <A + HREF="directive-dict.html#Module" + REL="Help" + ><STRONG>Module:</STRONG></A> mod_setenvif + <BR> + <A + HREF="directive-dict.html#Compatibility" + REL="Help" + ><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above (in Apache 1.2 + this directive was found in the now-obsolete mod_browser module) + </P> + <P> + The BrowserMatch directive defines environment variables based on the + <SAMP>User-Agent</SAMP> HTTP request header field. The first argument + should be a POSIX.2 extended regular expression (similar to an + <SAMP>egrep</SAMP>-style regex). The rest of the arguments give the + names of variables to set, and optionally values to which they should + be set. These take the form of + </P> + <OL> + <LI><SAMP><EM>varname</EM></SAMP>, or + </LI> + <LI><SAMP>!<EM>varname</EM></SAMP>, or + </LI> + <LI><SAMP><EM>varname</EM>=<EM>value</EM></SAMP> + </LI> + </OL> + <P> + In the first form, the value will be set to "1". The second + will remove the given variable if already defined, and the third will + set the variable to the value given by <SAMP><EM>value</EM></SAMP>. If a + <SAMP>User-Agent</SAMP> string matches more than one entry, they will + be merged. Entries are processed in the order in which they appear, + and later entries can override earlier ones. + </P> + <P> + For example: + </P> + <PRE> + BrowserMatch ^Mozilla forms jpeg=yes browser=netscape + BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript + BrowserMatch MSIE !javascript + </PRE> + <P> + Note that the regular expression string is + <STRONG>case-sensitive</STRONG>. For cane-INsensitive matching, see + the + <A + HREF="#BrowserMatchNoCase" + ><SAMP>BrowserMatchNoCase</SAMP></A> + directive. + </P> + <P> + The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP> + directives are special cases of the + <A + HREF="#SetEnvIf" + ><SAMP>SetEnvIf</SAMP></A> + and + <A + HREF="#SetEnvIfNoCase" + ><SAMP>SetEnvIfNoCase</SAMP></A> + directives. The following two lines have the same effect: + </P> + <PRE> + BrowserMatchNoCase Robot is_a_robot + SetEnvIfNoCase User-Agent Robot is_a_robot + </PRE> + + <HR> <!-- the HR is part of the directive description --> + <H2> + <A NAME="BrowserMatchNoCase"> + The <SAMP>BrowserMatchNoCase</SAMP> Directive + </A> + </H2> + <P> + <A + HREF="directive-dict.html#Syntax" + REL="Help" + ><STRONG>Syntax:</STRONG></A> BrowserMatchNoCase <EM>regex envar[=value] + [...]</EM> + <BR> + <A + HREF="directive-dict.html#Default" + REL="Help" + ><STRONG>Default:</STRONG></A> <EM>none</EM> + <BR> + <A + HREF="directive-dict.html#Context" + REL="Help" + ><STRONG>Context:</STRONG></A> server config + <BR> + <A + HREF="directive-dict.html#Override" + REL="Help" + ><STRONG>Override:</STRONG></A> <EM>none</EM> + <BR> + <A + HREF="directive-dict.html#Status" + REL="Help" + ><STRONG>Status:</STRONG></A> Base + <BR> + <A + HREF="directive-dict.html#Module" + REL="Help" + ><STRONG>Module:</STRONG></A> mod_setenvif + <BR> + <A + HREF="directive-dict.html#Compatibility" + REL="Help" + ><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above (in Apache 1.2 + this directive was found in the now-obsolete mod_browser module) + </P> + <P> + The <SAMP>BrowserMatchNoCase</SAMP> directive is semantically identical to + the + <A + HREF="#BrowserMatch" + ><SAMP>BrowserMatch</SAMP></A> + directive. However, it provides for case-insensitive matching. For + example: + </P> + <PRE> + BrowserMatchNoCase mac platform=macintosh + BrowserMatchNoCase win platform=windows + </PRE> + <P> + The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP> + directives are special cases of the + <A + HREF="#SetEnvIf" + ><SAMP>SetEnvIf</SAMP></A> + and + <A + HREF="#SetEnvIfNoCase" + ><SAMP>SetEnvIfNoCase</SAMP></A> + directives. The following two lines have the same effect: + </P> + <PRE> + BrowserMatchNoCase Robot is_a_robot + SetEnvIfNoCase User-Agent Robot is_a_robot + </PRE> + + <HR> <!-- the HR is part of the directive description --> + <H2> + <A NAME="SetEnvIf"> + The <SAMP>SetEnvIf</SAMP> Directive + </A> + </H2> + <P> + <A + HREF="directive-dict.html#Syntax" + REL="Help" + ><STRONG>Syntax:</STRONG></A> SetEnvIf <EM> attribute regex envar[=value] + [...]</EM> + <BR> + <A + HREF="directive-dict.html#Default" + REL="Help" + ><STRONG>Default:</STRONG></A> <EM>none</EM> + <BR> + <A + HREF="directive-dict.html#Context" + REL="Help" + ><STRONG>Context:</STRONG></A> server config + <BR> + <A + HREF="directive-dict.html#Override" + REL="Help" + ><STRONG>Override:</STRONG></A> <EM>none</EM> + <BR> + <A + HREF="directive-dict.html#Status" + REL="Help" + ><STRONG>Status:</STRONG></A> Base + <BR> + <A + HREF="directive-dict.html#Module" + REL="Help" + ><STRONG>Module:</STRONG></A> mod_setenvif + <BR> + <A + HREF="directive-dict.html#Compatibility" + REL="Help" + ><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above + </P> + <P> + The <SAMP>SetEnvIf</SAMP> directive defines environment variables + based on attributes of the request. These attributes can be the + values of various HTTP request header fields (see + <A + HREF="http://ds.internic.net/rfc/rfc2068.txt" + >RFC2068</A> + for more information about these), or of other aspects of the request, + including the following: + </P> + <UL> + <LI><SAMP>Remote_Host</SAMP> - the hostname (if available) of the + client making the request + </LI> + <LI><SAMP>Remote_Addr</SAMP> - the IP address of the client making + the request + </LI> + <LI><SAMP>Remote_User</SAMP> - the authenticated username (if + available) + </LI> + <LI><SAMP>Request_Method</SAMP> - the name of the method being used + (<SAMP>GET</SAMP>, <SAMP>POST</SAMP>, <EM>et cetera</EM>) + </LI> + <LI><SAMP>Request_URI</SAMP> - the portion of the URL following the + scheme and host portion + </LI> + </UL> + <P> + Some of the more commonly used request header field names include + <SAMP>Host</SAMP>, <SAMP>User-Agent</SAMP>, and <SAMP>Referer</SAMP>. + </P> + <P> + Example: + </P> + <PRE> + SetEnvIf Request_URI "\.(gif)|(jpg)|(xbm)$" object_is_image + SetEnvIf Referer www\.mydomain\.com intra_site_referral + </PRE> + <P> + The first will set the envariable <SAMP>object_is_image</SAMP> if the + request was for an image file, and the second sets + <SAMP>intra_site_referral</SAMP> if the referring page was somewhere + on the <SAMP>www.mydomain.com</SAMP> Web site. + </P> + + <HR> <!-- the HR is part of the directive description --> + <H2> + <A NAME="SetEnvIfNoCase"> + The <SAMP>SetEnvIfNoCase</SAMP> Directive + </A> + </H2> + <P> + <A + HREF="directive-dict.html#Syntax" + REL="Help" + ><STRONG>Syntax:</STRONG></A> SetEnvIfNoCase + <EM> attribute regex envar[=value] [...]</EM> + <BR> + <A + HREF="directive-dict.html#Default" + REL="Help" + ><STRONG>Default:</STRONG></A> <EM>none</EM> + <BR> + <A + HREF="directive-dict.html#Context" + REL="Help" + ><STRONG>Context:</STRONG></A> server config + <BR> + <A + HREF="directive-dict.html#Override" + REL="Help" + ><STRONG>Override:</STRONG></A> <EM>none</EM> + <BR> + <A + HREF="directive-dict.html#Status" + REL="Help" + ><STRONG>Status:</STRONG></A> Base + <BR> + <A + HREF="directive-dict.html#Module" + REL="Help" + ><STRONG>Module:</STRONG></A> mod_setenvif + <BR> + <A + HREF="directive-dict.html#Compatibility" + REL="Help" + ><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above + </P> + <P> + The <SAMP>SetEnvIfNoCase</SAMP> is semantically identical to the + <A + HREF="#SetEnvIf" + ><SAMP>SetEnvIf</SAMP></A> + directive, and differs only in that the regular expression matching is + performed in a case-insensitive manner. For example: + </P> + <PRE> + SetEnvIfNoCase Host Apache\.Org site=apache + </PRE> + <P> + This will cause the <SAMP>site</SAMP> envariable to be set to + "<SAMP>apache</SAMP>" if the HTTP request header field + <SAMP>Host:</SAMP> was included and contained <SAMP>Apache.Org</SAMP>, + <SAMP>apache.org</SAMP>, or any other combination. + </P> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + + </BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_so.html b/usr.sbin/httpd/htdocs/manual/mod/mod_so.html new file mode 100644 index 00000000000..bd466f4aab9 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_so.html @@ -0,0 +1,178 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_so</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_so</H1> + +This module is contained in the <CODE>mod_so.c</CODE> file. It is +compiled in by default on Windows and is not compiled in by default on +Unix. It provides for loading of executable code and modules into the +server at start-up or restart time. On Unix, the loaded code typically +comes from shared object files (usually with <SAMP>.so</SAMP> +extension), whilst on Windows this module loads <SAMP>DLL</SAMP> +files. This module is only available in Apache 1.3 and up. + +<P> + +In previous releases, the functionality of this module was provided +for Unix by mod_dld, and for Windows by mod_dll. On Windows, mod_dll +was used in beta release 1.3b1 through 1.3b5. mod_so combines these +two modules into a single module for all operating systems. + +<H2>Summary</H2> + +This is an experimental module. On selected operating systems it can be used +to load modules into Apache at runtime via the <A HREF="../dso.html">Dynamic +Shared Object</A> (DSO) mechanism, rather than requiring a recompilation. + +<H2>Directives</H2> +<UL> +<LI><A HREF="#loadfile">LoadFile</A> +<LI><A HREF="#loadmodule">LoadModule</A> +</UL> +<HR> + + +<H2><A NAME="loadfile">LoadFile</A></H2> +<!--%plaintext <?INDEX {\tt LoadFile} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> LoadFile <EM>filename filename ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Experimental<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_so<P> + +The LoadFile directive links in the named object files or libraries +when the server is started or restarted; this is used to load +additional code which may be required for some module to +work. <EM>Filename</EM> is either and absolute path or relative to <A +HREF="core.html#serverroot">ServerRoot</A>.<P><HR> + +<H2><A NAME="loadmodule">LoadModule</A></H2> +<!--%plaintext <?INDEX {\tt LoadModule} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> LoadModule <EM>module filename</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Experimental<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_so<P> + +The LoadModule directive links in the object file or library <EM>filename</EM> +and adds the module structure named <EM>module</EM> to the list of active +modules. <EM>Module</EM> is the name of the external variable of type +<CODE>module</CODE> in the file. Example (Unix): +<BLOCKQUOTE><CODE> +LoadModule status_module modules/mod_status.so +</CODE></BLOCKQUOTE> + +<P> + +Example (Windows): +<BLOCKQUOTE><CODE> +LoadModule status_module modules/ApacheModuleStatus.dll<BR> +</CODE></BLOCKQUOTE> + +loads the named module from the modules subdirectory of the +ServerRoot.<P> + +<HR> + +<H2><A NAME="creating">Creating DLL Modules for Windows</A></H2> + +<P>The Apache module API is unchanged between the Unix and Windows + versions. Many modules will run on Windows with no or little change + from Unix, although others rely on aspects of the Unix architecture + which are not present in Windows, and will not work.</P> + +<P>When a module does work, it can be added to the server in one of two + ways. As with Unix, it can be compiled into the server. Because Apache + for Windows does not have the <CODE>Configure</CODE> program of Apache + for Unix, the module's source file must be added to the ApacheCore + project file, and its symbols must be added to the + <CODE>os\win32\modules.c</CODE> file.</P> + +<P>The second way is to compile the module as a DLL, a shared library + that can be loaded into the server at runtime, using the + <CODE><A HREF="#loadmodule">LoadModule</A></CODE> + directive. These module DLLs can be distributed and run on any Apache + for Windows installation, without recompilation of the server.</P> + +<P>To create a module DLL, a small change is necessary to the module's + source file: The module record must be exported from the DLL (which + will be created later; see below). To do this, add the + <CODE>MODULE_VAR_EXPORT</CODE> (defined in the Apache header files) to + your module's module record definition. For example, if your module + has:</P> +<PRE> + module foo_module; +</PRE> +<P>Replace the above with:</P> +<PRE> + module MODULE_VAR_EXPORT foo_module; +</PRE> +<P>Note that this will only be activated on Windows, so the module can + continue to be used, unchanged, with Unix if needed. Also, if you are + familiar with <CODE>.DEF</CODE> files, you can export the module + record with that method instead.</P> + +<P>Now, create a DLL containing your module. You will need to link this + against the ApacheCore.lib export library that is created when the + ApacheCore.dll shared library is compiled. You may also have to change + the compiler settings to ensure that the Apache header files are + correctly located.</P> + +<P>This should create a DLL version of your module. Now simply place it + in the <SAMP>modules</SAMP> directory of your server root, and use + the <CODE><A HREF="#loadmodule">LoadModule</A></CODE> directive to + load it.</P> + + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_speling.html b/usr.sbin/httpd/htdocs/manual/mod/mod_speling.html new file mode 100644 index 00000000000..cde7271ef20 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_speling.html @@ -0,0 +1,136 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Apache module mod_speling</TITLE> + </HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> + <BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" + > +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + + <H1 ALIGN="CENTER">Module mod_speling</H1> + <P> + This module is contained in the <CODE>mod_speling.c</CODE> file, + and is <STRONG>not</STRONG> compiled in by default. + It attempts to correct misspellings of + URLs that users might have entered, by ignoring capitalization + and by allowing up to one misspelling.<BR> + This catches the majority of misspelled requests. An automatic + "spelling corrected" redirection is returned if only one matching + document was found, and a list of matches is returned if more than + one document with a sufficiently similar name is found. + </P> + + <H2>Summary</H2> + <P> + Requests to documents sometimes cannot be served by the core apache + server because the request was misspelled or miscapitalized. This + module addresses this problem by trying to find a matching document, + even after all other modules gave up. It does its work by comparing + each document name in the requested directory against the requested + document name <STRONG>without regard to case</STRONG>, and allowing + <STRONG>up to one misspelling</STRONG> (character insertion / omission + / transposition or wrong character). A list is built with all document + names which were matched using this strategy. + </P> + <P> + If, after scanning the directory, + <UL> + <LI>no matching document was found, Apache will proceed as usual + and return a "document not found" error. + <LI>only one document is found that "almost" matches the request, + then it is returned in the form of a redirection response. + <LI>more than one document with a close match was found, then + the list of the matches is returned to the client, and the client + can select the correct candidate. + </UL> + </P> + + <H2>Directives</H2> + + <MENU> + <LI><A HREF="#checkspelling">CheckSpelling</A> + </MENU> + + <HR> <!-- the HR is part of the directive description --> + <H2><A NAME="checkspelling">CheckSpelling</A></H2> + <!--%plaintext <?INDEX {\tt CheckSpelling} directive> --> + <A + HREF="directive-dict.html#Syntax" + REL="Help" + ><STRONG>Syntax:</STRONG></A> CheckSpelling <EM>on/off</EM><BR> + <A + HREF="directive-dict.html#Default" + REL="Help" + ><STRONG>Default:</STRONG></A> <CODE>CheckSpelling Off</CODE><BR> + <A + HREF="directive-dict.html#Context" + REL="Help" + ><STRONG>Context:</STRONG></A> server config, virtual host, + directory, .htaccess<BR> + <A + HREF="directive-dict.html#Override" + REL="Help" + ><STRONG>Override:</STRONG></A> Options + <BR> + <A + HREF="directive-dict.html#Status" + REL="Help" + ><STRONG>Status:</STRONG></A> Base<BR> + <A + HREF="directive-dict.html#Module" + REL="Help" + ><STRONG>Module:</STRONG></A> mod_speling<BR> + <A + HREF="directive-dict.html#Compatibility" + REL="Help" + ><STRONG>Compatibility:</STRONG></A> CheckSpelling was available as a + separately + available module for Apache 1.1, but was limited to miscapitalizations. + As of Apache 1.3, it is part of the Apache distribution. Prior to + Apache 1.3.2, the <SAMP>CheckSpelling</SAMP> directive was only available + in the "server" and "virtual host" contexts. + <P> + This directive enables or disables the spelling module. When enabled, + keep in mind that + </P> + <UL> + <LI>the directory scan which is necessary for the spelling + correction will have an impact on the server's performance + when many spelling corrections have to be performed at the same time. + </LI> + <LI>the document trees should not contain sensitive files which could + be matched inadvertently by a spelling "correction". + </LI> + <LI>the module is unable to correct misspelled user names + (as in <CODE>http://my.host/~apahce/</CODE>), just file names or + directory names. + </LI> + <LI>spelling corrections apply strictly to existing files, so a request for + the <SAMP><Location /status></SAMP> may get incorrectly treated + as the negotiated file "<SAMP>/stats.html</SAMP>". + </LI> + </UL> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + + </BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html b/usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html new file mode 100644 index 00000000000..22f53108e61 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html @@ -0,0 +1,194 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_unique_id</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_unique_id</H1> + +This module provides a magic token for each request which is guaranteed +to be unique across "all" requests under very specific conditions. +The unique identifier is even unique across multiple machines in a +properly configured cluster of machines. The environment variable +<CODE>UNIQUE_ID</CODE> is set to the identifier for each request. +Unique identifiers are useful for various reasons which are beyond the +scope of this document. + +<H2>Theory</H2> + +<P> +First a brief recap of how the Apache server works on Unix machines. +This feature currently isn't supported on Windows NT. On Unix machines, +Apache creates several children, the children process requests one at +a time. Each child can serve multiple requests in its lifetime. For the +purpose of this discussion, the children don't share any data +with each other. We'll refer to the children as httpd processes. + +<P> +Your website has one or more machines under your administrative control, +together we'll call them a cluster of machines. Each machine can +possibly run multiple instances of Apache. All of these collectively +are considered "the universe", and with certain assumptions we'll +show that in this universe we can generate unique identifiers for each +request, without extensive communication between machines in the cluster. + +<P> +The machines in your cluster should satisfy these requirements. +(Even if you have only one machine you should synchronize its clock +with NTP.) + +<UL> +<LI>The machines' times are synchronized via NTP or other network time + protocol. + +<LI>The machines' hostnames all differ, such that the module can do a + hostname lookup on the hostname and receive a different IP address + for each machine in the cluster. +</UL> + +<P> +As far as operating system assumptions go, we assume that pids (process +ids) fit in 32-bits. If the operating system uses more than 32-bits +for a pid, the fix is trivial but must be performed in the code. + +<P> +Given those assumptions, at a single point in time we can identify +any httpd process on any machine in the cluster from all other httpd +processes. The machine's IP address and the pid of the httpd process +are sufficient to do this. So in order to generate unique identifiers +for requests we need only distinguish between different points in time. + +<P> +To distinguish time we will use a Unix timestamp (seconds since January +1, 1970 UTC), and a 16-bit counter. The timestamp has only one second +granularity, so the counter is used to represent up to 65536 values +during a single second. The quadruple <EM>( ip_addr, pid, time_stamp, +counter )</EM> is sufficient to enumerate 65536 requests per second per +httpd process. There are issues however with pid reuse over +time, and the counter is used to alleviate this issue. + +<P> +When an httpd child is created, the counter is initialized with ( +current microseconds divided by 10 ) modulo 65536 (this formula was +chosen to eliminate some variance problems with the low order bits of +the microsecond timers on some systems). When a unique identifier is +generated, the time stamp used is the time the request arrived at the +web server. The counter is incremented every time an identifier is +generated (and allowed to roll over). + +<P> +The kernel generates a pid for each process as it forks the process, and +pids are allowed to roll over (they're 16-bits on many Unixes, but newer +systems have expanded to 32-bits). So over time the same pid will be +reused. However unless it is reused within the same second, it does not +destroy the uniqueness of our quadruple. That is, we assume the system +does not spawn 65536 processes in a one second interval (it may even be +32768 processes on some Unixes, but even this isn't likely to happen). + +<P> +Suppose that time repeats itself for some reason. That is, suppose that +the system's clock is screwed up and it revisits a past time (or it is +too far forward, is reset correctly, and then revisits the future time). +In this case we can easily show that we can get pid and time stamp reuse. +The choice of initializer for the counter is intended to help defeat this. +Note that we really want a random number to initialize the counter, +but there aren't any readily available numbers on most systems (<EM>i.e.</EM>, you +can't use rand() because you need to seed the generator, and can't seed +it with the time because time, at least at one second resolution, has +repeated itself). This is not a perfect defense. + +<P> +How good a defense is it? Well suppose that one of your machines serves +at most 500 requests per second (which is a very reasonable upper bound +at this writing, because systems generally do more than just shovel out +static files). To do that it will require a number of children which +depends on how many concurrent clients you have. But we'll be pessimistic +and suppose that a single child is able to serve 500 requests per second. +There are 1000 possible starting counter values such that two sequences +of 500 requests overlap. So there is a 1.5% chance that if time (at one +second resolution) repeats itself this child will repeat a counter value, +and uniqueness will be broken. This was a very pessimistic example, +and with real world values it's even less likely to occur. If your +system is such that it's still likely to occur, then perhaps you should +make the counter 32 bits (by editing the code). + +<P> +You may be concerned about the clock being "set back" during summer +daylight savings. However this isn't an issue because the times used here +are UTC, which "always" go forward. Note that x86 based Unixes may need +proper configuration for this to be true -- they should be configured to +assume that the motherboard clock is on UTC and compensate appropriately. +But even still, if you're running NTP then your UTC time will be correct +very shortly after reboot. + +<P> +The <CODE>UNIQUE_ID</CODE> environment variable is constructed by +encoding the 112-bit (32-bit IP address, 32 bit pid, 32 bit time stamp, +16 bit counter) quadruple using the alphabet <CODE>[A-Za-z0-9@-]</CODE> +in a manner similar to MIME base64 encoding, producing 19 characters. +The MIME base64 alphabet is actually <CODE>[A-Za-z0-9+/]</CODE> however +<CODE>+</CODE> and <CODE>/</CODE> need to be specially encoded in URLs, +which makes them less desirable. All values are encoded in network +byte ordering so that the encoding is comparable across architectures of +different byte ordering. The actual ordering of the encoding is: time +stamp, IP address, pid, counter. This ordering has a purpose, but it +should be emphasized that applications should not dissect the encoding. +Applications should treat the entire encoded <CODE>UNIQUE_ID</CODE> as an +opaque token, which can be compared against other <CODE>UNIQUE_ID</CODE>s +for equality only. + +<P> +The ordering was chosen such that it's possible to change the encoding +in the future without worrying about collision with an existing database +of <CODE>UNIQUE_ID</CODE>s. The new encodings should also keep the time +stamp as the first element, and can otherwise use the same alphabet and +bit length. Since the time stamps are essentially an increasing sequence, +it's sufficient to have a <EM>flag second</EM> in which all machines in the +cluster stop serving and request, and stop using the old encoding format. +Afterwards they can resume requests and begin issuing the new encodings. + +<P> +This we believe is a relatively portable solution to this problem. It can +be extended to multithreaded systems like Windows NT, and can grow with +future needs. The identifiers generated have essentially an infinite +life-time because future identifiers can be made longer as required. +Essentially no communication is required between machines in the cluster +(only NTP synchronization is required, which is low overhead), and no +communication between httpd processes is required (the communication is +implicit in the pid value assigned by the kernel). In very specific +situations the identifier can be shortened, but more information needs +to be assumed (for example the 32-bit IP address is overkill for any +site, but there is no portable shorter replacement for it). + +<HR> + +<H2>Directives</H2> + +<CODE>mod_unique_id</CODE> has no directives. + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/new_features_1_3.html b/usr.sbin/httpd/htdocs/manual/new_features_1_3.html new file mode 100644 index 00000000000..8e955ceefc2 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/new_features_1_3.html @@ -0,0 +1,636 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>New features with Apache 1.3</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" + VLINK="#000080" ALINK="#FF0000"> +<DIV ALIGN="CENTER"> + <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Overview of New Features in Apache 1.3</H1> + +<P>New features with this release, as extensions of the Apache +functionality. Because the core code has changed so +significantly, there are certain liberties that earlier versions of +Apache (and the NCSA daemon) took that recent Apache versions are +pickier about - please check the +<A HREF="misc/compat_notes.html">compatibility notes</A> if you have any +problems.</P> + +<P>If you're upgrading from Apache 1.2, you may wish to read +the <A HREF="upgrading_to_1_3.html">upgrade notes</A>. + +<P>Enhancements: <A HREF="#core">Core</A> | +<A HREF="#performance">Performance</A> | +<A HREF="#config">Configuration</A> | +<A HREF="#mod">Modules</A> | +<A HREF="#api">API</A> | +<A HREF="#misc">Misc</A> + +<P><HR> + +<H2><A NAME="core">Core Enhancements:</A></H2> + +<DL> +<DT><STRONG><A HREF="dso.html">Dynamic Shared Object (DSO) support</A></STRONG> +<DD>Apache modules may now be loaded at runtime; this means that + modules can be loaded into the server process space only when necessary, + thus overall memory usage by Apache will be significantly reduced. DSO + currently is supported on FreeBSD, OpenBSD, NetBSD, Linux, Solaris, SunOS, + Digital UNIX, IRIX, HP/UX, UnixWare, AIX, ReliantUnix and generic SVR4 + platforms. + +<DT><STRONG><A HREF="windows.html">Support for Windows NT/95</A></STRONG> +<DD>Apache now experimentally supports the Windows NT and Windows 95 + operating systems. + +<DT><STRONG><A HREF="sourcereorg.html">Re-organized + Sources</A></STRONG> +<DD>The source files for Apache have been re-organized. The main + difference for Apache users is that the "Module" lines in + <CODE>Configuration</CODE> have been replaced with "AddModule" + with a slightly different syntax. For module authors there are + some changes designed to make it easier for users to add their + module. + +<DT><STRONG>Reliable Piped Logs</STRONG> +<DD>On almost all Unix architectures Apache now implements "reliable" + piped logs in <A + HREF="mod/mod_log_config.html">mod_log_config</A>. Where reliable + means that if the logging child dies for whatever reason, Apache + will recover and respawn it without having to restart the entire + server. Furthermore if the logging child becomes "stuck" and + isn't reading its pipe frequently enough Apache will also restart + it. This opens up more opportunities for log rotation, hit + filtering, real-time splitting of multiple vhosts into separate + logs, and asynchronous DNS resolving on the fly. + +</DL> + +<P><HR> + +<H2><A NAME="performance">Performance Improvements</A></H2> + +<UL> + <LI>IP-based virtual hosts are looked up via hash table. + <LI><Directory> parsing speedups. + <LI>The critical path for static requests has fewer system calls. + This generally helps all requests. (45 syscalls for a static + request in 1.2 versus 22 in 1.3 in a well tuned + configuration). + <LI><A HREF="mod/mod_proxy.html#proxyreceivebuffersize"> + <CODE>ProxyReceiveBufferSize</CODE></A> directive gives + <CODE>mod_proxy</CODE>'s outgoing connections larger network + buffers, for increased throughput. + <LI>The low level I/O routines use <CODE>writev</CODE> (where + available) to issue multiple writes with a single system call. + They also avoid copying memory into buffers as much as + possible. The result is less CPU time spent on transferring + large files. + <LI>Static requests are served using <CODE>mmap</CODE>, which + means bytes are only copied from the disk buffer to the + network buffer directly by the kernel. The program never + copies bytes around, which reduces CPU time. (Only where + available/tested.) + <LI>When presented with a load spike, the server quickly adapts by + spawning children at faster rates. + <LI>The code which dispatches modules was optimized to avoid + repeatedly skipping over modules that don't implement certain + phases of the API. (This skipping showed up as 5% of the cpu + time on profiles of a server with the default module mix.) + <LI>Revamp of the Unix scoreboard management code so that less + time is spent counting children in various states. Previously + a scan was performed for each hit, now it is performed only + once per second. This should be noticeable on servers running + with hundreds of children and high loads. + <LI>New serialization choices improve performance on Linux, and + IRIX. + <LI><CODE><A + HREF="mod/mod_log_config.html">mod_log_config</A></CODE> can + be compile-time configured to buffer writes. + <LI>Replaced <CODE>strncpy()</CODE> with + <CODE>ap_cpystrn()</CODE>, a routine which doesn't have to + zero-fill the entire result. This has dramatic effects on + <CODE>mod_include</CODE> speed. + <LI>Additions to the internal "table" API (used for keeping lists + of key/value string pairs) provide for up to 20% performance + improvement in many situations. +</UL> + +<P>See <A HREF="misc/perf-tuning.html">the new performance +documentation</A> for more information. + +<P><HR> + +<H2><A NAME="config">Configuration Enhancements</A></H2> + +<DL> +<DT><STRONG>Apache Autoconf-style Interface (APACI)</STRONG> +<DD>Until Apache 1.3 there was no real out-of-the-box batch-capable + build and installation procedure for the complete Apache + package. This is now provided by a top-level + <CODE>configure</CODE> script and a corresponding top-level + <CODE>Makefile.tmpl</CODE> file. The goal is to provide a GNU + Autoconf-style frontend which is capable to both drive the old + <CODE>src/Configure</CODE> stuff in batch and additionally + installs the package with a GNU-conforming directory layout. Any + options from the old configuration scheme are available plus a lot + of new options for flexibly customizing Apache. + +<DT><STRONG>APache eXtenSion (APXS) support tool</STRONG> +<DD>Now that Apache provides full support for loading modules under + runtime from dynamic shared object (DSO) files, a new support tool + <CODE>apxs</CODE> was created which provides off-source building, + installing and activating of those DSO-based modules. It + completely hides the platform-dependent DSO-build commands from + the user and provides an easy way to build modules outside the + Apache source tree. To achieve this APACI installs the Apache C + header files together with the <CODE>apxs</CODE> tool. + +<DT><A HREF="install.html#install"><STRONG>Default Apache directory + path changed to <CODE>/usr/local/apache/</CODE></STRONG></A><BR> +<DD>The default directory for the apache ServerRoot changed from the + NCSA-compatible <CODE>/usr/local/etc/httpd/</CODE> to + <CODE>/usr/local/apache/</CODE>. This change covers only the + default setting (and the documentation); it is of course possible + to override it using the <A HREF="invoking.html"> -d + <EM>ServerRoot</EM> and -f <EM>httpd.conf</EM></A> switches when + starting apache. + +<DT><STRONG>Improved HTTP/1.1-style Virtual Hosts</STRONG> +<DD>The new <A + HREF="mod/core.html#namevirtualhost"><CODE>NameVirtualHost</CODE></A> + directive is used to list IP address:port pairs on which + HTTP/1.1-style virtual hosting occurs. This is vhosting based on + the <CODE>Host:</CODE> header from the client. Previously this + address was implicitly the same as the "main address" of the + machine, and this caused no end of problems for users, and was not + powerful enough. Please see the <A + HREF="vhosts/index.html">Apache Virtual Host documentation</A> for + further details on configuration. + +<DT><STRONG><CODE>Include</CODE> directive</STRONG> +<DD>The <A HREF="mod/core.html#include" ><CODE>Include</CODE></A> + directive includes other config files immediately at that point in + parsing. + +<DT><STRONG>-S command line option for debugging vhost setup</STRONG> +<DD>If Apache is invoked with the <CODE>-S</CODE> command line option + it will dump out information regarding how it parsed the + <CODE>VirtualHost</CODE> sections. This is useful for folks + trying to debug their virtual host configuration. + +</DL> + +<P><HR> + +<H3><A NAME="mod">Module Enhancements</A></H3> + +<DL> +<DT><A HREF="mod/mod_speling.html"><STRONG>NEW - Spelling correction + module</STRONG></A><BR> +<DD>This optional module corrects frequently occurring spelling and + capitalization errors in document names requested from the server. + +<DT><A HREF="mod/mod_setenvif.html"><STRONG>NEW - Conditional setting of + environment variables</STRONG></A><BR> +<DD>The addition of + <A HREF="mod/mod_setenvif.html#SetEnvIf"> + <CODE>SetEnvIf</CODE></A> and + <A HREF="mod/mod_setenvif.html#SetEnvIfNoCase"> + <CODE>SetEnvIfNoCase</CODE></A>. These allow you to set + environment variables for server and CGI use based upon attributes + of the request. + +<DT><STRONG><A HREF="mod/mod_mime_magic.html">NEW - "Magic" +MIME-typing</A></STRONG> +<DD>The optional <CODE>mod_mime_magic</CODE> has been + added. It uses "magic numbers" and other hints from a file's + contents to figure out what the contents are. It then uses this + information to set the file's media type, if it cannot be + determined by the file's extension. + +<DT><STRONG><A HREF="mod/mod_unique_id.html">NEW - Unique Request + Identifiers</A></STRONG> +<DD><A HREF="mod/mod_unique_id.html">mod_unique_id</A> can be included + to generate a unique identifier that distinguishes a hit from + every other hit. ("Unique" has some restrictions on it.) The + identifier is available in the environment variable + <CODE>UNIQUE_ID</CODE>. + +<DT><STRONG>mod_proxy enhancements:</STRONG> +<UL> +<LI>Easier and safer authentification for ftp proxy logins: + When no ftp user name and/or password is specified in the + URL, but the destination ftp server requires one, apache now + returns a "[401] Authorization Required" status. This status code + usually makes the client browser pop up an "Enter user name and + password" dialog, and the request is retried with the given user + authentification. That is slightly more secure than specifying + the authentication information as part of the request URL, + where it could be logged in plaintext by older proxy servers. +<LI>The new <SAMP>AllowCONNECT</SAMP> directive allows configuration + of the port numbers to which the proxy CONNECT method may connect. + That allows proxying to https://some.server:8443/ which resulted + in an error message prior to Apache version 1.3.2. +<LI>The proxy now supports the HTTP/1.1 "Via:" header as specified in + RFC2068. The new + <A HREF="mod/mod_proxy.html#proxyvia"><CODE>ProxyVia</CODE></A> + directive allows switching "Via:" support off or on, or + suppressing outgoing "Via:" header lines altogether for privacy + reasons. +<LI>The "Max-Forwards:" TRACE header specified in HTTP/1.1 is now + supported. With it, you can trace the path of a request along a + chain of proxies (if they, too, support it). +<LI><A + HREF="mod/mod_proxy.html#noproxy"><CODE>NoProxy</CODE></A> and <A + HREF="mod/mod_proxy.html#proxydomain"><CODE>ProxyDomain</CODE></A> + directives added to proxy, useful for intranets. +<LI>New <CODE><A HREF="mod/mod_proxy.html#proxypassreverse"> + ProxyPassReverse</A></CODE> directive. It lets Apache adjust the + URL in the <TT>Location</TT> header on HTTP redirect + responses. +<LI>Easier navigation in ftp server directory trees. +</UL> + +<DT><A HREF="mod/mod_include.html#flowctrl"><STRONG>Enhanced + <CODE>mod_include</CODE> string comparisons</STRONG></A><BR> +<DD>The string-based server-side include (SSI) flow-control directives + now include comparison for less-than (<), less-than-or-equal + (<=), greater-than (>), and greater-than-or-equal (>=). + Previously comparisons could only be made for equality or + inequality. + +<DT><STRONG>ServerRoot relative auth filenames</STRONG> +<DD>Auth filenames for the various authentication modules are now + treated as relative to the ServerRoot if they are not full paths. + +<DT><A HREF="mod/mod_autoindex.html"><STRONG>Enhancements to directory + indexing:</STRONG></A> + +<DD><UL> + <LI><STRONG>Code split:</STRONG>The <CODE>mod_dir</CODE> module has + been split in two, with <A + HREF="mod/mod_dir.html">mod_dir</A> handling directory index + files, and <A HREF="mod/mod_autoindex.html">mod_autoindex</A> + creating directory listings. Thus allowing folks to remove the + indexing function from critical servers. + + <LI><STRONG>Sortable:</STRONG> Clicking on a column title will now sort + the listing in order by the values in that column. This feature can + be disabled using the <CODE>SuppressColumnSorting</CODE> <A + HREF="mod/mod_autoindex.html#indexoptions">IndexOptions</A> + keyword. + + <LI><A HREF="mod/mod_autoindex.html#indexoptions"> + <CODE><STRONG>SuppressHTMLPreamble</STRONG></CODE></A> can be used if + your README.html file includes its own HTML header. + + <LI><STRONG><CODE>IconHeight</CODE> and <CODE>IconWidth</CODE></STRONG> let + you set + height and width attributes to the <CODE><IMG></CODE> tag in + directory listings. + + <LI>The <A HREF="mod/mod_autoindex.html#fancyindexing" + ><SAMP>FancyIndexing</SAMP></A> directive now correctly has + the same impact as <SAMP>IndexOptions FancyIndexing</SAMP> + without replacing the effect of any existing <SAMP>IndexOptions</SAMP> + directive. + + </UL> + +<DT><STRONG>Less Buffering of CGI Script Output</STRONG> +<DD>In previous versions of Apache, the output from CGI scripts would + be internally buffered by the server, and wouldn't be forwarded to + the client until either the buffers were full or the CGI script + completed. As of Apache 1.3, the buffer to the client is flushed + any time it contains something and the server is waiting for more + information from the script. This allows CGI script to provide + partial status reports during long processing operations. + + +<DT><STRONG><A HREF="mod/mod_alias.html">Regular Expression support for + <CODE>Alias</CODE> and <CODE>Redirect</CODE></A></STRONG> +<DD>New <A HREF="mod/mod_alias.html#aliasmatch"><CODE>AliasMatch</CODE></A>, + <A HREF="mod/mod_alias.html#scriptaliasmatch" + ><CODE>ScriptAliasMatch</CODE></A>, and + <A HREF="mod/mod_alias.html#redirectmatch"><CODE>RedirectMatch</CODE></A> + directives allow for the use of regular expression matching. + Additionally, new + <A HREF="mod/core.html#directorymatch" + ><CODE><DirectoryMatch></CODE></A>, + <A HREF="mod/core.html#locationmatch" + ><CODE><LocationMatch></CODE></A>, + and + <A HREF="mod/core.html#filesmatch"><CODE><FilesMatch></CODE></A> + sections provide a new syntax for regular expression sectioning. + +<DT><STRONG><A + HREF="mod/mod_info.html#addmoduleinfo"><CODE>AddModuleInfo</CODE></A> + directive added to <A + HREF="mod/mod_info.html">mod_info</A></STRONG> +<DD>Allows additional information to be listed along with a specified + module. + +<DT><STRONG>Absence of any <CODE>TransferLog</CODE> disables + logging</STRONG> +<DD>If no <A HREF="mod/mod_log_config.html#transferlog" + ><CODE>TransferLog</CODE></A> directive is given then no log is + written. This supports co-existence with other logging modules. + +<DT><STRONG>Ability to name logging formats</STRONG> +<DD>The <A + HREF="mod/mod_log_config.html#logformat"><CODE>LogFormat</CODE></A> + directive has been enhanced to allow you to give nicknames to + specific logging formats. You can then use these nicknames in + other <CODE>LogFormat</CODE> and <A + HREF="mod/mod_log_config.html#customlog" + ><CODE>CustomLog</CODE></A> directives, rather than having to + spell out the complete log format string each time. + +<DT><STRONG>mod_cern_meta configurable per-directory</STRONG> +<DD><A HREF="mod/mod_cern_meta.html">mod_cern_meta</A> is now + configurable on a per-directory basis. + +<DT><STRONG>New map types for + <A HREF="mod/mod_rewrite.html#RewriteMap"><CODE>RewriteMap</CODE></A> + directive</STRONG> +<DD>The new map types `Randomized Plain Text' and `Internal Function' + were added to the <CODE>RewriteMap</CODE> directive of + mod_rewrite. They provide two new features: First, you now can + randomly choose a sub-value from a value which was looked-up in a + rewriting map (which is useful when choosing between backend + servers in a Reverse Proxy situation). Second, you now can + translate URL parts to fixed (upper or lower) case (which is + useful when doing mass virtual hosting by the help of + mod_rewrite). + +<DT><STRONG>CIDR and Netmask access control</STRONG> +<DD><A HREF="mod/mod_access.html">mod_access</A> directives now + support CIDR (Classless Inter-Domain Routing) style prefixes, and + netmasks for greater control over IP access lists. + +</DL> +<P><HR> + +<H3><A NAME="api">API Additions and Changes</A></H3> + +<P>For all those module writers and code hackers: + +<DL> +<DT><STRONG><CODE>child_init</CODE></STRONG> +<DD>A new phase for Apache's API is called once per "heavy-weight process," + before any requests are handled. This allows the module to set up + anything that need to be done once per processes. For example, + connections to databases. + +<DT><STRONG><CODE>child_exit</CODE></STRONG> +<DD>A new phase called once per "heavy-weight process," when it is + terminating. Note that it can't be called in some fatal cases (such + as segfaults and kill -9). The <CODE>child_init</CODE> and + <CODE>child_exit</CODE> functions are passed a pool whose lifetime is + the same as the lifetime of the child (modulo completely fatal + events in which apache has no hope of recovering). In contrast, + the module <CODE>init</CODE> function is passed a pool whose lifetime + ends when the parent exits or restarts. + +<DT><STRONG><CODE>child_terminate</CODE></STRONG> +<DD>Used in the child to indicate the child should exit after finishing + the current request. + +<DT><STRONG><CODE>register_other_child</CODE></STRONG> +<DD>See <CODE>http_main.h</CODE>. This is used in the parent to register + a child for monitoring. The parent will report status to a supplied + callback function. This allows modules to create their own children + which are monitored along with the httpd children. + +<DT><STRONG><CODE>piped_log</CODE></STRONG> +<DD>See <CODE>http_log.h</CODE>. This API provides the common code for + implementing piped logs. In particular it implements a reliable piped + log on architectures supporting it (<EM>i.e.</EM>, Unix at the moment). + +<DT><STRONG>scoreboard format changed</STRONG> +<DD>The scoreboard format is quite different. It is considered a + "private" interface in general, so it's only mentioned here as an FYI. + +<DT><STRONG><CODE>set_last_modified</CODE> split into three</STRONG> +<DD>The old function <CODE>set_last_modified</CODE> performed multiple + jobs including the setting of the <CODE>Last-Modified</CODE> header, the + <CODE>ETag</CODE> header, and processing conditional requests (such as + IMS). These functions have been split into three functions: + <CODE>set_last_modified</CODE>, <CODE>set_etag</CODE>, and + <CODE>meets_conditions</CODE>. The field <CODE>mtime</CODE> has been + added to <CODE>request_rec</CODE> to facilitate + <CODE>meets_conditions</CODE>. + +<DT><STRONG>New error logging function: <CODE>ap_log_error</CODE></STRONG> +<DD>All old logging functions are deprecated, we are in the process of + replacing them with a single function called <CODE>ap_log_error</CODE>. + This is still a work in progress. + +<DT><STRONG><CODE>set_file_slot</CODE> for config parsing</STRONG> +<DD>The <CODE>set_file_slot</CODE> routine provides a standard routine that + prepends ServerRoot to non-absolute paths. + +<DT><STRONG><CODE>post_read_request</CODE> module API</STRONG> +<DD>This request phase occurs immediately after reading the request (headers), + and immediately after creating an internal redirect. It is most useful + for setting environment variables to affect future phases. + +<DT><STRONG><CODE>psocket</CODE>, and <CODE>popendir</CODE></STRONG> +<DD>The <CODE>psocket</CODE> and <CODE>pclosesocket</CODE> functions allow + for race-condition free socket creation with resource tracking. + Similarly <CODE>popendir</CODE> and <CODE>pclosedir</CODE> protect + directory reading. + +<DT><STRONG><CODE>is_initial_req</CODE></STRONG> +<DD>Test if the request is the initial request (<EM>i.e.</EM>, the one + coming from the client). + +<DT><STRONG><CODE>kill_only_once</CODE></STRONG> +<DD>An option to <CODE>ap_spawn_child</CODE> functions which prevents Apache + from aggressively trying to kill off the child. + +<DT><STRONG><CODE>alloc debugging code</CODE></STRONG> +<DD>Defining <CODE>ALLOC_DEBUG</CODE> provides a rudimentary memory + debugger which can be used on live servers with low impact -- + it sets all allocated and freed memory bytes to 0xa5. Defining + <CODE>ALLOC_USE_MALLOC</CODE> will cause the alloc code to use + <CODE>malloc()</CODE> and <CODE>free()</CODE> for each object. This + is far more expensive and should only be used for testing with tools + such as Electric Fence and Purify. See <CODE>main/alloc.c</CODE> + for more details. + +<DT><STRONG><CODE>ap_cpystrn</CODE></STRONG> +<DD>The new <CODE>strncpy</CODE> "lookalike", with slightly different + semantics is much faster than <CODE>strncpy</CODE> because it + doesn't have to zero-fill the entire buffer. + +<DT><STRONG><CODE>table_addn</CODE>, <CODE>table_setn</CODE>, + <CODE>table_mergen</CODE></STRONG> +<DD>These new functions do <STRONG>not</STRONG> call <CODE>pstrdup</CODE> + on their arguments. This provides for big speedups. There is + also some debugging support to ensure code uses them properly. + See <CODE>src/CHANGES</CODE> for more information. + +<DT><STRONG><CODE>construct_url</CODE></STRONG> +<DD>The function prototype for this changed from taking a + <CODE>server_rec *</CODE> to taking a <CODE>request_rec *</CODE>. + +<DT><STRONG><CODE>get_server_name</CODE>, <CODE>get_server_port</CODE></STRONG> +<DD>These are wrappers which deal with the + <A HREF="mod/core.html#usecanonicalname">UseCanonicalName</A> directive + when retrieving the server name and port for a request. + +<DT><STRONG>Change to prototype for <CODE>ap_bspawn_child</CODE> and + <CODE>ap_call_exec</CODE></STRONG> +<DD>Added a <CODE>child_info *</CODE> to <CODE>spawn</CODE> function + (as passed to <CODE>ap_bspawn_child</CODE>) and to + <CODE>ap_call_exec</CODE> to allow children to work correctly on Win32. + We also cleaned up the nomenclature a bit, replacing + <CODE>spawn_child_err</CODE> with simply + <CODE>ap_spawn_child</CODE> and <CODE>spawn_child_err_buff</CODE> + with simply <CODE>ap_bspawn_child</CODE>. + +<DT><STRONG><CODE>ap_add_version_component()</CODE></STRONG> +<DD>This API function allows for modules to add their own additional + server tokens which are printed on the on the <CODE>Server:</CODE> + header line. Previous 1.3beta versions had used a + <CODE>SERVER_SUBVERSION</CODE> compile-time <CODE>#define</CODE> + to perform this function. Whether the tokens are actually displayed + is controlled by the new <CODE>ServerTokens</CODE> directive. + +</DL> + +<P><HR> + +<H3><A NAME="misc">Miscellaneous Enhancements</A></H3> + +<DL> +<DT><STRONG><A HREF="ebcdic.html">Port to EBCDIC mainframe machine + running BS2000/OSD</A></STRONG> +<DD>As a premiere, this version of Apache comes with a beta version of + a port to a mainframe machine which uses the EBCDIC character set + as its native codeset (It is the SIEMENS NIXDORF family of + mainframes running the BS2000/OSD operating system on a IBM/390 + compatible processor This mainframe OS nowadays features a + SVR4-like POSIX subsystem). + +<DT><STRONG><A HREF="mod/core.html#accessfilename"><CODE>AccessFileName</CODE> + Enhancement</A></STRONG> +<DD>The <CODE>AccessFileName</CODE> directive can now take more than + one filename. This lets sites serving pages from network file + systems and more than one Apache web server, configure access + based on the server through which shared pages are being served. + +<DT><STRONG><CODE>HostNameLookups</CODE> now defaults to "Off"</STRONG> +<DD>The <A + HREF="mod/core.html#hostnamelookups"><CODE>HostNameLookups</CODE></A> + directive now defaults to "Off". This means that, unless explicitly + turned on, the server will not resolve IP addresses into names. This + was done to spare the Internet from unnecessary DNS traffic. + +<DT><STRONG>Double-Reverse DNS enforced</STRONG> +<DD>The <A + HREF="mod/core.html#hostnamelookups"><CODE>HostnameLookups</CODE></A> + directive now supports double-reverse DNS. (Known as + <EM>PARANOID</EM> in the terminology of tcp_wrappers.) An IP + address passes a double-reverse DNS test if the forward map of the + reverse map includes the original IP. Regardless of the + HostnameLookups setting, <A + HREF="mod/mod_access.html">mod_access</A> access lists using DNS + names <STRONG>require</STRONG> all names to pass a double-reverse + DNS test. (Prior versions of Apache required a compile-time + switch to enable double-reverse DNS.) + +<DT><STRONG>LogLevel and syslog support</STRONG> +<DD>Apache now has <A HREF="mod/core.html#loglevel">configurable error + logging levels</A> and supports <A + HREF="mod/core.html#errorlog">error logging via syslogd(8)</A>. + +<DT><STRONG>Detaching from stdin/out/err</STRONG> +<DD>On boot Apache will now detach from stdin, stdout, and stderr. It + does not detach from stderr until it has successfully read the + config files. So you will see errors in the config file. This + should make it easier to start Apache via rsh or crontab. + +<DT><STRONG>Year-2000 Improvements</STRONG> +<DD>The default <CODE>timefmt</CODE> string used by <A + HREF="mod/mod_include.html"><CODE>mod_include</CODE></A> has been + modified to display the year using four digits rather than the + two-digit format used previously. The <A + HREF="mod/mod_autoindex.html"><CODE>mod_autoindex</CODE></A> + module has also been modified to display years using four digits + in FancyIndexed directory listings. + +<DT><STRONG>Common routines Moving to a Separate Library</STRONG> +<DD>There are a number of functions and routines that have been + developed for the Apache project that supplement or supersede + library routines that differ from one operating system to another. + While most of these are used only by the Apache server itself, + some are referenced by supporting applications (such as + <CODE>htdigest</CODE>), and these other applications would fail to + build because the routines were built only into the server. These + routines are now being migrated to a separate subdirectory and + library so they can be used by other applications than just the + server. See the <CODE>src/ap/</CODE> subdirectory. + +<DT><STRONG>New <CODE><A HREF="mod/core.html#serversignature"> + ServerSignature</A></CODE> directive</STRONG> +<DD>This directive optionally adds a line containing the server + version and virtual host name to server-generated pages (error + documents, ftp directory listings, mod_info output <EM>etc.</EM>). This + makes it easier for users to tell which server produced the error + message, especially in a proxy chain (often found in intranet + environments). + +<DT><STRONG>New <CODE><A HREF="mod/core.html#usecanonicalname"> + UseCanonicalName</A></CODE> directive</STRONG> +<DD>This directive gives control over how Apache creates + self-referential URLs. Previously Apache would always use the <A + HREF="mod/core.html#servername"> ServerName</A> and <A + HREF="mod/core.html#port">Port</A> directives to construct a + "canonical" name for the server. With <CODE>UseCanonicalName + off</CODE> Apache will use the hostname and port supplied by the + client, if available. + +<DT><STRONG><CODE>SERVER_VERSION</CODE> definition abstracted, and server + build date added</STRONG> +<DD>In earlier versions, the Apache server version was available to + modules through the <CODE>#define</CODE>d value for + <CODE>SERVER_VERSION</CODE>. In order to keep this value + consistent when modules and the core server are compiled at + different times, this information is now available through the + core API routine <CODE>ap_get_server_version()</CODE>. The use of + the <CODE>SERVER_VERSION</CODE> symbol is deprecated. Also, + <CODE>ap_get_server_built()</CODE> returns a string representing + the time the core server was linked. + +<DT><A HREF="mod/core.html#servertokens"><STRONG>Including the operating + system in the server identity</STRONG></A><BR> +<DD>A new directive, <CODE>ServerTokens</CODE>, allows the Webmaster + to change the value of the <CODE>Server</CODE> response header + field which is sent back to clients. The <CODE>ServerTokens</CODE> + directive controls whether the server will include a non-specific + note in the server identity about the type of operating system on + which the server is running as well as included module information. + As of Apache 1.3, this additional information is included by default. + +</DL> + +<HR> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> + +<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/sections.html b/usr.sbin/httpd/htdocs/manual/sections.html new file mode 100644 index 00000000000..ddf041c70e2 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/sections.html @@ -0,0 +1,180 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>How Directory, Location and Files sections work</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">How Directory, Location and Files sections work</H1> + +The sections <A +HREF="mod/core.html#directory"><CODE><Directory></CODE></A>, <A +HREF="mod/core.html#location"><CODE><Location></CODE></A> and <A +HREF="mod/core.html#files"><CODE><Files></CODE></A> can contain +directives which only apply to specified directories, URLs or files +respectively. Also htaccess files can be used inside a directory to +apply directives to that directory. This document explains how these +different sections differ and how they relate to each other when +Apache decides which directives apply for a particular directory or +request URL. + +<H2>Directives allowed in the sections</H2> + +Everything that is syntactically allowed in +<CODE><Directory></CODE> is also allowed in +<CODE><Location></CODE> (except a sub-<CODE><Files></CODE> +section). Semantically however some things, and the most +notable are <CODE>AllowOverride</CODE> and the two options +<CODE>FollowSymLinks</CODE> and <CODE>SymLinksIfOwnerMatch</CODE>, +make no sense in <CODE><Location></CODE>. The same for +<CODE><Files></CODE> -- syntactically everything is fine, but +semantically some things are different. + +<H2>How the sections are merged</H2> + +The order of merging is: + +<OL> + +<LI> + + <CODE><Directory></CODE> (except regular expressions) and + .htaccess done simultaneously (with .htaccess overriding + <CODE><Directory></CODE>) + +</LI> + +<LI> + <CODE><DirectoryMatch></CODE>, and + <CODE><Directory></CODE> with regular expressions + +</LI> + + <LI><CODE><Files></CODE> and <CODE><FilesMatch></CODE> done + simultaneously + </LI> + + <LI><CODE><Location></CODE> and <CODE><LocationMatch></CODE> done + simultaneously + </LI> + +</OL> + +Apart from <CODE><Directory></CODE>, each group is processed in +the order that they appear in the configuration +files. <CODE><Directory></CODE> (group 1 above) is processed in +the order shortest directory component to longest. If multiple +<CODE><Directory></CODE> sections apply to the same directory +they they are processed in the configuration file order. The +configuration files are read in the order httpd.conf, srm.conf and +access.conf. Configurations included via the <CODE>Include</CODE> +directive will be treated as if they where inside the including file +at the location of the <CODE>Include</CODE> directive. + +<P> + +Sections inside <CODE><VirtualHost></CODE> sections are applied +<EM>after</EM> the corresponding sections outside the virtual host +definition. This allows virtual hosts to override the main server +configuration. (Note: this only works correctly from 1.2.2 and 1.3a2 +onwards. Before those releases sections inside virtual hosts were +applied <EM>before</EM> the main server). + +<H2>Notes about using sections</H2> + +The general guidelines are: + +<P> + +<UL> +<LI> + If you are attempting to match objects at the filesystem level + then you must use <CODE><Directory></CODE> and/or + <CODE><Files></CODE>. +</LI> + +<LI> + If you are attempting to match objects at the URL level then you + must use <CODE><Location></CODE> +</LI> +</UL> + +But a notable exception is: + +<UL> +<LI> + proxy control is done via <CODE><Directory></CODE>. This is + a legacy mistake because the proxy existed prior to + <CODE><Location></CODE>. A future version of the config + language should probably switch this to + <CODE><Location></CODE>. +</LI> +</UL> + +<P> +Note about .htaccess parsing: +</P> +<UL> +<LI> + Modifying .htaccess parsing during Location doesn't do + anything because .htaccess parsing has already occurred. +</UL> + +<P> +<CODE><Location></CODE> and symbolic links: +</P> +<UL> +<LI> + It is not possible to use "<CODE>Options FollowSymLinks</CODE>" + or "<CODE>Options SymLinksIfOwnerMatch</CODE>" inside a + <CODE><Location></CODE>/<CODE><LocationMatch></CODE> section + (the options are simply ignored). + Using the options in question is only possible inside a + <CODE><Directory></CODE> section (or a <CODE>.htaccess</CODE> file). +</UL> + +<P> +<CODE><Files></CODE> and <CODE>Options</CODE>: +</P> +<UL> +<LI> + Apache won't check for it, but using an <CODE>Options</CODE> + directive inside a <CODE><Files></CODE> section has no effect. +</UL> + +<P> +Another note: +</P> + +<UL> +<LI> + There is actually a + <CODE><Location></CODE>/<CODE><LocationMatch></CODE> + sequence performed just before the name translation phase (where + <CODE>Aliases</CODE> and <CODE>DocumentRoots</CODE> are used to + map URLs to filenames). The results of this sequence are + completely thrown away after the translation has completed. +</LI> +</UL> + +<HR> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> + +<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> + +</BODY></HTML> diff --git a/usr.sbin/httpd/htdocs/manual/sourcereorg.html b/usr.sbin/httpd/htdocs/manual/sourcereorg.html new file mode 100644 index 00000000000..6c47ae972df --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/sourcereorg.html @@ -0,0 +1,312 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Source Re-organisation</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Source Re-organisation</H1> + +As of 1.3, the Apache source directories have been re-organised. This +re-organisation is designed to simplify the directory structure, +make it easier to add additional modules, and to give module authors +a way of specifying compile time options or distribute binary +modules. + +<H2>Summary of Changes</H2> + +The source changes are: +<UL> + <LI>The non-module source files have moved from <CODE>src</CODE> into + <CODE>src/main</CODE> + </LI> + <LI>The module source files previously in <CODE>src</CODE> have moved + to <CODE>src/modules/standard</CODE> + </LI> + <LI>The <CODE>support</CODE> directory is now in <CODE>src/support</CODE> + </LI> + <LI>The existing symbol names used for global Apache function and variable + identifiers have been renamed in the source. This way namespace conflicts + are avoided when linking Apache with third-party libraries. See the file + <CODE>src/include/compat.h</CODE> both for the list of renamed symbol + names and for a way to get source backward compatibility in existing + third-party module sources. + </LI> +</UL> + +In addition, the following enhancements have been made: + +<UL> + <LI>OS abstractions can be added in the <CODE>src/os</CODE> directory. + Currently this contains information for unix, OS/2 and Windows 32 + platforms. + </LI> + <LI><CODE>Configuration</CODE> syntax has been simplified for adding new + modules. Users no longer need to enter the module's structure name. + In addition, new modules can be located anywhere on the + file system, or typically in new or existing directories under + <CODE>src/modules</CODE>. + </LI> + <LI>Module authors can give simpler instructions for adding their modules + to Apache compilation. They can also now provide compile time information + required by <CODE>Configure</CODE>, such as additional libraries + required. + </LI> + <LI>Module authors can distribute pre-compiled (.a or .o) versions of their + modules if required, along with a "module definition file" which + contains the information required by <CODE>Configure</CODE>. + </LI> + <LI>All the sub-directories (main, modules/* and os/*) are built as + libraries. + </LI> + <LI>The new Apache Autoconf-style Interface (APACI) script named + <CODE>configure</CODE> replaced the old top-level <CODE>Makefile</CODE> + and <CODE>src/helpers/InstallApache</CODE> stuff. + </LI> +</UL> + +<H2>Adding Modules</H2> + +Modules are added to Apache by adding a reference to them in +<CODE>src/Configuration</CODE> then running <CODE>Configure</CODE> and +<CODE>make</CODE>. In earlier version of Apache before 1.3, the +line added to Configuration looked like this: + +<PRE> + Module status_module mod_status.o +</PRE> + +From 1.3 onwards, the <CODE>AddModule</CODE> line should be used +instead, and typically looks like this: + +<PRE> + AddModule modules/standard/mod_status.o +</PRE> + +The argument to AddModule is the path, relative to <CODE>src</CODE>, to +the module file's source or object file. + +<P> + +Normally when adding a module you should follow the instructions of +the module author. However if the module comes as a single source +file, say mod_foo.c, then the recommended way to add the module to +Apache is as follows: + +<UL> + <LI>Put <CODE>mod_foo.c</CODE> into the directory + <CODE>src/modules/extra</CODE> + </LI> + <LI>Go to the <CODE>src</CODE> directory and add the following line + to <CODE>Configuration</CODE><BR> + <CODE>AddModule modules/extra/mod_foo.o</CODE> + </LI> + <LI>Run <CODE>./Configure</CODE></LI> + <LI>Run <CODE>make</CODE></LI> +</UL> + +<H2>New Facilities for Module Authors</H2> + +In previous releases of Apache, new modules were added to the +<CODE>src</CODE> directory, and if the module required any additional +compilation options (such as libraries) they would have to be added +to <CODE>Configuration</CODE>. Also the user would have to be +told the module's structure name to add on the Module line +of <CODE>Configuration</CODE>. + +<P> + +From Apache 1.3 onwards, module authors can make use of these new features: + +<UL> + <LI>Simplified <CODE>Configuration</CODE> command AddModule which only + requires a path to the module source or object file + </LI> + <LI>If the module requires compile time options (such as extra + libraries) these can be specified in the module file source + or an external "module definition file". + </LI> + <LI>If a module is distributed as binary (.o or .a) then an external + "module definition file" can also be distributed which gives + the information Configure needs to add the module, such as extra + libraries and the module's structure name. + <LI>Modules can be installed anywhere on the file system, although a directory + under <CODE>src/modules</CODE> is recommended. + </LI> + <LI>If the module is in its own directory, Apache can automatically + create a Makefile to build the module given a file containing + the module's dependencies. + </LI> + <LI>For building a third-party module <STRONG>outside</STRONG> the + Apache source tree the new <CODE>apxs</CODE> support tool can be + used to compile the module into a <A HREF="dso.html">dynamic + shared object (DSO)</A>, install it into the existing Apache + installation and optionally activating it in the Apache + <CODE>httpd.conf</CODE> file. The only requirement is that + Apache has DSO-support for the used platform and the module + <CODE><A HREF="mod/mod_so.html">mod_so</A></CODE> was built into + the server binary <CODE>httpd</CODE>. + </LI> +</UL> + +The rest of this document shows how to package modules for Apache 1.3 +and later and what to tell end-users of the module. + +<H3>Building a simple source distribution</H3> + +Consider a simple add-on module, distributed as a single file. For +example, say it is called mod_demo.c. The archive for this module +should consist of two files, in a suitable directory name. For +example: + +<UL> + <LI>mod_demo/mod_demo.c + <LI>mod_demo/Makefile.tmpl +</UL> + +(Of course end-user instructions, README's, etc can also be supplied +in the archive). The end user should be told to extract this archive +in the <CODE>src/modules</CODE> directory of their Apache source +tree. This will create a new directory +<CODE>src/modules/mod_demo</CODE>. Then they need to add the following +line to the <CODE>Configuration</CODE> file: + +<PRE> + AddModule modules/mod_demo/mod_demo.o +</PRE> + +then run <CODE>Configure</CODE> and <CODE>make</CODE> as normal. + +<P> + +The <CODE>mod_demo/Makefile.tmpl</CODE> should contain the dependencies +of the module source. For example, a simple module which just interfaces to +some standard Apache module API functions might look this this: + +<PRE> + mod_demo.o: mod_demo.c $(INCDIR)/httpd.h $(INCDIR)/http_protocol.h +</PRE> + +When the user runs <CODE>Configure</CODE> Apache will create a full +makefile to build this module. If this module also requires +some additional built-time options to be given, such as libraries, +see the next section. +<P> + +If the module also comes with header files, these can be added to the +archive. If the module consists of multiple source files it can be +built into a library file using a supplied makefile. In this case, +distribute the makefile as <CODE>mod_demo/Makefile</CODE> and <STRONG>do +not</STRONG> include a <CODE>mod_demo/Makefile.tmpl</CODE>. If +<CODE>Configure</CODE> sees a <CODE>Makefile.tmpl</CODE> it assumes it +is safe to overwrite any existing <CODE>Makefile</CODE>. + +<P> + +See the Apache <CODE>src/modules/standard</CODE> for an example of a +module directory where the makefile is created automatically from a +Makefile.tmpl file (note that this directory also shows how to +distribute multiple modules in a single directory). See +<CODE>src/modules/proxy</CODE> and <CODE>src/modules/example</CODE> +for examples of modules built using custom makefiles (to build a +library and an object file, respectively). + +<H3>Adding Compile time Information</H3> + +Apache source files (or module definition files, see below) can +contain information used by <CODE>Configure</CODE> to add compile-time +options such as additional libraries. For example, if mod_demo in the +example above also requires that Apache be linked against a DBM +library, then the following text could be inserted into the mod_demo.c +source: + +<PRE> +/* + * Module definition information - the part between the -START and -END + * lines below is used by Configure. This could be stored in a separate + * instead. + * + * MODULE-DEFINITION-START + * Name: demo_module + * ConfigStart + LIBS="$LIBS $DBM_LIB" + if [ "X$DBM_LIB" != "X" ]; then + echo " + using $DBM_LIB for mod_demo" + fi + * ConfigEnd + * MODULE-DEFINITION-END + */ +</PRE> + +Note that this is contained inside a C language comment to hide it +from the compiler. Anything between the lines which contains +<CODE>MODULE-DEFINITION-START</CODE> and +<CODE>MODULE-DEFINITION-END</CODE> is used by <CODE>Configure</CODE>. +The <CODE>Name:</CODE> line gives the module's structure name. This is +not really necessary in this case since if not present +<CODE>Configure</CODE> will guess at a name based on the filename +(<EM>e.g.</EM>, given "mod_demo" it will remove the leading "mod_" and append +"_module" to get a structure name. This works with all modules +distributed with Apache). + +<P> + +The lines between <CODE>ConfigStart</CODE> and <CODE>ConfigEnd</CODE> +as executed by <CODE>Configure</CODE> and can be used to add +compile-time options and libraries. In this case it adds the DBM +library (from $DBM_LIB) to the standard compilation libraries ($LIB) +and displays a message. + +<P> + +See the default distribution's mod_auth_dbm.c for an example of +an embedded module definition. + +<H3>Module Definition Information for Binary Distribitions</H3> + +If the module is to be distributed as binary (object or library) rather +than source, it is not possible to add the module definition +information to the source file. In this case it can be placed in a +separate file which has the same base name as the object or library +file, but with a <CODE>.module</CODE> extension. So, for example, if +the distributed module object file is mod_demo.o, the module +definition file should be called mod_demo.module. It contains the same +information as above, but does not need to be inside a C comment or +delimited with <CODE>MODULE-DEFINITION-START</CODE> <EM>etc.</EM> For example: + +<PRE> +Name: demo_module +ConfigStart + LIBS="$LIBS $DBM_LIB" + if [ "X$DBM_LIB" != "X" ]; then + echo " + using $DBM_LIB for mod_demo" + fi +ConfigEnd +</PRE> + +See the default distribution's mod_auth_db.module for an example of +a separate module definition file. + +<HR> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> + +<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/upgrading_to_1_3.html b/usr.sbin/httpd/htdocs/manual/upgrading_to_1_3.html new file mode 100644 index 00000000000..0db2c7c666d --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/upgrading_to_1_3.html @@ -0,0 +1,299 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>Upgrading to 1.3 from 1.2</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Upgrading to 1.3 from 1.2</H1> + +<P>In order to assist folks upgrading we are now going to maintain a +document describing information critical to existing Apache users. Note +that it only lists differences between recent major releases, so +for example, folks using Apache 1.1 or earlier will have to figure out +what changed up to Apache 1.2 before this document can be considered +relevant. Old users could look at the <CODE>src/CHANGES</CODE> file +which tracks code changes. + +<P>These are intended to be brief notes, and you should be able to find +more information in either the <A HREF="new_features_1_3.html">New Features</A> +document, or in the <CODE>src/CHANGES</CODE> file. + +<H3>Compile-Time Configuration Changes</H3> + +<UL> + <LI>The source code has been <A HREF="sourcereorg.html">reorganized</A>, + which affects anyone with custom modules or modifications. But also, + the <CODE>Module</CODE> directive has been changed to the + <CODE>AddModule</CODE> directive. + + <LI>The <CODE>Configuration</CODE> variable <CODE>EXTRA_LFLAGS</CODE> has + been renamed <CODE>EXTRA_LDFLAGS</CODE>. + + <LI>The <CODE>-DMAXIMUM_DNS</CODE> definition has been obsoleted by + changes to <CODE>mod_access</CODE> enforcing double-reverse DNS lookups + when necessary. + + <LI>The <CODE>-DSERVER_SUBVERSION=\"string\"</CODE> compile-time option has + been replaced with the run-time API call + <CODE>ap_add_version_component()</CODE>. Compile-time modification of the + server identity by the configuration scripts is no longer supported. + </LI> + + <LI><CODE>mod_dir</CODE> has been split into two pieces + <CODE><A HREF="mod/mod_autoindex.html">mod_autoindex</A></CODE>, and + <CODE><A HREF="mod/mod_dir.html">mod_dir</A></CODE>. + + <LI><A HREF="mod/mod_browser.html"><CODE>mod_browser</CODE></A> has been + replaced by <A HREF="mod/mod_setenvif.html"><CODE>mod_setenvif</CODE></A>. + + <LI>IRIX systems with untrusted users who can write CGIs which execute + as the same uid as httpd should consider using <CODE>suexec</CODE>, + or adding <CODE>-DUSE_FCNTL_SERIALIZED_ACCEPT</CODE> to + <CODE>EXTRA_CFLAGS</CODE>. This is slower, more information is available + on the <A HREF="misc/perf-tuning.html#serialize">performance tuning + page</A>. There is a mild denial of service attack possible with the + default config, but the default config is an order of magnitude faster. + + <LI><CODE>mod_auth_msql</CODE> has been removed from the distribution. + + <LI>The new Apache Autoconf-style Interface (APACI) was added to + the top-level to provide a real out-of-the-box build and installation + procedure for the complete Apache package. +</UL> + +<H3>Run-Time Configuration Changes</H3> + +<UL> + <LI>As of 1.3.2, <A HREF="mod/mod_expires.html"><CODE>mod_expires</CODE></A> + will add Expires headers to content that does not come from a file + on disk, unless you are using a modification time based setting. + Previously, it would never add an Expires header unless content came + from a file on disk. This could result in Expires headers being added + in places where they were not previously added. + <LI>Standalone <STRONG><SAMP>FancyIndexing</SAMP></STRONG> directives + are now combined with the settings of any <SAMP>IndexOptions</SAMP> + directive already in effect, rather than replacing them. + </LI> + <LI><STRONG><SAMP>AuthName</SAMP> strings will need to be quoted</STRONG> + in <SAMP>.htaccess</SAMP> or server configuration files if they contain + blank characters (like spaces). For example, if you use + an <SAMP>AuthName</SAMP> directive like this: + <P> + <PRE> + AuthName This and That + </PRE> + </P> + you will need to change it to + <P> + <PRE> + AuthName "This and That" + </PRE> + </P> + This change was made for consistency in the config language. + <LI><STRONG>As of Apache 1.3.1, methods listed in <SAMP><Limit></SAMP> + directives must be uppercase.</STRONG> Method names, such as + <SAMP>GET</SAMP>, <SAMP>POST</SAMP>, and <SAMP>PUT</SAMP> are + defined as being case-sensitive. That is, a <SAMP>GET</SAMP> + request is different from a <SAMP>get</SAMP> request. Prior + to Apache 1.3.1, the <SAMP><Limit></SAMP> directive + parser incorrectly treated both of these as being the same. + Apache's built-in method limit processing currently only understands + uppercase method names, so if you've used clauses such as + "<SAMP><Limit Get post></SAMP>" in your configuration + files, you need to correct them to use uppercase names. + <P> + Unrecognised method names in the server configuration files will + result in the server logging an error message and failing to start. + In <SAMP>.htaccess</SAMP> files, unknown methods will cause the + server to log an error to its error log and return an 'Internal + Server Error' page to the client. + </P> + </LI> + <LI><STRONG>The default Apache ServerRoot directory changed</STRONG> + from the NCSA-compatible <SAMP>/usr/local/etc/httpd/</SAMP> to + <SAMP>/usr/local/apache/</SAMP>. This change covers only the default + setting (and the documentation); it is of course possible to override it + using the <EM>-d ServerRoot</EM> and <EM>-f httpd.conf</EM> switches + when starting apache. + + <LI>Folks using HTTP/1.1-style virtual hosting will need to list the + ip:port pairs that are supposed to have HTTP/1.1-style virtual hosting + via the <A HREF="mod/core.html#namevirtualhost"><CODE> + NameVirtualHost</CODE></A> directive (one directive per pair). + Previously this support was given implicitly on the "main server + address". Now it has to be explicitly listed so as to avoid many + problems that users had. + Please see the <A HREF="vhosts/index.html">Apache Virtual Host + documentation</A> for further details on configuration. + + <LI>The precedence of virtual hosts has been reversed (applies mainly to + vhosts using HTTP/1.1 Host: headers, and the + <A HREF="mod/core.html#serverpath">ServerPath</A> directive). Now + the earlier vhosts in the file have precedence over the later vhosts. + + <LI><CODE>HostnameLookups</CODE> defaults to Off. + + <LI><STRONG><SAMP>REMOTE_HOST</SAMP> CGI variable changed.</STRONG> + In Apache 1.2 and earlier, the <SAMP>REMOTE_HOST</SAMP> environment + variable made available to CGI scripts was set to either the + full DNS name of the client, or else to the client's IP address + if the name was not known. This behaviour differed from that + specified by the CGI specification, which defines this variable as being + NULL if the name isn't known. In Apache 1.3, we have made this correction. + <SAMP>REMOTE_ADDR</SAMP> always contains the client's IP address, + but <SAMP>REMOTE_HOST</SAMP> is only defined when the server has + been able to determine the client's DNS name. + </LI> + + <LI>The undocumented + <A HREF="mod/mod_access.html"><CODE>mod_access</CODE></A> + syntax "allow user-agents" was removed. The replacement is the + more general "allow from env". + + <LI>When using wildcards in pathnames (such as * and ?) they no longer + match / (slash). That is, they more closely behave how a UNIX shell + behaves. This affects <CODE><Directory></CODE> directives, + for example. + + <LI>If no <CODE>TransferLog</CODE> directive is given then nothing will + be logged. + (Previously it would default to <CODE>logs/access_log</CODE>.) + + <LI>Apache now has <A HREF="mod/core.html#loglevel">configurable error + logging levels</A>, and the default eliminates some messages that + earlier versions always generated. + + <LI>When booting, Apache will now detach itself from stdin, stdout, + and stderr. stderr will not be detached until after the config + files have been read so you will be able to see initial error + messages. After that all errors are logged in the error_log. + This makes it more convenient to start Apache via rsh, ssh, + or crontabs. + + <LI><Files> sections previously could take a full pathname, and + were matched against the full pathnames. This had some + inconsistancies, and was removed. To emulate this older behaviour + use a <Files> section nested inside a <Directory> + section. + + <LI><Location> matching behaviour with respect to slashes has + changed. See the <A HREF="mod/core.html#location"><Location> + documentation</A> for more info. + +</UL> + +<H3>Misc Changes</H3> + +<UL> + <LI><CODE>ServerType inetd</CODE> has been deprecated. It still exists, + but bugs are unlikely to be fixed. + + <LI><CODE>httpd_monitor</CODE> has been deprecated. The replacement is + to use <CODE>mod_status</CODE> and make a request to a URL such as + <CODE>http://myhost/server-status?refresh=10</CODE>. + + <LI> + Apache now provides an effectively unbuffered connection for + CGI scripts. This means that data will be sent to the client + as soon as the CGI pauses or stops output; previously, Apache would + buffer the output up to a fixed buffer size before sending, which + could result in the user viewing an empty page until the CGI finished + or output a complete buffer. It is no longer necessary to use an + "nph-" CGI to get unbuffered output. Given that most CGIs are written + in a language that by default does buffering (<EM>e.g.</EM>, perl) this + shouldn't have a detrimental effect on performance. + + <P>"nph-" CGIs, which formerly provided a direct socket to the client + without any server post-processing, were not fully compatible with + HTTP/1.1 or SSL support. As such they would have had to implement + the transport details, such as encryption or chunking, in order + to work properly in certain situations. Now, the only difference + between nph and non-nph scripts is "non-parsed headers". + + <LI> + <CODE>dbmmanage</CODE> has been overhauled. + +</UL> + +<H3>Third Party Modules</H3> + +<P>The following changes between the 1.2 and 1.3 API may require slight +changes in third party modules not maintained by Apache. + +<UL> + <LI> + To avoid symbol clashes with third-party code compiled into the server, the + general prefix `<CODE>ap_</CODE>' was globally applied to the following + classes of symbols: Apache provided general functions (<EM>e.g.</EM>, + <CODE>ap_cpystrn</CODE>), public API functions (<EM>e.g.</EM>, + <CODE>palloc</CODE>, + <CODE>bgets</CODE>) and private functions which can't be made static + (because of cross-object usage) but should be (<EM>e.g.</EM>, + <CODE>new_connection</CODE>). For backward source compatibility with + Apache 1.2 a new header file named <CODE>compat.h</CODE> was created which + provides defines for the old symbol names. + You'll either have to <CODE>#include compat.h</CODE> or update the API + symbols you use. + </LI> + <LI> + Be sure and examine the <A HREF="sourcereorg.html">source code + reorganization page</A> to see whether any item there affects you. + </LI> + + <LI>Use of <SAMP>SERVER_VERSION</SAMP> definition. If third-party + modules reference the server version string using this symbol, + they should be corrected to obtain it by calling the new API routine + <CODE>const char *ap_get_server_version()</CODE>. + </LI> + + <LI><CODE>ap_construct_url</CODE> prototype change. The second parameter + was previously a <CODE>server_rec</CODE>, it has been changed to + a <CODE>request_rec</CODE>. + + <LI>The <CODE>table</CODE> datatype has been made an opaque type. + Code which assumes a <CODE>table</CODE> is the same as an + <CODE>array_header</CODE> will not compile. This is actually a + change to enforce the API the way it was intended, all versions + of Apache have had a <CODE>table_elts()</CODE> function which + is intended for code which needs to access the elements of + a table. The changes required for this are pretty easy, and + work with all versions of Apache. + + <P>Suppose <CODE>t</CODE> is a table. Whenever code refers to + <CODE>t->elts</CODE>, replace it with something like this: + +<BLOCKQUOTE><PRE> + array_header *arr = table_elts(t); + table_entry *elts = (table_entry *)arr->elts; +</PRE></BLOCKQUOTE> + + Whenever code refers to <CODE>t->nelts</CODE> use + <CODE>arr->nelts</CODE>. Many examples can be found in + the standard modules, search for <CODE>table_elts</CODE>. + </LI> + +</UL> + +<HR> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> + +<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/details.html b/usr.sbin/httpd/htdocs/manual/vhosts/details.html new file mode 100644 index 00000000000..c0c4e6a73b8 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/details.html @@ -0,0 +1,387 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>An In-Depth Discussion of Virtual Host Matching</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">An In-Depth Discussion of Virtual Host Matching</H1> + +<P>The virtual host code was completely rewritten in +<STRONG>Apache 1.3</STRONG>. +This document attempts to explain exactly what Apache does when +deciding what virtual host to serve a hit from. With the help of the +new <A HREF="../mod/core.html#namevirtualhost"><SAMP>NameVirtualHost</SAMP></A> +directive virtual host configuration should be a lot easier and safer +than with versions prior to 1.3. + +<P>If you just want to <CITE>make it work</CITE> without understanding +how, here are <A HREF="examples.html">some examples</A>. + +<H3>Config File Parsing</H3> + +<P>There is a <EM>main_server</EM> which consists of all +the definitions appearing outside of <CODE><VirtualHost></CODE> sections. +There are virtual servers, called <EM>vhosts</EM>, which are defined by +<A HREF="../mod/core.html#virtualhost"><SAMP><VirtualHost></SAMP></A> +sections. + +<P>The directives +<A HREF="../mod/core.html#port"><SAMP>Port</SAMP></A>, +<A HREF="../mod/core.html#servername"><SAMP>ServerName</SAMP></A>, +<A HREF="../mod/core.html#serverpath"><SAMP>ServerPath</SAMP></A>, +and +<A HREF="../mod/core.html#serveralias"><SAMP>ServerAlias</SAMP></A> +can appear anywhere within the definition of +a server. However, each appearance overrides the previous appearance +(within that server). + +<P>The default value of the <CODE>Port</CODE> field for main_server +is 80. The main_server has no default <CODE>ServerPath</CODE>, or +<CODE>ServerAlias</CODE>. The default <CODE>ServerName</CODE> is +deduced from the servers IP address. + +<P>The main_server Port directive has two functions due to legacy +compatibility with NCSA configuration files. One function is +to determine the default network port Apache will bind to. This +default is overridden by the existence of any +<A HREF="../mod/core.html#listen"><CODE>Listen</CODE></A> directives. +The second function is to specify the port number which is used +in absolute URIs during redirects. + +<P>Unlike the main_server, vhost ports <EM>do not</EM> affect what +ports Apache listens for connections on. + +<P>Each address appearing in the <CODE>VirtualHost</CODE> directive +can have an optional port. If the port is unspecified it defaults to +the value of the main_server's most recent <CODE>Port</CODE> statement. +The special port <SAMP>*</SAMP> indicates a wildcard that matches any port. +Collectively the entire set of addresses (including multiple +<SAMP>A</SAMP> record +results from DNS lookups) are called the vhost's <EM>address set</EM>. + +<P>Unless a <A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A> +directive is used for a specific IP address the first vhost with +that address is treated as an IP-based vhost. + +<P>If name-based vhosts should be used a <CODE>NameVirtualHost</CODE> +directive <EM>must</EM> appear with the IP address set to be used for the +name-based vhosts. In other words, you must specify the IP address that +holds the hostname aliases (CNAMEs) for your name-based vhosts via a +<CODE>NameVirtualHost</CODE> directive in your configuration file. + +<P>Multiple <CODE>NameVirtualHost</CODE> directives can be used each +with a set of <CODE>VirtualHost</CODE> directives but only one +<CODE>NameVirtualHost</CODE> directive should be used for each +specific IP:port pair. + +<P>The ordering of <CODE>NameVirtualHost</CODE> and +<CODE>VirtualHost</CODE> directives is not important which makes the +following two examples identical (only the order of the +<CODE>VirtualHost</CODE> directives for <EM>one</EM> address set +is important, see below): + +<PRE> + | + NameVirtualHost 111.22.33.44 | <VirtualHost 111.22.33.44> + <VirtualHost 111.22.33.44> | # server A + # server A | </VirtualHost> + ... | <VirtualHost 111.22.33.55> + </VirtualHost> | # server C + <VirtualHost 111.22.33.44> | ... + # server B | </VirtualHost> + ... | <VirtualHost 111.22.33.44> + </VirtualHost> | # server B + | ... + NameVirtualHost 111.22.33.55 | </VirtualHost> + <VirtualHost 111.22.33.55> | <VirtualHost 111.22.33.55> + # server C | # server D + ... | ... + </VirtualHost> | </VirtualHost> + <VirtualHost 111.22.33.55> | + # server D | NameVirtualHost 111.22.33.44 + ... | NameVirtualHost 111.22.33.55 + </VirtualHost> | + | +</PRE> + +<P>(To aid the readability of your configuration you should prefer the +left variant.) + +<P> After parsing the <CODE>VirtualHost</CODE> directive, the vhost server +is given a default <CODE>Port</CODE> equal to the port assigned to the +first name in its <CODE>VirtualHost</CODE> directive. + +<P>The complete list of names in the <CODE>VirtualHost</CODE> directive +are treated just like a <CODE>ServerAlias</CODE> (but are not overridden by any +<CODE>ServerAlias</CODE> statement) if all names resolve to the same address +set. Note that subsequent <CODE>Port</CODE> statements for this vhost will not +affect the ports assigned in the address set. + +<P>During initialization a list for each IP address +is generated an inserted into an hash table. If the IP address is +used in a <CODE>NameVirtualHost</CODE> directive the list contains +all name-based vhosts for the given IP address. If there are no +vhosts defined for that address the <CODE>NameVirtualHost</CODE> directive +is ignored and an error is logged. For an IP-based vhost the list in the +hash table is empty. + +<P>Due to a fast hashing function the overhead of hashing an IP address +during a request is minimal and almost not existent. Additionally +the table is optimized for IP addresses which vary in the last octet. + +<P>For every vhost various default values are set. In particular: + +<OL> +<LI>If a vhost has no + <A HREF="../mod/core.html#serveradmin"><CODE>ServerAdmin</CODE></A>, + <A HREF="../mod/core.html#resourceconfig"><CODE>ResourceConfig</CODE></A>, + <A HREF="../mod/core.html#accessconfig"><CODE>AccessConfig</CODE></A>, + <A HREF="../mod/core.html#timeout"><CODE>Timeout</CODE></A>, + <A HREF="../mod/core.html#keepalivetimeout" + ><CODE>KeepAliveTimeout</CODE></A>, + <A HREF="../mod/core.html#keepalive"><CODE>KeepAlive</CODE></A>, + <A HREF="../mod/core.html#maxkeepaliverequests" + ><CODE>MaxKeepAliveRequests</CODE></A>, + or + <A HREF="../mod/core.html#sendbuffersize"><CODE>SendBufferSize</CODE></A> + directive then the respective value is + inherited from the main_server. (That is, inherited from whatever + the final setting of that value is in the main_server.) + +<LI>The "lookup defaults" that define the default directory + permissions + for a vhost are merged with those of the main_server. This includes + any per-directory configuration information for any module. + +<LI>The per-server configs for each module from the main_server are + merged into the vhost server. +</OL> + +Essentially, the main_server is treated as "defaults" or a +"base" on which to build each vhost. +But the positioning of these main_server +definitions in the config file is largely irrelevant -- the entire +config of the main_server has been parsed when this final merging occurs. +So even if a main_server definition appears after a vhost definition +it might affect the vhost definition. + +<P> If the main_server has no <CODE>ServerName</CODE> at this point, +then the hostname of the machine that httpd is running on is used +instead. We will call the <EM>main_server address set</EM> those IP +addresses returned by a DNS lookup on the <CODE>ServerName</CODE> of +the main_server. + +<P> For any undefined <CODE>ServerName</CODE> fields, a name-based vhost +defaults to the address given first in the <CODE>VirtualHost</CODE> +statement defining the vhost. + +<P>Any vhost that includes the magic <SAMP>_default_</SAMP> wildcard +is given the same <CODE>ServerName</CODE> as the main_server. + + +<H3>Virtual Host Matching</H3> + +<P>The server determines which vhost to use for a request as follows: + +<H4>Hash table lookup</H4> + +<P>When the connection is first made by a client, the IP address to +which the client connected is looked up in the internal IP hash table. + +<P>If the lookup fails (the IP address wasn't found) the request is +served from the <SAMP>_default_</SAMP> vhost if there is such a vhost +for the port to which the client sent the request. If there is no +matching <SAMP>_default_</SAMP> vhost the request is served from the +main_server. + +<P>If the lookup succeeded (a corresponding list for the IP address was +found) the next step is to decide if we have to deal with an IP-based +or a name-base vhost. + +<H4>IP-based vhost</H4> + +<P>If the entry we found has an empty name list then we have found an +IP-based vhost, no further actions are performed and the request is +served from that vhost. + +<H4>Name-based vhost</H4> + +<P>If the entry corresponds to a name-based vhost the name list contains +one or more vhost structures. This list contains the vhosts in the same +order as the <CODE>VirtualHost</CODE> directives appear in the config +file. + +<P>The first vhost on this list (the first vhost in the config file with +the specified IP address) has the highest priority and catches any request +to an unknown server name or a request without a <CODE>Host:</CODE> +header field. + +<P>If the client provided a <CODE>Host:</CODE> header field the list is +searched for a matching vhost and the first hit on a <CODE>ServerName</CODE> +or <CODE>ServerAlias</CODE> is taken and the request is served from +that vhost. A <CODE>Host:</CODE> header field can contain a port number, but +Apache always matches against the real port to which the client sent +the request. + +<P>If the client submitted a HTTP/1.0 request without <CODE>Host:</CODE> +header field we don't know to what server the client tried to connect and +any existing <CODE>ServerPath</CODE> is matched against the URI +from the request. The first matching path on the list is used and the +request is served from that vhost. + +<P>If no matching vhost could be found the request is served from the +first vhost with a matching port number that is on the list for the IP +to which the client connected (as already mentioned before). + +<H4>Persistent connections</H4> +The IP lookup described above is only done <EM>once</EM> for a particular +TCP/IP session while the name lookup is done on <EM>every</EM> request +during a KeepAlive/persistent connection. In other words a client may +request pages from different name-based vhosts during a single +persistent connection. + + +<H4>Absolute URI</H4> + +<P>If the URI from the request is an absolute URI, and its hostname and +port match the main server or one of the configured virtual hosts +<EM>and</EM> match the address and port to which the client sent the request, +then the scheme/hostname/port prefix is stripped off and the remaining +relative URI is served by the corresponding main server or virtual host. +If it does not match, then the URI remains untouched and the request is +taken to be a proxy request. + + +<H3>Observations</H3> + +<UL> + +<LI>A name-based vhost can never interfere with an IP-base vhost and + vice versa. IP-based vhosts can only be reached through an IP address + of its own address set and never through any other address. + The same applies to name-based vhosts, they can only be reached + through an IP address of the corresponding address set which must + be defined with a <CODE>NameVirtualHost</CODE> directive. + <P> + +<LI><CODE>ServerAlias</CODE> and <CODE>ServerPath</CODE> checks are never + performed for an IP-based vhost. + <P> + +<LI>The order of name-/IP-based, the <SAMP>_default_</SAMP> + vhost and the <CODE>NameVirtualHost</CODE> directive within the config + file is not important. Only the ordering + of name-based vhosts for a specific address set is significant. The one + name-based vhosts that comes first in the configuration file has + the highest priority for its corresponding address set. + <P> + +<LI>For security reasons the port number given in a <CODE>Host:</CODE> + header field is never used during the matching process. Apache always + uses the real port to which the client sent the request. + <P> + +<LI>If a <CODE>ServerPath</CODE> directive exists which is a prefix of + another <CODE>ServerPath</CODE> directive that appears later in + the configuration file, then the former will always be matched + and the latter will never be matched. (That is assuming that no + <CODE>Host:</CODE> header field was available to disambiguate the two.) + <P> + +<LI>If two IP-based vhosts have an address in common, the vhost appearing + first in the config file is always matched. Such a thing might happen + inadvertently. The server will give a warning in the error + logfile when it detects this. + <P> + +<LI>A <CODE>_default_</CODE> vhost catches a request only if there is no + other vhost with a matching IP address <EM>and</EM> a matching port + number for the request. The request is only caught if the port number + to which the client sent the request matches the port number of your + <CODE>_default_</CODE> vhost which is your standard <CODE>Port</CODE> + by default. A wildcard port can be specified (<EM>i.e.</EM>, + <CODE>_default_:*</CODE>) to catch requests to any available port. + <P> + +<LI>The main_server is only used to serve a request if the IP address + and port number to which the client connected is unspecified + and does not match any other vhost (including a <CODE>_default_</CODE> + vhost). In other words the main_server only catches a request for an + unspecified address/port combination (unless there is a + <CODE>_default_</CODE> vhost which matches that port). + <P> + +<LI>A <CODE>_default_</CODE> vhost or the main_server is <EM>never</EM> + matched for a request with an unknown or missing <CODE>Host:</CODE> header + field if the client connected to an address (and port) which is used + for name-based vhosts, <EM>e.g.</EM>, in a <CODE>NameVirtualHost</CODE> + directive. + <P> + +<LI>You should never specify DNS names in <CODE>VirtualHost</CODE> + directives because it will force your server to rely on DNS to boot. + Furthermore it poses a security threat if you do not control the + DNS for all the domains listed. + There's <A HREF="../dns-caveats.html">more information</A> + available on this and the next two topics. + <P> + +<LI><CODE>ServerName</CODE> should always be set for each vhost. Otherwise + A DNS lookup is required for each vhost. + <P> + +</UL> + +<H3>Tips</H3> + +<P>In addition to the tips on the <A HREF="../dns-caveats.html#tips">DNS +Issues</A> page, here are some further tips: + +<UL> + +<LI>Place all main_server definitions before any <CODE>VirtualHost</CODE> + definitions. (This is to aid the readability of the configuration -- + the post-config merging process makes it non-obvious that definitions + mixed in around virtual hosts might affect all virtual hosts.) + <P> + +<LI>Group corresponding <CODE>NameVirtualHost</CODE> and + <CODE>VirtualHost</CODE> definitions in your configuration to ensure + better readability. + <P> + +<LI>Avoid <CODE>ServerPaths</CODE> which are prefixes of other + <CODE>ServerPaths</CODE>. If you cannot avoid this then you have to + ensure that the longer (more specific) prefix vhost appears earlier in + the configuration file than the shorter (less specific) prefix + (<EM>i.e.</EM>, "ServerPath /abc" should appear after + "ServerPath /abc/def"). + <P> + +</UL> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/details_1_2.html b/usr.sbin/httpd/htdocs/manual/vhosts/details_1_2.html new file mode 100644 index 00000000000..3560ee48cab --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/details_1_2.html @@ -0,0 +1,410 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>An In-Depth Discussion of VirtualHost Matching</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">An In-Depth Discussion of VirtualHost Matching</H1> + +<P>This is a very rough document that was probably out of date the moment +it was written. It attempts to explain exactly what the code does when +deciding what virtual host to serve a hit from. It's provided on the +assumption that something is better than nothing. The server version +under discussion is Apache 1.2. + +<P>If you just want to "make it work" without understanding +how, there's a <A HREF="#whatworks">What Works</A> section at the bottom. + +<H3>Config File Parsing</H3> + +<P>There is a main_server which consists of all the definitions appearing +outside of <CODE>VirtualHost</CODE> sections. There are virtual servers, +called <EM>vhosts</EM>, which are defined by +<A + HREF="../mod/core.html#virtualhost" +><SAMP>VirtualHost</SAMP></A> +sections. + +<P>The directives +<A + HREF="../mod/core.html#port" +><SAMP>Port</SAMP></A>, +<A + HREF="../mod/core.html#servername" +><SAMP>ServerName</SAMP></A>, +<A + HREF="../mod/core.html#serverpath" +><SAMP>ServerPath</SAMP></A>, +and +<A + HREF="../mod/core.html#serveralias" +><SAMP>ServerAlias</SAMP></A> +can appear anywhere within the definition of +a server. However, each appearance overrides the previous appearance +(within that server). + +<P>The default value of the <CODE>Port</CODE> field for main_server +is 80. The main_server has no default <CODE>ServerName</CODE>, +<CODE>ServerPath</CODE>, or <CODE>ServerAlias</CODE>. + +<P>In the absence of any +<A + HREF="../mod/core.html#listen" +><SAMP>Listen</SAMP></A> +directives, the (final if there +are multiple) <CODE>Port</CODE> directive in the main_server indicates +which port httpd will listen on. + +<P> The <CODE>Port</CODE> and <CODE>ServerName</CODE> directives for +any server main or virtual are used when generating URLs such as during +redirects. + +<P> Each address appearing in the <CODE>VirtualHost</CODE> directive +can have an optional port. If the port is unspecified it defaults to +the value of the main_server's most recent <CODE>Port</CODE> statement. +The special port <SAMP>*</SAMP> indicates a wildcard that matches any port. +Collectively the entire set of addresses (including multiple +<SAMP>A</SAMP> record +results from DNS lookups) are called the vhost's <EM>address set</EM>. + +<P> The magic <CODE>_default_</CODE> address has significance during +the matching algorithm. It essentially matches any unspecified address. + +<P> After parsing the <CODE>VirtualHost</CODE> directive, the vhost server +is given a default <CODE>Port</CODE> equal to the port assigned to the +first name in its <CODE>VirtualHost</CODE> directive. The complete +list of names in the <CODE>VirtualHost</CODE> directive are treated +just like a <CODE>ServerAlias</CODE> (but are not overridden by any +<CODE>ServerAlias</CODE> statement). Note that subsequent <CODE>Port</CODE> +statements for this vhost will not affect the ports assigned in the +address set. + +<P> +All vhosts are stored in a list which is in the reverse order that +they appeared in the config file. For example, if the config file is: + +<BLOCKQUOTE><PRE> + <VirtualHost A> + ... + </VirtualHost> + + <VirtualHost B> + ... + </VirtualHost> + + <VirtualHost C> + ... + </VirtualHost> +</PRE></BLOCKQUOTE> + +Then the list will be ordered: main_server, C, B, A. Keep this in mind. + +<P> +After parsing has completed, the list of servers is scanned, and various +merges and default values are set. In particular: + +<OL> +<LI>If a vhost has no + <A + HREF="../mod/core.html#serveradmin" + ><CODE>ServerAdmin</CODE></A>, + <A + HREF="../mod/core.html#resourceconfig" + ><CODE>ResourceConfig</CODE></A>, + <A + HREF="../mod/core.html#accessconfig" + ><CODE>AccessConfig</CODE></A>, + <A + HREF="../mod/core.html#timeout" + ><CODE>Timeout</CODE></A>, + <A + HREF="../mod/core.html#keepalivetimeout" + ><CODE>KeepAliveTimeout</CODE></A>, + <A + HREF="../mod/core.html#keepalive" + ><CODE>KeepAlive</CODE></A>, + <A + HREF="../mod/core.html#maxkeepaliverequests" + ><CODE>MaxKeepAliveRequests</CODE></A>, + or + <A + HREF="../mod/core.html#sendbuffersize" + ><CODE>SendBufferSize</CODE></A> + directive then the respective value is + inherited from the main_server. (That is, inherited from whatever + the final setting of that value is in the main_server.) + +<LI>The "lookup defaults" that define the default directory + permissions + for a vhost are merged with those of the main server. This includes + any per-directory configuration information for any module. + +<LI>The per-server configs for each module from the main_server are + merged into the vhost server. +</OL> + +Essentially, the main_server is treated as "defaults" or a +"base" on +which to build each vhost. But the positioning of these main_server +definitions in the config file is largely irrelevant -- the entire +config of the main_server has been parsed when this final merging occurs. +So even if a main_server definition appears after a vhost definition +it might affect the vhost definition. + +<P> If the main_server has no <CODE>ServerName</CODE> at this point, +then the hostname of the machine that httpd is running on is used +instead. We will call the <EM>main_server address set</EM> those IP +addresses returned by a DNS lookup on the <CODE>ServerName</CODE> of +the main_server. + +<P> Now a pass is made through the vhosts to fill in any missing +<CODE>ServerName</CODE> fields and to classify the vhost as either +an <EM>IP-based</EM> vhost or a <EM>name-based</EM> vhost. A vhost is +considered a name-based vhost if any of its address set overlaps the +main_server (the port associated with each address must match the +main_server's <CODE>Port</CODE>). Otherwise it is considered an IP-based +vhost. + +<P> For any undefined <CODE>ServerName</CODE> fields, a name-based vhost +defaults to the address given first in the <CODE>VirtualHost</CODE> +statement defining the vhost. Any vhost that includes the magic +<SAMP>_default_</SAMP> wildcard is given the same <CODE>ServerName</CODE> as +the main_server. Otherwise the vhost (which is necessarily an IP-based +vhost) is given a <CODE>ServerName</CODE> based on the result of a reverse +DNS lookup on the first address given in the <CODE>VirtualHost</CODE> +statement. + +<P> + +<H3>Vhost Matching</H3> + + +<P><STRONG>Apache 1.3 differs from what is documented +here, and documentation still has to be written.</STRONG> + +<P> +The server determines which vhost to use for a request as follows: + +<P> <CODE>find_virtual_server</CODE>: When the connection is first made +by the client, the local IP address (the IP address to which the client +connected) is looked up in the server list. A vhost is matched if it +is an IP-based vhost, the IP address matches and the port matches +(taking into account wildcards). + +<P> If no vhosts are matched then the last occurrence, if it appears, +of a <SAMP>_default_</SAMP> address (which if you recall the ordering of the +server list mentioned above means that this would be the first occurrence +of <SAMP>_default_</SAMP> in the config file) is matched. + +<P> In any event, if nothing above has matched, then the main_server is +matched. + +<P> The vhost resulting from the above search is stored with data +about the connection. We'll call this the <EM>connection vhost</EM>. +The connection vhost is constant over all requests in a particular TCP/IP +session -- that is, over all requests in a KeepAlive/persistent session. + +<P> For each request made on the connection the following sequence of +events further determines the actual vhost that will be used to serve +the request. + +<P> <CODE>check_fulluri</CODE>: If the requestURI is an absoluteURI, that +is it includes <CODE>http://hostname/</CODE>, then an attempt is made to +determine if the hostname's address (and optional port) match that of +the connection vhost. If it does then the hostname portion of the URI +is saved as the <EM>request_hostname</EM>. If it does not match, then the +URI remains untouched. <STRONG>Note</STRONG>: to achieve this address +comparison, +the hostname supplied goes through a DNS lookup unless it matches the +<CODE>ServerName</CODE> or the local IP address of the client's socket. + +<P> <CODE>parse_uri</CODE>: If the URI begins with a protocol +(<EM>i.e.</EM>, <CODE>http:</CODE>, <CODE>ftp:</CODE>) then the request is +considered a proxy request. Note that even though we may have stripped +an <CODE>http://hostname/</CODE> in the previous step, this could still +be a proxy request. + +<P> <CODE>read_request</CODE>: If the request does not have a hostname +from the earlier step, then any <CODE>Host:</CODE> header sent by the +client is used as the request hostname. + +<P> <CODE>check_hostalias</CODE>: If the request now has a hostname, +then an attempt is made to match for this hostname. The first step +of this match is to compare any port, if one was given in the request, +against the <CODE>Port</CODE> field of the connection vhost. If there's +a mismatch then the vhost used for the request is the connection vhost. +(This is a bug, see observations.) + +<P> +If the port matches, then httpd scans the list of vhosts starting with +the next server <STRONG>after</STRONG> the connection vhost. This scan does not +stop if there are any matches, it goes through all possible vhosts, +and in the end uses the last match it found. The comparisons performed +are as follows: + +<UL> +<LI>Compare the request hostname:port with the vhost + <CODE>ServerName</CODE> and <CODE>Port</CODE>. + +<LI>Compare the request hostname against any and all addresses given in + the <CODE>VirtualHost</CODE> directive for this vhost. + +<LI>Compare the request hostname against the <CODE>ServerAlias</CODE> + given for the vhost. +</UL> + +<P> +<CODE>check_serverpath</CODE>: If the request has no hostname +(back up a few paragraphs) then a scan similar to the one +in <CODE>check_hostalias</CODE> is performed to match any +<CODE>ServerPath</CODE> directives given in the vhosts. Note that the +<STRONG>last match</STRONG> is used regardless (again consider the ordering of +the virtual hosts). + +<H3>Observations</H3> + +<UL> + +<LI>It is difficult to define an IP-based vhost for the machine's + "main IP address". You essentially have to create a bogus + <CODE>ServerName</CODE> for the main_server that does not match the + machine's IPs. + <P> + +<LI>During the scans in both <CODE>check_hostalias</CODE> and + <CODE>check_serverpath</CODE> no check is made that the vhost being + scanned is actually a name-based vhost. This means, for example, that + it's possible to match an IP-based vhost through another address. But + because the scan starts in the vhost list at the first vhost that + matched the local IP address of the connection, not all IP-based vhosts + can be matched. + <P> + Consider the config file above with three vhosts A, B, C. Suppose + that B is a named-based vhost, and A and C are IP-based vhosts. If + a request comes in on B or C's address containing a header + "<SAMP>Host: A</SAMP>" then + it will be served from A's config. If a request comes in on A's + address then it will always be served from A's config regardless of + any Host: header. + </P> + +<LI>Unless you have a <SAMP>_default_</SAMP> vhost, + it doesn't matter if you mix name-based vhosts in amongst IP-based + vhosts. During the <CODE>find_virtual_server</CODE> phase above no + named-based vhost will be matched, so the main_server will remain the + connection vhost. Then scans will cover all vhosts in the vhost list. + <P> + If you do have a <SAMP>_default_</SAMP> vhost, then you cannot place + named-based vhosts after it in the config. This is because on any + connection to the main server IPs the connection vhost will always be + the <SAMP>_default_</SAMP> vhost since none of the name-based are + considered during <CODE>find_virtual_server</CODE>. + </P> + +<LI>You should never specify DNS names in <CODE>VirtualHost</CODE> + directives because it will force your server to rely on DNS to boot. + Furthermore it poses a security threat if you do not control the + DNS for all the domains listed. + <A HREF="dns-caveats.html">There's more information + available on this and the next two topics</A>. + <P> + +<LI><CODE>ServerName</CODE> should always be set for each vhost. Otherwise + A DNS lookup is required for each vhost. + <P> + +<LI>A DNS lookup is always required for the main_server's + <CODE>ServerName</CODE> (or to generate that if it isn't specified + in the config). + <P> + +<LI>If a <CODE>ServerPath</CODE> directive exists which is a prefix of + another <CODE>ServerPath</CODE> directive that appears later in + the configuration file, then the former will always be matched + and the latter will never be matched. (That is assuming that no + Host header was available to disambiguate the two.) + <P> + +<LI>If a vhost that would otherwise be a name-vhost includes a + <CODE>Port</CODE> statement that doesn't match the main_server + <CODE>Port</CODE> then it will be considered an IP-based vhost. + Then <CODE>find_virtual_server</CODE> will match it (because + the ports associated with each address in the address set default + to the port of the main_server) as the connection vhost. Then + <CODE>check_hostalias</CODE> will refuse to check any other name-based + vhost because of the port mismatch. The result is that the vhost + will steal all hits going to the main_server address. + <P> + +<LI>If two IP-based vhosts have an address in common, the vhost appearing + later in the file is always matched. Such a thing might happen + inadvertently. If the config has name-based vhosts and for some reason + the main_server <CODE>ServerName</CODE> resolves to the wrong address + then all the name-based vhosts will be parsed as ip-based vhosts. + Then the last of them will steal all the hits. + <P> + +<LI>The last name-based vhost in the config is always matched for any hit + which doesn't match one of the other name-based vhosts. + +</UL> + +<H3><A NAME="whatworks">What Works</A></H3> + +<P>In addition to the tips on the <A HREF="dns-caveats.html#tips">DNS +Issues</A> page, here are some further tips: + +<UL> + +<LI>Place all main_server definitions before any VirtualHost definitions. +(This is to aid the readability of the configuration -- the post-config +merging process makes it non-obvious that definitions mixed in around +virtualhosts might affect all virtualhosts.) +<P> + +<LI>Arrange your VirtualHosts such +that all name-based virtual hosts come first, followed by IP-based +virtual hosts, followed by any <SAMP>_default_</SAMP> virtual host +<P> + +<LI>Avoid <CODE>ServerPaths</CODE> which are prefixes of other +<CODE>ServerPaths</CODE>. If you cannot avoid this then you have to +ensure that the longer (more specific) prefix vhost appears earlier in +the configuration file than the shorter (less specific) prefix +(<EM>i.e.</EM>, "ServerPath /abc" should appear after +"ServerPath /abcdef"). +<P> + +<LI>Do not use <EM>port-based</EM> vhosts in the same server as +name-based vhosts. A loose definition for port-based is a vhost which +is determined by the port on the server (<EM>i.e.</EM>, one server with +ports 8000, 8080, and 80 - all of which have different configurations). +<P> + +</UL> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/examples.html b/usr.sbin/httpd/htdocs/manual/vhosts/examples.html new file mode 100644 index 00000000000..f6e6f573b77 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/examples.html @@ -0,0 +1,526 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>VirtualHost Examples</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Virtual Host examples for common setups</H1> + + +<H2>Base configuration</H2> + +<UL> +<LI><A HREF="#ip">IP-based vhosts only</A> +<LI><A HREF="#name">Name-based vhosts only</A> +<LI><A HREF="#mixed">Mixed name-/IP-based vhosts</A> +<LI><A HREF="#port">Port-based vhosts</A> +</UL> + +<H2>Additional features</H2> + +<UL> +<LI><A HREF="#default">Using <CODE>_default_</CODE> vhosts</A> +<LI><A HREF="#migrate">Migrating a named-based vhost to an IP-based vhost</A> +<LI><A HREF="#serverpath">Using the <CODE>ServerPath</CODE> directive</A> +</UL> + +<HR> + +<H3><A NAME="ip">IP-based vhosts only</A></H3> + +<UL> + +<LI><STRONG>Setup 1:</STRONG> + The server machine has two IP addresses (<SAMP>111.22.33.44</SAMP> + and <SAMP>111.22.33.55</SAMP>) + which resolve to the names <SAMP>server.domain.tld</SAMP> and + <SAMP>www.otherdomain.tld</SAMP> respectively. + The hostname <SAMP>www.domain.tld</SAMP> is an alias (CNAME) + for <SAMP>server.domain.tld</SAMP> and will represent the + main server. + <P> + <STRONG>Server configuration:</STRONG> + + + <BLOCKQUOTE><PRE> + ... + Port 80 + DocumentRoot /www/domain + ServerName www.domain.tld + + <VirtualHost 111.22.33.55> + DocumentRoot /www/otherdomain + ServerName www.otherdomain.tld + ... + </VirtualHost> + </PRE> + <SAMP>www.otherdomain.tld</SAMP> can only be reached through the + address <SAMP>111.22.33.55</SAMP>, while <SAMP>www.domain.tld</SAMP> + can only be reached through <SAMP>111.22.33.44</SAMP> + (which represents our main server). + </BLOCKQUOTE> + <P> + +<LI><STRONG>Setup 2:</STRONG> + Same as setup 1, but we don't want to have a dedicated main server. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + Port 80 + ServerName server.domain.tld + + <VirtualHost 111.22.33.44> + DocumentRoot /www/domain + ServerName www.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55> + DocumentRoot /www/otherdomain + ServerName www.otherdomain.tld + ... + </VirtualHost> + </PRE> + The main server can never catch a request, because all IP addresses + of our machine are in use for IP-based virtual hosts + (only <SAMP>localhost</SAMP> requests can hit the main server). + </BLOCKQUOTE> + <P> + +<LI><STRONG>Setup 3:</STRONG> + The server machine has two IP addresses (<SAMP>111.22.33.44</SAMP> + and <SAMP>111.22.33.55</SAMP>) + which resolve to the names <SAMP>server.domain.tld</SAMP> and + <SAMP>www-cache.domain.tld</SAMP> respectively. + The hostname <SAMP>www.domain.tld</SAMP> is an alias (CNAME) + for <SAMP>server.domain.tld</SAMP> and will represent the + main server. + <SAMP>www-cache.domain.tld</SAMP> will become our proxy-cache + listening on port 8080, while the web server itself uses the default + port 80. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + Port 80 + Listen 111.22.33.44:80 + Listen 111.22.33.55:8080 + ServerName server.domain.tld + + <VirtualHost 111.22.33.44:80> + DocumentRoot /www/domain + ServerName www.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55:8080> + ServerName www-cache.domain.tld + ... + <Directory proxy:> + order deny,allow + deny from all + allow from 111.22.33 + </Directory> + </VirtualHost> + </PRE> + The main server can never catch a request, because all IP addresses + (apart from <SAMP>localhost</SAMP>) of our machine are in use for IP-based + virtual hosts. The web server can only be reached on the first address + through port 80 and the proxy only on the second address through port 8080. + </BLOCKQUOTE> +</UL> +<HR> + +<H3><A NAME="name">Name-based vhosts only</A></H3> + +<UL> + +<LI><STRONG>Setup 1:</STRONG> + The server machine has one IP address (<SAMP>111.22.33.44</SAMP>) + which resolves to the name <SAMP>server.domain.tld</SAMP>. + There are two aliases (CNAMEs) <SAMP>www.domain.tld</SAMP> and + <SAMP>www.sub.domain.tld</SAMP> for the address <SAMP>111.22.33.44</SAMP>. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + Port 80 + ServerName server.domain.tld + + NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + DocumentRoot /www/domain + ServerName www.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + DocumentRoot /www/subdomain + ServerName www.sub.domain.tld + ... + </VirtualHost> + </PRE> + Apart from <SAMP>localhost</SAMP> there are no unspecified + addresses/ports, therefore the main server only serves + <SAMP>localhost</SAMP> requests. Due to the fact + that <SAMP>www.domain.tld</SAMP> has the highest priority + it can be seen as the <CITE>default</CITE> or + <CITE>primary</CITE> server. + </BLOCKQUOTE> + <P> + +<LI><STRONG>Setup 2:</STRONG> + The server machine has two IP addresses (<SAMP>111.22.33.44</SAMP> + and <SAMP>111.22.33.55</SAMP>) + which resolve to the names <SAMP>server1.domain.tld</SAMP> and + <SAMP>server2.domain.tld</SAMP> respectively. + The alias <SAMP>www.domain.tld</SAMP> should be used for the + main server which should also catch any unspecified addresses. + We want to use a virtual host for the alias + <SAMP>www.otherdomain.tld</SAMP> and one virtual host should + catch any request to hostnames of the form + <SAMP>*.sub.domain.tld</SAMP> with <SAMP>www.sub.domain.tld</SAMP> + as its server name. The address <SAMP>111.22.33.55</SAMP> should be + used for the virtual hosts. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + Port 80 + ServerName www.domain.tld + DocumentRoot /www/domain + + NameVirtualHost 111.22.33.55 + + <VirtualHost 111.22.33.55> + DocumentRoot /www/otherdomain + ServerName www.otherdomain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55> + DocumentRoot /www/subdomain + ServerName www.sub.domain.tld + ServerAlias *.sub.domain.tld + ... + </VirtualHost> + </PRE> + Any request to an address other than <SAMP>111.22.33.55</SAMP> + will be served from the main server. A request to + <SAMP>111.22.33.55</SAMP> with an unknown or no <CODE>Host:</CODE> + header will be served from <SAMP>www.otherdomain.tld</SAMP>. + </BLOCKQUOTE> +</UL> + +<HR> + +<H3><A NAME="mixed">Mixed name-/IP-based vhosts</A></H3> + +<UL> + +<LI><STRONG>Setup:</STRONG> + The server machine has three IP addresses (<SAMP>111.22.33.44</SAMP>, + <SAMP>111.22.33.55</SAMP> and <SAMP>111.22.33.66</SAMP>) + which resolve to the names <SAMP>server.domain.tld</SAMP>, + <SAMP>www.otherdomain1.tld</SAMP> and <SAMP>www.otherdomain2.tld</SAMP> + respectively. + The address <SAMP>111.22.33.44</SAMP> should we used for a couple + of name-based vhosts and the other addresses for IP-based vhosts. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + Port 80 + ServerName server.domain.tld + + NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + DocumentRoot /www/domain + ServerName www.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + DocumentRoot /www/subdomain1 + ServerName www.sub1.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + DocumentRoot /www/subdomain2 + ServerName www.sub2.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55> + DocumentRoot /www/otherdomain1 + ServerName www.otherdomain1.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.66> + DocumentRoot /www/otherdomain2 + ServerName www.otherdomain2.tld + ... + </VirtualHost> + </PRE></BLOCKQUOTE> + +</UL> + +<HR> + +<H3><A NAME="port">Port-based vhosts</A></H3> + +<UL> + +<LI><STRONG>Setup:</STRONG> + The server machine has one IP address (<SAMP>111.22.33.44</SAMP>) + which resolves to the name <SAMP>www.domain.tld</SAMP>. + If we don't have the option to get another address or alias + for our server we can use port-based vhosts if we need + a virtual host with a different configuration. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + Listen 80 + Listen 8080 + ServerName www.domain.tld + DocumentRoot /www/domain + + <VirtualHost 111.22.33.44:8080> + DocumentRoot /www/domain2 + ... + </VirtualHost> + </PRE> + A request to <SAMP>www.domain.tld</SAMP> on port 80 is served + from the main server and a request to port 8080 is served from + the virtual host. + </BLOCKQUOTE> +</UL> + +<HR> + +<H3><A NAME="default">Using <CODE>_default_</CODE> vhosts</A></H3> + +<UL> + +<LI><STRONG>Setup 1:</STRONG> + Catching <EM>every</EM> request to any unspecified IP address and port, + <EM>i.e.</EM>, an address/port combination that is not used for any other + virtual host. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + <VirtualHost _default_:*> + DocumentRoot /www/default + ... + </VirtualHost> + </PRE> + Using such a default vhost with a wildcard port effectively + prevents any request going to the main server.<BR> + A default vhost never serves a request that was sent to an + address/port that is used for name-based vhosts. If the request + contained an unknown or no <CODE>Host:</CODE> header it is + always served from the primary name-based vhost (the + vhost for that address/port appearing first in the configuration + file).<BR> + You can use + <A HREF="../mod/mod_alias.html#aliasmatch"><CODE>AliasMatch</CODE></A> + or + <A HREF="../mod/mod_rewrite.html#RewriteRule"><CODE>RewriteRule</CODE></A> + to rewrite any request to a single information page (or script). + </BLOCKQUOTE> + <P> + +<LI><STRONG>Setup 2:</STRONG> + Same as setup 1, but the server listens on several ports and + we want to use a second <CODE>_default_</CODE> vhost for port 80. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + <VirtualHost _default_:80> + DocumentRoot /www/default80 + ... + </VirtualHost> + + <VirtualHost _default_:*> + DocumentRoot /www/default + ... + </VirtualHost> + </PRE> + The default vhost for port 80 (which <EM>must</EM> appear before + any default vhost with a wildcard port) catches all requests that + were sent to an unspecified IP address. The main server is + never used to serve a request. + </BLOCKQUOTE> + <P> + +<LI><STRONG>Setup 3:</STRONG> + We want to have a default vhost for port 80, but no other default vhosts. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + <VirtualHost _default_:80> + DocumentRoot /www/default + ... + </VirtualHost> + </PRE> + A request to an unspecified address on port 80 is served from the + default vhost any other request to an unspecified address and port + is served from the main server. + </BLOCKQUOTE> + +</UL> + +<HR> + +<H3><A NAME="migrate">Migrating a name-based vhost to an IP-based vhost</A></H3> + +<UL> + +<LI><STRONG>Setup:</STRONG> + The name-based vhost with the hostname + <SAMP>www.otherdomain.tld</SAMP> (from our <A HREF="#name">name-based</A> + example, setup 2) should get its own IP address. + To avoid problems with name servers or proxies who cached the old + IP address for the name-based vhost we want to provide both variants + during a migration phase.<BR> + The solution is easy, because we can simply add the new IP address + (<SAMP>111.22.33.66</SAMP>) to the <CODE>VirtualHost</CODE> directive. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + Port 80 + ServerName www.domain.tld + DocumentRoot /www/domain + + NameVirtualHost 111.22.33.55 + + <VirtualHost 111.22.33.55 111.22.33.66> + DocumentRoot /www/otherdomain + ServerName www.otherdomain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55> + DocumentRoot /www/subdomain + ServerName www.sub.domain.tld + ServerAlias *.sub.domain.tld + ... + </VirtualHost> + </PRE> + The vhost can now be accessed through the new address (as an IP-based + vhost) and through the old address (as a name-based vhost). + </BLOCKQUOTE> + +</UL> + +<HR> + +<H3><A NAME="serverpath">Using the <CODE>ServerPath</CODE> directive</A></H3> + +<UL> + +<LI><STRONG>Setup:</STRONG> + We have a server with two name-based vhosts. In order to match the correct + virtual host a client must send the correct <CODE>Host:</CODE> header. + Old HTTP/1.0 clients do not send such a header and Apache has no clue + what vhost the client tried to reach (and serves the request from + the primary vhost). To provide as much backward compatibility + as possible we create a primary vhost which returns a single page + containing links with an URL prefix to the name-based virtual hosts. + <P> + <STRONG>Server configuration:</STRONG> + + <BLOCKQUOTE><PRE> + ... + NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + # primary vhost + DocumentRoot /www/subdomain + RewriteEngine On + RewriteRule ^/.* /www/subdomain/index.html + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + DocumentRoot /www/subdomain/sub1 + ServerName www.sub1.domain.tld + ServerPath /sub1/ + RewriteEngine On + RewriteRule ^(/sub1/.*) /www/subdomain$1 + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + DocumentRoot /www/subdomain/sub2 + ServerName www.sub2.domain.tld + ServerPath /sub2/ + RewriteEngine On + RewriteRule ^(/sub2/.*) /www/subdomain$1 + ... + </VirtualHost> + </PRE> + Due to the <A HREF="../mod/core.html#serverpath"><CODE>ServerPath</CODE></A> + directive a request to the + URL <SAMP>http://www.sub1.domain.tld/sub1/</SAMP> is <EM>always</EM> + served from the sub1-vhost. <BR> + A request to the URL <SAMP>http://www.sub1.domain.tld/</SAMP> + is only served from the sub1-vhost if the client sent a correct + <CODE>Host:</CODE> header. + If no <CODE>Host:</CODE> header is sent the client gets the + information page from the primary host.<BR> + Please note that there is one oddity: A request to + <SAMP>http://www.sub2.domain.tld/sub1/</SAMP> is also served from + the sub1-vhost if the client sent no <CODE>Host:</CODE> header. <BR> + The <CODE>RewriteRule</CODE> directives are used to make sure that + a client which sent a correct <CODE>Host:</CODE> header can use + both URL variants, <EM>i.e.</EM>, with or without URL prefix. + </BLOCKQUOTE> + +</UL> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html b/usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html new file mode 100644 index 00000000000..0991cae74e2 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html @@ -0,0 +1,73 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache Server Virtual Host Support</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">File Descriptor Limits</H1> + +<P> +When using a large number of Virtual Hosts, Apache may run out of available +file descriptors (sometimes called <CITE>file handles</CITE> if each Virtual +Host specifies different log files. +The total number of file descriptors used by Apache is one for each distinct +error log file, one for every other log file directive, plus 10-20 for +internal use. Unix operating systems limit the number of file descriptors that +may be used by a process; the limit is typically 64, and may usually be +increased up to a large hard-limit. +<P> +Although Apache attempts to increase the limit as required, this +may not work if: +<OL> +<LI>Your system does not provide the setrlimit() system call. +<LI>The setrlimit(RLIMIT_NOFILE) call does not function on your system + (such as Solaris 2.3) +<LI>The number of file descriptors required exceeds the hard limit. +<LI>Your system imposes other limits on file descriptors, such as a limit +on stdio streams only using file descriptors below 256. (Solaris 2) +</OL> + +In the event of problems you can: +<UL> +<LI>Reduce the number of log files; don't specify log files in the VirtualHost +sections, but only log to the main log files. +<LI>If you system falls into 1 or 2 (above), then increase the file descriptor +limit before starting Apache, using a script like +<BLOCKQUOTE><CODE> +#!/bin/sh <BR> +ulimit -S -n 100 <BR> +exec httpd</CODE></BLOCKQUOTE> +</UL> +<P> +Please see the +<A HREF="../misc/descriptors.html">Descriptors and Apache</A> +document containing further details about file descriptor problems and how +they can be solved on your operating system. +</P> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY></HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/footer.html b/usr.sbin/httpd/htdocs/manual/vhosts/footer.html new file mode 100644 index 00000000000..7fe745dcfde --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/footer.html @@ -0,0 +1,8 @@ +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/header.html b/usr.sbin/httpd/htdocs/manual/vhosts/header.html new file mode 100644 index 00000000000..56623000296 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/header.html @@ -0,0 +1,6 @@ +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/host.html b/usr.sbin/httpd/htdocs/manual/vhosts/host.html new file mode 100644 index 00000000000..a00e1da49eb --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/host.html @@ -0,0 +1,186 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>Apache non-IP Virtual Hosts</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Apache non-IP Virtual Hosts</H1> + +<STRONG>See Also:</STRONG> +<A HREF="virtual-host.html">Virtual Host Support</A> + +<HR> + +<H2>What is a Virtual Host</H2> + +<P>The "Virtual Host" refers to the practice of maintaining more than +one server on one machine, as differentiated by their apparent +hostname. For example, it is often desirable for companies sharing a +web server to have their own domains, with web servers accessible as +<CODE>www.company1.com</CODE> and <CODE>www.company2.com</CODE>, +without requiring the user to know any extra path information.</P> + +<P>Apache was one of the first servers to support virtual hosts right +out of the box, but since the base <CODE>HTTP</CODE> (HyperText +Transport Protocol) standard does not allow any method for the server +to determine the hostname it is being addressed as, Apache's virtual +host support has required a separate IP address for each +server. Documentation on using this approach (which still works very +well) <A HREF="virtual-host.html">is available</A>. + +<P>While the approach described above works, with the available IP +address space growing smaller, and the number of domains increasing, +it is not the most elegant solution, and is hard to implement on some +machines. The <CODE>HTTP/1.1</CODE> protocol contains a method for the +server to identify what name it is being addressed as. Apache 1.1 and +later support this approach as well as the traditional +IP-address-per-hostname method.</P> + +<P>The benefits of using the new virtual host support is a practically +unlimited number of servers, ease of configuration and use, and +requires no additional hardware or software. The main disadvantage is +that the user's browser must support this part of the protocol. The +latest versions of many browsers (including Netscape Navigator 2.0 and +later) do, but many browsers, especially older ones, do not. This can +cause problems, although a possible solution is addressed below.</P> + +<H2>Using non-IP Virtual Hosts</H2> + +<P>Using the new virtual hosts is quite easy, and superficially looks +like the old method. You simply add to one of the Apache configuration +files (most likely <CODE>httpd.conf</CODE> or <CODE>srm.conf</CODE>) +code similar to the following:</P> +<PRE> + <VirtualHost www.apache.org> + ServerName www.apache.org + DocumentRoot /usr/web/apache + </VirtualHost> +</PRE> + +<P>Of course, any additional directives can (and should) be placed +into the <CODE><VirtualHost></CODE> section. To make this work, +all that is needed is to make sure that the <CODE>www.apache.org</CODE> +DNS entry points to the same IP address as the main +server. Optionally, you could simply use that IP address in the +<VirtualHost> entry.</P> + +<P>Additionally, many servers may wish to be accessible by more than +one name. For example, the Apache server might want to be accessible +as <CODE>apache.org</CODE>, or <CODE>ftp.apache.org</CODE>, assuming +the IP addresses pointed to the same server. In fact, one might want it +so that all addresses at <CODE>apache.org</CODE> were picked up by the +server. This is possible with the <CODE>ServerAlias</CODE> +directive, placed inside the <VirtualHost> section. For +example:</P> + +<PRE> + ServerAlias apache.org *.apache.org +</PRE> + +<P>Note that you can use <CODE>*</CODE> and <CODE>?</CODE> as wild-card +characters.</P> + +<P>You also might need ServerAlias if you are serving local users who +do not always include the domain name. For example, if local users are +familiar with typing "www" or "www.physics" then you will need to add +<CODE>ServerAlias www www.physics</CODE>. It isn't possible for the +server to know what domain the client uses for their name resolution +because the client doesn't provide that information in the request.</P> + +<H2>Security Considerations</H2> + +Apache allows all virtual hosts to be made accessible via the +<CODE>Host:</CODE> header through all IP interfaces, even those which +are configured to use different IP interfaces. For example, if the +configuration for <CODE>www.foo.com</CODE> contained a virtual host +section for <CODE>www.bar.com</CODE>, and <CODE>www.bar.com</CODE> was +a separate IP interface, such that +non-<CODE>Host:</CODE>-header-supporting browsers can use it, as +before with Apache 1.0. If a request is made to +<CODE>www.foo.com</CODE> and the request includes the header +<CODE>Host: www.bar.com</CODE>, a page from <CODE>www.bar.com</CODE> +will be sent. + +<P> + +This is a security concern if you are controlling access to a +particular server based on IP-layer controls, such as from within a +firewall or router. Let's say <CODE>www.bar.com</CODE> in the above +example was instead an intra-net server called +<CODE>private.foo.com</CODE>, and the router used by foo.com only let +internal users access <CODE>private.foo.com</CODE>. Obviously, +<CODE>Host:</CODE> header functionality now allows someone who has +access to <CODE>www.foo.com</CODE> to get +<CODE>private.foo.com</CODE>, if they send a <CODE>Host: +private.foo.com</CODE> header. It is important to note that this +condition exists only if you only implement this policy at the IP +layer - all security controls used by Apache (<EM>i.e.</EM>, <A +HREF="../mod/mod_access.html">allow, deny from,</A> <EM>etc.</EM>) are +consistently respected. + +<H2>Compatibility with Older Browsers</H2> + +<P>As mentioned earlier, a majority of browsers do not send the +required data for the new virtual hosts to work properly. These +browsers will always be sent to the main server's pages. There is a +workaround, albeit a slightly cumbersome one:</P> + +<P>To continue the <CODE>www.apache.org</CODE> example (Note: Apache's +web server does not actually function in this manner), we might use the +new <CODE>ServerPath</CODE> directive in the <CODE>www.apache.org</CODE> +virtual host, for example: + +<PRE> + ServerPath /apache +</PRE> +<P>What does this mean? It means that a request for any file beginning +with "<CODE>/apache</CODE>" will be looked for in the Apache +docs. This means that the pages can be accessed as +<CODE>http://www.apache.org/apache/</CODE> for all browsers, although +new browsers can also access it as +<CODE>http://www.apache.org/</CODE>.</P> + +<P>In order to make this work, put a link on your main server's page +to <CODE>http://www.apache.org/apache/</CODE> (Note: Do not use +<CODE>http://www.apache.org/</CODE> - this would create an endless +loop). Then, in the virtual host's pages, be sure to use either purely +relative links (<EM>e.g.</EM>, "<CODE>file.html</CODE>" or +"<CODE>../icons/image.gif</CODE>" or links containing the prefacing +<CODE>/apache/</CODE> +(<EM>e.g.</EM>, "<CODE>http://www.apache.org/apache/file.html</CODE>" or +"<CODE>/apache/docs/1.1/index.html</CODE>").</P> + +<P>This requires a bit of +discipline, but adherence to these guidelines will, for the most part, +ensure that your pages will work with all browsers, new and old. When +a new browser contacts <CODE>http://www.apache.org/</CODE>, they will +be directly taken to the Apache pages. Older browsers will be able to +click on the link from the main server, go to +<CODE>http://www.apache.org/apache/</CODE>, and then access the +pages.</P> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/index.html b/usr.sbin/httpd/htdocs/manual/vhosts/index.html new file mode 100644 index 00000000000..d7fe8bb2f8a --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/index.html @@ -0,0 +1,78 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache Virtual Host documentation</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Apache Virtual Host documentation</H1> + +<P>The term <CITE>Virtual Host</CITE> refers to the practice of maintaining +more than one server on one machine, as differentiated by their apparent +hostname. For example, it is often desirable for companies sharing a +web server to have their own domains, with web servers accessible as +<SAMP>www.company1.com</SAMP> and <SAMP>www.company2.com</SAMP>, +without requiring the user to know any extra path information.</P> + +<P>Apache was one of the first servers to support IP-based +virtual hosts right out of the box. Versions 1.1 and later of +Apache support both, IP-based and name-based virtual hosts (vhosts). +The latter variant of virtual hosts is sometimes also called host-based or +non-IP virtual hosts.</P> + +<P>Below is a list of documentation pages which explain all details +of virtual host support in Apache version 1.3 and later.</P> + +<HR> + +<H2>Virtual Host Support</H2> + +<UL> +<LI><A HREF="ip-based.html">IP-based Virtual Hosts</A> +<LI><A HREF="name-based.html">Name-based Virtual Hosts</A> +<LI><A HREF="examples.html">Virtual Host examples for common setups</A> +<LI><A HREF="details.html">In-Depth Discussion of Virtual Host Matching</A> +<LI><A HREF="fd-limits.html">File Descriptor Limits</A> +</UL> + +<H2>Configuration directives</H2> + +<UL> +<LI><A HREF="../mod/core.html#virtualhost"><VirtualHost></A> +<LI><A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A> +<LI><A HREF="../mod/core.html#servername">ServerName</A> +<LI><A HREF="../mod/core.html#serveralias">ServerAlias</A> +<LI><A HREF="../mod/core.html#serverpath">ServerPath</A> +</UL> + +<P>Folks trying to debug their virtual host configuration may find the +Apache <CODE>-S</CODE> command line switch useful. It will dump out a +description of how Apache parsed the configuration file. Careful +examination of the IP addresses and server names may help uncover +configuration mistakes. + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/ip-based.html b/usr.sbin/httpd/htdocs/manual/vhosts/ip-based.html new file mode 100644 index 00000000000..7b8993b5c58 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/ip-based.html @@ -0,0 +1,154 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache IP-based Virtual Host Support</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Apache IP-based Virtual Host Support</H1> + +<STRONG>See also:</STRONG> +<A HREF="name-based.html">Name-based Virtual Hosts Support</A> + +<HR> + +<H2>System requirements</H2> +As the term <CITE>IP-based</CITE> indicates, the server <STRONG>must have a +different IP address for each IP-based virtual host</STRONG>. +This can be achieved by the machine having several physical network connections, +or by use of virtual interfaces which are supported by most modern +operating systems (see system documentation for details, these are +frequently called "ip aliases", and the "ifconfig" command +is most commonly used to set them up). + +<H2>How to set up Apache</H2> +There are two ways of configuring apache to support multiple hosts. +Either by running a separate httpd daemon for each hostname, or by running a +single daemon which supports all the virtual hosts. +<P> +Use multiple daemons when: +<UL> +<LI>There are security partitioning issues, such as company1 does not want + anyone at company2 to be able to read their data except via the web. + In this case you would need two daemons, each running with different + <A HREF="../mod/core.html#user">User</A>, + <A HREF="../mod/core.html#group">Group</A>, + <A HREF="../mod/core.html#listen">Listen</A>, and + <A HREF="../mod/core.html#serverroot">ServerRoot</A> settings. +<LI>You can afford the memory and + <A HREF="../misc/descriptors.html">file descriptor requirements</A> of + listening to every IP alias on the machine. It's only possible to + <A HREF="../mod/core.html#listen">Listen</A> + to the "wildcard" address, or to specific addresses. So if you have + a need to listen to a specific address for whatever reason, then you + will need to listen to all specific addresses. (Although one httpd + could listen to N-1 of the addresses, and another could listen to + the remaining address.) +</UL> +Use a single daemon when: +<UL> +<LI>Sharing of the httpd configuration between virtual hosts is acceptable. +<LI>The machine services a large number of requests, and so the performance + loss in running separate daemons may be significant. +</UL> + +<H2>Setting up multiple daemons</H2> +Create a separate httpd installation for each virtual host. +For each installation, use the +<A HREF="../mod/core.html#listen">Listen</A> directive in the configuration +file to select which IP address (or virtual host) that daemon services. +e.g. +<PRE> + Listen www.smallco.com:80 +</PRE> +It is recommended that you use an IP address instead of a hostname +(see <A HREF="../dns-caveats.html">DNS caveats</A>). + +<H2>Setting up a single daemon with virtual hosts</H2> +For this case, a single httpd will service requests for the main server +and all the virtual hosts. +The <A HREF="../mod/core.html#virtualhost">VirtualHost</A> directive in the + configuration file is used to set the values of +<A HREF="../mod/core.html#serveradmin">ServerAdmin</A>, +<A HREF="../mod/core.html#servername">ServerName</A>, +<A HREF="../mod/core.html#documentroot">DocumentRoot</A>, +<A HREF="../mod/core.html#errorlog">ErrorLog</A> and +<A HREF="../mod/mod_log_config.html#transferlog">TransferLog</A> or +<A HREF="../mod/mod_log_config.html#customlog">CustomLog</A> +configuration directives to different values for each virtual host. +e.g. +<PRE> + <VirtualHost www.smallco.com> + ServerAdmin webmaster@mail.smallco.com + DocumentRoot /groups/smallco/www + ServerName www.smallco.com + ErrorLog /groups/smallco/logs/error_log + TransferLog /groups/smallco/logs/access_log + </VirtualHost> + + <VirtualHost www.baygroup.org> + ServerAdmin webmaster@mail.baygroup.org + DocumentRoot /groups/baygroup/www + ServerName www.baygroup.org + ErrorLog /groups/baygroup/logs/error_log + TransferLog /groups/baygroup/logs/access_log + </VirtualHost> +</PRE> + +It is recommended that you use an IP address instead of a hostname +(see <A HREF="../dns-caveats.html">DNS caveats</A>). + +<P> + +Almost <STRONG>any</STRONG> configuration directive can be put +in the VirtualHost directive, with the exception of +<A HREF="../mod/core.html#servertype">ServerType</A>, +<A HREF="../mod/core.html#startservers">StartServers</A>, +<A HREF="../mod/core.html#maxspareservers">MaxSpareServers</A>, +<A HREF="../mod/core.html#minspareservers">MinSpareServers</A>, +<A HREF="../mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A>, +<A HREF="../mod/core.html#bindaddress">BindAddress</A>, +<A HREF="../mod/core.html#listen">Listen</A>, +<A HREF="../mod/core.html#pidfile">PidFile</A>, +<A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A>, +<A HREF="../mod/core.html#serverroot">ServerRoot</A> and +<A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A>. +<P> +<A HREF="../mod/core.html#user">User</A> and +<A HREF="../mod/core.html#group">Group</A> may be used inside a VirtualHost +directive if the <A HREF="../suexec.html">suEXEC wrapper</A> is used. +<P> + +<EM>SECURITY:</EM> When specifying where to write log files, be aware +of some security risks which are present if anyone other than the +user that starts Apache has write access to the directory where they +are written. See the <A HREF="../misc/security_tips.html">security +tips</A> document for details. +</P> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html b/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html new file mode 100644 index 00000000000..339f54949e0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html @@ -0,0 +1,160 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>Apache name-based Virtual Hosts</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Apache name-based Virtual Host Support</H1> + +<STRONG>See Also:</STRONG> +<A HREF="ip-based.html">IP-based Virtual Host Support</A> + +<HR> + +<H2>Name-based vs. IP-based virtual hosts</H2> + +<P>While the approach with IP-based virtual hosts works very well, +it is not the most elegant solution, because a dedicated IP address +is needed for every virtual host and it is hard to implement on some +machines. The <CODE>HTTP/1.1</CODE> protocol contains a method for the +server to identify what name it is being addressed as. Apache 1.1 and +later support this approach as well as the traditional +IP-address-per-hostname method.</P> + +<P>The benefits of using the new name-based virtual host support is a +practically unlimited number of servers, ease of configuration and use, and +requires no additional hardware or software. +The main disadvantage is that the client must support this part of the +protocol. The latest versions of most browsers do, but there are still +old browsers in use who do not. This can cause problems, although a possible +solution is addressed below.</P> + +<H2>Using non-IP Virtual Hosts</H2> + +<P>Using the new virtual hosts is quite easy, and superficially looks +like the old method. You simply add to one of the Apache configuration +files (most likely <CODE>httpd.conf</CODE> or <CODE>srm.conf</CODE>) +code similar to the following:</P> +<PRE> + NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + ServerName www.domain.tld + DocumentRoot /web/domain + </VirtualHost> +</PRE> + +<P>The notable difference between IP-based and name-based virtual host +configuration is the +<A HREF="../mod/core.html#namevirtualhost"><CODE>NameVirtualHost</CODE></A> +directive which specifies an IP address that should be used as a target for +name-based virtual hosts. + +<P>Of course, any additional directives can (and should) be placed +into the <CODE><VirtualHost></CODE> section. To make this work, +all that is needed is to make sure that the name +<SAMP>www.domain.tld</SAMP> points to the IP address +<SAMP>111.22.33.44</SAMP></P> + +<P>Note: When you specify an IP address in a <CODE>NameVirtualHost</CODE> +directive then requests to that IP address will only ever be served +by matching <VirtualHost>s. The "main server" will <STRONG>never</STRONG> +be served from the specified IP address. + +<P>Additionally, many servers may wish to be accessible by more than +one name. For example, the example server might want to be accessible +as <CODE>domain.tld</CODE>, or <CODE>www2.domain.tld</CODE>, assuming +the IP addresses pointed to the same server. In fact, one might want it +so that all addresses at <CODE>domain.tld</CODE> were picked up by the +server. This is possible with the +<A HREF="../mod/core.html#serveralias"><CODE>ServerAlias</CODE></A> +directive, placed inside the <VirtualHost> section. For +example:</P> + +<PRE> + ServerAlias domain.tld *.domain.tld +</PRE> + +<P>Note that you can use <CODE>*</CODE> and <CODE>?</CODE> as wild-card +characters.</P> + +<P>You also might need <CODE>ServerAlias</CODE> if you are +serving local users who do not always include the domain name. +For example, if local users are +familiar with typing "www" or "www.foobar" then you will need to add +<CODE>ServerAlias www www.foobar</CODE>. It isn't possible for the +server to know what domain the client uses for their name resolution +because the client doesn't provide that information in the request.</P> + +<H2>Compatibility with Older Browsers</H2> + +<P>As mentioned earlier, there are still some clients in use who +do not send the required data for the name-based virtual hosts to work +properly. These clients will always be sent the pages from the +<CITE>primary</CITE> name-based virtual host (the first virtual host +appearing in the configuration file for a specific IP address).</P> + +<P>There is a possible workaround with the +<A HREF="../mod/core.html#serverpath"><CODE>ServerPath</CODE></A> +directive, albeit a slightly cumbersome one:</P> + +<P>Example configuration: + +<PRE> + NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + ServerName www.domain.tld + ServerPath /domain + DocumentRoot /web/domain + </VirtualHost> +</PRE> + +<P>What does this mean? It means that a request for any URI beginning +with "<SAMP>/domain</SAMP>" will be served from the virtual host +<SAMP>www.domain.tld</SAMP> This means that the pages can be accessed as +<CODE>http://www.domain.tld/domain/</CODE> for all clients, although +clients sending a <SAMP>Host:</SAMP> header can also access it as +<CODE>http://www.domain.tld/</CODE>.</P> + +<P>In order to make this work, put a link on your primary virtual host's page +to <SAMP>http://www.domain.tld/domain/</SAMP> +Then, in the virtual host's pages, be sure to use either purely +relative links (<EM>e.g.</EM>, "<SAMP>file.html</SAMP>" or +"<SAMP>../icons/image.gif</SAMP>" or links containing the prefacing +<SAMP>/domain/</SAMP> +(<EM>e.g.</EM>, "<SAMP>http://www.domain.tld/domain/misc/file.html</SAMP>" or +"<SAMP>/domain/misc/file.html</SAMP>").</P> + +<P>This requires a bit of +discipline, but adherence to these guidelines will, for the most part, +ensure that your pages will work with all browsers, new and old.</P> + +<P>See also: <A HREF="examples.html#serverpath">ServerPath configuration +example</A></P> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/vhosts-in-depth.html b/usr.sbin/httpd/htdocs/manual/vhosts/vhosts-in-depth.html new file mode 100644 index 00000000000..3560ee48cab --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/vhosts-in-depth.html @@ -0,0 +1,410 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>An In-Depth Discussion of VirtualHost Matching</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">An In-Depth Discussion of VirtualHost Matching</H1> + +<P>This is a very rough document that was probably out of date the moment +it was written. It attempts to explain exactly what the code does when +deciding what virtual host to serve a hit from. It's provided on the +assumption that something is better than nothing. The server version +under discussion is Apache 1.2. + +<P>If you just want to "make it work" without understanding +how, there's a <A HREF="#whatworks">What Works</A> section at the bottom. + +<H3>Config File Parsing</H3> + +<P>There is a main_server which consists of all the definitions appearing +outside of <CODE>VirtualHost</CODE> sections. There are virtual servers, +called <EM>vhosts</EM>, which are defined by +<A + HREF="../mod/core.html#virtualhost" +><SAMP>VirtualHost</SAMP></A> +sections. + +<P>The directives +<A + HREF="../mod/core.html#port" +><SAMP>Port</SAMP></A>, +<A + HREF="../mod/core.html#servername" +><SAMP>ServerName</SAMP></A>, +<A + HREF="../mod/core.html#serverpath" +><SAMP>ServerPath</SAMP></A>, +and +<A + HREF="../mod/core.html#serveralias" +><SAMP>ServerAlias</SAMP></A> +can appear anywhere within the definition of +a server. However, each appearance overrides the previous appearance +(within that server). + +<P>The default value of the <CODE>Port</CODE> field for main_server +is 80. The main_server has no default <CODE>ServerName</CODE>, +<CODE>ServerPath</CODE>, or <CODE>ServerAlias</CODE>. + +<P>In the absence of any +<A + HREF="../mod/core.html#listen" +><SAMP>Listen</SAMP></A> +directives, the (final if there +are multiple) <CODE>Port</CODE> directive in the main_server indicates +which port httpd will listen on. + +<P> The <CODE>Port</CODE> and <CODE>ServerName</CODE> directives for +any server main or virtual are used when generating URLs such as during +redirects. + +<P> Each address appearing in the <CODE>VirtualHost</CODE> directive +can have an optional port. If the port is unspecified it defaults to +the value of the main_server's most recent <CODE>Port</CODE> statement. +The special port <SAMP>*</SAMP> indicates a wildcard that matches any port. +Collectively the entire set of addresses (including multiple +<SAMP>A</SAMP> record +results from DNS lookups) are called the vhost's <EM>address set</EM>. + +<P> The magic <CODE>_default_</CODE> address has significance during +the matching algorithm. It essentially matches any unspecified address. + +<P> After parsing the <CODE>VirtualHost</CODE> directive, the vhost server +is given a default <CODE>Port</CODE> equal to the port assigned to the +first name in its <CODE>VirtualHost</CODE> directive. The complete +list of names in the <CODE>VirtualHost</CODE> directive are treated +just like a <CODE>ServerAlias</CODE> (but are not overridden by any +<CODE>ServerAlias</CODE> statement). Note that subsequent <CODE>Port</CODE> +statements for this vhost will not affect the ports assigned in the +address set. + +<P> +All vhosts are stored in a list which is in the reverse order that +they appeared in the config file. For example, if the config file is: + +<BLOCKQUOTE><PRE> + <VirtualHost A> + ... + </VirtualHost> + + <VirtualHost B> + ... + </VirtualHost> + + <VirtualHost C> + ... + </VirtualHost> +</PRE></BLOCKQUOTE> + +Then the list will be ordered: main_server, C, B, A. Keep this in mind. + +<P> +After parsing has completed, the list of servers is scanned, and various +merges and default values are set. In particular: + +<OL> +<LI>If a vhost has no + <A + HREF="../mod/core.html#serveradmin" + ><CODE>ServerAdmin</CODE></A>, + <A + HREF="../mod/core.html#resourceconfig" + ><CODE>ResourceConfig</CODE></A>, + <A + HREF="../mod/core.html#accessconfig" + ><CODE>AccessConfig</CODE></A>, + <A + HREF="../mod/core.html#timeout" + ><CODE>Timeout</CODE></A>, + <A + HREF="../mod/core.html#keepalivetimeout" + ><CODE>KeepAliveTimeout</CODE></A>, + <A + HREF="../mod/core.html#keepalive" + ><CODE>KeepAlive</CODE></A>, + <A + HREF="../mod/core.html#maxkeepaliverequests" + ><CODE>MaxKeepAliveRequests</CODE></A>, + or + <A + HREF="../mod/core.html#sendbuffersize" + ><CODE>SendBufferSize</CODE></A> + directive then the respective value is + inherited from the main_server. (That is, inherited from whatever + the final setting of that value is in the main_server.) + +<LI>The "lookup defaults" that define the default directory + permissions + for a vhost are merged with those of the main server. This includes + any per-directory configuration information for any module. + +<LI>The per-server configs for each module from the main_server are + merged into the vhost server. +</OL> + +Essentially, the main_server is treated as "defaults" or a +"base" on +which to build each vhost. But the positioning of these main_server +definitions in the config file is largely irrelevant -- the entire +config of the main_server has been parsed when this final merging occurs. +So even if a main_server definition appears after a vhost definition +it might affect the vhost definition. + +<P> If the main_server has no <CODE>ServerName</CODE> at this point, +then the hostname of the machine that httpd is running on is used +instead. We will call the <EM>main_server address set</EM> those IP +addresses returned by a DNS lookup on the <CODE>ServerName</CODE> of +the main_server. + +<P> Now a pass is made through the vhosts to fill in any missing +<CODE>ServerName</CODE> fields and to classify the vhost as either +an <EM>IP-based</EM> vhost or a <EM>name-based</EM> vhost. A vhost is +considered a name-based vhost if any of its address set overlaps the +main_server (the port associated with each address must match the +main_server's <CODE>Port</CODE>). Otherwise it is considered an IP-based +vhost. + +<P> For any undefined <CODE>ServerName</CODE> fields, a name-based vhost +defaults to the address given first in the <CODE>VirtualHost</CODE> +statement defining the vhost. Any vhost that includes the magic +<SAMP>_default_</SAMP> wildcard is given the same <CODE>ServerName</CODE> as +the main_server. Otherwise the vhost (which is necessarily an IP-based +vhost) is given a <CODE>ServerName</CODE> based on the result of a reverse +DNS lookup on the first address given in the <CODE>VirtualHost</CODE> +statement. + +<P> + +<H3>Vhost Matching</H3> + + +<P><STRONG>Apache 1.3 differs from what is documented +here, and documentation still has to be written.</STRONG> + +<P> +The server determines which vhost to use for a request as follows: + +<P> <CODE>find_virtual_server</CODE>: When the connection is first made +by the client, the local IP address (the IP address to which the client +connected) is looked up in the server list. A vhost is matched if it +is an IP-based vhost, the IP address matches and the port matches +(taking into account wildcards). + +<P> If no vhosts are matched then the last occurrence, if it appears, +of a <SAMP>_default_</SAMP> address (which if you recall the ordering of the +server list mentioned above means that this would be the first occurrence +of <SAMP>_default_</SAMP> in the config file) is matched. + +<P> In any event, if nothing above has matched, then the main_server is +matched. + +<P> The vhost resulting from the above search is stored with data +about the connection. We'll call this the <EM>connection vhost</EM>. +The connection vhost is constant over all requests in a particular TCP/IP +session -- that is, over all requests in a KeepAlive/persistent session. + +<P> For each request made on the connection the following sequence of +events further determines the actual vhost that will be used to serve +the request. + +<P> <CODE>check_fulluri</CODE>: If the requestURI is an absoluteURI, that +is it includes <CODE>http://hostname/</CODE>, then an attempt is made to +determine if the hostname's address (and optional port) match that of +the connection vhost. If it does then the hostname portion of the URI +is saved as the <EM>request_hostname</EM>. If it does not match, then the +URI remains untouched. <STRONG>Note</STRONG>: to achieve this address +comparison, +the hostname supplied goes through a DNS lookup unless it matches the +<CODE>ServerName</CODE> or the local IP address of the client's socket. + +<P> <CODE>parse_uri</CODE>: If the URI begins with a protocol +(<EM>i.e.</EM>, <CODE>http:</CODE>, <CODE>ftp:</CODE>) then the request is +considered a proxy request. Note that even though we may have stripped +an <CODE>http://hostname/</CODE> in the previous step, this could still +be a proxy request. + +<P> <CODE>read_request</CODE>: If the request does not have a hostname +from the earlier step, then any <CODE>Host:</CODE> header sent by the +client is used as the request hostname. + +<P> <CODE>check_hostalias</CODE>: If the request now has a hostname, +then an attempt is made to match for this hostname. The first step +of this match is to compare any port, if one was given in the request, +against the <CODE>Port</CODE> field of the connection vhost. If there's +a mismatch then the vhost used for the request is the connection vhost. +(This is a bug, see observations.) + +<P> +If the port matches, then httpd scans the list of vhosts starting with +the next server <STRONG>after</STRONG> the connection vhost. This scan does not +stop if there are any matches, it goes through all possible vhosts, +and in the end uses the last match it found. The comparisons performed +are as follows: + +<UL> +<LI>Compare the request hostname:port with the vhost + <CODE>ServerName</CODE> and <CODE>Port</CODE>. + +<LI>Compare the request hostname against any and all addresses given in + the <CODE>VirtualHost</CODE> directive for this vhost. + +<LI>Compare the request hostname against the <CODE>ServerAlias</CODE> + given for the vhost. +</UL> + +<P> +<CODE>check_serverpath</CODE>: If the request has no hostname +(back up a few paragraphs) then a scan similar to the one +in <CODE>check_hostalias</CODE> is performed to match any +<CODE>ServerPath</CODE> directives given in the vhosts. Note that the +<STRONG>last match</STRONG> is used regardless (again consider the ordering of +the virtual hosts). + +<H3>Observations</H3> + +<UL> + +<LI>It is difficult to define an IP-based vhost for the machine's + "main IP address". You essentially have to create a bogus + <CODE>ServerName</CODE> for the main_server that does not match the + machine's IPs. + <P> + +<LI>During the scans in both <CODE>check_hostalias</CODE> and + <CODE>check_serverpath</CODE> no check is made that the vhost being + scanned is actually a name-based vhost. This means, for example, that + it's possible to match an IP-based vhost through another address. But + because the scan starts in the vhost list at the first vhost that + matched the local IP address of the connection, not all IP-based vhosts + can be matched. + <P> + Consider the config file above with three vhosts A, B, C. Suppose + that B is a named-based vhost, and A and C are IP-based vhosts. If + a request comes in on B or C's address containing a header + "<SAMP>Host: A</SAMP>" then + it will be served from A's config. If a request comes in on A's + address then it will always be served from A's config regardless of + any Host: header. + </P> + +<LI>Unless you have a <SAMP>_default_</SAMP> vhost, + it doesn't matter if you mix name-based vhosts in amongst IP-based + vhosts. During the <CODE>find_virtual_server</CODE> phase above no + named-based vhost will be matched, so the main_server will remain the + connection vhost. Then scans will cover all vhosts in the vhost list. + <P> + If you do have a <SAMP>_default_</SAMP> vhost, then you cannot place + named-based vhosts after it in the config. This is because on any + connection to the main server IPs the connection vhost will always be + the <SAMP>_default_</SAMP> vhost since none of the name-based are + considered during <CODE>find_virtual_server</CODE>. + </P> + +<LI>You should never specify DNS names in <CODE>VirtualHost</CODE> + directives because it will force your server to rely on DNS to boot. + Furthermore it poses a security threat if you do not control the + DNS for all the domains listed. + <A HREF="dns-caveats.html">There's more information + available on this and the next two topics</A>. + <P> + +<LI><CODE>ServerName</CODE> should always be set for each vhost. Otherwise + A DNS lookup is required for each vhost. + <P> + +<LI>A DNS lookup is always required for the main_server's + <CODE>ServerName</CODE> (or to generate that if it isn't specified + in the config). + <P> + +<LI>If a <CODE>ServerPath</CODE> directive exists which is a prefix of + another <CODE>ServerPath</CODE> directive that appears later in + the configuration file, then the former will always be matched + and the latter will never be matched. (That is assuming that no + Host header was available to disambiguate the two.) + <P> + +<LI>If a vhost that would otherwise be a name-vhost includes a + <CODE>Port</CODE> statement that doesn't match the main_server + <CODE>Port</CODE> then it will be considered an IP-based vhost. + Then <CODE>find_virtual_server</CODE> will match it (because + the ports associated with each address in the address set default + to the port of the main_server) as the connection vhost. Then + <CODE>check_hostalias</CODE> will refuse to check any other name-based + vhost because of the port mismatch. The result is that the vhost + will steal all hits going to the main_server address. + <P> + +<LI>If two IP-based vhosts have an address in common, the vhost appearing + later in the file is always matched. Such a thing might happen + inadvertently. If the config has name-based vhosts and for some reason + the main_server <CODE>ServerName</CODE> resolves to the wrong address + then all the name-based vhosts will be parsed as ip-based vhosts. + Then the last of them will steal all the hits. + <P> + +<LI>The last name-based vhost in the config is always matched for any hit + which doesn't match one of the other name-based vhosts. + +</UL> + +<H3><A NAME="whatworks">What Works</A></H3> + +<P>In addition to the tips on the <A HREF="dns-caveats.html#tips">DNS +Issues</A> page, here are some further tips: + +<UL> + +<LI>Place all main_server definitions before any VirtualHost definitions. +(This is to aid the readability of the configuration -- the post-config +merging process makes it non-obvious that definitions mixed in around +virtualhosts might affect all virtualhosts.) +<P> + +<LI>Arrange your VirtualHosts such +that all name-based virtual hosts come first, followed by IP-based +virtual hosts, followed by any <SAMP>_default_</SAMP> virtual host +<P> + +<LI>Avoid <CODE>ServerPaths</CODE> which are prefixes of other +<CODE>ServerPaths</CODE>. If you cannot avoid this then you have to +ensure that the longer (more specific) prefix vhost appears earlier in +the configuration file than the shorter (less specific) prefix +(<EM>i.e.</EM>, "ServerPath /abc" should appear after +"ServerPath /abcdef"). +<P> + +<LI>Do not use <EM>port-based</EM> vhosts in the same server as +name-based vhosts. A loose definition for port-based is a vhost which +is determined by the port on the server (<EM>i.e.</EM>, one server with +ports 8000, 8080, and 80 - all of which have different configurations). +<P> + +</UL> + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/virtual-host.html b/usr.sbin/httpd/htdocs/manual/vhosts/virtual-host.html new file mode 100644 index 00000000000..a419be1e738 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/virtual-host.html @@ -0,0 +1,222 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache Server Virtual Host Support</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Virtual Host Support</H1> + +<STRONG>See Also:</STRONG> +<A HREF="host.html">Non-IP based virtual hosts</A> + +<H2>What are virtual hosts?</H2> +This is the ability of a single machine to be a web server for multiple +domains. For example, an Internet service provider might have a machine +called <CODE>www.serve.com</CODE> which provides Web space for several +organizations including, say, <EM>smallco</EM> and <EM>baygroup</EM>. +Ordinarily, these groups would be given parts of the Web tree on www.serve.com. +So smallco's home page would have the URL +<BLOCKQUOTE> +http://www.serve.com/smallco/ +</BLOCKQUOTE> +and baygroup's home page would have the URL +<BLOCKQUOTE> +http://www.serve.com/baygroup/ +</BLOCKQUOTE> +<P> +For esthetic reasons, however, both organizations would rather their home +pages appeared under their own names rather than that of the service +provider's; but they do not want to set up their own Internet links and +servers. +<P> +Virtual hosts are the solution to this problem. smallco and baygroup would +have their own Internet name registrations, <CODE>www.smallco.com</CODE> and +<CODE>www.baygroup.org</CODE> respectively. These hostnames would both +correspond to the service provider's machine (www.serve.com). Thus +smallco's home page would now have the URL +<BLOCKQUOTE> +http://www.smallco.com/ +</BLOCKQUOTE> +and baygroup's home page would would have the URL +<BLOCKQUOTE> +http://www.baygroup.org/ +</BLOCKQUOTE> + +<H2>System requirements</H2> +Due to limitations in the HTTP/1.0 protocol, the web server <STRONG>must have a +different IP address for each virtual host</STRONG>. This can be achieved +by the machine having several physical network connections, or by use +of a <A HREF="../misc/vif-info.html">virtual interface</A> on some operating +systems. + +<H2>How to set up Apache</H2> +There are two ways of configuring apache to support multiple hosts. +Either by running a separate httpd daemon for each hostname, or by running a +single daemon which supports all the virtual hosts. +<P> +Use multiple daemons when: +<UL> +<LI>The different virtual hosts need very different httpd configurations, such + as different values for: + <A HREF="../mod/core.html#servertype">ServerType</A>, + <A HREF="../mod/core.html#user">User</A>, + <A HREF="../mod/core.html#group">Group</A>, + <A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A> or + <A HREF="../mod/core.html#serverroot">ServerRoot</A>. +<LI>The machine does not process a very high request rate. +</UL> +Use a single daemon when: +<UL> +<LI>Sharing of the httpd configuration between virtual hosts is acceptable. +<LI>The machine services a large number of requests, and so the performance + loss in running separate daemons may be significant. +</UL> + +<H2>Setting up multiple daemons</H2> +Create a separate httpd installation for each virtual host. +For each installation, use the +<A HREF="../mod/core.html#bindaddress">BindAddress</A> directive in the +configuration +file to select which IP address (or virtual host) that daemon services. +<EM>E.g.</EM>, +<BLOCKQUOTE><CODE>BindAddress www.smallco.com</CODE></BLOCKQUOTE> +This hostname can also be given as an IP address. + +<H2>Setting up a single daemon</H2> +For this case, a single httpd will service requests for all the virtual hosts. +The <A HREF="../mod/core.html#virtualhost">VirtualHost</A> directive in the + configuration file is used to set the values of +<A HREF="../mod/core.html#serveradmin">ServerAdmin</A>, +<A HREF="../mod/core.html#servername">ServerName</A>, +<A HREF="../mod/core.html#documentroot">DocumentRoot</A>, +<A HREF="../mod/core.html#errorlog">ErrorLog</A> and +<A HREF="../mod/mod_log_config.html#transferlog">TransferLog</A> configuration +directives to different values for each virtual host. +<EM>E.g.</EM>, +<BLOCKQUOTE><CODE> +<VirtualHost www.smallco.com><BR> +ServerAdmin webmaster@mail.smallco.com<BR> +DocumentRoot /groups/smallco/www<BR> +ServerName www.smallco.com<BR> +ErrorLog /groups/smallco/logs/error_log<BR> +TransferLog /groups/smallco/logs/access_log<BR> +</VirtualHost><BR> +<BR> +<VirtualHost www.baygroup.org><BR> +ServerAdmin webmaster@mail.baygroup.org<BR> +DocumentRoot /groups/baygroup/www<BR> +ServerName www.baygroup.org<BR> +ErrorLog /groups/baygroup/logs/error_log<BR> +TransferLog /groups/baygroup/logs/access_log<BR> +</VirtualHost><BR> +</CODE></BLOCKQUOTE> + +This VirtualHost hostnames can also be given as IP addresses. + +<P> + +Almost <STRONG>ANY</STRONG> configuration directive can be put +in the VirtualHost directive, with the exception of +<A HREF="../mod/core.html#servertype">ServerType</A>, +<A HREF="../mod/core.html#user">User</A>, +<A HREF="../mod/core.html#group">Group</A>, +<A HREF="../mod/core.html#startservers">StartServers</A>, +<A HREF="../mod/core.html#maxspareservers">MaxSpareServers</A>, +<A HREF="../mod/core.html#minspareservers">MinSpareServers</A>, +<A HREF="../mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A>, +<A HREF="../mod/core.html#bindaddress">BindAddress</A>, +<A HREF="../mod/core.html#pidfile">PidFile</A>, +<A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A>, and +<A HREF="../mod/core.html#serverroot">ServerRoot</A>. + +<P> + +<EM>SECURITY:</EM> When specifying where to write log files, be aware +of some security risks which are present if anyone other than the +user that starts Apache has write access to the directory where they +are written. See the <A HREF="../misc/security_tips.html">security +tips</A> document for details. + +<P> + +<H2>File Handle/Resource Limits:</H2> +When using a large number of Virtual Hosts, Apache may run out of available +file descriptors if each Virtual Host specifies different log files. +The total number of file descriptors used by Apache is one for each distinct +error log file, one for every other log file directive, plus 10-20 for +internal use. Unix operating systems limit the number of file descriptors that +may be used by a process; the limit is typically 64, and may usually be +increased up to a large hard-limit. +<P> +Although Apache attempts to increase the limit as required, this +may not work if: +<OL> +<LI>Your system does not provide the setrlimit() system call. +<LI>The setrlimit(RLIMIT_NOFILE) call does not function on your system + (such as Solaris 2.3) +<LI>The number of file descriptors required exceeds the hard limit. +<LI>Your system imposes other limits on file descriptors, such as a limit +on stdio streams only using file descriptors below 256. (Solaris 2) +</OL> + +In the event of problems you can: +<UL> +<LI>Reduce the number of log files; don't specify log files in the VirtualHost +sections, but only log to the main log files. +<LI>If you system falls into 1 or 2 (above), then increase the file descriptor +limit before starting Apache, using a script like +<BLOCKQUOTE><CODE> +#!/bin/sh <BR> +ulimit -S -n 100 <BR> +exec httpd</CODE></BLOCKQUOTE> +</UL> + +The have been reports that Apache may start running out of resources allocated +for the root process. This will exhibit itself as errors in the error log like +"unable to fork". There are two ways you can bump this up: + +<OL> +<LI>Have a <CODE>csh</CODE> script wrapper around httpd which sets the +"rlimit" to some large number, like 512. +<LI>Edit http_main.c to add calls to setrlimit() from main(), along the lines +of +<PRE> + struct rlimit rlp; + + rlp.rlim_cur = rlp.rlim_max = 512; + if (setrlimit(RLIMIT_NPROC, &rlp)) { + fprintf(stderr, "setrlimit(RLIMIT_NPROC) failed.\n"); + exit(1); + } +</PRE> +(thanks to "Aaron Gifford <agifford@InfoWest.COM>" for the patch) +</OL> + +The latter will probably manifest itself in a later version of Apache. + +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/windows.html b/usr.sbin/httpd/htdocs/manual/windows.html new file mode 100644 index 00000000000..385be7cead4 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/windows.html @@ -0,0 +1,454 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Using Apache with Microsoft Windows</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Using Apache With Microsoft Windows</H1> + +<P>This document explains how to install, configure and run + Apache 1.3 under Microsoft Windows. Please note that at + this time, Windows support is entirely experimental, and is + recommended only for experienced users. The Apache Group does not + guarantee that this software will work as documented, or even at + all. If you find any bugs, or wish to contribute in other ways, please + use our <A HREF="http://www.apache.org/bug_report.html">bug reporting + page.</A></P> + +<P><STRONG>Warning: Apache on NT has not yet been optimized for performance. +Apache still performs best, and is most reliable on Unix platforms. Over +time we will improve NT performance. Folks doing comparative reviews +of webserver performance are asked to compare against Apache +on a Unix platform such as Solaris, FreeBSD, or Linux.</STRONG></P> + +<P> + +Most of this document assumes that you are installing Windows from a +binary distribution. If you want to compile Apache yourself (possibly +to help with development, or to track down bugs), see the section on +<A HREF="#comp">Compiling Apache for Windows</A> below. + +<HR> + +<UL> + <LI><A HREF="#req">Requirements</A> + <LI><A HREF="#down">Downloading Apache for Windows</A> + <LI><A HREF="#inst">Installing Apache for Windows (binary install)</A> + <LI><A HREF="#run">Running Apache for Windows</A> + <LI><A HREF="#use">Using Apache for Windows</A> + <LI><A HREF="#cmdline">Running Apache for Windows from the Command Line</A> + <LI><A HREF="#comp">Compiling Apache for Windows</A> +</UL> + +<HR> + +<H2><A NAME="req">Requirements</A></H2> + +Apache 1.3 is designed to run on Windows NT 4.0. The binary installer +will only work in Intel processors. Apache may also run on Windows 95 +and Windows NT 3.5.1, but these have not been tested. In all cases +TCP/IP networking must be installed. + +<P> + +If running on Windows 95, using the "Winsock2" upgrade is recommended +but may not be necessary. If running on NT 4.0, installing Service Pack 2 +is recommended. + +<H2><A NAME="down">Downloading Apache for Windows</A></H2> + +<P>Information on the latest version of Apache can be found on the +Apache web server at <A +HREF="http://www.apache.org/">http://www.apache.org/</A>. This will +list the current release, any more recent alpha or beta-test releases, +together with details of mirror web and anonymous ftp sites.</P> + +<P> + +You should download the version of Apache for Windows with the +<CODE>.exe</CODE> extension. This is a single file containing Apache, +ready to install and run. There may also be a <CODE>.zip</CODE> file +containing the source code, to compile Apache yourself. (If there is +no <SAMP>.zip</SAMP> file, the source will be available in a +<SAMP>.tar.gz</SAMP> file but this will contain Unix line endings. You +will have to convert at least the <SAMP>.mak</SAMP> and +<SAMP>.dsp</SAMP> files to have DOS line endings before MSVC will +understand them). + +<H2><A NAME="inst">Installing Apache for Windows</A></H2> + +Run the Apache <SAMP>.exe</SAMP> file you downloaded above. This will +ask for: + +<UL> + + <LI>the directory to install Apache into (the default is + <CODE>\Program Files\Apache Group\Apache</CODE> although you can + change this to any other directory) + + <LI>the start menu name (default is "Apache Web Server") + + <LI>the installation type. The "Typical" option installs + everything except the source code. The "Minimum" option does not + install the manuals or source code. Choose the "Custom" install if + you want to install the source code. + +</UL> + +<P> + +During the installation, Apache will configure the files in the +<SAMP>conf</SAMP> directory for your chosen installation +directory. However if any of the files in this directory already exist +they will <STRONG>not</STRONG> be overwritten. Instead the new copy of +the corresponding file will be left with the extension +<SAMP>.default</SAMP>. So, for example, if +<SAMP>conf\httpd.conf</SAMP> already exists it will not be altered, +but the version which would have been installed will be left in +<SAMP>conf\httpd.conf.default</SAMP>. After the installation has +finished you should manually check to see what in new in the +<SAMP>.default</SAMP> file, and if necessary update your existing +configuration files. + +<P> + +Also, if you already have a file called <SAMP>htdocs\index.html</SAMP> +then it will not be overwritten (no <SAMP>index.html.default</SAMP> +file will be installed either). This should mean it a safe to install +Apache over an existing installation (but you will have to stop the +existing server running before doing the installation, then start the +new one after the installation is finished). + +<P> + +<BLOCKQUOTE> +<STRONG>Important note for 1.3b6 installs</STRONG>: the above only +applies for 1.3b7 and later. In 1.3b6 the installer would overwrite +any existing <SAMP>httpd.conf</SAMP>, <SAMP>access.conf</SAMP>, +<SAMP>srm.conf</SAMP> or <SAMP>mime.types</SAMP> files in the +<SAMP>conf</SAMP>, and will also overwrite your +<SAMP>index.html</SAMP> file in the <SAMP>htdocs</SAMP> directory. You +should copy these files or directories before installing Apache 1.3b6 +or install into a new directory. +</BLOCKQUOTE> + +<P> + +After installing Apache, you should edit the configuration files in +the <SAMP>conf</SAMP> directory as required. These files will be +configured during the install ready for Apache to be run from the +directory where it was installed, with the documents served from the +subdirectory <SAMP>htdocs</SAMP>. There are lots of other options +which should be set before you start really using Apache. However to +get started quickly the files should work as installed. + +<H2><A NAME="run">Running Apache for Windows</A></H2> + +There are two ways you can run Apache: + +<UL> + <LI>As a "service" (available on NT only). This is the best option if + you want Apache to automatically start when you machine boots, and to + keep Apache running when you log-off. + + <LI>From a <A HREF="#cmdline">console window</A>. This is the only option + available for + Windows 95 users. +</UL> + +To start Apache as a service, you first need to install it as a +service. Run the "Install Apache as Service" option from the Start +menu. Once this is done you can start Apache by opening the Services +window (in the Control Panel), selecting Apache, then clicking on +Start. Apache will now be running in the background. You can later +stop Apache by clicking on Stop. As an alternative to using the +Services window, you can start and stop Apache from the control line +with + +<PRE> + NET START APACHE + NET STOP APACHE +</PRE> + +To run Apache from a console window, select the "Apache Server" option +from the Start menu. This will open a console window and start Apache +running inside it. The window will remain active until you stop +Apache. To stop Apache running, press Control-C within the console +window. + +<P> + +After starting Apache running (either in a console window or as a +service) if will be listening to port 80 (unless you changed the +<SAMP>Port</SAMP>, <SAMP>Listen</SAMP> or <SAMP>BindAddress</SAMP> +directives in the configuration files). To connect to the server and +access the default page, launch a browser and enter this URL: + +<PRE> + http://localhost/ +</PRE> + +This should respond with a welcome page, and a link to the Apache +manual. If nothing happens or you get an error, look in the +<SAMP>error_log</SAMP> file in the <SAMP>logs</SAMP> directory. + +<P> + +Once your basic installation is working, you should configure it +properly by editing the files in the <SAMP>conf</SAMP> directory. + +<H2><A NAME="use">Configuring Apache for Windows</A></H2> + +Apache is configured by files in the <SAMP>conf</SAMP> +directory. These are the same as files used to configure the Unix +version, but there are a few different directives for Apache on +Windows. See the <A HREF="./">Apache documentation</A> for all the +available directives. + +<P> + +The main differences in Apache for Windows are: + +<UL> + <LI><P>Because Apache for Windows is multithreaded, it does not use a + separate process for each request, as Apache does with + Unix. Instead there are usually only two Apache processes running: + a parent process, and a child which handles the requests. Within + the child each request is handled by a separate thread. + <P> + + So the "process"-management directives are different: + <P><A + HREF="mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A> + - Like the Unix directive, this controls how many requests a + process will serve before exiting. However, unlike Unix, a + process serves all the requests at once, not just one, so if + this is set, it is recommended that a very high number is + used. The recommended default, <CODE>MaxRequestsPerChild + 0</CODE>, does not cause the process to ever exit. + <P><A HREF="mod/core.html#threadsperchild">ThreadsPerChild</A> - + This directive is new, and tells the server how many threads it + should use. This is the maximum number of connections the server + can handle at once; be sure and set this number high enough for + your site if you get a lot of hits. The recommended default is + <CODE>ThreadsPerChild 50</CODE>.</P> + <LI><P>The directives that accept filenames as arguments now must use + Windows filenames instead of Unix ones. However, because Apache + uses Unix-style names internally, you must use forward slashes, not + backslashes. Drive letters can be used; if omitted, the drive with + the Apache executable will be assumed.</P> + <LI><P>Apache for Windows contains the ability to load modules at runtime, + without recompiling the server. If Apache is compiled normally, it + will install a number of optional modules in the + <CODE>\Apache\modules</CODE> directory. To activate these, or other + modules, the new <A HREF="mod/mod_so.html#loadmodule">LoadModule</A> + directive must be used. For example, to active the status module, + use the following (in addition to the status-activating directives + in <CODE>access.conf</CODE>):</P> +<PRE> + LoadModule status_module modules/ApacheModuleStatus.dll +</PRE> + <P>Information on <A HREF="mod/mod_so.html#creating">creating loadable + modules</A> is also available.</P> + <LI><P>Apache can also load ISAPI Extensions (<EM>i.e.</EM>, Internet Server + Applications), such as those used by Microsoft's IIS, and other + Windows servers. <A HREF="mod/mod_isapi.html">More information + is available.</A> +</UL> + +<H2><A NAME="cmdline">Running Apache for Windows from the Command Line</A></H2> + +The Start menu icons and the NT Service manager can provide an simple +interafce for administering Apache. But in some cases it is easier to +work from the command line. + +<P> +When working with Apache it is important to know how it will find the +configuration files. Apache will try one of the following, in this order. + +<UL> +<LI>A ServerRoot directive via a -C switch. +<LI>The -f switch on the command line. +<LI>The -d switch on the command line. +<LI>A registry entry, created if you did a binary install. +<LI>The server root compiled into the server. +</UL> + +<P> +The server root compiled into the server is usually "/apache". +invoking apache with the -v switch will display this value +labeled as HTTPD_ROOT. + +<P> +Your current working directory when Apache is started up has no +effect on Apache's behavior. + +<P> +Under windows, when invoked from the start menu or the Service Manager Apache is +usually passed no arguments. So using the registry entry is the perfered +technique. + +<P> +During a binary installation, a registry key will have +been installed, for example: +<PRE> + HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.1\ServerRoot +</PRE> + +<P> +This key is compiled into the server and can enable you to test +new versions without affecting the current version. Of course +you must take care not to install the new version on top of the +old version in the file system. You can not run two invocations +of Apache on Windows simultaneously. + +<P> +If you did not do a binary install then Apache will in some +senarios complain that about the missing registry key. This +warning can be ignored if it otherwise was able to find it's +configuration files. + +<P> +The value of this key is the "ServerRoot" directory, containing the +<SAMP>conf</SAMP> directory. When Apache starts it will read the +<SAMP>httpd.conf</SAMP> file from this directory. If this file +contains a <SAMP>ServerRoot</SAMP> directive which is different from +the directory obtained from the registry key above, Apache will forget +the registry key and use the directory from the configuration file. +If you copy the Apache directory or configuration files to a new +location it is vital that you update the <SAMP>ServerRoot</SAMP> +directory in the <SAMP>httpd.conf</SAMP> file to the new location. + +<P> +To run Apache from the command line as a console application, use the +following command: + +<PRE> + apache -s +</PRE> + +Apache will execute, and will remain running until it is stopped by pressing +control-C. (The -s option is not required by Windows 95, but on Windows NT it +prevents Apache waiting to see if Apache is running as a service.) + +<P> + +To install Apache as a Windows NT service as follows: + +<PRE> + apache -i +</PRE> + +and to remove the Apache service, use + +<PRE> + apache -u +</PRE> + + +<H2><A NAME="comp">Compiling Apache for Windows</A></H2> + +<P>Compiling Apache requires Microsoft Visual C++ 5.0 to be properly + installed. It is easiest to compile with the command-line tools + (nmake, <EM>etc.</EM>..). Consult the VC++ manual to determine how to install + them.</P> + +<P>First, unpack the Apache distribution into an appropriate + directory. Open a command-line prompt, and change to the + <CODE>src</CODE> subdirectory of the Apache distribution.</P> + +<P>The master Apache makefile instructions are contained in the + <CODE>Makefile.nt</CODE> file. To compile Apache, simply use one of + the following commands: +<UL> +<LI><CODE>nmake /f Makefile.nt _apacher</CODE> (release build) +<LI><CODE>nmake /f Makefile.nt _apached</CODE> (debug build) +</UL> + +<P>These will both compile Apache. The latter will include debugging + information in the resulting files, making it easier to find bugs and + track down problems.</P> + +<P>Apache can also be compiled using VC++'s Visual Studio development + environment. Although compiling Apache in this manner is not as + simple, it makes it possible to easily modify the Apache source, or + to compile Apache if the command-line tools are not installed. + Project files (<CODE>.DSP</CODE>) are included for each of the + portions of Apache. To build Apache from the these projects files + you will need to build the following projects <EM>in this order</EM>: + + <OL> + <LI><CODE>os\win32\ApacheOS.dsp</CODE> + <LI><CODE>regex\regex.dsp</CODE> + <LI><CODE>ap\ap.dsp</CODE> + <LI><CODE>main\gen_uri_delims.dsp</CODE> + <LI><CODE>main\gen_test_char.dsp</CODE> + <LI><CODE>ApacheCore.dsp</CODE> + <LI><CODE>Apache.dsp</CODE> + </OL> + + In addition, the <CODE>src\os\win32</CODE> subdirectory contains + project files for the optional modules (see below).</P> + +<P>Once Apache has been compiled, it needs to be installed in its server + root directory. The default is the <CODE>\Apache</CODE> + directory, on the current hard drive. </P> + +<P>To install the files into the <CODE>\Apache</CODE> directory + automatically, use one the following nmake commands (see above):</P> +<UL> +<LI><CODE>nmake /f Makefile.nt installr INSTDIR=<EM>dir</EM></CODE> + (for release build) +<LI><CODE>nmake /f Makefile.nt installd INSTDIR=<EM>dir</EM></CODE> + (for debug build) +</UL> + +The dir argument to INSTDIR gives the installation directory. The can +be omitted if Apache is to be installed into <SAMP>\Apache</SAMP>. + +<P>This will install the following:</P> + +<UL> + <LI><CODE><EM>dir</EM>\Apache.exe</CODE> - Apache executable + <LI><CODE><EM>dir</EM>\ApacheCore.dll</CODE> - Main Apache shared library + <LI><CODE><EM>dir</EM>\modules\ApacheModule*.dll</CODE> - Optional Apache + modules (7 files) + <LI><CODE><EM>dir</EM>\conf</CODE> - Empty configuration directory + <LI><CODE><EM>dir</EM>\logs</CODE> - Empty logging directory +</UL> + +<P>If you do not have nmake, or wish to install in a different directory, + be sure to use a similar naming scheme.</P> + +<P> +Before running the server you must fill out the conf directory. +Copy the *.conf-dist-win from the distribution conf directory +and rename *.conf. Edit the @@ServerRoot@@ entries to your +actual server root (for example "C:\apache"). Copy over +the conf/magic and conf/mime.types files as well. + +<HR> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> + +<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> + +</BODY> +</HTML> |
