forked from fgeller/emacs-mac-port
/
tramp.info
3694 lines (2884 loc) · 161 KB
/
tramp.info
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is /misc/emacs/bzr/emacs24-merge/doc/misc/../../info/tramp.info,
produced by makeinfo version 4.13 from
/misc/emacs/bzr/emacs24-merge/doc/misc/tramp.texi.
Copyright (C) 1999-2013 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being "A GNU Manual", and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
"GNU Free Documentation License".
(a) The FSF's Back-Cover Text is: "You have the freedom to copy
and modify this GNU manual."
INFO-DIR-SECTION Emacs network features
START-INFO-DIR-ENTRY
* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
Emacs remote file access via rsh and rcp.
END-INFO-DIR-ENTRY
File: tramp.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
TRAMP version 2.2.6-24.3 User Manual
************************************
This file documents TRAMP version 2.2.6-24.3, a remote file editing
package for Emacs.
TRAMP stands for `Transparent Remote (file) Access, Multiple
Protocol'. This package provides remote file editing, similar to
Ange-FTP.
The difference is that Ange-FTP uses FTP to transfer files between
the local and the remote host, whereas TRAMP uses a combination of
`rsh' and `rcp' or other work-alike programs, such as `ssh'/`scp'.
You can find the latest version of this document on the web at
`http://www.gnu.org/software/tramp/'.
There is a mailing list for TRAMP, available at
<tramp-devel@gnu.org>, and archived at the TRAMP Mail Archive
(http://lists.gnu.org/archive/html/tramp-devel/).
Copyright (C) 1999-2013 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being "A GNU Manual", and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
"GNU Free Documentation License".
(a) The FSF's Back-Cover Text is: "You have the freedom to copy
and modify this GNU manual."
* Menu:
* Overview:: What TRAMP can and cannot do.
For the end user:
* Obtaining Tramp:: How to obtain TRAMP.
* History:: History of TRAMP.
* Configuration:: Configuring TRAMP for use.
* Usage:: An overview of the operation of TRAMP.
* Bug Reports:: Reporting Bugs and Problems.
* Frequently Asked Questions:: Questions and answers from the mailing list.
* Function Index:: TRAMP functions.
* Variable Index:: User options and variables.
* Concept Index:: An item for each concept.
For the developer:
* Files directories and localnames:: How file names, directories and localnames are mangled and managed.
* Traces and Profiles:: How to Customize Traces.
* Issues:: Debatable Issues and What Was Decided.
* GNU Free Documentation License:: The license for this documentation.
--- The Detailed Node Listing ---
Configuring TRAMP for use
* Connection types:: Types of connections made to remote machines.
* Inline methods:: Inline methods.
* External methods:: External methods.
* GVFS based methods:: GVFS based external methods.
* Gateway methods:: Gateway methods.
* Default Method:: Selecting a default method.
* Default User:: Selecting a default user.
* Default Host:: Selecting a default host.
* Multi-hops:: Connecting to a remote host using multiple hops.
* Customizing Methods:: Using Non-Standard Methods.
* Customizing Completion:: Selecting config files for user/host name completion.
* Password handling:: Reusing passwords for several connections.
* Connection caching:: Reusing connection related information.
* Remote Programs:: How TRAMP finds and uses programs on the remote machine.
* Remote shell setup:: Remote shell setup hints.
* Windows setup hints:: Issues with Cygwin ssh.
* Auto-save and Backup:: Auto-save and Backup.
Using TRAMP
* Filename Syntax:: TRAMP filename conventions.
* Alternative Syntax:: URL-like filename syntax.
* Filename completion:: Filename completion.
* Ad-hoc multi-hops:: Declaring multiple hops in the file name.
* Remote processes:: Integration with other Emacs packages.
* Cleanup remote connections:: Cleanup remote connections.
How file names, directories and localnames are mangled and managed
* Localname deconstruction:: Breaking a localname into its components.
* External packages:: Integration with external Lisp packages.
File: tramp.info, Node: Overview, Next: Obtaining Tramp, Prev: Top, Up: Top
1 An overview of TRAMP
**********************
After the installation of TRAMP into your Emacs, you will be able to
access files on remote machines as though they were local. Access to
the remote file system for editing files, version control, and `dired'
are transparently enabled.
Your access to the remote machine can be with the `rsh', `rlogin',
`telnet' programs or with any similar connection method. This
connection must pass ASCII successfully to be usable but need not be
8-bit clean.
The package provides support for `ssh' connections out of the box,
one of the more common uses of the package. This allows relatively
secure access to machines, especially if `ftp' access is disabled.
Under Windows, TRAMP is integrated with the PuTTY package, using the
`plink' program.
The majority of activity carried out by TRAMP requires only that the
remote login is possible and is carried out at the terminal. In order
to access remote files TRAMP needs to transfer their content to the
local machine temporarily.
TRAMP can transfer files between the machines in a variety of ways.
The details are easy to select, depending on your needs and the
machines in question.
The fastest transfer methods for large files rely on a remote file
transfer package such as `rcp', `scp', `rsync' or (under Windows)
`pscp'.
If the remote copy methods are not suitable for you, TRAMP also
supports the use of encoded transfers directly through the shell. This
requires that the `mimencode' or `uuencode' tools are available on the
remote machine. These methods are generally faster for small files.
TRAMP is still under active development and any problems you
encounter, trivial or major, should be reported to the TRAMP developers.
*Note Bug Reports::.
Behind the scenes
.................
This section tries to explain what goes on behind the scenes when you
access a remote file through TRAMP.
Suppose you type `C-x C-f' and enter part of an TRAMP file name,
then hit `<TAB>' for completion. Suppose further that this is the
first time that TRAMP is invoked for the host in question. Here's what
happens:
* TRAMP discovers that it needs a connection to the host. So it
invokes `telnet HOST' or `rsh HOST -l USER' or a similar tool to
connect to the remote host. Communication with this process
happens through an Emacs buffer, that is, the output from the
remote end goes into a buffer.
* The remote host may prompt for a login name (for `telnet'). The
login name is given in the file name, so TRAMP sends the login
name and a newline.
* The remote host may prompt for a password or pass phrase (for
`rsh' or for `telnet' after sending the login name). TRAMP
displays the prompt in the minibuffer, asking you for the password
or pass phrase.
You enter the password or pass phrase. TRAMP sends it to the
remote host, followed by a newline.
* TRAMP now waits for the shell prompt or for a message that the
login failed.
If TRAMP sees neither of them after a certain period of time (a
minute, say), then it issues an error message saying that it
couldn't find the remote shell prompt and shows you what the remote
host has sent.
If TRAMP sees a `login failed' message, it tells you so, aborts
the login attempt and allows you to try again.
* Suppose that the login was successful and TRAMP sees the shell
prompt from the remote host. Now TRAMP invokes `/bin/sh' because
Bourne shells and C shells have different command syntaxes.(1)
After the Bourne shell has come up, TRAMP sends a few commands to
ensure a good working environment. It turns off echoing, it sets
the shell prompt, and a few other things.
* Now the remote shell is up and it good working order. Remember,
what was supposed to happen is that TRAMP tries to find out what
files exist on the remote host so that it can do filename
completion.
So, TRAMP basically issues `cd' and `ls' commands and also
sometimes `echo' with globbing. Another command that is often
used is `test' to find out whether a file is writable or a
directory or the like. The output of each command is parsed for
the necessary operation.
* Suppose you are finished with filename completion, have entered
`C-x C-f', a full file name and hit `<RET>'. Now comes the time to
transfer the file contents from the remote host to the local host
so that you can edit them.
See above for an explanation of how TRAMP transfers the file
contents.
For inline transfers, TRAMP issues a command like `mimencode -b
/path/to/remote/file', waits until the output has accumulated in
the buffer that's used for communication, then decodes that output
to produce the file contents.
For external transfers, TRAMP issues a command like the following:
rcp user@host:/path/to/remote/file /tmp/tramp.4711
It then reads the local temporary file `/tmp/tramp.4711' into a
buffer and deletes the temporary file.
* You now edit the buffer contents, blithely unaware of what has
happened behind the scenes. (Unless you have read this section,
that is.) When you are finished, you type `C-x C-s' to save the
buffer.
* Again, TRAMP transfers the file contents to the remote host either
inline or external. This is the reverse of what happens when
reading the file.
I hope this has provided you with a basic overview of what happens
behind the scenes when you open a file with TRAMP.
---------- Footnotes ----------
(1) Invoking `/bin/sh' will fail if your login shell doesn't
recognize `exec /bin/sh' as a valid command. Maybe you use the Scheme
shell `scsh'...
File: tramp.info, Node: Obtaining Tramp, Next: History, Prev: Overview, Up: Top
2 Obtaining Tramp.
******************
TRAMP is freely available on the Internet and the latest release may be
downloaded from `ftp://ftp.gnu.org/gnu/tramp/'. This release includes
the full documentation and code for TRAMP, suitable for installation.
But Emacs (22 or later) includes TRAMP already, and there is a TRAMP
package for XEmacs, as well. So maybe it is easier to just use those.
But if you want the bleeding edge, read on...
For the especially brave, TRAMP is available from Git. The Git
version is the latest version of the code and may contain incomplete
features or new issues. Use these versions at your own risk.
Instructions for obtaining the latest development version of TRAMP
from Git can be found by going to the Savannah project page at the
following URL and then clicking on the Git link in the navigation bar
at the top.
`http://savannah.gnu.org/projects/tramp/'
Or follow the example session below:
] *cd ~/emacs*
] *git clone git://git.savannah.gnu.org/tramp.git*
Tramp developers use instead
] *git clone login@git.sv.gnu.org:/srv/git/tramp.git*
You should now have a directory `~/emacs/tramp' containing the latest
version of TRAMP. You can fetch the latest updates from the repository
by issuing the command:
] *cd ~/emacs/tramp*
] *git pull*
Once you've got updated files from the Git repository, you need to run
`autoconf' in order to get an up-to-date `configure' script:
] *cd ~/emacs/tramp*
] *autoconf*
File: tramp.info, Node: History, Next: Configuration, Prev: Obtaining Tramp, Up: Top
3 History of TRAMP
******************
Development was started end of November 1998. The package was called
`rssh.el', back then. It only provided one method to access a file,
using `ssh' to log in to a remote host and using `scp' to transfer the
file contents. After a while, the name was changed to `rcp.el', and
now it's TRAMP. Along the way, many more methods for getting a remote
shell and for transferring the file contents were added. Support for
VC was added.
After that, there were added the multi-hop methods in April 2000 and
the unification of TRAMP and Ange-FTP filenames in July 2002. In July
2004, multi-hop methods have been replaced by proxy hosts. Running
commands on remote hosts was introduced in December 2005. Support of
gateways exists since April 2007. GVFS integration started in February
2009. Remote commands on Windows hosts are available since September
2011. Ad-hoc multi-hop methods (with a changed syntax) have been
reenabled in November 2011.
In December 2001, TRAMP has been added to the XEmacs package
repository. Being part of the Emacs repository happened in June 2002,
the first release including TRAMP was Emacs 22.1.
TRAMP is also a Debian GNU/Linux package since February 2001.
File: tramp.info, Node: Configuration, Next: Usage, Prev: History, Up: Top
4 Configuring TRAMP for use
***************************
TRAMP is (normally) fully functional when it is initially installed.
It is initially configured to use the `scp' program to connect to the
remote host. So in the easiest case, you just type `C-x C-f' and then
enter the filename `/user@machine:/path/to.file'.
On some hosts, there are problems with opening a connection. These
are related to the behavior of the remote shell. See *Note Remote
shell setup::, for details on this.
If you do not wish to use these commands to connect to the remote
host, you should change the default connection and transfer method that
TRAMP uses. There are several different methods that TRAMP can use to
connect to remote machines and transfer files (*note Connection
types::).
If you don't know which method is right for you, see *Note Default
Method::.
* Menu:
* Connection types:: Types of connections made to remote machines.
* Inline methods:: Inline methods.
* External methods:: External methods.
* GVFS based methods:: GVFS based external methods.
* Gateway methods:: Gateway methods.
* Default Method:: Selecting a default method.
Here we also try to help those who
don't have the foggiest which method
is right for them.
* Default User:: Selecting a default user.
* Default Host:: Selecting a default host.
* Multi-hops:: Connecting to a remote host using multiple hops.
* Customizing Methods:: Using Non-Standard Methods.
* Customizing Completion:: Selecting config files for user/host name completion.
* Password handling:: Reusing passwords for several connections.
* Connection caching:: Reusing connection related information.
* Remote Programs:: How TRAMP finds and uses programs on the remote machine.
* Remote shell setup:: Remote shell setup hints.
* Auto-save and Backup:: Auto-save and Backup.
* Windows setup hints:: Issues with Cygwin ssh.
File: tramp.info, Node: Connection types, Next: Inline methods, Up: Configuration
4.1 Types of connections made to remote machines
================================================
There are two basic types of transfer methods, each with its own
advantages and limitations. Both types of connection make use of a
remote shell access program such as `rsh', `ssh' or `telnet' to connect
to the remote machine.
This connection is used to perform many of the operations that TRAMP
requires to make the remote file system transparently accessible from
the local machine. It is only when visiting files that the methods
differ.
Loading or saving a remote file requires that the content of the file
be transferred between the two machines. The content of the file can
be transferred using one of two methods: the "inline method" over the
same connection used to log in to the remote machine, or the "external
method" through another connection using a remote copy program such as
`rcp', `scp' or `rsync'.
The performance of the external methods is generally better than that
of the inline methods, at least for large files. This is caused by the
need to encode and decode the data when transferring inline.
The one exception to this rule are the `scp' based transfer methods.
While these methods do see better performance when actually
transferring files, the overhead of the cryptographic negotiation at
startup may drown out the improvement in file transfer times.
External methods should be configured such a way that they don't
require a password (with `ssh-agent', or such alike). Modern `scp'
implementations offer options to reuse existing `ssh' connections, see
method `scpc'. If it isn't possible, you should consider *note
Password handling::, otherwise you will be prompted for a password
every copy action.
File: tramp.info, Node: Inline methods, Next: External methods, Prev: Connection types, Up: Configuration
4.2 Inline methods
==================
The inline methods in TRAMP are quite powerful and can work in
situations where you cannot use an external transfer program to connect.
Inline methods are the only methods that work when connecting to the
remote machine via telnet. (There are also strange inline methods which
allow you to transfer files between _user identities_ rather than
hosts, see below.)
These methods depend on the existence of a suitable encoding and
decoding command on remote machine. Locally, TRAMP may be able to use
features of Emacs to decode and encode the files or it may require
access to external commands to perform that task.
TRAMP checks the availability and usability of commands like
`mimencode' (part of the `metamail' package) or `uuencode' on the
remote host. The first reliable command will be used. The search path
can be customized, see *note Remote Programs::.
If both commands aren't available on the remote host, TRAMP
transfers a small piece of Perl code to the remote host, and tries to
apply it for encoding and decoding.
The variable TRAMP-INLINE-COMPRESS-START-SIZE controls, whether a
file shall be compressed before encoding. This could increase transfer
speed for large text files.
`rsh'
Connect to the remote host with `rsh'. Due to the unsecure
connection it is recommended for very local host topology only.
On operating systems which provide the command `remsh' instead of
`rsh', you can use the method `remsh'. This is true for HP-UX or
Cray UNICOS, for example.
`ssh'
Connect to the remote host with `ssh'. This is identical to the
previous option except that the `ssh' package is used, making the
connection more secure.
There are also two variants, `ssh1' and `ssh2', that call `ssh -1'
and `ssh -2', respectively. This way, you can explicitly select
whether you want to use the SSH protocol version 1 or 2 to connect
to the remote host. (You can also specify in `~/.ssh/config', the
SSH configuration file, which protocol should be used, and use the
regular `ssh' method.)
All the methods based on `ssh' have an additional feature: you can
specify a host name which looks like `host#42' (the real host
name, then a hash sign, then a port number). This means to
connect to the given host but to also pass `-p 42' as arguments to
the `ssh' command.
`telnet'
Connect to the remote host with `telnet'. This is as unsecure as
the `rsh' method.
`su'
This method does not connect to a remote host at all, rather it
uses the `su' program to allow you to edit files as another user.
That means, the specified host name in the file name must be either
`localhost' or the host name as returned by the function
`(system-name)'. For an exception of this rule see *note
Multi-hops::.
`sudo'
This is similar to the `su' method, but it uses `sudo' rather than
`su' to become a different user.
Note that `sudo' must be configured to allow you to start a shell
as the user. It would be nice if it was sufficient if `ls' and
`mimencode' were allowed, but that is not easy to implement, so I
haven't got around to it, yet.
`sshx'
As you would expect, this is similar to `ssh', only a little
different. Whereas `ssh' opens a normal interactive shell on the
remote host, this option uses `ssh -t -t HOST -l USER /bin/sh' to
open a connection. This is useful for users where the normal
login shell is set up to ask them a number of questions when
logging in. This procedure avoids these questions, and just gives
TRAMP a more-or-less `standard' login shell to work with.
Note that this procedure does not eliminate questions asked by
`ssh' itself. For example, `ssh' might ask "Are you sure you want
to continue connecting?" if the host key of the remote host is not
known. TRAMP does not know how to deal with such a question
(yet), therefore you will need to make sure that you can log in
without such questions.
This is also useful for Windows users where `ssh', when invoked
from an Emacs buffer, tells them that it is not allocating a
pseudo tty. When this happens, the login shell is wont to not
print any shell prompt, which confuses TRAMP mightily.
This supports the `-p' argument.
`krlogin'
This method is also similar to `ssh'. It only uses the `krlogin
-x' command to log in to the remote host.
`ksu'
This is another method from the Kerberos suite. It behaves like
`su'.
`plink'
This method is mostly interesting for Windows users using the PuTTY
implementation of SSH. It uses `plink -ssh' to log in to the
remote host.
This supports the `-P' argument.
Additionally, the methods `plink1' and `plink2' are provided,
which call `plink -1 -ssh' or `plink -2 -ssh' in order to use SSH
protocol version 1 or 2 explicitly.
CCC: Do we have to connect to the remote host once from the command
line to accept the SSH key? Maybe this can be made automatic?
CCC: Say something about the first shell command failing. This
might be due to a wrong setting of `tramp-rsh-end-of-line'.
`plinkx'
Another method using PuTTY on Windows. Instead of host names, it
expects PuTTY session names, calling `plink -load SESSION -t"'.
User names are relevant only in case the corresponding session
hasn't defined a user name. Different port numbers must be
defined in the session.
File: tramp.info, Node: External methods, Next: GVFS based methods, Prev: Inline methods, Up: Configuration
4.3 External methods
====================
The external methods operate through multiple channels, using the
remote shell connection for many actions while delegating file
transfers to an external transfer utility.
This saves the overhead of encoding and decoding that multiplexing
the transfer through the one connection has with the inline methods.
Since external methods need their own overhead opening a new channel,
all files which are smaller than TRAMP-COPY-SIZE-LIMIT are still
transferred with the corresponding inline method. It should provide a
fair trade-off between both approaches.
`rcp'--`rsh' and `rcp'
This method uses the `rsh' and `rcp' commands to connect to the
remote machine and transfer files. This is probably the fastest
connection method available.
The alternative method `remcp' uses the `remsh' and `rcp'
commands. It should be applied on machines where `remsh' is used
instead of `rsh'.
`scp'--`ssh' and `scp'
Using `ssh' to connect to the remote host and `scp' to transfer
files between the machines is the best method for securely
connecting to a remote machine and accessing files.
The performance of this option is also quite good. It may be
slower than the inline methods when you often open and close small
files however. The cost of the cryptographic handshake at the
start of an `scp' session can begin to absorb the advantage that
the lack of encoding and decoding presents.
There are also two variants, `scp1' and `scp2', that call `ssh -1'
and `ssh -2', respectively. This way, you can explicitly select
whether you want to use the SSH protocol version 1 or 2 to connect
to the remote host. (You can also specify in `~/.ssh/config', the
SSH configuration file, which protocol should be used, and use the
regular `scp' method.)
All the `ssh' based methods support the `-p' feature where you can
specify a port number to connect to in the host name. For
example, the host name `host#42' tells TRAMP to specify `-p 42' in
the argument list for `ssh', and to specify `-P 42' in the
argument list for `scp'.
`sftp'--`ssh' and `sftp'
That is mostly the same method as `scp', but using `sftp' as
transfer command. So the same remarks are valid.
This command does not work like Ange-FTP, where `ftp' is called
interactively, and all commands are send from within this session.
Instead of, `ssh' is used for login.
This method supports the `-p' argument.
`rsync'--`ssh' and `rsync'
Using the `ssh' command to connect securely to the remote machine
and the `rsync' command to transfer files is almost identical to
the `scp' method.
While `rsync' performs much better than `scp' when transferring
files that exist on both hosts, this advantage is lost if the file
exists only on one side of the connection. A file can exists on
both the remote and local host, when you copy a file from/to a
remote host. When you just open a file from the remote host (or
write a file there), a temporary file on the local side is kept as
long as the corresponding buffer, visiting this file, is alive.
This method supports the `-p' argument.
`scpx'--`ssh' and `scp'
As you would expect, this is similar to `scp', only a little
different. Whereas `scp' opens a normal interactive shell on the
remote host, this option uses `ssh -t -t HOST -l USER /bin/sh' to
open a connection. This is useful for users where the normal
login shell is set up to ask them a number of questions when
logging in. This procedure avoids these questions, and just gives
TRAMP a more-or-less `standard' login shell to work with.
This is also useful for Windows users where `ssh', when invoked
from an Emacs buffer, tells them that it is not allocating a
pseudo tty. When this happens, the login shell is wont to not
print any shell prompt, which confuses TRAMP mightily.
This method supports the `-p' argument.
`scpc'--`ssh' and `scp'
Newer versions of `ssh' (for example OpenSSH 4) offer an option
`ControlMaster'. This allows `scp' to reuse an existing `ssh'
channel, which increases performance.
Before you use this method, you should check whether your `ssh'
implementation supports this option. Try from the command line
ssh localhost -o ControlMaster=yes /bin/true
If that command succeeds silently, then you can use `scpc'; but if
it fails like
command-line: line 0: Bad configuration option: ControlMaster
then you cannot use it. Note, that the option `ControlPersist',
if it is supported by your `ssh' version, must be set to `no'.
This method supports the `-p' argument.
`rsyncc'--`ssh' and `rsync'
Like the `scpc' method, `rsyncc' improves the underlying `ssh'
connection by the option `ControlMaster'. This allows `rsync' to
reuse an existing `ssh' channel, which increases performance.
This method supports the `-p' argument.
`pscp'--`plink' and `pscp'
This method is similar to `scp', but it uses the `plink' command
to connect to the remote host, and it uses `pscp' for transferring
the files. These programs are part of PuTTY, an SSH
implementation for Windows.
This method supports the `-P' argument.
`psftp'--`plink' and `psftp'
As you would expect, this method is similar to `sftp', but it uses
the `plink' command to connect to the remote host, and it uses
`psftp' for transferring the files. These programs are part of
PuTTY, an SSH implementation for Windows.
This method supports the `-P' argument.
`fcp'--`fsh' and `fcp'
This method is similar to `scp', but it uses the `fsh' command to
connect to the remote host, and it uses `fcp' for transferring the
files. `fsh/fcp' are a front-end for `ssh' which allow for
reusing the same `ssh' session for submitting several commands.
This avoids the startup overhead of `scp' (which has to establish
a secure connection whenever it is called). Note, however, that
you can also use one of the inline methods to achieve a similar
effect.
This method uses the command `fsh HOST -l USER /bin/sh -i' to
establish the connection, it does not work to just say `fsh HOST
-l USER'.
There is no inline method using `fsh' as the multiplexing provided
by the program is not very useful in our context. TRAMP opens
just one connection to the remote host and then keeps it open,
anyway.
`ftp'
This is not a native TRAMP method. Instead, it forwards all
requests to Ange-FTP.
`smb'--`smbclient'
This is another not native TRAMP method. It uses the `smbclient'
command on different Unices in order to connect to an SMB server.
An SMB server might be a Samba (or CIFS) server on another UNIX
host or, more interesting, a host running MS Windows. So far, it
is tested against MS Windows NT, MS Windows 2000, MS Windows XP,
MS Windows Vista, and MS Windows 7.
The first directory in the localname must be a share name on the
remote host. Remember that the `$' character, in which default
shares usually end, must be written `$$' due to environment
variable substitution in file names. If no share name is given
(i.e., remote directory `/'), all available shares are listed.
Since authorization is done on share level, you will always be
prompted for a password if you access another share on the same
host. This can be suppressed by *note Password handling::.
For authorization, MS Windows uses both a user name and a domain
name. Because of this, the TRAMP syntax has been extended: you can
specify a user name which looks like `user%domain' (the real user
name, then a percent sign, then the domain name). So, to connect
to the machine `melancholia' as user `daniel' of the domain
`BIZARRE', and edit `.emacs' in the home directory (share
`daniel$') I would specify the filename
`/smb:daniel%BIZARRE@melancholia:/daniel$$/.emacs'.
Depending on the Windows domain configuration, a Windows user
might be considered as domain user per default. In order to
connect as local user, the WINS name of that machine must be given
as domain name. Usually, it is the machine name in capital
letters. In the example above, the local user `daniel' would be
specified as
`/smb:daniel%MELANCHOLIA@melancholia:/daniel$$/.emacs'.
The domain name as well as the user name are optional. If no user
name is specified at all, the anonymous user (without password
prompting) is assumed. This is different from all other TRAMP
methods, where in such a case the local user name is taken.
The `smb' method supports the `-p' argument.
*Please note:* If Emacs runs locally under MS Windows, this method
isn't available. Instead, you can use UNC file names like
`//melancholia/daniel$$/.emacs'. The only disadvantage is that
there's no possibility to specify another user name.
File: tramp.info, Node: GVFS based methods, Next: Gateway methods, Prev: External methods, Up: Configuration
4.4 GVFS based external methods
===============================
The connection methods described in this section are based on GVFS
`http://en.wikipedia.org/wiki/GVFS'. Via GVFS, the remote filesystem
is mounted locally through FUSE. TRAMP uses this local mounted
directory internally.
The communication with GVFS is implemented via D-Bus messages.
Therefore, your Emacs must have D-Bus integration, *note D-Bus:
(dbus)Top.
`dav'
This method provides access to WebDAV files and directories. There
exists also the external method `davs', which uses SSL encryption
for the access.
Both methods support the port number specification as discussed
above.
`obex'
OBEX is an FTP-like access protocol for simple devices, like cell
phones. For the time being, TRAMP only supports OBEX over
Bluetooth.
`synce'
The `synce' method allows communication with Windows Mobile
devices. Beside GVFS for mounting remote files and directories via
FUSE, it also needs the SYNCE-GVFS plugin.
-- User Option: tramp-gvfs-methods
This customer option, a list, defines the external methods which
shall be used with GVFS. Per default, these are `dav', `davs',
`obex' and `synce'. Other possible values are `ftp', `sftp' and
`smb'.
File: tramp.info, Node: Gateway methods, Next: Default Method, Prev: GVFS based methods, Up: Configuration
4.5 Gateway methods
===================
Gateway methods are not methods to access a remote host directly.
These methods are intended to pass firewalls or proxy servers.
Therefore, they can be used for proxy host declarations (*note
Multi-hops::) only.
A gateway method must always come along with a method which supports
port setting. This is because TRAMP targets the accompanied method to
`localhost#random_port', from where the firewall or proxy server is
accessed.
Gateway methods support user name and password declarations. These
are used to authenticate towards the corresponding firewall or proxy
server. They can be passed only if your friendly administrator has
granted your access.
`tunnel'
This method implements an HTTP tunnel via the `CONNECT' command
(see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server shall
support this command.
As authentication method, only `Basic Authentication' (see RFC
2617) is implemented so far. If no port number is given in the
declaration, port `8080' is used for the proxy server.
`socks'
The `socks' method provides access to SOCKSv5 servers (see RFC
1928). `Username/Password Authentication' according to RFC 1929
is supported.
The default port number of the socks server is `1080', if not
specified otherwise.
File: tramp.info, Node: Default Method, Next: Default User, Prev: Gateway methods, Up: Configuration
4.6 Selecting a default method
==============================
When you select an appropriate transfer method for your typical usage
you should set the variable `tramp-default-method' to reflect that
choice. This variable controls which method will be used when a method
is not specified in the TRAMP file name. For example:
(setq tramp-default-method "ssh")
You can also specify different methods for certain user/host
combinations, via the variable `tramp-default-method-alist'. For
example, the following two lines specify to use the `ssh' method for
all user names matching `john' and the `rsync' method for all host
names matching `lily'. The third line specifies to use the `su' method
for the user `root' on the machine `localhost'.
(add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
(add-to-list 'tramp-default-method-alist '("lily" "" "rsync"))
(add-to-list 'tramp-default-method-alist
'("\\`localhost\\'" "\\`root\\'" "su"))
See the documentation for the variable `tramp-default-method-alist' for
more details.
External methods are normally preferable to inline methods, giving
better performance.
*Note Inline methods::. *Note External methods::.
Another consideration with the selection of transfer methods is the
environment you will use them in and, especially when used over the
Internet, the security implications of your preferred method.
The `rsh' and `telnet' methods send your password as plain text as
you log in to the remote machine, as well as transferring the files in
such a way that the content can easily be read from other machines.
If you need to connect to remote systems that are accessible from the
Internet, you should give serious thought to using `ssh' based methods
to connect. These provide a much higher level of security, making it a
non-trivial exercise for someone to obtain your password or read the
content of the files you are editing.
4.6.1 Which method is the right one for me?
-------------------------------------------
Given all of the above, you are probably thinking that this is all fine
and good, but it's not helping you to choose a method! Right you are.
As a developer, we don't want to boss our users around but give them
maximum freedom instead. However, the reality is that some users would
like to have some guidance, so here I'll try to give you this guidance
without bossing you around. You tell me whether it works ...
My suggestion is to use an inline method. For large files, external
methods might be more efficient, but I guess that most people will want
to edit mostly small files. And if you access large text files,
compression (driven by TRAMP-INLINE-COMPRESS-START-SIZE) shall still
result in good performance.
I guess that these days, most people can access a remote machine by
using `ssh'. So I suggest that you use the `ssh' method. So, type
`C-x C-f /ssh:root@otherhost:/etc/motd <RET>' to edit the `/etc/motd'
file on the other host.
If you can't use `ssh' to log in to the remote host, then select a
method that uses a program that works. For instance, Windows users
might like the `plink' method which uses the PuTTY implementation of
`ssh'. Or you use Kerberos and thus like `krlogin'.
For the special case of editing files on the local host as another
user, see the `su' or `sudo' methods. They offer shortened syntax for
the `root' account, like `/su::/etc/motd'.
People who edit large files may want to consider `scpc' instead of
`ssh', or `pscp' instead of `plink'. These external methods are faster
than inline methods for large files. Note, however, that external
methods suffer from some limitations. Please try first whether you
really get a noticeable speed advantage from using an external method!
Maybe even for large files, inline methods are fast enough.
File: tramp.info, Node: Default User, Next: Default Host, Prev: Default Method, Up: Configuration
4.7 Selecting a default user
============================
The user part of a TRAMP file name can be omitted. Usually, it is
replaced by the user name you are logged in. Often, this is not what
you want. A typical use of TRAMP might be to edit some files with root
permissions on the local host. This case, you should set the variable
`tramp-default-user' to reflect that choice. For example:
(setq tramp-default-user "root")
`tramp-default-user' is regarded as obsolete, and will be removed
soon.
You can also specify different users for certain method/host
combinations, via the variable `tramp-default-user-alist'. For
example, if you always have to use the user `john' in the domain
`somewhere.else', you can specify the following:
(add-to-list 'tramp-default-user-alist
'("ssh" ".*\\.somewhere\\.else\\'" "john"))
See the documentation for the variable `tramp-default-user-alist' for
more details.
One trap to fall in must be known. If TRAMP finds a default user,
this user will be passed always to the connection command as parameter
(for example `ssh here.somewhere.else -l john'. If you have specified
another user for your command in its configuration files, TRAMP cannot
know it, and the remote access will fail. If you have specified in the
given example in `~/.ssh/config' the lines
Host here.somewhere.else
User lily
than you must discard selecting a default user by TRAMP. This will be
done by setting it to `nil' (or `lily', likewise):
(add-to-list 'tramp-default-user-alist
'("ssh" "\\`here\\.somewhere\\.else\\'" nil))
The last entry in `tramp-default-user-alist' could be your default
user you'll apply predominantly. You shall _append_ it to that list at
the end:
(add-to-list 'tramp-default-user-alist '(nil nil "jonas") t)
File: tramp.info, Node: Default Host, Next: Multi-hops, Prev: Default User, Up: Configuration
4.8 Selecting a default host
============================
Finally, it is even possible to omit the host name part of a TRAMP file
name. This case, the value of the variable `tramp-default-host' is
used. Per default, it is initialized with the host name your local
Emacs is running.
If you, for example, use TRAMP mainly to contact the host `target'
as user `john', you can specify:
(setq tramp-default-user "john"
tramp-default-host "target")
Then the simple file name `/ssh::' will connect you to John's home
directory on target. Note, however, that the most simplification `/::'
won't work, because `/:' is the prefix for quoted file names.
File: tramp.info, Node: Multi-hops, Next: Customizing Methods, Prev: Default Host, Up: Configuration