Date: Wed, 16 Apr 2014 15:55:46 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44578 - head/en_US.ISO8859-1/books/handbook/network-servers Message-ID: <201404161555.s3GFtkVM096754@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@your.address</literal></term> + <term><literal>ServerAdmin you@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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404161555.s3GFtkVM096754>