           Frequently Asked Questions (FAQ) concerning Services
           ====================================================

---------------------------------------------------------------------------

Index:
======

General questions
-----------------
A.1. What is Services (a.k.a. IRC Services or Services for IRC Networks)?

A.2. Where can I find Services?

A.3. Does Services run under Windows?

A.4. How about OS/2?

A.5. Can I send you questions without reading the FAQ or README files?

A.6. There is no question number 6.

Compiling and starting Services
-------------------------------
B.1. When I run "make", I get an error message like "missing separator",
     "Need an operator", "Unexpected end of line seen", etc.

B.1.5. I get an error like "Makefile.inc not found".

B.2. I typed "./services" at the command line, but nothing happened!

B.2.5. I get an error in the log file saying "Protocol mismatch" or "You
       have not registered".

B.3. I need support for the XYZ protocol.

B.4. Whenever I start Services, I get a message on my IRC server saying
     "connection refused" or something similar, and Services gives an error
     message from the server saying "Closing Link: ...".

B.5. My IRC server is giving me messages like "Connection to
     services.whatever.net[127.0.0.1] activated" and then "Access denied --
     no N line".  Why?

B.6. When I say "/connect services.*", it doesn't work!

B.7. Services complains in the logfile about being unable to load the
     default language, or gives messages like "Warning: bad number of
     strings (747, wanted 863) for language 0 (en_us)".

Running Services
----------------
C.1. Services always dies after about five minutes, saying "FATAL ERROR!
     Can't back up nick.db".

C.2. Services can't keep up with my network--it eventually falls off with
     "Max SendQ exceeded".  What can I do about this?

C.3. Services starts up okay, but if I try to register a nickname, it
     replies with "Sorry, registration failed" or "Internal error -
     unable to process request."

C.4. Services crashed with a segmentation fault.

C.5. Services' channel mode setting doesn't work.  I can't set modes with
     OperServ, and every time ChanServ tries to set a mode, my server
     reverses the change.

C.5.5. But my U:lines are set correctly!

C.6. My server sometimes sends messages saying "Notice -- User on
     services.my.net remotely JOINing new channel".

C.7. How can I make Services send replies using PRIVMSG (/msg) instead of
     NOTICE?

C.8. Can I make ChanServ send channel modes all at once instead of one at
     a time?

C.9. I'm using Unreal, and Services keeps removing any G-lines placed with
     /gline.  How can I make it stop?

NickServ features
-----------------
D.1. When I link nicks, the URL and E-mail fields aren't copied.

D.2. Some people get nick collided when their nick is changed to Guest###.

ChanServ features
-----------------
E.1. Services ignored the SET SUCCESSOR setting and deleted a channel when
     the founder expired.

E.2. When ChanServ sets the topic for a channel, it always appends
     "(nickname)" to the end.  How do I make it not do that?

OperServ features
-----------------
F.1. Using the OperServ JUPE command results in server messages like
     "Server juped.server introduced by non-hub server services.my.net".

F.2. I can't use the ADMIN command to add Services admins--it tells me
     "Permission denied."

F.3. How can I set up multiple Services roots?

F.4. When I add an AKILL, the users matching it don't get killed.

F.5. Services reports (via /stats u or /msg OperServ STATS) a different
     number of users online than I get from doing /lusers.

F.6. Services killed a user it thought was cloning when the user really
     wasn't.

F.7. Trying to use OperServ gives me "Access denied", but my nick is in the
     ServicesRoot directive and is registered, and I've identified for my
     nick.

F.8. I used the RAW command to do something, and then Services stopped
     working!

F.9. On Unreal, every time I use the /gline command, Services cancels the
     G:line.

Bug reporting and feature requests
----------------------------------
Z.1. Services doesn't speak my language!

Z.2. I selected a language other than English, but sometimes Services sends
     responses in English instead.

Z.3. I've found a bug that's not mentioned here or in the README or
     KnownBugs files.  What should I do?

