Mercurial > hg > xemacs-beta
annotate etc/gnuserv.1 @ 5640:e6b5c49f9e13
Add autoload cookie to custom-set-face-bold
| author | Vin Shelton <acs@xemacs.org> |
|---|---|
| date | Sun, 08 Jan 2012 22:29:06 -0500 |
| parents | 863f16484873 |
| children |
| rev | line source |
|---|---|
| 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). | |
|
5428
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
300 |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
301 .SH COPYING |
|
5433
863f16484873
Added copyright notice with year 1998.
Mats Lidell <matsl@xemacs.org>
parents:
5428
diff
changeset
|
302 Copyright |
|
863f16484873
Added copyright notice with year 1998.
Mats Lidell <matsl@xemacs.org>
parents:
5428
diff
changeset
|
303 .if t \(co |
|
863f16484873
Added copyright notice with year 1998.
Mats Lidell <matsl@xemacs.org>
parents:
5428
diff
changeset
|
304 .if n (C) |
|
863f16484873
Added copyright notice with year 1998.
Mats Lidell <matsl@xemacs.org>
parents:
5428
diff
changeset
|
305 1998 Andy Norman, Bob Weiner, Darrell Kindred, Arup Mukherjee, Ben |
|
863f16484873
Added copyright notice with year 1998.
Mats Lidell <matsl@xemacs.org>
parents:
5428
diff
changeset
|
306 Wing and Hrvoje Niksic. |
|
5428
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
307 |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
308 .PP |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
309 This file is part of XEmacs. |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
310 .PP |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
311 XEmacs is free software: you can redistribute it and/or modify it |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
312 under the terms of the GNU General Public License as published by the |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
313 Free Software Foundation, either version 3 of the License, or (at your |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
314 option) any later version. |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
315 .PP |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
316 XEmacs is distributed in the hope that it will be useful, but WITHOUT |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
317 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
318 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
319 for more details. |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
320 .PP |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
321 You should have received a copy of the GNU General Public License |
|
73eef12660cd
Converted gnuserv docs to GPLv3 or later.
Mats Lidell <matsl@xemacs.org>
parents:
2437
diff
changeset
|
322 along with XEmacs. If not, see <http://www.gnu.org/licenses/>. |