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