Z.4. Your Services program doesn't do XYZ like DALnet Services.  What's
     wrong?

Z.5. I've got a great new idea for Services.  Do you want it?

Z.6. Examples of features I have been asked about and why I won't add (or
     haven't yet added) them--so don't ask me about them.

Z.7. I submitted a bug report / feature request and it got fixed / added,
     but I didn't get credit in the Changes file!

---------------------------------------------------------------------------

General questions:
==================

A.1. What is Services (a.k.a. IRC Services or Services for IRC Networks)?

	Services is a package of services for IRC networks.  See the README
	file for more information.


A.2. Where can I find Services?

	The latest version can always be found at the official Services
	distribution site:

	ftp://ftp.ircservices.za.net/pub/ircservices/


A.3. Does Services run under Windows?

	No.  I don't know enough about Windows programming to accomplish
	this, nor do I have the time to do so.  Unless and until someone
	contributes patches allowing Services to run under Windows, you'll
	need a different operating system (try Linux or FreeBSD).


A.4. How about OS/2?

	You may have better luck there; as of version 4.0, Services tries
	to be compilable on OS/2 through patches and suggestions from
	others.  I've never tested it, though (I don't use OS/2).


A.5. Can I send you questions without reading the FAQ or README files?

	Sure you can.  It's one of the easiest ways I know to get your
	messages ignored.


A.6. There is no question number 6.

---------------------------------------------------------------------------

Compiling and starting Services:
================================

B.1. When I run "make", I get an error message like "missing separator",
     "Need an operator", "Unexpected end of line seen", etc.

	Your make program isn't compatible with the Makefile for Services.
	The Makefile was designed to work with GNU make, and as such may
	not work on other systems' "make" programs.  If you get an error
	from "make", obtain GNU make from ftp://prep.ai.mit.edu/pub/gnu/
	(or wherever you prefer) and use it instead of your system's
	default "make".  Note that GNU make may already be installed on
	your system; try using the command "gmake" instead of "make".

	The make programs bundled with SunOS/Solaris and FreeBSD have been
	reported not to work; you will need to use GNU make on these
	systems.

B.1.5. I get an error like "Makefile.inc not found".

	You forgot to run the configure script first.  See the README file
	for compilation instructions.


B.2. I typed "./services" at the command line, but nothing happened!

	Services puts itself in the background when it starts, so you get
	your shell prompt right back.  Meanwhile, Services will continue
	setting up, then connect to the IRC server specified in
	services.conf (or on the command line).  If it doesn't connect, you
	probably specified the wrong server type when running the configure
	script.

	Also make sure that you are actually running one of the supported
	servers.  There are a gazillion different variations on the basic
	IRC protocol out there, and I have neither the time nor the desire
	to add support for all of them.  See the README for information on
	which servers are known to work and not to work with Services.  If
	your server is not listed in the "interoperates" list as a
	supported server, chances are it will not work.

	As always, you can check the log file (services.log by default) for
	error messages.


B.2.5. I get an error in the log file saying "Protocol mismatch" or "You
       have not registered".

	This means you've selected the wrong protocol for your IRC server;
	see the previous answer.  In some cases, it may also indicate that
	you have configured Services incorrectly; in particular, make sure
	the ServerName directive in services.conf is set to a different
	name from any other server on your network.


B.3. I need support for the XYZ protocol.

	Tough luck, unless you want to write support for it yourself, or you
	can supply a complete RFC-style description of the protocol to work
	from.


B.4. Whenever I start Services, I get a message on my IRC server saying
     "connection refused" or something similar, and Services gives an error
     message from the server saying "Closing Link: ...".

	You need to configure your IRC server to accept Services as an IRC
	server.  For most IRC servers (those based on the irc2.x
	distribution), that involves adding two lines like the following to
	your ircd.conf file:

	C:127.0.0.1:password:services.whatever.net::99
	N:127.0.0.1:password:services.whatever.net::99

	See the example ircd.conf provided with most distributions for the
	meaning of each field.


