Mercurial > hg > xemacs-beta

comparison etc/gnuserv.1 @ 428:3ecd8885ac67 r21-2-22

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-22
author cvs
date Mon, 13 Aug 2007 11:28:15 +0200
parents
children abe6d1db359e
comparison
equal deleted inserted replaced
427:0a0253eac470 428:3ecd8885ac67
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 depreciated. 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 and if deleted will cause communication between server
175 and client to fail. Only the user running gnuserv will be able to
176 connect to the socket.
177 .SH INTERNET-DOMAIN SOCKETS
178 Internet-domain sockets are used to communicate between
179 \fIgnuclient\fP and \fIgnuserv\fP if the symbol
180 INTERNET_DOMAIN_SOCKETS is defined at the top of gnuserv.h. Both
181 Internet-domain and Unix-domain sockets can be used at the same
182 time. If a hostname is specified via -h or via the GNU_HOST
183 environment variable, \fIgnuclient\fP establish connections using an
184 internet domain socket. If not, a local connection is attempted via
185 either a unix-domain socket or SYSV IPC.
186 .SH SECURITY
187 Using Internet-domain sockets, a more robust form of security is
188 needed that wasn't necessary with either Unix-domain sockets or SysV
189 IPC. Currently, two authentication protocols are supported to provide
190 this: MIT-MAGIC-COOKIE-1 (based on the X11 xauth(1) program) and a
191 simple host-based access control mechanism, hereafter called
192 GNUSERV-1. The GNUSERV-1 protocol is always available, whereas support
193 for MIT-MAGIC-COOKIE-1 may or may not have been enabled (via a #define
194 at the top of gnuserv.h) at compile-time.
195 .PP
196 \fIgnuserv\fP, using GNUSERV-1, performs a limited form of access
197 control at the machine level. By default no internet-domain socket is
198 opened. If the variable GNU_SECURE can be found in \fIgnuserv\fP's
199 environment, and it names a readable filename, then this file is
200 opened and assumed to be a list of hosts, one per line, from which the
201 server will allow requests. Connections from any other host will be
202 rejected. Even the machine on which \fIgnuserv\fP is running is not
203 permitted to make connections via the internet socket unless its
204 hostname is explicitly specified in this file. Note that a host may
205 be either a numeric IP address or a hostname, and that
206 .I any
207 user on an approved host may connect to your gnuserv and execute arbitrary
208 elisp (e.g., delete all your files).
209 If this file contains a lot of
210 hostnames then the server may take quite a time to start up.
211 .PP
212 When the MIT-MAGIC-COOKIE-1 protocol is enabled, an internet socket
213 \fIis\fP opened by default. \fIgnuserv\fP will accept a connection from
214 any host, and will wait for a "magic cookie" (essentially, a password)
215 to be presented by the client. If the client doesn't present the
216 cookie, or if the cookie is wrong, the authentication of the client is
217 considered to have failed. At this point. \fIgnuserv\fP falls back to
218 the GNUSERV-1 protocol; If the client is calling from a host listed in
219 the GNU_SECURE file, the connection will be accepted, otherwise it
220 will be rejected.
221 .TP 4
222 .I Using MIT-MAGIC-COOKIE-1 authentication
223 When the \fIgnuserv\fP server is started, it looks for a cookie
224 defined for display 999 on the machine where it is running. If the
225 cookie is found, it will be stored for use as the authentication
226 cookie. These cookies are defined in an authorization file (usually
227 ~/.Xauthority) that is manipulated by the X11 xauth(1) program. For
228 example, a machine "kali" which runs an emacs that invokes
229 \fIgnuserv\fP should respond as follows (at the shell prompt) when set
230 up correctly.
231 .PP
232 .RS 8
233 kali% xauth list
234 .br
235 GS65.SP.CS.CMU.EDU:0 MIT-MAGIC-COOKIE-1 11223344
236 .br
237 KALI.FTM.CS.CMU.EDU:999 MIT-MAGIC-COOKIE-1 1234
238 .RE
239 .PP
240 .RS 4
241 In the above case, the authorization file defines two cookies. The
242 second one, defined for screen 999 on the server machine, is used for
243 gnuserv authentication.
244 .PP
245 On the client machine's side, the authorization file must contain an
246 identical line, specifying the
247 .I server's
248 cookie. In other words, on a machine "foobar" which wishes to connect
249 to "kali," the `xauth list' output should contain the line:
250 .PP
251 .RS 4
252 KALI.FTM.CS.CMU.EDU:999 MIT-MAGIC-COOKIE-1 1234
253 .RE
254 .PP
255 For more information on authorization files, take a look at the
256 xauth(1X11) man page, or invoke xauth interactively (without any
257 arguments) and type "help" at the prompt. Remember that case in the
258 name of the authorization protocol (i.e.`MIT-MAGIC-COOKIE-1')
259 .I is
260 significant!
261 .RE
262
263
264 .SH ENVIRONMENT
265 .PP
266 .TP 8
267 .B DISPLAY
268 Default X device to put edit frame.
269
270 .SH FILES
271 .PP
272 .TP 8
273 .B /tmp/gsrv???
274 (SYSV_IPC only)
275 .TP 8
276 .B /tmp/gsrvdir???/gsrv
277 (unix domain sockets only)
278 .TP 8
279 .B ~/.emacs
280 XEmacs customization file, see xemacs(1).
281 .SH SEE ALSO
282 .PP
283 .TP 8
284 xauth(1X11), Xsecurity(1X11), gnuserv.el
285 .SH BUGS
286 .PP
287 NULs occurring in result strings don't get passed back to gnudoit properly.
288
289 .SH AUTHOR.
290 Andy Norman (ange@hplb.hpl.hp.com), based heavily upon
291 etc/emacsclient.c, etc/server.c and lisp/server.el from the GNU Emacs
292 18.52 distribution. Various modifications from Bob Weiner (weiner@mot.com),
293 Darrell Kindred (dkindred@cmu.edu), Arup Mukherjee (arup@cmu.edu), Ben
294 Wing (ben@xemacs.org) and Hrvoje Niksic (hniksic@xemacs.org).