reference.conf

/*
 * Bahamut IRCd, doc/reference.conf
 *
 * Originally written by Trevor Talbot (Quension) in April 2004.
 * 
 * The configuration format consists of blocks, each containing name-value
 * pairs, tags, or string data.  It is designed to be easily readable by
 * both human and ircd.
 * 
 * A block consists of a block name, an opening '{' brace, statements, a
 * closing '}' brace, and a ';' semicolon.  A statement consists of a
 * name, possibly followed by a value, and ending with a semicolon.
 * Strings that contain special characters or whitespace can be surrounded
 * by '"' double quotes.  All elements of the configuration are separated
 * by whitespace, and can be packed on one line, or broken up over several
 * lines.
 *
 */

# Comments are supported in three forms:
    /* C style
       multi-line */
    # shell style single-line
    // C++ style single-line

/*
 * A sample block:
 * 
 *     block {
 *         name value;            # A statement with a name value
 *         name 123;              # A statement with a number value
 *         name "hello world";    # A statement with a string value
 *         tag;                   # A simple tag
 *         "will code for food";  # A simple string
 *     };
 * 
 * The parser also understands a special include directive outside of a
 * block context:
 * 
 *     include path/to/file.conf;
 */


###########################################################################
# Global [REQUIRED]
# The Global block defines information about the server itself.
# This block is required for the server to start.
# 
# Old conf format equivalents:
#     M:name::info
#     X:dpass:rpass

global {
    // required tokens
    name    not.configured;     # The IRC name of the server
    info    "located on earth"; # A short info line

    // optional tokens
    dpass   secret;             # Password for DIE command
    rpass   secret;             # Password for RESTART command

    // the optional Admin block may also be specified here
};

# The DIE and RESTART commands can optionally require passwords to be
# supplied, to help prevent accidents.  If the dpass and rpass tokens are
# not specified, no passwords are needed.
# 
# The Admin block may be nested here.  (This is currently a purely
# organizational/astetic option.  This will probably change in future
# releases.  -epi)
# 
# The server name may only be changed by a server restart.  The info line
# can be changed on rehash, but will not propagate to other linked servers.
# 
# There must be exactly one Global block.
###########################################################################


###########################################################################
# Admin [SUGGESTED]
# The Admin block defines up to 3 information lines for the ADMIN command.
# It may also exist inside the Global block.
# 
# Old conf format equivalents:
#     A:line 1:line 2:line 3

admin {
    // optional tokens
    "An unconfigured server";   # Info line #1
    "An unknown administrator"; # Info line #2
    "email@somewhere.earth";    # Info line #3
};

# Not all lines are required.  There may be only one Admin block.
###########################################################################


###########################################################################
# Options [OPTIONAL]
# The Options block configures various options for the server itself.
# This block is recommended for networks other than DALnet.
# 
# Old conf format equivalents:
#     T:wgmonhost:wgmonurl

options {
    // optional tokens
    network_name    unconfigured;   # Name of the network
    services_name   services.name;  # IRC name of services server
    stats_name      stats.name;     # IRC name of stats server
    staff_address   staff.net;      # Opermask hostname
    nshelpurl       "http://foo";   # URL for nick registration help
    spamfilterurl   "http://foo";   # URL for spamfilter help
    wgmonhost       wgmon.host;     # Wingate monitor scan host
    wgmonurl        "http://foo";   # URL for wingate monitor info
    network_kline   "kline@net";    # Contact email for network bans
    local_kline     "kline@server"; # Contact email for server bans
    servtype        client;         # Set server type:
                                    #     CLIENT, HUB, SERVICESHUB
    maxchannels     10;             # Max chans user can join
    ts_max_delta    300;            # Maximum timestamp delta
    ts_warn_delta   30;             # Warn for TS deltas larger than this
    local_clones    1:15;           # Default maximum local IP:site clones
    global_clones   3:30;           # Default maximum global IP:site clones
    crypt_oper_pass;                # Encrypted passwords in Oper blocks
    short_motd;                     # Use ircd.smotd
    show_links;                     # Show real LINKS output
    allow_split_ops;                # Op in empty channels while unlinked
    allow_remote_rehash;            # Accept rehash sent from remote server
};

