tramp: External methods
4.3 External methods
====================
External methods operate over multiple channels, using the remote shell
connection for some actions while delegating file transfers to an
external transfer program.
External methods save on the overhead of encoding and decoding of
inline methods.
Since external methods have the overhead of opening a new channel,
files smaller than TRAMP-COPY-SIZE-LIMIT still use inline methods.
‘rcp’—‘rsh’ and ‘rcp’
This method uses the ‘rsh’ and ‘rcp’ commands to connect to the
remote host and transfer files. This is the fastest access method
available.
The alternative method ‘remcp’ uses the ‘remsh’ and ‘rcp’ commands.
‘scp’—‘ssh’ and ‘scp’
Using a combination of ‘ssh’ to connect and ‘scp’ to transfer is
the most secure. While the performance is good, it is slower than
the inline methods for smaller files. Though there is no overhead
of encoding and decoding of the inline methods, ‘scp’’s
cryptographic handshake negates those speed gains.
‘ssh’-based methods support ‘-p’ feature for specifying port
numbers. For example, ‘host#42’ passes ‘-p 42’ in the argument
list to ‘ssh’, and ‘-P 42’ in the argument list to ‘scp’.
‘rsync’—‘ssh’ and ‘rsync’
‘ssh’ command to connect in combination with ‘rsync’ command to
transfer is similar to the ‘scp’ method.
‘rsync’ performs much better than ‘scp’ when transferring files
that exist on both hosts. However, this advantage is lost if the
file exists only on one side of the connection.
This method supports the ‘-p’ argument.
‘scpx’—‘ssh’ and ‘scp’
‘scpx’ is useful to avoid login shell questions. It is similar in
performance to ‘scp’. ‘scpx’ uses ‘ssh -t -t HOST -l USER /bin/sh’
to open a connection.
‘sshx’ is useful for Windows users when ‘ssh’ triggers an error
about allocating a pseudo tty. This happens due to missing shell
prompts that confuses TRAMP.
This method supports the ‘-p’ argument.
‘pscp’—‘plink’ and ‘pscp’
‘psftp’—‘plink’ and ‘psftp’
These methods are similar to ‘scp’ or ‘sftp’, but they use the
‘plink’ command to connect to the remote host, and they use ‘pscp’
or ‘psftp’ for transferring the files. These programs are part of
PuTTY, an SSH implementation for Windows.
Check the ‘Share SSH connections if possible’ control for that
session.
These methods support the ‘-P’ argument.
‘fcp’—‘fsh’ and ‘fcp’
This method is similar to ‘scp’, but uses ‘fsh’ to connect and
‘fcp’ to transfer files. ‘fsh/fcp’, a front-end for ‘ssh’, reuse
‘ssh’ session by submitting several commands. This avoids the
startup overhead due to ‘scp’’s secure connection. Inline methods
have similar benefits.
The command used for this connection is: ‘fsh HOST -l USER /bin/sh
-i’
‘fsh’ has no inline method since the multiplexing it offers is not
useful for TRAMP. ‘fsh’ connects to remote host and TRAMP keeps
that one connection open.
‘nc’—‘telnet’ and ‘nc’
Using ‘telnet’ to connect and ‘nc’ to transfer files is sometimes
the only combination suitable for accessing routers or NAS hosts.
These dumb devices have severely restricted local shells, such as
the ‘busybox’ and do not host any other encode or decode programs.
‘ftp’
When TRAMP uses ‘ftp’, it forwards requests to whatever ftp program
is specified by Ange-FTP. This external program must be capable of
servicing requests from TRAMP.
‘smb’—‘smbclient’
This non-native TRAMP method connects via the Server Message Block
(SMB) networking protocol to hosts running file servers that are
typically based on Samba or MS Windows.
Using ‘smbclient’ requires a few tweaks when working with TRAMP:
The first directory in the localname must be a share name on the
remote host.
Since SMB shares end in the ‘$’ character, TRAMP must use ‘$$’ when
specifying those shares to avoid environment variable
substitutions.
When TRAMP is not specific about the share name or uses the generic
remote directory ‘/’, ‘smbclient’ returns all available shares.
Since SMB authentication is based on each SMB share, TRAMP prompts
for a password even when accessing a different share on the same
SMB host. This prompting can be suppressed by 
Password
handling.
To accommodate user name/domain name syntax required by MS Windows
authorization, TRAMP provides for an extended syntax in
‘user%domain’ format (where user is username, ‘%’ is the percent
symbol, and domain is the windows domain name). An example:
/smb:daniel%BIZARRE@melancholia:/daniel$$/.emacs
where user ‘daniel’ connects as a domain user to the SMB host
‘melancholia’ in the windows domain ‘BIZARRE’ to edit ‘.emacs’
located in the home directory (share ‘daniel$’).
Alternatively, for local WINS users (as opposed to domain users),
substitute the domain name with the name of the local host in
UPPERCASE as shown here:
/smb:daniel%MELANCHOLIA@melancholia:/daniel$$/.emacs
where user ‘daniel’ connects as local user to the SMB host
‘melancholia’ in the local domain ‘MELANCHOLIA’ to edit ‘.emacs’
located in the home directory (share ‘daniel$’).
The domain name and user name are optional for ‘smbclient’
authentication. When user name is not specified, ‘smbclient’ uses
the anonymous user (without prompting for password). This behavior
is unlike other TRAMP methods, where local user name is
substituted.
The ‘smb’ method is unavailable if Emacs is run under a local user
authentication context in MS Windows. However such users can still
access remote files using UNC file names instead of TRAMP:
//melancholia/daniel$$/.emacs
UNC file name specification does not allow the specification of a
different user name for authentication like the ‘smbclient’ can.
‘adb’
This method uses Android Debug Bridge program for accessing Android
devices. The Android Debug Bridge must be installed locally for
TRAMP to work. Some GNU/Linux distributions provide Android Debug
Bridge as an installation package. Alternatively, the program is
installed as part of the Android SDK. TRAMP finds the ‘adb’
program either via the ‘PATH’ environment variable or the absolute
path set in the variable TRAMP-ADB-PROGRAM.
TRAMP connects to Android devices with ‘adb’ only when the custom
option ‘tramp-adb-connect-if-not-connected’ is not ‘nil’.
Otherwise, the connection must be established outside Emacs.
TRAMP does not require a host name part of the remote file name
when a single Android device is connected to ‘adb’. TRAMP instead
uses ‘/adb::’ as the default name. ‘adb devices’ shows available
host names.
‘adb’ method normally does not need user name to authenticate on
the Android device because it runs under the ‘adbd’ process. But
when a user name is specified, however, TRAMP applies an ‘su’ in
the syntax. When authentication does not succeed, especially on
un-rooted Android devices, TRAMP displays login errors.
For Android devices connected through TCP/IP, a port number can be
specified using ‘device#42’ host name syntax or TRAMP can use the
default value as declared in ‘adb’ command. Port numbers are not
applicable to Android devices connected through USB.
Info Catalog
tramp: Inline methods
tramp: Configuration
tramp: GVFS based methods