tramp.texi 171 KB
Newer Older
1
\input texinfo   @c -*- mode: texinfo; coding: utf-8 -*-
2
@setfilename ../../info/tramp.info
Glenn Morris's avatar
Glenn Morris committed
3
@c %**start of header
4
@include docstyle.texi
5 6
@c In the Tramp GIT, the version number is auto-frobbed from tramp.el,
@c and the bug report address is auto-frobbed from configure.ac.
Glenn Morris's avatar
Glenn Morris committed
7
@include trampver.texi
Michael Albinus's avatar
Michael Albinus committed
8 9 10 11 12
@settitle @value{tramp} @value{trampver} User Manual
@c %**end of header

@c This is *so* much nicer :)
@footnotestyle end
Glenn Morris's avatar
Glenn Morris committed
13 14

@copying
Paul Eggert's avatar
Paul Eggert committed
15
Copyright @copyright{} 1999--2020 Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
16 17 18

@quotation
Permission is granted to copy, distribute and/or modify this document
19
under the terms of the GNU Free Documentation License, Version 1.3 or
Glenn Morris's avatar
Glenn Morris committed
20
any later version published by the Free Software Foundation; with no
21
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
22 23
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''.
Glenn Morris's avatar
Glenn Morris committed
24

25
(a) The FSF's Back-Cover Text is: ``You have the freedom to
26
copy and modify this GNU manual.''
Glenn Morris's avatar
Glenn Morris committed
27 28 29
@end quotation
@end copying

30
@c Entries for @command{install-info} to use.  We cannot use @value{tramp}.
31
@dircategory Emacs network features
Glenn Morris's avatar
Glenn Morris committed
32
@direntry
33
* Tramp: (tramp).               Transparent Remote Access, Multiple Protocol
34
                                  Emacs remote file access via ssh and scp.
Glenn Morris's avatar
Glenn Morris committed
35 36 37
@end direntry

@titlepage
Michael Albinus's avatar
Michael Albinus committed
38
@title @value{tramp} @value{trampver} User Manual
Glenn Morris's avatar
Glenn Morris committed
39
@author by Daniel Pittman
40
@author based on documentation by Kai Großjohann
Glenn Morris's avatar
Glenn Morris committed
41 42
@end titlepage

43
@contents
Glenn Morris's avatar
Glenn Morris committed
44

45

46
@node Top, Overview, (dir), (dir)
Michael Albinus's avatar
Michael Albinus committed
47
@top @value{tramp} @value{trampver} User Manual
Glenn Morris's avatar
Glenn Morris committed
48

Michael Albinus's avatar
Michael Albinus committed
49
This file documents @w{@value{tramp} @value{trampver}}, a remote file
50
editing package for Emacs.
Glenn Morris's avatar
Glenn Morris committed
51

52 53
@value{tramp} stands for ``Transparent Remote (file) Access, Multiple
Protocol''.  This package provides remote file editing, similar to
54
Ange FTP@.
Glenn Morris's avatar
Glenn Morris committed
55

56 57 58 59
The difference is that Ange FTP 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}.
Glenn Morris's avatar
Glenn Morris committed
60 61

You can find the latest version of this document on the web at
Michael Albinus's avatar
Michael Albinus committed
62
@uref{@value{trampurl}}.
Glenn Morris's avatar
Glenn Morris committed
63 64 65

