# Services installation and operation manual

James
Hess

This guide documents the basic architecture, installation, and use of the sorserv (services) add-on for IRC from a system administrator's point of view.

## Introduction

### Introduction

The purpose of this document is to aid in the installation of the services software.

This is not an introduction to IRC.

The reader is assumed to already be familiar with IRC. Prior to installing and configuring services, it is necessary at the very least to know how to install, use, and administer IRC servers based on or similar to sorircd.

Services is known to run on the following platforms:

- Linux

- NetBSD

Services may also run on similar operating systems, but if a platform is not listed above, then services may not run on it, so expect to have problems if you are attempting to install on an unsupported platform.

Basic skills in the use of the operating system that you will run services on and IRC itself is assumed. Extensive knowledge of your operating system, development tools, and services may be required if you are attempting to install on a target not shown above.

### Overview

Sorserv (IRC Services) is an IRC addon, that is, it is an extension to IRC and not part of the original IRC protocol.

The addon provides registration services for user nicknames and channels on IRC, and it provides additional tools to help administrators see and take action against abuses of their server and enforce their policies.

The addon is implemented as a pseudo-server.

That is, under normal operation, services exists as a server node in the IRC network and provides its services under the pseudonym of "fake" user nodes on the network who are used when any request needs to be made of services and who are used to return the results of the request to the user who made it.

So services is not truly an IRC server or part of IRC itself, nor are the "services users" really users, but to the network they appear as such, and the basic IRC commands for interacting with services are the same as those for interacting with an ordinary IRC Robot (or user).

Requests to services are sent over IRC's private message facility, and services' answer to a request is returned in the form of a private notice.

Although the services package allows an administrator of services to name the services units however they like, the typical names of the services provided by the sorserv addon are:

- OperServ

  Handles most administrative requests, and it is an interface usable only by global operators of the IRC system.

- NickServ

  Has the domain of requests (including administrative ones) that relate to the registration, ownership, and control of use of nicknames on the IRC system.

- ChanServ

  Has the domain of requests (including administrative ones) that relate to the registration, ownership, and control of use of channels on IRC.

- InfoServ

  Has the domain of requests (including administrative ones) that relate to the automated distribution of "news articles" by services on IRC.

- GameServ

  Handles "dice roll" requests, for use by roleplayers

### Copyright

          Copyright (c) 2002 James Hess

          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 no invariant sections, with no Front-Cover Texts, and with
          no Back-Cover Texts. A copy of the license is included in the
          section entitled "GNU Free Documentation License".

## Getting Started

### Installation Pre-requisites

- A POSIX-compatible operating system with support for BSD signals and sockets. Linux and NetBSD are known to be ok.

- The C and C++ development toolset including at least the following utilities:

  - GNU Make

  - c++ compiler (Only GCC is known to work at this time)

  - c compiler (GCC recommended)

  - The Bourne shell (/bin/sh) (bash is ok, so long as you use version 2.0.4(1) or higher)

  - The 'ar' utility (as is found in the GNU Binutils package)

  - Perl version 5.6.1 or higher

  - An ascii text editor such as vi, vim, emacs, joe, jed, nano, ed, jove, ...

