9pfs/solanum-vs-hackint-and-charybdis
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

config.rst review

Browse source
This commit is contained in:
Antoine Beaupré 2017-03-25 12:22:36 -04:00
parent ea56df54f7
commit f41c25c0c1
No known key found for this signature in database
GPG key ID: 792152527B75921E
1 changed files with 279 additions and 213 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

468
doc/oper-guide/config.rst
View file

@ -9,15 +9,18 @@ consists of a series of values inside it which pertain to configuration
settings that apply to the given block. settings that apply to the given block.
Several values take lists of values and have defaults preset inside Several values take lists of values and have defaults preset inside
them. Prefix a keyword with a tilde (~) to override the default and them. Prefix a keyword with a tilde (``~``) to override the default and
disable it. disable it.
A line may also be a .include directive, which is of the form .include A line may also be a .include directive, which is of the form::
"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 .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. ignored. C-style comments are also supported.
Specific blocks and directives Specific blocks and directives
@ -30,9 +33,10 @@ revisions of this manual.
loadmodule directive loadmodule directive
-------------------- --------------------
loadmodule " ::
text
"; loadmodule "text";
Loads a module into the IRCd. In charybdis 1.1, most modules are Loads a module into the IRCd. In charybdis 1.1, most modules are
automatically loaded in. In future versions, it is intended to remove automatically loaded in. In future versions, it is intended to remove
this behaviour as to allow for easy customization of the IRCd's this behaviour as to allow for easy customization of the IRCd's
@ -41,24 +45,25 @@ featureset.
serverinfo {} block serverinfo {} block
------------------- -------------------
serverinfo { name = " ::
text
"; sid = " serverinfo {
text name = "text";
"; description = " sid = "text";
text description = "text";
"; network\_name = " network_name = "text";
text network_desc = "text";
"; hub = hub = boolean;
boolean vhost = "text";
; vhost = " vhost6 = "text";
text };
"; vhost6 = "
text
"; };
The serverinfo {} block defines the core operational parameters of the The serverinfo {} block defines the core operational parameters of the
IRC server. IRC server.
serverinfo {} variables
~~~~~~~~~~~~~~~~~~~~~~~
name name
The name of the IRC server that you are configuring. This must 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 contain at least one dot. It is not necessarily equal to any DNS
@ -70,13 +75,13 @@ sid
description description
A user-defined field of text which describes the IRC server. This A user-defined field of text which describes the IRC server. This
information is used in /links and /whois requests. Geographical information is used in ``/links`` and ``/whois`` requests. Geographical
location information could be a useful use of this field, but most location information could be a useful use of this field, but most
administrators put a witty saying inside it instead. administrators put a witty saying inside it instead.
network\_name network\_name
The name of the IRC network that this server will be a member of. 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. This is used in the welcome message and ``NETWORK=`` in 005.
hub hub
A boolean which defines whether or not this IRC server will be A boolean which defines whether or not this IRC server will be
@ -93,14 +98,15 @@ vhost6
admin {} block admin {} block
-------------- --------------
admin { name = " ::
text
"; description = " admin {
text name = "text";
"; email = " description = "text";
text email = "text";
"; }; };
This block provides the information which is returned by the ADMIN
This block provides the information which is returned by the ``ADMIN``
command. command.
name name
@ -115,38 +121,27 @@ email
class {} block class {} block
-------------- --------------
class " ::
name
" { ping\_time = class "name" {
duration ping_time = duration;
; number\_per\_ident = number_per_ident = number;
number number_per_ip = number;
; number\_per\_ip = number_per_ip_global = number;
number cidr_ipv4_bitlen = number;
; number\_per\_ip\_global = cidr_ipv6_bitlen = number;
number number_per_cidr = number;
; cidr\_ipv4\_bitlen = max_number = number;
number sendq = size;
; cidr\_ipv6\_bitlen = };
number
; number\_per\_cidr = class "name" {
number ping_time = duration;
; max\_number = connectfreq = duration;
number max_number = number;
; sendq = sendq = size;
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 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 is used to connect them to other blocks in the config file (auth{} and
connect{}). They must be defined before they are used. connect{}). They must be defined before they are used.
@ -154,6 +149,9 @@ connect{}). They must be defined before they are used.
Classes are used both for client and server connections, but most Classes are used both for client and server connections, but most
variables are different. variables are different.
class {} variables: client classes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ping\_time ping\_time
The amount of time between checking pings for clients, e.g.: 2 The amount of time between checking pings for clients, e.g.: 2
minutes minutes
@ -193,6 +191,9 @@ sendq
The maximum size of the queue of data to be sent to a client before The maximum size of the queue of data to be sent to a client before
it is dropped. it is dropped.
class {} variables: server classes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ping\_time ping\_time
The amount of time between checking pings for servers, e.g.: 2 The amount of time between checking pings for servers, e.g.: 2
minutes minutes
@ -213,25 +214,27 @@ sendq
auth {} block auth {} block
------------- -------------
auth { user = " ::
hostmask
"; password = " auth {
text user = "hostmask";
"; spoof = " password = "text";
text spoof = "text";
"; flags = flags = list;
list class = "text";
; class = " };
text
"; };
auth {} blocks allow client connections to the server, and set various auth {} blocks allow client connections to the server, and set various
properties concerning those connections. properties concerning those connections.
Auth blocks are evaluated from top to bottom in priority, so put special Auth blocks are evaluated from top to bottom in priority, so put special
blocks first. blocks first.
auth {} variables
~~~~~~~~~~~~~~~~~
user user
A hostmask (user@host) that the auth {} block applies to. It is A hostmask (``user@host``) that the auth {} block applies to. It is
matched against the hostname and IP address (using :: shortening for 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 IPv6 and prepending a 0 if it starts with a colon) and can also use
CIDR masks. You can have multiple user entries. CIDR masks. You can have multiple user entries.
@ -242,19 +245,22 @@ password
(will not fall back on another auth{} block). (will not fall back on another auth{} block).
spoof spoof
An optional fake hostname (or user@host) to apply to users An optional fake hostname (or ``user@host``) to apply to users
authenticated to this auth{} block. In STATS i and TESTLINE, an authenticated to this auth{} block. In ``STATS i`` and ``TESTLINE``, an
equals sign (=) appears before the user@host and the spoof is shown. equals sign (=) appears before the ``user@host`` and the spoof is shown.
flags flags
A list of flags to apply to this auth{} block. They are listed A list of flags to apply to this ``auth{}`` block. They are listed
below. Some of the flags appear as a special character, below. Some of the flags appear as a special character,
parenthesized in the list, before the user@host in STATS i and parenthesized in the list, before the ``user@host`` in ``STATS i`` and
TESTLINE. ``TESTLINE``.
class class
A name of a class to put users matching this auth{} block into. A name of a class to put users matching this auth{} block into.
auth {} flags
~~~~~~~~~~~~~
encrypted encrypted
The password used has been encrypted. The password used has been encrypted.
@ -313,27 +319,38 @@ need\_sasl
exempt {} block exempt {} block
--------------- ---------------
exempt { ip = " ::
ip
"; }; exempt {
An exempt block specifies IP addresses which are exempt from D:lines and 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 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 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. blacklist unless they also have appropriate flags in their auth{} block.
exempt {} variables
~~~~~~~~~~~~~~~~~~~
ip ip
The IP address or CIDR range to exempt. The IP address or CIDR range to exempt.
privset {} block privset {} block
---------------- ----------------
privset { extends = " ::
name
"; privs = privset {
list extends = "name";
; }; privs = list;
};
A privset (privilege set) block specifies a set of operator privileges. A privset (privilege set) block specifies a set of operator privileges.
privset {} variables
~~~~~~~~~~~~~~~~~~~~
extends extends
An optional privset to inherit. The new privset will have all An optional privset to inherit. The new privset will have all
privileges that the given privset has. privileges that the given privset has.
@ -345,24 +362,23 @@ privs
operator {} block operator {} block
----------------- -----------------
operator " ::
name
" { user = " operator "name" {
hostmask user = "hostmask";
"; password = " password = "text";
text rsa_public_key_file = "text";
"; rsa\_public\_key\_file = " umodes = list;
text snomask = "text";
"; umodes = flags = list;
list };
; snomask = "
text Operator blocks define who may use the ``OPER`` command to gain extended
"; flags =
list
; };
Operator blocks define who may use the OPER command to gain extended
privileges. privileges.
operator {} variables
~~~~~~~~~~~~~~~~~~~~~
user user
A hostmask that users trying to use this operator {} block must A hostmask that users trying to use this operator {} block must
match. This is checked against the original host and IP address; match. This is checked against the original host and IP address;
@ -375,15 +391,15 @@ user
spoofs worked in operator {} blocks. spoofs worked in operator {} blocks.
password password
A password used with the OPER command to use this operator {} block. A password used with the ``OPER`` command to use this operator {} block.
Passwords are encrypted by default, but may be unencrypted if Passwords are encrypted by default, but may be unencrypted if
~encrypted is present in the flags list. ~encrypted is present in the flags list.
rsa\_public\_key\_file rsa\_public\_key\_file
An optional path to a RSA public key file associated with the An optional path to a RSA public key file associated with the
operator {} block. This information is used by the CHALLENGE operator {} block. This information is used by the ``CHALLENGE``
command, which is an alternative authentication scheme to the command, which is an alternative authentication scheme to the
traditional OPER command. traditional ``OPER`` command.
umodes umodes
A list of usermodes to apply to successfully opered clients. A list of usermodes to apply to successfully opered clients.
@ -399,6 +415,9 @@ flags
A list of flags to apply to this operator{} block. They are listed A list of flags to apply to this operator{} block. They are listed
below. below.
operator {} flags
~~~~~~~~~~~~~~~~~
encrypted encrypted
The password used has been encrypted. This is enabled by default, The password used has been encrypted. This is enabled by default,
use ~encrypted to disable it. use ~encrypted to disable it.
@ -409,35 +428,31 @@ need\_ssl
connect {} block connect {} block
---------------- ----------------
connect " ::
name
" { host = " connect "name" {
text host = "text";
"; send\_password = " send_password = "text";
text accept_password = "text";
"; accept\_password = " port = number;
text hub_mask = "mask";
"; port = leaf_mask = "mask";
number class = "text";
; hub\_mask = " flags = list;
mask aftype = protocol;
"; leaf\_mask = " };
mask
"; class = "
text
"; flags =
list
; aftype =
protocol
; };
Connect blocks define what servers may connect or be connected to. Connect blocks define what servers may connect or be connected to.
connect {} variables
~~~~~~~~~~~~~~~~~~~~
host host
The hostname or IP to connect to. The hostname or IP to connect to.
.. note:: Furthermore, if a hostname is used, it must have an ``A`` or .. note:: Furthermore, if a hostname is used, it must have an
``AAAA`` record (no ``CNAME``) and it must be the primary hostname ``A`` or ``AAAA`` record (no ``CNAME``) and it must be
for inbound connections to work. the primary hostname for inbound connections to work.
IPv6 addresses must be in ``::`` shortened form; addresses which IPv6 addresses must be in ``::`` shortened form; addresses which
then start with a colon must be prepended with a zero, for then start with a colon must be prepended with a zero, for
@ -473,6 +488,9 @@ aftype
The protocol that should be used to connect with, either ipv4 or The protocol that should be used to connect with, either ipv4 or
ipv6. This defaults to ipv4 unless host is a numeric IPv6 address. ipv6. This defaults to ipv4 unless host is a numeric IPv6 address.
connect {} flags
~~~~~~~~~~~~~~~~
encrypted encrypted
The value for accept\_password has been encrypted. The value for accept\_password has been encrypted.
@ -496,13 +514,18 @@ topicburst
listen {} block listen {} block
--------------- ---------------
listen { host = " ::
text
"; port = listen {
number host = "text";
; }; port = number;
};
A listen block specifies what ports a server should listen on. A listen block specifies what ports a server should listen on.
listen {} variables
~~~~~~~~~~~~~~~~~~~
host host
An optional host to bind to. Otherwise, the ircd will listen on all An optional host to bind to. Otherwise, the ircd will listen on all
available hosts. available hosts.
@ -515,13 +538,18 @@ port
modules {} block modules {} block
---------------- ----------------
modules { path = " ::
text
"; module = modules {
text path = "text";
; }; module = text;
};
The modules block specifies information for loadable modules. The modules block specifies information for loadable modules.
modules {} variables
~~~~~~~~~~~~~~~~~~~~
path path
Specifies a path to search for loadable modules. Specifies a path to search for loadable modules.
@ -531,9 +559,12 @@ module
general {} block general {} block
---------------- ----------------
::
modules { modules {
values values
}; };
The general block specifies a variety of options, many of which were in The general block specifies a variety of options, many of which were in
``config.h`` in older daemons. The options are documented in ``config.h`` in older daemons. The options are documented in
``reference.conf``. ``reference.conf``.
@ -541,9 +572,12 @@ The general block specifies a variety of options, many of which were in
channel {} block channel {} block
---------------- ----------------
::
modules { modules {
values values
}; };
The channel block specifies a variety of channel-related options, many The channel block specifies a variety of channel-related options, many
of which were in ``config.h`` in older daemons. The options are of which were in ``config.h`` in older daemons. The options are
documented in ``reference.conf``. documented in ``reference.conf``.
@ -551,20 +585,25 @@ documented in ``reference.conf``.
serverhide {} block serverhide {} block
------------------- -------------------
::
modules { modules {
values values
}; };
The serverhide block specifies options related to server hiding. The The serverhide block specifies options related to server hiding. The
options are documented in ``reference.conf``. options are documented in ``reference.conf``.
blacklist {} block blacklist {} block
------------------ ------------------
blacklist { host = " ::
text
"; reject\_reason = " blacklist {
text host = "text";
"; }; reject_reason = "text";
};
The blacklist block specifies DNS blacklists to check. Listed clients The blacklist block specifies DNS blacklists to check. Listed clients
will not be allowed to connect. IPv6 clients are not checked against will not be allowed to connect. IPv6 clients are not checked against
these. these.
@ -572,6 +611,9 @@ these.
Multiple blacklists can be specified, in pairs with first host then Multiple blacklists can be specified, in pairs with first host then
reject\_reason. reject\_reason.
blacklist {} variables
~~~~~~~~~~~~~~~~~~~~~~
host host
The DNSBL to use. The DNSBL to use.
@ -581,17 +623,21 @@ reject\_reason
alias {} block alias {} block
-------------- --------------
alias " ::
name
" { target = " alias "name" {
text target = "text";
"; }; };
Alias blocks allow the definition of custom commands. These commands Alias blocks allow the definition of custom commands. These commands
send PRIVMSG to the given target. A real command takes precedence above send ``PRIVMSG`` to the given target. A real command takes precedence above
an alias. an alias.
alias {} variables
~~~~~~~~~~~~~~~~~~
target target
The target nick (must be a network service (umode +S)) or The target nick (must be a network service (umode ``+S``)) or
user@server. In the latter case, the server cannot be this server, user@server. In the latter case, the server cannot be this server,
only opers can use user starting with "opers" reliably and the user 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 is interpreted on the target server only so you may need to use
@ -600,11 +646,13 @@ target
cluster {} block cluster {} block
---------------- ----------------
cluster { name = " ::
text
"; flags = cluster {
list name = "text";
; }; flags = list;
};
The cluster block specifies servers we propagate things to The cluster block specifies servers we propagate things to
automatically. This does not allow them to set bans, you need a separate automatically. This does not allow them to set bans, you need a separate
shared{} block for that. shared{} block for that.
@ -613,7 +661,10 @@ Having overlapping cluster{} items will cause the command to be executed
twice on the target servers. This is particularly undesirable for ban twice on the target servers. This is particularly undesirable for ban
removals. removals.
The letters in parentheses denote the flags in /stats U. The letters in parentheses denote the flags in ``/stats`` U.
cluster {} variables
~~~~~~~~~~~~~~~~~~~~
name name
The server name to share with, this may contain wildcards and may be The server name to share with, this may contain wildcards and may be
@ -624,23 +675,26 @@ flags
another flags entry) will receive these flags. They are listed another flags entry) will receive these flags. They are listed
below. below.
cluster {} flags
~~~~~~~~~~~~~~~~
kline (K) kline (K)
Permanent K:lines Permanent ``K:lines``
tkline (k) tkline (k)
Temporary K:lines Temporary ``K:lines``
unkline (U) unkline (U)
K:line removals ``K:line`` removals
xline (X) xline (X)
Permanent X:lines Permanent ``X:lines``
txline (x) txline (x)
Temporary X:lines Temporary ``X:lines``
unxline (Y) unxline (Y)
X:line removals ``X:line`` removals
resv (Q) resv (Q)
Permanently reserved nicks/channels Permanently reserved nicks/channels
@ -649,11 +703,11 @@ tresv (q)
Temporarily reserved nicks/channels Temporarily reserved nicks/channels
unresv (R) unresv (R)
RESV removals ``RESV`` removals
locops (L) locops (L)
LOCOPS messages (sharing this with \* makes LOCOPS rather similar to ``LOCOPS`` messages (sharing this with \* makes ``LOCOPS`` rather similar to
OPERWALL which is not useful) ``OPERWALL`` which is not useful)
all all
All of the above All of the above
@ -661,19 +715,22 @@ all
shared {} block shared {} block
--------------- ---------------
shared { oper = " ::
user@host
", " shared {
server oper = "user@host", "server";
"; flags = flags = list;
list };
; };
The shared block specifies opers allowed to perform certain actions on The shared block specifies opers allowed to perform certain actions on
our server remotely. These are ordered top down. The first one matching 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 will determine the oper's access. If access is denied, the command will
be silently ignored. be silently ignored.
The letters in parentheses denote the flags in /stats U. The letters in parentheses denote the flags in ``/stats U``.
shared {} variables
~~~~~~~~~~~~~~~~~~~
oper oper
The user@host the oper must have, and the server they must be on. The user@host the oper must have, and the server they must be on.
@ -687,23 +744,26 @@ flags
.. note:: While they have the same names, the flags have subtly .. note:: While they have the same names, the flags have subtly
different meanings from those in the cluster{} block. different meanings from those in the cluster{} block.
shared {} flags
~~~~~~~~~~~~~~~
kline (K) kline (K)
Permanent and temporary K:lines Permanent and temporary ``K:lines``
tkline (k) tkline (k)
Temporary K:lines Temporary ``K:lines``
unkline (U) unkline (U)
K:line removals ``K:line`` removals
xline (X) xline (X)
Permanent and temporary X:lines Permanent and temporary ``X:lines``
txline (x) txline (x)
Temporary X:lines Temporary ``X:lines``
unxline (Y) unxline (Y)
X:line removals ``X:line`` removals
resv (Q) resv (Q)
Permanently and temporarily reserved nicks/channels Permanently and temporarily reserved nicks/channels
@ -712,29 +772,29 @@ tresv (q)
Temporarily reserved nicks/channels Temporarily reserved nicks/channels
unresv (R) unresv (R)
RESV removals ``RESV`` removals
all all
All of the above; this does not include locops, rehash, dline, All of the above; this does not include locops, rehash, dline,
tdline or undline. tdline or undline.
locops (L) locops (L)
LOCOPS messages (accepting this from \* makes LOCOPS rather similar ``LOCOPS`` messages (accepting this from \* makes ``LOCOPS`` rather similar
to OPERWALL which is not useful); unlike the other flags, this can to ``OPERWALL`` which is not useful); unlike the other flags, this can
only be accepted from \*@\* although it can be restricted based on only be accepted from \*@\* although it can be restricted based on
source server. source server.
rehash (H) rehash (H)
REHASH commands; all options can be used ``REHASH`` commands; all options can be used
dline (D) dline (D)
Permanent and temporary D:lines Permanent and temporary ``D:lines``
tdline (d) tdline (d)
Temporary D:lines Temporary ``D:lines``
undline (E) undline (E)
D:line removals ``D:line`` removals
none none
Allow nothing to be done Allow nothing to be done
@ -742,12 +802,15 @@ none
service {} block service {} block
---------------- ----------------
service { name = " ::
text
"; }; service {
name = "text";
};
The service block specifies privileged servers (services). These servers The service block specifies privileged servers (services). These servers
have extra privileges such as setting login names on users and have extra privileges such as setting login names on users and
introducing clients with umode +S (unkickable, hide channels, etc). This introducing clients with umode ``+S`` (unkickable, hide channels, etc). This
does not allow them to set bans, you need a separate shared{} block for does not allow them to set bans, you need a separate shared{} block for
that. that.
@ -756,6 +819,9 @@ Do not place normal servers here.
Multiple names may be specified but there may be only one service{} Multiple names may be specified but there may be only one service{}
block. block.
service {} variables
~~~~~~~~~~~~~~~~~~~~
name name
The server name to grant special privileges. This may not contain The server name to grant special privileges. This may not contain
wildcards. wildcards.
@ -766,7 +832,7 @@ Hostname resolution (DNS)
Charybdis uses solely DNS for all hostname/address lookups (no Charybdis uses solely DNS for all hostname/address lookups (no
``/etc/hosts`` or anything else). The DNS servers are taken from ``/etc/hosts`` or anything else). The DNS servers are taken from
``/etc/resolv.conf``. If this file does not exist or no valid IP ``/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 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.) 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 IPv4 as well as IPv6 DNS servers are supported, but it is not possible
@ -774,4 +840,4 @@ to use both IPv4 and IPv6 in ``/etc/resolv.conf``.
For both security and performance reasons, it is recommended that a For both security and performance reasons, it is recommended that a
caching nameserver such as BIND be run on the same machine as Charybdis caching nameserver such as BIND be run on the same machine as Charybdis
and that ``/etc/resolv.conf`` only list 127.0.0.1. and that ``/etc/resolv.conf`` only list ``127.0.0.1``.