<sect>Runtime Configuration Options<label id="config">
<p>

This section of the document by Hans, 
<htmlurl url="mailto:lermen@fgan.de" name="&lt;lermen@fgan.de&gt;">. Last
updated on Mar 20, 1998.

<p>
Most of DOSEMU configuration is done during runtime and per default it
expects the system wide configuration file /etc/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 /etc/dosemu.conf and ~/.dosemurc (which have identical syntax)
are included by the systemwide configuration script
/var/lib/dosemu/global.conf, but as a normal user you won't ever think on
editing this, only dosemu.conf and your personal ~/.dosemurc.

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 <em/after/ global.conf and follows (same
as -I) the syntax of global.conf.


<p>
The first file expected (and interpreted) before any other configuration
(such as global.conf, dosemu.conf and ~/.dosemurc) is /etc/dosemu.users.
If /etc/dosemu.users doesn't exist, DOSEMU check for /etc/dosemu/dosemu.users,
this makes people happy, which prefer to have to configuration stuff in
a separate directory under /etc.
Within dosemu.users the general permissions are set:

<itemize>
  <item> which users are allowed to use DOSEMU.
  <item> which users are allowed to use DOSEMU suid root.
  <item> which users are allowed to have a private lib dir.
  <item> what kind of access class the user belongs to.
  <item> what special configuration stuff the users needs
</itemize>

and further more:
<itemize>
  <item> wether the lib dir (/var/lib/dosemu) resides elsewhere.
  <item> setting the loglevel.
</itemize>

<p>
This is done via setting configuration variables.

<p>
After /etc/dosemu.users /etc/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 /etc/dosemu.conf.


<p>
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 /etc/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.

<p>
For an example of a general configuration  look
at ./etc/global.conf. The later behaves insecure, when /etc/dosemu.users
is a copy of ./etc/dosemu.users.easy and behave 'secure', when
/etc/dosemu.users is a copy of ./etc/dosemu.users.secure.

<sect1>Format of /etc/dosemu.users

<p>
Except for lines starting with x=' (explanation below),
each line corresponds to exactly _one_ valid user count:

<tscreen><verb>
  loginname [ c_strict ] [ classes ...] [ c_dexeonly ] [ other ]
</verb></tscreen>

<p>where the elements are:

