5.5 Integration with other Emacs packages

tramp supports running processes on a remote host. This allows to exploit Emacs packages without modification for remote file names. It does not work for the ftp method. Association of a pty, as specified in start-file-process, is not supported.

process-file and start-file-process work on the remote host when the variable default-directory is remote:

     (let ((default-directory "/ssh:remote.host:"))
       (start-file-process "grep" (get-buffer-create "*grep*")
                           "/bin/sh" "-c" "grep -e tramp *"))

If the remote host is mounted via GVFS (see GVFS based methods), the remote filesystem is mounted locally. Therefore, there are no remote processes; all processes run still locally on your machine with an adapted default-directory. This section does not apply for such connection methods.

Remote processes are started when a corresponding command is executed from a buffer belonging to a remote file or directory. Up to now, the packages compile.el (commands like compile and grep) and gud.el (gdb or perldb) have been integrated. Integration of further packages is planned, any help for this is welcome!

When your program is not found in the default search path tramp sets on the remote machine, you should either use an absolute path, or extend tramp-remote-path (see Remote Programs):

     (add-to-list 'tramp-remote-path "~/bin")
     (add-to-list 'tramp-remote-path "/appli/pub/bin")

The environment for your program can be adapted by customizing tramp-remote-process-environment. This variable is a list of strings. It is structured like process-environment. Each element is a string of the form "ENVVARNAME=VALUE". An entry "ENVVARNAME=" disables the corresponding environment variable, which might have been set in your init file like ~/.profile.

Adding an entry can be performed via add-to-list:

     (add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")

Changing or removing an existing entry is not encouraged. The default values are chosen for proper tramp work. Nevertheless, if for example a paranoid system administrator disallows changing the HISTORY environment variable, you can customize tramp-remote-process-environment, or you can apply the following code in your .emacs:

     (let ((process-environment tramp-remote-process-environment))
       (setenv "HISTORY" nil)
       (setq tramp-remote-process-environment process-environment))

If you use other Emacs packages which do not run out-of-the-box on a remote host, please let us know. We will try to integrate them as well. See Bug Reports.

5.5.1 Running remote programs that create local X11 windows

If you want to run a remote program, which shall connect the X11 server you are using with your local host, you can set the DISPLAY environment variable on the remote host:

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

(getenv "DISPLAY") shall return a string containing a host name, which can be interpreted on the remote host; otherwise you might use a fixed host name. Strings like :0 cannot be used properly on the remote host.

Another trick might be that you put ForwardX11 yes or ForwardX11Trusted yes to your ~/.ssh/config file for that host.

5.5.2 Running shell on a remote host

Calling M-x shell in a buffer related to a remote host runs the local shell as defined in shell-file-name. This might be also a valid path name for a shell to be applied on the remote host, but it will fail at least when your local and remote hosts belong to different system types, like ‘windows-nt’ and ‘gnu/linux’.

You must set the variable explicit-shell-file-name to the shell path name on the remote host, in order to start that shell on the remote host.

Starting with Emacs 24 this won't be necessary, if you call shell interactively. You will be asked for the remote shell path, if you are on a remote buffer, and if explicit-shell-file-name is equal to nil.

5.5.3 Running shell-command on a remote host

shell-command allows to execute commands in a shell, either synchronously, either asynchronously. This works also on remote hosts. Example:

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

You will see the buffer *Async Shell Command*, containing the continuous output of the tail command.

A similar behaviour can be reached by M-x auto-revert-tail-mode, if available.

5.5.4 Running eshell on a remote host

tramp is integrated into eshell.el. That is, you can open an interactive shell on your remote host, and run commands there. After you have started M-x eshell, you could perform commands like this:

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

Since Emacs 23.2, eshell has also an own implementation of the su and sudo commands. Both commands change the default directory of the *eshell* buffer to the value related to the user the command has switched to. This works even on remote hosts, adding silently a corresponding entry to the variable tramp-default-proxies-alist (see Multi-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.5.5 Running a debugger on a remote host

gud.el offers an unified interface to several symbolic debuggers With tramp, it is possible to debug programs on remote hosts. You can call gdb with a remote file name:

     M-x gdb <RET>
     Run gdb (like this): gdb --annotate=3 /ssh:host:~/myprog <RET>

The file name can also be relative to a remote default directory. Given you are in a buffer that belongs to the remote directory /ssh:host:/home/user, you could call

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

It is not possible to use just the absolute local part of a remote file name as program to debug, like perl -d /home/user/myprog.pl, though.

Arguments of the program to be debugged are taken literally. That means, file names as arguments must be given as ordinary relative or absolute file names, without any remote specification.

5.5.6 Running remote processes on Windows hosts

With the help of the winexe it is possible tu run processes on a remote Windows host. tramp has implemented this for process-file and start-file-process.

The variable tramp-smb-winexe-program must contain the file name of your local winexe command. On the remote host, Powershell V2.0 must be installed; it is used to run the remote process.

In order to open a remote shell on the Windows host via M-x shell, you must set the variables explicit-shell-file-name and explicit-*-args. If you want, for example, run cmd, you must set:

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

In case of running powershell as remote shell, the settings are

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