Enhance documentation a bit, add doc/QuickStart.md

And this file could well be expanded!

diff --git a/INSTALL.md b/INSTALL.md
index 56c7cc52352f68aea6e9086205d59745a9a37198..b5ad20edc6b473e7b1eacdcf436a2e72ffa2962f 100644 (file)
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,7 +1,7 @@
 # [ngIRCd](https://ngircd.barton.de) - Internet Relay Chat Server
 
-This document explains how to install ngIRCd, the lightweight Internet Relay
-Chat (IRC) server.
+This document explains how to install and configure ngIRCd, the lightweight
+Internet Relay Chat (IRC) server.
 
 The first section lists noteworthy changes to earlier releases; you definitely
 should read this when upgrading your setup! But you can skip over this section
@@ -10,6 +10,10 @@ when you do a fresh installation.
 All the subsequent sections describe the steps required to install and
 configure ngIRCd.
 
+Please see the file `doc/QuickStart.md` in the `doc/` directory and
+[online](https://ngircd.barton.de/doc/QuickStart.md) on the homepage for some
+configuration examples.
+
 ## Upgrade Information
 
 Differences to version 25
@@ -361,6 +365,10 @@ Please have a look at the `ngircd(8)` and `ngircd.conf(5)` manual pages for
 details and all possible command line and configuration options -- **and don't
 forget to run `ngircd --configtest` to validate your configuration file!**
 
+The file `doc/QuickStart.md` in the `doc/` directory and
+[online](https://ngircd.barton.de/doc/QuickStart.md) on the homepage has some
+configuration examples, you should take a look :-)
+
 After installing ngIRCd, a sample configuration file will be set up (if it
 does not exist already). By default, when installing from sources, the file is
 named `/usr/local/etc/ngircd.conf` (other common names, especially for

diff --git a/README.md b/README.md
index f0856d7f3338122ee07b59e65ea5efcf31912ca6..f576481f178b86d2438e1ca5287e50e6937bb1e5 100644 (file)
--- a/README.md
+++ b/README.md
@@ -47,6 +47,10 @@ specified by the RFCs that are used by existing clients.
 
 The **homepage** of the ngIRCd project is <https://ngircd.barton.de>.
 
+Installation on 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.
+
 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
new file mode 100644 (file)
index 0000000..ff1f2aa
--- /dev/null
+++ b/doc/QuickStart.md
@@ -0,0 +1,62 @@
+# [ngIRCd](https://ngircd.barton.de) - Internet Relay Chat Server
+
+This *Quick Start* document explains how to configure ngIRCd, the lightweight
+Internet Relay Chat (IRC) server, using some "real world" scenarios.
+
+## Simple Single-Instance Server
+
+ngIRCd needs at least a valid IRC server name configured, therefore the
+simplest configuration file looks like this:
+
+``` ini
+[Global]
+Name = irc.example.net
+````
+
+This results in the following *warning* in the logs when starting the daemon:
+`No administrative information configured but required by RFC!` -- which works,
+but is a bit ugly. So let's fix that by adding some *admin info*:
+
+``` ini
+[Global]
+Name = irc.example.net
+AdminInfo1 = Example IRC Server
+AdminInfo2 = Anywhere On Earth
+AdminEMail = admin@irc.example.net
+```
+
+*Please Note*: The server `Name` looks like a DNS host name, but it is not: in
+fact it is not related to your server's fully qualified domain name (FQDN) in
+any way and can be an arbitrary string -- but which *must* contain at least
+one dot (".") character!
+
+## Add a Local IRC Operator
+
+Some IRC commands, like `REHASH` which reloads the server configuration on the
+fly, require the user to authenticate to the daemon to become an *IRC
+Operator* first.
+
+So let's configure an *Operator* account in the configuration file (in
+addition to what we configured above):
+
+``` ini
+[Operator]
+# ID of the operator (may be different of the nickname)
+Name = BigOp
+# Password of the IRC operator
+Password = secret
+# Optional Mask from which /OPER will be accepted
+;Mask = *!ident@somewhere.example.com
+```
+
+Now you can use the IRC command `OPER BigOp secret` to get *IRC Operator*
+status on that server.
+
+Please choose a sensible password, and keep in mind that the *name* is not
+related to the *nickname* used by the user at all!
+
+We don't make use of the `Mask` setting in the example above (commented out
+with the `;` character), but it is a good idea to enable it whenever possible!
+
+And you can have as many *Operator blocks* as you like, configuring multiple
+different IRC Operators.