<sect1 id="config">
<title>Runtime Configuration Options</title>

<para>
This section of the document by Hans, 
<ulink
url="mailto:lermen@fgan.de"
>&#60;lermen@fgan.de&#62;</ulink
>. Last
updated on May 4, 2007, by Bart Oldeman.
</para>

<para>
Most of DOSEMU configuration is done during runtime and per default it
can use the system wide configuration file dosemu.conf (which is often
situated in /etc or /etc/dosemu) optionally followed by the users
~/.dosemurc and additional configurations statements on the commandline
(-I option). If /etc/dosemu.users exists then dosemu.conf is searched for
in /etc and otherwise in /etc/dosemu (or an alternative sysconfdir
compiletime-setting).
</para>

<para>
The default dosemu.conf and ~/.dosemurc have all settings commented
out for documentation purposes; the commented out values are the
ones that DOSEMU uses by default. Note that a non-suid type of installation 
does not need the dosemu.users and dosemu.conf files, and the main 
per-user configuration file is $HOME/.dosemurc.
However, for security reasons, a suid-root installation will not
run without dosemu.users, and in that case certain dosemu.conf settings
are ignored by ~/.dosemurc.
</para>
 
<para>
In fact dosemu.conf and ~/.dosemurc (which have identical syntax)
are included by the systemwide configuration script global.conf which,
by default, is built into the DOSEMU binary.  As a normal user 
you won't ever think on editing this, only dosemu.conf and your personal 
~/.dosemurc.  The syntax of global.conf is described in detail in 
README-tech.txt, so this is skipped here. However, the option -I string too
uses the same syntax as global.conf, hence, if you are doing some special
stuff (after you got familar with DOSEMU) you may need to have a look there.
</para>

<para>
The first file expected (and interpreted) before any other configuration
(such as global.conf, dosemu.conf and ~/.dosemurc) is /etc/dosemu.users
or /etc/dosemu/dosemu.users. As mentioned above, this file is entirely
optional for non-suid-root (default) installations. 
Within this file the general permissions are set:
</para>

<para>

<itemizedlist>
<listitem>

<para>
 which users are allowed to use DOSEMU.
</para>
</listitem>
<listitem>

<para>
 which users are allowed to use DOSEMU suid root.
</para>
</listitem>
<listitem>

<para>
 which users are allowed to have a private lib dir.
</para>
</listitem>
<listitem>

<para>
 what kind of access class the user belongs to.
</para>
</listitem>
<listitem>

<para>
 what special configuration stuff the users needs
</para>
</listitem>

</itemizedlist>

</para>

<para>
and further more:

<itemizedlist>
<listitem>

<para>
 whether the lib dir (DOSEMU_LIB_DIR) resides elsewhere.
</para>
</listitem>
<listitem>

<para>
 setting the loglevel.
</para>
</listitem>

</itemizedlist>

</para>

<para>
Except for lines starting with `xxx=' (explanation below),
each line in dosemu.user corresponds to exactly <emphasis>one</emphasis> valid user count,
the special user `all' means any user not mentioned earlier. Format:

<screen>
  [ &#60;login&#62; | all ] [ confvar [ confvar [ ... ] ] ]
</screen>

</para>

<para>
The below example is from etc/dosemu.users.secure, which you may copy
to /etc/dosemu.users.

<screen>
  root c_all     # root is allowed to do all weird things
  nobody nosuidroot guest # variable 'guest' is checked in global.conf
                          # to allow only DEXE execution
  guest nosuidroot guest  # login guest treated as `nobody'
  myfriend c_all unrestricted private_setup
  myboss nosuidroot restricted private_setup
  all nosuidroot restricted # all other users have normal user restrictions
</screen>

Note that the above `restricted' is checked in global.conf and will
disable all secure relevant feature. Setting `guest' will force
setting `restricted' too.
</para>

<para>
The use of `nosuidroot' will force a suid root dosemu binary to exit,
the user may however use a non-suid root copy of the binary.
For more information on this look at README-tech,
chapter 11.1 `Privileges and Running as User'
</para>

<para>
Giving the keyword `private_setup' to a user means he/she can have a private
DOSEMU lib under $HOME/.dosemu/lib. If this directory is existing, DOSEMU
will expect all normally under DOSEMU_LIB_DIR within that directory.
As this would be a security risk, it only will be allowed, if the used DOSEMU
binary is non-suid-root. If you really trust a user you may additionally give
the keyword `unrestricted', which will allow this user to execute a suid-root
binary even on a private lib directory (though, be aware).
</para>

<para>
In addition, dosemu.users can be used to define some global settings, which
must be known before any other file is accessed, such as:

<screen>
  default_lib_dir= /opt/dosemu  # replaces DOSEMU_LIB_DIR
  log_level= 2                  # highest log level
</screen>

</para>

<para>
With `default_lib_dir=' you may move DOSEMU_LIB_DIR elsewhere, this mostly
is interesting for distributors, who want it elsewhere but won't patch the
DOSEMU source just for this purpose. But note, the dosemu supplied scripts
and helpers may need some adaption too in order to fit your new directory.
</para>

<para>
The `log_level=' can be 0 (never log) or 1 (log only errors) or 2 (log all)
and controls the ammount written to the systems log facility (notice).
This keyword replaces the former /etc/dosemu.loglevel file, which now is
obsolete.
</para>

<para>
Nevertheless, for a first try of DOSEMU you may prefer etc/dosemu.users.easy,
which just contains

<screen>
  root c_all
  all c_all
</screen>

to allow everybody all weird things. For more details on security issues
have a look at chapter 3.
</para>

<para>
After the file dosemu.users, the file dosemu.conf (via global.conf, which
may be built-in) is interpreted,
and only during global.conf parsing the access to all configuration options is
allowed. dosemu.conf normally lives in the same directory as dosemu.users,
for instance /etc/dosemu or /etc (that is, sysconfdir in compiletime-settings).

Your personal ~/.dosemurc is included directly after dosemu.conf,
but has less access rights (in fact the lowest level), all variables you
define within ~/.dosemurc transparently are prefixed with `dosemu_' such
that the normal namespace cannot be polluted (and a hacker cannot overwrite
security relevant enviroment variables). Within global.conf only those
~/.dosemurc created variables, that are needed are taken over and may
overwrite those defined in dosemu.conf.
</para>

<para>
The dosemu.conf (global.conf) may check for the configuration variables,
that are set in dosemu.users and optionaly include further configuration
files. But once dosemu.conf (global.conf) has finished interpretation,
the access to secure relevant configurations is (class-wise) restricted while
the following interpretation of (old) .dosrc and -I statements.
</para>

<para>
For more details on security settings/issues look at README-tech.txt, for
now (using DOSEMU the first time) you should need only the below description
of dosemu.conf (~/.dosemurc)
</para>

<sect2>
<title>Format of dosemu.conf and ~/.dosemurc</title>

<para>
All settings are variables, and have the form of
</para>

<para>

<screen>
  $_xxx = (n)
</screen>

or

<screen>
  $_zzz = "s"
</screen>

</para>

<para>
where `n' is a numerical or boolean value and `s' is a string.
Note that the brackets are important, else the parser will not decide
for a number expression. For numbers you may have complete expressions
( such as (2*1024) ) and strings may be concatenated such as
</para>

<para>

<screen>
  $_zzz = "This is a string containing '", '"', "' (quotes)"
</screen>

</para>

<para>
Hence a comma separated list of strings is concatenated.
All these settings are also environment variables. You can override them
by prefixing with dosemu_, e.g.
<screen>
dosemu__X_title="DOS was in the BOX" dosemu
</screen>
temporarily changes the X window title.
</para>

<sect3>
<title>Disks, boot directories and floppies</title>

<para>
The parameter settings are tailored to fit the recommended
usage of disk and floppy access. There are other methods too, but for these
you have to look at README-tech.txt (and you may need to modify global.conf).
We strongly recommend that you use the proposed techique. Here the normal
setup:
</para>

<para>

<screen>
# List of hdimages or boot directories under 
# ~/.dosemu, the system config directory (/etc/dosemu by default), or
# syshdimagedir (/var/lib/dosemu by default) assigned in this order
# such as "hdimage_c directory_d hdimage_e"
# Absolute pathnames are also allowed.
  $_hdimage = "drives/*"
  $_floppy_a ="threeinch" # or "fiveinch" or empty, if not existing
  $_floppy_b = ""       # dito for B:
  $_cdrom = "/dev/cdrom" # list of CDROM devices
</screen>

</para>

<para>
A hdimage is
a file containing a virtual image of a DOS-FAT filesystem. Once you have
booted it, you (or autoexec.bat) can use `lredir' to access any directory
in your Linux tree as DOS drive (a -t msdos mounted too).
Look at chapter 5 (Using Lredir) for more details.
If you want to create your own hdimage use "mkfatimage16" (see the manual
page). To make it bootable you can make it, say, drive F:, and use
"SYS F:" at the DOS prompt. 
The DOSEMU-HOWTO explains how to manipulate it using mtools.
</para>

<para>
You can also specify a Linux directory containing all what you want to have
under your DOS C:. Copy your IO.SYS, MSDOS.SYS or equivalent to that
directory (e.g. DOSEMU_LIB_DIR/bootdir), set

<screen>
   $_hdimage = "bootdir"
</screen>

and up it goes. Alternatively you can specify
an absolute path such as "/dos" or "/home/username/dosemu/freedos". 
DOSEMU makes a lredir'ed drive out of it and can boot from it. 
You can edit the config.sys and the autoexec.bat within this directory 
before you start dosemu.
Further more, you may have a more sohisticated setup. Given you want to run
the same DOS drive as you normal have when booting into native DOS,
then you just mount you DOS partition under Linux (say to /dos) and
put links to its subdirectories into the boot dir. This way you can decide
which files/directories have to be visible under DOSEMU and which have to be
different. Here a small and not complete example bootdir setup:

<screen>
  config.sys
  autoexec.bat
  command.com -&#62; /dos/command.com
  io.sys -&#62; /dos/io.sys
  msdos.sys -&#62; /dos/msdos.sys
  dos -&#62; /dos/dos
  bc -&#62; /dos/bc
  windows -&#62; /dos/windows
</screen>

</para>

<para>
As a further enhancement of your drives setup you may even use the following
strategy: given you have the following directory structure in one the
directories where the $_hdimage setting applies (this is done by default
in ~/.dosemu and in /etc/dosemu)

<screen>
  drives/c
  drives/d
</screen>

where <emphasis>c</emphasis> and <emphasis>d</emphasis> are symbolic
links to appropriate DOS useable directories, then the following single
statement

<screen>
  $_hdimage = "drives/*"
</screen>

will assign all these directories to drive C: and D: respectively.
Note, however, that the <emphasis>order</emphasis> in which the directories under drives/*
are assigned comes from the order given by /bin/ls. Hence the folling

<screen>
  drives/x
  drives/a
</screen>

will assign C: to drives/a and D: to drives/x, keep that in mind.
</para>

<para>
In some rare cases you may have problems accessing Lredir'ed drives
(especially when your DOS application refuses to run on a 'network drive'),
For this to overcome you may need to use so-called `partition access',
use a floppy, or a special-purpose hdimage. The odd
with partition access is, that you <emphasis>never</emphasis> should have
those partition
mounted in the Linux file system at the same time as you use it in DOSEMU
(which is quite uncomfortable and dangerous on a multitasking OS such as
Linux ). Though DOSEMU checks for mounted partitions, there may be races
that are not caught. In addition, when your DOSEMU crashes, it may leave
some FAT sectors unflushed to the disk, hence destroying the partition.
Anyway, if you think you need it, you must have r/w access to the partition
in /dev, and you have to `assign' real DOS partitions as follows:
</para>

<para>

<screen>
  $_hdimage = "hdimage.first /dev/hda1 /dev/sdc4:ro"
</screen>

</para>

<para>
The above will have `hdimage.first' as booted drive C:, /dev/hda1 as D:
(read/write) and /dev/sdc4 as E: (readonly). You may have any kind of order
within `$_hdimage', hence
</para>

<para>

<screen>
  $_hdimage = "/dev/hda1 hdimage.first /dev/sdc4:ro"
</screen>

</para>

<para>
would have /dev/hda1 as booted drive C:. Note that the access to the
/dev/* devices <emphasis>must</emphasis> be exclusive (no other process should use it)
except for `:ro'.
</para>

</sect3>

<sect3>
<title>Controlling amount of debug output</title>

<para>
DOSEMU will help you find problems, when you enable its debug messages.
These will go into the file, that you defined via the `-o file' or `-O'
commandline option (the latter prints to stderr). If you do not specify
any -O or -o switch, then the log output will be written to ~/.dosemu/boot.log. 
You can preset the kind of debug output via
</para>

<para>

<screen>
  $_debug = "-a"
</screen>

where the string contains all you normally may pass to the `-D' commandline
option (look at the man page for details). 
</para>

</sect3>

<sect3>
<title>Basic emulation settings</title>

<para>
Whether a numeric processor should be shown to the DOS space

<screen>
  $_mathco = (on)
</screen>

</para>

<para>
Which type of CPU should be emulated (NOTE: this is not the one you
are running on, but your setting may not exeed the capabilities of
the running CPU). Valid values are:  80[345]86

<screen>
  $_cpu = (80386)
</screen>

</para>

<para>
To let DOSEMU use the Pentium cycle counter (if availabe) to do better timing
use the below
</para>

<para>

<screen>
  $_rdtsc = (off)   # or on
</screen>

Note that the RDTSC can be unreliable on SMP systems, and in combination with
power management (APM/ACPI).
</para>

<para>
For the above `rdtsc' feature DOSEMU needs to know the exact CPU clock,
it normally calibrates it itself, but is you encounter a wrong mesurement
you may overide it such as

<screen>
  $_cpuspeed = (166.666)  # 0 = let DOSEMU calibrate
</screen>

</para>

<para>
If you have a PCI board you may allow DOSEMU to access the PCI
configuration space by defining the below

<screen>
  $_pci = (auto)    # or auto, or off
</screen>

</para>

<para>
NOTE: `$_pci' can <emphasis>not</emphasis> be overwritten by ~/.dosemurc.
The "on" setting can be very dangerous because it gives DOSEMU complete
write access; you need to edit dosemu.users to enable it.
In console graphics mode, some video card BIOSes need some PCI
configuration space access,
which is enabled by the default (auto) setting. This setting is far more
restricted and less dangerous.
</para>

<para>
Starting with dosemu-1.0 there is a flexible way to handle the mapping
strategy used by DOSEMU, which is needed by video emulation, EMS,
DPMI and XMS support and other things to map a given page of memory to the
required virtual DOS address space.
</para>

<para>
Normally DOSEMU will detect the proper mapping driver for the kernel you are
using, however, in some cases you may want to define it explicitely to
overcome eventual problems. For this you can specify

<screen>
  $_mapping= "mapfile"
</screen>

to force the use of the driver, which uses a temporary file.
</para>

<para>
If you are using a kernel above 2.3.40, you may use

<screen>
  $_mapping= "mapshm"
</screen>
which uses a POSIX shared memory object (the default) or
<screen>
  $_mapping= "mapashm"
</screen>
which uses anonymous shared memory (in case the above gives problems).
</para>

<para>
Note, that in case of `mapfile' and `mapshm' the size of the file or the
segment depend on how much memory you configured for XMS, EMS and DPMI
(see below).
You should take care yourself that you have enough diskspace
for 'mapfile'. For 'mapshm' the tmpfs mount option 'size=nbytes' controls
the amount of space; by default it is half of the (real machine) memory.
</para>

<para>
Defining the memory layout, which DOS should see:

<screen>
  $_xms = (8192)          # in Kbyte
  $_ems = (2048)          # in Kbyte
  $_ems_frame = (0xe400)
  $_dpmi = (0x5000)       # in Kbyte
  $_dosmem = (640)        # in Kbyte, &#60; 640
</screen>

Note that (other as in native DOS) each piece of mem is separate, hence
DOS perhaps will show other values for 'extended' memory. To use EMS
memory you must load the supplied ems.sys device driver. For XMS memory
you must either use a DOS XMS driver such as himem.sys, himem.exe,
fdxms.sys, or fdxxms.sys, or the internal XMS driver via ems.sys.
</para>

<para>
If you want mixed operation on the filesystem, from which you
boot DOSEMU (native and via DOSEMU), it may be necessary to have two
separate sets of config.sys and system.ini. DOSEMU can
fake a different file extension, so DOS will get other files when
running under DOSEMU. Faking autoexec.bat cannot happen in a reliable
fashion, so if you would like to use an autoexec.bat replacement then
just use the SHELL command in config.XXX, like this:
</para>
<para>
SHELL=COMMAND.COM /P /K AUTOEMU.BAT
</para>

<para>

<screen>
  $_emusys = ""    # empty or 3 char., config.sys   -&#62; config.XXX
  $_emuini = ""    # empty or 3 char., system.ini   -&#62; system.XXX
</screen>

</para>

<para>
As you would realize at the first glance: DOS will <emphasis>not</emphasis> have the
the CPU for its own. But how much it gets from Linux, depends on the setting
of `hogthreshold'.
The HogThreshold value determines how nice Dosemu will be about
giving other Linux processes a chance to run.
</para>

<para>

<screen>
  $_hogthreshold = (1)   # 0 == all CPU power to DOSEMU
                         # 1 == max power for Linux
                         # &#62;1   the higher, the faster DOSEMU will be
</screen>

</para>

</sect3>

<sect3>
<title>Code page and character set</title>

<para>
To select the character set and code page for use with DOSEMU you have

<screen>
  $_external_char_set = "XXX"
</screen>
where XXX is one of
<screen>
"cp437", "cp737", "cp773", "cp775", "cp850", "cp852", "cp857", "cp860",
"cp861", "cp862", "cp863", "cp864", "cp865", "cp866", "cp869", "cp874",
"cp1125", "cp1251"
"iso8859-1", "iso8859-2", "iso8859-3", "iso8859-4", "iso8859-5", "iso8859-6",
"iso8859-7", "iso8859-8", "iso8859_9", "iso8859-14", "iso8859-15", "koi8-r"
"koi8-u", "koi8-ru", "utf8"
</screen>
</para>

<para>
The external character set is used to:
<itemizedlist>
<listitem> <para>
    compute the unicode values of characters coming in from the terminal
</para> </listitem>
<listitem> <para>
    compute the character set index of unicode characters output to
    a terminal display screen.
</para> </listitem>
</itemizedlist>
The default is to use "", which denotes the current locale, and is usually
the right setting.
</para>

<para>
If you set a DOS external character set, then it is to the user
to load a proper DOS font (cp437.f16, cp850.f16 or cp852.f16 on the
console).
</para>

<para>
<screen>
  $_internal_char_set = "XXX"
</screen>
where XXX is one of:
<screen>
"cp437", "cp737", "cp773", "cp775", "cp850", "cp852", "cp857", "cp860",
"cp861", "cp862", "cp863", "cp864", "cp865", "cp866", "cp869", "cp874"
"cp895", "cp1125", "cp1251", "bg-mik"
</screen>
</para>

<para>
The internal character set is used to:
<itemizedlist>
<listitem> <para>
       compute the unicode value of characters of video memory,
       when using DOSEMU in a terminal or using X with a unicode
       font.
</para> </listitem>
<listitem> <para>
       compute the character set index of unicode characters 
       returned by bios keyboard translation services.
</para> </listitem>
<listitem> <para>
     compute the unicode values of characters in file names.
</para> </listitem>
</itemizedlist>
</para>

</sect3>

<sect3>
<title>Terminals</title>

<para>
This section applies whenever you run DOSEMU remotely, in an xterm or
on the Linux console without graphics.
Color terminal support is now built into DOSEMU.  Skip this section for
now to use terminal defaults, until you get DOSEMU to work.

<screen>
  $_term_color = (on)   # terminal with color support
  $_term_updfreq = (4)  # time between refreshs (units: 20 == 1 second)
  $_escchar = (30)      # 30 == Ctrl-^, special-sequence prefix
</screen>

`term_updfreq' is a number indicating the frequency of terminal updates of
the screen. The smaller the number, the more frequent.  A value of 20 gives
a frequency of about one per second, which is very slow.
`escchar' is a number (ascii code below 32) that specifies the control
character used as a prefix character for sending alt, shift, ctrl, and
function keycodes.  The default value is 30 which is Ctrl-^. So, for
example,

<screen>
  F1 is 'Ctrl-^1', Alt-F7 is 'Ctrl-^s Ctrl-^7'.
  For online help, press 'Ctrl-^h' or 'Ctrl-^?'.
</screen>

</para>

</sect3>

<sect3>
<title>Keyboard settings</title>

<para>
When running DOSEMU from console (also remote from console) or X you
may need to define a proper keyboard layout. It is possible to let
DOSEMU do this work automatically for you (see <emphasis>auto</emphasis> below), however,
this may fail and you'll end up defining it explicitely. This is done either
by choosing one on the internal keytables or by loading an external
keytable from DOSEMU_LIB_DIR/keymap/* (which you may modify according
to your needs). Both sets have identical names (though you may add
any new one to DOSEMU_LIB_DIR/keymap/*):

<screen>
  be              finnish         hu-latin2       sg-latin1
  de              finnish-latin1  it              sw
  de-latin1       fr              keyb-no         uk
  dk              fr-latin1       no-latin1       us
  dk-latin1       hr-cp852        po
  dvorak          hr-latin2       sf
  es              hu              sf-latin1
  es-latin1       hu-cwi          sg              jp106
  cz-qwerty       cz-qwertz
</screen>

You define an internal keytable such as

<screen>
  $_layout = "name"
</screen>

where `name' is one of the above. To load a keytable you just prefix
the string with "load" such as

<screen>
  $_layout = "load de-latin1"
</screen>

</para>

<para>
Note, however, that you have to set

<screen>
  $_X_keycode = (on)
</screen>

to use this feature under X, because by default the keytable is
forced to be neutral (us). Normally you will have the correct settings
of your keyboard given by the X-server.
</para>

<para>
The most comfortable method, however, is to first let DOSEMU set the
keyboard layout itself. This involves 2 parts and can be done by setting

<screen>
  $_X_keycode = (auto)
</screen>

which  checks for existence of the X keyboard extension and if yes,
it sets $_X_keycode to 'on', that means the DOSEMU keytables
are active. The second part (which is independent from $_X_keycode)
can be set by

<screen>
  $_layout = "auto"
</screen>

DOSEMU then queries the keyboard layout from the kernel or X (which
only does work on the console or X, but not in remote text terminals)
and generates a new DOSEMU
keytable out of the kernel information. This currently seems
only to work for latin-1 layouts, the latin-2 type of accents
seem not to exist so far in the kernel (linux/keyboard.h).
The resulting table can be monitor with DOSEMU 'keytable dump'
feature (see README-tech.txt) for details).
</para>

