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 *"))
For a local process, process-file returns either the exit code
of the process, or a string describing a signal, when the process has
been interrupted. Since it cannot be determined reliably whether a
remote process has been interrupted, process-file will always
returns the exit code for it. When the user option
process-file-return-signal-string is non-nil,
process-file treats all exit codes greater than 128 as an
indication that the process has been interrupted, and returns a
corresponding string.
This remote process handling does not apply to GVFS
(see GVFS-based external methods) because the remote file system is mounted
on the local host and TRAMP accesses it 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: shell.el,
eshell.el, compile.el (commands like compile and
grep) and gud.el (gdb or perldb).
TRAMP always modifies the INSIDE_EMACS environment
variable for remote processes. By default, this environment variable
shows the Emacs version. TRAMP adds its own version string,
so it looks like ‘27.2,tramp:2.4.5.1’. However, other packages
might also add their name to this environment variable, like
‘27.2,comint,tramp:2.4.5.1’.
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 How TRAMP finds and uses programs on the remote host):
(add-to-list 'tramp-remote-path "~/bin") (add-to-list 'tramp-remote-path "/appli/pub/bin")
Customize user option 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 environment 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 environment 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))
Setting the ENV environment variable instructs some shells to
read an initialization file. By default, TRAMP disables
this. You can override this behavior by evaluating
(let ((process-environment tramp-remote-process-environment)) (setenv "ENV" "$HOME/.profile") (setq tramp-remote-process-environment process-environment))
In addition to tramp-remote-process-environment, you can set
environment variables for individual remote process calls by
let-binding process-environment. TRAMP applies any
entries not present in the global default value of
process-environment (overriding
tramp-remote-process-environment settings, if they conflict).
For example:
(let ((process-environment (cons "HGPLAIN=1" process-environment))) (process-file …))
Let-binding in this way works regardless of whether the process to be
called is local or remote, since TRAMP would add just the
HGPLAIN setting and local processes would take whole value of
process-environment along with the new value of HGPLAIN.
For integrating other Emacs packages so TRAMP can execute remotely, please file a bug report. See Reporting Bugs and Problems.
shell on a remote hostshell-command on a remote hosteshell on a remote hostTo 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. Furthermore, set tramp-use-connection-share to
nil (see Using ssh connection sharing), in order to avoid
unwanted side effects.
Due to the remote shell saving tilde expansions triggered by
TRAMP, the shell history file is probably growing rapidly.
TRAMP can suppress this behavior with the user option
tramp-histfile-override. When set to t, environment
variable HISTFILE is unset, and environment variables
HISTFILESIZE and HISTSIZE are set to 0. Don’t use this
with bash 5.0.0 that version has a bug which
causes bash to die.
Alternatively, tramp-histfile-override can be a string.
The environment variable HISTFILE is then set to this file name. Be
careful if using /dev/null; this might result in undesired
results when using bash as remote shell.
Another approach is to completely disable TRAMP’s handling of
the HISTFILE by setting tramp-histfile-override to
nil. In this case, saving history can be turned off by putting
this shell code in .bashrc or .kshrc:
if [ -f $HOME/.sh_history ] ; then
/bin/rm $HOME/.sh_history
fi
if [ "${HISTFILE-unset}" != "unset" ] ; then
unset HISTFILE
fi
if [ "${HISTSIZE-unset}" != "unset" ] ; then
unset HISTSIZE
fi
For ssh-based method, add the following line to your ~/.ssh/environment:
HISTFILE=/dev/null
shell on a remote hostSet 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 can 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)
The command shell reads the remote history file in order to to
initialize the history input ring. You can set the user option
shell-history-file-name in order to specify which remote
history file is taken, or whether to suppress this at all. It accepts
the same values as tramp-histfile-override, see see Managing remote shell history. shell-history-file-name accepts also
connection-local values in shell buffers.
shell-command on a remote hostshell-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.
TRAMP cares about the user option
async-shell-command-width 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.
eshell on a remote hostTRAMP 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 $
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.
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" "-"))
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.
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:
This is a list of arguments (strings) ps is called with.
The default value is appropriate for GNU/Linux remote hosts.
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, can 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.
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-local variable
tramp-direct-async-process,
which must be set to a non-nil value. Example:
(connection-local-set-profile-variables 'remote-direct-async-process '((tramp-direct-async-process . t)))
(connection-local-set-profiles '(:application tramp :machine "remotehost") 'remote-direct-async-process)
This enables direct async processes for the host ‘remotehost’. If you want to enable direct async processes for all remote hosts connected via the same method (e.g., ssh), use instead
(connection-local-set-profiles '(:application tramp :protocol "ssh") 'remote-direct-async-process)
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:
ssh-agent, using public key authentication, or
using ControlMaster options.
interrupt-process.
process-tty-name.
remote-pid. Consequently,
signals cannot be sent to that remote process; they are sent to the
local process instead, which establishes the connection.
PATH
and/or other environment variables, which must be set, are too long.
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-connection-share to nil in order to bypass
TRAMP’s handling of the ControlMaster options, and
use your own settings in ~/.ssh/config, see Using ssh connection sharing.
Note: In previous TRAMP versions this was triggered
by the connection property "direct-async-process". This is still
supported but deprecated, and it will be removed in a future
TRAMP version.
Note: For the ssh and scp methods, TRAMP does not faithfully pass binary sequences on to the process. You can change this by changing the respective connection argument (see Setting own connection related information) via
(add-to-list 'tramp-connection-properties (list "/ssh:" "direct-async" t))