@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-2012 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
* 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 ---
* Customizing Completion:: Selecting config files for user/host name completion.
* Password handling:: Reusing passwords for several connections.
* Connection caching:: Reusing connection related information.
+* Predefined connection information::
+ Setting own 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.
+* 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}
@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{...}
+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
* Customizing Completion:: Selecting config files for user/host name completion.
* Password handling:: Reusing passwords for several connections.
* Connection caching:: Reusing connection related information.
+* Predefined connection information::
+ Setting own 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.
+* Android shell setup:: Android shell setup hints.
* Auto-save and Backup:: Auto-save and Backup.
+* Windows setup hints:: Issues with Cygwin ssh.
@end menu
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 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
hasn't defined a user name. Different port numbers must be defined in
the session.
-
-@item @option{adb}
-@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.
-
@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)
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
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}
-@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}
+@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)
@end ifset
-@item @option{smb} --- @command{smbclient}
+@item @option{smb}---@command{smbclient}
@cindex method smb
@cindex smb method
file names like @file{//melancholia/daniel$$/.emacs}. The only
disadvantage is that there's no possibility to specify another user
name.
+
+
+@item @option{adb}
+@cindex method adb
+@cindex adb method
+
+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 @code{$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
The @option{synce} method allows communication with Windows Mobile
devices. Beside GVFS for mounting remote files and directories via
FUSE, it also needs the SYNCE-GVFS plugin.
+
@end table
@defopt tramp-gvfs-methods
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.
@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
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 @option{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
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,
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
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
@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
"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
@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 machine.
+
+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 @code{$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
Some examples of @value{tramp} filenames are shown below.
@table @file
-@item @trampfn{, , melancholia, .emacs}
+@item @value{prefix}melancholia@value{postfix}.emacs
Edit the file @file{.emacs} in your home directory on the machine
@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.
-@item @trampfn{, , melancholia, ~/.emacs}
-This also edits the same file --- the @file{~} is expanded to your
+@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.
-@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>}
construct is expanded to the home directory of that user on the remote
machine.
-@item @trampfn{, , melancholia, /etc/squid.conf}
+@item @value{prefix}melancholia@value{postfix}/etc/squid.conf
This edits the file @file{/etc/squid.conf} on the machine
@code{melancholia}.
@file{.emacs} in my home directory I would specify the filename
@file{@trampfn{ssh, daniel, melancholia, .emacs}}.
+@ifset emacs
+A remote filename 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,
@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
@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
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,}
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
@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:
+
+@lisp
+(setq tramp-ssh-controlmaster-options
+ (concat
+ "-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p "
+ "-o ControlMaster=auto -o ControlPersist=yes"))
+@end lisp
-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}:
+Note, that "%r", "%h" and "%p" must be encoded as "%%r", "%%h" and
+"%%p", respectively. The entries of @code{ControlPath},
+@code{ControlMaster} and @code{ControlPersist} can be removed from
+this setting, if they are configured properly in your
+@file{~/.ssh/config}:
-@example
-Host *
- ControlMaster auto
- ControlPersist yes
-@end example
+@lisp
+(setq tramp-ssh-controlmaster-options "")
+@end lisp
@item
@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