From owner-svn-doc-head@FreeBSD.ORG Wed Apr 16 15:55:47 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id E2587422; Wed, 16 Apr 2014 15:55:46 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id CDA051FBD; Wed, 16 Apr 2014 15:55:46 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3GFtka4096755; Wed, 16 Apr 2014 15:55:46 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3GFtkVM096754; Wed, 16 Apr 2014 15:55:46 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404161555.s3GFtkVM096754@svn.freebsd.org> From: Dru Lavigne Date: Wed, 16 Apr 2014 15:55:46 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 16 Apr 2014 15:55:47 -0000 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 - - Apache HTTP Server + web servers setting up @@ -4273,7 +4274,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key This section summarizes how to configure and start version 2.x of the Apache HTTP - Server, the most widely used version, on &os;. + Server on &os;. For more detailed information about Apache 2.X and its configuration directives, refer to In &os;, the main Apache HTTP Server configuration file is installed as - /usr/local/etc/apache2x/httpd.conf. - This ASCII text file begins comment lines with the + /usr/local/etc/apache2x/httpd.conf, + where x represents the version number. + This ASCII text file begins comment lines with a #. The most frequently modified directives are: @@ -4301,30 +4303,36 @@ $include Kexample.com.+005+nnnnn.ZSK.key Apache installation. Binaries are stored in the bin and sbin subdirectories of the server - root, and configuration files are stored in + root and configuration files are stored in the etc/apache2x. + class="directory">etc/apache2x + subdirectory. - ServerAdmin you@your.address + ServerAdmin you@example.com - The email address to receive problems with the + 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. - ServerName www.example.com + ServerName www.example.com:80 - Allows an administrator to set a host name which is + Allows an administrator to set a hostname which is sent back to clients for the server. For example, www can be used instead of the - actual host name. + actual hostname. If the system does not have a + registeredDNS name, enter its + IP address instead. If the server + will listen on an alternate report, change + 80 to the alternate port + number. @@ -4342,106 +4350,102 @@ $include Kexample.com.+005+nnnnn.ZSK.key - It is always a good idea to make backup copies of the + It is always a good idea to make a backup copy of the default Apache configuration file before making changes. When the configuration of - Apache, is complete, save the - file and verify the configuration using apachectl(8). + Apache is complete, save the + file and verify the configuration using apachectl. Running apachectl configtest should return Syntax OK. Apache starting or stopping - The www/apache24 port - installs an &man.rc.8; script to aid in starting, stopping, - and restarting Apache, which can be - found in /usr/local/etc/rc.d/. - To launch Apache at system startup, add the following line to /etc/rc.conf: - apache24_enable="YES" + apache24_enable="YES" If Apache should be started with non-default options, the following line may be added to /etc/rc.conf to specify the needed flags: - apache24_flags="" - - The Apache configuration can be - tested for errors after making subsequent configuration - changes while httpd 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: + apache24_flags="" - &prompt.root; service apache24 configtest - - - It is important to note that the - configtest is not an &man.rc.8; standard, - and should not be expected to work for all &man.rc.8; - startup scripts. - - - If Apache does not report + If apachectl does not report configuration errors, start httpd - with &man.service.8;: + now: - &prompt.root; service apache24 start + &prompt.root; service apache24 start The httpd service can be tested by entering http://localhost in a web browser, replacing localhost with the fully-qualified - domain name of the machine running httpd, - if it is not the local machine. The default web page that is + domain name of the machine running httpd. + The default web page that is displayed is - /usr/local/www/apache24/data/index.html. + /usr/local/www/apache24/data/index.html. + + The Apache configuration can be + tested for errors after making subsequent configuration + changes while httpd is running using + the following + command: + + &prompt.root; service apache24 configtest + + + It is important to note that + configtest is not an &man.rc.8; standard, + and should not be expected to work for all + startup scripts. + Virtual Hosting - Apache 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 IP + Virtual hosting allows multiple websites to run on one + Apache server. The virtual hosts + can be IP-based or + name-based. IP-based + virtual hosting uses a different IP 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 IP address. To setup Apache to use - Name-based Virtual Hosting add an entry like the following to - httpd.conf: - - NameVirtualHost * - - If the webserver was named www.domain.tld and - a virtual domain for www.someotherdomain.tld - then add the following entries to + name-based virtual hosting, add a + VirtualHost block for each website. For + example, for the webserver named www.domain.tld with + a virtual domain of www.someotherdomain.tld, + add the following entries to httpd.conf: <VirtualHost *> -ServerName www.domain.tld -DocumentRoot /www/domain.tld +ServerName www.domain.tld +DocumentRoot /www/domain.tld </VirtualHost> <VirtualHost *> -ServerName www.someotherdomain.tld -DocumentRoot /www/someotherdomain.tld +ServerName www.someotherdomain.tld +DocumentRoot /www/someotherdomain.tld </VirtualHost> - Replace the addresses with the addresses needed and the - path to the documents with what are being used. + For each virtual host, replace the values for + ServerName and + DocumentRoot with the values to be + used. For more information about setting up virtual hosts, - please consult the official Apache + consult the official Apache documentation at: http://httpd.apache.org/docs/vhosts/. @@ -4452,14 +4456,25 @@ DocumentRoot /www/someotherdomain.tld Apache modules - There are many different Apache - modules available to add functionality to the basic server. - The &os; Ports Collection provides an easy way to install - Apache together with some of the - more popular add-on modules. + Apache uses + modules to augment the functionality provided by the basic + server. Refer to http://httpd.apache.org/docs/current/mod/ + for a complete listing of and the configuration details for + the available modules. + + In &os;, some modules can be compiled with the + www/apache24 port. Type make + config within + /usr/ports/www/apache24 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. - <application>mod_ssl</application> + <filename>mod_ssl</filename> web servers @@ -4468,157 +4483,56 @@ DocumentRoot /www/someotherdomain.tld SSL cryptography - The mod_ssl 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 + The mod_ssl module uses the + OpenSSL library to provide strong cryptography via the + Secure Sockets Layer (SSLv3) and Transport Layer + Security (TLSv1) 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;. - The mod_ssl module is built - by default, but can be enabled by specifying - -DWITH_SSL at compile time. - - - - Language Bindings - - There are Apache modules for most major scripting - languages. These modules typically make it possible to - write Apache 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. - - - - - Dynamic Websites - - - web servers - dynamic - - - 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, - mod_perl2, and - mod_php. - - - Django - - Python - Django - - 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. - - Django depends on mod_python, - Apache, and an SQL database - engine. The &os; Port will install all of - these pre-requisites with the appropriate - flags. - - - Installing Django with - <application>Apache2</application>, - <application>mod_python3</application>, and - <application>PostgreSQL</application> - - &prompt.root; cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL - - - 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. - - - Apache Configuration for Django/mod_python - - A line must be added to the apache - httpd.conf file to configure Apache - to pass requests for certain URLs to the web - application: - - <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> - - - - - Ruby on Rails - - Ruby on Rails - - 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. - - &prompt.root; cd /usr/ports/www/rubygem-rails; make all install clean + In &os;, mod_ssl module is enabled + by default in both the package and the port. The available + configuration directives are explained at http://httpd.apache.org/docs/current/mod/mod_ssl.html. - <application>mod_perl2</application> + <filename>mod_perl2</filename> mod_perl2 Perl - The Apache/Perl integration - project brings together the full power of the Perl - programming language and the - Apache HTTP Server. With the - mod_perl2 module it is possible - to write Apache modules entirely - in Perl. In addition, the persistent interpreter embedded + The + mod_perl2 module makes it possible + to write Apache modules + in Perl. 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. + interpreter and the penalty of Perl start-up time. - mod_perl2 is available in the - www/mod_perl2 - port. + The mod_perl2 can be installed using the + www/mod_perl2 package or + port. Documentation for using this module can be found at + http://perl.apache.org/docs/2.0/index.html. - - <application>mod_php</application> + mod_php @@ -4717,6 +4631,95 @@ DocumentRoot /www/someotherdomain.tld &prompt.root; apachectl graceful + + + Dynamic Websites + + + web servers + dynamic + + + 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, + mod_perl2, and + mod_php. + + + Django + + Python + Django + + 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. + + Django depends on mod_python, + Apache, and an SQL database + engine. The &os; Port will install all of + these pre-requisites with the appropriate + flags. + + + Installing Django with + <application>Apache2</application>, + <application>mod_python3</application>, and + <application>PostgreSQL</application> + + &prompt.root; cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL + + + 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. + + + Apache Configuration for Django/mod_python + + A line must be added to the apache + httpd.conf file to configure Apache + to pass requests for certain URLs to the web + application: + + <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> + + + + + Ruby on Rails + + Ruby on Rails + + 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. + + &prompt.root; cd /usr/ports/www/rubygem-rails; make all install clean + +