5.6.1 Running remote programs that create local X11 windows

To allow a remote program to create an X11 window on the local host, set the DISPLAY environment variable for the remote host as follows in the local .emacs file:

(add-to-list 'tramp-remote-process-environment
             (format "DISPLAY=%s" (getenv "DISPLAY")))

(getenv "DISPLAY") should return a recognizable name for the local host that the remote host can redirect X11 window interactions. If querying for a recognizable name is not possible for whatever reason, then replace (getenv "DISPLAY") with a hard-coded, fixed name. Note that using :0 for X11 display name here will not work as expected.

An alternate approach is specify ForwardX11 yes or ForwardX11Trusted yes in ~/.ssh/config on the local host.

5.6.2 Running shell on a remote host

Set explicit-shell-file-name to the appropriate shell name when using TRAMP between two hosts with different operating systems, such as ‘windows-nt’ and ‘gnu/linux’. This option ensures the correct name of the remote shell program.

When explicit-shell-file-name is equal to nil, calling shell interactively will prompt for a shell name.

You could use connection-local variables for setting different values of explicit-shell-file-name for different remote hosts.

(connection-local-set-profile-variables
  'remote-bash
  '((explicit-shell-file-name . "/bin/bash")
    (explicit-bash-args . ("-i"))))

(connection-local-set-profile-variables
  'remote-ksh
  '((explicit-shell-file-name . "/bin/ksh")
    (explicit-ksh-args . ("-i"))))

