tramp.el 216 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

Kai Großjohann's avatar
Kai Großjohann committed
67 68 69
;;; User Customizable Internal Variables:

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

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

81 82 83 84 85 86
  (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)

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

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

111 112 113 114 115 116 117
(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)

118 119
(defcustom tramp-backup-directory-alist nil
  "Alist of filename patterns and backup directory names.
120 121 122
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
123
name prefix \(method, user, host) of file.
124

125
  (setq tramp-backup-directory-alist backup-directory-alist)
126 127 128

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

Kai Großjohann's avatar
Kai Großjohann committed
132
(defcustom tramp-auto-save-directory nil
133
  "Put auto-save files in this directory, if set.
134 135 136
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
137
		 (directory :tag "Auto save directory name")))
Kai Großjohann's avatar
Kai Großjohann committed
138

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

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

    /bin/sh -c COMMAND < INPUT > OUTPUT

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

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

Kai Großjohann's avatar
Kai Großjohann committed
159 160 161
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
162
  :type '(file :must-match t))
Kai Großjohann's avatar
Kai Großjohann committed
163

164
;; Suppress `shell-file-name' for w32 systems.
Michael Albinus's avatar
Michael Albinus committed
165
(defcustom tramp-encoding-command-switch
166 167
  (let (shell-file-name)
    (if (tramp-compat-funcall 'w32-shell-dos-semantics) "/c" "-c"))
168
  "Use this switch together with `tramp-encoding-shell' for local commands.
169
See the variable `tramp-encoding-shell' for more information."
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"
Michael Albinus's avatar
Michael Albinus committed
179
  :type '(choice (const nil) string))
180

Michael Albinus's avatar
Michael Albinus committed
181 182 183 184 185 186
;; 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.")

187
(defvar tramp-methods nil
188
  "Alist of methods for remote files.
Kai Großjohann's avatar
Kai Großjohann committed
189 190 191
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:
192

193
  * `tramp-remote-shell'
194 195 196 197 198 199 200
    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.
201

Michael Albinus's avatar
Michael Albinus committed
202 203 204 205 206 207
  * `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.
208

209 210
  * `tramp-remote-shell-args'
    For implementation of `shell-command', this specifies the
211
    arguments to let `tramp-remote-shell' run a single command.
212

213 214
  * `tramp-login-program'
    This specifies the name of the program to use for logging in to the
215 216
    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.
217

218
  * `tramp-login-args'
219 220 221 222
    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\").
223

224 225 226 227
    \"%\" followed by a letter are expanded in the arguments as
    follows:

    - \"%h\" is replaced by the host name
228 229 230 231
    - \"%u\" is replaced by the user name
    - \"%p\" is replaced by the port number
    - \"%%\" can be used to obtain a literal percent character.

232 233 234 235 236 237 238 239 240 241
    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:
242 243 244 245 246

    - \"%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'.
247
    - \"%k\" indicates the keep-date parameter of a program, if exists.
248 249
    - \"%c\" adds additional `tramp-ssh-controlmaster-options'
      options for the first hop.
250
    - \"%n\" expands to \"2>/dev/null\".
251 252 253 254

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

256 257 258 259 260
  * `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.
261

262 263 264
  * `tramp-direct-async'
    Whether the method supports direct asynchronous processes.
    Until now, just \"ssh\"-based and \"adb\"-based methods do.
265

266 267
  * `tramp-copy-program'
    This specifies the name of the program to use for remotely copying
268
    the file; this might be the absolute filename of scp or the name of
269
    a workalike program.  It is always applied on the local host.
270

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

275 276 277
  * `tramp-copy-env'
     A list of environment variables and their values, which will
     be set when calling `tramp-copy-program'.
278

279 280
  * `tramp-remote-copy-program'
    The listener program to be applied on remote side, if needed.
281

282 283 284 285 286
  * `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.
287

288 289 290
  * `tramp-copy-keep-date'
    This specifies whether the copying program when the preserves the
    timestamp of the original file.
291

292 293 294
  * `tramp-copy-keep-tmpfile'
    This specifies whether a temporary local file shall be kept
    for optimization reasons (useful for \"rsync\" methods).
295

296 297
  * `tramp-copy-recursive'
    Whether the operation copies directories recursively.
298

299
  * `tramp-default-port'
300
    The default port of a method.
301

302 303 304
  * `tramp-tmpdir'
    A directory on the remote host for temporary files.  If not
    specified, \"/tmp\" is taken as default.
305

306 307 308 309 310
  * `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.
311

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

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

323 324 325 326 327 328 329 330 331 332 333
  * `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.

334 335 336
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
337
remote side.  One way is using an additional scp-like program.  If you want
338
to do this, set `tramp-copy-program' in the method.
Kai Großjohann's avatar
Kai Großjohann committed
339 340

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

348
So, to summarize: if the method is an out-of-band method, then you
349
must specify `tramp-copy-program' and `tramp-copy-args'.  If it is an
350
inline method, then these two parameters should be nil.
Kai Großjohann's avatar
Kai Großjohann committed
351 352 353

