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