DOCSEARCHbyAlgolia
Submit Docs

Heisenbridge

repository·master·Indexed 43 days ago

https://github.com/hifi/heisenbridge

A bouncer-style Matrix IRC bridge that allows users to connect to IRC networks through Matrix. It supports two primary modes: Bouncer mode for 1:1 mapping between Matrix users and IRC connections, and Relaybot mode for relaying messages between a Matrix room and IRC. Compatible with Synapse, Dendrite, and Conduit homeservers.

Tokens
3.6K
Snippets
9
Records
12
Agent score
55%

What's inside Heisenbridge

  1. How Heisenbridge modes work: Bouncer vs Relaybot

    master

    Heisenbridge operates in two primary modes that change how users interact with IRC:

    Bouncer Mode

    In this mode, there is one direct Matrix user per IRC connection. The Matrix user's identity is directly mapped to IRC, giving them full control. There is no Matrix-side permission management; all interactions are between the Matrix user and the bridge. Multiple authorized Matrix users can use the bridge to create their own separate IRC connections.

    Relaybot Mode

    In this mode, the bridge acts as a single IRC connection for a larger Matrix room, relaying messages from Matrix to IRC. Matrix users' identities are relayed through their messages. Permissions are separate: the bridge must be explicitly invited to non-public Matrix rooms. A single authorized Matrix user manages the relaybot.

  4. Manage IRC networks via Matrix DM

    master

    Once Heisenbridge is running, you can manage it by sending Direct Messages (DMs) to @heisenbridge:your.homeserver.

    To get started, type heisenbridge: help in the DM.

    Example: Adding and connecting to a network

    1. ADDNETWORK IRCnet
    2. ADDSERVER IRCnet ssl.ircnet.io 6697 --tls
    3. OPEN IRCnet

    After running OPEN, you will be invited to a room where you can use CONNECT and JOIN #some-channel to interact with the IRC network.

    ADDNETWORK IRCnet
ADDSERVER IRCnet ssl.ircnet.io 6697 --tls
OPEN IRCnet

# Inside the resulting room:
CONNECT
JOIN #some-channel

  5. Production deployment considerations for docker-compose

    master

    The default docker-compose setup is intended for testing and uses startup scripts for self-configuration.

    For production use, it is advised to:

    1. Manually generate the registration file.
    2. Handle the registration file manually by placing it on a shared host volume.
    3. Ensure both services can access this shared volume at startup to avoid reliance on automatic startup scripts.

  6. Generate Matrix registration YAML

    master

    Heisenbridge requires a registration YAML file to share secrets with your Matrix homeserver (Synapse, Dendrite, or Conduit). Use the --generate flag for Synapse, or --generate-compat for Dendrite and Conduit.

    Note: Dendrite is not officially supported due to existing bugs in Dendrite; use Conduit if possible.

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

# For Dendrite or Conduit
python -m heisenbridge -c /path/to/config/heisenbridge.yaml --generate-compat
    python -m heisenbridge -c /path/to/synapse/config/heisenbridge.yaml --generate

  7. Configure Heisenbridge for Matrix Appservice

    master

    To run Heisenbridge as an appservice, follow these steps:

    1. Generate registration YAML using --generate (for Synapse) or --generate-compat (for Dendrite/Conduit).
    2. Configure Homeserver: Add the generated .yaml file to your homeserver's appservice list.
    3. Disable Default Encryption: Ensure your homeserver does not force encryption on all new rooms, as Heisenbridge does not support encryption. For Synapse, set encryption_enabled_by_default_for_room_type to off.
    4. Start Heisenbridge: Run the bridge using the --config flag pointing to the registration file.

    Network Connectivity: The homeserver and Heisenbridge must be able to communicate bi-directionally. By default, Heisenbridge expects the homeserver at http://localhost:8008 and listens on localhost:9898. If using Docker, you must provide the correct homeserver URL as a positional argument.

    TLS/HTTPS: Heisenbridge does not support loading TLS certificates directly. If running over the internet, place it behind a reverse proxy for TLS termination.

  8. Run Heisenbridge with docker-compose

    master

    You can use the provided docker-compose setup to quickly test Heisenbridge. This configuration is simplified and automatically self-configures itself upon startup.

    To start the services, run:

    docker-compose up

    Once the services are running, follow these steps to test the connection:

    1. Navigate to https://app.element.io.
    2. Change the homeserver setting to http://localhost:8008.
    3. Register a new account.
    4. Once logged in, send a Direct Message (DM) to @heisenbridge:localhost to test the IRC connection.

  9. Run Heisenbridge using Docker Compose

    master

    You can deploy Heisenbridge alongside a Matrix Synapse homeserver using the provided docker-compose.yml. The setup uses a shared volume synapse-data to allow Heisenbridge to access Synapse data.

    Service Configuration

    heisenbridge service

    • Image: hif1/heisenbridge:latest
    • Volumes:
      • ./init/heisenbridge-init.sh is mounted to /heisenbridge-init.sh as read-only (ro). This script serves as the container's entrypoint.
      • synapse-data is mounted to /data to provide access to the homeserver data.

    homeserver (Synapse) service

    • Image: matrixdotorg/synapse:latest
    • Environment Variables:
      • SYNAPSE_SERVER_NAME: Set to localhost by default.
      • SYNAPSE_REPORT_STATS: Set to 'no' by default.
    • Ports:
      • Maps host port 8008 to container port 8008.
    • Volumes:
      • ./init/synapse-init.sh is mounted to /synapse-init.sh as read-only (ro). This script serves as the container's entrypoint.
      • synapse-data is mounted to /data.

    Shared Volumes

    • synapse-data: A named volume used by both services to persist and share Matrix data.
    version: "3"
