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
26 `/etc/default/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
66 rejected 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
98 instructs 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
145 `giant floppy disks' which are unpartitioned, OS/2 and Windows
146 NT treat them like hard disks, i.e. partitioned devices. The
147 partition flag is also useful DOSEMU hdimages. It is not recom‐
148 mended for hard disks for which direct access to partitions is
149 available 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
164 information on the command line. See section mformat, for
165 details.
166 filtering
168 On some Unixes there are device nodes which only support one
169 physical geometry. For instance, you might need a different node
170 to access a disk as high density or as low density. The geometry
171 is compared to the actual geometry stored on the boot sector to
172 make sure that this device node is able to correctly read the
173 disk. If the geometry doesn't match, this drive entry fails, and
174 the next drive entry bearing the same drive letter is tried. See
175 section multiple descriptions, for more details on supplying
176 several descriptions for one drive letter.
177 If no geometry information is supplied in the configuration
179 file, all disks are accepted. On Linux (and on SPARC) there
180 exist device nodes with configurable geometry (`/dev/fd0',
181 `/dev/fd1' etc), and thus filtering is not needed (and ignored)
182 for disk drives. (Mtools still does do filtering on plain files
183 (disk images) in Linux: this is mainly intended for test pur‐
184 poses, as I don't have access to a Unix which would actually
185 need filtering).
186 If you do not need filtering, but want still a default geometry
188 for mformatting, you may switch off filtering using the mfor‐
189 mat_only flag.
190 If you want filtering, you should supply the filter flag. If
192 you supply a geometry, you must supply one of both flags.
193 initial geometry
195 On devices that support it (usually floppy devices), the geome‐
196 try information is also used to set the initial geometry. This
197 initial geometry is applied while reading the boot sector, which
198 contains the real geometry. If no geometry information is sup‐
199 plied in the configuration file, or if the mformat_only flag is
200 supplied, no initial configuration is done.
201 On Linux, initial geometry is not really needed, as the config‐
203 urable devices are able to auto-detect the disk type accurately
204 enough (for most common formats) to read the boot sector.
205 Wrong geometry information may lead to very bizarre errors. That's why
207 I strongly recommend that you add the mformat_only flag to your drive
208 description, unless you really need filtering or initial geometry.
209 The following geometry related variables are available:
211 cylinders
213 tracks The number of cylinders. (cylinders is the preferred form,
214 tracks is considered obsolete)
215 heads The number of heads (sides).
217 sectors
219 The number of sectors per track.
220 Example: the following drive section describes a 1.44M drive:
222 drive a:
224 file="/dev/fd0H1440"
225 fat_bits=12
226 cylinders=80 heads=2 sectors=18
227 mformat_only
228 The following shorthand geometry descriptions are available:
232 1.44m high density 3 1/2 disk. Equivalent to: fat_bits=12 cylinders=80
234 heads=2 sectors=18
235 1.2m high density 5 1/4 disk. Equivalent to: fat_bits=12 cylinders=80
237 heads=2 sectors=15
238 720k double density 3 1/2 disk. Equivalent to: fat_bits=12 cylin‐
240 ders=80 heads=2 sectors=9
241 360k double density 5 1/4 disk. Equivalent to: fat_bits=12 cylin‐
243 ders=40 heads=2 sectors=9
244 The shorthand format descriptions may be amended. For example, 360k
246 sectors=8 describes a 320k disk and is equivalent to: fat_bits=12
247 cylinders=40 heads=2 sectors=8
248 Open Flags
250 Moreover, the following flags are available:
251 sync All i/o operations are done synchronously
253 nodelay
255 The device or file is opened with the O_NDELAY flag. This is
256 needed on some non-Linux architectures.
257 exclusive
259 The device or file is opened with the O_EXCL flag. On Linux,
260 this ensures exclusive access to the floppy drive. On most other
261 architectures, and for plain files it has no effect at all.
262 General Purpose Drive Variables
264 The following general purpose drive variables are available. Depending
265 to their type, these variables can be set to a string (precmd) or an
266 integer (all others)
267 fat_bits
269 The number of FAT bits. This may be 12 or 16. This is very
270 rarely needed, as it can almost always be deduced from informa‐
271 tion in the boot sector. On the contrary, describing the number
272 of fat bits may actually be harmful if you get it wrong. You
273 should only use it if mtools gets the auto-detected number of
274 fat bits wrong, or if you want to mformat a disk with a weird
275 number of fat bits.
276 codepage
278 Describes the DOS code page used for short filenames. This is a
279 number between 1 and 999. By default, code page 850 is used. The
280 reason for this is because this code page contains most of the
281 characters that are also available in ISO-Latin-1. You may also
282 specify a global code page for all drives by using the global
283 default_codepage parameter (outside of any drive description).
284 This parameters exists starting at version 4.0.0
285 precmd
287 On some variants of Solaris, it is necessary to call 'volcheck
288 -v' before opening a floppy device, in order for the system to
289 notice that there is indeed a disk in the drive.
290 precmd="volcheck -v" in the drive clause establishes the desired
291 behavior.
292 blocksize
294 This parameter represents a default block size to be always used
295 on this device. All I/O is done with multiples of this block
296 size, independently of the sector size registered in the file
297 system's boot sector. This is useful for character devices
298 whose sector size is not 512, such as for example CD-ROM drives
299 on Solaris.
300 Only the file variable is mandatory. The other parameters may be left
302 out. In that case a default value or an auto-detected value is used.
303 General Purpose Drive Flags
305 A flag can either be set to 1 (enabled) or 0 (disabled). If the value
306 is omitted, it is enabled. For example, scsi is equivalent to scsi=1
307 nolock
309 Instruct mtools to not use locking on this drive. This is
310 needed on systems with buggy locking semantics. However,
311 enabling this makes operation less safe in cases where several
312 users may access the same drive at the same time.
313 scsi When set to 1, this option tells mtools to use raw SCSI I/O
315 instead of the standard read/write calls to access the device.
316 Currently, this is supported on HP-UX, Solaris and SunOS. This
317 is needed because on some architectures, such as SunOS or
318 Solaris, PC media can't be accessed using the read and write
319 system calls, because the OS expects them to contain a Sun spe‐
320 cific "disk label".
321 As raw SCSI access always uses the whole device, you need to
323 specify the "partition" flag in addition
324 On some architectures, such as Solaris, mtools needs root privi‐
326 leges to be able to use the scsi option. Thus mtools should be
327 installed setuid root on Solaris if you want to access Zip/Jaz
328 drives. Thus, if the scsi flag is given, privileged is automat‐
329 ically implied, unless explicitly disabled by privileged=0
330 Mtools uses its root privileges to open the device, and to issue
332 the actual SCSI I/O calls. Moreover, root privileges are only
333 used for drives described in a system-wide configuration file
334 such as `/etc/mtools.conf', and not for those described in
335 `~/.mtoolsrc' or `$MTOOLSRC'.
336 privileged
338 When set to 1, this instructs mtools to use its setuid and set‐
339 gid privileges for opening the given drive. This option is only
340 valid for drives described in the system-wide configuration
341 files (such as `/etc/mtools.conf', not `~/.mtoolsrc' or `$MTOOL‐
342 SRC'). Obviously, this option is also a no op if mtools is not
343 installed setuid or setgid. This option is implied by 'scsi=1',
344 but again only for drives defined in system-wide configuration
345 files. Privileged may also be set explicitly to 0, in order to
346 tell mtools not to use its privileges for a given drive even if
347 scsi=1 is set.
348 Mtools only needs to be installed setuid if you use the privi‐
350 leged or scsi drive variables. If you do not use these options,
351 mtools works perfectly well even when not installed setuid root.
352 vold
354 Instructs mtools to interpret the device name as a vold identi‐
356 fier rather than as a filename. The vold identifier is trans‐
357 lated into a real filename using the media_findname() and
358 media_oldaliases() functions of the volmgt library. This flag
359 is only available if you configured mtools with the --enable-
360 new-vold option before compilation.
361 swap
363 Consider the media as a word-swapped Atari disk.
365 use_xdf
367 If this is set to a non-zero value, mtools also tries to access
368 this disk as an XDF disk. XDF is a high capacity format used by
369 OS/2. This is off by default. See section XDF, for more details.
370 mformat_only
372 Tells mtools to use the geometry for this drive only for mfor‐
373 matting and not for filtering.
374 filter
376 Tells mtools to use the geometry for this drive both for mfor‐
377 matting and filtering.
378 remote
380 Tells mtools to connect to floppyd (see section floppyd).
381 Supplying multiple descriptions for a drive
383 It is possible to supply multiple descriptions for a drive. In that
384 case, the descriptions are tried in order until one is found that fits.
385 Descriptions may fail for several reasons:
386 1. because the geometry is not appropriate,
388 2. because there is no disk in the drive,
390 3. or because of other problems.
392 Multiple definitions are useful when using physical devices which are
394 only able to support one single disk geometry. Example:
395 drive a: file="/dev/fd0H1440" 1.44m
397 drive a: file="/dev/fd0H720" 720k
398 This instructs mtools to use /dev/fd0H1440 for 1.44m (high density)
402 disks and /dev/fd0H720 for 720k (double density) disks. On Linux, this
403 feature is not really needed, as the /dev/fd0 device is able to handle
404 any geometry.
405 You may also use multiple drive descriptions to access both of your
407 physical drives through one drive letter:
408 drive z: file="/dev/fd0"
410 drive z: file="/dev/fd1"
411 With this description, mdir z: accesses your first physical drive if it
415 contains a disk. If the first drive doesn't contain a disk, mtools
416 checks the second drive.
417 When using multiple configuration files, drive descriptions in the
419 files parsed last override descriptions for the same drive in earlier
420 files. In order to avoid this, use the drive+ or +drive keywords
421 instead of drive. The first adds a description to the end of the list
422 (i.e. it will be tried last), and the first adds it to the start of the
423 list.
424 Location of configuration files and parsing order
426 The configuration files are parsed in the following order:
427 1. compiled-in defaults
429 2. `/etc/mtools.conf'
431 3. `~/.mtoolsrc'.
433 4. `$MTOOLSRC' (file pointed by the MTOOLSRC environmental vari‐
435 able)
436 Options described in the later files override those described in the
438 earlier files. Drives defined in earlier files persist if they are not
439 overridden in the later files. For instance, drives A and B may be
440 defined in `/etc/mtools.conf' and drives C and D may be defined in
441 `~/.mtoolsrc' However, if `~/.mtoolsrc' also defines drive A, this new
442 description would override the description of drive A in
443 `/etc/mtools.conf' instead of adding to it. If you want to add a new
444 description to a drive already described in an earlier file, you need
445 to use either the +drive or drive+ keyword.
446 Backwards compatibility with old configuration file syntax
448 The syntax described herein is new for version mtools-3.0. The old
449 line-oriented syntax is still supported. Each line beginning with a
450 single letter is considered to be a drive description using the old
451 syntax. Old style and new style drive sections may be mixed within the
452 same configuration file, in order to make upgrading easier. Support for
453 the old syntax will be phased out eventually, and in order to discour‐
454 age its use, I purposefully omit its description here.
455
457 mtools
458MTOOLS 22Mar20 mtools(5)