From: Michael Albinus Date: Mon, 10 Jul 2017 13:36:23 +0000 (+0200) Subject: Add Quick Start Guide to Tramp manual X-Git-Tag: emacs-26.0.90~518^2~131 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0440c748aaec9b8b32c8cb268f6e24e874fedc75;p=emacs.git Add Quick Start Guide to Tramp manual * doc/misc/tramp.texi: Use consequently "@value{tramp}" and "MS Windows". (Quick Start Guide): New node. * doc/misc/trampver.texi: * lisp/net/trampver.el: Change version to "2.3.3-pre". --- diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 6209e02ebc5..1b751a01db6 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -43,7 +43,7 @@ copy and modify this GNU manual.'' @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 @@ -77,8 +77,8 @@ You can find the latest version of this document on the web at @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}. @@ -97,11 +97,12 @@ There is a mailing list for @value{tramp}, available at 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. @@ -192,7 +193,7 @@ and related programs. If these programs can successfully pass 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 @@ -207,7 +208,7 @@ benefit of direct integration of @value{tramp} in Emacs. @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. @@ -314,9 +315,9 @@ behind the scenes when you open a file with @value{tramp}. @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). @@ -354,7 +355,7 @@ From behind a firewall: @end example @noindent -Tramp developers: +@value{tramp} developers: @example ] @strong{git clone login@@git.sv.gnu.org:/srv/git/tramp.git} @@ -403,7 +404,7 @@ July 2002, @value{tramp} unified file names with Ange FTP@. In July 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}. @@ -418,6 +419,147 @@ XEmacs support was stopped in January 2016. Since March 2017, @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 @@ -610,16 +752,16 @@ continue connecting?''. @value{tramp} cannot handle such questions. 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. @@ -627,7 +769,7 @@ This method is also similar to @option{ssh}. It uses the @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}. @@ -635,7 +777,7 @@ 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. @@ -648,9 +790,9 @@ session. @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. @@ -730,9 +872,9 @@ This method supports the @samp{-p} argument. 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. @@ -742,17 +884,17 @@ 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. @@ -805,6 +947,8 @@ capable of servicing requests from @value{tramp}. @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 @@ -831,15 +975,16 @@ handling}. 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), @@ -876,6 +1021,7 @@ can. @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 @@ -949,7 +1095,7 @@ but with SSL encryption. Both methods support the port numbers. @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 @@ -981,8 +1127,8 @@ that for security reasons refuse @command{ssh} connections. @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 @@ -1070,7 +1216,7 @@ access and it has the most reasonable security protocols, use @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 @@ -1289,8 +1435,8 @@ restricted shell: @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 @@ -1746,8 +1892,8 @@ Similar localization may be necessary for handling wrong password 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} @@ -1847,7 +1993,7 @@ Then re-set the prompt string in @file{~/.emacs_SHELLNAME} as follows: @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 @@ -1859,8 +2005,8 @@ 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}): @@ -1891,7 +2037,7 @@ where @samp{192.168.0.1} is the remote host IP address @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 @@ -2072,12 +2218,12 @@ to direct all auto saves to that location. @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 @@ -2091,34 +2237,34 @@ Some older versions of Cygwin's @command{ssh} work with the @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. @@ -2716,11 +2862,11 @@ Arguments of the program to be debugged must be literal, can take 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}. @@ -2730,7 +2876,7 @@ processes triggered from @value{tramp}. @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 @@ -3283,7 +3429,7 @@ Redefine another key sequence in Emacs for @kbd{C-x C-f}: (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 @@ -3353,7 +3499,7 @@ The minibuffer expands for further editing. @item Use bookmarks: -Use bookmarks to save Tramp file names. +Use bookmarks to save @value{tramp} file names. @ifinfo @pxref{Bookmarks, , , emacs}. @end ifinfo @@ -3736,4 +3882,3 @@ strings from being written to @file{*trace-output*}. @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. diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 05b577da005..5d9dcc5635d 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,7 +8,7 @@ @c In the Tramp GIT, the version number is auto-frobbed from @c configure.ac, so you should edit that file and run @c "autoconf && ./configure" to change the version number. -@set trampver 2.3.2 +@set trampver 2.3.3-pre @c Other flags from configuration @set instprefix /usr/local diff --git a/lisp/net/trampver.el b/lisp/net/trampver.el index 4be487e1f4f..527630d747c 100644 --- a/lisp/net/trampver.el +++ b/lisp/net/trampver.el @@ -7,7 +7,7 @@ ;; Maintainer: Michael Albinus ;; Keywords: comm, processes ;; Package: tramp -;; Version: 2.3.2 +;; Version: 2.3.3-pre ;; This file is part of GNU Emacs. @@ -33,7 +33,7 @@ ;; should be changed only there. ;;;###tramp-autoload -(defconst tramp-version "2.3.2" +(defconst tramp-version "2.3.3-pre" "This version of Tramp.") ;;;###tramp-autoload @@ -55,7 +55,7 @@ ;; Check for Emacs version. (let ((x (if (>= emacs-major-version 24) "ok" - (format "Tramp 2.3.2 is not fit for %s" + (format "Tramp 2.3.3-pre is not fit for %s" (when (string-match "^.*$" (emacs-version)) (match-string 0 (emacs-version))))))) (unless (string-match "\\`ok\\'" x) (error "%s" x)))