# MDM Display Manager Reference Manual

## Terms and Conventions Used in This Manual

This manual describes version &version; of the MDM Display Manager. It was last updated on &date;.

Configurator - The configuration application (`mdmsetup`).

MDM - MDM Display Manager. Used to describe the software package as a whole. Sometimes also referred to as MDM2.

mdm - The MDM Display Manager daemon (`mdm`).

Greeter - The graphical login window (`mdmlogin` or `mdmgreeter` or `mdmwebkit`).

GTK+ Greeter - The standard login window (`mdmlogin`).

PAM - Pluggable Authentication Mechanism

Themed Greeter - The themable login window (`mdmgreeter`).

Paths that start with a word in angle brackets are relative to the installation prefix. I.e. `<share>/pixmaps/` refers to `<share>/pixmaps` if MDM was configured with `--prefix=/usr`. Normally also note that MDM is installed with `--sysconfigdir=<etc>/X11`, meaning any path to which we refer to as `<etc>/mdm/PreSession` usually means `<etc/X11>/mdm/PreSession`. Note that for interoperability it is recommended that you use a --prefix of `/usr` and a --sysconfdir of `<etc>/X11`.

## Overview

### Introduction

The MDM Display Manager (MDM) is a display manager that implements all significant features required for managing attached and remote displays. MDM was written from scratch and does not contain any XDM / X Consortium code.

Note that MDM is highly configurable, and many configuration settings can affect security. Issues to be aware of are highlighted in this document and in the MDM Configuration files.

### Interface Stability

The key/value pairs defined in the MDM configuration files and the location of these files are considered "stable" interfaces should only change in ways that are backwards compatible. Note that this includes functionality like the MDM scripts (Init, PreSession, PostSession, PostLogin, XKeepsCrashing, etc.); directory locations (ServAuthDir, etc.), system applications (SoundProgram), etc. Some configuration values depend on OS interfaces may need to be modified to work on a given OS. Typical examples are HaltCommand, RebootCommand, CustomCommands, SuspendCommand, StandardXServer, Xnest, SoundProgram, and the "command" value for each `server-foo`.

Command-line interfaces for MDM programs installed to `<bin>` and `<sbin>` are considered stable. Refer to your distribution documentation to see if there are any distribution-specific changes to these MDM interfaces and what support exists for them.

### The MDM Daemon

The MDM daemon is responsible for managing displays on the system. This includes authenticating users, starting the user session, and terminating the user session. MDM is configurable and the ways it can be configured are described in the "Configuring MDM" section of this document. The `Init`, `PostLogin`, `PreSession`, and `PostSession` scripts discussed below are discussed in this "Configuring MDM section".

The MDM daemon supports a UNIX domain socket protocol which can be used to control aspects of its behavior and to query information. This protocol is described in the "Controlling MDM" section of this document.

MDM can be asked to manage a display a number of ways. Attached displays are always managed when MDM starts and will be restarted when a user's session is finished. Remote displays can be requested via XDMCP, flexible displays via the `mdmflexiserver` command, and dynamic displays via the `mdmdynamic` command. Displays that are started on request are not restarted on session exit.

When the MDM daemon is asked to manage a display, it will fork an X server process, then run the `Init` script as the root user, and start the login GUI dialog as a slave process on the display. MDM can be configured to use either `mdmgreeter` (the default) or `mdmlogin` as the GUI dialog program. The `mdmlogin` program supports accessibility while the `mdmgreeter` program supports greater themeability. The GUI dialog is run as the unpriviledged "mdm" user/group which is described in the "Security" section below. The GUI dialog communicates with the daemon via a sockets protocol and via standard input/output. The slave, for example passes the username and password information to the MDM daemon via standard input/output so the daemon can handle the actual authentication.

The login GUI dialog screen allows the user to select which session they wish to start and which language they wish to use. Sessions are defined by files that end in the .desktop extension and more information about these files can be found in the "Configuration" section. The user enters their name and password and if these successfully authenticate, MDM will start the requested session for the user. It is possible to configure MDM to avoid the authentication process by turning on the Automatic or Timed Login features in the MDM configuration. The login GUI can also be configured to provide additional features to the user, such as the Face Browser; the ability to halt, restart, or suspend the system; and/or edit the login configuration (after entering the root password).

MDM uses Pluggable Authentication Modules (PAM) for authentication. After authenticating a user, the daemon runs the `PostLogin` script as root, and forks a slave process to start the requested session. This slave process runs the `PreSession` script as root, sets up the user's environment, and starts the requested session. MDM keeps track of the user's default session and language in the user's `~/.dmrc` and will use these defaults if the user did not pick a session or language in the login GUI. When the user's session exits, the MDM daemon will run the `PostSession` script as root.

Note that, by default, MDM uses the "mdm" service name for normal login and the "mdm-autologin" service name for automatic login. The `PamStack` configuration option can be used to specify a different service name. For example, if "foo" is specified, then MDM will use the "foo" service name for normal login and "foo-autologin" for automatic login.

For those looking at the code, the mdm_verify_user function in `daemon/verify-pam.c` is used for normal login and the mdm_verify_setup_user function is used for automatic login.

### Different Display Types

MDM supports three different display types: attached displays, flexible displays, and XDMCP remote displays. The "X Server Definitions" subsection of the "Configuration" section explains how the X server is configured for different displays.

Attached (also known as local or static) displays are always started by the daemon, and when they die or are killed, they are restarted. MDM can run as many of these as needed. MDM can also manage displays on which it does not manage a GUI login, thus MDM can be used for supporting X terminals. The "Attached DISPLAY Configuration" subsection of the "Configuration" section describes how attached displays are defined.

Flexible (also known as on-demand) displays are only available to users logged on the console. Starting a flexible display will lock the current user session and will show a new login screen over the current running session. If at least one flexible display is already running, and the user requests another, then a dialog will display showing existing flexible displays. The user can choose to switch back to a previous display or start a new flexible display. If the user switches back to a previous display, they will need to enter the password in the lock screen program to return to their session. The MDM configuration file specifies the maximum number of flexible displays allowed on the system.

Flexible displays may be started by running the `mdmflexiserver` command, or via calling the MDM socket protocol directly. Some lock screen programs provide a button to start a new flexible session. This allows a user to start a new session even if the screen was left locked. Flexible displays are not restarted when the user session ends. Flexible displays require virtual terminal (VT) support in the kernel.

The `FlexibleXServers`, `FirstVT=7`, `VTAllocation`, and `FlexiReapDelayMinutes` configuration settings are used to configure how flexible displays operate.

Nested displays are available to users even if not logged in on the console. Nested displays launch a login screen in a window in the user's current session. This can be useful if the user has more than one account on a machine and wishes to login to the other account without disrupting their current session. Nested displays may be started by running the `mdmflexiserver -n` command or via calling the MDM socket protocol directly. Nested displays require that the X server supports a nested X server command like Xnest or Xephyr. The `Xnest` configuration option is used to configure how nested displays are started.

The `mdmdynamic` is similar to `mdmflexiserver` in the sense that it allows the user to manage displays dynamically. However displays started with `mdmdynamic` are treated as attached displays, so they are restarted automatically when the session exits. This command is intended to be used in multi-user server environments (many displays connected to a single server). In other words, this command allows the displays to be managed without hardcoding the display information in the "Attached DISPLAY Configuration" section of the configuration file. This is useful to support the ability of adding new displays to the server without needing to restart MDM, for example.

The last display type is the XDMCP remote displays which are described in the next section. Remote hosts can connect to MDM and present the login screen if this is enabled. Some things are different for remote sessions. For example, the Actions menu which allows you to shut down, restart, suspend, or configure MDM are not shown.

### XDMCP

The MDM daemon can be configured to listen for and manage X Display Manage Protocol (XDMCP) requests from remote displays. By default XDMCP support is turned off, but can be enabled if desired. If MDM is built with TCP Wrapper support, then the daemon will only grant access to hosts specified in the MDM service section in the TCP Wrappers configuration file.

MDM includes several measures making it more resistant to denial of service attacks on the XDMCP service. A lot of the protocol parameters, handshaking timeouts etc. can be fine tuned. The defaults should work for most systems, however. Do not change them unless you know what you are doing.

MDM listens to UDP port 177 and will respond to QUERY and BROADCAST_QUERY requests by sending a WILLING packet to the originator.

MDM can also be configured to honor INDIRECT queries and present a host chooser to the remote display. MDM will remember the user's choice and forward subsequent requests to the chosen manager. MDM also supports an extension to the protocol which will make it forget the redirection once the user's connection succeeds. This extension is only supported if both daemons are MDM. It is transparent and will be ignored by XDM or other daemons that implement XDMCP.

If XDMCP seems to not be working, make sure that all machines are specified in `/etc/hosts`.

Refer to the "Security" section for information about security concerns when using XDMCP.

### Securing Remote Connection Through SSH

As explained in the "Security" section, XDMCP does not use any kind of encryption and as such is inherently insecure. As XDMCP uses UDP as a network transport layer, it is not possible to simply secure it through an SSH tunnel.

To remedy this problem, MDM can be configured at compilation-time with the option --enable-secureremote, in which case MDM proposes as a built-in session a session called "Secure Remote Connection". Starting such a session allows the user to enter the name or the address of the host on which to connect; provided the said host runs an SSH server, the user then gets connected to the server on which the default X session is started and displayed on the local host.

Using this session allows a much more secure network connection and only necessitates to have an SSH server running on the remote host.

### The GTK+ Greeter

The GTK+ Greeter is the default graphical user interface that is presented to the user. The greeter contains a menu at the top, an optional face browser, an optional logo and a text entry widget. This greeter has full accessibility support, and should be used by users with accessibility needs.

The text entry field is used for entering logins, passwords, passphrases etc. `mdmlogin` is controlled by the underlying daemon and is basically stateless. The daemon controls the greeter through a simple protocol where it can ask the greeter for a text string with echo turned on or off. Similarly, the daemon can change the label above the text entry widget to correspond to the value the authentication system wants the user to enter.

The menu bar in the top of the greeter enables the user to select the requested session type/desktop environment, select an appropriate locale/language, halt/restart/suspend the computer, configure MDM (given the user knows the root password), change the GTK+ theme, or start an XDMCP chooser.

The greeter can optionally display a logo in the login window. The image must be in a format readable to the gdk-pixbuf library (GIF, JPG, PNG, TIFF, XPM and possibly others), and it must be readable to the MDM user. See the `Logo` option in the reference section below for details.

### The GDM Greeter

The GDM Greeter is a greeter interface that takes up the whole screen and is very themable. Themes can be selected and new themes can be installed by the configuration application or by setting the `GraphicalTheme` configuration key. The Themed Greeter is much like the GTK+ Greeter in that it is controlled by the underlying daemon, is stateless, and is controlled by the daemon using the same simple protocol.

The look and feel of this greeter is really controlled by the theme and so the user interface elements that are present may be different. The only thing that must always be present is the text entry field as described above in the GTK+ Greeter. The theme can include buttons that allow the user to select an appropriate locale/language, halt/restart/suspend the computer, configure MDM (given the user knows the root password), or start an XDMCP chooser.

You can always get a menu of available actions by pressing the F10 key. This can be useful if the theme doesn't provide certain buttons when you wish to do some action allowed by the MDM configuration.

### The MDM Face Browser

MDM supports a face browser which will display a list of users who can login and an icon for each user. Starting with version 2.18.1 the `Browser` configuration option must be set to "true" for this function to be available. In previous versions it was only required when using the GTK+ Greeter. When using the Themed Greeter, the Face Browser is only available if the MDM theme includes a "userlist" item type.

By default, the face browser is disabled since revealing usernames on the login screen is not appropriate on many systems for security reasons. Also MDM requires some setup to specify which users should be visible. Setup can be done on the "Users" tab in `mdmsetup`. This feature is most practical to use on a system with a smaller number of users.

The icons used by MDM can be installed globally by the sysadmin or can be located in the users' home directories. If installed globally they should be in the `<share>/pixmaps/faces/` directory (though this can be configured with the `GlobalFaceDir` configuration option) and the filename should be the name of the user, optionally with a `.png` appended. Face icons placed in the global face directory must be readable to the MDM user. However, the daemon, proxies user pictures to the greeter and thus those do not have be be readable by the "mdm" user, but root.

Users may run the `mdmphotosetup` command to configure the image to use for their userid. This program properly scales the file down if it is larger than the `MaxIconWidth` or `MaxIconHeight` configuration options and places the icon in a file called `~/.face`. Although `mdmphotosetup` scales user images automatically, this does not guarantee that user images are properly scaled since a user may create their `~/.face` file by hand.

MDM will first look for the user's face image in `~/.face`. If not found, it will try `~/.face.icon`. If still not found, it will use the value defined for "face/picture=" in the `~/.gnome2/mdm` file. Lastly, it will try `~/.gnome2/photo` and `~/.gnome/photo` which are deprecated and supported for backwards compatibility.

If a user has no defined face image, MDM will use the "stock_person" icon defined in the current GTK+ theme. If no such image is defined, it will fallback to the image specified in the `DefaultFace` configuration option, normally `<share>/pixmaps/nobody.png`.

Please note that loading and scaling face icons located in user home directories can be a very time-consuming task. Since it not practical to load images over NIS or NFS, MDM does not attempt to load face images from remote home directories. Furthermore, MDM will give up loading face images after 5 seconds of activity and will only display the users whose pictures it has gotten so far. The `Include` configuration option can be used to specify a set of users who should appear on the face browser. As long as the users to include is of a reasonable size, there should not be a problem with MDM being unable to access the face images. To work around such problems, it is recommended to place face images in the directory specified by the `GlobalFaceDir` configuration option.

To control the users who get displayed in the face browser, there are a number of configuration options that can be used. If the `IncludeAll` option is set to true, then the password file will be scanned and all users will be displayed. If `IncludeAll` option is set to false, then the `Include` option should contain a list of users separated by commas. Only the users specified will be displayed. Any user listed in the `Exclude` option and users whose UID's is lower than `MinimalUID` will be filtered out regardless of the `IncludeAll` setting. `IncludeAll` is not recommended for systems where the passwords are loaded over a network (such as when NIS is used), since it can be very slow to load more than a small number of users over the network..

When the browser is turned on, valid usernames on the computer are inherently exposed to a potential intruder. This may be a bad idea if you do not know who can get to a login screen. This is especially true if you run XDMCP (turned off by default).

### Logging

MDM itself will use syslog to log errors or status. It can also log debugging information, which can be useful for tracking down problems if MDM is not working properly. This can be enabled in the configuration file.

Output from the various X servers is stored in the MDM log directory, which is configurable, but is usually `<var>/log/mdm/`. The output from the session can be found in a file called `<display>.log`. Four older files are also stored with `.1` through `.4` appended. These will be rotated as new sessions on that display are started. You can use these logs to view what the X server said when it started up.

The output from the user session is redirected to `~/.xsession-errors` before even the `PreSession` script is started. So it is not really necessary to redirect this again in the session setup script. As is usually done. If the user session lasted less then 10 seconds, MDM assumes that the session crashed and allows the user to view this file in a dialog before returning to the login screen. This way the user can view the session errors from the last session and correct the problem this way.

You can suppress the 10 second warning by returning code 66 from the `Xsession`script or from your session binary (the default `Xsession` script propagates those codes back). This is useful if you have some sort of special logins for which it is not an error to return less then 10 seconds later, or if you setup the session to already display some error message and the MDM message would be confusing and redundant.

The session output is piped through the MDM daemon and so the `~/.xsession-errors` file is capped at about 200 kilobytes by MDM to prevent a possible denial of service attack on the session. An application could perhaps on reading some wrong data print out warnings or errors on the stderr or stdout. This could perhaps fill up the user's home directory making it necessary to log out and back into their session to clear this. This could be especially nasty if quotas are set. MDM also correctly traps the XFSZ signal and stops writing the file, which would lead to killed sessions if the file was redirected in the old fashioned way from the script.

Note that some distributors seem to override the `~/.xsession-errors` redirection and do it themselves in their own Xsession script (set by the `BaseXsession` configuration key) which means that MDM will not be able to trap the output and cap this file. You also lose output from the `PreSession` script which can make debugging things harder to figure out as perhaps useful output of what is wrong will not be printed out. See the description of the `BaseXsession` configuration key for more information, especially on how to handle multiple display managers using the same script.

Note that if the session is a failsafe session, or if MDM can't open this file for some reason, then a fallback file will be created in the `/tmp` directory named `/tmp/xses-<user>.XXXXXX` where the `XXXXXX` are some random characters.

If you run a system with quotas set, it would be good to delete the `~/.xsession-errors` in the `PostSession` script. Such that this log file doesn't unnecessarily stay around.

### Accessing Files

In general MDM is very reluctant regarding reading/writing of user files (such as the `~/.dmrc`, `~/.face`, `~/.xsession-errors`, and `~/.Xauthority` files). For instance it refuses to access anything but regular files. Links, sockets and devices are ignored. The value of the `RelaxPermissions` parameter determines whether MDM should accept files writable by the user's group or others. These are ignored by default.

All operations on user files are done with the effective user id of the user. If the sanity check fails on the user's `.Xauthority` file, a fallback cookie is created in the directory specified by the `UserAuthFBDir` configuration setting (`/tmp` by default).

Finally, the sysadmin can specify the maximum file size MDM should accept, and, if the face browser is enabled, a tunable maximum icon size is also enforced. On large systems it is still advised to turn off the face browser for performance reasons. Looking up icons in home directories, scaling and rendering face icons can take a long time.

### MDM Performance