- An IRC server compatible with dal4.4.10 such as dreamforge or sor1.3.x (The latter is required for certain features such as autohurt and mode locking to work as they were meant to.

It is also strongly recommended but not absolutely required that you have GNU Autoconf and GNU Automake installed, particularly if you want to tweak your build process, then you do need those.

### Installing Services

- Untar the package (where XXX is the version number)

      				gunzip services-XXX.tar.gz
      				tar xvf services-XXX.tar

- Build the package.

  - cd services

  - Run configure with appropriate options (see ./configure --help)

    Example:

        		./configure --with-cfgpath=/usr/local/lib/services \
        			    --with-help=/usr/local/lib/services/help \
        			    --with-network='sorcery.net' \
        			    --with-klinemail='kline@example.net' \
        			    --with-md5 \
        			    --with-opsemail='ircops@bogus.example.net' \
        			    --with-sendmail='/usr/sbin/sendmail -T' \
        			    --disable-grpops

  - Run make

- Install the services binary in the configuration directory by copying it there; alternatively, run make install after building services.

- Switch to the directory you named in the 'cfgpath' compilation option, and create blank databases to be used when services runs. For example:

      		cd /usr/local/lib/services
      		mkdir chanserv nickserv memoserv operserv
      		      nickserv/backups chanserv/backups
      		echo 'done' > nickserv/nickserv.db
      		echo 'done' > chanserv/chanserv.db
      		echo 'done' > memoserv/memoserv.db
      		echo 'done' > operserv/trigger.db

- Write a services.conf file and place it within the directory named in the --with-cfgpath option.

- To install the services helpfiles, unpack the help tarball one level above the directory named in the --with-help configure option. For example:

      		cd /usr/local/lib/services
      		gunzip < /path/to/tarball/services-help.tar.gz | tar -xvf -

- Add appropriate matching C and N lines for your services.conf configuration to your IRC server. The C-line and the N-line should be identical. The N-line password should match the W-line in services.conf, and the server name in the C and N-lines should match the H-line in services.conf. Example C/N-line pair (supposing that you are using Y-line class 32 for hub connection class):

      		C:127.0.0.1:mypasswd:services.hostname_here.net::32
      		N:127.0.0.1:mypasswd:services.hostname_here.net::32

- Add a U-line and a H-line for services to your IRC server's configuration file, and have all other servers on the network do the same.

  Be certain the U-line and H-lines are added before starting services, or you will need to restart services after adding the lines (and doing a server /rehash) for changes to take effect. Sample U/H-lines:

      		U:services.hostname_here.net:*:*
      		H:*::services.hostname_here.net

After services have been installed, in this manner, you should be able to start them by running the binary. If the IRC server is running and both services and your IRC server are properly configured, services will then activate.

However, if you have been installing services using administrative access on your machine, stop now , make a separate services account, and ensure that the databases and database directories where the logfiles will be written are all owned by that account.

Never run services as root for any reason.

To gain administrative access within services during the first services session, start services, register your nickname with NickServ, add a line that reads 'SRA:nickname_here' to your services.conf file, and finally, restart services.

Once you have administrative access, new configuration options can be added and helpfiles can be updated with the /OperServ reset command.

Once services start, and you are able to interact with services, the installation is completed.

It is, however, a good idea to test services functions that required special actions on your part to work properly:

Test to ensure that requests such as /NickServ HELP work (if it fails, you may not have installed the helpfiles properly, see .), and register sample nicks, channels, memos, triggers, and restart services to ensure all databases are being written: if they are not, ensure that the permissions on the files and directories allow the services user full access to those files.

If services fail to start, core.log, and notices sent to +s users on the IRC server you were trying to connect services to are good places to start looking for information on why the startup failed.

## Configuring Services

### About services.conf

Services.conf is the file used to set certain parameters and variables, particularly limits and startup settings that are global to services.

A services.conf configuration file is viewed by services as a series of directives to be executed as the file is being read, and each line is a single directive.

A directive which takes a single line consists of a special word that services knows to represent a certain kind of directive, followed by a colon, and then a parameter for the directive.

Any line beginning with a ``#'' symbol is instead read as a comment (or annotation) and is ignored by services.

This can also be used to comment out or temporarily disable a directive.

Some directives are completely optional, whereas others must be invoked at least once in order for services to start up properly.

What follows is a description of each directive.

### Mandatory configuration directives

This first set of directives are essnetial because any valid services.conf must have at least one of each for services to fully function.

- Host configuration (H line): A H directive (also called H line) contains the name of the services server. Example:

      		H:services.sorcery.net

- Port configuration (P line): A P directive tells services what port on the IRC server to connect to (the port number ircd listens on). Example:

      		P:6667

- Password configuration (W line): A W line tells services what password to use when connecting connect to an IRC server.

- IRC Server configuration (C line): A C line tells services the address of the IRC server to connect to (note, the IRC server must have a C-line and a N-line for services using a password specified in the services W line for services to connect to IRC.) Example:

      	C:127.0.0.1

- Services client configuration (XX lines):

  - An ON-line tells services what OperServ's nickname should be

  - An OU-line tells services what OperServ's username should be

  - An OH-line tells services what OperServ's hostname should be

  - An OR-line tells services what OperServ's realname should be

  - An OM-line tells services what OperServ's usermode should be

  - Nx, Cx, Mx, and Ix are the same respectively for NickServ, ChanServ, MemoServ, and InfoServ. (NN/NU/NH/NR/NM/CN/CU/CH/...)

  Example:

                      C:localhost
                      ### OperServ ###
                      ON:OperServ
                      OU:warlock
                      OH:sorcery.net
                      OR:Operator Services
                      OM:+oi

                      ### NickServ ###
                      NN:NickServ
                      NU:sorceress
                      NH:sorcery.net
                      NR:Nickname Services
                      NM:

                      ### ChanServ ###
                      CN:ChanServ
                      CU:wizard
                      CH:sorcery.net
                      CR:Channel Services
                      CM:

                      ### MemoServ ###
                      MN:MemoServ
                      MU:witch
                      MH:sorcery.net
                      MR:Memo Services
                      MM:

                      ### InfoServ ###
                      IN:InfoServ
                      IU:sorcerer
                      IH:sorcery.net
                      IR:Information Services
      		IM:

      		### GameServ ###
      		GN:GameServ
      		GU:sorcerer
      		GH:sorcery.net
      		GR:Game Services
      		GM:+oi

      		## SpamServ
      		AN:SpamServ
      		AU:service
      		AH:test.sorcery.net
      		AR:SpamServ
      		AM:+sgw

### Recommended Directives

The limiting directives are 'recommended', because although they are not required for services to operate, many of the limits have default values that might or might not be suitable to your use of services. It is a good idea to set these values yourself rather than relying on what was good for some other user to be good for you.

Limits (CL, NL, OL, BL, LL lines):

- These configuration lines are used to set limits on user data within services.

- CL Maximum number of registered channels (Default: 10)

- NL Maximum number registered nicknames (Default: 5) [not enforced]

- OL Maximum number channel operator access entries per channel (Default: 25)

- BL Maximum number akick list entries per channel (Default: 30)

- LL Maximum number nickserv access entries per nickname

               (Default: 3)
                      OL:251
                      BL:100
                      LL:10
                      CL:10
                      NL:5

### Optional Directives

These directives are completely optional. Some of them you may have reason to use, some of them you may not.

- Services IPC port configuration (IPCPORT line):

  - An IPCPORT line tells services to enable IPC (inter-process communication) and listen on a particular port for connections. Example:

                        IPCPORT:8560

  - Note that it is necessary to set up IPC logins and be using proper software for IPCPORT to be useful.

  - If an IPCPORT line is not specified, then IPC is completely disabled for security reasons.

- Services root configuration (SRA line):

  - A SRA line tells services that a particular registered nickname should be given Services Root access. Example:

        	SRA:Joe

  - Warning: Services root access allows a user to make any change to services available to be made online. It is advisable to limit this access to competent operators and developers who are familiar with the internals of services: giving this permission flag to services can be thought of as giving a user on a unix system limited superuser access (and access to the services account analogous to full superuser access over services).

  - SRA lines should not be added for a nickname until that nickname is registered -- presently, this would cause a security problem (a user you don't want to have this access could register the nick of a user you want to have access and gain that access).

  - Services.conf can be reloaded to make a new SRA using the OperServ reset command. If there is no SRA available to reload the configuration, then the only way to do that is to shut down the services process using a normal kill and bring them back on line.

  - Removing a services root requires a services restart.

- Services Operator configuration (SERVOP line):

  - A SERVOP line tells services that a particular registered nickname should be given ServOP access. Syntax and usage are the same as that of the `SRA' directive.

  - ServOp access grants many of the SRA features such as the ability to delete nicknames, channels, perm akills, ignores, autohurts; however, it does not grant the ability to change operator access flags, directly modify things, shutdown services, or access internal debugging commands. The most useful of those abilities (other than actually setting flags or killing services) can now be assigned using the OperServ SETOP command and appropriate permission flags, also.

  - ServOps can be added or removed when services is online using the /OperServ SETOP command (no restart required).

## Administering Services

### Basic Administration

Now we come to the matter of the basic services administrative functions.

First of all, to perform any administration, you must have administrative access to services. See for information on how to get services to give you full access.

Secondly, you must be using the nickname that has administrative access and be fully identified with NickServ. This is true of all commands that require special administrative access to services, including standard oper commands such as autokill.

Certain changes to services require a restart, you might also need to shut down services, for example to reboot the host machine, hence to shut down services, you do: /OperServ SHUTDOWN

Restarting services requires that you log into the machine and re-run the binary after invoking the shutdown command (normally one does a shutdown while already logged in -- sending the process signal 15 will result in a clean shutdown as well).

Another thing you might need to do while administering services is to reload the configuration file. To do this, you send the request: /OperServ reset

The /OperServ RAW request is used to cause services to send RAW data over the network.

This data is sent over a connection that the other servers recognize as a super server (because of the U-line), so use of this should be cautioned.

The /OperServ UPTIME request can be used to see how long services have been running since the past restart.

The /Operserv SYNC request can be used to force a complete sync of services' databases to disk which is very useful in running full backups.

Finally, the /NickServ DELETE command can be used to cancel NickServ registrations, /NickServ BANISH can be used to permanently block registration and use of a nick, and ChanServ has equivalent commands for channels.

The directive /OperServ HELP contains a more complete description of many requests (commands) used to administer services and the databases, that are less important to the general problem of administering services, for example: clonerules, autokills, autohurts, jupes, timers, and triggers.

### Administering Permission Flags

The command /OperServ SETOP is used to administer permission flags of operators.

There exist a number of 'flags' that allow access to specific services functions to be shared with operators.

These permission flags can be added or removed individually as needed.

The command /OperServ SETOP LIST displays a list of all operators who have been assigned any special permissions, and the command /OperSERV SETOP <nickname> shows the access flags that nickname has (if any).

Other than this, SETOP acts much like the /mode command, each flag resembles an 'mode' in that it determines the access (or no access) state of an operator to a services function.

Also note that the Administrative access to services allows one to change on/off any mode shown below, but the setop access granted by the +s access greatly limited in comparison, because a +s user can only revoke or assign certain very specific permissions, never can a user other than a services root change the flags of a '+!' user either.

The following are the flags that can be toggled by any user with access to SETOP (who also has that flag):

- +o, the default operator flags [+opka]

- +k, autokill access but not full access to autokill (limited durations <= 3 hours, limits on akill patterns, can't remove akills set by others)

- +a, access to /OperServ OVERRIDE which allows overriding of some restrictions normally placed on users, but that services allows staff of a network to override directly. Note that some uses of OVERRIDE require flags other than +a, for example editing a channel access list requires +d also.

- +p, ability to post low-priority messages on InfoServ (full ServOP access provides priority 3 and 4 posting)

The following permission flags require administrative access to change:

- +S, nickserv setflag: ability to change flags on nicknames such as vacation, kill mode, banished.

- +O, services operator access [not saved across restarts, services.conf needs to be manually updated too]

- +K, services operator autokill access (no restrictions on normal use of akill)

- +N, banish/delete nicknames

- +C, banish/delete/close channels

- +I, set services ignores

- +j, use the JUPE command

- +L, List channels/nicknames

- +c, change the clone auto-trigger rules

- +G, access to NickServ GETPASS -xfer and related commands used to help get users a working password to their nick/channels back if stolen/lost.

- +D, when combined with +a allows an oper to use /OperServ OVERRIDE to directly edit channels in certain ways as though they were the founder

- +H, autohurt: write access to the OperServ AUTOHURT list.

- +! this oper's permission entry is locked, probably because it is listed in services.conf and as a result use of SETOP on them without proper precautions would be temporary and cause potential confusion.

Information on the other commands is well-documented within services itself, see /OperServ HELP, /ChanServ HELP <command>, ... for more information.

## Services IPC

### Making contact with services

Services' IPC facility (if enabled) is provided by a TCP Stream listener that binds to the local interface.

At this time, the testing services on SorceryNet are using local port 2050 for this purpose, but any other port could be used, as an explicit port number is supplied in services.conf to enable IPC. So an application using IPC will need to consider the port number a variable parameter that is supplied when services have been configured to use a particular port number.

Contact is initiated by simply connecting to the local TCP port.

Once a connection is established, commands will be read from the connection, although many will be unavailable until you authenticate for some IPC system privileges.

All messages are read as commands, input is line-by-line much like in IRC; however, unlike in IRC, the commands are case-sensitive.

    	AUTH SYSTEM LOGIN bob

is a valid command, but

    	AuTh SyStEm LOGIN bob

is not a valid command and will either be ignored or you may instead receive an error:

    	ERR-NOAUTH (Allowed: AUTH, HELP, QUIT) - You are not authenticated.

### Authentication

#### Semantics

Before gaining any useful privileges, all IPC clients must authenticate themselves by using an auth name and a password.

Two levels of authentication are available:

- System authentication

- Object authentication

System authentication grants an application system-level permissions, for example: the ability to access the akill database, to list private data on nicknames in NickServ, or change certain parts of a nick that ordinary authentication to the nickname doesn't allow.

Object authentication grants a client extended permissions for a particular object; for example, by knowing a nickname's password, you can authenticate to that nickname in particular and make changes that your level of system authentication doesn't otherwise allow you.

In other words: system authentication grants a client certain rights on the system overall, and object authentication grants specific access to a particular nickname, channel, or other object and potentially other rights that are associated with being authenticated to that object.

#### System Authentication Details

System authentication occurs in a number of steps:

- Connection: upon successful connection, a client is greeted with the following:

      HELO IAM services.network.net
      AUTH SYSTEM PID XXXX
      AUTH SYSTEM LOGIN irc/services

  The actual information shown depends on the services session.

  This verifies you are connecting to services IPC.

  Once services has sent its AUTH SYSTEM LOGIN message, it now expects the client to send one. This can be done with:

      			AUTH SYSTEM LOGIN username

- Upon receiving and processing AUTH SYSTEM LOGIN, services will reply with OK AUTH SYSTEM LOGIN. This verifies that the message was accepted: errors such as ERR-BADLOGIN AUTH SYSTEM LOGIN - Invalid login are also possible, but for this to occur on AUTH SYSTEM LOGIN, a syntax error is likely, because usernames that aren't valid authenticators do not normally flag an error until later in the authentication process.

  In general, errors are prefixed by ERR-cause command - informative message

  If your AUTH SYSTEM LOGIN message is successful, services will additionally send you another message of type AUTH COOKIE, for example:

      AUTH COOKIE 10569CC3C9

  Services uses challenge-response authentication for both system and object logins.

  This means that if IPC were to be extended over a network, passwords would not be exposed to sniffers over the plaintext protocol.

  To respond to the message, it is necessary to compute a MD5 Message digest of the cookie and the password.

  The following is what you need to compute:

      			MD5( cookie:authenticator )

  In the cause of SYSTEM LOGINs, the authenticator is the password, whereas in the case of Object logins, the authenticator is typically MD5(password)

  The MD5 function here indicates the base16 (hexadecimal) representation of the message digest, also known as md5hex.

  Supposing my cookie were 123 and my password abc, I would compute

      MD5("123:abc") = ebecf09cd7c661306f05c7c7fa017549

  And login with:

      AUTH SYSTEM PASS ebecf09cd7c661306f05c7c7fa017549

- Recognition

  An example of the message that follows a successful SYSTEM PASS:

      OK AUTH SYSTEM PASS
      YOU ARE www/test

  Once you receive the OK AUTH SYSTEM PASS message, your connection is authenticated, and you can issue ALTER, QUERY commands or authenticate to OBJECTs if the user you've authenticated with has those privileges.

#### Object Authentication Details

The syntax and usage for OBJECT authentication is the same as that for SYSTEM authentication with a few differences.

- Instead of AUTH SYSTEM LOGIN user, the message is:

      	AUTH OBJECT LOGIN object type object name

  Object type is one of RNICK for Registered Nickname, or RCHAN for registered channel.

  New types could be created as well.

- The response to a valid AUTH OBJECT LOGIN message is:

      AUTH COOKIE XXX

  And the client is then expected to send:

      AUTH OBJECT PASS response

  The response is the result of applying the MD5 function, in this fashion:

      			MD5(cookie:MD5(secret authenticator))

  For RNICKs and RCHANs, the secret authenticator is simply their password.

- Successful authentication to an object results in this message:

      OK AUTH OBJECT RNICK PASS

### Query Messages

#### System Queries

- QUERY SYSTEM UPTIME

#### Object Queries

- QUERY OBJECT AKILL|AHURT|IGNORE LIST

- QUERY OBJECT RNICK nick ISREG

  Results in, for instance:

      OK QUERY OBJECT RNICK=nickname ISREG=TRUE - Nickname is registered.

  OR

      OK QUERY OBJECT RNICK=nickname ISREG=FALSE - Nickname is not registered.

- QUERY OBJECT RNICK nick ISBYPASS

  Example response:

       OK QUERY OBJECT RNICK=nick ISBYPASS=TRUE
      						ERR-BADTARGET QUERY OBJECT RNICK=nickname - NOT_REGISTERED

- QUERY OBJECT RNICK nick REG-TIME

  Sample result:

      OK QUERY OBJECT RNICK=nickname REG-TIME 861620971

- QUERY OBJECT RNICK nick LAST-TIME

  Sample result: OK QUERY OBJECT RNICK=nickname LAST-TIME 1067654340

- QUERY OBJECT RNICK nick MARK

  Sample result: OK QUERY OBJECT RNICK=Mysidia MARK NO

  OK QUERY OBJECT RNICK=Mysidia MARK YES

- QUERY OBJECT RNICK nick LAST-HOST

  Sample result:

      OK QUERY OBJECT RNICK=nickname LAST-HOST asdf.com.hmsk
      						ERR-NOPRIV QUERY OBJECT RNICK=nickname LAST-HOST - User WWW/test Not authorized to query RNICK LAST-HOST.

- QUERY OBJECT RNICK nick NUM-MASKS

- QUERY OBJECT RNICK nick ACCESS-*

- QUERY OBJECT RNICK nick ACCESS-number

- QUERY OBJECT RNICK nick URL

- QUERY OBJECT RNICK nick EMAIL

- QUERY OBJECT RNICK nick LAST-HOST-UNMASK

- QUERY OBJECT RNICK nick FLAGS

- QUERY OBJECT RNICK nick OPFLAGS

- QUERY OBJECT RNICK nick BADPWS

- QUERY OBJECT RNICK nick TIMEREG

- QUERY OBJECT RNICK nick IS-READTIME

- QUERY OBJECT RNICK nick ACC

### Alter Messages

#### Registered Nick Alterations

- ALTER OBJECT RNICK nick [+|-]BYPASS

- ALTER OBJECT RNICK nick PASS new password

** Many of the other QUERY RNICKs should work with ALTER as well **

#### Other IPC Commands

- QUIT

- HELP

## GNU Free Documentation License

                    GNU Free Documentation License
                       Version 1.1, March 2000

     Copyright (C) 2000  Free Software Foundation, Inc.
         59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

    0. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other
    written document "free" 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.

    This License is a kind of "copyleft", 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.

    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.

    1. APPLICABILITY AND DEFINITIONS

    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 "Document", below, refers to any
    such manual or work.  Any member of the public is a licensee, and is
    addressed as "you".

    A "Modified Version" 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.

    A "Secondary Section" is a named appendix or a front-matter section of
    the Document 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.

    The "Invariant Sections" are certain Secondary Sections whose titles
    are designated, as being those of Invariant Sections, in the notice
    that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed,
    as Front-Cover Texts or Back-Cover Texts, in the notice that says that
    the Document is released under this License.

    A "Transparent" copy of the Document 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 "Transparent" is called "Opaque".

    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.

    The "Title Page" 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, "Title Page" means
    the text near the most prominent appearance of the work's title,
    preceding the beginning of the body of the text.

    2. VERBATIM COPYING

    You may copy and distribute the Document 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 section 3.

    You may also lend copies, under the same conditions stated above, and
    you may publicly display copies.

    3. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100,
    and the Document's license notice requires Cover Texts, 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 Document and satisfy these conditions, can be treated
    as verbatim copying in other respects.

    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.

    If you publish or distribute Opaque copies of the Document numbering
    more than 100, you must either include a machine-readable Transparent
    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.

    It is requested, but not required, that you contact the authors of the
    Document well before redistributing any large number of copies, to give
    them a chance to provide you with an updated version of the Document.

    4. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under
    the conditions of sections 2 and 3 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:

    A. Use in the Title Page (and on the covers, if any) a title distinct
       from that of the Document, 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.
    B. List on the Title Page, as authors, one or more persons or entities
       responsible for authorship of the modifications in the Modified
       Version, together with at least five of the principal authors of the
       Document (all of its principal authors, if it has less than five).
    C. State on the Title page the name of the publisher of the
       Modified Version, as the publisher.
    D. Preserve all the copyright notices of the Document.
    E. Add an appropriate copyright notice for your modifications
       adjacent to the other copyright notices.
    F. Include, immediately after the copyright notices, a license notice
       giving the public permission to use the Modified Version under the
       terms of this License, in the form shown in the Addendum below.
    G. Preserve in that license notice the full lists of Invariant Sections
       and required Cover Texts given in the Document's license notice.
    H. Include an unaltered copy of this License.
    I. Preserve the section entitled "History", and its title, and add to
       it an item stating at least the title, year, new authors, and
       publisher of the Modified Version as given on the Title Page.  If
       there is no section entitled "History" in the Document, 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.
    J. Preserve the network location, if any, given in the Document for
       public access to a Transparent 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 "History" 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.
    K. In any section entitled "Acknowledgements" or "Dedications",
       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.
    L. Preserve all the Invariant Sections of the Document,
       unaltered in their text and in their titles.  Section numbers
       or the equivalent are not considered part of the section titles.
    M. Delete any section entitled "Endorsements".  Such a section
       may not be included in the Modified Version.
    N. Do not retitle any existing section as "Endorsements"
       or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or
    appendices that qualify as Secondary Sections 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 Invariant Sections in the Modified Version's license notice.
    These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains
    nothing but endorsements of your Modified Version 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.

    You may add a passage of up to five words as a Front-Cover Text, and a
    passage of up to 25 words as a Back-Cover Text, to the end of the list
    of Cover Texts in the Modified Version.  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 Document 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.

    The author(s) and publisher(s) of the Document do not by this License
    give permission to use their names for publicity for or to assert or
    imply endorsement of any Modified Version.

    5. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this
    License, under the terms defined in section 4 above for modified
    versions, provided that you include in the combination all of the
    Invariant Sections of all of the original documents, unmodified, and
    list them all as Invariant Sections of your combined work in its
    license notice.

    The combined work need only contain one copy of this License, and
    multiple identical Invariant Sections 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.

    In the combination, you must combine any sections entitled "History"
    in the various original documents, forming one section entitled
    "History"; likewise combine any sections entitled "Acknowledgements",
    and any sections entitled "Dedications".  You must delete all sections
    entitled "Endorsements."

    6. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document 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.

    You may extract a single document from such a collection, and distribute
    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.

    7. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document 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 Modified Version
    of the Document, provided no compilation copyright is claimed for the
    compilation.  Such a compilation is called an "aggregate", 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 Cover Text requirement of section 3 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.

    8. TRANSLATION

    Translation is considered a kind of modification, so you may
    distribute translations of the Document under the terms of section 4.
    Replacing Invariant Sections 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.

    9. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document 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.

    10. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation 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
    http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number.
    If the Document specifies that a particular numbered version of this
    License "or any later version" 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.

    ADDENDUM: How to use this License for your documents

    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:

          Copyright (c)  YEAR  YOUR NAME.
          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 Invariant Sections being LIST THEIR TITLES, with the
          Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
          A copy of the license is included in the section entitled "GNU
          Free Documentation License".

    If you have no Invariant Sections, write "with no Invariant Sections"
    instead of saying which ones are invariant.  If you have no
    Front-Cover Texts, write "no Front-Cover Texts" instead of
    "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.

    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 GNU General Public License,
    to permit their use in free software.