1. Introduction 1.1. Project/Component Working Name: ConsoleKit 1.2. Name of Document Author/Supplier: Brian Cameron 1.3. Date of This Document: 08/11/2009 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The PAC or CPT you expect to review your project: Solaris PAC 1.4.2. The ARC(s) you expect to review your project: LSARC 1.4.3. The Director/VP who is "Sponsoring" this project: Robert O'Dea 1.4.4. The name of your business unit: Software - OPG 1.5. Email Aliases: 1.5.1. Responsible Manager: leo.binchy@sun.com 1.5.2. Responsible Engineer: brian.cameron@sun.com 1.5.3 Marketing Manager: dan.robert@sun.com 1.5.4. Interest List: desktop-discuss@opensolaris.org 2. Project Summary 2.1. Project Description: ConsoleKit is a FreeDesktop framework for defining and tracking users, login sessions and seats. ConsoleKit has two main purposes: - To maintain a database of information about each running session which the display manager (GDM) uses. The old GDM keeps track of this information internally, but new versions of GDM (2.21 and later) use ConsoleKit. - To support switching sessions and session migration when using mechanisms such as VT. Note that Sun Ray uses its own separate session migration techniques. While there may be some value in Sun Ray making use of ConsoleKit in the future to avoid replicating functionality, there are no immediate plans for Sun Ray to use ConsoleKit directly for this. Today, Solaris does not support graphical VT sessions. However, the virtual console team is currently targeting build 124 to add this feature. Refer to PSARC 2006/591 Virtual Console. VT support is not needed to use ConsoleKit, but will support it as soon as it is available. 4. Technical Description: 4.1. Details: ConsoleKit maintains a database of which users are logged into the system. ConsoleKit groups sessions by seats which represent a set of hardware (usually a keyboard and mouse). Other process communicate with ConsoleKit via D-Bus. One session leader process is responsible for asking ConsoleKit to open a new session. In the typical case, the session leader would be a ConsoleKit enabled display manager, such as GDM. This leader makes a connection to the D-Bus system bus and asks ConsoleKit to open a session when needed. If the operation succeeds, ConsoleKit will return a cookie to the session leader. The session leader should store this variable in the environment as XDG_SESSION_COOKIE so that it may be shared with its child processes. The environment variable contains the UUID used to tie processes to a session. At this point the session will be registered with ConsoleKit and a particular set of information about the session will be stored along with it. The Session will remain open until the Session Leader disconnects from the D-Bus system bus. The session will be removed from its seat, and deregistered. Various other programs need to know information about running user sessions, such as the Fast User Switch Applet and other mechanisms for switching the console to use a different VT display. Such programs make use of ConsoleKit interfaces to determine if user switching is supported and to manage the switching of different sessions on the same seat. On some Linux systems, the pam_ck_connector is used to ensure that non-graphical logins (e.g. telnet, ssh, etc.) are registered with ConsoleKit. Thus ConsoleKit can be used as a utmp/wtmp replacement since it stores a superset of the information as in the utmp/wtmp database. This PAM module will be delivered in the SUNWconsolekit-pam package, but it will not be referenced in the default /etc/pam.conf(4) file. This way it is available if any users decide to make use of it. ConsoleKit source code contains the programs /usr/sbin/ck-log-system-start, /usr/sbin/ck-log-system-restart, and /usr/sbin/ck-log-system-stop. These are intended to be helper tools to log system start, restart, and stop events. These are intended to make ConsoleKit more like utmp/wtmp which also logs these events. Since there are no plans to support ConsoleKit as a utmp/wtmp replacement, these programs are not included with the Solaris ConsoleKit packages. The ConsoleKit database is stored in /var/run/ConsoleKit/database. It stores information about active Seats, Sessions, and the current SessionLeader. The following is an example of what this file contains. Comments (lines beginning with "#" are comments added to explain the purpose of each line: Note that the XDG_SESSION_COOKIE variable is only meaningful to help manage session switching and migration, which currently only works with graphical VT sessions running on the console. Although ConsoleKit will assign the variable for all sessions, it is ignored if the session does not support migration via ConsoleKit. Note Sun Ray uses its own mechanisms for user switching, and is not affected by ConsoleKit. Likewise, other parts of the ConsoleKit framework are designed to only be useful in environments that support VT switching. For example, the /usr/lib/ck-get-x11-server-pid program will not work if the X server is running in a different zone/label as the client, as in a Trusted Extensions system. However, this is not a problem since this script is only used when supporting VT switching. 4.1.1 Detail About ConsoleKit Database # Seat configuration section. [Seat /org/freedesktop/ConsoleKit/Seat1] # Kind value=0 indicates a static seat, value=1 indicates a dynamic # seat. kind=0 # Sessions running on the display. sessions=/org/freedesktop/ConsoleKit/SessionSeat1Local # Devices associated with the display. Currently not used. devices= # Active session on the display. active_session=/org/freedesktop/ConsoleKit/SessionSeat1Local # Session configuration section. [Session /org/freedesktop/ConsoleKit/SessionSeat1Local] # UID of user running the session. uid=50 # Seat associated with the session seat=/org/freedesktop/ConsoleKit/Seat1 # Session cookie value. Note XDG_SESSION_COOKIE environment variable. cookie=4008fb789ce5f1a7f346407e4a669cfe-1249973209.172145-1566549659 # Session type. type=LoginWindow # Device associated with session (if any). display_device=/dev/console # Device associated with Xserver running session (if any). x11_display_device=/dev/console # Display value associated with session (if any). x11_display=:0 # Remote hostname if a remote connection, e.g. XDMCP. remote_host_name= # Boolean. Set to "true" if the session is active, "false otherwise" # For example, useful to keep track of which VT session is the active # one. is_active=false # Boolean. Set to "true" if a local session, "false" if remote. is_local=true # Timestamp of when the session started. creation_time=2009-08-11T06:46:42.941134Z # Session leader configuration section. [SessionLeader /org/freedesktop/ConsoleKit/SessionSeat1Local] # Session associated with the leader. session=/org/freedesktop/ConsoleKit/SessionSeat1Local # UID and PID of session leader process uid=0 pid=24768 # Session leader cookie value. cookie=4008fb789ce5f1a7f346407e4a669cfe-1249973209.172145-1566549659 # Session leader service name service_name=:1.203 4.1.2 Detail About ConsoleKit Program And Library Interfaces + /usr/sbin/console-kit-daemon [--debug] [--no-daemon] [--timed-exit] The main consoleKit daemon. Supports --debug, --no-daemon, and --timed-exit arguments for debugging purposes. + /usr/bin/ck-history [--frequent] [--last] [--last-compat] [--log] [--seat=SEAT] [--session-type=TYPE] [--user=USER] A program that shows historical information about which users have logged in most recently (--last) or most frequently (--frequent). A 'last' compatible listing of last logged in users can be specified with the --last-compat argument. The entire log can be viewed with the --log argument. Users can specify to show entries for a specific seat, session type, or user via the --seat, --session-type, and --user arguments. This is used in GDM when showing the face browser. When GDM is configured to use the face browser, users who have logged in most frequently are displayed first. + /usr/bin/ck-launch-session COMMAND A program used for starting a command in its own ConsoleKit session. This would be useful if a user wanted to start their own session via a startx script and have it registered with ConsoleKit, for example. + /usr/bin/ck-list-sessions [--all] [--format=VAR1,VAR2...] Program that displays information from the ConsoleKit database about open sessions or all exsiting (--all) sessions on the system. It returns information about each ConsoleKit session. Users can specify what properties to show via --format arguments. Example 1: output for a login single session without --format: SessionSeat1Local: unix-user = '50' realname = 'GDM Reserved UID' seat = 'Seat1' session-type = 'LoginWindow' display-type = 'Local' open = 'TRUE' active = 'TRUE' x11-display = ':0' x11-display-device = '/dev/console' display-device = '/dev/console' remote-host-name = '' is-local = 'TRUE' on-since = '2009-08-11T06:46:42.941134Z' login-session-id = '' idle-since-hint = '' Example 2: output for a login single session with argument "--format=session-id,unix-user,display-type" SessionSeat1Local 50 Local + /usr/bin/ck-seat-tool [--add --session-type=SESSION_TYPE --display-type=DISPLAY_TYPE [--seat-id=SEAT_ID] [variables...] | --delete --session-id=SESSION_ID] This program tells ConsoleKit to add or delete a session on a given parameters. This interface will be used by Sun Ray for starting and stopping sessions on Sun Ray devices, but could also be used for dynamically managing other kinds of displays. To use ck-seat-tool, it must be run as the same user which is running the main ConsoleKit daemon, which is normally root. Otherwise the request is ignored. Regarding how the --seat-id argument works: + If --seat-id=SEAT_ID is given and this seat is existing, a new session will be append on that seat. + If --seat-id=SEAT_ID is given but this seat is not existing, a new seat with given seat id created, and a new session append on that seat. + If --seat-id=SEAT_ID is not given, a new seat with generated seat id (Seat#) will be created, and a new session append on that seat. Currently this program is added by a Solaris-specific patch to support the gdmdynamic program, needed for backwards compatibility. The Sun GNOME team is working with the external community to upstream this feature. + /usr/lib/ck-collect-session-info --uid UID --pid PID This program is passed the UID and PID of a process, and it returns the following information from the ConsoleKit database about that process. This is useful for determining which Xserver is associated with a given process. Example output for a process running in a session: unix-user = 100 x11-display = :0.0 x11-display-device = /dev/console display-device = /dev/pts/1 is-local = true This program is a private interface used by the console-kit-daemon when opening a session. + /usr/lib/ck-get-x11-display-device [--display=DISPLAY] Returns the display device associated with an Xserver. GDM uses this program to determine the TTY value associated with an Xserver process, and this value is passed into PAM_TTY, logindevperm, and the audit interfaces. If no --display argument is provided, the current $DISPLAY environment value is used. + /usr/lib/ck-get-x11-server-pid Returns the PID of the Xserver process running on the current $DISPLAY environment variable. + /usr/lib/libck-connector.so Library used by GDM and other programs which access ConsoleKit interfaces. 4.1.3 TTY Settings And Use Of proc Interfaces ConsoleKit keeps track of the device associated with the Xserver. The display manager, such as GDM, will use this value when calling logindevperm, when setting PAM_TTY, and when interacting with Sun audit interfaces. This device is called the x11-display-device by ConsoleKit. When using graphical VT displays, the x11-display-device device is named "/dev/vt/#" where "#" is the number of the VT display. On Solaris, "attached" non-console displays use the value "/dev/dtlocal" and remote displays use the value "/dev/dtremote". The "/dev/dtlocal" and "/dev/dtremote" are considered pseudo-devices and are symlinks to /dev/null. It is necessary to set up the symlinks before they are used by the display manager. When VT support is not enabled or available, then the value "/dev/console" is used for the main console display. ConsoleKit is responsible for making sure that the value is set properly in all these situations. Note that the ConsoleKit ck-collect-session-info program is used privately by ConsoleKit to access information about a running session including the x11-display-device. It makes use of the ck-get-x11-server-pid program to access the x11-display-device value. GDM uses the ck-get-x11-display-device application to get the x11-display-device value. When a display is running via graphical VT, ConsoleKit uses the following mechanism to get the TTY value. This mechanism works on other operating systems, such as Linux, and also works on Solaris when VT is being used. When VT is used, these programs make use of proc interfaces to collect some of this information, as follows: The ConsoleKit ck-get-x11-display-device, ck-get-x11-server-pid, and ck-collect-session-info programs call XOpenDisplay on a given $DISPLAY, and then calls ConnectionNumber to get the socket associated with that display. getpeerucred is used to get the UID and PID of the process. The ck-get-x11-display-device and ck-collect-session-info programs then open /proc//psinfo on the Xserver process in order to access environment values associated with that process. The tty_text value from the psinfo structure is then used to determine the TTY device associated with the Xserver. These interfaces are highlighted because this is a somewhat roundabout way to get the TTY value associated with a given display. That said, this mechanism works well when VT is enabled in the Xserver. Note that the intent of ConsoleKit is that the daemon should be able to determine this information without needing to be informed by the display manager. Obviously, when VT is not used, the above mechanism does not work, so ConsoleKit will heuristically set the value in the non-VT case depending on whether the display is the console display, a local non-console display, or a remote display. 4.1.4 Script Directories ConsoleKit provides two directories which may contain scripts that get run when a ConsoleKit session starts. By default these directories are empty on Solaris. - /usr/lib/ConsoleKit/run-session.d - For scripts shipped by the distro. - /etc/ConsoleKit/run-session.d - For scripts installed by the system administrator. 4.1.5 Environment Variables ConsoleKit makes use of the following environment variables: XDG_SESSION_COOKIE - Environment variable that ConsoleKit provides to the session leader. The session leader is expected to ensure this is set for the session process started. It contains a UUID used to tie the processes to the session. This is used to support user switching on displays that support it (currently only graphical VT displays on the console). The following environment variables are set when running scripts in the script directories described in section 4.1.4. This way the scripts can support conditional logic based on the settings of the session. CK_SESSION_SEAT_ID - Seat ID associated with the session. CK_SESSION_USER_UID - UID associated with the session. CK_SESSION_DISPLAY_DEVICE - The device associated with the CK_SESSION_X11_DISPLAY_DEVICE - The device associated with the Xserver. CK_SESSION_X11_DISPLAY - Display value, such as ":0" CK_SESSION_REMOTE_HOST_NAME - Set to the remote host name if the session is not local (e.g. XDMCP). CK_SESSION_IS_ACTIVE - Set to "true" or "false". Is "true" if the session is active. For example, VT displays not running on the display would be "false" CK_SESSION_IS_LOCAL - Set to "true" or "false". Is "true" if the session is local. Is "false" if the session is remote (e.g. XDMCP). CK_SESSION_IS_DYNAMIC - Set to "true" or "false". Is "true" if the session was started via ck-dynamic, "false" otherwise. 4.1.6 Stop/Restart Scripts ConsoleKit manages stopping and restarting the system. On Solaris, when the display manager informs ConsoleKit that such an action is requested, the chkauthattr function is called to see if the calling user has RBAC permissions for the "solaris.system.shutdown" key. If yes, then the /usr/lib/ConsoleKit/scripts/ck-system-restart script is run if a restart action was requested. If a shutdown action was requested, then the /usr/lib/ConsoleKit/scripts/ck-system-stop script is run. On Solaris, the ck-system-stop script runs "/sbin/init 5" and the ck-system-restart script runs "/sbin/init 6". 4.1.7. D-Bus Interfaces The ConsoleKit D-Bus interfaces are documented here: http://people.freedesktop.org/~mccann/doc/ConsoleKit/ConsoleKit.html A copy of the above interface documentation is included with the case materials. 4.1.8 Usage of /var/run The /var/run interfaces are not installed with the ConsoleKit packages. They are created at runtime when the /usr/sbin/console-kit-daemon starts. 4.1.9 SMF integration ConsoleKit includes SMF integration files to start and stop the /usr/sbin/console-kit-daemon program as a service. 4.1.10 Detail About Seat configuration file ConsoleKit load static seat configuration files from /etc/ConsoleKit/seats.d. One .seat file stands for one static configured seat to start. By default, there is one .seat file available: 00-primary.seat. Administrators could put customized .seat files. Following are explanation for each key of 00-primary.seat # Seat Entry section [Seat Entry] # Version information Version=1.0 # Name of this seat Name=Primary seat # Description of this seat Description=start one static local display at :0 # Indicate whether to create this seat or not. If it is set true, # then CK will not create this seat. Default value is false. Hidden=false # Indicate input/output devices including keyboard-pointer-video # card-monitor-sound-usb devices, # This key is not used now, it might need be divided into several # keys in the future: # Pointer= # Monitor= # VideoCard= # Monitor= # UsbHub= Devices= # List of sessions to start on the seat, separated by ';' # Each session is defined in sessions.d/ Sessions=Local; 4.1.11 Detail About Session configuration file ConsoleKit load session configuration files from /etc/ConsoleKit/sessions.d. By default, there are four .session files available: Local.session, LocalVNC.session, Headless.session and Remote.session. Administrators could put customized .session files. Following are explanation for each key of Local.session # Session Entry section [Session Entry] # Indicate whether to create this session or not. If it is set true, # then CK will not create this session. Default value is false. Hidden=false # Name of this session Name=Local # Type of this session. Default is LoginWindow. Type=LoginWindow # Description of this session Description=Local Login Screen # Display Template of this session, it is defined in displays.d/ DisplayTemplate=Local # Session variables section # They are used to override corresponding parameters of Exec defined in # displays.d/Loal.display [Local] # Override $diplay to :0 display=:0 # Override $vt to /dev/vt/7 # Again, graphical VT sessions will be added in build 124. vt=/dev/vt/7 4.1.12 Detail About Display Template configuration file ConsoleKit load display template configuration files from /etc/ConsoleKit/displays.d. By default, there are five .display files available: Local.display, LocalVNC.display, Headless.display Remote.display and Sunray.display. Sunray.display should be removed when SRSS ship this file itself in the future. Administrators could put customized .display files. Following are explanation for each key of Local.display # Display Entry section [Display] # Display type Type=X11 # X11 section [X11] # Command to start X11. # # Parameters with prefix dollar ('$') would be overridden at run time. # ConsoleKit will override them either by variables defined in # session configuration files, or by variables passed to # "ck-seat-tool --add". # # If any parameter is not overridden, then Display Manager will # decide the value. # # For example, $display and $vt are not given, GDM will choose next # available display number and VT, then start Xorg process. Exec=/usr/X11/bin/Xorg $display -br -verbose \ -auth $auth -nolisten tcp $vt 4.1.13 Detail About How to start multiple sessions on single seat For example, users want to start two local displays, one is :0 on vt7 and another one is :1 on vt8. Refer to 4.1.10, 4.1.11 and 4.1.12, users can edit 00-primary.seat file as following: [Seat Entry] Version=1.0 Name=Primary seat Description=start two static local displays, one is :0 on vt7 \ and another one is :1 on vt8 Hidden=false Devices= Sessions=Local;Local2; Besides original Local.session, we put another similar Local2.session under /etc/ConsoleKit/sessions.d/ [Session Entry] Name=Local Type=LoginWindow Description=Local Login Screen DisplayTemplate=Local [Local] display=:1 vt=/dev/vt/8 Alternatively, users can do with 'ck-seat-tool' at run time without modifying configuration files. $ck-seat-tool --add --session-type=LoginWindow \ --display-type=Local --seat-id=Seat1 \ display=:1,vt=/dev/vt/8 4.1.14 Detail About How to start multiple seats For example, users want to start two seats, one seat start local session :0 on vt7 and another seat start VNC session :64. Refer to 4.1.10, 4.1.11 and 4.1.12, users can put another file 01-vnc.seat under /etc/ConsoleKit/seats.d/ as following: [Seat Entry] Version=1.0 Name=VNC seat Description=start one VNC display on :64 Hidden=false Devices= Sessions=LocalVNC; The LocalVNC.session is as following: [Session Entry] Name=LocalVNC Type=LoginWindow Description=Connect to local VNC server running on same machine DisplayTemplate=LocalVNC [LocalVNC] display=:64 The LocalVNC.display is as following: [Display] Type=X11 [X11] Exec=/usr/X11/bin/Xvnc $display -auth $auth -query localhost Alternatively, users can do with 'ck-seat-tool' at run time without modifying configuration files. $ck-seat-tool --add --session-type=LoginWindow \ --display-type=LocalVNC display=:64 4.2. Interfaces: Exported Interfaces Stability Comments --------------------------------------- ----------- ------------- SUNWconsolekit Uncommitted Package name. SUNWconsolekit-devel Uncommitted Package name. SUNWconsolekit-root Uncommitted Package name. SUNWconsolekit-pam Uncommitted Package name. /usr/lib/pkgconfig/ck-connector.pc Uncommitted pkg-config file. svc:/system/consolekit:default Uncommitted ConsoleKit FMRI /var/svc/manifest/system/consolekit.xml Project SMF manifest Private integration /usr/bin/ck-history Volatile See 4.1.2. /usr/bin/ck-launch-session Volatile See 4.1.2. /usr/bin/ck-list-sessions Volatile See 4.1.2. /usr/sbin/ck-seat-tool Volatile See 4.1.2. /usr/sbin/console-kit-daemon Volatile See 4.1.2. /usr/lib/ck-collect-session-info Private See 4.1.2. /usr/lib/ck-get-x11-display-device Volatile See 4.1.2. /usr/lib/ck-get-x11-server-pid Private See 4.1.2. /usr/lib/ConsoleKit/scripts/ck-system-restart Private See 4.1.6. /usr/lib/ConsoleKit/scripts/ck-system-stop Private See 4.1.6. /usr/lib/libck-connector.so Volatile ConsoleKit library. /usr/include/ConsoleKit Volatile Header files. /usr/lib/ConsoleKit/run-session.d Volatile See 4.1.4. /etc/ConsoleKit/run-session.d Volatile See 4.1.4. /etc/ConsoleKit/seats.d/ Volatile See 4.1.10. /etc/ConsoleKit/seats.d/00-primary.seat Volatile See 4.1.10. /etc/ConsoleKit/sessions.d/ Volatile See 4.1.11. /etc/ConsoleKit/sessions.d/Local.session Volatile See 4.1.11. /etc/ConsoleKit/sessions.d/LocalVNC.session Volatile See 4.1.11. /etc/ConsoleKit/sessions.d/Headless.session Volatile See 4.1.11. /etc/ConsoleKit/sessions.d/Remote.session Volatile See 4.1.11. /etc/ConsoleKit/displays.d/ Volatile See 4.1.12. /etc/ConsoleKit/displays.d/Local.display Volatile See 4.1.12. /etc/ConsoleKit/displays.d/LocalVNC.display Volatile See 4.1.12. /etc/ConsoleKit/displays.d/Headless.display Volatile See 4.1.12. /etc/ConsoleKit/displays.d/RemoteMachine.display Volatile See 4.1.12. /etc/ConsoleKit/displays.d/Sunray.display Volatile See 4.1.12. /etc/dbus-1/system.d/ConsoleKit.conf Volatile D-Bus Integration. [1] /var/log/ConsoleKit/history Volatile History database. /var/run/ConsoleKit/database Volatile Session database. See 4.1.8. /var/run/ConsoleKit/pid Volatile ConsoleKit daemon PID. See 4.1.8. /usr/share/dbus-1/interfaces/*ConsoleKit* Volatile D-Bus integration. /usr/share/dbus-1/system-services/*ConsoleKit* Volatile D-Bus integration. XDG_SESSION_COOKIE Volatile See 4.1.5. CK_SESSION_SEAT_ID Volatile See 4.1.5. CK_SESSION_USER_UID Volatile See 4.1.5. CK_SESSION_DISPLAY_DEVICE Volatile See 4.1.5. CK_SESSION_X11_DISPLAY_DEVICE Volatile See 4.1.5. CK_SESSION_X11_DISPLAY Volatile See 4.1.5. CK_SESSION_REMOTE_HOST_NAME Volatile See 4.1.5. CK_SESSION_IS_ACTIVE Volatile See 4.1.5. CK_SESSION_IS_LOCAL Volatile See 4.1.5. CK_SESSION_IS_DYNAMIC Volatile See 4.1.5. Imported Interfaces Stability Comments ----------------------- --------------- ----------------------- GObject & GThread (GLib) Committed LSARC 2006/202 D-Bus & dbus-glib Volatile LSARC 2006/368 /proc & /proc/pid Public PSARC 1992/073 chkauthattr Stable PSARC 1997/332 X11 Standard PSARC 1998/299 Virtual Console Committed PSARC 2006/591 /sbin/init ? 4.3. Doc Impact: Man page is needed. 4.4. Packaging & Delivery: SUNWconsolekit, SUNWconsolekit-root, SUNWconsolekit-devel, SUNWconsolekit-pam - packages for ConsoleKit. 4.5. Dependencies: For VT features to work, the following case will need to integrate: PSARC 2006/591 Virtual Console 4.6. L10N Impact: The Desktop team and the G11N team are working together to evaluate and provide I18N/L10N support. 4.7. Security Impact: ConsoleKit makes use of RBAC so that the Shutdown and Reboot options are only available if the requesting user has solaris.system.shutdown authority. The /var/run/ConsoleKit/database file contains all information about each user's session. This is owned by root:root with 600 permissions to prevent snooping or tampering. 5. Reference Documents: [1] The ./ConsoleKit.conf file is also included with the case materials for reference. The ConsoleKit documentation from the ConsoleKit website is also included with the case materials as the file ./ConsoleKit.html ConsoleKit Website: http://www.freedesktop.org/wiki/Software/ConsoleKit ConsoleKit Documentation: http://people.freedesktop.org/~mccann/doc/ConsoleKit/ConsoleKit.html