X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/cfbf790d80eaa399afceecd9a6c3e2e76bca59b0..a7bef505860dc15dd9fc1513e45a1ec71417471e:/doc/misc/tramp.texi diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index f1dac49305..4c3740f02f 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -20,6 +20,33 @@ @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 @@ -35,6 +62,7 @@ @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. @@ -621,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 @@ -723,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 @@ -796,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 @@ -994,10 +998,26 @@ name. @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 @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 @@ -2323,25 +2343,25 @@ using the default method. @xref{Default Method}. 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} +@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{~} 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}. @@ -2386,13 +2406,18 @@ 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{#} 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 @@ -2453,7 +2478,8 @@ If you, for example, type @kbd{C-x C-f @value{prefix}t @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 @@ -2480,7 +2506,8 @@ Next @kbd{@key{TAB}} brings you all machine 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,} @@ -3096,6 +3123,45 @@ Host * @end example +@item +@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 + +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 File name completion does not work with @value{tramp} @@ -3887,3 +3953,4 @@ for @value{emacsothername}. @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.