From: Alexander Barton Date: Sat, 23 Mar 2024 19:39:23 +0000 (+0100) Subject: Add manual pages and links to them X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c3fccb39ef069f81474261024f724d9b5fdf8f90;p=ngircd-web.git Add manual pages and links to them --- diff --git a/documentation.php.de b/documentation.php.de index a021d90..1c3151c 100644 --- a/documentation.php.de +++ b/documentation.php.de @@ -78,5 +78,24 @@

+ Manual Pages +

+ AuÃerdem enthÃ¤lt ngIRCd zwei manual pages: + ngircd(8) (fÃ¼r den Daemon) und ngircd.conf(5) + (fÃ¼r seine Konfigurationsdatei). Sie enthalten noch mehr Details und + listen alle mÃ¶glichen Kommandozeilenparameter und + Konfigurationsoptionen auf. Sie kÃ¶nnen sie mit dem + man-Befehl lesen (wenn sie lokal auf Ihrem System + installiert sind, z.B. `man 8 ngircd` und `man 5 ngircd.conf`) oder + online hier: +

Server: ngircd(8)
Konfigurationsdatei: ngircd.conf(5)

+ diff --git a/documentation.php.en b/documentation.php.en index 95da73a..6aa718f 100644 --- a/documentation.php.en +++ b/documentation.php.en @@ -71,9 +71,27 @@ exemplary configurations sample-ngircd.conf).

- The documents of tha actual version can be found online here: + The documents of the current version can be found online here:

+ Manual Pages +

+ In addition, ngIRCd comes with two manual pages: ngircd(8) + (for the daemon) and ngircd.conf(5) (for its configuration + file). They have even more details and list all possible command line + parameters and configuration options. You can read them with the + man command (when they are installed locally on your + system, e.g. man 8 ngircd and man 5 + ngircd.conf) or online here: +

Daemon: ngircd(8)
Configuration file: ngircd.conf(5)

+ diff --git a/man/ngircd.8.html b/man/ngircd.8.html new file mode 100644 index 0000000..7646e30 --- /dev/null +++ b/man/ngircd.8.html @@ -0,0 +1,294 @@ + + + + + + + ngircd + + + +

ngircd

Sep 2023

NAME

ngIRCd - the "next generation" IRC daemon

SYNOPSIS

ngircd [ Options ]

DESCRIPTION

ngIRCd is a free, portable and lightweight Internet +Relay Chat (IRC) server for small or private networks, developed under +the GNU General Public License (GPL).

The server is quite easy to configure and runs as a single-node +server or can be part of a network of ngIRCd servers in a LAN or across +the internet. It optionally supports the IPv6 protocol, +SSL/TLS-protected client-server and server-server links, the Pluggable +Authentication Modules (PAM) system for user authentication, IDENT +requests, and character set conversion for legacy clients.

The name ngIRCd stands for next-generation IRC daemon, which +is a little bit exaggerated: lightweight Internet Relay Chat +server most probably would have been a better name :-)

By default ngIRCd logs diagnostic and informational messages using +the syslog mechanism, or writes directly to the console when running in +the foreground (see below).

OPTIONS

The default behavior of ngircd is to read its +standard configuration file (see below), to detach from the controlling +terminal and to wait for clients.

You can use these options to modify this default:

-f file, --config +file: +
Use file as configuration file.
+
-n, --nodaemon: +
Don't fork a child and don't detach from controlling terminal. All +log messages go to the console and you can use CTRL-C to terminate the +server.
+
-p, --passive: +
Disable automatic connections to other servers. You can use the IRC +command CONNECT later on as IRC Operator to link this ngIRCd to other +servers.
+
-y, --syslog: +
Write log messages to the syslog even when running in the foreground. +This only makes sense when -n/--nodaemon was given on the +command line before this option!
+

The following options prevent ngIRCd from starting regularly, but +perform a specific action and then exit the daemon again:

-h, --help: +
Display a brief help text and exit.
+
-t, --configtest: +
Read, validate and display the configuration; then exit.
+
-V, --version: +
Output version information and exit.
+

FILES

/usr/local/etc/ngircd.conf

+
The system wide default configuration file.
+

/usr/local/etc/ngircd.motd

+
Default "message of the day" (MOTD).
+

