Annotation of wikisrc/guide/x.mdwn, revision 1.2

1.2     ! jdf         1: **Contents**
        !             2: 
        !             3: [[!toc levels=3]]
        !             4: 
1.1       jdf         5: # X
                      6: 
                      7: ## What is X?
                      8: 
                      9: NetBSD uses the X Window System (often referred as X11) to provide a graphical
                     10: interface. In NetBSD 5.0, the amd64, i386, macppc, shark, sgimips, and sparc64
                     11: ports use X.Org and the rest use XFree86.
                     12: 
                     13: Please note that the X Window System is a rather bare bones framework. It acts
                     14: as a base for modern desktop environments like GNOME or KDE, but they are not
                     15: part of the X Window System. NetBSD ships with the X Window System, but it does
                     16: not include these desktop environments; they must be added via pkgsrc.
                     17: 
                     18: When you start using X you'll find many new terms which you may find confusing
                     19: at first. The basic elements are:
                     20: 
                     21:  * *Video hardware*, i.e., your video card.
                     22:  * An *X server* running on top of the hardware. The X server provides a
                     23:    standard way to display graphics (including fonts for text display) and get
                     24:    mouse/keyboard/other input. X is network-transparent, which means that you
                     25:    can run X clients on one machine, and the X server (i.e., the display, with
                     26:    video hardware) on another machine.
                     27:  * *X clients*. These are the programs you directly interact with. They run on
                     28:    top of the X server. A web browser like Firefox is an example of an X client.
                     29:  * A *window manager* running on top of the X server. The window manager is a
                     30:    special X client that is allowed to control the placement of windows. It can
                     31:    also *decorate* windows with standard *widgets* (usually these provide
                     32:    actions like window motion, resizing, iconifying, window killing, etc.).
                     33:  * A *desktop environment* such as GNOME or KDE. These are suites of integrated
                     34:    software designed to give you a well-defined range of software and a more or
                     35:    less common interface to each program. These typically include a window
                     36:    manager, file manager, web browser, email client, multimedia player, text
                     37:    editor, address book, help browser, etc. As you may have guessed, a desktop
                     38:    environment is not needed to use X, but many users will want to install one.
                     39: 
                     40: 
                     41: ## Configuration
                     42: 
                     43: In some cases, you may be able to start using X without any configuration at
                     44: all, and **startx** will work just fine. In many cases, however, some
                     45: configuration of the X server is required. Depending on the port you use, this
                     46: configuration file will be either `/etc/X11/xorg.conf` (for platforms using
                     47: X.org) or `/etc/X11/XF86Config` (for those using XFree86). The structure of the
                     48: configuration file is described formally in
                     49: [xorg.conf(5)](http://netbsd.gw.com/cgi-bin/man-cgi?xorg.conf+5+NetBSD-5.0.1+i386)
                     50: or
                     51: [XF86Config(5)](http://netbsd.gw.com/cgi-bin/man-cgi?XF86Config+5+NetBSD-5.0.1+i386).
                     52: 
                     53: To generate an initial configuration file for your X server, run the command
                     54: 
                     55:     # X -configure
                     56: 
                     57: This command should create a configuration file and place it in your home
                     58: directory. To test the generated configuration file, run, e.g.,
                     59: 
                     60:     # X -config ~/xorg.conf.new
                     61: 
                     62: If this succeeds, you should see a crosshatched background and a cursor in the
                     63: shape of an X. Try moving the cursor around to verify that the mouse is
                     64: functional. To quit, press `Ctrl-Alt-Backspace`.
                     65: 
                     66: If the above test was successful, move the file into place (as either
                     67: `/etc/X11/xorg.conf` or `/etc/X11/XF86Config`) and you are ready to go. The
                     68: following sections may be of interest or use, but are not required reading.
                     69: 
                     70: ## The mouse
                     71: 
                     72: PS/2 and USB mice will normally be autodetected, and a configuration entry like
                     73: the following will be generated:
                     74: 
                     75:     Section "InputDevice"
                     76:             Identifier  "Mouse0"
                     77:             Driver      "mouse"
                     78:             Option      "Protocol" "wsmouse"
                     79:             Option      "Device" "/dev/wsmouse"
                     80:             Option      "ZAxisMapping" "4 5 6 7"
                     81:     EndSection
                     82: 
                     83: For a serial mouse on the first serial port, try something like:
                     84: 
                     85:     Section "InputDevice"
                     86:             Identifier  "Mouse0"
                     87:             Driver      "mouse"
                     88:             Option      "Protocol" "auto"
                     89:             Option      "Device" "/dev/tty00"
                     90:     EndSection
                     91: 
                     92: In this example. `/dev/tty00` is the first serial port. Use `/dev/tty01` for the
                     93: second, and so on. Protocol `auto` will try to automatically detect the protocol
                     94: of your serial mouse. If this doesn't work, try values like `Microsoft`,
                     95: `IntelliMouse` or `Logitech`. See
                     96: [mousedrv(4)](http://netbsd.gw.com/cgi-bin/man-cgi?mousedrv+4+NetBSD-5.0.1+i386)
                     97: for more information.
                     98: 
                     99: ## The keyboard
                    100: 
                    101: Even if you have already configured your keyboard for wscons (see
                    102: [[wscons|guide/cons#wscons]]), you need to configure it for X as well, at
                    103: least if you want to use a non-US layout.
                    104: 
                    105: An easy solution is to use the XKB protocol to specify the keyboard type and
                    106: layout.
                    107: 
                    108: Here is an example that shows how to use a German keyboard:
                    109: 
                    110:     Section "InputDevice"
                    111:             Identifier  "Keyboard0"
                    112:             Driver      "kbd"
                    113:             Option      "XkbRules" "xorg"
                    114:             Option      "XkbModel" "pc105"
                    115:             Option      "XkbLayout" "de"
                    116:             Option      "XkbOptions" "ctrl:nocaps"
                    117:     EndSection
                    118: 
                    119: If you wish to change the repeat rate of your keyboard, you can set it with the
                    120: `AutoRepeat` option, which takes two arguments: delay and rate, respectively.
                    121: The following example sets the initial delay to 200 milliseconds and the repeat
                    122: rate to 30 per second:
                    123: 
                    124:     Option      "AutoRepeat"    "200 30"
                    125: 
                    126: If X is already running, the keyboard repeat rate can be changed with the
                    127: [xset(1)](http://netbsd.gw.com/cgi-bin/man-cgi?xset+1+NetBSD-5.0.1+i386)
                    128: command:
                    129: 
                    130:     $ xset r 200 30
                    131: 
                    132: You can also run this command in your `.xinitrc` file. See below ([[Customizing
                    133: X|guide/x#customizing]]) for more information.
                    134: 
                    135: ## The monitor
                    136: 
                    137: If X does not run at the resolution you think it should, first run **xrandr**
                    138: and see if the resolution you want is listed. If your preferred resolution is
                    139: listed in that command's output, you can change resolutions with, e.g.,
                    140: 
                    141:     $ xrandr -s 1680x1050
                    142: 
                    143: If your preferred resolution is not listed, or you have issues with flickering,
                    144: you may need to manually specify your monitor's horizontal and vertical
                    145: frequencies. These can be set with the `HorizSync` and `VertRefresh` directives
                    146: in the `Monitor` section. An example is provided below.
                    147: 
                    148:     Section "Monitor"
                    149:             Identifier   "Monitor0"
                    150:             VendorName   "Monitor Vendor"
                    151:             ModelName    "Monitor Model"
                    152:             HorizSync    30-83
                    153:             VertRefresh  56-75
                    154:     EndSection
                    155: 
                    156: Possible values for your specific monitor can often be found in the manual,
                    157: sometimes even on the monitor itself.
                    158: 
                    159: ## The video card
                    160: 
                    161: Normally, your video card will be automatically detected. In the event that this
                    162: autodetection fails, all available drivers can be found in
                    163: `/usr/X11R7/lib/modules/drivers`. (Replace `X11R7` with `X11R6` if you use a
                    164: port that has not yet switched to X.Org.) The driver can be set with the
                    165: `Driver` directive in the `Device` section, as shown below.
                    166: 
                    167:     Section "Device"
                    168:             Identifier  "Card0"
                    169:             Driver      "intel"
                    170:     EndSection
                    171: 
                    172: ## Starting X
                    173: 
                    174: You can start X with the following command:
                    175: 
                    176:     $ startx
                    177: 
                    178: If your basic X server configuration is correct, you are left in the X
                    179: environment with the default window manager (twm). If you want a more advanced
                    180: window manager or desktop environment, many are available in pkgsrc. See [[Other
                    181: window managers or desktop
                    182: environments|guide/x#other_window_managers_or_desktop_environments]] for
                    183: information about adding and changing window managers.
                    184: 
                    185: ## Customizing X
                    186: 
                    187: One of the first things you will want to do is to change the programs that run
                    188: when X is first started. The easiest way to do this is to copy the default
                    189: `.xinitrc` file to your home directory and modify it, or create a simple new one
                    190: from scratch. For example:
                    191: 
                    192:     $ cp /etc/X11/xinit/xinitrc ~/.xinitrc
                    193:     $ vi ~/.xinitrc
                    194: 
                    195: The following example shows how to start the window manager (twm) and open an
                    196: instance of the xclock and xterm programs. The screen background color is set to
                    197: `bisque4`, which is defined in `/usr/X11R7/lib/X11/rgb.txt`.
                    198: 
                    199:     ...
                    200:     # start some nice programs
                    201:     xclock -geometry 50x50-1-1 &
                    202:     xsetroot -solid bisque4 &
                    203:     xterm -geometry 80x34-1+1 -bg OldLace &
                    204:     
                    205:     exec twm    # no '&' here
                    206: 
                    207: With this type of setup, to quit X you must exit the window manager, which is
                    208: usually done by selecting `exit` from its menu.
                    209: 
                    210: The above example is very simple, but illustrates the basics of controlling the
                    211: clients that are run when X is started. You can run any number of commands from
                    212: your `.xinitrc`, including basic X configuration commands like **xset b off** to
                    213: turn off the bell.
                    214: 
                    215: ## Other window managers or desktop environments
                    216: 
                    217: If you don't like twm, which is a very simple window manager, you can install
                    218: another window manager or a desktop environment from pkgsrc. The following
                    219: example uses the Openbox window manager, but there are many others available in
                    220: `pkgsrc/wm`.
                    221: 
                    222: Openbox can be installed via binary packages or compiled with pkgsrc. As always,
                    223: assuming a properly set `PKG_PATH`, the binary package method is:
                    224: 
                    225:     # pkg_add -v openbox
                    226: 
                    227: Or, with pkgin:
                    228: 
                    229:     # pkgin install openbox
                    230: 
                    231: To build it with pkgsrc, run:
                    232: 
                    233:     # cd /usr/pkgsrc/wm/openbox
                    234:     # make install
                    235: 
                    236: Openbox is now installed; to start it you must modify your `.xinitrc` file:
                    237: substitute the line which calls `twm` with a line which calls `openbox`. For
                    238: example:
                    239: 
                    240:     # start some useful programs
                    241:     xclock -geometry 50x50-1-1 &
                    242:     # start window manager:
                    243:     exec openbox   # no '&' here
                    244: 
                    245: The [startx(1)](http://netbsd.gw.com/cgi-bin/man-cgi?startx+1+NetBSD-current)
                    246: command will start the X11 session with Openbox. As configured in the example
                    247: `.xinitrc` file above, choosing `Exit` or similar from the window manager's menu
                    248: will quit the window manager and end the X11 session.
                    249: 
                    250: Installing a desktop environment is almost as easy. The following example shows
                    251: how to use the Xfce desktop environment.
                    252: 
                    253:     # pkg_add -v xfce4
                    254:     # cp /usr/pkg/share/examples/rc.d/famd /etc/rc.d
                    255:     # cp /usr/pkg/share/examples/rc.d/dbus /etc/rc.d
                    256:     # cp /usr/pkg/share/examples/rc.d/hal /etc/rc.d
                    257:     # echo rpcbind=YES >> /etc/rc.conf
                    258:     # echo famd=YES >> /etc/rc.conf
                    259:     # echo dbus=YES >> /etc/rc.conf
                    260:     # echo hal=YES >> /etc/rc.conf
                    261:     # /etc/rc.d/rpcbind start
                    262:     # /etc/rc.d/famd start
                    263:     # /etc/rc.d/dbus start
                    264:     # /etc/rc.d/hal start
                    265: 
                    266: After running the above commands, edit your `.xinitrc` as above and change
                    267: `openbox` (or `twm`) to `xfce4-session`. The next time you run `startx`, the
                    268: Xfce desktop environment will be started.
                    269: 
                    270: ## Graphical login with xdm
                    271: 
                    272: If you always use X and the first thing you do after you log in is run `startx`,
                    273: you can set up a graphical login to do this automatically. It is very easy:
                    274: 
                    275:  1. Create the `.xsession` file in your home directory. This file is similar to
                    276:     `.xinitrc` and can, in fact, be a link to it.
                    277: 
                    278:         $ ln -s .xinitrc ~/.xsession
                    279: 
                    280:  2. Modify `/etc/rc.conf`, adding the following line:
                    281: 
                    282:         xdm=YES       # x11 display manager
                    283: 
                    284:  3. Start xdm (or reboot your system, as this will be done automatically from
                    285:     now on):
                    286: 
                    287:         # /etc/rc.d/xdm start
                    288: 
                    289: The configuration files for xdm are in the `/etc/X11/xdm` directory. The
                    290: `Xservers` file specifies the virtual console that X is started on. It defaults
                    291: to `vt05`, which is the console you reach via `Ctrl+Alt+F5`. If you want to use
                    292: a different virtual console, change vt05 as desired. In order to avoid keyboard
                    293: contention between getty and xdm, be sure to start xdm on a virtual terminal
                    294: where getty is disabled. For example, if in `Xservers` you have:
                    295: 
                    296:     :0 local /usr/X11R6/bin/X :0 vt04
                    297: 
                    298: Then, in `/etc/ttys` you should have:
                    299: 
                    300:     ttyE3   "/usr/libexec/getty Pc"         vt220   off secure
                    301: 
                    302: (Please note that `vt04` corresponds to `ttyE3`; In `/etc/X11/xdm/Xservers`,
                    303: numbering starts at 1, but in `/etc/ttys`, numbering starts at 0).
                    304: 
                    305: If you want to change the look of your xdm login screen, you can modify the xdm
                    306: configuration file. For example, to change the background color you can add the
                    307: following line to the `Xsetup_0` file:
                    308: 
                    309:     xsetroot -solid SeaGreen
                    310: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb