Volume Eight X Window System Admi n " s trator 's Guide for X11 Release 4 and Release 5 by Linda Mui and Eric Pearce O'Reilly & Associates, Inc. X Window System Administrator's Guide Books That Help Peo Get More Out of Computers X Protocol Reference Manual, 516 pages Describes the X Network Protocol which underlies all software for Version l l of the X Window System. Xlib Programming Manual, 824 pages Xlib Reference Manual, 1144 pages Complete programming and reference guides to the X library (Xlib), the lowest level of programming interface to X. X Window System User's Guide Orients the new user to window system concepts, provides detailed tutorials for many client programs, and explains how to customize the X environment. Standard Edition, 752 pages Motif Edition, 734 pages X Toolkit Intrinsics Programming Manual Complete guide to programming with Xt Intrinsics, the library of C language routines that facilitate the design of user interfaces, with reusable components called widgets. Standard Edition, 624 pages Motif Edition, 714 pages X Toolkit Intrinsics Reference Manual, 918 pages Complete programmer's reference for the X Toolkit. Motif Programming Manual, 1042 pages Complete guide to programming for the Motif graphical user interface. gView Programming Manual, 798 pages XView Reference Manual, 292 pages Complete information on programming with XView, an easy-to-use toolkit that is widely available The g Window System in a Nutshell, 3ao pages A single-volume quick reference that is an indispensable companion to the series. Contact us for a catalog of our books, for orders, or for more information. O'Reilly & Associates, Inc. 103 Morris Street, Suite A, Sebastopol CA 95472 (800) 998-9938 US/Canada 707-829-0515 overseas/local 707-829-0104 Fax Volume Eight X Window System Administrator's Guide for X Version 11 By Linda Mui and Eric Pearce O'Reilly & Associates, Inc. Table of Contents Page Preface ................................................................................................................................... xix How to Use this Book ................................................................................................................. xix Assumptions ................................................................................................................................ xxi Related Documents ..................................................................................................................... xxi Font Conventions Used in This Book ...................................................................................... xxii Request for Comments ............................................................................................................. xxiii Bulk Sales Information ............................................................................................................ xxiii Acknowledgments .................................................................................................................... xxiii Chapter 1 An Introduction to X Administration ................................................. 3 1.1 The Design of X 11 .................................................................................................................. 3 1.1.1 Display Servers ................................................................................................................ 4 1.1.2 Clients and Resources ..................................................................................................... 6 1.1.3 Toolkits and GUIs ............................................................................................................ 7 1.2 X Administration ..................................................................................................................... 8 1.2.1 Installing X ....................................................................................................................... 8 1.2.2 Supporting Users ............................................................................................................. 9 1.2.3 Maintaining Software ...................................................................................................... 9 1.2.4 Maintaining Multiple Machines ................................................................................... 10 1.2.5 A "'Philosophy" of X Administration ........................................................................... 10 Chapter 2 The X User Environment ........................................................................ 13 2.1 The Configured X Session ................................................................................................... 13 2.1.1 The Twilight Zone ......................................................................................................... 16 2.2 Components of the X Environment ..................................................................................... 18 2.2.1 Window Managers ......................................................................................................... 18 2.2.2 Customizing Clients ...................................................................................................... 20 2.2.2.1 The -fn Command-line Option ................................................................................ 20 2.2.2.2 The -geometry Command-line Option .................................................................... 20 2.2.2.3 Specifying Colors ..................................................................................................... 23 2.2.2.4 Using Resources ....................................................................................................... 24 2.2.3 The Startup Script .......................................................................................................... 25 2.2.3.1 The Foreground Process ........................................................................................... 26 2.3 The Shell Environment ......................................................................................................... 27 2.3.1 Setting the DISPLAY Variable .................................................................................... 27 2.3.1.1 Complications with Display Names ........................................................................ 28 2.3.2 Redefining the Search Path ........................................................................................... 29 2.3.2.1 Setting the Search Path for OpenWindows Support .............................................. 30 2.3.2.2 Setting the Search Path for Mixed Environments .................................................. 30 2.3.3 xterm Issues .................................................................................................................... 31 2.3.3.1 xterm and Terminal Emulation ................................................................................ 31 2.3.3.2 The resize Client ....................................................................................................... 31 2.3.3.3 xterm and the Login Shell (C Shell) ....................................................................... 33 2.3.4 Starting Remote Clients ................................................................................................ 34 2.3.4.1 Starting a Remote Client with rsh ........................................................................... 35 2.4 Startup Methods .................................................................................................................... 37 2.4.1 xinit and startx ............................................................................................................... 38 2.4.2 Differences Between .xinitrc and .xsession ................................................................. 39 2.5 Related Documentation ........................................................................................................ 39 Chapter 3 The X Display Manager ........................................................................... 43 3.1 xdm Concepts ........................................................................................................................ 44 3.2 xdm Configuration Files ...................................................................................................... 46 3.3 xdm the Easy Way ................................................................................................................ 48 3.4 Troubleshooting xdm ............................................................................................................ 49 3.5 Customizing xdm .................................................................................................................. 51 3.5.1 The Master Configuration File (xdm-config) .............................................................. 51 3.5.2 Listing X Servers (the Xservers File) ........................................................................... 53 3.5.2.1 Xservers Syntax ........................................................................................................ 53 3.5.3 xdm Host Access Control: the Xaccess File (R5 Only) .............................................. 55 3.5.3.1 Direct and Broadcast Access ................................................................................... 56 3.5.3.2 Indirect Access and the Chooser ............................................................................. 57 3.5.3.3 Using Macros ............................................................................................................ 59 3.5.3.4 Advantages and Disadvantages of the Chooser ..................................................... 59 3.5.4 The Xresources File ....................................................................................................... 60 3.5.4.1 Configuring the Login Box ...................................................................................... 60 3.5.4.2 The xconsole Client .................................................................................................. 62 3.5.5 Starting Up Individual X Sessions (the Xsession File) ............................................... 63 3.5.5.1 No Home Directory? (R5) ....................................................................................... 64 3.5.6 Display Classes .............................................................................................................. 65 3.6 Testing Your xdm Setup ....................................................................................................... 66 3.6.1 Resetting the Keyboard ................................................................................................. 67 3.6.2 Restarting xdm Using xdm-pid (R4 and Later) ........................................................... 68 3.6.3 Rereading xdm Configuration Files (R3) .................................................................... 68 3.7 Permanent Installation of xdm ............................................................................................. 69 3.8 Related Documentation ........................................................................................................ 70 Chapter 4 Security ............................................................................................................ 73 4.1 Host-based Access Control .................................................................................................. 74 4.1.1 The/etc/Xn.hosts File ................................................................................................... 74 4.1.2 The xhost Client ............................................................................................................. 75 4.1.3 Problems with Host-based Access Control .................................................................. 76 4.2 Access Control with MIT-MAGIC-COOKIE-1 ...................................................................... 77 4.2.1 Using MIT-MAGIC-COOKIE-1 with xdm ...................................................................... 78 4.2.2 The xauth Program ........................................................................................................ 79 4.2.3 Using MIT-MAGIC-COOKIE-1 with xinit ..................................................................... 81 4.2.4 xauth vs. xhost ............................................................................................................... 82 4.3 The XDM-AUTHORIZATION-1 Mechanism (RS) ............................................................... 83 4.4 The SUN-DES-1 Mechanism (R5) ........................................................................................ 84 4.4.1 Public Key Encryption .................................................................................................. 85 4.4.2 Prerequisites for Using SUN-DES-1 .............................................................................. 86 4.4.3 Using SUN-DES-I with xdm .......................................................................................... 88 4.4.4 Using SUN-DES-1 with xinit ......................................................................................... 89 4.4.5 Adding Another User with SUN-DES-1 ........................................................................ 91 4.4.6 xterm and SUN-DES-1 .................................................................................................... 92 4.4.7 Troubleshooting SUN-DES-I ......................................................................................... 92 4.5 xterm and Secure Keyboard ................................................................................................. 93 4.6 Other Security Issues ............................................................................................................ 94 4.6.1 The Console xterm (R4 and Earlier) ............................................................................ 94 4.6.2 The Console and xdm (R5) ........................................................................................... 95 4.6.3 Hanging the Server Remotely (R3) .............................................................................. 96 4.6.4 Reading the Framebuffer (Sun Workstations) ............................................................. 96 4.6.5 Removing Files in/tmp ................................................................................................. 97 4.6.6 The Network Design ..................................................................................................... 97 4.7 Related Documentation ........................................................................................................ 98 Chapter 5 Font Management .................................................................................... 101 5.1 Fonts on the X Window System ........................................................................................ 101 5.1.1 xlsfonts ......................................................................................................................... 103 5.1.2 xfd ................................................................................................................................. 103 5.1.3 xfontsel ......................................................................................................................... 104 5.1.4 The Font Path ............................................................................................................... 105 5.1.5 The Font Directory File .............................................................................................. 106 5.1.6 The fonts.scale File (R5 only) .................................................................................... 107 5.1.7 Wildcards ..................................................................................................................... 108 5.1.8 Aliases .......................................................................................................................... 108 5.1.8.1 The FILE_NAMES_ALIAS Alias ............................................................................ 109 5.2 All About Fonts .................................................................................................................. 110 5.2.1 Bitmap Versus Outline Fonts ...................................................................................... 110 5.2.2 Font Formats ................................................................................................................ 111 5.2.3 Format Conversion Tools ............................................................................................ 112 5.3 Adding New Fonts .............................................................................................................. 114 5.3.1 Adding a Single Font .................................................................................................. 114 5.3.2 Adding Multiple Fonts ................................................................................................ 115 5.3.2.1 Multiple Font Example .......................................................................................... 116 5.3.3 Problems with Running Vendor-specific Clients ...................................................... 117 5.3.4 DECWindows Examples ............................................................................................. 118 5.3.4.1 Aliasing ................................................................................................................... 119 5.3.4.2 DECWindows Conversion ..................................................................................... 120 5.3.5 AIXWindows Example ............................................................................................... 121 5.3.6 OpenWindows Example ............................................................................................. 123 5.3.6.1 Aliasing ................................................................................................................... 124 5.3.6.2 OpenWindows Conversion .................................................................................... 125 5.3.6.3 Converting from X11/NeWS to PCF or SNF ....................................................... 125 5.3.6.4 More Conversions .................................................................................................. 126 5.4 Providing Fonts Over the Network ................................................................................... 127 5.5 The R5 Font Server ............................................................................................................ 127 5.5.1 The Configuration File ................................................................................................ 128 5.5.2 Installing the Font Server ............................................................................................ 130 5.5.2.1 Testing By Hand ..................................................................................................... 131 5.5.2.2 Changing BSD Boot Files ..................................................................................... 131 5.5.2.3 Changing System V Boot Files ............................................................................. 132 5.5.2.4 Changing AIX Boot Files ...................................................................................... 133 5.5.3 Font Server Name Syntax ........................................................................................... 133 5.5.4 Debugging the Font Server ......................................................................................... 134 5.5.5 Font Server Clients ...................................................................................................... 135 5.5.6 The Font Path and the Font Server ............................................................................. 136 5.5.7 Hostname Aliases ........................................................................................................ 138 5.5.8 A Font Server Example ............................................................................................... 138 5.6 Related Documentation ...................................................................................................... 140 Chapter 6 Color ............................................................................................................... 143 6.1 Color Specification in Release 4 and Earlier ................................................................... 144 6.1.1 RGB Color Names ....................................................................................................... 144 6.1.2 Numeric Color Values ................................................................................................. 145 6.1.3 Adding Your Own Color Names (RGB) .................................................................... 146 6.1.4 Fixing a Corrupted Color Database ........................................................................... 147 6.2 Color Specification in Release 5 (Xcms) ......................................................................... 147 6.2.1 Xcms Color Names ...................................................................................................... 148 6.2.2 Adding Your Own Color Names in Xcms ................................................................. 150 6.2.3 Xcms Database Example ............................................................................................ 151 6.2.4 Device Profiles ............................................................................................................ 152 6.3 Related Documentation ...................................................................................................... 153 Chapter 7 X Terminals ................................................................................................. 157 7.1 Buying an X Terminal: What's What ................................................................................ 157 7.1.1 Monitors ....................................................................................................................... 157 7.1.1.1 Screen Size .............................................................................................................. 158 7.1.1.2 Resolution ............................................................................................................... 158 7.1.1.3 Depth ....................................................................................................................... 159 7.1.1.4 Refresh Rate ........................................................................................................... 159 7.1.2 Keyboard and Mouse .................................................................................................. 159 7.1.3 X Server Software ....................................................................................................... 160 7.1.4 Special Features ........................................................................................................... 16 l 7.1.5 Memory Configuration ............................................................................................... 16 l 7.1.6 Network Interface ........................................................................................................ 162 7.2 X Terminal Setup ................................................................................................................ 163 7.3 Network Setup .................................................................................................................... 164 7.3.1 Getting the IP Address Using RARP ......................................................................... 165 7.3.2 Getting Information Using BOOTP ........................................................................... 165 7.3.3 Trivial File Transfer Protocol (TFTP) ........................................................................ 167 7.3.4 Setting Up the Network on the X Terminal ............................................................... 168 7.3.5 Debugging Hints .......................................................................................................... 168 7.3.5.1 Error Messages ....................................................................................................... 169 7.3.5.2 Updating the arp Table ........................................................................................... 169 7.3.5.3 Name Server Problems ........................................................................................... 169 7.4 Fonts on X Terminals ......................................................................................................... 170 7.4.1 Font Formats ................................................................................................................ 170 7.4.2 The Font Server (RS) ................................................................................................... 171 7.4.3 Choosing TFTP or NFS for Font Access ................................................................... 171 7.4.3.1 Reading Fonts Using TFTP ................................................................................... 171 7.4.3.2 Reading Fonts Using NFS ..................................................................................... 172 7.5 Configuring for the X Display Manager ........................................................................... 173 7.5.1 Configuring the X Terminal for xdm ......................................................................... 173 7.5.2 Configuring an R5 Host .............................................................................................. 174 7.5.3 Configuring an R4 Host .............................................................................................. 174 7.5.4 Configuring xdm Without XDMCP ........................................................................... 174 7.5.5 Setting Up Server Access Control .............................................................................. 175 7.6 Remote Configuration of X Terminals .............................................................................. 175 7.6.1 Remote Configuration on NCD Terminals ................................................................ 176 7.6.2 Remote Configuration on Visual Terminals .............................................................. 177 7.6.3 Remote Configuration on Tektronix Terminals ........................................................ 178 7.7 Reconfiguring the Host ...................................................................................................... 178 7.7.1 Increasing the Number of Processes .......................................................................... 178 7.7.2 Increasing the Number of Pseudo-ttys ....................................................................... 179 7.7.3 Increasing the Amount of Swap Space ...................................................................... 180 7.7.3.1 Swapping to a File .................................................................................................. 180 7.7.3.2 Swapping to a Disk ................................................................................................ 180 7.8 Related Documentation ...................................................................................................... 181 Chapter 8 Building the X Window System ......................................................... 185 8.1 Installation Issues ............................................................................................................... 185 8.1.1 Should You Use MIT Source? .................................................................................... 185 8.1.2 Types of Vendor-supplied X Distributions ................................................................ 186 8.1.2.1 X from Your OS Vendor ........................................................................................ 187 8.1.2.2 X from a Third Party .............................................................................................. 187 8.1.3 X Source Code from MIT ........................................................................................... 188 8.1.4 Complete or Client-only Distribution? ...................................................................... 189 8.1.5 Installing Multiple X Releases ................................................................................... 189 8.2 Source Preparation ............................................................................................................. 191 8.2.1 Do You Have Enough Disk Space? ............................................................................ 191 8.2.2 Is Your Platform Supported? ...................................................................................... 192 8.2.3 Applying OS Patches .................................................................................................. 194 8.2.4 Applying X Patches ..................................................................................................... 194 8.2.5 Creating a Link Tree (Optional) ................................................................................. 196 8.3 Simplest Case Build ........................................................................................................... 197 8.4 Host Problems ..................................................................................................................... 198 8.4.1 Disk Space ................................................................................................................... 198 8.4.1. l Changing the trap Directory Using TMPDIR (Ultrix and HP-UX) .................... 199 8.4.1.2 Changing the trap Directory Using -temp (SunOS) ............................................. 200 8.4.2 Shared Library Installation (SunOS) ......................................................................... 200 8.4.3 NFS Installation ........................................................................................................... 201 8.4.3.1 NFS Installation Without Root Access ................................................................. 201 8.4.3.2 Installation Over the Network (rdist) .................................................................... 203 8.4.4 Installing the termcap or terminfo Definition for xterm ........................................... 203 8.5 Simple Configuration ......................................................................................................... 204 8.5.1 Configuration Parameters ........................................................................................... 205 8.5.1.1 site.def ..................................................................................................................... 205 8.5.1.2 The ProjectRoot Flag ............................................................................................. 207 8.5.1.3 The Platform Configuration File (platform.cf) .................................................... 208 8.5.2 Configuration Example 1 ............................................................................................ 210 8.5.3 Configuration Example 2 ............................................................................................ 211 8.5.4 Configuration Example 3 ............................................................................................ 212 8.5.5 Configuration Example 4 ............................................................................................ 212 8.5.6 Configuration Example 5 ............................................................................................ 213 8.5.7 Other Build Flags ........................................................................................................ 213 8.5.7.1 xterm Build Flags ................................................................................................... 214 8.6 Building Programs After X Is Installed ............................................................................ 214 8.6.1 xmkmf .......................................................................................................................... 214 8.6.2 Include Files ................................................................................................................. 215 8.6.3 Libraries ....................................................................................................................... 216 8.7 More About imake .............................................................................................................. 216 8.7.1 The make Program ...................................................................................................... 216 8.7.2 The C Preprocessor ..................................................................................................... 217 8.7.3 Imake Syntax ............................................................................................................... 219 8.7.3.1 Comments in imake ................................................................................................ 219 8.7.3.2 Multi-line Macros (@@) ....................................................................................... 220 8.7.3.3 Concatenating Macros ........................................................................................... 221 8.7.3.4 Dealing with Tabs ................................................................................................... 222 8.7.4 imake Configuration Files .......................................................................................... 222 8.7.4.1 A Quick Tour of Files Used by imake .................................................................. 223 8.7.5 Using imake to Build X11 .......................................................................................... 224 8.8 Porting Hints ....................................................................................................................... 226 8.8.1 Undefined Symbols or Functions ............................................................................... 226 8.8.1.1 Missing Header Files ............................................................................................. 226 8.8.1.2 Missing Function Definitions ................................................................................ 226 8.8.2 Searching for Preprocessor Symbols ......................................................................... 228 8.9 Related Documentation ...................................................................................................... 230 Appendix A Useful Things to Know ....................................................................... 233 A.1 The comp.windows.x Newsgroup .................................................................................... 233 A.2 How to ftp a File ................................................................................................................ 234 A.2.1 Getting Files Using ftpmail ....................................................................................... 235 A.2.2 BITFTP ........................................................................................................................ 237 A.3 The xstuff Mail Archive Server ........................................................................................ 237 A.4 Unpacking Files ................................................................................................................. 238 A.5 Making a Filesystem Available via NFS ......................................................................... 239 A.6 How to Add a Host ............................................................................................................ 239 A.6.1 Adding a Host to/etc/hosts ........................................................................................ 239 A.6.2 Adding a Host Using NIS .......................................................................................... 240 A.6.3 Adding a Host Using DNS ......................................................................................... 240 A.7 Adding an Ethernt Address ............................................................................................. 242 A.8 Printing Documentation in the MIT X Distribution ........................................................ 242 A.9 Converting a Number Into Hexadecimal and Back ........................................................ 243 A. 10 Configuring a Sun as an X terminal ............................................................................... 243 A. 11 Using More than One Frame Buffer Under SunOS ...................................................... 244 Appendix B Compiling Public Domain Software ............................................ 247 B. 1 Finding the Sources ........................................................................................................... 247 B.I.1 Using an Archie Server .............................................................................................. 248 B.1.2 Get the FAQ ................................................................................................................ 250 B.1.3 The Usual Suspects ..................................................................................................... 250 B.2 An Example: xarchie ......................................................................................................... 251 B.2.1 Getting the xarchie Sources ....................................................................................... 251 B.2.2 Untarring the Sources ................................................................................................. 252 B.2.3 Editing the Imakefile .................................................................................................. 254 B.2.4 Compiling the Source ................................................................................................. 255 B.3 Using Patches ..................................................................................................................... 259 B.4 Another Example: xkeycaps ............................................................................................. 264 B.5 Related Documentation ..................................................................................................... 268 Appendix C X on Non-UNIX Platforms .............................................................. 271 C. 1 X on DOS-based PCs ......................................................................................................... 272 C. 1.1 Requirements for PC X Servers ................................................................................. 272 C. 1.2 Installing and Configuring PC X Servers ................................................................. 273 C. 1.3 Problems Particular to PC X Servers ........................................................................ 274 C.2 X on Macintosh Computers .............................................................................................. 275 C.2.1 Macintosh-based X Servers ....................................................................................... 275 C.2.2 MacTCP and the Communications Toolbox ............................................................. 276 C.3 X on NeXT Computers ...................................................................................................... 277 Appendix D Resources and Keysym Mappings ................................................ 281 D. 1 Using Resources ................................................................................................................ 281 D. 1.1 Resource Definition Syntax ....................................................................................... 281 D. 1.1.1 Loose and Tight Bindings ..................................................................................... 282 D. 1.1.2 The -name Command-line Option ....................................................................... 283 D. 1.1.3 xterm Versus XTerm .............................................................................................. 283 D. 1.2 Where Resources Are Defined .................................................................................. 285 D. 1.3 Advantages of xrdb .................................................................................................... 287 D. 1.4 Translation Tables ....................................................................................................... 288 D.2 Defining Keys and Button Presses With xmodmap ........................................................ 290 D.2.1 Using xev to Learn Keysym Mappings ..................................................................... 292 D.3 Related Documentation ..................................................................................................... 293 Appendix E The Components of X Products ..................................................... 297 E. 1 MIT X 11 Release 5 ............................................................................................................ 298 E.2 OSF/Motif ........................................................................................................................... 299 E.3 Sun OpenWindows ............................................................................................................. 300 E.4 DECWindows ..................................................................................................................... 301 E.5 AIXWindows ...................................................................................................................... 302 E.6 Silicon Graphics ................................................................................................................. 302 E.7 A Guide to X 11 Libraries .................................................................................................. 303 Appendix F Getting Xll .............................................................................................. 307 F.1 Where Can I Get XI IR5? .................................................................................................. 307 F.2 Where Can I Get Patches to XI IR5? ................................................................................ 311 F.3 Where Can I Get X11R4? .................................................................................................. 311 Appendix G Error Messages ...................................................................................... 315 G. 1 X Errors .............................................................................................................................. 315 G.2 UNIX Errors ....................................................................................................................... 318 G.3 Compilation Errors ............................................................................................................ 320 x/// Figures Page 1-1 An X server with clients from multiple hosts ...................................................................... 5 2-1 A configured X session ....................................................................................................... 13 2-2 A root menu ......................................................................................................................... 14 2-3 An unconfigured X session ................................................................................................. 16 2-4 Starting a new client ........................................................................................................... 17 2-5 xclock window over xterm window ................................................................................... 17 2-6 Starting the window manager ............................................................................................. 19 2-7 xterm window with new font .............................................................................................. 21 2-8 A window with a specified geometry ................................................................................ 22 2-9 An xterm window in reverse video, decorated by twm .................................................... 23 2-10 vi using only part of a window ......................................................................................... 32 2-l 1 Logging in with xdm ......................................................................................................... 37 2-12 Starting the X server with xinit ........................................................................................ 38 3-1 xdm flow chart ..................................................................................................................... 44 3-2 3-3 3-4 3-5 3-6 3-7 3-8 3-9 4-1 4-2 4-3 4-4 5-1 5-2 5-3 5-4 5-5 5-6 5-7 5-8 6-1 6-2 6-3 8-1 8-2 8-3 8-4 B-I B-2 D-I Default xdm configuration files ......................................................................................... 46 xdm login box ...................................................................................................................... 48 Default xdm environment ................................................................................................... 49 XDMCP Direct, Indirect, and Broadcast queries ............................................................. 56 The chooser .......................................................................................................................... 58 An example chooser box .................................................................................................... 58 Chooser box with an R4 host .............................................................................................. 60 Adapted xlogin greeting ..................................................................................................... 62 Host-based access control ................................................................................................... 74 XDMCP and the access code ............................................................................................. 77 User-based access control ................................................................................................... 78 Propagating the magic cookie between two hosts ............................................................ 80 Components of a font name .............................................................................................. 102 xfd ....................................................................................................................................... 104 xfontsel ............................................................................................................................... 105 Font conversion utilities ................................................................................................... 113 dxcalendar with the wrong fonts ...................................................................................... 119 dxcalendar with aliases ..................................................................................................... 120 cm without aliases ............................................................................................................. 123 cm with aliases .................................................................................................................. 124 Red, green, and blue color guns ....................................................................................... 143 Xcms vs. RGB color specification ................................................................................... 149 xtici Edit menu .................................................................................................................. 150 oclock without the SHAPE extension ............................................................................. 190 oclock with the SHAPE extension ................................................................................... 190 Recursive make ................................................................................................................. 218 Files processed by imake .................................................................................................. 223 xarchie window ................................................................................................................ 258 xkeycaps window ............................................................................................................. 267 xcalc window .................................................................................................................... 289 xiv Tables Page 8-1 cpp Symbols ...................................................................................................................... 228 B-I Archie Servers as of January 3, 1992 .............................................................................. 248 E-1 X Distribution Directories ................................................................................................ 297 E-2 MIT X I I R5 Files .............................................................................................................. 298 E-3 Motif Files (Motif 1.1.x) .................................................................................................. 300 E-40penWindows Files (Sun4, SunOS 4.1.1) ...................................................................... 300 E-5 OPEN LOOK Files ........................................................................................................... 301 E-6 DECWindows Files (DecStation, Ultrix 4.7) ................................................................. 301 E-7 AIXWindows Files (RS/6000, AIX 3.2) ......................................................................... 302 E-8 Graphics X11 Files (Indigo, IRIX 4.0) ............................................................................ 302 1=-1 North America Anonymous tip ........................................................................................ 307 F-2 Europe/Middle East/Australia Anonymous tip .............................................................. 308 F-3 Japan Anonymous tip ....................................................................................................... 308 F-4 UUCP ................................................................................................................................. 309 F-5 Other File Transfer Methods ............................................................................................ 309 XV Preface This preface outlines who should be reading this book, and what readers should expect from it. In The Preface: How to Use this Book ............................................................................ xix Assumptions ......................................................................................... xxi Related Documents ............................................................................... xxi Font Conventions Used in This Book .................................................... xxii Request for Comments ........................................................................ xxiii Bulk Sales Information ......................................................................... xxiii Acknowledgments ................................................................................ xxiii Preface UNIX machines can be difficult to maintain. Traditionally, UNIX administration has meant juggling dozens of configuration files and supporting end users who may not understand how the system actually works. Because it is infinitely flexible, UNIX can be a power-user's para- dise and a beginner's nightmare, with the administrator sandwiched somewhere in between. This book is designed to bridge that gap. It provides detailed information and procedures for setting up a system that gives users access to the full power of X, without the headaches. How to Use this Book This book has been written to be useful to as many types of X Window System administrators as possible. Some readers are full-time system administrators at large academic sites who are well-versed in UNIX and X, but are always looking for new tips. Other readers are part-time administrators at smaller sites who know a good amount about UNIX and X but are tired of always having to reinvent the wheel. Still other readers are workstation owners who are forced to do their own administration, interested only in getting their system running smoothly. Since this book is aimed at such a wide audience, not all readers will be interested in every chapter. If we tell you about platforms you don't use, issues that aren't relevant to you, or describe basic concepts with more detail than you need, we hope that you'll be patient and just skim through to find what you need to know. Chapter 1, An Introduction to X Administration, briefly introduces the design of X, with emphasis on the administrative issues that arise out of that design. Beginners to X and X administration should read this chapter. Chapter 2, Chapter 3, Chapter 4, The X User Environment, describes issues for configuring the X user envi- ronment. Readers who need to set up new users should read this chapter. This chapter is also a good place for readers who are new to X and need to learn more about how it works from the user's point of view. The X Display Manager, describes the X Display Manager (xdm) and how to configure it. Readers who are interested in running xdm should read this chapter. Securi_', describes security issues for X. We recommend that managers of all networked X environments study this chapter. Preface xix Chapter 5, Chapter 6, Chapter 7, Chapter 8, Appendix A, Appendix B, Appendix C, Appendix D, Appendix E, Appendix F, Appendix G, Font Management, describes issues with using and adding fonts, both under the standard methods and through the X ll Release 5 font server. Readers who are interested in adding fonts to their system or using a networked font server should read this chapter. Color, describes how color works in X, and how to add new colors in both the RGB and Xcms color databases. Readers who have color displays may want to read this chapter to learn more about how color works and how it can be manipulated. X Terminals, describes the different types of X terminals, how to set up the network for new X terminals, how to install fonts on the host, and how to reconfigure the host machine to support more processes. If you use or intend to use X terminals at your site, you should read this chapter. Building the X Window System, describes the issues involved with building X from source. Readers who must build X from source, or who are inter- ested in understanding more about the basic structure of the X software should read this chapter. Useful Things to Know, documents various "miscellaneous" procedures and odds-and-ends that many users will already be familiar with, but which we want to include for the benefit of those users who are not. This appendix shows how to 32p files, how to export NFS directories, how to add a hostname to your name server, etc. Browse through this chapter at least once to see if there's anything new in there; throughout the book, we refer to sections of this chapter when applicable. Compiling Public Domain Software, a tutorial, describes how to find and compile public domain software. Readers who aren't familiar with this process should read this appendix. X Servers on Non-UNIX Platforms, briefly describes issues with using X1 1 servers on DOS-based PC and Apple Macintosh machines. Readers who are interested in running X on these platforms should read this appendix. Resources and Keysym Mappings, provides a more thorough description of resources and keysym mappings. You can't work with X without needing to understand these topics at least a little bit, so we include some back- ground here. Some of this material duplicates what you'll find in Volume Three, X Window System User's Guide, but we also give some useful tips and advanced information for administrators. So even if you are familiar with how to use resources, you may want to scan this appendix. The Components of X Products, lists the directory structure of MIT X 1 1 and various vendors' implementations. Use this appendix as needed. Getting XII, lists sites that have made the X1 1 source code available. Reprinted from the comp.windows.x newsgroup Frequently Asked Ques- tions list. Use this appendix if you need to obtain the X 1 1 source code. Error Messages, lists some of the error messages users may encounter. Refer to this appendix when troubleshooting. xx The X Window System Administrator's Guide Assumptions To get the most out of this book, you should be familiar with UNIX and with general princi- ples of system and network administration. If you have never administered a UNIX system or a TCP/IP network, see the Nutshell Handbooks Essential System Administration by /Eleen Frisch (O'Reilly & Associates, 1991) and TCP/IP Network Administration by Craig Hunt (O'Reilly & Associates, 1992). A firm understanding of X is helpful. If you have never used X, you should have a copy of Volume Three, X Window System User's Guide, close at hand. However, we have included a lot of background information on X for the benefit of readers who have not had a formal introduction to X. Readers are not expected to have any C programming experience, although UNIX shell pro- gramming experience may come in handy for understanding some of the examples. Readers are assumed to have the X manpages available, or to be able to obtain them easily. (These pages are reprinted in the X Window System User's GuMe and are also available online with many X distributions.) This book does not attempt to replace the X manpages Related Documents The following Nutshell Handbooks published by O'Reilly & Associates, Inc. may also be helpful: Managing Projects with make, by Andy Oram and Steve Talbott Managing NFS and NIS, by Hal Stern Practical UNIX Scurity, by Simson Garfinkel and Gene Spafford System Petformance Tuning, by Mike Loukides DNS and BIND, by Cricket Liu and Paul Albitz The Whole lnternet User's Guide and Catalog, by Ed Krol TCP/IP Network Administration, by Craig Hunt Several other books and a journal on the X Window System are available from O'Reilly & Associates, Inc.: Volume Volume Volume Volume Volume Volume Volume Volume Zero -- X Protocol Reference Manual One -- Xlib Programming Manual Two -- Xlib Reference Manual Three --X Window System User's Guide, Motif and Standard editions Four --X Toolkit lntrinsics Programming Manual, Motif and Standard editions Five --X Toolkit lntrinsics Reference Manual Six -- Motif Programming Manual Seven --XView Programming Manual Preface xx/ Request for Comments To help us provide you with the best documentation possible, please write to tell us about any flaws you find in this manual or how you think it could be improved. Our U.S. mail address, e-mail address, and phone numbers are as follows: O'Reilly & Associates, Inc. 103A Morris Street Sebastopol, CA 95472 800-998-9938 international + 1 707-829-05 ! 5 fax + 1 707-829-0104 UUCP: uunet!ora.com! nuts lnternet: nuts@ora.com Bulk Sales Information For information on volume discounts for bulk purchase, call O'Reilly & Associates, Inc. at 800-998-9938, or send e-mail to linda@ora.com (uunet!ora.com!linda). For companies requiring extensive customization of the book, source licensing terms are also available. Acknowledgments Though it might seem a logical addition to our X Window System series, we didn't think up this book on our own. It was a customer call that set the project in motion. Scott Hunter of Oracle called up to ask if we had anything on X administration in the works. We said we didn't, but that we thought it was a great idea. Scott and his co-worker Mike Riggs outlined for us the kinds of problems they were facing that made such a book a necessity. We would like to thank Scott and Mike for their initial efforts in conceiving the book, as well as Mary Beth Hagan and Marilyn Grady, who did some of the initial research and writing before it fell into our laps. We would also like to thank the technical reviewers for the first edition of this book. They were David Lewis: Jeffrey Vogel: Mike Braca of Visual Technology; Stephen Gildea of the X Consortium: Liam Quin and lan Darwin of Softquad, Inc.; Doug Klein, Dave Lemke, and the staff at Network Computing Devices; Dave Curry of Purdue University; Dinah McNutt of Tivoli Systems; Miles O'Neal of Pencom; Jim Frost of CenterLine Software; Jon Werner of International Business Machines; Spencer Murray of Silicon Graphics, Inc.: Joe llacqua: Valerie Quercia, David Flanagan and Adrian Nye of O'Reilly & Associates; A1 Tabayoyan of North Valley Research: and Upesh Patel of The Santa Cruz Operation. Our thanks to each of these reviewers for taking the time to make this book useful and com- plete. Additional thanks to David Tolman of Human Designed Systems and R. Lee Rainey of Tektronix for supplying information on their company's X terminals, and to Garry Paxinos of MetroLink, Inc. and Greg Mudge of PhoeniX Software Solutions for helping to clear up some Preface xxiii details about running X on PC hardware. Also, thanks to Dave Curry, Chris Calabrese of AT&T Bell Labs, Joe llacqua, and David Lewis for supplying random number generation methods for use with the discussion of MIT-MAGIC-COOKIE-I in Chapter 4. David Lewis was also kind enough to allow us to reprint the material in Appendix F from the cornp.win- dows.x Frequently Asked Questions list that he maintains. Several vendors were kind enough to lend us software or hardware for testing purposes. These were Silicon Graphics, Visual Technology, Human Designed Systems, Unipress Soft- ware, White Pine Software, Network Computing Devices, Locus Computing Corporation, Unipress Software, VisionWare Ltd., Quarterdeck Office Systems, FTP Software, Humming- bird Communications Ltd., and Stamet Communications. We would also like to thank those who worked on the production of the book. At O'Reilly & Associates, we would like to thank Gigi Estabrook for her initial copy-edit, Chris Reilley for the figures, Ellie Cutler for indexing, and Rosanne Wagger and Mike Sierra for production of the final copy. We would also like to thank Lenny Muellner for tools support and for allow- ing us to disrupt his life whenever we had the urge to make screendumps. Finally, we would like to thank our editor, Tim O'Reilly, for his initial trust in us and for his patience during the countless months it took us to put the book together. Of course, we alone take responsibility for any errors or omissions that remain. xxiv The X Window System Administrator's Guide 1 An Introduction to X Administration This chapter provides an introduction to X and to X administration. In This Chapter: The Design of Xl 1 ................................................................................. 3 Display Servers ................................................................................. 4 Clients and Resources ....................................................................... 6 Toolkits and GUIs .............................................................................. 7 X Administration .................................................................................... 8 Installing X ......................................................................................... 8 Supporting Users ............................................................................... 9 Maintaining Software ......................................................................... 9 Maintaining Multiple Machines ......................................................... 10 A "Philosophy" of X Administration ................................................... 10 1 An Introduction to X Administration Administrators make things work. On the surface, the X Window System is just one more software package that the administrator needs to install, maintain and support for users. X runs on any architecture, so there are fewer differences between systems than with most soft- ware. What makes X different from other packages, however, is that it provides a great deal of configurability. It's relatively easy to get X to run on your site with its default settings, but it requires a bit more homework to take advantage of its flexibility and create a secure, cen- trally-maintained environment for users. This book does the homework for you. Administrators need to know how X works before they can figure out how to make it work for them. This chapter provides an introduction both to X and to X administration. 1.1 The Design of Xll The X Window System, called X or X 11 for short, is a network-based graphics window sys- tem that was developed at the Massachusetts Institute of Technology. X is based on the cli- entCerver model, in which the application program (the client) does not directly access the display, but communicates with an intermediary display program (the server). One important feature of the client/server model is that the client and server programs can communicate over a network. They do not need to run on the same machine, or even in the same building. This means that an X display is an ideal front end for a distributed computing environment. A system administrator might open windows on each of a dozen machines she is maintaining; a financial analyst at a Wall Street firm might have a spreadsheet in one win- dow, Quotron data "off the wire" in another, and a custom mainframe-based analysis program in another. The client and server communicate using the X Protocol, which can run on top of UNIX domain sockets, TCP/IP, or DECnet. Technically, the X Protocol is the true definition of X. However, when we refer to X, we often mean not only the protocol but also the widely avail- able implementation of clients, servers and libraries that use that protocol. Since the client and server can run on different machines, the local display machine can get away with running a server program and nothing else. X servers can run on single-tasking DOS-based PCs, which connect across the network to multi-user systems capable of running multiple graphical applications. More importantly, this feature has led to the development of low-cost X terminals, designed specifically for running X servers. Using X terminals, a An Introduction to X Administration 3 company can give multiple users the ability to run graphics-intensive programs, without hav- ing to buy each user a machine powerful enough to execute the graphics programs them- selves. X has great commercial potential because X can be ported to any architecture, operating sys- tem, or display type. Servers have been written for all sorts of architectures, under all sorts of operating systems, for all types of displays. The only requirement is that there be a keyboard, a graphic display, and an input pointer (such as a mouse). And because the server handles the hardware and operating-system dependencies, client programs can be almost completely por- table. Currently, most client programs run on some flavor of the UNIX operating system, but they have also long been available under many other operating systems (such as VMS), and recent products now run X clients (as well as servers) on DOS and Macintosh machines. Further- more, clients have been written to be heavily dependent on programming libraries. This means that once the libraries are ported to another operating system, clients using those libraries should be easily ported as well. X was developed at the Massachusetts Institute of Technology and is maintained by a non- profit consortium of vendors and universities. The source code to X 11 is free. As a result, X has led to an explosion of free software not seen since the heyday of Berkeley UNIX develop- ment. The fact that X was developed by a consortium and had to meet the sometimes conflicting needs of many different vendors, does, however, lead to a few complications. At times, it seems that the developers have gone overboard to make X flexible, configurable and extens- ible, so that it could be adapted to the needs of whatever platform and environment it is ported to. However, in the end, it is hard to fault the bias towards flexibility. The almost uni- versal adoption of X is a tribute to just how insightful those design decisions were. One very concrete expression of X's political heritage is that X itself is a no-frills window system. Rather than choose between competing graphical user interfaces (GUIs), the X designers chose to articulate "mechanism not policy." That is, they provided base technology for manipulating windows, but didn't insist on a particular "'look and feel." X keeps the GUI distinctly separate from the window system itself. Several GUIs (notably those based on the OSF/Motif and OPEN LOOK specifications) have already been built upon X11. What's more, because X doesn't have a GUI to get in the way, it has been integrated with other window systems such as Microsoft Windows and the Macintosh Finder. In such implementations, X windows exist side-by-side with the native windows of that GUI. 1.1.1 Display Servers Client-server terminology often seems "backwards" to people who are new to X. Since the X display runs on a local machine on the user's desk, you might think that the X display should run the X client program. People are used to thinking of servers as something they access across the network (such as file or print server). 4 X Window System Administrator's Guide On other window systems, you might be able to configure this information directly into the application at installation time, since there's only one display that the program can access. X clients, however, need to be able to run with all possible servers. The X server therefore needs to mediate between clients and the specifics of the display. For the output device--i.e., the monitor--the server not only needs to know how to draw to the display as specified by the client, it also needs to be able to tell the client the screen dimensions or whether color is supported. If a user has more than one monitor, each monitor can be used as a separate screen of the display. Input devices (the mouse and keyboard) can also differ. In order to insulate clients from these differences, the server maintains a mapping between physical buttons and keys and cor- responding logical identifiers. For example, the code generated by each key is assigned a symbol, called a keysym. Clients refer only to keysyms, and the server performs the actual translation between keysyms and the actual keycodes generated by a particular keyboard. (For more information on keysyms, see Section D.2.) 1.1.2 Clients and Resources Because X applications, or clients, can display on any X server on the network that allows the connection, X applications must be configurable. However portable the X client-server model makes an application, there are going to be dependencies and preferences that the user needs to be able to express. A font that looks good on one display might be too small on another; a key that is easily reached on one keyboard might be a stretch on another. On another window system, such as that on a Macintosh or on a PC running DOS, all applica- tion preferences can be set at the application level. This makes sense, because the Macintosh OS and DOS are single-user operating systems with only one display to connect to. All pref- erences might as well be stored in the same place. By necessity, X needs to deal with application resources more robustly. X generally runs on multi-user systems, so clients need to be configurable by each individual user. (Character- based UNIX programs already do that using "dot" files in the user's home directory, such as .exrc, .newsrc and .mailrc.) X clients can display on any server on the network, and each server may require its own preferences; so X clients also need to be configured for each indi- vidual server. And because binaries are often shared among several different hosts, each X client executable might be run on any number of systems, so system-specific defaults are needed. X applications need to be configurable at each of these levels. X applications are configured primarily via resources. Resources are variables that are used by X clients and that can be set at the user level, system level, server level, and client level. It is essential that a system administrator thoroughly understand the resource mechanism. Resources are discussed in detail in Volume Three, X Window System User's Guide. In addi- tion, Appendix D provides a summary of the most important points of syntax and usage. 6 X Window System Administrator's Guide 1.1.3 Toolkits and GUIs X clients are built using a number of programming libraries that progressively insulate the programmer from the details of the X protocol. The lowest layer is Xlib, which maps fairly directly to the protocol, and requires the programmer to do a great deal of "handwork." Each event generated by mouse movement, key presses, or graphics exposure must be handled explicitly. Writing a graphical user interface with Xlib would be a bit like starting out with logs when you want to build a house. For this reason, in most X clients, Xlib is used chiefly for drawing, or in cases where the programmer needs more direct control of the dialog with the server. The X Toolkit Intrinsics (Xt) are built on top of Xlib. They simplify the job of building a graphical user interface by creating support for objects called widgets. Widgets are proto- types for common user interface elements such as scrollbars, menus, and so forth, plus other objects that can be used to glue these elements together into a complete application window. But Xt itself does not provide a GUI. This is the job of additional libraries that are layered on top of Xt in turn. The three most common GUIs are provided by the Athena widgets and the OSF/Motif and OPEN LOOK specifications. What's more, even a widget set provides only part of the GUI's look and feel. The basic framework for moving, resizing, and managing windows is handed over to a separate program called a window manager. Athena is a bare-bones widget set originally developed by MIT as a "proof of concept" for Xt. Athena is not terribly pretty, but is widespread because most of the original MIT client programs were written with the Athena widgets. The corresponding window manager is usually twin. OSF/Motif is a GUI that was developed by the Open Software Foundation and is sold by var- ious licensed resellers. (Motif source can be purchased directly from OSF.) OSF/Motif con- sists of a set of Motif libraries and widgets, a style guide, several demo clients, and the Motif window manager (mwm). OPEN LOOK is a GUI specification with multiple implementations. The OLIT toolkit is an Xt-based toolkit developed by AT&T. The XView toolkit was developed by Sun directly on top of Xlib, with an API similar to its native SunView user interface, which predated X. XView is available in the contrib/part of the MIT distribution. OpenWindows is a complete windowing environment distributed by Sun Microsystems that is compatible with the OPEN LOOK specification, and which includes a window manager client called olwm. To further complicate the picture, clients can be written using one set of widgets, yet work with the window manager of a competing GUI. This is most common with MIT clients writ- ten with the Athena widgets, which are often used with mwm or olwm. Fortunately, there is a set of conventions (called the Inter-Client Communication Conventions) that ensure inter- operability of clients and window managers from different X-based GUIs. An Introduction to X Administration 7 1.2 X Administration One of the philosophies that X is built on is that it provides "mechanism, not policy." This is good for developers, since it allows them to decide how X should be used. But until a single standard emerges, it leaves users (and administrators) without much guidance. This book hopes to come to the rescue. One complication for users and administrators is that there are so many different flavors of X. There's "standard" X--that is, the client, server and library distribution maintained by the X Consortium at MIT. Then there are the various vendor-configured versions that are derived from MIT X 11 but then configured for a vendor's operating system and proprietary "look and feel." There's OpenWindows, which runs on Sun workstations. There's Open Desktop, which runs on PCs running SCO UNIX. There's DECWindows, which runs on DEC workstations, and AIXWindows, which runs on IBM workstations running AIX. And many more. This means that X may not look the same on different platforms. A user who thinks he or she has learned X may find that they're totally lost in a co-worker's environment across the hall- way. Furthermore, an administrator might have several different platforms to maintain. This book concentrates on "standard" X 11 as distributed by MIT, but also covers conflicts with vendor distributions of X, as well as conflicts between different releases of X 11. Another complication is that while the X Consortium provides only "mechanism" and relies on vendors to decide how to use it, there are some gaps where no robust, universally- accepted way of dealing with the mechanism has come to light. For example, resources have the potential to be a very powerful tool, but are currently difficult to understand, manipulate, and debug. You need to know what's "under the hood" before you can use resources prop- erly. This is one of the most difficult things about X administration: you may need to know an awful lot about how things work before you can do what you really want. This book tries to make it easier to configure X for your site by describing procedures step-by-step. At the same time, we try to provide background information for readers who continue to have prob- lems or are interested in knowing more. The X sources provide ample documentation, but it's often difficult to weed through the doc- umentation tree to find what you want to know. For example, to learn how to use security fea- tures of X 11, you need to read the xauth, Xsecuri., xhost and xdm manpages before you can begin to get an idea of how it works. This book attempts to group together everything you need to know to get X working on your site. 1.2.1 Installing X You can get X from your operating system vendor, or you can use the standard MIT X11. Which you choose to do depends on what you plan to do with it. If you plan to run specific clients, you may have no choice: a client might run only with a vendor's distribution of X (such as OpenWindows), or it might run only with X11R5 (which at this writing is unavailable from OS vendors). 8 X Window System Administrator's Guide If technical support matters a lot to you, you might prefer to stick with your vendor's distri- bution of XI 1. If having the "latest and greatest" is more important to you, you probably want to build MIT X11 with all the latest patches. If you plan to develop your own X applications, you may want several different X distribu- tions installed, so you can test (or port) your applications on multiple platforms. In addition to the X distribution itself, you will probably also need other toolkits installed, such as OSF/Motif, OLIT or XView. Chapter 8 describes how to build X 11 from source. In addition to the X distribution of clients, libraries and a local server, administrators need to provide X servers for users. X terminals are available from many different vendors. X servers that run on top of PC and Macintosh environments are also available. Chapter 7 discusses the issues of choosing and installing an X terminal, and Appendix C discusses X servers that run on PCs, on Macintosh computers, and on NeXT computers. 1.2.2 Supporting Users Your users might all be self-sufficient power users, or they might need their hands held with every step. You probably have both types on your site, as well as every gradation in between. You will need to set up default environments for the users on your site, and be prepared to help them debug their environment when things go wrong. Remember that the more time you spend on setting up templates for users, the faster users will be able to be productive, and the less time you'll spend later on debugging their environments. Chapter 2 covers some of the issues that you will need to address when setting up a user's environment. If you have any X terminals at your site, you should run the X Display Manager (xdm) to pro- vide an easy way for those users to log on and start their X sessions. You might also want to set up xdm to control X servers running on workstations as well, since among other things, rdm provides a way to configure user environments in a central place. Chapter 3 describes how to set up xdm for your site. Unless everyone at your site trusts everyone else, you should probably look into using secu- rity for X servers on your site. If you are on the Internet, you should definitely use security. If someone's determined to snoop on you, they can probably get through, but there are a few things you can do to trip up the more casual attacker. Chapter 4 describes security issues for XII. 1.2.3 Maintaining Software After you have everything running smoothly on your site, you'll find that most of your time as administrator will involve getting and installing new software, and upgrading existing software. In addition to commercial software, sources to many X programs are available in the public domain. Appendix B is a tutorial on how to find and build public domain software. An Introduction to X Administration 9 New clients often call for new fonts. These fonts have to be made available to all servers that might run the client. Chapter 5 describes how to install new fonts and how to convert fonts from other formats. 1.2.4 Maintaining Multiple Machines The whole idea of X is to have many machines networked together: PCs, workstations, X terminals, minicomputers, supercomputers, you name it. This can become a lot of work for administrators, since that means multiple machines to configure and maintain consistently. One useful tool is to keep up-to-date documentation on how each machine is configured. This is especially helpful on a large site, particularly on one with more than one administra- tor. But maintaining many different machines can be made much easier if you configure machines centrally when you can. This book describes the various mechanisms X provides for doing so. The X Display Manager can be used to maintain all X sessions centrally. Many X terminals can be configured remotely from a host machine. The font server, new with X I I RS, provides a way to supply fonts to multiple servers. 1.2.5 A "Philosophy" of X Administration If we had to come up with a "philosophy" of X administration, it would be that X is made to fit the needs of its users. As the administrator, you have the responsibility to determine your users' needs and configure X accordingly. X is installed in all sorts of environments, from universities with hundreds of student users, to home offices with a single standalone machine. For that reason, almost everything in X is configurable at multiple levels. Application resources can be set in several different places. You can create new fonts and define new colors. The X Display Manager can be configured to meet practically any need. Even the source code to X is available for programmers who want to create their own workarounds if none already exist. The fundamental idea is that if you don't like the way something works, change it. From the onset, you'll see that this book is less about making X work than it is about getting X to work for you. 10 X Window System Administrator's Guide 2 The X User Environment Administrators need to configure X environments for their users. This chap- ter describes the issues involved in making an X environment work properly. In This Chapter: The Configured X Session ................................................................... 13 The Twilight Zone ............................................................................ 16 Components of the X Environment ...................................................... 18 Window Managers ........................................................................... 18 Customizing Clients ......................................................................... 20 The -fn Command-line Option ........................................................ 20 The -geometry Command-line Option ............................................ 20 Specifying Colors ........................................................................... 23 Using Resources ........................................................................... 24 The Startup Script ............................................................................ 25 The Foreground Process ............................................................... 26 The Shell Environment ......................................................................... 27 Setting the DISPLAY Variable ........................................................... 27 Complications with Display Names ................................................ 28 Redefining the Search Path ............................................................. 29 Setting the Search Path for OpenWindows Support ....................... 30 Setting the Search Path for Mixed Environments ........................... 30 xterm Issues .................................................................................... 31 xterm and Terminal Emulation ........................................................ 31 The resize Client ............................................................................ 31 xterm and the Login Shell (C Shell) ................................................ 33 Starting Remote Clients ................................................................... 34 Starting a Remote Client with rsh ................................................... 35 Startup Methods .................................................................................. 37 xinit and startx ................................................................................. 38 Differences Between .xinitrc and .xsession ...................................... 39 Related Documentation ....................................................................... 39 xsetroot -bitmap /usr/include/Xll/bitmaps/dimplel # Merge in user resources: xrdb -merge $HOME/.Xresources # Start some applications: xterm -title Top -g 70x35+i+i & xterm -title Bottom -g +i-0 & xclock -g -0+0 & xcalc -g -0+298 & xpostit -sv -g ii0x50-0+200 & # Start a window manager in the foreground: twm .Xresources The .Xresources file contains resource definitions. These resources define Joan's client preferences. Currently, Joan's resources are used to set some preferences for her aterm terminal emulator windows. We set her up to use a font that we think she would prefer over the default, we turned on a scroll bar, and we set the number of lines to be saved for scrolling to be 200. The .Xresources file reads: ' Resource definition file. ,. XTerm definitions : XTerm* font :-misc- fixed-bold-r-normal--15-140-75-75-c-90-iso8859-1 XTerm* scrol iBar: true XTerm*savedlines : 200 The .twmrc file is a configuration file for Joan's window manager, twin. A window manager is a special client that controls how windows are moved and resized. In addi- tion, the window manager defines the root menu shown in Figure 2-2. The .twmrc file is long, but we can show you the part that defines the root menu: menu "rootmenu" { "twm Root Menu" f.title "Terminal" f.exec "xterm &" "Clock" f.exec "xclock &" "Calculator" f.exec "xcalc &" "Dictionary" f.exec "xwebster &" "Solitaire" f.exec "spider &" " " f. hop "Kill Window" f. destroy "" f. nop "Restart twm" f. restart "Log Out" f.quit } Together, these files define Joan's X user environment. They are defined in addition to the shell startup files that she needs to define her UNIX shell environment. Now, imagine that you're Joan, new to both UNIX and X, and you're faced with these startup files. Each file has its own peculiar syntax that she might be able to follow, but will probably have trouble duplicating. Where did we get that arcane font name? Why do some of the com- mands in .xsession end in ampersands (&) while others don't? The X User Environment 15 2.1.1 The Twilight Zone One day Joan logs in at a workstation. The X server isn't running on the workstation console, so Joan tries to start her X session by typing X. What she gets is a blank screen with an "x" representing her pointer. She is unable to start applications and after several minutes decides to start over. After rebooting the machine, Joan learns that she should use the xinit command, not X. When she does this, she gets a single xterm terminal emulation window with a very small font, and no window manager, as shown in Figure 2-3. Figure 2-3. An unconfigured X session (Unknown to Joan, this has happened because the .xsession file is the one primarily responsi- ble for configuring Joan's user environment under xdm. Under xinit, she needs an .xinitrc file. See Section 2.4 for more information on starting the X session using xinit.) Joan tries to start a clock using the xclock command, shown in Figure 2-4. 16 The X Window System Administrator's Guide ruby:joan 2B xclock &| Figure 2-4. Starting a new client What happens is that the clock appears on top of the xterm window, obscuring her prompt, as shown in Figure 2-5. Figure 2-5. xclock window over xterm window Since there is no window manager running, Joan can't move the new xclock window from on top of the xterm window. She needs to place her pointer on the xterm window and type RETURN a few times before her prompt peeks out from underneath the clock window. What Joan has stumbled onto is X in its unconfigured state. Joan types "XYZZY". Nothing happens. The X User Environment 17 2.2 Components of the X Environment Joan's adventures are meant to show the world of difference between X in its raw state, and X when it has been configured. You might think of it as the difference between an unfur- nished apartment and a home. Like someone's home, the X user environment is made up of many components. You can't just bring in furniture and expect the house to look lived-in; similarly, you can't just start a window manager and expect the X environment to be complete. Some users would prefer to configure their own environments. Other users won't have the slightest idea of where to begin. As an administrator, you have to decide whether you want to set up an environment with reasonable defaults for new users, or whether you'd rather just give users a bare-bones environment and let them figure it out on their own. Our opinion is that it's always better to take the time to set up a decent environment for your users. "Power" users can always rip apart what you set up and start again from scratch; but users who are just interested in getting their jobs done will appreciate having something workable to begin with. One approach to creating a useful default environment is to alter the system-wide files. For example, if a user has no .twmrc file, they will use the file/usr/lib/Xll/twm/system.twmrc. If a user has no .xsession file, they will use commands specified in the/usr/lib/Xll/xdm/Xsession file. As shipped in the MIT distribution, the defaults in these files are fairly basic. But you can configure these defaults system-wide to better accommodate your users. The preferable approach is the "template" approach, as we set up earlier for the user named Joan. We gave Joan a set of configuration files that had been tried and tested and liked by other users. The advantage to using templates is that when users are ready to edit their envi- ronment, it's much easier if the configuration files are already set up locally. Either way, the administrator needs to take a strong hand in setting up the user environment. The administrator is all that stands between a user and the abyss of the default X environ- ment. There are an endless number of factors that can influence a user's X environment, but the simplest user environment (like Joan's) consists of a window manager, a little client customi- zation, and a startup script to bring it all together. 2.2.1 Window Managers As we mentioned earlier, window managers are special clients that allow you to move, resize, and iconify windows. The window manager provided in the X source distribution is twin, the Tab Window Manager. Window managers are generally started in the user's startup script, but like other clients, they can be started on the command line as well, as shown in the fol- lowing figure. 18 The X Window System Administrator's Guide rub:joan 2B twm &| Figure 2-6. Starting the window manager If a window manager were already running, the command would fail with a message resem- bling: twin: another window manager is already running on screen O? twin: unable to find any ged screens The window manager gives each window its own borders and titlebar. By pressing the pointer on the titlebar (i.e., holding down the first mouse button while the pointer is on the titlebar), you can move the window. By pressing the icon at the upper right corner of the titlebar, you can resize the window. By pressing the icon at the upper left corner of the titlebar, the window is iconified. Once the window manager is started, you can use it to move windows on the screen. You can also use it to start new applications on the root menu, as shown in Figure 2-2. When a new window appears, twm allows you to place the window by displaying an outline of the window with the upper left corner at your current pointer position. When you press the first mouse button, the window will be placed at that position. The behavior of twm can be configured by editing a file called .twmrc in your home directory. Alternatively, the default behavior of twm on a system can be changed by editing the system.twmrc file, usuall3) in the/usr/lib/Xll/twm directory. For information on how to con- figure twm, see either the twm manual page or The X Window System User's Guide, Standard Edition (O'Reilly & Associates, 1990). twm is the only window manager supplied with the MIT X distribution, but there are many other window managers distributed by vendors. One of the most popular window managers is mwm, the Motif Window Manager. mwm is a window manager which implements the OSF/Motif "look and feel." Another popular window manager is olwm, a window manager for OPEN LOOK. Other window managers are swm (the Solbourne window manager, which can simulate both olwm and mwm in separate "modes"); gwm (a public domain window man- ager that uses LISP-like syntax in its configuration, and can simulate mwm); and ,'m and olvwm, which are versions of twm and olwm (respectively) that support a "virtual" root win- dow. A virtual root window is a root window that is larger than the portion visible on your display. It can be scrolled around to move different sections into view. This simulates having a much larger display and gives more room to display clients. See The X Window System User's Guide, Motif Edition (O'Reilly & Associates, 1992) for more information on mwm and Motif. For more information on olwm and OPEN LOOK, see the upcoming X Window System User's Guide, OPEN LOOK Edition (O'Reilly & Associates, 1993). The X User Environment 19 2.2.2 Customizing Clients There are two ways to customize clients: with command-line options, and with resources. The use of command-line options to modify the behavior of a program should be familiar to any UNIX user, but even so, it's worth reviewing a few of the most commonly-used X options--those for specifying fonts, window size and placement, and colors. This discussion will also serve to introduce the treatment of resources, which provide a convenient way to set "global" options. 2.2.2.1 The-fn Command-line Option For specifying a font, the xterm client provides a -fn command line option. Font names in X are a bit unwieldy, but you can use the xlsfonts command to get a list of fonts available for your X server. For example: % xlsfonts -adobe-courier-bold-o-normal--lO-lO0-75-75-m-60-iso8859-1 -adobe-courier-bold-o-normal--i I- 80-i 00-i O0-m-60-iso8859-1 -adobe-courier-bold-o-normal--12-120-75-75-m-70-iso8859-I ... -misc- fixed-bold-r-normal--15-140-75-75-c-90-iso8859-I ... (You might also try the ffontsel client, which can be used to display fonts available to your server.) See Chapter 6 for a description of each of the fields in a font name. For now, let's use the fixed font that we showed in the output of xlsfonts. Use the -fn option: % xterm -fn -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-i & This command line gives you a window resembling that in Figure 2-7. 2.2.2.2 The -geometry Command-line Option The -geometry or-g command-line option can be used to specify two things: where the client window initially appears and what size it should initially be. To have an xterm window that's 92 characters across and 40 lines long (instead of the default 80x24), enter: ruby:joan % xterm -geometry 92x40 & To have an xterm window appear at position (324,190) on the screen, enter: ruby:joan % xterm -geometry +324+190 & You can combine the two requests into one argument: ruby:joan % xterm -geometry 92x40+324+190 & You see a window resembling that in Figure 2-8. 20 The X Window System Administrator's Guide 2.2.3 The Startup Script The startup script is what brings a user's entire X environment together. If you use xdm to start your X sessions, this script is called SHOME/.xsession. If you use xinit, the script is called SHOME/.xinitrc.* We'll show the simple startup script that we used earlier: # .'/bin/sh # Add /usr/local/bin to the path for this script: PATH=$PATH:/usr/local/bin export PATH # Set up a pattern for the root window: xsetroot -bitmap /usr/include/Xll/bitmaps/dimplel # Merge in user resources: xrdb -merge $HOME/.Xresources # Start some applications: xterm -title Top -g 70x35+i+i & xterm -title Bottom -g +i-0 & xclock -g -0+0 & xcalc -g -0+298 & xpostit -sv -g ii0x50-0+200 & # Start a window manager in the foreground: twm The first thing that this startup script does is set the path to be used for commands for that script. By default, :/bin:/usr/bin:/usr/bin/Xll:/usr/ucb is used as the search path for the startup shell. Since the xpostit command resides in/usr/local/bin, it needs to be called with its full pathname, or/usr/local/bin needs to be appended to the search path. This path is then exported, so that it will also be used by other clients such as twm. The startup script uses xsetroot to give the user a nicer background than the default root win- dow background. Next, the startup script calls the xrdb client. It is this command that reads the resources defined in the .Xresources file. The xrdb client loads resources directly into the X server. There are alternate ways of reading resources (as described in Section D. 1.2), but if you load the resources directly into the server, you guarantee that all clients displaying to that server will be able to access them. xrdb should be run before any applications are run, since you want to make sure that the resources are loaded before you start any applications that use them; and it should be called in the foreground, to guarantee that the resources are fully loaded before the script continues. The applications are then started. We described how the -g options are being used in Section 2.2.2.2. Note that each of these command lines are placed in the background. Finally, the twm window manager is started. When twm starts up, it is configured by the .twmrc file. * See Section 2.4 for more information on using xinit. See Chapter 3 for more information on using xdm. The X User Environment 25 2.3.2.1 Setting the Search Path for OpenWindows Support If you are running OpenWindows, you need to add the following directories to your search path along with your vanilla X 11 binary directories: set path = ($path /usr/openwin/{bin, demo} ) (In OpenWindows 3.0, the/bin/xview directory is now linked to bin.) In addition, you need to set the shared library path to/usr/openwin/lib: setenv LD_LIBRARY_PATH /usr/openwin/lib:/usr/lib If the OpenWindows distribution is elsewhere on your system, you can set the OPENWINHOME environment variable and use it in place of/usr/openwin. For example, if the OpenWindows distribution is in/usr/local/openwin, C shell users can enter in their .cshrc files: setenv OPWINHOME /usr/local/openwin set path = ($path $OPENWINHOME/{bin,demo} ) setenv LD_LIBRARY_PATH $OPENWINHOME/Iib:/usr/lib In Bourne shell syntax, this might read: OPENWINHOME=/usr/local/openwin PATH= $PATH: $OPENWINHOME/bin: $OPENWINHOME/demo LD_LIBRARY_PATH= $OPENWINHOME/lib:/usr/lib export OPENWINHOME PATH LD_LIBRARY_PATH 2.3.2.2 Setting the Search Path for Mixed Environments If you are running multiple releases of X 11 on your system, you need to set your search path appropriately according to which executables you want to run. One situation in which you might want to run multiple releases is if you are testing a new release of X 11 before setting it loose on your users. For example, suppose that you have X11R4 installed and running in /usr/lib/Xll and /usr/bin/Xll, and have just compiled and installed XI1R5 into /usr/XllR5/lib and /usr/XllR5/bin. For testing your new environment, enter the /usr/X11R5/bin directory into your command search path before/usr/bin/X11: set path = ( /usr/XllR5/bin $path ) On SunOS, you also need to enter/usr/X11R5/lib into your LD_LIBRARY_PATH: setenv LD_LIBRARY_PATH /usr/XllR5/lib Another possibility is to set the LD_LIBRARY_PATH environment variable for each com- mand: % (setenv LD_LIBRARY_PATH /usr/XllR5/lib ; /usr/XllR5/bin/xterm)& 30 The X Window System Administrator's Guide [] xterm COMM SXConsortium: Imakefile,v 1.105 91/07/27 14:13:23 rws Exp $ #define IHaveSubdirs #define PassCgebugFlags ORLDOPTS = -k CHECKFNSRC = $(UTILSRC)/checkfn CHECKFN = $(CHECKFNSRC)/checkfn #if BuiIdServer SERVERDIRSTONAKE = server rgb #endif SUBDIRS = confi9 include lib extensions fonts $(SERVERDIRSTONAKE) \ clients demos util man LNINSTALLDIRS = $(LIBSRC) $(EXTENSIONSRC) NakeSubdirs($(SUBDIRS)) NakeLintSubdirs($(LNINSTALLDIRS),instaII.In,nstaIl.ln) NakeLXntSubdirs($(LNINSTALLDIRS),externaI.In,Iintlib) XCOMM "Imakefi]e" [Red only] 107 lines, 2918 characters Figure 2-10. vi using only part of a window The resize client is typically used immediately after the dimensions of an xterm window are changed. A peculiarity of the resize client is that it does not access the shell itself, but simply returns the shell commands that would be needed; to have those commands read by the shell, you have to either save its output in a file and source it in with the .... command (Bourne shell) or source (C shell) commands, or call it using the shell command eval. For example, after resizing a window you would type in that shell: % eval "resize" When you call the resize command under a termcap system, it produces the commands for resetting the TERMCAP environment variable with the li# and co# capabilities reflecting the current dimensions. When you call the resize command under a terminfo system, it produces the commands for resetting the LINES and COLUMNS environment variables. 32 The X Window System Administrator's Guide 2.3.3.3 The resize command consults the value of your SHELL environment variable and generates the commands for setting variables within that shell. If you are using a non-standard shell, resize may still recognize your shell; as of R5, resize recognizes tcsh,jcsh, ksh, bash, and jsh. But if resize does not recognize your shell, try using the -c or -u options to force resize to use C Shell or Bourne Shell syntax (respectively), depending on which syntax is appropriate for your shell. xterm and the Login Shell (C Shell) Most people who use the C shell know that the .cshrc file is read for every csh command run, and the .login file is read only once, at the beginning of each "login shell." One thing that X does is to effectively redefine the meaning of the "login shell." Before X, you could assume that a user had a single interactive shell per login. Since the .login file would therefore be read only once, at the beginning of the login session, you could use it as a "batch" file to run some daily commands. For example, you might have it show the "message of the day" and start mail for you first thing in the morning: cat /etc/motd mail Since X gives you the ability to run multiple xterm windows, however, the usage of the .login file becomes more confused. You probably don't want to read your mail and see the "mes- sage of the day" every time you call up a new xterm window. It makes more sense for these functions to be taken up by your X startup script, and to run X clients rather than text-based applications. For example, if you log in via xdm, your .xsession might contain the lines: # Show the message of the day: xmessage -file /etc/motd & # Start a mail application: zmail -gui & Here, we use the contrib client xmessage to show the message of the day, and we call up an X-based commercial mail application, zmail. What does that leave for terminal emulator windows like xterm? Well, by default, xterm shells are not login shells--that is, xterm shells don't run .login, but just the shell startup file .cshrc. You can call up a login shell xterm by starting xterm clients with the -Is option. (Alternatively, you can set up all xterms to run login shells by setting the XTerm*login- Shell resource to true.) Whether you want to set up xterm as login shells depends on what you use .login for. How- ever, you might want to start thinking of the .login file as the startup file for ASCII-based user sessions only. Some of the functions of the .login script don't make sense for xterm shells (such as setting the terminal type, which xterm is smart enough to do on its own). But those functions are still useful for when you log in at an ASCII terminal, which you undoubtedly still do on occasion (for example, when dialing in on a modem line). The .cshrc file therefore takes on a lot more responsibility for your shell environment, since it needs to make the xterm shell environment complete on its own. Since it's also used for C The X User Environment 33 shell scripts, you can write it so it tests for a prompt and provides interactive-shell startup commands for interactive shells only: # Make default file mode -rw-rw-r--. umask 002 set path= (/usr/local/bin /usr/ucb /usr/bin /usr/bin/Xll . ) # Fix "dirs" and "$cwd" not to be fooled by symbolic links: set hardpaths # ALIASES AND OTHER INTERACTIVE COMMANDS GO BEqWEEN HERE AND endif: if ($?prompt) then set history=50 savehist=25 set host=" hostname" set mail=(300 /usr/spool/mail/$user) set prompt=" ${host} : Suser \ ! % " alias h history alias is "is -F" alias rm "rm -i" stty erase '^h' setenv PRINTER dodo_ps endif In this example, the part between "if ($?prompt) "" and "endif" are only executed for the primary interactive shell. Note that if you use xinit to start your X session, then your .login file is executed when you first log in prior to starting the X server. If you use xdm to start your X session, the .login file is never executed at all unless you run xterm with the -Is option. 2.3.4 Starting Remote Clients One of the advantages of a window system like X is that you can run applications remotely and view them on the local display. You can try this easily enough by just doing a rlogin to the remote host, setting the DISPLAY environment variable, and starting up a client. In the following example, we start up a new xterm client running on the host ruby: sapphire:joan % rlogin ruby Password: Last login: Tue May 12 16:27:23 from sapphire.ora.com SunOS Release 4.1.2 (RUBY+COALM+PPP) #i: Tue Mar 3 23:29:52 EST 1992 You have mail. TERM = (vtl00) xterm ruby:joan % setenv DISPLAY saDDhire:0 ruby:joan % xterm & (You must, of course, have an account on the remote system.) The first thing that might go wrong is that you may run into server access control If you see the following error: Xlib: connection to "sapphire:0" refused by server Xlib: Client is not authorized to connect to Server Error: Can't open display: sapphire:0 34 The X Window System Administrator's Guide Or: ruby: ruby: cannot open where ruby is the name of the system that you wanted to run the remote shell on, the problem is probably that are using the wrong rsh command. Use the which or whereis command to track down which rsh you are using: sapphire:joan % which rsh /bin/rsh sapphire:joan % echo $path /bin /usr/bin /usr/bin/Xll /usr/bsd On some System V-derived systems such as IRIX, the restricted shell rsh might live in /bin, while the remote shell rsh (the one you want) resides in/usr/bsd. /bin often shows up in search paths earlier than/usr/bsd, so on those systems you need to explicitly rede- fine your path so that/usr/bsd is searched before/bin. You may need to use the -n option to rsh to avoid a "Stopped" error message on some machines. You need to be sure that the directory containing X binaries is defined in your search path in either .cshrc or .projile on the remote system. If you are using host-based access control, you need to execute the xhost client to extend access to the remote host before the rsh command is run. Otherwise, clients from the remote host will not have permission to access your display. If you are using user-based access control, you may need to run the xauth command to copy your access code to the remote machine. See Chapter 4 for more information on server access control. You have to use the -display option in calling a remote shell, or the "Can't Open display" error will be returned. (Alternatively, you can have your DISPLAY environ- ment variable hard-coded into your .cshrc or .profile on the remote machine, but this is a Very Bad Idea.) See Section 2.3.1 for more information on setting your display. Be careful not to use unix:0.0 or :0.0 as the display name! Otherwise, the client will display the window on the local display of the remote host. If this succeeds, the user on that display could either become very annoyed, or could take advantage of the sudden access to your account to read personal files and send nasty mail to your boss. You would have no warning; all you would know is that your window didn't appear. (See Section 2.3.1 for more information on the DISPLAY environment variable.) A common situation is to start rsh commands as follows: sapphire:joan % rsh ruby -n xterm -display SDISPLAY This works great if your DISPLAY variable is set to something like sapphire : 0.0, but if it's set to unix : 0.0 or : 0.0 (as is the default for X sessions begun on the console display), then the wrong display name will be sent to the remote machine. The X11R5 distribution contains a shell script called xrsh in the contrib/clients area. This script sets the DISPLAY variable for the remote client and handles authentication according to the value of an XRSH_AUTH_TYPE environment variable. See the manpage on xrsh for more information. 36 The X Window System Administrator's Guide 2.4 Startup Methods The X Display Manager, xdm, is the method of choice for starting your X session The main reason for this is that xdm is the only elegant way of starting an X session on an X terminal or other remote "'passive" X server. However, for local X servers, you can use the xinit or start.,: command to start both the X server and your X session in a single step. If you are running a vendor-configured version of X, there might also be another command for starting the X server, such as openwin for Sun OpenWindows; see your vendor's documentation for details. On an X server controlled by xdm, the X server is always running, and users start their indi- vidual X sessions by logging in via a login box window. r Login: I Password: emerald X Figure 2-11. Logging in with xdm When you log in, your window manager and other X clients are automatically started as specified in your .xsession startup script. Chapter 3 discusses xdm in detail. On a local console display server that does not already have the X server running (i.e., is not controlled by xdm), you log in as usual on the console (using get') and type xinit to start both the X server and the X clients specified in your .xinitrc script. The X User Environment 37 Iogin: Imui Password: Last Iogin : Wed May 614:1:36 from ncdlO.ora.com SunOS Release 4.1.2 (RUBY+COALM+PPP) #1: TUE EST 1992 Imui@rubble% xinit 2.4.1 Figure 2-12. Starting the X server with xinit xinit and startx The xinit program first starts up the X server for the local display. By default, it starts the X server by running the program called/usr/bin/Xll/X. X is usually a link to another server program, for example, Xsun on a Sun workstation. You can override the server command by entering another command in a file called $HOME/.xserverrc. For example, it could contain: /usr/bin/Xll/XsunMono You may want to set up a new command in $HOME/.xserverrc if you are testing a new server for your display, or if you prefer to start up your server with particular command-line options. If you want to test an option to the X server, follow the xinit command with two dash charac- ters (- -) and it will pass any following command-line options onto the server. For example: % xinit -- -dev /dev/cgthreeO After starting the server, xinit looks for a shell script called $HOME/.xinitrc. As we saw in Section 2.1. l, if SHOME/.xinitrc does not exist, a single xterrn window is sent to the local dis- play to get you started. The startx script is a front end to xinit provided in X 11 R4 and X 11R5. Like xinit, it looks for an .xinitrc file in your home directory; however, if you don't have an .xinitrc, it then uses a system-wide default file in/usr/lib/Xll/xinit called xinitrc. This file can also be used as a template for .xinitrc files, startx also uses a file called xserverrc in the same directory for users who don't have an .xserverrc file in their home directory. 38 The X Window System Administrator's Guide 2.4.2 Differences Between .xinitrc and .xsession All of the rules about configuring .xinitrc files also apply to .xsession files. For that reason, many users simply link their .xinitrc files to their .xsession files. However, there are three points to consider: 1. The .xsession file is generally a shell script, but it can actually be any executable file, such as a session manager or desktop manager..xinitrc must be a Bourne shell script. 2. The .xsession file must be an executable file. If you get bounced back to your xdm login box, you might have to do the following: % chmod +x .xsession The .xinitrc file does not have to be executable. 3. The _tsession script does not inherit the user's login shell environment. The .xinitrc script inherits the environment from the shell from which it was run. 2.5 Related Documentation For more information, see the X Window System User's Guide, by Valerie Quercia and Tim O'Reilly, published by O'Reilly & Associates, Inc. The following X manual pages may be of interest: X, xrdb, xinit, xset, xterm, twm, mwm, olwm, xlsfonts, showrgb, and resize. The following UNIX mandal pages may be of interest: rsh, csh, and sh. The X User Environment 39 3 The X Display Manager The X Display Manager provides a way for users to log on and start initial cfi- ents, regardless of which X server they use. This chapter shows how to get xdm going and how to configure it to the needs of your site. In This Chapter: xdm Concepts ..................................................................................... 44 xdm Configuration Files ....................................................................... 46 xdm the Easy Way ............................................................................... 48 Troubleshooting xdm ............................................................................ 49 Customizing xdm ................................................................................. 51 The Master Configuration File (xdm-config) ...................................... 51 Listing X Servei's (the Xservers File) ................................................ 53 Xservers Syntax ............................................................................ 53 xdm Host Access Control: the Xaccess File (R5 Only) ..................... 55 Direct and Broadcast Access ......................................................... 56 Indirect Access and the Chooser ................................................... 57 Using Macros ................................................................................ 59 Advantages and Disadvantages of the Chooser ............................. 59 The Xresources File ......................................................................... 60 Configuring the Login Box .............................................................. 60 The xconsole Client ....................................................................... 62 Starting Up Individual X Sessions (the Xsession File) ...................... 63 No Home Directory? (R5) .............................................................. 64 Display Classes ............................................................................... 65 Testing Your xdm Setup ....................................................................... 66 Resetting the Keyboard ................................................................... 67 Restarting xdm Using xdm-pid (R4 and Later) .................................. 68 Rereading xdm Configuration Files (R3) ........................................... 68 Permanent Installation of xdm .............................................................. 69 Related Documentation ....................................................................... 70 3 The X Display Manager The X Display Manager, xdm, runs as a daemon on a host machine. It provides a way for users to log on and start initial clients, regardless of what X server they use. Not all sites use xdm to control X sessions. Many workstation users still prefer to log on as usual on the console and use the xinit program to start the X server and any preferred clients. xinit, however, is considered obsolete by the X Consortium, with all new functionality being built into xdm. And on a site that includes X terminals, xdm is an essential tool for providing a standard way for users to log on across the network. xdm also provides a way for administrators to configure environments system-wide. So if you don't already use xdm to control X sessions for users on your site, we encourage you to give it a try. xdm and Vendor Environments If you're running a vendor-distributed version of X that's greatly modified from the MIT version, your mileage may vary with this chapter. For example, the OpenWindows 2.x server doesn't work very well with xdm at all. The OpenWindows 3.x distribution, meanwhile, supplies its own version of xdm which is somewhat modified from the ver- sion documented here. SCO Open Desktop has its own version of xdm, called scologin, which must be used for all logins, scologin is enhanced in that it has SCO's session manager scosession built-in as the controlling process for the X session, and it checks for expired passwords, scolo- gin also provides a front end (/etc/scologin) to facilitate some administrative responsi- bilities. In addition, many vendor-supplied X environments already have xdm pre-configured when X is installed. The X Display Manager 43 3.1 xdm Concepts The xdm program is simply an X client that manages the first and last points of connection, control, and coordination of the user session. If you need a conceptual feel for what the X Display Manager is, think of xdm as working for network-connected X servers the way init, getty, and login work for serial-connected ASCII terminals. This is only a loose comparison, but it will serve our purposes in conveying the general function of xdm. Like init, xdm keeps track of which X servers are available to be connected. When init has determined that an ASCII terminal is available to be managed, it spawns the getty program, which puts up a login prompt. Similarly, when xdm is given management of an X server, it sends a login box to the server display. When a user types a name and password on a serial ASCII terminal, that information is sent to the login program, which authenticates the password and then starts up whatever program is specified in the user's/etc/passwd, almost always an interactive shell. When the shell begins, user-configurable batch files are executed, $HOME/.profile for the Boume/Kom shell or $HOME/.cshrc and $HOME/.login for the C shell. The user is then deposited in the selected shell environment, ready to run UNIX commands. For a user who logs in with an xdm login box, the name and password are also authenticated, using the same mechanism as the login program. However, this is where the functions of login and xdm diverge. As shown in Figure 3-1, instead of running an interactive shell, xdm runs a series of shell scripts. These scripts normally start all your desired X clients, including xlogin box emerald Login: I Password: exec (Xrest script) #Vbin/sh #Load resources xrdb -merge $HOME/.Xresources #start window manager twm& #Initial xterm xterm -name Iogin exec $HOME/.xsession Iogin authentic? exec ( Xstartup script) exec Xsession Figure 3-1. xdm flow chart 44 The X Window System Administrator's Guide one or more terminal emulators, each of which will contain an interactive shell. In the default xdm configuration, Xsession is one of the shell scripts that are executed. Xsession then calls another script called $HOME/.xsession (if it exists). When a user logs out on a character-based terminal, control of the terminal returns to getty, sending another login prompt to the terminal. Consistent with that model, when a user logs out of an X session (i.e., when the "controlling" process of the X session has been ter- minated), xdm closes all connections and resets the terminal to a "ready for log on" state, dis- playing a new login box, ready for another user session. As you can see, xdm is a very ambitious program. It can be configured to control logins on multiple X servers connected to the same machine, creating customized sessions, and offer- ing some basic network security features. The conclusion is that xdm, when set up properly, enables users to walk up to a display and log in by typing their usernames and passwords, the same as they would on an ASCII termi- nal. xdm then runs their startup scripts automatically, setting up customized environments and enabling users to begin productive work immediately. When users finish their X sessions, xdm resets each display for the next user. With the X session startup process incorporated into the login process, users need to know relatively little about X11 to start work- ing--given, of course, that xdm and users' individual environments are configured appropri- ately. History of xdm and XDMCP xdm was introduced with X1 IR3, to support the X terminals that were just coming to the market. That first version of xdm had several problems, which were solved in X 11 R4 by the introduction of the XDM Control Protocol (XDMCP). The most urgent problem that XDMCP addressed was the problem of X terminals that are turned off and on again. Prior to XDMCP, the only way xdm knew to control an X termi- nal was to look for its entry in the Xservers file (see Section 3.5.2 for more information). Since Xservers is consulted only when xdm is first started, this caused problems when X terminals were turned off temporarily, or when new X terminals were attached. It meant that every time a user turned an X terminal off and on, the system administrator needed to send a SIGHUP to xdm. XDMCP provides a solution to this problem. XDMCP, introduced in X11R4, is a protocol shared by the xdm client and X servers throughout the network. Using XDMCP, the X server has the responsibility of actively requesting an xdm connection from the host. If an X server uses XDMCP, therefore, it no longer requires an entry in Xservers since the host no longer has the burden of initiating the connection. Almost all X terminals sold today are XDMCP-compatible. R4 and R5 servers running on local console displays are also XDMCP-compatible, but XDMCP queries are not enabled by default. The X Display Manager 45 3.2 xdm Configuration Files xdm is configured through a set of editable ASCII files for some of the mechanisms you would expect--a list of servers to be explicitly controlled by xdm, resources to be used by xdm, error messages, whether to use security, etc.--but it also provides ASCII files for setting up an initial default session and setting resources to be loaded by the server itself. The files used for xdm configuration in/usr/lib/Xll/xdm are listed here (and shown in Figure 3-2), to be dis- cussed in detail later in the chapter: xdm-config Resources specified for xdm. Note that the location of all other files listed below can be redefined with resources specified in xdm-config. (The location of the xdm-config file itself can be reassigned using the -config option to xdm when it is started.) Xservers A list of servers to be explicitly managed by xdm. The local display server usually needs to be listed here. Xsession The initial startup script used by each individual X session. Xresources Resources to be loaded via xrdb by servers managed by xdm. xdm-pid A file containing the process ID ofxdm. (This file is not designed to be edited by administrators, but is for informational purposes only.) (X 11 R4 and later only.) The error log file for xdm. (This file is not designed to be edited by administra- tors, but is for informational purposes only.) xdm-errors $HOME/  .xsession .Xresources Figure 3-2. Default xdm configuration files 46 The X Window System Administrator's Guide Xaccess A file for configuring access control for XDMCP, specifying different behavior according to the sort of query used. This configuration file is new to X I I R5. GiveConsole A shell script that changes the ownership of the console to the user. This file is new to X I I R5. See Section 4.6.2 for information on how the GiveConsole script is used. TakeConsole A shell script that changes the ownership of the console back to root. This file is new to X I I R5. See Section 4.6.2 for information on how the TakeConsole script is used. Xsetup_O A shell script used for display setup specific to the local console server. This file is new to X1 I R5. In users' home directories, the following files are used by xdm in its default configuration: $HOMELxsession User-specific startup script executed by the systemwide Xsession script. $HOME/.Xresources User-specific resources read by the systemwide Xsession script if $HOME/.xses- sion does not exist. (If $HOME/.xsession does exist, then the .xsession script is responsible for loading user-specific resources from .Xresources or any other resource file.) See Appendix D for information on setting resources. $HOME/.xsession-errors Errors specific to a user's X session (R5 only). This file is not designed to be edited. $HOME/.Xauthority Machine-readable authorization codes for the user's server. This file is not designed to be edited by hand. See Chapter 4 for information on how the .Xau- thority file is used. Note that the user-configurable .xsession file is available only because it is exec'd by the Xsession shell script. If you don't understand yet why this is important, consider that any administrator can remove that functionality, or can add any other clients or resources to be used by all X user sessions. So xdm configuration is unusual in that you can do just minimal configuration (just set things up so it runs and then leave it alone) or you can go wild setting up a global user environment. We'll talk about all these files in detail later in the chapter. First, though, we'll give a quick and dirty procedure to get a minimal setup running. The X Display Manager 47 3.3 xdm the Easy Way For those of you that are interested in just getting xdm working for the first time, you can fol- low the steps below to set up xdm on a standalone workstation. These steps assume that you are using the MIT-distributed version of xdm, and that the xdm configuration files have not been changed from the defaults distributed by MIT. 1. Edit the Xservers file in/usr/lib/Xll/xdm as needed. If you want xdm to control the local display server, the Xservers file should contain the line: :0 local /usr/bin/Xll/X If you don't want xdm to control the local display server, this line should be omitted. In all likelihood, the default Xservers file will work just fine. 2. If you're currently running the X server on the local console display, you should exit it. It's also a good idea to have an alternate way to log in to the workstation (such as a remote login across the network, or an ASCII terminal connected to a serial port), since if something goes wrong, your console may become unusable. 3. Start xdm as root: # /usr/bin/Xll/xdm The X server will take over your display and you should see a login box resembling that in Figure 3-3. login: Password: Figure 3-3. xdm Iogin box 48 The X Window System Administrator's Guide Now log in. You should get an xterm window and a twm window manager, as shown in Fig- ure 3-4. Figure 3-4. Default xdm environment You can configure this environment by creating a shell script in your home directory called .xsession and making it executable. If written as a Bourne shell script, the rules for writing the .xsession file are similar to those for the .xinitrc file used for xinit. Unlike .xinitrc, how- ever, .xsession does not have to be a Bourne shell script, it can be any executable. For infor- mation on configuring individual X sessions at the user level, see Chapter 2. See Section 3.7 for information on how to install xdm to start at boot time. 3.4 Troubleshooting xdm Problems with logging in via xdrn might be traced using xdrn error messages. Many errors are placed in the file/usr/lib/X11/xdm/xdm-errors, but if you are using R5 xdm, the first place to look is in the file $HOME/.xsession-errors. $HOME/.xsession-errors contains errors generated only under your user account. In addition, some of the more common situations are listed here: If the server doesn't start or if you don't get the login box, there is probably something wrong with your xdm configuration files. Kill xdm from the alternate login we recom- mended in Step 2, and look in the file/usr/lib/X11/xdm/xdm-errors for hints. Good candi- dates for mistakes of this magnitude are the Xservers, xdm-config, and Xaccess files. If The X Display Manager 49 xdm proper. An example of a resource like this is DisplayManager. servers, for specifying which file should be used for listing the X servers to be managed by xdm. You can think of this sort of resource name as applying to xdm's behavior independent of its connection to any particular X server: which servers to connect to, where to copy its pro- cess ID, where to put error messages, etc. The second form is used to specify a resource that should apply to a single display server only. Here's where the tricky part to resource naming rules for xdm comes into play: since the colon (:) has special meaning in resource specification syntax, the underscore (_) is used where these would normally occur in a display name. For example, the display name bigbird: 0 becomes bigbird_0 if it appears in a resource name. Without an underscore to specify that a particular server is being referred to, the name is taken to rep- resent a group of X servers, called a display class. See Section 3.5.6 for more information on display classes. The server for which you'd most want to define a specific resource is the local console display ( : 0, specified as _0 in resource specifications). An example of one of these is the DisplayManager ._0. authori ze resource--you usually want to enable access control on the local server, but you may not want it enabled on X terminals if they don't support that functionality. The third form of an xdm resource specification is really just a generalization of the sec- ond form. By putting an asterisk between the DisplayManager keyword and the vari- able name, where a display name would normally be, you can define this value for all servers not specifically defined otherwise. As a common example, you could use the fol- lowing lines: Di splayManager *authorize: false DisplayManager ._0. authorize: true and only the local display server will use access control. In resource lingo, these are called "loose" and "tight" bindings. We discuss resource bindings in detail in Appendix D. See your xdm manpage for a description of other resources that can be specified in the xdm- con.fig file. For testing purposes, you can use the -con.fig option to xdm to test new configuration files. For example, to start xdm with a customized configuration file, enter: # /usr/bin/X11/xdm -config ./my.xdm-config The DisplayManager.autoRescan resource controls whether xdm automatically rereads the configuration files after they have been changed. If set to true (the default), xdm will reread the xdm-cong file the next time a server connects to xdm. If set to false, then if you edit the xdm-cong file while xdm is still running, you have to send xdm a SIGHUP sig- nal before it will be reread. See Sections 3.6.2 and 3.6.3 for more information on sending a SIGHUP to xdm. 52 The X Window System Administrator's Guide 3.5.2 Listing X Servers (the Xservers File) 3.5.2.1 The Xservers file was originally designed in X11R3 to list all X servers to be managed by xdm. The XDM Control Protocol, introduced in R4, changes the function of the Xservers file significantly. Under X 11R3, all X servers managed by xdm required entries in Xservers. The only way xdm would know to connect to a server is if it appeared in the Xservers file at startup. In that way, Xservers acted somewhat like an inittab for xdm. With X11R4 and XDMCP, the X terminal takes responsibility for querying the host for an xdm connection. For that reason, any X terminal that supports XDMCP should have its entry removed from Xservers on a host running X 1 I R4 or later. The Xservers file is not yet obsolete, however. It is still used to start the X session on the local console display, which does not normally use XDMCP queries. It is also used to tell rdm how to start up the X server on the local machine. Xservers Syntax The syntax for each line in the Xservers file varies on whether it's for a server that runs on the local machine, and whether a display class is specified in Xservers for that machine. The only X servers that you need to enter into the Xservers file are those that do not use XDMCP to request a connection. For the most part, the only X server that needs to be specified in Xservers is the console display server. If your console display server is R4- or R5-compat- ible, it probably supports XDMCP queries but does not have them enabled by default. So you need to enter the local server into the Xservers file if you want it to be managed by xdm: :0 local /usr/bifi/Xll/X The console display name, :0, is followed by the word local to tell xdm that it's an X server running on the local machine, and then by the command used to start the X server. This command,/usr/bin/X11/X, is executed when xdm is started up. /usr/bin/X11/X is usually a symbolic link to another server program.* Since X terminals run their server on another machine, they have a slightly different syntax in Xservers. You only need to enter X terminals in Xservers if they don't support XDMCP or if you're running R3 xdrn on the host. The following are examples of Xservers entries for X ter- minals: ncdl: 0 foreign NCD xterminal visuall : 0 VISUAL-XI9TURBO foreign Visual xterminal bigbird: 0 XNCDI9r foreign Eileen' s xterminal *An example of when this would be useful is for a '386 workstation, on which any number of third-party monitors might be installed, requiring multiple servers to support them all. Among the steps required to install a new monitor may be to link X to a different server program. The X Display Manager 53 Managing Another Workstation's Display It's common to use xdm on a given host to manage X terminals, but what if you want it to manage the display server on another workstation? This can be done, it just needs a little coordination between the two hosts. For example, if you want to set up a host rock to manage the display of the workstation scribe, you have to do the following: 1. First of all, make sure xdm isn't being run on the workstation scribe, since you prob- ably don't want it running. If for some bizarre reason you do want it running, make sure that the local server isn't listed in the Xservers file on scribe--that is, if xdm is running, make sure the following is commented out in Xservers: #:0 local /usr/bin/Xll/X 2. You have to decide which end you want to start the xdm connection on. a. If you want to start the connection on the server side, have the X server started with an active XDMCP query. % /usr/bin/X11/X -query rock.west, ora. com If you want to set it up permanently, put this command in/etc/rc.local. The -query option tells the X server to place a Direct XDMCP query to the speci- fied host. Use the -indirect option in place of -query for an Indirect query to the specified host--for example, to get a chooser box from R5 xdm (see Section 3.5.3.2 for more information on the chooser client). You can also use the -broadcast option for a Broadcast query, in which case the first xdm host who replies to the query gets control of the server. The -broadcast option is not fol- lowed by a hostname. b. If you want to start the connection on the host side, put in the Xservers file on the host running xdm (rock in this example): scribe: 0 foreign X server on workstation "scribe" And have the X server on scribe started "passively", such as: % /usr/bin/Xll/X (Again, to set it up permanently, put this command in/etc/rc.local.) As a policy, it's probably better to have the connection started via an XDMCP query and avoid explicitly listing hosts in Xservers. A disadvantage to listing hosts in Xservers is that you have to make sure that you don't end up having the same server listed in two Xservers files on two different hosts. If you see the following error in the/usr/lib/X11/xdm/xdm-errors file: error (pid n) : WARNING: keyboard on display ... could not be secured what might have happened is that another host has the server listed in its Xservers file and is currently running xdm on the same X server. 54 The X Window System Administrator's Guide *. ora. com : harry, ora. com In its MIT-distributed form, the Xaccess file is configured to allow Direct and Broadcast con- nections from all X servers: #any host can get a login window 3.5.3.2 Indirect Access and the Chooser Until R5, the distinction between Direct and Indirect queries was poorly defined--there didn't seem to be any difference between connecting via a Direct query or an Indirect query to a particular host. The R5 Xaccess file changes that. An Indirect query basically allows xdm on the host to determine what to do with the query. If xdm encounters a Broadcast or Direct query, it either pops up a login box or it doesn't (depending on whether the node is allowed access in the Xaccess file, as described above). Responding to an Indirect query, however, the Xaccess file gives the administrator a chance to configure whether to respond directly, whether to pass the query on to another host, or whether to give the user a choice between multiple hosts. For example, to configure xdm to transfer an Indirect query from any NCD X terminals (named ncdl, ncd2, etc.) directly to the host ruby.ora.com, you might enter in Xaccess: ned*. ora. com ruby. ora. com Alternatively, you can set up xdm to respond to Indirect queries with a chooser box. This gives the user the opportunity to choose between several hosts, as shown in Figure 3-6. The chooser client, implemented via the CHOOSER keyword in the Xaccess file, is a big plus in R5. To allow the NCD X-terminals to choose from harry.ora.com, ruby.ora.com, and rock.west.ora.com, enter into gaccess: ncd*.ora.com CHOOSER harry.ora.com ruby.ora.com rock.west.ora.com The chooser box would resemble the box in Figure 3-7. The chooser client itself resides in/usr/lib/Xll/xdm, with everything else. Note that unlike the other files in that directory, it is not a readable ASCII file, but a compiled executable. Yet another possibility might be to set up the chooser client so it just does a broadcast among all hosts on the network and allows the user to choose among them. To do this, just use the keyword BROADCAST following the CHOOSER keyword. ncd*. ora. com CHOOSER BROADCAST To customize the appearance of the chooser client, use the Xresources file. The default Xresources file defines the following resources used by the chooser client: Chooser*geometry: Chooser *al lowShel iResize: Chooser*viewport. forceBars : Chooser*label. font: Chooser*label. label : Chooser*list. font: Chooser*Conmand. font: 700x500+300+200 false true *-new century schoolbook-bold-i-norr0al-*-240-* XZ/4CP Host Menu from CLINrfHOST * * * * * * * - - -medium-r-normal- - -230- - -c- -iso8859-i *-new century schoolbook-bold-r-normal-*-180-* The X Display Manager 57 3.5.3.3 Using Macros The Xaccess file allows you to define macros to group together a set of hosts. A macro defini- tion starts with a percent character (%), followed by the macro name, followed by a list of hostnames (with a backslash at the end of the line signifying that the definition continues onto the next line). The macro is then called later on, preceded by the %. An alternative way of allowing X terminals to choose among harry, ruby and rock might be: %NCDHOSTS harry, ora. ccn ruby. ora. ccn rock.west, ora. ccn ncd*. ora. ccn CHOOSER %NCDHOSTS 3.5.3.4 Advantages and Disadvantages of the Chooser The big advantage that the Xaccess file provides is that it can make it much easier to maintain and control X terminals on a network. Without the chooser, the host to query is configured directly on the setup menu of an X terminal using XDMCP. If you want to move the manage- ment of some X terminals to another host, it may involve personally visiting each terminal and editing their setup menus manually, step-by-step. However, using the Xaccess file, you can simply set up a single host as the primary xdm server, designed to accept Indirect queries and determine where they should be transferred. Using this scheme, switching xdm manage- ment from one host to another is a matter of editing a single file. In our bicoastal environment, we use the chooser to allow East Coast employees to access their environments from the West Coast without having to do contortions: they simply choose the East Coast xdm host and they are greeted by the same friendly login box they're used to at home. A problem with the chooser functionality is that due to a bug in R4 xdm, it can be used only to transfer xdm control to another host running R5. For example, if you had in your Xaccess file: %R5HOSTS harry.ora.ccn ruby.ora.ccn rock.west.ora.ccn %R4HOSTS opal. ora. ccn * CHOOSER %R5HOSTS %R4HOSTS with opal running R4 xdm, the chooser box would look like the one in Figure 3-8. Note that only the R5 hosts (harry, ruby and rock) are reported as "Willing to manage." If you select one of the R5 hosts you'll get the xlogin box as expected; but although the R4 host is listed, if you select opal you'll be temporarily "'hung" and then you will be returned to the chooser box without a chance to log on. Note that like the xdm-conjhg file, the DisplayManager. autoRescan resource controls whether xdm automatically rereads the Xaccess file if it has been changed, or requires a SIGHUP signal before it rereads configuration files. By default, any configuration files that have been changed are automatically reread when the next server connects to xdm. A mes- sage appears in the xdm-errors file: info (pid 1564): Rereading access file /usr/lib/Xll/xdm/Xaccess See Sections 3.6.2 and 3.6.3 for more information on sending a SIGHUP to xdm. The X Display Manager 59 XDMCP Host Menu from rock hosL opal Ui 11 ing Lo manage Ui 11 ing Lo manage Ui 11 ing to manage 3.5.4 Figure 3-8. Chooser box with an R4 host The Xresources File The Xresources file is loaded into each individual X server as it is connected to xdm. The most important function of the Xresources file is to set resources for clients or widgets that are run before the user actually logs in. In particular, the xlogin widget's resources need to be loaded into the server by xdm itself, since it is (by necessity) run before the user logs in. In RS, the chooser and xconsole clients may also be run before the user logs in, so those clients need their resources specified in Xresources as well. As each X server connects to xdm, the resources in the Xresources file are loaded by the server via the xrdb client. See Section D. 1.3 for more information on xrdb. 3.5.4.1 Configuring the Login Box The login box displayed on an X server controlled by xdm can be configured using the Xresources file. In its default configuration, that file contains thefollowing lines: xlogin*login.translations: #override\ CtrlR: abort-display()\n\ Fl: set-session-argument(failsafe) finish-field()\n\ CtrlReturn: set-session-argument(failsafe) finish-field()\n\ Return: set-session-argument() finish-field() xlogin*borderWidth: 3 60 The X Window System Administrator's Guide xlogin*greet ing: CLIENTHOST xlogin*namePropt: login: \ xlogin*fail: Login incorrect #ifdef COLOR xlogin*greetColor: CadetBlue xlogin* failColor: red *Foreground: black *Background: #fffff0 #else xlogin*Foreground: black xlogin*Background: white #endif The resources starting with the string xlogin are used by the xlogin widget, xlogin sends the box to the display, prompting the user for a name and password. The xlogin box typically resembles Figure 3-3. Note that the first resource for xlogin is a translation table, used for defining how special keystrokes might be used within the client. (See Section D. 1.4 for more information on translation tables.) This translation table is particularly important. What it does is to allow you to log in without running your .xsession file, by pressing F1 after your password instead of RETURN.* Instead of running your .xsession, pressing F1 tells xdm to run a "failsafe" X session, defined as a single xterm window. (You can actually change this in the Xsession file. See Section 3.5.5 for more information on the Xsession file.) This is important, since otherwise you may have no way of logging in if your .xsession is corrupted. The other important translation listed here is that you can use CTRL-R to stop :drn from managing your display entirely. This feature, new to RS, is useful for the local console dis- play, where you might want to return to the console to start another windowing system or load a different X server image. Note that this only works if the X server isn't initiating XDMCP queries; otherwise, CTRL-R will abort the current xdrn connection, but a new one will instantly replace it. The remainder of the resources set for xlogin are fairly straightforward, used largely to spec- ify the messages used for prompts and error messages. Note that since this resource file is loaded into the server via xrdb, cpp pre-processor commands (particularly #ifdef, #else, and #endif) can be used. In the R5 default shown above, the pre-processor commands are used to specify how the xlogin box should appear, depending on whether the display has color support. COLOR is one of the variables that are pre-defined in R5 xrdb; see Section D. 1.3 for more information on xrdb pre-defined variables. One resource you may want to change is the greeting in the xlogin box. In previous releases of X11, this box said "Welcome to the X Window System" by default; in RS, it simply gives the hostname, as shown in Figure 3-3. If you want to change this greeting, edit the resource definition: xlogin*greeting: CLIENTHOST * Alternatively, in R5 you could also enter CFR-RETURN, for those users who don't have an F1 key. The X Display Manager 61 3.5.5.1 We told you that this key translation set things up so if you typed FI or CTRL-RETURN after your password instead of RETURN, you would avoid running your .xsession script and would get a lone xterrn instead. Now you know how that gets implemented. Admin- istrators can use this as a model to write translations that pass other arguments for Xses- sion to interpret. Next, the script looks for a script in the user's home directory called .xsession. If it exists, it execs it. If the .xsession script doesn't exist, the Xsession script creates a workable X session by first looking for a resource file called .Xresources, and if that file exists, loading it with xrdb; regardless, it then starts the twrn window manager and a single xterrn window. This is actually a fairly simple script, when you consider that it controls every X server con- necting to xdrn. It also gives the administrator an unusual amount of power over each X ses- sion. At the most innocuous, an administrator could use the Xsession file to add some func- tionality that all users may need--for example, to add a local font directory into font paths using the xset client. At a slightly more intrusive level, the administrator could use it to set up a message-of-the-day client for users to see when they first log in. But there are really no lim- its-an administrator could set up a network so that users have no control at all over their own X sessions (by removing the line that executes .xsession), and in fact don't have xterrn windows to start new clients (presuming that all they'd want to do is run a mail client and a word processor). Note that the Xsession script is defined as a loose binding, DisplayManager*session. You could therefore set up a separate X session file for particular X servers. For example, you might want to set up an X session file called Xsession_O: DisplayManager ._0. session: Xsession_0 The only difference in Xsession_O might be that the xterrn called in the failsafe situation would be called with -C, so that console messages will be diverted to this xterrn window: exec xterm -gecmetry 80x24+i0+i0 -is -C (See Sections 4.6.1 and 4.6.2 for more information on the xterm console window.) You can also use display classes to group several X terminals together. See Section 3.5.6 for more information on display classes. No Home Directory? (R5) The redirection of error messages to $HOME/.xsession-errors is a nice addition to R5--it means that if users are having problems, they don't need to weed through the systemwide xdm-errors file, but can start looking for problems locally. This makes life easier for users and administrators alike. However, it does present a problem if for some reason you don't have a home directory on the host. Since Xsession is executed as a Bourne shell script, the line: exec > $HOME/.xsession-errors 2>&l 64 The X Window System Administrator's Guide produces a fatal error if it cannot be completed. One reason that may happen is if you don't have a home directory, either because it's a new machine or because there is a problem with your NFS link. The shell tries to create a file in a directory that does not exist and when it can't, the script aborts. The effect is that the user logs in and is immediately bumped out with no sign of what happened except in xdm-errors: error (pid 2547): can't lock authorization file /home/imui/.Xauthority or backup /us r/i ib/Xl i/xdm/. Xautha02547 error (pid 2547): No home directory /home/imui for user imui, using / /usr/lib/Xll/xdm/Xsession: /home/imui/.xsession-errors: No such file or directory error (pid 2549) : fatal IO error 32 (Broken pipe) To remedy this situation, you might change the line in Xsession to read: if [ -d $HOME -a -w $HOME ] then exec > $HOME/.xsession-errors 2>&l fi 3.5.6 Display Classes Display classes provide a way to group together several X servers connecting to the same host. The display class is built into the X server, and is presented to xdm when the X server connects via XDMCP. To find out the display class for a given X terminal, you can look it up in the documentation or ask the manufacturer; or, if it won't disturb any users, kill xdm and then restart it at a high "debug" level: # /usr/lib/Xll/xdm -debug 9 Running xdm at this level of debugging is likely to give you far more information than you really want. Among this stream of messages, however, is information about any X server that connects to xdm, including its display class: Starting display visual5, ora. com: 0,VISUAL-XI9TURBO This tells us that the Visual X terminal we're experimenting with is in the display class VISUAL-X19TURBO.* Display classes come in useful in allowing you to fine-tune your xdm configuration differ- ently according to the display type. Thus far, almost all our examples of display-specific resources have been about the local display server, _0. However, because of hardware pecu- larities, there are situations when you would want to set resources for individual X servers or for a group of X servers. For example, the Visual X19TURBO terminal has 2-bit gray scale support. This is nice, except that it confuses FrameMaker into thinking it has color support. FrameMaker therefore tries to show menus with its color defaults of black text on blue background; the X terminal * In x I 1R3, XDMCP was not available, so the Xservers file was used to explicitly list the display class used by an X server; see Section 3.5.2.1 for more information. The X Display Manager 65 3.6.2 Restarting xdm Using xdm-pid (R4 and Later) In R4 and R5, the xdm process ID is stored in whatever file is pointed to by the Display- Manager .pidFile resource, xdm-pid in the default configuration. If you are running R4 or R5, you can use the xdrn-pid file to send a signal to xdrn. This file contains the process ID of xdrn. # cat /usr/lib/Xll/xdm/xdm-pid 28683 You can send xdm the SIGHUP signal by using the cat output directly: # kill -HUP "cat /usr/lib/Xll/xdm/xdm-pid" The xdm process should now reflect the current configuration files for any new sessions. If xdrn becomes unusable and you are not able to fix it by editing the configuration files, you can kill it for real. (You'll have to use a more severe signal (SIGTERM) to tell it you are seri- ous.) # kill -TERM "cat /usr/lib/Xll/xdm/xdm-pid" Beware that all active sessions managed by xdrn will be killed if you use SIGTERM. 3.6.3 Rereading xdm Configuration Files (R3) To force xdm to reread its configuration files on an R3 system, you need to find the process ID ofxdm manually in order to kill it. First find the process ID of the parent xdm process using the ps command. Then send the SIGHUP signal to the process. % ps agxlgrep xdm 2547 ? IW 0:30 -xterml:0 (xdm) 13511 13757 15199 19175 19466 28683 28685 28743 17796 ? IW 0:56 -xterm2:0 (xdm) ? IW 0:58 -xterm4:0 (xdm) ? IW 1:08 -xterm5:0 (xdm) ? S 1:51 -xterm7:0 (xdm) ? IW 2:08 -xterm3:0 (xdm) ? IW 0:09 /usr/bin/Xll/xdm ? S 2:07 -xterm9:0 (xdm) ? IW 0:00 /bin/sh /usr/lib/Xll/xdm/Xsession p0 S 0:00 grep xdm The parent xdm stands out, since the xdm processes associated with a particular display change their names to the name of the display. (The arguments to the ps command, as well as its output, will vary according to the flavor of UNIX you are running.) If you send signals to the wrong xdm process, only the display being controlled by that xdm process will be affected. 68 The X Window System Administrator's Guide Controlling scologin scologin (the version of xdm on Open Desktop, which runs on SCO UNIX machines) has its own ways of starting and restarting the display manager. The scologin daemon has a front end,/etc/scologin, which takes the following options: start Starts the scologin process; if scologin is already running, the start com- mand will cause scologin to reread the configuration files Xconfig, Xservers and Xresources. reread If scologin is already running, the reread command will cause scologin to reread the configuration files Xconfig, Xseta'ers and Xresources. stop Stops scologin. All X sessions currently managed by scologin will be halted. query Returns the current status of scologin. disable Stops scologin and disables it from restarting when the system reboots. enable Starts scologin if not already running, and ensures that it will start automati- cally at the next reboot. init If scologin is enabled, the gett>, processes on terminals configured for scolo- gin are disabled. This option should be run only by init at boot time. For example, to have your configuration files reread, enter: # /etc/scologin reread 3.7 Permanent Installation of xdm When you are happy with your xdm setup, it is time to install it so it will start automatically when the system boots. The way you do this is system dependent, but it is the same procedure as adding any other kind of daemon. In a typical BSD system, you would modify the /etc/rc.local script. Under System V, edit/etc/inittab. (Remember to keep backup copies of any system files you modify!) Here are a few examples of installing xdm on various platforms: Installing xdm on SunOS 4.1.1 Add xdm to/etc/rc.local: if [ -f /usr/bin/Xll/xdm ]; then /usr/bin/Xll/xdm; echo -n "XDM" fi Then reboot the system. The X Display Manager 69 Installing xdm on Uitrix 4.2 Add xdm to/etc/rc.local: [ -f /usr/bin/Xll/xdm ] && { /usr/bin/Xll/xdm & echo -n "xdm " > /dev/console } Then reboot the system. Installing xdm on a System V Machine (IRIX 4.0) (Your system may already be set up for running xdm as shipped. Check before contin- uing.) Add xdm to/etc/inittab: xw: 2 3 : respawn:/usr/bin/Xll/xdm -nodaemon Then reboot the system. Installing xdm on AIX 3.1 Add xdm to/etc/rc.tcpip: start /usr/bin/Xll/xdm "$src_running" Then reboot the system. 3.8 Related Documentation For more detailed information on xdm and its resources, see the xdm manual page. For documentation on XDMCP, look in the X source distribution, in mit/hard- copy/XDMCP/xdmcp.PS.Z. "The X Administrator: Taming the X Display Manager," by Miles O'Neal, published in The XResource, Issue 4, O'Reilly & Associates, Inc., Fall 1992. 70 The X Window System Administrator's Guide 4 Security Because X runs in a networked environment, it's particularly important that administrators be aware of its security lapses and how to reduce the risks of running X. This chapter discusses security issues as they relate to X. In This Chapter: Host-based Access Control ................................................................. 74 The/etc/Xn.hosts File ...................................................................... 74 The xhost Client ............................................................................... 75 Problems with Host-based Access Control ....................................... 76 Access Control with MIT-MAGIC-COOKIE-1 ............................................ 77 Using MIT-MAGIC-COOKIE-1 with xdm ............................................... 78 The xauth Program .......................................................................... 79 Using MIT-MAGIC-COOKIE-1 with xinit ............................................... 81 xauth vs. xhost ................................................................................ 82 The XDM-AUTHORIZATION-1 Mechanism (R5) ...................................... 83 The SUN-DES-1 Mechanism (R5) ......................................................... 84 Public Key Encryption ...................................................................... 85 Prerequisites for Using SUN-DES-1 ................................................... 86 Using SUN-DES-1 with xdm .............................................................. 88 Using SUN-DES-1 with xinit ............................................................... 89 Adding Another User with SUN-DES-1 .............................................. 91 xterm and SUN-DES-1 ...................................................................... 92 Troubleshooting SUN-DES-1 ............................................................. 92 xterm and Secure Keyboard ................................................................ 93 Other Security Issues .......................................................................... 94 The Console xterm (R4 and Earlier) ................................................. 94 The Console and xdm (R5) .............................................................. 95 Hanging the Server Remotely (R3) .................................................. 96 Reading the Framebuffer (Sun Workstations) ................................... 96 Removing Files in/tmp .................................................................... 97 The Network Design ........................................................................ 97 Related Documentation ....................................................................... 98 4 Security X runs in a networked environment. Because of X's design, your workstation is no longer your private preserve but hypothetically can be accessed by any other host on the network. If you are on the Internet, your display may be accessible world-wide. This is the true meaning of the server concept: your display can serve clients on any system, and clients on your sys- tem can display on any other screen. The possibilities for abuse are considerable. When our office was introduced to X 11, one of the first things we learned how to do was to play pranks on one another. Call it a "learning experience"--we became familiar with X by sending prank clients to remote servers: xmelt to make someone's screen melt away, xsetroot to put a giant bitmap picture of our boss on someone else's root window, etc. When we got a hold of anything "neat" (e.g., kaleidoscope, a GIF file of Bart Simpson, a bitmap of Bill the Cat), we fired it off to a friend's display to amuse him, and then ran down to his office to see his reaction. If this scares you, it should. Within our office, among our friends, we had no intention of hurting anyone, and if anyone seemed busy or grouchy we left them alone. But if good inten- tions were enough, none of us would have passwords for our accounts. Having unlimited access to someone's display leaves a lot of potential for serious damage. Our pranks involved clients that the user could see, be amused (or annoyed) by, and then promptly kill. However, if you can run one client on a display then you can run any other client on that display. The X Window System design allows any client that successfully connects to the X server to exercise complete control over the display. This means that clients can take over the mouse or the keyboard, send keystrokes to other applications, or even kill the windows associated with other clients. It is difficult to make X completely secure. However, there are four access control mecha- nisms, one host-based and three user-based. The host-based scheme involve a system file (/etc/Xn.hosts) and can be controlled using the xhost client. The user-based schemes involve authorization capabilities provided by the xauth program and by the X Display Manager Control Protocol (XDMCP). There is also a "secure keyboard" feature in the xterm terminal emulator that can provide protection against some problems. Security 73 4.1 Host-based Access Control One way of protecting against unauthorized clients is to use host-based access control, shown in Figure 4-1. The way this works for workstations is that, by default, the server running on the local workstation only accepts clients that are running on that workstation. For example, the local display sapphire : 0, which runs on the console of the host sapphire, would only accept clients started on sapphire. For the local display server of a workstation, the list of hosts that can send clients to display on sapphire:O can be supplemented by adding a hostname to the/etc/Xn.hosts file (where n is the number of the display), or by using the xhost client. Many X terminals also support host- based access control (sometimes called "TCP/IP access control"), with the list of hosts speci- fied on the setup menu or uploaded via remote configuration from the host. Hosts opal.ora.com sapphire.ora.com ccavax.camb.com X server sapphire:O Network OK .J Client Program o .......... --. -- =--'r .... t Client Program  Denied Figure 4-1. Host-based access control 4.1.1 The/etc/Xn.hosts File The/etc/Xn.hosts file contains a list of systems that are allowed to access local server n. On most workstations, only one server runs at a time, so/etc/XO.hosts is the only file you need to be concerned with. This list of hosts is read by the server at startup time. The/etc/XO.hosts file can be edited so that it contains the list of systems you want to allow access to your server on a regular basis. For example, the file/etc/XO.hosts on the host sapphire might con- tain the following: opal. ora. ccn sapphire, ore. cn ccavax, camb. ccm 74 X Window System Administrator's Guide Needless to say, we strongly discourage you from doing this. You can use the xhost client to enable access from a specific host only long enough to start up clients from that host, and then disable access immediately. For example, a script might do something like this: xhost +sapphire rsh sapphire xterm -display reno: 0 sleep 15 xhost -sapphire You can also use the remote host's IP address instead of the hostname. % xhost +140.186.65.13 The IP address is useful when the remote hostname isn't known to the name server. (The name server translates domain names into IP addresses.) Also, in the rare case when a host is on two different networks and has two different IP addresses, xhost may get confused. You might have to explicitly specify the IP address the host uses on the current network. (The better solution is to fix the problem for good, by re-linking X with updated resolver libraries; but in the interim, using the direct IP address may do the trick.) If the above description left you in the dark--if you don't know name servers from X servers, and IP addresses are greek to you--consult the Nutshell Handbook TCP/IP Network Administration by Craig Hunt (O'Reilly & Associates, 1992). 4.1.3 Problems with Host-based Access Control Host-based access control is better than nothing, but it has some basic conceptual problems that make it insufficient for true security. One problem is that, while the primary reason for denying a remote system access to your display is to prevent a person working on the remote system from displaying on your server, this also prevents you from running clients from that remote system on your display. So you have to deny yourself functionality in order to deny it to others. The main problem with host-based access control, however, is that it's easy to get around. It's a great idea if workstations are really single-user machines, where only the person who actually uses a given host has an account on it. But on today's UNIX networks, you are proba- bly running yellow pages (NIS) to simplify account allocation and file permission issues. On these networks, as long as a prankster has an account on one of the hosts you do allow access from, xhost provides no protection. Any user with an account on your machine (or any other host your server allows access to) can access your display. On an X terminal, host-based access control makes even less sense. X terminals are depen- dent on a host to run almost all of its clients. That host is often a compute server used to sup- port several other X terminals as well. So X terminals that support host-based access control generally need to list a host with many other users on it, meaning that all those users can access each others' displays. This is still better than nothing, but definitely not secure. If you're running Secure RPC, you can use the SUN-DES-1 method of security and use xhost to give access to a particular user in a given domain, such as "xhost +dave@ora. com." This is really the best way to control access to a server, since it is entirely user-based. Not all 76 X Window System Administrator's Guide machines support Secure RPC, however. See Section 4.4 for more information on SUN- DES- 1. 4.2 Access Control with MIT-MAGIC-COOKIE-1 With Release 4 of X11, a user-based access control mechanism can be used to supplement or replace host-based access control. User-based access control is built into the XDM Control Protocol (XDMCP), but it can be used independently of xdm. In Section 4.2.3, we show how you can use it with xinit. In addition, it is automatically enabled when the openwin server is started under OpenWindows. The most common method of user-based access control (and the only one available under R4) is a mechanism known as MIT-MAGIC-COOKIE-I. This scheme might be called permis- sion-based rather than user-based, since it depends on UNIX file permission more than any- thing. If both the host and the X server are configured to use MIT-MAGIC-COOKIE-1, then when you log in using xdm, a machine-readable code is put in a file called .Xauthorit" in your home directory, belonging to you. This is shown in Figure 4-2. This code, called a magic cookie, is also told to the server. The magic cookie code can be thought of as a password known only to the server and to the user who logs in using xdm. Users don't have to actually type the code at any point, they just need to be able to run the programs that manipulate it. X server Host Figure 4-2. XDMCP and the access code Once the code is established for that X session, a client must present the code before it is allowed to connect to the server. The client gets the code by reading the .Xauthorit).' file in the user's home directory. This file has the permissions "-rw ....... ", meaning that it can be read and written only by the owner. The MIT-MAGIC-COOKIE-1 mechanism therefore takes advantage of the fact that all processes started by a user inherit that user's permissions. Figure 4-3 shows a user who does not have access to the code being rejected. Secud 77 Access Code #A#OMIT-MAGIC-COOKIE567.. Network OK #A/OMIT-MAG IC-COOKIE567.. i | ! ! X server - 1 ! Denied Host --J /home/fred/.Xauthority i %,/h_0n]e/bo.b!iXautho rity i Figure 4-3. User-based access control Since this type of access control is based entirely on UNIX file permissions, it is only as secure as the user's account--if you don't have a password, for example, it's totally useless since anyone can log in as you and then do whatever they want to your server. User-based access control is clearly more secure than host-based access control, but it depends on the server being programmed to take advantage of it. Not all X terminals are cap- able of using the magic cookie. Furthermore, magic cookie-type access control is tightly bound to the operating system, which is not in the spirit of X. 4.2.1 Using MIT-MAGIC-COOKIE-1 with xdm In Chapter 3, we discussed the resources for xdrn specified in the xdrn-con.fig file. In addition to pointers to several special files, the xdrn-con.fig file contains these resource specifications: DisplayManager ._0. authorize: true DisplayManager *authorize: false The first resource specification turns on authorization for the local display. The second one turns the scheme off on all other displays. To turn authorization on for any other servers that are connected to the host, change the second resource definition: DisplayManager *authorize: true xdrn is probably configured to reread the configuration file on its own (by setting the DisplayManager.autoRescan resource, which is on by default), but if not, you can send xdm a SIGHUP so it will reread its configuration file: root# kill -HUP "cat lusrlliblXlllxdmlxdm-pid" 78 X Window System Administrator's Guide In addition to this, some X terminals need to be explicitly configured to use MIT-MAGIC- COOKIE-1. See your X terminal's documentation for more information. 4.2.2 The xauth Program A problem with user-based access control is that it relies on all your clients having access to the magic cookie. This is reasonable to expect if you run all your clients on the same host or if your home directory is shared (for example, using NFS or AFS) across all the hosts you run clients on. Since all the necessary information is in your $HOME/.Xauthority file, you can access your server from all hosts with the same shared home directory. But what about the situation when you want to run clients from a host that does not have a shared home directory? The solution is a program called xauth, used to propagate the magic cookie from one host to another. The most common use for xauth is to extract a user's authorization information for the current display, copy it to another machine, and merge it into the $HOME/.Xauthority file on the remote machine, as shown in Figure 4-4. From a host where the user already has the magic cookie listed, this can be accomplished with the following command line: % xauth extract - $DISPLAY I rsh remotehost xauth merge - For example, to share the authorization information for the reno : 0 display with your user account on the host ruby, type: % xauth extract - reno:O I rsh ruby xauth merge - The extract function takes the magic cookie from the .Xauthority file in your home directory on reno. Since you may be logged on at several different displays at once, you need to spec- ify which display you want io extract the magic cookie for. In the example above, we want to extract the magic cookie for the local display server, reno:0. By using a dash (-), the magic cookie is written to standard output. The xrsh Command If you run remote clients using the xrsh shell script provided in the R5 contrib/cli- entsLrrsh directory, xauth is automatically run to propagate the magic cookie code to the remote machine before the remote client is started. For example: % xrsh -auth xauth ruby xterm starts up xterm on the host ruby after first using xauth to transfer the cookie. If you use host-based access control, xrsh can also give the remote host access to the server. This is the default behavior: % xrsh -auth xhost ruby xterm You can also set the XRSH_AUTH_TYPE environment variable to specify which type of authorization you need enabled for the remote host. The default behavior is for ,:host authorization. Security 79 Access Code #A#OMIT-MAGIC-COOKIE567.. X server "reno:O" Figure 4-4. Propagating the magic cookie between two hosts The xauth merge function accepts magic cookie codes from the specified file--in this case, from standard input. It then merges that information into the SHOME/.Xauthority file on that system. Since only you have access to the magic cookie for your server, only you can successfully run xauth to send that code to another host. Particularly picky readers might point out that technically, xauth is not a client program since it never contacts the X server itself, but is simply used to manipulate the .Xauthority file. Our examples so far have only shown how to use xauth to extract the magic cookie code from a local machine and merge it into a remote one. But it's just as easy to do it the other way around. In the following example, we rlogin to a machine called rock, try to run an xterrn window, and when we are rejected we simply copy the magic cookie and try again. Note that as far as the shell is concerned, reno is now the remote machine and rock is the local one, so rsh needs to be called on the xauth extract command. imui@reno 79% rlogin rock Last icgin: Fri Sep 18 07:27:17 frcn ruby.ora.ccn SunOS Release 4.1.2 (ROCK) #I: Fri Sep II 17:56:56 PDT 1992 imui@rock % xterm -display reno:0 Xlib: connection to "reno:0.0" refused by server Xlib: Client is not authorized to connect to Server Error: Can't open display: reno:O imui@rock % rsh reno xauth extract - reno:O  xauth merge - imui@rock % xterm -display reno: 0 & (client runs successfully) It's also possible to copy a code from one host to another from an uninvolved third host, but it's hard to come up with a circumstance in which you'd need to do that. 80 X Window System Administrator's Guide AUTHORIZATION-l, you need to build xdm with the implementation of DES in mit/lib/Xdmcp/Wraphelp.c.* You should also make sure that the Ha.XdmAuth build flag is set to YES. See Section A.2 for information on how toftp a file. Once you are sure that xdm supports XDM-AUTHORIZATION-1, you can enable it on the local display server by simply redefining the Di splayManager ._0. authName resource in the xdm-config file. (By default, the MIT-MAGIC-COOKIE-1 mechanism is used.) The autho- rize resource must also be turned on. DisplayManager * authorize: true DisplayManager ._0. authName: XEM-AUTHORIZATION- 1 Note that we only redefined the authName resource for the local display, : 0. At this writ- ing, no X terminals support this mechanism/f The authName resource actually accepts a list of authorization schemes which xdm will use in order, so you could also just set the fol- lowing global resource: DisplayManager* authName: XEM-AUTHORIZATION- 1 MIT-MAGIC-COOKIE- 1 After the xdm-config file is reread by xdm, xdm will use XDM-AUTHORIZATION-1 for the local display server. As with MIT-MAGIC-COOKIE-1, the server is started with the -auth option and the code is placed in the .Xauthority file. In this case, however, the code consists of two parts, a 56-bit encryption key and 64 bits of random data. Once you log in using xdm and XDM-AUTHORIZATION-1, check that you're using access control properly with xauth list: eap % xauth list nugget.west.ora.cn:0 XEM-AUTHORIZATION-I bd4dc546c869a81fOO979e36956f6c95 nugget/unix: 0 XI4-AUTHORIZATION-I bd4dc546c869a81fOO979e36956f6c95 Note that XDM-AUTHORIZATION-1 is only available for X sessions that are managed by xdm. 4.4 The SUN-DES-1 Mechanism (R5) The SUN-DES-1 server access control scheme uses the Data Encryption Standard (DES) for encryption of authorization data. This scheme uses Sun's Secure RPC to pass authorization data across the network, and it uses NIS to maintain a database across the network. DES code has export restrictions, so it may not appear on systems outside of the U.S. Since SUN-DES-1 uses Secure RPC, you need to have Secure RPC installed before you can use it. Secure RPC, in turn, requires NIS (Network Information System). *If this file does not appear in your distribution but you can legally use it, you can get it via ftp from ex- port.lcs.rait.edu. The procedure is a little convoluted; see the file publR51xdra-authlREADME for information on how to obtain and incorporate the DES code. %If the X terminals initiate the connection using XDMCP, they will ignore the authNarao resource anyway. This re- source is only used for X servers that are listed in the Xservers file. When the XDMCP connection is initiated from the server side, xdra uses whatever authorization mechanism the server specifies at initiation. 84 X Window System Administrator's Guide SUN-DES-I gives you true user-based access control. Unlike the magic cookie and XDM- AUTHORIZATION schemes, the entire mechanism does not rely on the security of the .Xauthority file. You have to explicitly use the xhost command to add specific users to the list of users who can access your display. This gives you a degree of specificity that is unavail- able under the other schemes. 4.4.1 Public Key Encryption Before you can set yourself up to use SUN-DES-l, you need to understand a little about how Secure RPC works. Secure RPC is a system that uses both a public key and a private key. It uses a principal to identify an instance of a user. The principal is composed of the word unix combined with a user ID and the name of the current NIS domain: unix. @ If the NIS domain is omitted, the current domain is assumed. If you do not know your user ID, use the ypmatch command: % ypmatch eap passwd eap: z7xoeuD8WpyOG: 243 : I00 : Eric Pearce:/hcme/eap:/bin/tcsh The user ID is the third field of the passwd entry. In this example, our user ID is 243. If you need to learn the NIS domain name, use the domainname command. Note that although the NIS domain may be the same as the Internet domain, they are not related and do not neces- sarily correspond. % domainname west So in this example, the principal for user eap in the current domain would be: unix. 243@west Or, since the current domain is the default: unix. 2430 A special case is the principal for root. The principal for root uses the hostname in place of the user ID. For example, on the machine nugget, the principal for root is: unix. nugget@west The principal is stored with a public key in the public key database. The public key is truly "public"---take a look at the file/etc/publickey, which is world-readable: # # Sun Public Key Database # # To add an entry to this file, an administrator should use the NIS conmm%d # "newkey" on the Network Information Services master machine. # # Users can also insert their own entries into this file using the chkey # conmm%d. Comaenting out the "nobody  entry below disallows this feature, # and chkey will only allow users to change their existing entry, not create Security 85 Systems not running NIS will complain that ypbind isn't running: % ypwhich ypwhich: bigbird is not running ypbind For information on NIS, see Managing NFS and NIS by Hal Stem (O'Reilly & Associ- ates, 1991 ). The private key server, keyserv, must be running. This is usually started at system startup in/etc/rc or/etc/rc.local. Use the ps command to confirm that it is running: % ps agx I grep keyserv I grep -v grep 74 ? I-W 0 : 01 keyserv Each user of the Secure RPC system should have a unique public key entry. You can have each user to do this on their own using chkey: % chkey Generating new key for unix.243@west. Password: Sending key change request to nugget... Done. or the system administrator can create public keys for users with the newkey command: # newkey -u eap Adding new key for unix.243@west. New password: Retype password: Please wait for the database to get updated... Your new key has been successfully stored away. You can also create a new public key for root on a given host using newkey: # newkey -h nugget Adding new key for unix.nugget.west.ora.ccn@west. New password: Retype password: Please wait for the database to get updated... Your new key has been successfully stored away. You must propagate the public key information from NIS clients to the NIS master when you add or change a public key on the client. If you are running the rpc.ypupdated dae- mon, this will be done automatically. To see if the daemon is running: % ps agx I grep rpc.ypupdated I grep-v grep 70 ? IW 0 : 00 /usr/etc/rpc .ypupdated If you do not run rpc.ypupdated, chkey and newkey will not automatically update the pub- lic key map on the NIS master. If you have root permission on the NIS master machine, you can push the NIS map for publickey.byname on the NIS master manually: # cd /var/yp # make Security 87 It might be easier, however, to just enable rpc.ypupdated. You can make sure it will be enabled at the next reboot by adding it to/etc/rc.local: if [ -f /usr/etc/rpc.ypupdated -a -d /var/yp/$dname ] ; then rpc.ypupdated; echo-n ' ypupdated' fi Or you can uncomment it from/etc/inetd.conf: ypupdated/l stream rpc/tcp wait root /usr/etc/rpc.ypupdated rpc.ypupdated and kill -HUP inetd so it will be enabled right away: # ps agx I grep inetd I grep-v grep 197 ? IW 2:24 inetd # kill -HUP 197 You can use the SUN-DES-1 scheme only after you have an entry for your principal in the NIS master's public key map. This is also true for anybody else that wants to connect to your X server. 4.4.3 Using SUN-DES-1 with xdm Once you have confirmed that SUN-DES-1 works on your machine, you can set up xdm to use it on the local console display server the same way you set up xdm to use XDM-AUTHORIZA- TION-I as shown in Section 4.3. Make sure that the authorize resource is turned on and then redefine the Display- Manager._0. authName resource for the local display only: DisplayManager *authorize: true DisplayManager ._0. authName: SUN-DES- 1 When you next connect, xdm will set up the server for SUN-DES-1. After logging in, check using xhost: eap % xhost access control enabled, only authorized clients can connect eap@ (unix. 243@west) unix. nugget @west Note that not only are you listed under the xhost list, but so is the principal for root on nug- get, unix. nugget@west. The first line indicates the user with user ID 243 can connect to the server from any host within the NIS domain west. The second line indicates that root on nugget can connect. Don't remove the root principal from the xhost listing, since you'll need it if you want to run any setuid clients, such as xterm. See Section 4.4.6 for more information. If you do an xauth list, you'll see this special root principal listed again: eap % xauth list nugget.west, ora. ccm: 0 SUN-DES-I unix.nugget@west nugget/unix:0 SUN-DES-I unix.nugget@west xdm is run as root, and xdm is responsible for starting the server. Since the server is started as root, root is considered the "owner" of the server. 88 X Window System Administrator's Guide 4.4.4 Using SUN-DES-1 with xinit As with MIT-MAGIC-COOKIE-1, you need to do a little of the dirty work yourself if you want to use SUN-DES-I with xinit. First we'll show the procedure by hand, and then we'll show how to automate it using .xinitrc. This example is on a machine with a local display named nugget. User eap has a user ID of 243, and the NIS domain name is west. 1. Start with a clean .Xauthority file: nugget% rm -f .Xauthority 2. Create an entry for each type of connection from your host to your server. Use xauth with SUN-DES-l, with the syntax: xauth add SUN-DES-I unix.@ Give yourself permission to the machine using both its TCP/IP address and its IPC address: nugget% xauth add nugget : 0 SUN-DES-I unix. 243@west xauth: creating new authority file /home/eap/.Xauthority nugget% xauth add nugget/unix: 0 SUN-DES-I unix. 243@west nugget% xauth list nugget.west, ora. com: 0 SUN-DES-I unix. 243@west nugget/unix:0 SUN-DES-I unix.243@west 3. Start the server with the .Xauthoritv file just created: nugget% xinit -- -auth ~/.Xauthority When the server is up and running, check who has access by using the xhost command: nugget % xhost access control enabled, only authorized clients can connect nugget, west. ora. com localhost The hosts list has the local machine listed by default, both by its hostname and by localhost. Using the xhost command, you need to give yourself permission to your server. If you want to be able to run xterm clients (or any other setuid clients) from the local host, you also have to give permission to root (see Section 4.4.6 for an explanation of why root needs to be on your access control list). You then need to remove the other entries. The syntax for giving a user permission is: xhost + username@domain The domain field can be left empty if it is the current NIS domain. Give both yourself and root permission to access the server. Note that when giving permission to root, you have to use the root principal for that machine (unix. hostname@domain), not root@. nugget% x_host +eap@ +unix.nugget@west eap@ (unix.243@west) being added to access control list unix.nugget@west being added to access control list Security 89 Then remove permission from the entire host: nugget% xhost -nugget .west. ora. com -localhost nugget.west.ora.ccm being removed frcm access control list localhost being removed frcm access control list This ensures that only user eap in the current NIS domain and root on the host named nugget can connect to your server. Note that since the .Xauthority file only contains information about the principal that started the server, the SUN-DES-1 security method does not depend on the security of the .Xauthority file. Unlike the MIT-MAGIC-COOKIE- 1 and XDM-AUTHORIZATION- 1 methods, if other users gain read access to your .Xauthority file, they still can't access your server unless you expli- citly grant them access with xhost. To automate this process, you need to edit your .xinitrc script. # !/bin/sh # Get user ID: uid='ypmatch ${USER} passwd.byname I awk -F: '{print $3}" # Get hostname: host=" hostname" domain=" dcmainname" # Get principal: principal=unix. $ {uid} @$ {domain} # Add entries to .Xauthority file: xauth add ${host} :0 SUN-DES-I ${principal} xauth add $ {host }/unix: 0 SUN-DES-I $ {principal } # Add permission to self, remove permission frcm entire host: xhost +$ {USER} @ +unix. $ {host } 05 { domain} - $ {host } -localhost # Start some clients: twm& xterm & When you start the server with xinit, this will set up your workstation display and prepare it for SUN-DES-1 use. Note that a private key is automatically generated only when you log in with your password. If you log in without typing your password, you need to run the keylogin command to gener- ate a new private key: % keylogin Password: You might need to do this if you can remotely log into a machine because of entries in $HOME/.rhosts or/etc/hosts.equiv. 90 X Window System Administrator's Guide 4.4.5 Adding Another User with SUN-DES-1 To allow another user to connect to your host using SUN-DES-1 security, you have to run xhost to give the remote user access, and the remote user also has to run xauth to place an entry for that server in their .Xauthorit3' file. For this example, user cathyr on the host rock in the NIS domain west wants to connect to the host nugget in the same NIS domain, where user eap is currently running a server. I. User eap has to give cathyr permission to access the server using xhost: nugget% xhost +cathyr@ cathyr@ (unix.206@west) being added to access control list nugget% xhost cathyr@ (unix.206@west) eap@ (unix.243@west) unix.nugget@west 2. User cathyr has to create an .Xauthority file entry with the server she wants to connect to (nugget) and the principal of the user running the server: rock% xauth add nugget : 0 SUN-DES-I unix. nugget@west Note that this means that cathyr needs to know which user is running the server, and she needs to know that user's principal. In this case, the server was started using xdm, so it belongs to root. cathyr therefore needs to add root's principal, not eap's. 3. cathyr should now be able to connect to nugget's X server: ruby% xroach -display nugget .west. ora. cm: 0 & Something went wrong ff cathyr getsthefollowing error: Xlib: connection to "nugget:0.0" refused by server Xlib: Client is not authorized to connect to Server Error: Can't open display: nugget:0 You might want to run X clients from a host in another NIS domain. The first complication is that if you're in another NIS domain, it's harder to find out what principal to use in the xauth command line. If the server was started with xdm, then you can use root's principal; but if the server was started with xinit then you have to do some research. If cathyr is in the same NIS domain (as in the example above), she can figure out what prin- cipal to use with only a little bit of detective work. She can just see who owns/dev/console, and use ypmatch and domainname to figure out that user's principal. If cathyr were in a remote domain, however, she would have to be able to run a remote shell to the local host to get that information: ruby% rsh nugget is -i /dev/console crw--w--w- 1 eap 0, 0 Sep 3 15:56 /dev/console ruby% rsh nugget ypmatch eap passwd eap:XZTOEUdSwjYgo:243 : 100 :Eric Pearce:/hcme/eap:/bin/tcsh ruby% rsh nugget domainname west or 3he would be dependent on eap to tell her that information. Security 91 If NIS is not running on the host (in this case, the host is rock): Sending key change request to rock... chkey: unable to update NIS database (ii) : can't ccmnicate with ypserv rock is down or not running rpc.ypupdated If/usr/etc/keyserv is not running, you might get any of the following errors: Sending key change request to rock... chkey: unable to update NIS database(7) : local resource allocation failure I couldn't generate a secure RPC authenticator to rock The keyserver /usr/etc/keyserv must be running. You may have to keylogin before doing a before doing a chkey. If you do not have a key, you may need to get a system administrator to create an initial key for you with newkey. The system could be loaded, so you might try this again. or" auth_create: Bad file number Error: Can't open display: nugget:0.0 Or: Could not set unix.243@west's secret key Maybe the keyserver is down? If you are running a (pre-R5) version ofxauth that does not know about SUN-DES-l: xauth: (argv) :i: key contains odd number of or non-hex characters Ifyou are running a(pre-R5)version ofxhostthatdoes notknow aboutSUN-DES-I: access control enabled (only the following hosts are alled) If you run a mixed environment with R4 programs as well as R5 programs, make sure you have the R5 versions of xauth and xhost in your path before the R4 versions. This applies not only to MIT X11R4 but also any commercial X distributions that are not yet updated to R5. 4.5 xterm and Secure Keyboard The xterm client has a Secure Keyboard option that you can enable on the xterm Main Menu. (You can access the Main Menu by holding down the CTRL key while pressing the second mouse button.) This feature can be used to prevent others from reading what you type in that window. By enabling Secure Keyboard, xterm performs a GrabKeyboardO protocol request. Only one client can grab the keyboard at a time, so the Secure Keyboard feature can be enabled only temporarily; however, if you are typing a sensitive document or entering a password in that xterm window, enabling Secure Keyboard ensures that only xterm is receiving input directly from the keyboard. By using Secure Keyboard, you can be sure that no other client can be snooping on what you type. Securi 93 When you enable Secure Keyboard, the xterm window should reverse its colors. If the colors do not reverse, then xterm was unable to grab the keyboard, and it is very possible that your display is being snooped. The Secure Keyboard feature provides some protection against a particular kind of snoop- ing, but it has many drawbacks. One drawback, of course, is that it is available only using xterm. Another is that it's a security feature that requires the user's intervention to be enabled--like a seatbelt, it's only as effective as its users make it. Since it grabs the key- board, it's annoying to use--you have to disable it every time you want to type in another client window. And it doesn't protect against taking screendumps of a display, just against people snooping on keyboard input itself. The big thing it buys you is protection on pass- words, since passwords are not copied on the display. But the rest of your display is still up for grabs. 4.6 Other Security Issues Thus far we've only discussed security issues as far as server access control is concerned. X has many more security issues, which we discuss briefly here. 4.6.1 The Console xterm (R4 and Earlier) The -C option to xterm gives the user a console window for the host running the xterm client. Prior to X 11R5, any user can run an xterm -C regardless of whether they are logged on to the console.* Furthermore, multiple users can each run xterm -C, and the console messages will simply display on whichever console window was opened last. This means that the person on the console display won't receive console messages, and will have no indication that mes- sages are not being shown. On some systems, a console window which has been diverted to a foreign server may also prevent new login sessions on the console display. When an X server started with xinit shuts down on the console, the login prompt may be diverted to the console xterm window instead of to the console itself. There is also a possibility that if root is logged in on the console, users running xterm -C can get root permission. For all these reasons, many systems do not support the -C option to xterm. As an alternative, some systems (such as SCO Open Desktop) have each error message appear in a separate pop-up window on the console. For getting a diverted console window back, the following C program may be of use: /* This will redirect console input and output back to /dev/console. */ #include *For SunOS, you may wish to look at patch 100188-01 that addresses this issue. 94 X Window System Administrator's Guide #include main() { int fd; if ((fd = open("/dev/console", O_RDWR, 0)) >= 0) ioctl (fd, TIOCCONS, 0); close(fd); If you suspect that the console has been redirected, try compiling this program and running it as root. % cc -o console console.c % su # ./console 4.6.2 The Console and xdm (R5) With Release 5 of X11, many of the concerns about console ownership have been solved. In R5, xterm has been adjusted to allow only the owner of/dev/console to start up a console window. Other users are able to run the -C option without receiving an error message, but no console messages will appear in their window. The R5 solution, however, requires a bit of fiddling for workstations configured to use xdm on the console display. When you start X using xinit, you have to first log into the console using get.' and Iogin, so you necessarily own /dev/console. When you log in using xdm, however, you bypass the get.'/login mechanisms, so you have to be given ownership of/dev/console explicitly. For that purpose, the default xdm configuration is altered in R5 to define scripts that are run when a user logs in on the console and when the user logs out again. The xdm-config file specifies: Di splayManager. _0. s tartup: /us r / i ib/Xl i/xdm/GiveConsol e DisplayManager ._0. reset: /usr/lib/Xll/xdm/TakeConsole (The _0 means that this resource is used only for xdm sessions on the display named : 0, i.e., the console display. See Chapter 3 for more information on configuring xdm.) Both the GiveConsole and TakeConsole scripts are specified as display-specific resources for the local console display. The GiveConsole script is specified with the Display- Manager._O. startup resource, which defines a program that is run when the user has first logged in, but before any other clients are executed. The TakeConsole script is specified with the DisplayManager._O. reset resource, defining a program run after the user logs out but before a new connection is established. Both scripts are executed as root. Although all three files are currently shell scripts, they can be any executable file. (Note that since these scripts are run as root, you should be extremely careful should you choose to edit them.) The GiveConsole script in the R5 distribution does a simple chown to give the user owner- ship of/dev/console so that the user might get console messages: # .'/bin/sh # Assign ownership of the console to the invoking user # # By convention, both xconsole and xterm -C check that the Security 95 # console is owned by the invoking user and is readable before attaching # the console output. This way a randcm user can invoke xterm -C without # causing serious grief. # chown $USER /dev/console Similarly, the TakeConsole script returns ownership of/dev/console to root: # !/bin/sh # Reassign ownership of the console to root, this should disallow # assist of console output to any randcm users's xterm # chmd 622 /dev/console chown root /dev/console Together, GiveConsole and TakeConsole ensure that the user running xdm on the local display server can receive console messages. 4.6.3 Hanging the Server Remotely (R3) In X11 Release 3, there's a bug where the server looks for a small packet from the client before it determines whether or not the client is in the xhost list. The server halts operation until this packet is sent. You can find out if your X server has this problem by running: % telnet localhost 6000 (6000 is the TCP/IP port used by server 0 on the local host.) If your X server freezes, then your workstation has this problem. Some servers will time out after 30 seconds, but others will remain blocked until the telnet connection is closed. Note that since this freezes your server, it's better not to try this from a window on your local display! 4.6.4 Reading the Framebuffer (Sun Workstations) Sun workstations have a special device called a frarnebuffer, represented by the file/dev/fb. The framebuffer contains the current image on the console. Sun workstations supply com- mands, called screendurnp and screenload, for copying the framebuffer to a file and display- ing that file, respectively. If someone can log onto your Sun workstation, they can usually read your framebuffer regardless of any X security you have in place. To view the screen on one Sun workstation from another, try: % rsh host screendump I screenload From any X server, you can use the public domain xloadimage client: % rsh host screendump I xloadimage To prevent this, you could try changing the permissions on the framebuffer (i.e., chmod 6 O0 /dev/fb), but this might break other programs and interfere with the functionality of your workstation. Another possibility might be to make the framebuffer readable by only a special group and have all commands that access it setgid to that group, similar to how per- mission to/dev/kmem is restricted to the kmem group. 96 X Window System Administrator's Guide The best solution is to use the file/etc/fbtab to control access to the frame buffer. Uncom- ment the line that lists the frame buffer: /dev/console 0600 /dev/fb:/dev/bwoneO:/dev/b,;twoO and log out completely from the system and then log back in. The flame buffer device will now be owned and only readable by you, preventing another user from reading it. As long your account remains secure, your flame buffer should also. See the manual page forfbtab for more information. 4.6.5 Removing Files in/tmp Another trick for disrupting the server on a workstation is to remove the files in /tmp/.Xl l-unix. This directory contains a UNIX socket file for each X server running on that workstation. % is -i /tmp/.Xll-unix srwxrwxrwx 1 imui 0 Apr 27 09:46 X0 This file is the socket descriptor used by X to connect to local server : 0 via IPC. And by default, everyone has write permission (and thus delete permission) to/tmp/.Xll-unix. So another trick for perverse users is to delete the XO file on someone else's workstation % rsh harry rm /tmp/.Xll-unix/XO The workstation will subsequently be unable to use IPC to start local X clients anymore. That is, clients will not be able to connect using the display name unix : 0.0 or : 0.0, but only via TCP/IP or DECnet. To protect against the XO file being deleted, turn on the sticky bit for the /tmp/,Xll-unix directory on systems that support that functionality: root# chmod 1777 /tmp/.Xll-unix This will prevent users from deleting files that belong to other users in that directory. While you're there, you might want to make sure the sticky bit is set for/tmp itself. But note that setting the sticky bit for/tmp does not set it recursively--you need to explicitly set it for /tmp/.Xl 1-unix as well. On some versions of SunOS, cron automatically removes files in /tmp, including the .XI 1-unixWsubdirectory. On those systems, change the cron job to exclude sockets by adding ": -type s" to the.find command line. 4.6.6 The Network Design Despite all the work in keeping others from interfering with your server or snooping on your work, the basic security problem is in the very design of X 11: if the client and server are run- ning on different machines, then they necessarily communicate over the network. This means that anyone who knows the X protocol and who knows how to snoop over TCP/IP can follow everything you do over the network, and none of the security mechanisms described Security 97 in this chapter can prevent them from doing that. The X protocol itself can be encrypted, but not without a substantial loss in efficiency. Since new clients are started all the time, the magic cookie code itself is being sent over the network repeatedly--so even that can be captured, and the snoop will then have direct access to your display. X11R5 makes DES (Data Encryption Standard) available with both XDM-AUTHORITY-1 and SUN-DES-l, so that the magic cookie is encrypted across the net- work; but commercial servers are slow to incorporate DES code, and there are export restric- tions on DES that make it unavailable outside of the United States. Several X vendors have implemented the U.S. Government specification on Compartmented Mode Workstations (CMW), which allows the X workstation to run as a standalone trusted system. On a CMW, for example, each window has its own security label. (See the Nutshell Handbook Computer Security Basics by Deborah Russell (O'Reilly & Associates, 1991) for more information on security labels and trusted systems.) As you would imagine, however, all bets are off on a networked environment. There are trusted networking specifications being worked on (such as MaxSix), but X still has a long way to go before it can be consid- ered secure. 4.7 Related Documentation "Issues in Building Trusted X Window Systems," by Jeremy Epstein and Jeffrey Picciotto, published in The X Resource, Issue 0, O'Reilly & Associates, Inc., Fall 1991. The Xsecurity, xauth, xhost, xterm,fbtab, and xdm manual pages. "Framework Generic Requirements for X Window System Security, Issue 1," by Maria Cangelosi and Charles Blauner, published by Bell Communications Research, Inc. (Bellcore), document number FA-STS-001324, July 1992. For more information on Secure RPC, see Managing NFS and NIS by Hal Stern (O'Reilly & Associates, 1991). 98 X Window System Administrator's Guide 5 Font Management The fonts used by an application need to be available to every server that might display it. This chapter discusses the issues with using fonts, installing new fonts, and converting fonts from other formats. It also discusses the X l 1R5 font server. In This Chapter: Fonts on the X Window System ......................................................... 101 xlsfonts .......................................................................................... 103 xfd ................................................................................................. 103 xfontsel .......................................................................................... 104 The Font Path ................................................................................ 105 The Font Directoi File .................................................................. 106 The fonts.scale File (R5 only) ......................................................... 107 Wildcards ....................................................................................... 108 Aliases ........................................................................................... 108 The FILE_NAMES_ALIAS Alias ...................................................... 109 All About Fonts .................................................................................. 110 Bitmap Versus Outline Fonts .......................................................... 110 Font Formats ................................................................................. 111 Format Conversion Tools ............................................................... 112 Adding New Fonts ............................................................................. 114 Adding a Single Font ...................................................................... 114 Adding Multiple Fonts .................................................................... 115 Multiple Font Example ................................................................. 116 Problems with Running Vendor-specific Clients .............................. 117 DECWindows Examples ................................................................ 118 Aliasing ........................................................................................ 119 DECWindows Conversion ............................................................ 120 AIXWindows Example .................................................................... 121 OpenWindows Example ................................................................. 123 Aliasing ........................................................................................ 124 OpenWindows Conversion ........................................................... 125 Converting from Xl 1/NEWS to PCF or SNF ................................. 125 More Conversions ........................................................................ 126 Providing Fonts Over the Network ...................................................... 127 The R5 Font Server ........................................................................... 127 The Configuration File .................................................................... 128 Installing the Font Server ............................................................... 130 Testing By Hand .......................................................................... 131 Changing BSD Boot Files ............................................................ 131 Changing System V Boot Files ..................................................... 132 Changing AIX Boot Files .............................................................. 133 Font Server Name Syntax .............................................................. 133 Debugging the Font Server ............................................................ 134 Font Server Clients ........................................................................ 135 The Font Path and the Font Server ................................................ 136 Hostname Aliases .......................................................................... 138 A Font Server Example .................................................................. 138 Related Documentation ..................................................................... 140 5 Font Management The number of fonts available under X11 is enormous, and there's no limit to adding more. Each size and orientation is treated as a different font. Furthermore, fonts are stored in sev- eral different formats, so the same font might be stored five different ways. The administrator's role is to ensure that each server can access the fonts it needs for a given application. In Release 3 and Release 4, fonts for servers needed to be available locally--usually stored on a local disk drive or made to appear local via a NFS or AFS filesystem. In Release 5, fonts can be obtained either locally or through a font server, which allows access to fonts on more than one host on the network. 5.1 Fonts on the X Window System In general, a client has default fonts chosen by the programmer, but administrators or users may want to change them tO their own preference. The default fonts may be too small to read, unavailable for a given server, or just plain ugly. For example, the default font for xterm is usually the font fixed, a 13-pixel semi-condensed font that tends to be quite small on high- resolution monitors. Before we discuss the administrative issues of fonts, let's talk about how fonts are designated on the X Window System. An example of a font name and its components is shown in Figure 5-1. The field names have the following meanings: Foundry Family Weight Slant This is a registered name for the font "foundry" (usually a company name) that supplied the font to the X Consortium ("Adobe," "Bitstream," etc). The "family" or typographic style of the font ("Courier," "Lucida," etc). The typographic weight or "blackness" of the font ("medium," "bold," etc). The "posture" of the typeface ("Roman" is upright, "Italic" is slanted, etc). Font Management 101 -Adobe-Couri er-Bol d-R-Normal--i 4-140-75-75-H-90-I S08859-I F6E ii.-7;;;.7i..;;;G,;i iii;;;)iTi;; Select a character range: OxO020 (0.32) thru OxOOFF (0.255) upper left: OxO000 (0.0) Figure 5-2. xfd 5.1.3 xfontsel The xfontsel client (which was new in R4) allows browsing through all the available fonts and seeing each one in tum. When you find a font that you are happy with, click on the "select" button and the selection can be pasted into a file or command line without having to type it by hand. 104 The X Window System Administrator's Guide % xset -q Font Path: /usr/lib/Xll/fonts/local,/usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/75dpi/, /usr/lib/Xll/fonts/lOOdpi/ The local directory is now searched before the regular directories. If you want to redefine one of the default fonts, you can install a new one in the local directory and the server will access the new one instead. Rehashing the Font Path Each time the font path is changed, the server reads the fonts.dir and fonts.alias files in each directory listed in the new font path. The server then maintains a list of valid font names in memory instead of searching for a font in the filesystem every time it is requested. If a new font is added to one of the font directories and the fonts.dir or fonts.alias files are changed, you need to update the list of fonts known to your server with the command: % xset fp rehash The rehash command tells the server that something has changed and it should rebuild this internal list. The xset client controls many server features. See the manual page for xset for more infor- mation. The font path can also be specified when the server is first started. For example, on the com- mand line: % xinit -- -fp /usr/lib/Xll/fonts/local,/usr/lib/Xll/fonts/misc/,\ /usr/lib/Xll/fonts/75dpi/,/usr/lib/Xll/fonts/lOOdpi/ or in the Xservers file: :0 local /usr/bin/Xll/X -fp /usr/lib/Xll/fonts/iocal,/usr/lib/Xll/fonts/misc/,\ /usr/lib/Xll/fonts/75dpi/,/usr/lib/Xll/fonts/lOOdpi/ 5.1.5 The Font Directory File When a client requests a specified font, the server searches in each of the directories in its font path for a file called fonts.dir, as in/usr/lib/Xll/fonts/75dpi/fonts.dir. The fonts.dir file maps the name of the requested font to the filename of the font as it is stored in the filesys- tem. If there is no match, the client reverts to its own defaults (e.g., xterm reverts to "fixed"). The fonts.dir file is needed because some operating systems have restrictions on filenames. For example, MS-DOS, VMS, and UNIX all have restrictions on filename length or on the char- acters used within filenames. When installing a new font, you should choose a filename for the new font that conforms to the semantics of your operating system. The fonts.dir file con- tains the mapping of the font filename to the name of the font itself. 106 The X Window System Administrator's Guide The fonts.dir file's presence is required for the server to access any fonts within a directory. It is created by the mkfontdir command. You have to run mkfontdir every time you add or delete a font from a directory to keep the fonts.dir file in sync with the actual contents of the font area. (See Section 5.3.1 for an example of how to use mkfontdir.) Thefonts.dir file has a simple format--the first several lines of a sample R4 file resemble the following: 200 courBOl 0. snf - adobe- couri er-bol d-o -norma i-- 10-100 - 75 - 75-m- 60- i so8859 - 1 courBOl2, snf -adobe-courier-bold-o-normal- - 12 - 120 -75-75-m-70- i so8859 - 1 courBOl4, snf -adobe- courier-bol d-o-norma i- - 14 - 140- 75 - 75 -m- 90- i so8859 - 1 courBOl8, snf -adobe-courier-bold-o-normal--18-180-75-75-m-l10-iso8859-1 courBO24, snf -adobe-courier-bold-o-normal--24-240-75-75-m-150-iso8859-1 The number at the top is the number of fonts in the directory. The remaining lines are pairs of filenames and font names. The .snfextension to filenames in this example indicates the for- mat that the font is stored in--in this case, the Server Natural Format. (See Section 5.2.2 for more information on font formats.) The files may also have a .Z extension, if the server sup- ports compressed fonts. OpenWindows-specific Features Sun's OpenWindows has a different system for fonts (scalable F3 format), but most of the font administration utilities parallel the MIT ones in function. The OpenWindows file Families.list is similar in function to the fonts.dir file. It is created by the bldfamily command, which should be run any time the contents of the font directory are changed. in the same manner as montdir. 5.1.6 The fonts.scale File (R5 only) In R5, the outline or scalable fonts (as described in Section 5.2.1) introduce a problem with creating thefonts.dir file. It is difficult for mkfontdir to determine the values in the font name fields for a scalable font. If there are scalable fonts within a font directory, a fonts.scale file should be created by hand. When mkfontdir is run, it will create entries in fonts.dir for each bitmap font it finds and will then append the contents of the fonts.scale file. The Speedo fonts distributed with R5 come with a fonts.scale file that is installed along with the fonts in/usr/lib/X11/fonts/Speedo. It contains an entry for each scalable font: 8 font0648.spd -bitstream-charter-medium-r-normal--0-0-0-0-p-0-iso8859-1 font0649.spd -bitstream-charter-medium-i-normal--0-0-0-0-p-0-iso8859-1 font0709.spd -bitstream-charter-bold-r-normal--0-0-0-0-p-0-iso8859-1 font0710.spd -bitstream-charter-bold-i-normal--0-0-0-0-p-0-iso8859-1 font0419.spd -bitstream-courier-medium-r-normal--0-0-0-0-m-0-iso8859-1 Font Management 10 7 fontO582.spd -bitstream-courier-medium-i-normal--O-O-O-O-m-O-iso8859-1 fontO583.spd -bitstream-courier-bold-r-normal--O-O-O-O-m-O-iso8859-1 fontO611.spd -bitstream-courier-bold-i-normal--O-O-O-O-m-O-iso8859-1 Asthere are no other fontsinthe Speedo directory, the connts ofthefon.scale file and the resultingfon.dir file are identical. 5.1.7 Wildcards As shown in our xlsfonts example earlier, users don't have to use the full names of a font when specifying them. Wildcards can be used to limit the amount of typing required and pro- vide flexibility. Users can use asterisks ("*") in the font specification, such as: % xterm -fn '-fixed-*-*-*-*--15-1O-*-*-*-*-*-*' The asterisks will match any of the possible values for a given field in the font specification. Notice that a font name using an asterisk as a wildcard needs to be single-quoted on the com- mand line. This is to protect the asterisks from being interpreted by the shell. The first font found in the font path that matches the pattern is the one that is used. If you supply the pattern to xlsfonts, you can see which fonts in your font path match the pattern: % xlsfonts -fn '-fixed-*-*-*-*--15-1O-*-*-*-*-*-*' -misc- fixed-bold-r-normal--15-140-75-75-c- 90-iso8859-i -misc- fixed-medium-r-normal-- 15-140-75-75-c-90-iso8859- i Although xlsfonts may report more than one font name, only the first font listed will be used by a client when supplied a font name using the same wildcards. If you run xfd with the same font pattern, the name of the first matching font is displayed at the top of the window: -misc- fixed-bold-r-normal-- 15-140-75-75-c-90-iso8859-i Using wildcards could have a surprising effect, especially when a new font is installed: if an administrator adds a new font that is similar in name to an already existing font, users may end up matching the new one instead of the one they thought they were requesting. Other surprises could occur when a new version of X11 is installed, as each release has had more fonts than the previous release, leading to new matches to a wildcard. Using wildcards can make an application more flexible, as it may still find a usable font if the intended one is missing, whereas a complete font specification may cause a failure if not matched exactly. 5.1.8 Aliases A font subdirectory can contain a file called fonts.alias, which contains aliases for font names. An example of an alias is the default fixed font, which is defined in fonts.alias in the MIT distribution of X as: fixed -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-1 108 The X Window System Administrator's Guide .Z Compressed file. This extension indicates that the compress program has been run on the font file. This should reduce the size of the file on disk. Some servers (such as those from MIT) can read compressed fonts directly, but this is not true for all implementations. 5.2.3 Format Conversion Tools There are several commands for converting from one format to another, as illustrated in Fig- ure 5-4. The following are some common examples. See the manual pages for these com- mands for more information. bdftosnf Converts BDF to SNF. This command should come with any server that uses SNF, such as the stock MIT server Releases 2 through 4. Example usage: # bdftosnf myfont.bdf > myfont, snf bdftopcf Converts BDF to PCF. This command should come with any server that uses PCF, such as DECWindows and MIT Release 5. Example usage: # bdftopcf -o myfont.pcf myfont.bdf c Converts BDF to PCF. This command is distributed with DECWindows. Example usage: # dxfc myfont.bdf > myfont.pcf snftobdf Converts SNF back to BDF. This program can be found on various anony- mousftp sites and X source archives.* Example usage: # snftobdf myfont, snf > myfont.bdf conve.rtfont fstobdf Converts BDF to several Xll/NeWS formats and back. This command comes with Sun OpenWindows. Example usage: # convertfont -f 32 myfont.bdf See Section 5.3.6.3 for an example using convertfont. Dumps the BDF version of any font available to the font server. See Sec- tion 5.5 for more information on the font server. # fstobdf -s tcp/harry.ora.com:7000 -fn fixed > fixed.bdf getbdf Dumps the BDF version of any font available to the X server. See Section 5.3.4.2 and 5.3.5 for examples of using getbdf. # getbdf -font 9x15 > 9xl5.bdf * One ftp site is export.lcs.mit.edu in contrib/snftobdftar.Z. 112 The X Window System Administrator's Guide 5.3 Adding New Fonts There are lots of reasons to expand the numbers of fonts available. Some applications, espe- cially desktop publishing packages, provide new fonts as part of their installation. Clients that support languages other than English are becoming commonplace and are widely avail- able on the Internet--these clients require large numbers of new fonts to be added. It is possible to access fonts in your home directory by adding paths to existing font paths with the fp option to the xset command. This is useful for testing. It also means that you can have users install the fonts they want in their own home directories if you don't think every- one will want to use them. 5.3.1 Adding a Single Font Let's step through the procedure for adding a new font in a stock MIT R3 or R4 environment. (For an R5 environment running a font server, the font may already exist on another system and you can just tell the font server where it is. See Section 5.5 for more information.) You may come across an application that requires some non-standard fonts, say a Kanji. font for the OSF/Motif demo program hellomotif.* This font is distributed in BDF format. 1. Convert it to SNF (or whatever is appropriate for your server) with the bdftosnf com- mand: # bdftosnf -t kl-l.bdf > kl-l.snf # bdftosnf -t rkanal4.bdf > rkanal4.snf The -t flag indicates that these fonts are going to be displayed on a "terminal" (such as xterm) and each character should be same size. 2. Copy the SNF files into one of the font directories. For this example, the misc directory is a good candidate: # cp kl-l.snf /usr/lib/X11/fonts/misc # cp rkanal4.snf /usr/lib/Xll/fonts/misc 3. Rebuild thefonts.dir file with the mkfontdir command: # mkfontdir /usr/lib/X11/fonts/misc This command will increment by 2 the number of fonts listed on the first line of the fonts.dir file, and add two pairs of entries: the filename and the font name. k14-1, snf -k14-screen-medium-r-normal--14-140-75-75-m-140-j isx0208.1983-1 rkanal4, snf -romankana14-screen-medium-r-normal--14-140-75-75-m-70-j isx0201 1976-0 The next step would be to add aliases to fonts.alias for convenience. In the hellomotif case, the application requests the font by its full name, not by an alias--so unless you intend to access the font from other applications, it probably isn't worth aliasing. * OSF/Motif source can be purchased from the Open Software Foundation. 114 The X Window System Administrator's Guide 3. Verify yourcuentfont path using the xsetcommand: % xset -q Font Path: /usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/75dpi/, /usr/lib/Xll/fonts/lOOdpi/,/usr/lib/Xll/fonts/tex Note that, in order to access the new fonts, users have to run the xsetfp+ command specified above every time they start their server. Their .xsession or .xinitrc files would be an appropri- ate place for the command. For sites that start their X sessions from xdm, you can add local changes like this one to the xdm startup files. This will add the font path for all users who start their X sessions using xdm. Rather than creating multiple font directories to be added to the font path of each server, you could just put all non-standard fonts into one directory, for example,/usr/lib/Xll/fonts/local. Some vendor implementations (such as DECWindows) provide a "local" directory structure just for this purpose. The path is already known to the server, so you can add fonts and they will be available without further changes. You could also define this path within the default search path when you build the X11 distri- bution from source (using the DefaultFontPath build flag) or supply a font path when starting the X server. See Section 8.5 for information on how to change your build flags when building X11 from source. To supply a new font path when starting the X server, most servers accept a -fp option on the command line. 5.3.3 Problems with Running Vendor-specific Clients The fonts available to a server vary from one vendor to another. If a client requests a font from the server and it is not recognized, this may render an application unusable or just make it look strange. Let's say you are on a Sun running an MIT Release 4 server and wish to run the DECWin- dows desk calendar dacalendar off a remote Ultrix host. dacalendar looks for specific fonts that are not available on the Sun, and the program will complain about the missing fonts: scud% dxcalendar X Toolkit Warning: Cannot convert string "-*-MIqU-MEDIUM-R-Normal -*-120-*-*-P-*-IS08859-I" to type FontList, using fixed font X Toolkit Warning: Cannot convert string "-*-Menu-Medium-R-Normal -*-I00-*-*-P-*-ISO8859-I" to type FontList, using fixed font X Toolkit Warning: Cannot convert string "-*-Menu-Medium-R-Normal -*-120-*-*-P-*-IS08859-I" to type FontList, using fixed font The application in this example will still run, but it doesn't look as good as it should. The InfoExplorer utility in AIXWindows also has its own set of fonts. While InfoExplorer will run without its fonts, you can improve its appearance on a non-AIXWindows server by making these fonts available to it. Font Management 117 The OpenWindows cm (calendar manager) is a highly desirable program, but it, like most OpenWindows applications, will look terrible running under the MIT R4 server if you don't make its special fonts available. It will also complain about missing fonts: h-street% cm XView warning: Cannot load font '-b&h-lucida-medium-r-normal-sans-* -90-*-*-*-*-*-*' (Font package) XView warning: Cannot load font '-b&h-lucida-bold-r-normal-sans*-9 0-*-*-*-*-*-*' (Font package) For all these examples, the solution is to make the font available to the local server. (This may cause some confusion for people new to X, as the fonts might appear to be available along with the clients on a remote host.) Sometimes the solution to supplying a missing font may be as simple as creating an alias to it from an existing font. It is also possible to convert fonts required by a special client into a format that is recognized by your server, but this may involve some work. The getbdf pro- gram is one such font converter that may work.* getbdf can query the server for a font and dump it out in the bdfform, which can then be converted into the local font format. In most cases, you should do the conversion from bdf to your local format on the machine where the fonts are going to reside. This should avoid any problems with byte order when the conversion takes place. The font server introduced in MIT R5 will probably eliminate these problems, but it will take some time before the font server is available for all X servers. In the meantime, the tech- niques introduced here should suffice. These examples may not match the exact problem you are having. Think of them as "case studies" that show problem solving techniques. The purpose of this section is to demonstrate that it is possible for the administrator to compensate for differences between vendor imple- mentations. 5.3.4 DECWindows Examples The DECWindows software contains fonts in the directory/usr/lib/X11/fonts/decwin that do not exist in the MIT X 11 R4 release. There are two ways to get around this problem: alias the DECWindows fonts to existing MIT fonts, or you can convert the DECWindows PCF fonts into SNF fonts that can be used by the MIT R4 server. For an example problem, the dxcalendar program does not look quite right without the DECWindows fonts. * getbdfis available via anonymous lip to larry.mcrcim.mcgill.edu as X/getbdf.c. 118 The X Window System Administrator's Guide File Edit. ew Customize Help Figure 5-6. dxcalendar with aliases 5.3.4.2 DECWindows Conversion Another option is to use a program that extracts fonts from the server and outputs them in BDF format. You can then convert them into SNF or whatever your local server requires. Once they are in your local format, you can add them to your font directory. 1. Compile the getbdfprogram on the Ultrix host: % cc -o getbdf getbdf.c -IXll 2. On the Ultrix host, run the getbdf program to dump out the fonts into BDF format. Since fonts.alias contains the keyword FILE_NAME_ALIASES, you know that the filename of the font is also a valid name for the font. You can use this fact to automate the conversion process. If you are using csh, the following commands will convert each font in the direc- tory: # # ? ? ? The # # cd lusrlliblX11Ifontsldecwin/75dpi foreach goo (*.pcf) set foo='basename $goo .pcf" getbdf $foo > $foo.bdf end shequivalent would be: cd lusrlliblX1ilfontsldecwin/75dpi for goo in *.pcf do foo='basename $goo .pcf" getbdf $foo > $foo.bdf done 120 The X Window System Administrator's Guide 3. Make a directory on the target machine for the new fonts: # mkdir /usr/lib/Xll/fonts/decwin 4. Copy all the BDF files to the new directory on the target machine or access them via NFS. On the target machine, convert the BDF fonts to local format (SNF in this example) for your server. This example also uses csh: # foreach goo (*.bdf) ? bdftosnf $goo > "basename $goo .bdf" .snf ? end The sh equivalent would be: # for goo in *.bdf > do > bdftosnf $goo > "basename $goo .bdf" .snf > done 5. Create the fonts.alias file: # echo FILE_NAMES_ALIASES > fonts.alias 6. Create thefonts.dir file: # mkfontdir 7. Add the new directory to your font path: % xset fp+ /usr/lib/Xll/fonts/decwin 8. Try out a program that needs DECWindows fonts: % dxcalendar & 5.3.5 AIXWindows Example The InfoExplorer utility on the IBM RS/6000 running AIX also has its own set of fonts. The InfoExplorer fonts are in the directory/usr/lpp/info/Xllfonts. As in the Ultrix example, you need to convert the fonts into BDF format and then into the native format of your server. You can use the same font conversion trick here that we used in the DECWindows conversion. In this example, the target server uses the SNF format. 1. Compile the getbdf program on the AIX host: % cc -o getbdf getbdf.c -iXll 2. Use the getbdfprogram to dump the fonts into BDF format. Since the fonts.alias file con- tains the keyword FILE_NAME_ALIASES, you know that the filename of the font is also a valid name for the font. You can use this fact to automate the conversion process. This example is using csh: Font Management 121 5.3.60penWindows Example The cm desktop calendar program in the Sun OpenWindows 2.0 distribution does not work properly under MIT R4 without the fonts it needs. To demonstrate the problem, try running the crn program without the aliases. '[-] Untitled Man Tue Wed Thu Fri Sat Figure 5-7. cm without aliases The dates on the calendar are missing, because the necessary fonts are missing. Font Management 123 5.3.6.1 Aliasiflg Most of these types of font problems can be handled by a few aliases. Aliases can be added to an existing fonts.alias file, such as the one in/usr/lib/Xll/fonts/75dpi/. This example adds the necessary fonts to the fonts.alias file so you can run cm under an MIT R4 server. Simply append the following lines to the fonts.alias file: -b&_h-lucida-ndium-r-normal-sans- 9-90-75-75-p- 58-iso8859-1 -b&_h-lucida- ndium-r-normal-sans-I O- 100-75-75-p-58-iso8859-1 -b&_h-lucida-bold-r-normal-sans-9-90-75-75-p-58-iso8859-1 -b&_h-lucida- bold-r-normal-sans- 12 -120-75-75-p-79-iso8859-1 Next, tell the server about them: % xset fp rehash Now, run cm again, this time with the aliases (see Figure 5-8.) May 1992 Sun Mon Tue Wed Thu i Sat 1 2 3 4 S 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 Figure 5-8. cm with aliases 124 The X Window System Administrator's Guide 5.4 Providing Fonts Over the Network Diskless workstations and X terminals present a new set of problems for font administration. For an X server to display text on a diskless workstation or X terminal, it has to have access to fonts on a remote host, since X terminals don't have any local permanent storage. X termi- nals will typically come with a small set of fonts (usually fixed, at the minimum) that are stored in ROM, but need to read additional fonts over the network to be useful. TFTP access is often needed for X terminals to boot off the remote host. When an X terminal is initially powered up or rebooted, it broadcasts a request for boot services over the network and a designated host downloads a kernel or server to the X terminal. See Section 7.4 for more information on fonts and X terminals. Fonts can also be downloaded using the same mechanism after the X terminal is up and run- ning, but a more flexible approach is to NFS-mount the fonts from a remote host. The server can then add fonts "on-the-fly" after booting. Unfortunately, this also implies all the normal administration problems associated with NFS, such as access control, network loading, and server failures. When using NFS, X terminals become closer to the diskless workstations that they were designed to replace, as they are subject to the same problems. See Section 7.4.3 for more information. 5.5 The R5 Font Server Previous to Release 5, fonts on the X Window System needed to be available on local disk or provided over the network via TFTP or NFS. Starting with R5, fonts can be requested from a font server. The font server is a program that runs on a host somewhere on the network and provides fonts to your X server. This makes font administration easier, as you can have several sources for a given font, which makes font access more reliable and less dependent on a single host. It also separates font problems from TFTP and NFS problems. The font server can understand several different font formats. This means that all you have to do to make a font available is to run the font server on the host where the font resides. You no longer have to copy over the font and convert it to a format recognized by your local server. This is great for multi-vendor environments where you have many different font for- mats, as clients can run under any server and are still able to access special fonts they may require. There is a host-based security mechanism to limit font access to a group of hosts. This can be used when making licensed fonts available with the font server. The number of simultaneous connections to the font server can be controlled, preventing the font server host from being overloaded. Font requests can also be passed onto other font servers if the current one becomes overloaded. The font server program supplied in MIT R5 is called fs and is usually installed as /usr/bin/Xll/fs. The font server is described in the manual page fores. If you have access to the MIT source code, the file mit/doc/fontserver/FSlib.doc describes the font server library Font Management 127 functions and mit/doc/fontserver/design.ms provides a detailed description of the font server design. 5.5.1 The Configuration File The font server's operation is controlled by a configuration file, usually named /usr/lib/X11/fs/config. If you are building R5 from the MIT source code and want to use the font server, you may want to enable the Tnstal 1FSConfig flag in your config/site.def file. Setting the flag to YES will copy a sample font server configuration file into /usr/lib/Xll/fs/config when the make install is performed. See Section 8.5.1 for more infor- mation on configuring X 11 at build time. The syntax of the configuration file is pretty simple. The following is a sample file that con- tains every option: # font server configuration file (kitchen sink version) # cache-size = 2000000 # alternate-servers = pepper, ora. com: 8000, bigbird, ora. com: 8001 # catalogue = /usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/Speedo/, /usr/lib/Xll/fonts/75dpi/,/usr/lib/Xll/fonts/lOOdpi/ # client-limit = i0 # clone-self = on # default-point-size = 120 # default-resolutions = 75,75,100,100 # error-file = /var/log/fs # port = 7000 # trusted-clients = pepper,bigbird # use-syslog = off # Any line starting with a "#" is treated as a comment and ignored. The following keywords are defined in the configuration file: cache-size This is the number of bytes of memory that the font server will allocate in its font cache. The cache speeds up font access, as any recently requested font should still be in the cache and immediately available (otherwise, it would have to be read from a file on disk or scaled from an outline font). If the font server is running on a host that has lots of memory, make the cache size larger. The cache size is approximately 2 megabytes in this example. 128 The X Window System Administrator's Guide alternate-servers This is a list of alternate font servers for this font server. If the current font server is unable to service the request, it supplies a list of alternate- servers to the X server, permitting the X server to try again at one of the alter- nate font servers. The name of an alternate server is a hostname and port number pair separated by a colon. The alternate servers are referred to as delegates in the MIT documentation. The primary server will supply a client with a list of alternate servers that it knows about. This example has two alternate servers, one on the host pepper and the other on bigbird. catalogue A list of font directories available from this server.* This example lists all the standard MIT R5 font directories. These can be stored in any format recognized by the font server. The font server currently understands the PCF, Speedo, SNF, and BDF formats, described in Section 5.2.2. This keyword should not be con- fused with the catalogue-list component of the font server name (see Section 5.5.6 for an explanation). client-limit The number of clients that the font server will allow before cloning itself or rejecting the connection. If the clone-self flag is set to off and a client attempts a connection, the font server will send back a reply listing other font servers that it knows about. These are specified in the alternate-servers list. clone-self Whether the font server should attempt to clone itself or use delegates when it reaches the client-limit. In this example, it is set to on and the font server would spawn another copy of itself if it received more than l0 (the client-limit) connec- tions. default -point-size The default point size (in tenths of a point) for font requests that don't specify this value. These are called decipoints in the MIT documentation. The example value of 120 indicates a 12 point size. de f aul t - resolut ions Default resolutions supported by the server. The numbers are pairs of horizontal and vertical resolutions per inch. Resolutions of 75x75 and 100xl00 are speci- fied in the example. error-file The filename of the error log file. You can use this if your system does not sup- port the syslogO facility. This file would normally be the first place you would look when debugging the font server configuration file. Leave out this keyword if you have use-syslog enabled. * You may notice that the syntax described here differs from the paper "Font Server Implementation Overview," (rnit/doc/fontserver/design.rns) where a prefix of the font format, such as pcfor Speedo, is used in front of the font di- rectory list. This feature is not used in the MIT R5 font server. Font Management 129 port The TCP port number on which the font server will listen for client connections. Since the font server does not use a privileged port, a user can start up her own font server at any time. As you can choose the port number yourself, you can test the font server without disturbing other servers by selecting a unique port num- ber. The MIT examples all use port 7000. This is a safe distance from port 6000, which is what the X server uses. use-syslog Whether syslogO is to be used for error logging. If set to on, font server errors will be sent to the LOG_LOCALO syslog facility. You will need to add a line to your/etc/syslog.conf file to capture the error messages in a file. If you log other messages to the directory/var/log, the following entry will add logging for the font server: local0, debug /var/log/fs This will log errors to the file/var/log/fs. See the manual page on syslog.conf(5) for more information on setting up syslog. If you want to use the error-file key- word, set use-syslog to off. trusted-clients The names of hosts the font server will supply fonts to. This can be used to restrict fonts to a certain group of hosts for licensing reasons. An empty list indi- cates that any host can make a connection to the font server. You probably won't need to specify most of these options for your site. The MIT-supplied configuration file/usr/lib/Xll/fs/config should be good enough to start with: # font server configuration file # $XConsortium: config.cpp,v 1.7 91/08/22 11:39:59 rws Exp $ clone-self = on use-syslog = off catalogue = /usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/Speedo/,/usr/lib/Xll/fonts/75 dpi/,/usr/lib/Xll/fonts/lOOdpi/ error-file = /usr/lib/Xll/fs/fs-errors # in decipoints default-point-size = 120 default-resolutions = 75,75, i00, i00 5.5.2 Installing the Font Server If you wish to have the font server running all the time (as you probably do), you can add it to a system start-up file, such as/etc/rc.local. However, you probably should not add it to any system files until you are satisfied that it will work correctly. You can test it "by hand" by starting it on the command line. 130 The X Window System Administrator's Guide 5.5.2.1 Testing By Hand The -config flag can be used to test a configuration file that is not yet installed or when you do not have write permission to/usr/lib/Xll/fs: # fs -config ./test-config & If the font server dies with the error: Error: Binding TCP socket: Address already in use Error: Fatal server error.' Error: Cannot establish any listening sockets there is probably another font server (or some other program) running with the same port number. You can specify a number other than 7000 (the default) with the port keyword in the configuration file or on the command line with the -port flag: # fs -config ./test-config -port 7001 & The SIGUSRI signal will cause the server to reread the configuration file. Use this if you have edited the file and wish your changes to take effect without having to kill and restart the font server. The SIGUSR2 signal will cause the server to flush the font cache. This may be desirable if you want the server to get a fresh copy of a font instead of using a cached version that may be out-of-date. The SIGHUP signal is used to reset the server, closing all active client connections and rereading the configuration file. You can kill the font server at any time by sending it the SIGTERM signal. For example, under BSD UNIX: # kill -TERM fs pid Under System V: # killall -TERM fs When you are satisfied with the font server's configuration, it can then be added to the system boot files, which will automatically start it upon the next reboot 5.5.2.2 Changing BSD Boot Files In the BSD world, the/etc/rc.local file is the usual place to add new daemons. You will want to locate the entry for the font server before any other X1 l-related daemons (such as xdm), if they are going to need fonts from the font server. For SunOS 4.x, an example/etc/rc.local entry would look like this: # # start up X font server # if [ -f /usr/bin/Xll/fs ]; then /usr/bin/Xll/fs & echo -n ' fs' fi # Font Management 131 2. Create symbolic links to/etc/init.d/fs from the/etc/rcO.d and/etc/rc2.d directories. The format of the symbolic link name is either a "S" (for start) or a "K" (for kill), followed by a sequence number that determines the order of the file execution, followed by the name of the file in/etc/init.d. To determine the sequence number, you need to see what numbers are already in use. Here is a listing from a sample IRIX 4.0 system: % is /etc/rc2.d S0 LMOUNISYS S30network S50mail S70uucp S88configmsg S20sysetup S40nck S58RMTMPFILES S75cron S95autoconfig S21perf S45netls S601p S78winattr S97cdromd S22acct $48savecore S61bsdlpr S83audio S98xdm The S98xdm entry is for the xdm daemon. Since xdm may require the font server to be running before it starts, you should move it to the next highest number: # mv S98xdm S99xdm And then make a link to the file/etc/init.d/fs file: # in -s /etc/init.d/fs S98fs Repeat the process for the/etc/rcO.d entry: # Kl5cron K2 0mail K251p K30netls K40network K90sysetup Kl8uucp K22acct K26bsdlpr K35nck K78winattr In this case, there isn't a sequence number conflict with an existing script: # in -s /etc/init.d/fs K98fs 3. The final step is to add an entry to the/etc/config directory to enable the script at boot time: # /etc/chkconfig -f fs on 5.5.2.4 Changing AIX Boot Files AIX is a combination of System V and BSD. Starting the fontserverconsists ofadding aline to/etrc.tcpip: # Start font server start /usr/bin/Xll/fs "" # 5.5.3 Font Server Name Syntax Any client wishing to use the font server must be supplied with the name of the host where the font server is running and the port number that the font server is listening on. These two components uniquely identify a particular instance of the font server: transport/hos tname :port Font Management 133 Under System V UNIX: % ps-ef I grep fs I grep-v grep root 169 1 0 Jan 2 ? 0:00 /usr/bin/Xll/fs If the process doesn't show up, there probably is a serious error in the configuration file or something else is wrong with your system. If the font server has reached its client limit, a connection to it may fail with: FSlib: connection to "rock:7000" refused by server FSlib: name of server: rock:7000 fsinfo: unable to open server "rock:7000" Turning on the clone-self keyword or raising the client-limit are possible solu- tions. If you have the error-file flag specified in the configuration file, all font server error messages will appear in the /usr/lib/Xll/fs/fs-errors file (or the file specified with the error-file parameter). If the use-syslog flag is enabled, the errors will be logged in the file specified in/etc/syslog.conf for the LOG_LOCALO facility. Any error message prefixed with CONFTG: has something to do with the configuration file. A typical error might be: Error: CONFIG: can't open configuration file "/usr/lib/Xll/fs/config" /usr/lib/Xll/fs/conjg is the default location of the configuration file. Make sure that the file exists and is readable. You can specify another location for the config file with the -con]ig option tofs. (You might use this option if you are running your own private font server.) If you get the following error: Error: Can't open error file "/usr/lib/Xll/fs/fs-errors" the font server probably does not have write permission to the error file. Any errors will be sent to the controlling terminal or the console. You can specify a different file with the error-file keyword in the font server configuration file. 5.5.5 Font Server Clients Once you have verified the existence of the font server, try requesting a font from it. There are several clients that have names that start with fs, indicating that they are for use with the font server. The fslsfonts client is analogous to xlsfonts in that it lists the names of all available fonts or just those specified on the command line. It understands the same wildcard syntax you use when specifying fonts elsewhere. Try a font that you know should be available from the server: harry% fslsfonts -server tcp/harry:7000 -fn "fixed" fixed Font Management 135 The following example has a font server running on the host harry. First, check the current font path with xset: % xset -q Font Path: /usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/75dpi/,/usr/lib/Xll/fonts/100dpi/ Add the font server entry: % xset fp+ tcp/harry:7000 Check the new path: % xset -q Font Path: /usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/75dpi/,/usr/lib/Xll/fonts/lOOdpi/, tcp/harry: 7000 If you get the following error from xset: X Error of failed request: BadValue (integer parameter out of range for operation) Major opcode of failed request: 51 (X_SetFontPath) Value in failed request: 0x6 Serial number of failed request: 5 Current serial number in output stream: 8 either you made an error in the font server name, or the font server specified in the font path is no longer running. Here are some more examples of valid font path entries: tcp/harry: 7000 tcp/aixfonts : 8000, tcp/decfonts : 7000 DECnet / SRVNOD: : FONT$DEFAULT decnet/44.70: : font$special/symbols Font path additions can specified anywhere you would normally put them. such as in a user's .xsession or .xinitrc file: .oo xset m 2 2 xset b i0 I00 i0 xset fp+ tcp/decfonts.ora.com:7000 xrdb $HOME/.Xdefaults xmodmap $HOME/. xmodmaprc twm& ..o This example assumes the font server will be running before the user's X session is started. If it is not running, the xset command will fail with the BadVal ue error shown previously. Font Management 137 5.6 Related Documentation The font clients are described in the manpages for xfd, xlsfonts, and xfontsel. The font server clients are described in the manpages forfsinfo,fslsfonts, andfstobdf. The OpenWindows font programs are described in the manpages for convertfont, rnakeafb, bldfarnily, and the OpenWindows documentation set. A technical description of X fonts is in the file rnit/doc/XLFD/xlfd.tbl.ms (the PostScript ver- sion is mit/hardcopy/XLFD/xlfd.PS.Z). For more information on the font server, see the manpage forfs and the original design docu- ment mit/doc/fontserver/design.rns. Beware of differences between this paper and the version of the font server included in the R5 distribution. The Font Server Protocol is described in the file rnit/doc/fontserver/FSlib.doc (PostScript ver- sion is mitlhardcopylFSProtocollfsproto.PS.Z). "The X Administrator: Font Formats and Utilities," by Dinah McNutt and Miles O'Neal, published in The X Resource, Issue 2, O'Reilly and Associates, Inc., Spring 1992. Section 5.5 of this chapter also appeared as an article entitled "The X Administrator: Manag- ing Font Servers," by Eric Pearce, published in The X Resource, Issue 3, O'Reilly and Asso- ciates, Inc., Summer 1992. 140 The X Window System Administrator's Guide 6 Color This chapter describes the mechanisms used to make color available to X servers that support color. It covers both the RGB and the Xcms methods of color management. In This Chapter: Color Specification in Release 4 and Earlier ....................................... 144 RGB Color Names ......................................................................... 144 Numeric Color Values .................................................................... 145 Adding Your Own Color Names (RGB) ........................................... 146 Fixing a Corrupted Color Database ................................................ 147 Color Specification in Release 5 (Xcms) ............................................ 147 Xcms Color Narnes ........................................................................ 148 Adding Your Own Color Names in Xcms ........................................ 150 Xcms Database Example ............................................................... 151 Device Profiles ............................................................................... 152 Related Documentation ..................................................................... 153 6 Color Color can make a world of difference for a user. Not all X users have servers that support color, but those that do need to be able to assign colors to their applications easily. The X Window System provides a way for colors to be addressed using both familiar names (such as red, blue, yellow) and obscure names (such as papayawhip, pale goldenrod, and dodgerblue). These names are then converted to a numeric representation that the server understands. Most color monitors are equipped with red, green, and blue electron guns, called "color guns," as shown in Figure 6-1. These color guns can be run at different intensities, producing different colors on the display screen. For example, the color "'red" could be displayed by turning the green and blue guns off entirely and turning the red gun on at full capacity. The red, green, and blue gun intensity values are called an RGB triplet.  enlarged pixel Figure 6-1. Red, green, and blue color guns Prior to X11R5, there was no built-in mechanism to address the lack of color consistency between displays. The mappings of RGB triplets to color names were hard-coded directly on the host system, using the RGB System. This meant that when a user requested "turquoise" on a particular system, he would get the same gun intensities regardless of which X server he was actually using. Since not all monitors are created equal, "turquoise" might look slightly different depending on which display it was being viewed on. R5 addresses this problem Color 143 with a new device-independent system called the X Color Management System, or Xcms. Xcms allows colors to be specified in internationally accepted standards that are in wide use outside of the computer field. This chapter discusses both the RGB and Xcms systems of color specification. 6.1 Color Specification in Release 4 and Earlier In Release 4 and earlier, the X Window System uses the RGB system for defining and dis- playing different colors. MIT X11R4 defines 738 color names by associating names with RGB triplets. The list of colors available on your system can be retrieved using the showrgb client, or by examining the file rgb.txt, usually in the directory/usr/lib/Xll or/usr/lib/Xll/rgb. (The con- tents of the rgb.txt file is identical to the output of the showrgb client.) If you run the showrgb client, be sure to use a pager, as there are screenfuls of output: % showrgb I more 255 239 213 papayawhip 240 255 255 azure 105 105 105 dimgray 176 196 222 lightsteelblue 127 255 212 aquamarine 0 250 154 mediumspringgreen 238 232 170 pale goldenrod ... Each line contains 4 columns. The first column is the red value, the second column is the green value, and the third column is the blue value. Each value is an integer from 0 and 255, inclusive. The fourth column is the name assigned on your host system to that particular combination of RGB values. The color "black" is defined with "0'" values for each color gun, and "white" is defined with maximum values for each gun. 255 255 255 white 0 0 0 black For a visual list of colors, try the contrib client xcolors. It will read the RGB database and display all the colors it finds. 6.1.1 RGB Color Names You can specify colors for clients by using the -fg and -bg options on the command line, or by setting the foreground and background resources for the client. For an xterm win- dow with an aquamarine background and blue text, for example, you could use the following command line: % xterm -bg aquamarine -fg blue 144 X Window System Administrator's Guide Alternatively, you could define the following resources: xterm*background: aquamarine xterm*foreground: blue To become familiar with specifying colors, try picking a few colors and pass them to a client to see the effect. If you get an error such as: Warning: Color name "barfgreen" is not defined in server database you probably chose a non-existent color or spelled a color name incorrectly. There are several "aliases" provided for a single color--for example, the color "dark slate grey" appears in rgb.txt with four different ways to name it: 47 79 79 dark slate gray 47 79 79 DarkSlateGray 47 79 79 dark slate grey 47 79 79 DarkSlateGrey All of these names produce the same color. 6.1.2 Numeric Color Values Clearly, every RGB value cannot have a name associated with it, but you can also specify colors by using the RGB values directly. Any color resource starting with the "#'" character is expected to have a number following it. The numbers are expressed in hexadecimal, with one, two, three, or four digits for each value: #RGB #RRGGBB #RRRGGGBBB #RRRRGGGGBBBB where "R","G", and "B" represent red, green, and blue digits. For example, all of the follow- ing color specifications represent the same value: XTerm* foreground: #f00 XTerm* foreground: #ff0000 XTerm* foreground: #fff000000 XTerm* foreground: #ffff00000000 XTerm* foreground: red You would usually produce colors with complex hex numbers only if you used a resoul ce editor such as OSF/Motif's mre,* props in Sun OpenWindows or the contrib client xcoloredit,% as color names are much easier for humans to deal with. *If you buy OSF/Motif 1.x source code from OSF, the mre program is included as "demo" program. There is a README file, but no manpage. %xcoloredit is available via anonymous ftp from export.lcs.mit.edu as/contrib/xcoloredit.tar.Z. Color 145 A complete description of the Xcms color model is beyond the scope of this book, which covers only the aspects of Xcms that affect administrators. 6.2.1 Xcms Color Names The Xcms color system uses a color database on the client side, whereas the RGB system database is used by the server (see Figure 6-2). All color names are looked up in a Xcms cli- ent database before being passed onto the server. Xcms introduces several new ways to specify color and retains all of the old ones. Some examples of colors used in resources are: *Background: RGBi: i. 0 / 1.0 / 0.0 *Foreground: NavyBlue *Text*Background: CIElab: 0.0/. 54/. 90 *Text*Foreground: White *Text*border: #ff00fc Under the Xcms system, a color specification is checked as follows: 1. If it begins with the character "#", the rest of the color specification is interpreted as a hexadecimal RGB value: # This syntax is still supported, but for only backwards compatibility. You are encouraged to use the newer uniform methods of numeric color specification. 2. If it contains the character ":", the prefix is checked to see if it is a recognized color space and if it is, the rest of the color is taken as a value in that color space: : The color spaces described here all use the "/" character to delimit the numeric values as in: : // but this method is specific to the particular encoding scheme used. 3. If it contains neither the ":" or "#" character, it is assumed to be a color name that would appear either in the Xcms client database or the RGB server database. The database is composed of pairs of color names and corresponding numeric color specifica- tions. The prefix on the number indicates the type of color system that is represented by the number. The following is a list of the current color spaces and their prefixes in the Xcms database. Name Various CIE formats Tektronix HVC RGB RGB intensity Prefixes CIEXYZ, CIEuvY, CIExyY, CIELab, CIELuv TekHVC RGB RGBi 148 X Window System Administrator's Guide Color Specification Client Side Server Side I RGB I I RGB ! : Figure 6-2. Xcms vs. RGB color specification Xcms stores its color database in a file called Xcms.txt, usually in/usr/lib/Xl 1. You can also create your own Xcms database and set the environment variable XCMSDB to it: % setenv XCMSDB /home/eap/mydatabase This will be used instead of the system database. The database is similar to the rgb.txt file in that it maps a color name to a numeric color spec- ification, but differs in that it recognizes all the new color specification formats (color spaces) in addition to RGB. It also supports color name aliases, as new names for an existing color can be defined here. The order of the columns is also reversed compared to the RGB database. Here is a portion of a sample Xcms.txt file (anything outside of the lines XCMS_COLORDB_START and XCMS_COLORDB_END is ignored.): XCMS_COLORDB_START 0. i red CIEXYZ: 0.371298/0.201443/0. 059418 green CIEXYZ: 0.321204/0.660070/0.159833 blue CIEXYZ: 0.279962/0.160195/1.210705 aquamarine CIEXYZ: 0.34672401/0. 54832153/0 grayO TekHVC: 0.0/0.0/0.0 grayl0 TekHVC: 0.0/i0.0/0.0 gray20 TekHVC: 0.0/20.0/0.0 mygreen aquamarine myblack black XCMS_COLORDB_mD Color 149 you use the TAB character between the color name and the beginning of the color specifi- cation. For example, to define the same color we created earlier for the RGB database: UglyGreen TekHVC: 88. 00004/72.66564/38.25869 5. Unlike the RGB system, you don't have to rebuild the Xcms database into a binary form after you edit it. 6.2.3 Xcms Database Example To illustrate the use of the client-side database, let's pretend you are a clothing designer for a mail order catalog. The marketing people have suggested that you choose interesting names for the colors of the garments. Let's also assume that you do not want to change any system files, only ones in your home directory. First, pick some nice colors using a color editor (such as xtici) and record the Xcms color specification in a file (maybe called FallCatalog.txt). Pick catchy names for each color you design and put them in the Xcms database format described earlier: # # Ocean's Start Fall Catalog Colors, attempt #i # XCMS_COLORDB_START 0.1 Berry CIEuvY: 0. 34568/0.45488/0.23013 Port CIEuvY: 0. 37875/0.45637/0. 05117 Straw CIEuvY: 0.19325/0. 53761/0. 85767 Paprika CIEuvY: 0. 39617/0. 51446/0.20947 GrapeFruit CIEuvY: 0.19261/0. 52793/0. 85069 Pool CIEuvY: 0.15229/0.48240/0. 60646 To test out this particular database by yourself, you have to tell Xcms where to look for it: % setenv XCMSDB -/FallCatalog. txt Let's say your clothing design program is called autoclad. You can use the color names listed in the Xcms database as resource specifications: Autoclad*outfitl.pants: Pool Autoclad*out fit i. tie: GrapeFruit Autoclad*outfitl. shirt: Berry You can also specify them on the command line: % autoclad -fg Port -bg Paprika If you want to try another set of colors, you can easily create another database and redefine the XCMSDB environment variable to tell Xcms where to look for the new database Color 151 6.2.4 Device Profiles An integral part of Xcms is Device Color Characterization (DCC), or a Device Profile. This is data that tells Xcms how to modify colors to fit your particular display device so they will look as they should. The data may be specific to the size, brand, model, and the type of screen on which you are displaying the color. The DCC data is stored in properties on the screen's root window. Some servers are able to automatically load the properties with data appropriate to the attached display(s). For servers that are built from MIT source, you will probably have to load the DCC data by hand. The xcmsdb client that comes with the MIT source distribution will load the DCC data from a text file you supply. There are some sample DCC files in the directory mit/clients/xcrnsdb/datafiles. Examine the top portion of the file for a description of the monitor. This is from the file Sparc1-19.dcc: SCREENDATA_BEGIN 0.3 NAME Sun SPARCstation 1 19" color monitor PART_JqUMBER 3 MODEL Hitachi HM-4119-S-AA-0, July 1989 SCREEN_CLASS VIDEO_RGB REVISION 2.0 COLORIMETRIC_BEGIN XYZtoRGB_MATRIX_BEGIN 2.898873264142915 -i. 137294035493891 0. 052401943410025 XYZtoRGB_MATRIX_END RGBt oXYZ_MATRIX_BEGIN 0.473564943660944 0.257273262661955 0. 028079972620921 RGBtoXYZ_MATRIX_END COLORIMETRIC_END INTENSITY_PROFILE_BEGIN 0 3 INTENS ITY_TBL_BEGIN RED 256 0x0000 0.000000000000000000 0x0101 0. 000000000000000000 -1.405253453722755 2.090468612762945 -0.208571555336254 0.335917466635681 0.659599528857479 0.116792496677968 -0.401375502033969 0.027097795177010 1.027214718138772 0.176180053794631 0.083127208480565 0.981397341912346 0xfdfd 0.975557917109458050 0xfefe 0.980162947219270220 0xffff 1.000000000000000000 INTENSITY_TBL_END INTENSITY_PROFILE_END SCREENDATA_END The file contains values that are loaded into the root window properties and then plugged into Xcms functions, converting each device-independent color value into a device-specific value and vice-versa. You can load a DCC file in the same manner as you would load a .Xdefaults 152 X Window System Administrator's Guide 7 X Terminals X terminals allowyou to put X on everyone's desk at relatively little cost. This chapter covers the issues with buying and configuring X terminals on your site. In This Chapter: Buying an X Terminal: What's What ................................................... 157 Monitors ........................................................................................ 157 Screen Size ................................................................................. 158 Resolution ................................................................................... 158 Depth .......................................................................................... 159 Refresh Rate ............................................................................... 159 Keyboard and Mouse ..................................................................... 159 X Server Software ......................................................................... 160 Special Features ............................................................................ 161 Memory Configuration .................................................................... 161 Network Interface .......................................................................... 162 X Terminal Setup ............................................................................... 163 Network Setup ................................................................................... 164 Getting the IP Address Using RARP ............................................... 165 Getting Information Using BOOTP .................................................. 165 Trivial File Transfer Protocol (TFTP) ................................................ 167 Setting Up the Network on the X Terminal ...................................... 168 Debugging Hints ............................................................................ 168 Error Messages ........................................................................... 169 Updating the arp Table ................................................................. 169 Name Server Problems ................................................................ 169 Fonts on X Terminals ......................................................................... 170 Font Formats ................................................................................. 170 The Font Server (R5) ..................................................................... 171 Choosing TFTP or NFS for Font Access ......................................... 171 Reading Fonts Using TFTP ........................................................... 171 Reading Fonts Using NFS ........................................................... 172 Configuring for the X Display Manager ............................................... 173 Configuring the X Terminal for xdm ................................................ 173 Configuring an R5 Host .................................................................. 174 Configuring an R4 Host .................................................................. 174 Configuring xdm Without XDMCP ................................................... 174 Setting Up Server Access Control .................................................. 175 Remote Configuration of X Terminals ................................................. 175 Remote Configuration on NCD Terminals ....................................... 176 Remote Configuration on Visual Terminals ..................................... 177 Remote Configuration on Tektronix Terminals ................................ 178 Reconfiguring the Host ...................................................................... 178 Increasing the Number of Processes ............................................. 178 Increasing the Number of Pseudo-ttys ........................................... 179 Increasing the Amount of Swap Space .......................................... 180 Swapping to a File ....................................................................... 180 Swapping to a Disk ...................................................................... 180 Related Documentation ..................................................................... 181 7 X Terminals Only a few years ago, the average UNIX site was equipped with a few expensive computers, connected to ASCII terminals on every desk. The X terminal is a newcomer in the market of UNIX hardware. Today, the rapidly-growing market of X terminals demonstrates how X 11 has changed the landscape of UNIX sites. An X terminal is as "dumb'" as an ASCII terminal, in that without a host computer to connect to, it's nothing but a blank screen with a setup menu. But when properly configured, the X terminal gives the user all the functionality of a workstation without all of its cost and admin- istrative worries. 7.1 Buying an X Terminal" What's What Today, there are more than two dozen vendors of X terminals. X terminals are sold with a variety of screen sizes, sc:een depth and resolution, memory configurations, and software. If you are buying an X terminal, you'll probably want to examine recent trade magazines for evaluations of current products. (The market changes so quickly that X terminals tested for this book will undoubtedly be outdated by the time you read this.) But for background of what you're getting into, this section describes some of the areas where X terminals differ and how they should factor in your decision.* 7.1.1 Monitors The monitor is arguably the single most important part of the X terminal. The size, resolu- tion, and depth of the monitor have a bigger impact on the perceived quality of the terminal than anything else. Accordingly, the type of monitor also has the biggest impact on the price of the X terminal as well. The short story is that, when choosing the monitor for an X terminal, you will end up weigh- ing the user's needs against how much money you have to burn. A user who spends the day in data-entry applications might be satisfied with a monochrome 15-inch monitor, but users *The comp.window.x newsgroup has a quarterly posting on X terminal manufacturers, including pricing informa- tion. X Terminals 157 7.1.1.3 Depth 7.1.1.4 The depth of an X terminal is determined by the number of bits per pixel it supports for color information. A monochrome (a.k.a. static gray) monitor has one bit per pixel: each pixel is either black or white, with no shades of gray. Most grayscale and color monitors have 8 bits per pixel, although some may have as few as 2 or 4, and others may have as many as 12 or 24. A color monitor with 8 bits per pixel can support as many as 28 = 256 simultaneous colors; likewise, a grayscale monitor with 8 bits per pixel can support 256 shades of gray. If you choose to buy an X terminal with a depth of only 2 or 4 bits per pixel, beware that some X clients are dumber than others. Some of the less robust applications assume that if you have a depth greater than 1, then you must have 8 bits per pixel. (These clients can also cause problems on displays with 12 or 24 bits per pixel.) Another possible complication is that, if you buy a grayscale monitor, you may find that some applications think you have color. For example, on a 2-bit grayscale display, FrameMaker will try to display windows using its color default of a blue background. The best way to deal with this complication is to set up your application resources to use only black and white; see Section 3.5.6 for an example of using xdm and display classes to set up different defaults according to the display type. Although you might be concerned that an X terminal with 8 bits per pixel may produce 8 times as much traffic as one with a monochrome display, this is seldom an issue in practice. Most clients address only 1 bit per pixel, regardless of the depth of the display. Refresh Rate The refi'esh rate of a monitor is the frequency that the screen is redrawn. If the screen is refreshed too slowly, it may be noticeable to users and quickly cause eye-strain. In general, a refresh rate of less than 70 Hz is considered to be too slow for daily use. 7.1.2 Keyboard and Mouse There are several different types of keyboards available for X terminals. Since there are few things more frustrating to users than having to use a keyboard they are unaccustomed to, choose the keyboard carefully. DEC users are used to different key configurations than both Sun users and PC users. Users have different ideas of what a "UNIX" keyboard is--some users think it's a Sun3 keyboard, others think it's a Sun4 keyboard, and some think it's a DEC keyboard. (What NCD calls a UNIX keyboard is actually a DEC keyboard.) Keyboards differ in things like the position of the tilde and escape keys, the position of the Alt key(s), and the positions of the CTRL and CAPS LOCK keys (which are sometimes reversed, to the great frustration of the user). Most X terminal manufacturers also have inter- national keyboards available. Almost all X terminals come with a 3-button mouse. The only deviations between the mouse distributed with X terminals is whether it's a mechanical mouse or an optical mouse. Optical X Terminals 159 7.1.4 Special Features As the X terminal market has grown, X terminal capabilities have expanded as well. Local Clients Some X terminals can run X clients locally. Window managers are the most popular clients to run locally, and can make quite an impact on perfor- mance. Note, however, that the more you want your X terminal to do, the more memory you'll need. And remember that the whole idea of X and the X terminal in particular is to have cheap desktop access to remote comput- ing-so don't go wild on local clients unless you have real reasons for keeping network traffic at a minimum. For example, if you're running the X terminal over serial lines, you may want to have a local window manager. In any event, the local window manager will be more responsive, but you have to live with the X terminal vendor's choice of a window manager. Backing Store Almost all X terminals are capable of backing store. Backing store allows an X server to keep an image of obscured windows in memory so they can be redrawn quickly and without network overhead when exposed. To use this feature, however, terminals need to have some extra memory installed, or they may produce an error message (or crash). Some terminals give the option of using backing store only when there is enough memory available; enable this option if it is provided with your terminal, since it might help performance. Beware, however, that when the X terminal later needs more memory, it may not consider the memory set aside for backing store to be fair game. Remote Configuration All X terminals can be configured using a local setup menu. Some X termi- nals, however, also provide the ability to read their configuration parame- ters from a file on a remote host at boot time. This becomes a great advan- tage when you have many X terminals to maintain--it's always easier to edit files on-line than to visit every office on your site after hours. See Sec- tion 7.6 for more information on remote configuration. Peripheral Support Many X terminals allow you to hang printers off their serial port. In addi- tion, some X terminals made by IBM have a port for connecting a hard drive directly to the X terminal. The hard drive is used for "'swapping" large images, reducing memory requirements. 7.1.5 Memory Configuration X terminals range from 512K of memory to 72MB. As usual, what you should get depends on what you plan to use it for. If you plan to run graphics-intensive applications, you'll want more memory for a reasonable display. Remember that the more pixels on the screen and the greater the depth of your terminal, the more memory you'll need. X Terminals 161 In addition, many of the fancier features available for X terminals can be memory-intensive. X terminals that can run clients locally will need more memory to support them. If you want your X terminals to do backing store, that will also require more memory. Although many X terminals are smart enough to cut down on backing store when memory gets low, beware that some X terminals might crash if they run out of memory. If this hap- pens, it's a good idea to disable backing store completely, if you can. Some X terminal manufacturers use their own proprietary memory. If you think this may turn into an issue when it becomes time to upgrade the memory, you might prefer to stick to a manufacturer that uses industry-standard SIMMs. 7.1.6 Network Interface Most X terminals come with built-in Ethernet and TCP/IP support, and most also provide a serial interface. Some X terminals support the IBM Token Ring beneath TCP/IP. DECnet is supported by some X terminals as well. Most X terminals support SLIP for running X over a modem line. X terminals supporting PPP for modem lines are just now coming to the market. In addition, some X terminal manufac- turers have their own serial line protocols that are more efficient than SLIP, such as NCD's Xremote and Serial Xpress by Tektronix. X Terminal Alternatives There are a few alternatives to buying X terminals. If you already have PCs available, there are many X servers that run on PCs. Although PC X servers are slower than X ter- minals and have inferior resolution, they are often sufficient for "occasional" X users, and can be much cheaper (depending on how "souped-up" your PC is already). See Appendix C for more information on PC X servers. Another alternative is to use diskless workstations instead of X terminals. New diskless workstations are significantly more expensive than X terminals, and create more admin- istrative overhead. But if they have enough RAM, diskless workstations are generally faster and reduce both network traffic and the load on the central host, since all (or most) X clients can run locally. You can also turn an older workstation into an X terminal by installing a stripped-down kernel running only the X server. See Section A. 10 for more information on how this is done. 162 X Window System Administrator's Guide 7.2 X Terminal Setup Assuming you now have an X terminal, you probably want to make sure it works before you do any serious configuration. For an X terminal running over TCP/IP, this means you have to perform the following steps. These steps are described in more detail later in this chapter. Please note that X terminals may have different procedures where noted. 1. Configure the local name server to include a new IP address for the new machine. If you aren't already familiar with this procedure, see Section A.6 for more information. 2. Install the fonts on the host machine. The X terminal should have arrived with a font tape. Unless both the X terminal and the host support the R5 font server (and to this date, no X terminals do), you need to install the fonts as documented by the X terminal vendor. Where you install your fonts depends on how you intend for them to be read. Some X ter- minals can read fonts via NFS; all X terminals can read fonts via TPTP. Although it may be preferable to read fonts via NFS, it's a bit harder to set up. For easy setup, therefore, install the fonts in/pboot/usr/lib/Xll/vendorConts. (You can move the fonts elsewhere if and when you switch to NFS.) See Section 7.4 for more information on font manage- ment for X terminals. See Section 7.3.3 for more information on TPTP. If the X terminal has support for the R5 font server, and you have an R5 machine running the font server, you don't need to install new fonts. You can just set up the X terminal to use the font server, specifying the name of the font server (consisting of transport, host, and port number). Note that some X terminals may use the term "font server" differ- ently--i.e., as the host that the X terminal reads its fonts from, but without actually using the R5 font service protocol. 3. Install the X server. If the X server is built into ROM, you can skip this step. Otherwise, the X server software was probably sent on a tape, to be copied onto the host and read by the X terminal at startup via TFTP. Copy the X server program to the proper directory on the host machine (probably /pboot) and make sure that the TPTP daemon is running on the host. (See Section 7.3.3 for more information on TFTP.) Next, tell the X terminal where to download the server from. At this point, you need to consult your documentation; however, for an example, our NCD X terminals use a com- mand line similar to the following on their boot monitors: > bt Xncdl6 140.186.65.137 140.186.65.25 The X terminal will boot using the file /(-tpboot/Xncdl6 on the host with IP address :1.40. :1.86.65.25. The X terminal will use IP address :1.40. :1.86.65. :1.37. After the X terminal is initially booted, you can configure its setup menu so that it can automatically boot at power up. Alternatively, if the X terminal uses BOOTP, then you can enter this information into/etc/bootptab; see Section 7.3.2 for more information. X Terminals 163 4. Now it's time to connect to a host. If you don't have R4 or R5 xdm already running on a host machine, see Section 3.3 for information on how to start it up.* Once you have xdm running on a host machine, some X terminals arrive pre-configured to do a Broadcast query. Those terminals should receive the login box immediately once the X terminal has been supplied a broadcast address. If there's some complication, you can configure the X terminal to query the host running xdm directly. See your vendor's docu- mentation to learn how to configure the terminal to use XDMCP. Connecting with Telnet If you have trouble connecting using xdm, test the connection using telnet. Most X ter- minals are supplied with a telnet window for starting an initial client. The telnet window may be part of the setup menu, or it may be a local X client. See your vendor's docu- mentation to learn how to access the telnet window. Once you have a telnet window, try to connect to a host using its IP address. If you can't connect, there's either a cabling problem or there's something wrong with the network configuration of the X terminal. If you can connect, log in and type "who am i'" to confirm that you're resolving to the correct hostname. Then set the DISPLAY environ- ment variable to the hostname, and start an initial xterm. imui@ruby 26% who am i ruby:imui ttyp6Aug 20 18:18 (ncd9.ora.com) imui@ruby 27% setenv DISPLAY ncd9 .ora.com: 0 imui@ruby 28% xterm & If the telnet session ran as a local client, the new xterm should pop up immediately. If it ran as a subsession of the setup menu, you have to suspend the setup menu to access the xterm window. If an X client can connect to your X terminal this way, then there must be something wrong with your xdm configuration. See Chapter 3 for more information. 7.3 Network Setup Now for the details. To configure the X terminal for the network, you first need to set up the hosts database. If you aren't already familiar with how to do this on your site, see Section A.6 for more information. The hosts database maps hostnames to IP addresses. The next issue is how the X terminal knows its IP address. Some X terminals can save their IP address in NVRAM (Non-Volatile RAM). Other X terminals, however, have no way of storing their IP addresses. Instead, they have to depend on the host to tell them their IP address at boot time, using RARP (Reverse Address Resolution Protocol) or BOOTP (Bootstrap Protocol). * If you have configured the Xaccess file to restrict xdm access to specified hosts, you may have to add the X terminal to the list; see Section 7.5.2 for more information. 164 X Window System Administrator's Guide Another issue, for X terminals that boot over the network, is how the terminal accesses its server binary. The server image for these X terminals resides on a host somewhere on the net- work, and the X terminal needs to be able to read their boot image using some protocol, gen- erally TFTP (Trivial File Transfer Protocol). 7.3.1 Getting the IP Address Using RARP The way RARP works is that the host machine keeps a table of Ethernet addresses and the corresponding IP addresses. This table is kept either in/etc/ethers or in the ethers database if the host uses NIS. The rarpd daemon waits for broadcast requests from X terminals and other diskless machines. In its broadcast, the X terminal supplies its Ethernet hardware address (which is built into their Ethernet interface). The rarpd daemon on the host responds with its IP address on that network. If you don't run NIS, adding a new RARP entry is just a matter of editing /etc/ethers. /etc/ethers has a simple syntax similar to /etc/hosts. You can get the Ethernet hardware address of the new X terminal from the monitor at boot time. NCD X terminals, for example, print a message similar to the following: Boot Prom V2.1.0 Testing available memory 3.0 Mbytes Network controller passed 00:00:A7:I0:II:BF Keyboard controller V2.00 To add this terminal as ncd4. add the following line to/etc/ethers (convert the letters in the hex number to lowercase): 00:00:a7:10:ll:bf ncd4 The RARP daemon uses the ethers database along with the hosts database to determine the X terminal's IP address. Note that for RARP to work. you must have an entry for the new X ter- minal in the hosts database. If you run NIS. see Section A.7 for information on how to add an entry to the ethers database. 7.3.2 Getting Information Using BOOTP BOOTP is similar to RARP, but it gives a bit more information. RARP will tell the X terminal only its IP address. BOOTP can be set up to tell the X terminal its subnet mask, name server host, and what machine and pathname to download the X server from. The BOOTP daemon bootpd uses a file called /etc/bootptab. The BOOTP protocol has changed over the years, as has the syntax for bootptab. Standard BOOTP (RFC951) uses a single-line entry per hardware address, to supply the IP address and the name of the boot file The first two uncommented lines contain, respectively, the directory in which the boot files reside, and the default boot file. For example: # # default boot directory # X Terminals 165 /t ftpboot : / # default bootfile Xncdl9 # bootp clients -- # host htype haddr iaddr bootfile ncd4 1 00:00:A7:I0:II:BF 140.186.65.13 Xncdl 6 The first field is the hostname of the BOOTP client (in this example, ncd4). The second field is the hardware type, with l=Ethernet. The third and fourth fields represent the hardware and Internet addresses. The fifth field is the name of the boot file to use in the specified directory. (The ":/" following the default boot directory/pboot is needed for systems that run TFTP in restricted mode.) "Extended" BOOTP (RFCI048 with CMU extensions) has syntax similar to that of /etc/termcap and /etc/printcap. A single BOOTP definition is in two parts, a "global" part used for all machines and a part that is particular to the new machine. The "global" part must appear first, and might resemble the following: global : \ : sm=255.255.255.0 : \ :ht=ethernet : \ : ds=140.186.65.25 : \ :ns=140.186.65.25 : \ : to=18000 : \ :hn:\ :vm=rfc1048: The client-specific part might then resemble: ncd4 : \ : hd=/t ftpboot : \ :bf=Xncdl6 : \ : tc=global : \ :ha=0000A71011BF: \ : ip=140.186.65.13 : The two-character capabilities have the following meanings: bf Boot file for client machine ds IP address of Internet domain name server host ha Hardware (Ethernet) address hd Home directory for boot files hn Host name ht Hardware type -ip Internet address ns IP address of UDP name server host sra Subnet mask tc Append specified entry to Time out, in milliseconds vra Version number of BOOTP protocol on the host The hn entry should be set to the hostname of the terminal. For the g'loba] entry, hn should be left blank (as shown above). 166 X Window System Administrator's Guide 7.3.3 Trivial File Transfer Protocol (TFTP) An X terminal needs to use some simple transfer protocol to download its server software. Most X terminals use TFTP as their transfer protocol of choice. Since TFTP does not require a user name or password in order to allow a connection, we strongly recommend running tftpd in "restricted" or "secure" mode. Using restricted TFTP, the server code must be copied to the TFTP home directory--usually/tftpboot--and the X terminal needs to be told which host to boot from. When the X terminal connects to the host via restricted TFFP, the host's TFTP server does a chroot to/tftpboot and reads files relative to the new root. The TFFP server is usually run from inetd, which is started at boot time from /etc/rc or rc.local, inetd manages several daemons listed in/etc/inetd.conf; requests for those services are routed through inetd, which then starts up the appropriate daemon. TFFP is often disabled from inetd.conf because it is considered a potential security hole. If you're not sure if TFTP is active, first make sure that inetd is running, and if it is, then look in the configuration file for inetd (either/etc/inetd.conf or/etc/servers) to make sure TFTP is called. In/etc/inetd.conf, the line starting TFTP should look something like the following: tftp dgram udp wait root /usr/etc/in.tftpd in.tftpd -s /tftpboot In/etc/servers, it should look like: tftp udp /usr/etc/in.tftpd -s /tftpboot (The -s option says to run TFTP in "secure" mode, so that machines connecting via TFTP can read files only in/rftpboot. On some systems this option appears as -r, for "'restricted" mode. Since TFTP is such a security hazard, we do not recommend using it except in restricted mode; otherwise, anyone on the network can get any file on your host!) . You can also test if TFTP is running by trying it manually: imui@reno % tftp ruby tftp> status Connected to ruby.ora, com. Mode: netascii Verbose: off Tracing: off Rexmt-interval: 5 seconds, Max-timeout: 25 seconds tftp> get Xncdl6 Received 846244 bytes in 8.4 seconds tftp> (After quitting TFTP and confirming that the file was properly retrieved, you probably want to remove it from the directory it was copied to.) Test if TFTP is running in restricted mode by requesting a file that isn't in/tftpboot: tftp> get /etc/motd Error code i: File not found tftp> Another possible error message on some systems is: tftp> get /etc/motd Transfer timed out. tftp> X Terminals 167 If this command is successful but "hostname : 0" was not, then the problem could be with the name server configuration, with the NIS configuration, or with the resolver configuration file ( /etc/resolv.conf). 7.4 Fonts on X Terminals Many X terminals have some fonts built into the server, but you usually need to read fonts from the host machine as well. Most X terminal manufacturers supply a "font tape" with their product, with fonts that need to be read on your host system. At minimum, the font tape that comes with the X terminal contains vendor-specific .snfor .pcfversions of the BDF fonts supplied by the MIT source distribution of XI 1. Many vendors also supply some additional fonts. We said earlier that for easy set up, just put the fonts in/(f-tpboot. But for real setup, you prob- ably want to think a little harder about where to put the fonts and how they should be read. 7.4.1 Font Formats Every X server vendor supplies its own font tree for that server. Each font tree takes approxi- mately three to four megabytes of disk space. If you have X terminals manufactured by three different vendors, therefore, you're using up 9 to 12 megabytes just to hold their fonts--not to mention the fonts for running X on the local display of the host machine. Luckily, you can often get away without keeping multiple fonts on line. For .snffonts, there are four ways that fonts for different servers might deviate: the byte order, the bit order, the scanline unit padding, and the glyph padding. In most cases, the scanline and glyph padding for a server is 1 (the default), so you seldom have to consider those variables for incompati- bilities (although if you find that your characters are drawing over one another, you're proba- bly using fonts compiled with a different padding). The byte order and bit order generally go hand-in-hand. So for most cases, you really need to keep at most only two sets of .snffonts on line: one for X terminals that number bytes starting at the high end (big endian), and one for X terminals that number bytes starting at the low end (little endian). PCF fonts don't have byte-order incompatibilities, so if all your X terminals support PCF fonts, you might be able to get away with a single set of fonts. For example, NCD X terminals are big endian, so if they are reading fonts from a Sun works- tation (a big endian machine), chances are that they can read and display the .snffonts com- piled for the local server without a hitch. The bdftosnffont compiler defaults to the byte order on the host machine, so there should be no problem in font compatibility between Sun and NCD X servers. In this situation, you would not have to keep the NCD fonts on line, but could have the X terminals read the Sun-compiled .snffonts. The easiest way to do this is by linking the standard X11 font directory to the server-specific font directory. For example: # mkdir lusrlliblX11Incd # in-s /usr/lib/Xll/fonts /usr/lib/Xll/ncd/fonts 170 X Window System Administrator's Guide (You may still want to use the fonts supplied with the X terminal, since they may be more sophisticated than those on the core MIT distribution, but that's up to you.) HDS X terminals are little endian. This means that the fonts on a Sun are not compatible with those supplied by HDS (although fonts on a VAX are). There is another hitch. Although each of the factors for font compatibility can be overridden on the bdftosnf command line, the options for a different bit or byte order will apply only to the glyph section of the font--the header section will still be in the bit and byte order of the host. So HDS supplies its own font compiler, bdftohds, since they cannot rely on the fonts compiled by bdftosnf on a big endian machine. Many X terminal manufacturers supply their own compiler to convert .bdffonts to their own format. Some X terminals (e.g., those made by Visual) can read fonts in either byte order. Further- more, X terminals are beginning to support the .pcf font format, which does not have byte- order incompatibilities. Tektronix is one vendor that currently sells X terminals supporting both .pcf and .snf formats. 7.4.2 The Font Server (R5) With Release 5 of X 11, a lot of the font confusion is cleared up with the font server. R5-com- patible X terminals (of which there are currently none) supply a field in the setup menu for the address of the font server. If your X terminal provides this functionality, and you have an R5 host available to run a font server, run (do not walk) to Section 5.5 to learn how to enable the font server on the host. You have been spared a giant headache. Some X terminal vendors, such as Visual Technology, have their own proprietary font server mechanism. Although they are unlikely to be compatible with the R5 font server, these pro- prietary font servers are worth looking into if running the R5 font server is not an option. 7.4.3 7.4.3.1 Choosing TFTP or NFS for Font Access Assuming that your X terminal does not support the font server introduced with X11R5, you are stuck with either TFTP or NFS. (Some X terminals also support using FTP, but you're probably better off not opening that can of worms.) Reading Fonts Using TFTP It's easy to install fonts to be transferred with TFTP. But since TFTP doesn't provide any user authentication, you need to decide whether you want to run it in restricted mode or not, and either option has its downside. If you run TFTP in restricted mode, you have to put the font files in the TFTP home directory tree (usually /tftpboot). When the X terminal connects to the host using TFTP, it will do a chroot to/tftpboot and then look for the fonts relative to that directory--so, for example, an NCD X terminal will effectively look for its fonts in/tftpboot/usr/lib/Xll/ncd/fonts. X Terminals 171 7.5 Configuring for the X Display Manager If you're using X terminals, you probably want to control them using the X Display Manager (xdm). There are other ways of starting sessions, such as logging on via telnet and starting cli- ents manually, or using the rexec (remote execution) capabilities supported by some X termi- nals. But if both the host system and the X server support the XDM Control Protocol (R4 or later), then you should definitely use xdm. If you aren't running xdm at all, read Section 3.3 for more information to get it started. See Section 3.1 for some background information on XDMCP. 7.5.1 Configuring the X Terminal for xdm X terminals Direct Indirect Broadcast generally supply three different ways of running XDMCP: Calling XDMCP "directly" requires that the name or IP address of the host run- ning xdm be supplied. The X terminal will request an xdm login box from that host and from that host only. Calling XDMCP "indirectly" requires that the name or IP address of the host be supplied. The host is then expected to pass the XDMCP request to another host or group of hosts. For a host running vanilla X11R4, an "'Indirect" query is treated the same as a "Direct" one. For a host running X I 1R5, it can be configured to respond to an "Indirect" query by forwarding the request to another host or by offering a list of hosts for the user to choose from. See Section 3.5.3 for infor- mation on how to configure how "Indirect" queries are treated on an R5 host. Calling XDMCP in "broadcast" mode does not require a hostname or address, but means that the X terminal sends out a general request for an xdm login box across the subnet. For most X terminals, the first host that responds is the one that is used. For some smarter X terminals, the X server gathers responses from all hosts on the local network and allows the user to choose one to start up on. If an X terminal doesn't connect to any host running xdm under a Broadcast query, but can connect to hosts via a Direct or Indirect query, then there is proba- bly something wrong with the Broadcast address that you have configured the X terminal to use. See your vendor's documentation for information on how to set the Broadcast address. Note that Broadcast queries are restricted to the local network or subnet. Unlike Direct and Indirect queries, you cannot use a Broadcast query to access a host through a gateway. X Terminals 173 7.5.2 Configuring an R5 Host If the host is using Xl 1RS, then you need to make sure that the new X terminal is given per- mission to connect to xdm on the host. The/usr/lib/Xll/xdm/Xaccess file controls which X servers can connect to the host. The Xaccess file also controls how Indirect queries are dealt with on that host. For example, to add ncd4 to the list of X servers that can connect to the host, you can simply add the line: ncd4. ora. cc[n Note that the Xaccess file accepts wildcards. So ncd4 would already have permission to con- nect to the host if there were a line such as: *. ora. cc[n See Section 3.5.3 for more information on how to configure the Xaccess file. 7.5.3 Configuring an R4 Host If the host is using X11R4, you don't need to make any changes on the host for a XDMCP- compatible X server to use xdm--you just need to configure the X terminal to use XDMCP. 7.5.4 Configuring xdm Without XDMCP If either the X server or the host is not XDMCP-compatible (R3 or earlier), then you need to make an entry in the/usr/lib/Xll/xdm/Xservers file in order to manage the X terminal using xdm. For example, you can add the line: ned4. ora. cc: 0 foreign xxx (The "xxx" is required because although R3 xdm ignores the third field in a foreign entry, the field cannot be left empty.) See Section 3.5.2 for more information on how to configure the Xservers file. The problem with using pre-XDMCP xdm is that, should the X terminal be turned off for any reason, xdm needs to be restarted before it will know to reconnect to the terminal. If you have no choice but to use an R3 host system, you might be interested in X terminals that offer their own proprietary protocol for controlling xdm. X terminals made by Visual, for example, pro- vide XDSXDM for controlling Release 3 xdm for their XDS terminals. 174 X Window System Administrator's Guide 7.5.5 Setting Up Server Access Control As described in Chapter 4, there are two current mechanisms for restricting clients from accessing a particular server: host-based access control and user-based access control. Host-based access control is controlled entirely by the server. Some X terminals allow you to keep a list of hosts that you want to allow access from, using the setup menu on the X termi- nal. However, it's better to use user-based access control if you can. User-based access control is controlled both by the server and by the X Display Manager. Check your X terminal documentation to see if user-based access control is supported. If it is, then check if xdm is set up to use user-based access control on X terminals. You can deter- mine this by examining the configuration file for xdm, usually/usr/lib/Xll/xdm/xdm-config. The following line: Di splayManager * authorize: true specifies that authorization is being used for all X servers managed by xdm on that host. Host-based access control overrides user-based access control. This can cause complications when your X terminal supports both types of server access control. Contrary to what your instincts might be, to enable user-based access control you should make sure that host-based access control is also enabled--disabling host-based access control may effectively result in all hosts having access to the server, regardless of any user-based access control in effect. If you want to use user-based access control exclusively, you should make sure host-based access control is enabled but the list of hosts that are allowed access is empty. See Section 4.2.4 for more information. See Chapter 4 for more information on security issues and Xl I. 7.6 Remote Configuration of X Terminals Many X terminals provide a facility called remote configuration. Our experience with remote configuration has been very positive, so we recommend that if you have more than one of a single type of terminal, you should consider using remote configuration. With remote configuration, the parameters in the setup menu can be defined in a file to be downloaded by the X terminal when it boots. What this does for the administrator is that it makes it easy to change a given field--the administrator no longer needs to visit each X ter- minal on the site after hours and change their setup menus manually, but can simply edit the remote configuration files for each terminal. The next time the terminal is booted, the new values will be read. Another advantage of remote configuration is ease in troubleshooting. The danger of user- accessible setup menus is that a user might unknowingly change something that disables their terminal. Many terminal manufacturers provide a mechanism for "locking" the current setup menu settings with a password--so that only administrators with the password will be able to make further changes to the X terminal configuration. Using remote configuration, however, X Terminals 175 the X terminal is configured at boot time from a file residing on a host. If a terminal's set up is corrupted, therefore, the user can restore its settings just by rebooting the X terminal. Another advantage of using remote configuration is that it can help you get out of a jam if for some reason your current configuration is so corrupted that you cannot even access the setup menu. If you are using remote configuration, you can just edit the file and then reboot the ter- minal. Each X terminal vendor has its own syntax for remote configuration. To give you an idea of what they do, here's a description of how remote configuration is handled by various X ter- minal vendors. 7.6.1 Remote Configuration on NCD Terminals On NCD X terminals with remote configuration turned on, each X terminal at boot time looks for a configuration file whose name is derived from its IP address, in hexadecimal. For example, an NCD X terminal with IP address :1.40. :1.86.65. :1.3 would look for a configura- tion file called 8CBA410D in the directory /usr/lib/Xll/ncd/conJigs. (See Section A.9 for information on how to get the hexadecimal equivalent of an IP address.) If the configuration file for its specific IP address doesn't exist, the X terminal then looks for a configuration file called ncd_std in the same directory. If you are using NFS to read the remote configuration file, the X terminal needs to have read access for the/usr/lib/X11/ncd/conJigs directory on the host. If you are using restricted TFTP to read the remote configuration file, the configuration files need to be installed in the /tftpboot/usr/lib/Xl l /ncd/configs directory. The following is a portion of the remote configuration file used by our NCD X terminals: background = white backing-store = by-request baud-I = 9600 boot-at-reset = yes boot-server = 140.186.65.25 broadcast-address = 140.186. O. 0 data-bits-i = 8 default-cterm-host = O. 0 default-domain = ora. cc ... virtual-terminal-at-reset = xdm xdm-access = direct ... xdm-server = 140.186.65.25 Now for the good news: NCD doesn't require you to write it all in by hand. Instead, you can set up a single terminal, make sure it works to your liking, and then download its parameters to a file using the Utilities menu. The next problem is how to tell the terminal to read the remote configuration file the first time. There's a logistical problem involved: NCD X terminals support NFS only if they're using remote configuration, so if you want to read the actual configuration file over NFS, you 176 X Window System Administrator's Guide 7.6.3 Remote Configuration on Tektronix Terminals For Tektronix X terminals, the syntax for remote configuration files consists of commands followed directly by parameters. Lines starting with "#" are taken as comments. The remote configuration file is read using the same file access method that is used for downloading the server image (i.e., TFTP), so remote configuration is not available for terminals that boot from ROM. Tektronix remote configuration files need to be thought of somewhat differently, since the terminal executes each line as a command and doesn't just store it as a variable definition. This means that you have to be careful about the sequence of commands. For example, you need to declare a host's address using the ip_host_table command before you can use its hostname for thefile_host_name_l command. The sample is a portion from a configuration file for Tektronix X terminals: ip_host_table 140.186.65.25 ruby ip_host_table 140.186.65.35 opal fi le_host_name_l ruby file_access_l TFTP 7.7 Reconfiguring the Host When you replace an ASCII terminal with an X terminal, you're giving a user a whole new world of functionality. You are also allowing that user to use five to ten times the resources he or she used previously. Whereas a user on an ASCII terminal might run maybe one or two processes in the background (which usually exit on their own), a user on an X terminal can go hog wild, running an xclock, xbiff, multiple xterms, a mail reader, a news reader, etc.--all this before starting actual "work." In addition, xdm forks a copy of itself for every display it manages. In this section, we include an example of how to configure a SunOS system to support more users, processes, pseudo-ttys, and swap space. Refer to your vendor's manual for information on how to reconfigure the kernel on your system. 7.7.1 Increasing the Number of Processes When you set up a site for running multiple X terminals, you probably want to increase the number of processes that the host can handle at once. If the system runs out of processes, it may give an error: % is No more processes % or commands may fail silently. 178 X Window System Administrator's Guide To increase the number of processes on SunOS 4.x, edit the kernel configuration file. The name of this file follows the form /sys/arch/conf/kernel_name. For our Sun4, this file is /sys/sun4m/conf/RUBY. Edit the rnaxusers line as appropriate. For example, change: maxusers 8 to: maxusers 48 Then rebuild the kernel and reboot: # /etc/config RUBY # cd ../RUBY # make # cp /vmunix /ovmunix # cp vmunix / # sync; reboot Be careful to follow the guidelines in vendor US manuals in increasing maxusers. If you increase it beyond the specified upper limit, you run the risk of wasting resources. 7.7.2 Increasing the Number of Pseudo-ttys Another consideration is the number of pseudo-ttys, or pt)'s, a host can handle. A typical symptom of running out of ptys is an immediate logout when trying to open a new connec- tion: % rlogin rock Pas sword: SunOS Release 4.1.2 (ORAWEST) #3: Wed Jul 29 12:50:14 PDT 1992 TERM= (xterm) Connection closed. On SunOS, edit the same kernel config file/svs/arch/conf/kernel_natne. Find the line for devices. pseudo-device pty # pseudo-tty' s, also needed for SunView The default entry is for 48 ptys. Appending a number suffix changes it accordingly: pseudo-device pty128 # pseudo-tty's, also needed for SunView We have now set up the system to support 128 pt3's. (See your documentation to learn what the maximum number ofptys on your system is. SunOS 4.1.2 can handle up to 256 pO's.) Next, make more ptys in/dev for each bank of 16 prvs. Since we have expanded to 128 pt3"s, this would be 128 + 16 = 8 banks of p.tys in total. The p,ty banks are numbered from 0, so you'd remake banks 0 through 7: # cd /dev # MAKEDEV pty0 ptyl pty2 pty3 pty4 pty5 pty6 pty7 # is pty?? I wc -i 128 Then rebuild the kernel and reboot as shown above. # /etc/config kernel name X Terminals 179 Finally, run swapon and then check the size ofthe swap space again: # swapon -a Adding /dev/sd2b as swap device # /etc/pstat -T 163/2758 files 829/1223 inodes 74/778 processes 14488/127944 swap The swap space has doubled to approximately 128MB. 7.8 Related Documentation Articles on X terminals appear frequently in periodicals serving the X and UNIX community. Advertisements (in periodicals that accept them) are also very helpful for keeping track of the latest and greatest X terminal technology. In addition, a list of X terminal manufacturers is posted quarterly to the comp.windows.x newsgroup. The following Nutshell Handbooks might come in handy: Managing NFS and NIS by Hal Stem; Essential System Administration by AEleen Frisch; TCP/IP Network Administration by Craig Hunt; and DNS and BIND by Cricket Liu and Paul Albitz. X Terminals 181 8 Building the X Window System By necessity, you can't do anything with X until it is installed on your system. This chapter tells you how to build and install X. In This Chapter: Installation Issues .............................................................................. 185 Should You Use MIT Source? ........................................................ 185 Types of Vendor-supplied X Distributions ....................................... 186 X from Your OS Vendor ............................................................... 187 X from a Third Party .................................................................... 187 X Source Code from MIT ............................................................... 188 Complete or Client-only Distribution? ............................................. 189 Installing Multiple X Releases ........................................................ 189 Source Preparation ............................................................................ 191 Do You Have Enough Disk Space? ................................................ 191 Is Your Platform Supported? .......................................................... 192 Applying OS Patches ..................................................................... 194 Applying X Patches ........................................................................ 194 Creating a Link Tree (Optional) ...................................................... 196 Simplest Case Build ........................................................................... 197 Host Problems ................................................................................... 198 Disk Space .................................................................................... 198 Changing the tmp Directory Using TMPDIR (Ultrix and HP-UX) ..... 199 Changing the tmp Directory Using -temp (SunOS) ....................... 200 Shared Library Installation (SunOS) ............................................... 200 NFS Installation ............................................................................. 201 NFS Installation Without Root Access .......................................... 201 Installation Over the Network (rdist) ............................................. 203 Installing the termcap or terminfo Definition for xterm ..................... 203 Simple Configuration .......................................................................... 204 Configuration Parameters .............................................................. 205 site.def ........................................................................................ 205 The ProjectRoot Flag ................................................................... 207 The Platform Configuration File (platform.cf) ................................ 208 Configuration Example 1 ................................................................ 210 Configuration Example 2 ................................................................ 211 Configuration Example 3 ................................................................ 212 Configuration Example 4 ................................................................ 212 Configuration Example 5 ................................................................ 213 Other Build Flags ........................................................................... 213 xterm Build Flags ......................................................................... 214 Building Programs After X Is Installed ................................................ 214 xmkmf ........................................................................................... 214 Include Files .................................................................................. 215 Libraries ........................................................................................ 216 More About imake ............................................................................. 216 The make Program ........................................................................ 216 The C Preprocessor ....................................................................... 217 Imake Syntax ................................................................................. 219 Comments in imake ..................................................................... 219 Multi-line Macros (@@) ............................................................... 220 Concatenating Macros ................................................................. 221 Dealing with Tabs ........................................................................ 222 imake Configuration Files ............................................................... 222 A Quick Tour of Files Used by imake ............................................ 223 Using imake to Build X11 ............................................................... 224 Porting Hints ...................................................................................... 226 Undefined Symbols or Functions .................................................... 226 Missing Header Files ................................................................... 226 Missing Function Definitions ......................................................... 226 Searching for Preprocessor Symbols ............................................. 228 Related Documentation ..................................................................... 230 8.1.2.1 X from Your OS Vendor 8.1.2.2 Some examples of vendor-supplied X11 are OpenWindows from Sun, DECWindows from DEC, and AIXWindows from IBM. X from your OS vendor is probably the easiest to install. In fact, you may not have to install it at all--more and more UNIX platforms are being shipped with the OS and software packages (such as X) already installed, so you might luck out and have everything in place when your system is delivered. You should be able to tell if X11 is pre-installed by looking in the directory/usr/bin/Xll or the directory that your vendor uses (typically /usr/openwin for OpenWindows,/usr/lpp/Xl I for AIXWindows, etc). If the directory is not empty, you probably have at least some portion of the software already in- stalled. Some systems have tools to tell you what software is installed. For example, setld -i on Ultrix and versions on IRIX. You could also try starting the window system with xinit (or openwin) to see what happens. If you need to install an X distribution provided by your OS vendor, the installation proce- dure for the X package should be similar to that of any other package that is bundled with the operating system. The X package installation should require whatever tool is normally used for installing software on that platform, i.e., setld for Ultrix, inst for IRIX, cdm or extract un- -- bundled for SunOS, etc. The vendor may break the X11 package into separate components: an "execution-only" package that allows you to run X servers and clients, and a "development" environment for compiling new X applications. The development environment includes the X libraries, header files and imake configuration files. (See Appendix E for more information on the com- ponents of the standard X distribution.) If you intend to write your own X programs or com- pile any of the public domain X applications available on the Internet, you should install a full development environment. See Appendix B for information on installing public domain software. Be aware that some vendors charge extra for the X 11 distribution, and others include it in the cost of the operating system. You should ask the salesperson about this before you order your software configuration. X from a Third Party There are several third-party vendors who provide pre-compiled X 11 distributions for some of the more popular platforms. Some vendors are listed in Appendix F and in the comp.win- dows.x Frequently Asked Questions list. Third-party X distributions are usually derived from recent MIT releases without adding much functionality. If you are up to the task of building X from the MIT source, you can probably duplicate a third-party distribution for your platform and save some money. How- ever, it may be easier to purchase a third-party X installation than try to figure out what patches, bug fixes, and work-arounds are necessary to build it on your platform. You might also be able to get invaluable technical support from a third-party vendor. Furthermore, building the MIT distribution is resource-intensive, consuming large amounts of disk space and CPU time. If these resources are in short supply, this may be reason enough to buy a pre-built X distribution. Building the X Window System 187 AT&T Unix System V Release 4 V2, on AT&T WGS6386 A/UX 2.0.1 HP-UX 7.0, on HP9000/s300 IRIX 4.0 Mach 2.5 Version 1.13, on OMRC Luna 88k NEWS-OS 3.3, on Sony NWS-1850 NEWS-OS 5.0U, on Sony NWS-37 I0 SunOS 4.1.i, on Sun 3, Sparc I, and Sparc 2 Ultrix-32 4.2, VAX and RISC UNICOS 5.1 UTek 4.0 VAX 4.3bsd (with unknown local changes) ..o If your platform is listed in the release notes, then you're probably in good shape. If not, you may still be in good shape: the X distribution is frequently ported to new platforms, with the binary distribution made publicly available. The best way to track the progress of the X dis- tribution on your platform is to watch the appropriate Usenet newsgroup, or post a query to either that newsgroup or to comp.windows.x.* Some examples of useful "ports" that appear outside of the official MIT distribution are the XNeXT distribution for NeXT workstations, the X386 server binary for 386-based UNIX machines, and patches for Sun Solaris 2.0. 8.1.4 Complete or Client-only Distribution? Before buying an X distribution or investing any time in building one from source, you still have a few more decisions to make. First, you need to decide whether you want a complete distribution or a client-only distribu- tion. A complete distribution includes a server, clients, libraries, header files, fonts and confi- guration files. A client-only distribution could include only the clients and, if necessary, shared libraries for dynamically linked executables. If you wanted to compile X programs, you would also need libraries and header files. Client-only installations make sense for hosts that don't have a bitmapped console display, such as a fileserver, compute server, or NFS server. The X clients are expected to display on remote X servers (for example, X terminals) across a network. Complete distributions make sense for workstations and for development environments. 8.1.5 Installing Multiple X Releases Next, you should consider whether you want more than one release of the MIT X 11 installed at one time. This would come in useful if you intend to test an X application under more than one X release. * comp.windows_x also has an e-mail address for those who cannot get news, xpert@expo.lcs.mit.edu. Building the X Window System 189 For example, you might want to have Sun OpenWindows, MIT R4, and MIT R5 distributions residing on your platform at the same time: you could do this so you can test clients under each environment. Each distribution can have its own directory hierarchy. As a example of this, OpenWindows could be installed under/usr/openwin, MIT X1 I R4 under/usr/X1 IR4, and MIT X 11 R5 under/usr/X11R5: Contents OpenWindows XllR4 XllR5 Binaries /usr/openwin/bin /usr/X11R4/bin Libraries /usr/openwin/lib /usr/X11R4/lib Headers /usr/openwin/include /usr/X1 lR4/include/Xl 1 /usr/X11R5/bin /usr/X11R5/lib /usr/X 11R5/include/X11 Another possibility is that you can run a server from one MIT release with the client distribu- tion from another. You might do this if you are installing a new version of X that doesn't sup- ply a server for your workstation console: you can continue to use the vendor supplied server with updated clients until an updated server is available for your display hardware. Mixing clients with a server from a different release may have unexpected results. For ex- ample, newer X servers have the SHAPE extension, which allows windows to be shapes other than rectangular. If you run the oclock client under a server without this extension, it would appear as a square instead of a circle, as shown in Figure 8-I. Figure 8-1. oclock without the SHAPE extension With the SHAPE extension, oclock appears as it should, as shown in Figure 8-2. Figure 8-2. oclock with the SHAPE extension 190 X Window System Administrator's Guide mi t l server l ddx/ cfb /REAEME mit Iserverlddx/x3861README mit Iserverlddx/x3 861c fb. bankedlREADME The cgthree is mentioned in mitlserverlddxlsunlREADME: Sunl2  cg21315 Sun/3 bw2 cg2/3/4/5 SPARCstation cg3/6 o.. From this information, you can determine that the Sun server supports the cgthree frame buf- fer that you have installed on your system. If your platform is supported and a server exists for your display hardware, then you're home free. 8.2.3 Applying OS Patches You should make sure your OS has the latest patches, as the MIT X distribution may rely on a patch being in place in order for it to work properly. This is especially true for security and compiler patches, as X relies on setuid programs and also tends to expose weaknesses in compilers during the build process. The mechanism for obtaining OS patches varies depending on the vendor, but it usually in- volves a support contract or calling for technical support. Some vendors make their OS patches available on the lnternet or from mail servers. 8.2.4 Applying X Patches Before continuing with the build, you should verify that you're using the latest version of the MIT source and have all official MIT "fixes," or patches, applied. Some patches may affect installation or close security holes, so it's always a good idea to install the latest patch. If you obtained the sources from a reputable location and they appear to be unmodified, try looking at the file mit/bug-report. There should be a line resembling: R5, patch-level-0 "patch-level-0" indicates that no official patches have yet been applied. The patch-level num- ber is incremented as each patch (or "fix") is applied. You should go back to wherever you obtained the MIT source for the available patches. If you got the source from export.lcs.mit.edu, the patches are in the/pub/R5/fixes directory. The contents of this directory are: fix-01 fix-05 fix-09 fix-13 sunGX.uu fix-02 fix-06 fix-10 fix-14 fix-03 fix-07 fix-ll fix-15 fix-04 fix-08 fix-12 fix-16 194 X Window System Administrator's Guide There are 16 patches available for R5 at the time of this writing.* The fixes are small enough to be sent through mail and are available through a mail archive server. See Section A.3 for information on getting a patch through the mail. Patches are applied using the patch program. If patch isn't already installed on your system, the source for this program is available in the mit/util/patch directory. The top of each patch file describes how to use the patch program to install the patch, for ex- ample: Release 5 Public Patch #i MIT X Consortium This patch comes in two parts: this file, and the file "sunGX.uu'. (If you obtained this patch via the xstuff mail daemon, and you do not have "sunGX.uu', get it with the request "send fixes sunGX. //". ) To apply this patch: cd to the top of the source tree (to the directory containing the "mit" and "contrib" subdirectories) and do: patch -p -s < ThisFile Patch will work silently unless an error occurs. You will likely get two warning messages, which can be ignored: mkdir: mit : File exists mkdir: mit/hardcopy: File exists If you want to watch patch do its thing, leave out the argument to patch. Next, from the same top-level directory do: uudecode sunGX, uu rm - f mit/server/ddx/sun/sunGX, o. dist uncompress mit/server/ddx/sun/sunGX, o. dist ... This example assumes you created a directory for patches called fixes in the mit/directory. Apply the first patch (fix-O1) simply by following directions: % is mit/fixes fix-01 fix-05 fix-09 fix-13 sunGX, uu fix-02 fix-06 fix-10 fix-14 fix-03 fix-07 fix-ll fix-15 fix-04 fix- 08 fix- 12 fix- 16 % patch -p -s < mit/fixes/fix-01 mkdir: mit: File exists mkdir: mit/hardcopy: File exists % uudecode mit/fixes/sunGX.uu % rm -f mit/server/ddx/sun/sunGX.o.dist % uncompress mit/server/ddx/sun/sunGX, o. dist (As mentioned in the instructions, the mkdir errors can be ignored.) *The sunGX.uu file is a replacement object file for the Sun GX graphics accelerator. The .uu extension indicates that it is a binary file that has been converted to ASCII text by the uuencode program. This makes it possible to send a bi- nary file through the mail. When the sunGX.uu file has been copied to your system, run the uudecode program on it to recreate the binary file. Building the X Window System 195 Make sure you follow the directions and pay careful attention to the ordering of the patches. When you have exhausted all the available patches, the "patch-level" number will be incre- mented to the number of the last patch. If you get an error message such as: reversed (or previously applied) patch detected! Assume -R? [y] then abort the patch program, as it is likely that you are applying the patches in the wrong or- der or are applying the same patch twice. Patches to contrib software are applied in a fashion similar to the core patches, but they are organized by specific packages. If you obtain them from the host export.lcs.mit.edu, they are in the directory/pub/R5/contrib-fires. 8.2.5 Creating a Link Tree (Optional) One method of managing the X source distribution is to create a "link tree" of the MIT source code. The directory structure is the same as the original MIT distribution, but the files in the directories are symbolic links back to the original files. If the X distribution is built within the link tree, the object files and libraries will reside in the copy, not in the original. Using link trees makes it possible to build any number of different sets of binaries from one set of source code files. This makes it very easy to maintain a group of binaries for different platforms. It also conserves disk space, as the symbolic links will take up less space than a copy of the source files. If you are going to build the distribution only once, however, you may not want to use a link tree, since it complicates the directory structure and uses up disk space when creating links. Link trees may be the only way to effectively use read-only copies of the X source, such as those mounted from a CD/ROM. For example, the source area could look like: % is -F mit/ rs_aix31/ sun3_411/ pmax_ul 42 / sgi _40 / sun4_411 / The rs_aix31, sun3_411, pmax_u142, sgi_40, and sun4_411 directories* are link trees that are linked back to the mit directory. MIT supplies a shell script called lndir that creates the tree for you. You can find lndir in the source distribution as mit/util/scripts/lndir.sh. *The example directory names are borrowed from AFS. They are intended to describe a platform and the version of the operating system. For example, sun4_4 ! 1 indicates a Sun4 running S unOS 4.1.1. 196 X Window System Administrator's Guide To build a link tree: 1. Install the lndir program: # cp mit/util/scripts/lndir.sh /usr/local/bin/lndir # rehash 2. Create a directory for the tree to reside in: # mkdir sun4_411 3. cd into the new directory: # cd sun4_ll 4. Run the lndir program, supplying the relative path of the original source tree: # lndir ../mit config: extensions: include: PEX: lib: xinput: o.. When Indir finishes, you will be left with a usable copy of the X source tree. 8.3 Simplest Case Build If you have confirmed that you have adequate disk space, have applied all the available patches, and are working on a supported platform, then you may be able to install the X core software quickly and painlessly. This example uses the Sun4 running SunOS 4.1. l, as it is one of the most trouble-free builds. If you want to build X using all default settings, change directories to the top of the distribu- tion (usually mit/) and type: % make World >& world, log If you would like to monitor the progress of the build, use the tail program on the log file: % tail -f world.log The build will probably take several hours on even the fastest machines. When the make is complete, check for errors; any build problems should be reported in the file worM.log.* Examine the file for the messages "not made because of" or "Error." You can the grep program to search for the ":", as it is commonly present in error messages: % grep ":" world.log Sun Jun 7 23:12:09 PUP 1992 * Be careful to search the entire file for errors, as it may still have the message "Full build of Release 5 of the X Win- dow System complete." at the end even if there were problems with the build. This is because the make World target invokes make with the -k option, telling it to ignore non-fatal errors. Building the X Window System 197 make: Fatal error: Ccranand failed for target "subdirMakefiles' make: Fatal error: Ccranand failed for target "Makefiles' make: Fatal error: Cortland failed for target "World' make: Fatal error: Cortland failed for target "World' If there are no errors, the next step is to install the distribution. In this example, we use the default installation pathnames--see Section 8.5.1.2 for information on how to change the de- fault pathnames. If you want to install X as an unprivileged user, you will need write permission to/usdlib, /usdbin,/usdinclude,/usdman/man3, and/usdman/mann. It is probably easier to install X as root instead of touching up permissions after the installation is completed. (The permis- sions for the installed files are very important to the security of the X distribution.) Become the superuser: % flu Password: Install the distribution:* # make install >& install.log Install the manual pages (if desired): # make install.man >& man.log If there are no errors at this point, X should be installed and usable. Any remaining adminis- tration work would involve customizing the installed files for your site. For example, you may want to configure the X Display Manager. If so, see Chapter 3 for more information. 8.4 Host Problems There are some problems that can disturb even the default X build. These problems have more to do with the host configuration than with the X installation itself; that is, problems with disk space, shared libraries, or NFS. 8.4.1 Disk Space There are several stages in the build process that can consume large amounts of disk space. Optimization options The -O flag to the C compiler turns on optimization and can generate very large temporary files. These files are usually written to/tmp. * Note that the install process will write to the source area in some cases. One example of this occurs when installing the xterm binary for the Sun platform, as the binary is re-linked to overcome a security problem with Sun shared li- braries. 198 X Window System Administrator's Guide 8.4.3 NFS Installation You may choose to install X on a filesystem that is NFS-mounted from another host. You'll have problems installing X if the NFS-mounted filesystem does not allow root access over the NFS link. For security reasons, it's a bad idea to allow remote root users to write to your filesystem, but you can add root access temporarily to allow you to build X. For root to be able to write to an NFS-mounted partition, you need an entry for the local sys- tem in the/etc/exports file on the remote system.* For example, to give temporary root per- mission for the/usr directory to the host named rock, you could change the following line in /etc/exports : /usr -access=rock to: /usr -root=rock, access=rock On systems with the newer version of NFS, run the exportfs command to make this take ef- fect: rubble# exportfs -v /usr re-exported /usr Back on the local host, the installation can proceed from this point as if it was taking place on a local filesystem. Build X on rock: % make world >& world.log When the installation is complete, the entry in/etc/exports should be changed back to what it was and then re-exported With the exportfs command: rubble# exI)ortfs -v /usr re-exported /usr 8.4.3.1 NFS Installation Without Root Access An alternative to giving temporary NFS root access to the remote directory is to install the distribution as an unprivileged user and change the ownership of the files later. The problem with this approach is that it opens the system to attack during the installation, so it should be avoided if possible. For this example, the ownership of the target directories is changed just long enough for the installation to take place. The permissions are then touched up as root. As in the previous example, the host that has the compiled X source on it is named rock and the host that NFS- mounts the rock partition is named rubble. * If you have an older version of NFS, the/etc/exports entries are simply the filesystem names followed by the hosts which have access. Changes to the file will have an immediate effect. This is in contrast to the current system, which uses the exporfs command to notify the system of changes in the/etc/exports file and supplies different levels of per- missions. Building the X Window System 201 Pas sword: TERM= (xterm) TERM= (unknown) You might also get error messages when you try using your favorite editor: % vi foo xterm: Unknown terminal type I don't know what kind of terminal you are on - all I have is 'xterm'. [Using open mode] "foo" [Read only] 3564 lines, 133099 characters :q., % emacs foo emacs: Terminal type xterm is not defined. You could use vtl02 as a temporary value until you are able to install the xterm entry. % setenv TERM vtl02 The terminal definition for systems using termcap can be installed simply by inserting the contents of the file called mit/clients/xterm/termcap into the/etc/termcap file on your system. It's a good idea to insert the termcap definition before any other definitions, since xterm is likely to be used frequently. The terminfo definition can be installed by using the terminfo compiler, tic. For example: # tic mit/clients/xterm/terminfo (Note that you must be root for this to succeed.) The terminfo definition is placed in/usr/lib/terminfo/x/xterm. See the Nutshell Handbook termcap and terminfo (O'Reilly & Associates, 1991) for more in- formation on the termcap and terminfo terminal databases. 8.5 Simple Configuration If you are not satisfied with the default configuration, you can change some simple configura- tion parameters, as described in this section. These parameters need to be configured before the build is begun. The files used to configure the X compilation and installation reside in the directory mit/con- fig. The syntax within these files should look familiar if you have used the C preprocessor (cpp) before. If you are not familiar with C preprocessor syntax, you should still be able to do the right thing by looking at other examples within the configuration files. Section 8.7 gives some more background on imake syntax; for most configurations, you can probably figure it out on your own. You need to modify two files that will affect the build process: site.def, which defines param- eters for your particular site, and a platform-specific file (e.g., sun.cf) which defines parame- ters for your particular platform. 204 X Window System Administrator's Guide InstallFSConfig The font server configuration files are not installed unless this flag is set to YES. St ripInstal i edPrograms Setting this flag to YES will strip binaries as they are installed. The usual reason for doing this is to save disk space: removing the symbol table from the binary will reduce its size. It will be difficult to debug any run-time problem if the pro- grams are stripped, but this is not a concern to most X users. HasXdmAuth This flag indicates that the XDMCP library should include DES code. DES, or Data Encryption Standard, is an encryption scheme used in the authorization process. There are restrictions on exporting DES outside the United States. This flag must be on if you want to use the XDM-AUTHORIZATION-1 method of server access control. See Section 4.3 for more information. ExpandManNames Some operating systems have restrictions on filename length. To deal with this problem, the manual pages for X library functions have their names shortened to 14 characters. If your operating system does not have this problem, the manual page filename can be expanded to its full name (for example, XTranWCo.3 is ex- panded to XTranslateCoordinates.3). HasLargeTmp This flag indicates that you have enough disk space in Crap for the ar command to create its temporary file. Setting this parameter to NO instructs ar to use the current directory. Instal ILibManPages - There are two sections of manpages: client manpages and library function man- pages. If this flag is set to NO, it prevents the library manual pages from being installed with the make install.man command. This flag is set to YES by default. You might set it to NO if no one at your site intends to program in X and if disk space is low. (The library manpages consume approximately 2 megabytes of disk space.) 8.5.1.2 The ProjectRoot Flag The Proj ectRoot flag defines the "root" directory for the build. It is not used in the ex- ample site.def file, but can be easily enabled by removing the C comments surrounding this section: #ifdef Proj ectRoot #undef Proj ectRoot #endif #define ProjectRoot /usr/XllR5 If Proj ectRoot is already defined, it is first undefined. (The reason for this test is that some of the platform.cf files define Proj ectRoot by default. The C preprocessor will complain if a flag is defined twice.) Building the X Window System 207 OSTeenyVersion A more precise version number for patch releases of the OS BuildServer This flag controls whether the server should be built along with the rest of the X distribution. It is set to YES if the server exists; if a server doesn't exist for your platform, it is set to NO. You can also set it to NO if you don't want to build a server for some reason--for example, for the IBM RS/6000, the MIT server runs only on the SLsway display adaptor. If you do not have this particular board, you should set the BuildServer flag to NO. Server Options Look for any server specific options. This could include monochrome and color versions, as in: #define XmfblmnaxServer NO #define XcfblmnaxServer YES 8.5.2 Configuration Example 1 For this example, a Sun with limited available space in Crap is being used. The -temp= flag is needed to specify an alternate directory for the temporary files from the compiler. See Sec- tion 8.4.1.2 for more information on the -temp= flag. The -temp= flag needs to be supplied on every cc command line used in the X build. This means that it needs to make it into every Makefile used in the X distribution. You can accom- plish this by editing the DefaultCCOptions parameter in the sun.cf file. (Being a very system-specific flag, this parameter is specified in the platform.cffile, not in the site.deffile.) The README file in the rnit/config/directory describes all of the configuration parameters, including De faul tCCOpt ions: DefaultCCOptions default special C compiler options In sun.el, De faul tCCOpt ions is currently specified with the following lines: #ifdef mc68000 #define DefaultCCOptions -f68881 -pipe #else #define DefaultCCOptions -pipe #endif (The test for mc68000 is to add the flag for the mc68881 floating-point chip, available only on the sun3 platform.) If you enough space in the area where you are building X, set the -ternp= flag to the current directory ("."). The C compiler will then use whatever directory it is invoked in for tempo- rary files: #ifdef mc68000 #define DefaultCCOptions -f68881 -pipe -temp=. #else #define DefaultCCOptions -pipe -temp=. #endif 210 X Window System Administrator's Guide 8.5.7.1 xterm Build Flags mit/clients/xterm/lmakefile contains the following comment: /* * add -DWTMP and -DLASTLOG if you want them; make sure that bcopy can * handle overlapping copies before using it. */ You may want to enable these flags if you want users who log into the system using xterm to be recorded in the wtmp file. They will then appear when the last command is used. Change the following line in mit/clients/xterm/lmakefile from: MISC__DEFINES = /* -DALLOWLOGFILEEXEC * / to: MISC__DEFINES = /* -DALLOWLOGFILEEXEC */ -DWTMP -DLASTI/3G 8.6 Building Programs After X Is Installed If you have people at your site who are going to be programming with X, you should supply them with the proper tools to do this. This usually means installing the libraries, header files, and configuration files in a public area in the same manner as other programming environ- ments. Even if you choose non-standard locations for the X distribution, the imake program provides tools programmers can use without worrying about the location of the installed soft- ware. Appendix B shows how to compile an X program after X is already installed. 8.6.1 xmkmf The xmkmfprogram is a shell script front end to the imake program, supplied in X11R4 and X1 IR5. (See Section 8.7 for more information on imake itself.) It can be run in any directory than contains an Imakefile. This could be within a subdirectory of the X distribution source code or a program outside of it: % xmkmf mv Makefile Makefile.bak imake -DUseInstalled - I/usr/lib/Xll/config It first makes a backup copy of any existing Makefile, as it will create a new one with the same name. It then invokes imake with the Usernstal 1 ed flag, which tells imake that the X distribution is installed and that it should use the header files and libraries on the system instead of expecting ones to be present in the X source tree. For example, in config/Proj- ect.tmph #ifdef UseInstalled #define PhigsInclude -I$(INCDIR) #else 214 X Window System Administrator's Guide #define PhigsInclude -IS (BUILDCDIR) #endif This sequence means "use the system include file area if UseInstalled is defined, other- wise use the include files in the source code for PHIGS." If you set Proj ectRoot before the build, xmkmf will use the new root directory. For ex- ample, if you set Proj ectRoot in site.de/before installation: #ifdef Proj ectRoot #unde f Proj ectRoot #endif #define ProjectRoot /usr/XllR5 Running xmkmf would produce: mv Makefile Makefile.bak imake -DUseInstal led - I/usr/Xl IR5 / lib/Xl i/config xmkmf uses the -/flag to tell cpp where to look for include files. The include files in this case are the imake configuration files. The default location for installing these files is /usr/lib/X11/config. If you have your own private set of configuration files, you can invoke imake with a different include directory: % imake -DUseInstalled -I/home/eap/myconfig In R5, xmkmf also takes an -a flag, which executes the normal make targets automatically: % xmkmf -a mv Makefile Makefile.bak imake -DUseInstal led - I/usr/lib/Xl I/config make Makefiles make includes make depend The Make f i l es target will recursively build any Makefiles that may be present in subdirec- tories. The includes and depend targets are used to build a list of dependencies that are ap- pended to the Makefile. These will force recompilation of the target if something related to the program changes elsewhere. 8.6.2 Include Files Include or "header" files should be found automatically by the preprocessor, as they are stored in standard system directories, such as/usr/include. Note that MIT supplied header files will have the Xll directory already prepended to the name of the include file: #include oo. or even a subdirectory within X11: #include ... Building the X Window System 215 cpp will interpret the complete path, for example, as /usr/include/X11/Xaw/Box.h. If you wish to bury the include files in another subdirectory, you will still need to have the last di- rectory named Xll, as in /usr/XllR5/include/Xll. cpp would then be invoked with -I/usr/X11R5/include. You could also cheat and create a symbolic link from Xll to the in- clude file directory: # in -s Xll . This would keep cpp happy when it looks for the files. It is often desirable to keep the MIT headers separate from the system headers, as this will keep them from being damaged during OS upgrades. 8.6.3 Libraries The X libraries will usually be installed in/usr/lib, but there are several reasons to install them in an alternate location. In any case, the Makefiles generated by imake should do the right thing if you configured the X distribution this way. Alternate library locations can be specified with the -L option. If you have Proj ect:loot: set to/usr/XllR5, the X libraries will be in/usr/X11R5/lib. 8.7 More About imake This section describes the configuration process in more detail and may help if you encoun- tered a problem with your X build. imake is a project management tool that is used for building the X Window System from source code. This section describes imake in the context of building X 1 1, but imake can be used for any large project that is going to be compiled on more than one type of platform. In particular, it is the tool of choice for public domain X programs that are distributed in source form. See Appendix B for more information on compiling public domain software. imake uses a combination of make and the C preprocessor (cpp). A basic understanding of each is required to intelligently configure the X build process. 8.7.1 The make Program The make program is the default UNIX tool for maintaining source code. It uses a configura- tion file called Makefile to describe each component of the source distribution, how each should be compiled, and how individual files relate to one another. It saves time and effort by automating common programming tasks. For example, if a header file has been modified, any program that uses it is recompiled, ensuring that everything is up to date.* * See the Nutshell Handbook Managing Projects with make (O'Reilly & Associates, 1991) for more information on the make program. 216 X Window System Administrator's Guide 8.7.3.3 Concatenating Macros A common trick is to use the null comments "/**/" to concatenate macros or strings within cpp. For example, if you had a file called testfile containing the following: #define MYTOPDIR /usr/ #define XLIBDIR lib/Xll/ #define FONTDIR fonts/ You may want to concatenate these strings into one. If you try concatenating them directly, such as: MYTOPDIRXLIBDIRFONTDIR cpp will respond by trying to expand the entire string. Since the string is not defined, it will return the string itself, which is hardly what you want. % cpp testfile # 1 "testfile" MYTOPDIRXLIBDIRFONTDIR You can get around this with some versions of cpp by separating each component with null comments. The comments prevent the components from being interpreted as a single string. For example: MYTOPDIR/**/XLIBDIR/**/FONTDIR With the comments inserted, passing testfile through some versions of cpp yields: % cpp testfile # 1 "testfile" /usr/lib/Xl i / fonts / This works great. But the problem with this trick is that ANSI C preprocessors have a differ- ent and incompatible syntax for concatenation. Under an ANSI C preprocessor, the preceding example fails to concatenate. The null comments are expanded into white space, which is di- sastrous in this example: % acpp testfile # 1 "testfile" /usr/ lib/Xll/ fonts/ ANSI C uses the "##" sequence for concatenation. For example: MYTOPDIR# #XLIBDIR# #FONTDIR Running this through an ANSI C preprocessor yields the correct value: % acpp testfile # 1 "testfile" /usr/lib/Xll/fonts/ Building the X Window System 221 To concatenate macros within imake, imake provides the Concat and Concat3 macros which do the right thing depending on what type of preprocessor you use. In this case, since we have 3 arguments, we use Concat3: Concat3 (MYTOPDIR, XLIBDIR, FONTDIR) 8.7.3.4 Dealing with Tabs In some versions of cpp, tabs are converted to space characters. The make program, mean- while, requires tab characters to precede the commands in a make rule. So if a version of cpp that converts tabs to spaces is used on a Makefile, make will bomb out with an error such as: % make make: Fatal error in reader: Makefile, line nn: Unexpected end of line seen The imake program therefore tries to intelligently place the tab characters back in the Makefile after being processed by cpp. If the version of cpp that comes with your system is unsuitable for building the X distribution, the contrib area provides a replacement in con- trib/util/cpp. 8.7.4 imake Configuration Files imake uses a series of configuration files when creating Makefiles for a particular package. First, it uses a series of system-wide imake configuration files, found in the directory /usr/lib/Xll/config. In addition, imake looks for a file named lmakefile in the directory it is being invoked in, which defines parameters specific to that particular package. This discussion will be much easier to follow if you have these files online and available to browse through while reading. If you have the X distribution source code available, look in the directory mit/config. If the distribution is already installed, look in the directory /usr/ lib/X l l / config . This looks very complex--it is. However, you should be relieved to know that any changes you make are confined to one file (unless you need to do something more complex, such as add support for a new platform). The filenames indicate the function of the file in a general manner. Files ending in .tmpl are template files. They are like templates in that they provide a structure that is "generic" and later customized to a specific result. Files ending in .cfare configuration files, used to config- ure imake for a specific platform. Files ending in .rules contain make rules that describe how make should build programs and what files depend on the others. One convention to keep in mind while browsing the files is that cpp macros are mixed-case (for example, InstallAppDefaults), and make flags are uppercase (for example, INSTKMEMFLAGS). 222 X Window System Administrator's Guide 8.7.5 Using imake to Build Xll You rarely ever need to run the imake program directly. It is usually run by the Makefile at the top level of the X 11 source tree when the make command is used. The usual thing to do when building X is to type: % make World If this fails with an error message such as: ooo *** Error code 1 make: Fatal error: C(mmand failed for target "subdirMakefiles' CALrrent working directory /eap/XllR5/src/sun4_412 *** Error code 1 make: Fatal error: Conmnd failed for target "Makefiles" CALrrent working directory /eap/XllR5/src/sun4_412 *** Error code 1 make: Fatal error: Co.and failed for target "World' CALrrent working directory /eap/XllR5/src/sun4_412 *** Error code 1 make: Fatal error: Conmnd failed for target "World' You will have to figure out what went wrong and correct it. After you have done this, you may be able to save some time by using a target other than WorM. A target is a specific task within a Makefile. The top-level Makefile has several targets: Makefiles clean includes depend This target creates a Makefile in any subdirectory that contains an Imakefile. You should run this anytime you change a configuration option. This target "cleans" or removes all the object files and libraries from the source tree. You should use this if you fail miserably and want to start over again. This target creates symbolic links from the current directory to where the include files are stored in the source tree. It should be used before the depend target. This target generates dependency information for make. A program called makedepend is invoked, which searches all the source files for #include statements and builds a list that is appended to the Makefile. For example: World ..o Tekproc. o: /usr/include/fcntl .h /usr/include/sys/fcntlccm.h Tekproc. o: /usr/include/sys/stat.h /usr/include/unistd.h Tekproc. o: /usr/include/sys/time.h /usr/include/sys/time.h Tekproc. o: ../.././Xll/Xatcn.h ../.././Xll/cursorfont .h Tekproc. o: ../.././Xll/StringDefs .h ../.././Xll/Shell .h Tekproc. o: ../.././Xll/Xmu/CharSet .h /usr/include/stdio.h This should be run every time a Makefile is rebuilt. This is the primary target for building the distribution. It runs make with the following targets: Makefiles, clean, include, depend and then with just with the -k option. (Keep in mind that -k tells make to keep running even 224 X Window System Administrator's Guide 8.8.2 Searching for Preprocessor Symbols An important feature of cpp is that it can tell other programs what type of platform it is being executed on. cpp provides pre-defined symbols indicating the platform, operating system, byte order, processor type, and type of C compiler. Some of these symbols are shown in the following table. Table 8-1. cpp Symbols Symbol Type Architecture OS Byte Order Type Compiler Examples mc68k, i386, i8086, iAPX286, sparc unix, DGUX, M_XENIX, UTS, ultrix, venix, xenix MIPSEB, MIPSEL sun3, sun4, sun386, nsl6000, ns32000, mips _POSIX_SOURCE, ANSI, __STDC .... ANSI C SOURCE, _NO_PROTO imake uses these symbols to automatically determine what type of platform it is being run on.* So one of the first tasks of porting X to a new platform is to find a unique preprocessor symbol so that imake can determine the type of platform. On some systems the BOOTSTRAPCFLAGS flag will have to be used for this function, but it's worth checking first. The following are hints about where to check: The manual pages for the preprocessor and the compiler are the first places you should check. Beware that the names of the compiler programs vary. For example, the C com- piler on the IBM RS/6000 is called xlc. There may be several different versions of the compiler available, each with its own behavior. It is not unusual to have an ANSI C and "K&R" C compiler on the same system. There may be more than one version of cpp as well--for example, IRIX has both cpp and acpp. Not surprisingly, some vendors do not list all the predefined flags and you will have to hunt for them. 2. See if the compiler or preprocessor has a "verbose" flag, usually -v or -verbose. This flag shows which flags are being passed to the preprocessor (where they are interpreted): % cc -v -E foo.c > /dev/null /lib/cpp -undef -Dunix -Dsun -Dsparc foo. c From this, you can determine that the flags unix, sun, and sparc are defined by the preprocessor. The -E flag means "run the preprocessor only," and the output of the preprocessor is discarded into/dev/null. * Some systems have no unique preprocessor symbols, requiring you to tell imake the type of platform when it is first invoked. 228 X Window System Administrator's Guide 3. If the previous methods fail, it may require a low-tech approach. In most cases, this means the strings program. The strings program reports all printable strings in a binary file: % strings /lib/cpp oo . too many -I options, ignoring %s cpp internal bug alert, readinit(argv0), argv0=NULL %s. init unix m68k _SYSV_SOURCE _BSD_SOURCE _AUX_SOURCE /usr/include /usr/include %s : %s ... Experience would tell you that the strings clustered around unix are likely suspects for preprocessor symbols. You can test them by running them through the preprocessor and checking to see if they are defined. First, enter into a file the symbols you wish to test: % cat > foo.c unix m68k _SYSV_SOURCE _BSD_SOURCE _AUX_SOURCE /usr/include Then run the preprocessor on them: % cc -E foo.c # 1 "foo.c" 1 1 1 1 1 /usr/include Any symbol that evaluated to "1" is being defined by the preprocessor. The "/usr/in- clude'" is unchanged, showing that it does not mean anything special to the compiler. (The line starting with the "#" character is a line number inserted by the preprocessor showing its position in the C source file.) Beware that symbols may not be unique to a platform and BOOTSTRAPCFLAGS may have to be specified after all. For example, both Sequent and Encore define ns32000 on their machines. You would have to specify a unique symbol on the command line for the initial make: % make World BOOTSTRAPCFLAGS=" -Dumax" Building the X Window System 229 A Useful Things to Know This appendix covers "miscellaneous" topics that either didn't fit cleanly into any other chapter, or fit into so many that we found ourselves repeating our- selves all the time. In This Appendix" The comp.windows.x Newsgroup ....................................................... 233 How to ftp a File .................................................................................. 234 Getting Files Using ftpmail ............................................................. 235 BITFTP ........................................................................................... 237 The xstuff Mail Archive Server ........................................................... 237 Unpacking Files ................................................................................. 238 Making a Filesystern Available via NFS .............................................. 239 How to Add a Host ............................................................................. 239 Adding a Host to/etc/hosts ............................................................ 239 Adding a Host Using NIS ............................................................... 240 Adding a Host Using DNS .............................................................. 240 Adding an Ethernet Address .............................................................. 242 Printing Documentation in the MIT X Distribution ............................... 242 Converting a Number Into Hexadecimal and Back ............................. 243 Configuring a Sun as an X terminal .................................................... 243 Using More than One Frame Buffer Under SunOS ............................. 244 A Useful Things to Know As we wrote this book. we found that there were a lot of odds-and-ends that didn't fit into any chapters but were too important to leave out. This appendix was devised as a "catch-all" for miscellaneous information. A.1 The comp.windows.x Newsgroup comp.windows.x is a Usenet newsgroup dedicated to the X Window System. You can use it reach thousands of X programmers and users. You would normally use a newsreader such as rn, vn, xrn, or readnews to read the group. If you do not have Usenet access at your site, you can still reach the newsgroup through e-mail. To request that you be added to the list. send a polite message to .qert-requestexpo.lcs.mit.edu. To send mail to the entire list. use xpert expo. lcs.mit, edu. In addition to com/.wi/ttows.A-, there are also newsgroups for comp.windows...motif, comp.windows.x.intrinsics, comp.windows.x.apps, and comp.windows.openlook. Each of these newsgroups maintains a Frequently Asked Questions list. or FAQ, which contain a wealth of intbrmation on X. comp.windows.x.announce is a newsgroup dedicated to announcements about X, for example, announcements of new patches being released. For more information on Usenet, see Managing UUCP and Usenet by Tim O'Reilly and Grace Todino (O'Reilly & Associates, Inc., 1992), Using UUCP and Usenet by Grace Todino and Dale Dougherty (O'Reilly & Associates, Inc., 1991), and The Whole lnternet User's Guide & Catalog by Ed Krol (O'Reilly & Associates, Inc., 1992). Useful Thngs to Know 233 ftp> binary 200 Type set to I. ftp> get FAQ.Z 200 PORT cd successful. 150 Opening BINARY mode data connection for FAQ.Z (84245 bytes). 226 Transfer complete. local : FAQ. Z remote: FAQ. Z 84730 bytes received in 16.87 seconds (4.91 Kbytes/s) ftp> The file should now be in whatever directory you ran ftp from. Note that if you had another file in this director), called FAQ.Z, it would be overwritten even if you had the csh noclobber variable set. For getting multiple files, use the mget command. (Use the prompt command first to toggle being asked to confirm each file transfer.) If you are done with yourftp session, use the quit command to exitftp. ftp> quit 221 Goodbye. imui@opal% A.2.1 Getting Files Using ftpmail ftpmail is a mail server available to anyone who can send and receive electronic mail to and from Internet sites. This includes most workstations that have an e-mail connection to the outside world, and CompuServe users. You do not need to be directly on the Internet to use ftpmail. Send mail to the ftpmail server, ftpmail@decwrl.dec.com. There are a set of commands that the server understands; to get a complete help file, send a message with no subject and the single word "hel p" in the body. The following is an example mail session that will get you the comp.windows.x FAQ. imuiOruby 145% mail ftpmail@decwrl.dec.com Subj ect : reply imui@ora.com connect export.lcs.mit.edu chdir /contrib binary uuencode get FAQ.Z quit imui@ruby 146% The reply line is specified to ensure that the correct return address is used. Without this line, ftpmail will mail the file to whatever return address is in your mail header, which may be wrong. The connect line is required to tell ftpmail what host to connect to. In this case, we set it to export.lcs.mit.edu. By default, ftpmail logs in as anonymous; you could actually supply a user name and password here if you had an account on the machine in question. Useful Things to Know 235 As an example, if you sent mail with the subject line "send fixes 1", it will respond with "fix-l": From: Xstuff service Subject: fixes/l In-Reply-To: Request from eap@ora.com (eric pearce) dated Tue Aug 25 13 : 00: 01 EDT 1992 To: eap@ora.com (eric pearce) Release 5 Public Patch #i MIT X Consortium This patch comes in two parts: this file, and the file "sunGX.uu". ..o The mail message can then be applied to the patch program to patch the X11 source distribu- tion. See Section 8.2.4 for a description of applying X11 patches. Try using the subject "index" to get a listing of available files. A.4 Unpacking Files The extension on the end of the file usually indicates what programs should be used for unpacking a file. For .Z files: % uncompress filename. Z For .tar.Z files: % zcat filename.tar. Z I tar xpvf - For files that look like this (might have .uu extension): begin 444 mit/server/ddx/sun/sunGX.o.dist. Z M'YV0 085. 0!5T!0F@*@@ 0D$#8!@RI( H(85.XWX!PW<"%!5X!D! J, 0 ... Run uudecode: % uudecode filename This will create the file mit/server/ddx/sun/sunOX.o.dist.Z. 238 X Window System Administrator's Guide A.5 Making a Filesystem Available via NFS For a host to be able to mount a remote filesystem, it will have to have an entry in the /etc/exports file on the remote system. The format of this file has changed as NFS has gained new functionality. The "old" style of entry in/etc/eaports is simply the name of the filesys- tern and list of hosts that can mount it: /usr/lib/Xll/fonts ncdl ncd2 ncd3 ncd4 The file is consulted every time a request is made to mount a filesystem. The "new" style of entry has a different syntax with many more options. For example, the above example would be written as: /usr/lib/Xll/fonts -access=ncdl :ncd2 :ncd3 :ncd4 Under "newer" NFS, you have to execute the exportfs command after the/etc/exports file is edited in order for the changes to take effect: % exportfs -v /usr/lib/Xll/fonts exported /usr/lib/Xll/fonts To remove access to a filesystem, edit the file and run the exportfs command with the -u option: % exportfs -v -u /usr/lib/Xll/fonts unexported /usr/lib/Xll/fonts For more information, see Managing NFS and NIS by Hal Stern (O'Reilly & Associates, 1991). A.6 How to Add a Host A common administration task is to add a new host name to the/etc/hosts file, the Network Information Service (NIS), or the Domain Name Service (DNS). The procedure for each of these is described here, but they will not be adequate for more complicated configurations. NIS is described in detail in Managing NIS and NFS by Hal Stern (O'Reilly & Associates, 1991). DNS is described in DNS and BIND by Paul Albitz and Cricket Liu (O'Reilly & Associates, 1992). All these examples assume a pre-existing, working configuration. A.6.1 Adding a Host to/etc/hosts If you are not using NIS or DNS, the new host can be added directly to the file/etc/hosts, with the IP address followed by the hostname and any aliases that the host is going to be known by: 140.186.65.13 ncd4.ora.comncd4 Useful Things to Know 239 A.6.2 Adding a Host Using NIS If you are using NIS (previously known as Yellow Pages), you first have to determine which host is the NIS master. This is usually the hostname retumed by the ypwhich command: % ypwhich (This not always the case, as NIS slave servers will also respond.) Once you have located the master, add the new host entry to its /etc/hosts file as shown above, and remake the NIS map: # vi /etc/hosts add hostname # cd /var/yp # make updated hosts pushed hosts You should test the map to make sure it has the new entry (in some cases, it may take a while to propagate the new map to all hosts within an NIS domain): % ypmatch ruby hosts 140.186.65.13 ncd4. ora. ccm ncd4 If there is a problem, you will get the error: Can't match key ncd4 in map hosts.byrkan. Reason: no such key in map. A.6.3 Adding a Host Using DNS For networks using DNS, you need to edit the configuration files for the name daemon named, named looks at a boot file at startup, usually/etc/named.boot. On our name server, this file contains the lines: directory /vat/named ; type domain source host/file backup file primary ora. corn . ora. zone primary 65.186.140. in-addr, arpa ora. revzone The/var/named directory is where the configuration files live. The file/var/named/ora.zone is the primary configuration file for the ora.com domain--this is the file that tells named how to convert hostnames to the proper IP address. The file/var/named/ora.revzone contains the reverse entries--i.e., it tells named how to convert IP addresses to the proper hostnames within ora.com. Note that your site will undoubtedly use different pathnames. To add ncd4 as address 140. 186.65.13, we enter into/var/named/ora.zone: ncd4 IN A 140.186.65.13 IN HINFO NCD-16 2.2.0 (The HINFO line contains host information--in this case, the version of the X server.) 240 X Window System Administrator's Guide A.7 Adding an Ethernet Address When you want to boot an X terminal or diskless workstation off a server machine, you will usually have to add its Ethernet address to the ethers database. Add the entry to the /etc/ethers file: 00 : 00 :a7 : i0 : ii :bf ncd4 The letters within the hex number should be in lowercase. If you run NIS, you will also have to remake the ethers map on the NIS master: # cd /var/yp # make updated ethers pushed hosts A.8 Printing Documentation in the MIT X Distribution If you have a PostScript printer, you can print out the MIT documentation in mit/hardcopy/. Any file with the .PS extension should print on BSD-based UNIX machines with: % ipr filename.PS or (on System-V based machines): $ip filename.PS Any filename with a .Z extension is compressed. You should uncompress it before trying to print it: % uncompress filename. PS. Z % ipr filename.PS or" % zcat filename.PS.Z  ipr If you do not have PostScript or if you just want to look at the document on your screen, you should use the files in the mit/doc/directory. If the file has .ms extension, this indicates that it uses the ms macro package for nroff and troff: % nroff -ms mit/doc/Xmu/Xmu.ms I more If the file has a .man extension, it is meant to be installed so it can be used with the man com- mand, but you can view it independently with: % nroff -man mit/clients/xterm/xterm.man I more If the file has a .tbl extension, run it through the tbl preprocessor and then through col after passing it through nroff: % tbl mit/doc/Server/gdz.tbl.ms I nroff-ms I col I more 242 X Window System Administrator's Guide There is no reason why you could not do this with other hardware. The 3/50 is singled out only because it is considered to be underpowered by today's standards. A.11 Using More than One Frame Buffer Under SunOS The MIT X server for the Sun platform can support more than one frame buffer at a time. It is possible to have two separate monitors on the same host or to use separate frame buffers within the same monitor. The cgfour frame buffer has an 8 bit color device and 1 bit mono- chrome device. The Xsun X server will not use both unless you modify the default worksta- tion configuration. 1. Become root and change directories to/dev: % au # cd /dev 2. Remove the default monochrome device: # rm /dev/bwtwoO 3. Create the new monochrome device: # MAKEDEV bwtwol 4. Make sure the kernel contains the bwtwol device and it is not commented-out. For example, on a Sun 3/60 with a kernel named "HARRY": # grep bwtwol /usr/sys/sun3/conf/HARRY device xtl at ohem 7 csr Oxff300000 priority 4# 3/60 device htwol at ohtnea 7 csr Oxff400000# 3/60 If the device is missing, add it to the kernel config file and build a new kernel. If this procedure works, you should be able to toggle back and forth between the frame buf- fers just by moving the mouse pointer to the edge of the display. Some systems can support more than one physical monitor. The Sun color IPC comes with a monochrome frame buffer built onto the CPU board and a cgthree card in one of the Sbus slots. If you connect a monochrome monitor to a CPU and a color monitor to the cgthree device, you can run the X server on both. Moving the mouse pointer to edge of the screen will move it onto the adjacent monitor. 244 X Window System Administrator's Guide B Compiling Public Domain Software Public domain software for X is available all over the Internet, but you may not think you have the right programming skills, or no one ever explicitly told you what to do. This appendix is a tutorial on how to find and compile public domain software. In This Appendix: Finding the Sources ........................................................................... 247 Using an Archie Server .................................................................. 248 Get the FAQ .................................................................................. 250 The Usual Suspects ....................................................................... 250 An Example: xarchie .......................................................................... 251 Getting the xarchie Sources ........................................................... 251 Untarring the Sources .................................................................... 252 Editing the Imakefile ...................................................................... 254 Compiling the Source ..................................................................... 255 Using Patches ................................................................................... 259 Another Example: xkeycaps ............................................................... 264 Related Documentation ..................................................................... 268 B Compiling Public Domain Software You've probably seen this sort of talk over the newsgroups: "Does anyone know where I can get xtetris? .... Is there an ftp site for xpostit?" You know that one of the best things about X is that there's all this great public domain software available, but you're not sure how to go about getting it. Either you don't know how toftp the sources, or you don't know how to use imake or make, or you aren't much of a C programmer so the whole idea of dealing with the source just scares you. Well, the good news is that for most source distributions, you don't need to know very much about make or imake, and you don't really need to know much about programming in C--mostly all you need to know is how to follow directions. This appendix gives you some idea of how to compile sources without knowing a lot about what you're doing. If you've been installing X from source or if you're a competent (and confident) C programmer in your own right, then you already know all the material in this appendix and it isn't for you. But if you're one of these people who's Scared of the Source, then this appendix may help. Don't expect to learn much about make or imake in this appendix, just enough to get through some of the simpler builds. If you're interested only in how to compile the X ll sources themselves, see Chapter 8. But if you already have X 11 installed and you just want to install new software, read on. B.1 Finding the Sources There are a lot of ways to find out about a program. You might see a reference to it on a newsgroup, or you might see it running on someone else's machine, or you might have read about it in this book. Let's suppose you saw a posting on the net about the xrolodex client: From: hrp@world, std.com Newsgroups: ccp. windows .x. apps Subj ect : xrolodex Hey, Has anyone seen the new xrolodex app? How is it related to xrolo? -Ross Compiling Public Domain Software 24 7 When you read this message, you are intrigued by the possibilities of a rolodex program, and you wonder whether it's available at no cost. B.1.1 Using an Archie Server The first thing to try is to use an Archie server. Archie is a robust database of anonymousftp sites and their contents. If you have Internet access, the most direct way to gain access to archie is to telnet directly to one of the Archie servers. Current Archie servers are listed in Table B- I. Table B-1. Archie Servers as of January 3, 1992 Site archie.mcgill.ca archie.sura.net archie.ans.net archie.unl.edu archie.rutgers.edu archie funet.fi archie.au archie.doc.ic.ac.uk cs.huji.ac.il IP Address 132.206.2.3 128.167.254.179 147.225.1.2 129.93.1.14 128.6.18.15 128.214.6.100 139.130.4.6 146.169.11.3 132.65.6.5 Location McGill University, Montreal, Canada SURAnet, College Park, Maryland, USA ANS, New York, USA Lincoln, Nebraska, USA Piscataway, New Jersey, USA FUnet, Helsinki, Finland Deakin University, Geelong, Australia Imperial College, London, UK Hebrew University, Jerusalem, Israel In our case, since Archie was written by the Archive Group at McGill University, it seemed fitting to use the one at McGill. In reality, you should use the server closest to you, since the McGill machine is generally overloaded with requests. You should generally use a front-end Archie client program to access an Archie server, such as archie or xarchie (we show how to build xarchie later in this chapter, in Section B.2). But you can also connect to Archie directly using telnet. imuiOopal% telnet archie.mcgill, ca Trying 132.206.2.3 ... Connected to quiche, cs .McGill. CA. Escape character is '^]' SunOS UNIX (quiche.CS.McGill.CA) login: Log on as archie. (There is no password.) login: archie ARCHIE: The McGill School of Computer Science Archive Server [2 Apr 1992] .o. Use the 'servers' conmand to list all archie servers. A limit of i0 concurrent telnet sessions has been put on archie.mcgill.ca. 248 The X Window System Administrator's Guide Alternative access through the standalone clients available via anonymous ftp to this machine. See REAEb file in -archie/clients. ** 'help' for help ** corrections/additions to archie-admin@archie.mcgill.ca ** bug reports, comments etc. to archie-l@archie.mcgill.ca archie> For a full listing of commands, type help. As an example of how to use archie to find a program called xrolodex, type: archie> prog xrolodex The first thing Archie does is find how many matches to xrolodex there are in the database. It keeps you updated on how many matches it's found so far, and how far it's gotten in its search. # matches / % database searched: 1 / 78% When it is 100% through the database, the list of sites that have xrolodex will stream to your terminal. For the purposes of this example, we have deliberately chosen a recently- announced program that has not made it to many sites yet (at least, not at the time of this example). If we had searched for something like xpostit, many screenfuls of output would have been reported. archie> prog xrolodex # matches / % database searched: 4 / 100% Host think, corn (131.239.2.1) Last updated 05:54 25 Feb 1992 Location: /think FILE rw-rw-r-- 53208 Dec 4 1990 xrolodex.shar.Z Host citi .umich. edu (141.211.128.16) Last updated 16:05 9 Apr 1992 Locat ion: /afs/alw. nih. gov/dcrt/brunetti/Oldfiles DIRECTORY rwxrwxrwx 2048 Apr 1 i0 : 16 xrolodex Location: /afs/alw. nih. gov/dcrt/brunetti DIRECTORY rwx_rwxrwx 2048 Apr 1 10:16 xrolodex Host plaza, aarnet, edu. au (139.130.4.6) Last updated 05:54 27 Apr 1992 Location: /Xll/contrib FILE r--r--r-- 103267 Apr 24 02:28 xrolodex.tar.Z archie> In this example, the pattern used for the prog command is assumed to be an exact match to the name of the program we want. You can specify different ways of searching using the set search command. For example: archie> set search sub archie> prog rolo will force a search of all items in the database with "rolo" as a substring. Compiling Public Domain Software 249 Rather than using telnet to directly contact an Archie server, there are programs available to automate the search. See Section B.2 for information on obtaining and compiling xarchie, which provides an X I 1 interface to accessing an Archie server. If you don't have Internet access at all, you can use the e-mail interface by sending mail to archie@host, where host is one of the machines listed in Table B- I. See The Whole lnternet User's Guide & Catalog by Ed Krol (O'Reilly & Associates, 1992) for more information. B.1.2 Get the FAQ Archie is a great way to find sources. However, if you have access to the comp.widows.x FAQ (Frequently Asked Questions) list, looking through the FAQ might actually be easier. The FAQ is a great wealth of information that is posted at the beginning of each month to the newsgroup comp.windows.x. It is updated frequently, so if you have absolutely any question about X, the first place you should look is in the FAQ. As far as sources are concerned, some public domain sources are placed on several anony- mous ftp sites, but not all are updated when new versions or bug fixes are announced. If the comp.windows.x FAQ list tells you where to get sources, it's likely to tell you the most reli- able site. If you don't have a FAQ handy, either post to one of the comp.windows.x newsgroups for someone to send it to you, orfip it yourself as described in Section A.2. You can also get it from mail-server@pit-manager.mit.edu. Or if you can wait a little, look for it on comp.win- dows.x--the FAQ is promptly re-posted at the beginning of every month, as are the FAQs for comp.windows.x.motif and comp.windows.openlook. (If you don't have access to Usenet, you can get on a mailing list called xpert. To get on that mailing list, send mail to xpert-request@expo.lcs.mit.edu.) At this writing, there are 145 questions answered in the FAQ, definitely worth the bandwidth to get it. If you find it useful, also look for the FAQs for OSF/Motif and for OPEN LOOK. B.1.3 The Usual Suspects You can find a description of other ways to find sources on the machine rOCrn.mit.edu, in the directory/puh/usenet/news.answers. A list offtp sites can be found in the ftp-list directory, and the file finding-sources gives some more information on how to find what you want. If neither the FAQ nor Archie mentions what you want, and you have Internet access, try a few of the usual suspects--such as export.lcs.mit.edu (where you'd also find the X l I sources themselves) in the/contrib directory, orftp.uu.net in the/comp.windows.x directory. (While you're at export or uunet, you might want to browse around a bit. There's a lot of good stuff available, you just need to know about it.) If all else fails, try sending a polite post to comp.windows.x asking if this program is public domain and, if so, would anyone be kind enough to help you get it. 250 The X Window System Administrator's Guide act ions. c get_vdir, c udp. c act ions. h patchl evel. h vl_ccp, c alert, c pauthent, h vlalloc, c alert .h pccpat .h xarchie- 1.3. tar. Z appres, h perrmesg, c xarchie, c aquery, c perrno, h xarchie, h archie, h pfs. h xarchie, man atal 1 oc. c Inachine. h imui@opal% Now we've come to the First Cardinal Rule of compiling sources: when there's a README, read it. imui@opal% more README  for Xarchie - Xll browser interface to Archie George Ferguson, ferguson@cs, rochester, edu Last Change: 12 Nov 1991 DISCLAIMER: This is release 1.3 of xarch/e -- an X browser interface to the Archie Internet information system. This software is provided as is with no warranty expressed or implied. I hope you find it useful, but I n't be held responsible for any damage that may occur frcm reading, ccpiling, installing, using, or even thinking about it. ..o Further down in the README are the instructions on how to actually install the program. INSTALLATION: i. Edit the Imakefile to reflect any changes for your site. These include setting BINDIR, LIBDIR, and MANDIR if needed, and checking CDEBUGFLAGS if debugging or optimization is desired. If your system doesn't have re_ccp() and re_exec(), then you need to unccment the appropriate section in the Imakefile to include those routines. Ccpiling this program requires the "ad2c" program. You should have received a copy of ad2c with this distribution, in the subdirectory "Ad2c'. You should set the AD2C variable as r_quired. Actually, ad2c is only required if you change Xarchie.ad and want the new defaults ccpiled in as fallback resources. If you don't have ad2c, you probably want to remove the line that adds Xarchie.ad.h to the "clean" target. You may want to change defaults in Xarchie.ad; consult the manpage for details, and see above about ad2c. This brings us to Cardinal Rule Number 2: follow directions. Compiling Public Domain Software 253 B.2.3 Editing the Imakefile You may not feel up to editing an Imakefile, but we recommend that you give it a try regard- less. The xarchie lmake3le is somewhat non-standard, but it is straightforward and well-doc- umented, so it's a good place to start becoming familiar with imake. We'll build a more stan- dard program, xkeycaps, later in this appendix. If you don't know what imake is, it's basically a utility to create Makefiles based on system dependencies. It actually makes a lot of sense--if you're building a lot of applications for a lot of different machines, you end up editing your Make3le a lot according to each different machine, and then you have to edit the Make3le of the next application according to the same dependencies, and it seems as if you keep duplicating your edits, imake lets you set up sys- tem dependencies in an independent place, in a file called lmake.tmpl, usually kept in /usr/lib/X11/con3g. For more information on imake syntax, see Section 8.7. If you just read the lmake3le carefully, you'll get the idea of the sorts of things you might change. # # Imakefile for xarchie : Xll Browser interface to Archie # # George Ferguson, ferguson@cs.rochester.edu, 12 Sep 1991. # # Where do you want this stuff? Unconent and adjust these to change the # destinations of "make install" and "make install.man" if the defaults # are not satisfactory. #BINDIR = bin #LIBDIR = lib #MANDIR = man/manl ##undef ManSuf fix ##define ManSuffix 1 BINDIR is the target directory where the xarchie program will eventually be installed. If you prefer that xarchie be installed in/usr/local/bin, this is where you'd specify it. Otherwise, the program will be installed in whatever directory imake has been configured for on your system. On our system, the default is/usr/bin/X11. LIBDIR is your X library directory. On our system, the default is/usr/lib/Xll. MANDIR is where the manual pages go. On our system, the default is/usr/man. In all three cases, we are satisfied with the default values and leave them unchanged. Con- tinue with the lmakefile: # Where is the app-defaults to C converter? # Only needed if you change the app-defaults file Xarchie.ad and want the # changes compiled into the program. If you don't have ad2c you should # remove the extra clean target for Xarchie.ad.h below. If you lose # Xarchie.ad.h and can't remake it, create it to be an empty file. Of course # then you'll have to use the resource file at run time. # If your ad2c came from this xarchie distribution, then use the following # target, otherwise change it to reflect where you put ad2c. AD2C = Ad2c/ad2c. script # Where is the EzMenu widget package? # You should have received a copy of the EzMenu package with this 254 The X Window System Administrator's Guide # xarchie distribution. EZMENUDIR = EzMenu EZMENULIB = ezMenu$ (TARGET_MACH) Since both the ad2c and EzMenu packages were included in the tar file, we don't have to do anything here. # How excited are you about debugging? This can be -g, -O, or nothing. CDEBUGFLAGS = -g # To enable Prospero tracing (controlled by the -debug option), unccnent # this #PDEBUG = -DDEBUG # Does your system have re_comp ( ) and re_exec ( ), or regcmp ( ) and regex ( ) # [in the case of A/UX] ? If not, unccnent the following definitions. #REGEXC = regex.c #REGEXO = regex, o ########################################################################### # Nothing to change below here... We don't care about debugging, we don't know what Prospero tracing is, and we've deter- mined that we have the re_compO and re_execO functions by using the man command on them. We thus declare ourselves to have finished editing the lmakefile. As for editing the application defaults: the file Xarchie.ad is the systemwide resource file for the xarchie application. It's worth it to take a minute to make sure it's set up the way you want it. , ! Xarchie.ad : Appli.cation defaults for the Xll browser interface to Archie ! George Ferguson, ferguson@cs.rochester.edu, 12 Nov 1991. ! Non-widget resources Xarchie. archieHost: archie, sura. net ! Possible values are: exact, substr, subcase, or regexp Xarchie. searchType: exact This is when you'd change the name of the archie host to the one closest to you. For example, you might change it to the one at Rutgers: Xarchie. archieHost: archie, rutgers, edu B.2.4 Compiling the Source Once the lmakefile is set up, compiling is usually a matter of just executing a few commands and hoping it works. From the README: 2. Execute % xmkmf to create the Makefile. Compiling Public Domain Software 255 If you're running Xl IR4 or later, your X distribution comes with a command called xmkmf, which stands for "'X Make Makefile." xmkmf is a shell script (usually kept in/usr/bin/Xll) that is designed to run imake to create Makefiles for third-party X 11 software distributions. See Section 8.6.1 for more information on xmkmf. If a software distribution comes with a proper Imakefile, if your X distribution is set up prop- erly, and if you're generally a lucky person, you can simply run xmkmf and your Makefile(s) are all set. imui@opal% xmkmf mvMakefileMakefile.bak imake -DUseInstalled -I/usr/lib/Xll/config imui@opal% You now have a new Makefile. (Although a Makefile was supplied with the distribution for sites that may not have imake, it's always better to use one generated by imake.) 3. Execute % make Makefiles to run xmkmf in the Ad2c and EzMenu subdirectories. Alternately, run it (or imake) in each subdirectory by hand. 4. Execute % make depend to add the dependencies to the Makefile. This is necessary to ensure that Xarchie.ad.h is created when needed. IMPORTANT: Ignore the error message frcn makedepend if Xarchie.ad.h is not found; it will be created autcatically. Once again, follow directions. imui@opal% make Makefiles making Makefiles in ./Ad2c... rm -f Ad2c/Makefile.bak + mv Ad2c/Makefile Ad2c/Makefile.bak cd Ad2c; imake -DUseInstalled -I/usr/lib/Xll/config -DTOPDIR=../. IR=./Ad2c; \ make Makefiles making Makefiles in ./EzMenu... rm -f EzMenu/Makefile.bak + mv EzMenu/Makefile EzMenu/Makefile.bak cd EzMenu; imake -DUseInstalled -I/usr/lib/Xll/config -DTOPDIR=../. RDIR=./EzMenu; \ make Makefiles imui@opal% make depend makedepend -s "# DO NOT DELETE ...... I. -IEzMenu -DARCHIE -DXARCHIE -- aquery, c atalloc, c dirsend, c get_pauth, c get_vdir, c perrmesg, c ptalloc, c stcopy, c support, c vl_comp, c vlalloc, c xarchie, c db.c actions.c types.c classnames.c procquery.c settings.c ftp.c alert, c confirm, c dialog, c (In R5, xmkmf-a will take combine steps 2-4 of this example.) Now you're ready for the moment of truth: 5. Make the package using % make or install it directly with % make install install.man 256 The X Window System Administrator's Guide cc -o xarchie aquery.o atalloc.o dirsend.o get_pauth.o get_vdir.o perrmesg, o ptalloc, o stcopy, o support, o vl_ccp, o vlalloc, o xarchie, o db.o actions.o types.o classnames.o procquery.o settings.o ftp.o alert.o confirm.o dialog.o -g -pipe -LEzMenu -lezMenu-sparc -iXaw -]/mu -iXt -iXext -IX11 install -c -s xarchie /usr/bin/Xll install -c -m 0444 Xarchie.ad /usr/lib/Xll/app-defaults/Xarchie install -c -m 0444 xarchie.man /usr/man/mann/xarchie.l If you're satisfied with these locations, run the installation for real. (You may have to become root now.) imuiSopal% su Password: opal# make install making all in ./EzMenu... rm -f xarchie cc -o xarchie aquery.o atalloc.o dirsend.o get_pauth.o get_vdir.o perrmesg, o ptalloc, o stcopy, o support, o vl_ccp, o vlalloc, o xarchie, o db.o actions.o types.o classnames.o procquery.o settings.o ftp.o alert.o confirm.o dialog.o -g -pipe -LEzMenu -lezMenu-sparc -iXaw -iXmu -iXt -iXext -IXll install -c -s xarchie /usr/bin/Xll install -c -m 0444 Xarchie.ad /usr/lib/Xll/app-defaults/Xarchie install -c -m 0444 xarchie.man /usr/man/mann/xarchie.l And now it's just a matter of running rehash and starting the xarchie application. imui@opal% rehash imui@opal% xarchie & Note that, for this example, you didn't need to know any C programming, you just needed to use some basic common sense. Not all compilations work this easily, but many do. B.3 Using Patches A patch to a program is exactly what it sounds like: a fix to build on the current sources. As an example, in the following example we have the xwebster sources from export.lcs.rnit.edu, which we will unpack and untar. imui@opal% zcat xwebster.tar.Z I tar xfp - imui@opal% cd xwebster imui@opal% is -F Imakefile controlpanel, c user_prefs.h xwebster, c xwebster.xhm Make file display_def, c wordlist, c xwebster, h Xwebster. ad patches/ xwebster.  xwebster, man (The xwebster program is a client program depending on access to a licensed Webster server. Unless you have access to such a server, you will not be able to use this program. It also requires a compiled Xw library, which many vendors don't include--you'll have to build it yourself.) Compiling Public Domain Software 259 Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk Hunk done #2 succeeded at 32. #3 succeeded at 57. #4 succeeded at 71. #5 succeeded at 105. #6 succeeded at 116. #7 succeeded at 131. #8 succeeded at 166. #9 succeeded at 173. #i0 succeeded at 199. #ii succeeded at 259. #12 succeeded at 271. #13 succeeded at 287. #14 succeeded at 319. #15 succeeded at 332. #16 succeeded at 342. #17 succeeded at 372. #18 succeeded at 386. #19 succeeded at 411. (The message staing with "Hmm . . . " is the patch program's polite way of telling you what it thinks it's doing.) The second patch (patches/patch-Ol) resembles the first in form: Return-Path: root@gauss.llnl.gov ... Received: from localhost.ARPAby gauss.llnl.gov (4.0/1.15) idAA00823; Tue, 3 Apr 90 13:11:46 PDT Message-Id: <9004032011.AA00823@gauss.llnl.gov> From: casey@gauss.llnl.gov (Casey Leedom) To: mayer@hplms2.hpl.hp.com (Niels P. Mayer) Subject: Small fixes.to X.VllR4/contrib/clients/xwebster/Imakefile Date: Tue, 03 Apr 90 13:11:45 -0700 Sender: root@gauss.llnl.gov *** Imakefile-dist Mon Mar 6 03:41:36 1989 Imakefile Wed Mar 28 11:00:54 1990 *** 1,37 **** # # This assumes that the HP Xwidget sources patched for r3 have been placed ! # in $(TOP)/lib/Xw. # ! XWLIB = $(TOP)/lib/Xw/libXw.a Apply this patch in a similar fashion: imui@opal% patch < patches/patch-01 Hn... Ixoks like a new-style context diff to me... The text leading up to this was: ]*** Imakefile-dist Mon Mar 6 03:41:36 1989 ]--- Imakefile Wed Mar 28 11:00:54 1990 Patching file Imakefile using Plan A... Hunk #i succeeded at i. done Compiling Public Domain Software 261 Hunk #I succeeded at 50. Hnn... The next patch looks like a new-style context diff to me... The text leading up to this was: I*** /tmp/,RCStlall804 Wed Jun 28 14:29:00 1989 I--- Xwebster.ad Wed Jun 28 14:22:26 1989 Patching file Xwebster.adusing Plan A... Hunk #I succeeded at 48 (offset 2 lines). Hunk #2 succeeded at 307 with fuzz 1 (offset 28 lines). Hunk #3 succeeded at 297 (offset 4 lines). Hunk #4 failed at 368. Hunk #5 succeeded at 454 (offset 49 lines). 1 out of 5 hunks failed--saving rejects to Xwebster.ad.rej Hnn... The next patch looks like a new-style context diff tome... The text leading up to this was: I*** /tp/,RCStlall812 Wed Jun 28 14:30:18 1989 I--- controlpanel.c Wed Jun 28 14:22:27 1989 Patching file controlpanel.c using Plan A... Hunk #I succeeded at 40. Hunk #2 succeeded at 47. Hunk #3 succeeded at 209. Hunk #4 succeeded at 270. Hunk #5 succeeded at 330. Hunk #6 succeeded at 374. Hunk #7 succeeded at 402. Hunk #8 succeeded at 426. Hunk #9 succeeded at 483. Hunk #i0 succeeded at 502. Hunk #II succeeded at 520. Hnn... The next patbh looks like a new-style context diff tome... The text leading up to this was: I*** /tp/,RCStlal1826 Wed Jun 28 14:32:56 1989 I--- xwebster.c Wed Jun 28 14:22:31 1989 Patching file xwebster.c using Plan A... Hunk #I succeeded at 266. Hunk #2 succeeded at 275. done The error you may want to pay attention to is the one that failed, at line 368 in the Xweb- ster.ad file. The patch program is nice enough to tell you what failed and to save the rejected patch in a file called Xwebster.ad.rej. (You can use the -s option to patch to suppress com- ments and report failures only.) You can examine that file and see if you can reconstruct what it intends to do, but that's beyond the scope of this exercise. When you are satisfied that all patches are applied, you can complete the build: imui@opal % xmkmf mv Makefile Makefile.bak imake -DUseInstalled -I/usr/lib/Xll/config imui@opal% make depend makedepend -s "# DO NOT DELETE .... I/work/imui/src/Xw -DAPPDEFAULTSDIR= display_def.c wordlist.c xwebster.c Compiling Public Domain Software 263 imui@opal % make cc -O -pipe - I/work/imui/src/Xw -DAPPDEFAULTSDIR= -target sun4 -c controlpanel.c cc -0 -pipe - I/work/imui/src/Xw -DAPPDEFAULTSDIR= -target sun4 -c display_def.c cc -0 -pipe -I/work/imui/src/Xw -DAPPDEFAULTSDIR= -target sun4 -c xwebster, c rm -f xwebster cc -o xwebster controlpanel.o display_def.o wordlist.o xwebster.o -O -pipe /work/imui/src/Xw/Xw/libXw.a -iXt -iXext -IXll imui@opal% Once the you have edited the application defaults to reflect the location of the Webster server, you can install the xebster program system-wide by executing make install and (optionally) make install.man as root. Then read the manual page to learn how to run the pro- gram and enjoy. B.4 Another Example-xkeycaps Before we end this appendix, let's show a more "standard" compilation. For this we choose xkeycaps, a public domain program that's useful as a front end for the xrnodrnap program. xkeycaps can be taken from export.lcs.mit.edu: imui@ruby 35% ftp export.lcs.mit.edu Connected to export.lcs.mit.edu. 220 export.lcs.mit.edu FTP server (NEWS-OS Release 4.1C) ready. Name (export.lcs.mit.edu:imui): anonymous 331 Guest login ok, send ident as password. Password: 230 Guest login ok, access restrictions apply. ftp> cd contrib 250 CWD conmand successful. ftp> is *keycaps* 200 PORT conm%nd successful. 150 Opening data connection for /bin/is (ascii mode) (0 bytes). xkeycaps, tar. Z 226 Transfer complete. remote: *keycaps* 16 bytes received in 0.014 seconds (1.2 Kbytes/s) ftp> bin 200 Type set to I. ftp> get xkeycaps, tar. Z 200 PORT conm%nd successful. 150 Opening data connection for xkeycaps.tar.Z (binary mode) (121687 bytes). 226 Transfer complete. local : xkeycaps, tar. Z remote: xkeycaps, tar. Z 121687 bytes received in 31 seconds (3.9 Kbytes/s) ftp> quit 221 Goodbye. imui@ruby 36% Now that we have it, unpack the compressed tar file, take a look at the resulting directory contents. Once again, since there's a README, read it. 264 The X Window System Administrator's Guide Sun2 Sun3 Sun4 Sun4ow N97 NI01 NI02 NI02SF NI02N NI02F NI08 NCD220 LK201 LK401 RS6k SCOII0 HP700X HP720 NWS DELL SGI Explorer - Sun type2 (MIT layout) - Sun type3 (MIT layout) - Sun type4 (MIT layout) - Sun type4 (OpenWindows layout) - Network Ccputing Devices N97 - Network Ccputing Devices NI01 - Network Ccputing Devices NI02 - Network Ccputing Devices NI02 (Swedish/Finnish layout) - Network Ccputing Devices NI02 (Norwegian layout) - Network Ccputing Devices NI02 (French layout) - Network Ccputing Devices NI08 - Network Ccputing Devices vt220 - Digital Equilmnent Corporation LK201 - Digital Equilmnent Corporation LK401 - Inferior But Marketable RS/6000 - Santa Cruz Operation II0 - Hewlett Packard 700X - Hewlett-Packard 720 - Hewlett-Packard PC - Atari T? - Sony NWS 1250 - DELL PC - Silicon Graphics - Texas Instruments Explorer As the default, we get the N101 keyboard: [ XKeyCaps; Network Computing Oult KeyCode" Select Keyboard) KeySym:   -, ASCII" Figure B-2. xkeycaps window When you decide to install xkeycaps, run both make install and make install.man as root. As before, it's a good idea to check what's going to be installed before you actually do it, using the -n option to make: imui@ruby 82% make -n install install.man if [ -d /usr/bin/X11 ] ; then set +x; \ else (set-x; /bin/sh /usr/bin/Xll/mkdirhier /usr/bin/Xll); fi Compiling Public Domain Software 267 install -c -s xkeycaps /usr/bin/Xll echo "install in . done" if [ -d /usr/man/mann ]; then set +x; \ else (set-x; /bin/sh /usr/bin/Xll/mkdirhier /usr/man/mann); fi install -c -m 0444 xkeycaps.man /usr/man/mann/xkeycaps.n echo "install.man in . done" If this is fine with you, go ahead and install the program: imui@ruby 83% su Password: # make install install.man install -c -s xkeycaps /usr/bin/Xll install in . done install -c -m 0444 xkeycaps.man /usr/man/mann/xkeycaps.n install.man in . done # B.5 Related Documentation imake is discussed in more detail in Section 8.7. For more information on xmkmf, see its manual page and Section 8.6.1 of this book. The Whole Internet User's Guide & Catalog by Ed Krol (O'Reilly & Associates, 1992). Managing Projects with make, by Andy Oram and Steve Talbott (O'Reilly and Associates, 1991). 268 The X Window System Administrator's Guide C X on Non-UNIX Platforms X runs on all types of hardware, on all sorts of operating systems. Both cli- ents and servers run on IBM-compatible PCs running DOS, as well as Macin- tosh computers. Full X distributions are available for NeXT machhTes, but the servers have to negotiate with the NeXTstep interface. This chapter briefly describes the X products available on those platforms. In This Appendix: X on DOS-based PCs ........................................................................ 272 Requirements for PC X Servers ..................................................... 272 Installing and Configuring PC X Servers ........................................ 273 Problems Particular to PC X Servers ............................................. 274 X on Macintosh Computers ................................................................ 275 Macintosh-based X Servers ........................................................... 275 MacTCP and the Communications Toolbox .................................... 276 X on NeXT Computers ....................................................................... 277 Since there are so many products out there, this appendix only covers generalities about X running on other platforms. For more information, look for the monthly posting on comp.win- dows.x on X servers for PCs, Macs and Amigas. This document is also kept on export.lcs.mit.edu in the file/contrib/XServers-Non UNIX.txt.Z. C.1 X on DOS-based PCs Most X software available on PCs running DOS is server software. There are two types of PC X servers on the market: those that run on top of DOS directly, and those that run on top of Microsoft Windows. The X servers that run on top of DOS replace the entire desktop, and returning to DOS usually requires exiting (or suspending) X. The X servers that run on top of Windows, on the other hand, provide an integrated environment with access to both X and Microsoft Windows applications simultaneously. Some Windows-based X servers also let you cut-and-paste between the X environment and the Windows environment. If the PC will be used primarily for running X--that is, as an economical X terminal--then the DOS-based X servers are probably sufficient for your needs. If the PC will frequently be used to run Windows applications as well, however, Windows-based X servers give you the best of both worlds. Desqview/X by Quarterdeck Office Systems provides the first distribution of both X clients and servers for PCs running MS/DOS. Desqview/X runs on top of Quarterdeck's Desqview multi-tasking GUI, integrating DOS applications, MS-Windows applications, and X applica- tions. You can use Desqview/X to remotely execute PC applications as X clients and display them on any connected X server. C.1.1 Requirements for PC X Servers We mentioned that PCs have to meet serveral requirements before they can run X servers. In general, before you can run a PC X server, you have to meet the following requirements: Processor The PC should have a 80386 or '486 CPU processor. (Some vendors also support '286 machines, but no one recommends it.) Monitor The PC needs an enhanced video display. Most vendors require either a VGA or Super VGA display. Some vendors also support EGA and 8514 graphics. Note that what the PC world calls a "high resolution" monitor still has lower resolu- tion than a low-resolution X terminal. Mouse The PC must have a two-button or three-button mouse. Memory The PC must have 640K bytes of base memory, plus either 1.4 megabytes of usable extended memory for DOS-based X servers, or 2 megabytes of memory for Windows-based X servers. 272 The X Window System Administrator's Guide C.2 X on Macintosh Computers Full X distributions are available on Macintosh computers that run UNIX as well as the Mac- intosh OS. Two UNIX products for the Macintosh are System-V based A/UX by Apple Com- puter, and BSD-based MachTen from Tenon Intersystems. If you don't have a full UNIX distribution, you can still run an X server, or set up the Macin- tosh to run an X client. There are currently two X server products for the Macintosh: MacX and eXodus. MacX is a Macintosh X server that is available from Apple Computer (it is also bundled with their System V-based UNIX operating system, A/UX, as of version 2.0. l). eXo- dus is a Macintosh X server distributed by White Pine Software. There are also currently two X client products for the Macintosh: Planet X and Xgator. Planet X is distributed by InterCon Systems and Xgator is distributed by Cayman Systems. The advantage of a Macintosh X client is that you can run Macintosh programs on your X terminal. Unfortunately, only one user can access the same Macintosh at a time, so the Mac- intosh becomes disabled while the X client is running, and no other X users can start up the client software while someone else is using it. Macintosh-based X servers and clients alike require either a direct Ethernet connection or a LocalTalk connection to a LocalTalk/IP gateway such as Cayman's GatorBox. The Commu- nications Toolbox must also be installed (standard with System 7), with the MacTCP tool installed and configured properly.* (eXodus works with DECnet as well as TCP/IP.) C.2.1 Macintosh-based X Servers Both X servers for the Macintosh, MacX and eXodus, can run either "rootless" or "rooted." By "rootless," we mean that X clients open directly on the Macintosh desktop, intermixed with other Macintosh windows. The Macintosh OS acts as a window manager for both X and Macintosh windows. By "rooted", we mean that a typical X root window is active, either enclosed entirely within a Macintosh window, or available through a pull-down menu. An X window manager can be used in a rooted window (such as twrn, rnwrn or olwm). Some X programs may have problems with a rootless environment; to run those programs, use rooted screens only. MacX defines 4 screens: screen 0 is rootless monochrome, screen l is rooted monochrome, screen 2 is rootless color, and screen 3 is rooted color, eXodus allows you to define up to 6 screens as either rooted or rootless. One of the most obvious problems with using a Macintosh as an X server is that the Macin- tosh mouse only has one button. MacX uses the left-arrow and right-arrow keys to act as the second and third mouse button (respectively). eXodus provides a little more flexibility for configuring mouse behavior. In addition, there are third-party mice for Macintosh computers that have two or three buttons. * SLIP has also recently become available for the Macintosh. X on Non-UNIX Platforms 275 (Users of OPEN LOOK programs can use the props utility to change the behavior of the SELECT mouse button so that it brings up menus instead of selecting the default item when pressed on a menu button. This is a good tip for all 1- and 2- button mouse users. Mac users who also run olwm might also want to use props to turn off "pointer jumping," by which olwm and olvwm move the mouse pointer automatically to follow scrollbars and pop-up notices.) You can get upgrades to MacX from aux.support.apple.com, in the /aux.patches/sup- ported/MacX directory. You are encouraged to retrieve the MacX upgrades only if you already have a legal license for MacX. (Only the server is redistributed on the ftp site, which is useless without the fonts or a font conversion utility anyway.) If you use either MacroMaker or QuickKeys on your Mac, it is strongly recommended that you disable it. MacroMaker and QuickKeys translate keystrokes, conflicting with the X server. C.2.2 MacTCP and the Communications Toolbox To run Macintosh X products, you generally need to have MacTCP running. MacTCP was developed by Apple, and is distributed by several third-party vendors. It is also bundled with MacX. MacTCP runs under the Communications Toolbox. The following tips are important to note when installing MacTCP: 1. You must install the Communications Toolbox correctly. Under System 7, the Commu- nications Toolbox is already installed as part of the base OS distribution. If you need to install the Communications Toolbox for a Macintosh that is not running System 7, how- ever, you can't simply create a Communications folder under your System folder and copy the MacTCP tool in there. You must run the installation utility that is bundled with the Communications Toolbox. If you don't install the Communications Toolbox correctly, you'll never get a message that tells you it's improperly installed. Instead, you'll get an error message such as "No Communications Tools Installed," which misleadingly implies t_hat the Toolbox is installed correctly but MacTCP isn't. 2. You need to copy the MacTCP tool to the new Communications folder within the system folder, and copy the MacTCP and AdminTCP files to the System folder (under System 7, these files reside in the Control Panels folder). We strongly recommend that you do not copy these files from another Macintosh, but take them directly from the distribution flop- pies. If you do copy them from another Mac, make sure not to take the MacTCP Prefer- ences file. 3. Configure MacTCP using the AdminTCP control panel document. (AdminTCP is identi- cal to MacTCP, except that you can use AdminTCP to lock the configuration after it is properly configured.) Here is where you specify things like your IP address, subnet mask, name server, etc. 4. Reboot and try running a MacTCP program. 276 The X Window System Administrator's Guide 5. Once you have confirmed that MacTCP is properly configured, put a lock on it and throw the AdminTCP file in the trash. A possible conflict with MacTCP is that if you are also running NCSA Telnet, you need to be sure that you are running the version that is MacTCP-compatible. That means that you need to install the version of NCSA Telnet entitled something like Telnet 2.4 - MacTCP. If you don't do this, then after running an application that uses MacTCP, you won't be able to run NCSA Telnet again until you reboot. Notes on configuring MacTCP are available on sumex-aim.stanford.edu in the file /info- mac/report/mac-tcp-info.txt . C.3 X on NeXT Computers The NeXT machine does not technically belong in a chapter about non-UNIX machines, since it is based on UNIX. The NeXT machine also has built-in Ethernet and TCP/IP, so a lot of the issues for running X on PCs and Macs don't apply to the NEXT. However, we discuss them here because NeXT X distributions are a different breed from other UNIX distributions, since they have to deal with the NeXTstep interface. A public domain R4 X distribution for the NeXT called XNeXT is available through anony- mous ftp from cunixf.cc.columbia.edu. (Although an R5 server is currently available for the NeXTstation Turbo, it is not yet available for other NeXT machines.) There are also three commercial products for the NEXT. These are co-Xist by Pencom Soft- ware, Cub'X by Cub'X Systemes (distributed in the U.S. by Interactive Technology), and eXodus from White Pine Software. Cub'X and co-Xist are full X distributions including servers, clients, and libraries, with OSF/Motif clients and libraries also available, eXodus is just a server with a select group of clients. All three commercial implementations meld X with the NeXTstep interface much in the way Macintosh and Windows-based X servers do, in a "rootless" mode. XNeXT, on the other hand, supplants the NeXTstep interface and requires you to "hot-key" to switch between the two modes. Regardless of what X server you choose to run on the NEXT, you should make sure that the second mouse button is enabled in NeXTstep (through the Preferences application), or it won't be available to the X server. X on Non-UNIX Platforms 277 D Resources and Keysym Mappings Resources and keysym mappings are topics that the administrator needs to be familiar with in order to configure applications and set up user environ- ments. This appendix gives some background material on both of those top- ics. In This Appendix: Using Resources Resource Definition Syntax .................................................... Loose and Tight Bindings ..................................................... The -name Command-line Option ........................................ xterm Versus XT.erm ............................................................ Where Resources Are Defined ............................................... Advantages of xrdb ................................................................ Translation Tables .................................................................. Defining Keys and Button Presses With xmodmap ..................... Using xev to Learn Keysym Mappings ........................................... 292 Related Documentation ..................................................................... 293 ....... 281 ....... 282 ....... 283 ....... 283 ....... 285 ....... 287 ....... 288 ....... 290 D Resources and Keysym Mappings Two important pieces to the X puzzle are resources and keysym mappings. Although these two issues are unrelated, they both come into play when administrators have to debug user environments or configure applications system-wide. This appendix gives some background material on both of those topics. Resources are covered in detail in Volume Three, X Window System User's Guide, by Valerie Quercia and Tim O'Reilly (O'Reilly & Associates, 1990). Some of the material in this chap- ter repeats what you'll find there, but we also give some useful tips and advanced informa- tion for administrators. Even if you are familiar with how to use resources, you may want to scan this appendix. D.1 Using Resources Resources are tricky to deai with, but understanding how they work is extremely important for X administration. They are used for configuring not only everyday clients like xterm and xclock, but also special clients such as window managers and the X Display Manager (xdm). Resource syntax is used even by some X terminal vendors for configuring the X server remotely. For these reasons, we think it's worth it to cover resource definition in depth. D.1.1 Resource Definition Syntax The syntax for defining resources can be quite complex, requiring some familiarity with widget hierarchies. For our purposes, however, it will suffice to know that the syntax for a simple resource follows the form: name*variable: value For e xample: xt erm*background: cadetblue xterm* foreground: deeppink specifies that the client named xterm should use a background color of cadet blue and a fore- ground color of deep pink. Similarly, you can specify a specific font with: xterm* font: -schumacher-clean-bold-r-normal--16-160-75-75-c-80-iso8859-1 Resources and Keysym Mappings 281 D.1.1.2 D.1.1.3 the xcal calendar program, for example, to affect the behavior of the xcalc calculator pro- gram as well. A resource can be overridden by a more specific resource--for example, if you set the fol- lowing resources: xterm*background: blue xterm.VTl O0. background: red and then open a standard xterm window with the VTIO0 widget, the second declaration is more specific than the first and the window background will appear in red. However, note that any other xterm widgets, such as mainMenu, will appear with a blue background. In R5, the question mark (.9) character is introduced in resource names. A question mark in a resource name represents exactly one field in a loose binding. Loose bindings using question marks are considered to be more specific than bindings using only asterisks. Bindings with question marks will therefore take precedence over other loose bindings. The-name Command-line Option An X toolkit option that has an important effect on which resources a client uses is the -name option, which effectively changes the name of the client. By changing the name of the client, it changes the name of the resources it accepts as well. The possibilities available with the -name option are best illustrated by example. A user might want to have xterm windows from a host called sapphire with a blue border, but win- dows from host ruby with a red border. There are multiple ways of doing this, but one way might be to define the following resources to be accessed by all xterm clients: xt erm- sapphire *BorderColor: blue xterm- ruby*BorderColor: red and then start up the windows with -name options, to give the window from machine rub)' the name xterm-ruby and the window from the machine sapphire the name xterm-sapphire. % xterm -name xterm-ruby & % xterm -name xterm-sapphire & Although the -name option for the xterm client changes the string in the titlebar as well, it should not be confused with the -title option, which changes the string in the titlebar but does not change the name of the client itself. xterm Versus XTerm Although we'd like to avoid all the complexities of how resources are named, there is one detail that we can't escape. Sometimes the name xterm is used in resource names, and sometimes XTerm is used. Although this usage seems arbitrary, it isn't at all, and the two terms should not be confused. The name of your window is usually the name of the client; that is, if you just run xterm, the window that comes up will have the name xterm. As described above, however, you can use the -name toolkit option to change the name of the window. For example, if you are running a console window (started with the -C option to xterm), you might want to name that window Resources and Keysym Mappings 283 shared among multiple hosts. In general, the preferred way of specifying a reasonable number of resources for a user is to use xrdb. The xrdb client is typically run in the user's startup script, e.g., .xsession or .xinitrc, to load a resource file (any filename can be used, but common names are .Xresources and .Xdefaults). An administrator can also set up a default resource file for all users, to be read by xrdb in the systemwide startup script (for sessions started with xdm, this would be /usr/lib/Xll/xdm/Xsession). Note that resources loaded into the resource database are still read only at client startup: a change will affect only subsequent clients, not clients already running. 5. If no resources are loaded directly into the server (i.e., if xrdb has not been run), defaults are read from a file called .Xdefaults, usually in the user's home directory. Note that this means that clients run from different hosts may use different resources if your home directory is not shared among machines. 6. Resources loaded directly on the command line, using the -xrm option. In the list above, we say that some default files are "usually" read from a user's home direc- tory. The directory in which you keep your application defaults is assumed to be your home directory. The XAPPLRESDIR environment variable comes into play here--if you set XAP- PLRESDIR to $HOME/Xstuff, the resource manager will look under that directory for client- specific resource files (such as XTerm). Other environment variables that affect where resources are read from are XFILESEARCHPATH and XUSERFILESEARCHPATH. Seeing Where Resources are Read (SunOS, Solaris, SVR4) To see what resource files are read on client startup, try using the trace command on a SunOS machine, or the truss command on a Solaris 2.0 or SVR4 machine. For example: imui@ruby% trace xterm >& /tm/xterm. trace Then examine the resulting file: gethostname (" ", 1002) = 0 open ("/hcme/imui/.Xdefaults-ruby", 0, 017777777) =-i ENOENT (No such file or directory) access ("/hcme/imui/XTerm", 04) = -1 ENOENT (No such file or directory) access ("/usr/lib/X11/app-defaults/XTerm", 04) = 0 stat ("/usr/lib/X11/app-defaults/XTerm", 0xf7ffed90) = 0 open ("/usr/lib/X11/app-defaults/XTerm", 0, 036734323664) = 4 stat ("/usr/lib/Xll/app-defaults/XTerm", 0xf7fff200) = 0 read (4, "*SimpleMenu*BackingStore: NotUse".., 2800) = 2800 close (4) = 0 In the example, note that the user had resources loaded into the server, so $HOME/.Xde- faults was not opened. The only resource file in its path that it found and opened was the system-wide app-defaults/XTerm file. 286 The X Window System Administrator's Guide Calculator Figure D-1. xcalc window Each button is given its label (e.g., PI for the first button), followed by the event translation when it is pressed. In the case of the 16th button, the internal function piO is called, presum- ably returning the value of n. (Since the foreground and background colors are reversed on the button when it is initially pressed, the Athena Command widget action unsetO is then called, returning the button colors to the default.) For the 20th button, "/" is the label, and pressing it calls the divide() function. Clearly a user could easily redefine the behavior of each button on the xcalc keypad by switching the translations in their own resource files. (Be sure to switch the labels too, though!) Also in the XCalc application defaults file is a full translation table for interpreting keys- trokes within the xcalc window: XCalc. ti. bevel, screen. LCD. Translations: #replace\n\ Ctrlc :quit ( ) \n\ Ctrlh: clear ( ) \n\ None0: digit (0) \n\ Nonel :digit (i) \n\ _'0: digit (0) \n\ KP_I : digit (i) \n\ 3 :digit (9) \n\ ooo KP_Divide: divide ( ) \n\ : [iecimal ()\n\ +: add ( ) \n\ -: subtract ( ) \n\ * :multiply ( ) \n\ /:divide() \n\ ( : leftParen ( ) \n\ ) : rightParen ( ) \n\ ! : factorial ( ) \n\ Resources and Keysym Mappings 289 D.2.1 Using xev to Learn Keysym Mappings The xev client is essential for debugging keysym mappings. When you start up xev, a small "event window" appears. All events that take place within that window are shown on stan- dard output. This means screenfuls of output, but it also means that when you type a key, you can immediately trace the resulting event. For example, if you need to know what keysym is sent when you type the Delete key on the keyboard, just run xev and type the Delete key in the event window. Typical output might be: KeyPress event, serial 13, synthetic NO, window 0x800001, root 0x8006d, sub 0x800002, time 1762968270, (50,36), root: (190,176), state 0x0, keycode 27 (keysym 0xffff, Delete), same_screen YES, XLookupString gives 1 characters: KeyRelease event, serial 15, synthetic NO, window 0x800001, root 0x8006d, sub 0x800002, time 1762968336, (50,36), root: (190,176), state 0x0, keycode 27 (keysym 0xffff, Delete), same_screen YES, XLookupString gives 1 characters: This tells you that the Delete key (keycode 27), interpreted as keysym Oxffff, which is Delete and character ^ ?. If you do an xrnodmap -pk, you should see a line resembling: 27 0xffff (Delete) If you redefine the Delete key as the Backspace key and do the same exercise (run xev and press the Delete key), you should see something like: % xmodmap -e "keysym Delete = BackSpace" % xev oo, KeyPress event, serial 13, synthetic NO, window 0x800001, root 0x8006d, sub 0x800002, time 1763440073, (44,39), root: (240,235), state 0x0, keycode 27 (keysym 0xff08, BackSpace), same_screen YES, XLookupString gives 1 characters: "^H" KeyRelease event, serial 15, synthetic NO, window 0x800001, root 0x8006d, sub 0x800002, time 1763440139, (44,39), root: (240,235), state 0x0, keycode 27 (keysym 0xff08, BackSpace), same_screen YES, XLookupString gives 1 characters: "^H" This tells you that now the Delete key (still keycode 27) is being interpreted as hexadecimal 0xff08, keysym BackSpace, and generates character "^H." xmodmap -pk should show you: 27 0xff08 (BackSpace) 292 The X Window System Administrator's Guide D.3 Related Documentation The following X manual pages may be of interest: xrdb, xmodmap, xcalc, xcalc, xprop, xev, and tWmo For more information, see X Window System User's Guide, by Valerie Quercia and Tim O'Reilly (O'Reilly & Associates, 1990). "Making Better Use of Resources," by Paul Davey, published in The X Resource, Issue 3, O'Reilly & Associates, Inc., Summer 1992. Resources and Keysym Mapptngs 293 E The Components of X Products This appendix lists the contents of various X distributions. In This Appendix: MIT Xl 1 Release 5 ............................................................................ 298 OSF/Motif .......................................................................................... 299 Sun OpenWindows ............................................................................ 300 DECWindows .................................................................................... 301 AIXWindows ...................................................................................... 302 Silicon Graphics ................................................................................. 302 A Guide to Xl 1 Libraries .................................................................... 303 Keep in mind that your pathnames may differ, but the directories bin, lib, and include should exist in some form. The names of libraries vary depending on the system--SunOS shared libraries have a .so.version or .sa.version extension, while Silicon Graphics shared libraries have a _s exten- sion. A _p extension usually means that the library has been "profiled" for performance anal- ysis. An extension such as _GO indicates it was built with a specific compiler option. The following information should help you determine what type of installation you currently have and what you would like to install. E.1 MIT Xll Release 5 To the user, Release 5 looks very similar to Release 4. Most of the new features (such as the font server, PEX, and the Xcms color system) are more visible to the X programmer and to the administrator than they are to the user. As in R4, the include files for toolkits and related files are grouped into subdirectories. (In previous MIT releases and some vendor implemen- tations, the include files were in one directory.) Table E-2. MIT X l 1R5 Files File /usr/bin/X11/X /usr/bin/X11/twm /usr/bin/X11/fs /usr/lib/X11/PEX/ /usr/ lib/X11/XKeysymD B /usr/lib/X11/XErrorDB /usr/ lib/X11/app-defaults/ /usr/lib/X11/config/ /usr/lib/X11/fon ts/ /usr/lib/X11/fs/ Description A link to a server executable. The server name usually starts with a capital X. For example, Xsun, Xcfbprnax, and Xsgi are the names for X servers. The X server will be present in com- plete installations. Tab window manager. This is the default window manager in MIT R4 and R5. The font server program. A directory of files used by PEX, the 3-D extension to X11. This directory is new to R5. A list of keysyms. This should be installed on any system using OSF/Motif clients and MIT R5 (A different version of this will file comes with MIT R5). Most Motif clients will fail to work properly without this file. A mapping of X error codes to error messages. A directory of system-wide default resources for clients. A directory of configuration files copied from the source build area. These configuration files are used by imake when build- ing X programs after the X distribution is installed. A directory of fonts for the X server. If a local X server is not present (i.e., if it is a client-only installation), this directory may be unnecessary. The font server could also read fonts from this directory over the network for a remote server. A directory of font server configuration files. 298 X Window System Administrator's Guide Motif programs include the header files with the Motif subdirectory prepended: #include The complete pathname of this file becomes/usr/include/Xll/Xm/Xm.h. Table E-3. Motif Files (Motif 1.1.x) File /usr/bin/X11/mwm /usr/bin/X11/uil /usr/bin/X11/mre / usr/ lib/ fibMrm.a /usr/ lib/ fibXm.a /usr/ lib/ libUil.a /usr/lib/X 11/XKeysymDB / usr/ lib/X11/app-defaults/Mwm /usr/lib/X11/system.mwmrc /usr/lib/X11/uid/ /usr/include/Xm/ /usr/include/Mrm/ / usr/ include/ ui l/ $HOME/.mwmrc Description The Motif Window Manager. The UIL (User Interface Language) compiler. The Motif Resource Editor (this is officially a "demo," but it is potentially quite useful--only present in version 1.x). The Motif resource manager library. The Motif toolkit library. The Motif UIL library. A database of special OSF keysyms for Motif applica- tions. System-wide default resources for mwm. The default startup file for mwm. A directory of compiled UIL files for clients. A directory of Motif toolkit include files. A directory of Motif resource manager include files. A directory of Motif UIL include files. The user-specific startup file for mwm. E.3 Sun OpenWindows The OPEN LOOK GUI is currently packaged as part of the OpenWindows environment on Sun systems. OpenWindows is laid out differently from the MIT X installation: all software is installed under/usr/openwin, as listed in Table E-4. Table E-4. OpenWindows Files (Sun4, SunOS 4.1.1) File bin/openwin bin/ demo/ etc/ include/ Description The server start-up script. A combination of X, OpenWindows, and NeWS clients. A combination of X, OpenWindows, and NeWS demo programs (including a demo xterm). Configuration information for NEWS. Header files for X and OpenWindows. 300 X Window System Administrator's Guide E.5 AlXWindows AIXWindows is quite different than the MIT distribution and it may take some work to get it to look like the MIT environment. The names and options of standard clients have been changed from what you are used to, and the layout of the software is quite different than other vendors' implementations. The current version of AIX, 3.2, is also missing some cli- ents you would expect when using an MIT distribution. The layout of libraries and include files is relatively standard. Table E-7. AIXWindows Files (RS/6000, AIX 3.2) Files /usr/bin/Xl l/X /usr/bin/X11/mwm /usr/bin/X1 l/xdt /usr/bin/X11/aixterm /usr/bin/info /usr/include/Xl l /*.h /usr/ include/Xm/*.h /usr/include/Mrm/*.h /usr/include/uil/*.h /usr/lib/lib*.a /usr/lib/X11 / /usr/lpp/info/X1 l fonts Description The AIXWindows server. The Motif window manager. The AIXWindows desktop. The AIXWindows version of xterm. The lnfoExplorer hypertext X documentation browser. AIXWindows header files. Motif 1.x header files. Standard X 11 R4 and Motif 1 .x libraries. Standard X11 R4 lib files. A directory of fonts for the InfoExplorer utility. E.6 Silicon Graphics SGI has had a decent NeWS implementation for several years, working together with the SGI Graphics Library system (GL). X functionality was added over time in a piecemeal fashion. With the release of IRIX 4.0, X 11 is an integral part of the server, and works well along with GL and NEWS. The clients are based on OSF/Motif, which comes with the OS. Table E-8. Graphics X11 Files (Indigo, IRIX 4.0) Files /usr/bin/X11/Xsgi /usr/bin/X11/4Dwm /usr/bin/X11/toolchest /usr/lib/X11/ Description A combined X11/GL/NeWS server. A mwm-like window manager. A "desktop" manager client. A directory of X 11 R4 "lib" files. 302 X Window System Administrator's Guide Table E-8. Graphics Xl I Files (Indigo, IRIX 4.0) (continued) Files Description /usr/include/Xll/ A directory of both X11 R4 and Motif 1.1 header files. /usr/lib/lib* X 11 R4 and Motif 1.1 libraries. E.7 A Guide to Xll Libraries When compiling software, you may suddenly discover that it requires a library you've never heard of. In your X 11 adventures, you may see references to the following libraries. Library libX 11 .a libXaw.a libXext.a libXt.a libXau.a libXdmcp.a libXinput.a libXmu.a liboldX.a libphigs.a libXm.a libUil.a libMrm.a libXtm.a libMXt.a libMu.a libXw.a Description Xlib Athena widget set Extensions to Xlib Toolkit Authorization XDMCP Input methods Misc Utilities Backwards compatibility library for X 10 R5 phigs Motif widgets Motif user interface language Motif resource manager Names for libXt when Motif (1.0.A) required its own version MIT Motif utilities library (sometimes found in software from MIT Athena project) HP Widgets in R3 and R4 contrib The Components of X Products 303 F Getting Xll This appendix lists where you can get the sources and patches to both Release 4 and Release 5 of X l 1. In This Appendix: Where Can I Get Xl 1R5? .................................................................. 307 Where Can I Get Patches to Xl 1R5? ................................................. 311 Where Can I Get Xl 1R4? .................................................................. 311 F Getting X11 The information in this chapter is taken from the comp.windows.x Frequently Asked Ques- tions List. We provide it here for your convenience, but we encourage you to get the latest version of the FAQ (as described in Section A.2) for more updated information. F.1 Where Can I Get X11 R5? Information about MIT's distribution of the sources on 6250bpi and QIC-24 tape and its dis- tribution of hardcopy of the documents is available from Software Center, Technology Licensing Office, Massachusetts Institute of Technology, 28 Carleton Street, Room E32-300, Cambridge MA 02142-1324, phone: 617-258-8330. You will need about 100Mb of disk space to hold all of Core and 140MB to hold the Contrib software donated by individuals and companies. PLEASE use a site that is close to you in the network. Note that the RELEASE notes are generally available separately in the same directory; the notes list changes from previous versions of X and offer a guide to the distribution. Table F-1. North America Anonymous ftp State California California Indiana Maryland Massachusetts Massachusetts Michigan Missouri Montana New Mexico New York Name gatekeeper.dec.com soda.berkeley.edu mordred.cs.purdue.edu ftp.brl.mil (good for MILNET sites) crl.dec.com export.lcs.rnit.edu (crl.dec.com is better) merit.edu wuarchive, wustl.edu ftp.cs.montana.edu pprg.eece.unm.edu azure.acsu.buffalo.edu Directory pub/Xl l/R5 pub/Xl l R5 pub/Xl l /R5 pubC11R5 pub/X11/R5 pubC5 pub/X11R5 packages/X11R5 pub/X. Vl l R5 pub/dist/X11R5 pub/Xl l R5 Address 16.1.0.2 128.32.131.179 128.10.2.2 128.63.16.158 192.58.206.2 18.24.0.12 35.1.1.42 128.252.135.4 192.31.215.202 129.24.24.10 128.205.7.6 Getting Xl I 307 Table F-1. North America Anonymous ftp (continued) State North Carolina Ohio Ontario Washington DC Washington DC Name cs.duke.edu ftp.cis.ohio-state.edu ftp.cs.utoronto.ca xl lr5-a.uu.net xl lr5-b.uu.net Directory dist/sources/X11R5 pub/X. V11R5 pubC11R5 X/R5 X/R5 Address 128.109.140.1 128.146.8.52 128.100.1.105 192.48.96.12 137.39.1.12 Table F-2. EuropeCiddle EastCustralia Anonymous ftp Country Australia Denmark United Kingdom Finland France Germany Israel Italy Netherlands Norway Norway Switzerland Name munnari.oz.au freja.diku.dk src.doc.ic.ac.uk hpb.mcc.ac.uk nic funet.fi nuri.inriafr ftp.germany.eu.net cs.huji.ac.il ghost.sm.dsi.unimi.it archive.eu.net ugle.unit.no nac.no nic.switch.ch Directory X.Vl l/R5 pubC11R5 graphics/X. V11R5 pubC11 r5 pubC11/R5 X/X11R5 pubC11/X11R5 pubC11R5 pubC11R5 windows/X/R5 pubC11R5 pubC11R5 softwareC11R5 IP Address 128.250.1.21 129.142.96.1 146.169.3.7 130.88.200.7 128.214.6.100 128.93.1.26 192.76.144.129 132.65.6.5 149.132.2.1 192.16.202.1 129.241.1.97 129.240.2.40 130.59.1.40 Table F-3. Japan Anonymous ftp Region Kanagawa Kwansai Kyushu TISN Tokyo Tokyo Name sh.wide.ad.jp ftp.ics.osaka-u.ac.jp wnoc-fuk.wide.ad.jp utsun.s.u-tokyo.ac.jp kerr.iwanami.co.jp scslwide.sony.co.jp Directory X11R5 X11R5 X11R5 X11R5 X11R5 pub/X11R5 IP Address 133.4.11.11 133.1.12.30 133.4.14.3 133.11.11.11 133.235.128.1 133.138.199.1 308 X Window System Administrator's Guide Table F-4. UUCP Name uunet decwrl osu-cis WJanon utai hp4nl Comment for UUNET customers existing neighbors only (not online until early September) (host: watjo.swp.wj.com) Modem: Telebit TB2500 (PEP, V.32, etc) Systems or L.sys suggested/approximate entry: WJanon Any ACU 19200 1-408-435-0240 .... \ login: WJanon existing neighbors only Netherlands only Directory -/X/R5 -/pub/X l l /R5 -/X. V11 R5 -/X/X11R5/ -/ftp/pub/X11R5 -uucp/pub/windows/X/R5 Table F-5. Other File Transfer Methods Method NFS AFS NIFFP (hhcp, cpf, fcp .... ) anon k-TAM ACSNet Region Missouri Pennsylvania United Kingdom United Kingdom Australia Comments wuarchive, wustl.edu CrchiveCackagesC11R5 128.252.135.4 mount point:/archive /afs/ grand.c entral.org/pub/X11R5 uk.ac.ic.doc.src 00000510200001 user "guest" 000005102000 (Janet) X.V11R5 146.169.3.7 (Intemet) 204334504108 (IXI) munnari.oz (fetchfile) X.V1 l/R5 Please fetch only one file at a time, after check- ing that a copy is not available at a closer site. [9/2/91; updated for contrib 10/91 ] Anyone in Europe can get a copy of the MIT X.V11R5 distribution, including the core and contributed software and all official patches, free of charge. The only requirement is to agree to return the tapes, or equivalent new tapes. Only QIC and TK format cartridges can be pro- vided. Contact: Jamie Watson, Adasoft AG, Nesslerenweg 104, 3084 Wabem, Switzerland. Tel: +41 31 961.35.70 or +41 62 61.41.21; Fax: +41 62 61.41.30; jw@adasoft.ch. Getting X l I 309 UK sites can obtain X 11 through the UKUUG Software Distribution Service, from the Depart- ment of Computing, Imperial College, London, in several tape formats. You may also obtain the source via Janet (and therefore PSS) using Niftp (Host: uk.ac.ic.doc.src Name: guest Password: your_email_address). Queries should be directed to Lee McLoughlin, 071-589-5111#5037, or to info-server@doc.ic.ac.uk or ukuug-soft@uk.ac.ic.doc (send a Sub- ject line of "wanted". Also offered are copies of comp.sources.x, the export.lcs.mit.edu con- trib and doc areas and most other announced freely distributable packages. X 11 R5 and X 11 R4 source along with X 11 R5 contrib code, prebuilt X binaries for major plat- forms, and source code examples from O'Reilly's books is available on an ISO-9660-format CD-ROM from O'Reilly & Associates. [as of 3/92]. X l 1R5 source is available on ISO-9660-format CD-ROM for members of the Japan Unix Society from Hiroaki Obata, obata@jrd.dec.com. X 11R5 source along with GNU source, the comp.sources.x archives, and SPARC binaries is available on an ISO-9660-format CD-ROM from PDQ Software, 510-947-5996 (or Robert A. B ruce, rab@ sprite. Berkeley.EDU). X l 1 R5 source is available from Automata Design Associates, + 1 215-646-4894. Various users' groups (e.g., SUG) offer X sources cheaply, typically on CD-ROM. Source for the Andrew User Interface System 5.1 and binaries for common systems are avail- able on CD-ROM. Information: info-andrew-requests@andrew.cmu.edu, 412-268-6710, fax 412-621-8081. Binaries for X11RS, with shared libX11 and libXmu, for A/UX 2.0.1 are now available from wuarchive.wustl.edu:/archive/systems/aux/XllRS. Patches for XIIR5 compiled with gcc (but not shared libraries) are also available. [John L. Coolidge (coolidge@cs.uiuc.edu, 10/91)] Binaries by Rich Kaul (kaul@ee.eng.ohio-state.edu) for the Sun386i running SunOS 4.0.2 are available on dsinc.dsi.com (please only after-hours USA EST). Binaries for the Sun386i are available from compaq.com (131.168.249.254) in pub/sun-386i/sources and from vernam.cs.uwm.edu (129.89.9.117). A binary tree for the Next by Douglas Scott (doug@foxtrot.ccmrc.ucsb.edu) is on fox- trot.ccmrc.ucsb.edu; it is missing the server, though. Binaries for the Sun386i are in vernam.cs.uwm.edu:/sun386i. Binaries for the HP-PA are on hpcvaaz.cv.hp.com (15.255.72.15). Also, Binaries are available from Unipalm (+44 954 211797, xtech@unipalm.co.uk), proba- bly for the Sun platforms. 310 X Window System Administrator's Guide F.2 Where Can I Get Patches to X11R5? The release of new public patches by the MIT X Consortium is announced in the comp.win- dows.x.announce newsgroup. Patches themselves are available via ftp from export and from other sites from which X 11 is available. They are now also distributed through the newsgroup comp.sources.x. Some source re-sellers may be including patches in their source distributions of X11. People without ftp access can use the xstuff mail server. It now has 17 patches for XI 1R5 [8/92]. Send to xstuff@expo.lcs.mit.edu the Subject line: send fixes # where # is the name of the patch and is usually just the number of the patch. Here are a few complications: 1. Fix 5 is in four parts; you need to request "5a", "5b", "5c" and "5d" separately 2. The file sunGX.uu, which was part of an earlier patch, was re-released with patch 7 3. Fix 8 is in two parts: "8a" and "8b" 4. Fix 13 is in three parts: "13a", "13b", and "13c" 5. Fix 16 is in two parts: "16a" and "16b" F.3 Where Can I Get X11 R4? Integrated Computer Solutions, Inc., ships X11R4 on half-inch, quarter-inch, and TK50 for- mats. Call 617-621-0060 for ordering information. The Free Software Foundation (617-876-3296) sells XllR4 on half-inch tapes and on QIC-24 cartridges. Yaser Doleh (doleh@math-cs.kent.EDU; P.O. Box 1301, Kent, OH 44240) is making X 11 R4 available on HP format tapes, 16 track, and Sun cartridges. [2/90] European sites can obtain a free X11R4 distribution from Jamie Watson, who may be reached at chx400!pan!jw or jw@pan.uu.ch. [ 10/90] Non Standard Logics (+33 (1) 43 36 77 50; requests@nsl.fr) makes source available. IXI Limited (+44 223 462 131) is selling X11 R4 source on quarter-inch cartridge formats and on 5.25" and 3.5" floppy, with other formats available on request. [IXI, 2/90] Virtual Technologies (703-430-9247) provides the entire X11R4 compressed source release on a single QIC-24 quarter-inch cartridge and also on 1.2 meg or 1.44 meg floppies upon request. [Conor Cahill (cpcahil@virtech.uu.net) 2/90] Young Minds (714-335-1350) makes the R4 and GNU distributions available on a full-text- indexed CD-ROM. Getting X l I 311 [Note that some distributions are media-only and do not include docs.] X 11 R4 is ftp-able from export.lcs.mit.edu; these sites are preferable, and Location (1) West USA Central USA (2) Central USA Southeast USA (3) Northeast USA (4) UK Janet UK niftp (5) Australia Name gatekeeper.dec.corn mordred.cs.purdue.edu giza.cis.ohio-state.edu uunet.uu.net crl.dec.com src.doc.ic.ac.uk uk.ac.ic.doc.src munnari.oz.au Address 16.1.0.2 128.10.2.2 128.146.8.61 192.48.96.2 192.58.206.2 129.31.81.36 128.250.1.21 are more direct: Directory pubC11/R4 pubC11/R4 pub/X. V11R4 X/R4 pubC11/R4 X.VllR4 X.Vll/R4 The giza.cis.ohio-state.edu site, in particular, is known to have much of the contrib stuff that can be found on export. The release is available to DEC Easynet sites as CRL::"/pub/X1 l/R4". Sites in Australia may contact this address: ftp.Adelaide.EDU.AU [129.127.40.3] and check the directory pub/X/R4. The machine shadows export and archives comp.sources.x. (Mark Prior, mrp@ucs.adelaide.edu.au, 5/90) Note: a much more complete list is distributed regularly by Dan Heller (argv@sun.com) as part of the introductory postings to comp.sources.x. A set of XIlR4 binaries built by Tom Roell (roell@informatik.tu-muenchen.de) for the 386/ix will available from export.lcs.mit.edu in /contrib and in /pub/i386/XllR4 from 131.159.8.35 in Europe. Stephen Hite (shite@sinkhole.unf.edu) can also distribute to folks without ftp facilities via disks sent SASE; contact him for USmail and shipping details. [12/90] In addition, the binaries are available via uucp from szebra [1-408-739-1520, TB+ (PEP); ogin:nuucp sword:nuucp] in/usr2/xbbs/bbs/x. In addition, the source is on zok in/usr- X/i386.R4server/. [2/91] In addition, if you are in the U.S., the latest SVR4 binary (April 15), patches, and fonts are available on piggy.ucsb.edu (128.111.72.50) in the directory /pub/X386, same filenames as above. (Please use after 6pm Pacific, as these are large files.) [5/91] A set of HP 9000/800 binaries is available on hpcvaaz.cv.hp.com (15.255.72.15) as -ftp/pub/MitX 11R4/libs.xS00.Z. [2/91 ] A set of XllR4 binaries for the NeXT 2.x have been made available by Howie Kaye on cunixf.cc.columbia.edu A set of binaries by John Coolidge (coolidge@cs.uiuc.edu) for the Mac running A/UX 2.0 is available from wuarchive.wustl.edu in the file (/archive/systems/aux/X11R4/Xupdate2.tar .Z). Also in X11R4/diffs is a set of patches for making X11R4 with shared libraries with mkshlib. A complete distribution of SCO X11R4 binaries by Baruch Cochavy (blue@techunix.techn- ion.ac.il) can be found on uunet. The server is Roell's X386 1. lb, compiled for ET4000 based SVGA boards. 312 X Window System Administrator's Guide G Error Messages This appendix lists error messages that you might get when running X cli- ents. We not only list errors from X programs but also UNIX errors that you often encounter when running or compiling X programs. In This Appendix" X Errors ............................................................................................. 315 UNIX Errors ........................................................................................ 318 Compilation Errors ............................................................................. 320 G Error Messages This appendix lists error messages that you might get when running X clients. This appendix is broken up into the following categories: X Errors Errors that you may get from X clients. UNIX Errors Errors that you may get when running X clients, but which reflect problems more closely associated with UNIX. Compilation Errors Errors that you may get when compiling programs under UNIX. G.1 X Errors Can't Open display or Unable to open display There is a problem with the DISPLAY variable or with the display specified using the -dis- play option. The DISPLAY variable may not be set properly, or the specified host may be unknown. The host may also not have access to the specified display. Correct the setting of the DISPLAY variable, or extend server access as appropriate using either xhost or xauth. See Section 2.3.1 for more information on setting the DISPLAY variable, or Chapter 4 for infor- mation on server access control. (This particular error is actually generated by the application, so it may not be worded exactly like this. "Can't open display" is the wording generated by Xtobased applications.) Unknown preprocessor directive or n: undefined control You might get this error from xrdb if you used the "#" character to comment out a line in a resource file. For a resource file, replace the "#" with a "!", or use a dummy resource entry. See Section D. 1.3 for more information. Error Messages 315 Xlib: connection to "hostname:O.O" refused by server Xlib: Client is not authorized to connect to server Error: Can't Open display The client does not have permission to connect to the specified server. Either host-based or user-based access control is in effect. You need to add the host to the xhost list for that server, or you need to copy the code to your .Xauthority file on this host using xauth, or (if you are using SUN-DES-1 security) you need to be added to the xhost list on the server. See Chapter 4 for more information. Warning: Widget class nnn version mismatch (recompilation needed): widget 11004 vs. intrinsics 11003. You are probably mixing MIT clients with Sun OpenWindows libraries or vice versa. You should specify the right libraries for the client: % (setenv LD_LIBRARY_PATH /usr/openwin/lib; ON-client) % (setenv LD_LIBRARY_PATH /usr/lib; MIT-c1ient) Fatal server bug! no screens found. You might get this error when starting a Sun X server, where you can use the -dev option to specify a different device (such as -dev/dev/cgfourO -dev/dev/bwtwol). A device listed with the -dev option is incorrect, or the device may be missing from/dev. mwm: Invalid accelerator specification on line n of specification string mwm: Invalid accelerator specification on line m of configuration file The Motif Window Manager rnwrn uses function keys which your server does not have defined. You should define the function key using xmodmap, or alter your .mwmrc to use a different key. unknown keysym osfDown ... Motif-based applications (such as mwm) require the proper installation of the file /usr/lib/Xll/XKeysymDB. This file comes with most Motif distributions and is also present in X11RS. Error Binding TCP socket You may get this error when starting the X server on a workstation display. The server will try to create the socket in/tmp/,Y11-unixC If the/tmp directory is not writable, the X server will fail. Error Messages 317 There are stopped jobs You are trying to exit a shell without properly exiting or killing all jobs started in that shell. You should properly quit the jobs before exiting the shell--use the jobs command for a list of your stopped jobs. command: Command not found. You may get this error if the requested command isn't in your search path, or if it doesn't exist. Make sure the command is installed and make sure its path is in your search path. command:Permission denied. You may get this error if the command is in your search path but you don't have execute per- mission for it. Host is unreachable no network route is known to that host You may get this error when there is a routing problem--the gateway is probably down or misconfigured. Connection timed out You tried to connect to a host that is currently down or otherwise unreachable. Id.so: libX11 .so.4: not found You might get this message if you are running SunOS. Either the shared library cache is out of date, the shared library is missing, or the shared library is not in your LD_LIBRARY_PATH. You should either set the LD_LIBRARY_PATtt environment variable to the appropriate value, run ldconJig to update the library cache, or install the missing library. See Section 8.4.2 for more information. No more processes Your host has reached its process limit. You should increase the number of processes that the host can handle at once; see Section 7.7.1 for more information. Sorry, pid ... was killed due to lack of swap space Your host has run out of swap space. You should increase the amount swap space on your host; see Section 7.7.3 for more information. Error Messages 319 ::(double colon), in Makefiles, 225 : (colon), in resource definitions, 281 ! (exclamation point), in resource definitions, 282 in resource files, 287 in Xaccess file, 56 # (hash sign), 219 in resource def'mitions, 287 in RGB specification, 145 used to comment out lines, 315 % (percent sign), in Xaccess file, 59 * (asterisk), and specifying fonts, 108 in resource definitions, 281-283 in Xaccess file, 56-57 /**/(null comment), 219 ? (question mark), in resource definitions, 283 @@ (imake syntax), 220 \ (backslash), in resource defini- tions, 282 A access control server, 73-93; host-based (see host-based access control), ; reasons for, 73; user-based (see user-based access control), ; X terminals, 83, 175; xauth vs. xhost, 82-83 xdm, 47 .ad files, (see application defaults) additional style, font name field, 102 Index Adobe fonts, 101 converting to F3, 113 converting to X11/NeWS for- mat, 126 AIX, 188 chown command, 211 installing font server on, 133 installing xdm on, 70 AIXWindows, 8, 187 components of, 302 fonts; example, 121-122 InfoExplorer client, 117 aliases for fonts, 108-109, 114; DECWindows, 119; OpenWindows, 124 for hostnames, 138 for RGB color, 145 for Xcms color, 149 alternate-servers (font server), 129, 134 anonymous ftp, (see ftp com- mand) AnswerBook, 186 app-defaults directory, (see application defaults) Apple Macintosh computers, Communications Toolbox, 275-277 MacTCP, 275-277 UNIX and, 275 X clients and, 271,275 X servers and, 271,275 application defaults, 258,285 ar command, 199, 207 arch command, 192 Archie, 248-250 help command, 249 mail server, 250 prog command, 249 servers, 248 Index 321 C C compiler, (see cc) C preprocessor, (see cpp) .cal00 files, ! 53 cache-size (font server), 128 CAPS LOCK key, 159 disabling, 290 switching with Control, 291 cat, Bill, 73 catalogue (font server), 129, 136 catalogue-list (font server), 129, 136 cc, debugging, 199 -E flag, 228 -g flag, 199 -O flag, 198 optimization, 198 -temp= flag, 200 -v flag, 228 .cf files, 222 character cell fonts, 102-103 character set, font name field, 102 chkconfig command, 133 chkey command. 86-87 error messages, 93 chmod command, 97 chooser client, 53, 55, 57-59 indirect queries and, 57 resources, 57, 60 uses for, 59 chown command, 96 AIX, 211 -R flag, 202 recursive, 202 chroot command, 167, 171 CIE, 147 class names, 283-284 clean, make target, 224 client-limit (font server), 129, 135 client-only distribution, 189 clients, 3, 13 application defaults, 285 chooser, 55, 57-59 cm, 118; font problems, 123-125 command-line options, 20-23; -bg, 23; -display, 27-29, 36; -fg, 23; -fn, 20, 103; -geometry, 20-22; -iconic, 26; -name, 283-284; -rv, 23; -server (for font server cli- ents), 134; -xrm, 286 crtca, 153 customizing, 20 DOS-based, 272 dxcalendar, 117 fsinfo, 134 fslsfonts, 135 getbdf, 112 InfoExplorer, 117, 12 l Macintosh computers and, 271, 275 rare, 145-146 props, 145-146 public domain, 247-268; compiling, 255-268; patching, 259-264 remote; setting DISPLAY for, 36; starting, 34-36 resize, 31-33 resources, 6 running locally on X terminals, 161 xarchie, 248, 251-259 xcalc, 14 xclock, 14, 16 xcmsdb, 152-153 xcoloredit, 145-146 xcolors, 144 xconsole, 26, 62 xdpyinfo, 158 xdvi, 115 xev, 291-293 xfd, 103, 108, 115 xfontsel, 20, 104 xhost, 28, 35-36, 74-77, 93; SUN-DES-I and, 85, 88-90 xinit, 81-82 xkeycaps, 264-268, 291 xloadimage, 96 xlsfonts, 20, 103, 108 xmessage, 33 xmodmap, 264, 290-293 xpostit, 14, 249 xrdb, 24-25, 60-61,64, 285, 287-288 xrolodex, 247 xrsh, 79 xsccd, 153 dex 323 clients (cont'd) xset, 105-106, 114-116, 124, 137 xsetroot, 25 xterm, 14, 16, 93-94, 106, 144 xtex, 115-117 xtici, 150-151 xtrek, 138 xwebster, 259-264 (see also commercial clients.) clone-self (font server), 129, 135 cm client, 118 font problems, 123-125 CMW (Compartmented Mode Workstations), 98 col command, 242 color, 143-153 aliases, 145 defining resources for, 145 defining; RGB system, 146-147; Xcms, 150-151 device-independent; (see Xcms) editors, 145-146 getting list of, 23 hexadecimal color values, 145; converting to decimal, 146 listing, 144 monitors, 158 RGB system, 143-147; color names, 144-145; defining colors, 146-147; fixing corrupted database, 147; hexadecimal color values, 148 specifying, 23 Xcms, 144, 147-153; client database, 148; color names, 148-151; color spaces, 147-148, 150; database example, 151; DCC, 152-153; def'ming colors, 150-151; device profiles, 152-153; measuring colors, 153; specifying colors, 148; XCMSDB, 149; Xcms.txt file, 148-150 color clients, mre, 145 props, 145 xcoloredit, 145 xcolors, 144 xtici, 150 color database, alternates, 147 example, 151 fixing, 147 RGB, 146 Xcms, 148-150 XCMSDB, 149 color editors, 150-151 color guns, 143 color monitors, 143 color spaces, 147-148, 150 listing of, 148 colorimeters, 153 commands, ar, 199 arch, 192 archie, 248 arp, 169 bc, 81, 146, 243 bdftohds, 171 bdftopcf, 112 bdftosnf, 112, 114, 125, 170 bldfamily, 107, 126 chkconfig, 133 chkey, 86-87, 93 chmod, 97 chown, 96 chroot, 167, 171 col, 242 compress, 112 convertfont, 112, 125-126 cpp, 216-218 crypt, 86 date, 81 dmesg, 193 domainname, 85 dxfc, 112 exportfs, 172, 201,239 fstobdf, 112, 136 ftp, 234-235, 251 imake, 214 jobs, 319 keylogin, 90 ksh, 81 last, 214 ldconfig, 200 ldf, 111 lndir, 197 lpr, 242 mach, 192 make, 197 makeafb, 113, 126 man, 213,242 mkfile, 180 324 X Window System Administrator's Guide commands (cont'd) mkfontdir, 107, 114, 116, 139; fonts.scale, 107 newkey, 86-87 nm, 226 nroff, 242 nslookup, 241 openwin, 37 patch, 195,238 perl, 81 pstat, 180 ranlib, 199 rexec, 173 rgb, 146 dogin, 34 rsh, 35-36, 79, 81 screendump, 96 screenload, 96 setenv, 27-28, 30, 134, 149, 151,164, 199,204,211,213, 317 showrgb, 23, 144 snftobdf, 112 startx, 37-38 strings, 192, 229 swapon, 180-181 tail, 197 tar, 238,252 tbl, 242 telnet, 164, 248 trace, 286 truss, 286 tset, 31 uname, 192 uncompress, 238,242 unshar, 262 uudecode, 195,236, 238 uuencode, 195,238 wait, 26 X, 16, 38, 53 xauth, 36, 79-83, 93; SUN-DES-1 and, 89; using with xinit, 81-82 xinit, 16, 25, 37-38 xmkmf, 214-215,256, 266 xrsh, 36, 79 ypbind, 87 ypmatch, 85-86, 240 ypwhich, 86, 240 zcat, 238,242, 252 comments, ! (exclamation point), 282 # (hash sign), 128,219 /**/(null comment), 219 in font server configuration file, 128 in imake files, 219 in resource definitions, 282, 287 in Xservers file, 55 XCOMM, 220 commercial clients, FrameMaker, 65, 159 zmail, 33 Communications Toolbox (Mac- intosh computers), 276-277 Compat.list file, 109, 126 compiling sources, 255-268 porting hints, 226-230 compress command, I 12 compressed files, 236, 238,242 fonts and, 107, 112-I 13 CompuServe, 235 comp.windows.x, 157, 187, 189, 233,250 FAQ, 234-237, 250 eonfig file (font server), 128-130, 139 configuration files, app-defaults files, 258 .cshrc, 29-30, 33-34, 36 /etc/hosts.equiv, 81; Secure RPC and, 86, 90 /etc/syslog.conf, 169 /etc/Xn.hosts, 74-75, 82 for font server, 128-131 imake, 222 .login, 33-34 on remote system, 35-36 .profile, 29-30, 36 .rhosts, 35, 81; Secure RPC and, 86, 90 shell environment, 27-36 startup script, 25-26 syslog, 169 system.twmrc, 18 twm, 15, 18-19 .twmrc, 15, 19 user environment, 14 X session, 14 X terminals, 161,175-178 .Xdefaults, 286-287 .Xdefaults-hostname, 285 xdm, 46-66; installing, 206; rereading, 52, 55, 59, 67-68; Xaccess, 55-59, 164, 174; Index 325 configuration files, xdm (cont'd) xdm-config, 51-52, 78, 84, 95; Xresources, 60-62; Xservers, 48, 53-55, 65, 174; Xsession, 63-65 xinit; installing, 206 .xinitrc, 25-26, 37-38, 90 .xinitrc vs..xsession, 39 .Xmodmap, 291 .Xresources, 15, 24-25,286 .xserverrc, 38, 82 .xsession, 14, 25-26, 37 console, security, 94-96 console windows, 94-96 xdm and, 95-96 contrib/, 191 controlling process, 26 conversion fonts, 112-113; OpenWindows, 125-126 convertfont command, 112, 125 -b flag, 126 -d flag, 125 -s flag, 125 -x flag, 125 core, 191 Courier, 101 Clap, 216-218 comments in, 219, 315 #define command, 218 errors, 315 #ifdef command, 218 #ifndef command, 218 macro concatenation and, 221 resource files and, 287 standalone execution, 228 symbols; searching for, 228 -v flag, 228 cron daemon, 97 crtca client, 153 crylat command, 86 .cshrc file, 29, 33-34, 36 CTRL key, 159 D daemons, bootpd, 165 bootp; errors, 169 cron, 97 fs; (see font server) ftpd, 234 inetd, 88, 167-168; errors, 169 keyserv, 93 named, 241 rarpd, 165 rpc.ypupdated, 87 syslog, 129-130, 169 fftpd, 167; errors, 169 xdm; (see xdm) Data Encryption Standard, SUN- DES- 1, 84 XDM-AUTHORIZATION- 1, 83 support for, 86 database, (see color database) date command, 81 dbm format, 146 DCC, 152-153 .dcc files, 153 Dead Meat, 138 decipoints, 129 DECnet, 162 connecting via, 28 font server and, 136 DECWindows, 8, 187 components of, 301-302 dxcalendar client, 117 fonts, 111-112, 117-121 DefaultCCOptions build flag, 210-211 DefaultFontPath build flag, 117, 212 default-point-size (font server), 129 default-resolution (font server), 129 #define command (cpp), 218 delegates, 129 depend, make target, 215,224 depth, 159, 161 DES, 98, 207 (see Data Encryption Standard) Desqview/X, 271-272 /dev/console, 95 /dev/fb, 96-97 Device Color Characterization, (see DCC) device profiles, Xcms, 152-153 device-independent color, (see Xcms) direct queries, 55-57 326 X Window System Administrator's Guide X terminals and, 173 direct queries (cont'd) disk space, X installation and, 191,198-200 X terminals and, 170-171 diskless workstations, 162 fonts for, 127 display, problems with, 315, 317 display classes, 52, 55, 65-66 example, 65-66 finding, 65 DISPLAY environment variable, 164 name server problems, 28 problems with, 28-29, 315 setting, 27-29; remote clients, 34, 36 using IP address, 28 -display option, 36 problems with, 315 distfile, (see rdist program) dmesg command, 193 DNS, adding a hostname, 240-241 and nslookup, 241 testing, 241 documentation, printing, 242-243 Domain Name Service, (see DNS) domainname command, 85 DOS, X clients and, 271 X servers and, 271-275; " advantages and disadvan- tages, 271; requirements, 272 dot pitch, 158 dxcalendar client, 117 dxfc command, 112 E editing colors, 145-146 encoding, font name field, 102 encryption codes, server access control and, 83-84 environment variables, 29 DISPLAY, 27-29, 164 FONTSERVER, 134 LD_LIBRARY_PATH, 30 MANPATH, 213 OPENWINHOME, 30 PATH, 25, 29 SHELL, 33 showing, 27 TERM, 31 TERMCAP, 32 TMPDIR, 199 XAPPLRESDIR, 258,286 XCMSDB, 149, 151 XENVIRONMENT, 258, 285 XFILESEARCHPATH, 286 XRSH_AUTH_TYPE, 79 XUSERFILESEARCHPATH, 286 error messages, 315-320 auth_create: Bad file number, 93 Binding TCP socket: Address already in use, 131 Cannot establish any listening sockets, 131 cannot open, 35 can't communicate with ypserv 93 Can't find include file, 320 Can't lock authorization file, 64 Can't Open display, 36, 315, 317 Can't open error file /usr/lib/X 11/fs/fs-errors, 135 cat: ./Compat.list: No such file or directory, 126 Client is not authorized to con- nect to Server, 34, 75 Color name ... is not defined in server database, 145 Command not found, 29, 319 CONFIG: can't open configura- tion file .... 135 connection refused by server, 34 Connection timed out, 319 Could not set principal's secret key, 93 Current serial number in output stream, 316 Duplicate font names .... 116 (Encoding: unknown), 126 Fatal server bug! no screens found, 317 Fatal server error!, 131 Host is unreachable, 319 key contains odd number of or non-hex characters, 93 ld.so: libX11 .so.4: not found, 319 Index 327 error messages (cont'd) local resource allocation failure, 93 machine is down or not running rpc.ypupdated, 93 Major opcode of failed request, 316 make: Fatal error in reader: ... Unexpected end of line seen, 320 Maybe the keyserver is down?, 93 Minor opcode of failed request, 316 mkfontdir; failed to create directory in, 116 must be on local machine to add or remove hosts, 75 mwm; Invalid accelerator spec- ification on line n of specifi- cation string, 317 No home directory, 64 No more processes, 319 No such file or directory, 35 Not Iogin shell, 318 pattern ... unmatched, 136 Permission denied, 35, 318 Resource id in failed request, 316 reversed (or previously applied) patch detected!, 320 Serial number of failed request, 316 Sorry, pid ... was killed due to lack of swap space, 319 Stopped, 36 Terminal type xterm unknown, 318 There are stopped jobs, 319 unable to open server, 134-135 unable to update NIS database, 93 undefined control, 288,320 Undefined symbol, 320 , 93 unknown keysym osfDown, 317 Unknown preprocessor direc- tive, 288,315,320 Warning: Cannot convert string to type FontStruct, 115, 316 warning: table of contents for archive is out of date, rerun ranlib(1), 320 widget 11004 vs. intrinsics 11003, 317 X Error of failed request: Bad- Value, 116, 137, 172, 316 X Toolkit Warning: Cannot allocate colormap entry, 147 X Toolkit Warning: Cannot con- vert string ... to type FontList, using fixed font, 117 Xlib: Client is not authorized to connect to Server, 317 Xlib: connection refused by server, 317 XView warning: Cannot load font .... 118 error-file (font server), 129-130, 135 errors, 169 compiling, 226 generated by font server, 129-130, 135 generated by xdm, 46-47, 49-51, 53, 63-64 generated by .xsession files, 39, 47 linking, 226 undefined functions, 226 undefined symbols, 226 (see also error messages.) /etc/bootptab, 163, 165 /etc/ethers, 165, 169, 242 /etc/exports, 172, 201,239 /etc/fbtab, 97 /etc/fstab, 172, 180 /etc/hosts, 239-240 /etc/hosts.equiv, 35, 81 Secure RPC and, 86, 90 /etc/inetd.conf, 167, 88 rereading, 168 /etc/inittab, 69-70 /etc/motd, 33, 168, 192 /etc/named.boot, 241 /etc/named.pid, 241 /etc/passwd, 168 /etc/publickey, 85 /etc/rc.local, 69-70, 88, 131 /etc/rc.local file, 53 /etc/rc.tcpip, 70, 133 /etc/resolv.conf, 170 328 X Window System Administrator's Guide fslsfonts, 135 fstobdf, 112, 136 font tape, 170 fonts, 101-140 adding, 114-126; multiple directories, 115 AIXWindows, 121 aliases, 108-109, 114; DECWindows, 119; OpenWindows, 124 average width, 102 BDF format, 111 bitmap, 110 breaking into subdirectories, 115 browsing through, 104 byte order, 111,170-171 caching, 115, 128 character set, 102 CharCell, 102-103 components of font name, 102 converting between formats, 112-113, 118 converting from DECWindows, 118-121 DECWindows, 111 disk space, 113, 170-171 diskless workstations, 127 displaying characteristics of, 103 downloading; using NFS, 172; using TFTP, 171-172 encoding, 102 F3, 111,125 families, 101 filename length restrictions, 107 font conventions, xx font path, 105-106; default, 212 font server, 127-139; alternate-servers, 129, 134; cache size, 128; caching, 128; catalogue, 129, 136; catalogue-list, 129, 136; client-limit, 129, 135; clone-self, 129, 135; default-point-size, 129; default-resolution, 129; error-file, 129-130, 135; example use, 138-139; font path, 136-137; hostname aliases, 138; installing, 130-133; name syntax, 133-134; port, 130; starting, 131, 139; testing, 131; trusted-clients, 130, 136; use-syslog, 129-130 fonts.dir file, 106-107, 109, 116; creating, 107, 114, 139 fonts.scale file, 107-108 formats, 111-112; converting between, 112-113; font server and, 127 foundry, 101 horizontal resolution, 102; font server and, 129 inability to access, 316 legalities, 113, 136 linking, 170 listing, 20 mono-spaced, 103 obtaining list of, 103 OpenWindows, 107; Compat.list file, 126; converting, 125-126; example, 123; rebuilding Families.list file, 126; Synonyms.list file, 126 outline, 110 over the network, 127 PCF format, 111,170 pixel size, 102 point size, 102, 129 PostScript, 111 pre-scaled NEWS, 125 proportional, 102 scalable, 110 selecting with xfontsel, 104 set width, 102 slant, 101 SNF format, 111,170 spacing, 102 specifying, 20, 103 Speedo, 105, 110-111; fonts.scale and, 107 style, 102 using in xterm windows, 103 vertical resolution, 102; font server and, 129 weight, 101 330 X Window System Administrator's Guide fonts (cont'd) wildcards, 103, 108 X terminals, 127, 170-172; installing, 163 X11/NeWS, 111,125 fonts.alias file, 108-109, 114 adding to, 124 fonts.dir file, 106-107, 109, 116 creating, 114, 139 errors, 316 FONTSERVER environment vari- able, 134 fonts.scale file, 107-108 foreground color, 281 specifying, 23, 144 foreground processes, 26 foundry, font name field, 101 framebuffers, 96-97 FrameMaker, 65, 159 Frequently Asked Questions List, (see FAQ) fs daemon, (see font server) fsinfo client, 134 -server option, 134 fslsfonts client, 135 fstobdfcommand, 112, 136 FTP, (see ftp command) ftp command, 234-235, 251 ftpd daemon, 234 ftpmail, 235-236 functions, undefined, 226 G gateway, problems with, 319 generic.cf, 208 -geometry option, 20-22 getbdf client, 112, 118 getty program, 37, 44 GiveConsole, 47, 95 GrabKeyboard protocol request, 93 graphics hardware, finding list of supported, 193 grayscale, 65, 158 GUIs, 4 and X, 4 Athena widgets, 7 OPEN LOOK, 7 OSF/Motif, 7 gwm window manager, 19 H hardware addresses, 165,242 HasLargeTmp build flag, 199, 207 HasSecureRPC build flag, 86 HasXdmAuth build flag, 84, 207 HDS X terminals, 171 header files, 215 missing, 226 hexadecimal color values, 145 converting to decimal, 146 new format, 148 old format, 145 Xcms and, 148 hexadecimal conversions. 243 horizontal resolution, font name field, 102 host-based access control, 74-77 /etc/Xn.hosts, 74-75 overriding user-based access control, 82-83, 175 PC X servers and. 83 problems with, 76-77 X terminals and, 74-76, 79, 83, 175 xhost client, 75-77 hostname, finding with nslookup, 241 hosts, access to font server. 130, 136 adding to hosts database, 239-241 aliasing, 138 alternate font servers, 129, 134 denying access to; (see host- based access control) in arp table, 169 increasing number of ptys, 179 increasing number of users. 179 increasing processes, 178 increasing swap space, 180-181 rebuilding kemel, 179 reconfiguring for X terminals, 178-181 remote; accessing fonts on, 127 Human Designed Systems, (see HDS X terminals) dex 331 J jobs command, 319 kbd_mode command, 67 key symbols, (see keysyms) keyboards, 159-160 CAPS LOCK key, 159 CTRL key, 159 resetting, 67 securing, 93 keylogin command, 90 keymap tables, 290 keys, Backspace, 290 CAPS LOCK, 290-291 Control, 291 Delete, 290 mapping, 290-293 translation tables and, 288-290 keyserv daemon, 93 keysyms, 6, 290-293 adding/removing, 291 checking with xev, 292 disabling CAPS LOCK, 290 mapping, 290 mapping Backspace to Delete, 290 switching Control and CAPS LOCK, 291 ksh command, 81 last command, 214 Idconfig command, 200 Idf command, 111 LD LIBRARY PATH environ- _ -- ment variable, 30, 317 MIT X and, 317 OpenWindows and, 317 libraries, 4, 200, 216 building with ar, 199 errors, 320 for X, 303 (see also shared libraries.) link trees, 196-197 little endian, 111, 170 lndir command, 196-197 local clients,. X terminals and, 161 log files, font server errors, 129-130, 135 xdm errors, 49-51 Iogin, problems logging in with xdm, 49-51 remote, 34-36 login box, configuring, 60-62 Iogin program, 44 Iogin shell, 33-34 xterm and, 33 .Iogin file, 33-34 loose bindings, 52, 282 lpr command, 242 Lucida, 101 M mach command, 192 Macintosh computers, Commu- nications Toolbox, 275-277 MacTCP, 275-277 UNIX and, 275 X clients and, 271,275 X servers and, 271,275 macros, Xaccess file and, 59 MacTCP, 276-277 magic cookie, 77-83, 98 copying to a remote machine, 79 generating manually, 81-82 using with xdm, 78-79 using with xinit, 81-82 mail servers, archie, 250 bifftp, 237 ftpmail, 235-236 xstuff, 237-238 mailing lists, xpert, 233,250 make program, 216-217, 256-258 double colon syntax, 225 -k flag, 225 -n flag, 225 tabs and, 222 targets; clean, 224; depend, 224; Everything, 225; includes, 224; install, 198,225; install.man, 198,225; Makefiles, 224; Wodd, 197, 224 Index 333 O olvwm window manager, 19 olwm window manager, 7, 19 Open Desktop, 8, 185 scologin, 68 xdm, 43 OPEN LOOK GUI. 7 OPEN LOOK window manager, (see olwm window manager) openwin command, 37 server access control and, 77 OpenWindows, 8, 37, 185-187 cm client, 118 components of, 300-301 fonts, 107; aliases, 109; Compat.list file, 126; converting, 125-126; example, 123-126; Families.list file, 126; Synonyms.list file, 126 installing, 190 props client, 145-146 setting search path for, 30 xdm, 43 OPENWINHOME environment variable, 30 optimizing, 200 OSF/Motif, 7 components of, 299-300 (see also Motif.) OSMajorVersion build flag, 209 OSMinorVersion build flag, 209 OSName build flag, 209 OSTeenyVersion build flag, 210 outline fonts, 110 P patch command, 195,238, 260-263 errors, 196 source code for, 195 patch level, 194, 196 patches, 186, 259-264 applying, 194-196 getting with xstuff, 237 PATH environment variable, 25, 29 PC X servers, 162, 271-275 advantages and disadvantages, 271 requirements, 272 restricted number of TCP/IP connections, 29 server access control and, 83 X terminals and, 162 X386 (for UNIX derivatives), 189 PCF format, 111, i29, 170 converting BDF to, 112, 138 X terminals and, 171 .pcf files, 111, 170 X terminals and, 171 perl command, 81 PEX, building, 199, 213 PHIGS, building, 199, 213 pixel size, font name field, 102 pixels, 158, 161 bits per, 159 platform, determining type, 192 platform.cf, 204-206, 208-210, 210, 223 point size, and font server, 129 font name field, 102 pointer keyword. 291 Point-to-Point Protocol, (see PPP) port (font server), 130 Portable Compiled Font format, (see PCF format) porting programs, 226-230 ports, used by font server, 130-131,133, 136 used by X server, 96, 130 PostScript, color, 147 Display, 186 documentation, 242 fonts, 111 printing, 242 release notes, 188 Type 3, 111 PPP, 162 preprocessor symbols, searching for, 228 previewer, 115 principals, 85 for root, 85, 88-89; xterm client and, 92 printing documentation, 242-243 private keys, 86 generating, 90 Index 335 process ID, of xdm, 46 processes, increasing number of, 178-179 .profile file, 29, 36 ProjectRoot build flag, 207-208 Project.tmpl, 223 proportional fonts, 102 props resource editor, 145-146 .ps files, 242 .ps fonts, 111 pseudo-ttys, increasing number of, 179 pstat command, 180 ptys, increasing number of, 179 public domain software, 247-268 compiling, 255-268 finding sources, 247-250 patching, 259-264 untarring, 252 public keys, 85-86 generating, 87; for root, 87 propagating to NIS master, 87 Q Quarterdeck Office Systems, 271-272 queries, XDMCP, 55-59, 164, 173 R random numbers, 81 ranlib command, 199 RARP, 165 X terminals and, 164 rarpd daemon, 165 rdist program, 200, 203 example distfile, 203 example usage, 203 shared libraries, 203 special command, 203 release notes, 188-189, 192-193, 205 RELNOTES.TXT, 188-189, 192-193, 205 remote clients, setting DISPLAY for, 36 starting, 34-36 remote configuration, 175-178 advantages of, 175 for NCD X terminals, 176-177 for Tektronix X terminals, 178 for Visual X terminals, 177 of X terminals, 161 remote execution, 173 remote hosts, accessing fonts on, 127 remote Iogins, 34-36 resize client, 31-33 -c flag, 33 SHELL environment variable, 33 -u flag, 33 resizing windows, 19, 31-33 resolution, 158 resolver, 170 resource editors, 145 resources, 6, 8, 24, 281-290 and client -name option, 283-284 and client -xrm option, 286 app-defaults files, 258 application defaults, 103,285 background, 144 chooser, 57, 60 class names, 283-285; learning, 284 color and, 145 configuration files; .Xdefaults, 286-287; .Xdefaults-hostname, 285; .Xresources, 15, 24-25,286 defining, 281-286 font specification, 103 foreground, 144-145 instance names, 283-284; learning, 284 loading into servers, 24-25, 287-288 loose bindings, 52, 282 overriding, 283 read globally with xdm, 286 sample, 15 server-specific, 66 syntax, 281-284 tight bindings, 52, 282 tracing, 286 translation tables, 288-290 using font aliases in, 109 XAPPLRESDIR environment variable, 258 xconsole, 60, 62 xdm, 46, 51, 51-60; 336 X Window System Administrator's Guide resources, xdm (cont'd) DisplayManager*authName, 84, 88; DisplayManager*authorize, 78, 84, 88; DisplayManager*reset, 95; DisplayManager*startup, 95 XENVIRONMENT environment variable, 258 xlogin, 60-62 xrdb, 24 Reverse Address Resolution Pro- tocol, (see RARP) reverse video, 23 rexec command, 173 rgb command, 146 RGB system, 143 aliases, 145 altemate databases, 147 color names, 144-145 defining colors, 146-147 fixing corrupted database, 147 hexadecimal color values, 145; converting to decimal, 146; Xcms and, 148 triplets, 143 Xcms and, 147 rgb.dir file, 146 rgb.pag file, 146 rgb.txt file, 1 44-146 .rhosts file, 35, 81 Secure RPC and, 86, 90 rlogin command. 34 root menu, 14-15, 19, 26 root window, 14 rooted and rootless X servers, 275 rpc.ypupdated daemon, 87 rsh command, 35-36, 79, 81 xrsh command and, 79 .rules files, 222 -rv option, 23 S scalable fonts, 105, 110-111 SCO UNIX, increasing number of processes, 179 increasing number of ptys, 180 scologin, 43, 68 screen dumps, 96 screen resolution, 158 screen size, 158 screendump command, 96 screenload command, 96 screens, 6, 27 search path, setting, 29-30; in startup script, 25; mixed environments, 30; OpenWindows, 30 secure keyboard option, xterm, 93 Secure RPC, 76, 85-86 chkey command, 86 generating public key, 87; for root, 87 newkey command, 86 obtaining, 86 overview, 85-86 principals, 85; for root, 85 propagating public key, 87 SUN-DES-1 and, 84-93 security, 73-98 console windows, 94-96 /dev/kmem, 202 /etc/fbtab, 97 framebuffer, 97 host-based access control, 74-77; /etc/Xn.hosts, 74-75; PC X servers and, 83; problems with, 76-77; X terminals and, 75-76, 79, 83; xhost client, 75-77 kmem group, 202 server access control, 73-93; X terminals, 175 TFTP, 167-168 user-based access control, 77-93; MIT-MAGIC-COOKIE- 1, 77-83; SUN-DES-l, 84-93; XDM-AUTHORIZATION- 1, 83-84, 207 xload permissions, 202 xterm permissions, 202 (see also access control.) Serial Line Internet Protocol, (see SLIP) serial X sessions, 160, 162 Index 337 Serial Xpress, 162 Server Natural Format, (see SNF format) servers, 157 for Archie, 248 (see also font server; mail servers; X servers.) setenv command, CHOWNPROG and, 211 DISPLAY and, 27-28, 164 FONTSERVER and, 134 LD_LIBRARY_PATH and, 30, 317 MANPATH and, 213 TERM and, 204 TMPDIR and, 199 XCMSDB and, 149, 151 XENVIRONMENT and, 258 setup menu, X terminals, 164 SGI, 132-133, 185 sgi.cf, 208 SHAPE extension, 190 shar files, 262 shared libraries, 319 building, 223 installing, 200, 203; with rdist, 203 ldconfig command, 200 LD_LIBRARY_PATH and, 30 shell environment, 27-36 defining search path, 29-30 SHELL environment variable, 33 showrgb command, 23, 144 SIGHUP signal, inetd, 88, 168 named, 241 resetting font servers, 131 Xaccess file, 59 xdm, 45, 52, 55, 59, 67-68, 78 Xservers file, 55 SIGTERM signal, xdm, 68 signals SIGHUP; font server, 131; inetd, 168; named, 241; xdm, 45, 52, 78 SIGTERM; font server, 131; xdm, 68 SIGUSR1; font server, 131 SIGUSR2; font server, 131 SIGTERM signal, killing font servers, 131 SIGUSRI signal, rereading confi- guration file, 131 SIGUSR2 signal, flushing font cache, 131 Silicon Graphics, (see SGI) Silicon Graphics components, 302-303 site.def, 204-205,223 slant, font name field, 101 SLIP, 162 SNF format, 107, 11 l, 125, 129 converting BDF to, 112, 114 converting to BDF, 112 differences, 170 .snf files, 107, I l 1, 170 differences, 170 snftobdf command, I 12 software, public domain, 247-268; compiling, 255-268: finding sources, 247-250; patching, 259-264; untarring, 252 Solaris, 189 Solbourne window manager, (see swm window manager) source code, patch command, 195 servers, 193 XI 1,185-186, 188-189; disk space for, 191; link trees, 196 sources, 247-268 compiling, 255-268 finding, 247-250 patching, 259-264 spacing, font name field, 102 .spd files, 111 Speedo fonts, 105, 110-111,129 fonts.scale and, 107 startup script, 25-26 controlling process, 26 foreground process, 26 setting search path, 25 .xinitrc, 25-26, 38-39 .xinitrc vs..xsession, 39 .xsession, 14, 18, 25-26, 29, 33, 37, 39 startx command, 37-38 static gray, 159 sticky bit, 97 strings command, 192, 229 StripInstalledPrograms build flag, 207 338 X Window System Administrator's Guide window managers (cont'd) as local clients on X terminals, 161 gwm, 19 mwm, 19 olvwm, 19 olwm, 19 swm, 19 tvtwm, 19 twm, 18-19 uwm, 191 windows, iconifying, 19 moving, 19 resizing, 19, 31-33 specifying location of, 20-22 specifying size of, 20-22 titlebar, 19 workstations diskless, 162; fonts for, 127 World, make target, 197,224 wtmp file, 214 X X, AIXWindows components, 302 building; (see building X) client-only distribution, 189 configuring, 204-214 DECWindows components, 301-302 design, 3-7 development distribution, 187 distribution directories, 297 execution-only distribution, 187 graphics files, 302-303 installing; (see installing X) libraries, 303 multiple distributions, 189 on multiple machines, 10 OSF/Motif components, 299-300 portability of, 4 running multiple releases of, 30 source code, 185-186, 188-189 Sun OpenWindows compo- nents, 300-301 user environment, 9, 13-39 vendor-supplied distributions, 186-187 X 11 R5 components, 298-299 X administration, color, 143-153 font administration, 101 - 140 introduction to, 8-10 multiple machines, 10 philosophy of, 10 security, 73-98 user environment, 18 X terminals, 157-181 X clients, (see clients) X Color Management System, (see Xcms) X command, 16, 38, 53 -auth option, 81-82 -fp option, 117 setting default font path, 106 X Consortium, 4, 8 X Display Manager, (see xdm) X Protocol, 3, 98 X resources, (see resources) X servers, 3-6, 167 access control, 73-93; host-based (see host-based access control); reasons for, 73; user-based (see user-based access control); X terminals, 175 adding fonts, 114-126 backing store, 161 color support, 143-153, 158-159 controlled by xdm, 53-55 depth, 159 dimensions, 158 display classes, 65-66 DOS-based, 272-275; requirements, 272 dot pitch, 158 font path, 105-106; default, 106, 212 fonts, 101-140; byte order, 170-171; caching, 115; linking, 170 grayscale support, 158-159 hanging remotely, 96 in xdm resource names, 52 installing for X terminals, 163 keyboards, 159-160 Macintosh computers and, 271, 275 Microsoft Windows and, 271 Index 341 X servers (cont'd) monitors, 157-159 mouse, 159-160 MS-Windows-based, 272-275; requirements, 272 NeXT computers and, 271,277 refresh rate, 159 rooted and rootless, 275 screen resolution, 158 screen size, 158 screens, 6, 27 server-specific resources, 66 SHAPE extension, 190 starting, 38 starting with user-based access control, 81-82 supported by MIT, 193 using from different releases, 190 virtual screens, 158 X command, 53 X terminals, 157-181 X386, 189 XDMCP queries, 45, 53, 55-59 XNeXT, 189 .xserverrc and, 38 Xsun, 244 (see also X terminals.) X session, configuration files, 14 configuring, 13-39 defining search path, 29-30 login shell and, 33-34 sample, 13-15 shell environment, 27-36 starting with xdm, 63-65 startup methods, 37-39 startup script, 25-26; controlling process, 26; foreground process, 26; setting search path, 25 unconfigured, 16-17 xinit vs. xdm, 37-38 X terminals, 3, 9, 157-181 backing store, 161-162 booting, 167-168 color support, 158-159 configuring for xdm, 173-175 configuring for XDMCP, 173-175 depth, 159, 161 display classes and, 55 dot pitch, 158 font server support, 160, 163, 171 fonts, 127, 170-172; byte order, 170-171; disk space and, 170-171; downloading, 163, 171-172; font tape, 170; installing, 163; linking, 170 grayscale support, 158-159 hardware addresses, 165, 169 in Xservers file, 53 installing the server, 163 IP addresses, 164; getting with BOOTP, 165-166; getting with RARP, 165; name server and, 169 keyboards, 159-160 local clients, 161 memory, 158, 161 monitors, 157-159 mouse, 159-160 network interface, 162 network setup, 164-170 network traffic, 158 NVRAM, 164, 168 peripheral support, 161 refresh rate, 159 remote configuration, 161, 175-178; advantages of, 175; for NCD X terminals, 176-177; for Tektronix X terminals, 178; for Visual X terminals, 177 screen resolution, 158 screen size, 158 serial connections, 160-162 server access control, 74-76, 79, 83, 175; host-based, 175; user-based, 175 server software, 160; FLASH ROM, 160; ROM, 160; running on host, 160 setting up, 163-164; steps for, 163 setup menu, 164 telnet window, 164 virtual screens, 158 342 X Window System Administrator's Guide X terminals (cont'd) xdm and, 53 XDMCP support, 53, 160 xmodmap and, 291 X Toolkit Intrinsics (Xt), 7 X Window System, (see X) XlI, (see X) XII/NeWS, 110 fonts, 111,125; converting to BDF, 125; converting to SNF, 125 XlIR3, xdm, 45, 65 Xservers file, 53, 55 XlIRS, components of, 298-299 X386, 189 Xaccess file, 47, 55-59, 164, 174 * (asterisk), 56-57 ! (exclamation point), 56 % (percent sign), 59 BROADCAST keyword, 57 chooser client and, 57-59 CHOOSER keyword, 57 defining macros, 59 excluding, 56 including, 56 rereading, 59 SIGHUP signal, 59 syntax, 56-59 XAPPLRESDIR environment variable, 258, 286 xarchie client, 248, 251-259 xauth command, 36, 79-83, 93 adding a code, 81 commands; add, 81; extract, 79; list, 84, 88; merge, 79 copying magic cookie to remote machine, 79 overridden by xhost client, 82-83 SUN-DES-1 and, 89 using with xinit, 81-82 xrsh command and, 79 .Xauthority file, 77-83 adding a code, 81 extracting code from, 79 merging new entry, 79 SUN-DES-1 and, 85, 89-90 using with xinit, 81-82 47 xcalc client, 14 translation tables and, 288-290 xclock client, 14, 16 Xcms, 144, 147-153 aliases, 149 CIE, 147 client database, 148 color database; example, 151 color names, 148-151 color spaces, 147-148, 150; listing of, 148 defining colors, 150-151 device profiles, 152-153 RGB system and, 147 specifying colors, 148 XCMSDB environment variable, 149 Xcms.txt file, 148-150; example, 149 xcmsdb client, 152-153 .xinitrc example, 153 XCMSDB environment variable, 149, 151 Xcms.txt file, 148-150 example, 149 xcoloredit client, 145-146 xcolors client, 144 XCOMM (imake comment), 220 xconsole client, 26 resources, 60, 62 xdm and, 62 .Xdefaults file, 286-287 .Xdefaults-hostname file, 285 xdm, 9, 25, 37, 43-70 aborting, 61 changing greeting, 61 chooser and, 53, 57-59 command-line options; -config, 46, 52, 67; --debug, 65 concepts, 44-45 configuration files, 46-66; installing, 206; overriding, 67; rereading, 52, 55, 59, 67-68; Xaccess, 55-59, 164, 174; xdm-config, 51-52, 78, 84, 95; Xresources, 60-62; Xservers, 53-55, 65, 174; Xsession, 63-65,286 configuring, 51-66 configuring login box, 60-62 dex 343 xdm (cont'd) configuring X terminals for, 173-175 customizing, 51-66 default environment, 49 display classes, 52, 55, 65-66 easy setup, 48-49 error messages, 46, 63 FI and, 61, 63 failsafe session, 50, 61,63 font server and, 131, 133 history, 45 host access control, 47, 55-59 installing, 69-70 installing DES code, 207 installing; on AIX, 70; on IRIX, 70; on SunOS, 69; on Ultrix, 70 managing another workstation, 53 Open Desktop, 43 OpenWindows, 43 problems logging in, 49-51 process ID, 46 rereading configuration files, 52, 55, 59, 67-68 resources, 51-60; display classes, 52; DisplayManager._0.setup, 62; DisplayManager*authName, 84, 88; DisplayManager*authorize, 52, 78, 84, 88; DisplayManager.autoRescan, 52, 55, 59, 67; DisplayManager.errorFile, 63; DisplayManager.pidFile, 68; DisplayManager*reset, 95; DisplayManager*session, 63-64; DisplayManager*startup, 95; server-specific, 52 restarting with xdm-pid, 68 CTRL-R and, 61 CTRL-RETURN and, 61,63 SIGHUP and, 45, 52, 78 SIGTERM and, 68 SCO version; (see scologin) server access control and, 81; MIT-MAGIC-COOKIE- 1, 78-79; SUN-DES-l, 88; XDM-AUTHORIZATION- 1, 83-84 server-specific scripts, 64 starting, 48, 67 starting automatically, 69-70 starting X session, 63-65 testing, 66-68 troubleshooting, 49-51 vendor environments and, 43 vs. xinit, 37-38 X terminals and, 53, 160, 173-175 X11R3, 45, 53, 65, 174 xconsole client and, 62 xmodmap and, 291 XDM Control Protocol, (see XDMCP) XDM-AUTHORIZATION-I, 83, 83-84, 207 using with xdm, 84 xdm-config file, 46, 51-60, 78, 84, 95 overriding, 67 syntax, 51-52 XDMCP, 45, 174 broadcast queries, 55-57, 173; and subnet, 173 configuring X terminals for, 173-175 direct queries, 55-57, 173 display classes, 65 host access control, 47 indirect queries, 55, 57-59, 173 queries, 55-59, 164, 173; workstations and, 53 server access control and, 77; MIT-MAGIC-COOKIE- 1, 78-79; SUN-DES-l, 88; XDM-AUTHORIZATION- 1, 83-84 X terminals and, 160, 173-175 Xservers file and, 53 xdm-errors file, 46, 49-50, 63 xdm-pid file, 46, 68 xdpyinfo client, 158 xdvi client, 115 XENVIRONMENT environment variable, 258,285 xev client, 291-293 344 X Window System Administrator's Guide xfd client, 103, 108, 115 XFILESEARCHPATH environ- ment variable, 286 xfontsel client, 20, 104 xhost client, 28, 35-36, 74-77, 93 overriding xauth command, 82-83 SUN-DES-1 and, 85, 88-90 xrsh command and, 79 xinit command, 16, 25, 37-38 -- flag, 38, 82, 89 configuration files; installing, 206; .xinitrc, 37-38, 90; .xserverrc, 38; .xserverrc, 82 -dev flag, 38 server access control and, 81-82, 89-90 setting default font path, 106 using xauth with, 81-82 vs. xdm, 37-38, 43 .xinitrc file, 16, 25-26, 37-39 SUN-DES-1 and, 90 xcmsdb and, 153 xkeycaps client, 264-268, 291 Xlib, 7 xloadimage client, 96 xlogin widget, resources, 60-63 xlsfonts client, 20, 103, 108 " xmessage client, 33 xmkmf command, 214-215,256 -a flag, 215,266 xmodmap client, 264, 290-293 checking keysyms with xev, 292 disabling CAPS LOCK, 290 mapping Backspace to Delete, 290 -pk option, 291 redefining pointer, 291 switching Control and CAPS LOCK, 291 X terminals and, 291 .Xmodmap file, 291 XNeXT, 189, 277 xpert mailing list, 233,250 xpostit client, 14, 249 xrdb client, 24-25, 60-61, 64, 285, 287-288 cpp and, 287 -D option, 287 #define commands, 287 #ifdef commands, 287 #include commands, 287 -load option, 288 -merge option, 288 pre-defined symbols, 287 -query option, 288 Xremote, 162 Xresources file, 62-65 .Xresources file, 24-25, 47, 64, 286 sample, 15 -xrm option, 286 xrolodex client, 247 xrsh command, 36, 79 XRSH_AUTH_TYPE and, 79 XRSH AUTH TYPE environment -- -- variable, 79 xsccd client, 153 .xserverrc file, 38 server access control and, 82 Xservers file, 46, 48, 53-55, 65, 174 default font path, 106 display classes, 55 rereading, 55 SIGHUP signal, 55 syntax, 53 X 11R3, 53, 55 XDMCP and, 45, 53 Xsession file, 18, 45-46, 63-65 .xsession and, 64 .xsession file, 25-26, 39, 45, 47, 49, 63 bypassing, 50, 64 C shell, 29 controlling process, 50 default search path, 29 error messages, 39 failsafe session, 50 foreground process, 50 problems with, 49-51 sample, 14 Xsession and, 64 .xsession-errors file, 47, 49-50, 63 -64 problems with, 50 xset client, 105, 116, 124 font server and, 136-137 fp option, 105, 114, 136 fp rehash option, 106, 115, 124 -q option, 105, 137 xset command, fp option, 172 xsetroot client, 25 Index 345 Xsetup_0 file, 47 Xstartup file, 47 xstuff, 237-238 Xsun, 38, 244 xterm client, 14, 16 -bg option, 144 build flags, 214 --C option, 94 console windows, 94 -fg option, 144 -fn option, 20, 103 fonts, 101, 106 -geometry option, 20 installing terminal definition for, 203 -204 login shell, 33-34 -Is option, 33-34 resized windows, 31-33 resources; font, 15; loginShell, 33; savedlines, 15; scrollBar, 15 SUN-DES-I security and, 92 scroll bar, 15 secure keyboard feature, 93-94 shell issues, 31-34 terminal emulation, 31 VT 100 widget, 24 xtex client, 115-117 xtici color editor, 150-151 xtrek client, 138 XUSERFILESEARCHPATH envi- ronment variable, 286 XView toolkit, 7 xwebster client, 259-264 Yellow Pages, (see NIS) ypbind command, 87 ypmatch command, 85-86, 240 ypwhich command, 86, 240 .Z files, 107, 112, 236, 238, 242 Z zcat command, 238, 242, 252 zmail client, 33 346 X Window System Administrator's Guide About the Authors Linda Mui started working for O'Reilly & Associates in 1986. She was first hired as a production assistant, later became an apprentice system administrator, and is now a writer. Her first writing job was for termcap and terminfo, which she co-authored with John Strang and Tim O'Reilly. She also wrote Pick BASIC, on programming applications for Pick systems. In between writing jobs, Linda works on troffmacros and tools for the O'Reilly & Associates production staff. Linda was raised in the Bronx, New York and now lives in Cambridge, Massachusetts. Lately she has been trying to improve herself by learning how to swim, play billiards, and accessorize. Eric Pearce is an author and technical resource for O'Reilly & Associates. In addition to co- authoring this book, he is also responsible for developing CD-ROM companion disks for books produced by O'Reilly & Associates. Eric's interests include promoting public domain software, Internet connectivity and network services. Before coming to work for O'Reilly & Associates, Eric worked as a systems programmer for Boston University, which he also attended as a student. His favorite activities include bicycling, snow- boarding, rock climbing, and dangerous sports. I I I If you want more information about our books, or want to know where to buy them, we're happy to send it. :1 Send me a free catalog of titles. _3 What bookstores in my area carry your books (U.S. and Canada only)? L.1 Where can I buy your books outside the U.S. and Canada? :1 Send me information about consulting services for documentation or program- ming. [] Send me information about bundling books with my product. Name Address City State, ZIP Country Phone Email Address NAME COMPANY ADDRESS. CITY STATE Z l P II NO POSTAGE NECESSARYIF MAILEDIN THE UNITED STATES BUSINESS REPLY MAIL FIRST CLASS MAIL PERMIT NO. 80 SEBASTOPOL, CA POSTAGE WILL BE PAID BY ADDRESSEE O'Reilly & Associates, Inc. 103 Morris Street Suite A Sebastopol CA 95472-9902 NAME COMPANY ADDRESS CITY STATE ZIP II NO POSTAGE NECESSARYIF MAILEDIN THE UNITED STATES BUSINESS REPLY MAIL FIRST CLASS MAIL PERMIT NO. 80 SEBASTOPOL, CA POSTAGE WILL BE PAID BY ADDRESSEE O'Reilly & Associates, Inc. 103 Morris Street Suite A Sebastopol CA 95472-9902 Overseas Distributors Effective January 1, 1990, customers outside the U.S. and Canada will be able to order O" Reilly & Associates books through distributors near them. These overseas locations offer international customers faster order processing, more local bookstores and local distributors, and increased representation at trade shows worldwide, as well as the high level, quality service our customers have always received. AUSTRALIA & NEW ZEALAND (orders and inquiries) Addison-Wesley Publishers, Pty. Ltd. 6 Byfield Street North Ryde, N.S.W. 2113 AUSTRALIA Telephone: 61-2-888-2733 t:AX: 61-2-888-9404 GREAT BRITAIN & AFRICA (orders and inquiries) Addison-Wesley Publishers Ltd. Finchampstead Road Wokingham, Berkshire RG11 2NZ ENGLAND Telephone: 44-734-794-000 FAX: 44-734-794-035 EUROPE & MIDDLE EAST (orders and inquiries) Addison-Wesley Publishing Group Concertgebouwplein 25 1071 LM/nsterdam THE NETHERLANDS Telephone: 31-20-671-72-96 FAX: 31-20-664-53-34 U.S. & CANADA (orders and inquiries) O' Reilly & Associates, Inc. 103 Morris Street, Suite A Sebastopol, CA 95472 U.S.A. Telephone: 1-800-338-6887 Fax: 1-707-829-0104 LATIN AMERICA (inquiries) Addison-Wesley Iberoamericana S A. Blvd. de las Cataratas No. 3 Colonia Jardines del Pedregal Delegacion Alvaro Obregon Mexico 01900, D. F. MEXICO Telephone: 525-660-2497 FAX: 525-660-4930 LATIN AMERICA (orders) Addison-Wesley Publishing Company International Order Departznent Jacob Way Reading, MA 01867 U.S.A. Telephone: 1-617-944-3700 FAX: 1-617-942-2829 ASIA except JAPAN (inquiries) Addison-Wesley (Singapore) Pte. Ltd. 15 Beach Road 05-09/10 Beach Centre SINGAPORE 0718 Telephone: 65-339-7503 FAX: 65-339-9709 ASIA except JAPAN (orders) Addison-Wesley Publishing Company International Order Department Jacob Way Reading, MA 01867 U.S.A. Telephone: 1-617-944-3700 FAX: !-617-942-2829 JAPAN (orders and inquiries) Toppan Conpany, Ltd. Ochanomizu Square B, !-6 Kanda Surugadai Chiyoda-ku, Tokyo 101 JAPAN Telephone: 81-3-3295-3461 FAX: 8 I-3-3293-5963