# TRAMP mode manual

## 1 An overview of TRAMP

After the installation of TRAMP into your Emacs, you will be able to access files on remote hosts as though they were local. Access to the remote file system for editing files, version control, and dired are transparently enabled.

Emacs 中安装 tramp 自后，就可以访问远程主机上的文件了，就好像他们在本地一样。可以透明的访问远程主机上的文件来对它们进行编辑、版本控制或者文件管理。

Your access to the remote host can be with the rsh, rlogin, telnet programs or with any similar connection method. This connection must pass ASCII successfully to be usable but need not be 8-bit clean.

The package provides support for ssh connections out of the box, one of the more common uses of the package. This allows relatively secure access to hosts, especially if ftp access is disabled.

package 对 ssh 连接提供了开箱可用的支持，ssh 是用来访问远程主机最常用的方法。这允许相对安全的访问主机，特别是 ftp 访问关闭的情况下。

Under Windows, TRAMP is integrated with the PuTTY package, using the plink program.

window 下，TRAMP 通过 plink 程序与 putty 包整合在一起。

The majority of activity carried out by TRAMP requires only that the remote login is possible and is carried out at the terminal. In order to access remote files TRAMP needs to transfer their content to the local host temporarily.

TRAMP 最基本的要求就是远程主机可以登录，并且能够通过终端进行访问。为了访问远程主机文件，tramp 需要将文件内容临时传输到本地主机。

TRAMP can transfer files between the hosts in a variety of ways. The details are easy to select, depending on your needs and the hosts in question.

TRAMP 可以在主机间通过多种方法来传输文件。根据需求和访问主机很容易你选定细节。

The fastest transfer methods for large files rely on a remote file transfer package such as rcp, scp, rsync or (under Windows) pscp.

If the remote copy methods are not suitable for you, TRAMP also supports the use of encoded transfers directly through the shell. This requires that the mimencode or uuencode tools are available on the remote host. These methods are generally faster for small files.

TRAMP is still under active development and any problems you encounter, trivial or major, should be reported to the TRAMP developers. See Bug Reports.

tramp 还初级积极开发中，如果遇到任何问题，不管重要与否，请向 tramp 开发者报告。See Bug Reports。

### 1.1 Behind the scenes

This section tries to explain what goes on behind the scenes when you access a remote file through TRAMP.

Suppose you type C-x C-f and enter part of an TRAMP file name, then hit TAB for completion. Suppose further that this is the first time that TRAMP is invoked for the host in question. Here’s what happens:

• TRAMP discovers that it needs a connection to the host. So it invokes ‘telnet host’ or ‘rsh host -l user’ or a similar tool to connect to the remote host. Communication with this process happens through an Emacs buffer, that is, the output from the remote end goes into a buffer.

TRAMP 发现它需要连接主机。所以它调用‘telnet host’ 或 ‘rsh host -l user’ 或者类似的工具来连接远程主机。这个交流的过程发生在 Emacs buffer 当中，也就说远程主机的输出会进入 buffer 当中。

• The remote host may prompt for a login name (for telnet). The login name is given in the file name, so TRAMP sends the login name and a newline.

远程主机可能会提示输入登录名（如 telnet）。文件名中已经给出登录名字，所以 tramp 发送登录名和一个换行符。

• The remote host may prompt for a password or pass phrase (for rsh or for telnet after sending the login name). TRAMP displays the prompt in the minibuffer, asking you for the password or pass phrase.

远程主机及可能提示密码或 pass phrase（如 rsh 或 telnet 发送登录名后）。TRAMP 在 minibuffer 中显示提示，要求您输入密码或者 pass phrase。

You enter the password or pass phrase. TRAMP sends it to the remote host, followed by a newline.

tramp 在你输入的密码或 pass phrase 附加一个换行符，发送到远程服务器。

• TRAMP now waits for the shell prompt or for a message that the login failed.

现在 TRAMP 现在等待 shell 提示符或者登陆失败的消息。

• If TRAMP sees neither of them after a certain period of time (a minute, say), then it issues an error message saying that it couldn’t find the remote shell prompt and shows you what the remote host has sent.

如果等待一段时间（比如说一分钟）后，TRAMP 两个都没有都到，那它就发出一个错误消息说它找不到远程 shell 提示符，并显示远程主机发送的消息。

If TRAMP sees a ‘login failed’ message, it tells you so, aborts the login attempt and allows you to try again.

如果收到登陆失败消息，它会告诉你，不再尝试登陆，让你再试一次。

• Suppose that the login was successful and TRAMP sees the shell prompt from the remote host. Now TRAMP invokes /bin/sh because Bourne shells and C shells have different command syntaxes.

假设登陆成功，TRAMP 收到远程主机的提示符，TRAMP 会调用/bin/sh，因为 Bourne shells 和 C shells 有不同的命令语法。

After the Bourne shell has come up, TRAMP sends a few commands to ensure a good working environment. It turns off echoing, it sets the shell prompt, and a few other things.

Bourne shell 启动后，TRAMP 发送一些命令来确保一个良好的工作环境。它关闭回显，设置 shell 提示符，还有其它的事情。

• Now the remote shell is up and it good working order. Remember, what was supposed to happen is that TRAMP tries to find out what files exist on the remote host so that it can do file name completion.

现在远程 shell 启动并且工况良好，记住，希望发生的事情是 TRAMP 尝试确定远程文件系统上有哪些文件可以用来做文件名补全。

So, TRAMP basically issues cd and ls commands and also sometimes echo with globbing. Another command that is often used is test to find out whether a file is writable or a directory or the like. The output of each command is parsed for the necessary operation.

所以，tramp 主要调用 cd 和 ls 命令，有时调用带有 globbing 的 echo 命令。另一个经常使用的命令是 test，用来发现一个文件是否可写，是否是目录或者其他类似的什么。为了必要的操作每个命令的输出都会被分析。

• Suppose you are finished with file name completion, have entered C-x C-f, a full file name and hit RET. Now comes the time to transfer the file contents from the remote host to the local host so that you can edit them.

假设已经完成文件补全，现在应该将文件内容已从远程传到本地，这样就可以编辑了。

See above for an explanation of how TRAMP transfers the file contents.

上面介绍了 TRAMP 如何传输文件内容。

For inline transfers, TRAMP issues a command like ‘mimencode -b /path/to/remote/file’, waits until the output has accumulated in the buffer that’s used for communication, then decodes that output to produce the file contents.

低于 inline 传输，tramp 执行类似“mimecode -b /path/to/remote/file”的命令，等待用于通信的 buffer 中累积的输出，然后解码输出来生成文件内容。

For external transfers, TRAMP issues a command like the following:

对于 external 传输，tramp 执行如下的命令

rcp user@host:/path/to/remote/file /tmp/tramp.4711


It then reads the local temporary file /tmp/tramp.4711 into a buffer and deletes the temporary file.

然后将临时文件读取到一个 buffer，并删除临时文件。

• You now edit the buffer contents, blithely unaware of what has happened behind the scenes. (Unless you have read this section, that is.) When you are finished, you type C-x C-s to save the buffer.

现在可以编辑 buffer 的内容了，你并不会意识到幕后发生了什么。（除非你有阅读了本节内容）。当编辑完之后，键入 C-x C-s 保存 buffer。

• Again, TRAMP transfers the file contents to the remote host either inline or external. This is the reverse of what happens when reading the file.

tramp 通过 inline 或 external 再次传输文件到远程主机。这是读文件的逆过程。

I hope this has provided you with a basic overview of what happens behind the scenes when you open a file with TRAMP.

## 4 Configuring TRAMP for use

TRAMP is (normally) fully functional when it is initially installed. It is initially configured to use the scp program to connect to the remote host. So in the easiest case, you just type C-x C-f and then enter the file name /user@host:/path/to.file.

On some hosts, there are problems with opening a connection. These are related to the behavior of the remote shell. See See Remote shell setup, for details on this.