To speed performance it is possible to build MDM so that it will preload libraries when MDM first displays a greeter program. This has been shown to speed first time login since these libraries can be loaded into memory while the user types in their username and password.

To use this feature, configure MDM with the `--with-prefetch` option. This will cause MDM to install the `mdmprefetch` program to the `libexecdir` directory, install the `mdmprefetchlist` to the `<etc>/mdm` directory, and set the `PreFetchProgram` configuration variable so that the `mdmprefetch` program is called with the default `mdmprefetchlist` file. The default `mdmprefetchlist` file was optimized for a GNOME desktop running on Solaris, so may need fine-tuning on other systems. Alternative prefetchlist files can be contributed to the "mdm" category in bugzilla.gnome.org, so that they can be included in future MDM releases.

## Security

### PAM

MDM uses PAM for login authentication, though if your machine does not support PAM you can build MDM to work with the password database and the crypt library function.

PAM stands for Pluggable Authentication Module, and is used by most programs that request authentication on your computer. It allows the administrator to configure different authentication behavior for different programs.

Some MDM features (like turning on automatic login) may require that you update your PAM configuration. PAM configuration has different, but similar, interfaces on different operating systems, so check your pam.d or pam.conf man page for details. Be sure that you read the PAM documentation (e.g. pam.d/pam.conf man page) and are comfortable with the security implications of any changes you intend to make to your configuration.

If there is no entry for MDM in your system's PAM configuration file, then features like automatic login may not work. Not having an entry will cause MDM to use default behavior, conservative settings are recommended and probably shipped with your distribution.

If you wish to make MDM work with other types of authentication mechanisms (such as a SmartCard), then you should implement this by using a PAM service module for the desired authentication type rather than by trying to modify the MDM code directly. Refer to the PAM documentation on your system. This issue has been discussed on the

    mdm-list@gnome.org

mail list, so you can refer to the list archives for more information.

For example, an effective way to implement such an exotic authentication mechanism would be to have a daemon running on the server listening to the authentication device (e.g. USB key, fingerprint reader, etc.). When the device announces that it has received input, then the daemon can set the `PamStack` configuration value using per-display configuration, and restart the greeter with the PAM stack that works with this device. This avoids needing to hack the display manager code directly to support the feature.

### utmp/wtmp

MDM generates utmp and wtmp User Accounting Database entries upon session login and logout. The utmp database contains user access and accounting information that is accessed by commands such as `finger`, `last`, `login`, and `who`. The wtmp database contains the history of user access and accounting information for the utmp database.

MDM 2.18 and earlier would run the X server `sessreg` program from the default MDM `PreSession` and `PostSession` scripts. Starting with MDM 2.20, MDM interacts with the UTMP and WTMP databases directly and supports the following configuration options.

When doing utmp processing, MDM supports configurability on how the ut_line value is set. Programs that access the database assume that this value is an actual device, so MDM will set the device as follows. If the display is attached and has an associated Virtual Terminal (VT) device, then this device will be used. Otherwise, if an attached display in the `[servers]` specifies a device name, then this value will be used. Otherwise attached displays will default to the `UtmpLineAttached` value in the MDM configuration. Remote displays will default to the `UtmpLineRemote` value in the MDM configuration. Device values must begin with "/dev/".

MDM also supports the `UtmpPseudoDevice` configuration option. If this configuration setting is true, then MDM will ensure that the specified device exists and will create a pseudo device if the device does not exist. A pseudo device is a symlink to `/dev/null`. If `UtmpPseudoDevice` is true, and the device does already exist, MDM checks to see if the device is a symlink to `/dev/null`. If so, then MDM will update the access time of the symlink. This ensures that programs that check the access time of the device will get a reasonable value for the last time the device was accessed. If the `UtmpPseudoDevice` configuration option is false, then MDM will only set the ut_line value as specified regardless of whether the device exists or not.

### The MDM User

For security reasons a dedicated user and group id are required for proper operation! The need to be able to write Xauth files is why user "nobody" is not appropriate for mdm.

The MDM daemon normally runs as root, as does the slave. However MDM should also have a dedicated user id and a group id which it uses for its graphical interfaces such as `mdmgreeter` and `mdmlogin`. These are configured via the `User` and `Group` configuration options in the MDM configuration files. The user and group should be created before running "make install". By default MDM assumes the user and the group are called "mdm".

This userid is used to run the MDM GUI programs required for login. All functionality that requires root authority is done by the MDM daemon process. This design ensures that if the GUI programs are somehow exploited, only the dedicated user privileges are available.

It should however be noted that the MDM user and group have some privileges that make them somewhat dangerous. For one, they have access to the X server authorization directory. It must be able to read and write Xauth keys to `<var>/lib/mdm`. This directory should have root:mdm ownership and 1770 permissions. Running "make install" will set this directory to these values. The MDM daemon process will reset this directory to proper ownership/permissions if it is somehow not set properly.

The danger is that someone who gains the MDM user/group privileges can then connect to any session. So you should not, under any circumstances, make this some user/group which may be easy to get access to, such as the user `nobody`. Users who gain access to the "mdm" user could also modify the Xauth keys causing Denial-Of-Service attacks. Also if a person gains the ability to run programs as the user "mdm", it would be possible to snoop on running MDM processes, including usernames and passwords as they are being typed in.

Distributions and system administrators using MDM are expected to setup the dedicated user properly. It is recommended that this userid be configured to disallow login and to not have a default shell. Distributions and system administrators should set up the filesystem to ensure that the MDM user does not have read or write access to sensitive files.

### X Server Authentication Scheme

The X server authorization directory (the `ServAuthDir`) is used for a host of random internal data in addition to the X server authorization files, and the naming is really a relic of history. MDM daemon enforces this directory to be owned by `root.mdm` with the permissions of 1770. This way, only root and the MDM group have write access to this directory, but the MDM group cannot remove the root owned files from this directory, such as the X server authorization files.

MDM by default doesn't trust the X server authorization directory and treats it in the same way as the temporary directory with respect to creating files. This way someone breaking the MDM user cannot mount attacks by creating links in this directory. Similarly the X server log directory is treated safely, but that directory should really be owned and writable only by root.

MDM only supports the MIT-MAGIC-COOKIE-1 X server authentication scheme. Normally little is gained from the other schemes, and no effort has been made to implement them so far. Be especially careful about using XDMCP because the X server authentication cookie goes over the wire as clear text. If snooping is possible, then an attacker could simply snoop your authentication password as you log in, regardless of the authentication scheme being used. If snooping is possible and undesirable, then you should use ssh for tunneling an X connection rather then using XDMCP. You could think of XDMCP as a sort of graphical telnet, having the same security issues.

On the upside, MDM's random number generation is very conservative and MDM goes to extraordinary measures to truly get a 128 bit random number, using hardware random number generators (if available), plus the current time (in microsecond precision), a 20 byte array of pseudorandom numbers, process pid's, and other random information (possibly using `/dev/audio` or `/dev/mem` if hardware random generators are not available) to create a large buffer and then run MD5 digest on this. Obviously, all this work is wasted if you send this cookie over an open network or store it on an NFS directory (see `UserAuthDir` configuration key). So be careful about where you use remote X display.

### Firewall Security

Even though MDM tries to outsmart potential attackers trying to take advantage of XDMCP, it is still advised that you block the XDMCP port (normally UDP port 177) on your firewall unless you really need it. MDM guards against DoS (Denial of Service) attacks, but the X protocol is still inherently insecure and should only be used in controlled environments. Also each remote connection takes up lots of resources, so it is much easier to DoS via XDMCP then a webserver.

It is also wise to block all of the X Server ports. These are TCP ports 6000 + the display number of course) on your firewall. Note that MDM will use display numbers 20 and higher for flexible on-demand servers.

X is not a very safe protocol for leaving on the net, and XDMCP is even less safe.

### MDM Security With NFS

Note that NFS traffic really goes "over the wire" and thus can be snooped. When accessing the user's X authorization file (`~/.Xauthority`), MDM will try to open the file for reading as root. If it fails, MDM will conclude that it is on an NFS mount and it will automatically use `UserAuthFBDir`, which by default is set to `/tmp`. This behavior can be changed by setting the `NeverPlaceCookiesOnNFS` in the `[security]` section to false.

### XDMCP Security

Even though your display is protected by cookies, XEvents and thus keystrokes typed when entering passwords will still go over the wire in clear text. It is trivial to capture these.

XDMCP is primarily useful for running thin clients such as in terminal labs. Those thin clients will only ever need the network to access the server, and so it seems like the best security policy to have those thin clients on a separate network that cannot be accessed by the outside world, and can only connect to the server. The only point from which you need to access outside is the server.

The above sections "X Server Authentication Scheme" and "Firewall Security" also contain important information about using XDMCP securely. The next section also discusses how to set up XDMCP access control.

To workaround the inherent insecurity of XDMCP, mdm proposes a default built-in session that uses SSH to encrypt the remote connection. See the section "Securing remote connection through SSH" above.

### XDMCP Access Control

XDMCP access control is done using TCP wrappers. It is possible to compile MDM without TCP wrappers however, so you should test your configuration and verify that they work.

You should use the daemon name `mdm` in the `<etc>/hosts.allow` and `<etc>/hosts.deny` files. For example to deny computers from `.evil.domain` from logging in, then add

    mdm: .evil.domain

to `<etc>/hosts.deny`. You may also need to add

    mdm: .your.domain

to your `<etc>/hosts.allow` if you normally disallow all services from all hosts. See the hosts.allow(5) man page for details.

### RBAC (Role Based Access Control)

If MDM is compiled with RBAC support, then the `RBACSystemCommandKeys` configuration option can be used to specify the RBAC key to be used to determine if the user has authority to use commands. This is supported for the Shutdown, Reboot, Suspend, and Custom Commands that appear in the MDM greeter and via the `mdmflexiserver` QUERY_LOGOUT_ACTION, SET_LOGOUT_ACTION, and SET_SAFE_LOGOUT_ACTION commands. The greeter will only display the option if the mdm user (specified by the `User` configuration option) has permission via RBAC. Users will only be able to use the `mdmflexiserver` commands if the user has permission via RBAC.

## Support for ConsoleKit

MDM includes support for publishing user login information with the user and login session accounting framework known as ConsoleKit. ConsoleKit is able to keep track of all the users currently logged in. In this respect, it can be used as a replacement for the utmp or utmpx files that are available on most Unix-like operating systems.

When MDM is about to create a new login process for a user it will call a privileged method of ConsoleKit in order to open a new session for this user. At this time MDM also provides ConsoleKit with information about this user session such as: the user ID, the X11 Display name that will be associated with the session, the host-name from which the session originates (useful in the case of an XDMCP session), whether or not this session is attached, etc. As the entity that initiates the user process, MDM is in a unique position know and to be trusted to provide these bits of information about the user session. The use of this privileged method is restricted by the use of D-Bus system message bus security policy.

In the case where a user with an existing session and has authenticated at MDM and requests to resume that existing session MDM calls a privileged method of ConsoleKit to unlock that session. The exact details of what happens when the session receives this unlock signal is undefined and session-specific. However, most sessions will unlock a screensaver in response.

When the user chooses to log out, or if MDM or the session quit unexpectedly the user session will be unregistered from ConsoleKit.

If support for ConsoleKit is not desired it can be disabled at build time using the "--with-console-kit=no" option when running configure.

## Using mdmsetup To Configure MDM

The `mdmsetup` application can be used to configure MDM. If you believe running root-owned GUI's causes security risk, then you would want to always edit the files by hand and not use `mdmsetup`. Editing the files by hand is explained in the "Configuration" section of this document. Note that `mdmsetup` does not support changing of all configuration variables, so it may be necessary to edit the files by hand for some configurations.

The `mdmsetup` program has five tabs: Local, Remote, Accessibility, Security, and Users, described below. In parenthesis is information about which MDM configuration key is affected by each GUI choice. Refer to the "Configuration" section of this manual and the comments in the MDM System Defaults Configuration File for additional details about each key.

### Local Tab

The Local tab is used for controlling the appearance of MDM for attached (also known as local or static) displays. Attached displays are non-XDMCP remote connections, for example. The choices available in this tab depend on the setting of the "Style" combobox. This combobox is used to determine whether the "Plain" or "Themed" greeter GUI is used. The differences between these greeter programs are explained in the "Overview" section of this document.

If the "Style" choice is "Plain", then MDM will use the `mdmlogin` program as the GUI (daemon/Greeter). When this choice is selected, `mdmsetup` allows the user to select whether the background is an image or solid color (greeter/BackgroundType). If image is selected, there is a file selection button to pick the image file (greeter/BackgroundImage) and a checkbox to scale the image to fit the screen (greeter/BackgroundImageScaleToFit). If solid color is selected, there is a button available to allow the color selection (greeter/BackgroundColor). Also, the user may select the logo image that appears in mdmlogin (greeter/Logo).

If the "Style" choice is "Plain with face browser", then the `mdmlogin` program is used as the GUI (daemon/Greeter) and the face browser is turned on (greeter/Browser). The Face Browser is explained in the "Overview" section. Otherwise, the choices are the same as when the "Style" choice is "Plain". Additional setup in the Users tab may be necessary to choose which users appear in the Face Browser.

If the "Style" choice is "Themed", then the `mdmgreeter` program is used as the GUI (daemon/Greeter). When this choice is selected, `mdmsetup` allows the user to select the theme to be used (greeter/GraphicalTheme). Note that the checkbox to the left of the theme's name must be checked for a theme to be selected. Information about the theme's author and copyright are shown for the highlighted theme. The "Remove" button can be used to delete the highlighted theme. The "Add" button can be used to add new themes to the system. For a new theme to be added it must be in tar or compressed tar format. The "Background color" displayed when MDM starts (and if the theme has transparent elements) can be selected (greeter/GraphicalThemedColor). The "Theme" combo box may be set to "Random from selected" to display a random theme for each login (greeter/GraphicalThemeRand and greeter/GraphicalThemes). To use random themes, select each theme that you wish to be displayed. By default this combobox is set to "Selected only", so that only a single theme may be selected and be used.

If the "Style" choice is "Themed with face browser", then the `mdmgreeter` program is used as the GUI (daemon/Greeter) and the face browser is turned on (greeter/Browser) if supported by the theme. The Face Browser is explained in the Overview section. Otherwise, the choices are the same as when the "Style" choice is "Themed". Additional setup in the Users tab may be necessary to choose which users appear in the Face Browser.

Regardless of the "Style" choice, the user may also select whether the Actions menu is visible (greeter/SystemMenu), whether the Actions menu includes the choice to start `mdmsetup` (greeter/ConfigAvailable), and whether the Action menu includes the choice to start `mdmchooser` to run a remote XDMCP login session (greeter/ChooserButton). The welcome message for attached DISPLAYS may be specified (greeter/DefaultWelcome and greeter/Welcome). The welcome message may contain the character sequences described in the "Text Node" subsection of the "Themed Greeter" section of this manual. These character sequences allow the welcome message to contain things like the display or host name.

### Remote Tab

The Remote tab controls the appearance of the MDM for users logging in via XDMCP. By default XDMCP is disabled, and users should be comfortable with the XDMCP-related sections of the Security section of this document before enabling it. This tab includes a "Style" combobox which can be used to turn on XDMCP and control the appearance of MDM for remote users (gui/RemoteGreeter and xdmcp/Enable). The user may specify to use either the same greeter as used on the Local tab, or the other Greeter program. If the Face Browser setting is true on the Local tab, then it will also be true for the Remote tab. If the Face Browser setting is false on the Local tab, then it will also be false for the Remote tab. It is recommended that the "Plain" GUI be used for remote connections since it is more lightweight and tends to have better performance across a network.

If Remote login is enabled, then the welcome message for remote DISPLAYs may be specified (greeter/DefaultRemoteWelcome and greeter/RemoteWelcome). This welcome message is separate from the one shown for attached displays defined in the Local tab and can have a different value. The welcome message may contain the character sequences described in the "Text Node" subsection of the "Themed Greeter" section of this manual. These character sequences allow the welcome message to contain things like the display or host name.

If the "Style" choice is "Same as Local" and the local selection is "Plain" or "Plain with face browser", then the user may select whether background images should be displayed for remote logins (greeter/BackgroundRemoteOnlyColor).

If the "Style" choice is enabled and set to a different value than the Local tab, then the user has the same configuration choices as found on the Local tab except that the System Menu choices are not available since this is never available for remote logins for security purposes.

If Remote login is enabled, there is a "Configure XDMCP" button which displays a dialog allowing the user to set XDMCP configuration, including whether indirect requests are honored (xdmcp/HonorIndirect), UDP port (xdmcp/Port), maximum pending requests (xdmcp/MaxPending), maximum pending indirect requests (xmdcp/MaxPendingIndirect), maximum remote sessions (xdmcp/MaxSessions), maximum wait time (xdmcp/MaxWait), maximum indirect wait time (xdmcp/MaxWaitIndirect), displays per host (xdmcp/DisplaysPerHost), and ping interval (xdmcp/PingIntervalSeconds). The default settings are standard settings and should only be changed by someone who understands the ramifications of the change.

### Accessibility Tab

The Accessibility tab is used to turn on Accessibility features in MDM. "Enable accessible login" (daemon/AddGtkModules and daemon/GtkModulesList) turns on MDM's gesture listeners which are explained in the "Accessibility" section of this document. There is also a checkbox to allow users to change the theme when using the Plain greeter (gui/AllowGtkThemeChange). This feature allows MDM users to switch the theme to the HighContrast or LowContrast themes if needed. The user may also select whether MDM should play a sound when the login screen is ready, when login is successful and when login has failed. File chooser buttons are used to select the sound file to be played, and the "Play" button can be used to sample the sound.

