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.2-pre
11
;; Package-Requires: ((emacs "24.1"))
Kai Großjohann's avatar
Kai Großjohann committed
12 13 14

;; This file is part of GNU Emacs.

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

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

;;; 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.
;;
35
;; For more detailed instructions, please see the info file.
Kai Großjohann's avatar
Kai Großjohann committed
36 37 38
;;
;; Notes:
;; -----
39
;;
Kai Großjohann's avatar
Kai Großjohann committed
40 41
;; Also see the todo list at the bottom of this file.
;;
42
;; The current version of Tramp can be retrieved from the following URL:
43
;;            https://ftp.gnu.org/gnu/tramp/
Kai Großjohann's avatar
Kai Großjohann committed
44 45
;;
;; There's a mailing list for this, as well.  Its name is:
Michael Albinus's avatar
Michael Albinus committed
46 47
;;            tramp-devel@gnu.org
;; You can use the Web to subscribe, under the following URL:
Paul Eggert's avatar
Paul Eggert committed
48
;;            https://lists.gnu.org/mailman/listinfo/tramp-devel
Kai Großjohann's avatar
Kai Großjohann committed
49 50
;;
;; For the adventurous, the current development sources are available
51
;; via Git.  You can find instructions about this at the following URL:
52
;;            https://savannah.gnu.org/projects/tramp/
Kai Großjohann's avatar
Kai Großjohann committed
53 54 55 56 57
;;
;; Don't forget to put on your asbestos longjohns, first!

;;; Code:

