@setfilename ../../info/tramp
@c %**start of header
@settitle TRAMP User Manual
+@documentencoding UTF-8
@c %**end of header
@c This is *so* much nicer :)
@include trampver.texi
-@c Macro for formatting a filename according to the respective syntax.
+@c Macro for formatting a file name according to the respective syntax.
@c xxx and yyy are auxiliary macros in order to omit leading and
@c trailing whitespace. Not very elegant, but I don't know it better.
+@c There are subtle differences between texinfo 4.13 and 5.0. We must
+@c declare two versions of the macro. This will be improved, hopefully.
+
+@c Texinfo 5.0.
+@ifset txicommandconditionals
+@macro xxx {one}
+@set \one\
+@end macro
+
+@macro yyy {one, two}
+@xxx{x\one\}@c
+@ifclear x
+\one\@w{}\two\@c
+@end ifclear
+@clear x\one\
+@end macro
+
+@macro trampfn {method, user, host, localname}
+@value{prefix}@c
+@yyy{\method\,@value{postfixhop}}@c
+@yyy{\user\,@@}@c
+\host\@value{postfix}\localname\
+@end macro
+@end ifset
+
+@c Texinfo 4.13.
+@ifclear txicommandconditionals
@macro xxx {one}@c
@set \one\@c
@end macro
@macro trampfn {method, user, host, localname}@c
@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
@end macro
+@end ifclear
@copying
-Copyright @copyright{} 1999--2013 Free Software Foundation, Inc.
+Copyright @copyright{} 1999--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@dircategory @value{emacsname} network features
@direntry
* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
- @value{emacsname} remote file access via rsh and rcp.
+ @value{emacsname} remote file access via ssh and scp.
@end direntry
@titlepage
* Usage:: An overview of the operation of @value{tramp}.
* Bug Reports:: Reporting Bugs and Problems.
* Frequently Asked Questions:: Questions and answers from the mailing list.
-* Function Index:: @value{tramp} functions.
-* Variable Index:: User options and variables.
-* Concept Index:: An item for each concept.
For the developer:
* Issues:: Debatable Issues and What Was Decided.
* GNU Free Documentation License:: The license for this documentation.
+* Function Index:: @value{tramp} functions.
+* Variable Index:: User options and variables.
+* Concept Index:: An item for each concept.
@detailmenu
--- The Detailed Node Listing ---
Configuring @value{tramp} for use
-* Connection types:: Types of connections made to remote machines.
+* Connection types:: Types of connections made to remote hosts.
* Inline methods:: Inline methods.
* External methods:: External methods.
@ifset emacsgvfs
* Customizing Completion:: Selecting config files for user/host name completion.
* 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.
+* Predefined connection information::
+ Setting own connection related information.
+* Remote Programs:: How @value{tramp} finds and uses programs on the remote host.
* Remote shell setup:: Remote shell setup hints.
-* Windows setup hints:: Issues with Cygwin ssh.
+* Android shell setup:: Android shell setup hints.
* Auto-save and Backup:: Auto-save and Backup.
+* Windows setup hints:: Issues with Cygwin ssh.
Using @value{tramp}
-* Filename Syntax:: @value{tramp} filename conventions.
-* Alternative Syntax:: URL-like filename syntax.
-* Filename completion:: Filename completion.
+* File name Syntax:: @value{tramp} file name conventions.
+* File name completion:: File name 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 detailmenu
@end menu
+
@node Overview
@chapter An overview of @value{tramp}
@cindex overview
After the installation of @value{tramp} into your @value{emacsname}, you
-will be able to access files on remote machines as though they were
+will be able to access files on remote hosts as though they were
local. Access to the remote file system for editing files, version
control, and @code{dired} are transparently enabled.
-Your access to the remote machine can be with the @command{rsh},
+Your access to the remote host can be with the @command{rsh},
@command{rlogin}, @command{telnet} programs or with any similar
connection method. This connection must pass @acronym{ASCII}
successfully to be usable but need not be 8-bit clean.
The package provides support for @command{ssh} connections out of the
box, one of the more common uses of the package. This allows
-relatively secure access to machines, especially if @command{ftp}
+relatively secure access to hosts, especially if @command{ftp}
access is disabled.
Under Windows, @value{tramp} is integrated with the PuTTY package,
The majority of activity carried out by @value{tramp} requires only that
the remote login is possible and is carried out at the terminal. In
order to access remote files @value{tramp} needs to transfer their content
-to the local machine temporarily.
+to the local host temporarily.
-@value{tramp} can transfer files between the machines in a variety of ways.
+@value{tramp} can transfer files between the hosts in a variety of ways.
The details are easy to select, depending on your needs and the
-machines in question.
+hosts in question.
The fastest transfer methods for large files rely on a remote file
transfer package such as @command{rcp}, @command{scp}, @command{rsync}
If the remote copy methods are not suitable for you, @value{tramp} also
supports the use of encoded transfers directly through the shell.
This requires that the @command{mimencode} or @command{uuencode} tools
-are available on the remote machine. These methods are generally
+are available on the remote host. These methods are generally
faster for small files.
@value{tramp} is still under active development and any problems you encounter,
@item
Now the remote shell is up and it good working order. Remember, what
was supposed to happen is that @value{tramp} tries to find out what files exist
-on the remote host so that it can do filename completion.
+on the remote host so that it can do file name completion.
So, @value{tramp} basically issues @command{cd} and @command{ls} commands and
also sometimes @command{echo} with globbing. Another command that is
necessary operation.
@item
-Suppose you are finished with filename completion, have entered @kbd{C-x
+Suppose you are finished with file name completion, have entered @kbd{C-x
C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to
transfer the file contents from the remote host to the local host so
that you can edit them.
file contents were added. Support for VC was added.
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.
+the unification of @value{tramp} and Ange-FTP file names 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
@include trampinst.texi
@end ifset
+
@node Configuration
@chapter Configuring @value{tramp} for use
@cindex configuration
@value{tramp} is (normally) fully functional when it is initially
installed. It is initially configured to use the @command{scp}
program to connect to the remote host. So in the easiest case, you
-just type @kbd{C-x C-f} and then enter the filename
-@file{@trampfn{, user, machine, /path/to.file}}.
+just type @kbd{C-x C-f} and then enter the file name
+@file{@trampfn{, user, host, /path/to.file}}.
On some hosts, there are problems with opening a connection. These are
related to the behavior of the remote shell. See @xref{Remote shell
If you do not wish to use these commands to connect to the remote
host, you should change the default connection and transfer method
that @value{tramp} uses. There are several different methods that @value{tramp}
-can use to connect to remote machines and transfer files
+can use to connect to remote hosts and transfer files
(@pxref{Connection types}).
If you don't know which method is right for you, see @xref{Default
@menu
-* Connection types:: Types of connections made to remote machines.
+* Connection types:: Types of connections made to remote hosts.
* Inline methods:: Inline methods.
* External methods:: External methods.
@ifset emacsgvfs
* Customizing Completion:: Selecting config files for user/host name completion.
* 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.
+* Predefined connection information::
+ Setting own connection related information.
+* Remote Programs:: How @value{tramp} finds and uses programs on the remote host.
* Remote shell setup:: Remote shell setup hints.
+* Android shell setup:: Android shell setup hints.
* 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 hosts
@cindex connection types, overview
There are two basic types of transfer methods, each with its own
advantages and limitations. Both types of connection make use of a
remote shell access program such as @command{rsh}, @command{ssh} or
-@command{telnet} to connect to the remote machine.
+@command{telnet} to connect to the remote host.
This connection is used to perform many of the operations that @value{tramp}
requires to make the remote file system transparently accessible from
-the local machine. It is only when visiting files that the methods
+the local host. It is only when visiting files that the methods
differ.
@cindex inline methods
@cindex methods, inline
@cindex methods, external
Loading or saving a remote file requires that the content of the file
-be transferred between the two machines. The content of the file can
+be transferred between the two hosts. 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
+the same connection used to log in to the remote host, or the
@dfn{external method} through another connection using a remote copy
program such as @command{rcp}, @command{scp} or @command{rsync}.
External methods should be configured such a way that they don't
require a password (with @command{ssh-agent}, or such alike). Modern
@command{scp} implementations offer options to reuse existing
-@command{ssh} connections, see method @command{scpc}. If it isn't
-possible, you should consider @ref{Password handling}, otherwise you
-will be prompted for a password every copy action.
+@command{ssh} connections, which will be enabled by default if
+available. If it isn't possible, you should consider @ref{Password
+handling}, otherwise you will be prompted for a password every copy
+action.
@node Inline methods
The inline methods in @value{tramp} are quite powerful and can work in
situations where you cannot use an external transfer program to connect.
Inline methods are the only methods that work when connecting to the
-remote machine via telnet. (There are also strange inline methods which
+remote host via telnet. (There are also strange inline methods which
allow you to transfer files between @emph{user identities} rather than
hosts, see below.)
These methods depend on the existence of a suitable encoding and
-decoding command on remote machine. Locally, @value{tramp} may be able to
+decoding command on remote host. Locally, @value{tramp} may be able to
use features of @value{emacsname} to decode and encode the files or
it may require access to external commands to perform that task.
the previous option except that the @command{ssh} package is used,
making the connection more secure.
-There are also two variants, @option{ssh1} and @option{ssh2}, that
-call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
-explicitly select whether you want to use the SSH protocol version 1
-or 2 to connect to the remote host. (You can also specify in
-@file{~/.ssh/config}, the SSH configuration file, which protocol
-should be used, and use the regular @option{ssh} method.)
-
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
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
-order to use SSH protocol version 1 or 2 explicitly.
-
-CCC: Do we have to connect to the remote host once from the command
-line to accept the SSH key? Maybe this can be made automatic?
-
-CCC: Say something about the first shell command failing. This might
-be due to a wrong setting of @code{tramp-rsh-end-of-line}.
-
@item @option{plinkx}
@cindex method plinkx
@cindex rsh (with rcp method)
This method uses the @command{rsh} and @command{rcp} commands to connect
-to the remote machine and transfer files. This is probably the fastest
+to the remote host and transfer files. This is probably the fastest
connection method available.
The alternative method @option{remcp} uses the @command{remsh} and
-@command{rcp} commands. It should be applied on machines where
+@command{rcp} commands. It should be applied on hosts where
@command{remsh} is used instead of @command{rsh}.
@cindex ssh (with scp method)
Using @command{ssh} to connect to the remote host and @command{scp} to
-transfer files between the machines is the best method for securely
-connecting to a remote machine and accessing files.
+transfer files between the hosts is the best method for securely
+connecting to a remote host and accessing files.
The performance of this option is also quite good. It may be slower than
the inline methods when you often open and close small files however.
session can begin to absorb the advantage that the lack of encoding and
decoding presents.
-There are also two variants, @option{scp1} and @option{scp2}, that
-call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
-explicitly select whether you want to use the SSH protocol version 1
-or 2 to connect to the remote host. (You can also specify in
-@file{~/.ssh/config}, the SSH configuration file, which protocol
-should be used, and use the regular @option{scp} method.)
-
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
@cindex ssh (with rsync method)
Using the @command{ssh} command to connect securely to the remote
-machine and the @command{rsync} command to transfer files is almost
+host and the @command{rsync} command to transfer files is almost
identical to the @option{scp} method.
While @command{rsync} performs much better than @command{scp} when
This method supports the @samp{-p} argument.
-@item @option{scpc}---@command{ssh} and @command{scp}
-@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
-@option{ssh} channel, which increases performance.
-
-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 /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}
-@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}
@cindex method pscp
@cindex pscp method
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}.
+This works only for unified file names, see @ref{Issues}.
@end ifset
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 machine @code{melancholia} as user @code{daniel} of the domain
+the host @code{melancholia} as user @code{daniel} of the domain
@code{BIZARRE}, and edit @file{.emacs} in the home directory (share
-@code{daniel$}) I would specify the filename @file{@trampfn{smb,
+@code{daniel$}) I would specify the file name @file{@trampfn{smb,
daniel%BIZARRE, melancholia, /daniel$$/.emacs}}.
Depending on the Windows domain configuration, a Windows user might be
considered as domain user per default. In order to connect as local
-user, the WINS name of that machine must be given as domain name.
-Usually, it is the machine name in capital letters. In the example
+user, the WINS name of that host must be given as domain name.
+Usually, it is the host name in capital letters. In the example
above, the local user @code{daniel} would be specified as
@file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}.
@cindex method adb
@cindex adb method
-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.
+This special method uses the Android Debug Bridge for accessing
+Android devices. The Android Debug Bridge must be installed locally.
+Some GNU/Linux distributions offer it for installation, otherwise it
+can be installed as part of the Android SDK. If the @command{adb}
+program is not found via the @env{PATH} environment variable, the
+variable @var{tramp-adb-program} must point to its absolute path.
+
+Tramp does not connect Android devices to @command{adb}. This must be
+performed outside @value{emacsname}. If there is exactly one Android
+device connected to @command{adb}, a host name is not needed in the
+remote file name. The default @value{tramp} name to be used is
+@file{@trampfn{adb, , ,}} therefore. Otherwise, one could find
+potential host names with the command @command{adb devices}.
+
+Usually, the @command{adb} method does not need any user name. It
+runs under the permissions of the @command{adbd} process on the
+Android device. If a user name is specified, @value{tramp} applies an
+@command{su} on the device. This does not work with all Android
+devices, especially with unrooted ones. In that case, an error
+message is displayed.
@end table
method for all user names matching @samp{john} and the @option{rsync}
method for all host names matching @samp{lily}. The third line
specifies to use the @option{su} method for the user @samp{root} on
-the machine @samp{localhost}.
+the host @samp{localhost}.
@lisp
(add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
Internet, the security implications of your preferred method.
The @option{rsh} and @option{telnet} methods send your password as
-plain text as you log in to the remote machine, as well as
+plain text as you log in to the remote host, as well as
transferring the files in such a way that the content can easily be
-read from other machines.
+read from other hosts.
If you need to connect to remote systems that are accessible from the
Internet, you should give serious thought to using @option{ssh} based
compression (driven by @var{tramp-inline-compress-start-size}) shall
still result in good performance.
-I guess that these days, most people can access a remote machine by
+I guess that these days, most people can access a remote host by
using @command{ssh}. So I suggest that you use the @option{ssh}
method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost,
/etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other
shortened syntax for the @samp{root} account, like
@file{@trampfn{su, , , /etc/motd}}.
-People who edit large files may want to consider @option{scpc} instead
+People who edit large files may want to consider @option{scp} instead
of @option{ssh}, or @option{pscp} instead of @option{plink}. These
external methods are faster than inline methods for large files.
Note, however, that external methods suffer from some limitations.
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,
+methods, like @option{adb}, that default value must be overwritten,
which is already the initial value of @code{tramp-default-host-alist}.
@noindent
@var{host} and @var{user} are regular expressions or @code{nil}, which
is interpreted as a regular expression which always matches.
-@var{proxy} must be a Tramp filename which localname part is ignored.
+@var{proxy} must be a Tramp file name which localname part is ignored.
Method and user name on @var{proxy} are optional, which is interpreted
with the default values.
@ifset emacsgw
The variable @code{tramp-completion-function-alist} is intended to
customize which files are taken into account for user and host name
-completion (@pxref{Filename completion}). For every method, it keeps
+completion (@pxref{File name completion}). For every method, it keeps
a set of configuration files, accompanied by a Lisp function able to
parse that file. Entries in @code{tramp-completion-function-alist}
have the form (@var{method} @var{pair1} @var{pair2} ...).
connection again.
+@node Predefined connection information
+@section Setting own connection related information
+
+Sometimes, @var{tramp} is not able to detect correct connection
+related information. In such cases, you could tell @var{tramp} which
+value it has to take. Since this could result in errors, it has to be
+used with care.
+
+@vindex tramp-connection-properties
+Such settings can be performed via the list
+@code{tramp-connection-properties}. An entry in this list has the
+form @code{(@var{regexp} @var{property} @var{value})}. @var{regexp}
+matches remote file names for which a property shall be predefined.
+It can be @code{nil}. @var{property} is a string, and @var{value} the
+corresponding value. @var{property} could be any property found in
+the file @code{tramp-persistency-file-name}.
+
+A special property is @code{"busybox"}. This must be set, if the
+remote host runs a very restricted busybox as shell, which closes the
+connection at will. Since there is no reliable test for this,
+@var{tramp} must be indicated this way. Example:
+
+@lisp
+(add-to-list 'tramp-connection-properties
+ (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
+ "busybox" t))
+@end lisp
+
+
@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 host
@value{tramp} depends on a number of programs on the remote host in order to
function, including @command{ls}, @command{test}, @command{find} and
@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
+When @value{tramp} connects to the remote host, it searches for the
programs that it can use. The variable @code{tramp-remote-path}
-controls the directories searched on the remote machine.
+controls the directories searched on the remote host.
By default, this is set to a reasonable set of defaults for most
-machines. The symbol @code{tramp-default-remote-path} is a place
+hosts. 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,
+command @command{getconf PATH} on your remote host. For example,
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
@var{tramp-password-prompt-regexp} handles the detection of such
requests for English environments. When you use another localization
-of your (local or remote) host, you might need to adapt this. Example:
+of your (local or remote) host, you might need to adapt this. Example:
@lisp
(setq
@end table
+@node Android shell setup
+@section Android shell setup hints
+@cindex android shell setup
+
+Android devices use a restricted shell. They can be accessed via the
+@option{adb} method. However, this restricts the access to a USB
+connection, and it requires the installation of the Android SDK on the
+local host.
+
+When an @command{sshd} process runs on the Android device, like
+provided by the @code{SSHDroid} app, any @option{ssh}-based method can
+be used. This requires some special settings.
+
+The default shell @code{/bin/sh} does not exist. Instead, you shall
+use just @code{sh}, which invokes the shell installed on the device.
+You can instruct @value{tramp} by this form:
+
+@lisp
+(add-to-list 'tramp-connection-properties
+ (list (regexp-quote "192.168.0.26") "remote-shell" "sh"))
+@end lisp
+
+@noindent
+with @samp{192.168.0.26} being the IP address of your Android device
+(@pxref{Predefined connection information}).
+
+The user settings for the @env{PATH} environment variable must be
+preserved. It has also been reported, that the commands in
+@file{/system/xbin} are better suited than the ones in
+@file{/system/bin}. Add these setting:
+
+@lisp
+(add-to-list 'tramp-remote-path 'tramp-own-remote-path)
+(add-to-list 'tramp-remote-path "/system/xbin")
+@end lisp
+
+@noindent
+If the Android device is not @samp{rooted}, you must give the shell a
+writable directory for temporary files:
+
+@lisp
+(add-to-list 'tramp-remote-process-environment "TMPDIR=$HOME")
+@end lisp
+
+@noindent
+Now you shall be able to open a remote connection with @kbd{C-x C-f
+@trampfn{ssh, , 192.168.0.26#2222, }}, given that @command{sshd}
+listens on port @samp{2222}.
+
+It is also recommended to add a corresponding entry to your
+@file{~/.ssh/config} for that connection, like
+
+@example
+Host android
+ HostName 192.168.0.26
+ User root
+ Port 2222
+@end example
+
+@noindent
+In this case, you must change the setting for the remote shell to
+
+@lisp
+(add-to-list 'tramp-connection-properties
+ (list (regexp-quote "android") "remote-shell" "sh"))
+@end lisp
+
+@noindent
+You would open the connection with @kbd{C-x C-f @trampfn{ssh, ,
+android, }} then.
+
+
@node Auto-save and Backup
@section Auto-save and Backup configuration
@cindex auto-save
@cindex sshx method with Cygwin
The recent Cygwin installation of @command{ssh} works only with a
Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x
-eshell}, and starting @kbd{ssh test.machine}. The problem is evident
+eshell}, and starting @kbd{ssh test.host}. The problem is evident
if you see a message like this:
@example
@cindex scpx method with Cygwin
If you wish to use the @option{scpx} connection method, then you might
have the problem that @value{emacsname} calls @command{scp} with a
-Windows filename such as @code{c:/foo}. The Cygwin version of
-@command{scp} does not know about Windows filenames and interprets
-this as a remote filename on the host @code{c}.
+Windows file name such as @code{c:/foo}. The Cygwin version of
+@command{scp} does not know about Windows file names and interprets
+this as a remote file name on the host @code{c}.
One possible workaround is to write a wrapper script for @option{scp}
-which converts the Windows filename to a Cygwinized filename.
+which converts the Windows file name to a Cygwinized file name.
@cindex Cygwin and ssh-agent
@cindex SSH_AUTH_SOCK and @value{emacsname} on Windows
@cindex using @value{tramp}
Once you have installed @value{tramp} it will operate fairly
-transparently. You will be able to access files on any remote machine
+transparently. You will be able to access files on any remote host
that you can log in to as though they were local.
Files are specified to @value{tramp} using a formalized syntax specifying the
minute you have already forgotten that you hit that key!
@menu
-* Filename Syntax:: @value{tramp} filename conventions.
-* Alternative Syntax:: URL-like filename syntax.
-* Filename completion:: Filename completion.
+* File name Syntax:: @value{tramp} file name conventions.
+* File name completion:: File name 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
-@node Filename Syntax
-@section @value{tramp} filename conventions
-@cindex filename syntax
-@cindex filename examples
+@node File name Syntax
+@section @value{tramp} file name conventions
+@cindex file name syntax
+@cindex file name examples
-To access the file @var{localname} on the remote machine @var{machine}
-you would specify the filename @file{@trampfn{, , machine,
-localname}}. This will connect to @var{machine} and transfer the file
+To access the file @var{localname} on the remote host @var{host}
+you would specify the file name @file{@trampfn{, , host,
+localname}}. This will connect to @var{host} and transfer the file
using the default method. @xref{Default Method}.
-Some examples of @value{tramp} filenames are shown below.
+Some examples of @value{tramp} file names are shown below.
@table @file
-@item @trampfn{, , melancholia, .emacs}
-Edit the file @file{.emacs} in your home directory on the machine
+@item @value{prefix}melancholia@value{postfix}.emacs
+Edit the file @file{.emacs} in your home directory on the host
@code{melancholia}.
-@item @trampfn{, , melancholia.danann.net, .emacs}
+@item @value{prefix}melancholia.danann.net@value{postfix}.emacs
This edits the same file, using the fully qualified domain name of
-the machine.
+the host.
-@item @trampfn{, , melancholia, ~/.emacs}
+@item @value{prefix}melancholia@value{postfix}~/.emacs
This also edits the same file; the @file{~} is expanded to your
-home directory on the remote machine, just like it is locally.
+home directory on the remote host, just like it is locally.
-@item @trampfn{, , melancholia, ~daniel/.emacs}
+@item @value{prefix}melancholia@value{postfix}~daniel/.emacs
This edits the file @file{.emacs} in the home directory of the user
-@code{daniel} on the machine @code{melancholia}. The @file{~<user>}
+@code{daniel} on the host @code{melancholia}. The @file{~<user>}
construct is expanded to the home directory of that user on the remote
-machine.
+host.
-@item @trampfn{, , melancholia, /etc/squid.conf}
-This edits the file @file{/etc/squid.conf} on the machine
+@item @value{prefix}melancholia@value{postfix}/etc/squid.conf
+This edits the file @file{/etc/squid.conf} on the host
@code{melancholia}.
@end table
-@var{machine} can also be an IPv4 or IPv6 address, like in
+@var{host} 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
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
-part of the filename.
+part of the file name.
-To log in to the remote machine as a specific user, you use the syntax
-@file{@trampfn{, user, machine, path/to.file}}. That means that
+To log in to the remote host as a specific user, you use the syntax
+@file{@trampfn{, user, host, path/to.file}}. That means that
connecting to @code{melancholia} as @code{daniel} and editing
@file{.emacs} in your home directory you would specify
@file{@trampfn{, daniel, melancholia, .emacs}}.
It is also possible to specify other file transfer methods
(@pxref{Inline methods}, @pxref{External methods}) as part of the
-filename.
+file name.
@ifset emacs
This is done by putting the method before the user and host name, as
in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the
@file{@value{prefix}<method>@value{postfixhop}}. (Note the trailing
slash!).
@end ifset
-The user, machine and file specification remain the same.
+The user, host and file specification remain the same.
-So, to connect to the machine @code{melancholia} as @code{daniel},
+So, to connect to the host @code{melancholia} as @code{daniel},
using the @option{ssh} method to transfer files, and edit
-@file{.emacs} in my home directory I would specify the filename
+@file{.emacs} in my home directory I would specify the file name
@file{@trampfn{ssh, daniel, melancholia, .emacs}}.
+@ifset emacs
+A remote file name containing a host name only, which is equal to a
+method name, is not allowed. If such a host name is used, it must
+always be preceded by an explicit method name, like
+@file{@value{prefix}ssh@value{postfixhop}ssh@value{postfix}}.
+@end ifset
+
Finally, for some methods it is possible to specify a different port
number than the default one, given by the method. This is specified
by adding @file{#<port>} to the host name, like in @file{@trampfn{ssh,
daniel, melancholia#42, .emacs}}.
-Note that @value{tramp} supports only filenames encoded in unibyte.
-
-@node Alternative Syntax
-@section URL-like filename syntax
-@cindex filename syntax
-@cindex filename examples
+@node File name completion
+@section File name completion
+@cindex file name completion
-Additionally to the syntax described in the previous chapter, it is
-possible to use a URL-like syntax for @value{tramp}. This can be
-switched on by customizing the variable @code{tramp-syntax}. Please
-note that this feature is experimental for the time being.
-
-The variable @code{tramp-syntax} must be set before requiring @value{tramp}:
-
-@lisp
-(setq tramp-syntax 'url)
-(require 'tramp)
-@end lisp
-
-Then, a @value{tramp} filename would look like this:
-@file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}.
-@file{/@var{method}://} is mandatory, all other parts are optional.
-@file{:@var{port}} is useful for methods only who support this.
-
-The last example from the previous section would look like this:
-@file{/ssh://daniel@@melancholia/.emacs}.
-
-For the time being, @code{tramp-syntax} can have the following values:
-
-@itemize @w{}
-@ifset emacs
-@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
-@end ifset
-@end itemize
-
-
-@node Filename completion
-@section Filename completion
-@cindex filename completion
-
-Filename completion works with @value{tramp} for completion of method
-names, of user names and of machine names as well as for completion of
-file names on remote machines.
+File name completion works with @value{tramp} for completion of method
+names, of user names and of host names as well as for completion of
+file names on remote hosts.
@ifset emacs
In order to enable this, partial completion must be activated in your
@file{.emacs}.
@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,}}
+@c @multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
+@multitable @columnfractions .5 .5
@ifset emacs
@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/
@item @value{prefixhop}toto@value{postfix} @tab
@samp{@value{prefixhop}telnet@value{postfixhop}}
is a possible completion for the respective method,
@ifset emacs
-@samp{tmp/} stands for the directory @file{/tmp} on your local
-machine,
+@samp{tmp/} stands for the directory @file{/tmp} on your local host,
@end ifset
and @samp{@value{prefixhop}toto@value{postfix}}
might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts}
If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to
@samp{@value{prefix}telnet@value{postfixhop}}.
-Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in
+Next @kbd{@key{TAB}} brings you all host names @value{tramp} detects in
your @file{/etc/hosts} file, let's say
@example
-@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
+@multitable @columnfractions .5 .5
+@c @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
-complete file names on that machine.
+Now you can choose the desired host, and you can continue to
+complete file names on that host.
If the configuration files (@pxref{Customizing Completion}), which
@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
+Remote hosts 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
+Once the remote host identification is completed, it comes to
+file name completion on the remote host. This works pretty much like
for files on the local host, with the exception that minibuffer
-killing via a double-slash works only on the filename part, except
-that filename part starts with @file{//}.
+killing via a double-slash works only on the file name part, except
+that file name part starts with @file{//}.
@ifset emacs
A triple-slash stands for the default behavior.
@end ifset
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
+files by other processes. Therefore, during file name 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
This variable defines the number of seconds since last remote command
before rereading a directory contents. A value of 0 would require an
-immediate reread during filename completion, @code{nil} means to use
+immediate reread during file name completion, @code{nil} means to use
always cached values for the directory contents.
@end defopt
@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
+remote processes; all processes run still locally on your host with
an adapted @code{default-directory}. This section does not apply for
such connection methods.
@end ifset
this is welcome!
When your program is not found in the default search path
-@value{tramp} sets on the remote machine, you should either use an
+@value{tramp} sets on the remote host, you should either use an
absolute path, or extend @code{tramp-remote-path} (see @ref{Remote
Programs}):
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,
+also a valid file 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
+shell file 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
+file name, if you are on a remote buffer, and if
@option{explicit-shell-file-name} is equal to @code{nil}.
@end ifset
continuous output of the @command{tail} command.
@ifset emacs
-A similar behaviour can be reached by @kbd{M-x auto-revert-tail-mode},
+A similar behavior can be reached by @kbd{M-x auto-revert-tail-mode},
if available.
@end ifset
@uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/,
the @value{tramp} Mail Subscription Page}.
+@ifset emacs
+@ifset installchapter
+Before sending a bug report, you could check whether @value{tramp}
+works at all. Run the test suite on your local host, @ref{Testing}.
+@end ifset
+@end ifset
+
@findex tramp-bug
To report a bug in @value{tramp}, you should execute @kbd{M-x
tramp-bug}. This will automatically generate a buffer with the details
When submitting a bug report, please try to describe in excruciating
detail the steps required to reproduce the problem, the setup of the
-remote machine and any special conditions that exist. You should also
+remote host and any special conditions that exist. You should also
check that your problem is not described already in @xref{Frequently
Asked Questions}.
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 method, like @option{scpc}.
+Use an external method, like @option{scp}.
Use caching. This is already enabled by default. Information about
the remote host as well as the remote files are cached for reuse. The
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}.
+to @code{nil}, @ref{File name completion}.
Disable version control. If you access remote files which are not
under version control, a lot of check operations can be avoided by
@item
Unknown characters in the prompt
-@value{tramp} needs to recognize the prompt on the remote machine
+@value{tramp} needs to recognize the prompt on the remote host
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
@item
Echoed characters after login
-When the remote machine opens an echoing shell, there might be control
+When the remote host opens an echoing shell, there might be control
characters in the welcome message. @value{tramp} tries to suppress
such echoes via the @command{stty -echo} command, but sometimes this
command is not reached, because the echoed output has confused
@item
-How can I use @samp{ControlPersist}?
+@value{tramp} does not use my @command{ssh} @code{ControlPath}
+
+Your @code{ControlPath} setting will be overwritten by @command{ssh}
+sessions initiated by @value{tramp}. This is because a master
+session, initiated outside @value{emacsname}, could be closed, which
+would stall all other @command{ssh} sessions for that host inside
+@value{emacsname}.
+
+Consequently, if you connect to a remote host via @value{tramp}, you
+might be prompted for a password again, even if you have established
+already an @command{ssh} connection to that host. Further
+@value{tramp} connections to that host, for example in order to run a
+process on that host, will reuse that initial @command{ssh}
+connection.
+
+If your @command{ssh} version supports the @code{ControlPersist}
+option, you could customize the variable
+@code{tramp-ssh-controlmaster-options} to use your @code{ControlPath},
+for example:
-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}:
+@lisp
+(setq tramp-ssh-controlmaster-options
+ (concat
+ "-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p "
+ "-o ControlMaster=auto -o ControlPersist=yes"))
+@end lisp
-@example
-Host *
- ControlMaster auto
- ControlPersist yes
-@end example
+Note, that "%r", "%h" and "%p" must be encoded as "%%r", "%%h" and
+"%%p", respectively.
+
+These settings can be suppressed, if they are configured properly in
+your @file{~/.ssh/config}:
+
+@lisp
+(setq tramp-use-ssh-controlmaster-options nil)
+@end lisp
@item
File name completion does not work with @value{tramp}
-When you log in to the remote machine, do you see the output of
+When you log in to the remote host, do you see the output of
@command{ls} in color? If so, this may be the cause of your problems.
@command{ls} outputs @acronym{ANSI} escape sequences that your terminal
confuse @value{tramp} however.
In your @file{.bashrc}, @file{.profile} or equivalent on the remote
-machine you probably have an alias configured that adds the option
+host you probably have an alias configured that adds the option
@option{--color=yes} or @option{--color=auto}.
You should remove that alias and ensure that a new login @emph{does not}
display the output of @command{ls} in color. If you still cannot use
-filename completion, report a bug to the @value{tramp} developers.
+file name completion, report a bug to the @value{tramp} developers.
@item
package.
Their replacements are reasonably simplistic in their approach. They
-dissect the filename, call the original handler on the localname and
+dissect the file name, call the original handler on the localname and
then rebuild the @value{tramp} file name with the result.
This allows the platform specific hacks in the original handlers to take
@ifset emacs
@node External packages
@section Integration with external Lisp packages
-@subsection Filename completion.
+@subsection File name completion.
-While reading filenames in the minibuffer, @value{tramp} must decide
-whether it completes possible incomplete filenames, or not. Imagine
+While reading file names in the minibuffer, @value{tramp} must decide
+whether it completes possible incomplete file names, or not. Imagine
there is the following situation: You have typed @kbd{C-x C-f
@value{prefix}ssh@value{postfixhop} @key{TAB}}. @value{tramp} cannot
know, whether @option{ssh} is a method or a host name. It checks
therefore the last input character you have typed. If this is
@key{TAB}, @key{SPACE} or @kbd{?}, @value{tramp} assumes that you are
-still in filename completion, and it does not connect to the possible
+still in file name completion, and it does not connect to the possible
remote host @option{ssh}.
-@vindex tramp-completion-mode
-External packages, which use other characters for completing filenames
+External packages, which use other characters for completing file names
in the minibuffer, must signal this to @value{tramp}. For this case,
-the variable @code{tramp-completion-mode} can be bound temporarily to
+the variable @code{non-essential} can be bound temporarily to
a non-@code{nil} value.
@lisp
-(let ((tramp-completion-mode t))
+(let ((non-essential t))
...)
@end lisp
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 where 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.
+should let-bind the variable @code{process-file-side-effects} to
+@code{nil}. Then @value{tramp} won't flush the file attributes cache.
@lisp
(let (process-file-side-effects)
For asynchronous processes, @value{tramp} flushes the file attributes
cache via a process sentinel. If the caller of
@code{start-file-process} knows that there are no file attribute
-changes, it shall set the process sentinel to @code{nil}. In case the
-caller defines an own process sentinel, @value{tramp}'s process
+changes, it should set the process sentinel to the default. In cases
+where the caller defines its own process sentinel, @value{tramp}'s process
sentinel is overwritten. The caller can still flush the file
attributes cache in its process sentinel with this code:
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 Emacs and XEmacs.
+@item The @value{tramp} file name syntax differs between Emacs and XEmacs.
-The Emacs maintainers wish to use a unified filename syntax for
+The Emacs maintainers wish to use a unified file name 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.
For the XEmacs maintainers, the problems caused from using a unified
-filename syntax are greater than the gains. The XEmacs package system
+file name syntax are greater than the gains. The XEmacs package system
uses EFS for downloading new packages. So, obviously, EFS has to be
-installed from the start. If the filenames were unified, @value{tramp}
+installed from the start. If the file names were unified, @value{tramp}
would have to be installed from the start, too.
@ifset xemacs
disabled. This can be achieved by setting file permissions @code{000}
to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}.
-In case of unified filenames, all @value{emacsname} download sites are
+In case of unified file names, all @value{emacsname} download sites are
added to @code{tramp-default-method-alist} with default method
@option{ftp} @xref{Default Method}. These settings shouldn't be
touched for proper working of the @value{emacsname} package system.
-The syntax for unified filenames is described in the @value{tramp} manual
+The syntax for unified file names is described in the @value{tramp} manual
for @value{emacsothername}.
@end ifset
@end itemize
+
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
+
@node Function Index
@unnumbered Function Index
@printindex fn
+
@node Variable Index
@unnumbered Variable Index
@printindex vr
+
@node Concept Index
@unnumbered Concept Index
@printindex cp
@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 * Use `filename' resp. `file name' consistently.
-@c * Use `host' resp. `machine' consistently.
@c * Consistent small or capitalized words especially in menus.
+@c * Make a unique declaration of @trampfn.
HCoop / bpt / emacs.git / blobdiff