[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
-#Using notmuch remotely#
+# Using notmuch remotely #
-##Why?##
-It is hard to keep nomuch tags in sync across multiple instances of
+## Why? ##
+
+It is hard to keep notmuch tags in sync across multiple instances of
notmuch, on multiple computers. Though you can do this with "notmuch
dump" and "notmuch restore", it is often preferable to be able to use
-notmuch on a remote computer as if it were present on a local
-computer.
-
-The following guidelines show how I have accomplished this. It isn't
-perfect, but it works pretty well, and allows me to access notmuch on
-my home computer, using only an emacs client on my netbook or work
-computer, a trivial shell script, a few settings in my .emacs, and
-ssh.
-
-Note that this is all something of a hack, and future versions of
-notmuch will likely make all of these steps much more
-transparent. I'll note particularly which things should become
-unneccessary with future version. At the moment though, this does
-work, and might enable some of you to use notmuch away from your
-primary computer.
-
-##What you will need##
+notmuch on a remote computer as if it were present on a local computer.
+
+The following guidelines show how to accomplished this. It isn't
+perfect, but it works pretty well, and allows one to access notmuch on
+one computer, using only an Emacs client, a trivial shell script, and
+some Emacs and ssh settings on another computer.
+
+## What you will need ##
+
You will need to have the following items in place:
-1. a working notmuch on one computer (let's call that computer
-"server"). The notmuch should be at least version 0.2.
-2. a working notmuch emacs interface on another computer (let's call
-that computer "client")
-3. password-free login (public key authentication) from client to
-server. [Here](http://sial.org/howto/openssh/publickey-auth/) is a
-good page on how to set it up.
-4. a reasonably fast connection. (This isn't really *neccessary*, but
-if your connection is too slow, this won't be very pleasant to use,
-and certainly won't seem transparent.)
-
-##Write a wrapper shell script##
-
-/!\ Now that notmuch (>=0.5) allows for "raw" downloading of messages, a lot
-of the hacks in the older script, posted in 2010, are no longer necessary.
-
-Now we will need to write a simple shell script that does two things:
-
-1. replaces the call to the notmuch binary with a call to notmuch
-over ssh.
-2. caches messages when the entire raw message is downloaded. This
-avoids the need to constantly download large attachments over and
-over. (NB: this just checks to see if a message with the same id
-has already been cached. If you delete an attachment on the server,
-that could lead to an out-of-date cache. It would probably make more
-sense in the future to concatenate a hash of the message id and a hash
-of the message.)
-
-Note that this shell script also pauses briefly after every message
-entries. This is currently necessary so that the emacs process-filter
-doesn't chop off messages. It's an obvious hack, and hopefully won't
-be necessary in the furture.
-
- #!/usr/bin/env bash
- SSH_BIN="/path/to/ssh/on/client"
- USER="user_name"
- SSH_HOST="server_name"
- NOTMUCH_REMOTE_BIN="/path/to/notmuch/on/server"
- CACHE="${HOME}/.notmuch-cache.d"
-
- hash_name ()
- {
- echo -n ${1} | sha1sum | awk '{print $1}'
- }
-
- check_for_file_name ()
- {
- [ -f "${CACHE}/${1}" ]
- }
-
- notmuch_run ()
- {
- [ -d "${CACHE}" ] || mkdir -p "${CACHE}"
- CMD=$1
- shift
- # we need to a little sanitizing of msg ids so the shell
- # doesn't mangle them
- ARGS=`echo $@ | sed 's/[\\$\\*\\!]/\\\&/g'`
- $SSH_BIN $USER@$SSH_HOST $NOTMUCH_REMOTE_BIN ${CMD} ${ARGS}
- }
-
- notmuch_search ()
- {
- #COUNTER=1
- notmuch_run search $@ |
- while read line; do
- sleep 0.02
- #[ $((COUNTER % 3)) == "0" ] && sleep 0.03
- echo "${line}"
- #COUNTER=$((COUNTER + 1))
- done
- }
-
-
- notmuch_show ()
- {
- if [ ${1} = "--format=raw" ]; then
- hashed=`hash_name ${2}`
- check_for_file_name ${hashed} ||
- notmuch_run show --format=raw ${2} > "${CACHE}/${hashed}"
- cat "${CACHE}/${hashed}"
- else
- notmuch_run show $@
- fi
- }
-
-
- if [ ${1} = "search" ]; then
- shift
- notmuch_search $@
- elif [ ${1} = "show" ]; then
- shift
- notmuch_show $@
- else
- notmuch_run $@
- fi
-
-
-Save this to a file, "remote-notmuch.sh", in your path.
-
-Now you can run "remote-notmuch.sh new". You can call the script
-anything you like. I actually have $HOME/bin/notmuch linked to that
-script, so I can transparent
-usage. (Since I run "new" from an emacs keybinding, I've never
-bothered with this renaming.)
-
-##Configure your emacs client##
-
-The only thing you need to do is tell your emacs client to use the
-script. Add the following to your .emacs (this is on your client
-machine):
+1. a working notmuch and `sshd` on one computer (let's call that
+computer "server").
- (setq notmuch-command "/path/to/your/remote-notmuch.sh")
+2. a working notmuch emacs interface (of the same version as on the
+server), `bash`, and `ssh` on another computer (let's call that computer
+"client")
+
+3. password-free login (public key authentication) from client to
+server. [Here](http://www.debian-administration.org/articles/152) is a
+good page on how to set it up (<del>3</del>).
+
+4. a reasonably fast connection. (This isn't really *necessary*, but if
+your connection is too slow, this won't be very pleasant to use, and
+certainly won't seem transparent.)
+
+(<del>3</del>) If you don't want / cannot use password-free login,
+[[This|remoteusage/124]] page provides yet another alternative.
+
+## Configure `ssh` on the client computer ##
+
+Add this to your `~/.ssh/config`:
+ Host notmuch
+ HostName example.com
+ User remoteuser
+ ControlMaster auto
+ ControlPath ~/.ssh/master-%h@%p:%r
+ ControlPersist 15m
+ IdentityFile ~/.ssh/example.com.id_rsa
-##A tip to speed things up##
-If you have openssh >= 0.4, you can make use of the "ControlMaster"
-feature. This allows you to reuse an existing connection. Therefore
-if you keep a connection open, you won't have to authenticate every
-time.
+Replace `example.com` with your server. Replace `remoteuser` with the
+username on the server.
-Add the following to your ~/.ssh/config file:
+The `Control*` options keep the connection open in the background to not
+require authentication every time. The `ControlPersist` option defines
+the connection timeout. These aren't strictly necessary, but reduce
+latency.
- Host server_name
- ControlMaster auto
- ControlPath ~/.ssh/master-%r@%h:%p
-
-You can also se the Host to "*", if you want to use it for all
-connections. I usually have an interactive ssh connection to my home
-computer open, so I don't need to do anything more. But if not, you
-can always run:
+The `IdentityFile` option may not be necessary depending on how you set
+up public key authentication. This assumes you set up a separate key;
+set the filename accordingly.
- ssh -Nf server_name
+Please refer to `ssh_config(5)` man page for details.
-which will open up a background connection, which you can then reuse
-for all of your notmuch commands.
+## Set up a wrapper shell script on the client computer ##
-##Problems##
-Some things won't work perfectly, and there might be some unexpected
-mismatches between normal usage and this sort of usage. If you're
-using this approach and run into any problems, please feel free to
-list them here. And, of course, if you improve on any of these
+Save this to a file, for example `remote-notmuch.sh`, in your `PATH`:
+
+ #!/bin/bash
+ printf -v ARGS "%q " "$@"
+ exec ssh notmuch notmuch ${ARGS}
+
+and give it execute permissions: `chmod +x remote-notmuch.sh`
+
+Now you can run `remote-notmuch.sh new`, or other notmuch commands. You
+can call the script anything you like. (You could also call it `notmuch`
+or symlink `~/bin/notmuch` to it for transparent usage.)
+
+## Configure Emacs on the client computer ##
+
+Add this to your `~/.emacs` to tell the Emacs client to use the wrapper
+script:
+
+ (setq notmuch-command "/path/to/your/remote-notmuch.sh")
+
+If you use Fcc and Notmuch older than 0.23, you may want to do something like
+this on the client, to Bcc mails to yourself:
+
+ (setq notmuch-fcc-dirs nil)
+ (add-hook 'message-header-setup-hook
+ (lambda () (insert (format "Bcc: %s <%s>\n"
+ (notmuch-user-name)
+ (notmuch-user-primary-email))))))
+
+Starting from 0.23, Fcc is also done through notmuch-command.
+
+## Additional Emacs remote-notmuch configuration ##
+
+To prevent you from having to maintain your GPG private keys on the remote
+server, you can add advice to `notmuch-show-view-raw-message` to enable epa
+inline decryption from notmuch raw message views.
+
+```elisp
+;; enable gpg decryption in raw view
+(defadvice notmuch-show-view-raw-message
+ (after notmuch-show-view-raw-message-after activate)
+ (epa-mail-mode))
+```
+
+When using remote-notmuch in an environment that brings the ssh tunnel up and
+down often (e.g. laptop suspends), it's helpful to have an Emacs process
+sentinel in place that will monitor the process state of your remote-notmuch
+ssh session.
+
+```elisp
+(defvar my/ssh-tunnel-notmuch-proc nil)
+
+(defun my/ssh-tunnel-notmuch ()
+ "Start and monitor ssh session for remote-notmuch."
+ (my/ssh-tunnel-with-proc
+ (proc "~/.ssh/config" "notmuch")
+ (set-process-sentinel
+ proc
+ #'(lambda (proc string)
+ (when (buffer-live-p (process-buffer proc))
+ (kill-buffer (process-buffer proc)))
+ (when (yes-or-no-p "Restart notmuch control master? ")
+ (setq my/ssh-tunnel-notmuch-proc (my/ssh-tunnel-notmuch)))))
+ proc))
+
+(defadvice notmuch
+ (before notmuch-before activate)
+ (unless (process-live-p my/ssh-tunnel-notmuch-proc)
+ (message "Starting notmuch control master")
+ (setq my/ssh-tunnel-notmuch-proc (my/ssh-tunnel-notmuch))))
+
+;;; here be dragons
+
+(require 'cl-lib)
+(require 'tramp)
+
+(cl-defmacro my/ssh-tunnel-with-proc ((proc ssh-tunnel-config-path ssh-tunnel-config-name) &body body)
+ "Bind PROC with an ssh process for SSH-TUNNEL-CONFIG-NAME from SSH-TUNNEL-CONFIG-PATH for BODY.
+
+ Example of use:
+
+ (defun my/ssh-tunnel-start ()
+ \"returns active process or nil\"
+ (my/ssh-tunnel-with-proc (proc \"~/my-ssh-configs/someconfig.ssh\"
+ \"name_of_config\")
+ ;; BODY with process bound to proc
+ proc))
+ "
+ (let ((ssh-tunnel-process (gensym "ssh-tunnel-process")))
+
+ `(let ((,ssh-tunnel-process nil)
+ (ssh-tunnel-buffer-name (format "*%s*" ,ssh-tunnel-config-name))
+ (ssh-tunnel-config ,ssh-tunnel-config-name))
+ (if (not (process-live-p ,ssh-tunnel-process))
+ (let ((process (start-process
+ ,ssh-tunnel-config-name
+ (generate-new-buffer ssh-tunnel-buffer-name)
+ "ssh"
+ "-C"
+ "-N"
+ "-F"
+ (format "%s" (expand-file-name ,ssh-tunnel-config-path))
+ ,ssh-tunnel-config-name)))
+ (if (process-live-p process)
+ (progn
+ (setq ,ssh-tunnel-process process)
+ (set-process-filter
+ process
+ #'(lambda (proc string)
+ (when (and (process-live-p proc)
+ (buffer-live-p (process-buffer proc)))
+ (if (string-match-p tramp-password-prompt-regexp string)
+ (process-send-string proc (concat (read-passwd string) "\n"))
+ (princ (format "%s" string)
+ (process-buffer proc))))))
+ (set-process-sentinel
+ process
+ #'(lambda (proc string)
+ (message "%s-sentinel: %s" ,ssh-tunnel-config-name string)))
+ (message "Started ssh config: %s" ,ssh-tunnel-config-name))
+ ;; else
+ (message "Could not start ssh config: %s" ,ssh-tunnel-config-name)))
+ (message "%s already running" ,ssh-tunnel-config-name))
+ ;; BODY
+ (let ((,proc ,ssh-tunnel-process))
+ ,@body)
+ )))
+```
+
+## Problems ##
+
+Some things probably won't work perfectly, and there might be some
+unexpected mismatches between normal usage and this sort of usage. If
+you're using this approach and run into any problems, please feel free
+to list them here. And, of course, if you improve on any of these
approaches, please do edit this page and let people know!
+
+If you have issues, you may want to try the
+[[old remote usage instructions|remoteusage/old]] or
+[[yet another alternative|remoteusage/124]].
projects / notmuch-wiki / blobdiff