Mercurial > emacs
comparison man/tramp.texi @ 88155:d7ddb3e565de
sync with trunk
author | Henrik Enberg <henrik.enberg@telia.com> |
---|---|
date | Mon, 16 Jan 2006 00:03:54 +0000 |
parents | ffda74ab6dc4 |
children |
comparison
equal
deleted
inserted
replaced
88154:8ce476d3ba36 | 88155:d7ddb3e565de |
---|---|
6 @c %**end of header | 6 @c %**end of header |
7 | 7 |
8 @c This is *so* much nicer :) | 8 @c This is *so* much nicer :) |
9 @footnotestyle end | 9 @footnotestyle end |
10 | 10 |
11 @c In the Tramp CVS, the version number is auto-frobbed from the | 11 @c In the Tramp CVS, the version number is auto-frobbed from |
12 @c Makefile, so you should edit the top-level Makefile to change | 12 @c configure.ac, so you should edit that file and run |
13 @c the version number. | 13 @c "autoconf && ./configure" to change the version number. |
14 @macro trampver{} | 14 |
15 2.0.29 | 15 @c Additionally, flags are set with respect to the Emacs flavor; and |
16 @c depending whether Tramp is packaged into (X)Emacs, or standalone. | |
17 | |
18 @include trampver.texi | |
19 | |
20 @c Macros for formatting a filename. | |
21 @c trampfn is for a full filename, trampfnmhp means method, host, localname | |
22 @c were given, and so on. | |
23 @macro trampfn(method, user, host, localname) | |
24 @value{prefix}@value{method}@value{user}@@@value{host}@value{postfix}@value{localname} | |
16 @end macro | 25 @end macro |
17 | 26 |
18 @c Entries for @command{install-info} to use | |
19 @dircategory Emacs | |
20 @direntry | |
21 * TRAMP: (tramp). Transparent Remote Access, Multiple Protocol | |
22 Emacs remote file access via rsh and rcp. | |
23 @end direntry | |
24 | |
25 @c Macro to make formatting of the tramp program name consistent. | |
26 @macro tramp | |
27 @sc{tramp} | |
28 @end macro | |
29 | |
30 @c Distinguish between GNU Emacs and XEmacs. Derived from the | |
31 @c Makefile variable $(EMACS-ID). Valid values are `emacs' and `xemacs'. | |
32 @set emacs | |
33 | |
34 @c Some flags which make the text independent on the (X)Emacs flavor. | |
35 @c GNU Emacs values. | |
36 @ifset emacs | |
37 @set emacs-name Emacs | |
38 @set emacs-dir emacs | |
39 @set ftp-package-name Ange-FTP | |
40 @set tramp-prefix / | |
41 @set tramp-prefix-single-hop | |
42 @set tramp-postfix : | |
43 @set tramp-postfix-single-hop : | |
44 @set tramp-postfix-multi-hop : | |
45 @end ifset | |
46 | |
47 @c XEmacs counterparts. | |
48 @ifset xemacs | |
49 @set emacs-name XEmacs | |
50 @set emacs-dir xemacs | |
51 @set ftp-package-name EFS | |
52 @set tramp-prefix /[ | |
53 @set tramp-prefix-single-hop [ | |
54 @set tramp-postfix ] | |
55 @set tramp-postfix-single-hop / | |
56 @set tramp-postfix-multi-hop : | |
57 @end ifset | |
58 | |
59 @c Macros for formatting a filename. | |
60 @c trampfn is for a full filename, trampfnmhp means method, host, path | |
61 @c were given, and so on. | |
62 @macro trampfn(method, user, host, path) | |
63 @value{tramp-prefix}@value{method}@value{user}@@@value{host}@value{tramp-postfix}@value{path} | |
64 @end macro | |
65 | |
66 @copying | 27 @copying |
67 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Free Software | 28 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, |
68 Foundation, Inc. | 29 2005 Free Software Foundation, Inc. |
69 | 30 |
70 @quotation | 31 @quotation |
71 Permission is granted to copy, distribute and/or modify this document | 32 Permission is granted to copy, distribute and/or modify this document |
72 under the terms of the GNU Free Documentation License, Version 1.1 or | 33 under the terms of the GNU Free Documentation License, Version 1.2 or |
73 any later version published by the Free Software Foundation; with no | 34 any later version published by the Free Software Foundation; with no |
74 Invariant Sections, with the Front-Cover texts being ``A GNU | 35 Invariant Sections, with the Front-Cover texts being ``A GNU |
75 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | 36 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the |
76 license is included in the section entitled ``GNU Free Documentation | 37 license is included in the section entitled ``GNU Free Documentation |
77 License'' in the Emacs manual. | 38 License'' in the Emacs manual. |
85 separately from the collection, you can do so by adding a copy of the | 46 separately from the collection, you can do so by adding a copy of the |
86 license to the document, as described in section 6 of the license. | 47 license to the document, as described in section 6 of the license. |
87 @end quotation | 48 @end quotation |
88 @end copying | 49 @end copying |
89 | 50 |
51 @c Entries for @command{install-info} to use | |
52 @dircategory @value{emacsname} | |
53 @direntry | |
54 * TRAMP: (tramp). Transparent Remote Access, Multiple Protocol | |
55 @value{emacsname} remote file access via rsh and rcp. | |
56 @end direntry | |
57 | |
90 @tex | 58 @tex |
91 | 59 |
92 @titlepage | 60 @titlepage |
93 @title @tramp{} version @trampver{} User Manual | 61 @title @value{tramp} version @value{trampver} User Manual |
94 | 62 |
95 @author by Daniel Pittman | 63 @author by Daniel Pittman |
96 @author based on documentation by Kai Gro@ss{}johann | 64 @author based on documentation by Kai Gro@ss{}johann |
97 | 65 |
98 @page | 66 @page |
103 | 71 |
104 @end tex | 72 @end tex |
105 | 73 |
106 @ifnottex | 74 @ifnottex |
107 @node Top, Overview, (dir), (dir) | 75 @node Top, Overview, (dir), (dir) |
108 @top @tramp{} version @trampver{} User Manual | 76 @top @value{tramp} version @value{trampver} User Manual |
109 | 77 |
110 This file documents @tramp{} version @trampver{}, a remote file | 78 This file documents @value{tramp} version @value{trampver}, a remote file |
111 editing package for @value{emacs-name}. | 79 editing package for @value{emacsname}. |
112 | 80 |
113 @tramp{} stands for `Transparent Remote (file) Access, Multiple | 81 @value{tramp} stands for `Transparent Remote (file) Access, Multiple |
114 Protocol'. This package provides remote file editing, similar to | 82 Protocol'. This package provides remote file editing, similar to |
115 @value{ftp-package-name}. | 83 @value{ftppackagename}. |
116 | 84 |
117 The difference is that @value{ftp-package-name} uses FTP to transfer | 85 The difference is that @value{ftppackagename} uses FTP to transfer |
118 files between the local and the remote host, whereas @tramp{} uses a | 86 files between the local and the remote host, whereas @value{tramp} uses a |
119 combination of @command{rsh} and @command{rcp} or other work-alike | 87 combination of @command{rsh} and @command{rcp} or other work-alike |
120 programs, such as @command{ssh}/@command{scp}. | 88 programs, such as @command{ssh}/@command{scp}. |
121 | 89 |
122 You can find the latest version of this document on the web at | 90 You can find the latest version of this document on the web at |
123 @uref{http://www.freesoftware.fsf.org/tramp/}. | 91 @uref{http://www.gnu.org/software/tramp/}. |
124 | 92 |
93 @c Pointer to the other Emacs flavor is necessary only in case of | |
94 @c standalone installation. | |
95 @ifset installchapter | |
96 The manual has been generated for @value{emacsname}. | |
97 @ifinfo | |
98 If you want to read the info pages for @value{emacsothername}, you | |
99 should read in @ref{Installation} how to create them. | |
100 @end ifinfo | |
125 @ifhtml | 101 @ifhtml |
126 This manual is also available as a @uref{tramp_ja.html, Japanese | 102 If you're using the other Emacs flavor, you should read the |
127 translation}. | 103 @uref{@value{emacsotherfilename}, @value{emacsothername}} pages. |
128 | 104 @end ifhtml |
129 The latest release of @tramp{} is available for | 105 @end ifset |
130 @uref{http://savannah.gnu.org/download/tramp/, | 106 |
131 download}, or you may see @ref{Obtaining @tramp{}} for more details, | 107 @ifhtml |
132 including the CVS server details. | 108 @ifset jamanual |
133 | 109 This manual is also available as a @uref{@value{japanesemanual}, |
134 @tramp{} also has a @uref{https://savannah.gnu.org/projects/tramp/, | 110 Japanese translation}. |
111 @end ifset | |
112 | |
113 The latest release of @value{tramp} is available for | |
114 @uref{http://ftp.gnu.org/gnu/tramp/, download}, or you may see | |
115 @ref{Obtaining Tramp} for more details, including the CVS server | |
116 details. | |
117 | |
118 @value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/, | |
135 Savannah Project Page}. | 119 Savannah Project Page}. |
136 @end ifhtml | 120 @end ifhtml |
137 | 121 |
138 There is a mailing list for @tramp{}, available at | 122 There is a mailing list for @value{tramp}, available at |
139 @email{tramp-devel@@mail.freesoftware.fsf.org}, and archived at | 123 @email{tramp-devel@@gnu.org}, and archived at |
140 @uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/} as | 124 @uref{http://lists.gnu.org/archive/html/tramp-devel/, the |
141 well as the usual Savannah archives. | 125 @value{tramp} Mail Archive}. |
126 @ifhtml | |
127 Older archives are located at | |
128 @uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel, | |
129 SourceForge Mail Archive} and | |
130 @uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/, | |
131 The Mail Archive}. | |
132 @c in HTML output, there's no new paragraph. | |
133 @*@* | |
134 @end ifhtml | |
142 | 135 |
143 @insertcopying | 136 @insertcopying |
144 | 137 |
145 @end ifnottex | 138 @end ifnottex |
146 | 139 |
147 @menu | 140 @menu |
148 * Overview:: What @tramp{} can and cannot do. | 141 * Overview:: What @value{tramp} can and cannot do. |
149 | 142 |
150 For the end user: | 143 For the end user: |
151 * Obtaining @tramp{}:: How to obtain @tramp{}. | 144 |
152 * History:: History of @tramp{}. | 145 * Obtaining Tramp:: How to obtain @value{tramp}. |
153 * Installation:: Installing @tramp{} with your @value{emacs-name}. | 146 * History:: History of @value{tramp}. |
154 * Configuration:: Configuring @tramp{} for use. | 147 @ifset installchapter |
155 * Usage:: An overview of the operation of @tramp{}. | 148 * Installation:: Installing @value{tramp} with your @value{emacsname}. |
149 @end ifset | |
150 * Configuration:: Configuring @value{tramp} for use. | |
151 * Usage:: An overview of the operation of @value{tramp}. | |
156 * Bug Reports:: Reporting Bugs and Problems. | 152 * Bug Reports:: Reporting Bugs and Problems. |
157 * Frequently Asked Questions:: Questions and answers from the mailing list. | 153 * Frequently Asked Questions:: Questions and answers from the mailing list. |
154 * Concept Index:: An item for each concept. | |
158 | 155 |
159 For the developer: | 156 For the developer: |
157 | |
160 * Version Control:: The inner workings of remote version control. | 158 * Version Control:: The inner workings of remote version control. |
161 * Files directories and paths:: How file names, directories and paths are mangled and managed. | 159 * Files directories and localnames:: How file names, directories and localnames are mangled and managed. |
162 * Issues:: Debatable Issues and What Was Decided. | 160 * Issues:: Debatable Issues and What Was Decided. |
163 | 161 |
164 @detailmenu | 162 @detailmenu |
165 --- The Detailed Node Listing --- | 163 --- The Detailed Node Listing --- |
166 | 164 @c |
167 Configuring @tramp{} for use | 165 @ifset installchapter |
166 Installing @value{tramp} with your @value{emacsname} | |
167 | |
168 * Installation parameters:: Parameters in order to control installation. | |
169 * Load paths:: How to plug-in @value{tramp} into your environment. | |
170 * Japanese manual:: Japanese manual. | |
171 | |
172 @end ifset | |
173 | |
174 Configuring @value{tramp} for use | |
168 | 175 |
169 * Connection types:: Types of connections made to remote machines. | 176 * Connection types:: Types of connections made to remote machines. |
170 * Inline methods:: Inline methods. | 177 * Inline methods:: Inline methods. |
171 * External transfer methods:: External transfer methods. | 178 * External transfer methods:: External transfer methods. |
172 * Multi-hop Methods:: Connecting to a remote host using multiple hops. | 179 * Multi-hop Methods:: Connecting to a remote host using multiple hops. |
173 * Default Method:: Selecting a default method. | 180 * Default Method:: Selecting a default method. |
174 * Customizing Methods:: Using Non-Standard Methods. | 181 * Customizing Methods:: Using Non-Standard Methods. |
175 * Customizing Completion:: Selecting config files for user/host name completion. | 182 * Customizing Completion:: Selecting config files for user/host name completion. |
176 * Remote Programs:: How @tramp{} finds and uses programs on the remote machine. | 183 * Password caching:: Reusing passwords for several connections. |
184 * Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. | |
177 * Remote shell setup:: Remote shell setup hints. | 185 * Remote shell setup:: Remote shell setup hints. |
178 * Windows setup hints:: Issues with Cygwin ssh. | 186 * Windows setup hints:: Issues with Cygwin ssh. |
179 | 187 * Auto-save and Backup:: Auto-save and Backup. |
180 Using @tramp | 188 |
181 | 189 Using @value{tramp} |
182 * Filename Syntax:: @tramp{} filename conventions. | 190 |
191 * Filename Syntax:: @value{tramp} filename conventions. | |
183 * Multi-hop filename syntax:: Multi-hop filename conventions. | 192 * Multi-hop filename syntax:: Multi-hop filename conventions. |
184 * Filename completion:: Filename completion. | 193 * Filename completion:: Filename completion. |
185 * Dired:: Dired. | 194 * Dired:: Dired. |
195 * Compilation:: Compile remote files. | |
186 | 196 |
187 The inner workings of remote version control | 197 The inner workings of remote version control |
188 | 198 |
189 * Version Controlled Files:: Determining if a file is under version control. | 199 * Version Controlled Files:: Determining if a file is under version control. |
190 * Remote Commands:: Executing the version control commands on the remote machine. | 200 * Remote Commands:: Executing the version control commands on the remote machine. |
195 Things related to Version Control that don't fit elsewhere | 205 Things related to Version Control that don't fit elsewhere |
196 | 206 |
197 * Remote File Ownership:: How VC determines who owns a workfile. | 207 * Remote File Ownership:: How VC determines who owns a workfile. |
198 * Back-end Versions:: How VC determines what release your RCS is. | 208 * Back-end Versions:: How VC determines what release your RCS is. |
199 | 209 |
200 How file names, directories and paths are mangled and managed. | 210 How file names, directories and localnames are mangled and managed |
201 | 211 |
202 * Path deconstruction:: Breaking a path into its components. | 212 * Localname deconstruction:: Breaking a localname into its components. |
203 | 213 |
204 @end detailmenu | 214 @end detailmenu |
205 @end menu | 215 @end menu |
206 | 216 |
207 @node Overview | 217 @node Overview |
208 @chapter An overview of @tramp | 218 @chapter An overview of @value{tramp} |
209 @cindex overview | 219 @cindex overview |
210 | 220 |
211 After the installation of @tramp{} into your @value{emacs-name}, you | 221 After the installation of @value{tramp} into your @value{emacsname}, |
212 will be able to access files on remote machines as though they were | 222 you will be able to access files on remote machines as though they |
213 local. Access to the remote file system for editing files, version | 223 were local. Access to the remote file system for editing files, |
214 control, and @command{dired} are transparently enabled. | 224 version control, and @code{dired} are transparently enabled. |
215 | 225 |
216 Your access to the remote machine can be with the @command{rsh}, | 226 Your access to the remote machine can be with the @command{rsh}, |
217 @command{rlogin}, @command{telnet} programs or with any similar | 227 @command{rlogin}, @command{telnet} programs or with any similar |
218 connection method. This connection must pass ASCII successfully to be | 228 connection method. This connection must pass @acronym{ASCII} |
219 usable but need not be 8-bit clean. | 229 successfully to be usable but need not be 8-bit clean. |
220 | 230 |
221 The package provides support for @command{ssh} connections out of the | 231 The package provides support for @command{ssh} connections out of the |
222 box, one of the more common uses of the package. This allows | 232 box, one of the more common uses of the package. This allows |
223 relatively secure access to machines, especially if @command{ftp} | 233 relatively secure access to machines, especially if @command{ftp} |
224 access is disabled. | 234 access is disabled. |
225 | 235 |
226 The majority of activity carried out by @tramp{} requires only that | 236 The majority of activity carried out by @value{tramp} requires only that |
227 the remote login is possible and is carried out at the terminal. In | 237 the remote login is possible and is carried out at the terminal. In |
228 order to access remote files @tramp{} needs to transfer their content | 238 order to access remote files @value{tramp} needs to transfer their content |
229 to the local machine temporarily. | 239 to the local machine temporarily. |
230 | 240 |
231 @tramp{} can transfer files between the machines in a variety of ways. | 241 @value{tramp} can transfer files between the machines in a variety of ways. |
232 The details are easy to select, depending on your needs and the | 242 The details are easy to select, depending on your needs and the |
233 machines in question. | 243 machines in question. |
234 | 244 |
235 The fastest transfer methods (for large files) rely on a remote file | 245 The fastest transfer methods (for large files) rely on a remote file |
236 transfer package such as @command{rcp}, @command{scp} or | 246 transfer package such as @command{rcp}, @command{scp} or |
237 @command{rsync}. The use of these methods is only possible if the | 247 @command{rsync}. |
238 file copy command does not ask for a password for the remote machine. | 248 |
239 | 249 If the remote copy methods are not suitable for you, @value{tramp} also |
240 If the remote copy methods are not suitable for you, @tramp{} also | |
241 supports the use of encoded transfers directly through the shell. | 250 supports the use of encoded transfers directly through the shell. |
242 This requires that the @command{mimencode} or @command{uuencode} tools | 251 This requires that the @command{mimencode} or @command{uuencode} tools |
243 are available on the remote machine. These methods are generally | 252 are available on the remote machine. These methods are generally |
244 faster for small files. | 253 faster for small files. |
245 | 254 |
246 Within these limitations, @tramp{} is quite powerful. It is worth | 255 Within these limitations, @value{tramp} is quite powerful. It is worth |
247 noting that, as of the time of writing, it is far from a polished | 256 noting that, as of the time of writing, it is far from a polished |
248 end-user product. For a while yet you should expect to run into rough | 257 end-user product. For a while yet you should expect to run into rough |
249 edges and problems with the code now and then. | 258 edges and problems with the code now and then. |
250 | 259 |
251 It is finished enough that the developers use it for day to day work but | 260 It is finished enough that the developers use it for day to day work but |
252 the installation and setup can be a little difficult to master, as can | 261 the installation and setup can be a little difficult to master, as can |
253 the terminology. | 262 the terminology. |
254 | 263 |
255 @tramp{} is still under active development and any problems you encounter, | 264 @value{tramp} is still under active development and any problems you encounter, |
256 trivial or major, should be reported to the @tramp{} developers. | 265 trivial or major, should be reported to the @value{tramp} developers. |
257 @xref{Bug Reports}. | 266 @xref{Bug Reports}. |
258 | 267 |
259 | 268 |
260 @subsubheading Behind the scenes | 269 @subsubheading Behind the scenes |
261 @cindex behind the scenes | 270 @cindex behind the scenes |
262 @cindex details of operation | 271 @cindex details of operation |
263 @cindex how it works | 272 @cindex how it works |
264 | 273 |
265 This section tries to explain what goes on behind the scenes when you | 274 This section tries to explain what goes on behind the scenes when you |
266 access a remote file through @tramp{}. | 275 access a remote file through @value{tramp}. |
267 | 276 |
268 Suppose you type @kbd{C-x C-f} and enter part of an @tramp{} file name, | 277 Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name, |
269 then hit @kbd{@key{TAB}} for completion. Suppose further that this is | 278 then hit @kbd{@key{TAB}} for completion. Suppose further that this is |
270 the first time that @tramp{} is invoked for the host in question. Here's | 279 the first time that @value{tramp} is invoked for the host in question. Here's |
271 what happens: | 280 what happens: |
272 | 281 |
273 @itemize | 282 @itemize |
274 @item | 283 @item |
275 @tramp{} discovers that it needs a connection to the host. So it | 284 @value{tramp} discovers that it needs a connection to the host. So it |
276 invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l | 285 invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l |
277 @var{user}} or a similar tool to connect to the remote host. | 286 @var{user}} or a similar tool to connect to the remote host. |
278 Communication with this process happens through an | 287 Communication with this process happens through an |
279 @value{emacs-name} buffer, that is, the output from the remote end | 288 @value{emacsname} buffer, that is, the output from the remote end |
280 goes into a buffer. | 289 goes into a buffer. |
281 | 290 |
282 @item | 291 @item |
283 The remote host may prompt for a login name (for @command{telnet}). The | 292 The remote host may prompt for a login name (for @command{telnet}). |
284 login name is given in the file name, so @tramp{} sends the login name and | 293 The login name is given in the file name, so @value{tramp} sends the |
285 a newline. | 294 login name and a newline. |
286 | 295 |
287 @item | 296 @item |
288 The remote host may prompt for a password or pass phrase (for | 297 The remote host may prompt for a password or pass phrase (for |
289 @command{rsh} or for @command{telnet} after sending the login name). | 298 @command{rsh} or for @command{telnet} after sending the login name). |
290 @tramp{} displays the prompt in the minibuffer, asking you for the | 299 @value{tramp} displays the prompt in the minibuffer, asking you for the |
291 password or pass phrase. | 300 password or pass phrase. |
292 | 301 |
293 You enter the password or pass phrase. @tramp{} sends it to the remote | 302 You enter the password or pass phrase. @value{tramp} sends it to the remote |
294 host, followed by a newline. | 303 host, followed by a newline. |
295 | 304 |
296 @item | 305 @item |
297 @tramp{} now waits for the shell prompt or for a message that the login | 306 @value{tramp} now waits for the shell prompt or for a message that the login |
298 failed. | 307 failed. |
299 | 308 |
300 If @tramp{} sees neither of them after a certain period of time (a minute, | 309 If @value{tramp} sees neither of them after a certain period of time (a minute, |
301 say), then it issues an error message saying that it couldn't find the | 310 say), then it issues an error message saying that it couldn't find the |
302 remote shell prompt and shows you what the remote host has sent. | 311 remote shell prompt and shows you what the remote host has sent. |
303 | 312 |
304 If @tramp{} sees a @samp{login failed} message, it tells you so, | 313 If @value{tramp} sees a @samp{login failed} message, it tells you so, |
305 aborts the login attempt and allows you to try again. | 314 aborts the login attempt and allows you to try again. |
306 | 315 |
307 @item | 316 @item |
308 Suppose that the login was successful and @tramp{} sees the shell prompt | 317 Suppose that the login was successful and @value{tramp} sees the shell prompt |
309 from the remote host. Now @tramp{} invokes @command{/bin/sh} because | 318 from the remote host. Now @value{tramp} invokes @command{/bin/sh} because |
310 Bourne shells and C shells have different command | 319 Bourne shells and C shells have different command |
311 syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login | 320 syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login |
312 shell doesn't recognize @samp{exec /bin/sh} as a valid command. | 321 shell doesn't recognize @samp{exec /bin/sh} as a valid command. |
313 Maybe you use the Scheme shell @command{scsh}@dots{}} | 322 Maybe you use the Scheme shell @command{scsh}@dots{}} |
314 | 323 |
315 After the Bourne shell has come up, @tramp{} sends a few commands to | 324 After the Bourne shell has come up, @value{tramp} sends a few commands to |
316 ensure a good working environment. It turns off echoing, it sets the | 325 ensure a good working environment. It turns off echoing, it sets the |
317 shell prompt, and a few other things. | 326 shell prompt, and a few other things. |
318 | 327 |
319 @item | 328 @item |
320 Now the remote shell is up and it good working order. Remember, what | 329 Now the remote shell is up and it good working order. Remember, what |
321 was supposed to happen is that @tramp{} tries to find out what files exist | 330 was supposed to happen is that @value{tramp} tries to find out what files exist |
322 on the remote host so that it can do filename completion. | 331 on the remote host so that it can do filename completion. |
323 | 332 |
324 So, @tramp{} basically issues @command{cd} and @command{ls} commands and | 333 So, @value{tramp} basically issues @command{cd} and @command{ls} commands and |
325 also sometimes @command{echo} with globbing. Another command that is | 334 also sometimes @command{echo} with globbing. Another command that is |
326 often used is @command{test} to find out whether a file is writable or a | 335 often used is @command{test} to find out whether a file is writable or a |
327 directory or the like. The output of each command is parsed for the | 336 directory or the like. The output of each command is parsed for the |
328 necessary operation. | 337 necessary operation. |
329 | 338 |
331 Suppose you are finished with filename completion, have entered @kbd{C-x | 340 Suppose you are finished with filename completion, have entered @kbd{C-x |
332 C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to | 341 C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to |
333 transfer the file contents from the remote host to the local host so | 342 transfer the file contents from the remote host to the local host so |
334 that you can edit them. | 343 that you can edit them. |
335 | 344 |
336 See above for an explanation of how @tramp{} transfers the file contents. | 345 See above for an explanation of how @value{tramp} transfers the file contents. |
337 | 346 |
338 For inline transfers, @tramp{} issues a command like @samp{mimencode -b | 347 For inline transfers, @value{tramp} issues a command like @samp{mimencode -b |
339 /path/to/remote/file}, waits until the output has accumulated in the | 348 /path/to/remote/file}, waits until the output has accumulated in the |
340 buffer that's used for communication, then decodes that output to | 349 buffer that's used for communication, then decodes that output to |
341 produce the file contents. | 350 produce the file contents. |
342 | 351 |
343 For out-of-band transfers, @tramp{} issues a command like the following: | 352 For out-of-band transfers, @value{tramp} issues a command like the following: |
344 @example | 353 @example |
345 rcp user@@host:/path/to/remote/file /tmp/tramp.4711 | 354 rcp user@@host:/path/to/remote/file /tmp/tramp.4711 |
346 @end example | 355 @end example |
347 It then reads the local temporary file @file{/tmp/tramp.4711} into a | 356 It then reads the local temporary file @file{/tmp/tramp.4711} into a |
348 buffer and deletes the temporary file. | 357 buffer and deletes the temporary file. |
351 You now edit the buffer contents, blithely unaware of what has happened | 360 You now edit the buffer contents, blithely unaware of what has happened |
352 behind the scenes. (Unless you have read this section, that is.) When | 361 behind the scenes. (Unless you have read this section, that is.) When |
353 you are finished, you type @kbd{C-x C-s} to save the buffer. | 362 you are finished, you type @kbd{C-x C-s} to save the buffer. |
354 | 363 |
355 @item | 364 @item |
356 Again, @tramp{} transfers the file contents to the remote host either | 365 Again, @value{tramp} transfers the file contents to the remote host either |
357 inline or out-of-band. This is the reverse of what happens when reading | 366 inline or out-of-band. This is the reverse of what happens when reading |
358 the file. | 367 the file. |
359 | |
360 @end itemize | 368 @end itemize |
361 | 369 |
362 I hope this has provided you with a basic overview of what happens | 370 I hope this has provided you with a basic overview of what happens |
363 behind the scenes when you open a file with @tramp{}. | 371 behind the scenes when you open a file with @value{tramp}. |
364 | 372 |
365 | 373 |
366 @c For the end user | 374 @c For the end user |
367 @node Obtaining @tramp{} | 375 @node Obtaining Tramp |
368 @chapter Obtaining @tramp{}. | 376 @chapter Obtaining Tramp. |
369 @cindex obtaining Tramp | 377 @cindex obtaining Tramp |
370 | 378 |
371 @tramp{} is freely available on the Internet and the latest release may be | 379 @value{tramp} is freely available on the Internet and the latest |
372 downloaded from | 380 release may be downloaded from |
373 @uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/tramp.tar.gz}. This | 381 @uref{http://ftp.gnu.org/gnu/tramp/}. This release includes the full |
374 release includes the full documentation and code for @tramp{}, suitable | 382 documentation and code for @value{tramp}, suitable for installation. |
375 for installation. But Emacs (21.4 or later) includes @tramp{} | 383 But GNU Emacs (22 or later) includes @value{tramp} already, and there |
376 already, and there is a @tramp{} package for XEmacs, as well. So | 384 is a @value{tramp} package for XEmacs, as well. So maybe it is easier |
377 maybe it is easier to just use those. But if you want the bleeding | 385 to just use those. But if you want the bleeding edge, read |
378 edge, read on@dots{...} | 386 on@dots{...} |
379 | 387 |
380 For the especially brave, @tramp{} is available from CVS. The CVS version | 388 For the especially brave, @value{tramp} is available from CVS. The CVS |
381 is the latest version of the code and may contain incomplete features or | 389 version is the latest version of the code and may contain incomplete |
382 new issues. Use these versions at your own risk. | 390 features or new issues. Use these versions at your own risk. |
383 | 391 |
384 Instructions for obtaining the latest development version of @tramp{} | 392 Instructions for obtaining the latest development version of @value{tramp} |
385 from CVS can be found by going to the Savannah project page at the | 393 from CVS can be found by going to the Savannah project page at the |
386 following URL and then clicking on the CVS link in the navigation bar at | 394 following URL and then clicking on the CVS link in the navigation bar |
387 the top. | 395 at the top. |
388 | 396 |
389 @noindent | 397 @noindent |
390 @uref{http://savannah.gnu.org/projects/tramp/} | 398 @uref{http://savannah.gnu.org/projects/tramp/} |
391 | 399 |
392 @noindent | 400 @noindent |
393 Or follow the example session below: | 401 Or follow the example session below: |
394 | 402 |
395 @example | 403 @example |
396 ] @strong{cd ~/@value{emacs-dir}} | 404 ] @strong{cd ~/@value{emacsdir}} |
397 ] @strong{cvs -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp login} | 405 ] @strong{export CVS_RSH="ssh"} |
398 | 406 ] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp} |
399 (Logging in to anoncvs@@subversions.gnu.org) | |
400 CVS password: @strong{(just hit RET here)} | |
401 @dots{} | |
402 | |
403 ] @strong{cvs -z3 -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp co tramp} | |
404 @end example | 407 @end example |
405 | 408 |
406 @noindent | 409 @noindent |
407 You should now have a directory @file{~/@value{emacs-dir}/tramp} containing the latest | 410 You should now have a directory @file{~/@value{emacsdir}/tramp} |
408 version of @tramp{}. You can fetch the latest updates from the repository | 411 containing the latest version of @value{tramp}. You can fetch the latest |
409 by issuing the command: | 412 updates from the repository by issuing the command: |
410 | 413 |
411 @example | 414 @example |
412 ] @strong{cd ~/@value{emacs-dir}/tramp} | 415 ] @strong{cd ~/@value{emacsdir}/tramp} |
416 ] @strong{export CVS_RSH="ssh"} | |
413 ] @strong{cvs update -d} | 417 ] @strong{cvs update -d} |
414 @end example | 418 @end example |
415 | 419 |
420 @noindent | |
421 Once you've got updated files from the CVS repository, you need to run | |
422 @command{autoconf} in order to get an up-to-date @file{configure} | |
423 script: | |
424 | |
425 @example | |
426 ] @strong{cd ~/@value{emacsdir}/tramp} | |
427 ] @strong{autoconf} | |
428 @end example | |
429 | |
416 | 430 |
417 @node History | 431 @node History |
418 @chapter History of @tramp{} | 432 @chapter History of @value{tramp} |
419 @cindex history | 433 @cindex history |
420 @cindex development history | 434 @cindex development history |
421 | 435 |
422 Development was started end of November 1998. The package was called | 436 Development was started end of November 1998. The package was called |
423 @file{rssh.el}, back then. It only provided one method to access a | 437 @file{rssh.el}, back then. It only provided one method to access a |
424 file, using @command{ssh} to log in to a remote host and using | 438 file, using @command{ssh} to log in to a remote host and using |
425 @command{scp} to transfer the file contents. After a while, the name | 439 @command{scp} to transfer the file contents. After a while, the name |
426 was changed to @file{rcp.el}, and now it's @tramp{}. Along the way, | 440 was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way, |
427 many more methods for getting a remote shell and for transferring the | 441 many more methods for getting a remote shell and for transferring the |
428 file contents were added. Support for VC was added. | 442 file contents were added. Support for VC was added. |
429 | 443 |
430 The most recent addition of major features were the multi-hop methods | 444 The most recent addition of major features were the multi-hop methods |
431 added in April 2000 and the unification of @tramp{} and Ange-FTP | 445 added in April 2000 and the unification of @value{tramp} and Ange-FTP |
432 filenames in July 2002. | 446 filenames in July 2002. |
433 | 447 |
434 | 448 @c Installation chapter is necessary only in case of standalone |
435 @node Installation | 449 @c installation. Text taken from trampinst.texi. |
436 @chapter Installing @tramp{} into @value{emacs-name}. | 450 @ifset installchapter |
437 @cindex installation | 451 @include trampinst.texi |
438 | |
439 If you use the version that comes with your @value{emacs-name}, the | |
440 following information is not necessary. Installing @tramp{} into your | |
441 @value{emacs-name} is a relatively easy process, at least compared | |
442 to rebuilding your machine from scratch. ;) | |
443 | |
444 Seriously though, the installation should be a fairly simple matter. | |
445 | |
446 The easiest way to proceed is as follows: | |
447 | |
448 @itemize @bullet | |
449 @item | |
450 Choose a directory, say @file{~/@value{emacs-dir}/}. Change into that directory and | |
451 unpack the tarball. This will give you a directory | |
452 @file{~/@value{emacs-dir}/tramp/} which contains subdirectories @file{lisp} for the | |
453 Lisp code and @file{texi} for the documentation. | |
454 | |
455 @item | |
456 Optionally byte-compile all files in the Lisp directory, | |
457 @file{~/@value{emacs-dir}/tramp/lisp/}, by issuing a command like the following from | |
458 the top level directory @file{~/@value{emacs-dir}/tramp/}: | |
459 | |
460 @example | |
461 make EMACS=@value{emacs-dir} all | |
462 @end example | |
463 | |
464 @item | |
465 NOTE: If you run into problems running the example @command{make} | |
466 command, don't despair. You can still byte compile the @file{*.el} | |
467 files by opening @value{emacs-name} in @command{dired} (@command{C-x | |
468 d}) mode, at @file{~/@value{emacs-dir}/tramp/lisp}. Mark the lisp files with | |
469 @kbd{m}, then press @kbd{B} to byte compile your selections. | |
470 | |
471 Something similar can be done to create the info manual. Just change | |
472 to directory @file{~/@value{emacs-dir}/tramp/texi} and load the | |
473 @file{tramp.texi} file in @value{emacs-name}. Then press @kbd{M-x | |
474 texinfo-format-buffer @key{RET}} to generate @file{tramp.info}. | |
475 | |
476 @item | |
477 Tell @value{emacs-name} about the new Lisp directory and the | |
478 @tramp{} package with the following lines in @file{~/.emacs}: | |
479 | |
480 @lisp | |
481 (add-to-list 'load-path "~/@value{emacs-dir}/tramp/lisp/") | |
482 (require 'tramp) | |
483 @end lisp | |
484 | |
485 @item | |
486 To be able to read the Info documentation, create a file | |
487 @file{~/@value{emacs-dir}/tramp/texi/dir} using the | |
488 @command{install-info} command, and add the directory to the search | |
489 path for Info. | |
490 | |
491 NOTE: | |
492 On systems using the @cite{gnu} version of @command{install-info}, the | |
493 @command{install-info} syntax is very direct and simple. One can | |
494 change to directory @file{~/@value{emacs-dir}/tramp/texi} and type: | |
495 | |
496 @example | |
497 install-info tramp.info dir | |
498 @end example | |
499 | |
500 and a @file{dir} file will be created with the @tramp{} | |
501 entry. The info reader will know how to interpret it, but must | |
502 be told where to find it (see below). If you want anything fancier | |
503 you'll need to look through @kbd{man install-info}. | |
504 | |
505 Debian gnu/linux doesn't default to @cite{gnu} @command{install-info} | |
506 and uses its own version. This version does not create a @file{dir} | |
507 file for you from scratch. You must provide a skeleton @file{dir} | |
508 file it recognizes. One can be found in a default installation of | |
509 @value{emacs-name} at @file{/usr/info/dir}. Copy the top of this file | |
510 down to the first occurrence of @code{* Menu} including that line plus | |
511 one more blank line, to your working directory | |
512 @file{~/@value{emacs-dir}/tramp/texi}, or use the sample | |
513 @file{~/@value{emacs-dir}/tramp/texi/dir_sample}. | |
514 | |
515 Once a @file{dir} file is in place, this command will make the entry: | |
516 | |
517 @example | |
518 install-info --infodir=. tramp.info | |
519 @end example | |
520 | |
521 If you want it in a specific category see @kbd{man install-info} for | |
522 further details. | |
523 | |
524 If the environment variable @env{INFOPATH} is set, add the directory | |
525 @file{~/@value{emacs-dir}/tramp/texi/} to it. Else, add the directory to | |
526 @ifset emacs | |
527 @code{Info-default-directory-list}, as follows: | |
528 | |
529 @lisp | |
530 (add-to-list 'Info-default-directory-list "~/@value{emacs-dir}/tramp/texi/") | |
531 @end lisp | |
532 @end ifset | |
533 @ifset xemacs | |
534 @code{Info-directory-list}, as follows: | |
535 @lisp | |
536 (add-to-list 'Info-directory-list "~/@value{emacs-dir}/tramp/texi/") | |
537 @end lisp | |
538 @end ifset | |
539 | |
540 @end itemize | |
541 | |
542 @ifset xemacs | |
543 For @value{emacs-name}, the package @file{fsf-compat} must be installed. | |
544 For details on package installation, see @ref{Packages, , ,xemacs}. | |
545 @ifhtml | |
546 (If the previous link doesn't work, try the @value{emacs-name} | |
547 documentation at | |
548 @uref{http://www.xemacs.org/Documentation/packageGuide.html,the | |
549 @value{emacs-name} site}.) | |
550 @end ifhtml | |
551 @end ifset | 452 @end ifset |
552 | 453 |
553 @node Configuration | 454 @node Configuration |
554 @chapter Configuring @tramp{} for use | 455 @chapter Configuring @value{tramp} for use |
555 @cindex configuration | 456 @cindex configuration |
556 | 457 |
557 @cindex default configuration | 458 @cindex default configuration |
558 @tramp{} is (normally) fully functional when it is initially | 459 @value{tramp} is (normally) fully functional when it is initially installed. |
559 installed. It is initially configured to use the @command{ssh} program | 460 It is initially configured to use the @command{ssh} program to connect |
560 to connect to the remote host and to use base-64 encoding (on the | 461 to the remote host and to use base64 or uu encoding to transfer the |
561 remote host, via @command{mimencode}, and on the local host via the | 462 files through that shell connection. So in the easiest case, you just |
562 built-in support for base-64 encoding in Emacs). | 463 type @kbd{C-x C-f} and then enter the filename |
464 @file{@value{prefix}@var{user}@@@var{machine}@value{postfix}@var{/path/to.file}}. | |
563 | 465 |
564 On some hosts, there are problems with opening a connection. These are | 466 On some hosts, there are problems with opening a connection. These are |
565 related to the behavior of the remote shell. See @xref{Remote shell | 467 related to the behavior of the remote shell. See @xref{Remote shell |
566 setup}, for details on this. | 468 setup}, for details on this. |
567 | 469 |
568 If you do not wish to use these commands to connect to the remote | 470 If you do not wish to use these commands to connect to the remote |
569 host, you should change the default connection and transfer method | 471 host, you should change the default connection and transfer method |
570 that @tramp uses. There are several different methods that @tramp{} | 472 that @value{tramp} uses. There are several different methods that @value{tramp} |
571 can use to connect to remote machines and transfer files | 473 can use to connect to remote machines and transfer files |
572 (@pxref{Connection types}). | 474 (@pxref{Connection types}). |
475 | |
476 If you don't know which method is right for you, see @xref{Default | |
477 Method}. | |
573 | 478 |
574 | 479 |
575 @menu | 480 @menu |
576 * Connection types:: Types of connections made to remote machines. | 481 * Connection types:: Types of connections made to remote machines. |
577 * Inline methods:: Inline methods. | 482 * Inline methods:: Inline methods. |
578 * External transfer methods:: External transfer methods. | 483 * External transfer methods:: External transfer methods. |
579 * Multi-hop Methods:: Connecting to a remote host using multiple hops. | 484 * Multi-hop Methods:: Connecting to a remote host using multiple hops. |
580 * Default Method:: Selecting a default method. | 485 * Default Method:: Selecting a default method. |
486 Here we also try to help those who | |
487 don't have the foggiest which method | |
488 is right for them. | |
581 * Customizing Methods:: Using Non-Standard Methods. | 489 * Customizing Methods:: Using Non-Standard Methods. |
582 * Customizing Completion:: Selecting config files for user/host name completion. | 490 * Customizing Completion:: Selecting config files for user/host name completion. |
583 * Remote Programs:: How @tramp{} finds and uses programs on the remote machine. | 491 * Password caching:: Reusing passwords for several connections. |
492 * Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. | |
584 * Remote shell setup:: Remote shell setup hints. | 493 * Remote shell setup:: Remote shell setup hints. |
585 * Windows setup hints:: Issues with Cygwin ssh. | 494 * Windows setup hints:: Issues with Cygwin ssh. |
495 * Auto-save and Backup:: Auto-save and Backup. | |
586 @end menu | 496 @end menu |
587 | 497 |
588 | 498 |
589 @node Connection types | 499 @node Connection types |
590 @section Types of connections made to remote machines. | 500 @section Types of connections made to remote machines. |
593 There are two basic types of transfer methods, each with its own | 503 There are two basic types of transfer methods, each with its own |
594 advantages and limitations. Both types of connection make use of a | 504 advantages and limitations. Both types of connection make use of a |
595 remote shell access program such as @command{rsh}, @command{ssh} or | 505 remote shell access program such as @command{rsh}, @command{ssh} or |
596 @command{telnet} to connect to the remote machine. | 506 @command{telnet} to connect to the remote machine. |
597 | 507 |
598 This connection is used to perform many of the operations that @tramp | 508 This connection is used to perform many of the operations that @value{tramp} |
599 requires to make the remote file system transparently accessible from | 509 requires to make the remote file system transparently accessible from |
600 the local machine. It is only when visiting files that the methods | 510 the local machine. It is only when visiting files that the methods |
601 differ. | 511 differ. |
602 | 512 |
603 @cindex inline methods | 513 @cindex inline methods |
624 The one exception to this rule are the @command{scp} based transfer | 534 The one exception to this rule are the @command{scp} based transfer |
625 methods. While these methods do see better performance when actually | 535 methods. While these methods do see better performance when actually |
626 transferring files, the overhead of the cryptographic negotiation at | 536 transferring files, the overhead of the cryptographic negotiation at |
627 startup may drown out the improvement in file transfer times. | 537 startup may drown out the improvement in file transfer times. |
628 | 538 |
629 External transfer methods do require that the remote copy command is not | 539 External transfer methods should be configured such a way that they |
630 interactive --- that is, the command does not prompt you for a password. | 540 don't require a password (with @command{ssh-agent}, or such alike). |
631 If you cannot perform remote copies without a password, you will need to | 541 If it isn't possible, you should consider @ref{Password caching}, |
632 use an inline transfer method to work with @tramp{}. | 542 otherwise you will be prompted for a password every copy action. |
633 | 543 |
634 @cindex multi-hop methods | 544 @cindex multi-hop methods |
635 @cindex methods, multi-hop | 545 @cindex methods, multi-hop |
636 A variant of the inline methods are the @dfn{multi-hop methods}. | 546 A variant of the inline methods are the @dfn{multi-hop methods}. |
637 These methods allow you to connect a remote host using a number `hops', | 547 These methods allow you to connect a remote host using a number `hops', |
643 @node Inline methods | 553 @node Inline methods |
644 @section Inline methods | 554 @section Inline methods |
645 @cindex inline methods | 555 @cindex inline methods |
646 @cindex methods, inline | 556 @cindex methods, inline |
647 | 557 |
648 The inline methods in @tramp{} are quite powerful and can work in | 558 The inline methods in @value{tramp} are quite powerful and can work in |
649 situations where you cannot use an external transfer program to connect. | 559 situations where you cannot use an external transfer program to connect. |
650 Inline methods are the only methods that work when connecting to the | 560 Inline methods are the only methods that work when connecting to the |
651 remote machine via telnet. (There are also strange inline methods which | 561 remote machine via telnet. (There are also strange inline methods which |
652 allow you to transfer files between @emph{user identities} rather than | 562 allow you to transfer files between @emph{user identities} rather than |
653 hosts, see below.) | 563 hosts, see below.) |
654 | 564 |
655 These methods depend on the existence of a suitable encoding and | 565 These methods depend on the existence of a suitable encoding and |
656 decoding command on remote machine. Locally, @tramp{} may be able to use | 566 decoding command on remote machine. Locally, @value{tramp} may be able to |
657 features of Emacs to decode and encode the files or it may require | 567 use features of @value{emacsname} to decode and encode the files or |
658 access to external commands to perform that task. | 568 it may require access to external commands to perform that task. |
659 | 569 |
660 @cindex uuencode | 570 @cindex uuencode |
661 @cindex mimencode | 571 @cindex mimencode |
662 @cindex base-64 encoding | 572 @cindex base-64 encoding |
663 @tramp{} checks the availability and usability of commands like | 573 @value{tramp} checks the availability and usability of commands like |
664 @command{mimencode} (part of the @command{metamail} package) or | 574 @command{mimencode} (part of the @command{metamail} package) or |
665 @command{uuencode} on the remote host. The first reliable command | 575 @command{uuencode} on the remote host. The first reliable command |
666 will be used. The search path can be customized, see @ref{Remote | 576 will be used. The search path can be customized, see @ref{Remote |
667 Programs}. | 577 Programs}. |
668 | 578 |
669 If both commands aren't available on the remote host, @tramp{} | 579 If both commands aren't available on the remote host, @value{tramp} |
670 transfers a small piece of Perl code to the remote host, and tries to | 580 transfers a small piece of Perl code to the remote host, and tries to |
671 apply it for encoding and decoding. | 581 apply it for encoding and decoding. |
672 | 582 |
673 | 583 |
674 @table @asis | 584 @table @asis |
676 @cindex method rsh | 586 @cindex method rsh |
677 @cindex rsh method | 587 @cindex rsh method |
678 | 588 |
679 Connect to the remote host with @command{rsh}. Due to the unsecure | 589 Connect to the remote host with @command{rsh}. Due to the unsecure |
680 connection it is recommended for very local host topology only. | 590 connection it is recommended for very local host topology only. |
591 | |
592 On operating systems which provide the command @command{remsh} instead | |
593 of @command{rsh}, you can use the method @option{remsh}. This is true | |
594 for HP-UX or Cray UNICOS, for example. | |
681 | 595 |
682 | 596 |
683 @item @option{ssh} | 597 @item @option{ssh} |
684 @cindex method ssh | 598 @cindex method ssh |
685 @cindex ssh method | 599 @cindex ssh method |
736 | 650 |
737 | 651 |
738 @item @option{sshx} | 652 @item @option{sshx} |
739 @cindex method sshx | 653 @cindex method sshx |
740 @cindex sshx method | 654 @cindex sshx method |
741 @cindex Cygwin (with sshx method) | 655 |
742 | 656 As you would expect, this is similar to @option{ssh}, only a little |
743 As you expect, this is similar to @option{ssh}, only a little | |
744 different. Whereas @option{ssh} opens a normal interactive shell on | 657 different. Whereas @option{ssh} opens a normal interactive shell on |
745 the remote host, this option uses @samp{ssh -t -t @var{host} -l | 658 the remote host, this option uses @samp{ssh -t -t @var{host} -l |
746 @var{user} /bin/sh} to open a connection. This is useful for users | 659 @var{user} /bin/sh} to open a connection. This is useful for users |
747 where the normal login shell is set up to ask them a number of | 660 where the normal login shell is set up to ask them a number of |
748 questions when logging in. This procedure avoids these questions, and | 661 questions when logging in. This procedure avoids these questions, and |
749 just gives @tramp{} a more-or-less `standard' login shell to work | 662 just gives @value{tramp} a more-or-less `standard' login shell to work |
750 with. | 663 with. |
751 | 664 |
752 Note that this procedure does not eliminate questions asked by | 665 Note that this procedure does not eliminate questions asked by |
753 @command{ssh} itself. For example, @command{ssh} might ask ``Are you | 666 @command{ssh} itself. For example, @command{ssh} might ask ``Are you |
754 sure you want to continue connecting?'' if the host key of the remote | 667 sure you want to continue connecting?'' if the host key of the remote |
755 host is not known. @tramp{} does not know how to deal with such a | 668 host is not known. @value{tramp} does not know how to deal with such a |
756 question (yet), therefore you will need to make sure that you can log | 669 question (yet), therefore you will need to make sure that you can log |
757 in without such questions. | 670 in without such questions. |
758 | 671 |
759 This is also useful for Windows users where @command{ssh}, when | 672 This is also useful for Windows users where @command{ssh}, when |
760 invoked from an Emacs buffer, tells them that it is not allocating a | 673 invoked from an @value{emacsname} buffer, tells them that it is not |
761 pseudo tty. When this happens, the login shell is wont to not print | 674 allocating a pseudo tty. When this happens, the login shell is wont |
762 any shell prompt, which confuses @tramp{} mightily. For reasons | 675 to not print any shell prompt, which confuses @value{tramp} mightily. |
763 unknown, some Windows ports for @command{ssh} (maybe the Cygwin one) | 676 For reasons unknown, some Windows ports for @command{ssh} require the |
764 require the doubled @samp{-t} option. | 677 doubled @samp{-t} option. |
765 | 678 |
766 This supports the @samp{-p} kludge. | 679 This supports the @samp{-p} kludge. |
767 | 680 |
768 | 681 |
769 @item @option{krlogin} | 682 @item @option{krlogin} |
781 | 694 |
782 This method is mostly interesting for Windows users using the PuTTY | 695 This method is mostly interesting for Windows users using the PuTTY |
783 implementation of SSH. It uses @samp{plink -ssh} to log in to the | 696 implementation of SSH. It uses @samp{plink -ssh} to log in to the |
784 remote host. | 697 remote host. |
785 | 698 |
699 Additionally, the method @option{plink1} is provided, which calls | |
700 @samp{plink -1 -ssh} in order to use SSH protocol version 1 | |
701 explicitely. | |
702 | |
786 CCC: Do we have to connect to the remote host once from the command | 703 CCC: Do we have to connect to the remote host once from the command |
787 line to accept the SSH key? Maybe this can be made automatic? | 704 line to accept the SSH key? Maybe this can be made automatic? |
788 | 705 |
789 CCC: Does @command{plink} support the @samp{-p} option? @tramp{} will | 706 CCC: Does @command{plink} support the @samp{-p} option? @value{tramp} will |
790 support that, anyway. | 707 support that, anyway. |
791 | 708 |
792 @end table | 709 @end table |
793 | 710 |
794 | 711 |
805 transfers to an external transfer utility. | 722 transfers to an external transfer utility. |
806 | 723 |
807 This saves the overhead of encoding and decoding that multiplexing the | 724 This saves the overhead of encoding and decoding that multiplexing the |
808 transfer through the one connection has with the inline methods. | 725 transfer through the one connection has with the inline methods. |
809 | 726 |
810 If you want to use an external transfer method you @emph{must} be able | 727 If you want to use an external transfer method you should be able to |
811 to execute the transfer utility to copy files to and from the remote | 728 execute the transfer utility to copy files to and from the remote |
812 machine without any interaction. | 729 machine without any interaction. |
813 | 730 |
814 @cindex ssh-agent | 731 @cindex ssh-agent |
815 This means that you will need to use @command{ssh-agent} if you use the | 732 This means that you will need to use @command{ssh-agent} if you use the |
816 @command{scp} program for transfers, or maybe your version of | 733 @command{scp} program for transfers, or maybe your version of |
817 @command{scp} accepts a password on the command line.@footnote{PuTTY's | 734 @command{scp} accepts a password on the command line.@footnote{PuTTY's |
818 @command{pscp} allows you to specify the password on the command line.} | 735 @command{pscp} allows you to specify the password on the command line.} |
819 If you use @command{rsync} via @command{ssh} then the same rule must | 736 If you use @command{rsync} via @command{ssh} then the same rule must |
820 apply to that connection. | 737 apply to that connection. |
821 | 738 |
822 If you cannot get @command{scp} to run without asking for a password but | 739 If you cannot get an external method to run without asking for a |
823 would still like to use @command{ssh} to secure your connection, have a | 740 password you should consider @ref{Password caching}. |
824 look at the @command{ssh} based inline methods. | |
825 | 741 |
826 | 742 |
827 @table @asis | 743 @table @asis |
828 @item @option{rcp} --- @command{rsh} and @command{rcp} | 744 @item @option{rcp} --- @command{rsh} and @command{rcp} |
829 @cindex method rcp | 745 @cindex method rcp |
830 @cindex rcp method | 746 @cindex rcp method |
831 @cindex rcp (with rcp method) | 747 @cindex rcp (with rcp method) |
832 @cindex rsh (with rcp method) | 748 @cindex rsh (with rcp method) |
833 | 749 |
834 This method uses the @command{rsh} and @command{rcp} commands to connect | 750 This method uses the @command{rsh} and @command{rcp} commands to connect |
835 to the remote machine and transfer files. This is probably the fastest | 751 to the remote machine and transfer files. This is probably the fastest |
836 connection method available. | 752 connection method available. |
753 | |
754 The alternative method @option{remcp} uses the @command{remsh} and | |
755 @command{rcp} commands. It should be applied on machines where | |
756 @command{remsh} is used instead of @command{rsh}. | |
837 | 757 |
838 | 758 |
839 @item @option{scp} --- @command{ssh} and @command{scp} | 759 @item @option{scp} --- @command{ssh} and @command{scp} |
840 @cindex method scp | 760 @cindex method scp |
841 @cindex scp method | 761 @cindex scp method |
855 There are also two variants, @option{scp1} and @option{scp2}, that | 775 There are also two variants, @option{scp1} and @option{scp2}, that |
856 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can | 776 call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can |
857 explicitly select whether you want to use the SSH protocol version 1 | 777 explicitly select whether you want to use the SSH protocol version 1 |
858 or 2 to connect to the remote host. (You can also specify in | 778 or 2 to connect to the remote host. (You can also specify in |
859 @file{~/.ssh/config}, the SSH configuration file, which protocol | 779 @file{~/.ssh/config}, the SSH configuration file, which protocol |
860 should be used, and use the regular @option{ssh} method.) | 780 should be used, and use the regular @option{scp} method.) |
861 | 781 |
862 Two other variants, @option{scp1_old} and @option{scp2_old}, use the | 782 Two other variants, @option{scp1_old} and @option{scp2_old}, use the |
863 @command{ssh1} and @command{ssh2} commands explicitly. If you don't | 783 @command{ssh1} and @command{ssh2} commands explicitly. If you don't |
864 know what these are, you do not need these options. | 784 know what these are, you do not need these options. |
865 | 785 |
866 All the @command{ssh} based methods support the kludgy @samp{-p} | 786 All the @command{ssh} based methods support the kludgy @samp{-p} |
867 feature where you can specify a port number to connect to in the host | 787 feature where you can specify a port number to connect to in the host |
868 name. For example, the host name @file{host#42} tells @tramp{} to | 788 name. For example, the host name @file{host#42} tells @value{tramp} to |
869 specify @samp{-p 42} in the argument list for @command{ssh}. | 789 specify @samp{-p 42} in the argument list for @command{ssh}. |
870 | 790 |
871 | 791 |
872 @item @option{rsync} --- @command{ssh} and @command{rsync} | 792 @item @option{rsync} --- @command{ssh} and @command{rsync} |
873 @cindex method rsync | 793 @cindex method rsync |
893 @item @option{scpx} --- @command{ssh} and @command{scp} | 813 @item @option{scpx} --- @command{ssh} and @command{scp} |
894 @cindex method scpx | 814 @cindex method scpx |
895 @cindex scpx method | 815 @cindex scpx method |
896 @cindex scp (with scpx method) | 816 @cindex scp (with scpx method) |
897 @cindex ssh (with scpx method) | 817 @cindex ssh (with scpx method) |
898 @cindex Cygwin (with scpx method) | 818 |
899 | 819 As you would expect, this is similar to @option{scp}, only a little |
900 As you expect, this is similar to @option{scp}, only a little | |
901 different. Whereas @option{scp} opens a normal interactive shell on | 820 different. Whereas @option{scp} opens a normal interactive shell on |
902 the remote host, this option uses @samp{ssh -t -t @var{host} -l | 821 the remote host, this option uses @samp{ssh -t -t @var{host} -l |
903 @var{user} /bin/sh} to open a connection. This is useful for users | 822 @var{user} /bin/sh} to open a connection. This is useful for users |
904 where the normal login shell is set up to ask them a number of | 823 where the normal login shell is set up to ask them a number of |
905 questions when logging in. This procedure avoids these questions, and | 824 questions when logging in. This procedure avoids these questions, and |
906 just gives @tramp{} a more-or-less `standard' login shell to work | 825 just gives @value{tramp} a more-or-less `standard' login shell to work |
907 with. | 826 with. |
908 | 827 |
909 This is also useful for Windows users where @command{ssh}, when | 828 This is also useful for Windows users where @command{ssh}, when |
910 invoked from an Emacs buffer, tells them that it is not allocating a | 829 invoked from an @value{emacsname} buffer, tells them that it is not |
911 pseudo tty. When this happens, the login shell is wont to not print | 830 allocating a pseudo tty. When this happens, the login shell is wont |
912 any shell prompt, which confuses @tramp{} mightily. Maybe this | 831 to not print any shell prompt, which confuses @value{tramp} mightily. |
913 applies to the Cygwin port of SSH. | |
914 | 832 |
915 This method supports the @samp{-p} hack. | 833 This method supports the @samp{-p} hack. |
916 | 834 |
917 | 835 |
918 @item @option{pscp} --- @command{plink} and @command{pscp} | 836 @item @option{pscp} --- @command{plink} and @command{pscp} |
949 /bin/sh -i} to establish the connection, it does not work to just say | 867 /bin/sh -i} to establish the connection, it does not work to just say |
950 @command{fsh @var{host} -l @var{user}}. | 868 @command{fsh @var{host} -l @var{user}}. |
951 | 869 |
952 @cindex method fsh | 870 @cindex method fsh |
953 @cindex fsh method | 871 @cindex fsh method |
872 | |
954 There is no inline method using @command{fsh} as the multiplexing | 873 There is no inline method using @command{fsh} as the multiplexing |
955 provided by the program is not very useful in our context. @tramp{} | 874 provided by the program is not very useful in our context. @value{tramp} |
956 opens just one connection to the remote host and then keeps it open, | 875 opens just one connection to the remote host and then keeps it open, |
957 anyway. | 876 anyway. |
958 | 877 |
959 | 878 |
960 @ifset emacs | |
961 @item @option{ftp} | 879 @item @option{ftp} |
962 @cindex method ftp | 880 @cindex method ftp |
963 @cindex ftp method | 881 @cindex ftp method |
964 | 882 |
965 This is not a native @tramp{} method. Instead of, it forwards all | 883 This is not a native @value{tramp} method. Instead of, it forwards all |
966 requests to @value{ftp-package-name}. | 884 requests to @value{ftppackagename}. |
885 @ifset xemacs | |
886 This works only for unified filenames, see @ref{Issues}. | |
967 @end ifset | 887 @end ifset |
968 | 888 |
969 | 889 |
970 @item @option{smb} --- @command{smbclient} | 890 @item @option{smb} --- @command{smbclient} |
971 @cindex method smb | 891 @cindex method smb |
972 @cindex smb method | 892 @cindex smb method |
973 | 893 |
974 This is another not natural @tramp{} method. It uses the | 894 This is another not natural @value{tramp} method. It uses the |
975 @command{smbclient} command on different Unices in order to connect to | 895 @command{smbclient} command on different Unices in order to connect to |
976 an SMB server. An SMB server might be a Samba (or CIFS) server on | 896 an SMB server. An SMB server might be a Samba (or CIFS) server on |
977 another UNIX host or, more interesting, a host running MS Windows. So | 897 another UNIX host or, more interesting, a host running MS Windows. So |
978 far, it is tested towards MS Windows NT, MS Windows 2000, and MS | 898 far, it is tested towards MS Windows NT, MS Windows 2000, and MS |
979 Windows XP. | 899 Windows XP. |
980 | 900 |
981 The first directory in the path must be a share name on the remote | 901 The first directory in the localname must be a share name on the remote |
982 host. Remember, that the @code{$} character in which default shares | 902 host. Remember, that the @code{$} character in which default shares |
983 usually end, must be written @code{$$} due to environment variable | 903 usually end, must be written @code{$$} due to environment variable |
984 substitution in file names. If no share name is given (i.e. remote | 904 substitution in file names. If no share name is given (i.e. remote |
985 directory @code{/}), all available shares are listed. | 905 directory @code{/}), all available shares are listed. |
986 | 906 |
987 Since authorization is done on share level, you will be prompted | 907 Since authorization is done on share level, you will be prompted |
988 always for a password if you access another share on the same host. | 908 always for a password if you access another share on the same host. |
989 Due to security reasons, the password is not cached. | 909 This can be suppressed by @ref{Password caching}. |
990 | 910 |
991 MS Windows uses for authorization both a user name and a domain name. | 911 MS Windows uses for authorization both a user name and a domain name. |
992 Because of this, the @tramp{} syntax has been extended: you can | 912 Because of this, the @value{tramp} syntax has been extended: you can |
993 specify a user name which looks like @code{user%domain} (the real user | 913 specify a user name which looks like @code{user%domain} (the real user |
994 name, then a percent sign, then the domain name). So, to connect to | 914 name, then a percent sign, then the domain name). So, to connect to |
995 the machine @code{melancholia} as user @code{daniel} of the domain | 915 the machine @code{melancholia} as user @code{daniel} of the domain |
996 @code{BIZARRE}, and edit @file{.emacs} in the home directory (share | 916 @code{BIZARRE}, and edit @file{.emacs} in the home directory (share |
997 @code{daniel$}) I would specify the filename | 917 @code{daniel$}) I would specify the filename |
998 @file{@value{tramp-prefix}smb@value{tramp-postfix-single-hop}daniel%BIZARRE@@melancholia@value{tramp-postfix}/daniel$$/.emacs}. | 918 @file{@value{prefix}smb@value{postfixsinglehop}daniel%BIZARRE@@melancholia@value{postfix}/daniel$$/.emacs}. |
999 | 919 |
1000 The domain name as well as the user name are optional. If no user | 920 The domain name as well as the user name are optional. If no user |
1001 name is specified at all, the anonymous user (without password | 921 name is specified at all, the anonymous user (without password |
1002 prompting) is assumed. This is different from all other @tramp{} | 922 prompting) is assumed. This is different from all other @value{tramp} |
1003 methods, where in such a case the local user name is taken. | 923 methods, where in such a case the local user name is taken. |
1004 | 924 |
1005 The @option{smb} method supports the @samp{-p} hack. | 925 The @option{smb} method supports the @samp{-p} hack. |
1006 | 926 |
1007 @strong{Please note:} If Emacs runs locally under MS Windows, this | 927 @strong{Please note:} If @value{emacsname} runs locally under MS |
1008 method isn't available. Instead of, you can use UNC file names like | 928 Windows, this method isn't available. Instead of, you can use UNC |
1009 @file{//melancholia/daniel$$/.emacs}. The only disadvantage is that | 929 file names like @file{//melancholia/daniel$$/.emacs}. The only |
1010 there's no possiblity to specify another user name. | 930 disadvantage is that there's no possibility to specify another user |
931 name. | |
1011 | 932 |
1012 @end table | 933 @end table |
1013 | 934 |
1014 @node Multi-hop Methods | 935 @node Multi-hop Methods |
1015 @section Connecting to a remote host using multiple hops | 936 @section Connecting to a remote host using multiple hops |
1020 it is not possible to connect to a remote host using a simple command. | 941 it is not possible to connect to a remote host using a simple command. |
1021 For example, if you are in a secured network, you might have to log in | 942 For example, if you are in a secured network, you might have to log in |
1022 to a `bastion host' first before you can connect to the outside world. | 943 to a `bastion host' first before you can connect to the outside world. |
1023 Of course, the target host may also require a bastion host. The format | 944 Of course, the target host may also require a bastion host. The format |
1024 of multi-hop filenames is slightly different than the format of normal | 945 of multi-hop filenames is slightly different than the format of normal |
1025 @tramp{} methods. | 946 @value{tramp} methods. |
1026 | 947 |
1027 @cindex method multi | 948 @cindex method multi |
1028 @cindex multi method | 949 @cindex multi method |
1029 A multi-hop file name specifies a method, a number of hops, and a path | 950 A multi-hop file name specifies a method, a number of hops, and a |
1030 name on the remote system. The method name is always | 951 localname (path name on the remote system). The method name is always |
1031 @option{multi}. | 952 @option{multi}. |
1032 | 953 |
1033 Each hop consists of a @dfn{hop method} specification, a user name and | 954 Each hop consists of a @dfn{hop method} specification, a user name and |
1034 a host name. The hop method can be an inline method only. The | 955 a host name. The hop method can be an inline method only. The |
1035 following hop methods are (currently) available: | 956 following hop methods are (currently) available: |
1047 @cindex hop method rsh | 968 @cindex hop method rsh |
1048 @cindex rsh hop method | 969 @cindex rsh hop method |
1049 | 970 |
1050 This uses @command{rsh} to connect to the host. You do not need to | 971 This uses @command{rsh} to connect to the host. You do not need to |
1051 enter a password unless @command{rsh} explicitly asks for it. | 972 enter a password unless @command{rsh} explicitly asks for it. |
973 | |
974 The variant @option{remsh} uses the @command{remsh} command. It | |
975 should be applied on machines where @command{remsh} is used instead of | |
976 @command{rsh}. | |
1052 | 977 |
1053 @item ssh | 978 @item ssh |
1054 @cindex hop method ssh | 979 @cindex hop method ssh |
1055 @cindex ssh hop method | 980 @cindex ssh hop method |
1056 | 981 |
1085 | 1010 |
1086 Some people might wish to use port forwarding with @command{ssh} or | 1011 Some people might wish to use port forwarding with @command{ssh} or |
1087 maybe they have to use a nonstandard port. This can be accomplished | 1012 maybe they have to use a nonstandard port. This can be accomplished |
1088 by putting a stanza in @file{~/.ssh/config} for the account which | 1013 by putting a stanza in @file{~/.ssh/config} for the account which |
1089 specifies a different port number for a certain host name. But it can | 1014 specifies a different port number for a certain host name. But it can |
1090 also be accomplished within @tramp{}, by adding a multi-hop method. | 1015 also be accomplished within @value{tramp}, by adding a multi-hop method. |
1091 For example: | 1016 For example: |
1092 | 1017 |
1093 @lisp | 1018 @lisp |
1094 (add-to-list | 1019 (add-to-list |
1095 'tramp-multi-connection-function-alist | 1020 'tramp-multi-connection-function-alist |
1096 '("sshf" tramp-multi-connect-rlogin "ssh %h -l %u -p 4400%n")) | 1021 '("sshf" tramp-multi-connect-rlogin "ssh %h -l %u -p 4400%n")) |
1097 @end lisp | 1022 @end lisp |
1098 | 1023 |
1099 Now you can use an @code{sshf} hop which connects to port 4400 instead of | 1024 Now you can use an @option{sshf} hop which connects to port 4400 instead of |
1100 the standard port. | 1025 the standard port. |
1101 | 1026 |
1102 | 1027 |
1103 @node Default Method | 1028 @node Default Method |
1104 @section Selecting a default method | 1029 @section Selecting a default method |
1105 @cindex default method | 1030 @cindex default method |
1106 | 1031 |
1107 @vindex tramp-default-method | 1032 @vindex tramp-default-method |
1108 When you select an appropriate transfer method for your typical usage | 1033 When you select an appropriate transfer method for your typical usage |
1109 you should set the variable @var{tramp-default-method} to reflect that | 1034 you should set the variable @code{tramp-default-method} to reflect that |
1110 choice. This variable controls which method will be used when a method | 1035 choice. This variable controls which method will be used when a method |
1111 is not specified in the @tramp{} file path. For example: | 1036 is not specified in the @value{tramp} file name. For example: |
1112 | 1037 |
1113 @lisp | 1038 @lisp |
1114 (setq tramp-default-method "scp") | 1039 (setq tramp-default-method "scp") |
1115 @end lisp | 1040 @end lisp |
1116 | 1041 |
1117 @vindex tramp-default-method-alist | 1042 @vindex tramp-default-method-alist |
1118 You can also specify different methods for certain user/host | 1043 You can also specify different methods for certain user/host |
1119 combinations, via the variable @var{tramp-default-method-alist}. For | 1044 combinations, via the variable @code{tramp-default-method-alist}. For |
1120 example, the following two lines specify to use the @option{ssh} | 1045 example, the following two lines specify to use the @option{ssh} |
1121 method for all user names matching @samp{john} and the @option{rsync} | 1046 method for all user names matching @samp{john} and the @option{rsync} |
1122 method for all host names matching @samp{lily}. The third line | 1047 method for all host names matching @samp{lily}. The third line |
1123 specifies to use the @option{su} method for the user @samp{root} on | 1048 specifies to use the @option{su} method for the user @samp{root} on |
1124 the machine @samp{localhost}. | 1049 the machine @samp{localhost}. |
1130 '("\\`localhost\\'" "\\`root\\'" "su")) | 1055 '("\\`localhost\\'" "\\`root\\'" "su")) |
1131 @end lisp | 1056 @end lisp |
1132 | 1057 |
1133 @noindent | 1058 @noindent |
1134 See the documentation for the variable | 1059 See the documentation for the variable |
1135 @var{tramp-default-method-alist} for more details. | 1060 @code{tramp-default-method-alist} for more details. |
1136 | 1061 |
1137 External transfer methods are normally preferable to inline transfer | 1062 External transfer methods are normally preferable to inline transfer |
1138 methods, giving better performance. They may not be useful if you use | 1063 methods, giving better performance. |
1139 many remote machines where you cannot log in without a password. | |
1140 | 1064 |
1141 @xref{Inline methods}. | 1065 @xref{Inline methods}. |
1142 @xref{External transfer methods}. | 1066 @xref{External transfer methods}. |
1143 @xref{Multi-hop Methods}. | 1067 @xref{Multi-hop Methods}. |
1144 | 1068 |
1145 Another consideration with the selection of transfer methods is the | 1069 Another consideration with the selection of transfer methods is the |
1146 environment you will use them in and, especially when used over the | 1070 environment you will use them in and, especially when used over the |
1147 Internet, the security implications of your preferred method. | 1071 Internet, the security implications of your preferred method. |
1148 | 1072 |
1149 The @command{rsh} and @command{telnet} methods send your password as | 1073 The @option{rsh} and @option{telnet} methods send your password as |
1150 plain text as you log in to the remote machine, as well as transferring | 1074 plain text as you log in to the remote machine, as well as |
1151 the files in such a way that the content can easily be read from other | 1075 transferring the files in such a way that the content can easily be |
1152 machines. | 1076 read from other machines. |
1153 | 1077 |
1154 If you need to connect to remote systems that are accessible from the | 1078 If you need to connect to remote systems that are accessible from the |
1155 Internet, you should give serious thought to using @command{ssh} based | 1079 Internet, you should give serious thought to using @option{ssh} based |
1156 methods to connect. These provide a much higher level of security, | 1080 methods to connect. These provide a much higher level of security, |
1157 making it a non-trivial exercise for someone to obtain your password or | 1081 making it a non-trivial exercise for someone to obtain your password |
1158 read the content of the files you are editing. | 1082 or read the content of the files you are editing. |
1083 | |
1084 | |
1085 @subsection Which method is the right one for me? | |
1086 @cindex choosing the right method | |
1087 | |
1088 Given all of the above, you are probably thinking that this is all fine | |
1089 and good, but it's not helping you to choose a method! Right you are. | |
1090 As a developer, we don't want to boss our users around but give them | |
1091 maximum freedom instead. However, the reality is that some users would | |
1092 like to have some guidance, so here I'll try to give you this guidance | |
1093 without bossing you around. You tell me whether it works @dots{} | |
1094 | |
1095 My suggestion is to use an inline method. For large files, out-of-band | |
1096 methods might be more efficient, but I guess that most people will want | |
1097 to edit mostly small files. | |
1098 | |
1099 I guess that these days, most people can access a remote machine by | |
1100 using @command{ssh}. So I suggest that you use the @option{ssh} | |
1101 method. So, type @kbd{C-x C-f | |
1102 @value{prefix}ssh@value{postfixsinglehop}root@@otherhost@value{postfix}/etc/motd | |
1103 @key{RET}} to edit the @file{/etc/motd} file on the other host. | |
1104 | |
1105 If you can't use @option{ssh} to log in to the remote host, then | |
1106 select a method that uses a program that works. For instance, Windows | |
1107 users might like the @option{plink} method which uses the PuTTY | |
1108 implementation of @command{ssh}. Or you use Kerberos and thus like | |
1109 @option{krlogin}. | |
1110 | |
1111 For the special case of editing files on the local host as another | |
1112 user, see the @option{su} or @option{sudo} methods. They offer | |
1113 shortened syntax for the @samp{root} account, like | |
1114 @file{@value{prefix}su@value{postfixsinglehop}@value{postfix}/etc/motd}. | |
1115 | |
1116 People who edit large files may want to consider @option{scp} instead | |
1117 of @option{ssh}, or @option{pscp} instead of @option{plink}. These | |
1118 out-of-band methods are faster than inline methods for large files. | |
1119 Note, however, that out-of-band methods suffer from some limitations. | |
1120 Please try first whether you really get a noticeable speed advantage | |
1121 from using an out-of-band method! Maybe even for large files, inline | |
1122 methods are fast enough. | |
1123 | |
1159 | 1124 |
1160 @node Customizing Methods | 1125 @node Customizing Methods |
1161 @section Using Non-Standard Methods | 1126 @section Using Non-Standard Methods |
1162 @cindex customizing methods | 1127 @cindex customizing methods |
1163 @cindex using non-standard methods | 1128 @cindex using non-standard methods |
1233 in such files, it can return host names only. | 1198 in such files, it can return host names only. |
1234 | 1199 |
1235 @item @code{tramp-parse-sconfig} | 1200 @item @code{tramp-parse-sconfig} |
1236 @findex tramp-parse-shosts | 1201 @findex tramp-parse-shosts |
1237 | 1202 |
1238 This function returns the host nicnames defined by @code{Host} entries | 1203 This function returns the host nicknames defined by @code{Host} entries |
1239 in @file{~/.ssh/config} style files. | 1204 in @file{~/.ssh/config} style files. |
1205 | |
1206 @item @code{tramp-parse-shostkeys} | |
1207 @findex tramp-parse-shostkeys | |
1208 | |
1209 SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and | |
1210 @file{~/ssh2/hostkeys/*}. Hosts are coded in file names | |
1211 @file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names | |
1212 are always @code{nil}. | |
1213 | |
1214 @item @code{tramp-parse-sknownhosts} | |
1215 @findex tramp-parse-shostkeys | |
1216 | |
1217 Another SSH2 style parsing of directories like | |
1218 @file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This | |
1219 case, hosts names are coded in file names | |
1220 @file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}. | |
1240 | 1221 |
1241 @item @code{tramp-parse-hosts} | 1222 @item @code{tramp-parse-hosts} |
1242 @findex tramp-parse-hosts | 1223 @findex tramp-parse-hosts |
1243 | 1224 |
1244 A function dedicated to @file{/etc/hosts} style files. It returns | 1225 A function dedicated to @file{/etc/hosts} style files. It returns |
1272 @result{} ((nil "toto") ("daniel" "melancholia")) | 1253 @result{} ((nil "toto") ("daniel" "melancholia")) |
1273 @end example | 1254 @end example |
1274 @end defun | 1255 @end defun |
1275 | 1256 |
1276 | 1257 |
1258 @node Password caching | |
1259 @section Reusing passwords for several connections. | |
1260 @cindex passwords | |
1261 | |
1262 Sometimes it is necessary to connect to the same remote host several | |
1263 times. Reentering passwords again and again would be annoying, when | |
1264 the choosen method does not support access without password prompt | |
1265 throught own configuration. | |
1266 | |
1267 By default, @value{tramp} caches the passwords entered by you. They will | |
1268 be reused next time if a connection needs them for the same user name | |
1269 and host name, independant of the connection method. | |
1270 | |
1271 @vindex password-cache-expiry | |
1272 Passwords are not saved permanently, that means the password caching | |
1273 is limited to the lifetime of your @value{emacsname} session. You | |
1274 can influence the lifetime of password caching by customizing the | |
1275 variable @code{password-cache-expiry}. The value is the number of | |
1276 seconds how long passwords are cached. Setting it to @code{nil} | |
1277 disables the expiration. | |
1278 | |
1279 @findex tramp-clear-passwd | |
1280 A password is removed from the cache if a connection isn't established | |
1281 successfully. You can remove a password from the cache also by | |
1282 executing @kbd{M-x tramp-clear-passwd} in a buffer containing a | |
1283 related remote file or directory. | |
1284 | |
1285 @vindex password-cache | |
1286 If you don't like this feature for security reasons, password caching | |
1287 can be disabled totally by customizing the variable | |
1288 @code{password-cache} (setting it to @code{nil}). | |
1289 | |
1290 Implementation Note: password caching is based on the package | |
1291 password.el in No Gnus. For the time being, it is activated only when | |
1292 this package is seen in the @code{load-path} while loading @value{tramp}. | |
1293 @ifset installchapter | |
1294 If you don't use No Gnus, you can take password.el from the @value{tramp} | |
1295 @file{contrib} directory, see @ref{Installation parameters}. | |
1296 @end ifset | |
1297 It will be activated mandatory once No Gnus has found its way into | |
1298 @value{emacsname}. | |
1299 | |
1300 | |
1277 @node Remote Programs | 1301 @node Remote Programs |
1278 @section How @tramp{} finds and uses programs on the remote machine. | 1302 @section How @value{tramp} finds and uses programs on the remote machine. |
1279 | 1303 |
1280 @tramp{} depends on a number of programs on the remote host in order to | 1304 @value{tramp} depends on a number of programs on the remote host in order to |
1281 function, including @command{ls}, @command{test}, @command{find} and | 1305 function, including @command{ls}, @command{test}, @command{find} and |
1282 @command{cat}. | 1306 @command{cat}. |
1283 | 1307 |
1284 In addition to these required tools, there are various tools that may be | 1308 In addition to these required tools, there are various tools that may be |
1285 required based on the connection method. See @ref{Inline methods} and | 1309 required based on the connection method. See @ref{Inline methods} and |
1289 @command{grep} will be used if they can be found. When they are | 1313 @command{grep} will be used if they can be found. When they are |
1290 available, they are used to improve the performance and accuracy of | 1314 available, they are used to improve the performance and accuracy of |
1291 remote file access. | 1315 remote file access. |
1292 | 1316 |
1293 @vindex tramp-remote-path | 1317 @vindex tramp-remote-path |
1294 When @tramp{} connects to the remote machine, it searches for the | 1318 When @value{tramp} connects to the remote machine, it searches for the |
1295 programs that it can use. The variable @var{tramp-remote-path} controls | 1319 programs that it can use. The variable @var{tramp-remote-path} controls |
1296 the directories searched on the remote machine. | 1320 the directories searched on the remote machine. |
1297 | 1321 |
1298 By default, this is set to a reasonable set of defaults for most | 1322 By default, this is set to a reasonable set of defaults for most |
1299 machines. It is possible, however, that your local (or remote ;) system | 1323 machines. It is possible, however, that your local (or remote ;) system |
1300 administrator has put the tools you want in some obscure local | 1324 administrator has put the tools you want in some obscure local |
1301 directory. | 1325 directory. |
1302 | 1326 |
1303 In this case, you can still use them with @tramp{}. You simply need to | 1327 In this case, you can still use them with @value{tramp}. You simply need to |
1304 add code to your @file{.emacs} to add the directory to the remote path. | 1328 add code to your @file{.emacs} to add the directory to the remote path. |
1305 This will then be searched by @tramp{} when you connect and the software | 1329 This will then be searched by @value{tramp} when you connect and the software |
1306 found. | 1330 found. |
1307 | 1331 |
1308 To add a directory to the remote search path, you could use code such | 1332 To add a directory to the remote search path, you could use code such |
1309 as: | 1333 as: |
1310 | 1334 |
1311 @lisp | 1335 @lisp |
1312 @i{;; We load @tramp{} to define the variable.} | 1336 @i{;; We load @value{tramp} to define the variable.} |
1313 (require 'tramp) | 1337 (require 'tramp) |
1314 @i{;; We have @command{perl} in "/usr/local/perl/bin"} | 1338 @i{;; We have @command{perl} in "/usr/local/perl/bin"} |
1315 (add-to-list 'tramp-remote-path "/usr/local/perl/bin") | 1339 (add-to-list 'tramp-remote-path "/usr/local/perl/bin") |
1316 @end lisp | 1340 @end lisp |
1317 | 1341 |
1322 @cindex remote shell setup | 1346 @cindex remote shell setup |
1323 @cindex @file{.profile} file | 1347 @cindex @file{.profile} file |
1324 @cindex @file{.login} file | 1348 @cindex @file{.login} file |
1325 @cindex shell init files | 1349 @cindex shell init files |
1326 | 1350 |
1327 As explained in the @ref{Overview} section, @tramp{} connects to the | 1351 As explained in the @ref{Overview} section, @value{tramp} connects to the |
1328 remote host and talks to the shell it finds there. Of course, when you | 1352 remote host and talks to the shell it finds there. Of course, when you |
1329 log in, the shell executes its init files. Suppose your init file | 1353 log in, the shell executes its init files. Suppose your init file |
1330 requires you to enter the birth date of your mother; clearly @tramp{} | 1354 requires you to enter the birth date of your mother; clearly @value{tramp} |
1331 does not know this and hence fails to log you in to that host. | 1355 does not know this and hence fails to log you in to that host. |
1332 | 1356 |
1333 There are different possible strategies for pursuing this problem. One | 1357 There are different possible strategies for pursuing this problem. One |
1334 strategy is to enable @tramp{} to deal with all possible situations. | 1358 strategy is to enable @value{tramp} to deal with all possible situations. |
1335 This is a losing battle, since it is not possible to deal with | 1359 This is a losing battle, since it is not possible to deal with |
1336 @emph{all} situations. The other strategy is to require you to set up | 1360 @emph{all} situations. The other strategy is to require you to set up |
1337 the remote host such that it behaves like @tramp{} expect. This might | 1361 the remote host such that it behaves like @value{tramp} expects. This might |
1338 be inconvenient because you have to invest a lot of effort into shell | 1362 be inconvenient because you have to invest a lot of effort into shell |
1339 setup before you can begin to use @tramp{}. | 1363 setup before you can begin to use @value{tramp}. |
1340 | 1364 |
1341 The package, therefore, pursues a combined approach. It tries to figure | 1365 The package, therefore, pursues a combined approach. It tries to |
1342 out some of the more common setups, and only requires you to avoid | 1366 figure out some of the more common setups, and only requires you to |
1343 really exotic stuff. For example, it looks through a list of | 1367 avoid really exotic stuff. For example, it looks through a list of |
1344 directories to find some programs on the remote host. And also, it | 1368 directories to find some programs on the remote host. And also, it |
1345 knows that it is not obvious how to check whether a file exists, and | 1369 knows that it is not obvious how to check whether a file exists, and |
1346 therefore it tries different possibilities. (On some hosts and shells, | 1370 therefore it tries different possibilities. (On some hosts and |
1347 the command @code{test -e} does the trick, on some hosts the shell | 1371 shells, the command @command{test -e} does the trick, on some hosts |
1348 builtin doesn't work but the program @code{/usr/bin/test -e} or | 1372 the shell builtin doesn't work but the program @command{/usr/bin/test |
1349 @code{/bin/test -e} works. And on still other hosts, @code{ls -d} is | 1373 -e} or @command{/bin/test -e} works. And on still other hosts, |
1350 the right way to do this.) | 1374 @command{ls -d} is the right way to do this.) |
1351 | 1375 |
1352 Below you find a discussion of a few things that @tramp{} does not deal | 1376 Below you find a discussion of a few things that @value{tramp} does not deal |
1353 with, and that you therefore have to set up correctly. | 1377 with, and that you therefore have to set up correctly. |
1354 | 1378 |
1355 @table @asis | 1379 @table @asis |
1356 @item @var{shell-prompt-pattern} | 1380 @item @var{shell-prompt-pattern} |
1357 @vindex shell-prompt-pattern | 1381 @vindex shell-prompt-pattern |
1358 | 1382 |
1359 After logging in to the remote host, @tramp{} has to wait for the remote | 1383 After logging in to the remote host, @value{tramp} has to wait for the remote |
1360 shell startup to finish before it can send commands to the remote | 1384 shell startup to finish before it can send commands to the remote |
1361 shell. The strategy here is to wait for the shell prompt. In order to | 1385 shell. The strategy here is to wait for the shell prompt. In order to |
1362 recognize the shell prompt, the variable @code{shell-prompt-pattern} has | 1386 recognize the shell prompt, the variable @code{shell-prompt-pattern} has |
1363 to be set correctly to recognize the shell prompt on the remote host. | 1387 to be set correctly to recognize the shell prompt on the remote host. |
1364 | 1388 |
1365 Note that @tramp{} requires the match for @code{shell-prompt-pattern} | 1389 Note that @value{tramp} requires the match for @code{shell-prompt-pattern} |
1366 to be at the end of the buffer. Many people have something like the | 1390 to be at the end of the buffer. Many people have something like the |
1367 following as the value for the variable: @code{"^[^>$][>$] *"}. Now | 1391 following as the value for the variable: @code{"^[^>$][>$] *"}. Now |
1368 suppose your shell prompt is @code{a <b> c $ }. In this case, | 1392 suppose your shell prompt is @code{a <b> c $ }. In this case, |
1369 @tramp{} recognizes the @code{>} character as the end of the prompt, | 1393 @value{tramp} recognizes the @code{>} character as the end of the prompt, |
1370 but it is not at the end of the buffer. | 1394 but it is not at the end of the buffer. |
1371 | 1395 |
1372 @item @var{tramp-shell-prompt-pattern} | 1396 @item @var{tramp-shell-prompt-pattern} |
1373 @vindex tramp-shell-prompt-pattern | 1397 @vindex tramp-shell-prompt-pattern |
1374 | 1398 |
1375 This regular expression is used by @tramp{} in the same way as | 1399 This regular expression is used by @value{tramp} in the same way as |
1376 @code{shell-prompt-pattern}, to match prompts from the remote shell. | 1400 @code{shell-prompt-pattern}, to match prompts from the remote shell. |
1377 This second variable exists because the prompt from the remote shell | 1401 This second variable exists because the prompt from the remote shell |
1378 might be different from the prompt from a local shell --- after all, | 1402 might be different from the prompt from a local shell --- after all, |
1379 the whole point of @tramp{} is to log in to remote hosts as a | 1403 the whole point of @value{tramp} is to log in to remote hosts as a |
1380 different user. The default value of | 1404 different user. The default value of |
1381 @code{tramp-shell-prompt-pattern} is the same as the default value of | 1405 @code{tramp-shell-prompt-pattern} is the same as the default value of |
1382 @code{shell-prompt-pattern}, which is reported to work well in many | 1406 @code{shell-prompt-pattern}, which is reported to work well in many |
1383 circumstances. | 1407 circumstances. |
1384 | 1408 |
1385 @item @code{tset} and other questions | 1409 @item @command{tset} and other questions |
1386 @cindex Unix command tset | 1410 @cindex Unix command tset |
1387 @cindex tset Unix command | 1411 @cindex tset Unix command |
1388 | 1412 |
1389 Some people invoke the @code{tset} program from their shell startup | 1413 Some people invoke the @command{tset} program from their shell startup |
1390 scripts which asks the user about the terminal type of the shell. | 1414 scripts which asks the user about the terminal type of the shell. |
1391 Maybe some shells ask other questions when they are started. @tramp{} | 1415 Maybe some shells ask other questions when they are started. @value{tramp} |
1392 does not know how to answer these questions. There are two approaches | 1416 does not know how to answer these questions. There are two approaches |
1393 for dealing with this problem. One approach is to take care that the | 1417 for dealing with this problem. One approach is to take care that the |
1394 shell does not ask any questions when invoked from @tramp{}. You can | 1418 shell does not ask any questions when invoked from @value{tramp}. You can |
1395 do this by checking the @code{TERM} environment variable, it will be | 1419 do this by checking the @code{TERM} environment variable, it will be |
1396 set to @code{dumb} when connecting. | 1420 set to @code{dumb} when connecting. |
1397 | 1421 |
1398 @vindex tramp-terminal-type | 1422 @vindex tramp-terminal-type |
1399 The variable @code{tramp-terminal-type} can be used to change this value | 1423 The variable @code{tramp-terminal-type} can be used to change this value |
1400 to @code{dumb}. | 1424 to @code{dumb}. |
1401 | 1425 |
1402 The other approach is to teach @tramp{} about these questions. See | 1426 The other approach is to teach @value{tramp} about these questions. See |
1403 the variables @code{tramp-actions-before-shell} and | 1427 the variables @code{tramp-actions-before-shell} and |
1404 @code{tramp-multi-actions} (for multi-hop connections). | 1428 @code{tramp-multi-actions} (for multi-hop connections). |
1405 | 1429 |
1430 | |
1431 @item Environment variables named like users in @file{.profile} | |
1432 | |
1433 If you have a user named frumple and set the variable @code{FRUMPLE} in | |
1434 your shell environment, then this might cause trouble. Maybe rename | |
1435 the variable to @code{FRUMPLE_DIR} or the like. | |
1436 | |
1437 This weird effect was actually reported by a @value{tramp} user! | |
1438 | |
1439 | |
1440 @item Non-Bourne commands in @file{.profile} | |
1441 | |
1442 After logging in to the remote host, @value{tramp} issues the command | |
1443 @command{exec /bin/sh}. (Actually, the command is slightly | |
1444 different.) When @command{/bin/sh} is executed, it reads some init | |
1445 files, such as @file{~/.shrc} or @file{~/.profile}. | |
1446 | |
1447 Now, some people have a login shell which is not @code{/bin/sh} but a | |
1448 Bourne-ish shell such as bash or ksh. Some of these people might put | |
1449 their shell setup into the files @file{~/.shrc} or @file{~/.profile}. | |
1450 This way, it is possible for non-Bourne constructs to end up in those | |
1451 files. Then, @command{exec /bin/sh} might cause the Bourne shell to | |
1452 barf on those constructs. | |
1453 | |
1454 As an example, imagine somebody putting @command{export FOO=bar} into | |
1455 the file @file{~/.profile}. The standard Bourne shell does not | |
1456 understand this syntax and will emit a syntax error when it reaches | |
1457 this line. | |
1458 | |
1459 Another example is the tilde (@code{~}) character, say when adding | |
1460 @file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this | |
1461 character, and since there is usually no directory whose name consists | |
1462 of the single character tilde, strange things will happen. | |
1463 | |
1464 What can you do about this? | |
1465 | |
1466 Well, one possibility is to make sure that everything in @file{~/.shrc} | |
1467 and @file{~/.profile} on all remote hosts is Bourne-compatible. In the | |
1468 above example, instead of @command{export FOO=bar}, you might use | |
1469 @command{FOO=bar; export FOO} instead. | |
1470 | |
1471 The other possibility is to put your non-Bourne shell setup into some | |
1472 other files. For example, bash reads the file @file{~/.bash_profile} | |
1473 instead of @file{~/.profile}, if the former exists. So bash | |
1474 aficionados just rename their @file{~/.profile} to | |
1475 @file{~/.bash_profile} on all remote hosts, and Bob's your uncle. | |
1476 | |
1477 The @value{tramp} developers would like to circumvent this problem, so | |
1478 if you have an idea about it, please tell us. However, we are afraid | |
1479 it is not that simple: before saying @command{exec /bin/sh}, | |
1480 @value{tramp} does not know which kind of shell it might be talking | |
1481 to. It could be a Bourne-ish shell like ksh or bash, or it could be a | |
1482 csh derivative like tcsh, or it could be zsh, or even rc. If the | |
1483 shell is Bourne-ish already, then it might be prudent to omit the | |
1484 @command{exec /bin/sh} step. But how to find out if the shell is | |
1485 Bourne-ish? | |
1486 | |
1406 @end table | 1487 @end table |
1488 | |
1489 | |
1490 @node Auto-save and Backup | |
1491 @section Auto-save and Backup configuration | |
1492 @cindex auto-save | |
1493 @cindex backup | |
1494 @ifset emacs | |
1495 @vindex backup-directory-alist | |
1496 @end ifset | |
1497 @ifset xemacs | |
1498 @vindex bkup-backup-directory-info | |
1499 @end ifset | |
1500 | |
1501 Normally, @value{emacsname} writes backup files to the same directory | |
1502 as the original files, but this behavior can be changed via the | |
1503 variable | |
1504 @ifset emacs | |
1505 @code{backup-directory-alist}. | |
1506 @end ifset | |
1507 @ifset xemacs | |
1508 @code{bkup-backup-directory-info}. | |
1509 @end ifset | |
1510 In connection with @value{tramp}, this can have unexpected side effects. | |
1511 Suppose that you specify that all backups should go to the directory | |
1512 @file{~/.emacs.d/backups/}, and then you edit the file | |
1513 @file{@value{prefix}su@value{postfixsinglehop}root@@localhost@value{postfix}/etc/secretfile}. | |
1514 The effect is that the backup file will be owned by you and not by | |
1515 root, thus possibly enabling others to see it even if they were not | |
1516 intended to see it. | |
1517 | |
1518 When | |
1519 @ifset emacs | |
1520 @code{backup-directory-alist} | |
1521 @end ifset | |
1522 @ifset xemacs | |
1523 @code{bkup-backup-directory-info} | |
1524 @end ifset | |
1525 is @code{nil} (the default), such problems do not occur. | |
1526 | |
1527 Therefore, it is usefull to set special values for @value{tramp} | |
1528 files. For example, the following statement effectively `turns off' | |
1529 the effect of | |
1530 @ifset emacs | |
1531 @code{backup-directory-alist} | |
1532 @end ifset | |
1533 @ifset xemacs | |
1534 @code{bkup-backup-directory-info} | |
1535 @end ifset | |
1536 for @value{tramp} files: | |
1537 | |
1538 @ifset emacs | |
1539 @lisp | |
1540 (add-to-list 'backup-directory-alist | |
1541 (cons tramp-file-name-regexp nil)) | |
1542 @end lisp | |
1543 @end ifset | |
1544 @ifset xemacs | |
1545 @lisp | |
1546 (require 'backup-dir) | |
1547 (add-to-list 'bkup-backup-directory-info | |
1548 (list tramp-file-name-regexp "")) | |
1549 @end lisp | |
1550 @end ifset | |
1551 | |
1552 Another possibility is to use the @value{tramp} variable | |
1553 @ifset emacs | |
1554 @code{tramp-backup-directory-alist}. | |
1555 @end ifset | |
1556 @ifset xemacs | |
1557 @code{tramp-bkup-backup-directory-info}. | |
1558 @end ifset | |
1559 This variable has the same meaning like | |
1560 @ifset emacs | |
1561 @code{backup-directory-alist}. | |
1562 @end ifset | |
1563 @ifset xemacs | |
1564 @code{bkup-backup-directory-info}. | |
1565 @end ifset | |
1566 If a @value{tramp} file is backed up, and DIRECTORY is an absolute | |
1567 local file name, DIRECTORY is prepended with the @value{tramp} file | |
1568 name prefix of the file to be backed up. | |
1569 | |
1570 @noindent | |
1571 Example: | |
1572 | |
1573 @ifset emacs | |
1574 @lisp | |
1575 (add-to-list 'backup-directory-alist | |
1576 (cons "." "~/.emacs.d/backups/")) | |
1577 (setq tramp-backup-directory-alist backup-directory-alist) | |
1578 @end lisp | |
1579 @end ifset | |
1580 @ifset xemacs | |
1581 @lisp | |
1582 (require 'backup-dir) | |
1583 (add-to-list 'bkup-backup-directory-info | |
1584 (list "." "~/.emacs.d/backups/" 'full-path)) | |
1585 (setq tramp-bkup-backup-directory-info bkup-backup-directory-info) | |
1586 @end lisp | |
1587 @end ifset | |
1588 | |
1589 @noindent | |
1590 The backup file name of | |
1591 @file{@value{prefix}su@value{postfixsinglehop}root@@localhost@value{postfix}/etc/secretfile} | |
1592 would be | |
1593 @ifset emacs | |
1594 @file{@value{prefix}su@value{postfixsinglehop}root@@localhost@value{postfix}~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~} | |
1595 @end ifset | |
1596 @ifset xemacs | |
1597 @file{@value{prefix}su@value{postfixsinglehop}root@@localhost@value{postfix}~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~} | |
1598 @end ifset | |
1599 | |
1600 The same problem can happen with auto-saving files. | |
1601 @ifset emacs | |
1602 Since @value{emacsname} 21, the variable | |
1603 @code{auto-save-file-name-transforms} keeps information, on which | |
1604 directory an auto-saved file should go. By default, it is initialized | |
1605 for @value{tramp} files to the local temporary directory. | |
1606 | |
1607 On some versions of @value{emacsname}, namely the version built for | |
1608 Debian GNU/Linux, the variable @code{auto-save-file-name-transforms} | |
1609 contains the directory where @value{emacsname} was built. A | |
1610 workaround is to manually set the variable to a sane value. | |
1611 | |
1612 If auto-saved files should go into the same directory as the original | |
1613 files, @code{auto-save-file-name-transforms} should be set to @code{nil}. | |
1614 | |
1615 Another possibility is to set the variable | |
1616 @code{tramp-auto-save-directory} to a proper value. | |
1617 @end ifset | |
1618 @ifset xemacs | |
1619 For this purpose you can set the variable @code{auto-save-directory} | |
1620 to a proper value. | |
1621 @end ifset | |
1407 | 1622 |
1408 | 1623 |
1409 @node Windows setup hints | 1624 @node Windows setup hints |
1410 @section Issues with Cygwin ssh | 1625 @section Issues with Cygwin ssh |
1411 @cindex Cygwin, issues | 1626 @cindex Cygwin, issues |
1412 | 1627 |
1413 This section needs a lot of work! Please help. | 1628 This section needs a lot of work! Please help. |
1414 | 1629 |
1415 @cindex method sshx with Cygwin | 1630 @cindex method sshx with Cygwin |
1416 @cindex sshx method with Cygwin | 1631 @cindex sshx method with Cygwin |
1417 If you use the Cygwin installation of ssh (you have to explicitly select | 1632 The recent Cygwin installation of @command{ssh} works only with a |
1418 it in the installer), then it should work out of the box to just select | 1633 Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x |
1419 @code{sshx} as the connection method. You can find information about | 1634 eshell}, and starting @kbd{ssh test.machine}. The problem is evident |
1420 setting up Cygwin in their FAQ at @uref{http://cygwin.com/faq/}. | 1635 if you see a message like this: |
1636 | |
1637 @example | |
1638 Pseudo-terminal will not be allocated because stdin is not a terminal. | |
1639 @end example | |
1640 | |
1641 Older @command{ssh} versions of Cygwin are told to cooperate with | |
1642 @value{tramp} selecting @option{sshx} as the connection method. You | |
1643 can find information about setting up Cygwin in their FAQ at | |
1644 @uref{http://cygwin.com/faq/}. | |
1421 | 1645 |
1422 @cindex method scpx with Cygwin | 1646 @cindex method scpx with Cygwin |
1423 @cindex scpx method with Cygwin | 1647 @cindex scpx method with Cygwin |
1424 If you wish to use the @code{scpx} connection method, then you might | 1648 If you wish to use the @option{scpx} connection method, then you might |
1425 have the problem that Emacs calls @code{scp} with a Windows filename | 1649 have the problem that @value{emacsname} calls @command{scp} with a |
1426 such as @code{c:/foo}. The Cygwin version of @code{scp} does not know | 1650 Windows filename such as @code{c:/foo}. The Cygwin version of |
1427 about Windows filenames and interprets this as a remote filename on the | 1651 @command{scp} does not know about Windows filenames and interprets this |
1428 host @code{c}. | 1652 as a remote filename on the host @code{c}. |
1429 | 1653 |
1430 One possible workaround is to write a wrapper script for @code{scp} | 1654 One possible workaround is to write a wrapper script for @option{scp} |
1431 which converts the Windows filename to a Cygwinized filename. | 1655 which converts the Windows filename to a Cygwinized filename. |
1432 | 1656 |
1433 I guess that another workaround is to run Emacs under Cygwin, or to run | |
1434 a Cygwinized Emacs. | |
1435 | |
1436 @cindex Cygwin and ssh-agent | 1657 @cindex Cygwin and ssh-agent |
1437 @cindex SSH_AUTH_SOCK and Emacs on Windows | 1658 @cindex SSH_AUTH_SOCK and @value{emacsname} on Windows |
1438 If you want to use either @code{ssh} based method on Windows, then you | 1659 If you want to use either @option{ssh} based method on Windows, then |
1439 might encounter problems with @code{ssh-agent}. Using this program, | 1660 you might encounter problems with @command{ssh-agent}. Using this |
1440 you can avoid typing the pass-phrase every time you log in (and the | 1661 program, you can avoid typing the pass-phrase every time you log in. |
1441 @code{scpx} method more or less requires you to use @code{ssh-agent} | 1662 However, if you start @value{emacsname} from a desktop shortcut, then |
1442 because it does not allow you to type a password or pass-phrase). | 1663 the environment variable @code{SSH_AUTH_SOCK} is not set and so |
1443 However, if you start Emacs from a desktop shortcut, then the | 1664 @value{emacsname} and thus @value{tramp} and thus @command{ssh} and |
1444 environment variable @code{SSH_AUTH_SOCK} is not set and so Emacs and | 1665 @command{scp} started from @value{tramp} cannot communicate with |
1445 thus @tramp{} and thus @code{ssh} and @code{scp} started from @tramp{} | 1666 @command{ssh-agent}. It works better to start @value{emacsname} from |
1446 cannot communicate with @code{ssh-agent}. It works better to start | 1667 the shell. |
1447 Emacs from the shell. | 1668 |
1448 | 1669 If anyone knows how to start @command{ssh-agent} under Windows in such a |
1449 If anyone knows how to start @code{ssh-agent} under Windows in such a | |
1450 way that desktop shortcuts can profit, please holler. I don't really | 1670 way that desktop shortcuts can profit, please holler. I don't really |
1451 know anything at all about Windows@dots{} | 1671 know anything at all about Windows@dots{} |
1452 | 1672 |
1453 | 1673 |
1454 @node Usage | 1674 @node Usage |
1455 @chapter Using @tramp | 1675 @chapter Using @value{tramp} |
1456 @cindex using @tramp | 1676 @cindex using @value{tramp} |
1457 | 1677 |
1458 Once you have installed @tramp{} it will operate fairly transparently. You | 1678 Once you have installed @value{tramp} it will operate fairly transparently. You |
1459 will be able to access files on any remote machine that you can log in | 1679 will be able to access files on any remote machine that you can log in |
1460 to as though they were local. | 1680 to as though they were local. |
1461 | 1681 |
1462 Files are specified to @tramp{} using a formalized syntax specifying the | 1682 Files are specified to @value{tramp} using a formalized syntax specifying the |
1463 details of the system to connect to. This is similar to the syntax used | 1683 details of the system to connect to. This is similar to the syntax used |
1464 by the @value{ftp-package-name} package. | 1684 by the @value{ftppackagename} package. |
1465 | 1685 |
1466 @cindex type-ahead | 1686 @cindex type-ahead |
1467 Something that might happen which surprises you is that Emacs | 1687 Something that might happen which surprises you is that |
1468 remembers all your keystrokes, so if you see a password prompt from | 1688 @value{emacsname} remembers all your keystrokes, so if you see a |
1469 Emacs, say, and hit @kbd{@key{RET}} twice instead of once, then the | 1689 password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}} |
1470 second keystroke will be processed by Emacs after @tramp{} has done | 1690 twice instead of once, then the second keystroke will be processed by |
1471 its thing. Why, this type-ahead is normal behavior, you say. Right | 1691 @value{emacsname} after @value{tramp} has done its thing. Why, this |
1472 you are, but be aware that opening a remote file might take quite a | 1692 type-ahead is normal behavior, you say. Right you are, but be aware |
1473 while, maybe half a minute when a connection needs to be opened. | 1693 that opening a remote file might take quite a while, maybe half a |
1474 Maybe after half a minute you have already forgotten that you hit that | 1694 minute when a connection needs to be opened. Maybe after half a |
1475 key! | 1695 minute you have already forgotten that you hit that key! |
1476 | 1696 |
1477 @menu | 1697 @menu |
1478 * Filename Syntax:: @tramp{} filename conventions. | 1698 * Filename Syntax:: @value{tramp} filename conventions. |
1479 * Multi-hop filename syntax:: Multi-hop filename conventions. | 1699 * Multi-hop filename syntax:: Multi-hop filename conventions. |
1480 * Filename completion:: Filename completion. | 1700 * Filename completion:: Filename completion. |
1481 * Dired:: Dired. | 1701 * Dired:: Dired. |
1702 * Compilation:: Compile remote files. | |
1482 @end menu | 1703 @end menu |
1483 | 1704 |
1484 | 1705 |
1485 @node Filename Syntax | 1706 @node Filename Syntax |
1486 @section @tramp{} filename conventions | 1707 @section @value{tramp} filename conventions |
1487 @cindex filename syntax | 1708 @cindex filename syntax |
1488 @cindex filename examples | 1709 @cindex filename examples |
1489 | 1710 |
1490 To access the file @var{path} on the remote machine @var{machine} you | 1711 To access the file @var{localname} on the remote machine @var{machine} you |
1491 would specify the filename | 1712 would specify the filename |
1492 @file{@value{tramp-prefix}@var{machine}@value{tramp-postfix}@var{path}}. | 1713 @file{@value{prefix}@var{machine}@value{postfix}@var{localname}}. |
1493 This will connect to @var{machine} and transfer the file using the | 1714 This will connect to @var{machine} and transfer the file using the |
1494 default method. @xref{Default Method}. | 1715 default method. @xref{Default Method}. |
1495 | 1716 |
1496 Some examples of @tramp{} filenames are shown below. | 1717 Some examples of @value{tramp} filenames are shown below. |
1497 | 1718 |
1498 @table @file | 1719 @table @file |
1499 @item @value{tramp-prefix}melancholia@value{tramp-postfix}.emacs | 1720 @item @value{prefix}melancholia@value{postfix}.emacs |
1500 Edit the file @file{.emacs} in your home directory on the machine | 1721 Edit the file @file{.emacs} in your home directory on the machine |
1501 @code{melancholia}. | 1722 @code{melancholia}. |
1502 | 1723 |
1503 @item @value{tramp-prefix}melancholia.danann.net@value{tramp-postfix}.emacs | 1724 @item @value{prefix}melancholia.danann.net@value{postfix}.emacs |
1504 This edits the same file, using the fully qualified domain name of | 1725 This edits the same file, using the fully qualified domain name of |
1505 the machine. | 1726 the machine. |
1506 | 1727 |
1507 @item @value{tramp-prefix}melancholia@value{tramp-postfix}~/.emacs | 1728 @item @value{prefix}melancholia@value{postfix}~/.emacs |
1508 This also edits the same file --- the @file{~} is expanded to your | 1729 This also edits the same file --- the @file{~} is expanded to your |
1509 home directory on the remote machine, just like it is locally. | 1730 home directory on the remote machine, just like it is locally. |
1510 | 1731 |
1511 @item @value{tramp-prefix}melancholia@value{tramp-postfix}~daniel/.emacs | 1732 @item @value{prefix}melancholia@value{postfix}~daniel/.emacs |
1512 This edits the file @file{.emacs} in the home directory of the user | 1733 This edits the file @file{.emacs} in the home directory of the user |
1513 @code{daniel} on the machine @code{melancholia}. The @file{~<user>} | 1734 @code{daniel} on the machine @code{melancholia}. The @file{~<user>} |
1514 construct is expanded to the home directory of that user on the remote | 1735 construct is expanded to the home directory of that user on the remote |
1515 machine. | 1736 machine. |
1516 | 1737 |
1517 @item @value{tramp-prefix}melancholia@value{tramp-postfix}/etc/squid.conf | 1738 @item @value{prefix}melancholia@value{postfix}/etc/squid.conf |
1518 This edits the file @file{/etc/squid.conf} on the machine | 1739 This edits the file @file{/etc/squid.conf} on the machine |
1519 @code{melancholia}. | 1740 @code{melancholia}. |
1520 | 1741 |
1521 @end table | 1742 @end table |
1522 | 1743 |
1523 Unless you specify a different name to use, @tramp{} will use the | 1744 Unless you specify a different name to use, @value{tramp} will use the |
1524 current local user name as the remote user name to log in with. If you | 1745 current local user name as the remote user name to log in with. If you |
1525 need to log in as a different user, you can specify the user name as | 1746 need to log in as a different user, you can specify the user name as |
1526 part of the filename. | 1747 part of the filename. |
1527 | 1748 |
1528 To log in to the remote machine as a specific user, you use the syntax | 1749 To log in to the remote machine as a specific user, you use the syntax |
1529 @file{@value{tramp-prefix}@var{user}@@@var{machine}@value{tramp-postfix}/@var{path/to.file}}. | 1750 @file{@value{prefix}@var{user}@@@var{machine}@value{postfix}/@var{path/to.file}}. |
1530 That means that connecting to @code{melancholia} as @code{daniel} and | 1751 That means that connecting to @code{melancholia} as @code{daniel} and |
1531 editing @file{.emacs} in your home directory you would specify | 1752 editing @file{.emacs} in your home directory you would specify |
1532 @file{@value{tramp-prefix}daniel@@melancholia@value{tramp-postfix}.emacs}. | 1753 @file{@value{prefix}daniel@@melancholia@value{postfix}.emacs}. |
1533 | 1754 |
1534 It is also possible to specify other file transfer methods | 1755 It is also possible to specify other file transfer methods |
1535 (@pxref{Default Method}) as part of the filename. | 1756 (@pxref{Default Method}) as part of the filename. |
1536 @ifset emacs | 1757 @ifset emacs |
1537 This is done by putting the method before the user and host name, as | 1758 This is done by putting the method before the user and host name, as |
1538 in | 1759 in |
1539 @file{@value{tramp-prefix}@var{method}@value{tramp-postfix-single-hop}} | 1760 @file{@value{prefix}@var{method}@value{postfixsinglehop}} |
1540 (Note the trailing colon). | 1761 (Note the trailing colon). |
1541 @end ifset | 1762 @end ifset |
1542 @ifset xemacs | 1763 @ifset xemacs |
1543 This is done by replacing the initial | 1764 This is done by replacing the initial |
1544 @file{@value{tramp-prefix}} with | 1765 @file{@value{prefix}} with |
1545 @file{@value{tramp-prefix}<method>@value{tramp-postfix-single-hop}}. | 1766 @file{@value{prefix}<method>@value{postfixsinglehop}}. |
1546 (Note the trailing slash!). | 1767 (Note the trailing slash!). |
1547 @end ifset | 1768 @end ifset |
1548 The user, machine and file specification remain the same. | 1769 The user, machine and file specification remain the same. |
1549 | 1770 |
1550 So, to connect to the machine @code{melancholia} as @code{daniel}, | 1771 So, to connect to the machine @code{melancholia} as @code{daniel}, |
1551 using the @option{su} method to transfer files, and edit @file{.emacs} | 1772 using the @option{ssh} method to transfer files, and edit @file{.emacs} |
1552 in my home directory I would specify the filename | 1773 in my home directory I would specify the filename |
1553 @file{@value{tramp-prefix}su@value{tramp-postfix-single-hop}daniel@@melancholia@value{tramp-postfix}.emacs}. | 1774 @file{@value{prefix}ssh@value{postfixsinglehop}daniel@@melancholia@value{postfix}.emacs}. |
1554 | 1775 |
1555 | 1776 |
1556 @node Multi-hop filename syntax | 1777 @node Multi-hop filename syntax |
1557 @section Multi-hop filename conventions | 1778 @section Multi-hop filename conventions |
1558 @cindex filename syntax for multi-hop files | 1779 @cindex filename syntax for multi-hop files |
1559 @cindex multi-hop filename syntax | 1780 @cindex multi-hop filename syntax |
1560 | 1781 |
1561 The syntax of multi-hop file names is necessarily slightly different | 1782 The syntax of multi-hop file names is necessarily slightly different |
1562 than the syntax of other @tramp{} file names. Here's an example | 1783 than the syntax of other @value{tramp} file names. Here's an example |
1563 multi-hop file name, first in Emacs syntax and then in XEmacs syntax: | 1784 multi-hop file name: |
1564 | 1785 |
1565 @example | 1786 @example |
1566 @value{tramp-prefix}multi@value{tramp-postfix-single-hop}rsh@value{tramp-postfix-multi-hop}out@@gate@value{tramp-postfix-single-hop}telnet@value{tramp-postfix-multi-hop}kai@@real.host@value{tramp-postfix}/path/to.file | 1787 @value{prefix}multi@value{postfixsinglehop}rsh@value{postfixmultihop}out@@gate@value{postfixsinglehop}telnet@value{postfixmultihop}kai@@real.host@value{postfix}/path/to.file |
1567 @end example | 1788 @end example |
1568 | 1789 |
1569 This is quite a mouthful. So let's go through it step by step. The | 1790 This is quite a mouthful. So let's go through it step by step. The |
1570 file name consists of three parts. | 1791 file name consists of three parts. |
1571 @ifset emacs | 1792 @ifset emacs |
1572 The parts are separated by colons | 1793 The parts are separated by colons |
1573 @end ifset | 1794 @end ifset |
1574 @ifset xemacs | 1795 @ifset xemacs |
1575 The parts are separated by slashes and square brackets. | 1796 The parts are separated by slashes and square brackets. |
1576 @end ifset | 1797 @end ifset |
1577 The first part is @file{@value{tramp-prefix}multi}, the method | 1798 The first part is @file{@value{prefix}multi}, the method |
1578 specification. The second part is | 1799 specification. The second part is |
1579 @file{rsh@value{tramp-postfix-multi-hop}out@@gate@value{tramp-postfix-single-hop}telnet@value{tramp-postfix-multi-hop}kai@@real.host} | 1800 @file{rsh@value{postfixmultihop}out@@gate@value{postfixsinglehop}telnet@value{postfixmultihop}kai@@real.host} |
1580 and specifies the hops. The final part is @file{/path/to.file} and | 1801 and specifies the hops. The final part is @file{/path/to.file} and |
1581 specifies the file name on the remote host. | 1802 specifies the file name on the remote host. |
1582 | 1803 |
1583 The first part and the final part should be clear. See @ref{Multi-hop | 1804 The first part and the final part should be clear. See @ref{Multi-hop |
1584 Methods}, for a list of alternatives for the method specification. | 1805 Methods}, for a list of alternatives for the method specification. |
1585 | 1806 |
1586 The second part can be subdivided again into components, so-called | 1807 The second part can be subdivided again into components, so-called |
1587 hops. In the above file name, there are two hops, | 1808 hops. In the above file name, there are two hops, |
1588 @file{rsh@value{tramp-postfix-multi-hop}out@@gate} and | 1809 @file{rsh@value{postfixmultihop}out@@gate} and |
1589 @file{telnet@value{tramp-postfix-multi-hop}kai@@real.host}. | 1810 @file{telnet@value{postfixmultihop}kai@@real.host}. |
1590 | 1811 |
1591 Each hop can @emph{again} be subdivided into (three) components, the | 1812 Each hop can @emph{again} be subdivided into (three) components, the |
1592 @dfn{hop method}, the @dfn{user name} and the @dfn{host name}. The | 1813 @dfn{hop method}, the @dfn{user name} and the @dfn{host name}. The |
1593 meaning of the second and third component should be clear, and the hop | 1814 meaning of the second and third component should be clear, and the hop |
1594 method says what program to use to perform that hop. | 1815 method says what program to use to perform that hop. |
1595 | 1816 |
1596 The first hop, @file{rsh@value{tramp-postfix-multi-hop}out@@gate}, | 1817 The first hop, @file{rsh@value{postfixmultihop}out@@gate}, |
1597 says to use @command{rsh} to log in as user @code{out} to the host | 1818 says to use @command{rsh} to log in as user @code{out} to the host |
1598 @code{gate}. Starting at that host, the second hop, | 1819 @code{gate}. Starting at that host, the second hop, |
1599 @file{telnet@value{tramp-postfix-multi-hop}kai@@real.host}, says to | 1820 @file{telnet@value{postfixmultihop}kai@@real.host}, says to |
1600 use @command{telnet} to log in as user @code{kai} to host | 1821 use @command{telnet} to log in as user @code{kai} to host |
1601 @code{real.host}. | 1822 @code{real.host}. |
1602 | 1823 |
1603 @xref{Multi-hop Methods}, for a list of possible hop method values. | 1824 @xref{Multi-hop Methods}, for a list of possible hop method values. |
1604 The variable @code{tramp-multi-connection-function-alist} contains the | 1825 The variable @code{tramp-multi-connection-function-alist} contains the |
1608 | 1829 |
1609 @node Filename completion | 1830 @node Filename completion |
1610 @section Filename completion | 1831 @section Filename completion |
1611 @cindex filename completion | 1832 @cindex filename completion |
1612 | 1833 |
1613 Filename completion works with @tramp{} for both completing methods, | 1834 Filename completion works with @value{tramp} for both completing methods, |
1614 user names and machine names (except multi hop methods) as well as for | 1835 user names and machine names (except multi hop methods) as well as for |
1615 files on remote machines. | 1836 files on remote machines. |
1616 | 1837 |
1617 If you, for example, type @kbd{C-x C-f @value{tramp-prefix}t | 1838 If you, for example, type @kbd{C-x C-f @value{prefix}t |
1618 @key{TAB}}, @tramp{} might give you as result the choice for | 1839 @key{TAB}}, @value{tramp} might give you as result the choice for |
1619 | 1840 |
1620 @example | 1841 @example |
1621 @ifset emacs | 1842 @ifset emacs |
1622 @value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop} tmp/ | 1843 @value{prefixsinglehop}telnet@value{postfixsinglehop} tmp/ |
1623 @value{tramp-prefix-single-hop}toto@value{tramp-postfix} | 1844 @value{prefixsinglehop}toto@value{postfix} |
1624 @end ifset | 1845 @end ifset |
1625 @ifset xemacs | 1846 @ifset xemacs |
1626 @value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop} @value{tramp-prefix-single-hop}toto@value{tramp-postfix} | 1847 @value{prefixsinglehop}telnet@value{postfixsinglehop} @value{prefixsinglehop}toto@value{postfix} |
1627 @end ifset | 1848 @end ifset |
1628 @end example | 1849 @end example |
1629 | 1850 |
1630 @samp{@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}} | 1851 @samp{@value{prefixsinglehop}telnet@value{postfixsinglehop}} |
1631 is a possible completion for the respective method, | 1852 is a possible completion for the respective method, |
1632 @ifset emacs | 1853 @ifset emacs |
1633 @samp{tmp/} stands for the directory @file{/tmp} on your local | 1854 @samp{tmp/} stands for the directory @file{/tmp} on your local |
1634 machine, | 1855 machine, |
1635 @end ifset | 1856 @end ifset |
1636 and @samp{@value{tramp-prefix-single-hop}toto@value{tramp-postfix}} | 1857 and @samp{@value{prefixsinglehop}toto@value{postfix}} |
1637 might be a host @tramp has detected in your @file{~/.ssh/known_hosts} | 1858 might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts} |
1638 file (given you're using default method @option{ssh}). | 1859 file (given you're using default method @option{ssh}). |
1639 | 1860 |
1640 If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to | 1861 If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to |
1641 @samp{@value{tramp-prefix}telnet@value{tramp-postfix-single-hop}}. | 1862 @samp{@value{prefix}telnet@value{postfixsinglehop}}. |
1642 Next @kbd{@key{TAB}} brings you all machine names @tramp{} detects in | 1863 Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in |
1643 your @file{/etc/hosts} file, let's say | 1864 your @file{/etc/hosts} file, let's say |
1644 | 1865 |
1645 @example | 1866 @example |
1646 @value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}127.0.0.1@value{tramp-postfix} @value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}192.168.0.1@value{tramp-postfix} | 1867 @value{prefixsinglehop}telnet@value{postfixsinglehop}127.0.0.1@value{postfix} @value{prefixsinglehop}telnet@value{postfixsinglehop}192.168.0.1@value{postfix} |
1647 @value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}localhost@value{tramp-postfix} @value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}melancholia.danann.net@value{tramp-postfix} | 1868 @value{prefixsinglehop}telnet@value{postfixsinglehop}localhost@value{postfix} @value{prefixsinglehop}telnet@value{postfixsinglehop}melancholia.danann.net@value{postfix} |
1648 @value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}melancholia@value{tramp-postfix} | 1869 @value{prefixsinglehop}telnet@value{postfixsinglehop}melancholia@value{postfix} |
1649 @end example | 1870 @end example |
1650 | 1871 |
1651 Now you can choose the desired machine, and you can continue to | 1872 Now you can choose the desired machine, and you can continue to |
1652 complete file names on that machine. | 1873 complete file names on that machine. |
1653 | 1874 |
1654 As filename completion needs to fetch the listing of files from the | 1875 As filename completion needs to fetch the listing of files from the |
1655 remote machine, this feature is sometimes fairly slow. As @tramp{} | 1876 remote machine, this feature is sometimes fairly slow. As @value{tramp} |
1656 does not yet cache the results of directory listing, there is no gain | 1877 does not yet cache the results of directory listing, there is no gain |
1657 in performance the second time you complete filenames. | 1878 in performance the second time you complete filenames. |
1658 | 1879 |
1659 If the configuration files (@pxref{Customizing Completion}), which | 1880 If the configuration files (@pxref{Customizing Completion}), which |
1660 @tramp{} uses for analysis of completion, offer user names, those user | 1881 @value{tramp} uses for analysis of completion, offer user names, those user |
1661 names will be taken into account as well. | 1882 names will be taken into account as well. |
1662 | 1883 |
1663 | 1884 |
1664 @node Dired | 1885 @node Dired |
1665 @section Dired | 1886 @section Dired |
1666 @cindex dired | 1887 @cindex dired |
1667 | 1888 |
1668 @tramp{} works transparently with dired, enabling you to use this powerful | 1889 @value{tramp} works transparently with dired, enabling you to use this powerful |
1669 file management tool to manage files on any machine you have access to | 1890 file management tool to manage files on any machine you have access to |
1670 over the Internet. | 1891 over the Internet. |
1671 | 1892 |
1672 If you need to browse a directory tree, Dired is a better choice, at | 1893 If you need to browse a directory tree, Dired is a better choice, at |
1673 present, than filename completion. Dired has its own cache mechanism | 1894 present, than filename completion. Dired has its own cache mechanism |
1674 and will only fetch the directory listing once. | 1895 and will only fetch the directory listing once. |
1675 | 1896 |
1676 | 1897 |
1898 @node Compilation | |
1899 @section Compile remote files | |
1900 @cindex compile | |
1901 @cindex recompile | |
1902 | |
1903 @value{tramp} provides commands for compilation of files on remote | |
1904 machines. In order to get them loaded, you need to require | |
1905 @file{tramp-util.el}: | |
1906 | |
1907 @lisp | |
1908 (require 'tramp-util) | |
1909 @end lisp | |
1910 | |
1911 Afterwards, you can use the commands @code{tramp-compile} and | |
1912 @code{tramp-recompile} instead of @code{compile} and @code{recompile}, | |
1913 respectively; @inforef{Compilation, ,@value{emacsdir}}. This does not | |
1914 work for the @option{ftp} and @option{smb} methods. | |
1915 | |
1916 The corresponding key bindings and menu entries calling these commands | |
1917 are redefined automatically for buffers associated with remote files. | |
1918 | |
1919 After finishing the compilation, you can use the usual commands like | |
1920 @code{previous-error}, @code{next-error} and @code{first-error} for | |
1921 navigation in the @file{*Compilation*} buffer. | |
1922 | |
1923 | |
1677 @node Bug Reports | 1924 @node Bug Reports |
1678 @chapter Reporting Bugs and Problems | 1925 @chapter Reporting Bugs and Problems |
1679 @cindex bug reports | 1926 @cindex bug reports |
1680 | 1927 |
1681 Bugs and problems with @tramp{} are actively worked on by the development | 1928 Bugs and problems with @value{tramp} are actively worked on by the development |
1682 team. Feature requests and suggestions are also more than welcome. | 1929 team. Feature requests and suggestions are also more than welcome. |
1683 | 1930 |
1684 The @tramp{} mailing list is a great place to get information on working | 1931 The @value{tramp} mailing list is a great place to get information on working |
1685 with @tramp{}, solving problems and general discussion and advice on topics | 1932 with @value{tramp}, solving problems and general discussion and advice on topics |
1686 relating to the package. | 1933 relating to the package. |
1687 | 1934 |
1688 The mailing list is at @email{tramp-devel@@mail.freesoftware.fsf.org}. | 1935 The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to |
1689 Messages sent to this address go to all the subscribers. This is | 1936 this address go to all the subscribers. This is @emph{not} the address |
1690 @emph{not} the address to send subscription requests to. | 1937 to send subscription requests to. |
1691 | 1938 |
1692 For help on subscribing to the list, send mail to the administrative | 1939 Subscribing to the list is performed via |
1693 address, @email{tramp-devel-request@@mail.freesoftware.fsf.org}, with the | 1940 @uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/, |
1694 subject @samp{help}. | 1941 the @value{tramp} Mail Subscription Page}. |
1695 | 1942 |
1696 To report a bug in @tramp{}, you should execute @kbd{M-x tramp-bug}. This | 1943 To report a bug in @value{tramp}, you should execute @kbd{M-x tramp-bug}. This |
1697 will automatically generate a buffer with the details of your system and | 1944 will automatically generate a buffer with the details of your system and |
1698 @tramp{} version. | 1945 @value{tramp} version. |
1699 | 1946 |
1700 When submitting a bug report, please try to describe in excruciating | 1947 When submitting a bug report, please try to describe in excruciating |
1701 detail the steps required to reproduce the problem, the setup of the | 1948 detail the steps required to reproduce the problem, the setup of the |
1702 remote machine and any special conditions that exist. | 1949 remote machine and any special conditions that exist. |
1703 | 1950 |
1710 @cindex frequently asked questions | 1957 @cindex frequently asked questions |
1711 @cindex FAQ | 1958 @cindex FAQ |
1712 | 1959 |
1713 @itemize @bullet | 1960 @itemize @bullet |
1714 @item | 1961 @item |
1715 Where can I get the latest @tramp{}? | 1962 Where can I get the latest @value{tramp}? |
1716 | 1963 |
1717 @tramp{} is available under the URL below. | 1964 @value{tramp} is available under the URL below. |
1718 | 1965 |
1719 @noindent | 1966 @noindent |
1720 @uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/tramp.tar.gz} | 1967 @uref{http://ftp.gnu.org/gnu/tramp/} |
1721 | 1968 |
1722 @noindent | 1969 @noindent |
1723 There is also a Savannah project page. | 1970 There is also a Savannah project page. |
1724 | 1971 |
1725 @noindent | 1972 @noindent |
1726 @uref{https://savannah.gnu.org/projects/tramp/} | 1973 @uref{http://savannah.gnu.org/projects/tramp/} |
1727 | 1974 |
1728 @item | 1975 @item |
1729 Which systems does it work on? | 1976 Which systems does it work on? |
1730 | 1977 |
1731 The package has been used successfully on Emacs 20 and Emacs 21, as well | 1978 The package has been used successfully on GNU Emacs 20, GNU Emacs 21 |
1732 as XEmacs 21. XEmacs 20 is more problematic, see the notes in | 1979 and GNU Emacs 22, as well as XEmacs 21. XEmacs 20 is more |
1733 @file{tramp.el}. I don't think anybody has really tried it on Emacs 19. | 1980 problematic, see the notes in @file{tramp.el}. I don't think anybody |
1981 has really tried it on GNU Emacs 19. | |
1734 | 1982 |
1735 The package was intended to work on Unix, and it really expects a | 1983 The package was intended to work on Unix, and it really expects a |
1736 Unix-like system on the remote end, but some people seemed to have some | 1984 Unix-like system on the remote end (except the @option{smb} method), |
1737 success getting it to work on NT Emacs. | 1985 but some people seemed to have some success getting it to work on MS |
1738 | 1986 Windows NT/2000/XP @value{emacsname}. |
1739 There is some informations on @tramp{} on NT at the following URL; | 1987 |
1988 There is some informations on @value{tramp} on NT at the following URL; | |
1740 many thanks to Joe Stoy for providing the information: | 1989 many thanks to Joe Stoy for providing the information: |
1741 @uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/} | 1990 @uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/} |
1742 | 1991 |
1992 @c The link is broken. I've contacted Tom for clarification. Michael. | |
1993 @ignore | |
1743 The above mostly contains patches to old ssh versions; Tom Roche has a | 1994 The above mostly contains patches to old ssh versions; Tom Roche has a |
1744 Web page with instructions: | 1995 Web page with instructions: |
1745 @uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html} | 1996 @uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html} |
1997 @end ignore | |
1746 | 1998 |
1747 ??? Is the XEmacs info correct? | 1999 ??? Is the XEmacs info correct? |
1748 | 2000 |
1749 ??? Can somebody provide some information for getting it to work on NT | 2001 ??? Can somebody provide some information for getting it to work on NT |
1750 Emacs? I think there was some issue with @command{ssh}? | 2002 Emacs? I think there was some issue with @command{ssh}? |
1751 | 2003 |
1752 | 2004 |
1753 @item | 2005 @item |
1754 I can't stop @value{ftp-package-name} starting with @value{emacs-name} | 2006 I can't stop @value{ftppackagename} starting with @value{emacsname} |
1755 | 2007 |
1756 @ifset emacs | 2008 @ifset emacs |
1757 @value{ftp-package-name} is loaded from @tramp{} automatically if you | 2009 @value{ftppackagename} is loaded from @value{tramp} automatically if you |
1758 require a file by the ftp method. Unfortunately, there are some Lisp | 2010 require a file by the ftp method. Unfortunately, there are some Lisp |
1759 packages which make @value{ftp-package-name} file name handlers active. | 2011 packages which make @value{ftppackagename} file name handlers active. |
1760 You can see it applying @kbd{C-h v file-name-handler-alist}: | 2012 You can see it applying @kbd{C-h v file-name-handler-alist}: |
1761 | 2013 |
1762 @example | 2014 @example |
1763 file-name-handler-alist's value is | 2015 file-name-handler-alist's value is |
1764 (("^/[^/:]*\\'" . ange-ftp-completion-hook-function) | 2016 (("^/[^/:]*\\'" . ange-ftp-completion-hook-function) |
1765 ("^/[^/:]*[^/:.]:" . ange-ftp-hook-function) | 2017 ("^/[^/:]*[^/:.]:" . ange-ftp-hook-function) |
1766 ("^/[^/]*$" . tramp-completion-file-name-handler) | 2018 ("^/[^/]*$" . tramp-completion-file-name-handler) |
1767 ("\\`/[^/:]+:" . tramp-file-name-handler) | 2019 ("\\`/[^/:]+:" . tramp-file-name-handler) |
1768 ("\\`/:" . file-name-non-special)) | 2020 ("\\`/:" . file-name-non-special)) |
1769 @end example | 2021 @end example |
1770 | 2022 |
1771 Please try to find out which package is responsible for loading | 2023 Please try to find out which package is responsible for loading |
1772 @value{ftp-package-name}, and raise a bug report. | 2024 @value{ftppackagename}, and raise a bug report. |
1773 | 2025 |
1774 A workaround is to require @value{ftp-package-name} before @tramp{} in | 2026 A workaround is to require @value{ftppackagename} before @value{tramp} in |
1775 your @file{~/.emacs}, because @tramp{} cleans up the entries in | 2027 your @file{~/.emacs}, because @value{tramp} cleans up the entries in |
1776 @code{file-name-handler-alist}: | 2028 @code{file-name-handler-alist}: |
1777 | 2029 |
1778 @lisp | 2030 @lisp |
1779 ;; @value{ftp-package-name} temporarily required | 2031 ;; @value{ftppackagename} temporarily required |
1780 (require 'ange-ftp) | 2032 (require 'ange-ftp) |
1781 ;; @tramp{} cleans up @code{file-name-handler-alist} | 2033 ;; @value{tramp} cleans up @code{file-name-handler-alist} |
1782 (require 'tramp) | 2034 (require 'tramp) |
1783 @end lisp | 2035 @end lisp |
1784 @end ifset | 2036 @end ifset |
1785 | 2037 |
1786 @ifset xemacs | 2038 @ifset xemacs |
1787 Not all the older versions of @tramp{} supported @value{emacs-name} | 2039 Not all the older versions of @value{tramp} supported @value{emacsname} |
1788 correctly. The first thing to do is to make sure that you have the | 2040 correctly. The first thing to do is to make sure that you have the |
1789 latest version of @tramp{} installed. | 2041 latest version of @value{tramp} installed. |
1790 | 2042 |
1791 If you do, please try and find out exactly the conditions required for | 2043 If you do, please try and find out exactly the conditions required for |
1792 the @value{ftp-package-name} handlers to fire. If you can, putting a | 2044 the @value{ftppackagename} handlers to fire. If you can, putting a |
1793 breakpoint on @code{efs-ftp-path} and sending in the stack trace along | 2045 breakpoint on @code{efs-ftp-path} and sending in the stack trace along |
1794 with your bug report would make it easier for the developers to work out | 2046 with your bug report would make it easier for the developers to work out |
1795 what is going wrong. | 2047 what is going wrong. |
1796 @end ifset | 2048 @end ifset |
1797 | 2049 |
1798 | 2050 |
1799 @item | 2051 @item |
1800 File name completion does not work with @tramp{} | 2052 File name completion does not work with @value{tramp} |
1801 | 2053 |
1802 When you log in to the remote machine, do you see the output of | 2054 When you log in to the remote machine, do you see the output of |
1803 @command{ls} in color? If so, this may be the cause of your problems. | 2055 @command{ls} in color? If so, this may be the cause of your problems. |
1804 | 2056 |
1805 @command{ls} outputs @acronym{ANSI} escape sequences that your terminal | 2057 @command{ls} outputs @acronym{ANSI} escape sequences that your terminal |
1806 emulator interprets to set the colors. These escape sequences will | 2058 emulator interprets to set the colors. These escape sequences will |
1807 confuse @tramp{} however. | 2059 confuse @value{tramp} however. |
1808 | 2060 |
1809 In your @file{.bashrc}, @file{.profile} or equivalent on the remote | 2061 In your @file{.bashrc}, @file{.profile} or equivalent on the remote |
1810 machine you probably have an alias configured that adds the option | 2062 machine you probably have an alias configured that adds the option |
1811 @option{--color=yes} or @option{--color=auto}. | 2063 @option{--color=yes} or @option{--color=auto}. |
1812 | 2064 |
1813 You should remove that alias and ensure that a new login @emph{does not} | 2065 You should remove that alias and ensure that a new login @emph{does not} |
1814 display the output of @command{ls} in color. If you still cannot use | 2066 display the output of @command{ls} in color. If you still cannot use |
1815 filename completion, report a bug to the @tramp{} developers. | 2067 filename completion, report a bug to the @value{tramp} developers. |
1816 | 2068 |
1817 | 2069 |
1818 @item | 2070 @item |
1819 File name completion does not work in large directories | 2071 File name completion does not work in large directories |
1820 | 2072 |
1821 @tramp{} uses globbing for some operations. (Globbing means to use the | 2073 @value{tramp} uses globbing for some operations. (Globbing means to use the |
1822 shell to expand wildcards such as `*.c'.) This might create long | 2074 shell to expand wildcards such as `*.c'.) This might create long |
1823 command lines, especially in directories with many files. Some shells | 2075 command lines, especially in directories with many files. Some shells |
1824 choke on long command lines, or don't cope well with the globbing | 2076 choke on long command lines, or don't cope well with the globbing |
1825 itself. | 2077 itself. |
1826 | 2078 |
1830 @command{/bin/sh}, @command{ksh} or @command{bash}, depending on which | 2082 @command{/bin/sh}, @command{ksh} or @command{bash}, depending on which |
1831 of those supports tilde expansion. | 2083 of those supports tilde expansion. |
1832 | 2084 |
1833 | 2085 |
1834 @item | 2086 @item |
1835 What kinds of systems does @tramp{} work on | 2087 How can I get notified when @value{tramp} file transfers are complete? |
1836 | 2088 |
1837 @tramp{} really expects the remote system to be a Unix-like system. The | 2089 The following snippet can be put in your @file{~/.emacs} file. It |
1838 local system should preferably be Unix-like, as well, but @tramp{} might | 2090 makes @value{emacsname} beep after reading from or writing to the |
1839 work on NT with some tweaking. | 2091 remote host. |
1840 | |
1841 | |
1842 @item | |
1843 How can I get notified when @tramp{} file transfers are complete? | |
1844 | |
1845 The following snippet can be put in your @file{~/.emacs} file. It makes | |
1846 Emacs beep after reading from or writing to the remote host. | |
1847 | 2092 |
1848 @lisp | 2093 @lisp |
1849 (defadvice tramp-handle-write-region | 2094 (defadvice tramp-handle-write-region |
1850 (after tramp-write-beep-advice activate) | 2095 (after tramp-write-beep-advice activate) |
1851 " make tramp beep after writing a file." | 2096 " make tramp beep after writing a file." |
1866 | 2111 |
1867 @item | 2112 @item |
1868 There's this @file{~/.sh_history} file on the remote host which keeps | 2113 There's this @file{~/.sh_history} file on the remote host which keeps |
1869 growing and growing. What's that? | 2114 growing and growing. What's that? |
1870 | 2115 |
1871 Sometimes, @tramp{} starts @code{ksh} on the remote host for tilde | 2116 Sometimes, @value{tramp} starts @command{ksh} on the remote host for |
1872 expansion. Maybe @code{ksh} saves the history by default. @tramp{} | 2117 tilde expansion. Maybe @command{ksh} saves the history by default. |
1873 tries to turn off saving the history, but maybe you have to help. For | 2118 @value{tramp} tries to turn off saving the history, but maybe you have |
1874 example, you could put this in your @file{.kshrc}: | 2119 to help. For example, you could put this in your @file{.kshrc}: |
1875 | 2120 |
1876 @example | 2121 @example |
1877 if [ -f $HOME/.sh_history ] ; then | 2122 if [ -f $HOME/.sh_history ] ; then |
1878 /bin/rm $HOME/.sh_history | 2123 /bin/rm $HOME/.sh_history |
1879 fi | 2124 fi |
1883 if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then | 2128 if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then |
1884 unset HISTSIZE | 2129 unset HISTSIZE |
1885 fi | 2130 fi |
1886 @end example | 2131 @end example |
1887 | 2132 |
2133 | |
2134 @item | |
2135 @value{tramp} doesn't transfer strings with more than 500 characters | |
2136 correctly | |
2137 | |
2138 On some few systems, the implementation of @code{process-send-string} | |
2139 seems to be broken for longer strings. This case, you should | |
2140 customize the variable @code{tramp-chunksize} to 500. For a | |
2141 description how to determine whether this is necessary see the | |
2142 documentation of @code{tramp-chunksize}. | |
1888 @end itemize | 2143 @end itemize |
1889 | 2144 |
1890 | 2145 |
1891 @c For the developer | 2146 @c For the developer |
1892 @node Version Control | 2147 @node Version Control |
1893 @chapter The inner workings of remote version control | 2148 @chapter The inner workings of remote version control |
1894 | 2149 @cindex Version Control |
1895 Unlike @value{ftp-package-name}, @tramp{} has full shell access to the | 2150 |
2151 Unlike @value{ftppackagename}, @value{tramp} has full shell access to the | |
1896 remote machine. This makes it possible to provide version control for | 2152 remote machine. This makes it possible to provide version control for |
1897 files accessed under @tramp{}. | 2153 files accessed under @value{tramp}. |
1898 | 2154 |
1899 The actual version control binaries must be installed on the remote | 2155 The actual version control binaries must be installed on the remote |
1900 machine, accessible in the directories specified in | 2156 machine, accessible in the directories specified in |
1901 @var{tramp-remote-path}. | 2157 @var{tramp-remote-path}. |
1902 | 2158 |
1903 This transparent integration with the version control systems is one of | 2159 This transparent integration with the version control systems is one of |
1904 the most valuable features provided by @tramp{}, but it is far from perfect. | 2160 the most valuable features provided by @value{tramp}, but it is far from perfect. |
1905 Work is ongoing to improve the transparency of the system. | 2161 Work is ongoing to improve the transparency of the system. |
1906 | 2162 |
1907 @menu | 2163 @menu |
1908 * Version Controlled Files:: Determining if a file is under version control. | 2164 * Version Controlled Files:: Determining if a file is under version control. |
1909 * Remote Commands:: Executing the version control commands on the remote machine. | 2165 * Remote Commands:: Executing the version control commands on the remote machine. |
1916 @node Version Controlled Files | 2172 @node Version Controlled Files |
1917 @section Determining if a file is under version control | 2173 @section Determining if a file is under version control |
1918 | 2174 |
1919 The VC package uses the existence of on-disk revision control master | 2175 The VC package uses the existence of on-disk revision control master |
1920 files to determine if a given file is under revision control. These file | 2176 files to determine if a given file is under revision control. These file |
1921 tests happen on the remote machine through the standard @tramp{} mechanisms. | 2177 tests happen on the remote machine through the standard @value{tramp} mechanisms. |
1922 | 2178 |
1923 | 2179 |
1924 @node Remote Commands | 2180 @node Remote Commands |
1925 @section Executing the version control commands on the remote machine | 2181 @section Executing the version control commands on the remote machine |
1926 | 2182 |
1930 efficient than the @code{shell-command} function but that does not | 2186 efficient than the @code{shell-command} function but that does not |
1931 provide hooks for remote execution of commands. | 2187 provide hooks for remote execution of commands. |
1932 | 2188 |
1933 To work around this, the functions @code{vc-do-command} and | 2189 To work around this, the functions @code{vc-do-command} and |
1934 @code{vc-simple-command} have been advised to intercept requests for | 2190 @code{vc-simple-command} have been advised to intercept requests for |
1935 operations on files accessed via @tramp{}. | 2191 operations on files accessed via @value{tramp}. |
1936 | 2192 |
1937 In the case of a remote file, the @code{shell-command} interface is | 2193 In the case of a remote file, the @code{shell-command} interface is |
1938 used, with some wrapper code, to provide the same functionality on the | 2194 used, with some wrapper code, to provide the same functionality on the |
1939 remote machine as would be seen on the local machine. | 2195 remote machine as would be seen on the local machine. |
1940 | 2196 |
1942 @node Changed workfiles | 2198 @node Changed workfiles |
1943 @section Detecting if the working file has changed | 2199 @section Detecting if the working file has changed |
1944 | 2200 |
1945 As there is currently no way to get access to the mtime of a file on a | 2201 As there is currently no way to get access to the mtime of a file on a |
1946 remote machine in a portable way, the @code{vc-workfile-unchanged-p} | 2202 remote machine in a portable way, the @code{vc-workfile-unchanged-p} |
1947 function is advised to call an @tramp{} specific function for remote files. | 2203 function is advised to call an @value{tramp} specific function for remote files. |
1948 | 2204 |
1949 The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC | 2205 The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC |
1950 diff functionality to determine if any changes have occurred between the | 2206 diff functionality to determine if any changes have occurred between the |
1951 workfile and the version control master. | 2207 workfile and the version control master. |
1952 | 2208 |
1959 @node Checking out files | 2215 @node Checking out files |
1960 @section Bringing the workfile out of the repository | 2216 @section Bringing the workfile out of the repository |
1961 | 2217 |
1962 VC will, by default, check for remote files and refuse to act on them | 2218 VC will, by default, check for remote files and refuse to act on them |
1963 when checking out files from the repository. To work around this | 2219 when checking out files from the repository. To work around this |
1964 problem, the function @code{vc-checkout} knows about @tramp{} files and | 2220 problem, the function @code{vc-checkout} knows about @value{tramp} files and |
1965 allows version control to occur. | 2221 allows version control to occur. |
1966 | 2222 |
1967 | 2223 |
1968 @node Miscellaneous Version Control | 2224 @node Miscellaneous Version Control |
1969 @section Things related to Version Control that don't fit elsewhere | 2225 @section Things related to Version Control that don't fit elsewhere |
1977 | 2233 |
1978 | 2234 |
1979 @node Remote File Ownership | 2235 @node Remote File Ownership |
1980 @subsection How VC determines who owns a workfile | 2236 @subsection How VC determines who owns a workfile |
1981 | 2237 |
1982 Emacs provides the @code{user-full-name} function to return the login name | 2238 @value{emacsname} provides the @code{user-full-name} function to |
1983 of the current user as well as mapping from arbitrary user id values | 2239 return the login name of the current user as well as mapping from |
1984 back to login names. The VC code uses this functionality to map from the | 2240 arbitrary user id values back to login names. The VC code uses this |
1985 uid of the owner of a workfile to the login name in some circumstances. | 2241 functionality to map from the uid of the owner of a workfile to the |
2242 login name in some circumstances. | |
1986 | 2243 |
1987 This will not, for obvious reasons, work if the remote system has a | 2244 This will not, for obvious reasons, work if the remote system has a |
1988 different set of logins. As such, it is necessary to delegate to the | 2245 different set of logins. As such, it is necessary to delegate to the |
1989 remote machine the job of determining the login name associated with a | 2246 remote machine the job of determining the login name associated with a |
1990 uid. | 2247 uid. |
2018 Unfortunately, life is not quite so easy when remote version control | 2275 Unfortunately, life is not quite so easy when remote version control |
2019 comes into the picture. Each remote machine may have a different version | 2276 comes into the picture. Each remote machine may have a different version |
2020 of the version control tools and, while this is painful, we need to | 2277 of the version control tools and, while this is painful, we need to |
2021 ensure that unavailable features are not used remotely. | 2278 ensure that unavailable features are not used remotely. |
2022 | 2279 |
2023 To resolve this issue, @tramp{} currently takes the sledgehammer | 2280 To resolve this issue, @value{tramp} currently takes the sledgehammer |
2024 approach of making the release values of the revision control tools | 2281 approach of making the release values of the revision control tools |
2025 local to each @tramp{} buffer, forcing VC to determine these values | 2282 local to each @value{tramp} buffer, forcing VC to determine these values |
2026 again each time a new file is visited. | 2283 again each time a new file is visited. |
2027 | 2284 |
2028 This has, quite obviously, some performance implications. Thankfully, | 2285 This has, quite obviously, some performance implications. Thankfully, |
2029 most of the common operations performed by VC do not actually require | 2286 most of the common operations performed by VC do not actually require |
2030 that the remote version be known. This makes the problem far less | 2287 that the remote version be known. This makes the problem far less |
2031 apparent. | 2288 apparent. |
2032 | 2289 |
2033 Eventually these values will be captured by @tramp{} on a system by | 2290 Eventually these values will be captured by @value{tramp} on a system by |
2034 system basis and the results cached to improve performance. | 2291 system basis and the results cached to improve performance. |
2035 | 2292 |
2036 | 2293 |
2037 @node Files directories and paths | 2294 @node Files directories and localnames |
2038 @chapter How file names, directories and paths are mangled and managed. | 2295 @chapter How file names, directories and localnames are mangled and managed. |
2039 | 2296 |
2040 @menu | 2297 @menu |
2041 * Path deconstruction:: Breaking a path into its components. | 2298 * Localname deconstruction:: Breaking a localname into its components. |
2042 @end menu | 2299 @end menu |
2043 | 2300 |
2044 | 2301 |
2045 @node Path deconstruction | 2302 @node Localname deconstruction |
2046 @section Breaking a path into its components. | 2303 @section Breaking a localname into its components. |
2047 | 2304 |
2048 @tramp{} filenames are somewhat different, obviously, to ordinary path | 2305 @value{tramp} file names are somewhat different, obviously, to ordinary file |
2049 names. As such, the lisp functions @code{file-name-directory} and | 2306 names. As such, the lisp functions @code{file-name-directory} and |
2050 @code{file-name-nondirectory} are overridden within the @tramp{} package. | 2307 @code{file-name-nondirectory} are overridden within the @value{tramp} |
2308 package. | |
2051 | 2309 |
2052 Their replacements are reasonably simplistic in their approach. They | 2310 Their replacements are reasonably simplistic in their approach. They |
2053 dissect the filename, call the original handler on the remote path and | 2311 dissect the filename, call the original handler on the localname and |
2054 then rebuild the @tramp{} path with the result. | 2312 then rebuild the @value{tramp} file name with the result. |
2055 | 2313 |
2056 This allows the platform specific hacks in the original handlers to take | 2314 This allows the platform specific hacks in the original handlers to take |
2057 effect while preserving the @tramp{} path information. | 2315 effect while preserving the @value{tramp} file name information. |
2058 | 2316 |
2059 | 2317 |
2060 @node Issues | 2318 @node Issues |
2061 @chapter Debatable Issues and What Was Decided | 2319 @chapter Debatable Issues and What Was Decided |
2062 | 2320 |
2063 @itemize @bullet | 2321 @itemize @bullet |
2064 @item The uuencode method does not always work. | 2322 @item The uuencode method does not always work. |
2065 | 2323 |
2066 Due to the design of @tramp{}, the encoding and decoding programs need to | 2324 Due to the design of @value{tramp}, the encoding and decoding programs |
2067 read from stdin and write to stdout. On some systems, @code{uudecode -o | 2325 need to read from stdin and write to stdout. On some systems, |
2068 -} will read stdin and write the decoded file to stdout, on other | 2326 @command{uudecode -o -} will read stdin and write the decoded file to |
2069 systems @code{uudecode -p} does the same thing. But some systems have | 2327 stdout, on other systems @command{uudecode -p} does the same thing. |
2070 uudecode implementations which cannot do this at all---it is not | 2328 But some systems have uudecode implementations which cannot do this at |
2071 possible to call these uudecode implementations with suitable parameters | 2329 all---it is not possible to call these uudecode implementations with |
2072 so that they write to stdout. | 2330 suitable parameters so that they write to stdout. |
2073 | 2331 |
2074 Of course, this could be circumvented: the @code{begin foo 644} line | 2332 Of course, this could be circumvented: the @code{begin foo 644} line |
2075 could be rewritten to put in some temporary file name, then | 2333 could be rewritten to put in some temporary file name, then |
2076 @code{uudecode} could be called, then the temp file could be printed and | 2334 @command{uudecode} could be called, then the temp file could be |
2077 deleted. | 2335 printed and deleted. |
2078 | 2336 |
2079 But I have decided that this is too fragile to reliably work, so on some | 2337 But I have decided that this is too fragile to reliably work, so on some |
2080 systems you'll have to do without the uuencode methods. | 2338 systems you'll have to do without the uuencode methods. |
2081 | 2339 |
2082 @item @tramp{} does not work on XEmacs 20. | 2340 @item @value{tramp} does not work on XEmacs 20. |
2083 | 2341 |
2084 This is because it requires the macro @code{with-timeout} which does not | 2342 This is because it requires the macro @code{with-timeout} which does not |
2085 appear to exist in XEmacs 20. I'm somewhat reluctant to add an | 2343 appear to exist in XEmacs 20. I'm somewhat reluctant to add an |
2086 emulation macro to @tramp{}, but if somebody who uses XEmacs 20 steps | 2344 emulation macro to @value{tramp}, but if somebody who uses XEmacs 20 steps |
2087 forward and wishes to implement and test it, please contact me or the | 2345 forward and wishes to implement and test it, please contact me or the |
2088 mailing list. | 2346 mailing list. |
2089 | 2347 |
2090 @item The @tramp{} filename syntax differs between Emacs and XEmacs. | 2348 @item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs. |
2091 | 2349 |
2092 The Emacs maintainers wish to use a unified filename syntax for | 2350 The GNU Emacs maintainers wish to use a unified filename syntax for |
2093 Ange-FTP and @tramp{} so that users don't have to learn a new | 2351 Ange-FTP and @value{tramp} so that users don't have to learn a new |
2094 syntax. It is sufficient to learn some extensions to the old syntax. | 2352 syntax. It is sufficient to learn some extensions to the old syntax. |
2095 | 2353 |
2096 For the XEmacs maintainers, the problems caused from using a unified | 2354 For the XEmacs maintainers, the problems caused from using a unified |
2097 filename syntax are greater than the gains. The XEmacs package system | 2355 filename syntax are greater than the gains. The XEmacs package system |
2098 uses EFS for downloading new packages. So, obviously, EFS has to be | 2356 uses EFS for downloading new packages. So, obviously, EFS has to be |
2099 installed from the start. If the filenames were unified, @tramp{} | 2357 installed from the start. If the filenames were unified, @value{tramp} |
2100 would have to be installed from the start, too. | 2358 would have to be installed from the start, too. |
2101 | 2359 |
2360 @ifset xemacs | |
2361 @strong{Note:} If you'ld like to use a similar syntax like | |
2362 @value{ftppackagename}, you need the following settings in your init | |
2363 file: | |
2364 | |
2365 @lisp | |
2366 (setq tramp-unified-filenames t) | |
2367 (require 'tramp) | |
2368 @end lisp | |
2369 | |
2370 The autoload of the @value{emacsname} @value{tramp} package must be | |
2371 disabled. This can be achieved by setting file permissions @code{000} | |
2372 to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}. | |
2373 | |
2374 In case of unified filenames, all @value{emacsname} download sites | |
2375 are added to @code{tramp-default-method-alist} with default method | |
2376 @option{ftp} @xref{Default Method}. These settings shouldn't be touched | |
2377 for proper working of the @value{emacsname} package system. | |
2378 | |
2379 The syntax for unified filenames is described in the @value{tramp} manual | |
2380 for @value{emacsothername}. | |
2381 @end ifset | |
2102 @end itemize | 2382 @end itemize |
2103 | 2383 |
2104 | 2384 @node Concept Index |
2385 @comment node-name, next, previous, up | |
2386 @unnumbered Concept Index | |
2387 @printindex cp | |
2388 @contents | |
2105 @c End of tramp.texi - the TRAMP User Manual | 2389 @c End of tramp.texi - the TRAMP User Manual |
2106 @bye | 2390 @bye |
2107 | 2391 |
2108 @c TODO | 2392 @c TODO |
2109 @c | 2393 @c |
2117 | 2401 |
2118 @c * M. Albinus | 2402 @c * M. Albinus |
2119 @c ** Use `filename' resp. `file name' consistently. | 2403 @c ** Use `filename' resp. `file name' consistently. |
2120 @c ** Use `host' resp. `machine' consistently. | 2404 @c ** Use `host' resp. `machine' consistently. |
2121 @c ** Consistent small or capitalized words especially in menues. | 2405 @c ** Consistent small or capitalized words especially in menues. |
2406 | |
2407 @ignore | |
2408 arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808 | |
2409 @end ignore |