path: root/sgml/OpenBSD.sgml

<!DOCTYPE linuxdoc PUBLIC "-//Xorg//DTD linuxdoc//EN" [
<!ENTITY % defs SYSTEM "defs.ent"> %defs;
]>

<article>
<title>README for X11R&relvers; on OpenBSD
<author>
Matthieu Herrb
<Date>Last modified on: 9 December 2003; updated 25 March 2004 by Jim Gettys 
for X11R&relvers;

<ident>
</ident>

<toc>


<sect>What and Where is X11R&relvers;?

<p>
The X.org Foundation X11R&relvers; is an Open Source version of the X Window System that supports
several UNIX(R) and UNIX-like operating systems (such as Linux, the BSDs
and Solaris x86) on Intel and other platforms.

See the <htmlurl url="COPYRIGHT.html" name="Copyright Notice">.

<![ %notsnapshot [
The sources for X11R&relvers; are available from

<htmlurl name="http://wiki.x.org"
url="http://wiki.x.org">]]>

<p>

X11R&relvers; also builds on other OpenBSD architectures. See section
<ref id="otherarch" name="Building on other architectures"> for details.


<sect>Bug Reports for This Document

<p>
Use the X.org Bugzilla at <url url="http://bugzilla.freedesktop.org"> 
to submit comments or suggestions about this file, using the xorg product.

<sect>New OS dependent features
<p>
See the <htmlurl url="RELNOTES.html" name="Release Notes"> for
non-OS dependent new features in X11R&relvers;.

<sect1>New OS related features
<p>
<itemize>
<item>The IPv6 support is enabled on OpenBSD, but XDMCP over IPv6 is
not currently enabled since the code uses IPv6 mapped IPv4 addresses
which are not supported on OpenBSD. 
<item>The userland part of DRI is enabled and built. Now waiting for
someone to port the kernel modules...
<item>All major revisions of the shared libraries are incremented on 
OpenBSD 3.3 and later, to support the API changes introduced by 
gcc stack protector.
</itemize>

<sect1>New OS related features in 4.3
<p>
<itemize>
<item>Support for some VGA cards on OpenBSD/alpha
</itemize>

<sect1>New OS dependent features in 4.2
<p>
<itemize>
<item>Support for OpenBSD/macppc on the ATI Rage128 based
Power Macintoshes. 
<item>Support for building clients on OpenBSD/sparc64.
</itemize>

<sect1>New OS dependent features in 4.0.3
<p>
<itemize>
<item>Support for the wscons console driver in post 2.8 OpenBSD.
<item>A fix for multi-threaded libraries support. 
</itemize>

