Commit 92bd660d authored by Benjamin Berg's avatar Benjamin Berg Committed by Benjamin Berg

doc: Update gnome-session manpage for systemd related changes

This adds information about session configuration through drop-ins and
mentiones what will need to be done to move from XDG autostart files to
a purely systemd based startup (i.e. the various ExecCondition= tests).
parent b9f6fa5d
...@@ -161,17 +161,32 @@ RequiredComponents=gnome-shell;gnome-settings-daemon; ...@@ -161,17 +161,32 @@ RequiredComponents=gnome-shell;gnome-settings-daemon;
</programlisting> </programlisting>
<para> <para>
In <command>systemd</command> managed sessions the RequiredComponents may be provided by In <command>systemd</command> managed sessions, the components should instead
systemd units instead. In this case the corresponding <filename>.desktop</filename> file needs be defined by installing a drop-in systemd configuration (since GNOME 3.38) for
to contain <option>X-GNOME-HiddenUnderSystemd=true</option>. <command>gnome-session</command> will <filename>gnome-session@SESSION.target</filename>.
ignore these components and rely on <command>systemd</command> to manage them appropriately, Currently, the <varname>RequiredComponents</varname> list will still be
see the systemd section for more information on how this works. processed and <filename>.desktop</filename> files need to have
<varname>X-GNOME-HiddenUnderSystemd=true</varname> set so that
<command>gnome-session</command> will ignore them.
It strongly recommended to set <varname>X-systemd-skip=true</varname> to be more future proof.
</para> </para>
<para> <para>
The <filename>.session</filename> files are looked for in It is expected that <command>gnome-session</command> will stop allowing the use
<filename>$XDG_CONFIG_HOME/gnome-session/sessions</filename>, of autostart files to launch services within a systemd managed session.
<filename>$XDG_CONFIG_DIRS/gnome-session/sessions</filename> and At that point, XDG autostart files will only be usable to start applications
<filename>$XDG_DATA_DIRS/gnome-session/sessions</filename>. after the desktop is ready.
For this purpose, systemd has an XDG autostart generator that supports
a sufficient subset of features.
Please consider creating a <filename>.service</filename> file for any XDG
autostart file which needs <varname>X-GNOME-Autostart-Phase=</varname>.
To support <varname>OnlyShowIn=</varname> and <varname>NotShowIn=</varname> you
can make use of <command>systemd-xdg-autostart-condition</command> inside an
<varname>ExecCondition=</varname> which will be available in systemd v245.
<command>gnome-session</command> provides a similar tool which mirrors
<varname>AutostartCondition=</varname> which is called
<command>gnome-systemd-autostart-condition</command> and will eventually support
starting/stopping services on demand (this features is not yet enabled as of
GNOME 3.38).
</para> </para>
</refsect1> </refsect1>
...@@ -184,10 +199,14 @@ set in their <filename>.desktop</filename> file will be ignored by <command>gnom ...@@ -184,10 +199,14 @@ set in their <filename>.desktop</filename> file will be ignored by <command>gnom
It instead relies on the fact that these components are managed by systemd. It instead relies on the fact that these components are managed by systemd.
</para> </para>
<para> <para>
As of GNOME 3.34 the systemd support is new and the customizing the As of GNOME 3.38 the systemd support must be configured by providing drop-in
configuration is not yet easily possible. With GNOME 3.34 it may be best to use configurations for <filename>gnome-session@SESSION.target</filename>.
<option>--builtin</option> if session customizations are required. This is due to the way If such a configuration is not provided by a session, then it must force the
that GNOME currently defines the components that will be started on each session type. legacy login mode using the <option>--builtin</option> option.
Please see existing files and above for some more information on how to
define the session definition.
Below is more information on how to integrate new services properly with the
GNOME startup.
</para> </para>
<para> <para>
<command>systemd</command> provides the two special targets <filename>graphical-session.target</filename> <command>systemd</command> provides the two special targets <filename>graphical-session.target</filename>
...@@ -240,9 +259,12 @@ It is also strongly recommended to always do this in combination with <varname>B ...@@ -240,9 +259,12 @@ It is also strongly recommended to always do this in combination with <varname>B
or <varname>PartOf=</varname> on one of the core targets (e.g. <filename>graphical-session.target</filename>). or <varname>PartOf=</varname> on one of the core targets (e.g. <filename>graphical-session.target</filename>).
</para> </para>
<para> <para>
Units are required to set <varname>CollectMode=inactive-or-failed</varname>. It is strongly recommended that all units set <varname>TimeoutStopSec=5</varname>
In addition, it is strongly recommended to set <varname>TimeoutStopSec=5</varname> so that logout will not be delayed indefinitely in case the process does not stop
so that logout will not be delayed indefinitely in case the process does not stop properly. properly.
If this is not done, the user will likely need to wait for 90 seconds
before being able to log in again (and could see a black screen during this
time).
</para> </para>
</refsect1> </refsect1>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment