From 3dd19845c17a2ecada8f04f463867fb5c9d5040f Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Thu, 22 Jan 2015 20:27:08 -0400 Subject: re-add the missing hacking docs; add tb imap logging hint --- mail/docs/hacking.rst | 163 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 mail/docs/hacking.rst (limited to 'mail/docs/hacking.rst') diff --git a/mail/docs/hacking.rst b/mail/docs/hacking.rst new file mode 100644 index 0000000..daa3762 --- /dev/null +++ b/mail/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 ; Thu, 11 Sep 2014 16:52:10 +0000 (UTC) + Delivered-To: 926d4915cfd42b6d96d38660c04613af@testprovider.net + Message-Id: <20140911165205.GB8054@samsara> + From: Kali + + (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 -- cgit v1.2.3 From 6218f04f08c90b6cd3b250d725e0cb55a81b505f Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Thu, 19 Feb 2015 00:58:17 -0400 Subject: change environment variable for mail config --- mail/docs/hacking.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'mail/docs/hacking.rst') diff --git a/mail/docs/hacking.rst b/mail/docs/hacking.rst index daa3762..bd9f792 100644 --- a/mail/docs/hacking.rst +++ b/mail/docs/hacking.rst @@ -33,7 +33,7 @@ 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 + LEAP_MAIL_CONFIG=~/.leapmailrc twistd --profile=/tmp/mail-profiling -n -y imap-server.tac ``--profiler`` option allows you to select different profilers (default is "hotshot"). @@ -63,7 +63,7 @@ need a config with this info:: uuid = "deadbeefdeadabad" passwd = "foobar" # Optional -In the ``LEAP_MAIL_CONF`` enviroment variable. If you do not specify a password +In the ``LEAP_MAIL_CONFIG`` 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 @@ -72,7 +72,7 @@ provider at least once. Run the twisted service:: - LEAP_IMAP_CONFIG=~/.leapmailrc twistd -n -y imap-server.tac + LEAP_MAIL_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™:: -- cgit v1.2.3 From a5d45022906baa136cb0c6e576ff37b4f7178507 Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Wed, 10 Jun 2015 17:50:09 -0400 Subject: [docs] minimal mutt configuration snippet because we love to test with mutt. --- mail/docs/hacking.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'mail/docs/hacking.rst') diff --git a/mail/docs/hacking.rst b/mail/docs/hacking.rst index bd9f792..d5669e1 100644 --- a/mail/docs/hacking.rst +++ b/mail/docs/hacking.rst @@ -52,6 +52,19 @@ 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. +Mutt config +=========== + +You cannot live without mutt? You're lucky! Use the following minimal config +with the imap service:: + + set folder="imap://user@provider@localhost:1984" + set spoolfile="imap://user@provider@localhost:1984/INBOX" + set ssl_starttls = no + set ssl_force_tls = no + set imap_pass=MAHSIKRET + + Running the service with twistd =============================== -- cgit v1.2.3 From 1646b018bda0d40b38c747932029a41b8a7c8536 Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Fri, 10 Jul 2015 12:57:44 -0400 Subject: [docs] add some documentation about imap regression tests This is quite manual for the moment being, and it's not integrated into the unittests. But it is useful to have it documented, with some luck we can automate the process even more and add it to the CI quite soon. --- mail/docs/hacking.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'mail/docs/hacking.rst') diff --git a/mail/docs/hacking.rst b/mail/docs/hacking.rst index d5669e1..6c49c21 100644 --- a/mail/docs/hacking.rst +++ b/mail/docs/hacking.rst @@ -161,6 +161,25 @@ If looking for a quick way of inspecting mailboxes, have a look at ``getmail``:: From: Kali (snip) + +IMAP Message Rendering Regressions +---------------------------------- + +For testing the IMAP server implementation, there is a litte regressions script +that needs some manual work from your side. + +First of all, you need an already initialized account. Which for now basically +means you have created a new account with a provider that offers the Encrypted +Mail Service, using the Bitmask Client wizard. Then you need to log in with that +account, and let it generate the secrets and sync with the remote for a first +time. After this you can run the twistd server locally and offline. + +From the ``leap.mail.imap.tests`` folder, and with an already initialized server +running:: + + ./regressions_mime_struct user@provider pass path_to_samples/ + +You can find several message samples in the ``leap/mail/tests`` folder. Debugging IMAP commands -- cgit v1.2.3