@ifhtml
The latest release of @value{tramp} is available for
66
@uref{https://ftp.gnu.org/gnu/tramp/, download}, or you may see
67 68
@ref{Obtaining @value{tramp}} for more details, including the Git
server details.
Glenn Morris's avatar
Glenn Morris committed
69

70
@value{tramp} also has a @uref{https://savannah.gnu.org/projects/tramp/,
Glenn Morris's avatar
Glenn Morris committed
71 72 73 74
Savannah Project Page}.
@end ifhtml

There is a mailing list for @value{tramp}, available at
75 76 77
@email{@value{tramp-bug-report-address}}, and archived at
@uref{https://lists.gnu.org/r/tramp-devel/, the @value{tramp} Mail
Archive}.
Glenn Morris's avatar
Glenn Morris committed
78

79
@page
Glenn Morris's avatar
Glenn Morris committed
80 81 82 83 84 85 86
@insertcopying

@menu
* Overview::                    What @value{tramp} can and cannot do.

For the end user:

87
* Obtaining @value{tramp}::             How to obtain @value{tramp}.
Glenn Morris's avatar
Glenn Morris committed
88
@ifset installchapter
89
* Installation::                Installing @value{tramp} with your Emacs.
Glenn Morris's avatar
Glenn Morris committed
90
@end ifset
91
* Quick Start Guide::           Short introduction how to use @value{tramp}.
Glenn Morris's avatar
Glenn Morris committed
92 93 94 95 96 97 98
* 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:

99 100 101
* Files directories and localnames::
                                How file names, directories and localnames
                                  are mangled and managed.
Glenn Morris's avatar
Glenn Morris committed
102 103 104
* Traces and Profiles::         How to Customize Traces.

* GNU Free Documentation License:: The license for this documentation.
105 106 107
* Function Index::              @value{tramp} functions.
* Variable Index::              User options and variables.
* Concept Index::               An item for each concept.
Glenn Morris's avatar
Glenn Morris committed
108 109 110 111 112

@detailmenu
 --- The Detailed Node Listing ---
@c
@ifset installchapter
113

114
Installing @value{tramp} with your Emacs
Glenn Morris's avatar
Glenn Morris committed
115

116 117
* System Requirements::         Prerequisites for @value{tramp} installation.
* Basic Installation::          Installation steps.
Glenn Morris's avatar
Glenn Morris committed
118
* Installation parameters::     Parameters in order to control installation.
119
* Testing::                     A test suite for @value{tramp}.
Glenn Morris's avatar
Glenn Morris committed
120 121 122 123 124
* Load paths::                  How to plug-in @value{tramp} into your environment.
@end ifset

Configuring @value{tramp} for use

125
* Connection types::            Types of connections to remote hosts.
Glenn Morris's avatar
Glenn Morris committed
126
* Inline methods::              Inline methods.
127
* External methods::            External methods.
128
* GVFS-based methods::          @acronym{GVFS}-based external methods.
Glenn Morris's avatar
Glenn Morris committed
129 130 131 132
* 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.
133
* Firewalls::                   Passing firewalls.
Glenn Morris's avatar
Glenn Morris committed
134 135
* Customizing Methods::         Using Non-Standard Methods.
* Customizing Completion::      Selecting config files for user/host name completion.
136
* Password handling::           Reusing passwords for several connections.
Glenn Morris's avatar
Glenn Morris committed
137
* Connection caching::          Reusing connection related information.
138 139
* Predefined connection information::
                                Setting own connection related information.
Michael Albinus's avatar
Michael Albinus committed
140
* Remote programs::             How @value{tramp} finds and uses programs on the remote host.
Glenn Morris's avatar
Glenn Morris committed
141
* Remote shell setup::          Remote shell setup hints.
142
* Android shell setup::         Android shell setup hints.
Glenn Morris's avatar
Glenn Morris committed
143
* Auto-save and Backup::        Auto-save and Backup.
144
* Keeping files encrypted::     Protect remote files by encryption.
145
* Windows setup hints::         Issues with Cygwin ssh.
Glenn Morris's avatar
Glenn Morris committed
146 147 148

Using @value{tramp}

Michael Albinus's avatar
Michael Albinus committed
149 150 151 152
* File name syntax::            @value{tramp} file name conventions.
@ifset unified
* Change file name syntax::     Alternative file name syntax.
@end ifset
153
* File name completion::        File name completion.
Michael Albinus's avatar
Michael Albinus committed
154
* Ad-hoc multi-hops::           Declaring multiple hops in the file name.
155
* Remote processes::            Integration with other Emacs packages.
156
* Cleanup remote connections::  Cleanup remote connections.
157
* Renaming remote files::       Renaming remote files.
158
* Archive file names::          Access to files in file archives.
Glenn Morris's avatar
Glenn Morris committed
159 160 161 162

How file names, directories and localnames are mangled and managed

* Localname deconstruction::    Breaking a localname into its components.
163
* External packages::           Integration with external Lisp packages.
Glenn Morris's avatar
Glenn Morris committed
164 165 166 167

@end detailmenu
@end menu

168

Glenn Morris's avatar
Glenn Morris committed
169 170 171 172
@node Overview
@chapter An overview of @value{tramp}
@cindex overview

173
@value{tramp} is for transparently accessing remote files from within
174 175 176
Emacs.  @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}.
177 178 179 180

@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
181
@acronym{ASCII} characters, @value{tramp} can use them.
182 183 184 185 186 187
@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.

188
@value{tramp} on MS Windows operating systems is integrated with the
189 190 191 192 193 194 195 196 197 198
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
199
benefit of direct integration of @value{tramp} in Emacs.
200 201 202

@value{tramp} can transfer files using any number of available host
programs for remote files, such as @command{rcp}, @command{scp},
203
@command{rsync} or (under MS Windows) @command{pscp}.  @value{tramp}
204 205 206 207 208 209 210
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.
Glenn Morris's avatar
Glenn Morris committed
211 212


