CR-Avatar for ircd-hybrid

cr_avatar is a module for ircd-hybrid 8.2.47 that adds the CR-AVATAR protocol: your ircd advertises CR-AVATAR=1, offers the capability conferencerooms.org/avatar, and sends AVATAR messages to clients that ask for them. Clients that do not know the protocol notice nothing. It is free software (GPL-2.0-or-later, like ircd-hybrid).

On this page: Download - What you need - Install - Check that it works - Run the tests - Troubleshooting - Upgrade and uninstall - License and questions

Download

Check it before you use it: shasum -a 256 ircd-hybrid-cr-avatar-0.1.0.zip (Linux: sha256sum). The package contains:

cr_avatar/
  README.md  INSTALL.md  LICENSE  CHANGELOG.md
  src/cr_avatar.c            the module
  src/Makefile               builds it against your ircd-hybrid tree
  patches/ircd-hybrid-8.2.47-cr-avatar-hooks.patch     six small core changes
  tests/                     build_and_test.sh, the test scripts, a scratch configuration
  docs/                      SERVICES.md, TESTING.md, PORTING.md

You also need the ircd-hybrid 8.2.47 source from the ircd-hybrid project.

What you need

• ircd-hybrid 8.2.47 (source). Other versions are not tested; see docs/PORTING.md if you run another one.
• Services that send the avatar tag: SVSTAG, numeric 320, text has an avatar set: <emoji> :<name>:. See CR-Avatar for services authors. Without it the module loads and does nothing.
• A service { name = "..."; }; block in ircd.conf that names your services server. The module treats a linked server with that flag as "services are up".
• A C compiler, make, flex, bison and python3 (for the tests), plus what ircd-hybrid itself needs (the jansson library, and OpenSSL if you use TLS).

Install

Read this first. The core patch adds hooks to ircd-hybrid, so the ircd must be rebuilt and restarted once. A restart disconnects every user: choose a quiet time and announce it. Try everything on a scratch copy first (see Run the tests).

1. Back up

Back up your source tree, the installed binary and modules folder, ircd.conf and modules.conf.

2. Unpack and patch the source

unzip ircd-hybrid-cr-avatar-0.1.0.zip
tar xzf ircd-hybrid-8.2.47.tar.gz && cd ircd-hybrid-8.2.47
patch -p1 --dry-run < ../cr_avatar/patches/ircd-hybrid-8.2.47-cr-avatar-hooks.patch   # must list 6 files and no rejects
patch -p1 < ../cr_avatar/patches/ircd-hybrid-8.2.47-cr-avatar-hooks.patch

If you already carry your own patches to src/channel.c, modules/m_join.c or modules/m_sjoin.c, apply the three one-line hook_dispatch(...) additions by hand (docs/PORTING.md shows where).

3. Build and install ircd-hybrid

Use the same ./configure options as your running ircd.

./configure --prefix=/opt/ircd-hybrid     # plus your usual options
make && make install

4. Build and install the module

Install it into the folder that holds the other .la files (m_join.la, cap_chghost.la ...).

make -C ../cr_avatar/src HYBRID_SRC=$PWD MODDIR=/opt/ircd-hybrid/lib/ircd-hybrid/modules install

If you gave ./configure a CPPFLAGS (for example -I/opt/openssl/include so TLS is built in), export the same CPPFLAGS first. Without it the build stops with openssl/ssl.h file not found.

5. Load it

Add one line to modules.conf:

loadmodule "cr_avatar.la";

6. Restart the ircd

In the log you should see Module cr_avatar.la ... loaded.

Check that it works

Connect with any client (or openssl s_client -connect your.server:6697) and look for three things:

CAP LS 302                          -> the list contains  conferencerooms.org/avatar
(the 005 lines)                     -> one of them contains  CR-AVATAR=1
CAP REQ :conferencerooms.org/avatar
CAP END
JOIN #somechannel                   -> right after the end-of-NAMES reply (366):
                                       :nick!user@host AVATAR <emoji> <name>     for each member that has an avatar

Then set or change an avatar with your services. Clients that asked for the capability get one AVATAR line about 1 to 3 seconds later; AVATAR * means it was removed. /WHOIS still shows has an avatar set: <emoji> :<name>: for everybody. If services leave, clients get 005 ... -CR-AVATAR and the capability disappears from CAP LS; when services come back, both return.

Run the tests

The tests never touch your real ircd or any network. They build a throw-away ircd-hybrid 8.2.47 in a temporary folder with the patch and the module, start it on 127.0.0.1 ports 47740 to 47743, link a fake services server and a fake second server to it, and talk to it with plain sockets.

cd cr_avatar
tests/build_and_test.sh /path/to/ircd-hybrid-8.2.47.tar.gz [/path/to/prefix-with-jansson-and-openssl]

The optional second argument is a folder with include/ and lib/ for jansson (and OpenSSL, if you want the TLS tests; without OpenSSL headers the TLS tests are skipped and the script says so). The last line is ==> all tests passed.

What is checked (74 checks: 37 on plain connections, the same 37 over TLS):

Not tested by the authors: other ircd-hybrid versions (only 8.2.47), a production network, auditorium or other special channel modes, three or more linked servers, and TLS with a certificate check. To try it on a copy of your own configuration, point your client at the scratch ircd (./bin/ircd -f -c etc/ircd.conf inside the scratch prefix) or add the module to a test server of your own.

Troubleshooting

Upgrade and uninstall

• Uninstall: remove the loadmodule "cr_avatar.la"; line and restart. The core patch is harmless without the module (the hooks have no subscribers).
• Upgrade: download the new package, run the tests on a scratch copy, rebuild the module (and ircd-hybrid if the patch changed), restart.

License and questions

The package is licensed GPL-2.0-or-later, the same as ircd-hybrid, so that adopting it is simple: a module for ircd-hybrid is part of a GPL program. The license applies to this package only. It does not apply to the CR-AVATAR protocol (anybody may implement it under any license), to ConferenceRooms' other software, or to modules for other ircds: each of those is licensed on its own. This is a summary, not legal advice.

• *Do I have to give my users the source?* If you distribute a built ircd with the module, the GPL applies as it does to ircd-hybrid itself. If you only run it on your own server, you have no obligation to publish anything.
• *Does it change anything for clients without CR-AVATAR?* No. They see the same server, plus one extra token in the 005 line.
• *Another ircd?* Modules for other ircds are planned. The specification and docs/PORTING.md tell you what the module does.