<para>
When being on console you might wish to use raw keyboard, especially
together with some games, that don't use the BIOS/DOS to get their
keystrokes.

<screen>
  $_rawkeyboard = (1)
</screen>

However, be carefull, when the application locks, you may not be able
to switch your console and recover from this. For details on recovering
look at README-tech.txt (Recovering the console after a crash).
</para>

</sect3>

<sect3>
<title>X Support settings</title>

<para>
If DOSEMU is running in its own X-window (not xterm), you may need to
tailor it to your needs. Here a summary of the settings and a brief
description what they mean. A more detailed description of values
one can be found at chapter 2.2.14 (X Support settings) of README-tech.txt
</para>

<para>

<screen>
$_X_updfreq = (5)       # time between refreshs (units: 20 == 1 second)
$_X_title = "DOS in a BOX" # Title in the top bar of the window
$_X_icon_name = "xdos"  # Text for icon, when minimized
$_X_keycode = (off)     # on == translate keybord via dosemu keytables
$_X_blinkrate = (8)     # blink rate for the cursor
$_X_font = ""           # basename from /usr/X11R6/lib/X11/fonts/misc/*
                        # (without extension) e.g. "vga"
$_X_mitshm = (on)       # Use shared memory extensions
$_X_sharecmap = (off)   # share the colormap with other applications
$_X_fixed_aspect = (on) # Set fixed aspect for resize the graphics window
$_X_aspect_43 = (on)    # Always use an aspect ratio of 4:3 for graphics
$_X_lin_filt = (off)    # Use linear filtering for &#62;15 bpp interpol.
$_X_bilin_filt = (off)  # Use bi-linear filtering for &#62;15 bpp interpol.
$_X_mode13fact = (2)    # initial factor for video mode 0x13 (320x200)
$_X_winsize = ""        # "x,y" of initial windows size
$_X_gamma = (1.0)       # gamma correction
$_X_vgaemu_memsize = (1024) # size (in Kbytes) of the frame buffer
                        # for emulated vga
