summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKali Kaneko <kali@leap.se>2015-01-22 20:27:08 -0400
committerKali Kaneko <kali@leap.se>2015-02-11 14:05:44 -0400
commit459524ffa25eb9dae95a5f761024d15b6bdb25df (patch)
tree0e02b31ca6ab74ff44395e16f5dc7701c85b7f11
parentf211669206d30088181f7299aaa0ffb65a89becc (diff)
re-add the missing hacking docs; add tb imap logging hint
-rw-r--r--docs/conf.py2
-rw-r--r--docs/hacking.rst163
-rw-r--r--docs/index.rst2
3 files changed, 166 insertions, 1 deletions
diff --git a/docs/conf.py b/docs/conf.py
index 8e08f09..51e9d66 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -57,7 +57,7 @@ copyright = u'2014, Kali Kaneko'
# built documents.
#
# The short X.Y version.
-version = '0.3.9'
+version = '0.4.0alpha1'
# The full version, including alpha/beta/rc tags.
release = '0.3.9'
diff --git a/docs/hacking.rst b/docs/hacking.rst
new file mode 100644
index 0000000..daa3762
--- /dev/null
+++ b/docs/hacking.rst
@@ -0,0 +1,163 @@
+.. _hacking:
+
+========
+Hacking
+========
+
+Some hints oriented to `leap.mail` hackers. These notes are mostly related to
+the imap server, although they probably will be useful for other pieces too.
+
+Don't panic! Just manhole into it
+=================================
+
+If you want to inspect the objects living in your application memory, in
+realtime, you can manhole into it.
+
+First of all, check that the modules ``PyCrypto`` and ``pyasn1`` are installed
+into your system, they are needed for it to work.
+
+You just have to pass the ``LEAP_MAIL_MANHOLE=1`` enviroment variable while
+launching the client::
+
+ LEAP_MAIL_MANHOLE=1 bitmask --debug
+
+And then you can ssh into your application! (password is "leap")::
+
+ ssh boss@localhost -p 2222
+
+Did I mention how *awesome* twisted is?? ``:)``
+
+
+Profiling
+=========
+If using ``twistd`` to launch the server, you can use twisted profiling
+capabities::
+
+ LEAP_MAIL_CONF=~/.leapmailrc twistd --profile=/tmp/mail-profiling -n -y imap-server.tac
+
+``--profiler`` option allows you to select different profilers (default is
+"hotshot").
+
+You can also do profiling when using the ``bitmask`` client. Enable the
+``LEAP_PROFILE_IMAPCMD`` environment flag to get profiling of certain IMAP
+commands::
+
+ LEAP_PROFILE_IMAPCMD=1 bitmask --debug
+
+Offline mode
+============
+
+The client has an ``--offline`` flag that will make the Mail services (imap,
+currently) not try to sync with remote replicas. Very useful during development,
+although you need to login with the remote server at least once before being
+able to use it.
+
+Running the service with twistd
+===============================
+
+In order to run the mail service (currently, the imap server only), you will
+need a config with this info::
+
+ [leap_mail]
+ userid = "user@provider"
+ uuid = "deadbeefdeadabad"
+ passwd = "foobar" # Optional
+
+In the ``LEAP_MAIL_CONF`` enviroment variable. If you do not specify a password
+parameter, you'll be prompted for it.
+
+In order to get the user uid (uuid), look into the
+``~/.config/leap/leap-backend.conf`` file after you have logged in into your
+provider at least once.
+
+Run the twisted service::
+
+ LEAP_IMAP_CONFIG=~/.leapmailrc twistd -n -y imap-server.tac
+
+Now you can telnet into your local IMAP server and read your mail like a real
+programmerâ„¢::
+
+ % telnet localhost 1984
+ Trying 127.0.0.1...
+ Connected to localhost.
+ Escape character is '^]'.
+ * OK [CAPABILITY IMAP4rev1 LITERAL+ IDLE NAMESPACE] Twisted IMAP4rev1 Ready
+ tag LOGIN me@myprovider.net mahsikret
+ tag OK LOGIN succeeded
+ tag SELECT Inbox
+ * 2 EXISTS
+ * 1 RECENT
+ * FLAGS (\Seen \Answered \Flagged \Deleted \Draft \Recent List)
+ * OK [UIDVALIDITY 1410453885932] UIDs valid
+ tag OK [READ-WRITE] SELECT successful
+ ^]
+ telnet> Connection closed.
+
+
+Although you probably prefer to use ``offlineimap`` for tests::
+
+ offlineimap -c LEAPofflineimapRC-tests
+
+
+Minimal offlineimap configuration
+---------------------------------
+
+You can use this as a sample offlineimap config file::
+
+ [general]
+ accounts = leap-local
+
+ [Account leap-local]
+ localrepository = LocalLeap
+ remoterepository = RemoteLeap
+
+ [Repository LocalLeap]
+ type = Maildir
+ localfolders = ~/LEAPMail/Mail
+
+ [Repository RemoteLeap]
+ type = IMAP
+ ssl = no
+ remotehost = localhost
+ remoteport = 1984
+ remoteuser = user
+ remotepass = pass
+
+Testing utilities
+-----------------
+There are a bunch of utilities to test IMAP delivery in ``imap/tests`` folder.
+If looking for a quick way of inspecting mailboxes, have a look at ``getmail``::
+
+ ./getmail me@testprovider.net mahsikret
+ 1. Drafts
+ 2. INBOX
+ 3. Trash
+ Which mailbox? [1] 2
+ 1 Subject: this is the time of the revolution
+ 2 Subject: ignore me
+
+ Which message? [1] (Q quits) 1
+ 1 X-Leap-Provenance: Thu, 11 Sep 2014 16:52:11 -0000; pubkey="C1F8DE10BD151F99"
+ Received: from mx1.testprovider.net(mx1.testprovider.net [198.197.196.195])
+ (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
+ (Client CN "*.foobar.net", Issuer "Gandi Standard SSL CA" (not verified))
+ by blackhole (Postfix) with ESMTPS id DEADBEEF
+ for <me@testprovider.net>; Thu, 11 Sep 2014 16:52:10 +0000 (UTC)
+ Delivered-To: 926d4915cfd42b6d96d38660c04613af@testprovider.net
+ Message-Id: <20140911165205.GB8054@samsara>
+ From: Kali <kali@leap.se>
+
+ (snip)
+
+
+Debugging IMAP commands
+=======================
+
+Use ``ngrep`` to obtain logs of the commands::
+
+ sudo ngrep -d lo -W byline port 1984
+
+To get verbose output from thunderbird/icedove, set the following environment
+variable::
+
+ NSPR_LOG_MODULES="imap:5" icedove
diff --git a/docs/index.rst b/docs/index.rst
index d8634ea..8bacc51 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -38,6 +38,8 @@ server as another code entity that uses this lower layer.
.. toctree::
:maxdepth: 2
+ hacking
+
.. intro
.. tutorial