git.notmuchmail.org Git - notmuch-wiki/blob - remoteusage.mdwn

   1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
   2 # Using notmuch remotely #
   3
   4 ## Why? ##
   5
   6 It is hard to keep notmuch tags in sync across multiple instances of
   7 notmuch, on multiple computers. Though you can do this with "notmuch
   8 dump" and "notmuch restore", it is often preferable to be able to use
   9 notmuch on a remote computer as if it were present on a local computer.
  10
  11 The following guidelines show how to accomplished this. It isn't
  12 perfect, but it works pretty well, and allows one to access notmuch on
  13 one computer, using only an Emacs client, a trivial shell script, and
  14 some Emacs and ssh settings on another computer.
  15
  16 ## What you will need ##
  17
  18 You will need to have the following items in place:
  19
  20 1. a working notmuch and `sshd` on one computer (let's call that
  21 computer "server").
  22
  23 2. a working notmuch emacs interface (of the same version as on the
  24 server), `bash`, and `ssh` on another computer (let's call that computer
  25 "client")
  26
  27 3. password-free login (public key authentication) from client to
  28 server. [Here](http://www.debian-administration.org/articles/152) is a
  29 good page on how to set it up (<del>3</del>).
  30
  31 4. a reasonably fast connection. (This isn't really *necessary*, but if
  32 your connection is too slow, this won't be very pleasant to use, and
  33 certainly won't seem transparent.)
  34
  35 (<del>3</del>) If you don't want / cannot use password-free login,
  36 [[This|remoteusage/124]] page provides yet another alternative.
  37
  38 ## Configure `ssh` on the client computer ##
  39
  40 Add this to your `~/.ssh/config`:
  41
  42     Host notmuch
  43         HostName example.com
  44         User remoteuser
  45         ControlMaster auto
  46         ControlPath ~/.ssh/master-%h@%p:%r
  47         ControlPersist 15m
  48         IdentityFile ~/.ssh/example.com.id_rsa
  49
  50 Replace `example.com` with your server. Replace `remoteuser` with the
  51 username on the server.
  52
  53 The `Control*` options keep the connection open in the background to not
  54 require authentication every time. The `ControlPersist` option defines
  55 the connection timeout. These aren't strictly necessary, but reduce
  56 latency.
  57
  58 The `IdentityFile` option may not be necessary depending on how you set
  59 up public key authentication. This assumes you set up a separate key;
  60 set the filename accordingly.
  61
  62 Please refer to `ssh_config(5)` man page for details.
  63
  64 ## Set up a wrapper shell script on the client computer ##
  65
  66 Save this to a file, for example `remote-notmuch.sh`, in your `PATH`:
  67
  68     #!/bin/bash
  69     printf -v ARGS "%q " "$@"
  70     exec ssh notmuch notmuch ${ARGS}
  71
  72 and give it execute permissions: `chmod +x remote-notmuch.sh`
  73
  74 Now you can run `remote-notmuch.sh new`, or other notmuch commands. You
  75 can call the script anything you like. (You could also call it `notmuch`
  76 or symlink `~/bin/notmuch` to it for transparent usage.)
  77
  78 ## Configure Emacs on the client computer ##
  79
  80 Add this to your `~/.emacs` to tell the Emacs client to use the wrapper
  81 script:
  82
  83     (setq notmuch-command "/path/to/your/remote-notmuch.sh")
  84
  85 If you use Fcc and Notmuch older than 0.23, you may want to do something like
  86 this on the client, to Bcc mails to yourself:
  87
  88     (setq notmuch-fcc-dirs nil)
  89     (add-hook 'message-header-setup-hook
  90         (lambda () (insert (format "Bcc: %s <%s>\n"
  91                     (notmuch-user-name)
  92                     (notmuch-user-primary-email))))))
  93
  94 Starting from 0.23, Fcc is also done through notmuch-command.
  95
  96 ## Additional Emacs remote-notmuch configuration  ##
  97
  98 To prevent you from having to maintain your GPG private keys on the remote
  99 server, you can add advice to `notmuch-show-view-raw-message` to enable epa
 100 inline decryption from notmuch raw message views.
 101
 102 ```elisp
 103 ;; enable gpg decryption in raw view
 104 (defadvice notmuch-show-view-raw-message
 105     (after notmuch-show-view-raw-message-after activate)
 106   (epa-mail-mode))
 107 ```
 108
 109 When using remote-notmuch in an environment that brings the ssh tunnel up and
 110 down often (e.g. laptop suspends), it's helpful to have an Emacs process
 111 sentinel in place that will monitor the process state of your remote-notmuch
 112 ssh session.
 113
 114 ```elisp
 115 (defvar my/ssh-tunnel-notmuch-proc nil)
 116
 117 (defun my/ssh-tunnel-notmuch ()
 118   "Start and monitor ssh session for remote-notmuch."
 119   (my/ssh-tunnel-with-proc
 120    (proc "~/.ssh/config" "notmuch")
 121    (set-process-sentinel
 122     proc
 123     #'(lambda (proc string)
 124         (when (buffer-live-p (process-buffer proc))
 125           (kill-buffer (process-buffer proc)))
 126         (when (yes-or-no-p "Restart notmuch control master? ")
 127           (setq my/ssh-tunnel-notmuch-proc (my/ssh-tunnel-notmuch)))))
 128    proc))
 129
 130 (defadvice notmuch
 131     (before notmuch-before activate)
 132   (unless (process-live-p my/ssh-tunnel-notmuch-proc)
 133     (message "Starting notmuch control master")
 134     (setq my/ssh-tunnel-notmuch-proc (my/ssh-tunnel-notmuch))))
 135
 136 ;;; here be dragons
 137
 138 (require 'cl-lib)
 139 (require 'tramp)
 140
 141 (cl-defmacro my/ssh-tunnel-with-proc ((proc ssh-tunnel-config-path ssh-tunnel-config-name) &body body)
 142   "Bind PROC with an ssh process for SSH-TUNNEL-CONFIG-NAME from SSH-TUNNEL-CONFIG-PATH for BODY.
 143
 144   Example of use:
 145
 146   (defun my/ssh-tunnel-start ()
 147     \"returns active process or nil\"
 148     (my/ssh-tunnel-with-proc (proc \"~/my-ssh-configs/someconfig.ssh\"
 149                                    \"name_of_config\")
 150                              ;; BODY with process bound to proc
 151                              proc))
 152   "
 153   (let ((ssh-tunnel-process (gensym "ssh-tunnel-process")))
 154
 155     `(let ((,ssh-tunnel-process nil)
 156            (ssh-tunnel-buffer-name (format "*%s*" ,ssh-tunnel-config-name))
 157            (ssh-tunnel-config ,ssh-tunnel-config-name))
 158        (if (not (process-live-p ,ssh-tunnel-process))
 159            (let ((process (start-process
 160                            ,ssh-tunnel-config-name
 161                            (generate-new-buffer ssh-tunnel-buffer-name)
 162                            "ssh"
 163                            "-C"
 164                            "-N"
 165                            "-F"
 166                            (format "%s" (expand-file-name ,ssh-tunnel-config-path))
 167                            ,ssh-tunnel-config-name)))
 168              (if (process-live-p process)
 169                  (progn
 170                    (setq ,ssh-tunnel-process process)
 171                    (set-process-filter
 172                     process
 173                     #'(lambda (proc string)
 174                         (when (and (process-live-p proc)
 175                                    (buffer-live-p (process-buffer proc)))
 176                           (if (string-match-p tramp-password-prompt-regexp string)
 177                               (process-send-string proc (concat (read-passwd string) "\n"))
 178                             (princ (format "%s" string)
 179                                    (process-buffer proc))))))
 180                    (set-process-sentinel
 181                     process
 182                     #'(lambda (proc string)
 183                         (message "%s-sentinel: %s" ,ssh-tunnel-config-name string)))
 184                    (message "Started ssh config: %s" ,ssh-tunnel-config-name))
 185                ;; else
 186                (message "Could not start ssh config: %s" ,ssh-tunnel-config-name)))
 187          (message "%s already running" ,ssh-tunnel-config-name))
 188        ;; BODY
 189        (let ((,proc ,ssh-tunnel-process))
 190          ,@body)
 191        )))
 192 ```
 193
 194 ## Problems ##
 195
 196 Some things probably won't work perfectly, and there might be some
 197 unexpected mismatches between normal usage and this sort of usage. If
 198 you're using this approach and run into any problems, please feel free
 199 to list them here. And, of course, if you improve on any of these
 200 approaches, please do edit this page and let people know!
 201
 202 If you have issues, you may want to try the
 203 [[old remote usage instructions|remoteusage/old]] or
 204 [[yet another alternative|remoteusage/124]].