os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Editorial review of first half of Apache chapter.

Browse source 
Some reshuffling to improve flow.
Add descriptions for virtual hosting and modules.
Add URLs to module config docs.

Sponsored by:	iXsystems
This commit is contained in:
Dru Lavigne 2014-04-16 15:55:46 +00:00
parent 3d7f6d6bbe
commit f43c91b354
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44578
1 changed files with 204 additions and 201 deletions
Download patch file Download diff file Expand all files Collapse all files

403
en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
View file

@ -4249,18 +4249,19 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting>
</sect1> </sect1>
<sect1 xml:id="network-apache"> <sect1 xml:id="network-apache">
<!-- <info>
<sect1info> <title>Apache HTTP Server</title>
<authorgroup> <authorgroup>
<author> <author>
<personname>
<firstname>Murray</firstname> <firstname>Murray</firstname>
<surname>Stokely</surname> <surname>Stokely</surname>
</personname>
<contrib>Contributed by </contrib> <contrib>Contributed by </contrib>
</author> </author>
</authorgroup> </authorgroup>
</sect1info> </info>
-->
<title>Apache HTTP Server</title>
<indexterm><primary>web servers</primary> <indexterm><primary>web servers</primary>
<secondary>setting up</secondary></indexterm> <secondary>setting up</secondary></indexterm>
@ -4273,7 +4274,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting>
<para>This section summarizes how to configure and start version <para>This section summarizes how to configure and start version
2.<replaceable>x</replaceable> of the <application>Apache HTTP 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 For more detailed information about
<application>Apache</application>&nbsp;2.X and its configuration <application>Apache</application>&nbsp;2.X and its configuration
directives, refer to <link directives, refer to <link
@ -4287,8 +4288,9 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting>
<para>In &os;, the main <application>Apache HTTP <para>In &os;, the main <application>Apache HTTP
Server</application> configuration file is installed as Server</application> configuration file is installed as
<filename>/usr/local/etc/apache2<replaceable>x</replaceable>/httpd.conf</filename>. <filename>/usr/local/etc/apache2<replaceable>x</replaceable>/httpd.conf</filename>,
This ASCII text file begins comment lines with the 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 <literal>#</literal>. The most frequently modified directives
are:</para> are:</para>
@ -4301,30 +4303,36 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting>
<application>Apache</application> installation. <application>Apache</application> installation.
Binaries are stored in the <filename>bin</filename> and Binaries are stored in the <filename>bin</filename> and
<filename>sbin</filename> subdirectories of the server <filename>sbin</filename> subdirectories of the server
root, and configuration files are stored in root and configuration files are stored in the
<filename <filename
class="directory">etc/apache2<replaceable>x</replaceable></filename>.</para> class="directory">etc/apache2<replaceable>x</replaceable></filename>
subdirectory.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>ServerAdmin you@your.address</literal></term> <term><literal>ServerAdmin you@example.com</literal></term>
<listitem> <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. This address also appears on some
server-generated pages, such as error documents.</para> server-generated pages, such as error documents.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>ServerName www.example.com</literal></term> <term><literal>ServerName www.example.com:80</literal></term>
<listitem> <listitem>
<para>Allows an administrator to set a hostname which is <para>Allows an administrator to set a hostname which is
sent back to clients for the server. For example, sent back to clients for the server. For example,
<systemitem>www</systemitem> can be used instead of the <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> </listitem>
</varlistentry> </varlistentry>
@ -4342,106 +4350,102 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting>
</varlistentry> </varlistentry>
</variablelist> </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 <application>Apache</application> configuration file before
making changes. When the configuration of making changes. When the configuration of
<application>Apache</application>, is complete, save the <application>Apache</application> is complete, save the
file and verify the configuration using apachectl(8). file and verify the configuration using <command>apachectl</command>.
Running <command>apachectl configtest</command> should return Running <command>apachectl configtest</command> should return
<literal>Syntax OK</literal>.</para> <literal>Syntax OK</literal>.</para>
<indexterm><primary>Apache</primary> <indexterm><primary>Apache</primary>
<secondary>starting or stopping</secondary></indexterm> <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 <para>To launch <application>Apache</application> at system
startup, add the following line to startup, add the following line to
<filename>/etc/rc.conf</filename>:</para> <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 <para>If <application>Apache</application> should be started
with non-default options, the following line may be added to with non-default options, the following line may be added to
<filename>/etc/rc.conf</filename> to specify the needed <filename>/etc/rc.conf</filename> to specify the needed
flags:</para> flags:</para>
<programlisting>apache24_flags=""</programlisting> <programlisting>apache<replaceable>24</replaceable>_flags=""</programlisting>
<para>The <application>Apache</application> configuration can be <para>If <application>apachectl</application> does not report
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>
<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
configuration errors, start <command>httpd</command> 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 <para>The <command>httpd</command> service can be tested by
entering entering
<literal>http://<replaceable>localhost</replaceable></literal> <literal>http://<replaceable>localhost</replaceable></literal>
in a web browser, replacing in a web browser, replacing
<replaceable>localhost</replaceable> with the fully-qualified <replaceable>localhost</replaceable> with the fully-qualified
domain name of the machine running <command>httpd</command>, domain name of the machine running <command>httpd</command>.
if it is not the local machine. The default web page that is The default web page that is
displayed 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>
<sect2> <sect2>
<title>Virtual Hosting</title> <title>Virtual Hosting</title>
<para><application>Apache</application> supports two different <para>Virtual hosting allows multiple websites to run on one
types of Virtual Hosting. The first method is Name-based <application>Apache</application> server. The virtual hosts
Virtual Hosting. Name-based virtual hosting uses the clients can be <firstterm>IP-based</firstterm> or
HTTP/1.1 headers to figure out the hostname. This allows many <firstterm>name-based</firstterm>. <acronym>IP</acronym>-based
different domains to share the same <acronym>IP</acronym> 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> address.</para>
<para>To setup <application>Apache</application> to use <para>To setup <application>Apache</application> to use
Name-based Virtual Hosting add an entry like the following to name-based virtual hosting, add a
<filename>httpd.conf</filename>:</para> <literal>VirtualHost</literal> block for each website. For
example, for the webserver named <systemitem
<programlisting>NameVirtualHost *</programlisting> class="fqdomainname">www.domain.tld</systemitem> with
a virtual domain of <systemitem
<para>If the webserver was named <systemitem class="fqdomainname">www.someotherdomain.tld</systemitem>,
class="fqdomainname">www.domain.tld</systemitem> and add the following entries to
a virtual domain for <systemitem
class="fqdomainname">www.someotherdomain.tld</systemitem>
then add the following entries to
<filename>httpd.conf</filename>:</para> <filename>httpd.conf</filename>:</para>
<screen>&lt;VirtualHost *&gt; <screen>&lt;VirtualHost *&gt;
ServerName www.domain.tld ServerName <replaceable>www.domain.tld</replaceable>
DocumentRoot /www/domain.tld DocumentRoot <replaceable>/www/domain.tld</replaceable>
&lt;/VirtualHost&gt; &lt;/VirtualHost&gt;
&lt;VirtualHost *&gt; &lt;VirtualHost *&gt;
ServerName www.someotherdomain.tld ServerName <replaceable>www.someotherdomain.tld</replaceable>
DocumentRoot /www/someotherdomain.tld DocumentRoot <replaceable>/www/someotherdomain.tld</replaceable>
&lt;/VirtualHost&gt;</screen> &lt;/VirtualHost&gt;</screen>
<para>Replace the addresses with the addresses needed and the <para>For each virtual host, replace the values for
path to the documents with what are being used.</para> <literal>ServerName</literal> and
<literal>DocumentRoot</literal> with the values to be
used.</para>
<para>For more information about setting up virtual hosts, <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 documentation at: <uri
xlink:href="http://httpd.apache.org/docs/vhosts/">http://httpd.apache.org/docs/vhosts/</uri>.</para> xlink:href="http://httpd.apache.org/docs/vhosts/">http://httpd.apache.org/docs/vhosts/</uri>.</para>
</sect2> </sect2>
@ -4452,14 +4456,25 @@ DocumentRoot /www/someotherdomain.tld
<indexterm><primary>Apache</primary> <indexterm><primary>Apache</primary>
<secondary>modules</secondary></indexterm> <secondary>modules</secondary></indexterm>
<para>There are many different <application>Apache</application> <para><application>Apache</application> uses
modules available to add functionality to the basic server. modules to augment the functionality provided by the basic
The &os; Ports Collection provides an easy way to install server. Refer to <uri
<application>Apache</application> together with some of the xlink:href="http://httpd.apache.org/docs/current/mod/">http://httpd.apache.org/docs/current/mod/</uri>
more popular add-on modules.</para> 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> <sect3>
<title><application>mod_ssl</application></title> <title><filename>mod_ssl</filename></title>
<indexterm> <indexterm>
<primary>web servers</primary> <primary>web servers</primary>
@ -4468,157 +4483,56 @@ DocumentRoot /www/someotherdomain.tld
<indexterm><primary>SSL</primary></indexterm> <indexterm><primary>SSL</primary></indexterm>
<indexterm><primary>cryptography</primary></indexterm> <indexterm><primary>cryptography</primary></indexterm>
<para>The <application>mod_ssl</application> module uses the <para>The <filename>mod_ssl</filename> module uses the
OpenSSL library to provide strong cryptography via the <application>OpenSSL</application> library to provide strong cryptography via the
Secure Sockets Layer (SSL v2/v3) and Transport Layer Secure Sockets Layer (<acronym>SSLv3</acronym>) and Transport Layer
Security (TLS v1) protocols. This module provides Security (<acronym>TLSv1</acronym>) protocols. This module provides
everything necessary to request a signed certificate from a everything necessary to request a signed certificate from a
trusted certificate signing authority to run a secure web trusted certificate signing authority to run a secure web
server on &os;.</para> server on &os;.</para>
<para>The <application>mod_ssl</application> module is built <para>In &os;, <filename>mod_ssl</filename> module is enabled
by default, but can be enabled by specifying by default in both the package and the port. The available
<literal>-DWITH_SSL</literal> at compile time.</para> 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>
<sect3> <sect3>
<title>Language Bindings</title> <title><filename>mod_perl2</filename></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 &microsoft;,
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>&lt;Location "/"&gt;
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
&lt;/Location&gt;</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>
<sect3>
<title><application>mod_perl2</application></title>
<indexterm> <indexterm>
<primary>mod_perl2</primary> <primary>mod_perl2</primary>
<secondary>Perl</secondary> <secondary>Perl</secondary>
</indexterm> </indexterm>
<para>The <application>Apache</application>/Perl integration <para>The
project brings together the full power of the Perl <filename>mod_perl2</filename> module makes it possible
programming language and the to write <application>Apache</application> modules
<application>Apache HTTP Server</application>. With the in <application>Perl</application>. In addition, the persistent interpreter embedded
<application>mod_perl2</application> module it is possible
to write <application>Apache</application> modules entirely
in Perl. In addition, the persistent interpreter embedded
in the server avoids the overhead of starting an external 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 <para>The <filename>mod_perl2</filename> can be installed using the
<package>www/mod_perl2</package> <package>www/mod_perl2</package> package or
port.</para> 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>
<sect3> <sect3>
<!-- <info>
<sect3info> <title><application>mod_php</application></title>
<authorgroup> <authorgroup>
<author> <author>
<personname>
<firstname>Tom</firstname> <firstname>Tom</firstname>
<surname>Rhodes</surname> <surname>Rhodes</surname>
</personname>
<contrib>Written by </contrib> <contrib>Written by </contrib>
</author> </author>
</authorgroup> </authorgroup>
</sect3info> </info>
-->
<title><application>mod_php</application></title>
<indexterm> <indexterm>
<primary>mod_php</primary> <primary>mod_php</primary>
@ -4717,6 +4631,95 @@ DocumentRoot /www/someotherdomain.tld
<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen> <screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>
</sect3> </sect3>
</sect2> </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 &microsoft;,
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>&lt;Location "/"&gt;
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
&lt;/Location&gt;</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>
<sect1 xml:id="network-ftp"> <sect1 xml:id="network-ftp">