gnome-session - Man Page

gnome-session [OPTION...]

The gnome-session program starts up the GNOME desktop environment​. This command is typically executed by your login manager (either GDM, SDDM, lightdm, or other)​. It will load either your saved session, or it will provide a default session for the user as defined by the system administrator (or the default GNOME installation on your system)​.

The default session is defined in gnome​.session, a ​.desktop-like file that is looked for in $XDG_CONFIG_HOME/gnome-session/sessions, $XDG_CONFIG_DIRS/gnome-session/sessions and $XDG_DATA_DIRS/gnome-session/sessions​.

--session=SESSION

Use the applications defined in SESSION​.session​. If not specified, gnome​.session will be used​.

--debug

Enable debugging code​.

gnome-session uses systemd for the bulk of its service management​. systemd provides the two special targets for desktop integration: graphical-session​.target and graphical-session-pre​.target​. These work across desktop environments, and should be used if possible​. gnome-session provides the following additional GNOME-specific targets:

gnome-session​.target

Generic unit that will be active throughout the session​. Similar to graphical-session​.target​.

gnome-session-pre​.target

Used for tasks that need to be done before session startup​. Similar to graphical-session-pre​.target​.

gnome-session@SESSION​.target

Main unit started for the session​. SESSION is set according to the session that is passed in via --session​.

gnome-session-basic-services​.target

Special unit that lists basic services that are needed by any GNOME session built around gnome-shell​. This allows for convenient reuse by kiosk sessions like the GDM login screen​.

gnome-session-x11-services​.target

Special unit started when X11 services are needed​. Programs will need to use the special GNOME_SETUP_DISPLAY environment variable instead of DISPLAY​.

Note that care must be taken to set appropriate After= rules​. It is also strongly recommended to always do this in combination with BindsTo= or PartOf= on one of the core targets (e​.g​. graphical-session​.target)​.

Units are required to set CollectMode=inactive-or-failed​. In addition, it is strongly recommended to set TimeoutStopSec=5 so that logout will not be delayed indefinitely in case the process does not stop properly​.

Sessions are defined in ​.session files, that are using a ​.desktop-like format, with the following keys in the GNOME Session group:

Name

Name of the session​. This can be localized​.

Kiosk

Kiosk sessions are special single-purpose sessions that are built around starting some specific app​. For instance, a kiosk session may run a full-screen web browser that's locked to a specific page​. In GNOME, we use kiosk sessions for the login screen (where the app is the login screen UI) and the initial-setup first boot experience​. When set to true, gnome-session will make no attempt to autostart any ​.desktop files, and will instead require that the session configures all required functionality via systemd​.

Here is an example of a session definition:

[GNOME Session]
Name=GNOME

The ​.session files are loaded from $XDG_CONFIG_HOME/gnome-session/sessions, $XDG_CONFIG_DIRS/gnome-session/sessions and $XDG_DATA_DIRS/gnome-session/sessions​.

Session definitions don't do anything on their own, and they need to be accompanied by systemd configuration to provide some functionality (i​.e​. launch services)​. The recommended way to do that is by hooking into one of the targets described above​. For instance: when defining a session named foobar, you can create a systemd drop-in file in /etc/systemd/user/gnome-session@foobar​.target​.d/session​.conf and define Requires= and Wants= dependencies to tell systemd what services it needs to start when launching this session​.

      $XDG_CONFIG_HOME/autostart
      $XDG_CONFIG_DIRS/autostart
      /usr/share/gnome/autostart

Applications defined via ​.desktop files in those directories will be started on login​. Note that previous versions of gnome-session would launch services from here, but this is no longer the case​. Services should now be configured via systemd unit files

      $XDG_CONFIG_HOME/gnome-session/sessions
      $XDG_CONFIG_DIRS/gnome-session/sessions
      $XDG_DATA_DIRS/gnome-session/sessions

These directories contain the ​.session files that can be used with the --session option​.

If you find bugs in the gnome-session program, please report these on https://gitlab​.gnome​.org/GNOME/gnome-session/issues​.

gnome-session-quit(1)

gnome-session-quit(1).