@setfilename ../../info/tramp
@c %**start of header
@settitle TRAMP User Manual
-@setchapternewpage odd
@c %**end of header
@c This is *so* much nicer :)
@end macro
@copying
-Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
-2007 Free Software Foundation, Inc.
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+2006, 2007, 2008, 2009 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.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
-
-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.
+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.''
@end quotation
@end copying
@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.
This method does not connect to a remote host at all, rather it uses
the @command{su} program to allow you to edit files as another user.
-With other words, a specified host name in the file name is silently
-ignored.
+That means, the specified host name in the file name must be either
+@samp{localhost} or the host name as returned by the function
+@command{(system-name)}. For an exception of this rule see
+@ref{Multi-hops}.
@item @option{sudo}
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.
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 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
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@footnote{If you don't use Partial Completion mode, but want to
-keep full completion, load @value{tramp} like this in your
-@file{.emacs}:
-
-@lisp
-;; Preserve Tramp's completion features.
-(let ((partial-completion-mode t))
- (require 'tramp))
-@end lisp
-}.
+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
+
+@code{shell-command} allows to execute commands in a shell, either
+synchronously, either asynchronously. This works also on remote
+hosts. Example:
+
+@example
+@kbd{C-x C-f @trampfn{sudo, , , } @key{RET}}
+@kbd{M-! tail -f /var/log/syslog.log & @key{RET}}
+@end example
+
+You will see the buffer @file{*Async Shell Command*}, containing the
+continous output of the @command{tail} command.
+
+
@subsection Running eshell on a remote host
@cindex eshell
/home/user/myprog.pl}, though.
Arguments of the program to be debugged are taken literally. That
-means file names as arguments must be given as ordinary relative or
+means, file names as arguments must be given as ordinary relative or
absolute file names, without any remote specification.
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
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},
@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
the different recipes!
+@ifset emacs
@item
-How can I disable @value{tramp}?
+How can I use @value{tramp} to connect to a remote @value{emacsname}
+session?
-Shame on you, why did you read until now?
+You can configure Emacs Client doing this.
+@ifinfo
+@xref{Emacs Server, , , @value{emacsdir}}.
+@end ifinfo
-@ifset emacs
-If you just want to have @value{ftppackagename} as default remote
-files access package, you should apply the following code:
+On the remote host, you start the Emacs Server:
@lisp
-(setq tramp-default-method "ftp")
+(require 'server)
+(setq server-host (system-name)
+ server-use-tcp t)
+(server-start)
@end lisp
-@end ifset
-
-Unloading @value{tramp} can be achieved by applying @kbd{M-x
-tramp-unload-tramp}.
-@ifset emacs
-This resets also the @value{ftppackagename} plugins.
-@end ifset
-@end itemize
-
-
-@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.
+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:
-@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
-
+@example
+emacsclient @trampfn{ssh, user, host, /file/to/edit}
+@end example
-@node Remote File Ownership
-@subsection How VC determines who owns a workfile
+@code{user} and @code{host} shall be related to your local host.
-@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.
+If you want to use Emacs Client also as editor for other programs, you
+could write a script @file{emacsclient.sh}:
-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.
+@example
+#!/bin/sh
+emacsclient @trampfn{ssh, `whoami`, `hostname --fqdn`, $1}
+@end example
-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.
+Then you must set the environment variable @code{EDITOR} pointing to
+that script:
-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.
+@example
+export EDITOR=/path/to/emacsclient.sh
+@end example
+@end ifset
-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.
+@item
+How can I disable @value{tramp}?
-@node Back-end Versions
-@subsection How VC determines what release your RCS is
+Shame on you, why did you read until now?
-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)}.
+@itemize @minus
-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.
+@item
+@ifset emacs
+If you just want to have @value{ftppackagename} as default remote
+files access package, you should apply the following code:
-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.
+@lisp
+(setq tramp-default-method "ftp")
+@end lisp
+@end ifset
-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.
+@item
+In order to disable
+@ifset emacs
+@value{tramp} (and @value{ftppackagename}),
+@end ifset
+@ifset xemacs
+@value{tramp},
+@end ifset
+you must set @code{tramp-mode} to @code{nil}:
-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.
+@lisp
+(setq tramp-mode nil)
+@end lisp
-Eventually these values will be captured by @value{tramp} on a system by
-system basis and the results cached to improve performance.
+@item
+Unloading @value{tramp} can be achieved by applying @kbd{M-x
+tramp-unload-tramp}.
+@ifset emacs
+This resets also the @value{ftppackagename} plugins.
+@end ifset
+@end itemize
+@end itemize
+@c For the developer
@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 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
@end ifset
@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