213
@subsubheading @value{tramp} behind the scenes
Glenn Morris's avatar
Glenn Morris committed
214 215 216 217
@cindex behind the scenes
@cindex details of operation
@cindex how it works

218 219 220 221 222
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:
Glenn Morris's avatar
Glenn Morris committed
223

224 225 226
@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:
Glenn Morris's avatar
Glenn Morris committed
227 228 229

@itemize
@item
230 231 232
@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
233
Emacs buffer, which also shows output from the remote host.
Glenn Morris's avatar
Glenn Morris committed
234 235

@item
236 237 238 239
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.
Glenn Morris's avatar
Glenn Morris committed
240 241

@item
242
The remote host may then prompt for a password or passphrase (for
243 244 245
@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.
Glenn Morris's avatar
Glenn Morris committed
246 247

@item
248 249
@value{tramp} now waits for either the shell prompt or a failed login
message.
Glenn Morris's avatar
Glenn Morris committed
250

251 252 253 254
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.
Glenn Morris's avatar
Glenn Morris committed
255

256 257 258
For any @samp{login failed} message from the remote host,
@value{tramp} aborts the login attempt, and repeats the login steps
again.
Glenn Morris's avatar
Glenn Morris committed
259 260

@item
261 262 263 264
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.
Glenn Morris's avatar
Glenn Morris committed
265

266 267 268 269
@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.
Glenn Morris's avatar
Glenn Morris committed
270 271

@item
272 273 274 275 276 277
@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.
Glenn Morris's avatar
Glenn Morris committed
278 279

@item
280 281
After remote file name completion, @value{tramp} transfers the file
contents from the remote host.
Glenn Morris's avatar
Glenn Morris committed
282

283 284 285 286
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.
Glenn Morris's avatar
Glenn Morris committed
287

288
For external transfers, @value{tramp} sends a command as follows:
Glenn Morris's avatar
Glenn Morris committed
289 290 291
@example
rcp user@@host:/path/to/remote/file /tmp/tramp.4711
@end example
292 293
@value{tramp} reads the local temporary file @file{/tmp/tramp.4711}
into a buffer, and then deletes the temporary file.
Glenn Morris's avatar
Glenn Morris committed
294 295

@item
296
Edit, modify, change the buffer contents as normal, and then save the
Eli Zaretskii's avatar
Eli Zaretskii committed
297
buffer with @kbd{C-x C-s}.
Glenn Morris's avatar
Glenn Morris committed
298 299

@item
300 301 302
@value{tramp} transfers the buffer contents to the remote host in
a reverse of the process using the appropriate inline or external
program.
Glenn Morris's avatar
Glenn Morris committed
303 304 305 306 307 308 309
@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
310
@node Obtaining @value{tramp}
311
@chapter Obtaining @value{tramp}
312
@cindex obtaining @value{tramp}
313
@cindex GNU ELPA
314
@vindex tramp-version
Glenn Morris's avatar
Glenn Morris committed
315

Michael Albinus's avatar
Michael Albinus committed
316
@value{tramp} is included as part of Emacs (since @w{Emacs 22.1}).
Glenn Morris's avatar
Glenn Morris committed
317

318
@value{tramp} is also freely packaged for download on the Internet at
319 320 321
@uref{https://ftp.gnu.org/gnu/tramp/}.  The version number of
@value{tramp} can be obtained by the variable @code{tramp-version}.
For released @value{tramp} versions, this is a three-number string
Michael Albinus's avatar
Michael Albinus committed
322
like ``2.4.5''.
323 324 325 326 327

A @value{tramp} release, which is packaged with Emacs, could differ
slightly from the corresponding standalone release.  This is because
it isn't always possible to synchronize release dates between Emacs
and @value{tramp}.  Such version numbers have the Emacs version number
Michael Albinus's avatar
Michael Albinus committed
328 329
as suffix, like ``2.4.5.27.2''.  This means @w{@value{tramp} 2.4.5} as
integrated in @w{Emacs 27.2}.  A complete list of @value{tramp}
Michael Albinus's avatar
Michael Albinus committed
330
versions packaged with Emacs can be retrieved by
331 332 333 334 335

@vindex customize-package-emacs-version-alist
@lisp
(assoc 'Tramp customize-package-emacs-version-alist)
@end lisp
336 337 338 339 340

@value{tramp} is also available as @uref{https://elpa.gnu.org, GNU
ELPA} package.  Besides the standalone releases, further minor version
of @value{tramp} will appear on GNU ELPA, until the next @value{tramp}
release appears.  These minor versions have a four-number string, like
Michael Albinus's avatar
Michael Albinus committed
341
``2.4.5.1''.
342

343
@value{tramp} development versions are available on Git servers.
344 345
Development versions contain new and incomplete features.  The
development version of @value{tramp} is always the version number of
346
the next release, plus the suffix ``-pre'', like ``2.4.4-pre''.
347

348 349 350
One way to obtain @value{tramp} 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.
Glenn Morris's avatar
Glenn Morris committed
351 352

@noindent
353
@uref{https://savannah.gnu.org/projects/tramp/}
Glenn Morris's avatar
Glenn Morris committed
354 355

@noindent
356
Another way is to follow the terminal session below:
Glenn Morris's avatar
Glenn Morris committed
357 358

@example
359
@group
360 361
$ cd ~/emacs
$ git clone git://git.savannah.gnu.org/tramp.git
362
@end group
363
@end example
Michael Albinus's avatar
Michael Albinus committed
364 365

@noindent
366
From behind a firewall:
Michael Albinus's avatar
Michael Albinus committed
367 368

@example
369
@group
370 371
$ git config --global http.proxy http://user:pwd@@proxy.server.com:8080
$ git clone https://git.savannah.gnu.org/r/tramp.git
372
@end group
Michael Albinus's avatar
Michael Albinus committed
373
@end example
374 375

@noindent
376
@value{tramp} developers:
377 378

@example
379
$ git clone login@@git.sv.gnu.org:/srv/git/tramp.git
Glenn Morris's avatar
Glenn Morris committed
380 381 382
@end example

@noindent
383
After one of the above commands, @file{~/emacs/tramp} will
384 385 386
containing the latest version of @value{tramp}.

@noindent
387
To fetch updates from the repository, use @code{git pull}:
Glenn Morris's avatar
Glenn Morris committed
388 389

@example
390
@group
391 392
$ cd ~/emacs/tramp
$ git pull
393
@end group
Glenn Morris's avatar
Glenn Morris committed
394 395 396
@end example

@noindent
397 398
Run @command{autoconf} as follows to generate an up-to-date
@file{configure} script:
Glenn Morris's avatar
Glenn Morris committed
399 400

@example
401
@group
402 403
$ cd ~/emacs/tramp
$ autoconf
404
@end group
Glenn Morris's avatar
Glenn Morris committed
405 406
@end example

Michael Albinus's avatar
Michael Albinus committed
407
@ifset installchapter
Glenn Morris's avatar
Glenn Morris committed
408
@c Installation chapter is necessary only in case of standalone
409
@c installation.
Glenn Morris's avatar
Glenn Morris committed
410 411
@include trampinst.texi
@end ifset
Michael Albinus's avatar
Michael Albinus committed
412 413 414 415
@ifclear installchapter
See the file @file{INSTALL} in that directory for further information
how to install @value{tramp}.
@end ifclear
Glenn Morris's avatar
Glenn Morris committed
416

417

418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463
@node Quick Start Guide
@chapter Short introduction how to use @value{tramp}
@cindex quick start guide

@value{tramp} extends the Emacs file name syntax by a remote
component.  A remote file name looks always like
@file{@trampfn{method,user@@host,/path/to/file}}.

You can use remote files exactly like ordinary files, that means you
could open a file or directory by @kbd{C-x C-f
@trampfn{method,user@@host,/path/to/file} @key{RET}}, edit the file,
and save it.  You can also mix local files and remote files in file
operations with two arguments, like @code{copy-file} or
@code{rename-file}.  And finally, you can run even processes on a
remote host, when the buffer you call the process from has a remote
@code{default-directory}.


@anchor{Quick Start Guide: File name syntax}
@section File name syntax
@cindex file name syntax

Remote file names are prepended by the @code{method}, @code{user} and
@code{host} parts.  All of them, and also the local file name part,
are optional, in case of a missing part a default value is assumed.
The default value for an empty local file name part is the remote
user's home directory.  The shortest remote file name is
@file{@trampfn{-,,}}, therefore.  The @samp{-} notation for the
default host is used for syntactical reasons, @ref{Default Host}.

The @code{method} part describes the connection method used to reach
the remote host, see below.

The @code{user} part is the user name for accessing the remote host.
For the @option{smb} method, this could also require a domain name, in
this case it is written as @code{user%domain}.

The @code{host} part must be a host name which could be resolved on
your local host.  It could be a short host name, a fully qualified
domain name, an IPv4 or IPv6 address, @ref{File name syntax}.  Some
connection methods support also a notation of the port to be used, in
this case it is written as @code{host#port}.


@anchor{Quick Start Guide: @option{ssh} and @option{plink} methods}
@section Using @option{ssh} and @option{plink}
464 465 466 467
@cindex method @option{ssh}
@cindex @option{ssh} method
@cindex method @option{plink}
@cindex @option{plink} method
468 469

If your local host runs an SSH client, and the remote host runs an SSH
470
server, the simplest remote file name is
471 472 473 474 475 476 477 478 479 480 481 482
@file{@trampfn{ssh,user@@host,/path/to/file}}.  The remote file name
@file{@trampfn{ssh,,}} opens a remote connection to yourself on the
local host, and is taken often for testing @value{tramp}.

On MS Windows, PuTTY is often used as SSH client.  Its @command{plink}
method can be used there to open a connection to a remote host running
an @command{ssh} server:
@file{@trampfn{plink,user@@host,/path/to/file}}.


@anchor{Quick Start Guide: @option{su}, @option{sudo} and @option{sg} methods}
@section Using @option{su}, @option{sudo} and @option{sg}
483 484 485 486 487 488
@cindex method @option{su}
@cindex @option{su} method
@cindex method @option{sudo}
@cindex @option{sudo} method
@cindex method @option{sg}
@cindex @option{sg} method
489 490 491 492 493 494 495 496 497 498 499 500

Sometimes, it is necessary to work on your local host under different
permissions.  For this, you could use the @option{su} or @option{sudo}
connection method.  Both methods use @samp{root} as default user name
and the return value of @code{(system-name)} as default host name.
Therefore, it is convenient to open a file as
@file{@trampfn{sudo,,/path/to/file}}.

The method @option{sg} stands for ``switch group''; the changed group
must be used here as user name.  The default host name is the same.


501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521
@anchor{Quick Start Guide: @option{ssh}, @option{plink}, @option{su}, @option{sudo} and @option{sg} methods}
@section Combining @option{ssh} or @option{plink} with @option{su} or @option{sudo}
@cindex method @option{ssh}
@cindex @option{ssh} method
@cindex method @option{plink}
@cindex @option{plink} method
@cindex method @option{su}
@cindex @option{su} method
@cindex method @option{sudo}
@cindex @option{sudo} method

If the @option{su} or @option{sudo} option shall be performed on
another host, it could be comnbined with a leading @option{ssh} or
@option{plink} option.  That means, @value{tramp} connects first to
the other host with non-administrative credentials, and changes to
administrative credentials on that host afterwards.  In a simple case,
the syntax looks like
@file{@value{prefix}ssh@value{postfixhop}user@@host|sudo@value{postfixhop}@value{postfix}/path/to/file}.
@xref{Ad-hoc multi-hops}.


Michael Albinus's avatar
Michael Albinus committed
522 523 524 525 526 527 528 529 530 531 532 533 534
@anchor{Quick Start Guide: @option{sudoedit} method}
@section Using @command{sudoedit}
@cindex method @option{sudoedit}
@cindex @option{sudoedit} method

The @option{sudoedit} method is similar to the @option{sudo} method.
However, it is a different implementation: it does not keep an open
session running in the background.  This is for security reasons; on
the backside this method is less performant than the @option{sudo}
method, it is restricted to the @samp{localhost} only, and it does not
support external processes.


535 536
@anchor{Quick Start Guide: @option{smb} method}
@section Using @command{smbclient}
537 538 539 540
@cindex method @option{smb}
@cindex @option{smb} method
@cindex ms windows (with @option{smb} method)
@cindex @command{smbclient}
541 542 543 544 545 546 547 548 549

In order to access a remote MS Windows host or Samba server, the
@command{smbclient} client is used.  The remote file name syntax is
@file{@trampfn{smb,user%domain@@host,/path/to/file}}.  The first part
of the local file name is the share exported by the remote host,
@samp{path} in this example.


@anchor{Quick Start Guide: GVFS-based methods}
550
@section Using @acronym{GVFS}-based methods
551
@cindex methods, gvfs
552
@cindex gvfs-based methods
553 554 555 556 557 558 559 560
@cindex method @option{sftp}
@cindex @option{sftp} method
@cindex method @option{afp}
@cindex @option{afp} method
@cindex method @option{dav}
@cindex method @option{davs}
@cindex @option{dav} method
@cindex @option{davs} method
Michael Albinus's avatar
Michael Albinus committed
561 562
@cindex method @option{media}
@cindex @option{media} method
563

564 565 566
On systems, which have installed @acronym{GVFS, the GNOME Virtual File
System}, its offered methods could be used by @value{tramp}.  Examples
are @file{@trampfn{sftp,user@@host,/path/to/file}},
567
@file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP
Michael Albinus's avatar
Michael Albinus committed
568 569 570
file system), @file{@trampfn{dav,user@@host,/path/to/file}},
@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares) and
@file{@trampfn{media,device,/path/to/file}} (for media devices).
571 572


573 574 575
@anchor{Quick Start Guide: GNOME Online Accounts based methods}
@section Using @acronym{GNOME} Online Accounts based methods
@cindex @acronym{GNOME} Online Accounts
576 577
@cindex method @option{gdrive}
@cindex @option{gdrive} method
578
@cindex google drive
579 580
@cindex method @option{nextcloud}
@cindex @option{nextcloud} method
581
@cindex nextcloud
582

583 584 585 586
@acronym{GVFS}-based methods include also @acronym{GNOME} Online
Accounts, which support the @option{Files} service.  These are the
Google Drive file system, and the OwnCloud/NextCloud file system.  The
file name syntax is here always
587 588
@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}
(@samp{john.doe@@gmail.com} stands here for your Google Drive
589
account), or @file{@trampfn{nextcloud,user@@host#8081,/path/to/file}}
590
(@samp{8081} stands for the port number) for OwnCloud/NextCloud files.
591 592 593 594


@anchor{Quick Start Guide: Android}
@section Using Android
595 596
@cindex method @option{adb}
@cindex @option{adb} method
597 598 599 600 601 602 603
@cindex android

An Android device, which is connected via USB to your local host, can
be accessed via the @command{adb} command.  No user or host name is
needed.  The file name syntax is @file{@trampfn{adb,,/path/to/file}}.


Michael Albinus's avatar
Michael Albinus committed
604 605 606 607 608 609 610 611 612 613 614 615
@anchor{Quick Start Guide: @option{rclone} method}
@section Using @command{rclone}
@cindex method @option{rclone}
@cindex @option{rclone} method

A convenient way to access system storages is the @command{rclone}
program.  If you have configured a storage in @command{rclone} under a
name @samp{storage} (for example), you could access it via the remote
file name syntax @file{@trampfn{rclone,storage,/path/to/file}}.  User
names are not needed.


Glenn Morris's avatar
Glenn Morris committed
616
@node Configuration
617
@chapter Configuring @value{tramp}
Glenn Morris's avatar
Glenn Morris committed
618 619
@cindex configuration
@cindex default configuration
620 621 622

@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
623
file name @file{@trampfn{scp,user@@host,/path/to/file}}.  For details,
624
@xref{Default Method}, @xref{Default User}, @xref{Default Host}.
625

626 627
For problems related to the behavior of the remote shell, @xref{Remote
shell setup}.
628 629

For changing the connection type and file access method from the
630
defaults to one of several other options, @xref{Connection types}.
631

632 633 634
@strong{Note} that some user options described in these examples are
not auto loaded by Emacs.  All examples require @value{tramp} is
installed and loaded:
Michael Albinus's avatar
Michael Albinus committed
635 636

@lisp
637
(customize-set-variable 'tramp-verbose 6 "Enable remote command traces")
Michael Albinus's avatar
Michael Albinus committed
638 639
@end lisp

640 641 642 643 644 645 646
For functions used to configure @value{tramp}, the following clause
might be used in your init file:

@lisp
(with-eval-after-load 'tramp (tramp-change-syntax 'simplified))
@end lisp

Glenn Morris's avatar
Glenn Morris committed
647 648

@menu
649
* Connection types::            Types of connections to remote hosts.
Glenn Morris's avatar
Glenn Morris committed
650
* Inline methods::              Inline methods.
651
* External methods::            External methods.
652
* GVFS-based methods::          @acronym{GVFS}-based external methods.
Glenn Morris's avatar
Glenn Morris committed
653 654 655 656 657 658 659
* 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.
660
* Firewalls::                   Passing firewalls.
Glenn Morris's avatar
Glenn Morris committed
661 662
* Customizing Methods::         Using Non-Standard Methods.
* Customizing Completion::      Selecting config files for user/host name completion.
663
* Password handling::           Reusing passwords for several connections.
Glenn Morris's avatar
Glenn Morris committed
664
* Connection caching::          Reusing connection related information.
665 666
* Predefined connection information::
                                Setting own connection related information.
Michael Albinus's avatar
Michael Albinus committed
667
* Remote programs::             How @value{tramp} finds and uses programs on the remote host.
Glenn Morris's avatar
Glenn Morris committed
668
* Remote shell setup::          Remote shell setup hints.
669
* Android shell setup::         Android shell setup hints.
Glenn Morris's avatar
Glenn Morris committed
670
* Auto-save and Backup::        Auto-save and Backup.
671
* Keeping files encrypted::     Protect remote files by encryption.
Andreas Schwab's avatar
Andreas Schwab committed
672
* Windows setup hints::         Issues with Cygwin ssh.
Glenn Morris's avatar
Glenn Morris committed
673 674 675 676
@end menu


@node Connection types
677
@section Types of connections to remote hosts
Glenn Morris's avatar
Glenn Morris committed
678 679
@cindex connection types, overview

680 681 682 683 684 685
@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.
Glenn Morris's avatar
Glenn Morris committed
686

687 688 689
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.
Glenn Morris's avatar
Glenn Morris committed
690

691
The one exception to this rule are the @option{scp}-based access
Glenn Morris's avatar
Glenn Morris committed
692 693 694 695
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.

696 697 698
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
699 700 701 702
@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.
Glenn Morris's avatar
Glenn Morris committed
703 704 705 706 707 708 709


@node Inline methods
@section Inline methods
@cindex inline methods
@cindex methods, inline

710 711 712 713
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}
714
may use built-in equivalents of such programs in Emacs.
Glenn Morris's avatar
Glenn Morris committed
715

716 717 718
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.
Glenn Morris's avatar
Glenn Morris committed
719 720

@cindex base-64 encoding
721 722 723
@cindex base-64 encoding
@cindex uu encoding
@vindex tramp-remote-coding-commands
724
@value{tramp} checks the remote host for the availability and
725 726 727 728
usability of one of the commands defined in
@code{tramp-remote-coding-commands}.  @value{tramp} uses the first
reliable command it finds.  @value{tramp}'s search path can be
customized, see @ref{Remote programs}.
Glenn Morris's avatar
Glenn Morris committed
729

730 731 732
In case none of the commands are unavailable, @value{tramp} first
transfers a small Perl program to the remote host, and then tries that
program for encoding and decoding.
733

734
@vindex tramp-inline-compress-start-size
735
@vindex tramp-inline-compress-commands
736
To increase transfer speeds for large text files, use compression
737
before encoding.  The user option
738
@code{tramp-inline-compress-start-size} specifies the file size for
739 740 741
such optimization.  This feature depends on the availability and
usability of one of the commands defined in
@code{tramp-inline-compress-commands}.
Glenn Morris's avatar
Glenn Morris committed
742 743 744

@table @asis
@item @option{rsh}
745 746
@cindex method @option{rsh}
@cindex @option{rsh} method
Glenn Morris's avatar
Glenn Morris committed
747

748 749
@command{rsh} is an option for connecting to hosts within local
networks since @command{rsh} is not as secure as other methods.
Glenn Morris's avatar
Glenn Morris committed
750 751

@item @option{ssh}
752 753
@cindex method @option{ssh}
@cindex @option{ssh} method
Glenn Morris's avatar
Glenn Morris committed
754

755 756
@command{ssh} is a more secure option than others to connect to a
remote host.
Glenn Morris's avatar
Glenn Morris committed
757

758 759 760
@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
761
@samp{-p 42} to the @command{ssh} command.
Glenn Morris's avatar
Glenn Morris committed
762 763

@item @option{telnet}
764 765
@cindex method @option{telnet}
@cindex @option{telnet} method
Glenn Morris's avatar
Glenn Morris committed
766

767
Connecting to a remote host with @command{telnet} is as insecure
Glenn Morris's avatar
Glenn Morris committed
768 769 770
as the @option{rsh} method.

@item @option{su}
771 772
@cindex method @option{su}
@cindex @option{su} method
Glenn Morris's avatar
Glenn Morris committed
773

774 775 776 777
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.
Glenn Morris's avatar
Glenn Morris committed
778 779

@item @option{sudo}
780 781
@cindex method @option{sudo}
@cindex @option{sudo} method
Glenn Morris's avatar
Glenn Morris committed
782

783 784
Similar to @option{su} method, @option{sudo} uses @command{sudo}.
@command{sudo} must have sufficient rights to start a shell.
Glenn Morris's avatar
Glenn Morris committed
785

786 787 788
For security reasons, a @option{sudo} connection is disabled after a
predefined timeout (5 minutes per default).  This can be changed, see
@ref{Predefined connection information}.
789

790
@item @option{doas}
791 792
@cindex method @option{doas}
@cindex @option{doas} method
793

794
This method is used on OpenBSD like the @command{sudo} command.  Like
795
the @option{sudo} method, a @option{doas} connection is disabled after
796
a predefined timeout.
797

Michael Albinus's avatar
Michael Albinus committed
798
@item @option{sg}
799 800
@cindex method @option{sg}
@cindex @option{sg} method
Michael Albinus's avatar
Michael Albinus committed
801 802 803 804 805 806 807

The @command{sg} program allows editing as different group.  The host
can be either @samp{localhost} or the host returned by the function
@command{(system-name)}.  The user name must be specified, but it
denotes a group name.  See @ref{Multi-hops} for an exception to this
behavior.

Glenn Morris's avatar
Glenn Morris committed
808
@item @option{sshx}
809 810
@cindex method @option{sshx}
@cindex @option{sshx} method
Glenn Morris's avatar
Glenn Morris committed
811

812 813
Works like @option{ssh} but without the extra authentication prompts.
@option{sshx} uses @samp{ssh -t -t @var{host} -l @var{user} /bin/sh}
814 815
to open a connection with a ``standard'' login shell.  It supports
changing the remote login shell @command{/bin/sh}.
Glenn Morris's avatar
Glenn Morris committed
816

817 818 819 820 821 822
@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.
Glenn Morris's avatar
Glenn Morris committed
823

824 825 826
@option{sshx} is useful for MS Windows users when @command{ssh}
triggers an error about allocating a pseudo tty.  This happens due to
missing shell prompts that confuses @value{tramp}.
Glenn Morris's avatar
Glenn Morris committed
827

828
@option{sshx} supports the @samp{-p} argument.
Glenn Morris's avatar
Glenn Morris committed
829 830

@item @option{krlogin}
831 832 833
@cindex method @option{krlogin}
@cindex @option{krlogin} method
@cindex kerberos (with @option{krlogin} method)
Glenn Morris's avatar
Glenn Morris committed
834

835 836
This method is also similar to @option{ssh}.  It uses the
@command{krlogin -x} command only for remote host login.
Glenn Morris's avatar
Glenn Morris committed
837

838
@item @option{ksu}
839 840 841
@cindex method @option{ksu}
@cindex @option{ksu} method
@cindex kerberos (with @option{ksu} method)
842 843 844

This is another method from the Kerberos suite.  It behaves like @option{su}.

Glenn Morris's avatar
Glenn Morris committed
845
@item @option{plink}
846 847
@cindex method @option{plink}
@cindex @option{plink} method
Glenn Morris's avatar
Glenn Morris committed
848

849
@option{plink} method is for MS Windows users with the PuTTY
850
implementation of SSH@.  It uses @samp{plink -ssh} to log in to the
851
remote host.  It supports changing the remote login shell @command{/bin/sh}.
Glenn Morris's avatar
Glenn Morris committed
852

853 854
Check the @samp{Share SSH connections if possible} control for that
session.
Michael Albinus's avatar
Michael Albinus committed
855

856
@option{plink} method supports the @samp{-P} argument.
Glenn Morris's avatar
Glenn Morris committed
857 858

@item @option{plinkx}
859 860
@cindex method @option{plinkx}
@cindex @option{plinkx} method
Glenn Morris's avatar
Glenn Morris committed
861

862 863
Another method using PuTTY on MS Windows with session names instead of
host names.  @option{plinkx} calls @samp{plink -load @var{session}
864
-t}.  User names and port numbers must be defined in the session.  It
865
supports changing the remote login shell @command{/bin/sh}.
Michael Albinus's avatar
Michael Albinus committed
866

867 868
Check the @samp{Share SSH connections if possible} control for that
session.
Glenn Morris's avatar
Glenn Morris committed
869 870 871 872

@end table


873 874 875 876
@node External methods
@section External methods
@cindex methods, external
@cindex external methods
Glenn Morris's avatar
Glenn Morris committed
877

878 879 880
External methods operate over multiple channels, using the remote
shell connection for some actions while delegating file transfers to
an external transfer program.
Glenn Morris's avatar
Glenn Morris committed
881

882 883
External methods save on the overhead of encoding and decoding of
inline methods.
Glenn Morris's avatar
Glenn Morris committed
884

885
Since external methods have the overhead of opening a new channel,
886
files smaller than @code{tramp-copy-size-limit} still use inline
887
methods.
Glenn Morris's avatar
Glenn Morris committed
888 889

@table @asis
Michael Albinus's avatar
Michael Albinus committed
890
@item @option{rcp}
891 892 893
@cindex method @option{rcp}
@cindex @option{rcp} method
@cindex @command{rsh} (with @option{rcp} method)
Glenn Morris's avatar
Glenn Morris committed
894

895 896 897
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.
Glenn Morris's avatar
Glenn Morris committed
898 899

The alternative method @option{remcp} uses the @command{remsh} and
900
@command{rcp} commands.
Glenn Morris's avatar
Glenn Morris committed
901

Michael Albinus's avatar