some styling

[solanum.git] / doc / oper-guide / config.rst

Server config file format
=========================

General format
~~~~~~~~~~~~~~

The config file consists of a series of BIND-style blocks. Each block
consists of a series of values inside it which pertain to configuration
settings that apply to the given block.

Several values take lists of values and have defaults preset inside
them. Prefix a keyword with a tilde (~) to override the default and
disable it.

A line may also be a .include directive, which is of the form .include
"file" and causes file to be read in at that point, before the rest of
the current file is processed. Relative paths are first tried relative
to PREFIX and then relative to ETCPATH (normally PREFIX/etc).

Anything from a # to the end of a line is a comment. Blank lines are
ignored. C-style comments are also supported.

Specific blocks and directives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Not all configuration blocks and directives are listed here, only the
most common ones. More blocks and directives will be documented in later
revisions of this manual.

loadmodule directive
--------------------

loadmodule "
text
";
Loads a module into the IRCd. In charybdis 1.1, most modules are
automatically loaded in. In future versions, it is intended to remove
this behaviour as to allow for easy customization of the IRCd's
featureset.

serverinfo {} block
-------------------

serverinfo { name = "
text
"; sid = "
text
"; description = "
text
"; network\_name = "
text
"; hub =
boolean
; vhost = "
text
"; vhost6 = "
text
"; };
The serverinfo {} block defines the core operational parameters of the
IRC server.

name
    The name of the IRC server that you are configuring. This must
    contain at least one dot. It is not necessarily equal to any DNS
    name. This must be unique on the IRC network.

sid
    A unique ID which describes the server. This consists of one digit
    and two characters which can be digits or letters.

description
    A user-defined field of text which describes the IRC server. This
    information is used in /links and /whois requests. Geographical
    location information could be a useful use of this field, but most
    administrators put a witty saying inside it instead.

network\_name
    The name of the IRC network that this server will be a member of.
    This is used in the welcome message and NETWORK= in 005.

hub
    A boolean which defines whether or not this IRC server will be
    serving as a hub, i.e. have multiple servers connected to it.

vhost
    An optional text field which defines an IPv4 address from which
    to connect outward to other IRC servers.

vhost6
    An optional text field which defines an IPv6 address from which
    to connect outward to other IRC servers.

admin {} block
--------------

admin { name = "
text
"; description = "
text
"; email = "
text
"; };
This block provides the information which is returned by the ADMIN
command.

name
    The name of the administrator running this service.

description
    The description of the administrator's position in the network.

email
    A point of contact for the administrator, usually an e-mail address.

class {} block
--------------

class "
name
" { ping\_time =
duration
; number\_per\_ident =
number
; number\_per\_ip =
number
; number\_per\_ip\_global =
number
; cidr\_ipv4\_bitlen =
number
; cidr\_ipv6\_bitlen =
number
; number\_per\_cidr =
number
; max\_number =
number
; sendq =
size
; };
class "
name
" { ping\_time =
duration
; connectfreq =
duration
; max\_number =
number
; sendq =
size
; };
Class blocks define classes of connections for later use. The class name
is used to connect them to other blocks in the config file (auth{} and
connect{}). They must be defined before they are used.

Classes are used both for client and server connections, but most
variables are different.

ping\_time
    The amount of time between checking pings for clients, e.g.: 2
    minutes

number\_per\_ident
    The amount of clients which may be connected from a single identd
    username on a per-IP basis, globally. Unidented clients all count as
    the same username.

number\_per\_ip
    The amount of clients which may be connected from a single IP
    address.

number\_per\_ip\_global
    The amount of clients which may be connected globally from a single
    IP address.

cidr\_ipv4\_bitlen
    The netblock length to use with CIDR-based client limiting for IPv4
    users in this class (between 0 and 32).

cidr\_ipv6\_bitlen
    The netblock length to use with CIDR-based client limiting for IPv6
    users in this class (between 0 and 128).

number\_per\_cidr
    The amount of clients which may be connected from a single netblock.

    If this needs to differ between IPv4 and IPv6, make different
    classes for IPv4 and IPv6 users.

max\_number
    The maximum amount of clients which may use this class at any given
    time.

sendq
    The maximum size of the queue of data to be sent to a client before
    it is dropped.

ping\_time
    The amount of time between checking pings for servers, e.g.: 2
    minutes

connectfreq
    The amount of time between autoconnects. This must at least be one
    minute, as autoconnects are evaluated with that granularity.

max\_number
    The amount of servers to autoconnect to in this class. More
    precisely, no autoconnects are done if the number of servers in this
    class is greater than or equal max\_number

sendq
    The maximum size of the queue of data to be sent to a server before
    it is dropped.

auth {} block
-------------

auth { user = "
hostmask
"; password = "
text
"; spoof = "
text
"; flags =
list
; class = "
text
"; };
auth {} blocks allow client connections to the server, and set various
properties concerning those connections.

Auth blocks are evaluated from top to bottom in priority, so put special
blocks first.

user
    A hostmask (user@host) that the auth {} block applies to. It is
    matched against the hostname and IP address (using :: shortening for
    IPv6 and prepending a 0 if it starts with a colon) and can also use
    CIDR masks. You can have multiple user entries.

password
    An optional password to use for authenticating into this auth{}
    block. If the password is wrong the user will not be able to connect
    (will not fall back on another auth{} block).

spoof
    An optional fake hostname (or user@host) to apply to users
    authenticated to this auth{} block. In STATS i and TESTLINE, an
    equals sign (=) appears before the user@host and the spoof is shown.

flags
    A list of flags to apply to this auth{} block. They are listed
    below. Some of the flags appear as a special character,
    parenthesized in the list, before the user@host in STATS i and
    TESTLINE.

class
    A name of a class to put users matching this auth{} block into.

encrypted
    The password used has been encrypted.

spoof\_notice
    Causes the IRCd to send out a server notice when activating a spoof
    provided by this auth{} block.

exceed\_limit (>)
    Users in this auth{} block can exceed class-wide limitations.

dnsbl\_exempt ($)
    Users in this auth{} block are exempted from DNS blacklist checks.
    However, they will still be warned if they are listed.

kline\_exempt (^)
    Users in this auth{} block are exempted from DNS blacklists, k:lines
    and x:lines.

spambot\_exempt
    Users in this auth{} block are exempted from spambot checks.

shide\_exempt
    Users in this auth{} block are exempted from some serverhiding
    effects.

jupe\_exempt
    Users in this auth{} block do not trigger an alarm when joining
    juped channels.

resv\_exempt
    Users in this auth{} block may use reserved nicknames and channels.

.. note:: The initial nickname may still not be reserved.
          
flood\_exempt (\|) Users in this auth{} block may send arbitrary
    amounts of commands per time unit to the server. This does not
    exempt them from any other flood limits. You should use this
    setting with caution.

no\_tilde (-)
    Users in this auth{} block will not have a tilde added to their
    username if they do not run identd.

need\_ident (+)
    Users in this auth{} block must have identd, otherwise they will be
    rejected.

need\_ssl
    Users in this auth{} block must be connected via SSL/TLS, otherwise
    they will be rejected.

need\_sasl
    Users in this auth{} block must identify via SASL, otherwise they
    will be rejected.

exempt {} block
---------------

exempt { ip = "
ip
"; };
An exempt block specifies IP addresses which are exempt from D:lines and
throttling. Multiple addresses can be specified in one block. Clients
coming from these addresses can still be K/G/X:lined or banned by a DNS
blacklist unless they also have appropriate flags in their auth{} block.

ip
    The IP address or CIDR range to exempt.

privset {} block
----------------

privset { extends = "
name
"; privs =
list
; };
A privset (privilege set) block specifies a set of operator privileges.

extends
    An optional privset to inherit. The new privset will have all
    privileges that the given privset has.

privs
    Privileges to grant to this privset. These are described in the
    operator privileges section.

operator {} block
-----------------

operator "
name
" { user = "
hostmask
"; password = "
text
"; rsa\_public\_key\_file = "
text
"; umodes =
list
; snomask = "
text
"; flags =
list
; };
Operator blocks define who may use the OPER command to gain extended
privileges.

user
    A hostmask that users trying to use this operator {} block must
    match. This is checked against the original host and IP address;
    CIDR is also supported. So auth {} spoofs work in operator {}
    blocks; the real host behind them is not checked. Other kind of
    spoofs do not work in operator {} blocks; the real host behind them
    is checked.

    Note that this is different from charybdis 1.x where all kinds of
    spoofs worked in operator {} blocks.

password
    A password used with the OPER command to use this operator {} block.
    Passwords are encrypted by default, but may be unencrypted if
    ~encrypted is present in the flags list.

rsa\_public\_key\_file
    An optional path to a RSA public key file associated with the
    operator {} block. This information is used by the CHALLENGE
    command, which is an alternative authentication scheme to the
    traditional OPER command.

umodes
    A list of usermodes to apply to successfully opered clients.

snomask
    An snomask to apply to successfully opered clients.

privset
    The privilege set granted to successfully opered clients. This must
    be defined before this operator{} block.

flags
    A list of flags to apply to this operator{} block. They are listed
    below.

encrypted
    The password used has been encrypted. This is enabled by default,
    use ~encrypted to disable it.

need\_ssl
    Restricts use of this operator{} block to SSL/TLS connections only.

connect {} block
----------------

connect "
name
" { host = "
text
"; send\_password = "
text
"; accept\_password = "
text
"; port =
number
; hub\_mask = "
mask
"; leaf\_mask = "
mask
"; class = "
text
"; flags =
list
; aftype =
protocol
; };
Connect blocks define what servers may connect or be connected to.

