File:  [NetBSD Developer Wiki] / wikisrc / guide / x.mdwn
Revision 1.2: download - view: text, annotated - select for diffs
Thu Mar 21 11:11:21 2013 UTC (5 years, 3 months ago) by jdf
Branches: MAIN
CVS tags: HEAD
Add TOCs to all chapters.


[[!toc levels=3]]

# X

## What is X?

NetBSD uses the X Window System (often referred as X11) to provide a graphical
interface. In NetBSD 5.0, the amd64, i386, macppc, shark, sgimips, and sparc64
ports use X.Org and the rest use XFree86.

Please note that the X Window System is a rather bare bones framework. It acts
as a base for modern desktop environments like GNOME or KDE, but they are not
part of the X Window System. NetBSD ships with the X Window System, but it does
not include these desktop environments; they must be added via pkgsrc.

When you start using X you'll find many new terms which you may find confusing
at first. The basic elements are:

 * *Video hardware*, i.e., your video card.
 * An *X server* running on top of the hardware. The X server provides a
   standard way to display graphics (including fonts for text display) and get
   mouse/keyboard/other input. X is network-transparent, which means that you
   can run X clients on one machine, and the X server (i.e., the display, with
   video hardware) on another machine.
 * *X clients*. These are the programs you directly interact with. They run on
   top of the X server. A web browser like Firefox is an example of an X client.
 * A *window manager* running on top of the X server. The window manager is a
   special X client that is allowed to control the placement of windows. It can
   also *decorate* windows with standard *widgets* (usually these provide
   actions like window motion, resizing, iconifying, window killing, etc.).
 * A *desktop environment* such as GNOME or KDE. These are suites of integrated
   software designed to give you a well-defined range of software and a more or
   less common interface to each program. These typically include a window
   manager, file manager, web browser, email client, multimedia player, text
   editor, address book, help browser, etc. As you may have guessed, a desktop
   environment is not needed to use X, but many users will want to install one.

## Configuration