<descrip>
  <tag/loginname/ valid login name (root also is one) or 'all'. The later means
             any user not mentioned in previous lines.
  <tag/nosuidroot/ Do not allow execution of a suid dosemu binary. The user
	may, howver, use a non-suid root copy of DOSEMU
	(reasonable sysadmins will supply it)
        For more information on this look at chapter 11.1
        (`Priveleges and Running as User')

  <tag/c_strict/ Do not allow -F option (global.conf can't be replaced)

  <tag/c_dexeonly/ Only allow execution of DEXE files, forbid any other use.

  <tag/classes/ One or more of the following:
  <descrip>
             <tag/c_all/ no restriction
             <tag/c_normal/ normal restrictions, all but the following classes:
                       c_var, c_boot, c_vport, c_secure, c_irq, c_hardram.
             <tag/c_var/     allow (un)setting of configuration- and
                             environment variables
             <tag/c_nice/    allow `HogThreshold' setting
             <tag/c_floppy/  allow floppy access
             <tag/c_boot/    allow definition of boot file/device
             <tag/c_secure/  allow setting of 'secure off'
             <tag/c_vport/   allow setting of 'allowvideoportaccess'
             <tag/c_dpmi/    allow DPMI setting
             <tag/c_video/   allow `video' setting
             <tag/c_port/    allow `port' setting
             <tag/c_disk/    allow `disk'  settings
             <tag/c_x/       allow X support settings
             <tag/c_sound/   allow sound settings
             <tag/c_irq/     allow `irqpassing' statement
             <tag/c_dexe/    allow `dexe' settings
             <tag/c_printer/ allow printer settings
             <tag/c_hardram/ allow 'hardware_ram' settings
             <tag/c_shell/   allow the parser's `shell()' function
  </descrip>
  <tag/other/      Here you may define any configuration variable, that you
             want to test
             in global.conf (or (old) .dosrc, -I), see `ifdef', `ifndef'
             When this variable is intended to be unset in lower privilege
             configuration files (.dosrc, -I), then the variable name
             has to be prefixed with `u_'.
  <tag/private_setup/ Keyword, this makes dosemu to accept a private DOSEMU lib
             under  $HOME/.dosemu/lib. If this directory is existing, DOSEMU
             will expect all normally under /var/lib/dosemu within that
             directory,including `global.conf'. 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).
   <tag/unrestricted/ Keyword, used to allow `private_setup' on suid-root
            binaries too. USE WITH CARE !

</descrip>
<p>
A line with '#' at colum 1 is treated as comment line. When only the login
name is given (no further parameters, old format) the following setting is
assumed:

<tscreen><verb>
  if 'root'  c_all
  else       c_normal
</verb></tscreen>

<p>
Other than with previous DOSEMU versions, the /etc/dosemu.users now is
mandatory. Also note, that you may restrict 'root' doing something silly ;-)

In addition, dosemu.users can be used to define some global settings, which
must be known before any other file is accessed, such as:
<tscreen><verb>
  default_lib_dir= /opt/dosemu  # replaces /var/lib/dosemu
  log_level= 2                  # highest log level
</verb></tscreen>

With `default_lib_dir=' you may move /var/lib/dosemu elsewere, this mostly
is interesting for distributors, who want it elswere 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.



<sect1>Format of /var/lib/dosemu/global.conf ( (old) .dosrc, -I option)

<p>
The configuration files are not line oriented, instead are consisting of
`statements' (optionally separated by `;'), whitespaces are removed
and all behind a '#' up to the end of the line is treated as comment.
( Note that older DOSEMUs also allowed `!' and `;' as comment character,
but those are no longer supported ). 


<sect2>Enviroment variables and configuration variables

<p>
They existed already in very early versions of DOSEMU (until now),
but now evironment variables are much more useful in dosemu.conf / global.conf
as before, because you now can set them, test them in the new 'if' statement
and compute them in expressions.
The problem with the enviroment variables is, however,
that the user may set and fake them <em/before/ calling DOSEMU, hence this
is a security problem. To avoid this, we have the above mentioned
<em/configuration variables/, which are of complete different name space
and are not visible outside of DOSEMU's configuration parser. On the other
hand it may be useful to export settings from global.conf to the
running DOS environment, which can be achieved by the 'unix.exe -e'
DOS programm.

<p>To summarize:
<descrip>
  <tag/configuration variables/ have their own namespace only within the
       configuration parser. They usual are prefixed by <em/c_/, <em/u_/
       and <em/h_/ and cannot be made visible outside. They do not contain
       any value and are only tested for existence.

  <tag/environment variables/ are inherited from the calling process, can
       be set within global.conf (dosemu.conf) and passed to DOSEMU running
       DOS-applications. Within *.conf they always are prefixed
       by '$' (Hence TERM becomes $TERM, even on the left side of an
       assigment). However, <em/setting/ them is controled by the configuration
       variable 'c_var' (see above) and may be disallowed within the user
       supplied (old) .dosrc and alike.
</descrip>

<p>At startup DOSEMU generates the following environment variables, which
may be used to let the configuration adapt better:

<descrip>
  <tag/KERNEL_VERSION_CODE/ holds the numerical coded version of the running
       linux kernel (same format as within linux/version.h)
  <tag/DOSEMU_VERSION_CODE/ holds the numerical coded version of the running
       DOSEMU version (format: MSB ... LSB == major, minor, patchlevel,
       sublevel)
  <tag/DOSEMU_EUID/ effective uid
  <tag/DOSEMU_UID/ uid. You may protect security relevant parts of the
       configuration such as:
  <descrip>
  <tscreen><verb>
if ( ! $DOSEMU_EUID && ($DOSEMU_EUID != $DOSEMU_UID) )
  warn "running suid root"
endif
  </verb></tscreen>
  </descrip>
  <tag/DOSEMU_HOST/ Name of the host DOSEMU is running on. This is same
       as what follows the `h_' configuration variable, see below.
       ( if not available, then DOSEMU_HOST contains `unknown' )
  <tag/DOSEMU_USER/ The user name, that got matched in /etc/dosemu.users.
       This needs not to be the _real_ user name, it may be `all' or
       `unknown'.
  <tag/DOSEMU_REAL_USER/ The user name out of getpwuid(uid).
  <tag/DOSEMU_SHELL_RETURN/ The exitcode (0-255) from the recently executed
                            <em/shell()/ command.
  <tag/DOSEMU_OPTIONS/      A string of all commandline options used (one
       character per option). You may remove a character from this string,
       such that the normal override of dosemu.conf settings will not take
       place for that option. However, parsing the command line options
       happens in two stages, one _before_ parsing dosemu.conf and one
       _after_. The options 'FfhIdLoO23456' have
       already gotten processed before dosemu.conf, so they can be disabled.
</descrip>



<sect2>Conditional statements

<p>
You may control execution of configuration statements via the following
conditional statement:

<tscreen><verb>
  ifdef <configuration variable>
</verb></tscreen>
or
<tscreen><verb>
  ifndef <configuration variable>
    ...
  else
    ...
  endif
</verb></tscreen>

<p> where <em/variable/ is a <em/configuration variable/ (not an
environment variable). Additionally there is a `normal' <em/if statement/,
a <em/while statement/ and a <em/foreach statement/ such as
<tscreen><verb>
  if ( expression )
  endif
  while ( expression )
  done
  foreach loop_variable (delim, list)
  done
</verb></tscreen>
but these behaves a bit different and are described later.

<p>
The 'else' clause may be ommitted and 'ifndef' is the opposite to 'ifdef'.
The &lt;variable&gt; can't be tested for its contents, only if it is set or not.
Clauses also may contain further if*def..endif clause up to a depth of 15.
All stuff in /etc/dosemu.users behind the 'loginname' in fact are
 <em/configuration variables/
that are set. Hence, what you set there, can be tested here in the config
file. Further more you may set/unset  <em/configuration variables/
in the config files itself:

<tscreen><verb>
  define <configuration variable>
  undef  <configuration variable>
</verb></tscreen>

<p>
However, use of define/undef is restricted to scope of global.conf,
as long as you don't 'define c_var' _within_ global.conf.
If you are under scope of a 'user config file' (e.g. outside
global.conf) you have to prefix the <em/configuration variable/
name with 'u_', else it
will not be allowed to be set/unset (hence 'c_' type variables can't be
unset out of scope of global.conf).

<p>
There are some <em/configuration variables/
(besides the ones described above for dosemu.users)
implicitely predefined by DOSEMU itself:

<descrip>
  <tag/c_system/     set while being in /var/lib/dosemu/global.conf
  <tag/c_user/       set while parsing a user configuration file
  <tag/c_dosrc/      set while parsing (old) .dosrc
  <tag/c_comline/    set while parsing -I option statements
  <tag/c_dexerun/    set if a DEXE will be executed

  <tag/h_&lt;ownhost&gt;/  defined on startup as 'h_&lt;host&gt;.&lt;domain&gt;' of the host
               DOSEMU is running on. If &lt;domain&gt; can't be resolved,
               the pure hostname is taken. This makes sense only if a file
               system containing DOSEMU is mounted on diskless machines and you
               want restrict access. Note however, h_&lt;ownhost&gt; is set using
               gethostname/getdomainname. Hence, if the user on the
               diskless machine has root access, this is _not_ secure,
               because he could fake a valid address.
</descrip>

<p>
Also, you may define any 'u_' type variable at start of DOSEMU via the new
option -u such as

<tscreen><verb>
# dos -u myspecialfun
</verb></tscreen>

<p>
this will then define the config variable 'u_myspecialfun' _before_ parsing
any configuration file. You then may check this in your (old) ./dosrc or
global.conf to do the needed special configuration.

<p>
Now, what's this with the <em/if statement/ and <em/while statement/?
All those conditionals via <em/ifdef/ and <em/indef/ are completly
handled <em/before/ the remaining input is passed to the parser. Hence you
even may use them <em/within/ a configuration statement such as

<tscreen><verb>
terminal { charset
  ifdef u_likeibm
    ibm
  else
    latin
  endif
  updatefreq 4  color on }
</verb></tscreen>

This is not the case with the (above mentioned) <em/if statement/, this one
is of course processed within the parser itself and can only take place within
the proper syntax context such as

<tscreen><verb>      
  if ( defined( u_likeibm ) )
    $mycharset = "ibm"
  else
    $mycharset = "latin"
  endif
  terminal { charset $mycharset updatefreq 4  color on }
</verb></tscreen>

but it has the advantage, that you can put any (even complex)
<em/expression/ (see chapter `expressions') between the brackets.
If the expression's numerical value is 0, then false is assumed, else true.

Same rules apply to the <em/while statement/, the loop will be executed
as long as `expression' is not 0. The loop end is given by the keyword
<em/done/ such as in

<tscreen><verb>
  $counter = (3)
  while ($counter > 0)
    # what ever should loop
    $counter = ($counter -1)
  done

  # or some kind of list processing
  # ... but look below, `foreach' does it better
  $list = "aa bbb ccc"
  while (strlen($list))
    $item = strdel($list, strchr($list," "), 999)
    $list = strsplit($list, (strlen($item)+1),9999);
    warn "doing something with ", $item
  done

</verb></tscreen>

The <em/foreach statement/ behaves a bit like the /bin/sh `for i in', but
you can specify a list of delimiters.

<tscreen><verb>
  $list = "anton, berta; caesar dora"
  $delim = " ,;"
  foreach $xx ($delim, $list)
    warn "My name is ", $xx
  done

  $list = "a b c : 1 2 3"               
  $delim = ":"
  foreach $xx ($delim, $list)
    if ($delim eq ":")
      $delim = " ";
    else
      warn "processing number ", $xx
    endif
  done
</verb></tscreen>
The later example jumps to the colon (`:') in one step and after that
process the numbers step by step.

For all loops and `if' statement the allowed depth is 32 (totally).

<sect2>Include files
<p>
If you for some reason want to bundle some major settings in a separate file
you can include it via

<tscreen><verb>
  include "somefile"
</verb></tscreen>

<p>
If 'somefile' doesn't have a leading '/', it is assumed to be relative to /etc.
Also includeing may be nested up to a max depth of 10 files.
Note however, that the privilege is inherited from the main file from which
is included, hence all what is included by /var/lib/dosemu/global.conf has its
privilege.

However, there are restrictions for `while' loops: You can't have
<em/include statements/ within loops without beeing prepared for unexpected
behave. In fact you may try, but due to the technique used, include files
within loops are loaded completely <em/prior/ loop execution.
Hence, if you do conditional including this won't work.

A further restriction is, that the name of the include file must not be
a variable. However, you can work around this with a macro (see next
chapter) as shows the following example:

<tscreen><verb>
  $file = $HOME, "/.my_dosrc_include"
  shell("test -f ", $file)
  if ( ! $DOSEMU_SHELL_RETURN)                                       
    # we can include
    $INC = ' include "', $file, '"';
    $$INC
  endif
</verb></tscreen>


<sect2>Macro substitution
<p>

There is a <em/very/ rudimentary macro substitution available, which
does allow recursion but no arguments: Whenever you write

<tscreen><verb>
  $MYMACRO = "warn 'this is executed as macro'" ;
  $$MYMACRO
</verb></tscreen>
it will expand to
<tscreen><verb>
  warn 'this is executed as macro'
</verb></tscreen>

Note, that the `;' is required for parser to recognize the end of the
statement and to set the variable <em/before/ it tries to read the next
token (which will let the lexer process `$$MYMACRO'). Macro substitution
is completely done on the input stream before the parser gets the data.

For what is it worth then? Now, this enables you to insert text into the
input stream, that otherwise would be expected to be constant. Or simple,
it allows you to be lazy to write the same things more then once.
<tscreen><verb>
  $loop = '
    while ($xxx)
      warn "loop in macro ",$xxx
      $xxx = ($xxx -1)
    done  
  ';
  $xxx = (2); $$loop; $xxx = (3); $$loop;

  $_X_keycode = (off)
  $_X_lin_filt = (on)
  ...
  if ($_X_keycode) $_X_keycode = "keycode" else $_X_keycode = "" endif
  if ($_X_lin_filt) $_X_lin_filt = "lin_filt" else $_X_lin_filt = "" endif
  X { icon_name "xdos" $$_X_keycode $$_X_lin_filt }
</verb></tscreen>
You see, that in cases the variables are `false', the (parameterless)
`keycode' and/or `lin_filt' keywords would not appear in the `X{}' statement.


<sect2>Expressions
<p>
Expression within the configuration files follow the usual numerical rules
and may be as complex as you wish. At some places, the parser only can
`understand' expressions, when you enclose them in brackets, but mostly
you just can type
<tscreen><verb>
  123 + 456 + 2 * 1.2
</verb></tscreen>

Though, if you want be sure, you better type them as
<tscreen><verb>
  ( 123 + 456 + 2 * 1.2 )
</verb></tscreen>

You may place expressions whenever a numerical value is expected and there
is no ambiguity in the syntax. Such an ambiguity is given, when a statement
needs more then one successive number such as

<tscreen><verb>
  ... winsize x y ...
  ... vesamode width heigh ...
  ... range from to ...
</verb></tscreen>

If you want to place expression herein, you need the new syntax for those
statements / terms which have a coma (instead of a blank) as delimiter:

<tscreen><verb>
  ... winsize x , y ...
  ... vesamode width , heigh ...
  ... range from , to ...
</verb></tscreen>

The old syntax is left for compatibility and is only parsed correcty, if
pure numbers (integers) are used.

Valid constant numbers (not only in expressions) are
<tscreen><verb>
  123     decimal, integer
  0x1a    hexadecimal, integer
  0b10101 bitstream, integer
  1.2     float number, real
  0.5e3   exponential form, real
  off     boolean false, integer
  on      boolean true, integer
  no      boolean false, integer
  yes     boolean true, integer
</verb></tscreen>

The following operator are recognized:
<tscreen><verb>
  + - *   as usual
  / div   division, the '/' _must_ be surrounded by whitespaces, else
          it conflicts with pathnames on quoteless strings
  |       bitwise or
  ^       bitwise exclusive or
  ~       bitwise not
  &       bitwise and
  >>      shift right
  <<      shift left
  <       less then
  <=      less or equal
  >       greater then
  >=      greater or equal
  ||      boolean or
  &&      boolean and
  !       boolean not
  ==      numerical equivalence
  eq      string equivalence
  !=      numerical, not equal
  ne      string not equal
</verb></tscreen>

The type of the expression result may be real (float) or integer, depending
on which type is on the `left side'. Conversion is mostly done automaticaly,
but you may force it using the (below mentioned) int() and real() functions
such as:
<tscreen><verb>
   $is_real =    ( 3.1415 * 100 )
   $is_integer = ( int( 3.1415 * 100) )
   $is_integer = ( 100 * 3.1415 )
   $is_real =  ( real($is_integer) )
</verb></tscreen>

The above also shows, how environment variables can be set: if you want
to place `expressions' (which are always numbers) onto a variable, you
have to surround them with brackets, else the parser won't be able to detect
them. In principal, all $xxx settings are string-settings and numbers will
be converted correctly before. In fact the `$xxx =' statement accepts a
complete coma separated list, which it will concatenate, examples:

<tscreen><verb>
  $termnum = (1)
  $MYTERM = "/dev/ttyp", $termnum       # results in "/dev/ttyp1"
  $VER = (($DOSEMU_VERSION_CODE >> 24) & 255)
  $MINOR = (($DOSEMU_VERSION_CODE >> 16) & 255)
  $running_dosemu = "dosemu-", $VER, ".", $MINOR
</verb></tscreen>


Several builtin functions, which can be used in expressions, are available:
<descrip>
  <tag/int(real)/         converts a float expression to integer
  <tag/real(integer)/    converts a integer expression to float
  <tag/strlen(string)/    returns the length of `string'
  <tag/strtol(string)/    returns the integer value of `string'
  <tag/strncmp(str1,str2,expression)/ compares strings, see `man strncmp'
  <tag/strpbrk(str1,str2)/ like `man strpbrk', but returns an index
                          or -1 instead of a char pointer.
  <tag/strchr(str1,str2)/ like `man strchr', but returns an index
                          or -1 instead of a char pointer.
  <tag/strrchr(str1,str2)/ like `man strrchr', but returns an index
                          or -1 instead of a char pointer.
  <tag/strstr(str1,str2)/ like `man strstr', but returns an index
                          or -1 instead of a char pointer.
  <tag/strspn(str1,str2)/ as `man strspn'
  <tag/strcspn(str1,str2)/ as `man strcspn'
  <tag/defined(varname)/  returns true, if the configuration variable
                          `varname' exists.
</descrip>


<sect2>String expressions
<p>
For manipulation of strings there are the following builtin functions,
which all return a new string. These very well may be placed as argument
to a numerical function's string argument, but within an `expression' they
may be only used together with the `eq' or `ne' operator.

<p>
<descrip>
  <tag/strcat(str1, ,strn)/ concatenates any number of strings, the result
                          is a string again.
  <tag/strsplit(string, expr1, expr2)/ cuts off parts of `string', starting
                          at index `expr1' with length of `expr2'.
                          If either `expr1' is < 0 or `expr2' is < 1, an empty
                          string is returned.
  <tag/strdel(string, expr1, expr2)/ deletes parts of `string', starting
                          at index `expr1' with length of `expr2'.
                          If either `expr1' or `expr2' is < 0, nothing
                          is deleted (the original strings is returned).
  <tag/shell(string)/     executes the command in `string' and returns
                          its stdout result in a string. The exit code of
                          executed command is put into $DOSEMU_SHELL_RETURN
                          (value between 0 and 255). You may also call
                          shell() as a standalone statement (hence
                          discarding the returned string), if you only need
                          $DOSEMU_SHELL_RETURN (or not even that).
                          However, to avoid
                          security implications all privilegdes are dropped
                          and executions is under control of <em/c_shell/
                          configuration variable. The default is, that it
                          can only be executed from within global.conf.
</descrip>

With these tools you should be able to make your global.conf adapt
to any special case, such as different terminal types, different hdimages
for different users and/or different host, adapt to different (future)
dosemu and/or kernel versions. Here some small examples:

<tscreen><verb>
  $whoami = shell("who am i")
  if ( strchr($whoami, "(" ) < 0 )
    # beeing on console
  else
    if (strstr($whoami, "(:") < 0)
      # beeing remote logged in
    endif
    if ($TERM eq "xterm")
      # beeing on xterm
    else
      if (strstr("linux console", $TERM) < 0)
        # remote side must be some type of real terminal
      else
        # remote side is a Linux console
      endif
    endif
  endif

  if ($DISPLAY ne "")
    # we can rely on reaching an Xserver
    if (strsplit($DISPLAY, 0, 1) ne ":")
      # the X server is remote
    endif
  endif

  if ($DOSEMU_REAL_USER eq "alistair")
    # ha, this one is allowed to do odds sound tricks :-)
  endif

  if (strsplit($DOSEMU_HOST, 0, strchr($DOSEMU_HOST,"."))
                                                   eq $DOSEMU_HOST)
    # we have no domain suffix for this host, should be a local one
  endif

  # disable setting graphics mode per commandline option -g
  $DOSEMU_OPTIONS = strdel($DOSEMU_OPTIONS, strchr($DOSEMU_OPTIONS,"g"),1);

</verb></tscreen>


<sect2>`Dry' testing your configuration
<p>

It may be usefull to verify, that your *.conf does what you
want before starting a real running DOSEMU. For this purpose there is a 
new commandline option (-h), which just runs the parser, print some
useful output, dumps the main configuration structure and then exits.
The option has an argument (0,1,2), which sets the amount of parser debug
output: 0 = no parser debug, 1 = print loop debugs, 2 = same as 1 plus
if_else_endif-stack debug. This feature can be used such as

<tscreen><verb>
  $ dos -h0 -O 2>&1 | less
</verb></tscreen>

The output of `-h2' looks like
<tscreen><verb>
  PUSH 1->2 1 >foreach__yy__<
  PUSH 2->3 1 >if<
  POP 2<-3 0 >endif< -1
  POP 1<-2 1 >done< -1
  PUSH 1->2 1 >foreach__yy__<
  PUSH 2->3 1 >if<
  POP 2<-3 1 >endif< -1
  POP 1<-2 1 >done< -1
      |  | |         +-------`cached' read status (0 = not cached)
      |  | +-----------------`if' or `loop' test result (0 = false = skipped)
      |  +-------------------inner level
      +----------------------outer level (1 = no depth)
</verb></tscreen>
 
There are also some configuration statements, which aren't of any use
except for help debugging your *.conf such as

<tscreen><verb>
  exprtest ($DOSEMU_VERSION_CODE)   # will just print the result
  warn "content of DOSEMU_VERSION_CODE: ", $DOSEMU_VERSION_CODE
</verb></tscreen>


<sect2>Debug statement
<p>
This section is of interest mainly to programmers.  This is useful if
you are having problems with DOSEMU and you want to enclose debug info
when you make bug reports to a member of the DOSEMU development team.
Simply set desired flags to "on" or "off", then redirect stderr of
DOSEMU to a file using "dos -o debug" to record the debug information
if desired.  Skip this section if you're only starting to set up.

<tscreen><verb>
  debug { config  off	disk    off	warning off	hardware off
        port    off	read    off	general off	IPC      off
        video   off	write   off	xms     off	ems      off
        serial  off	keyb    off	dpmi    off
       	printer off	mouse   off	sound	off
  }
</verb></tscreen>

Alternatively you may use the same format as -D commandline option
(but without the -D in front), look at the dos.1 man page.

<tscreen><verb>
  debug "+a-v"     # all messages but video
  debug "+4r"      # default + maximum of PIC debug
</verb></tscreen>    

or simply (to turn off all debugging)

<tscreen><verb>
  debug { off }
</verb></tscreen>

<sect2>Miscellaneous
<p>
The HogThreshold value determines how nice Dosemu will be about
giving other Linux processes a chance to run.  Setting the HogThreshold
value to approximately half of you BogoMips value will slightly
degrade Dosemu performance, but significantly increase overall
system idle time.  A zero value runs Dosemu at full tilt.

<tscreen><verb>
  HogThreshold 0
</verb></tscreen>

Want startup DOSEMU banner messages?  Of course :-)

