# setup

Setting up your XFree86 system

This section gives a short introduction on how to set up a XFree86 system on your computer. The most important (and most difficult) part is setting up a `Xconfig` file. If you have XFree86 2.1.1 and your graphic card is in the data base, you should use `ConfigXF86` to do this. It is comfortable and safe that way. You can use `ConfigXF86` for many things even if your card and monitor are not known to the program. Please use it if you have XFree86 2.1.1.

### The Xconfig file

To be able to set up a `Xconfig` file, you need to read the following files that reside in `/usr/X386/lib/X11/etc`: `README`, `README.Config`, `VideoModes.doc`, and `README.Linux`.

Furthermore you need to read the following manpages: `Xconfig`, `XFree86`, `XFree86kbd`, and that of the server you are going to use. This section will try to give you an approach to these files as well as making some of the statements in those more understandable for the unexperienced user.

The `Xconfig` file can be located in several places:

- `/usr/X386/lib/X11`. This is the standard location for the sample `Xconfig` file, but is in some cases not possible to use (e.g. a read-only `/usr` partition).
- `/etc`.
- In the user's home directory.
- As `Xconfig.hostname` in `/usr/X386/lib/X11`.

The Linux file system standard places the Xconfig file into `/etc/X11`. This has several causes, but you should never edit that file. The XFree86 servers will not expect a `Xconfig` file at this location, so there has to be a link from one of the above places to this location. Find this link first and access the file using the link. This way you can be sure your changes will take effect.

To give you some hints, here is a list of what you need to set up the `Xconfig` file correctly:

- The server that is suitable for you system. To get a hint which is the correct one, run the `SuperProbe` program that comes with XFree86. It will identify your chipset and you can look at the table above [cf. <here> ],which server supports this chipset. Note that `SuperProbe` can detect far more hardware than XFree86 supports.
- The specifications of your monitor. Most important are the maximal horizontal and vertical scan frequency ranges and the bandwidth of the monitor. This information should be obtained from your monitor's datasheet. See the video mode section <here> for further information.
- The name of the chipset for your card. See <here> for more information.
- The available dot clocks for your card or (if supported) the name of the programmable dot clock generator. How to obtain these is explained concisely in `/usr/X386/lib/X11/etc/README.Config`. This will be done automagically by `ConfigXF86`. Note that if you have a programmable clock generator, you have to look in the `Xconfig` manpage, whether it is supported. A programmable clock cannot be detected properly.
- Mouse type (this refers to the protocol the mouse is using, not to the manufacturer, e.g. a serial microsoft mouse connected to the ps/2 port uses the `ps/2` protocol, not the `Microsoft` protocol). See <here> for more information.
- The device name of the device your mouse is connected to. See <here> for more information.
- If you want to use a national keyboard map for the kernel (i.e. you are not running the generic US keytable), you should read <here> to set up XFree86 correctly.

You should read `README.Config` that is located in `/usr/X386/lib/X11/etc` and follow the instructions there to the point. Especially the caveats that can be found int this file must be obeyed, otherwise you might damage your hardware.

WARNING: Do not ever share `Xconfig` files with people who do not have exactly the same Configuration (i.e. graphic card and monitor). By doing this you could toast your monitor. It isn't so hard to figure out modes (that is, for multisync monitors) and you surely shouldn't ever use a mode that you didn't check by yourself to be within your monitor's specs. Even if you have exactly the same setup you should check all modes yourself before trying them. There are many people who run their hardware out of specs which may not damage their hardware but could yours.

### Running ConfigXF86

From XFree86 2.1.1 on there is a great tool available for XFree86, called `ConfigXF86`. It was written by Stephen Zwaska, comments and new database entries should be sent to him (`stz@netcom.com`). This utility will give you an easy interface to the database of tested graphic cards and monitors and it gives you some tools to configure your `Xconfig` file correctly. The documentation for `ConfigXF86` is located in `/usr/X386/lib/X11/ConfigXF86`. Please read this first, it will help you to run this program. This documentation is provided in several formats. A text version (`ConfigXF86.txt`) can be read online, a PostScript version (`ConfigXF86.PS`) can be printed if a PostScript printer is available. `ConfigXF86` can be obtained from sunsite in the directory `/pub/linux/packages/X11/ConfigXF86`.

