summaryrefslogblamecommitdiffstats
path: root/README
blob: 49963f38dd0051f60045612c6e176a412615fadb (plain) (tree)

















































                                                                                                     
                                                                                                     


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                                                                                                    
 

                                                                                                     


                                                                                                     
                                                                                 

         


                                                                                                                                               
 













                                                                                                     
                                                                                        




                                                                                              
                                                                                          




                                                                                                   
ircxmpp is a simple one-to-one bridge between IRC and XMPP.

Usage: IX_JID=j@xmpp IX_PASS=xmpp IX_HOST=irc.srv IX_PORT=6666 IX_CHANNEL=#c IX_MUC=muc@xmpp ircxmpp
	- one XMPP user needs to be created on XMPP server, identified by jid and password
	- prepend # to irc.srv hostname (#irc.srv) to connect with TLS
	- change port to 6697 (or whatever is used) when connecting with TLS
	- replace muc with the MUC XMPP group to connect to

Configure the MUC room and XMPP server if possible:
	- disable sending full jids, because every IRC user has same bare JID, only nickname changes
	- default visitors as participants or make ircxmpp XMPP a participant in MUC room
	- disable any per-JID or per-IP limits, ircxmpp connects multiple times
	- MAM may be enabled, since old messages will never be sent to IRC
	- disable any MUC password protection or allow JID of ircxmpp to connect

Configure the IRC channel or server if possible:
	- disable any per-IP limits, ircxmpp connects multiple times. libera chat is okay with that.
	- use a bot to set XMPP users to have +o, +v or +h to prevent flood kicks
	- disable invite-only mode on channel. you may use IRC channel passwords.

Required environment variables for configuration:
	- IX_JID	JID of ircxmpp user on XMPP server to connect with
	- IX_PASS	password for XMPP authentication of ircxmpp user
	- IX_HOST	hostname of the IRC server, prefix the value with # to connect with TLS
	- IX_PORT	port of the IRC server to connect to, choose apropriate for plaintext/TLS
	- IX_CHANNEL	channel on IRC server to bridge
	- IX_MUC	multi-user chat on XMPP server to bridge

Optional environment variables for configuration:
	- IX_CHPASS	set to IRC channel password if channel on IRC is password protected
	- IX_LOOPDELAY	delay after each event loop cycle in microseconds, defaults to 100 ms.

Operation principle:
	- ircxmpp initiates two control connections, one to XMPP server, one to IRC server, and joins
	- when user joins in XMPP, a bridge connection is established to IRC and joins the channel
	- when user joins in IRC, a bridge connection is established to XMPP and joins the MUC
	- when a chat is made in IRC, it's reflected on the correct bridge connection in XMPP
	- when a chat is made in XMPP, it's reflected on the correct bridge connection in IRC
	- when user quits in IRC, resources are freed for the bridge, connection to XMPP is dropped
	- when user quits in XMPP, resources are freed for the bridge, connection to IRC is dropped
	- control connections are reconnected automatically and remain connected till exit.
	- program can be stopped by sending a SIGTERM or SIGINT (well, or SIGKILL for that matter)
	- topic changes are reflected in XMPP MUC as messages

To implement:
	- private messages
	- ctcp messages (ACTION - /me) and perhaps file upload (that'd be hard)
	- subject changing
	- automatic +v/+h/+o botnet juggling between bridge IRC connections and control IRC conn
	- setting user@host of bridge bots on IRC to JIDs of XMPP users by temporary changing rDNS
	- reusing bridge and control connections with same nick to different channels on same network

Notes:
	- when connecting to a channel with already joined nicks, they're not connected to XMPP until they send a message or change their nick. only after that are they bridged, and the sent message is not lost. implementing this would require parsing NAMES list, which only contains nicks and not usernames and hostnames, and would also impact performance, especially on MAM-enabled MUCs that send a lot of history on XMPP join for every connection. XMPP MUCs also tend to slow down with a large number of connections, whereas IRC channels don't.
	- if possible, send core dumps of crashes to my email address anton@šijanec.eu.
	- coredumps contain passwords and some chats, so make sure to change XMPP password before
	- to capture core dumps of systemd services (when installed on debian), use systemd-coredump

Debian installation, systemd service and precompiled dynamically linked binaries:
	- packages in my ppa on http://prog.sijanec.eu/ (amd64, arm64, armel, i386, src, dbgsym, lib)
	- after adding the archive and running apt update, install with apt install ircxmpp
	- edit the configuration file with environment variables in /etc/ircxmpp
	- run the service with service ircxmpp start, enable it at boot with systemctl enable ircxmpp
	- ci/cd: http://jenkins.sijanec.eu/job/ircxmpp for amd64, arm64 and armel

Security:
	- do not trust this program.
	- if you find a (security) vulnerability or any issue, please email anton@šijanec.eu.
	- whenever possible, run the program in a chroot jail as an unpriviledged user. Running with systemd (service ircxmpp start) does that.

Running multiple irc<->xmpp links at the same time:
	- first link's environment variables are still in format IX_JID, IX_PASS, IX_HOST and so on
	- second link's environment variables are in format IX_JID2, IX_PASS2, IX_HOST2 and so on
	- this means you concatenate the config environment variable with the digit
	- digits must be consecutive from 2 to infinity, vars without digit (1st link) are required
	- IX_LOOPDELAY applies to all links, as there is no delay between individual links (no 2, 3)

Compilation and manual install from source:
	- git clone https://git.sijanec.eu/sijanec/ircxmpp
	- cd ircxmpp
	- make		# tested compilers: gcc, clang and tcc. make -e CC=tcc, make -e CC=clang, ...
	- make install	# not required, but otherwise LD_LIBRARY_PATH=. ./ircxmpp for libircxmpp.so

Using as a library:
	- you may only use functions after #endif in ircxmpp.h, handler struct is opaque
	- after make install, ircxmpp.h and libircxmpp.so are placed in /usr/{include,lib}
	- #include <ircxmpp.h> and link with -lircxmpp
	- functions return nothing (except ircxmpp_init) and log to standard error
	- do not call ircxmpp_set_*() functions after first call to ircxmpp_run_once()
	- actual main function of the ircxmpp program is in ircxmpp.c between #else and #endif
	- in the 0.0.x stage, no binary compatiblity is guaranteed. nothing is guaranteed.

Gentoo/openrc?:
	- http://github.com/OpenRC/openrc/pull/517 needs to be merged before for increased security

 -- Anton Luka Šijanec <anton@sijanec.eu>  Fri, 29 Apr 2022 17:00:00 +0200