<tscreen><verb>
  dosbanner on
</verb></tscreen>

Timint is necessary for many programs to work.

<tscreen><verb>
  timint on
</verb></tscreen>

For "mathco", set this to "on" to enable the coprocessor during DOSEMU.
This really only has an effect on kernels prior to 1.0.3.

<tscreen><verb>
  mathco on
</verb></tscreen>

For "cpu", set this to the CPU you want recognized during DOSEMU.

<tscreen><verb>
  cpu 80386
</verb></tscreen>

If you have DOSEMU configured to use the 386-emulator, you can enable the
emulator via

<tscreen><verb>
  cpu emulated
</verb></tscreen>

You may ask why we need to emulate a 386 on an 386 ;-) Well, for normal
purpose its not needed (and will be slower anyway), but the emulator offers
a better way to debug DOS applications, especially DPMI code.
Also, we hope that some day we may be able to run DOSEMU on other machines
than 386. At the time of writing this, the cpu emulators is very alpha and
you should not use it except you are willing to help us. So please, don't
even try to report 'bugs' except you have a patch for the bug too.

If you have a pentium, DOSEMU can make use of the pentium cycle counter
to do better timing. DOSEMU detects the pentium and will use the RDTSC
instruction for get time per default. To disable this feature use

<tscreen><verb>
  rdtsc off
