Matrix-Mirrors/pantalaimon
1
0
Fork 0
mirror of https://github.com/matrix-org/pantalaimon.git synced 2025-02-08 19:08:32 -05:00
Code Issues Packages Projects Releases Wiki Activity

man: Add the man pages in the markdown format.

Browse Source
This commit is contained in:
Damir Jelić 2019-05-24 16:00:26 +02:00
parent 6a578c95b6
commit 6c91466537
3 changed files with 356 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
man/panctl.md Normal file
View File

@ -0,0 +1,104 @@
PANCTL(1) - General Commands Manual
# NAME
**panctl** - Control the Matrix reverse proxy daemon pantalaimon.
# DESCRIPTION
**panctl**
is a small utility to control and introspect the state of pantalaimon.
## Commands
The commands accepted by
**panctl**
are as follows:
**list-servers**
> List the configured homeservers and pan users on each homeserver.
**list-devices** *pan-user* *user-id*
> List the devices of a user that are known to the
> *pan-user*.
**start-verification** *pan-user* *user-id*
> Start an interactive key verification between the given pan-user and user.
**accept-verification** *pan-user* *user-id*
> Accept an interactive key verification that the given user has started with our
> given pan-user.
**cancel-verification** *pan-user* *user-id*
> Cancel an interactive key verification between the given pan-user and user.
**confirm-verification** *pan-user* *user-id*
> Confirm that the short authentication string of the interactive key verification
> with the given pan-user and user is matching.
**verify-device** *pan-user* *user-id* *device-id*
> Manually mark the given device as verified. The device will be marked as verified
> only for the given pan-user.
**unverify-device** *pan-user* *user-id* *device-id*
> Mark a previously verified device of the given user as unverified.
**blacklist-device** *pan-user* *user-id* *device-id*
> Manually mark the given device of the given user as blacklisted.
**unblacklist-device** *pan-user* *user-id* *device-id*
> Mark a previously blacklisted device of the given user as unblacklisted.
**send-anyways** *pan-user* *room-id*
> If a encrypted room contains unverified devices and a connected Matrix client
> tries to send an message to such a room
> **pantalaimon**
> will send a notification that the room contains unverified users. Using this
> command the user can choose to mark all unverified devices as ignored. Ignored
> devices will receive encryption keys but will be left marked as unverified.
> The message will be sent away after all devices are marked as ignored.
**cancel-sending** *pan-user* *room-id*
> In contrast to the
> **send-anyways**
> command this command cancels the sending of a message to an encrypted room with
> unverified devices and gives the user the oportunity to verify or blacklist
> devices as they see fit.
**import-keys** *pan-user* *file* *passphrase*
> Import end-to-end encryption keys from the given file for the given pan-user.
**export-keys** *pan-user* *file* *passphrase*
> Export end-to-end encryption keys to the given file for the given pan-user. The
> provided passphrase is used to encrypt the file containing the keys.
# EXIT STATUS
The **panctl** utility exits 0 on success, and >0 if an error occurs.
# SEE ALSO
pantalaimon(8)
pantalaimon(5)
# AUTHORS
**panctl**
was written by
Damir Jelić <[poljar@termina.org.uk](mailto:poljar@termina.org.uk)>.
Linux 5.1.3-arch2-1-ARCH - May 23, 2019

153
man/pantalaimon.5.md Normal file
View File

