Commit c5916efd authored by paul's avatar paul
Browse files

New manual setup. This is the current docs for all versions of the 

server merged into a single manual.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@76987 13f79535-47bb-0310-9956-ffa450edef68
parent a30ad39c

docs/manual/LICENSE

0 → 100644
+51 −0
Original line number Diff line number Diff line 


Apache httpd license

 ====================





This is the license for the Apache Server. It covers all the

files which come in this distribution, and should never be removed.



The "Apache Group" has based this server, called "Apache", on

public domain code distributed under the name "NCSA httpd 1.3".



NCSA httpd 1.3 was placed in the public domain by the National Center 

for Supercomputing Applications at the University of Illinois 

at Urbana-Champaign.



As requested by NCSA we acknowledge,



  "Portions developed at the National Center for Supercomputing

   Applications at the University of Illinois at Urbana-Champaign."



Copyright on the sections of code added by the "Apache Group" belong

to the "Apache Group" and/or the original authors. The "Apache Group" and

authors hereby grant permission for their code, along with the

public domain NCSA code, to be distributed under the "Apache" name.



Reuse of "Apache Group" code outside of the Apache distribution should

be acknowledged with the following quoted text, to be included with any new

work;



 "Portions developed by the "Apache Group", taken with permission 

    from the Apache Server   http://www.hyperreal.com/apache/   "





Permission is hereby granted to anyone to redistribute Apache under

the "Apache" name. We do not grant permission for the resale of Apache, but

we do grant permission for vendors to bundle Apache free with other software,

or to charge a reasonable price for redistribution, provided it is made

clear that Apache is free. Permission is also granted for vendors to 

sell support for for Apache. We explicitly forbid the redistribution of 

Apache under any other name.



The "Apache Group" makes no promises to support "Apache". Users and

sellers of Apache support, and users of "Apache Group" code, should be 

aware that they use "Apache" or portions of the "Apache Group" code at 

their own risk. While every effort has been made to ensure that "Apache"

is robust and safe to use, we will not accept responsibility for any

damage caused, or loss of data or income which results from its use.







Apache httpd server (c) 1995 The Apache Group.

docs/manual/bind.html

0 → 100644
+103 −0
Original line number Diff line number Diff line 
<html><head>

<title>Setting which addresses and ports Apache uses</title>

</head><body>



<img src="../images/apache_sub.gif" alt="">

<h1>Setting which addresses and ports Apache uses</h1>



<hr>



When Apache starts, it connects to some port and address on the

local machine and waits for incoming requests. By default, it

listens to all addresses on the machine, and to the port

as specified by the <tt>Port</tt> directive in the server configuration.

However, it can be told to listen to more the one port, or to listen

to only selected addresses, or a combination. This is often combined

with the Virtual Host feature which determines how Apache

responds to different IP addresses, hostnames and ports.<p>



There are two directives used to restrict or specify which addresses

and ports Apache listens to.



<ul>

<li><a href="#bindaddress">BindAddress</a> is used to restrict the server to listening to

  a single address, and can be used to permit multiple Apache servers

  on the same machine listening to different IP addresses.

<li><a href="#listen">Listen</a> can be used to make a single Apache server listen

  to more than one address and/or port.

</ul>



<h3><a name="bindaddress">BindAddress</a></h3>

<strong>Syntax:</strong> BindAddress <em>[ * | IP-address | hostname ]</em><br>

<strong>Default:</strong> <code>BindAddress *</code><br>

<strong>Context:</strong> server config<br>

<strong>Status:</strong> Core<p>



Makes the server listen to just the specified address. If the argument

is *, the server listens to all addresses. The port listened to

is set with the <tt>Port</tt> directive. Only one BindAddress

should be used.



<h3><a name="listen">Listen</a></h3>

<strong>Syntax:</strong> Listen <em>[ port | IP-address:port ]</em><br>

<strong>Default:</strong> <code>none</code><br>

<strong>Context:</strong> server config<br>

<strong>Status:</strong> Core<p>



<tt>Listen</tt> can be used instead of <tt>BindAddress</tt> and

<tt>Port</tt>. It tells the server to accept incoming requests on the

specified port or address-and-port combination. If the first format is

used, with a port number only, the server listens to the given port on

all interfaces, instead of the port given by the <tt>Port</tt>

directive. If an IP address is given as well as a port, the server

will listen on the given port and interface.  <p> Multiple Listen

directives may be used to specify a number of addresses and ports to

listen to. The server will respond to requests from any of the listed

addresses and ports.<p>



For example, to make the server accept connections on both port

80 and port 8000, use:

<pre>

   Listen 80

   Listen 8000

</pre>



To make the server accept connections on two specified

interfaces and port numbers, use

<pre>

   Listen 192.170.2.1:80

   Listen 192.170.2.5:8000

</pre>



<h2>How this works with Virtual Hosts</h2>



BindAddress and Listen do not implement Virtual Hosts. They tell the

main server what addresses and ports to listen to.  If no

&lt;VirtualHost&gt; directives are used, the server will behave the

same for all accepted requests. However, &lt;VirtualHost&gt; can be

used to specify a different behavour for one or more of the addresses

and ports. To implement a VirtualHost, the server must first be told

to listen to the address and port to be used. Then a

&lt;VirtualHost&gt; section should be created for a specified address

and port to set the behaviour of this virtual host. Note that if the

&lt;VirtualHost&gt; is set for an address and port that the server is

not listening to, it cannot be accessed.



<h2>See also</h2>



See also the documentation on

<a href="virtual-host.html">Virtual Hosts</a>,

<a href="host.html">Non-IP virtual hosts</a>,

<a href="core.html#bindaddress">BindAddress directive</a>,

<a href="core.html#port">Port directive</a>

and

<a href="core.html#virtualhost">&lt;VirtualHost&gt; section</a>.

</ul>



<hr>

<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>

<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>



</BODY>

</HTML>

docs/manual/bind.html.en

0 → 100644
+103 −0
Original line number Diff line number Diff line 
<html><head>

<title>Setting which addresses and ports Apache uses</title>

</head><body>



<img src="../images/apache_sub.gif" alt="">

<h1>Setting which addresses and ports Apache uses</h1>



<hr>



When Apache starts, it connects to some port and address on the

local machine and waits for incoming requests. By default, it

listens to all addresses on the machine, and to the port

as specified by the <tt>Port</tt> directive in the server configuration.

However, it can be told to listen to more the one port, or to listen

to only selected addresses, or a combination. This is often combined

with the Virtual Host feature which determines how Apache

responds to different IP addresses, hostnames and ports.<p>



There are two directives used to restrict or specify which addresses

and ports Apache listens to.



<ul>

<li><a href="#bindaddress">BindAddress</a> is used to restrict the server to listening to

  a single address, and can be used to permit multiple Apache servers

  on the same machine listening to different IP addresses.

<li><a href="#listen">Listen</a> can be used to make a single Apache server listen

  to more than one address and/or port.

</ul>



<h3><a name="bindaddress">BindAddress</a></h3>

<strong>Syntax:</strong> BindAddress <em>[ * | IP-address | hostname ]</em><br>

<strong>Default:</strong> <code>BindAddress *</code><br>

<strong>Context:</strong> server config<br>

<strong>Status:</strong> Core<p>



Makes the server listen to just the specified address. If the argument

is *, the server listens to all addresses. The port listened to

is set with the <tt>Port</tt> directive. Only one BindAddress

should be used.



<h3><a name="listen">Listen</a></h3>

<strong>Syntax:</strong> Listen <em>[ port | IP-address:port ]</em><br>

<strong>Default:</strong> <code>none</code><br>

<strong>Context:</strong> server config<br>

<strong>Status:</strong> Core<p>



<tt>Listen</tt> can be used instead of <tt>BindAddress</tt> and

<tt>Port</tt>. It tells the server to accept incoming requests on the

specified port or address-and-port combination. If the first format is

used, with a port number only, the server listens to the given port on

all interfaces, instead of the port given by the <tt>Port</tt>

directive. If an IP address is given as well as a port, the server

will listen on the given port and interface.  <p> Multiple Listen

directives may be used to specify a number of addresses and ports to

listen to. The server will respond to requests from any of the listed

addresses and ports.<p>



For example, to make the server accept connections on both port

80 and port 8000, use:

<pre>

   Listen 80

   Listen 8000

</pre>



To make the server accept connections on two specified

interfaces and port numbers, use

<pre>

   Listen 192.170.2.1:80

   Listen 192.170.2.5:8000

</pre>



<h2>How this works with Virtual Hosts</h2>



BindAddress and Listen do not implement Virtual Hosts. They tell the