</verb></tscreen>

Also, to use the pentium cycle counter correctly DOSEMU needs to know
the CPU-clock which your chip is running. This per default is calibrated
automatically, however, that may be not exact enough. In this case you
have to set it yourself via

<tscreen><verb>
  cpuspeed 180
</verb></tscreen>

or, for values like 166.6666 you may give two numbers such as

<tscreen><verb>  
  cpuspeed 500 3
</verb></tscreen>

which will be calculated as 'cpuspeed=500/3'


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

<tscreen><verb>
  pci on | off
</verb></tscreen>

PCI is assumed to be present on CPUs better then a pentium, otherwise
the default is 'pci off'


For "bootA"/"bootC", set this to the bootup drive you want to use.
It is strongly recommended you start with "bootA" to get DOSEMU
going, and during configuration of DOSEMU to recognize hard disks.

<tscreen><verb>
  bootA
</verb></tscreen>


During compile there will be a symbol map generated, this usually
then is ./bin/dosemu.map. You may wnt to save it to an other places
and let 'dosdebug' know where to find it:

<tscreen><verb>
  dosemumap /var/lib/dosemu/dosemu.map
</verb></tscreen>

Normally all debug logging is done _imediately_ (unbuffered). However,
when dumping big amounts of logdata, the dynamic behave of DOSEMU may
change, hence hiding the real problem (or causing a new one)
Using the below switches buffering on and sets the buffer size.

<tscreen><verb>
  logbufsize 0x20000
</verb></tscreen>

In addition, you may want to limit the file size of the log file, especially
when you expect huge amounts of data (such as with -D+e). This can be done
via
<tscreen><verb>
  logfilesize 0x200000
</verb></tscreen>

which (in this case) will limit the size to 2Mbytes. The default setting is
a file size of 10Mbytes.

When you want to abort DOSEMU from within a configuration file (because
you detected something weird) then do

<tscreen><verb>
  abort
</verb></tscreen>
or
<tscreen><verb>
  abort "message text"
</verb></tscreen>

When you want just to warn the user use the following (the message will
get printed to the log file via the debug-flag '+c')

<tscreen><verb>
  warn "message text"
</verb></tscreen>

When you want to use the CDrom driver and the Linux device is other
then /dev/cdrom you may define

<tscreen><verb>
  cdrom { /dev/xxx }
</verb></tscreen>

However, you need to include the DOSEMU supplied cdrom.sys into your config.sys
such as
<tscreen><verb>
  device=cdrom.sys
</verb></tscreen>

If you have more then one cdrom, you have to use the cdrom statement
multiple times such as
<tscreen><verb>
  cdrom { /dev/cdrom }
  cdrom { /dev/cdrom2 }
</verb></tscreen>
and have multiple instancies of the DOS driver too:
<tscreen><verb>
  device=cdrom.sys
  device=cdrom.sys 2
</verb></tscreen>

In any case you will need MSCDEX.EXE in your autoexe.bat refer to the
DOS devices MSCD0001, MSCD0002 respectively.

<sect2>Code page and character set
<p>
To select the character set and code page for use with DOSEMU we now
(against earlier versions of DOSEMU) have a separate statement:
<tscreen><verb>
  charset XXX
</verb></tscreen>
where XXX is one of
  <descrip>
    <tag/ibm/ 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).
    <tag/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.
    <tag/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)
    <tag/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.
  </descrip>
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.


<sect2>Keyboard settings
<p>
For defining the keyboard layouts you are using there is the "keyboard"
statement such as

<tscreen><verb>
  keyboard {  layout us  .... }

or

  keyboard {  layout us {alt 66=230} ... }
</verb></tscreen>

The later modifies the US keyboard layout such that it will allow you to
type a character 230 (micro) with right ALT-M.

The same can be done via a "keytable" statement such as

<tscreen><verb>
  keytable keyb-user {alt 66=230}
</verb></tscreen>

The "keyb-user" is preset with an US layout and is intended to be used
as "buffer" for user defined keyboard tables.

The format of the "{}" modification list (either in the "keyboard" or the
"keytable" statement) is as follows:

<tscreen><verb>
  [submap] key_number = value [,value [,...]]
</verb></tscreen>

Given we call the above  a "definition" then it may be repeated 
(blank separated) such as

<tscreen><verb>
  definition [definition [...]]
</verb></tscreen>

