@end macro
@copying
-Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
-2008, 2009, 2010, 2011 Free Software Foundation, Inc.
+Copyright @copyright{} 1999-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end ifset
@ifhtml
-@ifset jamanual
-This manual is also available as a @uref{@value{japanesemanual},
-Japanese translation}.
-@end ifset
-
The latest release of @value{tramp} is available for
@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
@ref{Obtaining Tramp} for more details, including the CVS server
* Installation parameters:: Parameters in order to control installation.
* Load paths:: How to plug-in @value{tramp} into your environment.
-* Japanese manual:: Japanese manual.
@end ifset
@ifset emacsgvfs
GVFS integration started in February 2009.
@end ifset
-@ifset emacsimap
-Storing files into IMAP mailboxes has been added in September 2009.
-@end ifset
In December 2001, @value{tramp} has been added to the XEmacs package
repository. Being part of the Emacs repository happened in June 2002,
@file{~/.ssh/config}, the SSH configuration file, which protocol
should be used, and use the regular @option{ssh} method.)
-Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
-@command{ssh1} and @command{ssh2} commands explicitly. If you don't
-know what these are, you do not need these options.
-
All the methods based on @command{ssh} have an additional feature: you
can specify a host name which looks like @file{host#42} (the real host
name, then a hash sign, then a port number). This means to connect to
@command{krlogin -x} command to log in to the remote host.
+@item @option{ksu}
+@cindex method ksu
+@cindex ksu method
+@cindex Kerberos (with ksu method)
+
+This is another method from the Kerberos suite. It behaves like @option{su}.
+
+
@item @option{plink}
@cindex method plink
@cindex plink method
hasn't defined a user name. Different port numbers must be defined in
the session.
-
-@item @option{fish}
-@cindex method fish
-@cindex fish method
-
-This is an experimental implementation of the fish protocol, known from
-the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
-the fish server implementation from the KDE kioslave. That means, the
-file @file{~/.fishsrv.pl} is expected to reside on the remote host.
-
-The implementation lacks good performance. The code is offered anyway,
-maybe somebody can improve the performance.
-
@end table
@file{~/.ssh/config}, the SSH configuration file, which protocol
should be used, and use the regular @option{scp} method.)
-Two other variants, @option{scp1_old} and @option{scp2_old}, use the
-@command{ssh1} and @command{ssh2} commands explicitly. If you don't
-know what these are, you do not need these options.
-
All the @command{ssh} based methods support the @samp{-p} feature
where you can specify a port number to connect to in the host name.
For example, the host name @file{host#42} tells @value{tramp} to
@cindex method ftp
@cindex ftp method
-This is not a native @value{tramp} method. Instead of, it forwards all
+This is not a native @value{tramp} method. Instead, it forwards all
requests to @value{ftppackagename}.
@ifset xemacs
This works only for unified filenames, see @ref{Issues}.
@command{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 towards MS Windows NT, MS Windows 2000, and MS
+far, it is tested against MS Windows NT, MS Windows 2000, and MS
Windows XP.
The first directory in the localname must be a share name on the remote
-host. Remember, that the @code{$} character in which default shares
+host. Remember that the @code{$} character, in which default shares
usually end, must be written @code{$$} due to environment variable
substitution in file names. If no share name is given (i.e. remote
directory @code{/}), all available shares are listed.
-Since authorization is done on share level, you will be prompted
-always for a password if you access another share on the same host.
+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 @ref{Password handling}.
-MS Windows uses for authorization both a user name and a domain name.
+For authorization, MS Windows uses both a user name and a domain name.
Because of this, the @value{tramp} syntax has been extended: you can
specify a user name which looks like @code{user%domain} (the real user
name, then a percent sign, then the domain name). So, to connect to
The @option{smb} method supports the @samp{-p} argument.
@strong{Please note:} If @value{emacsname} runs locally under MS
-Windows, this method isn't available. Instead of, you can use UNC
+Windows, this method isn't available. Instead, you can use UNC
file names like @file{//melancholia/daniel$$/.emacs}. The only
disadvantage is that there's no possibility to specify another user
name.
-
-
-@ifset emacsimap
-@item @option{imap}
-@cindex method imap
-@cindex method imaps
-@cindex imap method
-@cindex imaps method
-
-Accessing an IMAP mailbox is intended to save files there as encrypted
-message. It could be used in case there are no other remote file
-storages available.
-
-@value{tramp} supports both @option{imap} and @option{imaps} methods.
-The latter one accesses the IMAP server over ssl.
-
-Both methods support the port number specification.
-
-Note, that special handling is needed for declaring a passphrase for
-encryption / decryption of the messages (@pxref{Using an
-authentication file}).
-
-@end ifset
@end table
The connection methods described in this section are based on GVFS
@uref{http://en.wikipedia.org/wiki/GVFS}. Via GVFS, the remote
filesystem is mounted locally through FUSE. @value{tramp} uses
-internally this local mounted directory.
+this local mounted directory internally.
The communication with GVFS is implemented via D-Bus messages.
Therefore, your @value{emacsname} must have D-Bus integration,
@cindex obex method
OBEX is an FTP-like access protocol for simple devices, like cell
-phones. Until now @value{tramp} supports only OBEX over Bluetooth.
+phones. For the time being, @value{tramp} only supports OBEX over Bluetooth.
@item @option{synce}
The @option{synce} method allows communication with Windows Mobile
devices. Beside GVFS for mounting remote files and directories via
-FUSE, it needs also the SYNCE-GVFS plugin.
+FUSE, it also needs the SYNCE-GVFS plugin.
@end table
@defopt tramp-gvfs-methods
-This customer option, a list, defines the external methods, which
+This customer option, a list, defines the external methods which
shall be used with GVFS. Per default, these are @option{dav},
@option{davs}, @option{obex} and @option{synce}. Other possible
values are @option{ftp}, @option{sftp} and @option{smb}.
Therefore, they can be used for proxy host declarations
(@pxref{Multi-hops}) only.
-A gateway method must come always along with a method who supports
+A gateway method must always come along with a method which supports
port setting. This is because @value{tramp} targets the accompanied
method to @file{localhost#random_port}, from where the firewall or
-proxy server is accessed to.
+proxy server is accessed.
Gateway methods support user name and password declarations. These
are used to authenticate towards the corresponding firewall or proxy
@pxref{External methods}), to match only this method. When you omit
the port, you match all @value{tramp} methods.
-@ifset emacsimap
-A special case are @option{imap}-like methods. Authentication with
-the IMAP server is performed via @file{imap.el}, there is no special
-need from @value{tramp} point of view. An additional passphrase, used
-for symmetric encryption and decryption of the stored messages, should
-be given with the special port indication @option{tramp-imap}:
-
-@example
-machine melancholia port tramp-imap login daniel password ultrageheim
-@end example
-@end ifset
-
@anchor{Caching passwords}
@subsection Caching passwords
When @value{tramp} detects a changed operating system version on a
remote host (via the command @command{uname -sr}), it flushes all
connection related information for this host, and opens the
-connection, again.
+connection again.
@node Remote Programs
@end lisp
Another possibility is to reuse the path settings of your remote
-account, when you log in. Usually, these settings are overwritten,
+account when you log in. Usually, these settings are overwritten,
because they might not be useful for @value{tramp}. The place holder
@code{tramp-own-remote-path} preserves these settings. You can
activate it via
this line.
Another example is the tilde (@code{~}) character, say when adding
-@file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this
+@file{~/bin} to @code{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.
@command{exec /bin/sh} step. But how to find out if the shell is
Bourne-ish?
+
+@item Interactive shell prompt
+
+@value{tramp} redefines the shell prompt in order to parse the shell's
+output robustly. When calling an interactive shell by @kbd{M-x
+shell}, this doesn't look nice.
+
+You can redefine the shell prompt by checking the environment variable
+@code{INSIDE_EMACS}, which is set by @value{tramp}, in your startup
+script @file{~/.emacs_SHELLNAME}. @code{SHELLNAME} might be the string
+@code{bash} or similar, in case of doubt you could set it the
+environment variable @code{ESHELL} in your @file{.emacs}:
+
+@lisp
+(setenv "ESHELL" "bash")
+@end lisp
+
+Your file @file{~/.emacs_SHELLNAME} could contain code like
+
+@example
+# Reset the prompt for remote Tramp shells.
+if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then
+ PS1="[\u@@\h \w]$ "
+fi
+@end example
+
+@ifinfo
+@ifset emacs
+@xref{Interactive Shell, , , @value{emacsdir}}.
+@end ifset
+@end ifinfo
+
@end table
@value{tramp} uses for analysis of completion, offer user names, those user
names will be taken into account as well.
-Remote machines, which have been visited in the past and kept
-persistently (@pxref{Connection caching}), will be offered too.
+Remote machines which have been visited in the past and kept
+persistently (@pxref{Connection caching}) will be offered too.
Once the remote machine identification is completed, it comes to
filename completion on the remote host. This works pretty much like
A remote directory might have changed its contents out of
@value{emacsname} control, for example by creation or deletion of
-files by other processes. Therefore, during filename completion the
-remote directory contents is reread regularly in order to detect such
+files by other processes. Therefore, during filename completion, the
+remote directory contents are reread regularly in order to detect such
changes, which would be invisible otherwise (@pxref{Connection caching}).
@defopt tramp-completion-reread-directory-timeout
@option{smb} methods. Association of a pty, as specified in
@code{start-file-process}, is not supported.
+@code{process-file} and @code{start-file-process} work on the remote
+host when the variable @code{default-directory} is remote:
+
+@lisp
+(let ((default-directory "/ssh:remote.host:"))
+ (start-file-process "grep" (get-buffer-create "*grep*")
+ "/bin/sh" "-c" "grep -e tramp *"))
+@end lisp
+
@ifset emacsgvfs
If the remote host is mounted via GVFS (see @ref{GVFS based methods}),
the remote filesystem is mounted locally. Therefore, there are no
Changing or removing an existing entry is not encouraged. The default
values are chosen for proper @value{tramp} work. Nevertheless, if for
example a paranoid system administrator disallows changing the
-@var{$HISTORY} environment variable, you can customize
+@code{HISTORY} environment variable, you can customize
@code{tramp-remote-process-environment}, or you can apply the
following code in your @file{.emacs}:
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
-@var{$DISPLAY} environment variable on the remote host:
+@code{DISPLAY} environment variable on the remote host:
@lisp
(add-to-list 'tramp-remote-process-environment
21 (starting with 21.4), and SXEmacs 22.
The package was intended to work on Unix, and it really expects a
-Unix-like system on the remote end (except the @option{smb} and
-@option{imap} methods), but some people seemed to have some success
-getting it to work on MS Windows XP/Vista/7 @value{emacsname}.
+Unix-like system on the remote end (except the @option{smb} method),
+but some people seemed to have some success getting it to work on MS
+Windows XP/Vista/7 @value{emacsname}.
@item
Use caching. This is already enabled by default. Information about
the remote host as well as the remote files are cached for reuse. The
information about remote hosts is kept in the file specified in
-@code{tramp-persistency-file-name}. Keep this file.
+@code{tramp-persistency-file-name}. Keep this file. If you are
+confident that files on remote hosts are not changed out of
+@value{emacsname}' control, set @code{remote-file-name-inhibit-cache}
+to @code{nil}.
Disable version control. If you access remote files which are not
under version control, a lot of check operations can be avoided by
Unknown characters in the prompt
@value{tramp} needs to recognize the prompt on the remote machine
-after execution any command. This is not possible, when the prompt
+after execution any command. This is not possible when the prompt
contains unknown characters like escape sequences for coloring. This
should be avoided on the remote side. @xref{Remote shell setup}. for
setting the regular expression detecting the prompt.
When your network connection is down, @command{ssh} sessions might
hang. @value{tramp} cannot detect it safely, because it still sees a
running @command{ssh} process. Timeouts cannot be used as well,
-because it cannot be predicted, how long a remote command will last,
+because it cannot be predicted how long a remote command will last,
for example when copying very large files.
Therefore, you must configure the @command{ssh} process to die
The file name left to type would be
@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
-Note, that there are some useful settings already. Accessing your
+Note that there are some useful settings already. Accessing your
local host as @samp{root} user, is possible just by @kbd{C-x C-f
@trampfn{su, , ,}}.
@end lisp
Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you
-are. The disadvantage is, that you cannot edit the file name, because
+are. The disadvantage is that you cannot edit the file name, because
environment variables are not expanded during editing in the
minibuffer.
Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}.
Because BBDB is not prepared for @value{tramp} syntax, you must
-specify a method together with the user name, when needed. Example:
+specify a method together with the user name when needed. Example:
@example
@kbd{M-x bbdb-create-ftp-site @key{RET}}
@end enumerate
-I would like to thank all @value{tramp} users, who have contributed to
+I would like to thank all @value{tramp} users who have contributed to
the different recipes!
(server-start)
@end lisp
-Make sure, that the result of @code{(system-name)} can be resolved on
+Make sure that the result of @code{(system-name)} can be resolved on
your local host; otherwise you might use a hard coded IP address.
The resulting file @file{~/.emacs.d/server/server} must be copied to
it has seen so far.
This is a performance degradation, because the lost file attributes
-must be recomputed, when needed again. In cases the caller of
+must be recomputed when needed again. In cases the caller of
@code{process-file} knows that there are no file attribute changes, it
shall let-bind the variable @code{process-file-side-effects} to
@code{nil}. @value{tramp} wouldn't flush the file attributes cache then.
@c * Use `filename' resp. `file name' consistently.
@c * Use `host' resp. `machine' consistently.
@c * Consistent small or capitalized words especially in menues.
-
-@ignore
- arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808
-@end ignore