1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/tramp
4 @settitle TRAMP User Manual
8 @c This is *so* much nicer :)
11 @c In the Tramp CVS, the version number is auto-frobbed from
12 @c configure.ac, so you should edit that file and run
13 @c "autoconf && ./configure" to change the version number.
15 @c Additionally, flags are set with respect to the Emacs flavor; and
16 @c depending whether Tramp is packaged into (X)Emacs, or standalone.
18 @include trampver.texi
20 @c Macro for formatting a filename according to the repective syntax.
21 @c xxx and yyy are auxiliary macros in order to omit leading and
22 @c trailing whitespace. Not very elegant, but I don't know it better.
28 @macro yyy {one, two}@c
36 @macro trampfn {method, user, host, localname}@c
37 @value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
41 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
42 2007 Free Software Foundation, Inc.
45 Permission is granted to copy, distribute and/or modify this document
46 under the terms of the GNU Free Documentation License, Version 1.2 or
47 any later version published by the Free Software Foundation; with no
48 Invariant Sections, with the Front-Cover texts being ``A GNU
49 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
50 license is included in the section entitled ``GNU Free Documentation
51 License'' in the Emacs manual.
53 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
54 this GNU Manual, like GNU software. Copies published by the Free
55 Software Foundation raise funds for GNU development.''
57 This document is part of a collection distributed under the GNU Free
58 Documentation License. If you want to distribute this document
59 separately from the collection, you can do so by adding a copy of the
60 license to the document, as described in section 6 of the license.
64 @c Entries for @command{install-info} to use
65 @dircategory @value{emacsname}
67 * TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
68 @value{emacsname} remote file access via rsh and rcp.
74 @title @value{tramp} version @value{trampver} User Manual
76 @author by Daniel Pittman
77 @author based on documentation by Kai Gro@ss{}johann
88 @node Top, Overview, (dir), (dir)
89 @top @value{tramp} version @value{trampver} User Manual
91 This file documents @value{tramp} version @value{trampver}, a remote file
92 editing package for @value{emacsname}.
94 @value{tramp} stands for `Transparent Remote (file) Access, Multiple
95 Protocol'. This package provides remote file editing, similar to
96 @value{ftppackagename}.
98 The difference is that @value{ftppackagename} uses FTP to transfer
99 files between the local and the remote host, whereas @value{tramp} uses a
100 combination of @command{rsh} and @command{rcp} or other work-alike
101 programs, such as @command{ssh}/@command{scp}.
103 You can find the latest version of this document on the web at
104 @uref{http://www.gnu.org/software/tramp/}.
106 @c Pointer to the other Emacs flavor is necessary only in case of
107 @c standalone installation.
108 @ifset installchapter
109 The manual has been generated for @value{emacsname}.
111 If you want to read the info pages for @value{emacsothername}, you
112 should read in @ref{Installation} how to create them.
115 If you're using the other Emacs flavor, you should read the
116 @uref{@value{emacsotherfilename}, @value{emacsothername}} pages.
122 This manual is also available as a @uref{@value{japanesemanual},
123 Japanese translation}.
126 The latest release of @value{tramp} is available for
127 @uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
128 @ref{Obtaining Tramp} for more details, including the CVS server
131 @value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/,
132 Savannah Project Page}.
135 There is a mailing list for @value{tramp}, available at
136 @email{tramp-devel@@gnu.org}, and archived at
137 @uref{http://lists.gnu.org/archive/html/tramp-devel/, the
138 @value{tramp} Mail Archive}.
140 Older archives are located at
141 @uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel,
142 SourceForge Mail Archive} and
143 @uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/,
145 @c in HTML output, there's no new paragraph.
154 * Overview:: What @value{tramp} can and cannot do.
158 * Obtaining Tramp:: How to obtain @value{tramp}.
159 * History:: History of @value{tramp}.
160 @ifset installchapter
161 * Installation:: Installing @value{tramp} with your @value{emacsname}.
163 * Configuration:: Configuring @value{tramp} for use.
164 * Usage:: An overview of the operation of @value{tramp}.
165 * Bug Reports:: Reporting Bugs and Problems.
166 * Frequently Asked Questions:: Questions and answers from the mailing list.
167 * Concept Index:: An item for each concept.
171 * Version Control:: The inner workings of remote version control.
172 * Files directories and localnames:: How file names, directories and localnames are mangled and managed.
173 * Traces and Profiles:: How to Customize Traces.
174 * Issues:: Debatable Issues and What Was Decided.
176 * GNU Free Documentation License:: The license for this documentation.
179 --- The Detailed Node Listing ---
181 @ifset installchapter
182 Installing @value{tramp} with your @value{emacsname}
184 * Installation parameters:: Parameters in order to control installation.
185 * Load paths:: How to plug-in @value{tramp} into your environment.
186 * Japanese manual:: Japanese manual.
190 Configuring @value{tramp} for use
192 * Connection types:: Types of connections made to remote machines.
193 * Inline methods:: Inline methods.
194 * External transfer methods:: External transfer methods.
196 * Gateway methods:: Gateway methods.
198 * Default Method:: Selecting a default method.
199 * Default User:: Selecting a default user.
200 * Default Host:: Selecting a default host.
201 * Multi-hops:: Connecting to a remote host using multiple hops.
202 * Customizing Methods:: Using Non-Standard Methods.
203 * Customizing Completion:: Selecting config files for user/host name completion.
204 * Password caching:: Reusing passwords for several connections.
205 * Connection caching:: Reusing connection related information.
206 * Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
207 * Remote shell setup:: Remote shell setup hints.
208 * Windows setup hints:: Issues with Cygwin ssh.
209 * Auto-save and Backup:: Auto-save and Backup.
213 * Filename Syntax:: @value{tramp} filename conventions.
214 * Alternative Syntax:: URL-like filename syntax.
215 * Filename completion:: Filename completion.
216 * Remote processes:: Integration with other @value{emacsname} packages.
218 The inner workings of remote version control
220 * Version Controlled Files:: Determining if a file is under version control.
221 * Remote Commands:: Executing the version control commands on the remote machine.
222 * Changed workfiles:: Detecting if the working file has changed.
223 * Checking out files:: Bringing the workfile out of the repository.
224 * Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
226 Things related to Version Control that don't fit elsewhere
228 * Remote File Ownership:: How VC determines who owns a workfile.
229 * Back-end Versions:: How VC determines what release your RCS is.
231 How file names, directories and localnames are mangled and managed
233 * Localname deconstruction:: Breaking a localname into its components.
235 * External packages:: Integration with external Lisp packages.
242 @chapter An overview of @value{tramp}
245 After the installation of @value{tramp} into your @value{emacsname}, you
246 will be able to access files on remote machines as though they were
247 local. Access to the remote file system for editing files, version
248 control, and @code{dired} are transparently enabled.
250 Your access to the remote machine can be with the @command{rsh},
251 @command{rlogin}, @command{telnet} programs or with any similar
252 connection method. This connection must pass @acronym{ASCII}
253 successfully to be usable but need not be 8-bit clean.
255 The package provides support for @command{ssh} connections out of the
256 box, one of the more common uses of the package. This allows
257 relatively secure access to machines, especially if @command{ftp}
260 The majority of activity carried out by @value{tramp} requires only that
261 the remote login is possible and is carried out at the terminal. In
262 order to access remote files @value{tramp} needs to transfer their content
263 to the local machine temporarily.
265 @value{tramp} can transfer files between the machines in a variety of ways.
266 The details are easy to select, depending on your needs and the
267 machines in question.
269 The fastest transfer methods (for large files) rely on a remote file
270 transfer package such as @command{rcp}, @command{scp} or
273 If the remote copy methods are not suitable for you, @value{tramp} also
274 supports the use of encoded transfers directly through the shell.
275 This requires that the @command{mimencode} or @command{uuencode} tools
276 are available on the remote machine. These methods are generally
277 faster for small files.
279 Within these limitations, @value{tramp} is quite powerful. It is worth
280 noting that, as of the time of writing, it is far from a polished
281 end-user product. For a while yet you should expect to run into rough
282 edges and problems with the code now and then.
284 It is finished enough that the developers use it for day to day work but
285 the installation and setup can be a little difficult to master, as can
288 @value{tramp} is still under active development and any problems you encounter,
289 trivial or major, should be reported to the @value{tramp} developers.
293 @subsubheading Behind the scenes
294 @cindex behind the scenes
295 @cindex details of operation
298 This section tries to explain what goes on behind the scenes when you
299 access a remote file through @value{tramp}.
301 Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name,
302 then hit @kbd{@key{TAB}} for completion. Suppose further that this is
303 the first time that @value{tramp} is invoked for the host in question. Here's
308 @value{tramp} discovers that it needs a connection to the host. So it
309 invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
310 @var{user}} or a similar tool to connect to the remote host.
311 Communication with this process happens through an
312 @value{emacsname} buffer, that is, the output from the remote end
316 The remote host may prompt for a login name (for @command{telnet}).
317 The login name is given in the file name, so @value{tramp} sends the
318 login name and a newline.
321 The remote host may prompt for a password or pass phrase (for
322 @command{rsh} or for @command{telnet} after sending the login name).
323 @value{tramp} displays the prompt in the minibuffer, asking you for the
324 password or pass phrase.
326 You enter the password or pass phrase. @value{tramp} sends it to the remote
327 host, followed by a newline.
330 @value{tramp} now waits for the shell prompt or for a message that the login
333 If @value{tramp} sees neither of them after a certain period of time (a minute,
334 say), then it issues an error message saying that it couldn't find the
335 remote shell prompt and shows you what the remote host has sent.
337 If @value{tramp} sees a @samp{login failed} message, it tells you so,
338 aborts the login attempt and allows you to try again.
341 Suppose that the login was successful and @value{tramp} sees the shell prompt
342 from the remote host. Now @value{tramp} invokes @command{/bin/sh} because
343 Bourne shells and C shells have different command
344 syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login
345 shell doesn't recognize @samp{exec /bin/sh} as a valid command.
346 Maybe you use the Scheme shell @command{scsh}@dots{}}
348 After the Bourne shell has come up, @value{tramp} sends a few commands to
349 ensure a good working environment. It turns off echoing, it sets the
350 shell prompt, and a few other things.
353 Now the remote shell is up and it good working order. Remember, what
354 was supposed to happen is that @value{tramp} tries to find out what files exist
355 on the remote host so that it can do filename completion.
357 So, @value{tramp} basically issues @command{cd} and @command{ls} commands and
358 also sometimes @command{echo} with globbing. Another command that is
359 often used is @command{test} to find out whether a file is writable or a
360 directory or the like. The output of each command is parsed for the
364 Suppose you are finished with filename completion, have entered @kbd{C-x
365 C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to
366 transfer the file contents from the remote host to the local host so
367 that you can edit them.
369 See above for an explanation of how @value{tramp} transfers the file contents.
371 For inline transfers, @value{tramp} issues a command like @samp{mimencode -b
372 /path/to/remote/file}, waits until the output has accumulated in the
373 buffer that's used for communication, then decodes that output to
374 produce the file contents.
376 For out-of-band transfers, @value{tramp} issues a command like the following:
378 rcp user@@host:/path/to/remote/file /tmp/tramp.4711
380 It then reads the local temporary file @file{/tmp/tramp.4711} into a
381 buffer and deletes the temporary file.
384 You now edit the buffer contents, blithely unaware of what has happened
385 behind the scenes. (Unless you have read this section, that is.) When
386 you are finished, you type @kbd{C-x C-s} to save the buffer.
389 Again, @value{tramp} transfers the file contents to the remote host either
390 inline or out-of-band. This is the reverse of what happens when reading
394 I hope this has provided you with a basic overview of what happens
395 behind the scenes when you open a file with @value{tramp}.
399 @node Obtaining Tramp
400 @chapter Obtaining Tramp.
401 @cindex obtaining Tramp
403 @value{tramp} is freely available on the Internet and the latest
404 release may be downloaded from
405 @uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
406 documentation and code for @value{tramp}, suitable for installation.
407 But GNU Emacs (22 or later) includes @value{tramp} already, and there
408 is a @value{tramp} package for XEmacs, as well. So maybe it is easier
409 to just use those. But if you want the bleeding edge, read
412 For the especially brave, @value{tramp} is available from CVS. The CVS
413 version is the latest version of the code and may contain incomplete
414 features or new issues. Use these versions at your own risk.
416 Instructions for obtaining the latest development version of @value{tramp}
417 from CVS can be found by going to the Savannah project page at the
418 following URL and then clicking on the CVS link in the navigation bar
422 @uref{http://savannah.gnu.org/projects/tramp/}
425 Or follow the example session below:
428 ] @strong{cd ~/@value{emacsdir}}
429 ] @strong{export CVS_RSH="ssh"}
430 ] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
434 You should now have a directory @file{~/@value{emacsdir}/tramp}
435 containing the latest version of @value{tramp}. You can fetch the latest
436 updates from the repository by issuing the command:
439 ] @strong{cd ~/@value{emacsdir}/tramp}
440 ] @strong{export CVS_RSH="ssh"}
441 ] @strong{cvs update -d}
445 Once you've got updated files from the CVS repository, you need to run
446 @command{autoconf} in order to get an up-to-date @file{configure}
450 ] @strong{cd ~/@value{emacsdir}/tramp}
454 People who have no direct CVS access (maybe because sitting behind a
455 blocking firewall), can try the
456 @uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly
457 CVS Tree Tarball} instead of.
461 @chapter History of @value{tramp}
463 @cindex development history
465 Development was started end of November 1998. The package was called
466 @file{rssh.el}, back then. It only provided one method to access a
467 file, using @command{ssh} to log in to a remote host and using
468 @command{scp} to transfer the file contents. After a while, the name
469 was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way,
470 many more methods for getting a remote shell and for transferring the
471 file contents were added. Support for VC was added.
473 The most recent addition of major features were the multi-hop methods
474 added in April 2000 and the unification of @value{tramp} and Ange-FTP
475 filenames in July 2002. In July 2004, multi-hop methods have been
476 replaced by proxy hosts. Running commands on remote hosts was
477 introduced in December 2005.
479 Support of gateways exists since April 2007.
482 In December 2001, @value{tramp} has been added to the XEmacs package
483 repository. Being part of the GNU Emacs repository happened in June
484 2002, the first release including @value{tramp} was GNU Emacs 22.1.
486 @value{tramp} is also a GNU/Linux Debian package since February 2001.
489 @c Installation chapter is necessary only in case of standalone
490 @c installation. Text taken from trampinst.texi.
491 @ifset installchapter
492 @include trampinst.texi
496 @chapter Configuring @value{tramp} for use
497 @cindex configuration
499 @cindex default configuration
500 @value{tramp} is (normally) fully functional when it is initially
501 installed. It is initially configured to use the @command{scp}
502 program to connect to the remote host. So in the easiest case, you
503 just type @kbd{C-x C-f} and then enter the filename
504 @file{@trampfn{, user, machine, /path/to.file}}.
506 On some hosts, there are problems with opening a connection. These are
507 related to the behavior of the remote shell. See @xref{Remote shell
508 setup}, for details on this.
510 If you do not wish to use these commands to connect to the remote
511 host, you should change the default connection and transfer method
512 that @value{tramp} uses. There are several different methods that @value{tramp}
513 can use to connect to remote machines and transfer files
514 (@pxref{Connection types}).
516 If you don't know which method is right for you, see @xref{Default
521 * Connection types:: Types of connections made to remote machines.
522 * Inline methods:: Inline methods.
523 * External transfer methods:: External transfer methods.
525 * Gateway methods:: Gateway methods.
527 * Default Method:: Selecting a default method.
528 Here we also try to help those who
529 don't have the foggiest which method
531 * Default User:: Selecting a default user.
532 * Default Host:: Selecting a default host.
533 * Multi-hops:: Connecting to a remote host using multiple hops.
534 * Customizing Methods:: Using Non-Standard Methods.
535 * Customizing Completion:: Selecting config files for user/host name completion.
536 * Password caching:: Reusing passwords for several connections.
537 * Connection caching:: Reusing connection related information.
538 * Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
539 * Remote shell setup:: Remote shell setup hints.
540 * Windows setup hints:: Issues with Cygwin ssh.
541 * Auto-save and Backup:: Auto-save and Backup.
545 @node Connection types
546 @section Types of connections made to remote machines.
547 @cindex connection types, overview
549 There are two basic types of transfer methods, each with its own
550 advantages and limitations. Both types of connection make use of a
551 remote shell access program such as @command{rsh}, @command{ssh} or
552 @command{telnet} to connect to the remote machine.
554 This connection is used to perform many of the operations that @value{tramp}
555 requires to make the remote file system transparently accessible from
556 the local machine. It is only when visiting files that the methods
559 @cindex inline methods
560 @cindex external transfer methods
561 @cindex external methods
562 @cindex out-of-band methods
563 @cindex methods, inline
564 @cindex methods, external transfer
565 @cindex methods, out-of-band
566 Loading or saving a remote file requires that the content of the file
567 be transfered between the two machines. The content of the file can be
568 transfered over the same connection used to log in to the remote
569 machine or the file can be transfered through another connection using
570 a remote copy program such as @command{rcp}, @command{scp} or
571 @command{rsync}. The former are called @dfn{inline methods}, the
572 latter are called @dfn{out-of-band methods} or @dfn{external transfer
573 methods} (@dfn{external methods} for short).
575 The performance of the external transfer methods is generally better
576 than that of the inline methods, at least for large files. This is
577 caused by the need to encode and decode the data when transferring
580 The one exception to this rule are the @command{scp} based transfer
581 methods. While these methods do see better performance when actually
582 transferring files, the overhead of the cryptographic negotiation at
583 startup may drown out the improvement in file transfer times.
585 External transfer methods should be configured such a way that they
586 don't require a password (with @command{ssh-agent}, or such alike).
587 Modern @command{scp} implementations offer options to reuse existing
588 @command{ssh} connections, see method @command{scpc}. If it isn't
589 possible, you should consider @ref{Password caching}, otherwise you
590 will be prompted for a password every copy action.
594 @section Inline methods
595 @cindex inline methods
596 @cindex methods, inline
598 The inline methods in @value{tramp} are quite powerful and can work in
599 situations where you cannot use an external transfer program to connect.
600 Inline methods are the only methods that work when connecting to the
601 remote machine via telnet. (There are also strange inline methods which
602 allow you to transfer files between @emph{user identities} rather than
605 These methods depend on the existence of a suitable encoding and
606 decoding command on remote machine. Locally, @value{tramp} may be able to
607 use features of @value{emacsname} to decode and encode the files or
608 it may require access to external commands to perform that task.
612 @cindex base-64 encoding
613 @value{tramp} checks the availability and usability of commands like
614 @command{mimencode} (part of the @command{metamail} package) or
615 @command{uuencode} on the remote host. The first reliable command
616 will be used. The search path can be customized, see @ref{Remote
619 If both commands aren't available on the remote host, @value{tramp}
620 transfers a small piece of Perl code to the remote host, and tries to
621 apply it for encoding and decoding.
629 Connect to the remote host with @command{rsh}. Due to the unsecure
630 connection it is recommended for very local host topology only.
632 On operating systems which provide the command @command{remsh} instead
633 of @command{rsh}, you can use the method @option{remsh}. This is true
634 for HP-UX or Cray UNICOS, for example.
641 Connect to the remote host with @command{ssh}. This is identical to
642 the previous option except that the @command{ssh} package is used,
643 making the connection more secure.
645 There are also two variants, @option{ssh1} and @option{ssh2}, that
646 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
647 explicitly select whether you want to use the SSH protocol version 1
648 or 2 to connect to the remote host. (You can also specify in
649 @file{~/.ssh/config}, the SSH configuration file, which protocol
650 should be used, and use the regular @option{ssh} method.)
652 Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
653 @command{ssh1} and @command{ssh2} commands explicitly. If you don't
654 know what these are, you do not need these options.
656 All the methods based on @command{ssh} have an additional kludgy
657 feature: you can specify a host name which looks like @file{host#42}
658 (the real host name, then a hash sign, then a port number). This
659 means to connect to the given host but to also pass @code{-p 42} as
660 arguments to the @command{ssh} command.
663 @item @option{telnet}
664 @cindex method telnet
665 @cindex telnet method
667 Connect to the remote host with @command{telnet}. This is as unsecure
668 as the @option{rsh} method.
675 This method does not connect to a remote host at all, rather it uses
676 the @command{su} program to allow you to edit files as another user.
677 With other words, a specified host name in the file name is silently
685 This is similar to the @option{su} method, but it uses @command{sudo}
686 rather than @command{su} to become a different user.
688 Note that @command{sudo} must be configured to allow you to start a
689 shell as the user. It would be nice if it was sufficient if
690 @command{ls} and @command{mimencode} were allowed, but that is not
691 easy to implement, so I haven't got around to it, yet.
698 As you would expect, this is similar to @option{ssh}, only a little
699 different. Whereas @option{ssh} opens a normal interactive shell on
700 the remote host, this option uses @samp{ssh -t -t @var{host} -l
701 @var{user} /bin/sh} to open a connection. This is useful for users
702 where the normal login shell is set up to ask them a number of
703 questions when logging in. This procedure avoids these questions, and
704 just gives @value{tramp} a more-or-less `standard' login shell to work
707 Note that this procedure does not eliminate questions asked by
708 @command{ssh} itself. For example, @command{ssh} might ask ``Are you
709 sure you want to continue connecting?'' if the host key of the remote
710 host is not known. @value{tramp} does not know how to deal with such a
711 question (yet), therefore you will need to make sure that you can log
712 in without such questions.
714 This is also useful for Windows users where @command{ssh}, when
715 invoked from an @value{emacsname} buffer, tells them that it is not
716 allocating a pseudo tty. When this happens, the login shell is wont
717 to not print any shell prompt, which confuses @value{tramp} mightily.
718 For reasons unknown, some Windows ports for @command{ssh} require the
719 doubled @samp{-t} option.
721 This supports the @samp{-p} kludge.
724 @item @option{krlogin}
725 @cindex method krlogin
726 @cindex krlogin method
727 @cindex Kerberos (with krlogin method)
729 This method is also similar to @option{ssh}. It only uses the
730 @command{krlogin -x} command to log in to the remote host.
737 This method is mostly interesting for Windows users using the PuTTY
738 implementation of SSH. It uses @samp{plink -ssh} to log in to the
741 This supports the @samp{-P} kludge.
743 Additionally, the methods @option{plink1} and @option{plink2} are
744 provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in
745 order to use SSH protocol version 1 or 2 explicitly.
747 CCC: Do we have to connect to the remote host once from the command
748 line to accept the SSH key? Maybe this can be made automatic?
750 CCC: Say something about the first shell command failing. This might
751 be due to a wrong setting of @code{tramp-rsh-end-of-line}.
754 @item @option{plinkx}
755 @cindex method plinkx
756 @cindex plinkx method
758 Another method using PuTTY on Windows. Instead of host names, it
759 expects PuTTY session names, calling @samp{plink -load @var{session}
760 -t"}. User names are relevant only in case the corresponding session
761 hasn't defined a user name. Different port numbers must be defined in
769 This is an experimental implementation of the fish protocol, known from
770 the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
771 the fish server implementation from the KDE kioslave. That means, the
772 file @file{~/.fishsrv.pl} is expected to reside on the remote host.
774 The implementation lacks good performance. The code is offered anyway,
775 maybe somebody can improve the performance.
780 @node External transfer methods
781 @section External transfer methods
782 @cindex methods, external transfer
783 @cindex methods, out-of-band
784 @cindex external transfer methods
785 @cindex out-of-band methods
787 The external transfer methods operate through multiple channels, using
788 the remote shell connection for many actions while delegating file
789 transfers to an external transfer utility.
791 This saves the overhead of encoding and decoding that multiplexing the
792 transfer through the one connection has with the inline methods.
794 Since external transfer methods need their own overhead opening a new
795 channel, all files which are smaller than @var{tramp-copy-size-limit}
796 are still transferred with the corresponding inline method. It should
797 provide a fair trade-off between both approaches.
800 @item @option{rcp} --- @command{rsh} and @command{rcp}
803 @cindex rcp (with rcp method)
804 @cindex rsh (with rcp method)
806 This method uses the @command{rsh} and @command{rcp} commands to connect
807 to the remote machine and transfer files. This is probably the fastest
808 connection method available.
810 The alternative method @option{remcp} uses the @command{remsh} and
811 @command{rcp} commands. It should be applied on machines where
812 @command{remsh} is used instead of @command{rsh}.
815 @item @option{scp} --- @command{ssh} and @command{scp}
818 @cindex scp (with scp method)
819 @cindex ssh (with scp method)
821 Using @command{ssh} to connect to the remote host and @command{scp} to
822 transfer files between the machines is the best method for securely
823 connecting to a remote machine and accessing files.
825 The performance of this option is also quite good. It may be slower than
826 the inline methods when you often open and close small files however.
827 The cost of the cryptographic handshake at the start of an @command{scp}
828 session can begin to absorb the advantage that the lack of encoding and
831 There are also two variants, @option{scp1} and @option{scp2}, that
832 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
833 explicitly select whether you want to use the SSH protocol version 1
834 or 2 to connect to the remote host. (You can also specify in
835 @file{~/.ssh/config}, the SSH configuration file, which protocol
836 should be used, and use the regular @option{scp} method.)
838 Two other variants, @option{scp1_old} and @option{scp2_old}, use the
839 @command{ssh1} and @command{ssh2} commands explicitly. If you don't
840 know what these are, you do not need these options.
842 All the @command{ssh} based methods support the kludgy @samp{-p}
843 feature where you can specify a port number to connect to in the host
844 name. For example, the host name @file{host#42} tells @value{tramp} to
845 specify @samp{-p 42} in the argument list for @command{ssh}, and to
846 specify @samp{-P 42} in the argument list for @command{scp}.
849 @item @option{sftp} --- @command{ssh} and @command{sftp}
852 @cindex sftp (with sftp method)
853 @cindex ssh (with sftp method)
855 That is mostly the same method as @option{scp}, but using
856 @command{sftp} as transfer command. So the same remarks are valid.
858 This command does not work like @value{ftppackagename}, where
859 @command{ftp} is called interactively, and all commands are send from
860 within this session. Instead of, @command{ssh} is used for login.
862 This method supports the @samp{-p} hack.
865 @item @option{rsync} --- @command{ssh} and @command{rsync}
868 @cindex rsync (with rsync method)
869 @cindex ssh (with rsync method)
871 Using the @command{ssh} command to connect securely to the remote
872 machine and the @command{rsync} command to transfer files is almost
873 identical to the @option{scp} method.
875 While @command{rsync} performs much better than @command{scp} when
876 transferring files that exist on both hosts, this advantage is lost if
877 the file exists only on one side of the connection.
879 The @command{rsync} based method may be considerably faster than the
880 @command{rcp} based methods when writing to the remote system. Reading
881 files to the local machine is no faster than with a direct copy.
883 This method supports the @samp{-p} hack.
886 @item @option{scpx} --- @command{ssh} and @command{scp}
889 @cindex scp (with scpx method)
890 @cindex ssh (with scpx method)
892 As you would expect, this is similar to @option{scp}, only a little
893 different. Whereas @option{scp} opens a normal interactive shell on
894 the remote host, this option uses @samp{ssh -t -t @var{host} -l
895 @var{user} /bin/sh} to open a connection. This is useful for users
896 where the normal login shell is set up to ask them a number of
897 questions when logging in. This procedure avoids these questions, and
898 just gives @value{tramp} a more-or-less `standard' login shell to work
901 This is also useful for Windows users where @command{ssh}, when
902 invoked from an @value{emacsname} buffer, tells them that it is not
903 allocating a pseudo tty. When this happens, the login shell is wont
904 to not print any shell prompt, which confuses @value{tramp} mightily.
906 This method supports the @samp{-p} hack.
909 @item @option{scpc} --- @command{ssh} and @command{scp}
912 @cindex scp (with scpx method)
913 @cindex ssh (with scpx method)
915 Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
916 @option{ControlMaster}. This allows @option{scp} to reuse an existing
917 @option{ssh} channel, which increases performance.
919 Before you use this method, you shall check whether your @option{ssh}
920 implementation does support this option. Try from the command line
923 ssh localhost -o ControlMaster=yes
926 This method supports the @samp{-p} hack.
929 @item @option{pscp} --- @command{plink} and @command{pscp}
932 @cindex pscp (with pscp method)
933 @cindex plink (with pscp method)
934 @cindex PuTTY (with pscp method)
936 This method is similar to @option{scp}, but it uses the
937 @command{plink} command to connect to the remote host, and it uses
938 @command{pscp} for transferring the files. These programs are part
939 of PuTTY, an SSH implementation for Windows.
941 This method supports the @samp{-P} hack.
944 @item @option{psftp} --- @command{plink} and @command{psftp}
947 @cindex psftp (with psftp method)
948 @cindex plink (with psftp method)
949 @cindex PuTTY (with psftp method)
951 As you would expect, this method is similar to @option{sftp}, but it
952 uses the @command{plink} command to connect to the remote host, and it
953 uses @command{psftp} for transferring the files. These programs are
954 part of PuTTY, an SSH implementation for Windows.
956 This method supports the @samp{-P} hack.
959 @item @option{fcp} --- @command{fsh} and @command{fcp}
962 @cindex fsh (with fcp method)
963 @cindex fcp (with fcp method)
965 This method is similar to @option{scp}, but it uses the @command{fsh}
966 command to connect to the remote host, and it uses @command{fcp} for
967 transferring the files. @command{fsh/fcp} are a front-end for
968 @command{ssh} which allow for reusing the same @command{ssh} session
969 for submitting several commands. This avoids the startup overhead of
970 @command{scp} (which has to establish a secure connection whenever it
971 is called). Note, however, that you can also use one of the inline
972 methods to achieve a similar effect.
974 This method uses the command @samp{fsh @var{host} -l @var{user}
975 /bin/sh -i} to establish the connection, it does not work to just say
976 @command{fsh @var{host} -l @var{user}}.
981 There is no inline method using @command{fsh} as the multiplexing
982 provided by the program is not very useful in our context. @value{tramp}
983 opens just one connection to the remote host and then keeps it open,
991 This is not a native @value{tramp} method. Instead of, it forwards all
992 requests to @value{ftppackagename}.
994 This works only for unified filenames, see @ref{Issues}.
998 @item @option{smb} --- @command{smbclient}
1002 This is another not natural @value{tramp} method. It uses the
1003 @command{smbclient} command on different Unices in order to connect to
1004 an SMB server. An SMB server might be a Samba (or CIFS) server on
1005 another UNIX host or, more interesting, a host running MS Windows. So
1006 far, it is tested towards MS Windows NT, MS Windows 2000, and MS
1009 The first directory in the localname must be a share name on the remote
1010 host. Remember, that the @code{$} character in which default shares
1011 usually end, must be written @code{$$} due to environment variable
1012 substitution in file names. If no share name is given (i.e. remote
1013 directory @code{/}), all available shares are listed.
1015 Since authorization is done on share level, you will be prompted
1016 always for a password if you access another share on the same host.
1017 This can be suppressed by @ref{Password caching}.
1019 MS Windows uses for authorization both a user name and a domain name.
1020 Because of this, the @value{tramp} syntax has been extended: you can
1021 specify a user name which looks like @code{user%domain} (the real user
1022 name, then a percent sign, then the domain name). So, to connect to
1023 the machine @code{melancholia} as user @code{daniel} of the domain
1024 @code{BIZARRE}, and edit @file{.emacs} in the home directory (share
1025 @code{daniel$}) I would specify the filename @file{@trampfn{smb,
1026 daniel%BIZARRE, melancholia, /daniel$$/.emacs}}.
1028 Depending on the Windows domain configuration, a Windows user might be
1029 considered as domain user per default. In order to connect as local
1030 user, the WINS name of that machine must be given as domain name.
1031 Usually, it is the machine name in capital letters. In the example
1032 above, the local user @code{daniel} would be specified as
1033 @file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}.
1035 The domain name as well as the user name are optional. If no user
1036 name is specified at all, the anonymous user (without password
1037 prompting) is assumed. This is different from all other @value{tramp}
1038 methods, where in such a case the local user name is taken.
1040 The @option{smb} method supports the @samp{-p} hack.
1042 @strong{Please note:} If @value{emacsname} runs locally under MS
1043 Windows, this method isn't available. Instead of, you can use UNC
1044 file names like @file{//melancholia/daniel$$/.emacs}. The only
1045 disadvantage is that there's no possibility to specify another user
1052 @node Gateway methods
1053 @section Gateway methods
1054 @cindex methods, gateway
1055 @cindex gateway methods
1057 Gateway methods are not methods to access a remote host directly.
1058 These methods are intended to pass firewalls or proxy servers.
1059 Therefore, they can be used for proxy host declarations
1060 (@pxref{Multi-hops}) only.
1062 A gateway method must come always along with a method who supports
1063 port setting (referred to as @samp{-p} kludge). This is because
1064 @value{tramp} targets the accompanied method to
1065 @file{localhost#random_port}, from where the firewall or proxy server
1068 Gateway methods support user name and password declarations. These
1069 are used to authenticate towards the corresponding firewall or proxy
1070 server. They can be passed only if your friendly administrator has
1071 granted your access.
1074 @item @option{tunnel}
1075 @cindex method tunnel
1076 @cindex tunnel method
1078 This method implements an HTTP tunnel via the @command{CONNECT}
1079 command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server
1080 shall support this command.
1082 As authentication method, only @option{Basic Authentication} (see RFC
1083 2617) is implemented so far. If no port number is given in the
1084 declaration, port @option{8080} is used for the proxy server.
1087 @item @option{socks}
1088 @cindex method socks
1089 @cindex socks method
1091 The @command{socks} method provides access to SOCKSv5 servers (see
1092 RFC 1928). @option{Username/Password Authentication} according to RFC
1095 The default port number of the socks server is @option{1080}, if not
1096 specified otherwise.
1102 @node Default Method
1103 @section Selecting a default method
1104 @cindex default method
1106 @vindex tramp-default-method
1107 When you select an appropriate transfer method for your typical usage
1108 you should set the variable @code{tramp-default-method} to reflect that
1109 choice. This variable controls which method will be used when a method
1110 is not specified in the @value{tramp} file name. For example:
1113 (setq tramp-default-method "ssh")
1116 @vindex tramp-default-method-alist
1117 You can also specify different methods for certain user/host
1118 combinations, via the variable @code{tramp-default-method-alist}. For
1119 example, the following two lines specify to use the @option{ssh}
1120 method for all user names matching @samp{john} and the @option{rsync}
1121 method for all host names matching @samp{lily}. The third line
1122 specifies to use the @option{su} method for the user @samp{root} on
1123 the machine @samp{localhost}.
1126 (add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
1127 (add-to-list 'tramp-default-method-alist '("lily" "" "rsync"))
1128 (add-to-list 'tramp-default-method-alist
1129 '("\\`localhost\\'" "\\`root\\'" "su"))
1133 See the documentation for the variable
1134 @code{tramp-default-method-alist} for more details.
1136 External transfer methods are normally preferable to inline transfer
1137 methods, giving better performance.
1139 @xref{Inline methods}.
1140 @xref{External transfer methods}.
1142 Another consideration with the selection of transfer methods is the
1143 environment you will use them in and, especially when used over the
1144 Internet, the security implications of your preferred method.
1146 The @option{rsh} and @option{telnet} methods send your password as
1147 plain text as you log in to the remote machine, as well as
1148 transferring the files in such a way that the content can easily be
1149 read from other machines.
1151 If you need to connect to remote systems that are accessible from the
1152 Internet, you should give serious thought to using @option{ssh} based
1153 methods to connect. These provide a much higher level of security,
1154 making it a non-trivial exercise for someone to obtain your password
1155 or read the content of the files you are editing.
1158 @subsection Which method is the right one for me?
1159 @cindex choosing the right method
1161 Given all of the above, you are probably thinking that this is all fine
1162 and good, but it's not helping you to choose a method! Right you are.
1163 As a developer, we don't want to boss our users around but give them
1164 maximum freedom instead. However, the reality is that some users would
1165 like to have some guidance, so here I'll try to give you this guidance
1166 without bossing you around. You tell me whether it works @dots{}
1168 My suggestion is to use an inline method. For large files, out-of-band
1169 methods might be more efficient, but I guess that most people will want
1170 to edit mostly small files.
1172 I guess that these days, most people can access a remote machine by
1173 using @command{ssh}. So I suggest that you use the @option{ssh}
1174 method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost,
1175 /etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other
1178 If you can't use @option{ssh} to log in to the remote host, then
1179 select a method that uses a program that works. For instance, Windows
1180 users might like the @option{plink} method which uses the PuTTY
1181 implementation of @command{ssh}. Or you use Kerberos and thus like
1184 For the special case of editing files on the local host as another
1185 user, see the @option{su} or @option{sudo} methods. They offer
1186 shortened syntax for the @samp{root} account, like
1187 @file{@trampfn{su, , , /etc/motd}}.
1189 People who edit large files may want to consider @option{scpc} instead
1190 of @option{ssh}, or @option{pscp} instead of @option{plink}. These
1191 out-of-band methods are faster than inline methods for large files.
1192 Note, however, that out-of-band methods suffer from some limitations.
1193 Please try first whether you really get a noticeable speed advantage
1194 from using an out-of-band method! Maybe even for large files, inline
1195 methods are fast enough.
1199 @section Selecting a default user
1200 @cindex default user
1202 The user part of a @value{tramp} file name can be omitted. Usually,
1203 it is replaced by the user name you are logged in. Often, this is not
1204 what you want. A typical use of @value{tramp} might be to edit some
1205 files with root permissions on the local host. This case, you should
1206 set the variable @code{tramp-default-user} to reflect that choice.
1210 (setq tramp-default-user "root")
1213 @code{tramp-default-user} is regarded as obsolete, and will be removed
1216 @vindex tramp-default-user-alist
1217 You can also specify different users for certain method/host
1218 combinations, via the variable @code{tramp-default-user-alist}. For
1219 example, if you always have to use the user @samp{john} in the domain
1220 @samp{somewhere.else}, you can specify the following:
1223 (add-to-list 'tramp-default-user-alist
1224 '("ssh" ".*\\.somewhere\\.else\\'" "john"))
1228 See the documentation for the variable
1229 @code{tramp-default-user-alist} for more details.
1231 One trap to fall in must be known. If @value{tramp} finds a default
1232 user, this user will be passed always to the connection command as
1233 parameter (for example @samp{ssh here.somewhere.else -l john}. If you
1234 have specified another user for your command in its configuration
1235 files, @value{tramp} cannot know it, and the remote access will fail.
1236 If you have specified in the given example in @file{~/.ssh/config} the
1240 Host here.somewhere.else
1245 than you must discard selecting a default user by @value{tramp}. This
1246 will be done by setting it to @code{nil} (or @samp{lily}, likewise):
1249 (add-to-list 'tramp-default-user-alist
1250 '("ssh" "\\`here\\.somewhere\\.else\\'" nil))
1253 The last entry in @code{tramp-default-user-alist} could be your
1254 default user you'll apply predominantly. You shall @emph{append} it
1255 to that list at the end:
1258 (add-to-list 'tramp-default-user-alist '(nil nil "jonas") t)
1263 @section Selecting a default host
1264 @cindex default host
1266 @vindex tramp-default-host
1267 Finally, it is even possible to omit the host name part of a
1268 @value{tramp} file name. This case, the value of the variable
1269 @code{tramp-default-host} is used. Per default, it is initialized
1270 with the host name your local @value{emacsname} is running.
1272 If you, for example, use @value{tramp} mainly to contact the host
1273 @samp{target} as user @samp{john}, you can specify:
1276 (setq tramp-default-user "john"
1277 tramp-default-host "target")
1280 Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you
1281 to John's home directory on target.
1283 Note, however, that the most simplification @samp{/::} won't work,
1284 because @samp{/:} is the prefix for quoted file names.
1289 @section Connecting to a remote host using multiple hops
1293 Sometimes, the methods described before are not sufficient. Sometimes,
1294 it is not possible to connect to a remote host using a simple command.
1295 For example, if you are in a secured network, you might have to log in
1296 to a `bastion host' first before you can connect to the outside world.
1297 Of course, the target host may also require a bastion host.
1299 @vindex tramp-default-proxies-alist
1300 In order to specify such multiple hops, it is possible to define a proxy
1301 host to pass through, via the variable
1302 @code{tramp-default-proxies-alist}. This variable keeps a list of
1303 triples (@var{host} @var{user} @var{proxy}).
1305 The first matching item specifies the proxy host to be passed for a
1306 file name located on a remote target matching @var{user}@@@var{host}.
1307 @var{host} and @var{user} are regular expressions or @code{nil}, which
1308 is interpreted as a regular expression which always matches.
1310 @var{proxy} must be a Tramp filename which localname part is ignored.
1311 Method and user name on @var{proxy} are optional, which is interpreted
1312 with the default values.
1314 The method must be an inline or gateway method (@pxref{Inline
1315 methods}, @pxref{Gateway methods}).
1318 The method must be an inline method (@pxref{Inline methods}).
1320 If @var{proxy} is @code{nil}, no additional hop is required reaching
1321 @var{user}@@@var{host}.
1323 If you, for example, must pass the host @samp{bastion.your.domain} as
1324 user @samp{bird} for any remote host which is not located in your local
1328 (add-to-list 'tramp-default-proxies-alist
1329 '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}"))
1330 (add-to-list 'tramp-default-proxies-alist
1331 '("\\.your\\.domain\\'" nil nil))
1334 Please note the order of the code. @code{add-to-list} adds elements at the
1335 beginning of a list. Therefore, most relevant rules must be added last.
1337 Proxy hosts can be cascaded. If there is another host called
1338 @samp{jump.your.domain}, which is the only one in your local domain who
1339 is allowed connecting @samp{bastion.your.domain}, you can add another
1343 (add-to-list 'tramp-default-proxies-alist
1344 '("\\`bastion\\.your\\.domain\\'"
1346 "@trampfn{ssh, , jump.your.domain,}"))
1349 @var{proxy} can contain the patterns @code{%h} or @code{%u}. These
1350 patterns are replaced by the strings matching @var{host} or
1351 @var{user}, respectively.
1353 If you, for example, wants to work as @samp{root} on hosts in the
1354 domain @samp{your.domain}, but login as @samp{root} is disabled for
1355 non-local access, you might add the following rule:
1358 (add-to-list 'tramp-default-proxies-alist
1359 '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
1362 Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect
1363 first @samp{randomhost.your.domain} via @code{ssh} under your account
1364 name, and perform @code{sudo -u root} on that host afterwards. It is
1365 important to know that the given method is applied on the host which
1366 has been reached so far. @code{sudo -u root}, applied on your local
1367 host, wouldn't be useful here.
1369 This is the recommended configuration to work as @samp{root} on remote
1373 Finally, @code{tramp-default-proxies-alist} can be used to pass
1374 firewalls or proxy servers. Imagine your local network has a host
1375 @samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to
1376 the outer world. Your friendly administrator has granted you access
1377 under your user name to @samp{host.other.domain} on that proxy
1378 server.@footnote{HTTP tunnels are intended for secure SSL/TLS
1379 communication. Therefore, many proxy server restrict the tunnels to
1380 related target ports. You might need to run your ssh server on your
1381 target host @samp{host.other.domain} on such a port, like 443 (https).
1382 See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall}
1383 for discussion of ethical issues.} You would need to add the
1387 (add-to-list 'tramp-default-proxies-alist
1388 '("\\`host\\.other\\.domain\\'" nil
1389 "@trampfn{tunnel, , proxy.your.domain#3128,}"))
1392 Gateway methods can be declared as first hop only in a multiple hop
1397 @node Customizing Methods
1398 @section Using Non-Standard Methods
1399 @cindex customizing methods
1400 @cindex using non-standard methods
1401 @cindex create your own methods
1403 There is a variable @code{tramp-methods} which you can change if the
1404 predefined methods don't seem right.
1406 For the time being, I'll refer you to the Lisp documentation of that
1407 variable, accessible with @kbd{C-h v tramp-methods @key{RET}}.
1410 @node Customizing Completion
1411 @section Selecting config files for user/host name completion
1412 @cindex customizing completion
1413 @cindex selecting config files
1414 @vindex tramp-completion-function-alist
1416 The variable @code{tramp-completion-function-alist} is intended to
1417 customize which files are taken into account for user and host name
1418 completion (@pxref{Filename completion}). For every method, it keeps
1419 a set of configuration files, accompanied by a Lisp function able to
1420 parse that file. Entries in @code{tramp-completion-function-alist}
1421 have the form (@var{method} @var{pair1} @var{pair2} ...).
1423 Each @var{pair} is composed of (@var{function} @var{file}).
1424 @var{function} is responsible to extract user names and host names
1425 from @var{file} for completion. There are two functions which access
1428 @defun tramp-get-completion-function method
1429 This function returns the list of completion functions for @var{method}.
1433 (tramp-get-completion-function "rsh")
1435 @result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
1436 (tramp-parse-rhosts "~/.rhosts"))
1440 @defun tramp-set-completion-function method function-list
1441 This function sets @var{function-list} as list of completion functions
1446 (tramp-set-completion-function "ssh"
1447 '((tramp-parse-sconfig "/etc/ssh_config")
1448 (tramp-parse-sconfig "~/.ssh/config")))
1450 @result{} ((tramp-parse-sconfig "/etc/ssh_config")
1451 (tramp-parse-sconfig "~/.ssh/config"))
1455 The following predefined functions parsing configuration files exist:
1458 @item @code{tramp-parse-rhosts}
1459 @findex tramp-parse-rhosts
1461 This function parses files which are syntactical equivalent to
1462 @file{~/.rhosts}. It returns both host names and user names, if
1465 @item @code{tramp-parse-shosts}
1466 @findex tramp-parse-shosts
1468 This function parses files which are syntactical equivalent to
1469 @file{~/.ssh/known_hosts}. Since there are no user names specified
1470 in such files, it can return host names only.
1472 @item @code{tramp-parse-sconfig}
1473 @findex tramp-parse-shosts
1475 This function returns the host nicknames defined by @code{Host} entries
1476 in @file{~/.ssh/config} style files.
1478 @item @code{tramp-parse-shostkeys}
1479 @findex tramp-parse-shostkeys
1481 SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and
1482 @file{~/ssh2/hostkeys/*}. Hosts are coded in file names
1483 @file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names
1484 are always @code{nil}.
1486 @item @code{tramp-parse-sknownhosts}
1487 @findex tramp-parse-shostkeys
1489 Another SSH2 style parsing of directories like
1490 @file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This
1491 case, hosts names are coded in file names
1492 @file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}.
1494 @item @code{tramp-parse-hosts}
1495 @findex tramp-parse-hosts
1497 A function dedicated to @file{/etc/hosts} style files. It returns
1500 @item @code{tramp-parse-passwd}
1501 @findex tramp-parse-passwd
1503 A function which parses @file{/etc/passwd} like files. Obviously, it
1504 can return user names only.
1506 @item @code{tramp-parse-netrc}
1507 @findex tramp-parse-netrc
1509 Finally, a function which parses @file{~/.netrc} like files.
1512 If you want to keep your own data in a file, with your own structure,
1513 you might provide such a function as well. This function must meet
1514 the following conventions:
1516 @defun my-tramp-parse file
1517 @var{file} must be either a file name on your host, or @code{nil}.
1518 The function must return a list of (@var{user} @var{host}), which are
1519 taken as candidates for user and host name completion.
1523 (my-tramp-parse "~/.my-tramp-hosts")
1525 @result{} ((nil "toto") ("daniel" "melancholia"))
1530 @node Password caching
1531 @section Reusing passwords for several connections.
1534 Sometimes it is necessary to connect to the same remote host several
1535 times. Reentering passwords again and again would be annoying, when
1536 the chosen method does not support access without password prompt
1537 through own configuration.
1539 By default, @value{tramp} caches the passwords entered by you. They will
1540 be reused next time if a connection needs them for the same user name
1541 and host name, independently of the connection method.
1543 @vindex password-cache-expiry
1544 Passwords are not saved permanently, that means the password caching
1545 is limited to the lifetime of your @value{emacsname} session. You
1546 can influence the lifetime of password caching by customizing the
1547 variable @code{password-cache-expiry}. The value is the number of
1548 seconds how long passwords are cached. Setting it to @code{nil}
1549 disables the expiration.
1551 @findex tramp-clear-passwd
1552 A password is removed from the cache if a connection isn't established
1553 successfully. You can remove a password from the cache also by
1554 executing @kbd{M-x tramp-clear-passwd} in a buffer containing a
1555 related remote file or directory.
1557 @vindex password-cache
1558 If you don't like this feature for security reasons, password caching
1559 can be disabled totally by customizing the variable
1560 @code{password-cache} (setting it to @code{nil}).
1562 Implementation Note: password caching is based on the package
1563 @file{password.el} in No Gnus. For the time being, it is activated
1564 only when this package is seen in the @code{load-path} while loading
1566 @ifset installchapter
1567 If you don't use No Gnus, you can take @file{password.el} from the
1568 @value{tramp} @file{contrib} directory, see @ref{Installation
1571 It will be activated mandatory once No Gnus has found its way into
1575 @node Connection caching
1576 @section Reusing connection related information.
1579 @vindex tramp-persistency-file-name
1580 In order to reduce initial connection time, @value{tramp} stores
1581 connection related information persistently. The variable
1582 @code{tramp-persistency-file-name} keeps the file name where these
1583 information are written. Its default value is
1585 @file{~/.emacs.d/tramp}.
1588 @file{~/.xemacs/tramp}.
1590 It is recommended to choose a local file name.
1592 @value{tramp} reads this file during startup, and writes it when
1593 exiting @value{emacsname}. You can simply remove this file if
1594 @value{tramp} shall be urged to recompute these information next
1595 @value{emacsname} startup time.
1597 Using such persistent information can be disabled by setting
1598 @code{tramp-persistency-file-name} to @code{nil}.
1601 @node Remote Programs
1602 @section How @value{tramp} finds and uses programs on the remote machine.
1604 @value{tramp} depends on a number of programs on the remote host in order to
1605 function, including @command{ls}, @command{test}, @command{find} and
1608 In addition to these required tools, there are various tools that may be
1609 required based on the connection method. See @ref{Inline methods} and
1610 @ref{External transfer methods} for details on these.
1612 Certain other tools, such as @command{perl} (or @command{perl5}) and
1613 @command{grep} will be used if they can be found. When they are
1614 available, they are used to improve the performance and accuracy of
1617 @vindex tramp-remote-path
1618 When @value{tramp} connects to the remote machine, it searches for the
1619 programs that it can use. The variable @code{tramp-remote-path}
1620 controls the directories searched on the remote machine.
1622 By default, this is set to a reasonable set of defaults for most
1623 machines. The symbol @code{tramp-default-remote-path} is a place
1624 holder, it is replaced by the list of directories received via the
1625 command @command{getconf PATH} on your remote machine. For example,
1626 on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is
1627 @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is
1628 recommended to apply this symbol on top of @code{tramp-remote-path}.
1630 It is possible, however, that your local (or remote ;) system
1631 administrator has put the tools you want in some obscure local
1634 In this case, you can still use them with @value{tramp}. You simply
1635 need to add code to your @file{.emacs} to add the directory to the
1636 remote path. This will then be searched by @value{tramp} when you
1637 connect and the software found.
1639 To add a directory to the remote search path, you could use code such
1643 @i{;; We load @value{tramp} to define the variable.}
1645 @i{;; We have @command{perl} in "/usr/local/perl/bin"}
1646 (add-to-list 'tramp-remote-path "/usr/local/perl/bin")
1649 @value{tramp} caches several information, like the Perl binary
1650 location. The changed remote search path wouldn't affect these
1651 settings. In order to force @value{tramp} to recompute these values,
1652 you must exit @value{emacsname}, remove your persistency file
1653 (@pxref{Connection caching}), and restart @value{emacsname}.
1656 @node Remote shell setup
1657 @comment node-name, next, previous, up
1658 @section Remote shell setup hints
1659 @cindex remote shell setup
1660 @cindex @file{.profile} file
1661 @cindex @file{.login} file
1662 @cindex shell init files
1664 As explained in the @ref{Overview} section, @value{tramp} connects to the
1665 remote host and talks to the shell it finds there. Of course, when you
1666 log in, the shell executes its init files. Suppose your init file
1667 requires you to enter the birth date of your mother; clearly @value{tramp}
1668 does not know this and hence fails to log you in to that host.
1670 There are different possible strategies for pursuing this problem. One
1671 strategy is to enable @value{tramp} to deal with all possible situations.
1672 This is a losing battle, since it is not possible to deal with
1673 @emph{all} situations. The other strategy is to require you to set up
1674 the remote host such that it behaves like @value{tramp} expects. This might
1675 be inconvenient because you have to invest a lot of effort into shell
1676 setup before you can begin to use @value{tramp}.
1678 The package, therefore, pursues a combined approach. It tries to
1679 figure out some of the more common setups, and only requires you to
1680 avoid really exotic stuff. For example, it looks through a list of
1681 directories to find some programs on the remote host. And also, it
1682 knows that it is not obvious how to check whether a file exists, and
1683 therefore it tries different possibilities. (On some hosts and
1684 shells, the command @command{test -e} does the trick, on some hosts
1685 the shell builtin doesn't work but the program @command{/usr/bin/test
1686 -e} or @command{/bin/test -e} works. And on still other hosts,
1687 @command{ls -d} is the right way to do this.)
1689 Below you find a discussion of a few things that @value{tramp} does not deal
1690 with, and that you therefore have to set up correctly.
1693 @item @var{shell-prompt-pattern}
1694 @vindex shell-prompt-pattern
1696 After logging in to the remote host, @value{tramp} has to wait for the remote
1697 shell startup to finish before it can send commands to the remote
1698 shell. The strategy here is to wait for the shell prompt. In order to
1699 recognize the shell prompt, the variable @code{shell-prompt-pattern} has
1700 to be set correctly to recognize the shell prompt on the remote host.
1702 Note that @value{tramp} requires the match for @code{shell-prompt-pattern}
1703 to be at the end of the buffer. Many people have something like the
1704 following as the value for the variable: @code{"^[^>$][>$] *"}. Now
1705 suppose your shell prompt is @code{a <b> c $ }. In this case,
1706 @value{tramp} recognizes the @code{>} character as the end of the prompt,
1707 but it is not at the end of the buffer.
1709 @item @var{tramp-shell-prompt-pattern}
1710 @vindex tramp-shell-prompt-pattern
1712 This regular expression is used by @value{tramp} in the same way as
1713 @code{shell-prompt-pattern}, to match prompts from the remote shell.
1714 This second variable exists because the prompt from the remote shell
1715 might be different from the prompt from a local shell --- after all,
1716 the whole point of @value{tramp} is to log in to remote hosts as a
1717 different user. The default value of
1718 @code{tramp-shell-prompt-pattern} is the same as the default value of
1719 @code{shell-prompt-pattern}, which is reported to work well in many
1722 @item @command{tset} and other questions
1723 @cindex Unix command tset
1724 @cindex tset Unix command
1726 Some people invoke the @command{tset} program from their shell startup
1727 scripts which asks the user about the terminal type of the shell.
1728 Maybe some shells ask other questions when they are started.
1729 @value{tramp} does not know how to answer these questions. There are
1730 two approaches for dealing with this problem. One approach is to take
1731 care that the shell does not ask any questions when invoked from
1732 @value{tramp}. You can do this by checking the @code{TERM}
1733 environment variable, it will be set to @code{dumb} when connecting.
1735 @vindex tramp-terminal-type
1736 The variable @code{tramp-terminal-type} can be used to change this value
1739 @vindex tramp-actions-before-shell
1740 The other approach is to teach @value{tramp} about these questions. See
1741 the variable @code{tramp-actions-before-shell}. Example:
1744 (defconst my-tramp-prompt-regexp
1745 (concat (regexp-opt '("Enter the birth date of your mother:") t)
1747 "Regular expression matching my login prompt question.")
1749 (defun my-tramp-action (proc vec)
1750 "Enter \"19000101\" in order to give a correct answer."
1751 (save-window-excursion
1752 (with-current-buffer (tramp-get-connection-buffer vec)
1753 (tramp-message vec 6 "\n%s" (buffer-string))
1754 (tramp-send-string vec "19000101"))))
1756 (add-to-list 'tramp-actions-before-shell
1757 '(my-tramp-prompt-regexp my-tramp-action))
1761 @item Environment variables named like users in @file{.profile}
1763 If you have a user named frumple and set the variable @code{FRUMPLE} in
1764 your shell environment, then this might cause trouble. Maybe rename
1765 the variable to @code{FRUMPLE_DIR} or the like.
1767 This weird effect was actually reported by a @value{tramp} user!
1770 @item Non-Bourne commands in @file{.profile}
1772 After logging in to the remote host, @value{tramp} issues the command
1773 @command{exec /bin/sh}. (Actually, the command is slightly
1774 different.) When @command{/bin/sh} is executed, it reads some init
1775 files, such as @file{~/.shrc} or @file{~/.profile}.
1777 Now, some people have a login shell which is not @code{/bin/sh} but a
1778 Bourne-ish shell such as bash or ksh. Some of these people might put
1779 their shell setup into the files @file{~/.shrc} or @file{~/.profile}.
1780 This way, it is possible for non-Bourne constructs to end up in those
1781 files. Then, @command{exec /bin/sh} might cause the Bourne shell to
1782 barf on those constructs.
1784 As an example, imagine somebody putting @command{export FOO=bar} into
1785 the file @file{~/.profile}. The standard Bourne shell does not
1786 understand this syntax and will emit a syntax error when it reaches
1789 Another example is the tilde (@code{~}) character, say when adding
1790 @file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this
1791 character, and since there is usually no directory whose name consists
1792 of the single character tilde, strange things will happen.
1794 What can you do about this?
1796 Well, one possibility is to make sure that everything in
1797 @file{~/.shrc} and @file{~/.profile} on all remote hosts is
1798 Bourne-compatible. In the above example, instead of @command{export
1799 FOO=bar}, you might use @command{FOO=bar; export FOO} instead.
1801 The other possibility is to put your non-Bourne shell setup into some
1802 other files. For example, bash reads the file @file{~/.bash_profile}
1803 instead of @file{~/.profile}, if the former exists. So bash
1804 aficionados just rename their @file{~/.profile} to
1805 @file{~/.bash_profile} on all remote hosts, and Bob's your uncle.
1807 The @value{tramp} developers would like to circumvent this problem, so
1808 if you have an idea about it, please tell us. However, we are afraid
1809 it is not that simple: before saying @command{exec /bin/sh},
1810 @value{tramp} does not know which kind of shell it might be talking
1811 to. It could be a Bourne-ish shell like ksh or bash, or it could be a
1812 csh derivative like tcsh, or it could be zsh, or even rc. If the
1813 shell is Bourne-ish already, then it might be prudent to omit the
1814 @command{exec /bin/sh} step. But how to find out if the shell is
1820 @node Auto-save and Backup
1821 @section Auto-save and Backup configuration
1825 @vindex backup-directory-alist
1828 @vindex bkup-backup-directory-info
1831 Normally, @value{emacsname} writes backup files to the same directory
1832 as the original files, but this behavior can be changed via the
1835 @code{backup-directory-alist}.
1838 @code{bkup-backup-directory-info}.
1840 In connection with @value{tramp}, this can have unexpected side
1841 effects. Suppose that you specify that all backups should go to the
1842 directory @file{~/.emacs.d/backups/}, and then you edit the file
1843 @file{@trampfn{su, root, localhost, /etc/secretfile}}. The effect is
1844 that the backup file will be owned by you and not by root, thus
1845 possibly enabling others to see it even if they were not intended to
1850 @code{backup-directory-alist}
1853 @code{bkup-backup-directory-info}
1855 is @code{nil} (the default), such problems do not occur.
1857 Therefore, it is useful to set special values for @value{tramp}
1858 files. For example, the following statement effectively `turns off'
1861 @code{backup-directory-alist}
1864 @code{bkup-backup-directory-info}
1866 for @value{tramp} files:
1870 (add-to-list 'backup-directory-alist
1871 (cons tramp-file-name-regexp nil))
1876 (require 'backup-dir)
1877 (add-to-list 'bkup-backup-directory-info
1878 (list tramp-file-name-regexp ""))
1882 Another possibility is to use the @value{tramp} variable
1884 @code{tramp-backup-directory-alist}.
1887 @code{tramp-bkup-backup-directory-info}.
1889 This variable has the same meaning like
1891 @code{backup-directory-alist}.
1894 @code{bkup-backup-directory-info}.
1896 If a @value{tramp} file is backed up, and DIRECTORY is an absolute
1897 local file name, DIRECTORY is prepended with the @value{tramp} file
1898 name prefix of the file to be backed up.
1905 (add-to-list 'backup-directory-alist
1906 (cons "." "~/.emacs.d/backups/"))
1907 (setq tramp-backup-directory-alist backup-directory-alist)
1912 (require 'backup-dir)
1913 (add-to-list 'bkup-backup-directory-info
1914 (list "." "~/.emacs.d/backups/" 'full-path))
1915 (setq tramp-bkup-backup-directory-info bkup-backup-directory-info)
1920 The backup file name of @file{@trampfn{su, root, localhost,
1921 /etc/secretfile}} would be
1923 @file{@trampfn{su, root, localhost,
1924 ~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
1927 @file{@trampfn{su, root, localhost,
1928 ~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}
1931 The same problem can happen with auto-saving files.
1933 Since @value{emacsname} 21, the variable
1934 @code{auto-save-file-name-transforms} keeps information, on which
1935 directory an auto-saved file should go. By default, it is initialized
1936 for @value{tramp} files to the local temporary directory.
1938 On some versions of @value{emacsname}, namely the version built for
1939 Debian GNU/Linux, the variable @code{auto-save-file-name-transforms}
1940 contains the directory where @value{emacsname} was built. A
1941 workaround is to manually set the variable to a sane value.
1943 If auto-saved files should go into the same directory as the original
1944 files, @code{auto-save-file-name-transforms} should be set to @code{nil}.
1946 Another possibility is to set the variable
1947 @code{tramp-auto-save-directory} to a proper value.
1950 For this purpose you can set the variable @code{auto-save-directory}
1955 @node Windows setup hints
1956 @section Issues with Cygwin ssh
1957 @cindex Cygwin, issues
1959 This section needs a lot of work! Please help.
1961 @cindex method sshx with Cygwin
1962 @cindex sshx method with Cygwin
1963 The recent Cygwin installation of @command{ssh} works only with a
1964 Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x
1965 eshell}, and starting @kbd{ssh test.machine}. The problem is evident
1966 if you see a message like this:
1969 Pseudo-terminal will not be allocated because stdin is not a terminal.
1972 Older @command{ssh} versions of Cygwin are told to cooperate with
1973 @value{tramp} selecting @option{sshx} as the connection method. You
1974 can find information about setting up Cygwin in their FAQ at
1975 @uref{http://cygwin.com/faq/}.
1977 @cindex method scpx with Cygwin
1978 @cindex scpx method with Cygwin
1979 If you wish to use the @option{scpx} connection method, then you might
1980 have the problem that @value{emacsname} calls @command{scp} with a
1981 Windows filename such as @code{c:/foo}. The Cygwin version of
1982 @command{scp} does not know about Windows filenames and interprets
1983 this as a remote filename on the host @code{c}.
1985 One possible workaround is to write a wrapper script for @option{scp}
1986 which converts the Windows filename to a Cygwinized filename.
1988 @cindex Cygwin and ssh-agent
1989 @cindex SSH_AUTH_SOCK and @value{emacsname} on Windows
1990 If you want to use either @option{ssh} based method on Windows, then
1991 you might encounter problems with @command{ssh-agent}. Using this
1992 program, you can avoid typing the pass-phrase every time you log in.
1993 However, if you start @value{emacsname} from a desktop shortcut, then
1994 the environment variable @code{SSH_AUTH_SOCK} is not set and so
1995 @value{emacsname} and thus @value{tramp} and thus @command{ssh} and
1996 @command{scp} started from @value{tramp} cannot communicate with
1997 @command{ssh-agent}. It works better to start @value{emacsname} from
2000 If anyone knows how to start @command{ssh-agent} under Windows in such a
2001 way that desktop shortcuts can profit, please holler. I don't really
2002 know anything at all about Windows@dots{}
2006 @chapter Using @value{tramp}
2007 @cindex using @value{tramp}
2009 Once you have installed @value{tramp} it will operate fairly
2010 transparently. You will be able to access files on any remote machine
2011 that you can log in to as though they were local.
2013 Files are specified to @value{tramp} using a formalized syntax specifying the
2014 details of the system to connect to. This is similar to the syntax used
2015 by the @value{ftppackagename} package.
2018 Something that might happen which surprises you is that
2019 @value{emacsname} remembers all your keystrokes, so if you see a
2020 password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}}
2021 twice instead of once, then the second keystroke will be processed by
2022 @value{emacsname} after @value{tramp} has done its thing. Why, this
2023 type-ahead is normal behavior, you say. Right you are, but be aware
2024 that opening a remote file might take quite a while, maybe half a
2025 minute when a connection needs to be opened. Maybe after half a
2026 minute you have already forgotten that you hit that key!
2029 * Filename Syntax:: @value{tramp} filename conventions.
2030 * Alternative Syntax:: URL-like filename syntax.
2031 * Filename completion:: Filename completion.
2032 * Remote processes:: Integration with other @value{emacsname} packages.
2036 @node Filename Syntax
2037 @section @value{tramp} filename conventions
2038 @cindex filename syntax
2039 @cindex filename examples
2041 To access the file @var{localname} on the remote machine @var{machine}
2042 you would specify the filename @file{@trampfn{, , machine,
2043 localname}}. This will connect to @var{machine} and transfer the file
2044 using the default method. @xref{Default Method}.
2046 Some examples of @value{tramp} filenames are shown below.
2049 @item @trampfn{, , melancholia, .emacs}
2050 Edit the file @file{.emacs} in your home directory on the machine
2053 @item @trampfn{, , melancholia.danann.net, .emacs}
2054 This edits the same file, using the fully qualified domain name of
2057 @item @trampfn{, , melancholia, ~/.emacs}
2058 This also edits the same file --- the @file{~} is expanded to your
2059 home directory on the remote machine, just like it is locally.
2061 @item @trampfn{, , melancholia, ~daniel/.emacs}
2062 This edits the file @file{.emacs} in the home directory of the user
2063 @code{daniel} on the machine @code{melancholia}. The @file{~<user>}
2064 construct is expanded to the home directory of that user on the remote
2067 @item @trampfn{, , melancholia, /etc/squid.conf}
2068 This edits the file @file{/etc/squid.conf} on the machine
2073 Unless you specify a different name to use, @value{tramp} will use the
2074 current local user name as the remote user name to log in with. If you
2075 need to log in as a different user, you can specify the user name as
2076 part of the filename.
2078 To log in to the remote machine as a specific user, you use the syntax
2079 @file{@trampfn{, user, machine, path/to.file}}. That means that
2080 connecting to @code{melancholia} as @code{daniel} and editing
2081 @file{.emacs} in your home directory you would specify
2082 @file{@trampfn{, daniel, melancholia, .emacs}}.
2084 It is also possible to specify other file transfer methods
2085 (@pxref{Inline methods}, @pxref{External transfer methods}) as part of
2088 This is done by putting the method before the user and host name, as
2089 in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the
2093 This is done by replacing the initial @file{@value{prefix}} with
2094 @file{@value{prefix}<method>@value{postfixhop}}. (Note the trailing
2097 The user, machine and file specification remain the same.
2099 So, to connect to the machine @code{melancholia} as @code{daniel},
2100 using the @option{ssh} method to transfer files, and edit
2101 @file{.emacs} in my home directory I would specify the filename
2102 @file{@trampfn{ssh, daniel, melancholia, .emacs}}.
2105 @node Alternative Syntax
2106 @section URL-like filename syntax
2107 @cindex filename syntax
2108 @cindex filename examples
2110 Additionally to the syntax described in the previous chapter, it is
2111 possible to use a URL-like syntax for @value{tramp}. This can be
2112 switched on by customizing the variable @code{tramp-syntax}. Please
2113 note that this feature is experimental for the time being.
2115 The variable @code{tramp-syntax} must be set before requiring @value{tramp}:
2118 (setq tramp-syntax 'url)
2122 Then, a @value{tramp} filename would look like this:
2123 @file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}.
2124 @file{/@var{method}://} is mandatory, all other parts are optional.
2125 @file{:@var{port}} is useful for methods only who support this.
2127 The last example from the previous section would look like this:
2128 @file{/ssh://daniel@@melancholia/.emacs}.
2130 For the time being, @code{tramp-syntax} can have the following values:
2134 @item @code{ftp} -- That is the default syntax
2135 @item @code{url} -- URL-like syntax
2138 @item @code{sep} -- That is the default syntax
2139 @item @code{url} -- URL-like syntax
2140 @item @code{ftp} -- EFS-like syntax
2145 @node Filename completion
2146 @section Filename completion
2147 @cindex filename completion
2149 Filename completion works with @value{tramp} for completion of method
2150 names, of user names and of machine names as well as for completion of
2151 file names on remote machines.
2153 In order to enable this, Partial Completion mode must be set
2154 on@footnote{If you don't use Partial Completion mode, but want to
2155 keep full completion, load @value{tramp} like this in your
2159 ;; Preserve Tramp's completion features.
2160 (let ((partial-completion-mode t))
2165 @xref{Completion Options, , , @value{emacsdir}}.
2169 If you, for example, type @kbd{C-x C-f @value{prefix}t
2170 @key{TAB}}, @value{tramp} might give you as result the choice for
2174 @value{prefixhop}telnet@value{postfixhop} tmp/
2175 @value{prefixhop}toto@value{postfix}
2178 @value{prefixhop}telnet@value{postfixhop} @value{prefixhop}toto@value{postfix}
2182 @samp{@value{prefixhop}telnet@value{postfixhop}}
2183 is a possible completion for the respective method,
2185 @samp{tmp/} stands for the directory @file{/tmp} on your local
2188 and @samp{@value{prefixhop}toto@value{postfix}}
2189 might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts}
2190 file (given you're using default method @option{ssh}).
2192 If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to
2193 @samp{@value{prefix}telnet@value{postfixhop}}.
2194 Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in
2195 your @file{/etc/hosts} file, let's say
2198 @trampfn{telnet, , 127.0.0.1,} @trampfn{telnet, , 192.168.0.1,}
2199 @trampfn{telnet, , localhost,} @trampfn{telnet, , melancholia.danann.net,}
2200 @trampfn{telnet, , melancholia,}
2203 Now you can choose the desired machine, and you can continue to
2204 complete file names on that machine.
2206 If the configuration files (@pxref{Customizing Completion}), which
2207 @value{tramp} uses for analysis of completion, offer user names, those user
2208 names will be taken into account as well.
2210 Remote machines, which have been visited in the past and kept
2211 persistently (@pxref{Connection caching}), will be offered too.
2213 Once the remote machine identification is completed, it comes to
2214 filename completion on the remote host. This works pretty much like
2215 for files on the local host, with the exception that minibuffer
2216 killing via a double-slash works only on the filename part, except
2217 that filename part starts with @file{//}.
2219 @xref{Minibuffer File, , , @value{emacsdir}}.
2223 As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//etc}
2224 @key{TAB}} would result in
2225 @file{@trampfn{telnet, , melancholia, /etc}}, whereas
2226 @kbd{@trampfn{telnet, , melancholia, //etc} @key{TAB}} reduces the
2227 minibuffer contents to @file{/etc}. A triple-slash stands for the
2229 i.e. @kbd{@trampfn{telnet, , melancholia, /usr/local/bin///etc}
2230 @key{TAB}} expands directly to @file{/etc}.
2234 As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//}}
2235 would result in @file{@trampfn{telnet, , melancholia, /}}, whereas
2236 @kbd{@trampfn{telnet, , melancholia, //}} expands the minibuffer
2237 contents to @file{/}.
2241 @node Remote processes
2242 @section Integration with other @value{emacsname} packages.
2246 @value{tramp} supports running processes on a remote host. This
2247 allows to exploit @value{emacsname} packages without modification for
2248 remote file names. It does not work for the @option{ftp} and
2249 @option{smb} methods.
2251 Remote processes are started when a corresponding command is executed
2252 from a buffer belonging to a remote file or directory. Up to now, the
2253 packages @file{compile.el} (commands like @code{compile} and
2254 @code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}) have been
2255 integrated. Integration of further packages is planned, any help for
2258 When your program is not found in the default search path
2259 @value{tramp} sets on the remote machine, you should either use an
2260 absolute path, or extend @code{tramp-remote-path} (see @ref{Remote
2264 (add-to-list 'tramp-remote-path "~/bin")
2265 (add-to-list 'tramp-remote-path "/appli/pub/bin")
2268 The environment for your program can be adapted by customizing
2269 @code{tramp-remote-process-environment}. This variable is a list of
2270 strings. It is structured like @code{process-environment}. Each
2271 element is a string of the form ENVVARNAME=VALUE. An entry
2272 ENVVARNAME= disables the corresponding environment variable, which
2273 might have been set in your init file like @file{~/.profile}.
2276 Adding an entry can be performed via @code{add-to-list}:
2279 (add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")
2282 Changing or removing an existing entry is not encouraged. The default
2283 values are chosen for proper @value{tramp} work. Nevertheless, if for
2284 example a paranoid system administrator disallows changing the
2285 @var{$HISTORY} environment variable, you can customize
2286 @code{tramp-remote-process-environment}, or you can apply the
2287 following code in your @file{.emacs}:
2290 (let ((process-environment tramp-remote-process-environment))
2291 (setenv "HISTORY" nil)
2292 (setq tramp-remote-process-environment process-environment))
2295 If you use other @value{emacsname} packages which do not run
2296 out-of-the-box on a remote host, please let us know. We will try to
2297 integrate them as well. @xref{Bug Reports}.
2300 @subsection Running eshell on a remote host
2303 @value{tramp} is integrated into @file{eshell.el}. That is, you can
2304 open an interactive shell on your remote host, and run commands there.
2305 After you have started @code{eshell}, you could perform commands like
2309 @b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
2310 @b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET}
2312 @b{@trampfn{sudo, root, host, /etc} $} id @key{RET}
2313 uid=0(root) gid=0(root) groups=0(root)
2314 @b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET}
2316 @b{@trampfn{sudo, root, host, /etc} $}
2320 @anchor{Running a debugger on a remote host}
2321 @subsection Running a debugger on a remote host
2326 @file{gud.el} offers an unified interface to several symbolic
2330 (@ref{Debuggers, , , @value{emacsdir}}).
2333 With @value{tramp}, it is possible to debug programs on
2334 remote hosts. You can call @code{gdb} with a remote file name:
2337 @kbd{M-x gdb @key{RET}}
2338 @b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET}
2341 The file name can also be relative to a remote default directory.
2342 Given you are in a buffer that belongs to the remote directory
2343 @trampfn{ssh, , host, /home/user}, you could call
2346 @kbd{M-x perldb @key{RET}}
2347 @b{Run perldb (like this):} perl -d myprog.pl @key{RET}
2350 It is not possible to use just the absolute local part of a remote
2351 file name as program to debug, like @kbd{perl -d
2352 /home/user/myprog.pl}, though.
2354 Arguments of the program to be debugged are taken literally. That
2355 means file names as arguments must be given as ordinary relative or
2356 absolute file names, without any remote specification.
2360 @chapter Reporting Bugs and Problems
2363 Bugs and problems with @value{tramp} are actively worked on by the
2364 development team. Feature requests and suggestions are also more than
2367 The @value{tramp} mailing list is a great place to get information on
2368 working with @value{tramp}, solving problems and general discussion
2369 and advice on topics relating to the package. It is moderated so
2370 non-subscribers can post but messages will be delayed, possibly up to
2371 48 hours (or longer in case of holidays), until the moderator approves
2374 The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to
2375 this address go to all the subscribers. This is @emph{not} the address
2376 to send subscription requests to.
2378 Subscribing to the list is performed via
2379 @uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/,
2380 the @value{tramp} Mail Subscription Page}.
2382 To report a bug in @value{tramp}, you should execute @kbd{M-x
2383 tramp-bug}. This will automatically generate a buffer with the details
2384 of your system and @value{tramp} version.
2386 When submitting a bug report, please try to describe in excruciating
2387 detail the steps required to reproduce the problem, the setup of the
2388 remote machine and any special conditions that exist. You should also
2389 check that your problem is not described already in @xref{Frequently
2392 If you can identify a minimal test case that reproduces the problem,
2393 include that with your bug report. This will make it much easier for
2394 the development team to analyze and correct the problem.
2396 Before reporting the bug, you should set the verbosity level to 6
2397 (@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and
2398 repeat the bug. Then, include the contents of the @file{*tramp/foo*}
2399 and @file{*debug tramp/foo*} buffers in your bug report. A verbosity
2400 level greater than 6 will produce a very huge debug buffer, which is
2401 mostly not necessary for the analysis.
2403 Please be aware that, with a verbosity level of 6 or greater, the
2404 contents of files and directories will be included in the debug
2405 buffer. Passwords you've typed will never be included there.
2408 @node Frequently Asked Questions
2409 @chapter Frequently Asked Questions
2410 @cindex frequently asked questions
2415 Where can I get the latest @value{tramp}?
2417 @value{tramp} is available under the URL below.
2420 @uref{ftp://ftp.gnu.org/gnu/tramp/}
2423 There is also a Savannah project page.
2426 @uref{http://savannah.gnu.org/projects/tramp/}
2430 Which systems does it work on?
2432 The package has been used successfully on GNU Emacs 21, GNU Emacs 22
2433 and XEmacs 21 (starting with 21.4). Gateway methods are supported for
2436 The package was intended to work on Unix, and it really expects a
2437 Unix-like system on the remote end (except the @option{smb} method),
2438 but some people seemed to have some success getting it to work on MS
2439 Windows NT/2000/XP @value{emacsname}.
2441 There is some informations on @value{tramp} on NT at the following URL;
2442 many thanks to Joe Stoy for providing the information:
2443 @uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/}
2445 @c The link is broken. I've contacted Tom for clarification. Michael.
2447 The above mostly contains patches to old ssh versions; Tom Roche has a
2448 Web page with instructions:
2449 @uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html}
2453 How could I speed up @value{tramp}?
2455 In the backstage, @value{tramp} needs a lot of operations on the
2456 remote host. The time for transferring data from and to the remote
2457 host as well as the time needed to perform the operations there count.
2458 In order to speed up @value{tramp}, one could either try to avoid some
2459 of the operations, or one could try to improve their performance.
2461 Use an external transfer method, like @option{scpc}.
2463 Use caching. This is already enabled by default. Information about
2464 the remote host as well as the remote files are cached for reuse. The
2465 information about remote hosts is kept in the file specified in
2466 @code{tramp-persistency-file-name}. Keep this file.
2468 Disable version control. If you access remote files which are not
2469 under version control, a lot of check operations can be avoided by
2470 disabling VC. This can be achieved by
2473 (setq vc-handled-backends nil)
2476 Disable excessive traces. The default trace level of @value{tramp},
2477 defined in the variable @code{tramp-verbose}, is 3. You should
2478 increase this level only temporarily, hunting bugs.
2482 @value{tramp} does not connect to the remote host
2484 When @value{tramp} does not connect to the remote host, there are two
2485 reasons heading the bug mailing list:
2490 Unknown characters in the prompt
2492 @value{tramp} needs to recognize the prompt on the remote machine
2493 after execution any command. This is not possible, when the prompt
2494 contains unknown characters like escape sequences for coloring. This
2495 should be avoided on the remote side. @xref{Remote shell setup}. for
2496 setting the regular expression detecting the prompt.
2498 You can check your settings after an unsuccessful connection by
2499 switching to the @value{tramp} connection buffer @file{*tramp/foo*},
2500 setting the cursor at the top of the buffer, and applying the expression
2503 @kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))}
2506 If it fails, or the cursor is not moved at the end of the buffer, your
2507 prompt is not recognised correctly.
2509 A special problem is the zsh, which uses left-hand side and right-hand
2510 side prompts in parallel. Therefore, it is necessary to disable the
2511 zsh line editor on the remote host. You shall add to @file{~/.zshrc}
2512 the following command:
2515 [ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
2520 @value{tramp} doesn't transfer strings with more than 500 characters
2523 On some few systems, the implementation of @code{process-send-string}
2524 seems to be broken for longer strings. It is reported for HP-UX,
2525 FreeBSD and Tru64 Unix, for example. This case, you should customize
2526 the variable @code{tramp-chunksize} to 500. For a description how to
2527 determine whether this is necessary see the documentation of
2528 @code{tramp-chunksize}.
2530 Additionally, it will be useful to set @code{file-precious-flag} to
2531 @code{t} for @value{tramp} files. Then the file contents will be
2532 written into a temporary file first, which is checked for correct
2535 @pxref{Saving Buffers, , , elisp}
2542 (when (file-remote-p default-directory)
2543 (set (make-local-variable 'file-precious-flag) t))))
2550 File name completion does not work with @value{tramp}
2552 When you log in to the remote machine, do you see the output of
2553 @command{ls} in color? If so, this may be the cause of your problems.
2555 @command{ls} outputs @acronym{ANSI} escape sequences that your terminal
2556 emulator interprets to set the colors. These escape sequences will
2557 confuse @value{tramp} however.
2559 In your @file{.bashrc}, @file{.profile} or equivalent on the remote
2560 machine you probably have an alias configured that adds the option
2561 @option{--color=yes} or @option{--color=auto}.
2563 You should remove that alias and ensure that a new login @emph{does not}
2564 display the output of @command{ls} in color. If you still cannot use
2565 filename completion, report a bug to the @value{tramp} developers.
2569 File name completion does not work in large directories
2571 @value{tramp} uses globbing for some operations. (Globbing means to use the
2572 shell to expand wildcards such as `*.c'.) This might create long
2573 command lines, especially in directories with many files. Some shells
2574 choke on long command lines, or don't cope well with the globbing
2577 If you have a large directory on the remote end, you may wish to execute
2578 a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs.
2579 Note that you must first start the right shell, which might be
2580 @command{/bin/sh}, @command{ksh} or @command{bash}, depending on which
2581 of those supports tilde expansion.
2585 How can I get notified when @value{tramp} file transfers are complete?
2587 The following snippet can be put in your @file{~/.emacs} file. It
2588 makes @value{emacsname} beep after reading from or writing to the
2592 (defadvice tramp-handle-write-region
2593 (after tramp-write-beep-advice activate)
2594 " make tramp beep after writing a file."
2598 (defadvice tramp-handle-do-copy-or-rename-file
2599 (after tramp-copy-beep-advice activate)
2600 " make tramp beep after copying a file."
2604 (defadvice tramp-handle-insert-file-contents
2605 (after tramp-copy-beep-advice activate)
2606 " make tramp beep after copying a file."
2614 I'ld like to see a host indication in the mode line when I'm remote
2616 The following code has been tested with @value{emacsname} 22.1. You
2617 should put it into your @file{~/.emacs}:
2620 (defconst my-mode-line-buffer-identification
2624 (if (file-remote-p default-directory)
2625 (tramp-file-name-host
2626 (tramp-dissect-file-name default-directory))
2628 (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
2629 (substring host-name 0 (match-beginning 1))
2634 mode-line-buffer-identification
2635 my-mode-line-buffer-identification)
2641 mode-line-buffer-identification
2642 my-mode-line-buffer-identification)))
2645 Since @value{emacsname} 23.1, the mode line contains an indication if
2646 @code{default-directory} for the current buffer is on a remote host.
2647 The corresponding tooltip includes the name of that host. If you
2648 still want the host name as part of the mode line, you can use the
2649 example above, but the @code{:eval} clause can be simplified:
2654 (or (file-remote-p default-directory 'host)
2656 (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
2657 (substring host-name 0 (match-beginning 1))
2665 My remote host does not understand default directory listing options
2667 @value{emacsname} computes the @command{dired} options depending on
2668 the local host you are working. If your @command{ls} command on the
2669 remote host does not understand those options, you can change them
2674 'dired-before-readin-hook
2676 (when (file-remote-p default-directory)
2677 (setq dired-actual-switches "-al"))))
2683 There's this @file{~/.sh_history} file on the remote host which keeps
2684 growing and growing. What's that?
2686 Sometimes, @value{tramp} starts @command{ksh} on the remote host for
2687 tilde expansion. Maybe @command{ksh} saves the history by default.
2688 @value{tramp} tries to turn off saving the history, but maybe you have
2689 to help. For example, you could put this in your @file{.kshrc}:
2692 if [ -f $HOME/.sh_history ] ; then
2693 /bin/rm $HOME/.sh_history
2695 if [ "$@{HISTFILE-unset@}" != "unset" ] ; then
2698 if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then
2704 @item There are longish file names to type. How to shorten this?
2706 Let's say you need regularly access to @file{@trampfn{ssh, news,
2707 news.my.domain, /opt/news/etc}}, which is boring to type again and
2708 again. The following approaches can be mixed:
2712 @item Use default values for method and user name:
2714 You can define default methods and user names for hosts,
2715 (@pxref{Default Method}, @pxref{Default User}):
2718 (setq tramp-default-method "ssh"
2719 tramp-default-user "news")
2722 The file name left to type would be
2723 @kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
2725 Note, that there are some useful settings already. Accessing your
2726 local host as @samp{root} user, is possible just by @kbd{C-x C-f
2729 @item Use configuration possibilities of your method:
2731 Several connection methods (i.e. the programs used) offer powerful
2732 configuration possibilities (@pxref{Customizing Completion}). In the
2733 given case, this could be @file{~/.ssh/config}:
2737 HostName news.my.domain
2741 The file name left to type would be @kbd{C-x C-f @trampfn{ssh, , xy,
2742 /opt/news/etc}}. Depending on files in your directories, it is even
2743 possible to complete the hostname with @kbd{C-x C-f
2744 @value{prefix}ssh@value{postfixhop}x @key{TAB}}.
2746 @item Use environment variables:
2748 File names typed in the minibuffer can be expanded by environment
2749 variables. You can set them outside @value{emacsname}, or even with
2753 (setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")
2756 Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you
2757 are. The disadvantage is, that you cannot edit the file name, because
2758 environment variables are not expanded during editing in the
2761 @item Define own keys:
2763 You can define your own key sequences in @value{emacsname}, which can
2764 be used instead of @kbd{C-x C-f}:
2768 [(control x) (control y)]
2774 "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))))
2777 Simply typing @kbd{C-x C-y} would initialize the minibuffer for
2778 editing with your beloved file name.
2780 See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the
2781 Emacs Wiki} for a more comprehensive example.
2783 @item Define own abbreviation (1):
2785 It is possible to define an own abbreviation list for expanding file
2790 'directory-abbrev-alist
2791 '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
2794 This shortens the file openening command to @kbd{C-x C-f /xy
2795 @key{RET}}. The disadvantage is, again, that you cannot edit the file
2796 name, because the expansion happens after entering the file name only.
2798 @item Define own abbreviation (2):
2800 The @code{abbrev-mode} gives more flexibility for editing the
2804 (define-abbrev-table 'my-tramp-abbrev-table
2805 '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))
2808 'minibuffer-setup-hook
2811 (setq local-abbrev-table my-tramp-abbrev-table)))
2813 (defadvice minibuffer-complete
2814 (before my-minibuffer-complete activate)
2817 ;; If you use partial-completion-mode
2818 (defadvice PC-do-completion
2819 (before my-PC-do-completion activate)
2823 After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is
2824 expanded, and you can continue editing.
2826 @item Use bookmarks:
2828 Bookmarks can be used to visit Tramp files or directories.
2830 @pxref{Bookmarks, , , @value{emacsdir}}
2833 When you have opened @file{@trampfn{ssh, news, news.my.domain,
2834 /opt/news/etc/}}, you should save the bookmark via
2836 @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}.
2839 @kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}.
2842 Later on, you can always navigate to that bookmark via
2844 @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}.
2847 @kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}.
2850 @item Use recent files:
2858 remembers visited places.
2861 @pxref{File Conveniences, , , @value{emacsdir}}
2864 @pxref{recent-files, , , edit-utils}
2868 You could keep remote file names in the recent list without checking
2869 their readability through a remote access:
2876 (recent-files-initialize)
2880 (when (file-remote-p (buffer-file-name))
2881 (recent-files-make-permanent)))
2886 The list of files opened recently is reachable via
2888 @kbd{@key{menu-bar} @key{file} @key{Open Recent}}.
2891 @kbd{@key{menu-bar} @key{Recent Files}}.
2895 @item Use filecache:
2897 @file{filecache} remembers visited places. Add the directory into
2901 (eval-after-load "filecache"
2902 '(file-cache-add-directory
2903 "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
2906 Whenever you want to load a file, you can enter @kbd{C-x C-f
2907 C-@key{TAB}} in the minibuffer. The completion is done for the given
2914 @file{bbdb} has a built-in feature for @value{ftppackagename} files,
2915 which works also for @value{tramp}.
2917 @pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb}
2920 You need to load @file{bbdb}:
2927 Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}.
2928 Because BBDB is not prepared for @value{tramp} syntax, you must
2929 specify a method together with the user name, when needed. Example:
2932 @kbd{M-x bbdb-create-ftp-site @key{RET}}
2933 @b{Ftp Site:} news.my.domain @key{RET}
2934 @b{Ftp Directory:} /opt/news/etc/ @key{RET}
2935 @b{Ftp Username:} ssh@value{postfixhop}news @key{RET}
2936 @b{Company:} @key{RET}
2937 @b{Additional Comments:} @key{RET}
2940 When you have opened your BBDB buffer, you can access such an entry by
2941 pressing the key @key{F}.
2946 I would like to thank all @value{tramp} users, who have contributed to
2947 the different recipes!
2951 How can I disable @value{tramp}?
2953 Shame on you, why did you read until now?
2956 If you just want to have @value{ftppackagename} as default remote
2957 files access package, you should apply the following code:
2960 (setq tramp-default-method "ftp")
2964 Unloading @value{tramp} can be achieved by applying @kbd{M-x
2965 tramp-unload-tramp}.
2967 This resets also the @value{ftppackagename} plugins.
2972 @c For the developer
2973 @node Version Control
2974 @chapter The inner workings of remote version control
2975 @cindex Version Control
2977 Unlike @value{ftppackagename}, @value{tramp} has full shell access to the
2978 remote machine. This makes it possible to provide version control for
2979 files accessed under @value{tramp}.
2981 The actual version control binaries must be installed on the remote
2982 machine, accessible in the directories specified in
2983 @code{tramp-remote-path}.
2985 This transparent integration with the version control systems is one of
2986 the most valuable features provided by @value{tramp}, but it is far from perfect.
2987 Work is ongoing to improve the transparency of the system.
2990 * Version Controlled Files:: Determining if a file is under version control.
2991 * Remote Commands:: Executing the version control commands on the remote machine.
2992 * Changed workfiles:: Detecting if the working file has changed.
2993 * Checking out files:: Bringing the workfile out of the repository.
2994 * Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
2998 @node Version Controlled Files
2999 @section Determining if a file is under version control
3001 The VC package uses the existence of on-disk revision control master
3002 files to determine if a given file is under revision control. These file
3003 tests happen on the remote machine through the standard @value{tramp} mechanisms.
3006 @node Remote Commands
3007 @section Executing the version control commands on the remote machine
3009 There are no hooks provided by VC to allow intercepting of the version
3010 control command execution. The calls occur through the
3011 @code{call-process} mechanism, a function that is somewhat more
3012 efficient than the @code{shell-command} function but that does not
3013 provide hooks for remote execution of commands.
3015 To work around this, the functions @code{vc-do-command} and
3016 @code{vc-simple-command} have been advised to intercept requests for
3017 operations on files accessed via @value{tramp}.
3019 In the case of a remote file, the @code{shell-command} interface is
3020 used, with some wrapper code, to provide the same functionality on the
3021 remote machine as would be seen on the local machine.
3024 @node Changed workfiles
3025 @section Detecting if the working file has changed
3027 As there is currently no way to get access to the mtime of a file on a
3028 remote machine in a portable way, the @code{vc-workfile-unchanged-p}
3029 function is advised to call an @value{tramp} specific function for remote files.
3031 The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC
3032 diff functionality to determine if any changes have occurred between the
3033 workfile and the version control master.
3035 This requires that a shell command be executed remotely, a process that
3036 is notably heavier-weight than the mtime comparison used for local
3037 files. Unfortunately, unless a portable solution to the issue is found,
3038 this will remain the cost of remote version control.
3041 @node Checking out files
3042 @section Bringing the workfile out of the repository
3044 VC will, by default, check for remote files and refuse to act on them
3045 when checking out files from the repository. To work around this
3046 problem, the function @code{vc-checkout} knows about @value{tramp} files and
3047 allows version control to occur.
3050 @node Miscellaneous Version Control
3051 @section Things related to Version Control that don't fit elsewhere
3053 Minor implementation details, &c.
3056 * Remote File Ownership:: How VC determines who owns a workfile.
3057 * Back-end Versions:: How VC determines what release your RCS is.
3061 @node Remote File Ownership
3062 @subsection How VC determines who owns a workfile
3064 @value{emacsname} provides the @code{user-login-name} function to
3065 return the login name of the current user as well as mapping from
3066 arbitrary user id values back to login names. The VC code uses this
3067 functionality to map from the uid of the owner of a workfile to the
3068 login name in some circumstances.
3070 This will not, for obvious reasons, work if the remote system has a
3071 different set of logins. As such, it is necessary to delegate to the
3072 remote machine the job of determining the login name associated with a
3075 Unfortunately, with the profusion of distributed management systems such
3076 as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple,
3077 reliable and portable method for performing this mapping.
3079 Thankfully, the only place in the VC code that depends on the mapping of
3080 a uid to a login name is the @code{vc-file-owner} function. This returns
3081 the login of the owner of the file as a string.
3083 This function has been advised to use the output of @command{ls} on the
3084 remote machine to determine the login name, delegating the problem of
3085 mapping the uid to the login to the remote system which should know more
3089 @node Back-end Versions
3090 @subsection How VC determines what release your RCS is
3092 VC needs to know what release your revision control binaries you are
3093 running as not all features VC supports are available with older
3094 versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}.
3096 The default implementation of VC determines this value the first time it
3097 is needed and then stores the value globally to avoid the overhead of
3098 executing a process and parsing its output each time the information is
3101 Unfortunately, life is not quite so easy when remote version control
3102 comes into the picture. Each remote machine may have a different version
3103 of the version control tools and, while this is painful, we need to
3104 ensure that unavailable features are not used remotely.
3106 To resolve this issue, @value{tramp} currently takes the sledgehammer
3107 approach of making the release values of the revision control tools
3108 local to each @value{tramp} buffer, forcing VC to determine these values
3109 again each time a new file is visited.
3111 This has, quite obviously, some performance implications. Thankfully,
3112 most of the common operations performed by VC do not actually require
3113 that the remote version be known. This makes the problem far less
3116 Eventually these values will be captured by @value{tramp} on a system by
3117 system basis and the results cached to improve performance.
3120 @node Files directories and localnames
3121 @chapter How file names, directories and localnames are mangled and managed.
3124 * Localname deconstruction:: Breaking a localname into its components.
3126 * External packages:: Integration with external Lisp packages.
3131 @node Localname deconstruction
3132 @section Breaking a localname into its components.
3134 @value{tramp} file names are somewhat different, obviously, to ordinary file
3135 names. As such, the lisp functions @code{file-name-directory} and
3136 @code{file-name-nondirectory} are overridden within the @value{tramp}
3139 Their replacements are reasonably simplistic in their approach. They
3140 dissect the filename, call the original handler on the localname and
3141 then rebuild the @value{tramp} file name with the result.
3143 This allows the platform specific hacks in the original handlers to take
3144 effect while preserving the @value{tramp} file name information.
3148 @node External packages
3149 @section Integration with external Lisp packages.
3151 While reading filenames in the minibuffer, @value{tramp} must decide
3152 whether it completes possible incomplete filenames, or not. Imagine
3153 there is the following situation: You have typed @kbd{C-x C-f
3154 @value{prefix}ssh@value{postfixhop} @key{TAB}}. @value{tramp} cannot
3155 know, whether @option{ssh} is a method or a host name. It checks
3156 therefore the last input character you have typed. If this is
3157 @key{TAB}, @key{SPACE} or @kbd{?}, @value{tramp} assumes that you are
3158 still in filename completion, and it does not connect to the possible
3159 remote host @option{ssh}.
3161 @vindex tramp-completion-mode
3162 External packages, which use other characters for completing filenames
3163 in the minibuffer, must signal this to @value{tramp}. For this case,
3164 the variable @code{tramp-completion-mode} can be bound temporarily to
3168 (let ((tramp-completion-mode t))
3174 @node Traces and Profiles
3175 @chapter How to Customize Traces
3177 All @value{tramp} messages are raised with a verbosity level. The
3178 verbosity level can be any number between 0 and 10. Only messages with
3179 a verbosity level less than or equal to @code{tramp-verbose} are
3182 The verbosity levels are
3184 @w{ 0} silent (no @value{tramp} messages at all)
3185 @*@indent @w{ 1} errors
3186 @*@indent @w{ 2} warnings
3187 @*@indent @w{ 3} connection to remote hosts (default verbosity)
3188 @*@indent @w{ 4} activities
3189 @*@indent @w{ 5} internal
3190 @*@indent @w{ 6} sent and received strings
3191 @*@indent @w{ 7} file caching
3192 @*@indent @w{ 8} connection properties
3193 @*@indent @w{10} traces (huge)
3195 When @code{tramp-verbose} is greater than or equal to 4, the messages
3196 are also written into a @value{tramp} debug buffer. This debug buffer
3197 is useful for analysing problems; sending a @value{tramp} bug report
3198 should be done with @code{tramp-verbose} set to a verbosity level of at
3199 least 6 (@pxref{Bug Reports}).
3201 The debug buffer is in
3203 @ref{Outline Mode, , , @value{emacsdir}}.
3208 That means, you can change the level of messages to be viewed. If you
3209 want, for example, see only messages up to verbosity level 5, you must
3210 enter @kbd{C-u 6 C-c C-q}.
3212 Other keys for navigating are described in
3213 @ref{Outline Visibility, , , @value{emacsdir}}.
3216 @value{tramp} errors are handled internally in order to raise the
3217 verbosity level 1 messages. When you want to get a Lisp backtrace in
3218 case of an error, you need to set both
3221 (setq debug-on-error t
3225 Sometimes, it might be even necessary to step through @value{tramp}
3226 function call traces. Such traces are enabled by the following code:
3231 (mapcar 'trace-function-background
3233 (all-completions "tramp-" obarray 'functionp)))
3234 (untrace-function 'tramp-read-passwd)
3235 (untrace-function 'tramp-gw-basic-authentication)
3238 The function call traces are inserted in the buffer
3239 @file{*trace-output*}. @code{tramp-read-passwd} and
3240 @code{tramp-gw-basic-authentication} shall be disabled when the
3241 function call traces are added to @value{tramp}, because both
3242 functions return password strings, which should not be distributed.
3246 @chapter Debatable Issues and What Was Decided
3249 @item The uuencode method does not always work.
3251 Due to the design of @value{tramp}, the encoding and decoding programs
3252 need to read from stdin and write to stdout. On some systems,
3253 @command{uudecode -o -} will read stdin and write the decoded file to
3254 stdout, on other systems @command{uudecode -p} does the same thing.
3255 But some systems have uudecode implementations which cannot do this at
3256 all---it is not possible to call these uudecode implementations with
3257 suitable parameters so that they write to stdout.
3259 Of course, this could be circumvented: the @code{begin foo 644} line
3260 could be rewritten to put in some temporary file name, then
3261 @command{uudecode} could be called, then the temp file could be
3262 printed and deleted.
3264 But I have decided that this is too fragile to reliably work, so on some
3265 systems you'll have to do without the uuencode methods.
3267 @item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs.
3269 The GNU Emacs maintainers wish to use a unified filename syntax for
3270 Ange-FTP and @value{tramp} so that users don't have to learn a new
3271 syntax. It is sufficient to learn some extensions to the old syntax.
3273 For the XEmacs maintainers, the problems caused from using a unified
3274 filename syntax are greater than the gains. The XEmacs package system
3275 uses EFS for downloading new packages. So, obviously, EFS has to be
3276 installed from the start. If the filenames were unified, @value{tramp}
3277 would have to be installed from the start, too.
3280 @strong{Note:} If you'd like to use a similar syntax like
3281 @value{ftppackagename}, you need the following settings in your init
3285 (setq tramp-unified-filenames t)
3289 The autoload of the @value{emacsname} @value{tramp} package must be
3290 disabled. This can be achieved by setting file permissions @code{000}
3291 to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}.
3293 In case of unified filenames, all @value{emacsname} download sites are
3294 added to @code{tramp-default-method-alist} with default method
3295 @option{ftp} @xref{Default Method}. These settings shouldn't be
3296 touched for proper working of the @value{emacsname} package system.
3298 The syntax for unified filenames is described in the @value{tramp} manual
3299 for @value{emacsothername}.
3303 @node GNU Free Documentation License
3304 @appendix GNU Free Documentation License
3305 @include doclicense.texi
3308 @comment node-name, next, previous, up
3309 @unnumbered Concept Index
3312 @c End of tramp.texi - the TRAMP User Manual
3317 @c * Say something about the .login and .profile files of the remote
3319 @c * Explain how tramp.el works in principle: open a shell on a remote
3320 @c host and then send commands to it.
3321 @c * Make terminology "inline" vs "out-of-band" consistent.
3322 @c It seems that "external" is also used instead of "out-of-band".
3325 @c ** Use `filename' resp. `file name' consistently.
3326 @c ** Use `host' resp. `machine' consistently.
3327 @c ** Consistent small or capitalized words especially in menues.
3330 arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808