mirror of https://github.com/tLDP/LDP
999 lines
42 KiB
Plaintext
999 lines
42 KiB
Plaintext
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" []>
|
|
<article>
|
|
<articleinfo>
|
|
<title>PHHTTPD Userland HTTP Accelerator HOWTO</title>
|
|
<author><firstname>Zach</firstname><surname>Brown</surname></author>
|
|
<author><firstname>David</firstname><othername role="mi">C.</othername><surname>Merrill</surname></author>
|
|
<copyright><year>2000</year><holder>Zach Brown</holder></copyright>
|
|
<copyright><year>2001</year><holder>David C. Merrill</holder></copyright>
|
|
<pubdate>2001-04-24</pubdate>
|
|
<abstract><para>This document explains the use of the phhttpd http server
|
|
accelerator under Linux.</para>
|
|
|
|
<para>As of the later 2.3 kernels, and offically in 2.4 and later, the TUX
|
|
http accelerator is included in the standard Linux kernel tree.
|
|
Therefore, this document should be considered obsolete for most users.
|
|
</para>
|
|
</abstract>
|
|
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>1.1</revnumber>
|
|
<date>2001-04-24</date>
|
|
<authorinitials>DCM</authorinitials>
|
|
<revremark>Converted to DocBook 4.1 article, with some minor language cleanup.
|
|
Copyright passed from Zach Brown to David C. Merrill.</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>1.0</revnumber>
|
|
<date>2000</date>
|
|
<authorinitials>ZB</authorinitials>
|
|
<revremark>Initial release.</revremark>
|
|
</revision>
|
|
</revhistory>
|
|
</articleinfo>
|
|
|
|
<!--- ************************************************** -->
|
|
<sect1 id="introduction"><title>Introduction</title>
|
|
<para>
|
|
phhttpd is an HTTP accelerator. It serves fast static HTTP fetches from a
|
|
local file-system
|
|
and passes slower dynamic requests back to a waiting server. It features
|
|
a lean networking I/O core and an aggressive content cache that help it
|
|
perform its job efficiently.
|
|
</para>
|
|
<sect2><title>Architectural Overview</title>
|
|
<para>
|
|
phhttpd features a very slim I/O core. It does all its networking
|
|
work using non-blocking system calls driven by whatever event model
|
|
is most appropriate for the host operating system. This
|
|
allows a single execution context
|
|
to handle as many client connections as the event model dictates.
|
|
</para>
|
|
<para>
|
|
phhttpd's job is to serve static content as quickly as it possibly
|
|
can. To do this it maintains a cache of content in memory. When
|
|
a request is serviced, phhttpd saves a reference to the on disk content
|
|
and whatever HTTP headers are dependent on the content. The next time
|
|
a request for this content is received, phhttpd can service it
|
|
very quickly. This cache can be prepopulated (populated at run time), or can
|
|
be built dynamically as requests come in. Its size may also be
|
|
capped by the administrator so that it doesn't overwhelm a system.
|
|
</para>
|
|
<para>
|
|
phhttpd is a threaded stand alone daemon. The number of threads
|
|
is currently statically defined at run time. Incoming connections
|
|
are evenly balanced among the running threads, regardless of what
|
|
content they may be serving. Connections are served by the thread
|
|
that accepted them until the transfer is done.
|
|
</para>
|
|
</sect2>
|
|
<sect2><title>Supported Systems</title>
|
|
<para>
|
|
phhttpd is currently only expected to build and run on Linux
|
|
systems using glibc2.1 under a kernel that supports passing POLL*
|
|
information over real-time SIGIO signals. This means later 2.3.x
|
|
kernels or a 2.2.x kernel that has been patched.
|
|
</para>
|
|
<para>
|
|
I badly want this to change. If you're interested in doing porting
|
|
work to other Operating Systems, please do let me know.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<!--- ************************************************** -->
|
|
<sect1 id="configuration"><title>Configuration File</title>
|
|
<sect2><title>Overview</title>
|
|
<para>
|
|
phhttpd uses an XML config file format to express how it should behave
|
|
while running. More information on XML may be found near
|
|
<ulink url="http://www.w3.org/XML/">http://www.w3.org/XML/</ulink>
|
|
</para>
|
|
<para>
|
|
phhttpd's configuration centers around the concept of virtual servers.
|
|
For us, a virtual server may be thought of as the merging of a document
|
|
tree and the actions phhttpd takes while serving that content.
|
|
</para>
|
|
<para>phhttpd.conf may be thought of as having two main sections.
|
|
The global section, which defines properties that are consistent
|
|
across the entire running phhttpd server, and multiple virtual sections
|
|
that describe properties of that only apply to a virtual server.
|
|
There will only be one global section while multiple virtual sections
|
|
are allowed.
|
|
</para>
|
|
</sect2>
|
|
<sect2><title>Global Config Section</title>
|
|
<para>
|
|
The global section defines properties of the running server that don't
|
|
apply to a single virtual server. It should be enclosed in
|
|
</para>
|
|
<para>
|
|
<variablelist><title>Global config entities</title>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
cache max=NUM
|
|
</SGMLTag></term> <listitem> <para>
|
|
Sets the maximum number of cached responses that will be held in memory. Each
|
|
cached responses holds a minimal amount of memory. More importantly, each
|
|
cached response holds an open file descriptor to the file with real content and
|
|
an <function>mmap()</function>ed region of that content. phhttpd will start pruning the cache when
|
|
it notices either of these two resources coming under pressure, but has no way
|
|
to easily deduce that its running low on memory. The administrator may set this
|
|
value to set an upper bound on the number of responses to keep in memory.
|
|
</para> </listitem> </varlistentry>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
control file=PATH
|
|
</SGMLTag></term> <listitem> <para>
|
|
This specifies the file that will be used to talk with <command>phhttpd_ctl</command>.
|
|
</para> </listitem> </varlistentry>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
globallog file=PATH
|
|
</SGMLTag></term> <listitem> <para>
|
|
This specifies the file to which global messages will be logged.
|
|
</para> </listitem> </varlistentry>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
mime file=PATH
|
|
</SGMLTag></term> <listitem> <para>
|
|
This specifies the file that contains the mapping of file extensions to <acronym>MIME</acronym> types. It should be of the form:
|
|
<programlisting>
|
|
text/sgml sgml sgm
|
|
video/mpeg mpeg mpg mpe</programlisting>
|
|
</para> </listitem> </varlistentry>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
timeout inactivity=NUM
|
|
</SGMLTag></term> <listitem> <para>
|
|
Controls various network connection timeouts. 'inactivity' sets the amount
|
|
of time that a connection can be idle before phhttpd will forcibly disconnect it.
|
|
inactivity defaults to 0, which lets the connections idle until TCP timeouts
|
|
take effect.
|
|
</para> </listitem> </varlistentry>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
sendfile
|
|
</SGMLTag></term> <listitem> <para>
|
|
Enabling this option tells phhttpd to use <function>sendfile()</function> rather than
|
|
<function>write()</function>ing from an <function>mmap()</function>ed region.
|
|
Avoiding calling <function>mmap()</function> will
|
|
shorten the amount of time it takes to build cached responses.
|
|
</para> </listitem> </varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2><title>Virtual Servers</title>
|
|
<para>A Virtual Server can be thought of as the abstraction serving up a content tree
|
|
( <quote>docroot</quote> in <command>Apache</command> speak). There are a set of attributes
|
|
that are used to define a virtual server. These attributes are used to decide which
|
|
virtual server will process a client's request. Then there are attributes which define
|
|
how the content is served.</para>
|
|
<para> A virtual server must have a docroot. The virtual tag in the config
|
|
file has a docroot attribute that must be set.</para>
|
|
<para><programlisting><virtual docroot=PATH>
|
|
...
|
|
</virtual>
|
|
</programlisting>
|
|
There can be as many virtual sections in the configuration file as one likes.
|
|
</para>
|
|
<para>
|
|
<variablelist><title>Global Config Entities</title>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
md5
|
|
</SGMLTag></term> <listitem> <para>
|
|
This enables the generation of the Content-MD5: header. This greatly increases the
|
|
cost of creating a cached response for this virtual, because the MD5 function must
|
|
be applied to the entire content of the response. Once the response is created, though,
|
|
there is no per-request overhead.
|
|
</para> </listitem> </varlistentry>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
prepop
|
|
</SGMLTag></term> <listitem> <para>
|
|
This will cause phhttpd to traverse the entire docroot at initialization time and prepare
|
|
cached responses for all the files it finds. This happens in the back ground during
|
|
normal operation, so there is no dramatic increase in the time it takes for phhttpd
|
|
to start serving connections.
|
|
</para> </listitem> </varlistentry>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
name
|
|
</SGMLTag></term> <listitem> <para>
|
|
This tag surrounds the string that will be used to identify the server. This string
|
|
will be compared to the Host: header given in the request from the client, or will
|
|
be compared to the 'host part' of the full URL if that was given. This will be
|
|
used in combination with the network address and port pair to determine if a request
|
|
should be served by a virtual server.
|
|
</para> </listitem> </varlistentry>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
listen v4=DOT.TED.QU.AD port=PORT
|
|
</SGMLTag></term> <listitem> <para>
|
|
This virtual server will be chosen to serve an incoming request if that request was
|
|
made to the network address specified in this entity. There can be as many of these
|
|
as one likes in a given virtual server, and '*' may be specified for either parameter to
|
|
indicate that all addresses or ports should match.
|
|
</para> </listitem> </varlistentry>
|
|
|
|
<varlistentry><term><SGMLTag>
|
|
logs
|
|
</SGMLTag></term> <listitem> <para>
|
|
The logs section of the virtual server define the per virtual log files that should
|
|
be written to during operation. See the following section on logging.
|
|
</para> </listitem> </varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<!--- ************************************************** -->
|
|
<sect1 id="logging"><title>Logging</title>
|
|
<para><quote>All kids love log!</quote></para>
|
|
<sect2><title>Overview</title>
|
|
<para>
|
|
phhttpd maintains log buffers for each log it writes to. Logged events are put in
|
|
these buffers at reporting time rather than being immediately written to disk. These
|
|
logs are written as they are filled during normal operation, or at regular intervals.
|
|
This greatly reduces the performance impact of keeping detailed logs.
|
|
</para>
|
|
</sect2>
|
|
<sect2><title>Configuration</><para>
|
|
phhttpd keeps interesting logs on a virtual server granularity.
|
|
You can specify which logs you wish to keep by including an entity
|
|
in the log section of a virtual server for each source you wish to log.
|
|
There is an entity for each source of logging, and attributes to that
|
|
entity define where it is logged.
|
|
It looks something like this:<programlisting>
|
|
<logs>
|
|
<LOGSOURCE mode=OCTALMODE file=PATH>
|
|
...
|
|
</logs></programlisting>
|
|
</para>
|
|
<para><varname>mode</varname> is the octal permissions mode of the file that is
|
|
to be opened. As it is parsed by dumb routines, a leading 0 is highly recommended.
|
|
<varname>file</varname> is the file to which the logged events will be written.
|
|
The LOG_SOURCE is one of:
|
|
<informaltable frame=none><tgroup cols=2><tbody>
|
|
<row><entry>access</entry><entry>Successfully answered requests</entry></row>
|
|
<row><entry>agent</entry><entry>
|
|
The value given in the 'User-Agent' HTTP request header</entry></row>
|
|
<row><entry>referer</entry><entry>
|
|
The string given in the 'Referer' HTTP request header</entry></row>
|
|
</tbody></tgroup></informaltable>
|
|
</para></sect2>
|
|
|
|
<sect2><title>Format and Strange Behaviour</title>
|
|
<para>
|
|
phhttpd log entries are contained with a single line in a text file. They contain
|
|
the time the log entry was written, an opaque token that is associated with the connection
|
|
that caused the log entry, followed by the actual entry.
|
|
</para><para>The contents of the 'referer' and 'agent' log entries is simply the string
|
|
that was given with the header. The contents of the 'access' log is a little more
|
|
interesting. It has the decoded relative URL that was asked for, followed by the total bytes
|
|
that were transfered, and the time in seconds that it took to transfer.
|
|
<programlisting>
|
|
387f7a45 387f7a45800210ac8910500 /index.html - 2132 0
|
|
</programlisting>
|
|
is an entry from an 'access' log.
|
|
</para>
|
|
<para>The first field is the time in seconds since the Unix epoch, a.k.a. <varname>time_t</varname>. The second field is associated with the client connection that caused the log
|
|
entry. It is constant for the duration of the connection, and is written to all the logs
|
|
entries, of whatever type, that are generated. This allows a log parser to do more complete
|
|
connection granularity analysis. As it happens, this opaque token is currently built up
|
|
of the time the client was connected, its remote and local network address, etc, but these
|
|
values most _not_ be parsed as they may change in the future.
|
|
</para><para>
|
|
Entries generated by a thread will be written in chronological order. If, however,
|
|
multiple threads are sharing an output file the resulting entries may not be written
|
|
in chronological order. It is up to the parsing programs to use the 'time' field
|
|
to sort by, if they care about chronological order.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<!--- ************************************************** -->
|
|
<sect1 id="runtime"><title>Run Time Facilities</title>
|
|
<sect2><title>Overview</title>
|
|
<para>While phhttpd is running it listens to a 'control' socket for messages from the
|
|
administrator. The currently provided <command>phhttpd_ctl</command> program allows
|
|
the administrator to minimally interact with phhttpd. This provides both control
|
|
and status reporting.
|
|
</para><para>
|
|
<command>phhttpd_ctl</command> always wants a <parameter>--control</parameter> argument
|
|
that specifies the control socket of the running phhttpd daemon. This should match
|
|
the <control> tag specified in the config file.
|
|
</para></sect2>
|
|
<sect2><title>Log Rotating</title>
|
|
<para>
|
|
phhttpd can be told to rotate its logs so that existing logs may be processed.
|
|
</para><para>
|
|
The <parameter>--rotate</parameter> argument to <command>phhttpd_ctl</command> tells phhttpd
|
|
to rename the existing files to a unique name, open new files with the previously used names,
|
|
then close the renamed logs and start using the newly created files. <command>phhttpd_ctl</command>
|
|
will output the names of the newly created files which will be safe to use once the command
|
|
exits.
|
|
</para><para>
|
|
The <parameter>--reopen</parameter> argument to <command>phhttpd_ctl</command> tells phhttpd
|
|
to close the existing file logs and reopen the files with the filenames that were configured.
|
|
This implies that an external entity has moved the files to new names and wants phhttpd
|
|
to stop using them.
|
|
</para>
|
|
</sect2>
|
|
<sect2><title>Status Reporting</title>
|
|
<para>
|
|
The <parameter>--status</parameter> argument to <command>phhttpd_ctl</command> tells phhttpd
|
|
to return a quick status blurb about the server. It contains miscellaneous information
|
|
about the running state of the server.
|
|
</para> </sect2>
|
|
</sect1>
|
|
<!--- ************************************************** -->
|
|
</article>
|
|
<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
|
|
]>
|
|
|
|
<article id="index">
|
|
<title>GNU Free Documentation License</title>
|
|
<artheader>
|
|
<releaseinfo>
|
|
Version 1.1, March 2000
|
|
</releaseinfo>
|
|
|
|
<copyright>
|
|
<year>2000</year><holder>Free Software Foundation, Inc.</holder>
|
|
</copyright>
|
|
|
|
<legalnotice id="legalnotice">
|
|
<para>
|
|
<address>Free Software Foundation, Inc.
|
|
<street>59 Temple Place, Suite 330</street>,
|
|
<city>Boston</city>,
|
|
<state>MA</state> <postcode>02111-1307</postcode>
|
|
<country>USA</country></address>. Everyone is permitted to
|
|
copy and distribute verbatim copies of this license
|
|
document, but changing it is not allowed.
|
|
</para>
|
|
</legalnotice>
|
|
|
|
</artheader>
|
|
|
|
|
|
<sect1 id="fdl-preamble">
|
|
<title>0. PREAMBLE</title>
|
|
<para>
|
|
The purpose of this License is to make a manual, textbook, or
|
|
other written document <quote>free</quote> in the sense of
|
|
freedom: to assure everyone the effective freedom to copy and
|
|
redistribute it, with or without modifying it, either
|
|
commercially or noncommercially. Secondarily, this License
|
|
preserves for the author and publisher a way to get credit for
|
|
their work, while not being considered responsible for
|
|
modifications made by others.
|
|
</para>
|
|
|
|
<para>
|
|
This License is a kind of <quote>copyleft</quote>, which means
|
|
that derivative works of the document must themselves be free in
|
|
the same sense. It complements the GNU General Public License,
|
|
which is a copyleft license designed for free software.
|
|
</para>
|
|
|
|
<para>
|
|
We have designed this License in order to use it for manuals for
|
|
free software, because free software needs free documentation: a
|
|
free program should come with manuals providing the same
|
|
freedoms that the software does. But this License is not limited
|
|
to software manuals; it can be used for any textual work,
|
|
regardless of subject matter or whether it is published as a
|
|
printed book. We recommend this License principally for works
|
|
whose purpose is instruction or reference.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="fdl-section1">
|
|
<title>1. APPLICABILITY AND DEFINITIONS</title>
|
|
<para id="fdl-document">
|
|
This License applies to any manual or other work that contains a
|
|
notice placed by the copyright holder saying it can be
|
|
distributed under the terms of this License. The
|
|
<quote>Document</quote>, below, refers to any such manual or
|
|
work. Any member of the public is a licensee, and is addressed
|
|
as <quote>you</quote>.
|
|
</para>
|
|
|
|
<para id="fdl-modified">
|
|
A <quote>Modified Version</quote> of the Document means any work
|
|
containing the Document or a portion of it, either copied
|
|
verbatim, or with modifications and/or translated into another
|
|
language.
|
|
</para>
|
|
|
|
<para id="fdl-secondary">
|
|
A <quote>Secondary Section</quote> is a named appendix or a
|
|
front-matter section of the <link
|
|
linkend="fdl-document">Document</link> that deals exclusively
|
|
with the relationship of the publishers or authors of the
|
|
Document to the Document's overall subject (or to related
|
|
matters) and contains nothing that could fall directly within
|
|
that overall subject. (For example, if the Document is in part a
|
|
textbook of mathematics, a Secondary Section may not explain any
|
|
mathematics.) The relationship could be a matter of historical
|
|
connection with the subject or with related matters, or of
|
|
legal, commercial, philosophical, ethical or political position
|
|
regarding them.
|
|
</para>
|
|
|
|
<para id="fdl-invariant">
|
|
The <quote>Invariant Sections</quote> are certain <link
|
|
linkend="fdl-secondary"> Secondary Sections</link> whose titles
|
|
are designated, as being those of Invariant Sections, in the
|
|
notice that says that the <link
|
|
linkend="fdl-document">Document</link> is released under this
|
|
License.
|
|
</para>
|
|
|
|
<para id="fdl-cover-texts">
|
|
The <quote>Cover Texts</quote> are certain short passages of
|
|
text that are listed, as Front-Cover Texts or Back-Cover Texts,
|
|
in the notice that says that the <link
|
|
linkend="fdl-document">Document</link> is released under this
|
|
License.
|
|
</para>
|
|
|
|
<para id="fdl-transparent">
|
|
A <quote>Transparent</quote> copy of the <link
|
|
linkend="fdl-document"> Document</link> means a machine-readable
|
|
copy, represented in a format whose specification is available
|
|
to the general public, whose contents can be viewed and edited
|
|
directly and straightforwardly with generic text editors or (for
|
|
images composed of pixels) generic paint programs or (for
|
|
drawings) some widely available drawing editor, and that is
|
|
suitable for input to text formatters or for automatic
|
|
translation to a variety of formats suitable for input to text
|
|
formatters. A copy made in an otherwise Transparent file format
|
|
whose markup has been designed to thwart or discourage
|
|
subsequent modification by readers is not Transparent. A copy
|
|
that is not <quote>Transparent</quote> is called
|
|
<quote>Opaque</quote>.
|
|
</para>
|
|
|
|
<para>
|
|
Examples of suitable formats for Transparent copies include
|
|
plain ASCII without markup, Texinfo input format, LaTeX input
|
|
format, SGML or XML using a publicly available DTD, and
|
|
standard-conforming simple HTML designed for human
|
|
modification. Opaque formats include PostScript, PDF,
|
|
proprietary formats that can be read and edited only by
|
|
proprietary word processors, SGML or XML for which the DTD
|
|
and/or processing tools are not generally available, and the
|
|
machine-generated HTML produced by some word processors for
|
|
output purposes only.
|
|
</para>
|
|
|
|
<para id="fdl-title-page">
|
|
The <quote>Title Page</quote> means, for a printed book, the
|
|
title page itself, plus such following pages as are needed to
|
|
hold, legibly, the material this License requires to appear in
|
|
the title page. For works in formats which do not have any title
|
|
page as such, <quote>Title Page</quote> means the text near the
|
|
most prominent appearance of the work's title, preceding the
|
|
beginning of the body of the text.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-section2">
|
|
<title>2. VERBATIM COPYING</title>
|
|
<para>
|
|
You may copy and distribute the <link
|
|
linkend="fdl-document">Document</link> in any medium, either
|
|
commercially or noncommercially, provided that this License, the
|
|
copyright notices, and the license notice saying this License
|
|
applies to the Document are reproduced in all copies, and that
|
|
you add no other conditions whatsoever to those of this
|
|
License. You may not use technical measures to obstruct or
|
|
control the reading or further copying of the copies you make or
|
|
distribute. However, you may accept compensation in exchange for
|
|
copies. If you distribute a large enough number of copies you
|
|
must also follow the conditions in <link
|
|
linkend="fdl-section3">section 3</link>.
|
|
</para>
|
|
|
|
<para>
|
|
You may also lend copies, under the same conditions stated
|
|
above, and you may publicly display copies.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-section3">
|
|
<title>3. COPYING IN QUANTITY</title>
|
|
<para>
|
|
If you publish printed copies of the <link
|
|
linkend="fdl-document">Document</link> numbering more than 100,
|
|
and the Document's license notice requires <link
|
|
linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
|
|
the copies in covers that carry, clearly and legibly, all these
|
|
Cover Texts: Front-Cover Texts on the front cover, and
|
|
Back-Cover Texts on the back cover. Both covers must also
|
|
clearly and legibly identify you as the publisher of these
|
|
copies. The front cover must present the full title with all
|
|
words of the title equally prominent and visible. You may add
|
|
other material on the covers in addition. Copying with changes
|
|
limited to the covers, as long as they preserve the title of the
|
|
<link linkend="fdl-document">Document</link> and satisfy these
|
|
conditions, can be treated as verbatim copying in other
|
|
respects.
|
|
</para>
|
|
|
|
<para>
|
|
If the required texts for either cover are too voluminous to fit
|
|
legibly, you should put the first ones listed (as many as fit
|
|
reasonably) on the actual cover, and continue the rest onto
|
|
adjacent pages.
|
|
</para>
|
|
|
|
<para>
|
|
If you publish or distribute <link
|
|
linkend="fdl-transparent">Opaque</link> copies of the <link
|
|
linkend="fdl-document">Document</link> numbering more than 100,
|
|
you must either include a machine-readable <link
|
|
linkend="fdl-transparent">Transparent</link> copy along with
|
|
each Opaque copy, or state in or with each Opaque copy a
|
|
publicly-accessible computer-network location containing a
|
|
complete Transparent copy of the Document, free of added
|
|
material, which the general network-using public has access to
|
|
download anonymously at no charge using public-standard network
|
|
protocols. If you use the latter option, you must take
|
|
reasonably prudent steps, when you begin distribution of Opaque
|
|
copies in quantity, to ensure that this Transparent copy will
|
|
remain thus accessible at the stated location until at least one
|
|
year after the last time you distribute an Opaque copy (directly
|
|
or through your agents or retailers) of that edition to the
|
|
public.
|
|
</para>
|
|
|
|
<para>
|
|
It is requested, but not required, that you contact the authors
|
|
of the <link linkend="fdl-document">Document</link> well before
|
|
redistributing any large number of copies, to give them a chance
|
|
to provide you with an updated version of the Document.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-section4">
|
|
<title>4. MODIFICATIONS</title>
|
|
<para>
|
|
You may copy and distribute a <link
|
|
linkend="fdl-modified">Modified Version</link> of the <link
|
|
linkend="fdl-document">Document</link> under the conditions of
|
|
sections <link linkend="fdl-section2">2</link> and <link
|
|
linkend="fdl-section3">3</link> above, provided that you release
|
|
the Modified Version under precisely this License, with the
|
|
Modified Version filling the role of the Document, thus
|
|
licensing distribution and modification of the Modified Version
|
|
to whoever possesses a copy of it. In addition, you must do
|
|
these things in the Modified Version:
|
|
</para>
|
|
|
|
<itemizedlist mark="opencircle">
|
|
<listitem>
|
|
<formalpara>
|
|
<title>A</title>
|
|
<para>
|
|
Use in the <link linkend="fdl-title-page">Title
|
|
Page</link> (and on the covers, if any) a title distinct
|
|
from that of the <link
|
|
linkend="fdl-document">Document</link>, and from those of
|
|
previous versions (which should, if there were any, be
|
|
listed in the History section of the Document). You may
|
|
use the same title as a previous version if the original
|
|
publisher of that version gives permission.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>B</title>
|
|
<para>
|
|
List on the <link linkend="fdl-title-page">Title
|
|
Page</link>, as authors, one or more persons or entities
|
|
responsible for authorship of the modifications in the
|
|
<link linkend="fdl-modified">Modified Version</link>,
|
|
together with at least five of the principal authors of
|
|
the <link linkend="fdl-document">Document</link> (all of
|
|
its principal authors, if it has less than five).
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>C</title>
|
|
<para>
|
|
State on the <link linkend="fdl-title-page">Title
|
|
Page</link> the name of the publisher of the <link
|
|
linkend="fdl-modified">Modified Version</link>, as the
|
|
publisher.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>D</title>
|
|
<para>
|
|
Preserve all the copyright notices of the <link
|
|
linkend="fdl-document">Document</link>.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>E</title>
|
|
<para>
|
|
Add an appropriate copyright notice for your modifications
|
|
adjacent to the other copyright notices.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>F</title>
|
|
<para>
|
|
Include, immediately after the copyright notices, a
|
|
license notice giving the public permission to use the
|
|
<link linkend="fdl-modified">Modified Version</link> under
|
|
the terms of this License, in the form shown in the
|
|
Addendum below.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>G</title>
|
|
<para>
|
|
Preserve in that license notice the full lists of <link
|
|
linkend="fdl-invariant"> Invariant Sections</link> and
|
|
required <link linkend="fdl-cover-texts">Cover
|
|
Texts</link> given in the <link
|
|
linkend="fdl-document">Document's</link> license notice.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>H</title>
|
|
<para>
|
|
Include an unaltered copy of this License.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>I</title>
|
|
<para>
|
|
Preserve the section entitled <quote>History</quote>, and
|
|
its title, and add to it an item stating at least the
|
|
title, year, new authors, and publisher of the <link
|
|
linkend="fdl-modified">Modified Version </link>as given on
|
|
the <link linkend="fdl-title-page">Title Page</link>. If
|
|
there is no section entitled <quote>History</quote> in the
|
|
<link linkend="fdl-document">Document</link>, create one
|
|
stating the title, year, authors, and publisher of the
|
|
Document as given on its Title Page, then add an item
|
|
describing the Modified Version as stated in the previous
|
|
sentence.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>J</title>
|
|
<para>
|
|
Preserve the network location, if any, given in the <link
|
|
linkend="fdl-document">Document</link> for public access
|
|
to a <link linkend="fdl-transparent">Transparent</link>
|
|
copy of the Document, and likewise the network locations
|
|
given in the Document for previous versions it was based
|
|
on. These may be placed in the <quote>History</quote>
|
|
section. You may omit a network location for a work that
|
|
was published at least four years before the Document
|
|
itself, or if the original publisher of the version it
|
|
refers to gives permission.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>K</title>
|
|
<para>
|
|
In any section entitled <quote>Acknowledgements</quote> or
|
|
<quote>Dedications</quote>, preserve the section's title,
|
|
and preserve in the section all the substance and tone of
|
|
each of the contributor acknowledgements and/or
|
|
dedications given therein.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>L</title>
|
|
<para>
|
|
Preserve all the <link linkend="fdl-invariant">Invariant
|
|
Sections</link> of the <link
|
|
linkend="fdl-document">Document</link>, unaltered in their
|
|
text and in their titles. Section numbers or the
|
|
equivalent are not considered part of the section titles.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>M</title>
|
|
<para>
|
|
Delete any section entitled
|
|
<quote>Endorsements</quote>. Such a section may not be
|
|
included in the <link linkend="fdl-modified">Modified
|
|
Version</link>.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>N</title>
|
|
<para>
|
|
Do not retitle any existing section as
|
|
<quote>Endorsements</quote> or to conflict in title with
|
|
any <link linkend="fdl-invariant">Invariant
|
|
Section</link>.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
If the <link linkend="fdl-modified">Modified Version</link>
|
|
includes new front-matter sections or appendices that qualify as
|
|
<link linkend="fdl-secondary">Secondary Sections</link> and
|
|
contain no material copied from the Document, you may at your
|
|
option designate some or all of these sections as invariant. To
|
|
do this, add their titles to the list of <link
|
|
linkend="fdl-invariant">Invariant Sections</link> in the
|
|
Modified Version's license notice. These titles must be
|
|
distinct from any other section titles.
|
|
</para>
|
|
|
|
<para>
|
|
You may add a section entitled <quote>Endorsements</quote>,
|
|
provided it contains nothing but endorsements of your <link
|
|
linkend="fdl-modified">Modified Version</link> by various
|
|
parties--for example, statements of peer review or that the text
|
|
has been approved by an organization as the authoritative
|
|
definition of a standard.
|
|
</para>
|
|
|
|
<para>
|
|
You may add a passage of up to five words as a <link
|
|
linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
|
|
of up to 25 words as a <link
|
|
linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
|
|
the list of <link linkend="fdl-cover-texts">Cover Texts</link>
|
|
in the <link linkend="fdl-modified">Modified Version</link>.
|
|
Only one passage of Front-Cover Text and one of Back-Cover Text
|
|
may be added by (or through arrangements made by) any one
|
|
entity. If the <link linkend="fdl-document">Document</link>
|
|
already includes a cover text for the same cover, previously
|
|
added by you or by arrangement made by the same entity you are
|
|
acting on behalf of, you may not add another; but you may
|
|
replace the old one, on explicit permission from the previous
|
|
publisher that added the old one.
|
|
</para>
|
|
|
|
<para>
|
|
The author(s) and publisher(s) of the <link
|
|
linkend="fdl-document">Document</link> do not by this License
|
|
give permission to use their names for publicity for or to
|
|
assert or imply endorsement of any <link
|
|
linkend="fdl-modified">Modified Version </link>.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-section5">
|
|
<title>5. COMBINING DOCUMENTS</title>
|
|
<para>
|
|
You may combine the <link linkend="fdl-document">Document</link>
|
|
with other documents released under this License, under the
|
|
terms defined in <link linkend="fdl-section4">section 4</link>
|
|
above for modified versions, provided that you include in the
|
|
combination all of the <link linkend="fdl-invariant">Invariant
|
|
Sections</link> of all of the original documents, unmodified,
|
|
and list them all as Invariant Sections of your combined work in
|
|
its license notice.
|
|
</para>
|
|
|
|
<para>
|
|
The combined work need only contain one copy of this License,
|
|
and multiple identical <link linkend="fdl-invariant">Invariant
|
|
Sections</link> may be replaced with a single copy. If there are
|
|
multiple Invariant Sections with the same name but different
|
|
contents, make the title of each such section unique by adding
|
|
at the end of it, in parentheses, the name of the original
|
|
author or publisher of that section if known, or else a unique
|
|
number. Make the same adjustment to the section titles in the
|
|
list of Invariant Sections in the license notice of the combined
|
|
work.
|
|
</para>
|
|
|
|
<para>
|
|
In the combination, you must combine any sections entitled
|
|
<quote>History</quote> in the various original documents,
|
|
forming one section entitled <quote>History</quote>; likewise
|
|
combine any sections entitled <quote>Acknowledgements</quote>,
|
|
and any sections entitled <quote>Dedications</quote>. You must
|
|
delete all sections entitled <quote>Endorsements.</quote>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-section6">
|
|
<title>6. COLLECTIONS OF DOCUMENTS</title>
|
|
<para>
|
|
You may make a collection consisting of the <link
|
|
linkend="fdl-document">Document</link> and other documents
|
|
released under this License, and replace the individual copies
|
|
of this License in the various documents with a single copy that
|
|
is included in the collection, provided that you follow the
|
|
rules of this License for verbatim copying of each of the
|
|
documents in all other respects.
|
|
</para>
|
|
|
|
<para>
|
|
You may extract a single document from such a collection, and
|
|
dispbibute it individually under this License, provided you
|
|
insert a copy of this License into the extracted document, and
|
|
follow this License in all other respects regarding verbatim
|
|
copying of that document.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-section7">
|
|
<title>7. AGGREGATION WITH INDEPENDENT WORKS</title>
|
|
<para>
|
|
A compilation of the <link
|
|
linkend="fdl-document">Document</link> or its derivatives with
|
|
other separate and independent documents or works, in or on a
|
|
volume of a storage or distribution medium, does not as a whole
|
|
count as a <link linkend="fdl-modified">Modified Version</link>
|
|
of the Document, provided no compilation copyright is claimed
|
|
for the compilation. Such a compilation is called an
|
|
<quote>aggregate</quote>, and this License does not apply to the
|
|
other self-contained works thus compiled with the Document , on
|
|
account of their being thus compiled, if they are not themselves
|
|
derivative works of the Document. If the <link
|
|
linkend="fdl-cover-texts">Cover Text</link> requirement of <link
|
|
linkend="fdl-section3">section 3</link> is applicable to these
|
|
copies of the Document, then if the Document is less than one
|
|
quarter of the entire aggregate, the Document's Cover Texts may
|
|
be placed on covers that surround only the Document within the
|
|
aggregate. Otherwise they must appear on covers around the whole
|
|
aggregate.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-section8">
|
|
<title>8. TRANSLATION</title>
|
|
<para>
|
|
Translation is considered a kind of modification, so you may
|
|
distribute translations of the <link
|
|
linkend="fdl-document">Document</link> under the terms of <link
|
|
linkend="fdl-section4">section 4</link>. Replacing <link
|
|
linkend="fdl-invariant"> Invariant Sections</link> with
|
|
translations requires special permission from their copyright
|
|
holders, but you may include translations of some or all
|
|
Invariant Sections in addition to the original versions of these
|
|
Invariant Sections. You may include a translation of this
|
|
License provided that you also include the original English
|
|
version of this License. In case of a disagreement between the
|
|
translation and the original English version of this License,
|
|
the original English version will prevail.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-section9">
|
|
<title>9. TERMINATION</title>
|
|
<para>
|
|
You may not copy, modify, sublicense, or distribute the <link
|
|
linkend="fdl-document">Document</link> except as expressly
|
|
provided for under this License. Any other attempt to copy,
|
|
modify, sublicense or distribute the Document is void, and will
|
|
automatically terminate your rights under this License. However,
|
|
parties who have received copies, or rights, from you under this
|
|
License will not have their licenses terminated so long as such
|
|
parties remain in full compliance.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-section10">
|
|
<title>10. FUTURE REVISIONS OF THIS LICENSE</title>
|
|
<para>
|
|
The <ulink type="http"
|
|
url="http://www.gnu.org/fsf/fsf.html">Free Software
|
|
Foundation</ulink> may publish new, revised versions of the GNU
|
|
Free Documentation License from time to time. Such new versions
|
|
will be similar in spirit to the present version, but may differ
|
|
in detail to address new problems or concerns. See <ulink
|
|
type="http"
|
|
url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
Each version of the License is given a distinguishing version
|
|
number. If the <link linkend="fdl-document">Document</link>
|
|
specifies that a particular numbered version of this License
|
|
<quote>or any later version</quote> applies to it, you have the
|
|
option of following the terms and conditions either of that
|
|
specified version or of any later version that has been
|
|
published (not as a draft) by the Free Software Foundation. If
|
|
the Document does not specify a version number of this License,
|
|
you may choose any version ever published (not as a draft) by
|
|
the Free Software Foundation.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="fdl-using">
|
|
<title>Addendum</title>
|
|
<para>
|
|
To use this License in a document you have written, include a copy of
|
|
the License in the document and put the following copyright and
|
|
license notices just after the title page:
|
|
</para>
|
|
|
|
<blockquote>
|
|
<para>
|
|
Copyright © YEAR YOUR NAME.
|
|
</para>
|
|
<para>
|
|
Permission is granted to copy, distribute and/or modify this
|
|
document under the terms of the GNU Free Documentation
|
|
License, Version 1.1 or any later version published by the
|
|
Free Software Foundation; with the <link
|
|
linkend="fdl-invariant">Invariant Sections</link> being LIST
|
|
THEIR TITLES, with the <link
|
|
linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,
|
|
and with the <link linkend="fdl-cover-texts">Back-Cover
|
|
Texts</link> being LIST. A copy of the license is included in
|
|
the section entitled <quote>GNU Free Documentation
|
|
License</quote>.
|
|
</para>
|
|
</blockquote>
|
|
|
|
<para>
|
|
If you have no <link linkend="fdl-invariant">Invariant
|
|
Sections</link>, write <quote>with no Invariant Sections</quote>
|
|
instead of saying which ones are invariant. If you have no
|
|
<link linkend="fdl-cover-texts">Front-Cover Texts</link>, write
|
|
<quote>no Front-Cover Texts</quote> instead of
|
|
<quote>Front-Cover Texts being LIST</quote>; likewise for <link
|
|
linkend="fdl-cover-texts">Back-Cover Texts</link>.
|
|
</para>
|
|
|
|
<para>
|
|
If your document contains nontrivial examples of program code,
|
|
we recommend releasing these examples in parallel under your
|
|
choice of free software license, such as the <ulink type="http"
|
|
url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public
|
|
License</ulink>, to permit their use in free software.
|
|
</para>
|
|
</sect1>
|
|
</article>
|
|
|