@end macro
@copying
-Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
-2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+Copyright @copyright{} 1999-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end copying
@c Entries for @command{install-info} to use
-@dircategory @value{emacsname}
+@dircategory @value{emacsname} network features
@direntry
* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
@value{emacsname} remote file access via rsh and rcp.
@cindex obtaining Tramp
@value{tramp} is freely available on the Internet and the latest
-release may be downloaded from
-@uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
-documentation and code for @value{tramp}, suitable for installation.
-But GNU Emacs (22 or later) includes @value{tramp} already, and there
-is a @value{tramp} package for XEmacs, as well. So maybe it is easier
-to just use those. But if you want the bleeding edge, read
-on@dots{...}
+release may be downloaded from @uref{ftp://ftp.gnu.org/gnu/tramp/}.
+This release includes the full documentation and code for
+@value{tramp}, suitable for installation. But Emacs (22 or later)
+includes @value{tramp} already, and there is a @value{tramp} package
+for XEmacs, as well. So maybe it is easier to just use those. But if
+you want the bleeding edge, read on@dots{...}
For the especially brave, @value{tramp} is available from CVS. The CVS
version is the latest version of the code and may contain incomplete
@ifset emacsgvfs
GVFS integration started in February 2009.
@end ifset
-@ifset emacsimap
-Storing files into IMAP mailboxes has been added in September 2009.
-@end ifset
In December 2001, @value{tramp} has been added to the XEmacs package
-repository. Being part of the GNU Emacs repository happened in June
-2002, the first release including @value{tramp} was GNU Emacs 22.1.
+repository. Being part of the Emacs repository happened in June 2002,
+the first release including @value{tramp} was Emacs 22.1.
-@value{tramp} is also a GNU/Linux Debian package since February 2001.
+@value{tramp} is also a Debian GNU/Linux package since February 2001.
@c Installation chapter is necessary only in case of standalone
@cindex methods, inline
@cindex methods, external
Loading or saving a remote file requires that the content of the file
-be transfered between the two machines. The content of the file can
-be transfered using one of two methods: the @dfn{inline method} over
+be transferred between the two machines. The content of the file can
+be transferred using one of two methods: the @dfn{inline method} over
the same connection used to log in to the remote machine, or the
@dfn{external method} through another connection using a remote copy
program such as @command{rcp}, @command{scp} or @command{rsync}.
@command{krlogin -x} command to log in to the remote host.
+@item @option{ksu}
+@cindex method ksu
+@cindex ksu method
+@cindex Kerberos (with ksu method)
+
+This is another method from the Kerberos suite. It behaves like @option{su}.
+
+
@item @option{plink}
@cindex method plink
@cindex plink method
@cindex method ftp
@cindex ftp method
-This is not a native @value{tramp} method. Instead of, it forwards all
+This is not a native @value{tramp} method. Instead, it forwards all
requests to @value{ftppackagename}.
@ifset xemacs
This works only for unified filenames, see @ref{Issues}.
@command{smbclient} command on different Unices in order to connect to
an SMB server. An SMB server might be a Samba (or CIFS) server on
another UNIX host or, more interesting, a host running MS Windows. So
-far, it is tested towards MS Windows NT, MS Windows 2000, and MS
+far, it is tested against MS Windows NT, MS Windows 2000, and MS
Windows XP.
The first directory in the localname must be a share name on the remote
-host. Remember, that the @code{$} character in which default shares
+host. Remember that the @code{$} character, in which default shares
usually end, must be written @code{$$} due to environment variable
substitution in file names. If no share name is given (i.e. remote
directory @code{/}), all available shares are listed.
-Since authorization is done on share level, you will be prompted
-always for a password if you access another share on the same host.
+Since authorization is done on share level, you will always be
+prompted for a password if you access another share on the same host.
This can be suppressed by @ref{Password handling}.
-MS Windows uses for authorization both a user name and a domain name.
+For authorization, MS Windows uses both a user name and a domain name.
Because of this, the @value{tramp} syntax has been extended: you can
specify a user name which looks like @code{user%domain} (the real user
name, then a percent sign, then the domain name). So, to connect to
The @option{smb} method supports the @samp{-p} argument.
@strong{Please note:} If @value{emacsname} runs locally under MS
-Windows, this method isn't available. Instead of, you can use UNC
+Windows, this method isn't available. Instead, you can use UNC
file names like @file{//melancholia/daniel$$/.emacs}. The only
disadvantage is that there's no possibility to specify another user
name.
-
-
-@ifset emacsimap
-@item @option{imap}
-@cindex method imap
-@cindex method imaps
-@cindex imap method
-@cindex imaps method
-
-Accessing an IMAP mailbox is intended to save files there as encrypted
-message. It could be used in case there are no other remote file
-storages available.
-
-@value{tramp} supports both @option{imap} and @option{imaps} methods.
-The latter one accesses the IMAP server over ssl.
-
-Both methods support the port number specification.
-
-Note, that special handling is needed for declaring a passphrase for
-encryption / decryption of the messages (@pxref{Using an
-authentication file}).
-
-@end ifset
@end table
The connection methods described in this section are based on GVFS
@uref{http://en.wikipedia.org/wiki/GVFS}. Via GVFS, the remote
filesystem is mounted locally through FUSE. @value{tramp} uses
-internally this local mounted directory.
+this local mounted directory internally.
The communication with GVFS is implemented via D-Bus messages.
Therefore, your @value{emacsname} must have D-Bus integration,
@cindex obex method
OBEX is an FTP-like access protocol for simple devices, like cell
-phones. Until now @value{tramp} supports only OBEX over Bluetooth.
+phones. For the time being, @value{tramp} only supports OBEX over Bluetooth.
@item @option{synce}
The @option{synce} method allows communication with Windows Mobile
devices. Beside GVFS for mounting remote files and directories via
-FUSE, it needs also the SYNCE-GVFS plugin.
+FUSE, it also needs the SYNCE-GVFS plugin.
@end table
@defopt tramp-gvfs-methods
-This customer option, a list, defines the external methods, which
+This customer option, a list, defines the external methods which
shall be used with GVFS. Per default, these are @option{dav},
@option{davs}, @option{obex} and @option{synce}. Other possible
values are @option{ftp}, @option{sftp} and @option{smb}.
Therefore, they can be used for proxy host declarations
(@pxref{Multi-hops}) only.
-A gateway method must come always along with a method who supports
+A gateway method must always come along with a method which supports
port setting. This is because @value{tramp} targets the accompanied
method to @file{localhost#random_port}, from where the firewall or
-proxy server is accessed to.
+proxy server is accessed.
Gateway methods support user name and password declarations. These
are used to authenticate towards the corresponding firewall or proxy
@item @code{tramp-parse-netrc}
@findex tramp-parse-netrc
-Finally, a function which parses @file{~/.netrc} like files.
+Finally, a function which parses @file{~/.netrc} like files. This
+includes also @file{~/.authinfo}-style files.
@end table
If you want to keep your own data in a file, with your own structure,
methods, or @command{pageant} for @option{plink}-like methods.
However, if you cannot apply such native password handling,
-@value{tramp} offers altenatives.
+@value{tramp} offers alternatives.
@anchor{Using an authentication file}
@pxref{External methods}), to match only this method. When you omit
the port, you match all @value{tramp} methods.
-@ifset emacsimap
-A special case are @option{imap}-like methods. Authentication with
-the IMAP server is performed via @file{imap.el}, there is no special
-need from @value{tramp} point of view. An additional passphrase, used
-for symmetric encryption and decryption of the stored messages, should
-be given with the special port indication @option{tramp-imap}:
+In case of problems, setting @code{auth-source-debug} to @code{t}
+gives useful debug messages.
-@example
-machine melancholia port tramp-imap login daniel password ultrageheim
-@end example
-@end ifset
@anchor{Caching passwords}
@subsection Caching passwords
When @value{tramp} detects a changed operating system version on a
remote host (via the command @command{uname -sr}), it flushes all
connection related information for this host, and opens the
-connection, again.
+connection again.
@node Remote Programs
machines. The symbol @code{tramp-default-remote-path} is a place
holder, it is replaced by the list of directories received via the
command @command{getconf PATH} on your remote machine. For example,
-on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is
-@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is
-recommended to apply this symbol on top of @code{tramp-remote-path}.
+on Debian GNU/Linux this is @file{/bin:/usr/bin}, whereas on Solaris
+this is @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}.
+It is recommended to apply this symbol on top of
+@code{tramp-remote-path}.
It is possible, however, that your local (or remote ;) system
administrator has put the tools you want in some obscure local
@end lisp
Another possibility is to reuse the path settings of your remote
-account, when you log in. Usually, these settings are overwritten,
+account when you log in. Usually, these settings are overwritten,
because they might not be useful for @value{tramp}. The place holder
@code{tramp-own-remote-path} preserves these settings. You can
activate it via
@value{tramp} uses for analysis of completion, offer user names, those user
names will be taken into account as well.
-Remote machines, which have been visited in the past and kept
-persistently (@pxref{Connection caching}), will be offered too.
+Remote machines which have been visited in the past and kept
+persistently (@pxref{Connection caching}) will be offered too.
Once the remote machine identification is completed, it comes to
filename completion on the remote host. This works pretty much like
A remote directory might have changed its contents out of
@value{emacsname} control, for example by creation or deletion of
-files by other processes. Therefore, during filename completion the
-remote directory contents is reread regularly in order to detect such
+files by other processes. Therefore, during filename completion, the
+remote directory contents are reread regularly in order to detect such
changes, which would be invisible otherwise (@pxref{Connection caching}).
@defopt tramp-completion-reread-directory-timeout
@option{smb} methods. Association of a pty, as specified in
@code{start-file-process}, is not supported.
+@code{process-file} and @code{start-file-process} work on the remote
+host when the variable @code{default-directory} is remote:
+
+@lisp
+(let ((default-directory "/ssh:remote.host:"))
+ (start-file-process "grep" (get-buffer-create "*grep*")
+ "/bin/sh" "-c" "grep -e tramp *"))
+@end lisp
+
@ifset emacsgvfs
If the remote host is mounted via GVFS (see @ref{GVFS based methods}),
the remote filesystem is mounted locally. Therefore, there are no
that host.
-@subsection Running shell-command on a remote host
+@subsection Running @code{shell} on a remote host
+@cindex shell
+
+Calling @code{M-x shell} in a buffer related to a remote host runs the
+local shell as defined in @option{shell-file-name}. This might be
+also a valid path name for a shell to be applied on the remote host,
+but it will fail at least when your local and remote hosts belong to
+different system types, like @samp{windows-nt} and @samp{gnu/linux}.
+
+You must set the variable @option{explicit-shell-file-name} to the
+shell path name on the remote host, in order to start that shell on
+the remote host.
+
+@ifset emacs
+Starting with Emacs 24 this won't be necessary, if you call
+@code{shell} interactively. You will be asked for the remote shell
+path, if you are on a remote buffer, and if
+@option{explicit-shell-file-name} is equal to @code{nil}.
+@end ifset
+
+
+@subsection Running @code{shell-command} on a remote host
@cindex shell-command
@code{shell-command} allows to execute commands in a shell, either
continuous output of the @command{tail} command.
-@subsection Running eshell on a remote host
+@subsection Running @code{eshell} on a remote host
@cindex eshell
@value{tramp} is integrated into @file{eshell.el}. That is, you can
open an interactive shell on your remote host, and run commands there.
-After you have started @code{eshell}, you could perform commands like
-this:
+After you have started @code{M-x eshell}, you could perform commands
+like this:
@example
@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
connection buffers.
@end deffn
+@deffn Command tramp-cleanup-this-connection
+This command flushes all objects of the current buffer's remote
+connection. The same objects are removed as in
+@code{tramp-cleanup-connection}.
+@end deffn
+
@deffn Command tramp-cleanup-all-connections
This command flushes objects for all active remote connections. The
same objects are removed as in @code{tramp-cleanup-connection}.
@item
Which systems does it work on?
-The package has been used successfully on GNU Emacs 22, GNU Emacs 23,
-XEmacs 21 (starting with 21.4), and SXEmacs 22.
+The package has been used successfully on Emacs 22, Emacs 23, Emacs
+24, XEmacs 21 (starting with 21.4), and SXEmacs 22.
The package was intended to work on Unix, and it really expects a
-Unix-like system on the remote end (except the @option{smb} and
-@option{imap} methods), but some people seemed to have some success
-getting it to work on MS Windows XP/Vista/7 @value{emacsname}.
+Unix-like system on the remote end (except the @option{smb} method),
+but some people seemed to have some success getting it to work on MS
+Windows XP/Vista/7 @value{emacsname}.
@item
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. If you are
-confident, that files on remote hosts are not changed out of
+confident that files on remote hosts are not changed out of
@value{emacsname}' control, set @code{remote-file-name-inhibit-cache}
to @code{nil}.
reasons heading the bug mailing list:
@itemize @minus
-
@item
Unknown characters in the prompt
@value{tramp} needs to recognize the prompt on the remote machine
-after execution any command. This is not possible, when the prompt
+after execution any command. This is not possible when the prompt
contains unknown characters like escape sequences for coloring. This
should be avoided on the remote side. @xref{Remote shell setup}. for
setting the regular expression detecting the prompt.
[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
@end example
+Furthermore it has been reported, that @value{tramp} (like sshfs,
+incidentally) doesn't work with WinSSHD due to strange prompt settings.
+
@item
Echoed characters after login
(when (file-remote-p default-directory)
(set (make-local-variable 'file-precious-flag) t))))
@end lisp
-
@end itemize
When your network connection is down, @command{ssh} sessions might
hang. @value{tramp} cannot detect it safely, because it still sees a
running @command{ssh} process. Timeouts cannot be used as well,
-because it cannot be predicted, how long a remote command will last,
+because it cannot be predicted how long a remote command will last,
for example when copying very large files.
Therefore, you must configure the @command{ssh} process to die
The file name left to type would be
@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
-Note, that there are some useful settings already. Accessing your
+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
@trampfn{su, , ,}}.
@end lisp
Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you
-are. The disadvantage is, that you cannot edit the file name, because
+are. The disadvantage is that you cannot edit the file name, because
environment variables are not expanded during editing in the
minibuffer.
'("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
@end lisp
-This shortens the file openening command to @kbd{C-x C-f /xy
+This shortens the file opening command to @kbd{C-x C-f /xy
@key{RET}}. The disadvantage is, again, that you cannot edit the file
name, because the expansion happens after entering the file name only.
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:
+specify a method together with the user name when needed. Example:
@example
@kbd{M-x bbdb-create-ftp-site @key{RET}}
@end enumerate
-I would like to thank all @value{tramp} users, who have contributed to
+I would like to thank all @value{tramp} users who have contributed to
the different recipes!
(server-start)
@end lisp
-Make sure, that the result of @code{(system-name)} can be resolved on
+Make sure that the result of @code{(system-name)} can be resolved on
your local host; otherwise you might use a hard coded IP address.
The resulting file @file{~/.emacs.d/server/server} must be copied to
@item
-How can I disable @value{tramp}?
+There are packages which call @value{tramp} although I haven't entered
+a remote file name ever. I dislike it, how could I disable it?
-Shame on you, why did you read until now?
+In general, @value{tramp} functions are used only when
+you apply remote file name syntax. However, some packages enable
+@value{tramp} on their own.
@itemize @minus
+@item
+@file{ido.el}
+
+You could disable @value{tramp} file name completion:
+
+@lisp
+(custom-set-variables
+ '(ido-enable-tramp-completion nil))
+@end lisp
+
+@item
+@file{rlogin.el}
+
+You could disable remote directory tracking mode:
+
+@lisp
+(rlogin-directory-tracking-mode -1)
+@end lisp
+@end itemize
+
@item
+How can I disable @value{tramp} at all?
+
+Shame on you, why did you read until now?
+
+@itemize @minus
@ifset emacs
+@item
If you just want to have @value{ftppackagename} as default remote
files access package, you should apply the following code:
it has seen so far.
This is a performance degradation, because the lost file attributes
-must be recomputed, when needed again. In cases the caller of
+must be recomputed when needed again. In cases the caller of
@code{process-file} knows that there are no file attribute changes, it
shall let-bind the variable @code{process-file-side-effects} to
@code{nil}. @value{tramp} wouldn't flush the file attributes cache then.
When @code{tramp-verbose} is greater than or equal to 4, the messages
are also written into a @value{tramp} debug buffer. This debug buffer
-is useful for analysing problems; sending a @value{tramp} bug report
+is useful for analyzing problems; sending a @value{tramp} bug report
should be done with @code{tramp-verbose} set to a verbosity level of at
least 6 (@pxref{Bug Reports}).
But I have decided that this is too fragile to reliably work, so on some
systems you'll have to do without the uuencode methods.
-@item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs.
+@item The @value{tramp} filename syntax differs between Emacs and XEmacs.
-The GNU Emacs maintainers wish to use a unified filename syntax for
+The Emacs maintainers wish to use a unified filename syntax for
Ange-FTP and @value{tramp} so that users don't have to learn a new
syntax. It is sufficient to learn some extensions to the old syntax.
@c host and then send commands to it.
@c * Use `filename' resp. `file name' consistently.
@c * Use `host' resp. `machine' consistently.
-@c * Consistent small or capitalized words especially in menues.
-
-@ignore
- arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808
-@end ignore
+@c * Consistent small or capitalized words especially in menus.
HCoop / bpt / emacs.git / blobdiff