If you do not wish to use these commands to connect to the remote host, you should change the default connection and transfer method that TRAMP uses. There are several different methods that TRAMP can use to connect to remote hosts and transfer files (see Connection types).

If you don’t know which method is right for you, see See Default Method.

### 4.1 Types of connections made to remote hosts

There are two basic types of transfer methods, each with its own advantages and limitations. Both types of connection make use of a remote shell access program such as rsh, ssh or telnet to connect to the remote host.

This connection is used to perform many of the operations that TRAMP requires to make the remote file system transparently accessible from the local host. It is only when visiting files that the methods differ.

Loading or saving a remote file requires that the content of the file be transferred between the two hosts. The content of the file can be transferred using one of two methods: the inline method over the same connection used to log in to the remote host, or the external method through another connection using a remote copy program such as rcp, scp or rsync.

The performance of the external methods is generally better than that of the inline methods, at least for large files. This is caused by the need to encode and decode the data when transferring inline.

external 方法的性能一般好于 inline 方法，至少大文件如此。这是由于 inline 方法传输的时候需要进行编码和解码导致的。

The one exception to this rule are the scp based transfer methods. While these methods do see better performance when actually transferring files, the overhead of the cryptographic negotiation at startup may drown out the improvement in file transfer times.

External methods should be configured such a way that they don’t require a password (with ssh-agent, or such alike). Modern scp implementations offer options to reuse existing ssh connections, which will be enabled by default if available. If it isn’t possible, you should consider Password handling, otherwise you will be prompted for a password every copy action.

external 方法应该配置成不需要密码的（使用 ssh-agent 或者类似工具）。现代的 scp 实现提供了选项来复用已存在的 ssh 连接，如果这项功能可用，是默认开启的。如果不可用，你应该考虑一下密码处理，否侧每次拷贝操作都会被提示输入密码。

### 4.2 Inline methods

The inline methods in TRAMP are quite powerful and can work in situations where you cannot use an external transfer program to connect. There are also strange inline methods which allow you to transfer files between user identities rather than hosts, see below.

tramp 的 inline 方法十分强大，可以在不能使用外部传输程序进行连接的时候使用。也有奇怪的内部方法可以让你在用户实体而不是主机间传递文件。

These methods depend on the existence of a suitable encoding and decoding command on remote host. Locally, TRAMP may be able to use features of Emacs to decode and encode the files or it may require access to external commands to perform that task.

TRAMP checks the availability and usability of commands like mimencode (part of the metamail package) or uuencode on the remote host. The first reliable command will be used. The search path can be customized, see Remote Programs.

tramp 会检查远程主机上类似 mimencode（是 metamail package 的部分）或 uuencodez 命令是否存在以及可用，并且使用第一个可用的命令。搜索的路径是可定制的，参看 Remote Programs。

If both commands aren’t available on the remote host, TRAMP transfers a small piece of Perl code to the remote host, and tries to apply it for encoding and decoding.

The variable tramp-inline-compress-start-size controls, whether a file shall be compressed before encoding. This could increase transfer speed for large text files.

#### 4.2.1 rsh

Connect to the remote host with rsh. Due to the unsecure connection it is recommended for very local host topology only.

On operating systems which provide the command remsh instead of rsh, you can use the method remsh. This is true for HP-UX or Cray UNICOS, for example.

#### 4.2.2 ssh

Connect to the remote host with ssh. This is identical to the previous option except that the ssh package is used, making the connection more secure.

All the methods based on ssh have an additional feature: you can specify a host name which looks like host#42 (the real host name, then a hash sign, then a port number). This means to connect to the given host but to also pass -p 42 as arguments to the ssh command.

#### 4.2.3 telnet

Connect to the remote host with telnet. This is as unsecure as the rsh method.

#### 4.2.4 su

This method does not connect to a remote host at all, rather it uses the su program to allow you to edit files as another user. That means, the specified host name in the file name must be either ‘localhost’ or the host name as returned by the function (system-name). For an exception of this rule see Multi-hops.

