@include trampver.texi
-@c Macro for formatting a filename according to the repective syntax.
+@c Macro for formatting a filename according to the respective syntax.
@c xxx and yyy are auxiliary macros in order to omit leading and
@c trailing whitespace. Not very elegant, but I don't know it better.
@end macro
@copying
-Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
-2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 1999-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@c Entries for @command{install-info} to use
@dircategory @value{emacsname}
@direntry
-* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
- @value{emacsname} remote file access via rsh and rcp.
+* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
+ @value{emacsname} remote file access via rsh and rcp.
@end direntry
@titlepage
@end ifset
@ifhtml
-@ifset jamanual
-This manual is also available as a @uref{@value{japanesemanual},
-Japanese translation}.
-@end ifset
-
The latest release of @value{tramp} is available for
@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
@ref{Obtaining Tramp} for more details, including the CVS server
* Installation parameters:: Parameters in order to control installation.
* Load paths:: How to plug-in @value{tramp} into your environment.
-* Japanese manual:: Japanese manual.
@end ifset
transfers a small piece of Perl code to the remote host, and tries to
apply it for encoding and decoding.
+The variable @var{tramp-inline-compress-start-size} controls, whether
+a file shall be compressed before encoding. This could increase
+transfer speed for large text files.
+
@table @asis
@item @option{rsh}
@file{~/.ssh/config}, the SSH configuration file, which protocol
should be used, and use the regular @option{ssh} method.)
-Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
-@command{ssh1} and @command{ssh2} commands explicitly. If you don't
-know what these are, you do not need these options.
-
-All the methods based on @command{ssh} have an additional kludgy
-feature: you can specify a host name which looks like @file{host#42}
-(the real host name, then a hash sign, then a port number). This
-means to connect to the given host but to also pass @code{-p 42} as
-arguments to the @command{ssh} command.
+All the methods based on @command{ssh} have an additional feature: you
+can specify a host name which looks like @file{host#42} (the real host
+name, then a hash sign, then a port number). This means to connect to
+the given host but to also pass @code{-p 42} as arguments to the
+@command{ssh} command.
@item @option{telnet}
invoked from an @value{emacsname} buffer, tells them that it is not
allocating a pseudo tty. When this happens, the login shell is wont
to not print any shell prompt, which confuses @value{tramp} mightily.
-For reasons unknown, some Windows ports for @command{ssh} require the
-doubled @samp{-t} option.
This supports the @samp{-p} argument.
@command{krlogin -x} command to log in to the remote host.
+@item @option{ksu}
+@cindex method ksu
+@cindex ksu method
+@cindex Kerberos (with ksu method)
+
+This is another method from the Kerberos suite. It behaves like @option{su}.
+
+
@item @option{plink}
@cindex method plink
@cindex plink method
hasn't defined a user name. Different port numbers must be defined in
the session.
-
-@item @option{fish}
-@cindex method fish
-@cindex fish method
-
-This is an experimental implementation of the fish protocol, known from
-the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
-the fish server implementation from the KDE kioslave. That means, the
-file @file{~/.fishsrv.pl} is expected to reside on the remote host.
-
-The implementation lacks good performance. The code is offered anyway,
-maybe somebody can improve the performance.
-
@end table
@file{~/.ssh/config}, the SSH configuration file, which protocol
should be used, and use the regular @option{scp} method.)
-Two other variants, @option{scp1_old} and @option{scp2_old}, use the
-@command{ssh1} and @command{ssh2} commands explicitly. If you don't
-know what these are, you do not need these options.
-
All the @command{ssh} based methods support the @samp{-p} feature
where you can specify a port number to connect to in the host name.
For example, the host name @file{host#42} tells @value{tramp} to
My suggestion is to use an inline method. For large files, external
methods might be more efficient, but I guess that most people will
-want to edit mostly small files.
+want to edit mostly small files. And if you access large text files,
+compression (driven by @var{tramp-inline-compress-start-size}) shall
+still result in good performance.
I guess that these days, most people can access a remote machine by
using @command{ssh}. So I suggest that you use the @option{ssh}
this line.
Another example is the tilde (@code{~}) character, say when adding
-@file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this
+@file{~/bin} to @code{PATH}. Many Bourne shells will not expand this
character, and since there is usually no directory whose name consists
of the single character tilde, strange things will happen.
@command{exec /bin/sh} step. But how to find out if the shell is
Bourne-ish?
+
+@item Interactive shell prompt
+
+@value{tramp} redefines the shell prompt in order to parse the shell's
+output robustly. When calling an interactive shell by @kbd{M-x
+shell}, this doesn't look nice.
+
+You can redefine the shell prompt by checking the environment variable
+@code{INSIDE_EMACS}, which is set by @value{tramp}, in your startup
+script @file{~/.emacs_SHELLNAME}. @code{SHELLNAME} might be the string
+@code{bash} or similar, in case of doubt you could set it the
+environment variable @code{ESHELL} in your @file{.emacs}:
+
+@lisp
+(setenv "ESHELL" "bash")
+@end lisp
+
+Your file @file{~/.emacs_SHELLNAME} could contain code like
+
+@example
+# Reset the prompt for remote Tramp shells.
+if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then
+ PS1="[\u@@\h \w]$ "
+fi
+@end example
+
+@ifinfo
+@ifset emacs
+@xref{Interactive Shell, , , @value{emacsdir}}.
+@end ifset
+@end ifinfo
+
@end table
@end lisp
@end ifset
+@ifset emacs
+It is also possible to disable backups depending on the used method.
+The following code disables backups for the @option{su} and
+@option{sudo} methods:
+
+@lisp
+(setq backup-enable-predicate
+ (lambda (name)
+ (and (normal-backup-enable-predicate name)
+ (not
+ (let ((method (file-remote-p name 'method)))
+ (when (stringp method)
+ (member method '("su" "sudo"))))))))
+@end lisp
+@end ifset
+
+
Another possibility is to use the @value{tramp} variable
@ifset emacs
@code{tramp-backup-directory-alist}.
The same problem can happen with auto-saving files.
@ifset emacs
-Since @value{emacsname} 21, the variable
-@code{auto-save-file-name-transforms} keeps information, on which
-directory an auto-saved file should go. By default, it is initialized
-for @value{tramp} files to the local temporary directory.
+The variable @code{auto-save-file-name-transforms} keeps information,
+on which directory an auto-saved file should go. By default, it is
+initialized for @value{tramp} files to the local temporary directory.
On some versions of @value{emacsname}, namely the version built for
Debian GNU/Linux, the variable @code{auto-save-file-name-transforms}
@file{.emacs} in my home directory I would specify the filename
@file{@trampfn{ssh, daniel, melancholia, .emacs}}.
+Finally, for some methods it is possible to specify a different port
+number than the default one, given by the method. This is specified
+by adding @file{#<port>} to the host name, like in @file{@trampfn{ssh,
+daniel, melancholia#42, .emacs}}.
+
@node Alternative Syntax
@section URL-like filename syntax
@option{smb} methods. Association of a pty, as specified in
@code{start-file-process}, is not supported.
+@code{process-file} and @code{start-file-process} work on the remote
+host, when the variable @code{default-directory} is remote:
+
+@lisp
+(let ((default-directory "/ssh:remote.host:"))
+ (start-file-process "grep" (get-buffer-create "*grep*")
+ "/bin/sh" "-c" "grep -e tramp *"))
+@end lisp
+
@ifset emacsgvfs
If the remote host is mounted via GVFS (see @ref{GVFS based methods}),
the remote filesystem is mounted locally. Therefore, there are no
Changing or removing an existing entry is not encouraged. The default
values are chosen for proper @value{tramp} work. Nevertheless, if for
example a paranoid system administrator disallows changing the
-@var{$HISTORY} environment variable, you can customize
+@code{HISTORY} environment variable, you can customize
@code{tramp-remote-process-environment}, or you can apply the
following code in your @file{.emacs}:
If you want to run a remote program, which shall connect the X11
server you are using with your local host, you can set the
-@var{$DISPLAY} environment variable on the remote host:
+@code{DISPLAY} environment variable on the remote host:
@lisp
(add-to-list 'tramp-remote-process-environment
@end example
You will see the buffer @file{*Async Shell Command*}, containing the
-continous output of the @command{tail} command.
+continuous output of the @command{tail} command.
@subsection Running eshell on a remote host
@b{@trampfn{sudo, root, host, /etc} $}
@end example
+@ifset emacs
+Since @value{emacsname} 23.2, @code{eshell} has also an own
+implementation of the @code{su} and @code{sudo} commands. Both
+commands change the default directory of the @file{*eshell*} buffer to
+the value related to the user the command has switched to. This works
+even on remote hosts, adding silently a corresponding entry to the
+variable @code{tramp-default-proxies-alist} (@pxref{Multi-hops}):
+
+@example
+@b{~ $} cd @trampfn{ssh, user, remotehost, /etc} @key{RET}
+@b{@trampfn{ssh, user, remotehost, /etc} $} find-file shadow @key{RET}
+File is not readable: @trampfn{ssh, user, remotehost, /etc/shadow}
+@b{@trampfn{ssh, user, remotehost, /etc} $} sudo find-file shadow @key{RET}
+#<buffer shadow>
+
+@b{@trampfn{ssh, user, remotehost, /etc} $} su - @key{RET}
+@b{@trampfn{su, root, remotehost, /root} $} id @key{RET}
+uid=0(root) gid=0(root) groups=0(root)
+@b{@trampfn{su, root, remotehost, /root} $}
+@end example
+@end ifset
+
@anchor{Running a debugger on a remote host}
@subsection Running a debugger on a remote host
@item
Which systems does it work on?
-The package has been used successfully on GNU Emacs 21, GNU Emacs 22
-and XEmacs 21 (starting with 21.4). Gateway methods are supported for
-GNU Emacs 22 only.
+The package has been used successfully on GNU Emacs 22, GNU Emacs 23,
+XEmacs 21 (starting with 21.4), and SXEmacs 22.
The package was intended to work on Unix, and it really expects a
-Unix-like system on the remote end (except the @option{smb} method),
-but some people seemed to have some success getting it to work on MS
-Windows NT/2000/XP @value{emacsname}.
-
-There is some informations on @value{tramp} on NT at the following URL;
-many thanks to Joe Stoy for providing the information:
-@uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/}
+Unix-like system on the remote end (except the @option{smb} and
+@option{imap} methods), but some people seemed to have some success
+getting it to work on MS Windows XP/Vista/7 @value{emacsname}.
-@c The link is broken. I've contacted Tom for clarification. Michael.
-@ignore
-The above mostly contains patches to old ssh versions; Tom Roche has a
-Web page with instructions:
-@uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html}
-@end ignore
@item
How could I speed up @value{tramp}?
Use caching. This is already enabled by default. Information about
the remote host as well as the remote files are cached for reuse. The
information about remote hosts is kept in the file specified in
-@code{tramp-persistency-file-name}. Keep this file.
+@code{tramp-persistency-file-name}. Keep this file. If you are
+confident, that files on remote hosts are not changed out of
+@value{emacsname}' control, set @code{remote-file-name-inhibit-cache}
+to @code{nil}.
Disable version control. If you access remote files which are not
under version control, a lot of check operations can be avoided by
@item
@value{tramp} does not connect to the remote host
-When @value{tramp} does not connect to the remote host, there are two
+When @value{tramp} does not connect to the remote host, there are three
reasons heading the bug mailing list:
@itemize @minus
[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
@end example
+@item
+Echoed characters after login
+
+When the remote machine opens an echoing shell, there might be control
+characters in the welcome message. @value{tramp} tries to suppress
+such echoes via the @code{stty -echo} command, but sometimes this
+command is not reached, because the echoed output has confused
+@value{tramp} already. In such situations it might be helpful to use
+the @option{sshx} or @option{scpx} methods, which allocate a pseudo tty.
+@xref{Inline methods}.
@item
@value{tramp} doesn't transfer strings with more than 500 characters
@end itemize
+@item
+@value{tramp} does not recognize hung @command{ssh} sessions
+
+When your network connection is down, @command{ssh} sessions might
+hang. @value{tramp} cannot detect it safely, because it still sees a
+running @command{ssh} process. Timeouts cannot be used as well,
+because it cannot be predicted, how long a remote command will last,
+for example when copying very large files.
+
+Therefore, you must configure the @command{ssh} process to die
+in such a case. The following entry in @file{~/.ssh/config} would do
+the job:
+
+@example
+Host *
+ ServerAliveInterval 5
+@end example
+
+
@item
File name completion does not work with @value{tramp}
@example
#!/bin/sh
-emacsclient @trampfn{ssh, `whoami`, `hostname --fqdn`, $1}
+emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1}
@end example
Then you must set the environment variable @code{EDITOR} pointing to
This is a performance degradation, because the lost file attributes
must be recomputed, when needed again. In cases the caller of
-@code{process-file} knows that there are file attribute changes, it
+@code{process-file} knows that there are no file attribute changes, it
shall let-bind the variable @code{process-file-side-effects} to
@code{nil}. @value{tramp} wouldn't flush the file attributes cache then.
(let (process-file-side-effects)
...)
@end lisp
+
+For asynchronous processes, @value{tramp} flushes the file attributes
+cache via a process sentinel. If the caller of
+@code{start-file-process} knows that there are no file attribute
+changes, it shall set the process sentinel to @code{nil}. In case the
+caller defines an own process sentinel, @value{tramp}'s process
+sentinel is overwritten. The caller can still flush the file
+attributes cache in its process sentinel with this code:
+
+@lisp
+(unless (memq (process-status proc) '(run open))
+ (dired-uncache remote-directory))
+@end lisp
+
+@code{remote-directory} shall be the root directory, where file
+attribute changes can happen during the process lifetime.
+@value{tramp} traverses all subdirectories, starting at this
+directory. Often, it is sufficient to use @code{default-directory} of
+the process buffer as root directory.
@end ifset
@*@indent @w{ 6} sent and received strings
@*@indent @w{ 7} file caching
@*@indent @w{ 8} connection properties
+@*@indent @w{ 9} test commands
@*@indent @w{10} traces (huge)
When @code{tramp-verbose} is greater than or equal to 4, the messages
@c * Use `filename' resp. `file name' consistently.
@c * Use `host' resp. `machine' consistently.
@c * Consistent small or capitalized words especially in menues.
-
-@ignore
- arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808
-@end ignore
HCoop / bpt / emacs.git / blobdiff