Xsession(5)

✨ Xsession — initialize X session ✨

Xsession(5), File Formats Manual — this is the page that explains how your X session gets set up, bestie 💖

🎀 NAME 🎀

Xsession — initialize X session 🌸

🦋 SYNOPSIS 🦋

Xsession [ session-type ]

💅 DESCRIPTION 💅

okay so /etc/X11/Xsession is a Bourne shell (sh(1)) script that runs whenever an X Window System session gets started, either by startx(1) or by a display manager like xdm(1) ✨ (some display managers only call Xsession when the user specifically asks for it, so check your display manager's docs to see what it's doing 🙈). Admins who aren't into the Bourne shell will probably find the Xsession.options(5) config file way easier to handle than Xsession itself 🫶

Xsession is not meant to be run directly by you 🚫 it needs to run in a special environment that gets set up during X server initialization to actually work. startx, xdm, xinit(1), and other similar programs take care of that part for you 💜

By default on a Debian system, Xsession gets used by both of the usual ways of starting the X Window System: xdm (or another X display manager) and startx 🌈 if you want to change this for xdm, edit the ‘DisplayManager*session’ resource in the /etc/X11/xdm/xdm-config file. For other display managers, go read their documentation 📚 and if you want startx to stop using Xsession by default, replace the contents of the /etc/X11/xinit/xinitrc file ⭐

The Xsession script is super flexible, so you can customize the whole X startup procedure without ever touching the script itself 🧚 see “CUSTOMIZING THE STARTUP PROCEDURE” below, it's so worth it.

---

🌸 SESSION TYPES 🌸

Xsession can optionally be handed a single argument that says what kind of X session to start 🦋 the display manager is the one that normally decides what that argument is. If you want to pass one in from startx or xinit, you have to call /etc/X11/Xsession (or /etc/X11/xinit/xinitrc) explicitly with a path, like this: startx /etc/X11/Xsession failsafe. By default, three different arguments are supported:

• failsafe — starts a session that's nothing but an x-terminal-emulator(1) 🖥️ (no window manager gets launched, so it's bare-bones on purpose). If the x-terminal-emulator program can't be found, the session just exits 💀 and heads up, the failsafe argument gets ignored unless there's an allow-failsafe line in Xsession.options.
• default — does exactly the same thing as if you hadn't passed a session type argument at all 🍓
• program — starts program if it can be found somewhere in your $PATH 🔥 this is usually a session manager or a super feature-packed window manager. If program can't be found, Xsession just carries on with its default behavior. This argument gets ignored if there's no allow-user-xsession line in Xsession.options. (Real talk, if the admin doesn't want users writing their own .xsession files, it doesn't make much sense to let them name arbitrary programs to run either 🙈) Also, the restriction might be easy to get around, e.g. by just using a .gnomerc file instead 👀

---

🧚 DEFAULT STARTUP PROCEDURE 🧚

To start, Xsession does some housekeeping 🧹 it declares a set of built-in functions (see “BUILT-IN SHELL FUNCTIONS” below) and variables, and then tries to create a log file for the X session, or append to one that already exists. Historically this is called an ‘error’ file, but honestly it catches all sorts of diagnostic output from the various X clients running in your session, not just error messages 🫶 If it's impossible to write to an error file, the script (and therefore the whole X session) aborts 😭

For convenience, once the error file gets opened successfully, Xsession logs that the session has started, the username that invoked it, and the date, all into the error file ✨ this makes it way easier to figure out which X session produced a particular line of output in the file 🎀

Next up, Xsession checks that its script directory, Xsession.d, exists. If it doesn't, the script aborts 💔 once that directory is confirmed to be there, Xsession uses run-parts(1) to figure out which files in it should be sourced (executed) in the shell's environment 🌈 only files named in a certain way get sourced, so check the run-parts manual page for a description of which characters are valid in a filename. (This restriction is actually clever: the admin can move experimental or problematic files out of the way but keep them in an obvious place, like by adding .old or .broken to the end of the filename 🍓)

---

🦋 SUPPLIED SCRIPTS 🦋

Five shell script portions come supplied by default to handle the details of the session startup procedure 💖

/etc/X11/Xsession.d/20x11-common_process-args

Arguments get processed the way described in “SESSION TYPES” above. If a startup program gets identified at this point, it's just stored for later reference and not run right away 🧚

/etc/X11/Xsession.d/30x11-common_xresources

This one merges your X resources ✨ it uses run-parts again, this time to find files in the /etc/X11/Xresources directory that should be processed with xrdb -merge. After that, if the line allow-user-resources is present in Xsession.options, the user's $HOME/.Xresources file gets merged in the same way 💅

/etc/X11/Xsession.d/35x11-common_xhost-local

Gives access to the X server to the same user on the local host 🔓 if the xhost command is available, it gets used to let any process of the same user running on the local host access the X server 🫶

/etc/X11/Xsession.d/40x11-common_xsessionrc

Sources global environment variables 🌸 this script will source anything in $HOME/.xsessionrc if that file is there. It's how you can set global environment variables for your X session, like locale information 🌍

/etc/X11/Xsession.d/50x11-common_determine-startup

This is where the startup program gets decided 👑 the X client that launches as the controlling process (the one that, when it exits, makes the X server exit too) is figured out here. If a program or failsafe argument got passed in and is allowed (see above), it becomes the controlling process. Otherwise, if the line allow-user-xsession is present in Xsession.options, a user-specified session program or script gets used. In that case, two historically popular names for user X session scripts get searched for: $HOME/.xsession and $HOME/.Xsession (notice the difference in case 👀). The first one found is used. If the script isn't executable, it gets marked to be run with the Bourne shell interpreter, sh. Finally, if none of the above works out, these programs get searched for: /usr/bin/x-session-manager, /usr/bin/x-window-manager, and /usr/bin/x-terminal-emulator. The first one found is used. If none of them are found, Xsession aborts with an error 💀

/etc/X11/Xsession.d/90x11-common_ssh-agent

Starts ssh-agent(1), if it's needed 🔑 if the line use-ssh-agent is present in Xsession.options, and no SSH agent process seems to be running already, ssh-agent is marked to be used to run the startup program figured out earlier. Note: this functionality may move to the ssh package in the future 👀

/etc/X11/Xsession.d/99x11-common_start

The big finale ✨ this one starts the X session. The startup program gets executed, inside a Bourne shell if it isn't executable, and inside an ssh-agent if that's necessary. The shell's exec command is used so it doesn't waste a slot in the process table 🧚

---

to be continued in part 2, bestie, so stay tuned 💜

✨ INPUT FILES ✨

okay so these are all the files Xsession reads from, bestie 🫶

/etc/X11/Xsession.d/ 📂

This is a directory full of Bourne shell scripts that Xsession runs for you 💅. The files in here get matched using run-parts, and they're sourced, not run in a subshell, so they can actually change the session's environment 🔥

/etc/X11/Xresources/ 🎀

This directory holds files named after Debian package names 🧚. Each one has system-wide X resource settings for the X clients from that package. The settings get loaded with xrdb -merge, and the files are matched using run-parts ✨

/etc/X11/Xsession.options ⚙️

This file has the configuration options for the /etc/X11/Xsession script. For more details, check out Xsession.options(5) 🦋

$HOME/.Xresources 🌸

This one is your own personal X resources file, specific to your environment 💖 The settings get loaded with xrdb -merge.

Heads up: $HOME/.Xdefaults is a total relic 🙈 It comes from the X Version 10 (and X11R1) days, back before app-defaults files were a thing. It's been deprecated for over ten years at the time of writing, so use .Xresources instead, periodt 💅

$HOME/.xsession 🌈

This is a list of commands that launch X clients, or a session manager like xsm(1) 👑 For tips on writing one, look at the manual page for xinit. It's giving very helpful energy 💜

---

✨ OUTPUT FILES ✨

okay now the places where stuff gets written out 📝

$HOME/.xsession-errors 🍓

This is the default spot where standard output and standard error go, for the Xsession script and for every X client process 😭

$TMPDIR/filename 🧚

If $HOME/.xsession-errors can't be opened, the X session error file gets put here instead 🫣 For security reasons, the exact filename is randomly generated by tempfile(1), so nobody can guess it. Iconic behavior, honestly 🔐

---

✨ AUTHORS ✨

Stephen Early, Mark Eichin, and Branden Robinson built Debian's X session handling scripts together 🫶 Branden Robinson is also the one who wrote this manual page 💖

---

✨ SEE ALSO ✨

Xsession.options(5), X(7), run-parts(1), ssh-agent(1), startx(1), tempfile(1), xdm(1), xmessage(1), xmodmap(1), xrdb(1), sh(1) 🦋

---

That's the whole page, bestie! 🌈 It was brought to you by the Debian Project, last touched on 2004-11-04, and it's filed under Xsession(5) 💅✨