tramp.texi 90.5 KB
Newer Older
Kai Großjohann's avatar
Kai Großjohann committed
1 2
\input texinfo   @c -*-texinfo-*-
@c %**start of header
David Kastrup's avatar
David Kastrup committed
3
@setfilename ../info/tramp
Kai Großjohann's avatar
Kai Großjohann committed
4 5 6 7 8 9 10
@settitle TRAMP User Manual
@setchapternewpage odd
@c %**end of header

@c This is *so* much nicer :)
@footnotestyle end

11 12 13
@c In the Tramp CVS, the version number is auto-frobbed from
@c configure.ac, so you should edit that file and run
@c "autoconf && ./configure" to change the version number.
14 15 16 17

@c Additionally, flags are set with respect to the Emacs flavor; and
@c depending whether Tramp is packaged into (X)Emacs, or standalone.

18
@include trampver.texi
Kai Großjohann's avatar
Kai Großjohann committed
19

20
@c Macros for formatting a filename.
Kai Großjohann's avatar
Kai Großjohann committed
21
@c trampfn is for a full filename, trampfnmhp means method, host, localname
22
@c were given, and so on.
Kai Großjohann's avatar
Kai Großjohann committed
23
@macro trampfn(method, user, host, localname)
24
@value{prefix}@value{method}@value{user}@@@value{host}@value{postfix}@value{localname}
25
@end macro
Kai Großjohann's avatar
Kai Großjohann committed
26

27
@copying
Glenn Morris's avatar
Glenn Morris committed
28
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
Michael Albinus's avatar
Michael Albinus committed
29
Free Software Foundation, Inc.
30

31
@quotation
32
Permission is granted to copy, distribute and/or modify this document
33
under the terms of the GNU Free Documentation License, Version 1.2 or
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying

51
@c Entries for @command{install-info} to use
52
@dircategory @value{emacsname}
53 54
@direntry
* TRAMP: (tramp).                Transparent Remote Access, Multiple Protocol
55
                                 @value{emacsname} remote file access via rsh and rcp.
56 57
@end direntry

Kai Großjohann's avatar
Kai Großjohann committed
58 59 60
@tex

@titlepage
61
@title @value{tramp} version @value{trampver} User Manual
Kai Großjohann's avatar
Kai Großjohann committed
62 63 64

@author by Daniel Pittman
@author based on documentation by Kai Gro@ss{}johann
65

Kai Großjohann's avatar
Kai Großjohann committed
66
@page
67
@insertcopying
Kai Großjohann's avatar
Kai Großjohann committed
68 69 70 71 72 73 74

@end titlepage
@page

@end tex

@ifnottex
75
@node Top, Overview, (dir), (dir)
76
@top @value{tramp} version @value{trampver} User Manual
77

78 79
This file documents @value{tramp} version @value{trampver}, a remote file
editing package for @value{emacsname}.
Kai Großjohann's avatar
Kai Großjohann committed
80

