Pipebridge

Pipebridge is a general-purpose bridge for connecting various program and game chats together.

Compiling

You need gcc and make installed. To compile, simply do make.

Installing

There's currently no automatic way of installing, but it can simply be done manually by copying all executables to /usr/local/bin or whatever directory you want to install in and setting the appropriate ownership of the executables.

Setting up

Relay

The relay itself (the pipebridge executable) is the one responsible for transmitting messages between systems. For this reason, it's most important component of the ecosystem; if it goes down, everything else stops transmitting data. For this reason, it needs to be started first and be shut down last, and all endpoints connected to it must shut down first before the relay can be restarted.

pipebridge takes one mandatory parameter, which is the path to the socket that endpoints communicate with. All endpoints must then be configured to connect to that socket, and send messages through it.

pipebridge also takes additional arguments:

• -d - If specified, pipebridge will fork to the background and write a PID file to the specified path. Useful when integrating to an init system.
• -u - When combined with -d, this will also cause pipebridge to switch user to the specified name if applicable. Has no effect if -d is not specified.

ircbridge

ircbridge is the endpoint that is used to bridge an IRC channel to pipebridge. It does that by connecting to a channel and listening for chat messages on the channel, as well as sending chat messages from the relay.

These are the argument you can pass to ircbridge:

• -c - Path to the configuration file, defaults to /usr/local/etc/ircbridge.conf.
• -v - Verbose output, should only be used for debugging.
• -l - File to log output to. Timestamps will be added automatically per line on each outputted line.

To set up ircbridge, a configuration file is required. An example configuration can look like this:

# Network to connect to.
network = irc.example.com
# Channel to join upon connection.
channel = #example
# Time, in seconds, between reconnects if connection is lost or shut down.
# Leaving this unset will cause ircbridge to shut down on disconnect.
reconnect = 5
# Path to relay socket.
bridge_path = /tmp/pipebridge.sock
# Prefix to use when sending messages to the relay.
prefix = IRC
# Nickname to be used by the bot.
nick = ircbridge
# Password to use for authentication (only QuakeNet is supported at this time).
auth = password123
# If true, enables the use of tls to connect.
tls = true
# If true, send any events to the bridge, like joins and disconnects. Note that status messages will still be logged.
send_status = true

It also requires two additional parameters: the name of the network to connect to and the channel, in that order. Note that the channel must be prefixed with #, which requires this argument to be quoted to not be interpreted as a comment.

Example:

ircbridge -r 5 -b /tmp/pipebridge.sock -n Example -N example irc.example.com '#examplechat'

matrixbridge

matrixbridge is the endpoint used by Matrix in order to bridge a Matrix room to the relay. Due to it's complex nature, installation instructions are documented in matrixbridge/README.md.

srb2bridge

srb2bridge is the endpoint that is used to bridge SRB2 server chat to the relay. This endpoint works by attaching itself as a PTY to SRB2, and scraping off messages from the game console as well as inserting commands through the terminal interface.

For it to work, the srb2-pipebridge.lua addon must be added to the server that SRB2 should relay to. If this is not added, the endpoint won't get the log lines required for it to be able to recognize a message, and the __m command that is used to display messages will instead result in unknown commands.

Once added to a server, you first need to set the endpoint tag on the server to the pb_bridgename cvar, so player listing will work as intended. After that, you can then roll out srb2bridge. These are the arguments you can pass to the endpoint:

• -p - Specifies a path to a FIFO pipe that srb2bridge reads commands from. This is useful to be able to run commands from outside the program, since SRB2 doesn't have any other way to run commands other than from PTY, which srb2bridge already occupies.
• -b - Path to the relay socket, must be the same as the one that pipebridge was started with.
• -n - Prefix that is used on messages. Recommended to be set to SRB2, but could be set to anything you like.
• -r - Automatically restarts the SRB2 server after n seconds if it shuts down, where n is a number following the argument.
• -d - If specified, srb2bridge will fork to the background and write a PID file to the specified path. Useful when integrating to an init system.
• -l - File to log output to. Timestamps will be added automatically per line on each outputted line.
• -u - When combined with -d, this will also cause srb2bridge to switch user to the specified name if applicable. Has no effect if -d is not specified.

It also takes one mandatory parameter: the path to the executable to invoke. It's strongly adviced to point srb2bridge to a shell script that later invokes SRB2's executable, to be able to do some pre-initialization as well as pass additional parameters to SRB2.

Example:

srb2bridge -b /tmp/pipebridge.sock -p /tmp/srb2.pipe -n Example -r 5 /home/srb2/run-srb2.sh

