===== Pre-requisites ====== It is assumed the following: * You have already read the official [[https://ngircd.barton.de/documentation.php.en|ngIRCd documentation]]. This wiki page is **just a supplementary guide** * You already have configured ''[[openbsd:doas|doas]]''. If you have not configured ''doas'' and are running everything as root (user), you are asking for trouble! * You already have a text editor you prefer using. If you **do not** have a preference or have no idea about text editors. I personally suggest ''nano'' * This guide will not help you understand how to use ''nano'' or ''vim'' or whatever other editors that you may fancy * You already know how to install packages on OpenBSD, if not [[https://www.openbsd.org/faq/faq15.html#PkgInstall|read here]]. ===== Installation ===== $ doas pkg_add ngircd $ doas cp /usr/local/share/examples/ngircd/sample-ngircd.conf /etc/ngircd/ngircd.conf If you want to build from source: $ doas pkg_add ngircd # this will provide files /etc/rc.d/ startup scripts $ export CFLAGS=-static $ doas pkg_add autoconf-2.69p2 $ doas pkg_add automake-1.11.6p3 $ doas pkg_add libident $ doas pkg_add libiconv $ ./configure --enable-ipv6 --with-openssl --with-ident=/usr/local/ --with-iconv=/usr/loca l/ --with-syslog --sysconfdir=/etc/ngircd/ --mandir=/usr/local/man/ $ make $ doas make install ===== Configuration ===== ==== Text editors ==== Edit ''/etc/ngircd/ngircd.conf'' **with your favourite editor**, making sure to prefix doas at the beginning. For example, if your favourite editor is ''vim'', you would do, doas vim /etc/ngircd/ngircd.conf ''vim'' is not installed by default on OpenBSD! so you will need to install it before you can use it. In the previous example with installing ngircd, you just replace it with ''vim'', e.g. doas pkg_add vim **If your favourite text editor is not ''vim'', please do not simply just install ''vim''! Instead, replace ''vim'' with whatever text editor you are familiar with. If you are a novice to command line text editors, I suggest you to install/use ''nano'' or ''pico'' instead. Please also do ensure that you read up the relevant text editor documentation of your choice.** ==== Configuration file ==== **Any lines begins with either "#" or ";" in ''ngircd.conf'' are comments. The example configuration file has lots of these lines, make sure you un-comment it where needed** **Example** # This is a comment in ngircd.conf. ngircd will ignore this line. ;This is a also a comment in ngircd.conf. ngircd will ignore this line as well. Example within ''ngircd.conf'', [Global] # The [Global] section of this file 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! # Server name in the IRC network, must contain at least one dot # (".") and be unique in the IRC network. Required! ;Name = irc.example.com This should really be, [Global] # The [Global] section of this file 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! # Server name in the IRC network, must contain at least one dot # (".") and be unique in the IRC network. Required! Name = irc.acme.ircnow.org Note how: ;Name = irc.acme.ircnow.org Became: Name = irc.acme.ircnow.org You have now successfully turned from what was a comment into an actual parameter. You will need to uncomment and set any line that begins with semi-colon (;) character at the beginning of the line for any feature that you want. **Without removing that semi-colon that feature is either disabled or the defaults are used!** ===== Testing and running ===== To save yourself the hassles of finding out why ''ngircd'' fails to start, it is advised that you make ''ngircd'' test your configuration, doas ngircd -t Any errors and such will be shown along with waiting for you to press enter to show the configuration, without the comments. Remember how I emphasised that both "#" and ";" are at the beginning of the line, indicates a comment? those will not be visible by ''ngircd''! instead they are ignored. Once you are happy with your configuration and that ''ngircd'' no longer is reporting errors and such, simply, doas rcctl start ngircd To start ''ngircd'', if you want to have it started whenever you reboot the machine, replace the words "start" with "enable", e.g., doas rcctl enable ngircd Read [[https://www.openbsd.org/faq/faq10.html#rc|here]] on how to control system daemons such as using ''rcctl'' command above. Once all that is set, connect to your IRCd via your IRC client. Test to see if you can connect and can login as an IRC Operator. ===== Linking (Peering) ===== ==== MaxNickLength ==== There's a few gotchas with linking multiple ''ngircd'' servers. First and foremost, ensure that all your ''ngircd.conf'' has ''MaxNickLength'' set to a specific value. # 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! ;MaxNickLength = 9 **If one or more servers has a value that isn't 9 and/or that field is commented out, you will not be able to link up with that server.** So please ascertain what value to set **prior** to linking. ==== MyPassword and PeerPassword dilemma ==== Another simpler catch involves the MyPassword and PeerPassword keys. Your MyPassword should be the password that you set for other servers/peers to connect to your server. On their (these other server/peer end), should be set as PeerPassword when connecting to you. However, when you are connecting to them you need to know their PeerPassword. === Example ngIRCd server configurations === To illustrate what I mean is, say for example, you have two ''ngircd'' servers that you want to connect to each other. Let's say that the server "foo" has this configuration, [Global] Name = irc.foo.org Ports = 6667 ... [Server] MyPassword = Jp5meaikMiRAKsbBy6G6 Server "bar" has the following configuration, [Global] Name = irc.bar.org Ports = 6667 ... [Server] MyPassword = HpNSbcDbrTVQ3lkkqSfq Under "[Server]" section (**not global section**), it should be added as the following for server "foo". Ideally, I would put it in a separate ''[Server]'' section, which would have the following, # 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" or "NickServ,ChanServ,XyzServ". ;ServiceMask = *Serv,Global [Server] # More [Server] sections, if you like ... [Channel] See ''# More [Server] sections, if you like ...''? I would replace that line with the following below, [Server] Name = irc.bar.org Host = irc.bar.org Port = 6667 MyPassword = Jp5meaikMiRAKsbBy6G6 PeerPassword = HpNSbcDbrTVQ3lkkqSfq Likewise under server "bar", [Server] Name = irc.foo.org Host = irc.foo.org Port = 6667 MyPassword = HpNSbcDbrTVQ3lkkqSfq PeerPassword = Jp5meaikMiRAKsbBy6G6 === Password considerations === Keep in mind that ''MyPassword'' is used for linking with other servers. **It is stored in plaintext and has nothing to do with the server password specified under [Global] section, nor is it related to your [Operator] password!**. When other servers connects to you, they **need** to know **your** ''MyPassword'', in which they will then set it as their ''PeerPassword'' on their end. The same thing likewise when you need to peer with them, you **need** to know their ''MyPassword'' so that you can set it as **your** ''PeerPassword''. Considering how the passwords for linking are revealed when linking, you //do not// need to generate by hand a password that is to either be shared amongst your peering server(s), or for every new peer server(s), that you need to arbitrarily give it a different password. According to [[https://www.reddit.com/r/openbsd/comments/a1fyd5/generating_a_pseudorandom_password_from_the/|this link (reddit)]], you can simply make the system generate a pseudo random password, which isn't dictionary based, and can be arbitrarily lengthened (or shortened) to however long you wish, $ alias pw=" This will generate a pseudo password of up to 21 characters long, whenever you type the command ''pw'', $ pw LwF33FVlnBbHLFlgA6pc If you want to lengthen or shorten the length of the password, in the ''fold -w 20'', replace ''20'' with whatever number you wish. Keep in mind that the number you specify, doesn't include the very first character. In other words, specifying ''fold -w 29'' instead of ''fold -w 20'', $ alias pw=" This will generate a pseudo password of up to 30 characters long, $ pw dtkqvMhZDxBs5OJYewWBlK1Gnqbpa You can also choose to have this ''pw'' command whenever you login, by putting it inside your ''.rc'', where '''' implies the shell you are currently using, by default on OpenBSD, it is ''ksh'' and therefore it would be ''.kshrc''. See how in the example above how ''irc.foo.org'' ''MyPassword'' is set as ''Jp5meaikMiRAKsbBy6G6'' but when linking with ''irc.bar.org'', whose ''MyPassword'' is set as ''HpNSbcDbrTVQ3lkkqSfq'', that ''irc.foo.org'' ''PeerPassword'' is therefore ''HpNSbcDbrTVQ3lkkqSfq'' for linking to ''irc.bar.org''? The same logic also applies in reverse for when ''irc.bar.org'' is to link up with ''irc.foo.org''. === Summing it up === To sum it up in the prior example, Server ''irc.foo.org'' has the following for ''irc.bar.org'', [Server] Name = irc.bar.org Host = irc.bar.org Port = 6667 MyPassword = Password_To_Be_Set_On_IRCBARORG's_PeerPassword PeerPassword = Password_That_Is_To_Be_received_from_owner_of_IRCBARORG's_MyPassword and the same likewise, for ''irc.bar.org'' when linking to ''irc.foo.org'', [Server] Name = irc.foo.org Host = irc.foo.org Port = 6667 MyPassword = Password_To_Be_Set_On_IRCFOOORG's_PeerPassword PeerPassword = Password_That_Is_To_Be_received_from_owner_of_IRCFOOORG's_MyPassword You replace the contents of, * ''Name'', ''Host'' and ''Port'', keeping in mind that ''[Server]'' needs to be explicitly implied in the ''/etc/ngircd/ngircd.conf'' or ''ngircd'' will not understand what to do with the following contents. The following should be very self explanatory, on the string that is to be replaced, * ''Password_To_Be_Set_On_IRCBARORG's_PeerPassword'', * ''Password_That_Is_To_Be_received_from_owner_of_IRCBARORG's_MyPassword'', * ''Password_To_Be_Set_On_IRCFOOORG's_PeerPassword'', and * ''Password_That_Is_To_Be_received_from_owner_of_IRCFOOORG's_MyPassword'' ==== Fancy IRC domain names ==== If you or other ''ngircd'' owners chooses to use a domain name that resolves to a different IP, say ''irc.freenode.net'', you **must** set ''Host'' parameter, which points to their actual ''ngircd'''s [[https://en.wikipedia.org/wiki/Fully_qualified_domain_name|Fully Qualified Domain Name (FQDN)]] ''or'' their ''ngircd'''s IP address. I personally **do not** condone the notion of using FQDN that does not belong to you, as the consequences of going public with the named servers //can// potentially end up in lawsuits, for falsely misrepresenting a domain name. Let's use the prior example with the ''[Server]'' block. This time we assume, * ''irc.bar.org'' is owned by another operator, and * the owner of ''irc.bar.org'' wants to use ''irc.freenode.net'', * the owner has indicated under their ''Name'' key, under ''[Global]'' section is ''irc.freenode.net'' You **should** try to check if it resolves, $ host irc.freenode.net Regardless if it resolves or not, you need to confirm whether or not it points to their server's FQDN or their IP address. The owner of ''irc.foo.org'' needs to confirm the FQDN/IP address(es) for the owner of ''irc.freenode.net'' who is formerly the owner of ''irc.bar.org'', by asking the operator to perform the following, $ ifconfig | grep broadcast Note that it is the literal pipe character ''|'' , not the letter ''l'' in between ''ifconfig'' and ''grep''. If the IP address(es) irc.bar.org states does not match the output of ''irc.freenode.net'', or say for example ''host irc.freenode.net'' returns not found, you should then, decide to ask for their FQDN or the IP address to connect to. Now, there's two ways to go about on this, in terms of filling in the information. You can either choose to fill in (as owner of ''irc.foo.org''), [Server] Name = irc.freenode.net Host = irc.bar.org Port = 6667 MyPassword = Jp5meaikMiRAKsbBy6G6 PeerPassword = HpNSbcDbrTVQ3lkkqSfq See how ''Host = irc.bar.org'' is specified when the name they provided from within their config mentions ''irc.freenode.net''? This is one way. Assume that they give you the IP address to connect to on their server, and assume that the IP address is ''127.0.0.2'', [Server] Name = irc.freenode.net Host = 127.0.0.2 Port = 6667 MyPassword = Jp5meaikMiRAKsbBy6G6 PeerPassword = HpNSbcDbrTVQ3lkkqSfq ''Host = 127.0.0.2'' is implied, instead of ''Host = irc.bar.org''. Specifying the IP address in the ''Host'' key is more //ideal// as it does not require ''ngircd'' to query the [[https://en.wikipedia.org/wiki/Domain_Name_System#Address_resolution_mechanism|Domain Name System (DNS)]] for the IP address of a given FQDN. As an added bonus, connections to the said server via IP address //persists// even when the domain name has expired or changed hands (and therefore resolves to different IP address). ===== Chrooting ===== ==== Why chroot ==== You can simply reload your daemon without needing to restart it. Reloading your daemon makes it re-read any of the associated configuration files without restarting. In the case of ''ngircd'' the existing IRC connections/sessions you have active will be kept active. Restarting your daemon will also make it re-read any of the associated configuration files. **However**, it will also terminate any of your existing IRC connection/sessions. ==== Configuration ==== There are three values that you will need to unset it as a key. These are (in ''ngircd.conf''), [Global] ... # Group ID under which the ngIRCd 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! ServerGID = _ngircd # User ID under which the server 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! ServerUID = _ngircd ... [Options] ... # 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! ChrootDir = /var/ngircd ... You will then need to create missing directories within your ''ChrootDir''. Assuming you are using the defaults, for which ''ChrootDir'' is ''/var/ngircd'', you will need to create the following base layout, /var /var/ngircd /var/ngircd/etc /var/ngircd/etc/ngircd /var/ngircd/etc/ngircd.conf ''man 7 hier'' to get an understanding of how the filesystem is laid out. This means you will need to create parent directories leading up to ''/var/ngircd/etc/ngircd/ngircd.conf'', $ doas mkdir -p /var/ngircd/etc/ngircd Copy the ''ngircd.conf'' from ''/etc/ngircd'' into ''/var/ngircd/etc/ngircd'', $ doas cp /etc/ngircd/ngircd.conf /var/ngircd/etc/ngircd Make sure the path to ''/var/ngircd/etc/ngircd'' has the correct permissions. The following sets permissions as ''drwxrw-rw'', ''man chmod'' if in doubt, $ find /var/ngircd -type d -exec doas chmod 755 '{}' \; Make sure any of the files within ''/var/ngircd'' does not have others/world read/write/execute capability. You currently only have one file within it anyway, $ find /var/ngircd -type f -exec doas chmod 640 '{}' \; You should now be able to execute either ''doas rcctl reload ngircd'' or ''/quote rehash'' from either the console or your IRC client respectively. ===== SSL via TLS ===== ==== Pre-requisites ==== * You have a certificate that you can use with ''ngircd''. If you do not have one, I **recommend** that you obtain a free certificate from Let's Encrypt, following [[https://ircnow.org/kb/doku.php?id=openbsd:acme-client|this guide]]. ==== Pre-configuration ==== Copy the necessary certificates into both your ''/etc/ngircd'' directory and your chrooted ''ngircd'' directory. Chrooted ''ngircd'' directory by default is ''/var/ngircd'' but can be altered. If you have a custom chroot directory, you will need to copy the certificates there. Assuming you got your certificates from Let's Encrypt via following the aforementioned [[https://ircnow.org/kb/doku.php?id=openbsd:acme-client|acme-client]] guide, $ doas cp /etc/ssl/example.com.fullchain.pem /etc/ngircd $ doas cp /etc/ssl/private/example.com.key /etc/ngircd The same with your chrooted ''ngircd''. Again assuming defaults, $ doas cp /etc/ssl/example.com.fullchain.pem /var/ngircd/etc/ngircd $ doas cp /etc/ssl/private/example.com.key /var/ngircd/etc/ngircd Note: if /var/ngircd/etc/ doesn't exist, you can create it. ==== Configuration ==== In your ''ngircd.conf'', you will need to have the following, [SSL] # SSL-related configuration options. Please note that this section # is only available when ngIRCd is compiled with support for SSL! # So don't forget to remove the ";" above if this is the case ... # SSL Server Key Certificate CertFile = /etc/ngircd/example.com.fullchain.pem # Select cipher suites allowed for SSL/TLS connections. This defaults # to HIGH:!aNULL:@STRENGTH (OpenSSL) or SECURE128 (GnuTLS). # See 'man 1ssl ciphers' (OpenSSL) or 'man 3 gnutls_priority_init' # (GnuTLS) for details. # For OpenSSL: CipherList = HIGH:!aNULL:@STRENGTH:!SSLv3 # For GnuTLS: ;CipherList = SECURE128:-VERS-SSL3.0 # Diffie-Hellman parameters ;DHFile = /etc/ngircd/dhparams.pem # SSL Server Key KeyFile = /etc/ngircd/example.com.key # password to decrypt SSLKeyFile (OpenSSL only) ;KeyFilePassword = secret # Additional Listen Ports that expect SSL/TLS encrypted connections Ports = 6697, 9999 Notice how I, * Left the ''CipherList'' under the words ''For GnuTLS'' as-is, without uncommenting it? We're not using GnuTLS as OpenBSD does not include that by default. * Left ''DHFile'' commented out? This is **unnecessary**, however, if you feel you must have a DHFile set, you can do, $ doas openssl dhparam -out /etc/ngircd/dhparams.pem 2048 $ doas cp /etc/ngircd/dhparams.pem /var/ngircd/etc/ngircd Then once you have generated that file. Make sure you uncomment it in your ''ngircd.conf'' Save, and reload/restart your ''ngircd''. Check ''/var/log/messages'' to see if it is also listening on ports ''6697'' and ''9999''. Then connect to those ports via your IRC client to verify that SSL does work as intended. ===== HOPM ===== [[https://github.com/ircd-hybrid/hopm/blob/master/README|Hybrid Open Proxy Monitor (HOPM)]] can be configured for ''ngircd''. [[openbsd:irc:hopm|Click here to read more about it]]. ===== ACOPM ===== [[https://packages.alphachat.net/projects/ACOPM.git/plain/README.md|AlphaChat Open Proxy Monitor (ACOPM)]] can be configured for ''ngircd''. [[openbsd:irc:acopm|Click here to read more about it]]. ===== IRC services ===== You may wish to refer to [[https://github.com/ngircd/ngircd/blob/master/doc/Services.txt|this link]] for more information on hints with setting up IRC services for ''ngircd''. ===== Caveats ===== ngIRCd v25 provided by OpenBSD 6.6 via ports does not have the following compiled: * IDENT support, * PAM support ngIRCd without these compiled **can not** be enabled in ''/etc/ngircd/ngircd.conf''! IDENT support will be covered in [[openbsd:irc:ngircd:adv_topics|advanced topics]]. ===== See also ===== * [[openbsd:irc:ngircd:adv_topics|Advanced topics on ngIRCd]].