### Security Tab

The Security tab allows the user to turn on Automatic and Timed login, which user is logged in via an automatic or timed login, and the timed login delay (daemon/AutomaticLoginEnable, daemon/AutomaticLogin, daemon/TimedLoginEnable, daemon/TimedLogin, and daemon/TimedLoginDelay). If automatic login is turned on, then the specified user will immediately log in on reboot without MDM asking for username/password. If the user logs out of their session, MDM will start and ask for username and password to log back in. If TimedLogin is turned on, then MDM will log into the specified user after a specified number of seconds. The user may enable Timed Login for remote (XDMCP) connections by checking the "Allow remote timed logins" checkbox.

On this tab, the user may select whether the system administrator user can log in, and whether the system administrator user can log in via remote (XDMCP) connections (security/AllowRoot and security/AllowRemoteRoot). The user may turn on MDM debug (debug/Enable) which causes debug messages to be sent to the system log. Debug should only be used when diagnosing a problem and not be left on when not needed. The "Deny TCP connections to X server" choice will disable X forwarding if selected (security/DisallowTCP). A login retry delay (security/RetryDelay) can be set to cause MDM to wait a number of seconds after a failed login.

The "Configure X Server" button can be used to specify how MDM manages each display. The "Servers" combobox shows what server definitions are available (Standard, Terminal, and Chooser by default). Refer to the "X Server Definitions" section of the "Configuration" section for more information about how to create new Server Definitions.

For any server type, the user may modify the "Server Name" (server/name), the "Command" (server/command) to be used to launch the X server, whether the server type will "Launch" (server/chooser) the greeter or chooser GUI after starting the X server, whether MDM handles this type (normally only set to false when logging into a Terminal session type), and whether the session type supports "Flexible" (server/flexible) sessions.

The "Servers To Start" section shows what server type is displayed for each display on the machine. Users may click on the "Add/Modify" button to add a new display to the list or to modify a selected display. This simply corresponds each physical display with the Server Definition to be used for managing that display. The "Remove" button may be used to remove a display from the list.

### Users Tab

The Users tab controls which users appear in the Face Browser. If the "Include all users from /etc/password" checkbox is selected, then all users (with a userid above greeter/MinimalUID and not in the Exclude list) are displayed. If this checkbox is not selected, then users must be added to the "Include" list. Users in the "Exclude" list are never displayed. The "Add" and "Remove" buttons are used to add a new user to the list or remove a selected user from the list. The "Apply User Changes" button must be pressed after the "Include" and "Exclude" lists have been modified. The left and right arrow buttons between the "Include" and "Exclude" lists can be used to move a selected user from one list to the other.

## Configuration

MDM has powerful configuration management. System default configuration is stored in the MDM System Defaults Configuration File and user changes to the default configuration are stored in the MDM Custom Configuration File. This allows sysadmins to store the MDM System Defaults Configuration File on a shared filesystem, so a single file can be used to control configuration for multiple machines. MDM also supports per-display configuration for GUI-related keys.

The `mdmsetup` is a GUI program you can use to edit the MDM configuration. This program may also be launched directly from the login screen if the greeter/ConfigAvailable key is set to "true" Not all keys in the MDM configuration file are supported in the GUI, so you may need to edit the configuration files by hand to edit these keys. If you believe running root-owned GUI's causes security risk, then you would want to always edit the files by hand. This program does not support setting per-display configuration, so per-display configuration files must be set up by hand.

Aside from the MDM System Defaults Configuration File, the other MDM configuration files are located, by default, in the `<etc>/mdm/` folder or its subdirectories. Note that the location of many configuration files are defined in the MDM configuration files, so check the MDM System Defaults Configuration File and the MDM Custom Configuration File if the files are not in the locations specified in this document.

Listing of the config directory contents:

    custom.conf
    locale.alias
    Xsession
    XKeepsCrashing
    modules/
    Init/
    PostLogin/
    PreSession/
    PostSession/

`locale.alias` is a file which looks much like the system locale alias but, in fact, is not the same. This is a list of all languages that may be on your system. All languages are checked to see if they exist before displaying them in the Language Selection dialog in the login GUI. Only those that exist are displayed.

`Xsession` is a script which sets up a user session and then executes the user's choice of session. Note that the session script is typically started via the `desktop` file associated with the session the user has picked. Some sessions may start the user's session via a different mechanism than the `Xsession` script, so please check the appropriate `desktop` before assuming a session startup issue is being caused by this file.

`XKeepsCrashing` is a script which gets run when the X server keeps crashing and we cannot recover. The shipped default script will work with most Linux distributions and can run the X configuration application provided the person on the console knows the root password.

Accessibility modules are configured in the `modules/` subdirectory, and are a separate topic. Read the default files provided, they have adequate documentation. Again normally the default install is given in the files with `factory` in their name, and those files are not read, they are just there for you so you can always revert to default config.

Files describing available MDM session follow the freedesktop.org desktop file specification. The `.desktop`-style files are installed to `<etc>/X11/sessions/`. This directory is also read by the KDE desktop manager (KDM) for common configuration. Next the directory `<share>/mdm/BuiltInSessions/` is read for MDM specific built-in sessions (KDM hardcodes these at time of this writing). Lastly the default setup will also read `<share>/xsessions/` (which should be `<share>/xsessions/` if you really wish to cooperate with KDM) where desktop packages can install their session files. The directories under the `<etc>` should be reserved for configuration. The desktop file specification approach makes it easy for package management systems to install window managers and different session types without requiring the sysadmin to edit files. See the `SessionDesktopDir` configuration key for changing the paths. It used to be that MDM stored its built in sessions in `<etc>/dm/Sessions/` but this is deprecated as of 2.5.90.0. Note that prior to version 2.4.4.2 only the `<etc>/dm/Sessions/` was being read.

A session can be disabled (if it was installed in `<share>/xsessions/`) by adding an identically named `.desktop` to one of the directories earlier in the path (likely `<etc>/X11/sessions`) and using `Hidden=true` in that file.

MDM uses the optional key `X-Mdm-XserverArgs` in session files to specify additional arguments to be passed to the X server. For example, the entry `X-Mdm-XserverArgs=-depth 16` will start the X server with a color depth of 16 bits. Any such additional arguments are ignored when using a Nested display (when MDM is launched in a window).

### The Script Directories

In this section we will explain the `Init`, `PostLogin`, `PreSession` and `PostSession` directories as they are very similar.

When the X server has been successfully started, MDM will try to run the script called `Init/<displayname>`. I.e. `Init/:0` for the first attached display. If this file is not found, MDM will attempt to to run `Init/<hostname>`. I.e. `Init/somehost`. If this still is not found, MDM will try `Init/XDMCP` for all XDMCP logins or `Init/Flexi` for all on demand flexible displays. If none of the above were found, MDM will run `Init/Default`. The script will be run as root and MDM blocks until it terminates. Use the `Init/*` script for applications that are supposed to run alongside with the MDM login window. xconsole for instance. Commands to set the background etc. go in this file too.

It is up to the sysadmin to decide whether clients started by the Init script should be killed before starting the user session. This is controlled with the `KillInitClients` configuration option.

When the user has been successfully authenticated MDM tries the scripts in the `PostLogin` directory in the same manner as for the `Init` directory. This is done before any session setup is done, and so this would be the script where you might setup the home directory if you need to (though you should use the `pam_mount` module if you can for this). You have the `$USER` and `$DISPLAY` environment variables set for this script, and again it is run as root. The script should return 0 on success as otherwise the user won't be logged in. This is not true for failsafe session however.

After the user session has been setup from the MDM side of things, MDM will run the scripts in the `PreSession` directory, again in the same manner as the `Init` directory. This script can be used for session management or accounting, for example. The `$USER` environment variable contains the login of the authenticated user and `$DISPLAY` is set to the current display. The script should return 0 on success. Any other value will cause MDM to terminate the current login process. This is not true for failsafe sessions however. Also `$X_SERVERS` environmental variable is set and this points to a fake generated X servers file for use with the sessreg accounting application.

After this the base `Xsession` script is run with the selected session executable as the first argument. This is run as the user, and really this is the user session. The available session executables are taken from the `Exec=` line in the `.desktop` files in the path specified by `SessionDesktopDir`. Usually this path is `<etc>/X11/sessions/:<etc>/dm/Sessions:/usr/share/xsessions/`. The first found file is used. The user either picks from these sessions or MDM will look inside the file `~/.dmrc` for the stored preference.

This script should really load the user's profile and generally do all the voodoo that is needed to launch a session. Since many systems reset the language selections done by MDM, MDM will also set the `$MDM_LANG` variable to the selected language. You can use this to reset the language environmental variables after you run the user's profile. If the user elected to use the system language, then `$MDM_LANG` is not set.

When the user terminates his session, the `PostSession` script will be run. Again operation is similar to `Init`, `PostLogin` and `PreSession`. Again the script will be run with root privileges, the slave daemon will block and the `$USER` environment variable will contain the name of the user who just logged out and `$DISPLAY` will be set to the display the user used, however note that the X server for this display may already be dead and so you shouldn't try to access it. Also `$X_SERVERS` environmental variable is set and this points to a fake generated X servers file for use with the sessreg accounting application.

Note that the `PostSession` script will be run even when the display fails to respond due to an I/O error or similar. Thus, there is no guarantee that X applications will work during script execution.

Except for the `Xsession` script all of these scripts will also have the environment variable `$RUNNING_UNDER_MDM` set to `yes`, so that you could perhaps use similar scripts for different display managers. The `Xsession` will always have the `$MDMSESSION` set to the basename of the session that the user chose to run without the `.desktop` extension. In addition `$DESKTOP_SESSION` is also set to the same value and in fact this will also be set by KDM in future versions.

Neither of the `Init`, `PostLogin`, `PreSession` or `PostSession` scripts are necessary and can be left out. The `Xsession` script is however required as well as at least one session `.desktop` file.

### The Configuration Files - MDM System Defaults Configuration File and MDM Custom Configuraiton File

MDM uses two configuration files: the MDM System Defaults Configuration File (`<share>/mdm/defaults.conf`) and the MDM Custom Configuration File (`<etc>/mdm/custom.conf`). The MDM System Defaults File contains the default configuration choices for MDM, and should not be modified by the user. The MDM Custom Configuration File is where users may specify their custom configuration choices. If a configuration option is not defined in either file, MDM will default to the value described in the comments in the MDM System Defaults Configuration File.

Both configuration files are divided into sections each containing variables that define the behavior for a specific part of the MDM suite. Refer to the comments in the MDM System Defaults Configuration File for additional information about each configuration setting.

MDM also supports per-display configuration for parameters in the "gui", "greeter" sections of the configuration file Also the `security/PamStack` and `daemon/LockScreen` keys may be customized per-display. Per-display configuration is specified by creating a file named `<etc>/mdm/custom.conf<display num>`. In this file the section and keys to use on this display can be specified. For example, configuration overrides for display ":103" would be stored in the file `<etc>/mdm/custom.conf:0`. Per-display configuration is supported in MDM 2.14.6 and later.

To change configuration by hand, edit the MDM Custom Configuration File or per-display configuration file and make sure the keyname=value pair you want is included in the appropriate section. For example, to change the value for the "Greeter" key in the "daemon" section, make sure the daemon section of the MDM Custom Configuration File or per-display configuration file includes the "[daemon]" section followed by the key and value change desired. As in this example:

    [daemon]
    Greeter=/usr/lib/mdmgreeter

The `mdmsetup` command can be used to modify the MDM Custom Configuration File. Note the `mdmsetup` is intended to be run as root, so users who feel it is insecure to run GUI programs as root should edit the configuration files by hand.

The MDM daemon `--config` argument may instead be used to specify a different configuration file location. The MDM daemon must be restarted to change the configuration file being used. Also when building MDM, the location of the configuration files may be specified via the `--with-defaults-conf` and `--with-custom-conf` configuration options.

Previous to MDM 2.13.0.4 only the `<etc>/mdm/mdm.conf` existed. For best backwards compatibility, this file will be used instead of the MDM Custom Configuration File if it exists on your system. If upgrading to the new version of MDM, "make install" will check to see if the `<etc>/mdm/mdm.conf` file is different than the `<etc>/mdm/factory-mdm.conf` file. If so, the `<etc>/mdm/mdm.conf` file will be automatically copied to `<etc>/mdm/custom.conf` to preserve any configuration changes.

Distributions should edit the MDM System Defaults Configuration File to establish default configuration values, so that they are preserved as defaults and not modified by users modifying the MDM Custom Configuration File. Note that distributions may modify the MDM System Defaults Configuration File on update to improve usability, security, etc. So any changes made to this file may be lost.

The MDM System Defaults Configuration File and the MDM Custom Configuration File follow the standard `.ini` style configuration file syntax. Keywords in brackets define sections, strings before an equal sign (=) are variables and the data after equal sign represents their value. Empty lines or lines starting with the hash mark (#) are ignored. The graphical configurator will try to preserve both comments (lines with a hash mark) and the overall structure of the file so you can intermix using the GUI or hand editing the configuration file.

The following configuration keys are supported in MDM:

#### Daemon Configuration

#### [daemon]

AddGtkModules

-     AddGtkModules=false

  If true, then enables `mdmgreeter` or `mdmlogin` to be launched with additional Gtk+ modules. This is useful when extra features are required such as accessible login. Note that only "trusted" modules should be used to minimize security issues.

  If true, then the registry daemon `at-spi-registryd` will be launched by `mdmgreeter` or `mdmlogin` starting with version MDM 2.17.

  Usually this is used for accessibility modules. The modules which are loaded are specified with the `GtkModulesList` key.

AllowLogoutActions

-     AllowLogoutActions=HALT;REBOOT;SHUTDOWN;SUSPEND;CUSTOM_CMD

  Specify which actions are supported by the QUERY_LOGOUT_ACTION, SET_LOGOUT_ACTION, and SET_SAFE_LOGOUT_ACTION `mdmflexiserver` commands. Valid values are HALT, REBOOT, SHUTDOWN, SUSPEND, and CUSTOM_CMD and these should be separated by semicolons. This allows certain options to be disabled if desired. Refer to the related `SystemCommandsInMenu` and `RBACSystemCommandKeys` configuration options.

AlwaysLoginCurrentSession

-     AlwaysLoginCurrentSession=true

  If true, then when the user logs in and already has an existing session, then they are connected to that session rather than starting a new session. This only works for sessions running on VTs (Virtual Terminals) started with mdmflexiserver, and not with XDMCP. Note that VTs are not supported on all operating systems.

AutomaticLoginEnable

-     AutomaticLoginEnable=false

  If the user given in AutomaticLogin should be logged in upon first bootup. No password will be asked. This is useful for single user workstations where console security is not an issue and also could be useful for public terminals. Refer also to `TimedLogin`.

AutomaticLogin

-     AutomaticLogin=

  This user should be automatically logged in on first bootup. AutomaticLoginEnable must be true and this must be a valid user for this to happen. "root" can never be autologged in however and mdm will just refuse to do it even if you set it up.

  The following control chars are recognized within the specified name:

  %% — the `%' character

  %d — display's name

  %h — display's hostname

  Alternatively, the name may end with a vertical bar |, the pipe symbol. The name is then used as a application to execute which returns the desired username on standard output. If an empty or otherwise invalid username is returned, automatic login is not performed. This feature is typically used when several remote displays are used as internet kiosks, with a specific user to automatically login for each display.

BaseXsession

-     BaseXsession=<etc>/mdm/Xsession

  This is the base X session file. When a user logs in, this script will be run with the selected session as the first argument. The selected session will be the `Exec=` from the `.desktop` file of the session.

  If you wish to use the same script for several different display managers, and wish to have some of the script run only for MDM, then you can check the presence of the `MDMSESSION` environmental variable. This will always be set to the basename of `.desktop` (without the extension) file that is being used for this session, and will only be set for MDM sessions. Previously some scripts were checking for `MDM_LANG`, but that is only set when the user picks a non-system default language.

  This script should take care of doing the "login" for the user and so it should source the `<etc>/profile` and friends. The standard script shipped with MDM sources the files in this order: `<etc>/profile` then `~/.profile` then `<etc>/xprofile` and finally `~/.xprofile`. Note that different distributions may change this however. Sometimes users personal setup will be in `~/.bash_profile`, however broken that is.

Chooser

-     Chooser=<bin>/mdmchooser

  Full path and name of the chooser executable followed by optional arguments.

Configurator

-     Configurator=<bin>/mdmsetup --disable-sound --disable-crash-dialog

  The pathname to the configurator binary. If the greeter `ConfigAvailable` option is set to true then run this binary when somebody chooses Configuration from the Actions menu. Of course MDM will first ask for root password however. And it will never allow this to happen from a remote display.

ConsoleCannotHandle

-     ConsoleCannotHandle=am,ar,az,bn,el,fa,gu,hi,ja,ko,ml,mr,pa,ta,zh

  These are the languages that the console cannot handle because of font issues. Here we mean the text console, not X. This is only used when there are errors to report and we cannot start X.

ConsoleNotify

-     ConsoleNotify=true

  If false, mdm will not display a message dialog on the console when an error happens.

DefaultPath

-     DefaultPath=defaultpath (value set by configure)

  Specifies the path which will be set in the user's session. This value will be overridden with the value from `/etc/default/login` if it contains "ROOT=<pathname>". If the `/etc/default/login` file exists, but contains no value for ROOT, the value as defined in the MDM configuration will be be used.

DefaultSession

-     DefaultSession=gnome.desktop

  The session that is used by default if the user does not have a saved preference and has picked 'Last' from the list of sessions. Note that 'Last' need not be displayed, see the `ShowLastSession` key.

DisplayInitDir

-     DisplayInitDir=<etc>/mdm/Init

  Directory containing the display init scripts. See the ``The Script Directories'' section for more info.

DisplayLastLogin

-     DisplayLastLogin=true

  If true then the last login information is printed to the user before being prompted for password. While this gives away some info on what users are on a system, it on the other hand should give the user an idea of when they logged in and if it doesn't seem kosher to them, they can just abort the login and contact the sysadmin (avoids running malicious startup scripts). This was added in version 2.5.90.0.

  This is for making MDM conformant to CSC-STD-002-85, although that is purely theoretical now. Someone should read that spec and ensure that this actually conforms (in addition to other places in MDM). See `http://www.radium.ncsc.mil/tpep/library/rainbow/CSC-STD-002-85.html` for more info.

DoubleLoginWarning

-     DoubleLoginWarning=true

  If true, MDM will warn the user if they are already logged in on another virtual terminal. On systems where MDM supports checking the X virtual terminals, MDM will let the user switch to the previous login virtual terminal instead of logging in.

DynamicXServers

-     DynamicXServers=false

  If true, the MDM daemon will honor requests to manage displays via the `/tmp/.mdm_socket` socket connection. Displays can be created, started, and deleted with the appropriate commands. The `mdmdynamic` command is a convenient method to send these messages.

FailsafeXServer

-     FailsafeXServer=

  An X command line in case we can't start the normal X server. should probably be some sort of a script that runs an appropriate low resolution X server that will just work. This is tried before the `XKeepsCrashing` script is run.

FirstVT

-     FirstVT=7

  On systems where MDM supports automatic VT (virtual terminal) allocation, this is the first vt to try. Usually standard text logins are run on the lower vts. See also `VTAllocation`.

FlexibleXServers

-     FlexibleXServers=5

  The maximum number of allowed flexible displays. These are displays that can be run using the `/tmp/.mdm_socket` socket connection. This is used for both full flexible displays and for nested displays (refer to the `Xnest` configuration option).

FlexiReapDelayMinutes

-     FlexiReapDelayMinutes=5

  After how many minutes of inactivity at the login screen should a flexi display be reaped. This is only in effect before a user logs in. Also it does not affect nested displays (refer to the `Xnest` configuration option). To turn off this behavior set this value to 0. This was added in version 2.5.90.0.

Greeter

-     Greeter=<bin>/mdmlogin

  Full path and name of the greeter executable followed by optional arguments. This is the greeter used for all displays except for the XDMCP remote displays. See also `RemoteGreeter`

Group

-     Group=mdm

  The group name under which `mdmlogin`, `mdmgreeter`, `mdmchooser` and the internal failsafe GTK+ dialogs are run. Also see `User`. This user will have access to all the X authorization files, and perhaps to other internal MDM data and it should not therefore be a user such as nobody, but rather a dedicated user. The `ServAuthDir` is owned by this group. The ownership and permissions of `ServAuthDir` should be `root.mdm` and 1770.

GtkModulesList

-     GtkModulesList=module-1:module-2:...

  A colon separated list of Gtk+ modules that `mdmgreeter` or `mdmlogin` will be invoked with if `AddGtkModules` is true. The format is the same as the standard Gtk+ module interface.

HaltCommand

-     HaltCommand=<sbin>/shutdown -h now

  Full path and arguments to command to be executed when user selects "Shut Down" from the Actions menu. This can be a ';' separated list of commands to try. If a value is missing, the shut down command is not available. Note that the default for this value is not empty, so to disable "Shut Down" it must be set to an empty value.

KillInitClients

-     KillInitClients=true

  Determines whether MDM should kill X clients started by the init scripts when the user logs in.

LogDir

-     LogDir=<var>/log/mdm

  Directory containing the log files for the individual displays. By default this is the same as the ServAuthDir.

PreFetchProgram

-     PreFetchProgram=command

  Program to be run by the MDM greeter/login program when the initial screen is displayed. The purpose is to provide a hook where files which will be used after login can be preloaded to speed performance for the user. The program will be called once only, the first time a greeter is displayed. The mdmprefetch command may be used. This utility will load any libraries passed in on the command line, or if the argument starts with a "@" character, it will process the file assuming it is an ASCII file containing a list of libraries, one per line, and load each library in the file.

PamStack

-     PamStack=mdm

  If using PAM, this specifies the PAM service name to use when calling pam_start. This option may be configured per-display so that MDM can be configured to have a different PAM stack on a given display. Note that autologin sessions append "-autologin" to this value, so by default autologin sessions use the service name "mdm-autologin".

PostLoginScriptDir

-     PostLoginScriptDir=<etc>/mdm/PostLogin

  Directory containing the scripts run right after the user logs in, but before any session setup is done. See the ``The Script Directories'' section for more info.

PostSessionScriptDir

-     PostSessionScriptDir=<etc>/mdm/PostSession

  Directory containing the scripts run after the user logs out. See the ``The Script Directories'' section for more info.

PreSessionScriptDir

-     PreSessionScriptDir=<etc>/mdm/PreSession

  Directory containing the scripts run before the user logs in. See the ``The Script Directories'' section for more info.

RBACSystemCommandKeys

-     RBACSystemCommandKeys

  Support RBAC (Role Based Access Control) for system commands (Shutdown, Reboot, Suspend, etc.). This feature is only functional if MDM is compiled with RBAC support. Specify the RBAC key used to determine if the user has permission to use the action via the QUERY_LOGOUT_ACTION, SET_LOGOUT_ACTION, and SET_SAFE_LOGOUT_ACTION `mdmflexiserver` commands. Valid actions are HALT, REBOOT, SUSPEND, and CUSTOM_CMD. The greeter will only display the command if the mdm user (`User` configuration key) has RBAC permissions to use the action. RBAC keys for multiple actions can be specified by separating them with semicolons. The format for each is "Action:RBAC key". If an action is not specified, it is assumed that all users have permission to use this action. For example, a valid value for this configuration option would be "HALT:key.for.halt;REBOOT:key.for.reboot". Refer to the related `AllowLogoutActions` and `SystemCommandsInMenu` configuration options.

RebootCommand

-     RebootCommand=<sbin>/shutdown -r now

  Full path and optional arguments to the command to be executed when user selects Restart from the Actions menu. This can be a ';' separated list of commands to try. If missing, the restart command is not available. Note that the default for this value is not empty so to disable restart you must set this explicitly to an empty value.

RemoteGreeter

-     RemoteGreeter=<bin>/mdmlogin

  Full path and name of the greeter executable followed by optional arguments. This is used for all remote XDMCP sessions. It is useful to have the less graphically demanding greeter here if you use the Themed Greeter for your main greeter. See also the `Greeter` key.

RootPath

-     RootPath=defaultpath (value set by configure)

  Specifies the path which will be set in the root's session and the {Init,PostLogin,PreSession,PostSession} scripts executed by MDM. This value will be overridden with the value from `/etc/default/login` if it contains "SUROOT=<pathname>". If the `/etc/default/login` file exists, but contains no value for SUROOT, the value as defined in the MDM configuration will be used.

ServAuthDir

-     ServAuthDir=<var>/mdm

  Directory containing the X authentication files for the individual displays. Should be owned by `root.mdm` with permissions 1770, where `mdm` is the MDM group as defined by the `Group` option. That is should be owned by root, with `mdm` group having full write permissions and the directory should be sticky and others should have no permission to the directory. This way the MDM user can't remove files owned by root in that directory, while still being able to write its own files there. MDM will attempt to change permissions for you when it's first run if the permissions are not the above. This directory is also used for other private files that the daemon needs to store. Other users should not have any way to get into this directory and read/change it's contents. Anybody who can read this directory can connect to any display on this computer.

SessionDesktopDir

-     SessionDesktopDir=<etc>/X11/sessions/:<etc>/dm/Sessions/:<share>/xsessions/

  Directory containing the `.desktop` files which are the available sessions on the system. Since 2.4.4.2 this is treated like a PATH type variable and the first file found is used.

SoundProgram

-     SoundProgram=<bin>/play (or <bin>/audioplay on Solaris)

  Application to use when playing a sound. Currently used for playing the login sound, see the `SoundOnLoginFile` key. Supported since 2.5.90.0.

StandardXServer

-     StandardXServer=/dir/to/X (value assigned by configuration file)

  Full path and arguments to the standard X server command. This is used when mdm cannot find any other definition, and it's used as the default and failsafe fallback in a number of places. This should be able to run some sort of X server.

SuspendCommand

-     SuspendCommand=

  Full path and arguments to command to be executed when user selects Suspend from the Actions menu. If empty there is no such menu item. Note that the default for this value is not empty so to disable suspend you must set this explicitly to an empty value.

SystemCommandsInMenu

-     SuspendCommand=HALT;REBOOT;SHUTDOWN;SUSPEND;CUSTOM_CMD

  Specify which system commands are available in the greeter menu. Valid values are HALT, REBOOT, SHUTDOWN, SUSPEND, and CUSTOM_CMD and these should be separated by semicolons. This can be useful if you want to disable some options in the menu, but still have them available to authenticated users via the SET_LOGOUT_ACTION or SET_SAFE_LOGOUT_ACTION `mdmflexiserver` commands. For example, the GNOME panel uses these commands to provide Shutdown, Reboot, and Suspend in the application menu. Therefore if you turn off these options in the greeter, these options can still be available to users who have authenticated via the GNOME panel. Refer to the related `AllowLogoutActions` and `RBACSystemCommandKeys` configuration options.

TimedLoginEnable

-     TimedLoginEnable=false

  If the user given in `TimedLogin` should be logged in after a number of seconds (set with `TimedLoginDelay`) of inactivity on the login screen. This is useful for public access terminals or perhaps even home use. If the user uses the keyboard or browses the menus, the timeout will be reset to `TimedLoginDelay` or 30 seconds, whichever is higher. If the user does not enter a username but just hits the ENTER key while the login program is requesting the username, then MDM will assume the user wants to login immediately as the timed user. Note that no password will be asked for this user so you should be careful, although if using PAM it can be configured to require password entry before allowing login.

TimedLogin

-     TimedLogin=

  This is the user that should be logged in after a specified number of seconds of inactivity. This can never be "root" and mdm will refuse to log in root this way. The same features as for `AutomaticLogin` are supported. The same control chars and piping to a application are supported.

TimedLoginDelay

-     TimedLoginDelay=30

  Delay in seconds before the `TimedLogin` user will be logged in. It must be greater then or equal to 10.

User

-     User=mdm

  The username under which `mdmlogin`, `mdmgreeter`, `mdmchooser` and the internal failsafe GTK+ dialogs are run. Also see `Group`. This user will have access to all the X authorization files, and perhaps to other internal MDM data and it should not therefore be a user such as nobody, but rather a dedicated user.

UserAuthDir

-     UserAuthDir=

  The directory where user's `.Xauthority` file should be saved. When nothing is specified the user's home directory is used. This is tilde expanded so you can set it to things like: `~/authdir/`.

  If you do not use the tilde expansion, then the filename created will be random, like in `UserAuthFBDir`. This way many users can have the same authentication directory. For example you might want to set this to `/tmp` when user has the home directory on NFS, since you really don't want cookie files to go over the wire. The users should really have write privileges to this directory, and this directory should really be sticky and all that, just like the `/tmp` directory.

  Normally if this is the user's home directory MDM will still refuse to put cookies there if it thinks it is NFS (by testing root-squashing). This can be changed by setting `NeverPlaceCookiesOnNFS` in the `[security]` section to false.

UserAuthFBDir

-     UserAuthFBDir=/tmp

  If MDM fails to update the user's `.Xauthority` file a fallback cookie is created in this directory.

UserAuthFile

-     UserAuthFile=.Xauthority

  Name of the file used for storing user cookies.

VTAllocation

-     VTAllocation=true

  On systems where MDM supports automatic VT (virtual terminal) allocation (currently Linux and FreeBSD only), you can have MDM automatically append the vt argument to the X server executable. This way races that come up from each X server managing it's own vt allocation can be avoided. See also `FirstVT`.

XKeepsCrashing

-     XKeepsCrashing=<etc>/mdm/XKeepsCrashing

  A script to run in case X keeps crashing. This is for running An X configuration or whatever else to make the X configuration work. See the script that came with the distribution for an example. The distributed `XKeepsCrashing` script is tested on Red Hat, but may work elsewhere. Your system integrator should make sure this script is up to date for your particular system.

  In case `FailsafeXServer` is setup, that will be tried first. and this only used as a backup if even that X server keeps crashing.

Xnest

-     Xnest=<bin>/X11/Xephyr -audit 0

  The full path and arguments to the nested X server command, which can be Xephyr, Xnest, or similar program. This command is used for starting nested displays allowing the user to start new login screens in a nested window. Xephyr is recommended since it works best and better supports modern X server extensions. Therefore MDM will set the default configuration to use Xephyr if available. If Xephyr is not available, then Xnest will be used if it is available.

XnestUnscaledFontPath

-     XnestUnscaledFontPath=true

  Set to true if the nested X server command program supports the ":unscaled" suffix in the FontPath (passed to nested X server command via the -fp argument). Some Xnest (e.g. Xsun Xnest) programs do not, and it is necessary to set this to false for such nested X server commands to work with MDM. Refer to the `Xnest` configuration option.

#### Security Options

#### [security]

AllowRoot

-     AllowRoot=true

  Allow root (privileged user) to log in through MDM. Set this to false if you want to disallow such logins.

  On systems that support PAM, this parameter is not as useful as you can use PAM to do the same thing, and in fact do even more. However it is still followed, so you should probably leave it true for PAM systems.

AllowRemoteRoot

-     AllowRemoteRoot=false

  Allow root (privileged user) to log in remotely through MDM. This value should be set to true to allow such logins. Remote logins are any logins that come in through the XDMCP.

  On systems that support PAM, this parameter is not as useful since you can use PAM to do the same thing, and do even more.

  This value will be overridden and set to false if the `/etc/default/login` file exists and contains "CONSOLE=/dev/login", and set to true if the `/etc/default/login` file exists and contains any other value or no value for CONSOLE.

AllowRemoteAutoLogin

-     AllowRemoteAutoLogin=false

  Allow the timed login feature to work for remote displays. In other words, remote connections via XDMCP will be allowed to log into the "TimedLogin" user after the delay defined by `TimedLoginDelay`.

  Note that this can make a system quite insecure, and thus is off by default.

CheckDirOwner

-     CheckDirOwner=true

  By default MDM checks the ownership of the home directories before writing to them, this prevents security issues in case of bad setup. However in some instances home directories will be owned by a different user and in this case it is necessary to turn this option on. You will also most likely have to turn the `RelaxPermissions` key to at least value 1 since in such a scenario home directories are likely to be group writable. Supported since 2.6.0.4.

SupportAutomount

-     SupportAutomount=false

  By default MDM checks the ownership of the home directories before writing to them, this prevents security issues in case of bad setup. However, when home directories are managed by automounter, they are often not mounted before they are accessed. This option works around subtleties of Linux automounter.

DisallowTCP

-     DisallowTCP=true

  If true, then always append `-nolisten tcp` to the command line when starting attached X servers, thus disallowing TCP connection. This is a more secure configuration if not using remote connections.

NeverPlaceCookiesOnNFS

-     NeverPlaceCookiesOnNFS=true

  Normally if this is true (which is by default), MDM will not place cookies into the user's home directory if this directory is on NFS. Well, MDM will consider any filesystem with root-squashing an NFS filesystem. Sometimes however the remote file system can have root squashing and be safe (perhaps by using encryption). In this case set this to 'false'. Note that this option appeared in version 2.4.4.4 and is ignored in previous versions.

PasswordRequired

-     PasswordRequired=false

  If true, this will cause PAM_DISALLOW_NULL_AUTHTOK to be passed as a flag to pam_authenticate and pam_acct_mgmt, disallowing NULL password. This setting will only take effect if PAM is being used by MDM. This value will be overridden with the value from `/etc/default/login` if it contains "PASSREQ=[YES|NO]". If the `/etc/default/login` file exists, but contains no value for PASSREQ, the value as defined in the MDM configuration will be used.

RelaxPermissions

-     RelaxPermissions=0

  By default MDM ignores files and directories writable to other users than the owner.

  Changing the value of RelaxPermissions makes it possible to alter this behavior:

  0 - Paranoia option. Only accepts user owned files and directories.

  1 - Allow group writable files and directories.

  2 - Allow world writable files and directories.

RetryDelay

-     RetryDelay=1

  The number of seconds MDM should wait before reactivating the entry field after a failed login.

UserMaxFile

-     UserMaxFile=65536

  MDM will refuse to read/write files bigger than this number (specified in bytes).

  In addition to the size check MDM is extremely picky about accessing files in user directories. It will not follow symlinks and can optionally refuse to read files and directories writable by other than the owner. See the `RelaxPermissions` option for more info.

UtmpLineAttached

-     UtmpLineAttached=/dev/console (or /dev/dtlocal on Solaris)

  When doing Utmp processing for attached displays, MDM sets the ut_line to the device associated with the Virtual Terminal (VT) if it is being used. Otherwise, it will use the value specified with the display in the `[servers]` section if a value is provided. If not, then the default value specified in UtmpLineAttached is used for attached displays. The value can contain "%d" which is translated to the DISPLAY value or "%h" which is translated to the hostname. This value must begin with `/dev/`.

UtmpLineRemote

-     UtmpLineRemote= (or /dev/dtremote on Solaris)

  When doing Utmp processing, MDM sets the ut_line to this value for remote displays. The value can contain "%d" which is translated to the DISPLAY value or "%h" which is translated to the hostname. This value must begin with `/dev/`.

UtmpPseudoDevice

-     PseudoDevice=false (or true on Solaris)

  If the device associated with a display does not exist, then MDM will create a symlink to `/dev/null`, or touch it if it is a symlink to `/dev/null`. Some programs such as `last`, `finger`, or `who` access the utmp database and may assume that the device points to an actual file. Creating such symlinks ensures that such programs work properly.

#### XDCMP Support

#### [xdmcp]

DisplaysPerHost

-     DisplaysPerHost=1

  To prevent attackers from filling up the pending queue, MDM will only allow one connection for each remote computer. If you want to provide display services to computers with more than one screen, you should increase the `DisplaysPerHost` value accordingly.

  Note that the number of attached DISPLAYS allowed is not limited. Only remote connections via XDMCP are limited by this configuration option.

Enable

-     Enable=false

  Setting this to true enables XDMCP support allowing remote displays/X terminals to be managed by MDM.

  `mdm` listens for requests on UDP port 177. See the Port option for more information.

  If MDM is compiled to support it, access from remote displays can be controlled using the TCP Wrappers library. The service name is `mdm`

  You should add

      mdm:.my.domain

  to your `<etc>/hosts.allow`, depending on your TCP Wrappers configuration. See the hosts.allow(5) man page for details.

  Please note that XDMCP is not a particularly secure protocol and that it is a good idea to block UDP port 177 on your firewall unless you really need it.

EnableProxy

-     EnableProxy=false

  Setting this to true enables support for running XDMCP sessions on a local proxy X server. This may improve the performance of XDMCP sessions, especially on high latency networks, as many X protocol operations can be completed without going over the network.

  Note, however, that this mode will significantly increase the burden on the machine hosting the XDMCP sessions

  See the `FlexiProxy` and `FlexiProxyDisconnect` options for further details on how to configure support for this feature.

HonorIndirect

-     HonorIndirect=true

  Enables XDMCP INDIRECT choosing (i.e. remote execution of `mdmchooser`) for X-terminals which don't supply their own display browser.

MaxPending

-     MaxPending=4

  To avoid denial of service attacks, MDM has fixed size queue of pending connections. Only MaxPending displays can start at the same time.

  Please note that this parameter does *not* limit the number of remote displays which can be managed. It only limits the number of displays initiating a connection simultaneously.

MaxPendingIndirect

-     MaxPendingIndirect=4

  MDM will only provide `MaxPendingIndirect` displays with host choosers simultaneously. If more queries from different hosts come in, the oldest ones will be forgotten.

MaxSessions

-     MaxSessions=16

  Determines the maximum number of remote display connections which will be managed simultaneously. I.e. the total number of remote displays that can use your host.

MaxWait

-     MaxWait=30

  When MDM is ready to manage a display an ACCEPT packet is sent to it containing a unique session id which will be used in future XDMCP conversations.

  MDM will then place the session id in the pending queue waiting for the display to respond with a MANAGE request.

  If no response is received within MaxWait seconds, MDM will declare the display dead and erase it from the pending queue freeing up the slot for other displays.

MaxWaitIndirect

-     MaxWaitIndirect=30

  The MaxWaitIndirect parameter determines the maximum number of seconds between the time where a user chooses a host and the subsequent indirect query where the user is connected to the host. When the timeout is exceeded, the information about the chosen host is forgotten and the indirect slot freed up for other displays. The information may be forgotten earlier if there are more hosts trying to send indirect queries then `MaxPendingIndirect`.

Port

-     Port=177

  The UDP port number `mdm` should listen to for XDMCP requests. Don't change this unless you know what you are doing.

PingIntervalSeconds

-     PingIntervalSeconds=15

  Interval in which to ping the X server in seconds. If the X server doesn't return before the next time we ping it, the connection is stopped and the session ended. This is a combination of the XDM PingInterval and PingTimeout, but in seconds.

  Note that MDM in the past used to have a `PingInterval` configuration key which was also in minutes. For most purposes you'd want this setting to be lower then one minute however since in most cases where XDMCP would be used (such as terminal labs), a lag of more than 15 or so seconds would really mean that the terminal was turned off or restarted and you would want to end the session.

ProxyReconnect

-     FlexiProxyReconnect=

  Setting this option enables experimental support for session migration with XDMCP sessions. This enables users to disconnect from their session and later reconnect to that same session, possibly from a different terminal.

  In order to use this feature, you must have a nested X server available which supports disconnecting from its parent X server and reconnecting to another X server. Currently, the Distributed Multihead X (DMX) server supports this feature to some extent and other projects like NoMachine NX are busy implementing it.

  This option should be set to the path of a command which will handle reconnecting the XDMCP proxy to another backend display. A sample implementation for use with DMX is supplied.

ProxyXServer

-     ProxyXServer=

  The X server command line for a XDMCP proxy. Any nested X server like Xnest, Xephyr or Xdmx should work fairly well.

Willing

-     Willing=<etc>/mdm/Xwilling

  When the machine sends a WILLING packet back after a QUERY it sends a string that gives the current status of this server. The default message is the system ID, but it is possible to create a script that displays customized message. If this script doesn't exist or this key is empty the default message is sent. If this script succeeds and produces some output, the first line of it's output is sent (and only the first line). It runs at most once every 3 seconds to prevent possible denial of service by flooding the machine with QUERY packets.

#### Common GUI Configuration Options

#### [gui]

AllowGtkThemeChange

-     AllowGtkThemeChange=true

  If to allow changing the GTK+ (widget) theme from the greeter. Currently this only affects the standard greeter as the graphical greeter does not yet have this ability. The theme will stay in effect on this display until changed and will affect all the other windows that are put up by MDM. Supported since 2.5.90.2.

GtkRC

-     GtkRC=

  Path to a `gtkrc` to read when MDM puts up a window. You should really now use the `GtkTheme` key for just setting a theme.

GtkTheme

-     GtkTheme=Default

  A name of an installed theme to use by default. It will be used in the greeter, chooser and all other GUI windows put up by MDM. Supported since 2.5.90.2.

GtkThemesToAllow

-     GtkThemesToAllow=all

  Comma separated list of themes to allow. These must be the names of the themes installed in the standard locations for GTK+ themes. You can also specify 'all' to allow all installed themes. This is related to the `AllowGtkThemeChange` key. Supported since 2.5.90.2.

MaxIconWidth

-     MaxIconWidth=128

  Specifies the maximum icon width (in pixels) that the face browser will display. Icons larger than this will be scaled. This also affects icons in the XDMCP chooser.

MaxIconHeight

-     MaxIconHeight=128

  Specifies the maximum icon height (in pixels) that the face browser will display. Icons larger than this will be scaled. This also affects icons in the XDMCP chooser.

#### Greeter Configuration

#### [greeter]

BackgroundColor

-     BackgroundColor=#000000

  If the BackgroundType is 2, use this color in the background of the greeter. Also use it as the back of transparent images set on the background and if the BackgroundRemoteOnlyColor is set and this is a remote display. This only affects the GTK+ Greeter.

BackgroundProgramInitialDelay

-     BackgroundProgramInitialDelay=30

  The background application will be started after at least that many seconds of inactivity.

RestartBackgroundProgram

-     RestartBackgroundProgram=true

  If set the background application will be restarted when it has exited, after the delay described below has elapsed. This option can be useful when you wish to run a screen saver application when no user is using the computer.

BackgroundProgramRestartDelay

-     BackgroundProgramRestartDelay=30

  The background application will be restarted after at least that many seconds of inactivity.

BackgroundImage

-     BackgroundImage=somefile.png

  If the BackgroundType is 1, then display this file as the background in the greeter. This only affects the GTK+ Greeter.

BackgroundProgram

-     BackgroundProgram=<bin>/xeyes

  If set this command will be run in the background while the login window is being displayed. Note that not all applications will run this way, since MDM does not usually have a home directory. You could set up home directory for the MDM user if you wish to run applications which require it. This only affects the GTK+ Greeter.

BackgroundRemoteOnlyColor

-     BackgroundRemoteOnlyColor=true

  On remote displays only set the color background. This is to make network load lighter. The `BackgroundProgram` is also not run. This only affects the GTK+ Greeter.

BackgroundScaleToFit

-     BackgroundScaleToFit=true

  Scale background image to fit the screen. This only affects the GTK+ Greeter.

BackgroundType

-     BackgroundType=2

  The type of background to set. 0 is none, 1 is image and color, 2 is color and 3 is image. This only affects the GTK+ Greeter.

Browser

-     Browser=true

  Set to true to enable the face browser. See the ``The GTK+ Greeter'' section for more information on the face browser. This option only works for the GTK+ Greeter. For the Themed Greeter, the face browser is enabled by choosing a theme which includes a face browser

ChooserButton

-     ChooserButton=true

  If true, add a chooser button to the Actions menu that will restart the current X server with a chooser. XDMCP does not need to be enabled on the local computer for this to work.

ConfigAvailable

-     ConfigAvailable=false

  If true, allows the configurator to be run from the greeter. Note that the user will need to type in the root password before the configurator will be started. This is set to false by default for additional security. See the `Configurator` option in the daemon section.

DefaultFace

-     DefaultFace=<share>/pixmaps/nophoto.png

  If a user has no defined face image, MDM will use the "stock_person" icon defined in the current GTK+ theme. If no such image is defined, the image specified by `DefaultFace` will be used. The image must be in a gdk-pixbuf supported format and the file must be readable to the MDM user.

Include

-     Include=

  Comma separated list of users to be included in the face browser and in the `mdmsetup` selection list for Automatic/Timed login. See also `Exclude`, `IncludeAll`, and `MinimalUID`.

Exclude

-     Exclude=bin,daemon,adm,lp,sync,shutdown,halt,mail,...

  Comma separated list of users to be excluded from the face browser and from the `mdmsetup` selection list for Automatic/Timed login. Excluded users will still be able to log in, but will have to type their username. See also `Include`, `IncludeAll`, and `MinimalUID`.

IncludeAll

-     IncludeAll=false

  By default, an empty include list means display no users. By setting IncludeAll to true, the password file will be scanned and all users will be displayed aside from users excluded via the Exclude setting and user ID's less than MinimalUID. Scanning the password file can be slow on systems with large numbers of users and this feature should not be used in such environments. See also `Include`, `Exclude`, and `MinimalUID`.

GlobalFaceDir

-     GlobalFaceDir=<share>/pixmaps/faces/

  Systemwide directory for face files. The sysadmin can place icons for users here without touching their homedirs. Faces are named after their users' logins.

  I.e. `<GlobalFaceDir>/johndoe` would contain the face icon for the user ``johndoe''. No image format extension should be specified.

  The face images must be stored in gdk-pixbuf supported formats and they must be readable for the MDM user.

  A user's own icon file will always take precedence over the sysadmin provided one.

GraphicalTheme

-     GraphicalTheme=circles

  The graphical theme that the Themed Greeter should use. it should refer to a directory in the theme directory set by `GraphicalThemeDir`.

GraphicalThemes

-     GraphicalThemes=circles

  The graphical themes that the Themed Greeter should use is the Mode is set on Random Themes. This is a "/:" delimited list. It should refer to a directory in the theme directory set by `GraphicalThemeDir`. This is only used if `GraphicalThemeRand` is set to true.

GraphicalThemeRand

-     GraphicalThemeRand=false

  Whether the graphical greeter will use Only One Theme or Random Theme mode. Only One Theme mode uses themes listed by `GraphicalTheme`, Random Themes mode uses themes listed by `GraphicalThemes`. A value of false sets greeter to use Only One Theme mode, a value of true sets the greeter to use Random Theme mode.

GraphicalThemeDir

-     GraphicalThemeDir=<share>/mdm/themes/

  The directory where themes for the Themed Greeter are installed.

GraphicalThemedColor

-     GraphicalThemedColor=#000000

  Use this color in the background of the Themed Greeter. This only affects the Themed Greeter.

InfoMsgFile

-     InfoMsgFile=/path/to/infofile

  If present and /path/to/infofile specifies an existing and readable text file (e.g. <etc>/infomsg.txt) the contents of the file will be displayed in a modal dialog box before the user is allowed to login. This works both with the standard and the themable greeters.

InfoMsgFont

-     InfoMsgFont=fontspec

  If present and InfoMsgFile (see above) is used, this specifies the font to use when displaying the contents of the InfoMsgFile text file. For example fontspec could be Sans 24 to get a sans serif font of size 24 points. This works both with the standard and the themable greeters.

LocaleFile

-     LocaleFile=<etc>/mdm/locale.alias

  File in format similar to the GNU locale format with entries for all supported languages on the system. The format is described above or in a comment inside that file.

LockPosition

-     LockPosition=true

  If true the position of the login window of the GTK+ Greeter cannot be changed even if the title bar is turned on.

Logo

-     Logo=<share>/pixmaps/gnome-logo-large.png

  Image file to display in the logo box. The file must be in a gdk-pixbuf supported format and it must be readable by the MDM user. If no file is specified the logo feature is disabled. This only affects the GTK+ Greeter.

ChooserButtonLogo

-     ChooserButtonLogo=<share>/pixmaps/gnome-logo-large.png

  Image file to display in the file chooser button in `mdmsetup`. This key is modified by `mdmsetup` and should not be manually modified by the user. This only affects the Login Window Preferences (`mdmsetup`).

MinimalUID

-     MinimalUID=100

  The minimal UID that MDM should consider a user. All users with a lower UID will be excluded from the face browser. See also `Include`, `Exclude`, and `IncludeAll`.

PositionX

-     PositionX=200

  The horizontal position of the login window of the GTK+ Greeter.

PositionY

-     PositionY=100

  The vertical position of the login window of the GTK+ Greeter.

Quiver

-     Quiver=true

  Controls whether `mdmlogin` should shake the display when an incorrect username/password is entered. This only affects the GTK+ Greeter.

DefaultRemoteWelcome

-     DefaultRemoteWelcome=true

  If set to true, the value "Welcome to %n" is used for the `RemoteWelcome`. This value is translated into the appropriate language for the user. If set to false, the `RemoteWelcome` setting is used. This string can use the same special character sequences as explained in the "Text Node" section of the "Themed Greeter" chapter. This explains the meaning of "%n".

RemoteWelcome

-     RemoteWelcome=Welcome to %n

  Controls which text to display next to the logo image in the greeter for remote XDMCP sessions. The same expansion is done here as in the `Welcome` string. This string can use the same special character sequences as explained in the "Text Node" section of the "Themed Greeter" chapter. chapter.

RunBackgroundProgramAlways

-     RunBackgroundProgramAlways=false

  If this is true then the background application is run always, otherwise it is only run when the `BackgroundType` is 0 (None) This only affects the GTK+ Greeter.

SetPosition

-     SetPosition=true

  If true the position of the login window of the GTK+ Greeter is determined by `PositionX` / `PositionY`.

SoundOnLogin

-     SoundOnLogin=true

  If true, the greeter will play a sound or beep when it is ready for a login. See also the `SoundOnLoginFile` key. Supported since 2.5.90.0.

SoundOnLoginSuccess

-     SoundOnLoginSuccess=true

  If true, the greeter will play a sound after a successful login attempt. See also the `SoundOnLoginSuccessFile` key.

SoundOnLoginFailure

-     SoundOnLoginFailure=true

  If true, the greeter will play a sound after a failed login attempt. See also the `SoundOnLoginFailureFile` key.

SoundOnLoginFile

-     SoundOnLoginFile=/path/to/sound.wav

  The file that will be played using the specified sound application (by default that is `/usr/bin/play`) instead of a beep when the greeter is ready for a login. See also the `SoundOnLogin` key and the `SoundProgram` key. Supported since 2.5.90.0.

SoundOnLoginSuccessFile

-     SoundOnLoginSuccessFile=/path/to/sound.wav

  The file that will be played using the specified sound application (by default that is `/usr/bin/play`) after a successful login attempt. See also the `SoundOnLoginSuccess` key and the `SoundProgram` key.

SoundOnLoginFailureFile

-     SoundOnLoginFailureFile=/path/to/sound.wav

  The file that will be played using the specified sound application (by default that is `/usr/bin/play`) after a failed login attempt. See also the `SoundOnLoginFailure` key and the `SoundProgram` key.

SystemMenu

-     SystemMenu=true

  Turns the Actions menu (which used to be called System menu) on or off. If this is off then one of the actions will be available anywhere. These actions include Shutdown, Restart, Configure, XDMCP chooser and such. All of those can however be turned off individually. Shutdown, Restart and Suspend can be turned off by just setting the corresponding keys to empty. Note that the actions menu is only shown on attached displays. It would not be safe or even desirable on remote logins, so you do not have to worry about remote users having these privileges.

  Note that if this is off none of the actions will be available even if a theme for a graphical greeter mistakenly shows them. Also note that sometimes a graphical theme may not show all the available actions as buttons and you may have to press F10 to see the menu.

TitleBar

-     TitleBar=true

  Display the title bar in the greeter. This only affects the GTK+ Greeter.

Use24Clock

-     Use24Clock=auto

  Select the use of 24 hour clock. Some locales do not support 12 hour format (like Finnish, that is `fi_FI`), and in those locales this setting has no effect at all.

  Possible values are "auto" (default), "true", and "false". If this is set to "auto" or left empty, then time format is chosen from locale settings. Locale settings are based on the language in use, thus it is changed by setting environment variables LANGUAGE (GNU extension), LANG, LC_MESSAGES or LC_ALL in the MDM's runtime environment. Priorities between the mentioned environment variables can be found from your system's C library manual.

UseInvisibleInEntry

-     UseInvisibleInEntry=false

  Do not show any visual feedback is the password entry. This is the standard in console and xdm. Settings this option discards the `UseCirclesInEntry` option.

DefaultWelcome

-     DefaultWelcome=true

  If set to true, the value "Welcome" is used for the `Welcome`. This value is translated into the appropriate language for the user. If set to false, the `Welcome` setting is used.

Welcome

-     Welcome=Welcome

  Controls which text to display next to the logo image in the standard greeter. The following control chars are supported:

  %% — the `%' character

  %d — display's hostname

  %h — Fully qualified hostname

  %m — machine (processor type)

  %n — Nodename (i.e. hostname without .domain)

  %r — release (OS version)

  %s — sysname (i.e. OS)

  This string is only used for attached displays. For remote XDMCP displays we use `RemoteWelcome`.

  In the Themed Greeter the location of this text depends on the theme. Unless the theme uses the stock welcome string somewhere this string will not be displayed at all.

XineramaScreen

-     XineramaScreen=0

  If the Xinerama extension is active the login window will be centered on this physical screen (use 0 for the first screen, 1 for the second...).

#### XDCMP Chooser Options

#### [chooser]

AllowAdd

-     AllowAdd=true

  If true, allow the user to add arbitrary hosts to the chooser. This way the user could connect to any host that responds to XDMCP queries from the chooser.

Broadcast

-     Broadcast=true

  If true, the chooser will broadcast a query to the local network and collect responses. This way the chooser will always show all available managers on the network. If you need to add some hosts not local to this network, or if you don't want to use a broadcast, you can list them explicitly in the `Hosts` key.

Multicast

-     Multicast=true

  If true and IPv6 is enabled, the chooser will send a multicast query to the local network and collect responses from the hosts who have joined multicast group. If you don't want to send a multicast, you can specify IPv6 address in the `Hosts` key. The host will respond if it is listening to XDMCP requests and IPv6 is enabled there.

MulticastAddr

-     MulticastAddr=ff02::1

  This is the Link-local Multicast address and is hardcoded here.

DefaultHostImage

-     DefaultHostImage=<share>/pixmaps/nohost.png

  File name for the default host icon. This image will be displayed if no icon is specified for a given host. The file must be in a gdk-pixbuf supported format and it must be readable for the MDM user.

HostImageDir

-     HostImageDir=<share>/hosts

  Repository for host icon files. The sysadmin can place icons for remote hosts here and they will appear in `mdmchooser`.

  The file name must match the fully qualified name (FQDN) for the host. The icons must be stored in gdk-pixbuf supported formats and they must be readable to the MDM user.

Hosts

-     Hosts=host1,host2

  The hosts which should be listed in the chooser. The chooser will only list them if they respond. This is done in addition to broadcast (if `Broadcast` is set), so you need not list hosts on the local network. This is useful if your networking setup doesn't allow all hosts to be reachable by a broadcast packet.

ScanTime

-     ScanTime=4

  Specifies how many seconds the chooser should wait for replies to its BROADCAST_QUERY. Really this is only the time in which we expect a reply. We will still add hosts to the list even if they reply after this time.

#### Debug Configuration

#### [debug]

Enable

-     Enable=false

  Setting to true sends debug ouput to the syslog. This can be useful for tracking down problems with MDM. This output tends to be verbose so should not be turned on for general use.

Gestures

-     Gestures=false

  Setting to true sends debug ouput concerning the accessibility gesture listeners to the syslog. This can be useful for tracking down problems with them not working properly. This output tends to be verbose so should not be turned on for general use.

#### Custom Commands

You can create up to 10 different commands. Gaps between command numbers are allowed and their relative positioning within the section and with respect to each other is not important as long as they conform to the permitted range of [0-9].

#### [customcommand]

CustomCommand[0-9]

-     CustomCommand[0-9]=

  Full path and arguments to command to be executed when user selects `n-th` "Custom Command" from the Actions menu. This can be a ';' separated list of commands to try. If the value is empty or missing, then the custom command is not available. By default this value is not enabled, so to enable "Custom Command" it must be set to a nonempty value. [0-9] represents the `CustomCommand` suffix and can be an integer between 0 and 9.

CustomCommandIsPersistent[0-9]

-     CustomCommandIsPersistent[0-9]=

  Specifies if `n-th` "Custom Command" will appear outside the login manager, for example on the desktop through the Log Out/Shut Down dialogs. If not specified the default value is "false". This option is only valid if corresponding `CustomCommand` is defined. [0-9] represents `CustomCommand` suffix and can be an integer between 0 and 9.

CustomCommandLabel[0-9]

-     CustomCommandLabel[0-9]=

  Specifies the stock label that will be displayed on the `n-th` "Custom Command" buttons and menu items. If not specified the default value is "Custom_[0-9]". This option is only valid if corresponding `CustomCommand` is defined. [0-9] represents `CustomCommand` suffix and can be an integer between 0 and 9. This option can't contain any semicolon characters (i.e. ";").

CustomCommandLRLabel[0-9]

-     CustomCommandLRLabel[0-9]=

  Specifies the stock label that will be displayed on the `n-th` "Custom Command" list items and radio buttons. If not specified the default value is "Execute custom command _[0-9]". This option is only valid if corresponding `CustomCommand` is defined. [0-9] represents `CustomCommand` suffix and can be an integer between 0 and 9.

CustomCommandNoRestart[0-9]

-     CustomCommandNoRestart[0-9]=

  Specifies if mdm will be stopped/restarted once `n-th` "Custom Command" has been executed. If not specified the default value is "false". This option is only valid if corresponding `CustomCommand` is defined. [0-9] represents `CustomCommand` suffix and can be an integer between 0 and 9. In addition when corresponding `CustomCommandIsPersistent` is set to true, setting CustomCommandNoRestart to false will place corresponding `CustomCommand` in the Shut Down dialog set of actions, setting it to true will place corresponding `CustomCommand` in the Log Out dialog set of actions.

CustomCommandText[0-9]

-     CustomCommandText[0-9]=

  Specifies the message that will be displayed on the warning dialog box once `n-th` "Custom Command" button/menu item/radio button/list item has been activated. If not specified the default value is "Are you sure?". This option is only valid if corresponding `CustomCommand` is defined. [0-9] represents `CustomCommand` suffix and can be an integer between 0 and 9.

CustomCommandTooltip[0-9]

-     CustomCommandTooltip[0-9]=

  Specifies the message that will be displayed on tooltips for `n-th` "Custom Command" entries. If not specified the default value is "Execute custom command [0-9]". This option is only valid if corresponding `CustomCommand` is defined. [0-9] represents `CustomCommand` suffix and can be an integer between 0 and 9.

#### X Server Definitions

MDM needs to be provided with information about each X servers that will be used. You can have as many different definitions as you wish, each identified with a unique name. The name `Standard` is required. If you do not specify this server, MDM will assume default values for a 'Standard' server and the path given by `daemon/StandardXServer`. `Standard` is used as the default, in situations when no other server has been defined.

Servers are defined by sections named `server-` followed by the identifier of this server. This should be a simple ASCII string with no spaces. The GUI configuration program allows users to edit the servers defined in the MDM configuration files but currently does not allow adding or deleting entries. Like normal configuration options, `server-` sections in the `<etc>/mdm/custom.conf` file override values in the `<share>/mdm/defaults.conf` file. In other words, if a `server-Standard` section is defined in `<etc>/mdm/custom.conf`, then that will be used and the section in the `<share>/mdm/defaults.conf` file will be ignored.

#### [server-Standard]

name

-     name=Standard server

  The name that will be displayed to the user.

command

-     command=/path/to/X

  The command to execute, with full path to the binary of the X server, and any extra arguments needed. Normally it is not necessary to add a `-nolisten tcp` argument since the addition of this argument is controlled by the `DisallowTCP` MDM configuration option.

flexible

-     flexible=true

  Indicates if this server is available as a choice when a user wishes to run a flexible, on demand server.

handled

-     handled=true

  Indicates that MDM should run the login window on this server and allow a user to log in. If set to false, then MDM will just run this server and wait for it to terminate. This can be useful to run an X terminal using MDM. When this is done you should normally also add `-terminate` to the command line of the server to make the server terminate after each session. Otherwise the control of the slave will never come back to MDM and, for example, soft restarts won't work. This is because MDM assumes there is a login in progress for the entire time this server is active.

chooser

-     chooser=false

  Indicates that MDM should instead of a login window run a chooser on this window and allow the user to choose which server to log into.

priority

-     priority=0

  Indicates that the X server should be started at a different process priority. Values can be any integer value accepted by the setpriority C library function (normally between -20 and 20) with 0 being the default. For highly interactive applications, -5 yields good responsiveness. The default value is 0 and the setpriority function is not called if the value is 0.

#### Attached DISPLAY Configuration

The attached (also known as local or static) display configuration specifies what displays should be always managed by MDM. MDM will restart the X server on the display if it dies, for example. There may be as many attached displays that are managed as you wish. Typically each display is associated with a real display. On a typical single-display machine this section would only contain one key `0` that corresponds to DISPLAY `:0`.

The GUI configuration program allows users to edit the attached display configuration defined in the MDM configuration files and allows the user to add or delete entries. Like normal configuration options, the `[servers]` section in the `<etc>/mdm/custom.conf` file overrides values in the `<share>/mdm/defaults.conf` file.

#### [servers]

<display number>

-     0=Standard [device=/dev/foo]

  The key cooresponds to the DISPLAY to be managed, so that key `0` cooresponds to DISPLAY `:0`. On a multi-display machine you can configure MDM to manage a login program on other displays by adding additional keys. For example, adding key `1` would cause MDM to manage DISPLAY `:1`.

  The first word of the value corresponds to a X server definition in the "X Server Definitions" section of the configuration file. For example, the following entry means that DISPLAY `:0` will start an X server as defined in the `[server-Standard]` section:

      [servers]
      0=Standard

  The first word of the value can also be set to the string "inactive" to indicate that this DISPLAY should not be managed. This can be used in the MDM Custom Configuration File to turn off a DISPLAY that is defined in the MDM System Defaults Configuration File.

  The optional device argument is used to specify the device that is associated with the DISPLAY. When using Virtual Terminals (VT), this value is ignored and MDM will use the correct device name associated with the VT. If not using VT, then MDM will use the value specified by this optional argument. If the device argument is not defined, then MDM will use the default setting for attached displays defined in the `UtmpLineAttached` configuration section. For the main display (typically DISPLAY `:0`), `/dev/console` is a reasonable value. For other displays it is probably best to not include this argument unless you know the specific device associated with the DISPLAY. The device value can contain "%d" which is translated to the DISPLAY value or "%h" which is translated to the hostname.

### Per User Configuration

There are some per user configuration settings that control how MDM behaves. MDM is picky about the file ownership and permissions of the user files it will access, and will ignore files if they are not owned by the user or files that have group/world write permission. It will also ignore the user if the user's $HOME directory is not owned by the user or if the user's $HOME directory has group/world write permission. files must also be smaller than the `UserMaxFile` value as defined in the MDM configuration. If it seems that MDM is not properly accessing user configuration settings, the problem is most likely caused by one of these checks failing.

First there is the `~/.dmrc` file. In theory this file should be shared between MDM and KDM, so users only have to configure things once. This is a standard `.ini` style configuration file. It has one section called `[Desktop]` which has two keys: `Session` and `Language`.

The `Session` key specifies the basename of the session `.desktop` file that the user wishes to normally use (without the `.desktop` extension, in other words). The `Language` key specifies the language that the user wishes to use by default. If either of these keys is missing, the system default is used. The file would normally look as follows:

    [Desktop]
    Session=gnome
    Language=cs_CZ.UTF-8

Normally MDM will write this file when the user logs in for the first time, and rewrite it if the user chooses to change their default values on a subsequent login.

If the MDM Face Browser is turned on, then the file `$HOME/.face` is accessed. This file should be a standard image that GTK+ can read, such as PNG or JPEG. It also must be smaller than the `MaxIconWidth` and `MaxIconHeight` values defined in the MDM configuration or it will be ignored. Users can run the `mdmphotosetup` program to specify a face image and it will copy the file to the `$HOME/.face` location and scale it so its longest dimension is not larger than the `MaxIconWidth` or `MaxIconHeight` values. `mdmphotosetup` takes care to not change the aspect ratio of the image.

Face images can also be placed in the global face directory, which is specified by the `GlobalFaceDir` configuration option ( normally `<share>/pixmaps/faces/`) and the filename should be the name of the user, optionally with a `.png`, `.jpg`, etc. appended.

## Controlling MDM

You can control MDM behavior during runtime in several different ways. You can either run certain commands, or you can talk to MDM using either a unix socket protocol, or a FIFO protocol.

### Commands

To stop MDM, you can either send the TERM signal to the main daemon or run the `mdm-stop` command which is in the `<sbin>/` directory. To restart MDM, you can either send the HUP signal to the main daemon or run the `mdm-restart` command which is also in the `<sbin>/` directory. To restart MDM but only after all the users have logged out, you can either send the USR1 signal to the main daemon or run the `mdm-safe-restart` command which is in the `<sbin>/` directory as well.

The `mdmflexiserver` command can be used to start new flexible (on demand) displays if your system supports virtual terminals. This command will normally lock the current session with a screensaver so that the user can safely walk away from the computer and let someone else log in. If more that two flexible displays have started `mdmflexiserver` will display a pop-up dialog allowing the user to select which session to continue. The user will normally have to enter a password to return to the session. On session exit the system will return to the previous virtual terminal. Run `mdmflexiserver --help` to get a listing of possible options.

### The FIFO protocol

MDM also provides a FIFO called `.mdmfifo` in the `ServAuthDir` directory (usually `<var>/mdm/.mdmfifo`). You must be root to use this protocol, and it is mostly used for internal MDM chatter. It is a very simple protocol where you just echo a command on a single line to this file. It can be used to tell MDM things such as restart, suspend the computer, or restart all X servers next time it has a chance (which would be useful from an X configuration application).

Full and up to date documentation of the commands and their use is contained in the MDM source tree in the file `daemon/mdm.h`. Look for the defines starting with `MDM_SOP_`. The commands which require the pid of the slave as an argument are the ones that are really used for internal communication of the slave with the master and should not be used.

### Socket Protocol

MDM provides a unix domain socket for communication at `/tmp/.mdm_socket`. Using this you can check if MDM is running, the version of the daemon, the current displays that are running and who is logged in on them, and if MDM supports it on your operating system, also the virtual terminals of all the console logins. The `mdmflexiserver` command uses this protocol, for example, to launch flexible (on-demand) displays.

mdmflexiserver accepts the following commands with the --command option:

    ADD_DYNAMIC_DISPLAY
    ALL_SERVERS
    ATTACHED_SERVERS
    AUTH_LOCAL
    CLOSE
    FLEXI_XNEST
    FLEXI_XNEST_USER
    FLEXI_XSERVER
    FLEXI_XSERVER_USER
    GET_CONFIG
    GET_CONFIG_FILE
    GET_CUSTOM_CONFIG_FILE
    GET_SERVER_LIST
    GET_SERVER_DETAILS
    GREETERPIDS
    QUERY_LOGOUT_ACTION
    QUERY_CUSTOM_CMD_LABELS
    QUERY_CUSTOM_CMD_NO_RESTART_STATUS
    QUERY_VT
    RELEASE_DYNAMIC_DISPLAYS
    REMOVE_DYNAMIC_DISPLAY
    SERVER_BUSY
    SET_LOGOUT_ACTION
    SET_SAFE_LOGOUT_ACTION
    SET_VT
    UPDATE_CONFIG
    VERSION

These are described in detail below, including required arguments, response format, and return codes.

#### ADD_DYNAMIC_DISPLAY

    ADD_DYNAMIC_DISPLAY: Create a new server definition that will
                         run on the specified display leaving, it
                         in DISPLAY_CONFIG state.
    Supported since: 2.8.0.0
    Arguments: <display to run on>=<server>
      Where <server> is either a configuration named in the
      MDM configuration or a literal command name.
    Answers:
      OK <display>
      ERROR <err number> <english error description>
         0 = Not implemented
         2 = Existing display
         3 = No server string
         4 = Display startup failure
         100 = Not authenticated
         200 = Dynamic Displays not allowed
         999 = Unknown error

#### ALL_SERVERS

    ALL_SERVERS: List all displays, including console, remote, xnest.
                 This can, for example, be useful to figure out if
                 the display you are on is managed by the mdm daemon,
                 by seeing if it is in the list.  It is also somewhat
                 like the 'w' command but for graphical sessions.
    Supported since: 2.4.2.96
    Arguments: None
    Answers:
      OK <server>;<server>;...

      <server> is <display>,<logged in user>

      <logged in user> can be empty in case no one logged in yet

      ERROR <err number> <english error description>
         0 = Not implemented
         200 = Too many messages
         999 = Unknown error

#### ATTACHED_SERVERS

    ATTACHED_SERVERS: List all attached displays.  Doesn't list XDMCP
                      and xnest non-attached displays.
    Note:             This command used to be named CONSOLE_SERVERS,
                      which is still recognized for backwards
                      compatibility. The optional pattern argument
                      is supported as of version 2.8.0.0.
    Supported since: 2.2.4.0
    Arguments: <pattern> (optional)
      With no argument, all attached displays are returned. The optional
      <pattern> is a string that may contain glob characters '*', '?', and
      '[]'. Only displays that match the pattern will be returned.
    Answers:
      OK <server>;<server>;...

      <server> is <display>,<logged in user>,<vt or xnest
      display>

      <logged in user> can be empty in case no one logged
      in yet, and <vt> can be -1 if it's not known or not
      supported (on non-Linux for example).  If the display is an
      xnest display and is a console one (that is, it is an xnest
      inside another console display) it is listed and instead of
      vt, it lists the parent display in standard form.

      ERROR <err number> <english error description>
         0 = Not implemented
         200 = Too many messages
         999 = Unknown error

#### AUTH_LOCAL

    AUTH_LOCAL: Setup this connection as authenticated for
                FLEXI_SERVER.  Because all full blown
                (non-nested) displays can be started only from
                users logged into attached displays, and here MDM
                assumes only users logged in from MDM.  They must
                pass the xauth MIT-MAGIC-COOKIE-1 that they were
                passed before the connection is authenticated.
    Note:       The AUTH LOCAL command requires the
                --authenticate option, although only
                FLEXI XSERVER uses this currently.
    Note:       Since 2.6.0.6 you can also use a global
                <ServAuthDir>/.cookie, which works for all
                authentication except for SET_LOGOUT_ACTION and
                QUERY_LOGOUT_ACTION and SET_SAFE_LOGOUT_ACTION
                which require a logged in display.
    Supported since: 2.2.4.0
    Arguments: <xauth cookie>
      <xauth cookie> is in hex form with no 0x prefix
    Answers:
      OK
      ERROR <err number> <english error description>
         0 = Not implemented
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### CLOSE

    CLOSE: Close sockets connection
    Supported since: 2.2.4.0
    Arguments: None
    Answers: None

#### FLEXI_XNEST

    FLEXI_XNEXT: Start a new flexible nested display.
    Note:        Supported on older version from 2.2.4.0, later
                 2.2.4.2, but since 2.3.90.4 you must supply 4
                 arguments or ERROR 100 will be returned.  This
                 will start the nested X server command using
                 the XAUTHORITY file supplied and as the uid
                 same as the owner of that file (and same as
                 you supply).  You must also supply the cookie as
                 the third argument for this display, to prove
                 that you indeed are this user.  Also this file
                 must be readable ONLY by this user, that is
                 have a mode of 0600.  If this all is not met,
                 ERROR 100 is returned.
    Note:        The cookie should be the MIT-MAGIC-COOKIE-1,
                 the first one MDM can find in the XAUTHORITY
                 file for this display.  If that's not what you
                 use you should generate one first.  The cookie
                 should be in hex form.
    Supported since: 2.3.90.4
    Arguments: <display to run on> <uid of requesting user>
               <xauth cookie for the display> <xauth file>
    Answers:
      OK <display>
      ERROR <err number> <english error description>
         0 = Not implemented
         1 = No more flexi servers
         2 = Startup errors
         3 = X failed
         4 = X too busy
         5 = Xnest can't connect
         6 = No server binary
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### FLEXI_XNEST_USER

    FLEXI_XNEST_USER: Start a new flexible nested display and
                      initialize the greeter with the given username.
    Note:             This is a variant of the FLEXI_XNEST command.
    Note:             The cookie should be the MIT-MAGIC-COOKIE-1,
                      the first one MDM can find in the XAUTHORITY
                      file for this display.  If that's not what you
                      use you should generate one first.  The cookie
                      should be in hex form.
    Supported since:  2.17.7
    Arguments: <username> <display to run on> <uid of requesting
               user> <xauth cookie for the display> <xauth file>
    Answers:
      OK <display>
      ERROR <err number> <english error description>
         0 = Not implemented
         1 = No more flexi servers
         2 = Startup errors
         3 = X failed
         4 = X too busy
         5 = Xnest can't connect
         6 = No server binary
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### FLEXI_XSERVER

    FLEXI_XSERVER: Start a new X flexible display.  Only supported on
                   connection that passed AUTH_LOCAL
    Supported since: 2.2.4.0
    Arguments: <xserver type>
      If no arguments, starts the standard X server
    Answers:
      OK <display>
      ERROR <err number> <english error description>
         0 = Not implemented
         1 = No more flexi servers
         2 = Startup errors
         3 = X failed
         4 = X too busy
         6 = No server binary
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### FLEXI_XSERVER_USER

    FLEXI_XSERVER_USER: Start a new X flexible display and initialize the
                        greeter with the given username.  Only supported on
                        connection that passed AUTH_LOCAL
    Supported since:    2.17.7
    Arguments: <username> <xserver type>
      If no server type specified, starts the standard X server
    Answers:
      OK <display>
      ERROR <err number> <english error description>
         0 = Not implemented
         1 = No more flexi servers
         2 = Startup errors
         3 = X failed
         4 = X too busy
         6 = No server binary
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### GET_CONFIG

    GET_CONFIG:  Get configuration value for key.  Useful so
                 that other applications can request configuration
                 information from MDM.  Any key defined as MDM_KEY_*
                 in mdm-daemon-config-keys.h is supported.  Starting with version
                 2.13.0.2, translated keys (such as
                 "greeter/MdmWelcome[cs]" are supported via GET_CONFIG.
                 Also starting with version 2.13.0.2 it is no longer necessary to
                 include the default value (i.e. you can use key
                 "greeter/IncludeAll" instead of having to use
                 "greeter/IncludeAll=false".
    Supported since: 2.6.0.9
    Arguments: <key>
    Answers:
      OK <value>
      ERROR <err number> <english error description>
         0 = Not implemented
         50 = Unsupported key
         200 = Too many messages
         999 = Unknown error

#### GET_CONFIG_FILE

    GET_CONFIG_FILE:  Get config file location being used by
                      the daemon.  If the MDM daemon was started
                      with the --config option, it will return
                      the value passed in via the argument.
    Supported since: 2.8.0.2
    Arguments: None
    Answers:
      OK <full path to MDM configuration file>
      ERROR <err number> <english error description>
         0 = Not implemented
         200 = Too many messages
         999 = Unknown error

#### GET_CUSTOM_CONFIG_FILE

    GET_CUSTOM_CONFIG_FILE:  Get custom config file location being
                            used by the daemon.
    Supported since: 2.14.0.0
    Arguments: None
    Answers:
      OK <full path to MDM custom configuration file>
      ERROR <err number> <english error description>
         0 = Not implemented
         1 = File not found
         200 = Too many messages
         999 = Unknown error

#### GET_SERVER_DETAILS

    GET_SERVER_DETAILS:  Get detail information for a specific server.
    Supported since: 2.13.0.4
    Arguments: <server> <key>
      Key values include:
        NAME      - Returns the server name
        COMMAND   - Returns the server command
        FLEXIBLE  - Returns "true" if flexible, "false"
                    otherwise
        CHOOSABLE - Returns "true" if choosable, "false"
                    otherwise
        HANDLED   - Returns "true" if handled, "false"
                    otherwise
        CHOOSER   - Returns "true" if chooser, "false"
                    otherwise
        PRIORITY  - Returns process priority
    Answers:
      OK <value>
      ERROR <err number> <english error description>
         0 = Not implemented
         1 = Server not found
         2 = Key not valid
         50 = Unsupported key
         200 = Too many messages
         999 = Unknown error

#### GET_SERVER_LIST

    GET_SERVER_LIST:  Get a list of the server sections from
                      the configuration file.
    Supported since: 2.13.0.4
    Arguments: None
    Answers:
      OK <value>;<value>;...
      ERROR <err number> <english error description>
         0 = Not implemented
         1 = No servers found
         200 = Too many messages
         999 = Unknown error

#### GREETERPIDS

    GREETERPIDS: List all greeter pids so that one can send HUP
                 to them for config rereading.  Of course one
                 must be root to do that.
    Supported since: 2.3.90.2
    Arguments: None
    Answers:
      OK <pid>;<pid>;...
      ERROR <err number> <english error description>
         0 = Not implemented
         200 = Too many messages
         999 = Unknown error

#### QUERY_LOGOUT_ACTION

    QUERY_LOGOUT_ACTION: Query which logout actions are possible
                         Only supported on connections that passed
                         AUTH_LOCAL.
    Supported since: 2.5.90.0
    Answers:
      OK <action>;<action>;...
         Where action is one of HALT, REBOOT, SUSPEND or CUSTOM_CMD[0-9].
         An empty list can also be returned if no action is possible.
         A '!' is appended to an action if it was already set with
         SET_LOGOUT_ACTION or SET_SAFE_LOGOUT_ACTION.  Note that
         SET_LOGOUT_ACTION has precedence over
         SET_SAFE_LOGOUT_ACTION.
      ERROR <err number> <english error description>
         0 = Not implemented
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### QUERY_CUSTOM_CMD_LABELS

     QUERY_CUSTOM_CMD_LABELS: Query labels belonging to exported custom
                              commands Only supported on connections that
                              passed AUTH_LOCAL.
     Supported since: 2.5.90.0
     Answers:
       OK <label1>;<label2>;...
          Where labelX is one of the labels belonging to CUSTOM_CMDX
          (where X in [0,MDM_CUSTOM_COMMAND_MAX)).  An empty list can
          also be returned if none of the custom commands are exported
          outside login manager (no CustomCommandIsPersistent options
          are set to true).
       ERROR <err number> <english error description>
          0 = Not implemented
          100 = Not authenticated
          200 = Too many messages
          999 = Unknown error

#### QUERY_CUSTOM_CMD_NO_RESTART_STATUS

    QUERY_CUSTOM_CMD_NO_RESTART_STATUS: Query NoRestart config options
                                        for each of custom commands Only
                                        supported on connections that
                                        passed AUTH_LOCAL.
    Supported since: 2.5.90.0
    Answers:
      OK <status>
         Where each bit of the status represents NoRestart value for
         each of the custom commands.
         bit on (1):  NoRestart = true,
         bit off (0): NoRestart = false.
      ERROR <err number> <english error description>
         0 = Not implemented
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### QUERY_VT

    QUERY_VT:  Ask the daemon about which VT we are currently on.
               This is useful for logins which don't own
               /dev/console but are still console logins.  Only
               supported on Linux currently, other places will
               just get ERROR 8.  This is also the way to query
               if VT support is available in the daemon in the
               first place.  Only supported on connections that
               passed AUTH_LOCAL.
    Supported since: 2.5.90.0
    Arguments: None
    Answers:
      OK <vt number>
      ERROR <err number> <english error description>
         0 = Not implemented
         8 = Virtual terminals not supported
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### RELEASE_DYNAMIC_DISPLAYS

    RELEASE_DYNAMIC_DISPLAYS: Release dynamic displays currently in
                              DISPLAY_CONFIG state
    Supported since: 2.8.0.0
    Arguments: <display to release>
    Answers:
      OK <display>
      ERROR <err number> <english error description>
         0 = Not implemented
         1 = Bad display number
         100 = Not authenticated
         200 = Dynamic Displays not allowed
         999 = Unknown error

#### REMOVE_DYNAMIC_DISPLAY

    REMOVE_DYNAMIC_DISPLAY: Remove a dynamic display, killing the server
                            and purging the display configuration
    Supported since: 2.8.0.0
    Arguments: <display to remove>
    Answers:
      OK <display>
      ERROR <err number> <english error description>
         0 = Not implemented
         1 = Bad display number
         100 = Not authenticated
         200 = Dynamic Displays not allowed
         999 = Unknown error

#### SERVER_BUSY

    SERVER_BUSY:  Returns true if half or more of the daemon's sockets
                  are busy, false otherwise.  Used by slave programs
                  which want to ensure they do not overwhelm the
                  sever.
    Supported since: 2.13.0.8
    Arguments: None
    Answers:
      OK <value>
      ERROR <err number> <english error description>
         0 = Not implemented
         200 = Too many messages
         999 = Unknown error

#### SET_LOGOUT_ACTION

    SET_LOGOUT_ACTION: Tell the daemon to halt/restart/suspend after
                       slave process exits.  Only supported on
                       connections that passed AUTH_LOCAL.
    Supported since: 2.5.90.0
    Arguments: <action>
      NONE               Set exit action to 'none'
      HALT               Set exit action to 'halt'
      REBOOT             Set exit action to 'reboot'
      SUSPEND            Set exit action to 'suspend'
      CUSTOM_CMD[0-9]    Set exit action to 'custom command [0-9]'
    Answers:
      OK
      ERROR <err number> <english error description>
         0 = Not implemented
         7 = Unknown logout action, or not available
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### SET_SAFE_LOGOUT_ACTION

    SET_SAFE_LOGOUT_ACTION:  Tell the daemon to halt/restart/suspend
                             after everybody logs out.  If only one
                             person logs out, then this is obviously
                             the same as the SET_LOGOUT_ACTION.  Note
                             that SET_LOGOUT_ACTION has precedence
                             over SET_SAFE_LOGOUT_ACTION if it is set
                             to something other then NONE.  If no one
                             is logged in, then the action takes effect
                             effect immediately.  Only supported on
                             connections that passed AUTH_LOCAL.
    Supported since: 2.5.90.0
    Arguments: <action>
      NONE               Set exit action to 'none'
      HALT               Set exit action to 'halt'
      REBOOT             Set exit action to 'reboot'
      SUSPEND            Set exit action to 'suspend'
      CUSTOM_CMD[0-9]    Set exit action to 'custom command [0-9]'
    Answers:
      OK
      ERROR <err number> <english error description>
         0 = Not implemented
         7 = Unknown logout action, or not available
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### SET_VT

    SET_VT:  Change to the specified virtual terminal.
             This is useful for logins which don't own /dev/console
             but are still console logins.  Only supported on Linux
             currently, other places will just get ERROR 8.
             Only supported on connections that passed AUTH_LOCAL.
    Supported since: 2.5.90.0
    Arguments: <vt>
    Answers:
      OK
      ERROR <err number> <english error description>
         0 = Not implemented
         8 = Virtual terminals not supported
         9 = Invalid virtual terminal number
         100 = Not authenticated
         200 = Too many messages
         999 = Unknown error

#### UPDATE_CONFIG

    UPDATE_CONFIG: Tell the daemon to re-read a key from the
                   MDM configuration file.   Any user can request
                   that values are re-read but the daemon will
                   only do so if the file has been modified
                   since MDM first read the file.  Only users
                   who can change the MDM configuration file
                   (normally writable only by the root user) can
                   actually modify the MDM configuration.  This
                   command is useful to cause the MDM to update
                   itself to recognize a change made to the MDM
                   configuration file by the root user.

                   Starting with version 2.13.0.0, all MDM keys are
                   supported except for the following:

                          daemon/PidFile
                          daemon/ConsoleNotify
                          daemon/User
                          daemon/Group
                          daemon/LogDir
                          daemon/ServAuthDir
                          daemon/UserAuthDir
                          daemon/UserAuthFile
                          daemon/UserAuthFBDir

                   MDM also supports the following Psuedokeys:

                   xdmcp/PARAMETERS (2.3.90.2) updates the following:
                          xdmcp/MaxPending
                          xdmcp/MaxSessions
                          xdmcp/MaxWait
                          xdmcp/DisplaysPerHost
                          xdmcp/HonorIndirect
                          xdmcp/MaxPendingIndirect
                          xdmcp/MaxWaitIndirect
                          xdmcp/PingIntervalSeconds (only affects new connections)

                    xservers/PARAMETERS (2.13.0.4) updates the following:
                          all [server-foo] sections.

                    Supported keys for previous versions of MDM:

                          security/AllowRoot (2.3.90.2)
                          security/AllowRemoteRoot (2.3.90.2)
                          security/AllowRemoteAutoLogin (2.3.90.2)
                          security/RetryDelay (2.3.90.2)
                          security/DisallowTCP (2.4.2.0)
                          daemon/Greeter (2.3.90.2)
                          daemon/RemoteGreeter (2.3.90.2)
                          xdmcp/Enable (2.3.90.2)
                          xdmcp/Port (2.3.90.2)
                          daemon/TimedLogin (2.3.90.3)
                          daemon/TimedLoginEnable (2.3.90.3)
                          daemon/TimedLoginDelay (2.3.90.3)
                          greeter/SystemMenu (2.3.90.3)
                          greeter/ConfigAvailable (2.3.90.3)
                          greeter/ChooserButton (2.4.2.0)
                          greeter/SoundOnLoginFile (2.5.90.0)
                          daemon/AddGtkModules (2.5.90.0)
                          daemon/GtkModulesList (2.5.90.0)
    Supported since: 2.3.90.2
    Arguments: <key>
      <key> is just the base part of the key such as
      "security/AllowRemoteRoot"
    Answers:
      OK
      ERROR <err number> <english error description>
         0 = Not implemented
         50 = Unsupported key
         200 = Too many messages
         999 = Unknown error

#### VERSION

    VERSION: Query MDM version
    Supported since: 2.2.4.0
    Arguments: None
    Answers:
      MDM <mdm version>
      ERROR <err number> <english error description>
         200 = Too many messages
         999 = Unknown error

## MDM Commands

### MDM User Commands

The MDM package provides the following different commands in `/usr/bin` intended to be used by the end-user:

#### `mdm-recovery`

`mdm-recovery` gives MDM a safe configuration. Its purpose is to prevent most common issues from happening and helping the user successfully log in. Launch this command if you are unable to log in.

#### `mdm-theme-emulator`

`mdm-theme-emulator` is an emulator for HTML theme artists. It is able to open HTML themes and emulate MDM to a certain extent.

#### `mdmflexiserver`

`mdmflexiserver` locks the session and invokes a greeter (i.e. a login screen). It is the command used by the screensaver to switch users. If a greeter is already running, mdmflexiserver switches to it. Otherwise it asks MDM to start a new one.

`mdmflexiserver` can also be used with the -c argument to launch a command on the MDM daemon.

For instance `mdmflexiserver -c "GET_CONFIG daemon/Greeter"` returns the value of the active greeter.

And `mdmflexiserver -c "ATTACHED_SERVERS"` returns a list of active MDM servers (i.e. sessions and greeters).

### MDM Root User Commands

The MDM package provides the following different commands in `/usr/sbin` intended to be used by the root user:

#### `mdm`

#### Command Line Options

--help

- Gives a brief overview of the command line options.

--nodaemon

- If this option is specified, then MDM does not fork into the background when run. You can also use a single-dash version, "-nodaemon" for compatibility with other display managers.

--no-console

- Tell the daemon that it should not run anything on the console. This means that none of the attached servers from the `[servers]` section will be started, and the console will not be used for communicating errors to the user. An empty `[servers]` section automatically implies this option.

--config=CONFIGFILE

- Specify an alternative configuration file.

--preserve-ld-vars

- When clearing the environment internally, preserve all variables starting with LD_. This is mostly for debugging purposes.

--version

- Print the version of the MDM daemon.

--wait-for-go

- If started with this option, mdm will init, but only start the first attached display and then wait for a GO message in the fifo protocol. No greeter will be shown until the GO message is sent. Also flexiserver requests will be denied and XDMCP will not be started until GO is given. This is useful for initialization scripts which wish to start X early, but where you don't yet want the user to start logging in. So the script would send the GO to the fifo once it is ready and MDM will then continue. This functionality was added in version 2.5.90.0.

#### `mdmsetup`

`mdmsetup` runs a graphical application for modifying the MDM configuration file.

### MDM Internal Commands

The MDM package provides the following different commands in `/usr/lib/mdm/` intended to be used by the mdm daemon process.

#### `mdmlogin`, `mdmgreeter` and `mdmwebkit`

The `mdmlogin`, `mdmgreeter` and `mdmwebkit` are three different login applications which can be used by MDM. `mdmlogin` is a simple GTK login screen, while `mdmgreeter` and `mdmwebkit` are respectively themed with GDM and HTML themes. These applications are normally executed by the MDM daemon.

#### `mdm-ssh-session`

The `mdm-ssh-session` is normally executed by the MDM daemon when starting a secure remote connection through ssh. It does not take any options.

## GDM Themes

This section describes the creation of GDM themes. For examples of themes, visit gnome-look.org and select "GDM Themes".

### Theme Overview

GDM Themes are located in `/usr/share/mdm/themes`. They contain a file called `GdmGreeterTheme.desktop` which has a similar format to other .desktop files and looks like this:

    [GdmGreeterTheme]
    Encoding=UTF-8
    Greeter=configuration.xml
    Name=Mytheme
    Description=My Theme
    Author=My name
    Copyright=GPL
    Screenshot=screenshot.jpg

The Name, Description, Author and Copyright fields can be translated just like the other `.desktop`files. All the files that are mentioned should be in the theme directory itself. The Screenshot field points to a file which should be a 200x150 screenshot of the theme in action. The Greeter field points to an XML file that contains the structure of the theme itself.

### Detailed Description of the Theme XML format

#### greeter tag

The GDM theme format is specified in XML format contained within a <greeter> tag. You may specify a GTK+ theme to be used with this theme by using the gtk-theme element in the greeter tag as in the following example.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE greeter SYSTEM "greeter.dtd">
    <greeter gtk-theme="Crux">
    [...]
    </greeter>

Contained within the greeter tag can be the nodes described in the next sections of this document. Some of these nodes are containers (box nodes, rect item nodes) which can be used to organize how to display the nodes that the user sees and interacts with (such as button, pixmap and entry item nodes).

#### Box Nodes

Box nodes are container nodes for item nodes. Box nodes are specified as follows:

    <box orientation="alignment" min-width="num"
    xpadding="num" ypadding="num" spacing="num"
    homogeneous="bool">

Where "num" means number and bool means either "true" or "false" The alignment value can be either "horizontal" or "vertical". If you leave any property off it will default to zero or "false" in case of "homogeneous" and "vertical" for the orientation.

If the box is homogeneous then the children are allocated equal amount of space.

The "min-width" must be specified in pixels. Obviously there is also a corresponding "min-height" property as well.

#### Fixed Nodes

Fixed is a container that has its children scattered about laid out with precise coordinates. The size of this container is the biggest rectangle that contains all the children. Fixed has no extra properties and so you just use:

    <fixed>

Then you put other items with proper position nodes inside this.

The "toplevel" node is really just like a fixed node.

#### Item Nodes

A GDM Theme is created by specifying a hierarchy of item and box nodes. Item nodes can have the following value for "type":

button

- A button field. This field uses a GTK+ button. It is also possible to make a "rect" item act like a button by setting its button element to true. However it is better to use GTK+ buttons in GDM themes since these are accessible to users with disabilities. Also, GTK+ buttons can be themed.

entry

- Text entry field.

label

- A text label. Must have a "text" node to specify the text.

list

- A face browser widget. Only useful if the face browser is enabled via the configuration.

pixmap

- An pixmap image in a format that gdk-pixbuf supports like PNG, JPEG, Tiff, etc...)

rect

- Rectangle.

svg

- Scaled Vector Graphic image.

For example:

    <item type="label">

Items can specify ID values which gives them a specific look and feel or formatting. Furthermore you can customize the login process by adding custom widgets with custom id's for some items (currently only the list item)

Entry items can have id values as follows:

user-pw-entry

- Entry field for userid and password entry. This is the field used for responses for the PAM/MDM questions (Username, Password, etc..).

List items by default display as lists, but the combo="true" attribute can be used to specify combo box style. Some predefined lists may be included in a theme by using the following id values. Customized lists may also be defined, which are explained below.

session

- A list of available sessions, which allows the user to pick the session to use.

language

- A list of available languages, which allows the user to pick the language to use.

userlist

- A Face Browser list, so that users can pick their username by clicking on this instead of typing. This obviously exposes the usernames to viewers of the login screen, and is not recommended for users who feel that this reduces security. The face browser does not support combo box style.

userlist-rect

- This id can be specified for the <rect> object containing the userlist and if the userlist is empty then this rectangle will not be shown. This allows the theme to define something like an area with a different color and/or alpha to surround the userlist, but only if there are users to display.

Furthermore, you can have an arbitrary id (I'd recommend starting the id with 'custom' not to conflict with future additions to this spec) and ask extra information of the user. See the section 'Custom Widgetry'

Label items can have id values as follows:

clock

- Label that displays the date and time.

pam-prompt

- Label that displays the PAM prompt. This is the prompt that PAM uses to ask for username, password, etc...

pam-error

- Label that displayst PAM/MDM error messages. Such as when user can't log in.

pam-error-logo

- An image that will be displayed only when a pam-error message is being displayed. This is useful for displaying an "Attention" icon, for example.

pam-message

- Label that displays the PAM message. These are messages that PAM/MDM gives about state of the account, help about the prompts and other information.

timed-label

- Label that displays timed login information.

Rectangles can have id values as follows:

caps-lock-warning

- Displays an icon that shows if the CAPS LOCK key is depressed. This rectangle will be hidden/shown appropriately

If an item is of type rect, the item can be a button. Buttons must also include a "button" value as follows:

    <item type="rect" id="disconnect_button" button="true">.

Possible values for button ids are as follows.

disconnect_button

- Disconnect from remote session.

language_button

- Displays the language selection dialog.

halt_button

- Halt (shuts down) the system.

reboot_button

- Restart the system.

session_button

- List and select from available sessions.

suspend_button

- Suspend the system.

system_button

- Perform halt/restart/suspend/etc. options (if allowed by MDM configuration). Also allows user to run configurator if user enters root password (again if allowed by MDM configuration). This is usually now labeled Actions, and referred to as the Actions menu.

By default, the MDM login screen will disappear after authentication. This can result in flicker between the login screen and the session. The "background" property allows users to specify what elements of the theme are the background image. When used, this will cause MDM to remove all non-background items from the display and render the remaining "background" items to the root window. This can be used to create a smooth transition between the login screen and the session. For example, if the GDM theme and the session use the same background, then this will make the background apear seamless.

Item nodes may specify a "background" property which can be set to "true" or "false" (not setting this property is equivalent to "false"), as follows:

    <item type="rect" background="true">
        <normal file="background.svg"/>
        <pos x="0" y="0" width="100%" height="-75"/>
    </item>

If no item node has "background" property set, then the background is not modified when greeter exits.

To use a different background for login transition than the one used for login, the theme should specify two item nodes (which could contain pixmaps or svg images, for example). The item which corresponds to the greeter background should not have the "background" property while the item which corresponds to the transition background should have the "background" property. For instance :

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE greeter SYSTEM "greeter.dtd">
     <greeter>

      <item type="rect" background="true">
        <normal file="background_for_login.svg"/>
        <pos x="0" y="0" width="100%" height="100%"/>
      </item>
      <item type="rect">
        <normal file="background_for_greeter.svg"/>
        <pos x="0" y="0" width="100%" height="100%"/>
      </item>
    [...]
    </greeter>

#### Position Node

Each item can specify its position and size via the "pos" node. For example:

    <pos x="0" y="4" width="100%" height="100%"/>

Both position and size can be given in percent and it will be taken as the percentage of the size of the current container. For toplevel items it's the percentage of the whole screen.

For x and y, you can also specify a negative position which means position from the right or bottom edge. But this only applies with absolute coordinates. With percentage you can specify negative position and it will be still from the same edge.

The position also specifies the anchor of the item, this can be "n" "ne" "e" "se" "s" "sw" "w" and "nw" or "center" which stand for the different edges/corners or "center" for center. For example:

    <pos x="10%" y="50%" anchor="w" width="80%" height="95"/>

If the item contains a box, you can specify width and height to be "box" to mean that they are supposed to be the width and height of the box, that is the items in the box plus the padding.

If the item contains an SVG image, you can specify width and height to be "scale" to mean that the SVG image should be scaled to fit the requested area.

You can also specify an "expand" property to either be "true" or false. If true then the child will be expanded in the box as much as possible (that is it will be given more space if available).

There are two extra properties you can specify (as of 2.4.4.3) for labels (and labels only). The first is "max-width" which will specify the maximum width of the label in pixels. And the second is "max-screen-percent-width" which specifies the maximum percentage of the screen width that the label can occupy. By default no label will occupy more then 90% of the screen by width. An example may be:

    <item type="label">
    <pos x="10%" max-screen-percent-width="50%"/>

#### Show Node

Some items may only display in certain modes, like when doing a remote display. Multiple values can be specified and must be separated with commas. The following values are possible:

`console` - In console mode.

`console-fixed` - In console non-flexi mode.

`console-flexi` - In console & flexi mode.

`flexi` - In flexi mode.

`remote` - In remote mode.

`remote-flexi` - In remote & flexi mode.

For example:

    <show modes="flexi,remote"/>

You can also specify the "type" value to indicate that certain items should only be displayed if the type is true. Valid values include the following:

`chooser`, if ChooserButton is set to "true" in the MDM configuration.

`config`, if ConfigAvailable is set to "true" in the MDM configuration.

`custom_cmd[0-9]`, if `n-th` CustomCommand is specified in the MDM configuration.

`halt`, if HaltDaemon is specified in the MDM configuration.

`reboot`, if RebootCommand is specified in the MDM configuration.

`suspend`, if SuspendCommand is specified in the MDM configuration.

`system`, if SystemMenu is specified in the MDM configuration.

`timed`, if TimedLoginEnabled is set to "true" in the MDM configuration.

For example:

    <show modes="console" type="system"/>

Alternatively, you can specify a "min-screen-width" or "min-screen-height" value to indicate that certain items should only be displayed if the screen resolution is the at least the given required size.

For example:

    <show min-screen-height="768"/>

Note that if SystemMenu is off then the halt, restart, suspend, chooser and config choices will not be shown, so this is a global toggle for them all. See some of the standard themes for how the show modes are used.

#### Normal/Active/Prelight Nodes

Depending on the item type (except for userlist - refer to Color node below), it can specify its color, font, or image via the following tags:

`normal` - normal state.

`active` - when the item has active focus.

`prelight` - when the mouse is hovering over the item.

When item is "rect" (alpha can be omitted and defaults to 0.0):

    <normal color="#ffffff" alpha="0.0">

When item is "label"

    <normal color="#ffffff" font="Sans 14"/>

When the item type is "pixmap" or "SVG", then the normal, active, and prelight tags specify the images to use as follows:

    <normal file="picture.png" tint="#dddddd"/>

Note that relative pathnames are assumed to be in the same directory as the theme `.xml` file in `<share>/mdm/themes/<theme_name>`.

Note that alternative image file can be specified using the altfile[n] property. MDM will use the last valid image filename specified. For example:

    <normal file="picture.png" altfile1="distribution-blah-image.png" altfile2="distribution-foo-image.png"/>

If `distribution-foo-image.png` is a valid image filename it will be used. Otherwise distribution-blah-image.png will be used if valid. This feature supported since 2.16.3.

#### Face Browser Icon/Label Color Nodes

If the item type is of userlist, then the background color for the icon and label can be set separately via the the following tag:

    <color iconcolor="#dddddd" labelcolor="#ffffff"/>

#### Text Node

Text tags are used by labels. They can be used to display localized text as follows (if the "xml:lang" attribute is omitted, the C locale is assumed):

    <text xml:lang="fr">Option</text>

You can include pango markup in the text nodes for labels, however you must encode it. So for example to have the label of "foo<sup>bar</sup>", you must type:

    <text>"foo<sup>bar</sup>"</text>

Text nodes can contain the following special character sequences which will be translated as follows:

%% - A literal % character

%c - Clock time. Only labels with the "clock" id will update automatically every second. Other labels will contain a static timestamp.

%d - Display name (DISPLAY environment variable)

%h - Hostname (gethostname output)

%m - Machine name (uname.machine output)

%n - Node name (uname.nodename output)

%o - Domain name (getdomainname output)

%r - Release name (uname.release output)

%s - System name (uname.sysname output)

%t - Current timed delay value from configuration file (0 if off) followed by the word "seconds" if value is greater than 1 or the word "second" if the value is 1. This character sequence is intended to be only used internally to display the "timed-label" message, which is automatically updated every second.

%u - Timed username value from configuration file (empty if off) This character sequence is intended to be only used internally to display the "timed-label" message, which is automatically updated every second.

\n - Carriage return

_ - An underscore causes the following character to be underlined. If it precedes a % character sequence, the string that replaces the character sequence is underlined.

#### Stock node

Certain common localized labels can be specified via the stock tags. The "text" tag is ignored if the "stock" tag is used. You should really use the stock labels rather then just putting all the translations into the themes. This gives faster load times and likely better translations. The following values are valid:

`cancel`, _("_Cancel"

`caps-lock-warning`, _("Caps Lock is on."

`disconnect`, _("D_isconnect"

`halt`, _("Shut _Down"

`language`, _("_Language"

`ok`, _("_OK"

`options`, _("_Options"

`quit`, _("_Quit"

`reboot`, _("_Restart"

`session`, _("_Session"

`startagain`, _("_Start Again"

`suspend`, _("Sus_pend"

`system`, _("_Actions" (Formerly "S_ystem"

`timed-label`, _("User %u will login in %t"

`username-label`, _("Username:"

`welcome-label`, _("Welcome to %n"

For example:

    <stock type="welcome-label">

#### Custom Widgetry

Currently there is one item which is customizable and this is the list item. If you need to ask the user extra things, such as to pick from a list of places to log into, or set of custom login sessions you can setup the list item and add listitem children that describe the choices. Each listitem must have an id and a text child. The choice will be recorded in the file `<ServAuthDir>/<display>.GreeterInfo` as `<list id>=<listitem id>`.

For example suppose we are on display :0, `ServAuthDir` is `<var>/lib/mdm` and we have the following in the theme:

    <item type="list" id="custom-config">
    <pos anchor="nw" x="1" y="1" height="200" width="100"/>
    <listitem id="foo">
    <text>Foo</text>
    </listitem>
    <listitem id="bar">
    <text>Bar</text>
    </listitem>
    </item>

The file is created in INI format. The group value is "GreeterInfo", and the "custom-config" key will specify the id of the chosen listitem. For example, if the user chooses "Foo" (which has an id value of "foo", then `<var>/lib/mdm/:0.GreeterInfo` will contain:

    [GreeterInfo]
    custom-config=foo

## Troubleshooting

This section discusses helpful tips for getting MDM working.

If MDM is failing to work properly, it is always a good idea to include debug information. Use the `mdmsetup` command to turn on debug ("Log debug information to /var/log/syslog" in the "Options" tab), reboot and then use MDM to the point where it fails, and include the MDM output sent to your system log (`<var>/log/syslog`). Since the system log can be large, please only include the MDM debug information and do not sent the entire file.

If MDM fails to start or you can't log in, reset MDM to its default configuration by using the command `mdm-recovery`. This usually solves the most common issues or the ones related to configuration or a faulty theme.

If you face an issue with one particular greeter, try to run that greeter on its own with the command `DOING_MDM_DEVELOPMENT=1 /usr/lib/mdm/mdmlogin` (for the GTK greeter), `DOING_MDM_DEVELOPMENT=1 /usr/lib/mdm/mdmgreeter` (for the GDM greeter) or `DOING_MDM_DEVELOPMENT=1 /usr/lib/mdm/mdmwebkit` (for the HTML greeter). Any error messages echoed to the terminal will likely highlight the problem. Also, turning on debug and checking the output sent to the system log will often highlight the problem.

Also make sure that the `/tmp` directory has reasonable ownership and permissions, and that the machine's file system is not full. These problems will cause MDM to fail to start.