Mercurial > hg > xemacs-beta

comparison etc/gnuserv.1 @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children 0132846995bd
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1 .TH GNUSERV 1 "" "XEmacs Server"
2 .UC 4
3 .SH NAME
4 gnuserv, gnuclient, gnuattach, gnudoit \- Server and Clients for XEmacs
5 .SH SYNOPSIS
6 .B gnuclient
7 [-q] [[-h hostname] [-p port] [-r pathname]] [[+line] path] ...
8 .br
9 .B gnuattach
10 [[-h hostname] [-p port] [-r pathname]] [[+line] path] ...
11 .br
12 .B gnudoit
13 [-q] [[-h hostname] [-p port]] [sexpr] ...
14 .br
15 .B gnuserv
16 .SH DESCRIPTION
17
18 .PP
19 \fIgnuclient\fP allows the user to request a running XEmacs process to edit
20 the named files or directories (typically in a newly created X frame).
21 .PP
22 \fIgnuattach\fP allows the user to request a running XEmacs process to edit
23 the named files or directories in the current TTY connection. One typical
24 use for this is with a dialup connection to a machine on which an XEmacs
25 process is currently running.
26 .PP
27 \fIgnudoit\fP allows the user to request a running XEmacs process to
28 evaluate the given arguments inside a progn LISP form.
29 .PP
30 \fIgnuserv\fP is the server program that is set running by XEmacs to handle
31 all incoming and outgoing requests. It is not usually invoked directly, but is
32 started from XEmacs by loading the \fIgnuserv\fP package and evaluating
33 the LISP form (gnuserv-start).
34 .SH OPTIONS
35 .TP 8
36 .BI \-q
37 This option informs both \fIgnuclient\fP and \fIgnudoit\fP to exit once
38 connection has been made with the XEmacs process. Normally \fIgnuclient\fP
39 waits until all of the files on the command line have been finished with
40 (their buffers killed) by the XEmacs process, and \fIgnudoit\fP normally
41 waits around for evaluation of its arguments by the XEmacs process, and
42 prints the results or error conditions. This option does not exist for
43 \fIgnuattach\fP because it does not make sense -- XEmacs and the shell
44 would fight for input and would screw up each other's output.
45 .TP 8
46 .BI \-h " hostname"
47 Used only with Internet-domain sockets, this option specifies the host
48 machine which should be running \fIgnuserv\fP. If this option is not
49 specified then the value of the environment variable GNU_HOST is used
50 if set. If no hostname is specified, and the GNU_HOST variable is not
51 set, an internet connection will not be attempted. N\.B.: \fIgnuserv\fP
52 does NOT allow internet connections unless the GNU_SECURE variable has
53 been specified and points at a file listing all trusted hosts. (See
54 SECURITY below.)
55
56 .br
57 Note that an internet address may be specified instead of a hostname which can
58 speed up connections to the server by quite a bit, especially if the client
59 machine is running YP.
60
61 .br
62 Note also that a hostname of \fBunix\fP can be used to specify that
63 the connection to the server should use a Unix-domain socket (if
64 supported) rather than an Internet-domain socket.
65 .TP 8
66 .BI \-p " port"
67 Used only with Internet-domain sockets, this option specifies the
68 service port used to communicate between server and clients. If this
69 option is not specified, then the value of the environment variable
70 GNU_PORT is used, if set, otherwise a service called ``gnuserv'' is
71 looked up in the services database. Finally, if no other value can be
72 found for the port, then a default port is used which is usually 21490
73 + uid.
74 .br
75 Note that since \fIgnuserv\fP doesn't allow command-line options, the port for
76 it will have to be specified via one of the alternative methods.
77 .TP 8
78 .BI \-r " pathname"
79 Used only with Internet-domain sockets, the pathname argument may be
80 needed to inform XEmacs how to reach the root directory of a remote
81 machine. \fIgnuclient\fP and \fIgnuattach\fP prepend this string to
82 each path argument given. For example, if you were trying to edit a
83 file on a client machine called otter, whose root directory was
84 accessible from the server machine via the path /net/otter, then this
85 argument should be set to '/net/otter'. If this option is omitted,
86 then the value is taken from the environment variable GNU_NODE, if
87 set, or the empty string otherwise.
88 .TP 8
89 .BI "path"
90 This is the path of the file to be edited. If the file is a directory, then
91 the directory browsers dired or monkey are usually invoked instead.
92 .TP 8
93 .BI "sexpr"
94 This is part of an XEmacs LISP expression to evaluate. All the sexprs are
95 concatenated together and wrapped in a progn form before sending to
96 XEmacs. If no sexpr is supplied on the \fIgnudoit\fP commandline,
97 \fIgnudoit\fP will read the sexpr to be evaluated from standard input.
98
99 .PP
100 .SH SETUP
101 \fIgnuserv\fP is packaged standardly with recent versions of XEmacs.
102 Therefore, you should be able to start the server simply by evaluating
103 the XEmacs Lisp form (gnuserv-start), or equivalently by typing
104 `M-x gnuserv-start'.
105 .SH EXAMPLE
106 .RS 4
107 gnudoit -q '(mh-smail)'
108 .br
109 gnuclient -h cuckoo -r /ange@otter: /tmp/*
110 .br
111 gnuattach ../src/listproc.c
112 .RE
113
114 .SH SYSV IPC
115 SysV IPC is used to communicate between \fIgnuclient\fP,
116 \fIgnuattach\fP, \fIgnudoit\fP and \fIgnuserv\fP if the symbol
117 SYSV_IPC is defined at the top of gnuserv.h. This is incompatible with
118 both Unix-domain and Internet-domain socket communication as described
119 below. A file called /tmp/gsrv??? is created as a key for the message
120 queue, and if removed will cause the communication between server and
121 client to fail until the server is restarted.
122 .SH UNIX-DOMAIN SOCKETS
123 A Unix-domain socket is used to communicate between \fIgnuclient\fP,
124 \fIgnuattach\fP, \fIgnudoit\fP and \fIgnuserv\fP if the symbol
125 UNIX_DOMAIN_SOCKETS is defined at the top of gnuserv.h. A file called
126 /tmp/gsrvdir????/gsrv is created for communication and if deleted will
127 cause communication between server and client to fail. Only the user
128 running gnuserv will be able to connect to the socket.
129 .SH INTERNET-DOMAIN SOCKETS
130 Internet-domain sockets are used to communicate between
131 \fIgnuclient\fP, \fIgnuattach\fP, \fIgnudoit\fP and \fIgnuserv\fP if
132 the symbol INTERNET_DOMAIN_SOCKETS is defined at the top of
133 gnuserv.h. Both Internet-domain and Unix-domain sockets can be used at
134 the same time. If a hostname is specified via -h or via the GNU_HOST
135 environment variable, \fIgnudoit\fP, \fIgnuclient\fP and
136 \fIgnuattach\fP establish connections using an internet domain
137 socket. If not, a local connection is attempted via either a
138 unix-domain socket or SYSV IPC."
139 .SH SECURITY
140 Using Internet-domain sockets, a more robust form of security is
141 needed that wasn't necessary with either Unix-domain sockets or SysV
142 IPC. Currently, two authentication protocols are supported to provide
143 this: MIT-MAGIC-COOKIE-1 (based on the X11 xauth(1) program) and a
144 simple host-based access control mechanism, hereafter called
145 GNUSERV-1. The GNUSERV-1 protocol is always available, whereas support
146 for MIT-MAGIC-COOKIE-1 may or may not have been enabled (via a #define
147 at the top of gnuserv.h) at compile-time.
148 .PP
149 \fIgnuserv\fP, using GNUSERV-1, performs a limited form of access
150 control at the machine level. By default no internet-domain socket is
151 opened. If the variable GNU_SECURE can be found in \fIgnuserv\fP's
152 environment, and it names a readable filename, then this file is
153 opened and assumed to be a list of hosts, one per line, from which the
154 server will allow requests. Connections from any other host will be
155 rejected. Even the machine on which \fIgnuserv\fP is running is not
156 permitted to make connections via the internet socket unless its
157 hostname is explicitly specified in this file. Note that a host may
158 be either a numeric IP address or a hostname, and that
159 .I any
160 user on an approved host may connect to your gnuserv and execute arbitrary
161 elisp (e.g., delete all your files).
162 If this file contains a lot of
163 hostnames then the server may take quite a time to start up.
164 .PP
165 When the MIT-MAGIC-COOKIE-1 protocol is enabled, an internet socket
166 \fIis\fP opened by default. \fIgnuserv\fP will accept a connection from
167 any host, and will wait for a "magic cookie" (essentially, a password)
168 to be presented by the client. If the client doesn't present the
169 cookie, or if the cookie is wrong, the authentication of the client is
170 considered to have failed. At this point. \fIgnuserv\fP falls back to
171 the GNUSERV-1 protocol; If the client is calling from a host listed in
172 the GNU_SECURE file, the connection will be accepted, otherwise it
173 will be rejected.
174 .TP 4
175 .I Using MIT-MAGIC-COOKIE-1 authentication
176 When the \fIgnuserv\fP server is started, it looks for a cookie
177 defined for display 999 on the machine where it is running. If the
178 cookie is found, it will be stored for use as the authentication
179 cookie. These cookies are defined in an authorization file (usually
180 ~/.Xauthority) that is manipulated by the X11 xauth(1) program. For
181 example, a machine "kali" which runs an emacs that invokes
182 \fIgnuserv\fP should respond as follows (at the shell prompt) when set
183 up correctly.
184 .PP
185 .RS 8
186 kali% xauth list
187 .br
188 GS65.SP.CS.CMU.EDU:0 MIT-MAGIC-COOKIE-1 11223344
189 .br
190 KALI.FTM.CS.CMU.EDU:999 MIT-MAGIC-COOKIE-1 1234
191 .RE
192 .PP
193 .RS 4
194 In the above case, the authorization file defines two cookies. The
195 second one, defined for screen 999 on the server machine, is used for
196 gnuserv authentication.
197 .PP
198 On the client machine's side, the authorization file must contain an
199 identical line, specifying the
200 .I server's
201 cookie. In other words, on a machine "foobar" which wishes to connect
202 to "kali," the `xauth list' output should contain the line:
203 .PP
204 .RS 4
205 KALI.FTM.CS.CMU.EDU:999 MIT-MAGIC-COOKIE-1 1234
206 .RE
207 .PP
208 For more information on authorization files, take a look at the
209 xauth(1X11) man page, or invoke xauth interactively (without any
210 arguments) and type "help" at the prompt. Remember that case in the
211 name of the authorization protocol (i.e.`MIT-MAGIC-COOKIE-1')
212 .I is
213 significant!
214 .RE
215
216 .SH FILES
217 .PP
218 .TP 8
219 .B /tmp/gsrv???
220 (SYSV_IPC only)
221 .TP 8
222 .B /tmp/gsrvdir???/gsrv
223 (unix domain sockets only)
224 .TP 8
225 .B ~/.emacs
226 XEmacs customization file, see xemacs(1).
227 .SH SEE ALSO
228 .PP
229 .TP 8
230 xauth(1X11), Xsecurity(1X11)
231 .SH BUGS
232 .PP
233 Ctrl-D's occurring in gnudoit input strings won't be handled correctly.
234 .PP
235 NULs occurring in result strings don't get passed back to gnudoit properly.
236
237 .SH AUTHOR.
238 Andy Norman (ange@hplb.hpl.hp.com), based heavily upon
239 etc/emacsclient.c, etc/server.c and lisp/server.el from the GNU Emacs
240 18.52 distribution. Various modifications from Bob Weiner (weiner@mot.com),
241 Darrell Kindred (dkindred@cmu.edu), Arup Mukherjee (arup@cmu.edu), and
242 Ben Wing (wing@666.com).