#### 4.2.5 sudo

This is similar to the su method, but it uses sudo rather than su to become a different user.

Note that sudo must be configured to allow you to start a shell as the user. It would be nice if it was sufficient if ls and mimencode were allowed, but that is not easy to implement, so I haven’t got around to it, yet.

#### 4.2.6 sshx

As you would expect, this is similar to ssh, only a little different. Whereas ssh opens a normal interactive shell on the remote host, this option uses ‘ssh -t -t host -l user /bin/sh’ to open a connection. This is useful for users where the normal login shell is set up to ask them a number of questions when logging in. This procedure avoids these questions, and just gives TRAMP a more-or-less ‘standard’ login shell to work with.

Note that this procedure does not eliminate questions asked by ssh itself. For example, ssh might ask “Are you sure you want to continue connecting?” if the host key of the remote host is not known. TRAMP does not know how to deal with such a question (yet), therefore you will need to make sure that you can log in without such questions.

This is also useful for Windows users where ssh, when invoked from an Emacs buffer, tells them that it is not allocating a pseudo tty. When this happens, the login shell is wont to not print any shell prompt, which confuses TRAMP mightily.

This supports the ‘-p’ argument.

This method is also similar to ssh. It only uses the krlogin -x command to log in to the remote host.

#### 4.2.8 ksu

This is another method from the Kerberos suite. It behaves like su.

Kerberos 套件的另一种方法，行为类似 su。

This method is mostly interesting for Windows users using the PuTTY implementation of SSH. It uses ‘plink -ssh’ to log in to the remote host.

With a recent PuTTY, it is recommended to check the ‘Share SSH connections if possible’ control for that session.

This method supports the ‘-P’ argument.

Another method using PuTTY on Windows. Instead of host names, it expects PuTTY session names, calling ‘plink -load session -t’. User names and port numbers must be defined in the session.

With a recent PuTTY, it is recommended to check the ‘Share SSH connections if possible’ control for that session.

### 4.3 External methods

The external methods operate through multiple channels, using the remote shell connection for many actions while delegating file transfers to an external transfer utility.

external 方法有多种渠道来操作，当授权文件传输给外部传输工具后，可以使用远程 shell 连接来进行很多操作。

This saves the overhead of encoding and decoding that multiplexing the transfer through the one connection has with the inline methods.

Since external methods need their own overhead opening a new channel, all files which are smaller than tramp-copy-size-limit are still transferred with the corresponding inline method. It should provide a fair trade-off between both approaches.

external 方法开通一个新通道需要产生额外的开销，大小低于 tramp-copy-size-limitare 的文件还是会用对应的 inline 方法来传输，这样在提供了两种方法间的一种平衡。

#### 4.3.1 rcp—rsh and rcp

This method uses the rsh and rcp commands to connect to the remote host and transfer files. This is probably the fastest connection method available.

The alternative method remcp uses the remsh and rcp commands. It should be applied on hosts where remsh is used instead of rsh.

#### 4.3.2 scp—ssh and scp

Using ssh to connect to the remote host and scp to transfer files between the hosts is the best method for securely connecting to a remote host and accessing files.

The performance of this option is also quite good. It may be slower than the inline methods when you often open and close small files however. The cost of the cryptographic handshake at the start of an scp session can begin to absorb the advantage that the lack of encoding and decoding presents.

All the ssh based methods support the ‘-p’ feature where you can specify a port number to connect to in the host name. For example, the host name host#42 tells TRAMP to specify ‘-p 42’ in the argument list for ssh, and to specify ‘-P 42’ in the argument list for scp.

#### 4.3.3 rsync—ssh and rsync

Using the ssh command to connect securely to the remote host and the rsync command to transfer files is almost identical to the scp method.

While rsync performs much better than scp when transferring files that exist on both hosts, this advantage is lost if the file exists only on one side of the connection. A file can exists on both the remote and local host, when you copy a file from/to a remote host. When you just open a file from the remote host (or write a file there), a temporary file on the local side is kept as long as the corresponding buffer, visiting this file, is alive.

