Add 2011 to FSF/AIST copyright years.
[emacs.git] / doc / misc / tramp.texi
blob7c59c9f1e05dbbd8419c2844e1afbb010f072f8e
1 \input texinfo   @c -*-texinfo-*-
2 @setfilename ../../info/tramp
3 @c %**start of header
4 @settitle TRAMP User Manual
5 @c %**end of header
7 @c This is *so* much nicer :)
8 @footnotestyle end
10 @c In the Tramp CVS, the version number is auto-frobbed from
11 @c configure.ac, so you should edit that file and run
12 @c "autoconf && ./configure" to change the version number.
14 @c Additionally, flags are set with respect to the Emacs flavor; and
15 @c depending whether Tramp is packaged into (X)Emacs, or standalone.
17 @include trampver.texi
19 @c Macro for formatting a filename according to the repective syntax.
20 @c xxx and yyy are auxiliary macros in order to omit leading and
21 @c trailing whitespace.  Not very elegant, but I don't know it better.
23 @macro xxx {one}@c
24 @set \one\@c
25 @end macro
27 @macro yyy {one, two}@c
28 @xxx{x\one\}@c
29 @ifclear x@c
30 \one\@w{}\two\@c
31 @end ifclear
32 @clear x\one\@c
33 @end macro
35 @macro trampfn {method, user, host, localname}@c
36 @value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
37 @end macro
39 @copying
40 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
41 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
43 @quotation
44 Permission is granted to copy, distribute and/or modify this document
45 under the terms of the GNU Free Documentation License, Version 1.3 or
46 any later version published by the Free Software Foundation; with no
47 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
48 and with the Back-Cover Texts as in (a) below.  A copy of the license
49 is included in the section entitled ``GNU Free Documentation License''.
51 (a) The FSF's Back-Cover Text is: ``You have the freedom to
52 copy and modify this GNU manual.  Buying copies from the FSF
53 supports it in developing GNU and promoting software freedom.''
54 @end quotation
55 @end copying
57 @c Entries for @command{install-info} to use
58 @dircategory @value{emacsname}
59 @direntry
60 * TRAMP: (tramp).               Transparent Remote Access, Multiple Protocol
61                                 @value{emacsname} remote file access via rsh and rcp.
62 @end direntry
64 @titlepage
65 @title @value{tramp} version @value{trampver} User Manual
66 @author by Daniel Pittman
67 @author based on documentation by Kai Gro@ss{}johann
68 @page
69 @insertcopying
70 @end titlepage
72 @contents
74 @ifnottex
75 @node Top, Overview, (dir), (dir)
76 @top @value{tramp} version @value{trampver} User Manual
78 This file documents @value{tramp} version @value{trampver}, a remote file
79 editing package for @value{emacsname}.
81 @value{tramp} stands for `Transparent Remote (file) Access, Multiple
82 Protocol'.  This package provides remote file editing, similar to
83 @value{ftppackagename}.
85 The difference is that @value{ftppackagename} uses FTP to transfer
86 files between the local and the remote host, whereas @value{tramp} uses a
87 combination of @command{rsh} and @command{rcp} or other work-alike
88 programs, such as @command{ssh}/@command{scp}.
90 You can find the latest version of this document on the web at
91 @uref{http://www.gnu.org/software/tramp/}.
93 @c Pointer to the other Emacs flavor is necessary only in case of
94 @c standalone installation.
95 @ifset installchapter
96 The manual has been generated for @value{emacsname}.
97 @ifinfo
98 If you want to read the info pages for @value{emacsothername}, you
99 should read in @ref{Installation} how to create them.
100 @end ifinfo
101 @ifhtml
102 If you're using the other Emacs flavor, you should read the
103 @uref{@value{emacsotherfilename}, @value{emacsothername}} pages.
104 @end ifhtml
105 @end ifset
107 @ifhtml
108 @ifset jamanual
109 This manual is also available as a @uref{@value{japanesemanual},
110 Japanese translation}.
111 @end ifset
113 The latest release of @value{tramp} is available for
114 @uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
115 @ref{Obtaining Tramp} for more details, including the CVS server
116 details.
118 @value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/,
119 Savannah Project Page}.
120 @end ifhtml
122 There is a mailing list for @value{tramp}, available at
123 @email{tramp-devel@@gnu.org}, and archived at
124 @uref{http://lists.gnu.org/archive/html/tramp-devel/, the
125 @value{tramp} Mail Archive}.
126 @ifhtml
127 Older archives are located at
128 @uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel,
129 SourceForge Mail Archive} and
130 @uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/,
131 The Mail Archive}.
132 @c in HTML output, there's no new paragraph.
133 @*@*
134 @end ifhtml
136 @insertcopying
138 @end ifnottex
140 @menu
141 * Overview::                    What @value{tramp} can and cannot do.
143 For the end user:
145 * Obtaining Tramp::             How to obtain @value{tramp}.
146 * History::                     History of @value{tramp}.
147 @ifset installchapter
148 * Installation::                Installing @value{tramp} with your @value{emacsname}.
149 @end ifset
150 * Configuration::               Configuring @value{tramp} for use.
151 * Usage::                       An overview of the operation of @value{tramp}.
152 * Bug Reports::                 Reporting Bugs and Problems.
153 * Frequently Asked Questions::  Questions and answers from the mailing list.
154 * Function Index::              @value{tramp} functions.
155 * Variable Index::              User options and variables.
156 * Concept Index::               An item for each concept.
158 For the developer:
160 * Files directories and localnames::  How file names, directories and localnames are mangled and managed.
161 * Traces and Profiles::         How to Customize Traces.
162 * Issues::                      Debatable Issues and What Was Decided.
164 * GNU Free Documentation License:: The license for this documentation.
166 @detailmenu
167  --- The Detailed Node Listing ---
169 @ifset installchapter
170 Installing @value{tramp} with your @value{emacsname}
172 * Installation parameters::     Parameters in order to control installation.
173 * Load paths::                  How to plug-in @value{tramp} into your environment.
174 * Japanese manual::             Japanese manual.
176 @end ifset
178 Configuring @value{tramp} for use
180 * Connection types::            Types of connections made to remote machines.
181 * Inline methods::              Inline methods.
182 * External methods::            External methods.
183 @ifset emacsgvfs
184 * GVFS based methods::          GVFS based external methods.
185 @end ifset
186 @ifset emacsgw
187 * Gateway methods::             Gateway methods.
188 @end ifset
189 * Default Method::              Selecting a default method.
190 * Default User::                Selecting a default user.
191 * Default Host::                Selecting a default host.
192 * Multi-hops::                  Connecting to a remote host using multiple hops.
193 * Customizing Methods::         Using Non-Standard Methods.
194 * Customizing Completion::      Selecting config files for user/host name completion.
195 * Password handling::           Reusing passwords for several connections.
196 * Connection caching::          Reusing connection related information.
197 * Remote Programs::             How @value{tramp} finds and uses programs on the remote machine.
198 * Remote shell setup::          Remote shell setup hints.
199 * Windows setup hints::         Issues with Cygwin ssh.
200 * Auto-save and Backup::        Auto-save and Backup.
202 Using @value{tramp}
204 * Filename Syntax::             @value{tramp} filename conventions.
205 * Alternative Syntax::          URL-like filename syntax.
206 * Filename completion::         Filename completion.
207 * Remote processes::            Integration with other @value{emacsname} packages.
208 * Cleanup remote connections::  Cleanup remote connections.
210 How file names, directories and localnames are mangled and managed
212 * Localname deconstruction::    Breaking a localname into its components.
213 @ifset emacs
214 * External packages::           Integration with external Lisp packages.
215 @end ifset
217 @end detailmenu
218 @end menu
220 @node Overview
221 @chapter An overview of @value{tramp}
222 @cindex overview
224 After the installation of @value{tramp} into your @value{emacsname}, you
225 will be able to access files on remote machines as though they were
226 local.  Access to the remote file system for editing files, version
227 control, and @code{dired} are transparently enabled.
229 Your access to the remote machine can be with the @command{rsh},
230 @command{rlogin}, @command{telnet} programs or with any similar
231 connection method.  This connection must pass @acronym{ASCII}
232 successfully to be usable but need not be 8-bit clean.
234 The package provides support for @command{ssh} connections out of the
235 box, one of the more common uses of the package.  This allows
236 relatively secure access to machines, especially if @command{ftp}
237 access is disabled.
239 Under Windows, @value{tramp} is integrated with the PuTTY package,
240 using the @command{plink} program.
242 The majority of activity carried out by @value{tramp} requires only that
243 the remote login is possible and is carried out at the terminal.  In
244 order to access remote files @value{tramp} needs to transfer their content
245 to the local machine temporarily.
247 @value{tramp} can transfer files between the machines in a variety of ways.
248 The details are easy to select, depending on your needs and the
249 machines in question.
251 The fastest transfer methods for large files rely on a remote file
252 transfer package such as @command{rcp}, @command{scp}, @command{rsync}
253 or (under Windows) @command{pscp}.
255 If the remote copy methods are not suitable for you, @value{tramp} also
256 supports the use of encoded transfers directly through the shell.
257 This requires that the @command{mimencode} or @command{uuencode} tools
258 are available on the remote machine.  These methods are generally
259 faster for small files.
261 @value{tramp} is still under active development and any problems you encounter,
262 trivial or major, should be reported to the @value{tramp} developers.
263 @xref{Bug Reports}.
266 @subsubheading Behind the scenes
267 @cindex behind the scenes
268 @cindex details of operation
269 @cindex how it works
271 This section tries to explain what goes on behind the scenes when you
272 access a remote file through @value{tramp}.
274 Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name,
275 then hit @kbd{@key{TAB}} for completion.  Suppose further that this is
276 the first time that @value{tramp} is invoked for the host in question.  Here's
277 what happens:
279 @itemize
280 @item
281 @value{tramp} discovers that it needs a connection to the host.  So it
282 invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
283 @var{user}} or a similar tool to connect to the remote host.
284 Communication with this process happens through an
285 @value{emacsname} buffer, that is, the output from the remote end
286 goes into a buffer.
288 @item
289 The remote host may prompt for a login name (for @command{telnet}).
290 The login name is given in the file name, so @value{tramp} sends the
291 login name and a newline.
293 @item
294 The remote host may prompt for a password or pass phrase (for
295 @command{rsh} or for @command{telnet} after sending the login name).
296 @value{tramp} displays the prompt in the minibuffer, asking you for the
297 password or pass phrase.
299 You enter the password or pass phrase.  @value{tramp} sends it to the remote
300 host, followed by a newline.
302 @item
303 @value{tramp} now waits for the shell prompt or for a message that the login
304 failed.
306 If @value{tramp} sees neither of them after a certain period of time
307 (a minute, say), then it issues an error message saying that it
308 couldn't find the remote shell prompt and shows you what the remote
309 host has sent.
311 If @value{tramp} sees a @samp{login failed} message, it tells you so,
312 aborts the login attempt and allows you to try again.
314 @item
315 Suppose that the login was successful and @value{tramp} sees the shell prompt
316 from the remote host.  Now @value{tramp} invokes @command{/bin/sh} because
317 Bourne shells and C shells have different command
318 syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login
319 shell doesn't recognize @samp{exec /bin/sh} as a valid command.
320 Maybe you use the Scheme shell @command{scsh}@dots{}}
322 After the Bourne shell has come up, @value{tramp} sends a few commands to
323 ensure a good working environment.  It turns off echoing, it sets the
324 shell prompt, and a few other things.
326 @item
327 Now the remote shell is up and it good working order.  Remember, what
328 was supposed to happen is that @value{tramp} tries to find out what files exist
329 on the remote host so that it can do filename completion.
331 So, @value{tramp} basically issues @command{cd} and @command{ls} commands and
332 also sometimes @command{echo} with globbing.  Another command that is
333 often used is @command{test} to find out whether a file is writable or a
334 directory or the like.  The output of each command is parsed for the
335 necessary operation.
337 @item
338 Suppose you are finished with filename completion, have entered @kbd{C-x
339 C-f}, a full file name and hit @kbd{@key{RET}}.  Now comes the time to
340 transfer the file contents from the remote host to the local host so
341 that you can edit them.
343 See above for an explanation of how @value{tramp} transfers the file contents.
345 For inline transfers, @value{tramp} issues a command like @samp{mimencode -b
346 /path/to/remote/file}, waits until the output has accumulated in the
347 buffer that's used for communication, then decodes that output to
348 produce the file contents.
350 For external transfers, @value{tramp} issues a command like the
351 following:
352 @example
353 rcp user@@host:/path/to/remote/file /tmp/tramp.4711
354 @end example
355 It then reads the local temporary file @file{/tmp/tramp.4711} into a
356 buffer and deletes the temporary file.
358 @item
359 You now edit the buffer contents, blithely unaware of what has happened
360 behind the scenes.  (Unless you have read this section, that is.)  When
361 you are finished, you type @kbd{C-x C-s} to save the buffer.
363 @item
364 Again, @value{tramp} transfers the file contents to the remote host
365 either inline or external.  This is the reverse of what happens when
366 reading the file.
367 @end itemize
369 I hope this has provided you with a basic overview of what happens
370 behind the scenes when you open a file with @value{tramp}.
373 @c For the end user
374 @node Obtaining Tramp
375 @chapter Obtaining Tramp.
376 @cindex obtaining Tramp
378 @value{tramp} is freely available on the Internet and the latest
379 release may be downloaded from
380 @uref{ftp://ftp.gnu.org/gnu/tramp/}.  This release includes the full
381 documentation and code for @value{tramp}, suitable for installation.
382 But GNU Emacs (22 or later) includes @value{tramp} already, and there
383 is a @value{tramp} package for XEmacs, as well.  So maybe it is easier
384 to just use those.  But if you want the bleeding edge, read
385 on@dots{...}
387 For the especially brave, @value{tramp} is available from CVS.  The CVS
388 version is the latest version of the code and may contain incomplete
389 features or new issues.  Use these versions at your own risk.
391 Instructions for obtaining the latest development version of @value{tramp}
392 from CVS can be found by going to the Savannah project page at the
393 following URL and then clicking on the CVS link in the navigation bar
394 at the top.
396 @noindent
397 @uref{http://savannah.gnu.org/projects/tramp/}
399 @noindent
400 Or follow the example session below:
402 @example
403 ] @strong{cd ~/@value{emacsdir}}
404 ] @strong{export CVS_RSH="ssh"}
405 ] @strong{cvs -z3 -d:pserver:anonymous@@cvs.savannah.gnu.org:/sources/tramp co tramp}
406 @end example
408 @noindent
409 You should now have a directory @file{~/@value{emacsdir}/tramp}
410 containing the latest version of @value{tramp}.  You can fetch the latest
411 updates from the repository by issuing the command:
413 @example
414 ] @strong{cd ~/@value{emacsdir}/tramp}
415 ] @strong{export CVS_RSH="ssh"}
416 ] @strong{cvs update -d}
417 @end example
419 @noindent
420 Once you've got updated files from the CVS repository, you need to run
421 @command{autoconf} in order to get an up-to-date @file{configure}
422 script:
424 @example
425 ] @strong{cd ~/@value{emacsdir}/tramp}
426 ] @strong{autoconf}
427 @end example
430 @node History
431 @chapter History of @value{tramp}
432 @cindex history
433 @cindex development history
435 Development was started end of November 1998.  The package was called
436 @file{rssh.el}, back then.  It only provided one method to access a
437 file, using @command{ssh} to log in to a remote host and using
438 @command{scp} to transfer the file contents.  After a while, the name
439 was changed to @file{rcp.el}, and now it's @value{tramp}.  Along the way,
440 many more methods for getting a remote shell and for transferring the
441 file contents were added.  Support for VC was added.
443 After that, there were added the multi-hop methods in April 2000 and
444 the unification of @value{tramp} and Ange-FTP filenames in July 2002.
445 In July 2004, multi-hop methods have been replaced by proxy hosts.
446 Running commands on remote hosts was introduced in December 2005.
447 @ifset emacsgw
448 Support of gateways exists since April 2007.
449 @end ifset
450 @ifset emacsgvfs
451 GVFS integration started in February 2009.
452 @end ifset
453 @ifset emacsimap
454 Storing files into IMAP mailboxes has been added in September 2009.
455 @end ifset
457 In December 2001, @value{tramp} has been added to the XEmacs package
458 repository.  Being part of the GNU Emacs repository happened in June
459 2002, the first release including @value{tramp} was GNU Emacs 22.1.
461 @value{tramp} is also a GNU/Linux Debian package since February 2001.
464 @c Installation chapter is necessary only in case of standalone
465 @c installation.  Text taken from trampinst.texi.
466 @ifset installchapter
467 @include trampinst.texi
468 @end ifset
470 @node Configuration
471 @chapter Configuring @value{tramp} for use
472 @cindex configuration
474 @cindex default configuration
475 @value{tramp} is (normally) fully functional when it is initially
476 installed.  It is initially configured to use the @command{scp}
477 program to connect to the remote host.  So in the easiest case, you
478 just type @kbd{C-x C-f} and then enter the filename
479 @file{@trampfn{, user, machine, /path/to.file}}.
481 On some hosts, there are problems with opening a connection.  These are
482 related to the behavior of the remote shell.  See @xref{Remote shell
483 setup}, for details on this.
485 If you do not wish to use these commands to connect to the remote
486 host, you should change the default connection and transfer method
487 that @value{tramp} uses.  There are several different methods that @value{tramp}
488 can use to connect to remote machines and transfer files
489 (@pxref{Connection types}).
491 If you don't know which method is right for you, see @xref{Default
492 Method}.
495 @menu
496 * Connection types::            Types of connections made to remote machines.
497 * Inline methods::              Inline methods.
498 * External methods::            External methods.
499 @ifset emacsgvfs
500 * GVFS based methods::          GVFS based external methods.
501 @end ifset
502 @ifset emacsgw
503 * Gateway methods::             Gateway methods.
504 @end ifset
505 * Default Method::              Selecting a default method.
506                                   Here we also try to help those who
507                                   don't have the foggiest which method
508                                   is right for them.
509 * Default User::                Selecting a default user.
510 * Default Host::                Selecting a default host.
511 * Multi-hops::                  Connecting to a remote host using multiple hops.
512 * Customizing Methods::         Using Non-Standard Methods.
513 * Customizing Completion::      Selecting config files for user/host name completion.
514 * Password handling::           Reusing passwords for several connections.
515 * Connection caching::          Reusing connection related information.
516 * Remote Programs::             How @value{tramp} finds and uses programs on the remote machine.
517 * Remote shell setup::          Remote shell setup hints.
518 * Windows setup hints::         Issues with Cygwin ssh.
519 * Auto-save and Backup::        Auto-save and Backup.
520 @end menu
523 @node Connection types
524 @section Types of connections made to remote machines.
525 @cindex connection types, overview
527 There are two basic types of transfer methods, each with its own
528 advantages and limitations.  Both types of connection make use of a
529 remote shell access program such as @command{rsh}, @command{ssh} or
530 @command{telnet} to connect to the remote machine.
532 This connection is used to perform many of the operations that @value{tramp}
533 requires to make the remote file system transparently accessible from
534 the local machine.  It is only when visiting files that the methods
535 differ.
537 @cindex inline methods
538 @cindex external methods
539 @cindex methods, inline
540 @cindex methods, external
541 Loading or saving a remote file requires that the content of the file
542 be transfered between the two machines.  The content of the file can
543 be transfered using one of two methods: the @dfn{inline method} over
544 the same connection used to log in to the remote machine, or the
545 @dfn{external method} through another connection using a remote copy
546 program such as @command{rcp}, @command{scp} or @command{rsync}.
548 The performance of the external methods is generally better than that
549 of the inline methods, at least for large files.  This is caused by
550 the need to encode and decode the data when transferring inline.
552 The one exception to this rule are the @command{scp} based transfer
553 methods.  While these methods do see better performance when actually
554 transferring files, the overhead of the cryptographic negotiation at
555 startup may drown out the improvement in file transfer times.
557 External methods should be configured such a way that they don't
558 require a password (with @command{ssh-agent}, or such alike).  Modern
559 @command{scp} implementations offer options to reuse existing
560 @command{ssh} connections, see method @command{scpc}.  If it isn't
561 possible, you should consider @ref{Password handling}, otherwise you
562 will be prompted for a password every copy action.
565 @node Inline methods
566 @section Inline methods
567 @cindex inline methods
568 @cindex methods, inline
570 The inline methods in @value{tramp} are quite powerful and can work in
571 situations where you cannot use an external transfer program to connect.
572 Inline methods are the only methods that work when connecting to the
573 remote machine via telnet.  (There are also strange inline methods which
574 allow you to transfer files between @emph{user identities} rather than
575 hosts, see below.)
577 These methods depend on the existence of a suitable encoding and
578 decoding command on remote machine.  Locally, @value{tramp} may be able to
579 use features of @value{emacsname} to decode and encode the files or
580 it may require access to external commands to perform that task.
582 @cindex uuencode
583 @cindex mimencode
584 @cindex base-64 encoding
585 @value{tramp} checks the availability and usability of commands like
586 @command{mimencode} (part of the @command{metamail} package) or
587 @command{uuencode} on the remote host.  The first reliable command
588 will be used.  The search path can be customized, see @ref{Remote
589 Programs}.
591 If both commands aren't available on the remote host, @value{tramp}
592 transfers a small piece of Perl code to the remote host, and tries to
593 apply it for encoding and decoding.
595 The variable @var{tramp-inline-compress-start-size} controls, whether
596 a file shall be compressed before encoding.  This could increase
597 transfer speed for large text files.
600 @table @asis
601 @item @option{rsh}
602 @cindex method rsh
603 @cindex rsh method
605 Connect to the remote host with @command{rsh}.  Due to the unsecure
606 connection it is recommended for very local host topology only.
608 On operating systems which provide the command @command{remsh} instead
609 of @command{rsh}, you can use the method @option{remsh}.  This is true
610 for HP-UX or Cray UNICOS, for example.
613 @item @option{ssh}
614 @cindex method ssh
615 @cindex ssh method
617 Connect to the remote host with @command{ssh}.  This is identical to
618 the previous option except that the @command{ssh} package is used,
619 making the connection more secure.
621 There are also two variants, @option{ssh1} and @option{ssh2}, that
622 call @samp{ssh -1} and @samp{ssh -2}, respectively.  This way, you can
623 explicitly select whether you want to use the SSH protocol version 1
624 or 2 to connect to the remote host.  (You can also specify in
625 @file{~/.ssh/config}, the SSH configuration file, which protocol
626 should be used, and use the regular @option{ssh} method.)
628 Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
629 @command{ssh1} and @command{ssh2} commands explicitly.  If you don't
630 know what these are, you do not need these options.
632 All the methods based on @command{ssh} have an additional feature: you
633 can specify a host name which looks like @file{host#42} (the real host
634 name, then a hash sign, then a port number).  This means to connect to
635 the given host but to also pass @code{-p 42} as arguments to the
636 @command{ssh} command.
639 @item @option{telnet}
640 @cindex method telnet
641 @cindex telnet method
643 Connect to the remote host with @command{telnet}.  This is as unsecure
644 as the @option{rsh} method.
647 @item @option{su}
648 @cindex method su
649 @cindex su method
651 This method does not connect to a remote host at all, rather it uses
652 the @command{su} program to allow you to edit files as another user.
653 That means, the specified host name in the file name must be either
654 @samp{localhost} or the host name as returned by the function
655 @command{(system-name)}.  For an exception of this rule see
656 @ref{Multi-hops}.
659 @item @option{sudo}
660 @cindex method sudo
661 @cindex sudo method
663 This is similar to the @option{su} method, but it uses @command{sudo}
664 rather than @command{su} to become a different user.
666 Note that @command{sudo} must be configured to allow you to start a
667 shell as the user.  It would be nice if it was sufficient if
668 @command{ls} and @command{mimencode} were allowed, but that is not
669 easy to implement, so I haven't got around to it, yet.
672 @item @option{sshx}
673 @cindex method sshx
674 @cindex sshx method
676 As you would expect, this is similar to @option{ssh}, only a little
677 different.  Whereas @option{ssh} opens a normal interactive shell on
678 the remote host, this option uses @samp{ssh -t -t @var{host} -l
679 @var{user} /bin/sh} to open a connection.  This is useful for users
680 where the normal login shell is set up to ask them a number of
681 questions when logging in.  This procedure avoids these questions, and
682 just gives @value{tramp} a more-or-less `standard' login shell to work
683 with.
685 Note that this procedure does not eliminate questions asked by
686 @command{ssh} itself.  For example, @command{ssh} might ask ``Are you
687 sure you want to continue connecting?'' if the host key of the remote
688 host is not known.  @value{tramp} does not know how to deal with such a
689 question (yet), therefore you will need to make sure that you can log
690 in without such questions.
692 This is also useful for Windows users where @command{ssh}, when
693 invoked from an @value{emacsname} buffer, tells them that it is not
694 allocating a pseudo tty.  When this happens, the login shell is wont
695 to not print any shell prompt, which confuses @value{tramp} mightily.
697 This supports the @samp{-p} argument.
700 @item @option{krlogin}
701 @cindex method krlogin
702 @cindex krlogin method
703 @cindex Kerberos (with krlogin method)
705 This method is also similar to @option{ssh}.  It only uses the
706 @command{krlogin -x} command to log in to the remote host.
709 @item @option{plink}
710 @cindex method plink
711 @cindex plink method
713 This method is mostly interesting for Windows users using the PuTTY
714 implementation of SSH.  It uses @samp{plink -ssh} to log in to the
715 remote host.
717 This supports the @samp{-P} argument.
719 Additionally, the methods @option{plink1} and @option{plink2} are
720 provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in
721 order to use SSH protocol version 1 or 2 explicitly.
723 CCC: Do we have to connect to the remote host once from the command
724 line to accept the SSH key?  Maybe this can be made automatic?
726 CCC: Say something about the first shell command failing.  This might
727 be due to a wrong setting of @code{tramp-rsh-end-of-line}.
730 @item @option{plinkx}
731 @cindex method plinkx
732 @cindex plinkx method
734 Another method using PuTTY on Windows.  Instead of host names, it
735 expects PuTTY session names, calling @samp{plink -load @var{session}
736 -t"}.  User names are relevant only in case the corresponding session
737 hasn't defined a user name.  Different port numbers must be defined in
738 the session.
741 @item @option{fish}
742 @cindex method fish
743 @cindex fish method
745 This is an experimental implementation of the fish protocol, known from
746 the GNU Midnight Commander or the KDE Konqueror.  @value{tramp} expects
747 the fish server implementation from the KDE kioslave.  That means, the
748 file @file{~/.fishsrv.pl} is expected to reside on the remote host.
750 The implementation lacks good performance.  The code is offered anyway,
751 maybe somebody can improve the performance.
753 @end table
756 @node External methods
757 @section External methods
758 @cindex methods, external
759 @cindex external methods
761 The external methods operate through multiple channels, using the
762 remote shell connection for many actions while delegating file
763 transfers to an external transfer utility.
765 This saves the overhead of encoding and decoding that multiplexing the
766 transfer through the one connection has with the inline methods.
768 Since external methods need their own overhead opening a new channel,
769 all files which are smaller than @var{tramp-copy-size-limit} are still
770 transferred with the corresponding inline method.  It should provide a
771 fair trade-off between both approaches.
773 @table @asis
774 @item @option{rcp}  ---  @command{rsh} and @command{rcp}
775 @cindex method rcp
776 @cindex rcp method
777 @cindex rcp (with rcp method)
778 @cindex rsh (with rcp method)
780 This method uses the @command{rsh} and @command{rcp} commands to connect
781 to the remote machine and transfer files.  This is probably the fastest
782 connection method available.
784 The alternative method @option{remcp} uses the @command{remsh} and
785 @command{rcp} commands.  It should be applied on machines where
786 @command{remsh} is used instead of @command{rsh}.
789 @item @option{scp}  ---  @command{ssh} and @command{scp}
790 @cindex method scp
791 @cindex scp method
792 @cindex scp (with scp method)
793 @cindex ssh (with scp method)
795 Using @command{ssh} to connect to the remote host and @command{scp} to
796 transfer files between the machines is the best method for securely
797 connecting to a remote machine and accessing files.
799 The performance of this option is also quite good.  It may be slower than
800 the inline methods when you often open and close small files however.
801 The cost of the cryptographic handshake at the start of an @command{scp}
802 session can begin to absorb the advantage that the lack of encoding and
803 decoding presents.
805 There are also two variants, @option{scp1} and @option{scp2}, that
806 call @samp{ssh -1} and @samp{ssh -2}, respectively.  This way, you can
807 explicitly select whether you want to use the SSH protocol version 1
808 or 2 to connect to the remote host.  (You can also specify in
809 @file{~/.ssh/config}, the SSH configuration file, which protocol
810 should be used, and use the regular @option{scp} method.)
812 Two other variants, @option{scp1_old} and @option{scp2_old}, use the
813 @command{ssh1} and @command{ssh2} commands explicitly.  If you don't
814 know what these are, you do not need these options.
816 All the @command{ssh} based methods support the @samp{-p} feature
817 where you can specify a port number to connect to in the host name.
818 For example, the host name @file{host#42} tells @value{tramp} to
819 specify @samp{-p 42} in the argument list for @command{ssh}, and to
820 specify @samp{-P 42} in the argument list for @command{scp}.
823 @item @option{sftp}  ---  @command{ssh} and @command{sftp}
824 @cindex method sftp
825 @cindex sftp method
826 @cindex sftp (with sftp method)
827 @cindex ssh (with sftp method)
829 That is mostly the same method as @option{scp}, but using
830 @command{sftp} as transfer command.  So the same remarks are valid.
832 This command does not work like @value{ftppackagename}, where
833 @command{ftp} is called interactively, and all commands are send from
834 within this session.  Instead of, @command{ssh} is used for login.
836 This method supports the @samp{-p} argument.
839 @item @option{rsync}  ---  @command{ssh} and @command{rsync}
840 @cindex method rsync
841 @cindex rsync method
842 @cindex rsync (with rsync method)
843 @cindex ssh (with rsync method)
845 Using the @command{ssh} command to connect securely to the remote
846 machine and the @command{rsync} command to transfer files is almost
847 identical to the @option{scp} method.
849 While @command{rsync} performs much better than @command{scp} when
850 transferring files that exist on both hosts, this advantage is lost if
851 the file exists only on one side of the connection.  A file can exists
852 on both the remote and local host, when you copy a file from/to a
853 remote host.  When you just open a file from the remote host (or write
854 a file there), a temporary file on the local side is kept as long as
855 the corresponding buffer, visiting this file, is alive.
857 This method supports the @samp{-p} argument.
860 @item @option{scpx} --- @command{ssh} and @command{scp}
861 @cindex method scpx
862 @cindex scpx method
863 @cindex scp (with scpx method)
864 @cindex ssh (with scpx method)
866 As you would expect, this is similar to @option{scp}, only a little
867 different.  Whereas @option{scp} opens a normal interactive shell on
868 the remote host, this option uses @samp{ssh -t -t @var{host} -l
869 @var{user} /bin/sh} to open a connection.  This is useful for users
870 where the normal login shell is set up to ask them a number of
871 questions when logging in.  This procedure avoids these questions, and
872 just gives @value{tramp} a more-or-less `standard' login shell to work
873 with.
875 This is also useful for Windows users where @command{ssh}, when
876 invoked from an @value{emacsname} buffer, tells them that it is not
877 allocating a pseudo tty.  When this happens, the login shell is wont
878 to not print any shell prompt, which confuses @value{tramp} mightily.
880 This method supports the @samp{-p} argument.
883 @item @option{scpc} --- @command{ssh} and @command{scp}
884 @cindex method scpc
885 @cindex scpc method
886 @cindex scp (with scpc method)
887 @cindex ssh (with scpc method)
889 Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
890 @option{ControlMaster}.  This allows @option{scp} to reuse an existing
891 @option{ssh} channel, which increases performance.
893 Before you use this method, you shall check whether your @option{ssh}
894 implementation does support this option.  Try from the command line
896 @example
897 ssh localhost -o ControlMaster=yes
898 @end example
900 This method supports the @samp{-p} argument.
903 @item @option{rsyncc}  ---  @command{ssh} and @command{rsync}
904 @cindex method rsyncc
905 @cindex rsyncc method
906 @cindex rsync (with rsyncc method)
907 @cindex ssh (with rsyncc method)
909 Like the @option{scpc} method, @option{rsyncc} improves the underlying
910 @command{ssh} connection by the option @option{ControlMaster}.  This
911 allows @command{rsync} to reuse an existing @command{ssh} channel,
912 which increases performance.
914 This method supports the @samp{-p} argument.
917 @item @option{pscp} --- @command{plink} and @command{pscp}
918 @cindex method pscp
919 @cindex pscp method
920 @cindex pscp (with pscp method)
921 @cindex plink (with pscp method)
922 @cindex PuTTY (with pscp method)
924 This method is similar to @option{scp}, but it uses the
925 @command{plink} command to connect to the remote host, and it uses
926 @command{pscp} for transferring the files.  These programs are part
927 of PuTTY, an SSH implementation for Windows.
929 This method supports the @samp{-P} argument.
932 @item @option{psftp} --- @command{plink} and @command{psftp}
933 @cindex method psftp
934 @cindex psftp method
935 @cindex psftp (with psftp method)
936 @cindex plink (with psftp method)
937 @cindex PuTTY (with psftp method)
939 As you would expect, this method is similar to @option{sftp}, but it
940 uses the @command{plink} command to connect to the remote host, and it
941 uses @command{psftp} for transferring the files.  These programs are
942 part of PuTTY, an SSH implementation for Windows.
944 This method supports the @samp{-P} argument.
947 @item @option{fcp} --- @command{fsh} and @command{fcp}
948 @cindex method fcp
949 @cindex fcp method
950 @cindex fsh (with fcp method)
951 @cindex fcp (with fcp method)
953 This method is similar to @option{scp}, but it uses the @command{fsh}
954 command to connect to the remote host, and it uses @command{fcp} for
955 transferring the files.  @command{fsh/fcp} are a front-end for
956 @command{ssh} which allow for reusing the same @command{ssh} session
957 for submitting several commands.  This avoids the startup overhead of
958 @command{scp} (which has to establish a secure connection whenever it
959 is called).  Note, however, that you can also use one of the inline
960 methods to achieve a similar effect.
962 This method uses the command @samp{fsh @var{host} -l @var{user}
963 /bin/sh -i} to establish the connection, it does not work to just say
964 @command{fsh @var{host} -l @var{user}}.
966 @cindex method fsh
967 @cindex fsh method
969 There is no inline method using @command{fsh} as the multiplexing
970 provided by the program is not very useful in our context.  @value{tramp}
971 opens just one connection to the remote host and then keeps it open,
972 anyway.
975 @item @option{ftp}
976 @cindex method ftp
977 @cindex ftp method
979 This is not a native @value{tramp} method.  Instead of, it forwards all
980 requests to @value{ftppackagename}.
981 @ifset xemacs
982 This works only for unified filenames, see @ref{Issues}.
983 @end ifset
986 @item @option{smb} --- @command{smbclient}
987 @cindex method smb
988 @cindex smb method
990 This is another not natural @value{tramp} method.  It uses the
991 @command{smbclient} command on different Unices in order to connect to
992 an SMB server.  An SMB server might be a Samba (or CIFS) server on
993 another UNIX host or, more interesting, a host running MS Windows.  So
994 far, it is tested towards MS Windows NT, MS Windows 2000, and MS
995 Windows XP.
997 The first directory in the localname must be a share name on the remote
998 host.  Remember, that the @code{$} character in which default shares
999 usually end, must be written @code{$$} due to environment variable
1000 substitution in file names.  If no share name is given (i.e. remote
1001 directory @code{/}), all available shares are listed.
1003 Since authorization is done on share level, you will be prompted
1004 always for a password if you access another share on the same host.
1005 This can be suppressed by @ref{Password handling}.
1007 MS Windows uses for authorization both a user name and a domain name.
1008 Because of this, the @value{tramp} syntax has been extended: you can
1009 specify a user name which looks like @code{user%domain} (the real user
1010 name, then a percent sign, then the domain name).  So, to connect to
1011 the machine @code{melancholia} as user @code{daniel} of the domain
1012 @code{BIZARRE}, and edit @file{.emacs} in the home directory (share
1013 @code{daniel$}) I would specify the filename @file{@trampfn{smb,
1014 daniel%BIZARRE, melancholia, /daniel$$/.emacs}}.
1016 Depending on the Windows domain configuration, a Windows user might be
1017 considered as domain user per default.  In order to connect as local
1018 user, the WINS name of that machine must be given as domain name.
1019 Usually, it is the machine name in capital letters.  In the example
1020 above, the local user @code{daniel} would be specified as
1021 @file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}.
1023 The domain name as well as the user name are optional.  If no user
1024 name is specified at all, the anonymous user (without password
1025 prompting) is assumed.  This is different from all other @value{tramp}
1026 methods, where in such a case the local user name is taken.
1028 The @option{smb} method supports the @samp{-p} argument.
1030 @strong{Please note:} If @value{emacsname} runs locally under MS
1031 Windows, this method isn't available.  Instead of, you can use UNC
1032 file names like @file{//melancholia/daniel$$/.emacs}.  The only
1033 disadvantage is that there's no possibility to specify another user
1034 name.
1037 @ifset emacsimap
1038 @item @option{imap}
1039 @cindex method imap
1040 @cindex method imaps
1041 @cindex imap method
1042 @cindex imaps method
1044 Accessing an IMAP mailbox is intended to save files there as encrypted
1045 message.  It could be used in case there are no other remote file
1046 storages available.
1048 @value{tramp} supports both @option{imap} and @option{imaps} methods.
1049 The latter one accesses the IMAP server over ssl.
1051 Both methods support the port number specification.
1053 Note, that special handling is needed for declaring a passphrase for
1054 encryption / decryption of the messages (@pxref{Using an
1055 authentication file}).
1057 @end ifset
1058 @end table
1061 @ifset emacsgvfs
1062 @node GVFS based methods
1063 @section GVFS based external methods
1064 @cindex methods, gvfs
1065 @cindex gvfs based methods
1066 @cindex dbus
1068 The connection methods described in this section are based on GVFS
1069 @uref{http://en.wikipedia.org/wiki/GVFS}.  Via GVFS, the remote
1070 filesystem is mounted locally through FUSE.  @value{tramp} uses
1071 internally this local mounted directory.
1073 The communication with GVFS is implemented via D-Bus messages.
1074 Therefore, your @value{emacsname} must have D-Bus integration,
1075 @pxref{Top, , D-Bus, dbus}.
1077 @table @asis
1078 @item @option{dav}
1079 @cindex method dav
1080 @cindex method davs
1081 @cindex dav method
1082 @cindex davs method
1084 This method provides access to WebDAV files and directories.  There
1085 exists also the external method @option{davs}, which uses SSL
1086 encryption for the access.
1088 Both methods support the port number specification as discussed above.
1091 @item @option{obex}
1092 @cindex method obex
1093 @cindex obex method
1095 OBEX is an FTP-like access protocol for simple devices, like cell
1096 phones.  Until now @value{tramp} supports only OBEX over Bluetooth.
1099 @item @option{synce}
1100 @cindex method synce
1101 @cindex synce method
1103 The @option{synce} method allows communication with Windows Mobile
1104 devices.  Beside GVFS for mounting remote files and directories via
1105 FUSE, it needs also the SYNCE-GVFS plugin.
1106 @end table
1108 @defopt tramp-gvfs-methods
1109 This customer option, a list, defines the external methods, which
1110 shall be used with GVFS.  Per default, these are @option{dav},
1111 @option{davs}, @option{obex} and @option{synce}.  Other possible
1112 values are @option{ftp}, @option{sftp} and @option{smb}.
1113 @end defopt
1114 @end ifset
1117 @ifset emacsgw
1118 @node Gateway methods
1119 @section Gateway methods
1120 @cindex methods, gateway
1121 @cindex gateway methods
1123 Gateway methods are not methods to access a remote host directly.
1124 These methods are intended to pass firewalls or proxy servers.
1125 Therefore, they can be used for proxy host declarations
1126 (@pxref{Multi-hops}) only.
1128 A gateway method must come always along with a method who supports
1129 port setting.  This is because @value{tramp} targets the accompanied
1130 method to @file{localhost#random_port}, from where the firewall or
1131 proxy server is accessed to.
1133 Gateway methods support user name and password declarations.  These
1134 are used to authenticate towards the corresponding firewall or proxy
1135 server.  They can be passed only if your friendly administrator has
1136 granted your access.
1138 @table @asis
1139 @item @option{tunnel}
1140 @cindex method tunnel
1141 @cindex tunnel method
1143 This method implements an HTTP tunnel via the @command{CONNECT}
1144 command (see RFC 2616, 2817).  Any HTTP 1.1 compliant (proxy) server
1145 shall support this command.
1147 As authentication method, only @option{Basic Authentication} (see RFC
1148 2617) is implemented so far.  If no port number is given in the
1149 declaration, port @option{8080} is used for the proxy server.
1152 @item @option{socks}
1153 @cindex method socks
1154 @cindex socks method
1156 The @command{socks} method provides access to SOCKSv5 servers (see
1157 RFC 1928).  @option{Username/Password Authentication} according to RFC
1158 1929 is supported.
1160 The default port number of the socks server is @option{1080}, if not
1161 specified otherwise.
1163 @end table
1164 @end ifset
1167 @node Default Method
1168 @section Selecting a default method
1169 @cindex default method
1171 @vindex tramp-default-method
1172 When you select an appropriate transfer method for your typical usage
1173 you should set the variable @code{tramp-default-method} to reflect that
1174 choice.  This variable controls which method will be used when a method
1175 is not specified in the @value{tramp} file name.  For example:
1177 @lisp
1178 (setq tramp-default-method "ssh")
1179 @end lisp
1181 @vindex tramp-default-method-alist
1182 You can also specify different methods for certain user/host
1183 combinations, via the variable @code{tramp-default-method-alist}.  For
1184 example, the following two lines specify to use the @option{ssh}
1185 method for all user names matching @samp{john} and the @option{rsync}
1186 method for all host names matching @samp{lily}.  The third line
1187 specifies to use the @option{su} method for the user @samp{root} on
1188 the machine @samp{localhost}.
1190 @lisp
1191 (add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
1192 (add-to-list 'tramp-default-method-alist '("lily" "" "rsync"))
1193 (add-to-list 'tramp-default-method-alist
1194              '("\\`localhost\\'" "\\`root\\'" "su"))
1195 @end lisp
1197 @noindent
1198 See the documentation for the variable
1199 @code{tramp-default-method-alist} for more details.
1201 External methods are normally preferable to inline methods, giving
1202 better performance.
1204 @xref{Inline methods}.
1205 @xref{External methods}.
1207 Another consideration with the selection of transfer methods is the
1208 environment you will use them in and, especially when used over the
1209 Internet, the security implications of your preferred method.
1211 The @option{rsh} and @option{telnet} methods send your password as
1212 plain text as you log in to the remote machine, as well as
1213 transferring the files in such a way that the content can easily be
1214 read from other machines.
1216 If you need to connect to remote systems that are accessible from the
1217 Internet, you should give serious thought to using @option{ssh} based
1218 methods to connect.  These provide a much higher level of security,
1219 making it a non-trivial exercise for someone to obtain your password
1220 or read the content of the files you are editing.
1223 @subsection Which method is the right one for me?
1224 @cindex choosing the right method
1226 Given all of the above, you are probably thinking that this is all fine
1227 and good, but it's not helping you to choose a method!  Right you are.
1228 As a developer, we don't want to boss our users around but give them
1229 maximum freedom instead.  However, the reality is that some users would
1230 like to have some guidance, so here I'll try to give you this guidance
1231 without bossing you around.  You tell me whether it works @dots{}
1233 My suggestion is to use an inline method.  For large files, external
1234 methods might be more efficient, but I guess that most people will
1235 want to edit mostly small files.  And if you access large text files,
1236 compression (driven by @var{tramp-inline-compress-start-size}) shall
1237 still result in good performance.
1239 I guess that these days, most people can access a remote machine by
1240 using @command{ssh}.  So I suggest that you use the @option{ssh}
1241 method.  So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost,
1242 /etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other
1243 host.
1245 If you can't use @option{ssh} to log in to the remote host, then
1246 select a method that uses a program that works.  For instance, Windows
1247 users might like the @option{plink} method which uses the PuTTY
1248 implementation of @command{ssh}.  Or you use Kerberos and thus like
1249 @option{krlogin}.
1251 For the special case of editing files on the local host as another
1252 user, see the @option{su} or @option{sudo} methods.  They offer
1253 shortened syntax for the @samp{root} account, like
1254 @file{@trampfn{su, , , /etc/motd}}.
1256 People who edit large files may want to consider @option{scpc} instead
1257 of @option{ssh}, or @option{pscp} instead of @option{plink}.  These
1258 external methods are faster than inline methods for large files.
1259 Note, however, that external methods suffer from some limitations.
1260 Please try first whether you really get a noticeable speed advantage
1261 from using an external method!  Maybe even for large files, inline
1262 methods are fast enough.
1265 @node Default User
1266 @section Selecting a default user
1267 @cindex default user
1269 The user part of a @value{tramp} file name can be omitted.  Usually,
1270 it is replaced by the user name you are logged in.  Often, this is not
1271 what you want.  A typical use of @value{tramp} might be to edit some
1272 files with root permissions on the local host.  This case, you should
1273 set the variable @code{tramp-default-user} to reflect that choice.
1274 For example:
1276 @lisp
1277 (setq tramp-default-user "root")
1278 @end lisp
1280 @code{tramp-default-user} is regarded as obsolete, and will be removed
1281 soon.
1283 @vindex tramp-default-user-alist
1284 You can also specify different users for certain method/host
1285 combinations, via the variable @code{tramp-default-user-alist}.  For
1286 example, if you always have to use the user @samp{john} in the domain
1287 @samp{somewhere.else}, you can specify the following:
1289 @lisp
1290 (add-to-list 'tramp-default-user-alist
1291              '("ssh" ".*\\.somewhere\\.else\\'" "john"))
1292 @end lisp
1294 @noindent
1295 See the documentation for the variable
1296 @code{tramp-default-user-alist} for more details.
1298 One trap to fall in must be known.  If @value{tramp} finds a default
1299 user, this user will be passed always to the connection command as
1300 parameter (for example @samp{ssh here.somewhere.else -l john}.  If you
1301 have specified another user for your command in its configuration
1302 files, @value{tramp} cannot know it, and the remote access will fail.
1303 If you have specified in the given example in @file{~/.ssh/config} the
1304 lines
1306 @example
1307 Host here.somewhere.else
1308      User lily
1309 @end example
1311 @noindent
1312 than you must discard selecting a default user by @value{tramp}.  This
1313 will be done by setting it to @code{nil} (or @samp{lily}, likewise):
1315 @lisp
1316 (add-to-list 'tramp-default-user-alist
1317              '("ssh" "\\`here\\.somewhere\\.else\\'" nil))
1318 @end lisp
1320 The last entry in @code{tramp-default-user-alist} could be your
1321 default user you'll apply predominantly.  You shall @emph{append} it
1322 to that list at the end:
1324 @lisp
1325 (add-to-list 'tramp-default-user-alist '(nil nil "jonas") t)
1326 @end lisp
1329 @node Default Host
1330 @section Selecting a default host
1331 @cindex default host
1333 @vindex tramp-default-host
1334 Finally, it is even possible to omit the host name part of a
1335 @value{tramp} file name.  This case, the value of the variable
1336 @code{tramp-default-host} is used.  Per default, it is initialized
1337 with the host name your local @value{emacsname} is running.
1339 If you, for example, use @value{tramp} mainly to contact the host
1340 @samp{target} as user @samp{john}, you can specify:
1342 @lisp
1343 (setq tramp-default-user "john"
1344       tramp-default-host "target")
1345 @end lisp
1347 Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you
1348 to John's home directory on target.
1349 @ifset emacs
1350 Note, however, that the most simplification @samp{/::} won't work,
1351 because @samp{/:} is the prefix for quoted file names.
1352 @end ifset
1355 @node Multi-hops
1356 @section Connecting to a remote host using multiple hops
1357 @cindex multi-hop
1358 @cindex proxy hosts
1360 Sometimes, the methods described before are not sufficient.  Sometimes,
1361 it is not possible to connect to a remote host using a simple command.
1362 For example, if you are in a secured network, you might have to log in
1363 to a `bastion host' first before you can connect to the outside world.
1364 Of course, the target host may also require a bastion host.
1366 @vindex tramp-default-proxies-alist
1367 In order to specify such multiple hops, it is possible to define a proxy
1368 host to pass through, via the variable
1369 @code{tramp-default-proxies-alist}.  This variable keeps a list of
1370 triples (@var{host} @var{user} @var{proxy}).
1372  The first matching item specifies the proxy host to be passed for a
1373 file name located on a remote target matching @var{user}@@@var{host}.
1374 @var{host} and @var{user} are regular expressions or @code{nil}, which
1375 is interpreted as a regular expression which always matches.
1377 @var{proxy} must be a Tramp filename which localname part is ignored.
1378 Method and user name on @var{proxy} are optional, which is interpreted
1379 with the default values.
1380 @ifset emacsgw
1381 The method must be an inline or gateway method (@pxref{Inline
1382 methods}, @pxref{Gateway methods}).
1383 @end ifset
1384 @ifclear emacsgw
1385 The method must be an inline method (@pxref{Inline methods}).
1386 @end ifclear
1387 If @var{proxy} is @code{nil}, no additional hop is required reaching
1388 @var{user}@@@var{host}.
1390 If you, for example, must pass the host @samp{bastion.your.domain} as
1391 user @samp{bird} for any remote host which is not located in your local
1392 domain, you can set
1394 @lisp
1395 (add-to-list 'tramp-default-proxies-alist
1396              '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}"))
1397 (add-to-list 'tramp-default-proxies-alist
1398              '("\\.your\\.domain\\'" nil nil))
1399 @end lisp
1401 Please note the order of the code.  @code{add-to-list} adds elements at the
1402 beginning of a list.  Therefore, most relevant rules must be added last.
1404 Proxy hosts can be cascaded.  If there is another host called
1405 @samp{jump.your.domain}, which is the only one in your local domain who
1406 is allowed connecting @samp{bastion.your.domain}, you can add another
1407 rule:
1409 @lisp
1410 (add-to-list 'tramp-default-proxies-alist
1411              '("\\`bastion\\.your\\.domain\\'"
1412                "\\`bird\\'"
1413                "@trampfn{ssh, , jump.your.domain,}"))
1414 @end lisp
1416 @var{proxy} can contain the patterns @code{%h} or @code{%u}.  These
1417 patterns are replaced by the strings matching @var{host} or
1418 @var{user}, respectively.
1420 If you, for example, wants to work as @samp{root} on hosts in the
1421 domain @samp{your.domain}, but login as @samp{root} is disabled for
1422 non-local access, you might add the following rule:
1424 @lisp
1425 (add-to-list 'tramp-default-proxies-alist
1426              '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
1427 @end lisp
1429 Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect
1430 first @samp{randomhost.your.domain} via @code{ssh} under your account
1431 name, and perform @code{sudo -u root} on that host afterwards.  It is
1432 important to know that the given method is applied on the host which
1433 has been reached so far.  @code{sudo -u root}, applied on your local
1434 host, wouldn't be useful here.
1436 @var{host}, @var{user} and @var{proxy} can also be Lisp forms.  These
1437 forms are evaluated, and must return a string, or @code{nil}.  The
1438 previous example could be generalized then: For all hosts except my
1439 local one connect via @code{ssh} first, and apply @code{sudo -u root}
1440 afterwards:
1442 @lisp
1443 (add-to-list 'tramp-default-proxies-alist
1444              '(nil "\\`root\\'" "@trampfn{ssh, , %h,}"))
1445 (add-to-list 'tramp-default-proxies-alist
1446              '((regexp-quote (system-name)) nil nil))
1447 @end lisp
1449 This is the recommended configuration to work as @samp{root} on remote
1450 Ubuntu hosts.
1452 @ifset emacsgw
1453 Finally, @code{tramp-default-proxies-alist} can be used to pass
1454 firewalls or proxy servers.  Imagine your local network has a host
1455 @samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to
1456 the outer world.  Your friendly administrator has granted you access
1457 under your user name to @samp{host.other.domain} on that proxy
1458 server.@footnote{HTTP tunnels are intended for secure SSL/TLS
1459 communication.  Therefore, many proxy server restrict the tunnels to
1460 related target ports.  You might need to run your ssh server on your
1461 target host @samp{host.other.domain} on such a port, like 443 (https).
1462 See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall}
1463 for discussion of ethical issues.}  You would need to add the
1464 following rule:
1466 @lisp
1467 (add-to-list 'tramp-default-proxies-alist
1468              '("\\`host\\.other\\.domain\\'" nil
1469                "@trampfn{tunnel, , proxy.your.domain#3128,}"))
1470 @end lisp
1472 Gateway methods can be declared as first hop only in a multiple hop
1473 chain.
1474 @end ifset
1477 @node Customizing Methods
1478 @section Using Non-Standard Methods
1479 @cindex customizing methods
1480 @cindex using non-standard methods
1481 @cindex create your own methods
1483 There is a variable @code{tramp-methods} which you can change if the
1484 predefined methods don't seem right.
1486 For the time being, I'll refer you to the Lisp documentation of that
1487 variable, accessible with @kbd{C-h v tramp-methods @key{RET}}.
1490 @node Customizing Completion
1491 @section Selecting config files for user/host name completion
1492 @cindex customizing completion
1493 @cindex selecting config files
1494 @vindex tramp-completion-function-alist
1496 The variable @code{tramp-completion-function-alist} is intended to
1497 customize which files are taken into account for user and host name
1498 completion (@pxref{Filename completion}).  For every method, it keeps
1499 a set of configuration files, accompanied by a Lisp function able to
1500 parse that file.  Entries in @code{tramp-completion-function-alist}
1501 have the form (@var{method} @var{pair1} @var{pair2} ...).
1503 Each @var{pair} is composed of (@var{function} @var{file}).
1504 @var{function} is responsible to extract user names and host names
1505 from @var{file} for completion.  There are two functions which access
1506 this variable:
1508 @defun tramp-get-completion-function method
1509 This function returns the list of completion functions for @var{method}.
1511 Example:
1512 @example
1513 (tramp-get-completion-function "rsh")
1515      @result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
1516          (tramp-parse-rhosts "~/.rhosts"))
1517 @end example
1518 @end defun
1520 @defun tramp-set-completion-function method function-list
1521 This function sets @var{function-list} as list of completion functions
1522 for @var{method}.
1524 Example:
1525 @example
1526 (tramp-set-completion-function "ssh"
1527  '((tramp-parse-sconfig "/etc/ssh_config")
1528    (tramp-parse-sconfig "~/.ssh/config")))
1530      @result{} ((tramp-parse-sconfig "/etc/ssh_config")
1531          (tramp-parse-sconfig "~/.ssh/config"))
1532 @end example
1533 @end defun
1535 The following predefined functions parsing configuration files exist:
1537 @table @asis
1538 @item @code{tramp-parse-rhosts}
1539 @findex tramp-parse-rhosts
1541 This function parses files which are syntactical equivalent to
1542 @file{~/.rhosts}.  It returns both host names and user names, if
1543 specified.
1545 @item @code{tramp-parse-shosts}
1546 @findex tramp-parse-shosts
1548 This function parses files which are syntactical equivalent to
1549 @file{~/.ssh/known_hosts}.  Since there are no user names specified
1550 in such files, it can return host names only.
1552 @item @code{tramp-parse-sconfig}
1553 @findex tramp-parse-shosts
1555 This function returns the host nicknames defined by @code{Host} entries
1556 in @file{~/.ssh/config} style files.
1558 @item @code{tramp-parse-shostkeys}
1559 @findex tramp-parse-shostkeys
1561 SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and
1562 @file{~/ssh2/hostkeys/*}.  Hosts are coded in file names
1563 @file{hostkey_@var{portnumber}_@var{host-name}.pub}.  User names
1564 are always @code{nil}.
1566 @item @code{tramp-parse-sknownhosts}
1567 @findex tramp-parse-shostkeys
1569 Another SSH2 style parsing of directories like
1570 @file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}.  This
1571 case, hosts names are coded in file names
1572 @file{@var{host-name}.@var{algorithm}.pub}.  User names are always @code{nil}.
1574 @item @code{tramp-parse-hosts}
1575 @findex tramp-parse-hosts
1577 A function dedicated to @file{/etc/hosts} style files.  It returns
1578 host names only.
1580 @item @code{tramp-parse-passwd}
1581 @findex tramp-parse-passwd
1583 A function which parses @file{/etc/passwd} like files.  Obviously, it
1584 can return user names only.
1586 @item @code{tramp-parse-netrc}
1587 @findex tramp-parse-netrc
1589 Finally, a function which parses @file{~/.netrc} like files.
1590 @end table
1592 If you want to keep your own data in a file, with your own structure,
1593 you might provide such a function as well.  This function must meet
1594 the following conventions:
1596 @defun my-tramp-parse file
1597 @var{file} must be either a file name on your host, or @code{nil}.
1598 The function must return a list of (@var{user} @var{host}), which are
1599 taken as candidates for user and host name completion.
1601 Example:
1602 @example
1603 (my-tramp-parse "~/.my-tramp-hosts")
1605      @result{} ((nil "toto") ("daniel" "melancholia"))
1606 @end example
1607 @end defun
1610 @node Password handling
1611 @section Reusing passwords for several connections.
1612 @cindex passwords
1614 Sometimes it is necessary to connect to the same remote host several
1615 times.  Reentering passwords again and again would be annoying, when
1616 the chosen method does not support access without password prompt
1617 through own configuration.
1619 The best recommendation is to use the method's own mechanism for
1620 password handling. Consider @command{ssh-agent} for @option{ssh}-like
1621 methods, or @command{pageant} for @option{plink}-like methods.
1623 However, if you cannot apply such native password handling,
1624 @value{tramp} offers altenatives.
1627 @anchor{Using an authentication file}
1628 @subsection Using an authentication file
1630 @vindex auth-sources
1631 The package @file{auth-source.el}, originally developed in No Gnus,
1632 offers the possibility to read passwords from a file, like FTP does it
1633 from @file{~/.netrc}.  The default authentication file is
1634 @file{~/.authinfo.gpg}, this can be changed via the variable
1635 @code{auth-sources}.
1637 @noindent
1638 A typical entry in the authentication file would be
1640 @example
1641 machine melancholia port scp login daniel password geheim
1642 @end example
1644 The port can be any @value{tramp} method (@pxref{Inline methods},
1645 @pxref{External methods}), to match only this method.  When you omit
1646 the port, you match all @value{tramp} methods.
1648 @ifset emacsimap
1649 A special case are @option{imap}-like methods.  Authentication with
1650 the IMAP server is performed via @file{imap.el}, there is no special
1651 need from @value{tramp} point of view.  An additional passphrase, used
1652 for symmetric encryption and decryption of the stored messages, should
1653 be given with the special port indication @option{tramp-imap}:
1655 @example
1656 machine melancholia port tramp-imap login daniel password ultrageheim
1657 @end example
1658 @end ifset
1660 @anchor{Caching passwords}
1661 @subsection Caching passwords
1663 If there is no authentication file, @value{tramp} caches the passwords
1664 entered by you.  They will be reused next time if a connection needs
1665 them for the same user name and host name, independently of the
1666 connection method.
1668 @vindex password-cache-expiry
1669 Passwords are not saved permanently, that means the password caching
1670 is limited to the lifetime of your @value{emacsname} session.  You
1671 can influence the lifetime of password caching by customizing the
1672 variable @code{password-cache-expiry}.  The value is the number of
1673 seconds how long passwords are cached.  Setting it to @code{nil}
1674 disables the expiration.
1676 @vindex password-cache
1677 If you don't like this feature for security reasons, password caching
1678 can be disabled totally by customizing the variable
1679 @code{password-cache} (setting it to @code{nil}).
1681 Implementation Note: password caching is based on the package
1682 @file{password-cache.el}.  For the time being, it is activated only
1683 when this package is seen in the @code{load-path} while loading
1684 @value{tramp}.
1685 @ifset installchapter
1686 If you don't use No Gnus, you can take @file{password.el} from the
1687 @value{tramp} @file{contrib} directory, see @ref{Installation
1688 parameters}.
1689 @end ifset
1692 @node Connection caching
1693 @section Reusing connection related information.
1694 @cindex caching
1696 @vindex tramp-persistency-file-name
1697 In order to reduce initial connection time, @value{tramp} stores
1698 connection related information persistently.  The variable
1699 @code{tramp-persistency-file-name} keeps the file name where these
1700 information are written.  Its default value is
1701 @ifset emacs
1702 @file{~/.emacs.d/tramp}.
1703 @end ifset
1704 @ifset xemacs
1705 @file{~/.xemacs/tramp}.
1706 @end ifset
1707 It is recommended to choose a local file name.
1709 @value{tramp} reads this file during startup, and writes it when
1710 exiting @value{emacsname}.  You can simply remove this file if
1711 @value{tramp} shall be urged to recompute these information next
1712 @value{emacsname} startup time.
1714 Using such persistent information can be disabled by setting
1715 @code{tramp-persistency-file-name} to @code{nil}.
1717 Once consequence of reusing connection related information is that
1718 @var{tramp} needs to distinguish hosts.  If you, for example, run a
1719 local @code{sshd} on port 3001, which tunnels @command{ssh} to another
1720 host, you could access both @file{@trampfn{ssh, , localhost,}} and
1721 @file{@trampfn{ssh, , localhost#3001,}}.  @var{tramp} would use the
1722 same host related information (like paths, Perl variants, etc) for
1723 both connections, although the information is valid only for one of
1724 them.
1726 In order to avoid trouble, you must use another host name for one of
1727 the connections, like introducing a @option{Host} section in
1728 @file{~/.ssh/config} (@pxref{Frequently Asked Questions}) or applying
1729 multiple hops (@pxref{Multi-hops}).
1731 When @value{tramp} detects a changed operating system version on a
1732 remote host (via the command @command{uname -sr}), it flushes all
1733 connection related information for this host, and opens the
1734 connection, again.
1737 @node Remote Programs
1738 @section How @value{tramp} finds and uses programs on the remote machine.
1740 @value{tramp} depends on a number of programs on the remote host in order to
1741 function, including @command{ls}, @command{test}, @command{find} and
1742 @command{cat}.
1744 In addition to these required tools, there are various tools that may be
1745 required based on the connection method.  See @ref{Inline methods} and
1746 @ref{External methods} for details on these.
1748 Certain other tools, such as @command{perl} (or @command{perl5}) and
1749 @command{grep} will be used if they can be found.  When they are
1750 available, they are used to improve the performance and accuracy of
1751 remote file access.
1753 @vindex tramp-remote-path
1754 @vindex tramp-default-remote-path
1755 @vindex tramp-own-remote-path
1756 @defopt tramp-remote-path
1757 When @value{tramp} connects to the remote machine, it searches for the
1758 programs that it can use.  The variable @code{tramp-remote-path}
1759 controls the directories searched on the remote machine.
1761 By default, this is set to a reasonable set of defaults for most
1762 machines.  The symbol @code{tramp-default-remote-path} is a place
1763 holder, it is replaced by the list of directories received via the
1764 command @command{getconf PATH} on your remote machine.  For example,
1765 on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is
1766 @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}.  It is
1767 recommended to apply this symbol on top of @code{tramp-remote-path}.
1769 It is possible, however, that your local (or remote ;) system
1770 administrator has put the tools you want in some obscure local
1771 directory.
1773 In this case, you can still use them with @value{tramp}.  You simply
1774 need to add code to your @file{.emacs} to add the directory to the
1775 remote path.  This will then be searched by @value{tramp} when you
1776 connect and the software found.
1778 To add a directory to the remote search path, you could use code such
1781 @lisp
1782 @i{;; We load @value{tramp} to define the variable.}
1783 (require 'tramp)
1784 @i{;; We have @command{perl} in "/usr/local/perl/bin"}
1785 (add-to-list 'tramp-remote-path "/usr/local/perl/bin")
1786 @end lisp
1788 Another possibility is to reuse the path settings of your remote
1789 account, when you log in.  Usually, these settings are overwritten,
1790 because they might not be useful for @value{tramp}.  The place holder
1791 @code{tramp-own-remote-path} preserves these settings.  You can
1792 activate it via
1794 @lisp
1795 (add-to-list 'tramp-remote-path 'tramp-own-remote-path)
1796 @end lisp
1797 @end defopt
1799 @value{tramp} caches several information, like the Perl binary
1800 location.  The changed remote search path wouldn't affect these
1801 settings.  In order to force @value{tramp} to recompute these values,
1802 you must exit @value{emacsname}, remove your persistency file
1803 (@pxref{Connection caching}), and restart @value{emacsname}.
1806 @node Remote shell setup
1807 @section Remote shell setup hints
1808 @cindex remote shell setup
1809 @cindex @file{.profile} file
1810 @cindex @file{.login} file
1811 @cindex shell init files
1813 As explained in the @ref{Overview} section, @value{tramp} connects to the
1814 remote host and talks to the shell it finds there.  Of course, when you
1815 log in, the shell executes its init files.  Suppose your init file
1816 requires you to enter the birth date of your mother; clearly @value{tramp}
1817 does not know this and hence fails to log you in to that host.
1819 There are different possible strategies for pursuing this problem.  One
1820 strategy is to enable @value{tramp} to deal with all possible situations.
1821 This is a losing battle, since it is not possible to deal with
1822 @emph{all} situations.  The other strategy is to require you to set up
1823 the remote host such that it behaves like @value{tramp} expects.  This might
1824 be inconvenient because you have to invest a lot of effort into shell
1825 setup before you can begin to use @value{tramp}.
1827 The package, therefore, pursues a combined approach.  It tries to
1828 figure out some of the more common setups, and only requires you to
1829 avoid really exotic stuff.  For example, it looks through a list of
1830 directories to find some programs on the remote host.  And also, it
1831 knows that it is not obvious how to check whether a file exists, and
1832 therefore it tries different possibilities.  (On some hosts and
1833 shells, the command @command{test -e} does the trick, on some hosts
1834 the shell builtin doesn't work but the program @command{/usr/bin/test
1835 -e} or @command{/bin/test -e} works.  And on still other hosts,
1836 @command{ls -d} is the right way to do this.)
1838 Below you find a discussion of a few things that @value{tramp} does not deal
1839 with, and that you therefore have to set up correctly.
1841 @table @asis
1842 @item @var{shell-prompt-pattern}
1843 @vindex shell-prompt-pattern
1845 After logging in to the remote host, @value{tramp} has to wait for the remote
1846 shell startup to finish before it can send commands to the remote
1847 shell.  The strategy here is to wait for the shell prompt.  In order to
1848 recognize the shell prompt, the variable @code{shell-prompt-pattern} has
1849 to be set correctly to recognize the shell prompt on the remote host.
1851 Note that @value{tramp} requires the match for @code{shell-prompt-pattern}
1852 to be at the end of the buffer.  Many people have something like the
1853 following as the value for the variable: @code{"^[^>$][>$] *"}.  Now
1854 suppose your shell prompt is @code{a <b> c $ }.  In this case,
1855 @value{tramp} recognizes the @code{>} character as the end of the prompt,
1856 but it is not at the end of the buffer.
1858 @item @var{tramp-shell-prompt-pattern}
1859 @vindex tramp-shell-prompt-pattern
1861 This regular expression is used by @value{tramp} in the same way as
1862 @code{shell-prompt-pattern}, to match prompts from the remote shell.
1863 This second variable exists because the prompt from the remote shell
1864 might be different from the prompt from a local shell --- after all,
1865 the whole point of @value{tramp} is to log in to remote hosts as a
1866 different user.  The default value of
1867 @code{tramp-shell-prompt-pattern} is the same as the default value of
1868 @code{shell-prompt-pattern}, which is reported to work well in many
1869 circumstances.
1871 @item @var{tramp-password-prompt-regexp}
1872 @vindex tramp-password-prompt-regexp
1873 @vindex tramp-wrong-passwd-regexp
1875 During login, @value{tramp} might be forced to enter a password or a
1876 passphrase.  The difference between both is that a password is
1877 requested from the shell on the remote host, while a passphrase is
1878 needed for accessing local authentication information, like your ssh
1879 key.
1881 @var{tramp-password-prompt-regexp} handles the detection of such
1882 requests for English environments.  When you use another localization
1883 of your (local or remote) host, you might need to adapt this. Example:
1885 @lisp
1886 (setq
1887   tramp-password-prompt-regexp
1888     (concat
1889       "^.*"
1890       (regexp-opt
1891         '("passphrase" "Passphrase"
1892           ;; English
1893           "password" "Password"
1894           ;; Deutsch
1895           "passwort" "Passwort"
1896           ;; Fran@,{c}ais
1897           "mot de passe" "Mot de passe") t)
1898       ".*:\0? *"))
1899 @end lisp
1901 In parallel, it might also be necessary to adapt
1902 @var{tramp-wrong-passwd-regexp}.
1904 @item @command{tset} and other questions
1905 @cindex Unix command tset
1906 @cindex tset Unix command
1908 Some people invoke the @command{tset} program from their shell startup
1909 scripts which asks the user about the terminal type of the shell.
1910 Maybe some shells ask other questions when they are started.
1911 @value{tramp} does not know how to answer these questions.  There are
1912 two approaches for dealing with this problem.  One approach is to take
1913 care that the shell does not ask any questions when invoked from
1914 @value{tramp}.  You can do this by checking the @code{TERM}
1915 environment variable, it will be set to @code{dumb} when connecting.
1917 @vindex tramp-terminal-type
1918 The variable @code{tramp-terminal-type} can be used to change this value
1919 to @code{dumb}.
1921 @vindex tramp-actions-before-shell
1922 The other approach is to teach @value{tramp} about these questions.  See
1923 the variable @code{tramp-actions-before-shell}.  Example:
1925 @lisp
1926 (defconst my-tramp-prompt-regexp
1927   (concat (regexp-opt '("Enter the birth date of your mother:") t)
1928           "\\s-*")
1929   "Regular expression matching my login prompt question.")
1931 (defun my-tramp-action (proc vec)
1932   "Enter \"19000101\" in order to give a correct answer."
1933   (save-window-excursion
1934     (with-current-buffer (tramp-get-connection-buffer vec)
1935       (tramp-message vec 6 "\n%s" (buffer-string))
1936       (tramp-send-string vec "19000101"))))
1938 (add-to-list 'tramp-actions-before-shell
1939              '(my-tramp-prompt-regexp my-tramp-action))
1940 @end lisp
1943 @item Environment variables named like users in @file{.profile}
1945 If you have a user named frumple and set the variable @code{FRUMPLE} in
1946 your shell environment, then this might cause trouble.  Maybe rename
1947 the variable to @code{FRUMPLE_DIR} or the like.
1949 This weird effect was actually reported by a @value{tramp} user!
1952 @item Non-Bourne commands in @file{.profile}
1954 After logging in to the remote host, @value{tramp} issues the command
1955 @command{exec /bin/sh}.  (Actually, the command is slightly
1956 different.)  When @command{/bin/sh} is executed, it reads some init
1957 files, such as @file{~/.shrc} or @file{~/.profile}.
1959 Now, some people have a login shell which is not @code{/bin/sh} but a
1960 Bourne-ish shell such as bash or ksh.  Some of these people might put
1961 their shell setup into the files @file{~/.shrc} or @file{~/.profile}.
1962 This way, it is possible for non-Bourne constructs to end up in those
1963 files.  Then, @command{exec /bin/sh} might cause the Bourne shell to
1964 barf on those constructs.
1966 As an example, imagine somebody putting @command{export FOO=bar} into
1967 the file @file{~/.profile}.  The standard Bourne shell does not
1968 understand this syntax and will emit a syntax error when it reaches
1969 this line.
1971 Another example is the tilde (@code{~}) character, say when adding
1972 @file{~/bin} to @code{$PATH}.  Many Bourne shells will not expand this
1973 character, and since there is usually no directory whose name consists
1974 of the single character tilde, strange things will happen.
1976 What can you do about this?
1978 Well, one possibility is to make sure that everything in
1979 @file{~/.shrc} and @file{~/.profile} on all remote hosts is
1980 Bourne-compatible.  In the above example, instead of @command{export
1981 FOO=bar}, you might use @command{FOO=bar; export FOO} instead.
1983 The other possibility is to put your non-Bourne shell setup into some
1984 other files.  For example, bash reads the file @file{~/.bash_profile}
1985 instead of @file{~/.profile}, if the former exists.  So bash
1986 aficionados just rename their @file{~/.profile} to
1987 @file{~/.bash_profile} on all remote hosts, and Bob's your uncle.
1989 The @value{tramp} developers would like to circumvent this problem, so
1990 if you have an idea about it, please tell us.  However, we are afraid
1991 it is not that simple: before saying @command{exec /bin/sh},
1992 @value{tramp} does not know which kind of shell it might be talking
1993 to.  It could be a Bourne-ish shell like ksh or bash, or it could be a
1994 csh derivative like tcsh, or it could be zsh, or even rc.  If the
1995 shell is Bourne-ish already, then it might be prudent to omit the
1996 @command{exec /bin/sh} step.  But how to find out if the shell is
1997 Bourne-ish?
1999 @end table
2002 @node Auto-save and Backup
2003 @section Auto-save and Backup configuration
2004 @cindex auto-save
2005 @cindex backup
2006 @ifset emacs
2007 @vindex backup-directory-alist
2008 @end ifset
2009 @ifset xemacs
2010 @vindex bkup-backup-directory-info
2011 @end ifset
2013 Normally, @value{emacsname} writes backup files to the same directory
2014 as the original files, but this behavior can be changed via the
2015 variable
2016 @ifset emacs
2017 @code{backup-directory-alist}.
2018 @end ifset
2019 @ifset xemacs
2020 @code{bkup-backup-directory-info}.
2021 @end ifset
2022 In connection with @value{tramp}, this can have unexpected side
2023 effects.  Suppose that you specify that all backups should go to the
2024 directory @file{~/.emacs.d/backups/}, and then you edit the file
2025 @file{@trampfn{su, root, localhost, /etc/secretfile}}.  The effect is
2026 that the backup file will be owned by you and not by root, thus
2027 possibly enabling others to see it even if they were not intended to
2028 see it.
2030 When
2031 @ifset emacs
2032 @code{backup-directory-alist}
2033 @end ifset
2034 @ifset xemacs
2035 @code{bkup-backup-directory-info}
2036 @end ifset
2037 is @code{nil} (the default), such problems do not occur.
2039 Therefore, it is useful to set special values for @value{tramp}
2040 files.  For example, the following statement effectively `turns off'
2041 the effect of
2042 @ifset emacs
2043 @code{backup-directory-alist}
2044 @end ifset
2045 @ifset xemacs
2046 @code{bkup-backup-directory-info}
2047 @end ifset
2048 for @value{tramp} files:
2050 @ifset emacs
2051 @lisp
2052 (add-to-list 'backup-directory-alist
2053              (cons tramp-file-name-regexp nil))
2054 @end lisp
2055 @end ifset
2056 @ifset xemacs
2057 @lisp
2058 (require 'backup-dir)
2059 (add-to-list 'bkup-backup-directory-info
2060              (list tramp-file-name-regexp ""))
2061 @end lisp
2062 @end ifset
2064 @ifset emacs
2065 It is also possible to disable backups depending on the used method.
2066 The following code disables backups for the @option{su} and
2067 @option{sudo} methods:
2069 @lisp
2070 (setq backup-enable-predicate
2071       (lambda (name)
2072         (and (normal-backup-enable-predicate name)
2073              (not
2074               (let ((method (file-remote-p name 'method)))
2075                 (when (stringp method)
2076                   (member method '("su" "sudo"))))))))
2077 @end lisp
2078 @end ifset
2081 Another possibility is to use the @value{tramp} variable
2082 @ifset emacs
2083 @code{tramp-backup-directory-alist}.
2084 @end ifset
2085 @ifset xemacs
2086 @code{tramp-bkup-backup-directory-info}.
2087 @end ifset
2088 This variable has the same meaning like
2089 @ifset emacs
2090 @code{backup-directory-alist}.
2091 @end ifset
2092 @ifset xemacs
2093 @code{bkup-backup-directory-info}.
2094 @end ifset
2095 If a @value{tramp} file is backed up, and DIRECTORY is an absolute
2096 local file name, DIRECTORY is prepended with the @value{tramp} file
2097 name prefix of the file to be backed up.
2099 @noindent
2100 Example:
2102 @ifset emacs
2103 @lisp
2104 (add-to-list 'backup-directory-alist
2105              (cons "." "~/.emacs.d/backups/"))
2106 (setq tramp-backup-directory-alist backup-directory-alist)
2107 @end lisp
2108 @end ifset
2109 @ifset xemacs
2110 @lisp
2111 (require 'backup-dir)
2112 (add-to-list 'bkup-backup-directory-info
2113              (list "." "~/.emacs.d/backups/" 'full-path))
2114 (setq tramp-bkup-backup-directory-info bkup-backup-directory-info)
2115 @end lisp
2116 @end ifset
2118 @noindent
2119 The backup file name of @file{@trampfn{su, root, localhost,
2120 /etc/secretfile}} would be
2121 @ifset emacs
2122 @file{@trampfn{su, root, localhost,
2123 ~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
2124 @end ifset
2125 @ifset xemacs
2126 @file{@trampfn{su, root, localhost,
2127 ~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}
2128 @end ifset
2130 The same problem can happen with auto-saving files.
2131 @ifset emacs
2132 The variable @code{auto-save-file-name-transforms} keeps information,
2133 on which directory an auto-saved file should go.  By default, it is
2134 initialized for @value{tramp} files to the local temporary directory.
2136 On some versions of @value{emacsname}, namely the version built for
2137 Debian GNU/Linux, the variable @code{auto-save-file-name-transforms}
2138 contains the directory where @value{emacsname} was built.  A
2139 workaround is to manually set the variable to a sane value.
2141 If auto-saved files should go into the same directory as the original
2142 files, @code{auto-save-file-name-transforms} should be set to @code{nil}.
2144 Another possibility is to set the variable
2145 @code{tramp-auto-save-directory} to a proper value.
2146 @end ifset
2147 @ifset xemacs
2148 For this purpose you can set the variable @code{auto-save-directory}
2149 to a proper value.
2150 @end ifset
2153 @node Windows setup hints
2154 @section Issues with Cygwin ssh
2155 @cindex Cygwin, issues
2157 This section needs a lot of work!  Please help.
2159 @cindex method sshx with Cygwin
2160 @cindex sshx method with Cygwin
2161 The recent Cygwin installation of @command{ssh} works only with a
2162 Cygwinized @value{emacsname}.  You can check it by typing @kbd{M-x
2163 eshell}, and starting @kbd{ssh test.machine}.  The problem is evident
2164 if you see a message like this:
2166 @example
2167 Pseudo-terminal will not be allocated because stdin is not a terminal.
2168 @end example
2170 Older @command{ssh} versions of Cygwin are told to cooperate with
2171 @value{tramp} selecting @option{sshx} as the connection method.  You
2172 can find information about setting up Cygwin in their FAQ at
2173 @uref{http://cygwin.com/faq/}.
2175 @cindex method scpx with Cygwin
2176 @cindex scpx method with Cygwin
2177 If you wish to use the @option{scpx} connection method, then you might
2178 have the problem that @value{emacsname} calls @command{scp} with a
2179 Windows filename such as @code{c:/foo}.  The Cygwin version of
2180 @command{scp} does not know about Windows filenames and interprets
2181 this as a remote filename on the host @code{c}.
2183 One possible workaround is to write a wrapper script for @option{scp}
2184 which converts the Windows filename to a Cygwinized filename.
2186 @cindex Cygwin and ssh-agent
2187 @cindex SSH_AUTH_SOCK and @value{emacsname} on Windows
2188 If you want to use either @option{ssh} based method on Windows, then
2189 you might encounter problems with @command{ssh-agent}.  Using this
2190 program, you can avoid typing the pass-phrase every time you log in.
2191 However, if you start @value{emacsname} from a desktop shortcut, then
2192 the environment variable @code{SSH_AUTH_SOCK} is not set and so
2193 @value{emacsname} and thus @value{tramp} and thus @command{ssh} and
2194 @command{scp} started from @value{tramp} cannot communicate with
2195 @command{ssh-agent}.  It works better to start @value{emacsname} from
2196 the shell.
2198 If anyone knows how to start @command{ssh-agent} under Windows in such a
2199 way that desktop shortcuts can profit, please holler.  I don't really
2200 know anything at all about Windows@dots{}
2203 @node Usage
2204 @chapter Using @value{tramp}
2205 @cindex using @value{tramp}
2207 Once you have installed @value{tramp} it will operate fairly
2208 transparently.  You will be able to access files on any remote machine
2209 that you can log in to as though they were local.
2211 Files are specified to @value{tramp} using a formalized syntax specifying the
2212 details of the system to connect to.  This is similar to the syntax used
2213 by the @value{ftppackagename} package.
2215 @cindex type-ahead
2216 Something that might happen which surprises you is that
2217 @value{emacsname} remembers all your keystrokes, so if you see a
2218 password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}}
2219 twice instead of once, then the second keystroke will be processed by
2220 @value{emacsname} after @value{tramp} has done its thing.  Why, this
2221 type-ahead is normal behavior, you say.  Right you are, but be aware
2222 that opening a remote file might take quite a while, maybe half a
2223 minute when a connection needs to be opened.  Maybe after half a
2224 minute you have already forgotten that you hit that key!
2226 @menu
2227 * Filename Syntax::             @value{tramp} filename conventions.
2228 * Alternative Syntax::          URL-like filename syntax.
2229 * Filename completion::         Filename completion.
2230 * Remote processes::            Integration with other @value{emacsname} packages.
2231 * Cleanup remote connections::  Cleanup remote connections.
2232 @end menu
2235 @node Filename Syntax
2236 @section @value{tramp} filename conventions
2237 @cindex filename syntax
2238 @cindex filename examples
2240 To access the file @var{localname} on the remote machine @var{machine}
2241 you would specify the filename @file{@trampfn{, , machine,
2242 localname}}.  This will connect to @var{machine} and transfer the file
2243 using the default method.  @xref{Default Method}.
2245 Some examples of @value{tramp} filenames are shown below.
2247 @table @file
2248 @item @trampfn{, , melancholia, .emacs}
2249 Edit the file @file{.emacs} in your home directory on the machine
2250 @code{melancholia}.
2252 @item @trampfn{, , melancholia.danann.net, .emacs}
2253 This edits the same file, using the fully qualified domain name of
2254 the machine.
2256 @item @trampfn{, , melancholia, ~/.emacs}
2257 This also edits the same file --- the @file{~} is expanded to your
2258 home directory on the remote machine, just like it is locally.
2260 @item @trampfn{, , melancholia, ~daniel/.emacs}
2261 This edits the file @file{.emacs} in the home directory of the user
2262 @code{daniel} on the machine @code{melancholia}.  The @file{~<user>}
2263 construct is expanded to the home directory of that user on the remote
2264 machine.
2266 @item @trampfn{, , melancholia, /etc/squid.conf}
2267 This edits the file @file{/etc/squid.conf} on the machine
2268 @code{melancholia}.
2270 @end table
2272 @var{machine} can also be an IPv4 or IPv6 address, like in
2273 @file{@trampfn{, , 127.0.0.1, .emacs}} or @file{@trampfn{, ,
2274 @value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}.
2275 @ifset emacs
2276 For syntactical reasons, IPv6 addresses must be embedded in square
2277 brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
2278 @end ifset
2280 Unless you specify a different name to use, @value{tramp} will use the
2281 current local user name as the remote user name to log in with.  If you
2282 need to log in as a different user, you can specify the user name as
2283 part of the filename.
2285 To log in to the remote machine as a specific user, you use the syntax
2286 @file{@trampfn{, user, machine, path/to.file}}.  That means that
2287 connecting to @code{melancholia} as @code{daniel} and editing
2288 @file{.emacs} in your home directory you would specify
2289 @file{@trampfn{, daniel, melancholia, .emacs}}.
2291 It is also possible to specify other file transfer methods
2292 (@pxref{Inline methods}, @pxref{External methods}) as part of the
2293 filename.
2294 @ifset emacs
2295 This is done by putting the method before the user and host name, as
2296 in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the
2297 trailing colon).
2298 @end ifset
2299 @ifset xemacs
2300 This is done by replacing the initial @file{@value{prefix}} with
2301 @file{@value{prefix}<method>@value{postfixhop}}.  (Note the trailing
2302 slash!).
2303 @end ifset
2304 The user, machine and file specification remain the same.
2306 So, to connect to the machine @code{melancholia} as @code{daniel},
2307 using the @option{ssh} method to transfer files, and edit
2308 @file{.emacs} in my home directory I would specify the filename
2309 @file{@trampfn{ssh, daniel, melancholia, .emacs}}.
2311 Finally, for some methods it is possible to specify a different port
2312 number than the default one, given by the method.  This is specified
2313 by adding @file{#<port>} to the host name, like in @file{@trampfn{ssh,
2314 daniel, melancholia#42, .emacs}}.
2317 @node Alternative Syntax
2318 @section URL-like filename syntax
2319 @cindex filename syntax
2320 @cindex filename examples
2322 Additionally to the syntax described in the previous chapter, it is
2323 possible to use a URL-like syntax for @value{tramp}.  This can be
2324 switched on by customizing the variable @code{tramp-syntax}.  Please
2325 note that this feature is experimental for the time being.
2327 The variable @code{tramp-syntax} must be set before requiring @value{tramp}:
2329 @lisp
2330 (setq tramp-syntax 'url)
2331 (require 'tramp)
2332 @end lisp
2334 Then, a @value{tramp} filename would look like this:
2335 @file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}.
2336 @file{/@var{method}://} is mandatory, all other parts are optional.
2337 @file{:@var{port}} is useful for methods only who support this.
2339 The last example from the previous section would look like this:
2340 @file{/ssh://daniel@@melancholia/.emacs}.
2342 For the time being, @code{tramp-syntax} can have the following values:
2344 @itemize @w{}
2345 @ifset emacs
2346 @item @code{ftp} -- That is the default syntax
2347 @item @code{url} -- URL-like syntax
2348 @end ifset
2349 @ifset xemacs
2350 @item @code{sep} -- That is the default syntax
2351 @item @code{url} -- URL-like syntax
2352 @item @code{ftp} -- EFS-like syntax
2353 @end ifset
2354 @end itemize
2357 @node Filename completion
2358 @section Filename completion
2359 @cindex filename completion
2361 Filename completion works with @value{tramp} for completion of method
2362 names, of user names and of machine names as well as for completion of
2363 file names on remote machines.
2364 @ifset emacs
2365 In order to enable this, partial completion must be activated in your
2366 @file{.emacs}.
2367 @ifinfo
2368 @xref{Completion Options, , , @value{emacsdir}}.
2369 @end ifinfo
2370 @end ifset
2372 If you, for example, type @kbd{C-x C-f @value{prefix}t
2373 @key{TAB}}, @value{tramp} might give you as result the choice for
2375 @example
2376 @multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
2377 @ifset emacs
2378 @item @value{prefixhop}telnet@value{postfixhop} @tab tmp/
2379 @item @value{prefixhop}toto@value{postfix} @tab
2380 @end ifset
2381 @ifset xemacs
2382 @item @value{prefixhop}telnet@value{postfixhop} @tab @value{prefixhop}toto@value{postfix}
2383 @end ifset
2384 @end multitable
2385 @end example
2387 @samp{@value{prefixhop}telnet@value{postfixhop}}
2388 is a possible completion for the respective method,
2389 @ifset emacs
2390 @samp{tmp/} stands for the directory @file{/tmp} on your local
2391 machine,
2392 @end ifset
2393 and @samp{@value{prefixhop}toto@value{postfix}}
2394 might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts}
2395 file (given you're using default method @option{ssh}).
2397 If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to
2398 @samp{@value{prefix}telnet@value{postfixhop}}.
2399 Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in
2400 your @file{/etc/hosts} file, let's say
2402 @example
2403 @multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
2404 @item @trampfn{telnet, , 127.0.0.1,} @tab @trampfn{telnet, , 192.168.0.1,}
2405 @item @trampfn{telnet, , @value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet, , localhost,}
2406 @item @trampfn{telnet, , melancholia.danann.net,} @tab @trampfn{telnet, , melancholia,}
2407 @end multitable
2408 @end example
2410 Now you can choose the desired machine, and you can continue to
2411 complete file names on that machine.
2413 If the configuration files (@pxref{Customizing Completion}), which
2414 @value{tramp} uses for analysis of completion, offer user names, those user
2415 names will be taken into account as well.
2417 Remote machines, which have been visited in the past and kept
2418 persistently (@pxref{Connection caching}), will be offered too.
2420 Once the remote machine identification is completed, it comes to
2421 filename completion on the remote host.  This works pretty much like
2422 for files on the local host, with the exception that minibuffer
2423 killing via a double-slash works only on the filename part, except
2424 that filename part starts with @file{//}.
2425 @ifset emacs
2426 A triple-slash stands for the default behavior.
2427 @end ifset
2428 @ifinfo
2429 @xref{Minibuffer File, , , @value{emacsdir}}.
2430 @end ifinfo
2432 @noindent
2433 Example:
2435 @example
2436 @ifset emacs
2437 @kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//etc} @key{TAB}}
2438      @print{} @trampfn{telnet, , melancholia, /etc}
2440 @kbd{C-x C-f @trampfn{telnet, , melancholia, //etc} @key{TAB}}
2441      @print{} /etc
2443 @kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin///etc} @key{TAB}}
2444      @print{} /etc
2445 @end ifset
2447 @ifset xemacs
2448 @kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//}}
2449      @print{} @trampfn{telnet, , melancholia, /}
2451 @kbd{C-x C-f @trampfn{telnet, , melancholia, //}}
2452      @print{} /
2453 @end ifset
2454 @end example
2456 A remote directory might have changed its contents out of
2457 @value{emacsname} control, for example by creation or deletion of
2458 files by other processes.  Therefore, during filename completion the
2459 remote directory contents is reread regularly in order to detect such
2460 changes, which would be invisible otherwise (@pxref{Connection caching}).
2462 @defopt tramp-completion-reread-directory-timeout
2463 This variable defines the number of seconds since last remote command
2464 before rereading a directory contents.  A value of 0 would require an
2465 immediate reread during filename completion, @code{nil} means to use
2466 always cached values for the directory contents.
2467 @end defopt
2470 @node Remote processes
2471 @section Integration with other @value{emacsname} packages.
2472 @cindex compile
2473 @cindex recompile
2475 @value{tramp} supports running processes on a remote host.  This
2476 allows to exploit @value{emacsname} packages without modification for
2477 remote file names.  It does not work for the @option{ftp} and
2478 @option{smb} methods.  Association of a pty, as specified in
2479 @code{start-file-process}, is not supported.
2481 @ifset emacsgvfs
2482 If the remote host is mounted via GVFS (see @ref{GVFS based methods}),
2483 the remote filesystem is mounted locally.  Therefore, there are no
2484 remote processes; all processes run still locally on your machine with
2485 an adapted @code{default-directory}.  This section does not apply for
2486 such connection methods.
2487 @end ifset
2489 Remote processes are started when a corresponding command is executed
2490 from a buffer belonging to a remote file or directory.  Up to now, the
2491 packages @file{compile.el} (commands like @code{compile} and
2492 @code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}) have been
2493 integrated.  Integration of further packages is planned, any help for
2494 this is welcome!
2496 When your program is not found in the default search path
2497 @value{tramp} sets on the remote machine, you should either use an
2498 absolute path, or extend @code{tramp-remote-path} (see @ref{Remote
2499 Programs}):
2501 @lisp
2502 (add-to-list 'tramp-remote-path "~/bin")
2503 (add-to-list 'tramp-remote-path "/appli/pub/bin")
2504 @end lisp
2506 The environment for your program can be adapted by customizing
2507 @code{tramp-remote-process-environment}.  This variable is a list of
2508 strings.  It is structured like @code{process-environment}.  Each
2509 element is a string of the form ENVVARNAME=VALUE.  An entry
2510 ENVVARNAME= disables the corresponding environment variable, which
2511 might have been set in your init file like @file{~/.profile}.
2513 @noindent
2514 Adding an entry can be performed via @code{add-to-list}:
2516 @lisp
2517 (add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")
2518 @end lisp
2520 Changing or removing an existing entry is not encouraged.  The default
2521 values are chosen for proper @value{tramp} work.  Nevertheless, if for
2522 example a paranoid system administrator disallows changing the
2523 @var{$HISTORY} environment variable, you can customize
2524 @code{tramp-remote-process-environment}, or you can apply the
2525 following code in your @file{.emacs}:
2527 @lisp
2528 (let ((process-environment tramp-remote-process-environment))
2529   (setenv "HISTORY" nil)
2530   (setq tramp-remote-process-environment process-environment))
2531 @end lisp
2533 If you use other @value{emacsname} packages which do not run
2534 out-of-the-box on a remote host, please let us know.  We will try to
2535 integrate them as well.  @xref{Bug Reports}.
2538 @subsection Running remote programs that create local X11 windows
2540 If you want to run a remote program, which shall connect the X11
2541 server you are using with your local host, you can set the
2542 @var{$DISPLAY} environment variable on the remote host:
2544 @lisp
2545 (add-to-list 'tramp-remote-process-environment
2546              (format "DISPLAY=%s" (getenv "DISPLAY")))
2547 @end lisp
2549 @noindent
2550 @code{(getenv "DISPLAY")} shall return a string containing a host
2551 name, which can be interpreted on the remote host; otherwise you might
2552 use a fixed host name.  Strings like @code{:0} cannot be used properly
2553 on the remote host.
2555 Another trick might be that you put @code{ForwardX11 yes} or
2556 @code{ForwardX11Trusted yes} to your @file{~/.ssh/config} file for
2557 that host.
2560 @subsection Running shell-command on a remote host
2561 @cindex shell-command
2563 @code{shell-command} allows to execute commands in a shell, either
2564 synchronously, either asynchronously.  This works also on remote
2565 hosts.  Example:
2567 @example
2568 @kbd{C-x C-f @trampfn{sudo, , , } @key{RET}}
2569 @kbd{M-! tail -f /var/log/syslog.log & @key{RET}}
2570 @end example
2572 You will see the buffer @file{*Async Shell Command*}, containing the
2573 continuous output of the @command{tail} command.
2576 @subsection Running eshell on a remote host
2577 @cindex eshell
2579 @value{tramp} is integrated into @file{eshell.el}.  That is, you can
2580 open an interactive shell on your remote host, and run commands there.
2581 After you have started @code{eshell}, you could perform commands like
2582 this:
2584 @example
2585 @b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
2586 @b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET}
2587 host
2588 @b{@trampfn{sudo, root, host, /etc} $} id @key{RET}
2589 uid=0(root) gid=0(root) groups=0(root)
2590 @b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET}
2591 #<buffer shadow>
2592 @b{@trampfn{sudo, root, host, /etc} $}
2593 @end example
2595 @ifset emacs
2596 Since @value{emacsname} 23.2, @code{eshell} has also an own
2597 implementation of the @code{su} and @code{sudo} commands.  Both
2598 commands change the default directory of the @file{*eshell*} buffer to
2599 the value related to the user the command has switched to.  This works
2600 even on remote hosts, adding silently a corresponding entry to the
2601 variable @code{tramp-default-proxies-alist} (@pxref{Multi-hops}):
2603 @example
2604 @b{~ $} cd @trampfn{ssh, user, remotehost, /etc} @key{RET}
2605 @b{@trampfn{ssh, user, remotehost, /etc} $} find-file shadow @key{RET}
2606 File is not readable: @trampfn{ssh, user, remotehost, /etc/shadow}
2607 @b{@trampfn{ssh, user, remotehost, /etc} $} sudo find-file shadow @key{RET}
2608 #<buffer shadow>
2610 @b{@trampfn{ssh, user, remotehost, /etc} $} su - @key{RET}
2611 @b{@trampfn{su, root, remotehost, /root} $} id @key{RET}
2612 uid=0(root) gid=0(root) groups=0(root)
2613 @b{@trampfn{su, root, remotehost, /root} $}
2614 @end example
2615 @end ifset
2618 @anchor{Running a debugger on a remote host}
2619 @subsection Running a debugger on a remote host
2620 @cindex gud
2621 @cindex gdb
2622 @cindex perldb
2624 @file{gud.el} offers an unified interface to several symbolic
2625 debuggers
2626 @ifset emacs
2627 @ifinfo
2628 (@ref{Debuggers, , , @value{emacsdir}}).
2629 @end ifinfo
2630 @end ifset
2631 With @value{tramp}, it is possible to debug programs on
2632 remote hosts.  You can call @code{gdb} with a remote file name:
2634 @example
2635 @kbd{M-x gdb @key{RET}}
2636 @b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET}
2637 @end example
2639 The file name can also be relative to a remote default directory.
2640 Given you are in a buffer that belongs to the remote directory
2641 @trampfn{ssh, , host, /home/user}, you could call
2643 @example
2644 @kbd{M-x perldb @key{RET}}
2645 @b{Run perldb (like this):} perl -d myprog.pl @key{RET}
2646 @end example
2648 It is not possible to use just the absolute local part of a remote
2649 file name as program to debug, like @kbd{perl -d
2650 /home/user/myprog.pl}, though.
2652 Arguments of the program to be debugged are taken literally.  That
2653 means, file names as arguments must be given as ordinary relative or
2654 absolute file names, without any remote specification.
2657 @node Cleanup remote connections
2658 @section Cleanup remote connections.
2659 @cindex cleanup
2661 Sometimes it is useful to cleanup remote connections.  The following
2662 commands support this.
2664 @deffn Command tramp-cleanup-connection vec
2665 This command flushes all connection related objects.  @option{vec} is
2666 the internal representation of a remote connection.  Called
2667 interactively, the command offers all active remote connections in the
2668 minibuffer as remote file name prefix like @file{@trampfn{method,
2669 user, host, }}.  The cleanup includes password cache (@pxref{Password
2670 handling}), file cache, connection cache (@pxref{Connection caching}),
2671 connection buffers.
2672 @end deffn
2674 @deffn Command tramp-cleanup-all-connections
2675 This command flushes objects for all active remote connections.  The
2676 same objects are removed as in @code{tramp-cleanup-connection}.
2677 @end deffn
2679 @deffn Command tramp-cleanup-all-buffers
2680 Like in @code{tramp-cleanup-all-connections}, all remote connections
2681 are cleaned up.  Additionally all buffers, which are related to a
2682 remote connection, are killed.
2683 @end deffn
2686 @node Bug Reports
2687 @chapter Reporting Bugs and Problems
2688 @cindex bug reports
2690 Bugs and problems with @value{tramp} are actively worked on by the
2691 development team.  Feature requests and suggestions are also more than
2692 welcome.
2694 The @value{tramp} mailing list is a great place to get information on
2695 working with @value{tramp}, solving problems and general discussion
2696 and advice on topics relating to the package.  It is moderated so
2697 non-subscribers can post but messages will be delayed, possibly up to
2698 48 hours (or longer in case of holidays), until the moderator approves
2699 your message.
2701 The mailing list is at @email{tramp-devel@@gnu.org}.  Messages sent to
2702 this address go to all the subscribers.  This is @emph{not} the address
2703 to send subscription requests to.
2705 Subscribing to the list is performed via
2706 @uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/,
2707 the @value{tramp} Mail Subscription Page}.
2709 @findex tramp-bug
2710 To report a bug in @value{tramp}, you should execute @kbd{M-x
2711 tramp-bug}.  This will automatically generate a buffer with the details
2712 of your system and @value{tramp} version.
2714 When submitting a bug report, please try to describe in excruciating
2715 detail the steps required to reproduce the problem, the setup of the
2716 remote machine and any special conditions that exist.  You should also
2717 check that your problem is not described already in @xref{Frequently
2718 Asked Questions}.
2720 If you can identify a minimal test case that reproduces the problem,
2721 include that with your bug report.  This will make it much easier for
2722 the development team to analyze and correct the problem.
2724 Before reporting the bug, you should set the verbosity level to 6
2725 (@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and
2726 repeat the bug.  Then, include the contents of the @file{*tramp/foo*}
2727 and @file{*debug tramp/foo*} buffers in your bug report.  A verbosity
2728 level greater than 6 will produce a very huge debug buffer, which is
2729 mostly not necessary for the analysis.
2731 Please be aware that, with a verbosity level of 6 or greater, the
2732 contents of files and directories will be included in the debug
2733 buffer.  Passwords you've typed will never be included there.
2736 @node Frequently Asked Questions
2737 @chapter Frequently Asked Questions
2738 @cindex frequently asked questions
2739 @cindex FAQ
2741 @itemize @bullet
2742 @item
2743 Where can I get the latest @value{tramp}?
2745 @value{tramp} is available under the URL below.
2747 @noindent
2748 @uref{ftp://ftp.gnu.org/gnu/tramp/}
2750 @noindent
2751 There is also a Savannah project page.
2753 @noindent
2754 @uref{http://savannah.gnu.org/projects/tramp/}
2757 @item
2758 Which systems does it work on?
2760 The package has been used successfully on GNU Emacs 22, GNU Emacs 23,
2761 XEmacs 21 (starting with 21.4), and SXEmacs 22.
2763 The package was intended to work on Unix, and it really expects a
2764 Unix-like system on the remote end (except the @option{smb} and
2765 @option{imap} methods), but some people seemed to have some success
2766 getting it to work on MS Windows XP/Vista/7 @value{emacsname}.
2769 @item
2770 How could I speed up @value{tramp}?
2772 In the backstage, @value{tramp} needs a lot of operations on the
2773 remote host.  The time for transferring data from and to the remote
2774 host as well as the time needed to perform the operations there count.
2775 In order to speed up @value{tramp}, one could either try to avoid some
2776 of the operations, or one could try to improve their performance.
2778 Use an external method, like @option{scpc}.
2780 Use caching.  This is already enabled by default.  Information about
2781 the remote host as well as the remote files are cached for reuse.  The
2782 information about remote hosts is kept in the file specified in
2783 @code{tramp-persistency-file-name}.  Keep this file.
2785 Disable version control.  If you access remote files which are not
2786 under version control, a lot of check operations can be avoided by
2787 disabling VC.  This can be achieved by
2789 @lisp
2790 (setq vc-ignore-dir-regexp
2791       (format "\\(%s\\)\\|\\(%s\\)"
2792               vc-ignore-dir-regexp
2793               tramp-file-name-regexp))
2794 @end lisp
2796 Disable excessive traces.  The default trace level of @value{tramp},
2797 defined in the variable @code{tramp-verbose}, is 3.  You should
2798 increase this level only temporarily, hunting bugs.
2801 @item
2802 @value{tramp} does not connect to the remote host
2804 When @value{tramp} does not connect to the remote host, there are three
2805 reasons heading the bug mailing list:
2807 @itemize @minus
2809 @item
2810 Unknown characters in the prompt
2812 @value{tramp} needs to recognize the prompt on the remote machine
2813 after execution any command.  This is not possible, when the prompt
2814 contains unknown characters like escape sequences for coloring.  This
2815 should be avoided on the remote side.  @xref{Remote shell setup}. for
2816 setting the regular expression detecting the prompt.
2818 You can check your settings after an unsuccessful connection by
2819 switching to the @value{tramp} connection buffer @file{*tramp/foo*},
2820 setting the cursor at the top of the buffer, and applying the expression
2822 @example
2823 @kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))}
2824 @end example
2826 If it fails, or the cursor is not moved at the end of the buffer, your
2827 prompt is not recognized correctly.
2829 A special problem is the zsh, which uses left-hand side and right-hand
2830 side prompts in parallel.  Therefore, it is necessary to disable the
2831 zsh line editor on the remote host.  You shall add to @file{~/.zshrc}
2832 the following command:
2834 @example
2835 [ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
2836 @end example
2838 @item
2839 Echoed characters after login
2841 When the remote machine opens an echoing shell, there might be control
2842 characters in the welcome message.  @value{tramp} tries to suppress
2843 such echoes via the @code{stty -echo} command, but sometimes this
2844 command is not reached, because the echoed output has confused
2845 @value{tramp} already.  In such situations it might be helpful to use
2846 the @option{sshx} or @option{scpx} methods, which allocate a pseudo tty.
2847 @xref{Inline methods}.
2849 @item
2850 @value{tramp} doesn't transfer strings with more than 500 characters
2851 correctly
2853 On some few systems, the implementation of @code{process-send-string}
2854 seems to be broken for longer strings.  It is reported for HP-UX,
2855 FreeBSD and Tru64 Unix, for example.  This case, you should customize
2856 the variable @code{tramp-chunksize} to 500.  For a description how to
2857 determine whether this is necessary see the documentation of
2858 @code{tramp-chunksize}.
2860 Additionally, it will be useful to set @code{file-precious-flag} to
2861 @code{t} for @value{tramp} files.  Then the file contents will be
2862 written into a temporary file first, which is checked for correct
2863 checksum.
2864 @ifinfo
2865 @pxref{Saving Buffers, , , elisp}
2866 @end ifinfo
2868 @lisp
2869 (add-hook
2870  'find-file-hooks
2871  '(lambda ()
2872     (when (file-remote-p default-directory)
2873       (set (make-local-variable 'file-precious-flag) t))))
2874 @end lisp
2876 @end itemize
2879 @item
2880 @value{tramp} does not recognize hung @command{ssh} sessions
2882 When your network connection is down, @command{ssh} sessions might
2883 hang.  @value{tramp} cannot detect it safely, because it still sees a
2884 running @command{ssh} process.  Timeouts cannot be used as well,
2885 because it cannot be predicted, how long a remote command will last,
2886 for example when copying very large files.
2888 Therefore, you must configure the @command{ssh} process to die
2889 in such a case.  The following entry in @file{~/.ssh/config} would do
2890 the job:
2892 @example
2893 Host *
2894      ServerAliveInterval 5
2895 @end example
2898 @item
2899 File name completion does not work with @value{tramp}
2901 When you log in to the remote machine, do you see the output of
2902 @command{ls} in color? If so, this may be the cause of your problems.
2904 @command{ls} outputs @acronym{ANSI} escape sequences that your terminal
2905 emulator interprets to set the colors.  These escape sequences will
2906 confuse @value{tramp} however.
2908 In your @file{.bashrc}, @file{.profile} or equivalent on the remote
2909 machine you probably have an alias configured that adds the option
2910 @option{--color=yes} or @option{--color=auto}.
2912 You should remove that alias and ensure that a new login @emph{does not}
2913 display the output of @command{ls} in color.  If you still cannot use
2914 filename completion, report a bug to the @value{tramp} developers.
2917 @item
2918 File name completion does not work in large directories
2920 @value{tramp} uses globbing for some operations.  (Globbing means to use the
2921 shell to expand wildcards such as `*.c'.)  This might create long
2922 command lines, especially in directories with many files.  Some shells
2923 choke on long command lines, or don't cope well with the globbing
2924 itself.
2926 If you have a large directory on the remote end, you may wish to execute
2927 a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs.
2928 Note that you must first start the right shell, which might be
2929 @command{/bin/sh}, @command{ksh} or @command{bash}, depending on which
2930 of those supports tilde expansion.
2933 @item
2934 How can I get notified when @value{tramp} file transfers are complete?
2936 The following snippet can be put in your @file{~/.emacs} file.  It
2937 makes @value{emacsname} beep after reading from or writing to the
2938 remote host.
2940 @lisp
2941 (defadvice tramp-handle-write-region
2942   (after tramp-write-beep-advice activate)
2943   "Make tramp beep after writing a file."
2944   (interactive)
2945   (beep))
2947 (defadvice tramp-handle-do-copy-or-rename-file
2948   (after tramp-copy-beep-advice activate)
2949   "Make tramp beep after copying a file."
2950   (interactive)
2951   (beep))
2953 (defadvice tramp-handle-insert-file-contents
2954   (after tramp-insert-beep-advice activate)
2955   "Make tramp beep after inserting a file."
2956   (interactive)
2957   (beep))
2958 @end lisp
2961 @ifset emacs
2962 @item
2963 I'ld like to get a Visual Warning when working in a sudo:ed context
2965 When you are working with @samp{root} privileges, it might be useful
2966 to get an indication in the buffer's modeline.  The following code,
2967 tested with @value{emacsname} 22.1, does the job.  You should put it
2968 into your @file{~/.emacs}:
2970 @lisp
2971 (defun my-mode-line-function ()
2972   (when (string-match "^/su\\(do\\)?:" default-directory)
2973     (setq mode-line-format
2974           (format-mode-line mode-line-format 'font-lock-warning-face))))
2976 (add-hook 'find-file-hooks 'my-mode-line-function)
2977 (add-hook 'dired-mode-hook 'my-mode-line-function)
2978 @end lisp
2979 @end ifset
2982 @ifset emacs
2983 @item
2984 I'ld like to see a host indication in the mode line when I'm remote
2986 The following code has been tested with @value{emacsname} 22.1.  You
2987 should put it into your @file{~/.emacs}:
2989 @lisp
2990 (defconst my-mode-line-buffer-identification
2991   (list
2992    '(:eval
2993      (let ((host-name
2994             (if (file-remote-p default-directory)
2995                 (tramp-file-name-host
2996                  (tramp-dissect-file-name default-directory))
2997               (system-name))))
2998        (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
2999            (substring host-name 0 (match-beginning 1))
3000          host-name)))
3001    ": %12b"))
3003 (setq-default
3004  mode-line-buffer-identification
3005  my-mode-line-buffer-identification)
3007 (add-hook
3008  'dired-mode-hook
3009  '(lambda ()
3010     (setq
3011      mode-line-buffer-identification
3012      my-mode-line-buffer-identification)))
3013 @end lisp
3015 Since @value{emacsname} 23.1, the mode line contains an indication if
3016 @code{default-directory} for the current buffer is on a remote host.
3017 The corresponding tooltip includes the name of that host.  If you
3018 still want the host name as part of the mode line, you can use the
3019 example above, but the @code{:eval} clause can be simplified:
3021 @lisp
3022    '(:eval
3023      (let ((host-name
3024             (or (file-remote-p default-directory 'host)
3025                 (system-name))))
3026        (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
3027            (substring host-name 0 (match-beginning 1))
3028          host-name)))
3029 @end lisp
3030 @end ifset
3033 @ifset emacs
3034 @item
3035 My remote host does not understand default directory listing options
3037 @value{emacsname} computes the @command{dired} options depending on
3038 the local host you are working.  If your @command{ls} command on the
3039 remote host does not understand those options, you can change them
3040 like this:
3042 @lisp
3043 (add-hook
3044  'dired-before-readin-hook
3045  '(lambda ()
3046     (when (file-remote-p default-directory)
3047       (setq dired-actual-switches "-al"))))
3048 @end lisp
3049 @end ifset
3052 @item
3053 There's this @file{~/.sh_history} file on the remote host which keeps
3054 growing and growing.  What's that?
3056 Sometimes, @value{tramp} starts @command{ksh} on the remote host for
3057 tilde expansion.  Maybe @command{ksh} saves the history by default.
3058 @value{tramp} tries to turn off saving the history, but maybe you have
3059 to help.  For example, you could put this in your @file{.kshrc}:
3061 @example
3062 if [ -f $HOME/.sh_history ] ; then
3063    /bin/rm $HOME/.sh_history
3065 if [ "$@{HISTFILE-unset@}" != "unset" ] ; then
3066    unset HISTFILE
3068 if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then
3069    unset HISTSIZE
3071 @end example
3074 @item There are longish file names to type.  How to shorten this?
3076 Let's say you need regularly access to @file{@trampfn{ssh, news,
3077 news.my.domain, /opt/news/etc}}, which is boring to type again and
3078 again.  The following approaches can be mixed:
3080 @enumerate
3082 @item Use default values for method and user name:
3084 You can define default methods and user names for hosts,
3085 (@pxref{Default Method}, @pxref{Default User}):
3087 @lisp
3088 (setq tramp-default-method "ssh"
3089       tramp-default-user "news")
3090 @end lisp
3092 The file name left to type would be
3093 @kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
3095 Note, that there are some useful settings already.  Accessing your
3096 local host as @samp{root} user, is possible just by @kbd{C-x C-f
3097 @trampfn{su, , ,}}.
3099 @item Use configuration possibilities of your method:
3101 Several connection methods (i.e. the programs used) offer powerful
3102 configuration possibilities (@pxref{Customizing Completion}).  In the
3103 given case, this could be @file{~/.ssh/config}:
3105 @example
3106 Host xy
3107      HostName news.my.domain
3108      User news
3109 @end example
3111 The file name left to type would be @kbd{C-x C-f @trampfn{ssh, , xy,
3112 /opt/news/etc}}.  Depending on files in your directories, it is even
3113 possible to complete the host name with @kbd{C-x C-f
3114 @value{prefix}ssh@value{postfixhop}x @key{TAB}}.
3116 @item Use environment variables:
3118 File names typed in the minibuffer can be expanded by environment
3119 variables.  You can set them outside @value{emacsname}, or even with
3120 Lisp:
3122 @lisp
3123 (setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")
3124 @end lisp
3126 Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you
3127 are.  The disadvantage is, that you cannot edit the file name, because
3128 environment variables are not expanded during editing in the
3129 minibuffer.
3131 @item Define own keys:
3133 You can define your own key sequences in @value{emacsname}, which can
3134 be used instead of @kbd{C-x C-f}:
3136 @lisp
3137 (global-set-key
3138  [(control x) (control y)]
3139  (lambda ()
3140    (interactive)
3141    (find-file
3142     (read-file-name
3143      "Find Tramp file: "
3144      "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))))
3145 @end lisp
3147 Simply typing @kbd{C-x C-y} would initialize the minibuffer for
3148 editing with your beloved file name.
3150 See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the
3151 Emacs Wiki} for a more comprehensive example.
3153 @item Define own abbreviation (1):
3155 It is possible to define an own abbreviation list for expanding file
3156 names:
3158 @lisp
3159 (add-to-list
3160  'directory-abbrev-alist
3161  '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
3162 @end lisp
3164 This shortens the file openening command to @kbd{C-x C-f /xy
3165 @key{RET}}.  The disadvantage is, again, that you cannot edit the file
3166 name, because the expansion happens after entering the file name only.
3168 @item Define own abbreviation (2):
3170 The @code{abbrev-mode} gives more flexibility for editing the
3171 minibuffer:
3173 @lisp
3174 (define-abbrev-table 'my-tramp-abbrev-table
3175   '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))
3177 (add-hook
3178  'minibuffer-setup-hook
3179  '(lambda ()
3180     (abbrev-mode 1)
3181     (setq local-abbrev-table my-tramp-abbrev-table)))
3183 (defadvice minibuffer-complete
3184   (before my-minibuffer-complete activate)
3185   (expand-abbrev))
3187 ;; If you use partial-completion-mode
3188 (defadvice PC-do-completion
3189   (before my-PC-do-completion activate)
3190   (expand-abbrev))
3191 @end lisp
3193 After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is
3194 expanded, and you can continue editing.
3196 @item Use bookmarks:
3198 Bookmarks can be used to visit Tramp files or directories.
3199 @ifinfo
3200 @pxref{Bookmarks, , , @value{emacsdir}}
3201 @end ifinfo
3203 When you have opened @file{@trampfn{ssh, news, news.my.domain,
3204 /opt/news/etc/}}, you should save the bookmark via
3205 @ifset emacs
3206 @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}.
3207 @end ifset
3208 @ifset xemacs
3209 @kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}.
3210 @end ifset
3212 Later on, you can always navigate to that bookmark via
3213 @ifset emacs
3214 @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}.
3215 @end ifset
3216 @ifset xemacs
3217 @kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}.
3218 @end ifset
3220 @item Use recent files:
3222 @ifset emacs
3223 @file{recentf}
3224 @end ifset
3225 @ifset xemacs
3226 @file{recent-files}
3227 @end ifset
3228 remembers visited places.
3229 @ifinfo
3230 @ifset emacs
3231 @pxref{File Conveniences, , , @value{emacsdir}}
3232 @end ifset
3233 @ifset xemacs
3234 @pxref{recent-files, , , edit-utils}
3235 @end ifset
3236 @end ifinfo
3238 You could keep remote file names in the recent list without checking
3239 their readability through a remote access:
3241 @lisp
3242 @ifset emacs
3243 (recentf-mode 1)
3244 @end ifset
3245 @ifset xemacs
3246 (recent-files-initialize)
3247 (add-hook
3248  'find-file-hooks
3249  (lambda ()
3250    (when (file-remote-p (buffer-file-name))
3251      (recent-files-make-permanent)))
3252  'append)
3253 @end ifset
3254 @end lisp
3256 The list of files opened recently is reachable via
3257 @ifset emacs
3258 @kbd{@key{menu-bar} @key{file} @key{Open Recent}}.
3259 @end ifset
3260 @ifset xemacs
3261 @kbd{@key{menu-bar} @key{Recent Files}}.
3262 @end ifset
3264 @ifset emacs
3265 @item Use filecache:
3267 @file{filecache} remembers visited places.  Add the directory into
3268 the cache:
3270 @lisp
3271 (eval-after-load "filecache"
3272   '(file-cache-add-directory
3273     "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
3274 @end lisp
3276 Whenever you want to load a file, you can enter @kbd{C-x C-f
3277 C-@key{TAB}} in the minibuffer.  The completion is done for the given
3278 directory.
3279 @end ifset
3281 @ifset emacs
3282 @item Use bbdb:
3284 @file{bbdb} has a built-in feature for @value{ftppackagename} files,
3285 which works also for @value{tramp}.
3286 @ifinfo
3287 @pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb}
3288 @end ifinfo
3290 You need to load @file{bbdb}:
3292 @lisp
3293 (require 'bbdb)
3294 (bbdb-initialize)
3295 @end lisp
3297 Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}.
3298 Because BBDB is not prepared for @value{tramp} syntax, you must
3299 specify a method together with the user name, when needed. Example:
3301 @example
3302 @kbd{M-x bbdb-create-ftp-site @key{RET}}
3303 @b{Ftp Site:} news.my.domain @key{RET}
3304 @b{Ftp Directory:} /opt/news/etc/ @key{RET}
3305 @b{Ftp Username:} ssh@value{postfixhop}news @key{RET}
3306 @b{Company:} @key{RET}
3307 @b{Additional Comments:} @key{RET}
3308 @end example
3310 When you have opened your BBDB buffer, you can access such an entry by
3311 pressing the key @key{F}.
3312 @end ifset
3314 @end enumerate
3316 I would like to thank all @value{tramp} users, who have contributed to
3317 the different recipes!
3320 @ifset emacs
3321 @item
3322 How can I use @value{tramp} to connect to a remote @value{emacsname}
3323 session?
3325 You can configure Emacs Client doing this.
3326 @ifinfo
3327 @xref{Emacs Server, , , @value{emacsdir}}.
3328 @end ifinfo
3330 On the remote host, you start the Emacs Server:
3332 @lisp
3333 (require 'server)
3334 (setq server-host (system-name)
3335       server-use-tcp t)
3336 (server-start)
3337 @end lisp
3339 Make sure, that the result of @code{(system-name)} can be resolved on
3340 your local host; otherwise you might use a hard coded IP address.
3342 The resulting file @file{~/.emacs.d/server/server} must be copied to
3343 your local host, at the same location.  You can call then the Emacs
3344 Client from the command line:
3346 @example
3347 emacsclient @trampfn{ssh, user, host, /file/to/edit}
3348 @end example
3350 @code{user} and @code{host} shall be related to your local host.
3352 If you want to use Emacs Client also as editor for other programs, you
3353 could write a script @file{emacsclient.sh}:
3355 @example
3356 #!/bin/sh
3357 emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1}
3358 @end example
3360 Then you must set the environment variable @code{EDITOR} pointing to
3361 that script:
3363 @example
3364 export EDITOR=/path/to/emacsclient.sh
3365 @end example
3366 @end ifset
3369 @item
3370 How can I disable @value{tramp}?
3372 Shame on you, why did you read until now?
3374 @itemize @minus
3376 @item
3377 @ifset emacs
3378 If you just want to have @value{ftppackagename} as default remote
3379 files access package, you should apply the following code:
3381 @lisp
3382 (setq tramp-default-method "ftp")
3383 @end lisp
3384 @end ifset
3386 @item
3387 In order to disable
3388 @ifset emacs
3389 @value{tramp} (and @value{ftppackagename}),
3390 @end ifset
3391 @ifset xemacs
3392 @value{tramp},
3393 @end ifset
3394 you must set @code{tramp-mode} to @code{nil}:
3396 @lisp
3397 (setq tramp-mode nil)
3398 @end lisp
3400 @item
3401 Unloading @value{tramp} can be achieved by applying @kbd{M-x
3402 tramp-unload-tramp}.
3403 @ifset emacs
3404 This resets also the @value{ftppackagename} plugins.
3405 @end ifset
3406 @end itemize
3407 @end itemize
3410 @c For the developer
3411 @node Files directories and localnames
3412 @chapter How file names, directories and localnames are mangled and managed.
3414 @menu
3415 * Localname deconstruction::    Breaking a localname into its components.
3416 @ifset emacs
3417 * External packages::           Integration with external Lisp packages.
3418 @end ifset
3419 @end menu
3422 @node Localname deconstruction
3423 @section Breaking a localname into its components.
3425 @value{tramp} file names are somewhat different, obviously, to ordinary file
3426 names.  As such, the lisp functions @code{file-name-directory} and
3427 @code{file-name-nondirectory} are overridden within the @value{tramp}
3428 package.
3430 Their replacements are reasonably simplistic in their approach.  They
3431 dissect the filename, call the original handler on the localname and
3432 then rebuild the @value{tramp} file name with the result.
3434 This allows the platform specific hacks in the original handlers to take
3435 effect while preserving the @value{tramp} file name information.
3438 @ifset emacs
3439 @node External packages
3440 @section Integration with external Lisp packages.
3441 @subsection Filename completion.
3443 While reading filenames in the minibuffer, @value{tramp} must decide
3444 whether it completes possible incomplete filenames, or not.  Imagine
3445 there is the following situation: You have typed @kbd{C-x C-f
3446 @value{prefix}ssh@value{postfixhop} @key{TAB}}.  @value{tramp} cannot
3447 know, whether @option{ssh} is a method or a host name.  It checks
3448 therefore the last input character you have typed.  If this is
3449 @key{TAB}, @key{SPACE} or @kbd{?}, @value{tramp} assumes that you are
3450 still in filename completion, and it does not connect to the possible
3451 remote host @option{ssh}.
3453 @vindex tramp-completion-mode
3454 External packages, which use other characters for completing filenames
3455 in the minibuffer, must signal this to @value{tramp}.  For this case,
3456 the variable @code{tramp-completion-mode} can be bound temporarily to
3457 a non-@code{nil} value.
3459 @lisp
3460 (let ((tramp-completion-mode t))
3461   ...)
3462 @end lisp
3465 @subsection File attributes cache.
3467 When @value{tramp} runs remote processes, files on the remote host
3468 could change their attributes.  Consequently, @value{tramp} must flush
3469 its complete cache keeping attributes for all files of the remote host
3470 it has seen so far.
3472 This is a performance degradation, because the lost file attributes
3473 must be recomputed, when needed again.  In cases the caller of
3474 @code{process-file} knows that there are no file attribute changes, it
3475 shall let-bind the variable @code{process-file-side-effects} to
3476 @code{nil}.  @value{tramp} wouldn't flush the file attributes cache then.
3478 @lisp
3479 (let (process-file-side-effects)
3480   ...)
3481 @end lisp
3483 For asynchronous processes, @value{tramp} flushes the file attributes
3484 cache via a process sentinel.  If the caller of
3485 @code{start-file-process} knows that there are no file attribute
3486 changes, it shall set the process sentinel to @code{nil}.  In case the
3487 caller defines an own process sentinel, @value{tramp}'s process
3488 sentinel is overwritten.  The caller can still flush the file
3489 attributes cache in its process sentinel with this code:
3491 @lisp
3492 (unless (memq (process-status proc) '(run open))
3493   (dired-uncache remote-directory))
3494 @end lisp
3496 @code{remote-directory} shall be the root directory, where file
3497 attribute changes can happen during the process lifetime.
3498 @value{tramp} traverses all subdirectories, starting at this
3499 directory.  Often, it is sufficient to use @code{default-directory} of
3500 the process buffer as root directory.
3501 @end ifset
3504 @node Traces and Profiles
3505 @chapter How to Customize Traces
3507 All @value{tramp} messages are raised with a verbosity level.  The
3508 verbosity level can be any number between 0 and 10.  Only messages with
3509 a verbosity level less than or equal to @code{tramp-verbose} are
3510 displayed.
3512 The verbosity levels are
3514           @w{ 0}  silent (no @value{tramp} messages at all)
3515 @*@indent @w{ 1}  errors
3516 @*@indent @w{ 2}  warnings
3517 @*@indent @w{ 3}  connection to remote hosts (default verbosity)
3518 @*@indent @w{ 4}  activities
3519 @*@indent @w{ 5}  internal
3520 @*@indent @w{ 6}  sent and received strings
3521 @*@indent @w{ 7}  file caching
3522 @*@indent @w{ 8}  connection properties
3523 @*@indent @w{ 9}  test commands
3524 @*@indent @w{10}  traces (huge)
3526 When @code{tramp-verbose} is greater than or equal to 4, the messages
3527 are also written into a @value{tramp} debug buffer.  This debug buffer
3528 is useful for analysing problems; sending a @value{tramp} bug report
3529 should be done with @code{tramp-verbose} set to a verbosity level of at
3530 least 6 (@pxref{Bug Reports}).
3532 The debug buffer is in
3533 @ifinfo
3534 @ref{Outline Mode, , , @value{emacsdir}}.
3535 @end ifinfo
3536 @ifnotinfo
3537 Outline Mode.
3538 @end ifnotinfo
3539 That means, you can change the level of messages to be viewed.  If you
3540 want, for example, see only messages up to verbosity level 5, you must
3541 enter @kbd{C-u 6 C-c C-q}.
3542 @ifinfo
3543 Other keys for navigating are described in
3544 @ref{Outline Visibility, , , @value{emacsdir}}.
3545 @end ifinfo
3547 @value{tramp} errors are handled internally in order to raise the
3548 verbosity level 1 messages.  When you want to get a Lisp backtrace in
3549 case of an error, you need to set both
3551 @lisp
3552 (setq debug-on-error t
3553       debug-on-signal t)
3554 @end lisp
3556 Sometimes, it might be even necessary to step through @value{tramp}
3557 function call traces.  Such traces are enabled by the following code:
3559 @lisp
3560 (require 'tramp)
3561 (require 'trace)
3562 (dolist (elt (all-completions "tramp-" obarray 'functionp))
3563   (trace-function-background (intern elt)))
3564 (untrace-function 'tramp-read-passwd)
3565 (untrace-function 'tramp-gw-basic-authentication)
3566 @end lisp
3568 The function call traces are inserted in the buffer
3569 @file{*trace-output*}.  @code{tramp-read-passwd} and
3570 @code{tramp-gw-basic-authentication} shall be disabled when the
3571 function call traces are added to @value{tramp}, because both
3572 functions return password strings, which should not be distributed.
3575 @node Issues
3576 @chapter Debatable Issues and What Was Decided
3578 @itemize @bullet
3579 @item The uuencode method does not always work.
3581 Due to the design of @value{tramp}, the encoding and decoding programs
3582 need to read from stdin and write to stdout.  On some systems,
3583 @command{uudecode -o -} will read stdin and write the decoded file to
3584 stdout, on other systems @command{uudecode -p} does the same thing.
3585 But some systems have uudecode implementations which cannot do this at
3586 all---it is not possible to call these uudecode implementations with
3587 suitable parameters so that they write to stdout.
3589 Of course, this could be circumvented: the @code{begin foo 644} line
3590 could be rewritten to put in some temporary file name, then
3591 @command{uudecode} could be called, then the temp file could be
3592 printed and deleted.
3594 But I have decided that this is too fragile to reliably work, so on some
3595 systems you'll have to do without the uuencode methods.
3597 @item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs.
3599 The GNU Emacs maintainers wish to use a unified filename syntax for
3600 Ange-FTP and @value{tramp} so that users don't have to learn a new
3601 syntax.  It is sufficient to learn some extensions to the old syntax.
3603 For the XEmacs maintainers, the problems caused from using a unified
3604 filename syntax are greater than the gains.  The XEmacs package system
3605 uses EFS for downloading new packages.  So, obviously, EFS has to be
3606 installed from the start.  If the filenames were unified, @value{tramp}
3607 would have to be installed from the start, too.
3609 @ifset xemacs
3610 @strong{Note:} If you'd like to use a similar syntax like
3611 @value{ftppackagename}, you need the following settings in your init
3612 file:
3614 @lisp
3615 (setq tramp-unified-filenames t)
3616 (require 'tramp)
3617 @end lisp
3619 The autoload of the @value{emacsname} @value{tramp} package must be
3620 disabled.  This can be achieved by setting file permissions @code{000}
3621 to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}.
3623 In case of unified filenames, all @value{emacsname} download sites are
3624 added to @code{tramp-default-method-alist} with default method
3625 @option{ftp} @xref{Default Method}.  These settings shouldn't be
3626 touched for proper working of the @value{emacsname} package system.
3628 The syntax for unified filenames is described in the @value{tramp} manual
3629 for @value{emacsothername}.
3630 @end ifset
3631 @end itemize
3633 @node GNU Free Documentation License
3634 @appendix GNU Free Documentation License
3635 @include doclicense.texi
3637 @node Function Index
3638 @unnumbered Function Index
3639 @printindex fn
3641 @node Variable Index
3642 @unnumbered Variable Index
3643 @printindex vr
3645 @node Concept Index
3646 @unnumbered Concept Index
3647 @printindex cp
3649 @bye
3651 @c TODO
3653 @c * Say something about the .login and .profile files of the remote
3654 @c   shells.
3655 @c * Explain how tramp.el works in principle: open a shell on a remote
3656 @c   host and then send commands to it.
3657 @c * Use `filename' resp. `file name' consistently.
3658 @c * Use `host' resp. `machine' consistently.
3659 @c * Consistent small or capitalized words especially in menues.
3661 @ignore
3662    arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808
3663 @end ignore