1mtools.1(3)                         MTOOLS                         mtools.1(3)
2
3
4

Name

6       mtools.conf - mtools configuration files
7
8
9

Description

11       This  manpage  describes  the  configuration files for mtools. They are
12       called `/etc/mtools.conf' and `~/.mtoolsrc'. If the environmental vari‐
13       able  MTOOLSRC is set, its contents is used as the filename for a third
14       configuration file. These configuration files  describe  the  following
15       items:
16
17       *  Global configuration flags and variables
18
19       *  Per drive flags and variables
20
21   Location of the configuration files
22       `/etc/mtools.conf'   is   the   system-wide   configuration  file,  and
23       `~/.mtoolsrc' is the user's private configuration file.
24
25       On  some  systems,  the  system-wide  configuration  file   is   called
26       `/etc/default/mtools.conf' instead.
27
28     General configuration file syntax
29       The  configuration  files  is  made up of sections. Each section starts
30       with a keyword identifying the section followed by a colon.  Then  fol‐
31       low  variable assignments and flags. Variable assignments take the fol‐
32       lowing form:
33       name=value
34
35       Flags are lone keywords without an equal sign and value following them.
36       A  section either ends at the end of the file or where the next section
37       begins.
38
39       Lines starting with a hash (#) are  comments.  Newline  characters  are
40       equivalent  to whitespace (except where ending a comment). The configu‐
41       ration file is case insensitive, except for  item  enclosed  in  quotes
42       (such as filenames).
43
44   Default values
45       For most platforms, mtools contains reasonable compiled-in defaults for
46       physical floppy drives.  Thus, you usually don't need  to  bother  with
47       the  configuration file, if all you want to do with mtools is to access
48       your floppy drives. On the other hand, the configuration file is needed
49       if  you also want to use mtools to access your hard disk partitions and
50       dosemu image files.
51
52   Global variables
53       Global flags may be set to 1 or to 0.
54
55       The following global flags are recognized:
56
57       MTOOLS_SKIP_CHECK
58              If this is set to 1, mtools skips most  of  its  sanity  checks.
59              This  is  needed  to  read some Atari disks which have been made
60              with the earlier ROMs, and which would not be recognized  other‐
61              wise.
62
63       MTOOLS_FAT_COMPATIBILITY
64              If  this  is  set  to  1, mtools skips the fat size checks. Some
65              disks have a bigger FAT than they  really  need  to.  These  are
66              rejected if this option is not set.
67
68       MTOOLS_LOWER_CASE
69              If  this is set to 1, mtools displays all-upper-case short file‐
70              names as lowercase. This has been done to allow a behavior which
71              is  consistent  with  older versions of mtools which didn't know
72              about the case bits.
73
74       MTOOLS_NO_VFAT
75              If this is set to 1, mtools  won't  generate  VFAT  entries  for
76              filenames  which  are  mixed-case, but otherwise legal dos file‐
77              names.  This is useful when  working  with  DOS  versions  which
78              can't grok VFAT longnames, such as FreeDos.
79
80       MTOOLS_DOTTED_DIR
81              In a wide directory, prints the short name with a dot instead of
82              spaces separating the basename and the extension.
83
84       MTOOLS_NAME_NUMERIC_TAIL
85              If this is set to one (default), generate numeric tails for  all
86              long names (~1).  If set to zero, only generate numeric tails if
87              otherwise a clash would have happened.
88
89       MTOOLS_TWENTY_FOUR_HOUR_CLOCK
90              If 1, uses the European notation for  times  (twenty  four  hour
91              clock), else uses the UK/US notation (am/pm)
92
93       Example:  Inserting  the  following  line  into your configuration file
94       instructs mtools to skip the sanity checks:
95
96            MTOOLS_SKIP_CHECK=1
97
98
99
100       Global variables may also be set via the environment:
101
102            export MTOOLS_SKIP_CHECK=1
103
104
105
106       Global string variables may be set to any value:
107
108       MTOOLS_DATE_STRING
109              The format used for printing dates of files.  By default, is dd-
110              mm-yyyy.
111
112   Per drive flags and variables
113     General information
114       Per drive flags and values may be described in a drive section. A drive
115       section starts with drive "driveletter" :
116
117       Then follow variable-value pairs and flags.
118
119       This is a sample drive description:
120
121            drive a:
122              file="/dev/fd0" use_xdf=1
123
124
125
126     Location information
127       For each drive, you need to  describe  where  its  data  is  physically
128       stored (imag file, physical device, partition, offset).
129
130       file   The  name  of the file or device holding the disk image. This is
131              mandatory. The file name should be enclosed in quotes.
132
133       partition
134              Tells mtools to treat the drive as a partitioned device, and  to
135              use  the given partition. Only primary partitions are accessible
136              using this method, and they are numbered from 1 to 4. For  logi‐
137              cal partitions, use the more general offset variable. The parti‐
138              tion variable is intended for removable media such as  Syquests,
139              ZIP  drives, and magneto-optical disks. Although traditional DOS
140              sees Syquests and magneto-optical disks as `giant floppy  disks'
141              which  are  unpartitioned,  OS/2  and Windows NT treat them like
142              hard disks, i.e. partioned devices. The partition flag  is  also
143              useful DOSEMU hdimages. It is not recommended for hard disks for
144              which direct access to partitions is available through mounting.
145
146       offset
147              Describes where in the file the MS-DOS filesystem  starts.  This
148              is  useful  for  logical  partitions in DOSEMU hdimages, and for
149              ATARI ram disks. By default, this  is  zero,  meaning  that  the
150              filesystem starts right at the beginning of the device or file.
151
152     Disk Geometry Configuration
153       Geometry  information  describes the physical characteristics about the
154       disk. Its has three purposes:
155
156       formatting
157              The geometry information is written into the boot sector of  the
158              newly  made  disk.  However,  you may also describe the geometry
159              information on  the  command  line.  See  section  mformat,  for
160              details.
161
162       filtering
163              On  some  Unices  there  are device nodes which only support one
164              physical geometry. For instance, you might need a different node
165              to access a disk as high density or as low density. The geometry
166              is compared to the actual geometry stored on the boot sector  to
167              make  sure  that  this device node is able to correctly read the
168              disk. If the geometry doesn't match, this drive entry fails, and
169              the next drive entry bearing the same drive letter is tried. See
170              section multiple descriptions, for  more  details  on  supplying
171              several descriptions for one drive letter.
172
173              If  no  geometry  information  is  supplied in the configuration
174              file, all disks are accepted. On  Linux  (and  on  Sparc)  there
175              exist  device  nodes  with  configurable  geometry  (`/dev/fd0',
176              `/dev/fd1' etc), and thus filtering is not needed (and  ignored)
177              for disk drives.  (Mtools still does do filtering on plain files
178              (disk images) in Linux: this is mainly intended  for  test  pur‐
179              poses,  as  I  don't  have access to a Unix which would actually
180              need filtering).
181
182              If you do not need filtering, but want still a default  geometry
183              for  mformatting,  you  may switch off filtering using the mfor‐
184              mat_only flag.
185
186              If you want filtering, you should supply the  filter  flag.   If
187              you supply a geometry, you must supply one of both flags.
188
189       initial geometry
190              On  devices that support it (usually floppy devices), the geome‐
191              try information is also used to set the initial  geometry.  This
192              initial geometry is applied while reading the boot sector, which
193              contains the real geometry.  If no geometry information is  sup‐
194              plied  in the configuration file, or if the mformat_only flag is
195              supplied, no initial configuration is done.
196
197              On Linux, initial geometry is not really needed, as the  config‐
198              urable  devices are able to auto-detect the disk type accurately
199              enough (for most common formats) to read the boot sector.
200
201       Wrong geometry information may lead to very bizarre errors. That's  why
202       I  strongly  recommend that you add the mformat_only flag to your drive
203       description, unless you really need filtering or initial geometry.
204
205       The following geometry related variables are available:
206
207       cylinders
208       tracks The number of  cylinders.  (cylinders  is  the  preferred  form,
209              tracks is considered obsolete)
210
211       heads  The number of heads (sides).
212
213       sectors
214              The number of sectors per track.
215
216       Example: the following drive section describes a 1.44M drive:
217
218            drive a:
219                file="/dev/fd0H1440"
220                fat_bits=12
221                cylinders=80 heads=2 sectors=18
222                mformat_only
223
224
225
226       The following shorthand geometry descriptions are available:
227
228       1.44m  high density 3 1/2 disk. Equivalent to: fat_bits=12 cylinders=80
229              heads=2 sectors=18
230
231       1.2m   high density 5 1/4 disk. Equivalent to: fat_bits=12 cylinders=80
232              heads=2 sectors=15
233
234       720k   double  density  3  1/2  disk. Equivalent to: fat_bits=12 cylin‐
235              ders=80 heads=2 sectors=9
236
237       360k   double density 5 1/4 disk.  Equivalent  to:  fat_bits=12  cylin‐
238              ders=40 heads=2 sectors=9
239
240       The  shorthand  format  descriptions  may be amended. For example, 360k
241       sectors=8 describes a 320k  disk  and  is  equivalent  to:  fat_bits=12
242       cylinders=40 heads=2 sectors=8
243
244     Open Flags
245       Moreover, the following flags are available:
246
247       sync   All i/o operations are done synchronously
248
249       nodelay
250              The  device  or  file  is opened with the O_NDELAY flag. This is
251              needed on some non-Linux architectures.
252
253       exclusive
254              The device or file is opened with the  O_EXCL  flag.  On  Linux,
255              this ensures exclusive access to the floppy drive. On most other
256              architectures, and for plain files it has no effect at all.
257
258     General Purpose Drive Variables
259       The following general purpose drive variables are available.  Depending
260       to  their  type,  these variables can be set to a string (precmd) or an
261       integer (all others)
262
263       fat_bits
264              The number of FAT bits. This may be  12  or  16.  This  is  very
265              rarely  needed, as it can almost always be deduced from informa‐
266              tion in the boot sector. On the contrary, describing the  number
267              of  fat  bits  may  actually be harmful if you get it wrong. You
268              should only use it if mtools gets the autodetected number of fat
269              bits wrong, or if you want to mformat a disk with a weird number
270              of fat bits.
271
272       codepage
273              Describes the DOS codepage used for short filenames. This  is  a
274              number  between 1 and 999. By default, codepage 850 is used. The
275              reason for this is because this codepage contains  most  of  the
276              characters  that are also available in ISO-Latin-1. You may also
277              specify a global codepage for all drives  by  using  the  global
278              default_codepage  parameter  (outside of any drive description).
279              This parameters exists starting at version 4.0.0
280
281       precmd
282              On some variants of Solaris, it is necessary to  call  'volcheck
283              -v'  before  opening a floppy device, in order for the system to
284              notice  that  there   is   indeed   a   disk   in   the   drive.
285              precmd="volcheck -v" in the drive clause establishes the desired
286              behavior.
287
288       blocksize
289              This parameter represents a default block size to be always used
290              on  this  device.   All I/O is done with multiples of this block
291              size,  independantly  of  the  sector  size  registered  in  the
292              filesystem's  boot sector.  This is useful for character devices
293              whose sector size is not 512, such as for example CD Rom  drives
294              on Solaris.
295
296       Only  the  file variable is mandatory. The other parameters may be left
297       out. In that case a default value or an autodetected value is used.
298
299     General Purpose Drive Flags
300       A flag can either be set to 1 (enabled) or 0 (disabled). If  the  value
301       is ommitted, it is enabled.  For example, scsi is equivalent to scsi=1
302
303       nolock
304              Instruct  mtools  to  not  use  locking  on this drive.  This is
305              needed  on  systems  with  buggy  locking  semantics.   However,
306              enabling  this  makes operation less safe in cases where several
307              users may access the same drive at the same time.
308
309       scsi   When set to 1, this option tells mtools  to  use  raw  SCSI  I/O
310              instead  of  the standard read/write calls to access the device.
311              Currently, this is supported on HP/UX, Solaris and SunOs.   This
312              is  needed  because  on  some  architectures,  such  as SunOs or
313              Solaris, PC media can't be accessed using  the  read  and  write
314              syscalls,  because the OS expects them to contain a Sun specific
315              "disk label".
316
317              As raw Scsi access always uses the whole  device,  you  need  to
318              specify the "partition" flag in addition
319
320              On some architectures, such as Solaris, mtools needs root privi‐
321              leges to be able to use the scsi option.  Thus mtools should  be
322              installed  set uid root on Solaris if you want to access Zip/Jaz
323              drives.  Thus, if the scsi flag is given, privileged is automat‐
324              ically implied, unless explicitly disabled by privileged=0
325
326              Mtools uses its root privileges to open the device, and to issue
327              the actual SCSI I/O calls.  Moreover, root privileges  are  only
328              used  for  drives  described in a system-wide configuration file
329              such as `/etc/mtools.conf',  and  not  for  those  described  in
330              `~/.mtoolsrc' or `$MTOOLSRC'.
331
332       privileged
333              When set to 1, this instructs mtools to use its set-uid and set-
334              gid privileges for opening the given drive.  This option is only
335              valid  for  drives  described  in  the system-wide configuration
336              files (such as `/etc/mtools.conf', not `~/.mtoolsrc' or `$MTOOL‐
337              SRC').   Obviously, this option is also a no op if mtools is not
338              installed setuid or setgid.  This option is implied by 'scsi=1',
339              but  again  only for drives defined in system-wide configuration
340              files.  Privileged may also be set explicitely to 0, in order to
341              tell  mtools not to use its privileges for a given drive even if
342              scsi=1 is set.
343
344              Mtools only needs to be installed setuid if you use  the  privi‐
345              leged or scsi drive variables.  If you do not use these options,
346              mtools works perfectly well even when not installed setuid root.
347
348       vold
349
350              Instructs mtools to interpret the device name as a vold  identi‐
351              fier  rather  than as a filename.  The vold identifier is trans‐
352              lated into  a  real  filename  using  the  media_findname()  and
353              media_oldaliases()  functions  of the volmgt library.  This flag
354              is only available if you configured mtools  with  the  --enable-
355              new-vold option before compilation.
356
357       swap
358
359              Consider the media as a word-swapped Atari disk.
360
361       use_xdf
362              If  this is set to a non-zero value, mtools also tries to access
363              this disk as an XDF disk. XDF is a high capacity format used  by
364              OS/2. This is off by default. See section XDF, for more details.
365
366       mformat_only
367              Tells  mtools  to use the geometry for this drive only for mfor‐
368              matting and not for filtering.
369
370       filter
371              Tells mtools to use the geometry for this drive both  for  mfor‐
372              matting and filtering.
373
374       remote
375              Tells mtools to connect to floppyd (see section  floppyd).
376
377     Supplying multiple descriptions for a drive
378       It  is  possible  to  supply multiple descriptions for a drive. In that
379       case, the descriptions are tried in order until one is found that fits.
380       Descriptions may fail for several reasons:
381
382       1.     because the geometry is not appropriate,
383
384       2.     because there is no disk in the drive,
385
386       3.     or because of other problems.
387
388       Multiple  definitions  are useful when using physical devices which are
389       only able to support one single disk geometry.  Example:
390
391            drive a: file="/dev/fd0H1440" 1.44m
392            drive a: file="/dev/fd0H720" 720k
393
394
395
396       This instructs mtools to use /dev/fd0H1440  for  1.44m  (high  density)
397       disks  and /dev/fd0H720 for 720k (double density) disks. On Linux, this
398       feature is not really needed, as the /dev/fd0 device is able to  handle
399       any geometry.
400
401       You  may  also  use  multiple drive descriptions to access both of your
402       physical drives through one drive letter:
403
404            drive z: file="/dev/fd0"
405            drive z: file="/dev/fd1"
406
407
408
409       With this description, mdir z: accesses your first physical drive if it
410       contains  a  disk.  If  the  first drive doesn't contain a disk, mtools
411       checks the second drive.
412
413       When using multiple configuration  files,  drive  descriptions  in  the
414       files  parsed  last override descriptions for the same drive in earlier
415       files. In order to avoid  this,  use  the  drive+  or  +drive  keywords
416       instead  of  drive. The first adds a description to the end of the list
417       (i.e. it will be tried last), and the first adds it to the start of the
418       list.
419
420   Location of configuration files and parsing order
421       The configuration files are parsed in the following order:
422
423       1.     compiled-in defaults
424
425       2.     `/etc/mtools.conf'
426
427       3.     `/etc/mtools'  This  is for backwards compatibility only, and is
428              only parsed if `mtools.conf' doesn't exist.
429
430       4.     `~/.mtoolsrc'.
431
432       5.     `$MTOOLSRC' (file pointed by the  MTOOLSRC  environmental  vari‐
433              able)
434
435       Options  described  in  the later files override those described in the
436       earlier files. Drives defined in earlier files persist if they are  not
437       overridden  in  the  later  files.  For instance, drives A and B may be
438       defined in `/etc/mtools.conf' and drives C and  D  may  be  defined  in
439       `~/.mtoolsrc'  However, if `~/.mtoolsrc' also defines drive A, this new
440       description  would   override   the   description   of   drive   A   in
441       `/etc/mtools.conf'  instead  of  adding to it. If you want to add a new
442       description to a drive already described in an earlier file,  you  need
443       to use either the +drive or drive+ keyword.
444
445   Backwards compatibility with old configuration file syntax
446       The  syntax  described  herein  is  new for version mtools-3.0. The old
447       line-oriented syntax is still supported. Each  line  beginning  with  a
448       single  letter  is  considered  to be a drive description using the old
449       syntax. Old style and new style drive sections may be mixed within  the
450       same configuration file, in order to make upgrading easier. Support for
451       the old syntax will be phased out eventually, and in order to  discour‐
452       age its use, I purposefully omit its description here.
453

See also

455       mtools
456
457
458
459MTOOLS                              03Nov09                        mtools.1(3)
Impressum