Mercurial > emacs
annotate man/tramp.texi @ 46271:35153dd59211
*** empty log message ***
author | Juanma Barranquero <lekktu@gmail.com> |
---|---|
date | Tue, 09 Jul 2002 09:46:38 +0000 |
parents | d07b0e5f80b9 |
children | 49f06e689a20 |
rev | line source |
---|---|
45861 | 1 \input texinfo @c -*-texinfo-*- |
2 @c %**start of header | |
45864 | 3 @setfilename ../info/tramp |
45861 | 4 @settitle TRAMP User Manual |
5 @setchapternewpage odd | |
6 @c %**end of header | |
7 | |
8 @c This is *so* much nicer :) | |
9 @footnotestyle end | |
10 | |
11 @c Version values, for easy modification | |
12 @c NOTE: The 'UPDATED' value is updated by the 'time-stamp' function. | |
13 @c If you change it by hand, the modifications will not stay. | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
14 @set VERSION $Revision: 1.3 $ |
45864 | 15 @set UPDATED Monday, 17 June, 2002 |
45861 | 16 |
17 | |
18 @c Entries for @command{install-info} to use | |
19 @direntry | |
20 * TRAMP: (tramp). Transparent Remote Access, Multiple Protocol | |
21 Emacs remote file access via rsh and rcp. | |
22 @end direntry | |
23 | |
24 @c Macro to make formatting of the tramp program name consistent. | |
25 @macro tramp | |
26 @sc{tramp} | |
27 @end macro | |
28 | |
29 @c Copying permissions, et al | |
30 @ifinfo | |
31 This file documents @tramp{}, a remote file editing package for Emacs and | |
32 XEmacs. | |
33 | |
34 Copyright @copyright{} 1999, 2000 Free Software Foundation, Inc. | |
35 | |
36 Permission is granted to make and distribute verbatim copies of this | |
37 manual provided the copyright notice and this permission notice are | |
38 preserved on all copies. | |
39 | |
40 @ignore | |
41 Permission is granted to process this file through TeX and print the | |
42 results, provided the printed document carries a copying permission | |
43 notice identical to this one except for the removal of this paragraph | |
44 (this paragraph not being relevant to the printed manual). | |
45 | |
46 @end ignore | |
47 Permission is granted to copy and distribute modified versions of this | |
48 manual under the conditions for verbatim copying, provided also that the | |
49 sections entitled ``Copying'' and ``GNU General Public License'' are | |
50 included exactly as in the original, and provided that the entire | |
51 resulting derived work is distributed under the terms of a permission | |
52 notice identical to this one. | |
53 | |
54 Permission is granted to copy and distribute translations of this manual | |
55 into another language, under the above conditions for modified versions, | |
56 except that this permission notice may be stated in a translation | |
57 approved by the Free Software Foundation. | |
58 @end ifinfo | |
59 | |
60 @tex | |
61 | |
62 @titlepage | |
63 @title @tramp{} User Manual | |
64 @subtitle Last updated @value{UPDATED} | |
65 | |
66 @author by Daniel Pittman | |
67 @author based on documentation by Kai Gro@ss{}johann | |
68 @page | |
69 | |
70 @vskip 0pt plus 1filll | |
71 Permission is granted to make and distribute verbatim copies of this | |
72 manual provided the copyright notice and this permission notice are | |
73 preserved on all copies. | |
74 | |
75 Permission is granted to copy and distribute modified versions of this | |
76 manual under the conditions for verbatim copying, provided also that the | |
77 sections entitled ``Copying'' and ``GNU General Public License'' are | |
78 included exactly as in the original, and provided that the entire | |
79 resulting derived work is distributed under the terms of a permission | |
80 notice identical to this one. | |
81 | |
82 Permission is granted to copy and distribute translations of this manual | |
83 into another language, under the above conditions for modified versions, | |
84 except that this permission notice may be stated in a translation | |
85 approved by the Free Software Foundation. | |
86 | |
87 @end titlepage | |
88 @page | |
89 | |
90 @end tex | |
91 | |
92 @ifnottex | |
93 @node Top, Copying, (dir), (dir) | |
94 @top @tramp{} User Manual | |
95 | |
96 @tramp{} stands for `Transparent Remote (file) Access, Multiple | |
97 Protocol'. This package provides remote file editing, similar to | |
98 @cite{ange-ftp} and @cite{EFS}. | |
99 | |
100 The difference is that ange-ftp uses FTP to transfer files between the | |
101 local and the remote host, whereas @tramp{} uses a combination of | |
102 @command{rsh} and @command{rcp} or other work-alike programs, such as | |
103 @command{ssh}/@command{scp}. | |
104 | |
105 This is version @value{VERSION} of the @tramp{} manual, last updated on | |
106 @value{UPDATED}. | |
107 | |
108 You can find the latest version of this document on the web at | |
109 @uref{http://www.freesoftware.fsf.org/tramp/}. | |
110 | |
111 @ifhtml | |
112 This manual is also available as a @uref{tramp_ja.html, Japanese | |
113 translation}. | |
114 | |
115 The latest release of @tramp{} is available for | |
116 @uref{http://savannah.gnu.org/download/tramp/, | |
117 download}, or you may see @ref{Obtaining @tramp{}} for more details, | |
118 including the CVS server details. | |
119 | |
120 @tramp{} also has a @uref{https://savannah.gnu.org/projects/tramp/, | |
121 Savannah Project Page}. | |
122 @end ifhtml | |
123 | |
124 There is a mailing list for @tramp{}, available at | |
125 @email{tramp-devel@@mail.freesoftware.fsf.org}, and archived at | |
126 @uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/} as | |
127 well as the usual Savannah archives. | |
128 | |
129 @end ifnottex | |
130 | |
131 @menu | |
132 * Copying:: @tramp{} Copying conditions. | |
133 * Overview:: What @tramp{} can and cannot do. | |
134 | |
135 For the end user: | |
136 * Obtaining @tramp{}:: How to obtain @tramp{}. | |
137 * History:: History of @tramp{} | |
138 * Installation:: Installing @tramp{} with your (X)Emacs. | |
139 * Configuration:: Configuring @tramp{} for use. | |
140 * Usage:: An overview of the operation of @tramp{}. | |
141 * Bug Reports:: Reporting Bugs and Problems | |
142 * Frequently Asked Questions:: Questions and answers from the mailing list. | |
143 | |
144 For the developer: | |
145 * Version Control:: The inner workings of remote version control. | |
146 * Files directories and paths:: How file names, directories and paths are mangled and managed. | |
147 * Issues:: | |
148 | |
149 @detailmenu | |
150 --- The Detailed Node Listing --- | |
151 | |
152 Configuring @tramp{} for use | |
153 | |
154 * Connection types:: Types of connections made to remote machines. | |
155 * Inline methods:: Inline methods. | |
156 * External transfer methods:: External transfer methods. | |
157 * Multi-hop Methods:: Connecting to a remote host using multiple hops. | |
158 * Default Method:: Selecting a default method. | |
159 * Customizing Methods:: Using Non-Standard Methods. | |
160 * Remote Programs:: How @tramp{} finds and uses programs on the remote machine. | |
161 * Remote shell setup:: | |
162 | |
163 Using @tramp | |
164 | |
165 * Filename Syntax:: @tramp{} filename conventions. | |
166 * Multi-hop filename syntax:: Multi-hop filename conventions | |
167 * Dired:: Dired and filename completion. | |
168 | |
169 The inner workings of remote version control | |
170 | |
171 * Version Controlled Files:: Determining if a file is under version control. | |
172 * Remote Commands:: Executing the version control commands on the remote machine. | |
173 * Changed workfiles:: Detecting if the working file has changed. | |
174 * Checking out files:: Bringing the workfile out of the repository. | |
175 * Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere | |
176 | |
177 Things related to Version Control that don't fit elsewhere | |
178 | |
179 * Remote File Ownership:: How VC determines who owns a workfile. | |
180 * Back-end Versions:: How VC determines what release your RCS is. | |
181 | |
182 How file names, directories and paths are mangled and managed. | |
183 | |
184 * Path deconstruction:: Breaking a path into its components. | |
185 | |
186 @end detailmenu | |
187 @end menu | |
188 | |
189 @node Copying | |
190 @chapter @tramp{} Copying conditions | |
191 | |
192 Copyright (C) 1998, 1999, 2000 Free Software Foundation, Inc. | |
193 | |
194 tramp.el is free software; you can redistribute it and/or modify it under | |
195 the terms of the GNU General Public License as published by the Free | |
196 Software Foundation; either version 2, or (at your option) any later | |
197 version. | |
198 | |
199 tramp.el is distributed in the hope that it will be useful, but WITHOUT | |
200 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
201 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for | |
202 more details. | |
203 | |
204 You should have received a copy of the GNU General Public License along | |
205 with GNU Emacs; see the file COPYING. If not, write to the Free Software | |
206 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, | |
207 USA. | |
208 | |
209 | |
210 @node Overview | |
211 @chapter An overview of @tramp | |
212 | |
213 After the installation of @tramp{} into your Emacs, you will be able to | |
214 access files on remote machines as though they were local. Access to the | |
215 remote file system for editing files, version control, and | |
216 @command{dired} are transparently enabled. | |
217 | |
218 Your access to the remote machine can be with the @command{rsh}, | |
219 @command{rlogin}, @command{telnet} programs or with any similar | |
220 connection method. This connection must pass ASCII successfully to be | |
221 usable but need not be 8-bit clean. | |
222 | |
223 The package provides support for @command{ssh} connections out of the | |
224 box, one of the more common uses of the package. This allows relatively | |
225 secure access to machines, especially if @command{ftp} access is | |
226 disabled. | |
227 | |
228 The majority of activity carried out by @tramp{} requires only that the | |
229 remote login is possible and is carried out at the terminal. In order to | |
230 access remote files @tramp{} needs to transfer their content to the local | |
231 machine temporarily. | |
232 | |
233 @tramp{} can transfer files between the machines in a variety of ways. The | |
234 details are easy to select, depending on your needs and the machines in | |
235 question. | |
236 | |
237 The fastest transfer methods rely on a remote file transfer package such | |
238 as @command{rcp}, @command{scp} or @command{rsync}. The use of these | |
239 methods is only possible if the file copy command does not ask for a | |
240 password for the remote machine. | |
241 | |
242 If the remote copy methods are not suitable for you, @tramp{} also | |
243 supports the use of encoded transfers directly through the shell. This | |
244 requires that the @command{mimencode} or @command{uuencode} tools are | |
245 available on the remote machine. | |
246 | |
247 Within these limitations, @tramp{} is quite powerful. It is worth noting | |
248 that, as of the time of writing, it is far from a polished end-user | |
249 product. For a while yet you should expect to run into rough edges and | |
250 problems with the code now and then. | |
251 | |
252 It is finished enough that the developers use it for day to day work but | |
253 the installation and setup can be a little difficult to master, as can | |
254 the terminology. | |
255 | |
256 @tramp{} is still under active development and any problems you encounter, | |
257 trivial or major, should be reported to the @tramp{} developers. | |
258 @xref{Bug Reports}. | |
259 | |
260 | |
261 @subsubheading Behind the scenes | |
262 | |
263 This section tries to explain what goes on behind the scenes when you | |
264 access a remote file through @tramp{}. | |
265 | |
266 Suppose you type @kbd{C-x C-f} and enter part of an @tramp{} file name, | |
267 then hit @kbd{@key{TAB}} for completion. Suppose further that this is | |
268 the first time that @tramp{} is invoked for the host in question. Here's | |
269 what happens: | |
270 | |
271 @itemize | |
272 @item | |
273 @tramp{} discovers that it needs a connection to the host. So it invokes | |
274 @command{telnet HOST} or @command{rsh HOST -l USER} or a similar tool to | |
275 connect to the remote host. Communication with this process happens | |
276 through an Emacs buffer, that is, the output from the remote end goes | |
277 into a buffer. | |
278 | |
279 @item | |
280 The remote host may prompt for a login name (for @command{telnet}). The | |
281 login name is given in the file name, so @tramp{} sends the login name and | |
282 a newline. | |
283 | |
284 @item | |
285 The remote host may prompt for a password or pass phrase (for | |
286 @command{rsh} or for @command{telnet} after sending the login name). | |
287 @tramp{} displays the prompt in the minibuffer, asking you for the | |
288 password or pass phrase. | |
289 | |
290 You enter the password or pass phrase. @tramp{} sends it to the remote | |
291 host, followed by a newline. | |
292 | |
293 @item | |
294 @tramp{} now waits for the shell prompt or for a message that the login | |
295 failed. | |
296 | |
297 If @tramp{} sees neither of them after a certain period of time (a minute, | |
298 say), then it issues an error message saying that it couldn't find the | |
299 remote shell prompt and shows you what the remote host has sent. | |
300 | |
301 If @tramp{} sees a `login failed' message, it tells you so, aborts the | |
302 login attempt and allows you to try again. | |
303 | |
304 @item | |
305 Suppose that the login was successful and @tramp{} sees the shell prompt | |
306 from the remote host. Now @tramp{} invokes @command{/bin/sh} because | |
307 Bourne shells and C shells have different command | |
308 syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login | |
309 shell doesn't recognize @command{exec /bin/sh} as a valid command. | |
310 Maybe you use the Scheme shell @command{scsh}@dots{}} | |
311 | |
312 After the Bourne shell has come up, @tramp{} sends a few commands to | |
313 ensure a good working environment. It turns off echoing, it sets the | |
314 shell prompt, and a few other things. | |
315 | |
316 @item | |
317 Now the remote shell is up and it good working order. Remember, what | |
318 was supposed to happen is that @tramp{} tries to find out what files exist | |
319 on the remote host so that it can do filename completion. | |
320 | |
321 So, @tramp{} basically issues @command{cd} and @command{ls} commands and | |
322 also sometimes @command{echo} with globbing. Another command that is | |
323 often used is @command{test} to find out whether a file is writable or a | |
324 directory or the like. The output of each command is parsed for the | |
325 necessary operation. | |
326 | |
327 @item | |
328 Suppose you are finished with filename completion, have entered @kbd{C-x | |
329 C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to | |
330 transfer the file contents from the remote host to the local host so | |
331 that you can edit them. | |
332 | |
333 See above for an explanation of how @tramp{} transfers the file contents. | |
334 | |
335 For inline transfers, @tramp{} issues a command like @command{mimencode -b | |
336 /path/to/remote/file}, waits until the output has accumulated in the | |
337 buffer that's used for communication, then decodes that output to | |
338 produce the file contents. | |
339 | |
340 For out-of-band transfers, @tramp{} issues a command like @command{rcp | |
341 user@@host:/path/to/remote/file /tmp/tramp.4711} and then reads the local | |
342 temporary file @file{/tmp/tramp.4711} into a buffer and deletes the | |
343 temporary file. | |
344 | |
345 @item | |
346 You now edit the buffer contents, blithely unaware of what has happened | |
347 behind the scenes. (Unless you have read this section, that is.) When | |
348 you are finished, you type @kbd{C-x C-s} to save the buffer. | |
349 | |
350 @item | |
351 Again, @tramp{} transfers the file contents to the remote host either | |
352 inline or out-of-band. This is the reverse of what happens when reading | |
353 the file. | |
354 | |
355 @end itemize | |
356 | |
357 I hope this has provided you with a basic overview of what happens | |
358 behind the scenes when you open a file with @tramp{}. | |
359 | |
360 | |
361 @c For the end user | |
362 @node Obtaining @tramp{} | |
363 @chapter Obtaining @tramp{}. | |
364 | |
365 @tramp{} is freely available on the Internet and the latest release may be | |
366 downloaded from | |
367 @uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/tramp.tar.gz}. This | |
368 release includes the full documentation and code for @tramp{}, suitable | |
369 for installation. | |
370 | |
371 For the especially brave, @tramp{} is available from CVS. The CVS version | |
372 is the latest version of the code and may contain incomplete features or | |
373 new issues. Use these versions at your own risk. | |
374 | |
375 Instructions for obtaining the latest development version of @tramp{} | |
376 from CVS can be found by going to the Savannah project page at | |
377 @uref{http://savannah.gnu.org/projects/tramp/} and then clicking on the | |
378 CVS link in the navigation bar at the top. Or follow the example | |
379 session below: | |
380 | |
381 @example | |
382 ] @strong{cd ~/lisp} | |
383 ] @strong{cvs -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp login} | |
384 | |
385 (Logging in to anoncvs@@subversions.gnu.org) | |
386 CVS password: @strong{(just hit RET here)} | |
387 @dots{} | |
388 | |
389 ] @strong{cvs -z3 -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp co tramp} | |
390 @end example | |
391 | |
392 You should now have a directory @file{~/lisp/tramp} containing the latest | |
393 version of @tramp{}. You can fetch the latest updates from the repository | |
394 by issuing the command: | |
395 | |
396 @example | |
397 ] @strong{cd ~/lisp/tramp} | |
398 ] @strong{cvs update -d} | |
399 @end example | |
400 | |
401 | |
402 @node History | |
403 @chapter History of @tramp{} | |
404 | |
405 Development was started end of November 1998. The package was called | |
406 `rssh.el', back then. It only provided one method to access a file, | |
407 using @command{ssh} to log in to a remote host and using @command{scp} | |
408 to transfer the file contents. After a while, the name was changed to | |
409 `rcp.el', and now it's @tramp{}. Along the way, many more methods for | |
410 getting a remote shell and for transferring the file contents were | |
411 added. Support for VC was added. | |
412 | |
413 The most recent addition of a major feature was the multi-hop methods | |
414 added in April 2000. | |
415 | |
416 | |
417 @node Installation | |
418 @chapter Installing @tramp{} into Emacs or XEmacs | |
419 | |
420 Installing @tramp{} into your Emacs or XEmacs is a relatively easy | |
421 process, at least compared to rebuilding your machine from scratch. ;) | |
422 | |
423 Seriously though, the installation should be a fairly simple matter. | |
424 | |
425 The easiest way to proceed is as follows: | |
426 | |
427 @itemize | |
428 @item | |
429 Choose a directory, say @file{~/emacs/}. Change into that directory and | |
430 unpack the tarball. This will give you a directory | |
431 @file{~/emacs/tramp/} which contains subdirectories @file{lisp} for the | |
432 Lisp code and @file{texi} for the documentation. | |
433 | |
434 @item | |
435 Optionally byte-compile all files in the Lisp directory, | |
436 @file{~/emacs/tramp/lisp/}, by issuing a command like the following from | |
437 the top level directory @file{~/emacs/tramp/}: | |
438 @example | |
439 make EMACS=emacs all # for Emacs users | |
440 make EMACS=xemacs all # for XEmacs users | |
441 @end example | |
442 | |
443 @item | |
444 NOTE: | |
445 @example | |
446 If you run into problems running the example @command{make} | |
447 commands, don't dispare. You can still byte compile the | |
448 @file{*.el} files by opening emacs in @command{dired} | |
449 (@command{C-x d}) mode, at @file{~/tramp/lisp}. Mark the lisp | |
450 files with @command{m}, then press @command{B} to byte compile | |
451 your selections. | |
452 | |
453 Something similar can be done to create the info manual. | |
454 Just cd to @file{~/emacs/tramp/texi} and load the @file{tramp.texi} | |
455 file in emacs. Then press @command{M-x makeinfo-buffer <RET>} | |
456 to generate @file{tramp.info}. | |
457 @end example | |
458 | |
459 @item | |
460 Tell Emacs about the new Lisp directory and the @tramp{} package | |
461 with the following lines in @file{~/.emacs}: | |
462 @lisp | |
463 (add-to-list 'load-path "~/emacs/tramp/lisp/") | |
464 (require 'tramp) | |
465 @end lisp | |
466 | |
467 @item | |
468 To be able to read the Info documentation, create a file | |
469 @file{~/emacs/tramp/texi/dir} using for example the | |
470 @command{install-info} command, and add the directory to the search | |
471 path for Info. | |
472 | |
473 @item | |
474 NOTE: | |
475 @example | |
476 On systems using `gnu' @command{install-info}, the | |
477 @command{install-info} syntax is very direct and simple. One can | |
478 cd to @file{~/emacs/tramp/texi} and type: | |
479 @command{install-info tramp.info dir} | |
480 and a @file{dir} file will be created with the @tramp{} | |
481 entry. The info reader will know how to interpret it, but must | |
482 be told where to find it (see below). If you want anything fancier | |
483 you'll need to look through @command{man install-info}. | |
484 | |
485 Debian gnu/linux doesn't default to `gnu' @command{install-info} and | |
486 uses its own version. This version does not create a @file{dir} file | |
487 for you from scratch. You must provide a skeleton dir file it | |
488 recognizes. One can be found in a default install at | |
489 @file{/usr/info/dir}. Copy the top of this file down to the first | |
490 occurrence of `* Menu' including that line plus one more blank line, | |
491 to your working directory @file{texi/dir}, or use the sample provided | |
492 in the @file{texi} directroy of this distribution. See | |
493 @file{texi/dir_sample} | |
494 | |
495 Once a @file{dir} file is in place, this command will make the entry. | |
496 install-info --infodir=. tramp.info | |
497 If you want it in a specific category | |
498 (see @command{man install-info} for further details) | |
499 @end example | |
500 | |
501 If the environment variable @env{INFOPATH} is set, add the directory | |
502 @file{~/emacs/tramp/texi/} to it. Else, add the directory to | |
503 @code{Info-default-directory-list}, as follows: | |
504 @lisp | |
505 (add-to-list 'Info-default-directory-list "~/emacs/tramp/texi/") | |
506 @end lisp | |
507 XEmacs 21 users should use @code{Info-directory-list} rather than | |
508 @code{Info-default-directory-list}. | |
509 | |
510 @end itemize | |
511 | |
512 | |
513 For XEmacs users, the package @command{fsf-compat} must be installed. | |
514 For details on package installation, see @ref{Packages, , ,xemacs}. | |
515 @ifhtml | |
516 (If the previous link doesn't work, try the XEmacs documentation at | |
517 @uref{http://www.xemacs.org/Documentation/packageGuide.html,the XEmacs | |
518 site}.) | |
519 @end ifhtml | |
520 | |
521 @node Configuration | |
522 @chapter Configuring @tramp{} for use | |
523 | |
524 @tramp{} is (normally) fully functional when it is initially | |
525 installed. It is initially configured to use the @command{rsh} and | |
526 @command{rcp} programs to connect to the remote host. | |
527 | |
528 On some hosts, there are problems with opening a connection. These are | |
529 related to the behavior of the remote shell. See @xref{Remote shell | |
530 setup}, for details on this. | |
531 | |
532 If you do not wish to use these commands to connect to the remote host, | |
533 you should change the default connection and transfer method that @tramp | |
534 uses. There are several different methods that @tramp{} can use to | |
535 connect to remote machines and transfer files (@pxref{Connection types}). | |
536 | |
537 | |
538 @menu | |
539 * Connection types:: Types of connections made to remote machines. | |
540 * Inline methods:: Inline methods. | |
541 * External transfer methods:: External transfer methods. | |
542 * Multi-hop Methods:: Connecting to a remote host using multiple hops. | |
543 * Default Method:: Selecting a default method. | |
544 * Customizing Methods:: Using Non-Standard Methods. | |
545 * Remote Programs:: How @tramp{} finds and uses programs on the remote machine. | |
546 * Remote shell setup:: Remote shell setup hints. | |
547 * Windows setup hints:: Issues with Cygwin ssh. | |
548 @end menu | |
549 | |
550 | |
551 @node Connection types | |
552 @section Types of connections made to remote machines. | |
553 | |
554 There are two basic types of transfer methods, each with its own | |
555 advantages and limitations. Both types of connection make use of a | |
556 remote shell access program such as @command{rsh}, @command{ssh} or | |
557 @command{telnet} to connect to the remote machine. | |
558 | |
559 This connection is used to perform many of the operations that @tramp | |
560 requires to make the remote file system transparently accessible from | |
561 the local machine. It is only when visiting files that the methods | |
562 differ. | |
563 | |
564 Loading or saving a remote file requires that the content of the file be | |
565 transfered between the two machines. The content of the file can be | |
566 transfered over the same connection used to log in to the remote machine | |
567 or the file can be transfered through another connection using a remote | |
568 copy program such as @command{rcp}, @command{scp} or @command{rsync}. | |
569 The former are called @dfn{inline methods}, the latter are called | |
570 @dfn{external transfer methods}. | |
571 | |
572 The performance of the external transfer methods is generally better | |
573 than that of the inline methods. This is caused by the need to encode | |
574 and decode the data when transferring inline. | |
575 | |
576 The one exception to this rule are the @command{scp} based transfer | |
577 methods. While these methods do see better performance when actually | |
578 transferring files, the overhead of the cryptographic negotiation at | |
579 startup may drown out the improvement in file transfer times. | |
580 | |
581 External transfer methods do require that the remote copy command is not | |
582 interactive --- that is, the command does not prompt you for a password. | |
583 If you cannot perform remote copies without a password, you will need to | |
584 use an inline transfer method to work with @tramp{}. | |
585 | |
586 A variant of the inline methods are the @dfn{multi-hop methods}. | |
587 These methods allow you to connect a remote host using a number `hops', | |
588 each of which connects to a different host. This is useful if you are | |
589 in a secured network where you need to go through a bastion host to | |
590 connect to the outside world. | |
591 | |
592 | |
593 @node Inline methods | |
594 @section Inline methods | |
595 | |
596 The inline methods in @tramp{} are quite powerful and can work in | |
597 situations where you cannot use an external transfer program to connect. | |
598 Inline methods are the only methods that work when connecting to the | |
599 remote machine via telnet. (There are also strange inline methods which | |
600 allow you to transfer files between @emph{user identities} rather than | |
601 hosts, see below.) | |
602 | |
603 These methods depend on the existence of a suitable encoding and | |
604 decoding command on remote machine. Locally, @tramp{} may be able to use | |
605 features of Emacs to decode and encode the files or it may require | |
606 access to external commands to perform that task. | |
607 | |
608 @tramp{} supports the use of @command{uuencode} to transfer files. This is | |
609 @emph{not} recommended. The @command{uuencode} and @command{uudecode} | |
610 commands are not well standardized and may not function correctly or at | |
611 all on some machines, notably AIX and IRIX. These systems do not work | |
612 with @command{uuencode} at all. (But do see the note about AIX in the | |
613 documentation for @var{tramp-methods}.) | |
614 | |
615 In summary, if possible use the @command{mimencode} methods to transfer | |
616 the data base64 encoded. This has the advantage of using a built-in | |
617 command in every modern Emacs, improving performance. | |
618 | |
619 @itemize | |
620 @item @option{rm} --- @command{rsh} with @command{mimencode} | |
621 | |
622 Connect to the remote host with @command{rsh} and use base64 encoding to | |
623 transfer files between the machines. | |
624 | |
625 This requires the @command{mimencode} command that is part of the | |
626 @command{metamail} packages. This may not be installed on all remote | |
627 machines. | |
628 | |
629 | |
630 @item @option{sm} --- @command{ssh} with @command{mimencode} | |
631 | |
632 Connect to the remote host with @command{ssh} and use base64 encoding to | |
633 transfer files between the machines. | |
634 | |
635 This is identical to the previous option except that the @command{ssh} | |
636 package is used, making the connection more secure. | |
637 | |
638 There are also two variants, @option{sm1} and @option{sm2} that use the | |
639 @command{ssh1} and @command{ssh2} commands explicitly. If you don't know | |
640 what these are, you do not need these options. | |
641 | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
642 All the methods based on @command{ssh} have an additional kludgy |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
643 feature: you can specify a host name which looks like @file{host#42} |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
644 (the real host name, then a hash sign, then a port number). This |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
645 means to connect to the given host but to also pass @code{-p 42} as |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
646 arguments to the @command{ssh} command. |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
647 |
45861 | 648 |
649 @item @option{tm} --- @command{telnet} with @command{mimencode} | |
650 | |
651 Connect to the remote host with @command{telnet} and use base64 encoding | |
652 to transfer files between the machines. | |
653 | |
654 This requires the @command{mimencode} command that is part of the | |
655 @command{metamail} packages. | |
656 | |
657 | |
658 @item @option{ru} --- @command{rsh} with @command{uuencode} | |
659 | |
660 Connect to the remote host with @command{rsh} and use the | |
661 @command{uuencode} and @command{uudecode} commands to transfer files | |
662 between the machines. | |
663 | |
664 | |
665 @item @option{su} --- @command{ssh} with @command{uuencode} | |
666 | |
667 Connect to the remote host with @command{ssh} and use the | |
668 @command{uuencode} and @command{uudecode} commands to transfer files | |
669 between the machines. | |
670 | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
671 As with the @command{ssh} and base64 option (@option{sm}) above, this |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
672 provides the @option{su1} and @option{su2} methods to explicitly |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
673 select an ssh version. |
45861 | 674 |
675 Note that this method does not invoke the @command{su} program, see | |
676 below for methods which use that. | |
677 | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
678 This supports the @command{-p} kludge. |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
679 |
45861 | 680 |
681 @item @option{tu} --- @command{telnet} with @command{uuencode} | |
682 | |
683 Connect to the remote host with @command{telnet} and use the | |
684 @command{uuencode} and @command{uudecode} commands to transfer files | |
685 between the machines. | |
686 | |
687 | |
688 @item @option{sum} --- @command{su} with @command{mimencode} | |
689 | |
690 This method does not connect to a remote host at all, rather it uses the | |
691 @command{su} program to allow you to edit files as another user. Uses | |
692 base64 encoding to transfer the file contents. | |
693 | |
694 | |
695 @item @option{suu} --- @command{su} with @command{uuencode} | |
696 | |
697 Like @option{sum}, this uses the @command{su} program to allow you to | |
698 edit files on the local host as another user. Uses @command{uuencode} | |
699 and @command{uudecode} to transfer the file contents. | |
700 | |
701 | |
702 @item @option{sudm} --- @command{sudo} with @command{mimencode} | |
703 | |
704 This is similar to the @option{sum} method, but it uses @command{sudo} | |
705 rather than @command{su} to become a different user. | |
706 | |
707 Note that @command{sudo} must be configured to allow you to start a | |
708 shell as the user. It would be nice if it was sufficient if | |
709 @command{ls} and @command{mimencode} were allowed, but that is not easy | |
710 to implement, so I haven't got around to it, yet. | |
711 | |
712 | |
713 @item @option{sudu} --- @command{sudo} with @command{uuencode} | |
714 | |
715 This is similar to the @option{suu} method, but it uses @command{sudo} | |
716 rather than @command{su} to become a different user. | |
717 | |
718 | |
719 @item @option{smx} --- @command{ssh} with @command{mimencode} | |
720 | |
721 As you expect, this is similar to @option{sm}, only a little | |
722 different. Whereas @option{sm} opens a normal interactive shell on | |
723 the remote host, this option uses @command{ssh -t -t HOST -l USER | |
724 /bin/sh} tp open a connection. This is useful for users where the | |
725 normal login shell is set up to ask them a number of questions when | |
726 logging in. This procedure avoids these questions, and just gives | |
727 @tramp{} a more-or-less `standard' login shell to work with. | |
728 | |
729 This is also useful for Windows users where @command{ssh}, when | |
730 invoked from an Emacs buffer, tells them that it is not allocating a | |
731 pseudo tty. When this happens, the login shell is wont to not print | |
732 any shell prompt, which confuses @tramp{} mightily. | |
733 | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
734 This supports the @command{-p} kludge. |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
735 |
45861 | 736 |
737 @item @option{km} --- @command{krlogin} with @command{mimencode} | |
738 | |
739 This method is also similar to @option{sm}. It only uses the | |
740 @command{krlogin -x} command to log in to the remote host. | |
741 | |
742 | |
743 @item @option{plinku} --- @command{plink} with @command{uuencode} | |
744 | |
745 This method is mostly interesting for Windows users using the PuTTY | |
746 implementation of SSH. It uses @command{plink -ssh} to log in to the | |
747 remote host. | |
748 | |
749 CCC: Do we have to connect to the remote host once from the command | |
750 line to accept the SSH key? Maybe this can be made automatic? | |
751 | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
752 CCC: Does @command{plink} support the @command{-p} option? Tramp |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
753 will support that, anyway. |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
754 |
45861 | 755 @item @option{plinkm} --- @command{plink} with @command{mimencode} |
756 | |
757 Like @option{plinku}, but uses base64 encoding instead of uu encoding. | |
758 | |
759 @end itemize | |
760 | |
761 | |
762 | |
763 @node External transfer methods | |
764 @section External transfer methods | |
765 | |
766 The external transfer methods operate through multiple channels, using | |
767 the remote shell connection for many actions while delegating file | |
768 transfers to an external transfer utility. | |
769 | |
770 This saves the overhead of encoding and decoding that multiplexing the | |
771 transfer through the one connection has with the inline methods. | |
772 | |
773 If you want to use an external transfer method you @emph{must} be able | |
774 to execute the transfer utility to copy files to and from the remote | |
775 machine without any interaction. | |
776 | |
777 This means that you will need to use @command{ssh-agent} if you use the | |
778 @command{scp} program for transfers, or maybe your version of | |
779 @command{scp} accepts a password on the command line.@footnote{PuTTY's | |
780 @command{pscp} allows you to specify the password on the command line.} | |
781 If you use @command{rsync} via @command{ssh} then the same rule must | |
782 apply to that connection. | |
783 | |
784 If you cannot get @command{scp} to run without asking for a password but | |
785 would still like to use @command{ssh} to secure your connection, have a | |
786 look at the @command{ssh} based inline methods. | |
787 | |
788 | |
789 @itemize | |
790 @item @option{rcp} --- @command{rsh} and @command{rcp} | |
791 | |
792 This method uses the @command{rsh} and @command{rcp} commands to connect | |
793 to the remote machine and transfer files. This is probably the fastest | |
794 connection method available. | |
795 | |
796 | |
797 @item @option{scp} --- @command{ssh} and @command{scp} | |
798 | |
799 Using @command{ssh} to connect to the remote host and @command{scp} to | |
800 transfer files between the machines is the best method for securely | |
801 connecting to a remote machine and accessing files. | |
802 | |
803 The performance of this option is also quite good. It may be slower than | |
804 the inline methods when you often open and close small files however. | |
805 The cost of the cryptographic handshake at the start of an @command{scp} | |
806 session can begin to absorb the advantage that the lack of encoding and | |
807 decoding presents. | |
808 | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
809 All the @command{ssh} based methods support the kludgy @command{-p} |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
810 feature where you can specify a port number to connect to in the host |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
811 name. For example, the host name @file{host#42} tells Tramp to |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
812 specify @command{-p 42} in the argument list for @command{ssh}. |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
813 |
45861 | 814 |
815 @item @option{rsync} --- @command{ssh} and @command{rsync} | |
816 | |
817 Using the @command{ssh} command to connect securely to the remote | |
818 machine and the @command{rsync} command to transfer files is almost | |
819 identical to the @option{scp} method. | |
820 | |
821 While @command{rsync} performs much better than @command{scp} when | |
822 transferring files that exist on both hosts, this advantage is lost if | |
823 the file exists only on one side of the connection. | |
824 | |
825 The @command{rsync} based method may be considerably faster than the | |
826 @command{rcp} based methods when writing to the remote system. Reading | |
827 files to the local machine is no faster than with a direct copy. | |
828 | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
829 This method supports the @command{-p} hack. |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
830 |
45861 | 831 |
832 @item @option{scpx} --- @command{ssh} and @command{scp} | |
833 | |
834 As you expect, this is similar to @option{scp}, only a little | |
835 different. Whereas @option{scp} opens a normal interactive shell on the | |
836 remote host, this option uses @command{ssh -t -t HOST -l USER /bin/sh} to | |
837 open a connection. This is useful for users where the normal login | |
838 shell is set up to ask them a number of questions when logging in. This | |
839 procedure avoids these questions, and just gives @tramp{} a more-or-less | |
840 `standard' login shell to work with. | |
841 | |
842 This is also useful for Windows users where @command{ssh}, when | |
843 invoked from an Emacs buffer, tells them that it is not allocating a | |
844 pseudo tty. When this happens, the login shell is wont to not print | |
845 any shell prompt, which confuses @tramp{} mightily. | |
846 | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
847 This method supports the @command{-p} hack. |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
848 |
45861 | 849 |
850 @item @option{pscp} --- @command{plink} and @command{pscp} | |
851 | |
852 This method is similar to @option{scp}, but it uses the | |
853 @command{plink} command to connect to the remote host, and it uses | |
854 @command{pscp} for transferring the files. These programs are part | |
855 of PuTTY, an SSH implementation for Windows. | |
856 | |
46010
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
857 CCC: Does @command{plink} support the @command{-p} hack? |
d07b0e5f80b9
(tramp-open-connection-rsh): Support a kludgy feature for the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
45979
diff
changeset
|
858 |
45861 | 859 |
860 @item @option{fcp} --- @command{fsh} and @command{fcp} | |
861 | |
862 This method is similar to @option{scp}, but it uses the @command{fsh} | |
863 command to connect to the remote host, and it uses @command{fcp} for | |
864 transferring the files. @command{fsh/fcp} are a front-end for | |
865 @command{ssh} which allow for reusing the same @command{ssh} session | |
866 for submitting several commands. This avoids the startup overhead of | |
867 @command{scp} (which has to establish a secure connection whenever it | |
868 is called). Note, however, that you can also use one of the inline | |
869 methods to achieve a similar effect. | |
870 | |
871 This method uses the command @command{fsh HOST -l USER /bin/sh -i} to | |
872 establish the connection, it does not work to just say @command{fsh | |
873 HOST -l USER}. | |
874 | |
875 @end itemize | |
876 | |
877 @node Multi-hop Methods | |
878 @section Connecting to a remote host using multiple hops | |
879 | |
880 Sometimes, the methods described before are not sufficient. Sometimes, | |
881 it is not possible to connect to a remote host using a simple command. | |
882 For example, if you are in a secured network, you might have to log in | |
883 to a `bastion host' first before you can connect to the outside world. | |
884 Of course, the target host may also require a bastion host. The format | |
885 of multi-hop filenames is slightly different than the format of normal | |
886 @tramp{} methods. | |
887 | |
888 A multi-hop file name specifies a method, a number of hops, and a path | |
889 name on the remote system. The method specifies how the file is | |
890 transferred through the inline connection. The following two multi-hop | |
891 methods are available: | |
892 | |
893 @itemize | |
894 @item @option{multi} --- base64 encoding with @command{mimencode} | |
895 | |
896 The file is transferred through the connection in base64 encoding. Uses | |
897 the @command{mimencode} program for doing encoding and decoding, but | |
898 uses an Emacs internal implementation on the local host if available. | |
899 | |
900 @item @option{multiu} --- use commands @command{uuencode} and @command{uudecode} | |
901 | |
902 The file is transferred through the connection in `uu' encoding. Uses | |
903 the @command{uuencode} and @command{uudecode} programs for encoding and | |
904 decoding, but uses a Lisp implementation for decoding on the local host | |
905 if available. | |
906 | |
907 @end itemize | |
908 | |
909 Each hop consists of a @dfn{hop method} specification, a user name and a | |
910 host name. The following hop methods are (currently) available: | |
911 | |
912 @itemize | |
913 @item @option{telnet} | |
914 | |
915 Uses the well-known @command{telnet} program to connect to the host. | |
916 Whereas user name and host name are supplied in the file name, the | |
917 user is queried for the password. | |
918 | |
919 @item @option{rsh} | |
920 | |
921 This uses @command{rsh} to connect to the host. You do not need to | |
922 enter a password unless @command{rsh} explicitly asks for it. | |
923 | |
924 @item @option{ssh} | |
925 | |
926 This uses @command{ssh} to connect to the host. You might have to enter | |
927 a password or a pass phrase. | |
928 | |
929 @item @option{su} | |
930 | |
931 This method does not actually contact a different host, but it allows | |
932 you to become a different user on the host you're currently on. This | |
933 might be useful if you want to edit files as root, but the remote host | |
934 does not allow remote root logins. In this case you can use | |
935 @option{telnet}, @option{rsh} or @option{ssh} to connect to the | |
936 remote host as a non-root user, then use an @option{su} hop to become | |
937 root. But @option{su} need not be the last hop in a sequence, you could | |
938 also use it somewhere in the middle, if the need arises. | |
939 | |
940 Even though you @emph{must} specify both user and host with a | |
941 @option{su} hop, the host name is ignored and only the user name is | |
942 used. | |
943 | |
944 @item @option{sudo} | |
945 | |
946 This is similar to the @option{su} hop, except that it uses | |
947 @command{sudo} rather than @command{su} to become a different user. | |
948 | |
949 @end itemize | |
950 | |
951 Some people might wish to use port forwarding with @code{ssh} or maybe | |
952 they have to use a nonstandard port. This can be accomplished by | |
953 putting a stanza in @file{~/.ssh/config} for the account which specifies | |
954 a different port number for a certain host name. But it can also be | |
955 accomplished within Tramp, by adding a multi-hop method. For example: | |
956 | |
957 @lisp | |
958 (add-to-list 'tramp-multi-connection-function-alist | |
959 '("sshf" tramp-multi-connect-rlogin "ssh %h -l %u -p 4400%n")) | |
960 @end lisp | |
961 | |
962 Now you can use a @code{sshf} hop which connects to port 4400 instead of | |
963 the standard port. | |
964 | |
965 | |
966 @node Default Method | |
967 @section Selecting a default method | |
968 | |
969 When you select an appropriate transfer method for your typical usage | |
970 you should set the variable @var{tramp-default-method} to reflect that | |
971 choice. This variable controls which method will be used when a method | |
972 is not specified in the @tramp{} file path. For example: | |
973 | |
974 @lisp | |
975 (setq tramp-default-method "scp") | |
976 @end lisp | |
977 | |
978 External transfer methods are normally preferable to inline transfer | |
979 methods, giving better performance. They may not be useful if you use | |
980 many remote machines where you cannot log in without a password. | |
981 | |
982 @xref{Inline methods}. | |
983 @xref{External transfer methods}. | |
984 @xref{Multi-hop Methods}. | |
985 | |
986 Another consideration with the selection of transfer methods is the | |
987 environment you will use them in and, especially when used over the | |
988 Internet, the security implications of your preferred method. | |
989 | |
990 The @command{rsh} and @command{telnet} methods send your password as | |
991 plain text as you log in to the remote machine, as well as transferring | |
992 the files in such a way that the content can easily be read from other | |
993 machines. | |
994 | |
995 If you need to connect to remote systems that are accessible from the | |
996 Internet, you should give serious thought to using @command{ssh} based | |
997 methods to connect. These provide a much higher level of security, | |
998 making it a non-trivial exercise for someone to obtain your password or | |
999 read the content of the files you are editing. | |
1000 | |
1001 @node Customizing Methods | |
1002 @section Using Non-Standard Methods | |
1003 | |
1004 There is a variable @code{tramp-methods} which you can change if the | |
1005 predefined methods don't seem right. | |
1006 | |
1007 For the time being, I'll refer you to the Lisp documentation of that | |
1008 variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. | |
1009 | |
1010 | |
1011 @node Remote Programs | |
1012 @section How @tramp{} finds and uses programs on the remote machine. | |
1013 | |
1014 @tramp{} depends on a number of programs on the remote host in order to | |
1015 function, including @command{ls}, @command{test}, @command{find} and | |
1016 @command{cat}. | |
1017 | |
1018 In addition to these required tools, there are various tools that may be | |
1019 required based on the connection method. See @ref{Inline methods} and | |
1020 @ref{External transfer methods} for details on these. | |
1021 | |
1022 Certain other tools, such as @command{perl} (or @command{perl5}) and | |
1023 @command{grep} will be used if they can be found. When they are | |
1024 available, they are used to improve the performance and accuracy of | |
1025 remote file access. | |
1026 | |
1027 When @tramp{} connects to the remote machine, it searches for the | |
1028 programs that it can use. The variable @var{tramp-remote-path} controls | |
1029 the directories searched on the remote machine. | |
1030 | |
1031 By default, this is set to a reasonable set of defaults for most | |
1032 machines. It is possible, however, that your local (or remote ;) system | |
1033 administrator has put the tools you want in some obscure local | |
1034 directory. | |
1035 | |
1036 In this case, you can still use them with @tramp{}. You simply need to | |
1037 add code to your @file{.emacs} to add the directory to the remote path. | |
1038 This will then be searched by @tramp{} when you connect and the software | |
1039 found. | |
1040 | |
1041 To add a directory to the remote search path, you could use code such | |
1042 as: | |
1043 | |
1044 @example | |
1045 (require 'tramp) @i{; @tramp{} must be loaded before this} | |
1046 @i{; happens.} | |
1047 | |
1048 @i{; We have @command{perl} in "/usr/local/perl"} | |
1049 (add-to-list 'tramp-remote-path "/usr/local/perl") | |
1050 @end example | |
1051 | |
1052 @node Remote shell setup | |
1053 @comment node-name, next, previous, up | |
1054 @section Remote shell setup hints | |
1055 | |
1056 As explained in the @ref{Overview} section, @tramp{} connects to the | |
1057 remote host and talks to the shell it finds there. Of course, when you | |
1058 log in, the shell executes its init files. Suppose your init file | |
1059 requires you to enter the birthdate of your mother; clearly @tramp{} | |
1060 does not know this and hence fails to log you in to that host. | |
1061 | |
1062 There are different possible strategies for pursuing this problem. One | |
1063 strategy is to enable @tramp{} to deal with all possible situations. | |
1064 This is a losing battle, since it is not possible to deal with | |
1065 @emph{all} situations. The other strategy is to require you to set up | |
1066 the remote host such that it behaves like @tramp{} expect. This might | |
1067 be inconvenient because you have to invest a lot of effort into shell | |
1068 setup before you can begin to use @tramp{}. | |
1069 | |
1070 The package, therefore, pursues a combined approach. It tries to figure | |
1071 out some of the more common setups, and only requires you to avoid | |
1072 really exotic stuff. For example, it looks through a list of | |
1073 directories to find some programs on the remote host. And also, it | |
1074 knows that it is not obvious how to check whether a file exist, and | |
1075 therefore it tries different possibilities. (On some hosts and shells, | |
1076 the command @code{test -e} does the trick, on some hosts the shell | |
1077 builtin doesn't work but the program @code{/usr/bin/test -e} or | |
1078 @code{/bin/test -e} works. And on still other hosts, @code{ls -d} is | |
1079 the right way to do this.) | |
1080 | |
1081 Below you find a discussion of a few things that @tramp{} does not deal | |
1082 with, and that you therefore have to set up correctly. | |
1083 | |
1084 @itemize | |
1085 @item @code{shell-prompt-pattern} | |
1086 | |
1087 @vindex shell-prompt-pattern | |
1088 After logging in to the remote host, @tramp{} has to wait for the remote | |
1089 shell startup to finish before it can send commands to the remote | |
1090 shell. The strategy here is to wait for the shell prompt. In order to | |
1091 recognize the shell prompt, the variable @code{shell-prompt-pattern} has | |
1092 to be set correctly to recognize the shell prompt on the remote host. | |
1093 | |
1094 @item @code{tset} and other questions | |
1095 | |
1096 Some people invoke the @code{tset} program from their shell startup | |
1097 scripts which asks the user about the terminal type of the shell. Maybe | |
1098 some shells ask other questions when they are started. @tramp{} does | |
1099 not know how to answer these questions. (A facility for enabling | |
1100 @tramp{} to answer these questions is planned for some future version, | |
1101 but don't hold your breath.) | |
1102 | |
1103 Therefore, you should take care that the shell does not ask any | |
1104 questions when invoked from @tramp{}. You can do this by checking the | |
1105 @code{TERM} environment variable, it will be set to @code{dumb} when | |
1106 connecting. | |
1107 | |
1108 @vindex tramp-terminal-type | |
1109 The variable @code{tramp-terminal-type} can be used to change this value | |
1110 @code{dumb}. | |
1111 | |
1112 @end itemize | |
1113 | |
1114 | |
1115 @node Windows setup hints | |
1116 @section Issues with Cygwin ssh | |
1117 | |
1118 This section needs a lot of work! Please help. | |
1119 | |
1120 If you use the Cygwin installation of ssh (you have to explicitly select | |
1121 it in the installer), then it should work out of the box to just select | |
1122 @code{smx} as the connection method. You can find information about | |
1123 setting up Cygwin in their FAQ at @uref{http://cygwin.com/faq/}. | |
1124 | |
1125 | |
1126 @node Usage | |
1127 @chapter Using @tramp | |
1128 | |
1129 Once you have installed @tramp{} it will operate fairly transparently. You | |
1130 will be able to access files on any remote machine that you can log in | |
1131 to as though they were local. | |
1132 | |
1133 Files are specified to @tramp{} using a formalized syntax specifying the | |
1134 details of the system to connect to. This is similar to the syntax used | |
1135 by the @command{EFS} and @command{ange-ftp} packages. | |
1136 | |
1137 | |
1138 @menu | |
1139 * Filename Syntax:: @tramp{} filename conventions. | |
1140 * Multi-hop filename syntax:: Multi-hop filename conventions | |
1141 * Dired:: Dired and filename completion. | |
1142 @end menu | |
1143 | |
1144 | |
1145 @node Filename Syntax | |
1146 @section @tramp{} filename conventions | |
1147 | |
1148 To access the file <path> on the remote machine <machine> you would | |
1149 specify the filename @file{/[<machine>]<path>}. (The square brackets | |
1150 are part of the file name.) This will connect to <machine> and transfer | |
1151 the file using the default method. @xref{Default Method}. | |
1152 | |
1153 Some examples of @tramp{} filenames are: | |
1154 | |
1155 @table @file | |
1156 @item /[melancholia].emacs | |
1157 Edit the file @file{.emacs} in your home directory on the machine | |
1158 @code{melancholia}. | |
1159 | |
1160 @item /[melancholia.danann.net].emacs | |
1161 This edits the same file, using the fully qualified domain name of | |
1162 the machine. | |
1163 | |
1164 @item /[melancholia]~/.emacs | |
1165 This also edits the same file --- the @file{~} is expanded to your | |
1166 home directory on the remote machine, just like it is locally. | |
1167 | |
1168 @item /[melancholia]~daniel/.emacs | |
1169 This edits the file @file{.emacs} in the home directory of the user | |
1170 @code{daniel} on the machine @code{melancholia}. The @file{~<user>} | |
1171 construct is expanded to the home directory of that user on the remote | |
1172 machine. | |
1173 | |
1174 @item /[melancholia]/etc/squid.conf | |
1175 This edits the file @file{/etc/squid.conf} on the machine | |
1176 @code{melancholia}. | |
1177 | |
1178 @end table | |
1179 | |
1180 | |
1181 Unless you specify a different name to use, @tramp{} will use the current | |
1182 local user name as the remote user name to log in with. If you need to | |
1183 log in as a different user, you can specify the user name as part of the | |
1184 filename. | |
1185 | |
1186 To log in to the remote machine as a specific user, you use the syntax | |
1187 @file{/[<user>@@<machine>]/path/to.file}. That means that connecting to | |
1188 @code{melancholia} as @code{daniel} and editing @file{.emacs} in your | |
1189 home directory you would specify @file{/[daniel@@melancholia].emacs}. | |
1190 | |
1191 | |
1192 It is also possible to specify other file transfer methods | |
1193 (@pxref{Default Method}) as part of the filename. This is done by | |
1194 replacing the initial @file{/[} with @file{/[<method>/}. (Note the | |
1195 trailing slash!) The user, machine and file specification remain the | |
1196 same. | |
1197 | |
1198 So, to connect to the machine @code{melancholia} as @code{daniel}, using | |
1199 the @option{su} method to transfer files, and edit @file{.emacs} in my | |
1200 home directory I would specify the filename | |
1201 @file{/[su/daniel@@melancholia].emacs}. | |
1202 | |
1203 | |
1204 @node Multi-hop filename syntax | |
1205 @section Multi-hop filename conventions | |
1206 | |
1207 The syntax of multi-hop file names is necessarily slightly different | |
1208 than the syntax of other @tramp{} file names. Here's an example multi-hop | |
1209 file name: | |
1210 | |
1211 @file{/[multi/rsh:out@@gate/telnet:kai@@real.host]/path/to.file} | |
1212 | |
1213 This is quite a mouthful. So let's go through it step by step. The | |
1214 file name consists of three parts, separated by slashes and square | |
1215 brackets. The first part is @file{/[multi}, the method specification. | |
1216 The second part is @file{rsh:out@@gate/telnet:kai@@real.host} and | |
1217 specifies the hops. (Yes, the second part may contain even more | |
1218 slashes, so that's why this file name has more than two colons in it.) | |
1219 The final part is @file{/path/to.file} and specifies the file name on | |
1220 the remote host. | |
1221 | |
1222 The first part and the final part should be clear. @ref{Multi-hop | |
1223 Methods}, for a list of alternatives for the method specification. | |
1224 | |
1225 The second part can be subdivided again into components, so-called hops. | |
1226 In the above file name, there are two hops, @file{rsh:out@@gate} and | |
1227 @file{telnet:kai@@real.host}. | |
1228 | |
1229 Each hop can @emph{again} be subdivided into (three) components, the | |
1230 @dfn{hop method}, the @dfn{user name} and the @dfn{host name}. The | |
1231 meaning of the second and third component should be clear, and the hop | |
1232 method says what program to use to perform that hop. | |
1233 | |
1234 The first hop, @file{rsh:out@@gate}, says to use @command{rsh} to log in | |
1235 as user @code{out} to the host @code{gate}. Starting at that host, the | |
1236 second hop, @file{telnet:kai@@real.host}, says to use @command{telnet} | |
1237 to log in as user @code{kai} to host @code{real.host}. | |
1238 | |
1239 @xref{Multi-hop Methods}, for a list of possible hop method values. The | |
1240 variable @var{tramp-multi-connection-function-alist} contains the list of | |
1241 possible hop methods and information on how to execute them, should you | |
1242 want to add your own. | |
1243 | |
1244 | |
1245 @node Dired | |
1246 @section Dired and filename completion | |
1247 | |
1248 @tramp{} works transparently with dired, enabling you to use this powerful | |
1249 file management tool to manage files on any machine you have access to | |
1250 over the Internet. | |
1251 | |
1252 Filename completion also works with @tramp{} for files on remote machines | |
1253 although there is no completion for user names or machine names at this | |
1254 stage. | |
1255 | |
1256 As filename completion needs to fetch the listing of files from the | |
1257 remote machine, this feature is sometimes fairly slow. As @tramp{} does not | |
1258 yet cache the results of directory listing, there is no gain in | |
1259 performance the second time you complete filenames. | |
1260 | |
1261 If you need to browse a directory tree, Dired is a better choice, at | |
1262 present, than filename completion. Dired has its own cache mechanism | |
1263 and will only fetch the directory listing once. | |
1264 | |
1265 | |
1266 @node Bug Reports | |
1267 @chapter Reporting Bugs and Problems | |
1268 | |
1269 Bugs and problems with @tramp{} are actively worked on by the development | |
1270 team. Feature requests and suggestions are also more than welcome. | |
1271 | |
1272 The @tramp{} mailing list is a great place to get information on working | |
1273 with @tramp{}, solving problems and general discussion and advice on topics | |
1274 relating to the package. | |
1275 | |
1276 The mailing list is at @email{tramp-devel@@mail.freesoftware.fsf.org}. | |
1277 Messages sent to this address go to all the subscribers. This is | |
1278 @emph{not} the address to send subscription requests to. | |
1279 | |
1280 For help on subscribing to the list, send mail to the administrative | |
1281 address, @email{tramp-devel-request@@mail.freesoftware.fsf.org}, with the | |
1282 subject @samp{help}. | |
1283 | |
1284 To report a bug in @tramp{}, you should execute @kbd{M-x tramp-bug}. This | |
1285 will automatically generate a buffer with the details of your system and | |
1286 @tramp{} version. | |
1287 | |
1288 When submitting a bug report, please try to describe in excruciating | |
1289 detail the steps required to reproduce the problem, the setup of the | |
1290 remote machine and any special conditions that exist. | |
1291 | |
1292 If you can identify a minimal test case that reproduces the problem, | |
1293 include that with your bug report. This will make it much easier for the | |
1294 development team to analyze and correct the problem. | |
1295 | |
1296 @node Frequently Asked Questions | |
1297 @chapter Frequently Asked Questions | |
1298 | |
1299 @itemize @bullet | |
1300 @item Where can I get the latest @tramp{}? | |
1301 | |
1302 @tramp{} is available at | |
1303 @uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/tramp.tar.gz}. | |
1304 There is also a Savannah project page, at | |
1305 @uref{https://savannah.gnu.org/projects/tramp/}. | |
1306 | |
1307 | |
1308 @item Which systems does it work on? | |
1309 | |
1310 The package has been used successfully on Emacs 20 and Emacs 21, as well | |
1311 as XEmacs 21. XEmacs 20 is more problematic, see the notes in | |
1312 @file{tramp.el}. I don't think anybody has really tried it on Emacs 19. | |
1313 | |
1314 The package was intended to work on Unix, and it really expects a | |
1315 Unix-like system on the remote end, but some people seemed to have some | |
1316 success getting it to work on NT Emacs. | |
1317 | |
1318 There are some informations on Tramp on NT at the following URL; many | |
1319 thanks to Joe Stoy for providing the information: | |
1320 @uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/} | |
1321 | |
1322 The above mostly contains patches to old ssh versions; Tom Roche has a | |
1323 Web page with instructions: | |
1324 @uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html} | |
1325 | |
1326 ??? Is the XEmacs info correct? | |
1327 | |
1328 ??? Can somebody provide some information for getting it to work on NT | |
1329 Emacs? I think there was some issue with @command{ssh}? | |
1330 | |
1331 | |
1332 @item I can't stop EFS starting with XEmacs | |
1333 | |
1334 Not all the older versions of @tramp{} supported XEmacs correctly. The | |
1335 first thing to do is to make sure that you have the latest version of | |
1336 @tramp{} installed. | |
1337 | |
1338 If you do, please try and find out exactly the conditions required for | |
1339 the @code{EFS} handlers to fire. If you can, putting a breakpoint on | |
1340 @code{efs-ftp-path} and sending in the stack trace along with your bug | |
1341 report would make it easier for the developers to work out what is going | |
1342 wrong. | |
1343 | |
1344 | |
1345 @item File name completion does not work with @tramp{} | |
1346 | |
1347 When you log in to the remote machine, do you see the output of | |
1348 @command{ls} in color? If so, this may be the cause of your problems. | |
1349 | |
1350 @command{ls} outputs @acronym{ANSI} escape sequences that your terminal | |
1351 emulator interprets to set the colors. These escape sequences will | |
1352 confuse @tramp{} however. | |
1353 | |
1354 In your @file{.bashrc}, @file{.profile} or equivalent on the remote | |
1355 machine you probably have an alias configured that adds the option | |
1356 @option{--color=yes} or @option{--color=auto}. | |
1357 | |
1358 You should remove that alias and ensure that a new login @emph{does not} | |
1359 display the output of @command{ls} in color. If you still cannot use | |
1360 filename completion, report a bug to the @tramp{} developers. | |
1361 | |
1362 | |
1363 @item File name completion does not work in large directories | |
1364 | |
1365 @tramp{} uses globbing for some operations. (Globbing means to use the | |
1366 shell to expand wildcards such as `*.c'.) This might create long | |
1367 command lines, especially in directories with many files. Some shell | |
1368 choke on long command lines, or don't cope well with the globbing | |
1369 itself. | |
1370 | |
1371 If you have a large directory on the remote end, you may wish to execute | |
1372 a command like @command{ls -d * ..?* > /dev/null} and see if it hangs. | |
1373 Note that you must first start the right shell, which might be | |
1374 @command{/bin/sh}, @command{ksh} or @command{bash}, depending on which | |
1375 of those supports tilde expansion. | |
1376 | |
1377 | |
1378 @item What kinds of systems does @tramp{} work on | |
1379 | |
1380 @tramp{} really expects the remote system to be a Unix-like system. The | |
1381 local system should preferably be Unix-like, as well, but @tramp{} might | |
1382 work on NT with some tweaking. | |
1383 | |
1384 | |
1385 @item How can I get notified when @tramp{} file transfers are complete? | |
1386 | |
1387 The following snippet can be put in your @file{~/.emacs} file. It makes | |
1388 Emacs beep after reading from or writing to the remote host. | |
1389 | |
1390 @lisp | |
1391 (defadvice tramp-handle-write-region | |
1392 (after tramp-write-beep-advice activate) | |
1393 " make tramp beep after writing a file." | |
1394 (interactive) | |
1395 (beep)) | |
1396 (defadvice tramp-handle-do-copy-or-rename-file | |
1397 (after tramp-copy-beep-advice activate) | |
1398 " make tramp beep after copying a file." | |
1399 (interactive) | |
1400 (beep)) | |
1401 (defadvice tramp-handle-insert-file-contents | |
1402 (after tramp-copy-beep-advice activate) | |
1403 " make tramp beep after copying a file." | |
1404 (interactive) | |
1405 (beep)) | |
1406 @end lisp | |
1407 | |
1408 | |
1409 @item There's this @file{~/.sh_history} file on the remote host which | |
1410 keeps growing and growing. What's that? | |
1411 | |
1412 Sometimes, @tramp{} starts @code{ksh} on the remote host for tilde | |
1413 expansion. Maybe @code{ksh} saves the history by default. @tramp{} | |
1414 tries to turn off saving the history, but maybe you have to help. For | |
1415 example, you could put this in your @file{.kshrc}: | |
1416 | |
1417 @example | |
1418 if [ -f $HOME/.sh_history ] ; then | |
1419 /bin/rm $HOME/.sh_history | |
1420 fi | |
1421 if [ "$@{HISTFILE-unset@}" != "unset" ] ; then | |
1422 unset HISTFILE | |
1423 fi | |
1424 if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then | |
1425 unset HISTSIZE | |
1426 fi | |
1427 @end example | |
1428 | |
1429 @end itemize | |
1430 | |
1431 | |
1432 @c For the developer | |
1433 @node Version Control | |
1434 @chapter The inner workings of remote version control | |
1435 | |
1436 Unlike EFS and ange-ftp, @tramp{} has full shell access to the remote | |
1437 machine. This makes it possible to provide version control for files | |
1438 accessed under @tramp{}. | |
1439 | |
1440 The actual version control binaries must be installed on the remote | |
1441 machine, accessible in the directories specified in | |
1442 @var{tramp-remote-path}. | |
1443 | |
1444 This transparent integration with the version control systems is one of | |
1445 the most valuable features provided by @tramp{}, but it is far from perfect. | |
1446 Work is ongoing to improve the transparency of the system. | |
1447 | |
1448 @menu | |
1449 * Version Controlled Files:: Determining if a file is under version control. | |
1450 * Remote Commands:: Executing the version control commands on the remote machine. | |
1451 * Changed workfiles:: Detecting if the working file has changed. | |
1452 * Checking out files:: Bringing the workfile out of the repository. | |
1453 * Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere | |
1454 @end menu | |
1455 | |
1456 | |
1457 @node Version Controlled Files | |
1458 @section Determining if a file is under version control | |
1459 | |
1460 The VC package uses the existence of on-disk revision control master | |
1461 files to determine if a given file is under revision control. These file | |
1462 tests happen on the remote machine through the standard @tramp{} mechanisms. | |
1463 | |
1464 | |
1465 @node Remote Commands | |
1466 @section Executing the version control commands on the remote machine | |
1467 | |
1468 There are no hooks provided by VC to allow intercepting of the version | |
1469 control command execution. The calls occur through the | |
1470 @code{call-process} mechanism, a function that is somewhat more | |
1471 efficient than the @code{shell-command} function but that does not | |
1472 provide hooks for remote execution of commands. | |
1473 | |
1474 To work around this, the functions @code{vc-do-command} and | |
1475 @code{vc-simple-command} have been advised to intercept requests for | |
1476 operations on files accessed via @tramp{}. | |
1477 | |
1478 In the case of a remote file, the @code{shell-command} interface is | |
1479 used, with some wrapper code, to provide the same functionality on the | |
1480 remote machine as would be seen on the local machine. | |
1481 | |
1482 | |
1483 @node Changed workfiles | |
1484 @section Detecting if the working file has changed | |
1485 | |
1486 As there is currently no way to get access to the mtime of a file on a | |
1487 remote machine in a portable way, the @code{vc-workfile-unchanged-p} | |
1488 function is advised to call an @tramp{} specific function for remote files. | |
1489 | |
1490 The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC | |
1491 diff functionality to determine if any changes have occurred between the | |
1492 workfile and the version control master. | |
1493 | |
1494 This requires that a shell command be executed remotely, a process that | |
1495 is notably heavier-weight than the mtime comparison used for local | |
1496 files. Unfortunately, unless a portable solution to the issue is found, | |
1497 this will remain the cost of remote version control. | |
1498 | |
1499 | |
1500 @node Checking out files | |
1501 @section Bringing the workfile out of the repository | |
1502 | |
1503 VC will, by default, check for remote files and refuse to act on them | |
1504 when checking out files from the repository. To work around this | |
1505 problem, the function @code{vc-checkout} knows about @tramp{} files and | |
1506 allows version control to occur. | |
1507 | |
1508 | |
1509 @node Miscellaneous Version Control | |
1510 @section Things related to Version Control that don't fit elsewhere | |
1511 | |
1512 Minor implementation details, &c. | |
1513 | |
1514 @menu | |
1515 * Remote File Ownership:: How VC determines who owns a workfile. | |
1516 * Back-end Versions:: How VC determines what release your RCS is. | |
1517 @end menu | |
1518 | |
1519 | |
1520 @node Remote File Ownership | |
1521 @subsection How VC determines who owns a workfile | |
1522 | |
1523 Emacs provides the @code{user-full-name} function to return the login name | |
1524 of the current user as well as mapping from arbitrary user id values | |
1525 back to login names. The VC code uses this functionality to map from the | |
1526 uid of the owner of a workfile to the login name in some circumstances. | |
1527 | |
1528 This will not, for obvious reasons, work if the remote system has a | |
1529 different set of logins. As such, it is necessary to delegate to the | |
1530 remote machine the job of determining the login name associated with a | |
1531 uid. | |
1532 | |
1533 Unfortunately, with the profusion of distributed management systems such | |
1534 as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple, | |
1535 reliable and portable method for performing this mapping. | |
1536 | |
1537 Thankfully, the only place in the VC code that depends on the mapping of | |
1538 a uid to a login name is the @code{vc-file-owner} function. This returns | |
1539 the login of the owner of the file as a string. | |
1540 | |
1541 This function has been advised to use the output of @command{ls} on the | |
1542 remote machine to determine the login name, delegating the problem of | |
1543 mapping the uid to the login to the remote system which should know more | |
1544 about it than I do. | |
1545 | |
1546 | |
1547 @node Back-end Versions | |
1548 @subsection How VC determines what release your RCS is | |
1549 | |
1550 VC needs to know what release your revision control binaries you are | |
1551 running as not all features VC supports are available with older | |
1552 versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}. | |
1553 | |
1554 The default implementation of VC determines this value the first time it | |
1555 is needed and then stores the value globally to avoid the overhead of | |
1556 executing a process and parsing its output each time the information is | |
1557 needed. | |
1558 | |
1559 Unfortunately, life is not quite so easy when remote version control | |
1560 comes into the picture. Each remote machine may have a different version | |
1561 of the version control tools and, while this is painful, we need to | |
1562 ensure that unavailable features are not used remotely. | |
1563 | |
1564 To resolve this issue, @tramp{} currently takes the sledgehammer | |
1565 approach of making the release values of the revision control tools | |
1566 local to each @tramp{} buffer, forcing VC to determine these values | |
1567 again each time a new file is visited. | |
1568 | |
1569 This has, quite obviously, some performance implications. Thankfully, | |
1570 most of the common operations performed by VC do not actually require | |
1571 that the remote version be known. This makes the problem far less | |
1572 apparent. | |
1573 | |
1574 Eventually these values will be captured by @tramp{} on a system by | |
1575 system basis and the results cached to improve performance. | |
1576 | |
1577 | |
1578 @node Files directories and paths | |
1579 @chapter How file names, directories and paths are mangled and managed. | |
1580 | |
1581 @menu | |
1582 * Path deconstruction:: Breaking a path into its components. | |
1583 @end menu | |
1584 | |
1585 | |
1586 @node Path deconstruction | |
1587 @section Breaking a path into its components. | |
1588 | |
1589 @tramp{} filenames are somewhat different, obviously, to ordinary path | |
1590 names. As such, the lisp functions @code{file-name-directory} and | |
1591 @code{file-name-nondirectory} are overridden within the @tramp{} package. | |
1592 | |
1593 Their replacements are reasonably simplistic in their approach. They | |
1594 dissect the filename, call the original handler on the remote path and | |
1595 then rebuild the @tramp{} path with the result. | |
1596 | |
1597 This allows the platform specific hacks in the original handlers to take | |
1598 effect while preserving the @tramp{} path information. | |
1599 | |
1600 | |
1601 @node Issues | |
1602 @chapter Debatable Issues and What Was Decided | |
1603 | |
1604 @itemize @bullet | |
1605 @item The uuencode method does not always work. | |
1606 | |
1607 Due to the design of @tramp{}, the encoding and decoding programs need to | |
1608 read from stdin and write to stdout. On some systems, @code{uudecode -o | |
1609 -} will read stdin and write the decoded file to stdout, on other | |
1610 systems @code{uudecode -p} does the same thing. But some systems have | |
1611 uudecode implementations which cannot do this at all---it is not | |
1612 possible to call these uudecode implementations with suitable parameters | |
1613 so that they write to stdout. | |
1614 | |
1615 Of course, this could be circumvented: the @code{begin foo 644} line | |
1616 could be rewritten to put in some temporary file name, then | |
1617 @code{uudecode} could be called, then the temp file could be printed and | |
1618 deleted. | |
1619 | |
1620 But I have decided that this is too fragile to reliably work, so on some | |
1621 systems you'll have to do without the uuencode methods. | |
1622 | |
1623 @item @tramp{} does not work on XEmacs 20. | |
1624 | |
1625 This is because it requires the macro @code{with-timeout} which does not | |
1626 appear to exist in XEmacs 20. I'm somewhat reluctant to add an | |
1627 emulation macro to @tramp{}, but if somebody who uses XEmacs 20 steps | |
1628 forward and wishes to implement and test it, please contact me or the | |
1629 mailing list. | |
1630 | |
1631 @end itemize | |
1632 | |
1633 | |
1634 @c End of tramp.texi - the TRAMP User Manual | |
1635 @bye | |
1636 | |
1637 @c TODO | |
1638 @c | |
1639 @c * Say something about the .login and .profile files of the remote | |
1640 @c shells. | |
1641 @c * Explain how tramp.el works in principle: open a shell on a remote | |
1642 @c host and then send commands to it. | |
1643 | |
1644 @c Local Variables: | |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
45864
diff
changeset
|
1645 @c eval: (add-hook 'write-file-functions 'time-stamp) |
45861 | 1646 @c time-stamp-start: "@set UPDATED " |
1647 @c time-stamp-format: "%:a, %:d %:b, %:y" | |
1648 @c time-stamp-end: "$" | |
1649 @c time-stamp-line-limit: 50 | |
1650 @c End: |