TRAMP User Manual: Frequently Asked Questions

7 Frequently Asked Questions

Where can I get the latest TRAMP?

TRAMP is available under the URL below.

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

There is also a Savannah project page.

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

Which systems does it work on?

The package has been used successfully on Emacs 22, Emacs 23, Emacs 24, XEmacs 21 (starting with 21.4), and SXEmacs 22.

The package was intended to work on Unix, and it really expects a Unix-like system on the remote end (except the smb method), but some people seemed to have some success getting it to work on MS Windows XP/Vista/7 Emacs.

How could I speed up TRAMP?

In the backstage, TRAMP needs a lot of operations on the remote host. The time for transferring data from and to the remote host as well as the time needed to perform the operations there count. In order to speed up TRAMP, one could either try to avoid some of the operations, or one could try to improve their performance.

Use an external method, like scp.

Use caching. This is already enabled by default. Information about the remote host as well as the remote files are cached for reuse. The information about remote hosts is kept in the file specified in tramp-persistency-file-name. Keep this file. If you are confident that files on remote hosts are not changed out of Emacs’ control, set remote-file-name-inhibit-cache to nil. Set also tramp-completion-reread-directory-timeout to nil, File name completion.

Disable version control. If you access remote files which are not under version control, a lot of check operations can be avoided by disabling VC. This can be achieved by

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

Disable excessive traces. The default trace level of TRAMP, defined in the variable tramp-verbose, is 3. You should increase this level only temporarily, hunting bugs.

TRAMP does not connect to the remote host

When TRAMP does not connect to the remote host, there are three reasons heading the bug mailing list:

- Unknown characters in the prompt
TRAMP needs to recognize the prompt on the remote host after execution any command. This is not possible when the prompt contains unknown characters like escape sequences for coloring. This should be avoided on the remote side. See Remote shell setup. for setting the regular expression detecting the prompt.

You can check your settings after an unsuccessful connection by switching to the TRAMP connection buffer *tramp/foo*, setting the cursor at the top of the buffer, and applying the expression
```
M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))
```
If it fails, or the cursor is not moved at the end of the buffer, your prompt is not recognized correctly.

A special problem is the zsh shell, which uses left-hand side and right-hand side prompts in parallel. Therefore, it is necessary to disable the zsh line editor on the remote host. You shall add to ~/.zshrc the following command:
```
[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
```
Similar fancy prompt settings are known from the fish shell. Here you must add in ~/.config/fish/config.fish:
```
function fish_prompt
  if test $TERM = "dumb"
     echo "\$ "
  else
     …
  end
end
```
Furthermore it has been reported, that TRAMP (like sshfs, incidentally) doesn’t work with WinSSHD due to strange prompt settings.
- Echoed characters after login
When the remote host opens an echoing shell, there might be control characters in the welcome message. TRAMP tries to suppress such echoes via the stty -echo command, but sometimes this command is not reached, because the echoed output has confused TRAMP already. In such situations it might be helpful to use the sshx or scpx methods, which allocate a pseudo tty. See Inline methods.
- TRAMP doesn’t transfer strings with more than 500 characters correctly
On some few systems, the implementation of process-send-string seems to be broken for longer strings. It is reported for HP-UX, FreeBSD and Tru64 Unix, for example. This case, you should customize the variable tramp-chunksize to 500. For a description how to determine whether this is necessary see the documentation of tramp-chunksize.

Additionally, it will be useful to set file-precious-flag to t for TRAMP files. Then the file contents will be written into a temporary file first, which is checked for correct checksum.
```
(add-hook
 'find-file-hook
 (lambda ()
   (when (file-remote-p default-directory)
     (set (make-local-variable 'file-precious-flag) t))))
```

TRAMP does not recognize hung ssh sessions

When your network connection is down, ssh sessions might hang. TRAMP cannot detect it safely, because it still sees a running ssh process. Timeouts cannot be used as well, because it cannot be predicted how long a remote command will last, for example when copying very large files.

Therefore, you must configure the ssh process to die in such a case. The following entry in ~/.ssh/config would do the job:

Host *
     ServerAliveInterval 5