# The services and stats IRC server names are used for the shortform
# commands, which are transformed into targeted name@server messages for
# security.  The services server name is used by SERVICES, IDENTIFY,
# NICKSERV, CHANSERV, MEMOSERV, ROOTSERV, NS, CS, MS, and RS.  The stats
# server name is used by OPERSERV, STATSERV, HELPSERV, OS, SS, and HS.
# >> defaults: services.dal.net, stats.dal.net
# 
# The staff_address token is used for operator hostmasking, as described
# in the Allow block documentation.
# >> default: staff.dalnet
# 
# The nshelpurl token is used to supply a URL for nick registration help.
# It is sent to clients in the rejection numeric when they encounter a +R
# channel and are not registered.
# >> default: http://docs.dal.net/docs/nsemail.html
# 
# The maxchannels token limits the number of channels a user may join at
# one time.  The limit for server operators is 3x this one.
# >> default: 10
# 
# The server type changes some behavior to be appropriate to the role.
# CLIENT servers can only link to one other server (their uplink hub).
# HUB servers link several servers together, but are not intended to hold
# general users.
# >> default: CLIENT
# 
# The server is capable of sending a set of notices to users on connect,
# providing some information about a proxy bot that scans them.  The
# wgmonhost token is the host the bot will be connecting from (for users
# with firewalls or other connection monitoring), and wgmonurl is a web
# page containing additional information about the bot.  If neither token
# is specified, the notices will not be sent.
# 
# Proper clock synchronization is required among connected servers.  This
# requirement can be relaxed by using the ts_warn_delta and ts_max_delta
# tokens.  The TS delta is the difference (in seconds) between the clocks
# of this server and the one it is linked to.  These options should only
# be used as a last resort; the correct fix for TS delta problems is to
# synchronize the clocks on both server computers, such as with the ntpdate
# tool.  Unsynchronized clocks may cause unpredictable network problems.
# >> defaults: 15, 120
# 
# The local_clones and global_clones tokens control the maximum number of
# connections the server will allow from the same place by default.  The
# first number refers connections from the same IP (10.0.0.5).  This number
# may optionally be followed by a colon ':' and a second number, which
# refers to connections from the same site (10.0.0.*).  The local_clones
# token sets the default limits for connections on this server only, and
# may be overridden by the maxclones token in a Class block.  The
# global_clones token sets the default limits for connections as seen on
# the entire network, and may be overridden by network services.
# >> defaults: 10:60, 25:150
# 
# The crypt_oper_pass token configures the server to use hashed passwords
# in the Oper blocks, to avoid password discovery by someone reading the
# conf file.  If this token is specified, passwords in the Oper blocks
# must be generated by the tools/mkpasswd utility.
# 
# The short_motd token enables use of the ircd.smotd file, which is sent
# to clients on connect instead of ircd.motd.  The MOTD command still sends
# the contents of ircd.motd as normal.  This option is intended to reduce
# traffic on connect, but still convince users to read the full motd when
# appropriate.
# 
# The show_links token causes the LINKS command to display real server
# links (though Super servers are still hidden).  If this token is not
# specified, LINKS will display the list given to it by services.
# 
# The allow_split_ops token causes the server to always give chanop status
# to users who join empty channels, even when no other servers are linked.
# Normally op status will not be given when this server is alone, to help
# prevent channel abuse during netsplits.  This token should be used if
# your server is not part of a network.  Opers are always given op status
# in empty channels regardless of this setting.
# 
# All of these tokens are optional, and can be specified at different times
# in multiple Options blocks.  If a token is specified twice, the second
# value overrides the first.
###########################################################################


###########################################################################
# Port [REQUIRED]
# The Port blocks define where the server will accept connections.  At
# least one Port block is required to start.
# 
# Old conf format equivalents:
#     M::bind::port
#     P:ipmask:bind::port

port {
    // required tokens
    port    6667;       # Port to listen on

    // optional tokens
    bind    127.0.0.1;  # IP address to listen on
    ipmask  127.0.*.*;  # Mask to accept connections from
    flags   S;		# Allow SSL connections on this port
};

