svn commit: r44578 - head/en_US.ISO8859-1/books/handbook/network-servers
Dru Lavigne
dru at FreeBSD.org
Wed Apr 16 15:55:47 UTC 2014
Author: dru
Date: Wed Apr 16 15:55:46 2014
New Revision: 44578
URL: http://svnweb.freebsd.org/changeset/doc/44578
Log:
Editorial review of first half of Apache chapter.
Some reshuffling to improve flow.
Add descriptions for virtual hosting and modules.
Add URLs to module config docs.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Apr 16 14:05:35 2014 (r44577)
+++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Apr 16 15:55:46 2014 (r44578)
@@ -4249,18 +4249,19 @@ $include Kexample.com.+005+nnnnn.ZSK.key
</sect1>
<sect1 xml:id="network-apache">
- <!--
- <sect1info>
+ <info>
+ <title>Apache HTTP Server</title>
+
<authorgroup>
<author>
+ <personname>
<firstname>Murray</firstname>
<surname>Stokely</surname>
+ </personname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
- </sect1info>
- -->
- <title>Apache HTTP Server</title>
+ </info>
<indexterm><primary>web servers</primary>
<secondary>setting up</secondary></indexterm>
@@ -4273,7 +4274,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key
<para>This section summarizes how to configure and start version
2.<replaceable>x</replaceable> of the <application>Apache HTTP
- Server</application>, the most widely used version, on &os;.
+ Server</application> on &os;.
For more detailed information about
<application>Apache</application> 2.X and its configuration
directives, refer to <link
@@ -4287,8 +4288,9 @@ $include Kexample.com.+005+nnnnn.ZSK.key
<para>In &os;, the main <application>Apache HTTP
Server</application> configuration file is installed as
- <filename>/usr/local/etc/apache2<replaceable>x</replaceable>/httpd.conf</filename>.
- This ASCII text file begins comment lines with the
+ <filename>/usr/local/etc/apache2<replaceable>x</replaceable>/httpd.conf</filename>,
+ where <replaceable>x</replaceable> represents the version number.
+ This <acronym>ASCII</acronym> text file begins comment lines with a
<literal>#</literal>. The most frequently modified directives
are:</para>
@@ -4301,30 +4303,36 @@ $include Kexample.com.+005+nnnnn.ZSK.key
<application>Apache</application> installation.
Binaries are stored in the <filename>bin</filename> and
<filename>sbin</filename> subdirectories of the server
- root, and configuration files are stored in
+ root and configuration files are stored in the
<filename
- class="directory">etc/apache2<replaceable>x</replaceable></filename>.</para>
+ class="directory">etc/apache2<replaceable>x</replaceable></filename>
+ subdirectory.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>ServerAdmin you at your.address</literal></term>
+ <term><literal>ServerAdmin you at example.com</literal></term>
<listitem>
- <para>The email address to receive problems with the
+ <para>Change this to the email address to receive problems with the
server. This address also appears on some
server-generated pages, such as error documents.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>ServerName www.example.com</literal></term>
+ <term><literal>ServerName www.example.com:80</literal></term>
<listitem>
- <para>Allows an administrator to set a host name which is
+ <para>Allows an administrator to set a hostname which is
sent back to clients for the server. For example,
<systemitem>www</systemitem> can be used instead of the
- actual host name.</para>
+ actual hostname. If the system does not have a
+ registered<acronym>DNS</acronym> name, enter its
+ <acronym>IP</acronym> address instead. If the server
+ will listen on an alternate report, change
+ <literal>80</literal> to the alternate port
+ number.</para>
</listitem>
</varlistentry>
@@ -4342,106 +4350,102 @@ $include Kexample.com.+005+nnnnn.ZSK.key
</varlistentry>
</variablelist>
- <para>It is always a good idea to make backup copies of the
+ <para>It is always a good idea to make a backup copy of the default
<application>Apache</application> configuration file before
making changes. When the configuration of
- <application>Apache</application>, is complete, save the
- file and verify the configuration using apachectl(8).
+ <application>Apache</application> is complete, save the
+ file and verify the configuration using <command>apachectl</command>.
Running <command>apachectl configtest</command> should return
<literal>Syntax OK</literal>.</para>
<indexterm><primary>Apache</primary>
<secondary>starting or stopping</secondary></indexterm>
- <para>The <package>www/apache24</package> port
- installs an &man.rc.8; script to aid in starting, stopping,
- and restarting <application>Apache</application>, which can be
- found in <filename>/usr/local/etc/rc.d/</filename>.</para>
-
<para>To launch <application>Apache</application> at system
startup, add the following line to
<filename>/etc/rc.conf</filename>:</para>
- <programlisting>apache24_enable="YES"</programlisting>
+ <programlisting>apache<replaceable>24</replaceable>_enable="YES"</programlisting>
<para>If <application>Apache</application> should be started
with non-default options, the following line may be added to
<filename>/etc/rc.conf</filename> to specify the needed
flags:</para>
- <programlisting>apache24_flags=""</programlisting>
-
- <para>The <application>Apache</application> configuration can be
- tested for errors after making subsequent configuration
- changes while <command>httpd</command> is running. This can
- be done by the &man.rc.8; script directly, or by the
- &man.service.8; utility by issuing one of the following
- commands:</para>
+ <programlisting>apache<replaceable>24</replaceable>_flags=""</programlisting>
- <screen>&prompt.root; <userinput>service apache24 configtest</userinput></screen>
-
- <note>
- <para>It is important to note that the
- <literal>configtest</literal> is not an &man.rc.8; standard,
- and should not be expected to work for all &man.rc.8;
- startup scripts.</para>
- </note>
-
- <para>If <application>Apache</application> does not report
+ <para>If <application>apachectl</application> does not report
configuration errors, start <command>httpd</command>
- with &man.service.8;:</para>
+ now:</para>
- <screen>&prompt.root; <userinput>service apache24 start</userinput></screen>
+ <screen>&prompt.root; <userinput>service apache<replaceable>24</replaceable> start</userinput></screen>
<para>The <command>httpd</command> service can be tested by
entering
<literal>http://<replaceable>localhost</replaceable></literal>
in a web browser, replacing
<replaceable>localhost</replaceable> with the fully-qualified
- domain name of the machine running <command>httpd</command>,
- if it is not the local machine. The default web page that is
+ domain name of the machine running <command>httpd</command>.
+ The default web page that is
displayed is
- <filename>/usr/local/www/apache24/data/index.html</filename>.</para>
+ <filename>/usr/local/www/apache<replaceable>24</replaceable>/data/index.html</filename>.</para>
+
+ <para>The <application>Apache</application> configuration can be
+ tested for errors after making subsequent configuration
+ changes while <command>httpd</command> is running using
+ the following
+ command:</para>
+
+ <screen>&prompt.root; <userinput>service apache<replaceable>24</replaceable> configtest</userinput></screen>
+
+ <note>
+ <para>It is important to note that
+ <literal>configtest</literal> is not an &man.rc.8; standard,
+ and should not be expected to work for all
+ startup scripts.</para>
+ </note>
</sect2>
<sect2>
<title>Virtual Hosting</title>
- <para><application>Apache</application> supports two different
- types of Virtual Hosting. The first method is Name-based
- Virtual Hosting. Name-based virtual hosting uses the clients
- HTTP/1.1 headers to figure out the hostname. This allows many
- different domains to share the same <acronym>IP</acronym>
+ <para>Virtual hosting allows multiple websites to run on one
+ <application>Apache</application> server. The virtual hosts
+ can be <firstterm>IP-based</firstterm> or
+ <firstterm>name-based</firstterm>. <acronym>IP</acronym>-based
+ virtual hosting uses a different <acronym>IP</acronym> address
+ for each website. Name-based virtual hosting uses the clients
+ HTTP/1.1 headers to figure out the hostname, which allows the
+ websites to share the same <acronym>IP</acronym>
address.</para>
<para>To setup <application>Apache</application> to use
- Name-based Virtual Hosting add an entry like the following to
- <filename>httpd.conf</filename>:</para>
-
- <programlisting>NameVirtualHost *</programlisting>
-
- <para>If the webserver was named <systemitem
- class="fqdomainname">www.domain.tld</systemitem> and
- a virtual domain for <systemitem
- class="fqdomainname">www.someotherdomain.tld</systemitem>
- then add the following entries to
+ name-based virtual hosting, add a
+ <literal>VirtualHost</literal> block for each website. For
+ example, for the webserver named <systemitem
+ class="fqdomainname">www.domain.tld</systemitem> with
+ a virtual domain of <systemitem
+ class="fqdomainname">www.someotherdomain.tld</systemitem>,
+ add the following entries to
<filename>httpd.conf</filename>:</para>
<screen><VirtualHost *>
-ServerName www.domain.tld
-DocumentRoot /www/domain.tld
+ServerName <replaceable>www.domain.tld</replaceable>
+DocumentRoot <replaceable>/www/domain.tld</replaceable>
</VirtualHost>
<VirtualHost *>
-ServerName www.someotherdomain.tld
-DocumentRoot /www/someotherdomain.tld
+ServerName <replaceable>www.someotherdomain.tld</replaceable>
+DocumentRoot <replaceable>/www/someotherdomain.tld</replaceable>
</VirtualHost></screen>
- <para>Replace the addresses with the addresses needed and the
- path to the documents with what are being used.</para>
+ <para>For each virtual host, replace the values for
+ <literal>ServerName</literal> and
+ <literal>DocumentRoot</literal> with the values to be
+ used.</para>
<para>For more information about setting up virtual hosts,
- please consult the official <application>Apache</application>
+ consult the official <application>Apache</application>
documentation at: <uri
xlink:href="http://httpd.apache.org/docs/vhosts/">http://httpd.apache.org/docs/vhosts/</uri>.</para>
</sect2>
@@ -4452,14 +4456,25 @@ DocumentRoot /www/someotherdomain.tld
<indexterm><primary>Apache</primary>
<secondary>modules</secondary></indexterm>
- <para>There are many different <application>Apache</application>
- modules available to add functionality to the basic server.
- The &os; Ports Collection provides an easy way to install
- <application>Apache</application> together with some of the
- more popular add-on modules.</para>
+ <para><application>Apache</application> uses
+ modules to augment the functionality provided by the basic
+ server. Refer to <uri
+ xlink:href="http://httpd.apache.org/docs/current/mod/">http://httpd.apache.org/docs/current/mod/</uri>
+ for a complete listing of and the configuration details for
+ the available modules.</para>
+
+ <para>In &os;, some modules can be compiled with the
+ <package>www/apache24</package> port. Type <command>make
+ config</command> within
+ <filename>/usr/ports/www/apache24</filename> to see which
+ modules are available and which are enabled by
+ default. If the module is not compiled with the port, the
+ &os; Ports Collection provides an easy way to install
+ many modules. This section describes three of the most
+ commonly used modules.</para>
<sect3>
- <title><application>mod_ssl</application></title>
+ <title><filename>mod_ssl</filename></title>
<indexterm>
<primary>web servers</primary>
@@ -4468,157 +4483,56 @@ DocumentRoot /www/someotherdomain.tld
<indexterm><primary>SSL</primary></indexterm>
<indexterm><primary>cryptography</primary></indexterm>
- <para>The <application>mod_ssl</application> module uses the
- OpenSSL library to provide strong cryptography via the
- Secure Sockets Layer (SSL v2/v3) and Transport Layer
- Security (TLS v1) protocols. This module provides
+ <para>The <filename>mod_ssl</filename> module uses the
+ <application>OpenSSL</application> library to provide strong cryptography via the
+ Secure Sockets Layer (<acronym>SSLv3</acronym>) and Transport Layer
+ Security (<acronym>TLSv1</acronym>) protocols. This module provides
everything necessary to request a signed certificate from a
trusted certificate signing authority to run a secure web
server on &os;.</para>
- <para>The <application>mod_ssl</application> module is built
- by default, but can be enabled by specifying
- <literal>-DWITH_SSL</literal> at compile time.</para>
- </sect3>
-
- <sect3>
- <title>Language Bindings</title>
-
- <para>There are Apache modules for most major scripting
- languages. These modules typically make it possible to
- write <application>Apache</application> modules entirely in
- a scripting language. They are also often used as a
- persistent interpreter embedded into the server that avoids
- the overhead of starting an external interpreter and the
- startup-time penalty for dynamic websites, as described in
- the next section.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Dynamic Websites</title>
-
- <indexterm>
- <primary>web servers</primary>
- <secondary>dynamic</secondary>
- </indexterm>
-
- <para>In the last decade, more businesses have turned to the
- Internet in order to enhance their revenue and increase
- exposure. This has also increased the need for interactive
- web content. While some companies, such as µsoft;,
- have introduced solutions into their proprietary products,
- the open source community answered the call. Modern options
- for dynamic web content include Django, Ruby on Rails,
- <application>mod_perl2</application>, and
- <application>mod_php</application>.</para>
-
- <sect3>
- <title>Django</title>
-
- <indexterm><primary>Python</primary></indexterm>
- <indexterm><primary>Django</primary></indexterm>
-
- <para>Django is a BSD licensed framework designed to allow
- developers to write high performance, elegant web
- applications quickly. It provides an object-relational
- mapper so that data types are developed as Python objects,
- and a rich dynamic database-access API is provided for those
- objects without the developer ever having to write SQL. It
- also provides an extensible template system so that the
- logic of the application is separated from the HTML
- presentation.</para>
-
- <para>Django depends on <application>mod_python</application>,
- <application>Apache</application>, and an SQL database
- engine. The &os; Port will install all of
- these pre-requisites with the appropriate
- flags.</para>
-
- <example xml:id="network-www-django-install">
- <title>Installing Django with
- <application>Apache2</application>,
- <application>mod_python3</application>, and
- <application>PostgreSQL</application></title>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL</userinput></screen>
- </example>
-
- <para>Once Django and these pre-requisites are installed,
- the application will need a Django project directory along
- with the Apache configuration to use the embedded Python
- interpreter. This will be the interpreter to
- call the application for specific URLs on the site.</para>
-
- <example xml:id="network-www-django-apache-config">
- <title>Apache Configuration for Django/mod_python</title>
-
- <para>A line must be added to the apache
- <filename>httpd.conf</filename> file to configure Apache
- to pass requests for certain URLs to the web
- application:</para>
-
- <screen><Location "/">
- SetHandler python-program
- PythonPath "['/dir/to/the/django/packages/'] + sys.path"
- PythonHandler django.core.handlers.modpython
- SetEnv DJANGO_SETTINGS_MODULE mysite.settings
- PythonAutoReload On
- PythonDebug On
-</Location></screen>
- </example>
- </sect3>
-
- <sect3>
- <title>Ruby on Rails</title>
-
- <indexterm><primary>Ruby on Rails</primary></indexterm>
-
- <para>Ruby on Rails is another open source web framework that
- provides a full development stack and is optimized to make
- web developers more productive and capable of writing
- powerful applications quickly. It can be installed easily
- from the ports system.</para>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/www/rubygem-rails; make all install clean</userinput></screen>
+ <para>In &os;, <filename>mod_ssl</filename> module is enabled
+ by default in both the package and the port. The available
+ configuration directives are explained at <uri
+ xlink:href="http://httpd.apache.org/docs/current/mod/mod_ssl.html">http://httpd.apache.org/docs/current/mod/mod_ssl.html</uri>.</para>
</sect3>
<sect3>
- <title><application>mod_perl2</application></title>
+ <title><filename>mod_perl2</filename></title>
<indexterm>
<primary>mod_perl2</primary>
<secondary>Perl</secondary>
</indexterm>
- <para>The <application>Apache</application>/Perl integration
- project brings together the full power of the Perl
- programming language and the
- <application>Apache HTTP Server</application>. With the
- <application>mod_perl2</application> module it is possible
- to write <application>Apache</application> modules entirely
- in Perl. In addition, the persistent interpreter embedded
+ <para>The
+ <filename>mod_perl2</filename> module makes it possible
+ to write <application>Apache</application> modules
+ in <application>Perl</application>. In addition, the persistent interpreter embedded
in the server avoids the overhead of starting an external
- interpreter and the penalty of Perl start-up time.</para>
+ interpreter and the penalty of <application>Perl</application> start-up time.</para>
- <para><application>mod_perl2</application> is available in the
- <package>www/mod_perl2</package>
- port.</para>
+ <para>The <filename>mod_perl2</filename> can be installed using the
+ <package>www/mod_perl2</package> package or
+ port. Documentation for using this module can be found at
+ <uri
+ xlink:href="http://perl.apache.org/docs/2.0/index.html">http://perl.apache.org/docs/2.0/index.html</uri>.</para>
</sect3>
<sect3>
- <!--
- <sect3info>
+ <info>
+ <title><application>mod_php</application></title>
+
<authorgroup>
<author>
+ <personname>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
+ </personname>
<contrib>Written by </contrib>
</author>
</authorgroup>
- </sect3info>
- -->
- <title><application>mod_php</application></title>
+ </info>
<indexterm>
<primary>mod_php</primary>
@@ -4717,6 +4631,95 @@ DocumentRoot /www/someotherdomain.tld
<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>
</sect3>
</sect2>
+
+ <sect2>
+ <title>Dynamic Websites</title>
+
+ <indexterm>
+ <primary>web servers</primary>
+ <secondary>dynamic</secondary>
+ </indexterm>
+
+ <para>In the last decade, more businesses have turned to the
+ Internet in order to enhance their revenue and increase
+ exposure. This has also increased the need for interactive
+ web content. While some companies, such as µsoft;,
+ have introduced solutions into their proprietary products,
+ the open source community answered the call. Modern options
+ for dynamic web content include Django, Ruby on Rails,
+ <application>mod_perl2</application>, and
+ <application>mod_php</application>.</para>
+
+ <sect3>
+ <title>Django</title>
+
+ <indexterm><primary>Python</primary></indexterm>
+ <indexterm><primary>Django</primary></indexterm>
+
+ <para>Django is a BSD licensed framework designed to allow
+ developers to write high performance, elegant web
+ applications quickly. It provides an object-relational
+ mapper so that data types are developed as Python objects,
+ and a rich dynamic database-access API is provided for those
+ objects without the developer ever having to write SQL. It
+ also provides an extensible template system so that the
+ logic of the application is separated from the HTML
+ presentation.</para>
+
+ <para>Django depends on <application>mod_python</application>,
+ <application>Apache</application>, and an SQL database
+ engine. The &os; Port will install all of
+ these pre-requisites with the appropriate
+ flags.</para>
+
+ <example xml:id="network-www-django-install">
+ <title>Installing Django with
+ <application>Apache2</application>,
+ <application>mod_python3</application>, and
+ <application>PostgreSQL</application></title>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL</userinput></screen>
+ </example>
+
+ <para>Once Django and these pre-requisites are installed,
+ the application will need a Django project directory along
+ with the Apache configuration to use the embedded Python
+ interpreter. This will be the interpreter to
+ call the application for specific URLs on the site.</para>
+
+ <example xml:id="network-www-django-apache-config">
+ <title>Apache Configuration for Django/mod_python</title>
+
+ <para>A line must be added to the apache
+ <filename>httpd.conf</filename> file to configure Apache
+ to pass requests for certain URLs to the web
+ application:</para>
+
+ <screen><Location "/">
+ SetHandler python-program
+ PythonPath "['/dir/to/the/django/packages/'] + sys.path"
+ PythonHandler django.core.handlers.modpython
+ SetEnv DJANGO_SETTINGS_MODULE mysite.settings
+ PythonAutoReload On
+ PythonDebug On
+</Location></screen>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Ruby on Rails</title>
+
+ <indexterm><primary>Ruby on Rails</primary></indexterm>
+
+ <para>Ruby on Rails is another open source web framework that
+ provides a full development stack and is optimized to make
+ web developers more productive and capable of writing
+ powerful applications quickly. It can be installed easily
+ from the ports system.</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/www/rubygem-rails; make all install clean</userinput></screen>
+ </sect3>
+ </sect2>
</sect1>
<sect1 xml:id="network-ftp">
More information about the svn-doc-all
mailing list