ZNC

This page describes client and server setup for ZNC with LDAP authentication. For more info on ZNC, see [1].

Server setup

Saslauthd setup

For LDAP authentication, we use the Cyrusauth module [2], which needs to communicate with the SASL authentication daemon (saslauthd).

1. On the server, install the following packages:

   apt install sasl2-bin ca-certificates

2. Open /etc/default/saslauthd, and change the following lines:

   START=yes
   MECHANISM="ldap"
   

3. Paste the following into /etc/saslauthd.conf:

   ldap_servers: ldaps://auth1.csclub.uwaterloo.ca ldaps://auth2.csclub.uwaterloo.ca
   ldap_search_base: ou=People,dc=csclub,dc=uwaterloo,dc=ca
   ldap_filter: (uid=%u)
   

4. Start saslauthd:

   # service saslauthd start
   

5. Test saslauthd to make sure it's working:

   $ testsaslauthd -u "your_csc_username" -p "your_csc_password"
   

   You should see a response like

   0: OK "Success."
   

ZNC setup

1. Install ZNC:

   # apt install znc
   

2. Add a user for ZNC and create an initial configuration:

   # useradd -s /bin/bash -m znc
   # usermod -a -G sasl znc
   # su - znc
   $ znc --makeconf
   

   Note that the znc user must be part of the sasl group to communicate with saslauthd.

3. Visit the web interface at <SERVER_IP>:<PORT>. Note that you may need to modify your browser settings so that you can visit a website at port 6667 or 6697.
4. Log in using your admin credentials, then go to "Global Settings". Check the "cyrusauth" box, type "saslauthd" in the arguments input field, then scroll to the bottom and click "Save".
5. You will now need to connect to ZNC with an IRC client. The commands below assume Weechat is being used, but other clients should be similar.

   /server add myznc <SERVER_IP>/<PORT> -username=<ADMIN_USERNAME> -password=<ADMIN_PASSWORD>
   /connect myznc
   /msg *Cyrusauth CreateUsers yes
   

   This will tell ZNC to create a new user on their first login.

6. You may optionally wish to create users from a template (i.e. dummy) user to share some common per-user settings, such as MaxNetworks. To do this, login to the ZNC web interface as admin and click on "Manage Users". Add a new user called "dummy" with the desired settings, then click "save". Now open Weechat, login to ZNC as admin, and run the following:

   /msg *Cyrusauth CreateUsers clone dummy
   

   This will tell ZNC to clone new users using "dummy" as the template.

7. You may wish to optionally enable the adminlog module [3] so that you can see who has logged in from where at what time. By default, these logs will be written to a file. To prevent this file from growing too long, install logrotate and paste the following into /etc/logrotate.d/znc:

   /home/znc/.znc/moddata/adminlog/znc.log {
           rotate 4
           weekly
           compress
   }
   

   This will keep rotate logs every week, discarding logs after they have been rotated 4 times.

NGINX tuning

If you are running ZNC behind NGINX as a reverse proxy, keep in mind that by default, NGINX will run one worker process per CPU core. To reduce this, change the following in /etc/nginx/nginx.conf:

worker_processes 4

Client setup

These instructions show how to connect to the #csc channel on Freenode via ZNC.

1. Visit the ZNC web portal and login using your CSC credentials.
2. Go to "Your Settings". Under "Networks", if you do not see a network called "freenode", then click "Add", type "freenode" for the Network Name, edit your nickname if desired, and enter the following into the IRC servers table:

   Hostname            Port    SSL
   chat.freenode.net   6697    [Checked]
   

3. (Optional, but recommended): Under the settings for freenode, check the box which says "Connect to IRC & automatically re-connect". This will connect you to Freenode as soon as you connect to ZNC.
4. Set your nick, alt. nick, and ident for freenode. Make sure these all have the same value. By default these are set to %user% which will expand to your csc username. If you are already logged in to freenode with your csc username on a different IRC client, make sure to change your nick here as two different connections cannot share the same nick.
5. Under the "channels" section for freenode, click "Add", then enter "#csc" in the "Channel Name" field, and check the boxes "Save to config", "Detached", and "Enabled". Click "Add Channel and return".
6. Now you will connect to ZNC with an IRC client. The commands below assume you are using Weechat, but other clients should be similar.

   /server add myznc znc.csclub.uwaterloo.ca/6697 -username=<CSC_USERNAME>/freenode -password=<CSC_PASSWORD> -ssl -autoconnect
   /connect myznc
   /join #csc
   

   Don't forget to concatenate "/freenode" to the end of your username.

7. If you did not check the autoconnect box, you will need to manually connect using:

   /msg *status connect
   

   To verify that you are connected to Freenode, run

   /msg *status ListNetworks
   

   The "IRC" column should have the value "Yes".

8. A modified version of the backlog module [4] is enabled globally. To use this, first enable the log module for your user via the web UI. You will then be able to request older logs for a channel from your IRC client, e.g.

   /msg *backlog #csc 42
   

   Note that you do not need to specify the log path.