TRAMP mode manual

Table of Contents

参照《TRAMP version 2.2.11 User Manual》在 Emacs 中使用 TRAMP mode。

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.

可以通过 rsh、rlogin、telnet 或者类似的连接方法来访问远程主机。这些连接方法必须能够成功传送 ASCII 为可用的,但不必是 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.

大文件的最快传输方法依赖于远程文件传输软件包,如 rcp、scp、rsync 或者 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 还支持直接通过 shell 进行编码传输。这要求远程主机上 mimencode 或者 uuencode 工具可用,这些方法通常更适合快速地传输小文件。

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.

这部分尝试解释 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:

假设键入 C-x C-f 并输入了部分 tramp 文件名,接着按下 tab 进行补全。进一步假设这是第一次调用 TRAMP 访问主机。发生的事情如下:

  • 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.

希望这能够让你对使用 tramp 打开文件的时候发生了什么有一个基本的认识。

2 Obtaining TRAMP

3 History of 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.

通常 TRAMP 初始安装后就已经功能齐全。初始配置使用 scp 程序连接远程主机。所以最简单的情况下,只需要 c-x c-f 然后输入文件名 /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.

一些主机上打开链接可能会有问题。这和远程 shell 的行为有关。查看 Remote shell setup 了解相关细节。

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

如果不想使用这些命令连接远程主机,应该修改 tramp 使用的默认连接和传输方法。tramp 可以使用多种不同的方法来连接远程主机和传输文件。

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

如果不知道哪种方法适合你,看一下 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.

有两种类型的传输方法,各有优劣。两种类型的连接都使用远程 shell 访问程序,如 rsh、ssh 或 telnet,来连接远程主机。

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.