Notes:

354 355 356
All these arguments can be overwritten by connection properties.
See Info node `(tramp) Predefined connection information'.

357 358 359 360 361 362 363
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
364

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

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

407 408 409
(defconst tramp-default-method-marker "-"
  "Marker for default method in remote file names.")

410
(defcustom tramp-default-user nil
411
  "Default user to use for transferring files.
412 413 414 415
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
416
  :type '(choice (const nil) string))
417

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

Michael Albinus's avatar
Michael Albinus committed
434
(defcustom tramp-default-host tramp-system-name
435
  "Default host to use for transferring files.
436
Useful for su and sudo methods mostly."
Michael Albinus's avatar
Michael Albinus committed
437
  :type 'string)
438

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

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

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
480
		       (choice :tag " Proxy name" string (const nil)))))
481

Michael Albinus's avatar
Michael Albinus committed
482 483
(defcustom tramp-save-ad-hoc-proxies nil
  "Whether to save ad-hoc proxies persistently."
Glenn Morris's avatar
Glenn Morris committed
484
  :version "24.3"
Michael Albinus's avatar
Michael Albinus committed
485
  :type 'boolean)
Michael Albinus's avatar
Michael Albinus committed
486

487 488 489
;; 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>.
490 491
(defcustom tramp-restricted-shell-hosts-alist
  (when (memq system-type '(windows-nt))
492
    (list (format "\\`\\(%s\\|%s\\)\\'"
Michael Albinus's avatar
Michael Albinus committed
493 494
		  (regexp-quote (downcase tramp-system-name))
		  (regexp-quote (upcase tramp-system-name)))))
495 496
  "List of hosts, which run a restricted shell.
This is a list of regular expressions, which denote hosts running
497
a restricted shell like \"rbash\".  Those hosts can be used as
498
proxies only, see `tramp-default-proxies-alist'.  If the local
499 500
host runs a restricted shell, it shall be added to this list, too."
  :version "27.1"
Michael Albinus's avatar
Michael Albinus committed
501
  :type '(repeat (regexp :tag "Host regexp")))
502

503
(defcustom tramp-local-host-regexp
504
  (concat
505 506
   "\\`"
   (regexp-opt
Michael Albinus's avatar
Michael Albinus committed
507
    (list "localhost" "localhost6" tramp-system-name "127.0.0.1" "::1") t)
508
   "\\'")
509 510 511 512
  "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
513
		 (regexp :tag "Host regexp")))
514

515
(defvar tramp-completion-function-alist nil
516
  "Alist of methods for remote files.
517
This is a list of entries of the form \(NAME PAIR1 PAIR2 ...).
518
Each NAME stands for a remote access method.  Each PAIR is of the form
519
\(FUNCTION FILE).  FUNCTION is responsible to extract user names and host
520 521
names from FILE for completion.  The following predefined FUNCTIONs exists:

522 523 524 525 526 527 528
 * `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
529
 * `tramp-parse-etc-group'   for \"/etc/group\" like files.
530
 * `tramp-parse-netrc'       for \"~/.netrc\" like files.
Michael Albinus's avatar
Michael Albinus committed
531
 * `tramp-parse-putty'       for PuTTY registered sessions.
532

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

536 537 538
(defconst tramp-echo-mark-marker "_echo"
  "String marker to surround echoed commands.")

539 540 541 542 543 544
(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))
545 546 547 548 549
  "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
550 551 552
`tramp-echoed-echo-mark-regexp'.  Using `tramp-echo-mark-marker',
followed by an equal number of backspaces to erase them will
usually suffice.")
553

554 555 556
(defconst tramp-echoed-echo-mark-regexp
  (format "%s\\(\b\\( \b\\)?\\)\\{%d\\}"
	  tramp-echo-mark-marker tramp-echo-mark-marker-length)
557
  "Regexp which matches `tramp-echo-mark' as it gets echoed by \
558 559
the remote shell.")

560 561
(defcustom tramp-local-end-of-line
  (if (memq system-type '(windows-nt)) "\r\n" "\n")
562
  "String used for end of line in local processes."
563
  :version "24.1"
Michael Albinus's avatar
Michael Albinus committed
564
  :type 'string)
565

Kai Großjohann's avatar
Kai Großjohann committed
566
(defcustom tramp-rsh-end-of-line "\n"
567
  "String used for end of line in rsh connections.
Kai Großjohann's avatar
Kai Großjohann committed
568
I don't think this ever needs to be changed, so please tell me about it
Michael Albinus's avatar
Michael Albinus committed
569
if you need to change this."
Michael Albinus's avatar
Michael Albinus committed
570
  :type 'string)
Kai Großjohann's avatar
Kai Großjohann committed
571 572

(defcustom tramp-login-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
573
  ".*\\(user\\|login\\)\\( .*\\)?: *"
574
  "Regexp matching login-like prompts.
575 576 577
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
578
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
579

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

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

606
This variable is, by default, initialised from
Michael Albinus's avatar
Michael Albinus committed
607
`password-word-equivalents' when Tramp is loaded, and it is
608 609 610
usually more convenient to add new passphrases to that variable
instead of altering this variable.

Kai Großjohann's avatar
Kai Großjohann committed
611
The `sudo' program appears to insert a `^@' character into the prompt."
612
  :version "24.4"
Michael Albinus's avatar
Michael Albinus committed
613
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
614 615

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

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

Kai Großjohann's avatar
Kai Großjohann committed
652
(defcustom tramp-yn-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
653 654
  (concat
   (regexp-opt '("Store key in cache? (y/n)"
655 656
		 "Update cached key? (y/n, Return cancels connection)")
               t)
Michael Albinus's avatar
Michael Albinus committed
657
   "\\s-*")
Kai Großjohann's avatar
Kai Großjohann committed
658 659 660 661
  "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
662
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
663

664 665 666 667 668 669 670 671
(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
672 673 674 675 676 677 678 679 680
(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
681
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
682

683 684
;; 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
685
;; "-no-antispoof".  However, since we don't know which PuTTY
686 687 688
;; 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
689 690
  "Regular expression matching plink's anti-spoofing message.
The regexp should match at end of buffer."
691
  :version "27.1"
692 693
  :type 'regexp)

694 695 696 697 698 699 700 701 702
;; Powershell requires "ssh -t -t" for terminal emulation.  If it
;; doesn't fit, there is an error.
(defcustom tramp-no-job-control-regexp
  (regexp-quote "Thus no job control in this shell.")
  "Regular expression matching powershell's job control message.
The regexp should match at end of buffer."
  :version "28.1"
  :type 'regexp)

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

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

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

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

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

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

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

It can have the following values:

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

758 759
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
760
  :version "26.1"
Michael Albinus's avatar
Michael Albinus committed
761
  :package-version '(Tramp . "2.3.3")
Michael Albinus's avatar
Michael Albinus committed
762 763 764
  :type '(choice (const :tag "Default" default)
		 (const :tag "Ange-FTP" simplified)
		 (const :tag "XEmacs" separate))
Michael Albinus's avatar
Michael Albinus committed
765
  :require 'tramp
766 767
  :initialize #'custom-initialize-default
  :set #'tramp-set-syntax)
Michael Albinus's avatar
Michael Albinus committed
768 769 770 771 772 773 774

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

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

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

Gemini Lasswell's avatar
Gemini Lasswell committed
817
(defun tramp-lookup-syntax (alist)
818
  "Look up a syntax string in ALIST according to `tramp-compat-tramp-syntax'.
Gemini Lasswell's avatar
Gemini Lasswell committed
819 820 821 822 823 824 825 826 827 828
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.")

829
(defun tramp-build-prefix-format ()
830
  "Return `tramp-prefix-format' according to `tramp-syntax'."
Gemini Lasswell's avatar
Gemini Lasswell committed
831 832
  (tramp-lookup-syntax tramp-prefix-format-alist))

833
(defvar tramp-prefix-format nil ;Initialized when defining `tramp-syntax'!
834 835 836 837
  "String matching the very beginning of Tramp file names.
Used in `tramp-make-tramp-file-name'.")

(defun tramp-build-prefix-regexp ()
838
  "Return `tramp-prefix-regexp'."
839
  (concat "^" (regexp-quote tramp-prefix-format)))
840

841
(defvar tramp-prefix-regexp nil ;Initialized when defining `tramp-syntax'!
842
  "Regexp matching the very beginning of Tramp file names.
843
Should always start with \"^\". Derived from `tramp-prefix-format'.")
Gemini Lasswell's avatar
Gemini Lasswell committed
844 845

(defconst tramp-method-regexp-alist
Michael Albinus's avatar
Michael Albinus committed
846
  '((default    . "[[:alnum:]-]+")
Gemini Lasswell's avatar
Gemini Lasswell committed
847
    (simplified . "")
Michael Albinus's avatar
Michael Albinus committed
848
    (separate   . "[[:alnum:]-]*"))
Gemini Lasswell's avatar
Gemini Lasswell committed
849
  "Alist mapping Tramp syntax to regexps matching methods identifiers.")
850

851
(defun tramp-build-method-regexp ()
852
  "Return `tramp-method-regexp' according to `tramp-syntax'."
Gemini Lasswell's avatar
Gemini Lasswell committed
853 854
  (tramp-lookup-syntax tramp-method-regexp-alist))

855
(defvar tramp-method-regexp nil ;Initialized when defining `tramp-syntax'!