--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/etc/gnuserv.1	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,242 @@
+.TH GNUSERV 1 "" "XEmacs Server"
+.UC 4
+.SH NAME
+gnuserv, gnuclient, gnuattach, gnudoit \- Server and Clients for XEmacs
+.SH SYNOPSIS
+.B gnuclient
+[-q] [[-h hostname] [-p port] [-r pathname]] [[+line] path] ...
+.br
+.B gnuattach
+[[-h hostname] [-p port] [-r pathname]] [[+line] path] ...
+.br
+.B gnudoit 
+[-q] [[-h hostname] [-p port]] [sexpr] ...
+.br
+.B gnuserv
+.SH DESCRIPTION
+
+.PP
+\fIgnuclient\fP allows the user to request a running XEmacs process to edit
+the named files or directories (typically in a newly created X frame).
+.PP
+\fIgnuattach\fP allows the user to request a running XEmacs process to edit
+the named files or directories in the current TTY connection.  One typical
+use for this is with a dialup connection to a machine on which an XEmacs
+process is currently running.
+.PP
+\fIgnudoit\fP allows the user to request a running XEmacs process to
+evaluate the given arguments inside a progn LISP form.
+.PP
+\fIgnuserv\fP is the server program that is set running by XEmacs to handle
+all incoming and outgoing requests. It is not usually invoked directly, but is
+started from XEmacs by loading the \fIgnuserv\fP package and evaluating 
+the LISP form (gnuserv-start). 
+.SH OPTIONS
+.TP 8
+.BI \-q
+This option informs both \fIgnuclient\fP and \fIgnudoit\fP to exit once
+connection has been made with the XEmacs process.  Normally \fIgnuclient\fP
+waits until all of the files on the command line have been finished with
+(their buffers killed) by the XEmacs process, and \fIgnudoit\fP normally
+waits around for evaluation of its arguments by the XEmacs process, and
+prints the results or error conditions.  This option does not exist for
+\fIgnuattach\fP because it does not make sense -- XEmacs and the shell
+would fight for input and would screw up each other's output.
+.TP 8
+.BI \-h " hostname"
+Used only with Internet-domain sockets, this option specifies the host
+machine which should be running \fIgnuserv\fP.  If this option is not
+specified then the value of the environment variable GNU_HOST is used
+if set.  If no hostname is specified, and the GNU_HOST variable is not
+set, an internet connection will not be attempted.  N\.B.: \fIgnuserv\fP
+does NOT allow internet connections unless the GNU_SECURE variable has
+been specified and points at a file listing all trusted hosts. (See
+SECURITY below.)
+
+.br
+Note that an internet address may be specified instead of a hostname which can
+speed up connections to the server by quite a bit, especially if the client
+machine is running YP.
+
+.br
+Note also that a hostname of \fBunix\fP can be used to specify that
+the connection to the server should use a Unix-domain socket (if
+supported) rather than an Internet-domain socket.
+.TP 8
+.BI \-p " port"
+Used only with Internet-domain sockets, this option specifies the
+service port used to communicate between server and clients.  If this
+option is not specified, then the value of the environment variable
+GNU_PORT is used, if set, otherwise a service called ``gnuserv'' is
+looked up in the services database.  Finally, if no other value can be
+found for the port, then a default port is used which is usually 21490
++ uid.
+.br
+Note that since \fIgnuserv\fP doesn't allow command-line options, the port for
+it will have to be specified via one of the alternative methods.
+.TP 8
+.BI \-r " pathname"
+Used only with Internet-domain sockets, the pathname argument may be
+needed to inform XEmacs how to reach the root directory of a remote
+machine.  \fIgnuclient\fP and \fIgnuattach\fP prepend this string to
+each path argument given.  For example, if you were trying to edit a
+file on a client machine called otter, whose root directory was
+accessible from the server machine via the path /net/otter, then this
+argument should be set to '/net/otter'.  If this option is omitted,
+then the value is taken from the environment variable GNU_NODE, if
+set, or the empty string otherwise.
+.TP 8
+.BI "path"
+This is the path of the file to be edited.  If the file is a directory, then
+the directory browsers dired or monkey are usually invoked instead.
+.TP 8
+.BI "sexpr"
+This is part of an XEmacs LISP expression to evaluate.  All the sexprs are
+concatenated together and wrapped in a progn form before sending to
+XEmacs.  If no sexpr is supplied on the  \fIgnudoit\fP commandline,
+\fIgnudoit\fP will read the sexpr to be evaluated from standard input.
+
+.PP
+.SH SETUP
+\fIgnuserv\fP is packaged standardly with recent versions of XEmacs.
+Therefore, you should be able to start the server simply by evaluating
+the XEmacs Lisp form (gnuserv-start), or equivalently by typing
+`M-x gnuserv-start'.
+.SH EXAMPLE
+.RS 4
+gnudoit -q '(mh-smail)'
+.br
+gnuclient -h cuckoo -r /ange@otter: /tmp/*
+.br
+gnuattach ../src/listproc.c
+.RE
+
+.SH SYSV IPC 
+SysV IPC is used to communicate between \fIgnuclient\fP,
+\fIgnuattach\fP, \fIgnudoit\fP and \fIgnuserv\fP if the symbol
+SYSV_IPC is defined at the top of gnuserv.h. This is incompatible with
+both Unix-domain and Internet-domain socket communication as described
+below. A file called /tmp/gsrv??? is created as a key for the message
+queue, and if removed will cause the communication between server and
+client to fail until the server is restarted.
+.SH UNIX-DOMAIN SOCKETS
+A Unix-domain socket is used to communicate between \fIgnuclient\fP,
+\fIgnuattach\fP, \fIgnudoit\fP and \fIgnuserv\fP if the symbol
+UNIX_DOMAIN_SOCKETS is defined at the top of gnuserv.h.  A file called
+/tmp/gsrvdir????/gsrv is created for communication and if deleted will
+cause communication between server and client to fail.  Only the user
+running gnuserv will be able to connect to the socket.
+.SH INTERNET-DOMAIN SOCKETS
+Internet-domain sockets are used to communicate between
+\fIgnuclient\fP, \fIgnuattach\fP, \fIgnudoit\fP and \fIgnuserv\fP if
+the symbol INTERNET_DOMAIN_SOCKETS is defined at the top of
+gnuserv.h. Both Internet-domain and Unix-domain sockets can be used at
+the same time. If a hostname is specified via -h or via the GNU_HOST
+environment variable, \fIgnudoit\fP, \fIgnuclient\fP and
+\fIgnuattach\fP establish connections using an internet domain
+socket. If not, a local connection is attempted via either a
+unix-domain socket or SYSV IPC."
+.SH SECURITY
+Using Internet-domain sockets, a more robust form of security is
+needed that wasn't necessary with either Unix-domain sockets or SysV
+IPC. Currently, two authentication protocols are supported to provide
+this: MIT-MAGIC-COOKIE-1 (based on the X11 xauth(1) program) and a
+simple host-based access control mechanism, hereafter called
+GNUSERV-1. The GNUSERV-1 protocol is always available, whereas support
+for MIT-MAGIC-COOKIE-1 may or may not have been enabled (via a #define
+at the top of gnuserv.h) at compile-time.
+.PP
+\fIgnuserv\fP, using GNUSERV-1, performs a limited form of access
+control at the machine level. By default no internet-domain socket is
+opened.  If the variable GNU_SECURE can be found in \fIgnuserv\fP's
+environment, and it names a readable filename, then this file is
+opened and assumed to be a list of hosts, one per line, from which the
+server will allow requests. Connections from any other host will be
+rejected. Even the machine on which \fIgnuserv\fP is running is not
+permitted to make connections via the internet socket unless its
+hostname is explicitly specified in this file.  Note that a host may
+be either a numeric IP address or a hostname, and that
+.I any
+user on an approved host may connect to your gnuserv and execute arbitrary
+elisp (e.g., delete all your files).
+If this file contains a lot of
+hostnames then the server may take quite a time to start up.
+.PP
+When the MIT-MAGIC-COOKIE-1 protocol is enabled, an internet socket
+\fIis\fP opened by default. \fIgnuserv\fP will accept a connection from
+any host, and will wait for a "magic cookie" (essentially, a password)
+to be presented by the client. If the client doesn't present the
+cookie, or if the cookie is wrong, the authentication of the client is
+considered to have failed. At this point. \fIgnuserv\fP falls back to
+the GNUSERV-1 protocol; If the client is calling from a host listed in
+the GNU_SECURE file, the connection will be accepted, otherwise it
+will be rejected. 
+.TP 4
+.I  Using MIT-MAGIC-COOKIE-1 authentication
+When the \fIgnuserv\fP server is started, it looks for a cookie
+defined for display 999 on the machine where it is running. If the
+cookie is found, it will be stored for use as the authentication
+cookie. These cookies are defined in an authorization file (usually
+~/.Xauthority) that is manipulated by the X11 xauth(1) program. For
+example, a machine "kali" which runs an emacs that invokes
+\fIgnuserv\fP should respond as follows (at the shell prompt) when set
+up correctly.
+.PP
+.RS 8
+kali% xauth list
+.br
+GS65.SP.CS.CMU.EDU:0  MIT-MAGIC-COOKIE-1  11223344
+.br
+KALI.FTM.CS.CMU.EDU:999  MIT-MAGIC-COOKIE-1  1234
+.RE
+.PP
+.RS 4
+In the above case, the authorization file defines two cookies. The
+second one, defined for screen 999 on the server machine, is used for
+gnuserv authentication. 
+.PP
+On the client machine's side, the authorization file must contain an
+identical line, specifying the 
+.I server's 
+cookie. In other words, on a machine "foobar" which wishes to connect
+to "kali,"  the `xauth list' output should contain the line:
+.PP
+.RS 4
+KALI.FTM.CS.CMU.EDU:999  MIT-MAGIC-COOKIE-1  1234
+.RE
+.PP
+For more information on authorization files, take a look at the
+xauth(1X11) man page, or invoke xauth interactively (without any
+arguments) and type "help" at the prompt. Remember that case in the
+name of the authorization protocol (i.e.`MIT-MAGIC-COOKIE-1') 
+.I is
+significant!
+.RE
+
+.SH FILES
+.PP
+.TP 8
+.B /tmp/gsrv???
+(SYSV_IPC only)
+.TP 8
+.B /tmp/gsrvdir???/gsrv
+(unix domain sockets only)
+.TP 8
+.B ~/.emacs
+XEmacs customization file, see xemacs(1).
+.SH SEE ALSO
+.PP
+.TP 8
+xauth(1X11), Xsecurity(1X11)
+.SH BUGS
+.PP 
+Ctrl-D's occurring in gnudoit input strings won't be handled correctly.
+.PP 
+NULs occurring in result strings don't get passed back to gnudoit properly.
+
+.SH AUTHOR.
+Andy Norman (ange@hplb.hpl.hp.com), based heavily upon
+etc/emacsclient.c, etc/server.c and lisp/server.el from the GNU Emacs
+18.52 distribution.  Various modifications from Bob Weiner (weiner@mot.com),
+Darrell Kindred (dkindred@cmu.edu), Arup Mukherjee (arup@cmu.edu), and
+Ben Wing (wing@666.com).