Services -- a system of IRC services for IRC networks
-----------------------------------------------------

Services is copyright (c) 1996-1998 Andrew Church.  There is absolutely NO
WARRANTY provided with this program; if it blows up in your face, you get
to clean up the mess.  Services may be freely redistributed; see the GNU
General Public License (in the file "COPYING") for details.

Services has a web site at:
	http://achurch.dragonfire.net/services/
The latest version of Services can always be obtained at that site, or at
the corresponding FTP archive:
	ftp://ftp.dragonfire.net/software/unix/irc/
If you obtained your copy of Services from a different location, check at
one of the above sites to ensure that you have the latest, complete copy.


1. INTRODUCTION

     Services is a system of services (as the name implies) to be used
with Internet Relay Chat networks.  Services provides for definitive
nickname and channel ownership, as well as the ability to send messages
("memos") to offline users, and gives IRC operators considerably more
control over the network, enabling them to change modes in any channel and
place network-wide bans, among other things.
     Services runs as a server on an IRC network, and is designed to use
the RFC 1459 IRC protocol, with some optional additions discussed at the
end of this document.
     Services was designed for use with versions of the DALnet IRC server
implementation (ircd.dal) through 4.4.13.  Services will also operate with
servers based directly on the RFC 1459 protocol, as well the Undernet
server (ircu) and versions of ircd.dal from 4.4.15 through at least 4.6.3.
As of this release, ircu 2.10 is supported, but Services will continue to
use the ircu 2.9 protocol, so support for that is required in the IRC
server.  The following servers have been reported NOT to work with
Services:
          NewNet
          ircd-hybrid
          ircd 2.x with "+CS" extension
          TS4
          ircd 2.9.4
     If you have one of these servers or you cannot get Services to work
with your server, I recommend downloading and installing ircd.dal 4.4.10,
which is available in the same place as Services:

ftp://ftp.dragonfire.net/software/unix/irc/


2. CONFIGURATION, COMPILATION AND INSTALLATION

     In order to compile Services, you'll need the Bourne shell or a
compatible shell (such as GNU bash), GNU make or a compatible make (which
needs to support the "include" and "ifdef" directives), and an ANSI C
compiler (gcc recommended).  If you want to modify the language files, you
will also need the Perl interpreter in your path.  All GNU utilities can be
found at ftp://prep.ai.mit.edu/pub/gnu/.
     Before trying to compile Services, there are some manual configuration
tasks that need to be done: run the "configure" script, edit config.h, and
(optionally) edit the top section of the Makefile.
     The "configure" script will try to learn how things work on your
system, and set up appropriate Makefile and C source definitions.  It will
also ask you a few questions about how you want Services set up.  (It will
ask all of the questions before doing any of the automated tests.)  If you
get an error while running the script, get bash (if you don't already have
it) and run "bash configure".  IMPORTANT NOTE:  Make sure you select the
correct IRC server style!  If Services compiles correctly but you only get
messages like "Internal error - unable to process request", the most likely
cause is that you chose the wrong IRC server style.
     config.h contains all of the basic definitions for Services -- uplink
server, data directory, default limits, etc.  Some of these can be changed
with command-line options (see below), but you may find it more convenient
to set them as defaults.  Others can be set only in config.h, and you
should review them to make sure they are to your liking.  Pay particular
attention to the SERVICES_ROOT define; this is the only person who can add
Services admins (and Services admins, in turn, are the only people who can
add Services operators).  See section 4 below for more information.
     The Makefile has a section at the top allowing you to configure
Services' general mode of operation.  There are two such modes: normal
(full services available) and skeleton (-DSKELETON: only OperServ is
enabled).  Normally you will want to compile without -DSKELETON, but a
skeleton version can be useful for emergencies when the main copy of
Services goes down and the databases are not accessible.  You can also add
additional C compiler flags here, such as warning flags (this can also be
done in the configure script using the -cflags command-line option).
     Once these steps are done, you should be able to compile Services with
little trouble.  If Services fails to compile on your system, or if you
have to tweak configure's output to get it to work, let me know what went
wrong so I can try and incorporate a fix into the configure script or the
main code.
     Once Services is compiled, type "make install" to copy the program
files to their destinations.  If you are installing Services for the first
time, you also need to run "make install-data" to copy the data files to
the destination data directory.  Care should be taken that only authorized
people have access to the data files; by default (changeable with the
configure script), passwords are NOT encrypted, so unauthorized access to
the files would be a big problem!


3. OPERATION

     This section does not detail the operation of the individual pieces of