81
@value{tramp} stands for `Transparent Remote (file) Access, Multiple
Kai Großjohann's avatar
Kai Großjohann committed
82
Protocol'.  This package provides remote file editing, similar to
83
@value{ftppackagename}.
Kai Großjohann's avatar
Kai Großjohann committed
84

85 86
The difference is that @value{ftppackagename} uses FTP to transfer
files between the local and the remote host, whereas @value{tramp} uses a
87 88
combination of @command{rsh} and @command{rcp} or other work-alike
programs, such as @command{ssh}/@command{scp}.
Kai Großjohann's avatar
Kai Großjohann committed
89 90

You can find the latest version of this document on the web at
Michael Albinus's avatar
Michael Albinus committed
91
@uref{http://www.gnu.org/software/tramp/}.
Kai Großjohann's avatar
Kai Großjohann committed
92

93
@c Pointer to the other Emacs flavor is necessary only in case of
94 95 96 97 98 99 100 101
@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
Juanma Barranquero's avatar
Juanma Barranquero committed
102
If you're using the other Emacs flavor, you should read the
103 104
@uref{@value{emacsotherfilename}, @value{emacsothername}} pages.
@end ifhtml
105 106
@end ifset

Kai Großjohann's avatar
Kai Großjohann committed
107
@ifhtml
108
@ifset jamanual
109
This manual is also available as a @uref{@value{japanesemanual},
110 111
Japanese translation}.
@end ifset
Kai Großjohann's avatar
Kai Großjohann committed
112

113
The latest release of @value{tramp} is available for
Michael Albinus's avatar
Michael Albinus committed
114
@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
Michael Albinus's avatar
Michael Albinus committed
115 116
@ref{Obtaining Tramp} for more details, including the CVS server
details.
Kai Großjohann's avatar
Kai Großjohann committed
117

Michael Albinus's avatar
Michael Albinus committed
118
@value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/,
Kai Großjohann's avatar
Kai Großjohann committed
119 120 121
Savannah Project Page}.
@end ifhtml

122
There is a mailing list for @value{tramp}, available at
Michael Albinus's avatar
Michael Albinus committed
123 124 125
@email{tramp-devel@@gnu.org}, and archived at
@uref{http://lists.gnu.org/archive/html/tramp-devel/, the
@value{tramp} Mail Archive}.
126 127 128 129 130 131 132 133 134
@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
Kai Großjohann's avatar
Kai Großjohann committed
135

136 137
@insertcopying

Kai Großjohann's avatar
Kai Großjohann committed
138 139 140
@end ifnottex

@menu
141
* Overview::                    What @value{tramp} can and cannot do.
Kai Großjohann's avatar
Kai Großjohann committed
142 143

For the end user:
144

145 146 147 148
* Obtaining Tramp::             How to obtain @value{tramp}.
* History::                     History of @value{tramp}.
@ifset installchapter
* Installation::                Installing @value{tramp} with your @value{emacsname}.
149
@end ifset
150 151
* Configuration::               Configuring @value{tramp} for use.
* Usage::                       An overview of the operation of @value{tramp}.
152
* Bug Reports::                 Reporting Bugs and Problems.
Kai Großjohann's avatar
Kai Großjohann committed
153
* Frequently Asked Questions::  Questions and answers from the mailing list.
154
* Concept Index::               An item for each concept.
Kai Großjohann's avatar
Kai Großjohann committed
155 156

For the developer:
157

Kai Großjohann's avatar
Kai Großjohann committed
158
* Version Control::             The inner workings of remote version control.
Kai Großjohann's avatar
Kai Großjohann committed
159
* Files directories and localnames::  How file names, directories and localnames are mangled and managed.
160
* Issues::                      Debatable Issues and What Was Decided.
Kai Großjohann's avatar
Kai Großjohann committed
161

Chong Yidong's avatar
Chong Yidong committed
162 163
* GNU Free Documentation License:: The license for this documentation.

Kai Großjohann's avatar
Kai Großjohann committed
164 165
@detailmenu
 --- The Detailed Node Listing ---
166
@c
167 168
@ifset installchapter
Installing @value{tramp} with your @value{emacsname}
169 170

* Installation parameters::     Parameters in order to control installation.
171
* Load paths::                  How to plug-in @value{tramp} into your environment.
172
* Japanese manual::             Japanese manual.
173 174

@end ifset
Kai Großjohann's avatar
Kai Großjohann committed
175

176
Configuring @value{tramp} for use
Kai Großjohann's avatar
Kai Großjohann committed
177 178 179 180 181 182 183

* Connection types::            Types of connections made to remote machines.
* Inline methods::              Inline methods.
* External transfer methods::   External transfer methods.
* Multi-hop Methods::           Connecting to a remote host using multiple hops.
* Default Method::              Selecting a default method.
* Customizing Methods::         Using Non-Standard Methods.
184
* Customizing Completion::      Selecting config files for user/host name completion.
185
* Password caching::            Reusing passwords for several connections.
186
* Remote Programs::             How @value{tramp} finds and uses programs on the remote machine.
187 188
* Remote shell setup::          Remote shell setup hints.
* Windows setup hints::         Issues with Cygwin ssh.
189
* Auto-save and Backup::        Auto-save and Backup.
Kai Großjohann's avatar
Kai Großjohann committed
190

191
Using @value{tramp}
Kai Großjohann's avatar
Kai Großjohann committed
192

193
* Filename Syntax::             @value{tramp} filename conventions.
194 195 196
* Multi-hop filename syntax::   Multi-hop filename conventions.
* Filename completion::         Filename completion.
* Dired::                       Dired.
Michael Albinus's avatar
Michael Albinus committed
197
* Compilation::                 Compile remote files.
Kai Großjohann's avatar
Kai Großjohann committed
198 199 200 201 202 203 204

The inner workings of remote version control

* Version Controlled Files::    Determining if a file is under version control.
* Remote Commands::             Executing the version control commands on the remote machine.
* Changed workfiles::           Detecting if the working file has changed.
* Checking out files::          Bringing the workfile out of the repository.
205
* Miscellaneous Version Control::  Things related to Version Control that don't fit elsewhere.
Kai Großjohann's avatar
Kai Großjohann committed
206 207 208 209 210 211

Things related to Version Control that don't fit elsewhere

* Remote File Ownership::       How VC determines who owns a workfile.
* Back-end Versions::           How VC determines what release your RCS is.

212
How file names, directories and localnames are mangled and managed
Kai Großjohann's avatar
Kai Großjohann committed
213

214
* Localname deconstruction::    Breaking a localname into its components.
Kai Großjohann's avatar
Kai Großjohann committed
215 216 217 218 219

@end detailmenu
@end menu

@node Overview
220
@chapter An overview of @value{tramp}
221
@cindex overview
Kai Großjohann's avatar
Kai Großjohann committed
222

Michael Albinus's avatar
Michael Albinus committed
223 224 225 226
After the installation of @value{tramp} into your @value{emacsname},
you will be able to access files on remote machines as though they
were local.  Access to the remote file system for editing files,
version control, and @code{dired} are transparently enabled.
Kai Großjohann's avatar
Kai Großjohann committed
227 228 229

Your access to the remote machine can be with the @command{rsh},
@command{rlogin}, @command{telnet} programs or with any similar
230 231
connection method.  This connection must pass @acronym{ASCII}
successfully to be usable but need not be 8-bit clean.
Kai Großjohann's avatar
Kai Großjohann committed
232 233

The package provides support for @command{ssh} connections out of the
234 235 236
box, one of the more common uses of the package.  This allows
relatively secure access to machines, especially if @command{ftp}
access is disabled.
Kai Großjohann's avatar
Kai Großjohann committed
237

238
The majority of activity carried out by @value{tramp} requires only that
239
the remote login is possible and is carried out at the terminal.  In
240
order to access remote files @value{tramp} needs to transfer their content
241
to the local machine temporarily.
Kai Großjohann's avatar
Kai Großjohann committed
242

243
@value{tramp} can transfer files between the machines in a variety of ways.
244 245
The details are easy to select, depending on your needs and the
machines in question.
Kai Großjohann's avatar
Kai Großjohann committed
246

247 248
The fastest transfer methods (for large files) rely on a remote file
transfer package such as @command{rcp}, @command{scp} or
249
@command{rsync}.
Kai Großjohann's avatar
Kai Großjohann committed
250

251
If the remote copy methods are not suitable for you, @value{tramp} also
252 253 254 255
supports the use of encoded transfers directly through the shell.
This requires that the @command{mimencode} or @command{uuencode} tools
are available on the remote machine.  These methods are generally
faster for small files.
Kai Großjohann's avatar
Kai Großjohann committed
256

257
Within these limitations, @value{tramp} is quite powerful.  It is worth
258 259 260
noting that, as of the time of writing, it is far from a polished
end-user product.  For a while yet you should expect to run into rough
edges and problems with the code now and then.
Kai Großjohann's avatar
Kai Großjohann committed
261 262 263 264 265

It is finished enough that the developers use it for day to day work but
the installation and setup can be a little difficult to master, as can
the terminology.

266 267
@value{tramp} is still under active development and any problems you encounter,
trivial or major, should be reported to the @value{tramp} developers.
Kai Großjohann's avatar
Kai Großjohann committed
268 269 270 271
@xref{Bug Reports}.


@subsubheading Behind the scenes
272
@cindex behind the scenes
Kai Großjohann's avatar
Kai Großjohann committed
273 274
@cindex details of operation
@cindex how it works
Kai Großjohann's avatar
Kai Großjohann committed
275 276

This section tries to explain what goes on behind the scenes when you
277
access a remote file through @value{tramp}.
Kai Großjohann's avatar
Kai Großjohann committed
278

279
Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name,
Kai Großjohann's avatar
Kai Großjohann committed
280
then hit @kbd{@key{TAB}} for completion.  Suppose further that this is
281
the first time that @value{tramp} is invoked for the host in question.  Here's
Kai Großjohann's avatar
Kai Großjohann committed
282 283 284 285
what happens:

@itemize
@item
286
@value{tramp} discovers that it needs a connection to the host.  So it
287 288
invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
@var{user}} or a similar tool to connect to the remote host.
289
Communication with this process happens through an
290
@value{emacsname} buffer, that is, the output from the remote end
291
goes into a buffer.
Kai Großjohann's avatar
Kai Großjohann committed
292 293

@item
Michael Albinus's avatar
Michael Albinus committed
294 295 296
The remote host may prompt for a login name (for @command{telnet}).
The login name is given in the file name, so @value{tramp} sends the
login name and a newline.
Kai Großjohann's avatar
Kai Großjohann committed
297 298 299 300

@item
The remote host may prompt for a password or pass phrase (for
@command{rsh} or for @command{telnet} after sending the login name).
301
@value{tramp} displays the prompt in the minibuffer, asking you for the
Kai Großjohann's avatar
Kai Großjohann committed
302 303
password or pass phrase.

304
You enter the password or pass phrase.  @value{tramp} sends it to the remote
Kai Großjohann's avatar
Kai Großjohann committed
305 306 307
host, followed by a newline.

@item
308
@value{tramp} now waits for the shell prompt or for a message that the login
Kai Großjohann's avatar
Kai Großjohann committed
309 310
failed.

311
If @value{tramp} sees neither of them after a certain period of time (a minute,
Kai Großjohann's avatar
Kai Großjohann committed
312 313 314
say), then it issues an error message saying that it couldn't find the
remote shell prompt and shows you what the remote host has sent.

315
If @value{tramp} sees a @samp{login failed} message, it tells you so,
316
aborts the login attempt and allows you to try again.
Kai Großjohann's avatar
Kai Großjohann committed
317 318

@item
319 320
Suppose that the login was successful and @value{tramp} sees the shell prompt
from the remote host.  Now @value{tramp} invokes @command{/bin/sh} because
Kai Großjohann's avatar
Kai Großjohann committed
321 322
Bourne shells and C shells have different command
syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login
323
shell doesn't recognize @samp{exec /bin/sh} as a valid command.
Kai Großjohann's avatar
Kai Großjohann committed
324 325
Maybe you use the Scheme shell @command{scsh}@dots{}}

326
After the Bourne shell has come up, @value{tramp} sends a few commands to
Kai Großjohann's avatar
Kai Großjohann committed
327 328 329 330 331
ensure a good working environment.  It turns off echoing, it sets the
shell prompt, and a few other things.

@item
Now the remote shell is up and it good working order.  Remember, what
332
was supposed to happen is that @value{tramp} tries to find out what files exist
Kai Großjohann's avatar
Kai Großjohann committed
333 334
on the remote host so that it can do filename completion.

335
So, @value{tramp} basically issues @command{cd} and @command{ls} commands and
Kai Großjohann's avatar
Kai Großjohann committed
336 337 338 339 340 341 342 343 344 345 346
also sometimes @command{echo} with globbing.  Another command that is
often used is @command{test} to find out whether a file is writable or a
directory or the like.  The output of each command is parsed for the
necessary operation.

@item
Suppose you are finished with filename completion, have entered @kbd{C-x
C-f}, a full file name and hit @kbd{@key{RET}}.  Now comes the time to
transfer the file contents from the remote host to the local host so
that you can edit them.

347
See above for an explanation of how @value{tramp} transfers the file contents.
Kai Großjohann's avatar
Kai Großjohann committed
348

349
For inline transfers, @value{tramp} issues a command like @samp{mimencode -b
Kai Großjohann's avatar
Kai Großjohann committed
350 351 352 353
/path/to/remote/file}, waits until the output has accumulated in the
buffer that's used for communication, then decodes that output to
produce the file contents.

354
For out-of-band transfers, @value{tramp} issues a command like the following:
355 356 357 358 359
@example
rcp user@@host:/path/to/remote/file /tmp/tramp.4711
@end example
It then reads the local temporary file @file{/tmp/tramp.4711} into a
buffer and deletes the temporary file.
Kai Großjohann's avatar
Kai Großjohann committed
360 361 362 363 364 365 366

@item
You now edit the buffer contents, blithely unaware of what has happened
behind the scenes.  (Unless you have read this section, that is.)  When
you are finished, you type @kbd{C-x C-s} to save the buffer.

@item
367
Again, @value{tramp} transfers the file contents to the remote host either
Kai Großjohann's avatar
Kai Großjohann committed
368 369 370 371 372
inline or out-of-band.  This is the reverse of what happens when reading
the file.
@end itemize

I hope this has provided you with a basic overview of what happens
373
behind the scenes when you open a file with @value{tramp}.
Kai Großjohann's avatar
Kai Großjohann committed
374 375 376


@c For the end user
377 378 379
@node Obtaining Tramp
@chapter Obtaining Tramp.
@cindex obtaining Tramp
Kai Großjohann's avatar
Kai Großjohann committed
380

Michael Albinus's avatar
Michael Albinus committed
381 382
@value{tramp} is freely available on the Internet and the latest
release may be downloaded from
Michael Albinus's avatar
Michael Albinus committed
383
@uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
Michael Albinus's avatar
Michael Albinus committed
384 385 386 387 388
documentation and code for @value{tramp}, suitable for installation.
But GNU Emacs (22 or later) includes @value{tramp} already, and there
is a @value{tramp} package for XEmacs, as well.  So maybe it is easier
to just use those.  But if you want the bleeding edge, read
on@dots{...}
Kai Großjohann's avatar
Kai Großjohann committed
389

390
For the especially brave, @value{tramp} is available from CVS.  The CVS
391 392
version is the latest version of the code and may contain incomplete
features or new issues. Use these versions at your own risk.
Kai Großjohann's avatar
Kai Großjohann committed
393

394
Instructions for obtaining the latest development version of @value{tramp}
395
from CVS can be found by going to the Savannah project page at the
396 397
following URL and then clicking on the CVS link in the navigation bar
at the top.
398 399

@noindent
Michael Albinus's avatar
Michael Albinus committed
400
@uref{http://savannah.gnu.org/projects/tramp/}
401 402 403

@noindent
Or follow the example session below:
Kai Großjohann's avatar
Kai Großjohann committed
404 405

@example
406
] @strong{cd ~/@value{emacsdir}}
407
] @strong{export CVS_RSH="ssh"}
Michael Albinus's avatar
Michael Albinus committed
408
] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
Kai Großjohann's avatar
Kai Großjohann committed
409 410
@end example

411
@noindent
412 413
You should now have a directory @file{~/@value{emacsdir}/tramp}
containing the latest version of @value{tramp}. You can fetch the latest
414
updates from the repository by issuing the command:
Kai Großjohann's avatar
Kai Großjohann committed
415 416

@example
417
] @strong{cd ~/@value{emacsdir}/tramp}
418
] @strong{export CVS_RSH="ssh"}
Kai Großjohann's avatar
Kai Großjohann committed
419 420 421
] @strong{cvs update -d}
@end example

422 423 424 425 426 427
@noindent
Once you've got updated files from the CVS repository, you need to run
@command{autoconf} in order to get an up-to-date @file{configure}
script:

@example
428
] @strong{cd ~/@value{emacsdir}/tramp}
429 430 431
] @strong{autoconf}
@end example

Kai Großjohann's avatar
Kai Großjohann committed
432 433

@node History
434
@chapter History of @value{tramp}
435 436
@cindex history
@cindex development history
Kai Großjohann's avatar
Kai Großjohann committed
437 438

Development was started end of November 1998.  The package was called
439 440 441
@file{rssh.el}, back then.  It only provided one method to access a
file, using @command{ssh} to log in to a remote host and using
@command{scp} to transfer the file contents.  After a while, the name
442
was changed to @file{rcp.el}, and now it's @value{tramp}.  Along the way,
443 444
many more methods for getting a remote shell and for transferring the
file contents were added.  Support for VC was added.
Kai Großjohann's avatar
Kai Großjohann committed
445

446
The most recent addition of major features were the multi-hop methods
447
added in April 2000 and the unification of @value{tramp} and Ange-FTP
448
filenames in July 2002.
Kai Großjohann's avatar
Kai Großjohann committed
449

450 451
@c Installation chapter is necessary only in case of standalone
@c installation.  Text taken from trampinst.texi.
452 453
@ifset installchapter
@include trampinst.texi
454
@end ifset
Kai Großjohann's avatar
Kai Großjohann committed
455 456

@node Configuration
457
@chapter Configuring @value{tramp} for use
458
@cindex configuration
Kai Großjohann's avatar
Kai Großjohann committed
459

460
@cindex default configuration
461 462 463 464
@value{tramp} is (normally) fully functional when it is initially
installed.  It is initially configured to use the @command{scp}
program to connect to the remote host.  So in the easiest case, you
just type @kbd{C-x C-f} and then enter the filename
465
@file{@value{prefix}@var{user}@@@var{machine}@value{postfix}@var{/path/to.file}}.
Kai Großjohann's avatar
Kai Großjohann committed
466 467 468 469 470

On some hosts, there are problems with opening a connection.  These are
related to the behavior of the remote shell.  See @xref{Remote shell
setup}, for details on this.

471 472
If you do not wish to use these commands to connect to the remote
host, you should change the default connection and transfer method
473
that @value{tramp} uses.  There are several different methods that @value{tramp}
474 475
can use to connect to remote machines and transfer files
(@pxref{Connection types}).
Kai Großjohann's avatar
Kai Großjohann committed
476

477 478 479
If you don't know which method is right for you, see @xref{Default
Method}.

Kai Großjohann's avatar
Kai Großjohann committed
480 481 482 483 484 485 486

@menu
* Connection types::            Types of connections made to remote machines.
* Inline methods::              Inline methods.
* External transfer methods::   External transfer methods.
* Multi-hop Methods::           Connecting to a remote host using multiple hops.
* Default Method::              Selecting a default method.
487 488 489
                                  Here we also try to help those who
                                  don't have the foggiest which method
                                  is right for them.
Kai Großjohann's avatar
Kai Großjohann committed
490
* Customizing Methods::         Using Non-Standard Methods.
491
* Customizing Completion::      Selecting config files for user/host name completion.
492
* Password caching::            Reusing passwords for several connections.
493
* Remote Programs::             How @value{tramp} finds and uses programs on the remote machine.
Kai Großjohann's avatar
Kai Großjohann committed
494 495
* Remote shell setup::          Remote shell setup hints.
* Windows setup hints::         Issues with Cygwin ssh.
496
* Auto-save and Backup::        Auto-save and Backup.
Kai Großjohann's avatar
Kai Großjohann committed
497 498 499 500 501
@end menu


@node Connection types
@section Types of connections made to remote machines.
502
@cindex connection types, overview
Kai Großjohann's avatar
Kai Großjohann committed
503 504

There are two basic types of transfer methods, each with its own
505
advantages and limitations.  Both types of connection make use of a
Kai Großjohann's avatar
Kai Großjohann committed
506 507 508
remote shell access program such as @command{rsh}, @command{ssh} or
@command{telnet} to connect to the remote machine.

509
This connection is used to perform many of the operations that @value{tramp}
Kai Großjohann's avatar
Kai Großjohann committed
510 511 512 513
requires to make the remote file system transparently accessible from
the local machine. It is only when visiting files that the methods
differ.

514 515 516 517 518 519 520 521
@cindex inline methods
@cindex external transfer methods
@cindex external methods
@cindex out-of-band methods
@cindex methods, inline
@cindex methods, external transfer
@cindex methods, out-of-band
Loading or saving a remote file requires that the content of the file
522 523 524
be transfered between the two machines. The content of the file can be
transfered over the same connection used to log in to the remote
machine or the file can be transfered through another connection using
525 526 527 528
a remote copy program such as @command{rcp}, @command{scp} or
@command{rsync}.  The former are called @dfn{inline methods}, the
latter are called @dfn{out-of-band methods} or @dfn{external transfer
methods} (@dfn{external methods} for short).
Kai Großjohann's avatar
Kai Großjohann committed
529 530

The performance of the external transfer methods is generally better
531 532 533
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.
Kai Großjohann's avatar
Kai Großjohann committed
534 535 536 537 538 539

The one exception to this rule are the @command{scp} based transfer
methods.  While these methods do see better performance when actually
transferring files, the overhead of the cryptographic negotiation at
startup may drown out the improvement in file transfer times.

540 541 542 543
External transfer methods should be configured such a way that they
don't require a password (with @command{ssh-agent}, or such alike).
If it isn't possible, you should consider @ref{Password caching},
otherwise you will be prompted for a password every copy action.
Kai Großjohann's avatar
Kai Großjohann committed
544

545 546
@cindex multi-hop methods
@cindex methods, multi-hop
Kai Großjohann's avatar
Kai Großjohann committed
547 548 549 550 551 552 553 554 555
A variant of the inline methods are the @dfn{multi-hop methods}.
These methods allow you to connect a remote host using a number `hops',
each of which connects to a different host.  This is useful if you are
in a secured network where you need to go through a bastion host to
connect to the outside world.


