Use non-extra-payload algorthm for rooms that don't support it
Fix <<loop>> caused by accidental name shadowing
Detect presence from ghost using custom element
This is a "double-puppeting" bridge between two XMPP MUCs, which means it keeps userlist in sync across a certain number of MUC chatrooms, and enables private messages across MUC servers. As XMPP enables to join MUC servers effortlessly, that may sound pretty useless. However, if one of those MUCs bridged is actually a gateway/transport to another protocol (like biboumi for IRC), you may find it very useful.
cheogram-muc-bridge is currently alpha-quality software. Please try it out and contribute feedback and patches. See the list of Known issues, Getting help, and Contributing section.
cheogram-muc-bridge is currently not packaged for any distribution.
Alternatively, if you have a server with root access, and no web/XMPP services configured, you can setup cheogram-muc-bridge using ansible-selfhosted recipes (alpha software), like so:
# apt install ansible
# git clone https://codeberg.org/southerntofu/ansible-selfhosted infra
# cat << EOF > infra/config.yml
hostname: "example.com"
services: [ "mucbridge" ]
mucbridge:
nick: "my-own-bridge"
host: "bridge.example.com"
chans: # List of JIDs to bridge together
- [ { jid: "#foo@biboumi.example.net", tag: "net", nickChars: "Some \"a-z[]A-Z\"" }, { jid: "foo@muc.example.ml", tag: "ml", nickChars: "None Text" } ]
EOF
# cd infra
# roles/deploy.sh mucbridge
This assumes DNS records are already pointing to your server for example.com
and bridge.example.com
, and you don't have a firewall running.
You need to have cabal
(the Haskell build system) installed, as well as ghc
and c2hs
. In addition, you need the libxml2
, gnutls
, zlib
and gsasl
libraries installed. On debian, you can set it all up from the following packages: cabal-install libxml2-dev libgsasl7-dev gnutls-dev c2hs zlib1g-dev
Download the sources, build with cabal (Haskell build system). The built program will be in dist/build/gateway/gateway
:
$ git clone https://git.singpolyma.net/cheogram-muc-bridge
$ cd cheogram-muc-bridge
$ cabal update # Refresh packages list
$ cabal install --only-dependencies
$ cabal configure && cabal build
The built program, located in dist/build/gateway/gateway
can then be copied to wherever you desire on your system, for example /usr/local/bin/cheogram-muc-bridge
.
Now you can initialize the SQLite database using the sqlite3 CLI interface (sqlite3
package in Debian):
$ sqlite3 sqlite.db < schema.sqlite
ATTENTION: In addition to having write permissions to the file, SQLite expects to have write permissions on the parent folder. So you need to make sure the parent folder is readable by cheogram-muc-bridge as well! Otherwise, you may spot SQLite3 returned ErrorReadOnly while attempting to perform step: attempt to write a readonly database
despite the SQLite DB having correct permissions.
cheogram-muc-bridge requires its own XMPP domain to operate. If you have no other XMPP virtual hosts or component on a specific domain, you may reuse it to host cheogram-muc-bridge. Otherwise, you will need to add a new record pointing to the server where your Jabber/XMPP server is hosted.
Note: It is assumed cheogram-muc-bridge will run on the same machine as your Jabber/XMPP server, and connection can be established via localhost. Setting up the two services on different machines is beyond the scope of this document.
Now, you need to generate a passphrase which will be a shared secret between cheogram-muc-bridge and your Jabber/XMPP server, for example using cat /dev/urandom | tr -dc 'A-Za-z0-9@#$%&_+=' | head -c 64
. This secret will be used in the configuration file, as explained in the Configuration section. Now, how to configure the component depends on the server you use. In both cases, you need a valid TLS certificate for the component domain you intend to use.
ATTENTION: In addition to the configuration provided here, you need to make sure that cheogram-muc-bridge is reachable via your Jabber/XMPP server using a valid TLS certificate! How to setup a TLS certificate is beyond the scope of this document, as it is usually a requirement to operate your Jabber/XMPP server.
Component "mucbridge.example.com"
component_secret = "SECRET"
ssl = {
certificate = "/etc/letsencrypt/live/mucbridge.example.com/fullchain.pem",
key = "/etc/letsencrypt/live/mucbridge.example.com/privkey.pem"
}
In the section that says: '{listen,' add those two lines:
{5347, ejabberd_service, [{host, "mucbridge.example.com",
[{password, "SECRET"}]}]},
TODO: That is according to a tutorial found on ejabberd.im, but it does not mention TLS support! Please someone who knows ejabberd well propose better guidance.
Configuration is explained in the Configuration section of this README. You can find an example config file.
Now, you should be able to run cheogram-muc-bridge /path/to/config.dhall
. If you would like to deploy a service to make sure cheogram bridge is started when your machine boots, the instructions depend on your init system. In the examples below, we assume:
/usr/local/bin/cheogram-muc-bridge
/etc/cheogram/muc-bridge.dhall
cheogram/cheogram
The systemd service file should be placed in /etc/systemd/system/cheogram-muc-bridge.service
:
[Unit]
Description=cheogram-muc-bridge MUC2MUC bridge
After=network.target
[Service]
ExecStart=/usr/local/bin/cheogram-muc-bridge /etc/cheogram/muc-bridge.dhall
User=cheogram
Group=cheogram
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
Every time it is modified (or the first time it is created), you need to run systemctl daemon-reload
. Then, you can make sure the service is enabled at boot time with systemctl enable cheogram-muc-bridge
and/or start it immediately with systemctl start cheogram-muc-bridge
.
You can find an example configuration file in the config.dhall.example file. It can have the following options:
[]
if the nickChars allows it on the other sides; illegal characters are replaced with _
Some "a-zA-Z[]"
for IRC); None Text
does not place any special restrictionsNone Natural
for no limit.cheogram-muc-bridge is alpha-quality software. Just because we haven't found a bug yet doesn't mean it's not there, so don't hesitate to report bugs so they can be fixed. Below, you will find a list of issues we are aware of:
user[foo][bar][foo]
; this bug is currently being investigated (July 2021)tag
on a chan is deemed illegal by another chan's nickChars
, no warning is currently producednickChars = None Text
does not enforce that illegal JID characters are prevented; in the future, such characters should be properly escaped as explained in XEP-0106 or entirely forbiddenPart of the soprani.ca family of projects.
If you have any questions about this project, or wish to report a bug, please send email to: dev@singpolyma.net
You may come discuss the project in our chatroom: xmpp:discuss@conference.soprani.ca?join
If you have code or patches you wish to contribute, the maintainer's preferred mechanism is a git pull request. Push your changes to a git repository somewhere, for example:
git remote rename origin upstream
git remote add origin git@git.sr.ht:~yourname/cidfd
git push -u origin master
Then generate the pull request:
git fetch upstream master
git request-pull -p upstream/master origin
And copy-paste the result into a plain-text email to: dev@singpolyma.net
You may alternately use a patch-based approach as described on https://git-send-email.io
Contributions follow an inbound=outbound model -- you (or your employer) keep all copyright on your patches, but agree to license them according to this project's COPYING file.
This program is released under the AGPLv3 license. You can find a copy in the COPYING file.