diff options
Diffstat (limited to 'doc/misc/tramp.texi')
| -rw-r--r-- | doc/misc/tramp.texi | 142 |
1 files changed, 76 insertions, 66 deletions
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 6ed7e0ac032..53a848ad652 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -12,7 +12,7 @@ @footnotestyle end @copying -Copyright @copyright{} 1999--2023 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2024 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -289,9 +289,11 @@ accumulated in the buffer, then decodes that output to produce the file's contents. For external transfers, @value{tramp} sends a command as follows: + @example -$ rcp user@@host:/path/to/remote/file /tmp/tramp.4711 +$ scp user@@host:/path/to/remote/file /tmp/tramp.4711 @end example + @value{tramp} reads the local temporary file @file{/tmp/tramp.4711} into a buffer, and then deletes the temporary file. @@ -361,7 +363,7 @@ Another way is to follow the terminal session below: @example @group $ cd ~/emacs -$ git clone git://git.savannah.gnu.org/tramp.git +$ git clone https://git.savannah.gnu.org/git/tramp.git @end group @end example @@ -2415,8 +2417,10 @@ which may not be the same as the local login shell prompt, @value{tramp} sets a similar default value for both prompts. @item @code{tramp-password-prompt-regexp} +@item @code{tramp-otp-password-prompt-regexp} @item @code{tramp-wrong-passwd-regexp} @vindex tramp-password-prompt-regexp +@vindex tramp-otp-password-prompt-regexp @vindex tramp-wrong-passwd-regexp @value{tramp} uses @code{tramp-password-prompt-regexp} to @@ -2450,6 +2454,10 @@ This user option is, by default, initialized from is usually more convenient to add new passphrases to that user option instead of altering this user option. +The user option @code{tramp-otp-password-prompt-regexp} has a similar +purpose, but for one-time passwords. Those passwords are not cached +by @value{tramp} for reuse. + Similar localization may be necessary for handling wrong password prompts, for which @value{tramp} uses @code{tramp-wrong-passwd-regexp}. @@ -2721,6 +2729,7 @@ entry, @option{Seconds between keepalives} option. Set this to 5. There is no counter which could be set. +@anchor{Using ssh connection sharing} @subsection Using ssh connection sharing @vindex ControlPath@r{, ssh option} @@ -2751,19 +2760,32 @@ Note how @samp{%r}, @samp{%h} and @samp{%p} must be encoded as @samp{%%r}, @samp{%%h} and @samp{%%p}. @vindex tramp-use-ssh-controlmaster-options -If the @file{~/.ssh/config} file is configured appropriately for the -above behavior, then any changes to @command{ssh} can be suppressed -with this @code{nil} setting: +Using a predefined string in @code{tramp-ssh-controlmaster-options}, +or puzzling an own string, happens only when user option +@code{tramp-use-ssh-controlmaster-options} is set to @code{t}. If the +@file{~/.ssh/config} file is configured appropriately for the above +behavior, then any changes to @command{ssh} can be suppressed with +this @code{nil} setting: @lisp (customize-set-variable 'tramp-use-ssh-controlmaster-options nil) @end lisp +Sometimes, it is not possible to use OpenSSH's @option{ControlMaster} +option for remote processes. This could result in concurrent access +to the OpenSSH socket when reading data by different processes, which +could block Emacs. In this case, setting +@code{tramp-use-ssh-controlmaster-options} to @code{suppress} disables +shared access. It is not needed to set this user option permanently +to @code{suppress}, binding the user option prior calling +@code{make-process} is sufficient. @value{tramp} does this for +esxample for compilation processes on its own. + @vindex ProxyCommand@r{, ssh option} @vindex ProxyJump@r{, ssh option} -This should also be set to @code{nil} if you use the -@option{ProxyCommand} or @option{ProxyJump} options in your -@command{ssh} configuration. +@code{tramp-use-ssh-controlmaster-options} should also be set to +@code{nil} or @code{suppress} if you use the @option{ProxyCommand} or +@option{ProxyJump} options in your @command{ssh} configuration. In order to use the @option{ControlMaster} option, @value{tramp} must check whether the @command{ssh} client supports this option. This is @@ -2938,7 +2960,7 @@ connection cleanup or on Emacs exiting. @cindex rclone setup The default arguments of the @command{rclone} operations -@command{mount}, @command{coopyto}, @command{moveto} and +@command{mount}, @command{copyto}, @command{moveto} and @command{about} are declared in the variable @code{tramp-methods} as method specific parameters. Usually, they don't need to be overwritten. @@ -3472,12 +3494,7 @@ much more appropriate. @value{tramp} can complete the following @value{tramp} file name components: method names, user names, host names, and file names -located on remote hosts. User name and host name completion is -activated only, if file name completion has one of the styles -@code{basic}, @code{emacs21}, or @code{emacs22}. -@ifinfo -@xref{Completion Styles, , , emacs}. -@end ifinfo +located on remote hosts. For example, type @kbd{C-x C-f @value{prefixwithspace} s @key{TAB}}, @value{tramp} completion choices show up as @@ -3511,10 +3528,7 @@ directory @file{/sbin} on your local host. Type @kbd{s h @value{postfixhop}} for the minibuffer completion to @samp{@value{prefix}ssh@value{postfixhop}}. Typing @kbd{@key{TAB}} shows host names @value{tramp} extracts from @file{~/.ssh/config} -@c bug#50387 -file, for example@footnote{Some completion styles, like -@code{substring} or @code{flex}, require to type at least one -character after the trailing @samp{@value{postfixhop}}.}. +file, for example: @example @group @@ -3605,13 +3619,23 @@ ssh@value{postfixhop}you@@remotehost@value{postfix}/path @key{RET}} Each involved method must be an inline method (@pxref{Inline methods}). @value{tramp} adds the ad-hoc definitions on the fly to -@code{tramp-default-proxies-alist} and is available for re-use during +@code{tramp-default-proxies-alist} and is available for reuse during that Emacs session. Subsequent @value{tramp} connections to the same remote host can then use the shortcut form: -@samp{@trampfn{ssh,you@@remotehost,/path}}. Ad-hoc definitions are -removed from @code{tramp-default-proxies-alist} via the command -@kbd{M-x tramp-cleanup-all-connections @key{RET}} (@pxref{Cleanup -remote connections}). +@samp{@trampfn{ssh,you@@remotehost,/path}}. + +@defopt tramp-show-ad-hoc-proxies +If this user option is non-@code{nil}, ad-hoc definitions are kept in +remote file names instead of showing the shortcuts. + +@lisp +(customize-set-variable 'tramp-show-ad-hoc-proxies t) +@end lisp +@end defopt + +Ad-hoc definitions are removed from @code{tramp-default-proxies-alist} +via the command @kbd{M-x tramp-cleanup-all-connections @key{RET}} +(@pxref{Cleanup remote connections}). @defopt tramp-save-ad-hoc-proxies For ad-hoc definitions to be saved automatically in @@ -4299,7 +4323,8 @@ In order to gain even more performance, it is recommended to bind @code{start-file-process}. Furthermore, you might set @code{tramp-use-ssh-controlmaster-options} to @code{nil} in order to bypass @value{tramp}'s handling of the @option{ControlMaster} options, -and use your own settings in @file{~/.ssh/config}. +and use your own settings in @file{~/.ssh/config}, @ref{Using ssh +connection sharing}. @node Cleanup remote connections @@ -5044,7 +5069,7 @@ Yes. @command{OpenSSH} has added support for @acronym{FIDO} hardware devices via special key types @option{*-sk}. @value{tramp} supports the additional handshaking messages for them. This requires at least @command{OpenSSH} 8.2, and a @acronym{FIDO} @acronym{U2F} compatible -security key, like yubikey, solokey, or nitrokey. +security key, like yubikey, solokey, nitrokey, or titankey. @item @@ -5103,30 +5128,11 @@ How to get notified after @value{tramp} completes file transfers? Make Emacs beep after reading from or writing to the remote host with the following code in @file{~/.emacs}. +@vindex tramp-handle-write-region-hook +@vindex tramp-handle-file-local-copy-hook @lisp -@group -(defadvice tramp-handle-write-region - (after tramp-write-beep-advice activate) - "Make @value{tramp} beep after writing a file." - (interactive) - (beep)) -@end group - -@group -(defadvice tramp-handle-do-copy-or-rename-file - (after tramp-copy-beep-advice activate) - "Make @value{tramp} beep after copying a file." - (interactive) - (beep)) -@end group - -@group -(defadvice tramp-handle-insert-file-contents - (after tramp-insert-beep-advice activate) - "Make @value{tramp} beep after inserting a file." - (interactive) - (beep)) -@end group +(add-hook 'tramp-handle-write-region-hook 'beep) +(add-hook 'tramp-handle-file-local-copy-hook 'beep) @end lisp @@ -5397,9 +5403,8 @@ minibuffer: @end group @group -(defadvice minibuffer-complete - (before my-minibuffer-complete activate) - (expand-abbrev)) +(advice-add 'minibuffer-complete + :before 'expand-abbrev) @end group @end lisp @@ -5596,6 +5601,8 @@ If you find the cleanup disturbing, because the file names in two forms in your @file{~/.emacs} after loading the @code{tramp} and @code{recentf} packages: +@vindex tramp-cleanup-connection-hook +@vindex tramp-cleanup-all-connections-hook @lisp @group (remove-hook @@ -5881,20 +5888,23 @@ wrapping the timer function body as follows: to 10. @value{tramp} does not display all messages; only those with a verbosity level less than or equal to @code{tramp-verbose}. +@noindent The verbosity levels are - @w{ 0} silent (no @value{tramp} messages at all) -@*@indent @w{ 1} errors -@*@indent @w{ 2} warnings -@*@indent @w{ 3} connection to remote hosts (default verbosity) -@*@indent @w{ 4} activities -@*@indent @w{ 5} internal -@*@indent @w{ 6} sent and received strings -@*@indent @w{ 7} connection properties -@*@indent @w{ 8} file caching -@*@indent @w{ 9} test commands -@*@indent @w{10} traces (huge) -@*@indent @w{11} call traces (maintainer only) +@itemize @w{} +@item @w{ 0} Silent (no @value{tramp} messages at all) +@item @w{ 1} Errors +@item @w{ 2} Warnings +@item @w{ 3} Connection to remote hosts (default verbosity) +@item @w{ 4} Activities +@item @w{ 5} Internal +@item @w{ 6} Sent and received strings +@item @w{ 7} Connection properties +@item @w{ 8} File caching +@item @w{ 9} Test commands +@item @w{10} Traces (huge) +@item @w{11} Call traces (maintainer only) +@end itemize With @code{tramp-verbose} greater than or equal to 4, messages are also written to a @value{tramp} debug buffer. Such debug buffers are @@ -5944,7 +5954,7 @@ this option with care, because it could decrease the performance of @value{tramp} actions. If @code{tramp-verbose} is greater than or equal to 11, @value{tramp} -function call traces are written to the buffer @file{*trace-output*}. +function call traces are written to a @value{tramp} trace buffer. @node GNU Free Documentation License |