$_X_lfb = (on)  # use linear frame buffer in VESA modes
$_X_pm_interface = (on) # use protected mode interface for VESA modes
$_X_mgrab_key = ""      # KeySym name to activate mouse grab, empty == off
$_X_vesamode = ""       # "xres,yres ... xres,yres"
                        # List of vesamodes to add. The list has to contain
                        # SPACE separated "xres,yres" pairs
</screen>

</para>

</sect3>

<sect3>
<title>Builtin ASPI SCSI Driver</title>

<para>
The builtin ASPI driver (a SCSI interface protocol defined by Adaptec) can be
used to run DOS based SCSI drivers that use this standard (most SCSI devices
ship with such a DOS driver). This enables you to run hardware on Linux, that
normally isn't supported otherwise, such as CD writers, Scanners e.t.c.
The driver was successfully tested with Dat-streamers, EXABYTE tapedrives,
JAZ drives (from iomega) and CD writers. To make it work under DOSEMU
you need

<itemizedlist>
<listitem>

<para>
 to configure $_aspi to define which
of the /dev/sgX devices you want to show up in DOSEMU.
</para>
</listitem>
<listitem>

<para>
 to load the DOSEMU aspi.sys stub driver within config.sys
(e.g. DEVICE=ASPI.SYS) <emphasis>before</emphasis> any ASPI using driver.
</para>
</listitem>

