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

3 Short introduction how to use TRAMP

TRAMP extends the Emacs file name syntax by adding a remote component. A remote file name always looks like /method:user@host:/path/to/file.

You can use remote files exactly like ordinary files, that means you can open a file or directory by C-x C-f /method:user@host:/path/to/file RET, edit the file, and save it. You can also mix local files and remote files in file operations with two arguments, like copy-file or rename-file. And finally, you can even run processes on a remote host, when the buffer you call the process from has a remote default-directory.

3.1 File name syntax

Remote file names have method, user and host parts prepended. All of them, and also the local file name part, are optional, in case of a missing part a default value is assumed. The default value for an empty local file name part is the remote user’s home directory. The shortest remote file name is thus /-::. The ‘-’ notation for the default method is used for syntactical reasons, Default Method.

The method part describes the connection method used to reach the remote host, see below.

The user part is the user name for accessing the remote host. For the smb method, this could also require a domain name, in which case it is written as user%domain.

The host part must be a host name which can be resolved on your local host. It could be a short host name, a fully qualified domain name, an IPv4 or IPv6 address, File name syntax. Some connection methods also support a notation for the port to be used, in which case it is written as host#port.

3.2 Using ssh and plink

If your local host runs an SSH client, and the remote host runs an SSH server, the simplest remote file name is /ssh:user@host:/path/to/file. The remote file name /ssh:: opens a remote connection to yourself on the local host, and is often used for testing TRAMP.

On MS Windows, PuTTY is often used as the SSH client. Its plink method can be used there to open a connection to a remote host running an ssh server: /plink:user@host:/path/to/file.

3.3 Using su, sudo, doas and sg

Sometimes, it is necessary to work on your local host under different permissions. For this, you can use the su or sudo connection method. On OpenBSD systems, the doas connection method offers the same functionality. These methods use ‘root’ as default user name and the return value of (system-name) as default host name. Therefore, it is convenient to open a file as /sudo::/path/to/file.

The method sg stands for “switch group”; here the user name is used as the group to change to. The default host name is the same.

3.4 Combining ssh or plink with su, sudo or doas

If the su, sudo or doas option should be performed on another host, it can be comnbined with a leading ssh or plink option. That means that TRAMP connects first to the other host with non-administrative credentials, and changes to administrative credentials on that host afterwards. In a simple case, the syntax looks like /ssh:user@host|sudo::/path/to/file. See Ad-hoc multi-hops.

3.5 Using sudoedit

The sudoedit method is similar to the sudo method. However, it is a different implementation: it does not keep an open session running in the background. This is for security reasons; on the backside this method has worse performance than the sudo method, it is restricted to ‘localhost’ only, and it does not support external processes.

3.6 Using smbclient

In order to access a remote MS Windows host or Samba server, the smbclient client is used. The remote file name syntax is /smb:user%domain@host:/path/to/file. The first part of the local file name is the share exported by the remote host, ‘path’ in this example.

3.7 Using GVFS-based methods

On systems which have GVFS (the GNOME Virtual File System) installed, its offered methods can be used by TRAMP. Examples are /sftp:user@host:/path/to/file, /afp:user@host:/path/to/file (accessing Apple’s AFP file system), /dav:user@host:/path/to/file, /davs:user@host:/path/to/file (for WebDAV shares) and /mtp:device:/path/to/file (for media devices).

3.8 Using GNOME Online Accounts based methods

GVFS-based methods also include GNOME Online Accounts, which support the Files service. These are the Google Drive file system, and the OwnCloud/NextCloud file system. The file name syntax here is always / (‘’ stands here for your Google Drive account), or /nextcloud:user@host#8081:/path/to/file (‘8081’ stands for the port number) for OwnCloud/NextCloud files.

3.9 Using FUSE-based methods

FUSE (Filesystem in Userspace) allows users to mount a virtual file system. It is also used by GVFS internally, but here we discuss methods which do not use the GVFS API.

A convenient way to access system storages is the rclone program. If you have configured a storage in rclone under a name ‘storage’ (for example), you can access it via the remote file name syntax /rclone:storage:/path/to/file. User names are not needed.

On local hosts which have installed the sshfs client for mounting a file system based on sftp, this method can be used. All remote files are available via the local mount point. TRAMP aids in mounting the file system if it isn’t mounted yet, and it supports the access with the usual file name syntax /sshfs:user@host:/path/to/file.

3.10 Using Android

An Android device, which is connected via USB to your local host, can be accessed via the adb command. No user or host name is needed. The file name syntax is /adb::/path/to/file.

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