0.0.1

1 files changed, 66 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..437edbd
--- /dev/null
+++ b/README
@@ -0,0 +1,66 @@
+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
+
+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.
+
+Debian installation and systemd service:
+	- this program is packaged in my personal package archive on http://prog.sijanec.eu/
+	- 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
+
+Security:
+	- Do not trust this program.
+	- If you find a (security) vulnerability or any issue, please email anton at šijanec.eu
+	- Whenever possible, run the program in a chroot jail as an unpriviledged user. Running with systemd (service ircxmpp start) does that.
+
+ -- Anton Luka Šijanec <anton@sijanec.eu>  Wed, 27 Apr 2022 14:30:00 +0200