A tarball containing the recent DOSEMU binaries together with a user
local configuration setup. This installation fits into any user HOME
directory and can be used and installed without root permissions.

A tarball containing a collection of suitable FreeDos binaries,
eventually patched to fit DOSEMU needs together with some GNU tools
you may find useful.

You have to unpack both tarballs (as normal user, NOT as
root) into the same directory , `cd' into the
directory `dosemu' and execute `./xdosemu' or `./dosemu'.
After you have played with this for a while and have looked into the files
under `dosemu/conf', you will be much better prepared to understand
the rest of this chapter.

Note: The DOSEMU installation described above may also come from a
systemwide installation, which you or your Linux distributor has
established. In this case, simply calling '[x]dosemu' will establish the
per user instance of DOSEMU. For details on how to create such a systemwide
installation, look at the file README.distributors in the DOSEMU source
distribution.

Also note: The following description was written for the older type of
systemwide installation (configuration under /etc). Though this type
of installation still works for suid-root DOSEMU runs, the new non-suid
type of installation has no dosemu.users and all configuration files
are normally kept under $HOME/dosemu/conf/*. The contents of these
configuration files are compatible with the below described, so most
of what is written also is valid for these private configuration files.

Most of DOSEMU configuration is done during runtime and per default it
expects the system wide configuration file dosemu.conf optionally
followed by the users ~/.dosemurc and additional configurations statements
on the commandline (-I option). The builtin configuration file of a DEXE
file is passed using the -I technique, hence the rules of -I apply.

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.

In DOSEMU prior to 0.97.5 the private configuration file was called ~/.dosrc
(not to be confused with the new ~/.dosemurc). This will work as expected
formerly, but is subject to be nolonger supported in the near future.
This (old) ~/.dosrc is processed after global.conf and follows (same
as -I) the syntax of global.conf (see README-tech.txt).

The first file expected (and interpreted) before any other configuration
(such as global.conf, dosemu.conf and ~/.dosemurc) is /etc/dosemu.users.
Within /etc/dosemu.users the general permissions are set:

which users are allowed to use DOSEMU.

which users are allowed to use DOSEMU suid root.

which users are allowed to have a private lib dir.

what kind of access class the user belongs to.

what special configuration stuff the users needs

and further more:

whether the lib dir (DOSEMU_LIB_DIR) resides elsewhere.

setting the loglevel.

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

[ <login> | all ] [ confvar [ confvar [ ... ] ] ]

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

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

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'

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 risc, it only will be allowed, if the used DOSEMU
binary is non-suid-root. If you realy 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).

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

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.

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.

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

root c_all
all c_all

to allow everybody all weird things. For more details on security issues
have a look at README-tech.txt chapter 2.

After /etc/dosemu.users dosemu.conf (via global.conf) is interpreted,
and only during global.conf parsing access to all configuration options is
allowed. 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.

The dosemu.conf (global.conf) may check for the configuration variables,
that are set in /etc/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.

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)

All settings in dosemu.conf are just variables, that are interpreted
in global.conf and have the form of

$_xxx = (n)

or

$_zzz = "s"

where `n' ist a numerical or boolean value and `s' is a string.
Note that the brackets are important, else the parser won't decide
for a number expression. For numers you may have complete expressions
( such as (2*1024) ) and strings may be concatenated such as

DOSEMU will help you finding 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 later prints to stderr). In dosemu.conf you
can preset this via

$_debug = "-a"

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

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

$_cpu = (80386)

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

$_rdtsc = (on) # or off

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

$_cpuspeed = (166.666) # 0 = let DOSEMU calibrate

NOTE: `$_rdtsc' and `$_cpuspeed' can not be overwritten by ~/.dosemurc.

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

$_pci = (on) # or off

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 stuff to map a given page of memory to the
required virtual DOS address space.

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

$_mapping= "mapfile"

to force the use of the driver, which uses a temporary file. Or on
kernels up to 2.3.27

$_mapping= "mapself"

to use mapping on the /proc/self/mem file, which is a lot faster the
the `mapfile' driver, but maybe not relyable in conjunctions with glibc
(NOTE: the kernel since ages has bugs on /proc/self/mem mapping and
our workaround doesn't fit exactly together glibc).

Last but not least, if you are using a kernel above 2.3.40, you may use

$_mapping= "mapshm"

which uses one big IPC shared memory segment as memory pool and the new
extended mremap() functionality for the mapping.

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)
and that you should take care yourself that you have enough diskspace
or have the IPC limits high enough. You can control IPC memory limits
with

Note that (other as in native DOS) each piece of mem is separate, hence
DOS perhaps will show other values for 'extended' memory. To enable
DPMI (by giving it memory) is a security concern, so you should either
not give access to dosemu for normal users (via /etc/dosemu.users)
or give those users the `restricted' attribute (see above).

There are some features in DOSEMU, that may violate system security
and which you should not use on machines, which are `net open'. To
have atleast a minimum of protection against intruders, use the folling:

The items in the lists are blank separated, `odd_hosts' checks for remote
logins, `diskless_hosts' are meant to be maschines, that mount a complete
tree, hence the checked host is the host DOSEMU is running on (not the
remote host). However, read README-tech,txt for more details on what
actually is disabled.

NOTE: `$_*_hosts' can not be overwritten by ~/.dosemurc.

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:

As you would realize at the first glance: DOS will not 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.

$_hogthreshold = (1) # 0 == all CPU power to DOSEMU
# 1 == max power for Linux
# >1 the higher, the faster DOSEMU will be

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.

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

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

$_speaker = "" # or "native" or "emulated"

And with the below may gain control over real ports on you machine.
But:

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.

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

$_term_char_set = "XXX"

where XXX is one of

ibm

With the kbd_unicode plugin (the default), the text is processed using
cp437->cp437 for the display, so the font used must be cp437
(eg cp437.f16 on the console).
The text is no longer taken without translation. It never really
was but it was close enough it apparently was used that way.
When reading characters they are assumed to be in iso-8859-1 from
the terminal.

If the old keyboard code is used, then the text is taken whithout translation.
It is to the user
to load a proper DOS font (cp437.f16, cp850.f16 or cp852.f16 on the
console).

latin

the text is processed using cp437->iso-8859-1 translation,
so the font used must be iso-8859-1 (eg iso01.f16 on console);
which is the default for unix in western languages countries.

latin1

like latin, but using cp850->iso-8859-1 translation (the
difference between cp437 and cp850 is that cp437 uses some chars for
drawing boxes while cp850 uses them for accentuated letters)

latin2

like latin1 but uses cp852->iso-8859-2 translation, so
translates the default DOS charset of eastern european countries to the
default unix charset for those countries.

The default one is ``latin'' and if the string is empty, then an automatic
attempt is made: ``ibm'' for remote console and ``latin'' for anything else.
Depending on the charset setting the (below described) keyboard layouts
and/or the terminal behave may vary. You need to know the correct code page
your DOS is configured for in order to get the correct results.
For most western european countries 'latin' should be the correct setting.

`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,

When running DOSEMU from console (also remote from console) or X you
may need to define a proper keyboard layout. Its possible to let
DOSEMU do this work automatically for you (see auto 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/*):

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

$_layout = "load de-latin1"

Note, however, that you have to set

$_X_keycode = (on)

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

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

$_X_keycode = (auto)

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

$_layout = "auto"

DOSEMU then queries the keyboard layout from the kernel (which
only does work on console or non-remote X) 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).

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.

$_rawkeyboard = (1)

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

NOTE: `$_rawkeyboard' can not be overwritten by ~/.dosemurc.

The `keybint (on)' allows more accurate of keyboard interrupts, It
is a bit unstable, but makes keyboard work better when set to "on".
Note that with the new default kbd_unicode plugin, $_keybint is obsolete.

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

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

The 'svgalib' setting uses svgalib 1.4.2 or greater for determining the correct
video chip. It should work with all svgalib drivers, except for "vesa" and
"ati", which are dangerous with respect to opening IO-ports.

The parameter settings via dosemu.conf 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:

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 6 (Using Lredir) and for more details
on creating your own hdimage look at chapter 4.3 of this README
(Making a bootable hdimage for general purpose). Chapter 4.4 also describes
how to import/export files from/to a hdimage.

Starting with dosemu-0.99.8, there is a more convenient method available:
you just can have a Linux directory containing all what you want to have
under your DOS C:. Copy your IO.SYS, MSDOS.SYS or what ever to that
directory (e.g. DOSEMU_LIB_DIR/bootdir), put

$_hdimage = "bootdir"

into your dosemu.conf, and up it goes. 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:

and the C, D, E are symlinks to appropriate DOS useable
directories, then the following single statement in dosemu.conf

$_hdimage = "drives/*"

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

DOSEMU_LIB_DIR/drives/x
DOSEMU_LIB_DIR/drives/a

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

Now, what does the above `vbootfloppy' mean? Instead of booting
from a virtual `disk' you may have an image of a virtual `floppy' which
you just created such as `dd if=/dev/fd0 of=floppy_image'. If this
floppy contains a bootable DOS, then

$_vbootfloppy = "floppy_image"

will boot that floppy. Once running in DOS you can make the floppy
available by (virtually) removing the `media' via `bootoff.com'.
If want the disk access specified via `$_hdimage' anyway, you may add the
keyword `+hd' such as

$_vbootfloppy = "floppy_image +hd"

In some rare cases you may have problems accessing Lredir'ed drives
(especially when your DOS application refuses to run on a 'network drive'),
though I personally never happened to fall into one of this.
For this to overcome you may need to use socalled `partition access'. The odd
with this kind of access is, that you never 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 global.conf 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, here is how you `assign' real DOS partitions
to DOSEMU:

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

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

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

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

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 no mouse.com driver installed in your DOS environment, DOSEMU
has the mousedriver builtin. The below example is such a setup

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)

However, you may use your favorite DOS mousedriver and directly let it
drive COM1 by changing the below variables (rest of variables unchanged)

$_com1 = "/dev/mouse"
$_mouse_dev = "com1"

And finaly, when you have a PS2 mouse on your machine you use
the builtin mousedriver (not your mouse.com) to get it work:
( again leaving the rest of variables unchanged)

$_mouse = "ps2"
$_mouse_dev = "/dev/mouse"

When using a PS2 mouse or when having more then 2 serial ports you may
of course assign _any_ free serialdevice to COM1, COM2. The order doesn't
matter:

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 to spool out the data to the printer.

$_printer = "lp" # list of (/etc/printcap) printer names to appear as
# LPT1 ... LPT3 (not all are needed, empty for none)
$_printer_timeout = (20)# idle time in seconds before spooling out

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.

$_ipxsupport = (on)

Enable Novell 8137->raw 802.3 translation hack in new packet driver.

$_novell_hack = (on)

If you make use of the dosnet device driver, you may turn on 'multi'
packet driver support via

$_vnet = (on)

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

$_netdev = "eth0"

Note that this requires raw packet access, and hence (suid)-root.
If $_vnet = (on), the $_netdev will default to "dsn0".
For more on this look at chapter 15 (Net code).

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

to configure $_aspi in dosemu.conf to define which
of the /dev/sgX devices you want to show up in DOSEMU.

to load the DOSEMU aspi.sys stub driver within config.sys
(e.g. DEVICE=ASPI.SYS) before any ASPI using driver.

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

$_aspi = "sg2:WORM"

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

$_aspi = "sg2 sg3 sg4"

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 want to map a disk drive to DOSEMU's ASPI driver, you need to
tell it explicitely

$_aspi = "sg1:Direct-Access"

or

$_aspi = "sg1:0"

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

$ cat /proc/scsi/scsi

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:

In the above example there are two scsi hostadapters (scsi0 and scsi1) and
DOSEMU will not show more than one 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

$_aspi = "sg2:CD-ROM:5 sg4:WORM"

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

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

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

echo "scsi remove-single-device 0 0 5 0" >/proc/scsi/scsi

to delete a device and

echo "scsi add-single-device 0 0 5 0" >/proc/scsi/scsi

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

Coming so far, one 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

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

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