When there's trouble, it might be good to understand what happens under the covers to sign a user into a GUI session and get a Unity (or other window manager) to bring up a desktop.


How a desktop user GUI session gets started with Ubuntu 12.04-14.04

Here's the chain of events:

The Ubuntu Linux kernel and upstart

The kernel starts the init process as process number 1. This is upstart for Ubuntu 12.04.

Upstart jobs are in /etc/init/

Man page: man init

Logs: kernel log (dmesg; copied to /var/log/syslog), /var/log/upstart/jobname.log, other logs determined by started jobs.

Source: /etc/init/lightdm.conf

The upstart job executes /usr/sbin/lightdm . We probably can expect this to be converted to a systemd service unit over time.


Man page: man lightdm , Also: Ubuntu Wiki: LightDM



## for PAM:

## for the Xorg X server:

Source: man lightdm and /var/log/lightdm/lightdm.log

lightdm get's started fairly late in the init process; For example, the system dbus must to be already started, the filesystem has to be ready, and the graphics display system must be ready.

lightdm creates an xauthority file and then starts X, starting it on VT 7, the virtual terminal you get if you press Alt+Ctrl+F7. When X is started lightdm signals for the Plymouth splash screen program to quit. It's essential that this happens after all of the tty's (1-6) have started.

Since July 2013 Mir support items have been added to lightdm, but those aren't used by default for desktop systems as of 14.04.

X attempts to use the most advanced drivers possible. It's own drivers are loaded from /usr/lib/xorg/modules/ . Note that there exist both kernel drivers and xorg drivers for many devices, with the xorg drivers almost certainly using the kernel ones. dri and glx are important features, in particular, for advanced high performance graphics. Logs are stored for X in /var/log/Xorg.0.log .

There is communications over the system dbus about this "seat" and possible user names are acquired. lightdm uses X to draw the screen. unity-greeter is used to assist in the process.

As you select the various possible userid's that userid's backgound image is used.

lightdm get's the names of potential window-managers/systems from /usr/share/xsessions/*.desktop.

Account information is acquired via the accountsservice accounts-daemon over dbus.

lightdm and the greeter use PAM to authenticate the user. Once authenticated, PAM will start a gnome-keyring-daemon daemon with the --login option and feed it the user's password so that it can unlock the user's login keyring, if present. See https://live.gnome.org/GnomeKeyring/Pam and man 8 pam_unix for more information. PAM stores log information in /var/log/auth.log and is controlled by /etc/pam.conf (almost empty) and /etc/pam.d/*. In particular, see /etc/pam.d/lightdm and /etc/pam.d/lightdm-autologin.

Once the user is authenticated privileges are dropped and a file is written to ~user/.dmrc describing the session. For example:




The .desktop files from /usr/share/xsessions/*.desktop now determine the rest of the startup sequence.

For example here's the one for Unity:

[Desktop Entry]
Comment=This session logs you into Ubuntu
Exec=gnome-session --session=ubuntu

The /usr/sbin/lightdm-session shell script is run with the arguments gnome-session --session=ubuntu (sic.--'ubuntu', not 'unity')


Logs: ?
Error Logs: ~/.xsession-errors
Started Process Logs: ~/.cache/upstart/*
Source: /usr/sbin/lightdm-session

/usr/sbin/lightdm-session then takes these steps:


  • /etc/profile, $HOME/.profile
  • /etc/xprofile $HOME/.xprofile;
  • loads resources from /etc/X11/Xresources and $HOME/.Xresources, if they exist, loads the keyboard map with setxbmap using the contents of /etc/X11/Xkbmap and $HOME/.Xkbmap;
  • if not using XKB uses xmodmap against any existing /etc/X11/Xmodmap and $HOME/.Xmodmap
  • runs scripts in /etc/X11/xinit/xinitrc.d;
  • runs the Xsession scripts in /etc/X11/Xsession.d/*, using the options in /etc/X11/Xsession.options.

    One of these starts ssh-agent (redundant), another executes $HOME/.xsessionrc. Another starts session-dbus (both ssh-agent and session-dbus as allowed in the above Xsession.options file). This session dbus is useful for communications between processes regarding this single user session.

ssh-agent can hold onto ssh keys for the session if they are ssh-add 'ed some time during the session, but gnome-keyring-daemon does the same thing.

/etc/X11/Xsession.d/50_check_unity_support runs /usr/lib/nux/unity_support_test and if it fails exports LIBGL_ALWAYS_SOFTWARE=1 to the environment so that llvmpipe will be used to software render the desktop.

Starting with Ubunu 13.10: /etc/X11/Xsession.d/00upstart sets variable UPSTART to 1. /etc/X11/Xsession.d/99upstart checks that variable and if set substitutes init --user to the other items set to $STARTUP. Thus user-mode upstart starts those upstart jobs in /usr/share/upstart/sessions. One of those is gnome-session.conf which starts gnome-session.

Unless already done, finally lightdm-session starts a window manager, or for unity, the above starts the gnome-session session manager.

It appears that lightdm-session takes on the traditional role of xsession. Its man page is at http://manpages.ubuntu.com/manpages/precise/man5/Xsession.5.html . lightdm considers it to be a session-wrapper.

gnome-session session manager (Unity and Gnome Shells)

Manpage: http://manpages.ubuntu.com/manpages/precise/en/man1/gnome-session.1.html
Logs: ?

Source: man page

gnome-session is used for Unity, but not for awesome by default, for example. See the above .desktop files.

gnome-session starts the specified program from /usr/share/gnome-session/sessions/ and starts applications from ~/.config/autostart/ and /etc/xdg/autostart.

Here's one example from /etc/xdg/autostart:

$cat /etc/xdg/autostart/nm-applet.desktop
[Desktop Entry]
Comment=Manage your network connections

Another, /etc/xdg/autostart/gnome-keyring-ssh.desktop, starts gnome-keyring-daemon with the --start option, completing the start of that daemon process and storing important information about it in the environment for potential use by ssh.

From a ps aux list it appears that gnome-session starts window managers with dbus-launch.

Window Managers

Awesome Window Manager

Man page: http://manpages.ubuntu.com/manpages/precise/en/man1/awesome.1.html
Logs: ?

Source: man page, config file examination

Here's the awesome.desktop file in /usr/share/xsessions/ used by lightdm-session:

[Desktop Entry] 
Comment=Highly configurable framework window manager

As you can see, the entry simply causes the awesome window manager to be executed. It reads its own configuration files, including /etc/xdg/awesome/rc.lua from the awesome package. It can be configured with $HOME/.config/awesome/rc.lua.


Source: config file examination

Here's the ubuntu.desktop file in /usr/share/xsessions/ :

[Desktop Entry]
Comment=This session logs you into Ubuntu
Exec=gnome-session --session=ubuntu

This starts the gnome session described in /usr/share/gnome-session/sessions/ubuntu.session

Here is that file:

[GNOME Session]

The IsRunnableHelper program run by gnome-session in 12.04 determines whether unity can be run or whether ubuntu-2d will run. If it makes a mistake and says unity can run and it cannot, there's trouble. Choose ubuntu-2d manually in lightdm if that happens to you. While it returns a return code, we can see what it is doing by running it with the -p option.

$ /usr/lib/nux/unity_support_test -p
OpenGL vendor string:   X.Org R300 Project
OpenGL renderer string: Gallium 0.4 on ATI RS690
OpenGL version string:  2.1 Mesa 8.0.2

Not software rendered:    yes
Not blacklisted:          yes
GLX fbconfig:             yes
GLX texture from pixmap:  yes
GL npot or rect textures: yes
GL vertex program:        yes
GL fragment program:      yes
GL vertex buffer object:  yes
GL framebuffer object:    yes
GL version is 1.4+:       yes

Unity 3D supported:       yes

For 12.10 and later unsupported hardware uses llvmpipe software to render what the hardware can't. Its configuration file is simpler than the above. See above for how it is enabled.

We can see from the above files that gnome-session must start the settings daemon, and start compiz for purposes of running a window manager and any panels.


Man page: http://manpages.ubuntu.com/manpages/precise/en/man1/compiz.1.html
Logs: ?
Source: http://en.wikipedia.org/wiki/Compiz, file system examination

Once compiz is started, it runs various plugins. Before 12.10 gnome-settings are used to define these. They can be changed with ccsm (compiz config settings manager) or with gconf-editor. The plugin settings are stored in apps/compiz-1/general/screen0/options under active_plugins. Duplicates have caused me to have segfaults with compiz. These are stored in the user's home directory in the ~/.gconf/ directory organized as above. The actual values are stored in %gconf.xml files there.

Since 12.10 these plugins are stored in binary in your ~/.config/dconf/user file. The dconf, or gsettings method of storing settings is newer. You can see all of these settings with dconf dump /org/gnome/.

Unityshell is one of these plugins. It uses the nux project as an embeded toolkit. Images are drawn on textures in 3 dimensional space with specified transparency values. These are processed by compiz and sent to either llvm or to advanced graphics drivers to have the graphics engines on the system's computer graphic hardware composite and render them. Generally, this is as opposed to rendering images directly to a framebuffer as was done more traditionally. This complicated chain of events is what requires more advanced drivers, and sometimes prompts the use of proprietary graphics drivers in Ubuntu.

  • How can I tell if my system is running Awesome, Unity or compiz? – James Dec 6 '13 at 10:35
  • @james You can probably check for compiz or awesome in the process list. You get that with a command such as ps aux . You can also check the file ~/.dmrc for the Session parameter cat ~/.dmrc. See above. The Session=ubuntu means you are using compiz and unity together (and that's the default. – John S Gruber Jan 13 '14 at 21:40
  • Exceptional answer, allowing to get a good grasp on the process without prerequisite knowledge ! Following your description, I tried to replicate the xsessions/ubuntu.desktopin another file and was hoping to end up with the same behavior, but without any success (more details in this question). Is there something special about the default ubuntu.desktop xsession ? – Ad N Mar 16 '15 at 9:55
  • Indeed, would +10 if I could. Better than the doc... – Ring Ø Oct 21 '17 at 4:53

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.