加载或保存文件需要在两个主机间传输文件内容。可以通过两种方法传输:inline 方法与远程主机的登录共用一条连接,external 方法使用远程拷贝程序(如 rcp、scp 或 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.

一个例外是是基于 scp 的传输方法。虽然这些方法实际传输文件的时候表现更好,但是启动时候的加密协商可能会抵消文件传输带来的方面的提升。

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 可以利用 emacs 的特性来编码或解码文件,或者也可以使用外部命令来完成这一任务。

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.

如果远程主机上所有命令都不可用,tramp 会传输小段的 Perl 代码到远程主机,尝试使用它来编码和解码。

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.

变量 tramp-inline-compress-start-size 控制一个文件在编码之前是否应该被压缩。这可以提高大文本文件传输的速度。

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.

如果操作系统提供了替代 rsh 的 remsh,可以用 remsh。这适用于 HP-UX 或者 Cray UNICOS。

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.

所有基于 ssh 的方法都有一个额外的特性:可以通过 host#42 这种方式来指定主机名字,这像 ssh 命令传递 -p 42 来连接主机。

4.2.3 telnet

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

和 rsh 一样,也是不安全的方法。

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.

该方法根本不会连接到远程主机,而是通过 su 程序来允许以另外一个用户身份编辑文件。也就是说,文件名中的主机部分须是 localhost 或者函数(如 system-name)返回的主机名。这个规则的例外是 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.

和 su 类似,但是它使用 sudo 而不是 su 变为不同的用户。

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.

如你所料,和 ssh 类似,只有一点不同。ssh 在远程主机上打开一个正常的交互式 shell,而该选项使用‘ssh -t -t host -l user /bin/sh’打开一个连接。有时候用户打开登录连接会被问道很多问题,这时候这个选项就会避免这些问题,仅仅给 tramp 一个凑合着用的标准登录 shell 来用。

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.

请注意这个过程并不会减少 ssh 本身提出的问题。例如如果不知道远程主机的 key 话,ssh 可能会问:“你确定想要继续连接么”。tramp 是不知道应该如何处理这种问题的,因而你需要确保你可以不用回答这些问题就能登录。

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.

这对于 windows 用户也是有用的,从 emacs buffer 调用 ssh,告诉他们这不会分配一个伪终端。当发生这种情况发生时,登录 shell 不会打印任何让 tramp 迷惑不解的任何 shell 提示符。

This supports the ‘-p’ argument.

支持 -p 参数。

4.2.7 krlogin

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

这种方法也类似于 ssh。它只使用 krlogin - x 命令登录到远程主机。

4.2.8 ksu

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

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

4.2.9 plink

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.

这种方法对于 windows 用户来说是有趣的,它使用 ssh 的 putty 实现。使用 plink -ssh 来登录远程主机。

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.

4.2.10 plinkx

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.

windows 上使用 putty 的另一种方法,它使用 putty 会话名而不是主机名,调用 ‘plink -loadsession -t’。用户名和端口号必须在会话中定义。

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

使用最近的 putty,建议检查会话的 ‘Share SSH connections if possible’ 控制项。

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.

这节省了 inline 方法中复用同一连接进行传输时候编码和解码的开销。

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.

这种方法使用 rsh 和 rcp 命令连接远程主机和传输文件。这可能是最快的连接方法。

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

替代方法 remcp 使用 remsh 和 rcp 命令。如果可用,应该使用 remsh 替代 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.

使用 ssh 连接远程主机,scp 在主机间传输文件,这是安全的连接远程主机和访问文件的最好方法。

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.

这种方法的性能也非常好,然而如果经常打开和关闭小文件的话,它可能比内部方法要慢。scp 会话开始阶段的加密握手可能抵消编码和解码方面的优势。

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.

所有基于 ssh 的方法都支持-p 特性,通过该特性可以在主机名中指定一个端口号。例如,主机名 host#42 告诉 tramp ‘-p 42’ 添加到 ssh 的参数列表中,‘-P 42’添加到 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.

使用 ssh 安全的连接远程主机,rsync 来传输文件,这种方法和 scp 没啥差别。

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.

当传输的文件都在两端主机上存在时,rsync 性能要比 scp 更好点。如果文件只存在一端,这种优势就不复存在。当从(向)远程主机拷贝文件时,文件就存在于两端了。当从远程主机打开文件(或向他写),本地这边会存在与正在编辑的 buffer 对应的临时文件。

This method supports the ‘-p’ argument.

这种方法也支持-p 参数。

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.

如你所想,这种方法和 scp 类似,只有一点点不同。还是上面 inline 方法中介绍的避免打开登录 shell 时候回答一系列的问题。

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.

4.3.5 pscp—plink and pscp

4.3.6 psftp—plink and psftp

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.

这两种方法类似 scp 或 sftp,但是他们使用 plink 命令来连接远程主机,pscp 或 psftp 来传输文件。这些程序是 putty 的部分,putty 是 windows 上 ssh 的一种实现。

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.

类似 scp,但是使用 fsh 连接远程主机间,使用 fcp 传输文件。

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.

使用 telnet 连接远程主机,使用 nc 进行文件传输,可能经常这么做访问哑终端设备,像路由器或 NAS 主机。这些主机有一个严格限制的 busybox 或本地 shell。没有程序可以编码解码文件以供传输。

4.3.9 ftp

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

并不是一个内置的 tramp 方法。相反,他将所有的请求都转发到了 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.

这是另一种肺内置方法。它在不同的 Unices 上使用 smbclient 命令去连接 SMB 服务器。SMB 服务器可能是另一台 UNIX 主机上的 Samba(或 CIFS)服务,或者更有趣的是可能运行在 MS Windows 上。目前只在 MS Windows NT, MS Windows 2000, MS Windows XP, MS Windows Vista, and MS Windows 7 上进行了测试。

The first directory in the localname must be a share name on the remote host. Remember that the $ character, in which default shares usually end, must be written $$ due to environment variable substitution in file names. If no share name is given (i.e., remote directory /), all available shares are listed.

Since authorization is done on share level, you will always be prompted for a password if you access another share on the same host. This can be suppressed by Password handling.

For authorization, MS Windows uses both a user name and a domain name. Because of this, the TRAMP syntax has been extended: you can specify a user name which looks like user%domain (the real user name, then a percent sign, then the domain name). So, to connect to the host melancholia as user daniel of the domain BIZARRE, and edit .emacs in the home directory (share daniel$) I would specify the file name smb:daniel%BIZARRE@melancholia:/daniel$$.emacs.

Depending on the Windows domain configuration, a Windows user might be considered as domain user per default. In order to connect as local user, the WINS name of that host must be given as domain name. Usually, it is the host name in capital letters. In the example above, the local user daniel would be specified as smb:daniel%MELANCHOLIA@melancholia:/daniel$$.emacs.

The domain name as well as the user name are optional. If no user name is specified at all, the anonymous user (without password prompting) is assumed. This is different from all other TRAMP methods, where in such a case the local user name is taken.

The smb method supports the ‘-p’ argument.

Please note: If Emacs runs locally under MS Windows, this method isn’t available. Instead, you can use UNC file names like /melancholia/daniel$$.emacs. The only disadvantage is that there’s no possibility to specify another user name.

请注意:如果在 ms windows 下面运行 emacs,这种方法是不可用的。

4.3.11 adb

This special method uses the Android Debug Bridge for accessing Android devices. The Android Debug Bridge must be installed locally. Some GNU/Linux distributions offer it for installation, otherwise it can be installed as part of the Android SDK. If the adb program is not found via the PATH environment variable, the variable tramp-adb-program must point to its absolute path.

Tramp does not connect Android devices to adb. This must be performed outside Emacs. If there is exactly one Android device connected to adb, a host name is not needed in the remote file name. The default TRAMP name to be used is /adb:: therefore. Otherwise, one could find potential host names with the command adb devices.

Usually, the adb method does not need any user name. It runs under the permissions of the adbd process on the Android device. If a user name is specified, TRAMP applies an su on the device. This does not work with all Android devices, especially with unrooted ones. In that case, an error message is displayed.

4.4 GVFS based external methods

The connection methods described in this section are based on GVFS Via GVFS, the remote filesystem is mounted locally through FUSE. TRAMP uses this local mounted directory internally.

The communication with GVFS is implemented via D-Bus messages. Therefore, your Emacs must have D-Bus integration, see (dbus)D-Bus.

4.4.1 dav

This method provides access to WebDAV files and directories. There exists also the external method davs, which uses SSL encryption for the access.

Both methods support the port number specification as discussed above.

4.4.2 obex

OBEX is an FTP-like access protocol for simple devices, like cell phones. For the time being, TRAMP only supports OBEX over Bluetooth.

4.4.3 sftp

As you might expect, this method uses sftp in order to access the remote host. Contrary to the ssh and scp methods, it doesn’t open an ssh session for login. Therefore, it could be used to access to remote hosts which refuse ssh for security reasons.

4.4.4 synce

The synce method allows communication with Windows Mobile devices. Beside GVFS for mounting remote files and directories via FUSE, it also needs the SYNCE-GVFS plugin.

4.4.5 User Option: tramp-gvfs-methods

This customer option, a list, defines the external methods which shall be used with GVFS. Per default, these are dav, davs, obex, sftp and synce. Other possible values are ftp and smb.

4.5 Gateway methods

Gateway methods are not methods to access a remote host directly. These methods are intended to pass firewalls or proxy servers. Therefore, they can be used for proxy host declarations (see Multi-hops) only.

Gateway 方法并不是用来直接连接远程主机。这些方法是为了穿过防火墙或者代理服务器。因而他们只能用于代理主机声明(参看multi-hops)。

A gateway method must always come along with a method which supports port setting. This is because TRAMP targets the accompanied method to localhost#random_port, from where the firewall or proxy server is accessed.

gateway 方法必须伴随一个支持端口设置的方法。

Gateway methods support user name and password declarations. These are used to authenticate towards the corresponding firewall or proxy server. They can be passed only if your friendly administrator has granted your access.

Gateway 方法支持用户名和密码声明。他们用来验证对应的防火墙或代理服务器。只有管理授权访问他们才能通过。

4.5.1 tunnel

This method implements an HTTP tunnel via the CONNECT command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server shall support this command.

该方法通过 CONNECT 命令实现了 HTTP 隧道。任何兼容 HTTP1.1 的服务器都支持该命令。

As authentication method, only Basic Authentication (see RFC 2617) is implemented so far. If no port number is given in the declaration, port 8080 is used for the proxy server.

作为身份验证方法,目前支持基本的验证。如果声明中没有指定端口号,代理服务器使用 8080。

4.5.2 socks

The socks method provides access to SOCKSv5 servers (see RFC 1928). Username/Password Authentication according to RFC 1929 is supported.

socks 用来访问 SOCKSv5 服务器。

The default port number of the socks server is 1080, if not specified otherwise.

socks 服务器如果没有指定,默认端口是 1080。

4.6 Selecting a default method

When you select an appropriate transfer method for your typical usage you should set the variable tramp-default-method to reflect that choice. This variable controls which method will be used when a method is not specified in the TRAMP file name. For example:

变量 tramp-default-method 指定默认的传输方法。

(setq tramp-default-method "ssh")

You can also specify different methods for certain user/host combinations, via the variable tramp-default-method-alist. For example, the following two lines specify to use the ssh method for all user names matching ‘john’ and the rsync method for all host names matching ‘lily’. The third line specifies to use the su method for the user ‘root’ on the host ‘localhost’.

也可以通过变量 tramp-default-method-alist 针对特定的 user/host 组合设置不同的方法。

(add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
(add-to-list 'tramp-default-method-alist '("lily" "" "rsync"))
(add-to-list 'tramp-default-method-alist
             '("\\`localhost\\'" "\\`root\\'" "su"))

See the documentation for the variable tramp-default-method-alist for more details.

External methods are normally preferable to inline methods, giving better performance.

external 方法通常比 inline 方法提供更好的性能。

See Inline methods. See External methods.

Another consideration with the selection of transfer methods is the environment you will use them in and, especially when used over the Internet, the security implications of your preferred method.

选择传输方法另一个要考虑的因素是使用环境,特别在 Internet 中使用时,应该使用更安全的实现。

The rsh and telnet methods send your password as plain text as you log in to the remote host, as well as transferring the files in such a way that the content can easily be read from other hosts.

rsh 和 telnet 方法登录远程服务器的时候明文发送密码,传输文件也是如此,这样很容易被其他主机截获读取。

If you need to connect to remote systems that are accessible from the Internet, you should give serious thought to using ssh based methods to connect. These provide a much higher level of security, making it a non-trivial exercise for someone to obtain your password or read the content of the files you are editing.

如果你需要从 Internet 访问远程主机,应该认真考虑使用基于 ssh 的方法来连接。他们提供了更高级别的安全,增加了其他人获得你的密码或者读取正在编辑的内容的难度。

4.6.1 Which method is the right one for me?

Given all of the above, you are probably thinking that this is all fine and good, but it’s not helping you to choose a method! Right you are. As a developer, we don’t want to boss our users around but give them maximum freedom instead. However, the reality is that some users would like to have some guidance, so here I’ll try to give you this guidance without bossing you around. You tell me whether it works …

说了这么多,你可能会觉得这些都很好,但是他没有能帮助你选择一个 method!没错。作为开发者,我们不想把用户呼来唤去,而是要给他们最大程度的自由。然而,现实是有些用户希望能得到一些知道,所以这里给出一些指导而不是指挥你团团转。你告诉我它是不是可行。。。

My suggestion is to use an inline method. For large files, external methods might be more efficient, but I guess that most people will want to edit mostly small files. And if you access large text files, compression (driven by tramp-inline-compress-start-size) shall still result in good performance.

我的建议是使用 inline 方法。对于大文件,外部方法可能更有效率,但我想大多数人主要还是想编辑小文件。如果访问大文本文件,压缩仍然会提供好的性能。

I guess that these days, most people can access a remote host by using ssh. So I suggest that you use the ssh method. So, type C-x C-f /ssh:root@otherhost:/etc/motd RET to edit the /etc/motd file on the other host.

我想现在大多数人能够通过 ssh 来访问元和才能主机。所以我建议使用 ssh 方法。

If you can’t use ssh to log in to the remote host, then select a method that uses a program that works. For instance, Windows users might like the plink method which uses the PuTTY implementation of ssh. Or you use Kerberos and thus like krlogin.

如果不能使用 ssh 登录远程主机,选择一个可用的方法。例如 windows 用户可能喜欢使用 plink。Kerberos 用户可能喜欢 krlogin。

For the special case of editing files on the local host as another user, see the su or sudo methods. They offer shortened syntax for the ‘root’ account, like /su::/etc/motd.

对于使用其他用户身份编辑本地主机上文件的特殊情况,看一下 su 或者 sudo 方法。

People who edit large files may want to consider scp instead of ssh, or pscp instead of plink. These external methods are faster than inline methods for large files. Note, however, that external methods suffer from some limitations. Please try first whether you really get a noticeable speed advantage from using an external method! Maybe even for large files, inline methods are fast enough.

编辑大文件可以考虑 scp 代替 ssh,或者 pscp 代替 plink。这些 external 方法在处理大文件方面要快于 inline 方法。然而,请注意 external 方法受到一些限制。不管 external 方法是否能够得到明显的速度优势,先试试 inline 方法。可能即使对于大文件,inline 方法也足够快。

4.7 Selecting a default user

The user part of a TRAMP file name can be omitted. Usually, it is replaced by the user name you are logged in. Often, this is not what you want. A typical use of TRAMP might be to edit some files with root permissions on the local host. This case, you should set the variable tramp-default-user to reflect that choice. For example:

可以忽略 tramp 文件名中的的用户部分。通常情况下会用你登录的用户名代替。有时候这非你所想。一个典型的情况是本地主机上使用 root 权限来编辑一些文件。这种情况下,你应该设定 tramp-default-user。例如:

(setq tramp-default-user "root")

tramp-default-user is regarded as obsolete, and will be removed soon.

tramp-default-user 已被弃用,很快就会被移除。

You can also specify different users for certain method/host combinations, via the variable tramp-default-user-alist. For example, if you always have to use the user ‘john’ in the domain ‘somewhere.else’, you can specify the following:

可以通过 tramp-default-user-alist 为特定的 method/host 组合指定不同的用户。

(add-to-list 'tramp-default-user-alist
             '("ssh" ".*\\.somewhere\\.else\\'" "john"))

See the documentation for the variable tramp-default-user-alist for more details.

One trap to fall in must be known. If TRAMP finds a default user, this user will be passed always to the connection command as parameter (for example ssh here.somewhere.else -l john. If you have specified another user for your command in its configuration files, TRAMP cannot know it, and the remote access will fail. If you have specified in the given example in ~/.ssh/config the lines

这里有一个必须知道的陷阱。如果 tramp 找到一个默认的用户,该用户总是会作为参数在连接的时候进行传递。(例如 ssh here.somewhere.else -l john。如果在配置文件中指定了另外一个用户名,tramp 不会知道它,进而远程访问就会失败。如果在 ~/.ssh/config 中进行了指定:

Host here.somewhere.else
	 User lily

than you must discard selecting a default user by TRAMP. This will be done by setting it to nil (or ‘lily’, likewise):

必须放弃通过 tramp 选择默认用户。应该进行如下设置:

(add-to-list 'tramp-default-user-alist
             '("ssh" "\\`here\\.somewhere\\.else\\'" nil))

The last entry in tramp-default-user-alist could be your default user you’ll apply predominantly. You shall append it to that list at the end:

(add-to-list 'tramp-default-user-alist '(nil nil "jonas") t)

4.8 Selecting a default host

Finally, it is even possible to omit the host name part of a TRAMP file name. This case, the value of the variable tramp-default-host is used. Per default, it is initialized with the host name your local Emacs is running.

最后,可以在 tramp 文件名中省略掉主机部分。这种情况下,使用 tramp-default-host 指定的主机名。默认情况下,使用 emacs 运行的主机名进行初始化。

If you, for example, use TRAMP mainly to contact the host ‘target’ as user ‘john’, you can specify:

比如,使用 tramp 主要以 john 身份连接 target 主机,可以进行如下指定:

(setq tramp-default-user "john"
      tramp-default-host "target")

Then the simple file name ‘/ssh::’ will connect you to John’s home directory on target. Note, however, that the most simplification ‘/::’ won’t work, because ‘/:’ is the prefix for quoted file names.

然后简单的文件名“/ssh::”将会连接到 john 在 target 上的 home 目录进。

Like with methods and users, you can also specify different default hosts for certain method/user combinations via the variable tramp-default-host-alist. Usually, this isn’t necessary, because tramp-default-host should be sufficient. For some methods, like adb, that default value must be overwritten, which is already the initial value of tramp-default-host-alist.

就像 method 和 users,也可以通过 tramp-default-host-alist 针对 method/user 组合指定不同的 host。通常没必要这么做,因为 tramp-default-host 应该足够了。对于一些默认值必须要重写的 methods,例如 adb,已经通过 tramp-default-host-alist 的初始值把这事干了。

See the documentation for the variable tramp-default-host-alist for more details.

4.9 Connecting to a remote host using multiple hops

Sometimes, the methods described before are not sufficient. Sometimes, it is not possible to connect to a remote host using a simple command. For example, if you are in a secured network, you might have to log in to a bastion host first before you can connect to the outside world. Of course, the target host may also require a bastion host.


4.9.1 User Option: tramp-default-proxies-alist

In order to specify multiple hops, it is possible to define a proxy host to pass through, via the variable tramp-default-proxies-alist. This variable keeps a list of triples (host user proxy).

为了指定多个 hops,可能通过 tramp-default-proxies-alist 定义要通过的代理主机。这个变量保存了一个三元组的列表。

The first matching item specifies the proxy host to be passed for a file name located on a remote target matching user@host. host and user are regular expressions or nil, which is interpreted as a regular expression which always matches.

proxy must be a Tramp file name which localname part is ignored. Method and user name on proxy are optional, which is interpreted with the default values. The method must be an inline or gateway method (see Inline methods, see Gateway methods). If proxy is nil, no additional hop is required reaching user@host.

If you, for example, must pass the host ‘bastion.your.domain’ as user ‘bird’ for any remote host which is not located in your local domain, you can set

(add-to-list 'tramp-default-proxies-alist
             '("\\." nil "/ssh:bird@bastion.your.domain:"))
(add-to-list 'tramp-default-proxies-alist
             '("\\.your\\.domain\\'" nil nil))

Please note the order of the code. add-to-list adds elements at the beginning of a list. Therefore, most relevant rules must be added last.

Proxy hosts can be cascaded. If there is another host called ‘jump.your.domain’, which is the only one in your local domain who is allowed connecting ‘bastion.your.domain’, you can add another rule:

(add-to-list 'tramp-default-proxies-alist '("\\`bastion\\.your\\.domain\\'" "\\`bird\\'" "/ssh:jump.your.domain:")) proxy can contain the patterns %h or %u. These patterns are replaced by the strings matching host or user, respectively.

If you, for example, wants to work as ‘root’ on hosts in the domain ‘your.domain’, but login as ‘root’ is disabled for non-local access, you might add the following rule:

(add-to-list 'tramp-default-proxies-alist '("\\.your\\.domain\\'" "\\`root\\'" "/ssh:%h:")) Opening /sudo:randomhost.your.domain: would connect first ‘randomhost.your.domain’ via ssh under your account name, and perform sudo -u root on that host afterwards. It is important to know that the given method is applied on the host which has been reached so far. sudo -u root, applied on your local host, wouldn’t be useful here.

host, user and proxy can also be Lisp forms. These forms are evaluated, and must return a string, or nil. The previous example could be generalized then: For all hosts except my local one connect via ssh first, and apply sudo -u root afterwards:

(add-to-list 'tramp-default-proxies-alist '(nil "\\`root\\'" "/ssh:%h:")) (add-to-list 'tramp-default-proxies-alist '((regexp-quote (system-name)) nil nil)) This is the recommended configuration to work as ‘root’ on remote Ubuntu hosts.

Finally, tramp-default-proxies-alist can be used to pass firewalls or proxy servers. Imagine your local network has a host ‘proxy.your.domain’ which is used on port 3128 as HTTP proxy to the outer world. Your friendly administrator has granted you access under your user name to ‘host.other.domain’ on that proxy server.2 You would need to add the following rule:

(add-to-list 'tramp-default-proxies-alist '("\\`host\\.other\\.domain\\'" nil "/tunnel:proxy.your.domain#3128:")) Gateway methods can be declared as first hop only in a multiple hop chain.

Hops to be passed tend to be restricted firewalls and alike. Sometimes they offer limited features only, like running rbash (restricted bash). This must be told to TRAMP.

User Option: tramp-restricted-shell-hosts-alist This variable keeps a list of regular expressions, which denote hosts running a registered shell like "rbash". Those hosts can be used as proxies only.

If the bastion host from the example above runs a restricted shell, you shall apply

(add-to-list 'tramp-restricted-shell-hosts-alist "\\`bastion\\.your\\.domain\\'") Next: Customizing Completion, Previous: Multi-hops, Up: Configuration [Contents][Index]

4.10 Using Non-Standard Methods

There is a variable tramp-methods which you can change if the predefined methods don’t seem right.

如果预定义的 method 不能用的话,还可以通过变量 tramp-methods 来改变。

For the time being, I’ll refer you to the Lisp documentation of that variable, accessible with C-h v tramp-methods RET.

开始建议去看一下这个变量的 lisp 文档。

4.11 Selecting config files for user/host name completion

The variable tramp-completion-function-alist is intended to customize which files are taken into account for user and host name completion (see File name completion). For every method, it keeps a set of configuration files, accompanied by a Lisp function able to parse that file. Entries in tramp-completion-function-alist have the form (method pair1 pair2 …).

变量 tramp-copmletion-function-alist 用来指定那些可以用来补全用户名、主机名的文件。对于每种 method,他用一个集合来保存配置文件和分析该文件的 lisp 函数。tramp-completion-function-alist 中的实体形式如下:(method pair1 pair2)。

Each pair is composed of (function file). function is responsible to extract user names and host names from file for completion. There are two functions which access this variable:

每个 pair 形式如下(function file)。function 用来从文件中提取用户名和主机名来补全。有两个函数可以访问该变量:

Function: tramp-get-completion-function method

This function returns the list of completion functions for method.


   (tramp-get-completion-function "rsh")
⇒ ((tramp-parse-rhosts "/etc/hosts.equiv")
(tramp-parse-rhosts "~/.rhosts"))

Function: tramp-set-completion-function method function-list

This function sets function-list as list of completion functions for method.


(tramp-set-completion-function "ssh"
                               '((tramp-parse-sconfig "/etc/ssh_config")
                                 (tramp-parse-sconfig "~/.ssh/config")))
⇒ ((tramp-parse-sconfig "/etc/ssh_config")
   (tramp-parse-sconfig "~/.ssh/config"))

The following predefined functions parsing configuration files exist:


4.11.1 tramp-parse-rhosts

This function parses files which are syntactical equivalent to ~/.rhosts. It returns both host names and user names, if specified.

4.11.2 tramp-parse-shosts

This function parses files which are syntactical equivalent to ~/.ssh/known_hosts. Since there are no user names specified in such files, it can return host names only.

4.11.3 tramp-parse-sconfig

This function returns the host nicknames defined by Host entries in ~/.ssh/config style files.

4.11.4 tramp-parse-shostkeys

SSH2 parsing of directories /etc/ssh2/hostkeys/* and ~/ssh2/hostkeys/*. Hosts are coded in file names User names are always nil.

4.11.5 tramp-parse-sknownhosts

Another SSH2 style parsing of directories like /etc/ssh2/knownhosts/* and ~/ssh2/knownhosts/*. This case, hosts names are coded in file names User names are always nil.

4.11.6 tramp-parse-hosts

A function dedicated to /etc/hosts style files. It returns host names only.

4.11.7 tramp-parse-passwd

A function which parses /etc/passwd like files. Obviously, it can return user names only.

4.11.8 tramp-parse-netrc

Finally, a function which parses ~/.netrc like files. This includes also ~/.authinfo-style files.

If you want to keep your own data in a file, with your own structure, you might provide such a function as well. This function must meet the following conventions:

Function: my-tramp-parse file

file must be either a file name on your host, or nil. The function must return a list of (user host), which are taken as candidates for user and host name completion.


   (my-tramp-parse "~/.my-tramp-hosts")
   ⇒ ((nil "toto") ("daniel" "melancholia"))

4.12 Reusing passwords for several connections

Sometimes it is necessary to connect to the same remote host several times. Reentering passwords again and again would be annoying, when the chosen method does not support access without password prompt through own configuration.

有时候需要多次连接远程 host。当选择的 method 不能根据配置实现免密码提示访问的话,重复输入密码的确很烦人。

The best recommendation is to use the method’s own mechanism for password handling. Consider ssh-agent for ssh-like methods, or pageant for plink-like methods.

推荐的方法是使用 method 自己的密码处理机制。ssh 类似的方法考虑 ssh-agent,plink 类似的方法考虑 pagent。

However, if you cannot apply such native password handling, TRAMP offers alternatives. 然而,如果没有类似的自带密码处理处理方法,tramp 还提供了其他选择。

4.12.1 4.12.1 Using an authentication file

The package auth-source.el, originally developed in No Gnus, offers the possibility to read passwords from a file, like FTP does it from ~/.netrc. The default authentication file is ~/.authinfo.gpg, this can be changed via the variable auth-sources.

最初 No Gnus 开发的 auth-source.el 包可以从文件中读取密码,就像 ftp 从~/.netrc 读取一样。默认的身份验证文件是~/.autoinfo.gpg,可以通过变量 auto-source 改变。

A typical entry in the authentication file would be


machine melancholia port scp login daniel password geheim

The port can be any TRAMP method (see Inline methods, see External methods), to match only this method. When you omit the port, you match all TRAMP methods.

In case of problems, setting auth-source-debug to t gives useful debug messages.

如果出问题了,设置 auto-source-debug 为 t 会给出有用的 debug 信息。

4.12.2 4.12.2 Caching passwords

If there is no authentication file, TRAMP caches the passwords entered by you. They will be reused next time if a connection needs them for the same user name and host name, independently of the connection method.

如果没有身份认证文件,tramp 会缓存输入的密码,相同主机和用户名的连接就会用到他们,这对于每个连接方法是独立的。

Passwords are not saved permanently, that means the password caching is limited to the lifetime of your Emacs session. You can influence the lifetime of password caching by customizing the variable password-cache-expiry. The value is the number of seconds how long passwords are cached. Setting it to nil disables the expiration.

密码不会永久保存下来,也就是说缓存受限于 emacs 会话的生存期。可以通过 password-cache-expiry 影响密码的生存期。它的数值表示密码会被缓存多久。设置为 nil 关闭该功能。

If you don’t like this feature for security reasons, password caching can be disabled totally by customizing the variable password-cache (setting it to nil).

Implementation Note: password caching is based on the package password-cache.el. For the time being, it is activated only when this package is seen in the load-path while loading TRAMP.

4.13 Reusing connection related information

In order to reduce initial connection time, TRAMP stores connection related information persistently. The variable tramp-persistency-file-name keeps the file name where these information are written. Its default value is ~/.emacs.d/tramp. It is recommended to choose a local file name.

为了减少初始化连接时间,tramp 持久存储了连接相关信息。变量 tramp-persistency-file-name 保存了存储这些信息的文件名。默认是~/.emacs.d/tramp。推荐选择一个本地文件名。

TRAMP reads this file during startup, and writes it when exiting Emacs. You can simply remove this file if TRAMP shall be urged to recompute these information next Emacs startup time.

tramp 启动时读取该文件,退出 emacs 时进行写入。如果 emacs 下次启动的时候需要重新计算这些连接信息,可以简单的删除这些文件。

Using such persistent information can be disabled by setting tramp-persistency-file-name to nil.

将变量设为 nil 可以关闭该功能。

Once consequence of reusing connection related information is that tramp needs to distinguish hosts. If you, for example, run a local sshd on port 3001, which tunnels ssh to another host, you could access both /ssh:localhost: and /ssh:localhost#3001:. tramp would use the same host related information (like paths, Perl variants, etc) for both connections, although the information is valid only for one of them.

重用连接相关信息的结果是 tramp 需要区分主机。举例来说,如果运行在端口 3001 的 sshd 将 ssh 转发到另外一台主机,可以同时使用/ssh:localhost: and /ssh:localhost#3001:进行访问。tramp 对于两个连接使用相同的主机相关信息,尽管该信息只对其中一个是有用的。

In order to avoid trouble, you must use another host name for one of the connections, like introducing a Host section in ~/.ssh/config (see Frequently Asked Questions) or applying multiple hops (see Multi-hops).

为了避免这种麻烦,必须对其中一个连接使用另外一个主机名字。比如在~/.ssh/config 中加入一个 host section 或者使用多 hops。

When TRAMP detects a changed operating system version on a remote host (via the command uname -sr), it flushes all connection related information for this host, and opens the connection again.

当 tramp 检测到远程主机有一个操作系统版本改变时,它会弃用所有该主机的所有连接相关信息,重新打开连接。

4.14 Setting own connection related information

Sometimes, tramp is not able to detect correct connection related information. In such cases, you could tell tramp which value it has to take. Since this could result in errors, it has to be used with care.

有时候,tramp 不能够侦测到连接相关的信息。这时应该告诉 tramp 使用哪个。由于这可能会引发错误,所以应该小心使用。

Such settings can be performed via the list tramp-connection-properties. An entry in this list has the form (regexp property value). regexp matches remote file names for which a property shall be predefined. It can be nil. property is a string, and value the corresponding value. property could be any property found in the file tramp-persistency-file-name.

这样的设置通过列表 tramp-connection-properties 执行。列表中的条目格式是(regexp property value)。regexp 匹配属性应该被预定义的文件名。可以是 nil。property 是一个字符串,val 是对应值。property 可以是 tramp-persistency-file-name 中的任何属性。

A special property is "busybox". This must be set, if the remote host runs a very restricted busybox as shell, which closes the connection at will. Since there is no reliable test for this, tramp must be indicated this way. Example:

一个特殊的属性是 busybox。如果远程主机运行一个非常受限制的 busybox 作为 shell,该值必须设置,因为 busybox 可能会随意关闭连接。由于这一点没有可靠的测试,必须这样指示 tramp。例如:

(add-to-list 'tramp-connection-properties
             (list (regexp-quote "/ssh:user@randomhost.your.domain:")
                   "busybox" t))

4.15 How TRAMP finds and uses programs on the remote host

TRAMP depends on a number of programs on the remote host in order to function, including ls, test, find and cat.

tramp 的功能依赖远程主机上的很多程序,比如 ls,test,find 和 cat。

In addition to these required tools, there are various tools that may be required based on the connection method. See Inline methods and External methods for details on these.


Certain other tools, such as perl (or perl5) and grep will be used if they can be found. When they are available, they are used to improve the performance and accuracy of remote file access.

某些其他工具如果能找到也会被使用,比如 perl 或者 grep。如果他们可用,就会用他们来提高访问远程文件的性能和准确度。

4.15.1 User Option: tramp-remote-path

When TRAMP connects to the remote host, it searches for the programs that it can use. The variable tramp-remote-path controls the directories searched on the remote host.

当 tramp 连接远程主机后,他开始查找可用的程序。变量 tramp-remote-path 控制了在远程主机上的搜索目录。

By default, this is set to a reasonable set of defaults for most hosts. The symbol tramp-default-remote-path is a place holder, it is replaced by the list of directories received via the command getconf PATH on your remote host. For example, on Debian GNU/Linux this is /bin:/usr/bin, whereas on Solaris this is /usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin. It is recommended to apply this symbol on top of tramp-remote-path.

默认该值设定为对于大多数主机来说合理的值。符号 tramp-default-remote-path 是一个占位符,他被远程主机上命令 getconf PATH 返回的值来替代。

It is possible, however, that your local (or remote ;) system administrator has put the tools you want in some obscure local directory.


In this case, you can still use them with TRAMP. You simply need to add code to your .emacs to add the directory to the remote path. This will then be searched by TRAMP when you connect and the software found.

这种情况下,仍然可以使用 tramp。只需要在.emacs 里面添加代码,并在 remote path 里面添加目录即可。当再次连接远程主机的时候,tramp 就会搜索并发现那些目录。

To add a directory to the remote search path, you could use code such as:

;; We load TRAMP to define the variable.
(require 'tramp)
;; We have perl in "/usr/local/perl/bin"
(add-to-list 'tramp-remote-path "/usr/local/perl/bin")

Another possibility is to reuse the path settings of your remote account when you log in. Usually, these settings are overwritten, because they might not be useful for TRAMP. The place holder tramp-own-remote-path preserves these settings. You can activate it via

另一个可行的方法是登陆时重用远程账户的 path 设置。通常这些设置会被重写,因为他们对 tramp 是没用的。tramp-own-remote-path 占位符保存这些设置,可以这样激活它:

   (add-to-list 'tramp-remote-path 'tramp-own-remote-path)

TRAMP caches several information, like the Perl binary location. The changed remote search path wouldn’t affect these settings. In order to force TRAMP to recompute these values, you must exit Emacs, remove your persistency file (see Connection caching), and restart Emacs.

tramp 缓存了一些信息,如 perl 二进制文件位置。改变远程搜索路径不会影响这些设置。为了强制 tramp 重新计算这些,必须退出 emacs,删除持久文件,重启 emacs。

4.16 Remote shell setup hints

As explained in the Overview section, TRAMP connects to the remote host and talks to the shell it finds there. Of course, when you log in, the shell executes its init files. Suppose your init file requires you to enter the birth date of your mother; clearly TRAMP does not know this and hence fails to log you in to that host.

正如 Overview 节解释的,tramp 连接远程主机,并和找到的 shell 进行交谈,当然,等你登录的时候,shell 执行他的初始化文件。假设初始化文件需要你输入你妈妈的生日,显然 tramp 对此一无所知,因而这次登录也就失败了。

There are different possible strategies for pursuing this problem. One strategy is to enable TRAMP to deal with all possible situations. This is a losing battle, since it is not possible to deal with all situations. The other strategy is to require you to set up the remote host such that it behaves like TRAMP expects. This might be inconvenient because you have to invest a lot of effort into shell setup before you can begin to use TRAMP.

解决这个问题有各种不同的策略。其中一个就是让 tramp 处理各种可能的情况。这注定会失败,因为他不可能处理所有情况。另一种策略是设置远程主机,让它的表现符合 tramp 预期。这可能是不方便的,因为在使用 tramp 之前需要投入大量精力在 shell 设置上面。

The package, therefore, pursues a combined approach. It tries to figure out some of the more common setups, and only requires you to avoid really exotic stuff. For example, it looks through a list of directories to find some programs on the remote host. And also, it knows that it is not obvious how to check whether a file exists, and therefore it tries different possibilities. (On some hosts and shells, the command test -e does the trick, on some hosts the shell builtin doesn’t work but the program /usr/bin/test -e or /bin/test -e works. And on still other hosts, ls -d is the right way to do this.) 因而,tramp 追求一种结合的方法。它试图找出一些常见的设置,避免接触那些奇怪的功能。例如,它会遍历远程主机上的目录列表来查找程序。它也知道检查一个文件存在方法并不是很显而易见,所以它会尝试不同的可能性。

Below you find a discussion of a few things that TRAMP does not deal with, and that you therefore have to set up correctly.

下面讨论了 tramp 不会处理的一些事情,你必须正确设置这些:

4.16.1 shell-prompt-pattern

After logging in to the remote host, TRAMP has to wait for the remote shell startup to finish before it can send commands to the remote shell. The strategy here is to wait for the shell prompt. In order to recognize the shell prompt, the variable shell-prompt-pattern has to be set correctly to recognize the shell prompt on the remote host.

登录远程主机后,tramp 必须在远程 shell 启动完成后才可以发送命令到远程 shell。这里的策略是等待 shell 提示符。为了识别 sehll 提示符,必须正确设置变量 shell-prompt-pattern 来识别远程主机的 shell 提示符。

Note that TRAMP requires the match for shell-prompt-pattern to be at the end of the buffer. Many people have something like the following as the value for the variable: "^[^>\(][>\)] *". Now suppose your shell prompt is a <b> c $ . In this case, TRAMP recognizes the > character as the end of the prompt, but it is not at the end of the buffer.

注意,tramp 要求 shell-prompt-patter 的匹配应该是在 buffer 末尾。很多人这样设置该变量值:"^[^>\(][>\)] *"。假设 shell 提示符是 a <b> c $。这种情况下,tramp 认为>字符 是提示符的末尾,但他不在缓冲区的末尾。

4.16.2 tramp-shell-prompt-pattern

This regular expression is used by TRAMP in the same way as shell-prompt-pattern, to match prompts from the remote shell. This second variable exists because the prompt from the remote shell might be different from the prompt from a local shell—after all, the whole point of TRAMP is to log in to remote hosts as a different user. The default value of tramp-shell-prompt-pattern is the same as the default value of shell-prompt-pattern, which is reported to work well in many circumstances.

tramp 中这个正则表达式的用法和 shell-prompt-pattern,用来匹配远程 shell。此变量存在的是因远程 shell 可能和本地 shell 不一样。毕竟 tramp 的目的是作为不同的用户登录远程主机。tramp-shell-prompt-pattern 的默认值和 sehll-prompt-pattern 相同,这在很多其情况下工作正常。

4.16.3 tramp-password-prompt-regexp

During login, TRAMP might be forced to enter a password or a passphrase. The difference between both is that a password is requested from the shell on the remote host, while a passphrase is needed for accessing local authentication information, like your ssh key.

登录的时候,tramp 可能被强制要求输入一个 password 或 passphrase。二者的不同是 password 是远程主机 shell 要求的,而 passphrase 是访问本地身份验证信息所需要的,比如 ssh key。

tramp-password-prompt-regexp handles the detection of such requests for English environments. When you use another localization of your (local or remote) host, you might need to adapt this. Example:

tramp-password-prompt-repgexp 在英语环境中可以检测这种请求。当你使用另外一个本地化主机(本地或远程),可能需要调整。例如:

   '("passphrase" "Passphrase"
     ;; English
     "password" "Password"
     ;; Deutsch
     "passwort" "Passwort"
     ;; Français
     "mot de passe" "Mot de passe") t)
  ".*:\0? *"))

In parallel, it might also be necessary to adapt tramp-wrong-passwd-regexp.

同样,可能也有必要调整 tramp-wrong-passwd-regexp。

4.16.4 tset and other questions

Some people invoke the tset program from their shell startup scripts which asks the user about the terminal type of the shell. Maybe some shells ask other questions when they are started. TRAMP does not know how to answer these questions. There are two approaches for dealing with this problem. One approach is to take care that the shell does not ask any questions when invoked from TRAMP. You can do this by checking the TERM environment variable, it will be set to dumb when connecting.

一些人在他们 shell 启动脚本中会调用一些 tset 程序来询问 shell 的终端类型。可能其他 shell 启动的时候询问不同的问题。tramp 并不知道如何回答这些问题。有两种方法来解决这个问题。一种是当从 tramp 调用时让 shell 不要提出这些问题。可以通过检查 TERM 环境变量来做到,当连接的时候该变量会设置为 dumb。

The variable tramp-terminal-type can be used to change this value to dumb.

The other approach is to teach TRAMP about these questions. See the variable tramp-actions-before-shell. Example:

另一种方式是教会 tramp 如何处理这些问题。

(defconst my-tramp-prompt-regexp
  (concat (regexp-opt '("Enter the birth date of your mother:") t)
  "Regular expression matching my login prompt question.")

(defun my-tramp-action (proc vec)
  "Enter \"19000101\" in order to give a correct answer."
    (with-current-buffer (tramp-get-connection-buffer vec)
      (tramp-message vec 6 "\n%s" (buffer-string))
      (tramp-send-string vec "19000101"))))

(add-to-list 'tramp-actions-before-shell
             '(my-tramp-prompt-regexp my-tramp-action))

4.16.5 Environment variables named like users in .profile

If you have a user named frumple and set the variable FRUMPLE in your shell environment, then this might cause trouble. Maybe rename the variable to FRUMPLE_DIR or the like.

如果有一个名为 frumple 的用户,还有一个 FRUMPLE shell 环境变量,这可能会导致问题。可能应该把环境变量重命名为 FRUMPLE_DIR 或者其他类似的什么。

This weird effect was actually reported by a TRAMP user!

这个奇怪的效果是一个 tramp 用户报告的。

4.16.6 Non-Bourne commands in .profile

After logging in to the remote host, TRAMP issues the command exec bin/sh. (Actually, the command is slightly different.) When /bin/sh is executed, it reads some init files, such as ~.shrc or ~/.profile.

登录远程主机后,tramp 会执行命令 bin/sh。(实际上,执行的命令可能有稍微的不同。)当/bin/sh 执行时,它会读取一些初始化文件,比如 ~.shrc 或 ~/.profile。

Now, some people have a login shell which is not bin/sh but a Bourne-ish shell such as bash or ksh. Some of these people might put their shell setup into the files ~.shrc or ~/.profile. This way, it is possible for non-Bourne constructs to end up in those files. Then, exec /bin/sh might cause the Bourne shell to barf on those constructs.

现在有一有用户的的登录 shell 不是/bin/sh,而是 Bouorne-ish shell 比如 bash 或者 ksh。这些人可能会把他们 shell 的设置放在~/.shrc 或 ~/.profile 中。这样就有可能导致 non-Bourne 的 shell 在这些文件中提早结束。

As an example, imagine somebody putting export FOO=bar into the file ~/.profile. The standard Bourne shell does not understand this syntax and will emit a syntax error when it reaches this line.

比方说,设想有人把 export FOO=bar 写在~/.profile 当中。标注的 Bourne shell 是不能理解这种文法的,当他读到这一行的时候就会发生语法错误。

Another example is the tilde (~) character, say when adding ~/bin to PATH. Many Bourne shells will not expand this character, and since there is usually no directory whose name consists of the single character tilde, strange things will happen.

另一个例子是波浪字符,当将~/bin 添加到 PATH,很多 Bourne shell 不会扩展该字符,因为通常没有哪个目录的名字会包含单个波浪字符,这样奇怪的事情就会发生。

What can you do about this?


Well, one possibility is to make sure that everything in ~/.shrc and ~/.profile on all remote hosts is Bourne-compatible. In the above example, instead of export FOO=bar, you might use FOO=bar; export FOO instead.

恩,一个可能解决办法是保证远程主机上的~/.shrc 和~/.profile 是兼容 Bourne。上面的例子中,应该使用 FOO=bar 而不是 export FOO=bar 来导出 FOO。

The other possibility is to put your non-Bourne shell setup into some other files. For example, bash reads the file ~/.bash_profile instead of ~/.profile, if the former exists. So bash aficionados just rename their ~/.profile to ~/.bash_profile on all remote hosts, and Bob’s your uncle.

另外一个可能是把你 non-Bourne shell 设置放到其他文件中。比如说,如果~/.bash_profile 存在的的话 bash 就不会读取~/.profile 文件。所以 bash 爱好者只需要将所有远程主机上的~/.profile 更名为~/.bash_profile 就好了。

The TRAMP developers would like to circumvent this problem, so if you have an idea about it, please tell us. However, we are afraid it is not that simple: before saying exec /bin/sh, TRAMP does not know which kind of shell it might be talking to. It could be a Bourne-ish shell like ksh or bash, or it could be a csh derivative like tcsh, or it could be zsh, or even rc. If the shell is Bourne-ish already, then it might be prudent to omit the exec /bin/sh step. But how to find out if the shell is Bourne-ish?

tramp 的开发者可能想绕开这个问题,所以如果关于这个有什么方法请告诉我们。然而,我们觉得可能没有那么简单,之前也说了执行/bin/sh,tramp 并不知道会和哪种 shell 进行交流,可能是类像 ksh 或者 bashe 的 Bourne-ish shell,也可能是 csh 的后继比如说 tcsh,或者可能是 zsh,甚至是 rc。如果 shell 已经是 Bourne-ish,那么可能会谨慎的忽略执行/bin/sh 的步骤。但是如何知道 shell 是 Bourne-ish 的呢?

4.16.7 Interactive shell prompt

TRAMP redefines the shell prompt in order to parse the shell’s output robustly. When calling an interactive shell by M-x shell, this doesn’t look nice.

tramp 重新定义了 shell 提示符用来分析 shell 的输出。当通过 M-x shell 调用一个交互式的 shell,这可能看起来并不漂亮。

You can redefine the shell prompt by checking the environment variable INSIDE_EMACS, which is set by TRAMP, in your startup script ~/.emacs_SHELLNAME. SHELLNAME might be the string bash or similar, in case of doubt you could set it the environment variable ESHELL in your .emacs:

可以通过坏境变量 INSIDE_EMACS 重新定义 shell 提示符,tramp 会在你的设置脚本~/.emacs_SHELLNAME 中设置该变量,如果有疑问你可以在.emacs 当中设置 ESHELL 环境变量。

(setenv "ESHELL" "bash")

Your file ~/.emacs_SHELLNAME could contain code like

# Reset the prompt for remote Tramp shells.
if [ "${INSIDE_EMACS/*tramp*/tramp}" == "tramp" ] ; then
    PS1="[\u@\h \w]$ "

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:

 `(,(regexp-quote "") "remote-copy-args" (("-l") ("%r"))))

with ‘’ 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 "") "remote-shell" "sh"))

with ‘’ 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:, 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
   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.

通常,Emacs 会在原文件所在目录写入备份文件,但是这个行为可以通过变量 backup-directory-alist 改变。使用 tramp 进行连接,这可能有意想不到的副作用。假设你指定所有的备份都应该存在~/.emacs.d/backups/,然后编辑/su:root@localhost:/etc/secretfile。副作用是备份文件的拥有者将会是你而不是 root,因而有可能别的不应该看到这些文件的人也可能会看到它。

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

当 back-directory-alist 为 nil(默认值),不会出现这问题。

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:

因而,有必要对 tramp 文件设置特殊值。

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

也可以更具使用的 method 关闭备份:

(setq backup-enable-predicate
      (lambda (name)
        (and (normal-backup-enable-predicate name)
              (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.


(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

This section needs a lot of work! Please help.

The recent Cygwin installation of ssh works only with a Cygwinized Emacs. You can check it by typing M-x eshell, and starting ssh 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

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.

安装 tramp 之后就能透明的操作登陆了的远程主机上的文件了,就和操作本地文件一样。

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.

通过形式化的语法像 tramp 指定了要访问的文件,这种语法指明了要连接的系统的信息,类似于 ange-ftp 使用的语法。

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!

有时候 emacs 会记录所有按键,这可能是让你惊喜的,所以如果你看到 emacs 显示一个密码提示,然后按了两次回车而不是一次,tramp 干完自己的事情后会处理第二次回车。你可能会问,为什么会这样,这是一个正常的输入。你是对的,但是你要认识到打开一个远程文件可能需要一段时间,可能开个连接需要半分钟,半分钟之后可能你已经忘了你已经按了啥键了。

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.

一些 tramp 文件名举例如下:


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


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


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


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.


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

host can also be an IPv4 or IPv6 address, like in / 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.

除非指定了使用另一名字,tramp 会使用当前用户名作为远程登录的用户名。如果需要不同的登陆了用户名,可以在文件名部分进行指定。

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.

通过 /user@hoot:path/to.file 来用指定用户名进行登录。举例说如果要作为 daniel 登录 melancholia 来修改 home 目录中的 .emacs 文件需要指定 /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.

也可以在 tramp 文件名中指定传输方法。

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

远程文件名的当中只包含主机名,而这个主机名和方法名是相同,这样做是不允许的。如果使用这样的主机名,那么必须显示指定连接方法,比如 /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.

和 tramp 一起工作的文件名补全功能可以补全方法名字、用户名、主机名以及远程主机上的文件名。使用该国更需要在 .emacs 文件中激活。 If you, for example, type C-x C-f /t TAB, TRAMP might give you as result the choice for


‘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


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.

如果 tramp 进行补全分析的配置文件提供了用户名,这些用户名也会被考虑。

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.

补全了远程主机,下一步就是远程主机上的文件名。 Example:

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

远程目录可能会在 emacs 控制之外改变它的内容。例如其他进程创建或者删除文件。因为,在文件补全过程中,会频繁读取远程目录来侦测这种改变,这原本是不可见的。

5.2.1 User Option: tramp-completion-reread-directory-timeout

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.

该变量定义了自从上次多少秒之后开始重新读取文件内容。0 表示文件名补全过程中立即读取,nil 表示总是使用目录缓存的数值。

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.

通过 tramp-default-proxies-alist 配置多 hops。但是,有些时候需要不改变配置立即访问远程主机。可以通过代理的 ad-hoc 规范做到。

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

代理看起来像一个没有本地文件名字的远程文件名字规范。他的目标是远程文件名字,,使用|进行分割。例如,通过代理 bired@bastion 访问 you@remotehost 上面的远程文件应该这样打开:

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.

多个 hops 可以是串联式的,使用“|”分割多个代理了。代理了可以包含%h 或%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.

ad-hoc 定义会动态添加到 tramp-default-proxies-alist。因此,emacs 会话的生命期中都没必要再次输入 ad-hoc 定义。远程文件名已经足够了。

5.3.1 User Option: tramp-save-ad-hoc-proxies

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 "/")) (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.

Adding an entry can be performed via add-to-list:

(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 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/, 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.

Author: lsl

Created: 2016-08-07 Sun 19:30