@node Inline methods
@section Inline methods
556 557
@cindex inline methods
@cindex methods, inline
Kai Großjohann's avatar
Kai Großjohann committed
558

559
The inline methods in @value{tramp} are quite powerful and can work in
Kai Großjohann's avatar
Kai Großjohann committed
560 561 562 563 564 565 566
situations where you cannot use an external transfer program to connect.
Inline methods are the only methods that work when connecting to the
remote machine via telnet.  (There are also strange inline methods which
allow you to transfer files between @emph{user identities} rather than
hosts, see below.)

These methods depend on the existence of a suitable encoding and
567 568
decoding command on remote machine.  Locally, @value{tramp} may be able to
use features of @value{emacsname} to decode and encode the files or
569
it may require access to external commands to perform that task.
Kai Großjohann's avatar
Kai Großjohann committed
570

571 572 573
@cindex uuencode
@cindex mimencode
@cindex base-64 encoding
574
@value{tramp} checks the availability and usability of commands like
575 576 577 578
@command{mimencode} (part of the @command{metamail} package) or
@command{uuencode} on the remote host.  The first reliable command
will be used.  The search path can be customized, see @ref{Remote
Programs}.
Kai Großjohann's avatar
Kai Großjohann committed
579

580
If both commands aren't available on the remote host, @value{tramp}
581 582
transfers a small piece of Perl code to the remote host, and tries to
apply it for encoding and decoding.
Kai Großjohann's avatar
Kai Großjohann committed
583 584