"key_number" is the physical number, that the keybord send to the machine
when you hit the key, its the index into the keytable. "value" may be
any integer between 0...255, a string, or one of the following keywords
for "dead keys" (NOTE: deadkeys have a value below 32, so be carefull).

<tscreen><verb>
  dgrave        (dead grave)
  dacute        (dead acute)
  dcircum       (dead circumflex)
  dtilde        (dead tilde)
  dbreve        (dead breve)
  daboved       (dead above dot)
  ddiares       (dead diaresis)
  dabover       (dead above ring)
  ddacute       (dead double acute)
  dcedilla      (dead cedilla)
  dogonek       (dead ogonek)
  dcaron        (dead caron)
</verb></tscreen>

After a "key_number =" there may be any number of comma separated values,
which will go into the table starting with "key_number", hence all below
examples are equivalent

<tscreen><verb>
  { 2="1" 3="2" }
  { 2="1","2" }
  { 2="12" }
  { 2=0x31,50 }
</verb></tscreen>

"submap" tells in about something about the shift state for which the
definition is to use or wether we mean the numpad:

<tscreen><verb>
  shift  16="Q"      (means key 16 + SHIFT pressed)
  alt    16="@"      (means key 16 + right ALT pressed (so called AltGr))
  numpad 12=","      (means numpad index 12)
</verb></tscreen>

You may even replace the whole table with a comma/blank separated list of
values. In order to make it easy for you, you may use dosemu to create
such a list. The following statement will dump all current key tables out
into a file "kbdtables", which is directly suitable for inclusion into
global.conf (hence it follows the syntax):

<tscreen><verb>
  keytable dump "kbdtables"
</verb></tscreen>

However, don't put this not into your global.conf, because dosemu will
exit after generating the tablefile. Instead use the -I commandline option
such as

<tscreen><verb>
  $ dos -I 'keytable dump "kbdtables"'
</verb></tscreen>

After installation of dosemu ("make install") you'll find the current dosemu
keytables in /var/lib/dosemu/keymap (and in ./etc/keymap, where they are
copied from). These tables are generated via "keytable dump" and split into
discrete files, such that you may modify them to fit your needs.
You may load them such as

<tscreen><verb>
  $ dos -I 'include "keymap/de-latin1"'
</verb></tscreen>

(when an include file is starting with "keymap/" it is taken out of
/var/lib/dosemu). When there was a keytable previously defined (e.g.
in global.conf), they new one will be take anyway and a warning will
be printed on stderr.


Anyway, you are not forced to modify or load a keytable, and
with the "layout" keyword from the "keyboard" statement, you can specify
your country's keyboard layout.
The following builtin layouts are implemented:

<tscreen><verb>
    finnish           us           dvorak       sf
    finnish-latin1    uk           sg           sf-latin1
    de                dk           sg-latin1    es
    de-latin1         dk-latin1    fr           es-latin1
    be                keyb-no      fr-latin1    po
    it                no-latin1    sw           jp106
    hu                hu-cwi       hu-latin2    keyb-user
    po                hr-cp852     hr-latin2
</verb></tscreen>


The keyb-user is selected by default if the "layout" keyword is omitted,
and this in fact is identical to us-layout, as long as it got not
overloaded by the "keytable" statement (see above).

The keyword "keybint" allows more accurate of keyboard interrupts,
It is a bit unstable, but makes keyboard work better when set to "on".

The keyword "rawkeyboard" allows for accurate keyboard emulation for
DOS programs, and is only activated when DOSEMU starts up at the
console.  It only becomes a problem when DOSEMU prematurely exits
with a "Segmentation Fault" fatal error, because the keyboard would
have not been reset properly.  In that case, you would have to run
kbd_mode -a remotely, or use the RESET button.  In reality,
this should never happen.  But if it does, please do report to the
dosemu development team, of the problem and detailed circumstances,
we're trying our best!  If you don't need near complete keyboard
emulation (needed by major software package), set it to "off"

recommended:

<tscreen><verb>
  keyboard {  layout us  keybint on  rawkeyboard off  }
</verb></tscreen>
or
<tscreen><verb>
  keyboard {  layout de-latin1  keybint on  rawkeyboard on  }
</verb></tscreen>


If you want DOSEMU feed with keystrokes, that are typed in
automagically, then you may define them such as

<tscreen><verb>
  keystroke "cd c:\\mysource\r"
</verb></tscreen>

You may have any number of 'keystroke' statements, they all will be
concatenated.

This feature however doesn't make much sense _here_ in the
configuration file, instead together with the commandine option -I
you can start dosemu and execute any arbitrary dos command such as

<tscreen><verb>
  # dos -D-a -I 'keystroke "c:\rcd \\windows\rwinemu\r"'
</verb></tscreen>

For more details please look at ./doc/README.batch

Ah, but _one_ sensible useage _here_ is to 'pre-strike' that damned F8
that is needed for DOS-7.0, when you don't want to edit the msdos.sys:

<tscreen><verb>
 keystroke "\F8;"
</verb></tscreen>


<sect2>Serial stuff
<p>
You can specify up to 4 simultaneous serial ports here.
If more than one ports have the same IRQ, only one of those ports
can be used at the same time.  Also, you can specify the com port,
base address, irq, and device path!  The defaults are:

<itemize>
<item>    COM1 default is base 0x03F8, irq 4, and device /dev/cua0
<item>    COM2 default is base 0x02F8, irq 3, and device /dev/cua1
<item>    COM3 default is base 0x03E8, irq 4, and device /dev/cua2
<item>    COM4 default is base 0x02E8, irq 3, and device /dev/cua3
</itemize>

If the "com" keyword is omitted, the next unused COM port is assigned.
Also, remember, these are only how you want the ports to be emulated
in DOSEMU.  That means what is COM3 on IRQ 5 in real DOS, can become
COM1 on IRQ 4 in DOSEMU!

<em/NOTE:/ You must have /usr/spool/uucp for LCK-file generation !
      You may change this path and the lockfile name via the
      below 'ttylocks' statement.

Also, as an example of defaults, these two lines are functionally equal:

<tscreen><verb>
  serial { com 1  mouse }
  serial { com 1  mouse  base 0x03F8  irq 4  device /dev/cua0 }
</verb></tscreen>

If you want to use a serial mouse with DOSEMU, the "mouse" keyword
should be specified in only one of the serial lines.  (For PS/2
mice, it is not necessary, and device path is in mouse line instead)

Use/modify any of the following if you want to support a modem:
(or any other serial device.)

<tscreen><verb>
  serial { com 1  device /dev/modem }
  serial { com 2  device /dev/modem }
  serial { com 3  device /dev/modem }
  serial { com 4  device /dev/modem }
  serial { com 3  base 0x03E8  irq 5  device /dev/cua2 }
</verb></tscreen>

If you are going to load a msdos mouse driver for mouse support
use/modify one of the following

<tscreen><verb>
  serial { mouse  com 1  device /dev/mouse }
  serial { mouse  com 2  device /dev/mouse }
</verb></tscreen>

What type is your mouse?  Use one of the following.
Use the 'internaldriver' option to try Dosemu internaldriver.
Use the 'emulate3buttons' for 3button mice.

<tscreen><verb>
  mouse { microsoft }
  mouse { logitech }
  mouse { mmseries }
  mouse { mouseman }
  mouse { hitachi }
  mouse { mousesystems }
  mouse { busmouse }
  mouse { ps2  device /dev/mouse internaldriver emulate3buttons }
  mouse { mousesystems device /dev/mouse internaldriver cleardtr }
</verb></tscreen>

For tty locking capabilities:

The serial lines are locked by dosemu via usual lock file technique,
which is compatible with most other unix apps (such as mgetty, dip,
e.t.c). However, you carefully need to check _where_ those other apps
expect the lock files. The most common used (old) place is
/usr/spool/uucp, but newer distributions following the FSSTND will have
it in /var/lock. The dosemu default one is /usr/spool/uucp.
The below defines /var/lock

<tscreen><verb>
  ttylocks { directory /var/lock }
</verb></tscreen>

<em/Note:/ you are responsible for ensuring that the directory exists !
If you want to define the lock prefix stub also, use this one

