Heisenbridge

a bouncer-style Matrix IRC bridge.

Heisenbridge brings IRC to Matrix by creating an environment where every user connects to each network individually like they would with a traditional IRC bouncer. Simplicity is achieved by exposing IRC in the most straightforward way as possible where it makes sense so it feels familiar for long time IRC users and prevents hiding protocol level events to help diagnose integration issues.

These compromises also mean that some IRC or Matrix features are managed with text commands rather than using the Matrix UI directly and some Matrix features that may seem to match IRC are not available anyway. Users on IRC should not know you are using Matrix unless you send media that is linked from your homeserver.

Please file an issue when you find something is missing or isn't working that you'd like to see fixed. Also bear in mind this project is still in very early stages of development so many things are missing or outright broken. Pull requests are more than welcome!

Support and development discussion in #heisenbridge:vi.fi

Use matrix-appservice-irc instead if you need to plumb rooms between Matrix and IRC seamlessly or need to connect large amounts of users.

Features

"zero configuration" - no databases or storage required
brings IRC to Matrix rather than Matrix to IRC - not annoying to folks on IRC
completely managed through admin room - just DM @heisenbridge!
channel management through bridge bot - type heisenbridge: help to get started!
online help within Matrix
access control for local and federated users
fully puppeted users from IRC, they come and go as they would on Matrix
tested with up to 2000 users in a single channel
optional public room plumbing with single puppeting Matrix <-> relay bot on IRC
IRCnet !channels are supported, you're welcome
any number of IRC networks and users technically possible
channel customization by setting the name and avatar
TLS support for networks that have it
customizable ident support
long message splitting directly to IRC
automatic identify/auth with server password or command on connect

Docker

The master branch is automatically published to Docker Hub:

docker pull hif1/heisenbridge
docker run --rm hif1/heisenbridge -h

Usage

usage: python -m heisenbridge [-h] [-v] -c CONFIG [-l LISTEN_ADDRESS]
                              [-p LISTEN_PORT] [-u UID] [-g GID] [-i]
                              [--generate] [--reset] [-o OWNER]
                              [homeserver]

a Matrix IRC bridge

positional arguments:
  homeserver            URL of Matrix homeserver (default:
                        http://localhost:8008)

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         logging verbosity level: once is info, twice is debug
                        (default: 0)
  -c CONFIG, --config CONFIG
                        registration YAML file path, must be writable if
                        generating (default: None)
  -l LISTEN_ADDRESS, --listen-address LISTEN_ADDRESS
                        bridge listen address (default: 127.0.0.1)
  -p LISTEN_PORT, --listen-port LISTEN_PORT
                        bridge listen port (default: 9898)
  -u UID, --uid UID     user id to run as (default: None)
  -g GID, --gid GID     group id to run as (default: None)
  -i, --identd          enable identd on TCP port 113, requires root (default:
                        False)
  --generate            generate registration YAML for Matrix homeserver
  --reset               reset ALL bridge configuration from homeserver and
                        exit
  -o OWNER, --owner OWNER
                        set owner MXID (eg: @user:homeserver) or first talking
                        local user will claim the bridge (default: None)

Install

Install Python 3.6 or newer

Install dependencies in virtualenv

virtualenv venv
source venv/bin/activate
pip install git+https://github.com/hifi/heisenbridge

Generate registration YAML

python -m heisenbridge -c /path/to/synapse/config/heisenbridge.yaml --generate

Add heisenbridge.yaml to Synapse appservice list
(Re)start Synapse

Start Heisenbridge

python -m heisenbridge -c /path/to/synapse/config/heisenbridge.yaml

Start a DM with @heisenbridge:your.homeserver to get online usage help

To update your installation, run pip install --upgrade git+https://github.com/hifi/heisenbridge

Develop

Install Python 3.6 or newer

Install dependencies

virtualenv venv
source venv/bin/activate
pip install -e .[dev,test]

(Optional) Set up pre-commit hooks
```
pre-commit install
```