scologin(X) 06 January 1993 scologin(X) Name scologin - X Display Manager Syntax scologin [start | stop | query | enable | disable | init] Description This display manager allows host machines to conduct graphical login dia- logs with local and remote X servers. It provides services similar to those that init(M), getty(M), and login(M) provide to character-based terminals: + prompting for user login and password + authenticating users + requesting new passwords + establishing secure X sessions scologin consists of two parts: /usr/bin/X11/scologin if enabled, this display manager X client is started as a daemon from a script in /etc/rc0.d when the system enters single-user mode, and from a script in /etc/rc2.d when the system enters multiuser mode. Once running, scologin can be stopped and restarted. This client may not be executed by users. For details on enabling and disabling scologin, see ``Options,'' below. /etc/scologin script that allows system administrators to control the scologin process. The scologin script must be run as root. For details on each script option, see ``Options,'' below. scologin manages the user's X session in three stages by executing the following scripts: /usr/lib/X11/scologin/Xstartup executed before the X session begins /usr/lib/X11/scologin/Xsession defines the X session /usr/lib/X11/scologin/Xreset executed when the X session is terminated. This script restores the main scologin dialog. Each X session is defined by the lifetime of a startx(X) process. The clients that are automatically run as the session can be defined on a per-user, per group, or system-wide basis. When the session is ter- minated, scologin resets the X server and restarts the whole login pro- cess. For details on defining sessions, see ``Defining X sessions.'' Options The /etc/scologin script has six options: start starts the scologin process and reads scologin's configuration files, Xconfig, Xservers, and Xresources stop stops the scologin process. Run scologin stop to halt all current X sessions managed by scologin. For example, run scologin stop if you want to reclaim scologin-managed ttys and restore getty processes. query returns the current state of the scologin process disable stops the current scologin process and prevents scologin from starting when the system re-boots enable ensures that scologin starts when the system re-boots and starts the scologin process if it is not already running init if scologin is enabled, disables getty processes on terminals that are configured for scologin. scologin init should only be run by init at boot time. Logging in The scologin dialog box appears on the screens of all active X servers for which scologin is configured unless the servers are already engaged in X sessions. For details on how to specify which X servers scologin manages, see ``Specifying X servers.'' The scologin dialog box contains two fields into which you enter your login name and password, and three buttons: Login, Restart, and Help. To start your X session, enter your login and password, then click Login or press <Return>. If your initial login attempt fails, enter new text and click Login again. To restart the server and clear the scologin dialog, click Restart. If the login is successful, the scologin dialog is replaced by the clients specified for your X session. For details on specifying initial clients, see ``Defining X sessions.'' Failsafe login Logging in through scologin usually establishes an X session consisting of a selection of X clients. For details on configuring scologin for specific clients, see ``Configuring the X session.'' For troubleshooting, however, it may be convenient to reduce the number of clients in your initial X session. This minimal X session is called ``failsafe'' login and, by default, consists of a single scoterm without the Motif window manager. To execute a failsafe session, enter your login and password in the scologin dialog, then press <F1>. Instead of your usual X session, you get a single, unmanaged scoterm window. System administrators should note that failsafe login causes ``failsafe'' to be passed as an argument to the user's session script. For details on customizing the user's session, see ``Defining X sessions.'' Specifying X servers There are two ways to specify which X display servers must be managed by scologin. If the display supports the X Consortium standard X Display Manager Control Protocol, XDMCP, you can usually specify the name or net- work address of a remote machine running scologin at the display or X terminal. If, however, you want to manage a display that does not support XDMCP, add an entry for the X display in the /usr/lib/X11/scologin/Xservers file. Each line of the Xservers file specifies a display that should constantly be managed and, optionally, a ``display class'' with which it is associated. For local servers that are not yet running, you can also include a command line to start the server. Each entry has the following syntax: displayname [displayclass] displaytype [startupcommand] displayname name of either a local X server or a remote X display using the following syntax: hostname:displaynumber[.screennumber] displayname can be used in X client -display options and can also be included in scologin configuration resource specifications. displayclass defines a ``display class'' with which displayname is associated. Once displayclass is defined, you can include it in scologin configuration resource specifica- tions to affect groups of displays. Although dis- playclass is optional, it is useful if you have a large collection of similar displays and want to set resources for groups of them. To include several X displays in the same class, use the same displayclass in each Xservers entry. displaytype indicates either a local or remote X server. If dis- playtype ``local'', scologin manages a local display that has a server program to run. If displaytype is ``foreign'', scologin manages a remote display on which the server is already running. startupcommand applies only to local displays, and by default is /usr/bin/X11/X. Use startupcommand to specify command line options to the Xsco server, such as the local tty you want scologin to manage. If the remote display is a system running the Xsco server, you may enable the server to connect with your host machine either by adding your host to the server's /etc/Xn.hosts files or by using XDMCP. For more informa- tion on XDMCP, see the scologin(X) manual page. To manage a local display on tty03 that is not yet running and a display on another machine named stimpy, include the following lines in your /usr/lib/X11/scologin/Xservers file: :0 local /usr/bin/X11/Xsco :0 -crt /dev/tty03 stimpy:0 foreign Note that you must have access to the stimpy:0 display to manage the dis- play. You can gain access to Xsco displays by including your machine's name in one of the other machine's /etc/Xn.hosts files. To manage a set of displays that belong to a class named ``myclass,'' the /usr/lib/X11/scologin/Xservers file would contain entries such as the following: :0 local /usr/bin/X11/Xsco :0 -crt /dev/tty02 :1 myclass local /usr/bin/X11/Xsco :1 -crt /dev/tty04 brillig:0 myclass foreign borogrove:0 myclass foreign ``myclass'' can then be inserted in scologin configuration resources to affect the :1 local server, brillig:0, and borogrove:0 remote displays. The :0 local display is not included in the myclass group of displays. scologin configuration resources Many aspects of scologin can be configured through the configuration file, /usr/lib/X11/scologin/Xconfig. Some scologin configuration resources modify the behavior of scologin on all displays, while others modify its behavior on one single display or display class. To specify a resource for all displays, insert an asterisk between ``DisplayManager'' and the final resource name segment. Where actions relate to a specific display, the display name is inserted into the resource name between ``DisplayManager'' and the final resource name segment. For example, DisplayManager.expo0.startup is the name of the resource that defines the startup shell file on the expo:0 display. For local servers, however, use only the display number, preceded by an underscore. For example, if your machine is named localhost, to specify the local :0 display, use ``_0'' instead of ``localhost_0''. Similarly, if the name of a display class that has been defined in the Xservers file is inserted between ``DisplayManager'' and the final resource name segment, only displays belonging to that display class obtain the specified value. For example, if your Xservers file defines a class named ``myclass'', your configuration file can include entries such as the following: DisplayManager*myclass*resources: Myresources DisplayManager*_0*resources: Xresources In this example, scologin obtains resources for the displays in the ``myclass'' group from the Myresources file, but obtains resources for the local :0 display from the Xresources file. For details on defining display classes, see ``Specifying X servers.'' _________________________________________________________________________ NOTE Because the resource manager uses colons to separate the name of the resource from its value and dots to separate resource name parts, scologin substitutes underscores for the dots and colons when generating the resource name. _________________________________________________________________________ The following resources affect scologin configuration: DisplayManager.servers specifies the full pathname of a file of server entries, one entry per line. Each entry indicates a display not using XDMCP that needs to be managed by scologin. The default is /usr/lib/X11/scologin/Xservers. For details, see ``Specifying X servers.'' DisplayManager.displayErrors determines whether error messages are displayed. The default is ``true''. DisplayManager.errorLogFile specifies the file where all errors are logged. All error mes- sages that are output from the Xsession, Xstartup and Xreset scripts are placed in this error file. The default is /usr/lib/X11/scologin/Xerrors. DisplayManager.autoRescan controls whether scologin rescans the configuration file and servers file after a session terminates and the files have changed. By default it is ``true''. System administrators can force scologin to reread these files by running scologin stop, then running scologin start. DisplayManager.display.authorize DisplayManager.display.authName authorize controls whether scologin generates and uses authori- zation for server connections. If authorize is ``true'', authorization is used, and authName specifies the authorization protocol to use. Currently, scologin only supports ``MIT- MAGIC-COOKIE-1'' authorization. In cases where XDMCP connec- tions are established, authName is ignored. By default, authorize is ``true''. DisplayManager.display.authFile file that is used to communicate authorization data from scologin to the server using the -auth command line option. This file should be in a directory that is not accessible to users to prevent the server's authorization mechanism from being disabled. DisplayManager.display.userAuthDir filename of authorization file to which the XAUTHORITY environ- ment variable is set if scologin is unable to write to the default authorization file, $HOME/.Xauthority. DisplayManager.display.resources specifies the file that contains X resources that control the appearance of the scologin dialog box. The resources are loaded by xrdb just before the authentication process begins. These resources control the appearance of the login window and are general Motif resources. For a full list of these resources, see ``scologin-specific appearance X resources.'' The default value for this file is /usr/lib/X11/scolog- in/Xresources. You can set display to localize the resource for specific displays. DisplayManager.display.startup specifies a file that contains a shell script that gets exe- cuted as root after the authentication process succeeds. This script is run using the standard Bourne shell. By default the value for this file is /usr/lib/X11/scologin/Xstartup. You can set display to localize the resource for specific displays. DisplayManager.display.session specifies the program that is run as the session. The program does not have to be run by root. By default, scologin executes Xsession[-SHELL] in /usr/lib/X11/scologin. DisplayManager.display.reset specifies a file that contains a shell script that is executed as root after the session terminates. This script is run using the standard Bourne shell. By default the value for this file is /usr/lib/X11/scologin/Xreset. You can set display to local- ize the resource for specific displays. DisplayManager.display.openDelay; DisplayManager.display.openRepeat; DisplayManager.display.openTimeout; DisplayManager.display.startAttempts control the behavior of scologin when attempting to open servers that do not start after receiving an initial request. openDelay is the length of the pause (in seconds) between suc- cessive attempts to open a server; openRepeat is the number of attempts; openTimeout is the waiting period for actually attempting the open (the maximum time spent in the connect sys- tem call), and startAttempts is the number of times this entire process repeats before giving up on the server. After openRepeat attempts have been made, or if openTimeout seconds elapse in any particular attempt, scologin terminates and restarts the server, attempting to connect again. This process is repeated startAttempts time, at which point the dis- play is declared dead and disabled. The default values are 5 for openDelay; 5 for openRepeat; 30 for openTimeout, and 4 for startAttempts. DisplayManager.display.pingInterval; DisplayManager.display.pingTimeout allow scologin to discover when remote displays disappear. scologin occasionally ``pings'' them, using an X connection and sending XSync requests. pingInterval specifies the time (in minutes) between each ping attempt, pingTimeout specifies the maximum amount of time (in minutes) to wait for the terminal to respond to the request. If the terminal does not respond, the session is officially terminated. Both resources default to 5 minutes. scologin does not ping local displays. DisplayManager.display.userPath the PATH environment variable for the session. This is a colon-delimited list of directories. The default is :/bin:/usr/bin:/usr/bin/X11. DisplayManager.display.systemPath sets the PATH environment variable for the startup and reset scripts. Because the reset and startup scripts are run by root, specify all root paths here. The default is /etc:/bin:/usr/bin:/usr/bin/X11. DisplayManager.display.systemShell sets the SHELL environment variable for the startup and reset scripts. The default is /bin/sh. DisplayManager.display.failsafeClient specifies the program to which scologin returns if the default session fails to execute (that is, the session script returns non-zero value). This program is executed with no arguments, but executes using the same environment variables as the ses- sion would have had (see ``Defining X sessions''). The default is /usr/bin/X11/scoterm. DisplayManager.display.debugLevel if non-zero, causes scologin to print debugging information. By default, the output is redirected to /dev/null by a line in /etc/inittab. To direct the output to standard output or to a file, edit the scologin entry in /etc/inittab. By default, debugLevel is zero. Xstartup script After scologin authenticates a user, it executes the startup script specified by the startup configuration resource. The default script is /usr/lib/X11/scologin/Xstartup. It is run as ``root'' and should be written with security in mind. This is the script that can execute com- mands that mount users' home directories from file servers, display the message of the day, or abort the session if logins are not allowed. The following environment variables are set prior to running this script: DISPLAY set to the associated display name HOME set to the home directory of the user USER set to the user name PATH set to the value of DisplayManager.DISPLAY.systemPath SHELL set to the value of DisplayManager.DISPLAY.systemShell XAUTHORITY set to an authority file No arguments are passed to the script. scologin waits until this script exits before starting the user session. If the exit value of this script is non-zero, scologin discontinues the session immediately and restarts the scologin dialog. Defining X sessions After executing the startup script, scologin looks for a script that defines the X session. First, it looks for .xsession in the user's home directory. If no user-specific session script is found, then scologin looks for /usr/lib/X11/scologin/Xsession-SHELL, where SHELL is the user's current type of shell. If no shell-specific session script is found, scologin executes /usr/lib/X11/scologin/Xsession as the X session. This search order allows X sessions to be defined on a per-user or system-wide basis. The Xsession files source the .profile or .login file in the user's home directory, setting any environment variables that are configured in these files. If a user uses the exec command in the .login or .profile file to run an application that requires a terminal, the X session terminates because no terminal is defined when scologin executes the user's .login and .profile files. On the other hand, if the application is run without the exec command, only the application terminates; the rest of the X session con- tinues. When using scologin, do not use an exec command in a .login or .profile file. Using exec disrupts and aborts scologin's entire startup mecha- nism. It is also good practice to avoid using a read that prompts the user for input in a .login or .profile file. The read will return immedi- ately as if an end of file was reached. The startup shell is not interactive with scologin. Session scripts are run with the authorized user's permissions and with the following environment variables: DISPLAY set to the associated display name HOME set to the home directory of the user USER set to the user name PATH set to the value of DisplayManager.DISPLAY.userPath SHELL set to the user's default shell (from /etc/passwd) XAUTHORITY set to a non-standard authority file All standard X session scripts accept the ``failsafe'' option to allow a minimal X session to be run for troubleshooting. For details on running a failsafe session, see ``Failsafe login.'' Xreset script Symmetrical with Xstartup, a ``reset'' script is run after the user ses- sion has terminated. Unless otherwise specified with the reset scologin configuration resource, /usr/lib/X11/scologin/Xreset is run. Run as root, the Xreset script should contain commands that undo the effects of commands in the Xstartup script. For example, the Xreset script can unmount directories from file servers. The environment variables that were passed to Xstartup are also passed to Xreset. scologin-specific appearance X resources scologin uses Motif Text widgets. The following X resources affect scologin and reside in the file specified by the DisplayManag- er.DISPLAY.resources scologin configuration resource: scologin*errorlb.foreground scologin*pwderrlb.foreground scologin*pwdmessagelb.foreground scologin*errorbox*background scologin*helpbox*background scologin*lockbox*background scologin*nullbox*background scologin*pwdbox*background specify the colors used by scologin for its dialogs and other widgets. On a monochrome display, the foreground is black and the background is white. scologin*XmFrame.shadowThickness specifies the thickness size of the frame shown around all the windows and dialog boxes of scologin. The default varies with the size of the display. scologin*helpwin.width scologin*helpwin.height specify the height and width of the help dialog box. The defaults vary with the size of the display. scologin*consoleHelpWindow.width scologin*consoleHelpWindow.height specify the height and width of the console help window. The defaults vary with the size of the display. scologin*errorwin.height scologin*errorwin.width specify the height and width of the console error message box that appears when console error messages appear. The default message box size varies with the size of the display. scologin*pwdwin.height scologin*pwdwin.width specify the height and width of the new password dialog box that appears when a new password is requested. The default message box size varies with the size of the display. scologin*iconlb.labelPixmap specifies an xbm format bitmap file that contains the Open Sys- tems Software logo displayed with scologin. The default file varies with the size of the display. scologin*XmLabel.fontList specifies the font list to be used for all labels within scologin. The default font list varies with the size of the display. scologin*passwordlb.fontList specifies the font list to use for the ``Password'' label in scologin. The default varies with the size of the display. scologin*helptitle.fontList specifies the font list to use for the title string of the help dialog box. The default varies with the size of the display. scologin*helptx.fontList specifies the font to use for the text in the help dialog. The default varies with the size of the display. scologin*errorfrm*errorlb.fontList specifies the font list to use for the error label in scologin. The default varies with the size of the display. scologin*errorlb.fontList specifies the font list to use for any errors that need to be printed in scologin. The default varies with the size of the display. scologin*XmText.fontList specifies the font list to use for all text widgets within scologin. The default varies with the size of the display. scologin*XmPushButton.fontList specifies the font list to use for all labels that appear in scologin buttons. The default varies with the size of the dis- play. scologin*loginbt.labelString specifies the string to use in the button in the lower left corner of the main scologin window. The default string is ``Login''. scologin*helpbt.labelString specifies the string to use in the button in the lower right corner of the main scologin window. The default string is ``Help''. scologin*abortbt.labelString specifies the string to use in the middle button of the main scologin window. The default string is ``Restart''. scologin*loginlb.labelString specifies the string to use after the machine name label on the scologin window. The default string is ``login''. scologin*passwordlb.labelString specifies the string to use for the label below the login and machine name labels. The default string is ``Password''. scologin*helptitle.labelString specifies the string to use for the title of the help dialog box. The default string is ``Help on SCO Login''. scologin*conhelptitle.labelString specifies the string to use for the title of the console help window. The default string is ``Help on Console Error Mes- sages''. scologin*closebt.labelString specifies the string to use for the buttons to close the help dialog. The default string is ``Close''. scologin*errorfrm*errorlb.labelString specifies the string to use for the label displayed at the top of the error dialog box. The default string is ``Console Errors''. scologin*errorbutton.labelString specifies the string that appears in the button in the error dialog box. scologin*pwd1lb.labelString specifies the string to use for the label displayed in the new password dialog box. This label appears to the left of the first text widget in the ``expired password'' dialog box. The default string is ``Enter New Password''. scologin*pwd2lb.labelString specifies the string for the label displayed in the ``expired password'' dialog box. This label appears to the left of the second text widget in the dialog box. The default string is ``Verify New Password''. scologin*okbt.labelString specifies the string for the lower left of the ``expired pass- word'' dialog box. The default string is ``OK''. scologin*canbt.labelString specifies the string for the lower right of the ``expired pass- word'' dialog box. The default string is ``Cancel''. scologin*nullmessagelb*labelString specifies the string for the null password dialog box. This dialog appears when a user tries to create a null password. The default string is ``Do you want to create a null password ?''. scologin*accountlocked.labelString specifies the string that appears when the user's account is locked. The default is ``Account is disabled -- see Account Administrator''. scologin*userlimit specifies the error string produced when a user's attempt to log into a system with a two-user license exceeds the system's user limit. The default string is ``The system has reached its' user limit.'' scologin*invalid specifies the error string produced when an invalid password is entered. The default string is ``Invalid Password'' scologin*nomatch specifies the error string that appears when the user inputs a new password, but enters two passwords that do not match. The default string is ``The passwords don't match. Try again.'' scologin*tooshort specifies the error string produced when the user enters a new password that is shorter than the system defined password length. The default string is ``The password is too short. Try again.'' scologin*unchanged specifies the error string produced when the user enters a password that is supposed to be new but matches the previous password. The default string is ``Password unchanged!'' scologin*illegalcombo specifies the error string produced when the user enters a new password that does not comply with the system-defined password combination set. The default string is ``Not a combination of letters and digits.'' scologin*nopwd specifies the string used as the title for the new password dialog when the user lacks a password. The default string is ``You do not have a password. Please create one.'' scologin*exppwd specifies the string used as the title for the new password dialog when the user's password expires. The default string is ``Your password has expired. Please create a new one.'' scologin*tryagain specifies the string used as the generic error message when the user enters an invalid name/password combination. The default string is ``Please try again.'' scologin*nohelpfound specifies the string used when there is no help file is on the system. The default string is ``Sorry, no help on this sys- tem.'' scologin*XmText*translations specifies translations that can be added to the text widgets. By default, the osfHelp key (usually <F1>), calls the activate function of the text widget. This enables the failsafe method of logging onto the system. scologin.helpfile scologin.consoleHelp scologin.defaultPasswdGuide specify the files that contain the text used in the scologin help dialog, the console help window, and in the ``new pass- word'' dialog box, respectively. scologin.allowaccess controls whether other clients can communicate with the server while scologin is active. For security reasons, you should not allow other clients to access the server while scologin is active. The routine used to control this behavior is XSetAc- cessControl(). By default, it is set to ``False''. scologin*errorbox.x scologin*errorbox.y control the placement of the console error message dialog box. By default, the dialog is placed near the upper left corner of the display. scologin*XmFrame.shadowType specifies the type of shadowing to use for all window frames. The default is ``SHADOW_ETCHED_OUT''. Typical usage For X terminals that support XDMCP, such as most X11 Release 4 servers, the host requires no configuration. XDMCP enables the X terminal to ini- tiate a dialog with a host, after which scologin establishes a connec- tion with the X terminal. The X terminal must be configured to communi- cate with the host through the X terminal's setup procedures, which vary from one model to another. Some X terminals let you specify the address of a display manager server. Some X terminals can broadcast over the net- work a request for a host and then display a list of all available hosts from which the user can choose. Other X terminals can broadcast a request, and merely accept the first available host. For servers that do not support XDMCP, the host must list their display names in the Xservers file. Controlling the server To control remote servers not using XDMCP, scologin searches the window hierarchy on the display and uses the X protocol request KillClient to clean up the terminal for the next session. This may not kill all clients, as only those which have created windows are noticed. With servers that support XDMCP, scologin closes its initial connection, end- ing the session and forcing the terminal to close all other connections. Files /etc/scologin /usr/bin/X11/scologin /usr/lib/X11/scologin/Xerrors /usr/lib/X11/scologin/Xreset /usr/lib/X11/scologin/Xresources /usr/lib/X11/scologin/Xservers /usr/lib/X11/scologin/Xsession /usr/lib/X11/scologin/Xsession-csh /usr/lib/X11/scologin/Xsession-ksh /usr/lib/X11/scologin/Xsession-sh /usr/lib/X11/scologin/Xstartup /usr/lib/X11/scologin/Xconfig /etc/rc2.d/S91scologin /etc/rc0.d/K91scologin See also X(X), Xsco(X), xauth(X), xhost(X), xinit(X), scosession(X), startx(X)