doc/sgml/oper-guide/config.sgml

   1   <chapter id="config">
   2     <title>Server config file format</title>
   3     <sect1>
   4       <title>General format</title>
   5       <para>
   6         The config file consists of a series of BIND-style blocks. Each block consists of a series
   7         of values inside it which pertain to configuration settings that apply to the given block.
   8       </para>
   9       <para>
  10         Several values take lists of values and have defaults preset inside
  11         them. Prefix a keyword with a tilde (~) to override the default and
  12         disable it.
  13       </para>
  14       <para>
  15         A line may also be a .include directive, which is of the form <synopsis>.include "<replaceable>file</replaceable>"</synopsis>
  16         and causes <replaceable>file</replaceable> to be read in at that point, before the rest of the current file is
  17         processed.
  18         Relative paths are first tried relative to PREFIX and then relative
  19         to ETCPATH (normally PREFIX/etc).
  20       </para>
  21       <para>
  22         Anything from a # to the end of a line is a comment. Blank lines are ignored. C-style comments are also supported.
  23       </para>
  24     </sect1>
  25     <sect1 id="configlines">
  26       <title>Specific blocks and directives</title>
  27       <para>
  28        Not all configuration blocks and directives are listed here, only the most common ones. More blocks and directives will
  29        be documented in later revisions of this manual.
  30       </para>
  31       <sect2>
  32         <title>loadmodule directive</title>
  33         <synopsis>
  34 loadmodule "<replaceable>text</replaceable>";</synopsis>
  35         <para>
  36           Loads a module into the IRCd. In charybdis 1.1, most modules are automatically loaded in. In future versions, it is
  37           intended to remove this behaviour as to allow for easy customization of the IRCd's featureset.
  38         </para>
  39       </sect2>
  40       <sect2>
  41         <title>serverinfo {} block</title>
  42         <synopsis>
  43 serverinfo {
  44         name = "<replaceable>text</replaceable>";
  45         sid = "<replaceable>text</replaceable>";
  46         description = "<replaceable>text</replaceable>";
  47         network_name = "<replaceable>text</replaceable>";
  48         network_desc = "<replaceable>text</replaceable>";
  49         hub = <replaceable>boolean</replaceable>;
  50         vhost = "<replaceable>text</replaceable>";
  51         vhost6 = "<replaceable>text</replaceable>";
  52 };</synopsis>
  53         <para>
  54           The serverinfo {} block defines the core operational parameters of the IRC server.
  55         </para>
  56         <variablelist>
  57           <title>serverinfo {} variables</title>
  58           <varlistentry>
  59             <term>name</term>
  60             <listitem>
  61               <para>
  62                 The name of the IRC server that you are configuring. This
  63                 must contain at least one dot. It is not necessarily equal
  64                 to any DNS name. This must be unique on the IRC network.
  65               </para>
  66             </listitem>
  67           </varlistentry>
  68           <varlistentry>
  69             <term>sid</term>
  70             <listitem>
  71               <para>
  72                 A unique ID which describes the server.
  73                 This consists of one digit and two characters which can be
  74                 digits or letters.
  75               </para>
  76             </listitem>
  77           </varlistentry>
  78           <varlistentry>
  79             <term>description</term>
  80             <listitem>
  81               <para>
  82                 A user-defined field of text which describes the IRC server. This information is used in
  83                 /links and /whois requests. Geographical location information could be a useful use of
  84                 this field, but most administrators put a witty saying inside it instead.
  85               </para>
  86             </listitem>
  87           </varlistentry>
  88           <varlistentry>
  89             <term>network_name</term>
  90             <listitem>
  91               <para>
  92                 The name of the IRC network that this server will be a member of.
  93                 This is used in the welcome message and NETWORK= in 005.
  94               </para>
  95             </listitem>
  96           </varlistentry>
  97           <varlistentry>
  98             <term>network_desc</term>
  99             <listitem>
 100               <para>
 101                 A description of the IRC network that this server will be a member of.
 102                 This is currently unused.
 103               </para>
 104             </listitem>
 105           </varlistentry>
 106           <varlistentry>
 107             <term>hub</term>
 108             <listitem>
 109               <para>
 110                 A boolean which defines whether or not this IRC server will be serving as a hub, i.e. have multiple servers connected to it.
 111               </para>
 112             </listitem>
 113           </varlistentry>
 114           <varlistentry>
 115             <term>vhost</term>
 116             <listitem>
 117               <para>
 118                 An optional text field which defines an IP from which to connect outward to other IRC servers.
 119               </para>
 120             </listitem>
 121           </varlistentry>
 122           <varlistentry>
 123             <term>vhost6</term>
 124             <listitem>
 125               <para>
 126                 An optional text field which defines an IPv6 IP from which to connect outward to other IRC servers.
 127               </para>
 128             </listitem>
 129           </varlistentry>
 130         </variablelist>
 131       </sect2>
 132       <sect2>
 133         <title>admin {} block</title>
 134         <synopsis>
 135 admin {
 136         name = "<replaceable>text</replaceable>";
 137         description = "<replaceable>text</replaceable>";
 138         email = "<replaceable>text</replaceable>";
 139 };</synopsis>
 140         <para>
 141           This block provides the information which is returned by the ADMIN command.
 142         </para>
 143         <variablelist>
 144           <title>admin {} variables</title>
 145           <varlistentry>
 146             <term>name</term>
 147             <listitem>
 148               <para>The name of the administrator running this service.</para>
 149             </listitem>
 150           </varlistentry>
 151           <varlistentry>
 152             <term>description</term>
 153             <listitem>
 154               <para>The description of the administrator's position in the network.</para>
 155             </listitem>
 156           </varlistentry>
 157           <varlistentry>
 158             <term>email</term>
 159             <listitem>
 160               <para>A point of contact for the administrator, usually an e-mail address.</para>
 161             </listitem>
 162           </varlistentry>
 163         </variablelist>
 164       </sect2>
 165       <sect2>
 166         <title>class {} block</title>
 167         <synopsis>
 168 class "<replaceable>name</replaceable>" {
 169         ping_time = <replaceable>duration</replaceable>;
 170         number_per_ident = <replaceable>number</replaceable>;
 171         number_per_ip = <replaceable>number</replaceable>;
 172         number_per_ip_global = <replaceable>number</replaceable>;
 173         cidr_ipv4_bitlen = <replaceable>number</replaceable>;
 174         cidr_ipv6_bitlen = <replaceable>number</replaceable>;
 175         number_per_cidr = <replaceable>number</replaceable>;
 176         max_number = <replaceable>number</replaceable>;
 177         sendq = <replaceable>size</replaceable>;
 178 };</synopsis>
 179         <synopsis>
 180 class "<replaceable>name</replaceable>" {
 181         ping_time = <replaceable>duration</replaceable>;
 182         connectfreq = <replaceable>duration</replaceable>;
 183         max_number = <replaceable>number</replaceable>;
 184         sendq = <replaceable>size</replaceable>;
 185 };</synopsis>
 186         <para>
 187           Class blocks define classes of connections for later use.
 188           The class name is used to connect them to
 189           other blocks in the config file (auth{} and connect{}).
 190           They must be defined before they are used.
 191         </para>
 192         <para>
 193           Classes are used both for client and server connections,
 194           but most variables are different.
 195         </para>
 196         <variablelist>
 197           <title>class {} variables: client classes</title>
 198           <varlistentry>
 199             <term>ping_time</term>
 200             <listitem>
 201               <para>The amount of time between checking pings for clients, e.g.: 2 minutes</para>
 202             </listitem>
 203           </varlistentry>
 204           <varlistentry>
 205             <term>number_per_ident</term>
 206             <listitem>
 207               <para>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.</para>
 208             </listitem>
 209           </varlistentry>
 210           <varlistentry>
 211             <term>number_per_ip</term>
 212             <listitem>
 213               <para>The amount of clients which may be connected from a single IP address.</para>
 214             </listitem>
 215           </varlistentry>
 216           <varlistentry>
 217             <term>number_per_ip_global</term>
 218             <listitem>
 219               <para>The amount of clients which may be connected globally from a single IP address.</para>
 220             </listitem>
 221           </varlistentry>
 222           <varlistentry>
 223             <term>cidr_ipv4_bitlen</term>
 224             <listitem>
 225               <para>The netblock length to use with CIDR-based client limiting for IPv4 users in this class (between 0 and 32).</para>
 226             </listitem>
 227           </varlistentry>
 228           <varlistentry>
 229             <term>cidr_ipv6_bitlen</term>
 230             <listitem>
 231               <para>The netblock length to use with CIDR-based client limiting for IPv6 users in this class (between 0 and 128).</para>
 232             </listitem>
 233           </varlistentry>
 234           <varlistentry>
 235             <term>number_per_cidr</term>
 236             <listitem>
 237               <para>The amount of clients which may be connected from a single netblock.</para>
 238               <para>If this needs to differ between IPv4 and IPv6, make different classes for IPv4 and IPv6 users.</para>
 239             </listitem>
 240           </varlistentry>
 241           <varlistentry>
 242             <term>max_number</term>
 243             <listitem>
 244               <para>The maximum amount of clients which may use this class at any given time.</para>
 245             </listitem>
 246           </varlistentry>
 247           <varlistentry>
 248             <term>sendq</term>
 249             <listitem>
 250               <para>The maximum size of the queue of data to be sent to a client before it is dropped.</para>
 251             </listitem>
 252           </varlistentry>
 253         </variablelist>
 254         <variablelist>
 255           <title>class {} variables: server classes</title>
 256           <varlistentry>
 257             <term>ping_time</term>
 258             <listitem>
 259               <para>The amount of time between checking pings for servers, e.g.: 2 minutes</para>
 260             </listitem>
 261           </varlistentry>
 262           <varlistentry>
 263             <term>connectfreq</term>
 264             <listitem>
 265               <para>The amount of time between autoconnects. This must at least be one minute, as autoconnects are evaluated with that granularity.</para>
 266             </listitem>
 267           </varlistentry>
 268           <varlistentry>
 269             <term>max_number</term>
 270             <listitem>
 271               <para>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</para>
 272             </listitem>
 273           </varlistentry>
 274           <varlistentry>
 275             <term>sendq</term>
 276             <listitem>
 277               <para>The maximum size of the queue of data to be sent to a server before it is dropped.</para>
 278             </listitem>
 279           </varlistentry>
 280         </variablelist>
 281       </sect2>
 282       <sect2>
 283         <title>auth {} block</title>
 284         <synopsis>
 285 auth {
 286         user = "<replaceable>hostmask</replaceable>";
 287         password = "<replaceable>text</replaceable>";
 288         spoof = "<replaceable>text</replaceable>";
 289         flags = <replaceable>list</replaceable>;
 290         class = "<replaceable>text</replaceable>";
 291 };</synopsis>
 292         <para>
 293           auth {} blocks allow client connections to the server, and set various properties concerning those connections.
 294         </para>
 295         <para>
 296           Auth blocks are evaluated from top to bottom in priority, so put special blocks first.
 297         </para>
 298         <variablelist>
 299           <title>auth {} variables</title>
 300           <varlistentry>
 301             <term>user</term>
 302             <listitem>
 303               <para>
 304                 A hostmask (user@host) that the auth {} block applies to.
 305                 It is matched against the hostname and IP address (using ::
 306                 shortening for IPv6 and prepending a 0 if it starts with
 307                 a colon) and can also use CIDR masks.
 308                 You can have multiple user entries.
 309               </para>
 310             </listitem>
 311           </varlistentry>
 312           <varlistentry>
 313             <term>password</term>
 314             <listitem>
 315               <para>
 316                 An optional password to use for authenticating into this auth{}
 317                 block.  If the password is wrong the user will not be able to
 318                 connect (will not fall back on another auth{} block).
 319               </para>
 320             </listitem>
 321           </varlistentry>
 322           <varlistentry>
 323             <term>spoof</term>
 324             <listitem>
 325               <para>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.</para>
 326             </listitem>
 327           </varlistentry>
 328           <varlistentry>
 329             <term>flags</term>
 330             <listitem>
 331               <para>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.</para>
 332             </listitem>
 333           </varlistentry>
 334           <varlistentry>
 335             <term>class</term>
 336             <listitem>
 337               <para>A name of a class to put users matching this auth{} block into.</para>
 338             </listitem>
 339           </varlistentry>
 340         </variablelist>
 341         <variablelist>
 342           <title>auth {} flags</title>
 343           <varlistentry>
 344             <term>encrypted</term>
 345             <listitem>
 346               <para>The password used has been encrypted.</para>
 347             </listitem>
 348           </varlistentry>
 349           <varlistentry>
 350             <term>spoof_notice</term>
 351             <listitem>
 352               <para>Causes the IRCd to send out a server notice when activating a spoof provided by this auth{} block.</para>
 353             </listitem>
 354           </varlistentry>
 355           <varlistentry>
 356             <term>exceed_limit (&gt;)</term>
 357             <listitem>
 358               <para>Users in this auth{} block can exceed class-wide limitations.</para>
 359             </listitem>
 360           </varlistentry>
 361           <varlistentry>
 362             <term>dnsbl_exempt ($)</term>
 363             <listitem>
 364               <para>Users in this auth{} block are exempted from DNS blacklist checks. However, they will still be warned if they are listed.</para>
 365             </listitem>
 366           </varlistentry>
 367           <varlistentry>
 368             <term>kline_exempt (^)</term>
 369             <listitem>
 370               <para>Users in this auth{} block are exempted from DNS blacklists, k:lines and x:lines.</para>
 371             </listitem>
 372           </varlistentry>
 373           <varlistentry>
 374             <term>spambot_exempt</term>
 375             <listitem>
 376               <para>Users in this auth{} block are exempted from spambot checks.</para>
 377             </listitem>
 378           </varlistentry>
 379           <varlistentry>
 380             <term>shide_exempt</term>
 381             <listitem>
 382               <para>Users in this auth{} block are exempted from some serverhiding effects.</para>
 383             </listitem>
 384           </varlistentry>
 385           <varlistentry>
 386             <term>jupe_exempt</term>
 387             <listitem>
 388               <para>Users in this auth{} block do not trigger an alarm when joining juped channels.</para>
 389             </listitem>
 390           </varlistentry>
 391           <varlistentry>
 392             <term>resv_exempt</term>
 393             <listitem>
 394               <para>Users in this auth{} block may use reserved nicknames and channels.</para>
 395               <note><para>The initial nickname may still not be reserved.</para></note>
 396             </listitem>
 397           </varlistentry>
 398           <varlistentry>
 399             <term>flood_exempt (|)</term>
 400             <listitem>
 401               <para>
 402                 Users in this auth{} block may send arbitrary amounts of
 403                 commands per time unit to the server. This does not exempt
 404                 them from any other flood limits.
 405                 You should use this setting with caution.
 406               </para>
 407             </listitem>
 408           </varlistentry>
 409           <varlistentry>
 410             <term>no_tilde (-)</term>
 411             <listitem>
 412               <para>Users in this auth{} block will not have a tilde added to their username if they do not run identd.</para>
 413             </listitem>
 414           </varlistentry>
 415           <varlistentry>
 416             <term>need_ident (+)</term>
 417             <listitem>
 418               <para>Users in this auth{} block must have identd, otherwise they will be rejected.</para>
 419             </listitem>
 420           </varlistentry>
 421           <varlistentry>
 422             <term>need_ssl</term>
 423             <listitem>
 424               <para>Users in this auth{} block must be connected via SSL/TLS, otherwise they will be rejected.</para>
 425             </listitem>
 426           </varlistentry>
 427           <varlistentry>
 428             <term>need_sasl</term>
 429             <listitem>
 430               <para>Users in this auth{} block must identify via SASL, otherwise they will be rejected.</para>
 431             </listitem>
 432           </varlistentry>
 433         </variablelist>
 434       </sect2>
 435       <sect2>
 436         <title>exempt {} block</title>
 437         <synopsis>
 438 exempt {
 439         ip = "<replaceable>ip</replaceable>";
 440 };</synopsis>
 441         <para>
 442           An exempt block specifies IP addresses which are exempt from D:lines
 443           and throttling.
 444           Multiple addresses can be specified in one block.
 445           Clients coming from these addresses can still be K/G/X:lined or
 446           banned by a DNS blacklist unless
 447           they also have appropriate flags in their auth{} block.
 448         </para>
 449         <variablelist>
 450           <title>exempt {} variables</title>
 451           <varlistentry>
 452             <term>ip</term>
 453             <listitem>
 454               <para>The IP address or CIDR range to exempt.</para>
 455             </listitem>
 456           </varlistentry>
 457         </variablelist>
 458       </sect2>
 459       <sect2>
 460         <title>privset {} block</title>
 461         <synopsis>
 462 privset {
 463         extends = "<replaceable>name</replaceable>";
 464         privs = <replaceable>list</replaceable>;
 465 };</synopsis>
 466         <para>
 467           A privset (privilege set) block specifies a set of
 468           operator privileges.
 469         </para>
 470         <variablelist>
 471           <title>privset {} variables</title>
 472           <varlistentry>
 473             <term>extends</term>
 474             <listitem>
 475               <para>An optional privset to inherit. The new privset will have all privileges that the given privset has.</para>
 476             </listitem>
 477           </varlistentry>
 478           <varlistentry>
 479             <term>privs</term>
 480             <listitem>
 481               <para>Privileges to grant to this privset. These are described in the operator privileges section.</para>
 482             </listitem>
 483           </varlistentry>
 484         </variablelist>
 485       </sect2>
 486       <sect2>
 487         <title>operator {} block</title>
 488         <synopsis>
 489 operator "<replaceable>name</replaceable>" {
 490         user = "<replaceable>hostmask</replaceable>";
 491         password = "<replaceable>text</replaceable>";
 492         rsa_public_key_file = "<replaceable>text</replaceable>";
 493         umodes = <replaceable>list</replaceable>;
 494         snomask = "<replaceable>text</replaceable>";
 495         flags = <replaceable>list</replaceable>;
 496 };</synopsis>
 497         <para>
 498           Operator blocks define who may use the OPER command to gain extended privileges.
 499         </para>
 500         <variablelist>
 501           <title>operator {} variables</title>
 502           <varlistentry>
 503             <term>user</term>
 504             <listitem>
 505               <para>
 506                 A hostmask that users trying to use this operator {} block
 507                 must match. This is checked against the original host and IP
 508                 address; CIDR is also supported. So auth {} spoofs work in
 509                 operator {} blocks; the real host behind them is not checked.
 510                 Other kind of spoofs do not work in operator {} blocks; the
 511                 real host behind them is checked.
 512               </para>
 513               <para>
 514                 Note that this is different from charybdis 1.x where all
 515                 kinds of spoofs worked in operator {} blocks.
 516               </para>
 517             </listitem>
 518           </varlistentry>
 519           <varlistentry>
 520             <term>password</term>
 521             <listitem>
 522               <para>
 523                 A password used with the OPER command to use this operator {} block.
 524                 Passwords are encrypted by default, but may be unencrypted if ~encrypted is present
 525                 in the flags list.
 526               </para>
 527             </listitem>
 528           </varlistentry>
 529           <varlistentry>
 530             <term>rsa_public_key_file</term>
 531             <listitem>
 532               <para>
 533                 An optional path to a RSA public key file associated with the operator {} block.
 534                 This information is used by the CHALLENGE command, which is an alternative authentication
 535                 scheme to the traditional OPER command.
 536               </para>
 537             </listitem>
 538           </varlistentry>
 539           <varlistentry>
 540             <term>umodes</term>
 541             <listitem>
 542               <para>A list of usermodes to apply to successfully opered clients.</para>
 543             </listitem>
 544           </varlistentry>
 545           <varlistentry>
 546             <term>snomask</term>
 547             <listitem>
 548               <para>
 549                 An snomask to apply to successfully opered clients.
 550               </para>
 551             </listitem>
 552           </varlistentry>
 553           <varlistentry>
 554             <term>privset</term>
 555             <listitem>
 556               <para>
 557                 The privilege set granted to successfully opered clients.
 558                 This must be defined before this operator{} block.
 559               </para>
 560             </listitem>
 561           </varlistentry>
 562           <varlistentry>
 563             <term>flags</term>
 564             <listitem>
 565               <para>A list of flags to apply to this operator{} block. They are listed below.</para>
 566             </listitem>
 567           </varlistentry>
 568         </variablelist>
 569         <variablelist>
 570           <title>operator {} flags</title>
 571           <varlistentry>
 572             <term>encrypted</term>
 573             <listitem>
 574               <para>The password used has been encrypted. This is enabled by default, use ~encrypted to disable it.</para>
 575             </listitem>
 576           </varlistentry>
 577           <varlistentry>
 578             <term>need_ssl</term>
 579             <listitem>
 580               <para>Restricts use of this operator{} block to SSL/TLS connections only.</para>
 581             </listitem>
 582           </varlistentry>
 583         </variablelist>
 584       </sect2>
 585       <sect2>
 586         <title>connect {} block</title>
 587         <synopsis>
 588 connect "<replaceable>name</replaceable>" {
 589         host = "<replaceable>text</replaceable>";
 590         send_password = "<replaceable>text</replaceable>";
 591         accept_password = "<replaceable>text</replaceable>";
 592         port = <replaceable>number</replaceable>;
 593         hub_mask = "<replaceable>mask</replaceable>";
 594         leaf_mask = "<replaceable>mask</replaceable>";
 595         class = "<replaceable>text</replaceable>";
 596         flags = <replaceable>list</replaceable>;
 597         aftype = <replaceable>protocol</replaceable>;
 598 };</synopsis>
 599         <para>
 600           Connect blocks define what servers may connect or be connected to.
 601         </para>
 602         <variablelist>
 603           <title>connect {} variables</title>
 604           <varlistentry>
 605             <term>host</term>
 606             <listitem>
 607               <para>The hostname or IP to connect to.</para>
 608               <note><para>
 609                 Furthermore, if a hostname is used, it must have an A or AAAA
 610                 record (no CNAME) and it must be the primary
 611                 hostname for inbound connections to work.
 612               </para><para>
 613                 IPv6 addresses must be in :: shortened form; addresses which
 614                 then start with a colon must be prepended with a zero,
 615                 for example 0::1.
 616               </para></note>
 617             </listitem>
 618           </varlistentry>
 619           <varlistentry>
 620             <term>send_password</term>
 621             <listitem>
 622               <para>The password to send to the other server.</para>
 623             </listitem>
 624           </varlistentry>
 625           <varlistentry>
 626             <term>accept_password</term>
 627             <listitem>
 628               <para>The password that should be accepted from the other server.</para>
 629             </listitem>
 630           </varlistentry>
 631           <varlistentry>
 632             <term>port</term>
 633             <listitem>
 634               <para>The port on the other server to connect to.</para>
 635             </listitem>
 636           </varlistentry>
 637           <varlistentry>
 638             <term>hub_mask</term>
 639             <listitem>
 640               <para>
 641                 An optional domain mask of servers allowed to be introduced
 642                 by this link. Usually, "*" is fine. Multiple hub_masks may be
 643                 specified, and any of them may be introduced.
 644                 Violation of hub_mask and leaf_mask restrictions will
 645                 cause the local link to be closed.
 646               </para>
 647             </listitem>
 648           </varlistentry>
 649           <varlistentry>
 650             <term>leaf_mask</term>
 651             <listitem>
 652               <para>
 653                 An optional domain mask of servers not allowed to be
 654                 introduced by this link. Multiple leaf_masks may be specified,
 655                 and none of them may be introduced. leaf_mask has priority
 656                 over hub_mask.
 657               </para>
 658             </listitem>
 659           </varlistentry>
 660           <varlistentry>
 661             <term>class</term>
 662             <listitem>
 663               <para>The name of the class this server should be placed into.</para>
 664             </listitem>
 665           </varlistentry>
 666           <varlistentry>
 667             <term>flags</term>
 668             <listitem>
 669               <para>A list of flags concerning the connect block. They are listed below.</para>
 670             </listitem>
 671           </varlistentry>
 672           <varlistentry>
 673             <term>aftype</term>
 674             <listitem>
 675               <para>The protocol that should be used to connect with, either ipv4 or ipv6. This defaults to ipv4 unless host is a numeric IPv6 address.</para>
 676             </listitem>
 677           </varlistentry>
 678         </variablelist>
 679         <variablelist>
 680           <title>connect {} flags</title>
 681           <varlistentry>
 682             <term>encrypted</term>
 683             <listitem>
 684               <para>The value for accept_password has been encrypted.</para>
 685             </listitem>
 686           </varlistentry>
 687           <varlistentry>
 688             <term>autoconn</term>
 689             <listitem>
 690               <para>
 691                 The server should automatically try to connect to the server defined in this
 692                 connect {} block if it's not connected already and max_number
 693                 in the class is not reached yet.
 694               </para>
 695             </listitem>
 696           </varlistentry>
 697           <varlistentry>
 698             <term>compressed</term>
 699             <listitem>
 700               <para>Ziplinks should be used with this server connection.
 701               This compresses traffic using zlib, saving some bandwidth
 702               and speeding up netbursts.</para>
 703               <para>If you have trouble setting up a link, you should
 704               turn this off as it often hides error messages.</para>
 705             </listitem>
 706           </varlistentry>
 707           <varlistentry>
 708             <term>topicburst</term>
 709             <listitem>
 710               <para>Topics should be bursted to this server.</para>
 711               <para>This is enabled by default.</para>
 712             </listitem>
 713           </varlistentry>
 714         </variablelist>
 715       </sect2>
 716       <sect2>
 717         <title>listen {} block</title>
 718         <synopsis>
 719 listen {
 720         host = "<replaceable>text</replaceable>";
 721         port = <replaceable>number</replaceable>;
 722 };</synopsis>
 723         <para>
 724           A listen block specifies what ports a server should listen on.
 725         </para>
 726         <variablelist>
 727           <title>listen {} variables</title>
 728           <varlistentry>
 729             <term>host</term>
 730             <listitem>
 731               <para>An optional host to bind to. Otherwise, the ircd will listen on all available hosts.</para>
 732             </listitem>
 733           </varlistentry>
 734           <varlistentry>
 735             <term>port</term>
 736             <listitem>
 737               <para>
 738                 A port to listen on. You can specify multiple ports via commas, and define a range by seperating
 739                 the start and end ports with two dots (..).
 740               </para>
 741             </listitem>
 742           </varlistentry>
 743         </variablelist>
 744       </sect2>
 745       <sect2>
 746         <title>modules {} block</title>
 747         <synopsis>
 748 modules {
 749         path = "<replaceable>text</replaceable>";
 750         module = <replaceable>text</replaceable>;
 751 };</synopsis>
 752         <para>
 753           The modules block specifies information for loadable modules.
 754         </para>
 755         <variablelist>
 756           <title>modules {} variables</title>
 757           <varlistentry>
 758             <term>path</term>
 759             <listitem>
 760               <para>Specifies a path to search for loadable modules.</para>
 761             </listitem>
 762           </varlistentry>
 763           <varlistentry>
 764             <term>module</term>
 765             <listitem>
 766               <para>
 767                 Specifies a module to load, similar to loadmodule.
 768               </para>
 769             </listitem>
 770           </varlistentry>
 771         </variablelist>
 772       </sect2>
 773       <sect2>
 774         <title>general {} block</title>
 775         <synopsis>
 776 modules {
 777         <replaceable>values</replaceable>
 778 };</synopsis>
 779         <para>
 780           The general block specifies a variety of options, many of which
 781           were in <filename>config.h</filename> in older daemons.
 782           The options are documented in <filename>reference.conf</filename>.
 783         </para>
 784       </sect2>
 785       <sect2>
 786         <title>channel {} block</title>
 787         <synopsis>
 788 modules {
 789         <replaceable>values</replaceable>
 790 };</synopsis>
 791         <para>
 792           The channel block specifies a variety of channel-related options,
 793           many of which were in <filename>config.h</filename> in older daemons.
 794           The options are documented in <filename>reference.conf</filename>.
 795         </para>
 796       </sect2>
 797       <sect2>
 798         <title>serverhide {} block</title>
 799         <synopsis>
 800 modules {
 801         <replaceable>values</replaceable>
 802 };</synopsis>
 803         <para>
 804           The serverhide block specifies options related to server hiding.
 805           The options are documented in <filename>reference.conf</filename>.
 806         </para>
 807       </sect2>
 808       <sect2>
 809         <title>blacklist {} block</title>
 810         <synopsis>
 811 blacklist {
 812         host = "<replaceable>text</replaceable>";
 813         reject_reason = "<replaceable>text</replaceable>";
 814 };</synopsis>
 815         <para>
 816           The blacklist block specifies DNS blacklists to check.
 817           Listed clients will not be allowed to connect.
 818           IPv6 clients are not checked against these.
 819         </para>
 820         <para>
 821           Multiple blacklists can be specified, in pairs with first host
 822           then reject_reason.
 823         </para>
 824         <variablelist>
 825           <title>blacklist {} variables</title>
 826           <varlistentry>
 827             <term>host</term>
 828             <listitem>
 829               <para>The DNSBL to use.</para>
 830             </listitem>
 831           </varlistentry>
 832           <varlistentry>
 833             <term>reject_reason</term>
 834             <listitem>
 835               <para>The reason to send to listed clients when disconnecting them.</para>
 836             </listitem>
 837           </varlistentry>
 838         </variablelist>
 839       </sect2>
 840       <sect2>
 841         <title>alias {} block</title>
 842         <synopsis>
 843 alias "<replaceable>name</replaceable>" {
 844         target = "<replaceable>text</replaceable>";
 845 };</synopsis>
 846         <para>
 847           Alias blocks allow the definition of custom commands.
 848           These commands send PRIVMSG to the given target. A real
 849           command takes precedence above an alias.
 850         </para>
 851         <variablelist>
 852           <title>alias {} variables</title>
 853           <varlistentry>
 854             <term>target</term>
 855             <listitem>
 856               <para>
 857                 The target nick (must be a network service (umode +S)) or
 858                 user@server.
 859                 In the latter case, the server cannot be this server,
 860                 only opers can use user starting with "opers" reliably and
 861                 the user is interpreted on the target server only
 862                 so you may need to use nick@server instead).
 863               </para>
 864             </listitem>
 865           </varlistentry>
 866         </variablelist>
 867       </sect2>
 868       <sect2>
 869         <title>cluster {} block</title>
 870         <synopsis>
 871 cluster {
 872         name = "<replaceable>text</replaceable>";
 873         flags = <replaceable>list</replaceable>;
 874 };</synopsis>
 875         <para>
 876           The cluster block specifies servers we propagate things to
 877           automatically.
 878           This does not allow them to set bans, you need a separate shared{}
 879           block for that.
 880         </para>
 881         <para>
 882           Having overlapping cluster{} items will cause the command to
 883           be executed twice on the target servers. This is particularly
 884           undesirable for ban removals.
 885         </para>
 886         <para>
 887           The letters in parentheses denote the flags in /stats U.
 888         </para>
 889         <variablelist>
 890           <title>cluster {} variables</title>
 891           <varlistentry>
 892             <term>name</term>
 893             <listitem>
 894               <para>The server name to share with, this may contain wildcards
 895               and may be stacked.</para>
 896             </listitem>
 897           </varlistentry>
 898           <varlistentry>
 899             <term>flags</term>
 900             <listitem>
 901               <para>The list of what to share, all the name lines above this
 902               (up to another flags entry) will receive these flags.
 903               They are listed below.</para>
 904             </listitem>
 905           </varlistentry>
 906         </variablelist>
 907         <variablelist>
 908           <title>cluster {} flags</title>
 909           <varlistentry>
 910             <term>kline (K)</term>
 911             <listitem>
 912               <para>Permanent K:lines</para>
 913             </listitem>
 914           </varlistentry>
 915           <varlistentry>
 916             <term>tkline (k)</term>
 917             <listitem>
 918               <para>Temporary K:lines</para>
 919             </listitem>
 920           </varlistentry>
 921           <varlistentry>
 922             <term>unkline (U)</term>
 923             <listitem>
 924               <para>K:line removals</para>
 925             </listitem>
 926           </varlistentry>
 927           <varlistentry>
 928             <term>xline (X)</term>
 929             <listitem>
 930               <para>Permanent X:lines</para>
 931             </listitem>
 932           </varlistentry>
 933           <varlistentry>
 934             <term>txline (x)</term>
 935             <listitem>
 936               <para>Temporary X:lines</para>
 937             </listitem>
 938           </varlistentry>
 939           <varlistentry>
 940             <term>unxline (Y)</term>
 941             <listitem>
 942               <para>X:line removals</para>
 943             </listitem>
 944           </varlistentry>
 945           <varlistentry>
 946             <term>resv (Q)</term>
 947             <listitem>
 948               <para>Permanently reserved nicks/channels</para>
 949             </listitem>
 950           </varlistentry>
 951           <varlistentry>
 952             <term>tresv (q)</term>
 953             <listitem>
 954               <para>Temporarily reserved nicks/channels</para>
 955             </listitem>
 956           </varlistentry>
 957           <varlistentry>
 958             <term>unresv (R)</term>
 959             <listitem>
 960               <para>RESV removals</para>
 961             </listitem>
 962           </varlistentry>
 963           <varlistentry>
 964             <term>locops (L)</term>
 965             <listitem>
 966               <para>LOCOPS messages (sharing this with * makes LOCOPS rather
 967               similar to OPERWALL which is not useful)</para>
 968             </listitem>
 969           </varlistentry>
 970           <varlistentry>
 971             <term>all</term>
 972             <listitem>
 973               <para>All of the above</para>
 974             </listitem>
 975           </varlistentry>
 976         </variablelist>
 977       </sect2>
 978       <sect2>
 979         <title>shared {} block</title>
 980         <synopsis>
 981 shared {
 982         oper = "<replaceable>user@host</replaceable>", "<replaceable>server</replaceable>";
 983         flags = <replaceable>list</replaceable>;
 984 };</synopsis>
 985         <para>
 986           The shared block specifies opers allowed to perform certain actions
 987           on our server remotely.
 988           These are ordered top down. The first one matching will determine
 989           the oper's access.
 990           If access is denied, the command will be silently ignored.
 991         </para>
 992         <para>
 993           The letters in parentheses denote the flags in /stats U.
 994         </para>
 995         <variablelist>
 996           <title>shared {} variables</title>
 997           <varlistentry>
 998             <term>oper</term>
 999             <listitem>
