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 RETEach involved method must be handled by TRAMP’s tramp-sh backend.
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 commands tramp-revert-buffer-with-sudo (C-x x @), and tramp-dired-find-file-with-sudo (@ in dired-mode) support this.
Command: tramp-revert-buffer-with-sudo
This command visits the current buffer with sudo permissions. The buffer must either visit a file, or a directory in dired-mode.
Command: tramp-dired-find-file-with-sudo
In dired-mode, visit the file or directory named on this line. This is performed with sudo permissions.
User Option: tramp-file-name-with-method
The method used in tramp-revert-buffer-with-sudo and tramp-dired-find-file-with-sudo. It defaults to sudo, other valid methods are su, doas, run0, and ksu. The value can be set connection-locally.
If a command is called with a prefix argument C-u, the option’s value is read interactively.
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"))5.4.1 Using different proxies for the same destination
Note: This feature is experimental, don’t use it in production systems!
Sometimes, it is needed to specify different proxies for the same destination host name. This can happen for the same destination when the local host is located in different networks over the time. This can also happen when the remote destination is specified by the remote same file name, although different hosts are meant depending on the used proxy. A typical example are docker containers, which run on different hosts under the same docker name.
When the user option tramp-show-ad-hoc-proxies is non-nil, such ad-hoc multi-hop file names can be used in parallel. In the following, on both remote hosts ‘host1’ and ‘host2’ there is a docker container ‘name’, respectively:
/ssh:user1@host1|docker:name:
/ssh:user2@host2|docker:name:If you use the shortened name ‘/docker:name:’, the last used proxy definition is expanded for.