1 .\" $XConsortium: Xserver.man /main/62 1996/12/09 17:06:18 kaleb $
2 .\" $XFree86: xc/programs/Xserver/Xserver.man,v 3.5.2.4 1998/02/24 13:20:02 dawes Exp $
3 .\" Copyright (c) 1984 - 1991, 1993, 1994 X Consortium
5 .\" Permission is hereby granted, free of charge, to any person obtaining
6 .\" a copy of this software and associated documentation files (the
7 .\" "Software"), to deal in the Software without restriction, including
8 .\" without limitation the rights to use, copy, modify, merge, publish,
9 .\" distribute, sublicense, and/or sell copies of the Software, and to
10 .\" permit persons to whom the Software is furnished to do so, subject to
11 .\" the following conditions:
13 .\" The above copyright notice and this permission notice shall be included
14 .\" in all copies or substantial portions of the Software.
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
20 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22 .\" OTHER DEALINGS IN THE SOFTWARE.
24 .\" Except as contained in this notice, the name of the X Consortium shall
25 .\" not be used in advertising or otherwise to promote the sale, use or
26 .\" other dealings in this Software without prior written authorization
27 .\" from the X Consortium.
28 .TH XSERVER 1 "Release 6.3" "X Version 11"
30 Xserver \- X Window System display server
36 is the generic name for the X Window System display server. It is
37 frequently a link or a copy of the appropriate server binary for
38 driving the most frequently used server on a given machine.
39 .SH "STARTING THE SERVER"
40 The X server is usually started from the X Display Manager program \fIxdm(1)\fP.
41 This utility is run from the system boot files and takes care of keeping
42 the server running, prompting for usernames and passwords, and starting up
45 Installations that run more than one window system may need to use the
46 \fIxinit(1)\fP utility instead of \fIxdm\fP. However, \fIxinit\fP is
47 to be considered a tool for building startup scripts and is not
48 intended for use by end users. Site administrators are \fBstrongly\fP
49 urged to use \fIxdm\fP, or build other interfaces for novice users.
51 The X server may also be started directly by the user, though this
52 method is usually reserved for testing and is not recommended for
53 normal operation. On some platforms, the user must have special
54 permission to start the X server, often because access to certain
55 devices (e.g. /dev/mouse) is restricted.
57 When the X server starts up, it typically takes over the display. If
58 you are running on a workstation whose console is the display, you may
59 not be able to log into the console while the server is running.
61 All of the X servers accept the following command line options:
63 .B :\fIdisplaynumber\fP
64 the X server runs as the given \fIdisplaynumber\fP, which by default is 0.
65 If multiple X servers are to run simultaneously on a host, each must have
66 a unique display number. See the DISPLAY
67 NAMES section of the \fIX(1)\fP manual page to learn how to specify
68 which display number clients should try to use.
71 sets pointer acceleration (i.e. the ratio of how much is reported to how much
72 the user actually moved the pointer).
75 disables host-based access control mechanisms. Enables access by any host,
76 and permits any host to modify the access control list.
77 Use with extreme caution.
78 This option exists primarily for running test suites remotely.
80 .B \-audit \fIlevel\fP
81 Sets the audit trail level. The default level is 1, meaning only connection
82 rejections are reported. Level 2 additionally reports all successful
83 connections and disconnects. Level 4 enables messages from the
84 SECURITY extension, if present, including generation and revocation of
85 authorizations and violations of the security policy.
86 Level 0 turns off the audit trail.
87 Audit lines are sent as standard error output.
89 .B \-auth \fIauthorization-file\fP
90 Specifies a file which contains a collection of authorization records used
91 to authenticate access. See also the \fIxdm\fP and \fIXsecurity\fP manual
95 disables certain kinds of error checking, for bug compatibility with
96 previous releases (e.g., to work around bugs in R2 and R3 xterms and toolkits).
100 disables backing store support on all screens.
106 sets key-click volume (allowable range: 0-100).
109 sets the visual class for the root window of color screens.
110 The class numbers are as specified in the X protocol.
111 Not obeyed by all servers.
113 .B \-co \fIfilename\fP
114 sets name of RGB color database. The default is <XRoot>/lib/X11/rgb,
115 where <XRoot> refers to the root of the X11 install tree.
118 .B \-config \fIfilename\fP
119 reads more options from the given file. Options in the file may be separated
120 by newlines if desired. If a '#' character appears on a line, all characters
121 between it and the next newline are ignored, providing a simple commenting
122 facility. The \fB\-config\fP option itself may appear in the file.
126 causes the server to generate a core dump on fatal errors.
128 .B \-dpi \fIresolution\fP
129 sets the resolution of the screen, in dots per inch.
130 To be used when the server cannot determine the screen size from the hardware.
133 Enable DPMS (when supported).
138 .B \-deferglyphs \fIwhichfonts\fP
139 specifies the types of fonts for which the server should attempt to use
140 deferred glyph loading. \fIwhichfonts\fP can be all (all fonts),
141 none (no fonts), or 16 (16 bit fonts only).
144 sets feep (bell) volume (allowable range: 0-100).
146 .B \-fc \fIcursorFont\fP
147 sets default cursor font.
150 sets the default font.
152 .B \-fp \fIfontPath\fP
153 sets the search path for fonts. This path is a comma separated list
154 of directories which the X server searches for font databases.
157 prints a usage message.
160 causes all remaining command line arguments to be ignored.
163 disables the XKEYBOARD extension if present.
165 .B \-nolisten \fItrans-type\fP
166 Disable a transport type. For example, TCP/IP connections can be disabled
171 Disable the use of an X server lock file.
174 sets screen-saver pattern cycle time in minutes.
177 permits the server to continue running if it fails to establish all of
178 its well-known sockets (connection points for clients), but
179 establishes at least one.
182 turns off auto-repeat.
185 turns on auto-repeat.
188 sets screen-saver timeout time in minutes.
191 disables save under support on all screens.
194 sets pointer acceleration threshold in pixels (i.e. after how many pixels
195 pointer acceleration should take effect).
198 causes the server to terminate at server reset, instead of continuing to run.
200 .B \-to \fIseconds\fP
201 sets default connection timeout in seconds.
204 disables all testing extensions (e.g., XTEST, XTrap, XTestExtension1, RECORD).
207 ignored, for servers started the ancient way (from init).
210 sets video-off screen-saver preference.
213 sets video-on screen-saver preference.
216 forces the default backing-store of all windows to be WhenMapped. This
217 is a backdoor way of getting backing-store to apply to all windows.
218 Although all mapped windows will have backing store, the backing store
219 attribute value reported by the server for a window will be the last
220 value established by a client. If it has never been set by a client,
221 the server will report the default value, NotUseful. This behavior is
222 required by the X protocol, which allows the server to exceed the
223 client's backing store expectations but does not provide a way to tell
224 the client that it is doing so.
226 .B \-x \fIextension\fP
227 loads the specified extension at init.
228 This is a no-op for most implementations.
229 .SH SERVER DEPENDENT OPTIONS
230 Some X servers accept the following options:
232 .B \-ld \fIkilobytes\fP
233 sets the data space limit of the server to the specified number of kilobytes.
234 A value of zero makes the data size as large as possible. The default value
235 of \-1 leaves the data space limit unchanged.
238 sets the number-of-open-files limit of the server to the specified number.
239 A value of zero makes the limit as large as possible. The default value
240 of \-1 leaves the limit unchanged.
242 .B \-ls \fIkilobytes\fP
243 sets the stack space limit of the server to the specified number of kilobytes.
244 A value of zero makes the stack size as large as possible. The default value
245 of \-1 leaves the stack space limit unchanged.
248 turns on the X Window System logo display in the screen-saver.
249 There is currently no way to change this from a client.
252 turns off the X Window System logo display in the screen-saver.
253 There is currently no way to change this from a client.
255 X servers that support XDMCP have the following options.
256 See the \fIX Display Manager Control Protocol\fP specification for more
259 .B \-query \fIhost-name\fP
260 Enable XDMCP and send Query packets to the specified host.
263 Enable XDMCP and broadcast BroadcastQuery packets to the network. The
264 first responding display manager will be chosen for the session.
266 .B \-indirect \fIhost-name\fP
267 Enable XDMCP and send IndirectQuery packets to the specified host.
269 .B \-port \fIport-num\fP
270 Use an alternate port number for XDMCP packets. Must be specified before
271 any \-query, \-broadcast or \-indirect options.
273 .B \-class \fIdisplay-class\fP
274 XDMCP has an additional display qualifier used in resource lookup for
275 display-specific options. This option sets that value, by default it
276 is "MIT-Unspecified" (not a very useful value).
278 .B \-cookie \fIxdm-auth-bits\fP
279 When testing XDM-AUTHENTICATION-1, a private key is shared between the
280 server and the manager. This option sets the value of that private
281 data (not that it is very private, being on the command line!).
283 .B \-displayID \fIdisplay-id\fP
284 Yet another XDMCP specific value, this one allows the display manager to
285 identify each display so that it can locate the shared key.
286 .SH XKEYBOARD OPTIONS
287 X servers that support the XKEYBOARD extension accept the following options:
290 .B \-xkbdir \fIdirectory\fP
291 base directory for keyboard layout files
294 .B \-xkbmap \fIfilename\fP
295 keyboard description to load on startup
298 enable(+) or disable(-) AccessX key sequences
300 .B \-ar1 \fImilliseconds\fP
301 sets the length of time in milliseconds that a key must be depressed before
304 .B \-ar2 \fImilliseconds\fP
305 sets the length of time in milliseconds that should elapse between
306 autorepeat-generated keystrokes
308 Many servers also have device-specific command line options. See the
309 manual pages for the individual servers for more details.
310 .SH SECURITY EXTENSION OPTIONS
311 X servers that support the SECURITY extension accept the following option:
313 .B \-sp \fIfilename\fP
315 the server to attempt to read and interpret filename as a security policy
316 file with the format described below. The file is read at
317 server startup and reread at each server reset.
319 The syntax of the security policy file is as follows.
320 Notation: "*" means zero or more occurrences of the preceding element,
321 and "+" means one or more occurrences. To interpret <foo/bar>, ignore
322 the text after the /; it is used to distinguish between instances of
323 <foo> in the next section.
326 <policy file> ::= <version line> <other line>*
328 <version line> ::= <string/v> '\en'
330 <other line > ::= <comment> | <access rule> | <site policy> | <blank line>
332 <comment> ::= # <not newline>* '\en'
334 <blank line> ::= <space> '\en'
336 <site policy> ::= sitepolicy <string/sp> '\en'
338 <access rule> ::= property <property/ar> <window> <perms> '\en'
340 <property> ::= <string>
342 <window> ::= any | root | <required property>
344 <required property> ::= <property/rp> | <property with value>
346 <property with value> ::= <property/rpv> = <string/rv>
348 <perms> ::= [ <operation> | <action> | <space> ]*
350 <operation> ::= r | w | d
352 <action> ::= a | i | e
354 <string> ::= <dbl quoted string> | <single quoted string> | <unqouted string>
356 <dbl quoted string> ::= <space> " <not dqoute>* " <space>
358 <single quoted string> ::= <space> ' <not squote>* ' <space>
360 <unquoted string> ::= <space> <not space>+ <space>
362 <space> ::= [ ' ' | '\et' ]*
366 <not newline> ::= any character except '\en'
367 <not dqoute> ::= any character except "
368 <not squote> ::= any character except '
369 <not space> ::= any character except those in <space>
372 The semantics associated with the above syntax are as follows.
374 <version line>, the first line in the file, specifies the file format
375 version. If the server does not recognize the version <string/v>, it
376 ignores the rest of the file. The version string for the file format
377 described here is "version-1" .
379 Once past the <version line>, lines that do not match the above syntax
382 <comment> lines are ignored.
384 <sitepolicy> lines are currently ignored. They are intended to
385 specify the site policies used by the XC-QUERY-SECURITY-1
386 authorization method.
388 <access rule> lines specify how the server should react to untrusted
389 client requests that affect the X Window property named <property/ar>.
390 The rest of this section describes the interpretation of an
393 For an <access rule> to apply to a given instance of <property/ar>,
394 <property/ar> must be on a window that is in the set of windows
395 specified by <window>. If <window> is any, the rule applies to
396 <property/ar> on any window. If <window> is root, the rule applies to
397 <property/ar> only on root windows.
399 If <window> is <required property>, the following apply. If <required
400 property> is a <property/rp>, the rule applies when the window also
401 has that <property/rp>, regardless of its value. If <required
402 property> is a <property with value>, <property/rpv> must also have
403 the value specified by <string/rv>. In this case, the property must
404 have type STRING and format 8, and should contain one or more
405 null-terminated strings. If any of the strings match <string/rv>, the
408 The definition of string matching is simple case-sensitive string
409 comparison with one elaboration: the occurence of the character '*' in
410 <string/rv> is a wildcard meaning "any string." A <string/rv> can
411 contain multiple wildcards anywhere in the string. For example, "x*"
412 matches strings that begin with x, "*x" matches strings that end with
413 x, "*x*" matches strings containing x, and "x*y*" matches strings that
414 start with x and subsequently contain y.
416 There may be multiple <access rule> lines for a given <property/ar>.
417 The rules are tested in the order that they appear in the file. The
418 first rule that applies is used.
420 <perms> specify operations that untrusted clients may attempt, and
421 the actions that the server should take in response to those operations.
423 <operation> can be r (read), w (write), or d (delete). The following
424 table shows how X Protocol property requests map to these operations
425 in the X Consortium server implementation.
428 GetProperty r, or r and d if delete = True
430 RotateProperties r and w
432 ListProperties none, untrusted clients can always list all properties
435 <action> can be a (allow), i (ignore), or e (error). Allow means
436 execute the request as if it had been issued by a trusted client.
437 Ignore means treat the request as a no-op. In the case of
438 GetProperty, ignore means return an empty property value if the
439 property exists, regardless of its actual value. Error means do not
440 execute the request and return a BadAtom error with the atom set to
441 the property name. Error is the default action for all properties,
442 including those not listed in the security policy file.
444 An <action> applies to all <operation>s that follow it, until the next
445 <action> is encountered. Thus, irwad means ignore read and write,
448 GetProperty and RotateProperties may do multiple operations (r and d,
449 or r and w). If different actions apply to the operations, the most
450 severe action is applied to the whole request; there is no partial
451 request execution. The severity ordering is: allow < ignore < error.
452 Thus, if the <perms> for a property are ired (ignore read, error
453 delete), and an untrusted client attempts GetProperty on that property
454 with delete = True, an error is returned, but the property value is
455 not. Similarly, if any of the properties in a RotateProperties do not
456 allow both read and write, an error is returned without changing any
459 Here is an example security policy file.
465 # Allow reading of application resources, but not writing.
466 property RESOURCE_MANAGER root ar iw
467 property SCREEN_RESOURCES root ar iw
469 # Ignore attempts to use cut buffers. Giving errors causes apps to crash,
470 # and allowing access may give away too much information.
471 property CUT_BUFFER0 root irw
472 property CUT_BUFFER1 root irw
473 property CUT_BUFFER2 root irw
474 property CUT_BUFFER3 root irw
475 property CUT_BUFFER4 root irw
476 property CUT_BUFFER5 root irw
477 property CUT_BUFFER6 root irw
478 property CUT_BUFFER7 root irw
480 # If you are using Motif, you probably want these.
481 property _MOTIF_DEFAULT_BINDINGS root ar iw
482 property _MOTIF_DRAG_WINDOW root ar iw
483 property _MOTIF_DRAG_TARGETS any ar iw
484 property _MOTIF_DRAG_ATOMS any ar iw
485 property _MOTIF_DRAG_ATOM_PAIRS any ar iw
487 # The next two rules let xwininfo -tree work when untrusted.
488 property WM_NAME any ar
490 # Allow read of WM_CLASS, but only for windows with WM_NAME.
491 # This might be more restrictive than necessary, but demonstrates
492 # the <required property> facility, and is also an attempt to
493 # say "top level windows only."
494 property WM_CLASS WM_NAME ar
496 # These next three let xlsclients work untrusted. Think carefully
497 # before including these; giving away the client machine name and command
498 # may be exposing too much.
499 property WM_STATE WM_NAME ar
500 property WM_CLIENT_MACHINE WM_NAME ar
501 property WM_COMMAND WM_NAME ar
503 # To let untrusted clients use the standard colormaps created by
504 # xstdcmap, include these lines.
505 property RGB_DEFAULT_MAP root ar
506 property RGB_BEST_MAP root ar
507 property RGB_RED_MAP root ar
508 property RGB_GREEN_MAP root ar
509 property RGB_BLUE_MAP root ar
510 property RGB_GRAY_MAP root ar
512 # To let untrusted clients use the color management database created
513 # by xcmsdb, include these lines.
514 property XDCCC_LINEAR_RGB_CORRECTION root ar
515 property XDCCC_LINEAR_RGB_MATRICES root ar
516 property XDCCC_GRAY_SCREENWHITEPOINT root ar
517 property XDCCC_GRAY_CORRECTION root ar
519 # To let untrusted clients use the overlay visuals that many vendors
520 # support, include this line.
521 property SERVER_OVERLAY_VISUALS root ar
523 # Dumb examples to show other capabilities.
525 # oddball property names and explicit specification of error conditions
526 property "property with spaces" 'property with "' aw er ed
528 # Allow deletion of Woo-Hoo if window also has property OhBoy with value
529 # ending in "son". Reads and writes will cause an error.
530 property Woo-Hoo OhBoy = "*son" ad
533 .SH "NETWORK CONNECTIONS"
534 The X server supports client connections via a platform-dependent subset of
535 the following transport types: TCP\/IP, Unix Domain sockets, DECnet,
536 and several varieties of SVR4 local connections. See the DISPLAY
537 NAMES section of the \fIX(1)\fP manual page to learn how to specify
538 which transport type clients should try to use.
540 The X server implements a platform-dependent subset of the following
541 authorization protocols: MIT-MAGIC-COOKIE-1, XDM-AUTHORIZATION-1,
542 SUN-DES-1, and MIT-KERBEROS-5. See the \fIXsecurity(1)\fP manual page
543 for information on the operation of these protocols.
545 Authorization data required by the above protocols is passed to the
546 server in a private file named with the \fB\-auth\fP command line
547 option. Each time the server is about to accept the first connection
548 after a reset (or when the server is starting), it reads this file.
549 If this file contains any authorization records, the local host is not
550 automatically allowed access to the server, and only clients which
551 send one of the authorization records contained in the file in the
552 connection setup information will be allowed access. See the
553 \fIXau\fP manual page for a description of the binary format of this
554 file. See \fIxauth(1)\fP for maintenance of this file, and distribution
555 of its contents to remote hosts.
557 The X server also uses a host-based access control list for deciding
558 whether or not to accept connections from clients on a particular machine.
559 If no other authorization mechanism is being used,
560 this list initially consists of the host on which the server is running as
561 well as any machines listed in the file \fI/etc/X\fBn\fI.hosts\fR, where
562 \fBn\fP is the display number of the server. Each line of the file should
563 contain either an Internet hostname (e.g. expo.lcs.mit.edu) or a DECnet
564 hostname in double colon format (e.g. hydra::). There should be no leading
565 or trailing spaces on any lines. For example:
570 corporate.company.com
576 Users can add or remove hosts from this list and enable or disable access
577 control using the \fIxhost\fP command from the same machine as the server.
579 The X protocol intrinsically does not have any notion of window operation
580 permissions or place any restrictions on what a client can do; if a program can
581 connect to a display, it has full run of the screen.
582 X servers that support the SECURITY extension fare better because clients
583 can be designated untrusted via the authorization they use to connect; see
584 the \fIxauth(1)\fP manual page for details. Restrictions are imposed
585 on untrusted clients that curtail the mischief they can do. See the SECURITY
586 extension specification for a complete list of these restrictions.
588 Sites that have better
589 authentication and authorization systems might wish to make
590 use of the hooks in the libraries and the server to provide additional
593 The X server attaches special meaning to the following signals:
596 This signal causes the server to close all existing connections, free all
597 resources, and restore all defaults. It is sent by the display manager
598 whenever the main user's main application (usually an \fIxterm\fP or window
599 manager) exits to force the server to clean up and prepare for the next
603 This signal causes the server to exit cleanly.
606 This signal is used quite differently from either of the above. When the
607 server starts, it checks to see if it has inherited SIGUSR1 as SIG_IGN
608 instead of the usual SIG_DFL. In this case, the server sends a SIGUSR1 to
609 its parent process after it has set up the various connection schemes.
610 \fIXdm\fP uses this feature to recognize when connecting to the server
614 can obtain fonts from directories and/or from font servers.
615 The list of directories and font servers
616 the X server uses when trying to open a font is controlled
617 by the \fIfont path\fP.
619 The default font path is
620 "<XRoot>/lib/X11/fonts/misc/,
621 <XRoot>/lib/X11/fonts/Speedo/,
622 <XRoot>/lib/X11/fonts/Type1/,
623 <XRoot>/lib/X11/fonts/75dpi/,
624 <XRoot>/lib/X11/fonts/100dpi/" .
625 where <XRoot> refers to the root of the X11 install tree.
627 The font path can be set with the \fB\-fp\fP option or by \fIxset(1)\fP
628 after the server has started.
632 Initial access control list for display number \fBn\fP
634 <XRoot>/lib/X11/fonts/misc, <XRoot>/lib/X11/fonts/75dpi, <XRoot>/lib/X11/fonts/100dpi
635 Bitmap font directories
637 <XRoot>/lib/X11/fonts/Speedo, <XRoot>/lib/X11/fonts/Type1
638 Outline font directories
640 <XRoot>/lib/X11/fonts/PEX
643 <XRoot>/lib/X11/rgb.txt
646 /tmp/.X11-unix/X\fBn\fP
647 Unix domain socket for display number \fBn\fP
650 Kerberos 5 replay cache for display number \fBn\fP
652 /usr/adm/X\fBn\fPmsgs
653 Error log file for display number \fBn\fP if run from \fIinit(8)\fP
655 <XRoot>/lib/X11/xdm/xdm-errors
656 Default error log file if the server is run from \fIxdm(1)\fP
658 Note: <XRoot> refers to the root of the X11 install tree.
660 General information: X(1)
663 .I "X Window System Protocol,"
664 .I "The X Font Service Protocol,"
665 .I "X Display Manager Control Protocol"
667 Fonts: bdftopcf(1), mkfontdir(1), xfs(1), xlsfonts(1), xfontsel(1), xfd(1),
668 .I "X Logical Font Description Conventions"
670 Security: Xsecurity(1), xauth(1), Xau(1), xdm(1), xhost(1),
671 .I "Security Extension Specification"
673 Starting the server: xdm(1), xinit(1)
675 Controlling the server once started: xset(1), xsetroot(1), xhost(1)
677 Server-specific man pages:
678 Xdec(1), XmacII(1), Xsun(1), Xnest(1), Xvfb(1),
679 XF86_Accel(1), XF86_Mono(1), XF86_SVGA(1), XF86_VGA16(1), XFree86(1)
681 Server internal documentation:
682 .I "Definition of the Porting Layer for the X v11 Sample Server"
684 The sample server was originally written by Susan Angebranndt, Raymond
685 Drewry, Philip Karlton, and Todd Newman, from Digital Equipment
686 Corporation, with support from a large cast. It has since been
687 extensively rewritten by Keith Packard and Bob Scheifler, from MIT.
688 Dave Wiggins took over post-R5 and made substantial improvements.
projects / rdpsrv / blob