NetBSD uses the X Window System to provide a graphical interface.

Please note that the X Window System is a rather bare bones framework. It acts as a base for modern desktop environments like MATE, or Xfce, 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:

The X Window System is included with NetBSD as separate distribution sets, see Section 3.10, “Installation type”. It can be added to an installed system with sysinst(8).

On NetBSD, X11 lives under the filesystem hierarchy /usr/X11R7. Therefore, to use X, /usr/X11R7/bin must be in your shell's PATH. See ~/.profile.

In most cases, you will be able to start using X without any configuration at all, and startx will work just fine.

In rare cases, however, configuration of the X server is required. This configuration file is located at /etc/X11/xorg.conf. The structure of the configuration file is described formally in xorg.conf(5).

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 ~/xorg.conf.new

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. You can then switch to another virtual terminal (Ctrl-Alt-F#) or log in remotely and kill the X process.

If the above test was successful, move the file into place as /etc/X11/xorg.conf and you are ready to go.

Even if you have already configured your keyboard for wscons (see Section 8.1, “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 setxkbmap(1) .

Here is an example that shows how to use a Hebrew keyboard, with Ctrl-Alt used to switch layouts, and with the position of the Escape and Caps Lock keys swapped as an additional option:

setxkbmap -option grp:alt_shift_toggle us,il \
 -option caps:swapescape -option terminate:ctrl_alt_bksp

If you wish to change the repeat rate of your keyboard, you can set it with the xset(1) command, 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:

$ xset r 200 30

You can also run this command in your .xinitrc or .xsession file. See below (Section 9.6, “Customizing X”) for more information.

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

xrandr can also be used to enable output to hot-plugged monitors.

Managing outputs can be done graphically with the pkgsrc package x11/arandr.

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 (ctwm). If you want a more advanced window manager or desktop environment, many are available in pkgsrc. See Section 9.7, “Other window managers or desktop environments” for information about adding and changing window managers.

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
$ chmod u+w ~/.xinitrc
$ vi ~/.xinitrc

If you use xdm(1), ~/.xsession is used in place of ~/.xinitrc.

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

...
# start some programs - a basic clcok
xclock -geometry 50x50-1-1 &
# change the color of the "root window" ("desktop background")
xsetroot -solid bisque4 &
# spawn a terminal
uxterm -geometry 80x34-1+1 -bg OldLace &
exec ctwm -W   # 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.

If you don't like ctwm, 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 pkgsrc/wm.

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

# pkgin in 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 ctwm with a line which calls openbox. For example:

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

The startx command will start the X11 session with Openbox. As configured in the example .xinitrc file above, choosing “Log Out” from Openbox's menu will end the X11 session.

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

# pkgin in xfce4

Depending on your requirements, you may wish to enable dbus as a system-wide service. The following example demonstates how. (If you don't enable dbus to run as a system-wide service, startxfce4 will start dbus under your user account during initialization.)

# cp /usr/pkg/share/examples/rc.d/dbus /etc/rc.d
# echo dbus=YES >> /etc/rc.conf
# service dbus start

If you wish to be able to control your system's power state from within the desktop, the account you intend to run X under must also be a member of the “operator” group (see Section 5.6, “Adding users”).

After running the above commands, edit your .xinitrc as above and change “openbox” (or “ctwm”) to “startxfce4”. The next time you run startx the Xfce desktop environment will be started.

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:

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/X11R7/bin/X :0 vt04

then in /etc/ttys you should have

ttyE3   "/usr/libexec/getty Pc"         wsvt25   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 are using xdm to start various modern desktop environments, such as Xfce or MATE, you will need to override its default permitted authorization mechanisms, by adding the following to /etc/X11/xdm/xdm-config:

DisplayManager*authName:    MIT-MAGIC-COOKIE-1

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

This is intended as a simple example of how to use multiple X servers. For illustration purposes, we'll simply use Xnest(1), which creates a new X server :1 as a window on the existing server :0:

$ Xnest :1 &

It's then possible to run programs on the second server, or even a different window manager:

$ DISPLAY=:1 uxterm &
$ DISPLAY=:1 ctwm &

Using X11 forwarding, programs can run on a remote machine while displaying on the local machine. This must typically be enabled in /etc/ssh/sshd_config:

X11Forwarding yes

Log in with ssh(1) and run X programs the normal way:

$ ssh -X remote.machine.example.com
$ uxterm &

On a completely headless system (with no monitor), Xvfb(1) (X virtual framebuffer) can be used in a similar manner. The fully virtual screen of the X server can be exported over the network with x11/x11vnc:

$ Xvfb :1 &
$ DISPLAY=:1 ctwm &
$ x11vnc -display :1 -localhost -passwdfile /path/to/password &

Notice we use the -localhost option. In theory this stops remote connections, however, in practice we're using a SSH tunnel to forward the VNC port, adding an extra layer of security. To connect to the headless machine:

$ ssh -L 5900:hostname:5900 hostname
$ vncviewer localhost &