tramp: Remote processes
5.4 Integration with other Emacs packages
=========================================
TRAMP supports starting new running processes on the remote host for
discovering remote file names. Emacs packages on the remote host need
no specific modifications for TRAMP’s use.
This type of integration does not work with the ‘ftp’ method, and
does not support the pty association as specified in
‘start-file-process’.
‘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 *"))
methods::) because the remote file system is mounted on the local host
and TRAMP just accesses by changing the ‘default-directory’.
TRAMP starts a remote process when a command is executed in a remote
file or directory buffer. As of now, these packages have been
integrated to work with TRAMP: ‘compile.el’ (commands like ‘compile’ and
‘grep’) and ‘gud.el’ (‘gdb’ or ‘perldb’).
For TRAMP to find the command on the remote, it must be accessible
through the default search path as setup by TRAMP upon first connection.
Alternatively, 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")
Customize ‘tramp-remote-process-environment’ to suit the remote
program’s environment for the remote host.
‘tramp-remote-process-environment’ is a list of strings structured
similar to ‘process-environment’, where each element is a string of the
form ‘ENVVARNAME=VALUE’.
To avoid any conflicts with local host variables set through local
configuration files, such as ‘~/.profile’, use ‘ENVVARNAME=’ to unset
them for the remote environment.
Use ‘add-to-list’ to add entries:
(add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")
Modifying or deleting already existing values in the
‘tramp-remote-process-environment’ list may not be feasible on
restricted remote hosts. For example, some system administrators
disallow changing ‘HISTORY’ variable. To accommodate such restrictions
when using TRAMP, fix the ‘tramp-remote-process-environment’ by the
following code in the local ‘.emacs’ file:
(let ((process-environment tramp-remote-process-environment))
(setenv "HISTORY" nil)
(setq tramp-remote-process-environment process-environment))
TRAMP does not use the defaults specified in ‘process-environment’
for running ‘process-file’ or ‘start-file-process’ on remote hosts.
When values from ‘process-environment’ are needed for remote processes,
then set them as follows:
(let ((process-environment (cons "HGPLAIN=1" process-environment)))
(process-file ...))
This works only for environment variables not already set in the
‘process-environment’.
For integrating other Emacs packages so TRAMP can execute remotely,
please file a bug report. Bug Reports.
5.4.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 the file ‘~/.ssh/config’ on the local host.
5.4.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.
Starting with Emacs 24, when ‘explicit-shell-file-name’ is equal to
‘nil’, calling ‘shell’ interactively will prompt for a shell name.
5.4.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, ‘*Async
Shell Command*’
‘M-x auto-revert-tail-mode’ runs similarly showing continuous output.
5.4.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’ 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’ in Emacs 23.2 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 (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.4.5 Running a debugger on a remote host
-----------------------------------------
‘gud.el’ provides a unified interface to symbolic debuggers (
(emacs)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 --annotate=3 /ssh:host:~/myprog <RET>
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.4.6 Running remote processes on Windows hosts
-----------------------------------------------
‘winexe’ runs processes on a remote 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’ can open a proper remote shell on a 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" "-"))
Info Catalog
tramp: Ad-hoc multi-hops
tramp: Usage
tramp: Cleanup remote connections