From 6c914665377d18fa00ac144db2fd9efce727a510 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk> Date: Fri, 24 May 2019 16:00:26 +0200 Subject: [PATCH] man: Add the man pages in the markdown format. --- man/panctl.md | 104 +++++++++++++++++++++++++++++ man/pantalaimon.5.md | 153 +++++++++++++++++++++++++++++++++++++++++++ man/pantalaimon.8.md | 99 ++++++++++++++++++++++++++++ 3 files changed, 356 insertions(+) create mode 100644 man/panctl.md create mode 100644 man/pantalaimon.5.md create mode 100644 man/pantalaimon.8.md diff --git a/man/panctl.md b/man/panctl.md new file mode 100644 index 0000000..ed733f5 --- /dev/null +++ b/man/panctl.md @@ -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 diff --git a/man/pantalaimon.5.md b/man/pantalaimon.5.md new file mode 100644 index 0000000..b140daf --- /dev/null +++ b/man/pantalaimon.5.md @@ -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 diff --git a/man/pantalaimon.8.md b/man/pantalaimon.8.md new file mode 100644 index 0000000..683c7a4 --- /dev/null +++ b/man/pantalaimon.8.md @@ -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