@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
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
-messages. 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
@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,
@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
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
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
reasons heading the bug mailing list:
@itemize @minus
-
@item
Unknown characters in the prompt
(when (file-remote-p default-directory)
(set (make-local-variable 'file-precious-flag) t))))
@end lisp
-
@end itemize
@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:
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.