xonbridge

xonbridge is the endpoint that is used to bridge Xonotic's server chat to the relay. It works by watching over the log files for event log entries and sending commands via RCON to send messages to Xonotic.

For it to work, xonotic.patch must be applied to the xonotic-data.pk3dir inside the data directory of the xonotic source code. It can be applied by cding into xonotic-data.pk3dir and invoking git apply on the patch.

Once that's done, the following configuration must be made to the xonotic server:

// configure xonotic to log events.
log_file "server.log"
sv_eventlog 1
sv_eventlog_ipv6_delimiter 1
sv_eventlog_console 1
// set up rcon (secure must be disabled right now, since xonbridge doesn't support secure connections at this time)
rcon_secure 0
rcon_password password // CHANGE THIS TO SOMETHING UNIQUE!!!

Once the patch has been applied and Xonotic is configured, xonbridge can be rolled out. These arguments can be passed to the endpoint:

• -b - Path to the relay socket, must be the same as the one that pipebridge was started with.
• -n - Prefix that is used on messages. Recommended to be set to Xonotic, but could be set to anything you like.
• -p - Sets the password to use when talking via RCON to Xonotic. Must be the same as the value specified in rcon_password in Xonotic's configuration.
• -d - If specified, xonbridge will fork to the background and write a PID file to the specified path. Useful when integrating to an init system.
• -u - When combined with -d, this will also cause xonbridge to switch user to the specified name if applicable. Has no effect if -d is not specified.

It also takes two mandatory parameters: the path to Xonotic's log file and the port that the Xonotic server is exposed on, which is used to send RCON messages to Xonotic.

Example:

xonbridge -b /tmp/pipebridge.sock -n Example -p password /home/xonotic/.xonotic/data/server.log 26000

luantibridge

luantibridge is the endpoint that Minetest can use to bridge it's chat to the relay. It works by simply opening up the pipebridge socket directly and transmitting data to it.

To get it working, start by installing lua-posix, preferrably via your system's package manager to make installation easy. Once installed, add the luantibridge mod to the server, normally by creating a symlink to the luantibridge directory inside the mods directory of your Minetest install. Once that's done, you need to enable trusted mods and point luantibridge to the socket that the relay provides by adding the following to minetest.conf:

secure.enable_security = true
secure.trusted_mods = luantibridge
pipebridge.path = /path/to/pipebridge.sock

Adjust the path on the last line accordingly. After this, just launch the server with the mod loaded and you should be good to go.

Finally, if needed, any message handling from the bridge can be overridden by replacing luantibridge.on_receive_message(message). Just make sure you add a dependency, either mandatory or optional, on luantibridge when you do to ensure that luantibridge process messages first.

overtebridge

overtebridge is the endpoint that runs as an Assignment Client on Overte to bridge it's domain chat to the relay. It transmits messages via websockets and forwards it via a Python script.

To run it, start by installing websockets for Python, preferrably via your system's package manager, then launching overtebridge.py, preferrably on port 17200. Once the intermediate Python script is set up, overtebridge.js need to be exposed via an HTTP server, so the domain server can access the script. Then, log into the domain server web interface, go to Content -> Scripts and add the HTTP URL pointing to the overtebridge.js script there. Finally, save and restart, and the script should connect to the intermediate.

Note that overtebridge.py must be launched first, and the Overte server must be restarted if the intermediate is restarted!

These argument can be passed to overtebridge.py:

• -b - Path to the relay socket, must be the same as the one that pipebridge was started with.
• -n - Prefix that is used on messages. Recommended to be set to Overte, but could be set to anything you like.
• -l - File to log output to. Timestamps will be added automatically per line on each outputted line.

announce

announce is a special tool that allows sending a single, raw message straight to the bridge. As the name implies, it's meant to be used for scheduled announcements across the entire bridge, but it's also useful for testing setups so messages are comping through as expected.

It takes two arguments: the path to the relay socket and the message to send. Note that the message format accepts color sequences, see DOCUMENTATION.md for more information.

Example:

announce /tmp/pipebridge.sock "^4[ANNOUNCEMENT] ^0Example text"

watchdog

watchdog is a special tool that reads and prints all messages over the bridge. This is mainly meant to be used for diagnostic and development purposes; it is not advised to use this for logging, as most endpoints log more information than what is being bridged.

You only need to specify the path to the relay socket to use it. Once it's running, all bridged messages will be printed by watchdog, allowing you to tell if messages are reaching the relay or not.