1 \input texinfo @c -*-texinfo-*-
3 @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 Macros for formatting a filename.
21 @c trampfn is for a full filename, trampfnmhl means method, host, localname
22 @c were given, and so on.
23 @macro trampfn {method, user, host, localname}
24 @value{prefix}\method\@value{postfixhop}\user\@@\host\@value{postfix}\localname\
27 @macro trampfnmhl {method, host, localname}
28 @value{prefix}\method\@value{postfixhop}\host\@value{postfix}\localname\
31 @macro trampfnuhl {user, host, localname}
32 @value{prefix}\user\@@\host\@value{postfix}\localname\
35 @macro trampfnhl {host, localname}
36 @value{prefix}\host\@value{postfix}\localname\
40 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
41 2007 Free Software Foundation, Inc.
44 Permission is granted to copy, distribute and/or modify this document
45 under the terms of the GNU Free Documentation License, Version 1.2 or
46 any later version published by the Free Software Foundation; with no
47 Invariant Sections, with the Front-Cover texts being ``A GNU
48 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
49 license is included in the section entitled ``GNU Free Documentation
50 License'' in the Emacs manual.
52 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
53 this GNU Manual, like GNU software. Copies published by the Free
54 Software Foundation raise funds for GNU development.''
56 This document is part of a collection distributed under the GNU Free
57 Documentation License. If you want to distribute this document
58 separately from the collection, you can do so by adding a copy of the
59 license to the document, as described in section 6 of the license.
63 @c Entries for @command{install-info} to use
64 @dircategory @value{emacsname}
66 * TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
67 @value{emacsname} remote file access via rsh and rcp.
73 @title @value{tramp} version @value{trampver} User Manual
75 @author by Daniel Pittman
76 @author based on documentation by Kai Gro@ss{}johann
87 @node Top, Overview, (dir), (dir)
88 @top @value{tramp} version @value{trampver} User Manual
90 This file documents @value{tramp} version @value{trampver}, a remote file
91 editing package for @value{emacsname}.
93 @value{tramp} stands for `Transparent Remote (file) Access, Multiple
94 Protocol'. This package provides remote file editing, similar to
95 @value{ftppackagename}.
97 The difference is that @value{ftppackagename} uses FTP to transfer
98 files between the local and the remote host, whereas @value{tramp} uses a
99 combination of @command{rsh} and @command{rcp} or other work-alike
100 programs, such as @command{ssh}/@command{scp}.
102 You can find the latest version of this document on the web at
103 @uref{http://www.gnu.org/software/tramp/}.
105 @c Pointer to the other Emacs flavor is necessary only in case of
106 @c standalone installation.
107 @ifset installchapter
108 The manual has been generated for @value{emacsname}.
110 If you want to read the info pages for @value{emacsothername}, you
111 should read in @ref{Installation} how to create them.
114 If you're using the other Emacs flavor, you should read the
115 @uref{@value{emacsotherfilename}, @value{emacsothername}} pages.
121 This manual is also available as a @uref{@value{japanesemanual},
122 Japanese translation}.
125 The latest release of @value{tramp} is available for
126 @uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
127 @ref{Obtaining Tramp} for more details, including the CVS server
130 @value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/,
131 Savannah Project Page}.
134 There is a mailing list for @value{tramp}, available at
135 @email{tramp-devel@@gnu.org}, and archived at
136 @uref{http://lists.gnu.org/archive/html/tramp-devel/, the
137 @value{tramp} Mail Archive}.
139 Older archives are located at
140 @uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel,
141 SourceForge Mail Archive} and
142 @uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/,
144 @c in HTML output, there's no new paragraph.
153 * Overview:: What @value{tramp} can and cannot do.
157 * Obtaining Tramp:: How to obtain @value{tramp}.
158 * History:: History of @value{tramp}.
159 @ifset installchapter
160 * Installation:: Installing @value{tramp} with your @value{emacsname}.
162 * Configuration:: Configuring @value{tramp} for use.
163 * Usage:: An overview of the operation of @value{tramp}.
164 * Bug Reports:: Reporting Bugs and Problems.
165 * Frequently Asked Questions:: Questions and answers from the mailing list.
166 * Concept Index:: An item for each concept.
170 * Version Control:: The inner workings of remote version control.
171 * Files directories and localnames:: How file names, directories and localnames are mangled and managed.
172 * Traces and Profiles:: How to Customize Traces.
173 * Issues:: Debatable Issues and What Was Decided.
175 * GNU Free Documentation License:: The license for this documentation.
178 --- The Detailed Node Listing ---
180 @ifset installchapter
181 Installing @value{tramp} with your @value{emacsname}
183 * Installation parameters:: Parameters in order to control installation.
184 * Load paths:: How to plug-in @value{tramp} into your environment.
185 * Japanese manual:: Japanese manual.
189 Configuring @value{tramp} for use
191 * Connection types:: Types of connections made to remote machines.
192 * Inline methods:: Inline methods.
193 * External transfer methods:: External transfer methods.
195 * Gateway methods:: Gateway methods.
197 * Default Method:: Selecting a default method.
198 * Default User:: Selecting a default user.
199 * Default Host:: Selecting a default host.
200 * Multi-hops:: Connecting to a remote host using multiple hops.
201 * Customizing Methods:: Using Non-Standard Methods.
202 * Customizing Completion:: Selecting config files for user/host name completion.
203 * Password caching:: Reusing passwords for several connections.
204 * Connection caching:: Reusing connection related information.
205 * Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
206 * Remote shell setup:: Remote shell setup hints.
207 * Windows setup hints:: Issues with Cygwin ssh.
208 * Auto-save and Backup:: Auto-save and Backup.
212 * Filename Syntax:: @value{tramp} filename conventions.
213 * Alternative Syntax:: URL-like filename syntax.
214 * Filename completion:: Filename completion.
215 * Remote processes:: Integration with other @value{emacsname} packages (@sc{experimental}).
217 The inner workings of remote version control
219 * Version Controlled Files:: Determining if a file is under version control.
220 * Remote Commands:: Executing the version control commands on the remote machine.
221 * Changed workfiles:: Detecting if the working file has changed.
222 * Checking out files:: Bringing the workfile out of the repository.
223 * Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
225 Things related to Version Control that don't fit elsewhere
227 * Remote File Ownership:: How VC determines who owns a workfile.
228 * Back-end Versions:: How VC determines what release your RCS is.
230 How file names, directories and localnames are mangled and managed
232 * Localname deconstruction:: Breaking a localname into its components.
238 @chapter An overview of @value{tramp}
241 After the installation of @value{tramp} into your @value{emacsname}, you
242 will be able to access files on remote machines as though they were
243 local. Access to the remote file system for editing files, version
244 control, and @code{dired} are transparently enabled.
246 Your access to the remote machine can be with the @command{rsh},
247 @command{rlogin}, @command{telnet} programs or with any similar
248 connection method. This connection must pass @acronym{ASCII}
249 successfully to be usable but need not be 8-bit clean.
251 The package provides support for @command{ssh} connections out of the
252 box, one of the more common uses of the package. This allows
253 relatively secure access to machines, especially if @command{ftp}
256 The majority of activity carried out by @value{tramp} requires only that
257 the remote login is possible and is carried out at the terminal. In
258 order to access remote files @value{tramp} needs to transfer their content
259 to the local machine temporarily.
261 @value{tramp} can transfer files between the machines in a variety of ways.
262 The details are easy to select, depending on your needs and the
263 machines in question.
265 The fastest transfer methods (for large files) rely on a remote file
266 transfer package such as @command{rcp}, @command{scp} or
269 If the remote copy methods are not suitable for you, @value{tramp} also
270 supports the use of encoded transfers directly through the shell.
271 This requires that the @command{mimencode} or @command{uuencode} tools
272 are available on the remote machine. These methods are generally
273 faster for small files.
275 Within these limitations, @value{tramp} is quite powerful. It is worth
276 noting that, as of the time of writing, it is far from a polished
277 end-user product. For a while yet you should expect to run into rough
278 edges and problems with the code now and then.
280 It is finished enough that the developers use it for day to day work but
281 the installation and setup can be a little difficult to master, as can
284 @value{tramp} is still under active development and any problems you encounter,
285 trivial or major, should be reported to the @value{tramp} developers.
289 @subsubheading Behind the scenes
290 @cindex behind the scenes
291 @cindex details of operation
294 This section tries to explain what goes on behind the scenes when you
295 access a remote file through @value{tramp}.
297 Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name,
298 then hit @kbd{@key{TAB}} for completion. Suppose further that this is
299 the first time that @value{tramp} is invoked for the host in question. Here's
304 @value{tramp} discovers that it needs a connection to the host. So it
305 invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
306 @var{user}} or a similar tool to connect to the remote host.
307 Communication with this process happens through an
308 @value{emacsname} buffer, that is, the output from the remote end
312 The remote host may prompt for a login name (for @command{telnet}).
313 The login name is given in the file name, so @value{tramp} sends the
314 login name and a newline.
317 The remote host may prompt for a password or pass phrase (for
318 @command{rsh} or for @command{telnet} after sending the login name).
319 @value{tramp} displays the prompt in the minibuffer, asking you for the
320 password or pass phrase.
322 You enter the password or pass phrase. @value{tramp} sends it to the remote
323 host, followed by a newline.
326 @value{tramp} now waits for the shell prompt or for a message that the login
329 If @value{tramp} sees neither of them after a certain period of time (a minute,
330 say), then it issues an error message saying that it couldn't find the
331 remote shell prompt and shows you what the remote host has sent.
333 If @value{tramp} sees a @samp{login failed} message, it tells you so,
334 aborts the login attempt and allows you to try again.
337 Suppose that the login was successful and @value{tramp} sees the shell prompt
338 from the remote host. Now @value{tramp} invokes @command{/bin/sh} because
339 Bourne shells and C shells have different command
340 syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login
341 shell doesn't recognize @samp{exec /bin/sh} as a valid command.
342 Maybe you use the Scheme shell @command{scsh}@dots{}}
344 After the Bourne shell has come up, @value{tramp} sends a few commands to
345 ensure a good working environment. It turns off echoing, it sets the
346 shell prompt, and a few other things.
349 Now the remote shell is up and it good working order. Remember, what
350 was supposed to happen is that @value{tramp} tries to find out what files exist
351 on the remote host so that it can do filename completion.
353 So, @value{tramp} basically issues @command{cd} and @command{ls} commands and
354 also sometimes @command{echo} with globbing. Another command that is
355 often used is @command{test} to find out whether a file is writable or a
356 directory or the like. The output of each command is parsed for the
360 Suppose you are finished with filename completion, have entered @kbd{C-x
361 C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to
362 transfer the file contents from the remote host to the local host so
363 that you can edit them.
365 See above for an explanation of how @value{tramp} transfers the file contents.
367 For inline transfers, @value{tramp} issues a command like @samp{mimencode -b
368 /path/to/remote/file}, waits until the output has accumulated in the
369 buffer that's used for communication, then decodes that output to
370 produce the file contents.
372 For out-of-band transfers, @value{tramp} issues a command like the following:
374 rcp user@@host:/path/to/remote/file /tmp/tramp.4711
376 It then reads the local temporary file @file{/tmp/tramp.4711} into a
377 buffer and deletes the temporary file.
380 You now edit the buffer contents, blithely unaware of what has happened
381 behind the scenes. (Unless you have read this section, that is.) When
382 you are finished, you type @kbd{C-x C-s} to save the buffer.
385 Again, @value{tramp} transfers the file contents to the remote host either
386 inline or out-of-band. This is the reverse of what happens when reading
390 I hope this has provided you with a basic overview of what happens
391 behind the scenes when you open a file with @value{tramp}.
395 @node Obtaining Tramp
396 @chapter Obtaining Tramp.
397 @cindex obtaining Tramp
399 @value{tramp} is freely available on the Internet and the latest
400 release may be downloaded from
401 @uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
402 documentation and code for @value{tramp}, suitable for installation.
403 But GNU Emacs (22 or later) includes @value{tramp} already, and there
404 is a @value{tramp} package for XEmacs, as well. So maybe it is easier
405 to just use those. But if you want the bleeding edge, read
408 For the especially brave, @value{tramp} is available from CVS. The CVS
409 version is the latest version of the code and may contain incomplete
410 features or new issues. Use these versions at your own risk.
412 Instructions for obtaining the latest development version of @value{tramp}
413 from CVS can be found by going to the Savannah project page at the
414 following URL and then clicking on the CVS link in the navigation bar
418 @uref{http://savannah.gnu.org/projects/tramp/}
421 Or follow the example session below:
424 ] @strong{cd ~/@value{emacsdir}}
425 ] @strong{export CVS_RSH="ssh"}
426 ] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
430 You should now have a directory @file{~/@value{emacsdir}/tramp}
431 containing the latest version of @value{tramp}. You can fetch the latest
432 updates from the repository by issuing the command:
435 ] @strong{cd ~/@value{emacsdir}/tramp}
436 ] @strong{export CVS_RSH="ssh"}
437 ] @strong{cvs update -d}
441 Once you've got updated files from the CVS repository, you need to run
442 @command{autoconf} in order to get an up-to-date @file{configure}
446 ] @strong{cd ~/@value{emacsdir}/tramp}
450 People who have no direct CVS access (maybe because sitting behind a
451 blocking firewall), can try the
452 @uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly
453 CVS Tree Tarball} instead of.
457 @chapter History of @value{tramp}
459 @cindex development history
461 Development was started end of November 1998. The package was called
462 @file{rssh.el}, back then. It only provided one method to access a
463 file, using @command{ssh} to log in to a remote host and using
464 @command{scp} to transfer the file contents. After a while, the name
465 was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way,
466 many more methods for getting a remote shell and for transferring the
467 file contents were added. Support for VC was added.
469 The most recent addition of major features were the multi-hop methods
470 added in April 2000 and the unification of @value{tramp} and Ange-FTP
471 filenames in July 2002. In July 2004, multi-hop methods have been
472 replaced by proxy hosts. Running commands on remote hosts was
473 introduced in December 2005.
475 Support of gateways exists since April 2007.
478 In December 2001, @value{tramp} has been added to the XEmacs package
479 repository. Being part of the GNU Emacs repository happened in June
480 2002, the first release including @value{tramp} was GNU Emacs 22.1.
482 @value{tramp} is also a GNU/Linux Debian package since February 2001.
485 @c Installation chapter is necessary only in case of standalone
486 @c installation. Text taken from trampinst.texi.
487 @ifset installchapter
488 @include trampinst.texi
492 @chapter Configuring @value{tramp} for use
493 @cindex configuration
495 @cindex default configuration
496 @value{tramp} is (normally) fully functional when it is initially
497 installed. It is initially configured to use the @command{scp}
498 program to connect to the remote host. So in the easiest case, you
499 just type @kbd{C-x C-f} and then enter the filename
500 @file{@trampfnuhl{user, machine, /path/to.file}}.
502 On some hosts, there are problems with opening a connection. These are
503 related to the behavior of the remote shell. See @xref{Remote shell
504 setup}, for details on this.
506 If you do not wish to use these commands to connect to the remote
507 host, you should change the default connection and transfer method
508 that @value{tramp} uses. There are several different methods that @value{tramp}
509 can use to connect to remote machines and transfer files
510 (@pxref{Connection types}).
512 If you don't know which method is right for you, see @xref{Default
517 * Connection types:: Types of connections made to remote machines.
518 * Inline methods:: Inline methods.
519 * External transfer methods:: External transfer methods.
521 * Gateway methods:: Gateway methods.
523 * Default Method:: Selecting a default method.
524 Here we also try to help those who
525 don't have the foggiest which method
527 * Default User:: Selecting a default user.
528 * Default Host:: Selecting a default host.
529 * Multi-hops:: Connecting to a remote host using multiple hops.
530 * Customizing Methods:: Using Non-Standard Methods.
531 * Customizing Completion:: Selecting config files for user/host name completion.
532 * Password caching:: Reusing passwords for several connections.
533 * Connection caching:: Reusing connection related information.
534 * Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
535 * Remote shell setup:: Remote shell setup hints.
536 * Windows setup hints:: Issues with Cygwin ssh.
537 * Auto-save and Backup:: Auto-save and Backup.
541 @node Connection types
542 @section Types of connections made to remote machines.
543 @cindex connection types, overview
545 There are two basic types of transfer methods, each with its own
546 advantages and limitations. Both types of connection make use of a
547 remote shell access program such as @command{rsh}, @command{ssh} or
548 @command{telnet} to connect to the remote machine.
550 This connection is used to perform many of the operations that @value{tramp}
551 requires to make the remote file system transparently accessible from
552 the local machine. It is only when visiting files that the methods
555 @cindex inline methods
556 @cindex external transfer methods
557 @cindex external methods
558 @cindex out-of-band methods
559 @cindex methods, inline
560 @cindex methods, external transfer
561 @cindex methods, out-of-band
562 Loading or saving a remote file requires that the content of the file
563 be transfered between the two machines. The content of the file can be
564 transfered over the same connection used to log in to the remote
565 machine or the file can be transfered through another connection using
566 a remote copy program such as @command{rcp}, @command{scp} or
567 @command{rsync}. The former are called @dfn{inline methods}, the
568 latter are called @dfn{out-of-band methods} or @dfn{external transfer
569 methods} (@dfn{external methods} for short).
571 The performance of the external transfer methods is generally better
572 than that of the inline methods, at least for large files. This is
573 caused by the need to encode and decode the data when transferring
576 The one exception to this rule are the @command{scp} based transfer
577 methods. While these methods do see better performance when actually
578 transferring files, the overhead of the cryptographic negotiation at
579 startup may drown out the improvement in file transfer times.
581 External transfer methods should be configured such a way that they
582 don't require a password (with @command{ssh-agent}, or such alike).
583 Modern @command{scp} implementations offer options to reuse existing
584 @command{ssh} connections, see method @command{scpc}. If it isn't
585 possible, you should consider @ref{Password caching}, otherwise you
586 will be prompted for a password every copy action.
590 @section Inline methods
591 @cindex inline methods
592 @cindex methods, inline
594 The inline methods in @value{tramp} are quite powerful and can work in
595 situations where you cannot use an external transfer program to connect.
596 Inline methods are the only methods that work when connecting to the
597 remote machine via telnet. (There are also strange inline methods which
598 allow you to transfer files between @emph{user identities} rather than
601 These methods depend on the existence of a suitable encoding and
602 decoding command on remote machine. Locally, @value{tramp} may be able to
603 use features of @value{emacsname} to decode and encode the files or
604 it may require access to external commands to perform that task.
608 @cindex base-64 encoding
609 @value{tramp} checks the availability and usability of commands like
610 @command{mimencode} (part of the @command{metamail} package) or
611 @command{uuencode} on the remote host. The first reliable command
612 will be used. The search path can be customized, see @ref{Remote
615 If both commands aren't available on the remote host, @value{tramp}
616 transfers a small piece of Perl code to the remote host, and tries to
617 apply it for encoding and decoding.
625 Connect to the remote host with @command{rsh}. Due to the unsecure
626 connection it is recommended for very local host topology only.
628 On operating systems which provide the command @command{remsh} instead
629 of @command{rsh}, you can use the method @option{remsh}. This is true
630 for HP-UX or Cray UNICOS, for example.
637 Connect to the remote host with @command{ssh}. This is identical to
638 the previous option except that the @command{ssh} package is used,
639 making the connection more secure.
641 There are also two variants, @option{ssh1} and @option{ssh2}, that
642 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
643 explicitly select whether you want to use the SSH protocol version 1
644 or 2 to connect to the remote host. (You can also specify in
645 @file{~/.ssh/config}, the SSH configuration file, which protocol
646 should be used, and use the regular @option{ssh} method.)
648 Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
649 @command{ssh1} and @command{ssh2} commands explicitly. If you don't
650 know what these are, you do not need these options.
652 All the methods based on @command{ssh} have an additional kludgy
653 feature: you can specify a host name which looks like @file{host#42}
654 (the real host name, then a hash sign, then a port number). This
655 means to connect to the given host but to also pass @code{-p 42} as
656 arguments to the @command{ssh} command.
659 @item @option{telnet}
660 @cindex method telnet
661 @cindex telnet method
663 Connect to the remote host with @command{telnet}. This is as unsecure
664 as the @option{rsh} method.
671 This method does not connect to a remote host at all, rather it uses
672 the @command{su} program to allow you to edit files as another user.
673 With other words, a specified host name in the file name is silently
681 This is similar to the @option{su} method, but it uses @command{sudo}
682 rather than @command{su} to become a different user.
684 Note that @command{sudo} must be configured to allow you to start a
685 shell as the user. It would be nice if it was sufficient if
686 @command{ls} and @command{mimencode} were allowed, but that is not
687 easy to implement, so I haven't got around to it, yet.
694 As you would expect, this is similar to @option{ssh}, only a little
695 different. Whereas @option{ssh} opens a normal interactive shell on
696 the remote host, this option uses @samp{ssh -t -t @var{host} -l
697 @var{user} /bin/sh} to open a connection. This is useful for users
698 where the normal login shell is set up to ask them a number of
699 questions when logging in. This procedure avoids these questions, and
700 just gives @value{tramp} a more-or-less `standard' login shell to work
703 Note that this procedure does not eliminate questions asked by
704 @command{ssh} itself. For example, @command{ssh} might ask ``Are you
705 sure you want to continue connecting?'' if the host key of the remote
706 host is not known. @value{tramp} does not know how to deal with such a
707 question (yet), therefore you will need to make sure that you can log
708 in without such questions.
710 This is also useful for Windows users where @command{ssh}, when
711 invoked from an @value{emacsname} buffer, tells them that it is not
712 allocating a pseudo tty. When this happens, the login shell is wont
713 to not print any shell prompt, which confuses @value{tramp} mightily.
714 For reasons unknown, some Windows ports for @command{ssh} require the
715 doubled @samp{-t} option.
717 This supports the @samp{-p} kludge.
720 @item @option{krlogin}
721 @cindex method krlogin
722 @cindex krlogin method
723 @cindex Kerberos (with krlogin method)
725 This method is also similar to @option{ssh}. It only uses the
726 @command{krlogin -x} command to log in to the remote host.
733 This method is mostly interesting for Windows users using the PuTTY
734 implementation of SSH. It uses @samp{plink -ssh} to log in to the
737 This supports the @samp{-P} kludge.
739 Additionally, the methods @option{plink1} and @option{plink2} are
740 provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in
741 order to use SSH protocol version 1 or 2 explicitly.
743 CCC: Do we have to connect to the remote host once from the command
744 line to accept the SSH key? Maybe this can be made automatic?
746 CCC: Say something about the first shell command failing. This might
747 be due to a wrong setting of @code{tramp-rsh-end-of-line}.
750 @item @option{plinkx}
751 @cindex method plinkx
752 @cindex plinkx method
754 Another method using PuTTY on Windows. Instead of host names, it
755 expects PuTTY session names, calling @samp{plink -load @var{session}
756 -t"}. User names are relevant only in case the corresponding session
757 hasn't defined a user name. Different port numbers must be defined in
765 This is an experimental implementation of the fish protocol, known from
766 the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
767 the fish server implementation from the KDE kioslave. That means, the
768 file @file{~/.fishsrv.pl} is expected to reside on the remote host.
770 The implementation lacks good performance. The code is offered anyway,
771 maybe somebody can improve the performance.
776 @node External transfer methods
777 @section External transfer methods
778 @cindex methods, external transfer
779 @cindex methods, out-of-band
780 @cindex external transfer methods
781 @cindex out-of-band methods
783 The external transfer methods operate through multiple channels, using
784 the remote shell connection for many actions while delegating file
785 transfers to an external transfer utility.
787 This saves the overhead of encoding and decoding that multiplexing the
788 transfer through the one connection has with the inline methods.
790 Since external transfer methods need their own overhead opening a new
791 channel, all files which are smaller than @var{tramp-copy-size-limit}
792 are still transferred with the corresponding inline method. It should
793 provide a fair trade-off between both approaches.
796 @item @option{rcp} --- @command{rsh} and @command{rcp}
799 @cindex rcp (with rcp method)
800 @cindex rsh (with rcp method)
802 This method uses the @command{rsh} and @command{rcp} commands to connect
803 to the remote machine and transfer files. This is probably the fastest
804 connection method available.
806 The alternative method @option{remcp} uses the @command{remsh} and
807 @command{rcp} commands. It should be applied on machines where
808 @command{remsh} is used instead of @command{rsh}.
811 @item @option{scp} --- @command{ssh} and @command{scp}
814 @cindex scp (with scp method)
815 @cindex ssh (with scp method)
817 Using @command{ssh} to connect to the remote host and @command{scp} to
818 transfer files between the machines is the best method for securely
819 connecting to a remote machine and accessing files.
821 The performance of this option is also quite good. It may be slower than
822 the inline methods when you often open and close small files however.
823 The cost of the cryptographic handshake at the start of an @command{scp}
824 session can begin to absorb the advantage that the lack of encoding and
827 There are also two variants, @option{scp1} and @option{scp2}, that
828 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
829 explicitly select whether you want to use the SSH protocol version 1
830 or 2 to connect to the remote host. (You can also specify in
831 @file{~/.ssh/config}, the SSH configuration file, which protocol
832 should be used, and use the regular @option{scp} method.)
834 Two other variants, @option{scp1_old} and @option{scp2_old}, use the
835 @command{ssh1} and @command{ssh2} commands explicitly. If you don't
836 know what these are, you do not need these options.
838 All the @command{ssh} based methods support the kludgy @samp{-p}
839 feature where you can specify a port number to connect to in the host
840 name. For example, the host name @file{host#42} tells @value{tramp} to
841 specify @samp{-p 42} in the argument list for @command{ssh}, and to
842 specify @samp{-P 42} in the argument list for @command{scp}.
845 @item @option{sftp} --- @command{ssh} and @command{sftp}
848 @cindex sftp (with sftp method)
849 @cindex ssh (with sftp method)
851 That is mostly the same method as @option{scp}, but using
852 @command{sftp} as transfer command. So the same remarks are valid.
854 This command does not work like @value{ftppackagename}, where
855 @command{ftp} is called interactively, and all commands are send from
856 within this session. Instead of, @command{ssh} is used for login.
858 This method supports the @samp{-p} hack.
861 @item @option{rsync} --- @command{ssh} and @command{rsync}
864 @cindex rsync (with rsync method)
865 @cindex ssh (with rsync method)
867 Using the @command{ssh} command to connect securely to the remote
868 machine and the @command{rsync} command to transfer files is almost
869 identical to the @option{scp} method.
871 While @command{rsync} performs much better than @command{scp} when
872 transferring files that exist on both hosts, this advantage is lost if
873 the file exists only on one side of the connection.
875 The @command{rsync} based method may be considerably faster than the
876 @command{rcp} based methods when writing to the remote system. Reading
877 files to the local machine is no faster than with a direct copy.
879 This method supports the @samp{-p} hack.
882 @item @option{scpx} --- @command{ssh} and @command{scp}
885 @cindex scp (with scpx method)
886 @cindex ssh (with scpx method)
888 As you would expect, this is similar to @option{scp}, only a little
889 different. Whereas @option{scp} opens a normal interactive shell on
890 the remote host, this option uses @samp{ssh -t -t @var{host} -l
891 @var{user} /bin/sh} to open a connection. This is useful for users
892 where the normal login shell is set up to ask them a number of
893 questions when logging in. This procedure avoids these questions, and
894 just gives @value{tramp} a more-or-less `standard' login shell to work
897 This is also useful for Windows users where @command{ssh}, when
898 invoked from an @value{emacsname} buffer, tells them that it is not
899 allocating a pseudo tty. When this happens, the login shell is wont
900 to not print any shell prompt, which confuses @value{tramp} mightily.
902 This method supports the @samp{-p} hack.
905 @item @option{scpc} --- @command{ssh} and @command{scp}
908 @cindex scp (with scpx method)
909 @cindex ssh (with scpx method)
911 Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
912 @option{ControlMaster}. This allows @option{scp} to reuse an existing
913 @option{ssh} channel, which increases performance.
915 Before you use this method, you shall check whether your @option{ssh}
916 implementation does support this option. Try from the command line
919 ssh localhost -o ControlMaster=yes
922 This method supports the @samp{-p} hack.
925 @item @option{pscp} --- @command{plink} and @command{pscp}
928 @cindex pscp (with pscp method)
929 @cindex plink (with pscp method)
930 @cindex PuTTY (with pscp method)
932 This method is similar to @option{scp}, but it uses the
933 @command{plink} command to connect to the remote host, and it uses
934 @command{pscp} for transferring the files. These programs are part
935 of PuTTY, an SSH implementation for Windows.
937 This method supports the @samp{-P} hack.
940 @item @option{psftp} --- @command{plink} and @command{psftp}
943 @cindex psftp (with psftp method)
944 @cindex plink (with psftp method)
945 @cindex PuTTY (with psftp method)
947 As you would expect, this method is similar to @option{sftp}, but it
948 uses the @command{plink} command to connect to the remote host, and it
949 uses @command{psftp} for transferring the files. These programs are
950 part of PuTTY, an SSH implementation for Windows.
952 This method supports the @samp{-P} hack.
955 @item @option{fcp} --- @command{fsh} and @command{fcp}
958 @cindex fsh (with fcp method)
959 @cindex fcp (with fcp method)
961 This method is similar to @option{scp}, but it uses the @command{fsh}
962 command to connect to the remote host, and it uses @command{fcp} for
963 transferring the files. @command{fsh/fcp} are a front-end for
964 @command{ssh} which allow for reusing the same @command{ssh} session
965 for submitting several commands. This avoids the startup overhead of
966 @command{scp} (which has to establish a secure connection whenever it
967 is called). Note, however, that you can also use one of the inline
968 methods to achieve a similar effect.
970 This method uses the command @samp{fsh @var{host} -l @var{user}
971 /bin/sh -i} to establish the connection, it does not work to just say
972 @command{fsh @var{host} -l @var{user}}.
977 There is no inline method using @command{fsh} as the multiplexing
978 provided by the program is not very useful in our context. @value{tramp}
979 opens just one connection to the remote host and then keeps it open,
987 This is not a native @value{tramp} method. Instead of, it forwards all
988 requests to @value{ftppackagename}.
990 This works only for unified filenames, see @ref{Issues}.
994 @item @option{smb} --- @command{smbclient}
998 This is another not natural @value{tramp} method. It uses the
999 @command{smbclient} command on different Unices in order to connect to
1000 an SMB server. An SMB server might be a Samba (or CIFS) server on
1001 another UNIX host or, more interesting, a host running MS Windows. So
1002 far, it is tested towards MS Windows NT, MS Windows 2000, and MS
1005 The first directory in the localname must be a share name on the remote
1006 host. Remember, that the @code{$} character in which default shares
1007 usually end, must be written @code{$$} due to environment variable
1008 substitution in file names. If no share name is given (i.e. remote
1009 directory @code{/}), all available shares are listed.
1011 Since authorization is done on share level, you will be prompted
1012 always for a password if you access another share on the same host.
1013 This can be suppressed by @ref{Password caching}.
1015 MS Windows uses for authorization both a user name and a domain name.
1016 Because of this, the @value{tramp} syntax has been extended: you can
1017 specify a user name which looks like @code{user%domain} (the real user
1018 name, then a percent sign, then the domain name). So, to connect to
1019 the machine @code{melancholia} as user @code{daniel} of the domain
1020 @code{BIZARRE}, and edit @file{.emacs} in the home directory (share
1021 @code{daniel$}) I would specify the filename @file{@trampfn{smb,
1022 daniel%BIZARRE, melancholia, /daniel$$/.emacs}}.
1024 Depending on the Windows domain configuration, a Windows user might be
1025 considered as domain user per default. In order to connect as local
1026 user, the WINS name of that machine must be given as domain name.
1027 Usually, it is the machine name in capital letters. In the example
1028 above, the local user @code{daniel} would be specified as
1029 @file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}.
1031 The domain name as well as the user name are optional. If no user
1032 name is specified at all, the anonymous user (without password
1033 prompting) is assumed. This is different from all other @value{tramp}
1034 methods, where in such a case the local user name is taken.
1036 The @option{smb} method supports the @samp{-p} hack.
1038 @strong{Please note:} If @value{emacsname} runs locally under MS
1039 Windows, this method isn't available. Instead of, you can use UNC
1040 file names like @file{//melancholia/daniel$$/.emacs}. The only
1041 disadvantage is that there's no possibility to specify another user
1048 @node Gateway methods
1049 @section Gateway methods
1050 @cindex methods, gateway
1051 @cindex gateway methods
1053 Gateway methods are not methods to access a remote host directly.
1054 These methods are intended to pass firewalls or proxy servers.
1055 Therefore, they can be used for proxy host declarations
1056 (@pxref{Multi-hops}) only.
1058 A gateway method must come always along with a method who supports
1059 port setting (referred to as @samp{-p} kludge). This is because
1060 @value{tramp} targets the accompanied method to
1061 @file{localhost#random_port}, from where the firewall or proxy server
1064 Gateway methods support user name and password declarations. These
1065 are used to authenticate towards the corresponding firewall or proxy
1066 server. They can be passed only if your friendly administrator has
1067 granted your access.
1070 @item @option{tunnel}
1071 @cindex method tunnel
1072 @cindex tunnel method
1074 This method implements an HTTP tunnel via the @command{CONNECT}
1075 command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server
1076 shall support this command.
1078 As authentication method, only @option{Basic Authentication} (see RFC
1079 2617) is implemented so far. If no port number is given in the
1080 declaration, port @option{8080} is used for the proxy server.
1083 @item @option{socks}
1084 @cindex method socks
1085 @cindex socks method
1087 The @command{socks} method provides access to SOCKSv5 servers (see
1088 RFC 1928). @option{Username/Password Authentication} according to RFC
1091 The default port number of the socks server is @option{1080}, if not
1092 specified otherwise.
1098 @node Default Method
1099 @section Selecting a default method
1100 @cindex default method
1102 @vindex tramp-default-method
1103 When you select an appropriate transfer method for your typical usage
1104 you should set the variable @code{tramp-default-method} to reflect that
1105 choice. This variable controls which method will be used when a method
1106 is not specified in the @value{tramp} file name. For example:
1109 (setq tramp-default-method "ssh")
1112 @vindex tramp-default-method-alist
1113 You can also specify different methods for certain user/host
1114 combinations, via the variable @code{tramp-default-method-alist}. For
1115 example, the following two lines specify to use the @option{ssh}
1116 method for all user names matching @samp{john} and the @option{rsync}
1117 method for all host names matching @samp{lily}. The third line
1118 specifies to use the @option{su} method for the user @samp{root} on
1119 the machine @samp{localhost}.
1122 (add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
1123 (add-to-list 'tramp-default-method-alist '("lily" "" "rsync"))
1124 (add-to-list 'tramp-default-method-alist
1125 '("\\`localhost\\'" "\\`root\\'" "su"))
1129 See the documentation for the variable
1130 @code{tramp-default-method-alist} for more details.
1132 External transfer methods are normally preferable to inline transfer
1133 methods, giving better performance.
1135 @xref{Inline methods}.
1136 @xref{External transfer methods}.
1138 Another consideration with the selection of transfer methods is the
1139 environment you will use them in and, especially when used over the
1140 Internet, the security implications of your preferred method.
1142 The @option{rsh} and @option{telnet} methods send your password as
1143 plain text as you log in to the remote machine, as well as
1144 transferring the files in such a way that the content can easily be
1145 read from other machines.
1147 If you need to connect to remote systems that are accessible from the
1148 Internet, you should give serious thought to using @option{ssh} based
1149 methods to connect. These provide a much higher level of security,
1150 making it a non-trivial exercise for someone to obtain your password
1151 or read the content of the files you are editing.
1154 @subsection Which method is the right one for me?
1155 @cindex choosing the right method
1157 Given all of the above, you are probably thinking that this is all fine
1158 and good, but it's not helping you to choose a method! Right you are.
1159 As a developer, we don't want to boss our users around but give them
1160 maximum freedom instead. However, the reality is that some users would
1161 like to have some guidance, so here I'll try to give you this guidance
1162 without bossing you around. You tell me whether it works @dots{}
1164 My suggestion is to use an inline method. For large files, out-of-band
1165 methods might be more efficient, but I guess that most people will want
1166 to edit mostly small files.
1168 I guess that these days, most people can access a remote machine by
1169 using @command{ssh}. So I suggest that you use the @option{ssh}
1170 method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost,
1171 /etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other
1174 If you can't use @option{ssh} to log in to the remote host, then
1175 select a method that uses a program that works. For instance, Windows
1176 users might like the @option{plink} method which uses the PuTTY
1177 implementation of @command{ssh}. Or you use Kerberos and thus like
1180 For the special case of editing files on the local host as another
1181 user, see the @option{su} or @option{sudo} methods. They offer
1182 shortened syntax for the @samp{root} account, like
1183 @file{@trampfnmhl{su, , /etc/motd}}.
1185 People who edit large files may want to consider @option{scpc} instead
1186 of @option{ssh}, or @option{pscp} instead of @option{plink}. These
1187 out-of-band methods are faster than inline methods for large files.
1188 Note, however, that out-of-band methods suffer from some limitations.
1189 Please try first whether you really get a noticeable speed advantage
1190 from using an out-of-band method! Maybe even for large files, inline
1191 methods are fast enough.
1195 @section Selecting a default user
1196 @cindex default user
1198 The user part of a @value{tramp} file name can be omitted. Usually,
1199 it is replaced by the user name you are logged in. Often, this is not
1200 what you want. A typical use of @value{tramp} might be to edit some
1201 files with root permissions on the local host. This case, you should
1202 set the variable @code{tramp-default-user} to reflect that choice.
1206 (setq tramp-default-user "root")
1209 @code{tramp-default-user} is regarded as obsolete, and will be removed
1212 @vindex tramp-default-user-alist
1213 You can also specify different users for certain method/host
1214 combinations, via the variable @code{tramp-default-user-alist}. For
1215 example, if you always have to use the user @samp{john} in the domain
1216 @samp{somewhere.else}, you can specify the following:
1219 (add-to-list 'tramp-default-user-alist
1220 '("ssh" ".*\\.somewhere\\.else\\'" "john"))
1224 See the documentation for the variable
1225 @code{tramp-default-user-alist} for more details.
1227 One trap to fall in must be known. If @value{tramp} finds a default
1228 user, this user will be passed always to the connection command as
1229 parameter (for example @samp{ssh here.somewhere.else -l john}. If you
1230 have specified another user for your command in its configuration
1231 files, @value{tramp} cannot know it, and the remote access will fail.
1232 If you have specified in the given example in @file{~/.ssh/config} the
1236 Host here.somewhere.else
1241 than you must discard selecting a default user by @value{tramp}. This
1242 will be done by setting it to @code{nil} (or @samp{lily}, likewise):
1245 (add-to-list 'tramp-default-user-alist
1246 '("ssh" "\\`here\\.somewhere\\.else\\'" nil))
1249 The last entry in @code{tramp-default-user-alist} could be your
1250 default user you'll apply predominantly. You shall @emph{append} it
1251 to that list at the end:
1254 (add-to-list 'tramp-default-user-alist '(nil nil "jonas") t)
1259 @section Selecting a default host
1260 @cindex default host
1262 @vindex tramp-default-host
1263 Finally, it is even possible to omit the host name part of a
1264 @value{tramp} file name. This case, the value of the variable
1265 @code{tramp-default-host} is used. Per default, it is initialized
1266 with the host name your local @value{emacsname} is running.
1268 If you, for example, use @value{tramp} mainly to contact the host
1269 @samp{target} as user @samp{john}, you can specify:
1272 (setq tramp-default-user "john"
1273 tramp-default-host "target")
1276 Then the simple file name @samp{@trampfnmhl{ssh,,}} will connect you
1277 to John's home directory on target.
1279 Note, however, that the most simplification @samp{@trampfnmhl{,,}}
1280 won't work, because @samp{/:} is the prefix for quoted file names.
1285 @section Connecting to a remote host using multiple hops
1289 Sometimes, the methods described before are not sufficient. Sometimes,
1290 it is not possible to connect to a remote host using a simple command.
1291 For example, if you are in a secured network, you might have to log in
1292 to a `bastion host' first before you can connect to the outside world.
1293 Of course, the target host may also require a bastion host.
1295 @vindex tramp-default-proxies-alist
1296 In order to specify such multiple hops, it is possible to define a proxy
1297 host to pass through, via the variable
1298 @code{tramp-default-proxies-alist}. This variable keeps a list of
1299 triples (@var{host} @var{user} @var{proxy}).
1301 The first matching item specifies the proxy host to be passed for a
1302 file name located on a remote target matching @var{user}@@@var{host}.
1303 @var{host} and @var{user} are regular expressions or @code{nil}, which
1304 is interpreted as a regular expression which always matches.
1306 @var{proxy} must be a Tramp filename which localname part is ignored.
1307 Method and user name on @var{proxy} are optional, which is interpreted
1308 with the default values.
1310 The method must be an inline or gateway method (@pxref{Inline
1311 methods}, @pxref{Gateway methods}).
1314 The method must be an inline method (@pxref{Inline methods}).
1316 If @var{proxy} is @code{nil}, no additional hop is required reaching
1317 @var{user}@@@var{host}.
1319 If you, for example, must pass the host @samp{bastion.your.domain} as
1320 user @samp{bird} for any remote host which is not located in your local
1324 (add-to-list 'tramp-default-proxies-alist
1325 '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}"))
1326 (add-to-list 'tramp-default-proxies-alist
1327 '("\\.your\\.domain\\'" nil nil))
1330 Please note the order of the code. @code{add-to-list} adds elements at the
1331 beginning of a list. Therefore, most relevant rules must be added last.
1333 Proxy hosts can be cascaded. If there is another host called
1334 @samp{jump.your.domain}, which is the only one in your local domain who
1335 is allowed connecting @samp{bastion.your.domain}, you can add another
1339 (add-to-list 'tramp-default-proxies-alist
1340 '("\\`bastion\\.your\\.domain\\'"
1342 "@trampfnmhl{ssh, jump.your.domain,}"))
1345 @var{proxy} can contain the patterns @code{%h} or @code{%u}. These
1346 patterns are replaced by the strings matching @var{host} or
1347 @var{user}, respectively.
1349 If you, for example, wants to work as @samp{root} on hosts in the
1350 domain @samp{your.domain}, but login as @samp{root} is disabled for
1351 non-local access, you might add the following rule:
1354 (add-to-list 'tramp-default-proxies-alist
1355 '("\\.your\\.domain\\'" "\\`root\\'" "@trampfnmhl{ssh, %h,}"))
1358 Opening @file{@trampfnmhl{sudo, randomhost.your.domain,}} would
1359 connect first @samp{randomhost.your.domain} via @code{ssh} under your
1360 account name, and perform @code{sudo -u root} on that host afterwards.
1361 It is important to know that the given method is applied on the host
1362 which has been reached so far. @code{sudo -u root}, applied on your
1363 local host, wouldn't be useful here.
1365 This is the recommended configuration to work as @samp{root} on remote
1369 Finally, @code{tramp-default-proxies-alist} can be used to pass
1370 firewalls or proxy servers. Imagine your local network has a host
1371 @samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to
1372 the outer world. Your friendly administrator has granted you access
1373 under your user name to @samp{host.other.domain} on that proxy
1374 server.@footnote{HTTP tunnels are intended for secure SSL/TLS
1375 communication. Therefore, many proxy server restrict the tunnels to
1376 related target ports. You might need to run your ssh server on your
1377 target host @samp{host.other.domain} on such a port, like 443 (https).
1378 See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall}
1379 for discussion of ethical issues.} You would need to add the
1383 (add-to-list 'tramp-default-proxies-alist
1384 '("\\`host\\.other\\.domain\\'" nil
1385 "@trampfnmhl{tunnel, proxy.your.domain#3128,}"))
1388 Gateway methods can be declared as first hop only in a multiple hop
1393 @node Customizing Methods
1394 @section Using Non-Standard Methods
1395 @cindex customizing methods
1396 @cindex using non-standard methods
1397 @cindex create your own methods
1399 There is a variable @code{tramp-methods} which you can change if the
1400 predefined methods don't seem right.
1402 For the time being, I'll refer you to the Lisp documentation of that
1403 variable, accessible with @kbd{C-h v tramp-methods @key{RET}}.
1406 @node Customizing Completion
1407 @section Selecting config files for user/host name completion
1408 @cindex customizing completion
1409 @cindex selecting config files
1410 @vindex tramp-completion-function-alist
1412 The variable @code{tramp-completion-function-alist} is intended to
1413 customize which files are taken into account for user and host name
1414 completion (@pxref{Filename completion}). For every method, it keeps
1415 a set of configuration files, accompanied by a Lisp function able to
1416 parse that file. Entries in @code{tramp-completion-function-alist}
1417 have the form (@var{method} @var{pair1} @var{pair2} ...).
1419 Each @var{pair} is composed of (@var{function} @var{file}).
1420 @var{function} is responsible to extract user names and host names
1421 from @var{file} for completion. There are two functions which access
1424 @defun tramp-get-completion-function method
1425 This function returns the list of completion functions for @var{method}.
1429 (tramp-get-completion-function "rsh")
1431 @result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
1432 (tramp-parse-rhosts "~/.rhosts"))
1436 @defun tramp-set-completion-function method function-list
1437 This function sets @var{function-list} as list of completion functions
1442 (tramp-set-completion-function "ssh"
1443 '((tramp-parse-sconfig "/etc/ssh_config")
1444 (tramp-parse-sconfig "~/.ssh/config")))
1446 @result{} ((tramp-parse-sconfig "/etc/ssh_config")
1447 (tramp-parse-sconfig "~/.ssh/config"))
1451 The following predefined functions parsing configuration files exist:
1454 @item @code{tramp-parse-rhosts}
1455 @findex tramp-parse-rhosts
1457 This function parses files which are syntactical equivalent to
1458 @file{~/.rhosts}. It returns both host names and user names, if
1461 @item @code{tramp-parse-shosts}
1462 @findex tramp-parse-shosts
1464 This function parses files which are syntactical equivalent to
1465 @file{~/.ssh/known_hosts}. Since there are no user names specified
1466 in such files, it can return host names only.
1468 @item @code{tramp-parse-sconfig}
1469 @findex tramp-parse-shosts
1471 This function returns the host nicknames defined by @code{Host} entries
1472 in @file{~/.ssh/config} style files.
1474 @item @code{tramp-parse-shostkeys}
1475 @findex tramp-parse-shostkeys
1477 SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and
1478 @file{~/ssh2/hostkeys/*}. Hosts are coded in file names
1479 @file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names
1480 are always @code{nil}.
1482 @item @code{tramp-parse-sknownhosts}
1483 @findex tramp-parse-shostkeys
1485 Another SSH2 style parsing of directories like
1486 @file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This
1487 case, hosts names are coded in file names
1488 @file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}.
1490 @item @code{tramp-parse-hosts}
1491 @findex tramp-parse-hosts
1493 A function dedicated to @file{/etc/hosts} style files. It returns
1496 @item @code{tramp-parse-passwd}
1497 @findex tramp-parse-passwd
1499 A function which parses @file{/etc/passwd} like files. Obviously, it
1500 can return user names only.
1502 @item @code{tramp-parse-netrc}
1503 @findex tramp-parse-netrc
1505 Finally, a function which parses @file{~/.netrc} like files.
1508 If you want to keep your own data in a file, with your own structure,
1509 you might provide such a function as well. This function must meet
1510 the following conventions:
1512 @defun my-tramp-parse file
1513 @var{file} must be either a file name on your host, or @code{nil}.
1514 The function must return a list of (@var{user} @var{host}), which are
1515 taken as candidates for user and host name completion.
1519 (my-tramp-parse "~/.my-tramp-hosts")
1521 @result{} ((nil "toto") ("daniel" "melancholia"))
1526 @node Password caching
1527 @section Reusing passwords for several connections.
1530 Sometimes it is necessary to connect to the same remote host several
1531 times. Reentering passwords again and again would be annoying, when
1532 the chosen method does not support access without password prompt
1533 through own configuration.
1535 By default, @value{tramp} caches the passwords entered by you. They will
1536 be reused next time if a connection needs them for the same user name
1537 and host name, independently of the connection method.
1539 @vindex password-cache-expiry
1540 Passwords are not saved permanently, that means the password caching
1541 is limited to the lifetime of your @value{emacsname} session. You
1542 can influence the lifetime of password caching by customizing the
1543 variable @code{password-cache-expiry}. The value is the number of
1544 seconds how long passwords are cached. Setting it to @code{nil}
1545 disables the expiration.
1547 @findex tramp-clear-passwd
1548 A password is removed from the cache if a connection isn't established
1549 successfully. You can remove a password from the cache also by
1550 executing @kbd{M-x tramp-clear-passwd} in a buffer containing a
1551 related remote file or directory.
1553 @vindex password-cache
1554 If you don't like this feature for security reasons, password caching
1555 can be disabled totally by customizing the variable
1556 @code{password-cache} (setting it to @code{nil}).
1558 Implementation Note: password caching is based on the package
1559 @file{password.el} in No Gnus. For the time being, it is activated
1560 only when this package is seen in the @code{load-path} while loading
1562 @ifset installchapter
1563 If you don't use No Gnus, you can take @file{password.el} from the
1564 @value{tramp} @file{contrib} directory, see @ref{Installation
1567 It will be activated mandatory once No Gnus has found its way into
1571 @node Connection caching
1572 @section Reusing connection related information.
1575 @vindex tramp-persistency-file-name
1576 In order to reduce initial connection time, @value{tramp} stores
1577 connection related information persistently. The variable
1578 @code{tramp-persistency-file-name} keeps the file name where these
1579 information are written. Its default value is
1581 @file{~/.emacs.d/tramp}.
1584 @file{~/.xemacs/tramp}.
1586 It is recommended to choose a local file name.
1588 @value{tramp} reads this file during startup, and writes it when
1589 exiting @value{emacsname}. You can simply remove this file if
1590 @value{tramp} shall be urged to recompute these information next
1591 @value{emacsname} startup time.
1593 Using such persistent information can be disabled by setting
1594 @code{tramp-persistency-file-name} to @code{nil}.
1597 @node Remote Programs
1598 @section How @value{tramp} finds and uses programs on the remote machine.
1600 @value{tramp} depends on a number of programs on the remote host in order to
1601 function, including @command{ls}, @command{test}, @command{find} and
1604 In addition to these required tools, there are various tools that may be
1605 required based on the connection method. See @ref{Inline methods} and
1606 @ref{External transfer methods} for details on these.
1608 Certain other tools, such as @command{perl} (or @command{perl5}) and
1609 @command{grep} will be used if they can be found. When they are
1610 available, they are used to improve the performance and accuracy of
1613 @vindex tramp-remote-path
1614 When @value{tramp} connects to the remote machine, it searches for the
1615 programs that it can use. The variable @code{tramp-remote-path}
1616 controls the directories searched on the remote machine.
1618 By default, this is set to a reasonable set of defaults for most
1619 machines. The symbol @code{tramp-default-remote-path} is a place
1620 holder, it is replaced by the list of directories received via the
1621 command @command{getconf PATH} on your remote machine. For example,
1622 on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is
1623 @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is
1624 recommended to apply this symbol on top of @code{tramp-remote-path}.
1626 It is possible, however, that your local (or remote ;) system
1627 administrator has put the tools you want in some obscure local
1630 In this case, you can still use them with @value{tramp}. You simply need to
1631 add code to your @file{.emacs} to add the directory to the remote path.
1632 This will then be searched by @value{tramp} when you connect and the software
1635 To add a directory to the remote search path, you could use code such
1639 @i{;; We load @value{tramp} to define the variable.}
1641 @i{;; We have @command{perl} in "/usr/local/perl/bin"}
1642 (add-to-list 'tramp-remote-path "/usr/local/perl/bin")
1646 @node Remote shell setup
1647 @comment node-name, next, previous, up
1648 @section Remote shell setup hints
1649 @cindex remote shell setup
1650 @cindex @file{.profile} file
1651 @cindex @file{.login} file
1652 @cindex shell init files
1654 As explained in the @ref{Overview} section, @value{tramp} connects to the
1655 remote host and talks to the shell it finds there. Of course, when you
1656 log in, the shell executes its init files. Suppose your init file
1657 requires you to enter the birth date of your mother; clearly @value{tramp}
1658 does not know this and hence fails to log you in to that host.
1660 There are different possible strategies for pursuing this problem. One
1661 strategy is to enable @value{tramp} to deal with all possible situations.
1662 This is a losing battle, since it is not possible to deal with
1663 @emph{all} situations. The other strategy is to require you to set up
1664 the remote host such that it behaves like @value{tramp} expects. This might
1665 be inconvenient because you have to invest a lot of effort into shell
1666 setup before you can begin to use @value{tramp}.
1668 The package, therefore, pursues a combined approach. It tries to
1669 figure out some of the more common setups, and only requires you to
1670 avoid really exotic stuff. For example, it looks through a list of
1671 directories to find some programs on the remote host. And also, it
1672 knows that it is not obvious how to check whether a file exists, and
1673 therefore it tries different possibilities. (On some hosts and
1674 shells, the command @command{test -e} does the trick, on some hosts
1675 the shell builtin doesn't work but the program @command{/usr/bin/test
1676 -e} or @command{/bin/test -e} works. And on still other hosts,
1677 @command{ls -d} is the right way to do this.)
1679 Below you find a discussion of a few things that @value{tramp} does not deal
1680 with, and that you therefore have to set up correctly.
1683 @item @var{shell-prompt-pattern}
1684 @vindex shell-prompt-pattern
1686 After logging in to the remote host, @value{tramp} has to wait for the remote
1687 shell startup to finish before it can send commands to the remote
1688 shell. The strategy here is to wait for the shell prompt. In order to
1689 recognize the shell prompt, the variable @code{shell-prompt-pattern} has
1690 to be set correctly to recognize the shell prompt on the remote host.
1692 Note that @value{tramp} requires the match for @code{shell-prompt-pattern}
1693 to be at the end of the buffer. Many people have something like the
1694 following as the value for the variable: @code{"^[^>$][>$] *"}. Now
1695 suppose your shell prompt is @code{a <b> c $ }. In this case,
1696 @value{tramp} recognizes the @code{>} character as the end of the prompt,
1697 but it is not at the end of the buffer.
1699 @item @var{tramp-shell-prompt-pattern}
1700 @vindex tramp-shell-prompt-pattern
1702 This regular expression is used by @value{tramp} in the same way as
1703 @code{shell-prompt-pattern}, to match prompts from the remote shell.
1704 This second variable exists because the prompt from the remote shell
1705 might be different from the prompt from a local shell --- after all,
1706 the whole point of @value{tramp} is to log in to remote hosts as a
1707 different user. The default value of
1708 @code{tramp-shell-prompt-pattern} is the same as the default value of
1709 @code{shell-prompt-pattern}, which is reported to work well in many
1712 @item @command{tset} and other questions
1713 @cindex Unix command tset
1714 @cindex tset Unix command
1716 Some people invoke the @command{tset} program from their shell startup
1717 scripts which asks the user about the terminal type of the shell.
1718 Maybe some shells ask other questions when they are started.
1719 @value{tramp} does not know how to answer these questions. There are
1720 two approaches for dealing with this problem. One approach is to take
1721 care that the shell does not ask any questions when invoked from
1722 @value{tramp}. You can do this by checking the @code{TERM}
1723 environment variable, it will be set to @code{dumb} when connecting.
1725 @vindex tramp-terminal-type
1726 The variable @code{tramp-terminal-type} can be used to change this value
1729 @vindex tramp-actions-before-shell
1730 The other approach is to teach @value{tramp} about these questions. See
1731 the variable @code{tramp-actions-before-shell}. Example:
1734 (defconst my-tramp-prompt-regexp
1735 (concat (regexp-opt '("Enter the birth date of your mother:") t)
1737 "Regular expression matching my login prompt question.")
1739 (defun my-tramp-action (proc vec)
1740 "Enter \"19000101\" in order to give a correct answer."
1741 (save-window-excursion
1742 (with-current-buffer (tramp-get-connection-buffer vec)
1743 (tramp-message vec 6 "\n%s" (buffer-string))
1744 (tramp-send-string vec "19000101"))))
1746 (add-to-list 'tramp-actions-before-shell
1747 '(my-tramp-prompt-regexp my-tramp-action))
1751 @item Environment variables named like users in @file{.profile}
1753 If you have a user named frumple and set the variable @code{FRUMPLE} in
1754 your shell environment, then this might cause trouble. Maybe rename
1755 the variable to @code{FRUMPLE_DIR} or the like.
1757 This weird effect was actually reported by a @value{tramp} user!
1760 @item Non-Bourne commands in @file{.profile}
1762 After logging in to the remote host, @value{tramp} issues the command
1763 @command{exec /bin/sh}. (Actually, the command is slightly
1764 different.) When @command{/bin/sh} is executed, it reads some init
1765 files, such as @file{~/.shrc} or @file{~/.profile}.
1767 Now, some people have a login shell which is not @code{/bin/sh} but a
1768 Bourne-ish shell such as bash or ksh. Some of these people might put
1769 their shell setup into the files @file{~/.shrc} or @file{~/.profile}.
1770 This way, it is possible for non-Bourne constructs to end up in those
1771 files. Then, @command{exec /bin/sh} might cause the Bourne shell to
1772 barf on those constructs.
1774 As an example, imagine somebody putting @command{export FOO=bar} into
1775 the file @file{~/.profile}. The standard Bourne shell does not
1776 understand this syntax and will emit a syntax error when it reaches
1779 Another example is the tilde (@code{~}) character, say when adding
1780 @file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this
1781 character, and since there is usually no directory whose name consists
1782 of the single character tilde, strange things will happen.
1784 What can you do about this?
1786 Well, one possibility is to make sure that everything in
1787 @file{~/.shrc} and @file{~/.profile} on all remote hosts is
1788 Bourne-compatible. In the above example, instead of @command{export
1789 FOO=bar}, you might use @command{FOO=bar; export FOO} instead.
1791 The other possibility is to put your non-Bourne shell setup into some
1792 other files. For example, bash reads the file @file{~/.bash_profile}
1793 instead of @file{~/.profile}, if the former exists. So bash
1794 aficionados just rename their @file{~/.profile} to
1795 @file{~/.bash_profile} on all remote hosts, and Bob's your uncle.
1797 The @value{tramp} developers would like to circumvent this problem, so
1798 if you have an idea about it, please tell us. However, we are afraid
1799 it is not that simple: before saying @command{exec /bin/sh},
1800 @value{tramp} does not know which kind of shell it might be talking
1801 to. It could be a Bourne-ish shell like ksh or bash, or it could be a
1802 csh derivative like tcsh, or it could be zsh, or even rc. If the
1803 shell is Bourne-ish already, then it might be prudent to omit the
1804 @command{exec /bin/sh} step. But how to find out if the shell is
1810 @node Auto-save and Backup
1811 @section Auto-save and Backup configuration
1815 @vindex backup-directory-alist
1818 @vindex bkup-backup-directory-info
1821 Normally, @value{emacsname} writes backup files to the same directory
1822 as the original files, but this behavior can be changed via the
1825 @code{backup-directory-alist}.
1828 @code{bkup-backup-directory-info}.
1830 In connection with @value{tramp}, this can have unexpected side
1831 effects. Suppose that you specify that all backups should go to the
1832 directory @file{~/.emacs.d/backups/}, and then you edit the file
1833 @file{@trampfn{su, root, localhost, /etc/secretfile}}. The effect is
1834 that the backup file will be owned by you and not by root, thus
1835 possibly enabling others to see it even if they were not intended to
1840 @code{backup-directory-alist}
1843 @code{bkup-backup-directory-info}
1845 is @code{nil} (the default), such problems do not occur.
1847 Therefore, it is useful to set special values for @value{tramp}
1848 files. For example, the following statement effectively `turns off'
1851 @code{backup-directory-alist}
1854 @code{bkup-backup-directory-info}
1856 for @value{tramp} files:
1860 (add-to-list 'backup-directory-alist
1861 (cons tramp-file-name-regexp nil))
1866 (require 'backup-dir)
1867 (add-to-list 'bkup-backup-directory-info
1868 (list tramp-file-name-regexp ""))
1872 Another possibility is to use the @value{tramp} variable
1874 @code{tramp-backup-directory-alist}.
1877 @code{tramp-bkup-backup-directory-info}.
1879 This variable has the same meaning like
1881 @code{backup-directory-alist}.
1884 @code{bkup-backup-directory-info}.
1886 If a @value{tramp} file is backed up, and DIRECTORY is an absolute
1887 local file name, DIRECTORY is prepended with the @value{tramp} file
1888 name prefix of the file to be backed up.
1895 (add-to-list 'backup-directory-alist
1896 (cons "." "~/.emacs.d/backups/"))
1897 (setq tramp-backup-directory-alist backup-directory-alist)
1902 (require 'backup-dir)
1903 (add-to-list 'bkup-backup-directory-info
1904 (list "." "~/.emacs.d/backups/" 'full-path))
1905 (setq tramp-bkup-backup-directory-info bkup-backup-directory-info)
1910 The backup file name of @file{@trampfn{su, root, localhost,
1911 /etc/secretfile}} would be
1913 @file{@trampfn{su, root, localhost,
1914 ~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
1917 @file{@trampfn{su, root, localhost,
1918 ~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}
1921 The same problem can happen with auto-saving files.
1923 Since @value{emacsname} 21, the variable
1924 @code{auto-save-file-name-transforms} keeps information, on which
1925 directory an auto-saved file should go. By default, it is initialized
1926 for @value{tramp} files to the local temporary directory.
1928 On some versions of @value{emacsname}, namely the version built for
1929 Debian GNU/Linux, the variable @code{auto-save-file-name-transforms}
1930 contains the directory where @value{emacsname} was built. A
1931 workaround is to manually set the variable to a sane value.
1933 If auto-saved files should go into the same directory as the original
1934 files, @code{auto-save-file-name-transforms} should be set to @code{nil}.
1936 Another possibility is to set the variable
1937 @code{tramp-auto-save-directory} to a proper value.
1940 For this purpose you can set the variable @code{auto-save-directory}
1945 @node Windows setup hints
1946 @section Issues with Cygwin ssh
1947 @cindex Cygwin, issues
1949 This section needs a lot of work! Please help.
1951 @cindex method sshx with Cygwin
1952 @cindex sshx method with Cygwin
1953 The recent Cygwin installation of @command{ssh} works only with a
1954 Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x
1955 eshell}, and starting @kbd{ssh test.machine}. The problem is evident
1956 if you see a message like this:
1959 Pseudo-terminal will not be allocated because stdin is not a terminal.
1962 Older @command{ssh} versions of Cygwin are told to cooperate with
1963 @value{tramp} selecting @option{sshx} as the connection method. You
1964 can find information about setting up Cygwin in their FAQ at
1965 @uref{http://cygwin.com/faq/}.
1967 @cindex method scpx with Cygwin
1968 @cindex scpx method with Cygwin
1969 If you wish to use the @option{scpx} connection method, then you might
1970 have the problem that @value{emacsname} calls @command{scp} with a
1971 Windows filename such as @code{c:/foo}. The Cygwin version of
1972 @command{scp} does not know about Windows filenames and interprets
1973 this as a remote filename on the host @code{c}.
1975 One possible workaround is to write a wrapper script for @option{scp}
1976 which converts the Windows filename to a Cygwinized filename.
1978 @cindex Cygwin and ssh-agent
1979 @cindex SSH_AUTH_SOCK and @value{emacsname} on Windows
1980 If you want to use either @option{ssh} based method on Windows, then
1981 you might encounter problems with @command{ssh-agent}. Using this
1982 program, you can avoid typing the pass-phrase every time you log in.
1983 However, if you start @value{emacsname} from a desktop shortcut, then
1984 the environment variable @code{SSH_AUTH_SOCK} is not set and so
1985 @value{emacsname} and thus @value{tramp} and thus @command{ssh} and
1986 @command{scp} started from @value{tramp} cannot communicate with
1987 @command{ssh-agent}. It works better to start @value{emacsname} from
1990 If anyone knows how to start @command{ssh-agent} under Windows in such a
1991 way that desktop shortcuts can profit, please holler. I don't really
1992 know anything at all about Windows@dots{}
1996 @chapter Using @value{tramp}
1997 @cindex using @value{tramp}
1999 Once you have installed @value{tramp} it will operate fairly
2000 transparently. You will be able to access files on any remote machine
2001 that you can log in to as though they were local.
2003 Files are specified to @value{tramp} using a formalized syntax specifying the
2004 details of the system to connect to. This is similar to the syntax used
2005 by the @value{ftppackagename} package.
2008 Something that might happen which surprises you is that
2009 @value{emacsname} remembers all your keystrokes, so if you see a
2010 password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}}
2011 twice instead of once, then the second keystroke will be processed by
2012 @value{emacsname} after @value{tramp} has done its thing. Why, this
2013 type-ahead is normal behavior, you say. Right you are, but be aware
2014 that opening a remote file might take quite a while, maybe half a
2015 minute when a connection needs to be opened. Maybe after half a
2016 minute you have already forgotten that you hit that key!
2019 * Filename Syntax:: @value{tramp} filename conventions.
2020 * Alternative Syntax:: URL-like filename syntax.
2021 * Filename completion:: Filename completion.
2022 * Remote processes:: Integration with other @value{emacsname} packages (@sc{experimental}).
2026 @node Filename Syntax
2027 @section @value{tramp} filename conventions
2028 @cindex filename syntax
2029 @cindex filename examples
2031 To access the file @var{localname} on the remote machine @var{machine}
2032 you would specify the filename @file{@trampfnhl{@var{machine},
2033 @var{localname}}}. This will connect to @var{machine} and transfer
2034 the file using the default method. @xref{Default Method}.
2036 Some examples of @value{tramp} filenames are shown below.
2039 @item @trampfnhl{melancholia, .emacs}
2040 Edit the file @file{.emacs} in your home directory on the machine
2043 @item @trampfnhl{melancholia.danann.net, .emacs}
2044 This edits the same file, using the fully qualified domain name of
2047 @item @trampfnhl{melancholia, ~/.emacs}
2048 This also edits the same file --- the @file{~} is expanded to your
2049 home directory on the remote machine, just like it is locally.
2051 @item @trampfnhl{melancholia, ~daniel/.emacs}
2052 This edits the file @file{.emacs} in the home directory of the user
2053 @code{daniel} on the machine @code{melancholia}. The @file{~<user>}
2054 construct is expanded to the home directory of that user on the remote
2057 @item @trampfnhl{melancholia, /etc/squid.conf}
2058 This edits the file @file{/etc/squid.conf} on the machine
2063 Unless you specify a different name to use, @value{tramp} will use the
2064 current local user name as the remote user name to log in with. If you
2065 need to log in as a different user, you can specify the user name as
2066 part of the filename.
2068 To log in to the remote machine as a specific user, you use the syntax
2069 @file{@trampfnuhl{@var{user}, @var{machine}, @var{path/to.file}}}.
2070 That means that connecting to @code{melancholia} as @code{daniel} and
2071 editing @file{.emacs} in your home directory you would specify
2072 @file{@trampfnuhl{daniel, melancholia, .emacs}}.
2074 It is also possible to specify other file transfer methods
2075 (@pxref{Default Method}) as part of the filename.
2077 This is done by putting the method before the user and host name, as
2078 in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the
2082 This is done by replacing the initial @file{@value{prefix}} with
2083 @file{@value{prefix}<method>@value{postfixhop}}. (Note the trailing
2086 The user, machine and file specification remain the same.
2088 So, to connect to the machine @code{melancholia} as @code{daniel},
2089 using the @option{ssh} method to transfer files, and edit
2090 @file{.emacs} in my home directory I would specify the filename
2091 @file{@trampfn{ssh, daniel, melancholia, .emacs}}.
2094 @node Alternative Syntax
2095 @section URL-like filename syntax
2096 @cindex filename syntax
2097 @cindex filename examples
2099 Additionally to the syntax described in the previous chapter, it is
2100 possible to use a URL-like syntax for @value{tramp}. This can be
2101 switched on by customizing the variable @code{tramp-syntax}. Please
2102 note that this feature is experimental for the time being.
2104 The variable @code{tramp-syntax} must be set before requiring @value{tramp}:
2107 (setq tramp-syntax 'url)
2111 Then, a @value{tramp} filename would look like this:
2112 @file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}.
2113 @file{/@var{method}://} is mandatory, all other parts are optional.
2114 @file{:@var{port}} is useful for methods only who support this.
2116 The last example from the previous section would look like this:
2117 @file{/ssh://daniel@@melancholia/.emacs}.
2119 For the time being, @code{tramp-syntax} can have the following values:
2123 @item @code{ftp} -- That is the default syntax
2124 @item @code{url} -- URL-like syntax
2127 @item @code{sep} -- That is the default syntax
2128 @item @code{url} -- URL-like syntax
2129 @item @code{ftp} -- EFS-like syntax
2134 @node Filename completion
2135 @section Filename completion
2136 @cindex filename completion
2138 Filename completion works with @value{tramp} for completion of method
2139 names, of user names and of machine names as well as for completion of
2140 file names on remote machines.
2142 In order to enable this, Partial Completion mode must be set
2143 on@footnote{If you don't use Partial Completion mode, but want to
2144 keep full completion, load @value{tramp} like this in your
2148 ;; Preserve Tramp's completion features.
2149 (let ((partial-completion-mode t))
2154 @xref{Completion Options, , , @value{emacsdir}}.
2158 If you, for example, type @kbd{C-x C-f @value{prefix}t
2159 @key{TAB}}, @value{tramp} might give you as result the choice for
2163 @value{prefixhop}telnet@value{postfixhop} tmp/
2164 @value{prefixhop}toto@value{postfix}
2167 @value{prefixhop}telnet@value{postfixhop} @value{prefixhop}toto@value{postfix}
2171 @samp{@value{prefixhop}telnet@value{postfixhop}}
2172 is a possible completion for the respective method,
2174 @samp{tmp/} stands for the directory @file{/tmp} on your local
2177 and @samp{@value{prefixhop}toto@value{postfix}}
2178 might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts}
2179 file (given you're using default method @option{ssh}).
2181 If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to
2182 @samp{@value{prefix}telnet@value{postfixhop}}.
2183 Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in
2184 your @file{/etc/hosts} file, let's say
2187 @trampfnmhl{telnet,127.0.0.1,} @trampfnmhl{telnet,192.168.0.1,}
2188 @trampfnmhl{telnet,localhost,} @trampfnmhl{telnet,melancholia.danann.net,}
2189 @trampfnmhl{telnet,melancholia,}
2192 Now you can choose the desired machine, and you can continue to
2193 complete file names on that machine.
2195 If the configuration files (@pxref{Customizing Completion}), which
2196 @value{tramp} uses for analysis of completion, offer user names, those user
2197 names will be taken into account as well.
2199 Remote machines, which have been visited in the past and kept
2200 persistently (@pxref{Connection caching}), will be offered too.
2202 Once the remote machine identification is completed, it comes to
2203 filename completion on the remote host. This works pretty much like
2204 for files on the local host, with the exception that minibuffer
2205 killing via a double-slash works only on the filename part, except
2206 that filename part starts with @file{//}.
2208 @xref{Minibuffer File, , , @value{emacsdir}}.
2212 As example, @kbd{@trampfnmhl{telnet,melancholia,/usr/local/bin//etc}
2213 @key{TAB}} would result in
2214 @file{@trampfnmhl{telnet,melancholia,/etc}}, whereas
2215 @kbd{@trampfnmhl{telnet,melancholia,//etc} @key{TAB}} reduces the
2216 minibuffer contents to @file{/etc}. A triple-slash stands for the
2218 i.e. @kbd{@trampfnmhl{telnet,melancholia,/usr/local/bin///etc}
2219 @key{TAB}} expands directly to @file{/etc}.
2223 As example, @kbd{@trampfnmhl{telnet,melancholia,/usr/local/bin//}}
2224 would result in @file{@trampfnmhl{telnet,melancholia,/}}, whereas
2225 @kbd{@trampfnmhl{telnet,melancholia,//}} expands the minibuffer
2226 contents to @file{/}.
2230 @node Remote processes
2231 @section Integration with other @value{emacsname} packages (@sc{experimental}).
2238 @value{tramp} has an @sc{experimental} implementation for running
2239 processes on a remote host. This allows to exploit @value{emacsname}
2240 packages without modification for remote file names. It does not work
2241 for the @option{ftp} and @option{smb} methods.
2243 Remote processes are started when a corresponding command is executed
2244 from a buffer belonging to a remote file or directory. Up to now, the
2245 packages @file{compile.el} (commands like @code{compile} and
2246 @code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}) have been
2247 integrated. Integration of further packages is planned, any help for
2250 When your program is not found in the default search path
2251 @value{tramp} sets on the remote machine, you should either use an
2252 absolute path, or extend @code{tramp-remote-path} (see @ref{Remote
2256 (add-to-list 'tramp-remote-path "~/bin")
2257 (add-to-list 'tramp-remote-path "/appli/pub/bin")
2260 The environment for your program can be adapted by customizing
2261 @code{tramp-remote-process-environment}. This variable is a list of
2262 strings. It is structured like @code{process-environment}. Each
2263 element is a string of the form ENVVARNAME=VALUE. An entry
2264 ENVVARNAME= disables the corresponding environment variable, which
2265 might have been set in your init file like @file{~/.profile}.
2268 Adding an entry can be performed via @code{add-to-list}:
2271 (add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")
2274 Changing or removing an existing entry is not encouraged. The default
2275 values are chosen for proper @value{tramp} work. Nevertheless, if for
2276 example a paranoid system administrator disallows changing the
2277 @var{$HISTORY} environment variable, you can customize
2278 @code{tramp-remote-process-environment}, or you can apply the
2279 following code in your @file{.emacs}:
2282 (let ((process-environment tramp-remote-process-environment))
2283 (setenv "HISTORY" nil)
2284 (setq tramp-remote-process-environment process-environment))
2287 If you use other @value{emacsname} packages which do not run
2288 out-of-the-box on a remote host, please let us know. We will try to
2289 integrate them as well. @xref{Bug Reports}.
2292 @subsection Running eshell on a remote host
2295 @value{tramp} is integrated into @file{eshell.el}. That is, you can
2296 open an interactive shell on your remote host, and run commands there.
2297 After you have started @code{eshell}, you could perform commands like
2301 @b{~ $} cd @trampfnmhl{sudo, , /etc}
2302 @b{@trampfn{sudo, root, host, /etc} $} hostname
2304 @b{@trampfn{sudo, root, host, /etc} $} id
2305 uid=0(root) gid=0(root) groups=0(root)
2306 @b{@trampfn{sudo, root, host, /etc} $} find-file shadow
2308 @b{@trampfn{sudo, root, host, /etc} $}
2313 @chapter Reporting Bugs and Problems
2316 Bugs and problems with @value{tramp} are actively worked on by the
2317 development team. Feature requests and suggestions are also more than
2320 The @value{tramp} mailing list is a great place to get information on
2321 working with @value{tramp}, solving problems and general discussion
2322 and advice on topics relating to the package. It is moderated so
2323 non-subscribers can post but messages will be delayed, possibly up to
2324 48 hours (or longer in case of holidays), until the moderator approves
2327 The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to
2328 this address go to all the subscribers. This is @emph{not} the address
2329 to send subscription requests to.
2331 Subscribing to the list is performed via
2332 @uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/,
2333 the @value{tramp} Mail Subscription Page}.
2335 To report a bug in @value{tramp}, you should execute @kbd{M-x
2336 tramp-bug}. This will automatically generate a buffer with the details
2337 of your system and @value{tramp} version.
2339 When submitting a bug report, please try to describe in excruciating
2340 detail the steps required to reproduce the problem, the setup of the
2341 remote machine and any special conditions that exist. You should also
2342 check that your problem is not described already in @xref{Frequently
2345 If you can identify a minimal test case that reproduces the problem,
2346 include that with your bug report. This will make it much easier for
2347 the development team to analyze and correct the problem.
2349 Before reporting the bug, you should set the verbosity level to 6
2350 (@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and
2351 repeat the bug. Then, include the contents of the @file{*tramp/foo*}
2352 and @file{*debug tramp/foo*} buffers in your bug report. A verbosity
2353 level greater than 6 will produce a very huge debug buffer, which is
2354 mostly not necessary for the analysis.
2356 Please be aware that, with a verbosity level of 6 or greater, the
2357 contents of files and directories will be included in the debug
2358 buffer. Passwords you've typed will never be included there.
2361 @node Frequently Asked Questions
2362 @chapter Frequently Asked Questions
2363 @cindex frequently asked questions
2368 Where can I get the latest @value{tramp}?
2370 @value{tramp} is available under the URL below.
2373 @uref{ftp://ftp.gnu.org/gnu/tramp/}
2376 There is also a Savannah project page.
2379 @uref{http://savannah.gnu.org/projects/tramp/}
2383 Which systems does it work on?
2385 The package has been used successfully on GNU Emacs 21, GNU Emacs 22
2386 and XEmacs 21 (starting with 21.4). Gateway methods are supported for
2389 The package was intended to work on Unix, and it really expects a
2390 Unix-like system on the remote end (except the @option{smb} method),
2391 but some people seemed to have some success getting it to work on MS
2392 Windows NT/2000/XP @value{emacsname}.
2394 There is some informations on @value{tramp} on NT at the following URL;
2395 many thanks to Joe Stoy for providing the information:
2396 @uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/}
2398 @c The link is broken. I've contacted Tom for clarification. Michael.
2400 The above mostly contains patches to old ssh versions; Tom Roche has a
2401 Web page with instructions:
2402 @uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html}
2406 How could I speed up @value{tramp}?
2408 In the backstage, @value{tramp} needs a lot of operations on the
2409 remote host. The time for transferring data from and to the remote
2410 host as well as the time needed to perform the operations there count.
2411 In order to speed up @value{tramp}, one could either try to avoid some
2412 of the operations, or one could try to improve their performance.
2414 Use an external transfer method, like @option{scpc}.
2416 Use caching. This is already enabled by default. Information about
2417 the remote host as well as the remote files are cached for reuse. Th
2418 information about remote hosts is kept in the file specified in
2419 @code{tramp-persistency-file-name}. Keep this file.
2421 Disable version control. If you access remote files which are not
2422 under version control, a lot of check operations can be avoided by
2423 disabling VC. This can be achieved by
2426 (setq vc-handled-backends nil)
2429 Disable excessive traces. The default trace level of @value{tramp},
2430 defined in the variable @code{tramp-verbose}, is 3. You should
2431 increase this level only temporarily, hunting bugs.
2435 @value{tramp} does not connect to the remote host
2437 When @value{tramp} does not connect to the remote host, there are two
2438 reasons heading the bug mailing list:
2443 Unknown characters in the prompt
2445 @value{tramp} needs to recognize the prompt on the remote machine
2446 after execution any command. This is not possible, when the prompt
2447 contains unknown characters like escape sequences for coloring. This
2448 should be avoided on the remote side. @xref{Remote shell setup}. for
2449 setting the regular expression detecting the prompt.
2451 You can check your settings after an unsuccessful connection by
2452 switching to the @value{tramp} connection buffer @file{*tramp/foo*},
2453 setting the cursor at the top of the buffer, and applying the expression
2456 @kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))}
2459 If it fails, or the cursor is not moved at the end of the buffer, your
2460 prompt is not recognised correctly.
2462 A special problem is the zsh, which uses left-hand side and right-hand
2463 side prompts in parallel. Therefore, it is necessary to disable the
2464 zsh line editor on the remote host. You shall add to @file{~/.zshrc}
2465 the following command:
2468 [ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
2473 @value{tramp} doesn't transfer strings with more than 500 characters
2476 On some few systems, the implementation of @code{process-send-string}
2477 seems to be broken for longer strings. It is reported for HP-UX,
2478 FreeBSD and Tru64 Unix, for example. This case, you should customize
2479 the variable @code{tramp-chunksize} to 500. For a description how to
2480 determine whether this is necessary see the documentation of
2481 @code{tramp-chunksize}.
2483 Additionally, it will be useful to set @code{file-precious-flag} to
2484 @code{t} for @value{tramp} files. Then the file contents will be
2485 written into a temporary file first, which is checked for correct
2488 @pxref{Saving Buffers, , , elisp}
2495 (when (file-remote-p default-directory)
2496 (set (make-local-variable 'file-precious-flag) t))))
2503 File name completion does not work with @value{tramp}
2505 When you log in to the remote machine, do you see the output of
2506 @command{ls} in color? If so, this may be the cause of your problems.
2508 @command{ls} outputs @acronym{ANSI} escape sequences that your terminal
2509 emulator interprets to set the colors. These escape sequences will
2510 confuse @value{tramp} however.
2512 In your @file{.bashrc}, @file{.profile} or equivalent on the remote
2513 machine you probably have an alias configured that adds the option
2514 @option{--color=yes} or @option{--color=auto}.
2516 You should remove that alias and ensure that a new login @emph{does not}
2517 display the output of @command{ls} in color. If you still cannot use
2518 filename completion, report a bug to the @value{tramp} developers.
2522 File name completion does not work in large directories
2524 @value{tramp} uses globbing for some operations. (Globbing means to use the
2525 shell to expand wildcards such as `*.c'.) This might create long
2526 command lines, especially in directories with many files. Some shells
2527 choke on long command lines, or don't cope well with the globbing
2530 If you have a large directory on the remote end, you may wish to execute
2531 a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs.
2532 Note that you must first start the right shell, which might be
2533 @command{/bin/sh}, @command{ksh} or @command{bash}, depending on which
2534 of those supports tilde expansion.
2538 How can I get notified when @value{tramp} file transfers are complete?
2540 The following snippet can be put in your @file{~/.emacs} file. It
2541 makes @value{emacsname} beep after reading from or writing to the
2545 (defadvice tramp-handle-write-region
2546 (after tramp-write-beep-advice activate)
2547 " make tramp beep after writing a file."
2551 (defadvice tramp-handle-do-copy-or-rename-file
2552 (after tramp-copy-beep-advice activate)
2553 " make tramp beep after copying a file."
2557 (defadvice tramp-handle-insert-file-contents
2558 (after tramp-copy-beep-advice activate)
2559 " make tramp beep after copying a file."
2567 I'ld like to see a host indication in the mode line when I'm remote
2569 The following code has been tested with @value{emacsname} 22. You
2570 should put it into your @file{~/.emacs}:
2573 (defconst my-mode-line-buffer-identification
2577 (if (file-remote-p default-directory)
2578 (tramp-file-name-host
2579 (tramp-dissect-file-name default-directory))
2581 (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
2582 (substring host-name 0 (match-beginning 1))
2587 mode-line-buffer-identification
2588 my-mode-line-buffer-identification)
2594 mode-line-buffer-identification
2595 my-mode-line-buffer-identification)))
2602 My remote host does not understand default directory listing options
2604 @value{emacsname} computes the @command{dired} options depending on
2605 the local host you are working. If your @command{ls} command on the
2606 remote host does not understand those options, you can change them
2611 'dired-before-readin-hook
2613 (when (file-remote-p default-directory)
2614 (setq dired-actual-switches "-al"))))
2620 There's this @file{~/.sh_history} file on the remote host which keeps
2621 growing and growing. What's that?
2623 Sometimes, @value{tramp} starts @command{ksh} on the remote host for
2624 tilde expansion. Maybe @command{ksh} saves the history by default.
2625 @value{tramp} tries to turn off saving the history, but maybe you have
2626 to help. For example, you could put this in your @file{.kshrc}:
2629 if [ -f $HOME/.sh_history ] ; then
2630 /bin/rm $HOME/.sh_history
2632 if [ "$@{HISTFILE-unset@}" != "unset" ] ; then
2635 if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then
2641 @item There are longish file names to type. How to shorten this?
2643 Let's say you need regularly access to @file{@trampfn{ssh, news,
2644 news.my.domain, /opt/news/etc}}, which is boring to type again and
2645 again. The following approaches can be mixed:
2649 @item Use default values for method and user name:
2651 You can define default methods and user names for hosts,
2652 (@pxref{Default Method}, @pxref{Default User}):
2655 (setq tramp-default-method "ssh"
2656 tramp-default-user "news")
2659 The file name left to type would be
2660 @kbd{C-x C-f @trampfnhl{news.my.domain, /opt/news/etc}}.
2662 Note, that there are some useful settings already. Accessing your
2663 local host as @samp{root} user, is possible just by @kbd{C-x C-f
2666 @item Use configuration possibilities of your method:
2668 Several connection methods (i.e. the programs used) offer powerful
2669 configuration possibilities (@pxref{Customizing Completion}). In the
2670 given case, this could be @file{~/.ssh/config}:
2674 HostName news.my.domain
2678 The file name left to type would be @kbd{C-x C-f @trampfnmhl{ssh, xy,
2679 /opt/news/etc}}. Depending on files in your directories, it is even
2680 possible to complete the hostname with @kbd{C-x C-f
2681 @value{prefix}ssh@value{postfixhop}x @key{TAB}}.
2683 @item Use environment variables:
2685 File names typed in the minibuffer can be expanded by environment
2686 variables. You can set them outside @value{emacsname}, or even with
2690 (setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")
2693 Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you
2694 are. The disadvantage is, that you cannot edit the file name, because
2695 environment variables are not expanded during editing in the
2698 @item Define own keys:
2700 You can define your own key sequences in @value{emacsname}, which can
2701 be used instead of @kbd{C-x C-f}:
2705 [(control x) (control y)]
2711 "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))))
2714 Simply typing @kbd{C-x C-y} would initialize the minibuffer for
2715 editing with your beloved file name.
2717 See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the
2718 Emacs Wiki} for a more comprehensive example.
2720 @item Define own abbreviation (1):
2722 It is possible to define an own abbreviation list for expanding file
2727 'directory-abbrev-alist
2728 '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
2731 This shortens the file openening command to @kbd{C-x C-f /xy
2732 @key{RET}}. The disadvantage is, again, that you cannot edit the file
2733 name, because the expansion happens after entering the file name only.
2735 @item Define own abbreviation (2):
2737 The @code{abbrev-mode} gives more flexibility for editing the
2741 (define-abbrev-table 'my-tramp-abbrev-table
2742 '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))
2745 'minibuffer-setup-hook
2748 (setq local-abbrev-table my-tramp-abbrev-table)))
2750 (defadvice minibuffer-complete
2751 (before my-minibuffer-complete activate)
2754 ;; If you use partial-completion-mode
2755 (defadvice PC-do-completion
2756 (before my-PC-do-completion activate)
2760 After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is
2761 expanded, and you can continue editing.
2763 @item Use bookmarks:
2765 Bookmarks can be used to visit Tramp files or directories.
2767 @pxref{Bookmarks, , , @value{emacsdir}}
2770 When you have opened @file{@trampfn{ssh, news, news.my.domain,
2771 /opt/news/etc/}}, you should save the bookmark via
2773 @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}.
2776 @kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}.
2779 Later on, you can always navigate to that bookmark via
2781 @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}.
2784 @kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}.
2787 @item Use recent files:
2795 remembers visited places.
2798 @pxref{File Conveniences, , , @value{emacsdir}}
2801 @pxref{recent-files, , , edit-utils}
2805 You could keep remote file names in the recent list without checking
2806 their readability through a remote access:
2811 (add-to-list 'recentf-keep 'file-remote-p)
2815 (recent-files-initialize)
2819 (when (file-remote-p (buffer-file-name))
2820 (recent-files-make-permanent)))
2825 The list of files opened recently is reachable via
2827 @kbd{@key{menu-bar} @key{file} @key{Open Recent}}.
2830 @kbd{@key{menu-bar} @key{Recent Files}}.
2834 @item Use filecache:
2836 @file{filecache} remembers visited places. Add the directory into
2840 (eval-after-load "filecache"
2841 '(file-cache-add-directory
2842 "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
2845 Whenever you want to load a file, you can enter @kbd{C-x C-f
2846 C-@key{TAB}} in the minibuffer. The completion is done for the given
2854 How can I disable @value{tramp}?
2856 Shame on you, why did you read until now?
2859 If you just want to have @value{ftppackagename} as default remote
2860 files access package, you should apply the following code:
2863 (setq tramp-default-method "ftp")
2867 Unloading @value{tramp} can be achieved by applying @kbd{M-x
2868 tramp-unload-tramp}.
2870 This resets also the @value{ftppackagename} plugins.
2875 @c For the developer
2876 @node Version Control
2877 @chapter The inner workings of remote version control
2878 @cindex Version Control
2880 Unlike @value{ftppackagename}, @value{tramp} has full shell access to the
2881 remote machine. This makes it possible to provide version control for
2882 files accessed under @value{tramp}.
2884 The actual version control binaries must be installed on the remote
2885 machine, accessible in the directories specified in
2886 @code{tramp-remote-path}.
2888 This transparent integration with the version control systems is one of
2889 the most valuable features provided by @value{tramp}, but it is far from perfect.
2890 Work is ongoing to improve the transparency of the system.
2893 * Version Controlled Files:: Determining if a file is under version control.
2894 * Remote Commands:: Executing the version control commands on the remote machine.
2895 * Changed workfiles:: Detecting if the working file has changed.
2896 * Checking out files:: Bringing the workfile out of the repository.
2897 * Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
2901 @node Version Controlled Files
2902 @section Determining if a file is under version control
2904 The VC package uses the existence of on-disk revision control master
2905 files to determine if a given file is under revision control. These file
2906 tests happen on the remote machine through the standard @value{tramp} mechanisms.
2909 @node Remote Commands
2910 @section Executing the version control commands on the remote machine
2912 There are no hooks provided by VC to allow intercepting of the version
2913 control command execution. The calls occur through the
2914 @code{call-process} mechanism, a function that is somewhat more
2915 efficient than the @code{shell-command} function but that does not
2916 provide hooks for remote execution of commands.
2918 To work around this, the functions @code{vc-do-command} and
2919 @code{vc-simple-command} have been advised to intercept requests for
2920 operations on files accessed via @value{tramp}.
2922 In the case of a remote file, the @code{shell-command} interface is
2923 used, with some wrapper code, to provide the same functionality on the
2924 remote machine as would be seen on the local machine.
2927 @node Changed workfiles
2928 @section Detecting if the working file has changed
2930 As there is currently no way to get access to the mtime of a file on a
2931 remote machine in a portable way, the @code{vc-workfile-unchanged-p}
2932 function is advised to call an @value{tramp} specific function for remote files.
2934 The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC
2935 diff functionality to determine if any changes have occurred between the
2936 workfile and the version control master.
2938 This requires that a shell command be executed remotely, a process that
2939 is notably heavier-weight than the mtime comparison used for local
2940 files. Unfortunately, unless a portable solution to the issue is found,
2941 this will remain the cost of remote version control.
2944 @node Checking out files
2945 @section Bringing the workfile out of the repository
2947 VC will, by default, check for remote files and refuse to act on them
2948 when checking out files from the repository. To work around this
2949 problem, the function @code{vc-checkout} knows about @value{tramp} files and
2950 allows version control to occur.
2953 @node Miscellaneous Version Control
2954 @section Things related to Version Control that don't fit elsewhere
2956 Minor implementation details, &c.
2959 * Remote File Ownership:: How VC determines who owns a workfile.
2960 * Back-end Versions:: How VC determines what release your RCS is.
2964 @node Remote File Ownership
2965 @subsection How VC determines who owns a workfile
2967 @value{emacsname} provides the @code{user-login-name} function to
2968 return the login name of the current user as well as mapping from
2969 arbitrary user id values back to login names. The VC code uses this
2970 functionality to map from the uid of the owner of a workfile to the
2971 login name in some circumstances.
2973 This will not, for obvious reasons, work if the remote system has a
2974 different set of logins. As such, it is necessary to delegate to the
2975 remote machine the job of determining the login name associated with a
2978 Unfortunately, with the profusion of distributed management systems such
2979 as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple,
2980 reliable and portable method for performing this mapping.
2982 Thankfully, the only place in the VC code that depends on the mapping of
2983 a uid to a login name is the @code{vc-file-owner} function. This returns
2984 the login of the owner of the file as a string.
2986 This function has been advised to use the output of @command{ls} on the
2987 remote machine to determine the login name, delegating the problem of
2988 mapping the uid to the login to the remote system which should know more
2992 @node Back-end Versions
2993 @subsection How VC determines what release your RCS is
2995 VC needs to know what release your revision control binaries you are
2996 running as not all features VC supports are available with older
2997 versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}.
2999 The default implementation of VC determines this value the first time it
3000 is needed and then stores the value globally to avoid the overhead of
3001 executing a process and parsing its output each time the information is
3004 Unfortunately, life is not quite so easy when remote version control
3005 comes into the picture. Each remote machine may have a different version
3006 of the version control tools and, while this is painful, we need to
3007 ensure that unavailable features are not used remotely.
3009 To resolve this issue, @value{tramp} currently takes the sledgehammer
3010 approach of making the release values of the revision control tools
3011 local to each @value{tramp} buffer, forcing VC to determine these values
3012 again each time a new file is visited.
3014 This has, quite obviously, some performance implications. Thankfully,
3015 most of the common operations performed by VC do not actually require
3016 that the remote version be known. This makes the problem far less
3019 Eventually these values will be captured by @value{tramp} on a system by
3020 system basis and the results cached to improve performance.
3023 @node Files directories and localnames
3024 @chapter How file names, directories and localnames are mangled and managed.
3027 * Localname deconstruction:: Breaking a localname into its components.
3031 @node Localname deconstruction
3032 @section Breaking a localname into its components.
3034 @value{tramp} file names are somewhat different, obviously, to ordinary file
3035 names. As such, the lisp functions @code{file-name-directory} and
3036 @code{file-name-nondirectory} are overridden within the @value{tramp}
3039 Their replacements are reasonably simplistic in their approach. They
3040 dissect the filename, call the original handler on the localname and
3041 then rebuild the @value{tramp} file name with the result.
3043 This allows the platform specific hacks in the original handlers to take
3044 effect while preserving the @value{tramp} file name information.
3047 @node Traces and Profiles
3048 @chapter How to Customize Traces
3050 All @value{tramp} messages are raised with a verbosity level. The
3051 verbosity level can be any number between 0 and 10. Only messages with
3052 a verbosity level less than or equal to @code{tramp-verbose} are
3055 The verbosity levels are
3057 @w{ 0} silent (no @value{tramp} messages at all)
3058 @*@indent @w{ 1} errors
3059 @*@indent @w{ 2} warnings
3060 @*@indent @w{ 3} connection to remote hosts (default verbosity)
3061 @*@indent @w{ 4} activities
3062 @*@indent @w{ 5} internal
3063 @*@indent @w{ 6} sent and received strings
3064 @*@indent @w{ 7} file caching
3065 @*@indent @w{ 8} connection properties
3066 @*@indent @w{10} traces (huge)
3068 When @code{tramp-verbose} is greater than or equal to 4, the messages
3069 are also written into a @value{tramp} debug buffer. This debug buffer
3070 is useful for analysing problems; sending a @value{tramp} bug report
3071 should be done with @code{tramp-verbose} set to a verbosity level of at
3072 least 6 (@pxref{Bug Reports}).
3074 The debug buffer is in
3076 @ref{Outline Mode, , , @value{emacsdir}}.
3081 That means, you can change the level of messages to be viewed. If you
3082 want, for example, see only messages up to verbosity level 5, you must
3083 enter @kbd{C-u 6 C-c C-q}.
3085 Other keys for navigating are described in
3086 @ref{Outline Visibility, , , @value{emacsdir}}.
3089 @value{tramp} errors are handled internally in order to raise the
3090 verbosity level 1 messages. When you want to get a Lisp backtrace in
3091 case of an error, you need to set both
3094 (setq debug-on-error t
3098 Sometimes, it might be even necessary to step through @value{tramp}
3099 function call traces. Such traces are enabled by the following code:
3104 (mapcar 'trace-function-background
3106 (all-completions "tramp-" obarray 'functionp)))
3107 (untrace-function 'tramp-read-passwd)
3108 (untrace-function 'tramp-gw-basic-authentication)
3111 The function call traces are inserted in the buffer
3112 @file{*trace-output*}. @code{tramp-read-passwd} and
3113 @code{tramp-gw-basic-authentication} shall be disabled when the
3114 function call traces are added to @value{tramp}, because both
3115 functions return password strings, which should not be distributed.
3119 @chapter Debatable Issues and What Was Decided
3122 @item The uuencode method does not always work.
3124 Due to the design of @value{tramp}, the encoding and decoding programs
3125 need to read from stdin and write to stdout. On some systems,
3126 @command{uudecode -o -} will read stdin and write the decoded file to
3127 stdout, on other systems @command{uudecode -p} does the same thing.
3128 But some systems have uudecode implementations which cannot do this at
3129 all---it is not possible to call these uudecode implementations with
3130 suitable parameters so that they write to stdout.
3132 Of course, this could be circumvented: the @code{begin foo 644} line
3133 could be rewritten to put in some temporary file name, then
3134 @command{uudecode} could be called, then the temp file could be
3135 printed and deleted.
3137 But I have decided that this is too fragile to reliably work, so on some
3138 systems you'll have to do without the uuencode methods.
3140 @item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs.
3142 The GNU Emacs maintainers wish to use a unified filename syntax for
3143 Ange-FTP and @value{tramp} so that users don't have to learn a new
3144 syntax. It is sufficient to learn some extensions to the old syntax.
3146 For the XEmacs maintainers, the problems caused from using a unified
3147 filename syntax are greater than the gains. The XEmacs package system
3148 uses EFS for downloading new packages. So, obviously, EFS has to be
3149 installed from the start. If the filenames were unified, @value{tramp}
3150 would have to be installed from the start, too.
3153 @strong{Note:} If you'd like to use a similar syntax like
3154 @value{ftppackagename}, you need the following settings in your init
3158 (setq tramp-unified-filenames t)
3162 The autoload of the @value{emacsname} @value{tramp} package must be
3163 disabled. This can be achieved by setting file permissions @code{000}
3164 to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}.
3166 In case of unified filenames, all @value{emacsname} download sites are
3167 added to @code{tramp-default-method-alist} with default method
3168 @option{ftp} @xref{Default Method}. These settings shouldn't be
3169 touched for proper working of the @value{emacsname} package system.
3171 The syntax for unified filenames is described in the @value{tramp} manual
3172 for @value{emacsothername}.
3176 @node GNU Free Documentation License
3177 @appendix GNU Free Documentation License
3178 @include doclicense.texi
3181 @comment node-name, next, previous, up
3182 @unnumbered Concept Index
3185 @c End of tramp.texi - the TRAMP User Manual
3190 @c * Say something about the .login and .profile files of the remote
3192 @c * Explain how tramp.el works in principle: open a shell on a remote
3193 @c host and then send commands to it.
3194 @c * Make terminology "inline" vs "out-of-band" consistent.
3195 @c It seems that "external" is also used instead of "out-of-band".
3198 @c ** Use `filename' resp. `file name' consistently.
3199 @c ** Use `host' resp. `machine' consistently.
3200 @c ** Consistent small or capitalized words especially in menues.
3203 arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808