>From f5a4c2ef877a476a1f2bfb8f3eb07cba7c641234 Mon Sep 17 00:00:00 2001 From: "Peder O. Klingenberg" Date: Sat, 29 Apr 2017 01:18:30 +0200 Subject: [PATCH] Improve documentation of TCP mode of server.el * doc/emacs/misc.texi (TCP Emacs server): New subsection describing the various knobs to tune server.el for TCP opereation. (emacsclient Options): Reference "TCP Emacs server" from description of --server-file. --- doc/emacs/misc.texi | 80 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 63 insertions(+), 17 deletions(-) diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index bcc20a6db1..c8504fef49 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -1661,10 +1661,66 @@ Emacs Server signaled.) Currently, this feature is mainly useful for developers. @menu +* TCP Emacs server:: Listening to a TCP socket. * Invoking emacsclient:: Connecting to the Emacs server. * emacsclient Options:: Emacs client startup options. @end menu +@node TCP Emacs server +@subsection TCP Emacs server +@cindex TCP Emacs server + +@vindex server-use-tcp + By default, the Emacs server will listen to a local unix domain +socket. In some cases it is useful to have it listen on a TCP socket +instead. Examples of such cases are operating systems like Microsoft +Windows that don't support local sockets, and if you need to contact +the Emacs server from a remote machine. You can set +@code{server-use-tcp} to non-@code{nil} to have Emacs listen on a TCP +socket instead of a local socket. This is the default if your OS does +not support local sockets. + +@vindex server-host +@vindex server-port + If the Emacs server is set to use TCP, it will by default listen to +a random port on the localhost interface. This can be changed to +another interface and/or a fixed port using the variables +@code{server-host} and @code{server-port}. + +@vindex server-auth-key + A TCP socket is not subject to file system permissions. To retain +some control over who can talk to a TCP Emacs server, the +@command{emacsclient} program must send an authorization key to the +server. This key is normally randomly generated by the Emacs server. +This is the recommended mode of operation. + +@findex server-generate-key + If needed, you can set it to a static value by setting the +@code{server-auth-key} variable. The key must consist of 64 ASCII +printable characters except for space (this means characters from ! to +~; or from code 33 to 126). You can use @kbd{M-x server-generate-key} +to get a random key. + +@vindex server-auth-dir +@cindex server file + When you start a TCP Emacs server, Emacs creates a @dfn{server file} +containing the TCP information to be used by @command{emacsclient} to +connect to the server. The variable @code{server-auth-dir} specifies +the directory containing the server file; by default, this is +@file{~/.emacs.d/server/}. In the absence of a local socket with file +permissions, it is the permissions of this directory that determines +who can talk to the Emacs server. + +@cindex @env{EMACS_SERVER_FILE} environment variable + To tell @command{emacsclient} to connect to the server over TCP with a +specific server file, use the @samp{-f} or @samp{--server-file} +option, or set the @env{EMACS_SERVER_FILE} environment variable +(@pxref{emacsclient Options}). If @code{server-auth-dir} is set to a +non-standard value, @command{emacsclient} needs an absolute path to the +server file, as the default @code{server-auth-dir} is hardcoded in +@command{emacsclient} as the base of relative filenames. + + @node Invoking emacsclient @subsection Invoking @code{emacsclient} @cindex @code{emacsclient} invocation @@ -1810,25 +1866,15 @@ emacsclient Options @item -f @var{server-file} @itemx --server-file=@var{server-file} -@cindex @env{EMACS_SERVER_FILE} environment variable Specify a @dfn{server file} for connecting to an Emacs server via TCP. -An Emacs server usually uses a -local socket to listen for connections. Some operating systems, -such as Microsoft Windows, do not support local sockets; in that case, -the server communicates with @command{emacsclient} via TCP. - -@vindex server-auth-dir -@cindex server file -@vindex server-port -When you start a TCP Emacs server, Emacs creates a @dfn{server file} -containing the TCP information to be used by @command{emacsclient} to -connect to the server. The variable @code{server-auth-dir} specifies -the directory containing the server file; by default, this is -@file{~/.emacs.d/server/}. To tell @command{emacsclient} to connect -to the server over TCP with a specific server file, use the @samp{-f} -or @samp{--server-file} option, or set the @env{EMACS_SERVER_FILE} -environment variable. +An Emacs server usually uses a local socket to listen for connections, +but also supports connections over TCP. To connect to a TCP Emacs +server, @command{emacsclient} needs to read a @dfn{server file} +containing the connection details of the Emacs server. The name of +this file is specified with this option, either as a file name +relative to @file{~/.emacs.d/server} or as an absolute file name. +@xref{TCP Emacs server}. @item -n @itemx --no-wait -- 2.11.0