Services; that information can be found in the online help files
("/msg *Serv help").  It only describes how to start Services itself.
     Normally, Services can be run simply by invoking the "services"
executable.  Services will then use the defaults specified in the config.h
file, and connect to the specified uplink server.  Alternatively, any of
the following command-line options can be specified to change the default
values:
	-remote server[:port]	Connect to the specified server
	-local host  -or-	Connect from the specified address (e.g.
	       [host]:[port]	    for multihomed servers)
	-name servername	Our server name (e.g. services.some.net)
	-desc string		Description of us (e.g. SomeNet Services)
	-user username		Username for Services' nicks (e.g. services)
	-host hostname		Hostname for Services' nicks (e.g. esper.net)
	-dir directory		Directory containing Services' data files
				    (e.g. /usr/local/lib/services)
	-log filename		Services log filename (e.g. services.log)
	-update secs		How often to update databases (in seconds)
	-expire secs		How often to check for nick/channel
				    expiration (in seconds)
	-debug			Enable debugging mode--more info sent to log
				    (give option more times for more info)
	-readonly		Enable read-only mode--no changes to
				    databases allowed, .db files and log
				    not written
	-nofork			Do not fork after startup; log messages will
				    be written to terminal (as well as to
				    the log file if not in read-only mode)

     Upon starting, Services will parse its command-line parameters, open
