Matrix IRCd

An IRCd implementation backed by Matrix. Inspired by PTO!

Join the discussion on the Matrix channel: #matrix-ircd:matrix.org

This is project is almost the inverse of matrix-appservice-irc. matrix-ircd lets you use any standard IRC Client to communicate with Matrix, whereas matrix-appservice-irc is primarily a way to use a Matrix client to communicate with IRC.

Status

This is a work in progress. Matrix IRCd should be stable enough to hack on and test, but has not been tested in production or for any length of time.

See the GitHub issues page for a more detailed breakdown of what is left to do.

Building

Matrix IRCd requires Rust v1.31.0 or later. Building and installing uses the standard cargo commands.

To run a plain debug version:

cargo run -- --url "https://matrix.org"

To build with trace logging:

cargo build --features trace_logging

Usage

IRC Matrix Daemon 0.1.0

USAGE:
    matrix-ircd [OPTIONS] --url <MATRIX_HS>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -b, --bind <BIND>            Sets the address to bind to. Defaults to 127.0.0.1:5999
        --url <MATRIX_HS>        The base url of the Matrix HS
        --password <PASSWORD>    The password of the PKCS#12 file
        --pkcs12 <PKCS12>        Sets the PKCS#12 file to read TLS cert and pkeyfrom

The MATRIX_HS URL should be of the form: https://matrix.org. Plain HTTP is also supported but should only be used for testing and development.

Supplying both pkcs12 and password arguments will cause Matrix IRCd to listen on TLS, otherwise it will use plain TCP.

The credentials for the matrix account are taken from the user name and server password specified by the IRC connection.

Snap

This software includes packaging information for Snapcraft. Building the snap package is as simple as installing as running snapcraft in the top-level directory of this repository. The resulting snap, until the snap is published on snapcraft.io, can be installed locally by using the --dangerous option to snap install. --dangerous is only needed as local snaps are not cryptographically signed.

The matrix-ircd daemon is configured in the snap package to read an environment file, which allows customisation of the parameters documented in the usage section. The environment file is a bash script which sets several environment variable, which are loaded by the systemd service file which runs matrix-ircd inside the snap environment.

To configure the service, create a file in /var/snap/matrix-ircd/common named matrix-ircd.env, and set the following variables inside:

MATRIX_IRCD_HOMESERVER Maps to the --url parameter, points to the home server you wold like matrix-ircd to connect to. Example: MATRIX_IRCD_HOMESERVER=https://example.homeserver:8989

MATRIX_IRCD_BIND Maps to the --bind parameter, sets the IP and port you would like matrix-ircd to listen on for IRC connections. Example: MATRIX_IRCD_BIND=0.0.0.0:9001

If you would like to use TLS, both of the following settings will need to be set. If you would not like to use TLS, do not include these settings in your environment file.

MATRIX_IRCD_PASSWORD Sets the password used to access the PKCS#12 certificate bundle. Example: MATRIX_IRCD_PASSWORD=Passw0rd

MATRIX_IRCD_PKCS12 Sets the filename of the PKCS#12 certificate bundle. This file must be located in the /var/snap/matrix-ircd/common directory. Example: matrix-ircd.pfx

With all of these parameters set, you should be able to start the service with: systemctl start snap.matrix-ircd.matrix-ircd Any errors with your configuration will be record in the system's journald logs for the service.

Development

Matrix IRCd aims to build with zero standard warning and no clippy warnings.

To run clippy use (after install clippy):

cargo clippy --features clippy

The feature flag disables certain spurious warnings related to third party crates.

Some high level development documentation can be generated by:

cargo doc --open

To generate the full documentation, including private APIs, use: