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 hints, 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 After installing ngIRCd, a sample configuration file should have been set up if
  23 none existed already. By default, when installing from sources, the file is
  24 named `/usr/local/etc/ngircd.conf` (other common names, especially for
  25 distribution packages, are `/etc/ngircd.conf` or `/etc/ngircd/ngircd.conf`).
  26 Run the command `ngircd --configtest` to check the name of the configuration
  27 file which is used by default on your local system.
  28
  29 In addition, ngIRCd supports configuration file snippets in a "drop-in"
  30 directory which is configured with the `IncludeDir` variable in the `[Options]`
  31 section and has a built-in default value (like `/etc/ngircd/ngircd.conf.d/`).
  32 All configuration files matching the `*.conf` pattern are read-in from this
  33 directory after the main `ngircd.conf` file.
  34
  35 It is a good idea to not edit the default `ngircd.conf` file but to create one
  36 ore more new files in this include directory, overriding the defaults as
  37 needed. This way you don't get any clashes when updating ngIRCd to newer
  38 releases.
  39
  40 You can find the template of the sample configuration file in the `doc/`
  41 directory as `sample-ngircd.conf` and
  42 [online](https://ngircd.barton.de/doc/sample-ngircd.conf) on the homepage. It
  43 contains all available options.
  44
  45 ## Configuration File Syntax
  46
  47 The configuration consists of sections and parameters.
  48
  49 A section begins with the name of the section in square brackets (like
  50 `[Example]`) and continues until the next section begins. Sections contain
  51 parameters of the form `name = value`.
  52
  53 Section and parameter names are not case sensitive.
  54
  55 Please see the `ngircd.conf`(5) manual page for an in-depth description of the
  56 configuration file, its syntax and all supported configuration options.
  57
  58 The sample configuration file uses comments beginning with `#` *or* `;` -- this
  59 is only for the better understanding of the file, both comment styles are
  60 equal. The lines commented out with `;` show example or default settings,
  61 whereas the lines using `#` are descriptions of the options.
  62
  63 ## Simple Single-Instance Server
  64
  65 A good starting point is to configure a valid (and unique!) IRC server name
  66 (which is *not* related to a host name, it is purely a unique *server ID* that
  67 must contain at least one dot ".").
  68
  69 This looks like this:
  70
  71 ``` ini
  72 [Global]
  73 Name = my.irc.server
  74 ```
  75
  76 This results in the following *warning* in the logs when starting the daemon:
  77 `No administrative information configured but required by RFC!` -- which works,
  78 but is a bit ugly. So let's fix that by adding some *admin info*:
  79
  80 ``` ini
  81 [Global]
  82 Name = irc.example.net
  83 AdminInfo1 = Example IRC Server
  84 AdminInfo2 = Anywhere On Earth
  85 AdminEMail = admin@irc.example.net
  86 ```
  87
  88 *Please Note*: The server `Name` looks like a DNS host name, but it is not: in
  89 fact it is not related to your server's fully qualified domain name (FQDN) in
  90 any way and can be an arbitrary string -- but it *must* contain at least
  91 one dot (".") character!
  92
  93 ## Add a Local IRC Operator
  94
  95 Some IRC commands, like `REHASH` which reloads the server configuration on the
  96 fly, require the user to authenticate to the daemon to become an *IRC
  97 Operator* first.
  98
  99 So let's configure an *Operator* account in the configuration file (in
 100 addition to what we configured above):
 101
 102 ``` ini
 103 [Operator]
 104 # ID of the operator (may be different of the nickname)
 105 Name = BigOp
 106 # Password of the IRC operator
 107 Password = secret
 108 # Optional Mask from which /OPER will be accepted
 109 ;Mask = *!ident@somewhere.example.com
 110 ```
 111
 112 Now you can use the IRC command `OPER BigOp secret` to get *IRC Operator*
 113 status on that server.
 114
 115 Please choose a sensible password, and keep in mind that the *name* is not
 116 related to the *nickname* used by the user at all!
 117
 118 We don't make use of the `Mask` setting in the example above (commented out
 119 with the `;` character), but it is a good idea to enable it whenever possible!
 120
 121 And you can have as many *Operator blocks* as you like, configuring multiple
 122 different IRC Operators.