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

Services is copyright (c) 1996-1998 Andrew Church.  Services may be freely
redistributed; see the GNU General Public License (in the file "COPYING")
for details.

The primary distribution site for Services is:

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

If you obtained your copy of Services from a different location, check at
the above site 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 additions discussed at the end of this
document.
     Also, Services may not work with the reference implementation of RFC
1459 (irc2.x); an extension to the code is required to allow Services to
change channel modes without requiring channel operator status.  The DALnet
extension to ircd (which can be found at ftp.dal.net:/pub/dalnet/server) is
one implementation with the necessary extension; the Undernet server,
a.k.a. ircu, is also reported to work.  The following servers are known to
NOT work with Services:
          NewNet
     The recommended server is DALnet version 4.4.4; version 4.4.10 is also
believed to work.  Both are available at the primary Services FTP site:

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

As of Services 3.0.4, preliminary support for the DALnet IRC server version
4.4.15 and above is present.  This has not been extensively tested and does
not include any of the new "features" of that version of the DALnet server.


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" directive), and an ANSI C compiler (gcc
recommended).  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
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 "Sorry, registration failed", 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, etc.  Many 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.  (In particular, you
should probably change GLOBAL_NOTICER_NICK to something appropriate for
your network.)
     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).  Remember to "make clean" after you change this!  (Note: the
functionality that used to be provided by -DREADONLY is now a command line
option, -readonly.)
     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 programs
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, then "make install-help" to install the
online help files.  Care should be taken that only authorized people have
access to the data files; by default, passwords are NOT encrypted, so
unauthorized access to the files could be a big problem!  If you are
upgrading from a previous version of Services, you will want to run
"make install-help" to copy the new help files to the Services data
directory.

     NOTE:  Services databases are endian-specific; that is, databases
created on a little-endian machine won't work on a big-endian one and
vice-versa (except in the degenerate case of an empty database).
Currently, this means that Services can't be moved from or to an Intel x86
machine without manually converting the databases, until Intel gets their
act together and starts making big-endian processors like the rest of the
world.  And no, don't ask me for an endian converter, because I don't have
one and don't plan to write one unless and until I need it.


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" or read lib/*serv/index).  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
	-name servername	Our server name (e.g. services.esper.net)
	-desc string		Description of us (e.g. EsperNet 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)
	-tz timezone		Name of Services' timezone (e.g. EST)
	-update secs		How often to update databases, in seconds
	-debug			Enable debugging mode--more info sent to log
	-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

     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 or SHUTDOWN command is sent--
see OperServ's help texts).
     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).
     Two additional programs 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 more detailed command descriptions.
     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.
     ChanServ is the channel server; as NickServ, 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.  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 (and kicking) of selected users.
     MemoServ allows users to send short messages to other users, which can
be stored and retrieved at the recipient's convenience.
     HelpServ is Services' help system; it will, on request, send a help
text to a user.  Other Services clients also call on HelpServ for their
own help functions.  (So, for example, "/msg ChanServ help register" is the
same as "/msg HelpServ chanserv register".  The actual help texts are
stroed 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.
     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
change the mode of any channel, kick any user from a channel, and add and
remove network-wide bans (similar to classic K:lines, but applying to all
servers on the network).  A certain set of operators can be defined (in
config.h) as Services operators, and can perform additional functions, such
as manually updating Services' databases or shutting Services down.  (Note
that Services will not recognize a user as a Services operator unless that
user both is in the SERVICES_ADMINS definition and 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 without affecting the rest of
Services in any way.
     EsperNet is the global noticer: when Services is instructed to send a
notice to all clients on the network, this nickname sends the message.
Obviously, you should change it to the name of your network (or some other
useful name)!  See config.h for the name definition.


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:

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.

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.  The same applies to
comments, suggestions for improvement, or anything else related to
Services.

     If you prefer, you may leave me an IRC memo on the EsperNet IRC
network.  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.