This method supports the ‘-p’ argument.

#### 4.3.4 scpx—ssh and scp

As you would expect, this is similar to scp, only a little different. Whereas scp opens a normal interactive shell on the remote host, this option uses ‘ssh -t -t host -l user /bin/sh’ to open a connection. This is useful for users where the normal login shell is set up to ask them a number of questions when logging in. This procedure avoids these questions, and just gives TRAMP a more-or-less ‘standard’ login shell to work with.

This is also useful for Windows users where ssh, when invoked from an Emacs buffer, tells them that it is not allocating a pseudo tty. When this happens, the login shell is wont to not print any shell prompt, which confuses TRAMP mightily.

This method supports the ‘-p’ argument.

These methods are similar to scp or sftp, but they use the plink command to connect to the remote host, and they use pscp or psftp for transferring the files. These programs are part of PuTTY, an SSH implementation for Windows.

With a recent PuTTY, it is recommended to configure the ‘Share SSH connections if possible’ control for that session.

These methods support the ‘-P’ argument.

#### 4.3.7 fcp—fsh and fcp

This method is similar to scp, but it uses the fsh command to connect to the remote host, and it uses fcp for transferring the files. fsh/fcp are a front-end for ssh which allow for reusing the same ssh session for submitting several commands. This avoids the startup overhead of scp (which has to establish a secure connection whenever it is called). Note, however, that you can also use one of the inline methods to achieve a similar effect.

This method uses the command ‘fsh host -l user /bin/sh -i’ to establish the connection, it does not work to just say fsh host -l user.

There is no inline method using fsh as the multiplexing provided by the program is not very useful in our context. TRAMP opens just one connection to the remote host and then keeps it open, anyway.

#### 4.3.8 nc—telnet and nc

Using telnet to connect to the remote host and nc for file transfer is often the only possibility to access dumb devices, like routers or NAS hosts. Those hosts have just a restricted busybox as local shell, and there is no program to encode and decode files for transfer.

#### 4.3.9 ftp

This is not a native TRAMP method. Instead, it forwards all requests to Ange-FTP.

#### 4.3.10 smb—smbclient

This is another not native TRAMP method. It uses the smbclient command on different Unices in order to connect to an SMB server. An SMB server might be a Samba (or CIFS) server on another UNIX host or, more interesting, a host running MS Windows. So far, it is tested against MS Windows NT, MS Windows 2000, MS Windows XP, MS Windows Vista, and MS Windows 7.

PS1="[\u@\h \w]$" fi  #### 4.16.8 busybox / nc The nc command will be used with the nc method. On the remote host, a listener will be installed. Unfortunately, the command line syntax for this has been changed with the different busybox versions. TRAMP uses the following syntax (see tramp-methods): If your remote nc refuses to accept the -p parameter, you could overwrite the syntax with the following form: (add-to-list 'tramp-connection-properties (,(regexp-quote "192.168.0.1") "remote-copy-args" (("-l") ("%r"))))  with ‘192.168.0.1’ being the IP address of your remote host (see Predefined connection information). ### 4.17 Android shell setup hints Android devices use a restricted shell. They can be accessed via the adb method. However, this restricts the access to a USB connection, and it requires the installation of the Android SDK on the local host. When an sshd process runs on the Android device, like provided by the SSHDroid app, any ssh-based method can be used. This requires some special settings. The default shell /bin/sh does not exist. Instead, you shall use just sh, which invokes the shell installed on the device. You can instruct TRAMP by this form: (add-to-list 'tramp-connection-properties (list (regexp-quote "192.168.0.26") "remote-shell" "sh"))  with ‘192.168.0.26’ being the IP address of your Android device (see Predefined connection information). The user settings for the PATH environment variable must be preserved. It has also been reported, that the commands in /system/xbin are better suited than the ones in /system/bin. Add these setting: (add-to-list 'tramp-remote-path 'tramp-own-remote-path) (add-to-list 'tramp-remote-path "/system/xbin")  If the Android device is not ‘rooted’, you must give the shell a writable directory for temporary files: (add-to-list 'tramp-remote-process-environment "TMPDIR=$HOME")


