Using the 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.

If you're an end user of the bridge, it's unlikely you will need to use the below commands, your IRC Channels may already be bridged to specific Matrix Rooms so you can simply join the Room from Matrix, or the Channel from IRC and communicate with Matrix/IRC users. Our End User focused documentation might be better suited to getting started with Matrix and IRC - Using the Matrix IRC Bridge as an End User

Please also refer to the Bridge Documentation for additional guidance.

The bridge is currently used on the matrix.org homeserver to bridge a number of popular IRC networks.

Getting Started with the Matrix IRC Bridge

In this guide we will be using the Matrix.org bridge to the Open and Free Technology Community (OFTC) IRC network. The key information to note is the Room alias format (#_oftc_#channame:matrix.org) and Appservice user (@oftc-irc:matrix.org). Though note this may differ from time of writing, check the link above to up-to-date details.

The Appservice user is the bot that interacts with the bridge, from a Direct Message with this user you will issue commands to connect to the desired channels and perform specific functions. First, invite the user to a DM:

Using @oftc-irc:matrix.org we start a chat, your first message can be anything to create the room. The bot should join the room and then be responsive to commands.

Matrix IRC Bridge Bot Command Overview

Commands to the bot are prefixed with !, to get started try !help, which should result in the bot listing out the available commands for use. You should see something like the below:

Actions

• !cmd [irc.example.net] COMMAND [arg0 [arg1 [...]]]: Issue a raw IRC command. These will not produce a reply.(Note that the command must be all uppercase.)
• !feature feature-name [true/false/default]: Enable, disable or default a feature's status for your account.Will display the current feature status if true/false/default not given.
• !join [irc.example.net] #channel [key]: Join a channel (with optional channel key)
• !nick [irc.example.net] DesiredNick: Change your nick. If no arguments are supplied, your current nick is shown.
• !quit: Leave all bridged channels, on all networks, and remove your connections to all networks.
• !active: Mark yourself as active, which will exclude you from any idleness kicks.

Authentication

• !storepass [irc.example.net] passw0rd: Store a NickServ OR SASL password (server password)
• !reconnect [irc.example.net]: Reconnect to an IRC network.
• !removepass [irc.example.net]: Remove a previously stored NickServ password
• !username [irc.example.net] username: Store a username to use for future connections.

Info

• !bridgeversion: Return the version from matrix-appservice-irc bridge.
• !listrooms [irc.example.net]: List all of your joined channels, and the rooms they are bridged into.
• !whois [irc.example.net] NickName|@alice:matrix.org: Do a /whois lookup. If a Matrix User ID is supplied, return information about that user's IRC connection.

Management

These commands only work for bridge administrators.

• !unlink !room:example.com irc.example.net #foobar: Unlink an IRC channel from a Matrix room. You need to be a moderator of the Matrix room or an administrator of this bridge.

• !plumb !room:example.com irc.network.net #channel: This command allows you to plumb a IRC channel into a room without using the HTTP provisioning API. This command does NOT validate that you have permission to do this on the IRC channel so please take care to ensure that the IRC channel is aware of your actions. You must invite the bridge bot into the Matrix room for this to work.

Using the Matrix IRC Bridge

Depending on your bridge setup you may have multiple IRC Networks accessible from your IRC Bridge bot, if so, you will need to specify the IRC Network after the each command. This guide is using @oftc-irc:matrix.org which is dedicated to the W3C IRC network so commands do not need to specify.

For any command given arguments wrapped in [] are optional, make sure to specify them if required for your usecase.

Joining a IRC Channel

The most basic usage of the bridge is to join IRC channels to talk with IRC users, you can do this with the !join command. Simply specify the channel you'd like the join:

• !join [irc.example.net] #channel [key]

The first time you run such a command, the bot will connect to the IRC network, then inform you that you are connected. The nickname your user appears as in IRC is dependant on the bridge's configuration. Using the example above, you can see [m] has been appended to the users Matrix display name.

If the Channel you are joining hasn't yet been joined via the bot, it will create a Matrix room linking it with the IRC Channel. If the room already exists, the command will simply invite you to the already created room. Likewise, if the Channel doesn't yet exist on the IRC Network, it will be created and your user sent an invite.

You will then recieve an invite to a Matrix room, connected to that IRC Channel.

Once you've joined the room, you can then communicate with others within the channel.

Listing joined IRC Channels

After joining a number of IRC Channels you may want to retrieve a list of all the Channels you are joined to, and the associated Matrix rooms. You can do this with the !listrooms command. The bot will respond including clickable links to jump straight to the Matrix room.

• !listrooms [irc.example.net]

Staying active

You can use the !active command to mark yourself as active, which will exclude you from any idleness kicks.

Changing your Nickname

To change the nickname presented to IRC users, simply use !nick. Provide your desired nickname and it will be updated on the IRC Network, you can also not provide any nickname for the bot to output your current nickname.

• !nick [irc.example.net] DesiredNick

Finding out more information on IRC / Matrix users

You can use the !whois command, supplying either a Matrix ID to retrieve their IRC nickname, or a IRC nickname to information on what channels that user is in. The !whois command is also useful to test your connection to the IRC network, supply your own Matrix ID and if there's any issues with the connection the command will produce an error.

• !whois [irc.example.net] NickName|@alice:matrix.org

Direct Messaging between Matrix and IRC

You can start a DM with an IRC user by simply clicking there profile icon from an existing room linked to an IRC Channel. Then from their profile panel, click Message to start a chat. Enter a message to create the room (note they will not see this message), then wait for there user to join the room - once joined, you can send a message which will then be sent to the IRC user.

IRC users can also start DMs with Matrix users, they can do this by double clicking the Matrix users' name within the participants list of a channel, or if supported by your client, using the /query NICKNAME or /msg NICKNAME MESSAGE commands. Once a message is sent, the Matrix user will receive an invite from them to start chatting.

If you know the configuration of your bridge (or by checking existing IRC users), you can also manually start a DM with a user. Simply start a new chat using the username format the bridge uses. In the example above we can see that the format is @_oftc_NICKNAME:matrix.org. So we can initiate chats with any nickname by following that format.

Leaving an IRC Channel

Leaving a Channel is simply a case of leaving the Matrix room. Find the room in the Left Panel, hoover over its name, then click the 3-dot menu then Leave.

Leaving all IRC Channels

If you wish to disconnect from IRC and leave all Channels (/ Matrix linked rooms) you can simply issue the !quit command. Doing so will remove you from all the rooms, you can find them again at the bottom of the Left Panel under Historical.

Advanced Bridge Usage

IRC Authentication

If you need to join the IRC Network using authentication credentials you will need to use the !storepass and possibly !username commands. With these you can set NickServ / SASL password and username respectively. Once completed, simply use !reconnect to rejoin the network with the provided credentials.

• !storepass [irc.example.net] passw0rd
• !username [irc.example.net] username
• !reconnect [irc.example.net]

You can also remove your stored password using, you will then need to use !reconnect to rejoin without the credential:

• !removepass [irc.example.net]

Troubleshooting bridge problems

If you are encountering issues with the bridge, first try using !reconnect, to see if disconnecting and reconnecting solves your issues. Otherwise !bridgeversion is a useful command to advise the version of the bridge. Supply this information, alongside any debug logs to the administrator of the bridge to help them troubleshoot your issue.

Sending raw IRC commands

It's possible to use the bot to issue raw IRC commands, to do so you'll need to use !cmd, followed by the commmand (in CAPS) and any additional arguments. Unless there is an error with the command, sending !cmd will not produce a reply.

• !cmd [irc.example.net] COMMAND [arg0 [arg1 [...]]]

For example, if you wanted to send a private message without creating DM in Matrix, you could use the /PRIVMSG IRC command. To do so you'd send:

!cmd PRIVMSG USERNAME MESSAGE

The recipient will then receive the message, but a room in Matrix wont have been created.

Unlinking an IRC channel from a Matrix room

In order to unlink a channel you will need to use the !unlink command, followed by the matrix room ID, IRC network and channel name. To successfully perform this action you will need to be a moderator of the Matrix room or an administrator of the bridge.

• !unlink !room:example.com irc.example.net #foobar

You can find the matrix room id by accessing the room's settings page, then within the Advanced section you will find the Internal Room ID.