# If a bind address is not specified, the server listens on all available
# interfaces.
#
# Flags available inside port blocks:
#	S  - allow SSL connections on this port
#	n  - do not perform DNS lookups on incoming connections on this port
#	i  - do not perform ident checks on incoming connections on this port
# 
# The ipmask token is used to limit the port to connections from the
# specified IP mask.  Only a simple mask is supported, consisting of a *
# where one component of the address is (e.g. "192.168.*.*").
# 
# There may be multiple Port blocks.
###########################################################################


###########################################################################
# Class [RECOMMENDED]
# The Class blocks define the connection classes used by the Allow, Oper,
# and Connect blocks.  While the server will start without a Class block,
# it will not be usable.
# 
# Old conf format equivalents:
#     Y:name:pingfreq::maxusers:maxsendq            (for clients)
#     Y:name:pingfreq:connfreq:maxlinks:maxsendq    (for servers)

class {
    // required tokens
    name        users;      # Name of the class
    pingfreq    90;         # PING idle connection every N seconds
    maxsendq    100000;     # Send buffer limit

    // optional, for Allow classes only:
    maxusers    100;        # Maximum number of clients
    maxclones   2:20;       # Maximum IP:site clones
    maxrecvq    2560;       # client excess flood threshold

    // optional, for Connect classes only:
    connfreq    300;        # Try autoconnect every N seconds
    maxlinks    1;          # Autoconnect if less than N links in class
};

# Idle connections are polled with the PING command every pingfreq seconds.
# 
# The maxsendq token controls the size of the internal send buffer, used
# when a connection cannot accept large amounts of data at once.  Certain
# server commands emit such large amounts of data.  As an example metric,
# a 100KB user send queue can support a WHO <channel> query for a channel
# with approximately 700 users.  Large amounts of data are also generated
# when two servers link and synchronize network state.  If the send queue
# limit is exceeded, the connection is terminated.
# 
# For classes used in the Allow blocks, the maxusers token limits the
# number of clients that may exist in this class.  This is the most common
# general user limit for the server.  If this limit is reached, additional
# clients will be rejected with a "server busy" message.  This token must
# not be specified for classes used in the Connect blocks.
# 
# For classes used in the Allow blocks, the maxclones token limits the
# number of clients that may connect from the same place in this class.
# The first number refers to connections from the same IP (10.0.0.5); it
# may be optionally followed by a colon ':' and a second number, which
# refers to connections from the same site (10.0.0.*).  If this limit is
# reached, clients will be rejected with a "too many connections from your
# host/site" message.  Limits defined here override the defaults as
# configured in the Options block.  If a site limit is not supplied here,
# clients in this class will effectively have no site limit; the default
# limit will not be used.  This token must not be specified for classes
# used in the Connect blocks.
# 
# For classes used in the Connect blocks, the connfreq token specifies the
# frequency at which autoconnections are tried.  This token works together
# with maxlinks, which specifies the maximum number of servers in this
# class to autoconnect to.  For an autoconnection to take place, the
# Connect block must have a valid port token, and there must be less than
# maxlinks connected servers in this class.  The connfreq and maxlinks
# tokens must not be specified for classes used in the Allow or Oper
# blocks.
# 
# A "default" class is created internally using definitions in config.h.
# This class is used when no other class is specified, but its settings are
# not useful for most situations.  Custom classes are strongly suggested.
# 
# There may be multiple Class blocks; at least one is recommended.
###########################################################################


###########################################################################
# Allow [RECOMMENDED]
# The Allow blocks define the hosts connections are allowed from, and
# places them into classes.  While the server will start without an Allow
# block, it will not be usable.
# 
# Old conf format equivalents:
#     I:ipmask:passwd:host:port:class

allow {
    // required tokens
    host        *;          # Resolved host mask (optional if using ipmask)
    ipmask      *;          # Unresolved IP mask (optional if using host)
    
    // optional tokens
    port        6667;       # Apply block to this port only
    passwd      secret;     # Require password for connection
    flags       mCFT;       # Special flags for this connection
    class       users;      # Place connections in this class
};