@ -0,0 +1,153 @@
PANTALAIMON.CONF(5) - File Formats Manual
# NAME
**pantalaimon.conf** - pantalaimon configuration file
# DESCRIPTION
pantalaimon(1) reads configuration data in the INI file format.
The configuration file is used to configure
**pantalaimon**
homeservers.
The sections inside the configuration file represent a pantalaimon proxy
instance with the section name enclosed in square brackets representing an user
chosen instance name.
The following keys are required in the proxy instance sections:
**Homeserver**
> The URI of the homeserver that the pantalaimon proxy should forward requests to,
> without the matrix API path but including the http(s) schema.
The following keys are optional in the proxy instance sections:
**ListenAddress**
> The address where the daemon will listen to client connections for this
> homeserver. Defaults to "localhost".
**ListenPort**
> The port where the daemon will listen to client connections for this
> homeserver. Note that the listen address/port combination needs to be unique
> between different homeservers. Defaults to "8009".
**Proxy**
> An URI of a HTTP proxy that the daemon should use when making requests to the
> homeserver.
> **pantalaimon**
> only supports HTTP proxies. The default is to make a direct connection to the
> homeserver.
**SSL**
> A boolean that decides if SSL verification should be enabled for outgoing
> connections to the homeserver. Defaults to "True".
**IgnoreVerification**
> A boolean that decides if device verification should be enabled. If this is True
> devices will be marked as ignored automatically and encryption keys will be
> shared with them, if this is False the user needs to verify, blacklist or ignore
> devices manually before messages can be sent to a room. Defaults to "False".
**UseKeyring**
> This option configures if a proxy instance should use the OS keyring to store
> its own access tokens. The access tokens are required for the daemon to resume
> operation. If this is set to "No", access tokens are stored in the pantalaimon
> database in plaintext. Defaults to "Yes".
Aditional to the homeserver section a special section with the name
**Default**
can be used to configure the following values for all homeservers:
**ListenAddress**,
**ListenPort**,
**Proxy**,
**SSL**
**IgnoreVerification**
**UseKeyring**
The
**Default**
section has the following keys that globally change the behaviour of the daemon:
**LogLevel**
> Set the log level of the daemon, can be one of
> *error*,
> *warning*,
> *info*,
> *debug*.
> Defaults to
> *warning*.
**Notifications**
> The daemon sends out notifications for some actions that require users to
> interfere (unverified devices are in a room, interactive key verification
> events), this option enables or disables OS notifications. Can be one of
> *On*,
> *Off*.
> Defaults to
> *On*.
# FILES
**pantalaimon**
supports the XDG Base Directory Specification, the default locations can be
overridden using appropriate environment variables.
*~/.config/pantalaimon/pantalaimon.conf*
> Default location of the configuration file.
# EXAMPLES
The following example shows a configured pantalaimon proxy with the name
*Clocktown*,
the homeserver URL is set to
*https://example.org*,
the pantalaimon proxy is listening for client connections on the address
*localhost*,
and port
*8009*.
The pantalaimon proxy is making connections to the homeserver through the proxy
*http://localhost:8009*,
finally, SSL verification is disabled.
Additionally to the
*Clocktown*
section the
*Default*
section is also listed and the default value for SSL verification is set to
True, OS notifications are enabled and the debug level is set to
*Debug*.
[Default]
LogLevel = Debug
SSL = True
Notifications = On
[Clocktown]
Homeserver = https://localhost:8448
ListenAddress = localhost
ListenPort = 8009
Proxy = http://localhost:8080
SSL = False
# SEE ALSO
pantalaimon(8)
# AUTHORS
**pantalaimon.conf**
was written by
Damir Jelić <[poljar@termina.org.uk](mailto:poljar@termina.org.uk)>.
Linux 5.1.3-arch2-1-ARCH - May 8, 2019

99
man/pantalaimon.8.md Normal file
View File

@ -0,0 +1,99 @@
PANTALAIMON(8) - System Manager's Manual
# NAME
**pantalaimon** - End-to-end encryption aware Matrix reverse proxy daemon.
# SYNOPSIS
**pantalaimon**
\[**-c** *config*]
\[**-log-level**]
# DESCRIPTION
**pantalaimon**
is a daemon that acts as a reverse proxy between a Matrix homeserver and a
Matrix client. The daemon transparently handles end-to-end encryption tasks on
behalf of the client.
**pantalaimon**
is supposed to run as your own user and listen to connections on a
non-privileged port. A client needs to log in using the standard Matrix HTTP
calls to register itself to the daemon, such a registered user is called a pan
user and will have his own sync loop to keep up with the server. Multiple matrix
clients can connect and use the same pan user.
If user interaction is required
**pantalaimon**
will send out OS notifications which the user can react to.
**pantalaimon**
also provides a D-Bus API that is used for encryption related tasks that
require user interference (e.g. device verification).
**pantalaimon**
requires a homeserver to be configured. Multiple homeservers can be configured,
each configured homeserver needs to listen on a separate port. Each homeserver
can handle end-to-end encryption for multiple users. The configuration file
format is specified in
pantalaimon(5),
the default location of the configuration file can be found in the
*FILES*
section.
## Options
The command line flags to change the behaviour of
**pantalaimon**
are as follows:
**-c**, **--config** *file*
> Use the supplied
> *file*
> as the configuration file instead of the default one.
**--log-level** *level*
> Set the log level of the daemon, can be one of
> *error*,
> *warning*,
> *info*,
> *debug*.
> Defaults to
> *warning*.
# FILES
**pantalaimon**
supports the XDG Base Directory Specification, the default locations can be
overridden using appropriate environment variables.
*~/.config/pantalaimon/pantalaimon.conf*
> Default location of the configuration file.
> The format of the configuration file is described in
> pantalaimon(5).
*~/.local/share/pantalaimon/pan.db*
> Default location of the pantalaimon database.
> This file is used to store a sqlite database holding daemon state and encryption
> keys.
# EXIT STATUS
The **pantalaimon** utility exits 0 on success, and >0 if an error occurs.
# SEE ALSO
panctl(1)
pantalaimon(5)
# AUTHORS
**pantalaimon**
was written by
Damir Jelić <[poljar@termina.org.uk](mailto:poljar@termina.org.uk)>.
Linux 5.1.3-arch2-1-ARCH - May 23, 2019