getting-started.xml revision f9569bee58de8f7a4f4ceb5bcacdaa07e1950603
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
cfc8d7e580247950151dbf37f022dd2d09168138igalic<!-- $LastChangedRevision$ -->
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen Licensed to the Apache Software Foundation (ASF) under one or more
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen contributor license agreements. See the NOTICE file distributed with
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen this work for additional information regarding copyright ownership.
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen The ASF licenses this file to You under the Apache License, Version 2.0
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen (the "License"); you may not use this file except in compliance with
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen the License. You may obtain a copy of the License at
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen Unless required by applicable law or agreed to in writing, software
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen distributed under the License is distributed on an "AS IS" BASIS,
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen See the License for the specific language governing permissions and
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen limitations under the License.
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<p>If you're completely new to the Apache HTTP Server, or even to running
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowena website at all, you might not know where to start, or what questions to
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenask. This document walks you through the basics.</p>
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenAddresses on the Web are expressed with URLs - Uniform Resource Locators
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen- which specify a protocol (e.g. <code>http</code>), a servername (e.g.
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<code>/docs/current/getting-started.html</code>), and possibly a query
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenstring (e.g. <code>?arg=value</code>) used to pass additional
650165e708b80320ce16e623113ad702c663aa40jailletcarguments to the server.
650165e708b80320ce16e623113ad702c663aa40jailletc<p>A client (e.g., a web browser) connects to a server (e.g., your Apache HTTP Server),
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenwith the specified protocol, and makes a <strong>request</strong> for a resource using the
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenURL-path.</p>
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<p>The URL-path may represent any number of things on the server. It may
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenbe a file (like <code>getting-started.html</code>) a handler (like <a
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenhref="mod/mod_status.html">server-status</a>) or some kind of program
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenfile (like <code>index.php</code>). We'll discuss this more below in
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenthe <a href="#content">Web Site Content</a> section.</p>
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenThe server will send a <strong>response</strong> consisting of a status
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowencode and, optionally, a response body.
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenThe status code indicates whether the request was successful, and, if not, what
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenkind of error condition there was. This tells the client what it should
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowendo with the response. You can read about the possible response codes in
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<a href="http://wiki.apache.org/httpd/CommonHTTPStatusCodes">HTTP Server
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<p>Details of the transaction, and any error conditions, are written to
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenlog files. This is discussed in greater detail below in the <a
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenhref="#logs">Logs Files and Troubleshooting</a> section.</p>
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<p>In order to connect to a server, the client will first have to resolve
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenthe servername to an IP address - the location on the Internet where the
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenserver resides. Thus, in order for your web server to be reachable, it
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenis necessary that the servername be in DNS.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<p>More than one hostname may point to the same IP address, and more
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenthan one IP address can be attached to the same physical server. Thus, you
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowencan run more than one web site on the same physical server, using a
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenfeature called <a href="vhosts/">virtual hosts</a>.</p>
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<p>If you don't know how to do this, you'll need to contact your network
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenadministrator, or Internet service provider, to perform this step for
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<p>If you are testing a server that is not Internet-accessible, you
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowencan put host names in your hosts file in order to do local resolution.
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenFor example, you might want to put a record in your hosts file to map a
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenrequest for <code>www.example.com</code> to your local system, for
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowentesting purposes. This entry would look like:</p>
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<p>A hosts file will probably be located at <code>/etc/hosts</code> or
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen<code>C:\Windows\system32\drivers\etc\hosts</code>.</p>
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenhref="http://en.wikipedia.org/wiki/Hosts_(file)">Wikipedia.org/wiki/Hosts_(file)</a>, and
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenmore about DNS at <a
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowenhref="http://en.wikipedia.org/wiki/Domain_Name_System">Wikipedia.org/wiki/Domain_Name_System</a>.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<p>The Apache HTTP Server is configured via simple text files.
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenThese files may be located any of a variety of places, depending on how
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenexactly you installed the server. Common locations for these files may
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenbe found <a href="http://wiki.apache.org/httpd/DistrosDefaultLayout">in
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenthe httpd wiki</a>. If you installed httpd from source, the default
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenlocation of the configuration files is
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<code>/usr/local/apache2/conf</code>. The default configuration file is
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenusually called <code>httpd.conf</code>. This, too, can vary in
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenthird-party distributions of the server.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<p>The configuration is frequently broken into multiple smaller files,
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenfor ease of management. These files are loaded via the <directive
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenmodule="core">Include</directive> directive. The names or locations of
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenthese sub-files are not magical, and may vary greatly from one
d34ef6c1f905c08b7f4b27de06b9694111c45c19rboweninstallation to another. Arrange and subdivide these files as
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenmakes the most sense to <strong>you</strong>. If the file arrangement
4c14866954f240e6e2c17c164900c4aa7900bbeehumbedoohyou have by default doesn't make sense to you, feel free to rearrange it.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenhref="mod/quickreference.html">configuration directives</a> in these
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenconfiguration files. A directive is a keyword followed by one or more
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenarguments that set its value.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowendirective?</em>" is generally answered by considering where you want a
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowendirective to be effective. If it is a global setting, it should appear
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenin the configuration file, outside of any <directive
f9569bee58de8f7a4f4ceb5bcacdaa07e1950603jailletctype="section" module="core">Directory</directive>, <directive
f9569bee58de8f7a4f4ceb5bcacdaa07e1950603jailletctype="section" module="core">Location</directive>, <directive
f9569bee58de8f7a4f4ceb5bcacdaa07e1950603jailletctype="section" module="core">VirtualHost</directive>, or other section. If it is to
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenapply only to a particular directory, then it should go inside a
f9569bee58de8f7a4f4ceb5bcacdaa07e1950603jailletc<directive type="section" module="core">Directory</directive> section referring to
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenthat directory, and so on. See the <a href="sections.html">Configuration
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenSections</a> document for further discussion of these sections.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<p>In addition to the main configuration files, certain directives may go in
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<code>.htaccess</code> files located in the content directories.
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<code>.htaccess</code> files are primarily for people who do not have
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenaccess to the main server configuration file(s). You can read more about
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenhref="howto/htaccess.html"><code>.htaccess</code> howto</a>.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<p>Web site content can take many different forms, but may be broadly
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowendivided into static and dynamic content.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<p>Static content is things like HTML files, image files, CSS files,
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenand other files that reside in the filesystem. The <directive
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenmodule="core">DocumentRoot</directive> directive specifies where in your
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenfilesystem you should place these files. This directive is either set
4c14866954f240e6e2c17c164900c4aa7900bbeehumbedoohglobally, or per virtual host. Look in your configuration file(s) to
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowendetermine how this is set for your server.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<p>Typically, a document called <code>index.html</code> will be served
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenwhen a directory is requested without a file name being specified. For
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<code>/var/www/html/work/index.html</code> will be served to the
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<p>Dynamic content is anything that is generated at request
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowentime, and may change from one request to another. There are numerous
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenways that dynamic content may be generated. Various <a
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenhref="handler.html">handlers</a> are available to generate content. <a
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenhref="howto/cgi.html">CGI programs</a> may be written to generate
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowencontent for your site.</p>
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowen<p>Third-party modules like mod_php may be used to write code that does a
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenvariety of things. Many third-party applications, written using a
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenvariety of languages and tools, are available for download and
d34ef6c1f905c08b7f4b27de06b9694111c45c19rboweninstallation on your Apache HTTP Server. Support of these third-party
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenthings is beyond the scope of this documentation, and you should find
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowentheir documentation or other support forums to answer your questions
d34ef6c1f905c08b7f4b27de06b9694111c45c19rbowenabout them.</p>
d33a7c3f7d739e98c2f781bfff73911ee13caaf1rbowen<p>As an Apache HTTP Server administrator, your most valuable assets are
0197cee5161da51ee309edd93275512f21eb00f0rbowenthe log files, and, in particular, the error log. Troubleshooting any
0197cee5161da51ee309edd93275512f21eb00f0rbowenproblem without the error log is like driving with your eyes closed.</p>
0197cee5161da51ee309edd93275512f21eb00f0rbowen<p>The location of the error log is defined by the <directive
0197cee5161da51ee309edd93275512f21eb00f0rbowenmodule="core">ErrorLog</directive> directive, which may be set globally,
0197cee5161da51ee309edd93275512f21eb00f0rbowenor per virtual host. Entries in the error log tell you what went wrong,
0197cee5161da51ee309edd93275512f21eb00f0rbowenand when. They often also tell you how to fix it. Each error log message
0197cee5161da51ee309edd93275512f21eb00f0rbowencontains a error code, which you can search for online for even more
0197cee5161da51ee309edd93275512f21eb00f0rbowendetailed descriptions of how to address the problem. You can also
0197cee5161da51ee309edd93275512f21eb00f0rbowenconfigure your error log to contain a log ID which you can then
0197cee5161da51ee309edd93275512f21eb00f0rbowencorrelate to an access log entry, so that you can determine what request
0197cee5161da51ee309edd93275512f21eb00f0rbowencaused the error condition.</p>
0197cee5161da51ee309edd93275512f21eb00f0rbowen<p>You can read more about logging in the <a href="logs.html">logs
0197cee5161da51ee309edd93275512f21eb00f0rbowen<p>This document covers only the bare basics. We hope that this gets you
0197cee5161da51ee309edd93275512f21eb00f0rbowenstarted, but there are many other things that you might need to know.
0197cee5161da51ee309edd93275512f21eb00f0rbowenHere's a partial list of what you might be looking for:</p>
0197cee5161da51ee309edd93275512f21eb00f0rbowen<li><a href="howto/auth.html">Authentication and Authorization (password protecting resources)</a></li>
0197cee5161da51ee309edd93275512f21eb00f0rbowen<li><a href="howto/access.html">Access Control</a></li>
0197cee5161da51ee309edd93275512f21eb00f0rbowen<li><a href="ssl/ssl_howto.html">Setting up SSL</a></li>
0197cee5161da51ee309edd93275512f21eb00f0rbowen<li><a href="http://wiki.apache.org/httpd/FAQ">Frequently Asked Questions</a></li>
be687b5f26bdb1a7795c01f6994ce8bd108943a1rbowen</manualpage>