mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-01 08:17:38 +00:00
3845 lines
122 KiB
Plaintext
3845 lines
122 KiB
Plaintext
\input texinfo @c -*- mode: texinfo; coding: utf-8 -*-
|
|
@setfilename ../../info/tramp.info
|
|
@c %**start of header
|
|
@settitle TRAMP User Manual
|
|
@include docstyle.texi
|
|
@c %**end of header
|
|
|
|
@c This is *so* much nicer :)
|
|
@footnotestyle end
|
|
|
|
@c In the Tramp repository, 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 Macro for formatting a file name according to the respective syntax.
|
|
@c xxx and yyy are auxiliary macros in order to omit leading and
|
|
@c trailing whitespace. Not very elegant, but I don't know it better.
|
|
|
|
@c There are subtle differences between texinfo 4.13 and 5.0. We must
|
|
@c declare two versions of the macro. This will be improved, hopefully.
|
|
|
|
@c Texinfo 5.0.
|
|
@ifset txicommandconditionals
|
|
@macro xxx {one}
|
|
@set \one\
|
|
@end macro
|
|
|
|
@macro yyy {one, two}
|
|
@xxx{x\one\}@c
|
|
@ifclear x
|
|
\one\@w{}\two\@c
|
|
@end ifclear
|
|
@clear x\one\
|
|
@end macro
|
|
|
|
@macro trampfn {method, user, host, localname}
|
|
@value{prefix}@c
|
|
@yyy{\method\,@value{postfixhop}}@c
|
|
@yyy{\user\,@@}@c
|
|
\host\@value{postfix}\localname\
|
|
@end macro
|
|
@end ifset
|
|
|
|
@c Texinfo 4.13.
|
|
@ifclear txicommandconditionals
|
|
@macro xxx {one}@c
|
|
@set \one\@c
|
|
@end macro
|
|
|
|
@macro yyy {one, two}@c
|
|
@xxx{x\one\}@c
|
|
@ifclear x@c
|
|
\one\@w{}\two\@c
|
|
@end ifclear
|
|
@clear x\one\@c
|
|
@end macro
|
|
|
|
@macro trampfn {method, user, host, localname}@c
|
|
@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
|
|
@end macro
|
|
@end ifclear
|
|
|
|
@copying
|
|
Copyright @copyright{} 1999--2015 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.3 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''.
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You have the freedom to
|
|
copy and modify this GNU manual.''
|
|
@end quotation
|
|
@end copying
|
|
|
|
@c Entries for @command{install-info} to use
|
|
@dircategory @value{emacsname} network features
|
|
@direntry
|
|
* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
|
|
@value{emacsname} remote file access via ssh and scp.
|
|
@end direntry
|
|
|
|
@titlepage
|
|
@title @value{tramp} version @value{trampver} User Manual
|
|
@author by Daniel Pittman
|
|
@author based on documentation by Kai Großjohann
|
|
@page
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
|
|
@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
|
|
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 Git 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.
|
|
|
|
For the developer:
|
|
|
|
* Files directories and localnames::
|
|
How file names, directories and localnames
|
|
are mangled and managed.
|
|
* Traces and Profiles:: How to Customize Traces.
|
|
* Issues:: Debatable Issues and What Was Decided.
|
|
|
|
* GNU Free Documentation License:: The license for this documentation.
|
|
* Function Index:: @value{tramp} functions.
|
|
* Variable Index:: User options and variables.
|
|
* Concept Index:: An item for each concept.
|
|
|
|
@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.
|
|
|
|
@end ifset
|
|
|
|
Configuring @value{tramp} for use
|
|
|
|
* Connection types:: Types of connections to remote hosts.
|
|
* Inline methods:: Inline methods.
|
|
* External methods:: External methods.
|
|
@ifset emacsgvfs
|
|
* GVFS based methods:: GVFS based external methods.
|
|
@end ifset
|
|
@ifset emacsgw
|
|
* Gateway methods:: Gateway methods.
|
|
@end ifset
|
|
* Default Method:: Selecting a default method.
|
|
* Default User:: Selecting a default user.
|
|
* Default Host:: Selecting a default host.
|
|
* Multi-hops:: Connecting to a remote host using multiple hops.
|
|
* Customizing Methods:: Using Non-Standard Methods.
|
|
* Customizing Completion:: Selecting config files for user/host name completion.
|
|
* Password handling:: Reusing passwords for several connections.
|
|
* Connection caching:: Reusing connection related information.
|
|
* Predefined connection information::
|
|
Setting own connection related information.
|
|
* Remote programs:: How @value{tramp} finds and uses programs on the remote host.
|
|
* Remote shell setup:: Remote shell setup hints.
|
|
* Android shell setup:: Android shell setup hints.
|
|
* Auto-save and Backup:: Auto-save and Backup.
|
|
* Windows setup hints:: Issues with Cygwin ssh.
|
|
|
|
Using @value{tramp}
|
|
|
|
* File name Syntax:: @value{tramp} file name conventions.
|
|
* File name completion:: File name completion.
|
|
* Ad-hoc multi-hops:: Declaring multiple hops in the file name.
|
|
* Remote processes:: Integration with other @value{emacsname} packages.
|
|
* Cleanup remote connections:: Cleanup remote connections.
|
|
|
|
How file names, directories and localnames are mangled and managed
|
|
|
|
* Localname deconstruction:: Breaking a localname into its components.
|
|
@ifset emacs
|
|
* External packages:: Integration with external Lisp packages.
|
|
@end ifset
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
|
|
@node Overview
|
|
@chapter An overview of @value{tramp}
|
|
@cindex overview
|
|
|
|
@value{tramp} is for transparently accessing remote files from within
|
|
@value{emacsname}. @value{tramp} enables an easy, convenient, and
|
|
consistent interface to remote files as if they are local files.
|
|
@value{tramp}'s transparency extends to editing, version control, and
|
|
@code{dired}.
|
|
|
|
@value{tramp} can access remote hosts using any number of access
|
|
methods, such as @command{rsh}, @command{rlogin}, @command{telnet},
|
|
and related programs. If these programs can successfully pass
|
|
@acronym{ASCII]} characters, @value{tramp} can use them.
|
|
@value{tramp} does not require or mandate 8-bit clean connections.
|
|
|
|
@value{tramp}'s most common access method is through @command{ssh}, a
|
|
more secure alternative to @command{ftp} and other older access
|
|
methods.
|
|
|
|
@value{tramp} on Windows operating systems is integrated with the
|
|
PuTTY package, and uses the @command{plink} program.
|
|
|
|
@value{tramp} mostly operates transparently in the background using
|
|
the connection programs. As long as these programs enable remote login
|
|
and can use the terminal, @value{tramp} can adapt them for seamless
|
|
and transparent access.
|
|
|
|
@value{tramp} temporarily transfers a remote file's contents to the
|
|
local host editing and related operations. @value{tramp} can also
|
|
transfer files between hosts using standard Emacs interfaces, a
|
|
benefit of direct integration of @value{tramp} in @value{emacsname}.
|
|
|
|
@value{tramp} can transfer files using any number of available host
|
|
programs for remote files, such as @command{rcp}, @command{scp},
|
|
@command{rsync} or (under Windows) @command{pscp}. @value{tramp}
|
|
provides easy ways to specify these programs and customize them to
|
|
specific files, hosts, or access methods.
|
|
|
|
For faster small-size file transfers, @value{tramp} supports encoded
|
|
transfers directly through the shell using @command{mimencode} or
|
|
@command{uuencode} provided such tools are available on the remote
|
|
host.
|
|
|
|
|
|
@subsubheading @value{tramp} behind the scenes
|
|
@cindex behind the scenes
|
|
@cindex details of operation
|
|
@cindex how it works
|
|
|
|
Accessing a remote file through @value{tramp} entails a series of
|
|
actions, many of which are transparent to the user. Yet some actions
|
|
may require user response (such as entering passwords or completing
|
|
file names). One typical scenario, opening a file on a remote host, is
|
|
presented here to illustrate the steps involved:
|
|
|
|
@kbd{C-x C-f} to initiate find-file, enter part of the @value{tramp}
|
|
file name, then hit @kbd{@key{TAB}} for completion. If this is the
|
|
first time connection to that host, here's what happens:
|
|
|
|
@itemize
|
|
@item
|
|
@value{tramp} invokes @samp{telnet @var{host}} or @samp{rsh @var{host}
|
|
-l @var{user}} and establishes an external process to connect to the
|
|
remote host. @value{tramp} communicates with the process through an
|
|
@value{emacsname} buffer, which also shows output from the remote
|
|
host.
|
|
|
|
@item
|
|
The remote host may prompt for a login name (for @command{telnet}, for
|
|
example) in the buffer. If on the other hand, the login name was
|
|
included in the file name portion, @value{tramp} sends the login name
|
|
followed by a newline.
|
|
|
|
@item
|
|
The remote host may then prompt for a password or pass phrase (for
|
|
@command{rsh} or for @command{telnet}). @value{tramp} displays the
|
|
password prompt in the minibuffer. @value{tramp} then sends whatever
|
|
is entered to the remote host, followed by a newline.
|
|
|
|
@item
|
|
@value{tramp} now waits for either the shell prompt or a failed login
|
|
message.
|
|
|
|
If @value{tramp} does not receive any messages within a timeout period
|
|
(a minute, for example), then @value{tramp} responds with an error
|
|
message about not finding the remote shell prompt. If any messages
|
|
from the remote host, @value{tramp} displays them in the buffer.
|
|
|
|
For any @samp{login failed} message from the remote host,
|
|
@value{tramp} aborts the login attempt, and repeats the login steps
|
|
again.
|
|
|
|
@item
|
|
Upon successful login and @value{tramp} recognizes the shell prompt
|
|
from the remote host, @value{tramp} prepares the shell environment by
|
|
turning off echoing, setting shell prompt, and other housekeeping
|
|
chores.
|
|
|
|
@strong{Note} that for the remote shell, @value{tramp} invokes
|
|
@command{/bin/sh}. The remote host must recognize @samp{exec /bin/sh}
|
|
and execute the appropriate shell. This shell must support Bourne
|
|
shell syntax.
|
|
|
|
@item
|
|
@value{tramp} executes @command{cd} and @command{ls} commands to find
|
|
which files exist on the remote host. @value{tramp} sometimes uses
|
|
@command{echo} with globbing. @value{tramp} checks if a file or
|
|
directory is writable with @command{test}. After each command,
|
|
@value{tramp} parses the output from the remote host for completing
|
|
the next operation.
|
|
|
|
@item
|
|
After remote file name completion, @value{tramp} transfers the file
|
|
contents from the remote host.
|
|
|
|
For inline transfers, @value{tramp} sends a command, such as
|
|
@samp{mimencode -b /path/to/remote/file}, waits until the output has
|
|
accumulated in the buffer, decodes that output to produce the file's
|
|
contents.
|
|
|
|
For external transfers, @value{tramp} sends a command as follows:
|
|
@example
|
|
rcp user@@host:/path/to/remote/file /tmp/tramp.4711
|
|
@end example
|
|
@value{tramp} reads the local temporary file @file{/tmp/tramp.4711}
|
|
into a buffer, and then deletes the temporary file.
|
|
|
|
@item
|
|
Edit, modify, change the buffer contents as normal, and then save the
|
|
buffer wth @kbd{C-x C-s}.
|
|
|
|
@item
|
|
@value{tramp} transfers the buffer contents to the remote host in
|
|
a reverse of the process using the appropriate inline or external
|
|
program.
|
|
@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 included as part of Emacs (since Emacs version 22.1).
|
|
|
|
@value{tramp} is also freely packaged for download on the Internet at
|
|
@uref{ftp://ftp.gnu.org/gnu/tramp/}.
|
|
|
|
@value{tramp} development versions are available on Git servers.
|
|
Development versions contain new and incomplete features.
|
|
|
|
One way to obtain from Git server is to visit the Savannah project
|
|
page at the following URL and then clicking on the Git link in the
|
|
navigation bar at the top.
|
|
|
|
@noindent
|
|
@uref{http://savannah.gnu.org/projects/tramp/}
|
|
|
|
@noindent
|
|
Another way is to follow the terminal session below:
|
|
|
|
@example
|
|
] @strong{cd ~/@value{emacsdir}}
|
|
] @strong{git clone git://git.savannah.gnu.org/tramp.git}
|
|
@end example
|
|
|
|
@noindent
|
|
From behind a firewall:
|
|
|
|
@example
|
|
] @strong{git config --global http.proxy http://user:pwd@@proxy.server.com:8080}
|
|
] @strong{git clone http://git.savannah.gnu.org/r/tramp.git}
|
|
@end example
|
|
|
|
@noindent
|
|
Tramp developers:
|
|
|
|
@example
|
|
] @strong{git clone login@@git.sv.gnu.org:/srv/git/tramp.git}
|
|
@end example
|
|
|
|
@noindent
|
|
After one of the above commands, @file{~/@value{emacsdir}/tramp} will
|
|
containing the latest version of @value{tramp}.
|
|
|
|
@noindent
|
|
To fetch updates from the repository, use git pull:
|
|
|
|
@example
|
|
] @strong{cd ~/@value{emacsdir}/tramp}
|
|
] @strong{git pull}
|
|
@end example
|
|
|
|
@noindent
|
|
Run @command{autoconf} as follows to generate 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
|
|
|
|
@value{tramp} development started at the end of November 1998 as
|
|
@file{rssh.el}. It provided only one method of access. It used
|
|
@command{ssh} for login and @command{scp} to transfer file contents.
|
|
The name was changed to @file{rcp.el} before it got its preset name
|
|
@value{tramp}. New methods of remote access were added, so was support
|
|
for version control.
|
|
|
|
April 2000 was the first time when multi-hop methods were added. In
|
|
July 2002, @value{tramp} unified file names with Ange-FTP@. In July
|
|
2004, proxy hosts replaced multi-hop methods. Running commands on
|
|
remote hosts was introduced in December 2005.
|
|
@ifset emacsgw
|
|
Support for gateways since April 2007.
|
|
@end ifset
|
|
@ifset emacsgvfs
|
|
GVFS integration started in February 2009.
|
|
@end ifset
|
|
@ifset emacs
|
|
Remote commands on Windows hosts since September 2011.
|
|
@end ifset
|
|
Ad-hoc multi-hop methods (with a changed syntax) re-enabled in November
|
|
2011.
|
|
|
|
In November 2012, added Juergen Hoetzel's @file{tramp-adb.el}.
|
|
|
|
In December 2001, XEmacs package repository adds @value{tramp}.
|
|
|
|
|
|
@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}
|
|
@cindex configuration
|
|
@cindex default configuration
|
|
|
|
@value{tramp} is initially configured to use the @command{scp} program
|
|
to connect to the remote host. Just type @kbd{C-x C-f} and then enter
|
|
file name @file{@trampfn{, user, host, /path/to.file}}. For details,
|
|
see @xref{Default Method}.
|
|
|
|
For problems related to the behavior of remote shell, see @ref{Remote
|
|
shell setup} for details.
|
|
|
|
For changing the connection type and file access method from the
|
|
defaults to one of several other options, see (@pxref{Connection
|
|
types}).
|
|
|
|
@strong{Note} that some user options and variables described in these
|
|
examples are not auto loaded by @value{emacsname}. All examples
|
|
require @value{tramp} is installed and loaded:
|
|
|
|
@lisp
|
|
(require 'tramp)
|
|
@end lisp
|
|
|
|
|
|
@menu
|
|
* Connection types:: Types of connections to remote hosts.
|
|
* Inline methods:: Inline methods.
|
|
* External methods:: External methods.
|
|
@ifset emacsgvfs
|
|
* GVFS based methods:: GVFS based external methods.
|
|
@end ifset
|
|
@ifset emacsgw
|
|
* Gateway methods:: Gateway methods.
|
|
@end ifset
|
|
* Default Method:: Selecting a default method.
|
|
Here we also try to help those who
|
|
don't have the foggiest which method
|
|
is right for them.
|
|
* Default User:: Selecting a default user.
|
|
* Default Host:: Selecting a default host.
|
|
* Multi-hops:: Connecting to a remote host using multiple hops.
|
|
* Customizing Methods:: Using Non-Standard Methods.
|
|
* Customizing Completion:: Selecting config files for user/host name completion.
|
|
* Password handling:: Reusing passwords for several connections.
|
|
* Connection caching:: Reusing connection related information.
|
|
* Predefined connection information::
|
|
Setting own connection related information.
|
|
* Remote programs:: How @value{tramp} finds and uses programs on the remote host.
|
|
* Remote shell setup:: Remote shell setup hints.
|
|
* Android shell setup:: Android shell setup hints.
|
|
* Auto-save and Backup:: Auto-save and Backup.
|
|
* Windows setup hints:: Issues with Cygwin ssh.
|
|
@end menu
|
|
|
|
|
|
@node Connection types
|
|
@section Types of connections to remote hosts
|
|
@cindex connection types, overview
|
|
|
|
@dfn{Inline method} and @dfn{external method} are the two basic types
|
|
of access methods. While they both use the same remote shell access
|
|
programs, such as @command{rsh}, @command{ssh}, or @command{telnet},
|
|
they differ in the file access methods. Choosing the right method
|
|
becomes important for editing files, transferring large files, or
|
|
operating on a large number of files.
|
|
|
|
@cindex inline methods
|
|
@cindex external methods
|
|
@cindex methods, inline
|
|
@cindex methods, external
|
|
|
|
The performance of the external 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 @option{scp}-based access
|
|
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 methods should be configured such a way that they don't
|
|
require a password (with @command{ssh-agent}, or such alike). Modern
|
|
@command{scp} implementations offer options to reuse existing
|
|
@command{ssh} connections, which will be enabled by default if
|
|
available. If it isn't possible, you should consider @ref{Password
|
|
handling}, otherwise you will be prompted for a password every copy
|
|
action.
|
|
|
|
|
|
@node Inline methods
|
|
@section Inline methods
|
|
@cindex inline methods
|
|
@cindex methods, inline
|
|
|
|
Inline methods use the same login connection to transfer file
|
|
contents. Inline methods are quick and easy for small files. They
|
|
depend on the availability of suitable encoding and decoding programs
|
|
on the remote host. For local source and destination, @value{tramp}
|
|
may use built-in equivalents of such programs in @value{emacsname}.
|
|
|
|
Inline methods can work in situations where an external transfer
|
|
program is unavailable. Inline methods also work when transferring
|
|
files between different @emph{user identities} on the same host.
|
|
|
|
@cindex uuencode
|
|
@cindex mimencode
|
|
@cindex base-64 encoding
|
|
|
|
@value{tramp} checks the remote host for the availability and
|
|
usability of @command{mimencode} (part of the @command{metamail}
|
|
package) or @command{uuencode}. @value{tramp} uses the first reliable
|
|
command it finds. @value{tramp}'s search path can be customized, see
|
|
@ref{Remote programs}.
|
|
|
|
In case both @command{mimencode} and @command{uuencode} are
|
|
unavailable, @value{tramp} first transfers a small Perl program to the
|
|
remote host, and then tries that program for encoding and decoding.
|
|
|
|
To increase transfer speeds for large text files, use compression
|
|
before encoding. The variable @var{tramp-inline-compress-start-size}
|
|
specifies the file size for such optimization.
|
|
|
|
@table @asis
|
|
@item @option{rsh}
|
|
@cindex method rsh
|
|
@cindex rsh method
|
|
|
|
@command{rsh} is an option for connecting to hosts within local
|
|
networks since @command{rsh} is not as secure as other methods.
|
|
|
|
|
|
@item @option{ssh}
|
|
@cindex method ssh
|
|
@cindex ssh method
|
|
|
|
@command{ssh} is a more secure option than others to connect to a
|
|
remote host.
|
|
|
|
@command{ssh} can also take extra parameters as port numbers. For
|
|
example, a host on port 42 is specified as @file{host#42} (the real
|
|
host name, a hash sign, then a port number). It is the same as passing
|
|
@code{-p 42} to the @command{ssh} command.
|
|
|
|
@item @option{telnet}
|
|
@cindex method telnet
|
|
@cindex telnet method
|
|
|
|
Connecting to a remote host with @command{telnet} is as insecure
|
|
as the @option{rsh} method.
|
|
|
|
|
|
@item @option{su}
|
|
@cindex method su
|
|
@cindex su method
|
|
|
|
Instead of connecting to a remote host, @command{su} program allows
|
|
editing as another user. The host can be either @samp{localhost} or
|
|
the host returned by the function @command{(system-name)}. See
|
|
@ref{Multi-hops} for an exception to this behavior.
|
|
|
|
@item @option{sudo}
|
|
@cindex method sudo
|
|
@cindex sudo method
|
|
|
|
Similar to @option{su} method, @option{sudo} uses @command{sudo}.
|
|
@command{sudo} must have sufficient rights to start a shell.
|
|
|
|
@item @option{sshx}
|
|
@cindex method sshx
|
|
@cindex sshx method
|
|
|
|
Works like @option{ssh} but without the extra authentication prompts.
|
|
@option{sshx} uses @samp{ssh -t -t @var{host} -l @var{user} /bin/sh}
|
|
to open a connection with a ``standard'' login shell.
|
|
|
|
@strong{Note} that @option{sshx} does not bypass authentication
|
|
questions. For example, if the host key of the remote host is not
|
|
known, @option{sshx} will still ask ``Are you sure you want to
|
|
continue connecting?''. @value{tramp} cannot handle such questions.
|
|
Connections will have to be setup where logins can proceed without
|
|
such questions.
|
|
|
|
@option{sshx} is useful for Windows users when @command{ssh} triggers
|
|
an error about allocating a pseudo tty. This happens due to missing
|
|
shell prompts that confuses @value{tramp}.
|
|
|
|
@option{sshx} supports the @samp{-p} argument.
|
|
|
|
@item @option{krlogin}
|
|
@cindex method krlogin
|
|
@cindex krlogin method
|
|
@cindex Kerberos (with krlogin method)
|
|
|
|
This method is also similar to @option{ssh}. It uses the
|
|
@command{krlogin -x} command only for remote host login.
|
|
|
|
@item @option{ksu}
|
|
@cindex method ksu
|
|
@cindex ksu method
|
|
@cindex Kerberos (with ksu method)
|
|
|
|
This is another method from the Kerberos suite. It behaves like @option{su}.
|
|
|
|
|
|
@item @option{plink}
|
|
@cindex method plink
|
|
@cindex plink method
|
|
|
|
@option{plink} method is for Windows users with the PuTTY
|
|
implementation of SSH@. It uses @samp{plink -ssh} to log in to the
|
|
remote host.
|
|
|
|
Check the @samp{Share SSH connections if possible} control for that
|
|
session.
|
|
|
|
@option{plink} method supports the @samp{-P} argument.
|
|
|
|
|
|
@item @option{plinkx}
|
|
@cindex method plinkx
|
|
@cindex plinkx method
|
|
|
|
Another method using PuTTY on Windows with session names instead of
|
|
host names. @option{plinkx} calls @samp{plink -load @var{session} -t}.
|
|
User names and port numbers must be defined in the session.
|
|
|
|
Check the @samp{Share SSH connections if possible} control for that
|
|
session.
|
|
|
|
@end table
|
|
|
|
|
|
@node External methods
|
|
@section External methods
|
|
@cindex methods, external
|
|
@cindex external methods
|
|
|
|
External methods operate over multiple channels, using the remote
|
|
shell connection for some actions while delegating file transfers to
|
|
an external transfer program.
|
|
|
|
External methods save on the overhead of encoding and decoding of
|
|
inline methods.
|
|
|
|
Since external methods have the overhead of opening a new channel,
|
|
files smaller than @var{tramp-copy-size-limit} still use inline
|
|
methods.
|
|
|
|
@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 host and transfer files. This is the fastest
|
|
access method available.
|
|
|
|
The alternative method @option{remcp} uses the @command{remsh} and
|
|
@command{rcp} commands.
|
|
|
|
@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 a combination of @command{ssh} to connect and @command{scp} to
|
|
transfer is the most secure. While the performance is good, it is
|
|
slower than the inline methods for smaller files. Though there is no
|
|
overhead of encoding and decoding of the inline methods,
|
|
@command{scp}'s cryptographic handshake negates those speed gains.
|
|
|
|
@option{ssh}-based methods support @samp{-p} feature for specifying
|
|
port numbers. For example, @file{host#42} passes @samp{-p 42} in the
|
|
argument list to @command{ssh}, and @samp{-P 42} in the argument list
|
|
to @command{scp}.
|
|
|
|
@item @option{rsync}---@command{ssh} and @command{rsync}
|
|
@cindex method rsync
|
|
@cindex rsync method
|
|
@cindex rsync (with rsync method)
|
|
@cindex ssh (with rsync method)
|
|
|
|
@command{ssh} command to connect in combination with @command{rsync}
|
|
command to transfer is similar to the @option{scp} method.
|
|
|
|
@command{rsync} performs much better than @command{scp} when
|
|
transferring files that exist on both hosts. However, this advantage
|
|
is lost if the file exists only on one side of the connection.
|
|
|
|
This method supports the @samp{-p} argument.
|
|
|
|
|
|
@item @option{scpx}---@command{ssh} and @command{scp}
|
|
@cindex method scpx
|
|
@cindex scpx method
|
|
@cindex scp (with scpx method)
|
|
@cindex ssh (with scpx method)
|
|
|
|
@option{scpx} is useful to avoid login shell questions. It is similar
|
|
in performance to @option{scp}. @option{scpx} uses @samp{ssh -t -t
|
|
@var{host} -l @var{user} /bin/sh} to open a connection.
|
|
|
|
@option{sshx} is useful for Windows users when @command{ssh} triggers
|
|
an error about allocating a pseudo tty. This happens due to missing
|
|
shell prompts that confuses @value{tramp}.
|
|
|
|
This method supports the @samp{-p} argument.
|
|
|
|
|
|
@item @option{pscp}---@command{plink} and @command{pscp}
|
|
@item @option{psftp}---@command{plink} and @command{psftp}
|
|
@cindex method pscp
|
|
@cindex pscp method
|
|
@cindex pscp (with pscp method)
|
|
@cindex plink (with pscp method)
|
|
@cindex PuTTY (with pscp method)
|
|
@cindex method psftp
|
|
@cindex psftp method
|
|
@cindex pscp (with psftp method)
|
|
@cindex plink (with psftp method)
|
|
@cindex PuTTY (with psftp method)
|
|
|
|
These methods are similar to @option{scp} or @option{sftp}, but they
|
|
use the @command{plink} command to connect to the remote host, and
|
|
they use @command{pscp} or @command{psftp} for transferring the files.
|
|
These programs are part of PuTTY, an SSH implementation for Windows.
|
|
|
|
Check the @samp{Share SSH connections if possible} control for that
|
|
session.
|
|
|
|
These methods support the @samp{-P} argument.
|
|
|
|
|
|
@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 uses @command{fsh} to
|
|
connect and @command{fcp} to transfer files. @command{fsh/fcp}, a
|
|
front-end for @command{ssh}, reuse @command{ssh} session by
|
|
submitting several commands. This avoids the startup overhead due to
|
|
@command{scp}'s secure connection. Inline methods have similar
|
|
benefits.
|
|
|
|
The command used for this connection is: @samp{fsh @var{host} -l
|
|
@var{user} /bin/sh -i}
|
|
|
|
@cindex method fsh
|
|
@cindex fsh method
|
|
|
|
@option{fsh} has no inline method since the multiplexing it offers is
|
|
not useful for @value{tramp}. @command{fsh} connects to remote host
|
|
and @value{tramp} keeps that one connection open.
|
|
|
|
@item @option{nc}---@command{telnet} and @command{nc}
|
|
@cindex method nc
|
|
@cindex nc method
|
|
@cindex nc (with nc method)
|
|
@cindex telnet (with nc method)
|
|
|
|
Using @command{telnet} to connect and @command{nc} to transfer files
|
|
is sometimes the only combination suitable for accessing routers or
|
|
NAS hosts. These dumb devices have severely restricted local shells,
|
|
such as the @command{busybox} and do not host any other encode or
|
|
decode programs.
|
|
|
|
@item @option{ftp}
|
|
@cindex method ftp
|
|
@cindex ftp method
|
|
|
|
When @value{tramp} uses @option{ftp}, it forwards requests to whatever
|
|
ftp program is specified by @value{ftppackagename}. This external
|
|
program must be capable of servicing requests from @value{tramp}.
|
|
|
|
@ifset xemacs
|
|
This method works only for unified file names, see @ref{Issues}.
|
|
@end ifset
|
|
|
|
|
|
@item @option{smb}---@command{smbclient}
|
|
@cindex method smb
|
|
@cindex smb method
|
|
|
|
This is another non-native @value{tramp} method. @command{smbclient}
|
|
connects to any host with SMB/CIFS protocol, such as MS Windows and
|
|
Samba Servers running on Unixes. Tests show this @value{tramp} method
|
|
works with MS Windows NT, MS Windows 2000, MS Windows XP, MS Windows
|
|
Vista, and MS Windows 7.
|
|
|
|
Using @command{smbclient} requires a few tweaks when working with
|
|
@value{tramp}:
|
|
|
|
The first directory in the localname must be a share name on the
|
|
remote host.
|
|
|
|
Since smb shares end in the @code{$} character, @value{tramp} must use
|
|
@code{$$} when specifying those shares to avoid environment variable
|
|
substitutions.
|
|
|
|
When @value{tramp} is not specific about the share name or uses the
|
|
generic remote directory @code{/}, @command{smbclient} returns all
|
|
available shares.
|
|
|
|
Since SMB authentication is based on each SMB share, @value{tramp}
|
|
prompts for a password even when accessing a different share on the
|
|
same SMB host. This prompting can be suppressed by @ref{Password
|
|
handling}.
|
|
|
|
To accommodate user name/domain name syntax required by MS Windows
|
|
authorization, @value{tramp} provides for an extended syntax in
|
|
@code{user%domain} format (where user is username, @code{%} is the
|
|
percent symbol, and domain is the windows domain name). An example:
|
|
|
|
@example
|
|
@trampfn{smb, daniel%BIZARRE, melancholia, /daniel$$/.emacs}
|
|
@end example
|
|
|
|
where user @code{daniel} connects as a domain user to the SMB host
|
|
@code{melancholia} in the windows domain @code{BIZARRE} to edit
|
|
@file{.emacs} located in the home directory (share @code{daniel$}).
|
|
|
|
Alternatively, for local WINS users (as opposed to domain users),
|
|
substitute the domain name with the name of the local host in
|
|
UPPERCASE as shown here:
|
|
|
|
@example
|
|
@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}
|
|
@end example
|
|
|
|
where user @code{daniel} connects as local user to the SMB host
|
|
@code{melancholia} in the local domain @code{MELANCHOLIA} to edit
|
|
@file{.emacs} located in the home directory (share @code{daniel$}).
|
|
|
|
The domain name and user name are optional for @command{smbclient}
|
|
authentication. When user name is not specified, @command{smbclient}
|
|
uses the anonymous user (without prompting for password). This
|
|
behavior is unlike other @value{tramp} methods, where local user name
|
|
is substituted.
|
|
|
|
@option{smb} method is unavailable if @value{emacsname} is run under a
|
|
local user authentication context in MS Windows. However such users
|
|
can still access remote files using UNC file names instead of @value{tramp}:
|
|
|
|
@example
|
|
//melancholia/daniel$$/.emacs
|
|
@end example
|
|
|
|
UNC file name specification does not allow to specify a different user
|
|
name for authentication like the @command{smbclient} can.
|
|
|
|
|
|
@item @option{adb}
|
|
@cindex method adb
|
|
@cindex adb method
|
|
|
|
This method uses Android Debug Bridge program for accessing Android
|
|
devices. The Android Debug Bridge must be installed locally for
|
|
@value{tramp} to work. Some GNU/Linux distributions provide Android
|
|
Debug Bridge as an installation package. Alternatively, the program is
|
|
installed as part of the Android SDK@. @value{tramp} finds the
|
|
@command{adb} program either via the @env{PATH} environment variable
|
|
or the absolute path set in the variable @var{tramp-adb-program}.
|
|
|
|
@value{tramp} connects to Android devices with @option{adb} only when
|
|
the custom option @option{tramp-adb-connect-if-not-connected} is not
|
|
@code{nil}. Otherwise, the connection must be established outside
|
|
@value{emacsname}.
|
|
|
|
@value{tramp} does not require a host name part of the remote file
|
|
name when a single Android device is connected to @command{adb}.
|
|
@value{tramp} instead uses @file{@trampfn{adb, , ,}} as the default
|
|
name. @command{adb devices} shows available host names.
|
|
|
|
@option{adb} method normally does not need user name to authenticate
|
|
on the Andriod device because it runs under the @command{adbd}
|
|
process. But when a user name is specified, however, @value{tramp}
|
|
applies an @command{su} in the syntax. When authentication does not
|
|
succeed, especially on un-rooted Android devices, @value{tramp}
|
|
displays login errors.
|
|
|
|
For Andriod devices connected through TCP/IP, a port number can be
|
|
specified using @file{device#42} host name syntax or @value{tramp} can
|
|
use the default value as declared in @command{adb} command. Port
|
|
numbers are not applicable to Android devices connected through USB@.
|
|
|
|
@end table
|
|
|
|
|
|
@ifset emacsgvfs
|
|
@node GVFS based methods
|
|
@section GVFS based external methods
|
|
@cindex methods, gvfs
|
|
@cindex gvfs based methods
|
|
@cindex dbus
|
|
|
|
GVFS is the virtual file system for the Gnome Desktop,
|
|
@uref{http://en.wikipedia.org/wiki/GVFS}. Remote files on GVFS are
|
|
mounted locally through FUSE and @value{tramp} uses this locally
|
|
mounted directory internally.
|
|
|
|
@value{emacsname} uses the D-Bus mechanism to communicate with GVFS@.
|
|
@value{emacsname} must have the message bus system, D-Bus integration
|
|
active, @pxref{Top, , D-Bus, dbus}.
|
|
|
|
@table @asis
|
|
@item @option{afp}
|
|
@cindex method afp
|
|
@cindex afp method
|
|
|
|
This method is for connecting to remote hosts with the Apple Filing
|
|
Protocol for accessing files on Mac OS X volumes. @value{tramp} access
|
|
syntax requires a leading volume (share) name, for example:
|
|
@file{@trampfn{afp, user, host, /volume}}.
|
|
|
|
@item @option{dav}
|
|
@item @option{davs}
|
|
@cindex method dav
|
|
@cindex method davs
|
|
@cindex dav method
|
|
@cindex davs method
|
|
|
|
@option{dav} method provides access to WebDAV files and directories
|
|
based on standard protocols, such as HTTP@. @option{davs} does the same
|
|
but with SSL encryption. Both methods support the port numbers.
|
|
|
|
@item @option{obex}
|
|
@cindex method obex
|
|
@cindex obex method
|
|
|
|
OBEX is an FTP-like access protocol for cell phones and similar simple
|
|
devices. @value{tramp} supports OBEX over Bluetooth.
|
|
|
|
|
|
@item @option{sftp}
|
|
@cindex method sftp
|
|
@cindex sftp method
|
|
|
|
This method uses @command{sftp} in order to securely access remote
|
|
hosts. @command{sftp} is a more secure option for connecting to hosts
|
|
that for security reasons refuse @command{ssh} connections.
|
|
|
|
@item @option{synce}
|
|
@cindex method synce
|
|
@cindex synce method
|
|
|
|
@option{synce} method allows connecting to Windows Mobile devices. It
|
|
uses GVFS for mounting remote files and directories via FUSE and
|
|
requires the SYNCE-GVFS plugin.
|
|
|
|
@end table
|
|
|
|
@defopt tramp-gvfs-methods
|
|
@vindex tramp-gvfs-methods
|
|
This custom option is a list of external methods for GVFS@. By
|
|
default, this list includes @option{afp}, @option{dav}, @option{davs},
|
|
@option{obex}, @option{sftp} and @option{synce}. Other methods to
|
|
include are: @option{ftp} and @option{smb}.
|
|
@end defopt
|
|
@end ifset
|
|
|
|
|
|
@ifset emacsgw
|
|
@node Gateway methods
|
|
@section Gateway methods
|
|
@cindex methods, gateway
|
|
@cindex gateway methods
|
|
|
|
Gateway methods are for proxy host declarations (@pxref{Multi-hops})
|
|
so as to pass through firewalls and proxy servers. They are not like
|
|
the other methods that declare direct connections to a remote host.
|
|
|
|
A gateway method always comes with a port setting. @value{tramp}
|
|
targets the port number with the gateway method
|
|
@file{localhost#random_port} from where the firewall or proxy server
|
|
is accessed.
|
|
|
|
Gateway methods support user name and password declarations for
|
|
authenticating the corresponding firewall or proxy server. Such
|
|
authentication can be passed through only if granted access by system
|
|
administrators.
|
|
|
|
@table @asis
|
|
@item @option{tunnel}
|
|
@cindex method tunnel
|
|
@cindex tunnel method
|
|
|
|
This method implements an HTTP tunnel via the @command{CONNECT}
|
|
command (conforming to RFC 2616, 2817 specifications). Proxy servers
|
|
using HTTP version 1.1 or later protocol support this command.
|
|
|
|
For authentication, this protocol uses only @option{Basic
|
|
Authentication} (see RFC 2617). When no port number is specified, this
|
|
protocol defaults to @option{8080}.
|
|
|
|
|
|
@item @option{socks}
|
|
@cindex method socks
|
|
@cindex socks method
|
|
|
|
The @option{socks} method connects to SOCKSv5 servers (see RFC 1928)
|
|
and supports @option{Username/Password Authentication}.
|
|
|
|
The default port number for the socks server is @option{1080}, if not
|
|
specified otherwise.
|
|
|
|
@end table
|
|
@end ifset
|
|
|
|
|
|
@node Default Method
|
|
@section Selecting a default method
|
|
@cindex default method
|
|
@vindex tramp-default-method
|
|
@vindex tramp-default-method-alist
|
|
|
|
Default method is for transferring files. The variable
|
|
@code{tramp-default-method} sets it. @value{tramp} uses this variable
|
|
to determine the default method for tramp file names that do not have
|
|
one specified.
|
|
|
|
@lisp
|
|
(setq tramp-default-method "ssh")
|
|
@end lisp
|
|
|
|
Default methods for transferring files can be customized for specific
|
|
user and host combinations through the alist 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 host @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 details.
|
|
|
|
@noindent
|
|
External methods performance faster for large files.
|
|
|
|
@noindent
|
|
@xref{Inline methods}.
|
|
@xref{External methods}.
|
|
|
|
Choosing the access method also depends on the security environment.
|
|
For example, @option{rsh} and @option{telnet} methods that use clear
|
|
text password transfers are inappropriate for over the Internet
|
|
connections. Secure remote connections should use @option{ssh} that
|
|
provide encryption.
|
|
|
|
|
|
@subsection Which method to use?
|
|
@cindex choosing the right method
|
|
|
|
@value{tramp} provides maximum number of choices for maximum
|
|
flexibility. Choosing which method depends on the hosts, clients,
|
|
network speeds, and the security context.
|
|
|
|
Start by using an inline method.
|
|
|
|
External methods might be more efficient for large files, but most
|
|
@value{tramp} users edit small files more often than large files.
|
|
|
|
Enable compression, @var{tramp-inline-compress-start-size}, for a
|
|
performance boost for large files.
|
|
|
|
Since @command{ssh} has become the most common method of remote host
|
|
access and it has the most reasonable security protocols, use
|
|
@option{ssh} method. Typical @option{ssh} usage to edit the
|
|
@file{/etc/motd} file on the otherhost:
|
|
|
|
@example
|
|
@kbd{C-x C-f @trampfn{ssh, root, otherhost,/etc/motd} @key{RET}}
|
|
@end example
|
|
|
|
If @option{ssh} is unavailable for whatever reason, look for other
|
|
obvious options. For Windows, try the @option{plink} method. For
|
|
Kerberos, try @option{krlogin}.
|
|
|
|
For editing local files as @option{su} or @option{sudo} methods, try
|
|
the shortened syntax of @samp{root}:
|
|
|
|
@example
|
|
@kbd{C-x C-f @trampfn{su, , , /etc/motd} @key{RET}}
|
|
@end example
|
|
|
|
For editing large files, @option{scp} is faster than @option{ssh}.
|
|
@option{pscp} is faster than @option{plink}. But this speed
|
|
improvement is not always true.
|
|
|
|
|
|
@node Default User
|
|
@section Selecting a default user
|
|
@cindex default user
|
|
@vindex tramp-default-user
|
|
@vindex tramp-default-user-alist
|
|
|
|
@value{tramp} file name can omit the user name part since
|
|
@value{tramp} substitutes the currently logged-in user name. However
|
|
this substitution can be overridden with @code{tramp-default-user}.
|
|
For example:
|
|
|
|
@lisp
|
|
(setq tramp-default-user "root")
|
|
@end lisp
|
|
|
|
Instead of a single default user, @code{tramp-default-user-alist}
|
|
allows multiple default user values based on access method or host
|
|
name combinations. The alist can hold multiple values. For example, to
|
|
use the @samp{john} as the default user for the domain
|
|
@samp{somewhere.else} only:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-default-user-alist
|
|
'("ssh" ".*\\.somewhere\\.else\\'" "john"))
|
|
@end lisp
|
|
|
|
@noindent
|
|
See the documentation for the variable @code{tramp-default-user-alist}
|
|
for more details.
|
|
|
|
A Caution: @value{tramp} will override any default user specified in
|
|
the configuration files outside @value{emacsname}, such as
|
|
@file{~/.ssh/config}. To stop @value{tramp} from applying the default
|
|
value, set the corresponding alist entry to nil:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-default-user-alist
|
|
'("ssh" "\\`here\\.somewhere\\.else\\'" nil))
|
|
@end lisp
|
|
|
|
The last entry in @code{tramp-default-user-alist} should be reserved
|
|
for catch-all or most often used login.
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-default-user-alist
|
|
'(nil nil "jonas") t)
|
|
@end lisp
|
|
|
|
|
|
@node Default Host
|
|
@section Selecting a default host
|
|
@cindex default host
|
|
@vindex tramp-default-host
|
|
@vindex tramp-default-host-alist
|
|
|
|
When host name is omitted, @value{tramp} substitutes the value from
|
|
the @code{tramp-default-host} variable. It is initially populated with
|
|
the local hostname where @value{emacsname} is running. Both the
|
|
default user and default host can be overridden as follows:
|
|
|
|
@lisp
|
|
(setq tramp-default-user "john"
|
|
tramp-default-host "target")
|
|
@end lisp
|
|
|
|
With both defaults set, @samp{@trampfn{ssh, , ,}} will connect
|
|
@value{tramp} to John's home directory on target.
|
|
|
|
@ifset emacs
|
|
@strong{Note} @samp{/::} won't work, because @samp{/:} is the prefix
|
|
for quoted file names.
|
|
@end ifset
|
|
|
|
Instead of a single default host, @code{tramp-default-host-alist}
|
|
allows multiple default host values based on access method or user
|
|
name combinations. The alist can hold multiple values. While
|
|
@code{tramp-default-host} is sufficient in most cases, some methods,
|
|
like @option{adb}, require defaults overwritten.
|
|
|
|
@noindent
|
|
See the documentation for the variable @code{tramp-default-host-alist}
|
|
for more details.
|
|
|
|
|
|
@node Multi-hops
|
|
@section Connecting to a remote host using multiple hops
|
|
@cindex multi-hop
|
|
@cindex proxy hosts
|
|
|
|
Multi-hops are methods to reach hosts behind firewalls or to reach the
|
|
outside world from inside a bastion host. With multi-hops,
|
|
@value{tramp} can negotiate these hops with the appropriate user/host
|
|
authentication at each hop. All methods until now have been the single
|
|
hop kind, where the start and end points of the connection did not
|
|
have intermediate check points.
|
|
|
|
@defopt tramp-default-proxies-alist
|
|
@vindex tramp-default-proxies-alist
|
|
@option{tramp-default-proxies-alist} specifies proxy hosts to pass
|
|
through. This variable is list of triples consisting of (@var{host}
|
|
@var{user} @var{proxy}).
|
|
|
|
The first match is the proxy host through which passes the file name
|
|
and the target host matching @var{user}@@@var{host}. @var{host} and
|
|
@var{user} are regular expressions or @code{nil}, interpreted as a
|
|
regular expression which always matches.
|
|
|
|
@var{proxy} is a literal @value{tramp} file name whose local name part
|
|
is ignored, and the method and user name parts are optional.
|
|
|
|
@ifset emacsgw
|
|
The method must be an inline or gateway method (@pxref{Inline
|
|
methods}, @pxref{Gateway methods}).
|
|
@end ifset
|
|
@ifclear emacsgw
|
|
The method must be an inline method (@pxref{Inline methods}).
|
|
@end ifclear
|
|
If @var{proxy} is @code{nil}, no additional hop is required reaching
|
|
@var{user}@@@var{host}.
|
|
|
|
For example, to pass through the host @samp{bastion.your.domain} as
|
|
user @samp{bird} to reach remote hosts outside the local domain:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-default-proxies-alist
|
|
'("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}"))
|
|
(add-to-list 'tramp-default-proxies-alist
|
|
'("\\.your\\.domain\\'" nil nil))
|
|
@end lisp
|
|
|
|
@strong{Note}: @code{add-to-list} adds elements at the beginning of a
|
|
list. Therefore, most relevant rules must come last in the list.
|
|
|
|
Proxy hosts can be cascaded in the alist. If there is another host
|
|
called @samp{jump.your.domain}, which is the only host allowed to
|
|
connect to @samp{bastion.your.domain}, then:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-default-proxies-alist
|
|
'("\\`bastion\\.your\\.domain\\'"
|
|
"\\`bird\\'"
|
|
"@trampfn{ssh, , jump.your.domain,}"))
|
|
@end lisp
|
|
|
|
@var{proxy} can take patterns @code{%h} or @code{%u} for @var{host} or
|
|
@var{user} respectively.
|
|
|
|
To login as @samp{root} on remote hosts in the domain
|
|
@samp{your.domain}, but login as @samp{root} is disabled for non-local
|
|
access, then use this alist entry:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-default-proxies-alist
|
|
'("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
|
|
@end lisp
|
|
|
|
Opening @file{@trampfn{sudo, , randomhost.your.domain,}} first
|
|
connects to @samp{randomhost.your.domain} via @code{ssh} under your
|
|
account name, and then perform @code{sudo -u root} on that host.
|
|
|
|
It is key for the sudo method in the above example to be applied on
|
|
the host after reaching it and not on the local host.
|
|
|
|
@var{host}, @var{user} and @var{proxy} can also take Lisp forms. These
|
|
forms when evaluated must return either a string or @code{nil}.
|
|
|
|
To generalize (from the previous example): For all hosts, except my
|
|
local one, first connect via @command{ssh}, and then apply
|
|
@command{sudo -u root}:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-default-proxies-alist
|
|
'(nil "\\`root\\'" "@trampfn{ssh, , %h,}"))
|
|
(add-to-list 'tramp-default-proxies-alist
|
|
'((regexp-quote (system-name)) nil nil))
|
|
@end lisp
|
|
|
|
The above configuration allows @value{tramp} connection as @samp{root}
|
|
to remote Ubuntu hosts.
|
|
|
|
@ifset emacsgw
|
|
@code{tramp-default-proxies-alist} is also used for passing through
|
|
firewalls or proxy servers.
|
|
|
|
For example, the local host @samp{proxy.your.domain} on port 3128
|
|
serves as HTTP proxy to the outer world. User has access rights to
|
|
another proxy server on @samp{host.other.domain}.@footnote{HTTP tunnels
|
|
are intended for secure SSL/TLS communication. Therefore, many proxy
|
|
servers restrict the tunnels to related target ports. You might need
|
|
to run your ssh server on your target host @samp{host.other.domain} on
|
|
such a port, like 443 (https). See
|
|
@uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall} for
|
|
discussion of ethical issues.} Then the configuration is:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-default-proxies-alist
|
|
'("\\`host\\.other\\.domain\\'" nil
|
|
"@trampfn{tunnel, , proxy.your.domain#3128,}"))
|
|
@end lisp
|
|
|
|
Gateway methods in a multiple hop chain can be declared only as the first hop.
|
|
@end ifset
|
|
@end defopt
|
|
|
|
Passing through hops involves dealing with restricted shells, such as
|
|
@command{rbash}. If @value{tramp} is made aware, then it would use
|
|
them for proxies only.
|
|
|
|
@defopt tramp-restricted-shell-hosts-alist
|
|
@vindex tramp-restricted-shell-hosts-alist
|
|
An alist of regular expressions of hosts running restricted shells,
|
|
such as @command{rbash}. @value{tramp} will then use them only as
|
|
proxies.
|
|
|
|
To specify the bastion host from the example above as running a
|
|
restricted shell:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-restricted-shell-hosts-alist
|
|
"\\`bastion\\.your\\.domain\\'")
|
|
@end lisp
|
|
@end defopt
|
|
|
|
|
|
@node Customizing Methods
|
|
@section Using Non-Standard Methods
|
|
@cindex customizing methods
|
|
@cindex using non-standard methods
|
|
@cindex create your own methods
|
|
|
|
The @code{tramp-methods} variable currently has an exhaustive list of
|
|
predefined methods. Any part of this list can be modified with more
|
|
suitable settings. Refer 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
|
|
|
|
@code{tramp-completion-function-alist} uses predefined files for user
|
|
and host name completion (@pxref{File name completion}). For each
|
|
method, it keeps a set of configuration files and a function that can
|
|
parse that file. Each entry in @code{tramp-completion-function-alist}
|
|
is of the form (@var{method} @var{pair1} @var{pair2} @dots{}).
|
|
|
|
Each @var{pair} is composed of (@var{function} @var{file}).
|
|
@var{function} is responsible for extracting 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} for host names.
|
|
|
|
@item @code{tramp-parse-passwd}
|
|
@findex tramp-parse-passwd
|
|
|
|
A function which parses @file{/etc/passwd} files for user names.
|
|
|
|
@item @code{tramp-parse-netrc}
|
|
@findex tramp-parse-netrc
|
|
|
|
A function which parses @file{~/.netrc} and @file{~/.authinfo}-style files.
|
|
|
|
@end table
|
|
|
|
To keep a custom file with custom data in a custom structure, a custom
|
|
function has to be provided. This function must meet the following
|
|
conventions:
|
|
|
|
@defun my-tramp-parse file
|
|
@var{file} must be either a file on the host, or @code{nil}. The
|
|
function must return a list of (@var{user} @var{host}), which are
|
|
taken as candidates for completion for user and host names.
|
|
|
|
Example:
|
|
@example
|
|
(my-tramp-parse "~/.my-tramp-hosts")
|
|
|
|
@result{} ((nil "toto") ("daniel" "melancholia"))
|
|
@end example
|
|
@end defun
|
|
|
|
|
|
@node Password handling
|
|
@section Reusing passwords for several connections
|
|
@cindex passwords
|
|
|
|
To avoid repeated prompts for passwords, consider native caching
|
|
mechanisms, such as @command{ssh-agent} for @option{ssh}-like
|
|
methods, or @command{pageant} for @option{plink}-like methods.
|
|
|
|
@value{tramp} offers alternatives when native solutions cannot meet
|
|
the need.
|
|
|
|
|
|
@anchor{Using an authentication file}
|
|
@subsection Using an authentication file
|
|
@vindex auth-sources
|
|
|
|
The package @file{auth-source.el}, originally developed for No Gnus,
|
|
reads passwords from different sources, @xref{Help for users, ,
|
|
auth-source, auth}. The default authentication file is
|
|
@file{~/.authinfo.gpg}, but this can be changed via the variable
|
|
@code{auth-sources}.
|
|
|
|
@noindent
|
|
A typical entry in the authentication file:
|
|
|
|
@example
|
|
machine melancholia port scp login daniel password geheim
|
|
@end example
|
|
|
|
The port can take any @value{tramp} method (@pxref{Inline methods},
|
|
@pxref{External methods}). Omitting port values matches all
|
|
@value{tramp} methods.
|
|
|
|
Setting @code{auth-source-debug} to @code{t} to debug messages.
|
|
|
|
|
|
@anchor{Caching passwords}
|
|
@subsection Caching passwords
|
|
|
|
@value{tramp} can cache passwords as entered and reuse when needed for
|
|
the same user or host name independent of the access method.
|
|
|
|
@vindex password-cache-expiry
|
|
|
|
@code{password-cache-expiry} sets the duration (in seconds) the
|
|
passwords are remembered. Passwords are never saved permanently nor
|
|
can they extend beyond the lifetime of the current @value{emacsname}
|
|
session. Set @code{password-cache-expiry} to @code{nil} to disable
|
|
expiration.
|
|
|
|
@vindex password-cache
|
|
|
|
Set @code{password-cache} to @code{nil} to disable password caching.
|
|
|
|
@strong{Implementation Note}: password caching depends on
|
|
@file{password-cache.el} package. @value{tramp} activates password
|
|
caching only if @value{tramp} can discover, while @value{emacsname} is
|
|
loading, the package through @code{load-path}.
|
|
|
|
@ifset installchapter
|
|
@file{password.el} is available from No Gnus or from the @value{tramp}
|
|
@file{contrib} directory, see @ref{Installation parameters}.
|
|
@end ifset
|
|
|
|
|
|
@node Connection caching
|
|
@section Reusing connection related information
|
|
@cindex caching
|
|
@vindex tramp-persistency-file-name
|
|
|
|
For faster initial connection times, @value{tramp} stores previous
|
|
connection properties in a file specified by the variable
|
|
@code{tramp-persistency-file-name}.
|
|
|
|
The default file name for @code{tramp-persistency-file-name} is:
|
|
@ifset emacs
|
|
@file{~/.emacs.d/tramp}.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@file{~/.xemacs/tramp}.
|
|
@end ifset
|
|
|
|
@value{tramp} reads this file during @value{emacsname} startup, and
|
|
writes to it when exiting @value{emacsname}. Delete this file for
|
|
@value{tramp} to recreate a new one on next @value{emacsname} startup.
|
|
|
|
Set @code{tramp-persistency-file-name} to @code{nil} to disable
|
|
storing connections persistently.
|
|
|
|
To reuse connection information from the persistent list,
|
|
@value{tramp} needs to uniquely identify every host. However in some
|
|
cases, two different connections may result in the same persistent
|
|
information. For example, connecting to a host using @command{ssh} and
|
|
connecting to the same host through @code{sshd} on port 3001. Both
|
|
access methods result in nearly identical persistent specifications
|
|
@file{@trampfn{ssh, , localhost,}} and @file{@trampfn{ssh, ,
|
|
localhost#3001,}}.
|
|
|
|
Changing host names could avoid duplicates. One way is to add a
|
|
@option{Host} section in @file{~/.ssh/config} (@pxref{Frequently Asked
|
|
Questions}). Another way is to apply multiple hops (@pxref{Multi-hops}).
|
|
|
|
When @value{tramp} detects a change in the operating system version in
|
|
a remote host (via the command @command{uname -sr}), it flushes all
|
|
connection related information for that host and creates a new entry.
|
|
|
|
|
|
@node Predefined connection information
|
|
@section Setting own connection related information
|
|
@vindex tramp-connection-properties
|
|
|
|
For more precise customization, parameters specified by
|
|
@code{tramp-methods} can be overwritten manually.
|
|
|
|
Set @code{tramp-connection-properties} to manually override
|
|
@code{tramp-methods}. Properties in this list are in the form
|
|
@code{(@var{regexp} @var{property} @var{value})}. @var{regexp} matches
|
|
remote file names. Use @code{nil} to match all. @var{property} is the
|
|
property's name, and @var{value} is the property's value.
|
|
|
|
@var{property} is any method specific parameter contained in
|
|
@code{tramp-methods}. The parameter key in @code{tramp-methods} is a
|
|
symbol name @code{tramp-<foo>}. To overwrite that property, use the
|
|
string @samp{<foo>} for @var{property}. For example, this changes the
|
|
remote shell:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-connection-properties
|
|
(list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
|
|
"remote-shell" "/bin/ksh"))
|
|
(add-to-list 'tramp-connection-properties
|
|
(list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
|
|
"remote-shell-login" '("-")))
|
|
@end lisp
|
|
|
|
The parameters @code{tramp-remote-shell} and
|
|
@code{tramp-remote-shell-login} in @code{tramp-methods} now have new
|
|
values for the remote host.
|
|
|
|
@var{property} could also be any property found in
|
|
@code{tramp-persistency-file-name}.
|
|
|
|
To get around how restricted shells randomly drop connections, set the
|
|
special property @samp{busybox}. For example:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-connection-properties
|
|
(list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
|
|
"busybox" t))
|
|
@end lisp
|
|
|
|
|
|
@node Remote programs
|
|
@section How @value{tramp} finds and uses programs on the remote host
|
|
|
|
@value{tramp} requires access to and rights to several commands on
|
|
remote hosts: @command{ls}, @command{test}, @command{find} and
|
|
@command{cat}.
|
|
|
|
Besides there are other required programs for @ref{Inline methods} and
|
|
@ref{External methods} of connection.
|
|
|
|
To improve performance and accuracy of remote file access,
|
|
@value{tramp} uses @command{perl} (or @command{perl5}) and
|
|
@command{grep} when available.
|
|
|
|
@defopt tramp-remote-path
|
|
@vindex tramp-remote-path
|
|
@vindex tramp-default-remote-path
|
|
@vindex tramp-own-remote-path
|
|
@option{tramp-remote-path} specifies which remote directory paths
|
|
@value{tramp} can search for @ref{Remote programs}.
|
|
|
|
@value{tramp} uses standard defaults, such as @file{/bin} and
|
|
@file{/usr/bin}, which are reasonable for most hosts. To accommodate
|
|
differences in hosts and paths, for example, @file{/bin:/usr/bin} on
|
|
Debian GNU/Linux or
|
|
@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin} on
|
|
Solaris, @value{tramp} queries the remote host with @command{getconf
|
|
PATH} and updates the symbol @code{tramp-default-remote-path}.
|
|
|
|
For instances where hosts keep obscure locations for paths for
|
|
security reasons, manually add such paths to local @file{.emacs} as
|
|
shown below for @value{tramp} to use when connecting.
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
|
|
@end lisp
|
|
|
|
Another way to find the remote path is to use the path assigned to the
|
|
remote user by the remote host. @value{tramp} does not normally retain
|
|
this remote path after logging. However, @code{tramp-own-remote-path}
|
|
preserves the path value, which can be used to update
|
|
@code{tramp-remote-path}.
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-remote-path 'tramp-own-remote-path)
|
|
@end lisp
|
|
@end defopt
|
|
|
|
When remote search paths are changed, local @value{tramp} caches must
|
|
be recomputed. To force @value{tramp} to recompute afresh, exit
|
|
@value{emacsname}, remove the persistent file (@pxref{Connection
|
|
caching}), and restart @value{emacsname}.
|
|
|
|
|
|
@node Remote shell setup
|
|
@section Remote shell setup hints
|
|
@cindex remote shell setup
|
|
@cindex @file{.profile} file
|
|
@cindex @file{.login} file
|
|
@cindex shell init files
|
|
|
|
@value{tramp} checks for the availability of standard programs in the
|
|
usual locations. Common tactics include successively trying
|
|
@command{test -e}, @command{/usr/bin/test -e}, and @command{/bin/test
|
|
-e}. @command{ls -d} is another approach. But these approaches do not
|
|
help with these new login patterns.
|
|
|
|
When @value{tramp} encounters two-factor logins or additional challenge
|
|
questions, such as entering birth date or security code or passphrase,
|
|
@value{tramp} needs a few more configuration steps to accommodate
|
|
them.
|
|
|
|
The difference between a password prompt and a passphrase prompt is
|
|
that the password for completing the login while the passphrase is
|
|
for authorizing access to local authentication information, such as
|
|
the ssh key.
|
|
|
|
There is no one configuration to accommodate all the variations in
|
|
login security, especially not the exotic ones. However, @value{tramp}
|
|
provides a few tweaks to address the most common ones.
|
|
|
|
@table @asis
|
|
@item @var{tramp-shell-prompt-pattern}
|
|
@vindex tramp-shell-prompt-pattern
|
|
|
|
@code{tramp-shell-prompt-pattern} is for remote login shell prompt,
|
|
which may not be the same as the local login shell prompt,
|
|
@code{shell-prompt-pattern}. Since most hosts use identical prompts,
|
|
@value{tramp} sets a similar default value for both prompts.
|
|
|
|
@item @var{tramp-password-prompt-regexp}
|
|
@item @var{tramp-wrong-passwd-regexp}
|
|
@vindex tramp-password-prompt-regexp
|
|
@vindex tramp-wrong-passwd-regexp
|
|
|
|
@value{tramp} uses @var{tramp-password-prompt-regexp} to distinguish
|
|
between prompts for passwords and prompts for passphrases. By default,
|
|
@var{tramp-password-prompt-regexp} handles the detection in English
|
|
language environments. See a localization example below:
|
|
|
|
@lisp
|
|
(setq
|
|
tramp-password-prompt-regexp
|
|
(concat
|
|
"^.*"
|
|
(regexp-opt
|
|
'("passphrase" "Passphrase"
|
|
;; English
|
|
"password" "Password"
|
|
;; Deutsch
|
|
"passwort" "Passwort"
|
|
;; Français
|
|
"mot de passe" "Mot de passe") t)
|
|
".*:\0? *"))
|
|
@end lisp
|
|
|
|
Similar localization may be necessary for handling wrong password
|
|
prompts, for which @value{tramp} uses @var{tramp-wrong-passwd-regexp}.
|
|
|
|
@item @command{tset} and other questions
|
|
@cindex Unix command tset
|
|
@cindex tset Unix command
|
|
@vindex tramp-terminal-type
|
|
|
|
To suppress inappropriate prompts for terminal type, @value{tramp}
|
|
sets the @env{TERM} to @code{dumb} before the remote login process
|
|
begins via the variable @code{tramp-terminal-type}. This will silence
|
|
common @command{tset} related prompts.
|
|
|
|
@value{tramp}'s strategy for handling such prompts (commonly triggered
|
|
from login scripts on remote hosts) is to set the environment
|
|
variables so that no prompts interrupt the shell initialization
|
|
process.
|
|
|
|
@vindex tramp-actions-before-shell
|
|
|
|
An alternative approach is to configure @value{tramp} with strings
|
|
that can identify such questions using
|
|
@code{tramp-actions-before-shell}. Example:
|
|
|
|
@lisp
|
|
(defconst my-tramp-prompt-regexp
|
|
(concat (regexp-opt '("Enter the birth date of your mother:") t)
|
|
"\\s-*")
|
|
"Regular expression matching my login prompt question.")
|
|
|
|
(defun my-tramp-action (proc vec)
|
|
"Enter \"19000101\" in order to give a correct answer."
|
|
(save-window-excursion
|
|
(with-current-buffer (tramp-get-connection-buffer vec)
|
|
(tramp-message vec 6 "\n%s" (buffer-string))
|
|
(tramp-send-string vec "19000101"))))
|
|
|
|
(add-to-list 'tramp-actions-before-shell
|
|
'(my-tramp-prompt-regexp my-tramp-action))
|
|
@end lisp
|
|
|
|
|
|
@item Conflicting names for users and variables in @file{.profile}
|
|
|
|
When a user name is the same as a variable name in a local file, such
|
|
as @file{.profile}, then @value{tramp} may send incorrect values for
|
|
environment variables. To avoid incorrect values, change the local
|
|
variable name to something different from the user name. For example,
|
|
if the user name is @env{FRUMPLE}, then change the variable name to
|
|
@env{FRUMPLE_DIR}.
|
|
|
|
|
|
@item Non-Bourne commands in @file{.profile}
|
|
|
|
When the remote host's @file{.profile} is also used for shells other
|
|
than Bourne shell, then some incompatible syntaxes for commands in
|
|
@file{.profile} may trigger errors in Bourne shell on the host and may
|
|
not complete client's @value{tramp} connections.
|
|
|
|
One example of a Bourne shell incompatible syntax in @file{.profile}:
|
|
using @command{export FOO=bar} instead of @command{FOO=bar; export
|
|
FOO}. After remote login, @value{tramp} will trigger an error during
|
|
its execution of @command{/bin/sh} on the remote host because Bourne
|
|
shell does not recognize the export command as entered in
|
|
@file{.profile}.
|
|
|
|
Likewise, (@code{~}) character in paths will cause errors because
|
|
Bourne shell does not do (@code{~}) character expansions.
|
|
|
|
One approach to avoiding these incompatibilities is to make all
|
|
commands in @file{~/.shrc} and @file{~/.profile} Bourne shell
|
|
compatible so @value{tramp} can complete connections to that remote.
|
|
To accommodate using non-Bourne shells on that remote, use other
|
|
shell-specific config files. For example, bash can use
|
|
@file{~/.bash_profile} and ignore @file{.profile}.
|
|
|
|
|
|
@item Interactive shell prompt
|
|
|
|
@value{tramp} redefines the remote shell prompt internally for robust
|
|
parsing. This redefinition affects the looks of a prompt in an
|
|
interactive remote shell through commands, such as @kbd{M-x
|
|
shell}. Such prompts, however, can be reset to something more readable
|
|
and recognizable using these @value{tramp} variables.
|
|
|
|
@value{tramp} sets the @env{INSIDE_EMACS} variable in the startup
|
|
script file @file{~/.emacs_SHELLNAME}.
|
|
|
|
@env{SHELLNAME} is @code{bash} or equivalent shell names. Change it by
|
|
setting the environment variable @env{ESHELL} in the @file{.emacs} as
|
|
follows:
|
|
|
|
@lisp
|
|
(setenv "ESHELL" "bash")
|
|
@end lisp
|
|
|
|
Then re-set the prompt string in @file{~/.emacs_SHELLNAME} as follows:
|
|
|
|
@example
|
|
# Reset the prompt for remote Tramp shells.
|
|
if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then
|
|
PS1="[\u@@\h \w]$ "
|
|
fi
|
|
@end example
|
|
|
|
@ifinfo
|
|
@ifset emacs
|
|
@xref{Interactive Shell, , , @value{emacsdir}}.
|
|
@end ifset
|
|
@end ifinfo
|
|
|
|
@item @command{busybox} / @command{nc}
|
|
@cindex Unix command nc
|
|
@cindex nc Unix command
|
|
|
|
@value{tramp}'s @option{nc} method uses the @command{nc} command to
|
|
install and execute a listener as follows (see @code{tramp-methods}):
|
|
|
|
@example
|
|
# nc -l -p 42
|
|
@end example
|
|
|
|
The above command-line syntax has changed with @command{busybox}
|
|
versions. If @command{nc} refuses the @command{-p} parameter, then
|
|
overwrite as follows:
|
|
|
|
@lisp
|
|
(add-to-list
|
|
'tramp-connection-properties
|
|
`(,(regexp-quote "192.168.0.1") "remote-copy-args" (("-l") ("%r"))))
|
|
@end lisp
|
|
|
|
@noindent
|
|
where @samp{192.168.0.1} is the remote host IP address
|
|
(@pxref{Predefined connection information}).
|
|
|
|
@end table
|
|
|
|
|
|
@node Android shell setup
|
|
@section Android shell setup hints
|
|
@cindex android shell setup
|
|
|
|
@value{tramp} uses the @option{adb} method to access Android
|
|
devices. Android devices provide a restricted shell access through an
|
|
USB connection. The local host must have Andriod SDK installed.
|
|
|
|
Applications such as @code{SSHDroid} that run @command{sshd} process
|
|
on the Android device can accept any @option{ssh}-based methods
|
|
provided these settings are adjusted:
|
|
|
|
@code{sh} must be specified for remote shell since Android devices do
|
|
not provide @code{/bin/sh}. @code{sh} will then invoke whatever shell is
|
|
installed on the device with this setting:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-connection-properties
|
|
(list (regexp-quote "192.168.0.26") "remote-shell" "sh"))
|
|
@end lisp
|
|
|
|
@noindent
|
|
where @samp{192.168.0.26} is the Android device's IP address.
|
|
(@pxref{Predefined connection information}).
|
|
|
|
@value{tramp} requires preserving @env{PATH} environment variable from
|
|
user settings. Android devices prefer @file{/system/xbin} path over
|
|
@file{/system/bin}. Both of these are set as follows:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-remote-path 'tramp-own-remote-path)
|
|
(add-to-list 'tramp-remote-path "/system/xbin")
|
|
@end lisp
|
|
|
|
@noindent
|
|
When the Android device is not @samp{rooted}, specify a writable
|
|
directory for temporary files:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-remote-process-environment "TMPDIR=$HOME")
|
|
@end lisp
|
|
|
|
@noindent
|
|
Open a remote connection with the command @kbd{C-x C-f @trampfn{ssh, ,
|
|
192.168.0.26#2222, }}, where @command{sshd} is listening on port
|
|
@samp{2222}.
|
|
|
|
To add a corresponding entry to the @file{~/.ssh/config} file
|
|
(recommended), use this:
|
|
|
|
@example
|
|
Host android
|
|
HostName 192.168.0.26
|
|
User root
|
|
Port 2222
|
|
@end example
|
|
|
|
@noindent
|
|
To use the host name @samp{android} instead of the IP address shown in
|
|
the previous example, fix the connection properties as follows:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-connection-properties
|
|
(list (regexp-quote "android") "remote-shell" "sh"))
|
|
@end lisp
|
|
|
|
@noindent
|
|
Open a remote connection with a more concise command @kbd{C-x C-f
|
|
@trampfn{ssh, , android, }}.
|
|
|
|
|
|
@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
|
|
|
|
To avoid @value{tramp} from saving backup files owned by root to
|
|
locations accessible to others, default backup settings in
|
|
@ifset emacs
|
|
@code{backup-directory-alist}
|
|
@end ifset
|
|
@ifset xemacs
|
|
@code{bkup-backup-directory-info}
|
|
@end ifset
|
|
have to be altered.
|
|
|
|
Here's a scenario where files could be inadvertently
|
|
exposed. @value{emacsname} by default writes backup files to the same
|
|
directory as the original files unless changed to another location,
|
|
such as @file{~/.emacs.d/backups/}. Such a directory will also be used
|
|
by default by @value{tramp} when using, say, a restricted file
|
|
@file{@trampfn{su, root, localhost, /etc/secretfile}}. The backup file
|
|
of the secretfile is now owned by the user logged in from tramp and
|
|
not root.
|
|
|
|
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.
|
|
|
|
To ``turns off'' the backup feature for @value{tramp} files and stop
|
|
@value{tramp} from saving to the backup directory, use this:
|
|
|
|
@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
|
|
|
|
@ifset emacs
|
|
@noindent
|
|
Disabling backups can be targetted to just @option{su} and
|
|
@option{sudo} methods:
|
|
|
|
@lisp
|
|
(setq backup-enable-predicate
|
|
(lambda (name)
|
|
(and (normal-backup-enable-predicate name)
|
|
(not
|
|
(let ((method (file-remote-p name 'method)))
|
|
(when (stringp method)
|
|
(member method '("su" "sudo"))))))))
|
|
@end lisp
|
|
@end ifset
|
|
|
|
Another option is to create better backup file naming with user and
|
|
host names prefixed to the file name. For example, transforming
|
|
@file{/etc/secretfile} to
|
|
@file{~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile}, set the
|
|
@value{tramp} variable
|
|
@ifset emacs
|
|
@code{tramp-backup-directory-alist}
|
|
@end ifset
|
|
@ifset xemacs
|
|
@code{tramp-bkup-backup-directory-info}
|
|
@end ifset
|
|
from the existing variable
|
|
@ifset emacs
|
|
@code{backup-directory-alist}.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@code{bkup-backup-directory-info}.
|
|
@end ifset
|
|
|
|
Then @value{tramp} backs up to a file name that is transformed with a
|
|
prefix consisting of the DIRECTORY name. This file name prefixing
|
|
happens only when the DIRECTORY is an absolute local file name.
|
|
|
|
@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{@trampfn{su, root, localhost,
|
|
/etc/secretfile}} would be
|
|
@ifset emacs
|
|
@file{@trampfn{su, root, localhost,
|
|
~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
|
|
@end ifset
|
|
@ifset xemacs
|
|
@file{@trampfn{su, root, localhost,
|
|
~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}
|
|
@end ifset
|
|
|
|
Just as for backup files, similar issues of file naming affect
|
|
auto-saving @value{tramp} files.
|
|
@ifset emacs
|
|
Auto-saved files are saved in the directory specified by the variable
|
|
@code{auto-save-file-name-transforms}. By default this is set to the
|
|
local temporary directory. But in some versions of Debian GNU/Linux,
|
|
this points to the source directory where the @value{emacsname} was
|
|
compiled. Reset such values to a valid directory.
|
|
|
|
Set @code{auto-save-file-name-transforms} to @code{nil} to save
|
|
auto-saved files to the same directory as the original file.
|
|
|
|
Alternatively, set the variable @code{tramp-auto-save-directory} to
|
|
direct all auto saves to that location.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@code{auto-save-directory} can also be used here instead of other
|
|
locations specfied above.
|
|
@end ifset
|
|
|
|
@node Windows setup hints
|
|
@section Issues with Cygwin ssh
|
|
@cindex Cygwin, issues
|
|
|
|
This section is incomplete. Please share your solutions.
|
|
|
|
@cindex method sshx with Cygwin
|
|
@cindex sshx method with Cygwin
|
|
|
|
Cygwin's @command{ssh} works only with a Cygwin version of
|
|
@value{emacsname}. To check for compatibility: type @kbd{M-x eshell}, and
|
|
start @kbd{ssh test.host}. Incompatbilities trigger this message:
|
|
|
|
@example
|
|
Pseudo-terminal will not be allocated because stdin is not a terminal.
|
|
@end example
|
|
|
|
Some older versions of Cygwin's @command{ssh} work with the
|
|
@option{sshx} access method. Consult Cygwin's FAQ at
|
|
@uref{http://cygwin.com/faq/} for details.
|
|
|
|
|
|
@cindex method scpx with Cygwin
|
|
@cindex scpx method with Cygwin
|
|
|
|
When using the @option{scpx} access method, @value{emacsname} may call
|
|
@command{scp} with Windows file naming, such as @code{c:/foo}. But
|
|
the version of @command{scp} that is installed with Cygwin does not
|
|
know about Windows file naming, which causes it to incorrectly look
|
|
for a host named @code{c}.
|
|
|
|
A workaround: write a wrapper script for @option{scp} to convert
|
|
Windows file names to Cygwin file names.
|
|
|
|
@cindex Cygwin and ssh-agent
|
|
@cindex SSH_AUTH_SOCK and @value{emacsname} on Windows
|
|
|
|
When using the @command{ssh-agent} on Windows for password-less
|
|
interaction, @option{ssh} methods depend on the environment variable
|
|
@env{SSH_AUTH_SOCK}. But this variable is not set when
|
|
@value{emacsname} is started from a Desktop shortcut and
|
|
authentication fails.
|
|
|
|
One workaround is to use a Windows based SSH Agent, such as
|
|
Pageant. It is part of the Putty Suite of tools.
|
|
|
|
The fallback is to start @value{emacsname} from a shell.
|
|
|
|
|
|
@node Usage
|
|
@chapter Using @value{tramp}
|
|
@cindex using @value{tramp}
|
|
|
|
@value{tramp} operates transparently, accessing remote files as if
|
|
they are local. However, @value{tramp} employs a formalized remote
|
|
file naming syntax to perform its functions transparently. This
|
|
syntax consists of many parts specifying access methods,
|
|
authentication, host names, and file names.
|
|
@ifset emacs
|
|
@value{ftppackagename} uses a similar syntax.
|
|
@end ifset
|
|
|
|
@cindex type-ahead
|
|
|
|
Unlike opening local files in @value{emacsname}, which are
|
|
instantaneous, opening remote files in @value{tramp} is slower at
|
|
first. Sometimes there is a noticable delay before the prompts for
|
|
passwords or authentication appear in the minibuffer. Hitting
|
|
@kbd{@key{RET}} or other keys during this gap will be processed by
|
|
@value{emacsname}. This type-ahead facility is a feature of
|
|
@value{emacsname} that may cause missed prompts when using
|
|
@value{tramp}.
|
|
|
|
@menu
|
|
* File name Syntax:: @value{tramp} file name conventions.
|
|
* File name completion:: File name completion.
|
|
* Ad-hoc multi-hops:: Declaring multiple hops in the file name.
|
|
* Remote processes:: Integration with other @value{emacsname} packages.
|
|
* Cleanup remote connections:: Cleanup remote connections.
|
|
@end menu
|
|
|
|
|
|
@node File name Syntax
|
|
@section @value{tramp} file name conventions
|
|
@cindex file name syntax
|
|
@cindex file name examples
|
|
|
|
@file{@trampfn{, , host, localfilename}}
|
|
opens file @var{localfilename} on the remote host @var{host}, using
|
|
the default method. @xref{Default Method}.
|
|
|
|
@table @file
|
|
@item @value{prefix}melancholia@value{postfix}.emacs
|
|
For the file @file{.emacs} located in the home directory, on the host
|
|
@code{melancholia}.
|
|
|
|
@item @value{prefix}melancholia.danann.net@value{postfix}.emacs
|
|
For the file @file{.emacs} specified using the fully qualified domain name of
|
|
the host.
|
|
|
|
@item @value{prefix}melancholia@value{postfix}~/.emacs
|
|
For the file @file{.emacs} specified using the @file{~}, which is expanded.
|
|
|
|
@item @value{prefix}melancholia@value{postfix}~daniel/.emacs
|
|
For the file @file{.emacs} located in @code{daniel}'s home directory
|
|
on the host, @code{melancholia}. The @file{~<user>} construct is
|
|
expanded to the home directory of that user on the remote host.
|
|
|
|
@item @value{prefix}melancholia@value{postfix}/etc/squid.conf
|
|
For the file @file{/etc/squid.conf} on the host @code{melancholia}.
|
|
|
|
@end table
|
|
|
|
@var{host} can take IPv4 or IPv6 address, as in @file{@trampfn{, ,
|
|
127.0.0.1, .emacs}} or @file{@trampfn{, ,
|
|
@value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}.
|
|
@ifset emacs
|
|
For syntactical reasons, IPv6 addresses must be embedded in square
|
|
brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
|
|
@end ifset
|
|
|
|
By default, @value{tramp} will use the current local user name as the
|
|
remote user name for log in to the remote host. Specifying a different
|
|
name using the proper syntax will override this default behavior:
|
|
|
|
@example
|
|
@trampfn{, user, host, path/to.file}
|
|
@end example
|
|
|
|
@file{@trampfn{, daniel, melancholia, .emacs}} is for file
|
|
@file{.emacs} in @code{daniel}'s home directory on the host,
|
|
@code{melancholia}.
|
|
|
|
Specify other file access methods (@pxref{Inline methods},
|
|
@pxref{External methods}) as part of the file name.
|
|
|
|
@ifset emacs
|
|
Method name comes before user name, as in
|
|
@file{@value{prefix}@var{method}@value{postfixhop}} (Note the trailing
|
|
colon).
|
|
@end ifset
|
|
@ifset xemacs
|
|
This is done by replacing the initial @file{@value{prefix}} with
|
|
@file{@value{prefix}@var{method}@value{postfixhop}} (Note the trailing
|
|
slash!).
|
|
@end ifset
|
|
The syntax specificaton for user, host, and file do not change.
|
|
|
|
To connect to the host @code{melancholia} as @code{daniel}, using
|
|
@option{ssh} method for @file{.emacs} in @code{daniel}'s home
|
|
directory, the full specification is: @file{@trampfn{ssh, daniel,
|
|
melancholia, .emacs}}.
|
|
|
|
A remote file name containing a host name, which is the same string as
|
|
a method name, is not allowed.
|
|
|
|
For specifying port numbers, affix @file{#<port>} to the host
|
|
name. For example: @file{@trampfn{ssh, daniel, melancholia#42,
|
|
.emacs}}.
|
|
|
|
|
|
@node File name completion
|
|
@section File name completion
|
|
@cindex file name completion
|
|
|
|
@value{tramp} can complete the following @value{tramp} file name
|
|
components: method names, user names, host names, and file names
|
|
located on remote hosts.
|
|
@ifset emacs
|
|
Enable this by activating partial completion in @file{.emacs}.
|
|
@ifinfo
|
|
@xref{Completion Options, , , @value{emacsdir}}.
|
|
@end ifinfo
|
|
@end ifset
|
|
|
|
For example, type @kbd{C-x C-f @value{prefix}t @key{TAB}},
|
|
@value{tramp} completion choices show up as
|
|
|
|
@example
|
|
@c @multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
|
|
@multitable @columnfractions .5 .5
|
|
@ifset emacs
|
|
@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/
|
|
@item @value{prefixhop}toto@value{postfix} @tab
|
|
@end ifset
|
|
@ifset xemacs
|
|
@item @value{prefixhop}telnet@value{postfixhop} @tab @value{prefixhop}toto@value{postfix}
|
|
@end ifset
|
|
@end multitable
|
|
@end example
|
|
|
|
@samp{@value{prefixhop}telnet@value{postfixhop}}
|
|
is a possible completion for the respective method,
|
|
@ifset emacs
|
|
@samp{tmp/} stands for the directory @file{/tmp} on your local host,
|
|
@end ifset
|
|
and @samp{@value{prefixhop}toto@value{postfix}}
|
|
might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts}
|
|
file (when using @option{ssh} as default method).
|
|
|
|
Type @kbd{e @key{TAB}} for the minibuffer completion to
|
|
@samp{@value{prefix}telnet@value{postfixhop}}. Typing @kbd{@key{TAB}}
|
|
shows host names @value{tramp} from @file{/etc/hosts} file, for example.
|
|
|
|
@example
|
|
@multitable @columnfractions .5 .5
|
|
@c @multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
|
|
@item @trampfn{telnet, , 127.0.0.1,} @tab @trampfn{telnet, , 192.168.0.1,}
|
|
@item @trampfn{telnet, , @value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet, , localhost,}
|
|
@item @trampfn{telnet, , melancholia.danann.net,} @tab @trampfn{telnet, , melancholia,}
|
|
@end multitable
|
|
@end example
|
|
|
|
Choose a host from the above list and then continue to complete file
|
|
names on that host.
|
|
|
|
When the configuration (@pxref{Customizing Completion}) includes user
|
|
names, then the completion lists will account for the user names as well.
|
|
|
|
Remote hosts previously visited or hosts whose connections are kept
|
|
persistently (@pxref{Connection caching}) will be included in the
|
|
completion lists.
|
|
|
|
After remote host name completion comes completion of file names on
|
|
the remote host. It works the same as on loal host file completion
|
|
except when killing with double-slash @file{//} kills only the file
|
|
name part of the @value{tramp} file name syntax.
|
|
@ifset emacs
|
|
A triple-slash stands for the default behavior.
|
|
@end ifset
|
|
@ifinfo
|
|
@xref{Minibuffer File, , , @value{emacsdir}}.
|
|
@end ifinfo
|
|
|
|
@noindent
|
|
Example:
|
|
|
|
@example
|
|
@ifset emacs
|
|
@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//etc} @key{TAB}}
|
|
@print{} @trampfn{telnet, , melancholia, /etc}
|
|
|
|
@kbd{C-x C-f @trampfn{telnet, , melancholia, //etc} @key{TAB}}
|
|
@print{} /etc
|
|
|
|
@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin///etc} @key{TAB}}
|
|
@print{} /etc
|
|
@end ifset
|
|
|
|
@ifset xemacs
|
|
@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//}}
|
|
@print{} @trampfn{telnet, , melancholia, /}
|
|
|
|
@kbd{C-x C-f @trampfn{telnet, , melancholia, //}}
|
|
@print{} /
|
|
@end ifset
|
|
@end example
|
|
|
|
During file name completion, remote directory contents are re-read
|
|
regularly to account for any changes in the filesystem that may affect
|
|
the completion candidates. Such re-reads can account for changes to
|
|
the file system by applications outside @value{emacsname}
|
|
(@pxref{Connection caching}).
|
|
|
|
@defopt tramp-completion-reread-directory-timeout
|
|
@vindex tramp-completion-reread-directory-timeout
|
|
The timeout is number of seconds since last remote command for
|
|
rereading remote directory contents. 0 re-reads immediately during
|
|
file name completion, @code{nil} uses cached directory contents.
|
|
@end defopt
|
|
|
|
|
|
@node Ad-hoc multi-hops
|
|
@section Declaring multiple hops in the file name
|
|
@cindex multi-hop, ad-hoc
|
|
@cindex proxy hosts, ad-hoc
|
|
|
|
@value{tramp} file name syntax can accommodate ad hoc specification of
|
|
multiple proxies without using @code{tramp-default-proxies-alist}
|
|
configuration setup(@pxref{Multi-hops}).
|
|
|
|
Each proxy is specified using the same syntax as the remote host
|
|
specification minus the file name part. Each hop is separated by a
|
|
@samp{|}. Chain the proxies from the starting host to the destination
|
|
remote host name and file name. For example, hopping over a single
|
|
proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}:
|
|
|
|
@example
|
|
@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh, you,
|
|
@c remotehost, /path}}
|
|
@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path}
|
|
@end example
|
|
|
|
Proxies can take patterns @code{%h} or @code{%u}.
|
|
|
|
@value{tramp} adds the ad-hoc definitions on the fly to
|
|
@code{tramp-default-proxies-alist} and is available for re-use during
|
|
that @value{emacsname} session. Subsequent @value{tramp} connections
|
|
to the same remote host can then use the shortcut form:
|
|
@samp{@trampfn{ssh, you, remotehost, /path}}.
|
|
|
|
@defopt tramp-save-ad-hoc-proxies
|
|
@vindex tramp-save-ad-hoc-proxies
|
|
For ad-hoc definitions to be saved automatically in
|
|
@option{tramp-default-proxies-alist} for future @value{emacsname}
|
|
sessions, set @option{tramp-save-ad-hoc-proxies}.
|
|
|
|
@lisp
|
|
(setq tramp-save-ad-hoc-proxies t)
|
|
@end lisp
|
|
@end defopt
|
|
|
|
|
|
@node Remote processes
|
|
@section Integration with other @value{emacsname} packages
|
|
@cindex compile
|
|
@cindex recompile
|
|
|
|
@value{tramp} supports starting new running processes on the remote
|
|
host for discovering remote file names. @value{emacsname} packages on
|
|
the remote host need no specific modifications for @value{tramp}'s
|
|
use.
|
|
|
|
This type of integration does not work with the @option{ftp} method,
|
|
and does not support the pty association as specified in
|
|
@code{start-file-process}.
|
|
|
|
@code{process-file} and @code{start-file-process} work on the remote
|
|
host when the variable @code{default-directory} is remote:
|
|
|
|
@lisp
|
|
(let ((default-directory "/ssh:remote.host:"))
|
|
(start-file-process "grep" (get-buffer-create "*grep*")
|
|
"/bin/sh" "-c" "grep -e tramp *"))
|
|
@end lisp
|
|
|
|
|
|
@ifset emacsgvfs
|
|
Remote processes do not apply to GVFS (see @ref{GVFS based methods})
|
|
because the remote file system is mounted on the local host and
|
|
@value{tramp} just accesses by changing the @code{default-directory}.
|
|
@end ifset
|
|
|
|
@value{tramp} starts a remote process when a command is executed in a
|
|
remote file or directory buffer. As of now, these packages have been
|
|
integrated to work with @value{tramp}: @file{compile.el} (commands
|
|
like @code{compile} and @code{grep}) and @file{gud.el} (@code{gdb} or
|
|
@code{perldb}).
|
|
|
|
For @value{tramp} to find the command on the remote, it must be
|
|
accessible through the default search path as setup by @value{tramp}
|
|
upon first connection. Alternatively, use an absolute path or extend
|
|
@code{tramp-remote-path} (see @ref{Remote programs}):
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-remote-path "~/bin")
|
|
(add-to-list 'tramp-remote-path "/appli/pub/bin")
|
|
@end lisp
|
|
|
|
Customize @code{tramp-remote-process-environment} to suit the remote
|
|
program's environment for the remote host.
|
|
@code{tramp-remote-process-environment} is a list of strings
|
|
structured similar to @code{process-environment}, where each element
|
|
is a string of the form @samp{ENVVARNAME=VALUE}.
|
|
|
|
To avoid any conflicts with local host variables set through local
|
|
configuration files, such as @file{~/.profile}, use @samp{ENVVARNAME=}
|
|
to unset them for the remote environment.
|
|
|
|
@noindent
|
|
Use @code{add-to-list} to add entries:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")
|
|
@end lisp
|
|
|
|
Modifying or deleting already existing values in the
|
|
@code{tramp-remote-process-environment} list may not be feasible on
|
|
restricted remote hosts. For example, some system administrators
|
|
disallow changing @env{HISTORY} variable. To accommodate such
|
|
restrictions when using @value{tramp}, fix the
|
|
@code{tramp-remote-process-environment} by the following code in the
|
|
local @file{.emacs} file:
|
|
|
|
@lisp
|
|
(let ((process-environment tramp-remote-process-environment))
|
|
(setenv "HISTORY" nil)
|
|
(setq tramp-remote-process-environment process-environment))
|
|
@end lisp
|
|
|
|
@value{tramp} does not use the defaults specified in
|
|
@code{process-environment} for running @code{process-file} or
|
|
@code{start-file-process} on remote hosts. When values from
|
|
@code{process-environment} are needed for remote processes, then set
|
|
them as follows:
|
|
|
|
@lisp
|
|
(let ((process-environment (cons "HGPLAIN=1" process-environment)))
|
|
(process-file @dots{}))
|
|
@end lisp
|
|
|
|
This works only for environment variables not already set in the
|
|
@code{process-environment}.
|
|
|
|
For integrating other @value{emacsname} packages so @value{tramp} can
|
|
execute remotely, please file a bug report. @xref{Bug Reports}.
|
|
|
|
|
|
@subsection Running remote programs that create local X11 windows
|
|
|
|
To allow a remote program to create an X11 window on the local host,
|
|
set the @env{DISPLAY} environment variable for the remote host as
|
|
follows in the local @file{.emacs} file:
|
|
|
|
@lisp
|
|
(add-to-list 'tramp-remote-process-environment
|
|
(format "DISPLAY=%s" (getenv "DISPLAY")))
|
|
@end lisp
|
|
|
|
@noindent
|
|
@code{(getenv "DISPLAY")} should return a recognizable name for the
|
|
local host that the remote host can redirect X11 window
|
|
interactions. If querying for a recognizable name is not possible for
|
|
whatever reason, then replace @code{(getenv "DISPLAY")} with a
|
|
hard-coded, fixed name. Note that using @code{:0} for X11 display name
|
|
here will not work as expected.
|
|
|
|
An alternate approach is specify @code{ForwardX11 yes} or
|
|
@code{ForwardX11Trusted yes} in the file @file{~/.ssh/config} on the
|
|
local host.
|
|
|
|
|
|
@subsection Running @code{shell} on a remote host
|
|
@cindex shell
|
|
|
|
Set @option{explicit-shell-file-name} to the appropriate shell name
|
|
when using @value{tramp} between two hosts with different operating
|
|
systems, such as @samp{windows-nt} and @samp{gnu/linux}. This option
|
|
ensures the correct name of the remote shell program.
|
|
|
|
@ifset emacs
|
|
Starting with Emacs 24, when @option{explicit-shell-file-name} is
|
|
equal to @code{nil}, calling @code{shell} interactively will prompt
|
|
for a shell name.
|
|
@end ifset
|
|
|
|
|
|
@subsection Running @code{shell-command} on a remote host
|
|
@cindex shell-command
|
|
|
|
@code{shell-command} executes commands synchronously or asynchronously
|
|
on remote hosts and displays output in buffers on the local
|
|
host. Example:
|
|
|
|
@example
|
|
@kbd{C-x C-f @trampfn{sudo, , , } @key{RET}}
|
|
@kbd{M-! tail -f /var/log/syslog.log & @key{RET}}
|
|
@end example
|
|
|
|
@command{tail} command outputs continuously to the local buffer,
|
|
@file{*Async Shell Command*}
|
|
|
|
@ifset emacs
|
|
@kbd{M-x auto-revert-tail-mode} runs similarly showing continuous output.
|
|
@end ifset
|
|
|
|
|
|
@subsection Running @code{eshell} on a remote host
|
|
@cindex eshell
|
|
|
|
@value{tramp} is integrated into @file{eshell.el}, which enables
|
|
interactive eshell sessions on remote hosts at the command prompt.
|
|
You must add the module @code{eshell-tramp} to
|
|
@code{eshell-modules-list}. Here's a sample interaction after opening
|
|
@kbd{M-x eshell} on a remote host:
|
|
|
|
@example
|
|
@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
|
|
@b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET}
|
|
host
|
|
@b{@trampfn{sudo, root, host, /etc} $} id @key{RET}
|
|
uid=0(root) gid=0(root) groups=0(root)
|
|
@b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET}
|
|
#<buffer shadow>
|
|
@b{@trampfn{sudo, root, host, /etc} $}
|
|
@end example
|
|
|
|
@ifset emacs
|
|
@code{eshell} in @value{emacsname} 23.2 added custom @code{su} and
|
|
@code{sudo} commands that set the default directory correctly for the
|
|
@file{*eshell*} buffer. @value{tramp} silently updates
|
|
@code{tramp-default-proxies-alist} with an entry for this directory
|
|
(@pxref{Multi-hops}):
|
|
|
|
@example
|
|
@b{~ $} cd @trampfn{ssh, user, remotehost, /etc} @key{RET}
|
|
@b{@trampfn{ssh, user, remotehost, /etc} $} find-file shadow @key{RET}
|
|
File is not readable: @trampfn{ssh, user, remotehost, /etc/shadow}
|
|
@b{@trampfn{ssh, user, remotehost, /etc} $} sudo find-file shadow @key{RET}
|
|
#<buffer shadow>
|
|
|
|
@b{@trampfn{ssh, user, remotehost, /etc} $} su - @key{RET}
|
|
@b{@trampfn{su, root, remotehost, /root} $} id @key{RET}
|
|
uid=0(root) gid=0(root) groups=0(root)
|
|
@b{@trampfn{su, root, remotehost, /root} $}
|
|
@end example
|
|
@end ifset
|
|
|
|
|
|
@anchor{Running a debugger on a remote host}
|
|
@subsection Running a debugger on a remote host
|
|
@cindex gud
|
|
@cindex gdb
|
|
@cindex perldb
|
|
|
|
@file{gud.el} provides a unified interface to symbolic debuggers
|
|
@ifset emacs
|
|
@ifinfo
|
|
(@ref{Debuggers, , , @value{emacsdir}}).
|
|
@end ifinfo
|
|
@end ifset
|
|
@value{tramp} can run debug on remote hosts by calling @code{gdb}
|
|
with a remote file name:
|
|
|
|
@example
|
|
@kbd{M-x gdb @key{RET}}
|
|
@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET}
|
|
@end example
|
|
|
|
Relative file names are based on the remote default directory. When
|
|
@file{myprog.pl} exists in @file{@trampfn{ssh, , host, /home/user}},
|
|
valid calls include:
|
|
|
|
@example
|
|
@kbd{M-x perldb @key{RET}}
|
|
@b{Run perldb (like this):} perl -d myprog.pl @key{RET}
|
|
@end example
|
|
|
|
Just the local part of a remote file name, such as @kbd{perl -d
|
|
/home/user/myprog.pl}, is not possible.
|
|
|
|
Arguments of the program to be debugged must be literal, can take
|
|
relative or absolute paths, but not remote paths.
|
|
|
|
|
|
@subsection Running remote processes on Windows hosts
|
|
@cindex winexe
|
|
@cindex powershell
|
|
|
|
@command{winexe} runs processes on a remote Windows host, and
|
|
@value{tramp} can use it for @code{process-file} and
|
|
@code{start-file-process}.
|
|
|
|
@code{tramp-smb-winexe-program} specifies the local @command{winexe}
|
|
command. Powershell V2.0 on the remote host is required to run
|
|
processes triggered from @value{tramp}.
|
|
|
|
@option{explicit-shell-file-name} and @option{explicit-*-args} have to
|
|
be set properly so @kbd{M-x shell} can open a proper remote shell on a
|
|
Windows host. To open @command{cmd}, set it as follows:
|
|
|
|
@lisp
|
|
(setq explicit-shell-file-name "cmd"
|
|
explicit-cmd-args '("/q"))
|
|
@end lisp
|
|
|
|
@noindent
|
|
To open @command{powershell} as a remote shell, use this:
|
|
|
|
@lisp
|
|
(setq explicit-shell-file-name "powershell"
|
|
explicit-powershell-args '("-file" "-"))
|
|
@end lisp
|
|
|
|
|
|
@node Cleanup remote connections
|
|
@section Cleanup remote connections
|
|
@cindex cleanup
|
|
|
|
@value{tramp} provides several ways to flush remote connections.
|
|
|
|
@deffn Command tramp-cleanup-connection vec
|
|
This command flushes all connection related objects. @option{vec} is
|
|
the internal representation of a remote connection. When called
|
|
interactively, this command lists active remote connections in the
|
|
minibuffer. Each connection is of the format @file{@trampfn{method,
|
|
user, host, }}. Flushing remote connections also cleans the password
|
|
cache (@pxref{Password handling}), file cache, connection cache
|
|
(@pxref{Connection caching}), and connection buffers.
|
|
@end deffn
|
|
|
|
@deffn Command tramp-cleanup-this-connection
|
|
Flushes only the current buffer's remote connection objects, the same
|
|
as in @code{tramp-cleanup-connection}.
|
|
@end deffn
|
|
|
|
@deffn Command tramp-cleanup-all-connections
|
|
Flushes all active remote connection objects, the same as in
|
|
@code{tramp-cleanup-connection}.
|
|
@end deffn
|
|
|
|
@deffn Command tramp-cleanup-all-buffers
|
|
Just as for @code{tramp-cleanup-all-connections}, all remote
|
|
connections are cleaned up in addition to killing buffers related to
|
|
that remote connection.
|
|
@end deffn
|
|
|
|
|
|
@node Bug Reports
|
|
@chapter Reporting Bugs and Problems
|
|
@cindex bug reports
|
|
|
|
@value{tramp}'s development team is actively engaged in solving bugs
|
|
and problems and looks to feature requests and suggestions.
|
|
|
|
@value{tramp}'s mailing list is the place for more advice and
|
|
information on working with @value{tramp}, solving problems,
|
|
discussing, and general discussions about @value{tramp}.
|
|
|
|
@value{tramp}'s mailing list is moderated but even non-subscribers can
|
|
post for moderator approval. Sometimes this approval step may take as
|
|
long as 48 hours due to public holidays.
|
|
|
|
@email{tramp-devel@@gnu.org} is the mailing list. Messages sent to
|
|
this address go to all the subscribers. This is @emph{not} the
|
|
address to send subscription requests to.
|
|
|
|
To subscribe to the mailing list, visit:
|
|
@uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/, the
|
|
@value{tramp} Mail Subscription Page}.
|
|
|
|
@ifset emacs
|
|
@ifset installchapter
|
|
Before sending a bug report, run the test suite first @ref{Testing}.
|
|
@end ifset
|
|
@end ifset
|
|
|
|
@findex tramp-bug
|
|
Check if the bug or problem is already addressed in @xref{Frequently
|
|
Asked Questions}.
|
|
|
|
Run @kbd{M-x tramp-bug} to generate a buffer with details of the
|
|
system along with the details of the @value{tramp}
|
|
installation. Please include these details with the bug report.
|
|
|
|
The bug report must describe in as excruciating detail as possible the
|
|
steps required to reproduce the problem. These details must include
|
|
the setup of the remote host and any special or unique conditions that
|
|
exist.
|
|
|
|
Include a minimal test case that reproduces the problem. This will
|
|
help the development team find the best solution and avoid unrelated
|
|
detours.
|
|
|
|
To exclude cache-related problems, flush all caches before running the
|
|
test, @ref{Cleanup remote connections}.
|
|
|
|
When including @value{tramp}'s messages in the bug report, increase
|
|
the verbosity level to 6 (@pxref{Traces and Profiles, Traces}) in the
|
|
@file{~/.emacs} file before repeating steps to the bug. Include the
|
|
contents of the @file{*tramp/foo*} and @file{*debug tramp/foo*}
|
|
buffers with the bug report.
|
|
|
|
@strong{Note} that a verbosity level greater than 6 is not necessary
|
|
at this stage. Also note that a verbosity level of 6 or greater, the
|
|
contents of files and directories will be included in the debug
|
|
buffer. Passwords typed in @value{tramp} will never be included
|
|
there.
|
|
|
|
|
|
@node Frequently Asked Questions
|
|
@chapter Frequently Asked Questions
|
|
@cindex frequently asked questions
|
|
@cindex FAQ
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Where is the latest @value{tramp}?
|
|
|
|
@value{tramp} is available at the GNU URL:
|
|
|
|
@noindent
|
|
@uref{ftp://ftp.gnu.org/gnu/tramp/}
|
|
|
|
@noindent
|
|
@value{tramp}'s GNU project page is located here:
|
|
|
|
@noindent
|
|
@uref{http://savannah.gnu.org/projects/tramp/}
|
|
|
|
|
|
@item
|
|
Which systems does it work on?
|
|
|
|
The package works successfully on Emacs 22, Emacs 23, Emacs 24, Emacs
|
|
25, XEmacs 21 (starting with 21.4), and SXEmacs 22.
|
|
|
|
While Unix and Unix-like systems are the primary remote targets,
|
|
@value{tramp} has equal success connecting to other platforms, such as
|
|
MS Windows XP/Vista/7.
|
|
|
|
|
|
@item
|
|
How to speed up @value{tramp}?
|
|
|
|
@value{tramp} does many things in the background, some of which
|
|
depends on network speeds, response speeds of remote hosts, and
|
|
authentication delays. During these operations, @value{tramp}'s
|
|
responsiveness slows down. Some suggestions within the scope of
|
|
@value{tramp}'s settings include:
|
|
|
|
Use an external method, such as @option{scp}, which are faster than
|
|
internal methods.
|
|
|
|
Keep the file @code{tramp-persistency-file-name}, which is where
|
|
@value{tramp} caches remote information about hosts and files. Caching
|
|
is enabled by default. Don't disable it.
|
|
|
|
Set @code{remote-file-name-inhibit-cache} to @code{nil} if remote
|
|
files are not independently updated outside @value{tramp}'s control.
|
|
That cache cleanup will be necessary if the remote directories or
|
|
files are updated independent of @value{tramp}.
|
|
|
|
Set @code{tramp-completion-reread-directory-timeout} to @code{nil} to
|
|
speed up completions, @ref{File name completion}.
|
|
|
|
Disable version control to avoid delays:
|
|
|
|
@lisp
|
|
(setq vc-ignore-dir-regexp
|
|
(format "\\(%s\\)\\|\\(%s\\)"
|
|
vc-ignore-dir-regexp
|
|
tramp-file-name-regexp))
|
|
@end lisp
|
|
|
|
Disable excessive traces. Set @code{tramp-verbose} to 3 or lower,
|
|
default being 3. Increase trace levels temporarily when hunting for
|
|
bugs.
|
|
|
|
@item
|
|
@value{tramp} does not connect to the remote host
|
|
|
|
Three main reasons for why @value{tramp} does not connect to the remote host:
|
|
|
|
@itemize @minus
|
|
@item
|
|
Unknown characters in the prompt
|
|
|
|
@value{tramp} needs a clean recognizable prompt on the remote host for
|
|
accurate parsing. Shell prompts that contain escape sequences for
|
|
coloring cause parsing problems. @ref{Remote shell setup} for
|
|
customizing prompt detection using regular expressions.
|
|
|
|
To check if the remote host's prompt is being recognized, use this
|
|
test: switch to @value{tramp} connection buffer @file{*tramp/foo*},
|
|
put the cursor at the top of the buffer, and then apply the following
|
|
expression:
|
|
|
|
@example
|
|
@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))}
|
|
@end example
|
|
|
|
If the cursor has not moved to the prompt at the bottom of the buffer,
|
|
then @value{tramp} has failed to recognize the prompt.
|
|
|
|
When using zsh on remote hosts, disable zsh line editor because zsh
|
|
uses left-hand side and right-hand side prompts in parallel. Add the
|
|
following line to @file{~/.zshrc}:
|
|
|
|
@example
|
|
[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
|
|
@end example
|
|
|
|
When using fish shell on remote hosts, disable fancy formatting by
|
|
adding the following to @file{~/.config/fish/config.fish}:
|
|
|
|
@example
|
|
function fish_prompt
|
|
if test $TERM = "dumb"
|
|
echo "\$ "
|
|
else
|
|
@dots{}
|
|
end
|
|
end
|
|
@end example
|
|
|
|
When using WinSSHD on remote hosts, @value{tramp} do not recognize the
|
|
strange prompt settings.
|
|
|
|
@item
|
|
Echoed characters after login
|
|
|
|
@value{tramp} suppresses echos from remote hosts with the
|
|
@command{stty -echo} command. But sometimes it is too late to suppress
|
|
welcome messages from the remote host containing harmful control
|
|
characters. Using @option{sshx} or @option{scpx} methods can avoid
|
|
this problem because they allocate a pseudo tty. @xref{Inline
|
|
methods}.
|
|
|
|
@item
|
|
@value{tramp} stops transferring strings longer than 500 characters
|
|
|
|
Set @code{tramp-chunksize} to 500 to get around this problem, which is
|
|
related to faulty implementation of @code{process-send-string} on
|
|
HP-UX, FreeBSD and Tru64 Unix systems. Consult the documentation for
|
|
@code{tramp-chunksize} to see when this is necessary.
|
|
|
|
Set @code{file-precious-flag} to @code{t} for files accessed by
|
|
@value{tramp} so the file contents are checked using checksum by
|
|
first saving to a temporary file.
|
|
@ifinfo
|
|
@pxref{Saving Buffers, , , elisp}
|
|
@end ifinfo
|
|
|
|
@lisp
|
|
(add-hook
|
|
'find-file-hook
|
|
(lambda ()
|
|
(when (file-remote-p default-directory)
|
|
(set (make-local-variable 'file-precious-flag) t))))
|
|
@end lisp
|
|
@end itemize
|
|
|
|
|
|
@item
|
|
@value{tramp} does not recognize if a @command{ssh} session hangs
|
|
|
|
@command{ssh} sessions on the local host hang when the network is
|
|
down. @value{tramp} cannot safely detect such hangs. The network
|
|
configuration for @command{ssh} can be configured to kill such hangs
|
|
with the following command in the @file{~/.ssh/config}:
|
|
|
|
@example
|
|
Host *
|
|
ServerAliveInterval 5
|
|
@end example
|
|
|
|
|
|
@item
|
|
@value{tramp} does not use default @command{ssh} @code{ControlPath}
|
|
|
|
@value{tramp} overwrites @code{ControlPath} settings when initiating
|
|
@command{ssh} sessions. @value{tramp} does this to fend off a stall
|
|
if a master session opened outside the @value{emacsname} session is no
|
|
longer open. That is why @value{tramp} prompts for the password again
|
|
even if there is an @command{ssh} already open.
|
|
|
|
Some @command{ssh} versions support a @code{ControlPersist} option,
|
|
which allows to set the @code{ControlPath} provided the variable
|
|
@code{tramp-ssh-controlmaster-options} is customized as follows:
|
|
|
|
@lisp
|
|
(setq tramp-ssh-controlmaster-options
|
|
(concat
|
|
"-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p "
|
|
"-o ControlMaster=auto -o ControlPersist=yes"))
|
|
@end lisp
|
|
|
|
Note how "%r", "%h" and "%p" must be encoded as "%%r", "%%h" and
|
|
"%%p".
|
|
|
|
If the @file{~/.ssh/config} is configured appropriately for the above
|
|
behavior, then any changes to @command{ssh} can be suppressed with
|
|
this @code{nil} setting:
|
|
|
|
@lisp
|
|
(setq tramp-use-ssh-controlmaster-options nil)
|
|
@end lisp
|
|
|
|
|
|
@item
|
|
File name completion does not work with @value{tramp}
|
|
|
|
@acronym{ANSI} escape sequences from the remote shell may cause errors
|
|
in @value{tramp}'s parsing of remote buffers.
|
|
|
|
To test if this is the case, open a remote shell and check if the output
|
|
of @command{ls} is in color.
|
|
|
|
To disable @acronym{ANSI} escape sequences from the remote hosts,
|
|
disable @option{--color=yes} or @option{--color=auto} in the remote
|
|
host's @file{.bashrc} or @file{.profile}. Turn this alias on and off
|
|
to see if file name completion works.
|
|
|
|
@item
|
|
File name completion does not work in directories with large number of
|
|
files
|
|
|
|
This may be related to globbing, which is the use of shell's ability
|
|
to expand wild card specifications, such as @samp{*.c}. For
|
|
directories with large number of files, globbing might exceed the
|
|
shell's limit on length of command lines and hang. @value{tramp} uses
|
|
globbing.
|
|
|
|
To test if globbing hangs, open a shell on the remote host and then
|
|
run @samp{ls -d * ..?* > /dev/null}.
|
|
|
|
When testing, ensure the remote shell is the same shell
|
|
(@command{/bin/sh}, @command{ksh} or @command{bash}), that
|
|
@value{tramp} uses when connecting to that host.
|
|
|
|
|
|
@item
|
|
How to get notified after @value{tramp} completes file transfers?
|
|
|
|
Make @value{emacsname} beep after reading from or writing to the
|
|
remote host with the following code in @file{~/.emacs} file.
|
|
|
|
@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-insert-beep-advice activate)
|
|
"Make tramp beep after inserting a file."
|
|
(interactive)
|
|
(beep))
|
|
@end lisp
|
|
|
|
|
|
@ifset emacs
|
|
@item
|
|
How to get a Visual Warning when working with @samp{root} privileges
|
|
|
|
Get a modeline indication when working with @samp{root} privileges
|
|
with the following code (tested with @value{emacsname} 22.1) in
|
|
@file{~/.emacs} file:
|
|
|
|
@lisp
|
|
(defun my-mode-line-function ()
|
|
(when (string-match "^/su\\(do\\)?:" default-directory)
|
|
(setq mode-line-format
|
|
(format-mode-line mode-line-format 'font-lock-warning-face))))
|
|
|
|
(add-hook 'find-file-hook 'my-mode-line-function)
|
|
(add-hook 'dired-mode-hook 'my-mode-line-function)
|
|
@end lisp
|
|
@end ifset
|
|
|
|
|
|
@ifset emacs
|
|
@item
|
|
How to get host indication in the mode line?
|
|
|
|
The following code (tested with @value{emacsname} 22.1) in
|
|
@file{~/.emacs} file shows it:
|
|
|
|
@lisp
|
|
(defconst my-mode-line-buffer-identification
|
|
(list
|
|
'(:eval
|
|
(let ((host-name
|
|
(if (file-remote-p default-directory)
|
|
(tramp-file-name-host
|
|
(tramp-dissect-file-name default-directory))
|
|
(system-name))))
|
|
(if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
|
|
(substring host-name 0 (match-beginning 1))
|
|
host-name)))
|
|
": %12b"))
|
|
|
|
(setq-default
|
|
mode-line-buffer-identification
|
|
my-mode-line-buffer-identification)
|
|
|
|
(add-hook
|
|
'dired-mode-hook
|
|
(lambda ()
|
|
(setq
|
|
mode-line-buffer-identification
|
|
my-mode-line-buffer-identification)))
|
|
@end lisp
|
|
|
|
The mode line in @value{emacsname} 23.1 and later versions now
|
|
contains an indication if @code{default-directory} for the current
|
|
buffer is on a remote host. Moreover, the corresponding tool-tip
|
|
shows the remote host name. The above @code{:eval} clause can also be
|
|
simplified to show the host name in the mode line:
|
|
|
|
@lisp
|
|
'(:eval
|
|
(let ((host-name
|
|
(or (file-remote-p default-directory 'host)
|
|
(system-name))))
|
|
(if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
|
|
(substring host-name 0 (match-beginning 1))
|
|
host-name)))
|
|
@end lisp
|
|
@end ifset
|
|
|
|
|
|
@ifset emacs
|
|
@item
|
|
Remote host does not understand default options for directory listing
|
|
|
|
@value{emacsname} computes the @command{dired} options based on the
|
|
local host but if the remote host cannot understand the same
|
|
@command{ls} command, then set them with a hook as follows:
|
|
|
|
@lisp
|
|
(add-hook
|
|
'dired-before-readin-hook
|
|
(lambda ()
|
|
(when (file-remote-p default-directory)
|
|
(setq dired-actual-switches "-al"))))
|
|
@end lisp
|
|
@end ifset
|
|
|
|
|
|
@item
|
|
Why is @file{~/.sh_history} file on the remote host growing?
|
|
|
|
Due to @command{ksh} saving tilde expansions triggered by
|
|
@value{tramp}, the history file is probably growing rapidly. To fix,
|
|
turn off saving history by putting this shell code in the
|
|
@file{.kshrc} file:
|
|
|
|
@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
|
|
|
|
For @option{ssh}-based method, add the following line to your
|
|
@file{~/.ssh/environment} file:
|
|
|
|
@example
|
|
HISTFILE=/dev/null
|
|
@end example
|
|
|
|
|
|
@item
|
|
How to shorten long file names when typing in @value{tramp}?
|
|
|
|
Adapt several of these approaches to reduce typing. If the full name
|
|
is @file{@trampfn{ssh, news, news.my.domain, /opt/news/etc}}, then:
|
|
|
|
@enumerate
|
|
|
|
@item
|
|
Use default values for method name and user name:
|
|
|
|
You can define default methods and user names for hosts,
|
|
(@pxref{Default Method}, @pxref{Default User}):
|
|
|
|
@lisp
|
|
(setq tramp-default-method "ssh"
|
|
tramp-default-user "news")
|
|
@end lisp
|
|
|
|
The reduced typing: @kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
|
|
|
|
@strong{Note} that there are some useful shortcuts already. Accessing
|
|
your local host as @samp{root} user, is possible just by @kbd{C-x C-f
|
|
@trampfn{su, , ,}}.
|
|
|
|
@item
|
|
Use configuration options of the access method:
|
|
|
|
Programs used for access methods already offer powerful configurations
|
|
(@pxref{Customizing Completion}). For @option{ssh}, configure the
|
|
file @file{~/.ssh/config}:
|
|
|
|
@example
|
|
Host xy
|
|
HostName news.my.domain
|
|
User news
|
|
@end example
|
|
|
|
The reduced typing: @kbd{C-x C-f @trampfn{ssh, , xy, /opt/news/etc}}.
|
|
|
|
Depending on the number of files in the directories, host names
|
|
completion can further reduce key strokes: @kbd{C-x C-f
|
|
@value{prefix}ssh@value{postfixhop}x @key{TAB}}.
|
|
|
|
@item
|
|
Use environment variables to expand long strings
|
|
|
|
For long file names, set up environment variables that are expanded in
|
|
the minibuffer. Environment variables are set either outside
|
|
@value{emacsname} or inside @value{emacsname} with Lisp:
|
|
|
|
@lisp
|
|
(setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")
|
|
@end lisp
|
|
|
|
The reduced typing: @kbd{C-x C-f $xy @key{RET}}.
|
|
|
|
@strong{Note} that file name cannot be edited here because the
|
|
environment variables are not expanded during editing in the
|
|
minibuffer.
|
|
|
|
@item Define own keys:
|
|
|
|
Redefine another key sequence in @value{emacsname} for @kbd{C-x C-f}:
|
|
|
|
@lisp
|
|
(global-set-key
|
|
[(control x) (control y)]
|
|
(lambda ()
|
|
(interactive)
|
|
(find-file
|
|
(read-file-name
|
|
"Find Tramp file: "
|
|
"@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))))
|
|
@end lisp
|
|
|
|
Simply typing @kbd{C-x C-y} would prepare minibuffer editing of file
|
|
name.
|
|
|
|
See @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the Emacs
|
|
Wiki} for a more comprehensive example.
|
|
|
|
@item
|
|
Define own abbreviation (1):
|
|
|
|
Abbreviation list expansion can be used to reduce typing long file names:
|
|
|
|
@lisp
|
|
(add-to-list
|
|
'directory-abbrev-alist
|
|
'("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
|
|
@end lisp
|
|
|
|
The reduced typing: @kbd{C-x C-f /xy @key{RET}}.
|
|
|
|
@strong{Note} that file name cannot be edited here because the
|
|
environment variables are not expanded during editing in the
|
|
minibuffer.
|
|
|
|
@item
|
|
Define own abbreviation (2):
|
|
|
|
The @code{abbrev-mode} gives additional flexibility for editing in the
|
|
minibuffer:
|
|
|
|
@lisp
|
|
(define-abbrev-table 'my-tramp-abbrev-table
|
|
'(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))
|
|
|
|
(add-hook
|
|
'minibuffer-setup-hook
|
|
(lambda ()
|
|
(abbrev-mode 1)
|
|
(setq local-abbrev-table my-tramp-abbrev-table)))
|
|
|
|
(defadvice minibuffer-complete
|
|
(before my-minibuffer-complete activate)
|
|
(expand-abbrev))
|
|
|
|
;; If you use partial-completion-mode
|
|
(defadvice PC-do-completion
|
|
(before my-PC-do-completion activate)
|
|
(expand-abbrev))
|
|
@end lisp
|
|
|
|
The reduced typing: @kbd{C-x C-f xy @key{TAB}}.
|
|
|
|
The minibuffer expands for further editing.
|
|
|
|
@item Use bookmarks:
|
|
|
|
Use bookmarks to save Tramp file names.
|
|
@ifinfo
|
|
@pxref{Bookmarks, , , @value{emacsdir}}.
|
|
@end ifinfo
|
|
|
|
Upon visiting a location with @value{tramp}, save it as a bookmark with
|
|
@ifset emacs
|
|
@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}.
|
|
@end ifset
|
|
|
|
To revisit that bookmark:
|
|
@ifset emacs
|
|
@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}.
|
|
@end ifset
|
|
|
|
@item Use recent files:
|
|
|
|
@ifset emacs
|
|
@file{recentf}
|
|
@end ifset
|
|
@ifset xemacs
|
|
@file{recent-files}
|
|
@end ifset
|
|
remembers visited places.
|
|
@ifinfo
|
|
@ifset emacs
|
|
@pxref{File Conveniences, , , @value{emacsdir}}.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@pxref{recent-files, , , edit-utils}.
|
|
@end ifset
|
|
@end ifinfo
|
|
|
|
Keep remote file names in the recent list without have to check for
|
|
their accessibility through remote access:
|
|
|
|
@lisp
|
|
@ifset emacs
|
|
(recentf-mode 1)
|
|
@end ifset
|
|
@ifset xemacs
|
|
(recent-files-initialize)
|
|
(add-hook
|
|
'find-file-hook
|
|
(lambda ()
|
|
(when (file-remote-p (buffer-file-name))
|
|
(recent-files-make-permanent)))
|
|
'append)
|
|
@end ifset
|
|
@end lisp
|
|
|
|
Reaching recently opened files:
|
|
@ifset emacs
|
|
@kbd{@key{menu-bar} @key{file} @key{Open Recent}}.
|
|
@end ifset
|
|
@ifset xemacs
|
|
@kbd{@key{menu-bar} @key{Recent Files}}.
|
|
@end ifset
|
|
|
|
@ifset emacs
|
|
@item Use filecache:
|
|
|
|
Since @file{filecache} remembers visited places, add the remote
|
|
directory to the cache:
|
|
|
|
@lisp
|
|
(eval-after-load "filecache"
|
|
'(file-cache-add-directory
|
|
"@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
|
|
@end lisp
|
|
|
|
Then use directory completion in the minibuffer with @kbd{C-x C-f
|
|
C-@key{TAB}}.
|
|
@end ifset
|
|
|
|
@ifset emacs
|
|
@item Use bbdb:
|
|
|
|
@file{bbdb} has a built-in feature for @value{ftppackagename} files,
|
|
which also works for @value{tramp} file names.
|
|
@ifinfo
|
|
@pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb}.
|
|
@end ifinfo
|
|
|
|
Load @file{bbdb} in @value{emacs}:
|
|
|
|
@lisp
|
|
(require 'bbdb)
|
|
(bbdb-initialize)
|
|
@end lisp
|
|
|
|
Create a BBDB entry with @kbd{M-x bbdb-create-ftp-site}. Then specify
|
|
a method and user name where needed. Examples:
|
|
|
|
@example
|
|
@kbd{M-x bbdb-create-ftp-site @key{RET}}
|
|
@b{Ftp Site:} news.my.domain @key{RET}
|
|
@b{Ftp Directory:} /opt/news/etc/ @key{RET}
|
|
@b{Ftp Username:} ssh@value{postfixhop}news @key{RET}
|
|
@b{Company:} @key{RET}
|
|
@b{Additional Comments:} @key{RET}
|
|
@end example
|
|
|
|
In BBDB buffer, access an entry by pressing the key @key{F}.
|
|
@end ifset
|
|
|
|
@end enumerate
|
|
|
|
Thanks to @value{tramp} users for contributing to these recipes.
|
|
|
|
@item
|
|
Why saved multi-hop file names do not work in a new @value{emacsname}
|
|
session?
|
|
|
|
When saving ad-hoc multi-hop @value{tramp} file names (@pxref{Ad-hoc
|
|
multi-hops}) via bookmarks, recent files,
|
|
@ifset emacs
|
|
filecache, bbdb,
|
|
@end ifset
|
|
or another package, use the full ad-hoc file name including all hops,
|
|
like @file{@trampfn{ssh, bird,
|
|
bastion|ssh@value{postfixhop}news.my.domain, /opt/news/etc}}.
|
|
|
|
Alternatively, when saving abbreviated multi-hop file names
|
|
@file{@trampfn{ssh, news, news.my.domain, /opt/news/etc}}, the custom
|
|
option @code{tramp-save-ad-hoc-proxies} must be set non-@code{nil}
|
|
value.
|
|
|
|
|
|
@ifset emacs
|
|
@item
|
|
How to connect to a remote @value{emacsname} session using @value{tramp}?
|
|
|
|
Configure Emacs Client
|
|
@ifinfo
|
|
(@pxref{Emacs Server, , , @value{emacsdir}}).
|
|
@end ifinfo
|
|
|
|
Then on the remote host, start the Emacs Server:
|
|
|
|
@lisp
|
|
(require 'server)
|
|
(setq server-host (system-name)
|
|
server-use-tcp t)
|
|
(server-start)
|
|
@end lisp
|
|
|
|
If @code{(system-name)} of the remote host cannot be resolved on the
|
|
local host, use IP address instead.
|
|
|
|
Copy from the remote host the resulting file
|
|
@file{~/.emacs.d/server/server} to the local host, to the same
|
|
location.
|
|
|
|
Then start Emacs Client from the command line:
|
|
|
|
@example
|
|
emacsclient @trampfn{ssh, user, host, /file/to/edit}
|
|
@end example
|
|
|
|
@code{user} and @code{host} refer to the local host.
|
|
|
|
To make Emacs Client an editor for other programs, use a wrapper
|
|
script @file{emacsclient.sh}:
|
|
|
|
@example
|
|
#!/bin/sh
|
|
emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1}
|
|
@end example
|
|
|
|
Then change the environment variable @env{EDITOR} to point to the
|
|
wrapper script:
|
|
|
|
@example
|
|
export EDITOR=/path/to/emacsclient.sh
|
|
@end example
|
|
@end ifset
|
|
|
|
|
|
@item
|
|
How to disable other packages from calling @value{tramp}?
|
|
|
|
There are packages that call @value{tramp} without the user ever
|
|
entering a remote file name. Even without applying a remote file
|
|
syntax, some packages enable @value{tramp} on their own. How can users
|
|
disable such features.
|
|
|
|
@itemize @minus
|
|
@item
|
|
@file{ido.el}
|
|
|
|
Disable @value{tramp} file name completion:
|
|
|
|
@lisp
|
|
(custom-set-variables
|
|
'(ido-enable-tramp-completion nil))
|
|
@end lisp
|
|
|
|
@item
|
|
@file{rlogin.el}
|
|
|
|
Disable remote directory tracking mode:
|
|
|
|
@lisp
|
|
(rlogin-directory-tracking-mode -1)
|
|
@end lisp
|
|
@end itemize
|
|
|
|
|
|
@item
|
|
How to disable @value{tramp}?
|
|
|
|
@itemize @minus
|
|
@ifset emacs
|
|
@item
|
|
To keep @value{ftppackagename} as default the remote files access
|
|
package, set this in @file{.emacs}:
|
|
|
|
@lisp
|
|
(setq tramp-default-method "ftp")
|
|
@end lisp
|
|
@end ifset
|
|
|
|
@item
|
|
To disable both
|
|
@ifset emacs
|
|
@value{tramp} (and @value{ftppackagename}),
|
|
@end ifset
|
|
@ifset xemacs
|
|
@value{tramp},
|
|
@end ifset
|
|
set @code{tramp-mode} to @code{nil} in @file{.emacs}.
|
|
|
|
@lisp
|
|
(setq tramp-mode nil)
|
|
@end lisp
|
|
|
|
@item
|
|
To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp}.
|
|
@ifset emacs
|
|
Unloading @value{tramp} resets @value{ftppackagename} plugins also.
|
|
@end ifset
|
|
@end itemize
|
|
@end itemize
|
|
|
|
|
|
@c For the developer
|
|
@node Files directories and localnames
|
|
@chapter How file names, directories and localnames are mangled and managed.
|
|
|
|
@menu
|
|
* Localname deconstruction:: Splitting a localname into its component parts.
|
|
@ifset emacs
|
|
* External packages:: Integrating with external Lisp packages.
|
|
@end ifset
|
|
@end menu
|
|
|
|
|
|
@node Localname deconstruction
|
|
@section Splitting a localname into its component parts
|
|
|
|
@value{tramp} package redefines lisp functions
|
|
@code{file-name-directory} and @code{file-name-nondirectory} to
|
|
accommodate the unique file naming syntax that @value{tramp} requires.
|
|
|
|
The replacements dissect the file name, use the original handler for
|
|
the localname, take that result, and then re-build the @value{tramp}
|
|
file name. By relying on the original handlers for localnames,
|
|
@value{tramp} benefits from platform specific hacks to the original
|
|
handlers.
|
|
|
|
|
|
@ifset emacs
|
|
@node External packages
|
|
@section Integrating with external Lisp packages
|
|
@subsection File name completion.
|
|
|
|
For name completions in the minibuffer, @value{tramp} depends on the
|
|
last input character to decide whether to look for method name
|
|
completion or host name completion. For example, @kbd{C-x C-f
|
|
@value{prefix}ssh@value{postfixhop} @key{TAB}} is not entirely clear
|
|
if @option{ssh} is a method or a host name. But if the last input
|
|
character was either @key{TAB}, @key{SPACE} or @kbd{?}, then
|
|
@value{tramp} favors file name completion over host name completion.
|
|
|
|
What about external packages using other characters to trigger file
|
|
name completions? They must somehow signal this to @value{tramp}. Use
|
|
the variable @code{non-essential} temporarily and bind it to
|
|
non-@code{nil} value.
|
|
|
|
@lisp
|
|
(let ((non-essential t))
|
|
@dots{})
|
|
@end lisp
|
|
|
|
|
|
@subsection File attributes cache.
|
|
|
|
Keeping a local cache of remote file attributes in sync with the
|
|
remote host is a time-consuming operation. Flushing and re-querying
|
|
these attributes can tax @value{tramp} to a grinding halt on busy
|
|
remote servers.
|
|
|
|
To get around these types of slow-downs in @value{tramp}'s
|
|
responsiveness, set the @code{process-file-side-effects} to @code{nil}
|
|
to stop @value{tramp} from flushing the cache. This is helpful in
|
|
situations where callers to @code{process-file} know there are no file
|
|
attribute changes. The let-bind form to accomplish this:
|
|
|
|
@lisp
|
|
(let (process-file-side-effects)
|
|
@dots{})
|
|
@end lisp
|
|
|
|
For asynchronous processes, @value{tramp} uses a process sentinel to
|
|
flush file attributes cache. When callers to @code{start-file-process}
|
|
know beforehand no file attribute changes are expected, then the
|
|
process sentinel should be set to the default state. In cases where
|
|
the caller defines its own process sentinel, @value{tramp}'s process
|
|
sentinel is overwritten. The caller can still flush the file
|
|
attributes cache in its process sentinel with this code:
|
|
|
|
@lisp
|
|
(unless (memq (process-status proc) '(run open))
|
|
(dired-uncache remote-directory))
|
|
@end lisp
|
|
|
|
Since @value{tramp} traverses subdirectories starting with the
|
|
root-directory, it is most likely sufficient to make the
|
|
@code{default-directory} of the process buffer as the root directory.
|
|
@end ifset
|
|
|
|
|
|
@node Traces and Profiles
|
|
@chapter How to Customize Traces
|
|
|
|
@value{tramp} messages are raised with verbosity levels ranging from 0
|
|
to 10. @value{tramp} does not display all messages; only those with a
|
|
verbosity level less than or equal to @code{tramp-verbose}.
|
|
|
|
The verbosity levels are
|
|
|
|
@w{ 0} silent (no @value{tramp} messages at all)
|
|
@*@indent @w{ 1} errors
|
|
@*@indent @w{ 2} warnings
|
|
@*@indent @w{ 3} connection to remote hosts (default verbosity)
|
|
@*@indent @w{ 4} activities
|
|
@*@indent @w{ 5} internal
|
|
@*@indent @w{ 6} sent and received strings
|
|
@*@indent @w{ 7} file caching
|
|
@*@indent @w{ 8} connection properties
|
|
@*@indent @w{ 9} test commands
|
|
@*@indent @w{10} traces (huge)
|
|
|
|
With @code{tramp-verbose} greater than or equal to 4, messages are
|
|
also written to a @value{tramp} debug buffer. Such debug buffers are
|
|
essential to bug and problem analyses. For @value{tramp} bug reports,
|
|
set the @code{tramp-verbose} level to 6 (@pxref{Bug Reports}).
|
|
|
|
The debug buffer is in
|
|
@ifinfo
|
|
@ref{Outline Mode, , , @value{emacsdir}}.
|
|
@end ifinfo
|
|
@ifnotinfo
|
|
Outline Mode.
|
|
@end ifnotinfo
|
|
In this buffer, messages can be filtered by their level. To see
|
|
messages up to verbosity level 5, enter @kbd{C-u 6 C-c C-q}.
|
|
@ifinfo
|
|
Other navigation keys are described in
|
|
@ref{Outline Visibility, , , @value{emacsdir}}.
|
|
@end ifinfo
|
|
|
|
@value{tramp} handles errors internally. But to get a Lisp backtrace,
|
|
both the error and the signal have to be set as follows:
|
|
|
|
@lisp
|
|
(setq debug-on-error t
|
|
debug-on-signal t)
|
|
@end lisp
|
|
|
|
To enable stepping through @value{tramp} function call traces, they
|
|
have to be specifically enabled as shown in this code:
|
|
|
|
@lisp
|
|
(require 'trace)
|
|
(dolist (elt (all-completions "tramp-" obarray 'functionp))
|
|
(trace-function-background (intern elt)))
|
|
(untrace-function 'tramp-read-passwd)
|
|
(untrace-function 'tramp-gw-basic-authentication)
|
|
@end lisp
|
|
|
|
The buffer @file{*trace-output*} contains the output from the function
|
|
call traces. Disable @code{tramp-read-passwd} and
|
|
@code{tramp-gw-basic-authentication} to stop password strings from
|
|
being written to @file{*trace-output*}.
|
|
|
|
|
|
@node Issues
|
|
@chapter Debatable Issues and What Was Decided
|
|
|
|
@itemize @bullet
|
|
@item The uuencode method does not always work.
|
|
|
|
@command{uudecode} on some systems cannot write to stdout, but
|
|
@value{tramp} depends on encoding and decoding programs to be able to
|
|
read from stdin and write to stdout.
|
|
|
|
We can find ways to circumvent @command{uudecode}'s ability to write
|
|
to stdout, such as writing to a temporary file and then piping that to
|
|
stdout.
|
|
|
|
But I have decided not to implement workarounds as they are too
|
|
fragile to work reliably. Some on systems, @value{tramp} will not have
|
|
uuencode method.
|
|
|
|
@item The @value{tramp} file name syntax differs between Emacs and XEmacs.
|
|
|
|
The Emacs maintainers wish to use a unified file name syntax for
|
|
Ange-FTP and @value{tramp} so that users don't have to learn yet
|
|
another syntax though it is okay to learn new extensions.
|
|
|
|
For the XEmacs maintainers, the disruption from a unified file name
|
|
syntax are not worth the gains. Firstly, the XEmacs package system
|
|
relies on EFS for downloading new packages and therefore is already
|
|
installed. On the other hand, @value{tramp} is not installed by
|
|
default in XEmacs. Unifying will require @value{tramp} installed from
|
|
the start.
|
|
|
|
@ifset xemacs
|
|
@strong{Note:} To make the syntax similar to @value{ftppackagename},
|
|
make this change to the init file:
|
|
|
|
@lisp
|
|
(setq tramp-unified-filenames t)
|
|
(require 'tramp)
|
|
@end lisp
|
|
|
|
To disable auto loading @value{emacsname} @value{tramp} package, set
|
|
file permissions of
|
|
@file{@dots{}/xemacs-packages/lisp/tramp/auto-autoloads.el*} to
|
|
@code{000}.
|
|
|
|
When using unified file names, @value{emacsname} download sites are
|
|
added to @code{tramp-default-method-alist} with default method of
|
|
@option{ftp} @xref{Default Method} for proper working of the
|
|
@value{emacsname} package system.
|
|
|
|
The syntax for unified file names is described in the @value{tramp} manual
|
|
for @value{emacsothername}.
|
|
@end ifset
|
|
@end itemize
|
|
|
|
|
|
@node GNU Free Documentation License
|
|
@appendix GNU Free Documentation License
|
|
@include doclicense.texi
|
|
|
|
|
|
@node Function Index
|
|
@unnumbered Function Index
|
|
@printindex fn
|
|
|
|
|
|
@node Variable Index
|
|
@unnumbered Variable Index
|
|
@printindex vr
|
|
|
|
|
|
@node Concept Index
|
|
@unnumbered Concept Index
|
|
@printindex cp
|
|
|
|
@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 * Consistent small or capitalized words especially in menus.
|
|
@c * Make a unique declaration of @trampfn.
|