Setting Up the IRC Bridge

Matrix IRC Bridge

The Matrix IRC Bridge is an IRC bridge for Matrix that will pass all IRC messages through to Matrix, and all Matrix messages through to IRC. Please also refer to the bridges' specific documentation for additional guidance.

For usage of the IRC Bridge via it's bot user see Using the Matrix IRC Bridge documentation.

Installation and Configuration

From the Installer's Integrations page find the IRC Bridge entry, and click Install.This will setup the IRC Bridges' config directory, by default this will be located:

~/.element-enterprise-server/config/legacy/ircbridge

You will initially be taken to the bridges configuration page, for any subsequent edits, the Install button will be replaced with Configure, indicating the bridge is installed.

There are two sections of the Matrix IRC Bridge configuration page, the Bridge.yml section, and a section to Upload a Private Key. We'll start with the latter as it's the simplest of the two, and is referenced in the first.

Upload a Private Key

As the bridge needs to send plaintext passwords to the IRC server, it cannot send a password hash, so those passwords are stored encrypted in the bridge database. When a user specifies a password to use, using the admin room command !storepass server.name passw0rd, the password is encrypted using a RSA PEM-formatted private key. When a connection is made to IRC on behalf of the Matrix user, this password will be sent as the server password (PASS command).

Therefore you will need a Private Key file, by default called passkey.pem:

The Bridge.yml Section

The Bridge.yml is the complete configuration of the Matrix IRC Bridge. It points to a private key file (Private Key Settings), and both configures the bridges' own settings and functionality (Bridge Settings), and the specific IRC services you want it to connect with (IRC Settings).

Private Key Settings

key_file: passkey.pem

By default this is the first line in the Bridge.yml config, it refers to the file either moved into the IRC Bridges' config directory, or generated in there using openssl. If moved into the directory ensure the file was correctly renamed to passkey.pem.

Bridge Settings

The rest of the configuration sits under the bridged_irc_servers: section:

bridged_irc_servers:

You'll notice all entries within are initially indented ( ) so all code blocks will include this indentation. Focusing on settings relating to the bridge itself (and not any specific IRC connection) covers everything except the address: and associated parameters: sections, by default found at the end of the Bridge.yml.

Postgres

If you are using postgres-create-in-cluster you can leave this section as-is, the default ircbridge-postgres / ircbridge / postgres_password values will ensure your setup works correctly.

- postgres_fqdn: ircbridge-postgres
  postgres_user: ircbridge
  postgres_db: ircbridge
  postgres_password: postgres_password

Otherwise you should edit as needed to connect to your existing Postgres setup:

You can uncomment the following to use as needed, note if unspecified some of these will default to the advised values, you do not need to uncomment if you are happy with the defaults.

For example, your Postgres section might instead look like the below:

- postgres_fqdn: https://db.example.com
  postgres_user: example-user
  postgres_db: matrixircbridge
  postgres_password: example-password
  # postgres_data_path: "/mnt/data/<bridged>-postgres"
  postgres_port: 2345
  postgres_sslmode: 'verify-full'
IRC Bridge Admins

Within the admins: section you will need to list all the Matrix User ID's of your users who should be Admins of the IRC Bridge. You should list one Matrix User ID per line using the full Matrix User ID formatted like @USERNAME:HOMESERVER

  admins:
  - "@user-one:example.com"
  - "@user-two:example.com"
Provisioning

Provisioning allows you to set specified rules about existing room when bridging those rooms to IRC Channels.

So the example bridge.yml config below will block the bridging of a room if it has any User IDs within it from the badguys.com homeserver except @doubleagent:badguys.com, and limit the number of bridged rooms to 50.

  enable_provisioning: true
  provisioning_rules:
    userIds:
      exempt:
        - "@doubleagent:badguys.com"
      conflict:
        - "@.*:badguys.com"
  provisioning_room_limit: 50
IRC Ident

If you are using the Ident protocol you can enable it usage with the following config:

  enable_ident: false
  ident_port_type: 'HostPort'
  ident_port_number: 10230
