@include trampver.texi
-@c Macro for formatting a file name according to the respective syntax.
-@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 Macro for formatting a file name according to the respective
+@c syntax. Macro arguments should not have any leading or trailing
+@c 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}
+@macro trampfn {method, userhost, 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
+\method\@value{postfixhop}@c
+\userhost\@value{postfix}\localname\
@end macro
-@macro yyy {one, two}@c
-@xxx{x\one\}@c
-@ifclear x@c
-\one\@w{}\two\@c
-@end ifclear
-@clear x\one\@c
-@end macro
+@c Similar, but without a method prefix.
-@macro trampfn {method, user, host, localname}@c
-@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
+@macro trampf {userhost, localname}
+@value{prefix}@c
+\userhost\@value{postfix}\localname\
@end macro
-@end ifclear
@copying
Copyright @copyright{} 1999--2016 Free Software Foundation, Inc.
@contents
-@ifnottex
@node Top, Overview, (dir), (dir)
@top @value{tramp} version @value{trampver} User Manual
+@ifnottex
This file documents @value{tramp} version @value{trampver}, a remote file
editing package for Emacs.
@end ifhtml
@insertcopying
-
@end ifnottex
@menu
July 2002, @value{tramp} unified file names with Ange-FTP@. In July
2004, proxy hosts replaced multi-hop methods. Running commands on
remote hosts was introduced in December 2005. Support for gateways
-since April 2007.
-@ifset emacsgvfs
-GVFS integration started in February 2009.
-@end ifset
-Remote commands on Windows hosts since September 2011. Ad-hoc
-multi-hop methods (with a changed syntax) re-enabled in November 2011.
-
-In November 2012, added Juergen Hoetzel's @file{tramp-adb.el}.
+since April 2007. GVFS integration started in February 2009. Remote
+commands on Windows hosts since September 2011. Ad-hoc multi-hop
+methods (with a changed syntax) re-enabled in November 2011. In
+November 2012, added Juergen Hoetzel's @file{tramp-adb.el}.
+XEmacs support has been stopped in January 2016.
@c Installation chapter is necessary only in case of standalone
@c installation. Text taken from trampinst.texi.
@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{@trampfn{, user, host, /path/to.file}}. For details,
-see @xref{Default Method}.
+file name @file{@trampf{user@@host,/path/to.file}}. For details, see
+@xref{Default Method}.
For problems related to the behavior of remote shell, see @ref{Remote
shell setup} for details.
@command{rsh} is an option for connecting to hosts within local
networks since @command{rsh} is not as secure as other methods.
-
@item @option{ssh}
@cindex method ssh
@cindex ssh method
@command{ssh} can also take extra parameters as port numbers. For
example, a host on port 42 is specified as @file{host#42} (the real
host name, a hash sign, then a port number). It is the same as passing
-@code{-p 42} to the @command{ssh} command.
+@samp{-p 42} to the @command{ssh} command.
@item @option{telnet}
@cindex method telnet
Connecting to a remote host with @command{telnet} is as insecure
as the @option{rsh} method.
-
@item @option{su}
@cindex method su
@cindex su method
Similar to @option{su} method, @option{sudo} uses @command{sudo}.
@command{sudo} must have sufficient rights to start a shell.
+@item @option{doas}
+@cindex method doas
+@cindex doas method
+
+This method is used on OpenBSD like the @command{sudo} command.
+
+@item @option{sg}
+@cindex method sg
+@cindex sg method
+
+The @command{sg} program allows editing as different group. The host
+can be either @samp{localhost} or the host returned by the function
+@command{(system-name)}. The user name must be specified, but it
+denotes a group name. See @ref{Multi-hops} for an exception to this
+behavior.
+
@item @option{sshx}
@cindex method sshx
@cindex sshx method
This is another method from the Kerberos suite. It behaves like @option{su}.
-
@item @option{plink}
@cindex method plink
@cindex plink method
@option{plink} method supports the @samp{-P} argument.
-
@item @option{plinkx}
@cindex method plinkx
@cindex plinkx method
This method supports the @samp{-p} argument.
-
@item @option{scpx}---@command{ssh} and @command{scp}
@cindex method scpx
@cindex scpx method
This method supports the @samp{-p} argument.
-
@item @option{pscp}---@command{plink} and @command{pscp}
@item @option{psftp}---@command{plink} and @command{psftp}
@cindex method pscp
These methods support the @samp{-P} argument.
-
@item @option{fcp}---@command{fsh} and @command{fcp}
@cindex method fcp
@cindex fcp method
ftp program is specified by Ange FTP. This external program must be
capable of servicing requests from @value{tramp}.
-
@item @option{smb}---@command{smbclient}
@cindex method smb
@cindex smb method
-This is another non-native @value{tramp} method. @command{smbclient}
-connects to any host with SMB/CIFS protocol, such as MS Windows and
-Samba Servers running on Unixes. Tests show this @value{tramp} method
-works with MS Windows NT, MS Windows 2000, MS Windows XP, MS Windows
-Vista, and MS Windows 7.
+This non-native @value{tramp} method connects via the Server Message
+Block (SMB) networking protocol to hosts running file servers that are
+typically based on @url{https://www.samba.org/,,Samba} or MS Windows.
Using @command{smbclient} requires a few tweaks when working with
@value{tramp}:
The first directory in the localname must be a share name on the
remote host.
-Since smb shares end in the @code{$} character, @value{tramp} must use
+Since SMB shares end in the @code{$} character, @value{tramp} must use
@code{$$} when specifying those shares to avoid environment variable
substitutions.
When @value{tramp} is not specific about the share name or uses the
-generic remote directory @code{/}, @command{smbclient} returns all
+generic remote directory @file{/}, @command{smbclient} returns all
available shares.
Since SMB authentication is based on each SMB share, @value{tramp}
percent symbol, and domain is the windows domain name). An example:
@example
-@trampfn{smb, daniel%BIZARRE, melancholia, /daniel$$/.emacs}
+@trampfn{smb,daniel%BIZARRE@@melancholia,/daniel$$/.emacs}
@end example
where user @code{daniel} connects as a domain user to the SMB host
UPPERCASE as shown here:
@example
-@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}
+@trampfn{smb,daniel%MELANCHOLIA@@melancholia,/daniel$$/.emacs}
@end example
where user @code{daniel} connects as local user to the SMB host
behavior is unlike other @value{tramp} methods, where local user name
is substituted.
-@option{smb} method is unavailable if Emacs is run under a local user
-authentication context in MS Windows. However such users can still
-access remote files using UNC file names instead of @value{tramp}:
+The @option{smb} method is unavailable if Emacs is run under a local
+user authentication context in MS Windows. However such users can
+still access remote files using UNC file names instead of @value{tramp}:
@example
//melancholia/daniel$$/.emacs
@end example
-UNC file name specification does not allow to specify a different user
-name for authentication like the @command{smbclient} can.
+UNC file name specification does not allow the specification of a
+different user name for authentication like the @command{smbclient}
+can.
@item @option{adb}
@value{tramp} does not require a host name part of the remote file
name when a single Android device is connected to @command{adb}.
-@value{tramp} instead uses @file{@trampfn{adb, , ,}} as the default
-name. @command{adb devices} shows available host names.
+@value{tramp} instead uses @file{@trampfn{adb,,}} as the default name.
+@command{adb devices} shows available host names.
@option{adb} method normally does not need user name to authenticate
-on the Andriod device because it runs under the @command{adbd}
+on the Android device because it runs under the @command{adbd}
process. But when a user name is specified, however, @value{tramp}
applies an @command{su} in the syntax. When authentication does not
succeed, especially on un-rooted Android devices, @value{tramp}
displays login errors.
-For Andriod devices connected through TCP/IP, a port number can be
+For Android devices connected through TCP/IP, a port number can be
specified using @file{device#42} host name syntax or @value{tramp} can
use the default value as declared in @command{adb} command. Port
numbers are not applicable to Android devices connected through USB@.
@end table
-@ifset emacsgvfs
@node GVFS based methods
@section GVFS based external methods
@cindex methods, gvfs
This method is for connecting to remote hosts with the Apple Filing
Protocol for accessing files on Mac OS X volumes. @value{tramp} access
syntax requires a leading volume (share) name, for example:
-@file{@trampfn{afp, user, host, /volume}}.
+@file{@trampfn{afp,user@@host,/volume}}.
@item @option{dav}
@item @option{davs}
based on standard protocols, such as HTTP@. @option{davs} does the same
but with SSL encryption. Both methods support the port numbers.
+@item @option{gdrive}
+@cindex method gdrive
+@cindex gdrive method
+@cindex Google Drive
+
+Via the @option{gdrive} method it is possible to access your Google
+Drive online storage. User and host name of the remote file name are
+your email address of the Google Drive credentials, like
+@file{@trampfn{gdrive,john.doe@@gmail.com,/}}. These credentials must
+be populated in your @command{Online Accounts} application outside Emacs.
+
+Since Google Drive uses cryptic blob file names internally,
+@value{tramp} works with the @code{display-name} of the files. This
+could produce unexpected behaviour in case two files in the same
+directory have the same @code{display-name}, such a situation must be avoided.
+
@item @option{obex}
@cindex method obex
@cindex obex method
OBEX is an FTP-like access protocol for cell phones and similar simple
devices. @value{tramp} supports OBEX over Bluetooth.
-
@item @option{sftp}
@cindex method sftp
@cindex sftp method
@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},
-@option{obex}, @option{sftp} and @option{synce}. Other methods to
-include are: @option{ftp} and @option{smb}.
+@option{gdrive}, @option{obex}, @option{sftp} and @option{synce}.
+Other methods to include are: @option{ftp} and @option{smb}.
@end defopt
-@end ifset
@node Gateway methods
Authentication} (see RFC 2617). When no port number is specified, this
protocol defaults to @option{8080}.
-
@item @option{socks}
@cindex method socks
@cindex socks method
@file{/etc/motd} file on the otherhost:
@example
-@kbd{C-x C-f @trampfn{ssh, root, otherhost,/etc/motd} @key{RET}}
+@kbd{C-x C-f @trampfn{ssh,root@@otherhost,/etc/motd} @key{RET}}
@end example
If @option{ssh} is unavailable for whatever reason, look for other
the shortened syntax of @samp{root}:
@example
-@kbd{C-x C-f @trampfn{su, , , /etc/motd} @key{RET}}
+@kbd{C-x C-f @trampfn{su,,/etc/motd} @key{RET}}
@end example
For editing large files, @option{scp} is faster than @option{ssh}.
tramp-default-host "target")
@end lisp
-With both defaults set, @samp{@trampfn{ssh, , ,}} will connect
+With both defaults set, @samp{@trampfn{ssh,,}} will connect
@value{tramp} to John's home directory on target.
@strong{Note} @samp{/::} won't work, because @samp{/:} is the prefix
@lisp
(add-to-list 'tramp-default-proxies-alist
- '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}"))
+ '("\\." nil "@trampfn{ssh,bird@@bastion.your.domain,}"))
(add-to-list 'tramp-default-proxies-alist
'("\\.your\\.domain\\'" nil nil))
@end lisp
(add-to-list 'tramp-default-proxies-alist
'("\\`bastion\\.your\\.domain\\'"
"\\`bird\\'"
- "@trampfn{ssh, , jump.your.domain,}"))
+ "@trampfn{ssh,jump.your.domain,}"))
@end lisp
@var{proxy} can take patterns @code{%h} or @code{%u} for @var{host} or
@lisp
(add-to-list 'tramp-default-proxies-alist
- '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
+ '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh,%h,}"))
@end lisp
-Opening @file{@trampfn{sudo, , randomhost.your.domain,}} first
-connects to @samp{randomhost.your.domain} via @code{ssh} under your
-account name, and then perform @code{sudo -u root} on that host.
+Opening @file{@trampfn{sudo,randomhost.your.domain,}} first connects
+to @samp{randomhost.your.domain} via @code{ssh} under your account
+name, and then perform @code{sudo -u root} on that host.
It is key for the sudo method in the above example to be applied on
the host after reaching it and not on the local host.
@lisp
(add-to-list 'tramp-default-proxies-alist
- '(nil "\\`root\\'" "@trampfn{ssh, , %h,}"))
+ '(nil "\\`root\\'" "@trampfn{ssh,%h,}"))
(add-to-list 'tramp-default-proxies-alist
'((regexp-quote (system-name)) nil nil))
@end lisp
@lisp
(add-to-list 'tramp-default-proxies-alist
'("\\`host\\.other\\.domain\\'" nil
- "@trampfn{tunnel, , proxy.your.domain#3128,}"))
+ "@trampfn{tunnel,proxy.your.domain#3128,}"))
@end lisp
Gateway methods in a multiple hop chain can be declared only as the first hop.
A function which parses @file{/etc/passwd} files for user names.
+@item @code{tramp-parse-etc-group}
+@findex tramp-parse-etc-group
+
+A function which parses @file{/etc/group} files for group names.
+
@item @code{tramp-parse-netrc}
@findex tramp-parse-netrc
Set @code{password-cache} to @code{nil} to disable password caching.
-@strong{Implementation Note}: password caching depends on
-@file{password-cache.el} package. @value{tramp} activates password
-caching only if @value{tramp} can discover, while Emacs is loading,
-the package through @code{load-path}.
-
-@ifset installchapter
-@file{password.el} is available from No Gnus or from the @value{tramp}
-@file{contrib} directory, see @ref{Installation parameters}.
-@end ifset
-
@node Connection caching
@section Reusing connection related information
information. For example, connecting to a host using @command{ssh} and
connecting to the same host through @code{sshd} on port 3001. Both
access methods result in nearly identical persistent specifications
-@file{@trampfn{ssh, , localhost,}} and @file{@trampfn{ssh, ,
-localhost#3001,}}.
+@file{@trampfn{ssh,localhost,}} and @file{@trampfn{ssh,localhost#3001,}}.
Changing host names could avoid duplicates. One way is to add a
@option{Host} section in @file{~/.ssh/config} (@pxref{Frequently Asked
@lisp
(add-to-list 'tramp-connection-properties
- (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
+ (list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}")
"remote-shell" "/bin/ksh"))
(add-to-list 'tramp-connection-properties
- (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
+ (list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}")
"remote-shell-login" '("-")))
@end lisp
@lisp
(add-to-list 'tramp-connection-properties
- (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
+ (list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}")
"busybox" t))
@end lisp
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 logging. However, @code{tramp-own-remote-path}
+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}.
@lisp
(add-to-list 'tramp-remote-path 'tramp-own-remote-path)
@end lisp
+
+@strong{Note} that this works only if your remote @command{/bin/sh}
+shell supports the login argument @samp{-l}.
@end defopt
When remote search paths are changed, local @value{tramp} caches must
@end example
The above command-line syntax has changed with @command{busybox}
-versions. If @command{nc} refuses the @command{-p} parameter, then
+versions. If @command{nc} refuses the @samp{-p} parameter, then
overwrite as follows:
@lisp
@value{tramp} uses the @option{adb} method to access Android
devices. Android devices provide a restricted shell access through an
-USB connection. The local host must have Andriod SDK installed.
+USB connection. The local host must have the Android SDK installed.
Applications such as @code{SSHDroid} that run @command{sshd} process
on the Android device can accept any @option{ssh}-based methods
provided these settings are adjusted:
-@code{sh} must be specified for remote shell since Android devices do
-not provide @code{/bin/sh}. @code{sh} will then invoke whatever shell is
-installed on the device with this setting:
+@command{sh} must be specified for remote shell since Android devices
+do not provide @command{/bin/sh}. @command{sh} will then invoke
+whatever shell is installed on the device with this setting:
@lisp
(add-to-list 'tramp-connection-properties
@end lisp
@noindent
-Open a remote connection with the command @kbd{C-x C-f @trampfn{ssh, ,
-192.168.0.26#2222, }}, where @command{sshd} is listening on port
-@samp{2222}.
+Open a remote connection with the command @kbd{C-x C-f
+@trampfn{ssh,192.168.0.26#2222,}}, where @command{sshd} is listening
+on port @samp{2222}.
To add a corresponding entry to the @file{~/.ssh/config} file
(recommended), use this:
@noindent
Open a remote connection with a more concise command @kbd{C-x C-f
-@trampfn{ssh, , android, }}.
+@trampfn{ssh,android,}}.
@node Auto-save and Backup
@cindex backup
@vindex backup-directory-alist
-To avoid @value{tramp} from saving backup files owned by root to
-locations accessible to others, default backup settings in
+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.
Here's a scenario where files could be inadvertently exposed. Emacs
files unless changed to another location, such as
@file{~/.emacs.d/backups/}. Such a directory will also be used by
default by @value{tramp} when using, say, a restricted file
-@file{@trampfn{su, root, localhost, /etc/secretfile}}. The backup
-file of the secretfile is now owned by the user logged in from tramp
-and not root.
+@file{@trampfn{su,root@@localhost,/etc/secretfile}}. The backup file
+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
problems do not occur.
-To ``turns off'' the backup feature for @value{tramp} files and stop
+To ``turn off'' the backup feature for @value{tramp} files and stop
@value{tramp} from saving to the backup directory, use this:
@lisp
@end lisp
@noindent
-Disabling backups can be targetted to just @option{su} and
+Disabling backups can be targeted to just the @option{su} and
@option{sudo} methods:
@lisp
@end lisp
@noindent
-The backup file name of @file{@trampfn{su, root, localhost,
-/etc/secretfile}} would be @file{@trampfn{su, root, localhost,
-~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
+The backup file name of
+@file{@trampfn{su,root@@localhost,/etc/secretfile}} would be
+@ifset unified
+@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
+@end ifset
+@ifset separate
+@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}
+@end ifset
Just as for backup files, similar issues of file naming affect
auto-saving @value{tramp} files. Auto-saved files are saved in the
Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To
check for compatibility: type @kbd{M-x eshell}, and start @kbd{ssh
-test.host}. Incompatbilities trigger this message:
+test.host}. Incompatibilities trigger this message:
@example
Pseudo-terminal will not be allocated because stdin is not a terminal.
Unlike opening local files in Emacs, which are instantaneous, opening
remote files in @value{tramp} is slower at first. Sometimes there is
-a noticable delay before the prompts for passwords or authentication
+a noticeable delay before the prompts for passwords or authentication
appear in the minibuffer. Hitting @kbd{@key{RET}} or other keys
during this gap will be processed by Emacs. This type-ahead facility
is a feature of Emacs that may cause missed prompts when using
@cindex file name syntax
@cindex file name examples
-@file{@trampfn{, , host, localfilename}}
-opens file @var{localfilename} on the remote host @var{host}, using
-the default method. @xref{Default Method}.
+@file{@trampf{host,localfilename}} opens file @var{localfilename} on
+the remote host @var{host}, using the default method. @xref{Default
+Method}.
@table @file
@item @value{prefix}melancholia@value{postfix}.emacs
@end table
-@var{host} can take IPv4 or IPv6 address, as in @file{@trampfn{, ,
-127.0.0.1, .emacs}} or @file{@trampfn{, ,
-@value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}. For syntactical
-reasons, IPv6 addresses must be embedded in square brackets
-@file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
+@var{host} can take IPv4 or IPv6 address, as in
+@file{@trampf{127.0.0.1,.emacs}} or
+@file{@trampf{@value{ipv6prefix}::1@value{ipv6postfix},.emacs}}.
+@ifset unified
+For syntactical reasons, IPv6 addresses must be embedded in square
+brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
+@end ifset
By default, @value{tramp} will use the current local user name as the
remote user name for log in to the remote host. Specifying a different
name using the proper syntax will override this default behavior:
@example
-@trampfn{, user, host, path/to.file}
+@trampf{user@@host,path/to.file}
@end example
-@file{@trampfn{, daniel, melancholia, .emacs}} is for file
-@file{.emacs} in @code{daniel}'s home directory on the host,
-@code{melancholia}.
+@file{@trampf{daniel@@melancholia,.emacs}} is for file @file{.emacs}
+in @code{daniel}'s home directory on the host, @code{melancholia}.
Specify other file access methods (@pxref{Inline methods},
@pxref{External methods}) as part of the file name.
Method name comes before user name, as in
@file{@value{prefix}@var{method}@value{postfixhop}} (Note the trailing
-colon). The syntax specificaton for user, host, and file do not
+colon). The syntax specifications for user, host, and file do not
change.
To connect to the host @code{melancholia} as @code{daniel}, using
@option{ssh} method for @file{.emacs} in @code{daniel}'s home
-directory, the full specification is: @file{@trampfn{ssh, daniel,
-melancholia, .emacs}}.
+directory, the full specification is:
+@file{@trampfn{ssh,daniel@@melancholia,.emacs}}.
A remote file name containing a host name, which is the same string as
a method name, is not allowed.
For specifying port numbers, affix @file{#<port>} to the host
-name. For example: @file{@trampfn{ssh, daniel, melancholia#42,
-.emacs}}.
+name. For example: @file{@trampfn{ssh,daniel@@melancholia#42,.emacs}}.
@node File name completion
@value{tramp} completion choices show up as
@example
-@c @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
@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/
@item @value{prefixhop}toto@value{postfix} @tab
@example
@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,}
+@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,}
+@c @item @trampfn{telnet,@value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet,localhost,}
+@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 example
completion lists.
After remote host name completion comes completion of file names on
-the remote host. It works the same as on loal host file completion
-except when killing with double-slash @file{//} kills only the file
+the remote host. It works the same as with local host file completion
+except that killing with double-slash @file{//} kills only the file
name part of the @value{tramp} file name syntax. A triple-slash
stands for the default behavior.
@ifinfo
Example:
@example
-@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{} @trampfn{telnet,melancholia,/etc}
-@kbd{C-x C-f @trampfn{telnet, , melancholia, //etc} @key{TAB}}
+@kbd{C-x C-f @trampfn{telnet,melancholia,//etc} @key{TAB}}
@print{} /etc
-@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin///etc} @key{TAB}}
+@kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin///etc} @key{TAB}}
@print{} /etc
@end example
proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}:
@example
-@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh, you,
-@c remotehost, /path}}
+@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you,remotehost,/path}}
@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path}
@end example
@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: @samp{@trampfn{ssh, you,
-remotehost, /path}}.
+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
"/bin/sh" "-c" "grep -e tramp *"))
@end lisp
-
-@ifset emacsgvfs
Remote processes do not apply to GVFS (see @ref{GVFS based methods})
because the remote file system is mounted on the local host and
@value{tramp} just accesses by changing the @code{default-directory}.
-@end ifset
@value{tramp} starts a remote process when a command is executed in a
remote file or directory buffer. As of now, these packages have been
host. Example:
@example
-@kbd{C-x C-f @trampfn{sudo, , , } @key{RET}}
+@kbd{C-x C-f @trampfn{sudo,,} @key{RET}}
@kbd{M-! tail -f /var/log/syslog.log & @key{RET}}
@end example
@kbd{M-x eshell} on a remote host:
@example
-@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
-@b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET}
+@b{~ $} cd @trampfn{sudo,,/etc} @key{RET}
+@b{@trampfn{sudo,root@@host,/etc} $} hostname @key{RET}
host
-@b{@trampfn{sudo, root, host, /etc} $} id @key{RET}
+@b{@trampfn{sudo,root@@host,/etc} $} id @key{RET}
uid=0(root) gid=0(root) groups=0(root)
-@b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET}
+@b{@trampfn{sudo,root@@host,/etc} $} find-file shadow @key{RET}
#<buffer shadow>
-@b{@trampfn{sudo, root, host, /etc} $}
+@b{@trampfn{sudo,root@@host,/etc} $}
@end example
@code{eshell} in Emacs 23.2 added custom @code{su} and @code{sudo}
(@pxref{Multi-hops}):
@example
-@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}
+@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>
-@b{@trampfn{ssh, user, remotehost, /etc} $} su - @key{RET}
-@b{@trampfn{su, root, remotehost, /root} $} id @key{RET}
+@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} $}
+@b{@trampfn{su,root@@remotehost,/root} $}
@end example
@example
@kbd{M-x gdb @key{RET}}
-@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET}
+@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh,host,~/myprog} @key{RET}
@end example
Relative file names are based on the remote default directory. When
-@file{myprog.pl} exists in @file{@trampfn{ssh, , host, /home/user}},
-valid calls include:
+@file{myprog.pl} exists in @file{@trampfn{ssh,host,/home/user}}, valid
+calls include:
@example
@kbd{M-x perldb @key{RET}}
This command flushes all connection related objects. @option{vec} is
the internal representation of a remote connection. When called
interactively, this command lists active remote connections in the
-minibuffer. Each connection is of the format @file{@trampfn{method,
-user, host, }}. Flushing remote connections also cleans the password
-cache (@pxref{Password handling}), file cache, connection cache
-(@pxref{Connection caching}), and connection buffers.
+minibuffer. Each connection is of the format
+@file{@trampfn{method,user@@host,}}. Flushing remote connections also
+cleans the password cache (@pxref{Password handling}), file cache,
+connection cache (@pxref{Connection caching}), and connection buffers.
@end deffn
@deffn Command tramp-cleanup-this-connection
if there is an @command{ssh} already open.
Some @command{ssh} versions support a @code{ControlPersist} option,
-which allows to set the @code{ControlPath} provided the variable
+which allows you to set the @code{ControlPath} provided the variable
@code{tramp-ssh-controlmaster-options} is customized as follows:
@lisp
of @command{ls} is in color.
To disable @acronym{ANSI} escape sequences from the remote hosts,
-disable @option{--color=yes} or @option{--color=auto} in the remote
-host's @file{.bashrc} or @file{.profile}. Turn this alias on and off
-to see if file name completion works.
+disable @samp{--color=yes} or @samp{--color=auto} in the remote host's
+@file{.bashrc} or @file{.profile}. Turn this alias on and off to see
+if file name completion works.
@item
File name completion does not work in directories with large number of
globbing.
To test if globbing hangs, open a shell on the remote host and then
-run @samp{ls -d * ..?* > /dev/null}.
+run @command{ls -d * ..?* > /dev/null}.
When testing, ensure the remote shell is the same shell
(@command{/bin/sh}, @command{ksh} or @command{bash}), that
@item
-How to get a Visual Warning when working with @samp{root} privileges
-
-Get a modeline indication when working with @samp{root} privileges
-with the following code (tested with Emacs 22.1) in @file{~/.emacs}
-file:
-
-@lisp
-(defun my-mode-line-function ()
- (when (string-match "^/su\\(do\\)?:" default-directory)
- (setq mode-line-format
- (format-mode-line mode-line-format 'font-lock-warning-face))))
-
-(add-hook 'find-file-hook 'my-mode-line-function)
-(add-hook 'dired-mode-hook 'my-mode-line-function)
-@end lisp
-
-
-@item
-How to get host indication in the mode line?
-
-The following code (tested with Emacs 22.1) in @file{~/.emacs} file
-shows it:
-
-@lisp
-(defconst my-mode-line-buffer-identification
- (list
- '(:eval
- (let ((host-name
- (if (file-remote-p default-directory)
- (tramp-file-name-host
- (tramp-dissect-file-name default-directory))
- (system-name))))
- (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
- (substring host-name 0 (match-beginning 1))
- host-name)))
- ": %12b"))
-
-(setq-default
- mode-line-buffer-identification
- my-mode-line-buffer-identification)
-
-(add-hook
- 'dired-mode-hook
- (lambda ()
- (setq
- mode-line-buffer-identification
- my-mode-line-buffer-identification)))
-@end lisp
-
-The mode line in Emacs 23.1 and later versions now contains an
-indication if @code{default-directory} for the current buffer is on a
-remote host. Moreover, the corresponding tool-tip shows the remote
-host name. The above @code{:eval} clause can also be simplified to
-show the host name in the mode line:
+How to get a Visual Warning when working with @samp{root} privileges?
+Host indication in the mode line?
-@lisp
- '(:eval
- (let ((host-name
- (or (file-remote-p default-directory 'host)
- (system-name))))
- (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
- (substring host-name 0 (match-beginning 1))
- host-name)))
-@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}.
@item
How to shorten long file names when typing in @value{tramp}?
Adapt several of these approaches to reduce typing. If the full name
-is @file{@trampfn{ssh, news, news.my.domain, /opt/news/etc}}, then:
+is @file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, then:
@enumerate
tramp-default-user "news")
@end lisp
-The reduced typing: @kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
+The reduced typing: @kbd{C-x C-f @trampf{news.my.domain,/opt/news/etc}}.
@strong{Note} that there are some useful shortcuts already. Accessing
your local host as @samp{root} user, is possible just by @kbd{C-x C-f
-@trampfn{su, , ,}}.
+@trampfn{su,,}}.
@item
Use configuration options of the access method:
User news
@end example
-The reduced typing: @kbd{C-x C-f @trampfn{ssh, , xy, /opt/news/etc}}.
+The reduced typing: @kbd{C-x C-f @trampfn{ssh,xy,/opt/news/etc}}.
Depending on the number of files in the directories, host names
completion can further reduce key strokes: @kbd{C-x C-f
inside Emacs with Lisp:
@lisp
-(setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")
+(setenv "xy" "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")
@end lisp
The reduced typing: @kbd{C-x C-f $xy @key{RET}}.
(find-file
(read-file-name
"Find Tramp file: "
- "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))))
+ "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))))
@end lisp
Simply typing @kbd{C-x C-y} would prepare minibuffer editing of file
@lisp
(add-to-list
'directory-abbrev-alist
- '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
+ '("^/xy" . "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))
@end lisp
The reduced typing: @kbd{C-x C-f /xy @key{RET}}.
@lisp
(define-abbrev-table 'my-tramp-abbrev-table
- '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))
+ '(("xy" "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")))
(add-hook
'minibuffer-setup-hook
directory to the cache:
@lisp
+@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/}"))
+ "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))
@end lisp
Then use directory completion in the minibuffer with @kbd{C-x C-f
When saving ad-hoc multi-hop @value{tramp} file names (@pxref{Ad-hoc
multi-hops}) via bookmarks, recent files, filecache, bbdb, or another
package, use the full ad-hoc file name including all hops, like
-@file{@trampfn{ssh, bird, bastion|ssh@value{postfixhop}news.my.domain,
-/opt/news/etc}}.
+@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
+@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}
value.
Then start Emacs Client from the command line:
@example
-emacsclient @trampfn{ssh, user, host, /file/to/edit}
+emacsclient @trampfn{ssh,user@@host,/file/to/edit}
@end example
@code{user} and @code{host} refer to the local host.
@example
#!/bin/sh
-emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1}
+emacsclient @trampfn{ssh,$(whoami)@@$(hostname --fqdn),$1}
@end example
Then change the environment variable @env{EDITOR} to point to the