B.5. My IRC server is giving me messages like "Connection to
     services.whatever.net[127.0.0.1] activated" and then "Access denied --
     no N line".  Why?

	This is typically caused by including a port number in the C:line
	for Services, which tells your server to try to autoconnect to it
	(depending on the class (Y:line) settings).  This is not what you
	want, because Services will connect to the server itself, but does
	not listen for servers to connect to it.  The solution is to remove
	the port number from the C:line.


B.6. When I say "/connect services.*", it doesn't work!

	Of course not.  RTFM (Read The Fine Manual), and see the previous
	answer.


B.7. Services complains in the logfile about being unable to load the
     default language, or gives messages like "Warning: bad number of
     strings (747, wanted 863) for language 0 (en_us)".

	You forgot to run "make install".

---------------------------------------------------------------------------

Running Services:
=================

C.1. Services always dies after about five minutes, saying "FATAL ERROR!
     Can't back up nick.db".

	Make sure that the user Services runs as has write access to the
	data directory, and that the data directory actually exists (the
	latter shouldn't be a problem if you ran the configure script).
	This means Services needs write and execute permission on the data
	directory itself and execute permission on every parent directory
	of the data directory.


C.2. Services can't keep up with my network--it eventually falls off with
     "Max SendQ exceeded".  What can I do about this?

	If you have a really large network (tens of thousands of
	simultaneous users), Services in its default configuration will
	probably be unable to keep up with all the network traffic.  Here
	are some possible ways to speed Services up:

	  - Run it on a faster computer.  (Services does _not_ need to run
	    on the same system as an ircd!  If you have several computers
	    connected via Ethernet or another type of high-speed network,
	    it's perfectly fine to have an ircd on one machine and Services
	    on a separate machine.)

	  - Enable the STREAMLINED option in the Makefile.  This will
	    disable clone checking, session limiting, and StatServ.

	  - When running configure, do not enable statistics generation
	    (StatServ).

	  - Comment out MSNotifyAll in services.conf.

	  - Reduce the nickname and channel expiration periods.

	  - Reduce the size of your autokill and session limit exception
	    lists as much as possible.

	  - Reduce the maximum number of autokicks per channel.

	  - Increase ExpireTimeout in services.conf to reduce the frequency
	    of checking for nickname and channel expiration.

	  - Increase UpdateTimeout in services.conf, but beware that this
	    will mean more potential data loss if/when Services falls off
	    your network or crashes.

	  - DON'T run in debug mode!

	Services is known to be functional on networks as large as 22,000
	simultaneous users with 260,000 registered nicks.


C.3. Services starts up okay, but if I try to register a nickname, it
     replies with "Sorry, registration failed" or "Internal error -
     unable to process request."

	Make sure you've selected the correct IRC server type in the
	configure script; see question B.2 for details.


C.4. Services crashed with a segmentation fault.

	See if you can reproduce this by doing a certain sequence of
	actions.  If so, please report it in detail (see question Z.3
	below).  If not, you're probably out of luck; if you like, you can
	report it anyway, but chances are it won't get fixed if I'm unable
	to reproduce it.  If you do have such a problem, you may find the
	crontab utility useful for dealing with it, by making a script to
	check whether Services is running and restart it if not.


C.5. Services' channel mode setting doesn't work.  I can't set modes with
     OperServ, and every time ChanServ tries to set a mode, my server
     reverses the change.

	If you're running the DALnet or Unreal (and maybe Undernet) daemon,
	make sure EVERY server on your network has a U: line for Services
	in ircd.conf, for example:

	U:services.whatever.net:*:*

	As of version 4.0, Services will report this in a WALLOPS or
	GLOBOPS message the first time it discovers it cannot change modes.


C.5.5. But my U:lines are set correctly!

	If the file was created, edited, or copied from a Windows
	computer, then it may be corrupt (Windows inserts ^M characters
	at the end of every line), which will cause the ircd to not
	recognize the U:line.  Use a text editor (like vi or emacs) to
	remove the ^M characters or re-create the file from scratch.


C.6. My server sometimes sends messages saying "Notice -- User on
     services.my.net remotely JOINing new channel".

	This is normal, and happens whenever ChanServ kicks a user from a
	channel in which they were the first to enter (for example, a user
	without privileges entering a channel with the RESTRICTED setting
	active, or a user on the channel's autokick list).  In this case,
	ChanServ joins the channel for a short period of time to prevent
	the user from joining again immediately after they've been kicked.
	If you are using the Bahamut or Unreal IRC servers, this will
	result in a message like the above; it can be safely ignored.


C.7. How can I make Services send replies using PRIVMSG (/msg) instead of
     NOTICE?

	You can't.  RFC 1459 (the IRC protocol definition) requires that
	all automated clients send all replies using NOTICE rather than
	PRIVMSG, and Services follows that requirement.  If you want to
	change how Services replies appear in your IRC client, change your
	client's settings.

C.8. Can I make ChanServ send channel modes all at once instead of one at
     a time?

	Yes; enable the MergeChannelModes directive in services.conf.
	(Note that this has minor security implications; be sure to read
	the comments in the example configuration file.)

C.9. I'm using Unreal, and Services keeps removing any G-lines placed with
     /gline.  How can I make it stop?

	You can't.  Use the OperServ AKILL command to set network-wide user
	bans.

---------------------------------------------------------------------------

NickServ features:
==================

D.1. When I link nicks, the URL and E-mail fields aren't copied.

	This is designed behavior (though it may be changed in a future
	version).


D.2. Some people get nick collided when their nick is changed to Guest###.

	Make sure you have Guest* (or whatever prefix you specified in
	services.conf) listed in a Q:line in the ircd.conf for ALL of your
	servers, for example:

	    Q::Reserved for Services:Guest*

	This prevents people from using Guest### nicks and colliding
	people who get their nicks changed.  Note that some IRC servers
	will generate messages whenever someone gets their nick changed
	to Guest### by Services and a configuration line like the above is
	used; you may want to modify your IRC client script so it doesn't
	display the messages (or change the IRC server itself so it doesn't
	generate them).

---------------------------------------------------------------------------

ChanServ features:
==================

E.1. Services ignored the SET SUCCESSOR setting and deleted a channel when
     the founder expired.

	Normally, this is because the successor had too many channels
	registered; in this case, you will see an entry in the log file
	like the following:

	[date] Successor (SuccessorNick) of channel #somechannel owns too
	       many channels, deleting channel #somechannel

	If you don't get a message like this or you can verify that the
	successor wasn't running into the channel limit, please report it
	using the bug-reporting procedure below (question Z.3).

E.2. When ChanServ sets the topic for a channel, it always appends
     "(nickname)" to the end.  How do I make it not do that?

	This has nothing to do with Services, and is a feature of the IRC
	server itself which occurs when Services sets the topic on a
	channel.  The "(nickname)" is not actually included in the topic,
	and the second and later users to join the channel will not see it.
	There is no way to disable it for the first user, unless you modify
	the IRC server itself.

---------------------------------------------------------------------------

OperServ features:
==================

F.1. Using the OperServ JUPE command results in server messages like
     "Server juped.server introduced by non-hub server services.my.net".

	In all irc2.x-derived IRC servers (and possibly others), every
	server on the network must have an H: line for Services in the
	ircd.conf file, which looks something like:

	H:*::services.whatever.net


F.2. I can't use the ADMIN command to add Services admins--it tells me
     "Permission denied."

	Did you define yourself as the Services root?  You need to insert
	your nickname in the ServicesRoot directive in services.conf.


F.3. How can I set up multiple Services roots?

	You can't.  However, you can allow Services admins to obtain
	Services root privilege by setting a password with the OperServ
	SET SUPASS command; Services admins can then use the SU command to
	obtain Services root privilege.


F.4. When I add an AKILL, the users matching it don't get killed.

	1) Did you include a nick in the mask?  If you did, DON'T.
	   Autokill masks must not include nicks; Services will consider
	   *!*@host.name to be "a username containing !", not "any nick and
	   any username".  Current versions of Services will prevent you
	   from adding autokills which contain a "!".

	2) Services does not kill users when an autokill is added; it only
	   kills them when they next connect.  This is designed behavior,
	   intended to reduce the possibility of a mistyped autokill
	   getting the wrong users.  (Suppose you typed "AKILL ADD *@*" and
	   then accidentally hit Return before finishing the host mask...)


F.5. Services reports (via /stats u or /msg OperServ STATS) a different
     number of users online than I get from doing /lusers.

	Services doesn't count its own pseudo-clients (NickServ, ChanServ,
	etc.) in its user count, so Services will normally report a number
	nine lower than /lusers.  This number will vary if you have
	disabled any of the pseudo-clients (StatServ, DevNull, IrcIIHelp),
	and will also change as nickname enforcers are introduced and
	removed.

	If you have a very large and/or busy network, there may be an
	additional offset, either positive or negative, caused by lag
	(1) between users signing on/off and Services recognizing them, or
	(2) between Services killing a user and the servers receiving the
	kill.  On a network with under 500 simultaneous clients, this
	difference should typically not be more than one at any time, but
	it can increase quickly as the network grows in size.  (If the
	difference is abnormally large, see question C.2 for ways to speed
	Services up.)


F.6. Services killed a user it thought was cloning when the user really
     wasn't.  Or something else went wrong with clone killing.

	Comment out KillClones in services.conf.  Better yet, remove it
	entirely so you forget it exists.  _Don't_ complain to me, or
	you'll get flamed, probably in public.

	Note that you can now use session limiting to achieve similar
	results with better precision.  To repeat: DO NOT USE the
	KillClones directive.  It will be removed in the next version
	of Services.


