path: root/README.md

# Matterpuppeter

*An API plugin for Matterbridge, that creates IRC puppets*

## Features

Turns this:

```
<Someone> rPerson, rando: hi both
<Matterbridge> [j] <rPerson> hello
<Matterbridge> [mx] <rando> Hi!
<Matterbridge> [irc2] <user> can i join in?
```

into this:

```
<Someone> rPerson|j, rando|mx: hi both
<rPerson|j> hello
--> rando|mx (934782619@matterpuppeter) (@rando:matrix.org [matrix.mxo]) has joined #chat
<rando|mx> Hi!
<user|irc2> can i join in?
```

- *Lazy puppeting*: creates a puppet only when users join or talk
- *Client limit*: limits how many puppets can connect at the same time
- *Built-in configurable pastebinning* of long codeblocks
- Works with *Matterbridge*'s REST API
- *Limited quit/join flood*: keeps connections alive during a Matterbridge 
  restart
  - Puppets are marked as "away" until Matterpuppeter can reconnect to the 
    Matterbridge API

In other words:

```
     Any protocol supported 
        by Matterbridge
  (e.g. XMPP, Discord, Matrix)
               |
               |
               v
          Matterbridge
               |
               |      Matterbridge API
               v
         Matterpuppeter
               |
               |      IRC protocol
               v
          IRC network
   (e.g. OFTC, Libera.Chat)
               |
               |
               v
          IRC channel
        (e.g. ##coffee)
```

This is not a standalone bridge.

## Caveats

- *Lazy puppeting*: while this makes client counts lower, it still means 
  people who do not have a puppet can still watch the channel on the other 
  side, without users on IRC knowing.
- *Portalling-style bridging* is not supported, on-purpose
- *Cannot bridge bans*: matterbridge does not support bridging bans and kicks
- *Private messages* are not supported
- *Connecting to multiple networks* is not supported - run Matterpuppeter 
  multiple times for each network instead

## How to

This currently requires a fork of Matterbridge: https://git.vitali64.duckdns.org/misc/matterbridge.git

Create a Matterbridge config by following [this guide](https://github.com/42wim/matterbridge/wiki/How-to-create-your-config).

Add the following at the top of your `matterbridge.toml`:

```
[api.matterpuppeter]
NoSendJoinPart=false
ShowJoinPart=true
BindAddress="127.0.0.1:4242"
Buffer=1000
RemoteNickFormat="{NICK}-{LABEL}"
Label="IRC"
```

If you're bridging to multiple IRC networks and want to use Matterpuppeter on 
all of them, you'll need one Matterpuppeter instance per network.

Add the following to one of the gateways you have configured:

```
[[gateway]]
name="gateway1"
<...>

    [[gateway.inout]]
    account="api.matterpuppeter"
    channel="api"

<...>
```

Now, you can configure Matterpuppeter itself.  The configuration is in 
`config.yaml`, and is extensively documented.  Do make sure to customise 
it, so it fits your bridging setup.

Here is a simple config file that will bridge to a `##Meow` channel on Libera.Chat:

```
irc:
  host: "irc.libera.chat"
  port: 6697
  tls: true
  nick: "_Bridger"
  gecos: "Matterpuppeter listener bot"
  message_limit: 380
  client_limit: 6

  sasl:
    enable: false

paste:
  enable: false

ident:
  enable: false

api:
  host: "http://localhost:4242"
  account: "api.matterpuppeter"

gateway:
  "gateway1": "##Meow"
```

### Pastebinning support

Long code blocks can be pastebinned to avoid spamming IRC.  This can be useful 
when it is common practise to paste snippets of code which would cause spam on 
the IRC side.  For example, the following message:

```
<f_> Here's my code:

     |  #include <stdio.h>
     |
     |  int main(int argc, char **argv)
     |  {
     |      print("This is a message\n");
     |
     |      return 0;
     |  }

```

can be bridged as:

```
<f_-X> Here's my code:
<f_-X> https://pastebin.matterpuppeter/<paste id here>
```

To configure this behaviour, first create a directory where Matterpuppeter will 
write code snippets to:

```
$ mkdir ~/pastes
```

Then, let an HTTP server serve files from that directory.  For example, when using 
nginx:

```
server {
    server_name paste.matterpuppeter;
    listen 80;
    root /home/_mp/pastes;

    location / {
        index index.html;
    }
}
```

This is a very minimal configuration, which may not be suitable in production, 
but it gives an overall idea of how things should be set up.  Also make sure that 
the `pastes` directory is readable by the user nginx runs as (typically `www-data`).

Finally, you can configure Matterpuppeter to make use of that directory:

```
paste:
  enable: true
  domain: "http://paste.matterpuppeter/"
  dir: "/home/_mp/pastes"
  maxlines: 5
```

Restart your HTTP server and Matterpuppeter, long code blocks should now be 
pastebinned!  You will need to set up cleaning up yourself at this point 
however, but this is left as an exercise to the reader.

### Identd

Matterpuppeter can integrate with an ident daemon for the purposes of identifying 
puppets.  It does this by writing to an *ident file*, which would then be read by 
your system's ident server (such as `oidentd`) and sent to the IRC server. After this 
is done Matterpuppeter clears the contents of the file.

To do this, your `/etc/oidentd.conf` file must allow the user Matterpuppeter runs as to 
spoof ident queries:

```
user "_mp" {
    default {
        allow spoof
        allow spoof_all
    }
}
```

Then create an `.oidentd.conf` file in the home directory of the Matterpuppeter user 
while logged in as that user, and make sure `oidentd` can read it:

```
$ touch ~/.oidentd.conf
$ chmod 644 ~/.oidentd.conf
$ chmod 711 ~
```

Finally, configure Matterpuppeter to write to that file:

```
<...>
ident:
  enable: true
  file: "/home/_mp/.oidentd.conf"
  format: "global { reply \"%user%\" }"
  username: "listener"
<...>
```

Then restart your ident daemon and Matterpuppeter, the puppets it creates should 
now be properly idented!

## TODO

* Possibly full puppeting support (as in, onboarding every single user joined on 
  the other side), probably not as default however
* sed-style (`s///`) or SMS-style edits
* Cleanup