tramp.texi 146 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
@c In the Tramp repository, the version number is auto-frobbed from
Glenn Morris's avatar
Glenn Morris committed
6 7 8
@c configure.ac, so you should edit that file and run
@c "autoconf && ./configure" to change the version number.
@include trampver.texi
Michael Albinus's avatar
Michael Albinus committed
9 10 11 12 13
@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
14 15

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

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

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

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

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

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

46

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

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

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

57 58 59 60
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
61 62

You can find the latest version of this document on the web at
63
@uref{https://www.gnu.org/software/tramp/}.
Glenn Morris's avatar
Glenn Morris committed
64 65 66

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

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

There is a mailing list for @value{tramp}, available at
76 77 78
@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
79

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

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

For the end user:

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

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

* GNU Free Documentation License:: The license for this documentation.
106 107 108
* 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
109 110 111 112 113

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

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

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

Configuring @value{tramp} for use

126
* Connection types::            Types of connections to remote hosts.
Glenn Morris's avatar
Glenn Morris committed
127
* Inline methods::              Inline methods.
128
* External methods::            External methods.
129
* GVFS based methods::          GVFS based external methods.
Glenn Morris's avatar
Glenn Morris committed
130 131 132 133
* 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.
134
* Firewalls::                   Passing firewalls.
Glenn Morris's avatar
Glenn Morris committed
135 136
* Customizing Methods::         Using Non-Standard Methods.
* Customizing Completion::      Selecting config files for user/host name completion.
137
* Password handling::           Reusing passwords for several connections.
Glenn Morris's avatar
Glenn Morris committed
138
* Connection caching::          Reusing connection related information.
139 140
* Predefined connection information::
                                Setting own connection related information.
Michael Albinus's avatar
Michael Albinus committed
141
* Remote programs::             How @value{tramp} finds and uses programs on the remote host.
Glenn Morris's avatar
Glenn Morris committed
142
* Remote shell setup::          Remote shell setup hints.
143
* Android shell setup::         Android shell setup hints.
Glenn Morris's avatar
Glenn Morris committed
144
* Auto-save and Backup::        Auto-save and Backup.
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
* Archive file names::          Access to files in file archives.
Glenn Morris's avatar
Glenn Morris committed
158 159 160 161

How file names, directories and localnames are mangled and managed

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

@end detailmenu
@end menu

167

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

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

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

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

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


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

217 218 219 220 221
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
222

223 224 225
@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
226 227 228

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

@item
235 236 237 238
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
239 240

@item
241 242 243 244
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.
Glenn Morris's avatar
Glenn Morris committed
245 246

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

250 251 252 253
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
254

255 256 257
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
258 259

@item
260 261 262 263
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
264

265 266 267 268
@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
269 270

@item
271 272 273 274 275 276
@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
277 278

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

282 283 284 285
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
286

287
For external transfers, @value{tramp} sends a command as follows:
Glenn Morris's avatar
Glenn Morris committed
288 289 290
@example
rcp user@@host:/path/to/remote/file /tmp/tramp.4711
@end example
291 292
@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
293 294

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

@item
299 300 301
@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
302 303 304 305 306 307 308
@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
309
@node Obtaining @value{tramp}
310
@chapter Obtaining @value{tramp}
311
@cindex obtaining @value{tramp}
Glenn Morris's avatar
Glenn Morris committed
312

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

315
@value{tramp} is also freely packaged for download on the Internet at
316
@uref{https://ftp.gnu.org/gnu/tramp/}.
Glenn Morris's avatar
Glenn Morris committed
317

318 319 320 321 322 323
@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.
Glenn Morris's avatar
Glenn Morris committed
324 325

@noindent
326
@uref{https://savannah.gnu.org/projects/tramp/}
Glenn Morris's avatar
Glenn Morris committed
327 328

@noindent
329
Another way is to follow the terminal session below:
Glenn Morris's avatar
Glenn Morris committed
330 331

@example
332
@group
333 334
$ cd ~/emacs
$ git clone git://git.savannah.gnu.org/tramp.git
335
@end group
336
@end example
Michael Albinus's avatar
Michael Albinus committed
337 338

@noindent
339
From behind a firewall:
Michael Albinus's avatar
Michael Albinus committed
340 341

@example
342
@group
343 344
$ git config --global http.proxy http://user:pwd@@proxy.server.com:8080
$ git clone https://git.savannah.gnu.org/r/tramp.git
345
@end group
Michael Albinus's avatar
Michael Albinus committed
346
@end example
347 348

@noindent
349
@value{tramp} developers:
350 351

@example
352
$ git clone login@@git.sv.gnu.org:/srv/git/tramp.git
Glenn Morris's avatar
Glenn Morris committed
353 354 355
@end example

@noindent
356
After one of the above commands, @file{~/emacs/tramp} will
357 358 359 360
containing the latest version of @value{tramp}.

@noindent
To fetch updates from the repository, use git pull:
Glenn Morris's avatar
Glenn Morris committed
361 362

@example
363
@group
364 365
$ cd ~/emacs/tramp
$ git pull
366
@end group
Glenn Morris's avatar
Glenn Morris committed
367 368 369
@end example

@noindent
370 371
Run @command{autoconf} as follows to generate an up-to-date
@file{configure} script:
Glenn Morris's avatar
Glenn Morris committed
372 373

@example
374
@group
375 376
$ cd ~/emacs/tramp
$ autoconf
377
@end group
Glenn Morris's avatar
Glenn Morris committed
378 379 380 381 382 383 384 385 386
@end example


@c Installation chapter is necessary only in case of standalone
@c installation.  Text taken from trampinst.texi.
@ifset installchapter
@include trampinst.texi
@end ifset

387

388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433
@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}
434 435 436 437
@cindex method @option{ssh}
@cindex @option{ssh} method
@cindex method @option{plink}
@cindex @option{plink} method
438 439

If your local host runs an SSH client, and the remote host runs an SSH
440
server, the simplest remote file name is
441 442 443 444 445 446 447 448 449 450 451 452
@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}
453 454 455 456 457 458
@cindex method @option{su}
@cindex @option{su} method
@cindex method @option{sudo}
@cindex @option{sudo} method
@cindex method @option{sg}
@cindex @option{sg} method
459 460 461 462 463 464 465 466 467 468 469 470

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.


Michael Albinus's avatar
Michael Albinus committed
471 472 473 474 475 476 477 478 479 480 481 482 483
@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.


484 485
@anchor{Quick Start Guide: @option{smb} method}
@section Using @command{smbclient}
486 487 488 489
@cindex method @option{smb}
@cindex @option{smb} method
@cindex ms windows (with @option{smb} method)
@cindex @command{smbclient}
490 491 492 493 494 495 496 497 498 499 500 501

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}
@section Using GVFS-based methods
@cindex methods, gvfs
@cindex gvfs based methods
502 503 504 505 506 507 508 509
@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
510

511 512 513 514
On systems, which have installed the virtual file system for the
@acronym{GNOME} Desktop (GVFS), its offered methods could be used by
@value{tramp}.  Examples are
@file{@trampfn{sftp,user@@host,/path/to/file}},
515 516 517 518 519
@file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP
file system), @file{@trampfn{dav,user@@host,/path/to/file}} and
@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares).


520 521 522
@anchor{Quick Start Guide: GNOME Online Accounts based methods}
@section Using @acronym{GNOME} Online Accounts based methods
@cindex @acronym{GNOME} Online Accounts
523 524
@cindex method @option{gdrive}
@cindex @option{gdrive} method
525
@cindex google drive
526 527 528
@cindex method @option{nextcloud}
@cindex @option{nextcloud} method
@cindex owncloud
529

530 531 532 533 534 535
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
@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}
(@samp{john.doe@@gmail.com} stands here for your Google Drive
536
account), or @file{@trampfn{nextcloud,user@@host#8081,/path/to/file}}
537
(@samp{8081} stands for the port number) for OwnCloud/NextCloud files.
538 539 540 541


@anchor{Quick Start Guide: Android}
@section Using Android
542 543
@cindex method @option{adb}
@cindex @option{adb} method
544 545 546 547 548 549 550
@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
551 552 553 554 555 556 557 558 559 560 561 562
@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
563
@node Configuration
564
@chapter Configuring @value{tramp}
Glenn Morris's avatar
Glenn Morris committed
565 566
@cindex configuration
@cindex default configuration
567 568 569

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

573 574
For problems related to the behavior of the remote shell, @xref{Remote
shell setup}.
575 576

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

579 580 581
@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
582 583

@lisp
584
(customize-set-variable 'tramp-verbose 6 "Enable remote command traces")
Michael Albinus's avatar
Michael Albinus committed
585 586
@end lisp

Glenn Morris's avatar
Glenn Morris committed
587 588

@menu
589
* Connection types::            Types of connections to remote hosts.
Glenn Morris's avatar
Glenn Morris committed
590
* Inline methods::              Inline methods.
591
* External methods::            External methods.
592
* GVFS based methods::          GVFS based external methods.
Glenn Morris's avatar
Glenn Morris committed
593 594 595 596 597 598 599
* 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.
600
* Firewalls::                   Passing firewalls.
Glenn Morris's avatar
Glenn Morris committed
601 602
* Customizing Methods::         Using Non-Standard Methods.
* Customizing Completion::      Selecting config files for user/host name completion.
603
* Password handling::           Reusing passwords for several connections.
Glenn Morris's avatar
Glenn Morris committed
604
* Connection caching::          Reusing connection related information.
605 606
* Predefined connection information::
                                Setting own connection related information.
Michael Albinus's avatar
Michael Albinus committed
607
* Remote programs::             How @value{tramp} finds and uses programs on the remote host.
Glenn Morris's avatar
Glenn Morris committed
608
* Remote shell setup::          Remote shell setup hints.
609
* Android shell setup::         Android shell setup hints.
Glenn Morris's avatar
Glenn Morris committed
610
* Auto-save and Backup::        Auto-save and Backup.
Andreas Schwab's avatar
Andreas Schwab committed
611
* Windows setup hints::         Issues with Cygwin ssh.
Glenn Morris's avatar
Glenn Morris committed
612 613 614 615
@end menu


@node Connection types
616
@section Types of connections to remote hosts
Glenn Morris's avatar
Glenn Morris committed
617 618
@cindex connection types, overview

619 620 621 622 623 624
@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
625

626 627 628
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
629

630
The one exception to this rule are the @option{scp}-based access
Glenn Morris's avatar
Glenn Morris committed
631 632 633 634
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.

635 636 637
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
638 639 640 641
@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
642 643 644 645 646 647 648


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

649 650 651 652
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}
653
may use built-in equivalents of such programs in Emacs.
Glenn Morris's avatar
Glenn Morris committed
654

655 656 657
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
658

659 660
@cindex @command{uuencode}
@cindex @command{mimencode}
Glenn Morris's avatar
Glenn Morris committed
661 662
@cindex base-64 encoding

663 664 665 666 667
@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}.
Glenn Morris's avatar
Glenn Morris committed
668

669 670 671
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.
672

673
@vindex tramp-inline-compress-start-size
674
To increase transfer speeds for large text files, use compression
675
before encoding.  The user option
676
@code{tramp-inline-compress-start-size} specifies the file size for
677
such optimization.
Glenn Morris's avatar
Glenn Morris committed
678 679 680

@table @asis
@item @option{rsh}
681 682
@cindex method @option{rsh}
@cindex @option{rsh} method
Glenn Morris's avatar
Glenn Morris committed
683

684 685
@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
686 687

@item @option{ssh}
688 689
@cindex method @option{ssh}
@cindex @option{ssh} method
Glenn Morris's avatar
Glenn Morris committed
690

691 692
@command{ssh} is a more secure option than others to connect to a
remote host.
Glenn Morris's avatar
Glenn Morris committed
693

694 695 696
@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
697
@samp{-p 42} to the @command{ssh} command.
Glenn Morris's avatar
Glenn Morris committed
698 699

@item @option{telnet}
700 701
@cindex method @option{telnet}
@cindex @option{telnet} method
Glenn Morris's avatar
Glenn Morris committed
702

703
Connecting to a remote host with @command{telnet} is as insecure
Glenn Morris's avatar
Glenn Morris committed
704 705 706
as the @option{rsh} method.

@item @option{su}
707 708
@cindex method @option{su}
@cindex @option{su} method
Glenn Morris's avatar
Glenn Morris committed
709

710 711 712 713
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
714 715

@item @option{sudo}
716 717
@cindex method @option{sudo}
@cindex @option{sudo} method
Glenn Morris's avatar
Glenn Morris committed
718

719 720
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
721

722 723 724
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}.
725

726
@item @option{doas}
727 728
@cindex method @option{doas}
@cindex @option{doas} method
729

730
This method is used on OpenBSD like the @command{sudo} command.  Like
731
the @option{sudo} method, a @option{doas} connection is disabled after
732
a predefined timeout.
733

Michael Albinus's avatar
Michael Albinus committed
734
@item @option{sg}
735 736
@cindex method @option{sg}
@cindex @option{sg} method
Michael Albinus's avatar
Michael Albinus committed
737 738 739 740 741 742 743

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
744
@item @option{sshx}
745 746
@cindex method @option{sshx}
@cindex @option{sshx} method
Glenn Morris's avatar
Glenn Morris committed
747

748 749 750
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.
Glenn Morris's avatar
Glenn Morris committed
751

752 753 754 755 756 757
@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
758

759 760 761
@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
762

763
@option{sshx} supports the @samp{-p} argument.
Glenn Morris's avatar
Glenn Morris committed
764 765

@item @option{krlogin}
766 767 768
@cindex method @option{krlogin}
@cindex @option{krlogin} method
@cindex kerberos (with @option{krlogin} method)
Glenn Morris's avatar
Glenn Morris committed
769

770 771
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
772

773
@item @option{ksu}
774 775 776
@cindex method @option{ksu}
@cindex @option{ksu} method
@cindex kerberos (with @option{ksu} method)
777 778 779

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

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

