From 3d770db69cf6419a808780f7165b4d3d7fb95697 Mon Sep 17 00:00:00 2001 From: Folker Bernitt Date: Thu, 23 Apr 2015 14:26:49 +0200 Subject: Added first draft of maintenance howto. - Issue #335 --- doc/maintenance.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 doc/maintenance.md (limited to 'doc') diff --git a/doc/maintenance.md b/doc/maintenance.md new file mode 100644 index 00000000..38c18bf8 --- /dev/null +++ b/doc/maintenance.md @@ -0,0 +1,97 @@ +Pixelated User Agent Maintenance +================================ + +## Overview + +The command line tool pixelated-maintenace allows you to run some common tasks, mostly related to soledad. + +``` +usage: pixelated-maintenance [-h] [--debug] [--dispatcher file] + [--dispatcher-stdin] [-c ] + [--home HOME] [-lc ] + [-lf ] + {reset,load-mails,dump-soledad,sync} ... + +pixelated maintenance + +positional arguments: + {reset,load-mails,dump-soledad,sync} + commands + reset reset account command + load-mails load mails into account + dump-soledad dump the soledad database + sync sync the soledad database + +optional arguments: + -h, --help show this help message and exit + --debug DEBUG mode. + --dispatcher file run in organization mode, the credentials will be read + from specified file + --dispatcher-stdin run in organization mode, the credentials will be read + from stdin + -c , --config + use specified file for credentials (for test purposes + only) + --home HOME The folder where the user agent stores its data. + Defaults to ~/.leap + -lc , --leap-provider-cert + use specified file for LEAP provider cert authority + certificate (url https:///ca.crt) + -lf , --leap-provider-cert-fingerprint + use specified fingerprint to validate connection with + LEAP provider +``` + +The commands you can run are: + +* reset - Use this to remove all mails from your account. Existing encryption keys like your GnuPG key is not affected +* sync - Sync your soledad database +* load-mails - Loads existing mails into your account +* dump-soledad- Get a soledad database dump. Mostly for debugging use cases + +Like with other such tools, to get detailed help for a single command, call it with the --help option. + +``` +$ pixelated-maintenace load-mails --help +usage: pixelated-maintenance load-mails [-h] file [file ...] + +positional arguments: + file file(s) with mail data + + optional arguments: + -h, --help show this help message and exit +``` + +## How to load mails into an account: + +With the load-mails command you are able to import existing mails into your account. The mails have to be in the **mbox** format, i.e. the need a 'From' line in the first line: +``` +From someone@somedomain.tld +Subject: This is a testmail +To: else@somedomain.tld +X-TW-Pixelated-Tags: nite, macro, trash + +This is a test mail +``` + +*Preparation* + +Steps you might want to consider before importing mails into an account: + +* You have started the pixelated-user-agent at least once for this account +* No pixelated-user-agent is currently running + +To import this mail into your soledad database, put it into an empty folder. Let's assume its called just 'example_mails'. + +``` +$ pixelated-maintenace load-mails /path/to/example_mails +``` + +--- +## Troubleshooting + +### load-mails fails with soledad sync errors + +This happens sometimes, kill the pixelated-maintenance process and start it again, but this time with the *sync* command. **Don't run the load-mails again as you will end up with double the mails**. + -- cgit v1.2.3