tramp.el 224 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-2021 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
Kai Großjohann's avatar
Kai Großjohann committed
10 11 12

;; This file is part of GNU Emacs.

13
;; GNU Emacs is free software: you can redistribute it and/or modify
Kai Großjohann's avatar
Kai Großjohann committed
14
;; it under the terms of the GNU General Public License as published by
15 16
;; 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
17 18 19 20 21 22 23

;; 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
24
;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
Kai Großjohann's avatar
Kai Großjohann committed
25 26 27 28 29 30 31 32

;;; 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.
;;
33
;; For more detailed instructions, please see the info file.
Kai Großjohann's avatar
Kai Großjohann committed
34 35
;;
;; Notes:
36
;; ------
37
;;
Kai Großjohann's avatar
Kai Großjohann committed
38 39
;; Also see the todo list at the bottom of this file.
;;
40
;; The current version of Tramp can be retrieved from the following URL:
41
;;            https://ftp.gnu.org/gnu/tramp/
Kai Großjohann's avatar
Kai Großjohann committed
42 43
;;
;; There's a mailing list for this, as well.  Its name is:
Michael Albinus's avatar
Michael Albinus committed
44
;;            tramp-devel@gnu.org
45

Michael Albinus's avatar
Michael Albinus committed
46
;; You can use the Web to subscribe, under the following URL:
Paul Eggert's avatar
Paul Eggert committed
47
;;            https://lists.gnu.org/mailman/listinfo/tramp-devel
Kai Großjohann's avatar
Kai Großjohann committed
48 49
;;
;; For the adventurous, the current development sources are available
50
;; via Git.  You can find instructions about this at the following URL:
51
;;            https://savannah.gnu.org/projects/tramp/
Kai Großjohann's avatar
Kai Großjohann committed
52 53 54 55 56
;;
;; Don't forget to put on your asbestos longjohns, first!

;;; Code:

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