its logfile, then (assuming all went well and the -nofork option is not
given) detach itself and run in the background.  If Services cannot connect
to its uplink server, it will terminate immediately; otherwise, it will run
until the connection is terminated (or a QUIT, SHUTDOWN, or RESTART command
is sent--see OperServ's help).
     If Services is run with the "-readonly" command-line option, it can
serve as a "backup" to the full version of Services.  A "full" version of
Services (run without -readonly) will automatically reintroduce its
pseudo-clients (NickServ, ChanServ, etc.), while a "backup" Services will
not, thus allowing full Services to be brought up at any time without
disrupting the network (and without having to take backup Services down
beforehand).
     The "-debug" option is useful if you find or suspect a problem in
Services. Giving it once on the command line will cause all traffic to and
from Services as well as some other debugging information to be recorded in
the log file; if you send a bug report, PLEASE include an excerpt from the
log file WITH DEBUGGING ACTIVE--I cannot emphasize enough how important
this is to tracking down problems.  (You can also enable debugging while
Services is running using OperServ's SET DEBUG command.)  If you repeat the
-debug option more than once, the debugging level will be increased, which
provides more detailed information but may also slow Services down
considerably and make the log file grow dramatically faster (in particular,
at debug level 4 a message is written to the log for every character
received from the server).  In general, a debug level of 1 is sufficient
for me to be able to trace a problem, because all network traffic is
included and I can usually cause the problem to occur again.
     Two additional programs are available in addition to the main
executable: "listnicks" and "listchans", both installed as hard links to
the main executable.  The programs will list all registered nicknames and
channels, respectively; or, if given the -c option, will display the
number of registered nicknames or channels.


4. OVERVIEW OF SERVICES CLIENTS

     This is a brief introduction to the various clients available from
Services.  All *Serv clients can be /msg'd with "help" for a general
introduction or "help <command>" for more detailed command descriptions.
A command reference can also be found at:
	http://achurch.dragonfire.net/services/commandref.html

     NickServ is the nickname server; it allows users to register and
control nicknames, and will (at the user's choice) /kill any unauthorized
user who tries to use that nick after a warning.  NickServ also allows
users to select a language which Services will then use for all
communication with the user (command responses as well as automatic
notices).
     ChanServ is the channel server; as NickServ does with nicknames, it
allows users to register and control channels.  There is a much wider array
of controls available via ChanServ than NickServ, since there are
considerably more features available for channels than for nicknames.
These include automatic mode setting, topic retention (active by default,
this will cause the channel's topic to be saved while the channel is empty
and restored when a user joins it again), and automatic opping, voicing, or
kicking of selected users, among others.
     MemoServ allows users to send short messages to other users, which can
be stored and retrieved at the recipient's convenience.
     HelpServ allows users to request information about Services and/or the
network on which it is being used.  HelpServ will, on request, send a help
text to a user.  The actual help texts used by HelpServ are stored in the
"helpfiles" subdirectory of the Services data directory; HelpServ
lowercases its arguments, joins them with slashes, and attempts to read the
filename given by the resulting string.  For example, the command
"/msg HelpServ server Dragonfire" causes HelpServ to look for the file
helpfiles/server/dragonfire in the data directory.  If a given help file is
a directory (for example, "/msg HelpServ server" where helpfiles/server is
a directory), HelpServ will look for a file named "index" in that directory
and send it in response to the help request if it exists.  (Note that the
other pseudo-clients have their own help systems independent of HelpServ,
and the help texts for those clients are stored in the "lang" subdirectory
of the Services distribution.)
     IrcIIHelp is HelpServ under another name, and allows ircII users to
simply type "/help <topic>" to get help on the ircII client.  The files can
also be accessed with "/msg HelpServ ircii <topic>".
     OperServ provides services to IRC operators, including the ability to
send a network-wide message from a Services pseudo-client and obtain
statistics on Services and the network.  A set of IRC operators can be
defined as "Services operators" using the OPER command; these users will
have access to more functions, including the ability to change the mode of
any channel, kick any user from a channel, and add and remove network-wide
bans ("autokills" or AKILLs, similar to classic K:lines but applying to all
servers on the network).  A more privileged group of operators can be
defined as "Services administrators" via the ADMIN command, and can perform
additional functions, such as manually updating Services' databases or
shutting Services down, as well as set options for any nickname and channel
without needing to identify for that nick or channel.  The only person who
can use the ADMIN ADD and ADMIN DEL commands is the Services superuser
(Services root), whose nick should be inserted in the SERVICES_ROOT define
in config.h.  (Note that Services will not recognize a user as a Services
operator or admin unless that user has identified with NickServ.)
Obviously, all these functions should be used with care.
     DevNull is just like its Unix equivalent /dev/null: it ignores
anything sent to it.  It can be removed, by undefining DEVNULL_NAME in
config.h, without affecting the rest of Services in any way.
     Global is the global noticer: when Services is instructed to send a
notice to all clients on the network, this nickname sends the message.


5. IRC PROTOCOL ADDITIONS

Services has not been tested on bare (non-TS8) irc2.x servers; please
report any problems.

The following commands, not defined in RFC 1459, are used by Services if
available on the selected server type:

AKILL

    Syntax: AKILL <hostmask> <usermask> <reason>

    Adds an AutoKill to the network; this is like a K:line, but is
    propogated to all servers.  Any user matching the usermask and
    hostmask will not be allowed to connect.

    Example:  :services.esper.net AKILL *.lame.com lamer :Flooding
        Disallows any client matching "lamer@*.lame.com" from connecting
        to the network.

RAKILL

    Syntax: RAKILL <hostmask> <usermask>

    Removes an AutoKill line from all servers.

    Example:  :services.esper.net RAKILL *.lame.com lamer
        Removes the AutoKill described in the previous example.

GLINE

    Syntax: GLINE * +<expire> <mask>

    Similar to AKILL, defines a network-wide ban.  <expire> is given in
    seconds from the current time, so, for example, 3600 means "1 hour
    from now".

    Example:  :services.esper.net GLINE * +604800 lamer@*.lame.com
        Disallows any client matching "lamer@*.lame.com" from connecting
        to the network for the next 604800 seconds (1 week).


GLOBOPS

    Syntax: GLOBOPS <message>

    Sends a message to all users with user mode +og.

    Example:  :Alcan GLOBOPS :Watch out for flooders from *.lame.com.

GOPER

    Syntax: GOPER <message>

    Sends a message to all IRC operators, regardless of other user modes.

    Example:  :services.esper.net GOPER :WARNING -- clones detected from
                      ppp1-9.lame.com


6. REACHING THE AUTHOR

     I can be reached via E-mail at achurch@dragonfire.net.  Please feel
free to send comments, suggestions, problem reports, context diffs, or
whatever, though you may not receive any reply.  Please do NOT ask for or
expect direct online help, as I am quite busy and cannot spare the time to
set up Services myself on every system where it will be used.  If you do
ask, expect to be abruptly dismissed or ignored.

     If you prefer, you may leave me an IRC memo on the EsperNet IRC
network (nickname Alcan).  If you do this, please include your problem or
suggestion _in the memo_.  Don't just say "I need to talk to you"; such
memos will be ignored.  Again, don't expect a reply even if you do have a
valid problem or suggestion; problem reports will be noted and addressed as
soon as practical, and suggestions will be taken into consideration for
future versions.

     There is also a mailing list, services@dragonfire.net, for discussion
of and announcements regarding Services.  The list is unmoderated, but you
must be subscribed to the list in order to post to it.  To subscribe, send
an E-mail message to:

	services-request@dragonfire.net

with a subject of "subscribe" and a body of:

subscribe <your-address>

where <your-address> is your E-mail address (without the angle brackets).
Unsubscription works the same way, but use "unsubscribe" instead of
"subscribe".