# The server uses a default-deny policy for incoming connections; at least
# one Allow block must be supplied if you wish to use your server.
# 
# The host and ipmask tokens specify which connections this block matches.
# The server always performs DNS and ident lookups for connections.  If DNS
# cannot find a hostname, the IP is used instead.  If ident cannot get a
# valid response, "unknown" is used during this stage.  The client's
# resolved hostname, IP address, ident reply, and username (from the USER
# line) are used according to the results of the matches described below.
# 
# The host token attempts to match first against the resolved hostname if
# available, then against the IP address.  To include the connection's
# ident response in the match, use a mask in the form "ident@host".  If a
# client matches this token, it appears on IRC using its resolved hostname.
# 
# The ipmask token attempts to match against the IP address only.  To
# include the connection's ident response in the match, use a mask in the
# form "ident@host".  If a client matches this token, it appears on IRC
# using its IP address, even if its hostname was resolved.
# 
# If the matching mask used ident ("ident@host" instead of "host"), and no
# ident response was received from the client, it appears on IRC with its
# username prefixed with '~'.  If the matching mask used only the "host"
# form, the client's username is not prefixed.  If a valid ident response
# was received, it is always used (without prefix), regardless of the mask
# form.
# 
# Only one of the host and ipmask tokens is needed; if both are used, host
# is matched first.  For typical configurations, using only the host token
# with a "*@host" or "ident@host" mask is recommended.
# 
# Examples:
#     // client with username "user", ident "ident", hostname "name"
#     host ident@*;     # appears as ident@name
#     ipmask *;         # appears as ident@10.0.0.1
# 
#     // same client without ident response
#     host *;           # appears as user@name
#     host *@*;         # appears as ~user@name
#     ipmask unknown@*; # appears as ~user@10.0.0.1
# 
# The port token limits this block to match connections to the specified
# port only.
# 
# The passwd token requires that matching connections supply a password to
# use the server.  Clients can send a password string in multiple forms,
# depending on which passwords need to be used.  The basic format is:
# 
#     [passwd][:][opername:operpass][:][nickpass]
# 
# If the Allow block requires a password, it must be supplied at the front
# of the string.  If operator hostmasking is enabled (via the flags token
# described below), the client can mask itself by supplying a "name:passwd"
# string as defined in an Oper block.  When masked, a client appears on IRC
# using the Oper block name for its ident, and the Options block
# staff_address for its hostname.  Any remaining passwords are sent to
# NickServ in an SIDENTIFY command.  All password components must be
# separated from each other by a ':' colon.
# 
# Using the examples in this file, a client could connect with the password
# string "secret:johndoe:secret" and be masked as johndoe@staff.net.
#
# The WEBIRC command identifies trusted clients, and permits the real
# hostname of a webirc client be used instead of the hostname of the
# webirc gateway they connected through. This can be used to prevent users
# from having ircip1.mibbit.com as their hostname, for example.
#
# Trusted clients are added to the ircd.conf by adding special allow
# blocks that match ident@host (if an identd response was received), or
# webirc@host (if not), and that use a password of the form:
# webirc.<password>
#
# For example:
#
# allow { ipmask webirc@127.0.0.1; passwd webirc.mypass; class users; };
#
# will allow the command to be used from a non-identd client connecting
# from 127.0.0.1 if they use the password mypass in the WEBIRC command.
#
# The flags token allows special behavior to be assigned to this
# connection, using a set of single-letter options.  The available flags
# are:
# 
#     m  Enable operator hostmasking
#     C  Bypass clone limiting
#     F  Force umode +F to bypass message flood checks
#     T  Disable rapid (re)connection throttling
# 
# When operator hostmasking is enabled, a matching client can connect using
# a special password to be masked, as described for the passwd token above.
# 
# Normally all clients are subjected to a clone limit check when they
# connect, as configured in the Options and Class blocks.  The C flag skips
# this check for matching clients, allowing them to have an unrestricted
# number of connections.
# 
# The F flag forces matching clients to always have usermode +F, to avoid
# various message flood checks.  This flag is intended for special bots and
# should not be used for server operators; opers can make use of the F
# access flag as described in the Oper block documentation.
# 
# By default, the server throttles rapid (re)connections from a single IP
# address, to help reduce abuse and load.  The T flag disables this
# mechanism for matching clients.  To qualify, a client must send valid
# NICK and USER messages to register the connection, and stay connected
# long enough to complete the ident and DNS lookups.  However, a correct
# password is not required.
#
# The class token specifies the connection Class to place matching
# connections in.  If not specified, the default class is used; see the
# Class block description for details.
# 
# There may be multiple Allow blocks; they are matched in the order they
# appear.
###########################################################################


