diff options
Diffstat (limited to 'doc/misc/tramp.texi')
| -rw-r--r-- | doc/misc/tramp.texi | 253 |
1 files changed, 166 insertions, 87 deletions
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index c65d4aac7ed..4c3740f02f7 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -216,8 +216,9 @@ Configuring @value{tramp} for use * 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. +* 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} @@ -479,7 +480,8 @@ GVFS integration started in February 2009. 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 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 Emacs repository happened in June 2002, @@ -542,6 +544,7 @@ Method}. * 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. +* Android shell setup:: Android shell setup hints. * Auto-save and Backup:: Auto-save and Backup. * Windows setup hints:: Issues with Cygwin ssh. @end menu @@ -584,9 +587,10 @@ startup may drown out the improvement in file transfer times. 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 @@ -645,13 +649,6 @@ Connect to the remote host with @command{ssh}. This is identical to 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 @@ -747,16 +744,6 @@ remote host. 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 @@ -820,13 +807,6 @@ The cost of the cryptographic handshake at the start of an @command{scp} 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 @@ -894,51 +874,6 @@ to not print any shell prompt, which confuses @value{tramp} mightily. 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 @@ -1057,6 +992,33 @@ 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. + + +@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 @@ -1105,6 +1067,7 @@ phones. For the time being, @value{tramp} only supports OBEX over Bluetooth. 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 @@ -1255,7 +1218,7 @@ user, see the @option{su} or @option{sudo} methods. They offer 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. @@ -1294,8 +1257,8 @@ example, if you always have to use the user @samp{john} in the domain @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 @@ -1353,6 +1316,18 @@ Note, however, that the most simplification @samp{/::} won't work, 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 @@ -1612,6 +1587,7 @@ can return user names only. 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, @@ -2049,6 +2025,77 @@ fi @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. + +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 @@ -2359,6 +2406,13 @@ using the @option{ssh} method to transfer files, and edit @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, @@ -2944,7 +2998,7 @@ host as well as the time needed to perform the operations there count. 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 @@ -3070,17 +3124,42 @@ Host * @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. 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}: + +@lisp +(setq tramp-ssh-controlmaster-options "") +@end lisp @item |