Declaring multiple hops in the file name

TRAMP file name syntax can accommodate ad-hoc specification of multiple proxies without using tramp-default-proxies-alist configuration setup (see Connecting to a remote host using multiple hops).

Each proxy is specified using the same syntax as the remote host specification minus the file name part. Each hop is separated by a ‘|’. Chain the proxies from the starting host to the destination remote host name and file name. For example, hopping over a single proxy ‘bird@bastion’ to a remote file on ‘you@remotehost’:

C-x C-f /ssh:bird@bastion|ssh:you@remotehost:/path RET

Each involved method must be an inline method (see Inline methods).

TRAMP adds the ad-hoc definitions as an ephemeral record to tramp-default-proxies-alist, which are available for reuse during that Emacs session. Subsequent TRAMP connections to the same remote host can then use the abbreviated form /ssh:you@remotehost:/path.

User Option: tramp-show-ad-hoc-proxies

If this user option is non-nil, ad-hoc definitions are kept in remote file names instead of showing the abbreviations. This is useful if the ad-hoc proxy definition shall be used in further Emacs sessions, kept in configuration files of recentf and other packages.

A non-nil setting of this option has effect only if set before the connection is established.

(customize-set-variable 'tramp-show-ad-hoc-proxies t)

Ad-hoc definitions are removed from tramp-default-proxies-alist via the command M-x tramp-cleanup-all-connections RET (see Cleanup remote connections).

User Option: tramp-save-ad-hoc-proxies

For ad-hoc definitions to be saved automatically in tramp-default-proxies-alist for future Emacs sessions, set tramp-save-ad-hoc-proxies to non-nil. The resulting user option tramp-default-proxies-alist is saved in your .emacs file.

If you use saved configuration files with abbreviated ad-hoc proxy definitions on another host, for example by distribution of the recentf-save-file, you must distribute your .emacs file as well.

(customize-set-variable 'tramp-save-ad-hoc-proxies t)

Ad-hoc proxies can take patterns %h or %u like in tramp-default-proxies-alist. The following file name expands to user ‘root’ on host ‘remotehost’, starting with an ssh session on host ‘remotehost’: /ssh:%h|su:remotehost:.

On the other hand, if a trailing hop does not specify a host name, the host name of the previous hop is reused. Therefore, the following file name is equivalent to the previous example: /ssh:remotehost|su::.

User Option: tramp-completion-multi-hop-methods

When this list includes the last method in a multi-hop connection, the remote host will be queried for a list of completion candidates. This can, for example, provide a list of running docker or podman containers on the remote host.

(customize-set-variable 'tramp-completion-multi-hop-methods
 `(,tramp-docker-method ,tramp-podman-method))

A common use case for ad-hoc specifications is to visit a file or a directory with proper permissions, for example with the sudo method. The command tramp-revert-buffer-with-sudo supports this.

Command: tramp-revert-buffer-with-sudo

This command shows the current buffer with sudo permissions. The buffer must either visit a file, or a directory (dired-mode).

User Option: tramp-file-name-with-method

The method tramp-revert-buffer-with-sudo shows an alternate buffer. It defaults to sudo, other valid methods are su, doas, run0, and ksu.

(customize-set-variable 'tramp-file-name-with-method "doas")

These methods apply the user ‘root’ as default. If another user shall be taken, add a proper rule to the user option tramp-default-user-alist (see Selecting a default user):

(add-to-list 'tramp-default-user-alist '("sudo" "remotehost" "admin"))