This project has been in a very hard to maintain state for a long time. A clean rewrite will be easier, so matrix-ircd will not receive further updates. See matrix2051 or matrirc for alternatives.
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.
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.
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
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.
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.
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:
cargo rustdoc -- --no-defaults --passes "collapse-docs" --passes "unindent-comments" --open