Epona -- a set of IRC services for IRC networks =============================================== Epona is (c) 2000-2002, 2004-2007 PegSoft . Based on Services (c) 1996-1999 Andrew Church . This program is free but copyrighted software; see the file COPYING for details. Latest information about Epona may be found at http://www.epona.org/. TABLE OF CONTENTS ----------------- 1. Credits 2. Presentation 3. Installation 4. Command line options 5. Log levels 6. Modules 7. Messages translation 8. Reporting bugs 9. Contact and mailing list 1. CREDITS ---------- Epona is based on Andy Church's IRC Services version 4.3.3. The original credits: Mauritz Antunes -- Portuguese translation Jose R. Holzmann, Raul S. Villarreal -- Spanish translation Andrew Kempe -- news system -- Italian translation -- Turkish translation Andrew Kempe -- session limiting Epona credits: lara -- Main coding CafeiN -- Turkish translation Sylvain Cresto aka tost -- FreeBSD 5 patch Marcelo Conde Foscarini aka Bras -- Portuguese translation Alvaro Toledo aka POLLITO -- Spanish translation Guven Guzelbey aka MeShGuL -- Turkish translation Jordi Pujol -- Catalan translation Eva Dachs -- Catalan translation Toni Perez -- Catalan translation Sergios Karalis -- Greek translation PablinFRK -- Spanish translation Vincenzo Ingrosso -- Italian translation Phantomal -- German translation phrozen77 -- German translation PChaos -- German translation Contributed code to Epona in previous releases: Thomas J. Stensas aka ShadowMaster -- Ultimate 3.x support chemical -- German translation shine -- German translation Special thanks: `blah -- Made the rebirth of Epona possible. cab -- Idea testing. Epona is bundled with the following source code and libraries that it uses and were written by other people: * TinyXml by Lee Thomason and Yves Berquin 2. PRESENTATION --------------- Epona is a set of Services for IRC networks that allows users to manage their nicks and channels in a secure and efficient way, and administrators to manage their network with powerful tools. Currently available services are: * NickServ, a powerful nickname manager that users can use to protect themselves against nick stealing. Each user has its own nickname group, that allows her to register as many nicks as she needs while still being able to take profit of her privileges and to modify her nick configuration. NickServ also has an optional password retrieval feature. * ChanServ, a powerful channel manager that helps users to administer their channels in a totally customizable way. ChanServ has an internal list of privilegied users and banned users that controls accesses on a per-channel basis. It eliminates all takeover problems, because of its powerful op/unban/invite and even mass deop and mass kick functions. * MemoServ, an helpful companion that allows sending short messages to offline users, that they can then read when they come online later. * BotServ, an original service that allows users to get a permanent, friendly bot on their channels in an easy way. Each bot can be configured to monitor the channels against floods, repetitions, caps writing, swear, and take appropriate actions. It also can handle user-friendly commands (!op,!deop,!voice,!devoice,!kick,...), say a short greet message when an user joins a channel, and even "take over" ChanServ actions such as auto-opping users, saying the entry notice, and so on. This service can be disabled if you want to save some bandwidth. * OperServ, the IRCops' and IRC admins' black box, that allows them to manage the list of network bans (also known as AKILL (DALnet) or GLINE (Unreal)), to configure messages displayed to users when they log on, to set modes and to kick users from any channel, to send notices quickly to the entire network, and much more! Epona works with DreamForge and Bahamut IRCDs (and some of their forks). 3. INSTALLATION --------------- See the INSTALL file. 4. COMMAND-LINE OPTIONS ----------------------- Normally, Epona can be run simply by invoking the "epona" executable. Epona will then read the configuration file (defaults to epona.conf, can be overridden by using the -c command-line option), and connect to the specified uplink server. The following command-line options can be used to modify the behavior of Epona: -c, --conf=file Set a different main configuration file -d, --debug Enable debugging mode--more info sent to log (give option more times to increase debug level) --debuglevel=level Enable debugging mode, setting debug level to level -D, --define=name[=value] Set a configuration file variable (see epona.conf.dist for more information) -f, --foreground Do not go into background after startup; log messages will be written to terminal (as well as to the log file) -I, --include=path Adds an additional directory to the configuration file search path (see epona.conf.dist for more information) --iid Generate an interface identifier and exit (useful to module developers only ;) -h, --help Display help and exit -m, --module=name Load this module on startup (may be used multiple times). Modules loaded through this command-line parameter "take over" Epona, allowing it to do various tasks it wasn't supposed to do (see the dbexport, dbimport and dbremove modules, for example). The load-module configuration directive is ignored when this parameter is used. -n, --noexpire Expiration routines won't be run at all -r, --readonly Enable read-only mode--no changes to databases allowed -V, --version Display version information and exit Upon starting, Epona will parse its command-line parameters, read its configuration files, then (assuming the -f option is not given) detach itself and run in the background. If Epona encounters a problem loading its modules, retrieving data from databases or cannot connect to its uplink server, it will terminate immediately; otherwise, it will run until the connection is terminated (or a FATAL, STOP, or RESTART command is sent--see OperServ's help). In the case of an error, an appropriate error message will be logged. If Epona 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 Epona. 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 Epona 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 reproduce the problem. 5. LOG LEVELS ------------- a. Concept ---------- Epona uses log levels to allow administrators to determine what and how things get logged. In essence, log levels have simple, descriptive strings used as their name. Some names may contain one or more "::" characters. They delimit parts of the name as to form a hierarchy of derived log levels. For example, "Debug::Memory" log level is derived from the "Debug" log level. This hierarchy allows you to log groups of related messages easily. For example, if Epona is configured to log messages in the Debug::Memory log level, it won't log messages in the Debug::Conf log level, but if it was configured to log messages in the Debug log level, then both Debug::Memory and Debug::Conf messages would be logged. b. Existing log levels ---------------------- Here are the log levels defined by Epona and standard modules, along with their descriptions: * Debug -- Debug messages (most of them aren't logged unless the debug level is different than 0.) * Debug::Blacklist -- Hostname blacklist debug messages * Debug::Channel -- Channel records debug messages * Debug::Channel::List -- Channel list debug messages (debug level >= 3) * Debug::ChanServ -- ChanServ debug messages * Debug::Conf -- Configuration debug messages * Debug::Language -- Language file debug messages * Debug::MySQL -- mysql module debug messages * Debug::NetBan -- Network bans debug messages * Debug::NickServ -- NickServ debug messages * Debug::Program -- Program debug messages * Debug::Server -- Server records debug messages * Debug::SMTPCli -- smtp-cli module debug messages * Debug::Twilight -- twilight module debug messages * Debug::User -- User records debug messages * Debug::User::List -- User list debug messages (debug level >= 3) * Info -- Informational messages * Info::ChanServ -- ChanServ information * Info::ChanServ::List -- New and deleted ChanServ records * Info::ChanServ::Rights -- Channels rights and privileges * Info::ChanServ::Settings -- Modification of important channel settings (including passwords). * Info::DBExport -- dbexport module information * Info::DBImport -- dbimport module information * Info::DBRemove -- dbremove module information * Info::Input -- Messages received from the IRC network (services::log-input configuration directive) * Info::LegacyDB -- legacy module information * Info::MemoServ -- MemoServ information * Info::MySQL -- mysql module information. * Info::MySQL::Connection -- mysql module connection information. * Info::MySQL::Queries -- mysql module queries. * Info::MySQL::Warnings -- mysql module query warnings. * Info::NetBan -- Network bans information * Info::NickServ -- NickServ information * Info::NickServ::List -- New and deleted NickServ records * Info::NickServ::Rights -- Nickname access and identification * Info::NickServ::Settings -- Modification of important nickname settings (including passwords). * Info::OperServ -- OperServ information * Info::OperServ::List -- New and deleted OperServ records * Info::OperServ::Use -- OperServ commands used by IRC operators * Info::Output -- Messages sent to the IRC network (services::log-output configuration directive) * Info::Program -- Program information * Info::Twilight -- twilight module information. * Info::User -- User-related information * Info::User::Count -- New maximum user count messages (services::log-maxusers configuration directive) * Info::User::Ignore -- Ignored users * Info::User::Logging -- User connections/disconnections (services::log-users configuration directive) * Notice -- Noteworthy informational messages * Notice::ChanServ -- Noteworthy ChanServ information * Notice::ChanServ::Privileges -- Use of privileged ChanServ commands * Notice::Flow -- Program flow (start, restart, stop) information * Notice::Flow::Restart -- Program restart messages * Notice::Flow::Start -- Program start messages * Notice::Flow::Stop -- Program stop messages * Notice::Module -- Module loading/unloading information * Notice::NickServ -- Noteworthy NickServ information * Notice::NickServ::Privileges -- Use of privileged NickServ commands * Notice::OperServ -- Noteworthy OperServ information * Notice::OperServ::Settings -- Change of important settings (through the SET command) * Warning -- Warning messages * Warning::ChanServ -- ChanServ warnings * Warning::Conf -- Configuration warnings * Warning::Language -- Language file warnings * Warning::MySQL -- mysql module warnings * Warning::Program -- Program warnings * Error -- Error messages * Error::Blacklist -- Hostname blacklist errors * Error::BotServ -- BotServ errors * Error::BotServ::List -- BotServ record-related errors * Error::Channel -- Channel-related errors * Error::ChanServ -- ChanServ errors * Error::ChanServ::List -- ChanServ record-related errors * Error::ConfData -- confdata module errors * Error::Datafiles -- Data files errors * Error::Language -- Language file errors * Error::LegacyDB -- legacydb module errors * Error::Logfile -- logfile module errors * Error::MemoServ -- MemoServ errors * Error::MemoServ::List MemoServ record-related errors * Error::MySQL -- mysql module errors * Error::MySQL::Connection -- MySQL connection errors * Error::News -- News error * Error::NickServ -- NickServ errors * Error::NickServ::List -- NickServ record-related errors * Error::OperServ -- OperServ errors * Error::PIDfile -- PID file errors * Error::Sessions -- Session limitation errors * Error::SMTPCli -- smtp-cli module errors * Error::Twilight -- twilight module errors * Error::Twilight::DB -- Database read/write errors * Error::User -- User-related errors * Critical -- Critical error messages * Critical::Conf -- Configuration errors * Critical::DBRemove -- dbremove module critical errors * Critical::Logfile -- logfile module critical errors * Critical::MySQL -- mysql module critical errors * Critical::MySQL::Connection -- MySQL connection critical errors * Critical::Program -- Critical program errors * Critical::Program::Panic -- PANIC! errors * Critical::Twilight -- Twilight module critical errors * Critical::Twilight::DB -- Database read/write critical errors * Fatal -- Fatal error messages 6. MODULES ---------- a. Concept ---------- Epona uses a system that allows any developer to expand its functionality easily by writing pieces of code compiled as modules. Modules can be used: - to add features conveniently on an as-needed basis. Besides the modules provided with Epona, you can use those contributed by others or even write your own easily, without having to rewrite them at each new Epona release; - to give you more choice on how goals get achieved, through generic interfaces. For example, you may switch from traditional, file-based databases to MySQL databases or anything else you could think of by simply switching the module that is used by each service to store their data, without having to change the service or the database module code thanks to the generic interface. b. Log modules -------------- Log modules are used with the log subsystem to provide new ways to record log messages. The following are provided with Epona: (Modules marked with [*] need to be configured.) * logfile [*] Provides a log file manager, with support for multiple files and log rotation. It can use file compression modules to compress rotated log files. c. File compression modules --------------------------- File compression modules are used by other modules to compress files as they need. They are therefore only useful to module writers, even though some modules may let you choose which one to use when they need to compress files. The following are provided with Epona: * bz2file A compression module that compresses files in bzip2 format. (Requires bzlib to be installed on the system and detected by the configure script.) * gzfile A compression module that compresses files in gzip format. (Requires zlib to be installed on the system and detected by the configure script.) d. Database modules ------------------- Database modules provide a way for other modules to store their records permanently. The following are provided with Epona: (Modules marked with [*] need to be configured.) (Modules marked with [E] can export their data through the dbexport utility module; modules marked with [I] can import data through the dbimport utility module; modules marked with [R] can remove their databases through the dbremove utility module) * twilight [*][E][I][R] This module stores its data on disk in a custom binary format. It is the recommended choice if you don't need to access the data from an external program as it is fast and reliable and needs no special setup or maintenance. * mysql [*][E][I][R] This module stores its data in tables in a MySQL database. The records are updated in realtime in the table, and the records may be changed by an external program even during program execution. See the file doc/modules/mysql.txt for more information. e. Database conversion modules ------------------------------ Database conversion modules are database modules with limited functionality, in that all they do is exporting their databases in XML format when used in conjunction with the dbexport utility module. The generated files may then be imported using the dbimport module for use with any of the database modules. The following are provided with Epona: * legacydb This module exports databases generated by Epona 1.4.x. Since there is no database module that can load these old databases, you'll need this module to convert them and use them to their full extent. Note that it is assumed your old databases are named nick.db, chan.db, bot.db, oper.db, news.db and exception.db, which were the default names for the databases but could be changed in the configuration file. Since it is believed that the vast majority of users went with the default database names, configuration settings to use different names weren't added. f. Password modules ------------------- Password modules may be used to encrypt NickServ and ChanServ passwords. The following are provided with Epona: * md5 This module encrypts passwords using the MD5 algorithm. * sha1 This module encrypts passwords using the SHA1 algorithm. * legacydb This database module is a password module too. It encrypts the passwords using the MD5 algorithm with /weird/ (and possibly insecure) changes applied, like the password encryption of past Epona releases used to. It must therefore NOT be used for encoding new passwords; it'll be automatically loaded as necessary if some old records in your databases still use that encoding scheme. g. Mail transport modules ------------------------- Mail transport modules are used to deliver e-mails in different ways. (Modules marked with [*] need to be configured.) * smtp-cli [*] This module uses a direct connection to a SMTP relay to deliver e-mails. It is the recommended standard mail transport module, except for very small networks which don't have a lot of traffic going on (this is going to be fixed in Epona 1.6). * sendmail [*] This module uses the sendmail program to deliver e-mails. As it is not very efficient when Epona sends large volumes of mails, it is not recommended unless you know you won't use it too much. y. Miscellaneous modules ------------------------ (Modules marked with [*] need to be configured.) * confdata [*] This module stores the values of the configuration directives of all in a database using a database module. This database is for read-only purposes only; changes made by external programs are ignored, and it is recreated from scratch each time the configuration is (re)loaded. * mysql-cli This module provides MySQL connectivity to other modules. z. Utility modules ------------------ Utility modules are NOT meant to be loaded during normal operation; they do special tasks and exit Epona when they are done. These modules are generally loaded through the -m or --module command-line parameters. * dbexport Exports some or all data stored by a database module to XML files that can then be imported to another module by the dbimport module or processed by an external program. This module is controlled by the following command-line parameters: --source=name Specifies the name of the database module that must export its data --dir=dirname Specifies the directory where all XML files should be put --index=filename Specifies the name of the XML index file that will be created, for use by the dbimport module. Defaults to index.xml --db=name Specifies a database name to export. This parameter may be used multiple times. By default all databases will be exported. Usage example: $ mkdir xml-files $ ./epona -m dbexport --source=twilight --dir=xml-files * dbimport Imports some or all data stored in XML files that were generated through the dbexport module into a database module so that they can be used afterwards. This module is controlled by the following command-line parameters: --target=name Specifies the name of the database module that will import the data --dir=dirname Specifies the directory where all XML files reside --index=filename Specifies the name of the XML index file that will be used. Defaults to index.xml --db=name Specifies a database name to import. This parameter may be used multiple times. By default all databases will be imported. Usage example: $ ./epona -m dbimport --target=mysql --dir=xml-files * dbremove Properly removes a database managed by a database module. This module is controlled by the following command-line parameters: --target=name Specifies the name of the database module that must remove one or more of its databases --db=name Specifies a database name to remove. This parameter may be used multiple times. There must be at least one database to remove, unless --all is used. --all Asks for removal of all databases. Usage example: $ ./epona -m dbremove --target=mysql --db=operserv_stats 7. MESSAGES TRANSLATIONS ------------------------ Epona has a powerful option in NickServ allowing users to choose what language it must use when sending messages to users. Messages are stored in language files (located in the lang directory). Epona is currently provided with nine languages: Catalan, English, French, German, Greek, Italian, Portuguese, Spanish and Turkish. If you want to translate Epona messages in another language, follow the following instructions: * Copy the src/lang/en_us.l file to a meaningful name (for example, if you would like to translate messages in Russian, you would rename it to ru.l). * Edit the file with your favourite text editor. Read carefully the instructions given at the top of the file, and start translating the whole file. The file is big so make sure you have some coffee available. ;) * When this is done, you have two solutions: either patch Epona source code so they take in account the new language file (basically, you'll have to modify src/lang/Makefile.am, src/language.c and maybe src/services.h and use Automake to update the src/lang/Makefile.in), or send me the translated file so I can make the patch myself and send it back to you. When new major releases come out, you'll not have to retranslate the whole file; the Changes.lang file will help you to know which messages were added, modified or deleted. On that note, all the language files except English and French need to be completed ! If you feel like doing it, please do and send me the updated file (see below) ! Your help will be greatly appreciated. If you did a language file translation, and want to let others use it, please send it to epona@pegsoft.net (don't forget to mention clearly your (nick)name, your e-mail and the language name). You'll of course get full credit for it, and will be contacted again each time a new major release is approaching, so you'll have a chance (;)) to complete your work. 8. REPORTING BUGS ----------------- Go to http://bugs.epona.org/ and follow the instructions given on the front page. You may also post feature requests there. 9. CONTACT AND MAILING LIST --------------------------- * For general discussion about Epona, see the mailing lists at http://lists.epona.org/cgi-bin/mailman/listinfo/ * If you read the documentation carefully, and think the mailing lists would be of no use for you, feel free to send a mail to epona@pegsoft.net. Be as precise as possible when asking a question, because I can't guess things that are not mentionned.