mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-26 10:49:33 +00:00
2421 lines
90 KiB
Plaintext
2421 lines
90 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename ../info/tramp
|
|
@settitle TRAMP User Manual
|
|
@setchapternewpage odd
|
|
@c %**end of header
|
|
|
|
@c This is *so* much nicer :)
|
|
@footnotestyle end
|
|
|
|
@c In the Tramp CVS, the version number is auto-frobbed from
|
|
@c configure.ac, so you should edit that file and run
|
|
@c "autoconf && ./configure" to change the version number.
|
|
|
|
@c Additionally, flags are set with respect to the Emacs flavor; and
|
|
@c depending whether Tramp is packaged into (X)Emacs, or standalone.
|
|
|
|
@include trampver.texi
|
|
|
|
@c Macros for formatting a filename.
|
|
@c trampfn is for a full filename, trampfnmhp means method, host, localname
|
|
@c were given, and so on.
|
|
@macro trampfn(method, user, host, localname)
|
|
@value{prefix}@value{method}@value{user}@@@value{host}@value{postfix}@value{localname}
|
|
@end macro
|
|
|
|
@copying
|
|
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
|
|
Free Software Foundation, Inc.
|
|
|
|
@quotation
|
|
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.
|
|
@end quotation
|
|
@end copying
|
|
|
|
@c Entries for @command{install-info} to use
|
|
@dircategory @value{emacsname}
|
|
@direntry
|
|
* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
|
|
@value{emacsname} remote file access via rsh and rcp.
|
|
@end direntry
|
|
|
|
@tex
|
|
|
|
@titlepage
|
|
@title @value{tramp} version @value{trampver} User Manual
|
|
|
|
@author by Daniel Pittman
|
|
@author based on documentation by Kai Gro@ss{}johann
|
|
|
|
@page
|
|
@insertcopying
|
|
|
|
@end titlepage
|
|
@page
|
|
|
|
@end tex
|
|
|
|
@ifnottex
|
|
@node Top, Overview, (dir), (dir)
|
|
@top @value{tramp} version @value{trampver} User Manual
|
|
|
|
This file documents @value{tramp} version @value{trampver}, a remote file
|
|
editing package for @value{emacsname}.
|
|
|
|
@value{tramp} stands for `Transparent Remote (file) Access, Multiple
|
|
Protocol'. This package provides remote file editing, similar to
|
|
@value{ftppackagename}.
|
|
|
|
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
|
|
@uref{http://www.gnu.org/software/tramp/}.
|
|
|
|
@c Pointer to the other Emacs flavor is necessary only in case of
|
|
@c standalone installation.
|
|
@ifset installchapter
|
|
The manual has been generated for @value{emacsname}.
|
|
@ifinfo
|
|
If you want to read the info pages for @value{emacsothername}, you
|
|
should read in @ref{Installation} how to create them.
|
|
@end ifinfo
|
|
@ifhtml
|
|
If you're using the other Emacs flavor, you should read the
|
|
@uref{@value{emacsotherfilename}, @value{emacsothername}} pages.
|
|
@end ifhtml
|
|
@end ifset
|
|
|
|
@ifhtml
|
|
@ifset jamanual
|
|
This manual is also available as a @uref{@value{japanesemanual},
|
|
Japanese translation}.
|
|
@end ifset
|
|
|
|
The latest release of @value{tramp} is available for
|
|
@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
|
|
@ref{Obtaining Tramp} for more details, including the CVS server
|
|
details.
|
|
|
|
@value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/,
|
|
Savannah Project Page}.
|
|
@end ifhtml
|
|
|
|
There is a mailing list for @value{tramp}, available at
|
|
@email{tramp-devel@@gnu.org}, and archived at
|
|
@uref{http://lists.gnu.org/archive/html/tramp-devel/, the
|
|
@value{tramp} Mail Archive}.
|
|
@ifhtml
|
|
Older archives are located at
|
|
@uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel,
|
|
SourceForge Mail Archive} and
|
|
@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/,
|
|
The Mail Archive}.
|
|
@c in HTML output, there's no new paragraph.
|
|
@*@*
|
|
@end ifhtml
|
|
|
|
@insertcopying
|
|
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Overview:: What @value{tramp} can and cannot do.
|
|
|
|
For the end user:
|
|
|
|
* Obtaining Tramp:: How to obtain @value{tramp}.
|
|
* History:: History of @value{tramp}.
|
|
@ifset installchapter
|
|
* Installation:: Installing @value{tramp} with your @value{emacsname}.
|
|
@end 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.
|
|
* Issues:: Debatable Issues and What Was Decided.
|
|
|
|
@detailmenu
|
|
--- The Detailed Node Listing ---
|
|
@c
|
|
@ifset 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.
|
|
|
|
@end 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.
|
|
* Multi-hop Methods:: Connecting to a remote host using multiple hops.
|
|
* Default Method:: Selecting a default method.
|
|
* Customizing Methods:: Using Non-Standard Methods.
|
|
* Customizing Completion:: Selecting config files for user/host name completion.
|
|
* Password caching:: Reusing passwords for several connections.
|
|
* 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.
|
|
* Multi-hop filename syntax:: Multi-hop filename conventions.
|
|
* Filename completion:: Filename completion.
|
|
* Dired:: Dired.
|
|
* Compilation:: Compile remote files.
|
|
|
|
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.
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@node Overview
|
|
@chapter An overview of @value{tramp}
|
|
@cindex 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},
|
|
@command{rlogin}, @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.
|
|
|
|
@value{tramp} 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
|
|
@command{rsync}.
|
|
|
|
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.
|
|
|
|
@value{tramp} is still under active development and any problems you encounter,
|
|
trivial or major, should be reported to the @value{tramp} developers.
|
|
@xref{Bug Reports}.
|
|
|
|
|
|
@subsubheading Behind the scenes
|
|
@cindex behind the scenes
|
|
@cindex details of operation
|
|
@cindex 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 @kbd{@key{TAB}} for completion. Suppose further that this is
|
|
the first time that @value{tramp} is invoked for the host in question. Here's
|
|
what happens:
|
|
|
|
@itemize
|
|
@item
|
|
@value{tramp} discovers that it needs a connection to the host. So it
|
|
invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
|
|
@var{user}} or a similar tool to connect to the remote host.
|
|
Communication with this process happens through an
|
|
@value{emacsname} buffer, that is, the output from the remote end
|
|
goes into a buffer.
|
|
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
The remote host may prompt for a password or pass phrase (for
|
|
@command{rsh} or for @command{telnet} after sending the login name).
|
|
@value{tramp} 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.
|
|
|
|
@item
|
|
@value{tramp} 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.
|
|
|
|
@item
|
|
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
|
|
syntaxes.@footnote{Invoking @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 @command{scsh}@dots{}}
|
|
|
|
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.
|
|
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
Suppose you are finished with filename completion, have entered @kbd{C-x
|
|
C-f}, a full file name and hit @kbd{@key{RET}}. 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:
|
|
@example
|
|
rcp user@@host:/path/to/remote/file /tmp/tramp.4711
|
|
@end example
|
|
It then reads the local temporary file @file{/tmp/tramp.4711} into a
|
|
buffer and deletes the temporary file.
|
|
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
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.
|
|
@end 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}.
|
|
|
|
|
|
@c For the end user
|
|
@node Obtaining Tramp
|
|
@chapter Obtaining Tramp.
|
|
@cindex obtaining Tramp
|
|
|
|
@value{tramp} is freely available on the Internet and the latest
|
|
release may be downloaded from
|
|
@uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
|
|
documentation and code for @value{tramp}, suitable for installation.
|
|
But GNU Emacs (22 or later) includes @value{tramp} already, and there
|
|
is a @value{tramp} package for XEmacs, as well. So maybe it is easier
|
|
to just use those. But if you want the bleeding edge, read
|
|
on@dots{...}
|
|
|
|
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.
|
|
|
|
@noindent
|
|
@uref{http://savannah.gnu.org/projects/tramp/}
|
|
|
|
@noindent
|
|
Or follow the example session below:
|
|
|
|
@example
|
|
] @strong{cd ~/@value{emacsdir}}
|
|
] @strong{export CVS_RSH="ssh"}
|
|
] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
|
|
@end example
|
|
|
|
@noindent
|
|
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:
|
|
|
|
@example
|
|
] @strong{cd ~/@value{emacsdir}/tramp}
|
|
] @strong{export CVS_RSH="ssh"}
|
|
] @strong{cvs update -d}
|
|
@end example
|
|
|
|
@noindent
|
|
Once you've got updated files from the CVS repository, you need to run
|
|
@command{autoconf} in order to get an up-to-date @file{configure}
|
|
script:
|
|
|
|
@example
|
|
] @strong{cd ~/@value{emacsdir}/tramp}
|
|
] @strong{autoconf}
|
|
@end example
|
|
|
|
|
|
@node History
|
|
@chapter History of @value{tramp}
|
|
@cindex history
|
|
@cindex development history
|
|
|
|
Development was started end of November 1998. The package was called
|
|
@file{rssh.el}, back then. It only provided one method to access a
|
|
file, using @command{ssh} to log in to a remote host and using
|
|
@command{scp} 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.
|
|
|
|
@c Installation chapter is necessary only in case of standalone
|
|
@c installation. Text taken from trampinst.texi.
|
|
@ifset installchapter
|
|
@include trampinst.texi
|
|
@end ifset
|
|
|
|
@node Configuration
|
|
@chapter Configuring @value{tramp} for use
|
|
@cindex configuration
|
|
|
|
@cindex default configuration
|
|
@value{tramp} is (normally) fully functional when it is initially installed.
|
|
It is initially configured to use the @command{ssh} program to connect
|
|
to the remote host and to use base64 or uu encoding to transfer the
|
|
files through that shell connection. So in the easiest case, you just
|
|
type @kbd{C-x C-f} and then enter the filename
|
|
@file{@value{prefix}@var{user}@@@var{machine}@value{postfix}@var{/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}.
|
|
|
|
|
|
@menu
|
|
* Connection types:: Types of connections made to remote machines.
|
|
* Inline methods:: Inline methods.
|
|
* External transfer methods:: External transfer methods.
|
|
* Multi-hop Methods:: Connecting to a remote host using multiple hops.
|
|
* 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.
|
|
* Customizing Methods:: Using Non-Standard Methods.
|
|
* Customizing Completion:: Selecting config files for user/host name completion.
|
|
* Password caching:: Reusing passwords for several connections.
|
|
* 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.
|
|
@end menu
|
|
|
|
|
|
@node Connection types
|
|
@section Types of connections made to remote machines.
|
|
@cindex 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
|
|
@command{telnet} 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.
|
|
|
|
@cindex inline methods
|
|
@cindex external transfer methods
|
|
@cindex external methods
|
|
@cindex out-of-band methods
|
|
@cindex methods, inline
|
|
@cindex methods, external transfer
|
|
@cindex 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
|
|
@command{rsync}. 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).
|
|
If it isn't possible, you should consider @ref{Password caching},
|
|
otherwise you will be prompted for a password every copy action.
|
|
|
|
@cindex multi-hop methods
|
|
@cindex methods, multi-hop
|
|
A variant of the inline methods are the @dfn{multi-hop methods}.
|
|
These methods allow you to connect a remote host using a number `hops',
|
|
each of which connects to a different host. This is useful if you are
|
|
in a secured network where you need to go through a bastion host to
|
|
connect to the outside world.
|
|
|
|
|
|
@node Inline methods
|
|
@section Inline methods
|
|
@cindex inline methods
|
|
@cindex 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.
|
|
|
|
@cindex uuencode
|
|
@cindex mimencode
|
|
@cindex base-64 encoding
|
|
@value{tramp} checks the availability and usability of commands like
|
|
@command{mimencode} (part of the @command{metamail} package) or
|
|
@command{uuencode} 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.
|
|
|
|
|
|
@table @asis
|
|
@item @option{rsh}
|
|
@cindex method rsh
|
|
@cindex 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.
|
|
|
|
|
|
@item @option{ssh}
|
|
@cindex method ssh
|
|
@cindex 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
|
|
@file{~/.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
|
|
@command{ssh1} 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.
|
|
|
|
|
|
@item @option{telnet}
|
|
@cindex method telnet
|
|
@cindex telnet method
|
|
|
|
Connect to the remote host with @command{telnet}. This is as unsecure
|
|
as the @option{rsh} method.
|
|
|
|
|
|
@item @option{su}
|
|
@cindex method su
|
|
@cindex 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.
|
|
|
|
|
|
@item @option{sudo}
|
|
@cindex method sudo
|
|
@cindex 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
|
|
@command{ls} and @command{mimencode} were allowed, but that is not
|
|
easy to implement, so I haven't got around to it, yet.
|
|
|
|
|
|
@item @option{sshx}
|
|
@cindex method sshx
|
|
@cindex 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
|
|
@var{user} /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
|
|
@command{ssh} 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.
|
|
|
|
|
|
@item @option{krlogin}
|
|
@cindex method krlogin
|
|
@cindex km krlogin
|
|
@cindex Kerberos (with krlogin method)
|
|
|
|
This method is also similar to @option{ssh}. It only uses the
|
|
@command{krlogin -x} command to log in to the remote host.
|
|
|
|
|
|
@item @option{plink}
|
|
@cindex method plink
|
|
@cindex 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.
|
|
|
|
Additionally, the method @option{plink1} is provided, which calls
|
|
@samp{plink -1 -ssh} in order to use SSH protocol version 1
|
|
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: Does @command{plink} support the @samp{-p} option? @value{tramp} will
|
|
support that, anyway.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node External transfer methods
|
|
@section External transfer methods
|
|
@cindex methods, external transfer
|
|
@cindex methods, out-of-band
|
|
@cindex external transfer methods
|
|
@cindex 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.
|
|
|
|
If you want to use an external transfer method you should be able to
|
|
execute the transfer utility to copy files to and from the remote
|
|
machine without any interaction.
|
|
|
|
@cindex ssh-agent
|
|
This means that you will need to use @command{ssh-agent} if you use the
|
|
@command{scp} program for transfers, or maybe your version of
|
|
@command{scp} accepts a password on the command line.@footnote{PuTTY's
|
|
@command{pscp} allows you to specify the password on the command line.}
|
|
If you use @command{rsync} via @command{ssh} then the same rule must
|
|
apply to that connection.
|
|
|
|
If you cannot get an external method to run without asking for a
|
|
password you should consider @ref{Password caching}.
|
|
|
|
|
|
@table @asis
|
|
@item @option{rcp} --- @command{rsh} and @command{rcp}
|
|
@cindex method rcp
|
|
@cindex rcp method
|
|
@cindex rcp (with rcp method)
|
|
@cindex 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
|
|
@command{rcp} commands. It should be applied on machines where
|
|
@command{remsh} is used instead of @command{rsh}.
|
|
|
|
|
|
@item @option{scp} --- @command{ssh} and @command{scp}
|
|
@cindex method scp
|
|
@cindex scp method
|
|
@cindex scp (with scp method)
|
|
@cindex 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
|
|
@file{~/.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
|
|
@command{ssh1} 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}.
|
|
|
|
|
|
@item @option{rsync} --- @command{ssh} and @command{rsync}
|
|
@cindex method rsync
|
|
@cindex rsync method
|
|
@cindex rsync (with rsync method)
|
|
@cindex 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
|
|
@command{rcp} 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.
|
|
|
|
|
|
@item @option{scpx} --- @command{ssh} and @command{scp}
|
|
@cindex method scpx
|
|
@cindex scpx method
|
|
@cindex scp (with scpx method)
|
|
@cindex 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
|
|
@var{user} /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.
|
|
|
|
|
|
@item @option{pscp} --- @command{plink} and @command{pscp}
|
|
@cindex method pscp
|
|
@cindex pscp method
|
|
@cindex pscp (with pscp method)
|
|
@cindex plink (with pscp method)
|
|
@cindex PuTTY (with pscp method)
|
|
|
|
This method is similar to @option{scp}, but it uses the
|
|
@command{plink} command to connect to the remote host, and it uses
|
|
@command{pscp} for transferring the files. These programs are part
|
|
of PuTTY, an SSH implementation for Windows.
|
|
|
|
CCC: Does @command{plink} support the @samp{-p} hack?
|
|
|
|
|
|
@item @option{fcp} --- @command{fsh} and @command{fcp}
|
|
@cindex method fcp
|
|
@cindex fcp method
|
|
@cindex fsh (with fcp method)
|
|
@cindex 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
|
|
@command{ssh} which allow for reusing the same @command{ssh} session
|
|
for submitting several commands. This avoids the startup overhead of
|
|
@command{scp} (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
|
|
@command{fsh @var{host} -l @var{user}}.
|
|
|
|
@cindex method fsh
|
|
@cindex 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.
|
|
|
|
|
|
@item @option{ftp}
|
|
@cindex method ftp
|
|
@cindex ftp method
|
|
|
|
This is not a native @value{tramp} method. Instead of, it forwards all
|
|
requests to @value{ftppackagename}.
|
|
@ifset xemacs
|
|
This works only for unified filenames, see @ref{Issues}.
|
|
@end ifset
|
|
|
|
|
|
@item @option{smb} --- @command{smbclient}
|
|
@cindex method smb
|
|
@cindex smb method
|
|
|
|
This is another not natural @value{tramp} method. It uses the
|
|
@command{smbclient} command on different Unices in order to connect to
|
|
an SMB server. An SMB server might be a Samba (or CIFS) server on
|
|
another UNIX host or, more interesting, a host running MS Windows. So
|
|
far, it is tested towards MS Windows NT, MS Windows 2000, and MS
|
|
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
|
|
@code{BIZARRE}, and edit @file{.emacs} in the home directory (share
|
|
@code{daniel$}) I would specify the filename
|
|
@file{@value{prefix}smb@value{postfixsinglehop}daniel%BIZARRE@@melancholia@value{postfix}/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.
|
|
|
|
@strong{Please 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.
|
|
|
|
@end table
|
|
|
|
@node Multi-hop Methods
|
|
@section Connecting to a remote host using multiple hops
|
|
@cindex multi-hop methods
|
|
@cindex methods, multi-hop
|
|
|
|
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. The format
|
|
of multi-hop filenames is slightly different than the format of normal
|
|
@value{tramp} methods.
|
|
|
|
@cindex method multi
|
|
@cindex multi method
|
|
A multi-hop file name specifies a method, a number of hops, and a
|
|
localname (path name on the remote system). The method name is always
|
|
@option{multi}.
|
|
|
|
Each hop consists of a @dfn{hop method} specification, a user name and
|
|
a host name. The hop method can be an inline method only. The
|
|
following hop methods are (currently) available:
|
|
|
|
@table @option
|
|
@item telnet
|
|
@cindex hop method telnet
|
|
@cindex telnet hop method
|
|
|
|
Uses the well-known @command{telnet} program to connect to the host.
|
|
Whereas user name and host name are supplied in the file name, the
|
|
user is queried for the password.
|
|
|
|
@item rsh
|
|
@cindex hop method rsh
|
|
@cindex rsh hop method
|
|
|
|
This uses @command{rsh} to connect to the host. You do not need to
|
|
enter a password unless @command{rsh} explicitly asks for it.
|
|
|
|
The variant @option{remsh} uses the @command{remsh} command. It
|
|
should be applied on machines where @command{remsh} is used instead of
|
|
@command{rsh}.
|
|
|
|
@item ssh
|
|
@cindex hop method ssh
|
|
@cindex ssh hop method
|
|
|
|
This uses @command{ssh} to connect to the host. You might have to enter
|
|
a password or a pass phrase.
|
|
|
|
@item su
|
|
@cindex hop method su
|
|
@cindex su hop method
|
|
|
|
This method does not actually contact a different host, but it allows
|
|
you to become a different user on the host you're currently on. This
|
|
might be useful if you want to edit files as root, but the remote host
|
|
does not allow remote root logins. In this case you can use
|
|
@option{telnet}, @option{rsh} or @option{ssh} to connect to the
|
|
remote host as a non-root user, then use an @option{su} hop to become
|
|
root. But @option{su} need not be the last hop in a sequence, you could
|
|
also use it somewhere in the middle, if the need arises.
|
|
|
|
Even though you @emph{must} specify both user and host with an
|
|
@option{su} hop, the host name is ignored and only the user name is
|
|
used.
|
|
|
|
@item sudo
|
|
@cindex hop method sudo
|
|
@cindex sudo hop method
|
|
|
|
This is similar to the @option{su} hop, except that it uses
|
|
@command{sudo} rather than @command{su} to become a different user.
|
|
|
|
@end table
|
|
|
|
Some people might wish to use port forwarding with @command{ssh} or
|
|
maybe they have to use a nonstandard port. This can be accomplished
|
|
by putting a stanza in @file{~/.ssh/config} for the account which
|
|
specifies a different port number for a certain host name. But it can
|
|
also be accomplished within @value{tramp}, by adding a multi-hop method.
|
|
For example:
|
|
|
|
@lisp
|
|
(add-to-list
|
|
'tramp-multi-connection-function-alist
|
|
'("sshf" tramp-multi-connect-rlogin "ssh %h -l %u -p 4400%n"))
|
|
@end lisp
|
|
|
|
Now you can use an @option{sshf} hop which connects to port 4400 instead of
|
|
the standard port.
|
|
|
|
|
|
@node Default Method
|
|
@section Selecting a default method
|
|
@cindex default method
|
|
|
|
@vindex 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:
|
|
|
|
@lisp
|
|
(setq tramp-default-method "scp")
|
|
@end lisp
|
|
|
|
@vindex 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}.
|
|
|
|
@lisp
|
|
(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"))
|
|
@end lisp
|
|
|
|
@noindent
|
|
See the documentation for the variable
|
|
@code{tramp-default-method-alist} for more details.
|
|
|
|
External transfer methods are normally preferable to inline transfer
|
|
methods, giving better performance.
|
|
|
|
@xref{Inline methods}.
|
|
@xref{External transfer methods}.
|
|
@xref{Multi-hop 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.
|
|
|
|
|
|
@subsection Which method is the right one for me?
|
|
@cindex 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
|
|
@value{prefix}ssh@value{postfixsinglehop}root@@otherhost@value{postfix}/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
|
|
@option{krlogin}.
|
|
|
|
For the special case of editing files on the local host as another
|
|
user, see the @option{su} or @option{sudo} methods. They offer
|
|
shortened syntax for the @samp{root} account, like
|
|
@file{@value{prefix}su@value{postfixsinglehop}@value{postfix}/etc/motd}.
|
|
|
|
People who edit large files may want to consider @option{scp} 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.
|
|
|
|
|
|
@node Customizing Methods
|
|
@section Using Non-Standard Methods
|
|
@cindex customizing methods
|
|
@cindex using non-standard methods
|
|
@cindex 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}}.
|
|
|
|
|
|
@node Customizing Completion
|
|
@section Selecting config files for user/host name completion
|
|
@cindex customizing completion
|
|
@cindex selecting config files
|
|
@vindex 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}).
|
|
@var{function} is responsible to extract user names and host names
|
|
from @var{file} for completion. There are two functions which access
|
|
this variable:
|
|
|
|
@defun tramp-get-completion-function method
|
|
This function returns the list of completion functions for @var{method}.
|
|
|
|
Example:
|
|
@example
|
|
(tramp-get-completion-function "rsh")
|
|
|
|
@result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
|
|
(tramp-parse-rhosts "~/.rhosts"))
|
|
@end example
|
|
@end defun
|
|
|
|
@defun tramp-set-completion-function method function-list
|
|
This function sets @var{function-list} as list of completion functions
|
|
for @var{method}.
|
|
|
|
Example:
|
|
@example
|
|
(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"))
|
|
@end example
|
|
@end defun
|
|
|
|
The following predefined functions parsing configuration files exist:
|
|
|
|
@table @asis
|
|
@item @code{tramp-parse-rhosts}
|
|
@findex tramp-parse-rhosts
|
|
|
|
This function parses files which are syntactical equivalent to
|
|
@file{~/.rhosts}. It returns both host names and user names, if
|
|
specified.
|
|
|
|
@item @code{tramp-parse-shosts}
|
|
@findex tramp-parse-shosts
|
|
|
|
This function parses files which are syntactical equivalent to
|
|
@file{~/.ssh/known_hosts}. Since there are no user names specified
|
|
in such files, it can return host names only.
|
|
|
|
@item @code{tramp-parse-sconfig}
|
|
@findex tramp-parse-shosts
|
|
|
|
This function returns the host nicknames defined by @code{Host} entries
|
|
in @file{~/.ssh/config} style files.
|
|
|
|
@item @code{tramp-parse-shostkeys}
|
|
@findex tramp-parse-shostkeys
|
|
|
|
SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and
|
|
@file{~/ssh2/hostkeys/*}. Hosts are coded in file names
|
|
@file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names
|
|
are always @code{nil}.
|
|
|
|
@item @code{tramp-parse-sknownhosts}
|
|
@findex tramp-parse-shostkeys
|
|
|
|
Another SSH2 style parsing of directories like
|
|
@file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This
|
|
case, hosts names are coded in file names
|
|
@file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}.
|
|
|
|
@item @code{tramp-parse-hosts}
|
|
@findex tramp-parse-hosts
|
|
|
|
A function dedicated to @file{/etc/hosts} style files. It returns
|
|
host names only.
|
|
|
|
@item @code{tramp-parse-passwd}
|
|
@findex tramp-parse-passwd
|
|
|
|
A function which parses @file{/etc/passwd} like files. Obviously, it
|
|
can return user names only.
|
|
|
|
@item @code{tramp-parse-netrc}
|
|
@findex tramp-parse-netrc
|
|
|
|
Finally, a function which parses @file{~/.netrc} like files.
|
|
@end 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:
|
|
|
|
@defun my-tramp-parse file
|
|
@var{file} 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:
|
|
@example
|
|
(my-tramp-parse "~/.my-tramp-hosts")
|
|
|
|
@result{} ((nil "toto") ("daniel" "melancholia"))
|
|
@end example
|
|
@end defun
|
|
|
|
|
|
@node Password caching
|
|
@section Reusing passwords for several connections.
|
|
@cindex 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.
|
|
|
|
@vindex 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.
|
|
|
|
@findex 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.
|
|
|
|
@vindex password-cache
|
|
If you don't like this feature for security reasons, password caching
|
|
can be disabled totally by customizing the variable
|
|
@code{password-cache} (setting it to @code{nil}).
|
|
|
|
Implementation Note: password caching is based on the package
|
|
password.el in No Gnus. For the time being, it is activated only when
|
|
this package is seen in the @code{load-path} while loading @value{tramp}.
|
|
@ifset installchapter
|
|
If you don't use No Gnus, you can take password.el from the @value{tramp}
|
|
@file{contrib} directory, see @ref{Installation parameters}.
|
|
@end ifset
|
|
It will be activated mandatory once No Gnus has found its way into
|
|
@value{emacsname}.
|
|
|
|
|
|
@node Remote Programs
|
|
@section How @value{tramp} finds and uses programs on the remote machine.
|
|
|
|
@value{tramp} depends on a number of programs on the remote host in order to
|
|
function, including @command{ls}, @command{test}, @command{find} and
|
|
@command{cat}.
|
|
|
|
In addition to these required tools, there are various tools that may be
|
|
required based on the connection method. See @ref{Inline methods} and
|
|
@ref{External transfer methods} for details on these.
|
|
|
|
Certain other tools, such as @command{perl} (or @command{perl5}) and
|
|
@command{grep} 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.
|
|
|
|
@vindex tramp-remote-path
|
|
When @value{tramp} connects to the remote machine, it searches for the
|
|
programs that it can use. The variable @var{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. 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:
|
|
|
|
@lisp
|
|
@i{;; We load @value{tramp} to define the variable.}
|
|
(require 'tramp)
|
|
@i{;; We have @command{perl} in "/usr/local/perl/bin"}
|
|
(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
|
|
@end lisp
|
|
|
|
|
|
@node Remote shell setup
|
|
@comment node-name, next, previous, up
|
|
@section Remote shell setup hints
|
|
@cindex remote shell setup
|
|
@cindex @file{.profile} file
|
|
@cindex @file{.login} file
|
|
@cindex 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
|
|
@emph{all} 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,
|
|
@command{ls -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.
|
|
|
|
@table @asis
|
|
@item @var{shell-prompt-pattern}
|
|
@vindex 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,
|
|
@value{tramp} recognizes the @code{>} character as the end of the prompt,
|
|
but it is not at the end of the buffer.
|
|
|
|
@item @var{tramp-shell-prompt-pattern}
|
|
@vindex tramp-shell-prompt-pattern
|
|
|
|
This regular expression is used by @value{tramp} in the same way as
|
|
@code{shell-prompt-pattern}, 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
|
|
@code{tramp-shell-prompt-pattern} is the same as the default value of
|
|
@code{shell-prompt-pattern}, which is reported to work well in many
|
|
circumstances.
|
|
|
|
@item @command{tset} and other questions
|
|
@cindex Unix command tset
|
|
@cindex 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. @value{tramp}
|
|
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 @value{tramp}. You can
|
|
do this by checking the @code{TERM} environment variable, it will be
|
|
set to @code{dumb} when connecting.
|
|
|
|
@vindex tramp-terminal-type
|
|
The variable @code{tramp-terminal-type} can be used to change this value
|
|
to @code{dumb}.
|
|
|
|
The other approach is to teach @value{tramp} about these questions. See
|
|
the variables @code{tramp-actions-before-shell} and
|
|
@code{tramp-multi-actions} (for multi-hop connections).
|
|
|
|
|
|
@item 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!
|
|
|
|
|
|
@item Non-Bourne commands in @file{.profile}
|
|
|
|
After logging in to the remote host, @value{tramp} issues the command
|
|
@command{exec /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
|
|
@file{~/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 @file{~/.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
|
|
@file{~/.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},
|
|
@value{tramp} 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
|
|
@command{exec /bin/sh} step. But how to find out if the shell is
|
|
Bourne-ish?
|
|
|
|
@end table
|
|
|
|
|
|
@node Auto-save and Backup
|
|
@section Auto-save and Backup configuration
|
|
@cindex auto-save
|
|
@cindex backup
|
|
@ifset emacs
|
|
@vindex backup-directory-alist
|
|
@end ifset
|
|
@ifset xemacs
|
|
@vindex bkup-backup-directory-info
|
|
@end ifset
|
|
|
|
Normally, @value{emacsname} writes backup files to the same directory
|
|
as the original files, but this behavior can be changed via the
|
|
variable
|
|
@ifset emacs
|
|
@code{backup-directory-alist}.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@code{bkup-backup-directory-info}.
|
|
@end 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
|
|
@file{@value{prefix}su@value{postfixsinglehop}root@@localhost@value{postfix}/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
|
|
@ifset emacs
|
|
@code{backup-directory-alist}
|
|
@end ifset
|
|
@ifset xemacs
|
|
@code{bkup-backup-directory-info}
|
|
@end 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
|
|
@ifset emacs
|
|
@code{backup-directory-alist}
|
|
@end ifset
|
|
@ifset xemacs
|
|
@code{bkup-backup-directory-info}
|
|
@end ifset
|
|
for @value{tramp} files:
|
|
|
|
@ifset emacs
|
|
@lisp
|
|
(add-to-list 'backup-directory-alist
|
|
(cons tramp-file-name-regexp nil))
|
|
@end lisp
|
|
@end ifset
|
|
@ifset xemacs
|
|
@lisp
|
|
(require 'backup-dir)
|
|
(add-to-list 'bkup-backup-directory-info
|
|
(list tramp-file-name-regexp ""))
|
|
@end lisp
|
|
@end ifset
|
|
|
|
Another possibility is to use the @value{tramp} variable
|
|
@ifset emacs
|
|
@code{tramp-backup-directory-alist}.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@code{tramp-bkup-backup-directory-info}.
|
|
@end ifset
|
|
This variable has the same meaning like
|
|
@ifset emacs
|
|
@code{backup-directory-alist}.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@code{bkup-backup-directory-info}.
|
|
@end 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.
|
|
|
|
@noindent
|
|
Example:
|
|
|
|
@ifset emacs
|
|
@lisp
|
|
(add-to-list 'backup-directory-alist
|
|
(cons "." "~/.emacs.d/backups/"))
|
|
(setq tramp-backup-directory-alist backup-directory-alist)
|
|
@end lisp
|
|
@end ifset
|
|
@ifset xemacs
|
|
@lisp
|
|
(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)
|
|
@end lisp
|
|
@end ifset
|
|
|
|
@noindent
|
|
The backup file name of
|
|
@file{@value{prefix}su@value{postfixsinglehop}root@@localhost@value{postfix}/etc/secretfile}
|
|
would be
|
|
@ifset emacs
|
|
@file{@value{prefix}su@value{postfixsinglehop}root@@localhost@value{postfix}~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}
|
|
@end ifset
|
|
@ifset xemacs
|
|
@file{@value{prefix}su@value{postfixsinglehop}root@@localhost@value{postfix}~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}
|
|
@end ifset
|
|
|
|
The same problem can happen with auto-saving files.
|
|
@ifset emacs
|
|
Since @value{emacsname} 21, the variable
|
|
@code{auto-save-file-name-transforms} 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
|
|
@code{tramp-auto-save-directory} to a proper value.
|
|
@end ifset
|
|
@ifset xemacs
|
|
For this purpose you can set the variable @code{auto-save-directory}
|
|
to a proper value.
|
|
@end ifset
|
|
|
|
|
|
@node Windows setup hints
|
|
@section Issues with Cygwin ssh
|
|
@cindex Cygwin, issues
|
|
|
|
This section needs a lot of work! Please help.
|
|
|
|
@cindex method sshx with Cygwin
|
|
@cindex 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:
|
|
|
|
@example
|
|
Pseudo-terminal will not be allocated because stdin is not a terminal.
|
|
@end example
|
|
|
|
Older @command{ssh} versions of Cygwin are told to cooperate with
|
|
@value{tramp} selecting @option{sshx} as the connection method. You
|
|
can find information about setting up Cygwin in their FAQ at
|
|
@uref{http://cygwin.com/faq/}.
|
|
|
|
@cindex method scpx with Cygwin
|
|
@cindex 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
|
|
@command{scp} 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.
|
|
|
|
@cindex Cygwin and ssh-agent
|
|
@cindex 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
|
|
@value{emacsname} and thus @value{tramp} and thus @command{ssh} and
|
|
@command{scp} started from @value{tramp} cannot communicate with
|
|
@command{ssh-agent}. 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 Windows@dots{}
|
|
|
|
|
|
@node Usage
|
|
@chapter Using @value{tramp}
|
|
@cindex 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.
|
|
|
|
@cindex type-ahead
|
|
Something that might happen which surprises you is that
|
|
@value{emacsname} remembers all your keystrokes, so if you see a
|
|
password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}}
|
|
twice instead of once, then the second keystroke will be processed by
|
|
@value{emacsname} 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!
|
|
|
|
@menu
|
|
* Filename Syntax:: @value{tramp} filename conventions.
|
|
* Multi-hop filename syntax:: Multi-hop filename conventions.
|
|
* Filename completion:: Filename completion.
|
|
* Dired:: Dired.
|
|
* Compilation:: Compile remote files.
|
|
@end menu
|
|
|
|
|
|
@node Filename Syntax
|
|
@section @value{tramp} filename conventions
|
|
@cindex filename syntax
|
|
@cindex filename examples
|
|
|
|
To access the file @var{localname} on the remote machine @var{machine} you
|
|
would specify the filename
|
|
@file{@value{prefix}@var{machine}@value{postfix}@var{localname}}.
|
|
This will connect to @var{machine} and transfer the file using the
|
|
default method. @xref{Default Method}.
|
|
|
|
Some examples of @value{tramp} filenames are shown below.
|
|
|
|
@table @file
|
|
@item @value{prefix}melancholia@value{postfix}.emacs
|
|
Edit the file @file{.emacs} in your home directory on the machine
|
|
@code{melancholia}.
|
|
|
|
@item @value{prefix}melancholia.danann.net@value{postfix}.emacs
|
|
This edits the same file, using the fully qualified domain name of
|
|
the machine.
|
|
|
|
@item @value{prefix}melancholia@value{postfix}~/.emacs
|
|
This also edits the same file --- the @file{~} is expanded to your
|
|
home directory on the remote machine, just like it is locally.
|
|
|
|
@item @value{prefix}melancholia@value{postfix}~daniel/.emacs
|
|
This edits the file @file{.emacs} in the home directory of the user
|
|
@code{daniel} on the machine @code{melancholia}. The @file{~<user>}
|
|
construct is expanded to the home directory of that user on the remote
|
|
machine.
|
|
|
|
@item @value{prefix}melancholia@value{postfix}/etc/squid.conf
|
|
This edits the file @file{/etc/squid.conf} on the machine
|
|
@code{melancholia}.
|
|
|
|
@end 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
|
|
@file{@value{prefix}@var{user}@@@var{machine}@value{postfix}/@var{path/to.file}}.
|
|
That means that connecting to @code{melancholia} as @code{daniel} and
|
|
editing @file{.emacs} in your home directory you would specify
|
|
@file{@value{prefix}daniel@@melancholia@value{postfix}.emacs}.
|
|
|
|
It is also possible to specify other file transfer methods
|
|
(@pxref{Default Method}) as part of the filename.
|
|
@ifset emacs
|
|
This is done by putting the method before the user and host name, as
|
|
in
|
|
@file{@value{prefix}@var{method}@value{postfixsinglehop}}
|
|
(Note the trailing colon).
|
|
@end ifset
|
|
@ifset xemacs
|
|
This is done by replacing the initial
|
|
@file{@value{prefix}} with
|
|
@file{@value{prefix}<method>@value{postfixsinglehop}}.
|
|
(Note the trailing slash!).
|
|
@end 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 @file{.emacs}
|
|
in my home directory I would specify the filename
|
|
@file{@value{prefix}ssh@value{postfixsinglehop}daniel@@melancholia@value{postfix}.emacs}.
|
|
|
|
|
|
@node Multi-hop filename syntax
|
|
@section Multi-hop filename conventions
|
|
@cindex filename syntax for multi-hop files
|
|
@cindex multi-hop filename syntax
|
|
|
|
The syntax of multi-hop file names is necessarily slightly different
|
|
than the syntax of other @value{tramp} file names. Here's an example
|
|
multi-hop file name:
|
|
|
|
@example
|
|
@value{prefix}multi@value{postfixsinglehop}rsh@value{postfixmultihop}out@@gate@value{postfixsinglehop}telnet@value{postfixmultihop}kai@@real.host@value{postfix}/path/to.file
|
|
@end example
|
|
|
|
This is quite a mouthful. So let's go through it step by step. The
|
|
file name consists of three parts.
|
|
@ifset emacs
|
|
The parts are separated by colons
|
|
@end ifset
|
|
@ifset xemacs
|
|
The parts are separated by slashes and square brackets.
|
|
@end ifset
|
|
The first part is @file{@value{prefix}multi}, the method
|
|
specification. The second part is
|
|
@file{rsh@value{postfixmultihop}out@@gate@value{postfixsinglehop}telnet@value{postfixmultihop}kai@@real.host}
|
|
and specifies the hops. The final part is @file{/path/to.file} and
|
|
specifies the file name on the remote host.
|
|
|
|
The first part and the final part should be clear. See @ref{Multi-hop
|
|
Methods}, for a list of alternatives for the method specification.
|
|
|
|
The second part can be subdivided again into components, so-called
|
|
hops. In the above file name, there are two hops,
|
|
@file{rsh@value{postfixmultihop}out@@gate} and
|
|
@file{telnet@value{postfixmultihop}kai@@real.host}.
|
|
|
|
Each hop can @emph{again} be subdivided into (three) components, the
|
|
@dfn{hop method}, the @dfn{user name} and the @dfn{host name}. The
|
|
meaning of the second and third component should be clear, and the hop
|
|
method says what program to use to perform that hop.
|
|
|
|
The first hop, @file{rsh@value{postfixmultihop}out@@gate},
|
|
says to use @command{rsh} to log in as user @code{out} to the host
|
|
@code{gate}. Starting at that host, the second hop,
|
|
@file{telnet@value{postfixmultihop}kai@@real.host}, says to
|
|
use @command{telnet} to log in as user @code{kai} to host
|
|
@code{real.host}.
|
|
|
|
@xref{Multi-hop Methods}, for a list of possible hop method values.
|
|
The variable @code{tramp-multi-connection-function-alist} contains the
|
|
list of possible hop methods and information on how to execute them,
|
|
should you want to add your own.
|
|
|
|
|
|
@node Filename completion
|
|
@section Filename completion
|
|
@cindex filename completion
|
|
|
|
Filename completion works with @value{tramp} for completion of method
|
|
names, of user names and of machine names (except multi-hop methods)
|
|
as well as for completion of file names on remote machines.
|
|
@ifset emacs
|
|
In order to enable this, Partial Completion mode must be set on.
|
|
@ifinfo
|
|
@xref{Completion Options, , , @value{emacsdir}}.
|
|
@end ifinfo
|
|
@end ifset
|
|
|
|
If you, for example, type @kbd{C-x C-f @value{prefix}t
|
|
@key{TAB}}, @value{tramp} might give you as result the choice for
|
|
|
|
@example
|
|
@ifset emacs
|
|
@value{prefixsinglehop}telnet@value{postfixsinglehop} tmp/
|
|
@value{prefixsinglehop}toto@value{postfix}
|
|
@end ifset
|
|
@ifset xemacs
|
|
@value{prefixsinglehop}telnet@value{postfixsinglehop} @value{prefixsinglehop}toto@value{postfix}
|
|
@end ifset
|
|
@end example
|
|
|
|
@samp{@value{prefixsinglehop}telnet@value{postfixsinglehop}}
|
|
is a possible completion for the respective method,
|
|
@ifset emacs
|
|
@samp{tmp/} stands for the directory @file{/tmp} on your local
|
|
machine,
|
|
@end ifset
|
|
and @samp{@value{prefixsinglehop}toto@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
|
|
@samp{@value{prefix}telnet@value{postfixsinglehop}}.
|
|
Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in
|
|
your @file{/etc/hosts} file, let's say
|
|
|
|
@example
|
|
@value{prefixsinglehop}telnet@value{postfixsinglehop}127.0.0.1@value{postfix} @value{prefixsinglehop}telnet@value{postfixsinglehop}192.168.0.1@value{postfix}
|
|
@value{prefixsinglehop}telnet@value{postfixsinglehop}localhost@value{postfix} @value{prefixsinglehop}telnet@value{postfixsinglehop}melancholia.danann.net@value{postfix}
|
|
@value{prefixsinglehop}telnet@value{postfixsinglehop}melancholia@value{postfix}
|
|
@end example
|
|
|
|
Now you can choose the desired machine, and you can continue to
|
|
complete file names on that machine.
|
|
|
|
As filename completion needs to fetch the listing of files from the
|
|
remote machine, this feature is sometimes fairly slow. As @value{tramp}
|
|
does not yet cache the results of directory listing, there is no gain
|
|
in performance the second time you complete filenames.
|
|
|
|
If the configuration files (@pxref{Customizing Completion}), which
|
|
@value{tramp} uses for analysis of completion, offer user names, those user
|
|
names will be taken into account as well.
|
|
|
|
|
|
@node Dired
|
|
@section Dired
|
|
@cindex dired
|
|
|
|
@value{tramp} works transparently with dired, enabling you to use this powerful
|
|
file management tool to manage files on any machine you have access to
|
|
over the Internet.
|
|
|
|
If you need to browse a directory tree, Dired is a better choice, at
|
|
present, than filename completion. Dired has its own cache mechanism
|
|
and will only fetch the directory listing once.
|
|
|
|
|
|
@node Compilation
|
|
@section Compile remote files
|
|
@cindex compile
|
|
@cindex recompile
|
|
|
|
@value{tramp} provides commands for compilation of files on remote
|
|
machines. In order to get them loaded, you need to require
|
|
@file{tramp-util.el}:
|
|
|
|
@lisp
|
|
(require 'tramp-util)
|
|
@end lisp
|
|
|
|
Afterwards, you can use the commands @code{tramp-compile} and
|
|
@code{tramp-recompile} instead of @code{compile} and @code{recompile},
|
|
respectively; @inforef{Compilation, ,@value{emacsdir}}. This does not
|
|
work for the @option{ftp} and @option{smb} methods.
|
|
|
|
The corresponding key bindings and menu entries calling these commands
|
|
are redefined automatically for buffers associated with remote files.
|
|
|
|
After finishing the compilation, you can use the usual commands like
|
|
@code{previous-error}, @code{next-error} and @code{first-error} for
|
|
navigation in the @file{*Compilation*} buffer.
|
|
|
|
|
|
@node Bug Reports
|
|
@chapter Reporting Bugs and Problems
|
|
@cindex 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
|
|
@uref{http://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.
|
|
|
|
@node Frequently Asked Questions
|
|
@chapter Frequently Asked Questions
|
|
@cindex frequently asked questions
|
|
@cindex FAQ
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Where can I get the latest @value{tramp}?
|
|
|
|
@value{tramp} is available under the URL below.
|
|
|
|
@noindent
|
|
@uref{ftp://ftp.gnu.org/gnu/tramp/}
|
|
|
|
@noindent
|
|
There is also a Savannah project page.
|
|
|
|
@noindent
|
|
@uref{http://savannah.gnu.org/projects/tramp/}
|
|
|
|
|
|
@item
|
|
Which systems does it work on?
|
|
|
|
The package has been used successfully on GNU Emacs 20, GNU Emacs 21
|
|
and GNU Emacs 22, as well as XEmacs 21. XEmacs 20 is more
|
|
problematic, see the notes in @file{tramp.el}. I don't think anybody
|
|
has really tried it on GNU Emacs 19.
|
|
|
|
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:
|
|
@uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/}
|
|
|
|
@c The link is broken. I've contacted Tom for clarification. Michael.
|
|
@ignore
|
|
The above mostly contains patches to old ssh versions; Tom Roche has a
|
|
Web page with instructions:
|
|
@uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html}
|
|
@end ignore
|
|
|
|
??? Is the XEmacs info correct?
|
|
|
|
??? Can somebody provide some information for getting it to work on NT
|
|
Emacs? I think there was some issue with @command{ssh}?
|
|
|
|
|
|
@item
|
|
@value{tramp} 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:
|
|
|
|
@itemize @minus
|
|
|
|
@item
|
|
Unknown characters in the prompt
|
|
|
|
@value{tramp} needs to recognize the prompt on the remote machine
|
|
after execution any command. This is not possible, when the prompt
|
|
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.
|
|
|
|
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: @command{[ $TERM = "dumb" ] && unsetopt zle}.
|
|
|
|
@item
|
|
@value{tramp} 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. 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 @code{tramp-chunksize}.
|
|
@end itemize
|
|
|
|
|
|
@item
|
|
File name completion does not work with @value{tramp}
|
|
|
|
When you log in to the remote machine, do you see the output of
|
|
@command{ls} in color? If so, this may be the cause of your problems.
|
|
|
|
@command{ls} 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
|
|
@option{--color=yes} 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.
|
|
|
|
|
|
@item
|
|
File name completion does not work in large directories
|
|
|
|
@value{tramp} 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
|
|
@command{/bin/sh}, @command{ksh} or @command{bash}, depending on which
|
|
of those supports tilde expansion.
|
|
|
|
|
|
@item
|
|
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.
|
|
|
|
@lisp
|
|
(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))
|
|
@end lisp
|
|
|
|
|
|
@item
|
|
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.
|
|
@value{tramp} tries to turn off saving the history, but maybe you have
|
|
to help. For example, you could put this in your @file{.kshrc}:
|
|
|
|
@example
|
|
if [ -f $HOME/.sh_history ] ; then
|
|
/bin/rm $HOME/.sh_history
|
|
fi
|
|
if [ "$@{HISTFILE-unset@}" != "unset" ] ; then
|
|
unset HISTFILE
|
|
fi
|
|
if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then
|
|
unset HISTSIZE
|
|
fi
|
|
@end example
|
|
|
|
|
|
@item
|
|
How can I disable @value{tramp}?
|
|
|
|
Shame on you, why did you read until now?
|
|
|
|
@ifset emacs
|
|
If you just want to have @value{ftppackagename} as default remote
|
|
files access package, you should apply the following code:
|
|
|
|
@lisp
|
|
(setq tramp-default-method "ftp")
|
|
@end lisp
|
|
@end ifset
|
|
|
|
Unloading @value{tramp} can be achieved by applying @kbd{M-x
|
|
tramp-unload-tramp}.
|
|
@ifset emacs
|
|
This resets also the @value{ftppackagename} plugins.
|
|
@end ifset
|
|
@end itemize
|
|
|
|
|
|
@c For the developer
|
|
@node Version Control
|
|
@chapter The inner workings of remote version control
|
|
@cindex 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
|
|
@var{tramp-remote-path}.
|
|
|
|
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.
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
|
|
@node Version Controlled Files
|
|
@section 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.
|
|
|
|
|
|
@node Remote Commands
|
|
@section 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
|
|
@code{call-process} 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
|
|
@code{vc-simple-command} 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.
|
|
|
|
|
|
@node Changed workfiles
|
|
@section 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.
|
|
|
|
|
|
@node Checking out files
|
|
@section 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.
|
|
|
|
|
|
@node Miscellaneous Version Control
|
|
@section Things related to Version Control that don't fit elsewhere
|
|
|
|
Minor implementation details, &c.
|
|
|
|
@menu
|
|
* Remote File Ownership:: How VC determines who owns a workfile.
|
|
* Back-end Versions:: How VC determines what release your RCS is.
|
|
@end menu
|
|
|
|
|
|
@node Remote File Ownership
|
|
@subsection How VC determines who owns a workfile
|
|
|
|
@value{emacsname} provides the @code{user-full-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.
|
|
|
|
|
|
@node Back-end Versions
|
|
@subsection 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.
|
|
|
|
|
|
@node Files directories and localnames
|
|
@chapter How file names, directories and localnames are mangled and managed.
|
|
|
|
@menu
|
|
* Localname deconstruction:: Breaking a localname into its components.
|
|
@end menu
|
|
|
|
|
|
@node Localname deconstruction
|
|
@section Breaking a localname into its components.
|
|
|
|
@value{tramp} file names are somewhat different, obviously, to ordinary file
|
|
names. As such, the lisp functions @code{file-name-directory} and
|
|
@code{file-name-nondirectory} 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.
|
|
|
|
|
|
@node Issues
|
|
@chapter Debatable Issues and What Was Decided
|
|
|
|
@itemize @bullet
|
|
@item 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,
|
|
@command{uudecode -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
|
|
@command{uudecode} 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.
|
|
|
|
@item @value{tramp} does not work on XEmacs 20.
|
|
|
|
This is because it requires the macro @code{with-timeout} which does not
|
|
appear to exist in XEmacs 20. I'm somewhat reluctant to add an
|
|
emulation macro to @value{tramp}, but if somebody who uses XEmacs 20 steps
|
|
forward and wishes to implement and test it, please contact me or the
|
|
mailing list.
|
|
|
|
@item 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.
|
|
|
|
@ifset xemacs
|
|
@strong{Note:} If you'd like to use a similar syntax like
|
|
@value{ftppackagename}, you need the following settings in your init
|
|
file:
|
|
|
|
@lisp
|
|
(setq tramp-unified-filenames t)
|
|
(require 'tramp)
|
|
@end 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
|
|
@option{ftp} @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}.
|
|
@end ifset
|
|
@end itemize
|
|
|
|
@node Concept Index
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Concept Index
|
|
@printindex cp
|
|
@contents
|
|
@c End of tramp.texi - the TRAMP User Manual
|
|
@bye
|
|
|
|
@c TODO
|
|
@c
|
|
@c * Say something about the .login and .profile files of the remote
|
|
@c shells.
|
|
@c * Explain how tramp.el works in principle: open a shell on a remote
|
|
@c host and then send commands to it.
|
|
@c * Mention that bookmarks are a cool feature to go along with Tramp.
|
|
@c * Make terminology "inline" vs "out-of-band" consistent.
|
|
@c It seems that "external" is also used instead of "out-of-band".
|
|
|
|
@c * M. Albinus
|
|
@c ** Use `filename' resp. `file name' consistently.
|
|
@c ** Use `host' resp. `machine' consistently.
|
|
@c ** Consistent small or capitalized words especially in menues.
|
|
|
|
@ignore
|
|
arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808
|
|
@end ignore
|