SIGNALS

The daemon understands the following signals:

TERM: +
Shut down all connections and terminate the daemon.
+
HUP: +
Shut down all listening sockets, re-read the configuration file and +re-initialize the daemon.
+

HINTS

It is always wise to use "ngircd --configtest" to validate +the configuration of ngIRCd after making changes to the configuration +files!

DEBUGGING

When ngIRCd is compiled with debug code, that is, its source code has +been ./configure'd with "--enable-debug" and/or "--enable-sniffer" +(witch enables debug mode automatically as well), you can use two more +command line options and two more signals to debug problems with the +daemon itself or IRC clients:

Options:

-d, --debug: +
Enable debug mode and log extra messages.
+
-s, --sniffer: +
Enable IRC protocol sniffer, which logs all sent and received IRC +commands to the console/syslog. This option requires that ngIRCd has +been ./configure'd with "--enable-sniffer" and enables debug mode +automatically, too.
+

Signals:

USR1: +
Toggle debug mode on and off during runtime.
+
USR2: +
Dump internal server state to the console/syslog when debug mode is +on (use command line option --debug or signal USR1).
+

AUTHORS

Alexander Barton, <alex@barton.de>
+Florian Westphal, <fw@strlen.de>

Homepage: http://ngircd.barton.de/

ngircd.conf

Sep 2023

NAME

ngircd.conf - configuration file of ngIRCd

SYNOPSIS

/usr/local/etc/ngircd.conf

DESCRIPTION

ngircd.conf is the configuration file of the +ngircd(8) Internet Relay Chat (IRC) daemon, which must +be customized to the local preferences and needs.

Most variables can be modified while the ngIRCd daemon is already +running: It will reload its configuration file when a HUP signal or +REHASH command is received.

FILE FORMAT

The file consists of sections and parameters. A section begins with +the name of the section in square brackets and continues until the next +section begins.

Sections contain parameters of the form

+
name = value
+

Empty lines and any line beginning with a semicolon (';') or a hash +('#') character are treated as a comment and will be ignored. Leading +and trailing whitespaces are trimmed before any processing takes +place.

The file format is line-based - that means, each non-empty +newline-terminated line represents either a comment, a section name, or +a parameter.

Section and parameter names are not case sensitive.

There are three types of variables: booleans, text +strings, and numbers. Boolean values are true if +they are "yes", "true", or any non-null integer. Text strings are used +1:1 without leading and following spaces; there is no way to quote +strings. And for numbers all decimal integer values are valid.

In addition, some string or numerical variables accept lists of +values, separated by commas (",").

SECTION OVERVIEW

The file can contain blocks of seven types: [Global], [Limits], +[Options], [SSL], [Operator], [Server], and [Channel].

The main configuration of the server is stored in the +[Global] section, like the server name, administrative +information and the ports on which the server should be listening. The +variables in this section have to be adjusted to the local requirements +most of the time, whereas all the variables in the other sections can be +left on their defaults very often.

Options in the [Limits] block are used to tweak different +limits and timeouts of the daemon, like the maximum number of clients +allowed to connect to this server. Variables in the [Options] +section can be used to enable or disable specific features of ngIRCd, +like support for IDENT, PAM, IPv6, and protocol and cloaking features. +The [SSL] block contains all SSL-related configuration +variables. These three sections are all optional.

IRC operators of this server are defined in [Operator] +blocks. Links to remote servers are configured in [Server] +sections. And [Channel] blocks are used to configure +pre-defined ("persistent") IRC channels.

There can be more than one [Operator], [Server] and [Channel] section +per configuration file, one for each operator, server, and channel. +[Global], [Limits], [Options], and [SSL] sections can occur multiple +times, too, but each variable overwrites itself, only the last +assignment is relevant.

[GLOBAL]

The [Global] section is used to define the main +configuration of the server, like the server name and the ports on which +the server should be listening. These settings depend on your personal +preferences, so you should make sure that they correspond to your +installation and setup!

