[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to tramp.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to tramp.texi |
|
Date: |
Thu, 06 Sep 2007 05:02:38 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 05:02:38
Index: tramp.texi
===================================================================
RCS file: tramp.texi
diff -N tramp.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ tramp.texi 6 Sep 2007 05:02:37 -0000 1.1
@@ -0,0 +1,3297 @@
+\input texinfo @c -*-texinfo-*-
address@hidden ../info/tramp
address@hidden %**start of header
address@hidden TRAMP User Manual
address@hidden odd
address@hidden %**end of header
+
address@hidden This is *so* much nicer :)
address@hidden end
+
address@hidden In the Tramp CVS, the version number is auto-frobbed from
address@hidden configure.ac, so you should edit that file and run
address@hidden "autoconf && ./configure" to change the version number.
+
address@hidden Additionally, flags are set with respect to the Emacs flavor; and
address@hidden depending whether Tramp is packaged into (X)Emacs, or standalone.
+
address@hidden trampver.texi
+
address@hidden Macro for formatting a filename according to the repective
syntax.
address@hidden xxx and yyy are auxiliary macros in order to omit leading and
address@hidden trailing whitespace. Not very elegant, but I don't know it
better.
+
address@hidden xxx address@hidden
address@hidden address@hidden
address@hidden macro
+
address@hidden yyy {one, address@hidden
address@hidden@c
address@hidden address@hidden
address@hidden@c
address@hidden ifclear
address@hidden address@hidden
address@hidden macro
+
address@hidden trampfn {method, user, host, address@hidden
address@hidden@yyy{\method\,@address@hidden,@@address@hidden@c
address@hidden macro
+
address@hidden
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
+2007 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
address@hidden quotation
address@hidden copying
+
address@hidden Entries for @command{install-info} to use
address@hidden @value{emacsname}
address@hidden
+* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
+ @value{emacsname} remote file access via rsh
and rcp.
address@hidden direntry
+
address@hidden
+
address@hidden
address@hidden @value{tramp} version @value{trampver} User Manual
+
address@hidden by Daniel Pittman
address@hidden based on documentation by Kai address@hidden
+
address@hidden
address@hidden
+
address@hidden titlepage
address@hidden
+
address@hidden tex
+
address@hidden
address@hidden Top, Overview, (dir), (dir)
address@hidden @value{tramp} version @value{trampver} User Manual
+
+This file documents @value{tramp} version @value{trampver}, a remote file
+editing package for @value{emacsname}.
+
address@hidden stands for `Transparent Remote (file) Access, Multiple
+Protocol'. This package provides remote file editing, similar to
address@hidden
+
+The difference is that @value{ftppackagename} uses FTP to transfer
+files between the local and the remote host, whereas @value{tramp} uses a
+combination of @command{rsh} and @command{rcp} or other work-alike
+programs, such as @command{ssh}/@command{scp}.
+
+You can find the latest version of this document on the web at
address@hidden://www.gnu.org/software/tramp/}.
+
address@hidden Pointer to the other Emacs flavor is necessary only in case of
address@hidden standalone installation.
address@hidden installchapter
+The manual has been generated for @value{emacsname}.
address@hidden
+If you want to read the info pages for @value{emacsothername}, you
+should read in @ref{Installation} how to create them.
address@hidden ifinfo
address@hidden
+If you're using the other Emacs flavor, you should read the
address@hidden@value{emacsotherfilename}, @value{emacsothername}} pages.
address@hidden ifhtml
address@hidden ifset
+
address@hidden
address@hidden jamanual
+This manual is also available as a @address@hidden,
+Japanese translation}.
address@hidden ifset
+
+The latest release of @value{tramp} is available for
address@hidden://ftp.gnu.org/gnu/tramp/, download}, or you may see
address@hidden Tramp} for more details, including the CVS server
+details.
+
address@hidden also has a @uref{http://savannah.gnu.org/projects/tramp/,
+Savannah Project Page}.
address@hidden ifhtml
+
+There is a mailing list for @value{tramp}, available at
address@hidden@@gnu.org}, and archived at
address@hidden://lists.gnu.org/archive/html/tramp-devel/, the
address@hidden Mail Archive}.
address@hidden
+Older archives are located at
address@hidden://sourceforge.net/mailarchive/forum.php?forum=tramp-devel,
+SourceForge Mail Archive} and
address@hidden://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/,
+The Mail Archive}.
address@hidden in HTML output, there's no new paragraph.
address@hidden@*
address@hidden ifhtml
+
address@hidden
+
address@hidden ifnottex
+
address@hidden
+* Overview:: What @value{tramp} can and cannot do.
+
+For the end user:
+
+* Obtaining Tramp:: How to obtain @value{tramp}.
+* History:: History of @value{tramp}.
address@hidden installchapter
+* Installation:: Installing @value{tramp} with your
@value{emacsname}.
address@hidden ifset
+* Configuration:: Configuring @value{tramp} for use.
+* Usage:: An overview of the operation of @value{tramp}.
+* Bug Reports:: Reporting Bugs and Problems.
+* Frequently Asked Questions:: Questions and answers from the mailing list.
+* Concept Index:: An item for each concept.
+
+For the developer:
+
+* Version Control:: The inner workings of remote version control.
+* Files directories and localnames:: How file names, directories and
localnames are mangled and managed.
+* Traces and Profiles:: How to Customize Traces.
+* Issues:: Debatable Issues and What Was Decided.
+
+* GNU Free Documentation License:: The license for this documentation.
+
address@hidden
+ --- The Detailed Node Listing ---
address@hidden
address@hidden installchapter
+Installing @value{tramp} with your @value{emacsname}
+
+* Installation parameters:: Parameters in order to control installation.
+* Load paths:: How to plug-in @value{tramp} into your
environment.
+* Japanese manual:: Japanese manual.
+
address@hidden ifset
+
+Configuring @value{tramp} for use
+
+* Connection types:: Types of connections made to remote machines.
+* Inline methods:: Inline methods.
+* External transfer methods:: External transfer methods.
address@hidden emacsgw
+* Gateway methods:: Gateway methods.
address@hidden ifset
+* Default Method:: Selecting a default method.
+* Default User:: Selecting a default user.
+* Default Host:: Selecting a default host.
+* Multi-hops:: Connecting to a remote host using multiple
hops.
+* Customizing Methods:: Using Non-Standard Methods.
+* Customizing Completion:: Selecting config files for user/host name
completion.
+* Password caching:: Reusing passwords for several connections.
+* Connection caching:: Reusing connection related information.
+* Remote Programs:: How @value{tramp} finds and uses programs on
the remote machine.
+* Remote shell setup:: Remote shell setup hints.
+* Windows setup hints:: Issues with Cygwin ssh.
+* Auto-save and Backup:: Auto-save and Backup.
+
+Using @value{tramp}
+
+* Filename Syntax:: @value{tramp} filename conventions.
+* Alternative Syntax:: URL-like filename syntax.
+* Filename completion:: Filename completion.
+* Remote processes:: Integration with other @value{emacsname}
packages.
+
+The inner workings of remote version control
+
+* Version Controlled Files:: Determining if a file is under version control.
+* Remote Commands:: Executing the version control commands on the
remote machine.
+* Changed workfiles:: Detecting if the working file has changed.
+* Checking out files:: Bringing the workfile out of the repository.
+* Miscellaneous Version Control:: Things related to Version Control that
don't fit elsewhere.
+
+Things related to Version Control that don't fit elsewhere
+
+* Remote File Ownership:: How VC determines who owns a workfile.
+* Back-end Versions:: How VC determines what release your RCS is.
+
+How file names, directories and localnames are mangled and managed
+
+* Localname deconstruction:: Breaking a localname into its components.
+
address@hidden detailmenu
address@hidden menu
+
address@hidden Overview
address@hidden An overview of @value{tramp}
address@hidden overview
+
+After the installation of @value{tramp} into your @value{emacsname}, you
+will be able to access files on remote machines as though they were
+local. Access to the remote file system for editing files, version
+control, and @code{dired} are transparently enabled.
+
+Your access to the remote machine can be with the @command{rsh},
address@hidden, @command{telnet} programs or with any similar
+connection method. This connection must pass @acronym{ASCII}
+successfully to be usable but need not be 8-bit clean.
+
+The package provides support for @command{ssh} connections out of the
+box, one of the more common uses of the package. This allows
+relatively secure access to machines, especially if @command{ftp}
+access is disabled.
+
+The majority of activity carried out by @value{tramp} requires only that
+the remote login is possible and is carried out at the terminal. In
+order to access remote files @value{tramp} needs to transfer their content
+to the local machine temporarily.
+
address@hidden can transfer files between the machines in a variety of ways.
+The details are easy to select, depending on your needs and the
+machines in question.
+
+The fastest transfer methods (for large files) rely on a remote file
+transfer package such as @command{rcp}, @command{scp} or
address@hidden
+
+If the remote copy methods are not suitable for you, @value{tramp} also
+supports the use of encoded transfers directly through the shell.
+This requires that the @command{mimencode} or @command{uuencode} tools
+are available on the remote machine. These methods are generally
+faster for small files.
+
+Within these limitations, @value{tramp} is quite powerful. It is worth
+noting that, as of the time of writing, it is far from a polished
+end-user product. For a while yet you should expect to run into rough
+edges and problems with the code now and then.
+
+It is finished enough that the developers use it for day to day work but
+the installation and setup can be a little difficult to master, as can
+the terminology.
+
address@hidden is still under active development and any problems you encounter,
+trivial or major, should be reported to the @value{tramp} developers.
address@hidden Reports}.
+
+
address@hidden Behind the scenes
address@hidden behind the scenes
address@hidden details of operation
address@hidden how it works
+
+This section tries to explain what goes on behind the scenes when you
+access a remote file through @value{tramp}.
+
+Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name,
+then hit @address@hidden for completion. Suppose further that this is
+the first time that @value{tramp} is invoked for the host in question. Here's
+what happens:
+
address@hidden
address@hidden
address@hidden discovers that it needs a connection to the host. So it
+invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
address@hidden or a similar tool to connect to the remote host.
+Communication with this process happens through an
address@hidden buffer, that is, the output from the remote end
+goes into a buffer.
+
address@hidden
+The remote host may prompt for a login name (for @command{telnet}).
+The login name is given in the file name, so @value{tramp} sends the
+login name and a newline.
+
address@hidden
+The remote host may prompt for a password or pass phrase (for
address@hidden or for @command{telnet} after sending the login name).
address@hidden displays the prompt in the minibuffer, asking you for the
+password or pass phrase.
+
+You enter the password or pass phrase. @value{tramp} sends it to the remote
+host, followed by a newline.
+
address@hidden
address@hidden now waits for the shell prompt or for a message that the login
+failed.
+
+If @value{tramp} sees neither of them after a certain period of time (a minute,
+say), then it issues an error message saying that it couldn't find the
+remote shell prompt and shows you what the remote host has sent.
+
+If @value{tramp} sees a @samp{login failed} message, it tells you so,
+aborts the login attempt and allows you to try again.
+
address@hidden
+Suppose that the login was successful and @value{tramp} sees the shell prompt
+from the remote host. Now @value{tramp} invokes @command{/bin/sh} because
+Bourne shells and C shells have different command
address@hidden @command{/bin/sh} will fail if your login
+shell doesn't recognize @samp{exec /bin/sh} as a valid command.
+Maybe you use the Scheme shell @address@hidden
+
+After the Bourne shell has come up, @value{tramp} sends a few commands to
+ensure a good working environment. It turns off echoing, it sets the
+shell prompt, and a few other things.
+
address@hidden
+Now the remote shell is up and it good working order. Remember, what
+was supposed to happen is that @value{tramp} tries to find out what files exist
+on the remote host so that it can do filename completion.
+
+So, @value{tramp} basically issues @command{cd} and @command{ls} commands and
+also sometimes @command{echo} with globbing. Another command that is
+often used is @command{test} to find out whether a file is writable or a
+directory or the like. The output of each command is parsed for the
+necessary operation.
+
address@hidden
+Suppose you are finished with filename completion, have entered @kbd{C-x
+C-f}, a full file name and hit @address@hidden Now comes the time to
+transfer the file contents from the remote host to the local host so
+that you can edit them.
+
+See above for an explanation of how @value{tramp} transfers the file contents.
+
+For inline transfers, @value{tramp} issues a command like @samp{mimencode -b
+/path/to/remote/file}, waits until the output has accumulated in the
+buffer that's used for communication, then decodes that output to
+produce the file contents.
+
+For out-of-band transfers, @value{tramp} issues a command like the following:
address@hidden
+rcp user@@host:/path/to/remote/file /tmp/tramp.4711
address@hidden example
+It then reads the local temporary file @file{/tmp/tramp.4711} into a
+buffer and deletes the temporary file.
+
address@hidden
+You now edit the buffer contents, blithely unaware of what has happened
+behind the scenes. (Unless you have read this section, that is.) When
+you are finished, you type @kbd{C-x C-s} to save the buffer.
+
address@hidden
+Again, @value{tramp} transfers the file contents to the remote host either
+inline or out-of-band. This is the reverse of what happens when reading
+the file.
address@hidden itemize
+
+I hope this has provided you with a basic overview of what happens
+behind the scenes when you open a file with @value{tramp}.
+
+
address@hidden For the end user
address@hidden Obtaining Tramp
address@hidden Obtaining Tramp.
address@hidden obtaining Tramp
+
address@hidden is freely available on the Internet and the latest
+release may be downloaded from
address@hidden://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
address@hidden
+
+For the especially brave, @value{tramp} is available from CVS. The CVS
+version is the latest version of the code and may contain incomplete
+features or new issues. Use these versions at your own risk.
+
+Instructions for obtaining the latest development version of @value{tramp}
+from CVS can be found by going to the Savannah project page at the
+following URL and then clicking on the CVS link in the navigation bar
+at the top.
+
address@hidden
address@hidden://savannah.gnu.org/projects/tramp/}
+
address@hidden
+Or follow the example session below:
+
address@hidden
+] @strong{cd ~/@value{emacsdir}}
+] @strong{export CVS_RSH="ssh"}
+] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
address@hidden example
+
address@hidden
+You should now have a directory @file{~/@value{emacsdir}/tramp}
+containing the latest version of @value{tramp}. You can fetch the latest
+updates from the repository by issuing the command:
+
address@hidden
+] @strong{cd ~/@value{emacsdir}/tramp}
+] @strong{export CVS_RSH="ssh"}
+] @strong{cvs update -d}
address@hidden example
+
address@hidden
+Once you've got updated files from the CVS repository, you need to run
address@hidden in order to get an up-to-date @file{configure}
+script:
+
address@hidden
+] @strong{cd ~/@value{emacsdir}/tramp}
+] @strong{autoconf}
address@hidden example
+
+People who have no direct CVS access (maybe because sitting behind a
+blocking firewall), can try the
address@hidden://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly
+CVS Tree Tarball} instead of.
+
+
address@hidden History
address@hidden History of @value{tramp}
address@hidden history
address@hidden development history
+
+Development was started end of November 1998. The package was called
address@hidden, back then. It only provided one method to access a
+file, using @command{ssh} to log in to a remote host and using
address@hidden to transfer the file contents. After a while, the name
+was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way,
+many more methods for getting a remote shell and for transferring the
+file contents were added. Support for VC was added.
+
+The most recent addition of major features were the multi-hop methods
+added in April 2000 and the unification of @value{tramp} and Ange-FTP
+filenames in July 2002. In July 2004, multi-hop methods have been
+replaced by proxy hosts. Running commands on remote hosts was
+introduced in December 2005.
address@hidden emacsgw
+Support of gateways exists since April 2007.
address@hidden 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.
+
address@hidden is also a GNU/Linux Debian package since February 2001.
+
+
address@hidden Installation chapter is necessary only in case of standalone
address@hidden installation. Text taken from trampinst.texi.
address@hidden installchapter
address@hidden trampinst.texi
address@hidden ifset
+
address@hidden Configuration
address@hidden Configuring @value{tramp} for use
address@hidden configuration
+
address@hidden default configuration
address@hidden is (normally) fully functional when it is initially
+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
address@hidden@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
+setup}, for details on this.
+
+If you do not wish to use these commands to connect to the remote
+host, you should change the default connection and transfer method
+that @value{tramp} uses. There are several different methods that
@value{tramp}
+can use to connect to remote machines and transfer files
+(@pxref{Connection types}).
+
+If you don't know which method is right for you, see @xref{Default
+Method}.
+
+
address@hidden
+* Connection types:: Types of connections made to remote machines.
+* Inline methods:: Inline methods.
+* External transfer methods:: External transfer methods.
address@hidden emacsgw
+* Gateway methods:: Gateway methods.
address@hidden ifset
+* Default Method:: Selecting a default method.
+ Here we also try to help those who
+ don't have the foggiest which method
+ is right for them.
+* Default User:: Selecting a default user.
+* Default Host:: Selecting a default host.
+* Multi-hops:: Connecting to a remote host using multiple
hops.
+* Customizing Methods:: Using Non-Standard Methods.
+* Customizing Completion:: Selecting config files for user/host name
completion.
+* Password caching:: Reusing passwords for several connections.
+* Connection caching:: Reusing connection related information.
+* Remote Programs:: How @value{tramp} finds and uses programs on
the remote machine.
+* Remote shell setup:: Remote shell setup hints.
+* Windows setup hints:: Issues with Cygwin ssh.
+* Auto-save and Backup:: Auto-save and Backup.
address@hidden menu
+
+
address@hidden Connection types
address@hidden Types of connections made to remote machines.
address@hidden connection types, overview
+
+There are two basic types of transfer methods, each with its own
+advantages and limitations. Both types of connection make use of a
+remote shell access program such as @command{rsh}, @command{ssh} or
address@hidden to connect to the remote machine.
+
+This connection is used to perform many of the operations that @value{tramp}
+requires to make the remote file system transparently accessible from
+the local machine. It is only when visiting files that the methods
+differ.
+
address@hidden inline methods
address@hidden external transfer methods
address@hidden external methods
address@hidden out-of-band methods
address@hidden methods, inline
address@hidden methods, external transfer
address@hidden methods, out-of-band
+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 over the same connection used to log in to the remote
+machine or the file can be transfered through another connection using
+a remote copy program such as @command{rcp}, @command{scp} or
address@hidden The former are called @dfn{inline methods}, the
+latter are called @dfn{out-of-band methods} or @dfn{external transfer
+methods} (@dfn{external methods} for short).
+
+The performance of the external transfer 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.
+
+The one exception to this rule are the @command{scp} based transfer
+methods. While these methods do see better performance when actually
+transferring files, the overhead of the cryptographic negotiation at
+startup may drown out the improvement in file transfer times.
+
+External transfer methods should be configured such a way that they
+don't require a password (with @command{ssh-agent}, or such alike).
+Modern @command{scp} implementations offer options to reuse existing
address@hidden connections, see method @command{scpc}. If it isn't
+possible, you should consider @ref{Password caching}, otherwise you
+will be prompted for a password every copy action.
+
+
address@hidden Inline methods
address@hidden Inline methods
address@hidden inline methods
address@hidden methods, inline
+
+The inline methods in @value{tramp} are quite powerful and can work in
+situations where you cannot use an external transfer program to connect.
+Inline methods are the only methods that work when connecting to the
+remote machine via telnet. (There are also strange inline methods which
+allow you to transfer files between @emph{user identities} rather than
+hosts, see below.)
+
+These methods depend on the existence of a suitable encoding and
+decoding command on remote machine. Locally, @value{tramp} may be able to
+use features of @value{emacsname} to decode and encode the files or
+it may require access to external commands to perform that task.
+
address@hidden uuencode
address@hidden mimencode
address@hidden base-64 encoding
address@hidden checks the availability and usability of commands like
address@hidden (part of the @command{metamail} package) or
address@hidden on the remote host. The first reliable command
+will be used. The search path can be customized, see @ref{Remote
+Programs}.
+
+If both commands aren't available on the remote host, @value{tramp}
+transfers a small piece of Perl code to the remote host, and tries to
+apply it for encoding and decoding.
+
+
address@hidden @asis
address@hidden @option{rsh}
address@hidden method rsh
address@hidden rsh method
+
+Connect to the remote host with @command{rsh}. Due to the unsecure
+connection it is recommended for very local host topology only.
+
+On operating systems which provide the command @command{remsh} instead
+of @command{rsh}, you can use the method @option{remsh}. This is true
+for HP-UX or Cray UNICOS, for example.
+
+
address@hidden @option{ssh}
address@hidden method ssh
address@hidden ssh method
+
+Connect to the remote host with @command{ssh}. This is identical to
+the previous option except that the @command{ssh} package is used,
+making the connection more secure.
+
+There are also two variants, @option{ssh1} and @option{ssh2}, that
+call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
+explicitly select whether you want to use the SSH protocol version 1
+or 2 to connect to the remote host. (You can also specify in
address@hidden/.ssh/config}, the SSH configuration file, which protocol
+should be used, and use the regular @option{ssh} method.)
+
+Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
address@hidden and @command{ssh2} commands explicitly. If you don't
+know what these are, you do not need these options.
+
+All the methods based on @command{ssh} have an additional kludgy
+feature: you can specify a host name which looks like @file{host#42}
+(the real host name, then a hash sign, then a port number). This
+means to connect to the given host but to also pass @code{-p 42} as
+arguments to the @command{ssh} command.
+
+
address@hidden @option{telnet}
address@hidden method telnet
address@hidden telnet method
+
+Connect to the remote host with @command{telnet}. This is as unsecure
+as the @option{rsh} method.
+
+
address@hidden @option{su}
address@hidden method su
address@hidden su method
+
+This method does not connect to a remote host at all, rather it uses
+the @command{su} program to allow you to edit files as another user.
+With other words, a specified host name in the file name is silently
+ignored.
+
+
address@hidden @option{sudo}
address@hidden method sudo
address@hidden sudo method
+
+This is similar to the @option{su} method, but it uses @command{sudo}
+rather than @command{su} to become a different user.
+
+Note that @command{sudo} must be configured to allow you to start a
+shell as the user. It would be nice if it was sufficient if
address@hidden and @command{mimencode} were allowed, but that is not
+easy to implement, so I haven't got around to it, yet.
+
+
address@hidden @option{sshx}
address@hidden method sshx
address@hidden sshx method
+
+As you would expect, this is similar to @option{ssh}, only a little
+different. Whereas @option{ssh} opens a normal interactive shell on
+the remote host, this option uses @samp{ssh -t -t @var{host} -l
address@hidden /bin/sh} to open a connection. This is useful for users
+where the normal login shell is set up to ask them a number of
+questions when logging in. This procedure avoids these questions, and
+just gives @value{tramp} a more-or-less `standard' login shell to work
+with.
+
+Note that this procedure does not eliminate questions asked by
address@hidden itself. For example, @command{ssh} might ask ``Are you
+sure you want to continue connecting?'' if the host key of the remote
+host is not known. @value{tramp} does not know how to deal with such a
+question (yet), therefore you will need to make sure that you can log
+in without such questions.
+
+This is also useful for Windows users where @command{ssh}, when
+invoked from an @value{emacsname} buffer, tells them that it is not
+allocating a pseudo tty. When this happens, the login shell is wont
+to not print any shell prompt, which confuses @value{tramp} mightily.
+For reasons unknown, some Windows ports for @command{ssh} require the
+doubled @samp{-t} option.
+
+This supports the @samp{-p} kludge.
+
+
address@hidden @option{krlogin}
address@hidden method krlogin
address@hidden krlogin method
address@hidden Kerberos (with krlogin method)
+
+This method is also similar to @option{ssh}. It only uses the
address@hidden -x} command to log in to the remote host.
+
+
address@hidden @option{plink}
address@hidden method plink
address@hidden plink method
+
+This method is mostly interesting for Windows users using the PuTTY
+implementation of SSH. It uses @samp{plink -ssh} to log in to the
+remote host.
+
+This supports the @samp{-P} kludge.
+
+Additionally, the methods @option{plink1} and @option{plink2} are
+provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in
+order to use SSH protocol version 1 or 2 explicitly.
+
+CCC: Do we have to connect to the remote host once from the command
+line to accept the SSH key? Maybe this can be made automatic?
+
+CCC: Say something about the first shell command failing. This might
+be due to a wrong setting of @code{tramp-rsh-end-of-line}.
+
+
address@hidden @option{plinkx}
address@hidden method plinkx
address@hidden plinkx method
+
+Another method using PuTTY on Windows. Instead of host names, it
+expects PuTTY session names, calling @samp{plink -load @var{session}
+-t"}. User names are relevant only in case the corresponding session
+hasn't defined a user name. Different port numbers must be defined in
+the session.
+
+
address@hidden @option{fish}
address@hidden method fish
address@hidden fish method
+
+This is an experimental implementation of the fish protocol, known from
+the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
+the fish server implementation from the KDE kioslave. That means, the
+file @file{~/.fishsrv.pl} is expected to reside on the remote host.
+
+The implementation lacks good performance. The code is offered anyway,
+maybe somebody can improve the performance.
+
address@hidden table
+
+
address@hidden External transfer methods
address@hidden External transfer methods
address@hidden methods, external transfer
address@hidden methods, out-of-band
address@hidden external transfer methods
address@hidden out-of-band methods
+
+The external transfer methods operate through multiple channels, using
+the remote shell connection for many actions while delegating file
+transfers to an external transfer utility.
+
+This saves the overhead of encoding and decoding that multiplexing the
+transfer through the one connection has with the inline methods.
+
+Since external transfer methods need their own overhead opening a new
+channel, all files which are smaller than @var{tramp-copy-size-limit}
+are still transferred with the corresponding inline method. It should
+provide a fair trade-off between both approaches.
+
address@hidden @asis
address@hidden @option{rcp} --- @command{rsh} and @command{rcp}
address@hidden method rcp
address@hidden rcp method
address@hidden rcp (with rcp method)
address@hidden rsh (with rcp method)
+
+This method uses the @command{rsh} and @command{rcp} commands to connect
+to the remote machine and transfer files. This is probably the fastest
+connection method available.
+
+The alternative method @option{remcp} uses the @command{remsh} and
address@hidden commands. It should be applied on machines where
address@hidden is used instead of @command{rsh}.
+
+
address@hidden @option{scp} --- @command{ssh} and @command{scp}
address@hidden method scp
address@hidden scp method
address@hidden scp (with scp method)
address@hidden ssh (with scp method)
+
+Using @command{ssh} to connect to the remote host and @command{scp} to
+transfer files between the machines is the best method for securely
+connecting to a remote machine and accessing files.
+
+The performance of this option is also quite good. It may be slower than
+the inline methods when you often open and close small files however.
+The cost of the cryptographic handshake at the start of an @command{scp}
+session can begin to absorb the advantage that the lack of encoding and
+decoding presents.
+
+There are also two variants, @option{scp1} and @option{scp2}, that
+call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
+explicitly select whether you want to use the SSH protocol version 1
+or 2 to connect to the remote host. (You can also specify in
address@hidden/.ssh/config}, the SSH configuration file, which protocol
+should be used, and use the regular @option{scp} method.)
+
+Two other variants, @option{scp1_old} and @option{scp2_old}, use the
address@hidden and @command{ssh2} commands explicitly. If you don't
+know what these are, you do not need these options.
+
+All the @command{ssh} based methods support the kludgy @samp{-p}
+feature where you can specify a port number to connect to in the host
+name. For example, the host name @file{host#42} tells @value{tramp} to
+specify @samp{-p 42} in the argument list for @command{ssh}, and to
+specify @samp{-P 42} in the argument list for @command{scp}.
+
+
address@hidden @option{sftp} --- @command{ssh} and @command{sftp}
address@hidden method sftp
address@hidden sftp method
address@hidden sftp (with sftp method)
address@hidden ssh (with sftp method)
+
+That is mostly the same method as @option{scp}, but using
address@hidden as transfer command. So the same remarks are valid.
+
+This command does not work like @value{ftppackagename}, where
address@hidden is called interactively, and all commands are send from
+within this session. Instead of, @command{ssh} is used for login.
+
+This method supports the @samp{-p} hack.
+
+
address@hidden @option{rsync} --- @command{ssh} and @command{rsync}
address@hidden method rsync
address@hidden rsync method
address@hidden rsync (with rsync method)
address@hidden ssh (with rsync method)
+
+Using the @command{ssh} command to connect securely to the remote
+machine and the @command{rsync} command to transfer files is almost
+identical to the @option{scp} method.
+
+While @command{rsync} performs much better than @command{scp} when
+transferring files that exist on both hosts, this advantage is lost if
+the file exists only on one side of the connection.
+
+The @command{rsync} based method may be considerably faster than the
address@hidden based methods when writing to the remote system. Reading
+files to the local machine is no faster than with a direct copy.
+
+This method supports the @samp{-p} hack.
+
+
address@hidden @option{scpx} --- @command{ssh} and @command{scp}
address@hidden method scpx
address@hidden scpx method
address@hidden scp (with scpx method)
address@hidden ssh (with scpx method)
+
+As you would expect, this is similar to @option{scp}, only a little
+different. Whereas @option{scp} opens a normal interactive shell on
+the remote host, this option uses @samp{ssh -t -t @var{host} -l
address@hidden /bin/sh} to open a connection. This is useful for users
+where the normal login shell is set up to ask them a number of
+questions when logging in. This procedure avoids these questions, and
+just gives @value{tramp} a more-or-less `standard' login shell to work
+with.
+
+This is also useful for Windows users where @command{ssh}, when
+invoked from an @value{emacsname} buffer, tells them that it is not
+allocating a pseudo tty. When this happens, the login shell is wont
+to not print any shell prompt, which confuses @value{tramp} mightily.
+
+This method supports the @samp{-p} hack.
+
+
address@hidden @option{scpc} --- @command{ssh} and @command{scp}
address@hidden method scpx
address@hidden scpx method
address@hidden scp (with scpx method)
address@hidden ssh (with scpx method)
+
+Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
address@hidden This allows @option{scp} to reuse an existing
address@hidden channel, which increases performance.
+
+Before you use this method, you shall check whether your @option{ssh}
+implementation does support this option. Try from the command line
+
address@hidden
+ssh localhost -o ControlMaster=yes
address@hidden example
+
+This method supports the @samp{-p} hack.
+
+
address@hidden @option{pscp} --- @command{plink} and @command{pscp}
address@hidden method pscp
address@hidden pscp method
address@hidden pscp (with pscp method)
address@hidden plink (with pscp method)
address@hidden PuTTY (with pscp method)
+
+This method is similar to @option{scp}, but it uses the
address@hidden command to connect to the remote host, and it uses
address@hidden for transferring the files. These programs are part
+of PuTTY, an SSH implementation for Windows.
+
+This method supports the @samp{-P} hack.
+
+
address@hidden @option{psftp} --- @command{plink} and @command{psftp}
address@hidden method psftp
address@hidden psftp method
address@hidden psftp (with psftp method)
address@hidden plink (with psftp method)
address@hidden PuTTY (with psftp method)
+
+As you would expect, this method is similar to @option{sftp}, but it
+uses the @command{plink} command to connect to the remote host, and it
+uses @command{psftp} for transferring the files. These programs are
+part of PuTTY, an SSH implementation for Windows.
+
+This method supports the @samp{-P} hack.
+
+
address@hidden @option{fcp} --- @command{fsh} and @command{fcp}
address@hidden method fcp
address@hidden fcp method
address@hidden fsh (with fcp method)
address@hidden fcp (with fcp method)
+
+This method is similar to @option{scp}, but it uses the @command{fsh}
+command to connect to the remote host, and it uses @command{fcp} for
+transferring the files. @command{fsh/fcp} are a front-end for
address@hidden which allow for reusing the same @command{ssh} session
+for submitting several commands. This avoids the startup overhead of
address@hidden (which has to establish a secure connection whenever it
+is called). Note, however, that you can also use one of the inline
+methods to achieve a similar effect.
+
+This method uses the command @samp{fsh @var{host} -l @var{user}
+/bin/sh -i} to establish the connection, it does not work to just say
address@hidden @var{host} -l @var{user}}.
+
address@hidden method fsh
address@hidden fsh method
+
+There is no inline method using @command{fsh} as the multiplexing
+provided by the program is not very useful in our context. @value{tramp}
+opens just one connection to the remote host and then keeps it open,
+anyway.
+
+
address@hidden @option{ftp}
address@hidden method ftp
address@hidden ftp method
+
+This is not a native @value{tramp} method. Instead of, it forwards all
+requests to @value{ftppackagename}.
address@hidden xemacs
+This works only for unified filenames, see @ref{Issues}.
address@hidden ifset
+
+
address@hidden @option{smb} --- @command{smbclient}
address@hidden method smb
address@hidden smb method
+
+This is another not natural @value{tramp} method. It uses the
address@hidden 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
+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
+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.
+This can be suppressed by @ref{Password caching}.
+
+MS Windows uses for authorization 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 machine @code{melancholia} as user @code{daniel} of the domain
address@hidden, and edit @file{.emacs} in the home directory (share
address@hidden) I would specify the filename @address@hidden,
+daniel%BIZARRE, melancholia, /daniel$$/.emacs}}.
+
+Depending on the Windows domain configuration, a Windows user might be
+considered as domain user per default. In order to connect as local
+user, the WINS name of that machine must be given as domain name.
+Usually, it is the machine name in capital letters. In the example
+above, the local user @code{daniel} would be specified as
address@hidden@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}.
+
+The domain name as well as the user name are optional. If no user
+name is specified at all, the anonymous user (without password
+prompting) is assumed. This is different from all other @value{tramp}
+methods, where in such a case the local user name is taken.
+
+The @option{smb} method supports the @samp{-p} hack.
+
address@hidden note:} If @value{emacsname} runs locally under MS
+Windows, this method isn't available. Instead of, 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.
+
address@hidden table
+
+
address@hidden emacsgw
address@hidden Gateway methods
address@hidden Gateway methods
address@hidden methods, gateway
address@hidden gateway methods
+
+Gateway methods are not methods to access a remote host directly.
+These methods are intended to pass firewalls or proxy servers.
+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
+port setting (referred to as @samp{-p} kludge). This is because
address@hidden targets the accompanied method to
address@hidden, from where the firewall or proxy server
+is accessed to.
+
+Gateway methods support user name and password declarations. These
+are used to authenticate towards the corresponding firewall or proxy
+server. They can be passed only if your friendly administrator has
+granted your access.
+
address@hidden @asis
address@hidden @option{tunnel}
address@hidden method tunnel
address@hidden tunnel method
+
+This method implements an HTTP tunnel via the @command{CONNECT}
+command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server
+shall support this command.
+
+As authentication method, only @option{Basic Authentication} (see RFC
+2617) is implemented so far. If no port number is given in the
+declaration, port @option{8080} is used for the proxy server.
+
+
address@hidden @option{socks}
address@hidden method socks
address@hidden socks method
+
+The @command{socks} method provides access to SOCKSv5 servers (see
+RFC 1928). @option{Username/Password Authentication} according to RFC
+1929 is supported.
+
+The default port number of the socks server is @option{1080}, if not
+specified otherwise.
+
address@hidden table
address@hidden ifset
+
+
address@hidden Default Method
address@hidden Selecting a default method
address@hidden default method
+
address@hidden tramp-default-method
+When you select an appropriate transfer method for your typical usage
+you should set the variable @code{tramp-default-method} to reflect that
+choice. This variable controls which method will be used when a method
+is not specified in the @value{tramp} file name. For example:
+
address@hidden
+(setq tramp-default-method "ssh")
address@hidden lisp
+
address@hidden tramp-default-method-alist
+You can also specify different methods for certain user/host
+combinations, via the variable @code{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}
+method for all host names matching @samp{lily}. The third line
+specifies to use the @option{su} method for the user @samp{root} on
+the machine @samp{localhost}.
+
address@hidden
+(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"))
address@hidden lisp
+
address@hidden
+See the documentation for the variable
address@hidden for more details.
+
+External transfer methods are normally preferable to inline transfer
+methods, giving better performance.
+
address@hidden methods}.
address@hidden transfer methods}.
+
+Another consideration with the selection of transfer methods is the
+environment you will use them in and, especially when used over the
+Internet, the security implications of your preferred method.
+
+The @option{rsh} and @option{telnet} methods send your password as
+plain text as you log in to the remote machine, as well as
+transferring the files in such a way that the content can easily be
+read from other machines.
+
+If you need to connect to remote systems that are accessible from the
+Internet, you should give serious thought to using @option{ssh} based
+methods to connect. These provide a much higher level of security,
+making it a non-trivial exercise for someone to obtain your password
+or read the content of the files you are editing.
+
+
address@hidden Which method is the right one for me?
address@hidden choosing the right method
+
+Given all of the above, you are probably thinking that this is all fine
+and good, but it's not helping you to choose a method! Right you are.
+As a developer, we don't want to boss our users around but give them
+maximum freedom instead. However, the reality is that some users would
+like to have some guidance, so here I'll try to give you this guidance
+without bossing you around. You tell me whether it works @dots{}
+
+My suggestion is to use an inline method. For large files, out-of-band
+methods might be more efficient, but I guess that most people will want
+to edit mostly small files.
+
+I guess that these days, most people can access a remote machine by
+using @command{ssh}. So I suggest that you use the @option{ssh}
+method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost,
+/etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other
+host.
+
+If you can't use @option{ssh} to log in to the remote host, then
+select a method that uses a program that works. For instance, Windows
+users might like the @option{plink} method which uses the PuTTY
+implementation of @command{ssh}. Or you use Kerberos and thus like
address@hidden
+
+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
address@hidden@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
+out-of-band methods are faster than inline methods for large files.
+Note, however, that out-of-band methods suffer from some limitations.
+Please try first whether you really get a noticeable speed advantage
+from using an out-of-band method! Maybe even for large files, inline
+methods are fast enough.
+
+
address@hidden Default User
address@hidden Selecting a default user
address@hidden default user
+
+The user part of a @value{tramp} file name can be omitted. Usually,
+it is replaced by the user name you are logged in. Often, this is not
+what you want. A typical use of @value{tramp} might be to edit some
+files with root permissions on the local host. This case, you should
+set the variable @code{tramp-default-user} to reflect that choice.
+For example:
+
address@hidden
+(setq tramp-default-user "root")
address@hidden lisp
+
address@hidden is regarded as obsolete, and will be removed
+soon.
+
address@hidden tramp-default-user-alist
+You can also specify different users for certain method/host
+combinations, via the variable @code{tramp-default-user-alist}. For
+example, if you always have to use the user @samp{john} in the domain
address@hidden, you can specify the following:
+
address@hidden
+(add-to-list 'tramp-default-user-alist
+ '("ssh" ".*\\.somewhere\\.else\\'" "john"))
address@hidden lisp
+
address@hidden
+See the documentation for the variable
address@hidden for more details.
+
+One trap to fall in must be known. If @value{tramp} finds a default
+user, this user will be passed always to the connection command as
+parameter (for example @samp{ssh here.somewhere.else -l john}. If you
+have specified another user for your command in its configuration
+files, @value{tramp} cannot know it, and the remote access will fail.
+If you have specified in the given example in @file{~/.ssh/config} the
+lines
+
address@hidden
+Host here.somewhere.else
+ User lily
address@hidden example
+
address@hidden
+than you must discard selecting a default user by @value{tramp}. This
+will be done by setting it to @code{nil} (or @samp{lily}, likewise):
+
address@hidden
+(add-to-list 'tramp-default-user-alist
+ '("ssh" "\\`here\\.somewhere\\.else\\'" nil))
address@hidden lisp
+
+The last entry in @code{tramp-default-user-alist} could be your
+default user you'll apply predominantly. You shall @emph{append} it
+to that list at the end:
+
address@hidden
+(add-to-list 'tramp-default-user-alist '(nil nil "jonas") t)
address@hidden lisp
+
+
address@hidden Default Host
address@hidden Selecting a default host
address@hidden default host
+
address@hidden tramp-default-host
+Finally, it is even possible to omit the host name part of a
address@hidden file name. This case, the value of the variable
address@hidden is used. Per default, it is initialized
+with the host name your local @value{emacsname} is running.
+
+If you, for example, use @value{tramp} mainly to contact the host
address@hidden as user @samp{john}, you can specify:
+
address@hidden
+(setq tramp-default-user "john"
+ tramp-default-host "target")
address@hidden lisp
+
+Then the simple file name @address@hidden, , ,}} will connect you
+to John's home directory on target.
address@hidden emacs
+Note, however, that the most simplification @samp{/::} won't work,
+because @samp{/:} is the prefix for quoted file names.
address@hidden ifset
+
+
address@hidden Multi-hops
address@hidden Connecting to a remote host using multiple hops
address@hidden multi-hop
address@hidden proxy hosts
+
+Sometimes, the methods described before are not sufficient. Sometimes,
+it is not possible to connect to a remote host using a simple command.
+For example, if you are in a secured network, you might have to log in
+to a `bastion host' first before you can connect to the outside world.
+Of course, the target host may also require a bastion host.
+
address@hidden tramp-default-proxies-alist
+In order to specify such multiple hops, it is possible to define a proxy
+host to pass through, via the variable
address@hidden This variable keeps a list of
+triples (@var{host} @var{user} @var{proxy}).
+
+ The first matching item specifies the proxy host to be passed for a
+file name located on a remote target matching @var{user}@@@var{host}.
address@hidden and @var{user} are regular expressions or @code{nil}, which
+is interpreted as a regular expression which always matches.
+
address@hidden must be a Tramp filename which localname part is ignored.
+Method and user name on @var{proxy} are optional, which is interpreted
+with the default values.
address@hidden emacsgw
+The method must be an inline or gateway method (@pxref{Inline
+methods}, @pxref{Gateway methods}).
address@hidden ifset
address@hidden emacsgw
+The method must be an inline method (@pxref{Inline methods}).
address@hidden ifclear
+If @var{proxy} is @code{nil}, no additional hop is required reaching
address@hidden@@@var{host}.
+
+If you, for example, must pass the host @samp{bastion.your.domain} as
+user @samp{bird} for any remote host which is not located in your local
+domain, you can set
+
address@hidden
+(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))
address@hidden lisp
+
+Please note the order of the code. @code{add-to-list} adds elements at the
+beginning of a list. Therefore, most relevant rules must be added last.
+
+Proxy hosts can be cascaded. If there is another host called
address@hidden, which is the only one in your local domain who
+is allowed connecting @samp{bastion.your.domain}, you can add another
+rule:
+
address@hidden
+(add-to-list 'tramp-default-proxies-alist
+ '("\\`bastion\\.your\\.domain\\'"
+ "\\`bird\\'"
+ "@trampfn{ssh, , jump.your.domain,}"))
address@hidden lisp
+
address@hidden can contain the patterns @code{%h} or @code{%u}. These
+patterns are replaced by the strings matching @var{host} or
address@hidden, respectively.
+
+If you, for example, wants to work as @samp{root} on hosts in the
+domain @samp{your.domain}, but login as @samp{root} is disabled for
+non-local access, you might add the following rule:
+
address@hidden
+(add-to-list 'tramp-default-proxies-alist
+ '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
address@hidden lisp
+
+Opening @address@hidden, , 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.
+
address@hidden emacsgw
+Finally, @code{tramp-default-proxies-alist} can be used to pass
+firewalls or proxy servers. Imagine your local network has a host
address@hidden which is used on port 3128 as HTTP proxy to
+the outer world. Your friendly administrator has granted you access
+under your user name to @samp{host.other.domain} on that proxy
address@hidden tunnels are intended for secure SSL/TLS
+communication. Therefore, many proxy server restrict the tunnels to
+related target ports. You might need to run your ssh server on your
+target host @samp{host.other.domain} on such a port, like 443 (https).
+See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall}
+for discussion of ethical issues.} You would need to add the
+following rule:
+
address@hidden
+(add-to-list 'tramp-default-proxies-alist
+ '("\\`host\\.other\\.domain\\'" nil
+ "@trampfn{tunnel, , proxy.your.domain#3128,}"))
address@hidden lisp
+
+Gateway methods can be declared as first hop only in a multiple hop
+chain.
address@hidden ifset
+
+
address@hidden Customizing Methods
address@hidden Using Non-Standard Methods
address@hidden customizing methods
address@hidden using non-standard methods
address@hidden create your own methods
+
+There is a variable @code{tramp-methods} which you can change if the
+predefined methods don't seem right.
+
+For the time being, I'll refer you to the Lisp documentation of that
+variable, accessible with @kbd{C-h v tramp-methods @key{RET}}.
+
+
address@hidden Customizing Completion
address@hidden Selecting config files for user/host name completion
address@hidden customizing completion
address@hidden selecting config files
address@hidden tramp-completion-function-alist
+
+The variable @code{tramp-completion-function-alist} is intended to
+customize which files are taken into account for user and host name
+completion (@pxref{Filename completion}). For every method, it keeps
+a set of configuration files, accompanied by a Lisp function able to
+parse that file. Entries in @code{tramp-completion-function-alist}
+have the form (@var{method} @var{pair1} @var{pair2} ...).
+
+Each @var{pair} is composed of (@var{function} @var{file}).
address@hidden is responsible to extract user names and host names
+from @var{file} for completion. There are two functions which access
+this variable:
+
address@hidden tramp-get-completion-function method
+This function returns the list of completion functions for @var{method}.
+
+Example:
address@hidden
+(tramp-get-completion-function "rsh")
+
+ @result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
+ (tramp-parse-rhosts "~/.rhosts"))
address@hidden example
address@hidden defun
+
address@hidden tramp-set-completion-function method function-list
+This function sets @var{function-list} as list of completion functions
+for @var{method}.
+
+Example:
address@hidden
+(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"))
address@hidden example
address@hidden defun
+
+The following predefined functions parsing configuration files exist:
+
address@hidden @asis
address@hidden @code{tramp-parse-rhosts}
address@hidden tramp-parse-rhosts
+
+This function parses files which are syntactical equivalent to
address@hidden/.rhosts}. It returns both host names and user names, if
+specified.
+
address@hidden @code{tramp-parse-shosts}
address@hidden tramp-parse-shosts
+
+This function parses files which are syntactical equivalent to
address@hidden/.ssh/known_hosts}. Since there are no user names specified
+in such files, it can return host names only.
+
address@hidden @code{tramp-parse-sconfig}
address@hidden tramp-parse-shosts
+
+This function returns the host nicknames defined by @code{Host} entries
+in @file{~/.ssh/config} style files.
+
address@hidden @code{tramp-parse-shostkeys}
address@hidden tramp-parse-shostkeys
+
+SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and
address@hidden/ssh2/hostkeys/*}. Hosts are coded in file names
address@hidden@address@hidden User names
+are always @code{nil}.
+
address@hidden @code{tramp-parse-sknownhosts}
address@hidden tramp-parse-shostkeys
+
+Another SSH2 style parsing of directories like
address@hidden/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This
+case, hosts names are coded in file names
address@hidden@address@hidden User names are always @code{nil}.
+
address@hidden @code{tramp-parse-hosts}
address@hidden tramp-parse-hosts
+
+A function dedicated to @file{/etc/hosts} style files. It returns
+host names only.
+
address@hidden @code{tramp-parse-passwd}
address@hidden tramp-parse-passwd
+
+A function which parses @file{/etc/passwd} like files. Obviously, it
+can return user names only.
+
address@hidden @code{tramp-parse-netrc}
address@hidden tramp-parse-netrc
+
+Finally, a function which parses @file{~/.netrc} like files.
address@hidden table
+
+If you want to keep your own data in a file, with your own structure,
+you might provide such a function as well. This function must meet
+the following conventions:
+
address@hidden my-tramp-parse file
address@hidden must be either a file name on your host, or @code{nil}.
+The function must return a list of (@var{user} @var{host}), which are
+taken as candidates for user and host name completion.
+
+Example:
address@hidden
+(my-tramp-parse "~/.my-tramp-hosts")
+
+ @result{} ((nil "toto") ("daniel" "melancholia"))
address@hidden example
address@hidden defun
+
+
address@hidden Password caching
address@hidden Reusing passwords for several connections.
address@hidden passwords
+
+Sometimes it is necessary to connect to the same remote host several
+times. Reentering passwords again and again would be annoying, when
+the chosen method does not support access without password prompt
+through own configuration.
+
+By default, @value{tramp} caches the passwords entered by you. They will
+be reused next time if a connection needs them for the same user name
+and host name, independently of the connection method.
+
address@hidden password-cache-expiry
+Passwords are not saved permanently, that means the password caching
+is limited to the lifetime of your @value{emacsname} session. You
+can influence the lifetime of password caching by customizing the
+variable @code{password-cache-expiry}. The value is the number of
+seconds how long passwords are cached. Setting it to @code{nil}
+disables the expiration.
+
address@hidden tramp-clear-passwd
+A password is removed from the cache if a connection isn't established
+successfully. You can remove a password from the cache also by
+executing @kbd{M-x tramp-clear-passwd} in a buffer containing a
+related remote file or directory.
+
address@hidden password-cache
+If you don't like this feature for security reasons, password caching
+can be disabled totally by customizing the variable
address@hidden (setting it to @code{nil}).
+
+Implementation Note: password caching is based on the package
address@hidden in No Gnus. For the time being, it is activated
+only when this package is seen in the @code{load-path} while loading
address@hidden
address@hidden installchapter
+If you don't use No Gnus, you can take @file{password.el} from the
address@hidden @file{contrib} directory, see @ref{Installation
+parameters}.
address@hidden ifset
+It will be activated mandatory once No Gnus has found its way into
address@hidden
+
+
address@hidden Connection caching
address@hidden Reusing connection related information.
address@hidden caching
+
address@hidden tramp-persistency-file-name
+In order to reduce initial connection time, @value{tramp} stores
+connection related information persistently. The variable
address@hidden keeps the file name where these
+information are written. Its default value is
address@hidden emacs
address@hidden/.emacs.d/tramp}.
address@hidden ifset
address@hidden xemacs
address@hidden/.xemacs/tramp}.
address@hidden ifset
+It is recommended to choose a local file name.
+
address@hidden reads this file during startup, and writes it when
+exiting @value{emacsname}. You can simply remove this file if
address@hidden shall be urged to recompute these information next
address@hidden startup time.
+
+Using such persistent information can be disabled by setting
address@hidden to @code{nil}.
+
+
address@hidden Remote Programs
address@hidden How @value{tramp} finds and uses programs on the remote machine.
+
address@hidden depends on a number of programs on the remote host in order to
+function, including @command{ls}, @command{test}, @command{find} and
address@hidden
+
+In addition to these required tools, there are various tools that may be
+required based on the connection method. See @ref{Inline methods} and
address@hidden transfer methods} for details on these.
+
+Certain other tools, such as @command{perl} (or @command{perl5}) and
address@hidden will be used if they can be found. When they are
+available, they are used to improve the performance and accuracy of
+remote file access.
+
address@hidden tramp-remote-path
+When @value{tramp} connects to the remote machine, it searches for the
+programs that it can use. The variable @code{tramp-remote-path}
+controls the directories searched on the remote machine.
+
+By default, this is set to a reasonable set of defaults for most
+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
address@hidden/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
+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.
+
+To add a directory to the remote search path, you could use code such
+as:
+
address@hidden
address@hidden;; We load @value{tramp} to define the variable.}
+(require 'tramp)
address@hidden;; We have @command{perl} in "/usr/local/perl/bin"}
+(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
address@hidden lisp
+
address@hidden 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}.
+
+
address@hidden Remote shell setup
address@hidden node-name, next, previous, up
address@hidden Remote shell setup hints
address@hidden remote shell setup
address@hidden @file{.profile} file
address@hidden @file{.login} file
address@hidden shell init files
+
+As explained in the @ref{Overview} section, @value{tramp} connects to the
+remote host and talks to the shell it finds there. Of course, when you
+log in, the shell executes its init files. Suppose your init file
+requires you to enter the birth date of your mother; clearly @value{tramp}
+does not know this and hence fails to log you in to that host.
+
+There are different possible strategies for pursuing this problem. One
+strategy is to enable @value{tramp} to deal with all possible situations.
+This is a losing battle, since it is not possible to deal with
address@hidden situations. The other strategy is to require you to set up
+the remote host such that it behaves like @value{tramp} expects. This might
+be inconvenient because you have to invest a lot of effort into shell
+setup before you can begin to use @value{tramp}.
+
+The package, therefore, pursues a combined approach. It tries to
+figure out some of the more common setups, and only requires you to
+avoid really exotic stuff. For example, it looks through a list of
+directories to find some programs on the remote host. And also, it
+knows that it is not obvious how to check whether a file exists, and
+therefore it tries different possibilities. (On some hosts and
+shells, the command @command{test -e} does the trick, on some hosts
+the shell builtin doesn't work but the program @command{/usr/bin/test
+-e} or @command{/bin/test -e} works. And on still other hosts,
address@hidden -d} is the right way to do this.)
+
+Below you find a discussion of a few things that @value{tramp} does not deal
+with, and that you therefore have to set up correctly.
+
address@hidden @asis
address@hidden @var{shell-prompt-pattern}
address@hidden shell-prompt-pattern
+
+After logging in to the remote host, @value{tramp} has to wait for the remote
+shell startup to finish before it can send commands to the remote
+shell. The strategy here is to wait for the shell prompt. In order to
+recognize the shell prompt, the variable @code{shell-prompt-pattern} has
+to be set correctly to recognize the shell prompt on the remote host.
+
+Note that @value{tramp} requires the match for @code{shell-prompt-pattern}
+to be at the end of the buffer. Many people have something like the
+following as the value for the variable: @code{"^[^>$][>$] *"}. Now
+suppose your shell prompt is @code{a <b> c $ }. In this case,
address@hidden recognizes the @code{>} character as the end of the prompt,
+but it is not at the end of the buffer.
+
address@hidden @var{tramp-shell-prompt-pattern}
address@hidden tramp-shell-prompt-pattern
+
+This regular expression is used by @value{tramp} in the same way as
address@hidden, to match prompts from the remote shell.
+This second variable exists because the prompt from the remote shell
+might be different from the prompt from a local shell --- after all,
+the whole point of @value{tramp} is to log in to remote hosts as a
+different user. The default value of
address@hidden is the same as the default value of
address@hidden, which is reported to work well in many
+circumstances.
+
address@hidden @command{tset} and other questions
address@hidden Unix command tset
address@hidden tset Unix command
+
+Some people invoke the @command{tset} program from their shell startup
+scripts which asks the user about the terminal type of the shell.
+Maybe some shells ask other questions when they are started.
address@hidden does not know how to answer these questions. There are
+two approaches for dealing with this problem. One approach is to take
+care that the shell does not ask any questions when invoked from
address@hidden You can do this by checking the @code{TERM}
+environment variable, it will be set to @code{dumb} when connecting.
+
address@hidden tramp-terminal-type
+The variable @code{tramp-terminal-type} can be used to change this value
+to @code{dumb}.
+
address@hidden tramp-actions-before-shell
+The other approach is to teach @value{tramp} about these questions. See
+the variable @code{tramp-actions-before-shell}. Example:
+
address@hidden
+(defconst my-tramp-prompt-regexp
+ (concat (regexp-opt '("Enter the birth date of your mother:") t)
+ "\\s-*")
+ "Regular expression matching my login prompt question.")
+
+(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"))))
+
+(add-to-list 'tramp-actions-before-shell
+ '(my-tramp-prompt-regexp my-tramp-action))
address@hidden lisp
+
+
address@hidden Environment variables named like users in @file{.profile}
+
+If you have a user named frumple and set the variable @code{FRUMPLE} in
+your shell environment, then this might cause trouble. Maybe rename
+the variable to @code{FRUMPLE_DIR} or the like.
+
+This weird effect was actually reported by a @value{tramp} user!
+
+
address@hidden Non-Bourne commands in @file{.profile}
+
+After logging in to the remote host, @value{tramp} issues the command
address@hidden /bin/sh}. (Actually, the command is slightly
+different.) When @command{/bin/sh} is executed, it reads some init
+files, such as @file{~/.shrc} or @file{~/.profile}.
+
+Now, some people have a login shell which is not @code{/bin/sh} but a
+Bourne-ish shell such as bash or ksh. Some of these people might put
+their shell setup into the files @file{~/.shrc} or @file{~/.profile}.
+This way, it is possible for non-Bourne constructs to end up in those
+files. Then, @command{exec /bin/sh} might cause the Bourne shell to
+barf on those constructs.
+
+As an example, imagine somebody putting @command{export FOO=bar} into
+the file @file{~/.profile}. The standard Bourne shell does not
+understand this syntax and will emit a syntax error when it reaches
+this line.
+
+Another example is the tilde (@code{~}) character, say when adding
address@hidden/bin} to @code{$PATH}. Many Bourne shells will not expand this
+character, and since there is usually no directory whose name consists
+of the single character tilde, strange things will happen.
+
+What can you do about this?
+
+Well, one possibility is to make sure that everything in
address@hidden/.shrc} and @file{~/.profile} on all remote hosts is
+Bourne-compatible. In the above example, instead of @command{export
+FOO=bar}, you might use @command{FOO=bar; export FOO} instead.
+
+The other possibility is to put your non-Bourne shell setup into some
+other files. For example, bash reads the file @file{~/.bash_profile}
+instead of @file{~/.profile}, if the former exists. So bash
+aficionados just rename their @file{~/.profile} to
address@hidden/.bash_profile} on all remote hosts, and Bob's your uncle.
+
+The @value{tramp} developers would like to circumvent this problem, so
+if you have an idea about it, please tell us. However, we are afraid
+it is not that simple: before saying @command{exec /bin/sh},
address@hidden does not know which kind of shell it might be talking
+to. It could be a Bourne-ish shell like ksh or bash, or it could be a
+csh derivative like tcsh, or it could be zsh, or even rc. If the
+shell is Bourne-ish already, then it might be prudent to omit the
address@hidden /bin/sh} step. But how to find out if the shell is
+Bourne-ish?
+
address@hidden table
+
+
address@hidden Auto-save and Backup
address@hidden Auto-save and Backup configuration
address@hidden auto-save
address@hidden backup
address@hidden emacs
address@hidden backup-directory-alist
address@hidden ifset
address@hidden xemacs
address@hidden bkup-backup-directory-info
address@hidden ifset
+
+Normally, @value{emacsname} writes backup files to the same directory
+as the original files, but this behavior can be changed via the
+variable
address@hidden emacs
address@hidden
address@hidden ifset
address@hidden xemacs
address@hidden
address@hidden ifset
+In connection with @value{tramp}, this can have unexpected side
+effects. Suppose that you specify that all backups should go to the
+directory @file{~/.emacs.d/backups/}, and then you edit the file
address@hidden@trampfn{su, root, localhost, /etc/secretfile}}. The effect is
+that the backup file will be owned by you and not by root, thus
+possibly enabling others to see it even if they were not intended to
+see it.
+
+When
address@hidden emacs
address@hidden
address@hidden ifset
address@hidden xemacs
address@hidden
address@hidden ifset
+is @code{nil} (the default), such problems do not occur.
+
+Therefore, it is useful to set special values for @value{tramp}
+files. For example, the following statement effectively `turns off'
+the effect of
address@hidden emacs
address@hidden
address@hidden ifset
address@hidden xemacs
address@hidden
address@hidden ifset
+for @value{tramp} files:
+
address@hidden emacs
address@hidden
+(add-to-list 'backup-directory-alist
+ (cons tramp-file-name-regexp nil))
address@hidden lisp
address@hidden ifset
address@hidden xemacs
address@hidden
+(require 'backup-dir)
+(add-to-list 'bkup-backup-directory-info
+ (list tramp-file-name-regexp ""))
address@hidden lisp
address@hidden ifset
+
+Another possibility is to use the @value{tramp} variable
address@hidden emacs
address@hidden
address@hidden ifset
address@hidden xemacs
address@hidden
address@hidden ifset
+This variable has the same meaning like
address@hidden emacs
address@hidden
address@hidden ifset
address@hidden xemacs
address@hidden
address@hidden ifset
+If a @value{tramp} file is backed up, and DIRECTORY is an absolute
+local file name, DIRECTORY is prepended with the @value{tramp} file
+name prefix of the file to be backed up.
+
address@hidden
+Example:
+
address@hidden emacs
address@hidden
+(add-to-list 'backup-directory-alist
+ (cons "." "~/.emacs.d/backups/"))
+(setq tramp-backup-directory-alist backup-directory-alist)
address@hidden lisp
address@hidden ifset
address@hidden xemacs
address@hidden
+(require 'backup-dir)
+(add-to-list 'bkup-backup-directory-info
+ (list "." "~/.emacs.d/backups/" 'full-path))
+(setq tramp-bkup-backup-directory-info bkup-backup-directory-info)
address@hidden lisp
address@hidden ifset
+
address@hidden
+The backup file name of @address@hidden, root, localhost,
+/etc/secretfile}} would be
address@hidden emacs
address@hidden@trampfn{su, root, localhost,
+~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
address@hidden ifset
address@hidden xemacs
address@hidden@trampfn{su, root, localhost,
+~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}
address@hidden ifset
+
+The same problem can happen with auto-saving files.
address@hidden emacs
+Since @value{emacsname} 21, the variable
address@hidden keeps information, on which
+directory an auto-saved file should go. By default, it is initialized
+for @value{tramp} files to the local temporary directory.
+
+On some versions of @value{emacsname}, namely the version built for
+Debian GNU/Linux, the variable @code{auto-save-file-name-transforms}
+contains the directory where @value{emacsname} was built. A
+workaround is to manually set the variable to a sane value.
+
+If auto-saved files should go into the same directory as the original
+files, @code{auto-save-file-name-transforms} should be set to @code{nil}.
+
+Another possibility is to set the variable
address@hidden to a proper value.
address@hidden ifset
address@hidden xemacs
+For this purpose you can set the variable @code{auto-save-directory}
+to a proper value.
address@hidden ifset
+
+
address@hidden Windows setup hints
address@hidden Issues with Cygwin ssh
address@hidden Cygwin, issues
+
+This section needs a lot of work! Please help.
+
address@hidden method sshx with Cygwin
address@hidden sshx method with Cygwin
+The recent Cygwin installation of @command{ssh} works only with a
+Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x
+eshell}, and starting @kbd{ssh test.machine}. The problem is evident
+if you see a message like this:
+
address@hidden
+Pseudo-terminal will not be allocated because stdin is not a terminal.
address@hidden example
+
+Older @command{ssh} versions of Cygwin are told to cooperate with
address@hidden selecting @option{sshx} as the connection method. You
+can find information about setting up Cygwin in their FAQ at
address@hidden://cygwin.com/faq/}.
+
address@hidden method scpx with Cygwin
address@hidden scpx method with Cygwin
+If you wish to use the @option{scpx} connection method, then you might
+have the problem that @value{emacsname} calls @command{scp} with a
+Windows filename such as @code{c:/foo}. The Cygwin version of
address@hidden does not know about Windows filenames and interprets
+this as a remote filename on the host @code{c}.
+
+One possible workaround is to write a wrapper script for @option{scp}
+which converts the Windows filename to a Cygwinized filename.
+
address@hidden Cygwin and ssh-agent
address@hidden SSH_AUTH_SOCK and @value{emacsname} on Windows
+If you want to use either @option{ssh} based method on Windows, then
+you might encounter problems with @command{ssh-agent}. Using this
+program, you can avoid typing the pass-phrase every time you log in.
+However, if you start @value{emacsname} from a desktop shortcut, then
+the environment variable @code{SSH_AUTH_SOCK} is not set and so
address@hidden and thus @value{tramp} and thus @command{ssh} and
address@hidden started from @value{tramp} cannot communicate with
address@hidden It works better to start @value{emacsname} from
+the shell.
+
+If anyone knows how to start @command{ssh-agent} under Windows in such a
+way that desktop shortcuts can profit, please holler. I don't really
+know anything at all about address@hidden
+
+
address@hidden Usage
address@hidden Using @value{tramp}
address@hidden using @value{tramp}
+
+Once you have installed @value{tramp} it will operate fairly
+transparently. You will be able to access files on any remote machine
+that you can log in to as though they were local.
+
+Files are specified to @value{tramp} using a formalized syntax specifying the
+details of the system to connect to. This is similar to the syntax used
+by the @value{ftppackagename} package.
+
address@hidden type-ahead
+Something that might happen which surprises you is that
address@hidden remembers all your keystrokes, so if you see a
+password prompt from @value{emacsname}, say, and hit @address@hidden
+twice instead of once, then the second keystroke will be processed by
address@hidden after @value{tramp} has done its thing. Why, this
+type-ahead is normal behavior, you say. Right you are, but be aware
+that opening a remote file might take quite a while, maybe half a
+minute when a connection needs to be opened. Maybe after half a
+minute you have already forgotten that you hit that key!
+
address@hidden
+* Filename Syntax:: @value{tramp} filename conventions.
+* Alternative Syntax:: URL-like filename syntax.
+* Filename completion:: Filename completion.
+* Remote processes:: Integration with other @value{emacsname}
packages.
address@hidden menu
+
+
address@hidden Filename Syntax
address@hidden @value{tramp} filename conventions
address@hidden filename syntax
address@hidden filename examples
+
+To access the file @var{localname} on the remote machine @var{machine}
+you would specify the filename @address@hidden, , 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.
+
address@hidden @file
address@hidden @trampfn{, , melancholia, .emacs}
+Edit the file @file{.emacs} in your home directory on the machine
address@hidden
+
address@hidden @trampfn{, , melancholia.danann.net, .emacs}
+This edits the same file, using the fully qualified domain name of
+the machine.
+
address@hidden @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.
+
address@hidden @trampfn{, , melancholia, ~daniel/.emacs}
+This edits the file @file{.emacs} in the home directory of the user
address@hidden on the machine @code{melancholia}. The @file{~<user>}
+construct is expanded to the home directory of that user on the remote
+machine.
+
address@hidden @trampfn{, , melancholia, /etc/squid.conf}
+This edits the file @file{/etc/squid.conf} on the machine
address@hidden
+
address@hidden table
+
+Unless you specify a different name to use, @value{tramp} will use the
+current local user name as the remote user name to log in with. If you
+need to log in as a different user, you can specify the user name as
+part of the filename.
+
+To log in to the remote machine as a specific user, you use the syntax
address@hidden@trampfn{, user, machine, path/to.file}}. That means that
+connecting to @code{melancholia} as @code{daniel} and editing
address@hidden in your home directory you would specify
address@hidden@trampfn{, daniel, melancholia, .emacs}}.
+
+It is also possible to specify other file transfer methods
+(@pxref{Default Method}) as part of the filename.
address@hidden emacs
+This is done by putting the method before the user and host name, as
+in @address@hidden@address@hidden (Note the
+trailing colon).
address@hidden ifset
address@hidden xemacs
+This is done by replacing the initial @address@hidden with
address@hidden@value{prefix}<method>@value{postfixhop}}. (Note the trailing
+slash!).
address@hidden ifset
+The user, machine and file specification remain the same.
+
+So, to connect to the machine @code{melancholia} as @code{daniel},
+using the @option{ssh} method to transfer files, and edit
address@hidden in my home directory I would specify the filename
address@hidden@trampfn{ssh, daniel, melancholia, .emacs}}.
+
+
address@hidden Alternative Syntax
address@hidden URL-like filename syntax
address@hidden filename syntax
address@hidden filename examples
+
+Additionally to the syntax described in the previous chapter, it is
+possible to use a URL-like syntax for @value{tramp}. This can be
+switched on by customizing the variable @code{tramp-syntax}. Please
+note that this feature is experimental for the time being.
+
+The variable @code{tramp-syntax} must be set before requiring @value{tramp}:
+
address@hidden
+(setq tramp-syntax 'url)
+(require 'tramp)
address@hidden lisp
+
+Then, a @value{tramp} filename would look like this:
address@hidden/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}.
address@hidden/@var{method}://} is mandatory, all other parts are optional.
address@hidden:@var{port}} is useful for methods only who support this.
+
+The last example from the previous section would look like this:
address@hidden/ssh://daniel@@melancholia/.emacs}.
+
+For the time being, @code{tramp-syntax} can have the following values:
+
address@hidden @w{}
address@hidden emacs
address@hidden @code{ftp} -- That is the default syntax
address@hidden @code{url} -- URL-like syntax
address@hidden ifset
address@hidden xemacs
address@hidden @code{sep} -- That is the default syntax
address@hidden @code{url} -- URL-like syntax
address@hidden @code{ftp} -- EFS-like syntax
address@hidden ifset
address@hidden itemize
+
+
address@hidden Filename completion
address@hidden Filename completion
address@hidden filename completion
+
+Filename completion works with @value{tramp} for completion of method
+names, of user names and of machine names as well as for completion of
+file names on remote machines.
address@hidden emacs
+In order to enable this, Partial Completion mode must be set
address@hidden you don't use Partial Completion mode, but want to
+keep full completion, load @value{tramp} like this in your
address@hidden:
+
address@hidden
+;; Preserve Tramp's completion features.
+(let ((partial-completion-mode t))
+ (require 'tramp))
address@hidden lisp
+}.
address@hidden
address@hidden Options, , , @value{emacsdir}}.
address@hidden ifinfo
address@hidden ifset
+
+If you, for example, type @kbd{C-x C-f @value{prefix}t
address@hidden, @value{tramp} might give you as result the choice for
+
address@hidden
address@hidden emacs
address@hidden@value{postfixhop} tmp/
address@hidden@value{postfix}
address@hidden ifset
address@hidden xemacs
address@hidden@value{postfixhop} @address@hidden
address@hidden ifset
address@hidden example
+
address@hidden@address@hidden
+is a possible completion for the respective method,
address@hidden emacs
address@hidden/} stands for the directory @file{/tmp} on your local
+machine,
address@hidden ifset
+and @address@hidden@value{postfix}}
+might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts}
+file (given you're using default method @option{ssh}).
+
+If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to
address@hidden@address@hidden
+Next @address@hidden brings you all machine names @value{tramp} detects in
+your @file{/etc/hosts} file, let's say
+
address@hidden
address@hidden, , 127.0.0.1,} @trampfn{telnet, , 192.168.0.1,}
address@hidden, , localhost,} @trampfn{telnet, ,
melancholia.danann.net,}
address@hidden, , melancholia,}
address@hidden example
+
+Now you can choose the desired machine, and you can continue to
+complete file names on that machine.
+
+If the configuration files (@pxref{Customizing Completion}), which
address@hidden 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.
+
+Once the remote machine identification is completed, it comes to
+filename completion on the remote host. This works pretty much like
+for files on the local host, with the exception that minibuffer
+killing via a double-slash works only on the filename part, except
+that filename part starts with @file{//}.
address@hidden
address@hidden File, , , @value{emacsdir}}.
address@hidden ifinfo
+
address@hidden emacs
+As example, @address@hidden, , melancholia, /usr/local/bin//etc}
address@hidden would result in
address@hidden@trampfn{telnet, , melancholia, /etc}}, whereas
address@hidden@trampfn{telnet, , melancholia, //etc} @key{TAB}} reduces the
+minibuffer contents to @file{/etc}. A triple-slash stands for the
+default behaviour,
+i.e. @address@hidden, , melancholia, /usr/local/bin///etc}
address@hidden expands directly to @file{/etc}.
address@hidden ifset
+
address@hidden xemacs
+As example, @address@hidden, , melancholia, /usr/local/bin//}}
+would result in @address@hidden, , melancholia, /}}, whereas
address@hidden@trampfn{telnet, , melancholia, //}} expands the minibuffer
+contents to @file{/}.
address@hidden ifset
+
+
address@hidden Remote processes
address@hidden Integration with other @value{emacsname} packages.
address@hidden compile
address@hidden recompile
+
address@hidden supports running processes on a remote host. This
+allows to exploit @value{emacsname} packages without modification for
+remote file names. It does not work for the @option{ftp} and
address@hidden methods.
+
+Remote processes are started when a corresponding command is executed
+from a buffer belonging to a remote file or directory. Up to now, the
+packages @file{compile.el} (commands like @code{compile} and
address@hidden) and @file{gud.el} (@code{gdb} or @code{perldb}) have been
+integrated. Integration of further packages is planned, any help for
+this is welcome!
+
+When your program is not found in the default search path
address@hidden sets on the remote machine, you should either use an
+absolute path, or extend @code{tramp-remote-path} (see @ref{Remote
+Programs}):
+
address@hidden
+(add-to-list 'tramp-remote-path "~/bin")
+(add-to-list 'tramp-remote-path "/appli/pub/bin")
address@hidden lisp
+
+The environment for your program can be adapted by customizing
address@hidden This variable is a list of
+strings. It is structured like @code{process-environment}. Each
+element is a string of the form ENVVARNAME=VALUE. An entry
+ENVVARNAME= disables the corresponding environment variable, which
+might have been set in your init file like @file{~/.profile}.
+
address@hidden
+Adding an entry can be performed via @code{add-to-list}:
+
address@hidden
+(add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")
address@hidden lisp
+
+Changing or removing an existing entry is not encouraged. The default
+values are chosen for proper @value{tramp} work. Nevertheless, if for
+example a paranoid system administrator disallows changing the
address@hidden environment variable, you can customize
address@hidden, or you can apply the
+following code in your @file{.emacs}:
+
address@hidden
+(let ((process-environment tramp-remote-process-environment))
+ (setenv "HISTORY" nil)
+ (setq tramp-remote-process-environment process-environment))
address@hidden lisp
+
+If you use other @value{emacsname} packages which do not run
+out-of-the-box on a remote host, please let us know. We will try to
+integrate them as well. @xref{Bug Reports}.
+
+
address@hidden Running eshell on a remote host
address@hidden eshell
+
address@hidden 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:
+
address@hidden
address@hidden $} cd @trampfn{sudo, , , /etc} @key{RET}
address@hidden@trampfn{sudo, root, host, /etc} $} hostname @key{RET}
+host
address@hidden@trampfn{sudo, root, host, /etc} $} id @key{RET}
+uid=0(root) gid=0(root) groups=0(root)
address@hidden@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET}
+#<buffer shadow>
address@hidden@trampfn{sudo, root, host, /etc} $}
address@hidden example
+
+
address@hidden a debugger on a remote host}
address@hidden Running a debugger on a remote host
address@hidden gud
address@hidden gdb
address@hidden perldb
+
address@hidden offers an unified interface to several symbolic
+debuggers
address@hidden emacs
address@hidden
+(@ref{Debuggers, , , @value{emacsdir}}).
address@hidden ifinfo
address@hidden ifset
+With @value{tramp}, it is possible to debug programs on
+remote hosts. You can call @code{gdb} with a remote file name:
+
address@hidden
address@hidden gdb @key{RET}}
address@hidden gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host,
~/myprog} @key{RET}
address@hidden 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
address@hidden, , host, /home/user}, you could call
+
address@hidden
address@hidden perldb @key{RET}}
address@hidden perldb (like this):} perl -d myprog.pl @key{RET}
address@hidden example
+
+It is not possible to use just the absolute local part of a remote
+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.
+
+
address@hidden Bug Reports
address@hidden Reporting Bugs and Problems
address@hidden bug reports
+
+Bugs and problems with @value{tramp} are actively worked on by the
+development team. Feature requests and suggestions are also more than
+welcome.
+
+The @value{tramp} mailing list is a great place to get information on
+working with @value{tramp}, solving problems and general discussion
+and advice on topics relating to the package. It is moderated so
+non-subscribers can post but messages will be delayed, possibly up to
+48 hours (or longer in case of holidays), until the moderator approves
+your message.
+
+The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to
+this address go to all the subscribers. This is @emph{not} the address
+to send subscription requests to.
+
+Subscribing to the list is performed via
address@hidden://lists.gnu.org/mailman/listinfo/tramp-devel/,
+the @value{tramp} Mail Subscription Page}.
+
+To report a bug in @value{tramp}, you should execute @kbd{M-x
+tramp-bug}. This will automatically generate a buffer with the details
+of your system and @value{tramp} version.
+
+When submitting a bug report, please try to describe in excruciating
+detail the steps required to reproduce the problem, the setup of the
+remote machine and any special conditions that exist. You should also
+check that your problem is not described already in @xref{Frequently
+Asked Questions}.
+
+If you can identify a minimal test case that reproduces the problem,
+include that with your bug report. This will make it much easier for
+the development team to analyze and correct the problem.
+
+Before reporting the bug, you should set the verbosity level to 6
+(@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and
+repeat the bug. Then, include the contents of the @file{*tramp/foo*}
+and @file{*debug tramp/foo*} buffers in your bug report. A verbosity
+level greater than 6 will produce a very huge debug buffer, which is
+mostly not necessary for the analysis.
+
+Please be aware that, with a verbosity level of 6 or greater, the
+contents of files and directories will be included in the debug
+buffer. Passwords you've typed will never be included there.
+
+
address@hidden Frequently Asked Questions
address@hidden Frequently Asked Questions
address@hidden frequently asked questions
address@hidden FAQ
+
address@hidden @bullet
address@hidden
+Where can I get the latest @value{tramp}?
+
address@hidden is available under the URL below.
+
address@hidden
address@hidden://ftp.gnu.org/gnu/tramp/}
+
address@hidden
+There is also a Savannah project page.
+
address@hidden
address@hidden://savannah.gnu.org/projects/tramp/}
+
+
address@hidden
+Which systems does it work on?
+
+The package has been used successfully on GNU Emacs 21, GNU Emacs 22
+and XEmacs 21 (starting with 21.4). Gateway methods are supported for
+GNU Emacs 22 only.
+
+The package was intended to work on Unix, and it really expects a
+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 NT/2000/XP @value{emacsname}.
+
+There is some informations on @value{tramp} on NT at the following URL;
+many thanks to Joe Stoy for providing the information:
address@hidden://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/}
+
address@hidden The link is broken. I've contacted Tom for clarification.
Michael.
address@hidden
+The above mostly contains patches to old ssh versions; Tom Roche has a
+Web page with instructions:
address@hidden://www4.ncsu.edu/~tlroche/plinkTramp.html}
address@hidden ignore
+
address@hidden
+How could I speed up @value{tramp}?
+
+In the backstage, @value{tramp} needs a lot of operations on the
+remote host. The time for transferring data from and to the remote
+host as well as the time needed to perform the operations there count.
+In order to speed up @value{tramp}, one could either try to avoid some
+of the operations, or one could try to improve their performance.
+
+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. The
+information about remote hosts is kept in the file specified in
address@hidden Keep this file.
+
+Disable version control. If you access remote files which are not
+under version control, a lot of check operations can be avoided by
+disabling VC. This can be achieved by
+
address@hidden
+(setq vc-handled-backends nil)
address@hidden lisp
+
+Disable excessive traces. The default trace level of @value{tramp},
+defined in the variable @code{tramp-verbose}, is 3. You should
+increase this level only temporarily, hunting bugs.
+
+
address@hidden
address@hidden does not connect to the remote host
+
+When @value{tramp} does not connect to the remote host, there are two
+reasons heading the bug mailing list:
+
address@hidden @minus
+
address@hidden
+Unknown characters in the prompt
+
address@hidden needs to recognize the prompt on the remote machine
+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.
+
+You can check your settings after an unsuccessful connection by
+switching to the @value{tramp} connection buffer @file{*tramp/foo*},
+setting the cursor at the top of the buffer, and applying the expression
+
address@hidden
address@hidden: (re-search-forward (concat tramp-shell-prompt-pattern "$"))}
address@hidden example
+
+If it fails, or the cursor is not moved at the end of the buffer, your
+prompt is not recognised correctly.
+
+A special problem is the zsh, which uses left-hand side and right-hand
+side prompts in parallel. Therefore, it is necessary to disable the
+zsh line editor on the remote host. You shall add to @file{~/.zshrc}
+the following command:
+
address@hidden
+[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
address@hidden example
+
+
address@hidden
address@hidden doesn't transfer strings with more than 500 characters
+correctly
+
+On some few systems, the implementation of @code{process-send-string}
+seems to be broken for longer strings. It is reported for HP-UX,
+FreeBSD and Tru64 Unix, for example. This case, you should customize
+the variable @code{tramp-chunksize} to 500. For a description how to
+determine whether this is necessary see the documentation of
address@hidden
+
+Additionally, it will be useful to set @code{file-precious-flag} to
address@hidden for @value{tramp} files. Then the file contents will be
+written into a temporary file first, which is checked for correct
+checksum.
address@hidden
address@hidden Buffers, , , elisp}
address@hidden ifinfo
+
address@hidden
+(add-hook
+ 'find-file-hooks
+ '(lambda ()
+ (when (file-remote-p default-directory)
+ (set (make-local-variable 'file-precious-flag) t))))
address@hidden lisp
+
address@hidden itemize
+
+
address@hidden
+File name completion does not work with @value{tramp}
+
+When you log in to the remote machine, do you see the output of
address@hidden in color? If so, this may be the cause of your problems.
+
address@hidden outputs @acronym{ANSI} escape sequences that your terminal
+emulator interprets to set the colors. These escape sequences will
+confuse @value{tramp} however.
+
+In your @file{.bashrc}, @file{.profile} or equivalent on the remote
+machine you probably have an alias configured that adds the option
address@hidden or @option{--color=auto}.
+
+You should remove that alias and ensure that a new login @emph{does not}
+display the output of @command{ls} in color. If you still cannot use
+filename completion, report a bug to the @value{tramp} developers.
+
+
address@hidden
+File name completion does not work in large directories
+
address@hidden uses globbing for some operations. (Globbing means to use the
+shell to expand wildcards such as `*.c'.) This might create long
+command lines, especially in directories with many files. Some shells
+choke on long command lines, or don't cope well with the globbing
+itself.
+
+If you have a large directory on the remote end, you may wish to execute
+a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs.
+Note that you must first start the right shell, which might be
address@hidden/bin/sh}, @command{ksh} or @command{bash}, depending on which
+of those supports tilde expansion.
+
+
address@hidden
+How can I get notified when @value{tramp} file transfers are complete?
+
+The following snippet can be put in your @file{~/.emacs} file. It
+makes @value{emacsname} beep after reading from or writing to the
+remote host.
+
address@hidden
+(defadvice tramp-handle-write-region
+ (after tramp-write-beep-advice activate)
+ " make tramp beep after writing a file."
+ (interactive)
+ (beep))
+
+(defadvice tramp-handle-do-copy-or-rename-file
+ (after tramp-copy-beep-advice activate)
+ " make tramp beep after copying a file."
+ (interactive)
+ (beep))
+
+(defadvice tramp-handle-insert-file-contents
+ (after tramp-copy-beep-advice activate)
+ " make tramp beep after copying a file."
+ (interactive)
+ (beep))
address@hidden lisp
+
+
address@hidden emacs
address@hidden
+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.1. You
+should put it into your @file{~/.emacs}:
+
address@hidden
+(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)))
address@hidden lisp
+
+Since @value{emacsname} 23.1, the mode line contains an indication if
address@hidden 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:
+
address@hidden
+ '(: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)))
address@hidden lisp
address@hidden ifset
+
+
address@hidden emacs
address@hidden
+My remote host does not understand default directory listing options
+
address@hidden computes the @command{dired} options depending on
+the local host you are working. If your @command{ls} command on the
+remote host does not understand those options, you can change them
+like this:
+
address@hidden
+(add-hook
+ 'dired-before-readin-hook
+ '(lambda ()
+ (when (file-remote-p default-directory)
+ (setq dired-actual-switches "-al"))))
address@hidden lisp
address@hidden ifset
+
+
address@hidden
+There's this @file{~/.sh_history} file on the remote host which keeps
+growing and growing. What's that?
+
+Sometimes, @value{tramp} starts @command{ksh} on the remote host for
+tilde expansion. Maybe @command{ksh} saves the history by default.
address@hidden tries to turn off saving the history, but maybe you have
+to help. For example, you could put this in your @file{.kshrc}:
+
address@hidden
+if [ -f $HOME/.sh_history ] ; then
+ /bin/rm $HOME/.sh_history
+fi
+if [ "address@hidden@}" != "unset" ] ; then
+ unset HISTFILE
+fi
+if [ "address@hidden@}" != "unset" ] ; then
+ unset HISTSIZE
+fi
address@hidden example
+
+
address@hidden There are longish file names to type. How to shorten this?
+
+Let's say you need regularly access to @address@hidden, news,
+news.my.domain, /opt/news/etc}}, which is boring to type again and
+again. The following approaches can be mixed:
+
address@hidden
+
address@hidden Use default values for method and user name:
+
+You can define default methods and user names for hosts,
+(@pxref{Default Method}, @pxref{Default User}):
+
address@hidden
+(setq tramp-default-method "ssh"
+ tramp-default-user "news")
address@hidden lisp
+
+The file name left to type would be
address@hidden 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
address@hidden, , ,}}.
+
address@hidden Use configuration possibilities of your method:
+
+Several connection methods (i.e. the programs used) offer powerful
+configuration possibilities (@pxref{Customizing Completion}). In the
+given case, this could be @file{~/.ssh/config}:
+
address@hidden
+Host xy
+ HostName news.my.domain
+ User news
address@hidden example
+
+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
address@hidden@value{postfixhop}x @key{TAB}}.
+
address@hidden Use environment variables:
+
+File names typed in the minibuffer can be expanded by environment
+variables. You can set them outside @value{emacsname}, or even with
+Lisp:
+
address@hidden
+(setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")
address@hidden 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
+environment variables are not expanded during editing in the
+minibuffer.
+
address@hidden Define own keys:
+
+You can define your own key sequences in @value{emacsname}, which can
+be used instead of @kbd{C-x C-f}:
+
address@hidden
+(global-set-key
+ [(control x) (control y)]
+ (lambda ()
+ (interactive)
+ (find-file
+ (read-file-name
+ "Find Tramp file: "
+ "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))))
address@hidden lisp
+
+Simply typing @kbd{C-x C-y} would initialize the minibuffer for
+editing with your beloved file name.
+
+See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the
+Emacs Wiki} for a more comprehensive example.
+
address@hidden Define own abbreviation (1):
+
+It is possible to define an own abbreviation list for expanding file
+names:
+
address@hidden
+(add-to-list
+ 'directory-abbrev-alist
+ '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
address@hidden lisp
+
+This shortens the file openening command to @kbd{C-x C-f /xy
address@hidden The disadvantage is, again, that you cannot edit the file
+name, because the expansion happens after entering the file name only.
+
address@hidden Define own abbreviation (2):
+
+The @code{abbrev-mode} gives more flexibility for editing the
+minibuffer:
+
address@hidden
+(define-abbrev-table 'my-tramp-abbrev-table
+ '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))
+
+(add-hook
+ 'minibuffer-setup-hook
+ '(lambda ()
+ (abbrev-mode 1)
+ (setq local-abbrev-table my-tramp-abbrev-table)))
+
+(defadvice minibuffer-complete
+ (before my-minibuffer-complete activate)
+ (expand-abbrev))
+
+;; If you use partial-completion-mode
+(defadvice PC-do-completion
+ (before my-PC-do-completion activate)
+ (expand-abbrev))
address@hidden lisp
+
+After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is
+expanded, and you can continue editing.
+
address@hidden Use bookmarks:
+
+Bookmarks can be used to visit Tramp files or directories.
address@hidden
address@hidden, , , @value{emacsdir}}
address@hidden ifinfo
+
+When you have opened @address@hidden, news, news.my.domain,
+/opt/news/etc/}}, you should save the bookmark via
address@hidden emacs
address@hidden@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}.
address@hidden ifset
address@hidden xemacs
address@hidden@key{menu-bar} @key{view} @key{bookmarks} @key{set}}.
address@hidden ifset
+
+Later on, you can always navigate to that bookmark via
address@hidden emacs
address@hidden@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}.
address@hidden ifset
address@hidden xemacs
address@hidden@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}.
address@hidden ifset
+
address@hidden Use recent files:
+
address@hidden emacs
address@hidden
address@hidden ifset
address@hidden xemacs
address@hidden
address@hidden ifset
+remembers visited places.
address@hidden
address@hidden emacs
address@hidden Conveniences, , , @value{emacsdir}}
address@hidden ifset
address@hidden xemacs
address@hidden, , , edit-utils}
address@hidden ifset
address@hidden ifinfo
+
+You could keep remote file names in the recent list without checking
+their readability through a remote access:
+
address@hidden
address@hidden emacs
+(recentf-mode 1)
address@hidden ifset
address@hidden xemacs
+(recent-files-initialize)
+(add-hook
+ 'find-file-hooks
+ (lambda ()
+ (when (file-remote-p (buffer-file-name))
+ (recent-files-make-permanent)))
+ 'append)
address@hidden ifset
address@hidden lisp
+
+The list of files opened recently is reachable via
address@hidden emacs
address@hidden@key{menu-bar} @key{file} @key{Open Recent}}.
address@hidden ifset
address@hidden xemacs
address@hidden@key{menu-bar} @key{Recent Files}}.
address@hidden ifset
+
address@hidden emacs
address@hidden Use filecache:
+
address@hidden remembers visited places. Add the directory into
+the cache:
+
address@hidden
+(eval-after-load "filecache"
+ '(file-cache-add-directory
+ "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
address@hidden lisp
+
+Whenever you want to load a file, you can enter @kbd{C-x C-f
address@hidden in the minibuffer. The completion is done for the given
+directory.
address@hidden ifset
+
address@hidden emacs
address@hidden Use bbdb:
+
address@hidden has a built-in feature for @value{ftppackagename} files,
+which works also for @value{tramp}.
address@hidden
address@hidden, Storing FTP sites in the BBDB, , bbdb}
address@hidden ifinfo
+
+You need to load @file{bbdb}:
+
address@hidden
+(require 'bbdb)
+(bbdb-initialize)
address@hidden 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:
+
address@hidden
address@hidden bbdb-create-ftp-site @key{RET}}
address@hidden Site:} news.my.domain @key{RET}
address@hidden Directory:} /opt/news/etc/ @key{RET}
address@hidden Username:} address@hidden @key{RET}
address@hidden:} @key{RET}
address@hidden Comments:} @key{RET}
address@hidden example
+
+When you have opened your BBDB buffer, you can access such an entry by
+pressing the key @key{F}.
address@hidden ifset
+
address@hidden enumerate
+
+I would like to thank all @value{tramp} users, who have contributed to
+the different recipes!
+
+
address@hidden
+How can I disable @value{tramp}?
+
+Shame on you, why did you read until now?
+
address@hidden emacs
+If you just want to have @value{ftppackagename} as default remote
+files access package, you should apply the following code:
+
address@hidden
+(setq tramp-default-method "ftp")
address@hidden lisp
address@hidden ifset
+
+Unloading @value{tramp} can be achieved by applying @kbd{M-x
+tramp-unload-tramp}.
address@hidden emacs
+This resets also the @value{ftppackagename} plugins.
address@hidden ifset
address@hidden itemize
+
+
address@hidden For the developer
address@hidden Version Control
address@hidden The inner workings of remote version control
address@hidden Version Control
+
+Unlike @value{ftppackagename}, @value{tramp} has full shell access to the
+remote machine. This makes it possible to provide version control for
+files accessed under @value{tramp}.
+
+The actual version control binaries must be installed on the remote
+machine, accessible in the directories specified in
address@hidden
+
+This transparent integration with the version control systems is one of
+the most valuable features provided by @value{tramp}, but it is far from
perfect.
+Work is ongoing to improve the transparency of the system.
+
address@hidden
+* Version Controlled Files:: Determining if a file is under version control.
+* Remote Commands:: Executing the version control commands on the
remote machine.
+* Changed workfiles:: Detecting if the working file has changed.
+* Checking out files:: Bringing the workfile out of the repository.
+* Miscellaneous Version Control:: Things related to Version Control that
don't fit elsewhere.
address@hidden menu
+
+
address@hidden Version Controlled Files
address@hidden Determining if a file is under version control
+
+The VC package uses the existence of on-disk revision control master
+files to determine if a given file is under revision control. These file
+tests happen on the remote machine through the standard @value{tramp}
mechanisms.
+
+
address@hidden Remote Commands
address@hidden Executing the version control commands on the remote machine
+
+There are no hooks provided by VC to allow intercepting of the version
+control command execution. The calls occur through the
address@hidden mechanism, a function that is somewhat more
+efficient than the @code{shell-command} function but that does not
+provide hooks for remote execution of commands.
+
+To work around this, the functions @code{vc-do-command} and
address@hidden have been advised to intercept requests for
+operations on files accessed via @value{tramp}.
+
+In the case of a remote file, the @code{shell-command} interface is
+used, with some wrapper code, to provide the same functionality on the
+remote machine as would be seen on the local machine.
+
+
address@hidden Changed workfiles
address@hidden Detecting if the working file has changed
+
+As there is currently no way to get access to the mtime of a file on a
+remote machine in a portable way, the @code{vc-workfile-unchanged-p}
+function is advised to call an @value{tramp} specific function for remote
files.
+
+The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC
+diff functionality to determine if any changes have occurred between the
+workfile and the version control master.
+
+This requires that a shell command be executed remotely, a process that
+is notably heavier-weight than the mtime comparison used for local
+files. Unfortunately, unless a portable solution to the issue is found,
+this will remain the cost of remote version control.
+
+
address@hidden Checking out files
address@hidden Bringing the workfile out of the repository
+
+VC will, by default, check for remote files and refuse to act on them
+when checking out files from the repository. To work around this
+problem, the function @code{vc-checkout} knows about @value{tramp} files and
+allows version control to occur.
+
+
address@hidden Miscellaneous Version Control
address@hidden Things related to Version Control that don't fit elsewhere
+
+Minor implementation details, &c.
+
address@hidden
+* Remote File Ownership:: How VC determines who owns a workfile.
+* Back-end Versions:: How VC determines what release your RCS is.
address@hidden menu
+
+
address@hidden Remote File Ownership
address@hidden How VC determines who owns a workfile
+
address@hidden provides the @code{user-login-name} function to
+return the login name of the current user as well as mapping from
+arbitrary user id values back to login names. The VC code uses this
+functionality to map from the uid of the owner of a workfile to the
+login name in some circumstances.
+
+This will not, for obvious reasons, work if the remote system has a
+different set of logins. As such, it is necessary to delegate to the
+remote machine the job of determining the login name associated with a
+uid.
+
+Unfortunately, with the profusion of distributed management systems such
+as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple,
+reliable and portable method for performing this mapping.
+
+Thankfully, the only place in the VC code that depends on the mapping of
+a uid to a login name is the @code{vc-file-owner} function. This returns
+the login of the owner of the file as a string.
+
+This function has been advised to use the output of @command{ls} on the
+remote machine to determine the login name, delegating the problem of
+mapping the uid to the login to the remote system which should know more
+about it than I do.
+
+
address@hidden Back-end Versions
address@hidden How VC determines what release your RCS is
+
+VC needs to know what release your revision control binaries you are
+running as not all features VC supports are available with older
+versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}.
+
+The default implementation of VC determines this value the first time it
+is needed and then stores the value globally to avoid the overhead of
+executing a process and parsing its output each time the information is
+needed.
+
+Unfortunately, life is not quite so easy when remote version control
+comes into the picture. Each remote machine may have a different version
+of the version control tools and, while this is painful, we need to
+ensure that unavailable features are not used remotely.
+
+To resolve this issue, @value{tramp} currently takes the sledgehammer
+approach of making the release values of the revision control tools
+local to each @value{tramp} buffer, forcing VC to determine these values
+again each time a new file is visited.
+
+This has, quite obviously, some performance implications. Thankfully,
+most of the common operations performed by VC do not actually require
+that the remote version be known. This makes the problem far less
+apparent.
+
+Eventually these values will be captured by @value{tramp} on a system by
+system basis and the results cached to improve performance.
+
+
address@hidden Files directories and localnames
address@hidden How file names, directories and localnames are mangled and
managed.
+
address@hidden
+* Localname deconstruction:: Breaking a localname into its components.
address@hidden menu
+
+
address@hidden Localname deconstruction
address@hidden Breaking a localname into its components.
+
address@hidden file names are somewhat different, obviously, to ordinary file
+names. As such, the lisp functions @code{file-name-directory} and
address@hidden are overridden within the @value{tramp}
+package.
+
+Their replacements are reasonably simplistic in their approach. They
+dissect the filename, call the original handler on the localname and
+then rebuild the @value{tramp} file name with the result.
+
+This allows the platform specific hacks in the original handlers to take
+effect while preserving the @value{tramp} file name information.
+
+
address@hidden Traces and Profiles
address@hidden How to Customize Traces
+
+All @value{tramp} messages are raised with a verbosity level. The
+verbosity level can be any number between 0 and 10. Only messages with
+a verbosity level less than or equal to @code{tramp-verbose} are
+displayed.
+
+The verbosity levels are
+
+ @w{ 0} silent (no @value{tramp} messages at all)
address@hidden@indent @w{ 1} errors
address@hidden@indent @w{ 2} warnings
address@hidden@indent @w{ 3} connection to remote hosts (default verbosity)
address@hidden@indent @w{ 4} activities
address@hidden@indent @w{ 5} internal
address@hidden@indent @w{ 6} sent and received strings
address@hidden@indent @w{ 7} file caching
address@hidden@indent @w{ 8} connection properties
address@hidden@indent @w{10} traces (huge)
+
+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
+should be done with @code{tramp-verbose} set to a verbosity level of at
+least 6 (@pxref{Bug Reports}).
+
+The debug buffer is in
address@hidden
address@hidden Mode, , , @value{emacsdir}}.
address@hidden ifinfo
address@hidden
+Outline Mode.
address@hidden ifnotinfo
+That means, you can change the level of messages to be viewed. If you
+want, for example, see only messages up to verbosity level 5, you must
+enter @kbd{C-u 6 C-c C-q}.
address@hidden
+Other keys for navigating are described in
address@hidden Visibility, , , @value{emacsdir}}.
address@hidden ifinfo
+
address@hidden errors are handled internally in order to raise the
+verbosity level 1 messages. When you want to get a Lisp backtrace in
+case of an error, you need to set both
+
address@hidden
+(setq debug-on-error t
+ debug-on-signal t)
address@hidden lisp
+
+Sometimes, it might be even necessary to step through @value{tramp}
+function call traces. Such traces are enabled by the following code:
+
address@hidden
+(require 'tramp)
+(require 'trace)
+(mapcar 'trace-function-background
+ (mapcar 'intern
+ (all-completions "tramp-" obarray 'functionp)))
+(untrace-function 'tramp-read-passwd)
+(untrace-function 'tramp-gw-basic-authentication)
address@hidden lisp
+
+The function call traces are inserted in the buffer
address@hidden @code{tramp-read-passwd} and
address@hidden shall be disabled when the
+function call traces are added to @value{tramp}, because both
+functions return password strings, which should not be distributed.
+
+
address@hidden Issues
address@hidden Debatable Issues and What Was Decided
+
address@hidden @bullet
address@hidden The uuencode method does not always work.
+
+Due to the design of @value{tramp}, the encoding and decoding programs
+need to read from stdin and write to stdout. On some systems,
address@hidden -o -} will read stdin and write the decoded file to
+stdout, on other systems @command{uudecode -p} does the same thing.
+But some systems have uudecode implementations which cannot do this at
+all---it is not possible to call these uudecode implementations with
+suitable parameters so that they write to stdout.
+
+Of course, this could be circumvented: the @code{begin foo 644} line
+could be rewritten to put in some temporary file name, then
address@hidden could be called, then the temp file could be
+printed and deleted.
+
+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.
+
address@hidden The @value{tramp} filename syntax differs between GNU Emacs and
XEmacs.
+
+The GNU 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.
+
+For the XEmacs maintainers, the problems caused from using a unified
+filename syntax are greater than the gains. The XEmacs package system
+uses EFS for downloading new packages. So, obviously, EFS has to be
+installed from the start. If the filenames were unified, @value{tramp}
+would have to be installed from the start, too.
+
address@hidden xemacs
address@hidden:} If you'd like to use a similar syntax like
address@hidden, you need the following settings in your init
+file:
+
address@hidden
+(setq tramp-unified-filenames t)
+(require 'tramp)
address@hidden lisp
+
+The autoload of the @value{emacsname} @value{tramp} package must be
+disabled. This can be achieved by setting file permissions @code{000}
+to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}.
+
+In case of unified filenames, all @value{emacsname} download sites are
+added to @code{tramp-default-method-alist} with default method
address@hidden @xref{Default Method}. These settings shouldn't be
+touched for proper working of the @value{emacsname} package system.
+
+The syntax for unified filenames is described in the @value{tramp} manual
+for @value{emacsothername}.
address@hidden ifset
address@hidden itemize
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden doclicense.texi
+
address@hidden Concept Index
address@hidden node-name, next, previous, up
address@hidden Concept Index
address@hidden cp
address@hidden
address@hidden End of tramp.texi - the TRAMP User Manual
address@hidden
+
address@hidden TODO
address@hidden
address@hidden * Say something about the .login and .profile files of the remote
address@hidden shells.
address@hidden * Explain how tramp.el works in principle: open a shell on a
remote
address@hidden host and then send commands to it.
address@hidden * Make terminology "inline" vs "out-of-band" consistent.
address@hidden It seems that "external" is also used instead of "out-of-band".
+
address@hidden * M. Albinus
address@hidden ** Use `filename' resp. `file name' consistently.
address@hidden ** Use `host' resp. `machine' consistently.
address@hidden ** Consistent small or capitalized words especially in menues.
+
address@hidden
+ arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808
address@hidden ignore