main server what addresses and ports to listen to.  If no

&lt;VirtualHost&gt; directives are used, the server will behave the

same for all accepted requests. However, &lt;VirtualHost&gt; can be

used to specify a different behavour for one or more of the addresses

and ports. To implement a VirtualHost, the server must first be told

to listen to the address and port to be used. Then a

&lt;VirtualHost&gt; section should be created for a specified address

and port to set the behaviour of this virtual host. Note that if the

&lt;VirtualHost&gt; is set for an address and port that the server is

not listening to, it cannot be accessed.



<h2>See also</h2>



See also the documentation on

<a href="virtual-host.html">Virtual Hosts</a>,

<a href="host.html">Non-IP virtual hosts</a>,

<a href="core.html#bindaddress">BindAddress directive</a>,

<a href="core.html#port">Port directive</a>

and

<a href="core.html#virtualhost">&lt;VirtualHost&gt; section</a>.

</ul>



<hr>

<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>

<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>



</BODY>

</HTML>

docs/manual/content-negotiation.html

0 → 100644
+216 −0
Original line number Diff line number Diff line 
<html>

<head>

<title>Apache server Content arbitration: MultiViews and *.var files</title>

</head>



<body>

<IMG SRC="../images/apache_sub.gif" ALT="">

<h3>Content Arbitration:  MultiViews and *.var files</h3>



The HTTP standard allows clients (i.e., browsers like Mosaic or

Netscape) to specify what data formats they are prepared to accept.

The intention is that when information is available in multiple

variants (e.g., in different data formats), servers can use this

information to decide which variant to send.  This feature has been

supported in the CERN server for a while, and while it is not yet

supported in the NCSA server, it is likely to assume a new importance

in light of the emergence of HTML3 capable browsers. <p>



The Apache module <A HREF="mod_negotiation.html">mod_negotiation</A> handles

content negotiation in two different ways; special treatment for the

pseudo-mime-type <code>application/x-type-map</code>, and the

MultiViews per-directory Option (which can be set in srm.conf, or in

.htaccess files, as usual).  These features are alternate user

interfaces to what amounts to the same piece of code (in the new file

<code>http_mime_db.c</code>) which implements the content negotiation

portion of the HTTP protocol. <p>



Each of these features allows one of several files to satisfy a

request, based on what the client says it's willing to accept; the

differences are in the way the files are identified:



<ul>

  <li> A type map (i.e., a <code>*.var</code> file) names the files

       containing the variants explicitly

  <li> In a MultiViews search, the server does an implicit filename

       pattern match, and chooses from among the results.

</ul>



Apache also supports a new pseudo-MIME type,

text/x-server-parsed-html3, which is treated as text/html;level=3

for purposes of content negotiation, and as server-side-included HTML

elsewhere. 



<h3>Type maps (*.var files)</h3>



A type map is a document which is typed by the server (using its

normal suffix-based mechanisms) as

<code>application/x-type-map</code>.  Note that to use this feature,

you've got to have an <code>AddType</code> some place which defines a

file suffix as <code>application/x-type-map</code>; the easiest thing

may be to stick a

<pre>



  AddType application/x-type-map var



</pre>

in <code>srm.conf</code>.  See comments in the sample config files for

details. <p>



Type map files have an entry for each available variant; these entries

consist of contiguous RFC822-format header lines.  Entries for

different variants are separated by blank lines.  Blank lines are

illegal within an entry.  It is conventional to begin a map file with

an entry for the combined entity as a whole, e.g.,

<pre>



  URI: foo; vary="type,language"



  URI: foo.en.html

  Content-type: text/html; level=2

  Content-language: en



  URI: foo.fr.html

  Content-type: text/html; level=2

  Content-language: fr



</pre>

If the variants have different qualities, that may be indicated by the

"qs" parameter, as in this picture (available as jpeg, gif, or ASCII-art):

<pre>



  URI: foo; vary="type,language"



  URI: foo.jpeg

  Content-type: image/jpeg; qs=0.8



  URI: foo.gif

  Content-type: image/gif; qs=0.5



  URI: foo.txt

  Content-type: text/plain; qs=0.01



</pre><p>



The full list of headers recognized is:



<dl>

  <dt> <code>URI:</code>

  <dd> uri of the file containing the variant (of the given media

       type, encoded with the given content encoding).  These are

       interpreted as URLs relative to the map file; they must be on

       the same server (!), and they must refer to files to which the

       client would be granted access if they were to be requested

       directly. 

  <dt> <code>Content-type:</code>

  <dd> media type --- level may be specified, along with "qs".  These

       are often referred to as MIME types; typical media types are

       <code>image/gif</code>, <code>text/plain</code>, or

       <code>text/html;&nbsp;level=3</code>.

  <dt> <code>Content-language:</code>

  <dd> The language of the variant, specified as an internet standard

       language code (e.g., <code>en</code> for English,

       <code>kr</code> for Korean, etc.).

  <dt> <code>Content-encoding:</code>

  <dd> If the file is compressed, or otherwise encoded, rather than

       containing the actual raw data, this says how that was done.

       For compressed files (the only case where this generally comes

       up), content encoding should be

       <code>x-compress</code>, or <code>gzip</code>, as appropriate.

  <dt> <code>Content-length:</code>

  <dd> The size of the file.  Clients can ask to receive a given media

       type only if the variant isn't too big; specifying a content

       length in the map allows the server to compare against these

       thresholds without checking the actual file.

</dl>



<h3>Multiviews</h3>



This is a per-directory option, meaning it can be set with an

<code>Options</code> directive within a <code>&lt;Directory&gt;</code>

section in <code>access.conf</code>, or (if <code>AllowOverride</code>

is properly set) in <code>.htaccess</code> files.  Note that

<code>Options All</code> does not set <code>MultiViews</code>; you

have to ask for it by name.  (Fixing this is a one-line change to

<code>httpd.h</code>).



<p>



The effect of <code>MultiViews</code> is as follows: if the server

receives a request for <code>/some/dir/foo</code>, if

<code>/some/dir</code> has <code>MultiViews</code> enabled, and

<code>/some/dir/foo</code> does *not* exist, then the server reads the

directory looking for files named foo.*, and effectively fakes up a

type map which names all those files, assigning them the same media

types and content-encodings it would have if the client had asked for

one of them by name.  It then chooses the best match to the client's

requirements, and forwards them along.



<p>



This applies to searches for the file named by the

<code>DirectoryIndex</code> directive, if the server is trying to

index a directory; if the configuration files specify

<pre>



  DirectoryIndex index



</pre> then the server will arbitrate between <code>index.html</code>

and <code>index.html3</code> if both are present.  If neither are

present, and <code>index.cgi</code> is there, the server will run it.



<p>



If one of the files found by the globbing is a CGI script, it's not

obvious what should happen.  My code gives that case gets special

treatment --- if the request was a POST, or a GET with QUERY_ARGS or

PATH_INFO, the script is given an extremely high quality rating, and

generally invoked; otherwise it is given an extremely low quality

rating, which generally causes one of the other views (if any) to be

retrieved.  This is the only jiggering of quality ratings done by the

MultiViews code; aside from that, all Qualities in the synthesized

type maps are 1.0.



<p>



<B>New as of 0.8:</B> Documents in multiple languages can also be resolved through the use

of the <code>AddLanguage</code> and <code>LanguagePriority</code> 

directives:



<pre>

AddLanguage en .en

AddLanguage fr .fr

AddLanguage de .de

AddLanguage da .da

AddLanguage el .el

AddLanguage it .it



# LanguagePriority allows you to give precedence to some languages

# in case of a tie during content negotiation.

# Just list the languages in decreasing order of preference.



LanguagePriority en fr de

</pre>



Here, a request for "foo.html" matched against "foo.html.en" and

"foo.html.fr" would return an French document to a browser that

indicated a preference for French, or an English document otherwise.

In fact, a request for "foo" matched against "foo.html.en",

"foo.html.fr", "foo.ps.en", "foo.pdf.de", and "foo.txt.it" would do

just what you expect - treat those suffices as a database and compare

the request to it, returning the best match.  The languages and data

types share the same suffix name space.



<p>



Note that this machinery only comes into play if the file which the

user attempted to retrieve does <em>not</em> exist by that name; if it

does, it is simply retrieved as usual.  (So, someone who actually asks

for <code>foo.jpeg</code>, as opposed to <code>foo</code>, never gets

<code>foo.gif</code>).



<P><HR><P>

<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>

<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>



</body> </html>

docs/manual/content-negotiation.html.en

0 → 100644
+216 −0

File added.

Preview size limit exceeded, changes collapsed.