docs/handbook/X/index.mdwn

   1 # The X Window System
   2
   3
   4 [[!toc  levels=3]]
   5
   6
   7 ## Synopsis
   8
   9 This chapter will cover the usual way of giving your Dragonfly BSD system an X Window style Graphical User Interface (GUI).
  10
  11 This multi-layered approach may be surprising to people coming from systems like Mac or like Windows where these components are not so flexible, or provided by so many separately installed and configured pieces.
  12
  13 Before reading this chapter, you should know how to install additional third-party software. Read the [dports](/docs/howtos/HowToDPorts) section of the documentation. Then install **xorg** meta package or both **xorg-minimal** and **xorg-apps** meta packages instead and **xdm** package (all of them are under `x11` category). Optionally install **cwm** package (it is under `x11-wm` category).
  14
  15 ## Introduction to X
  16
  17 The X Window System (sometimes just called "X") is the environment which provides graphics services to DragonFly BSD and other Unix-based systems. By itself, X provides very little, since one also must have a window manager to present a user interface, i.e. X Server does not provide a way to move and resize windows and does not provide decorations like title bar on the top of windows.  The X11 specification is an open standard, and there are different implementations, some commercial, and some free. [X.org](https://www.x.org/) is the free implementation of the X11 specification.
  18
  19 It is possible to run X clients on a system without any graphical support. For example, one could have an application (the X client) running on an ARM system, displaying its output on an amd64's graphical display (the X server). Since X is a well-defined, cross-platform protocol, it is even possible to have an X application running on (for example) an OpenBSD machine using a DragonFly BSD machine for its display. The client and server can also be running on the same machine, and for most of this section, that will be the assumption.
  20
  21 ## Configuring X
  22
  23 X often requires no configuration at all. You can put your configuration files in /usr/local/etc/X11/ or /usr/local/etc/X11/xorg.conf.d/
  24
  25 Read [xorg.conf(5)](https://leaf.dragonflybsd.org/cgi/web-man?command=xorg.conf&section=5) for more information on configuration files.
  26
  27 Add user running X to video group in order to use 3D acceleration:
  28
  29     # pw groupmod video -m username
  30
  31 ## Starting X
  32
  33 There are two common ways to run X: by manually invoking the [startx(1)](https://leaf.dragonflybsd.org/cgi/web-man?command=startx&section=1) or via [xdm(1)](https://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1).
  34
  35 **Note:** [twm(1)](https://leaf.dragonflybsd.org/cgi/web-man?command=twm&section=1) window manager is started by default.
  36
  37 ### Introduction to X Display Manager
  38
  39 The X Display Manager (XDM) is an optional part of the X Window System that provides services similar to those provided by [init(8)](https://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8), [getty(8)](https://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8) and [login(1)](https://leaf.dragonflybsd.org/cgi/web-man?command=login&section=1) on character terminals: prompting for login name and password, authenticating the user, and running a "session".
  40
  41 ### Running X Display Manager
  42
  43 Manually run `/usr/local/bin/xdm` as root or to run the XDM daemon on a virtual terminal change field 4 from `off` to `on` in `/etc/ttys` file:
  44
  45     ttyv8   "/usr/local/bin/xdm -nodaemon"  xterm   off secure
  46
  47 and restart [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8).
  48
  49 ### Running a Network Display Server
  50
  51 In order for other clients to connect to the display server, edit the access control rules and enable the connection listener. To make XDM listen for connections comment out a line in the `/usr/local/etc/X11/xdm/xdm-config` file:
  52
  53     ! SECURITY: do not listen for XDMCP or Chooser requests
  54     ! Comment out this line if you want to manage X terminals with xdm
  55     DisplayManager.requestPort:     0
  56
  57 and restart [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1). More strict access controls may be desired, so look at the example entries in `/usr/local/etc/X11/xdm/Xaccess`, and refer to the [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1) manual page for further information.
  58
  59 ## Customizing X
  60
  61 When an X session is started, shell scripts in the user's home directory can be used to start as many programs as desired. Most of the programs in these scripts should run in the background, but the last one (typically the window manager) should run in the foreground. When the window manager exits, the script will exit, and X will shut down or return to the [xdm(1)](https://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1) login prompt.
  62
  63 The [startx(1)](https://leaf.dragonflybsd.org/cgi/web-man?command=startx&section=1) command looks for a $HOME/.xinitrc script. If this script doesn't exist, the system's /usr/local/etc/X11/xinit/xinitrc file is used instead.
  64
  65 After the user logs in from [xdm(1)](https://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1), the /usr/local/etc/X11/xdm/Xsession script checks whether there is a $HOME/.xsession script.
  66
  67 In the simplest case, your .xinitrc or .xsession script contains only one line specifying your preferred window manager:
  68
  69     cwm
  70
  71 Or you can get a little more fancy:
  72
  73     export LANG=en_US.UTF-8
  74     setxkbmap -layout us,ru -option grp:sclk_toggle
  75     xconsole -geometry -0+0 -fn 5x7 &
  76     xclock -geometry 75x75-0-0 &
  77     xsetroot -solid grey &
  78     xterm -geometry 100x25-400+250 &
  79     cwm
  80
  81 **Note:** make sure you .xsession file is executable:
  82
  83     % chmod o+x ~/.xsession
  84
  85 ----