Git Product home page Git Product logo

matrix-appservice-irc's Introduction

Matrix <--> IRC Bridge

Build Status

This is an IRC bridge for Matrix using the Application Services (AS) API. If you're upgrading from an old release, be sure to read the CHANGELOG as there may be breaking changes between releases.

This bridge will pass all IRC messages through to Matrix, and all Matrix messages through to IRC. It is highly configurable and is currently used on the matrix.org homeserver to bridge a number of popular IRC networks including Freenode and Moznet.

Setup

There are 4 stages to setting up the IRC bridge which are outlined below.

For more information, check out the how-to guide.

WARNING: You should seek permission from the operator of the bridged IRC network before running this bridge. Bridging may be against the IRC network's Terms of Use.

1. Installation

To install all dependencies and add a binary matrix-appservice-irc:

 $ npm install matrix-appservice-irc --global

Alternatively, git clone this repository on the master branch, then run npm install. If you use this method, the bridge can be run via node app.js.

Requirements

  • Node.js v6.9 or above.
  • A Matrix homeserver you control running Synapse v0.18.5-rc3 or above.

2. Configuration

The bridge must be configured before it can be run. This tells the bridge where to find the homeserver and how to bridge IRC channels/users.

  • Copy config.sample.yaml to config.yaml.
  • Modify config.yaml to point to your homeserver and IRC network of choice.

For more information, check out the how-to guide and/or the sample config.

3. Registration

The bridge needs to generate a registration file which can be passed to the homeserver to tell the homeserver which Matrix events the bridge should receive. Execute the following command:

$ node app.js -r -f my_registration_file.yaml -u "http://where.the.appservice.listens:9999" -c config.yaml -l my_bot

Loading config file /home/github/matrix-appservice-irc/config.yaml
Output registration to: /home/github/matrix-appservice-irc/my_registration_file.yaml

More information on the CLI args can be found by running $ node app.js --help

This will create a registration YAML file. Edit your homeserver config file (e.g. homeserver.yaml) to point to this registration file:

# homeserver.yaml
app_service_config_files: ["my_registration_file.yaml"]

4. Running

Finally, the bridge can be run using the following command:

$ node app.js -c config.yaml -f my_registration_file.yaml -p 9999 

What does it do?

On startup, the bridge will join Matrix clients to the IRC channels specified in the configuration file. It will then listen for incoming IRC messages and forward them through to Matrix rooms. Each real Matrix user is represented by an IRC client, and each real IRC client is represented by a Matrix user. Full two-way communication in channels and PMs are supported, along with a huge array of customisation options.

For more information on how you can customise the bridge, check out the how-to guide.

Usage

To join a channel on an IRC network configured for public use:

  • Join a room with the alias #<alias_prefix><channel_name>:<homeserver_hosting_the_appservice> e.g. #irc_#python:example.com. The template for this can be configured at config.yaml:ircService.servers.<servername>.dynamicChannels.aliasTemplate.

For the publicly bridged IRC networks on matrix.org, the options are:

  • /join #freenode_#somewhere:matrix.org (for freenode)
  • /join #mozilla_#somewhere:matrix.org (for moznet)

To send a PM to someone on an IRC network:

  • Start a conversation with a user ID @<user_prefix><nick>:<homeserver_hosting_the_appservice> e.g. @irc_Alice:example.com. The template for this can be configured at config.yaml:ircService.servers.<servername>.matrixClients.userTemplate.

Configuration

See the sample config file for an explanation of the configuration options available.

Contributing

Please see the CONTRIBUTING file for information on contributing.

matrix-appservice-irc's People

Contributors

aidalgol avatar ansiwen avatar aperezdc avatar ara4n avatar betz avatar bkruger99 avatar dakrone avatar dbkr avatar delta1977 avatar deltawhy avatar erdnaxeli avatar erikjohnston avatar half-shot avatar illicitonion avatar kaiyou avatar kegsay avatar leonerd avatar lukebarnard1 avatar michaelkaye avatar roblabla avatar rubo77 avatar sash13 avatar silkeh avatar sohumb avatar t3chguy avatar turt2live avatar waldteufel avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.