1xscreensaver(1) XScreenSaver manual xscreensaver(1)
2
6 xscreensaver - extensible screen saver and screen locking framework
7
9 xscreensaver [-display host:display.screen] [-verbose] [-no-splash]
10 [-no-capture-stderr] [-log filename]
11
13 The xscreensaver program waits until the keyboard and mouse have been
14 idle for a period, and then runs a graphics demo chosen at random. It
15 turns off as soon as there is any mouse or keyboard activity.
16 This program can lock your terminal in order to prevent others from
18 using it, though its default mode of operation is merely to display
19 pretty pictures on your screen when it is not in use.
20 It also provides configuration and control of your monitor's power-sav‐
22 ing features.
23
25 For the impatient, try this:
26 xscreensaver &
27 xscreensaver-demo
28 The xscreensaver-demo(1) program pops up a dialog box that lets you
29 configure the screen saver, and experiment with the various display
30 modes.
31 Note that xscreensaver has a client-server model: the xscreensaver pro‐
33 gram is a daemon that runs in the background; it is controlled by the
34 foreground xscreensaver-demo(1) and xscreensaver-command(1) programs.
35
37 The easiest way to configure xscreensaver is to simply run the xscreen‐
38 saver-demo(1) program, and change the settings through the GUI. The
39 rest of this manual page describes lower level ways of changing set‐
40 tings.
41 I'll repeat that because it's important:
43 The easy way to configure xscreensaver is to run the xscreensaver-
45 demo(1) program. You shouldn't need to know any of the stuff
46 described in this manual unless you are trying to do something
47 tricky, like customize xscreensaver for site-wide use or something.
48 Options to xscreensaver are stored in one of two places: in a .xscreen‐
50 saver file in your home directory; or in the X resource database. If
51 the .xscreensaver file exists, it overrides any settings in the
52 resource database.
53 The syntax of the .xscreensaver file is similar to that of the .Xde‐
55 faults file; for example, to set the timeout parameter in the .xscreen‐
56 saver file, you would write the following:
57 timeout: 5
58 whereas, in the .Xdefaults file, you would write
59 xscreensaver.timeout: 5
60 If you change a setting in the .xscreensaver file while xscreensaver is
61 already running, it will notice this, and reload the file. (The file
62 will be reloaded the next time the screen saver needs to take some
63 action, such as blanking or unblanking the screen, or picking a new
64 graphics mode.)
65 If you change a setting in your X resource database, or if you want
67 xscreensaver to notice your changes immediately instead of the next
68 time it wakes up, then you will need to reload your .Xdefaults file,
69 and then tell the running xscreensaver process to restart itself, like
70 so:
71 xrdb < ~/.Xdefaults
72 xscreensaver-command -restart
73 If you want to set the system-wide defaults, then make your edits to
74 the xscreensaver app-defaults file, which should have been installed
75 when xscreensaver itself was installed. The app-defaults file will
76 usually be named /usr/lib/X11/app-defaults/XScreenSaver, but different
77 systems might keep it in a different place (for example, /usr/open‐
78 win/lib/app-defaults/XScreenSaver on Solaris).
79 When settings are changed in the Preferences dialog box (see above) the
81 current settings will be written to the .xscreensaver file. (The .Xde‐
82 faults file and the app-defaults file will never be written by xscreen‐
83 saver itself.)
84
86 xscreensaver also accepts a few command-line options, mostly for use
87 when debugging: for normal operation, you should configure things via
88 the ~/.xscreensaver file.
89 -display host:display.screen
91 The X display to use. For displays with multiple screens,
92 XScreenSaver will manage all screens on the display simultan‐
93 iously.
94 -verbose
96 Same as setting the verbose resource to true: print diagnostics
97 on stderr and on the xscreensaver window.
98 -no-capture-stderr
100 Do not redirect the stdout and stderr streams to the xscreen‐
101 saver window itself. If xscreensaver is crashing, you might
102 need to do this in order to see the error message.
103 -log filename
105 This is exactly the same as redirecting stdout and stderr to
106 the given file (for append). This is useful when reporting
107 bugs.
108
110 When it is time to activate the screensaver, a full-screen black window
111 is created on each screen of the display. Each window is created in
112 such a way that, to any subsequently-created programs, it will appear
113 to be a "virtual root" window. Because of this, any program which
114 draws on the root window (and which understands virtual roots) can be
115 used as a screensaver. The various graphics demos are, in fact, just
116 standalone programs that know how to draw on the provided window.
117 When the user becomes active again, the screensaver windows are
119 unmapped, and the running subprocesses are killed by sending them
120 SIGTERM. This is also how the subprocesses are killed when the screen‐
121 saver decides that it's time to run a different demo: the old one is
122 killed and a new one is launched.
123 You can control a running screensaver process by using the xscreen‐
125 saver-command(1) program (which see).
126
128 Modern X servers contain support to power down the monitor after an
129 idle period. If the monitor has powered down, then xscreensaver will
130 notice this (after a few minutes), and will not waste CPU by drawing
131 graphics demos on a black screen. An attempt will also be made to
132 explicitly power the monitor back up as soon as user activity is
133 detected.
134 The ~/.xscreensaver file controls the configuration of your display's
136 power management settings: if you have used xset(1) to change your
137 power management settings, then xscreensaver will override those
138 changes with the values specified in ~/.xscreensaver (or with its
139 built-in defaults, if there is no ~/.xscreensaver file yet).
140 To change your power management settings, run xscreensaver-demo(1) and
142 change the various timeouts through the user interface. Alternatively,
143 you can edit the ~/.xscreensaver file directly.
144 If the power management section is grayed out in the xscreen‐
146 saver-demo(1) window, then that means that your X server does not sup‐
147 port the XDPMS extension, and so control over the monitor's power state
148 is not available.
149 If you're using a laptop, don't be surprised if changing the DPMS set‐
151 tings has no effect: many laptops have monitor power-saving behavior
152 built in at a very low level that is invisible to Unix and X. On such
153 systems, you can typically adjust the power-saving delays only by
154 changing settings in the BIOS in some hardware-specific way.
155 If DPMS seems not to be working with XFree86, make sure the "DPMS"
157 option is set in your /etc/X11/XF86Config file. See the XF86Config(5)
158 manual for details.
159
161 For the better part of a decade, GNOME shipped xscreensaver as-is, and
162 everything just worked out of the box. In 2005, however, they decided
163 to re-invent the wheel and ship their own replacement for the xscreen‐
164 saver daemon called "gnome-screensaver", rather than improving xscreen‐
165 saver and contributing their changes back. As a result, the "gnome-
166 screensaver" program is insecure, bug-ridden, and missing many features
167 of xscreensaver. You shouldn't use it.
168 To replace gnome-screensaver with xscreensaver:
170 1: Fully uninstall the gnome-screensaver package.
172 sudo apt-get remove gnome-screensaver
173 or possibly
174 sudo dpkg -P gnome-screensaver
175 2: Launch xscreensaver at login.
177 Select "Startup Applications" from the menu (or manually launch
178 "gnome-session-properties") and add "xscreensaver".
179 Do this as your normal user account, not as root. (This should
181 go without saying, because you should never, ever, ever be
182 logged in to the graphical desktop as user "root".)
183 3: Make GNOME's "Lock Screen" use xscreensaver.
185 sudo ln -sf /usr/bin/xscreensaver-command \
186 /usr/bin/gnome-screensaver-command
187 That doesn't work under Unity, though. Apparently it has its
188 own built-in screen locker which is not gnome-screensaver, and
189 cannot be removed, and yet still manages to be bug-addled and
190 insecure. Keep reinventing that wheel, guys! (If you have fig‐
191 ured out how to replace Unity's locking "feature" with xscreen‐
192 saver, let me know.)
193 4: Turn off Unity's built-in blanking.
195 Open "System Settings / Brightness & Lock";
196 Un-check "Start Automatically";
197 Set "Turn screen off when inactive for" to "Never".
198
200 Like GNOME, KDE also decided to invent their own screen saver framework
201 from scratch instead of simply using xscreensaver. To replace the KDE
202 screen saver with xscreensaver, do the following:
203 1: Turn off KDE's screen saver.
205 Open the "Control Center" and select the "Appearance & Themes /
206 Screensaver" page. Un-check "Start Automatically".
207 Or possibly: Open "System Settings" and select "Screen Locking".
209 Un-check "Lock Screen Automatically".
210 2: Find your Autostart directory.
212 Open the "System Administration / Paths" page, and see what your
213 "Autostart path" is set to: it will probably be something like
214 ~/.kde/Autostart/ or ~/.config/autostart/
215 If that doesn't work, then try this:
217 Open "System Settings / Startup/Shutdown / Autostart", and then
219 add "/usr/bin/xscreensaver".
220 If you are lucky, that will create a "xscreensaver.desktop" file
222 for you in ~/.config/autostart/ or ~/.kde/Autostart/.
223 3: Make xscreensaver be an Autostart program.
225 If it does not already exist, create a file in your autostart
226 directory called xscreensaver.desktop that contains the follow‐
227 ing six lines:
228 [Desktop Entry]
229 Exec=xscreensaver
230 Name=XScreenSaver
231 Type=Application
232 StartupNotify=false
233 X-KDE-StartupNotify=false
234 4: Make the various "lock session" buttons call xscreensaver.
236 The file you want to replace next has moved around over the
237 years. It might be called /usr/libexec/kde4/kscreenlocker, or it
238 might be called "kdesktop_lock" or "krunner_lock" or "kscreen‐
239 locker_greet", and it might be in /usr/lib/kde4/libexec/ or in
240 /usr/kde/3.5/bin/ or even in /usr/bin/, depending on the distro
241 and phase of the moon. Replace the contents of that file with
242 these two lines:
243 #!/bin/sh
244 xscreensaver-command -lock
245 Make sure the file is executable (chmod a+x).
246 Now use xscreensaver normally, controlling it via the usual xscreen‐
248 saver-demo(1) and xscreensaver-command(1) mechanisms.
249
251 If the above didn't do it, and your system has systemd(1), then give
252 this a try:
253 1: Create a service.
255 Create the file ~/.config/systemd/user/xscreensaver.service contain‐
256 ing:
257 [Unit]
258 Description=XScreenSaver
259 [Service]
260 ExecStart=/usr/bin/xscreensaver
261 [Install]
262 WantedBy=default.target
263 2. Enable it.
265 systemctl --user enable xscreensaver
266 Then restart X11.
267
269 If it's still not working, but on your distro, that newfangled sys‐
270 temd(1) nonsense has already fallen out of favor? Then maybe this will
271 work: launch the "Startup Applications" applet, click "Add", enter
272 these lines, then restart X11:
273 Name: XScreenSaver
274 Command: xscreensaver
275 Comment: xscreensaver
276
278 You can run xscreensaver from your gdm(1) session, so that the screen‐
279 saver will run even when nobody is logged in on the console. To do
280 this, run gdmconfig(1).
281 On the General page set the Local Greeter to Standard Greeter.
283 On the Background page, type the command "xscreensaver -nosplash" into
285 the Background Program field. That will cause gdm to run xscreensaver
286 while nobody is logged in, and kill it as soon as someone does log in.
287 (The user will then be responsible for starting xscreensaver on their
288 own, if they want.)
289 If that doesn't work, you can edit the config file directly. Edit
291 /etc/X11/gdm/gdm.conf to include:
292 Greeter=/usr/bin/gdmlogin
293 BackgroundProgram=xscreensaver -nosplash
294 RunBackgroundProgramAlways=true
295 In this situation, the xscreensaver process will probably be running as
296 user gdm instead of root. You can configure the settings for this
297 nobody-logged-in state (timeouts, DPMS, etc.) by editing the
298 ~gdm/.xscreensaver file.
299 It is safe to run xscreensaver as root (as xdm or gdm may do). If run
301 as root, xscreensaver changes its effective user and group ids to some‐
302 thing safe (like "nobody") before connecting to the X server or launch‐
303 ing user-specified programs.
304 An unfortunate side effect of this (important) security precaution is
306 that it may conflict with cookie-based authentication.
307 If you get "connection refused" errors when running xscreensaver from
309 gdm, then this probably means that you have xauth(1) or some other
310 security mechanism turned on. For information on the X server's access
311 control mechanisms, see the man pages for X(1), Xsecurity(1), xauth(1),
312 and xhost(1).
313
315 If you are running a system with systemd(1) 221 or newer, and if
316 xscreensaver was compiled with libsystemd support, then closing the lid
317 of your laptop will cause the screen to lock immediately.
318 If not, then the screen might not lock until a few seconds after you
320 re-open the lid. Which is less than ideal. So if you don't use systemd,
321 you might want to get in the habit of doing xscreensaver-command -lock
322 before closing the lid.
323
325 Bugs? There are no bugs. Ok, well, maybe. If you find one, please
326 let me know. https://www.jwz.org/xscreensaver/bugs.html explains how
327 to construct the most useful bug reports.
328 Locking and root logins
330 In order for it to be safe for xscreensaver to be launched by xdm,
331 certain precautions had to be taken, among them that xscreensaver
332 never runs as root. In particular, if it is launched as root (as
333 xdm is likely to do), xscreensaver will disavow its privileges, and
334 switch itself to a safe user id (such as nobody).
335 An implication of this is that if you log in as root on the con‐
337 sole, xscreensaver will refuse to lock the screen (because it can't
338 tell the difference between root being logged in on the console,
339 and a normal user being logged in on the console but xscreensaver
340 having been launched by the xdm(1) Xsetup file).
341 The solution to this is simple: you shouldn't be logging in on the
343 console as root in the first place! (What, are you crazy or some‐
344 thing?)
345 Proper Unix hygiene dictates that you should log in as yourself,
347 and su(1) to root as necessary. People who spend their day logged
348 in as root are just begging for disaster.
349 XAUTH and XDM
351 For xscreensaver to work when launched by xdm(1) or gdm(1), pro‐
352 grams running on the local machine as user "nobody" must be able to
353 connect to the X server. This means that if you want to run
354 xscreensaver on the console while nobody is logged in, you may need
355 to disable cookie-based access control (and allow all users who can
356 log in to the local machine to connect to the display).
357 You should be sure that this is an acceptable thing to do in your
359 environment before doing it. See the "Using GDM" section, above,
360 for more details.
361 Passwords
363 If you get an error message at startup like "couldn't get password
364 of user" then this probably means that you're on a system in which
365 the getpwent(3) library routine can only be effectively used by
366 root. If this is the case, then xscreensaver must be installed as
367 setuid to root in order for locking to work. Care has been taken
368 to make this a safe thing to do.
369 It also may mean that your system uses shadow passwords instead of
371 the standard getpwent(3) interface; in that case, you may need to
372 change some options with configure and recompile.
373 If you change your password after xscreensaver has been launched,
375 it will continue using your old password to unlock the screen until
376 xscreensaver is restarted. On some systems, it may accept both
377 your old and new passwords. So, after you change your password,
378 you'll have to do
379 xscreensaver-command -restart
380 to make xscreensaver notice.
381 PAM Passwords
383 If your system uses PAM (Pluggable Authentication Modules), then in
384 order for xscreensaver to use PAM properly, PAM must be told about
385 xscreensaver. The xscreensaver installation process should update
386 the PAM data (on Linux, by creating the file /etc/pam.d/xscreen‐
387 saver for you, and on Solaris, by telling you what lines to add to
388 the /etc/pam.conf file).
389 If the PAM configuration files do not know about xscreensaver, then
391 you might be in a situation where xscreensaver will refuse to ever
392 unlock the screen.
393 This is a design flaw in PAM (there is no way for a client to tell
395 the difference between PAM responding "I have never heard of your
396 module", and responding, "you typed the wrong password"). As far
397 as I can tell, there is no way for xscreensaver to automatically
398 work around this, or detect the problem in advance, so if you have
399 PAM, make sure it is configured correctly!
400 Machine Load
402 Although this program "nices" the subprocesses that it starts,
403 graphics-intensive subprograms can still overload the machine by
404 causing the X server process itself (which is not "niced") to con‐
405 sume many cycles. Care has been taken in all the modules shipped
406 with xscreensaver to sleep periodically, and not run full tilt, so
407 as not to cause appreciable load.
408 However, if you are running the OpenGL-based screen savers on a
410 machine that does not have a video card with 3D acceleration, they
411 will make your machine slow, despite nice(1).
412 Your options are: don't use the OpenGL display modes; or, collect
414 the spare change hidden under the cushions of your couch, and use
415 it to buy a video card manufactured after 1998. (It doesn't even
416 need to be fast 3D hardware: the problem will be fixed if there is
417 any 3D hardware at all.)
418 Magic Backdoor Keystrokes
420 The XFree86 X server and the Linux kernel both trap certain magic
421 keystrokes before X11 client programs ever see them. If you care
422 about keeping your screen locked, this is a big problem.
423 Ctrl+Alt+Backspace
425 This keystroke kills the X server, and on some systems, leaves
426 you at a text console. If the user launched X11 manually, that
427 text console will still be logged in. To disable this keystroke
428 globally and permanently, you need to set the DontZap flag in
429 your xorg.conf or XF86Config or XF86Config-4 file, depending
430 which is in use on your system. See XF86Config(5) for details.
431 Ctrl-Alt-F1, Ctrl-Alt-F2, etc.
433 These keystrokes will switch to a different virtual console,
434 while leaving the console that X11 is running on locked. If you
435 left a shell logged in on another virtual console, it is unpro‐
436 tected. So don't leave yourself logged in on other consoles.
437 You can disable VT switching globally and permanently by setting
438 DontVTSwitch in your xorg.conf, but that might make your system
439 harder to use, since VT switching is an actual useful feature.
440 There is no way to disable VT switching only when the screen is
442 locked. It's all or nothing.
443 Ctrl-Alt-KP_Multiply
445 This keystroke kills any X11 app that holds a lock, so typing
446 this will kill xscreensaver and unlock the screen. This so-
447 called "feature" showed up in the X server in 2008, and as of
448 2011, some vendors are shipping it turned on by default. How
449 nice. You can disable it by turning off AllowClosedownGrabs in
450 xorg.conf.
451 Alt-SysRq-F
453 This is the Linux kernel "OOM-killer" keystroke. It shoots down
454 random long-running programs of its choosing, and so might might
455 target and kill xscreensaver, and there's no way for xscreen‐
456 saver to protect itself from that. You can disable it globally
457 with:
458 echo 176 > /proc/sys/kernel/sysrq
459 There's little that I can do to make the screen locker be secure so
460 long as the kernel and X11 developers are actively working against
461 security like this. The strength of the lock on your front door
462 doesn't matter much so long as someone else in the house insists on
463 leaving a key under the welcome mat.
464 Dangerous Backdoor Server Extensions
466 Many distros enable by default several X11 server extensions that
467 can be used to bypass grabs, and thus snoop on you while you're
468 typing your password. These extensions are nominally for debugging
469 and automation, but they are also security-circumventing keystroke
470 loggers. If your server is configured to load the RECORD, XTRAP or
471 XTEST extensions, you absolutely should disable those, 100% of the
472 time. Look for them in xorg.conf or whatever it is called.
473
475 These are the X resources use by the xscreensaver program. You proba‐
476 bly won't need to change these manually (that's what the xscreen‐
477 saver-demo(1) program is for).
478 timeout (class Time)
480 The screensaver will activate (blank the screen) after the key‐
481 board and mouse have been idle for this many minutes. Default
482 10 minutes.
483 cycle (class Time)
485 After the screensaver has been running for this many minutes,
486 the currently running graphics-hack sub-process will be killed
487 (with SIGTERM), and a new one started. If this is 0, then the
488 graphics hack will never be changed: only one demo will run
489 until the screensaver is deactivated by user activity. Default
490 10 minutes.
491 The running saver will be restarted every cycle minutes even
493 when mode is one, since some savers tend to converge on a
494 steady state.
495 lock (class Boolean)
497 Enable locking: before the screensaver will turn off, it will
498 require you to type the password of the logged-in user (really,
499 the person who ran xscreensaver), or the root password. (Note:
500 this doesn't work if the screensaver is launched by xdm(1)
501 because it can't know the user-id of the logged-in user. See
502 the "Using XDM(1)" section, below.
503 lockTimeout (class Time)
505 If locking is enabled, this controls the length of the "grace
506 period" between when the screensaver activates, and when the
507 screen becomes locked. For example, if this is 5, and -timeout
508 is 10, then after 10 minutes, the screen would blank. If there
509 was user activity at 12 minutes, no password would be required
510 to un-blank the screen. But, if there was user activity at 15
511 minutes or later (that is, -lock-timeout minutes after activa‐
512 tion) then a password would be required. The default is 0,
513 meaning that if locking is enabled, then a password will be
514 required as soon as the screen blanks.
515 passwdTimeout (class Time)
517 If the screen is locked, then this is how many seconds the
518 password dialog box should be left on the screen before giving
519 up (default 30 seconds). This should not be too large: the X
520 server is grabbed for the duration that the password dialog box
521 is up (for security purposes) and leaving the server grabbed
522 for too long can cause problems.
523 dpmsEnabled (class Boolean)
525 Whether power management is enabled.
526 dpmsStandby (class Time)
528 If power management is enabled, how long until the monitor goes
529 solid black.
530 dpmsSuspend (class Time)
532 If power management is enabled, how long until the monitor goes
533 into power-saving mode.
534 dpmsOff (class Time)
536 If power management is enabled, how long until the monitor pow‐
537 ers down completely. Note that these settings will have no
538 effect unless both the X server and the display hardware sup‐
539 port power management; not all do. See the Power Management
540 section, below, for more information.
541 dpmsQuickOff (class Boolean)
543 If mode is blank and this is true, then the screen will be pow‐
544 ered down immediately upon blanking, regardless of other power-
545 management settings.
546 visualID (class VisualID)
548 This is an historical artifacts left over from when 8-bit dis‐
549 plays were still common. You should probably ignore this.
550 Specify which X visual to use by default. (Note carefully that
552 this resource is called visualID, not merely visual; if you set
553 the visual resource instead, things will malfunction in obscure
554 ways for obscure reasons.)
555 Legal values for the VisualID resource are:
557 default Use the screen's default visual (the visual of the root
559 window). This is the default.
560 best Use the visual which supports the most colors. Note,
562 however, that the visual with the most colors might be
563 a TrueColor visual, which does not support colormap
564 animation. Some programs have more interesting behav‐
565 ior when run on PseudoColor visuals than on TrueColor.
566 mono Use a monochrome visual, if there is one.
568 gray Use a grayscale or staticgray visual, if there is one
570 and it has more than one plane (that is, it's not mono‐
571 chrome).
572 color Use the best of the color visuals, if there are any.
574 GL Use the visual that is best for OpenGL programs.
576 (OpenGL programs have somewhat different requirements
577 than other X programs.)
578 class where class is one of StaticGray, StaticColor, True‐
580 Color, GrayScale, PseudoColor, or DirectColor. Selects
581 the deepest visual of the given class.
582 number where number (decimal or hex) is interpreted as a vis‐
584 ual id number, as reported by the xdpyinfo(1) program;
585 in this way you can have finer control over exactly
586 which visual gets used, for example, to select a shal‐
587 lower one than would otherwise have been chosen.
588 Note that this option specifies only the default visual that
590 will be used: the visual used may be overridden on a program-
591 by-program basis. See the description of the programs
592 resource, below.
593 installColormap (class Boolean)
595 On PseudoColor (8-bit) displays, install a private colormap
596 while the screensaver is active, so that the graphics hacks can
597 get as many colors as possible. This is the default. (This
598 only applies when the screen's default visual is being used,
599 since non-default visuals get their own colormaps automati‐
600 cally.) This can also be overridden on a per-hack basis: see
601 the discussion of the default-n name in the section about the
602 programs resource.
603 This does nothing if you have a TrueColor (16-bit or deeper)
605 display. (Which, in this century, you do.)
606 verbose (class Boolean)
608 Whether to print diagnostics. Default false.
609 timestamp (class Boolean)
611 Whether to print the time of day along with any other diagnos‐
612 tic messages. Default true.
613 splash (class Boolean)
615 Whether to display a splash screen at startup. Default true.
616 splashDuration (class Time)
618 How long the splash screen should remain visible; default 5
619 seconds.
620 helpURL (class URL)
622 The splash screen has a Help button on it. When you press it,
623 it will display the web page indicated here in your web
624 browser.
625 loadURL (class LoadURL)
627 This is the shell command used to load a URL into your web
628 browser. The default setting will load it into Mozilla/Net‐
629 scape if it is already running, otherwise, will launch a new
630 browser looking at the helpURL.
631 demoCommand (class DemoCommand)
633 This is the shell command run when the Demo button on the
634 splash window is pressed. It defaults to xscreensaver-demo(1).
635 prefsCommand (class PrefsCommand)
637 This is the shell command run when the Prefs button on the
638 splash window is pressed. It defaults to xscreen‐
639 saver-demo -prefs.
640 newLoginCommand (class NewLoginCommand)
642 If set, this is the shell command that is run when the "New
643 Login" button is pressed on the unlock dialog box, in order to
644 create a new desktop session without logging out the user who
645 has locked the screen. Typically this will be some variant of
646 gdmflexiserver(1), kdmctl(1), lxdm(1) or dm-tool(1).
647 nice (class Nice)
649 The sub-processes created by xscreensaver will be "niced" to
650 this level, so that they are given lower priority than other
651 processes on the system, and don't increase the load unneces‐
652 sarily. The default is 10. (Higher numbers mean lower prior‐
653 ity; see nice(1) for details.)
654 fade (class Boolean)
656 If this is true, then when the screensaver activates, the cur‐
657 rent contents of the screen will fade to black instead of sim‐
658 ply winking out. This only works on certain systems. A fade
659 will also be done when switching graphics hacks (when the cycle
660 timer expires). Default: true.
661 unfade (class Boolean)
663 If this is true, then when the screensaver deactivates, the
664 original contents of the screen will fade in from black instead
665 of appearing immediately. This only works on certain systems,
666 and if fade is true as well. Default false.
667 fadeSeconds (class Time)
669 If fade is true, this is how long the fade will be in seconds
670 (default 3 seconds).
671 fadeTicks (class Integer)
673 If fade is true, this is how many times a second the colormap
674 will be changed to effect a fade. Higher numbers yield
675 smoother fades, but may make the fades take longer than the
676 specified fadeSeconds if your server isn't fast enough to keep
677 up. Default 20.
678 captureStderr (class Boolean)
680 Whether xscreensaver should redirect its stdout and stderr
681 streams to the window itself. Since its nature is to take over
682 the screen, you would not normally see error messages generated
683 by xscreensaver or the sub-programs it runs; this resource will
684 cause the output of all relevant programs to be drawn on the
685 screensaver window itself, as well as being written to the con‐
686 trolling terminal of the screensaver driver process. Default
687 true.
688 ignoreUninstalledPrograms (class Boolean)
690 There may be programs in the list that are not installed on the
691 system, yet are marked as "enabled". If this preference is
692 true, then such programs will simply be ignored. If false,
693 then a warning will be printed if an attempt is made to run the
694 nonexistent program. Also, the xscreensaver-demo(1) program
695 will suppress the non-existent programs from the list if this
696 is true. Default: false.
697 authWarningSlack (class Integer)
699 If all failed unlock attempts (incorrect password entered) were
700 made within this period of time, the usual dialog that warns
701 about such attempts after a successful login will be sup‐
702 pressed. The assumption is that incorrect passwords entered
703 within a few seconds of a correct one are user error, rather
704 than hostile action. Default 20 seconds.
705 GetViewPortIsFullOfLies (class Boolean)
707 Set this to true if the xscreensaver window doesn't cover the
708 whole screen. This works around a longstanding XFree86 bug
709 #421. See the xscreensaver FAQ for details.
710 font (class Font)
712 The font used for the stdout/stderr text, if captureStderr is
713 true. Default *-medium-r-*-140-*-m-* (a 14 point fixed-width
714 font).
715 mode (class Mode)
717 Controls the behavior of xscreensaver. Legal values are:
718 random When blanking the screen, select a random display mode
720 from among those that are enabled and applicable. This
721 is the default.
722 random-same
724 Like random, but if there are multiple screens, each
725 screen will run the same random display mode, instead
726 of each screen running a different one.
727 one When blanking the screen, only ever use one particular
729 display mode (the one indicated by the selected set‐
730 ting).
731 blank When blanking the screen, just go black: don't run any
733 graphics hacks.
734 off Don't ever blank the screen, and don't ever allow the
736 monitor to power down.
737 selected (class Integer)
740 When mode is set to one, this is the one, indicated by its
741 index in the programs list. You're crazy if you count them and
742 set this number by hand: let xscreensaver-demo(1) do it for
743 you!
744 programs (class Programs)
746 The graphics hacks which xscreensaver runs when the user is
747 idle. The value of this resource is a multi-line string, one
748 sh-syntax command per line. Each line must contain exactly one
749 command: no semicolons, no ampersands.
750 When the screensaver starts up, one of these is selected
752 (according to the mode setting), and run. After the cycle
753 period expires, it is killed, and another is selected and run.
754 If a line begins with a dash (-) then that particular program
756 is disabled: it won't be selected at random (though you can
757 still select it explicitly using the xscreensaver-demo(1) pro‐
758 gram).
759 If all programs are disabled, then the screen will just be made
761 blank, as when mode is set to blank.
762 To disable a program, you must mark it as disabled with a dash
764 instead of removing it from the list. This is because the sys‐
765 tem-wide (app-defaults) and per-user (.xscreensaver) settings
766 are merged together, and if a user just deletes an entry from
767 their programs list, but that entry still exists in the system-
768 wide list, then it will come back. However, if the user dis‐
769 ables it, then their setting takes precedence.
770 If the display has multiple screens, then a different program
772 will be run for each screen. (All screens are blanked and
773 unblanked simultaneously.)
774 Note that you must escape the newlines; here is an example of
776 how you might set this in your ~/.xscreensaver file:
777 programs: \
779 qix -root \n\
780 ico -r -faces -sleep 1 -obj ico \n\
781 xdaliclock -builtin2 -root \n\
782 xv -root -rmode 5 image.gif -quit \n
783 Make sure your $PATH environment variable is set up correctly
784 before xscreensaver is launched, or it won't be able to find
785 the programs listed in the programs resource.
786 To use a program as a screensaver, two things are required:
788 that that program draw on the root window (or be able to be
789 configured to draw on the root window); and that that program
790 understand "virtual root" windows, as used by virtual window
791 managers such as tvtwm(1). (Generally, this is accomplished by
792 just including the "vroot.h" header file in the program's
793 source.)
794 Visuals:
796 Because xscreensaver was created back when dinosaurs roamed the
798 earth, it still contains support for some things you've proba‐
799 bly never seen, such as 1-bit monochrome monitors, grayscale
800 monitors, and monitors capable of displaying only 8-bit col‐
801 ormapped images.
802 If there are some programs that you want to run only when using
804 a color display, and others that you want to run only when
805 using a monochrome display, you can specify that like this:
806 mono: mono-program -root \n\
807 color: color-program -root \n\
808 More generally, you can specify the kind of visual that should
809 be used for the window on which the program will be drawing.
810 For example, if one program works best if it has a colormap,
811 but another works best if it has a 24-bit visual, both can be
812 accommodated:
813 PseudoColor: cmap-program -root \n\
814 TrueColor: 24bit-program -root \n\
815 In addition to the symbolic visual names described above (in
816 the discussion of the visualID resource) one other visual name
817 is supported in the programs list:
818 default-n
820 This is like default, but also requests the use of the
821 default colormap, instead of a private colormap. (That
822 is, it behaves as if the -no-install command-line option
823 was specified, but only for this particular hack.) This
824 is provided because some third-party programs that draw on
825 the root window (notably: xv(1), and xearth(1)) make
826 assumptions about the visual and colormap of the root win‐
827 dow: assumptions which xscreensaver can violate.
828 If you specify a particular visual for a program, and that vis‐
830 ual does not exist on the screen, then that program will not be
831 chosen to run. This means that on displays with multiple
832 screens of different depths, you can arrange for appropriate
833 hacks to be run on each. For example, if one screen is color
834 and the other is monochrome, hacks that look good in mono can
835 be run on one, and hacks that only look good in color will show
836 up on the other.
837 You shouldn't ever need to change the following resources:
839 pointerPollTime (class Time)
841 When server extensions are not in use, this controls how fre‐
842 quently xscreensaver checks to see if the mouse position or
843 buttons have changed. Default 5 seconds.
844 pointerHysteresis (class Integer)
846 If the mouse moves less than this-many pixels in a second,
847 ignore it (do not consider that to be "activity"). This is so
848 that the screen doesn't un-blank (or fail to blank) just
849 because you bumped the desk. Default: 10 pixels.
850 windowCreationTimeout (class Time)
852 When server extensions are not in use, this controls the delay
853 between when windows are created and when xscreensaver selects
854 events on them. Default 30 seconds.
855 initialDelay (class Time)
857 When server extensions are not in use, xscreensaver will wait
858 this many seconds before selecting events on existing windows,
859 under the assumption that xscreensaver is started during your
860 login procedure, and the window state may be in flux. Default
861 0. (This used to default to 30, but that was back in the days
862 when slow machines and X terminals were more common...)
863 procInterrupts (class Boolean)
865 This resource controls whether the /proc/interrupts file should
866 be consulted to decide whether the user is idle. This is the
867 default if xscreensaver has been compiled on a system which
868 supports this mechanism (i.e., Linux systems).
869 The benefit to doing this is that xscreensaver can note that
871 the user is active even when the X console is not the active
872 one: if the user is typing in another virtual console, xscreen‐
873 saver will notice that and will fail to activate. For example,
874 if you're playing Quake in VGA-mode, xscreensaver won't wake up
875 in the middle of your game and start competing for CPU.
876 The drawback to doing this is that perhaps you really do want
878 idleness on the X console to cause the X display to lock, even
879 if there is activity on other virtual consoles. If you want
880 that, then set this option to False. (Or just lock the X con‐
881 sole manually.)
882 The default value for this resource is True, on systems where
884 it works.
885 overlayStderr (class Boolean)
887 If captureStderr is True, and your server supports "overlay"
888 visuals, then the text will be written into one of the higher
889 layers instead of into the same layer as the running screen‐
890 hack. Set this to False to disable that (though you shouldn't
891 need to).
892 overlayTextForeground (class Foreground)
894 The foreground color used for the stdout/stderr text, if cap‐
895 tureStderr is true. Default: Yellow.
896 overlayTextBackground (class Background)
898 The background color used for the stdout/stderr text, if cap‐
899 tureStderr is true. Default: Black.
900 bourneShell (class BourneShell)
902 The pathname of the shell that xscreensaver uses to start sub‐
903 processes. This must be whatever your local variant of /bin/sh
904 is: in particular, it must not be csh.
905
907 DISPLAY to get the default host and display number, and to inform the
908 sub-programs of the screen on which to draw.
909 XSCREENSAVER_WINDOW
911 Passed to sub-programs to indicate the ID of the window on
912 which they should draw. This is necessary on Xinerama/RANDR
913 systems where multiple physical monitors share a single X11
914 "Screen".
915 PATH to find the sub-programs to run.
917 HOME for the directory in which to read the .xscreensaver file.
919 XENVIRONMENT
921 to get the name of a resource file that overrides the global
922 resources stored in the RESOURCE_MANAGER property.
923
925 The latest version of xscreensaver, an online version of this manual,
926 and a FAQ can always be found at https://www.jwz.org/xscreensaver/
927
929 X(1), Xsecurity(1), xauth(1), xdm(1), gdm(1), xhost(1), xscreen‐
930 saver-demo(1), xscreensaver-command(1), xscreensaver-gl-helper(1),
931 xscreensaver-getimage(1), xscreensaver-text(1).
932
934 Copyright © 1991-2019 by Jamie Zawinski. Permission to use, copy, mod‐
935 ify, distribute, and sell this software and its documentation for any
936 purpose is hereby granted without fee, provided that the above copy‐
937 right notice appear in all copies and that both that copyright notice
938 and this permission notice appear in supporting documentation. No rep‐
939 resentations are made about the suitability of this software for any
940 purpose. It is provided "as is" without express or implied warranty.
941
943 Jamie Zawinski <jwz@jwz.org>. Written in late 1991; version 1.0 posted
944 to comp.sources.x on 17-Aug-1992.
945 Please let me know if you find any bugs or make any improvements.
947 And a huge thank you to the hundreds of people who have contributed, in
949 large ways and small, to the xscreensaver collection over the past two
950 decades!
951X Version 11 5.44-2.fc32 (16-Apr-2020) xscreensaver(1)