mirror of
https://github.com/matrix-org/pantalaimon.git
synced 2024-10-01 03:35:38 -04:00
122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
pantalaimon
|
|
===========
|
|
|
|
Pantalaimon is an end-to-end encryption aware Matrix reverse proxy daemon.
|
|
Pantalaimon acts as a good man in the middle that handles the encryption for you.
|
|
|
|
Messages are transparently encrypted and decrypted for clients inside of
|
|
pantalaimon.
|
|
|
|
|
|
|
|
Installation
|
|
============
|
|
|
|
The [Olm](https://gitlab.matrix.org/matrix-org/olm) C library is required to
|
|
be installed before installing pantalaimon.
|
|
|
|
If your distribution provides packages for libolm it is best to use those, note
|
|
that a recent version of libolm is required (3.1+). If your distribution doesn't
|
|
provide a package building from source is required. Please refer to the Olm
|
|
[readme](https://gitlab.matrix.org/matrix-org/olm/blob/master/README.md)
|
|
to see how to build the C library from source.
|
|
|
|
Installing pantalaimon works like usually with python packages:
|
|
|
|
python setup.py install
|
|
|
|
Pantalaimon can also be found on pypi:
|
|
|
|
pip install pantalaimon
|
|
|
|
Do note that man pages can't be installed with pip.
|
|
|
|
### macOS installation
|
|
|
|
For instance, on macOS, this means:
|
|
|
|
```bash
|
|
brew install dbus
|
|
perl -pi -e's#(<auth>EXTERNAL</auth>)#<!--$1-->#' $(brew --prefix dbus)/share/dbus-1/session.conf
|
|
brew services start dbus
|
|
# it may be necessary to restart now to get the whole OS to pick up the
|
|
# existence of the dbus daemon
|
|
|
|
git clone https://gitlab.matrix.org/matrix-org/olm
|
|
(cd olm; make)
|
|
git clone https://github.com/matrix-org/pantalaimon
|
|
(cd pantalaimon; CFLAGS=-I../olm/include LDFLAGS=-L../olm/build/ python3 setup.py install)
|
|
|
|
export DBUS_SESSION_BUS_ADDRESS=unix:path=$(launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET)
|
|
cd pantalaimon
|
|
DYLD_LIBRARY_PATH=../olm/build/ pantalaimon -c contrib/pantalaimon.conf
|
|
|
|
# for notification center:
|
|
git clone https://github.com/fakechris/notification-daemon-mac-py
|
|
# if you have django's `foundation` library installed and your filesystem
|
|
# is case insensitive (the default) then you will need to `pip uninstall foundation`
|
|
# or install PyObjC in a venv...
|
|
pip install PyObjC daemon glib dbus-python
|
|
cd notification-daemon-mac-py
|
|
./notify.py
|
|
```
|
|
|
|
### Experimental E2E search support.
|
|
|
|
Pantalaimon can handle the search endpoint of a Matrix server as well, providing
|
|
search support for E2E encrypted rooms.
|
|
|
|
For this to work [tantivy](https://github.com/tantivy-search/tantivy) is needed.
|
|
Tantivy is a full text search engine written in rust.
|
|
|
|
The python bindings for tantivy are needed for pantalaimon. The bindings are not
|
|
yet merged upstream, instead they can be found
|
|
[here](https://github.com/matrix-org/tantivy/tree/topcollector_order_by/python).
|
|
|
|
Note that rust nightly (tested version was: 1.36.0-nightly (50a0defd5 2019-05-21))
|
|
and [setuptools-rust](https://pypi.org/project/setuptools-rust/) are required
|
|
before the tantivy python bindings can be installed.
|
|
|
|
Usage
|
|
=====
|
|
|
|
While pantalaimon is a daemon, it is mean to be run as your own user. It won't
|
|
verify devices for you automatically, unless configured to do so, and requires
|
|
user interaction to verify, ignore or blacklist devices.
|
|
|
|
Pantalaimon requires a configuration file to run. The configuration file
|
|
specifies one or more homeservers for pantalaimon to connect to.
|
|
|
|
A minimal pantalaimon configuration looks like this:
|
|
```dosini
|
|
[local-matrix]
|
|
Homeserver = https://localhost:8448
|
|
ListenAddress = localhost
|
|
ListenPort = 8009
|
|
```
|
|
|
|
The configuration file should be placed in `~/.config/pantalaimon/pantalaimon.conf`.
|
|
|
|
The full documentation for the pantalaimons configuration can be found in
|
|
the man page `pantalaimon(5)`.
|
|
|
|
Now that pantalaimon is configured it can be run:
|
|
|
|
pantalaimon --log-level debug
|
|
|
|
After running the daemon, configure your client to connect to the daemon instead
|
|
of your homeserver. The daemon listens by default on localhost and port 8009.
|
|
|
|
Note that logging in to the daemon is required to start a sync loop for a user.
|
|
After that clients can connect using any valid access token for the user that
|
|
logged in. Multiple users per homeserver are supported.
|
|
|
|
For convenience a systemd service file is provided.
|
|
|
|
To control the daemon an interactive utility is provided in the form of
|
|
`panctl`.
|
|
|
|
`panctl` can be used to verify, blacklist or ignore devices, import or export
|
|
session keys, or to introspect devices of users that we share encrypted rooms
|
|
with.
|