1xscreensaver(1)               XScreenSaver manual              xscreensaver(1)
2
3
4

NAME

6       xscreensaver - extensible screen saver and screen locking framework
7

SYNOPSIS

9       xscreensaver  [-display  host:display.screen]  [-verbose]  [-no-splash]
10       [-no-capture-stderr] [-log filename]
11

DESCRIPTION

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
17       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
21       It also provides configuration and control of your monitor's power-sav‐
22       ing features.
23

GETTING STARTED

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
32       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

CONFIGURATION

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
42       I'll repeat that because it's important:
43
44           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
49       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
54       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
66       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
80       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

COMMAND-LINE OPTIONS

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
90       -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
95       -verbose
96               Same as setting the verbose resource to true: print diagnostics
97               on stderr and on the xscreensaver window.
98
99       -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
104       -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

HOW IT WORKS

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
118       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
124       You  can  control  a  running screensaver process by using the xscreen‐
125       saver-command(1) program (which see).
126

POWER MANAGEMENT

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
135       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
141       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
145       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
150       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
156       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

USING GNOME OR UNITY

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
169       To replace gnome-screensaver with xscreensaver:
170
171           1: Fully uninstall the gnome-screensaver package.
172              sudo apt-get remove gnome-screensaver
173              or possibly
174              sudo dpkg -P gnome-screensaver
175
176           2: Launch xscreensaver at login.
177              Select "Startup Applications" from the menu (or manually  launch
178              "gnome-session-properties") and add "xscreensaver".
179
180              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
184           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
194           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

USING KDE

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
204           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
208              Or possibly: Open "System Settings" and select "Screen Locking".
209              Un-check "Lock Screen Automatically".
210
211           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
216              If that doesn't work, then try this:
217
218              Open "System Settings / Startup/Shutdown / Autostart", and  then
219              add "/usr/bin/xscreensaver".
220
221              If  you are lucky, that will create a xscreensaver.desktop" file
222              for you in ~/.config/autostart/ or ~/.kde/Autostart/.
223
224           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
235           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
247       Now use xscreensaver normally, controlling it via  the  usual  xscreen‐
248       saver-demo(1) and xscreensaver-command(1) mechanisms.
249

USING SYSTEMD

251       If  the  above  didn't do it, and your system has systemd(1), then give
252       this a try:
253
254       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
264       2. Enable it.
265          systemctl --user enable xscreensaver
266          Then restart X11.
267

USING UPSTART

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

USING GDM

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
282       On the General page set the Local Greeter to Standard Greeter.
283
284       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
290       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
300       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
305       An  unfortunate  side effect of this (important) security precaution is
306       that it may conflict with cookie-based authentication.
307
308       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

BUGS

315       Bugs?  There are no bugs.  Ok, well, maybe.  If you  find  one,  please
316       let  me  know.  https://www.jwz.org/xscreensaver/bugs.html explains how
317       to construct the most useful bug reports.
318
319       Locking and root logins
320           In order for it to be safe for xscreensaver to be launched by  xdm,
321           certain  precautions  had to be taken, among them that xscreensaver
322           never runs as root.  In particular, if it is launched as  root  (as
323           xdm is likely to do), xscreensaver will disavow its privileges, and
324           switch itself to a safe user id (such as nobody).
325
326           An implication of this is that if you log in as root  on  the  con‐
327           sole, xscreensaver will refuse to lock the screen (because it can't
328           tell the difference between root being logged in  on  the  console,
329           and  a  normal user being logged in on the console but xscreensaver
330           having been launched by the xdm(1) Xsetup file).
331
332           The solution to this is simple: you shouldn't be logging in on  the
333           console  as root in the first place!  (What, are you crazy or some‐
334           thing?)
335
336           Proper Unix hygiene dictates that you should log  in  as  yourself,
337           and  su(1) to root as necessary.  People who spend their day logged
338           in as root are just begging for disaster.
339
340       XAUTH and XDM
341           For xscreensaver to work when launched by xdm(1)  or  gdm(1),  pro‐
342           grams running on the local machine as user "nobody" must be able to
343           connect to the X server.  This  means  that  if  you  want  to  run
344           xscreensaver on the console while nobody is logged in, you may need
345           to disable cookie-based access control (and allow all users who can
346           log in to the local machine to connect to the display).
347
348           You  should  be sure that this is an acceptable thing to do in your
349           environment before doing it.  See the "Using GDM"  section,  above,
350           for more details.
351
352       Passwords
353           If  you get an error message at startup like "couldn't get password
354           of user" then this probably means that you're on a system in  which
355           the  getpwent(3)  library  routine  can only be effectively used by
356           root.  If this is the case, then xscreensaver must be installed  as
357           setuid  to  root in order for locking to work.  Care has been taken
358           to make this a safe thing to do.
359
360           It also may mean that your system uses shadow passwords instead  of
361           the  standard  getpwent(3) interface; in that case, you may need to
362           change some options with configure and recompile.
363
364           If you change your password after xscreensaver has  been  launched,
365           it will continue using your old password to unlock the screen until
366           xscreensaver is restarted.  On some systems,  it  may  accept  both
367           your  old  and  new passwords.  So, after you change your password,
368           you'll have to do
369           xscreensaver-command -restart
370           to make xscreensaver notice.
371
372       PAM Passwords
373           If your system uses PAM (Pluggable Authentication Modules), then in
374           order  for xscreensaver to use PAM properly, PAM must be told about
375           xscreensaver.  The xscreensaver installation process should  update
376           the  PAM  data  (on Linux, by creating the file /etc/pam.d/xscreen‐
377           saver for you, and on Solaris, by telling you what lines to add  to
378           the /etc/pam.conf file).
379
380           If the PAM configuration files do not know about xscreensaver, then
381           you might be in a situation where xscreensaver will refuse to  ever
382           unlock the screen.
383
384           This  is a design flaw in PAM (there is no way for a client to tell
385           the difference between PAM responding "I have never heard  of  your
386           module",  and  responding, "you typed the wrong password").  As far
387           as I can tell, there is no way for  xscreensaver  to  automatically
388           work  around this, or detect the problem in advance, so if you have
389           PAM, make sure it is configured correctly!
390
391       Machine Load
392           Although this program "nices"  the  subprocesses  that  it  starts,
393           graphics-intensive  subprograms  can  still overload the machine by
394           causing the X server process itself (which is not "niced") to  con‐
395           sume  many  cycles.  Care has been taken in all the modules shipped
396           with xscreensaver to sleep periodically, and not run full tilt,  so
397           as not to cause appreciable load.
398
399           However,  if  you  are  running the OpenGL-based screen savers on a
400           machine that does not have a video card with 3D acceleration,  they
401           will make your machine slow, despite nice(1).
402
403           Your  options  are: don't use the OpenGL display modes; or, collect
404           the spare change hidden under the cushions of your couch,  and  use
405           it  to  buy a video card manufactured after 1998.  (It doesn't even
406           need to be fast 3D hardware: the problem will be fixed if there  is
407           any 3D hardware at all.)
408
409       Magic Backdoor Keystrokes
410           The  XFree86  X server and the Linux kernel both trap certain magic
411           keystrokes before X11 client programs ever see them.  If  you  care
412           about keeping your screen locked, this is a big problem.
413
414           Ctrl+Alt+Backspace
415              This  keystroke  kills the X server, and on some systems, leaves
416              you at a text console.  If the user launched X11 manually,  that
417              text console will still be logged in.  To disable this keystroke
418              globally and permanently, you need to set the  DontZap  flag  in
419              your  xorg.conf  or  XF86Config  or XF86Config-4 file, depending
420              which is in use on your system.  See XF86Config(5) for details.
421
422           Ctrl-Alt-F1, Ctrl-Alt-F2, etc.
423              These keystrokes will switch to  a  different  virtual  console,
424              while leaving the console that X11 is running on locked.  If you
425              left a shell logged in on another virtual console, it is  unpro‐
426              tected.   So  don't  leave yourself logged in on other consoles.
427              You can disable VT switching globally and permanently by setting
428              DontVTSwitch  in your xorg.conf, but that might make your system
429              harder to use, since VT switching is an actual useful feature.
430
431              There is no way to disable VT switching only when the screen  is
432              locked.  It's all or nothing.
433
434           Ctrl-Alt-KP_Multiply
435              This  keystroke  kills  any X11 app that holds a lock, so typing
436              this will kill xscreensaver and unlock  the  screen.   This  so-
437              called  "feature"  showed  up in the X server in 2008, and as of
438              2011, some vendors are shipping it turned on  by  default.   How
439              nice.   You can disable it by turning off AllowClosedownGrabs in
440              xorg.conf.
441
442           Alt-SysRq-F
443              This is the Linux kernel "OOM-killer" keystroke.  It shoots down
444              random long-running programs of its choosing, and so might might
445              target and kill xscreensaver, and there's no  way  for  xscreen‐
446              saver  to protect itself from that.  You can disable it globally
447              with:
448              echo 176 > /proc/sys/kernel/sysrq
449       There's little that I can do to make the screen  locker  be  secure  so
450       long  as  the  kernel  and  X11 developers are actively working against
451       security like this.  The strength  of  the  lock  on  your  front  door
452       doesn't  matter  much  so  long as someone else in the house insists on
453       leaving a key under the welcome mat.
454
455       Dangerous Backdoor Server Extensions
456           Many distros enable by default several X11 server  extensions  that
457           can  be  used  to  bypass grabs, and thus snoop on you while you're
458           typing your password.  These extensions are nominally for debugging
459           and  automation, but they are also security-circumventing keystroke
460           loggers.  If your server is configured to load the RECORD, XTRAP or
461           XTEST  extensions, you absolutely should disable those, 100% of the
462           time.  Look for them in xorg.conf or whatever it is called.
463

X RESOURCES

465       These are the X resources use by the xscreensaver program.  You  proba‐
466       bly  won't  need  to  change  these  manually (that's what the xscreen‐
467       saver-demo(1) program is for).
468
469       timeout (class Time)
470               The screensaver will activate (blank the screen) after the key‐
471               board  and mouse have been idle for this many minutes.  Default
472               10 minutes.
473
474       cycle (class Time)
475               After the screensaver has been running for this  many  minutes,
476               the  currently running graphics-hack sub-process will be killed
477               (with SIGTERM), and a new one started.  If this is 0, then  the
478               graphics  hack  will  never  be changed: only one demo will run
479               until the screensaver is deactivated by user activity.  Default
480               10 minutes.
481
482               The  running  saver  will be restarted every cycle minutes even
483               when mode is one, since some  savers  tend  to  converge  on  a
484               steady state.
485
486       lock (class Boolean)
487               Enable  locking:  before the screensaver will turn off, it will
488               require you to type the password of the logged-in user (really,
489               the person who ran xscreensaver), or the root password.  (Note:
490               this doesn't work if the  screensaver  is  launched  by  xdm(1)
491               because  it  can't know the user-id of the logged-in user.  See
492               the "Using XDM(1)" section, below.
493
494       lockTimeout (class Time)
495               If locking is enabled, this controls the length of  the  "grace
496               period"  between  when  the screensaver activates, and when the
497               screen becomes locked.  For example, if this is 5, and -timeout
498               is 10, then after 10 minutes, the screen would blank.  If there
499               was user activity at 12 minutes, no password would be  required
500               to  un-blank the screen.  But, if there was user activity at 15
501               minutes or later (that is, -lock-timeout minutes after  activa‐
502               tion)  then  a  password  would be required.  The default is 0,
503               meaning that if locking is enabled, then  a  password  will  be
504               required as soon as the screen blanks.
505
506       passwdTimeout (class Time)
507               If  the  screen  is  locked,  then this is how many seconds the
508               password dialog box should be left on the screen before  giving
509               up  (default  30 seconds).  This should not be too large: the X
510               server is grabbed for the duration that the password dialog box
511               is  up  (for  security purposes) and leaving the server grabbed
512               for too long can cause problems.
513
514       dpmsEnabled (class Boolean)
515               Whether power management is enabled.
516
517       dpmsStandby (class Time)
518               If power management is enabled, how long until the monitor goes
519               solid black.
520
521       dpmsSuspend (class Time)
522               If power management is enabled, how long until the monitor goes
523               into power-saving mode.
524
525       dpmsOff (class Time)
526               If power management is enabled, how long until the monitor pow‐
527               ers  down  completely.   Note  that these settings will have no
528               effect unless both the X server and the display  hardware  sup‐
529               port  power  management;  not all do.  See the Power Management
530               section, below, for more information.
531
532       dpmsQuickOff (class Boolean)
533               If mode is blank and this is true, then the screen will be pow‐
534               ered down immediately upon blanking, regardless of other power-
535               management settings.
536
537       visualID (class VisualID)
538               This is an historical artifacts left over from when 8-bit  dis‐
539               plays were still common.  You should probably ignore this.
540
541               Specify which X visual to use by default.  (Note carefully that
542               this resource is called visualID, not merely visual; if you set
543               the visual resource instead, things will malfunction in obscure
544               ways for obscure reasons.)
545
546               Legal values for the VisualID resource are:
547
548               default Use the screen's default visual (the visual of the root
549                       window).  This is the default.
550
551               best    Use  the  visual which supports the most colors.  Note,
552                       however, that the visual with the most colors might  be
553                       a  TrueColor  visual,  which  does not support colormap
554                       animation.  Some programs have more interesting  behav‐
555                       ior when run on PseudoColor visuals than on TrueColor.
556
557               mono    Use a monochrome visual, if there is one.
558
559               gray    Use  a  grayscale or staticgray visual, if there is one
560                       and it has more than one plane (that is, it's not mono‐
561                       chrome).
562
563               color   Use the best of the color visuals, if there are any.
564
565               GL      Use  the  visual  that  is  best  for  OpenGL programs.
566                       (OpenGL programs have somewhat  different  requirements
567                       than other X programs.)
568
569               class   where  class  is  one of StaticGray, StaticColor, True‐
570                       Color, GrayScale, PseudoColor, or DirectColor.  Selects
571                       the deepest visual of the given class.
572
573               number  where  number (decimal or hex) is interpreted as a vis‐
574                       ual id number, as reported by the xdpyinfo(1)  program;
575                       in  this  way  you  can have finer control over exactly
576                       which visual gets used, for example, to select a  shal‐
577                       lower one than would otherwise have been chosen.
578
579               Note  that  this  option specifies only the default visual that
580               will be used: the visual used may be overridden on  a  program-
581               by-program   basis.    See  the  description  of  the  programs
582               resource, below.
583
584       installColormap (class Boolean)
585               On PseudoColor (8-bit) displays,  install  a  private  colormap
586               while the screensaver is active, so that the graphics hacks can
587               get as many colors as possible.  This is  the  default.   (This
588               only  applies  when  the screen's default visual is being used,
589               since non-default visuals get  their  own  colormaps  automati‐
590               cally.)   This  can also be overridden on a per-hack basis: see
591               the discussion of the default-n name in the section  about  the
592               programs resource.
593
594               This  does  nothing  if you have a TrueColor (16-bit or deeper)
595               display.  (Which, in this century, you do.)
596
597       verbose (class Boolean)
598               Whether to print diagnostics.  Default false.
599
600       timestamp (class Boolean)
601               Whether to print the time of day along with any other  diagnos‐
602               tic messages.  Default true.
603
604       splash (class Boolean)
605               Whether to display a splash screen at startup.  Default true.
606
607       splashDuration (class Time)
608               How  long  the  splash  screen should remain visible; default 5
609               seconds.
610
611       helpURL (class URL)
612               The splash screen has a Help button on it.  When you press  it,
613               it  will  display  the  web  page  indicated  here  in your web
614               browser.
615
616       loadURL (class LoadURL)
617               This is the shell command used to load  a  URL  into  your  web
618               browser.   The  default  setting will load it into Mozilla/Net‐
619               scape if it is already running, otherwise, will  launch  a  new
620               browser looking at the helpURL.
621
622       demoCommand (class DemoCommand)
623               This  is  the  shell  command  run  when the Demo button on the
624               splash window is pressed.  It defaults to xscreensaver-demo(1).
625
626       prefsCommand (class PrefsCommand)
627               This is the shell command run when  the  Prefs  button  on  the
628               splash   window   is   pressed.    It   defaults   to  xscreen‐
629               saver-demo -prefs.
630
631       newLoginCommand (class NewLoginCommand)
632               If set, this is the shell command that is  run  when  the  "New
633               Login"  button is pressed on the unlock dialog box, in order to
634               create a new desktop session without logging out the  user  who
635               has  locked the screen.  Typically this will be some variant of
636               gdmflexiserver(1), kdmctl(1), lxdm(1) or dm-tool(1).
637
638       nice (class Nice)
639               The sub-processes created by xscreensaver will  be  "niced"  to
640               this  level,  so  that they are given lower priority than other
641               processes on the system, and don't increase the  load  unneces‐
642               sarily.   The default is 10.  (Higher numbers mean lower prior‐
643               ity; see nice(1) for details.)
644
645       fade (class Boolean)
646               If this is true, then when the screensaver activates, the  cur‐
647               rent  contents of the screen will fade to black instead of sim‐
648               ply winking out.  This only works on certain systems.   A  fade
649               will also be done when switching graphics hacks (when the cycle
650               timer expires).  Default: true.
651
652       unfade (class Boolean)
653               If this is true, then when  the  screensaver  deactivates,  the
654               original contents of the screen will fade in from black instead
655               of appearing immediately.  This only works on certain  systems,
656               and if fade is true as well.  Default false.
657
658       fadeSeconds (class Time)
659               If  fade  is true, this is how long the fade will be in seconds
660               (default 3 seconds).
661
662       fadeTicks (class Integer)
663               If fade is true, this is how many times a second  the  colormap
664               will  be  changed  to  effect  a  fade.   Higher  numbers yield
665               smoother fades, but may make the fades  take  longer  than  the
666               specified  fadeSeconds if your server isn't fast enough to keep
667               up.  Default 20.
668
669       captureStderr (class Boolean)
670               Whether xscreensaver should  redirect  its  stdout  and  stderr
671               streams to the window itself.  Since its nature is to take over
672               the screen, you would not normally see error messages generated
673               by xscreensaver or the sub-programs it runs; this resource will
674               cause the output of all relevant programs to be  drawn  on  the
675               screensaver window itself, as well as being written to the con‐
676               trolling terminal of the screensaver driver  process.   Default
677               true.
678
679       ignoreUninstalledPrograms (class Boolean)
680               There may be programs in the list that are not installed on the
681               system, yet are marked as "enabled".   If  this  preference  is
682               true,  then  such  programs  will simply be ignored.  If false,
683               then a warning will be printed if an attempt is made to run the
684               nonexistent  program.   Also,  the xscreensaver-demo(1) program
685               will suppress the non-existent programs from the list  if  this
686               is true.  Default: false.
687
688       authWarningSlack (class Integer)
689               If all failed unlock attempts (incorrect password entered) were
690               made within this period of time, the usual  dialog  that  warns
691               about  such  attempts  after  a  successful  login will be sup‐
692               pressed. The assumption is  that  incorrect  passwords  entered
693               within  a  few  seconds of a correct one are user error, rather
694               than hostile action.  Default 20 seconds.
695
696       GetViewPortIsFullOfLies (class Boolean)
697               Set this to true if the xscreensaver window doesn't  cover  the
698               whole  screen.   This  works  around a longstanding XFree86 bug
699               #421.  See the xscreensaver FAQ for details.
700
701       font (class Font)
702               The font used for the stdout/stderr text, if  captureStderr  is
703               true.   Default  *-medium-r-*-140-*-m-* (a 14 point fixed-width
704               font).
705
706       mode (class Mode)
707               Controls the behavior of xscreensaver.  Legal values are:
708
709               random  When blanking the screen, select a random display  mode
710                       from among those that are enabled and applicable.  This
711                       is the default.
712
713               random-same
714                       Like random, but if there are  multiple  screens,  each
715                       screen  will  run the same random display mode, instead
716                       of each screen running a different one.
717
718               one     When blanking the screen, only ever use one  particular
719                       display  mode  (the  one indicated by the selected set‐
720                       ting).
721
722               blank   When blanking the screen, just go black: don't run  any
723                       graphics hacks.
724
725               off     Don't  ever  blank the screen, and don't ever allow the
726                       monitor to power down.
727
728
729       selected (class Integer)
730               When mode is set to one, this is  the  one,  indicated  by  its
731               index in the programs list.  You're crazy if you count them and
732               set this number by hand: let  xscreensaver-demo(1)  do  it  for
733               you!
734
735       programs (class Programs)
736               The  graphics  hacks  which  xscreensaver runs when the user is
737               idle.  The value of this resource is a multi-line  string,  one
738               sh-syntax command per line.  Each line must contain exactly one
739               command: no semicolons, no ampersands.
740
741               When the screensaver  starts  up,  one  of  these  is  selected
742               (according  to  the  mode  setting),  and run.  After the cycle
743               period expires, it is killed, and another is selected and run.
744
745               If a line begins with a dash (-) then that  particular  program
746               is  disabled:  it  won't  be selected at random (though you can
747               still select it explicitly using the xscreensaver-demo(1)  pro‐
748               gram).
749
750               If all programs are disabled, then the screen will just be made
751               blank, as when mode is set to blank.
752
753               To disable a program, you must mark it as disabled with a  dash
754               instead of removing it from the list.  This is because the sys‐
755               tem-wide (app-defaults) and per-user  (.xscreensaver)  settings
756               are  merged  together, and if a user just deletes an entry from
757               their programs list, but that entry still exists in the system-
758               wide  list,  then it will come back.  However, if the user dis‐
759               ables it, then their setting takes precedence.
760
761               If the display has multiple screens, then a  different  program
762               will  be  run  for  each  screen.  (All screens are blanked and
763               unblanked simultaneously.)
764
765               Note that you must escape the newlines; here is an  example  of
766               how you might set this in your ~/.xscreensaver file:
767
768               programs:  \
769                      qix -root                          \n\
770                      ico -r -faces -sleep 1 -obj ico    \n\
771                      xdaliclock -builtin2 -root         \n\
772                      xv -root -rmode 5 image.gif -quit  \n
773               Make  sure  your $PATH environment variable is set up correctly
774               before xscreensaver is launched, or it won't be  able  to  find
775               the programs listed in the programs resource.
776
777               To  use  a  program  as a screensaver, two things are required:
778               that that program draw on the root window (or  be  able  to  be
779               configured  to  draw on the root window); and that that program
780               understand "virtual root" windows, as used  by  virtual  window
781               managers such as tvtwm(1).  (Generally, this is accomplished by
782               just including the  "vroot.h"  header  file  in  the  program's
783               source.)
784
785               Visuals:
786
787               Because xscreensaver was created back when dinosaurs roamed the
788               earth, it still contains support for some things you've  proba‐
789               bly  never  seen,  such as 1-bit monochrome monitors, grayscale
790               monitors, and monitors capable of displaying  only  8-bit  col‐
791               ormapped images.
792
793               If there are some programs that you want to run only when using
794               a color display, and others that you  want  to  run  only  when
795               using a monochrome display, you can specify that like this:
796                      mono:   mono-program  -root        \n\
797                      color:  color-program -root        \n\
798               More  generally, you can specify the kind of visual that should
799               be used for the window on which the program  will  be  drawing.
800               For  example,  if  one program works best if it has a colormap,
801               but another works best if it has a 24-bit visual, both  can  be
802               accommodated:
803                      PseudoColor: cmap-program  -root   \n\
804                      TrueColor:   24bit-program -root   \n\
805               In  addition  to  the symbolic visual names described above (in
806               the discussion of the visualID resource) one other visual  name
807               is supported in the programs list:
808
809                default-n
810                    This  is  like  default,  but also requests the use of the
811                    default colormap, instead of a  private  colormap.   (That
812                    is,  it  behaves as if the -no-install command-line option
813                    was specified, but only for this particular  hack.)   This
814                    is provided because some third-party programs that draw on
815                    the root  window  (notably:  xv(1),  and  xearth(1))  make
816                    assumptions about the visual and colormap of the root win‐
817                    dow: assumptions which xscreensaver can violate.
818
819               If you specify a particular visual for a program, and that vis‐
820               ual does not exist on the screen, then that program will not be
821               chosen to run.  This  means  that  on  displays  with  multiple
822               screens  of  different  depths, you can arrange for appropriate
823               hacks to be run on each.  For example, if one screen  is  color
824               and  the  other is monochrome, hacks that look good in mono can
825               be run on one, and hacks that only look good in color will show
826               up on the other.
827
828       You shouldn't ever need to change the following resources:
829
830       pointerPollTime (class Time)
831               When  server  extensions are not in use, this controls how fre‐
832               quently xscreensaver checks to see if  the  mouse  position  or
833               buttons have changed.  Default 5 seconds.
834
835       pointerHysteresis (class Integer)
836               If  the  mouse  moves  less  than this-many pixels in a second,
837               ignore it (do not consider that to be "activity").  This is  so
838               that  the  screen  doesn't  un-blank  (or  fail  to blank) just
839               because you bumped the desk.  Default: 10 pixels.
840
841       windowCreationTimeout (class Time)
842               When server extensions are not in use, this controls the  delay
843               between  when windows are created and when xscreensaver selects
844               events on them.  Default 30 seconds.
845
846       initialDelay (class Time)
847               When server extensions are not in use, xscreensaver  will  wait
848               this  many seconds before selecting events on existing windows,
849               under the assumption that xscreensaver is started  during  your
850               login  procedure, and the window state may be in flux.  Default
851               0.  (This used to default to 30, but that was back in the  days
852               when slow machines and X terminals were more common...)
853
854       procInterrupts (class Boolean)
855               This resource controls whether the /proc/interrupts file should
856               be consulted to decide whether the user is idle.  This  is  the
857               default  if  xscreensaver  has  been compiled on a system which
858               supports this mechanism (i.e., Linux systems).
859
860               The benefit to doing this is that xscreensaver  can  note  that
861               the  user  is  active even when the X console is not the active
862               one: if the user is typing in another virtual console, xscreen‐
863               saver will notice that and will fail to activate.  For example,
864               if you're playing Quake in VGA-mode, xscreensaver won't wake up
865               in the middle of your game and start competing for CPU.
866
867               The  drawback  to doing this is that perhaps you really do want
868               idleness on the X console to cause the X display to lock,  even
869               if  there  is  activity on other virtual consoles.  If you want
870               that, then set this option to False.  (Or just lock the X  con‐
871               sole manually.)
872
873               The  default  value for this resource is True, on systems where
874               it works.
875
876       overlayStderr (class Boolean)
877               If captureStderr is True, and your  server  supports  "overlay"
878               visuals,  then  the text will be written into one of the higher
879               layers instead of into the same layer as  the  running  screen‐
880               hack.   Set this to False to disable that (though you shouldn't
881               need to).
882
883       overlayTextForeground (class Foreground)
884               The foreground color used for the stdout/stderr text,  if  cap‐
885               tureStderr is true.  Default: Yellow.
886
887       overlayTextBackground (class Background)
888               The  background  color used for the stdout/stderr text, if cap‐
889               tureStderr is true.  Default: Black.
890
891       bourneShell (class BourneShell)
892               The pathname of the shell that xscreensaver uses to start  sub‐
893               processes.  This must be whatever your local variant of /bin/sh
894               is: in particular, it must not be csh.
895

