Next: , Previous: , Up: Configuration   [Contents][Index]

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

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

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 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

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. It supports changing the remote login shell /bin/sh.

scpx is useful for MS 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
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 MS Windows.

They support changing the remote login shell /bin/sh.

Check the ‘Share SSH connections if possible’ control for that session.

These methods support the ‘-P’ argument.

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

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.

sudoedit

The sudoedit method allows to edit a file as a different user on the local host. You could regard this as TRAMP’s implementation of the sudoedit. Contrary to the sudo method, all magic file name functions are implemented by single sudo … commands. The purpose is to make editing such a file as secure as possible; there must be no session running in the Emacs background which could be attacked from inside Emacs.

Consequently, external processes are not implemented.

The host name of such remote file names must represent the local host. Since the default value is already proper, it is recommended not to use any host name in the remote file name, like /sudoedit::/path/to/file or /sudoedit:user@:/path/to/file.

Like the sudo method, a sudoedit password expires after a predefined timeout.

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

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 some SMB share names 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 the user name, % is the percent symbol, and domain is the MS 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 MS 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 user option tramp-adb-program.

TRAMP connects to Android devices with adb only when the user 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.

rclone

The program rclone allows to access different system storages in the cloud, see https://rclone.org/ for a list of supported systems. If the rclone program isn’t found in your PATH environment variable, you can tell TRAMP its absolute path via the user option tramp-rclone-program.

A system storage must be configured via the rclone config command, outside Emacs. If you have configured a storage in rclone under a name ‘storage’ (for example), you could access it via the remote file name

/rclone:storage:/path/to/file

User names are part of the rclone configuration, and not needed in the remote file name. If a user name is contained in the remote file name, it is ignored.

Internally, TRAMP mounts the remote system storage at location /tmp/tramp.rclone.storage, with storage being the name of the configured system storage.

Optional flags to the different rclone operations could be passed as connection property, See Predefined connection information. Supported properties are "mount-args", "copyto-args" and "moveto-args".

Access via rclone is slow. If you have an alternative method for accessing the system storage, you shall prefer this. GVFS-based methods for example, methods gdrive and nextcloud.

Note: The rclone method is experimental, don’t use it in production systems!

Next: , Previous: , Up: Configuration   [Contents][Index]