</itemizedlist>

</para>

<para>
The $_aspi variable takes strings listing all generic SCSI
devices, that you want give to DOSEMU. NOTE: You should make sure,
that they are <emphasis>not</emphasis> used by Linux elsewhere, else you would come into
<emphasis>much</emphasis> trouble. To help you not doing the wrong thing, DOSEMU can
check the devicetype of the SCSI device such as

<screen>
$_aspi = "sg2:WORM"
</screen>

in which case you define /dev/sg2 being a CD writer device. If you omit
the type,

<screen>
                                                    
$_aspi = "sg2 sg3 sg4"
</screen>

DOSEMU will refuse any device that is a disk drive (imagine, what would happen
if you try to map a CD writer to the disk which contains a mounted Linux FS?).
If you <emphasis>want</emphasis> to map a disk drive to DOSEMU's ASPI driver, you need to
tell it explicitely

<screen>
$_aspi = "sg1:Direct-Access"
</screen>

or

<screen>
$_aspi = "sg1:0"
</screen>

and as you can see, `Direct-Access' is the devicetype reported by

<screen>
$ cat /proc/scsi/scsi
</screen>

which will list all SCSI devices in the order they are assigned to
the /dev/sgX devices (the first being /dev/sg0). You may also use the
DOSEMU supplied tool `scsicheck' (in src/tools/peripher), which helps
a lot to get the configuration right:

<screen>
$ scsicheck
sg0 scsi0 ch0 ID0 Lun0 ansi2 Direct-Access(0) IBM DCAS-34330 S61A
    $_aspi = "sg0:Direct-Access:0" (or "0/0/0/0:Direct-Access:0")
sg1 scsi0 ch0 ID5 Lun0 ansi2 Direct-Access(0) IOMEGA ZIP 100 D.08
    $_aspi = "sg1:Direct-Access:5" (or "0/0/5/0:Direct-Access:5")
sg2 scsi0 ch0 ID6 Lun0 ansi2 CD-ROM(5) TOSHIBA CD-ROM XM-5701TA 0167
    $_aspi = "sg2:CD-ROM:6" (or "0/0/6/0:CD-ROM:6") &#60;== multiple IDs
sg3 scsi1 ch0 ID4 Lun0 ansi2 Sequential-Access(1) HP C1533A 9503
    $_aspi = "sg3:Sequential-Access:4" (or "1/0/4/0:Sequential-Access:4")
sg4 scsi1 ch0 ID6 Lun0 ansi1 WORM(4) IMS CDD522/10 1.07
    $_aspi = "sg4:WORM:6" (or "1/0/6/0:WORM:6") &#60;== multiple IDs
</screen>

</para>

<para>
In the above example there are two scsi hostadapters (scsi0 and scsi1) and
DOSEMU will not show more than <emphasis>one</emphasis> hostadapter to DOS (mapping them
all into one), hence you would get problems accessing sg2 and sg4. For this
you may remap a different targetID such as

<screen>
$_aspi = "sg2:CD-ROM:5 sg4:WORM"
</screen>

and all would be fine. From the DOS side the CD-ROM appears as target 5
and the WORM (CD writer) as target 6.
Also from the above scsicheck output, you can see, that you can opt
to use a `host/channel/ID/LUN' construct in place of `sgX' such as

<screen>
$_aspi = "0/0/6/0:CD-ROM:5 1/0/6/0:WORM"
</screen>

which is exactly the same as the above example, exept it will assign
the right device, even if for some reasons you have changed the order
in which sgX device are assigned by the kernel. Those changes happen, if
you turned off power of one device `between' or if you play with dynamic
allocation of scsi devices via the /proc/scsi interface such as

<screen>
echo "scsi remove-single-device 0 0 5 0" &#62;/proc/scsi/scsi
</screen>

to delete a device and

<screen>
echo "scsi add-single-device 0 0 5 0" &#62;/proc/scsi/scsi
</screen>

to add a device. HOWEVER, we <emphasis>strongly</emphasis> discourage
you to use these kernel feature for temporaryly switching off
power of connected devices or even unplugging them: normal SCSI busses
are <emphasis>not</emphasis> hotpluggable. Damage may happen and uncontroled voltage
bursts during power off/on may lock your system !!!
</para>

<para>
Coming so far, <emphasis>one</emphasis> big problem remains: the (hard coded) buffersize for
the sg devices in the Linux kernel (default 32k) may be to small for DOS
applications and, if your distributor yet didn't it, you may need to
recompile your kernel with a bigger buffer. The buffer size is defined
in linux/include/scsi/sg.h and to be on the secure side you may define

<screen>
#define SG_BIG_BUFF (128*1024-512)  /* 128 Kb buffer size */
</screen>

though, CD writers are reported to work with 64Kb and the `Iomega guest'
driver happily works with the default size of 32k.
</para>

</sect3>

<sect3>
<title>COM ports and mice</title>

<para>
We have simplified the configuration for mice and serial ports and
check for depencies between them. If all strings in the below example
are empty, then no mouse and/or COM port is available. Note. that you
need <emphasis>no</emphasis> mouse.com driver installed in your DOS environment, DOSEMU
has the mousedriver builtin. The mouse settings below only apply to
DOSEMU in the Linux console; in X and terminals the mouse is detected
automatically. The below example is such a setup
</para>

<para>

<screen>
  $_com1 = ""           # e.g. "/dev/mouse" or "/dev/ttyS0"
  $_com2 = "/dev/modem" # e.g. "/dev/modem" or "/dev/ttyS1"

  $_mouse = "microsoft" # one of: microsoft, mousesystems, logitech,
                        # mmseries, mouseman, hitachi, busmouse, ps2
  $_mouse_dev = "/dev/mouse" # one of: com1, com2 or /dev/mouse
  $_mouse_flags = ""	# list of none or one or more of:
  			# "emulate3buttons cleardtr"
  $_mouse_baud = (0)	# baudrate, 0 == don't set
</screen>

</para>

<para>
The above example lets you have your modem on COM2, COM1 is spare (as
you may have your mouse under native DOS there and don't want to change
the configuration of your modem software between boots of native DOS and Linux)
</para>

<para>
However, you may use your favorite DOS mouse driver and directly let it
drive COM1 by changing the below variables (rest of variables unchanged)
</para>

<para>

<screen>
  $_com1 = "/dev/mouse"
  $_mouse_dev = "com1"
</screen>

</para>

<para>
And finaly, when you have a PS/2 or USB mouse on your machine you use
the built-in mouse driver (not your mouse.com) to get it work:
( again leaving the rest of variables unchanged)
</para>

<para>

<screen>
  $_mouse = "ps2"
  $_mouse_dev = "/dev/mouse"  
</screen>

</para>

<para>
When using a PS/2 or USB mouse or when having more than 2 serial ports you may
of course assign _any_ free serialdevice to COM1, COM2. The order doesn't
matter:
</para>

<para>

<screen>
  $_com1 = "/dev/ttyS2"
  $_com2 = "/dev/ttyS0"
</screen>

</para>

</sect3>

<sect3>
<title>Printers</title>

<para>
Printer is emulated by piping printer data to your normal Linux printer.
The belows tells DOSEMU which printers to use. The `timeout' tells DOSEMU
how long to wait after the last output to LPTx before considering the
print job as `done' and to close it.
</para>

<para>

<screen>
# Print commands to use for LPT1, LPT2 and LPT3.
# Default: "lpr -l, lpr -l -P lpt2, lpr -l P lpt3"
# Which means: use the default print queue for LPT1, "lpt2" queue for LPT2,
# "lpt3" queue for LPT3. "-l" means raw printing mode (no preprocessing).

$_lpt1 = "lpr -l"
$_lpt2 = "lpr -l -P lpt2"
$_lpt3 = "lpr -l -P lpt3"

$_printer_timeout = (20)# idle time in seconds before spooling out
</screen>

</para>

</sect3>

<sect3>
<title>Sound</title>

<para>
The following settings will tell DOSEMU to emulate an SB16 sound
card using your Linux sound drivers. For more information see
sound-usage.txt.
</para>

<para>

<screen>
$_sound = (on)            # sound support on/off
$_sb_base = (0x220)       # base IO-address (HEX)
$_sb_irq = (5)            # IRQ
$_sb_dma = (1)            # Low 8-bit DMA channel
$_sb_hdma = (5)           # High 16-bit DMA channel
$_sb_dsp = "/dev/dsp"     # Path to the sound device
$_sb_mixer = "" 	  # path to the mixer control
$_mpu_base = (0x330)      # base address for the MPU-401 chip (HEX)
</screen>

</para>

</sect3>

<sect3>
<title>Joystick</title>

<para>
Here are the settings for Joystick emulation.
</para>

<para>

<screen>
$_joy_device = "/dev/js0 /dev/js1"     
			  # 1st and 2nd joystick device 
                          # e.g. "/dev/js0" or "/dev/js0 /dev/js1"
                          #      (or "" if you don't want joystick support)
			  # 
$_joy_dos_min = (1)	  # range for joystick axis readings, must be > 0
$_joy_dos_max = (150)	  # avoid setting this to > 250
$_joy_granularity = (1)   # the higher, the less sensitive - 
			  # useful if you have a wobbly joystick
                          #
$_joy_latency = (1)       # delay between nonblocking linux joystick reads
                          # increases performance if >0 and processor>=Pentium
                          # recommended: 1-50ms or 0 if unsure
</screen>

</para>

</sect3>

<sect3>
<title>Networking under DOSEMU</title>

<para>
Turn the following option `on' if you require IPX/SPX emulation,
there is no need to load IPX.COM within the DOS session.
( the option does not emulate LSL.COM, IPXODI.COM, etc. )
And NOTE: You must have IPX protocol configured into the kernel.
</para>

<para>

<screen>
  $_ipxsupport = (on)
</screen>

</para>

<para>
Enable Novell 8137-&#62;raw 802.3 translation hack in new packet driver.
</para>

<para>

<screen>
  $_novell_hack = (on)
</screen>

</para>

<para>
If you make use of TUN/TAP driver, then you can select it via
</para>

<para>

<screen>
  $_vnet = "tap"
</screen>

</para>

<para>
But if you just need 'single' packet driver support that talks to, for
instance, your ethernet card eth0 then you need to set
</para>

<para>

<screen>
  $_netdev = "eth0"
</screen>

</para>

<para>
Note that dosnet and eth0 require raw packet access, and hence 
(suid)-root. If $_vnet = "dosnet", then $_netdev will default to "dsn0".
If you would like to use persistent TUN/TAP devices then you
need to specifify the TAP device in $_netdev.
For more on this look at chapter 15 (Networking using DOSEMU).
</para>

</sect3>

<sect3>
<title>Settings for enabling direct hardware access</title>
<para>
The following settings (together with the direct console video settings
below make it possible for DOSEMU to access your real (non-emulated) 
computer hardware directly. Because Linux does not permit this for
ordinary users, DOSEMU needs to be run as root, via sudo or suid-root
to be able to use these settings. They can NOT be overwritten by the
user configuration file ~/.dosemurc.
You must also run dosemu with the "-s" switch. This activates sudo
when appropriate; without it, even root will not get direct hardware
access.
</para>

<para>
Here you tell DOSEMU what to do when DOS wants let play the speaker:

<screen>
  $_speaker = ""     # or "native" or "emulated"
</screen>

</para>

<para>
And with the below may gain control over <emphasis>real</emphasis> ports on you machine.
But:
</para>

<para>
<emphasis remap="bf">WARNING: GIVING ACCESS TO PORTS IS BOTH A SECURITY CONCERN AND
SOME PORTS ARE DANGEROUS TO USE.  PLEASE SKIP THIS SECTION, AND
DON'T FIDDLE WITH THIS SECTION UNLESS YOU KNOW WHAT YOU'RE DOING.</emphasis>
</para>

<para>

<screen>
  $_ports = ""  # list of portnumbers such as "0x1ce 0x1cf 0x238"
                # or "0x1ce range 0x280,0x29f 310"
                # or "range 0x1a0,(0x1a0+15)"
</screen>

</para>

<para>
If you have hardware, that is not supported under Linux but you have
a DOS driver for, it may be necessary to enable IRQ passing to DOS.
Note that IRQ passing does not work on x86-64.

<screen>
  $_irqpassing = ""  # list of IRQ number (2-15) to pass to DOS such as
                     # "3 8 10"
</screen>

</para>

</sect3>

<sect3>
<title>Video settings ( console only )</title>

<para>
<emphasis>!!WARNING!!: IF YOU ENABLE GRAPHICS ON AN INCOMPATIBLE ADAPTOR,
YOU COULD GET A BLANK SCREEN OR MESSY SCREEN EVEN AFTER EXITING DOSEMU.
Read doc/README-tech.txt (Recovering the console after a crash).</emphasis>
</para>

<para>
Start with only text video using the following setup
</para>

<para>

<screen>
  $_video = "vga"         # one of: plainvga, vga, ega, mda, mga, cga
  $_console = (0)         # use 'console' video
  $_graphics = (0)        # use the cards BIOS to set graphics
  $_vbios_seg = (0xc000)  # set the address of your VBIOS (e.g. 0xe000)
  $_vbios_size = (0x10000)# set the size of your BIOS (e.g. 0x8000)
  $_vmemsize = (0)        # amount of video RAM to save/restore
  $_chipset = ""       
  $_dualmon = (0)         # if you have one vga _plus_ one hgc (2 monitors)
</screen>

</para>

<para>
After you get it `somehow' working and you have one of the DOSEMU supported
graphic cards you may switch to graphics mode changing the below
</para>