Miscellaneous

Finally there are a few additional options to configure:

The defaults are usually best left as-is unless a specific need requires changing these, however for troubleshooting purposes, switching logging_level to debug can help identify issues with the bridge.

  logging_level: debug
  enable_presence: false
  drop_matrix_messages_after_seconds: 0
  bot_username: "ircbridgebot"
  rmau_limit: 100
  users_prefix: "irc_"
  alias_prefix: "irc_"
Advanced Additional Configuration

You can find more advanced configuration options by checking the config.yaml sample provided on the Matrix IRC Bridge repository.

You can ignore the servers: block as config in that section should be added under the parameters: section associated with address: that will be setup per the below section. If you copy any config, ensure the indentation is correct, as above, all entries within are initially indented ( ), so they are under the bridged_irc_servers: section.

IRC Settings

The final section of Bridge.yml, here you specify the IRC network(s) you want the bridge to connect with, this is done using address: and parameter: formatted like so:

  address: irc.example.com
  parameters:

Aside from the address of the IRC Network, everything is configured within the parameters: section, and so is initially indented , all code blocks will include this indentation.

Basic IRC Network Configuration

At a minimum, you will need to specify the name: of your IRC Network, as well as some details for the bots configuration on the IRC side of the connection, you can use the below to get up and running.

    name: "Example IRC"
    botConfig:
      enabled: true
      nick: "MatrixBot"
      username: "matrixbot"
      password: "some_password"
Advanced IRC Network Configuration (Load Balancing, SSL, etc.)

For more fine-grained control of the IRC connection, there are some additional configuration lines you may wish to make use of. As these are not required, if unspecified some of these will default to the advised values, you do not need to include any of these if you are happy with the defaults. You can use the below config options, in addition to those in the section above, to get more complex setups up and running.

If you end up needing any of these additional configuration options, your parameters: section may look like the below example:

    name: "Example IRC"
    additionalAddresses: [ "irc2.example.com" ]
    onlyAdditionalAddresses: false
    port: 6697
    ssl: true
    sslselfsign: false
    sasl: false
    allowExpiredCerts: false
    botConfig:
      enabled: true
      nick: "MatrixBot"
      username: "matrixbot"
      password: "some_password"
      joinChannelsIfNoUsers: true
Mapping IRC user modes to Matrix power levels

You can use the configuration below to map the conversion of IRC user modes to Matrix power levels. This enables bridging of IRC ops to Matrix power levels only, it does not enable the reverse. If a user has been given multiple modes, the one that maps to the highest power level will be used.

    modePowerMap:
      o: 50
      v: 1
Configuring DMs between users

By default private messaging is enabled via the bridge and Matrix Direct Message rooms can be federated. You can customise this behaviour using the privateMessages: config section.

    privateMessages:
      enabled: true
      federate: true
Mapping IRC Channels to Matrix Rooms

Whilst a user can use the !join command (if Dynamic Channels are enabled) to manually connect to IRC Channels, you can specify mappings of IRC Channels to Matrix Rooms, 1 Channel can be mapped to multiple Matrix Rooms, up-front. The Matrix Room must already exist, and you will need to include it's Room ID within the configuration - you can get this ID by using the 3-dot menu next to the room, and opening Settings.

See the below example configuration for mapping the #welcome IRC Channel:

    mappings:
      "#welcome":
        roomIds: ["!exampleroomidhere:example.com"]
Allowing !join with Dynamic Channels

If you would like for users to be able to use the !join command to join any allowed IRC Channel you will need to configure dynamicChannels:.

You may remember you set an alias prefix in the Miscellaneous section above. If you wish to fully customise the format of aliases of bridged rooms you should remove that `alias_prefix:` line. However the only benefit to this would be to add a suffix to the Matrix Room alias so is not recommended.

