TRAMP User Manual: Frequently Asked Questions

7 Frequently Asked Questions

Where is the latest TRAMP?

TRAMP is available at the GNU URL:

ftp://ftp.gnu.org/gnu/tramp/

TRAMP’s GNU project page is located here:

http://savannah.gnu.org/projects/tramp/

Which systems does it work on?

The package works successfully on Emacs 22, Emacs 23, Emacs 24, Emacs 25, XEmacs 21 (starting with 21.4), and SXEmacs 22.

While Unix and Unix-like systems are the primary remote targets, TRAMP has equal success connecting to other platforms, such as MS Windows XP/Vista/7.

How to speed up TRAMP?

TRAMP does many things in the background, some of which depends on network speeds, response speeds of remote hosts, and authentication delays. During these operations, TRAMP’s responsiveness slows down. Some suggestions within the scope of TRAMP’s settings include:

Use an external method, such as scp, which are faster than internal methods.

Keep the file tramp-persistency-file-name, which is where TRAMP caches remote information about hosts and files. Caching is enabled by default. Don’t disable it.

Set remote-file-name-inhibit-cache to nil if remote files are not independently updated outside TRAMP’s control. That cache cleanup will be necessary if the remote directories or files are updated independent of TRAMP.

Set tramp-completion-reread-directory-timeout to nil to speed up completions, File name completion.

Disable version control to avoid delays:

(setq vc-ignore-dir-regexp
      (format "\\(%s\\)\\|\\(%s\\)"
              vc-ignore-dir-regexp
              tramp-file-name-regexp))

Disable excessive traces. Set tramp-verbose to 3 or lower, default being 3. Increase trace levels temporarily when hunting for bugs.

TRAMP does not connect to the remote host

Three main reasons for why TRAMP does not connect to the remote host:

- Unknown characters in the prompt
TRAMP needs a clean recognizable prompt on the remote host for accurate parsing. Shell prompts that contain escape sequences for coloring cause parsing problems. Remote shell setup for customizing prompt detection using regular expressions.

To check if the remote host’s prompt is being recognized, use this test: switch to TRAMP connection buffer *tramp/foo*, put the cursor at the top of the buffer, and then apply the following expression:
```
M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))
```
If the cursor has not moved to the prompt at the bottom of the buffer, then TRAMP has failed to recognize the prompt.

When using zsh on remote hosts, disable zsh line editor because zsh uses left-hand side and right-hand side prompts in parallel. Add the following line to ~/.zshrc:
```
[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
```
When using fish shell on remote hosts, disable fancy formatting by adding the following to ~/.config/fish/config.fish:
```
function fish_prompt
  if test $TERM = "dumb"
     echo "\$ "
  else
     …
  end
end
```
When using WinSSHD on remote hosts, TRAMP do not recognize the strange prompt settings.
- Echoed characters after login
TRAMP suppresses echos from remote hosts with the stty -echo command. But sometimes it is too late to suppress welcome messages from the remote host containing harmful control characters. Using sshx or scpx methods can avoid this problem because they allocate a pseudo tty. See Inline methods.
- TRAMP stops transferring strings longer than 500 characters
Set tramp-chunksize to 500 to get around this problem, which is related to faulty implementation of process-send-string on HP-UX, FreeBSD and Tru64 Unix systems. Consult the documentation for tramp-chunksize to see when this is necessary.

Set file-precious-flag to t for files accessed by TRAMP so the file contents are checked using checksum by first saving to a temporary file.
```
(add-hook
 'find-file-hook
 (lambda ()
   (when (file-remote-p default-directory)
     (set (make-local-variable 'file-precious-flag) t))))
```

TRAMP does not recognize if a ssh session hangs

ssh sessions on the local host hang when the network is down. TRAMP cannot safely detect such hangs. The network configuration for ssh can be configured to kill such hangs with the following command in the ~/.ssh/config:

Host *
     ServerAliveInterval 5

TRAMP does not use default ssh ControlPath

TRAMP overwrites ControlPath settings when initiating ssh sessions. TRAMP does this to fend off a stall if a master session opened outside the Emacs session is no longer open. That is why TRAMP prompts for the password again even if there is an ssh already open.

Some ssh versions support a ControlPersist option, which allows you to set the ControlPath provided the variable tramp-ssh-controlmaster-options is customized as follows:

(setq tramp-ssh-controlmaster-options
      (concat
        "-o ControlPath=/tmp/ssh-ControlPath-%%r@%%h:%%p "
        "-o ControlMaster=auto -o ControlPersist=yes"))

Note how "%r", "%h" and "%p" must be encoded as "%%r", "%%h" and "%%p".

If the ~/.ssh/config is configured appropriately for the above behavior, then any changes to ssh can be suppressed with this nil setting:

(setq tramp-use-ssh-controlmaster-options nil)

File name completion does not work with TRAMP

ANSI escape sequences from the remote shell may cause errors in TRAMP’s parsing of remote buffers.

