path: root/FAQ/x.sgml

<!-- $Id: x.sgml,v 1.6 1999-01-10 18:01:45 steve Exp $ -->
<!-- The FreeBSD Documentation Project -->

  <sect>
    <heading>The X Window System and Virtual Consoles<label id="x"></heading>

    <sect1>
      <heading>I want to run X, how do I go about it?</heading>

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

      <p>Then read and follow the documentation on the <htmlurl url=
      "http://www.freebsd.org/cgi/man.cgi?manpath=xfree86&amp;query=xf86config"
      name="xf86config"> tool, which assists you in configuring XFree86(tm)
      for your particular graphics card/mouse/etc.

      <p>You may also wish to investigate the Xaccel server, which is
      available at a very reasonable price.  See the section on
      <ref id="xig" name="Xi Graphics"> for more details.

    <sect1>
      <heading>Why doesn't my mouse work with X<label id="x-and-moused"></heading>

      <p>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 ``<tt>/dev/sysmouse</tt>''.  All mouse events
      received from the real mouse device are written to the sysmouse
      device, using the MouseSystems protocol.  If you wish to use your
      mouse on one or more virtual consoles, <bf/and/ use X, the
      following configuration is recommended:

      <verb>
        /etc/rc.conf:
          moused_type=ps/2          # or whatever your actual type is
          moused_port=/dev/psm0     # or whatever your real port is
          moused_flags=

        /etc/XF86Config
          Section Pointer
              Protocol "MouseSystems"
              Device   "/dev/sysmouse"
              .....
      </verb>

      <p>Some people prefer to use ``<tt>/dev/mouse</tt>'' under X.  To
      make this work, ``<tt>/dev/mouse</tt>'' should be linked to
      <htmlurl url="http://www.freebsd.org/cgi/man.cgi?sysmouse"
      name="/dev/sysmouse">:

      <verb>
        # cd /dev
        # rm -f mouse
        # ln -s sysmouse mouse
      </verb>

    <sect1>
      <heading>X Window menus and dialog boxes don't work right!</heading>

      <p>Try turning off the Num Lock key.

      <p>If your Num Lock key is on by default at boot-time, you may add
      the following line in the ``<tt/Keyboard/'' section of the
      <tt/XF86Config/ file.

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

    <sect1>
      <heading>What is a virtual console and how do I make more?</heading>

      <p>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.

      <p>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.

      <p>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.

      <p>The default FreeBSD installation has three virtual consoles
      enabled, and Alt-F1, Alt-F2, and Alt-F3 will switch between
      these virtual consoles.

      To enable more of them, edit <htmlurl 
      url="http://www.freebsd.org/cgi/man.cgi?ttys" name="/etc/ttys">
      and add entries for ``<tt/ttyv4/'' to ``<tt/ttyvc/'' after the
      comment on ``Virtual terminals'':

      <verb>
        # 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
      </verb>

      <p>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
      ``<tt/secure/'' to ``<tt/insecure/''.

      <p><bf/IMPORTANT NOTE/ if you want to run an X server you <bf/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're 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.

      <p>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:

      <verb>
        ttyvb   "/usr/libexec/getty Pc"         cons25  on secure
      </verb>

      <p>to:

      <verb>
        ttyvb   "/usr/libexec/getty Pc"         cons25  off secure
      </verb>

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

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

      <p>(You could also just delete these lines.)

      <p>Once you have edited <htmlurl 
      url="http://www.freebsd.org/cgi/man.cgi?ttys" name="/etc/ttys">,
      the next step is to make sure that you have enough virtual terminal
      devices.  The easiest way to do this is:

      <verb>
        # cd /dev
        # ./MAKEDEV vty12                 # For 12 devices
      </verb>

      <p>Next, the easiest (and cleanest) way to activate the virtual
      consoles is to reboot.  However, if you really don't want to
      reboot, you can just shut down the X Window system and execute (as
      <tt/root/):

      <verb>
        kill -HUP 1
      </verb>

      <p>It's 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.

    <sect1>
      <heading>How do I access the virtual consoles from X?</heading>

      <p>If the console is currently displaying X Window, you can use
      Ctrl-Alt-F1, etc. to switch to a virtual console.  Note, however,
      that once you've switched away from X Window to a virtual
      terminal, you may use only the Alt- function key to switch to another
      virtual terminal or back to X Window.  You do not need to also press the
      Ctrl key.  If you use the control key to switch back to X on some
      older releases, you can find your text console stuck in ``control-lock''
      mode. Tap the control key to wake it up again.

    <sect1>
      <heading>How do I start XDM on boot?</heading>

      <p>There are two schools of thought on how to start <htmlurl url=
      "http://www.freebsd.org/cgi/man.cgi?manpath=xfree86&amp;query=xdm"
      name="xdm">.  One school starts xdm from
      <htmlurl url="http://www.freebsd.org/cgi/man.cgi?ttys"
      name="/etc/ttys"> using the supplied example, while the other
      simply runs xdm from <htmlurl url="http://www.freebsd.org/cgi/man.cgi?rc" 
      name="rc.local"> or 
      from a <tt/X.sh/ script in <tt>/usr/local/etc/rc.d</tt>.
      Both are equally valid, and one may work in 
      situations where the other doesn't. In both cases the result is the
      same: X will popup a graphical login: prompt. 

      <p>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. 

      <p>If loaded from rc.local, <tt/xdm/ should be started without any 
      arguments (i.e., as a daemon).

      <p>A previous version of the FAQ said to add the
      <tt/vt/ you want X to use to the
      <tt>/usr/X11R6/lib/X11/xdm/Xservers</tt> file.  This is not necessary:
      X will use the first free <tt/vt/ it finds.

    <sect1>
      <heading>When I run xconsole, I get ``Couldn't open console''.</heading>

      <p>If you start <htmlurl
      url="http://www.freebsd.org/cgi/man.cgi?manpath=xfree86&amp;query=X"
      name="X"> with <htmlurl
      url="http://www.freebsd.org/cgi/man.cgi?manpath=xfree86&amp;query=startx"
      name="startx">, the permissions on /dev/console will <tt /not/ get
      changed, resulting in things like <htmlurl
      url="http://www.freebsd.org/cgi/man.cgi?manpath=xfree86&amp;query=xterm"
      name="xterm -C"> and <htmlurl url=
      "http://www.freebsd.org/cgi/man.cgi?manpath=xfree86&amp;query=xconsole"
      name="xconsole"> not working.

      <p>This is because of the way console permissions are set by default.
      On a multi-user system, one doesn't 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 
      <htmlurl url="http://www.freebsd.org/cgi/man.cgi?fbtab" name="fbtab">
      file exists to solve such problems.

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

      <verb>
        /dev/ttyv0 0600 /dev/console
      </verb>

      <p>is in <htmlurl url="http://www.freebsd.org/cgi/man.cgi?fbtab(5)"
      name="/etc/fbtab"> and it will ensure that whomever logs in on
      <tt>/dev/ttyv0</tt> will own the console.

    <sect1>
      <heading>My PS/2 mouse doesn't behave properly under X.</heading>

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

      <p>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.

      <verb>
        options PSM_CHECKSYNC
      </verb>

      <p>See the section on <ref id="make-kernel" name="building a kernel">
      if you've no experience with building kernels.

      <p>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.

      <p>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.

      <p>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:

      <verb>
        psmintr: out of sync (xxxx != yyyy)
      </verb>

      and find your mouse doesn't seem to work properly.

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

      <verb>
        boot: -c
      </verb>

      Then, in the <em>UserConfig</em> command line, type:

      <verb>
        UserConfig> flags psm0 0x100
        UserConfig> quit
      </verb>

    <sect1>
      <heading>My PS/2 mouse from MouseSystems doesn't seem to work.</heading>

      <p>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.

      <p>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 <tt>/sys/i386/isa/psm.c</tt> and rebuild the kernel.  See the 
      section on <ref id="make-kernel" name="building a kernel">
      if you've no experience with building kernels.

      <verb>
diff -u psm.c.orig psm.c
@@ -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 */
      </verb>

      <p>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 <em>UserConfig</em> by giving the ``<tt>-c</tt>'' option 
      at the boot prompt:

      <verb>
        boot: -c
      </verb>

      Then, in the <em>UserConfig</em> command line, type:

      <verb>
        UserConfig> flags psm0 0x04
        UserConfig> quit
      </verb>

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

   <sect1>
    <heading>When building an X app, <tt/imake/ can't find <tt/Imake.tmpl/.  Where is it?
    </heading>

    <p>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. </p>

  </sect1> 

  <sect1>
   <heading>How do I reverse the mouse buttons?
   </heading>
 
   <p>Run the command <tt/ xmodmap -e "pointer = 3 2 1"/ from your .xinitrc or .xsession.
   </p>
  </sect1>
  </sect>