tramp.el 188 KB
Newer Older
Michael Albinus's avatar
Michael Albinus committed
1
;;; tramp.el --- Transparent Remote Access, Multiple Protocol  -*- lexical-binding:t -*-
Kai Großjohann's avatar
Kai Großjohann committed
2

Paul Eggert's avatar
Paul Eggert committed
3
;; Copyright (C) 1998-2019 Free Software Foundation, Inc.
Kai Großjohann's avatar
Kai Großjohann committed
4

Stefan Monnier's avatar
Stefan Monnier committed
5
;; Author: Kai Großjohann <kai.grossjohann@gmx.net>
Michael Albinus's avatar
Michael Albinus committed
6
;;         Michael Albinus <michael.albinus@gmx.de>
7
;; Maintainer: Michael Albinus <michael.albinus@gmx.de>
Kai Großjohann's avatar
Kai Großjohann committed
8
;; Keywords: comm, processes
9
;; Package: tramp
10
;; Version: 2.4.3-pre
Michael Albinus's avatar
Michael Albinus committed
11
;; Package-Requires: ((emacs "24.4"))
12
;; URL: https://savannah.gnu.org/projects/tramp
Kai Großjohann's avatar
Kai Großjohann committed
13 14 15

;; This file is part of GNU Emacs.

16
;; GNU Emacs is free software: you can redistribute it and/or modify
Kai Großjohann's avatar
Kai Großjohann committed
17
;; it under the terms of the GNU General Public License as published by
18 19
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
Kai Großjohann's avatar
Kai Großjohann committed
20 21 22 23 24 25 26

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
27
;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
Kai Großjohann's avatar
Kai Großjohann committed
28 29 30 31 32 33 34 35

;;; Commentary:

;; This package provides remote file editing, similar to ange-ftp.
;; The difference is that ange-ftp uses FTP to transfer files between
;; the local and the remote host, whereas tramp.el uses a combination
;; of rsh and rcp or other work-alike programs, such as ssh/scp.
;;
36
;; For more detailed instructions, please see the info file.
Kai Großjohann's avatar
Kai Großjohann committed
37 38 39
;;
;; Notes:
;; -----
40
;;
Kai Großjohann's avatar
Kai Großjohann committed
41 42
;; Also see the todo list at the bottom of this file.
;;
43
;; The current version of Tramp can be retrieved from the following URL:
44
;;            https://ftp.gnu.org/gnu/tramp/
Kai Großjohann's avatar
Kai Großjohann committed
45 46
;;
;; There's a mailing list for this, as well.  Its name is:
Michael Albinus's avatar
Michael Albinus committed
47 48
;;            tramp-devel@gnu.org
;; You can use the Web to subscribe, under the following URL:
Paul Eggert's avatar
Paul Eggert committed
49
;;            https://lists.gnu.org/mailman/listinfo/tramp-devel
Kai Großjohann's avatar
Kai Großjohann committed
50 51
;;
;; For the adventurous, the current development sources are available
52
;; via Git.  You can find instructions about this at the following URL:
53
;;            https://savannah.gnu.org/projects/tramp/
Kai Großjohann's avatar
Kai Großjohann committed
54 55 56 57 58
;;
;; Don't forget to put on your asbestos longjohns, first!

;;; Code:

59
(require 'tramp-compat)
60
(require 'tramp-integration)
61
(require 'trampver)
Kai Großjohann's avatar
Kai Großjohann committed
62

Michael Albinus's avatar
Michael Albinus committed
63
;; Pacify byte-compiler.
Michael Albinus's avatar
Michael Albinus committed
64
(require 'cl-lib)
65
(declare-function netrc-parse "netrc")
Michael Albinus's avatar
Michael Albinus committed
66 67
(defvar auto-save-file-name-transforms)
(defvar outline-regexp)
Michael Albinus's avatar
Michael Albinus committed
68

Kai Großjohann's avatar
Kai Großjohann committed
69 70 71
;;; User Customizable Internal Variables:

(defgroup tramp nil
72
  "Edit remote files with a combination of ssh, scp, etc."
73
  :group 'files
74
  :group 'comm
Michael Albinus's avatar
Michael Albinus committed
75
  :link '(custom-manual "(tramp)Top")
76
  :version "22.1")
Kai Großjohann's avatar
Kai Großjohann committed
77

78
(eval-and-compile ;; So it's also available in tramp-loaddefs.el!
79 80 81
  (defvar tramp--startup-hook nil
    "Forms to be executed at the end of tramp.el.")

82 83 84 85 86 87
  (defmacro tramp--with-startup (&rest body)
    "Schedule BODY to be executed at the end of tramp.el."
    `(add-hook 'tramp--startup-hook (lambda () ,@body))))

(require 'tramp-loaddefs)

88 89 90
;; Maybe we need once a real Tramp mode, with key bindings etc.
;;;###autoload
(defcustom tramp-mode t
91
  "Whether Tramp is enabled.
92 93
If it is set to nil, all remote file names are used literally."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
94
  :type 'boolean)
95

96
(defcustom tramp-verbose 3
97
  "Verbosity level for Tramp messages.
98 99 100 101 102 103 104 105 106 107 108
Any level x includes messages for all levels 1 .. x-1.  The levels are

 0  silent (no tramp messages at all)
 1  errors
 2  warnings
 3  connection to remote hosts (default level)
 4  activities
 5  internal
 6  sent and received strings
 7  file caching
 8  connection properties
109
 9  test commands
110
10  traces (huge)."
Kai Großjohann's avatar
Kai Großjohann committed
111
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
112
  :type 'integer)
Kai Großjohann's avatar
Kai Großjohann committed
113

114 115
(defcustom tramp-backup-directory-alist nil
  "Alist of filename patterns and backup directory names.
116 117 118
Each element looks like (REGEXP . DIRECTORY), with the same meaning like
in `backup-directory-alist'.  If a Tramp file is backed up, and DIRECTORY
is a local file name, the backup directory is prepended with Tramp file
119
name prefix \(method, user, host) of file.
120

121
\(setq tramp-backup-directory-alist backup-directory-alist)
122 123 124

gives the same backup policy for Tramp files on their hosts like the
policy for local files."
125 126
  :group 'tramp
  :type '(repeat (cons (regexp :tag "Regexp matching filename")
Michael Albinus's avatar
Michael Albinus committed
127
		       (directory :tag "Backup directory name"))))
128

Kai Großjohann's avatar
Kai Großjohann committed
129
(defcustom tramp-auto-save-directory nil
130
  "Put auto-save files in this directory, if set.
131 132
The idea is to use a local directory so that auto-saving is faster.
This setting has precedence over `auto-save-file-name-transforms'."
Kai Großjohann's avatar
Kai Großjohann committed
133
  :group 'tramp
134
  :type '(choice (const :tag "Use default" nil)
Michael Albinus's avatar
Michael Albinus committed
135
		 (directory :tag "Auto save directory name")))
Kai Großjohann's avatar
Kai Großjohann committed
136

137
;; Suppress `shell-file-name' for w32 systems.
138
(defcustom tramp-encoding-shell
139 140
  (let (shell-file-name)
    (or (tramp-compat-funcall 'w32-shell-name) "/bin/sh"))
141
  "Use this program for encoding and decoding commands on the local host.
142 143 144 145 146
This shell is used to execute the encoding and decoding command on the
local host, so if you want to use `~' in those commands, you should
choose a shell here which groks tilde expansion.  `/bin/sh' normally
does not understand tilde expansion.

Paul Eggert's avatar
Paul Eggert committed
147
For encoding and decoding, commands like the following are executed:
148 149 150 151

    /bin/sh -c COMMAND < INPUT > OUTPUT

This variable can be used to change the \"/bin/sh\" part.  See the
152
variable `tramp-encoding-command-switch' for the \"-c\" part.
Kai Großjohann's avatar
Kai Großjohann committed
153

154 155 156
If the shell must be forced to be interactive, see
`tramp-encoding-command-interactive'.

Kai Großjohann's avatar
Kai Großjohann committed
157 158 159 160
Note that this variable is not used for remote commands.  There are
mechanisms in tramp.el which automatically determine the right shell to
use for the remote host."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
161
  :type '(file :must-match t))
Kai Großjohann's avatar
Kai Großjohann committed
162

163
;; Suppress `shell-file-name' for w32 systems.
Michael Albinus's avatar
Michael Albinus committed
164
(defcustom tramp-encoding-command-switch
165 166
  (let (shell-file-name)
    (if (tramp-compat-funcall 'w32-shell-dos-semantics) "/c" "-c"))
167
  "Use this switch together with `tramp-encoding-shell' for local commands.
168 169
See the variable `tramp-encoding-shell' for more information."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
170
  :type 'string)
171

172
;; Suppress `shell-file-name' for w32 systems.
173
(defcustom tramp-encoding-command-interactive
174 175
  (let (shell-file-name)
    (unless (tramp-compat-funcall 'w32-shell-dos-semantics) "-i"))
176
  "Use this switch together with `tramp-encoding-shell' for interactive shells.
177
See the variable `tramp-encoding-shell' for more information."
178
  :version "24.1"
179
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
180
  :type '(choice (const nil) string))
181

182
(defvar tramp-methods nil
183
  "Alist of methods for remote files.
Kai Großjohann's avatar
Kai Großjohann committed
184 185 186
This is a list of entries of the form (NAME PARAM1 PARAM2 ...).
Each NAME stands for a remote access method.  Each PARAM is a
pair of the form (KEY VALUE).  The following KEYs are defined:
187

188
  * `tramp-remote-shell'
189 190 191 192 193 194 195
    This specifies the shell to use on the remote host.  This
    MUST be a Bourne-like shell.  It is normally not necessary to
    set this to any value other than \"/bin/sh\": Tramp wants to
    use a shell which groks tilde expansion, but it can search
    for it.  Also note that \"/bin/sh\" exists on all Unixen,
    this might not be true for the value that you decide to use.
    You Have Been Warned.
196

Michael Albinus's avatar
Michael Albinus committed
197 198 199 200 201 202
  * `tramp-remote-shell-login'
    This specifies the arguments to let `tramp-remote-shell' run
    as a login shell.  It defaults to (\"-l\"), but some shells,
    like ksh, require another argument.  See
    `tramp-connection-properties' for a way to overwrite the
    default value.
203

204 205
  * `tramp-remote-shell-args'
    For implementation of `shell-command', this specifies the
206
    arguments to let `tramp-remote-shell' run a single command.
207

208 209
  * `tramp-login-program'
    This specifies the name of the program to use for logging in to the
210 211
    remote host.  This may be the name of rsh or a workalike program,
    or the name of telnet or a workalike, or the name of su or a workalike.
212

213
  * `tramp-login-args'
Kai Großjohann's avatar
Kai Großjohann committed
214
    This specifies the list of arguments to pass to the above
215
    mentioned program.  Please note that this is a list of list of arguments,
Kai Großjohann's avatar
Kai Großjohann committed
216
    that is, normally you don't want to put \"-a -b\" or \"-f foo\"
217 218 219 220 221 222 223 224 225
    here.  Instead, you want a list (\"-a\" \"-b\"), or (\"-f\" \"foo\").
    There are some patterns: \"%h\" in this list is replaced by the host
    name, \"%u\" is replaced by the user name, \"%p\" is replaced by the
    port number, and \"%%\" can be used to obtain a literal percent character.
    If a list containing \"%h\", \"%u\" or \"%p\" is unchanged during
    expansion (i.e. no host or no user specified), this list is not used as
    argument.  By this, arguments like (\"-l\" \"%u\") are optional.
    \"%t\" is replaced by the temporary file name produced with
    `tramp-make-tramp-temp-file'.  \"%k\" indicates the keep-date
226 227
    parameter of a program, if exists.  \"%c\" adds additional
    `tramp-ssh-controlmaster-options' options for the first hop.
228 229 230 231
    The existence of `tramp-login-args', combined with the absence of
    `tramp-copy-args', is an indication that the method is capable of
     multi-hops.

232 233 234
  * `tramp-login-env'
     A list of environment variables and their values, which will
     be set when calling `tramp-login-program'.
235

236 237 238 239 240
  * `tramp-async-args'
    When an asynchronous process is started, we know already that
    the connection works.  Therefore, we can pass additional
    parameters to suppress diagnostic messages, in order not to
    tamper the process output.
241

242 243
  * `tramp-copy-program'
    This specifies the name of the program to use for remotely copying
244
    the file; this might be the absolute filename of scp or the name of
245
    a workalike program.  It is always applied on the local host.
246

247
  * `tramp-copy-args'
Kai Großjohann's avatar
Kai Großjohann committed
248
    This specifies the list of parameters to pass to the above mentioned
249
    program, the hints for `tramp-login-args' also apply here.
250

251 252 253
  * `tramp-copy-env'
     A list of environment variables and their values, which will
     be set when calling `tramp-copy-program'.
254

255 256
  * `tramp-remote-copy-program'
    The listener program to be applied on remote side, if needed.
257

258 259 260 261 262
  * `tramp-remote-copy-args'
    The list of parameters to pass to the listener program, the hints
    for `tramp-login-args' also apply here.  Additionally, \"%r\" could
    be used here and in `tramp-copy-args'.  It denotes a randomly
    chosen port for the remote listener.
263

264 265 266
  * `tramp-copy-keep-date'
    This specifies whether the copying program when the preserves the
    timestamp of the original file.
267

268 269 270
  * `tramp-copy-keep-tmpfile'
    This specifies whether a temporary local file shall be kept
    for optimization reasons (useful for \"rsync\" methods).
271

272 273
  * `tramp-copy-recursive'
    Whether the operation copies directories recursively.
274

275
  * `tramp-default-port'
276
    The default port of a method.
277

278 279 280
  * `tramp-tmpdir'
    A directory on the remote host for temporary files.  If not
    specified, \"/tmp\" is taken as default.
281

282 283 284 285 286
  * `tramp-connection-timeout'
    This is the maximum time to be spent for establishing a connection.
    In general, the global default value shall be used, but for
    some methods, like \"su\" or \"sudo\", a shorter timeout
    might be desirable.
287

288 289 290 291
  * `tramp-session-timeout'
    How long a Tramp connection keeps open before being disconnected.
    This is useful for methods like \"su\" or \"sudo\", which
    shouldn't run an open connection in the background forever.
292

293 294 295 296 297
  * `tramp-case-insensitive'
    Whether the remote file system handles file names case insensitive.
    Only a non-nil value counts, the default value nil means to
    perform further checks on the remote host.  See
    `tramp-connection-properties' for a way to overwrite this.
298

299 300 301 302 303 304 305 306 307 308 309
  * `tramp-mount-args'
  * `tramp-copyto-args'
  * `tramp-moveto-args'
  * `tramp-about-args'
    These parameters, a list of list like `tramp-login-args', are used
    for the \"rclone\" method, and are appended to the respective
    \"rclone\" commands.  In general, they shouldn't be changed inside
    `tramp-methods'; it is recommended to change their values via
    `tramp-connection-properties'.  Unlike `tramp-login-args' there is
     no pattern replacement.

310 311 312
What does all this mean?  Well, you should specify `tramp-login-program'
for all methods; this program is used to log in to the remote site.  Then,
there are two ways to actually transfer the files between the local and the
313
remote side.  One way is using an additional scp-like program.  If you want
314
to do this, set `tramp-copy-program' in the method.
Kai Großjohann's avatar
Kai Großjohann committed
315 316

Another possibility for file transfer is inline transfer, i.e. the
317
file is passed through the same buffer used by `tramp-login-program'.  In
Kai Großjohann's avatar
Kai Großjohann committed
318
this case, the file contents need to be protected since the
319
`tramp-login-program' might use escape codes or the connection might not
Kai Großjohann's avatar
Kai Großjohann committed
320
be eight-bit clean.  Therefore, file contents are encoded for transit.
321 322
See the variables `tramp-local-coding-commands' and
`tramp-remote-coding-commands' for details.
Kai Großjohann's avatar
Kai Großjohann committed
323

324
So, to summarize: if the method is an out-of-band method, then you
325
must specify `tramp-copy-program' and `tramp-copy-args'.  If it is an
326
inline method, then these two parameters should be nil.
Kai Großjohann's avatar
Kai Großjohann committed
327 328 329

Notes:

330 331
When using `su' or `sudo' the phrase \"open connection to a remote
host\" sounds strange, but it is used nevertheless, for consistency.
332 333 334 335
No connection is opened to a remote host, but `su' or `sudo' is
started on the local host.  You should specify a remote host
`localhost' or the name of the local host.  Another host name is
useful only in combination with `tramp-default-proxies-alist'.")
Kai Großjohann's avatar
Kai Großjohann committed
336

337
(defcustom tramp-default-method
Paul Eggert's avatar
Paul Eggert committed
338 339
  ;; An external copy method seems to be preferred, because it performs
  ;; much better for large files, and it hasn't too serious delays
340 341
  ;; for small files.  But it must be ensured that there aren't
  ;; permanent password queries.  Either a password agent like
342 343
  ;; "ssh-agent" or "Pageant" shall run, or the optional
  ;; password-cache.el or auth-sources.el packages shall be active for
344 345 346
  ;; password caching.  If we detect that the user is running OpenSSH
  ;; 4.0 or newer, we could reuse the connection, which calls also for
  ;; an external method.
347
  (cond
Glenn Morris's avatar
Glenn Morris committed
348 349 350
   ;; PuTTY is installed.  We don't take it, if it is installed on a
   ;; non-windows system, or pscp from the pssh (parallel ssh) package
   ;; is found.
351
   ((and (eq system-type 'windows-nt) (executable-find "pscp")) "pscp")
352
   ;; There is an ssh installation.
353
   ((executable-find "scp") "scp")
354 355
   ;; Fallback.
   (t "ftp"))
356
  "Default method to use for transferring files.
357
See `tramp-methods' for possibilities.
358
Also see `tramp-default-method-alist'."
359
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
360
  :type 'string)
361

362
(defcustom tramp-default-method-alist nil
363
  "Default method to use for specific host/user pairs.
364 365 366 367 368 369 370 371 372 373 374
This is an alist of items (HOST USER METHOD).  The first matching item
specifies the method to use for a file name which does not specify a
method.  HOST and USER are regular expressions or nil, which is
interpreted as a regular expression which always matches.  If no entry
matches, the variable `tramp-default-method' takes effect.

If the file name does not specify the user, lookup is done using the
empty string for the user name.

See `tramp-methods' for a list of possibilities for METHOD."
  :group 'tramp
375 376
  :type '(repeat (list (choice :tag "Host regexp" regexp sexp)
		       (choice :tag "User regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
377
		       (choice :tag "Method name" string (const nil)))))
378

379 380 381
(defconst tramp-default-method-marker "-"
  "Marker for default method in remote file names.")

382
(defcustom tramp-default-user nil
383
  "Default user to use for transferring files.
384 385 386 387 388
It is nil by default; otherwise settings in configuration files like
\"~/.ssh/config\" would be overwritten.  Also see `tramp-default-user-alist'.

This variable is regarded as obsolete, and will be removed soon."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
389
  :type '(choice (const nil) string))
390

391
(defcustom tramp-default-user-alist nil
392
  "Default user to use for specific method/host pairs.
393 394
This is an alist of items (METHOD HOST USER).  The first matching item
specifies the user to use for a file name which does not specify a
395
user.  METHOD and HOST are regular expressions or nil, which is
396 397 398 399 400 401
interpreted as a regular expression which always matches.  If no entry
matches, the variable `tramp-default-user' takes effect.

If the file name does not specify the method, lookup is done using the
empty string for the method name."
  :group 'tramp
402 403
  :type '(repeat (list (choice :tag "Method regexp" regexp sexp)
		       (choice :tag "  Host regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
404
		       (choice :tag "    User name" string (const nil)))))
405

406
(defcustom tramp-default-host (system-name)
407
  "Default host to use for transferring files.
408 409
Useful for su and sudo methods mostly."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
410
  :type 'string)
411

412 413 414 415
(defcustom tramp-default-host-alist nil
  "Default host to use for specific method/user pairs.
This is an alist of items (METHOD USER HOST).  The first matching item
specifies the host to use for a file name which does not specify a
416
host.  METHOD and USER are regular expressions or nil, which is
417 418 419 420 421 422
interpreted as a regular expression which always matches.  If no entry
matches, the variable `tramp-default-host' takes effect.

If the file name does not specify the method, lookup is done using the
empty string for the method name."
  :group 'tramp
Glenn Morris's avatar
Glenn Morris committed
423
  :version "24.4"
424 425
  :type '(repeat (list (choice :tag "Method regexp" regexp sexp)
		       (choice :tag "  User regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
426
		       (choice :tag "    Host name" string (const nil)))))
427

428
(defcustom tramp-default-proxies-alist nil
429
  "Route to be followed for specific host/user pairs.
430 431 432
This is an alist of items (HOST USER PROXY).  The first matching
item specifies the proxy to be passed for a file name located on
a remote target matching USER@HOST.  HOST and USER are regular
433 434 435 436 437 438 439 440 441 442 443
expressions, which could also cover a domain (USER%DOMAIN) or
port (HOST#PORT).  PROXY must be a Tramp filename without a
localname part.  Method and user name on PROXY are optional,
which is interpreted with the default values.

PROXY can contain the patterns %h and %u, which are replaced by
the strings matching HOST or USER (without DOMAIN and PORT parts),
respectively.

If an entry is added while parsing ad-hoc hop definitions, PROXY
carries the non-nil text property `tramp-ad-hoc'.
444 445 446 447

HOST, USER or PROXY could also be Lisp forms, which will be
evaluated.  The result must be a string or nil, which is
interpreted as a regular expression which always matches."
448
  :group 'tramp
449 450
  :type '(repeat (list (choice :tag "Host regexp" regexp sexp)
		       (choice :tag "User regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
451
		       (choice :tag " Proxy name" string (const nil)))))
452

Michael Albinus's avatar
Michael Albinus committed
453 454 455
(defcustom tramp-save-ad-hoc-proxies nil
  "Whether to save ad-hoc proxies persistently."
  :group 'tramp
Glenn Morris's avatar
Glenn Morris committed
456
  :version "24.3"
Michael Albinus's avatar
Michael Albinus committed
457
  :type 'boolean)
Michael Albinus's avatar
Michael Albinus committed
458

459 460 461 462 463 464 465 466
(defcustom tramp-restricted-shell-hosts-alist
  (when (memq system-type '(windows-nt))
    (list (concat "\\`" (regexp-quote (system-name)) "\\'")))
  "List of hosts, which run a restricted shell.
This is a list of regular expressions, which denote hosts running
a registered shell like \"rbash\".  Those hosts can be used as
proxies only, see `tramp-default-proxies-alist'.  If the local
host runs a registered shell, it shall be added to this list, too."
467
  :version "24.3"
468
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
469
  :type '(repeat (regexp :tag "Host regexp")))
470

471
(defcustom tramp-local-host-regexp
472
  (concat
473 474
   "\\`"
   (regexp-opt
475
    (list "localhost" "localhost6" (system-name) "127.0.0.1" "::1") t)
476
   "\\'")
477 478 479 480 481
  "Host names which are regarded as local host.
If the local host runs a chrooted environment, set this to nil."
  :version "27.1"
  :group 'tramp
  :type '(choice (const :tag "Chrooted environment" nil)
Michael Albinus's avatar
Michael Albinus committed
482
		 (regexp :tag "Host regexp")))
483

484
(defvar tramp-completion-function-alist nil
485
  "Alist of methods for remote files.
486
This is a list of entries of the form \(NAME PAIR1 PAIR2 ...).
487
Each NAME stands for a remote access method.  Each PAIR is of the form
488
\(FUNCTION FILE).  FUNCTION is responsible to extract user names and host
489 490
names from FILE for completion.  The following predefined FUNCTIONs exists:

491 492 493 494 495 496 497
 * `tramp-parse-rhosts'      for \"~/.rhosts\" like files,
 * `tramp-parse-shosts'      for \"~/.ssh/known_hosts\" like files,
 * `tramp-parse-sconfig'     for \"~/.ssh/config\" like files,
 * `tramp-parse-shostkeys'   for \"~/.ssh2/hostkeys/*\" like files,
 * `tramp-parse-sknownhosts' for \"~/.ssh2/knownhosts/*\" like files,
 * `tramp-parse-hosts'       for \"/etc/hosts\" like files,
 * `tramp-parse-passwd'      for \"/etc/passwd\" like files.
Michael Albinus's avatar
Michael Albinus committed
498
 * `tramp-parse-etc-group'   for \"/etc/group\" like files.
499
 * `tramp-parse-netrc'       for \"~/.netrc\" like files.
Michael Albinus's avatar
Michael Albinus committed
500
 * `tramp-parse-putty'       for PuTTY registered sessions.
501

Michael Albinus's avatar
Michael Albinus committed
502
FUNCTION can also be a user defined function.  For more details see
503 504
the info pages.")

505 506 507
(defconst tramp-echo-mark-marker "_echo"
  "String marker to surround echoed commands.")

508 509 510 511 512 513
(defconst tramp-echo-mark-marker-length (length tramp-echo-mark-marker)
  "String length of `tramp-echo-mark-marker'.")

(defconst tramp-echo-mark
  (concat tramp-echo-mark-marker
	  (make-string tramp-echo-mark-marker-length ?\b))
514 515 516 517 518
  "String mark to be transmitted around shell commands.
Used to separate their echo from the output they produce.  This
will only be used if we cannot disable remote echo via stty.
This string must have no effect on the remote shell except for
producing some echo which can later be detected by
519 520 521
`tramp-echoed-echo-mark-regexp'.  Using `tramp-echo-mark-marker',
followed by an equal number of backspaces to erase them will
usually suffice.")
522

523 524 525
(defconst tramp-echoed-echo-mark-regexp
  (format "%s\\(\b\\( \b\\)?\\)\\{%d\\}"
	  tramp-echo-mark-marker tramp-echo-mark-marker-length)
526 527 528
  "Regexp which matches `tramp-echo-mark' as it gets echoed by
the remote shell.")

529 530
(defcustom tramp-local-end-of-line
  (if (memq system-type '(windows-nt)) "\r\n" "\n")
531
  "String used for end of line in local processes."
532
  :version "24.1"
533
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
534
  :type 'string)
535

Kai Großjohann's avatar
Kai Großjohann committed
536
(defcustom tramp-rsh-end-of-line "\n"
537
  "String used for end of line in rsh connections.
Kai Großjohann's avatar
Kai Großjohann committed
538
I don't think this ever needs to be changed, so please tell me about it
Michael Albinus's avatar
Michael Albinus committed
539
if you need to change this."
Kai Großjohann's avatar
Kai Großjohann committed
540
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
541
  :type 'string)
Kai Großjohann's avatar
Kai Großjohann committed
542 543

(defcustom tramp-login-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
544
  ".*\\(user\\|login\\)\\( .*\\)?: *"
545
  "Regexp matching login-like prompts.
546 547 548
The regexp should match at end of buffer.

Sometimes the prompt is reported to look like \"login as:\"."
Kai Großjohann's avatar
Kai Großjohann committed
549
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
550
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
551

Kai Großjohann's avatar
Kai Großjohann committed
552
(defcustom tramp-shell-prompt-pattern
553
  ;; Allow a prompt to start right after a ^M since it indeed would be
554 555
  ;; displayed at the beginning of the line (and Zsh uses it).  This
  ;; regexp works only for GNU Emacs.
Michael Albinus's avatar
Michael Albinus committed
556 557
  ;; Allow also [] style prompts.  They can appear only during
  ;; connection initialization; Tramp redefines the prompt afterwards.
558
  (concat "\\(?:^\\|\r\\)"
Michael Albinus's avatar
Michael Albinus committed
559
	  "[^]#$%>\n]*#?[]#$%>] *\\(\e\\[[0-9;]*[a-zA-Z] *\\)*")
Kai Großjohann's avatar
Kai Großjohann committed
560 561 562 563 564 565
  "Regexp to match prompts from remote shell.
Normally, Tramp expects you to configure `shell-prompt-pattern'
correctly, but sometimes it happens that you are connecting to a
remote host which sends a different kind of shell prompt.  Therefore,
Tramp recognizes things matched by `shell-prompt-pattern' as prompt,
and also things matched by this variable.  The default value of this
566
variable is similar to the default value of `shell-prompt-pattern',
567 568 569 570
which should work well in many cases.

This regexp must match both `tramp-initial-end-of-output' and
`tramp-end-of-output'."
Kai Großjohann's avatar
Kai Großjohann committed
571
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
572
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
573

Kai Großjohann's avatar
Kai Großjohann committed
574
(defcustom tramp-password-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
575
  (format "^.*\\(%s\\).*:\^@? *" (regexp-opt password-word-equivalents))
576
  "Regexp matching password-like prompts.
Kai Großjohann's avatar
Kai Großjohann committed
577
The regexp should match at end of buffer.
Kai Großjohann's avatar
Kai Großjohann committed
578 579

The `sudo' program appears to insert a `^@' character into the prompt."
580
  :version "24.4"
Kai Großjohann's avatar
Kai Großjohann committed
581
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
582
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
583 584

(defcustom tramp-wrong-passwd-regexp
Kai Großjohann's avatar
Kai Großjohann committed
585 586
  (concat "^.*"
	  ;; These strings should be on the last line
587
	  (regexp-opt '("Permission denied"
Kai Großjohann's avatar
Kai Großjohann committed
588 589 590
			"Login incorrect"
			"Login Incorrect"
			"Connection refused"
591
			"Connection closed"
Michael Albinus's avatar
Michael Albinus committed
592
			"Timeout, server not responding."
Kai Großjohann's avatar
Kai Großjohann committed
593 594
			"Sorry, try again."
			"Name or service not known"
595
			"Host key verification failed."
596 597
			"No supported authentication methods left to try!")
		      t)
Kai Großjohann's avatar
Kai Großjohann committed
598 599 600 601 602 603
	  ".*"
	  "\\|"
	  "^.*\\("
	  ;; Here comes a list of regexes, separated by \\|
	  "Received signal [0-9]+"
	  "\\).*")
604
  "Regexp matching a `login failed' message.
Kai Großjohann's avatar
Kai Großjohann committed
605 606
The regexp should match at end of buffer."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
607
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
608 609

(defcustom tramp-yesno-prompt-regexp
Kai Großjohann's avatar
Kai Großjohann committed
610
  (concat
611 612 613 614
   (regexp-opt
    '("Are you sure you want to continue connecting (yes/no)?"
      "Are you sure you want to continue connecting (yes/no/[fingerprint])?")
    t)
Kai Großjohann's avatar
Kai Großjohann committed
615 616
   "\\s-*")
  "Regular expression matching all yes/no queries which need to be confirmed.
Kai Großjohann's avatar
Kai Großjohann committed
617
The confirmation should be done with yes or no.
Kai Großjohann's avatar
Kai Großjohann committed
618 619
The regexp should match at end of buffer.
See also `tramp-yn-prompt-regexp'."
Kai Großjohann's avatar
Kai Großjohann committed
620
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
621
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
622

Kai Großjohann's avatar
Kai Großjohann committed
623
(defcustom tramp-yn-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
624 625
  (concat
   (regexp-opt '("Store key in cache? (y/n)"
626 627
		 "Update cached key? (y/n, Return cancels connection)")
               t)
Michael Albinus's avatar
Michael Albinus committed
628
   "\\s-*")
Kai Großjohann's avatar
Kai Großjohann committed
629 630 631 632 633
  "Regular expression matching all y/n queries which need to be confirmed.
The confirmation should be done with y or n.
The regexp should match at end of buffer.
See also `tramp-yesno-prompt-regexp'."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
634
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
635 636 637 638 639 640 641 642 643 644 645

(defcustom tramp-terminal-prompt-regexp
  (concat "\\("
	  "TERM = (.*)"
	  "\\|"
	  "Terminal type\\? \\[.*\\]"
	  "\\)\\s-*")
  "Regular expression matching all terminal setting prompts.
The regexp should match at end of buffer.
The answer will be provided by `tramp-action-terminal', which see."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
646
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
647

Michael Albinus's avatar
Michael Albinus committed
648 649 650 651 652 653 654
(defcustom tramp-operation-not-permitted-regexp
  (concat "\\(" "preserving times.*" "\\|" "set mode" "\\)" ":\\s-*"
	  (regexp-opt '("Operation not permitted") t))
  "Regular expression matching keep-date problems in (s)cp operations.
Copying has been performed successfully already, so this message can
be ignored safely."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
655
  :type 'regexp)
Michael Albinus's avatar
Michael Albinus committed
656

657 658 659 660 661
(defcustom tramp-copy-failed-regexp
  (concat "\\(.+: "
          (regexp-opt '("Permission denied"
                        "not a regular file"
                        "is a directory"
662 663
                        "No such file or directory")
                      t)
664 665 666
          "\\)\\s-*")
  "Regular expression matching copy problems in (s)cp operations."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
667
  :type 'regexp)
668

669
(defcustom tramp-process-alive-regexp
670
  ""
671
  "Regular expression indicating a process has finished.
672 673
In fact this expression is empty by intention, it will be used only to
check regularly the status of the associated process.
Kai Großjohann's avatar
Kai Großjohann committed
674
The answer will be provided by `tramp-action-process-alive',
675
`tramp-action-out-of-band', which see."
676
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
677
  :type 'regexp)
678

679
(defconst tramp-temp-name-prefix "tramp."
680
  "Prefix to use for temporary files.
Kai Großjohann's avatar
Kai Großjohann committed
681 682
If this is a relative file name (such as \"tramp.\"), it is considered
relative to the directory name returned by the function
683
`tramp-compat-temporary-file-directory' (which see).  It may also be an
Kai Großjohann's avatar
Kai Großjohann committed
684
absolute file name; don't forget to include a prefix for the filename
685
part, though.")
Kai Großjohann's avatar
Kai Großjohann committed
686

687 688 689 690
(defconst tramp-temp-buffer-name " *tramp temp*"
  "Buffer name for a temporary buffer.
It shall be used in combination with `generate-new-buffer-name'.")

691 692 693 694
(defvar tramp-temp-buffer-file-name nil
  "File name of a persistent local temporary file.
Useful for \"rsync\" like methods.")
(make-variable-buffer-local 'tramp-temp-buffer-file-name)
695
(put 'tramp-temp-buffer-file-name 'permanent-local t)
696

Michael Albinus's avatar
Michael Albinus committed
697
(defcustom tramp-syntax 'default
698 699 700 701
  "Tramp filename syntax to be used.

It can have the following values:

Michael Albinus's avatar
Michael Albinus committed
702 703
  `default'    -- Default syntax
  `simplified' -- Ange-FTP like syntax
Michael Albinus's avatar
Michael Albinus committed
704 705
  `separate'   -- Syntax as defined for XEmacs originally

706 707
Do not change the value by `setq', it must be changed only via
Customize.  See also `tramp-change-syntax'."
708
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
709
  :version "26.1"
Michael Albinus's avatar
Michael Albinus committed
710
  :package-version '(Tramp . "2.3.3")
Michael Albinus's avatar
Michael Albinus committed
711 712 713
  :type '(choice (const :tag "Default" default)
		 (const :tag "Ange-FTP" simplified)
		 (const :tag "XEmacs" separate))
Michael Albinus's avatar
Michael Albinus committed
714
  :require 'tramp
715 716
  :initialize #'custom-initialize-default
  :set #'tramp-set-syntax)
Michael Albinus's avatar
Michael Albinus committed
717 718 719 720 721 722 723

(defun tramp-set-syntax (symbol value)
  "Set SYMBOL to value VALUE.
Used in user option `tramp-syntax'.  There are further variables
to be set, depending on VALUE."
  ;; Check allowed values.
  (unless (memq value (tramp-syntax-values))
724
    (tramp-user-error "Wrong `tramp-syntax' %s" value))
Michael Albinus's avatar
Michael Albinus committed
725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750
  ;; Cleanup existing buffers.
  (unless (eq (symbol-value symbol) value)
    (tramp-cleanup-all-buffers))
  ;; Set the value:
  (set-default symbol value)
  ;; Reset the depending variables.
  (with-no-warnings
    (setq tramp-prefix-format (tramp-build-prefix-format)
	  tramp-prefix-regexp (tramp-build-prefix-regexp)
	  tramp-method-regexp (tramp-build-method-regexp)
	  tramp-postfix-method-format (tramp-build-postfix-method-format)
	  tramp-postfix-method-regexp (tramp-build-postfix-method-regexp)
	  tramp-prefix-ipv6-format (tramp-build-prefix-ipv6-format)
	  tramp-prefix-ipv6-regexp (tramp-build-prefix-ipv6-regexp)
	  tramp-postfix-ipv6-format (tramp-build-postfix-ipv6-format)
	  tramp-postfix-ipv6-regexp (tramp-build-postfix-ipv6-regexp)
	  tramp-postfix-host-format (tramp-build-postfix-host-format)
	  tramp-postfix-host-regexp (tramp-build-postfix-host-regexp)
	  tramp-remote-file-name-spec-regexp
          (tramp-build-remote-file-name-spec-regexp)
	  tramp-file-name-structure (tramp-build-file-name-structure)
	  tramp-file-name-regexp (tramp-build-file-name-regexp)
	  tramp-completion-file-name-regexp
          (tramp-build-completion-file-name-regexp)))
  ;; Rearrange file name handlers.
  (tramp-register-file-name-handlers))
Michael Albinus's avatar
Michael Albinus committed
751

752
;; Initialize the Tramp syntax variables.  We want to override initial
Michael Albinus's avatar
Michael Albinus committed
753 754 755
;; value of `tramp-file-name-regexp'.  Other Tramp syntax variables
;; must be initialized as well to proper values.  We do not call
;; `custom-set-variable', this would load Tramp via custom.el.
756 757
(tramp--with-startup
  (tramp-set-syntax 'tramp-syntax (tramp-compat-tramp-syntax)))
758

Michael Albinus's avatar
Michael Albinus committed
759 760 761
(defun tramp-syntax-values ()
  "Return possible values of `tramp-syntax', a list"
  (let ((values (cdr (get 'tramp-syntax 'custom-type))))
762 763 764
    (setq values (mapcar #'last values)
	  values (mapcar #'car values))
    values))
Michael Albinus's avatar
Michael Albinus committed
765

Gemini Lasswell's avatar
Gemini Lasswell committed
766 767 768 769 770 771 772 773 774 775 776 777
(defun tramp-lookup-syntax (alist)
  "Look up a syntax string in ALIST according to `tramp-compat-tramp-syntax.'
Raise an error if `tramp-syntax' is invalid."
  (or (cdr (assq (tramp-compat-tramp-syntax) alist))
      (error "Wrong `tramp-syntax' %s" tramp-syntax)))

(defconst tramp-prefix-format-alist
  '((default    . "/")
    (simplified . "/")
    (separate   . "/["))
  "Alist mapping Tramp syntax to strings beginning Tramp file names.")

778
(defun tramp-build-prefix-format ()
Gemini Lasswell's avatar
Gemini Lasswell committed
779 780
  (tramp-lookup-syntax tramp-prefix-format-alist))

781
(defvar tramp-prefix-format nil ;Initialized when defining `tramp-syntax'!
782 783 784 785 786
  "String matching the very beginning of Tramp file names.
Used in `tramp-make-tramp-file-name'.")

(defun tramp-build-prefix-regexp ()
  (concat "^" (regexp-quote tramp-prefix-format)))
787

788
(defvar tramp-prefix-regexp nil ;Initialized when defining `tramp-syntax'!
789
  "Regexp matching the very beginning of Tramp file names.
790
Should always start with \"^\". Derived from `tramp-prefix-format'.")
Gemini Lasswell's avatar
Gemini Lasswell committed
791 792 793 794 795 796

(defconst tramp-method-regexp-alist
  '((default    . "[a-zA-Z0-9-]+")
    (simplified . "")
    (separate   . "[a-zA-Z0-9-]*"))
  "Alist mapping Tramp syntax to regexps matching methods identifiers.")
797

798
(defun tramp-build-method-regexp ()
Gemini Lasswell's avatar
Gemini Lasswell committed
799 800
  (tramp-lookup-syntax tramp-method-regexp-alist))

801
(defvar tramp-method-regexp nil ;Initialized when defining `tramp-syntax'!
802 803 804
  "Regexp matching methods identifiers.
The `ftp' syntax does not support methods.")

Gemini Lasswell's avatar
Gemini Lasswell committed
805 806 807 808 809
(defconst tramp-postfix-method-format-alist
  '((default    . ":")
    (simplified . "")
    (separate   . "/"))
  "Alist mapping Tramp syntax to the delimiter after the method.")
810

811 812 813
(defun tramp-build-postfix-method-format ()
  (tramp-lookup-syntax tramp-postfix-method-format-alist))

814
(defvar tramp-postfix-method-format nil ;Init'd when defining `tramp-syntax'!
815
  "String matching delimiter between method and user or host names.
Michael Albinus's avatar
Michael Albinus committed
816
The `ftp' syntax does not support methods.
817
Used in `tramp-make-tramp-file-name'.")
Gemini Lasswell's avatar
Gemini Lasswell committed
818

819 820
(defun tramp-build-postfix-method-regexp ()
  (regexp-quote tramp-postfix-method-format))
821

822
(defvar tramp-postfix-method-regexp nil ;Init'd when defining `tramp-syntax'!
823
  "Regexp matching delimiter between method and user or host names.
824
Derived from `tramp-postfix-method-format'.")
825

Michael Albinus's avatar
Michael Albinus committed
826
(defconst tramp-user-regexp "[^/|: \t]+"
827
  "Regexp matching user names.")
828

829
(defconst tramp-prefix-domain-format "%"
830
  "String matching delimiter between user and domain names.")
831

832
(defconst tramp-prefix-domain-regexp (regexp-quote tramp-prefix-domain-format)
833
  "Regexp matching delimiter between user and domain names.
834 835
Derived from `tramp-prefix-domain-format'.")

836
(defconst tramp-domain-regexp "[a-zA-Z0-9_.-]+"
837
  "Regexp matching domain names.")
838 839 840 841 842

(defconst tramp-user-with-domain-regexp
  (concat "\\(" tramp-user-regexp "\\)"
	        tramp-prefix-domain-regexp
	  "\\(" tramp-domain-regexp "\\)")
843
  "Regexp matching user names with domain names.")
844

845
(defconst tramp-postfix-user-format "@"
846
  "String matching delimiter between user and host names.
847
Used in `tramp-make-tramp-file-name'.")
848

849
(defconst tramp-postfix-user-regexp (regexp-quote tramp-postfix-user-format)
850
  "Regexp matching delimiter between user and host names.
851 852
Derived from `tramp-postfix-user-format'.")

853
(defconst tramp-host-regexp "[a-zA-Z0-9_.%-]+"
854
  "Regexp matching host names.")
855

Gemini Lasswell's avatar
Gemini Lasswell committed
856 857 858 859 860 861
(defconst tramp-prefix-ipv6-format-alist
  '((default    . "[")
    (simplified . "[")
    (separate   . ""))
  "Alist mapping Tramp syntax to strings prefixing IPv6 addresses.")

862
(defun tramp-build-prefix-ipv6-format ()
Gemini Lasswell's avatar
Gemini Lasswell committed
863 864
  (tramp-lookup-syntax tramp-prefix-ipv6-format-alist))

865
(defvar tramp-prefix-ipv6-format nil ;Initialized when defining `tramp-syntax'!
866 867 868 869 870
  "String matching left hand side of IPv6 addresses.
Used in `tramp-make-tramp-file-name'.")

(defun tramp-build-prefix-ipv6-regexp ()
  (regexp-quote tramp-prefix-ipv6-format))
871

872
(defvar tramp-prefix-ipv6-regexp nil ;Initialized when defining `tramp-syntax'!
873
  "Regexp matching left hand side of IPv6 addresses.
874
Derived from `tramp-prefix-ipv6-format'.")