@setfilename ../../info/tramp
@c %**start of header
@settitle TRAMP User Manual
-@setchapternewpage odd
@c %**end of header
@c This is *so* much nicer :)
@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 Free Software Foundation, Inc.
+Copyright @copyright{} 1999-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
@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
-@tex
-
@titlepage
@title @value{tramp} version @value{trampver} User Manual
-
@author by Daniel Pittman
@author based on documentation by Kai Gro@ss{}johann
-
@page
@insertcopying
-
@end titlepage
-@page
-@end tex
+@contents
@ifnottex
@node Top, Overview, (dir), (dir)
@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
For the developer:
-* Version Control:: The inner workings of remote version control.
* Files directories and localnames:: How file names, directories and localnames are mangled and managed.
* Traces and Profiles:: How to Customize Traces.
* Issues:: Debatable Issues and What Was Decided.
* 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
* Connection types:: Types of connections made to remote machines.
* Inline methods:: Inline methods.
-* External transfer methods:: External transfer methods.
+* External methods:: External methods.
+@ifset emacsgvfs
+* GVFS based methods:: GVFS based external methods.
+@end ifset
@ifset emacsgw
* Gateway methods:: Gateway methods.
@end ifset
* Remote processes:: Integration with other @value{emacsname} packages.
* Cleanup remote connections:: Cleanup remote connections.
-The inner workings of remote version control
-
-* Version Controlled Files:: Determining if a file is under version control.
-* Remote Commands:: Executing the version control commands on the remote machine.
-* Changed workfiles:: Detecting if the working file has changed.
-* Checking out files:: Bringing the workfile out of the repository.
-* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
-
-Things related to Version Control that don't fit elsewhere
-
-* Remote File Ownership:: How VC determines who owns a workfile.
-* Back-end Versions:: How VC determines what release your RCS is.
-
How file names, directories and localnames are mangled and managed
* Localname deconstruction:: Breaking a localname into its components.
buffer that's used for communication, then decodes that output to
produce the file contents.
-For out-of-band transfers, @value{tramp} issues a command like the following:
+For external transfers, @value{tramp} issues a command like the
+following:
@example
rcp user@@host:/path/to/remote/file /tmp/tramp.4711
@end example
you are finished, you type @kbd{C-x C-s} to save the buffer.
@item
-Again, @value{tramp} transfers the file contents to the remote host either
-inline or out-of-band. This is the reverse of what happens when reading
-the file.
+Again, @value{tramp} transfers the file contents to the remote host
+either inline or external. This is the reverse of what happens when
+reading the file.
@end itemize
I hope this has provided you with a basic overview of what happens
@example
] @strong{cd ~/@value{emacsdir}}
] @strong{export CVS_RSH="ssh"}
-] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
+] @strong{cvs -z3 -d:pserver:anonymous@@cvs.savannah.gnu.org:/sources/tramp co tramp}
@end example
@noindent
] @strong{autoconf}
@end example
-People who have no direct CVS access (maybe because sitting behind a
-blocking firewall), can try the
-@uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly
-CVS Tree Tarball} instead of.
-
@node History
@chapter History of @value{tramp}
many more methods for getting a remote shell and for transferring the
file contents were added. Support for VC was added.
-The most recent addition of major features were the multi-hop methods
-added in April 2000 and the unification of @value{tramp} and Ange-FTP
-filenames in July 2002. In July 2004, multi-hop methods have been
-replaced by proxy hosts. Running commands on remote hosts was
-introduced in December 2005.
+After that, there were added the multi-hop methods in April 2000 and
+the unification of @value{tramp} and Ange-FTP filenames in July 2002.
+In July 2004, multi-hop methods have been replaced by proxy hosts.
+Running commands on remote hosts was introduced in December 2005.
@ifset emacsgw
Support of gateways exists since April 2007.
@end ifset
+@ifset emacsgvfs
+GVFS integration started in February 2009.
+@end ifset
+@ifset emacsimap
+Storing files into IMAP mailboxes has been added in September 2009.
+@end ifset
In December 2001, @value{tramp} has been added to the XEmacs package
repository. Being part of the GNU Emacs repository happened in June
@menu
* Connection types:: Types of connections made to remote machines.
* Inline methods:: Inline methods.
-* External transfer methods:: External transfer methods.
+* External methods:: External methods.
+@ifset emacsgvfs
+* GVFS based methods:: GVFS based external methods.
+@end ifset
@ifset emacsgw
* Gateway methods:: Gateway methods.
@end ifset
differ.
@cindex inline methods
-@cindex external transfer methods
@cindex external methods
-@cindex out-of-band methods
@cindex methods, inline
-@cindex methods, external transfer
-@cindex methods, out-of-band
+@cindex methods, external
Loading or saving a remote file requires that the content of the file
-be transfered between the two machines. The content of the file can be
-transfered over the same connection used to log in to the remote
-machine or the file can be transfered through another connection using
-a remote copy program such as @command{rcp}, @command{scp} or
-@command{rsync}. The former are called @dfn{inline methods}, the
-latter are called @dfn{out-of-band methods} or @dfn{external transfer
-methods} (@dfn{external methods} for short).
-
-The performance of the external transfer methods is generally better
-than that of the inline methods, at least for large files. This is
-caused by the need to encode and decode the data when transferring
-inline.
+be transfered between the two machines. The content of the file can
+be transfered using one of two methods: the @dfn{inline method} over
+the same connection used to log in to the remote machine, or the
+@dfn{external method} through another connection using a remote copy
+program such as @command{rcp}, @command{scp} or @command{rsync}.
+
+The performance of the external methods is generally better than that
+of the inline methods, at least for large files. This is caused by
+the need to encode and decode the data when transferring inline.
The one exception to this rule are the @command{scp} based transfer
methods. While these methods do see better performance when actually
transferring files, the overhead of the cryptographic negotiation at
startup may drown out the improvement in file transfer times.
-External transfer methods should be configured such a way that they
-don't require a password (with @command{ssh-agent}, or such alike).
-Modern @command{scp} implementations offer options to reuse existing
+External methods should be configured such a way that they don't
+require a password (with @command{ssh-agent}, or such alike). Modern
+@command{scp} implementations offer options to reuse existing
@command{ssh} connections, see method @command{scpc}. If it isn't
possible, you should consider @ref{Password handling}, otherwise you
will be prompted for a password every copy action.
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} kludge.
+This supports the @samp{-p} argument.
@item @option{krlogin}
@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
implementation of SSH. It uses @samp{plink -ssh} to log in to the
remote host.
-This supports the @samp{-P} kludge.
+This supports the @samp{-P} argument.
Additionally, the methods @option{plink1} and @option{plink2} are
provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in
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
-@node External transfer methods
-@section External transfer methods
-@cindex methods, external transfer
-@cindex methods, out-of-band
-@cindex external transfer methods
-@cindex out-of-band methods
+@node External methods
+@section External methods
+@cindex methods, external
+@cindex external methods
-The external transfer methods operate through multiple channels, using
-the remote shell connection for many actions while delegating file
+The external methods operate through multiple channels, using the
+remote shell connection for many actions while delegating file
transfers to an external transfer utility.
This saves the overhead of encoding and decoding that multiplexing the
transfer through the one connection has with the inline methods.
-Since external transfer methods need their own overhead opening a new
-channel, all files which are smaller than @var{tramp-copy-size-limit}
-are still transferred with the corresponding inline method. It should
-provide a fair trade-off between both approaches.
+Since external methods need their own overhead opening a new channel,
+all files which are smaller than @var{tramp-copy-size-limit} are still
+transferred with the corresponding inline method. It should provide a
+fair trade-off between both approaches.
@table @asis
@item @option{rcp} --- @command{rsh} and @command{rcp}
@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 kludgy @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
+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
specify @samp{-p 42} in the argument list for @command{ssh}, and to
specify @samp{-P 42} in the argument list for @command{scp}.
@command{ftp} is called interactively, and all commands are send from
within this session. Instead of, @command{ssh} is used for login.
-This method supports the @samp{-p} hack.
+This method supports the @samp{-p} argument.
@item @option{rsync} --- @command{ssh} and @command{rsync}
While @command{rsync} performs much better than @command{scp} when
transferring files that exist on both hosts, this advantage is lost if
-the file exists only on one side of the connection.
+the file exists only on one side of the connection. A file can exists
+on both the remote and local host, when you copy a file from/to a
+remote host. When you just open a file from the remote host (or write
+a file there), a temporary file on the local side is kept as long as
+the corresponding buffer, visiting this file, is alive.
-The @command{rsync} based method may be considerably faster than the
-@command{rcp} based methods when writing to the remote system. Reading
-files to the local machine is no faster than with a direct copy.
-
-This method supports the @samp{-p} hack.
+This method supports the @samp{-p} argument.
@item @option{scpx} --- @command{ssh} and @command{scp}
allocating a pseudo tty. When this happens, the login shell is wont
to not print any shell prompt, which confuses @value{tramp} mightily.
-This method supports the @samp{-p} hack.
+This method supports the @samp{-p} argument.
@item @option{scpc} --- @command{ssh} and @command{scp}
-@cindex method scpx
-@cindex scpx method
-@cindex scp (with scpx method)
-@cindex ssh (with scpx method)
+@cindex method scpc
+@cindex scpc method
+@cindex scp (with scpc method)
+@cindex ssh (with scpc method)
Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
@option{ControlMaster}. This allows @option{scp} to reuse an existing
ssh localhost -o ControlMaster=yes
@end example
-This method supports the @samp{-p} hack.
+This method supports the @samp{-p} argument.
+
+
+@item @option{rsyncc} --- @command{ssh} and @command{rsync}
+@cindex method rsyncc
+@cindex rsyncc method
+@cindex rsync (with rsyncc method)
+@cindex ssh (with rsyncc method)
+
+Like the @option{scpc} method, @option{rsyncc} improves the underlying
+@command{ssh} connection by the option @option{ControlMaster}. This
+allows @command{rsync} to reuse an existing @command{ssh} channel,
+which increases performance.
+
+This method supports the @samp{-p} argument.
@item @option{pscp} --- @command{plink} and @command{pscp}
@command{pscp} for transferring the files. These programs are part
of PuTTY, an SSH implementation for Windows.
-This method supports the @samp{-P} hack.
+This method supports the @samp{-P} argument.
@item @option{psftp} --- @command{plink} and @command{psftp}
uses @command{psftp} for transferring the files. These programs are
part of PuTTY, an SSH implementation for Windows.
-This method supports the @samp{-P} hack.
+This method supports the @samp{-P} argument.
@item @option{fcp} --- @command{fsh} and @command{fcp}
prompting) is assumed. This is different from all other @value{tramp}
methods, where in such a case the local user name is taken.
-The @option{smb} method supports the @samp{-p} hack.
+The @option{smb} method supports the @samp{-p} argument.
@strong{Please note:} If @value{emacsname} runs locally under MS
Windows, this method isn't available. Instead of, you can use UNC
disadvantage is that there's no possibility to specify another user
name.
+
+@ifset emacsimap
+@item @option{imap}
+@cindex method imap
+@cindex method imaps
+@cindex imap method
+@cindex imaps method
+
+Accessing an IMAP mailbox is intended to save files there as encrypted
+message. It could be used in case there are no other remote file
+storages available.
+
+@value{tramp} supports both @option{imap} and @option{imaps} methods.
+The latter one accesses the IMAP server over ssl.
+
+Both methods support the port number specification.
+
+Note, that special handling is needed for declaring a passphrase for
+encryption / decryption of the messages (@pxref{Using an
+authentication file}).
+
+@end ifset
+@end table
+
+
+@ifset emacsgvfs
+@node GVFS based methods
+@section GVFS based external methods
+@cindex methods, gvfs
+@cindex gvfs based methods
+@cindex dbus
+
+The connection methods described in this section are based on GVFS
+@uref{http://en.wikipedia.org/wiki/GVFS}. Via GVFS, the remote
+filesystem is mounted locally through FUSE. @value{tramp} uses
+internally this local mounted directory.
+
+The communication with GVFS is implemented via D-Bus messages.
+Therefore, your @value{emacsname} must have D-Bus integration,
+@pxref{Top, , D-Bus, dbus}.
+
+@table @asis
+@item @option{dav}
+@cindex method dav
+@cindex method davs
+@cindex dav method
+@cindex davs method
+
+This method provides access to WebDAV files and directories. There
+exists also the external method @option{davs}, which uses SSL
+encryption for the access.
+
+Both methods support the port number specification as discussed above.
+
+
+@item @option{obex}
+@cindex method obex
+@cindex obex method
+
+OBEX is an FTP-like access protocol for simple devices, like cell
+phones. Until now @value{tramp} supports only OBEX over Bluetooth.
+
+
+@item @option{synce}
+@cindex method synce
+@cindex synce method
+
+The @option{synce} method allows communication with Windows Mobile
+devices. Beside GVFS for mounting remote files and directories via
+FUSE, it needs also the SYNCE-GVFS plugin.
@end table
+@defopt tramp-gvfs-methods
+This customer option, a list, defines the external methods, which
+shall be used with GVFS. Per default, these are @option{dav},
+@option{davs}, @option{obex} and @option{synce}. Other possible
+values are @option{ftp}, @option{sftp} and @option{smb}.
+@end defopt
+@end ifset
+
@ifset emacsgw
@node Gateway methods
(@pxref{Multi-hops}) only.
A gateway method must come always along with a method who supports
-port setting (referred to as @samp{-p} kludge). This is because
-@value{tramp} targets the accompanied method to
-@file{localhost#random_port}, from where the firewall or proxy server
-is accessed to.
+port setting. This is because @value{tramp} targets the accompanied
+method to @file{localhost#random_port}, from where the firewall or
+proxy server is accessed to.
Gateway methods support user name and password declarations. These
are used to authenticate towards the corresponding firewall or proxy
See the documentation for the variable
@code{tramp-default-method-alist} for more details.
-External transfer methods are normally preferable to inline transfer
-methods, giving better performance.
+External methods are normally preferable to inline methods, giving
+better performance.
@xref{Inline methods}.
-@xref{External transfer methods}.
+@xref{External methods}.
Another consideration with the selection of transfer methods is the
environment you will use them in and, especially when used over the
like to have some guidance, so here I'll try to give you this guidance
without bossing you around. You tell me whether it works @dots{}
-My suggestion is to use an inline method. For large files, out-of-band
-methods might be more efficient, but I guess that most people will want
-to edit mostly small files.
+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. 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}
People who edit large files may want to consider @option{scpc} instead
of @option{ssh}, or @option{pscp} instead of @option{plink}. These
-out-of-band methods are faster than inline methods for large files.
-Note, however, that out-of-band methods suffer from some limitations.
+external methods are faster than inline methods for large files.
+Note, however, that external methods suffer from some limitations.
Please try first whether you really get a noticeable speed advantage
-from using an out-of-band method! Maybe even for large files, inline
+from using an external method! Maybe even for large files, inline
methods are fast enough.
has been reached so far. @code{sudo -u root}, applied on your local
host, wouldn't be useful here.
+@var{host}, @var{user} and @var{proxy} can also be Lisp forms. These
+forms are evaluated, and must return a string, or @code{nil}. The
+previous example could be generalized then: For all hosts except my
+local one connect via @code{ssh} first, and apply @code{sudo -u root}
+afterwards:
+
+@lisp
+(add-to-list 'tramp-default-proxies-alist
+ '(nil "\\`root\\'" "@trampfn{ssh, , %h,}"))
+(add-to-list 'tramp-default-proxies-alist
+ '((regexp-quote (system-name)) nil nil))
+@end lisp
+
This is the recommended configuration to work as @samp{root} on remote
Ubuntu hosts.
@value{tramp} offers altenatives.
-@anchor{auth-sources}
+@anchor{Using an authentication file}
@subsection Using an authentication file
@vindex auth-sources
@end example
The port can be any @value{tramp} method (@pxref{Inline methods},
-@pxref{External transfer methods}), to match only this method. When
-you omit the port, you match all @value{tramp} methods.
+@pxref{External methods}), to match only this method. When you omit
+the port, you match all @value{tramp} methods.
+@ifset emacsimap
+A special case are @option{imap}-like methods. Authentication with
+the IMAP server is performed via @file{imap.el}, there is no special
+need from @value{tramp} point of view. An additional passphrase, used
+for symmetric encryption and decryption of the stored messages, should
+be given with the special port indication @option{tramp-imap}:
-@anchor{password-cache}
+@example
+machine melancholia port tramp-imap login daniel password ultrageheim
+@end example
+@end ifset
+
+@anchor{Caching passwords}
@subsection Caching passwords
If there is no authentication file, @value{tramp} caches the passwords
In addition to these required tools, there are various tools that may be
required based on the connection method. See @ref{Inline methods} and
-@ref{External transfer methods} for details on these.
+@ref{External methods} for details on these.
Certain other tools, such as @command{perl} (or @command{perl5}) and
@command{grep} will be used if they can be found. When they are
remote file access.
@vindex tramp-remote-path
+@vindex tramp-default-remote-path
+@vindex tramp-own-remote-path
+@defopt tramp-remote-path
When @value{tramp} connects to the remote machine, it searches for the
programs that it can use. The variable @code{tramp-remote-path}
controls the directories searched on the remote machine.
(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
@end lisp
+Another possibility is to reuse the path settings of your remote
+account, when you log in. Usually, these settings are overwritten,
+because they might not be useful for @value{tramp}. The place holder
+@code{tramp-own-remote-path} preserves these settings. You can
+activate it via
+
+@lisp
+(add-to-list 'tramp-remote-path 'tramp-own-remote-path)
+@end lisp
+@end defopt
+
@value{tramp} caches several information, like the Perl binary
location. The changed remote search path wouldn't affect these
settings. In order to force @value{tramp} to recompute these values,
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}
@end table
+@var{machine} can also be an IPv4 or IPv6 address, like in
+@file{@trampfn{, , 127.0.0.1, .emacs}} or @file{@trampfn{, ,
+@value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}.
+@ifset emacs
+For syntactical reasons, IPv6 addresses must be embedded in square
+brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
+@end ifset
+
Unless you specify a different name to use, @value{tramp} will use the
current local user name as the remote user name to log in with. If you
need to log in as a different user, you can specify the user name as
@file{@trampfn{, daniel, melancholia, .emacs}}.
It is also possible to specify other file transfer methods
-(@pxref{Inline methods}, @pxref{External transfer methods}) as part of
-the filename.
+(@pxref{Inline methods}, @pxref{External methods}) as part of the
+filename.
@ifset emacs
This is done by putting the method before the user and host name, as
in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the
@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
names, of user names and of machine names as well as for completion of
file names on remote machines.
@ifset emacs
-In order to enable this, Partial Completion mode must be set on.
+In order to enable this, partial completion must be activated in your
+@file{.emacs}.
@ifinfo
@xref{Completion Options, , , @value{emacsdir}}.
@end ifinfo
@key{TAB}}, @value{tramp} might give you as result the choice for
@example
+@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
@ifset emacs
-@value{prefixhop}telnet@value{postfixhop} tmp/
-@value{prefixhop}toto@value{postfix}
+@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/
+@item @value{prefixhop}toto@value{postfix} @tab
@end ifset
@ifset xemacs
-@value{prefixhop}telnet@value{postfixhop} @value{prefixhop}toto@value{postfix}
+@item @value{prefixhop}telnet@value{postfixhop} @tab @value{prefixhop}toto@value{postfix}
@end ifset
+@end multitable
@end example
@samp{@value{prefixhop}telnet@value{postfixhop}}
your @file{/etc/hosts} file, let's say
@example
-@trampfn{telnet, , 127.0.0.1,} @trampfn{telnet, , 192.168.0.1,}
-@trampfn{telnet, , localhost,} @trampfn{telnet, , melancholia.danann.net,}
-@trampfn{telnet, , melancholia,}
+@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
+@item @trampfn{telnet, , 127.0.0.1,} @tab @trampfn{telnet, , 192.168.0.1,}
+@item @trampfn{telnet, , @value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet, , localhost,}
+@item @trampfn{telnet, , melancholia.danann.net,} @tab @trampfn{telnet, , melancholia,}
+@end multitable
@end example
Now you can choose the desired machine, and you can continue to
@value{tramp} supports running processes on a remote host. This
allows to exploit @value{emacsname} packages without modification for
remote file names. It does not work for the @option{ftp} and
-@option{smb} methods.
+@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
+remote processes; all processes run still locally on your machine with
+an adapted @code{default-directory}. This section does not apply for
+such connection methods.
+@end ifset
Remote processes are started when a corresponding command is executed
from a buffer belonging to a remote file or directory. Up to now, the
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}:
integrate them as well. @xref{Bug Reports}.
+@subsection Running remote programs that create local X11 windows
+
+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
+@code{DISPLAY} environment variable on the remote host:
+
+@lisp
+(add-to-list 'tramp-remote-process-environment
+ (format "DISPLAY=%s" (getenv "DISPLAY")))
+@end lisp
+
+@noindent
+@code{(getenv "DISPLAY")} shall return a string containing a host
+name, which can be interpreted on the remote host; otherwise you might
+use a fixed host name. Strings like @code{:0} cannot be used properly
+on the remote host.
+
+Another trick might be that you put @code{ForwardX11 yes} or
+@code{ForwardX11Trusted yes} to your @file{~/.ssh/config} file for
+that host.
+
+
@subsection Running shell-command on a remote host
@cindex shell-command
@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}?
In order to speed up @value{tramp}, one could either try to avoid some
of the operations, or one could try to improve their performance.
-Use an external transfer method, like @option{scpc}.
+Use an external method, like @option{scpc}.
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
disabling VC. This can be achieved by
@lisp
-(setq vc-handled-backends nil)
+(setq vc-ignore-dir-regexp
+ (format "\\(%s\\)\\|\\(%s\\)"
+ vc-ignore-dir-regexp
+ tramp-file-name-regexp))
@end lisp
Disable excessive traces. The default trace level of @value{tramp},
@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}
the different recipes!
+@ifset emacs
+@item
+How can I use @value{tramp} to connect to a remote @value{emacsname}
+session?
+
+You can configure Emacs Client doing this.
+@ifinfo
+@xref{Emacs Server, , , @value{emacsdir}}.
+@end ifinfo
+
+On the remote host, you start the Emacs Server:
+
+@lisp
+(require 'server)
+(setq server-host (system-name)
+ server-use-tcp t)
+(server-start)
+@end lisp
+
+Make sure, that the result of @code{(system-name)} can be resolved on
+your local host; otherwise you might use a hard coded IP address.
+
+The resulting file @file{~/.emacs.d/server/server} must be copied to
+your local host, at the same location. You can call then the Emacs
+Client from the command line:
+
+@example
+emacsclient @trampfn{ssh, user, host, /file/to/edit}
+@end example
+
+@code{user} and @code{host} shall be related to your local host.
+
+If you want to use Emacs Client also as editor for other programs, you
+could write a script @file{emacsclient.sh}:
+
+@example
+#!/bin/sh
+emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1}
+@end example
+
+Then you must set the environment variable @code{EDITOR} pointing to
+that script:
+
+@example
+export EDITOR=/path/to/emacsclient.sh
+@end example
+@end ifset
+
+
@item
How can I disable @value{tramp}?
@c For the developer
-@node Version Control
-@chapter The inner workings of remote version control
-@cindex Version Control
-
-Unlike @value{ftppackagename}, @value{tramp} has full shell access to the
-remote machine. This makes it possible to provide version control for
-files accessed under @value{tramp}.
-
-The actual version control binaries must be installed on the remote
-machine, accessible in the directories specified in
-@code{tramp-remote-path}.
-
-This transparent integration with the version control systems is one of
-the most valuable features provided by @value{tramp}, but it is far from perfect.
-Work is ongoing to improve the transparency of the system.
-
-@menu
-* Version Controlled Files:: Determining if a file is under version control.
-* Remote Commands:: Executing the version control commands on the remote machine.
-* Changed workfiles:: Detecting if the working file has changed.
-* Checking out files:: Bringing the workfile out of the repository.
-* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
-@end menu
-
-
-@node Version Controlled Files
-@section Determining if a file is under version control
-
-The VC package uses the existence of on-disk revision control master
-files to determine if a given file is under revision control. These file
-tests happen on the remote machine through the standard @value{tramp} mechanisms.
-
-
-@node Remote Commands
-@section Executing the version control commands on the remote machine
-
-There are no hooks provided by VC to allow intercepting of the version
-control command execution. The calls occur through the
-@code{call-process} mechanism, a function that is somewhat more
-efficient than the @code{shell-command} function but that does not
-provide hooks for remote execution of commands.
-
-To work around this, the functions @code{vc-do-command} and
-@code{vc-simple-command} have been advised to intercept requests for
-operations on files accessed via @value{tramp}.
-
-In the case of a remote file, the @code{shell-command} interface is
-used, with some wrapper code, to provide the same functionality on the
-remote machine as would be seen on the local machine.
-
-
-@node Changed workfiles
-@section Detecting if the working file has changed
-
-As there is currently no way to get access to the mtime of a file on a
-remote machine in a portable way, the @code{vc-workfile-unchanged-p}
-function is advised to call an @value{tramp} specific function for remote files.
-
-The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC
-diff functionality to determine if any changes have occurred between the
-workfile and the version control master.
-
-This requires that a shell command be executed remotely, a process that
-is notably heavier-weight than the mtime comparison used for local
-files. Unfortunately, unless a portable solution to the issue is found,
-this will remain the cost of remote version control.
-
-
-@node Checking out files
-@section Bringing the workfile out of the repository
-
-VC will, by default, check for remote files and refuse to act on them
-when checking out files from the repository. To work around this
-problem, the function @code{vc-checkout} knows about @value{tramp} files and
-allows version control to occur.
-
-
-@node Miscellaneous Version Control
-@section Things related to Version Control that don't fit elsewhere
-
-Minor implementation details, &c.
-
-@menu
-* Remote File Ownership:: How VC determines who owns a workfile.
-* Back-end Versions:: How VC determines what release your RCS is.
-@end menu
-
-
-@node Remote File Ownership
-@subsection How VC determines who owns a workfile
-
-@value{emacsname} provides the @code{user-login-name} function to
-return the login name of the current user as well as mapping from
-arbitrary user id values back to login names. The VC code uses this
-functionality to map from the uid of the owner of a workfile to the
-login name in some circumstances.
-
-This will not, for obvious reasons, work if the remote system has a
-different set of logins. As such, it is necessary to delegate to the
-remote machine the job of determining the login name associated with a
-uid.
-
-Unfortunately, with the profusion of distributed management systems such
-as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple,
-reliable and portable method for performing this mapping.
-
-Thankfully, the only place in the VC code that depends on the mapping of
-a uid to a login name is the @code{vc-file-owner} function. This returns
-the login of the owner of the file as a string.
-
-This function has been advised to use the output of @command{ls} on the
-remote machine to determine the login name, delegating the problem of
-mapping the uid to the login to the remote system which should know more
-about it than I do.
-
-
-@node Back-end Versions
-@subsection How VC determines what release your RCS is
-
-VC needs to know what release your revision control binaries you are
-running as not all features VC supports are available with older
-versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}.
-
-The default implementation of VC determines this value the first time it
-is needed and then stores the value globally to avoid the overhead of
-executing a process and parsing its output each time the information is
-needed.
-
-Unfortunately, life is not quite so easy when remote version control
-comes into the picture. Each remote machine may have a different version
-of the version control tools and, while this is painful, we need to
-ensure that unavailable features are not used remotely.
-
-To resolve this issue, @value{tramp} currently takes the sledgehammer
-approach of making the release values of the revision control tools
-local to each @value{tramp} buffer, forcing VC to determine these values
-again each time a new file is visited.
-
-This has, quite obviously, some performance implications. Thankfully,
-most of the common operations performed by VC do not actually require
-that the remote version be known. This makes the problem far less
-apparent.
-
-Eventually these values will be captured by @value{tramp} on a system by
-system basis and the results cached to improve performance.
-
-
@node Files directories and localnames
@chapter How file names, directories and localnames are mangled and managed.
@ifset emacs
@node External packages
@section Integration with external Lisp packages.
+@subsection Filename completion.
While reading filenames in the minibuffer, @value{tramp} must decide
whether it completes possible incomplete filenames, or not. Imagine
External packages, which use other characters for completing filenames
in the minibuffer, must signal this to @value{tramp}. For this case,
the variable @code{tramp-completion-mode} can be bound temporarily to
-a non-nil value.
+a non-@code{nil} value.
@lisp
(let ((tramp-completion-mode t))
...)
@end lisp
+
+
+@subsection File attributes cache.
+
+When @value{tramp} runs remote processes, files on the remote host
+could change their attributes. Consequently, @value{tramp} must flush
+its complete cache keeping attributes for all files of the remote host
+it has seen so far.
+
+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 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.
+
+@lisp
+(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
@unnumbered Concept Index
@printindex cp
-@contents
-@c End of tramp.texi - the TRAMP User Manual
@bye
@c TODO
@c shells.
@c * Explain how tramp.el works in principle: open a shell on a remote
@c host and then send commands to it.
-@c * Make terminology "inline" vs "out-of-band" consistent.
-@c It seems that "external" is also used instead of "out-of-band".
-
-@c * M. Albinus
-@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
+@c * Use `filename' resp. `file name' consistently.
+@c * Use `host' resp. `machine' consistently.
+@c * Consistent small or capitalized words especially in menues.
HCoop / bpt / emacs.git / blobdiff