1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/tramp
4 @settitle TRAMP User Manual
8 @c This is *so* much nicer :)
11 @c In the Tramp CVS, the version number is auto-frobbed from
12 @c configure.ac, so you should edit that file and run
13 @c "autoconf && ./configure" to change the version number.
15 @c Additionally, flags are set with respect to the Emacs flavor; and
16 @c depending whether Tramp is packaged into (X)Emacs, or standalone.
18 @include trampver.texi
20 @c Macro for formatting a filename according to the repective syntax.
21 @c xxx and yyy are auxiliary macros in order to omit leading and
22 @c trailing whitespace. Not very elegant, but I don't know it better.
28 @macro yyy {one, two}@c
36 @macro trampfn {method, user, host, localname}@c
37 @value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
41 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
42 2006, 2007, 2008 Free Software Foundation, Inc.
45 Permission is granted to copy, distribute and/or modify this document
46 under the terms of the GNU Free Documentation License, Version 1.2 or
47 any later version published by the Free Software Foundation; with no
48 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
49 and with the Back-Cover Texts as in (a) below. A copy of the license
50 is included in the section entitled ``GNU Free Documentation License''.
52 (a) The FSF's Back-Cover Text is: ``You have the freedom to
53 copy and modify this GNU manual. Buying copies from the FSF
54 supports it in developing GNU and promoting software freedom.''
58 @c Entries for @command{install-info} to use
59 @dircategory @value{emacsname}
61 * TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
62 @value{emacsname} remote file access via rsh and rcp.
68 @title @value{tramp} version @value{trampver} User Manual
70 @author by Daniel Pittman
71 @author based on documentation by Kai Gro@ss{}johann
82 @node Top, Overview, (dir), (dir)
83 @top @value{tramp} version @value{trampver} User Manual
85 This file documents @value{tramp} version @value{trampver}, a remote file
86 editing package for @value{emacsname}.
88 @value{tramp} stands for `Transparent Remote (file) Access, Multiple
89 Protocol'. This package provides remote file editing, similar to
90 @value{ftppackagename}.
92 The difference is that @value{ftppackagename} uses FTP to transfer
93 files between the local and the remote host, whereas @value{tramp} uses a
94 combination of @command{rsh} and @command{rcp} or other work-alike
95 programs, such as @command{ssh}/@command{scp}.
97 You can find the latest version of this document on the web at
98 @uref{http://www.gnu.org/software/tramp/}.
100 @c Pointer to the other Emacs flavor is necessary only in case of
101 @c standalone installation.
102 @ifset installchapter
103 The manual has been generated for @value{emacsname}.
105 If you want to read the info pages for @value{emacsothername}, you
106 should read in @ref{Installation} how to create them.
109 If you're using the other Emacs flavor, you should read the
110 @uref{@value{emacsotherfilename}, @value{emacsothername}} pages.
116 This manual is also available as a @uref{@value{japanesemanual},
117 Japanese translation}.
120 The latest release of @value{tramp} is available for
121 @uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
122 @ref{Obtaining Tramp} for more details, including the CVS server
125 @value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/,
126 Savannah Project Page}.
129 There is a mailing list for @value{tramp}, available at
130 @email{tramp-devel@@gnu.org}, and archived at
131 @uref{http://lists.gnu.org/archive/html/tramp-devel/, the
132 @value{tramp} Mail Archive}.
134 Older archives are located at
135 @uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel,
136 SourceForge Mail Archive} and
137 @uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/,
139 @c in HTML output, there's no new paragraph.
148 * Overview:: What @value{tramp} can and cannot do.
152 * Obtaining Tramp:: How to obtain @value{tramp}.
153 * History:: History of @value{tramp}.
154 @ifset installchapter
155 * Installation:: Installing @value{tramp} with your @value{emacsname}.
157 * Configuration:: Configuring @value{tramp} for use.
158 * Usage:: An overview of the operation of @value{tramp}.
159 * Bug Reports:: Reporting Bugs and Problems.
160 * Frequently Asked Questions:: Questions and answers from the mailing list.
161 * Function Index:: @value{tramp} functions.
162 * Variable Index:: User options and variables.
163 * Concept Index:: An item for each concept.
167 * Version Control:: The inner workings of remote version control.
168 * Files directories and localnames:: How file names, directories and localnames are mangled and managed.
169 * Traces and Profiles:: How to Customize Traces.
170 * Issues:: Debatable Issues and What Was Decided.
172 * GNU Free Documentation License:: The license for this documentation.
175 --- The Detailed Node Listing ---
177 @ifset installchapter
178 Installing @value{tramp} with your @value{emacsname}
180 * Installation parameters:: Parameters in order to control installation.
181 * Load paths:: How to plug-in @value{tramp} into your environment.
182 * Japanese manual:: Japanese manual.
186 Configuring @value{tramp} for use
188 * Connection types:: Types of connections made to remote machines.
189 * Inline methods:: Inline methods.
190 * External transfer methods:: External transfer methods.
192 * Gateway methods:: Gateway methods.
194 * Default Method:: Selecting a default method.
195 * Default User:: Selecting a default user.
196 * Default Host:: Selecting a default host.
197 * Multi-hops:: Connecting to a remote host using multiple hops.
198 * Customizing Methods:: Using Non-Standard Methods.
199 * Customizing Completion:: Selecting config files for user/host name completion.
200 * Password handling:: Reusing passwords for several connections.
201 * Connection caching:: Reusing connection related information.
202 * Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
203 * Remote shell setup:: Remote shell setup hints.
204 * Windows setup hints:: Issues with Cygwin ssh.
205 * Auto-save and Backup:: Auto-save and Backup.
209 * Filename Syntax:: @value{tramp} filename conventions.
210 * Alternative Syntax:: URL-like filename syntax.
211 * Filename completion:: Filename completion.
212 * Remote processes:: Integration with other @value{emacsname} packages.
213 * Cleanup remote connections:: Cleanup remote connections.
215 The inner workings of remote version control
217 * Version Controlled Files:: Determining if a file is under version control.
218 * Remote Commands:: Executing the version control commands on the remote machine.
219 * Changed workfiles:: Detecting if the working file has changed.
220 * Checking out files:: Bringing the workfile out of the repository.
221 * Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
223 Things related to Version Control that don't fit elsewhere
225 * Remote File Ownership:: How VC determines who owns a workfile.
226 * Back-end Versions:: How VC determines what release your RCS is.
228 How file names, directories and localnames are mangled and managed
230 * Localname deconstruction:: Breaking a localname into its components.
232 * External packages:: Integration with external Lisp packages.
239 @chapter An overview of @value{tramp}
242 After the installation of @value{tramp} into your @value{emacsname}, you
243 will be able to access files on remote machines as though they were
244 local. Access to the remote file system for editing files, version
245 control, and @code{dired} are transparently enabled.
247 Your access to the remote machine can be with the @command{rsh},
248 @command{rlogin}, @command{telnet} programs or with any similar
249 connection method. This connection must pass @acronym{ASCII}
250 successfully to be usable but need not be 8-bit clean.
252 The package provides support for @command{ssh} connections out of the
253 box, one of the more common uses of the package. This allows
254 relatively secure access to machines, especially if @command{ftp}
257 Under Windows, @value{tramp} is integrated with the PuTTY package,
258 using the @command{plink} program.
260 The majority of activity carried out by @value{tramp} requires only that
261 the remote login is possible and is carried out at the terminal. In
262 order to access remote files @value{tramp} needs to transfer their content
263 to the local machine temporarily.
265 @value{tramp} can transfer files between the machines in a variety of ways.
266 The details are easy to select, depending on your needs and the
267 machines in question.
269 The fastest transfer methods for large files rely on a remote file
270 transfer package such as @command{rcp}, @command{scp}, @command{rsync}
271 or (under Windows) @command{pscp}.
273 If the remote copy methods are not suitable for you, @value{tramp} also
274 supports the use of encoded transfers directly through the shell.
275 This requires that the @command{mimencode} or @command{uuencode} tools
276 are available on the remote machine. These methods are generally
277 faster for small files.
279 @value{tramp} is still under active development and any problems you encounter,
280 trivial or major, should be reported to the @value{tramp} developers.
284 @subsubheading Behind the scenes
285 @cindex behind the scenes
286 @cindex details of operation
289 This section tries to explain what goes on behind the scenes when you
290 access a remote file through @value{tramp}.
292 Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name,
293 then hit @kbd{@key{TAB}} for completion. Suppose further that this is
294 the first time that @value{tramp} is invoked for the host in question. Here's
299 @value{tramp} discovers that it needs a connection to the host. So it
300 invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
301 @var{user}} or a similar tool to connect to the remote host.
302 Communication with this process happens through an
303 @value{emacsname} buffer, that is, the output from the remote end
307 The remote host may prompt for a login name (for @command{telnet}).
308 The login name is given in the file name, so @value{tramp} sends the
309 login name and a newline.
312 The remote host may prompt for a password or pass phrase (for
313 @command{rsh} or for @command{telnet} after sending the login name).
314 @value{tramp} displays the prompt in the minibuffer, asking you for the
315 password or pass phrase.
317 You enter the password or pass phrase. @value{tramp} sends it to the remote
318 host, followed by a newline.
321 @value{tramp} now waits for the shell prompt or for a message that the login
324 If @value{tramp} sees neither of them after a certain period of time
325 (a minute, say), then it issues an error message saying that it
326 couldn't find the remote shell prompt and shows you what the remote
329 If @value{tramp} sees a @samp{login failed} message, it tells you so,
330 aborts the login attempt and allows you to try again.
333 Suppose that the login was successful and @value{tramp} sees the shell prompt
334 from the remote host. Now @value{tramp} invokes @command{/bin/sh} because
335 Bourne shells and C shells have different command
336 syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login
337 shell doesn't recognize @samp{exec /bin/sh} as a valid command.
338 Maybe you use the Scheme shell @command{scsh}@dots{}}
340 After the Bourne shell has come up, @value{tramp} sends a few commands to
341 ensure a good working environment. It turns off echoing, it sets the
342 shell prompt, and a few other things.
345 Now the remote shell is up and it good working order. Remember, what
346 was supposed to happen is that @value{tramp} tries to find out what files exist
347 on the remote host so that it can do filename completion.
349 So, @value{tramp} basically issues @command{cd} and @command{ls} commands and
350 also sometimes @command{echo} with globbing. Another command that is
351 often used is @command{test} to find out whether a file is writable or a
352 directory or the like. The output of each command is parsed for the
356 Suppose you are finished with filename completion, have entered @kbd{C-x
357 C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to
358 transfer the file contents from the remote host to the local host so
359 that you can edit them.
361 See above for an explanation of how @value{tramp} transfers the file contents.
363 For inline transfers, @value{tramp} issues a command like @samp{mimencode -b
364 /path/to/remote/file}, waits until the output has accumulated in the
365 buffer that's used for communication, then decodes that output to
366 produce the file contents.
368 For out-of-band transfers, @value{tramp} issues a command like the following:
370 rcp user@@host:/path/to/remote/file /tmp/tramp.4711
372 It then reads the local temporary file @file{/tmp/tramp.4711} into a
373 buffer and deletes the temporary file.
376 You now edit the buffer contents, blithely unaware of what has happened
377 behind the scenes. (Unless you have read this section, that is.) When
378 you are finished, you type @kbd{C-x C-s} to save the buffer.
381 Again, @value{tramp} transfers the file contents to the remote host either
382 inline or out-of-band. This is the reverse of what happens when reading
386 I hope this has provided you with a basic overview of what happens
387 behind the scenes when you open a file with @value{tramp}.
391 @node Obtaining Tramp
392 @chapter Obtaining Tramp.
393 @cindex obtaining Tramp
395 @value{tramp} is freely available on the Internet and the latest
396 release may be downloaded from
397 @uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
398 documentation and code for @value{tramp}, suitable for installation.
399 But GNU Emacs (22 or later) includes @value{tramp} already, and there
400 is a @value{tramp} package for XEmacs, as well. So maybe it is easier
401 to just use those. But if you want the bleeding edge, read
404 For the especially brave, @value{tramp} is available from CVS. The CVS
405 version is the latest version of the code and may contain incomplete
406 features or new issues. Use these versions at your own risk.
408 Instructions for obtaining the latest development version of @value{tramp}
409 from CVS can be found by going to the Savannah project page at the
410 following URL and then clicking on the CVS link in the navigation bar
414 @uref{http://savannah.gnu.org/projects/tramp/}
417 Or follow the example session below:
420 ] @strong{cd ~/@value{emacsdir}}
421 ] @strong{export CVS_RSH="ssh"}
422 ] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
426 You should now have a directory @file{~/@value{emacsdir}/tramp}
427 containing the latest version of @value{tramp}. You can fetch the latest
428 updates from the repository by issuing the command:
431 ] @strong{cd ~/@value{emacsdir}/tramp}
432 ] @strong{export CVS_RSH="ssh"}
433 ] @strong{cvs update -d}
437 Once you've got updated files from the CVS repository, you need to run
438 @command{autoconf} in order to get an up-to-date @file{configure}
442 ] @strong{cd ~/@value{emacsdir}/tramp}
446 People who have no direct CVS access (maybe because sitting behind a
447 blocking firewall), can try the
448 @uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly
449 CVS Tree Tarball} instead of.
453 @chapter History of @value{tramp}
455 @cindex development history
457 Development was started end of November 1998. The package was called
458 @file{rssh.el}, back then. It only provided one method to access a
459 file, using @command{ssh} to log in to a remote host and using
460 @command{scp} to transfer the file contents. After a while, the name
461 was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way,
462 many more methods for getting a remote shell and for transferring the
463 file contents were added. Support for VC was added.
465 The most recent addition of major features were the multi-hop methods
466 added in April 2000 and the unification of @value{tramp} and Ange-FTP
467 filenames in July 2002. In July 2004, multi-hop methods have been
468 replaced by proxy hosts. Running commands on remote hosts was
469 introduced in December 2005.
471 Support of gateways exists since April 2007.
474 In December 2001, @value{tramp} has been added to the XEmacs package
475 repository. Being part of the GNU Emacs repository happened in June
476 2002, the first release including @value{tramp} was GNU Emacs 22.1.
478 @value{tramp} is also a GNU/Linux Debian package since February 2001.
481 @c Installation chapter is necessary only in case of standalone
482 @c installation. Text taken from trampinst.texi.
483 @ifset installchapter
484 @include trampinst.texi
488 @chapter Configuring @value{tramp} for use
489 @cindex configuration
491 @cindex default configuration
492 @value{tramp} is (normally) fully functional when it is initially
493 installed. It is initially configured to use the @command{scp}
494 program to connect to the remote host. So in the easiest case, you
495 just type @kbd{C-x C-f} and then enter the filename
496 @file{@trampfn{, user, machine, /path/to.file}}.
498 On some hosts, there are problems with opening a connection. These are
499 related to the behavior of the remote shell. See @xref{Remote shell
500 setup}, for details on this.
502 If you do not wish to use these commands to connect to the remote
503 host, you should change the default connection and transfer method
504 that @value{tramp} uses. There are several different methods that @value{tramp}
505 can use to connect to remote machines and transfer files
506 (@pxref{Connection types}).
508 If you don't know which method is right for you, see @xref{Default
513 * Connection types:: Types of connections made to remote machines.
514 * Inline methods:: Inline methods.
515 * External transfer methods:: External transfer methods.
517 * Gateway methods:: Gateway methods.
519 * Default Method:: Selecting a default method.
520 Here we also try to help those who
521 don't have the foggiest which method
523 * Default User:: Selecting a default user.
524 * Default Host:: Selecting a default host.
525 * Multi-hops:: Connecting to a remote host using multiple hops.
526 * Customizing Methods:: Using Non-Standard Methods.
527 * Customizing Completion:: Selecting config files for user/host name completion.
528 * Password handling:: Reusing passwords for several connections.
529 * Connection caching:: Reusing connection related information.
530 * Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
531 * Remote shell setup:: Remote shell setup hints.
532 * Windows setup hints:: Issues with Cygwin ssh.
533 * Auto-save and Backup:: Auto-save and Backup.
537 @node Connection types
538 @section Types of connections made to remote machines.
539 @cindex connection types, overview
541 There are two basic types of transfer methods, each with its own
542 advantages and limitations. Both types of connection make use of a
543 remote shell access program such as @command{rsh}, @command{ssh} or
544 @command{telnet} to connect to the remote machine.
546 This connection is used to perform many of the operations that @value{tramp}
547 requires to make the remote file system transparently accessible from
548 the local machine. It is only when visiting files that the methods
551 @cindex inline methods
552 @cindex external transfer methods
553 @cindex external methods
554 @cindex out-of-band methods
555 @cindex methods, inline
556 @cindex methods, external transfer
557 @cindex methods, out-of-band
558 Loading or saving a remote file requires that the content of the file
559 be transfered between the two machines. The content of the file can be
560 transfered over the same connection used to log in to the remote
561 machine or the file can be transfered through another connection using
562 a remote copy program such as @command{rcp}, @command{scp} or
563 @command{rsync}. The former are called @dfn{inline methods}, the
564 latter are called @dfn{out-of-band methods} or @dfn{external transfer
565 methods} (@dfn{external methods} for short).
567 The performance of the external transfer methods is generally better
568 than that of the inline methods, at least for large files. This is
569 caused by the need to encode and decode the data when transferring
572 The one exception to this rule are the @command{scp} based transfer
573 methods. While these methods do see better performance when actually
574 transferring files, the overhead of the cryptographic negotiation at
575 startup may drown out the improvement in file transfer times.
577 External transfer methods should be configured such a way that they
578 don't require a password (with @command{ssh-agent}, or such alike).
579 Modern @command{scp} implementations offer options to reuse existing
580 @command{ssh} connections, see method @command{scpc}. If it isn't
581 possible, you should consider @ref{Password handling}, otherwise you
582 will be prompted for a password every copy action.
586 @section Inline methods
587 @cindex inline methods
588 @cindex methods, inline
590 The inline methods in @value{tramp} are quite powerful and can work in
591 situations where you cannot use an external transfer program to connect.
592 Inline methods are the only methods that work when connecting to the
593 remote machine via telnet. (There are also strange inline methods which
594 allow you to transfer files between @emph{user identities} rather than
597 These methods depend on the existence of a suitable encoding and
598 decoding command on remote machine. Locally, @value{tramp} may be able to
599 use features of @value{emacsname} to decode and encode the files or
600 it may require access to external commands to perform that task.
604 @cindex base-64 encoding
605 @value{tramp} checks the availability and usability of commands like
606 @command{mimencode} (part of the @command{metamail} package) or
607 @command{uuencode} on the remote host. The first reliable command
608 will be used. The search path can be customized, see @ref{Remote
611 If both commands aren't available on the remote host, @value{tramp}
612 transfers a small piece of Perl code to the remote host, and tries to
613 apply it for encoding and decoding.
621 Connect to the remote host with @command{rsh}. Due to the unsecure
622 connection it is recommended for very local host topology only.
624 On operating systems which provide the command @command{remsh} instead
625 of @command{rsh}, you can use the method @option{remsh}. This is true
626 for HP-UX or Cray UNICOS, for example.
633 Connect to the remote host with @command{ssh}. This is identical to
634 the previous option except that the @command{ssh} package is used,
635 making the connection more secure.
637 There are also two variants, @option{ssh1} and @option{ssh2}, that
638 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
639 explicitly select whether you want to use the SSH protocol version 1
640 or 2 to connect to the remote host. (You can also specify in
641 @file{~/.ssh/config}, the SSH configuration file, which protocol
642 should be used, and use the regular @option{ssh} method.)
644 Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
645 @command{ssh1} and @command{ssh2} commands explicitly. If you don't
646 know what these are, you do not need these options.
648 All the methods based on @command{ssh} have an additional kludgy
649 feature: you can specify a host name which looks like @file{host#42}
650 (the real host name, then a hash sign, then a port number). This
651 means to connect to the given host but to also pass @code{-p 42} as
652 arguments to the @command{ssh} command.
655 @item @option{telnet}
656 @cindex method telnet
657 @cindex telnet method
659 Connect to the remote host with @command{telnet}. This is as unsecure
660 as the @option{rsh} method.
667 This method does not connect to a remote host at all, rather it uses
668 the @command{su} program to allow you to edit files as another user.
669 That means, the specified host name in the file name must be either
670 @samp{localhost} or the host name as returned by the function
671 @command{(system-name)}. For an exception of this rule see
679 This is similar to the @option{su} method, but it uses @command{sudo}
680 rather than @command{su} to become a different user.
682 Note that @command{sudo} must be configured to allow you to start a
683 shell as the user. It would be nice if it was sufficient if
684 @command{ls} and @command{mimencode} were allowed, but that is not
685 easy to implement, so I haven't got around to it, yet.
692 As you would expect, this is similar to @option{ssh}, only a little
693 different. Whereas @option{ssh} opens a normal interactive shell on
694 the remote host, this option uses @samp{ssh -t -t @var{host} -l
695 @var{user} /bin/sh} to open a connection. This is useful for users
696 where the normal login shell is set up to ask them a number of
697 questions when logging in. This procedure avoids these questions, and
698 just gives @value{tramp} a more-or-less `standard' login shell to work
701 Note that this procedure does not eliminate questions asked by
702 @command{ssh} itself. For example, @command{ssh} might ask ``Are you
703 sure you want to continue connecting?'' if the host key of the remote
704 host is not known. @value{tramp} does not know how to deal with such a
705 question (yet), therefore you will need to make sure that you can log
706 in without such questions.
708 This is also useful for Windows users where @command{ssh}, when
709 invoked from an @value{emacsname} buffer, tells them that it is not
710 allocating a pseudo tty. When this happens, the login shell is wont
711 to not print any shell prompt, which confuses @value{tramp} mightily.
712 For reasons unknown, some Windows ports for @command{ssh} require the
713 doubled @samp{-t} option.
715 This supports the @samp{-p} kludge.
718 @item @option{krlogin}
719 @cindex method krlogin
720 @cindex krlogin method
721 @cindex Kerberos (with krlogin method)
723 This method is also similar to @option{ssh}. It only uses the
724 @command{krlogin -x} command to log in to the remote host.
731 This method is mostly interesting for Windows users using the PuTTY
732 implementation of SSH. It uses @samp{plink -ssh} to log in to the
735 This supports the @samp{-P} kludge.
737 Additionally, the methods @option{plink1} and @option{plink2} are
738 provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in
739 order to use SSH protocol version 1 or 2 explicitly.
741 CCC: Do we have to connect to the remote host once from the command
742 line to accept the SSH key? Maybe this can be made automatic?
744 CCC: Say something about the first shell command failing. This might
745 be due to a wrong setting of @code{tramp-rsh-end-of-line}.
748 @item @option{plinkx}
749 @cindex method plinkx
750 @cindex plinkx method
752 Another method using PuTTY on Windows. Instead of host names, it
753 expects PuTTY session names, calling @samp{plink -load @var{session}
754 -t"}. User names are relevant only in case the corresponding session
755 hasn't defined a user name. Different port numbers must be defined in
763 This is an experimental implementation of the fish protocol, known from
764 the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
765 the fish server implementation from the KDE kioslave. That means, the
766 file @file{~/.fishsrv.pl} is expected to reside on the remote host.
768 The implementation lacks good performance. The code is offered anyway,
769 maybe somebody can improve the performance.
774 @node External transfer methods
775 @section External transfer methods
776 @cindex methods, external transfer
777 @cindex methods, out-of-band
778 @cindex external transfer methods
779 @cindex out-of-band methods
781 The external transfer methods operate through multiple channels, using
782 the remote shell connection for many actions while delegating file
783 transfers to an external transfer utility.
785 This saves the overhead of encoding and decoding that multiplexing the
786 transfer through the one connection has with the inline methods.
788 Since external transfer methods need their own overhead opening a new
789 channel, all files which are smaller than @var{tramp-copy-size-limit}
790 are still transferred with the corresponding inline method. It should
791 provide a fair trade-off between both approaches.
794 @item @option{rcp} --- @command{rsh} and @command{rcp}
797 @cindex rcp (with rcp method)
798 @cindex rsh (with rcp method)
800 This method uses the @command{rsh} and @command{rcp} commands to connect
801 to the remote machine and transfer files. This is probably the fastest
802 connection method available.
804 The alternative method @option{remcp} uses the @command{remsh} and
805 @command{rcp} commands. It should be applied on machines where
806 @command{remsh} is used instead of @command{rsh}.
809 @item @option{scp} --- @command{ssh} and @command{scp}
812 @cindex scp (with scp method)
813 @cindex ssh (with scp method)
815 Using @command{ssh} to connect to the remote host and @command{scp} to
816 transfer files between the machines is the best method for securely
817 connecting to a remote machine and accessing files.
819 The performance of this option is also quite good. It may be slower than
820 the inline methods when you often open and close small files however.
821 The cost of the cryptographic handshake at the start of an @command{scp}
822 session can begin to absorb the advantage that the lack of encoding and
825 There are also two variants, @option{scp1} and @option{scp2}, that
826 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
827 explicitly select whether you want to use the SSH protocol version 1
828 or 2 to connect to the remote host. (You can also specify in
829 @file{~/.ssh/config}, the SSH configuration file, which protocol
830 should be used, and use the regular @option{scp} method.)
832 Two other variants, @option{scp1_old} and @option{scp2_old}, use the
833 @command{ssh1} and @command{ssh2} commands explicitly. If you don't
834 know what these are, you do not need these options.
836 All the @command{ssh} based methods support the kludgy @samp{-p}
837 feature where you can specify a port number to connect to in the host
838 name. For example, the host name @file{host#42} tells @value{tramp} to
839 specify @samp{-p 42} in the argument list for @command{ssh}, and to
840 specify @samp{-P 42} in the argument list for @command{scp}.
843 @item @option{sftp} --- @command{ssh} and @command{sftp}
846 @cindex sftp (with sftp method)
847 @cindex ssh (with sftp method)
849 That is mostly the same method as @option{scp}, but using
850 @command{sftp} as transfer command. So the same remarks are valid.
852 This command does not work like @value{ftppackagename}, where
853 @command{ftp} is called interactively, and all commands are send from
854 within this session. Instead of, @command{ssh} is used for login.
856 This method supports the @samp{-p} hack.
859 @item @option{rsync} --- @command{ssh} and @command{rsync}
862 @cindex rsync (with rsync method)
863 @cindex ssh (with rsync method)
865 Using the @command{ssh} command to connect securely to the remote
866 machine and the @command{rsync} command to transfer files is almost
867 identical to the @option{scp} method.
869 While @command{rsync} performs much better than @command{scp} when
870 transferring files that exist on both hosts, this advantage is lost if
871 the file exists only on one side of the connection.
873 The @command{rsync} based method may be considerably faster than the
874 @command{rcp} based methods when writing to the remote system. Reading
875 files to the local machine is no faster than with a direct copy.
877 This method supports the @samp{-p} hack.
880 @item @option{scpx} --- @command{ssh} and @command{scp}
883 @cindex scp (with scpx method)
884 @cindex ssh (with scpx method)
886 As you would expect, this is similar to @option{scp}, only a little
887 different. Whereas @option{scp} opens a normal interactive shell on
888 the remote host, this option uses @samp{ssh -t -t @var{host} -l
889 @var{user} /bin/sh} to open a connection. This is useful for users
890 where the normal login shell is set up to ask them a number of
891 questions when logging in. This procedure avoids these questions, and
892 just gives @value{tramp} a more-or-less `standard' login shell to work
895 This is also useful for Windows users where @command{ssh}, when
896 invoked from an @value{emacsname} buffer, tells them that it is not
897 allocating a pseudo tty. When this happens, the login shell is wont
898 to not print any shell prompt, which confuses @value{tramp} mightily.
900 This method supports the @samp{-p} hack.
903 @item @option{scpc} --- @command{ssh} and @command{scp}
906 @cindex scp (with scpx method)
907 @cindex ssh (with scpx method)
909 Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
910 @option{ControlMaster}. This allows @option{scp} to reuse an existing
911 @option{ssh} channel, which increases performance.
913 Before you use this method, you shall check whether your @option{ssh}
914 implementation does support this option. Try from the command line
917 ssh localhost -o ControlMaster=yes
920 This method supports the @samp{-p} hack.
923 @item @option{pscp} --- @command{plink} and @command{pscp}
926 @cindex pscp (with pscp method)
927 @cindex plink (with pscp method)
928 @cindex PuTTY (with pscp method)
930 This method is similar to @option{scp}, but it uses the
931 @command{plink} command to connect to the remote host, and it uses
932 @command{pscp} for transferring the files. These programs are part
933 of PuTTY, an SSH implementation for Windows.
935 This method supports the @samp{-P} hack.
938 @item @option{psftp} --- @command{plink} and @command{psftp}
941 @cindex psftp (with psftp method)
942 @cindex plink (with psftp method)
943 @cindex PuTTY (with psftp method)
945 As you would expect, this method is similar to @option{sftp}, but it
946 uses the @command{plink} command to connect to the remote host, and it
947 uses @command{psftp} for transferring the files. These programs are
948 part of PuTTY, an SSH implementation for Windows.
950 This method supports the @samp{-P} hack.
953 @item @option{fcp} --- @command{fsh} and @command{fcp}
956 @cindex fsh (with fcp method)
957 @cindex fcp (with fcp method)
959 This method is similar to @option{scp}, but it uses the @command{fsh}
960 command to connect to the remote host, and it uses @command{fcp} for
961 transferring the files. @command{fsh/fcp} are a front-end for
962 @command{ssh} which allow for reusing the same @command{ssh} session
963 for submitting several commands. This avoids the startup overhead of
964 @command{scp} (which has to establish a secure connection whenever it
965 is called). Note, however, that you can also use one of the inline
966 methods to achieve a similar effect.
968 This method uses the command @samp{fsh @var{host} -l @var{user}
969 /bin/sh -i} to establish the connection, it does not work to just say
970 @command{fsh @var{host} -l @var{user}}.
975 There is no inline method using @command{fsh} as the multiplexing
976 provided by the program is not very useful in our context. @value{tramp}
977 opens just one connection to the remote host and then keeps it open,
985 This is not a native @value{tramp} method. Instead of, it forwards all
986 requests to @value{ftppackagename}.
988 This works only for unified filenames, see @ref{Issues}.
992 @item @option{smb} --- @command{smbclient}
996 This is another not natural @value{tramp} method. It uses the
997 @command{smbclient} command on different Unices in order to connect to
998 an SMB server. An SMB server might be a Samba (or CIFS) server on
999 another UNIX host or, more interesting, a host running MS Windows. So
1000 far, it is tested towards MS Windows NT, MS Windows 2000, and MS
1003 The first directory in the localname must be a share name on the remote
1004 host. Remember, that the @code{$} character in which default shares
1005 usually end, must be written @code{$$} due to environment variable
1006 substitution in file names. If no share name is given (i.e. remote
1007 directory @code{/}), all available shares are listed.
1009 Since authorization is done on share level, you will be prompted
1010 always for a password if you access another share on the same host.
1011 This can be suppressed by @ref{Password handling}.
1013 MS Windows uses for authorization both a user name and a domain name.
1014 Because of this, the @value{tramp} syntax has been extended: you can
1015 specify a user name which looks like @code{user%domain} (the real user
1016 name, then a percent sign, then the domain name). So, to connect to
1017 the machine @code{melancholia} as user @code{daniel} of the domain
1018 @code{BIZARRE}, and edit @file{.emacs} in the home directory (share
1019 @code{daniel$}) I would specify the filename @file{@trampfn{smb,
1020 daniel%BIZARRE, melancholia, /daniel$$/.emacs}}.
1022 Depending on the Windows domain configuration, a Windows user might be
1023 considered as domain user per default. In order to connect as local
1024 user, the WINS name of that machine must be given as domain name.
1025 Usually, it is the machine name in capital letters. In the example
1026 above, the local user @code{daniel} would be specified as
1027 @file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}.
1029 The domain name as well as the user name are optional. If no user
1030 name is specified at all, the anonymous user (without password
1031 prompting) is assumed. This is different from all other @value{tramp}
1032 methods, where in such a case the local user name is taken.
1034 The @option{smb} method supports the @samp{-p} hack.
1036 @strong{Please note:} If @value{emacsname} runs locally under MS
1037 Windows, this method isn't available. Instead of, you can use UNC
1038 file names like @file{//melancholia/daniel$$/.emacs}. The only
1039 disadvantage is that there's no possibility to specify another user
1046 @node Gateway methods
1047 @section Gateway methods
1048 @cindex methods, gateway
1049 @cindex gateway methods
1051 Gateway methods are not methods to access a remote host directly.
1052 These methods are intended to pass firewalls or proxy servers.
1053 Therefore, they can be used for proxy host declarations
1054 (@pxref{Multi-hops}) only.
1056 A gateway method must come always along with a method who supports
1057 port setting (referred to as @samp{-p} kludge). This is because
1058 @value{tramp} targets the accompanied method to
1059 @file{localhost#random_port}, from where the firewall or proxy server
1062 Gateway methods support user name and password declarations. These
1063 are used to authenticate towards the corresponding firewall or proxy
1064 server. They can be passed only if your friendly administrator has
1065 granted your access.
1068 @item @option{tunnel}
1069 @cindex method tunnel
1070 @cindex tunnel method
1072 This method implements an HTTP tunnel via the @command{CONNECT}
1073 command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server
1074 shall support this command.
1076 As authentication method, only @option{Basic Authentication} (see RFC
1077 2617) is implemented so far. If no port number is given in the
1078 declaration, port @option{8080} is used for the proxy server.
1081 @item @option{socks}
1082 @cindex method socks
1083 @cindex socks method
1085 The @command{socks} method provides access to SOCKSv5 servers (see
1086 RFC 1928). @option{Username/Password Authentication} according to RFC
1089 The default port number of the socks server is @option{1080}, if not
1090 specified otherwise.
1096 @node Default Method
1097 @section Selecting a default method
1098 @cindex default method
1100 @vindex tramp-default-method
1101 When you select an appropriate transfer method for your typical usage
1102 you should set the variable @code{tramp-default-method} to reflect that
1103 choice. This variable controls which method will be used when a method
1104 is not specified in the @value{tramp} file name. For example:
1107 (setq tramp-default-method "ssh")
1110 @vindex tramp-default-method-alist
1111 You can also specify different methods for certain user/host
1112 combinations, via the variable @code{tramp-default-method-alist}. For
1113 example, the following two lines specify to use the @option{ssh}
1114 method for all user names matching @samp{john} and the @option{rsync}
1115 method for all host names matching @samp{lily}. The third line
1116 specifies to use the @option{su} method for the user @samp{root} on
1117 the machine @samp{localhost}.
1120 (add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
1121 (add-to-list 'tramp-default-method-alist '("lily" "" "rsync"))
1122 (add-to-list 'tramp-default-method-alist
1123 '("\\`localhost\\'" "\\`root\\'" "su"))
1127 See the documentation for the variable
1128 @code{tramp-default-method-alist} for more details.
1130 External transfer methods are normally preferable to inline transfer
1131 methods, giving better performance.
1133 @xref{Inline methods}.
1134 @xref{External transfer methods}.
1136 Another consideration with the selection of transfer methods is the
1137 environment you will use them in and, especially when used over the
1138 Internet, the security implications of your preferred method.
1140 The @option{rsh} and @option{telnet} methods send your password as
1141 plain text as you log in to the remote machine, as well as
1142 transferring the files in such a way that the content can easily be
1143 read from other machines.
1145 If you need to connect to remote systems that are accessible from the
1146 Internet, you should give serious thought to using @option{ssh} based
1147 methods to connect. These provide a much higher level of security,
1148 making it a non-trivial exercise for someone to obtain your password
1149 or read the content of the files you are editing.
1152 @subsection Which method is the right one for me?
1153 @cindex choosing the right method
1155 Given all of the above, you are probably thinking that this is all fine
1156 and good, but it's not helping you to choose a method! Right you are.
1157 As a developer, we don't want to boss our users around but give them
1158 maximum freedom instead. However, the reality is that some users would
1159 like to have some guidance, so here I'll try to give you this guidance
1160 without bossing you around. You tell me whether it works @dots{}
1162 My suggestion is to use an inline method. For large files, out-of-band
1163 methods might be more efficient, but I guess that most people will want
1164 to edit mostly small files.
1166 I guess that these days, most people can access a remote machine by
1167 using @command{ssh}. So I suggest that you use the @option{ssh}
1168 method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost,
1169 /etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other
1172 If you can't use @option{ssh} to log in to the remote host, then
1173 select a method that uses a program that works. For instance, Windows
1174 users might like the @option{plink} method which uses the PuTTY
1175 implementation of @command{ssh}. Or you use Kerberos and thus like
1178 For the special case of editing files on the local host as another
1179 user, see the @option{su} or @option{sudo} methods. They offer
1180 shortened syntax for the @samp{root} account, like
1181 @file{@trampfn{su, , , /etc/motd}}.
1183 People who edit large files may want to consider @option{scpc} instead
1184 of @option{ssh}, or @option{pscp} instead of @option{plink}. These
1185 out-of-band methods are faster than inline methods for large files.
1186 Note, however, that out-of-band methods suffer from some limitations.
1187 Please try first whether you really get a noticeable speed advantage
1188 from using an out-of-band method! Maybe even for large files, inline
1189 methods are fast enough.
1193 @section Selecting a default user
1194 @cindex default user
1196 The user part of a @value{tramp} file name can be omitted. Usually,
1197 it is replaced by the user name you are logged in. Often, this is not
1198 what you want. A typical use of @value{tramp} might be to edit some
1199 files with root permissions on the local host. This case, you should
1200 set the variable @code{tramp-default-user} to reflect that choice.
1204 (setq tramp-default-user "root")
1207 @code{tramp-default-user} is regarded as obsolete, and will be removed
1210 @vindex tramp-default-user-alist
1211 You can also specify different users for certain method/host
1212 combinations, via the variable @code{tramp-default-user-alist}. For
1213 example, if you always have to use the user @samp{john} in the domain
1214 @samp{somewhere.else}, you can specify the following:
1217 (add-to-list 'tramp-default-user-alist
1218 '("ssh" ".*\\.somewhere\\.else\\'" "john"))
1222 See the documentation for the variable
1223 @code{tramp-default-user-alist} for more details.
1225 One trap to fall in must be known. If @value{tramp} finds a default
1226 user, this user will be passed always to the connection command as
1227 parameter (for example @samp{ssh here.somewhere.else -l john}. If you
1228 have specified another user for your command in its configuration
1229 files, @value{tramp} cannot know it, and the remote access will fail.
1230 If you have specified in the given example in @file{~/.ssh/config} the
1234 Host here.somewhere.else
1239 than you must discard selecting a default user by @value{tramp}. This
1240 will be done by setting it to @code{nil} (or @samp{lily}, likewise):
1243 (add-to-list 'tramp-default-user-alist
1244 '("ssh" "\\`here\\.somewhere\\.else\\'" nil))
1247 The last entry in @code{tramp-default-user-alist} could be your
1248 default user you'll apply predominantly. You shall @emph{append} it
1249 to that list at the end:
1252 (add-to-list 'tramp-default-user-alist '(nil nil "jonas") t)
1257 @section Selecting a default host
1258 @cindex default host
1260 @vindex tramp-default-host
1261 Finally, it is even possible to omit the host name part of a
1262 @value{tramp} file name. This case, the value of the variable
1263 @code{tramp-default-host} is used. Per default, it is initialized
1264 with the host name your local @value{emacsname} is running.
1266 If you, for example, use @value{tramp} mainly to contact the host
1267 @samp{target} as user @samp{john}, you can specify:
1270 (setq tramp-default-user "john"
1271 tramp-default-host "target")
1274 Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you
1275 to John's home directory on target.
1277 Note, however, that the most simplification @samp{/::} won't work,
1278 because @samp{/:} is the prefix for quoted file names.
1283 @section Connecting to a remote host using multiple hops
1287 Sometimes, the methods described before are not sufficient. Sometimes,
1288 it is not possible to connect to a remote host using a simple command.
1289 For example, if you are in a secured network, you might have to log in
1290 to a `bastion host' first before you can connect to the outside world.
1291 Of course, the target host may also require a bastion host.
1293 @vindex tramp-default-proxies-alist
1294 In order to specify such multiple hops, it is possible to define a proxy
1295 host to pass through, via the variable
1296 @code{tramp-default-proxies-alist}. This variable keeps a list of
1297 triples (@var{host} @var{user} @var{proxy}).
1299 The first matching item specifies the proxy host to be passed for a
1300 file name located on a remote target matching @var{user}@@@var{host}.
1301 @var{host} and @var{user} are regular expressions or @code{nil}, which
1302 is interpreted as a regular expression which always matches.
1304 @var{proxy} must be a Tramp filename which localname part is ignored.
1305 Method and user name on @var{proxy} are optional, which is interpreted
1306 with the default values.
1308 The method must be an inline or gateway method (@pxref{Inline
1309 methods}, @pxref{Gateway methods}).
1312 The method must be an inline method (@pxref{Inline methods}).
1314 If @var{proxy} is @code{nil}, no additional hop is required reaching
1315 @var{user}@@@var{host}.
1317 If you, for example, must pass the host @samp{bastion.your.domain} as
1318 user @samp{bird} for any remote host which is not located in your local
1322 (add-to-list 'tramp-default-proxies-alist
1323 '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}"))
1324 (add-to-list 'tramp-default-proxies-alist
1325 '("\\.your\\.domain\\'" nil nil))
1328 Please note the order of the code. @code{add-to-list} adds elements at the
1329 beginning of a list. Therefore, most relevant rules must be added last.
1331 Proxy hosts can be cascaded. If there is another host called
1332 @samp{jump.your.domain}, which is the only one in your local domain who
1333 is allowed connecting @samp{bastion.your.domain}, you can add another
1337 (add-to-list 'tramp-default-proxies-alist
1338 '("\\`bastion\\.your\\.domain\\'"
1340 "@trampfn{ssh, , jump.your.domain,}"))
1343 @var{proxy} can contain the patterns @code{%h} or @code{%u}. These
1344 patterns are replaced by the strings matching @var{host} or
1345 @var{user}, respectively.
1347 If you, for example, wants to work as @samp{root} on hosts in the
1348 domain @samp{your.domain}, but login as @samp{root} is disabled for
1349 non-local access, you might add the following rule:
1352 (add-to-list 'tramp-default-proxies-alist
1353 '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
1356 Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect
1357 first @samp{randomhost.your.domain} via @code{ssh} under your account
1358 name, and perform @code{sudo -u root} on that host afterwards. It is
1359 important to know that the given method is applied on the host which
1360 has been reached so far. @code{sudo -u root}, applied on your local
1361 host, wouldn't be useful here.
1363 This is the recommended configuration to work as @samp{root} on remote
1367 Finally, @code{tramp-default-proxies-alist} can be used to pass
1368 firewalls or proxy servers. Imagine your local network has a host
1369 @samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to
1370 the outer world. Your friendly administrator has granted you access
1371 under your user name to @samp{host.other.domain} on that proxy
1372 server.@footnote{HTTP tunnels are intended for secure SSL/TLS
1373 communication. Therefore, many proxy server restrict the tunnels to
1374 related target ports. You might need to run your ssh server on your
1375 target host @samp{host.other.domain} on such a port, like 443 (https).
1376 See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall}
1377 for discussion of ethical issues.} You would need to add the
1381 (add-to-list 'tramp-default-proxies-alist
1382 '("\\`host\\.other\\.domain\\'" nil
1383 "@trampfn{tunnel, , proxy.your.domain#3128,}"))
1386 Gateway methods can be declared as first hop only in a multiple hop
1391 @node Customizing Methods
1392 @section Using Non-Standard Methods
1393 @cindex customizing methods
1394 @cindex using non-standard methods
1395 @cindex create your own methods
1397 There is a variable @code{tramp-methods} which you can change if the
1398 predefined methods don't seem right.
1400 For the time being, I'll refer you to the Lisp documentation of that
1401 variable, accessible with @kbd{C-h v tramp-methods @key{RET}}.
1404 @node Customizing Completion
1405 @section Selecting config files for user/host name completion
1406 @cindex customizing completion
1407 @cindex selecting config files
1408 @vindex tramp-completion-function-alist
1410 The variable @code{tramp-completion-function-alist} is intended to
1411 customize which files are taken into account for user and host name
1412 completion (@pxref{Filename completion}). For every method, it keeps
1413 a set of configuration files, accompanied by a Lisp function able to
1414 parse that file. Entries in @code{tramp-completion-function-alist}
1415 have the form (@var{method} @var{pair1} @var{pair2} ...).
1417 Each @var{pair} is composed of (@var{function} @var{file}).
1418 @var{function} is responsible to extract user names and host names
1419 from @var{file} for completion. There are two functions which access
1422 @defun tramp-get-completion-function method
1423 This function returns the list of completion functions for @var{method}.
1427 (tramp-get-completion-function "rsh")
1429 @result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
1430 (tramp-parse-rhosts "~/.rhosts"))
1434 @defun tramp-set-completion-function method function-list
1435 This function sets @var{function-list} as list of completion functions
1440 (tramp-set-completion-function "ssh"
1441 '((tramp-parse-sconfig "/etc/ssh_config")
1442 (tramp-parse-sconfig "~/.ssh/config")))
1444 @result{} ((tramp-parse-sconfig "/etc/ssh_config")
1445 (tramp-parse-sconfig "~/.ssh/config"))
1449 The following predefined functions parsing configuration files exist:
1452 @item @code{tramp-parse-rhosts}
1453 @findex tramp-parse-rhosts
1455 This function parses files which are syntactical equivalent to
1456 @file{~/.rhosts}. It returns both host names and user names, if
1459 @item @code{tramp-parse-shosts}
1460 @findex tramp-parse-shosts
1462 This function parses files which are syntactical equivalent to
1463 @file{~/.ssh/known_hosts}. Since there are no user names specified
1464 in such files, it can return host names only.
1466 @item @code{tramp-parse-sconfig}
1467 @findex tramp-parse-shosts
1469 This function returns the host nicknames defined by @code{Host} entries
1470 in @file{~/.ssh/config} style files.
1472 @item @code{tramp-parse-shostkeys}
1473 @findex tramp-parse-shostkeys
1475 SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and
1476 @file{~/ssh2/hostkeys/*}. Hosts are coded in file names
1477 @file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names
1478 are always @code{nil}.
1480 @item @code{tramp-parse-sknownhosts}
1481 @findex tramp-parse-shostkeys
1483 Another SSH2 style parsing of directories like
1484 @file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This
1485 case, hosts names are coded in file names
1486 @file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}.
1488 @item @code{tramp-parse-hosts}
1489 @findex tramp-parse-hosts
1491 A function dedicated to @file{/etc/hosts} style files. It returns
1494 @item @code{tramp-parse-passwd}
1495 @findex tramp-parse-passwd
1497 A function which parses @file{/etc/passwd} like files. Obviously, it
1498 can return user names only.
1500 @item @code{tramp-parse-netrc}
1501 @findex tramp-parse-netrc
1503 Finally, a function which parses @file{~/.netrc} like files.
1506 If you want to keep your own data in a file, with your own structure,
1507 you might provide such a function as well. This function must meet
1508 the following conventions:
1510 @defun my-tramp-parse file
1511 @var{file} must be either a file name on your host, or @code{nil}.
1512 The function must return a list of (@var{user} @var{host}), which are
1513 taken as candidates for user and host name completion.
1517 (my-tramp-parse "~/.my-tramp-hosts")
1519 @result{} ((nil "toto") ("daniel" "melancholia"))
1524 @node Password handling
1525 @section Reusing passwords for several connections.
1528 Sometimes it is necessary to connect to the same remote host several
1529 times. Reentering passwords again and again would be annoying, when
1530 the chosen method does not support access without password prompt
1531 through own configuration.
1533 The best recommendation is to use the method's own mechanism for
1534 password handling. Consider @command{ssh-agent} for @option{ssh}-like
1535 methods, or @command{pageant} for @option{plink}-like methods.
1537 However, if you cannot apply such native password handling,
1538 @value{tramp} offers altenatives.
1541 @anchor{auth-sources}
1542 @subsection Using an authentication file
1544 @vindex auth-sources
1545 The package @file{auth-source.el}, originally developed in No Gnus,
1546 offers the possibility to read passwords from a file, like FTP does it
1547 from @file{~/.netrc}. The default authentication file is
1548 @file{~/.authinfo.gpg}, this can be changed via the variable
1549 @code{auth-sources}.
1552 A typical entry in the authentication file would be
1555 machine melancholia port scp login daniel password geheim
1558 The port can be any @value{tramp} method (@pxref{Inline methods},
1559 @pxref{External transfer methods}), to match only this method. When
1560 you omit the port, you match all @value{tramp} methods.
1563 @anchor{password-cache}
1564 @subsection Caching passwords
1566 If there is no authentication file, @value{tramp} caches the passwords
1567 entered by you. They will be reused next time if a connection needs
1568 them for the same user name and host name, independently of the
1571 @vindex password-cache-expiry
1572 Passwords are not saved permanently, that means the password caching
1573 is limited to the lifetime of your @value{emacsname} session. You
1574 can influence the lifetime of password caching by customizing the
1575 variable @code{password-cache-expiry}. The value is the number of
1576 seconds how long passwords are cached. Setting it to @code{nil}
1577 disables the expiration.
1579 @vindex password-cache
1580 If you don't like this feature for security reasons, password caching
1581 can be disabled totally by customizing the variable
1582 @code{password-cache} (setting it to @code{nil}).
1584 Implementation Note: password caching is based on the package
1585 @file{password-cache.el}. For the time being, it is activated only
1586 when this package is seen in the @code{load-path} while loading
1588 @ifset installchapter
1589 If you don't use No Gnus, you can take @file{password.el} from the
1590 @value{tramp} @file{contrib} directory, see @ref{Installation
1595 @node Connection caching
1596 @section Reusing connection related information.
1599 @vindex tramp-persistency-file-name
1600 In order to reduce initial connection time, @value{tramp} stores
1601 connection related information persistently. The variable
1602 @code{tramp-persistency-file-name} keeps the file name where these
1603 information are written. Its default value is
1605 @file{~/.emacs.d/tramp}.
1608 @file{~/.xemacs/tramp}.
1610 It is recommended to choose a local file name.
1612 @value{tramp} reads this file during startup, and writes it when
1613 exiting @value{emacsname}. You can simply remove this file if
1614 @value{tramp} shall be urged to recompute these information next
1615 @value{emacsname} startup time.
1617 Using such persistent information can be disabled by setting
1618 @code{tramp-persistency-file-name} to @code{nil}.
1620 Once consequence of reusing connection related information is that
1621 @var{tramp} needs to distinguish hosts. If you, for example, run a
1622 local @code{sshd} on port 3001, which tunnels @command{ssh} to another
1623 host, you could access both @file{@trampfn{ssh, , localhost,}} and
1624 @file{@trampfn{ssh, , localhost#3001,}}. @var{tramp} would use the
1625 same host related information (like paths, Perl variants, etc) for
1626 both connections, although the information is valid only for one of
1629 In order to avoid trouble, you must use another host name for one of
1630 the connections, like introducing a @option{Host} section in
1631 @file{~/.ssh/config} (@pxref{Frequently Asked Questions}) or applying
1632 multiple hops (@pxref{Multi-hops}).
1634 When @value{tramp} detects a changed operating system version on a
1635 remote host (via the command @command{uname -sr}), it flushes all
1636 connection related information for this host, and opens the
1640 @node Remote Programs
1641 @section How @value{tramp} finds and uses programs on the remote machine.
1643 @value{tramp} depends on a number of programs on the remote host in order to
1644 function, including @command{ls}, @command{test}, @command{find} and
1647 In addition to these required tools, there are various tools that may be
1648 required based on the connection method. See @ref{Inline methods} and
1649 @ref{External transfer methods} for details on these.
1651 Certain other tools, such as @command{perl} (or @command{perl5}) and
1652 @command{grep} will be used if they can be found. When they are
1653 available, they are used to improve the performance and accuracy of
1656 @vindex tramp-remote-path
1657 When @value{tramp} connects to the remote machine, it searches for the
1658 programs that it can use. The variable @code{tramp-remote-path}
1659 controls the directories searched on the remote machine.
1661 By default, this is set to a reasonable set of defaults for most
1662 machines. The symbol @code{tramp-default-remote-path} is a place
1663 holder, it is replaced by the list of directories received via the
1664 command @command{getconf PATH} on your remote machine. For example,
1665 on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is
1666 @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is
1667 recommended to apply this symbol on top of @code{tramp-remote-path}.
1669 It is possible, however, that your local (or remote ;) system
1670 administrator has put the tools you want in some obscure local
1673 In this case, you can still use them with @value{tramp}. You simply
1674 need to add code to your @file{.emacs} to add the directory to the
1675 remote path. This will then be searched by @value{tramp} when you
1676 connect and the software found.
1678 To add a directory to the remote search path, you could use code such
1682 @i{;; We load @value{tramp} to define the variable.}
1684 @i{;; We have @command{perl} in "/usr/local/perl/bin"}
1685 (add-to-list 'tramp-remote-path "/usr/local/perl/bin")
1688 @value{tramp} caches several information, like the Perl binary
1689 location. The changed remote search path wouldn't affect these
1690 settings. In order to force @value{tramp} to recompute these values,
1691 you must exit @value{emacsname}, remove your persistency file
1692 (@pxref{Connection caching}), and restart @value{emacsname}.
1695 @node Remote shell setup
1696 @section Remote shell setup hints
1697 @cindex remote shell setup
1698 @cindex @file{.profile} file
1699 @cindex @file{.login} file
1700 @cindex shell init files
1702 As explained in the @ref{Overview} section, @value{tramp} connects to the
1703 remote host and talks to the shell it finds there. Of course, when you
1704 log in, the shell executes its init files. Suppose your init file
1705 requires you to enter the birth date of your mother; clearly @value{tramp}
1706 does not know this and hence fails to log you in to that host.
1708 There are different possible strategies for pursuing this problem. One
1709 strategy is to enable @value{tramp} to deal with all possible situations.
1710 This is a losing battle, since it is not possible to deal with
1711 @emph{all} situations. The other strategy is to require you to set up
1712 the remote host such that it behaves like @value{tramp} expects. This might
1713 be inconvenient because you have to invest a lot of effort into shell
1714 setup before you can begin to use @value{tramp}.
1716 The package, therefore, pursues a combined approach. It tries to
1717 figure out some of the more common setups, and only requires you to
1718 avoid really exotic stuff. For example, it looks through a list of
1719 directories to find some programs on the remote host. And also, it
1720 knows that it is not obvious how to check whether a file exists, and
1721 therefore it tries different possibilities. (On some hosts and
1722 shells, the command @command{test -e} does the trick, on some hosts
1723 the shell builtin doesn't work but the program @command{/usr/bin/test
1724 -e} or @command{/bin/test -e} works. And on still other hosts,
1725 @command{ls -d} is the right way to do this.)
1727 Below you find a discussion of a few things that @value{tramp} does not deal
1728 with, and that you therefore have to set up correctly.
1731 @item @var{shell-prompt-pattern}
1732 @vindex shell-prompt-pattern
1734 After logging in to the remote host, @value{tramp} has to wait for the remote
1735 shell startup to finish before it can send commands to the remote
1736 shell. The strategy here is to wait for the shell prompt. In order to
1737 recognize the shell prompt, the variable @code{shell-prompt-pattern} has
1738 to be set correctly to recognize the shell prompt on the remote host.
1740 Note that @value{tramp} requires the match for @code{shell-prompt-pattern}
1741 to be at the end of the buffer. Many people have something like the
1742 following as the value for the variable: @code{"^[^>$][>$] *"}. Now
1743 suppose your shell prompt is @code{a <b> c $ }. In this case,
1744 @value{tramp} recognizes the @code{>} character as the end of the prompt,
1745 but it is not at the end of the buffer.
1747 @item @var{tramp-shell-prompt-pattern}
1748 @vindex tramp-shell-prompt-pattern
1750 This regular expression is used by @value{tramp} in the same way as
1751 @code{shell-prompt-pattern}, to match prompts from the remote shell.
1752 This second variable exists because the prompt from the remote shell
1753 might be different from the prompt from a local shell --- after all,
1754 the whole point of @value{tramp} is to log in to remote hosts as a
1755 different user. The default value of
1756 @code{tramp-shell-prompt-pattern} is the same as the default value of
1757 @code{shell-prompt-pattern}, which is reported to work well in many
1760 @item @var{tramp-password-prompt-regexp}
1761 @vindex tramp-password-prompt-regexp
1762 @vindex tramp-wrong-passwd-regexp
1764 During login, @value{tramp} might be forced to enter a password or a
1765 passphrase. The difference between both is that a password is
1766 requested from the shell on the remote host, while a passphrase is
1767 needed for accessing local authentication information, like your ssh
1770 @var{tramp-password-prompt-regexp} handles the detection of such
1771 requests for English environments. When you use another localization
1772 of your (local or remote) host, you might need to adapt this. Example:
1776 tramp-password-prompt-regexp
1780 '("passphrase" "Passphrase"
1782 "password" "Password"
1784 "passwort" "Passwort"
1786 "mot de passe" "Mot de passe") t)