Skip to content

Setting Up Bridge To Freenode

Jason Kridner edited this page Mar 10, 2021 · 2 revisions

This is a guide that tries to explain how to configure the bridge between Matrix and the Freenode IRC network step by step.

Some Freenode channels accept only registered users, and in order to bridge properly you should register two users. First you should register user, you will use for communication, and, second you need to register a user for your bridge bot.

Initial setup and config example.

Let's imagine your homeserver have been set up at example.com domain and your user name is user.

First you should follow the basic installation instructions, we will repeat here. Follow this HOWTO using this server section sample as an inspiration.

  servers:
    chat.freenode.net:        ############## CHANGE THIS #############
      name: "FreeNode Server" ############## CHANGE THIS #############
      port: 6697
      ssl: true
      sslselfsign: false
      sasl: false
      sendConnectionMessages: true
      quitDebounce:
        enabled: false
        quitsPerSecond: 5
        delayMinMs: 3600000 # 1h
        delayMaxMs: 7200000 # 2h
      modePowerMap:
        o: 50
        v: 1
      botConfig:
        nick: "ExampleComBot"                                         ############## CHANGE THIS #############
        password: "erjlwerkjlkertjlwtwrketjrlewtjrlewtjrewterwterty"  ############## CHANGE THIS #############
        joinChannelsIfNoUsers: true
      privateMessages:
        enabled: true
        federate: true
      dynamicChannels:
        enabled: true
        createAlias: true
        published: true
        joinRule: public
        groupId: +myircnetwork:localhost
        federate: true
        aliasTemplate: "#_freenode_$CHANNEL"  ############## CHANGE THIS #############
      membershipLists:
        enabled: false
        floodDelayMs: 10000
        global:
          ircToMatrix:
            initial: false
            incremental: false
          matrixToIrc:
            initial: false
            incremental: false
        rooms:
          - room: "!fuasirouddJoxtwfge:localhost"
            matrixToIrc:
              initial: false
              incremental: false
        channels:
          - channel: "#foo"
            ircToMatrix:
              initial: false
              incremental: false
      mappings:
        "#thepub":
          roomIds: ["!kieouiJuedJoxtVdaG:localhost"]
      matrixClients:
        userTemplate: "@_freenode_$NICK" ############## CHANGE THIS #############
        displayName: "$NICK (IRC)"
        joinAttempts: -1
      ircClients:
        nickTemplate: "$DISPLAY[m]" 
        allowNickChanges: true
        maxClients: 30
        ipv6:
          only: false
        idleTimeout: 10800
        reconnectIntervalMs: 5000
        concurrentReconnectLimit: 50
        lineLimit: 3

Important lines are marked with CHANGE THIS sign.

First you should set irc server host and give it some name.

Then set up nick and password for your bridge bot. Nick for a bridge but should be unique, choose a name nobody will use but you. Bot suffix will be appreciated. But do not make nick too long, it's length is quite limited. We will register that nick later.

Then change aliasTemplate: and userTemplate:. Using a _freenode prefix is a kind of tradition. So you can just copy these lines to your config, if you do not want some custom names for bridged rooms and users.

Registering a bot nick

Freenode has quite strict rules about registration. They do not allow nick being logged in twice, and they do not allow to register more then two nicks per e-mail. So if you have some nick already registered for your e-mail, you better prepare a new e-mail for registering your bot.

So check, that your bridge is not running and not connected to irc using bot's nick, find some irc-chat program, and connect to freenode using your bot nick. Web chat https://webchat.freenode.net/ can be a good solution. Do not provide a password, since it is not registered yet, and connect to #freenode room.

Once we connected we will interact with NickServ bot using \msg command in order to register our bot nick. Issue a command

/msg NickServ REGISTER YourPasswordFromConfigFile [email protected]

you will receive a private message from NickServ saying, about confirming your e-mail in order to complete the registration.

You will get a e-mail a verification code and instruction to send another command to NickServ bot:

/msg NickServ VERIFY REGISTER YourBridgeBotName veRiFicaTi0NcOde

After that log out from chat, so your bot nick was not in use, run back your bridge, and check that your log now has lines like these:

INFO:BridgedClient <[email protected]#jf2sl5fzeuo00> Connecting to IRC server chat.freenode.net as YourBridgeBotName (user=matrixirc)
......
INFO:req onPrivateMessage: chat.freenode.net from=NickServ ([email protected]) to=YourBridgeBotName ([email protected]) action={"type":"notice","text":"This nickname is registered. Please choose a different 
INFO:req [9wqzev2ot8s00] [[I->M] ] Ignoring non-message PM
INFO:req onPrivateMessage: chat.freenode.net from=NickServ ([email protected]) to=YourBridgeBotName ([email protected]) action={"type":"notice","text":"You are now identified for \u0002YourBridgeBotName\u0002

If you have this You are now identified for message there, then we managed successfully register and configure bridge bot.

Registering your own nick and joining the channel

If you want to write something to an IRC channel, you will need your' own nick. You can't use your matrix ID to write a channel, so you need to register a nick at IRC server, and let IRC bridge know about that nick so it will map it to your matrix account. And when you are writing to a bridged room from your matrix account, bridge bot will send this message to an IRC room using that IRC nick of yours, that is mapped to your matrix ID.

Here we will interact with two entities. First is NickServ bot that works in the IRC server. We've used it to register a bot nick in previous section, and now we will use it to register your own nick. Second is your irc bridge bot. We will use it for looking at your bridging status, and to save your password.

Registering own nick using NickServ

At the previous section we used an IRC chat app, to register a nick name. Now we will use our bridge to communicate with FreeNode NickServ. To do that you need to create a direct message chat with a user @_freenode_NickServ:example.com (Replace example.com with your own matrix domain. If you set a custom userTemplate while configuring the bridge replace @_freenode_ with what you have written in the template)

If everything goes ok, you will successfully join the chat. It is the very same NickServ bot we've communicated in previous section, now we are talking with him using out bridge. You can issue a HELP command to check that everything works well.

Now it is a time to register a nick for you. First issue a command

INFO

and you will see what nick you are using now while chatting with NickServ. It should be like DiplayName[m]. We will try to register it. In order to do that type

REGISTER MyAcc0unTpAssWword [email protected]

replacing MyAcc0unTpAssWword with a password you will use for a nick and [email protected] with your own e-mail. As you can see your nick is not mentioned here. We are registering your current nick, that you've seen typing INFO command.

If NickServ replies you, that your account name is already occupied, you can change you desired nick using IDENTIFY MyUniqName[m] command and then try to register it again.

The second case where it can go wrong: FreeNode allows to register only two nicks per e-mail. So If you gen such a reply just use another e-mail.

If everything went right, and you get positive reply from NikcServ go, check your e-mail for a verification code, and type it as it is advised in the verification letter, (though ignoring /msg NickServ part):

VERIFY REGISTER DiplayName[m] AnotHeRveRiFicaTi0NcOde

Communicating with bridge bot

To find out the bridge bot ID, you should look into my_registration_file.yaml you've created while installing matrix-appservice-irc, and find sender_localpart option there. If you changed nothing, it would be my_bot, and so your bot ID is @[email protected] (Where example.com is your matrix domain). Create personal chat with that bot, and issue it a command !help. If it replies you with some sensible reply, everything works ok.

First thing you'd better do, is to tell bot to store your password for your IRC nick, so you do not need to identify yourself when you reconnect. To do that type

!storepass chat.freenode.net MyAcc0unTpAssWword

then your password will be stored for your FreeNode IRC nickname, and will be used automatically by a bridge bot when you are back again.

Then you can join FreeNode IRC channel. Let's say it is ##Linux (But please join some channel you really want to join). To join say to the bridge bot

!join ##linux

(once again replace ##Linux with a channel you need), and on the same instance, bridge bot will bridge that channel to a matrix chat room, and you will be automatically invited to it. Just accept the invitation.

Now you can chat as much as you can.

P.S. Please remember that FreeNode is very strict about being logged in, registration, and so on, and it use quite short nick names. If something goes wrong (both with bot nick or with own nick) check what nicks you are actually using, check it with NickServ (from own nick) or read logs carefully (for bot nick). If something is wrong with bot nick, the only way to know about it is an appservice log. So have a fun! :-)