Michael Albinus's avatar
Michael Albinus committed
61
;; Pacify byte-compiler.
Michael Albinus's avatar
Michael Albinus committed
62
(require 'cl-lib)
63
(declare-function file-notify-rm-watch "filenotify")
64
(declare-function netrc-parse "netrc")
Michael Albinus's avatar
Michael Albinus committed
65
(defvar auto-save-file-name-transforms)
Michael Albinus's avatar
Michael Albinus committed
66

Michael Albinus's avatar
Michael Albinus committed
67 68 69 70
;; Reload `tramp-compat' when we reload `tramp-autoloads' of the GNU ELPA package.
;;;###autoload (when (featurep 'tramp-compat)
;;;###autoload   (load "tramp-compat" 'noerror 'nomessage))

Kai Großjohann's avatar
Kai Großjohann committed
71 72 73
;;; User Customizable Internal Variables:

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

80
(eval-and-compile ;; So it's also available in tramp-loaddefs.el!
81 82
  (defvar tramp--startup-hook nil
    "Forms to be executed at the end of tramp.el.")
83
  (put 'tramp--startup-hook 'tramp-suppress-trace t)
84

85 86 87 88 89 90
  (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)

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

98
(defcustom tramp-verbose 3
99
  "Verbosity level for Tramp messages.
100 101 102 103 104 105 106 107 108 109 110
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
111
 9  test commands
Michael Albinus's avatar
Michael Albinus committed
112 113
10  traces (huge)
11  call traces (maintainer only)."
Michael Albinus's avatar
Michael Albinus committed
114
  :type 'integer)
Kai Großjohann's avatar
Kai Großjohann committed
115

116 117 118 119 120 121 122
(defcustom tramp-debug-to-file nil
  "Whether Tramp debug messages shall be saved to file.
The debug file has the same name as the debug buffer, written to
`temporary-file-directory'."
  :version "28.1"
  :type 'boolean)

123 124
(defcustom tramp-backup-directory-alist nil
  "Alist of filename patterns and backup directory names.
125 126 127
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
128
name prefix \(method, user, host) of file.
129

130
  (setq tramp-backup-directory-alist backup-directory-alist)
131 132 133

gives the same backup policy for Tramp files on their hosts like the
policy for local files."
134
  :type '(repeat (cons (regexp :tag "Regexp matching filename")
Michael Albinus's avatar
Michael Albinus committed
135
		       (directory :tag "Backup directory name"))))
136

Kai Großjohann's avatar
Kai Großjohann committed
137
(defcustom tramp-auto-save-directory nil
138
  "Put auto-save files in this directory, if set.
139 140 141
The idea is to use a local directory so that auto-saving is faster.
This setting has precedence over `auto-save-file-name-transforms'."
  :type '(choice (const :tag "Use default" nil)
Michael Albinus's avatar
Michael Albinus committed
142
		 (directory :tag "Auto save directory name")))
Kai Großjohann's avatar
Kai Großjohann committed
143

144
;; Suppress `shell-file-name' for w32 systems.
145
(defcustom tramp-encoding-shell
146 147
  (let (shell-file-name)
    (or (tramp-compat-funcall 'w32-shell-name) "/bin/sh"))
148
  "Use this program for encoding and decoding commands on the local host.
149
This shell is used to execute the encoding and decoding command on the
Michael Albinus's avatar
Michael Albinus committed
150 151
local host, so if you want to use \"~\" in those commands, you should
choose a shell here which groks tilde expansion.  \"/bin/sh\" normally
152 153
does not understand tilde expansion.

Paul Eggert's avatar
Paul Eggert committed
154
For encoding and decoding, commands like the following are executed:
155 156 157 158

    /bin/sh -c COMMAND < INPUT > OUTPUT

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

161 162 163
If the shell must be forced to be interactive, see
`tramp-encoding-command-interactive'.

Kai Großjohann's avatar
Kai Großjohann committed
164 165 166
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."
Michael Albinus's avatar
Michael Albinus committed
167
  :type '(file :must-match t))
Kai Großjohann's avatar
Kai Großjohann committed
168

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

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

Michael Albinus's avatar
Michael Albinus committed
186 187 188 189 190 191
;; Since Emacs 26.1, `system-name' can return `nil' at build time if
;; Emacs is compiled with "--no-build-details".  We do expect it to be
;; a string.  (Bug#44481)
(defconst tramp-system-name (or (system-name) "")
  "The system name Tramp is running locally.")

192
(defvar tramp-methods nil
193
  "Alist of methods for remote files.
Kai Großjohann's avatar
Kai Großjohann committed
194 195 196
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:
197

198
  * `tramp-remote-shell'
199 200 201 202 203 204 205
    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.
206

Michael Albinus's avatar
Michael Albinus committed
207 208 209 210 211 212
  * `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.
213

214 215
  * `tramp-remote-shell-args'
    For implementation of `shell-command', this specifies the
216
    arguments to let `tramp-remote-shell' run a single command.
217

218 219
  * `tramp-login-program'
    This specifies the name of the program to use for logging in to the
220 221
    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.
222

223
  * `tramp-login-args'
224 225 226 227
    This specifies a list of lists of arguments to pass to the
    above mentioned program.  You normally want to put each
    argument in an individual string, i.e.
    (\"-a\" \"-b\") rather than (\"-a -b\").
228

229 230 231 232
    \"%\" followed by a letter are expanded in the arguments as
    follows:

    - \"%h\" is replaced by the host name
233 234 235 236
    - \"%u\" is replaced by the user name
    - \"%p\" is replaced by the port number
    - \"%%\" can be used to obtain a literal percent character.

237 238 239 240 241 242 243 244 245 246
    If a sub-list containing \"%h\", \"%u\" or \"%p\" is
    unchanged after expansion (i.e. no host, no user or no port
    were specified), that sublist is not used.  For e.g.

    '((\"-a\" \"-b\") (\"-l\" \"%u\"))

    that means that (\"-l\" \"%u\") is used only if the user was
    specified, and it is thus effectively optional.

    Other expansions are:
247 248 249 250 251

    - \"%l\" is replaced by the login shell `tramp-remote-shell'
      and its parameters.
    - \"%t\" is replaced by the temporary file name produced with
      `tramp-make-tramp-temp-file'.
252
    - \"%k\" indicates the keep-date parameter of a program, if exists.
253 254
    - \"%c\" adds additional `tramp-ssh-controlmaster-options'
      options for the first hop.
255
    - \"%n\" expands to \"2>/dev/null\".
256 257
    - \"%x\" is replaced by the `tramp-scp-strict-file-name-checking'
      argument if it is supported.
258 259 260 261

    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.
262

263 264 265 266 267
  * `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.
268

269 270 271
  * `tramp-direct-async'
    Whether the method supports direct asynchronous processes.
    Until now, just \"ssh\"-based and \"adb\"-based methods do.
272

273 274
  * `tramp-copy-program'
    This specifies the name of the program to use for remotely copying
275
    the file; this might be the absolute filename of scp or the name of
276
    a workalike program.  It is always applied on the local host.
277

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

282 283 284
  * `tramp-copy-env'
     A list of environment variables and their values, which will
     be set when calling `tramp-copy-program'.
285

286 287
  * `tramp-remote-copy-program'
    The listener program to be applied on remote side, if needed.
288

289 290 291 292 293
  * `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.
294

295 296 297
  * `tramp-copy-keep-date'
    This specifies whether the copying program when the preserves the
    timestamp of the original file.
298

299 300 301
  * `tramp-copy-keep-tmpfile'
    This specifies whether a temporary local file shall be kept
    for optimization reasons (useful for \"rsync\" methods).
302

303 304
  * `tramp-copy-recursive'
    Whether the operation copies directories recursively.
305

306
  * `tramp-default-port'
307
    The default port of a method.
308

309 310 311
  * `tramp-tmpdir'
    A directory on the remote host for temporary files.  If not
    specified, \"/tmp\" is taken as default.
312

313 314 315 316 317
  * `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.
318

319 320 321 322
  * `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.
323

324 325 326 327 328
  * `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.
329

330 331 332 333 334 335 336 337 338 339 340
  * `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.

341 342 343
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
344
remote side.  One way is using an additional scp-like program.  If you want
345
to do this, set `tramp-copy-program' in the method.
Kai Großjohann's avatar
Kai Großjohann committed
346 347

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

355
So, to summarize: if the method is an out-of-band method, then you
356
must specify `tramp-copy-program' and `tramp-copy-args'.  If it is an
357
inline method, then these two parameters should be nil.
Kai Großjohann's avatar
Kai Großjohann committed
358 359 360

Notes:

361 362 363
All these arguments can be overwritten by connection properties.
See Info node `(tramp) Predefined connection information'.

364 365 366 367 368 369 370
When using `su', `sudo' or `doas' the phrase \"open connection to
a remote host\" sounds strange, but it is used nevertheless, for
consistency.  No connection is opened to a remote host, but `su',
`sudo' or `doas' 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
371

372
(defcustom tramp-default-method
Paul Eggert's avatar
Paul Eggert committed
373 374
  ;; An external copy method seems to be preferred, because it performs
  ;; much better for large files, and it hasn't too serious delays
375 376
  ;; for small files.  But it must be ensured that there aren't
  ;; permanent password queries.  Either a password agent like
377 378
  ;; "ssh-agent" or "Pageant" shall run, or the optional
  ;; password-cache.el or auth-sources.el packages shall be active for
379 380 381
  ;; 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.
382
  (cond
Glenn Morris's avatar
Glenn Morris committed
383 384 385
   ;; 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.
386
   ((and (eq system-type 'windows-nt) (executable-find "pscp")) "pscp")
387
   ;; There is an ssh installation.
388
   ((executable-find "scp") "scp")
389 390
   ;; Fallback.
   (t "ftp"))
391
  "Default method to use for transferring files.
392
See `tramp-methods' for possibilities.
393
Also see `tramp-default-method-alist'."
Michael Albinus's avatar
Michael Albinus committed
394
  :type 'string)
395

396
(defcustom tramp-default-method-alist nil
397 398
  ;; FIXME: This is not an "alist", because its elements are not of
  ;; the form (KEY . VAL) but (KEY1 KEY2 VAL).
399
  "Default method to use for specific host/user pairs.
400 401 402 403 404 405 406 407 408 409
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."
410 411
  :type '(repeat (list (choice :tag "Host regexp" regexp sexp)
		       (choice :tag "User regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
412
		       (choice :tag "Method name" string (const nil)))))
413

414 415 416
(defconst tramp-default-method-marker "-"
  "Marker for default method in remote file names.")

417
(defcustom tramp-default-user nil
418
  "Default user to use for transferring files.
419 420 421 422
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."
Michael Albinus's avatar
Michael Albinus committed
423
  :type '(choice (const nil) string))
424

425
(defcustom tramp-default-user-alist nil
426 427
  ;; FIXME: This is not an "alist", because its elements are not of
  ;; the form (KEY . VAL) but (KEY1 KEY2 VAL).
428
  "Default user to use for specific method/host pairs.
429 430
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
431
user.  METHOD and HOST are regular expressions or nil, which is
432 433 434 435 436
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."
437 438
  :type '(repeat (list (choice :tag "Method regexp" regexp sexp)
		       (choice :tag "  Host regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
439
		       (choice :tag "    User name" string (const nil)))))
440

Michael Albinus's avatar
Michael Albinus committed
441
(defcustom tramp-default-host tramp-system-name
442
  "Default host to use for transferring files.
443
Useful for su and sudo methods mostly."
Michael Albinus's avatar
Michael Albinus committed
444
  :type 'string)
445

446
(defcustom tramp-default-host-alist nil
447 448
  ;; FIXME: This is not an "alist", because its elements are not of
  ;; the form (KEY . VAL) but (KEY1 KEY2 VAL).
449 450 451
  "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
452
host.  METHOD and USER are regular expressions or nil, which is
453 454 455 456 457
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."
Glenn Morris's avatar
Glenn Morris committed
458
  :version "24.4"
459 460
  :type '(repeat (list (choice :tag "Method regexp" regexp sexp)
		       (choice :tag "  User regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
461
		       (choice :tag "    Host name" string (const nil)))))
462

463
(defcustom tramp-default-proxies-alist nil
464 465
  ;; FIXME: This is not an "alist", because its elements are not of
  ;; the form (KEY . VAL) but (KEY1 KEY2 VAL).
466
  "Route to be followed for specific host/user pairs.
467 468 469
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
470 471 472 473 474 475 476 477 478 479 480
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'.
481 482 483 484 485 486

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."
  :type '(repeat (list (choice :tag "Host regexp" regexp sexp)
		       (choice :tag "User regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
487
		       (choice :tag " Proxy name" string (const nil)))))
488

Michael Albinus's avatar
Michael Albinus committed
489 490
(defcustom tramp-save-ad-hoc-proxies nil
  "Whether to save ad-hoc proxies persistently."
Glenn Morris's avatar
Glenn Morris committed
491
  :version "24.3"
Michael Albinus's avatar
Michael Albinus committed
492
  :type 'boolean)
Michael Albinus's avatar
Michael Albinus committed
493

494 495 496
;; For some obscure technical reasons, `system-name' on w32 returns
;; either lower case or upper case letters.  See
;; <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=38079#20>.
497
(defcustom tramp-restricted-shell-hosts-alist
498
  (when (eq system-type 'windows-nt)
499
    (list (format "\\`\\(%s\\|%s\\)\\'"
Michael Albinus's avatar
Michael Albinus committed
500 501
		  (regexp-quote (downcase tramp-system-name))
		  (regexp-quote (upcase tramp-system-name)))))
502 503
  "List of hosts, which run a restricted shell.
This is a list of regular expressions, which denote hosts running
504
a restricted shell like \"rbash\".  Those hosts can be used as
505
proxies only, see `tramp-default-proxies-alist'.  If the local
506 507
host runs a restricted shell, it shall be added to this list, too."
  :version "27.1"
Michael Albinus's avatar
Michael Albinus committed
508
  :type '(repeat (regexp :tag "Host regexp")))
509

510
(defcustom tramp-local-host-regexp
511
  (concat
512 513
   "\\`"
   (regexp-opt
Michael Albinus's avatar
Michael Albinus committed
514
    (list "localhost" "localhost6" tramp-system-name "127.0.0.1" "::1") t)
515
   "\\'")
516 517 518 519
  "Host names which are regarded as local host.
If the local host runs a chrooted environment, set this to nil."
  :version "27.1"
  :type '(choice (const :tag "Chrooted environment" nil)
Michael Albinus's avatar
Michael Albinus committed
520
		 (regexp :tag "Host regexp")))
521

522
(defvar tramp-completion-function-alist nil
523
  "Alist of methods for remote files.
524
This is a list of entries of the form \(NAME PAIR1 PAIR2 ...).
525
Each NAME stands for a remote access method.  Each PAIR is of the form
526
\(FUNCTION FILE).  FUNCTION is responsible to extract user names and host
527 528
names from FILE for completion.  The following predefined FUNCTIONs exists:

529 530 531 532 533 534 535
 * `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
536
 * `tramp-parse-etc-group'   for \"/etc/group\" like files.
537
 * `tramp-parse-netrc'       for \"~/.netrc\" like files.
Michael Albinus's avatar
Michael Albinus committed
538
 * `tramp-parse-putty'       for PuTTY registered sessions.
539

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

543 544 545
(defconst tramp-echo-mark-marker "_echo"
  "String marker to surround echoed commands.")

546 547 548 549 550 551
(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))
552 553 554 555 556
  "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
557 558 559
`tramp-echoed-echo-mark-regexp'.  Using `tramp-echo-mark-marker',
followed by an equal number of backspaces to erase them will
usually suffice.")
560

561 562 563
(defconst tramp-echoed-echo-mark-regexp
  (format "%s\\(\b\\( \b\\)?\\)\\{%d\\}"
	  tramp-echo-mark-marker tramp-echo-mark-marker-length)
564
  "Regexp which matches `tramp-echo-mark' as it gets echoed by \
565 566
the remote shell.")

567
(defcustom tramp-local-end-of-line
568
  (if (eq system-type 'windows-nt) "\r\n" "\n")
569
  "String used for end of line in local processes."
570
  :version "24.1"
Michael Albinus's avatar
Michael Albinus committed
571
  :type 'string)
572

Kai Großjohann's avatar
Kai Großjohann committed
573
(defcustom tramp-rsh-end-of-line "\n"
574
  "String used for end of line in rsh connections.
Kai Großjohann's avatar
Kai Großjohann committed
575
I don't think this ever needs to be changed, so please tell me about it
Michael Albinus's avatar
Michael Albinus committed
576
if you need to change this."
Michael Albinus's avatar
Michael Albinus committed
577
  :type 'string)
Kai Großjohann's avatar
Kai Großjohann committed
578 579

(defcustom tramp-login-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
580
  ".*\\(user\\|login\\)\\( .*\\)?: *"
581
  "Regexp matching login-like prompts.
582 583 584
The regexp should match at end of buffer.

Sometimes the prompt is reported to look like \"login as:\"."
Michael Albinus's avatar
Michael Albinus committed
585
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
586

Kai Großjohann's avatar
Kai Großjohann committed
587
(defcustom tramp-shell-prompt-pattern
588
  ;; Allow a prompt to start right after a ^M since it indeed would be
589 590
  ;; 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
591 592
  ;; Allow also [] style prompts.  They can appear only during
  ;; connection initialization; Tramp redefines the prompt afterwards.
593
  (concat "\\(?:^\\|\r\\)"
Michael Albinus's avatar
Michael Albinus committed
594
	  "[^]#$%>\n]*#?[]#$%>] *\\(\e\\[[[:digit:];]*[[:alpha:]] *\\)*")
Kai Großjohann's avatar
Kai Großjohann committed
595 596 597 598 599 600
  "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
601
variable is similar to the default value of `shell-prompt-pattern',
602 603 604 605
which should work well in many cases.

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

Kai Großjohann's avatar
Kai Großjohann committed
608
(defcustom tramp-password-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
609
  (format "^.*\\(%s\\).*:\^@? *" (regexp-opt password-word-equivalents))
610
  "Regexp matching password-like prompts.
Kai Großjohann's avatar
Kai Großjohann committed
611
The regexp should match at end of buffer.
Kai Großjohann's avatar
Kai Großjohann committed
612

613
This variable is, by default, initialised from
Michael Albinus's avatar
Michael Albinus committed
614
`password-word-equivalents' when Tramp is loaded, and it is
615 616 617
usually more convenient to add new passphrases to that variable
instead of altering this variable.

Kai Großjohann's avatar
Kai Großjohann committed
618
The `sudo' program appears to insert a `^@' character into the prompt."
619
  :version "24.4"
Michael Albinus's avatar
Michael Albinus committed
620
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
621 622

(defcustom tramp-wrong-passwd-regexp
Kai Großjohann's avatar
Kai Großjohann committed
623 624
  (concat "^.*"
	  ;; These strings should be on the last line
625
	  (regexp-opt '("Permission denied"
Kai Großjohann's avatar
Kai Großjohann committed
626 627 628
			"Login incorrect"
			"Login Incorrect"
			"Connection refused"
629
			"Connection closed"
Michael Albinus's avatar
Michael Albinus committed
630
			"Timeout, server not responding."
Kai Großjohann's avatar
Kai Großjohann committed
631 632
			"Sorry, try again."
			"Name or service not known"
633
			"Host key verification failed."
634 635
			"No supported authentication methods left to try!")
		      t)
Kai Großjohann's avatar
Kai Großjohann committed
636 637 638 639
	  ".*"
	  "\\|"
	  "^.*\\("
	  ;; Here comes a list of regexes, separated by \\|
Michael Albinus's avatar
Michael Albinus committed
640
	  "Received signal [[:digit:]]+"
Kai Großjohann's avatar
Kai Großjohann committed
641
	  "\\).*")
642
  "Regexp matching a `login failed' message.
Kai Großjohann's avatar
Kai Großjohann committed
643
The regexp should match at end of buffer."
Michael Albinus's avatar
Michael Albinus committed
644
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
645 646

(defcustom tramp-yesno-prompt-regexp
Kai Großjohann's avatar
Kai Großjohann committed
647
  (concat
648 649 650 651
   (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
652 653
   "\\s-*")
  "Regular expression matching all yes/no queries which need to be confirmed.
Kai Großjohann's avatar
Kai Großjohann committed
654
The confirmation should be done with yes or no.
Kai Großjohann's avatar
Kai Großjohann committed
655 656
The regexp should match at end of buffer.
See also `tramp-yn-prompt-regexp'."
Michael Albinus's avatar
Michael Albinus committed
657
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
658

Kai Großjohann's avatar
Kai Großjohann committed
659
(defcustom tramp-yn-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
660 661
  (concat
   (regexp-opt '("Store key in cache? (y/n)"
662 663
		 "Update cached key? (y/n, Return cancels connection)")
               t)
Michael Albinus's avatar
Michael Albinus committed
664
   "\\s-*")
Kai Großjohann's avatar
Kai Großjohann committed
665 666 667 668
  "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'."
Michael Albinus's avatar
Michael Albinus committed
669
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
670

671 672 673 674 675 676 677 678
(defcustom tramp-terminal-type "dumb"
  "Value of TERM environment variable for logging in to remote host.
Because Tramp wants to parse the output of the remote shell, it is easily
confused by ANSI color escape sequences and suchlike.  Often, shell init
files conditionalize this setup based on the TERM environment variable."
  :group 'tramp
  :type 'string)

Kai Großjohann's avatar
Kai Großjohann committed
679 680 681 682 683 684 685 686 687
(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."
Michael Albinus's avatar
Michael Albinus committed
688
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
689

690 691
;; Plink 0.71 has added an additional anti-spoofing prompt after
;; authentication.  This could be discarded with the argument
Michael Albinus's avatar
Michael Albinus committed
692
;; "-no-antispoof".  However, since we don't know which PuTTY
693 694 695
;; version is installed, we must react interactively.
(defcustom tramp-antispoof-regexp
  (regexp-quote "Access granted. Press Return to begin session. ")
Michael Albinus's avatar
Michael Albinus committed
696 697
  "Regular expression matching plink's anti-spoofing message.
The regexp should match at end of buffer."
698
  :version "27.1"
699 700
  :type 'regexp)

Michael Albinus's avatar
Michael Albinus committed
701 702 703 704 705 706
(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."
Michael Albinus's avatar
Michael Albinus committed
707
  :type 'regexp)
Michael Albinus's avatar
Michael Albinus committed
708

709 710 711 712 713
(defcustom tramp-copy-failed-regexp
  (concat "\\(.+: "
          (regexp-opt '("Permission denied"
                        "not a regular file"
                        "is a directory"
714 715
                        "No such file or directory")
                      t)
716 717
          "\\)\\s-*")
  "Regular expression matching copy problems in (s)cp operations."
Michael Albinus's avatar
Michael Albinus committed
718
  :type 'regexp)
719

720
(defcustom tramp-process-alive-regexp
721
  ""
722
  "Regular expression indicating a process has finished.
723 724
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
725
The answer will be provided by `tramp-action-process-alive',
726
`tramp-action-out-of-band', which see."
Michael Albinus's avatar
Michael Albinus committed
727
  :type 'regexp)
728

729
(defconst tramp-temp-name-prefix "tramp."
730
  "Prefix to use for temporary files.
Kai Großjohann's avatar
Kai Großjohann committed
731 732
If this is a relative file name (such as \"tramp.\"), it is considered
relative to the directory name returned by the function
733
`tramp-compat-temporary-file-directory' (which see).  It may also be an
Kai Großjohann's avatar
Kai Großjohann committed
734
absolute file name; don't forget to include a prefix for the filename
735
part, though.")
Kai Großjohann's avatar
Kai Großjohann committed
736

737 738 739 740
(defconst tramp-temp-buffer-name " *tramp temp*"
  "Buffer name for a temporary buffer.
It shall be used in combination with `generate-new-buffer-name'.")

741 742 743 744
(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)
745
(put 'tramp-temp-buffer-file-name 'permanent-local t)
746

Michael Albinus's avatar
Michael Albinus committed
747
(defcustom tramp-syntax 'default
748 749 750 751
  "Tramp filename syntax to be used.

It can have the following values:

Michael Albinus's avatar
Michael Albinus committed
752 753
  `default'    -- Default syntax
  `simplified' -- Ange-FTP like syntax
Michael Albinus's avatar
Michael Albinus committed
754 755
  `separate'   -- Syntax as defined for XEmacs originally

756 757
Do not change the value by `setq', it must be changed only via
Customize.  See also `tramp-change-syntax'."
Michael Albinus's avatar
Michael Albinus committed
758
  :version "26.1"
Michael Albinus's avatar
Michael Albinus committed
759
  :package-version '(Tramp . "2.3.3")
Michael Albinus's avatar
Michael Albinus committed
760 761 762
  :type '(choice (const :tag "Default" default)
		 (const :tag "Ange-FTP" simplified)
		 (const :tag "XEmacs" separate))
Michael Albinus's avatar
Michael Albinus committed
763
  :require 'tramp
764 765
  :initialize #'custom-initialize-default
  :set #'tramp-set-syntax)
Michael Albinus's avatar
Michael Albinus committed
766 767 768 769 770 771 772

(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))
Michael Albinus's avatar
Michael Albinus committed
773
    (tramp-user-error nil "Wrong `tramp-syntax' %s" value))
Michael Albinus's avatar
Michael Albinus committed
774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792
  ;; 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
Michael Albinus's avatar
Michael Albinus committed
793
	  (tramp-build-remote-file-name-spec-regexp)
Michael Albinus's avatar
Michael Albinus committed
794 795 796 797 798 799
	  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
800

801
;; Initialize the Tramp syntax variables.  We want to override initial
Michael Albinus's avatar
Michael Albinus committed
802 803 804
;; 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.
805 806
(tramp--with-startup
  (tramp-set-syntax 'tramp-syntax (tramp-compat-tramp-syntax)))
807

Michael Albinus's avatar
Michael Albinus committed
808
(defun tramp-syntax-values ()
809
  "Return possible values of `tramp-syntax', a list."
Michael Albinus's avatar
Michael Albinus committed
810
  (let ((values (cdr (get 'tramp-syntax 'custom-type))))
811 812 813
    (setq values (mapcar #'last values)
	  values (mapcar #'car values))
    values))
Michael Albinus's avatar
Michael Albinus committed
814

Gemini Lasswell's avatar
Gemini Lasswell committed
815
(defun tramp-lookup-syntax (alist)
816
  "Look up a syntax string in ALIST according to `tramp-compat-tramp-syntax'.