XENODM(1) | General Commands Manual | XENODM(1) |
xenodm
— X Display
Manager
xenodm |
[-config
configuration_file]
[-nodaemon ] [-debug
debug_level] [-error
error_log_file] [-resources
resource_file] [-server
server_entry] [-session
session_program] |
xenodm
manages a collection of X displays
on the local host. xenodm
provides services similar
to those provided by getty(8)
and login(1) on character
terminals: prompting for login name and password, authenticating the user,
and running a “session”.
A “session” is defined by the lifetime of a
particular process; in the traditional character-based terminal world, it is
the user's login shell. In the xenodm
context, it is
an arbitrary session manager. This is because in a windowing environment, a
user's login shell process does not necessarily have any terminal-like
interface with which to connect. When a real session manager is not
available, a window manager or terminal emulator is typically used as the
“session manager”, meaning that termination of this process
terminates the user's session.
When the session is terminated, xenodm
resets the X server and (optionally) restarts the whole process.
Because xenodm
provides the first
interface that users will see, it is designed to be simple to use and easy
to customize to the needs of a particular site.
xenodm
has many options, most of which have
reasonable defaults. Browse through the various sections of this manual,
picking and choosing the things you want to change. Pay particular attention
to the SESSION PROGRAM section,
which will describe how to set up the style of session desired.
xenodm
is highly configurable, and most of
its behavior can be controlled by resource files and shell scripts. The
names of these files themselves are resources read from the file
xenodm-config or the file named by the
-config
option.
xenodm
can manage X servers running on the
local machine and specified in Xservers.
The resources of the X clients run by
xenodm
outside the user's session, including
xenodm
's own login window, can be affected by
setting resources in the Xresources file.
After resetting the X server, xenodm
runs
the Xsetup script to assist in setting up the screen
the user sees along with the xlogin widget.
The xlogin widget, which xenodm
presents,
offers the familiar login and password prompts, unless
autoLogin
is set.
After the user logs in, xenodm
runs the
Xstartup script as root.
Then xenodm
runs the
Xsession script as the user. This system session
file may do some additional startup and typically runs the
.xsession script in the user's home directory. When
the Xsession script exits, the session is over.
At the end of the session, the Xreset script is run to clean up, the X server is reset, and the cycle starts over.
The file /var/log/xenodm.log will contain
error messages from xenodm
and anything output to
stderr
by Xsetup,
Xstartup, Xsession or
Xreset. When you have trouble getting
xenodm
working, check this file to see if
xenodm
has any clues to the trouble.
All of these options, except -config
itself, specify values that can also be specified in the configuration file
as resources.
-config
configuration_filexenodm
.
/etc/X11/xenodm/xenodm-config is the default. See
the section CONFIGURATION
FILE.-nodaemon
false
as the value for the
DisplayManager.daemonMode
resource. This
suppresses the normal daemon behavior, which is for
xenodm
to close all file descriptors, disassociate
itself from the controlling terminal, and put itself in the background
when it first starts up.-debug
debug_levelDisplayManager.debugLevel
resource. A non-zero
value causes xenodm
to print lots of debugging
statements to the terminal; it also disables the
DisplayManager.daemonMode
resource, forcing
xenodm
to run synchronously. To interpret these
debugging messages, a copy of the source code for
xenodm
is almost a necessity. No attempt has been
made to rationalize or standardize the output.-error
error_log_fileDisplayManager.errorLogFile
resource. This file
contains errors from xenodm
as well as anything
written to stderr
by the various scripts and
programs run during the progress of the session.-resources
resource_fileDisplayManager*resources
resource. This file is
loaded using xrdb(1) to
specify configuration parameters for the authentication widget.-server
server_entryDisplayManager.servers
resource. See the section
LOCAL SERVER
SPECIFICATION for a description of this resource.-session
session_programDisplayManager*session
resource. This indicates the program to run as the session after the user
has logged in.-xrm
resource_specificationAt many stages the actions of xenodm
can
be controlled through the use of its configuration file, which is in the X
resource format. Some resources modify the behavior of
xenodm
on all displays, while others modify its
behavior on a single display. 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 local displays, the resource name and class are as read from the Xservers file.
Because the resource manager uses colons to separate the name of
the resource from its value and dots to separate resource name parts,
xenodm
substitutes underscores for both dots and
colons when generating the resource name. For example,
DisplayManager.expo_x_org_0.startup
is the name of
the resource which defines the startup shell file for the
“expo.x.org:0” display.
DisplayManager.servers
DisplayManager.errorLogFile
stderr
by the
Xsetup, Xstartup,
Xsession and Xreset files,
so it will contain descriptions of problems in those scripts as well.DisplayManager.debugLevel
xenodm
, which would normally not be
useful.DisplayManager.daemonMode
xenodm
attempts to make itself into a
daemon process unassociated with any terminal. This is accomplished by
forking and leaving the parent process to exit, then closing file
descriptors and releasing the controlling terminal. In some environments
this is not desired (in particular, when debugging). Setting this resource
to false
will disable this feature.DisplayManager.authDir
xenodm
stores
authorization files while initializing the session. The default value is
/etc/X11/xenodm. Can be overridden for specific
displays by
DisplayManager.
DISPLAY.authFile
.DisplayManager.autoRescan
xenodm
rescans the
configuration, servers, access control and authentication keys files after
a session terminates and the files have changed. By default it is
true
. You can force xenodm
to reread these files by sending a SIGHUP
to the
main process.DisplayManager.exportList
DisplayManager.
DISPLAY.autoLogin
DisplayManager.
DISPLAY.resources
DisplayManager.
DISPLAY.xrdb
xenodm
uses
/usr/X11R6/bin/xrdb.DisplayManager.
DISPLAY.cpp
DisplayManager.
DISPLAY.setup
DisplayManager.
DISPLAY.startup
DisplayManager.
DISPLAY.session
DisplayManager.
DISPLAY.reset
DisplayManager.
DISPLAY.openDelay
DisplayManager.
DISPLAY.openRepeat
DisplayManager.
DISPLAY.openTimeout
DisplayManager.
DISPLAY.startAttempts
DisplayManager.
DISPLAY.reservAttempts
xenodm
when attempting to open intransigent
servers. openDelay
is the length of the pause in
seconds between successive attempts, openRepeat
is
the number of attempts to make, openTimeout
is the
amount of time to wait while actually attempting the open (i.e., the
maximum time spent in the
connect(2) system call)
and startAttempts
is the number of times this
entire process is done before giving up on the server. After
openRepeat
attempts have been made, or if
openTimeout
seconds elapse in any particular
attempt, xenodm
terminates and restarts the
server, attempting to connect again. This process is repeated
startAttempts
times, at which point the display is
declared dead and disabled. Although this behavior may seem arbitrary, it
has been empirically developed and works quite well on most systems. The
bound reservAttempts
is the number of times a
successful connect is allowed to be followed by a fatal error. When
reached, the display is disabled. The default values are
openDelay
: 15, openRepeat
:
5, openTimeout
: 120,
startAttempts
: 4 and
reservAttempts
: 2.DisplayManager.
DISPLAY.terminateServer
false
.DisplayManager.
DISPLAY.userPath
xenodm
sets the PATH
environment variable for the session to this value. It should be a colon
separated list of directories; see
sh(1) for a full description.
The default value is
“/bin:/usr/bin:/sbin:/usr/sbin:/usr/X11R6/bin:/usr/local/bin:/usr/local/sbin”.DisplayManager.
DISPLAY.systemPath
xenodm
sets the PATH
environment variable for the startup and reset scripts to the value of
this resource. The default for this resource is
“/sbin:/usr/sbin:/bin:/usr/bin:/usr/X11R6/bin”. Note the
absence of ‘.
’ from this entry. This
is a good practice to follow for root; it avoids many common Trojan Horse
system penetration schemes.DisplayManager.
DISPLAY.systemShell
xenodm
sets the SHELL
environment variable for the startup and reset scripts to the value of
this resource. It is /bin/sh by default.DisplayManager.
DISPLAY.failsafeClient
xenodm
will fall back to this program. This program is executed with no
arguments, but executes using the same environment variables as the
session would have had (see the section
SESSION PROGRAM). By default,
/usr/X11R6/bin/xterm is used.DisplayManager.
DISPLAY.grabServer
DisplayManager.
DISPLAY.grabTimeout
xenodm
grabs the server and
keyboard while reading the login name and password. The
grabServer
resource specifies if the server should
be held for the duration of the name/password reading. When
false
, the server is ungrabbed after the keyboard
grab succeeds, otherwise the server is grabbed until just before the
session begins. The default is false
. The
grabTimeout
resource specifies the maximum time
xenodm
will wait for the grab to succeed. The grab
may fail if some other client has the server grabbed, or possibly if the
network latencies are very high. This resource has a default value of 3
seconds; you should be cautious when raising it, as a user can be spoofed
by a look-alike window on the display. If the grab fails,
xenodm
kills and restarts the server (if possible)
and the session.DisplayManager.
DISPLAY.authorize
DisplayManager.
DISPLAY.authName
authorize
is a boolean resource which controls whether
xenodm
generates and uses authorization for the
local server connections. If authorization is used,
authName
is a list of authorization mechanisms to
use, separated by white space. When authorize
is
set for a display and authorization is not available, the user is informed
by having a different message displayed in the login widget. By default,
Ic authorize is true
,
authName
is “MIT-MAGIC-COOKIE-1”,
or, if XDM-AUTHORIZATION-1 is available, “XDM-AUTHORIZATION-1
MIT-MAGIC-COOKIE-1”.DisplayManager.
DISPLAY.authFile
xenodm
to the server, using the
-auth
server command line option. It should be
kept in a directory which is not world-writable as it could easily be
removed, disabling the authorization mechanism in the server. If not
specified, a name is generated from DisplayManager.authDir and the name of
the display.DisplayManager.
DISPLAY.authComplain
false
, disables the use of the
unsecureGreeting
in the login window. See the
section AUTHENTICATION
WIDGET. The default is true
.DisplayManager.
DISPLAY.resetSignal
xenodm
sends to reset the
server. See the section
CONTROLLING THE SERVER.
The default is 1 (SIGHUP
).DisplayManager.
DISPLAY.termSignal
xenodm
sends to terminate
the server. See the section
CONTROLLING THE SERVER.
The default is 15 (SIGTERM
).DisplayManager.
DISPLAY.resetForAuth
xenodm
generates the
authorization information just before connecting to the display, an old
server would not get up-to-date authorization information. This resource
causes xenodm
to send
SIGHUP
to the server after setting up the file,
causing an additional server reset to occur, during which time the new
authorization information will be read. The default is
false
, which will work for all MIT servers.DisplayManager.
DISPLAY.userAuthDir
xenodm
is unable to write to the usual user
authorization file ($HOME/.Xauthority), it creates
a unique file name in this directory and points the environment variable
XAUTHORITY
at the created file. It uses
/tmp by default.First, the xenodm
configuration file
should be set up. Make a directory (usually
/etc/X11/xenodm) to contain all of the relevant
files.
Here is a reasonable configuration file, which could be named xenodm-config:
DisplayManager.servers: /etc/X11/xenodm/Xservers DisplayManager.errorLogFile: /var/log/xenodm.log DisplayManager*resources: /etc/X11/xenodm/Xresources DisplayManager*startup: /etc/X11/xenodm/Xstartup DisplayManager*session: /etc/X11/xenodm/Xsession DisplayManager._0.authorize: true DisplayManager*authorize: false
Note that this file mostly contains references to other files.
Note also that some of the resources are specified with
‘*
’ separating the components. These
resources can be made unique for each different display, by replacing the
‘*
’ with the display-name, but
normally this is not very useful. See the
RESOURCES section for a complete
discussion.
The resource DisplayManager.servers
gives
a server specification or, if the value starts with a slash
(‘/
’), the name of a file containing
server specifications, one per line.
Each specification indicates a display which should constantly be
managed. If the resource or the file named by the resource is empty,
xenodm
will exit.
Each specification consists of at least three parts: a display name, a display class, a display type, and a command line to start the server. A typical entry for local display number 0 would be:
The only recognized display type is:
local |
local display: xenodm will run
the server |
The display name must be something that can be passed in the
-display
option to an X program. This string is used
to generate the display-specific resource names, so be careful to match the
names (e.g., use “:0 local /usr/X11R6/bin/X :0” instead of
“localhost:0 local /usr/X11R6/bin/X :0” if your other
resources are specified as “DisplayManager._0.session”). The
display class portion is also used in the display-specific resources, as the
class of the resource. This is useful if you have a large collection of
similar displays (such as a corral of X terminals) and would like to set
resources for groups of them.
When xenodm
starts a session, it sets up
authorization data for the server. For local servers,
xenodm
passes “-auth
filename” on the server's command line to point
it at its authorization data.
The Xresources file is loaded onto the display as a resource database using xrdb(1). As the authentication widget reads this database before starting up, it usually contains parameters for that widget:
xlogin*login.translations: #override\ Ctrl<Key>R: abort-display()\n\ <Key>F1: set-session-argument(failsafe) finish-field()\n\ <Key>Return: set-session-argument() finish-field() xlogin*borderWidth: 3 xlogin*greeting: CLIENTHOST #ifdef COLOR xlogin*greetColor: CadetBlue xlogin*failColor: red #endif
Please note the translations entry; it specifies a few new translations for the widget which allow users to escape from the default session (and avoid troubles that may occur in it). Note that if #override is not specified, the default translations are removed and replaced by the new value, not a very useful result as some of the default translations are quite useful (such as “<Key>: insert-char ()” which responds to normal typing).
This file may also contain resources for the setup program.
The Xsetup file is run after the server is reset, but before the Login window is offered. The file is typically a shell script. It is run as root, so should be careful about security. This is the place to change the root background or bring up other windows that should appear on the screen along with the Login widget.
In addition to any specified by
DisplayManager.exportList
, the following environment
variables are passed:
DISPLAY
PATH
DisplayManager.
DISPLAY.systemPath
SHELL
DisplayManager.
DISPLAY.systemShell
XAUTHORITY
Note that since xenodm
grabs the keyboard,
any other windows will not be able to receive keyboard input. They will be
able to interact with the mouse, however; beware of potential security holes
here. If
DisplayManager.
DISPLAY.grabServer
is set, Xsetup will not be able to connect to the
display at all. Resources for this program can be put into the file named by
DisplayManager.
DISPLAY.resources
.
Here is a sample Xsetup script:
#!/bin/sh # Xsetup_0 - setup script for one workstation xcmsdb < /etc/X11/xenodm/monitors/alex.0 xconsole -geometry 480x130-0-0 -notify -verbose -exitOnFail &
The authentication widget prompts the user for the username,
password, and/or other required authentication data from the keyboard.
Nearly every imaginable parameter can be controlled with a resource.
Resources for this widget should be put into the file named by
DisplayManager.
DISPLAY.resources
.
All of these have reasonable default values, so it is not necessary to
specify any of them.
The resource file is loaded with xrdb(1) so it may use the substitutions defined by that program such as CLIENTHOST for the client hostname in the login message, or C pre-processor #ifdef statements to produce different displays depending on color depth or other variables.
xenodm
is compiled with support for the
Xft(3) library for font
rendering. Font faces are specified using the resources with names ending in
“face” in the fontconfig face format described in the
“Font Names” section of
fonts.conf(5).
xlogin.Login.width
,
xlogin.Login.height
,
xlogin.Login.x
,
xlogin.Login.y
xlogin.Login.foreground
xlogin.Login.face
xlogin.Login.greeting
xlogin.Login.unsecureGreeting
xlogin.Login.greetFace
xlogin.Login.greetColor
xlogin.Login.namePrompt
xlogin.Login.passwdPrompt
xlogin.Login.promptFace
xlogin.Login.promptColor
xlogin.Login.changePasswdMessage
xlogin.Login.fail
xlogin.Login.failFace
xlogin.Login.failColor
xlogin.Login.failTimeout
xlogin.Login.logoFileName
xlogin.Login.logoPadding
xlogin.Login.useShape
true
, when built with XPM support,
attempt to use the X Non-Rectangular Window Shape Extension to set the
window shape. The default is true
.xlogin.Login.hiColor
,
xlogin.Login.shdColor
hiColor
is
the highlight color, used on the top and left sides of the frame, and the
bottom and right sides of text input areas.
shdColor
is the shadow color, used on the bottom
and right sides of the frame, and the top and left sides of text input
areas. The default for both is the foreground color, providing a flat
appearance.xlogin.Login.frameWidth
frameWidth
is the width in pixels of the area around the greeter frame drawn in
hiColor
and shdColor
.xlogin.Login.innerFramesWidth
innerFramesWidth
is the width in pixels of the area around text input areas drawn in
hiColor
and shdColor
.xlogin.Login.sepWidth
sepWidth
is the width in pixels of the bezeled line between the greeting and input
areas drawn in hiColor
and
shdColor
.xlogin.Login.allowRootLogin
false
, don't allow root (and any other
user with uid = 0) to log in directly. The default is
true
. This setting is only checked by some of the
authentication backends at this time.xlogin.Login.allowNullPasswd
true
, allow an otherwise failing
password match to succeed if the account does not require a password at
all. The default is false
, so only users that have
passwords assigned can log in.xlogin.Login.echoPasswd
true
, a placeholder character
(echoPasswdChar
) will be shown for fields normally
set to not echo, such as password input. The default is
false
.xlogin.Login.echoPasswdChar
echoPasswd
is true. The
default is ‘*
’. If set to an empty
value, the cursor will advance for each character input, but no text will
be drawn.xlogin.Login.translations
Ctrl<Key>H: delete-previous-character() \n\ Ctrl<Key>D: delete-character() \n\ Ctrl<Key>B: move-backward-character() \n\ Ctrl<Key>F: move-forward-character() \n\ Ctrl<Key>A: move-to-begining() \n\ Ctrl<Key>E: move-to-end() \n\ Ctrl<Key>K: erase-to-end-of-line() \n\ Ctrl<Key>U: erase-line() \n\ Ctrl<Key>X: erase-line() \n\ Ctrl<Key>C: restart-session() \n\ Ctrl<Key>\\: abort-session() \n\ <Key>BackSpace: delete-previous-character() \n\ <Key>Delete: delete-previous-character() \n\ <Key>Return: finish-field() \n\ <Key>: insert-char() \
The actions which are supported by the widget are:
delete-previous-character
delete-character
move-backward-character
move-forward-character
move-to-begining
move-to-end
erase-to-end-of-line
erase-line
finish-field
xenodm
starts the session. Otherwise the
failure message is displayed and the user is prompted again.abort-session
abort-display
xenodm
on a system console, such as when
shutting the system down, when using
xdmshell(1), to start
another type of server, or to generally access the console. Sending
xenodm
a SIGHUP
will
restart the display. See the section
CONTROLLING XENODM.restart-session
insert-char
set-session-argument
allow-all-access
xenodm
. Be very careful using this; it might
be better to disconnect the machine from the network before doing
this.On some systems (OpenBSD) the user's shell must be listed in /etc/shells to allow login through xenodm. The normal password and account expiration dates are enforced too.
The Xstartup program is run as root when the user logs in. It is typically a shell script. Since it is run as root, Xstartup should be very careful about security. This is the place to put commands which add entries to utmp(5) or wtmp(5) files (the sessreg(1) program may be useful here), mount users' home directories from file servers, or abort the session if logins are not allowed.
In addition to any specified by
DisplayManager.exportList
, the following environment
variables are passed:
DISPLAY
HOME
LOGNAME
USER
PATH
DisplayManager.
DISPLAY.systemPath
SHELL
DisplayManager.
DISPLAY.systemShell
XAUTHORITY
WINDOWPATH
No arguments are passed to the script.
xenodm
waits until this script exits before starting
the user session. If the exit value of this script is non-zero,
xenodm
discontinues the session and starts another
authentication cycle.
The sample Xstartup file shown here prevents login while the file /etc/nologin exists. Thus this is not a complete example, but simply a demonstration of the available functionality.
Here is a sample Xstartup script:
#!/bin/sh # # Xstartup # # This program is run as root after the user is verified # if [ -f /etc/nologin ]; then xmessage -file /etc/nologin -timeout 30 -center exit 1 fi sessreg -a -l $DISPLAY -x /etc/X11/xenodm/Xservers $LOGNAME /etc/X11/xenodm/GiveConsole exit 0
The Xsession program is the command which is run as the user's session. It is run with the permissions of the authorized user.
In addition to any specified by
DisplayManager.exportList
, the following environment
variables are passed:
DISPLAY
HOME
LOGNAME
USER
PATH
DisplayManager.
DISPLAY.userPath
SHELL
XAUTHORITY
WINDOWPATH
At most installations, Xsession should look in $HOME for a file .xsession, which contains commands that each user would like to use as a session. Xsession should also implement a system default session if no user-specified session exists.
An argument may be passed to this program from the authentication
widget using the set-session-argument
action. This
can be used to select different styles of session. One good use of this
feature is to allow the user to escape from the ordinary session when it
fails. This allows users to repair their own
.xsession if it fails, without requiring
administrative intervention. The example following demonstrates this
feature.
This example recognizes the special failsafe mode, specified in the translations in the Xresources file, to provide an escape from the ordinary session. It also requires that the .xsession file be executable so we don't have to guess what shell it wants to use.
#!/bin/sh # # Xsession # # This is the program that is run as the client # for the display manager. case $# in 1) case $1 in failsafe) exec xterm -geometry 80x24-0-0 ;; esac esac startup=$HOME/.xsession resources=$HOME/.Xresources if [ -f "$startup" ]; then exec "$startup" else if [ -f "$resources" ]; then xrdb -load "$resources" fi twm & xman -geometry +10-10 & exec xterm -geometry 80x24+10+10 -ls fi
The user's .xsession file might look something like this example. Don't forget that the file must have execute permission.
#! /bin/csh # no -f in the previous line so .cshrc gets run to set $PATH twm & xrdb -merge "$HOME/.Xresources" emacs -geometry +0+50 & xbiff -geometry -430+5 & xterm -geometry -0+50 -ls
Symmetrical with Xstartup, the Xreset script is run after the user session has terminated. Run as root, it should contain commands that undo the effects of commands in Xstartup, updating entries in utmp(5) or wtmp(5) files, or unmounting directories from file servers. The environment variables that were passed to Xstartup are also passed to Xreset.
A sample Xreset script:
#!/bin/sh # # Xreset # # This program is run as root after the session ends # sessreg -d -l $DISPLAY -x /etc/X11/xenodm/Xservers $LOGNAME /etc/X11/xenodm/TakeConsole exit 0
xenodm
controls local servers using POSIX
signals. SIGHUP
is expected to reset the server,
closing all client connections and performing other cleanup duties.
SIGTERM
is expected to terminate the server. If
these signals do not perform the expected actions, the resources
DisplayManager.
DISPLAY.resetSignal
and
DisplayManager.
DISPLAY.termSignal
can specify alternate signals.
xenodm
responds to two signals:
SIGHUP
and SIGTERM
. When
sent a SIGHUP
, xenodm
rereads the configuration file, the access control file, and the servers
file. For the servers file, it notices if entries have been added or
removed. If a new entry has been added, xenodm
starts a session on the associated display. Entries which have been removed
are disabled immediately, meaning that any session in progress will be
terminated without notice and no new session will be started.
When sent a SIGTERM
,
xenodm
terminates all sessions in progress and
exits. This can be used when shutting down the system.
xenodm
attempts to mark its various
sub-processes for ps(1) by
editing the command line argument list in place. Because
xenodm
can't allocate additional space for this
task, it is useful to start xenodm
with a reasonably
long command line (using the full path name should be enough). Each process
which is servicing a display is marked
-
display.
To add an additional local display, add a line for it to the Xservers file. (See the section LOCAL SERVER SPECIFICATION.)
Examine the display-specific resources in
xenodm-config (e.g.,
DisplayManager._0.authorize
) and consider which of
them should be copied for the new display. The default
xenodm-config has all the appropriate lines for
displays :0 and :1.
You can use xenodm
to run a single session
at a time, using the 4.3
init(8) options or other
suitable daemon by specifying the server on the command line:
One thing that xenodm
isn't very good at
doing is coexisting with other window systems. To use multiple window
systems on the same hardware, you'll probably be more interested in
xinit(1).
xenodm
stores keys
for clients to readsessreg(1), xauth(1), xinit(1), xrdb(1), Xserver(1), fonts.conf(5), X(7), Xsecurity(7)
X Display Manager Control Protocol.
R. Hinden and S. Deering, IP Version 6 Addressing Architecture, RFC 4291, February 2006.
Keith Packard, MIT X Consortium
March 4, 2017 | xenodm 0.1 X Version 11 |