host
    The hostname or IP to connect to.

.. note:: Furthermore, if a hostname is used, it must have an ``A`` or
          ``AAAA`` record (no ``CNAME``) and it must be the primary hostname
          for inbound connections to work.

send\_password
    The password to send to the other server.

accept\_password
    The password that should be accepted from the other server.

port
    The port on the other server to connect to.

hub\_mask
    An optional domain mask of servers allowed to be introduced by this
    link. Usually, "\*" is fine. Multiple hub\_masks may be specified,
    and any of them may be introduced. Violation of hub\_mask and
    leaf\_mask restrictions will cause the local link to be closed.

leaf\_mask
    An optional domain mask of servers not allowed to be introduced by
    this link. Multiple leaf\_masks may be specified, and none of them
    may be introduced. leaf\_mask has priority over hub\_mask.

class
    The name of the class this server should be placed into.

flags
    A list of flags concerning the connect block. They are listed below.

aftype
    The protocol that should be used to connect with, either ipv4 or
    ipv6. This defaults to neither, allowing connection using either
    address family.

encrypted
    The value for accept\_password has been encrypted.

autoconn
    The server should automatically try to connect to the server defined
    in this connect {} block if it's not connected already and
    max\_number in the class is not reached yet.

compressed
    Ziplinks should be used with this server connection. This compresses
    traffic using zlib, saving some bandwidth and speeding up netbursts.

    If you have trouble setting up a link, you should turn this off as
    it often hides error messages.

topicburst
    Topics should be bursted to this server.

    This is enabled by default.

listen {} block
---------------

listen { host = "
text
"; port =
number
; };
A listen block specifies what ports a server should listen on.

host
    An optional host to bind to. Otherwise, the ircd will listen on all
    available hosts.

port
    A port to listen on. You can specify multiple ports via commas, and
    define a range by seperating the start and end ports with two dots
    (..).

modules {} block
----------------

modules { path = "
text
"; module =
text
; };
The modules block specifies information for loadable modules.

path
    Specifies a path to search for loadable modules.

module
    Specifies a module to load, similar to loadmodule.

general {} block
----------------

modules {
values
};
The general block specifies a variety of options, many of which were in
``config.h`` in older daemons. The options are documented in
``reference.conf``.

channel {} block
----------------

modules {
values
};
The channel block specifies a variety of channel-related options, many
of which were in ``config.h`` in older daemons. The options are
documented in ``reference.conf``.

serverhide {} block
-------------------

modules {
values
};
The serverhide block specifies options related to server hiding. The
options are documented in ``reference.conf``.

blacklist {} block
------------------

blacklist { host = "
text
"; reject\_reason = "
text
"; };
The blacklist block specifies DNS blacklists to check. Listed clients
will not be allowed to connect. IPv6 clients are not checked against
these.

Multiple blacklists can be specified, in pairs with first host then
reject\_reason.

host
    The DNSBL to use.

reject\_reason
    The reason to send to listed clients when disconnecting them.

alias {} block
--------------

alias "
name
" { target = "
text
"; };
Alias blocks allow the definition of custom commands. These commands
send PRIVMSG to the given target. A real command takes precedence above
an alias.

target
    The target nick (must be a network service (umode +S)) or
    user@server. In the latter case, the server cannot be this server,
    only opers can use user starting with "opers" reliably and the user
    is interpreted on the target server only so you may need to use
    nick@server instead).

cluster {} block
----------------

cluster { name = "
text
"; flags =
list
; };
The cluster block specifies servers we propagate things to
automatically. This does not allow them to set bans, you need a separate
shared{} block for that.

Having overlapping cluster{} items will cause the command to be executed
twice on the target servers. This is particularly undesirable for ban
removals.

The letters in parentheses denote the flags in /stats U.

name
    The server name to share with, this may contain wildcards and may be
    stacked.

flags
    The list of what to share, all the name lines above this (up to
    another flags entry) will receive these flags. They are listed
    below.

kline (K)
    Permanent K:lines

tkline (k)
    Temporary K:lines

unkline (U)
    K:line removals

xline (X)
    Permanent X:lines

txline (x)
    Temporary X:lines

unxline (Y)
    X:line removals

resv (Q)
    Permanently reserved nicks/channels

tresv (q)
    Temporarily reserved nicks/channels

unresv (R)
    RESV removals

locops (L)
    LOCOPS messages (sharing this with \* makes LOCOPS rather similar to
    OPERWALL which is not useful)

all
    All of the above

shared {} block
---------------

shared { oper = "
user@host
", "
server
"; flags =
list
; };
The shared block specifies opers allowed to perform certain actions on
our server remotely. These are ordered top down. The first one matching
will determine the oper's access. If access is denied, the command will
be silently ignored.

The letters in parentheses denote the flags in /stats U.

oper
    The user@host the oper must have, and the server they must be on.
    This may contain wildcards.

flags
    The list of what to allow, all the oper lines above this (up to
    another flags entry) will receive these flags. They are listed
    below.

.. note:: While they have the same names, the flags have subtly
          different meanings from those in the cluster{} block.

kline (K)
    Permanent and temporary K:lines

tkline (k)
    Temporary K:lines

unkline (U)
    K:line removals

xline (X)
    Permanent and temporary X:lines

txline (x)
    Temporary X:lines

unxline (Y)
    X:line removals

resv (Q)
    Permanently and temporarily reserved nicks/channels

tresv (q)
    Temporarily reserved nicks/channels

unresv (R)
    RESV removals

all
    All of the above; this does not include locops, rehash, dline,
    tdline or undline.

locops (L)
    LOCOPS messages (accepting this from \* makes LOCOPS rather similar
    to OPERWALL which is not useful); unlike the other flags, this can
    only be accepted from \*@\* although it can be restricted based on
    source server.

rehash (H)
    REHASH commands; all options can be used

dline (D)
    Permanent and temporary D:lines

tdline (d)
    Temporary D:lines

undline (E)
    D:line removals

none
    Allow nothing to be done

service {} block
----------------

service { name = "
text
"; };
The service block specifies privileged servers (services). These servers
have extra privileges such as setting login names on users and
introducing clients with umode +S (unkickable, hide channels, etc). This
does not allow them to set bans, you need a separate shared{} block for
that.

Do not place normal servers here.

Multiple names may be specified but there may be only one service{}
block.

name
    The server name to grant special privileges. This may not contain
    wildcards.

Hostname resolution (DNS)
~~~~~~~~~~~~~~~~~~~~~~~~~

Charybdis uses solely DNS for all hostname/address lookups (no
``/etc/hosts`` or anything else). The DNS servers are taken from
``/etc/resolv.conf``. If this file does not exist or no valid IP
addresses are listed in it, the local host (127.0.0.1) is used. (Note
that the latter part did not work in older versions of Charybdis.)

IPv4 as well as IPv6 DNS servers are supported, but it is not possible
to use both IPv4 and IPv6 in ``/etc/resolv.conf``.

For both security and performance reasons, it is recommended that a
caching nameserver such as BIND be run on the same machine as Charybdis
and that ``/etc/resolv.conf`` only list 127.0.0.1.