Bridge Matrix to IRC

Updated 4 June 2019

Preparing a LXC container

We recommend setting up the bridge in a separate container according to the manual.

Installing software

Install NodeJS:

emerge -a net-libs/nodejs

Download the latest version of matrix-appservice-irc from github to /var/calculate:

git clone /var/calculate/matrix-appservice-irc

Install the application from /var/calculate/matrix-appservice-irc:

npm install

Configuring the bridge

Copy the contents of config.sample.yaml to config.yaml and apply the configuration:

  # The URL of the homeserver hosting media files. This is only used to transform
  # mxc URIs to http URIs when bridging[file|image] events. Optional. By
  # default, this is the homeserver URL, specified above.
  media_url: ""
  # The 'domain' part for user IDs on this home server. Usually (but not always)
  # is the "domain name" part of the HS URL.
  domain: ""
# Configuration specific to the IRC service
  # The address of the server to connect to.
    name: "FreeNode"
    # additionalAddresses: [ "" ]
      # Enable the presence of the bot in IRC channels.
      enabled: false
    # Configuration for mappings not explicitly listed in the 'mappings'
    # section.
    # The room alias template to apply when creating new aliases. This only
    # applies if createAlias is 'true'. The following variables are exposed:
    # $SERVER => The IRC server address (e.g. "")
    # $CHANNEL => The IRC channel (e.g. "#python")
    # This MUST have $CHANNEL somewhere in it.
    # Default: '#irc_$SERVER_$CHANNEL'
    aliasTemplate: "#freenode_$CHANNEL"
    # Configuration for controlling how Matrix and IRC membership lists are
    # synced.
      # Enable the syncing of membership lists between IRC and Matrix. This
      # can have a significant effect on performance on startup as the lists are
      # synced. This must be enabled for anything else in this section to take
      # effect. Default: false.
      enabled: true

          # Get a snapshot of all real IRC users on a channel (via NAMES) and
          # join their virtual matrix clients to the room.
          initial: true
          # Make virtual matrix clients join and leave rooms as their real IRC
          # counterparts join/part channels. Default: false.
          incremental: true
          # Get a snapshot of all real Matrix users in the room and join all of
          # them to the mapped IRC channel on startup. Default: false.
          initial: true
          # Make virtual IRC clients join and leave channels as their real Matrix
          # counterparts join/leave rooms. Make sure your 'maxClients' value is
          # high enough! Default: false.
          incremental: true
      # 1:many mappings from IRC channels to room IDs on this IRC server.
      # The matrix room must already exist. Your matrix client should expose
      # the room ID in a "settings" page for the room.
      "#chatexample": ["!"]
    # Configuration for virtual matrix users. The following variables are
    # exposed:
    # $NICK => The IRC nick
    # $SERVER => The IRC server address (e.g. "")
      # The user ID template to use when creating virtual matrix users. This
      # MUST have $NICK somewhere in it.
      # Optional. Default: "@$SERVER_$NICK".
      # Example: ""
      userTemplate: "@freenode_$NICK"
      # The display name to use for created matrix clients. This should have
      # $NICK somewhere in it if it is specified. Can also use $SERVER to
      # insert the IRC domain.
      # Optional. Default: "$NICK (IRC)". Example: "Alice (IRC)"
      displayName: "$NICK"
    # Configuration for virtual IRC users. The following variables are exposed:
    # $LOCALPART => The user ID localpart ("alice" in @alice:localhost)
    # $USERID => The user ID
    # $DISPLAY => The display name of this user, with excluded characters
    #             (e.g. space) removed. If the user has no display name, this
    #             falls back to $LOCALPART.
      # The template to apply to every IRC client nick. This MUST have either
      # $DISPLAY or $USERID or $LOCALPART somewhere in it.
      # Optional. Default: "M-$DISPLAY". Example: "M-Alice".
      nickTemplate: "$DISPLAY[m]"
      # The max number of IRC clients that will connect. If the limit is
      # reached, the client that spoke the longest time ago will be
      # disconnected and replaced.
      # Optional. Default: 30.
      maxClients: 150
      # A list of user modes to set on every IRC client. For example, "RiG" would set
      # +R, +i and +G on every IRC connection when they have successfully connected.
      # User modes vary wildly depending on the IRC network you're connecting to,
      # so check before setting this value. Some modes may not work as intended
      # through the bridge e.g. caller ID as there is no way to /ACCEPT.
      # Default: "" (no user modes)
      userModes: "R"

Generate a key to encrypt IRC user passwords:

openssl genpkey -out passkey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048

Generate a log file that allows the application to communicate with the Matrix server. Specify as the IRC bridge hostname:

node app.js -r -f registration_freenode.yaml -u "" -c config.yaml -l freenodebot

Copy this file to the Synapse server:

scp registration_freenode.yaml root@synapse:/var/calculate/synapse/

Add it to the Synapse configuration:

# A list of application service config file to use
  - registration_freenode.yaml

Restart Synapse:

/etc/init.d/synapse restart

Using an Ident server

To be able to bridge with an identification protocol, include Ident in the IRC configuration file:

    enabled: true
    port: 1113

For multiple users, [this patch] ( must be used:

curl -o token.patch

patch -p1 <token.patch

Starting the bridge

Create an OpenRC script to manage the Matrix IRC bridge daemon:

# Copyright 1999-2011 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

name="Matrix-IRC daemon"
description="Matrix IRC bridge daemon"
command_args="app.js -c config.yaml -f registration_freenode.yaml -p 9999"

depend() {
        need net

Set the

chmod 0755 /etc/init.d/matrix-irc-bridge

Launch the daemon:

/etc/init.d/matrix-irc-bridge start

Add it to autostart:

rc-update add matrix-irc-bridge