@c Entries for @command{install-info} to use
@dircategory Emacs network features
@direntry
-* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
+* @value{tramp}: (tramp). Transparent Remote Access, Multiple Protocol
Emacs remote file access via ssh and scp.
@end direntry
@ifhtml
The latest release of @value{tramp} is available for
@uref{https://ftp.gnu.org/gnu/tramp/, download}, or you may see
-@ref{Obtaining Tramp} for more details, including the Git server
-details.
+@ref{Obtaining @value{tramp}} for more details, including the Git
+server details.
@value{tramp} also has a @uref{https://savannah.gnu.org/projects/tramp/,
Savannah Project Page}.
For the end user:
-* Obtaining Tramp:: How to obtain @value{tramp}.
+* Obtaining @value{tramp}:: How to obtain @value{tramp}.
* History:: History of @value{tramp}.
@ifset installchapter
* Installation:: Installing @value{tramp} with your Emacs.
@end ifset
+* Quick Start Guide:: Short introduction how to use @value{tramp}.
* Configuration:: Configuring @value{tramp} for use.
* Usage:: An overview of the operation of @value{tramp}.
* Bug Reports:: Reporting Bugs and Problems.
more secure alternative to @command{ftp} and other older access
methods.
-@value{tramp} on Windows operating systems is integrated with the
+@value{tramp} on MS Windows operating systems is integrated with the
PuTTY package, and uses the @command{plink} program.
@value{tramp} mostly operates transparently in the background using
@value{tramp} can transfer files using any number of available host
programs for remote files, such as @command{rcp}, @command{scp},
-@command{rsync} or (under Windows) @command{pscp}. @value{tramp}
+@command{rsync} or (under MS Windows) @command{pscp}. @value{tramp}
provides easy ways to specify these programs and customize them to
specific files, hosts, or access methods.
@c For the end user
-@node Obtaining Tramp
+@node Obtaining @value{tramp}
@chapter Obtaining @value{tramp}
-@cindex obtaining Tramp
+@cindex obtaining @value{tramp}
@value{tramp} is included as part of Emacs (since Emacs version 22.1).
@end example
@noindent
-Tramp developers:
+@value{tramp} developers:
@example
] @strong{git clone login@@git.sv.gnu.org:/srv/git/tramp.git}
2004, proxy hosts replaced multi-hop methods. Running commands on
remote hosts was introduced in December 2005. Support for gateways
since April 2007 (and removed in December 2016). GVFS integration
-started in February 2009. Remote commands on Windows hosts since
+started in February 2009. Remote commands on MS Windows hosts since
September 2011. Ad-hoc multi-hop methods (with a changed syntax)
re-enabled in November 2011. In November 2012, added Juergen
Hoetzel's @file{tramp-adb.el}.
@end ifset
+@node Quick Start Guide
+@chapter Short introduction how to use @value{tramp}
+@cindex quick start guide
+
+@value{tramp} extends the Emacs file name syntax by a remote
+component. A remote file name looks always like
+@file{@trampfn{method,user@@host,/path/to/file}}.
+
+You can use remote files exactly like ordinary files, that means you
+could open a file or directory by @kbd{C-x C-f
+@trampfn{method,user@@host,/path/to/file} @key{RET}}, edit the file,
+and save it. You can also mix local files and remote files in file
+operations with two arguments, like @code{copy-file} or
+@code{rename-file}. And finally, you can run even processes on a
+remote host, when the buffer you call the process from has a remote
+@code{default-directory}.
+
+
+@anchor{Quick Start Guide: File name syntax}
+@section File name syntax
+@cindex file name syntax
+
+Remote file names are prepended by the @code{method}, @code{user} and
+@code{host} parts. All of them, and also the local file name part,
+are optional, in case of a missing part a default value is assumed.
+The default value for an empty local file name part is the remote
+user's home directory. The shortest remote file name is
+@file{@trampfn{-,,}}, therefore. The @samp{-} notation for the
+default host is used for syntactical reasons, @ref{Default Host}.
+
+The @code{method} part describes the connection method used to reach
+the remote host, see below.
+
+The @code{user} part is the user name for accessing the remote host.
+For the @option{smb} method, this could also require a domain name, in
+this case it is written as @code{user%domain}.
+
+The @code{host} part must be a host name which could be resolved on
+your local host. It could be a short host name, a fully qualified
+domain name, an IPv4 or IPv6 address, @ref{File name syntax}. Some
+connection methods support also a notation of the port to be used, in
+this case it is written as @code{host#port}.
+
+
+@anchor{Quick Start Guide: @option{ssh} and @option{plink} methods}
+@section Using @option{ssh} and @option{plink}
+@cindex method ssh
+@cindex ssh method
+@cindex method plink
+@cindex plink method
+
+If your local host runs an SSH client, and the remote host runs an SSH
+server, the most simple remote file name is
+@file{@trampfn{ssh,user@@host,/path/to/file}}. The remote file name
+@file{@trampfn{ssh,,}} opens a remote connection to yourself on the
+local host, and is taken often for testing @value{tramp}.
+
+On MS Windows, PuTTY is often used as SSH client. Its @command{plink}
+method can be used there to open a connection to a remote host running
+an @command{ssh} server:
+@file{@trampfn{plink,user@@host,/path/to/file}}.
+
+
+@anchor{Quick Start Guide: @option{su}, @option{sudo} and @option{sg} methods}
+@section Using @option{su}, @option{sudo} and @option{sg}
+@cindex method su
+@cindex su method
+@cindex method sudo
+@cindex sudo method
+@cindex method sg
+@cindex sg method
+
+Sometimes, it is necessary to work on your local host under different
+permissions. For this, you could use the @option{su} or @option{sudo}
+connection method. Both methods use @samp{root} as default user name
+and the return value of @code{(system-name)} as default host name.
+Therefore, it is convenient to open a file as
+@file{@trampfn{sudo,,/path/to/file}}.
+
+The method @option{sg} stands for ``switch group''; the changed group
+must be used here as user name. The default host name is the same.
+
+
+@anchor{Quick Start Guide: @option{smb} method}
+@section Using @command{smbclient}
+@cindex method smb
+@cindex smb method
+@cindex ms windows (with smb method)
+@cindex smbclient
+
+In order to access a remote MS Windows host or Samba server, the
+@command{smbclient} client is used. The remote file name syntax is
+@file{@trampfn{smb,user%domain@@host,/path/to/file}}. The first part
+of the local file name is the share exported by the remote host,
+@samp{path} in this example.
+
+
+@anchor{Quick Start Guide: GVFS-based methods}
+@section Using GVFS-based methods
+@cindex methods, gvfs
+@cindex gvfs based methods
+@cindex method sftp
+@cindex sftp method
+@cindex method afp
+@cindex afp method
+@cindex method dav
+@cindex method davs
+@cindex dav method
+@cindex davs method
+
+On systems, which have installed the virtual file system for the Gnome
+Desktop (GVFS), its offered methods could be used by @value{tramp}.
+Examples are @file{@trampfn{sftp,user@@host,/path/to/file}},
+@file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP
+file system), @file{@trampfn{dav,user@@host,/path/to/file}} and
+@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares).
+
+
+@anchor{Quick Start Guide: Google Drive}
+@section Using Google Drive
+@cindex method gdrive
+@cindex gdrive method
+@cindex google drive
+
+Another GVFS-based method allows to access a Google Drive file system.
+The file name syntax is here always
+@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}.
+@samp{john.doe@@gmail.com} stands here for your Google Drive account.
+
+
+@anchor{Quick Start Guide: Android}
+@section Using Android
+@cindex method adb
+@cindex adb method
+@cindex android
+
+An Android device, which is connected via USB to your local host, can
+be accessed via the @command{adb} command. No user or host name is
+needed. The file name syntax is @file{@trampfn{adb,,/path/to/file}}.
+
+
@node Configuration
@chapter Configuring @value{tramp}
@cindex configuration
Connections will have to be setup where logins can proceed without
such questions.
-@option{sshx} is useful for Windows users when @command{ssh} triggers
-an error about allocating a pseudo tty. This happens due to missing
-shell prompts that confuses @value{tramp}.
+@option{sshx} is useful for MS Windows users when @command{ssh}
+triggers an error about allocating a pseudo tty. This happens due to
+missing shell prompts that confuses @value{tramp}.
@option{sshx} supports the @samp{-p} argument.
@item @option{krlogin}
@cindex method krlogin
@cindex krlogin method
-@cindex Kerberos (with krlogin method)
+@cindex kerberos (with krlogin method)
This method is also similar to @option{ssh}. It uses the
@command{krlogin -x} command only for remote host login.
@item @option{ksu}
@cindex method ksu
@cindex ksu method
-@cindex Kerberos (with ksu method)
+@cindex kerberos (with ksu method)
This is another method from the Kerberos suite. It behaves like @option{su}.
@cindex method plink
@cindex plink method
-@option{plink} method is for Windows users with the PuTTY
+@option{plink} method is for MS Windows users with the PuTTY
implementation of SSH@. It uses @samp{plink -ssh} to log in to the
remote host.
@cindex method plinkx
@cindex plinkx method
-Another method using PuTTY on Windows with session names instead of
-host names. @option{plinkx} calls @samp{plink -load @var{session} -t}.
-User names and port numbers must be defined in the session.
+Another method using PuTTY on MS Windows with session names instead of
+host names. @option{plinkx} calls @samp{plink -load @var{session}
+-t}. User names and port numbers must be defined in the session.
Check the @samp{Share SSH connections if possible} control for that
session.
in performance to @option{scp}. @option{scpx} uses @samp{ssh -t -t
@var{host} -l @var{user} /bin/sh} to open a connection.
-@option{scpx} is useful for Windows users when @command{ssh} triggers
-an error about allocating a pseudo tty. This happens due to missing
-shell prompts that confuses @value{tramp}.
+@option{scpx} is useful for MS Windows users when @command{ssh}
+triggers an error about allocating a pseudo tty. This happens due to
+missing shell prompts that confuses @value{tramp}.
This method supports the @samp{-p} argument.
@cindex pscp method
@cindex pscp (with pscp method)
@cindex plink (with pscp method)
-@cindex PuTTY (with pscp method)
+@cindex putty (with pscp method)
@cindex method psftp
@cindex psftp method
@cindex pscp (with psftp method)
@cindex plink (with psftp method)
-@cindex PuTTY (with psftp method)
+@cindex putty (with psftp method)
These methods are similar to @option{scp} or @option{sftp}, but they
use the @command{plink} command to connect to the remote host, and
they use @command{pscp} or @command{psftp} for transferring the files.
-These programs are part of PuTTY, an SSH implementation for Windows.
+These programs are part of PuTTY, an SSH implementation for MS Windows.
Check the @samp{Share SSH connections if possible} control for that
session.
@item @option{smb}
@cindex method smb
@cindex smb method
+@cindex ms windows (with smb method)
+@cindex smbclient
This non-native @value{tramp} method connects via the Server Message
Block (SMB) networking protocol to hosts running file servers that are
To accommodate user name/domain name syntax required by MS Windows
authorization, @value{tramp} provides for an extended syntax in
-@code{user%domain} format (where user is user name, @code{%} is the
-percent symbol, and domain is the windows domain name). An example:
+@code{user%domain} format (where @code{user} is the user name,
+@code{%} is the percent symbol, and @code{domain} is the MS Windows
+domain name). An example:
@example
@trampfn{smb,daniel%BIZARRE@@melancholia,/daniel$$/.emacs}
@end example
where user @code{daniel} connects as a domain user to the SMB host
-@code{melancholia} in the windows domain @code{BIZARRE} to edit
+@code{melancholia} in the MS Windows domain @code{BIZARRE} to edit
@file{.emacs} located in the home directory (share @code{daniel$}).
Alternatively, for local WINS users (as opposed to domain users),
@item @option{adb}
@cindex method adb
@cindex adb method
+@cindex android (with adb method)
This method uses Android Debug Bridge program for accessing Android
devices. The Android Debug Bridge must be installed locally for
@item @option{gdrive}
@cindex method gdrive
@cindex gdrive method
-@cindex Google Drive
+@cindex google drive
Via the @option{gdrive} method it is possible to access your Google
Drive online storage. User and host name of the remote file name are
@cindex method synce
@cindex synce method
-@option{synce} method allows connecting to Windows Mobile devices. It
-uses GVFS for mounting remote files and directories via FUSE and
+@option{synce} method allows connecting to MS Windows Mobile devices.
+It uses GVFS for mounting remote files and directories via FUSE and
requires the SYNCE-GVFS plugin.
@end table
@end example
If @option{ssh} is unavailable for whatever reason, look for other
-obvious options. For Windows, try the @option{plink} method. For
+obvious options. For MS Windows, try the @option{plink} method. For
Kerberos, try @option{krlogin}.
For editing local files as @option{su} or @option{sudo} methods, try
@node Firewalls
@section Passing firewalls
-@cindex HTTP tunnel
-@cindex proxy hosts, HTTP tunnel
+@cindex http tunnel
+@cindex proxy hosts, http tunnel
Sometimes, it is not possible to reach a remote host directly. A
firewall might be in the way, which could be passed via a proxy
prompts, for which @value{tramp} uses @option{tramp-wrong-passwd-regexp}.
@item @command{tset} and other questions
-@cindex Unix command tset
-@cindex tset Unix command
+@cindex unix command tset
+@cindex tset unix command
@vindex tramp-terminal-type
To suppress inappropriate prompts for terminal type, @value{tramp}
@example
@group
-# Reset the prompt for remote Tramp shells.
+# Reset the prompt for remote @value{tramp} shells.
if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then
PS1="[\u@@\h \w]$ "
fi
@end ifinfo
@item @command{busybox} / @command{nc}
-@cindex Unix command nc
-@cindex nc Unix command
+@cindex unix command nc
+@cindex nc unix command
@value{tramp}'s @option{nc} method uses the @command{nc} command to
install and execute a listener as follows (see @code{tramp-methods}):
@node Android shell setup
@section Android shell setup hints
-@cindex android shell setup
+@cindex android shell setup for ssh
@value{tramp} uses the @option{adb} method to access Android devices.
Android devices provide a restricted shell access through an USB
@node Windows setup hints
@section Issues with Cygwin ssh
-@cindex Cygwin, issues
+@cindex cygwin, issues
This section is incomplete. Please share your solutions.
-@cindex method sshx with Cygwin
-@cindex sshx method with Cygwin
+@cindex method sshx with cygwin
+@cindex sshx method with cygwin
Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To
check for compatibility: type @kbd{M-x eshell}, and start @kbd{ssh
@option{sshx} access method. Consult Cygwin's FAQ at
@uref{https://cygwin.com/faq/} for details.
-@cindex Cygwin and fakecygpty
-@cindex fakecygpty and Cygwin
+@cindex cygwin and fakecygpty
+@cindex fakecygpty and cygwin
On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs
Wiki} it is explained how to use the helper program @code{fakecygpty}
to fix this problem.
-@cindex method scpx with Cygwin
-@cindex scpx method with Cygwin
+@cindex method scpx with cygwin
+@cindex scpx method with cygwin
When using the @option{scpx} access method, Emacs may call
-@command{scp} with Windows file naming, such as @code{c:/foo}. But
+@command{scp} with MS Windows file naming, such as @code{c:/foo}. But
the version of @command{scp} that is installed with Cygwin does not
-know about Windows file naming, which causes it to incorrectly look
+know about MS Windows file naming, which causes it to incorrectly look
for a host named @code{c}.
A workaround: write a wrapper script for @option{scp} to convert
Windows file names to Cygwin file names.
-@cindex Cygwin and ssh-agent
-@cindex SSH_AUTH_SOCK and Emacs on Windows
+@cindex cygwin and ssh-agent
+@cindex SSH_AUTH_SOCK and emacs on ms windows
-When using the @command{ssh-agent} on Windows for password-less
+When using the @command{ssh-agent} on MS Windows for password-less
interaction, @option{ssh} methods depend on the environment variable
@env{SSH_AUTH_SOCK}. But this variable is not set when Emacs is
started from a Desktop shortcut and authentication fails.
-One workaround is to use a Windows based SSH Agent, such as
+One workaround is to use an MS Windows based SSH Agent, such as
Pageant. It is part of the Putty Suite of tools.
The fallback is to start Emacs from a shell.
relative or absolute paths, but not remote paths.
-@subsection Running remote processes on Windows hosts
+@subsection Running remote processes on MS Windows hosts
@cindex winexe
@cindex powershell
-@command{winexe} runs processes on a remote Windows host, and
+@command{winexe} runs processes on a remote MS Windows host, and
@value{tramp} can use it for @code{process-file} and
@code{start-file-process}.
@option{explicit-shell-file-name} and @option{explicit-*-args} have to
be set properly so @kbd{M-x shell} can open a proper remote shell on a
-Windows host. To open @command{cmd}, set it as follows:
+MS Windows host. To open @command{cmd}, set it as follows:
@lisp
@group
(interactive)
(find-file
(read-file-name
- "Find Tramp file: "
+ "Find @value{tramp} file: "
"@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))))
@end group
@end lisp
@item Use bookmarks:
-Use bookmarks to save Tramp file names.
+Use bookmarks to save @value{tramp} file names.
@ifinfo
@pxref{Bookmarks, , , emacs}.
@end ifinfo
@c * Explain how tramp.el works in principle: open a shell on a remote
@c host and then send commands to it.
@c * Consistent small or capitalized words especially in menus.
-@c * Make a unique declaration of @trampfn.
projects / emacs.git / commitdiff