Name (string): +
Server name in the IRC network. This is an individual name of the IRC +server, it is not related to the DNS host name. It must be unique in the +IRC network and must contain at least one dot (".") character. When not +set, ngIRCd tries to deduce a valid IRC server name from the local host +name.
+
AdminInfo1, AdminInfo2, +AdminEMail (string): +
Information about the server and the administrator, used by the ADMIN +command. This information is not required by the server but by RFC!
+
HelpFile (string): +
Text file which contains the ngIRCd help text. This file is required +to display help texts when using the "HELP <cmd>" command. Please +note: Changes made to this file take effect when ngircd starts up or is +instructed to re-read its configuration file. Default: a built-in +standard path.
+
Info (string): +
Info text of the server. This will be shown by WHOIS and LINKS +requests for example. Set to the server software name and version by +default.
+
Listen (list of strings): +
A comma separated list of IP address on which the server should +listen. If unset, the defaults value is "0.0.0.0" or, if ngIRCd was +compiled with IPv6 support, "::,0.0.0.0". So the server listens on all +configured IP addresses and interfaces by default.
+
MotdFile (string): +
Text file with the "message of the day" (MOTD). This message will be +shown to all users connecting to the server. Please note: Changes made +to this file take effect when ngircd starts up or is instructed to +re-read its configuration file. Default: a built-in standard path.
+
MotdPhrase (string): +
A simple Phrase (<127 chars) if you don't want to use a MOTD +file.
+
Network (string): +
The name of the IRC network to which this server belongs. This name +is optional, should only contain ASCII characters, and can't contain +spaces. It is only used to inform clients. The default is empty, so no +network name is announced to clients.
+
Password (string): +
Global password for all users needed to connect to the server. The +default is empty, so no password is required. Please note: This feature +is not available if ngIRCd is using PAM!
+
PidFile (string): +
This tells ngIRCd to write its current process ID to a file. Note +that the "PID file" is written AFTER chroot and switching the user ID, +therefore the directory the file resides in must be writable by the +ngIRCd user and exist in the chroot directory (if configured, see +above).
+
Ports (list of numbers): +
Port number(s) on which the server should listen for unencrypted +connections. There may be more than one port, separated with commas +(","). Default: 6667.
+
ServerGID (string or number): +
Group ID under which the ngIRCd daemon should run; you can use the +name of the group or the numerical ID.
+

+
Attention:
+For this to work the server must have been started with root +privileges!
+

ServerUID (string or number): +
User ID under which the ngIRCd daemon should run; you can use the +name of the user or the numerical ID.
+

+
Attention:
+For this to work the server must have been started with root privileges! +In addition, the configuration and MOTD files must be readable by this +user, otherwise RESTART and REHASH won't work!
+

[LIMITS]

This section is used to define some limits and timeouts for this +ngIRCd instance. Default values should be safe, but it is wise to +double-check :-)

ConnectRetry (number): +
The server tries every <ConnectRetry> seconds to establish a +link to not yet (or no longer) connected servers. Default: 60.
+
IdleTimeout (number): +
Number of seconds after which the whole daemon should shutdown when +no connections are left active after handling at least one client (0: +never). This can be useful for testing or when ngIRCd is started using +"socket activation" with systemd(8), for example. Default: 0.
+
MaxConnections (number): +
Maximum number of simultaneous in- and outbound connections the +server is allowed to accept (0: unlimited). Default: 0.
+
MaxConnectionsIP (number): +
Maximum number of simultaneous connections from a single IP address +that the server will accept (0: unlimited). This configuration options +lowers the risk of denial of service attacks (DoS). Default: 5.
+
MaxJoins (number): +
Maximum number of channels a user can be member of (0: no limit). +Default: 10.
+
MaxNickLength (number): +
Maximum length of an user nickname (Default: 9, as in RFC 2812). +Please note that all servers in an IRC network MUST use the same maximum +nickname length!
+
MaxPenaltyTime (number): +
Maximum penalty time increase in seconds, per penalty event. Set to +-1 for no limit (the default), 0 to disable penalties altogether. ngIRCd +doesn't use penalty increases higher than 2 seconds during normal +operation, so values greater than 1 rarely make sense.
+
MaxListSize (number): +
Maximum number of channels returned in response to a LIST command. +Default: 100.
+
PingTimeout (number): +
After <PingTimeout> seconds of inactivity the server will send +a PING to the peer to test whether it is alive or not. Default: 120.
+
PongTimeout (number): +
If a client fails to answer a PING with a PONG within +<PongTimeout> seconds, it will be disconnected by the server. +Default: 20.
+

