Merge pull request #132 from retropc/lua_country

[irc/quakenet/newserv.git] / MODULES

newserv Modules
===============

This is a brief overview of the newserv modules.

core
----

This is not actually a module. Instead, this is the code of the "newserv" binary
which provides minimal support for loading modules.

authext, bans, chanindex, channel, irc, nick, server
----------------------------------------------------

These modules provide basic support for accounts, channels, nicks and server
connections. Virtually all other modules depend on at least some of these
modules.

localuser
---------

Implements functionality for creating local users that are "connected" to the
newserv instance.

control
-------

Spawns the control user for your newserv instance. The control user provides
an IRC-based interface for newserv commands, e.g. to manage loaded modules
and modify user accounts.

Other modules can register their own commands.

Configuration:

[control]
nick=N3
#ident=control
#hostname=your.hostname.here
#realname=newserv Control Service
#authname=C

control_commands
----------------

Provides commonly-used oper commands.

control_management
------------------

Provides user management commands.

auth
----

Supports sending AC tokens. You should only use this module if you don't have
some other form of authentication service on your network (such as Q). This
module lets opers use arbitrary account names and IDs.

chanfix
-------

Keeps track of channel ops and can be used to re-op opless channels. However,
since its chanfixing commands require oper, it should be paired with the request
module, which provides REQUESTOP for users and uses chanfix internally.

chanserv
--------

This is QuakeNet's channel service (Q). In order to load this module you will
need also need to load the pqsql module.

Configuration:

[chanserv]
nick=Q
user=TheQBot
host=some.host
realname=ChannelService
account=Q
secret=
ticketsecret=
createaccountsecret=

secret can be an arbitrary string, at most 128 characters long. If not set, Q
will generate a random one and not write it to the configuration.

ticketsecret can be an arbitrary string, at most 256 characters long and must
be set for ticket auth to work. Note that you must implement ticket auth
yourself if you wish to use it.

createaccountsecret must be a hex string of exact 128 characters (i.e. 64 bytes
of hex-encoded data).

pqsql
-----

Provides support for PostgreSQL database queries.

Configuration:

[pqsql]
host=127.0.0.1
port=5432
username=gunnar
password=changeme
#database=newserv

dbapi2
------

Implements database functionality used by some other modules. In addition to
loading the dbapi2 module you will also need to load one of the database
provider modules: sqlite-dbapi2 or pqsql-dbapi2

fakeusers
---------

Provides a way to spawn fake users.

glines
------

Implements gline commands and general gline functionality that is used by other
modules.

geoip
-----

Provides geo-location services for other modules.

Configuration:

[geoip]
#db=GeoIP.dat

helpmod2
--------

This is QuakeNet's G service. It is primarily used on official support channels.

invalidbans
-----------

This module automatically removes invalid IPv6 bans as these can desync channel
modes on snircd 1.3.4a.

jupe
----

Provides commands to set, list and remove jupes.

lua
---

Provides support for Lua scripts. For an example of a fairly complex script
have a look at the labspace repository at http://hg.quakenet.org/lua-labspace/

Configuration:

[lua]
#botnick=U
#scriptsuffix=.lua
scriptdir=./luascripts
script=labspace

Note: You will need to create the script directory in your newserv
installation directory (e.g. "luascripts" in this example) and symlink the
lua/lib directory into it.

newsearch
---------

Provides functionality to search for nicks and channels based on certain
criteria.

nickwatch
---------

Implements event-based nicksearch queries.

nterfacer
---------

Implements a protocol that allows external services to communicate with this
newserv instance.

You will need to implement your own client if you wish to use this.

Configuration:

[nterfacer]
#debug=0
# listening port
#port=2438
# Each individual permit/allowed client must have a hostname and password
hostname=127.0.0.1
password=changeme

miscreply
---------

Implements rping and various other status query commands.

Configuration:

