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 documenation for additonal 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
:
-
If you have a Private Key file already, simply upload the file using this sections
Upload File
button, supplying a RSA PEM-formatted private key.
-
If you don't already have one, per the instructions provided in the section itself, you should generate this file by running the following command from within the IRC Bridges' config directory:
penssl genpkey -out passkey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048 ``
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:
-
postgres_fqdn:
Provide the URL to your Postgres setup -
postgres_user:
Provide the user that will be used to connect to the database -
postgres_db:
Provide the database you will connect to -
postgres_password:
Provide the password of the user specified above
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.
-
postgres_data_path:
This can be used to specify the path to the postgres db on the host machine -
postgres_port:
This can be used to specify a non-standard port, this defaults to5432
. -
postgres_sslmode:
This can be used to specify the sslmode for the Postgres connection, this defaults to'disable'
, however'no-verify'
and'verify-full
are available options
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 MXID's of your users who should be Admins of the IRC Bridge. You should list one MXID per line using the full MXID 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.
-
enable_provisioning:
Set this totrue
to enable the use ofprovisioning_rules:
-
provisioning_rules:
->userIds:
Use Regex to specifcy which User IDs to check for in existing rooms that are trying to be bridged-
exempt:
List any User IDs you do not want to prevent the bridging of a room, that would otherwise meet the match inconflict:
-
conflict:
Specify individual User IDs, or use Regex
-
-
provisioning_room_limit:
Specify the number of channels allowed to be bridged
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:
Set this totrue
to enable the use of IRC Ident -
ident_port_type:
Specify either'HostPort'
or'NodePort'
depending on your setup -
ident_port_number:
Specify the port number that should be used
enable_ident: false
ident_port_type: 'HostPort'
ident_port_number: 10230
Miscellaneous
Finally there are a few additional options to configure:
-
logging_level:
This specifies how detailed the logs should be for the bridge, by default this isinfo
, buterror
,warn
anddebug
are available.- You can see the bridge logs using
kubectl logs IRC_POD_NAME -n element-onprem
- You can see the bridge logs using
-
enable_presence:
Set totrue
if presence is required.- This should be kept as
false
if presence is disabled on the homeserver to avoid excess traffic.
- This should be kept as
-
drop_matrix_messages_after_seconds:
Specify after how many seconds the bridge should drop Matrix messages, by default this is0
meaning no messages will be dropped.- If the bridge is down for a while, the homeserver will attempt to send all missed events on reconnection. These events may be hours old, which can be confusing to IRC users if they are then bridged. This option allows these old messages to be dropped.
-
CAUTION: This is a very coarse heuristic. Federated homeservers may have different clock times which may be old enough to cause all events from the homeserver to be dropped.
-
bot_username:
Specify the Matrix User ID of the the bridge bot that will faciliate the creation of rooms and can be messaged by admins to perform commands.
-
rmau_limit:
Set this to the maximum number of remote monthly active users that you would like to allow in a bridged IRC room.
-
users_prefix:
Specifiy the prefix to be used on the Matrix User IDs created for users who are communicating via IRC.
-
alias_prefix:
Specifiy the prefix to be used on room aliases when created via the!join
command.
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 identation 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:
Specify your desired IRC Network
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.
Required 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.
-
name:
The server name to show on the bridge. -
botConfig:
-
enabled:
Keep this set astrue
-
nick:
Specify the nickname of the bot user within IRC -
username:
Specify the username of the bot user within IRC -
password:
Optionally specify the password of the bot to give to NickServ or IRC Server for this nick. You can generate this by using thepwgen 32 1
command -
joinChannelsIfNoUsers:
Set tofalse
to prevent the bot from joining channels even if there are no Matrix users on the other side of the bridge, this defaults totrue
so doesn't need to be specified unlessfalse
is required.
-
name: "Example IRC"
botConfig:
enabled: true
nick: "MatrixBot"
username: "matrixbot"
password: "some_password"
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.
-
additionalAddresses:
Specify any additional addresses to connect to that can be used for load balancing between IRCDs- Specify each additional address within the
[]
as comma-separated values, for example:-
[ "irc2.example.com", "irc3.example.com" ]
-
- Specify each additional address within the
-
onlyAdditionalAddresses:
Set totrue
to exclusively use additional addresses to connect to servers while reserving the main address for identification purposes, this defaults tofalse
-
port:
Specify the exact port to use for the IRC connection -
ssl:
Set totrue
to require the use SSL, this defaults tofalse
-
sslselfsign:
Set totrue
if the IRC network is using a self-signed certificate, this defaults tofalse
-
sasl:
Set totrue
should the connection attempt to identify via SASL, this defaults tofalse
-
allowExpiredCerts:
Set totrue
to allow expired certificates when connecting to the IRC server, this defaults tofalse
-
botConfig:
-
joinChannelsIfNoUsers:
Set tofalse
to prevent the bot from joining channels even if there are no Matrix users on the other side of the bridge, this defaults totrue
so doesn't need to be specified unlessfalse
is required.
-
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
# Whether to use SSL or not. Default: false.
ssl: true
# Whether or not IRC server is using a self-signed cert or not providing CA Chain
sslselfsign: false
# Should the connection attempt to identify via SASL (if a server or user password is given)
# If false, this will use PASS instead. If SASL fails, we do not fallback to PASS.
sasl: false
# Whether to allow expired certs when connecting to the IRC server.
# Usually this should be off. Default: false.
allowExpiredCerts: false
botConfig:
enabled: true
nick: "MatrixBot"
username: "matrixbot"
password: "some_password"
joinChannelsIfNoUsers: 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
.
Connecting to the Bridge
- From Element, send a DM to the bridge bot
/msg @ircbridgebot:element.local
whereelement.local
is you servers domain name - Send the bridge
!whois
to see if you can get logged in to the IRC network