###########################################################################
# Oper [SUGGESTED]
# The Oper blocks define server operators.  One or more of these blocks
# is recommended if you intend to maintain your server.
# 
# Old conf format equivalents:
#     O:host:passwd:name:access:class

oper {
    // required tokens
    name    johndoe;        # Account name
    passwd  secret;         # Account password (optionally encrypted)
    host    ident@hostmask; # Restrict access to this mask
    host    *@172.16.4.2;   # Up to 32 masks can be specified here
    access  *Aa;            # Access flags

    // optional tokens
    class   opers;          # Place authenticated client in this class
};

# The name and passwd tokens match the parameters of the OPER command.  If
# the crypt_oper_pass token is specified in the Options block, the passwd
# string must be generated by the tools/mkpasswd utility.  The plaintext
# password is still used in the OPER command.
# 
# To authenticate as an operator, a client must match one of the host
# tokens specified in "user@host" mask form.  There can be up to 32 host
# tokens.  The host part is matched against both resolved hostname and IP
# address.
# 
# The access token specifies what access an operator has, using a set of
# single-letter flags.  The available flags are:
# 
#     *  Includes all flags
# 
#     O  Network operator, includes these flags:
#        C  Can route other servers
#        K  Can kill clients on other servers
#        N  Can send global notices
#        and all flags included by 'o' (server operator)
# 
#     a  Can use umode +a (services administrator)
# 
#     Using any of the flags above will set umode +o (global operator).
#     All other flags set umode +O (local operator) by default.
# 
#     o  Server operator, includes these flags:
#        r  Can use REHASH
#        h  Can use GLOBOPS
#        w  Can use WALLOPS
#        l  Can use LOCOPS
#        b  Can use KLINE
#        B  Can use UNKLINE
#        c  Can route this server
#        k  Can kill clients on this server
#        n  Can send server notices
#        u  Can use umode +c (see client connection notices)
#        f  Can use umode +f (see flood notices)
#        W  Can use umode +b (CHATOPS)
#        d  Can use umode +d (debug)
#        y  Can use umode +y (see /stats, /info, /admin, /trace and /motd requests)
# 
#     D  Can use DIE
#     R  Can use RESTART
#     A  Can use umode +A (server administrator)
#     F  Can use umode +F (no flood limits)
# 
# The class token specifies the connection class the operator will be
# placed in.  If not specified, the default class is used; see the Class
# block description for details.
# 
# There may be multiple Oper blocks.
###########################################################################


###########################################################################
# Connect [OPTIONAL]
# The Connect blocks define links to other servers.
# 
# Old conf format equivalents:
#     C:host:cpasswd:name:port:class:bind
#     N:host:apasswd:name:flags:class
#     H:*::name

connect {
    // required tokens
    name    server.name;    # Other server's name
    host    server.host;    # Other server's host
    apasswd secret;         # Password to accept from other server
    cpasswd secret;         # Password to send to other server

    // optional tokens
    port    7000;           # Port to autoconnect to other server on
    bind    127.0.0.1;      # IP to connect from
    flags   ZEH;            # Flags for this link
    class   servers;        # Connection class to use for this link
};

# The name token specifies the IRC name of the other server, and the host
# token specifies its hostname or IP address.  Using an IP address is
# recommended.
# 
# The apasswd token defines the password this server will accept from the
# other one, and cpasswd defines the password to be sent.
# 
# The port token is used to enable autoconnection.  See the Class block
# description for details.
# 
# The bind token specifies the local IP to use when connecting to the
# other server.
# 
# The flags token defines various options for the connection:
# 
#     H   other server is a hub (allowed to link other servers)
#     Z   compress the link traffic
#     E   encrypt the link using RC4 with DH key exchange
# 
# The class token specifies the connection class to use for the server
# link.  If not specified, the default class is used; see the Class block
# description for details.
#
# The uflags token defines various options for U:lined server connections.
# These are typically used to prevent the services hub server from sending
# useless data to services that will just be ignored anyway.  It can help
# with the initial server sync burst on slow connections or older hardware.
#
#     s   Send shortform style services messages (:user NS :message)
#           instead of longform style messages
#           (:user PRIVMSG NickServ@services.host :message)
#     T   Don't send TOPICs on initial burst
#     a   Don't send AWAY messages ever
#     A   Don't send AWAY messages on initial burst
#     c   Don't send channel messages or notices
#     n   Don't send private notices
#     g   Don't send globops
#
# There may be multiple Connect blocks.
###########################################################################


