scologin(XC)


scologin -- X Display Manager

Syntax

scologin [start | stop | query | enable | disable | init]

Description

This display manager allows host machines to conduct graphical login dialogs 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: 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 part of the session can be defined on a per-user, per group, or system-wide basis. When the session is terminated, scologin resets the X server and restarts the whole login process. 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 network 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:

display_name [display_class]

display_type [startup_command]


display_name
name of either a local X server or a remote X display using the following syntax:

hostname:displaynumber[.screennumber]

display_name can be used in X client -display options and can also be included in scologin configuration resource specifications.


display_class
defines a ``display class'' with which display_name is associated. Once display_class is defined, you can include it in scologin configuration resource specifications to affect groups of displays. Although display_class 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 display_class in each Xservers entry.

display_type
indicates either a local or remote X server. If display_type is ``local'', scologin manages a local display that has a server program to run. If display_type is ``foreign'', scologin manages a remote display on which the server is already running.

startup_command
applies only to local displays, and by default is /usr/bin/X11/X. Use startup_command 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 information on XDMCP, see the Xsco(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 display. 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, insert the display name set off by periods into the resource name between ``DisplayManager'' and the final resource name segment.

For example, DisplayManager.expo_0.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 messages 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

authorize controls whether scologin generates and uses authorization 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. By default, authorize is ``true''. To turn off authorization, set this resource to ``false''. Note that this resource should be set in /usr/lib/X11/scologin/Xconfig.

DisplayManager.display.authName

authName specifies the authorization protocol to use if authorize is ``true''. Currently, scologin only supports ``MIT-MAGIC-COOKIE-1'' authorization. In cases where XDMCP connections are established, authName is ignored.

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 environment 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/scologin/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 executed 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 /usr/lib/X11/Xsession[--shell] where shell is the user's current shell type.

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 localize 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 successive 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 system 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 display 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 that scologin executes 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 session would have had (see ``Defining X sessions''). The default is /usr/bin/X11/scoterm.

DisplayManager.display.debugLevel

if set to an integer value other than 0, causes scologin to print debugging information to /tmp/scologin-debug. 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 commands 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 scologin login 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 executes /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 continues.

When using scologin, do not use an exec command in a .login or .profile file. Using exec disrupts and aborts scologin's entire startup mechanism. 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 immediately 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 session 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.

Resources

You can customize the characteristics of scologin using your personal X resource file, $HOME/.Xdefaults-hostname, where hostname is the name of the machine on which the client is running. If this file does not exist in your home directory, you will need to create it. Changes made to this file take effect the next time you run scologin.

In addition to recognizing the core resource names and classes, scologin defines the following application-specific resources:


scologin*error_lb.foreground

scologin*pwd_err_lb.foreground

scologin*pwd_message_lb.foreground

scologin*error_box*background

scologin*help_box*background

scologin*lock_box*background

scologin*null_box*background

scologin*pwd_box*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*help_win.width

scologin*help_win.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*error_win.height

scologin*error_win.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*pwd_win.height

scologin*pwd_win.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*icon_lb.labelPixmap

specifies an xbm format bitmap file that contains the Open Systems 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*password_lb.fontList

specifies the font list to use for the ``Password'' label in scologin. The default varies with the size of the display.

scologin*help_title.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*help_tx.fontList

specifies the font to use for the text in the help dialog. The default varies with the size of the display.

scologin*error_frm*error_lb.fontList

specifies the font list to use for the error label in scologin. The default varies with the size of the display.

scologin*error_lb.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 display.

scologin*login_bt.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*help_bt.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*abort_bt.labelString

specifies the string to use in the middle button of the main scologin window. The default string is ``Restart''.

scologin*login_lb.labelString

specifies the string to use after the machine name label on the scologin window. The default string is ``login''.

scologin*password_lb.labelString

specifies the string to use for the label below the login and machine name labels. The default string is ``Password''.

scologin*help_title.labelString

specifies the string to use for the title of the help dialog box. The default string is ``Help on SCO Login''.

scologin*con_help_title.labelString

specifies the string to use for the title of the console help window. The default string is ``Help on Console Error Messages''.

scologin*close_bt.labelString

specifies the string to use for the buttons to close the help dialog. The default string is ``Close''.

scologin*error_frm*error_lb.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*error_button.labelString

specifies the string that appears in the button in the error dialog box.

scologin*pwd_1_lb.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*pwd_2_lb.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*ok_bt.labelString

specifies the string for the lower left of the ``expired password'' dialog box. The default string is ``OK''.

scologin*can_bt.labelString

specifies the string for the lower right of the ``expired password'' dialog box. The default string is ``Cancel''.

scologin*null_message_lb*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*account_locked.labelString

specifies the string that appears when the user's account is locked. The default is ``Account is disabled -- see Account Administrator.''

scologin*user_limit

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*no_match

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*too_short

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*illegal_combo

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*no_pwd

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*exp_pwd

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*try_again

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*no_help_found

specifies the string used when there is no help file is on the system. The default string is ``Sorry, no help on this system.''

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.help_file

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 password'' dialog box, respectively.

scologin.allow_access

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 XSetAccessControl(). By default, it is set to ``False''.

scologin*error_box.x

scologin*error_box.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 initiate a dialog with a host, after which scologin establishes a connection with the X terminal. The X terminal must be configured to communicate 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 network 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 found. With servers that support XDMCP, scologin closes its initial connection, ending 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/P86scologin
/etc/rc0.d/P91scologin

See also

X(X), Xsco(X), xauth(X), xhost(X), xinit(X), scosession(XC), startx(X)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 -- 26 May 2005