diff options
| -rw-r--r-- | doc/misc/tramp.texi | 180 |
1 files changed, 121 insertions, 59 deletions
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 5dd1a2ca4ee..c34341b9ac9 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -682,7 +682,7 @@ remote host, and then tries that program for encoding and decoding. @vindex tramp-inline-compress-start-size To increase transfer speeds for large text files, use compression before encoding. The user option -@option{tramp-inline-compress-start-size} specifies the file size for +@code{tramp-inline-compress-start-size} specifies the file size for such optimization. @table @asis @@ -1023,17 +1023,18 @@ can. @cindex android (with @option{adb} method) @vindex tramp-adb-program +@vindex PATH@r{, environment variable} This method uses Android Debug Bridge program for accessing Android devices. The Android Debug Bridge must be installed locally for @value{tramp} to work. Some GNU/Linux distributions provide Android Debug Bridge as an installation package. Alternatively, the program is installed as part of the Android SDK@. @value{tramp} finds the @command{adb} program either via the @env{PATH} environment variable -or the absolute path set in the user option @option{tramp-adb-program}. +or the absolute path set in the user option @code{tramp-adb-program}. @vindex tramp-adb-connect-if-not-connected @value{tramp} connects to Android devices with @option{adb} only when -the user option @option{tramp-adb-connect-if-not-connected} is not +the user option @code{tramp-adb-connect-if-not-connected} is not @code{nil}. Otherwise, the connection must be established outside Emacs. @@ -1166,7 +1167,7 @@ pseudo method @option{-}, @ref{File name syntax}. @defopt tramp-default-method Default method is for transferring files. The user option -@option{tramp-default-method} sets it. @value{tramp} uses this user +@code{tramp-default-method} sets it. @value{tramp} uses this user option to determine the default method for remote file names that do not have one specified. @@ -1178,7 +1179,7 @@ not have one specified. @defopt tramp-default-method-alist Default methods for transferring files can be customized for specific user and host combinations through the user option -@option{tramp-default-method-alist}. +@code{tramp-default-method-alist}. For example, the following two lines specify to use the @option{ssh} method for all user names matching @samp{john} and the @option{rsync} @@ -1254,7 +1255,7 @@ improvement is not always true. @defopt tramp-default-user @value{tramp} file name can omit the user name part since @value{tramp} substitutes the currently logged-in user name. However -this substitution can be overridden with @option{tramp-default-user}. +this substitution can be overridden with @code{tramp-default-user}. For example: @lisp @@ -1263,7 +1264,7 @@ For example: @end defopt @defopt tramp-default-user-alist -Instead of a single default user, @option{tramp-default-user-alist} +Instead of a single default user, @code{tramp-default-user-alist} allows multiple default user values based on access method or host name combinations. The alist can hold multiple values. For example, to use the @samp{john} as the default user for the domain @@ -1288,7 +1289,7 @@ corresponding alist entry to nil: @end group @end lisp -The last entry in @option{tramp-default-user-alist} should be reserved +The last entry in @code{tramp-default-user-alist} should be reserved for catch-all or most often used login. @lisp @@ -1306,7 +1307,7 @@ for catch-all or most often used login. @defopt tramp-default-host When host name is omitted, @value{tramp} substitutes the value from -the @option{tramp-default-host} user option. It is initially +the @code{tramp-default-host} user option. It is initially populated with the local host name where Emacs is running. The default method, default user and default host can be overridden as follows: @@ -1325,10 +1326,10 @@ to John's home directory on @code{target} via @code{ssh}. @end defopt @defopt tramp-default-host-alist -Instead of a single default host, @option{tramp-default-host-alist} +Instead of a single default host, @code{tramp-default-host-alist} allows multiple default host values based on access method or user name combinations. The alist can hold multiple values. While -@option{tramp-default-host} is sufficient in most cases, some methods, +@code{tramp-default-host} is sufficient in most cases, some methods, like @option{adb}, require defaults overwritten. @end defopt @@ -1346,7 +1347,7 @@ hop kind, where the start and end points of the connection did not have intermediate check points. @defopt tramp-default-proxies-alist -@option{tramp-default-proxies-alist} specifies proxy hosts to pass +@code{tramp-default-proxies-alist} specifies proxy hosts to pass through. This user option is list of triples consisting of @code{(@var{host} @var{user} @var{proxy})}. @@ -1709,16 +1710,16 @@ Set @code{password-cache} to @code{nil} to disable password caching. @vindex tramp-persistency-file-name For faster initial connection times, @value{tramp} stores previous connection properties in a file specified by the user option -@option{tramp-persistency-file-name}. +@code{tramp-persistency-file-name}. -The default file name for @option{tramp-persistency-file-name} is +The default file name for @code{tramp-persistency-file-name} is @file{~/.emacs.d/tramp}. @value{tramp} reads this file during Emacs startup, and writes to it when exiting Emacs. Delete this file for @value{tramp} to recreate a new one on next Emacs startup. -Set @option{tramp-persistency-file-name} to @code{nil} to disable +Set @code{tramp-persistency-file-name} to @code{nil} to disable storing connections persistently. When @value{tramp} detects a change in the operating system version in @@ -1733,7 +1734,7 @@ For more precise customization, parameters specified by @code{tramp-methods} can be overwritten manually. @vindex tramp-connection-properties -Set @option{tramp-connection-properties} to manually override +Set @code{tramp-connection-properties} to manually override @code{tramp-methods}. Properties in this list are in the form @code{(@var{regexp} @var{property} @var{value})}. @var{regexp} matches remote file names. Use @code{nil} to match all. @@ -1765,7 +1766,7 @@ The parameters @code{tramp-remote-shell} and values for the remote host. @var{property} could also be any property found in -@option{tramp-persistency-file-name}. +@code{tramp-persistency-file-name}. To get around how restricted shells randomly drop connections, set the special property @samp{busybox}. For example: @@ -1794,7 +1795,7 @@ To improve performance and accuracy of remote file access, @command{grep} when available. @defopt tramp-remote-path -@option{tramp-remote-path} specifies which remote directory paths +@code{tramp-remote-path} specifies which remote directory paths @value{tramp} can search for @ref{Remote programs}. @vindex tramp-default-remote-path @@ -1819,7 +1820,7 @@ Another way to find the remote path is to use the path assigned to the remote user by the remote host. @value{tramp} does not normally retain this remote path after login. However, @code{tramp-own-remote-path} preserves the path value, which can be used to update -@option{tramp-remote-path}. +@code{tramp-remote-path}. @lisp (add-to-list 'tramp-remote-path 'tramp-own-remote-path) @@ -1863,22 +1864,22 @@ login security, especially not the exotic ones. However, @value{tramp} provides a few tweaks to address the most common ones. @table @asis -@item @option{tramp-shell-prompt-pattern} +@item @code{tramp-shell-prompt-pattern} @vindex tramp-shell-prompt-pattern -@option{tramp-shell-prompt-pattern} is for remote login shell prompt, +@code{tramp-shell-prompt-pattern} is for remote login shell prompt, which may not be the same as the local login shell prompt, @code{shell-prompt-pattern}. Since most hosts use identical prompts, @value{tramp} sets a similar default value for both prompts. -@item @option{tramp-password-prompt-regexp} -@item @option{tramp-wrong-passwd-regexp} +@item @code{tramp-password-prompt-regexp} +@item @code{tramp-wrong-passwd-regexp} @vindex tramp-password-prompt-regexp @vindex tramp-wrong-passwd-regexp -@value{tramp} uses @option{tramp-password-prompt-regexp} to +@value{tramp} uses @code{tramp-password-prompt-regexp} to distinguish between prompts for passwords and prompts for passphrases. -By default, @option{tramp-password-prompt-regexp} handles the +By default, @code{tramp-password-prompt-regexp} handles the detection in English language environments. See a localization example below: @@ -1902,17 +1903,66 @@ example below: @end lisp Similar localization may be necessary for handling wrong password -prompts, for which @value{tramp} uses @option{tramp-wrong-passwd-regexp}. +prompts, for which @value{tramp} uses @code{tramp-wrong-passwd-regexp}. + +@item @code{tramp-terminal-type} +@vindex tramp-terminal-type +@vindex TERM@r{, environment variable} + +@value{tramp} uses the user option @code{tramp-terminal-type} to set +the remote environment variable @env{TERM} for the shells it runs. +Per default, it is @samp{"dumb"}, but this could be changed. A dumb +terminal is best suited to run the background sessions of +@value{tramp}. However, running interactive remote shells might +require a different setting. This could be achieved by tweaking the +@env{TERM} environment variable in @code{process-environment}. + +@lisp +@group +(let ((process-environment + (cons "TERM=xterm-256color" process-environment))) + (shell)) +@end group +@end lisp + +@item Determining a @value{tramp} session +@vindex TERM@r{, environment variable} +@vindex INSIDE_EMACS@r{, environment variable} + +Sometimes, it is needed to identify whether a shell runs under +@value{tramp} control. The setting of environment variable @env{TERM} +will help: + +@example +@group +if test "$TERM" = "dumb"; then + ... +fi +@end group +@end example + +Another possibility is to check the environment variable +@env{INSIDE_EMACS}. Like for all subprocesses of Emacs, this is set +to the version of the parent Emacs process, @xref{Interactive Shell, , +, emacs}. @value{tramp} adds its own package version to this string, +which could be used for further tests in an inferior shell. The +string of that environment variable loooks always like + +@example +@group +echo $INSIDE_EMACS +@result{} 26.2,tramp:2.3.4 +@end group +@end example @item @command{tset} and other questions @cindex unix command @command{tset} @cindex @command{tset} unix command -@vindex tramp-terminal-type To suppress inappropriate prompts for terminal type, @value{tramp} -sets the @env{TERM} to @code{dumb} before the remote login process -begins via the user option @option{tramp-terminal-type}. This will -silence common @command{tset} related prompts. +sets the @env{TERM} environment variable before the remote login +process begins via the user option @code{tramp-terminal-type} (see +above). This will silence common @command{tset} related prompts. @value{tramp}'s strategy for handling such prompts (commonly triggered from login scripts on remote hosts) is to set the environment @@ -1985,6 +2035,9 @@ shell-specific config files. For example, bash can use @item Interactive shell prompt +@vindex INSIDE_EMACS@r{, environment variable} +@vindex SHELLNAME@r{, environment variable} +@vindex ESHELL@r{, environment variable} @value{tramp} redefines the remote shell prompt internally for robust parsing. This redefinition affects the looks of a prompt in an interactive remote shell through commands, such as @kbd{M-x shell @@ -2142,7 +2195,7 @@ Open a remote connection with a more concise command @kbd{C-x C-f @vindex backup-directory-alist To avoid @value{tramp} from saving backup files owned by @samp{root} to locations accessible to others, default backup settings in -@option{backup-directory-alist} have to be altered. +@code{backup-directory-alist} have to be altered. Here's a scenario where files could be inadvertently exposed. Emacs by default writes backup files to the same directory as the original @@ -2153,7 +2206,7 @@ default by @value{tramp} when using, say, a restricted file of the secretfile is now owned by the user logged in from @value{tramp} and not @samp{root}. -When @option{backup-directory-alist} is @code{nil} (the default), such +When @code{backup-directory-alist} is @code{nil} (the default), such problems do not occur. To ``turn off'' the backup feature for @value{tramp} files and stop @@ -2187,8 +2240,8 @@ Another option is to create better backup file naming with user and host names prefixed to the file name. For example, transforming @file{/etc/secretfile} to @file{~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile}, set the -@value{tramp} user option @option{tramp-backup-directory-alist} from -the existing user option @option{backup-directory-alist}. +@value{tramp} user option @code{tramp-backup-directory-alist} from +the existing user option @code{backup-directory-alist}. Then @value{tramp} backs up to a file name that is transformed with a prefix consisting of the DIRECTORY name. This file name prefixing @@ -2220,16 +2273,16 @@ The backup file name of Just as for backup files, similar issues of file naming affect auto-saving @value{tramp} files. Auto-saved files are saved in the directory specified by the user option -@option{auto-save-file-name-transforms}. By default this is set to +@code{auto-save-file-name-transforms}. By default this is set to the local temporary directory. But in some versions of Debian GNU/Linux, this points to the source directory where the Emacs was compiled. Reset such values to a valid directory. -Set @option{auto-save-file-name-transforms} to @code{nil} to save +Set @code{auto-save-file-name-transforms} to @code{nil} to save auto-saved files to the same directory as the original file. @vindex tramp-auto-save-directory -Alternatively, set the user option @option{tramp-auto-save-directory} +Alternatively, set the user option @code{tramp-auto-save-directory} to direct all auto saves to that location. @node Windows setup hints @@ -2275,6 +2328,7 @@ Windows file names to Cygwin file names. @cindex cygwin and @command{ssh-agent} @cindex @env{SSH_AUTH_SOCK} and emacs on ms windows +@vindex SSH_AUTH_SOCK@r{, environment variable} When using the @command{ssh-agent} on MS Windows for password-less interaction, @option{ssh} methods depend on the environment variable @@ -2551,7 +2605,7 @@ directory contents. @cindex proxy hosts, ad-hoc @value{tramp} file name syntax can accommodate ad hoc specification of -multiple proxies without using @option{tramp-default-proxies-alist} +multiple proxies without using @code{tramp-default-proxies-alist} configuration setup(@pxref{Multi-hops}). Each proxy is specified using the same syntax as the remote host @@ -2568,15 +2622,15 @@ proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: Proxies can take patterns @code{%h} or @code{%u}. @value{tramp} adds the ad-hoc definitions on the fly to -@option{tramp-default-proxies-alist} and is available for re-use +@code{tramp-default-proxies-alist} and is available for re-use 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}}. @defopt tramp-save-ad-hoc-proxies For ad-hoc definitions to be saved automatically in -@option{tramp-default-proxies-alist} for future Emacs sessions, set -@option{tramp-save-ad-hoc-proxies} to non-@code{nil}. +@code{tramp-default-proxies-alist} for future Emacs sessions, set +@code{tramp-save-ad-hoc-proxies} to non-@code{nil}. @lisp (customize-set-variable 'tramp-save-ad-hoc-proxies t) @@ -2621,7 +2675,7 @@ like @code{compile} and @code{grep}) and @file{gud.el} (@code{gdb} or For @value{tramp} to find the command on the remote, it must be accessible through the default search path as setup by @value{tramp} upon first connection. Alternatively, use an absolute path or extend -@option{tramp-remote-path} (see @ref{Remote programs}): +@code{tramp-remote-path} (see @ref{Remote programs}): @lisp @group @@ -2631,9 +2685,9 @@ upon first connection. Alternatively, use an absolute path or extend @end lisp @vindex tramp-remote-process-environment -Customize user option @option{tramp-remote-process-environment} to +Customize user option @code{tramp-remote-process-environment} to suit the remote program's environment for the remote host. -@option{tramp-remote-process-environment} is a list of strings +@code{tramp-remote-process-environment} is a list of strings structured similar to @code{process-environment}, where each element is a string of the form @samp{ENVVARNAME=VALUE}. @@ -2648,12 +2702,13 @@ Use @code{add-to-list} to add entries: (add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java") @end lisp +@vindex HISTORY@r{, environment variable} Modifying or deleting already existing values in the -@option{tramp-remote-process-environment} list may not be feasible on +@code{tramp-remote-process-environment} list may not be feasible on restricted remote hosts. For example, some system administrators disallow changing @env{HISTORY} environment variable. To accommodate such restrictions when using @value{tramp}, fix the -@option{tramp-remote-process-environment} by the following code in the +@code{tramp-remote-process-environment} by the following code in the local @file{.emacs} file: @lisp @@ -2664,6 +2719,7 @@ local @file{.emacs} file: @end group @end lisp +@vindex ENV@r{, environment variable} Setting the @env{ENV} environment variable instructs some shells to read an initialization file. Per default, @value{tramp} has disabled this. You could overwrite this behavior by evaluating @@ -2676,12 +2732,12 @@ this. You could overwrite this behavior by evaluating @end group @end lisp -In addition to @option{tramp-remote-process-environment}, you can set +In addition to @code{tramp-remote-process-environment}, you can set environment variables for individual remote process calls by let-binding @code{process-environment}. @value{tramp} applies any entries not present in the global default value of @code{process-environment} (overriding -@option{tramp-remote-process-environment} settings, if they conflict). +@code{tramp-remote-process-environment} settings, if they conflict). For example: @lisp @@ -2691,6 +2747,7 @@ For example: @end group @end lisp +@vindex HGPLAIN@r{, environment variable} Let-binding in this way works regardless of whether the process to be called is local or remote, since @value{tramp} would add just the @env{HGPLAIN} setting and local processes would take whole value of @@ -2702,6 +2759,7 @@ remotely, please file a bug report. @xref{Bug Reports}. @subsection Running remote programs that create local X11 windows +@vindex DISPLAY@r{, environment variable} To allow a remote program to create an X11 window on the local host, set the @env{DISPLAY} environment variable for the remote host as follows in the local @file{.emacs} file: @@ -2729,16 +2787,16 @@ local host. @subsection Running @code{shell} on a remote host @cindex @code{shell} -Set @option{explicit-shell-file-name} to the appropriate shell name +Set @code{explicit-shell-file-name} to the appropriate shell name when using @value{tramp} between two hosts with different operating systems, such as @samp{windows-nt} and @samp{gnu/linux}. This option ensures the correct name of the remote shell program. -When @option{explicit-shell-file-name} is equal to @code{nil}, calling +When @code{explicit-shell-file-name} is equal to @code{nil}, calling @code{shell} interactively will prompt for a shell name. Starting with Emacs 26, you could use connection-local variables for -setting different values of @option{explicit-shell-file-name} for +setting different values of @code{explicit-shell-file-name} for different remote hosts. @ifinfo @pxref{Connection Local Variables, , , elisp} @@ -2819,7 +2877,7 @@ uid=0(root) gid=0(root) groups=0(root) @code{eshell} added custom @code{su} and @code{sudo} commands that set the default directory correctly for the @file{*eshell*} buffer. -@value{tramp} silently updates @option{tramp-default-proxies-alist} +@value{tramp} silently updates @code{tramp-default-proxies-alist} with an entry for this directory (@pxref{Multi-hops}): @example @@ -2902,7 +2960,7 @@ relative or absolute paths, but not remote paths. command. Powershell V2.0 on the remote host is required to run processes triggered from @value{tramp}. -@option{explicit-shell-file-name} and @option{explicit-*-args} have to +@code{explicit-shell-file-name} and @code{explicit-*-args} have to be set properly so @kbd{M-x shell @key{RET}} can open a proper remote shell on a MS Windows host. To open @command{cmd}, set it as follows: @@ -3297,7 +3355,7 @@ responsiveness slows down. Some suggestions within the scope of Use an external method, such as @option{scp}, which are faster than internal methods. -Keep the file @option{tramp-persistency-file-name}, which is where +Keep the file @code{tramp-persistency-file-name}, which is where @value{tramp} caches remote information about hosts and files. Caching is enabled by default. Don't disable it. @@ -3307,7 +3365,7 @@ files are not independently updated outside @value{tramp}'s control. That cache cleanup will be necessary if the remote directories or files are updated independent of @value{tramp}. -Set @option{tramp-completion-reread-directory-timeout} to @code{nil} to +Set @code{tramp-completion-reread-directory-timeout} to @code{nil} to speed up completions, @ref{File name completion}. Disable version control to avoid delays: @@ -3364,7 +3422,7 @@ uses left-hand side and right-hand side prompts in parallel. Add the following line to @file{~/.zshrc}: @example -[ $TERM = "dumb" ] && unsetopt zle && PS1='$ ' +[[ $TERM == "dumb" ]] && unsetopt zle && PS1='$ ' && return @end example When using fish shell on remote hosts, disable fancy formatting by @@ -3572,7 +3630,7 @@ Host indication in the mode line? Install @file{tramp-theme} from GNU ELPA via Emacs' Package Manager. Enable it via @kbd{M-x load-theme @key{RET} tramp @key{RET}}. Further customization is explained in user option -@option{tramp-theme-face-remapping-alist}. +@code{tramp-theme-face-remapping-alist}. @item @@ -3597,10 +3655,13 @@ then set them with a hook as follows: Why is @file{~/.sh_history} file on the remote host growing? @vindex tramp-histfile-override +@vindex HISTFILE@r{, environment variable} +@vindex HISTFILESIZE@r{, environment variable} +@vindex HISTSIZE@r{, environment variable} Due to the remote shell saving tilde expansions triggered by @value{tramp}, the history file is probably growing rapidly. @value{tramp} can suppress this behavior with the user option -@option{tramp-histfile-override}. When set to @code{t}, environment +@code{tramp-histfile-override}. When set to @code{t}, environment variable @env{HISTFILE} is unset, and environment variables @env{HISTFILESIZE} @env{HISTSIZE} are set to 0. @@ -3896,7 +3957,7 @@ package, use the full ad-hoc file name including all hops, like Alternatively, when saving abbreviated multi-hop file names @file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, the user -option @option{tramp-save-ad-hoc-proxies} must be set non-@code{nil} +option @code{tramp-save-ad-hoc-proxies} must be set non-@code{nil} value. @@ -3944,6 +4005,7 @@ emacsclient @trampfn{ssh,$(whoami)@@$(hostname --fqdn),$1} @end group @end example +@vindex EDITOR@r{, environment variable} Then change the environment variable @env{EDITOR} to point to the wrapper script: |