<para>

<screen>
  $_graphics = (1)        # use the cards BIOS to set graphics
</screen>

</para>

<para>
If you have a 100% compatible standard VGA card that <emphasis>may</emphasis> work,
however, you get better results, if your card has one of the DOSEMU supported
video chips and you tell DOSEMU to use it such as
</para>

<para>

<screen>
  $_chipset = "s3"        # one of: plainvga, trident, et4000, diamond, s3,
                          # avance, cirrus, matrox, wdvga, paradise, ati, sis,
			  # svgalib, vesa
</screen>

</para>

<para>
Note, `s3' is only an example, you <emphasis>must</emphasis> set the correct video chip
else it most like will crash your screen.
</para>

<para>
The 'svgalib' setting uses svgalib 1.9.21 or greater for determining the correct
video chip.
</para>

<para>
The 'vmemsize' setting's default of 0 causes DOSEMU to try to autodetect
the amount of video memory on the graphics card. This amount is saved
and restored when you switch away from and back to the virtual console DOSEMU
runs in using the Ctrl-Alt-Fn key combination. Since saving video
memory can be a very slow operation you may want to restrict 'vmemsize'
to a value that was more common when DOS was still mainstream. For instance
1024 covers it if you want to be able to save and restore modes up to
1024x768x256.
</para>

<para>
NOTE: `video setting' can <emphasis>not</emphasis> be overwritten by ~/.dosemurc.
</para>

</sect3>

<sect3>
<title>Time settings</title>
<para>
By Paul Crawford. This is a short guide to the time modes supported in
DOSEMU; you can get
a more detailed description of how and why they operate at
<ulink url="http://www.sat.dundee.ac.uk/~psc/dosemu_time_advanced.html">
http://www.sat.dundee.ac.uk/~psc/dosemu_time_advanced.html
</ulink>. There are three modes currently supported
using the $_timemode variable:

<screen>
  $_timemode = "bios"
  $_timemode = "pit"
  $_timemode = "linux"
</screen>

Most users will only ever have a need for either BIOS or LINUX mode,
and the decision comes down to the two basic characteristics:
<itemizedlist>
<listitem>
<para>
In BIOS mode, the DOSEMU session begins with the current (local)
date &amp; time, and once running it behaves fully like an emulated PC.
You can set the date &amp; time using the normal DOS methods as you would expect.
However, time keeping accuracy in the long term under DOS was never very good,
and under DOSEMU it is typically poorer.
</para>
</listitem>

<listitem>
<para>
In LINUX mode, the emulated PC always reports the current host time,
and so you no longer have the option to set the DOS time (the date can be
set, which is odd, as this is kept in DOS and not in the emulator). In
this mode you get the long term accuracy of the host, so if you are
running NTP or similar, you always get accurate time.
</para>
</listitem>

</itemizedlist>

The PIT mode is an odd compromise, it provides BIOS-like time
(settable, decoupled from host time), but with slightly higher
accuracy. In summary, if you need accurate time, choose LINUX mode,
otherwise if you need time setting capabilities or close 'real' PC
emulation, choose BIOS mode.
</para>

<para>
A reasonable question for some applications is
"how do I get accurate UTC time?", of course, the more general question is
about running the emulated DOS session in a different timezone and/or with
differing "daylight saving" options to the host computer.
This is quite simple in fact, just start DOSEMU with the environment
variable TZ set to the required zone, and don't forget to have the
corresponding command in the DOS autoexec.bat file (otherwise
Microsoft products all assume -8 hours PST!). The DOSEMU emulation
of file system access is also based on the local timezone it is running in,
so you will get consistent file time stamps compared to the emulated time.
So in the UTC case, you would start DOSEMU in a shell with TZ=GMT0, and
have a line in autoexec.bat with "set TZ=GMT0" before any of your programs
are run.
</para>

</sect3>

</sect2>

</sect1>