After having read the documentation, start `ConfigXF86` as `root`. The program cannot be run while a X server is running on the system, so run `ConfigXF86` (and if needed `MakeCard`) from the console. You should be able to answer all questions. The program will probe your system and will (at least partly) recognize the setup. If both your graphic card and monitor are supported, you should not have any problems. The only thing you should do is test the video modes and (perhaps) try to make minor changes to the video modes to suit your monitor better [cf. <here> ].

This utility is very new, so there might be bugs (very probably there are). If you encounter any problems, please report them.

If your card is not supported, try to make a card database file using the `MakeCard` program that can be found in `/usr/X386/lib/X11/ConfigXF86`. Please read the next two sections before running it as it may help you with some questions. Having done that you can run `ConfigXF86` and choose the datafile you just generated. Don't forget to send the card data file and the monitor data files to `stz@netcom.com` so that other people may benefit from your achievements.

### The easy sections

### Remark:

The XFree86 servers parse the `Xconfig` file in case-insensitive mode, so you need not woory about Capitalization.

### Paths:

There is no reason to fiddle with the standard paths as provided in the sample `Xconfig` file (any distribution that provides a different path structure should have edited this section of the `Xconfig.sample` or the template Xconfig file for `ConfigXF86`). The only thing that could be interesting is the use of a fontserver. Look at the `Xconfig` manpage if you want use one, anything you need to know is shown there. `ConfigXF86` will prompt you whether you want to use a fontserver.

### The keyboard section:

This is fairly easy. You should set the `ServerNumlock` option, but otherwise only those keyboard modifications that are needed for international keyboard support should be needed to set [cf. <here> ]. So this section should look like:

> `

>     keyboard
>         servernumlock
>         RightAlt ModeShift

> `

### The mouse section:

The keyword for the mouse section is the name for the protocol the mouse uses. The available protocol names are listed in the `Xconfig` manpage. Some remarks on the mouse keywords:

The Logitech[TM] serial mice use several keywords: The MouseMan[TM] uses the `MouseMan` keyword and more recent Logitech serial mice use the `Microsoft` keyword. Older Logitech serial mice use the `Logitech` keyword.

Any mouse connected to the ps/2 port uses the `ps/2` keyword (even if it is in fact a serial mouse).

As there is some confusion on the Linux mouse devicenames, here is a list. The standard names confer to the names as of `MAKEDEV` 1.2. If you are not sure, which kind of busmouse you have, look at the startup messages of the kernel. It will identify the busmouse type. You should make sure that the kernel busmouse driver is using the same IRQ as the busmouse. If this is not the case, you have to change this (either on the mouse board or in the kernel). The IRQ for busmouse devices is given in `/usr/src/linux/include/linux/busmouse.h`. The macro `MOUSE_IRQ` contains this IRQ. It is set to 5 by default.

- `/dev/atibm` for the ATI XL busmouse (Note: the ATI GU busmouse is a Logitech or Microsoft busmouse depending on the version you got).
- `/dev/logibm` for the Logitech busmouse (Note: this uses the `Busmouse` protocol, not the `Logitech` protocol).
- `/dev/inportbm` for the Microsoft[TM] busmouse (Note: this uses the `Busmouse` protocol, not the `Microsoft` protocol).
- `/dev/psaux` for a ps/2 or quickport mouse (uses the `ps/2` protocol).
- The other supported mice are serial mice, therefore the device names are that of the serial devices (`/dev/ttyS?` or `/dev/ttyS??` for Linux).

There are still distributions around that use old or different device names than those of `MAKEDEV`. A list of the major and minor numbers for the mouse devices can be found in the`/dev/MAKEDEV` script. If it is missing you can find it on `sunsite` in the `/pub/Linux/system/Admin` directory [cf <here> ].

If you have a two-button mouse, you might want to emulate the third button (emulated by pressing both buttons simultaneously) by setting `Emulate3Buttons` in the mouse section. There are quite a lot of other settings available that are usually not needed. Look at the `Xconfig` manpage for a list of available settings.

### The server section

You should be able to set up this section by using the `ConfigXF86` program. If your graphic card is not part of the database, run `MakeCard` to build a new data file for your card. Many important things are probed by `MakeCard`, but you may need or want to set additional options. These options are described in the manpage of the server you want to use (`MakeCard` will suggest the right one) and in `README.Config`. After running `MakeCard`, run `ConfigXF86` to set up the `Xconfig` file. If you do not have the `ConfigXF86` package, you should follow the instructions in `README.Config` to get everything right.

If you want to identify the chipset your graphic card uses, run `SuperProbe`, a program that comes with XFree86 and is capable to identify a lot of graphic hardware. Note that `SuperProbe` can probe far more hardware than XFree86 supports.

### Setting up video modes

This is the hardest part. Please read `VideoModes.doc` before doing anything here. If you are using `ConfigXF86` (which is strongly recommended), and your monitor is not in the database, you should choose the generic modes and start making own modes from there. If you do not have `ConfigXF86`, a tutorial on building modes can be found in the `README.Config` and `VideoModes.doc` files.

`ConfigXF86` includes a very neat utility to tune video modes. As there is no check on the fitness of a mode, you have to check the mode data against your monitor's specifications before testing the mode. The first line of the screen for tuning modes gives you information on the specifications of the mode. You have to check always that these values are within you monitor's capabilities before testing that mode.

### International keyboard layout for XFree86

From version 2.1 on the XFree86 servers are able to read the keytable from the Linux kernel. So you need to set up only one keyboard layout file (that for the kernel). There are some restrictions, though (the kernel can support more keyboard functions than X11). X11 can only use 4 keytables (i.e. only one modifier is allowed, called `ModeShift`). This can be configured using the `ModeShift` line in the `Xconfig` file. Configurable keys for the ModeShift modifier are `LeftAlt`, `RightAlt` (=`AltGr`), `RightCtl`, and `ScrollLock`. By default the `ModeShift` modifier is not used.

Usually the `AltGr` key is used for national keyboard modifications. To enable the XFree86 server to read the `AltGr` keytable from the kernel, you should put

    RightAlt "ModeShift"

into the keyboard section of the `Xconfig` file.

Besides supporting only one additional keymap X11 cannot use 'dead' keys. A key is called 'dead', if it will not print a character when it is typed but only after a second character is typed. Depending on the following character, the second character is modified by the 'dead' character or two characters will be printed. A typical example are accent keys. Such keys are not supported by X11. So you need to replace all dead keysymbols non-dead equivalents. Here is a list, what you have to change:

> `

>              dead         non-dead

>            dead_tilde    asciitilde
>            dead_grave         grave
>       dead_circumflex   asciicircum
>            dead_acute    apostrophe
>        dead_diaeresis     diaeresis

> `

Instead of supporting dead keys XFree86 supports a `Compose` key. This feature is described in the `XFree86kbd` manpage and can be modified by assigning the `Compose` function to one of the keys mentioned above. By default the `ScrollLock` key has the `Compose` function.

If you still want to have the 'dead' keys on the console, you will have to use a xmodmap file to map the keys to the right symbols under X. This is also the method that must be used with earlier versions of XFree86. On `sunsite` in the directory `/pub/Linux/X11/misc` example xmodmap files for several languages can be found. Note that you have to set the `ModeShift` modifier nevertheless to get the right keytable working.

Please read the `kbd.FAQ` that comes with the kbd package for Linux. You will find many hints on modifying your keyboard layout on the console as well as for X.

### The .xinitrc file

To use X, you need a startup file that calls the local modifications, the window manager and some application you want to have right after X has started. If you are using startx (or runx) to start X, this startup file is called '`xinitrc`'. There is a standard xinitrc file, `/usr/lib/X11/xinit/xinitrc` <FOOTNOTE>This is the traditional location for this file. The Linux filesystem standard places this file to `/etc/X11/xinit/xinitrc` in order to allow a read-only mounted /usr partition. So you should look at that location first.</FOOTNOTE> . If you are not content with what this file does (e.g. you want to use a different window-manager), you should copy this file to the file `.xinitrc` in your home directory. After copying the file, you can edit it. Look at the manpages for `startx` and `xinit` for more information.

Note that both the `.xinitrc` and the `.Xresources` file must be readable and executable, so run `chmod u+rx .xinitrc` and `chmod u+rx .Xresources` after editing them.

### The personal X resource file

Sometimes you won't be content with default settings for several applications which often don't have a configruration file of their own. You can change some of these defaults by setting X resources in the `.Xresources` file in your home directory. Note that you should know what effects the setting of the resources has to the programs you use. Read the manpages for the program and for `xrdb` before fiddling with the `Xresources` file. This section is not needed to set up working X environment, but to customize a working one.

A resource file looks like an application default file (with the difference that in the resoucre file resources for several applications are set, you should use the full names (Progname.Resourcename) instead of abbreviating the program name by an asterisk. Examples of application default files can be found in the `/usr/X386/lib/X11/app-defaults` directory. Which resources are available for a single application is usually shown in the manpage of the application.

If you are running a colour server, you might want to put

> `

>     #ifdef COLOR
>     *customization: -color
>     #endif

> `

into your `.Xresources` file if some programs start up b&w and not colourful. If the upper change is made (it definetly should be in the system Xresources file, so you might hint that to the distribution maintainer), a program `foo` will read both the `Foo` and the `Foo-color` application default file from `/usr/X386/lib/X11/app-defaults`, not just the first which is the usual behaviour.
Note that the b&w outfit of a program may caused by the program not supporting colours.

### Using xdm

If you want to run X on your system all the time, you could run `xdm` from the system startup. `xdm` is preconfigured on most systems, so you should not have to edit any of the `xdm` configuration files. Usually a runlevel is attached to a X-only system (look into `/etc/inittab`), all you have to do to get it working is changing the default runlevel. On systems that use an `init` without runlevels (run `man init` to see, whether or not), you should look into the `/etc/rc` and `/etc/rc.local` files, you usually only have to remove comment signs at the beginning of a line that calls `xdm`. If no such line is present, you probably have a system that has no preconfigured `xdm`. Look at the manpages to see what has to be done (and complain to the distribution maintainer, if the distribution contains XFree86). If you install XFree86 on top of a distribution that is not providing X support, you should get enough information from the manpages. Help is also available from the X Faq, look at section <here> where to get this.

`xdm` runs by default the .xinitrc [cf <here> ]and the .Xresources [cf <here> ] files, so look at the sections above.

### Configuration of the window manager

Window managers are a very local issue. There are quite a lot window managers available [cf. <here> ]. Configuration of one windowmanager is quite different from that of another. You should look at your `.xinitrc` file or the system `xinitrc` [cf <here> ] file, which window manager is used (hint: most window managers have a `wm` ending) and look at its manpage. Configuration is usually explained there. The most common used window managers for Linux are:
`twm` (part of the XFree86 distribution), `fvwm` (this seems to be the most popular), `olwm` or `olvwm` (from the Xview[TM] package), or mwm (part of Motif[TM]).

### Running X

Once you have set up a `Xconfig` file, you probably want to run X. This is not done by running `X`, but by running `startx`. When running it for the first time run `startx 2>1 > Xstartup.log` <FOOTNOTE> For `csh` users this should read `startx >& Xstartup.log` .</FOOTNOTE> to get a log file of the X startup. If problems are encountered, this file will help you by providing information for you and for anyone you ask about your problems.

If you encounter any problems, please look at the Appendix <here> and at the XFree86 documentation files in `/usr/X386/lib/X11/etc`. These files provide a lot of information on what to do if problems occur. If you still cannot solve the problems, procede as in Section <here> . The FAQs that are mentioned there provide help on many problems you have with X, so you should get these and read them, too.

You should make sure that the `PATH` and `MANPATH` (or `path` and `manpath` for `csh` derivates) variables are set correctly.