58
(require 'tramp-compat)
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 netrc-parse "netrc")
Michael Albinus's avatar
Michael Albinus committed
64
(defvar auto-save-file-name-transforms)
Michael Albinus's avatar
Michael Albinus committed
65
(defvar eshell-path-env)
Michael Albinus's avatar
Michael Albinus committed
66 67
(defvar ls-lisp-use-insert-directory-program)
(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
(defcustom tramp-encoding-shell
Michael Albinus's avatar
Michael Albinus committed
138
  (or (tramp-compat-funcall 'w32-shell-name) "/bin/sh")
139
  "Use this program for encoding and decoding commands on the local host.
140 141 142 143 144
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
145
For encoding and decoding, commands like the following are executed:
146 147 148 149

    /bin/sh -c COMMAND < INPUT > OUTPUT

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

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

Kai Großjohann's avatar
Kai Großjohann committed
155 156 157 158
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
159
  :type '(file :must-match t))
Kai Großjohann's avatar
Kai Großjohann committed
160

Michael Albinus's avatar
Michael Albinus committed
161 162
(defcustom tramp-encoding-command-switch
  (if (tramp-compat-funcall 'w32-shell-dos-semantics) "/c" "-c")
163
  "Use this switch together with `tramp-encoding-shell' for local commands.
164 165
See the variable `tramp-encoding-shell' for more information."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
166
  :type 'string)
167

168
(defcustom tramp-encoding-command-interactive
Michael Albinus's avatar
Michael Albinus committed
169
  (unless (tramp-compat-funcall 'w32-shell-dos-semantics) "-i")
170
  "Use this switch together with `tramp-encoding-shell' for interactive shells.
171
See the variable `tramp-encoding-shell' for more information."
172
  :version "24.1"
173
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
174
  :type '(choice (const nil) string))
175

176
(defvar tramp-methods nil
177
  "Alist of methods for remote files.
Kai Großjohann's avatar
Kai Großjohann committed
178 179 180
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:
181

182
  * `tramp-remote-shell'
183 184 185 186 187 188 189
    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.
190

Michael Albinus's avatar
Michael Albinus committed
191 192 193 194 195 196
  * `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.
197

198 199
  * `tramp-remote-shell-args'
    For implementation of `shell-command', this specifies the
200
    arguments to let `tramp-remote-shell' run a single command.
201

202 203
  * `tramp-login-program'
    This specifies the name of the program to use for logging in to the
204 205
    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.
206

207
  * `tramp-login-args'
Kai Großjohann's avatar
Kai Großjohann committed
208
    This specifies the list of arguments to pass to the above
209
    mentioned program.  Please note that this is a list of list of arguments,
Kai Großjohann's avatar
Kai Großjohann committed
210
    that is, normally you don't want to put \"-a -b\" or \"-f foo\"
211 212 213 214 215 216 217 218 219
    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
220 221
    parameter of a program, if exists.  \"%c\" adds additional
    `tramp-ssh-controlmaster-options' options for the first hop.
222 223 224 225
    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.

226 227 228
  * `tramp-login-env'
     A list of environment variables and their values, which will
     be set when calling `tramp-login-program'.
229

230 231 232 233 234
  * `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.
235

236 237
  * `tramp-copy-program'
    This specifies the name of the program to use for remotely copying
238
    the file; this might be the absolute filename of scp or the name of
239
    a workalike program.  It is always applied on the local host.
240

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

245 246 247
  * `tramp-copy-env'
     A list of environment variables and their values, which will
     be set when calling `tramp-copy-program'.
248

249 250
  * `tramp-remote-copy-program'
    The listener program to be applied on remote side, if needed.
251

252 253 254 255 256
  * `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.
257

258 259 260
  * `tramp-copy-keep-date'
    This specifies whether the copying program when the preserves the
    timestamp of the original file.
261

262 263 264
  * `tramp-copy-keep-tmpfile'
    This specifies whether a temporary local file shall be kept
    for optimization reasons (useful for \"rsync\" methods).
265

266 267
  * `tramp-copy-recursive'
    Whether the operation copies directories recursively.
268

269
  * `tramp-default-port'
270
    The default port of a method.
271

272 273 274
  * `tramp-tmpdir'
    A directory on the remote host for temporary files.  If not
    specified, \"/tmp\" is taken as default.
275

276 277 278 279 280
  * `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.
281

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

287 288 289 290 291
  * `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.
292

293 294 295 296 297 298 299 300 301 302 303
  * `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.

304 305 306
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
307
remote side.  One way is using an additional scp-like program.  If you want
308
to do this, set `tramp-copy-program' in the method.
Kai Großjohann's avatar
Kai Großjohann committed
309 310

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

318
So, to summarize: if the method is an out-of-band method, then you
319
must specify `tramp-copy-program' and `tramp-copy-args'.  If it is an
320
inline method, then these two parameters should be nil.
Kai Großjohann's avatar
Kai Großjohann committed
321 322 323

Notes:

324 325
When using `su' or `sudo' the phrase \"open connection to a remote
host\" sounds strange, but it is used nevertheless, for consistency.
326 327 328 329
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
330

331
(defcustom tramp-default-method
Paul Eggert's avatar
Paul Eggert committed
332 333
  ;; An external copy method seems to be preferred, because it performs
  ;; much better for large files, and it hasn't too serious delays
334 335
  ;; for small files.  But it must be ensured that there aren't
  ;; permanent password queries.  Either a password agent like
336 337
  ;; "ssh-agent" or "Pageant" shall run, or the optional
  ;; password-cache.el or auth-sources.el packages shall be active for
338 339 340
  ;; 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.
341
  (cond
Glenn Morris's avatar
Glenn Morris committed
342 343 344
   ;; 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.
345
   ((and (eq system-type 'windows-nt) (executable-find "pscp")) "pscp")
346
   ;; There is an ssh installation.
347
   ((executable-find "scp") "scp")
348 349
   ;; Fallback.
   (t "ftp"))
350
  "Default method to use for transferring files.
351
See `tramp-methods' for possibilities.
352
Also see `tramp-default-method-alist'."
353
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
354
  :type 'string)
355

356
(defcustom tramp-default-method-alist nil
357
  "Default method to use for specific host/user pairs.
358 359 360 361 362 363 364 365 366 367 368
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
369 370
  :type '(repeat (list (choice :tag "Host regexp" regexp sexp)
		       (choice :tag "User regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
371
		       (choice :tag "Method name" string (const nil)))))
372

373 374 375
(defconst tramp-default-method-marker "-"
  "Marker for default method in remote file names.")

376
(defcustom tramp-default-user nil
377
  "Default user to use for transferring files.
378 379 380 381 382
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
383
  :type '(choice (const nil) string))
384

385
(defcustom tramp-default-user-alist nil
386
  "Default user to use for specific method/host pairs.
387 388
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
389
user.  METHOD and HOST are regular expressions or nil, which is
390 391 392 393 394 395
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
396 397
  :type '(repeat (list (choice :tag "Method regexp" regexp sexp)
		       (choice :tag "  Host regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
398
		       (choice :tag "    User name" string (const nil)))))
399

400
(defcustom tramp-default-host (system-name)
401
  "Default host to use for transferring files.
402 403
Useful for su and sudo methods mostly."
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
404
  :type 'string)
405

406 407 408 409
(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
410
host.  METHOD and USER are regular expressions or nil, which is
411 412 413 414 415 416
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
417
  :version "24.4"
418 419
  :type '(repeat (list (choice :tag "Method regexp" regexp sexp)
		       (choice :tag "  User regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
420
		       (choice :tag "    Host name" string (const nil)))))
421

422
(defcustom tramp-default-proxies-alist nil
423
  "Route to be followed for specific host/user pairs.
424 425 426
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
427 428 429 430 431 432 433 434 435 436 437
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'.
438 439 440 441

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."
442
  :group 'tramp
443 444
  :type '(repeat (list (choice :tag "Host regexp" regexp sexp)
		       (choice :tag "User regexp" regexp sexp)
Michael Albinus's avatar
Michael Albinus committed
445
		       (choice :tag " Proxy name" string (const nil)))))
446

Michael Albinus's avatar
Michael Albinus committed
447 448 449
(defcustom tramp-save-ad-hoc-proxies nil
  "Whether to save ad-hoc proxies persistently."
  :group 'tramp
Glenn Morris's avatar
Glenn Morris committed
450
  :version "24.3"
Michael Albinus's avatar
Michael Albinus committed
451
  :type 'boolean)
Michael Albinus's avatar
Michael Albinus committed
452

453 454 455 456 457 458 459 460
(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."
461
  :version "24.3"
462
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
463
  :type '(repeat (regexp :tag "Host regexp")))
464

465
(defcustom tramp-local-host-regexp
466
  (concat
467 468
   "\\`"
   (regexp-opt
469
    (list "localhost" "localhost6" (system-name) "127.0.0.1" "::1") t)
470
   "\\'")
471 472 473 474 475
  "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
476
		 (regexp :tag "Host regexp")))
477

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

485 486 487 488 489 490 491
 * `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
492
 * `tramp-parse-etc-group'   for \"/etc/group\" like files.
493
 * `tramp-parse-netrc'       for \"~/.netrc\" like files.
Michael Albinus's avatar
Michael Albinus committed
494
 * `tramp-parse-putty'       for PuTTY registered sessions.
495

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

499 500 501
(defconst tramp-echo-mark-marker "_echo"
  "String marker to surround echoed commands.")

502 503 504 505 506 507
(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))
508 509 510 511 512
  "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
513 514 515
`tramp-echoed-echo-mark-regexp'.  Using `tramp-echo-mark-marker',
followed by an equal number of backspaces to erase them will
usually suffice.")
516

517 518 519
(defconst tramp-echoed-echo-mark-regexp
  (format "%s\\(\b\\( \b\\)?\\)\\{%d\\}"
	  tramp-echo-mark-marker tramp-echo-mark-marker-length)
520 521 522
  "Regexp which matches `tramp-echo-mark' as it gets echoed by
the remote shell.")

523 524
(defcustom tramp-local-end-of-line
  (if (memq system-type '(windows-nt)) "\r\n" "\n")
525
  "String used for end of line in local processes."
526
  :version "24.1"
527
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
528
  :type 'string)
529

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

(defcustom tramp-login-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
538
  ".*\\(user\\|login\\)\\( .*\\)?: *"
539
  "Regexp matching login-like prompts.
540 541 542
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
543
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
544
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
545

Kai Großjohann's avatar
Kai Großjohann committed
546
(defcustom tramp-shell-prompt-pattern
547
  ;; Allow a prompt to start right after a ^M since it indeed would be
548 549
  ;; 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
550 551
  ;; Allow also [] style prompts.  They can appear only during
  ;; connection initialization; Tramp redefines the prompt afterwards.
552
  (concat "\\(?:^\\|\r\\)"
Michael Albinus's avatar
Michael Albinus committed
553
	  "[^]#$%>\n]*#?[]#$%>] *\\(\e\\[[0-9;]*[a-zA-Z] *\\)*")
Kai Großjohann's avatar
Kai Großjohann committed
554 555 556 557 558 559
  "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
560
variable is similar to the default value of `shell-prompt-pattern',
561 562 563 564
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
565
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
566
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
567

Kai Großjohann's avatar
Kai Großjohann committed
568
(defcustom tramp-password-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
569
  (format "^.*\\(%s\\).*:\^@? *"
Michael Albinus's avatar
Michael Albinus committed
570
	  ;; `password-word-equivalents' has been introduced with Emacs 24.4.
571 572
          (regexp-opt (or (bound-and-true-p password-word-equivalents)
                          '("password" "passphrase"))))
573
  "Regexp matching password-like prompts.
Kai Großjohann's avatar
Kai Großjohann committed
574
The regexp should match at end of buffer.
Kai Großjohann's avatar
Kai Großjohann committed
575 576

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

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

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

Kai Großjohann's avatar
Kai Großjohann committed
617
(defcustom tramp-yn-prompt-regexp
Michael Albinus's avatar
Michael Albinus committed
618 619
  (concat
   (regexp-opt '("Store key in cache? (y/n)"
620 621
		 "Update cached key? (y/n, Return cancels connection)")
               t)
Michael Albinus's avatar
Michael Albinus committed
622
   "\\s-*")
Kai Großjohann's avatar
Kai Großjohann committed
623 624 625 626 627
  "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
628
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
629 630 631 632 633 634 635 636 637 638 639

(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
640
  :type 'regexp)
Kai Großjohann's avatar
Kai Großjohann committed
641

Michael Albinus's avatar
Michael Albinus committed
642 643 644 645 646 647 648
(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
649
  :type 'regexp)
Michael Albinus's avatar
Michael Albinus committed
650

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

663
(defcustom tramp-process-alive-regexp
664
  ""
665
  "Regular expression indicating a process has finished.
666 667
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
668
The answer will be provided by `tramp-action-process-alive',
669
`tramp-action-out-of-band', which see."
670
  :group 'tramp
Michael Albinus's avatar
Michael Albinus committed
671
  :type 'regexp)
672

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

681 682 683 684
(defconst tramp-temp-buffer-name " *tramp temp*"
  "Buffer name for a temporary buffer.
It shall be used in combination with `generate-new-buffer-name'.")

685 686 687 688
(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)
689
(put 'tramp-temp-buffer-file-name 'permanent-local t)
690

Michael Albinus's avatar
Michael Albinus committed
691
(defcustom tramp-syntax 'default
692 693 694 695
  "Tramp filename syntax to be used.

It can have the following values:

Michael Albinus's avatar
Michael Albinus committed
696 697
  `default'    -- Default syntax
  `simplified' -- Ange-FTP like syntax
Michael Albinus's avatar
Michael Albinus committed
698 699
  `separate'   -- Syntax as defined for XEmacs originally

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

(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))
718
    (tramp-user-error "Wrong `tramp-syntax' %s" value))
Michael Albinus's avatar
Michael Albinus committed
719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744
  ;; 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
745

746
;; Initialize the Tramp syntax variables.  We want to override initial
Michael Albinus's avatar
Michael Albinus committed
747 748 749
;; 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.
750 751
(tramp--with-startup
  (tramp-set-syntax 'tramp-syntax (tramp-compat-tramp-syntax)))
752

Michael Albinus's avatar
Michael Albinus committed
753 754 755
(defun tramp-syntax-values ()
  "Return possible values of `tramp-syntax', a list"
  (let ((values (cdr (get 'tramp-syntax 'custom-type))))
756 757 758
    (setq values (mapcar #'last values)
	  values (mapcar #'car values))
    values))
Michael Albinus's avatar
Michael Albinus committed
759

Gemini Lasswell's avatar
Gemini Lasswell committed
760 761 762 763 764 765 766 767 768 769 770 771
(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.")

772
(defun tramp-build-prefix-format ()
Gemini Lasswell's avatar
Gemini Lasswell committed
773 774
  (tramp-lookup-syntax tramp-prefix-format-alist))

775
(defvar tramp-prefix-format nil ;Initialized when defining `tramp-syntax'!
776 777 778 779 780
  "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)))
781

782
(defvar tramp-prefix-regexp nil ;Initialized when defining `tramp-syntax'!
783
  "Regexp matching the very beginning of Tramp file names.
784
Should always start with \"^\". Derived from `tramp-prefix-format'.")
Gemini Lasswell's avatar
Gemini Lasswell committed
785 786 787 788 789 790

(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.")
791

792
(defun tramp-build-method-regexp ()
Gemini Lasswell's avatar
Gemini Lasswell committed
793 794
  (tramp-lookup-syntax tramp-method-regexp-alist))

795
(defvar tramp-method-regexp nil ;Initialized when defining `tramp-syntax'!
796 797 798
  "Regexp matching methods identifiers.
The `ftp' syntax does not support methods.")

Gemini Lasswell's avatar
Gemini Lasswell committed
799 800 801 802 803
(defconst tramp-postfix-method-format-alist
  '((default    . ":")
    (simplified . "")
    (separate   . "/"))
  "Alist mapping Tramp syntax to the delimiter after the method.")
804

805 806 807
(defun tramp-build-postfix-method-format ()
  (tramp-lookup-syntax tramp-postfix-method-format-alist))

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

813 814
(defun tramp-build-postfix-method-regexp ()
  (regexp-quote tramp-postfix-method-format))
815

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

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

823
(defconst tramp-prefix-domain-format "%"
824
  "String matching delimiter between user and domain names.")
825

826
(defconst tramp-prefix-domain-regexp (regexp-quote tramp-prefix-domain-format)
827
  "Regexp matching delimiter between user and domain names.
828 829
Derived from `tramp-prefix-domain-format'.")

830
(defconst tramp-domain-regexp "[a-zA-Z0-9_.-]+"
831
  "Regexp matching domain names.")
832 833 834 835 836

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

839
(defconst tramp-postfix-user-format "@"
840
  "String matching delimiter between user and host names.
841
Used in `tramp-make-tramp-file-name'.")
842

843
(defconst tramp-postfix-user-regexp (regexp-quote tramp-postfix-user-format)
844
  "Regexp matching delimiter between user and host names.
845 846
Derived from `tramp-postfix-user-format'.")

847
(defconst tramp-host-regexp "[a-zA-Z0-9_.%-]+"
848
  "Regexp matching host names.")
849

Gemini Lasswell's avatar
Gemini Lasswell committed
850 851 852 853 854 855
(defconst tramp-prefix-ipv6-format-alist
  '((default    . "[")
    (simplified . "[")
    (separate   . ""))
  "Alist mapping Tramp syntax to strings prefixing IPv6 addresses.")

856
(defun tramp-build-prefix-ipv6-format ()
Gemini Lasswell's avatar
Gemini Lasswell committed
857 858
  (tramp-lookup-syntax tramp-prefix-ipv6-format-alist))

859
(defvar tramp-prefix-ipv6-format nil ;Initialized when defining `tramp-syntax'!
860 861 862 863 864
  "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))
865

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

870 871 872
;; The following regexp is a bit sloppy.  But it shall serve our
;; purposes.  It covers also IPv4 mapped IPv6 addresses, like in
;; "::ffff:192.168.0.1".
873
(defconst tramp-ipv6-regexp "\\(?:\\(?:[a-zA-Z0-9]+\\)?:\\)+[a-zA-Z0-9.]+"
874
  "Regexp matching IPv6 addresses.")