(connection-local-set-profiles
  '(:application tramp :protocol "ssh" :machine "localhost")
  'remote-bash)

(connection-local-set-profiles
  `(:application tramp :protocol "sudo"
    :user "root" :machine ,(system-name))
  'remote-ksh)

5.6.3 Running shell-command on a remote host

shell-command executes commands synchronously or asynchronously on remote hosts and displays output in buffers on the local host. Example:

C-x C-f /sudo:: RET
M-& tail -f /var/log/syslog.log RET

tail command outputs continuously to the local buffer whose name is the value of the variable shell-command-buffer-name-async.

M-x auto-revert-tail-mode RET runs similarly showing continuous output.

shell-command uses the user option shell-file-name and the variable shell-command-switch in order to determine which shell to run. For remote hosts, their default values are /bin/sh and -c, respectively (except for the adb method, which uses /system/bin/sh). Like the variables in the previous section, these variables can be changed via connection-local variables.

If Emacs supports the user option async-shell-command-width (since Emacs 27), TRAMP cares about its value for asynchronous shell commands. It specifies the number of display columns for command output. For synchronous shell commands, a similar effect can be achieved by adding the environment variable COLUMNS to tramp-remote-process-environment.

5.6.4 Running eshell on a remote host

TRAMP is integrated into eshell.el, which enables interactive eshell sessions on remote hosts at the command prompt. You must add the module eshell-tramp to eshell-modules-list. Here’s a sample interaction after opening M-x eshell RET on a remote host:

~ $ cd /sudo::/etc RET
/sudo:root@host:/etc $ hostname RET
host
/sudo:root@host:/etc $ id RET
uid=0(root) gid=0(root) groups=0(root)
/sudo:root@host:/etc $ find-file shadow RET
#<buffer shadow>
/sudo:root@host:/etc $

eshell added custom su and sudo commands that set the default directory correctly for the *eshell* buffer. TRAMP silently updates tramp-default-proxies-alist with an entry for this directory (see Connecting to a remote host using multiple hops):

~ $ cd /ssh:user@remotehost:/etc RET
/ssh:user@remotehost:/etc $ find-file shadow RET
File is not readable: /ssh:user@remotehost:/etc/shadow
/ssh:user@remotehost:/etc $ sudo find-file shadow RET
#<buffer shadow>

/ssh:user@remotehost:/etc $ su - RET
/su:root@remotehost:/root $ id RET
uid=0(root) gid=0(root) groups=0(root)
/su:root@remotehost:/root $

5.6.5 Running a debugger on a remote host

gud.el provides a unified interface to symbolic debuggers. TRAMP can run debug on remote hosts by calling gdb with a remote file name:

M-x gdb RET
Run gdb (like this): gdb -i=mi /ssh:host:~/myprog RET

Since the remote gdb and gdb-inferior processes do not belong to the same process group on the remote host, there will be a warning, which can be ignored:

&"warning: GDB: Failed to set controlling terminal: Operation not permitted\n"

As consequence, there will be restrictions in I/O of the process to be debugged.

Relative file names are based on the remote default directory. When myprog.pl exists in /ssh:host:/home/user, valid calls include:

M-x perldb RET
Run perldb (like this): perl -d myprog.pl RET

Just the local part of a remote file name, such as perl -d /home/user/myprog.pl, is not possible.

Arguments of the program to be debugged must be literal, can take relative or absolute paths, but not remote paths.

5.6.6 Running remote processes on MS Windows hosts

winexe runs processes on a remote MS Windows host, and TRAMP can use it for process-file and start-file-process.

tramp-smb-winexe-program specifies the local winexe command. Powershell V2.0 on the remote host is required to run processes triggered from TRAMP.

explicit-shell-file-name and explicit-*-args have to be set properly so M-x shell RET can open a proper remote shell on a MS Windows host. To open cmd, set it as follows:

(setq explicit-shell-file-name "cmd"
      explicit-cmd-args '("/q"))

To open powershell as a remote shell, use this:

(setq explicit-shell-file-name "powershell"
      explicit-powershell-args '("-file" "-"))

5.6.7 Remote process connection type

Asynchronous processes behave differently based on whether they use a pseudo tty or not. This is controlled by the variable process-connection-type, which can be t or pty (use a pseudo tty), or nil or pipe (don’t use one). TRAMP is based on running shells on the remote host, which requires a pseudo tty. Therefore, it declares the variable tramp-process-connection-type, which carries this information for remote processes. Its default value is t, and there is no need to change it. The name of the remote pseudo tty is returned by the function process-tty-name.

If a remote process, started by start-file-process, should not use a pseudo tty, this can be requested by setting process-connection-type to nil or pipe. There is still a pseudo tty for the started process, but some terminal properties are changed, like suppressing translation of carriage return characters into newline.

The function make-process allows controlling this explicitly by using the :connection-type keyword. If this keyword is not used, the value of process-connection-type is applied instead.

5.6.8 Process properties of asynchronous remote processes

When available, TRAMP adds process properties to process objects of asynchronous properties. However, it is not guaranteed that all these properties are set.

• remote-tty

  This is the name of the terminal a process uses on the remote host, i.e., it reads and writes on.

• remote-pid

  The process id of the command executed on the remote host. This is used when sending signals remotely.

• remote-command

  The remote command which has been invoked via make-process or start-file-process, a list of strings (program and its arguments). This does not show the additional shell sugar TRAMP makes around the commands, in order to see this you must inspect TRAMP traces.

The functions list-system-processes and process-attributes return information about system processes on the respective remote host. In order to retrieve this information, they use the command ps, driven by the following constants:

Constant: tramp-process-attributes-ps-args ¶

This is a list of arguments (strings) ps is called with. The default value is appropriate for GNU/Linux remote hosts.

Constant: tramp-process-attributes-ps-format ¶

This is a list of cons cells (key . type) for interpretation of the ps output. key is a key used in the process-attributes output plus the key pid, and type is the respective value returned by ps. It can be

• numberp	— a number
• stringp	— a string without spaces
• number	— a string of number width, could contain spaces
• nil	— a string until end of line

The default value is appropriate for GNU/Linux remote hosts.

If, for example, tramp-process-attributes-ps-args is declared as ("-eww" "-o" "pid,euid,euser,egid,egroup,comm:40,state"), the output of the respective ps command would look like

    PID  EUID EUSER     EGID EGROUP   COMMAND                                  S
      1     0 root         0 root     systemd                                  S
   1610     0 root         0 root     NFSv4 callback                           S
   …

The corresponding tramp-process-attributes-ps-format has the value

((pid . numberp) (euid . numberp) (user . stringp)
 (egid . numberp) (group . stringp) (comm . 40) (state . stringp))

The default values for tramp-process-attributes-ps-args and tramp-process-attributes-ps-format can be overwritten by connection-local variables. This is already done by TRAMP for the adb method, see tramp-adb-connection-local-default-ps-profile and tramp-adb-connection-local-default-ps-variables.

There are three further predefined sets of connection-local variables for remote BSD systems, for remote macOS systems, and for a remote ps command implemented with busybox. These are called tramp-connection-local-*-ps-profile and tramp-connection-local-*-ps-variables. Use them like

(connection-local-set-profiles
 '(:application tramp :machine "mybsdhost")
 'tramp-connection-local-bsd-ps-profile)

If you want to see a listing of remote system processes when calling proced, set user option proced-show-remote-processes to non-nil, or invoke that command with a negative argument like C-u - M-x proced RET when your buffer has a remote default-directory.

5.6.9 Improving performance of asynchronous remote processes

TRAMP’s implementation of make-process and start-file-process requires a serious overhead for initialization, every process invocation. This is needed for handling interactive dialogs when connecting the remote host (like providing a password), and initial environment setup.

Sometimes, this is not needed. Instead of starting a remote shell and running the command afterwards, it is sufficient to run the command directly. TRAMP supports this by an alternative implementation of make-process and start-file-process. This is triggered by the connection property "direct-async-process", See Setting own connection related information, which must be set to a non-nil value. Example:

(add-to-list 'tramp-connection-properties
             (list (regexp-quote "/ssh:user@host:")
                   "direct-async-process" t))

Using direct asynchronous processes in TRAMP is not possible, if the remote host is connected via multiple hops (see Connecting to a remote host using multiple hops). In this case, TRAMP falls back to its classical implementation.

Furthermore, this approach has the following limitations:

• It works only for some connection methods defined in tramp-adb.el, tramp-container.el, tramp-sh.el and tramp-sshfs.el.
• It does not support interactive user authentication. With ssh-based methods, this can be avoided by using a password agent like ssh-agent, using public key authentication, or using ControlMaster options.
• It cannot be applied for ssh-based methods, which use the RemoteCommand option.
• It cannot be killed via interrupt-process.
• It does not report the remote terminal name via process-tty-name.
• It does not set process property remote-pid.
• It does not use tramp-remote-path.

In order to gain even more performance, it is recommended to bind tramp-verbose to 0 when running make-process or start-file-process. Furthermore, you might set tramp-use-ssh-controlmaster-options to nil in order to bypass TRAMP’s handling of the ControlMaster options, and use your own settings in ~/.ssh/config, Using ssh connection sharing.