F.7. Trying to use OperServ gives me "Access denied", but my nick is in the
     ServicesRoot directive and is registered, and I've identified for my
     nick.

	You need to be opered (i.e. user mode +o from using /oper; this is
	different from channel operator mode!) to access OperServ.


F.8. I used the RAW command to do something, and then Services stopped
     working!

	To quote from the help for the RAW command:

	    "This command has a very limited range of uses, and can
	     wreak havoc on a network or cause Services to crash if
	     used improperly.  DO NOT USE THIS COMMAND unless you are
	     absolutely certain you know what you are doing!"

	In particular, Services does _not_ process any messages sent with
	the RAW command, so if you (for example) use KILL to kill a user,
	Services will think the user is still online, and if they connect
	to the network again Services may well crash, or at least fail to
	recognize the new user.

	To summarize:  DO NOT USE the RAW command under any circumstances.

F.9. On Unreal, every time I use the /gline command, Services cancels the
     G:line.

	This is designed behavior.  Use the OperServ AKILL command instead
	of the /gline command.

---------------------------------------------------------------------------

Bug reporting and feature requests:
===================================

Z.1. Services doesn't speak my language!

	If you would like to supply a new language module for Services,
	take a look at lang/en_us.l, which is the language module for
	English, as well as the comments at the top of lang/langcomp.c,
	which describe the language module file format.  If/when you have
	completed a module for your language, E-mail it to me
	(achurch@achurch.org) for inclusion in Services.  However--warning,
	legal stuff follows--by sending me a language module for inclusion
	in Services, you agree to waive all copyright and other rights to
	that file and the text it contains, and you agree and state that no
	one else (such as your employer) has any claims of copyright or any
	other rights to said file and text.  (I will give credit, of
	course, but the copyright remains mine.  If you are not sure
	whether your employer might have rights to your translation,
	consult with your employer.)  Also, it would be very helpful if you
	would be willing to continue updating the module as changes are
	made to the base English module.

	If any British/Canadian English speakers want to make another
	version of the English language file which seems more natural to
	them, I'll take that too. (^:


Z.2. I selected a language other than English, but sometimes Services sends
     responses in English instead.

	Some language files are not complete--in other words, they don't
	have a translation of every message Services uses, but only some of
	them.  In this case, the missing messages will be displayed in
	English.  You can either wait for the primary translator to provide
	me with a translation, or do the translation yourself and send me
	the messages translated into your language (along with the original
	English messages so I know what they mean!).


Z.3. I've found a bug that's not mentioned here or in the README or
     KnownBugs files.  What should I do?

	Send a report of the bug with as many details as possible to
	achurch@achurch.org.  Even if something seems obvious to you, like
	what you think Services should be doing that it isn't, mention it
	anyway, because what seems obvious to you may not be obvious to me.
	Include in any case a copy of or excerpt from the Services log
	file, usually "services.log" in the Services data directory,
	  **** generated with the "-debug" command-line option, ****
	which includes a demonstration of the bug.  (This is important!)
	If the bug occurs in response to something you do (like sending a
	ChanServ command), also send the sequence of steps necessary to
	reproduce the bug, preferably starting with nickname or channel
	registration if NickServ or ChanServ is involved, and make sure the
	corresponding part of the log file is included.


Z.4. Your Services program doesn't do XYZ like DALnet Services.  What's
     wrong?

	Nothing is wrong, except your expectations.  Services is a
	completely different program from that used on DALnet; they are
	similar in concept only.


Z.5. I've got a great new idea for Services.  Do you want it?

	I'm always interested in hearing new ideas.  HOWEVER, I have very
	specific plans for what to include and not to include in Services.
	As a rule, I don't add anything that can be equivalently done by
	other means, or that I don't consider useful; see below for
	examples of things I don't plan to add.  If you have added
	something to Services you think would be useful to include in the
	standard distribution, feel free to send a context or unified diff
	along with (but not instead of!) your description.  If I choose not
	to include it, you're always free to keep and/or distribute the
	patch yourself.

	My general intent is for Services to provide as much functionality
	as possible--while staying as lean as possible (as opposed to, say,
	recent versions of Microsoft Word, which in my opinion provide so
	much functionality you can't do anything).  So features which are
	arguably beneficial will tend to be added, while features of
	limited or no benefit or which can be equally provided by something
	else already in use will tend to be passed over.


Z.6. Examples of features I have been asked about and why I won't add them--
     so don't ask about them:

	- An option to make ChanServ stay in some/all registered channels:
	  I see absolutely no necessity for this feature, since (1)
	  Services' channel privilege and information functions will
	  operate whether or not ChanServ (or any users at all) are in the
	  channel, and (2) if someone _really_ wants to keep a channel
	  open for some reason, they can use a standard bot.  Furthermore,
	  having ChanServ stay in channels will dramatically increase the
	  amount of traffic Services has to handle, which will in turn
	  reduce the rate at which Services can respond to requests.

	  This has also been discussed to death on the mailing list, the
	  archives of which can be found at the address below, so please
	  don't ask for it to be reconsidered.

	  Mailing list archive:
	  	http://www.ircservices.za.net/listarchive/maillist.html

	- A "current time" field in NickServ and ChanServ INFO displays:
	  Most people have clocks of some sort either on their computer
	  screens or on their walls (or both), and all IRC servers, as well
	  as Services, have a command to return the server's current time.
	  Thus a current-time field in INFO displays would simply take up
	  extra space for no reason.


Z.7. I submitted a bug report / feature request and it got fixed / added,
     but I didn't get credit in the Changes file!

	You may have reported it after it was already fixed or added.  In
	general, the Changes file lists the first person to submit the bug
	report or feature request, except when that person is one of the
	primary Services developers or a lot of people all report the same
	problem or request, in which case no individual credit is given.
	Mistakes do happen, though; if you really think you should be given
	credit for something, or if you find yourself being given credit
	for something that wasn't yours, please send E-mail.