[OPTIONS]

Optional features and configuration options to further tweak the +behavior of ngIRCd are configured in this section. If you want to get +started quickly, you most probably don't have to make changes here -- +they are all optional.

AllowedChannelTypes (string): +
List of allowed channel types (channel prefixes) for newly created +channels on the local server. By default, all supported channel types +are allowed. Set this variable to the empty string to disallow creation +of new channels by local clients at all. Default: #&+
+
AllowRemoteOper (boolean): +
If this option is active, IRC operators connected to remote servers +are allowed to control this local server using administrative commands, +for example like CONNECT, DIE, SQUIT etc. Default: no.
+
ChrootDir (string): +
A directory to chroot in when everything is initialized. It doesn't +need to be populated if ngIRCd is compiled as a static binary. By +default ngIRCd won't use the chroot() feature.
+

+
Attention:
+For this to work the server must have been started with root +privileges!
+

CloakHost (string): +
Set this hostname for every client instead of the real one. Default: +empty, don't change. Use %x to add the hashed value of the original +hostname.
+
CloakHostModeX (string): +
Use this hostname for hostname cloaking on clients that have the user +mode "+x" set, instead of the name of the server. Default: empty, use +the name of the server. Use %x to add the hashed value of the original +hostname
+
CloakHostSalt (string): +
The Salt for cloaked hostname hashing. When undefined a random hash +is generated after each server start.
+
CloakUserToNick (boolean): +
Set every clients' user name and real name to their nickname and hide +the one supplied by the IRC client. Default: no.
+
ConnectIPv4 (boolean): +
Set this to no if you do not want ngIRCd to connect to other IRC +servers using the IPv4 protocol. This allows the usage of ngIRCd in +IPv6-only setups. Default: yes.
+
ConnectIPv6 (boolean): +
Set this to no if you do not want ngIRCd to connect to other IRC +servers using the IPv6 protocol. Default: yes.
+
DefaultUserModes (string): +
Default user mode(s) to set on new local clients. Please note that +only modes can be set that the client could set using regular MODE +commands, you can't set "a" (away) for example! Default: none.
+
DNS (boolean): +
If set to false, ngIRCd will not make any DNS lookups when clients +connect. If you configure the daemon to connect to other servers, ngIRCd +may still perform a DNS lookup if required. Default: yes.
+
Ident (boolean): +
If ngIRCd is compiled with IDENT support this can be used to disable +IDENT lookups at run time. Users identified using IDENT are registered +without the "~" character prepended to their user name. Default: +yes.
+
IncludeDir (string): +
Directory containing configuration snippets (*.conf), that should be +read in after parsing the current configuration file. Default: a +built-in directory name when no configuration file was explicitly given +on the command line (check "ngircd --configtest"), none (empty) +otherwise.
+

+
This way no default include directory is used when a possibly +non-default configuration file was explicitly specified using +"--config"/"-f" on the command line which (intentionally) did not +specify an IncludeDir directive.
+