[miscreply]
#admin1=Located at the Union Aerospace Corp. facility, Stroggos
#admin2=Network IRC Service
#admin3=No administrative info available

patrol
------

Implements functionality to spawn trojanscan swarm clones.

Configuration:

[patrol]
#minpoolhosts=5000

patricia, patricianick, patriciasearch
--------------------------------------

Implements finding nicks based on CIDR prefixes.

proxyscan
---------

Does on-connect proxy scans and glines open proxies.

Configuration:

[proxyscan]
# listen port
port=9999
# bind IP
ip=127.0.0.1
maxscans=200
rescaninterval=3600
nick=P
user=proxyscan
host=some.host
realname=Proxyscan

request
-------

This is QuakeNet's channel service request bot (R).

Configuration:

[request]
#nick=R
#user=request
#host=request.quakenet.org
#real=Service Request v0.23
#snick=S
#sserver=spamscan.quakenet.org
#qnick=Q
#qserver=cserve.quakenet.org
#auth=R
#authid=1780711
# Auth to S
#user=R
#password=bla

serverlist
----------

Implements the serverlist command which shows various information about
connected servers (including their network latency).

Configuration:

[serverlist]
q_server=CServe.quakenet.org
s_server=services2.uk.quakenet.org
service_re=^services\d*\..*$
hub_re=^hub\d*\..*$
not_client_re=^(testserv\d*\.).*$

settime
-------

Provides commands to set the network time.

splitlist
---------

Keeps track of servers that were lost during a netsplit. This module is used
by chanfix to determine when it shouldn't re-op users.

ticketauth
----------

Provides ticketauth, a way to authenticate to noperserv using a one-time
ticket. It works similar to the ticket auth in chanserv.

If you want to use ticketauth, you'll need to implement a method to issue
tickets using the shared secret yourself.

Configuration:

[ticketauth]
sharedsecret=

sharedsecret is an arbitrary string of at most 512 characters.

trojanscan
----------

Used to find and gline drones on the network.

Note that this module uses MySQL exclusively and in a blocking manner, so that
a hanging connection to the MySQL database can and will block all network I/O.
For this reason, you will probably want a newserv instance dedicated to running
trojanscan if you wish to run it.

Configuration:

[trojanscan]
nick=T
ident=trojanscan
hostname=trojanscan.quakenet.org
realname=Trojanscan v2.73
authname=T
# MySQL credentials
dbhost=localhost
dbport=3306
dbuser=moo
dbpass=changeme
db=moo
maxchans=750
cycletime=16000
parttime=2600
maxusers=20
minchansize=150

trusts
------

Implements connection limits. Supports the TRUST protocol which is used
by quakenet-iauthd to determine whether to allow users to connect to the
network.

You will need to load the trusts_master module on exactly one of your newserv
instances. All other instances should load the trusts_slave module in order
to receive replication updates from the trusts master:

[trusts]
master=1
#masterserver=trusts.services.netsplit.net # Only used if master=0

In most cases you will also want to load the trusts_management module on
your trusts master. This module provides commands to add, modify and delete
trusts.

If you want to enforce connection limits on your network you can use the
trusts_policy module:

[trusts_policy]
enforcepolicy_irc=1
enforcepolicy_auth=0
trustport=5776
server=gnb.netsplit.net,changeme
server=test.gnb.netsplit.net,changeme

You can use the QuakeNet IAuth daemon available at
https://hg.quakenet.org/iauthd/ to enforce connection limits using IAuth rather
than g:lines.

whowas, whowas_channels
-----------------------

Keeps track of historical user records. Used by the glines module to chase
nicks and by newsearch.

The whowas_channels module optionally keeps track of which channels users
were on.

Configuration:

[whowas]
maxentries=1000

xsb
---

Provides newserv<->newserv communication capabilities. Used by the trusts
modules to sync trusts between newserv instances.

Configuration:

[xsb]
servicemask=*.services.netsplit.net