To test if this is the case, open a remote shell and check if the output of ls is in color.

To disable ANSI escape sequences from the remote hosts, disable --color=yes or --color=auto in the remote host’s .bashrc or .profile. Turn this alias on and off to see if file name completion works.

File name completion does not work in directories with large number of files

This may be related to globbing, which is the use of shell’s ability to expand wild card specifications, such as ‘*.c’. For directories with large number of files, globbing might exceed the shell’s limit on length of command lines and hang. TRAMP uses globbing.

To test if globbing hangs, open a shell on the remote host and then run ‘ls -d * ..?* > /dev/null’.

When testing, ensure the remote shell is the same shell (/bin/sh, ksh or bash), that TRAMP uses when connecting to that host.

How to get notified after TRAMP completes file transfers?

Make Emacs beep after reading from or writing to the remote host with the following code in ~/.emacs file.

(defadvice tramp-handle-write-region
  (after tramp-write-beep-advice activate)
  "Make tramp beep after writing a file."
  (interactive)
  (beep))

(defadvice tramp-handle-do-copy-or-rename-file
  (after tramp-copy-beep-advice activate)
  "Make tramp beep after copying a file."
  (interactive)
  (beep))

(defadvice tramp-handle-insert-file-contents
  (after tramp-insert-beep-advice activate)
  "Make tramp beep after inserting a file."
  (interactive)
  (beep))

How to get a Visual Warning when working with ‘root’ privileges

Get a modeline indication when working with ‘root’ privileges with the following code (tested with Emacs 22.1) in ~/.emacs file:

(defun my-mode-line-function ()
  (when (string-match "^/su\\(do\\)?:" default-directory)
    (setq mode-line-format
          (format-mode-line mode-line-format 'font-lock-warning-face))))

(add-hook 'find-file-hook 'my-mode-line-function)
(add-hook 'dired-mode-hook 'my-mode-line-function)

How to get host indication in the mode line?

The following code (tested with Emacs 22.1) in ~/.emacs file shows it:

(defconst my-mode-line-buffer-identification
  (list
   '(:eval
     (let ((host-name
            (if (file-remote-p default-directory)
                (tramp-file-name-host
                 (tramp-dissect-file-name default-directory))
              (system-name))))
       (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
           (substring host-name 0 (match-beginning 1))
         host-name)))
   ": %12b"))

(setq-default
 mode-line-buffer-identification
 my-mode-line-buffer-identification)

(add-hook
 'dired-mode-hook
 (lambda ()
   (setq
    mode-line-buffer-identification
    my-mode-line-buffer-identification)))

The mode line in Emacs 23.1 and later versions now contains an indication if default-directory for the current buffer is on a remote host. Moreover, the corresponding tool-tip shows the remote host name. The above :eval clause can also be simplified to show the host name in the mode line:

   '(:eval
     (let ((host-name
            (or (file-remote-p default-directory 'host)
                (system-name))))
       (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
           (substring host-name 0 (match-beginning 1))
         host-name)))

Remote host does not understand default options for directory listing

Emacs computes the dired options based on the local host but if the remote host cannot understand the same ls command, then set them with a hook as follows:

(add-hook
 'dired-before-readin-hook
 (lambda ()
   (when (file-remote-p default-directory)
     (setq dired-actual-switches "-al"))))

Why is ~/.sh_history file on the remote host growing?

Due to ksh saving tilde expansions triggered by TRAMP, the history file is probably growing rapidly. To fix, turn off saving history by putting this shell code in the .kshrc file:

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 file:

HISTFILE=/dev/null

How to shorten long file names when typing in TRAMP?

Adapt several of these approaches to reduce typing. If the full name is /ssh:[email protected]:/opt/news/etc, then:

Use default values for method name and user name:
You can define default methods and user names for hosts, (see Default Method, see Default User):
```
(setq tramp-default-method "ssh"
      tramp-default-user "news")
```
The reduced typing: C-x C-f /news.my.domain:/opt/news/etc.

Note that there are some useful shortcuts already. Accessing your local host as ‘root’ user, is possible just by C-x C-f /su::.
Use configuration options of the access method:
Programs used for access methods already offer powerful configurations (see Customizing Completion). For ssh, configure the file ~/.ssh/config:
```
Host xy
     HostName news.my.domain
     User news
```
The reduced typing: C-x C-f /ssh:xy:/opt/news/etc.

Depending on the number of files in the directories, host names completion can further reduce key strokes: C-x C-f /ssh:x TAB.
Use environment variables to expand long strings
For long file names, set up environment variables that are expanded in the minibuffer. Environment variables are set either outside Emacs or inside Emacs with Lisp:
```
(setenv "xy" "/ssh:[email protected]:/opt/news/etc/")
```
The reduced typing: C-x C-f $xy RET.

Note that file name cannot be edited here because the environment variables are not expanded during editing in the minibuffer.

Define own keys:

Redefine another key sequence in Emacs for C-x C-f:

(global-set-key
 [(control x) (control y)]
 (lambda ()
   (interactive)
   (find-file
    (read-file-name
     "Find Tramp file: "
     "/ssh:[email protected]:/opt/news/etc/"))))

Simply typing C-x C-y would prepare minibuffer editing of file name.

See the Emacs Wiki for a more comprehensive example.

Define own abbreviation (1):
Abbreviation list expansion can be used to reduce typing long file names:
```
(add-to-list
 'directory-abbrev-alist
 '("^/xy" . "/ssh:[email protected]:/opt/news/etc/"))
```
The reduced typing: C-x C-f /xy RET.

Note that file name cannot be edited here because the environment variables are not expanded during editing in the minibuffer.

Define own abbreviation (2):

The abbrev-mode gives additional flexibility for editing in the minibuffer:

(define-abbrev-table 'my-tramp-abbrev-table
  '(("xy" "/ssh:[email protected]:/opt/news/etc/")))

(add-hook
 'minibuffer-setup-hook
 (lambda ()
   (abbrev-mode 1)
   (setq local-abbrev-table my-tramp-abbrev-table)))

(defadvice minibuffer-complete
  (before my-minibuffer-complete activate)
  (expand-abbrev))

;; If you use partial-completion-mode
(defadvice PC-do-completion
  (before my-PC-do-completion activate)
  (expand-abbrev))

The reduced typing: C-x C-f xy TAB.

The minibuffer expands for further editing.

Use bookmarks:
Use bookmarks to save Tramp file names.

Upon visiting a location with TRAMP, save it as a bookmark with menu-bar edit bookmarks set.

To revisit that bookmark: menu-bar edit bookmarks jump.
Use recent files:
recentf remembers visited places.

Keep remote file names in the recent list without have to check for their accessibility through remote access:
```
(recentf-mode 1)
```
Reaching recently opened files: menu-bar file Open Recent.
Use filecache:
Since filecache remembers visited places, add the remote directory to the cache:
```
(eval-after-load "filecache"
  '(file-cache-add-directory
    "/ssh:[email protected]:/opt/news/etc/"))
```
Then use directory completion in the minibuffer with C-x C-f C-TAB.
Use bbdb:
bbdb has a built-in feature for Ange-FTP files, which also works for TRAMP file names.

Load bbdb in :
```
(require 'bbdb)
(bbdb-initialize)
```
Create a BBDB entry with M-x bbdb-create-ftp-site. Then specify a method and user name where needed. Examples:
```
M-x bbdb-create-ftp-site RET
Ftp Site: news.my.domain RET
Ftp Directory: /opt/news/etc/ RET
Ftp Username: ssh:news RET
Company: RET
Additional Comments: RET
```
In BBDB buffer, access an entry by pressing the key F.

Thanks to TRAMP users for contributing to these recipes.

Why saved multi-hop file names do not work in a new Emacs session?

When saving ad-hoc multi-hop TRAMP file names (see Ad-hoc multi-hops) via bookmarks, recent files, filecache, bbdb, or another package, use the full ad-hoc file name including all hops, like /ssh:bird@bastion|ssh:news.my.domain:/opt/news/etc.

Alternatively, when saving abbreviated multi-hop file names /ssh:[email protected]:/opt/news/etc, the custom option tramp-save-ad-hoc-proxies must be set non-nil value.

How to connect to a remote Emacs session using TRAMP?

Configure Emacs Client

Then on the remote host, start the Emacs Server:

(require 'server)
(setq server-host (system-name)
      server-use-tcp t)
(server-start)

If (system-name) of the remote host cannot be resolved on the local host, use IP address instead.

Copy from the remote host the resulting file ~/.emacs.d/server/server to the local host, to the same location.

Then start Emacs Client from the command line:

emacsclient /ssh:user@host:/file/to/edit

user and host refer to the local host.

To make Emacs Client an editor for other programs, use a wrapper script emacsclient.sh:

#!/bin/sh
emacsclient /ssh:$(whoami)@$(hostname --fqdn):$1

Then change the environment variable EDITOR to point to the wrapper script:

export EDITOR=/path/to/emacsclient.sh

How to disable other packages from calling TRAMP?

There are packages that call TRAMP without the user ever entering a remote file name. Even without applying a remote file syntax, some packages enable TRAMP on their own. How can users disable such features.

- ido.el

Disable TRAMP file name completion:

(custom-set-variables
 '(ido-enable-tramp-completion nil))

- rlogin.el
Disable remote directory tracking mode:
```
(rlogin-directory-tracking-mode -1)
```

How to disable TRAMP?

- To keep Ange-FTP as default the remote files access package, set this in .emacs:
```
(setq tramp-default-method "ftp")
```
- To disable both TRAMP (and Ange-FTP), set tramp-mode to nil in .emacs.
```
(setq tramp-mode nil)
```
- To unload TRAMP, type M-x tramp-unload-tramp. Unloading TRAMP resets Ange-FTP plugins also.