MorePrivacy (boolean): +
This will cause ngIRCd to censor user idle time, logon time as well +as the PART/QUIT messages (that are sometimes used to inform everyone +about which client software is being used). WHOWAS requests are also +silently ignored, and NAMES output doesn't list any clients for +non-members. This option is most useful when ngIRCd is being used +together with anonymizing software such as TOR or I2P and one does not +wish to make it too easy to collect statistics on the users. Default: +no.
+
NoticeBeforeRegistration (boolean): +
Normally ngIRCd doesn't send any messages to a client until it is +registered. Enable this option to let the daemon send "NOTICE *" +messages to clients while connecting. Default: no.
+
OperCanUseMode (boolean): +
Should IRC Operators be allowed to use the MODE command even if they +are not(!) channel-operators? Default: no.
+
OperChanPAutoOp (boolean): +
Should IRC Operators get AutoOp (+o) in persistent (+P) channels? +Default: yes.
+
OperServerMode (boolean): +
If OperCanUseMode is enabled, this may lead the +compatibility problems with Servers that run the ircd-irc2 Software. +This Option "masks" mode requests by non-chanops as if they were coming +from the server. Default: no; only enable it if you have ircd-irc2 +servers in your IRC network.
+
PAM (boolean): +
If ngIRCd is compiled with PAM support this can be used to disable +all calls to the PAM library at runtime; all users connecting without +password are allowed to connect, all passwords given will fail. Users +identified using PAM are registered without the "~" character prepended +to their user name. Default: yes.
+
PAMIsOptional (boolean): +
When PAM is enabled, all clients are required to be authenticated +using PAM; connecting to the server without successful PAM +authentication isn't possible. If this option is set, clients not +sending a password are still allowed to connect: they won't become +"identified" and keep the "~" character prepended to their supplied user +name. Please note: To make some use of this behavior, it most probably +isn't useful to enable "Ident", "PAM" and "PAMIsOptional" at the same +time, because you wouldn't be able to distinguish between Ident'ified +and PAM-authenticated users: both don't have a "~" character prepended +to their respective user names! Default: no.
+
PAMServiceName (string): +
When PAM is enabled, this value determines the used PAM +configuration. This setting allows running multiple ngIRCd instances +with different PAM configurations on each instance. If you set it to +"ngircd-foo", PAM will use /etc/pam.d/ngircd-foo instead of the default +/etc/pam.d/ngircd. Default: ngircd.
+
RequireAuthPing (boolean): +
Let ngIRCd send an "authentication PING" when a new client connects, +and register this client only after receiving the corresponding "PONG" +reply. Default: no.
+
ScrubCTCP (boolean): +
If set to true, ngIRCd will silently drop all CTCP requests sent to +it from both clients and servers. It will also not forward CTCP requests +to any other servers. CTCP requests can be used to query user clients +about which software they are using and which versions said software is. +CTCP can also be used to reveal clients IP numbers. ACTION CTCP requests +are not blocked, this means that /me commands will not be dropped, but +please note that blocking CTCP will disable file sharing between users! +Default: no.
+
SyslogFacility (string): +
Syslog "facility" to which ngIRCd should send log messages. Possible +values are system dependent, but most probably "auth", "daemon", "user" +and "local1" through "local7" are possible values; see syslog(3). +Default is "local5" for historical reasons, you probably want to change +this to "daemon", for example.
+
WebircPassword (string): +
Password required for using the WEBIRC command used by some +Web-to-IRC gateways. If not set or empty, the WEBIRC command can't be +used. Default: not set.
+

[SSL]

All SSL-related configuration variables are located in the +[SSL] section. Please note that this whole section is only +recognized by ngIRCd when it is compiled with support for SSL using +OpenSSL or GnuTLS!

CertFile (string): +
SSL Certificate file of the private server key.
+
CipherList (string): +
Select cipher suites allowed for SSL/TLS connections. This defaults +to "HIGH:!aNULL:@STRENGTH:!SSLv3" (OpenSSL) or "SECURE128:-VERS-SSL3.0" +(GnuTLS). Please see 'man 1ssl ciphers' (OpenSSL) and 'man 3 +gnutls_priority_init' (GnuTLS) for details.
+
DHFile (string): +
Name of the Diffie-Hellman Parameter file. Can be created with GnuTLS +"certtool --generate-dh-params" or "openssl dhparam". If this file is +not present, it will be generated on startup when ngIRCd was compiled +with GnuTLS support (this may take some time). If ngIRCd was compiled +with OpenSSL, then (Ephemeral)-Diffie-Hellman Key Exchanges and several +Cipher Suites will not be available.
+
KeyFile (string): +
Filename of SSL Server Key to be used for SSL connections. This is +required for SSL/TLS support.
+
KeyFilePassword (string): +
OpenSSL only: Password to decrypt the private key file.
+
Ports (list of numbers): +
Same as Ports , except that ngIRCd will expect +incoming connections to be SSL/TLS encrypted. Common port numbers for +SSL-encrypted IRC are 6669 and 6697. Default: none.
+

[OPERATOR]

[Operator] sections are used to define IRC Operators. There +may be more than one [Operator] block, one for each local +operator.

Name (string): +
ID of the operator (may be different of the nickname).
+
Password (string): +
Password of the IRC operator.
+
Mask (string): +
Mask that is to be checked before an /OPER for this account is +accepted. Example: nick!ident@*.example.com
+

[SERVER]

