Changes

Page history
update schleuder documentation authored by groente's avatar groente
Show whitespace changes
Inline Side-by-side
service/schleuder.md
View page @ 4a73fe95
......@@ -7,16 +7,15 @@ and send emails to non-subscribers via the list.
For more details see https://schleuder.org/schleuder/docs/index.html.
Schleuder runs on [Eugeni](https://db.torproject.org/machines.cgi?host=eugeni). The version of Schleuder currently
installed is: 3.1.2
Schleuder runs on mta.chameleon (part of Tails infra). The version of Schleuder currently
installed is: 4.0.3
Note that Schleuder was considered for retirement but eventually kept,
see [TPA-RFC-41](policy/tpa-rfc-41-schleuder-retirement).
Note that Schleuder was considered for retirement but eventually migrated,
see [TPA-RFC-41](policy/tpa-rfc-41-schleuder-retirement) and [TPA-RFC-71](policy/tpa-rfc-71-emergency-email-deployments-round-2.md).
## Known lists
The list of schleuder list is listed alongside the [main list of
mailing lists](service/lists#list-of-mailing-lists).
The list of schleuder list can be found in [hiera](https://gitlab.tails.boum.org/tails/puppet-code/-/blob/production/hieradata/node/mta.chameleon.eyaml?ref_type=heads)
## Using Schleuder
......@@ -54,7 +53,7 @@ And then:
## Administration of lists
There are two ways to administer schleuder lists: through the CLI interface of the schleuder API daemon, or by sending PGP encrypted emails with the appropriate commands to `listname-request@withtheemail.org`.
There are two ways to administer schleuder lists: through the CLI interface of the schleuder API daemon (sysadmins only), or by sending PGP encrypted emails with the appropriate commands to `listname-request@withtheemail.org`.
### Pre-requisites
......@@ -68,11 +67,7 @@ The daemon is configured to start automatically, but you can verify it's running
#### Permissions
The `schleuder-cli` program should be executed in the context of the `torschleuder` user account:
sudo -u torchleuder schleuder-cli
For this to work, your user account must be a member of the `torschleuder` group.
The `schleuder-cli` program should be executed in the context of `root`.
#### PGP
......@@ -82,36 +77,23 @@ All email commands must be PGP encrypted with the public key of the mailing list
### List creation
To create a list you can:
To create a list you add the list to [hiera](https://gitlab.tails.boum.org/tails/puppet-code/-/blob/production/hieradata/node/mta.chameleon.eyaml?ref_type=heads).
sudo -u torschleuder schleuder-cli lists new secret-team@lists.torproject.org admin@torproject.org /path/to/public.key
Schleuder will create the list gpg key together with the list. Please not that the created keys do not expires. For more information about how Schleuder creates keys you can check: https://0xacab.org/schleuder/schleuder/blob/master/lib/schleuder/list_builder.rb#L120
Puppet will tell schleuder to create the list gpg key together with the list. Please not that the created keys do not expire. For more information about how Schleuder creates keys you can check: https://0xacab.org/schleuder/schleuder/blob/master/lib/schleuder/list_builder.rb#L120
To export a list public key you can do the following:
sudo -u torschleuder schleuder-cli keys export secret-team@lists.torproject.org <list-key-fingerprint>
You also need to add the list to the `transport` file on eugeni,
currently in `tor-puppet.git`, in
`modules/postfix/files/transport.eugeni`. Ask TPA if that makes no
sense to you.
sudo schleuder-cli keys export secret-team@lists.torproject.org <list-key-fingerprint>
### List retirement
To delete a list, use:
To delete a list, remove it from hiera and run:
sudo -u torschleuder schleuder-cli lists delete secret-team@lists.torproject.org
sudo schleuder-cli lists delete secret-team@lists.torproject.org
This will ask for confirmation before deleting the list and all its
data.
Make sure you remove the list from the `transport` file on eugeni,
currently in `tor-puppet.git`, in
`modules/postfix/files/transport.eugeni`. Ask TPA if that makes no
sense to you. Also add an alias in `modules/postfix/files/virtual` if
you want the list redirected elsewhere.
### Subscriptions management
#### CLI daemon
......@@ -120,15 +102,15 @@ Subscription are managed with the subscriptions command.
To subscribe a new user to a list do:
sudo -u torschleuder schleuder-cli subscriptions new secret-team@lists.torproject.org person@torproject.org <fingerprint> /path/to/public.key
sudo schleuder-cli subscriptions new secret-team@lists.torproject.org person@torproject.org <fingerprint> /path/to/public.key
To list current list subscribers:
sudo -u torschleuder schleuder-cli subscriptions list secret-team@lists.torproject.org
sudo schleuder-cli subscriptions list secret-team@lists.torproject.org
To designate (or undesignate) a list admin:
sudo -u torschleuder schleuder-cli subscriptions set secret-team@lists.torproject.org person@torproject.org admin true
sudo schleuder-cli subscriptions set secret-team@lists.torproject.org person@torproject.org admin true
#### Email commands
......@@ -173,4 +155,21 @@ Email-delivery enabled? true
All the other commands are available by typing:
sudo -u torschleuder schleuder-cli help
sudo schleuder-cli help
### Migrating lists
To migrate a schleuder list, go through the following steps:
- export the public and secret keys from the list:
- `gpg --homedir /var/lib/schleuder/lists/[DOMAIN]/[LIST]/ --armor --export > ~/list-pub.asc`
- `gpg --homedir /var/lib/schleuder/lists/[DOMAIN]/[LIST]/ --armor --export-secret-keys > ~/list-sec.asc`
- create the list on the target server, with yourself as admin
- delete the list's secret key on the target server
- copy list-pub.asc and list-sec.asc from the old server to the target server and import them in the list keyring
- adjust the list fingerprint in the lists table in /var/lib/schleuder/db.sqlite
- copy the subscriptions from the old server to the new
- remove yourself as admin
- change the mail transport for the list
- remove the list from the old server
- remove all copies of list-sec.asc (and possible list-pub.asc)