From 3ab6c85284b6b6ba9eae8ee30cadcc545bf02178 Mon Sep 17 00:00:00 2001 From: Alexander Barton Date: Sun, 21 Jan 2024 02:56:23 +0100 Subject: [PATCH] Add an introduction and generic info to doc/QuickStart.md --- README.md | 5 +++-- doc/QuickStart.md | 51 ++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 51 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5a20d548..437ebb68 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,9 @@ and included in the package repositories of various operating systems. The **homepage** of the ngIRCd project is . Installation of ngIRCd is described in the file `INSTALL.md` in the source -directory; please see the file `doc/QuickStart.md` in the `doc/` directory for -some configuration examples. +directory; please see the file `doc/QuickStart.md` in the `doc/` directory or +[online](https://ngircd.barton.de/doc/QuickStart.md) for some real-world +configuration examples. More documentation can be found in the `doc/` directory and [online](https://ngircd.barton.de/documentation). diff --git a/doc/QuickStart.md b/doc/QuickStart.md index b9b846b4..d2e23568 100644 --- a/doc/QuickStart.md +++ b/doc/QuickStart.md @@ -3,14 +3,59 @@ This *Quick Start* document explains how to configure ngIRCd, the lightweight Internet Relay Chat (IRC) server, using some "real world" scenarios. +## Introduction + +The ngIRCd daemon can be run without any configuration file using built-in +defaults. These defaults are probably sufficient for very simple single-node +setups, but most probably need further tweaking for more "advanced" setups. + +You can check the current settings by running `ngircd --configtest`. This +command not only shows the settings, it shows error, warning and hits, if it +detects any. + +Therefore it is definitely best practice to *always run this check* after +making any changes to the configuration file(s) and double-check that +everything was parsed as expected! + +### Configuration File and Drop-in Directory + +The `ngircd --configtest` command shows the name of the default configuration +file, too. For example `/etc/ngircd/ngircd.conf`. + +In addition, ngIRCd supports further configuration file snippets in a "drop-in" +directory which is configured with the `IncludeDir` variable in the `[Options]` +section and has a built-in default value (like `/etc/ngircd/ngircd.conf.d/`). +All configuration files must match `*.conf`. + +It is a good idea to not edit a default `ngircd.conf` file but to create one +ore more new files in this include directory, overriding the defaults as +needed. This way you don't get any clashes when updating ngIRCd to newer +releases. + +## Configuration File Syntax + +The configuration consists of sections and parameters. + +A section begins with the name of the section in square brackets (like +`[Example]`) and continues until the next section begins. Sections contain +parameters of the form `name = value`. + +Section and parameter names are not case sensitive. + +Please see the `ngircd.conf`(5) manual page for an in-depth description of the +configuration file, its syntax and all supported configuration options. + ## Simple Single-Instance Server -ngIRCd needs at least a valid IRC server name configured, therefore the -simplest configuration file looks like this: +A good starting point is to configure a valid (and unique!) IRC server name +(which is *not* related to a host name, it is purely a unique *server ID* that +must contain at least one dot "."). + +This looks like this: ``` ini [Global] -Name = irc.example.net +Name = my.irc.server ``` This results in the following *warning* in the logs when starting the daemon: -- 2.39.2