<sect1>New OS dependent features in 4.0.2
<p>
<itemize>
<item>Support for the OpenBSD ports tree, 
<item>Preliminary support for the macppc architecture (clients build
and work, the server doesn't work yet),
<item>xdm now writes an utmp entry,
<item>startx now creates an Xauthority magic cookie for the display. 
</itemize>

<sect1>New OS dependent features in 4.0.1
<p>
<itemize>
<item>Several features from the OpenBSD X11 tree were merged into xdm:
<itemize>
<item> support for Kerberos IV authentication 
<item>use the arc4random(4) random number generator
<item>add a new resource "allowRootLogin", which can be used to disable
         root logins through xdm
<item>log failed logins to syslogd
<item>verify that the shell is valid using /etc/shell
<item>verify that the account hasn't expired
</itemize>
<item>The Xsun server can be built again on OpenBSD/sparc.
</itemize>

<sect1>New OS dependent features in 4.0
<p>
<itemize>
<item>Multi-thread safe libraries are built by default on OpenBSD 2.6
      and later,
<item>Preliminary APM support.
</itemize>

<sect1>New OS dependent features in 3.9.18
<p>
<itemize>
<item>Support for USB mices has been added on OpenBSD. 
<item>Soft-booting secondary cards through the int10 BIOS interface is 
now possible using the x86emu real mode emulator. 
</itemize>

<sect1>New OS dependent features in 3.9.17
<p>
<itemize>
<item><em>Silken mouse</em> is supported for serial mices, and, under
post 2.6 OpenBSD-current for PS/2 mices.
<item>MTRR Write Combining is enabled under post 2.6 OpenBSD-current. 
</itemize>

<sect>Installing the Binaries

<p>
Refer to the <htmlurl url="Install.html" name="Installation Document">
for detailed installation instructions.

<sect>Configuring X for Your Hardware
<p>
The <tt>/etc/X11/xorg.conf</tt> file tells the X server what kind of
monitor, 
video card and mouse you have.  You <em/must/ create it to tell the
server what specific hardware you have.
<p>
You'll need info on your hardware:
<itemize>
<item>Your mouse type, baud rate and its /dev entry.
<item>The video card's chipset (e.g. ET4000, S3, etc).
<item>Your monitor's sync frequencies.
</itemize>

The recommended way to generate an <tt/xorg.conf/ file is to use the
<tt/xorgcfg/ utility.  The xorgconfig text utility is still there
for the (few) cases where xorgcfg can't be used. Also, there is a
sample file installed as <tt>/usr/X11R6/lib/X11/xorg.conf.eg</tt>,
which can be used as a starting point.


For details about the <tt/xorg.conf/ file format, refer to the
<em><htmlurl name="xorg.conf(5)" url="xorg.conf.5.html"></em> manual page.

Once you've set up a xorg.conf file, you can fine tune the video
modes with the <tt>xvidtune</tt> utility. 

<sect1>About mouse configuration

<p>
X11R&relvers; has support for the mouse driver included in
the new <bf/wscons/ console driver introduced by OpenBSD-2.9. 
Specify ``<tt/wsmouse/'' as the protocol and
``<tt>/dev/wsmouse0</tt>'' as the  device in <tt>/etc/X11/xorg.conf</tt>
if you're using OpenBSD-2.9 or later with a PS/2 or USB mouse.
<p>
See <htmlurl url="mouse.html" name="README.mouse">  for general
instruction on mouse configuration.


<sect>Running X

<p>

<sect1>Starting xdm, the display manager

<p>
To start the display manager, log in as root on the console and type:
``<tt/xdm -nodaemon/''.

You can start xdm automatically on bootup by changing the line 
<tscreen><verb>
xdm_flags=NO            # for normal use: xdm_flags=""
</verb></tscreen>
to:
<tscreen><verb>
xdm_flags=""            # for normal use: xdm_flags=""
</verb></tscreen>
in <tt>/etc/rc.conf</tt>. 

<sect1>Running X without the display manager
<p>
The easiest way for new users to start X windows is to type: ``<tt/startx
>&amp; startx.log/''.  Error messages are lost unless you redirect them
because the server takes over the screen.

To get out of X windows, type: ``<tt/exit/'' in the console xterm.
You can customize your X by creating <tt/.xinitrc/, <tt/.xserverrc/,
and <tt/.twmrc/ files in your home directory as described in the xinit
and startx man pages.

<sect>Kernel Support for X

<p>
To make sure X support is enabled under  OpenBSD, the following
line must be in your config file in <tt>/sys/arch/i386/conf</tt>:

<tscreen>
 option APERTURE
</tscreen>

<sect1>Console drivers
<p>
The server supports wscons, the standard OpenBSD/i386 console driver. 

<p>
The pcvt console driver which was the default up to OpenBSD
2.8, is also supported on those releases.

<sect1>Aperture Driver
<p>
By default OpenBSD includes the BSD 4.4 kernel security
feature that disables access to the <tt>/dev/mem</tt> device when in
multi-user mode. But the X server requires
linear access to the display memory in most cases.

OpenBSD requires the aperture driver to be enabled for all X
servers, because the aperture driver also controls access to the
I/O ports of the video boards.
<p>
To enable the aperture driver, once included in the kernel, set
<tscreen><verb>
machdep.allowaperture=2     
</verb></tscreen>
in <tt>/etc/sysctl.conf</tt>.  See the
<htmlurl name="xf86(4)" url="http://www.openbsd.org/cgi-bin/man.cgi?query=xf86&amp;apropos=0&amp;sektion=4&amp;manpath=OpenBSD+Current&amp;arch=i386&amp;format=html">
manual page for details. 
<p>
Another (less recommended) way to enable linear memory and I/O ports
access is to disable the kernel security feature by 
initializing <tt/securelevel/ to -1 in <tt>/etc/rc.securelevel</tt>.
<p>
<quote>
<bf/Caveat:/ the aperture driver only allows one access at a time
(so that the system is in the same security state once X is
launched). This means that if you run multiple servers on multiple
virtual terminals, only the first one will have linear memory access.
Set <tt/securelevel/ to -1 if you need more that one X server at a time.
</quote>

<sect1>MIT-SHM
<p>
OpenBSD supports System V shared memory. If X
detects this support in your kernel, it will support the MIT-SHM
extension.

<sect> Rebuilding the X Distribution

You should configure the distribution by editing
<tt>xc/config/cf/host.def</tt>  before compiling.  To compile the
sources, invoke ``<tt/make World/'' in the xc directory.


<p> 
Note that OpenBSD project now has its own source tree, 
with some local modifications. You may want
to start with this tree to rebuild from sources.  The OpenBSD XF4
source tree is available by anoncvs from all OpenBSD anoncvs
servers. See <htmlurl url="http://www.openbsd.org/anoncvs.html"
name="http://www.openbsd.org/anoncvs.html"> for details on anoncvs.

<label id="otherarch">

<p>
X11R&relvers;  also compiles on other OpenBSD architectures. 
<sect1>X11R&relvers; on OpenBSD/alpha
<p>
The X server is known to work on some VGA cards in alpha
machines that support BWX I/O, with OpenBSD 3.2 and higher. 
<p>
The following cards have been successfully tested for now:
<itemize>
<item>3DLabs Permedia 2 (8, 15, 16 and 24 bits depth) 
<item>ATI Rage Pro (works with 'Option "NoAccel"')
<item>Cirrus Logic CL5430 (works with 'Option "NoAccel"')
<item>Cirrus Logic GD5446 (8, 16 and 24 bits depth)
<item>Matrox MGA 2064 (8, 16 and 24 bits depth)
</itemize>
<p>
Note that this version of doesn't work on TGA cards. The
version shipped with OpenBSD 3.1 and higher includes an OS-specific
driver <em/wsfb/ that is used to support TGA cards. 

<sect1>X11R&relvers; on OpenBSD/macppc
<p>
The X server is currently known to work on the G4 Macs and new
iBooks with ATI Rage 128 cards running OpenBSD 3.0 or later.
Other machines are more or less untested. Earlier OpenBSD versions
lack some kernel support for it.
<p>
Use xorgconfig to build a /etc/X11/xorg.conf file before starting 
the server for the first time. 
<p>
For the Titanium Powerbook G4, you can try the following mode line in
<tt>/etc/X11/xorg.conf</tt> to match the flat panel resolution:

<tscreen><verb>
Modeline "1152x768" 64.995 1152 1213 1349 1472  768 771 777 806 -HSync -VSync
</verb></tscreen>

<sect1>OpenBSD/sparc
<p>
OpenBSD 3.2 on sparc switched to the wscons device driver and now uses
the OS specific <em/wsfb/ driver in the X server. This driver is
not included in X11R&relvers;. Please use the version shipped with
OpenBSD instead. 

<sect1>OpenBSD/sparc64
<p>
This version only has support for X clients on
OpenBSD/sparc64. Note that the version shipped with OpenBSD also has
support for the X server on both SBus and PCI based machines. 


<sect>Building New X Clients

<p>
The easiest way to build a new client (X application) is to use
<tt/xmkmf/ if an <tt/Imakefile/ is included in the sources.  Type
``<tt/xmkmf -a/'' to create the Makefiles, check the configuration if
necessary and type ``<tt/make/''.  Whenever you install additional man
pages you should update <tt/whatis.db/ by running ``<tt>makewhatis
/usr/X11R6/man</tt>''.

<sect> Thanks
<p>
Many thanks to all people who contributed to make X11R&relvers; work on
*BSD, in particular:
<bf/David Dawes/,
<bf/Todd Fries/,
<bf/Rod Grimes/,
<bf/Charles Hannum/,
<bf/Amancio Hasty/, 
<bf/Christoph Robitschko/,
<bf/Matthias Scheler/,
<bf/Michael Smith/,
<bf/Ignatios Souvatzis/,
<bf/Jack Velte/,
<bf/Nate Williams/ and
<bf/Pace Willison/.

</article>