784
@option{plink} method is for MS Windows users with the PuTTY
785
implementation of SSH@.  It uses @samp{plink -ssh} to log in to the
Glenn Morris's avatar
Glenn Morris committed
786 787
remote host.

788 789
Check the @samp{Share SSH connections if possible} control for that
session.
Michael Albinus's avatar
Michael Albinus committed
790

791
@option{plink} method supports the @samp{-P} argument.
Glenn Morris's avatar
Glenn Morris committed
792 793

@item @option{plinkx}
794 795
@cindex method @option{plinkx}
@cindex @option{plinkx} method
Glenn Morris's avatar
Glenn Morris committed
796

797 798 799
Another method using PuTTY on MS 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.
Michael Albinus's avatar
Michael Albinus committed
800

801 802
Check the @samp{Share SSH connections if possible} control for that
session.
Glenn Morris's avatar
Glenn Morris committed
803 804 805 806

@end table


807 808 809 810
@node External methods
@section External methods
@cindex methods, external
@cindex external methods
Glenn Morris's avatar
Glenn Morris committed
811

812 813 814
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
815

816 817
External methods save on the overhead of encoding and decoding of
inline methods.
Glenn Morris's avatar
Glenn Morris committed
818

819
Since external methods have the overhead of opening a new channel,
820
files smaller than @code{tramp-copy-size-limit} still use inline
821
methods.
Glenn Morris's avatar
Glenn Morris committed
822 823

@table @asis
Michael Albinus's avatar
Michael Albinus committed
824
@item @option{rcp}
825 826 827
@cindex method @option{rcp}
@cindex @option{rcp} method
@cindex @command{rsh} (with @option{rcp} method)
Glenn Morris's avatar
Glenn Morris committed
828

829 830 831
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
832 833

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

Michael Albinus's avatar
Michael Albinus committed
836
@item @option{scp}
837 838 839
@cindex method @option{scp}
@cindex @option{scp} method
@cindex @command{ssh} (with @option{scp} method)
Glenn Morris's avatar
Glenn Morris committed
840

841 842 843 844 845
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.
Glenn Morris's avatar
Glenn Morris committed
846

847 848 849 850
@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}.
Glenn Morris's avatar
Glenn Morris committed
851

Michael Albinus's avatar
Michael Albinus committed
852
@item @option{rsync}
853 854 855
@cindex method @option{rsync}
@cindex @option{rsync} method
@cindex @command{ssh} (with @option{rsync} method)
Glenn Morris's avatar
Glenn Morris committed
856

857 858
@command{ssh} command to connect in combination with @command{rsync}
command to transfer is similar to the @option{scp} method.
Glenn Morris's avatar
Glenn Morris committed
859

860 861 862
@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.
Glenn Morris's avatar
Glenn Morris committed
863

864
This method supports the @samp{-p} argument.
Glenn Morris's avatar
Glenn Morris committed
865

Michael Albinus's avatar
Michael Albinus committed
866
@item @option{scpx}
867 868 869
@cindex method @option{scpx}
@cindex @option{scpx} method
@cindex @command{ssh} (with @option{scpx} method)
Glenn Morris's avatar
Glenn Morris committed
870

871 872 873
@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.
Glenn Morris's avatar
Glenn Morris committed
874

875 876 877
@option{scpx} 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
878

879
This method supports the @samp{-p} argument.
Glenn Morris's avatar
Glenn Morris committed
880

Michael Albinus's avatar
Michael Albinus committed
881 882
@item @option{pscp}
@item @option{psftp}
883 884 885 886 887 888 889 890
@cindex method @option{pscp}
@cindex @option{pscp} method
@cindex @command{plink} (with @option{pscp} method)
@cindex @command{putty} (with @option{pscp} method)
@cindex method @option{psftp}
@cindex @option{psftp} method
@cindex @command{plink} (with @option{psftp} method)
@cindex @command{putty} (with @option{psftp} method)
Glenn Morris's avatar
Glenn Morris committed
891

Michael Albinus's avatar
Michael Albinus committed
892 893 894
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.
895
These programs are part of PuTTY, an SSH implementation for MS Windows.
Glenn Morris's avatar
Glenn Morris committed
896

897 898
Check the @samp{Share SSH connections if possible} control for that
session.
Michael Albinus's avatar
Michael Albinus committed
899 900

These methods support the @samp{-P} argument.
Glenn Morris's avatar
Glenn Morris committed
901

Michael Albinus's avatar
Michael Albinus committed
902
@item @option{fcp}
903 904 905
@cindex method @option{fcp}
@cindex @option{fcp} method
@cindex @command{fsh} (with @option{fcp} method)
Glenn Morris's avatar
Glenn Morris committed
906

907 908 909 910 911 912
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.
Glenn Morris's avatar
Glenn Morris committed
913

914 915
The command used for this connection is: @samp{fsh @var{host} -l
@var{user} /bin/sh -i}
Glenn Morris's avatar
Glenn Morris committed
916

917 918
@cindex method @option{fsh}
@cindex @option{fsh} method
Glenn Morris's avatar
Glenn Morris committed
919

920 921 922
@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.
Glenn Morris's avatar
Glenn Morris committed
923

Michael Albinus's avatar
Michael Albinus committed
924
@item @option{nc}
925 926 927
@cindex method @option{nc}
@cindex @option{nc} method
@cindex @command{telnet} (with @option{nc} method)
Michael Albinus's avatar
Michael Albinus committed
928

929 930 931 932 933
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.
Michael Albinus's avatar
Michael Albinus committed
934

Michael Albinus's avatar
Michael Albinus committed
935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958
@item @option{sudoedit}
@cindex method @option{sudoedit}
@cindex @option{sudoedit} method

The @option{sudoedit} method allows to edit a file as a different user
on the local host.  You could regard this as @value{tramp}'s
implementation of the @command{sudoedit}.  Contrary to the
@option{sudo} method, all magic file name functions are implemented by
single @command{sudo @dots{}}  commands.  The purpose is to make
editing such a file as secure as possible; there must be no session
running in the Emacs background which could be attacked from inside
Emacs.

Consequently, external processes are not implemented.

The host name of such remote file names must represent the local host.
Since the default value is already proper, it is recommended not to
use any host name in the remote file name, like
@file{@trampfn{sudoedit,,/path/to/file}} or
@file{@trampfn{sudoedit,user@@,/path/to/file}}.

Like the @option{sudo} method, a @option{sudoedit} password expires
after a predefined timeout.

Glenn Morris's avatar
Glenn Morris committed
959
@item @option{ftp}
960 961
@cindex method @option{ftp}
@cindex @option{ftp} method
Glenn Morris's avatar
Glenn Morris committed
962

963
When @value{tramp} uses @option{ftp}, it forwards requests to whatever
964 965
ftp program is specified by Ange FTP.  This external program must be
capable of servicing requests from @value{tramp}.
Glenn Morris's avatar
Glenn Morris committed
966

Michael Albinus's avatar
Michael Albinus committed
967
@item @option{smb}
968 969 970 971
@cindex method @option{smb}
@cindex @option{smb} method
@cindex ms windows (with @option{smb} method)
@cindex @command{smbclient}
Glenn Morris's avatar
Glenn Morris committed
972

Paul Eggert's avatar
Paul Eggert committed
973 974 975
This non-native @value{tramp} method connects via the Server Message
Block (SMB) networking protocol to hosts running file servers that are
typically based on @url{https://www.samba.org/,,Samba} or MS Windows.
976 977 978 979 980 981 982

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.

983 984 985
Since some SMB share names end in the @code{$} character,
@value{tramp} must use @code{$$} when specifying those shares to avoid
environment variable substitutions.
986 987

When @value{tramp} is not specific about the share name or uses the
988
generic remote directory @file{/}, @command{smbclient} returns all
989 990 991 992 993 994 995 996 997
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
998 999 1000
@code{user%domain} format (where @code{user} is the user name,
@code{%} is the percent symbol, and @code{domain} is the MS Windows
domain name).  An example:
1001 1002

@example
1003
@trampfn{smb,daniel%BIZARRE@@melancholia,/daniel$$/.emacs}
1004 1005 1006
@end example

where user @code{daniel} connects as a domain user to the SMB host
1007
@code{melancholia} in the MS Windows domain @code{BIZARRE} to edit
1008 1009 1010 1011 1012 1013 1014
@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
1015
@trampfn{smb,daniel%MELANCHOLIA@@melancholia,/daniel$$/.emacs}
1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027
@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.

1028 1029 1030
The @option{smb} method is unavailable if Emacs 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}:
1031 1032 1033 1034 1035

@example
//melancholia/daniel$$/.emacs
@end example

1036 1037 1038
UNC file name specification does not allow the specification of a
different user name for authentication like the @command{smbclient}
can.
1039

1040

1041
@item @option{adb}
1042 1043 1044
@cindex method @option{adb}
@cindex @option{adb} method
@cindex android (with @option{adb} method)
1045

1046
@vindex tramp-adb-program
Michael Albinus's avatar
Michael Albinus committed
1047
@vindex PATH@r{, environment variable}
1048 1049 1050
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
1051 1052
Debug Bridge as an installation package.  Alternatively, the program
is installed as part of the Android SDK@.  @value{tramp} finds the
1053
@command{adb} program either via the @env{PATH} environment variable
1054
or the absolute path set in the user option @code{tramp-adb-program}.
1055

1056
@vindex tramp-adb-connect-if-not-connected
1057
@value{tramp} connects to Android devices with @option{adb} only when
1058
the user option @code{tramp-adb-connect-if-not-connected} is not
1059
@code{nil}.  Otherwise, the connection must be established outside
1060
Emacs.
1061 1062 1063

@value{tramp} does not require a host name part of the remote file
name when a single Android device is connected to @command{adb}.
1064 1065
@value{tramp} instead uses @file{@trampfn{adb,,}} as the default name.
@command{adb devices} shows available host names.
1066 1067

@option{adb} method normally does not need user name to authenticate
1068
on the Android device because it runs under the @command{adbd}
1069 1070 1071 1072 1073
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.

1074
For Android devices connected through TCP/IP, a port number can be
1075 1076 1077
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@.
Michael Albinus's avatar
Michael Albinus committed
1078

Michael Albinus's avatar
Michael Albinus committed
1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120

@item @option{rclone}
@cindex method @option{rclone}
@cindex @option{rclone} method

@vindex tramp-rclone-program
The program @command{rclone} allows to access different system
storages in the cloud, see @url{https://rclone.org/} for a list of
supported systems.  If the @command{rclone} program isn't found in
your @env{PATH} environment variable, you can tell Tramp its absolute
path via the user option @code{tramp-rclone-program}.

A system storage must be configured via the @command{rclone config}
command, outside Emacs.  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

@example
@trampfn{rclone,storage,/path/to/file}
@end example

User names are part of the @command{rclone} configuration, and not
needed in the remote file name.  If a user name is contained in the
remote file name, it is ignored.

Internally, Tramp mounts the remote system storage at location
@file{/tmp/tramp.rclone.storage}, with @file{storage} being the name
of the configured system storage.

Optional flags to the different @option{rclone} operations could be
passed as connection property, @xref{Predefined connection
information}.  Supported properties are @samp{mount-args},
@samp{copyto-args} and @samp{moveto-args}.

Access via @option{rclone} is slow.  If you have an alternative method
for accessing the system storage, you shall prefer this.  @ref{GVFS
based methods} for example, methods @option{gdrive} and
@option{nextcloud}.

@strong{Note}: The @option{rclone} method is experimental, don't use
it in production systems!

1121 1122
@end table

Glenn Morris's avatar
Glenn Morris committed
1123

1124 1125 1126 1127 1128
@node GVFS based methods
@section GVFS based external methods
@cindex methods, gvfs
@cindex gvfs based methods
@cindex dbus
1129

1130
GVFS is the virtual file system for the @acronym{GNOME} Desktop,
1131
@uref{https://en.wikipedia.org/wiki/GVFS}.  Remote files on GVFS are
1132 1133
mounted locally through FUSE and @value{tramp} uses this locally
mounted directory internally.
1134

1135 1136 1137
Emacs uses the D-Bus mechanism to communicate with GVFS@.  Emacs must
have the message bus system, D-Bus integration active, @pxref{Top, ,
D-Bus, dbus}.
1138