170 lines
6.6 KiB
Groff
170 lines
6.6 KiB
Groff
.\"
|
|
.\" gnome-session manual page.
|
|
.\" (C) 2000 Miguel de Icaza (miguel@helixcode.com)
|
|
.\" (C) 2009-2010 Vincent Untz (vuntz@gnome.org)
|
|
.\" (C) 2019 Benjamin Berg (bberg@redhat.com)
|
|
.\" (C) 2020 Sebastian Geiger (sbastig@gmx.net)
|
|
.\"
|
|
.TH GNOME-SESSION 1 "May 2020" "GNOME"
|
|
.SH NAME
|
|
gnome-session \- Start the GNOME desktop environment
|
|
.SH SYNOPSIS
|
|
.B gnome-session [\-a|\-\-autostart=DIR] [\-\-session=SESSION] [\-\-failsafe|\-f] [\-\-debug] [\-\-whale]
|
|
.SH DESCRIPTION
|
|
The \fIgnome-session\fP program starts up the GNOME desktop
|
|
environment. This command is typically executed by your login manager
|
|
(either gdm, xdm, or from your X startup scripts). 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). Note that \fIgnome-session\fP is a wrapper
|
|
script for \fIgnome-session-binary\fP.
|
|
.PP
|
|
The default session is defined in \fBgnome.session\fP, a .desktop-like
|
|
file that is looked for in
|
|
\fB$XDG_CONFIG_HOME/gnome-session/sessions\fP,
|
|
\fB$XDG_CONFIG_DIRS/gnome-session/sessions\fP and
|
|
\fB$XDG_DATA_DIRS/gnome-session/sessions\fP.
|
|
.PP
|
|
When saving a session, \fIgnome-session\fP saves the currently running
|
|
applications in the \fB$XDG_CONFIG_HOME/gnome-session/saved-session\fP
|
|
directory. Saving sessions is only supported with the legacy non-systemd
|
|
startup method.
|
|
.PP
|
|
\fIgnome-session\fP is an X11R6 session manager. It can manage GNOME
|
|
applications as well as any X11R6 SM compliant application.
|
|
.SH OPTIONS
|
|
The following options are supported:
|
|
.TP
|
|
.I "--autostart=DIR"
|
|
The directory \fBDIR\fP to be searched for autostart .desktop files. This option can be used multiple times.
|
|
When this option is present, then default autostart directories will not be searched.
|
|
.TP
|
|
.I "--session=SESSION"
|
|
Use the applications defined in \fBSESSION.session\fP. If not specified,
|
|
\fBgnome.session\fP will be used.
|
|
.TP
|
|
.I "--failsafe"
|
|
Run in fail-safe mode. User-specified applications will not be started.
|
|
.TP
|
|
.I "--debug"
|
|
Enable debugging code.
|
|
.TP
|
|
.I "--whale"
|
|
Show the fail whale in a dialog for debugging it.
|
|
.SH SESSION DEFINITION
|
|
Sessions are defined in \fB.session\fP files, that are using a .desktop-like
|
|
format, with the following keys in the \fBGNOME Session\fP group:
|
|
.TP
|
|
.I Name
|
|
Name of the session. This can be localized.
|
|
.TP
|
|
.I RequiredComponents
|
|
List of component identifiers (desktop files) that are required by the session. The required components will always run in the session.
|
|
.PP
|
|
Here is an example of a session definition:
|
|
.PP
|
|
.in +4n
|
|
.nf
|
|
[GNOME Session]
|
|
Name=GNOME
|
|
RequiredComponents=gnome-shell;gnome-settings-daemon;
|
|
.in
|
|
.fi
|
|
.PP
|
|
In \fBsystemd\fP managed sessions the RequiredComponents may be provided by
|
|
systemd units instead. In this case the corresponding \fB.desktop\fP file needs
|
|
to contain \fBX-GNOME-HiddenUnderSystemd=true\fP. \fIgnome-session\fP will
|
|
ignore these components and rely on \fIsystemd\fP to manage them appropriately,
|
|
see the \fIsystemd\fP for more information on how this works.
|
|
.PP
|
|
The \fB.session\fP files are looked for in
|
|
\fB$XDG_CONFIG_HOME/gnome-session/sessions\fP,
|
|
\fB$XDG_CONFIG_DIRS/gnome-session/sessions\fP and
|
|
\fB$XDG_DATA_DIRS/gnome-session/sessions\fP.
|
|
.SH systemd
|
|
\fIgnome-session\fP can pass much of the session management over to systemd.
|
|
In this case, startup components that have \fBX-GNOME-HiddenUnderSystemd=true\fP
|
|
set in their \fB.desktop\fP file will be ignored by \fIgnome-session\fP. It
|
|
instead relies on the fact that these components are managed by systemd.
|
|
.PP
|
|
.PP
|
|
\fBsystemd\fP provides the two special targets \fBgraphical-session.target\fP
|
|
and \fBgraphical-session-pre.target\fP which are fully functional and should be
|
|
used. \fIgnome-session\fP provides the following main targets:
|
|
.TP
|
|
.I "gnome-session.target"
|
|
Generic unit that will be active throughout the session. Similar to
|
|
\fBgraphical-session.target\fP.
|
|
.TP
|
|
.I "gnome-session-pre.target"
|
|
Used for tasks that need to be done before session startup. Similar to
|
|
\fBgraphical-session-pre.target\fP.
|
|
.TP
|
|
.I "gnome-session-x11@SESSION.target" "gnome-session-wayland@SESSION.target"
|
|
Main unit started for X11/wayland based session. \fBSESSION\fP is set according
|
|
to the session that is passed in \fI--session\fP.
|
|
.TP
|
|
.I "gnome-session-x11.target" "gnome-session-wayland.target"
|
|
Convenience units without the session embedded into the target.
|
|
.TP
|
|
.I "gnome-session@SESSION.target"
|
|
Convenience unit with just the \fBSESSION\fP information embedded.
|
|
.TP
|
|
.I "gnome-session-x11-services.target"
|
|
Special unit started when X11 services are needed. This will be used from GNOME
|
|
3.36 onwards. Programs will need to use the special \fBGNOME_SETUP_DISPLAY\fP
|
|
environment variable instead of \fIDISPLAY\fP.
|
|
.PP
|
|
Note that care must be taken to set appropriate \fBAfter=\fP rules. It is also
|
|
strongly recommended to always do this in combination with \fBBindsTo=\fP or
|
|
\fBPartOf=\fP on one of the core targets (e.g. \fBgraphical-session.target\fP).
|
|
.PP
|
|
Units are required to set \fBCollectMode=inactive-or-failed\fP. In addition, it
|
|
is strongly recommended to set \fBTimeoutStopSec=5\fP so that logout
|
|
will not be delayed indefinitely in case the process does not stop properly.
|
|
.SH ENVIRONMENT
|
|
\fIgnome-session\fP sets several environment variables for the use of
|
|
its child processes:
|
|
.PP
|
|
.B SESSION_MANAGER
|
|
.IP
|
|
This variable is used by session-manager aware clients to contact
|
|
gnome-session.
|
|
.PP
|
|
.B DISPLAY
|
|
.IP
|
|
This variable is set to the X display being used by
|
|
\fIgnome-session\fP. Note that if the \fI--display\fP option is used
|
|
this might be different from the setting of the environment variable
|
|
when gnome-session is invoked.
|
|
.PP
|
|
Behavior of \fIgnome-session\fP ifself can be modified via the following environment variable:
|
|
.PP
|
|
.B GNOME_SESSION_AUTOSTART_DIR
|
|
.IP
|
|
This variable specifies a list of directories to the searched for autostart
|
|
files. This variable overrides all directories specified via the
|
|
\fI--autostart\fP option, as well as all default autostart directories.
|
|
.SH FILES
|
|
.PP
|
|
.B $XDG_CONFIG_HOME/autostart
|
|
.B $XDG_CONFIG_DIRS/autostart
|
|
.B /usr/share/gnome/autostart
|
|
.IP
|
|
Applications defined via .desktop files in those directories will be started on login.
|
|
.PP
|
|
.B $XDG_CONFIG_HOME/gnome-session/sessions
|
|
.B $XDG_CONFIG_DIRS/gnome-session/sessions
|
|
.B $XDG_DATA_DIRS/gnome-session/sessions
|
|
.IP
|
|
These directories contain the \fB.session\fP files that can be used
|
|
with the \fI--session\fP option.
|
|
.PP
|
|
.B $XDG_CONFIG_HOME/gnome-session/saved-session
|
|
.IP
|
|
This directory contains the list of applications of the saved session.
|
|
.SH BUGS
|
|
If you find bugs in the \fIgnome-session\fP program, please report
|
|
these on https://gitlab.gnome.org/GNOME/gnome-session/issues.
|
|
.SH SEE ALSO
|
|
.BR gnome-session-quit(1)
|