From 4d5967a2f79ecee3f7b689a0c7f38a07b5127f96 Mon Sep 17 00:00:00 2001 From: georg Date: Sun, 28 Oct 2018 10:59:24 +0000 Subject: Make docs for schleuder version 3.2 accessible Relates #43 --- schleuder/docs/older/3.2/_list_usage_basics.md | 32 +++ schleuder/docs/older/3.2/changes.md | 21 ++ schleuder/docs/older/3.2/concept.md | 67 +++++ schleuder/docs/older/3.2/index.md | 17 ++ schleuder/docs/older/3.2/list-admins.md | 69 +++++ .../older/3.2/schleuder-schema-resend-small.png | Bin 0 -> 49924 bytes .../docs/older/3.2/schleuder-schema-resend.png | Bin 0 -> 141106 bytes schleuder/docs/older/3.2/server-admins.md | 308 +++++++++++++++++++++ schleuder/docs/older/3.2/subscribers.md | 38 +++ schleuder/docs/older/index.md | 1 + 10 files changed, 553 insertions(+) create mode 100644 schleuder/docs/older/3.2/_list_usage_basics.md create mode 100644 schleuder/docs/older/3.2/changes.md create mode 100644 schleuder/docs/older/3.2/concept.md create mode 100644 schleuder/docs/older/3.2/index.md create mode 100644 schleuder/docs/older/3.2/list-admins.md create mode 100644 schleuder/docs/older/3.2/schleuder-schema-resend-small.png create mode 100644 schleuder/docs/older/3.2/schleuder-schema-resend.png create mode 100644 schleuder/docs/older/3.2/server-admins.md create mode 100644 schleuder/docs/older/3.2/subscribers.md (limited to 'schleuder') diff --git a/schleuder/docs/older/3.2/_list_usage_basics.md b/schleuder/docs/older/3.2/_list_usage_basics.md new file mode 100644 index 0000000..a33a59f --- /dev/null +++ b/schleuder/docs/older/3.2/_list_usage_basics.md @@ -0,0 +1,32 @@ +## Using a list + +Everything you send to `foo@hostname` will be send to all subscribers, but they will see only certain headers and the body of your email. The selection of these headers can be configured for each list individually by the list-admins. + +### Getting a list's public key + +Each Schleuder-list replies with its public key to any email sent to `foo-sendkey@hostname`. E.g. to receive the key for our contact address write an email to `team-sendkey@schleuder.org`. + +### Special keywords + +Schleuder knows some special keywords that trigger different behaviour. You can e.g. subscribe someone, or resend an email to a non-subscriber using keywords. See a list of available keywords below. + +Keywords require that: + +* they start the line and begin with "x-", +* they are written into the beginning of the *first text-part* of the email (usually that's just the normal body of the email), +* possible arguments must be written *on the same line* as the keyword (exceptions are mentioned in the descriptions below), +* the email must be *encrypted and signed* by a list-member's key. +* the email must be formatted as a *plain text* message and not with HTML, RTF or similar formatting. + +Keywords can be repeated within one email at will. +Letter case doesn't matter. + +There are two types of keywords: those to enhance messages sent over the list ("list-keywords"), and those to request something from Schleuder ("request-keywords"). + +#### Security + +To mitigate replay attacks of emails containing keywords, every email using a keyword **must** contain the special `x-list-name` keyword followed by the list's emailaddress. Example: + +x-list-name: someone@example.org +: **You must always provide this keyword once per email.** Without it, no other keyword will be considered but you will receive an error message. + diff --git a/schleuder/docs/older/3.2/changes.md b/schleuder/docs/older/3.2/changes.md new file mode 100644 index 0000000..7a3a503 --- /dev/null +++ b/schleuder/docs/older/3.2/changes.md @@ -0,0 +1,21 @@ +--- +title: Changes from Schleuder 3.1 to 3.2 +--- + +{: .note} +This list describes changes that users or list-admins of Schleuder should be aware of. For a more technical changelog, please see the [repository](https://0xacab.org/schleuder/schleuder). + +User-relevant changes in version 3.2 compared to version 3.1: + +* To improve consistency with the English language, `X-LISTNAME` has been renamed to `X-LIST-NAME`. `X-LISTNAME` still works, but will be deprecated, therefore please use `X-LIST-NAME` from now on. +* Lists can have an internal-footer now. It's appended to each message sent to a subscriber (if it's not blank). +* New keywords: `X-RESEND-UNENCRYPTED` and `X-RESEND-CC-UNENCRYPTED`. With them you can enforce that resent-email will be sent in the clear, regardless of whether we would find a key for the recipient or not. +* The short representation of GnuPG keys became more human-friendly. Besides the fingerprint we now show the email-address of the first UID, the generation-date, and (if present) the expiration-date. +* The resend-keywords now check the given arguments to be valid email-addresses, and block resending if any one is found invalid. +* `X-LIST-KEYS` does not require an argument anymore. +* `X-SUBSCRIBE` now handles the combination of space-separated fingerprint and additional arguments (admin-flag, delivery-enabled-flag) correctly. +* `X-RESEND` now respects the encoding the mail was sent with. +* Fixed broken encoding of certain character-sequences in encrypted+signed messages. + + +{% include feedback.md %} diff --git a/schleuder/docs/older/3.2/concept.md b/schleuder/docs/older/3.2/concept.md new file mode 100644 index 0000000..da72124 --- /dev/null +++ b/schleuder/docs/older/3.2/concept.md @@ -0,0 +1,67 @@ +--- +title: Concept +--- + +{% include docs-head.md version=3.2 %} + +Schleuder is a gpg-enabled mailing list manager with resending capabilities. This document tries to explain what that means. + + +## An email hub for groups + +Schleuder enables subscribers to communicate encryptedly and pseudonymously. It takes care of all de- and encryption, stripping of headers, formatting conversions, etc. + +But Schleuder can also receive and send emails to non-subscribers, which makes it a useful email hub for groups. + +Incoming emails from non-subscribers ("outside people") are (re)encrypted and distributed among the subscribers, which can communicate internally as well as answer to the outside person via the list. + +The outside person only sees an email address with a public key, but has no information about who is behind it. + +Here's a simple picture of a message that is sent to a non-subscriber ("Zacharias"). It illustrates how Alice, Bob, Claire and David are invisible to Zacharias (click image to enlarge it). + +[![resent-schema](schleuder-schema-resend-small.png 'Click to enlarge')](schleuder-schema-resend.png) + + +### A helpful bot + +Additionally, Schleuder can send out its own public key upon request by email. Anyone sending a message to `listname-sendkey@hostname` will receive a reply that contains the public key of that list. + +And Schleuder can receive administrative commands by email. E.g. it is possible by email to add an OpenPGP-key to a list in order to reply encryptedly to an outside person. + + +## Technical details + +### A "wanted man-in-the-middle" + +Basically Schleuder is a "wanted man-in-the-middle". + +Each list has its own keypair. Schleuder decrypts every incoming email and verifies its signature with the keys from the list's keyring. Then Schleuder loops over the list of subscribers, creates for each a stripped down copy of the message, encrypts it with the subscriber's key and signs it with its own key, and sends it out. + +Schleuder inserts some lines of metadata into the top of the email, containing a (configurable) copy of some of the original headers and the result of the decryption and verification of the incoming email. Here's an example: + + + From: Bob + To: team@schleuder.org + Date: Tue, 6 Apr 2010 17:28:46 +0200 + Enc: encrypted + Sig: Good signature from 12345678DEADBEEF Bob + +The consequence of this approach is that you need to *really trust* the provider that runs Schleuder: they could store and decrypt all emails that pass the lists, if they wanted. + + +### Internal workings + +Schleuder behaves like an email-filter: it reads email from standard-input, and reports errors to standard-error. If all goes well Schleuder closes the initial connection to the Mail Transport Agent (MTA) only after it sent out all outgoing emails. + +In case of an error the MTA includes Schleuder's error message into a bounce-email that is sent back to the sender. + +The keyrings for each list are standard GnuPG keyrings and sit in the filesystem under `$lists_dir/$hostname/$listname/` ($lists_dir is read from `schleuder.yml`, see [Configuration](#configuration)). They can be used manually using gpg2. Please be careful to maintain proper file permissions if you touch the files. + +In the list-directory there's also a list specific log-file (might be missing if the log-level is high and no error occurred yet). + +Other logging is sent to syslog. Where that ends up depends on the operating system and the system administration. + +All other list-related data is stored in the SQL-database. Most data is unserialized, only some values are JSON-encoded. + + +{% include feedback.md %} diff --git a/schleuder/docs/older/3.2/index.md b/schleuder/docs/older/3.2/index.md new file mode 100644 index 0000000..55cbf51 --- /dev/null +++ b/schleuder/docs/older/3.2/index.md @@ -0,0 +1,17 @@ +--- +title: Documentation +--- + +### Schleuder for… + +* [subscribers](subscribers.html) +* [list-admins](list-admins.html) +* [server-admins](server-admins.html) + + +### Changed behaviour + +Changes to the previous version of Schleuder are summarized in [changes](changes.html). + + +{% include feedback.md %} diff --git a/schleuder/docs/older/3.2/list-admins.md b/schleuder/docs/older/3.2/list-admins.md new file mode 100644 index 0000000..ac23859 --- /dev/null +++ b/schleuder/docs/older/3.2/list-admins.md @@ -0,0 +1,69 @@ +--- +title: Documentation for list-admins +--- + +{% include docs-head.md version=3.2 %} + +{% include_relative _list_usage_basics.md %} + + +#### Subscription and key management + +These keywords must be send to `foo-request@hostname`. They are used to get information about the list, its subscribers and keys, or to change that information. + +x-list-subscriptions +: List all subscriptions. + +x-subscribe: person@example.org 0x12345678DEADBEEF12345678DEADBEEF12345678 +: Subscribe the given address and assign it the given OpenPGP-fingerprint. + +x-unsubscribe: person@example.org +: Unsubscribe the given address. + +x-set-fingerprint: 0x12345678DEADBEEF12345678DEADBEEF12345678 +: Assign the key with the given fingerprint to your subscription. + +x-set-fingerprint: person@example.org 0x12345678DEADBEEF12345678DEADBEEF12345678 +: Assign the key with the given fingerprint to the given subscription. This variant of this command may only be used by list-admins. + + +x-list-keys +: Lists all public keys known to the list. To see only keys that match a given string, use `x-list-keys: something`. + +x-add-key: +: Import the attachments or the rest of the email-body into the list's keyring. Only ascii-armored keys are supported. + +x-delete-key: 0x12345678DEADBEEF12345678DEADBEEF12345678 +: Delete the key with the given fingerprint from the list's keyring. + +x-get-key: 0x12345678DEADBEEF12345678DEADBEEF12345678 +: Export the key with the given fingerprint from the list's keyring. + +x-fetch-key: 0x12345678DEADBEEF12345678DEADBEEF12345678 +: Fetch the key with the given fingerprint from a keyserver and import it into the list's keyring. (This works only if a keyserver has been configured by the provider.) + +This keyword must be send to the normal list-address: `foo@hostname`. + +x-attach-listkey: +: Attachs the public key of the list. Probably most useful in combination with x-resend. + + +#### Other + +These must also be sent to the request-address: . + +x-get-logfile: +: Sends the logfile of the list. + +x-get-version: +: Returns the version of schleuder. + +x-sign-this: +: Sign the remaining contents of the email body or the attachments with the list's key. Use this e.g. to provide GnuPG-signatures for things you are publishing. + + +[↑](#top "Go to top of page") +{: .linktotop} + + +{% include docs-page-footer.md %} diff --git a/schleuder/docs/older/3.2/schleuder-schema-resend-small.png b/schleuder/docs/older/3.2/schleuder-schema-resend-small.png new file mode 100644 index 0000000..5dc7440 Binary files /dev/null and b/schleuder/docs/older/3.2/schleuder-schema-resend-small.png differ diff --git a/schleuder/docs/older/3.2/schleuder-schema-resend.png b/schleuder/docs/older/3.2/schleuder-schema-resend.png new file mode 100644 index 0000000..4804c41 Binary files /dev/null and b/schleuder/docs/older/3.2/schleuder-schema-resend.png differ diff --git a/schleuder/docs/older/3.2/server-admins.md b/schleuder/docs/older/3.2/server-admins.md new file mode 100644 index 0000000..a3df9df --- /dev/null +++ b/schleuder/docs/older/3.2/server-admins.md @@ -0,0 +1,308 @@ +--- +title: Documentation for server-admins +--- + +{% include docs-head.md version=3.2 %} + + +## Setup Schleuder + +### Installation + +You can install schleuder either from Linux distribution packages or rubygems. Currently there are supported distribution packages for Debian ("stretch-backports" and "buster") and CentOS 7. If you use one of the directly supported platforms, you should choose the packages over the gems. + +{: .note} +Don't use the packages provided by Ubuntu in all releases up to and including 17.10, they are severely outdated. On Ubuntu 18.04 only use the package if it has at least version 3.2.2. + +Besides schleuder you should also install at least one of [schleuder-cli](https://0xacab.org/schleuder/schleuder-cli) (the command line tool to manage Schleuder lists), and [schleuder-web](https://0xacab.org/schleuder/schleuder-web) (the web interface to manage and maintain Schleuder lists). + +Additionally we recommend running an entropy source such as `haveged`. This ensures Schleuder won't be blocked by lacking entropy, which otherwise might happen e.g. during key generation. + +#### Debian + +{: .note} +All steps need root privileges. + +We maintain schleuder and schleuder-cli in "stretch-backports" and "buster". (For production usage we recommend Debian "stretch".) + +First, add the backports to your APT sources list directory: + + echo "deb http://deb.debian.org/debian stretch-backports main" > /etc/apt/sources.list.d/stretch-backports.list + +After this, update the APT package cache: + + apt-get update + +Finally, install schleuder and schleuder-cli via: + + apt-get install -t stretch-backports schleuder schleuder-cli + +The package will finalize the setup of Schleuder, too. + + +#### CentOS + +For CentOS 7 there is a maintained [copr-repository](https://copr.fedorainfracloud.org/coprs/schleuder/schleuder/) using [Software Collections](https://www.softwarecollections.org/en/). + +{: .note} +All steps need root privileges + +Install the repository & the SCL repository + + yum install centos-release-scl + curl -o /etc/yum.repos.d/schleuder-schleuder-epel-7.repo https://copr.fedorainfracloud.org/coprs/schleuder/schleuder/repo/epel-7/schleuder-schleuder-epel-7.repo + +Now you are ready to install schleuder and schleuder-cli + + yum install schleuder schleuder-cli + +Afterwards run `schleuder install` to finalize the setup of Schleuder. This creates necessary directories, copies example configs, etc. If you see errors about missing write permissions please follow the advice given. + +{: .note} +The copr-repository also provides you with a package for [schleuder-web](https://0xacab.org/schleuder/schleuder-web/). Please read the documentation of schleuder-web on how to get it up and running. + + +#### From Ruby-Gem + +For instructions on how to install from rubygems please see the [README](https://0xacab.org/schleuder/schleuder/blob/master/README.md#installing-schleuder) of Schleuder. + + +#### Puppet + +There is a [schleuder puppet module](https://0xacab.org/schleuder/puppet-schleuder) to automate the installation and configuration of schleuder, schleuder-cli, and schleuder-web, and the creation and deletion of schleuder lists. Have a look at its [README](https://0xacab.org/schleuder/puppet-schleuder/blob/master/README.md) on how to use it. Currently it works for CentOS 7, but we would like to make it work for Debian as well - help would be highly appreciated. + + +### Configuration + +Schleuder reads its **basic settings** from a file that it by default expects at `/etc/schleuder/schleuder.yml`. To make Schleuder read a different file set the environment variable `SCHLEUDER_CONFIG` to the path to your file when running schleuder. E.g.: + + SCHLEUDER_CONFIG=/usr/local/etc/schleuder.yml /path/to/bin/schleuder ... + +For explanations of the possible settings read the default config file (also [available in the repository](https://0xacab.org/schleuder/schleuder/blob/master/etc/schleuder.yml)). + +The **default settings for new lists** are read from another config file. By default Schleuder looks at `/etc/schleuder/list-defaults.yml`. To make Schleuder read a different file set the environment variable `SCHLEUDER_LIST_DEFAULTS` analogous to above. The possible settings are explained in the default config file, which is [also available in the repository](https://0xacab.org/schleuder/schleuder/blob/master/etc/list-defaults.yml). + +Once a list is created, it is not affected by these configuration files any more. Existing lists have their configuration stored in the database. The settings in the database can be shown and set via the schleuder API, available through schleuder-web or schleuder-cli. Run `schleuder-cli lists help` and `schleuder-cli lists list-options` for more information on the latter. + +### Hook into Mail Transport Agent + +In "work"-mode, Schleuder expects the list's email-address as second argument (first one is "work") and the incoming email on standard-input. + +To enable Schleuder to receive emails, your Mail Transport Agent must be configured accordingly. How to do this with Postfix is documented in detail below. + +#### Postfix + +{: .note} +This section describes only those parts of a Postfix-setup that are relevant to Schleuder. We assume that you have a sensible and tested Postfix-setup already. + +Firstly, to hook Schleuder into Postfix adapt these lines (path and maybe user) and add them to `master.cf`: + + schleuder unix - n n - - pipe + flags=DRhu user=schleuder argv=/path/to/bin/schleuder work ${recipient} + +Then you have to chose how postfix should decide if a message should be delivered to Schleuder. There are two options: + +1. Configure it for each list individually. That's the way to go if you don't run many lists, or use the respective domain also for a varying number of email accounts or aliases. +2. Dedicate a whole domain to Schleuder. That's the way to go if you run more lists than email accounts or aliases on that domain. + + +**To configure each list individually,** add these lines to `main.cf`: + + schleuder_destination_recipient_limit = 1 + transport_maps = hash:/etc/postfix/transport_schleuder + +Now adapt the following lines for each list and add them to `/etc/postfix/transport_schleuder`: + + foo@example.org schleuder: + foo-request@example.org schleuder: + foo-owner@example.org schleuder: + foo-bounce@example.org schleuder: + foo-sendkey@example.org schleuder: + +Afterwards run `postmap /etc/postfix/transport_schleuder` and restart postfix. Remember to repeat this also for newly created lists later. + + +Another way to tell postfix which domain and list can be piped to schleuder is to get that information out of the sqlite database. A requirement for that is the postfix-sqlite package, which isn't in the standard repositories of CentOS, but Debian. + +**To dedicate a whole domain to Schleuder,** add these lines to `main.cf`: + + schleuder_destination_recipient_limit = 1 + virtual_mailbox_domains = sqlite:/etc/postfix/schleuder_domain_sqlite.cf + virtual_transport = schleuder + virtual_alias_maps = hash:/etc/postfix/virtual_aliases + virtual_mailbox_maps = sqlite:/etc/postfix/schleuder_list_sqlite.cf + +Then adapt and add at least the following exceptions from the All-to-Schleuder-rule to `/etc/postfix/virtual_aliases`: + + postmaster@lists.example.org root@anotherdomain + abuse@lists.example.org root@anotherdomain + MAILER-DAEMON@lists.example.org root@anotherdomain + root@lists.example.org root@anotherdomain + +Afterwards run `postmap /etc/postfix/virtual_aliases`. + +The file `schleuder_domain_sqlite.cf` can ask the schleuder sqlite database (this will delegate the whole domain to schleuder): + + dbpath = /var/lib/schleuder/db.sqlite + query = select distinct substr(email, instr(email, '@') + 1) from lists + where email like '%%%s' + +And the file `schleuder_list_sqlite.cf` can also get the information from the schleuder sqlite database: + + dbpath = /var/lib/schleuder/db.sqlite + query = select 'present' from lists + where email = '%s' + or email = replace('%s', '-bounce@', '@') + or email = replace('%s', '-owner@', '@') + or email = replace('%s', '-request@', '@') + or email = replace('%s', '-sendkey@', '@') + +From now on each Schleuder-list will instantly be reachable by email once it was created. + +#### Exim + +{: .note} +This section describes only those parts of a Exim-setup that are relevant to Schleuder. We assume that you have a sensible and tested Exim-setup already. + +As with any exim email routing, we need to configure essentially a router that accepts and directs a mail to a transport, which knows how to hand-over an email to schleuder. + +Within the `begin routers` section of your `exim.conf` you can add the following router: + + mlschleuder: + driver = accept + condition = ${lookup {$local_part@$domain}lsearch{/etc/exim/schleuder-lists} {yes}{no}} + local_part_suffix_optional + local_part_suffix = +* : -bounce : -sendkey : -request : -owner + transport = mlschleuder_transport_local + no_more + +`/etc/exim/schleuder-lists` is a simple textfile containing one list-address per line. You can for example create it by executing `schleuder-cli lists list > /etc/exim/schleuder-lists` after creating or deleting any lists. In more advanced setups you might have different conditions depending on how you manage the inventory of your schleuder lists and decide to accept a mail for a list. + +Within the `begin transports` section of your `exim.conf` you then configure the transport: + + mlschleuder_transport_local: + driver = pipe + user = schleuder + group = schleuder + # schleuders generates nice log messages for some of the problems + return_fail_output = true + home_directory = /var/lib/schleuder/lists/$domain/$local_part + command = "/usr/bin/schleuder work $local_part$local_part_suffix@$domain" + message_size_limit = 10M + +Please note that we keep the `$local_part_suffix` when handing the mail over to schleuder, so schleuder can e.g. detect bounces or sendkey emails properly. + +Restart exim and you have your working schleuder+exim setup. + +Remember to repeat dumping the list of schleuder-lists to `/etc/exim/schleuder-lists` also for newly created lists later. + +### Schleuder API + +The Schleuder API is provided by `schleuder-api-daemon`. Configuration clients (schleuder-web, schleuder-cli) use it to access information about lists, subscriptions, and keys. As you probably want to at least use schleuder-cli from localhost, setting up schleuder-api-daemon is useful even without remote clients. + +{: .note} +Schleuder does **not** use schleuder-api-daemon to process emails. You can stop schleuder-api-daemon at any time without breaking the email flow. + +To run `schleuder-api-daemon`, depending on the type of operating system and the setup you are using, you can either start the systemd-unit-file: + + systemctl start schleuder-api-daemon + +Or you can run it manually in a shell: + + schleuder-api-daemon + +{: .note} +Please take care to run `schleuder-api-daemon` as the user that owns the directory of schleuder lists (by default `/var/lib/schleuder/lists`) to avoid running into file permission problems! + +#### Transport encryption + +schleuder-api-daemon uses transport encyrption (TLS) for all connections. The required TLS-certifcates should have been generated during the setup (`schleuder install`). You can generate new ones at any time by executing: + + schleuder cert generate + +If the file systems permissions allow it, Schleuder will write the certificate and the key directly into the correct files (paths are read from the configuration file). Otherwise you might have to move them. Please read the output of the above command for possible instructions. + +In case you already have a suitable certificate you can use that, too. Its hostnames do not matter. Just copy it to the paths specified in the configuration file, or change those paths. + +In order to verify the connection, each client needs to know the fingerprint of the API-certificate. The fingerprint will be shown when generating the certificates. Later you can always have it show again by executing this: + + schleuder cert fingerprint + +{: .note} +Use secure channels to transport this information! + +#### Authentication + +The Schleuder API uses API-keys to authenticate clients. + +You can generate new API-keys by executing: + + schleuder new_api_key + +To enable the client to connect, their API-key must be added to the section `valid_api_keys` in Schleuder's configuration file. + +{: .note} +Provide each client with their own API-key, and use secure channels to transport this information! + +{: .note} +There is **no authorization of clients,** yet. Each client is allowed every action. So be wary who to give an API-key to. schleuder-web does its own authorization, but schleuder-cli does not! + + + +[↑](#top "Go to top of page") +{: .linktotop} + +## Managing a list + +To create and manage lists you have two options: schleuder-web and schleuder-cli. + +Both require a running `schleuder-api-daemon`. Please see [the previous section](#schleuder-api) on how to set that up. + + +### schleuder-web + +To create lists with schleuder-web log in as `root@localhost`. Managing lists is allowed to each list-admin. + +### schleuder-cli + +To use schleuder-cli please see the output of + + schleuder-cli help + + +[↑](#top "Go to top of page") +{: .linktotop} + +## Maintenance + +{: .note} +Please take care to have the following commands run by the user that owns the directory of schleuder lists (by default `/var/lib/schleuder/lists`) to avoid running into file permission problems! + + +Schleuder can **check all keys** that are present in the list's keyrings for (upcoming) expiration dates, revocation, or other reasons for not being usable. + +Call this command weekly from cron to automate the check and have the results sent to the respective list-admins: + + schleuder check_keys + + +Schleuder can also **refresh all keys** in the same manner. Each key of each list will be refreshed from a keyserver one by one. If you're using gpg 2.1, it's possible to configure a TOR onion service to be used as keyserver! See [the config](https://0xacab.org/schleuder/schleuder/blob/master/etc/schleuder.yml) for an example. + + +Call this command weekly from cron to automate the check and have the results sent to the respective list-admins: + + schleuder refresh_keys + +The available packages for Debian and CentOS both install a weekly cron job that check and refresh keys. Listadmins will be notified about issues with or changes to their keyring. + +An additional maintenance command is available that allows you to pin subscriptions to their best matching key. If there is no key assigned, schleuder will try to select a key from the list's keyring that distinctly matches the subscription's email address. + +This feature should be used with care. It's easy for a malicious (or inexperienced) person to inject additional user-IDs into the list's keyring. This can lead to situations in which people suddenly receive emails that are encrypted to a key they don't own. + +You should better not run this command automatedly, and you should always examine the output closely to check for unintended consequences. + + schleuder pin_keys + + +{% include docs-page-footer.md %} + diff --git a/schleuder/docs/older/3.2/subscribers.md b/schleuder/docs/older/3.2/subscribers.md new file mode 100644 index 0000000..bbfa291 --- /dev/null +++ b/schleuder/docs/older/3.2/subscribers.md @@ -0,0 +1,38 @@ +--- +title: Documentation for subscribers +--- + +{% include docs-head.md version=3.2 %} + +{% include_relative _list_usage_basics.md %} + + +#### Resending + +The resending-keywords must be included in messages sent to the normal list-address: `foo@hostname`. + +x-resend: someone@example.org +: Send the message to the given address, encrypted if possible, otherwise in the clear. + +x-resend-encrypted-only: someone@example.org +: Send the message to the given address only if it could be encrypted. Can be abbreviated to `x-resend-enc`. + +x-resend-unencrypted: someone@example.org +: Send the message to the given address without encrypting it. You can use this keyword to make schleuder skip looking for a matching key for this address and enforce sending the email out in the clear. + +x-resend-cc: someone@example.org anotherperson@example.org +: Send one message to all of the given addresses in Cc, so they get to know of each other (encrypted if possible, otherwise in the clear). + +x-resend-cc-encrypted-only: someone@example.org +: Send one message to all of the given addresses in Cc, so they get to know of each other, only if it could be encrypted to all of those addresses. Can be abbreviated to `x-resend-cc-enc.` + +x-resend-cc-unencrypted: someone@example.org +: Send one unencrypted message to all of the given addresses in Cc, so they get to know of each other. We skip looking for any key and will just send out the email in the clear. + + +### Contact list-owner + +Write to `foo-owner@hostname` to contact the list-owner(s) even if you don't know who they are. Use the list's key to encrypt the email! + + +{% include docs-page-footer.md %} diff --git a/schleuder/docs/older/index.md b/schleuder/docs/older/index.md index 12d81ce..33bbdb8 100644 --- a/schleuder/docs/older/index.md +++ b/schleuder/docs/older/index.md @@ -4,6 +4,7 @@ title: Older documentation Here are links to the documentation for older versions of Schleuder: +* [3.2](3.2/) * [3.1](3.1/) * [3.0](3.0/) * [2.x](https://schleuder2.nadir.org/documentation.html) -- cgit v1.2.3 From cf6fe5771d2d1f8ca4cf794ce4f9968ed977c8f0 Mon Sep 17 00:00:00 2001 From: georg Date: Sun, 28 Oct 2018 11:25:48 +0000 Subject: Add docs for schleuder version 3.3 Closes #36 Closes #43 --- schleuder/docs/changes.md | 24 ++++++++++++------------ schleuder/docs/concept.md | 2 +- schleuder/docs/list-admins.md | 10 ++++++---- schleuder/docs/server-admins.md | 2 +- schleuder/docs/subscribers.md | 2 +- 5 files changed, 21 insertions(+), 19 deletions(-) (limited to 'schleuder') diff --git a/schleuder/docs/changes.md b/schleuder/docs/changes.md index 7a3a503..e0b1e60 100644 --- a/schleuder/docs/changes.md +++ b/schleuder/docs/changes.md @@ -1,21 +1,21 @@ --- -title: Changes from Schleuder 3.1 to 3.2 +title: Changes from Schleuder 3.2 to 3.3 --- {: .note} This list describes changes that users or list-admins of Schleuder should be aware of. For a more technical changelog, please see the [repository](https://0xacab.org/schleuder/schleuder). -User-relevant changes in version 3.2 compared to version 3.1: - -* To improve consistency with the English language, `X-LISTNAME` has been renamed to `X-LIST-NAME`. `X-LISTNAME` still works, but will be deprecated, therefore please use `X-LIST-NAME` from now on. -* Lists can have an internal-footer now. It's appended to each message sent to a subscriber (if it's not blank). -* New keywords: `X-RESEND-UNENCRYPTED` and `X-RESEND-CC-UNENCRYPTED`. With them you can enforce that resent-email will be sent in the clear, regardless of whether we would find a key for the recipient or not. -* The short representation of GnuPG keys became more human-friendly. Besides the fingerprint we now show the email-address of the first UID, the generation-date, and (if present) the expiration-date. -* The resend-keywords now check the given arguments to be valid email-addresses, and block resending if any one is found invalid. -* `X-LIST-KEYS` does not require an argument anymore. -* `X-SUBSCRIBE` now handles the combination of space-separated fingerprint and additional arguments (admin-flag, delivery-enabled-flag) correctly. -* `X-RESEND` now respects the encoding the mail was sent with. -* Fixed broken encoding of certain character-sequences in encrypted+signed messages. +User-relevant changes in version 3.3 compared to version 3.2: +* Handle missing arguments for several keywords and reply with a helpful error-message. +* Send replies to keyword-usage and notices to admins regardless of the delivery-flag of their subscription. +* `X-UNSUBSCRIBE` will refuse to unsubscribe the last admin of a list. +* Handle "protected subjects" in a way that Thunderbird/Enigmail recognize. +* `X-SET-FINGERPRINT` will not anymore allow setting an empty fingerprint. +* To remove a fingerprint from a subscription one can use the new keyword `X-UNSET-FINGERPRINT`. +* The output of the keywords `X-ADD-KEY` and `X-DELETE-KEY` now also show the "oneline"-format to represent keys. +* In the response to `X-ADD-KEY`, differentiate between "newly imported" and "updated" keys. +* Parse keywords up to the first line detected as mail content. +* Extend the pseudoheaders configuration option to support `sig` and `enc` as configurable and sortable fields. {% include feedback.md %} diff --git a/schleuder/docs/concept.md b/schleuder/docs/concept.md index da72124..808d8ae 100644 --- a/schleuder/docs/concept.md +++ b/schleuder/docs/concept.md @@ -2,7 +2,7 @@ title: Concept --- -{% include docs-head.md version=3.2 %} +{% include docs-head.md version=3.3 %} Schleuder is a gpg-enabled mailing list manager with resending capabilities. This document tries to explain what that means. diff --git a/schleuder/docs/list-admins.md b/schleuder/docs/list-admins.md index ac23859..59f1f3e 100644 --- a/schleuder/docs/list-admins.md +++ b/schleuder/docs/list-admins.md @@ -2,7 +2,7 @@ title: Documentation for list-admins --- -{% include docs-head.md version=3.2 %} +{% include docs-head.md version=3.3 %} {% include_relative _list_usage_basics.md %} @@ -18,14 +18,16 @@ x-subscribe: person@example.org 0x12345678DEADBEEF12345678DEADBEEF12345678 : Subscribe the given address and assign it the given OpenPGP-fingerprint. x-unsubscribe: person@example.org -: Unsubscribe the given address. +: Unsubscribe the given address. It is not possible to unsubscribe the last admin of a list. x-set-fingerprint: 0x12345678DEADBEEF12345678DEADBEEF12345678 -: Assign the key with the given fingerprint to your subscription. +: Assign the key with the given fingerprint to your subscription. It is not possible to set an empty fingerprint. To unset a fingerprint use `x-unset-fingerprint`. x-set-fingerprint: person@example.org 0x12345678DEADBEEF12345678DEADBEEF12345678 -: Assign the key with the given fingerprint to the given subscription. This variant of this command may only be used by list-admins. +: Assign the key with the given fingerprint to the given subscription. This variant of this command may only be used by list-admins. To unset a fingerprint use `x-unset-fingerprint`. +x-unset-fingerprint: person@example.org +: Remove the fingerprint associated with a given subscription. x-list-keys : Lists all public keys known to the list. To see only keys that match a given string, use `x-list-keys: something`. diff --git a/schleuder/docs/server-admins.md b/schleuder/docs/server-admins.md index a3df9df..4e2ac11 100644 --- a/schleuder/docs/server-admins.md +++ b/schleuder/docs/server-admins.md @@ -2,7 +2,7 @@ title: Documentation for server-admins --- -{% include docs-head.md version=3.2 %} +{% include docs-head.md version=3.3 %} ## Setup Schleuder diff --git a/schleuder/docs/subscribers.md b/schleuder/docs/subscribers.md index bbfa291..e549919 100644 --- a/schleuder/docs/subscribers.md +++ b/schleuder/docs/subscribers.md @@ -2,7 +2,7 @@ title: Documentation for subscribers --- -{% include docs-head.md version=3.2 %} +{% include docs-head.md version=3.3 %} {% include_relative _list_usage_basics.md %} -- cgit v1.2.3 From bbeabd8bd8ce697a21e81fe4acaeb61df5b99876 Mon Sep 17 00:00:00 2001 From: paz Date: Sun, 3 Feb 2019 23:16:26 +0100 Subject: Text work on user-relevant changes. Also include the hint on older versions at the top. --- schleuder/docs/changes.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'schleuder') diff --git a/schleuder/docs/changes.md b/schleuder/docs/changes.md index e0b1e60..dbce06b 100644 --- a/schleuder/docs/changes.md +++ b/schleuder/docs/changes.md @@ -5,17 +5,18 @@ title: Changes from Schleuder 3.2 to 3.3 {: .note} This list describes changes that users or list-admins of Schleuder should be aware of. For a more technical changelog, please see the [repository](https://0xacab.org/schleuder/schleuder). +{% include docs-head.md version=3.3 %} + User-relevant changes in version 3.3 compared to version 3.2: -* Handle missing arguments for several keywords and reply with a helpful error-message. -* Send replies to keyword-usage and notices to admins regardless of the delivery-flag of their subscription. +* List-admins now receive replies to keyword-usage and notices regardless of the delivery-flag of their subscription. +* Keywords are now only looked for in the beginning of the message, up to the first line detected as mail content. Later content will not be interpreted or touched. * `X-UNSUBSCRIBE` will refuse to unsubscribe the last admin of a list. -* Handle "protected subjects" in a way that Thunderbird/Enigmail recognize. -* `X-SET-FINGERPRINT` will not anymore allow setting an empty fingerprint. -* To remove a fingerprint from a subscription one can use the new keyword `X-UNSET-FINGERPRINT`. -* The output of the keywords `X-ADD-KEY` and `X-DELETE-KEY` now also show the "oneline"-format to represent keys. +* `X-SET-FINGERPRINT` will not anymore allow setting an empty fingerprint. To remove a fingerprint from a subscription one can use the new keyword `X-UNSET-FINGERPRINT`. +* Missing arguments for several keywords are better handled and replied to with a helpful error-message. * In the response to `X-ADD-KEY`, differentiate between "newly imported" and "updated" keys. -* Parse keywords up to the first line detected as mail content. -* Extend the pseudoheaders configuration option to support `sig` and `enc` as configurable and sortable fields. +* In the response to `X-ADD-KEY` and `X-DELETE-KEY`, more information on each key than just the fingerprint is shown. +* In the pseudoheaders, `sig` and `enc` are now configurable. They can be reordered in or removed from the list-option `headers_to_meta`. +* Schleuder now handles "protected subjects" in a way that Thunderbird/Enigmail recognize. {% include feedback.md %} -- cgit v1.2.3