@c configure.ac, so you should edit that file and run
@c "autoconf && ./configure" to change the version number.
-@c Additionally, flags are set with respect to the Emacs flavor; and
-@c depending whether Tramp is packaged into (X)Emacs, or standalone.
-
@include trampver.texi
@c Macro for formatting a file name according to the respective
@node Top, Overview, (dir), (dir)
+@ifnottex
@top @value{tramp} version @value{trampver} User Manual
-@ifnottex
This file documents @value{tramp} version @value{trampver}, a remote file
editing package for Emacs.
@email{tramp-devel@@gnu.org}, and archived at
@uref{http://lists.gnu.org/archive/html/tramp-devel/, the
@value{tramp} Mail Archive}.
-@ifhtml
-Older archives are located at
-@uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel,
-SourceForge Mail Archive} and
-@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/,
-The Mail Archive}.
-@c in HTML output, there's no new paragraph.
-@*@*
-@end ifhtml
@insertcopying
@end ifnottex
Another way is to follow the terminal session below:
@example
+@group
] @strong{cd ~/emacs}
] @strong{git clone git://git.savannah.gnu.org/tramp.git}
+@end group
@end example
@noindent
From behind a firewall:
@example
+@group
] @strong{git config --global http.proxy http://user:pwd@@proxy.server.com:8080}
] @strong{git clone http://git.savannah.gnu.org/r/tramp.git}
+@end group
@end example
@noindent
To fetch updates from the repository, use git pull:
@example
+@group
] @strong{cd ~/emacs/tramp}
] @strong{git pull}
+@end group
@end example
@noindent
@file{configure} script:
@example
+@group
] @strong{cd ~/emacs/tramp}
] @strong{autoconf}
+@end group
@end example
@value{tramp} is initially configured to use the @command{scp} program
to connect to the remote host. Just type @kbd{C-x C-f} and then enter
-file name @file{@trampf{user@@host,/path/to.file}}. For details, see
-@xref{Default Method}.
+file name @file{@trampf{user@@host,/path/to.file}}. For details,
+@xref{Default Method}, @xref{Default User}, @xref{Default Host}.
-For problems related to the behavior of remote shell, see @ref{Remote
+For problems related to the behavior of remote shell, @xref{Remote
shell setup} for details.
For changing the connection type and file access method from the
-defaults to one of several other options, see (@pxref{Connection
-types}).
+defaults to one of several other options, @xref{Connection types}.
-@strong{Note} that some user options and variables described in these
-examples are not auto loaded by Emacs. All examples require
-@value{tramp} is installed and loaded:
+@strong{Note} that some user options described in these examples are
+not auto loaded by Emacs. All examples require @value{tramp} is
+installed and loaded:
@lisp
-(require 'tramp)
+@group
+(custom-set-variables
+ '(tramp-verbose 6 nil (tramp) "Enable remote command traces"))
+@end group
@end lisp
becomes important for editing files, transferring large files, or
operating on a large number of files.
-@cindex inline methods
-@cindex external methods
-@cindex methods, inline
-@cindex methods, external
-
The performance of the external methods is generally better than that
of the inline methods, at least for large files. This is caused by
the need to encode and decode the data when transferring inline.
remote host, and then tries that program for encoding and decoding.
To increase transfer speeds for large text files, use compression
-before encoding. The variable @var{tramp-inline-compress-start-size}
-specifies the file size for such optimization.
+before encoding. The user option
+@option{tramp-inline-compress-start-size} specifies the file size for
+such optimization.
@table @asis
@item @option{rsh}
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
+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 variable @var{tramp-adb-program}.
+or the absolute path set in the user option @option{tramp-adb-program}.
@value{tramp} connects to Android devices with @option{adb} only when
-the custom option @option{tramp-adb-connect-if-not-connected} is not
+the user option @option{tramp-adb-connect-if-not-connected} is not
@code{nil}. Otherwise, the connection must be established outside
Emacs.
@end table
@defopt tramp-gvfs-methods
-@vindex tramp-gvfs-methods
-This custom option is a list of external methods for GVFS@. By
-default, this list includes @option{afp}, @option{dav}, @option{davs},
+This user option is a list of external methods for GVFS@. By default,
+this list includes @option{afp}, @option{dav}, @option{davs},
@option{gdrive}, @option{obex}, @option{sftp} and @option{synce}.
Other methods to include are: @option{ftp} and @option{smb}.
@end defopt
@node Default Method
@section Selecting a default method
@cindex default method
-@vindex tramp-default-method
-@vindex tramp-default-method-alist
-Default method is for transferring files. The variable
-@code{tramp-default-method} sets it. @value{tramp} uses this variable
-to determine the default method for tramp file names that do not have
-one specified.
+@defopt tramp-default-method
+Default method is for transferring files. The user option
+@option{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.
@lisp
-(setq tramp-default-method "ssh")
+(custom-set-variables '(tramp-default-method "ssh" nil (tramp)))
@end lisp
+@end defopt
+@defopt tramp-default-method-alist
Default methods for transferring files can be customized for specific
-user and host combinations through the alist variable
-@code{tramp-default-method-alist}.
+user and host combinations through the user option
+@option{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}
the host @samp{localhost}.
@lisp
+@group
(add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
(add-to-list 'tramp-default-method-alist '("lily" "" "rsync"))
(add-to-list 'tramp-default-method-alist
'("\\`localhost\\'" "\\`root\\'" "su"))
+@end group
@end lisp
+@end defopt
@noindent
-See the documentation for the variable
-@code{tramp-default-method-alist} for details.
-
-@noindent
-External methods performance faster for large files.
-
-@noindent
-@xref{Inline methods}.
-@xref{External methods}.
+External methods performance faster for large files. @pxref{Inline
+methods}. @pxref{External methods}.
Choosing the access method also depends on the security environment.
For example, @option{rsh} and @option{telnet} methods that use clear
@node Default User
@section Selecting a default user
@cindex default user
-@vindex tramp-default-user
-@vindex tramp-default-user-alist
+@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 @code{tramp-default-user}.
+this substitution can be overridden with @option{tramp-default-user}.
For example:
@lisp
-(setq tramp-default-user "root")
+(custom-set-variables'(tramp-default-user "root" nil (tramp)))
@end lisp
+@end defopt
-Instead of a single default user, @code{tramp-default-user-alist}
+@defopt tramp-default-user-alist
+Instead of a single default user, @option{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
@samp{somewhere.else} only:
@lisp
+@group
(add-to-list 'tramp-default-user-alist
'("ssh" ".*\\.somewhere\\.else\\'" "john"))
+@end group
@end lisp
-@noindent
-See the documentation for the variable @code{tramp-default-user-alist}
-for more details.
-
A Caution: @value{tramp} will override any default user specified in
the configuration files outside Emacs, such as @file{~/.ssh/config}.
To stop @value{tramp} from applying the default value, set the
corresponding alist entry to nil:
@lisp
+@group
(add-to-list 'tramp-default-user-alist
'("ssh" "\\`here\\.somewhere\\.else\\'" nil))
+@end group
@end lisp
-The last entry in @code{tramp-default-user-alist} should be reserved
+The last entry in @option{tramp-default-user-alist} should be reserved
for catch-all or most often used login.
@lisp
+@group
(add-to-list 'tramp-default-user-alist
'(nil nil "jonas") t)
+@end group
@end lisp
+@end defopt
@node Default Host
@section Selecting a default host
@cindex default host
-@vindex tramp-default-host
-@vindex tramp-default-host-alist
+@defopt tramp-default-host
When host name is omitted, @value{tramp} substitutes the value from
-the @code{tramp-default-host} variable. It is initially populated
-with the local hostname where Emacs is running. Both the default user
-and default host can be overridden as follows:
+the @option{tramp-default-host} user option. It is initially
+populated with the local hostname where Emacs is running. Both the
+default user and default host can be overridden as follows:
@lisp
-(setq tramp-default-user "john"
- tramp-default-host "target")
+@group
+(custom-set-variables
+ '(tramp-default-user "john" nil (tramp))
+ '(tramp-default-host "target" nil (tramp)))
+@end group
@end lisp
With both defaults set, @samp{@trampfn{ssh,,}} will connect
-@value{tramp} to John's home directory on target.
+@value{tramp} to John's home directory on @code{target}.
@strong{Note} @samp{/::} won't work, because @samp{/:} is the prefix
for quoted file names.
+@ifinfo
+@pxref{Quoted File Names, , , emacs}.
+@end ifinfo
+@end defopt
-Instead of a single default host, @code{tramp-default-host-alist}
+@defopt tramp-default-host-alist
+Instead of a single default host, @option{tramp-default-host-alist}
allows multiple default host values based on access method or user
name combinations. The alist can hold multiple values. While
-@code{tramp-default-host} is sufficient in most cases, some methods,
+@option{tramp-default-host} is sufficient in most cases, some methods,
like @option{adb}, require defaults overwritten.
-
-@noindent
-See the documentation for the variable @code{tramp-default-host-alist}
-for more details.
+@end defopt
@node Multi-hops
have intermediate check points.
@defopt tramp-default-proxies-alist
-@vindex tramp-default-proxies-alist
@option{tramp-default-proxies-alist} specifies proxy hosts to pass
-through. This variable is list of triples consisting of (@var{host}
-@var{user} @var{proxy}).
+through. This user option is list of triples consisting of
+@code{(@var{host} @var{user} @var{proxy})}.
The first match is the proxy host through which passes the file name
and the target host matching @var{user}@@@var{host}. @var{host} and
user @samp{bird} to reach remote hosts outside the local domain:
@lisp
+@group
(add-to-list 'tramp-default-proxies-alist
'("\\." nil "@trampfn{ssh,bird@@bastion.your.domain,}"))
(add-to-list 'tramp-default-proxies-alist
'("\\.your\\.domain\\'" nil nil))
+@end group
@end lisp
@strong{Note}: @code{add-to-list} adds elements at the beginning of a
connect to @samp{bastion.your.domain}, then:
@lisp
+@group
(add-to-list 'tramp-default-proxies-alist
'("\\`bastion\\.your\\.domain\\'"
"\\`bird\\'"
"@trampfn{ssh,jump.your.domain,}"))
+@end group
@end lisp
@var{proxy} can take patterns @code{%h} or @code{%u} for @var{host} or
access, then use this alist entry:
@lisp
+@group
(add-to-list 'tramp-default-proxies-alist
'("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh,%h,}"))
+@end group
@end lisp
Opening @file{@trampfn{sudo,randomhost.your.domain,}} first connects
@command{sudo -u root}:
@lisp
+@group
(add-to-list 'tramp-default-proxies-alist
'(nil "\\`root\\'" "@trampfn{ssh,%h,}"))
(add-to-list 'tramp-default-proxies-alist
'((regexp-quote (system-name)) nil nil))
+@end group
@end lisp
The above configuration allows @value{tramp} connection as @samp{root}
to remote Ubuntu hosts.
-@code{tramp-default-proxies-alist} is also used for passing through
+@option{tramp-default-proxies-alist} is also used for passing through
firewalls or proxy servers.
For example, the local host @samp{proxy.your.domain} on port 3128
discussion of ethical issues.} Then the configuration is:
@lisp
+@group
(add-to-list 'tramp-default-proxies-alist
'("\\`host\\.other\\.domain\\'" nil
"@trampfn{tunnel,proxy.your.domain#3128,}"))
+@end group
@end lisp
Gateway methods in a multiple hop chain can be declared only as the first hop.
them for proxies only.
@defopt tramp-restricted-shell-hosts-alist
-@vindex tramp-restricted-shell-hosts-alist
An alist of regular expressions of hosts running restricted shells,
such as @command{rbash}. @value{tramp} will then use them only as
proxies.
restricted shell:
@lisp
+@group
(add-to-list 'tramp-restricted-shell-hosts-alist
"\\`bastion\\.your\\.domain\\'")
+@end group
@end lisp
@end defopt
Example:
@example
+@group
(tramp-get-completion-function "rsh")
@result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
(tramp-parse-rhosts "~/.rhosts"))
+@end group
@end example
@end defun
Example:
@example
+@group
(tramp-set-completion-function "ssh"
'((tramp-parse-sconfig "/etc/ssh_config")
(tramp-parse-sconfig "~/.ssh/config")))
@result{} ((tramp-parse-sconfig "/etc/ssh_config")
(tramp-parse-sconfig "~/.ssh/config"))
+@end group
@end example
@end defun
in such files, it can return host names only.
@item @code{tramp-parse-sconfig}
-@findex tramp-parse-shosts
+@findex tramp-parse-sconfig
This function returns the host nicknames defined by @code{Host} entries
in @file{~/.ssh/config} style files.
are always @code{nil}.
@item @code{tramp-parse-sknownhosts}
-@findex tramp-parse-shostkeys
+@findex tramp-parse-sknownhosts
Another SSH2 style parsing of directories like
@file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This
Example:
@example
+@group
(my-tramp-parse "~/.my-tramp-hosts")
@result{} ((nil "toto") ("daniel" "melancholia"))
+@end group
@end example
@end defun
the same user or host name independent of the access method.
@vindex password-cache-expiry
-
@code{password-cache-expiry} sets the duration (in seconds) the
passwords are remembered. Passwords are never saved permanently nor
can they extend beyond the lifetime of the current Emacs session. Set
@code{password-cache-expiry} to @code{nil} to disable expiration.
@vindex password-cache
-
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 variable
-@code{tramp-persistency-file-name}.
+connection properties in a file specified by the user option
+@option{tramp-persistency-file-name}.
-The default file name for @code{tramp-persistency-file-name} is
+The default file name for @option{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 @code{tramp-persistency-file-name} to @code{nil} to disable
+Set @option{tramp-persistency-file-name} to @code{nil} to disable
storing connections persistently.
To reuse connection information from the persistent list,
For more precise customization, parameters specified by
@code{tramp-methods} can be overwritten manually.
-Set @code{tramp-connection-properties} to manually override
+Set @option{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. @var{property} is the
-property's name, and @var{value} is the property's value.
+@code{(@var{regexp} @var{property} @var{value})}. @var{regexp}
+matches remote file names. Use @code{nil} to match all.
+@var{property} is the property's name, and @var{value} is the
+property's value.
@var{property} is any method specific parameter contained in
@code{tramp-methods}. The parameter key in @code{tramp-methods} is a
remote shell:
@lisp
+@group
(add-to-list 'tramp-connection-properties
(list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}")
"remote-shell" "/bin/ksh"))
+@end group
+
+@group
(add-to-list 'tramp-connection-properties
(list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}")
"remote-shell-login" '("-")))
+@end group
@end lisp
The parameters @code{tramp-remote-shell} and
values for the remote host.
@var{property} could also be any property found in
-@code{tramp-persistency-file-name}.
+@option{tramp-persistency-file-name}.
To get around how restricted shells randomly drop connections, set the
special property @samp{busybox}. For example:
@lisp
+@group
(add-to-list 'tramp-connection-properties
(list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}")
"busybox" t))
+@end group
@end lisp
@command{grep} when available.
@defopt tramp-remote-path
-@vindex tramp-remote-path
-@vindex tramp-default-remote-path
-@vindex tramp-own-remote-path
@option{tramp-remote-path} specifies which remote directory paths
@value{tramp} can search for @ref{Remote programs}.
+@vindex tramp-default-remote-path
@value{tramp} uses standard defaults, such as @file{/bin} and
@file{/usr/bin}, which are reasonable for most hosts. To accommodate
differences in hosts and paths, for example, @file{/bin:/usr/bin} on
(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
@end lisp
+@vindex tramp-own-remote-path
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
-@code{tramp-remote-path}.
+@option{tramp-remote-path}.
@lisp
(add-to-list 'tramp-remote-path 'tramp-own-remote-path)
provides a few tweaks to address the most common ones.
@table @asis
-@item @var{tramp-shell-prompt-pattern}
+@item @option{tramp-shell-prompt-pattern}
@vindex tramp-shell-prompt-pattern
-@code{tramp-shell-prompt-pattern} is for remote login shell prompt,
+@option{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 @var{tramp-password-prompt-regexp}
-@item @var{tramp-wrong-passwd-regexp}
+@item @option{tramp-password-prompt-regexp}
+@item @option{tramp-wrong-passwd-regexp}
@vindex tramp-password-prompt-regexp
@vindex tramp-wrong-passwd-regexp
-@value{tramp} uses @var{tramp-password-prompt-regexp} to distinguish
-between prompts for passwords and prompts for passphrases. By default,
-@var{tramp-password-prompt-regexp} handles the detection in English
-language environments. See a localization example below:
+@value{tramp} uses @option{tramp-password-prompt-regexp} to
+distinguish between prompts for passwords and prompts for passphrases.
+By default, @option{tramp-password-prompt-regexp} handles the
+detection in English language environments. See a localization
+example below:
@lisp
-(setq
- tramp-password-prompt-regexp
- (concat
- "^.*"
- (regexp-opt
- '("passphrase" "Passphrase"
- ;; English
- "password" "Password"
- ;; Deutsch
- "passwort" "Passwort"
- ;; Français
- "mot de passe" "Mot de passe") t)
- ".*:\0? *"))
+@group
+(custom-set-variables
+ '(tramp-password-prompt-regexp
+ (concat
+ "^.*"
+ (regexp-opt
+ '("passphrase" "Passphrase"
+ ;; English
+ "password" "Password"
+ ;; Deutsch
+ "passwort" "Passwort"
+ ;; Français
+ "mot de passe" "Mot de passe")
+ t)
+ ".*:\0? *")
+ nil (tramp)))
+@end group
@end lisp
Similar localization may be necessary for handling wrong password
-prompts, for which @value{tramp} uses @var{tramp-wrong-passwd-regexp}.
+prompts, for which @value{tramp} uses @option{tramp-wrong-passwd-regexp}.
@item @command{tset} and other questions
@cindex Unix command tset
To suppress inappropriate prompts for terminal type, @value{tramp}
sets the @env{TERM} to @code{dumb} before the remote login process
-begins via the variable @code{tramp-terminal-type}. This will silence
-common @command{tset} related prompts.
+begins via the user option @option{tramp-terminal-type}. 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
process.
@vindex tramp-actions-before-shell
-
An alternative approach is to configure @value{tramp} with strings
that can identify such questions using
@code{tramp-actions-before-shell}. Example:
@lisp
+@group
(defconst my-tramp-prompt-regexp
(concat (regexp-opt '("Enter the birth date of your mother:") t)
"\\s-*")
"Regular expression matching my login prompt question.")
+@end group
+@group
(defun my-tramp-action (proc vec)
"Enter \"19000101\" in order to give a correct answer."
(save-window-excursion
(with-current-buffer (tramp-get-connection-buffer vec)
(tramp-message vec 6 "\n%s" (buffer-string))
(tramp-send-string vec "19000101"))))
+@end group
+@group
(add-to-list 'tramp-actions-before-shell
'(my-tramp-prompt-regexp my-tramp-action))
+@end group
@end lisp
Then re-set the prompt string in @file{~/.emacs_SHELLNAME} as follows:
@example
+@group
# Reset the prompt for remote Tramp shells.
if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then
PS1="[\u@@\h \w]$ "
fi
+@end group
@end example
@ifinfo
overwrite as follows:
@lisp
+@group
(add-to-list
'tramp-connection-properties
- `(,(regexp-quote "192.168.0.1") "remote-copy-args" (("-l") ("%r"))))
+ `(,(regexp-quote "192.168.0.1")
+ "remote-copy-args" (("-l") ("%r"))))
+@end group
@end lisp
@noindent
whatever shell is installed on the device with this setting:
@lisp
+@group
(add-to-list 'tramp-connection-properties
(list (regexp-quote "192.168.0.26") "remote-shell" "sh"))
+@end group
@end lisp
@noindent
@file{/system/bin}. Both of these are set as follows:
@lisp
+@group
(add-to-list 'tramp-remote-path 'tramp-own-remote-path)
(add-to-list 'tramp-remote-path "/system/xbin")
+@end group
@end lisp
@noindent
(recommended), use this:
@example
+@group
Host android
HostName 192.168.0.26
User root
Port 2222
+@end group
@end example
@noindent
the previous example, fix the connection properties as follows:
@lisp
+@group
(add-to-list 'tramp-connection-properties
(list (regexp-quote "android") "remote-shell" "sh"))
+@end group
@end lisp
@noindent
To avoid @value{tramp} from saving backup files owned by @samp{root}
to locations accessible to others, default backup settings in
-@code{backup-directory-alist} have to be altered.
+@option{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
of the secretfile is now owned by the user logged in from
@value{tramp} and not @samp{root}.
-When @code{backup-directory-alist} is @code{nil} (the default), such
+When @option{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
@value{tramp} from saving to the backup directory, use this:
@lisp
+@group
(add-to-list 'backup-directory-alist
(cons tramp-file-name-regexp nil))
+@end group
@end lisp
@noindent
@option{sudo} methods:
@lisp
+@group
(setq backup-enable-predicate
(lambda (name)
(and (normal-backup-enable-predicate name)
(let ((method (file-remote-p name 'method)))
(when (stringp method)
(member method '("su" "sudo"))))))))
+@end group
@end lisp
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} variable @code{tramp-backup-directory-alist} from the
-existing variable @code{backup-directory-alist}.
+@value{tramp} user option @option{tramp-backup-directory-alist} from
+the existing user option @option{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
Example:
@lisp
+@group
(add-to-list 'backup-directory-alist
(cons "." "~/.emacs.d/backups/"))
-(setq tramp-backup-directory-alist backup-directory-alist)
+(custom-set-variables
+ '(tramp-backup-directory-alist backup-directory-alist 6 nil (tramp)))
+@end group
@end lisp
@noindent
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 variable
-@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.
+directory specified by the user option
+@option{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 @code{auto-save-file-name-transforms} to @code{nil} to save
+Set @option{auto-save-file-name-transforms} to @code{nil} to save
auto-saved files to the same directory as the original file.
-Alternatively, set the variable @code{tramp-auto-save-directory} to
-direct all auto saves to that location.
+Alternatively, set the user option @option{tramp-auto-save-directory}
+to direct all auto saves to that location.
@node Windows setup hints
@section Issues with Cygwin ssh
@value{tramp} completion choices show up as
@example
+@group
@c @multitable {@trampfn{telnet,melancholia.danann.net,}} {@trampfn{telnet,192.168.0.1,}}
@multitable @columnfractions .5 .5
@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/
@item @value{prefixhop}toto@value{postfix} @tab
@end multitable
+@end group
@end example
@samp{@value{prefixhop}telnet@value{postfixhop}} is a possible
shows host names @value{tramp} from @file{/etc/hosts} file, for example.
@example
+@group
@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 @value{prefix}telnet@value{postfixhop}@value{ipv6prefix}::1@value{ipv6postfix}@value{postfix} @tab @trampfn{telnet,localhost,}
@item @trampfn{telnet,melancholia.danann.net,} @tab @trampfn{telnet,melancholia,}
@end multitable
+@end group
@end example
Choose a host from the above list and then continue to complete file
Example:
@example
+@group
@kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin//etc} @key{TAB}}
@print{} @trampfn{telnet,melancholia,/etc}
@kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin///etc} @key{TAB}}
@print{} /etc
+@end group
@end example
During file name completion, remote directory contents are re-read
caching}).
@defopt tramp-completion-reread-directory-timeout
-@vindex tramp-completion-reread-directory-timeout
The timeout is number of seconds since last remote command for
-rereading remote directory contents. 0 re-reads immediately during
-file name completion, @code{nil} uses cached directory contents.
+rereading remote directory contents. A value of 0 re-reads
+immediately during file name completion, @code{nil} uses cached
+directory contents.
@end defopt
@cindex proxy hosts, ad-hoc
@value{tramp} file name syntax can accommodate ad hoc specification of
-multiple proxies without using @code{tramp-default-proxies-alist}
+multiple proxies without using @option{tramp-default-proxies-alist}
configuration setup(@pxref{Multi-hops}).
Each proxy is specified using the same syntax as the remote host
Proxies can take patterns @code{%h} or @code{%u}.
@value{tramp} adds the ad-hoc definitions on the fly to
-@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:
+@option{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
-@vindex 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}.
+@option{tramp-save-ad-hoc-proxies} to non-@code{nil}.
@lisp
-(setq tramp-save-ad-hoc-proxies t)
+(custom-set-variables '(tramp-save-ad-hoc-proxies t nil (tramp)))
@end lisp
@end defopt
host when the variable @code{default-directory} is remote:
@lisp
+@group
(let ((default-directory "/ssh:remote.host:"))
(start-file-process "grep" (get-buffer-create "*grep*")
"/bin/sh" "-c" "grep -e tramp *"))
+@end group
@end lisp
Remote processes do not apply to GVFS (see @ref{GVFS based methods})
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
-@code{tramp-remote-path} (see @ref{Remote programs}):
+@option{tramp-remote-path} (see @ref{Remote programs}):
@lisp
+@group
(add-to-list 'tramp-remote-path "~/bin")
(add-to-list 'tramp-remote-path "/appli/pub/bin")
+@end group
@end lisp
-Customize @code{tramp-remote-process-environment} to suit the remote
-program's environment for the remote host.
-@code{tramp-remote-process-environment} is a list of strings
+Customize user option @option{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
structured similar to @code{process-environment}, where each element
is a string of the form @samp{ENVVARNAME=VALUE}.
@end lisp
Modifying or deleting already existing values in the
-@code{tramp-remote-process-environment} list may not be feasible on
+@option{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
-@code{tramp-remote-process-environment} by the following code in the
+@option{tramp-remote-process-environment} by the following code in the
local @file{.emacs} file:
@lisp
+@group
(let ((process-environment tramp-remote-process-environment))
(setenv "HISTORY" nil)
(setq tramp-remote-process-environment process-environment))
+@end group
@end lisp
Setting the @env{ENV} environment variable instructs some shells to
this. You could overwrite this behaviour by evaluating
@lisp
+@group
(let ((process-environment tramp-remote-process-environment))
(setenv "ENV" "$HOME/.profile")
(setq tramp-remote-process-environment process-environment))
+@end group
@end lisp
@value{tramp} does not use the defaults specified in
them as follows:
@lisp
+@group
(let ((process-environment (cons "HGPLAIN=1" process-environment)))
(process-file @dots{}))
+@end group
@end lisp
This works only for environment variables not already set in the
follows in the local @file{.emacs} file:
@lisp
+@group
(add-to-list 'tramp-remote-process-environment
(format "DISPLAY=%s" (getenv "DISPLAY")))
+@end group
@end lisp
@noindent
host. Example:
@example
+@group
@kbd{C-x C-f @trampfn{sudo,,} @key{RET}}
@kbd{M-! tail -f /var/log/syslog.log & @key{RET}}
+@end group
@end example
@command{tail} command outputs continuously to the local buffer,
@kbd{M-x eshell} on a remote host:
@example
+@group
@b{~ $} cd @trampfn{sudo,,/etc} @key{RET}
@b{@trampfn{sudo,root@@host,/etc} $} hostname @key{RET}
host
@b{@trampfn{sudo,root@@host,/etc} $} find-file shadow @key{RET}
#<buffer shadow>
@b{@trampfn{sudo,root@@host,/etc} $}
+@end group
@end example
@code{eshell} in Emacs 23.2 added custom @code{su} and @code{sudo}
commands that set the default directory correctly for the
@file{*eshell*} buffer. @value{tramp} silently updates
-@code{tramp-default-proxies-alist} with an entry for this directory
+@option{tramp-default-proxies-alist} with an entry for this directory
(@pxref{Multi-hops}):
@example
+@group
@b{~ $} cd @trampfn{ssh,user@@remotehost,/etc} @key{RET}
@b{@trampfn{ssh,user@@remotehost,/etc} $} find-file shadow @key{RET}
File is not readable: @trampfn{ssh,user@@remotehost,/etc/shadow}
@b{@trampfn{ssh,user@@remotehost,/etc} $} sudo find-file shadow @key{RET}
#<buffer shadow>
+@end group
+@group
@b{@trampfn{ssh,user@@remotehost,/etc} $} su - @key{RET}
@b{@trampfn{su,root@@remotehost,/root} $} id @key{RET}
uid=0(root) gid=0(root) groups=0(root)
@b{@trampfn{su,root@@remotehost,/root} $}
+@end group
@end example
with a remote file name:
@example
+@group
@kbd{M-x gdb @key{RET}}
@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh,host,~/myprog} @key{RET}
+@end group
@end example
Relative file names are based on the remote default directory. When
calls include:
@example
+@group
@kbd{M-x perldb @key{RET}}
@b{Run perldb (like this):} perl -d myprog.pl @key{RET}
+@end group
@end example
Just the local part of a remote file name, such as @kbd{perl -d
Windows host. To open @command{cmd}, set it as follows:
@lisp
+@group
(setq explicit-shell-file-name "cmd"
explicit-cmd-args '("/q"))
+@end group
@end lisp
@noindent
To open @command{powershell} as a remote shell, use this:
@lisp
+@group
(setq explicit-shell-file-name "powershell"
explicit-powershell-args '("-file" "-"))
+@end group
@end lisp
Use an external method, such as @option{scp}, which are faster than
internal methods.
-Keep the file @code{tramp-persistency-file-name}, which is where
+Keep the file @option{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.
That cache cleanup will be necessary if the remote directories or
files are updated independent of @value{tramp}.
-Set @code{tramp-completion-reread-directory-timeout} to @code{nil} to
+Set @option{tramp-completion-reread-directory-timeout} to @code{nil} to
speed up completions, @ref{File name completion}.
Disable version control to avoid delays:
@lisp
+@group
(setq vc-ignore-dir-regexp
(format "\\(%s\\)\\|\\(%s\\)"
vc-ignore-dir-regexp
tramp-file-name-regexp))
+@end group
@end lisp
Disable excessive traces. Set @code{tramp-verbose} to 3 or lower,
adding the following to @file{~/.config/fish/config.fish}:
@example
+@group
function fish_prompt
if test $TERM = "dumb"
echo "\$ "
@dots{}
end
end
+@end group
@end example
When using WinSSHD on remote hosts, @value{tramp} do not recognize the
@end ifinfo
@lisp
+@group
(add-hook
'find-file-hook
(lambda ()
(when (file-remote-p default-directory)
(set (make-local-variable 'file-precious-flag) t))))
+@end group
@end lisp
@end itemize
with the following command in the @file{~/.ssh/config}:
@example
+@group
Host *
ServerAliveInterval 5
+@end group
@end example
open. That is why @value{tramp} prompts for the password again even
if there is an @command{ssh} already open.
+@vindex tramp-ssh-controlmaster-options
Some @command{ssh} versions support a @code{ControlPersist} option,
which allows you to set the @code{ControlPath} provided the variable
@code{tramp-ssh-controlmaster-options} is customized as follows:
@lisp
+@group
(setq tramp-ssh-controlmaster-options
(concat
"-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p "
"-o ControlMaster=auto -o ControlPersist=yes"))
+@end group
@end lisp
Note how "%r", "%h" and "%p" must be encoded as "%%r", "%%h" and
"%%p".
+@vindex tramp-use-ssh-controlmaster-options
If the @file{~/.ssh/config} is configured appropriately for the above
behavior, then any changes to @command{ssh} can be suppressed with
this @code{nil} setting:
@lisp
-(setq tramp-use-ssh-controlmaster-options nil)
+@group
+(custom-set-variables
+ '(tramp-use-ssh-controlmaster-options nil nil (tramp)))
+@end group
@end lisp
the following code in @file{~/.emacs} file.
@lisp
+@group
(defadvice tramp-handle-write-region
(after tramp-write-beep-advice activate)
"Make 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 tramp beep after copying a file."
(interactive)
(beep))
+@end group
+@group
(defadvice tramp-handle-insert-file-contents
(after tramp-insert-beep-advice activate)
"Make tramp beep after inserting a file."
(interactive)
(beep))
+@end group
@end lisp
Install @file{tramp-theme} from GNU ELPA via Emacs' Package Manager.
Enable it via @kbd{M-x load-theme @key{RET} tramp}. Further
-customization is explained in variable
-@code{tramp-theme-face-remapping-alist}.
+customization is explained in user option
+@option{tramp-theme-face-remapping-alist}.
@item
then set them with a hook as follows:
@lisp
+@group
(add-hook
'dired-before-readin-hook
(lambda ()
(when (file-remote-p default-directory)
(setq dired-actual-switches "-al"))))
+@end group
@end lisp
@file{.kshrc} file:
@example
+@group
if [ -f $HOME/.sh_history ] ; then
/bin/rm $HOME/.sh_history
fi
if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then
unset HISTSIZE
fi
+@end group
@end example
For @option{ssh}-based method, add the following line to your
(@pxref{Default Method}, @pxref{Default User}):
@lisp
-(setq tramp-default-method "ssh"
- tramp-default-user "news")
+@group
+(custom-set-variables
+ '(tramp-default-method "ssh" nil (tramp))
+ '(tramp-default-user "news" nil (tramp)))
+@end group
@end lisp
The reduced typing: @kbd{C-x C-f @trampf{news.my.domain,/opt/news/etc}}.
file @file{~/.ssh/config}:
@example
+@group
Host xy
HostName news.my.domain
User news
+@end group
@end example
The reduced typing: @kbd{C-x C-f @trampfn{ssh,xy,/opt/news/etc}}.
Redefine another key sequence in Emacs for @kbd{C-x C-f}:
@lisp
+@group
(global-set-key
[(control x) (control y)]
(lambda ()
(read-file-name
"Find Tramp file: "
"@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))))
+@end group
@end lisp
Simply typing @kbd{C-x C-y} would prepare minibuffer editing of file
Abbreviation list expansion can be used to reduce typing long file names:
@lisp
+@group
(add-to-list
'directory-abbrev-alist
'("^/xy" . "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))
+@end group
@end lisp
The reduced typing: @kbd{C-x C-f /xy @key{RET}}.
minibuffer:
@lisp
+@group
(define-abbrev-table 'my-tramp-abbrev-table
'(("xy" "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")))
+@end group
+@group
(add-hook
'minibuffer-setup-hook
(lambda ()
(abbrev-mode 1)
(setq local-abbrev-table my-tramp-abbrev-table)))
+@end group
+@group
(defadvice minibuffer-complete
(before my-minibuffer-complete activate)
(expand-abbrev))
+@end group
+@group
;; If you use partial-completion-mode
(defadvice PC-do-completion
(before my-PC-do-completion activate)
(expand-abbrev))
+@end group
@end lisp
The reduced typing: @kbd{C-x C-f xy @key{TAB}}.
directory to the cache:
@lisp
+@group
@c `with-eval-after-load' has been introduced with Emacs 24.4. Shall
@c be used when appropriate.
(eval-after-load "filecache"
'(file-cache-add-directory
"@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))
+@end group
@end lisp
Then use directory completion in the minibuffer with @kbd{C-x C-f
Load @file{bbdb} in Emacs:
@lisp
+@group
(require 'bbdb)
(bbdb-initialize)
+@end group
@end lisp
Create a BBDB entry with @kbd{M-x bbdb-create-ftp-site}. Then specify
a method and user name where needed. Examples:
@example
+@group
@kbd{M-x bbdb-create-ftp-site @key{RET}}
@b{Ftp Site:} news.my.domain @key{RET}
@b{Ftp Directory:} /opt/news/etc/ @key{RET}
@b{Ftp Username:} ssh@value{postfixhop}news @key{RET}
@b{Company:} @key{RET}
@b{Additional Comments:} @key{RET}
+@end group
@end example
In BBDB buffer, access an entry by pressing the key @key{F}.
@file{@trampfn{ssh,bird@@bastion|ssh@value{postfixhop}news.my.domain,/opt/news/etc}}.
Alternatively, when saving abbreviated multi-hop file names
-@file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, the custom
-option @code{tramp-save-ad-hoc-proxies} must be set non-@code{nil}
+@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}
value.
Then on the remote host, start the Emacs Server:
@lisp
+@group
(require 'server)
(setq server-host (system-name)
server-use-tcp t)
(server-start)
+@end group
@end lisp
If @code{(system-name)} of the remote host cannot be resolved on the
script @file{emacsclient.sh}:
@example
+@group
#!/bin/sh
emacsclient @trampfn{ssh,$(whoami)@@$(hostname --fqdn),$1}
+@end group
@end example
Then change the environment variable @env{EDITOR} to point to the
Disable @value{tramp} file name completion:
@lisp
-(custom-set-variables
- '(ido-enable-tramp-completion nil))
+(custom-set-variables '(ido-enable-tramp-completion nil))
@end lisp
@item
in @file{.emacs}:
@lisp
-(setq tramp-default-method "ftp")
+(custom-set-variables '(tramp-default-method "ftp" nil (tramp)))
@end lisp
@item
@code{nil} in @file{.emacs}.
@lisp
-(setq tramp-mode nil)
+(custom-set-variables '(tramp-mode nil nil (tramp)))
@end lisp
@item
non-@code{nil} value.
@lisp
+@group
(let ((non-essential t))
@dots{})
+@end group
@end lisp
attribute changes. The let-bind form to accomplish this:
@lisp
+@group
(let (process-file-side-effects)
@dots{})
+@end group
@end lisp
For asynchronous processes, @value{tramp} uses a process sentinel to
attributes cache in its process sentinel with this code:
@lisp
+@group
(unless (memq (process-status proc) '(run open))
(dired-uncache remote-directory))
+@end group
@end lisp
Since @value{tramp} traverses subdirectories starting with the
both the error and the signal have to be set as follows:
@lisp
+@group
(setq debug-on-error t
debug-on-signal t)
+@end group
@end lisp
To enable stepping through @value{tramp} function call traces, they
have to be specifically enabled as shown in this code:
@lisp
+@group
(require 'trace)
(dolist (elt (all-completions "tramp-" obarray 'functionp))
(trace-function-background (intern elt)))
(untrace-function 'tramp-read-passwd)
(untrace-function 'tramp-gw-basic-authentication)
+@end group
@end lisp
The buffer @file{*trace-output*} contains the output from the function
projects / emacs.git / commitdiff