###########################################################################
# Super [OPTIONAL]
# The Super block defines up to 24 super ("U-lined") servers, allowed to
# to do special network things.  Used for network services.
# 
# Old conf format equivalents:
#     U:name:*:*

super {
    "server1.name";     # Super server #1
    "server2.name";     # Super server #2
                        # ...
};

# Super servers are permitted to do things typical network services would
# want to do, such as apply network bans, manage channel modes, etc; the
# details are too numerous and complex to provide here.  This block is a
# simple list of up to 24 such servers, using their IRC names.
# 
# Super servers may be changed by a rehash, but will not take effect until
# all existing server links have been broken and reconnected.
# 
# There may be multiple Super blocks; all blocks are combined into one
# list.  There is a global limit of 24 super servers.
###########################################################################


###########################################################################
# Restrict [OPTIONAL]
# The Restrict blocks disallow nicknames, channelnames, or clients with
# specific GCOS (real name) fields.
# 
# Old conf format equivalents:
#     Q::reason:mask    (NICK, CHAN)
#     G::reason:mask    (GCOS)

restrict {
    // required tokens
    type    chan;           # Type of restriction: NICK, CHAN, GCOS
    mask    "#botworld";    # Disallowed mask
    
    // optional tokens
    reason  "evil bots";    # Reason for restriction
};

# Setting the type token to "nick" will create a nickname restriction,
# using the specified wildcard mask.  Restricted nicknames cannot be used
# by normal clients, but network operators may use them.
# 
# Setting the type token to "chan" will create a channel restriction,
# using the specified wildcard mask.  Restricted channels cannot be used
# by normal clients, but network operators may join them.
# 
# Setting the type token to "gcos" will create a real name field ban,
# using the specified wildcard mask.  Clients with a matching real name
# field will not be permitted to connect.
# 
# The reason token provides a single-line reason for the restriction, and
# is sent to clients along with the rejection notice.
# 
# There may be multiple Restrict blocks.
###########################################################################


###########################################################################
# Kill [OPTIONAL]
# The Kill blocks disallow connections from clients based on specific
# ident and host masks.
# 
# Old conf format equivalents:
#     K:host:reason:username    (mask was split)

kill {
    // required tokens
    mask    "*@192.168.0.0/24";     # Disallowed mask (wildcard or CIDR)
    
    // optional tokens
    reason  "tourists only!";       # Reason for ban
};

# Kill blocks are a flexible general client ban mechanism.  The mask token
# can be specified in several formats:
# 
#     mask *.bot.world;       # Wildcard hostname
#     mask user@*.isp;        # Wildcard user@hostname
#     mask 192.168.0.0/16;    # CIDR IP (all 4 parts needed)
#     mask user@10.4.2.2/30;  # CIDR user@IP
# 
# CIDR format is the most efficient, and should be used when possible.  The
# server will attempt to convert wildcard IP masks to CIDR form internally.
# 
# Clients that match a Kill block will be rejected from the server.
# Existing clients will be scanned for possible matches when new blocks are
# loaded during rehash.
# 
# There may be multiple Kill blocks.
###########################################################################


###########################################################################
# Modules [OPTIONAL]
# The Modules block configures dynamic module loading.
# 
# Old conf format equivalents:
#     modules.ini

modules {
    // optional tokens
    path        mods;   # Directory to look for modules in
    autoload    mod1;   # Module to load at startup
    autoload    mod2;   # Up to 128 modules can be specified here
};

# The path token specifies the directory to search for modules in, relative
# to the ircd directory.  There can only be one path, and the default is
# "modules".
# 
# The autoload token specifies the name of a module (without file
# extension) to load automatically at startup.  There can be up to 128
# autoload tokens.
# 
# There may be only one Modules block.
###########################################################################