Now you shall be able to open a remote connection with C-x C-f /ssh:192.168.0.26#2222:, given that sshd listens on port ‘2222’.

It is also recommended to add a corresponding entry to your ~/.ssh/config for that connection, like

Host android
HostName 192.168.0.26
User root
Port 2222


In this case, you must change the setting for the remote shell to

(add-to-list 'tramp-connection-properties
(list (regexp-quote "android") "remote-shell" "sh"))


You would open the connection with C-x C-f /ssh:android: then.

### 4.18 Auto-save and Backup configuration

Normally, Emacs writes backup files to the same directory as the original files, but this behavior can be changed via the variable backup-directory-alist. In connection with TRAMP, this can have unexpected side effects. Suppose that you specify that all backups should go to the directory ~/.emacs.d/backups/, and then you edit the file /su:root@localhost:/etc/secretfile. The effect is that the backup file will be owned by you and not by root, thus possibly enabling others to see it even if they were not intended to see it.

When backup-directory-alist is nil (the default), such problems do not occur.

Therefore, it is useful to set special values for TRAMP files. For example, the following statement effectively ‘turns off’ the effect of backup-directory-alist for TRAMP files:

(add-to-list 'backup-directory-alist
(cons tramp-file-name-regexp nil))


It is also possible to disable backups depending on the used method. The following code disables backups for the su and sudo methods:

(setq backup-enable-predicate
(lambda (name)
(and (normal-backup-enable-predicate name)
(not
(let ((method (file-remote-p name 'method)))
(when (stringp method)
(member method '("su" "sudo"))))))))


Another possibility is to use the TRAMP variable tramp-backup-directory-alist. This variable has the same meaning like backup-directory-alist. If a TRAMP file is backed up, and DIRECTORY is an absolute local file name, DIRECTORY is prepended with the TRAMP file name prefix of the file to be backed up.

Example:

(add-to-list 'backup-directory-alist
(cons "." "~/.emacs.d/backups/"))
(setq tramp-backup-directory-alist backup-directory-alist)


The backup file name of su:root@localhost:/etc/secretfile would be /su:root@localhost:~.emacs.d/backups/!su:root@localhost:!etc!secretfile~

The same problem can happen with auto-saving files. The variable auto-save-file-name-transforms keeps information, on which directory an auto-saved file should go. By default, it is initialized for TRAMP files to the local temporary directory.

On some versions of Emacs, namely the version built for Debian GNU/Linux, the variable auto-save-file-name-transforms contains the directory where Emacs was built. A workaround is to manually set the variable to a sane value.

If auto-saved files should go into the same directory as the original files, auto-save-file-name-transforms should be set to nil.

Another possibility is to set the variable tramp-auto-save-directory to a proper value.

### 4.19 Issues with Cygwin ssh

The recent Cygwin installation of ssh works only with a Cygwinized Emacs. You can check it by typing M-x eshell, and starting ssh test.host. The problem is evident if you see a message like this:

Pseudo-terminal will not be allocated because stdin is not a terminal.

Older ssh versions of Cygwin are told to cooperate with TRAMP selecting sshx as the connection method. You can find information about setting up Cygwin in their FAQ at http://cygwin.com/faq/.

If you wish to use the scpx connection method, then you might have the problem that Emacs calls scp with a Windows file name such as c:/foo. The Cygwin version of scp does not know about Windows file names and interprets this as a remote file name on the host c.

One possible workaround is to write a wrapper script for scp which converts the Windows file name to a Cygwinized file name.

If you want to use either ssh based method on Windows, then you might encounter problems with ssh-agent. Using this program, you can avoid typing the pass-phrase every time you log in. However, if you start Emacs from a desktop shortcut, then the environment variable SSH_AUTH_SOCK is not set and so Emacs and thus TRAMP and thus ssh and scp started from TRAMP cannot communicate with ssh-agent. It works better to start Emacs from the shell.

If anyone knows how to start ssh-agent under Windows in such a way that desktop shortcuts can profit, please holler. I don’t really know anything at all about Windows…

## 5 Using TRAMP

Once you have installed TRAMP it will operate fairly transparently. You will be able to access files on any remote host that you can log in to as though they were local.

Files are specified to TRAMP using a formalized syntax specifying the details of the system to connect to. This is similar to the syntax used by the Ange-FTP package.

Something that might happen which surprises you is that Emacs remembers all your keystrokes, so if you see a password prompt from Emacs, say, and hit RET twice instead of once, then the second keystroke will be processed by Emacs after TRAMP has done its thing. Why, this type-ahead is normal behavior, you say. Right you are, but be aware that opening a remote file might take quite a while, maybe half a minute when a connection needs to be opened. Maybe after half a minute you have already forgotten that you hit that key!

### 5.1 TRAMP file name conventions

To access the file localname on the remote host host you would specify the file name /host:localname. This will connect to host and transfer the file using the default method. See Default Method. 通过 /host:localhostname 指定要访问的远程主机上的文件。这将会连接到远程主机并使用默认的方法传输该文件。

Some examples of TRAMP file names are shown below.

/melancholia:.emacs


Edit the file .emacs in your home directory on the host melancholia.

/melancholia.danann.net:.emacs


This edits the same file, using the fully qualified domain name of the host.

/melancholia:~/.emacs


This also edits the same file; the ~ is expanded to your home directory on the remote host, just like it is locally.

/melancholia:~daniel/.emacs


This edits the file .emacs in the home directory of the user daniel on the host melancholia. The ~<user> construct is expanded to the home directory of that user on the remote host.

/melancholia:/etc/squid.conf


This edits the file /etc/squid.conf on the host melancholia.

host can also be an IPv4 or IPv6 address, like in /127.0.0.1:.emacs or /[::1]:.emacs. For syntactical reasons, IPv6 addresses must be embedded in square brackets [ and ].

host 也可以是 IPv4 或 IPv6 地址，由于文法原因，IPv6 地址需要放在中括号当中。

Unless you specify a different name to use, TRAMP will use the current local user name as the remote user name to log in with. If you need to log in as a different user, you can specify the user name as part of the file name.

To log in to the remote host as a specific user, you use the syntax /user@host:path/to.file. That means that connecting to melancholia as daniel and editing .emacs in your home directory you would specify /daniel@melancholia:.emacs.

It is also possible to specify other file transfer methods (see Inline methods, see External methods) as part of the file name. This is done by putting the method before the user and host name, as in /method: (Note the trailing colon). The user, host and file specification remain the same.

So, to connect to the host melancholia as daniel, using the ssh method to transfer files, and edit .emacs in my home directory I would specify the file name /ssh:daniel@melancholia:.emacs.

A remote file name containing a host name only, which is equal to a method name, is not allowed. If such a host name is used, it must always be preceded by an explicit method name, like /ssh:ssh:.

Finally, for some methods it is possible to specify a different port number than the default one, given by the method. This is specified by adding #<port> to the host name, like in /ssh:daniel@melancholia#42:.emacs.

### 5.2 File name completion

File name completion works with TRAMP for completion of method names, of user names and of host names as well as for completion of file names on remote hosts. In order to enable this, partial completion must be activated in your .emacs.

telnet:
tmp/
toto:


‘telnet:’ is a possible completion for the respective method, ‘tmp/’ stands for the directory tmp on your local host, and ‘toto:’ might be a host TRAMP has detected in your ~.ssh/known_hosts file (given you’re using default method ssh).

If you go on to type e TAB, the minibuffer is completed to ‘/telnet:’. Next TAB brings you all host names TRAMP detects in your /etc/hosts file, let’s say

/telnet:127.0.0.1:
/telnet:192.168.0.1:
/telnet:[::1]:
/telnet:localhost:
/telnet:melancholia.danann.net:
/telnet:melancholia:


Now you can choose the desired host, and you can continue to complete file names on that host.

If the configuration files (see Customizing Completion), which TRAMP uses for analysis of completion, offer user names, those user names will be taken into account as well.

Remote hosts which have been visited in the past and kept persistently (see Connection caching) will be offered too.

Once the remote host identification is completed, it comes to file name completion on the remote host. This works pretty much like for files on the local host, with the exception that minibuffer killing via a double-slash works only on the file name part, except that file name part starts with //. A triple-slash stands for the default behavior.

C-x C-f /telnet:melancholia:/usr/local/bin//etc TAB
-| /telnet:melancholia:/etc

C-x C-f /telnet:melancholia://etc TAB
-| /etc

C-x C-f /telnet:melancholia:/usr/local/bin///etc TAB
-| /etc


A remote directory might have changed its contents out of Emacs control, for example by creation or deletion of files by other processes. Therefore, during file name completion, the remote directory contents are reread regularly in order to detect such changes, which would be invisible otherwise (see Connection caching).

This variable defines the number of seconds since last remote command before rereading a directory contents. A value of 0 would require an immediate reread during file name completion, nil means to use always cached values for the directory contents.

### 5.3 Declaring multiple hops in the file name

Multiple hops are configured with the variable tramp-default-proxies-alist (see Multi-hops). However, sometimes it is desirable to reach a remote host immediately, without configuration changes. This can be reached by an ad-hoc specification of the proxies.

A proxy looks like a remote file name specification without the local file name part. It is prepended to the target remote file name, separated by ‘|’. As an example, a remote file on ‘you@remotehost’, passing the proxy ‘bird@bastion’, could be opened by

C-x C-f /ssh:bird@bastion|ssh:you@remotehost:/path


Multiple hops can be cascaded, separating all proxies by ‘|’. The proxies can also contain the patterns %h or %u.

The ad-hoc definition is added on the fly to tramp-default-proxies-alist. Therefore, during the lifetime of the Emacs session it is not necessary to enter this ad-hoc specification, again. The remote file name ‘/ssh:you@remotehost:/path’ would be sufficient from now on.

This customer option controls whether ad-hoc definitions are kept persistently in tramp-default-proxies-alist. That means, those definitions are available also for future Emacs sessions.

### 5.4 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.

tramp 支持在远程主机上运行程序。这使得不需要修改远程主机上的名字就可以使用 emacs packages。这不适用于 ftp method。也不支持协助 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 host 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 host, 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.

(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.4.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.4.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 file 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 file 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 file name, if you are on a remote buffer, and if explicit-shell-file-name is equal to nil.

#### 5.4.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 behavior can be reached by M-x auto-revert-tail-mode, if available.

#### 5.4.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.4.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.4.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" "-")) Previous: Remote processes, Up: Usage [Contents][Index]

### 5.5 Cleanup remote connections

Sometimes it is useful to cleanup remote connections. The following commands support this.

#### 5.5.1 Command: tramp-cleanup-connection vec

This command flushes all connection related objects. vec is the internal representation of a remote connection. Called interactively, the command offers all active remote connections in the minibuffer as remote file name prefix like /method:user@host:. The cleanup includes password cache (see Password handling), file cache, connection cache (see Connection caching), connection buffers.

#### 5.5.2 Command: tramp-cleanup-this-connection

This command flushes all objects of the current buffer’s remote connection. The same objects are removed as in tramp-cleanup-connection.

#### 5.5.3 Command: tramp-cleanup-all-connections

This command flushes objects for all active remote connections. The same objects are removed as in tramp-cleanup-connection.

#### 5.5.4 Command: tramp-cleanup-all-buffers

Like in tramp-cleanup-all-connections, all remote connections are cleaned up. Additionally all buffers, which are related to a remote connection, are killed.

Created: 2016-08-07 Sun 19:30

Validate