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.
239 @chapter An overview of @value{tramp}
242 After the installation of @value{tramp} into your @value{emacsname}, you
243 will be able to access files on remote machines as though they were
244 local. Access to the remote file system for editing files, version
245 control, and @code{dired} are transparently enabled.
247 Your access to the remote machine can be with the @command{rsh},
248 @command{rlogin}, @command{telnet} programs or with any similar
249 connection method. This connection must pass @acronym{ASCII}
250 successfully to be usable but need not be 8-bit clean.
252 The package provides support for @command{ssh} connections out of the
253 box, one of the more common uses of the package. This allows
254 relatively secure access to machines, especially if @command{ftp}
257 The majority of activity carried out by @value{tramp} requires only that
258 the remote login is possible and is carried out at the terminal. In
259 order to access remote files @value{tramp} needs to transfer their content
260 to the local machine temporarily.
262 @value{tramp} can transfer files between the machines in a variety of ways.
263 The details are easy to select, depending on your needs and the
264 machines in question.
266 The fastest transfer methods (for large files) rely on a remote file
267 transfer package such as @command{rcp}, @command{scp} or
270 If the remote copy methods are not suitable for you, @value{tramp} also
271 supports the use of encoded transfers directly through the shell.
272 This requires that the @command{mimencode} or @command{uuencode} tools
273 are available on the remote machine. These methods are generally
274 faster for small files.
276 Within these limitations, @value{tramp} is quite powerful. It is worth
277 noting that, as of the time of writing, it is far from a polished
278 end-user product. For a while yet you should expect to run into rough
279 edges and problems with the code now and then.
281 It is finished enough that the developers use it for day to day work but
282 the installation and setup can be a little difficult to master, as can
285 @value{tramp} is still under active development and any problems you encounter,
286 trivial or major, should be reported to the @value{tramp} developers.
290 @subsubheading Behind the scenes
291 @cindex behind the scenes
292 @cindex details of operation
295 This section tries to explain what goes on behind the scenes when you
296 access a remote file through @value{tramp}.
298 Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name,
299 then hit @kbd{@key{TAB}} for completion. Suppose further that this is
300 the first time that @value{tramp} is invoked for the host in question. Here's
305 @value{tramp} discovers that it needs a connection to the host. So it
306 invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
307 @var{user}} or a similar tool to connect to the remote host.
308 Communication with this process happens through an
309 @value{emacsname} buffer, that is, the output from the remote end
313 The remote host may prompt for a login name (for @command{telnet}).
314 The login name is given in the file name, so @value{tramp} sends the
315 login name and a newline.
318 The remote host may prompt for a password or pass phrase (for
319 @command{rsh} or for @command{telnet} after sending the login name).
320 @value{tramp} displays the prompt in the minibuffer, asking you for the
321 password or pass phrase.
323 You enter the password or pass phrase. @value{tramp} sends it to the remote
324 host, followed by a newline.
327 @value{tramp} now waits for the shell prompt or for a message that the login
330 If @value{tramp} sees neither of them after a certain period of time (a minute,
331 say), then it issues an error message saying that it couldn't find the
332 remote shell prompt and shows you what the remote host has sent.
334 If @value{tramp} sees a @samp{login failed} message, it tells you so,
335 aborts the login attempt and allows you to try again.
338 Suppose that the login was successful and @value{tramp} sees the shell prompt
339 from the remote host. Now @value{tramp} invokes @command{/bin/sh} because
340 Bourne shells and C shells have different command
341 syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login
342 shell doesn't recognize @samp{exec /bin/sh} as a valid command.
343 Maybe you use the Scheme shell @command{scsh}@dots{}}
345 After the Bourne shell has come up, @value{tramp} sends a few commands to
346 ensure a good working environment. It turns off echoing, it sets the
347 shell prompt, and a few other things.
350 Now the remote shell is up and it good working order. Remember, what
351 was supposed to happen is that @value{tramp} tries to find out what files exist
352 on the remote host so that it can do filename completion.
354 So, @value{tramp} basically issues @command{cd} and @command{ls} commands and
355 also sometimes @command{echo} with globbing. Another command that is
356 often used is @command{test} to find out whether a file is writable or a
357 directory or the like. The output of each command is parsed for the
361 Suppose you are finished with filename completion, have entered @kbd{C-x
362 C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to
363 transfer the file contents from the remote host to the local host so
364 that you can edit them.
366 See above for an explanation of how @value{tramp} transfers the file contents.
368 For inline transfers, @value{tramp} issues a command like @samp{mimencode -b
369 /path/to/remote/file}, waits until the output has accumulated in the
370 buffer that's used for communication, then decodes that output to
371 produce the file contents.
373 For out-of-band transfers, @value{tramp} issues a command like the following:
375 rcp user@@host:/path/to/remote/file /tmp/tramp.4711
377 It then reads the local temporary file @file{/tmp/tramp.4711} into a
378 buffer and deletes the temporary file.
381 You now edit the buffer contents, blithely unaware of what has happened
382 behind the scenes. (Unless you have read this section, that is.) When
383 you are finished, you type @kbd{C-x C-s} to save the buffer.
386 Again, @value{tramp} transfers the file contents to the remote host either
387 inline or out-of-band. This is the reverse of what happens when reading
391 I hope this has provided you with a basic overview of what happens
392 behind the scenes when you open a file with @value{tramp}.
396 @node Obtaining Tramp
397 @chapter Obtaining Tramp.
398 @cindex obtaining Tramp
400 @value{tramp} is freely available on the Internet and the latest
401 release may be downloaded from
402 @uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
403 documentation and code for @value{tramp}, suitable for installation.
404 But GNU Emacs (22 or later) includes @value{tramp} already, and there
405 is a @value{tramp} package for XEmacs, as well. So maybe it is easier
406 to just use those. But if you want the bleeding edge, read
409 For the especially brave, @value{tramp} is available from CVS. The CVS
410 version is the latest version of the code and may contain incomplete
411 features or new issues. Use these versions at your own risk.
413 Instructions for obtaining the latest development version of @value{tramp}
414 from CVS can be found by going to the Savannah project page at the
415 following URL and then clicking on the CVS link in the navigation bar
419 @uref{http://savannah.gnu.org/projects/tramp/}
422 Or follow the example session below:
425 ] @strong{cd ~/@value{emacsdir}}
426 ] @strong{export CVS_RSH="ssh"}
427 ] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
431 You should now have a directory @file{~/@value{emacsdir}/tramp}
432 containing the latest version of @value{tramp}. You can fetch the latest
433 updates from the repository by issuing the command:
436 ] @strong{cd ~/@value{emacsdir}/tramp}
437 ] @strong{export CVS_RSH="ssh"}
438 ] @strong{cvs update -d}
442 Once you've got updated files from the CVS repository, you need to run
443 @command{autoconf} in order to get an up-to-date @file{configure}
447 ] @strong{cd ~/@value{emacsdir}/tramp}
451 People who have no direct CVS access (maybe because sitting behind a
452 blocking firewall), can try the
453 @uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly
454 CVS Tree Tarball} instead of.
458 @chapter History of @value{tramp}
460 @cindex development history
462 Development was started end of November 1998. The package was called
463 @file{rssh.el}, back then. It only provided one method to access a
464 file, using @command{ssh} to log in to a remote host and using
465 @command{scp} to transfer the file contents. After a while, the name
466 was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way,
467 many more methods for getting a remote shell and for transferring the
468 file contents were added. Support for VC was added.
470 The most recent addition of major features were the multi-hop methods
471 added in April 2000 and the unification of @value{tramp} and Ange-FTP
472 filenames in July 2002. In July 2004, multi-hop methods have been
473 replaced by proxy hosts. Running commands on remote hosts was
474 introduced in December 2005.
476 Support of gateways exists since April 2007.
479 In December 2001, @value{tramp} has been added to the XEmacs package
480 repository. Being part of the GNU Emacs repository happened in June
481 2002, the first release including @value{tramp} was GNU Emacs 22.1.
483 @value{tramp} is also a GNU/Linux Debian package since February 2001.
486 @c Installation chapter is necessary only in case of standalone
487 @c installation. Text taken from trampinst.texi.
488 @ifset installchapter
489 @include trampinst.texi
493 @chapter Configuring @value{tramp} for use
494 @cindex configuration
496 @cindex default configuration
497 @value{tramp} is (normally) fully functional when it is initially
498 installed. It is initially configured to use the @command{scp}
499 program to connect to the remote host. So in the easiest case, you
500 just type @kbd{C-x C-f} and then enter the filename
501 @file{@trampfn{, user, machine, /path/to.file}}.
503 On some hosts, there are problems with opening a connection. These are
504 related to the behavior of the remote shell. See @xref{Remote shell
505 setup}, for details on this.
507 If you do not wish to use these commands to connect to the remote
508 host, you should change the default connection and transfer method
509 that @value{tramp} uses. There are several different methods that @value{tramp}
510 can use to connect to remote machines and transfer files
511 (@pxref{Connection types}).
513 If you don't know which method is right for you, see @xref{Default
518 * Connection types:: Types of connections made to remote machines.
519 * Inline methods:: Inline methods.
520 * External transfer methods:: External transfer methods.
522 * Gateway methods:: Gateway methods.
524 * Default Method:: Selecting a default method.
525 Here we also try to help those who
526 don't have the foggiest which method
528 * Default User:: Selecting a default user.
529 * Default Host:: Selecting a default host.
530 * Multi-hops:: Connecting to a remote host using multiple hops.
531 * Customizing Methods:: Using Non-Standard Methods.
532 * Customizing Completion:: Selecting config files for user/host name completion.
533 * Password caching:: Reusing passwords for several connections.
534 * Connection caching:: Reusing connection related information.
535 * Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
536 * Remote shell setup:: Remote shell setup hints.
537 * Windows setup hints:: Issues with Cygwin ssh.
538 * Auto-save and Backup:: Auto-save and Backup.
542 @node Connection types
543 @section Types of connections made to remote machines.
544 @cindex connection types, overview
546 There are two basic types of transfer methods, each with its own
547 advantages and limitations. Both types of connection make use of a
548 remote shell access program such as @command{rsh}, @command{ssh} or
549 @command{telnet} to connect to the remote machine.
551 This connection is used to perform many of the operations that @value{tramp}
552 requires to make the remote file system transparently accessible from
553 the local machine. It is only when visiting files that the methods
556 @cindex inline methods
557 @cindex external transfer methods
558 @cindex external methods
559 @cindex out-of-band methods
560 @cindex methods, inline
561 @cindex methods, external transfer
562 @cindex methods, out-of-band
563 Loading or saving a remote file requires that the content of the file
564 be transfered between the two machines. The content of the file can be
565 transfered over the same connection used to log in to the remote
566 machine or the file can be transfered through another connection using
567 a remote copy program such as @command{rcp}, @command{scp} or
568 @command{rsync}. The former are called @dfn{inline methods}, the
569 latter are called @dfn{out-of-band methods} or @dfn{external transfer
570 methods} (@dfn{external methods} for short).
572 The performance of the external transfer methods is generally better
573 than that of the inline methods, at least for large files. This is
574 caused by the need to encode and decode the data when transferring
577 The one exception to this rule are the @command{scp} based transfer
578 methods. While these methods do see better performance when actually
579 transferring files, the overhead of the cryptographic negotiation at
580 startup may drown out the improvement in file transfer times.
582 External transfer methods should be configured such a way that they
583 don't require a password (with @command{ssh-agent}, or such alike).
584 Modern @command{scp} implementations offer options to reuse existing
585 @command{ssh} connections, see method @command{scpc}. If it isn't
586 possible, you should consider @ref{Password caching}, otherwise you
587 will be prompted for a password every copy action.
591 @section Inline methods
592 @cindex inline methods
593 @cindex methods, inline
595 The inline methods in @value{tramp} are quite powerful and can work in
596 situations where you cannot use an external transfer program to connect.
597 Inline methods are the only methods that work when connecting to the
598 remote machine via telnet. (There are also strange inline methods which
599 allow you to transfer files between @emph{user identities} rather than
602 These methods depend on the existence of a suitable encoding and
603 decoding command on remote machine. Locally, @value{tramp} may be able to
604 use features of @value{emacsname} to decode and encode the files or
605 it may require access to external commands to perform that task.
609 @cindex base-64 encoding
610 @value{tramp} checks the availability and usability of commands like
611 @command{mimencode} (part of the @command{metamail} package) or
612 @command{uuencode} on the remote host. The first reliable command
613 will be used. The search path can be customized, see @ref{Remote
616 If both commands aren't available on the remote host, @value{tramp}
617 transfers a small piece of Perl code to the remote host, and tries to
618 apply it for encoding and decoding.
626 Connect to the remote host with @command{rsh}. Due to the unsecure
627 connection it is recommended for very local host topology only.
629 On operating systems which provide the command @command{remsh} instead
630 of @command{rsh}, you can use the method @option{remsh}. This is true
631 for HP-UX or Cray UNICOS, for example.
638 Connect to the remote host with @command{ssh}. This is identical to
639 the previous option except that the @command{ssh} package is used,
640 making the connection more secure.
642 There are also two variants, @option{ssh1} and @option{ssh2}, that
643 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
644 explicitly select whether you want to use the SSH protocol version 1
645 or 2 to connect to the remote host. (You can also specify in
646 @file{~/.ssh/config}, the SSH configuration file, which protocol
647 should be used, and use the regular @option{ssh} method.)
649 Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
650 @command{ssh1} and @command{ssh2} commands explicitly. If you don't
651 know what these are, you do not need these options.
653 All the methods based on @command{ssh} have an additional kludgy
654 feature: you can specify a host name which looks like @file{host#42}
655 (the real host name, then a hash sign, then a port number). This
656 means to connect to the given host but to also pass @code{-p 42} as
657 arguments to the @command{ssh} command.
660 @item @option{telnet}
661 @cindex method telnet
662 @cindex telnet method
664 Connect to the remote host with @command{telnet}. This is as unsecure
665 as the @option{rsh} method.
672 This method does not connect to a remote host at all, rather it uses
673 the @command{su} program to allow you to edit files as another user.
674 With other words, a specified host name in the file name is silently
682 This is similar to the @option{su} method, but it uses @command{sudo}
683 rather than @command{su} to become a different user.
685 Note that @command{sudo} must be configured to allow you to start a
686 shell as the user. It would be nice if it was sufficient if
687 @command{ls} and @command{mimencode} were allowed, but that is not
688 easy to implement, so I haven't got around to it, yet.
695 As you would expect, this is similar to @option{ssh}, only a little
696 different. Whereas @option{ssh} opens a normal interactive shell on
697 the remote host, this option uses @samp{ssh -t -t @var{host} -l
698 @var{user} /bin/sh} to open a connection. This is useful for users
699 where the normal login shell is set up to ask them a number of
700 questions when logging in. This procedure avoids these questions, and
701 just gives @value{tramp} a more-or-less `standard' login shell to work
704 Note that this procedure does not eliminate questions asked by
705 @command{ssh} itself. For example, @command{ssh} might ask ``Are you
706 sure you want to continue connecting?'' if the host key of the remote
707 host is not known. @value{tramp} does not know how to deal with such a
708 question (yet), therefore you will need to make sure that you can log
709 in without such questions.
711 This is also useful for Windows users where @command{ssh}, when
712 invoked from an @value{emacsname} buffer, tells them that it is not
713 allocating a pseudo tty. When this happens, the login shell is wont
714 to not print any shell prompt, which confuses @value{tramp} mightily.
715 For reasons unknown, some Windows ports for @command{ssh} require the
716 doubled @samp{-t} option.
718 This supports the @samp{-p} kludge.
721 @item @option{krlogin}
722 @cindex method krlogin
723 @cindex krlogin method
724 @cindex Kerberos (with krlogin method)
726 This method is also similar to @option{ssh}. It only uses the
727 @command{krlogin -x} command to log in to the remote host.
734 This method is mostly interesting for Windows users using the PuTTY
735 implementation of SSH. It uses @samp{plink -ssh} to log in to the
738 This supports the @samp{-P} kludge.
740 Additionally, the methods @option{plink1} and @option{plink2} are
741 provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in
742 order to use SSH protocol version 1 or 2 explicitly.
744 CCC: Do we have to connect to the remote host once from the command
745 line to accept the SSH key? Maybe this can be made automatic?
747 CCC: Say something about the first shell command failing. This might
748 be due to a wrong setting of @code{tramp-rsh-end-of-line}.
751 @item @option{plinkx}
752 @cindex method plinkx
753 @cindex plinkx method
755 Another method using PuTTY on Windows. Instead of host names, it
756 expects PuTTY session names, calling @samp{plink -load @var{session}
757 -t"}. User names are relevant only in case the corresponding session
758 hasn't defined a user name. Different port numbers must be defined in
766 This is an experimental implementation of the fish protocol, known from
767 the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
768 the fish server implementation from the KDE kioslave. That means, the
769 file @file{~/.fishsrv.pl} is expected to reside on the remote host.
771 The implementation lacks good performance. The code is offered anyway,
772 maybe somebody can improve the performance.
777 @node External transfer methods
778 @section External transfer methods
779 @cindex methods, external transfer
780 @cindex methods, out-of-band
781 @cindex external transfer methods
782 @cindex out-of-band methods
784 The external transfer methods operate through multiple channels, using
785 the remote shell connection for many actions while delegating file
786 transfers to an external transfer utility.
788 This saves the overhead of encoding and decoding that multiplexing the
789 transfer through the one connection has with the inline methods.
791 Since external transfer methods need their own overhead opening a new
792 channel, all files which are smaller than @var{tramp-copy-size-limit}
793 are still transferred with the corresponding inline method. It should
794 provide a fair trade-off between both approaches.
797 @item @option{rcp} --- @command{rsh} and @command{rcp}
800 @cindex rcp (with rcp method)
801 @cindex rsh (with rcp method)
803 This method uses the @command{rsh} and @command{rcp} commands to connect
804 to the remote machine and transfer files. This is probably the fastest
805 connection method available.
807 The alternative method @option{remcp} uses the @command{remsh} and
808 @command{rcp} commands. It should be applied on machines where
809 @command{remsh} is used instead of @command{rsh}.
812 @item @option{scp} --- @command{ssh} and @command{scp}
815 @cindex scp (with scp method)
816 @cindex ssh (with scp method)
818 Using @command{ssh} to connect to the remote host and @command{scp} to
819 transfer files between the machines is the best method for securely
820 connecting to a remote machine and accessing files.
822 The performance of this option is also quite good. It may be slower than
823 the inline methods when you often open and close small files however.
824 The cost of the cryptographic handshake at the start of an @command{scp}
825 session can begin to absorb the advantage that the lack of encoding and
828 There are also two variants, @option{scp1} and @option{scp2}, that
829 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
830 explicitly select whether you want to use the SSH protocol version 1
831 or 2 to connect to the remote host. (You can also specify in
832 @file{~/.ssh/config}, the SSH configuration file, which protocol
833 should be used, and use the regular @option{scp} method.)
835 Two other variants, @option{scp1_old} and @option{scp2_old}, use the
836 @command{ssh1} and @command{ssh2} commands explicitly. If you don't
837 know what these are, you do not need these options.
839 All the @command{ssh} based methods support the kludgy @samp{-p}
840 feature where you can specify a port number to connect to in the host
841 name. For example, the host name @file{host#42} tells @value{tramp} to
842 specify @samp{-p 42} in the argument list for @command{ssh}, and to
843 specify @samp{-P 42} in the argument list for @command{scp}.
846 @item @option{sftp} --- @command{ssh} and @command{sftp}
849 @cindex sftp (with sftp method)
850 @cindex ssh (with sftp method)
852 That is mostly the same method as @option{scp}, but using
853 @command{sftp} as transfer command. So the same remarks are valid.
855 This command does not work like @value{ftppackagename}, where
856 @command{ftp} is called interactively, and all commands are send from
857 within this session. Instead of, @command{ssh} is used for login.
859 This method supports the @samp{-p} hack.
862 @item @option{rsync} --- @command{ssh} and @command{rsync}
865 @cindex rsync (with rsync method)
866 @cindex ssh (with rsync method)
868 Using the @command{ssh} command to connect securely to the remote
869 machine and the @command{rsync} command to transfer files is almost
870 identical to the @option{scp} method.
872 While @command{rsync} performs much better than @command{scp} when
873 transferring files that exist on both hosts, this advantage is lost if
874 the file exists only on one side of the connection.
876 The @command{rsync} based method may be considerably faster than the
877 @command{rcp} based methods when writing to the remote system. Reading
878 files to the local machine is no faster than with a direct copy.
880 This method supports the @samp{-p} hack.
883 @item @option{scpx} --- @command{ssh} and @command{scp}
886 @cindex scp (with scpx method)
887 @cindex ssh (with scpx method)
889 As you would expect, this is similar to @option{scp}, only a little
890 different. Whereas @option{scp} opens a normal interactive shell on
891 the remote host, this option uses @samp{ssh -t -t @var{host} -l
892 @var{user} /bin/sh} to open a connection. This is useful for users
893 where the normal login shell is set up to ask them a number of
894 questions when logging in. This procedure avoids these questions, and
895 just gives @value{tramp} a more-or-less `standard' login shell to work
898 This is also useful for Windows users where @command{ssh}, when
899 invoked from an @value{emacsname} buffer, tells them that it is not
900 allocating a pseudo tty. When this happens, the login shell is wont
901 to not print any shell prompt, which confuses @value{tramp} mightily.
903 This method supports the @samp{-p} hack.
906 @item @option{scpc} --- @command{ssh} and @command{scp}
909 @cindex scp (with scpx method)
910 @cindex ssh (with scpx method)
912 Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
913 @option{ControlMaster}. This allows @option{scp} to reuse an existing
914 @option{ssh} channel, which increases performance.
916 Before you use this method, you shall check whether your @option{ssh}
917 implementation does support this option. Try from the command line
920 ssh localhost -o ControlMaster=yes
923 This method supports the @samp{-p} hack.
926 @item @option{pscp} --- @command{plink} and @command{pscp}
929 @cindex pscp (with pscp method)
930 @cindex plink (with pscp method)
931 @cindex PuTTY (with pscp method)
933 This method is similar to @option{scp}, but it uses the
934 @command{plink} command to connect to the remote host, and it uses
935 @command{pscp} for transferring the files. These programs are part
936 of PuTTY, an SSH implementation for Windows.
938 This method supports the @samp{-P} hack.
941 @item @option{psftp} --- @command{plink} and @command{psftp}
944 @cindex psftp (with psftp method)
945 @cindex plink (with psftp method)
946 @cindex PuTTY (with psftp method)
948 As you would expect, this method is similar to @option{sftp}, but it
949 uses the @command{plink} command to connect to the remote host, and it
950 uses @command{psftp} for transferring the files. These programs are
951 part of PuTTY, an SSH implementation for Windows.
953 This method supports the @samp{-P} hack.
956 @item @option{fcp} --- @command{fsh} and @command{fcp}
959 @cindex fsh (with fcp method)
960 @cindex fcp (with fcp method)
962 This method is similar to @option{scp}, but it uses the @command{fsh}
963 command to connect to the remote host, and it uses @command{fcp} for
964 transferring the files. @command{fsh/fcp} are a front-end for
965 @command{ssh} which allow for reusing the same @command{ssh} session
966 for submitting several commands. This avoids the startup overhead of
967 @command{scp} (which has to establish a secure connection whenever it
968 is called). Note, however, that you can also use one of the inline
969 methods to achieve a similar effect.
971 This method uses the command @samp{fsh @var{host} -l @var{user}
972 /bin/sh -i} to establish the connection, it does not work to just say
973 @command{fsh @var{host} -l @var{user}}.
978 There is no inline method using @command{fsh} as the multiplexing
979 provided by the program is not very useful in our context. @value{tramp}
980 opens just one connection to the remote host and then keeps it open,
988 This is not a native @value{tramp} method. Instead of, it forwards all
989 requests to @value{ftppackagename}.
991 This works only for unified filenames, see @ref{Issues}.
995 @item @option{smb} --- @command{smbclient}
999 This is another not natural @value{tramp} method. It uses the
1000 @command{smbclient} command on different Unices in order to connect to
1001 an SMB server. An SMB server might be a Samba (or CIFS) server on
1002 another UNIX host or, more interesting, a host running MS Windows. So
1003 far, it is tested towards MS Windows NT, MS Windows 2000, and MS
1006 The first directory in the localname must be a share name on the remote
1007 host. Remember, that the @code{$} character in which default shares
1008 usually end, must be written @code{$$} due to environment variable
1009 substitution in file names. If no share name is given (i.e. remote
1010 directory @code{/}), all available shares are listed.
1012 Since authorization is done on share level, you will be prompted
1013 always for a password if you access another share on the same host.
1014 This can be suppressed by @ref{Password caching}.
1016 MS Windows uses for authorization both a user name and a domain name.
1017 Because of this, the @value{tramp} syntax has been extended: you can
1018 specify a user name which looks like @code{user%domain} (the real user
1019 name, then a percent sign, then the domain name). So, to connect to
1020 the machine @code{melancholia} as user @code{daniel} of the domain
1021 @code{BIZARRE}, and edit @file{.emacs} in the home directory (share
1022 @code{daniel$}) I would specify the filename @file{@trampfn{smb,
1023 daniel%BIZARRE, melancholia, /daniel$$/.emacs}}.
1025 Depending on the Windows domain configuration, a Windows user might be
1026 considered as domain user per default. In order to connect as local
1027 user, the WINS name of that machine must be given as domain name.
1028 Usually, it is the machine name in capital letters. In the example
1029 above, the local user @code{daniel} would be specified as
1030 @file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}.
1032 The domain name as well as the user name are optional. If no user
1033 name is specified at all, the anonymous user (without password
1034 prompting) is assumed. This is different from all other @value{tramp}
1035 methods, where in such a case the local user name is taken.
1037 The @option{smb} method supports the @samp{-p} hack.
1039 @strong{Please note:} If @value{emacsname} runs locally under MS
1040 Windows, this method isn't available. Instead of, you can use UNC
1041 file names like @file{//melancholia/daniel$$/.emacs}. The only
1042 disadvantage is that there's no possibility to specify another user
1049 @node Gateway methods
1050 @section Gateway methods
1051 @cindex methods, gateway
1052 @cindex gateway methods
1054 Gateway methods are not methods to access a remote host directly.
1055 These methods are intended to pass firewalls or proxy servers.
1056 Therefore, they can be used for proxy host declarations
1057 (@pxref{Multi-hops}) only.
1059 A gateway method must come always along with a method who supports
1060 port setting (referred to as @samp{-p} kludge). This is because
1061 @value{tramp} targets the accompanied method to
1062 @file{localhost#random_port}, from where the firewall or proxy server
1065 Gateway methods support user name and password declarations. These
1066 are used to authenticate towards the corresponding firewall or proxy
1067 server. They can be passed only if your friendly administrator has
1068 granted your access.
1071 @item @option{tunnel}
1072 @cindex method tunnel
1073 @cindex tunnel method
1075 This method implements an HTTP tunnel via the @command{CONNECT}
1076 command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server
1077 shall support this command.
1079 As authentication method, only @option{Basic Authentication} (see RFC
1080 2617) is implemented so far. If no port number is given in the
1081 declaration, port @option{8080} is used for the proxy server.
1084 @item @option{socks}
1085 @cindex method socks
1086 @cindex socks method
1088 The @command{socks} method provides access to SOCKSv5 servers (see
1089 RFC 1928). @option{Username/Password Authentication} according to RFC
1092 The default port number of the socks server is @option{1080}, if not
1093 specified otherwise.
1099 @node Default Method
1100 @section Selecting a default method
1101 @cindex default method
1103 @vindex tramp-default-method
1104 When you select an appropriate transfer method for your typical usage
1105 you should set the variable @code{tramp-default-method} to reflect that
1106 choice. This variable controls which method will be used when a method
1107 is not specified in the @value{tramp} file name. For example:
1110 (setq tramp-default-method "ssh")
1113 @vindex tramp-default-method-alist
1114 You can also specify different methods for certain user/host
1115 combinations, via the variable @code{tramp-default-method-alist}. For
1116 example, the following two lines specify to use the @option{ssh}
1117 method for all user names matching @samp{john} and the @option{rsync}
1118 method for all host names matching @samp{lily}. The third line
1119 specifies to use the @option{su} method for the user @samp{root} on
1120 the machine @samp{localhost}.
1123 (add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
1124 (add-to-list 'tramp-default-method-alist '("lily" "" "rsync"))
1125 (add-to-list 'tramp-default-method-alist
1126 '("\\`localhost\\'" "\\`root\\'" "su"))
1130 See the documentation for the variable
1131 @code{tramp-default-method-alist} for more details.
1133 External transfer methods are normally preferable to inline transfer
1134 methods, giving better performance.
1136 @xref{Inline methods}.
1137 @xref{External transfer methods}.
1139 Another consideration with the selection of transfer methods is the
1140 environment you will use them in and, especially when used over the
1141 Internet, the security implications of your preferred method.
1143 The @option{rsh} and @option{telnet} methods send your password as
1144 plain text as you log in to the remote machine, as well as
1145 transferring the files in such a way that the content can easily be
1146 read from other machines.
1148 If you need to connect to remote systems that are accessible from the
1149 Internet, you should give serious thought to using @option{ssh} based
1150 methods to connect. These provide a much higher level of security,
1151 making it a non-trivial exercise for someone to obtain your password
1152 or read the content of the files you are editing.
1155 @subsection Which method is the right one for me?
1156 @cindex choosing the right method
1158 Given all of the above, you are probably thinking that this is all fine
1159 and good, but it's not helping you to choose a method! Right you are.
1160 As a developer, we don't want to boss our users around but give them
1161 maximum freedom instead. However, the reality is that some users would
1162 like to have some guidance, so here I'll try to give you this guidance
1163 without bossing you around. You tell me whether it works @dots{}
1165 My suggestion is to use an inline method. For large files, out-of-band
1166 methods might be more efficient, but I guess that most people will want
1167 to edit mostly small files.
1169 I guess that these days, most people can access a remote machine by
1170 using @command{ssh}. So I suggest that you use the @option{ssh}
1171 method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost,
1172 /etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other
1175 If you can't use @option{ssh} to log in to the remote host, then
1176 select a method that uses a program that works. For instance, Windows
1177 users might like the @option{plink} method which uses the PuTTY
1178 implementation of @command{ssh}. Or you use Kerberos and thus like
1181 For the special case of editing files on the local host as another
1182 user, see the @option{su} or @option{sudo} methods. They offer
1183 shortened syntax for the @samp{root} account, like
1184 @file{@trampfn{su, , , /etc/motd}}.
1186 People who edit large files may want to consider @option{scpc} instead
1187 of @option{ssh}, or @option{pscp} instead of @option{plink}. These
1188 out-of-band methods are faster than inline methods for large files.
1189 Note, however, that out-of-band methods suffer from some limitations.
1190 Please try first whether you really get a noticeable speed advantage
1191 from using an out-of-band method! Maybe even for large files, inline
1192 methods are fast enough.
1196 @section Selecting a default user
1197 @cindex default user
1199 The user part of a @value{tramp} file name can be omitted. Usually,
1200 it is replaced by the user name you are logged in. Often, this is not
1201 what you want. A typical use of @value{tramp} might be to edit some
1202 files with root permissions on the local host. This case, you should
1203 set the variable @code{tramp-default-user} to reflect that choice.
1207 (setq tramp-default-user "root")
1210 @code{tramp-default-user} is regarded as obsolete, and will be removed
1213 @vindex tramp-default-user-alist
1214 You can also specify different users for certain method/host
1215 combinations, via the variable @code{tramp-default-user-alist}. For
1216 example, if you always have to use the user @samp{john} in the domain
1217 @samp{somewhere.else}, you can specify the following:
1220 (add-to-list 'tramp-default-user-alist
1221 '("ssh" ".*\\.somewhere\\.else\\'" "john"))
1225 See the documentation for the variable
1226 @code{tramp-default-user-alist} for more details.
1228 One trap to fall in must be known. If @value{tramp} finds a default
1229 user, this user will be passed always to the connection command as
1230 parameter (for example @samp{ssh here.somewhere.else -l john}. If you
1231 have specified another user for your command in its configuration
1232 files, @value{tramp} cannot know it, and the remote access will fail.
1233 If you have specified in the given example in @file{~/.ssh/config} the
1237 Host here.somewhere.else
1242 than you must discard selecting a default user by @value{tramp}. This
1243 will be done by setting it to @code{nil} (or @samp{lily}, likewise):
1246 (add-to-list 'tramp-default-user-alist
1247 '("ssh" "\\`here\\.somewhere\\.else\\'" nil))
1250 The last entry in @code{tramp-default-user-alist} could be your
1251 default user you'll apply predominantly. You shall @emph{append} it
1252 to that list at the end:
1255 (add-to-list 'tramp-default-user-alist '(nil nil "jonas") t)
1260 @section Selecting a default host
1261 @cindex default host
1263 @vindex tramp-default-host
1264 Finally, it is even possible to omit the host name part of a
1265 @value{tramp} file name. This case, the value of the variable
1266 @code{tramp-default-host} is used. Per default, it is initialized
1267 with the host name your local @value{emacsname} is running.
1269 If you, for example, use @value{tramp} mainly to contact the host
1270 @samp{target} as user @samp{john}, you can specify:
1273 (setq tramp-default-user "john"
1274 tramp-default-host "target")
1277 Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you
1278 to John's home directory on target.
1280 Note, however, that the most simplification @samp{/::} won't work,
1281 because @samp{/:} is the prefix for quoted file names.
1286 @section Connecting to a remote host using multiple hops
1290 Sometimes, the methods described before are not sufficient. Sometimes,
1291 it is not possible to connect to a remote host using a simple command.
1292 For example, if you are in a secured network, you might have to log in
1293 to a `bastion host' first before you can connect to the outside world.
1294 Of course, the target host may also require a bastion host.
1296 @vindex tramp-default-proxies-alist
1297 In order to specify such multiple hops, it is possible to define a proxy
1298 host to pass through, via the variable
1299 @code{tramp-default-proxies-alist}. This variable keeps a list of
1300 triples (@var{host} @var{user} @var{proxy}).
1302 The first matching item specifies the proxy host to be passed for a
1303 file name located on a remote target matching @var{user}@@@var{host}.
1304 @var{host} and @var{user} are regular expressions or @code{nil}, which
1305 is interpreted as a regular expression which always matches.
1307 @var{proxy} must be a Tramp filename which localname part is ignored.
1308 Method and user name on @var{proxy} are optional, which is interpreted
1309 with the default values.
1311 The method must be an inline or gateway method (@pxref{Inline
1312 methods}, @pxref{Gateway methods}).
1315 The method must be an inline method (@pxref{Inline methods}).
1317 If @var{proxy} is @code{nil}, no additional hop is required reaching
1318 @var{user}@@@var{host}.
1320 If you, for example, must pass the host @samp{bastion.your.domain} as
1321 user @samp{bird} for any remote host which is not located in your local
1325 (add-to-list 'tramp-default-proxies-alist
1326 '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}"))
1327 (add-to-list 'tramp-default-proxies-alist
1328 '("\\.your\\.domain\\'" nil nil))
1331 Please note the order of the code. @code{add-to-list} adds elements at the
1332 beginning of a list. Therefore, most relevant rules must be added last.
1334 Proxy hosts can be cascaded. If there is another host called
1335 @samp{jump.your.domain}, which is the only one in your local domain who
1336 is allowed connecting @samp{bastion.your.domain}, you can add another
1340 (add-to-list 'tramp-default-proxies-alist
1341 '("\\`bastion\\.your\\.domain\\'"
1343 "@trampfn{ssh, , jump.your.domain,}"))
1346 @var{proxy} can contain the patterns @code{%h} or @code{%u}. These
1347 patterns are replaced by the strings matching @var{host} or
1348 @var{user}, respectively.
1350 If you, for example, wants to work as @samp{root} on hosts in the
1351 domain @samp{your.domain}, but login as @samp{root} is disabled for
1352 non-local access, you might add the following rule:
1355 (add-to-list 'tramp-default-proxies-alist
1356 '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
1359 Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect
1360 first @samp{randomhost.your.domain} via @code{ssh} under your account
1361 name, and perform @code{sudo -u root} on that host afterwards. It is
1362 important to know that the given method is applied on the host which
1363 has been reached so far. @code{sudo -u root}, applied on your local
1364 host, wouldn't be useful here.
1366 This is the recommended configuration to work as @samp{root} on remote
1370 Finally, @code{tramp-default-proxies-alist} can be used to pass
1371 firewalls or proxy servers. Imagine your local network has a host
1372 @samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to
1373 the outer world. Your friendly administrator has granted you access
1374 under your user name to @samp{host.other.domain} on that proxy
1375 server.@footnote{HTTP tunnels are intended for secure SSL/TLS
1376 communication. Therefore, many proxy server restrict the tunnels to
1377 related target ports. You might need to run your ssh server on your
1378 target host @samp{host.other.domain} on such a port, like 443 (https).
1379 See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall}
1380 for discussion of ethical issues.} You would need to add the
1384 (add-to-list 'tramp-default-proxies-alist
1385 '("\\`host\\.other\\.domain\\'" nil
1386 "@trampfn{tunnel, , proxy.your.domain#3128,}"))
1389 Gateway methods can be declared as first hop only in a multiple hop
1394 @node Customizing Methods
1395 @section Using Non-Standard Methods
1396 @cindex customizing methods
1397 @cindex using non-standard methods
1398 @cindex create your own methods
1400 There is a variable @code{tramp-methods} which you can change if the
1401 predefined methods don't seem right.
1403 For the time being, I'll refer you to the Lisp documentation of that
1404 variable, accessible with @kbd{C-h v tramp-methods @key{RET}}.
1407 @node Customizing Completion
1408 @section Selecting config files for user/host name completion
1409 @cindex customizing completion
1410 @cindex selecting config files
1411 @vindex tramp-completion-function-alist
1413 The variable @code{tramp-completion-function-alist} is intended to
1414 customize which files are taken into account for user and host name
1415 completion (@pxref{Filename completion}). For every method, it keeps
1416 a set of configuration files, accompanied by a Lisp function able to
1417 parse that file. Entries in @code{tramp-completion-function-alist}
1418 have the form (@var{method} @var{pair1} @var{pair2} ...).
1420 Each @var{pair} is composed of (@var{function} @var{file}).
1421 @var{function} is responsible to extract user names and host names
1422 from @var{file} for completion. There are two functions which access
1425 @defun tramp-get-completion-function method
1426 This function returns the list of completion functions for @var{method}.
1430 (tramp-get-completion-function "rsh")
1432 @result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
1433 (tramp-parse-rhosts "~/.rhosts"))
1437 @defun tramp-set-completion-function method function-list
1438 This function sets @var{function-list} as list of completion functions
1443 (tramp-set-completion-function "ssh"
1444 '((tramp-parse-sconfig "/etc/ssh_config")
1445 (tramp-parse-sconfig "~/.ssh/config")))
1447 @result{} ((tramp-parse-sconfig "/etc/ssh_config")
1448 (tramp-parse-sconfig "~/.ssh/config"))
1452 The following predefined functions parsing configuration files exist:
1455 @item @code{tramp-parse-rhosts}
1456 @findex tramp-parse-rhosts
1458 This function parses files which are syntactical equivalent to
1459 @file{~/.rhosts}. It returns both host names and user names, if
1462 @item @code{tramp-parse-shosts}
1463 @findex tramp-parse-shosts
1465 This function parses files which are syntactical equivalent to
1466 @file{~/.ssh/known_hosts}. Since there are no user names specified
1467 in such files, it can return host names only.
1469 @item @code{tramp-parse-sconfig}
1470 @findex tramp-parse-shosts
1472 This function returns the host nicknames defined by @code{Host} entries
1473 in @file{~/.ssh/config} style files.
1475 @item @code{tramp-parse-shostkeys}
1476 @findex tramp-parse-shostkeys
1478 SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and
1479 @file{~/ssh2/hostkeys/*}. Hosts are coded in file names
1480 @file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names
1481 are always @code{nil}.
1483 @item @code{tramp-parse-sknownhosts}
1484 @findex tramp-parse-shostkeys
1486 Another SSH2 style parsing of directories like
1487 @file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This
1488 case, hosts names are coded in file names
1489 @file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}.
1491 @item @code{tramp-parse-hosts}
1492 @findex tramp-parse-hosts
1494 A function dedicated to @file{/etc/hosts} style files. It returns
1497 @item @code{tramp-parse-passwd}
1498 @findex tramp-parse-passwd
1500 A function which parses @file{/etc/passwd} like files. Obviously, it
1501 can return user names only.
1503 @item @code{tramp-parse-netrc}
1504 @findex tramp-parse-netrc
1506 Finally, a function which parses @file{~/.netrc} like files.
1509 If you want to keep your own data in a file, with your own structure,
1510 you might provide such a function as well. This function must meet
1511 the following conventions:
1513 @defun my-tramp-parse file
1514 @var{file} must be either a file name on your host, or @code{nil}.
1515 The function must return a list of (@var{user} @var{host}), which are
1516 taken as candidates for user and host name completion.
1520 (my-tramp-parse "~/.my-tramp-hosts")
1522 @result{} ((nil "toto") ("daniel" "melancholia"))
1527 @node Password caching
1528 @section Reusing passwords for several connections.
1531 Sometimes it is necessary to connect to the same remote host several
1532 times. Reentering passwords again and again would be annoying, when
1533 the chosen method does not support access without password prompt
1534 through own configuration.
1536 By default, @value{tramp} caches the passwords entered by you. They will
1537 be reused next time if a connection needs them for the same user name
1538 and host name, independently of the connection method.
1540 @vindex password-cache-expiry
1541 Passwords are not saved permanently, that means the password caching
1542 is limited to the lifetime of your @value{emacsname} session. You
1543 can influence the lifetime of password caching by customizing the
1544 variable @code{password-cache-expiry}. The value is the number of
1545 seconds how long passwords are cached. Setting it to @code{nil}
1546 disables the expiration.
1548 @findex tramp-clear-passwd
1549 A password is removed from the cache if a connection isn't established
1550 successfully. You can remove a password from the cache also by
1551 executing @kbd{M-x tramp-clear-passwd} in a buffer containing a
1552 related remote file or directory.
1554 @vindex password-cache
1555 If you don't like this feature for security reasons, password caching
1556 can be disabled totally by customizing the variable
1557 @code{password-cache} (setting it to @code{nil}).
1559 Implementation Note: password caching is based on the package
1560 @file{password.el} in No Gnus. For the time being, it is activated
1561 only when this package is seen in the @code{load-path} while loading
1563 @ifset installchapter
1564 If you don't use No Gnus, you can take @file{password.el} from the
1565 @value{tramp} @file{contrib} directory, see @ref{Installation
1568 It will be activated mandatory once No Gnus has found its way into
1572 @node Connection caching
1573 @section Reusing connection related information.
1576 @vindex tramp-persistency-file-name
1577 In order to reduce initial connection time, @value{tramp} stores
1578 connection related information persistently. The variable
1579 @code{tramp-persistency-file-name} keeps the file name where these
1580 information are written. Its default value is
1582 @file{~/.emacs.d/tramp}.
1585 @file{~/.xemacs/tramp}.
1587 It is recommended to choose a local file name.
1589 @value{tramp} reads this file during startup, and writes it when
1590 exiting @value{emacsname}. You can simply remove this file if
1591 @value{tramp} shall be urged to recompute these information next
1592 @value{emacsname} startup time.
1594 Using such persistent information can be disabled by setting
1595 @code{tramp-persistency-file-name} to @code{nil}.
1598 @node Remote Programs
1599 @section How @value{tramp} finds and uses programs on the remote machine.
1601 @value{tramp} depends on a number of programs on the remote host in order to
1602 function, including @command{ls}, @command{test}, @command{find} and
1605 In addition to these required tools, there are various tools that may be
1606 required based on the connection method. See @ref{Inline methods} and
1607 @ref{External transfer methods} for details on these.
1609 Certain other tools, such as @command{perl} (or @command{perl5}) and
1610 @command{grep} will be used if they can be found. When they are
1611 available, they are used to improve the performance and accuracy of
1614 @vindex tramp-remote-path
1615 When @value{tramp} connects to the remote machine, it searches for the
1616 programs that it can use. The variable @code{tramp-remote-path}
1617 controls the directories searched on the remote machine.
1619 By default, this is set to a reasonable set of defaults for most
1620 machines. The symbol @code{tramp-default-remote-path} is a place
1621 holder, it is replaced by the list of directories received via the
1622 command @command{getconf PATH} on your remote machine. For example,
1623 on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is
1624 @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is
1625 recommended to apply this symbol on top of @code{tramp-remote-path}.
1627 It is possible, however, that your local (or remote ;) system
1628 administrator has put the tools you want in some obscure local
1631 In this case, you can still use them with @value{tramp}. You simply
1632 need to add code to your @file{.emacs} to add the directory to the
1633 remote path. This will then be searched by @value{tramp} when you
1634 connect and the software found.
1636 To add a directory to the remote search path, you could use code such
1640 @i{;; We load @value{tramp} to define the variable.}
1642 @i{;; We have @command{perl} in "/usr/local/perl/bin"}
1643 (add-to-list 'tramp-remote-path "/usr/local/perl/bin")
1646 @value{tramp} caches several information, like the Perl binary
1647 location. The changed remote search path wouldn't affect these
1648 settings. In order to force @value{tramp} to recompute these values,
1649 you must exit @value{emacsname}, remove your persistency file
1650 (@pxref{Connection caching}), and restart @value{emacsname}.
1653 @node Remote shell setup
1654 @comment node-name, next, previous, up
1655 @section Remote shell setup hints
1656 @cindex remote shell setup
1657 @cindex @file{.profile} file
1658 @cindex @file{.login} file
1659 @cindex shell init files
1661 As explained in the @ref{Overview} section, @value{tramp} connects to the
1662 remote host and talks to the shell it finds there. Of course, when you
1663 log in, the shell executes its init files. Suppose your init file
1664 requires you to enter the birth date of your mother; clearly @value{tramp}
1665 does not know this and hence fails to log you in to that host.
1667 There are different possible strategies for pursuing this problem. One
1668 strategy is to enable @value{tramp} to deal with all possible situations.
1669 This is a losing battle, since it is not possible to deal with
1670 @emph{all} situations. The other strategy is to require you to set up
1671 the remote host such that it behaves like @value{tramp} expects. This might
1672 be inconvenient because you have to invest a lot of effort into shell
1673 setup before you can begin to use @value{tramp}.
1675 The package, therefore, pursues a combined approach. It tries to
1676 figure out some of the more common setups, and only requires you to
1677 avoid really exotic stuff. For example, it looks through a list of
1678 directories to find some programs on the remote host. And also, it
1679 knows that it is not obvious how to check whether a file exists, and
1680 therefore it tries different possibilities. (On some hosts and
1681 shells, the command @command{test -e} does the trick, on some hosts
1682 the shell builtin doesn't work but the program @command{/usr/bin/test
1683 -e} or @command{/bin/test -e} works. And on still other hosts,
1684 @command{ls -d} is the right way to do this.)
1686 Below you find a discussion of a few things that @value{tramp} does not deal
1687 with, and that you therefore have to set up correctly.
1690 @item @var{shell-prompt-pattern}
1691 @vindex shell-prompt-pattern
1693 After logging in to the remote host, @value{tramp} has to wait for the remote
1694 shell startup to finish before it can send commands to the remote
1695 shell. The strategy here is to wait for the shell prompt. In order to
1696 recognize the shell prompt, the variable @code{shell-prompt-pattern} has
1697 to be set correctly to recognize the shell prompt on the remote host.
1699 Note that @value{tramp} requires the match for @code{shell-prompt-pattern}
1700 to be at the end of the buffer. Many people have something like the
1701 following as the value for the variable: @code{"^[^>$][>$] *"}. Now
1702 suppose your shell prompt is @code{a <b> c $ }. In this case,
1703 @value{tramp} recognizes the @code{>} character as the end of the prompt,
1704 but it is not at the end of the buffer.
1706 @item @var{tramp-shell-prompt-pattern}
1707 @vindex tramp-shell-prompt-pattern
1709 This regular expression is used by @value{tramp} in the same way as
1710 @code{shell-prompt-pattern}, to match prompts from the remote shell.
1711 This second variable exists because the prompt from the remote shell
1712 might be different from the prompt from a local shell --- after all,
1713 the whole point of @value{tramp} is to log in to remote hosts as a
1714 different user. The default value of
1715 @code{tramp-shell-prompt-pattern} is the same as the default value of
1716 @code{shell-prompt-pattern}, which is reported to work well in many
1719 @item @command{tset} and other questions
1720 @cindex Unix command tset
1721 @cindex tset Unix command
1723 Some people invoke the @command{tset} program from their shell startup
1724 scripts which asks the user about the terminal type of the shell.
1725 Maybe some shells ask other questions when they are started.
1726 @value{tramp} does not know how to answer these questions. There are
1727 two approaches for dealing with this problem. One approach is to take
1728 care that the shell does not ask any questions when invoked from
1729 @value{tramp}. You can do this by checking the @code{TERM}
1730 environment variable, it will be set to @code{dumb} when connecting.
1732 @vindex tramp-terminal-type
1733 The variable @code{tramp-terminal-type} can be used to change this value
1736 @vindex tramp-actions-before-shell
1737 The other approach is to teach @value{tramp} about these questions. See
1738 the variable @code{tramp-actions-before-shell}. Example:
1741 (defconst my-tramp-prompt-regexp
1742 (concat (regexp-opt '("Enter the birth date of your mother:") t)
1744 "Regular expression matching my login prompt question.")
1746 (defun my-tramp-action (proc vec)
1747 "Enter \"19000101\" in order to give a correct answer."
1748 (save-window-excursion
1749 (with-current-buffer (tramp-get-connection-buffer vec)
1750 (tramp-message vec 6 "\n%s" (buffer-string))
1751 (tramp-send-string vec "19000101"))))
1753 (add-to-list 'tramp-actions-before-shell
1754 '(my-tramp-prompt-regexp my-tramp-action))
1758 @item Environment variables named like users in @file{.profile}
1760 If you have a user named frumple and set the variable @code{FRUMPLE} in
1761 your shell environment, then this might cause trouble. Maybe rename
1762 the variable to @code{FRUMPLE_DIR} or the like.
1764 This weird effect was actually reported by a @value{tramp} user!
1767 @item Non-Bourne commands in @file{.profile}
1769 After logging in to the remote host, @value{tramp} issues the command
1770 @command{exec /bin/sh}. (Actually, the command is slightly
1771 different.) When @command{/bin/sh} is executed, it reads some init
1772 files, such as @file{~/.shrc} or @file{~/.profile}.
1774 Now, some people have a login shell which is not @code{/bin/sh} but a
1775 Bourne-ish shell such as bash or ksh. Some of these people might put
1776 their shell setup into the files @file{~/.shrc} or @file{~/.profile}.
1777 This way, it is possible for non-Bourne constructs to end up in those
1778 files. Then, @command{exec /bin/sh} might cause the Bourne shell to
1779 barf on those constructs.
1781 As an example, imagine somebody putting @command{export FOO=bar} into
1782 the file @file{~/.profile}. The standard Bourne shell does not
1783 understand this syntax and will emit a syntax error when it reaches
1786 Another example is the tilde (@code{~}) character, say when adding
1787 @file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this
1788 character, and since there is usually no directory whose name consists
1789 of the single character tilde, strange things will happen.
1791 What can you do about this?
1793 Well, one possibility is to make sure that everything in
1794 @file{~/.shrc} and @file{~/.profile} on all remote hosts is
1795 Bourne-compatible. In the above example, instead of @command{export
1796 FOO=bar}, you might use @command{FOO=bar; export FOO} instead.
1798 The other possibility is to put your non-Bourne shell setup into some
1799 other files. For example, bash reads the file @file{~/.bash_profile}
1800 instead of @file{~/.profile}, if the former exists. So bash
1801 aficionados just rename their @file{~/.profile} to
1802 @file{~/.bash_profile} on all remote hosts, and Bob's your uncle.
1804 The @value{tramp} developers would like to circumvent this problem, so
1805 if you have an idea about it, please tell us. However, we are afraid
1806 it is not that simple: before saying @command{exec /bin/sh},
1807 @value{tramp} does not know which kind of shell it might be talking
1808 to. It could be a Bourne-ish shell like ksh or bash, or it could be a
1809 csh derivative like tcsh, or it could be zsh, or even rc. If the
1810 shell is Bourne-ish already, then it might be prudent to omit the
1811 @command{exec /bin/sh} step. But how to find out if the shell is
1817 @node Auto-save and Backup
1818 @section Auto-save and Backup configuration
1822 @vindex backup-directory-alist
1825 @vindex bkup-backup-directory-info
1828 Normally, @value{emacsname} writes backup files to the same directory
1829 as the original files, but this behavior can be changed via the
1832 @code{backup-directory-alist}.
1835 @code{bkup-backup-directory-info}.
1837 In connection with @value{tramp}, this can have unexpected side
1838 effects. Suppose that you specify that all backups should go to the
1839 directory @file{~/.emacs.d/backups/}, and then you edit the file
1840 @file{@trampfn{su, root, localhost, /etc/secretfile}}. The effect is
1841 that the backup file will be owned by you and not by root, thus
1842 possibly enabling others to see it even if they were not intended to
1847 @code{backup-directory-alist}
1850 @code{bkup-backup-directory-info}
1852 is @code{nil} (the default), such problems do not occur.
1854 Therefore, it is useful to set special values for @value{tramp}
1855 files. For example, the following statement effectively `turns off'
1858 @code{backup-directory-alist}
1861 @code{bkup-backup-directory-info}
1863 for @value{tramp} files:
1867 (add-to-list 'backup-directory-alist
1868 (cons tramp-file-name-regexp nil))
1873 (require 'backup-dir)
1874 (add-to-list 'bkup-backup-directory-info
1875 (list tramp-file-name-regexp ""))
1879 Another possibility is to use the @value{tramp} variable
1881 @code{tramp-backup-directory-alist}.
1884 @code{tramp-bkup-backup-directory-info}.
1886 This variable has the same meaning like
1888 @code{backup-directory-alist}.
1891 @code{bkup-backup-directory-info}.
1893 If a @value{tramp} file is backed up, and DIRECTORY is an absolute
1894 local file name, DIRECTORY is prepended with the @value{tramp} file
1895 name prefix of the file to be backed up.
1902 (add-to-list 'backup-directory-alist
1903 (cons "." "~/.emacs.d/backups/"))
1904 (setq tramp-backup-directory-alist backup-directory-alist)
1909 (require 'backup-dir)
1910 (add-to-list 'bkup-backup-directory-info
1911 (list "." "~/.emacs.d/backups/" 'full-path))
1912 (setq tramp-bkup-backup-directory-info bkup-backup-directory-info)
1917 The backup file name of @file{@trampfn{su, root, localhost,
1918 /etc/secretfile}} would be
1920 @file{@trampfn{su, root, localhost,
1921 ~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
1924 @file{@trampfn{su, root, localhost,
1925 ~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}
1928 The same problem can happen with auto-saving files.
1930 Since @value{emacsname} 21, the variable
1931 @code{auto-save-file-name-transforms} keeps information, on which
1932 directory an auto-saved file should go. By default, it is initialized
1933 for @value{tramp} files to the local temporary directory.
1935 On some versions of @value{emacsname}, namely the version built for
1936 Debian GNU/Linux, the variable @code{auto-save-file-name-transforms}
1937 contains the directory where @value{emacsname} was built. A
1938 workaround is to manually set the variable to a sane value.
1940 If auto-saved files should go into the same directory as the original
1941 files, @code{auto-save-file-name-transforms} should be set to @code{nil}.
1943 Another possibility is to set the variable
1944 @code{tramp-auto-save-directory} to a proper value.
1947 For this purpose you can set the variable @code{auto-save-directory}
1952 @node Windows setup hints
1953 @section Issues with Cygwin ssh
1954 @cindex Cygwin, issues
1956 This section needs a lot of work! Please help.
1958 @cindex method sshx with Cygwin
1959 @cindex sshx method with Cygwin
1960 The recent Cygwin installation of @command{ssh} works only with a
1961 Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x
1962 eshell}, and starting @kbd{ssh test.machine}. The problem is evident
1963 if you see a message like this:
1966 Pseudo-terminal will not be allocated because stdin is not a terminal.
1969 Older @command{ssh} versions of Cygwin are told to cooperate with
1970 @value{tramp} selecting @option{sshx} as the connection method. You
1971 can find information about setting up Cygwin in their FAQ at
1972 @uref{http://cygwin.com/faq/}.
1974 @cindex method scpx with Cygwin
1975 @cindex scpx method with Cygwin
1976 If you wish to use the @option{scpx} connection method, then you might
1977 have the problem that @value{emacsname} calls @command{scp} with a
1978 Windows filename such as @code{c:/foo}. The Cygwin version of
1979 @command{scp} does not know about Windows filenames and interprets
1980 this as a remote filename on the host @code{c}.
1982 One possible workaround is to write a wrapper script for @option{scp}
1983 which converts the Windows filename to a Cygwinized filename.
1985 @cindex Cygwin and ssh-agent
1986 @cindex SSH_AUTH_SOCK and @value{emacsname} on Windows
1987 If you want to use either @option{ssh} based method on Windows, then
1988 you might encounter problems with @command{ssh-agent}. Using this
1989 program, you can avoid typing the pass-phrase every time you log in.
1990 However, if you start @value{emacsname} from a desktop shortcut, then
1991 the environment variable @code{SSH_AUTH_SOCK} is not set and so
1992 @value{emacsname} and thus @value{tramp} and thus @command{ssh} and
1993 @command{scp} started from @value{tramp} cannot communicate with
1994 @command{ssh-agent}. It works better to start @value{emacsname} from
1997 If anyone knows how to start @command{ssh-agent} under Windows in such a
1998 way that desktop shortcuts can profit, please holler. I don't really
1999 know anything at all about Windows@dots{}
2003 @chapter Using @value{tramp}
2004 @cindex using @value{tramp}
2006 Once you have installed @value{tramp} it will operate fairly
2007 transparently. You will be able to access files on any remote machine
2008 that you can log in to as though they were local.
2010 Files are specified to @value{tramp} using a formalized syntax specifying the
2011 details of the system to connect to. This is similar to the syntax used
2012 by the @value{ftppackagename} package.
2015 Something that might happen which surprises you is that
2016 @value{emacsname} remembers all your keystrokes, so if you see a
2017 password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}}
2018 twice instead of once, then the second keystroke will be processed by
2019 @value{emacsname} after @value{tramp} has done its thing. Why, this
2020 type-ahead is normal behavior, you say. Right you are, but be aware
2021 that opening a remote file might take quite a while, maybe half a
2022 minute when a connection needs to be opened. Maybe after half a
2023 minute you have already forgotten that you hit that key!
2026 * Filename Syntax:: @value{tramp} filename conventions.
2027 * Alternative Syntax:: URL-like filename syntax.
2028 * Filename completion:: Filename completion.
2029 * Remote processes:: Integration with other @value{emacsname} packages.
2033 @node Filename Syntax
2034 @section @value{tramp} filename conventions
2035 @cindex filename syntax
2036 @cindex filename examples
2038 To access the file @var{localname} on the remote machine @var{machine}
2039 you would specify the filename @file{@trampfn{, , machine,
2040 localname}}. This will connect to @var{machine} and transfer the file
2041 using the default method. @xref{Default Method}.
2043 Some examples of @value{tramp} filenames are shown below.
2046 @item @trampfn{, , melancholia, .emacs}
2047 Edit the file @file{.emacs} in your home directory on the machine
2050 @item @trampfn{, , melancholia.danann.net, .emacs}
2051 This edits the same file, using the fully qualified domain name of
2054 @item @trampfn{, , melancholia, ~/.emacs}
2055 This also edits the same file --- the @file{~} is expanded to your
2056 home directory on the remote machine, just like it is locally.
2058 @item @trampfn{, , melancholia, ~daniel/.emacs}
2059 This edits the file @file{.emacs} in the home directory of the user
2060 @code{daniel} on the machine @code{melancholia}. The @file{~<user>}
2061 construct is expanded to the home directory of that user on the remote
2064 @item @trampfn{, , melancholia, /etc/squid.conf}
2065 This edits the file @file{/etc/squid.conf} on the machine
2070 Unless you specify a different name to use, @value{tramp} will use the
2071 current local user name as the remote user name to log in with. If you
2072 need to log in as a different user, you can specify the user name as
2073 part of the filename.
2075 To log in to the remote machine as a specific user, you use the syntax
2076 @file{@trampfn{, user, machine, path/to.file}}. That means that
2077 connecting to @code{melancholia} as @code{daniel} and editing
2078 @file{.emacs} in your home directory you would specify
2079 @file{@trampfn{, daniel, melancholia, .emacs}}.
2081 It is also possible to specify other file transfer methods
2082 (@pxref{Default Method}) as part of the filename.
2084 This is done by putting the method before the user and host name, as
2085 in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the
2089 This is done by replacing the initial @file{@value{prefix}} with
2090 @file{@value{prefix}<method>@value{postfixhop}}. (Note the trailing
2093 The user, machine and file specification remain the same.
2095 So, to connect to the machine @code{melancholia} as @code{daniel},
2096 using the @option{ssh} method to transfer files, and edit
2097 @file{.emacs} in my home directory I would specify the filename
2098 @file{@trampfn{ssh, daniel, melancholia, .emacs}}.
2101 @node Alternative Syntax
2102 @section URL-like filename syntax
2103 @cindex filename syntax
2104 @cindex filename examples
2106 Additionally to the syntax described in the previous chapter, it is
2107 possible to use a URL-like syntax for @value{tramp}. This can be
2108 switched on by customizing the variable @code{tramp-syntax}. Please
2109 note that this feature is experimental for the time being.
2111 The variable @code{tramp-syntax} must be set before requiring @value{tramp}:
2114 (setq tramp-syntax 'url)
2118 Then, a @value{tramp} filename would look like this:
2119 @file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}.
2120 @file{/@var{method}://} is mandatory, all other parts are optional.
2121 @file{:@var{port}} is useful for methods only who support this.
2123 The last example from the previous section would look like this:
2124 @file{/ssh://daniel@@melancholia/.emacs}.
2126 For the time being, @code{tramp-syntax} can have the following values:
2130 @item @code{ftp} -- That is the default syntax
2131 @item @code{url} -- URL-like syntax
2134 @item @code{sep} -- That is the default syntax
2135 @item @code{url} -- URL-like syntax
2136 @item @code{ftp} -- EFS-like syntax
2141 @node Filename completion
2142 @section Filename completion
2143 @cindex filename completion
2145 Filename completion works with @value{tramp} for completion of method
2146 names, of user names and of machine names as well as for completion of
2147 file names on remote machines.
2149 In order to enable this, Partial Completion mode must be set
2150 on@footnote{If you don't use Partial Completion mode, but want to
2151 keep full completion, load @value{tramp} like this in your
2155 ;; Preserve Tramp's completion features.
2156 (let ((partial-completion-mode t))
2161 @xref{Completion Options, , , @value{emacsdir}}.
2165 If you, for example, type @kbd{C-x C-f @value{prefix}t
2166 @key{TAB}}, @value{tramp} might give you as result the choice for
2170 @value{prefixhop}telnet@value{postfixhop} tmp/
2171 @value{prefixhop}toto@value{postfix}
2174 @value{prefixhop}telnet@value{postfixhop} @value{prefixhop}toto@value{postfix}
2178 @samp{@value{prefixhop}telnet@value{postfixhop}}
2179 is a possible completion for the respective method,
2181 @samp{tmp/} stands for the directory @file{/tmp} on your local
2184 and @samp{@value{prefixhop}toto@value{postfix}}
2185 might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts}
2186 file (given you're using default method @option{ssh}).
2188 If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to
2189 @samp{@value{prefix}telnet@value{postfixhop}}.
2190 Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in
2191 your @file{/etc/hosts} file, let's say
2194 @trampfn{telnet, , 127.0.0.1,} @trampfn{telnet, , 192.168.0.1,}
2195 @trampfn{telnet, , localhost,} @trampfn{telnet, , melancholia.danann.net,}
2196 @trampfn{telnet, , melancholia,}
2199 Now you can choose the desired machine, and you can continue to
2200 complete file names on that machine.
2202 If the configuration files (@pxref{Customizing Completion}), which
2203 @value{tramp} uses for analysis of completion, offer user names, those user
2204 names will be taken into account as well.
2206 Remote machines, which have been visited in the past and kept
2207 persistently (@pxref{Connection caching}), will be offered too.
2209 Once the remote machine identification is completed, it comes to
2210 filename completion on the remote host. This works pretty much like
2211 for files on the local host, with the exception that minibuffer
2212 killing via a double-slash works only on the filename part, except
2213 that filename part starts with @file{//}.
2215 @xref{Minibuffer File, , , @value{emacsdir}}.
2219 As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//etc}
2220 @key{TAB}} would result in
2221 @file{@trampfn{telnet, , melancholia, /etc}}, whereas
2222 @kbd{@trampfn{telnet, , melancholia, //etc} @key{TAB}} reduces the
2223 minibuffer contents to @file{/etc}. A triple-slash stands for the
2225 i.e. @kbd{@trampfn{telnet, , melancholia, /usr/local/bin///etc}
2226 @key{TAB}} expands directly to @file{/etc}.
2230 As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//}}
2231 would result in @file{@trampfn{telnet, , melancholia, /}}, whereas
2232 @kbd{@trampfn{telnet, , melancholia, //}} expands the minibuffer
2233 contents to @file{/}.
2237 @node Remote processes
2238 @section Integration with other @value{emacsname} packages.
2242 @value{tramp} supports running processes on a remote host. This
2243 allows to exploit @value{emacsname} packages without modification for
2244 remote file names. It does not work for the @option{ftp} and
2245 @option{smb} methods.
2247 Remote processes are started when a corresponding command is executed
2248 from a buffer belonging to a remote file or directory. Up to now, the
2249 packages @file{compile.el} (commands like @code{compile} and
2250 @code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}) have been
2251 integrated. Integration of further packages is planned, any help for
2254 When your program is not found in the default search path
2255 @value{tramp} sets on the remote machine, you should either use an
2256 absolute path, or extend @code{tramp-remote-path} (see @ref{Remote
2260 (add-to-list 'tramp-remote-path "~/bin")
2261 (add-to-list 'tramp-remote-path "/appli/pub/bin")
2264 The environment for your program can be adapted by customizing
2265 @code{tramp-remote-process-environment}. This variable is a list of
2266 strings. It is structured like @code{process-environment}. Each
2267 element is a string of the form ENVVARNAME=VALUE. An entry
2268 ENVVARNAME= disables the corresponding environment variable, which
2269 might have been set in your init file like @file{~/.profile}.
2272 Adding an entry can be performed via @code{add-to-list}:
2275 (add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")
2278 Changing or removing an existing entry is not encouraged. The default
2279 values are chosen for proper @value{tramp} work. Nevertheless, if for
2280 example a paranoid system administrator disallows changing the
2281 @var{$HISTORY} environment variable, you can customize
2282 @code{tramp-remote-process-environment}, or you can apply the
2283 following code in your @file{.emacs}:
2286 (let ((process-environment tramp-remote-process-environment))
2287 (setenv "HISTORY" nil)
2288 (setq tramp-remote-process-environment process-environment))
2291 If you use other @value{emacsname} packages which do not run
2292 out-of-the-box on a remote host, please let us know. We will try to
2293 integrate them as well. @xref{Bug Reports}.
2296 @subsection Running eshell on a remote host
2299 @value{tramp} is integrated into @file{eshell.el}. That is, you can
2300 open an interactive shell on your remote host, and run commands there.
2301 After you have started @code{eshell}, you could perform commands like
2305 @b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
2306 @b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET}
2308 @b{@trampfn{sudo, root, host, /etc} $} id @key{RET}
2309 uid=0(root) gid=0(root) groups=0(root)
2310 @b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET}
2312 @b{@trampfn{sudo, root, host, /etc} $}
2316 @anchor{Running a debugger on a remote host}
2317 @subsection Running a debugger on a remote host
2322 @file{gud.el} offers an unified interface to several symbolic
2326 (@ref{Debuggers, , , @value{emacsdir}}).
2329 With @value{tramp}, it is possible to debug programs on
2330 remote hosts. You can call @code{gdb} with a remote file name:
2333 @kbd{M-x gdb @key{RET}}
2334 @b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET}
2337 The file name can also be relative to a remote default directory.
2338 Given you are in a buffer that belongs to the remote directory
2339 @trampfn{ssh, , host, /home/user}, you could call
2342 @kbd{M-x perldb @key{RET}}
2343 @b{Run perldb (like this):} perl -d myprog.pl @key{RET}
2346 It is not possible to use just the absolute local part of a remote
2347 file name as program to debug, like @kbd{perl -d
2348 /home/user/myprog.pl}, though.
2350 Arguments of the program to be debugged are taken literally. That
2351 means file names as arguments must be given as ordinary relative or
2352 absolute file names, without any remote specification.
2356 @chapter Reporting Bugs and Problems
2359 Bugs and problems with @value{tramp} are actively worked on by the
2360 development team. Feature requests and suggestions are also more than
2363 The @value{tramp} mailing list is a great place to get information on
2364 working with @value{tramp}, solving problems and general discussion
2365 and advice on topics relating to the package. It is moderated so
2366 non-subscribers can post but messages will be delayed, possibly up to
2367 48 hours (or longer in case of holidays), until the moderator approves
2370 The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to
2371 this address go to all the subscribers. This is @emph{not} the address
2372 to send subscription requests to.
2374 Subscribing to the list is performed via
2375 @uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/,
2376 the @value{tramp} Mail Subscription Page}.
2378 To report a bug in @value{tramp}, you should execute @kbd{M-x
2379 tramp-bug}. This will automatically generate a buffer with the details
2380 of your system and @value{tramp} version.
2382 When submitting a bug report, please try to describe in excruciating
2383 detail the steps required to reproduce the problem, the setup of the
2384 remote machine and any special conditions that exist. You should also
2385 check that your problem is not described already in @xref{Frequently
2388 If you can identify a minimal test case that reproduces the problem,
2389 include that with your bug report. This will make it much easier for
2390 the development team to analyze and correct the problem.
2392 Before reporting the bug, you should set the verbosity level to 6
2393 (@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and
2394 repeat the bug. Then, include the contents of the @file{*tramp/foo*}
2395 and @file{*debug tramp/foo*} buffers in your bug report. A verbosity
2396 level greater than 6 will produce a very huge debug buffer, which is
2397 mostly not necessary for the analysis.
2399 Please be aware that, with a verbosity level of 6 or greater, the
2400 contents of files and directories will be included in the debug
2401 buffer. Passwords you've typed will never be included there.
2404 @node Frequently Asked Questions
2405 @chapter Frequently Asked Questions
2406 @cindex frequently asked questions
2411 Where can I get the latest @value{tramp}?
2413 @value{tramp} is available under the URL below.
2416 @uref{ftp://ftp.gnu.org/gnu/tramp/}
2419 There is also a Savannah project page.
2422 @uref{http://savannah.gnu.org/projects/tramp/}
2426 Which systems does it work on?
2428 The package has been used successfully on GNU Emacs 21, GNU Emacs 22
2429 and XEmacs 21 (starting with 21.4). Gateway methods are supported for
2432 The package was intended to work on Unix, and it really expects a
2433 Unix-like system on the remote end (except the @option{smb} method),
2434 but some people seemed to have some success getting it to work on MS
2435 Windows NT/2000/XP @value{emacsname}.
2437 There is some informations on @value{tramp} on NT at the following URL;
2438 many thanks to Joe Stoy for providing the information:
2439 @uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/}
2441 @c The link is broken. I've contacted Tom for clarification. Michael.
2443 The above mostly contains patches to old ssh versions; Tom Roche has a
2444 Web page with instructions:
2445 @uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html}
2449 How could I speed up @value{tramp}?
2451 In the backstage, @value{tramp} needs a lot of operations on the
2452 remote host. The time for transferring data from and to the remote
2453 host as well as the time needed to perform the operations there count.
2454 In order to speed up @value{tramp}, one could either try to avoid some
2455 of the operations, or one could try to improve their performance.
2457 Use an external transfer method, like @option{scpc}.
2459 Use caching. This is already enabled by default. Information about
2460 the remote host as well as the remote files are cached for reuse. The
2461 information about remote hosts is kept in the file specified in
2462 @code{tramp-persistency-file-name}. Keep this file.
2464 Disable version control. If you access remote files which are not
2465 under version control, a lot of check operations can be avoided by
2466 disabling VC. This can be achieved by
2469 (setq vc-handled-backends nil)
2472 Disable excessive traces. The default trace level of @value{tramp},
2473 defined in the variable @code{tramp-verbose}, is 3. You should
2474 increase this level only temporarily, hunting bugs.
2478 @value{tramp} does not connect to the remote host
2480 When @value{tramp} does not connect to the remote host, there are two
2481 reasons heading the bug mailing list:
2486 Unknown characters in the prompt
2488 @value{tramp} needs to recognize the prompt on the remote machine
2489 after execution any command. This is not possible, when the prompt
2490 contains unknown characters like escape sequences for coloring. This
2491 should be avoided on the remote side. @xref{Remote shell setup}. for
2492 setting the regular expression detecting the prompt.
2494 You can check your settings after an unsuccessful connection by
2495 switching to the @value{tramp} connection buffer @file{*tramp/foo*},
2496 setting the cursor at the top of the buffer, and applying the expression
2499 @kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))}
2502 If it fails, or the cursor is not moved at the end of the buffer, your
2503 prompt is not recognised correctly.
2505 A special problem is the zsh, which uses left-hand side and right-hand
2506 side prompts in parallel. Therefore, it is necessary to disable the
2507 zsh line editor on the remote host. You shall add to @file{~/.zshrc}
2508 the following command:
2511 [ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
2516 @value{tramp} doesn't transfer strings with more than 500 characters
2519 On some few systems, the implementation of @code{process-send-string}
2520 seems to be broken for longer strings. It is reported for HP-UX,
2521 FreeBSD and Tru64 Unix, for example. This case, you should customize
2522 the variable @code{tramp-chunksize} to 500. For a description how to
2523 determine whether this is necessary see the documentation of
2524 @code{tramp-chunksize}.
2526 Additionally, it will be useful to set @code{file-precious-flag} to
2527 @code{t} for @value{tramp} files. Then the file contents will be
2528 written into a temporary file first, which is checked for correct
2531 @pxref{Saving Buffers, , , elisp}
2538 (when (file-remote-p default-directory)
2539 (set (make-local-variable 'file-precious-flag) t))))
2546 File name completion does not work with @value{tramp}
2548 When you log in to the remote machine, do you see the output of
2549 @command{ls} in color? If so, this may be the cause of your problems.
2551 @command{ls} outputs @acronym{ANSI} escape sequences that your terminal
2552 emulator interprets to set the colors. These escape sequences will
2553 confuse @value{tramp} however.
2555 In your @file{.bashrc}, @file{.profile} or equivalent on the remote
2556 machine you probably have an alias configured that adds the option
2557 @option{--color=yes} or @option{--color=auto}.
2559 You should remove that alias and ensure that a new login @emph{does not}
2560 display the output of @command{ls} in color. If you still cannot use
2561 filename completion, report a bug to the @value{tramp} developers.
2565 File name completion does not work in large directories
2567 @value{tramp} uses globbing for some operations. (Globbing means to use the
2568 shell to expand wildcards such as `*.c'.) This might create long
2569 command lines, especially in directories with many files. Some shells
2570 choke on long command lines, or don't cope well with the globbing
2573 If you have a large directory on the remote end, you may wish to execute
2574 a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs.
2575 Note that you must first start the right shell, which might be
2576 @command{/bin/sh}, @command{ksh} or @command{bash}, depending on which
2577 of those supports tilde expansion.
2581 How can I get notified when @value{tramp} file transfers are complete?
2583 The following snippet can be put in your @file{~/.emacs} file. It
2584 makes @value{emacsname} beep after reading from or writing to the
2588 (defadvice tramp-handle-write-region
2589 (after tramp-write-beep-advice activate)
2590 " make tramp beep after writing a file."
2594 (defadvice tramp-handle-do-copy-or-rename-file
2595 (after tramp-copy-beep-advice activate)
2596 " make tramp beep after copying a file."
2600 (defadvice tramp-handle-insert-file-contents
2601 (after tramp-copy-beep-advice activate)
2602 " make tramp beep after copying a file."
2610 I'ld like to see a host indication in the mode line when I'm remote
2612 The following code has been tested with @value{emacsname} 22.1. You
2613 should put it into your @file{~/.emacs}:
2616 (defconst my-mode-line-buffer-identification
2620 (if (file-remote-p default-directory)
2621 (tramp-file-name-host
2622 (tramp-dissect-file-name default-directory))
2624 (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
2625 (substring host-name 0 (match-beginning 1))
2630 mode-line-buffer-identification
2631 my-mode-line-buffer-identification)
2637 mode-line-buffer-identification
2638 my-mode-line-buffer-identification)))
2641 Since @value{emacsname} 23.1, the mode line contains an indication if
2642 @code{default-directory} for the current buffer is on a remote host.
2643 The corresponding tooltip includes the name of that host. If you
2644 still want the host name as part of the mode line, you can use the
2645 example above, but the @code{:eval} clause can be simplified:
2650 (or (file-remote-p default-directory 'host)
2652 (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
2653 (substring host-name 0 (match-beginning 1))
2661 My remote host does not understand default directory listing options
2663 @value{emacsname} computes the @command{dired} options depending on
2664 the local host you are working. If your @command{ls} command on the
2665 remote host does not understand those options, you can change them
2670 'dired-before-readin-hook
2672 (when (file-remote-p default-directory)
2673 (setq dired-actual-switches "-al"))))
2679 There's this @file{~/.sh_history} file on the remote host which keeps
2680 growing and growing. What's that?
2682 Sometimes, @value{tramp} starts @command{ksh} on the remote host for
2683 tilde expansion. Maybe @command{ksh} saves the history by default.
2684 @value{tramp} tries to turn off saving the history, but maybe you have
2685 to help. For example, you could put this in your @file{.kshrc}:
2688 if [ -f $HOME/.sh_history ] ; then
2689 /bin/rm $HOME/.sh_history
2691 if [ "$@{HISTFILE-unset@}" != "unset" ] ; then
2694 if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then
2700 @item There are longish file names to type. How to shorten this?
2702 Let's say you need regularly access to @file{@trampfn{ssh, news,
2703 news.my.domain, /opt/news/etc}}, which is boring to type again and
2704 again. The following approaches can be mixed:
2708 @item Use default values for method and user name:
2710 You can define default methods and user names for hosts,
2711 (@pxref{Default Method}, @pxref{Default User}):
2714 (setq tramp-default-method "ssh"
2715 tramp-default-user "news")
2718 The file name left to type would be
2719 @kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
2721 Note, that there are some useful settings already. Accessing your
2722 local host as @samp{root} user, is possible just by @kbd{C-x C-f
2725 @item Use configuration possibilities of your method:
2727 Several connection methods (i.e. the programs used) offer powerful
2728 configuration possibilities (@pxref{Customizing Completion}). In the
2729 given case, this could be @file{~/.ssh/config}:
2733 HostName news.my.domain
2737 The file name left to type would be @kbd{C-x C-f @trampfn{ssh, , xy,
2738 /opt/news/etc}}. Depending on files in your directories, it is even
2739 possible to complete the hostname with @kbd{C-x C-f
2740 @value{prefix}ssh@value{postfixhop}x @key{TAB}}.
2742 @item Use environment variables:
2744 File names typed in the minibuffer can be expanded by environment
2745 variables. You can set them outside @value{emacsname}, or even with
2749 (setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")
2752 Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you
2753 are. The disadvantage is, that you cannot edit the file name, because
2754 environment variables are not expanded during editing in the
2757 @item Define own keys:
2759 You can define your own key sequences in @value{emacsname}, which can
2760 be used instead of @kbd{C-x C-f}:
2764 [(control x) (control y)]
2770 "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))))
2773 Simply typing @kbd{C-x C-y} would initialize the minibuffer for
2774 editing with your beloved file name.
2776 See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the
2777 Emacs Wiki} for a more comprehensive example.
2779 @item Define own abbreviation (1):
2781 It is possible to define an own abbreviation list for expanding file
2786 'directory-abbrev-alist
2787 '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
2790 This shortens the file openening command to @kbd{C-x C-f /xy
2791 @key{RET}}. The disadvantage is, again, that you cannot edit the file
2792 name, because the expansion happens after entering the file name only.
2794 @item Define own abbreviation (2):
2796 The @code{abbrev-mode} gives more flexibility for editing the
2800 (define-abbrev-table 'my-tramp-abbrev-table
2801 '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))
2804 'minibuffer-setup-hook
2807 (setq local-abbrev-table my-tramp-abbrev-table)))
2809 (defadvice minibuffer-complete
2810 (before my-minibuffer-complete activate)
2813 ;; If you use partial-completion-mode
2814 (defadvice PC-do-completion
2815 (before my-PC-do-completion activate)
2819 After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is
2820 expanded, and you can continue editing.
2822 @item Use bookmarks:
2824 Bookmarks can be used to visit Tramp files or directories.
2826 @pxref{Bookmarks, , , @value{emacsdir}}
2829 When you have opened @file{@trampfn{ssh, news, news.my.domain,
2830 /opt/news/etc/}}, you should save the bookmark via
2832 @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}.
2835 @kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}.
2838 Later on, you can always navigate to that bookmark via
2840 @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}.
2843 @kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}.
2846 @item Use recent files:
2854 remembers visited places.
2857 @pxref{File Conveniences, , , @value{emacsdir}}
2860 @pxref{recent-files, , , edit-utils}
2864 You could keep remote file names in the recent list without checking
2865 their readability through a remote access:
2872 (recent-files-initialize)
2876 (when (file-remote-p (buffer-file-name))
2877 (recent-files-make-permanent)))
2882 The list of files opened recently is reachable via
2884 @kbd{@key{menu-bar} @key{file} @key{Open Recent}}.
2887 @kbd{@key{menu-bar} @key{Recent Files}}.
2891 @item Use filecache:
2893 @file{filecache} remembers visited places. Add the directory into
2897 (eval-after-load "filecache"
2898 '(file-cache-add-directory
2899 "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
2902 Whenever you want to load a file, you can enter @kbd{C-x C-f
2903 C-@key{TAB}} in the minibuffer. The completion is done for the given
2910 @file{bbdb} has a built-in feature for @value{ftppackagename} files,
2911 which works also for @value{tramp}.
2913 @pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb}
2916 You need to load @file{bbdb}:
2923 Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}.
2924 Because BBDB is not prepared for @value{tramp} syntax, you must
2925 specify a method together with the user name, when needed. Example:
2928 @kbd{M-x bbdb-create-ftp-site @key{RET}}
2929 @b{Ftp Site:} news.my.domain @key{RET}
2930 @b{Ftp Directory:} /opt/news/etc/ @key{RET}
2931 @b{Ftp Username:} ssh@value{postfixhop}news @key{RET}
2932 @b{Company:} @key{RET}
2933 @b{Additional Comments:} @key{RET}
2936 When you have opened your BBDB buffer, you can access such an entry by
2937 pressing the key @key{F}.
2942 I would like to thank all @value{tramp} users, who have contributed to
2943 the different recipes!
2947 How can I disable @value{tramp}?
2949 Shame on you, why did you read until now?
2952 If you just want to have @value{ftppackagename} as default remote
2953 files access package, you should apply the following code:
2956 (setq tramp-default-method "ftp")
2960 Unloading @value{tramp} can be achieved by applying @kbd{M-x
2961 tramp-unload-tramp}.
2963 This resets also the @value{ftppackagename} plugins.
2968 @c For the developer
2969 @node Version Control
2970 @chapter The inner workings of remote version control
2971 @cindex Version Control
2973 Unlike @value{ftppackagename}, @value{tramp} has full shell access to the
2974 remote machine. This makes it possible to provide version control for
2975 files accessed under @value{tramp}.
2977 The actual version control binaries must be installed on the remote
2978 machine, accessible in the directories specified in
2979 @code{tramp-remote-path}.
2981 This transparent integration with the version control systems is one of
2982 the most valuable features provided by @value{tramp}, but it is far from perfect.
2983 Work is ongoing to improve the transparency of the system.
2986 * Version Controlled Files:: Determining if a file is under version control.
2987 * Remote Commands:: Executing the version control commands on the remote machine.
2988 * Changed workfiles:: Detecting if the working file has changed.
2989 * Checking out files:: Bringing the workfile out of the repository.
2990 * Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
2994 @node Version Controlled Files
2995 @section Determining if a file is under version control
2997 The VC package uses the existence of on-disk revision control master
2998 files to determine if a given file is under revision control. These file
2999 tests happen on the remote machine through the standard @value{tramp} mechanisms.
3002 @node Remote Commands
3003 @section Executing the version control commands on the remote machine
3005 There are no hooks provided by VC to allow intercepting of the version
3006 control command execution. The calls occur through the
3007 @code{call-process} mechanism, a function that is somewhat more
3008 efficient than the @code{shell-command} function but that does not
3009 provide hooks for remote execution of commands.
3011 To work around this, the functions @code{vc-do-command} and
3012 @code{vc-simple-command} have been advised to intercept requests for
3013 operations on files accessed via @value{tramp}.
3015 In the case of a remote file, the @code{shell-command} interface is
3016 used, with some wrapper code, to provide the same functionality on the
3017 remote machine as would be seen on the local machine.
3020 @node Changed workfiles
3021 @section Detecting if the working file has changed
3023 As there is currently no way to get access to the mtime of a file on a
3024 remote machine in a portable way, the @code{vc-workfile-unchanged-p}
3025 function is advised to call an @value{tramp} specific function for remote files.
3027 The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC
3028 diff functionality to determine if any changes have occurred between the
3029 workfile and the version control master.
3031 This requires that a shell command be executed remotely, a process that
3032 is notably heavier-weight than the mtime comparison used for local
3033 files. Unfortunately, unless a portable solution to the issue is found,
3034 this will remain the cost of remote version control.
3037 @node Checking out files
3038 @section Bringing the workfile out of the repository
3040 VC will, by default, check for remote files and refuse to act on them
3041 when checking out files from the repository. To work around this
3042 problem, the function @code{vc-checkout} knows about @value{tramp} files and
3043 allows version control to occur.
3046 @node Miscellaneous Version Control
3047 @section Things related to Version Control that don't fit elsewhere
3049 Minor implementation details, &c.
3052 * Remote File Ownership:: How VC determines who owns a workfile.
3053 * Back-end Versions:: How VC determines what release your RCS is.
3057 @node Remote File Ownership
3058 @subsection How VC determines who owns a workfile
3060 @value{emacsname} provides the @code{user-login-name} function to
3061 return the login name of the current user as well as mapping from
3062 arbitrary user id values back to login names. The VC code uses this
3063 functionality to map from the uid of the owner of a workfile to the
3064 login name in some circumstances.
3066 This will not, for obvious reasons, work if the remote system has a
3067 different set of logins. As such, it is necessary to delegate to the
3068 remote machine the job of determining the login name associated with a
3071 Unfortunately, with the profusion of distributed management systems such
3072 as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple,
3073 reliable and portable method for performing this mapping.
3075 Thankfully, the only place in the VC code that depends on the mapping of
3076 a uid to a login name is the @code{vc-file-owner} function. This returns
3077 the login of the owner of the file as a string.
3079 This function has been advised to use the output of @command{ls} on the
3080 remote machine to determine the login name, delegating the problem of
3081 mapping the uid to the login to the remote system which should know more
3085 @node Back-end Versions
3086 @subsection How VC determines what release your RCS is
3088 VC needs to know what release your revision control binaries you are
3089 running as not all features VC supports are available with older
3090 versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}.
3092 The default implementation of VC determines this value the first time it
3093 is needed and then stores the value globally to avoid the overhead of
3094 executing a process and parsing its output each time the information is
3097 Unfortunately, life is not quite so easy when remote version control
3098 comes into the picture. Each remote machine may have a different version
3099 of the version control tools and, while this is painful, we need to
3100 ensure that unavailable features are not used remotely.
3102 To resolve this issue, @value{tramp} currently takes the sledgehammer
3103 approach of making the release values of the revision control tools
3104 local to each @value{tramp} buffer, forcing VC to determine these values
3105 again each time a new file is visited.
3107 This has, quite obviously, some performance implications. Thankfully,
3108 most of the common operations performed by VC do not actually require
3109 that the remote version be known. This makes the problem far less
3112 Eventually these values will be captured by @value{tramp} on a system by
3113 system basis and the results cached to improve performance.
3116 @node Files directories and localnames
3117 @chapter How file names, directories and localnames are mangled and managed.
3120 * Localname deconstruction:: Breaking a localname into its components.
3124 @node Localname deconstruction
3125 @section Breaking a localname into its components.
3127 @value{tramp} file names are somewhat different, obviously, to ordinary file
3128 names. As such, the lisp functions @code{file-name-directory} and
3129 @code{file-name-nondirectory} are overridden within the @value{tramp}
3132 Their replacements are reasonably simplistic in their approach. They
3133 dissect the filename, call the original handler on the localname and
3134 then rebuild the @value{tramp} file name with the result.
3136 This allows the platform specific hacks in the original handlers to take
3137 effect while preserving the @value{tramp} file name information.
3140 @node Traces and Profiles
3141 @chapter How to Customize Traces
3143 All @value{tramp} messages are raised with a verbosity level. The
3144 verbosity level can be any number between 0 and 10. Only messages with
3145 a verbosity level less than or equal to @code{tramp-verbose} are
3148 The verbosity levels are
3150 @w{ 0} silent (no @value{tramp} messages at all)
3151 @*@indent @w{ 1} errors
3152 @*@indent @w{ 2} warnings
3153 @*@indent @w{ 3} connection to remote hosts (default verbosity)
3154 @*@indent @w{ 4} activities
3155 @*@indent @w{ 5} internal
3156 @*@indent @w{ 6} sent and received strings
3157 @*@indent @w{ 7} file caching
3158 @*@indent @w{ 8} connection properties
3159 @*@indent @w{10} traces (huge)
3161 When @code{tramp-verbose} is greater than or equal to 4, the messages
3162 are also written into a @value{tramp} debug buffer. This debug buffer
3163 is useful for analysing problems; sending a @value{tramp} bug report
3164 should be done with @code{tramp-verbose} set to a verbosity level of at
3165 least 6 (@pxref{Bug Reports}).
3167 The debug buffer is in
3169 @ref{Outline Mode, , , @value{emacsdir}}.
3174 That means, you can change the level of messages to be viewed. If you
3175 want, for example, see only messages up to verbosity level 5, you must
3176 enter @kbd{C-u 6 C-c C-q}.
3178 Other keys for navigating are described in
3179 @ref{Outline Visibility, , , @value{emacsdir}}.
3182 @value{tramp} errors are handled internally in order to raise the
3183 verbosity level 1 messages. When you want to get a Lisp backtrace in
3184 case of an error, you need to set both
3187 (setq debug-on-error t
3191 Sometimes, it might be even necessary to step through @value{tramp}
3192 function call traces. Such traces are enabled by the following code:
3197 (mapcar 'trace-function-background
3199 (all-completions "tramp-" obarray 'functionp)))
3200 (untrace-function 'tramp-read-passwd)
3201 (untrace-function 'tramp-gw-basic-authentication)
3204 The function call traces are inserted in the buffer
3205 @file{*trace-output*}. @code{tramp-read-passwd} and
3206 @code{tramp-gw-basic-authentication} shall be disabled when the
3207 function call traces are added to @value{tramp}, because both
3208 functions return password strings, which should not be distributed.
3212 @chapter Debatable Issues and What Was Decided
3215 @item The uuencode method does not always work.
3217 Due to the design of @value{tramp}, the encoding and decoding programs
3218 need to read from stdin and write to stdout. On some systems,
3219 @command{uudecode -o -} will read stdin and write the decoded file to
3220 stdout, on other systems @command{uudecode -p} does the same thing.
3221 But some systems have uudecode implementations which cannot do this at
3222 all---it is not possible to call these uudecode implementations with
3223 suitable parameters so that they write to stdout.
3225 Of course, this could be circumvented: the @code{begin foo 644} line
3226 could be rewritten to put in some temporary file name, then
3227 @command{uudecode} could be called, then the temp file could be
3228 printed and deleted.
3230 But I have decided that this is too fragile to reliably work, so on some
3231 systems you'll have to do without the uuencode methods.
3233 @item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs.
3235 The GNU Emacs maintainers wish to use a unified filename syntax for
3236 Ange-FTP and @value{tramp} so that users don't have to learn a new
3237 syntax. It is sufficient to learn some extensions to the old syntax.
3239 For the XEmacs maintainers, the problems caused from using a unified
3240 filename syntax are greater than the gains. The XEmacs package system
3241 uses EFS for downloading new packages. So, obviously, EFS has to be
3242 installed from the start. If the filenames were unified, @value{tramp}
3243 would have to be installed from the start, too.
3246 @strong{Note:} If you'd like to use a similar syntax like
3247 @value{ftppackagename}, you need the following settings in your init
3251 (setq tramp-unified-filenames t)
3255 The autoload of the @value{emacsname} @value{tramp} package must be
3256 disabled. This can be achieved by setting file permissions @code{000}
3257 to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}.
3259 In case of unified filenames, all @value{emacsname} download sites are
3260 added to @code{tramp-default-method-alist} with default method
3261 @option{ftp} @xref{Default Method}. These settings shouldn't be
3262 touched for proper working of the @value{emacsname} package system.
3264 The syntax for unified filenames is described in the @value{tramp} manual
3265 for @value{emacsothername}.
3269 @node GNU Free Documentation License
3270 @appendix GNU Free Documentation License
3271 @include doclicense.texi
3274 @comment node-name, next, previous, up
3275 @unnumbered Concept Index
3278 @c End of tramp.texi - the TRAMP User Manual
3283 @c * Say something about the .login and .profile files of the remote
3285 @c * Explain how tramp.el works in principle: open a shell on a remote
3286 @c host and then send commands to it.
3287 @c * Make terminology "inline" vs "out-of-band" consistent.
3288 @c It seems that "external" is also used instead of "out-of-band".
3291 @c ** Use `filename' resp. `file name' consistently.
3292 @c ** Use `host' resp. `machine' consistently.
3293 @c ** Consistent small or capitalized words especially in menues.
3296 arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808