In some cases, you may be able to start using X without any configuration at
all, and **startx** will work just fine. In many cases, however, some
configuration of the X server is required. Depending on the port you use, this
configuration file will be either `/etc/X11/xorg.conf` (for platforms using or `/etc/X11/XF86Config` (for those using XFree86). The structure of the
configuration file is described formally in

To generate an initial configuration file for your X server, run the command

    # X -configure

This command should create a configuration file and place it in your home
directory. To test the generated configuration file, run, e.g.,

    # X -config ~/

If this succeeds, you should see a crosshatched background and a cursor in the
shape of an X. Try moving the cursor around to verify that the mouse is
functional. To quit, press `Ctrl-Alt-Backspace`.

If the above test was successful, move the file into place (as either
`/etc/X11/xorg.conf` or `/etc/X11/XF86Config`) and you are ready to go. The
following sections may be of interest or use, but are not required reading.

## The mouse

PS/2 and USB mice will normally be autodetected, and a configuration entry like
the following will be generated:

    Section "InputDevice"
            Identifier  "Mouse0"
            Driver      "mouse"
            Option      "Protocol" "wsmouse"
            Option      "Device" "/dev/wsmouse"
            Option      "ZAxisMapping" "4 5 6 7"

For a serial mouse on the first serial port, try something like:

    Section "InputDevice"
            Identifier  "Mouse0"
            Driver      "mouse"
            Option      "Protocol" "auto"
            Option      "Device" "/dev/tty00"

In this example. `/dev/tty00` is the first serial port. Use `/dev/tty01` for the
second, and so on. Protocol `auto` will try to automatically detect the protocol
of your serial mouse. If this doesn't work, try values like `Microsoft`,
`IntelliMouse` or `Logitech`. See
for more information.

## The keyboard

Even if you have already configured your keyboard for wscons (see
[[wscons|guide/cons#wscons]]), you need to configure it for X as well, at
least if you want to use a non-US layout.

An easy solution is to use the XKB protocol to specify the keyboard type and

Here is an example that shows how to use a German keyboard:

    Section "InputDevice"
            Identifier  "Keyboard0"
            Driver      "kbd"
            Option      "XkbRules" "xorg"
            Option      "XkbModel" "pc105"
            Option      "XkbLayout" "de"
            Option      "XkbOptions" "ctrl:nocaps"

If you wish to change the repeat rate of your keyboard, you can set it with the
`AutoRepeat` option, which takes two arguments: delay and rate, respectively.
The following example sets the initial delay to 200 milliseconds and the repeat
rate to 30 per second:

    Option      "AutoRepeat"    "200 30"

If X is already running, the keyboard repeat rate can be changed with the

    $ xset r 200 30

You can also run this command in your `.xinitrc` file. See below ([[Customizing
X|guide/x#customizing]]) for more information.

## The monitor

If X does not run at the resolution you think it should, first run **xrandr**
and see if the resolution you want is listed. If your preferred resolution is
listed in that command's output, you can change resolutions with, e.g.,

    $ xrandr -s 1680x1050

If your preferred resolution is not listed, or you have issues with flickering,
you may need to manually specify your monitor's horizontal and vertical
frequencies. These can be set with the `HorizSync` and `VertRefresh` directives
in the `Monitor` section. An example is provided below.

    Section "Monitor"
            Identifier   "Monitor0"
            VendorName   "Monitor Vendor"
            ModelName    "Monitor Model"
            HorizSync    30-83
            VertRefresh  56-75

Possible values for your specific monitor can often be found in the manual,
sometimes even on the monitor itself.

## The video card

Normally, your video card will be automatically detected. In the event that this
autodetection fails, all available drivers can be found in
`/usr/X11R7/lib/modules/drivers`. (Replace `X11R7` with `X11R6` if you use a
port that has not yet switched to X.Org.) The driver can be set with the
`Driver` directive in the `Device` section, as shown below.

    Section "Device"
            Identifier  "Card0"
            Driver      "intel"

## Starting X

You can start X with the following command:

    $ startx

If your basic X server configuration is correct, you are left in the X
environment with the default window manager (twm). If you want a more advanced
window manager or desktop environment, many are available in pkgsrc. See [[Other
window managers or desktop
environments|guide/x#other_window_managers_or_desktop_environments]] for
information about adding and changing window managers.

## Customizing X

One of the first things you will want to do is to change the programs that run
when X is first started. The easiest way to do this is to copy the default
`.xinitrc` file to your home directory and modify it, or create a simple new one
from scratch. For example:

    $ cp /etc/X11/xinit/xinitrc ~/.xinitrc
    $ vi ~/.xinitrc

The following example shows how to start the window manager (twm) and open an
instance of the xclock and xterm programs. The screen background color is set to
`bisque4`, which is defined in `/usr/X11R7/lib/X11/rgb.txt`.

    # start some nice programs
    xclock -geometry 50x50-1-1 &
    xsetroot -solid bisque4 &
    xterm -geometry 80x34-1+1 -bg OldLace &
    exec twm    # no '&' here

With this type of setup, to quit X you must exit the window manager, which is
usually done by selecting `exit` from its menu.

The above example is very simple, but illustrates the basics of controlling the
clients that are run when X is started. You can run any number of commands from
your `.xinitrc`, including basic X configuration commands like **xset b off** to
turn off the bell.

## Other window managers or desktop environments

If you don't like twm, which is a very simple window manager, you can install
another window manager or a desktop environment from pkgsrc. The following
example uses the Openbox window manager, but there are many others available in

Openbox can be installed via binary packages or compiled with pkgsrc. As always,
assuming a properly set `PKG_PATH`, the binary package method is:

    # pkg_add -v openbox

Or, with pkgin:

    # pkgin install openbox

To build it with pkgsrc, run:

    # cd /usr/pkgsrc/wm/openbox
    # make install

Openbox is now installed; to start it you must modify your `.xinitrc` file:
substitute the line which calls `twm` with a line which calls `openbox`. For

    # start some useful programs
    xclock -geometry 50x50-1-1 &
    # start window manager:
    exec openbox   # no '&' here

The [startx(1)](
command will start the X11 session with Openbox. As configured in the example
`.xinitrc` file above, choosing `Exit` or similar from the window manager's menu
will quit the window manager and end the X11 session.

Installing a desktop environment is almost as easy. The following example shows
how to use the Xfce desktop environment.

    # pkg_add -v xfce4
    # cp /usr/pkg/share/examples/rc.d/famd /etc/rc.d
    # cp /usr/pkg/share/examples/rc.d/dbus /etc/rc.d
    # cp /usr/pkg/share/examples/rc.d/hal /etc/rc.d
    # echo rpcbind=YES >> /etc/rc.conf
    # echo famd=YES >> /etc/rc.conf
    # echo dbus=YES >> /etc/rc.conf
    # echo hal=YES >> /etc/rc.conf
    # /etc/rc.d/rpcbind start
    # /etc/rc.d/famd start
    # /etc/rc.d/dbus start
    # /etc/rc.d/hal start

After running the above commands, edit your `.xinitrc` as above and change
`openbox` (or `twm`) to `xfce4-session`. The next time you run `startx`, the
Xfce desktop environment will be started.

## Graphical login with xdm

If you always use X and the first thing you do after you log in is run `startx`,
you can set up a graphical login to do this automatically. It is very easy:

 1. Create the `.xsession` file in your home directory. This file is similar to
    `.xinitrc` and can, in fact, be a link to it.

        $ ln -s .xinitrc ~/.xsession

 2. Modify `/etc/rc.conf`, adding the following line:

        xdm=YES       # x11 display manager

 3. Start xdm (or reboot your system, as this will be done automatically from
    now on):

        # /etc/rc.d/xdm start

The configuration files for xdm are in the `/etc/X11/xdm` directory. The
`Xservers` file specifies the virtual console that X is started on. It defaults
to `vt05`, which is the console you reach via `Ctrl+Alt+F5`. If you want to use
a different virtual console, change vt05 as desired. In order to avoid keyboard
contention between getty and xdm, be sure to start xdm on a virtual terminal
where getty is disabled. For example, if in `Xservers` you have:

    :0 local /usr/X11R6/bin/X :0 vt04

Then, in `/etc/ttys` you should have:

    ttyE3   "/usr/libexec/getty Pc"         vt220   off secure

(Please note that `vt04` corresponds to `ttyE3`; In `/etc/X11/xdm/Xservers`,
numbering starts at 1, but in `/etc/ttys`, numbering starts at 0).

If you want to change the look of your xdm login screen, you can modify the xdm
configuration file. For example, to change the background color you can add the
following line to the `Xsetup_0` file:

    xsetroot -solid SeaGreen

CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb