public-mirrors/reflectionircd
1
0
Fork 0
mirror of https://git.sr.ht/~emerson/reflectionircd synced 2025-04-13 09:59:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update readme

Browse source
This commit is contained in:
emerson 2023-07-03 13:38:20 +00:00
parent 9f8ecca96b
commit 5b32104a1a
1 changed files with 18 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
README.md
View file

@ -8,6 +8,17 @@ ReflectionIRCd is an IRCd that bridges Matrix, allowing you to use an IRC client
- Standalone: Uses the Client-Server API, so you can use it with any homeserver - Standalone: Uses the Client-Server API, so you can use it with any homeserver
## Running ## Running
### 1. Setup pantalaimon
The best way to run Reflection is using [pantalaimon](https://github.com/matrix-org/pantalaimon) to provide end to end encryption support. You can run Reflection without it by using the access token from an existing Matrix connection, but you will not be able to see encrypted messages.
* Install pantalaimon. When you become sad about the lack of setup documentation, just know that I built this entire thing with a similar lack of documentation.
* Initialize your user by sending a POST request to the `/login` endpoint, for example `curl -XPOST -d '{"type":"m.login.password", "user":"testing", "password":"secret"}' "http://127.0.0.1:8009/_matrix/client/r0/login"`
* Save the `access_token` somewhere
* Verify the device using `panctl`
### 2. Create config
Add a JSON file to `configs/`, and copy and edit the values from `config.example.json`: Add a JSON file to `configs/`, and copy and edit the values from `config.example.json`:
* `serverName` is the name of the IRC server * `serverName` is the name of the IRC server
* `port` is the listening port of the server * `port` is the listening port of the server
@ -16,20 +27,21 @@ Add a JSON file to `configs/`, and copy and edit the values from `config.example
* `syncTimeout` is the number of milliseconds to ask the homeserver to hold the sync open. `15000` seems to be the de-facto number. * `syncTimeout` is the number of milliseconds to ask the homeserver to hold the sync open. `15000` seems to be the de-facto number.
* `lagWarningLimit` is the number of milliseconds that will trigger a "Sync is lagging" message to warn of a lagging homeserver. If you run your own HS, setting it to 2000 more than `syncTimeout` will help you diagnose issues. Larger servers like matrix.org often have a 5-10 second lag time, so increase this to prevent your screen filling with lag warnings. * `lagWarningLimit` is the number of milliseconds that will trigger a "Sync is lagging" message to warn of a lagging homeserver. If you run your own HS, setting it to 2000 more than `syncTimeout` will help you diagnose issues. Larger servers like matrix.org often have a 5-10 second lag time, so increase this to prevent your screen filling with lag warnings.
* `mxid` is the MXID of your Matrix user * `mxid` is the MXID of your Matrix user
* `homeserver` is the URL of your homeserver. You get this value in Element by going to Settings > Help and About > Advanced * `homeserver` is the URL of your homeserver.
* `accessToken` is the access token to use. You get this value underneath the homeserver URL in Element. * `accessToken` is the access token to use.
* `saslPassword` is the SASL password to use when connecting to Reflection * `saslPassword` is the SASL password to use when connecting to Reflection
If you're running multiple instances, use multiple config files, i.e. `matrix.json` or `aria.json`. If you're running multiple instances, use multiple config files, i.e. `matrix.json` or `aria.json`.
### 3. Build and run
Then `npm ci`, `npm run build`, and `node reflection.js configs/matrix.json` (replace `matrix.json` if you named your config differently). You'll see a message about starting initial sync, and then "Synced to network!". Once it's synced, you can connect with your client, specifying the SASL password you put in the config (SASL username doesn't matter). Then `npm ci`, `npm run build`, and `node reflection.js configs/matrix.json` (replace `matrix.json` if you named your config differently). You'll see a message about starting initial sync, and then "Synced to network!". Once it's synced, you can connect with your client, specifying the SASL password you put in the config (SASL username doesn't matter).
## Known issues ## Known issues
* Encrypted rooms don't work. In theory you can use [pantalaimon](https://github.com/matrix-org/pantalaimon), however I haven't tried it yet. * You need to manually verify devices in encrypted rooms using Pantalaimon. You can also use the `send-anyways` `panctl` command to send without verifying everyone.
* You can't `/join` channels. However, if you join a channel via Element (other clients are available), it will auto-join your IRC client to it. * You can't `/join` channels. However, if you join a channel via Element (other clients are available), it will auto-join your IRC client to it.
* You can't open a PM to individual users, since a "PM" in Matrix is just another room, and you can't join rooms from IRC. * You can't open a PM to individual users, since a "PM" in Matrix is just another room, and you can't join rooms from IRC.
* There's no IRC equivalent to Spaces. Since they are just regular rooms, they show up in IRC as just regular rooms, however, you can't send messages to them. * There's no IRC equivalent to Spaces (yet). Since they are just regular rooms, they show up in IRC as just regular rooms, however, you can't send messages to them.
* In order to highlight users, you need to prefix their nick with an `@`, so `@emerson: hi`. Reflection automatically expands this to the user's MXID, so even though it's annoying, it's needed to stop inadvertent highlights for now. * In order to highlight users, you need to prefix their nick with an `@`, so `@emerson: hi`. Reflection automatically expands this to the user's MXID, so even though it's annoying, it's needed to stop inadvertent highlights for now.
* In general, Reflection trusts IRC clients to do the right thing, and doesn't have a lot of error-checking of IRC messages (it does have robust error checking for the Matrix side because Matrix sends a lot of error-filled messages). * In general, Reflection trusts IRC clients to do the right thing, and doesn't have a lot of error-checking of IRC messages (it does have robust error checking for the Matrix side because Matrix sends a lot of error-filled messages).
@ -90,9 +102,9 @@ On Libera I'm `emerson`, on Matrix I'm `@emersonveenstra:matrix.org`, feel free
| Channel bans | 🟨 | ❌ | [#24](https://todo.sr.ht/~emerson/reflectionircd/24) Single-user bans show up on IRC as kicks, there's no banlist yet | | Channel bans | 🟨 | ❌ | [#24](https://todo.sr.ht/~emerson/reflectionircd/24) Single-user bans show up on IRC as kicks, there's no banlist yet |
| Channel invites | ✅ | ✅ || | Channel invites | ✅ | ✅ ||
| Channel topics | ✅ | ✅ || | Channel topics | ✅ | ✅ ||
| Channel powers | ✅ | ❌ | [#6](https://todo.sr.ht/~emerson/reflectionircd/6) | | Channel powers/configuration changing | ✅ | ❌ | [#6](https://todo.sr.ht/~emerson/reflectionircd/6) |
| Channel lists/searching | ❌ | ❌ | [#30](https://todo.sr.ht/~emerson/reflectionircd/30) | | Channel lists/searching | ❌ | ❌ | [#30](https://todo.sr.ht/~emerson/reflectionircd/30) |
| Encrypted rooms | ❌ | ❌ | [#20](https://todo.sr.ht/~emerson/reflectionircd/20) | | Encrypted rooms (natively) | ❌ | ❌ | [#20](https://todo.sr.ht/~emerson/reflectionircd/20) |
| Rich text | ❌ | ❌ | [#31](https://todo.sr.ht/~emerson/reflectionircd/31) | | Rich text | ❌ | ❌ | [#31](https://todo.sr.ht/~emerson/reflectionircd/31) |
| Presence | ✅ | ✅ | Not all homeservers have presence enabled | | Presence | ✅ | ✅ | Not all homeservers have presence enabled |
| Channel renaming <small>(IRCv3)</small> | ✅ | ❌ | [#16](https://todo.sr.ht/~emerson/reflectionircd/16) | | Channel renaming <small>(IRCv3)</small> | ✅ | ❌ | [#16](https://todo.sr.ht/~emerson/reflectionircd/16) |