<tscreen><verb>
  ttylocks { directory /var/lock namestub LCK.. }
</verb></tscreen>

If the lockfile should contain the PID in binary form (instead of ASCII},
you may use the following

<tscreen><verb>
  ttylocks { directory /var/lock namestub LCK.. binary }
</verb></tscreen>


<sect2>Networking Support
<p>
Turn the following option 'on' if you require IPX/SPX emulation.
Therefore, there is no need to load IPX.COM within the DOS session.
The following option does not emulate LSL.COM, IPXODI.COM, etc.
<em>NOTE: YOU MUST HAVE IPX PROTOCOL ENABLED IN KERNEL !!</em>

<tscreen><verb>
  ipxsupport off
</verb></tscreen>

Enable Novell 8137-&gt;raw 802.3 translation hack in new packet driver.

<tscreen><verb>
  pktdriver novell_hack
</verb></tscreen>


<sect2>Terminals
<p>
This section applies whenever you run DOSEMU remotely or in an xterm.
Color terminal support is now built into DOSEMU.  Skip this section for
now to use terminal defaults, until you get DOSEMU to work.

There are a number of keywords for the terminal { } configuration line.

<descrip>
  <tag/color/ 
     Enable or disable color terminal support. One of ``on'' (default) or 
     ``off''.
  <tag/updatefreq/
     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.  However, more
     CPU time is given to DOS applications when updates are less frequent.
     A value of 4 (default) is recommended in most cases, but if you have a 
     fast system or link, you can decrease this to 0.
  <tag/escchar/
     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,
<tscreen><verb>
  F1 is 'Ctrl-^1', Alt-F7 is 'Ctrl-^s Ctrl-^7'.
  For online help, press 'Ctrl-^h' or 'Ctrl-^?'.
</verb></tscreen>

</descrip>

Use the following to enable the IBM character set.

<tscreen><verb>
  terminal { charset ibm  color on }
</verb></tscreen>

Use this for color xterms or rxvt's with no IBM font, with only 8 colors.

<tscreen><verb>
  terminal { charset latin  color on }
</verb></tscreen>

Use this for color xterms or rxvt's with IBM font, with only 8 colors.

<tscreen><verb>
  terminal { charset ibm  color on }
</verb></tscreen>

More detailed line for user configuration:

<tscreen><verb>
  terminal { charset latin  updatefreq 4  color on }
</verb></tscreen>


<sect2>X Support settings
<p>

If DOSEMU is running in its own X-window (not xterm), you may need
to tailor it to your needs. Valid keywords for the X { } config line:

<descrip>
  <tag/updatefreq/
     A number indicating the frequency of X 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.  However, more
     CPU time is given to DOS applications when updates are less frequent.
     The default is 8.

  <tag/display/
     The X server to use. If this is not specified, dosemu will use
     the DISPLAY environment variable. (This is the normal case) The default
     is ":0".

  <tag/title/
     What you want dosemu to display in the title bar of its window.
     The default is "dosemu".

  <tag/icon_name/
     Used when the dosemu window is iconified. The default is "dosemu".

  <tag/keycode/
     Used to give Xdos access to keycode part of XFree86. The default is off.

     <em/NOTE:/
     <itemize>
       <item> You should _not_ use this when using X remotely
          (the remote site may have other raw keyboard settings).
       <item> <em/If/ you use "keycode", you also <em/must/ define an 
          appropriate keyboard layout (see above).
       <item> If you do <em/not/ use "keycode" then under X a neutral keyboard
          layout is forced ( <tt/keyboard {layout us}/ ) regardless of
	  what you have set above.
      </itemize>

       Anyway, a cleaner way than using "keycode" is to let the X-server
       fiddle with keyboard translation and customize it via .xmodmaps.

  <tag/blinkrate/
     A number which sets the blink rate for the cursor. The default is 8.

  <tag/font/
     Used to pick a font other than vga (default). Must be monospaced.

  <tag/mitshm/
     Use shared memory extensions. The default is ``on''.

  <tag/sharecmap/
     Used to share the colormap with other applications in graphics mode.
     If not set, a private colormap is used. The default is off.

  <tag/fixed_aspect/
     Set fixed aspect for resize the graphics window. One of ``on'' (default)
     or ``off''.

  <tag/aspect_43/
     Always use an aspect ratio of 4:3 for graphics. The default is 
     ``floating''.

  <tag/lin_filt/
     Use linear filtering for &gt;15 bpp interpolation. The default is off.

  <tag/bilin_filt/
     Use bi-linear filtering for &gt;15 bpp interpolation. The default is off.

  <tag/mode13fact/
     A number which sets the initial size factor for video mode 0x13 (320x200).
     The default is 2.

  <tag/winsize/
     A pair of numbers which set the initial width and height of the window to a fixed 
     value. The default is to float.

  <tag/gamma/
    Set value for gamma correction, a value of 100 means gamma 1.0. The default
	is 100.

  <tag/vgaemu_memsize/
     Set the size (in Kbytes) of the frame buffer for emulated vga under X. The
	default is 1024.

  <tag/lfb/
     Enable or disable the linear frame buffer in VESA modes. The default is ``on''.

  <tag/pm_interface/
     Enable or disable the protected mode interface for VESA modes. The default is ``on''.

  <tag/mgrab_key/
     String, name of KeySym name to activate mouse grab. Default is `empty'
     (no mouse grab). A possible value could be "Home".

  <tag/vesamode/
     Define a VESA mode. Two variants are supported: vesamode width height
     and vesamode width height color_bits. The first adds the specified
     resolution in all supported color depths (currently 8, 15, 16, 24 and 32
     bit).
</descrip>

Recommended X statement:

<tscreen><verb>
  X { updatefreq 8 title "DOS in a BOX" icon_name "xdos" }
</verb></tscreen>

<sect2>Video settings ( console only )
<p>

<em>!!WARNING!!: A LOT OF THIS VIDEO CODE IS ALPHA!  IF YOU ENABLE GRAPHICS
ON AN INCOMPATIBLE ADAPTOR, YOU COULD GET A BLANK SCREEN OR MESSY SCREEN
EVEN AFTER EXITING DOSEMU.  JUST REBOOT (BLINDLY) AND THEN MODIFY CONFIG.
</em>

Start with only text video using the following line, to get started.
then when DOSEMU is running, you can set up a better video configuration.

<tscreen><verb>
  video { vga }                    Use this line, if you are using VGA
  video { cga  console }           Use this line, if you are using CGA
  video { ega  console }           Use this line, if you are using EGA
  video { mda  console }           Use this line, if you are using MDA
</verb></tscreen>

Notes for Graphics:
<itemize>
  <item> If your VGA-Bios resides at E000-EFFF, turn off video BIOS shadow
    for this address range and add the statement vbios_seg 0xe000
    to the correct vios-statement, see the example below
  <item> If your VBios size is only 32K you set it with  vbios_size 0x8000,
    you then gain some space for UMB or hardware ram locations.
  <item> Set "allowvideoportaccess on" earlier in this configuration file
    if DOSEMU won't boot properly, such as hanging with a blank screen,
    beeping, leaving Linux video in a bad state, or the video card
    bootup message seems to stick.
  <item> Video BIOS shadowing (in your CMOS setup) at C000-CFFF must be disabled.

    <em/CAUTION:/ TURN OFF VIDEO BIOS SHADOWING BEFORE ENABLING GRAPHICS!
                   This is not always necessary, but a word to the wise
                   shall be sufficient.

  <item> If you have a dual-monitor configuration (e.g. MDA as second display),
    you then may run CAD programs on 2 displays or let play your debugger
    on the MDA while debugging a graphics program on the VGA (e.g TD -do ).
    You also may switch to the MDA display by using the DOS command
    mode mono (mode co80 returns to your normal display).
    This feature can be enabled by the switch "dualmon" like this:
<tscreen><verb>
      video { vga  console  graphics dualmon }
</verb></tscreen>
    and can be used on a xterm and the console, but of course not, if you
    have the MDA as your primary display.
    You also must set USE_DUALMON 1 in include/video.h.
    <em/NOTE:/ Make sure no more then one process is using this feature !
          ( you will get funny garbage on your MDA display. )
          Also, you must NOT have the dualmon-patches for kernel applied
          ( having the MDA as Linux console )
  <item> If you want to run dosemu in situations when human doesn't sit at console
    (for instance to run it by cron) and want console option be enabled
    you should use option forcevtswitch.
<tscreen><verb>
           { vga console forcevtswitch }
</verb></tscreen>
    Without the option dosemu waits for becoming virtual terminal
    on which dosemu is run active (i.e. user must press Alt-F?).
    With this option dosemu perform the switch itself.
    Be careful with this option because with it user sat at console
    may face with unexpected switch.
</itemize>

It may be necessary to set this to "on" if DOSEMU can't boot up properly
on your system when it's set "off" and when graphics are enabled.
<em/Note:/ May interfere with serial ports when using certain video boards.

<tscreen><verb>
  allowvideoportaccess on
</verb></tscreen>

Any 100% compatible standard VGA card <em/MAY/ work with this:

<tscreen><verb>
  video { vga  console  graphics }
</verb></tscreen>

If your VGA-BIOS is at segment E000, this may work for you:

<tscreen><verb>
  video { vga  console  graphics  vbios_seg 0xe000 }
</verb></tscreen>

Trident SVGA with 1 megabyte on board

<tscreen><verb>
  video { vga  console  graphics  chipset trident  memsize 1024 }
</verb></tscreen>

Diamond SVGA (not S3 chip)

<tscreen><verb>
  video { vga  console  graphics  chipset diamond }
</verb></tscreen>

Cirrus SVGA

<tscreen><verb>
  video { vga  console  graphics  chipset cirrus }
</verb></tscreen>

ET4000 SVGA card with 1 megabyte on board:

<tscreen><verb>
  video { vga  console  graphics  chipset et4000  memsize 1024 }
</verb></tscreen>
or
<tscreen><verb>
  video { vga  console  graphics  chipset et4000  memsize 1024 vbios_size 0x8000 }
</verb></tscreen>

S3-based SVGA video card with 1 megabyte on board:

<tscreen><verb>
  video { vga  console  graphics  chipset s3  memsize 1024 }
</verb></tscreen>

Avance Logic (ALI) 230x SVGA

<tscreen><verb>
  video { vga  console  graphics  chipset avance }
</verb></tscreen>

For ATI graphic mode

<tscreen><verb>
  ports { 0x1ce 0x1cf 0x238 0x23b 0x23c 0x23f 0x9ae8 0x9ae9 0x9aee 0x9aef }
</verb></tscreen>


Matrox millenium:

<tscreen><verb>
  video { vga  console  graphics  chipset matrox }
</verb></tscreen>



VGA-cards with a WD(Paradise) chip:

<tscreen><verb>
  video { vga  console  graphics  chipset wdvga }
</verb></tscreen>



<sect2>Memory settings
<p>

These are memory parameters, stated in number of kilobytes.
If you get lots of disk swapping while DOSEMU runs, you should
reduce these values.

umb_max is a new parameter which tells DOSEMU to be more aggressive
about finding upper memory blocks.  The default is 'off'.


To be more aggressive about finding XMS UMB blocks use this:

<tscreen><verb>
  umb_max on
</verb></tscreen>

To be more secure use 'secure on'. If "on", then it disables DPMI access
to dosemu code and also disables execution of dosemu supplied 'system'
commands, which may execute arbitrary Linux-commands otherwise.
The background is, that DPMI clients are allowed to create selectors
that span the whole user space, hence may hack into the dosemu code,
and (when dosemu runs root or is suid root) can be a security hole.
"secure on" closes this hole, though this would very likely also disable
some dos4gw games :(.
Therfore <em/NOTE:/ You may not be able to run some DPMI programs, hence,
before reporting such a program as 'not running', first try to set 'secure off'.

<tscreen><verb>
  secure on                # "on" or "off"
</verb></tscreen>


The below enables/disables DPMI and sets the size of DPMI memory.

<tscreen><verb>
  dpmi 4086                # DPMI size in K, or "off"
</verb></tscreen>

The best solution (security wise), however, is to run dosemu <em/non-suid root/
under X (which is possible since dosemu-0.97.10). Under X most of the
things we would need to run under root privilidges aren't needed, as the
X server supports them. And giving DPMI access to non-suid root dosemu
is <em/not/ at all critical. You may forbid some users to use an eventually
available suid root binary by setting `nosuidroot' in /etc/dosemu.users.

XMS is enabled by the following statement

<tscreen><verb>
  xms 1024		   # XMS size in K,  or "off"
</verb></tscreen>

For ems, you now can set the frame to any 16K between 0xc800..0xe000

<tscreen><verb>
  ems 1024		   # EMS size in K,  or "off"
</verb></tscreen>
or
<tscreen><verb>
  ems { ems_size 1024 ems_frame 0xe000 }
</verb></tscreen>
or
<tscreen><verb>
  ems { ems_size 2048 ems_frame 0xd000 }
</verb></tscreen>

If you have adapters, which have memory mapped IO, you may map those regions
with <tt/hardware_ram { .. }/. You can only map in entities of 4k, you give the
address, not the segment.
The below maps 0xc8000..0xc8fff and 0xcc000..0xcffff:

<tscreen><verb>
  hardware_ram { 0xc8000 range 0xcc000 0xcffff }
</verb></tscreen>

With the below you define the maximum conventional RAM to show apps:

<tscreen><verb>
  dosmem 640
</verb></tscreen>


<sect2>IRQ passing
<p>

The irqpassing statement accepts IRQ values between 3..15,
if using the { .. } syntax each value or range can be prefixed
by the keyword use_sigio to monitor the IRQ via SIGIO.
If this is missing the IRQ is monitored by SIGALRM.

Use/modify one of the below statements

<tscreen><verb>
  irqpassing off    # this disables IRQ monitoring
  irqpassing 15
  irqpassing { 15 }
  irqpassing { use_sigio 15 }
  irqpassing { 10  use_sigio range 3 5 }
</verb></tscreen>


<sect2>Port Access
<p>

<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.</bf>

<p>
These keywords are allowable on a "ports" line.

<descrip>
  <tag>range <tt/addr1 addr2/ </tag>
	This allow access to this range of ports
  <tag>ormask <tt/value/ </tag>
	The default is 0
  <tag>andmask <tt/value/</tag>
	The default is 0xffff
  <tag/rdonly|wronly|rdwr/
	This specifies what kind of access to allow to the ports. The default
	is "rdwr"
  <tag/fast/
    Put port(s) in the ioperm bitmap (only valid for ports below 0x400)
    An access doesn't trap and isn't logged, but as vm86() isn't interrupted, 
    it's much faster. The default is not fast.
  <tag>device <tt/name/ </tag>         
    If the ports are registered, open this device to block access. The open()
    must be successfull or access to the ports will be denied. If you know 
    what you are doing, use <tt>/dev/null</tt> to fake a device to block
</descrip>

<tscreen><verb>
  ports { 0x388 0x389 }   # for SimEarth
  ports { 0x21e 0x22e 0x23e 0x24e 0x25e 0x26e 0x27e 0x28e 0x29e } # for jill
</verb></tscreen>


<sect2>Speaker
<p>

These keywords are allowable on the "speaker" line:

<descrip>
   <tag/native/      Enable DOSEMU direct access to the speaker ports.
   <tag/emulated/    Enable simple beeps at the terminal.
   <tag/off/         Disable speaker emulation.
</descrip>

Recommended:

<tscreen><verb>
  speaker off
</verb></tscreen>


<sect2>Hard disks
<p>

<bf>WARNING: DAMAGE MIGHT RESULT TO YOUR HARD DISK (LINUX AND/OR DOS)
IF YOU FIDDLE WITH THIS SECTION WITHOUT KNOWING WHAT YOU'RE DOING!</bf>