Other servers are configured in [Server] sections. If you +configure a port for the connection, then this ngIRCd tries to connect +to the other server on the given port (active); if not, it waits for the +other server to connect (passive).

ngIRCd supports "server groups": You can assign an "ID" to every +server with which you want this ngIRCd to link, and the daemon ensures +that at any given time only one direct link exists to servers with the +same ID. So if a server of a group won't answer, ngIRCd tries to connect +to the next server in the given group (="with the same ID"), but never +tries to connect to more than one server of this group +simultaneously.

There may be more than one [Server] block.

Name (string): +
IRC name of the remote server.
+
Host (string): +
Internet host name (or IP address) of the peer.
+
Bind (string): +
IP address to use as source IP for the outgoing connection. Default +is to let the operating system decide.
+
Port (number): +
Port of the remote server to which ngIRCd should connect (active). If +no port is assigned to a configured server, the daemon only waits for +incoming connections (passive, default).
+
MyPassword (string): +
Own password for this connection. This password has to be configured +as PeerPassword on the other server. Must not have ':' +as first character.
+
PeerPassword (string): +
Foreign password for this connection. This password has to be +configured as MyPassword on the other server.
+
Group (number): +
Group of this server (optional).
+
Passive (boolean): +
Disable automatic connection even if port value is specified. +Default: false. You can use the IRC Operator command CONNECT later on to +create the link.
+
SSLConnect (boolean): +
Connect to the remote server using TLS/SSL. Default: false.
+
ServiceMask (string): +
Define a (case insensitive) list of masks matching nicknames that +should be treated as IRC services when introduced via this remote +server, separated by commas (","). REGULAR SERVERS DON'T NEED this +parameter, so leave it empty (which is the default).
+

+
When you are connecting IRC services which mask as a IRC server and +which use "virtual users" to communicate with, for example "NickServ" +and "ChanServ", you should set this parameter to something like "*Serv", +"*Serv,OtherNick", or "NickServ,ChanServ,XyzServ".
+

[CHANNEL]

Pre-defined channels can be configured in [Channel] +sections. Such channels are created by the server when starting up and +even persist when there are no more members left.

Persistent channels are marked with the mode 'P', which can be set +and unset by IRC operators like other modes on the fly.

There may be more than one [Channel] block.

Name (string): +
Name of the channel, including channel prefix ("#" or "&").
+
Topic (string): +
Topic for this channel.
+
Modes (string): +
Initial channel modes, as used in "MODE" commands. Modifying lists +(ban list, invite list, exception list) is supported.
+

+
This option can be specified multiple times, evaluated top to +bottom.
+

Autojoin (boolean): +
Should ngIRCd automatically join ("autojoin") all users to this +channel on connect? Note: The users must have permissions to access the +channel, otherwise joining them will fail!
+
KeyFile (string): +
Path and file name of a "key file" containing individual channel keys +for different users. The file consists of plain text lines with the +following syntax (without spaces!):
+

+
+
user : nick : key
+
+
user and nick can contain the wildcard character +"*".
+key is an arbitrary password.
+
Valid examples are:
+
+
*:*:KeY
+*:nick:123
+~user:*:xyz
+
+
The key file is read on each JOIN command when this channel has a key +(channel mode +k). Access is granted, if a) the channel key set using +the MODE +k command or b) one of the lines in the key file match.
+
Please note:
+The file is not reopened on each access, so you can modify and overwrite +it without problems, but moving or deleting the file will have not +effect until the daemon re-reads its configuration!
+

HINTS

It's wise to use "ngircd --configtest" to validate the configuration +file after changing it. See ngircd(8) for details.

AUTHOR

Alexander Barton, <alex@barton.de>
+Florian Westphal, <fw@strlen.de>

Homepage: http://ngircd.barton.de/

+ Manual Pages +

+ Manual Pages +

ngircd

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

FILES

SIGNALS

HINTS

DEBUGGING

AUTHORS

SEE ALSO

ngircd.conf

NAME

SYNOPSIS

DESCRIPTION

FILE FORMAT

SECTION OVERVIEW

[GLOBAL]

[LIMITS]

[OPTIONS]

[SSL]

[OPERATOR]

[SERVER]

[CHANNEL]

HINTS

AUTHOR

SEE ALSO