TRAMP does not use my ssh ControlPath

Your ControlPath setting will be overwritten by ssh sessions initiated by TRAMP. This is because a master session, initiated outside Emacs, could be closed, which would stall all other ssh sessions for that host inside Emacs.

Consequently, if you connect to a remote host via TRAMP, you might be prompted for a password again, even if you have established already an ssh connection to that host. Further TRAMP connections to that host, for example in order to run a process on that host, will reuse that initial ssh connection.

If your ssh version supports the ControlPersist option, you could customize the variable tramp-ssh-controlmaster-options to use your ControlPath, for example:

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

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

These settings can be suppressed, if they are configured properly in your ~/.ssh/config:

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

File name completion does not work with TRAMP

When you log in to the remote host, do you see the output of ls in color? If so, this may be the cause of your problems.

ls outputs ANSI escape sequences that your terminal emulator interprets to set the colors. These escape sequences will confuse TRAMP however.

In your .bashrc, .profile or equivalent on the remote host you probably have an alias configured that adds the option --color=yes or --color=auto.

You should remove that alias and ensure that a new login does not display the output of ls in color. If you still cannot use file name completion, report a bug to the TRAMP developers.

File name completion does not work in large directories

TRAMP uses globbing for some operations. (Globbing means to use the shell to expand wildcards such as ‘*.c’.) This might create long command lines, especially in directories with many files. Some shells choke on long command lines, or don’t cope well with the globbing itself.

If you have a large directory on the remote end, you may wish to execute a command like ‘ls -d * ..?* > /dev/null’ and see if it hangs. Note that you must first start the right shell, which might be /bin/sh, ksh or bash, depending on which of those supports tilde expansion.

How can I get notified when TRAMP file transfers are complete?

The following snippet can be put in your ~/.emacs file. It makes Emacs beep after reading from or writing to the remote host.

(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))

I’ld like to get a Visual Warning when working in a sudo:ed context

When you are working with ‘root’ privileges, it might be useful to get an indication in the buffer’s modeline. The following code, tested with Emacs 22.1, does the job. You should put it into your ~/.emacs:

(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)

I’ld like to see a host indication in the mode line when I’m remote

The following code has been tested with Emacs 22.1. You should put it into your ~/.emacs:

(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)))

Since Emacs 23.1, the mode line contains an indication if default-directory for the current buffer is on a remote host. The corresponding tooltip includes the name of that host. If you still want the host name as part of the mode line, you can use the example above, but the :eval clause can be simplified:

   '(: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)))

My remote host does not understand default directory listing options

Emacs computes the dired options depending on the local host you are working. If your ls command on the remote host does not understand those options, you can change them like this:

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

There’s this ~/.sh_history file on the remote host which keeps growing and growing. What’s that?

Sometimes, TRAMP starts ksh on the remote host for tilde expansion. Maybe ksh saves the history by default. TRAMP tries to turn off saving the history, but maybe you have to help. For example, you could put this in your .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

Furthermore, if you use an ssh-based method, you could add the following line to your ~/.ssh/environment file:

HISTFILE=/dev/null

There are longish file names to type. How to shorten this?

Let’s say you need regularly access to /ssh:news@news.my.domain:/opt/news/etc, which is boring to type again and again. The following approaches can be mixed:

Use default values for method 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 file name left to type would be C-x C-f /news.my.domain:/opt/news/etc.

Note that there are some useful settings already. Accessing your local host as ‘root’ user, is possible just by C-x C-f /su::.
Use configuration possibilities of your method:
Several connection methods (i.e., the programs used) offer powerful configuration possibilities (see Customizing Completion). In the given case, this could be ~/.ssh/config:
```
Host xy
     HostName news.my.domain
     User news
```
The file name left to type would be C-x C-f /ssh:xy:/opt/news/etc. Depending on files in your directories, it is even possible to complete the host name with C-x C-f /ssh:x TAB.
Use environment variables:
File names typed in the minibuffer can be expanded by environment variables. You can set them outside Emacs, or even with Lisp:
```
(setenv "xy" "/ssh:news@news.my.domain:/opt/news/etc/")
```
Then you need simply to type C-x C-f $xy RET, and here you are. The disadvantage is that you cannot edit the file name, because environment variables are not expanded during editing in the minibuffer.
Define own keys:
You can define your own key sequences in Emacs, which can be used instead of C-x C-f:
```
(global-set-key
 [(control x) (control y)]
 (lambda ()
   (interactive)
   (find-file
    (read-file-name
     "Find Tramp file: "
     "/ssh:news@news.my.domain:/opt/news/etc/"))))
```
Simply typing C-x C-y would initialize the minibuffer for editing with your beloved file name.