services:
  heisenbridge:
    image: hif1/heisenbridge:latest
    volumes:
      - ./init/heisenbridge-init.sh:/heisenbridge-init.sh:ro
      - synapse-data:/data
    entrypoint: /heisenbridge-init.sh
  homeserver:
    image: matrixdotorg/synapse:latest
    environment:
      SYNAPSE_SERVER_NAME: localhost
      SYNAPSE_REPORT_STATS: 'no'
    ports:
      - '8008:8008'
    volumes:
      - ./init/synapse-init.sh:/synapse-init.sh:ro
      - synapse-data:/data
    entrypoint: /synapse-init.sh
volumes:
  synapse-data:

  10. Configure the InspIRCd service

    master

    The inspircd service uses the inspircd/inspircd-docker:latest image and runs in host network mode. It includes configuration for IRC operator (oper) privileges via environment variables.

    Key environment variables:

    • INSP_OPER_HASH: The hashing algorithm used for the operator password (e.g., sha256).
    • INSP_OPER_PASSWORD_HASH: The hashed password for the operator account.
    • INSP_OPER_SSLONLY: Set to 'no' to allow non-SSL connections for operators.
    inspircd:
  image: inspircd/inspircd-docker:latest
  network_mode: host
  environment:
    INSP_OPER_HASH: 'sha256'
    INSP_OPER_PASSWORD_HASH: 'fcbe80d4d1bcc6f21964c75ea2e5d26cdd67642ed7187d6bde8aae180a093576'
    INSP_OPER_SSLONLY: 'no'

  11. Configure the Synapse service

    master

    The synapse service uses the matrixdotorg/synapse:latest image. It is configured to run in host network mode and uses a custom entrypoint script for initialization.

    Key environment variables:

    • SYNAPSE_SERVER_NAME: The server name for the Synapse instance (defaults to localhost in this config).
    • SYNAPSE_REPORT_STATS: Set to 'no' to disable reporting statistics.
    • UID / GID: Set to 1000 for user/group identification.

    Required volumes:

    • ./docker-compose/init/synapse-init.sh must be mounted to /synapse-init.sh as read-only (ro).
    • ./synapse-data is mounted to /data for persistent storage.
    synapse:
  image: matrixdotorg/synapse:latest
  network_mode: host
  environment:
    SYNAPSE_SERVER_NAME: localhost
    SYNAPSE_REPORT_STATS: 'no'
    UID: 1000
    GID: 1000
  volumes:
    - ./docker-compose/init/synapse-init.sh:/synapse-init.sh:ro
    - './synapse-data:/data'
  entrypoint: /synapse-init.sh

  12. Heisenbridge CLI Reference

    master

    The Heisenbridge CLI is used to manage the bridge process and configuration.

    Usage: python -m heisenbridge [options] [homeserver]

    Arguments:

    • homeserver: URL of the Matrix homeserver (default: http://localhost:8008).

    Options:

    • -c CONFIG, --config CONFIG: Path to the registration YAML file. Must be writable if generating.
    • -l LISTEN_ADDRESS, --listen-address LISTEN_ADDRESS: Bridge listen address (default: from config, or 127.0.0.1).
    • -p LISTEN_PORT, --listen-port LISTEN_PORT: Bridge listen port (default: from config, or 9898).
    • -u UID, --uid UID: User ID to run as.
    • -g GID, --gid GID: Group ID to run as.
    • -i, --identd: Enable identd service (default: False).
    • --identd-port IDENTD_PORT: Identd listen port (default: 113).
    • --generate: Generate registration YAML for Synapse.
    • --generate-compat: Generate registration YAML for Dendrite and Conduit.
    • --reset: Reset ALL bridge configuration from homeserver and exit.
    • --safe-mode: Prevent appservice from leaving invalid rooms on startup (for debugging).
    • -o OWNER, --owner OWNER: Set owner MXID (e.g., @user:homeserver) or the first talking local user will claim the bridge.
    • -v, --verbose: Logging verbosity (once for info, twice for debug).
    usage: python -m heisenbridge [-h] [-v] (-c CONFIG | --version)
                              [-l LISTEN_ADDRESS] [-p LISTEN_PORT] [-u UID]
                              [-g GID] [-i] [--identd-port IDENTD_PORT]
                              [--generate] [--generate-compat] [--reset]
                              [--safe-mode] [-o OWNER]
                              [homeserver]

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

options:
  -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)
  --version             show bridge version
  -l LISTEN_ADDRESS, --listen-address LISTEN_ADDRESS
                        bridge listen address (default: as specified in url in config, 127.0.0.1 otherwise) (default: None)
  -p LISTEN_PORT, --listen-port LISTEN_PORT
                        bridge listen port (default: as specified in url in config, 9898 otherwise) (default: None)
  -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 service (default: False)
  --identd-port IDENTD_PORT
                        identd listen port (default: 113)
  --generate            generate registration YAML for Matrix homeserver (Synapse)
  --generate-compat     generate registration YAML for Matrix homeserver (Dendrite and Conduit)
  --reset               reset ALL bridge configuration from homeserver and exit
  --safe-mode           prevent appservice from leaving invalid rooms on startup (for debugging) (default: False)
  -o OWNER, --owner OWNER
                        set owner MXID (eg: @user:homeserver) or first talking local user will claim the bridge (default: None)