428
+ − 1 .TH GNUSERV 1 "" "XEmacs Server"
+ − 2 .UC 4
+ − 3 .SH NAME
+ − 4 gnuserv, gnuclient \- Server and Clients for XEmacs
+ − 5 .SH SYNOPSIS
+ − 6 .B gnuclient
+ − 7 [-nw] [-display display] [-q] [-v] [-l library] [-batch] [-f function] [-eval form]
+ − 8 [-h hostname] [-p port] [-r remote-pathname] [[+line] file] ...
+ − 9 .br
+ − 10 .B gnudoit [-q]
+ − 11 form
+ − 12 .br
+ − 13 .B gnuserv
+ − 14 .br
+ − 15 .B gnuattach
+ − 16 Removed as of gnuserv 3.x
+ − 17 .SH DESCRIPTION
+ − 18
+ − 19 .PP
2437
+ − 20 \fIgnuserv\fP is a server program run as a subprocess of XEmacs to handle
+ − 21 all incoming and outgoing requests from \fIgnuclient\fP. It is not usually
+ − 22 invoked directly, but is started from XEmacs by loading the \fIgnuserv\fP
+ − 23 package and evaluating the Lisp form (gnuserv-start).
+ − 24 .PP
428
+ − 25 \fIgnuclient\fP allows the user to request a running XEmacs process to
+ − 26 edit the named files or directories and/or evaluate lisp forms.
2437
+ − 27 Depending on your environment, TTY, X, GTK, or MS Windows frames, as well as
+ − 28 batch (frameless) execution of Lisp may be available.
428
+ − 29 One typical use for this is with a dialup connection to a machine on
+ − 30 which an XEmacs process is currently running.
+ − 31 .PP
+ − 32 \fIgnudoit\fP is a shell script frontend to ``gnuclient -batch -eval form''.
442
+ − 33 Its use is deprecated. Try to get used to calling gnuclient directly.
428
+ − 34 .PP
+ − 35 \fIgnuattach\fP no longer exists. Its functionality has been replaced by
+ − 36 \fIgnuclient -nw\fP.
+ − 37 .SH OPTIONS
+ − 38 .PP
2437
+ − 39 \fIgnuclient\fP supports as many of the command line options of Emacs as
+ − 40 make sense in this context. In addition it adds a few of its own.
428
+ − 41 .br
2437
+ − 42 For backward compatibility, ``long'' options (\fi.e.\fP, with doubled hyphen)
+ − 43 may be specified using a single hyphen instead of a doubled one. Similarly,
+ − 44 the ``-nw'' option is a historical artifact: a multiletter option with no
+ − 45 double-hyphen version.
428
+ − 46 .TP 8
+ − 47 .BI \-nw
+ − 48 This option makes \fIgnuclient\fP act as a frontend such that XEmacs
+ − 49 can attach to the current TTY. XEmacs will then open a new TTY frame.
+ − 50 The effect is similar to having started a new XEmacs on this TTY with
+ − 51 the ``-nw'' option. It currently only works if XEmacs is running on
+ − 52 the same machine as gnuclient. This is the default if the `DISPLAY'
+ − 53 environment variable is not set.
+ − 54 .TP 8
2437
+ − 55 .BI \--display " display, " \-display " display"
428
+ − 56 If this option is given or the `DISPLAY' environment variable is set
+ − 57 then gnuclient will tell XEmacs to edit files in a frame on the
+ − 58 specified X device.
+ − 59 .TP 8
+ − 60 .BI \-q
+ − 61 This option informs \fIgnuclient\fP to exit once connection has been
+ − 62 made with the XEmacs process. Normally \fIgnuclient\fP waits until
+ − 63 all of the files on the command line have been finished with (their
+ − 64 buffers killed) by the XEmacs process, and all the forms have been
2437
+ − 65 evaluated. Note that this is \fIdifferent\fP from XEmacs itself, where
+ − 66 this option means to inhibit loading of the user init file.
428
+ − 67 .TP 8
+ − 68 .BI \-v
+ − 69 When this option is specified \fIgnuclient\fP will request for the
+ − 70 specified files to be viewed instead of edited.
+ − 71 .TP 8
+ − 72 .BI \-l " library"
+ − 73 Tell Emacs to load the specified library.
+ − 74 .TP 8
+ − 75 .BI \-batch
+ − 76 Tell Emacs not to open any frames. Just load libraries and evaluate
+ − 77 lisp code. If no files to execute, functions to call or forms to eval
+ − 78 are given using the
+ − 79 .BR \-l ,
+ − 80 .BR \-f ,
+ − 81 or
+ − 82 .B \-eval
+ − 83 options, then forms to eval are read from STDIN.
+ − 84 .TP 8
+ − 85 .BI \-f " function,"
+ − 86 Make Emacs execute the lisp function.
+ − 87 .TP 8
2437
+ − 88 .BI \--eval " form, " \-eval " form"
+ − 89 Make Emacs execute the Lisp form.
428
+ − 90 .TP 8
+ − 91 .BI \-h " hostname"
+ − 92 Used only with Internet-domain sockets, this option specifies the host
+ − 93 machine which should be running \fIgnuserv\fP. If this option is not
+ − 94 specified then the value of the environment variable GNU_HOST is used
+ − 95 if set. If no hostname is specified, and the GNU_HOST variable is not
2437
+ − 96 set, an Internet connection will not be attempted. N\.B.:
+ − 97 \fIgnuserv\fP does NOT allow Internet connections unless XAUTH
428
+ − 98 authentication is used or the GNU_SECURE variable has been specified
+ − 99 and points at a file listing all trusted hosts. (See SECURITY below.)
+ − 100
+ − 101 .br
2437
+ − 102 An Internet address (``dotted-quad'') may be specified instead of a
+ − 103 hostname. IPv6 support is not robust.
428
+ − 104
+ − 105 .br
2437
+ − 106 A hostname of \fBunix\fP can be used to specify that
428
+ − 107 the connection to the server should use a Unix-domain socket (if
+ − 108 supported) rather than an Internet-domain socket.
+ − 109 .TP 8
+ − 110 .BI \-p " port"
+ − 111 Used only with Internet-domain sockets, this option specifies the
+ − 112 service port used to communicate between server and clients. If this
+ − 113 option is not specified, then the value of the environment variable
+ − 114 GNU_PORT is used, if set, otherwise a service called ``gnuserv'' is
+ − 115 looked up in the services database. Finally, if no other value can be
+ − 116 found for the port, then a default port is used which is usually 21490
+ − 117 + uid.
+ − 118 .br
+ − 119 Note that since \fIgnuserv\fP doesn't allow command-line options, the port for
+ − 120 it will have to be specified via one of the alternative methods.
+ − 121 .TP 8
+ − 122 .BI \-r " pathname"
+ − 123 Used only with Internet-domain sockets, the pathname argument may be
+ − 124 needed to inform XEmacs how to reach the root directory of a remote
+ − 125 machine. \fIgnuclient\fP prepends this string to each path argument
+ − 126 given. For example, if you were trying to edit a file on a client
+ − 127 machine called otter, whose root directory was accessible from the
+ − 128 server machine via the path /net/otter, then this argument should be
+ − 129 set to '/net/otter'. If this option is omitted, then the value is
+ − 130 taken from the environment variable GNU_NODE, if set, or the empty
+ − 131 string otherwise.
+ − 132 .TP 8
+ − 133 .BI "[+n] file"
+ − 134 This is the path of the file to be edited. If the file is a directory, then
+ − 135 the directory browsers dired or monkey are usually invoked instead.
+ − 136 The cursor is put at line number 'n' if specified.
+ − 137
+ − 138 .SH SETUP
2437
+ − 139 \fIgnuserv\fP is included with recent versions of XEmacs; no installation
+ − 140 is required. The server must be started before clients may attempt to
+ − 141 connect. Start the server by evaluating the Lisp form (gnuserv-start), or
+ − 142 interactively by typing `M-x gnuserv-start'.
428
+ − 143
+ − 144 .SH CONFIGURATION
2437
+ − 145 The behavior of this suite of programs can be customized to a large extent.
+ − 146 Type `M-x customize-group RET gnuserv RET'. More documentation can be found
+ − 147 in the file `gnuserv.el'
428
+ − 148
+ − 149 .SH EXAMPLE
+ − 150 .RS 4
+ − 151 gnuclient -q -f mh-smail
+ − 152 .br
+ − 153 gnuclient -h cuckoo -r /ange@otter: /tmp/*
+ − 154 .br
+ − 155 gnuclient -nw ../src/listproc.c
+ − 156 .RE
+ − 157 .br
+ − 158
+ − 159 .br
+ − 160 More examples and sample wrapper scripts are provided in the
2437
+ − 161 etc/gnuserv directory of the XEmacs installation.
428
+ − 162
+ − 163
+ − 164 .SH SYSV IPC
2437
+ − 165 SysV IPC is a build-time option, enabled by defining the symbol SYSV_IPC
+ − 166 at the top of gnuserv.h. It is used to communicate between \fIgnuclient\fP
+ − 167 and \fIgnuserv\fP. It is incompatible with both Unix-domain and
428
+ − 168 Internet-domain socket communication as described below. A file called
+ − 169 /tmp/gsrv??? is created as a key for the message queue, and if removed
+ − 170 will cause the communication between server and client to fail until
+ − 171 the server is restarted.
+ − 172 .SH UNIX-DOMAIN SOCKETS
2437
+ − 173 Unix-domain sockets are a build-time option, enabled by defining the symbol
+ − 174 UNIX_DOMAIN_SOCKETS at the top of gnuserv.h. A Unix-domain socket is used
+ − 175 to communicate between \fIgnuclient\fP
+ − 176 and \fIgnuserv\fP. A file called /tmp/gsrvdir????/gsrv is created for
464
+ − 177 communication. If the symbol USE_TMPDIR is set at the top of gnuserv.h,
+ − 178 $TMPDIR, when set, is used instead of /tmp. If that file is deleted,
+ − 179 or TMPDIR has different values for the server and the client, communication
+ − 180 between server and client will fail. Only the user running gnuserv will be
+ − 181 able to connect to the socket.
428
+ − 182 .SH INTERNET-DOMAIN SOCKETS
2437
+ − 183 Internet-domain sockets are a build-time option, enabled by defining the
+ − 184 symbol INTERNET_DOMAIN_SOCKETS at the top of gnuserv.h. Internet-domain
+ − 185 sockets are used to communicate between \fIgnuclient\fP and \fIgnuserv\fP.
+ − 186 Both Internet-domain and Unix-domain sockets can be used at the same
+ − 187 time. If a hostname is specified via -h or via the GNU_HOST
428
+ − 188 environment variable, \fIgnuclient\fP establish connections using an
2437
+ − 189 Internet domain socket. If not, a local connection is attempted via
+ − 190 either a Unix-domain socket or SYSV IPC.
428
+ − 191 .SH SECURITY
+ − 192 Using Internet-domain sockets, a more robust form of security is
+ − 193 needed that wasn't necessary with either Unix-domain sockets or SysV
+ − 194 IPC. Currently, two authentication protocols are supported to provide
+ − 195 this: MIT-MAGIC-COOKIE-1 (based on the X11 xauth(1) program) and a
+ − 196 simple host-based access control mechanism, hereafter called
2437
+ − 197 GNUSERV-1. The GNUSERV-1 protocol is always available. Support
+ − 198 for MIT-MAGIC-COOKIE-1 is enabled (by defining AUTH_MAGIC_COOKIE
+ − 199 at the top of gnuserv.h.
428
+ − 200 .PP
+ − 201 \fIgnuserv\fP, using GNUSERV-1, performs a limited form of access
2437
+ − 202 control at the machine level. By default no Internet-domain socket is
428
+ − 203 opened. If the variable GNU_SECURE can be found in \fIgnuserv\fP's
+ − 204 environment, and it names a readable filename, then this file is
+ − 205 opened and assumed to be a list of hosts, one per line, from which the
+ − 206 server will allow requests. Connections from any other host will be
+ − 207 rejected. Even the machine on which \fIgnuserv\fP is running is not
2437
+ − 208 permitted to make connections via the Internet socket unless its
428
+ − 209 hostname is explicitly specified in this file. Note that a host may
+ − 210 be either a numeric IP address or a hostname, and that
+ − 211 .I any
+ − 212 user on an approved host may connect to your gnuserv and execute arbitrary
2437
+ − 213 Lisp (e.g., delete all your files).
428
+ − 214 If this file contains a lot of
2437
+ − 215 hostnames then the server may take quite a long time to start up.
428
+ − 216 .PP
2437
+ − 217 When the MIT-MAGIC-COOKIE-1 protocol is enabled, an Internet socket
428
+ − 218 \fIis\fP opened by default. \fIgnuserv\fP will accept a connection from
+ − 219 any host, and will wait for a "magic cookie" (essentially, a password)
+ − 220 to be presented by the client. If the client doesn't present the
+ − 221 cookie, or if the cookie is wrong, the authentication of the client is
+ − 222 considered to have failed. At this point. \fIgnuserv\fP falls back to
+ − 223 the GNUSERV-1 protocol; If the client is calling from a host listed in
+ − 224 the GNU_SECURE file, the connection will be accepted, otherwise it
+ − 225 will be rejected.
+ − 226 .TP 4
+ − 227 .I Using MIT-MAGIC-COOKIE-1 authentication
+ − 228 When the \fIgnuserv\fP server is started, it looks for a cookie
+ − 229 defined for display 999 on the machine where it is running. If the
+ − 230 cookie is found, it will be stored for use as the authentication
+ − 231 cookie. These cookies are defined in an authorization file (usually
+ − 232 ~/.Xauthority) that is manipulated by the X11 xauth(1) program. For
+ − 233 example, a machine "kali" which runs an emacs that invokes
+ − 234 \fIgnuserv\fP should respond as follows (at the shell prompt) when set
+ − 235 up correctly.
+ − 236 .PP
+ − 237 .RS 8
+ − 238 kali% xauth list
+ − 239 .br
+ − 240 GS65.SP.CS.CMU.EDU:0 MIT-MAGIC-COOKIE-1 11223344
+ − 241 .br
+ − 242 KALI.FTM.CS.CMU.EDU:999 MIT-MAGIC-COOKIE-1 1234
+ − 243 .RE
+ − 244 .PP
+ − 245 .RS 4
+ − 246 In the above case, the authorization file defines two cookies. The
+ − 247 second one, defined for screen 999 on the server machine, is used for
+ − 248 gnuserv authentication.
+ − 249 .PP
+ − 250 On the client machine's side, the authorization file must contain an
+ − 251 identical line, specifying the
+ − 252 .I server's
+ − 253 cookie. In other words, on a machine "foobar" which wishes to connect
+ − 254 to "kali," the `xauth list' output should contain the line:
+ − 255 .PP
+ − 256 .RS 4
+ − 257 KALI.FTM.CS.CMU.EDU:999 MIT-MAGIC-COOKIE-1 1234
+ − 258 .RE
+ − 259 .PP
+ − 260 For more information on authorization files, take a look at the
+ − 261 xauth(1X11) man page, or invoke xauth interactively (without any
+ − 262 arguments) and type "help" at the prompt. Remember that case in the
+ − 263 name of the authorization protocol (i.e.`MIT-MAGIC-COOKIE-1')
+ − 264 .I is
+ − 265 significant!
+ − 266 .RE
+ − 267
+ − 268
+ − 269 .SH ENVIRONMENT
+ − 270 .PP
+ − 271 .TP 8
+ − 272 .B DISPLAY
2437
+ − 273 Default X (or GTK) device for display of edit frame.
428
+ − 274
+ − 275 .SH FILES
+ − 276 .PP
+ − 277 .TP 8
+ − 278 .B /tmp/gsrv???
+ − 279 (SYSV_IPC only)
+ − 280 .TP 8
+ − 281 .B /tmp/gsrvdir???/gsrv
+ − 282 (unix domain sockets only)
+ − 283 .TP 8
2437
+ − 284 .B ~/.xemacs/init.el
428
+ − 285 XEmacs customization file, see xemacs(1).
+ − 286 .SH SEE ALSO
+ − 287 .PP
+ − 288 .TP 8
+ − 289 xauth(1X11), Xsecurity(1X11), gnuserv.el
+ − 290 .SH BUGS
+ − 291 .PP
+ − 292 NULs occurring in result strings don't get passed back to gnudoit properly.
+ − 293
+ − 294 .SH AUTHOR.
+ − 295 Andy Norman (ange@hplb.hpl.hp.com), based heavily upon
+ − 296 etc/emacsclient.c, etc/server.c and lisp/server.el from the GNU Emacs
+ − 297 18.52 distribution. Various modifications from Bob Weiner (weiner@mot.com),
+ − 298 Darrell Kindred (dkindred@cmu.edu), Arup Mukherjee (arup@cmu.edu), Ben
+ − 299 Wing (ben@xemacs.org) and Hrvoje Niksic (hniksic@xemacs.org).