@setfilename ../../info/tramp
@c %**start of header
@settitle TRAMP User Manual
-@setchapternewpage odd
@c %**end of header
@c This is *so* much nicer :)
@copying
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
- 2006, 2007, 2008 Free Software Foundation, Inc.
+2006, 2007, 2008, 2009, 2010 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 is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
+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
+is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual. Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License. If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
@end quotation
@end copying
@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)
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.
* 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
* Multi-hops:: Connecting to a remote host using multiple hops.
* Customizing Methods:: Using Non-Standard Methods.
* Customizing Completion:: Selecting config files for user/host name completion.
-* Password caching:: Reusing passwords for several connections.
+* Password handling:: Reusing passwords for several connections.
* Connection caching:: Reusing connection related information.
* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
* Remote shell setup:: Remote shell setup hints.
* 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
* Multi-hops:: Connecting to a remote host using multiple hops.
* Customizing Methods:: Using Non-Standard Methods.
* Customizing Completion:: Selecting config files for user/host name completion.
-* Password caching:: Reusing passwords for several connections.
+* Password handling:: Reusing passwords for several connections.
* Connection caching:: Reusing connection related information.
* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
* Remote shell setup:: Remote shell setup hints.
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 caching}, otherwise you
+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}
@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}
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
@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}
@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 @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.
+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.
-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}
Since authorization is done on share level, you will be prompted
always for a password if you access another share on the same host.
-This can be suppressed by @ref{Password caching}.
+This can be suppressed by @ref{Password handling}.
MS Windows uses for authorization both a user name and a domain name.
Because of this, the @value{tramp} syntax has been extended: you can
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
@section 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.
@end defun
-@node Password caching
+@node Password handling
@section Reusing passwords for several connections.
@cindex passwords
the chosen method does not support access without password prompt
through own configuration.
-By default, @value{tramp} caches the passwords entered by you. They will
-be reused next time if a connection needs them for the same user name
-and host name, independently of the connection method.
+The best recommendation is to use the method's own mechanism for
+password handling. Consider @command{ssh-agent} for @option{ssh}-like
+methods, or @command{pageant} for @option{plink}-like methods.
+
+However, if you cannot apply such native password handling,
+@value{tramp} offers altenatives.
+
+
+@anchor{Using an authentication file}
+@subsection Using an authentication file
+
+@vindex auth-sources
+The package @file{auth-source.el}, originally developed in No Gnus,
+offers the possibility to read passwords from a file, like FTP does it
+from @file{~/.netrc}. The default authentication file is
+@file{~/.authinfo.gpg}, this can be changed via the variable
+@code{auth-sources}.
+
+@noindent
+A typical entry in the authentication file would be
+
+@example
+machine melancholia port scp login daniel password geheim
+@end example
+
+The port can be any @value{tramp} method (@pxref{Inline 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}:
+
+@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
+entered by you. They will be reused next time if a connection needs
+them for the same user name and host name, independently of the
+connection method.
@vindex password-cache-expiry
Passwords are not saved permanently, that means the password caching
@code{password-cache} (setting it to @code{nil}).
Implementation Note: password caching is based on the package
-@file{password.el} in No Gnus. For the time being, it is activated
-only when this package is seen in the @code{load-path} while loading
+@file{password-cache.el}. For the time being, it is activated only
+when this package is seen in the @code{load-path} while loading
@value{tramp}.
@ifset installchapter
If you don't use No Gnus, you can take @file{password.el} from the
@value{tramp} @file{contrib} directory, see @ref{Installation
parameters}.
@end ifset
-It will be activated mandatory once No Gnus has found its way into
-@value{emacsname}.
@node Connection caching
When @value{tramp} detects a changed operating system version on a
remote host (via the command @command{uname -sr}), it flushes all
-connection related information for this host, quits the execution, and
-displays a message like this:
-
-@example
-Quit: "Connection reset, because remote host changed from `Linux
-2.6.22-13-generic' to `Linux 2.6.22-14-generic'"
-@end example
-
-@noindent
-You can simply open the remote file again in such a case.
+connection related information for this host, and opens the
+connection, again.
@node Remote Programs
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,
@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
killing via a double-slash works only on the filename part, except
that filename part starts with @file{//}.
@ifset emacs
-A triple-slash stands for the default behaviour.
+A triple-slash stands for the default behavior.
@end ifset
@ifinfo
@xref{Minibuffer File, , , @value{emacsdir}}.
@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.
+
+@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
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
+@var{$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
interactively, the command offers all active remote connections in the
minibuffer as remote file name prefix like @file{@trampfn{method,
user, host, }}. The cleanup includes password cache (@pxref{Password
-caching}), file cache, connection cache (@pxref{Connection caching}),
+handling}), file cache, connection cache (@pxref{Connection caching}),
connection buffers.
@end deffn
@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}.
+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}.
-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/}
-
-@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
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
@end example
If it fails, or the cursor is not moved at the end of the buffer, your
-prompt is not recognised correctly.
+prompt is not recognized correctly.
A special problem is the zsh, which uses left-hand side and right-hand
side prompts in parallel. Therefore, it is necessary to disable the
[ $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.
+@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
HCoop / bpt / emacs.git / blobdiff