@c This is *so* much nicer :)
@footnotestyle end
-@c In the Tramp CVS, the version number is auto-frobbed from
+@c In the Tramp repository, the version number is auto-frobbed from
@c configure.ac, so you should edit that file and run
@c "autoconf && ./configure" to change the version number.
@end macro
@copying
-Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
-2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+Copyright @copyright{} 1999--2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
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.''
+copy and modify this GNU manual.''
@end quotation
@end copying
@c Entries for @command{install-info} to use
-@dircategory @value{emacsname}
+@dircategory @value{emacsname} network features
@direntry
* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
@value{emacsname} remote file access via rsh and rcp.
@ifhtml
The latest release of @value{tramp} is available for
@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
-@ref{Obtaining Tramp} for more details, including the CVS server
+@ref{Obtaining Tramp} for more details, including the Git server
details.
@value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/,
* Filename Syntax:: @value{tramp} filename conventions.
* Alternative Syntax:: URL-like filename syntax.
* Filename completion:: Filename completion.
+* Ad-hoc multi-hops:: Declaring multiple hops in the file name.
* Remote processes:: Integration with other @value{emacsname} packages.
* Cleanup remote connections:: Cleanup remote connections.
@cindex obtaining Tramp
@value{tramp} is freely available on the Internet and the latest
-release may be downloaded from
-@uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
-documentation and code for @value{tramp}, suitable for installation.
-But GNU Emacs (22 or later) includes @value{tramp} already, and there
-is a @value{tramp} package for XEmacs, as well. So maybe it is easier
-to just use those. But if you want the bleeding edge, read
-on@dots{...}
-
-For the especially brave, @value{tramp} is available from CVS. The CVS
+release may be downloaded from @uref{ftp://ftp.gnu.org/gnu/tramp/}.
+This release includes the full documentation and code for
+@value{tramp}, suitable for installation. But Emacs (22 or later)
+includes @value{tramp} already, and there is a @value{tramp} package
+for XEmacs, as well. So maybe it is easier to just use those. But if
+you want the bleeding edge, read on@dots{}
+
+For the especially brave, @value{tramp} is available from Git. The Git
version is the latest version of the code and may contain incomplete
features or new issues. Use these versions at your own risk.
Instructions for obtaining the latest development version of @value{tramp}
-from CVS can be found by going to the Savannah project page at the
-following URL and then clicking on the CVS link in the navigation bar
+from Git can be found by going to the Savannah project page at the
+following URL and then clicking on the Git link in the navigation bar
at the top.
@noindent
@example
] @strong{cd ~/@value{emacsdir}}
-] @strong{export CVS_RSH="ssh"}
-] @strong{cvs -z3 -d:pserver:anonymous@@cvs.savannah.gnu.org:/sources/tramp co tramp}
+] @strong{git clone git://git.savannah.gnu.org/tramp.git}
+@end example
+
+@noindent
+Tramp developers use instead
+
+@example
+] @strong{git clone login@@git.sv.gnu.org:/srv/git/tramp.git}
@end example
@noindent
@example
] @strong{cd ~/@value{emacsdir}/tramp}
-] @strong{export CVS_RSH="ssh"}
-] @strong{cvs update -d}
+] @strong{git pull}
@end example
@noindent
-Once you've got updated files from the CVS repository, you need to run
+Once you've got updated files from the Git repository, you need to run
@command{autoconf} in order to get an up-to-date @file{configure}
script:
@ifset emacsgvfs
GVFS integration started in February 2009.
@end ifset
-@ifset emacsimap
-Storing files into IMAP mailboxes has been added in September 2009.
+@ifset emacs
+Remote commands on Windows hosts are available since September 2011.
@end ifset
+Ad-hoc multi-hop methods (with a changed syntax) have been reenabled
+in November 2011. In November 2012, Juergen Hoetzel's
+@file{tramp-adb.el} has been added.
In December 2001, @value{tramp} has been added to the XEmacs package
-repository. Being part of the GNU Emacs repository happened in June
-2002, the first release including @value{tramp} was GNU Emacs 22.1.
+repository. Being part of the Emacs repository happened in June 2002,
+the first release including @value{tramp} was Emacs 22.1.
-@value{tramp} is also a GNU/Linux Debian package since February 2001.
+@value{tramp} is also a Debian GNU/Linux package since February 2001.
@c Installation chapter is necessary only in case of standalone
* 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.
-* Windows setup hints:: Issues with Cygwin ssh.
* Auto-save and Backup:: Auto-save and Backup.
+* Windows setup hints:: Issues with Cygwin ssh.
@end menu
@node Connection types
-@section Types of connections made to remote machines.
+@section Types of connections made to remote machines
@cindex connection types, overview
There are two basic types of transfer methods, each with its own
@cindex methods, inline
@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 using one of two methods: the @dfn{inline method} over
+be transferred between the two machines. The content of the file can
+be transferred 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}.
@file{~/.ssh/config}, the SSH configuration file, which protocol
should be used, and use the regular @option{ssh} method.)
-Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
-@command{ssh1} and @command{ssh2} commands explicitly. If you don't
-know what these are, you do not need these options.
-
All the methods based on @command{ssh} have an additional 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
@command{krlogin -x} command to log in to the remote host.
+@item @option{ksu}
+@cindex method ksu
+@cindex ksu method
+@cindex Kerberos (with ksu method)
+
+This is another method from the Kerberos suite. It behaves like @option{su}.
+
+
@item @option{plink}
@cindex method plink
@cindex plink method
This method is mostly interesting for Windows users using the PuTTY
-implementation of SSH. It uses @samp{plink -ssh} to log in to the
+implementation of SSH@. It uses @samp{plink -ssh} to log in to the
remote host.
This supports the @samp{-P} argument.
hasn't defined a user name. Different port numbers must be defined in
the session.
-
-@item @option{fish}
-@cindex method fish
-@cindex fish method
-
-This is an experimental implementation of the fish protocol, known from
-the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
-the fish server implementation from the KDE kioslave. That means, the
-file @file{~/.fishsrv.pl} is expected to reside on the remote host.
-
-The implementation lacks good performance. The code is offered anyway,
-maybe somebody can improve the performance.
-
@end table
fair trade-off between both approaches.
@table @asis
-@item @option{rcp} --- @command{rsh} and @command{rcp}
+@item @option{rcp}---@command{rsh} and @command{rcp}
@cindex method rcp
@cindex rcp method
@cindex rcp (with rcp method)
@command{remsh} is used instead of @command{rsh}.
-@item @option{scp} --- @command{ssh} and @command{scp}
+@item @option{scp}---@command{ssh} and @command{scp}
@cindex method scp
@cindex scp method
@cindex scp (with scp method)
@file{~/.ssh/config}, the SSH configuration file, which protocol
should be used, and use the regular @option{scp} method.)
-Two other variants, @option{scp1_old} and @option{scp2_old}, use the
-@command{ssh1} and @command{ssh2} commands explicitly. If you don't
-know what these are, you do not need these options.
-
All the @command{ssh} based methods support the @samp{-p} feature
where you can specify a port number to connect to in the host name.
For example, the host name @file{host#42} tells @value{tramp} to
specify @samp{-P 42} in the argument list for @command{scp}.
-@item @option{sftp} --- @command{ssh} and @command{sftp}
+@item @option{sftp}---@command{ssh} and @command{sftp}
@cindex method sftp
@cindex sftp method
@cindex sftp (with sftp method)
This method supports the @samp{-p} argument.
-@item @option{rsync} --- @command{ssh} and @command{rsync}
+@item @option{rsync}---@command{ssh} and @command{rsync}
@cindex method rsync
@cindex rsync method
@cindex rsync (with rsync method)
This method supports the @samp{-p} argument.
-@item @option{scpx} --- @command{ssh} and @command{scp}
+@item @option{scpx}---@command{ssh} and @command{scp}
@cindex method scpx
@cindex scpx method
@cindex scp (with scpx method)
This method supports the @samp{-p} argument.
-@item @option{scpc} --- @command{ssh} and @command{scp}
+@item @option{scpc}---@command{ssh} and @command{scp}
@cindex method scpc
@cindex scpc method
@cindex scp (with scpc method)
@option{ControlMaster}. This allows @option{scp} to reuse an existing
@option{ssh} channel, which increases performance.
-Before you use this method, you shall check whether your @option{ssh}
-implementation does support this option. Try from the command line
+Before you use this method, you should check whether your @option{ssh}
+implementation supports this option. Try from the command line
@example
-ssh localhost -o ControlMaster=yes
+ssh localhost -o ControlMaster=yes /bin/true
@end example
+If that command succeeds silently, then you can use @option{scpc}; but
+if it fails like
+
+@example
+command-line: line 0: Bad configuration option: ControlMaster
+@end example
+
+then you cannot use it. Note, that the option
+@option{ControlPersist}, if it is supported by your @option{ssh}
+version, must be set to @option{no}.
+
This method supports the @samp{-p} argument.
-@item @option{rsyncc} --- @command{ssh} and @command{rsync}
+@item @option{rsyncc}---@command{ssh} and @command{rsync}
@cindex method rsyncc
@cindex rsyncc method
@cindex rsync (with rsyncc method)
This method supports the @samp{-p} argument.
-@item @option{pscp} --- @command{plink} and @command{pscp}
+@item @option{pscp}---@command{plink} and @command{pscp}
@cindex method pscp
@cindex pscp method
@cindex pscp (with pscp method)
This method supports the @samp{-P} argument.
-@item @option{psftp} --- @command{plink} and @command{psftp}
+@item @option{psftp}---@command{plink} and @command{psftp}
@cindex method psftp
@cindex psftp method
@cindex psftp (with psftp method)
This method supports the @samp{-P} argument.
-@item @option{fcp} --- @command{fsh} and @command{fcp}
+@item @option{fcp}---@command{fsh} and @command{fcp}
@cindex method fcp
@cindex fcp method
@cindex fsh (with fcp method)
@cindex method ftp
@cindex ftp method
-This is not a native @value{tramp} method. Instead of, it forwards all
+This is not a native @value{tramp} method. Instead, it forwards all
requests to @value{ftppackagename}.
@ifset xemacs
This works only for unified filenames, see @ref{Issues}.
@end ifset
-@item @option{smb} --- @command{smbclient}
+@item @option{smb}---@command{smbclient}
@cindex method smb
@cindex smb method
-This is another not natural @value{tramp} method. It uses the
+This is another not native @value{tramp} method. It uses the
@command{smbclient} command on different Unices in order to connect to
an SMB server. An SMB server might be a Samba (or CIFS) server on
another UNIX host or, more interesting, a host running MS Windows. So
-far, it is tested towards MS Windows NT, MS Windows 2000, and MS
-Windows XP.
+far, it is tested against MS Windows NT, MS Windows 2000, MS Windows
+XP, MS Windows Vista, and MS Windows 7.
The first directory in the localname must be a share name on the remote
-host. Remember, that the @code{$} character in which default shares
+host. Remember that the @code{$} character, in which default shares
usually end, must be written @code{$$} due to environment variable
-substitution in file names. If no share name is given (i.e. remote
+substitution in file names. If no share name is given (i.e., remote
directory @code{/}), all available shares are listed.
-Since authorization is done on share level, you will be prompted
-always for a password if you access another share on the same host.
+Since authorization is done on share level, you will always be
+prompted for a password if you access another share on the same host.
This can be suppressed by @ref{Password handling}.
-MS Windows uses for authorization both a user name and a domain name.
+For authorization, MS Windows uses both a user name and a domain name.
Because of this, the @value{tramp} syntax has been extended: you can
specify a user name which looks like @code{user%domain} (the real user
name, then a percent sign, then the domain name). So, to connect to
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
+Windows, this method isn't available. Instead, you can use UNC
file names like @file{//melancholia/daniel$$/.emacs}. The only
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.
+@item @option{adb}
+@cindex method adb
+@cindex adb method
-@value{tramp} supports both @option{imap} and @option{imaps} methods.
-The latter one accesses the IMAP server over ssl.
+This special method uses the Android Debug Bridge for connecting
+Android devices. The Android Debug Bridge, part of the Android SDK,
+must be installed locally. The variable @var{tramp-adb-sdk-dir} must
+be set to its installation directory.
-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
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.
+filesystem is mounted locally through FUSE@. @value{tramp} uses
+this local mounted directory internally.
The communication with GVFS is implemented via D-Bus messages.
Therefore, your @value{emacsname} must have D-Bus integration,
@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.
+phones. For the time being, @value{tramp} only supports OBEX over Bluetooth.
@item @option{synce}
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.
+FUSE, it also needs 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},
+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
Therefore, they can be used for proxy host declarations
(@pxref{Multi-hops}) only.
-A gateway method must come always along with a method who supports
+A gateway method must always come along with a method which supports
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.
+proxy server is accessed.
Gateway methods support user name and password declarations. These
are used to authenticate towards the corresponding firewall or proxy
@end lisp
@noindent
-See the documentation for the variable
-@code{tramp-default-user-alist} for more details.
+See the documentation for the variable @code{tramp-default-user-alist}
+for more details.
One trap to fall in must be known. If @value{tramp} finds a default
user, this user will be passed always to the connection command as
-parameter (for example @samp{ssh here.somewhere.else -l john}. If you
-have specified another user for your command in its configuration
+parameter (for example @command{ssh here.somewhere.else -l john}. If
+you have specified another user for your command in its configuration
files, @value{tramp} cannot know it, and the remote access will fail.
If you have specified in the given example in @file{~/.ssh/config} the
lines
because @samp{/:} is the prefix for quoted file names.
@end ifset
+@vindex tramp-default-host-alist
+Like with methods and users, you can also specify different default
+hosts for certain method/user combinations via the variable
+@code{tramp-default-host-alist}. Usually, this isn't necessary,
+because @code{tramp-default-host} should be sufficient. For some
+methods, like @code{adb}, that default value must be overwritten,
+which is already the initial value of @code{tramp-default-host-alist}.
+
+@noindent
+See the documentation for the variable @code{tramp-default-host-alist}
+for more details.
+
@node Multi-hops
@section Connecting to a remote host using multiple hops
@cindex multi-hop
@cindex proxy hosts
-Sometimes, the methods described before are not sufficient. Sometimes,
-it is not possible to connect to a remote host using a simple command.
-For example, if you are in a secured network, you might have to log in
-to a `bastion host' first before you can connect to the outside world.
-Of course, the target host may also require a bastion host.
+Sometimes, the methods described before are not sufficient.
+Sometimes, it is not possible to connect to a remote host using a
+simple command. For example, if you are in a secured network, you
+might have to log in to a bastion host first before you can connect to
+the outside world. Of course, the target host may also require a
+bastion host.
@vindex tramp-default-proxies-alist
-In order to specify such multiple hops, it is possible to define a proxy
+@defopt tramp-default-proxies-alist
+In order to specify multiple hops, it is possible to define a proxy
host to pass through, via the variable
@code{tramp-default-proxies-alist}. This variable keeps a list of
triples (@var{host} @var{user} @var{proxy}).
- The first matching item specifies the proxy host to be passed for a
+The first matching item specifies the proxy host to be passed for a
file name located on a remote target matching @var{user}@@@var{host}.
@var{host} and @var{user} are regular expressions or @code{nil}, which
is interpreted as a regular expression which always matches.
@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:
+local one connect via @command{ssh} first, and apply @command{sudo -u
+root} afterwards:
@lisp
(add-to-list 'tramp-default-proxies-alist
Gateway methods can be declared as first hop only in a multiple hop
chain.
@end ifset
+@end defopt
+
+Hops to be passed tend to be restricted firewalls and alike.
+Sometimes they offer limited features only, like running @command{rbash}
+(restricted bash). This must be told to @value{tramp}.
+
+@vindex tramp-restricted-shell-hosts-alist
+@defopt tramp-restricted-shell-hosts-alist
+This variable keeps a list of regular expressions, which denote hosts
+running a registered shell like "rbash". Those hosts can be used as
+proxies only.
+
+If the bastion host from the example above runs a restricted shell,
+you shall apply
+
+@lisp
+(add-to-list 'tramp-restricted-shell-hosts-alist
+ "\\`bastion\\.your\\.domain\\'")
+@end lisp
+@end defopt
@node Customizing Methods
@item @code{tramp-parse-netrc}
@findex tramp-parse-netrc
-Finally, a function which parses @file{~/.netrc} like files.
+Finally, a function which parses @file{~/.netrc} like files. This
+includes also @file{~/.authinfo}-style files.
+
@end table
If you want to keep your own data in a file, with your own structure,
@node Password handling
-@section Reusing passwords for several connections.
+@section Reusing passwords for several connections
@cindex passwords
Sometimes it is necessary to connect to the same remote host several
methods, or @command{pageant} for @option{plink}-like methods.
However, if you cannot apply such native password handling,
-@value{tramp} offers altenatives.
+@value{tramp} offers alternatives.
@anchor{Using an authentication file}
@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}:
+In case of problems, setting @code{auth-source-debug} to @code{t}
+gives useful debug messages.
-@example
-machine melancholia port tramp-imap login daniel password ultrageheim
-@end example
-@end ifset
@anchor{Caching passwords}
@subsection Caching passwords
@node Connection caching
-@section Reusing connection related information.
+@section Reusing connection related information
@cindex caching
@vindex tramp-persistency-file-name
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, and opens the
-connection, again.
+connection again.
@node Remote Programs
-@section How @value{tramp} finds and uses programs on the remote machine.
+@section How @value{tramp} finds and uses programs on the remote machine
@value{tramp} depends on a number of programs on the remote host in order to
function, including @command{ls}, @command{test}, @command{find} and
machines. The symbol @code{tramp-default-remote-path} is a place
holder, it is replaced by the list of directories received via the
command @command{getconf PATH} on your remote machine. For example,
-on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is
-@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is
-recommended to apply this symbol on top of @code{tramp-remote-path}.
+on Debian GNU/Linux this is @file{/bin:/usr/bin}, whereas on Solaris
+this is @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}.
+It is recommended to apply this symbol on top of
+@code{tramp-remote-path}.
It is possible, however, that your local (or remote ;) system
administrator has put the tools you want in some obscure local
@end lisp
Another possibility is to reuse the path settings of your remote
-account, when you log in. Usually, these settings are overwritten,
+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
This regular expression is used by @value{tramp} in the same way as
@code{shell-prompt-pattern}, to match prompts from the remote shell.
This second variable exists because the prompt from the remote shell
-might be different from the prompt from a local shell --- after all,
+might be different from the prompt from a local shell---after all,
the whole point of @value{tramp} is to log in to remote hosts as a
different user. The default value of
@code{tramp-shell-prompt-pattern} is the same as the default value of
"passwort" "Passwort"
;; Fran@,{c}ais
"mot de passe" "Mot de passe") t)
- ".*:\0? *"))
+ ".*:\0? *"))
@end lisp
In parallel, it might also be necessary to adapt
@value{tramp} does not know how to answer these questions. There are
two approaches for dealing with this problem. One approach is to take
care that the shell does not ask any questions when invoked from
-@value{tramp}. You can do this by checking the @code{TERM}
+@value{tramp}. You can do this by checking the @env{TERM}
environment variable, it will be set to @code{dumb} when connecting.
@vindex tramp-terminal-type
@item Environment variables named like users in @file{.profile}
-If you have a user named frumple and set the variable @code{FRUMPLE} in
+If you have a user named frumple and set the variable @env{FRUMPLE} in
your shell environment, then this might cause trouble. Maybe rename
-the variable to @code{FRUMPLE_DIR} or the like.
+the variable to @env{FRUMPLE_DIR} or the like.
This weird effect was actually reported by a @value{tramp} user!
this line.
Another example is the tilde (@code{~}) character, say when adding
-@file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this
+@file{~/bin} to @env{PATH}. Many Bourne shells will not expand this
character, and since there is usually no directory whose name consists
of the single character tilde, strange things will happen.
@command{exec /bin/sh} step. But how to find out if the shell is
Bourne-ish?
+
+@item Interactive shell prompt
+
+@value{tramp} redefines the shell prompt in order to parse the shell's
+output robustly. When calling an interactive shell by @kbd{M-x
+shell}, this doesn't look nice.
+
+You can redefine the shell prompt by checking the environment variable
+@env{INSIDE_EMACS}, which is set by @value{tramp}, in your startup
+script @file{~/.emacs_SHELLNAME}. @env{SHELLNAME} might be the string
+@code{bash} or similar, in case of doubt you could set it the
+environment variable @env{ESHELL} in your @file{.emacs}:
+
+@lisp
+(setenv "ESHELL" "bash")
+@end lisp
+
+Your file @file{~/.emacs_SHELLNAME} could contain code like
+
+@example
+# Reset the prompt for remote Tramp shells.
+if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then
+ PS1="[\u@@\h \w]$ "
+fi
+@end example
+
+@ifinfo
+@ifset emacs
+@xref{Interactive Shell, , , @value{emacsdir}}.
+@end ifset
+@end ifinfo
+
@end table
you might encounter problems with @command{ssh-agent}. Using this
program, you can avoid typing the pass-phrase every time you log in.
However, if you start @value{emacsname} from a desktop shortcut, then
-the environment variable @code{SSH_AUTH_SOCK} is not set and so
+the environment variable @env{SSH_AUTH_SOCK} is not set and so
@value{emacsname} and thus @value{tramp} and thus @command{ssh} and
@command{scp} started from @value{tramp} cannot communicate with
@command{ssh-agent}. It works better to start @value{emacsname} from
* Filename Syntax:: @value{tramp} filename conventions.
* Alternative Syntax:: URL-like filename syntax.
* Filename completion:: Filename completion.
+* Ad-hoc multi-hops:: Declaring multiple hops in the file name.
* Remote processes:: Integration with other @value{emacsname} packages.
* Cleanup remote connections:: Cleanup remote connections.
@end menu
the machine.
@item @trampfn{, , melancholia, ~/.emacs}
-This also edits the same file --- the @file{~} is expanded to your
+This also edits the same file; the @file{~} is expanded to your
home directory on the remote machine, just like it is locally.
@item @trampfn{, , melancholia, ~daniel/.emacs}
by adding @file{#<port>} to the host name, like in @file{@trampfn{ssh,
daniel, melancholia#42, .emacs}}.
+Note that @value{tramp} supports only filenames encoded in unibyte.
+
@node Alternative Syntax
@section URL-like filename syntax
@itemize @w{}
@ifset emacs
-@item @code{ftp} -- That is the default syntax
-@item @code{url} -- URL-like syntax
+@item @code{ftp}---That is the default syntax
+@item @code{url}---URL-like syntax
@end ifset
@ifset xemacs
-@item @code{sep} -- That is the default syntax
-@item @code{url} -- URL-like syntax
-@item @code{ftp} -- EFS-like syntax
+@item @code{sep}---That is the default syntax
+@item @code{url}---URL-like syntax
+@item @code{ftp}---EFS-like syntax
@end ifset
@end itemize
@value{tramp} uses for analysis of completion, offer user names, those user
names will be taken into account as well.
-Remote machines, which have been visited in the past and kept
-persistently (@pxref{Connection caching}), will be offered too.
+Remote machines which have been visited in the past and kept
+persistently (@pxref{Connection caching}) will be offered too.
Once the remote machine identification is completed, it comes to
filename completion on the remote host. This works pretty much like
A remote directory might have changed its contents out of
@value{emacsname} control, for example by creation or deletion of
-files by other processes. Therefore, during filename completion the
-remote directory contents is reread regularly in order to detect such
+files by other processes. Therefore, during filename completion, the
+remote directory contents are reread regularly in order to detect such
changes, which would be invisible otherwise (@pxref{Connection caching}).
@defopt tramp-completion-reread-directory-timeout
@end defopt
+@node Ad-hoc multi-hops
+@section Declaring multiple hops in the file name
+@cindex multi-hop, ad-hoc
+@cindex proxy hosts, ad-hoc
+
+Multiple hops are configured with the variable
+@code{tramp-default-proxies-alist} (@pxref{Multi-hops}). However,
+sometimes it is desirable to reach a remote host immediately, without
+configuration changes. This can be reached by an ad-hoc specification
+of the proxies.
+
+A proxy looks like a remote file name specification without the local
+file name part. It is prepended to the target remote file name,
+separated by @samp{|}. As an example, a remote file on
+@samp{you@@remotehost}, passing the proxy @samp{bird@@bastion}, could
+be opened by
+
+@example
+@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh, you,
+@c remotehost, /path}}
+@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path}
+@end example
+
+Multiple hops can be cascaded, separating all proxies by @samp{|}.
+The proxies can also contain the patterns @code{%h} or @code{%u}.
+
+The ad-hoc definition is added on the fly to
+@code{tramp-default-proxies-alist}. Therefore, during the lifetime of
+the @value{emacsname} session it is not necessary to enter this ad-hoc
+specification, again. The remote file name @samp{@trampfn{ssh, you,
+remotehost, /path}} would be sufficient from now on.
+
+@vindex tramp-save-ad-hoc-proxies
+@defopt tramp-save-ad-hoc-proxies
+This customer option controls whether ad-hoc definitions are kept
+persistently in @code{tramp-default-proxies-alist}. That means, those
+definitions are available also for future @value{emacsname} sessions.
+@end defopt
+
+
@node Remote processes
-@section Integration with other @value{emacsname} packages.
+@section Integration with other @value{emacsname} packages
@cindex compile
@cindex recompile
@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. Association of a pty, as specified in
-@code{start-file-process}, is not supported.
+remote file names. It does not work for the @option{ftp} method.
+Association of a pty, as specified in @code{start-file-process}, is
+not supported.
+
+@code{process-file} and @code{start-file-process} work on the remote
+host when the variable @code{default-directory} is remote:
+
+@lisp
+(let ((default-directory "/ssh:remote.host:"))
+ (start-file-process "grep" (get-buffer-create "*grep*")
+ "/bin/sh" "-c" "grep -e tramp *"))
+@end lisp
@ifset emacsgvfs
If the remote host is mounted via GVFS (see @ref{GVFS based methods}),
The environment for your program can be adapted by customizing
@code{tramp-remote-process-environment}. This variable is a list of
strings. It is structured like @code{process-environment}. Each
-element is a string of the form ENVVARNAME=VALUE. An entry
-ENVVARNAME= disables the corresponding environment variable, which
-might have been set in your init file like @file{~/.profile}.
+element is a string of the form @code{"ENVVARNAME=VALUE"}. An entry
+@code{"ENVVARNAME="} disables the corresponding environment variable,
+which might have been set in your init file like @file{~/.profile}.
@noindent
Adding an entry can be performed via @code{add-to-list}:
Changing or removing an existing entry is not encouraged. The default
values are chosen for proper @value{tramp} work. Nevertheless, if for
example a paranoid system administrator disallows changing the
-@var{$HISTORY} environment variable, you can customize
+@env{HISTORY} environment variable, you can customize
@code{tramp-remote-process-environment}, or you can apply the
following code in your @file{.emacs}:
If you want to run a remote program, which shall connect the X11
server you are using with your local host, you can set the
-@var{$DISPLAY} environment variable on the remote host:
+@env{DISPLAY} environment variable on the remote host:
@lisp
(add-to-list 'tramp-remote-process-environment
that host.
-@subsection Running shell-command on a remote host
+@subsection Running @code{shell} on a remote host
+@cindex shell
+
+Calling @kbd{M-x shell} in a buffer related to a remote host runs the
+local shell as defined in @option{shell-file-name}. This might be
+also a valid path name for a shell to be applied on the remote host,
+but it will fail at least when your local and remote hosts belong to
+different system types, like @samp{windows-nt} and @samp{gnu/linux}.
+
+You must set the variable @option{explicit-shell-file-name} to the
+shell path name on the remote host, in order to start that shell on
+the remote host.
+
+@ifset emacs
+Starting with Emacs 24 this won't be necessary, if you call
+@code{shell} interactively. You will be asked for the remote shell
+path, if you are on a remote buffer, and if
+@option{explicit-shell-file-name} is equal to @code{nil}.
+@end ifset
+
+
+@subsection Running @code{shell-command} on a remote host
@cindex shell-command
@code{shell-command} allows to execute commands in a shell, either
You will see the buffer @file{*Async Shell Command*}, containing the
continuous output of the @command{tail} command.
+@ifset emacs
+A similar behaviour can be reached by @kbd{M-x auto-revert-tail-mode},
+if available.
+@end ifset
-@subsection Running eshell on a remote host
+
+@subsection Running @code{eshell} on a remote host
@cindex eshell
@value{tramp} is integrated into @file{eshell.el}. That is, you can
open an interactive shell on your remote host, and run commands there.
-After you have started @code{eshell}, you could perform commands like
-this:
+After you have started @kbd{M-x eshell}, you could perform commands
+like this:
@example
@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
absolute file names, without any remote specification.
+@subsection Running remote processes on Windows hosts
+@cindex winexe
+@cindex powershell
+
+With the help of the @command{winexe} it is possible tu run processes
+on a remote Windows host. @value{tramp} has implemented this for
+@code{process-file} and @code{start-file-process}.
+
+The variable @code{tramp-smb-winexe-program} must contain the file
+name of your local @command{winexe} command. On the remote host,
+Powershell V2.0 must be installed; it is used to run the remote
+process.
+
+In order to open a remote shell on the Windows host via @kbd{M-x
+shell}, you must set the variables @option{explicit-shell-file-name}
+and @option{explicit-*-args}. If you want, for example, run
+@command{cmd}, you must set:
+
+@lisp
+(setq explicit-shell-file-name "cmd"
+ explicit-cmd-args '("/q"))
+@end lisp
+
+@noindent
+In case of running @command{powershell} as remote shell, the settings are
+
+@lisp
+(setq explicit-shell-file-name "powershell"
+ explicit-powershell-args '("-file" "-"))
+@end lisp
+
+
@node Cleanup remote connections
-@section Cleanup remote connections.
+@section Cleanup remote connections
@cindex cleanup
Sometimes it is useful to cleanup remote connections. The following
connection buffers.
@end deffn
+@deffn Command tramp-cleanup-this-connection
+This command flushes all objects of the current buffer's remote
+connection. The same objects are removed as in
+@code{tramp-cleanup-connection}.
+@end deffn
+
@deffn Command tramp-cleanup-all-connections
This command flushes objects for all active remote connections. The
same objects are removed as in @code{tramp-cleanup-connection}.
include that with your bug report. This will make it much easier for
the development team to analyze and correct the problem.
+Sometimes, there might be also problems due to Tramp caches. Flush
+all caches before running the test, @ref{Cleanup remote connections}.
+
Before reporting the bug, you should set the verbosity level to 6
(@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and
repeat the bug. Then, include the contents of the @file{*tramp/foo*}
@item
Which systems does it work on?
-The package has been used successfully on GNU Emacs 22, GNU Emacs 23,
-XEmacs 21 (starting with 21.4), and SXEmacs 22.
+The package has been used successfully on Emacs 22, Emacs 23, Emacs
+24, 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} and
-@option{imap} methods), but some people seemed to have some success
-getting it to work on MS Windows XP/Vista/7 @value{emacsname}.
+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 XP/Vista/7 @value{emacsname}.
@item
Use caching. This is already enabled by default. Information about
the remote host as well as the remote files are cached for reuse. The
information about remote hosts is kept in the file specified in
-@code{tramp-persistency-file-name}. Keep this file.
+@code{tramp-persistency-file-name}. Keep this file. If you are
+confident that files on remote hosts are not changed out of
+@value{emacsname}' control, set @code{remote-file-name-inhibit-cache}
+to @code{nil}. Set also @code{tramp-completion-reread-directory-timeout}
+to @code{nil}, @ref{Filename completion}.
Disable version control. If you access remote files which are not
under version control, a lot of check operations can be avoided by
-disabling VC. This can be achieved by
+disabling VC@. This can be achieved by
@lisp
(setq vc-ignore-dir-regexp
reasons heading the bug mailing list:
@itemize @minus
-
@item
Unknown characters in the prompt
@value{tramp} needs to recognize the prompt on the remote machine
-after execution any command. This is not possible, when the prompt
+after execution any command. This is not possible when the prompt
contains unknown characters like escape sequences for coloring. This
should be avoided on the remote side. @xref{Remote shell setup}. for
setting the regular expression detecting the prompt.
[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
@end example
+Furthermore it has been reported, that @value{tramp} (like sshfs,
+incidentally) doesn't work with WinSSHD due to strange prompt settings.
+
@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
+such echoes via the @command{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.
@lisp
(add-hook
- 'find-file-hooks
- '(lambda ()
- (when (file-remote-p default-directory)
- (set (make-local-variable 'file-precious-flag) t))))
+ 'find-file-hook
+ (lambda ()
+ (when (file-remote-p default-directory)
+ (set (make-local-variable 'file-precious-flag) t))))
@end lisp
-
@end itemize
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,
+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
@end example
+@item
+How can I use @samp{ControlPersist}?
+
+When @samp{ControlPersist} is set to @samp{yes}, the @option{scpc}
+method does not work. You can use @option{scpx} instead with the
+following settings in @file{~/.ssh/config}:
+
+@example
+Host *
+ ControlMaster auto
+ ControlPersist yes
+@end example
+
+
@item
File name completion does not work with @value{tramp}
(setq mode-line-format
(format-mode-line mode-line-format 'font-lock-warning-face))))
-(add-hook 'find-file-hooks 'my-mode-line-function)
+(add-hook 'find-file-hook 'my-mode-line-function)
(add-hook 'dired-mode-hook 'my-mode-line-function)
@end lisp
@end ifset
(add-hook
'dired-mode-hook
- '(lambda ()
- (setq
- mode-line-buffer-identification
- my-mode-line-buffer-identification)))
+ (lambda ()
+ (setq
+ mode-line-buffer-identification
+ my-mode-line-buffer-identification)))
@end lisp
Since @value{emacsname} 23.1, the mode line contains an indication if
@lisp
(add-hook
'dired-before-readin-hook
- '(lambda ()
- (when (file-remote-p default-directory)
- (setq dired-actual-switches "-al"))))
+ (lambda ()
+ (when (file-remote-p default-directory)
+ (setq dired-actual-switches "-al"))))
@end lisp
@end ifset
The file name left to type would be
@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
-Note, that there are some useful settings already. Accessing your
+Note that there are some useful settings already. Accessing your
local host as @samp{root} user, is possible just by @kbd{C-x C-f
@trampfn{su, , ,}}.
@item Use configuration possibilities of your method:
-Several connection methods (i.e. the programs used) offer powerful
+Several connection methods (i.e., the programs used) offer powerful
configuration possibilities (@pxref{Customizing Completion}). In the
given case, this could be @file{~/.ssh/config}:
@end lisp
Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you
-are. The disadvantage is, that you cannot edit the file name, because
+are. The disadvantage is that you cannot edit the file name, because
environment variables are not expanded during editing in the
minibuffer.
'("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
@end lisp
-This shortens the file openening command to @kbd{C-x C-f /xy
+This shortens the file opening command to @kbd{C-x C-f /xy
@key{RET}}. The disadvantage is, again, that you cannot edit the file
name, because the expansion happens after entering the file name only.
(add-hook
'minibuffer-setup-hook
- '(lambda ()
- (abbrev-mode 1)
- (setq local-abbrev-table my-tramp-abbrev-table)))
+ (lambda ()
+ (abbrev-mode 1)
+ (setq local-abbrev-table my-tramp-abbrev-table)))
(defadvice minibuffer-complete
(before my-minibuffer-complete activate)
@ifset xemacs
(recent-files-initialize)
(add-hook
- 'find-file-hooks
+ 'find-file-hook
(lambda ()
(when (file-remote-p (buffer-file-name))
(recent-files-make-permanent)))
Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}.
Because BBDB is not prepared for @value{tramp} syntax, you must
-specify a method together with the user name, when needed. Example:
+specify a method together with the user name when needed. Example:
@example
@kbd{M-x bbdb-create-ftp-site @key{RET}}
@end enumerate
-I would like to thank all @value{tramp} users, who have contributed to
+I would like to thank all @value{tramp} users who have contributed to
the different recipes!
(server-start)
@end lisp
-Make sure, that the result of @code{(system-name)} can be resolved on
+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
emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1}
@end example
-Then you must set the environment variable @code{EDITOR} pointing to
+Then you must set the environment variable @env{EDITOR} pointing to
that script:
@example
@item
-How can I disable @value{tramp}?
+There are packages which call @value{tramp} although I haven't entered
+a remote file name ever. I dislike it, how could I disable it?
-Shame on you, why did you read until now?
+In general, @value{tramp} functions are used only when
+you apply remote file name syntax. However, some packages enable
+@value{tramp} on their own.
@itemize @minus
+@item
+@file{ido.el}
+
+You could disable @value{tramp} file name completion:
+
+@lisp
+(custom-set-variables
+ '(ido-enable-tramp-completion nil))
+@end lisp
@item
+@file{rlogin.el}
+
+You could disable remote directory tracking mode:
+
+@lisp
+(rlogin-directory-tracking-mode -1)
+@end lisp
+@end itemize
+
+
+@item
+How can I disable @value{tramp} at all?
+
+Shame on you, why did you read until now?
+
+@itemize @minus
@ifset emacs
+@item
If you just want to have @value{ftppackagename} as default remote
files access package, you should apply the following code:
@node Localname deconstruction
-@section Breaking a localname into its components.
+@section Breaking a localname into its components
@value{tramp} file names are somewhat different, obviously, to ordinary file
names. As such, the lisp functions @code{file-name-directory} and
@ifset emacs
@node External packages
-@section Integration with external Lisp packages.
+@section Integration with external Lisp packages
@subsection Filename completion.
While reading filenames in the minibuffer, @value{tramp} must decide
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
+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.
When @code{tramp-verbose} is greater than or equal to 4, the messages
are also written into a @value{tramp} debug buffer. This debug buffer
-is useful for analysing problems; sending a @value{tramp} bug report
+is useful for analyzing problems; sending a @value{tramp} bug report
should be done with @code{tramp-verbose} set to a verbosity level of at
least 6 (@pxref{Bug Reports}).
But I have decided that this is too fragile to reliably work, so on some
systems you'll have to do without the uuencode methods.
-@item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs.
+@item The @value{tramp} filename syntax differs between Emacs and XEmacs.
-The GNU Emacs maintainers wish to use a unified filename syntax for
+The Emacs maintainers wish to use a unified filename syntax for
Ange-FTP and @value{tramp} so that users don't have to learn a new
syntax. It is sufficient to learn some extensions to the old syntax.
@c host and then send commands to it.
@c * Use `filename' resp. `file name' consistently.
@c * Use `host' resp. `machine' consistently.
-@c * Consistent small or capitalized words especially in menues.
-
-@ignore
- arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808
-@end ignore
+@c * Consistent small or capitalized words especially in menus.