See also the Emacs Wiki for a more comprehensive example.
Define own abbreviation (1):
It is possible to define an own abbreviation list for expanding file names:
```
(add-to-list
 'directory-abbrev-alist
 '("^/xy" . "/ssh:news@news.my.domain:/opt/news/etc/"))
```
This shortens the file opening command to C-x C-f /xy RET. The disadvantage is, again, that you cannot edit the file name, because the expansion happens after entering the file name only.

Define own abbreviation (2):

The abbrev-mode gives more flexibility for editing the minibuffer:

(define-abbrev-table 'my-tramp-abbrev-table
  '(("xy" "/ssh:news@news.my.domain:/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))

After entering C-x C-f xy TAB, the minibuffer is expanded, and you can continue editing.

Use bookmarks:
Bookmarks can be used to visit Tramp files or directories.

When you have opened /ssh:news@news.my.domain:/opt/news/etc/, you should save the bookmark via menu-bar edit bookmarks set.

Later on, you can always navigate to that bookmark via menu-bar edit bookmarks jump.
Use recent files:
recentf remembers visited places.

You could keep remote file names in the recent list without checking their readability through a remote access:
```
(recentf-mode 1)
```
The list of files opened recently is reachable via menu-bar file Open Recent.
Use filecache:
filecache remembers visited places. Add the directory into the cache:
```
(eval-after-load "filecache"
  '(file-cache-add-directory
    "/ssh:news@news.my.domain:/opt/news/etc/"))
```
Whenever you want to load a file, you can enter C-x C-f C-TAB in the minibuffer. The completion is done for the given directory.
Use bbdb:
bbdb has a built-in feature for Ange-FTP files, which works also for TRAMP.

You need to load bbdb:
```
(require 'bbdb)
(bbdb-initialize)
```
Then you can create a BBDB entry via M-x bbdb-create-ftp-site. Because BBDB is not prepared for TRAMP syntax, you must specify a method together with the user name when needed. Example:
```
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
```
When you have opened your BBDB buffer, you can access such an entry by pressing the key F.

I would like to thank all TRAMP users who have contributed to the different recipes!

How can I use TRAMP to connect to a remote Emacs session?

You can configure Emacs Client doing this.

On the remote host, you start the Emacs Server:

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

Make sure that the result of (system-name) can be resolved on your local host; otherwise you might use a hard coded IP address.

The resulting file ~/.emacs.d/server/server must be copied to your local host, at the same location. You can call then the Emacs Client from the command line:

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

user and host shall be related to your local host.

If you want to use Emacs Client also as editor for other programs, you could write a script emacsclient.sh:

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

Then you must set the environment variable EDITOR pointing to that script:

export EDITOR=/path/to/emacsclient.sh

There are packages which call TRAMP although I haven’t entered a remote file name ever. I dislike it, how could I disable it?

In general, TRAMP functions are used only when you apply remote file name syntax. However, some packages enable TRAMP on their own.

- ido.el

You could disable TRAMP file name completion:

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

- rlogin.el
You could disable remote directory tracking mode:
```
(rlogin-directory-tracking-mode -1)
```

How can I disable TRAMP at all?

Shame on you, why did you read until now?

- If you just want to have Ange-FTP as default remote files access package, you should apply the following code:
```
(setq tramp-default-method "ftp")
```
- In order to disable TRAMP (and Ange-FTP), you must set tramp-mode to nil:
```
(setq tramp-mode nil)
```
- Unloading TRAMP can be achieved by applying M-x tramp-unload-tramp. This resets also the Ange-FTP plugins.