585 586 587 588
@table @asis
@item @option{rsh}
@cindex method rsh
@cindex rsh method
Kai Großjohann's avatar
Kai Großjohann committed
589

590 591
Connect to the remote host with @command{rsh}.  Due to the unsecure
connection it is recommended for very local host topology only.
Kai Großjohann's avatar
Kai Großjohann committed
592

593 594 595 596
On operating systems which provide the command @command{remsh} instead
of @command{rsh}, you can use the method @option{remsh}.  This is true
for HP-UX or Cray UNICOS, for example.

Kai Großjohann's avatar
Kai Großjohann committed
597

598 599 600
@item @option{ssh}
@cindex method ssh
@cindex ssh method
Kai Großjohann's avatar
Kai Großjohann committed
601

602 603 604
Connect to the remote host with @command{ssh}.  This is identical to
the previous option except that the @command{ssh} package is used,
making the connection more secure.
Kai Großjohann's avatar
Kai Großjohann committed
605

606 607
There are also two variants, @option{ssh1} and @option{ssh2}, that
call @samp{ssh -1} and @samp{ssh -2}, respectively.  This way, you can
Kai Großjohann's avatar
Kai Großjohann committed
608 609 610
explicitly select whether you want to use the SSH protocol version 1
or 2 to connect to the remote host.  (You can also specify in
@file{~/.ssh/config}, the SSH configuration file, which protocol
611
should be used, and use the regular @option{ssh} method.)
Kai Großjohann's avatar
Kai Großjohann committed
612

613 614 615
Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
@command{ssh1} and @command{ssh2} commands explicitly.  If you don't
know what these are, you do not need these options.
Kai Großjohann's avatar
Kai Großjohann committed
616

617
All the methods based on @command{ssh} have an additional kludgy
618 619 620 621 622
feature: you can specify a host name which looks like @file{host#42}
(the real host name, then a hash sign, then a port number).  This
means to connect to the given host but to also pass @code{-p 42} as
arguments to the @command{ssh} command.

Kai Großjohann's avatar
Kai Großjohann committed
623

624 625 626
@item @option{telnet}
@cindex method telnet
@cindex telnet method
Kai Großjohann's avatar
Kai Großjohann committed
627

628 629
Connect to the remote host with @command{telnet}.  This is as unsecure
as the @option{rsh} method.
Kai Großjohann's avatar
Kai Großjohann committed
630 631


632
@item @option{su}
633 634
@cindex method su
@cindex su method
Kai Großjohann's avatar
Kai Großjohann committed
635

636 637
This method does not connect to a remote host at all, rather it uses
the @command{su} program to allow you to edit files as another user.
Kai Großjohann's avatar
Kai Großjohann committed
638 639


640 641 642
@item @option{sudo}
@cindex method sudo
@cindex sudo method
Kai Großjohann's avatar
Kai Großjohann committed
643

644
This is similar to the @option{su} method, but it uses @command{sudo}
Kai Großjohann's avatar
Kai Großjohann committed
645 646 647 648
rather than @command{su} to become a different user.

Note that @command{sudo} must be configured to allow you to start a
shell as the user.  It would be nice if it was sufficient if
649 650
@command{ls} and @command{mimencode} were allowed, but that is not
easy to implement, so I haven't got around to it, yet.
Kai Großjohann's avatar
Kai Großjohann committed
651 652


653 654 655
@item @option{sshx}
@cindex method sshx
@cindex sshx method
Kai Großjohann's avatar
Kai Großjohann committed
656

657
As you would expect, this is similar to @option{ssh}, only a little
658
different.  Whereas @option{ssh} opens a normal interactive shell on
659
the remote host, this option uses @samp{ssh -t -t @var{host} -l
660
@var{user} /bin/sh} to open a connection.  This is useful for users
661 662
where the normal login shell is set up to ask them a number of
questions when logging in.  This procedure avoids these questions, and
663
just gives @value{tramp} a more-or-less `standard' login shell to work
664
with.
Kai Großjohann's avatar
Kai Großjohann committed
665

666 667 668
Note that this procedure does not eliminate questions asked by
@command{ssh} itself.  For example, @command{ssh} might ask ``Are you
sure you want to continue connecting?'' if the host key of the remote
669
host is not known.  @value{tramp} does not know how to deal with such a
670 671 672
question (yet), therefore you will need to make sure that you can log
in without such questions.

Kai Großjohann's avatar
Kai Großjohann committed
673
This is also useful for Windows users where @command{ssh}, when
674
invoked from an @value{emacsname} buffer, tells them that it is not
675
allocating a pseudo tty.  When this happens, the login shell is wont
Michael Albinus's avatar
Michael Albinus committed
676 677 678
to not print any shell prompt, which confuses @value{tramp} mightily.
For reasons unknown, some Windows ports for @command{ssh} require the
doubled @samp{-t} option.
Kai Großjohann's avatar
Kai Großjohann committed
679

680
This supports the @samp{-p} kludge.
681

Kai Großjohann's avatar
Kai Großjohann committed
682

683 684 685 686
@item @option{krlogin}
@cindex method krlogin
@cindex km krlogin
@cindex Kerberos (with krlogin method)
Kai Großjohann's avatar
Kai Großjohann committed
687

688
This method is also similar to @option{ssh}.  It only uses the
Kai Großjohann's avatar
Kai Großjohann committed
689 690 691
@command{krlogin -x} command to log in to the remote host.


692 693 694
@item @option{plink}
@cindex method plink
@cindex plink method
Kai Großjohann's avatar
Kai Großjohann committed
695 696

This method is mostly interesting for Windows users using the PuTTY
697
implementation of SSH.  It uses @samp{plink -ssh} to log in to the
Kai Großjohann's avatar
Kai Großjohann committed
698 699
remote host.

700 701
Additionally, the method @option{plink1} is provided, which calls
@samp{plink -1 -ssh} in order to use SSH protocol version 1
702
explicitly.
703

Kai Großjohann's avatar
Kai Großjohann committed
704 705 706
CCC: Do we have to connect to the remote host once from the command
line to accept the SSH key?  Maybe this can be made automatic?

707
CCC: Does @command{plink} support the @samp{-p} option?  @value{tramp} will
708
support that, anyway.
709

710
@end table
Kai Großjohann's avatar
Kai Großjohann committed
711 712 713 714 715



@node External transfer methods
@section External transfer methods
716 717 718 719
@cindex methods, external transfer
@cindex methods, out-of-band
@cindex external transfer methods
@cindex out-of-band methods
Kai Großjohann's avatar
Kai Großjohann committed
720 721 722 723 724 725 726 727

The external transfer methods operate through multiple channels, using
the remote shell connection for many actions while delegating file
transfers to an external transfer utility.

This saves the overhead of encoding and decoding that multiplexing the
transfer through the one connection has with the inline methods.

728 729
If you want to use an external transfer method you should be able to
execute the transfer utility to copy files to and from the remote
Kai Großjohann's avatar
Kai Großjohann committed
730 731
machine without any interaction.

732
@cindex ssh-agent
Kai Großjohann's avatar
Kai Großjohann committed
733 734 735 736 737 738 739
This means that you will need to use @command{ssh-agent} if you use the
@command{scp} program for transfers, or maybe your version of
@command{scp} accepts a password on the command line.@footnote{PuTTY's
@command{pscp} allows you to specify the password on the command line.}
If you use @command{rsync} via @command{ssh} then the same rule must
apply to that connection.

740 741
If you cannot get an external method to run without asking for a
password you should consider @ref{Password caching}.
Kai Großjohann's avatar
Kai Großjohann committed
742 743


744
@table @asis
Kai Großjohann's avatar
Kai Großjohann committed
745
@item @option{rcp}  ---  @command{rsh} and @command{rcp}
746 747
@cindex method rcp
@cindex rcp method
Kai Großjohann's avatar
Kai Großjohann committed
748 749
@cindex rcp (with rcp method)
@cindex rsh (with rcp method)
Kai Großjohann's avatar
Kai Großjohann committed
750 751

This method uses the @command{rsh} and @command{rcp} commands to connect
752
to the remote machine and transfer files.  This is probably the fastest
Kai Großjohann's avatar
Kai Großjohann committed
753 754
connection method available.

755 756 757 758
The alternative method @option{remcp} uses the @command{remsh} and
@command{rcp} commands.  It should be applied on machines where
@command{remsh} is used instead of @command{rsh}.

Kai Großjohann's avatar
Kai Großjohann committed
759 760

@item @option{scp}  ---  @command{ssh} and @command{scp}
761 762
@cindex method scp
@cindex scp method
Kai Großjohann's avatar
Kai Großjohann committed
763 764
@cindex scp (with scp method)
@cindex ssh (with scp method)
Kai Großjohann's avatar
Kai Großjohann committed
765 766 767 768 769 770 771 772 773 774 775

Using @command{ssh} to connect to the remote host and @command{scp} to
transfer files between the machines is the best method for securely
connecting to a remote machine and accessing files.

The performance of this option is also quite good. It may be slower than
the inline methods when you often open and close small files however.
The cost of the cryptographic handshake at the start of an @command{scp}
session can begin to absorb the advantage that the lack of encoding and
decoding presents.

776 777 778 779 780
There are also two variants, @option{scp1} and @option{scp2}, that
call @samp{ssh -1} and @samp{ssh -2}, respectively.  This way, you can
explicitly select whether you want to use the SSH protocol version 1
or 2 to connect to the remote host.  (You can also specify in
@file{~/.ssh/config}, the SSH configuration file, which protocol
781
should be used, and use the regular @option{scp} method.)
782 783 784 785 786

Two other variants, @option{scp1_old} and @option{scp2_old}, use the
@command{ssh1} and @command{ssh2} commands explicitly.  If you don't
know what these are, you do not need these options.

787
All the @command{ssh} based methods support the kludgy @samp{-p}
788
feature where you can specify a port number to connect to in the host
789
name.  For example, the host name @file{host#42} tells @value{tramp} to
790
specify @samp{-p 42} in the argument list for @command{ssh}.
791

Kai Großjohann's avatar
Kai Großjohann committed
792 793

@item @option{rsync}  ---  @command{ssh} and @command{rsync}
794 795
@cindex method rsync
@cindex rsync method
Kai Großjohann's avatar
Kai Großjohann committed
796 797
@cindex rsync (with rsync method)
@cindex ssh (with rsync method)
Kai Großjohann's avatar
Kai Großjohann committed
798 799 800 801 802 803 804 805 806 807 808

Using the @command{ssh} command to connect securely to the remote
machine and the @command{rsync} command to transfer files is almost
identical to the @option{scp} method.

While @command{rsync} performs much better than @command{scp} when
transferring files that exist on both hosts, this advantage is lost if
the file exists only on one side of the connection.

The @command{rsync} based method may be considerably faster than the
@command{rcp} based methods when writing to the remote system. Reading
809
files to the local machine is no faster than with a direct copy.
Kai Großjohann's avatar
Kai Großjohann committed
810

811
This method supports the @samp{-p} hack.
812

Kai Großjohann's avatar
Kai Großjohann committed
813 814

@item @option{scpx} --- @command{ssh} and @command{scp}
815 816
@cindex method scpx
@cindex scpx method
Kai Großjohann's avatar
Kai Großjohann committed
817 818
@cindex scp (with scpx method)
@cindex ssh (with scpx method)
Kai Großjohann's avatar
Kai Großjohann committed
819

820
As you would expect, this is similar to @option{scp}, only a little
821 822 823 824 825
different.  Whereas @option{scp} opens a normal interactive shell on
the remote host, this option uses @samp{ssh -t -t @var{host} -l
@var{user} /bin/sh} to open a connection.  This is useful for users
where the normal login shell is set up to ask them a number of
questions when logging in.  This procedure avoids these questions, and
826
just gives @value{tramp} a more-or-less `standard' login shell to work
827
with.
Kai Großjohann's avatar
Kai Großjohann committed
828 829

This is also useful for Windows users where @command{ssh}, when
830
invoked from an @value{emacsname} buffer, tells them that it is not
831
allocating a pseudo tty.  When this happens, the login shell is wont
832
to not print any shell prompt, which confuses @value{tramp} mightily.
Kai Großjohann's avatar
Kai Großjohann committed
833

834
This method supports the @samp{-p} hack.
835

Kai Großjohann's avatar
Kai Großjohann committed
836

837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856
@item @option{scpc} --- @command{ssh} and @command{scp}
@cindex method scpx
@cindex scpx method
@cindex scp (with scpx method)
@cindex ssh (with scpx method)

Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
@option{ControlMaster}.  This allows @option{scp} to reuse an existing
@option{ssh} channel, which increases performance.

Before you use this method, you shall check whether your @option{ssh}
implementation does support this option.  Try from the command line

@example
ssh localhost -o ControlMaster=yes
@end example

This method supports the @samp{-p} hack.


Kai Großjohann's avatar
Kai Großjohann committed
857
@item @option{pscp} --- @command{plink} and @command{pscp}
858 859
@cindex method pscp
@cindex pscp method
Kai Großjohann's avatar
Kai Großjohann committed
860 861 862
@cindex pscp (with pscp method)
@cindex plink (with pscp method)
@cindex PuTTY (with pscp method)
Kai Großjohann's avatar
Kai Großjohann committed
863 864 865 866 867 868

This method is similar to @option{scp}, but it uses the
@command{plink} command to connect to the remote host, and it uses
@command{pscp} for transferring the files.  These programs are part
of PuTTY, an SSH implementation for Windows.

869
CCC: Does @command{plink} support the @samp{-p} hack?
870

Kai Großjohann's avatar
Kai Großjohann committed
871 872

@item @option{fcp} --- @command{fsh} and @command{fcp}
873 874
@cindex method fcp
@cindex fcp method
Kai Großjohann's avatar
Kai Großjohann committed
875 876
@cindex fsh (with fcp method)
@cindex fcp (with fcp method)
Kai Großjohann's avatar
Kai Großjohann committed
877 878 879 880 881 882 883 884 885 886

This method is similar to @option{scp}, but it uses the @command{fsh}
command to connect to the remote host, and it uses @command{fcp} for
transferring the files.  @command{fsh/fcp} are a front-end for
@command{ssh} which allow for reusing the same @command{ssh} session
for submitting several commands.  This avoids the startup overhead of
@command{scp} (which has to establish a secure connection whenever it
is called).  Note, however, that you can also use one of the inline
methods to achieve a similar effect.

887 888 889
This method uses the command @samp{fsh @var{host} -l @var{user}
/bin/sh -i} to establish the connection, it does not work to just say
@command{fsh @var{host} -l @var{user}}.
Kai Großjohann's avatar
Kai Großjohann committed
890

Kai Großjohann's avatar
Kai Großjohann committed
891 892
@cindex method fsh
@cindex fsh method
893

894
There is no inline method using @command{fsh} as the multiplexing