Controlling GDM

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

Commands

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

The gdmflexiserver 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 gdmflexiserver 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 gdmflexiserver --help to get a listing of possible options.

The FIFO protocol

GDM also provides a FIFO called .gdmfifo in the ServAuthDir directory (usually <var>/gdm/.gdmfifo). You must be root to use this protocol, and it is mostly used for internal GDM 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 GDM 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 GDM source tree in the file daemon/gdm.h. Look for the defines starting with GDM_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

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

gdmflexiserver 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
  GDM 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 gdm 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 GDM
            assumes only users logged in from GDM.  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 GDM 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 GDM 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 GDM.  Any key defined as GDM_KEY_*
             in gdm-daemon-config-keys.h is supported.  Starting with version
             2.13.0.2, translated keys (such as
             "greeter/GdmWelcome[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 GDM 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 GDM 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 GDM 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,GDM_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 
               GDM 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 GDM first read the file.  Only users
               who can change the GDM configuration file
               (normally writable only by the root user) can
               actually modify the GDM configuration.  This
               command is useful to cause the GDM to update
               itself to recognize a change made to the GDM
               configuration file by the root user.

               Starting with version 2.13.0.0, all GDM 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

               GDM 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 GDM:

                      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 GDM version
Supported since: 2.2.4.0
Arguments: None
Answers:
  GDM <gdm version>
  ERROR <err number> <english error description>
     200 = Too many messages
     999 = Unknown error