ENVIRONMENT

897       DISPLAY to get the default host and display number, and to  inform  the
898               sub-programs of the screen on which to draw.
899
900       XSCREENSAVER_WINDOW
901               Passed  to  sub-programs  to  indicate  the ID of the window on
902               which they should draw.  This is  necessary  on  Xinerama/RANDR
903               systems  where  multiple  physical  monitors share a single X11
904               "Screen".
905
906       PATH    to find the sub-programs to run.
907
908       HOME    for the directory in which to read the .xscreensaver file.
909
910       XENVIRONMENT
911               to get the name of a resource file that  overrides  the  global
912               resources stored in the RESOURCE_MANAGER property.
913

UPGRADES

915       The  latest  version of xscreensaver, an online version of this manual,
916       and a FAQ can always be found at https://www.jwz.org/xscreensaver/
917

SEE ALSO

919       X(1),  Xsecurity(1),  xauth(1),  xdm(1),  gdm(1),  xhost(1),   xscreen‐
920       saver-demo(1),    xscreensaver-command(1),   xscreensaver-gl-helper(1),
921       xscreensaver-getimage(1), xscreensaver-text(1).
922
924       Copyright © 1991-2018 by Jamie Zawinski.  Permission to use, copy, mod‐
925       ify,  distribute,  and sell this software and its documentation for any
926       purpose is hereby granted without fee, provided that  the  above  copy‐
927       right  notice  appear in all copies and that both that copyright notice
928       and this permission notice appear in supporting documentation.  No rep‐
929       resentations  are  made  about the suitability of this software for any
930       purpose.  It is provided "as is" without express or implied warranty.
931

AUTHOR

933       Jamie Zawinski <jwz@jwz.org>.  Written in late 1991; version 1.0 posted
934       to comp.sources.x on 17-Aug-1992.
935
936       Please let me know if you find any bugs or make any improvements.
937
938       And a huge thank you to the hundreds of people who have contributed, in
939       large ways and small, to the xscreensaver collection over the past  two
940       decades!
941
942
943
944X Version 11               5.42-1.fc29 (30-Dec-2018)           xscreensaver(1)
Impressum