Chapter 9 The X Window System and Virtual Consoles

9.1. I want to run X, how do I go about it?
9.2. I tried to run X, but I get an ``KDENABIO failed (Operation not permitted)'' error when I type startx. What do I do now?
9.3. Why doesn't my mouse work with X?
9.4. My mouse has a fancy wheel. Can I use it in X?
9.5. Why do X Window menus and dialog boxes not work right?
9.6. What is a virtual console and how do I make more?
9.7. How do I access the virtual consoles from X?
9.8. How do I start XDM on boot?
9.9. Why do I get ``Couldn't open console'' when I run xconsole?
9.10. Before, I was able to run XFree86 as a regular user. Why does it now say that I must be root?
9.11. Why does my PS/2 mouse misbehave under X?
9.12. How come my PS/2 mouse from MouseSystems does not seem to work?
9.13. When building an X app, imake cannot find Imake.tmpl. Where is it?
9.14. How do I reverse the mouse buttons?
9.15. How do I install a splash screen and where do I find them?
9.16. Can I use the Windows(tm) keys on my keyboard in X?

9.1. I want to run X, how do I go about it?

The easiest way is to simply specify that you want to run X during the installation process.

Then read and follow the documentation on the xf86config tool, which assists you in configuring XFree86(tm) for your particular graphics card/mouse/etc.

You may also wish to investigate the Xaccel server. See the section on Xi Graphics or Metro Link for more details.

9.2. I tried to run X, but I get an ``KDENABIO failed (Operation not permitted)'' error when I type startx. What do I do now?

Your system is running at a raised securelevel, is not it? It is, indeed, impossible to start X at a raised securelevel. To see why, look at the init(8) man page.

So the question is what else you should do instead, and you basically have two choices: set your securelevel back down to zero (usually from /etc/rc.conf), or run xdm(1) at boot time (before the securelevel is raised).

See Q: 9.8. for more information about running xdm(1) at boot time.

9.3. Why doesn't my mouse work with X?

If you are using syscons (the default console driver), you can configure FreeBSD to support a mouse pointer on each virtual screen. In order to avoid conflicting with X, syscons supports a virtual device called /dev/sysmouse. All mouse events received from the real mouse device are written to the sysmouse device via moused. If you wish to use your mouse on one or more virtual consoles, and use X, see Q: 3.12. and set up moused.

Then edit /etc/XF86Config and make sure you have the following lines.

    Section         Pointer
    Protocol        "SysMouse"
    Device          "/dev/sysmouse"
    .....

The above example is for XFree86 3.3.2 or later. For earlier versions, the Protocol should be MouseSystems.

Some people prefer to use /dev/mouse under X. To make this work, /dev/mouse should be linked to /dev/sysmouse (see sysmouse(4)):

    # cd /dev
    # rm -f mouse
    # ln -s sysmouse mouse

9.4. My mouse has a fancy wheel. Can I use it in X?

Yes. But you need to customize X client programs. See Colas Nahaboo's web page (http://www.inria.fr/koala/colas/mouse-wheel-scroll/) .