1000               <para>The user@host the oper must have, and the server they must
1001               be on. This may contain wildcards.</para>
1002             </listitem>
1003           </varlistentry>
1004           <varlistentry>
1005             <term>flags</term>
1006             <listitem>
1007               <para>The list of what to allow, all the oper lines above this
1008               (up to another flags entry) will receive these flags.
1009               They are listed below.</para>
1010             </listitem>
1011           </varlistentry>
1012         </variablelist>
1013         <note><para>
1014           While they have the same names, the flags have subtly different
1015           meanings from those in the cluster{} block.
1016         </para></note>
1017         <variablelist>
1018           <title>shared {} flags</title>
1019           <varlistentry>
1020             <term>kline (K)</term>
1021             <listitem>
1022               <para>Permanent and temporary K:lines</para>
1023             </listitem>
1024           </varlistentry>
1025           <varlistentry>
1026             <term>tkline (k)</term>
1027             <listitem>
1028               <para>Temporary K:lines</para>
1029             </listitem>
1030           </varlistentry>
1031           <varlistentry>
1032             <term>unkline (U)</term>
1033             <listitem>
1034               <para>K:line removals</para>
1035             </listitem>
1036           </varlistentry>
1037           <varlistentry>
1038             <term>xline (X)</term>
1039             <listitem>
1040               <para>Permanent and temporary X:lines</para>
1041             </listitem>
1042           </varlistentry>
1043           <varlistentry>
1044             <term>txline (x)</term>
1045             <listitem>
1046               <para>Temporary X:lines</para>
1047             </listitem>
1048           </varlistentry>
1049           <varlistentry>
1050             <term>unxline (Y)</term>
1051             <listitem>
1052               <para>X:line removals</para>
1053             </listitem>
1054           </varlistentry>
1055           <varlistentry>
1056             <term>resv (Q)</term>
1057             <listitem>
1058               <para>Permanently and temporarily reserved nicks/channels</para>
1059             </listitem>
1060           </varlistentry>
1061           <varlistentry>
1062             <term>tresv (q)</term>
1063             <listitem>
1064               <para>Temporarily reserved nicks/channels</para>
1065             </listitem>
1066           </varlistentry>
1067           <varlistentry>
1068             <term>unresv (R)</term>
1069             <listitem>
1070               <para>RESV removals</para>
1071             </listitem>
1072           </varlistentry>
1073           <varlistentry>
1074             <term>all</term>
1075             <listitem>
1076               <para>All of the above; this does not include locops, rehash, dline, tdline or undline.</para>
1077             </listitem>
1078           </varlistentry>
1079           <varlistentry>
1080             <term>locops (L)</term>
1081             <listitem>
1082               <para>LOCOPS messages (accepting this from * makes LOCOPS rather
1083               similar to OPERWALL which is not useful); unlike the other flags,
1084               this can only be accepted from *@* although it can be
1085               restricted based on source server.</para>
1086             </listitem>
1087           </varlistentry>
1088           <varlistentry>
1089             <term>rehash (H)</term>
1090             <listitem>
1091               <para>REHASH commands; all options can be used</para>
1092             </listitem>
1093           </varlistentry>
1094           <varlistentry>
1095             <term>dline (D)</term>
1096             <listitem>
1097               <para>Permanent and temporary D:lines</para>
1098             </listitem>
1099           </varlistentry>
1100           <varlistentry>
1101             <term>tdline (d)</term>
1102             <listitem>
1103               <para>Temporary D:lines</para>
1104             </listitem>
1105           </varlistentry>
1106           <varlistentry>
1107             <term>undline (E)</term>
1108             <listitem>
1109               <para>D:line removals</para>
1110             </listitem>
1111           </varlistentry>
1112           <varlistentry>
1113             <term>none</term>
1114             <listitem>
1115               <para>Allow nothing to be done</para>
1116             </listitem>
1117           </varlistentry>
1118         </variablelist>
1119       </sect2>
1120       <sect2>
1121         <title>service {} block</title>
1122         <synopsis>
1123 service {
1124         name = "<replaceable>text</replaceable>";
1125 };</synopsis>
1126         <para>
1127           The service block specifies privileged servers (services). These
1128           servers have extra privileges such as setting login names on users
1129           and introducing clients with umode +S (unkickable, hide channels, etc).
1130           This does not allow them to set bans, you need a separate shared{}
1131           block for that.
1132         </para>
1133         <para>
1134           Do not place normal servers here.
1135         </para>
1136         <para>
1137           Multiple names may be specified but there may be only one service{}
1138           block.
1139         </para>
1140         <variablelist>
1141           <title>service {} variables</title>
1142           <varlistentry>
1143             <term>name</term>
1144             <listitem>
1145               <para>The server name to grant special privileges. This may not
1146               contain wildcards.</para>
1147             </listitem>
1148           </varlistentry>
1149         </variablelist>
1150       </sect2>
1151     </sect1>
1152     <sect1>
1153       <title>Hostname resolution (DNS)</title>
1154       <para>
1155         Charybdis uses solely DNS for all hostname/address lookups
1156         (no <filename>/etc/hosts</filename> or anything else).
1157         The DNS servers are taken from <filename>/etc/resolv.conf</filename>.
1158         If this file does not exist or no valid IP addresses are listed in it,
1159         the local host (127.0.0.1) is used. (Note that the latter part
1160         did not work in older versions of Charybdis.)
1161       </para>
1162       <para>
1163         IPv4 as well as IPv6 DNS servers are supported, but it is not
1164         possible to use both IPv4 and IPv6 in
1165         <filename>/etc/resolv.conf</filename>.
1166       </para>
1167       <para>
1168         For both security and performance reasons, it is recommended
1169         that a caching nameserver such as BIND be run on the same machine
1170         as Charybdis and that <filename>/etc/resolv.conf</filename> only
1171         list 127.0.0.1.
1172       </para>
1173     </sect1>
1174   </chapter>
1175 <!-- Keep this comment at the end of the file
1176 Local variables:
1177 mode: sgml
1178 sgml-omittag:t
1179 sgml-shorttag:t
1180 sgml-namecase-general:t
1181 sgml-general-insert-case:lower
1182 sgml-minimize-attributes:nil
1183 sgml-always-quote-attributes:t
1184 sgml-indent-step:2
1185 sgml-indent-data:t
1186 sgml-parent-document: ("dancer-oper-guide.sgml" "book")
1187 sgml-exposed-tags:nil
1188 fill-column:105
1189 sgml-validate-command: "nsgmls -e -g -s -u dancer-oper-guide.sgml"
1190 End:
1191 -->