\input texinfo @c -*-texinfo-*-
-@c %**start of header
@setfilename ../info/tramp
+@c %**start of header
@settitle TRAMP User Manual
@setchapternewpage odd
@c %**end of header
@include trampver.texi
-@c Macros for formatting a filename.
-@c trampfn is for a full filename, trampfnmhl means method, host, localname
-@c were given, and so on.
-@macro trampfn {method, user, host, localname}
-@value{prefix}\method\@value{postfixhop}\user\@@\host\@value{postfix}\localname\
-@end macro
+@c Macro for formatting a filename according to the repective 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.
-@macro trampfnmhl {method, host, localname}
-@value{prefix}\method\@value{postfixhop}\host\@value{postfix}\localname\
+@macro xxx {one}@c
+@set \one\@c
@end macro
-@macro trampfnuhl {user, host, localname}
-@value{prefix}\user\@@\host\@value{postfix}\localname\
+@macro yyy {one, two}@c
+@xxx{x\one\}@c
+@ifclear x@c
+\one\@w{}\two\@c
+@end ifclear
+@clear x\one\@c
@end macro
-@macro trampfnhl {host, localname}
-@value{prefix}\host\@value{postfix}\localname\
+@macro trampfn {method, user, host, localname}@c
+@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
@end macro
@copying
installed. It is initially configured to use the @command{scp}
program to connect to the remote host. So in the easiest case, you
just type @kbd{C-x C-f} and then enter the filename
-@file{@trampfnuhl{user, machine, /path/to.file}}.
+@file{@trampfn{, user, machine, /path/to.file}}.
On some hosts, there are problems with opening a connection. These are
related to the behavior of the remote shell. See @xref{Remote shell
For the special case of editing files on the local host as another
user, see the @option{su} or @option{sudo} methods. They offer
shortened syntax for the @samp{root} account, like
-@file{@trampfnmhl{su, , /etc/motd}}.
+@file{@trampfn{su, , , /etc/motd}}.
People who edit large files may want to consider @option{scpc} instead
of @option{ssh}, or @option{pscp} instead of @option{plink}. These
tramp-default-host "target")
@end lisp
-Then the simple file name @samp{@trampfnmhl{ssh,,}} will connect you
+Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you
to John's home directory on target.
@ifset emacs
-Note, however, that the most simplification @samp{@trampfnmhl{,,}}
-won't work, because @samp{/:} is the prefix for quoted file names.
+Note, however, that the most simplification @samp{/::} won't work,
+because @samp{/:} is the prefix for quoted file names.
@end ifset
(add-to-list 'tramp-default-proxies-alist
'("\\`bastion\\.your\\.domain\\'"
"\\`bird\\'"
- "@trampfnmhl{ssh, jump.your.domain,}"))
+ "@trampfn{ssh, , jump.your.domain,}"))
@end lisp
@var{proxy} can contain the patterns @code{%h} or @code{%u}. These
@lisp
(add-to-list 'tramp-default-proxies-alist
- '("\\.your\\.domain\\'" "\\`root\\'" "@trampfnmhl{ssh, %h,}"))
+ '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
@end lisp
-Opening @file{@trampfnmhl{sudo, randomhost.your.domain,}} would
-connect first @samp{randomhost.your.domain} via @code{ssh} under your
-account name, and perform @code{sudo -u root} on that host afterwards.
-It is important to know that the given method is applied on the host
-which has been reached so far. @code{sudo -u root}, applied on your
-local host, wouldn't be useful here.
+Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect
+first @samp{randomhost.your.domain} via @code{ssh} under your account
+name, and perform @code{sudo -u root} on that host afterwards. It is
+important to know that the given method is applied on the host which
+has been reached so far. @code{sudo -u root}, applied on your local
+host, wouldn't be useful here.
This is the recommended configuration to work as @samp{root} on remote
Ubuntu hosts.
@lisp
(add-to-list 'tramp-default-proxies-alist
'("\\`host\\.other\\.domain\\'" nil
- "@trampfnmhl{tunnel, proxy.your.domain#3128,}"))
+ "@trampfn{tunnel, , proxy.your.domain#3128,}"))
@end lisp
Gateway methods can be declared as first hop only in a multiple hop
administrator has put the tools you want in some obscure local
directory.
-In this case, you can still use them with @value{tramp}. You simply need to
-add code to your @file{.emacs} to add the directory to the remote path.
-This will then be searched by @value{tramp} when you connect and the software
-found.
+In this case, you can still use them with @value{tramp}. You simply
+need to add code to your @file{.emacs} to add the directory to the
+remote path. This will then be searched by @value{tramp} when you
+connect and the software found.
To add a directory to the remote search path, you could use code such
as:
(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
@end lisp
+@value{tramp} caches several information, like the Perl binary
+location. The changed remote search path wouldn't affect these
+settings. In order to force @value{tramp} to recompute these values,
+you must exit @value{emacsname}, remove your persistency file
+(@pxref{Connection caching}), and restart @value{emacsname}.
+
@node Remote shell setup
@comment node-name, next, previous, up
@cindex filename examples
To access the file @var{localname} on the remote machine @var{machine}
-you would specify the filename @file{@trampfnhl{@var{machine},
-@var{localname}}}. This will connect to @var{machine} and transfer
-the file using the default method. @xref{Default Method}.
+you would specify the filename @file{@trampfn{, , machine,
+localname}}. This will connect to @var{machine} and transfer the file
+using the default method. @xref{Default Method}.
Some examples of @value{tramp} filenames are shown below.
@table @file
-@item @trampfnhl{melancholia, .emacs}
+@item @trampfn{, , melancholia, .emacs}
Edit the file @file{.emacs} in your home directory on the machine
@code{melancholia}.
-@item @trampfnhl{melancholia.danann.net, .emacs}
+@item @trampfn{, , melancholia.danann.net, .emacs}
This edits the same file, using the fully qualified domain name of
the machine.
-@item @trampfnhl{melancholia, ~/.emacs}
+@item @trampfn{, , melancholia, ~/.emacs}
This also edits the same file --- the @file{~} is expanded to your
home directory on the remote machine, just like it is locally.
-@item @trampfnhl{melancholia, ~daniel/.emacs}
+@item @trampfn{, , melancholia, ~daniel/.emacs}
This edits the file @file{.emacs} in the home directory of the user
@code{daniel} on the machine @code{melancholia}. The @file{~<user>}
construct is expanded to the home directory of that user on the remote
machine.
-@item @trampfnhl{melancholia, /etc/squid.conf}
+@item @trampfn{, , melancholia, /etc/squid.conf}
This edits the file @file{/etc/squid.conf} on the machine
@code{melancholia}.
part of the filename.
To log in to the remote machine as a specific user, you use the syntax
-@file{@trampfnuhl{@var{user}, @var{machine}, @var{path/to.file}}}.
-That means that connecting to @code{melancholia} as @code{daniel} and
-editing @file{.emacs} in your home directory you would specify
-@file{@trampfnuhl{daniel, melancholia, .emacs}}.
+@file{@trampfn{, user, machine, path/to.file}}. That means that
+connecting to @code{melancholia} as @code{daniel} and editing
+@file{.emacs} in your home directory you would specify
+@file{@trampfn{, daniel, melancholia, .emacs}}.
It is also possible to specify other file transfer methods
(@pxref{Default Method}) as part of the filename.
@example
@ifset emacs
-@value{prefixhop}telnet@value{postfixhop} tmp/
+@value{prefixhop}telnet@value{postfixhop} tmp/
@value{prefixhop}toto@value{postfix}
@end ifset
@ifset xemacs
-@value{prefixhop}telnet@value{postfixhop} @value{prefixhop}toto@value{postfix}
+@value{prefixhop}telnet@value{postfixhop} @value{prefixhop}toto@value{postfix}
@end ifset
@end example
your @file{/etc/hosts} file, let's say
@example
-@trampfnmhl{telnet,127.0.0.1,} @trampfnmhl{telnet,192.168.0.1,}
-@trampfnmhl{telnet,localhost,} @trampfnmhl{telnet,melancholia.danann.net,}
-@trampfnmhl{telnet,melancholia,}
+@trampfn{telnet, , 127.0.0.1,} @trampfn{telnet, , 192.168.0.1,}
+@trampfn{telnet, , localhost,} @trampfn{telnet, , melancholia.danann.net,}
+@trampfn{telnet, , melancholia,}
@end example
Now you can choose the desired machine, and you can continue to
@end ifinfo
@ifset emacs
-As example, @kbd{@trampfnmhl{telnet,melancholia,/usr/local/bin//etc}
+As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//etc}
@key{TAB}} would result in
-@file{@trampfnmhl{telnet,melancholia,/etc}}, whereas
-@kbd{@trampfnmhl{telnet,melancholia,//etc} @key{TAB}} reduces the
+@file{@trampfn{telnet, , melancholia, /etc}}, whereas
+@kbd{@trampfn{telnet, , melancholia, //etc} @key{TAB}} reduces the
minibuffer contents to @file{/etc}. A triple-slash stands for the
default behaviour,
-i.e. @kbd{@trampfnmhl{telnet,melancholia,/usr/local/bin///etc}
+i.e. @kbd{@trampfn{telnet, , melancholia, /usr/local/bin///etc}
@key{TAB}} expands directly to @file{/etc}.
@end ifset
@ifset xemacs
-As example, @kbd{@trampfnmhl{telnet,melancholia,/usr/local/bin//}}
-would result in @file{@trampfnmhl{telnet,melancholia,/}}, whereas
-@kbd{@trampfnmhl{telnet,melancholia,//}} expands the minibuffer
+As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//}}
+would result in @file{@trampfn{telnet, , melancholia, /}}, whereas
+@kbd{@trampfn{telnet, , melancholia, //}} expands the minibuffer
contents to @file{/}.
@end ifset
this:
@example
-@b{~ $} cd @trampfnmhl{sudo, , /etc} @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}
@end example
+@anchor{Running a debugger on a remote host}
@subsection Running a debugger on a remote host
@cindex gud
@cindex gdb
@example
@kbd{M-x gdb @key{RET}}
-@b{Run gdb (like this):} gdb --annotate=3 @trampfnmhl{ssh, host, ~/myprog} @key{RET}
+@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET}
@end example
The file name can also be relative to a remote default directory.
Given you are in a buffer that belongs to the remote directory
-@trampfnmhl{ssh, host, /home/user}, you could call
+@trampfn{ssh, , host, /home/user}, you could call
@example
@kbd{M-x perldb @key{RET}}
@end example
It is not possible to use just the absolute local part of a remote
-file name, like @kbd{perl -d /home/user/myprog.pl}, though.
+file name as program to debug, like @kbd{perl -d
+/home/user/myprog.pl}, though.
+
+Arguments of the program to be debugged are taken literally. That
+means file names as arguments must be given as ordinary relative or
+absolute file names, without any remote specification.
@node Bug Reports
Use an external transfer method, like @option{scpc}.
Use caching. This is already enabled by default. Information about
-the remote host as well as the remote files are cached for reuse. Th
+the remote host as well as the remote files are cached for reuse. The
information about remote hosts is kept in the file specified in
@code{tramp-persistency-file-name}. Keep this file.
@item
I'ld like to see a host indication in the mode line when I'm remote
-The following code has been tested with @value{emacsname} 22. You
+The following code has been tested with @value{emacsname} 22.1. You
should put it into your @file{~/.emacs}:
@lisp
(list
'(:eval
(let ((host-name
- (if (file-remote-p default-directory)
- (tramp-file-name-host
- (tramp-dissect-file-name default-directory))
- (system-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)))
+ (substring host-name 0 (match-beginning 1))
+ host-name)))
": %12b"))
(setq-default
mode-line-buffer-identification
my-mode-line-buffer-identification)))
@end lisp
+
+Since @value{emacsname} 23.1, the mode line contains an indication if
+@code{default-directory} for the current buffer is on a remote host.
+The corresponding tooltip includes the name of that host. If you
+still want the host name as part of the mode line, you can use the
+example above, but the @code{:eval} clause can be simplified:
+
+@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
@end ifset
@end lisp
The file name left to type would be
-@kbd{C-x C-f @trampfnhl{news.my.domain, /opt/news/etc}}.
+@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
Note, that there are some useful settings already. Accessing your
local host as @samp{root} user, is possible just by @kbd{C-x C-f
-@trampfnmhl{su,,}}.
+@trampfn{su, , ,}}.
@item Use configuration possibilities of your method:
User news
@end example
-The file name left to type would be @kbd{C-x C-f @trampfnmhl{ssh, xy,
+The file name left to type would be @kbd{C-x C-f @trampfn{ssh, , xy,
/opt/news/etc}}. Depending on files in your directories, it is even
possible to complete the hostname with @kbd{C-x C-f
@value{prefix}ssh@value{postfixhop}x @key{TAB}}.
@lisp
@ifset emacs
-(require 'recentf)
-(add-to-list 'recentf-keep 'file-remote-p)
(recentf-mode 1)
@end ifset
@ifset xemacs
directory.
@end ifset
+@ifset emacs
+@item Use bbdb:
+
+@file{bbdb} has a built-in feature for @value{ftppackagename} files,
+which works also for @value{tramp}.
+@ifinfo
+@pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb}
+@end ifinfo
+
+You need to load @file{bbdb}:
+
+@lisp
+(require 'bbdb)
+(bbdb-initialize)
+@end lisp
+
+Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}.
+Because BBDB is not prepared for @value{tramp} syntax, you must
+specify a method together with the user name, when needed. Example:
+
+@example
+@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 example
+
+When you have opened your BBDB buffer, you can access such an entry by
+pressing the key @key{F}.
+@end ifset
+
@end enumerate
+I would like to thank all @value{tramp} users, who have contributed to
+the different recipes!
+
@item
How can I disable @value{tramp}?