1mtools(5) MTOOLS mtools(5)
2
6 mtools.conf - mtools configuration files
7
11 This manual page 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 * Global configuration flags and variables
18 * Per drive flags and variables
20 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 On some systems, the system-wide configuration file is called `/etc/de‐
26 fault/mtools.conf' instead.
27 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 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 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 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 Global variables
53 Global flags may be set to 1 or to 0.
54 The following global flags are recognized:
56 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 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 re‐
66 jected if this option is not set.
67 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 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 long names, such as FreeDOS.
79 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 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 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 MTOOLS_LOCK_TIMEOUT
94 How long, in seconds, to wait for a locked device to become
95 free. Defaults to 30.
96 Example: Inserting the following line into your configuration file in‐
98 structs mtools to skip the sanity checks:
99 MTOOLS_SKIP_CHECK=1
101 Global variables may also be set via the environment:
105 export MTOOLS_SKIP_CHECK=1
107 Global string variables may be set to any value:
111 MTOOLS_DATE_STRING
113 The format used for printing dates of files. By default, is dd-
114 mm-yyyy.
115 Per drive flags and variables
117 General information
118 Per drive flags and values may be described in a drive section. A drive
119 section starts with drive "driveletter" :
120 Then follow variable-value pairs and flags.
122 This is a sample drive description:
124 drive a:
126 file="/dev/fd0" use_xdf=1
127 Location information
131 For each drive, you need to describe where its data is physically
132 stored (image file, physical device, partition, offset).
133 file The name of the file or device holding the disk image. This is
135 mandatory. The file name should be enclosed in quotes.
136 partition
138 Tells mtools to treat the drive as a partitioned device, and to
139 use the given partition. Only primary partitions are accessible
140 using this method, and they are numbered from 1 to 4. For logi‐
141 cal partitions, use the more general offset variable. The parti‐
142 tion variable is intended for removable media such as Syquest
143 disks, ZIP drives, and magneto-optical disks. Although tradi‐
144 tional DOS sees Syquest disks and magneto-optical disks as `gi‐
145 ant floppy disks' which are unpartitioned, OS/2 and Windows NT
146 treat them like hard disks, i.e. partitioned devices. The parti‐
147 tion flag is also useful DOSEMU hdimages. It is not recommended
148 for hard disks for which direct access to partitions is avail‐
149 able through mounting.
150 offset
152 Describes where in the file the MS-DOS file system starts. This
153 is useful for logical partitions in DOSEMU hdimages, and for
154 ATARI ram disks. By default, this is zero, meaning that the file
155 system starts right at the beginning of the device or file.
156 Disk Geometry Configuration
158 Geometry information describes the physical characteristics about the
159 disk. Its has three purposes:
160 formatting
162 The geometry information is written into the boot sector of the
163 newly made disk. However, you may also describe the geometry in‐
164 formation on the command line. See section mformat, for details.
165 filtering
167 On some Unixes there are device nodes which only support one
168 physical geometry. For instance, you might need a different node
169 to access a disk as high density or as low density. The geometry
170 is compared to the actual geometry stored on the boot sector to
171 make sure that this device node is able to correctly read the
172 disk. If the geometry doesn't match, this drive entry fails, and
173 the next drive entry bearing the same drive letter is tried. See
174 section multiple descriptions, for more details on supplying
175 several descriptions for one drive letter.
176 If no geometry information is supplied in the configuration
178 file, all disks are accepted. On Linux (and on SPARC) there ex‐
179 ist device nodes with configurable geometry (`/dev/fd0',
180 `/dev/fd1' etc), and thus filtering is not needed (and ignored)
181 for disk drives. (Mtools still does do filtering on plain files
182 (disk images) in Linux: this is mainly intended for test pur‐
183 poses, as I don't have access to a Unix which would actually
184 need filtering).
185 If you do not need filtering, but want still a default geometry
187 for mformatting, you may switch off filtering using the mfor‐
188 mat_only flag.
189 If you want filtering, you should supply the filter flag. If
191 you supply a geometry, you must supply one of both flags.
192 initial geometry
194 On devices that support it (usually floppy devices), the geome‐
195 try information is also used to set the initial geometry. This
196 initial geometry is applied while reading the boot sector, which
197 contains the real geometry. If no geometry information is sup‐
198 plied in the configuration file, or if the mformat_only flag is
199 supplied, no initial configuration is done.
200 On Linux, initial geometry is not really needed, as the config‐
202 urable devices are able to auto-detect the disk type accurately
203 enough (for most common formats) to read the boot sector.
204 Wrong geometry information may lead to very bizarre errors. That's why
206 I strongly recommend that you add the mformat_only flag to your drive
207 description, unless you really need filtering or initial geometry.
208 The following geometry related variables are available:
210 cylinders
212 tracks The number of cylinders. (cylinders is the preferred form,
213 tracks is considered obsolete)
214 heads The number of heads (sides).
216 sectors
218 The number of sectors per track.
219 Example: the following drive section describes a 1.44M drive:
221 drive a:
223 file="/dev/fd0H1440"
224 fat_bits=12
225 cylinders=80 heads=2 sectors=18
226 mformat_only
227 The following shorthand geometry descriptions are available:
231 1.44m high density 3 1/2 disk. Equivalent to: fat_bits=12 cylinders=80
233 heads=2 sectors=18
234 1.2m high density 5 1/4 disk. Equivalent to: fat_bits=12 cylinders=80
236 heads=2 sectors=15
237 720k double density 3 1/2 disk. Equivalent to: fat_bits=12 cylin‐
239 ders=80 heads=2 sectors=9
240 360k double density 5 1/4 disk. Equivalent to: fat_bits=12 cylin‐
242 ders=40 heads=2 sectors=9
243 The shorthand format descriptions may be amended. For example, 360k
245 sectors=8 describes a 320k disk and is equivalent to: fat_bits=12
246 cylinders=40 heads=2 sectors=8
247 Open Flags
249 Moreover, the following flags are available:
250 sync All i/o operations are done synchronously
252 nodelay
254 The device or file is opened with the O_NDELAY flag. This is
255 needed on some non-Linux architectures.
256 exclusive
258 The device or file is opened with the O_EXCL flag. On Linux,
259 this ensures exclusive access to the floppy drive. On most other
260 architectures, and for plain files it has no effect at all.
261 General Purpose Drive Variables
263 The following general purpose drive variables are available. Depending
264 to their type, these variables can be set to a string (precmd, postcmd)
265 or an integer (all others)
266 fat_bits
268 The number of FAT bits. This may be 12 or 16. This is very
269 rarely needed, as it can almost always be deduced from informa‐
270 tion in the boot sector. On the contrary, describing the number
271 of fat bits may actually be harmful if you get it wrong. You
272 should only use it if mtools gets the auto-detected number of
273 fat bits wrong, or if you want to mformat a disk with a weird
274 number of fat bits.
275 codepage
277 Describes the DOS code page used for short filenames. This is a
278 number between 1 and 999. By default, code page 850 is used. The
279 reason for this is because this code page contains most of the
280 characters that are also available in ISO-Latin-1. You may also
281 specify a global code page for all drives by using the global
282 default_codepage parameter (outside of any drive description).
283 This parameters exists starting at version 4.0.0
284 data_map
286 Remaps data from image file. This is useful for image files
287 which might need additional zero-filled sectors to be inserted.
288 Such is the case for instance for IBM 3174 floppy images. These
289 images represent floppy disks with fewer sectors on their first
290 cylinder. These missing sectors are not stored in the image, but
291 are still counted in the filesystem layout. The data_map allows
292 to fake these missing sectors for the upper layers of mtools. A
293 data_map is a comma-separated sequence of source type and size.
294 Source type may be zero for zero-filled sectors created by map,
295 skip for data in raw image to be ignored (skipped), and nothing
296 for data to be used as is (copied) from the raw image. Datamap
297 is automatically complemented by an implicit last element of
298 data to be used as is from current offset to end of file. Each
299 size is a number followed by a unit: s for a 512 byte sector, K
300 for Kbytes, M for megabytes, G for gigabytes, and nothing for
301 single bytes.
302 Example:
304 data_map=1s,zero31s,28s,skip1s would be a map for use with IBM
306 3174 floppy images. First sector (1s, boot sector) is used as
307 is. Then follow 31 fake zero-filled sectors (zero31s), then the
308 next 28 sectors from image (28s) are used as is (they contain
309 FAT and root directory), then one sector from image is skipped
310 (skip1s), and finally the rest of image is used as is (implicit)
311 precmd
313 Executes the given command before opening the device. On some
314 variants of Solaris, it is necessary to call 'volcheck -v' be‐
315 fore opening a floppy device, in order for the system to notice
316 that there is indeed a disk in the drive. precmd="volcheck -v"
317 in the drive clause establishes the desired behavior.
318 postcmd
320 Executes the given command after closing the device. May be
321 useful if mtools shares the image file with some other applica‐
322 tion, in order to release the image file to that application.
323 blocksize
325 This parameter represents a default block size to be always used
326 on this device. All I/O is done with multiples of this block
327 size, independently of the sector size registered in the file
328 system's boot sector. This is useful for character devices
329 whose sector size is not 512, such as for example CD-ROM drives
330 on Solaris.
331 Only the file variable is mandatory. The other parameters may be left
333 out. In that case a default value or an auto-detected value is used.
334 General Purpose Drive Flags
336 A flag can either be set to 1 (enabled) or 0 (disabled). If the value
337 is omitted, it is enabled. For example, scsi is equivalent to scsi=1
338 nolock
340 Instruct mtools to not use locking on this drive. This is
341 needed on systems with buggy locking semantics. However, en‐
342 abling this makes operation less safe in cases where several
343 users may access the same drive at the same time.
344 scsi When set to 1, this option tells mtools to use raw SCSI I/O in‐
346 stead of the standard read/write calls to access the device.
347 Currently, this is supported on HP-UX, Solaris and SunOS. This
348 is needed because on some architectures, such as SunOS or So‐
349 laris, PC media can't be accessed using the read and write sys‐
350 tem calls, because the OS expects them to contain a Sun specific
351 "disk label".
352 As raw SCSI access always uses the whole device, you need to
354 specify the "partition" flag in addition
355 On some architectures, such as Solaris, mtools needs root privi‐
357 leges to be able to use the scsi option. Thus mtools should be
358 installed setuid root on Solaris if you want to access Zip/Jaz
359 drives. Thus, if the scsi flag is given, privileged is automat‐
360 ically implied, unless explicitly disabled by privileged=0
361 Mtools uses its root privileges to open the device, and to issue
363 the actual SCSI I/O calls. Moreover, root privileges are only
364 used for drives described in a system-wide configuration file
365 such as `/etc/mtools.conf', and not for those described in
366 `~/.mtoolsrc' or `$MTOOLSRC'.
367 privileged
369 When set to 1, this instructs mtools to use its setuid and set‐
370 gid privileges for opening the given drive. This option is only
371 valid for drives described in the system-wide configuration
372 files (such as `/etc/mtools.conf', not `~/.mtoolsrc' or `$MTOOL‐
373 SRC'). Obviously, this option is also a no op if mtools is not
374 installed setuid or setgid. This option is implied by 'scsi=1',
375 but again only for drives defined in system-wide configuration
376 files. Privileged may also be set explicitly to 0, in order to
377 tell mtools not to use its privileges for a given drive even if
378 scsi=1 is set.
379 Mtools only needs to be installed setuid if you use the privi‐
381 leged or scsi drive variables. If you do not use these options,
382 mtools works perfectly well even when not installed setuid root.
383 vold
385 Instructs mtools to interpret the device name as a vold identi‐
387 fier rather than as a filename. The vold identifier is trans‐
388 lated into a real filename using the media_findname() and me‐
389 dia_oldaliases() functions of the volmgt library. This flag is
390 only available if you configured mtools with the --enable-new-
391 vold option before compilation.
392 swap
394 Consider the media as a word-swapped Atari disk.
396 use_xdf
398 If this is set to a non-zero value, mtools also tries to access
399 this disk as an XDF disk. XDF is a high capacity format used by
400 OS/2. This is off by default. See section XDF, for more details.
401 mformat_only
403 Tells mtools to use the geometry for this drive only for mfor‐
404 matting and not for filtering.
405 filter
407 Tells mtools to use the geometry for this drive both for mfor‐
408 matting and filtering.
409 remote
411 Tells mtools to connect to floppyd (see section floppyd).
412 Supplying multiple descriptions for a drive
414 It is possible to supply multiple descriptions for a drive. In that
415 case, the descriptions are tried in order until one is found that fits.
416 Descriptions may fail for several reasons:
417 1. because the geometry is not appropriate,
419 2. because there is no disk in the drive,
421 3. or because of other problems.
423 Multiple definitions are useful when using physical devices which are
425 only able to support one single disk geometry. Example:
426 drive a: file="/dev/fd0H1440" 1.44m
428 drive a: file="/dev/fd0H720" 720k
429 This instructs mtools to use /dev/fd0H1440 for 1.44m (high density)
433 disks and /dev/fd0H720 for 720k (double density) disks. On Linux, this
434 feature is not really needed, as the /dev/fd0 device is able to handle
435 any geometry.
436 You may also use multiple drive descriptions to access both of your
438 physical drives through one drive letter:
439 drive z: file="/dev/fd0"
441 drive z: file="/dev/fd1"
442 With this description, mdir z: accesses your first physical drive if it
446 contains a disk. If the first drive doesn't contain a disk, mtools
447 checks the second drive.
448 When using multiple configuration files, drive descriptions in the
450 files parsed last override descriptions for the same drive in earlier
451 files. In order to avoid this, use the drive+ or +drive keywords in‐
452 stead of drive. The first adds a description to the end of the list
453 (i.e. it will be tried last), and the first adds it to the start of the
454 list.
455 Location of configuration files and parsing order
457 The configuration files are parsed in the following order:
458 1. compiled-in defaults
460 2. `/etc/mtools.conf'
462 3. `~/.mtoolsrc'.
464 4. `$MTOOLSRC' (file pointed by the MTOOLSRC environmental vari‐
466 able)
467 Options described in the later files override those described in the
469 earlier files. Drives defined in earlier files persist if they are not
470 overridden in the later files. For instance, drives A and B may be de‐
471 fined in `/etc/mtools.conf' and drives C and D may be defined in
472 `~/.mtoolsrc' However, if `~/.mtoolsrc' also defines drive A, this new
473 description would override the description of drive A in
474 `/etc/mtools.conf' instead of adding to it. If you want to add a new
475 description to a drive already described in an earlier file, you need
476 to use either the +drive or drive+ keyword.
477 Backwards compatibility with old configuration file syntax
479 The syntax described herein is new for version mtools-3.0. The old
480 line-oriented syntax is still supported. Each line beginning with a
481 single letter is considered to be a drive description using the old
482 syntax. Old style and new style drive sections may be mixed within the
483 same configuration file, in order to make upgrading easier. Support for
484 the old syntax will be phased out eventually, and in order to discour‐
485 age its use, I purposefully omit its description here.
486
488 mtools
489MTOOLS 21Mar23 mtools(5)