1mtools.1(3) MTOOLS mtools.1(3)
2
3
4
6 mtools.conf - mtools configuration files
7
8
9
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
455 mtools
456
457
458
459MTOOLS 03Nov09 mtools.1(3)