doc/QuickStart.md

   1 # [ngIRCd](https://ngircd.barton.de) - Quick Start
   2
   3 This *Quick Start* document explains how to configure ngIRCd, the lightweight
   4 Internet Relay Chat (IRC) server, using some "real world" scenarios.
   5
   6 ## Introduction
   7
   8 The ngIRCd daemon can be run without any configuration file using built-in
   9 defaults. These defaults are probably sufficient for very simple single-node
  10 setups, but most probably need further tweaking for more "advanced" setups.
  11
  12 You can check the current settings by running `ngircd --configtest`. This
  13 command not only shows the settings, it shows error, warning and hits, if it
  14 detects any.
  15
  16 Therefore it is definitely best practice to *always run this check* after
  17 making any changes to the configuration file(s) and double-check that
  18 everything was parsed as expected!
  19
  20 ### Configuration File and Drop-in Directory
  21
  22 The `ngircd --configtest` command shows the name of the default configuration
  23 file, too. For example `/etc/ngircd/ngircd.conf`.
  24
  25 In addition, ngIRCd supports further configuration file snippets in a "drop-in"
  26 directory which is configured with the `IncludeDir` variable in the `[Options]`
  27 section and has a built-in default value (like `/etc/ngircd/ngircd.conf.d/`).
  28 All configuration files must match `*.conf`.
  29
  30 It is a good idea to not edit a default `ngircd.conf` file but to create one
  31 ore more new files in this include directory, overriding the defaults as
  32 needed. This way you don't get any clashes when updating ngIRCd to newer
  33 releases.
  34
  35 ## Configuration File Syntax
  36
  37 The configuration consists of sections and parameters.
  38
  39 A section begins with the name of the section in square brackets (like
  40 `[Example]`) and continues until the next section begins. Sections contain
  41 parameters of the form `name = value`.
  42
  43 Section and parameter names are not case sensitive.
  44
  45 Please see the `ngircd.conf`(5) manual page for an in-depth description of the
  46 configuration file, its syntax and all supported configuration options.
  47
  48 ## Simple Single-Instance Server
  49
  50 A good starting point is to configure a valid (and unique!) IRC server name
  51 (which is *not* related to a host name, it is purely a unique *server ID* that
  52 must contain at least one dot ".").
  53
  54 This looks like this:
  55
  56 ``` ini
  57 [Global]
  58 Name = my.irc.server
  59 ```
  60
  61 This results in the following *warning* in the logs when starting the daemon:
  62 `No administrative information configured but required by RFC!` -- which works,
  63 but is a bit ugly. So let's fix that by adding some *admin info*:
  64
  65 ``` ini
  66 [Global]
  67 Name = irc.example.net
  68 AdminInfo1 = Example IRC Server
  69 AdminInfo2 = Anywhere On Earth
  70 AdminEMail = admin@irc.example.net
  71 ```
  72
  73 *Please Note*: The server `Name` looks like a DNS host name, but it is not: in
  74 fact it is not related to your server's fully qualified domain name (FQDN) in
  75 any way and can be an arbitrary string -- but it *must* contain at least
  76 one dot (".") character!
  77
  78 ## Add a Local IRC Operator
  79
  80 Some IRC commands, like `REHASH` which reloads the server configuration on the
  81 fly, require the user to authenticate to the daemon to become an *IRC
  82 Operator* first.
  83
  84 So let's configure an *Operator* account in the configuration file (in
  85 addition to what we configured above):
  86
  87 ``` ini
  88 [Operator]
  89 # ID of the operator (may be different of the nickname)
  90 Name = BigOp
  91 # Password of the IRC operator
  92 Password = secret
  93 # Optional Mask from which /OPER will be accepted
  94 ;Mask = *!ident@somewhere.example.com
  95 ```
  96
  97 Now you can use the IRC command `OPER BigOp secret` to get *IRC Operator*
  98 status on that server.
  99
 100 Please choose a sensible password, and keep in mind that the *name* is not
 101 related to the *nickname* used by the user at all!
 102
 103 We don't make use of the `Mask` setting in the example above (commented out
 104 with the `;` character), but it is a good idea to enable it whenever possible!
 105
 106 And you can have as many *Operator blocks* as you like, configuring multiple
 107 different IRC Operators.