98 lines
5.2 KiB
Markdown
98 lines
5.2 KiB
Markdown
# Easybridge
|
|
|
|
Easybridge is a Matrix-to-everything (almost) bridge.
|
|
It acts as a client under your name on all instant messaging networks where
|
|
you have an account, and presents your private messages as well as group
|
|
conversations in Matrix in a uniform view.
|
|
Basically, Matrix becomes your everything chat client!
|
|
|
|
**WARNING** Easybridge is still very experimental and crashes sometimes.
|
|
Also, the Facebook Messenger backend might get you rate-limited on login
|
|
attempts if you restart the bridge too often, which will lock you out of
|
|
your Facebook account asking you to recover your account and change your password.
|
|
See below for information on how to avoid this situation.
|
|
|
|
Current features:
|
|
|
|
- Backends: IRC, XMPP, Mattermost, Facebook Messenger (more to come)
|
|
- Private messages and group/chat room messages
|
|
- Automatic setup of Matrix rooms that bridge to outside rooms
|
|
- Room name and topic synchronization (partially)
|
|
- Images and file transfers (Mattermost backend)
|
|
- Avatar and room pictures (Mattermost backend, one-way only)
|
|
- Web interface for setting up accounts so that new accounts can be easily
|
|
added and you don't have to type your credentials in a clear-text Matrix room
|
|
- Credentials are stored encrypted in the database using users' Matrix passwords
|
|
|
|
There is lot to do! See the issues if you want to join us on this project.
|
|
|
|
A Docker image is provided on the [Docker hub](https://hub.docker.com/r/lxpz/easybridge_amd64).
|
|
|
|
Easybridge takes a single command line argument, `-config <filename>`, which is the
|
|
path to its config file (defaults to `./config.json`).
|
|
The configuration file is a JSON file whose contents is described in the following section.
|
|
|
|
Easybridge is licensed under the terms of the GPLv3.
|
|
|
|
|
|
## Building Easybridge
|
|
|
|
Easybridge requires go 1.13 or later.
|
|
|
|
To build Easybridge, clone this repository outside of your `$GOPATH`.
|
|
Then, run `make` in the root of the repo.
|
|
|
|
|
|
## Configuring Easybridge
|
|
|
|
Easybridge acts as a Matrix application service: in this regard,
|
|
it requires a registration file to be added to your homeserver.
|
|
It uses a database to store configuration and state information,
|
|
which can be any backend supported by [Gorm](https://gorm.io).
|
|
|
|
Easybridge is configured using a single JSON configuration file, which contains
|
|
a dictionnary whose keys are the following:
|
|
|
|
- `log_level`: what log level Easybridge runs with (trace, debug, info, warn, error, fatal, panic). **Warning:** in `trace` level, the content of all calls to the Matrix API and some other information will be dumped, exposing user's credentials and messages. In `debug` level, room join/leave information will be exposed. The `info` level (default) does not expose any user's private information.
|
|
- `easybridge_avatar`: path to the image that Easybridge uses as an avatar on Matrix
|
|
|
|
### Matrix configuration
|
|
|
|
- `registration`: path to the YAML appservice registration file
|
|
- `appservice_bind_addr`: on what IP/port to bind as a Matrix app service (HTTP only, no HTTPS)
|
|
- `homeserver_url`: HTTP address of the Matrix homeserver
|
|
- `matrix_domain`: the domain name of the Matrix homeserver (i.e. the domain used in user identifiers, room identifiers, etc)
|
|
- `name_format`: the format of identifiers that are created on Matrix for users and room aliases. `{}` is replaced by the concatenation of user/room identifier and protocol. Typically you want either `_ezbr_{}` or `{}_ezbr`, the latter having the advantage that the briged user's names are then used as prefixes for the created identifiers.
|
|
|
|
### Web interface configuration
|
|
|
|
- `web_bind_addr`: on what IP/port to bind for the web interface that allows adding and configuring accounts (HTTP only, no HTTPS, use a reverse proxy for that)
|
|
- `web_url`: the outside HTTP/HTTPS address at which the web interface is made available. If set, a widget will be added in the Easybridge room so that users can configure the bridge without leaving the Riot client.
|
|
- `session_key`: a key with which session cookies are encrypted for the web interface
|
|
|
|
### Storage configuration
|
|
|
|
- `db_type` and `db_path`: the database backend and path to use (see the [Gorm documentation](http://gorm.io/docs/connecting_to_the_database.html))
|
|
|
|
|
|
## Facebook Messenger alternative login procedure
|
|
|
|
The default login proedure for the Messenger backend is to log in with your email and password each time
|
|
Easybridge starts. Unfortunately, if Easybridge restarts too often, this will get you rate limited on login
|
|
attempts quite rapidly. To bypass this issue, the Messenger backend provides the ability to login
|
|
using a *client pickle*, i.e. a serialized client that contains all of the cookies obtained during a single
|
|
initial login procedure, so that further logins are not required any longer.
|
|
|
|
To use this method, *do not enter your password in Easybridge when configuring the Messenger backend*.
|
|
Generate your client pickle by running the following command:
|
|
|
|
```
|
|
./external/messenger.py create_client_pickle
|
|
```
|
|
|
|
This procedure will ask for your email and password and attempt to log you in to Facebook.
|
|
If it succeeds, it will print several dozen lines of data looking like `eJyVVlt....X9cgyfgY7mJaK`.
|
|
Then, when configuring the Messenger backend in Easybridge,
|
|
instead of entering your password,
|
|
enter the obtained client pickle string in the appropriate field.
|
|
|