<p>
The best way to get started is to start with a hdimage, and set "<tt/bootC/"
and "<tt/disk {image "/var/lib/dosemu/hdimage.first" }/" in global.conf.
To generate this first working and bootable hdimage, you should use
"<tt/setup-hdimage/" in the dosemu root directory. This script extracts your 
DOS from any native bootable DOS-partition and builts a bootable hdimage.
(for experience dosemu users: you need not to fiddle with floppies any more)
Keep using the hdimage while you are setting this hard disk configuration up
for DOSEMU, and testing by using <tt/DIR C:/ or something like that.
Whenever possible, use hdimage, mount your DOS partition under Linux
and "<tt/lredir/" it into dosemu. Look at <ref id="lredir" name="Using
Lredir">, <ref id="runasuser" name="Running as a user">,
QuickStart etc. on how to use "lredir".

As a last resort, if you want DOSEMU to be able to access a DOS partition, the
safer type of access is "partition" access, because "wholedisk"
access gives DOSEMU write access to a whole physical disk,
including any vulnerable Linux partitions on that drive!

<em/IMPORTANT/

You must not have LILO installed on the partition for dosemu to boot off.
As of 04/26/94, doublespace and stacker 3.1 will work with wholedisk
or partition only access.  Stacker 4.0 has been reported to work with
wholedisk access.

Please read the documentation in the "doc" subdirectory for info
on how to set up access to real hard disk.

These are meanings of the keywords:

<descrip>
  <tag/image/ specifies a hard disk image file.
  <tag/partition/ specifies partition access, with device and partition number.
  <tag/wholedisk/ specifies full access to entire hard drive.
  <tag/readonly/ for read only access.  A good idea to set up with.
  <tag/diskcyl4096/ INT13 support for more then 1024 cylinders, bits 6/7 of
  DH (head) used to build a 12 bit cylinder number.
  <tag/bootfile/ to specify an image of a boot sector to boot from.
</descrip>

Use/modify one (or more) of the folling statements:

<tscreen><verb>
  disk { image "/var/lib/dosemu/hdimage" }      # use diskimage file.
  disk { partition "/dev/hda1" readonly }       # 1st partition on 1st IDE.
  disk { partition "/dev/hda1" bootfile "/var/lib/bootsect.dos" }
                                                # 1st partition on 1st IDE
                                                # booting from the specified
                                                # file.
  disk { partition "/dev/hda6" readonly }       # 6th logical partition.
  disk { partition "/dev/sdb1" readonly }       # 1st partition on 2nd SCSI.
  disk { wholedisk "/dev/hda" }                 # Entire disk drive unit
</verb></tscreen>

Recommended:

<tscreen><verb>
  disk { image "/var/lib/dosemu/hdimage" }
</verb></tscreen>


<sect2>DOSEMU boot
<p>

Use the following option to boot from the specified file, and then
once booted, have bootoff execute in autoexec.bat. Thanks Ted :-).
Notice it follows a typical floppy spec. To create this file use:

<tscreen><verb>
dd if=/dev/fd0 of=/var/lib/dosemu/bdisk bs=16k
</verb></tscreen>

<tscreen><verb>
  bootdisk { heads 2 sectors 18 tracks 80 threeinch file /var/lib/dosemu/bdisk }
</verb></tscreen>

Specify extensions for the CONFIG and AUTOEXEC files.  If the below
are uncommented, the extensions become CONFIG.EMU and AUTOEXEC.EMU.
NOTE: this feature may affect file naming even after boot time.
If you use MSDOS 6+, you may want to use a CONFIG.SYS menu instead.

<tscreen><verb>
  EmuSys EMU
  EmuBat EMU
</verb></tscreen>



<sect2>Floppy disks
<p>

This part is fairly easy.  Make sure that the first (/dev/fd0) and
second (/dev/fd1) floppy drives are of the correct size, "threeinch"
and/or "fiveinch".  A floppy disk image can be used instead, however.

<bf>FOR SAFETY, UNMOUNT ALL FLOPPY DRIVES FROM YOUR FILESYSTEM BEFORE
STARTING UP DOSEMU!  DAMAGE TO THE FLOPPY MAY RESULT OTHERWISE!</bf>

Use/modify one of the below:

<tscreen><verb>
  floppy { device /dev/fd0 threeinch }
  floppy { device /dev/fd1 fiveinch }
  floppy { heads 2  sectors 18  tracks 80
           threeinch  file /var/lib/dosemu/diskimage }
</verb></tscreen>

If floppy disk speed is very important, uncomment the following
line.  However, this makes the floppy drive a bit unstable.  This
is best used if the floppies are write-protected.
Use an integer value to set the time between floppy updates.

<tscreen><verb>
  FastFloppy 8
</verb></tscreen>


<sect2>Printers
<p>

Printer is emulated by piping printer data to a file or via a unix
command such as "lpr".  Don't bother fiddling with this configuration
until you've got DOSEMU up and running already.

NOTE: Printers are assigned to LPT1:, LPT2:, and LPT3: on a one for
one basis with each line below.  The first printer line is assigned
to LPT1:, second to LPT2:, and third to LPT3:.  If you do not specify
a base port, the emulator will setup the bios to report 0x378, 0x278,
and 0x3bc for LPT1:, LPT2:, and LPT3: respectively.

To use standard unix lpr command for printing use this line:

<tscreen><verb>
  printer { options "%s"  command "lpr"  timeout 20 }
</verb></tscreen>

And for any special options like using pr to format files,
add it to the options parameter:

<tscreen><verb>
  printer { options "-p %s"  command "lpr"  timeout 10 }     pr format it
</verb></tscreen>

To just have your printer output end up in a file, use the following line:

<tscreen><verb>
  printer { file "lpt3" }
</verb></tscreen>

If you have a DOS application that is looking to access the printer
port directly, and uses the bios LPT: setting to find out the port to use,
you can modify the base port the bios will report with the following:

<tscreen><verb>
  printer { options "%s"  command "lpr"  base 0x3bc }
</verb></tscreen>

Be sure to also add a port line to allow the application access to
the port:

<tscreen><verb>
  ports { device /dev/lp0 0x3bc 0x3bd 0x3be }
</verb></tscreen>

NOTE: applications that require this will not interfere with applications
that continue to use the standard bios calls.  These applications will
continue to send the output piped to the file or unix command.

<sect2>Sound
<p>

The sound driver is more or less likely to be broken at the moment.

<descrip>
  <tag/sb_base/  base address of the SB (HEX)
  <tag/sb_irq/ IRQ for the SB
  <tag/sb_dma/ DMA channel for the SB
  <tag/sb_dsp/ Path the sound device
  <tag/sb_mixer/ path to the mixer control
  <tag/mpu_base/ base address for the MPU-401 chip (HEX) (Not Implemented)
</descrip>

Use this to disable sound support even if it is configured in

<tscreen><verb>
  sound_emu off
</verb></tscreen>

Linux defaults

<tscreen><verb>
  sound_emu { sb_base 0x220 sb_irq 5 sb_dma 1 sb_dsp /dev/dsp
               sb_mixer /dev/mixer mpu_base 0x330 }
</verb></tscreen>

NetBSD defaults

<tscreen><verb>
  sound_emu { sb_base 0x220 sb_irq 5 sb_dma 1 sb_dsp /dev/sound
              sb_mixer /dev/mixer mpu_base 0x330 }
</verb></tscreen>


<sect2>DEXE support
<p>

These are the setting for DEXE type DOS application, which are executed
by DOSEMU via the -L option.
( for what DEXE is look at ./doc/README.dexe

set the below to force 'secure on', when -L option is used _and_ the user
isn't root.

<tscreen><verb>
  dexe { secure }
</verb></tscreen>

set the below, if you want that a dexe may be allowed to have additional
disks. Normally the hdimage containing the DOS app (the .dexe itself) is
the only available disk, all other 'disk {}' statement are ignored.

<tscreen><verb>
  dexe { allowdisk }
</verb></tscreen>

set the below, if you want a DEXE to be forced to 'xdos', when X
available. This mainly is intended for beeing included into the
configuration of a DEXE file (see mkdexe). e.g. when the application
needs graphic it should not run on slang-terminal.

<tscreen><verb>
  dexe { forcexdos }
</verb></tscreen>

set the below, if you want a DEXE _only_ running on X (because it otherwise
would not run)

<tscreen><verb>
  dexe { xdosonly }
</verb></tscreen>


