diff --git a/INSTALL.md b/INSTALL.md index 56c7cc52..b5ad20ed 100644 --- 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 f0856d7f..f576481f 100644 --- 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 . +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 index 00000000..ff1f2aa2 --- /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.