1 Server config file format
2 =========================
7 The config file consists of a series of BIND-style blocks. Each block
8 consists of a series of values inside it which pertain to configuration
9 settings that apply to the given block.
11 Several values take lists of values and have defaults preset inside
12 them. Prefix a keyword with a tilde (``~``) to override the default and
15 A line may also be a .include directive, which is of the form::
19 and causes file to be read in at that point, before the rest of
20 the current file is processed. Relative paths are first tried relative
21 to ``PREFIX`` and then relative to ``ETCPATH`` (normally ``PREFIX``/etc).
23 Anything from a ``#`` to the end of a line is a comment. Blank lines are
24 ignored. C-style comments are also supported.
26 Specific blocks and directives
27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29 Not all configuration blocks and directives are listed here, only the
30 most common ones. More blocks and directives will be documented in later
31 revisions of this manual.
40 Loads a module into the IRCd. In charybdis 1.1, most modules are
41 automatically loaded in. In future versions, it is intended to remove
42 this behaviour as to allow for easy customization of the IRCd's
54 network_name = "text";
55 network_desc = "text";
61 The serverinfo {} block defines the core operational parameters of the
64 **serverinfo {} variables**
67 The name of the IRC server that you are configuring. This must
68 contain at least one dot. It is not necessarily equal to any DNS
69 name. This must be unique on the IRC network.
72 A unique ID which describes the server. This consists of one digit
73 and two characters which can be digits or letters.
76 A user-defined field of text which describes the IRC server. This
77 information is used in ``/links`` and ``/whois`` requests. Geographical
78 location information could be a useful use of this field, but most
79 administrators put a witty saying inside it instead.
82 The name of the IRC network that this server will be a member of.
83 This is used in the welcome message and ``NETWORK=`` in 005.
86 A boolean which defines whether or not this IRC server will be
87 serving as a hub, i.e. have multiple servers connected to it.
90 An optional text field which defines an IPv4 address from which
91 to connect outward to other IRC servers.
94 An optional text field which defines an IPv6 address from which
95 to connect outward to other IRC servers.
104 description = "text";
108 This block provides the information which is returned by the ``ADMIN``
112 The name of the administrator running this service.
115 The description of the administrator's position in the network.
118 A point of contact for the administrator, usually an e-mail address.
126 ping_time = duration;
127 number_per_ident = number;
128 number_per_ip = number;
129 number_per_ip_global = number;
130 cidr_ipv4_bitlen = number;
131 cidr_ipv6_bitlen = number;
132 number_per_cidr = number;
138 ping_time = duration;
139 connectfreq = duration;
144 Class blocks define classes of connections for later use. The class name
145 is used to connect them to other blocks in the config file (auth{} and
146 connect{}). They must be defined before they are used.
148 Classes are used both for client and server connections, but most
149 variables are different.
151 **class {} variables: client classes**
154 The amount of time between checking pings for clients, e.g.: 2
158 The amount of clients which may be connected from a single identd
159 username on a per-IP basis, globally. Unidented clients all count as
163 The amount of clients which may be connected from a single IP
166 number\_per\_ip\_global
167 The amount of clients which may be connected globally from a single
171 The netblock length to use with CIDR-based client limiting for IPv4
172 users in this class (between 0 and 32).
175 The netblock length to use with CIDR-based client limiting for IPv6
176 users in this class (between 0 and 128).
179 The amount of clients which may be connected from a single netblock.
181 If this needs to differ between IPv4 and IPv6, make different
182 classes for IPv4 and IPv6 users.
185 The maximum amount of clients which may use this class at any given
189 The maximum size of the queue of data to be sent to a client before
192 **class {} variables: server classes**
195 The amount of time between checking pings for servers, e.g.: 2
199 The amount of time between autoconnects. This must at least be one
200 minute, as autoconnects are evaluated with that granularity.
203 The amount of servers to autoconnect to in this class. More
204 precisely, no autoconnects are done if the number of servers in this
205 class is greater than or equal max\_number
208 The maximum size of the queue of data to be sent to a server before
224 auth {} blocks allow client connections to the server, and set various
225 properties concerning those connections.
227 Auth blocks are evaluated from top to bottom in priority, so put special
234 A hostmask (``user@host``) that the auth {} block applies to. It is
235 matched against the hostname and IP address (using :: shortening for
236 IPv6 and prepending a 0 if it starts with a colon) and can also use
237 CIDR masks. You can have multiple user entries.
240 An optional password to use for authenticating into this auth{}
241 block. If the password is wrong the user will not be able to connect
242 (will not fall back on another auth{} block).
245 An optional fake hostname (or ``user@host``) to apply to users
246 authenticated to this auth{} block. In ``STATS i`` and ``TESTLINE``, an
247 equals sign (=) appears before the ``user@host`` and the spoof is shown.
250 A list of flags to apply to this ``auth{}`` block. They are listed
251 below. Some of the flags appear as a special character,
252 parenthesized in the list, before the ``user@host`` in ``STATS i`` and
256 A name of a class to put users matching this auth{} block into.
262 The password used has been encrypted.
265 Causes the IRCd to send out a server notice when activating a spoof
266 provided by this auth{} block.
269 Users in this auth{} block can exceed class-wide limitations.
272 Users in this auth{} block are exempted from DNS blacklist checks.
273 However, they will still be warned if they are listed.
276 Users in this auth{} block are exempted from DNS blacklists, k:lines
280 Users in this auth{} block are exempted from spambot checks.
283 Users in this auth{} block are exempted from some serverhiding
287 Users in this auth{} block do not trigger an alarm when joining
291 Users in this auth{} block may use reserved nicknames and channels.
293 .. note:: The initial nickname may still not be reserved.
295 flood\_exempt (\|) Users in this auth{} block may send arbitrary
296 amounts of commands per time unit to the server. This does not
297 exempt them from any other flood limits. You should use this
298 setting with caution.
301 Users in this auth{} block will not have a tilde added to their
302 username if they do not run identd.
305 Users in this auth{} block must have identd, otherwise they will be
309 Users in this auth{} block must be connected via SSL/TLS, otherwise
310 they will be rejected.
313 Users in this auth{} block must identify via SASL, otherwise they
325 An exempt block specifies IP addresses which are exempt from ``D:lines`` and
326 throttling. Multiple addresses can be specified in one block. Clients
327 coming from these addresses can still be ``K/G/X:lined`` or banned by a DNS
328 blacklist unless they also have appropriate flags in their auth{} block.
330 **exempt {} variables**
333 The IP address or CIDR range to exempt.
345 A privset (privilege set) block specifies a set of operator privileges.
347 **privset {} variables**
350 An optional privset to inherit. The new privset will have all
351 privileges that the given privset has.
354 Privileges to grant to this privset. These are described in the
355 operator privileges section.
365 rsa_public_key_file = "text";
371 Operator blocks define who may use the ``OPER`` command to gain extended
374 **operator {} variables**
377 A hostmask that users trying to use this operator {} block must
378 match. This is checked against the original host and IP address;
379 CIDR is also supported. So auth {} spoofs work in operator {}
380 blocks; the real host behind them is not checked. Other kind of
381 spoofs do not work in operator {} blocks; the real host behind them
384 Note that this is different from charybdis 1.x where all kinds of
385 spoofs worked in operator {} blocks.
388 A password used with the ``OPER`` command to use this operator {} block.
389 Passwords are encrypted by default, but may be unencrypted if
390 ~encrypted is present in the flags list.
392 rsa\_public\_key\_file
393 An optional path to a RSA public key file associated with the
394 operator {} block. This information is used by the ``CHALLENGE``
395 command, which is an alternative authentication scheme to the
396 traditional ``OPER`` command.
399 A list of usermodes to apply to successfully opered clients.
402 An snomask to apply to successfully opered clients.
405 The privilege set granted to successfully opered clients. This must
406 be defined before this operator{} block.
409 A list of flags to apply to this operator{} block. They are listed
412 **operator {} flags**
415 The password used has been encrypted. This is enabled by default,
416 use ~encrypted to disable it.
419 Restricts use of this operator{} block to SSL/TLS connections only.
428 send_password = "text";
429 accept_password = "text";
438 Connect blocks define what servers may connect or be connected to.
440 **connect {} variables**
443 The hostname or IP to connect to.
445 .. note:: Furthermore, if a hostname is used, it must have an
446 ``A`` or ``AAAA`` record (no ``CNAME``) and it must be
447 the primary hostname for inbound connections to work.
450 The password to send to the other server.
453 The password that should be accepted from the other server.
456 The port on the other server to connect to.
459 An optional domain mask of servers allowed to be introduced by this
460 link. Usually, "\*" is fine. Multiple hub\_masks may be specified,
461 and any of them may be introduced. Violation of hub\_mask and
462 leaf\_mask restrictions will cause the local link to be closed.
465 An optional domain mask of servers not allowed to be introduced by
466 this link. Multiple leaf\_masks may be specified, and none of them
467 may be introduced. leaf\_mask has priority over hub\_mask.
470 The name of the class this server should be placed into.
473 A list of flags concerning the connect block. They are listed below.
476 The protocol that should be used to connect with, either ipv4 or
477 ipv6. This defaults to neither, allowing connection using either
483 The value for accept\_password has been encrypted.
486 The server should automatically try to connect to the server defined
487 in this connect {} block if it's not connected already and
488 max\_number in the class is not reached yet.
491 Ziplinks should be used with this server connection. This compresses
492 traffic using zlib, saving some bandwidth and speeding up netbursts.
494 If you have trouble setting up a link, you should turn this off as
495 it often hides error messages.
498 Topics should be bursted to this server.
500 This is enabled by default.
512 A listen block specifies what ports a server should listen on.
514 **listen {} variables**
517 An optional host to bind to. Otherwise, the ircd will listen on all
521 A port to listen on. You can specify multiple ports via commas, and
522 define a range by seperating the start and end ports with two dots
535 The modules block specifies information for loadable modules.
537 **modules {} variables**
540 Specifies a path to search for loadable modules.
543 Specifies a module to load, similar to loadmodule.
554 The general block specifies a variety of options, many of which were in
555 ``config.h`` in older daemons. The options are documented in
567 The channel block specifies a variety of channel-related options, many
568 of which were in ``config.h`` in older daemons. The options are
569 documented in ``reference.conf``.
580 The serverhide block specifies options related to server hiding. The
581 options are documented in ``reference.conf``.
590 reject_reason = "text";
593 The blacklist block specifies DNS blacklists to check. Listed clients
594 will not be allowed to connect. IPv6 clients are not checked against
597 Multiple blacklists can be specified, in pairs with first host then
600 **blacklist {} variables**
606 The reason to send to listed clients when disconnecting them.
617 Alias blocks allow the definition of custom commands. These commands
618 send ``PRIVMSG`` to the given target. A real command takes precedence above
621 **alias {} variables**
624 The target nick (must be a network service (umode ``+S``)) or
625 user@server. In the latter case, the server cannot be this server,
626 only opers can use user starting with "opers" reliably and the user
627 is interpreted on the target server only so you may need to use
628 nick@server instead).
640 The cluster block specifies servers we propagate things to
641 automatically. This does not allow them to set bans, you need a separate
642 shared{} block for that.
644 Having overlapping cluster{} items will cause the command to be executed
645 twice on the target servers. This is particularly undesirable for ban
648 The letters in parentheses denote the flags in ``/stats`` U.
650 **cluster {} variables**
653 The server name to share with, this may contain wildcards and may be
657 The list of what to share, all the name lines above this (up to
658 another flags entry) will receive these flags. They are listed
664 Permanent ``K:lines``
667 Temporary ``K:lines``
673 Permanent ``X:lines``
676 Temporary ``X:lines``
682 Permanently reserved nicks/channels
685 Temporarily reserved nicks/channels
691 ``LOCOPS`` messages (sharing this with \* makes ``LOCOPS`` rather similar to
692 ``OPERWALL`` which is not useful)
703 oper = "user@host", "server";
707 The shared block specifies opers allowed to perform certain actions on
708 our server remotely. These are ordered top down. The first one matching
709 will determine the oper's access. If access is denied, the command will
712 The letters in parentheses denote the flags in ``/stats U``.
714 **shared {} variables**
717 The user@host the oper must have, and the server they must be on.
718 This may contain wildcards.
721 The list of what to allow, all the oper lines above this (up to
722 another flags entry) will receive these flags. They are listed
725 .. note:: While they have the same names, the flags have subtly
726 different meanings from those in the cluster{} block.
731 Permanent and temporary ``K:lines``
734 Temporary ``K:lines``
740 Permanent and temporary ``X:lines``
743 Temporary ``X:lines``
749 Permanently and temporarily reserved nicks/channels
752 Temporarily reserved nicks/channels
758 All of the above; this does not include locops, rehash, dline,
762 ``LOCOPS`` messages (accepting this from \* makes ``LOCOPS`` rather similar
763 to ``OPERWALL`` which is not useful); unlike the other flags, this can
764 only be accepted from \*@\* although it can be restricted based on
768 ``REHASH`` commands; all options can be used
771 Permanent and temporary ``D:lines``
774 Temporary ``D:lines``
780 Allow nothing to be done
791 The service block specifies privileged servers (services). These servers
792 have extra privileges such as setting login names on users and
793 introducing clients with umode ``+S`` (unkickable, hide channels, etc). This
794 does not allow them to set bans, you need a separate shared{} block for
797 Do not place normal servers here.
799 Multiple names may be specified but there may be only one service{}
802 **service {} variables**
805 The server name to grant special privileges. This may not contain
808 Hostname resolution (DNS)
809 ~~~~~~~~~~~~~~~~~~~~~~~~~
811 Charybdis uses solely DNS for all hostname/address lookups (no
812 ``/etc/hosts`` or anything else). The DNS servers are taken from
813 ``/etc/resolv.conf``. If this file does not exist or no valid IP
814 addresses are listed in it, the local host (``127.0.0.1``) is used. (Note
815 that the latter part did not work in older versions of Charybdis.)
817 IPv4 as well as IPv6 DNS servers are supported, but it is not possible
818 to use both IPv4 and IPv6 in ``/etc/resolv.conf``.
820 For both security and performance reasons, it is recommended that a
821 caching nameserver such as BIND be run on the same machine as Charybdis
822 and that ``/etc/resolv.conf`` only list ``127.0.0.1``.