In addition you could also specify the below, though it is unlikely you should need to specify the exact Matrix Room Version to use.

    dynamicChannels:
      enabled: true
      createAlias: true
      published: true
      useHomeserverDirectory: true
      joinRule: invite
      federate: true
      aliasTemplate: "#irc_$CHANNEL"
      whitelist:
        - "@foo:example.com"
        - "@bar:example.com"
      exclude: ["#foo", "#bar"]
Exclude users from using the bridge

Using the excludedUsers: configuration you can specify Regex to identify users to be kicked from any IRC Bridged rooms.

    excludedUsers:
      - regex: "@.*:evilcorp.com"
        kickReason: "We don't like Evilcorp"
Syncing Matrix and IRC Membership lists

To manage and control how Matrix and IRC membership lists are synced you will need to include membershipLists: within your config.

Within membershipLists: are the following sections, global:, rooms:, channels: and ignoreIdleUsersOnStartup:. For global:, rooms:, channels: you can specify initial:, incremental: and requireMatrixJoined: which all default to false. You can configure settings globally, using global:, or specific to Matrix Rooms with rooms: or IRC Channels via channels:.

The last section is ignoreIdleUsersOnStartup: which determines if the bridge should ignore users which are not considered active on the bridge during startup.

    membershipLists:
      enabled: false
      floodDelayMs: 10000

      global:
        ircToMatrix:
          initial: false
          incremental: false
          requireMatrixJoined: false

        matrixToIrc:
          initial: false
          incremental: false
          
      rooms:
        - room: "!fuasirouddJoxtwfge:localhost"
          matrixToIrc:
            initial: false
            incremental: false

      channels:
        - channel: "#foo"
          ircToMatrix:
            initial: false
            incremental: false
            requireMatrixJoined: false

      ignoreIdleUsersOnStartup:
        enabled: true
        idleForHours: 720
        exclude: "foobar"
Configuring how IRC users appear in Matrix

As part of the bridge IRC users and their messages will appear in Matrix as Matrix users, you will be able to click on their profiles perform actions just like any other user. You can configure how they are display using matrixClients:.

You may remember you set a user name prefix in the Miscellaneous section above. If you wish to fully customise the format of your IRC users' Matrix User IDs you should remove that `users_prefix:` line. However the only benefit to this would be to add a suffix to the Matrix User ID so is not recommended.

    matrixClients:
      userTemplate: "@irc_$NICK"
      displayName: "$NICK"
      joinAttempts: -1
Configuring how Matrix users appear in IRC

As part of the bridge Matrix users and their messages will appear in IRC as IRC users, you will be able to perform IRC actions on them like any other user. You can configure how this functions using ircClients:.

You can also optionally configure the following, they do not need to be included in your config if you are not changing their default values.

    ircClients:
      nickTemplate: "$DISPLAY[m]"
      allowNickChanges: true
      maxClients: 30
      # ipv6:
      #   only: false
      idleTimeout: 10800
      reconnectIntervalMs: 5000
      concurrentReconnectLimit: 50
      lineLimit: 3
      realnameFormat: "mxid"
      # pingTimeoutMs: 600000
      # pingRateMs: 60000
      kickOn:
        channelJoinFailure: true
        ircConnectionFailure: true
        userQuit: true

Deploying the IRC Bridge

Once you have make the required changes to your Bridge.yml configuration, make sure you find and click the Save button at the bottom of the IRC Bridge configuration page to ensure your changes are updated.

You will then need to re-Deploy for any changes to take effect, as above ensure all changes made are saved then click Deploy.

Using the Bridge

For usage of the IRC Bridge via it's bot user see Using the Matrix IRC Bridge documentation, or for end user focused documentation see Using the Matrix IRC Bridge as an End User.

If you have setup mapping of rooms in your Bridge.yml, some rooms will already be connected IRC, users need only join the bridged room and start messaging. IRC users should see Matrix users in the Channel and be able to communicate with them like any other IRC user.


Revision #16
Created 31 October 2022 17:02:07 by Karl Abbott
Updated 7 September 2023 13:18:57 by Kieran Mitchell Lane