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.
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 "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 {
name = "text";
sid = "text";
description = "text";
network_name = "text";
network_desc = "text";
hub = boolean;
vhost = "text";
vhost6 = "text";
};
The serverinfo {} block defines the core operational parameters of the IRC server.
serverinfo {} variables
- 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 {
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.
A point of contact for the administrator, usually an e-mail address.
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.
class {} variables: client classes
- 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.
class {} variables: server classes
- 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 {
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. InSTATS i
andTESTLINE
, an equals sign (=) appears before theuser@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 theuser@host
inSTATS i
andTESTLINE
.- 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 {
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.
exempt {} variables
- ip
The IP address or CIDR range to exempt.
privset {
extends = "name";
privs = list;
};
A privset (privilege set) block specifies a set of operator privileges.
privset {} variables
- 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 "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.
operator {} variables
- 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 traditionalOPER
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.
operator {} flags
- 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 "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.
connect {} variables
- host
The hostname or IP to connect to.
Note
Furthermore, if a hostname is used, it must have an
A
orAAAA
record (noCNAME
) 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.
connect {} flags
- 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 {
host = "text";
port = number;
};
A listen block specifies what ports a server should listen on.
listen {} variables
- 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 {
path = "text";
module = text;
};
The modules block specifies information for loadable modules.
modules {} variables
- path
Specifies a path to search for loadable modules.
- module
Specifies a module to load, similar to loadmodule.
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
.
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
.
modules {
values
};
The serverhide block specifies options related to server hiding. The options are documented in reference.conf
.
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.
blacklist {} variables
- host
The DNSBL to use.
- reject_reason
The reason to send to listed clients when disconnecting them.
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.
alias {} variables
- 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 {
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.
cluster {} variables
- 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.
cluster {} flags
- 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 * makesLOCOPS
rather similar toOPERWALL
which is not useful)- all
All of the above
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
.
shared {} variables
- 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.
shared {} flags
- 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 * makesLOCOPS
rather similar toOPERWALL
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 {
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.
service {} variables
- name
The server name to grant special privileges. This may not contain wildcards.
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
.