If you want to use the imwheel program, just follow these simple steps.

  1. Translate the Wheel Events

    The imwheel program works by translating mouse button 4 and mouse button 5 events into key events. Thus, you have to get the mouse driver to translate mouse wheel events to button 4 and 5 events. There are two ways of doing this, the first way is to have moused(8) do the translation. The second way is for the X server itself to do the event translation.

    1. Using moused(8) to Translate Wheel Events

      To have moused(8) perform the event translations, simply add -z 4 to the command line used to start moused(8). For example, if you normally start moused(8) via moused -p /dev/psm0 you would start it by entering moused -p /dev/psm0 -z 4 instead. If you start moused(8) automatically during bootup via /etc/rc.conf, you can simply add -z 4 to the moused_flags variable in /etc/rc.conf.

      You now need to tell X that you have a 5 button mouse. To do this, simply add the line Buttons 5 to the ``Pointer'' section of /etc/XF86Config. For example, you might have the following ``Pointer'' section in /etc/XF86Config.

      Example 9-1. ``Pointer'' Section for Wheeled Mouse in XFree86 3.3.x series XF86Config with moused Translation

          Section "Pointer"
             Protocol        "SysMouse"
             Device          "/dev/sysmouse"
             Buttons         5
          EndSection
      

      Example 9-2. ``InputDevice'' Section for Wheeled Mouse in XFree86 4.x series XF86Config with automatic protocol recognition and button mapping Translation

          Section "InputDevice"
             Identifier      "Mouse1"
             Driver          "mouse"
             Option          "Protocol" "auto"
             Option          "Device" "/dev/psm0"
             Option          "Buttons" "5"
             Option          "ZAxisMapping" "4 5"
          EndSection
      

      Example 9-3. ``.emacs'' example for naive page scrolling with Wheeled Mouse

          ;; wheel mouse
          (global-set-key [mouse-4] 'scroll-down)
          (global-set-key [mouse-5] 'scroll-up)
      
    2. Using Your X Server to Translate the Wheel Events

      If you are not running moused(8), or if you do not want moused(8) to translate your wheel events, you can have the X server do the event translation instead. This requires a couple of modifications to your /etc/XF86Config file. First, you need to choose the proper protocol for your mouse. Most wheeled mice use the ``IntelliMouse'' protocol. However, XFree86 does support other protocols, such as ``MouseManPlusPS/2'' for the Logitech MouseMan+ mice. Once you have chosen the protocol you will use, you need to add a Protocol line to the ``Pointer'' section.

      Secondly, you need to tell the X server to remap wheel scroll events to mouse buttons 4 and 5. This is done with the ZAxisMapping option.

      For example, if you are not using moused(8), and you have an IntelliMouse attached to the PS/2 mouse port you would use the following in /etc/XF86Config.

      Example 9-4. ``Pointer'' Section for Wheeled Mouse in XF86Config with X Server Translation

          Section "Pointer"
             Protocol        "IntelliMouse"
             Device          "/dev/psm0"
             ZAxisMapping    4 5
          EndSection
      
  2. Install imwheel

    Next, install imwheel from the Ports collection. It can be found in the x11 category. This program will map the wheel events from your mouse into keyboard events. For example, it might send Page Up to a program when you scroll the wheel forwards. Imwheel uses a configuration file to map the wheel events to keypresses so that it can send different keys to different applications. The default imwheel configuration file is installed in /usr/X11R6/etc/imwheelrc. You can copy it to ~/.imwheelrc and then edit it if you wish to customize imwheel's configuration. The format of the configuration file is documented in imwheel(1).

  3. Configure Emacs to Work with Imwheel (optional)

    If you use emacs or Xemacs, then you need to add a small section to your ~/.emacs file. For emacs, add the following:

    Example 9-5. Emacs Configuration for Imwheel

        ;;; For imwheel
        (setq imwheel-scroll-interval 3)
        (defun imwheel-scroll-down-some-lines ()
          (interactive)
          (scroll-down imwheel-scroll-interval))
        (defun imwheel-scroll-up-some-lines ()
          (interactive)
          (scroll-up imwheel-scroll-interval))
        (global-set-key [?\M-\C-\)] 'imwheel-scroll-up-some-lines)
        (global-set-key [?\M-\C-\(] 'imwheel-scroll-down-some-lines)
        ;;; end imwheel section
    

    For Xemacs, add the following to your ~/.emacs file instead:

    Example 9-6. Xemacs Configuration for Imwheel

        ;;; For imwheel
        (setq imwheel-scroll-interval 3)
        (defun imwheel-scroll-down-some-lines ()
          (interactive)
          (scroll-down imwheel-scroll-interval))
        (defun imwheel-scroll-up-some-lines ()
          (interactive)
          (scroll-up imwheel-scroll-interval))
        (define-key global-map [(control meta \))] 'imwheel-scroll-up-some-lines)
        (define-key global-map [(control meta \()] 'imwheel-scroll-down-some-lines)
        ;;; end imwheel section
    
  4. Run Imwheel

    You can just type imwheel in an xterm to start it up once it is installed. It will background itself and take effect immediately. If you want to always use imwheel, simply add it to your .xinitrc or .xsession file. You can safely ignore any warnings imwheel displays about PID files. Those warnings only apply to the Linux version of imwheel.

9.5. Why do X Window menus and dialog boxes not work right?

Try turning off the Num Lock key.

If your Num Lock key is on by default at boot-time, you may add the following line in the Keyboard section of the XF86Config file.

    # Let the server do the NumLock processing.  This should only be
    # required when using pre-R6 clients
        ServerNumLock

9.6. What is a virtual console and how do I make more?

Virtual consoles, put simply, enable you to have several simultaneous sessions on the same machine without doing anything complicated like setting up a network or running X.

When the system starts, it will display a login prompt on the monitor after displaying all the boot messages. You can then type in your login name and password and start working (or playing!) on the first virtual console.

At some point, you will probably wish to start another session, perhaps to look at documentation for a program you are running or to read your mail while waiting for an FTP transfer to finish. Just do Alt-F2 (hold down the Alt key and press the F2 key), and you will find a login prompt waiting for you on the second ``virtual console''! When you want to go back to the original session, do Alt-F1.

The default FreeBSD installation has three virtual consoles enabled (8 starting with 3.3-RELEASE), and Alt-F1, Alt-F2, and Alt-F3 will switch between these virtual consoles.

To enable more of them, edit /etc/ttys (see ttys(5)) and add entries for ttyv4 to ttyvc after the comment on ``Virtual terminals'':

    # Edit the existing entry for ttyv3 in /etc/ttys and change
    # "off" to "on".
    ttyv3   "/usr/libexec/getty Pc"         cons25  on secure
    ttyv4   "/usr/libexec/getty Pc"         cons25  on secure
    ttyv5   "/usr/libexec/getty Pc"         cons25  on secure
    ttyv6   "/usr/libexec/getty Pc"         cons25  on secure
    ttyv7   "/usr/libexec/getty Pc"         cons25  on secure
    ttyv8   "/usr/libexec/getty Pc"         cons25  on secure
    ttyv9   "/usr/libexec/getty Pc"         cons25  on secure
    ttyva   "/usr/libexec/getty Pc"         cons25  on secure
    ttyvb   "/usr/libexec/getty Pc"         cons25  on secure

Use as many or as few as you want. The more virtual terminals you have, the more resources that are used; this can be important if you have 8MB RAM or less. You may also want to change the secure to insecure.

Important: If you want to run an X server you must leave at least one virtual terminal unused (or turned off) for it to use. That is to say that if you want to have a login prompt pop up for all twelve of your Alt-function keys, you are out of luck - you can only do this for eleven of them if you also want to run an X server on the same machine.

The easiest way to disable a console is by turning it off. For example, if you had the full 12 terminal allocation mentioned above and you wanted to run X, you would change settings for virtual terminal 12 from:

    ttyvb   "/usr/libexec/getty Pc"         cons25  on  secure

to:

    ttyvb   "/usr/libexec/getty Pc"         cons25  off secure

If your keyboard has only ten function keys, you would end up with:

    ttyv9   "/usr/libexec/getty Pc"         cons25  off secure
    ttyva   "/usr/libexec/getty Pc"         cons25  off secure
    ttyvb   "/usr/libexec/getty Pc"         cons25  off secure

(You could also just delete these lines.)

Once you have edited /etc/ttys, the next step is to make sure that you have enough virtualterminal devices. The easiest way to do this is:

    # cd /dev
    # sh MAKEDEV vty12

Next, the easiest (and cleanest) way to activate the virtual consoles is to reboot. However, if you really do not want to reboot, you can just shut down the X Window system and execute (as root):

    # kill -HUP 1

It is imperative that you completely shut down X Window if it is running, before running this command. If you don't, your system will probably appear to hang/lock up after executing the kill command.

9.7. How do I access the virtual consoles from X?

Use Ctrl+Alt+Fn to switch back to a virtual console. Ctrl+Alt+F1 would return you to the first virtual console.

Once you are back to a text console, you can then use Alt+Fn as normal to move between them.

To return to the X session, you must switch to the virtual console running X. If you invoked X from the command line, (e.g., using startx) then the X session will attach to the next unused virtual console, not the text console from which it was invoked. If you have eight active virtual terminals then X will be running on the ninth, and you would use Alt+F9 to return.

9.8. How do I start XDM on boot?

There are two schools of thought on how to start xdm. One school starts xdm from /etc/ttys (see ttys(5)) using the supplied example, while the other simply runs xdm from rc.local (see rc(8)) or from a X.sh script in /usr/local/etc/rc.d. Both are equally valid, and one may work in situations where the other does not. In both cases the result is the same: X will popup a graphical login: prompt.

The ttys method has the advantage of documenting which vty X will start on and passing the responsibility of restarting the X server on logout to init. The rc.local method makes it easy to kill xdm if there is a problem starting the X server.

If loaded from rc.local, xdm should be started without any arguments (i.e., as a daemon). xdm must start AFTER getty runs, or else getty and xdm will conflict, locking out the console. The best way around this is to have the script sleep 10 seconds or so then launch xdm.

If you are to start xdm from /etc/ttys, there still is a chance of conflict between xdm and getty(8). One way to avoid this is to add the vt number in the /usr/X11R6/lib/X11/xdm/Xservers file.

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

The above example will direct the X server to run in /dev/ttyv3. Note the number is offset by one. The X server counts the vty from one, whereas the FreeBSD kernel numbers the vty from zero.

9.9. Why do I get ``Couldn't open console'' when I run xconsole?

If you start X with startx, the permissions on /dev/console will not get changed, resulting in things like xterm -C and xconsole not working.

This is because of the way console permissions are set by default. On a multi-user system, one does not necessarily want just any user to be able to write on the system console. For users who are logging directly onto a machine with a VTY, the fbtab(5) file exists to solve such problems.

In a nutshell, make sure an uncommented line of the form

    /dev/ttyv0 0600 /dev/console

is in /etc/fbtab (see fbtab(5)) and it will ensure that whomever logs in on /dev/ttyv0 will own the console.

9.10. Before, I was able to run XFree86 as a regular user. Why does it now say that I must be root?

All X servers need to be run as root in order to get direct access to your video hardware. Older versions of XFree86 (<= 3.3.6) installed all bundled servers to be automatically run as root (setuid to root). This is obviously a security hazard because X servers are large, complicated programs. Newer versions of XFree86 do not install the servers setuid to root for just this reason.

Obviously, running an X server as the root user is not acceptable, nor a good idea security-wise. There are two ways to be able to use X as a regular user. The first is to use xdm or another display manager (e.g., kdm); the second is to use the Xwrapper.

xdm is a daemon that handles graphical logins. It is usually started at boot time, and is responsible for authenticating users and starting their sessions; it is essentially the graphical counterpart of getty(8) and login(1). For more information on xdm see the XFree86 documentation, and the the FAQ entry on it.

Xwrapper is the X server wrapper; it is a small utility to enable one to manually run an X server while maintaining reasonable safety. It performs some sanity checks on the command line arguments given, and if they pass, runs the appropriate X server. If you do not want to run a display manger for whatever reason, this is for you. If you have installed the complete ports collection, you can find the port in /usr/ports/x11/wrapper.

9.11. Why does my PS/2 mouse misbehave under X?

Your mouse and the mouse driver may have somewhat become out of synchronization.

In versions 2.2.5 and earlier, switching away from X to a virtual terminal and getting back to X again may make them re-synchronized. If the problem occurs often, you may add the following option in your kernel configuration file and recompile it.

    options PSM_CHECKSYNC

See the section on building a kernel if you have no experience with building kernels.

With this option, there should be less chance of synchronization problem between the mouse and the driver. If, however, you still see the problem, click any mouse button while holding the mouse still to re-synchronize the mouse and the driver.

Note that unfortunately this option may not work with all the systems and voids the ``tap'' feature of the ALPS GlidePoint device attached to the PS/2 mouse port.

In versions 2.2.6 and later, synchronization check is done in a slightly better way and is standard in the PS/2 mouse driver. It should even work with GlidePoint. (As the check code has become a standard feature, PSM_CHECKSYNC option is not available in these versions.) However, in rare case the driver may erroneously report synchronization problem and you may see the kernel message:

    psmintr: out of sync (xxxx != yyyy)

and find your mouse does not seem to work properly.

If this happens, disable the synchronization check code by setting the driver flags for the PS/2 mouse driver to 0x100. Enter UserConfig by giving the -c option at the boot prompt:

    boot: -c

Then, in the UserConfig command line, type:

    UserConfig> flags psm0 0x100
    UserConfig> quit

9.12. How come my PS/2 mouse from MouseSystems does not seem to work?

There have been some reports that certain model of PS/2 mouse from MouseSystems works only if it is put into the ``high resolution'' mode. Otherwise, the mouse cursor may jump to the upper-left corner of the screen every so often.

Unfortunately there is no workaround for versions 2.0.X and 2.1.X. In versions 2.2 through 2.2.5, apply the following patch to /sys/i386/isa/psm.c and rebuild the kernel. See the section on building a kernel if you have no experience with building kernels.

    @@ -766,6 +766,8 @@
         if (verbose >= 2)
             log(LOG_DEBUG, "psm%d: SET_DEFAULTS return code:%04x\n",
                 unit, i);
    +    set_mouse_resolution(sc->kbdc, PSMD_RES_HIGH);
    +
     #if 0
         set_mouse_scaling(sc->kbdc);        /* 1:1 scaling */
         set_mouse_mode(sc->kbdc);                /* stream mode */

In versions 2.2.6 or later, specify the flags 0x04 to the PS/2 mouse driver to put the mouse into the high resolution mode. Enter UserConfig by giving the -c option at the boot prompt:

    boot: -c

Then, in the UserConfig command line, type:

    UserConfig> flags psm0 0x04
    UserConfig> quit

See the previous section for another possible cause of mouse problems.

9.13. When building an X app, imake cannot find Imake.tmpl. Where is it?

Imake.tmpl is part of the Imake package, a standard X application building tool. Imake.tmpl, as well as several header files that are required to build X apps, is contained in the X prog distribution. You can install this from sysinstall or manually from the X distribution files.

9.14. How do I reverse the mouse buttons?

Run the command xmodmap -e "pointer = 3 2 1" from your .xinitrc or .xsession.

9.15. How do I install a splash screen and where do I find them?

Just prior to the release of FreeBSD 3.1, a new feature was added to allow the display of ``splash'' screens during the boot messages. The splash screens currently must be a 256 color bitmap (*.BMP) or ZSoft PCX (*.PCX) file. In addition, they must have a resolution of 320x200 or less to work on standard VGA adapters. If you compile VESA support into your kernel, then you can use larger bitmaps up to 1024x768. Note that VESA support requires the VM86 kernel option to be compiled into the kernel. The actual VESA support can either be compiled directly into the kernel with the VESA kernel config option or by loading the VESA kld module during bootup.

To use a splash screen, you need to modify the startup files that control the boot process for FreeBSD. The files for this changed prior to the release of FreeBSD 3.2, so there are now two ways of loading a splash screen:

  • FreeBSD 3.1

    The first step is to find a bitmap version of your splash screen. Release 3.1 only supports Windows bitmap splash screens. Once you have found your splash screen of choice copy it to /boot/splash.bmp. Next, you need to have a /boot/loader.rc file that contains the following lines:

        load kernel
        load -t splash_image_data /boot/splash.bmp
        load splash_bmp
        autoboot
    
  • FreeBSD 3.2+

    In addition to adding support for PCX splash screens, FreeBSD 3.2 includes a nicer way of configuring the boot process. If you wish, you can use the method listed above for FreeBSD 3.1. If you do and you want to use PCX, replace splash_bmp with splash_pcx. If, on the other hand, you want to use the newer boot configuration, you need to create a /boot/loader.rc file that contains the following lines:

        include /boot/loader.4th
        start
    

    and a /boot/loader.conf that contains the following:

        splash_bmp_load="YES"
        bitmap_load="YES"
    

    This assumes you are using /boot/splash.bmp for your splash screen. If you would rather use a PCX file, copy it to /boot/splash.pcx, create a /boot/loader.rc as instructed above, and create a /boot/loader.conf that contains:

        splash_pcx_load="YES"
        bitmap_load="YES"
        bitmap_name="/boot/splash.pcx"
    

Now all you need is a splash screen. For that you can surf on over to the gallery at http://www.baldwin.cx/splash/.

9.16. Can I use the Windows(tm) keys on my keyboard in X?

Yes. All you need to do is use xmodmap(1) to define what function you wish them to perform.

Assuming all ``Windows(tm)'' keyboards are standard then the keycodes for the 3 keys are

  • 115 - Windows(tm) key, between the left-hand Ctrl and Alt keys

  • 116 - Windows(tm) key, to the right of the Alt-Gr key

  • 117 - Menu key, to the left of the right-hand Ctrl key

To have the left Windows(tm) key print a comma, try this.

    # xmodmap -e "keycode 115 = comma"

You will probably have to re-start your window manager to see the result.

To have the Windows(tm) key-mappings enabled automatically every time you start X either put the xmodmap commands in your ~/.xinitrc file or, preferably, create a file ~/.xmodmaprc and include the xmodmap options, one per line, then add the line

    xmodmap $HOME/.xmodmaprc

to your ~/.xinitrc.

For example, you could map the 3 keys top be F13, F14, and F15, respectively. This would make it easy to map them to useful functions within applications or your window manager, as demonstrated further down.

To do this put the following in ~/.xmodmaprc.

    keycode 115 = F13
    keycode 116 = F14
    keycode 117 = F15

If you use fvwm2, for example, you could map the keys so that F13 iconifies (or de-iconifies) the window the cursor is in, F14 brings the window the cursor is in to the front or, if it is already at the front, pushes it to the back, and F15 pops up the main Workplace (application) menu even if the cursor is not on the desktop, which is useful if you do not have any part of the desktop visible (and the logo on the key matches its functionality).

The following entries in ~/.fvwmrc implement the aforementioned setup:

    Key F13        FTIWS    A        Iconify
    Key F14        FTIWS    A        RaiseLower
    Key F15        A        A        Menu Workplace Nop

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.