Skip to content

Latest commit

 

History

History
1197 lines (868 loc) · 50.9 KB

Guide:Managing-image-files-in-DOSBox‐X.asciidoc

File metadata and controls

1197 lines (868 loc) · 50.9 KB
Raw

Managing images files

Table of Contents

Overview

DOSBox-X supports three categories of image files;

  • Diskette (floppy disk) images

  • Harddisk images

  • CD-ROM or DVD images

Tip
 Whenever this guide mentions mounting an image file, such as disk.ima, hdd.img or cdrom.iso, those are files on your host filesystem. And they may optionally be prefixed with the host path to the file. e.g. disk.ima may become "C:\Users\John Doe\dosroot\disk.ima". Also note that if there are any spaces in the host path or filename, you need to enclose it with quotes.

Listing current mounts

The currently active mounts can be viewed by running the IMGMOUNT or MOUNT commands without arguments. The output of the two commands differs somewhat.

  • MOUNT will show all active mounts

  • IMGMOUNT will show mounted images, and the device numbers (drive numbers) in use

You can also see the currently mounted drive numbers from the "DOS" menu with the "Show mounted drive numbers" option, and the mounted harddisks or CD-ROM’s with the "Show IDE disk or CD status" option. Note that both of these options will only show image mounts, not folder mounts.

Diskette (floppy disk) images

DOSBox-X supports mounting diskette (aka Floppy) images in the following formats:

  • RAW MFM sector image format (typically ending in .ima or .img)

  • IBM XDF (ending in .xdf)

  • Microsoft DMF (typically ending in .dmf)

  • NEC PC-98 diskette images (typically ending in .fdd, .fdi, .nfd or .d88)

Note
 The .IMG extension is also used for harddisk images, so there can be some confusion. Files with the extension .IMA are automatically treated as diskette images.
Note
 There is no support for any type of copy-protected diskettes. Any programs on copy-protected diskettes need to be "cracked" to remove the copy protection before they can be used by DOSBox-X.

Some examples of diskette image files that DOSBox-X does not support:

Note
 While DOSBox-X does not support mounting or booting from diskette images in IBM DSKF format, it is possible to use the LOADDSKF.EXE program in DOSBox-X to convert an IBM DSKF file to a regular RAW MFM Disk format.

Creating diskette images

Note
 In addition to the below DOSBox-X command line utility, it is possible to create diskette images at any time from the DOSBox-X menu. Go to the "DOS" menu, and select "Create blank disk image…​". This option allows most common floppy disk types to be created, for less common types you need to use the command line utility.

DOSBox-X has a built-in IMGMAKE command with which you can create FAT12 formatted diskette images in RAW MFM sector image format from the DOSBox-X command prompt.

Example:

IMGMAKE disk.ima -t fd

This is equivalent to

IMGMAKE disk.ima -t fd_1440

The above command will create a 1.44MB formatted disk image named disk.ima. The diskette image will appear to have been formatted by MS-DOS 5.0.

The image filename for this command is optional, and if you do not specify a filename, then the name IMGMAKE.IMG will be used, such as the following:

IMGMAKE -t fd
Note
 The filename for the disk image is not limited to the DOS 8.3 filename length, but rather by your host filesystem. In DOSBox-X you can also specify the -force parameter to overwrite the file if it already exists.

You can optionally create a diskette image that is not formatted with:

IMGMAKE disk.ima -t fd -nofs
Note
 DOSBox-X does not supply a FORMAT command, so creating diskette images that are not formatted is typically not recommended.
Tip
 DOSBox-X will automatically assume it is a diskette image if the filename extension is .IMA, or if you’re mounting on the emulated A: or B: drive. If this is not the case, you can force DOSBox-X to treat an image as a diskette type with the -t floppy parameter.

Supported diskette sizes options:

Disk type Sides Tracks per Side Sectors per Track Capacity IMGMAKE option

5.25" SSDD

1

40

8

160KB

-t fd_160

5.25" SSDD

1

40

9

180KB

-t fd_180

5.25" SSDD

1

40

10

200KB

-t fd_200

5.25" DSDD

2

40

8

320KB

-t fd_320

5.25" DSDD

2

40

9

360KB

-t fd_360

5.25" DSDD

2

40

10

400KB

-t fd_400

5.25" HD

2

80

15

1200KB (1.2MB)

-t fd_1200

3.5" DSDD (2DD)

2

80

9

720KB

-t fd_720

3.5" HD

2

80

18

1440KB (1.44MB)

-t fd_1440 or -t fd

3.5" ED

2

80

36

2880KB (2.88MB)

-t fd_2880
Note
 Common PC disk types in bold. The 8-sector formats should be avoided unless you need backward compatibility with DOS 1.x. The 10-sector disks were used by the DEC Rainbow 100, and should likewise be avoided for compatibility reasons.

Mounting diskette images

Mounting a diskette image in DOSBox-X is typically as simple as

imgmount a disk.ima

This is equivalent to

imgmount A: disk.ima
imgmount A: disk.ima -t floppy

If you do not specify an image filename, then the name IMGMAKE.IMG will be used, such as the following:

imgmount a
Note
 The -t floppy parameter is only needed with DOSBox-X when the extension is not .IMA, and you’re wanting to mount a diskette image on drives greater than B:.

A diskette image that is not formatted, or has an unsupported filesystem can be attached as follows:

imgmount 0 disk.ima

This is equivalent to

imgmount 0 disk.ima -fs none

0 represents drive A: and 1 represents drive B:, but due to the use of drive numbers they cannot be directly accessed from the DOSBox-X integrated DOS. Note that when using drive numbers like 0 and 1 to mount a diskette image the -fs none flag is automatically assumed in DOSBox-X. For vanilla DOSBox, or other forks, the -fs none flag will be required.

Mounting an empty floppy disk drive

Starting with DOSBox-X 2024.03.01 it is possible to mount an empty floppy drive. This is really only if you intend to boot a guest OS, and want to be able to insert a diskette in the drive after booting using the DOSBox-X drop-down menu’s.

When no -size option is specified, a 3.5" 1.44MB drive type is emulated.

imgmount 0 empty -fs none -t floppy

To emulate an empty 5.25" 1.2MB drive as the first floppy drive:

imgmount 0 empty -fs none -t floppy -size 512,15,2,80
Drive type -size option Notes

SS/DD 5.25" 160KB

512,8,1,40

Only really for DOS 1.x backward compatibility

SS/DD 5.25" 180KB

512,9,1,40

DS/DD 5.25" 320KB

512,8,2,40

Only really for DOS 1.x backward compatibility

DS/DD 5.25" 360KB

512,9,2,40

Can also R/W 5.25" SS/DD media

DS/HD 5.25" 1.2MB

512,15,2,80

Can also R/W all other 5.25" media

DS/DD 3.5" 720KB

512,9,2,80

Can also R/W 3.5" SS/DD media

DS/HD 3.5" 1.44MB

512,18,2,80

Can also R/W 3.5" SS/DD and DS/DD media

DS/ED 3.5" 2.88MB

512,36,2,80

Can also R/W all other 3.5" media
Note
 The two most common and useful drive types to emulate are the 5.25" 1.2MB and the 3.5" 1.44MB varieties as they can each read and write lower capacity variants of the same physical media size.
Note
 The current DOSBox-X release seems to have a bug where Win9x will only see the first floppy drive.

Mounting from the Drive menu

The advantage of this option is, that you don’t need to mount all the disks before starting your program or game, but you can mount disk images when needed.

To access it, DOSBox-X needs to be in windowed mode, there is a menu bar with a "Drive" drop-down. Select a drive letter, and you will see various mount options.

The only mount option that can be used for image files is the "Mount disk image" option. All the other mount options are host folder mounts.

Select the Drive menu, and the "A" or "B" drive and "Mount disk image". Now a file browser will allow you to select an image file.

Limitations of this option, compared to the DOSBox-X command line:

  • No support for marking a diskette image as read-only.

  • No ability to specify multiple diskette images for use with the swap-disk functionality.

Mounting multiple diskette images

Some DOS programs or games came on multiple diskettes. For this purpose it is possible to mount multiple diskette images on one drive letter and swap between them. e.g.

imgmount a disk1.ima disk2.ima disk3.ima

In this example disk1.ima will be immediately usable on drive A: but disk2.ima will require a disk-swap action.

Disk-swap can be done using either a hot-key combination, or using the menu bar. The hot-key for Windows is F11+CTRL+D and for other platforms F12+CTRL+D. Or from the menu you can select "DOS" followed by "Swap floppy". Lastly, you can use the IMGSWAP command to swap between images.

If you lose track of which disk is currently active, open the 'Drive' menu option, select the drive letter and select 'Drive Information'. This information can also be retrieved from the IMGSWAP command.

Write protecting diskette images

By default, diskette images are mounted read-write. It is possible to make a diskette image read-only (write protected) either by using the -ro option, or by attaching the : prefix to the filename. e.g.

imgmount a disk.ima -ro

This is equivalent to:

imgmount a :disk.ima

They can also be used when mounting multiple diskette images. If you use the -ro option, then all images specified in the command will become read-only. On the other hand, if you wish to make individual images read-only (instead of all of them), then you can attach the : prefix to these images, like this:

imgmount a :disk1.ima :disk2.ima :disk3.ima userdisk.ima

In the above example, the first 3 disks are read-only, but the last one is read-write.

Unmounting diskette images

Diskette images can be unmounted using the -u flag. e.g.

imgmount a -u

You can also unmount using the MOUNT command.

mount a -u

It is also possible to unmount the currently mounted image (if any), and mount a new image in one step.

imgmount a disk2.ima -u

This will cause the currently mounted disk image (if any) to be unmounted, and disk2.ima to be mounted instead.

Alternatively you can unmount a diskette from the DOSBox-X menu bar (when running in Windowed mode) by selecting "Drive", followed by the drive letter and "Unmount".

Boot from a diskette image

You can either mount a disk image first and then boot from it:

imgmount a dos.ima
boot a:
Note
 DOSBox-X supports the -L parameter for the BOOT command for backward compatibility with vanilla DOSBox, or other forks, but the parameter is not required with DOSBox-X to boot from a drive letter.

Or you can boot directly from a disk as such:

boot dos.ima
Tip
 Multiple image files can be specified with either the IMGMOUNT or BOOT commands, in case you have a multi-disk install program. Image files can be made read-only by prefixing the filename with a column character (:).
Caution
 DOSBox-X will attempt to boot from a diskette, even if it is not bootable. This is needed to support early PC-Booter games.
Tip
 Once a disk image is mounted, you can alternatively also boot from a disk image by selecting "Drive" from the menu bar, followed by the drive letter and "Boot from drive". You can also mount and boot a disk image in one step by selecting "Boot from disk image" from this submenu.

Using diskette images in Linux

Warning
 You should never mount a disk image simultaneously in both DOSBox-X and in Linux, as that can cause corruption of files or the filesystem on the diskette image.

Gnome Disk Image Mounter

When using the Gnome desktop environment, you can open .IMG disks with the "Disk Image Mounter". Simply right-click on the file, and select 'Open with Disk Image Mounter' and the file will be mounted READ-ONLY in the Gnome file manager.

The first time you want to open .IMA files, you need to right-click and choose "Open With Other Application", and then click on "View All Applications" and choose "Disk Image Mounter" from the list. The next time you want to open a .IMA file, the option will be available directly from the right-click menu.

Disks can be unmounted from the Gnome file manager by clicking the unmount button next to the volume name.

Disk images can also be mounted READ-WRITE from the Linux Terminal using:

gnome-disk-image-mounter -w disk.ima

Or if you run gnome-disk-image-mounter without arguments, it will ask you which disk image to mount, and give you the ability to mount it READ-WRITE.

Mounting a diskette image from the Linux shell

The more traditional Linux method of mounting diskette image files from a Linux terminal. This method requires sudo access.

sudo mount -o loop,uid=$UID disk.ima /mnt

The above command will cause disk.ima to be mounted under /mnt on the host.

GNU mtools

GNU mtools is an optional package you can install to interact with DOS disks or disk images. It provides various commands which can be used to interact with DOS diskette images without having to mount them.

A subset of commands provided by mtools:

Command DOS equivalent Note

mattrib

ATTRIB

View and change file attributes

mcopy

COPY / XCOPY

Copy files

mdel

DEL / ERASE

Delete files

mdeltree

DELTREE

Delete directory tree

mdir

DIR

List directory contents

mdu

-

Disk Usage

minfo

-

Info about the disk

mlabel

LABEL

Label disk

mmd

MD / MKDIR

Make directory

mmove

MOVE

Move file or directory

mrd

RD / RMDIR

Remove directory

mren

REN / RENAME

Rename file or directory

mtype

TYPE

Show contents of a file
List contents of a diskette image

This will list the contents of the root directory of the diskette image, similar to the DOS DIR command.

mdir -i disk.ima

Assuming the diskette image has a directory named GAMES, the contents can be listed as

mdir -i disk.ima ::games
Copy file into a diskette image

This command will copy the file hello.txt into the root directory of the disk image.

mcopy -i disk.ima hello.txt ::

This command will copy the file hello.txt into the GAMES directory of the disk image.

mcopy -i disk.ima hello.txt ::games
Copy file(s) out of a diskette image

This command will copy the file hello.txt out of the root of the diskette image, to the current directory (.)

mcopy -i disk.ima ::hello.txt .

Or if you want to copy all files, including sub-directories, from the diskette image to the directory tmp

mkdir tmp
mcopy -s -i disk.ima :: tmp

Using diskette images in Windows

Warning
 You should never mount a disk image simultaneously in both DOSBox-X and in Windows, as that can cause corruption of files or the filesystem on the diskette image.
Note
 Windows 8 and newer has integrated support for mounting image files, and will offer the "Mount" option when you right-click a .IMG file. Unfortunately this support is incompatible with the typical RAW MFM image files used by DOSBox-X, and the mount will fail.

Several 3rd party tools are available which can open the diskette image files:

Using diskette images in macOS

You can mount RAW MFM image files with the extension .IMG in macOS from the Finder by double-clicking on it. You can unmount it by clicking on the "Eject" button next to it in the Finder.

It is also possible to mount the image file from the macOS Terminal using hdiutil

Harddisk images

DOSBox-X supports mounting harddisk images in the following formats:

  • RAW MFM sector image format (typically .img)

  • QCOW2 - QEMU copy-on-write v2 (.qcow2)

    • No support in DOSBox-X for QCOW2 zstd compression or encryption options

  • Virtual Hard Disk Volume (.vhd) (aka Virtual PC)

  • Bochs bximage (typically .img)

  • NEC PC-98 harddisk images (.nhd or .hdi)

Creating and accessing harddisk images is very similar to diskette images, with the exception that they also contain partitions and they may contain other filesystems.

Creating harddisk images

Note
 In addition to the below DOSBox-X command line utility, it is possible to create harddisk images at any time from the DOSBox-X menu. Go to the "DOS" menu, and select "Create blank disk image…". This option allows a few common HDD sizes to be created, for less common types you need to use the command line utility.

DOSBox-X has a built-in IMGMAKE command with which you can create partitioned and FAT formatted harddisk images in either RAW MFM sector image or VHD format from the DOSBox-X command prompt. IMGMAKE only creates a single primary DOS partition per harddisk image file.

FAT version

The IMGMAKE command supports FAT12, FAT16 and FAT32 formatted partitions, and will try to automatically decide which type to use depending on the HDD capacity and the reported DOS version:

HDD Capacity Reported DOS version < 7.1 Reported DOS version ≥ 7.1

≤ 12MB

FAT12

FAT12

> 12MB and < 512MB

FAT16

FAT16

≥ 512MB and ≤ 2GB

FAT16

FAT32

> 2GB

FAT32

FAT32

Using the -FAT option it is possible to overrule the decision process. But this can cause IMGMAKE to give errors if the partition size is not supported by the filesystem type, or can cause other problems such as performance issues or waisted disk space.

e.g., to create a 400MiB HDD image formatted as FAT32:

IMGMAKE hdd.img -t hd -size 400 -fat 32
Note
 FAT12 and FAT16 harddisk images will appear to have been partitioned and formatted by MS-DOS 5.0. FAT32 harddisk images will appear to have been partitioned and formatted by Windows 98.

Using templates

Example:

IMGMAKE hdd.img -t hd_520

This will create a 520MB partitioned and formatted harddisk image named hdd.img.

The image filename for this command is optional, and if you do not specify a filename, then the name IMGMAKE.IMG will be used, such as the following:

IMGMAKE -t hd_520
Note
 The filename in this case is not limited to the DOS 8.3 filename length, but rather by your host filesystem. In DOSBox-X you can also specify the -force parameter to overwrite the file if it already exists.

You can optionally attempt to force IMGMAKE to use a certain filesystem type with the -fat parameter.

You can optionally create a harddisk image that is not partitioned and formatted with:

IMGMAKE hdd.img -t hd_520 -nofs
Note
 DOSBox-X has no integrated FDISK and FORMAT commands, so creating harddisk images that are not partitioned and formatted is typically not recommended.

Supported harddisk sizes options using templates:

Disk type Capacity CHS IMGMAKE option Filesystem

Seagate ST225

21MB (~ 20.23MB usable)

615,4,17

-t hd_st225

FAT16

Seagate ST251

41MB (~ 40.65MB usable)

820,6,17

-t hd_st251

FAT16

241MB (~ 240.39MB usable)

489,16,63

-t hd_250

FAT16

504MB (~ 503.21MB usable)

1023,16,63

-t hd_520

FAT16

2GB (~ 1.96GB usable)

1023,64,63

-t hd_2gig

FAT16

4GB

1023,130,63

-t hd_4gig

FAT32

8GB

1023,255,63

-t hd_8gig

FAT32

Custom size

Instead of using one of the templates, you can create a custom size harddisk up to 2TB using the -size option, or up to 8GB using the -chs geometry option.

To create a partitioned and FAT16 formatted 31MB HDD image:

IMGMAKE hdd.img -t hd -size 31

The same can be accomplished with the CHS (Cylinders, Heads, Sectors) geometry:

IMGMAKE hdd.img -t hd -chs 992,2,32

The maximum allowed CHS value is 1023,255,63 which will create a 8GB HDD image.

You can optionally create a harddisk image that is not partitioned and formatted by specifying -nofs:

IMGMAKE hdd.img -t hd -size 31 -nofs
Note
 DOSBox-X has no integrated FDISK and FORMAT commands, so creating harddisk images that are not partitioned and formatted is typically not recommended.

The IMGMAKE command also has an optional ''-bat'' option for use on Windows systems.

IMGMAKE hdd.img -t hd -size 31 -nofs -bat

Will cause both a hdd.img and a hdd.bat to be generated. The BAT file will contain the imgmount command to mount the harddisk image, including geometry.

Creating harddisk images from folder mounts

Starting with DOSBox-X 2022.08.0 it is possible to convert a host folder mount to a harddisk image file.

The steps are simply to first mount a host folder, and then from the menus (when running in Windowed mode), select "Drive" > "drive letter" > "Save to disk image".

The FAT version will be automatically selected, based on the aggregate amount of files in the folder, plus (by default) 250MiB of free space. If the total does not exceed 2GiB, it will be converted to a FAT16 harddisk image file, otherwise it will become a FAT32 image instead (which will require a guest OS with FAT32 support).

The amount of free space can be adjusted in the DOSBox-X config file as such:

[sdl]
convert fat free space = 10

This will limit the free space to 10MiB. Set it to 0 for read-only (no free space) and -1 to attempt to use the actual free space on the host drive (subject to FAT filesystem limits).

Mounting harddisk images

Mounting a harddisk image in DOSBox-X is typically as simple as

imgmount c hdd.img

This is equivalent to

imgmount C: hdd.img
imgmount C: hdd.img -t hdd
imgmount C: hdd.img -t hdd -fs fat

If you do not specify an image filename, it will try to open a file named IMGMAKE.IMG, such as in this example:

imgmount c
Note
 The -t hdd option is only needed with DOSBox-X when mounting a harddisk image on the emulated A: or B: drive, as those are normally reserved for diskettes. Or when mounting a harddisk image that is not partitioned or formatted, or formatted with an unsupported filesystem in combination with the -size parameter. The -fs fat option should not be needed as the FAT12, FAT16 or FAT32 filesystem types will be automatically detected.
Note
 As of DOSBox-X 2023-10-06, you can specify a wildcard instead of a drive letter (e.g., imgmount *: hdd.img). This will cause DOSBox-X to take the next available drive letter.
Note
 If a harddisk image has either a "FAT16 LBA" or "FAT32" partition, the mount will fail unless a higher than default reported DOS version is set. Those partition types are normally restricted to, respectively, MS-DOS 7.0 (Windows 95) or MS-DOS 7.1 (Windows 95 OSR2/Windows 98) or later, and therefore DOSBox-X does not allow them to be mounted with the default DOS 5.0 version that DOSBox-X reports. You can change the reported DOS version in your DOSBox-X config file by for instance setting ver=7.1 in the [dos] section. Or alternatively from the DOSBox-X DOS prompt by typing for instance ver set 7.1.
Note
 If a harddisk image has multiple partitions, by default only the first primary partition will be mounted and accessible from the DOSBox-X integrated DOS. You can optionally mount a different partition, but only one partition at a time can be mounted and be accessible from the integrated DOS. When booting real DOS in DOSBox-X, all partitions will be accessible.
Note
 Starting with DOSBox-X 2023-05-01, if a harddisk image is 2GiB or larger, LBA size detection will be attempted. Smaller images will default to CHS detection. You can optionally add -lba or -chs to the imgmount command to force LBA or CHS detection.

A harddisk image that is partitioned, but not formatted, or has an unsupported filesystem can be mounted as follows:

imgmount 2 hdd.img

It is required to use a device number instead of a drive letter in this case. DOSBox-X automatically assumes the -fs none flag when a drive number is used, but this flag is required for vanilla DOSBox or other DOSBox forks.

Device number Controller option IDE Controller Master/Slave

2

-ide 1m

Primary

Master

3

-ide 1s

Primary

Slave

4

-ide 2m

Secondary

Master

5

-ide 2s

Secondary

Slave

A harddisk image that is not yet partitioned needs additional parameters, such as a template or the size in SHC geometry.

Using the original template it was based on:

imgmount 2 hdd.img -t hd_4gig

Or using the original SHC geometry it was based on:

imgmount 2 hdd.img -t hdd -size 512,32,2,992
Important
 The order of the geometry values for the IMGMOUNT command are reversed compared to IMGMAKE. So instead of specifying the size in CHS order, it needs to be specified in SHC (Sectors, Heads, Cylinders) order. In addition, it needs to be prefixed with the bytes-per-sector, which should always be 512 for now. So a CHS of 992,2,32 becomes -size 512,32,2,992.

Mounting from the Drive menu

To access it, DOSBox-X needs to be in windowed mode, there is a menu bar with a "Drive" drop-down. Select a drive letter, and you will see various mount options.

The only mount option that can be used for image files is the "Mount disk image" option. All the other mount options are host folder mounts.

Select the Drive menu, and for instance the "C" drive and "Mount disk image", now a file browser will allow you to select an image file.

Caution
 It is recommended to only mount harddisk images when at the integrated DOSBox-X DOS prompt. Doing so when running a program, real DOS or Win9x is strongly discouraged as it can lead to data corruption and/or crashes.

Specifying the partition to mount

If the harddisk image contains multiple partitions, by default DOSBox-X will only mount the first primary partition.

You can optionally specify the -o partidx= parameter, where you can specify the partition number you want to mount.

  • -1 means autodetect (default)

  • 0 is the 1st primary partition

  • 1 is the 2nd primary partition

  • 2 is the 3rd primary partition

  • 3 is the 4th primary partition or the Extended partition

  • 4 is the 1st logical partition

  • 5 is the 2nd logical partition

  • 6 is the 3rd logical partition

  • 7 is the 4th logical partition

e.g. to mount the 2nd primary partition:

imgmount C: hdd.img -o partidx=1
Note
 DOSBox-X only allows one partition per harddisk image to be mounted in the integrated DOS. When booting real DOS, all partitions will be available.
Note
 If the harddisk image has an Extended partition, that partition cannot be mounted, but the logical partitions it contains can.

Unmounting harddisk images

Harddisk images can be unmounted using the -u flag. e.g.

imgmount c -u

You can also unmount using the MOUNT command.

mount c -u

It is also possible to unmount the currently mounted image (if any), and mount a new image in one step.

imgmount c hdd2.img -u

This will cause the currently mounted harddisk image (if any) to be unmounted, and hdd2.img to be mounted instead.

Tip
 Alternatively you can unmount a harddisk image from the DOSBox-X menu bar by selecting "Drive", followed by the drive letter and "Unmount".
Caution
 It is recommended to only unmount harddisk images when at the integrated DOSBox-X DOS prompt. Doing so when running a program, real DOS or Win9x is strongly discouraged as it can lead to data corruption and/or crashes.

Booting from a harddisk image

First mount the harddisk image, and then boot from it as follows:

imgmount c hdd.img
boot c:
Note
 DOSBox-X supports the -L parameter for the BOOT command for backward compatibility with vanilla DOSBox, or other forks, but the parameter is not required with DOSBox-X to boot from a drive letter.
Tip
 Once a disk image is mounted, you can alternatively also boot from a disk image by selecting "Drive" from the menu bar (when in windowed mode), followed by the drive letter and "Boot from drive". You can also mount and boot a disk image in one step by selecting "Boot from disk image" from this submenu.

Using harddisk images in Linux

Warning
 You should never mount a harddisk image simultaneously in both DOSBox-X and in Linux, as that can cause corruption of files or the filesystem on the disk image.

Gnome Disk Image Mounter

When using the Gnome desktop environment, you can open .IMG disks with the "Disk Image Mounter". Simply right-click on the file, and select 'Open with Disk Image Mounter' and the file will be mounted READ-ONLY in the Gnome file manager.

Note
 If the harddisk image contains multiple partitions, they will ALL be mounted.

Disks can be unmounted from the Gnome file manager by clicking the unmount button next to the volume name.

Disk images can also be mounted READ-WRITE from the Linux Terminal using:

gnome-disk-image-mounter -w hdd.img

Or if you run gnome-disk-image-mounter without arguments, it will ask you which disk image to mount, and give you the ability to mount it READ-WRITE.

Mounting a harddisk image from the Linux shell

The more traditional Linux method of mounting harddisk image files from a Linux terminal. This method requires sudo access.

sudo mount -o loop,offset=32256,uid=$UID hdd.img /mnt

The above command will cause hdd.img to be mounted under /mnt on the host.

The offset is required to skip the Master Boot Record (MBR) and partition data at the beginning of the harddisk image.

Tip
 This command will mount the first partition only. If the harddisk image contains multiple partitions, you can find the offset for the other partitions by running on the host fdisk -l hdd.img and looking for the "Start" of the partition, and multiply the value by 512. For the first partition this should normally always start at 63*512=32256

Using harddisk images in Windows

Note
 Windows 8 and newer has integrated support for mounting image files, and will offer the "Mount" option when you right-click a .IMG file. Unfortunately this support is incompatible with the typical RAW MFM image files used by DOSBox-X, and the mount will fail.

One tool which is able to open harddisk images is 7-Zip, but only in read-only mode.

Using harddisk images in macOS

You can mount RAW MFM harddisk image files with the extension .IMG in macOS from the Finder by double-clicking on it. You can unmount it by clicking on the "Eject" button next to it in the Finder.

RAW MFM Harddisk images can also be opened in macOS from the Terminal using hdiutil as such:

hdiutil attach hdd.img
/dev/disk6              FDisk_partition_scheme
/dev/disk6a1            DOS_FAT_16

The output will tell you where the disk is attached. In the above example the disk is mounted on /dev/disk6, and the first partition as /dev/disk6a1.

After this the harddisk image should be available from both the terminal and from Finder. Once you’re done, you can detach it as follows:

hdiutil detach /dev/disk6
"disk6" ejected.

CD-ROM or DVD images

DOSbox-X supports CD-ROM or DVD image files with the ISO-9660 (or High-Sierra) filesystem in .ISO, .CUE+.BIN, .MDF or .CHD image format.

By default, ISO-9660 Level 1 is used, which is limited to traditional DOS 8.3 character filenames. When emulating DOS version 7.0 or later (or lfn=true is set in the DOSBox-X config file), ISO-9660 Level 2 is supported with up to 31 character filenames.

Starting with DOSBox-X 2022.08.0 there is also support for:

  • Rock Ridge extensions to ISO-9660, allowing up to 255 character mixed-case file names with Unicode (typically used by Unix or Unix-like systems, such as Linux)

  • Joliet extensions to ISO-9660, allowing up to 64 character mixed-case file names with Unicode (introduced for Windows 95)

  • UDF filesystem, more commonly used for DVD media (introduced for Windows 98)

.ISO is the easiest format to work with, as long as there is only a single data track on the CD or DVD. If the CD or DVD contains multiple tracks, like DATA and AUDIO (aka redbook audio) the use of .CUE+.BIN, .MDF or .CHD is required.

Copy protected media

DOSBox-X has limited support for copy protected CD-ROMs.

  • In DOSBox-X 2022.08.00 the IDE emulation was enhanced such that SafeDisc V1 games should work

  • In DOSBox-X 2022.09.00 another minor change was introduced to solve one of the issues with SafeDisc V2

If you run into issues with copy protected media, look for "cracks" for the game to bypass the copy protection.

Mounting CD or DVD images

Mounting a CD or DVD image in DOSBox-X is typically as simple as

imgmount d cdrom.iso

This is equivalent to

imgmount D: cdrom.iso
imgmount D: cdrom.iso -t iso
imgmount D: cdrom.iso -t cdrom
Note
 The -t iso or -t cdrom parameter is only needed with DOSBox-X when the extension is not .ISO, .CUE, .MDF or .CHD.
Note
 If the names of your CD/DVD images contain characters of foreign languages such as Japanese, please make sure that the current DOS code page matches the language you use before mounting the images. If you decide to put such commands in the [autoexec] section of the config file, please also make sure the encoding of your config file matches your language when you save the config file.

Rock Ridge, Joliet and UDF

Starting with DOSBox-X 2022.08.0, there is support for the Rock Ridge and Joliet extensions (for long filenames) to the ISO-9660 filesystem, in addition to support for the UDF filesystem.

Support for Rock Ridge and Joliet is automatically enabled when emulating DOS 7.0 or later. Support for UDF is enabled when emulating DOS 7.1 or later. Alternatively, Rock Ridge and Joliet support is also enabled when the lfn=true setting is set in the DOSBox-X config file.

If DOSBox-X detects a CD image with both Rock Ridge and Joliet extensions, it will only use the Joliet extensions.

Rock Ridge, Joliet or UDF support can be enabled or disabled when mounting a CD image with the -o [rr|joliet|udf] image mount option.

e.g. to mount a CD image and disable Rock Ridge support:

imgmount D: cdrom.iso -o rr=0

Mounting an empty CD-ROM drive

Starting with DOSBox-X 2024.03.01 it is possible to mount an empty CD-ROM drive. This is useful for when you intend to boot a guest OS, and want to be able to insert a CD-ROM in the drive after booting using the DOSBox-X drop-down menu’s.

imgmount e -t iso -empty

Accessing a CD or DVD in real DOS

With the integrated DOS that DOSBox-X provides, you do not need to worry about loading a CD-ROM driver and MSCDEX. If however, you boot real DOS in DOSBox-X, any mounted CD-ROM images will not be accessible until you load both an IDE CD-ROM driver and MSCDEX.

For an IDE CD-ROM driver we recommend either OAKCDROM.SYS, UIDE.SYS or VIDE-CDD.SYS.

  • OAK stands for OEM Adaptation Kit, and this is the IDE CD-ROM driver shipped on the Windows 95, 98 and ME boot disks.

  • UIDE.SYS is available from FreeDOS. Note that this driver is know to have issues in some cases, such as with mixed media (data+audio)

  • You can also use the Acer VIDE-CDD.SYS driver which loads faster than OAKCDROM.SYS.

MSCDEX.EXE is included with MS-DOS 6.x and included on the Windows 95, 98 or ME boot disks, or you can use the SHSUCDX.EXE redirector available from FreeDOS.

Edit the config.sys file and add the following line to it:

device=c:\dos\oakcdrom.sys /D:cdrom001

Edit the autoexec.bat file and add the following line to it:

device=c:\dos\mscdex.exe /D:cdrom001 /L:D

The above assumes oakcdrom.sys and mscdex.exe are in the C:\DOS directory in the harddisk image file. You can substitute oakcdrom.sys and mscdex.exe with their FreeDOS equivalents with the same parameters.

The /L:D option will cause MSCDEX to use the D: drive letter for the CD-ROM, adjust as needed.

Mounting multiple CD or DVD images

Some DOS programs or games came on multiple CD or DVDs, for this purpose it is possible to mount multiple images on one drive letter and swap between them. e.g.

imgmount d cdrom1.iso cdrom2.iso cdrom3.iso

In this example cdrom1.iso will be immediately usable on D: but cdrom2.iso will require a disc-swap action.

Disk-swap can be done using either a hot-key combination, or using the menu bar. The hot-key for Windows is F11+CTRL+C and for other platforms F12+CTRL+C. Or from the menu you can select "DOS" followed by "Swap CD". Lastly, you can use the IMGSWAP command to swap between images.

If you lose track of which disc is currently active, open the 'Drive' menu option, select the drive letter and select 'Drive Information'. This information can also be retrieved from the IMGSWAP command.

Mounting from the Drive menu

The advantage of this option is, that you don’t need to mount all the CD or DVDs before starting your program or game, but you can mount CD or DVD images when needed.

To access it, DOSBox-X needs to be in windowed mode, there is a menu bar with a "Drive" drop-down. Select a drive letter, and you will see various mount options.

The only mount option that can be used for image files is the "Mount disk image" option. All the other mount options are host folder mounts.

Select the Drive menu, and a suitable drive letter, and "Mount disk image". Now a file browser will allow you to select an image file.

Unmounting CD or DVD images

CD or DVD images can be unmounted using the -u flag. e.g.

imgmount d -u

You can also unmount using the MOUNT command.

mount d -u

It is also possible to unmount the currently mounted image (if any), and mount a new image in one step.

imgmount d cdrom2.iso -u

This will cause the currently mounted image file (if any) to be unmounted, and cdrom2.iso to be mounted instead.

Tip
 Alternatively you can unmount an image from the DOSBox-X menu bar (when in windowed mode) by selecting "Drive", followed by the drive letter and "Unmount".

Boot from a CD or DVD image

DOSBox-X has limited support for booting from a CD or DVD. Only those that use the El Torito emulated diskette method are supported, such as the Windows 98 or Windows ME full-OEM editions.

You first need to mount the CD-ROM, then mount the diskette image, located on the CD-ROM, and finally you can boot from the A: drive:

imgmount d Win98.iso
imgmount a -bootcd d
boot A:
Note
 The second command is equivalent to imgmount a -el-torito d or imgmount a -el-torito d -t floppy. If this command gives the error "El Torito CD-ROM boot record not found", the CD-ROM is either not bootable or uses an unsupported boot method.
Note
 DOSBox-X supports the -L parameter for the BOOT command for backward compatibility with vanilla DOSBox, or other forks, but the parameter is not required with DOSBox-X to boot from a drive letter.

Using CD or DVD images in Linux

.ISO images are fully supported by standard Linux tools, but .CUE+.BIN, .MDF and .CHD are not.

Gnome Disk Image Mounter

If you’re using the Gnome desktop environment, you can open .ISO disks with the "Disk Image Mounter". Simply right-click on the file, and select 'Open with Disk Image Mounter' and the file will be mounted in the Gnome file manager. This method will not work for .CUE+.BIN, .MDF or .CHD files.

Disks can be unmounted from the Gnome file manager by clicking the unmount button next to the volume name.

.ISO images can also be mounted from the Linux Terminal using:

gnome-disk-image-mounter cdrom.iso

CDEmu

CDEmu is a CD-ROM emulator for Linux. It supports numerous image formats, including .ISO, .CUE+.BIN and .MDF.

Mounting a ISO image from the Linux shell

The more traditional Linux method of mounting diskette image files from a Linux terminal. This method will not work for .CUE+.BIN, .MDF or .CHD files. This method requires sudo access.

sudo mount -o loop cdrom.iso /mnt

The above command will cause cdrom.iso to be mounted under /mnt on the host.

Using CD or DVD images in Windows

Windows 8 and later has integrated support for mounting ISO files. Simply right-click a ISO file and select "Mount".

Alternatively there is WinCDEmu which can mount amongst others ISO, CUE+BIN and MDF images.

Programs like 7-Zip, WinRAR and WinZIP can also extract the contents of a ISO file

Using CD or DVD images in macOS

You can mount ISO image files with the extension .ISO in macOS from the Finder by double-clicking on it. You can unmount it by clicking on the "Eject" button next to it in the Finder.

ISO images can also be opened in macOS from the Terminal using hdiutil.

Copying files into or out of image files from DOSBox-X

If you need to copy files into, or out of an image file, this can be done from the DOSBox-X integrated DOS.

Obviously, copying files to write-protected media is not possible. As such you cannot copy files to a CD or DVD image, or to write-protected diskette images.

The general steps are as follows:

  1. Start DOSBox-X

  2. imgmount the image file in DOSBox-X that you want to copy files into or out of

  3. mount a host directory or drive

  4. Copy the files using the copy or xcopy commands

Example of extracting the contents of a CD-ROM image file:

IMGMOUNT d cdrom.iso
MOUNT C .
MKDIR C:\CDROM
XCOPY D: C:\CDROM /I /S

This will create a new "CDROM" directory on the host system with the contents of the cdrom.iso file.

Example of copying a file into a harddisk image file:

IMGMOUNT C hdd.img
MOUNT D .
COPY D:\UNZIP.EXE C:\DOS

This copies the file UNZIP.EXE from the host system to the C:\DOS directory in the harddisk image file.

Creating a RAM drive

If you need a temporary drive, creating a RAM drive is as simple as running

IMGMOUNT e -t ram -size 20000

This will create a temporary RAM drive as drive E: with a size of 20MB.

Caution
 The contents of the RAM drive will be lost if the drive is unmounted, a program or yourself issues a reset in DOSBox-X or DOSBox-X is shut-down. They do however survive booting into real DOS.
Note
 Unlike traditional DOS RAM disk programs (e.g. VDISK, RAMDRIVE) this RAM drive will not use any memory allocated for use inside DOSBox-X itself. In other words, it will have no effect on available memory for DOS programs.

QCOW2 support

DOSBox-X provides limited support for QCOW2 disk images.

  • There is no support for creating QCOW2 images in DOSBox-X

  • There is no support for the newer zstd compression or encryption options

  • Copy-On-Write support needs to be handled manually, outside DOSBox-X

A QCOW2 image can be created with qemu-img as such:

qemu-img create -f qcow2 -o compat=0.10 hdd.qcow2 2G

The above command will create a 2GiB QCOW2 file named hdd.qcow2. Due to zlib compression the disk image will be significantly smaller and grow with usage.

Mounting an empty qcow2 image file can be accomplished in DOSBox-X as follows:

imgmount 2 hdd.qcow2

At this point, the image file will have to be partitioned or formatted, which can be done by booting from a DOS floppy disk:

Once a qcow2 image file has been partitioned and formatted, it can be mounted on a drive-letter as such:

imgmount C hdd.qcow2

The advantage of the QCOW2 format, is the Copy-On-Write (COW) functionality which allows you to create a base image of for instance Windows 98, and then have different snapshots on top of that with different drivers or applications. This saves disk space compared to maintaining multiple full installations, and can prevent Windows bit-rot.

VHD support

DOSBox-X provides support for VHD (aka Virtual PC) disk images. This supports was enhanced in DOSBox-X 2023.09.01.

There are various ways to create VHD images. Either external tools can be used, or the integrated IMGMAKE utility can be used.

For example to create a 2GiB dynamic VHD image using the integrated IMGMAKE utility:

imgmake hdd.vhd -t vhd -size 2048

Or to create a 2GiB fixed-size VHD image using the integrated 'IMGMAKE' utility:

imgmake hdd.vhd -t hd -size 2048

The advantage of using IMGMAKE is that the created image file will be partitioned and formatted and as such is ready to be mounted.

Alternatively, external tools such as qemu-img can be used to create VHD files, with the disadvantage that they may not be partitioned and formatted.

If you have a VHD image file that is not partitioned or formatted, it will have to be mounted on a drive-number, after which you can boot from a DOS floppy disk to partition and format the image:

imgmount 2 hdd.vhd

Once a VHD image file has been partitioned and formatted, it can be mounted on a drive-letter as such:

imgmount C hdd.vhd

Archiving diskettes

If you have 3.5" or 5.25" diskettes that you want to convert to image files, there are a multitude of ways to accomplish this, and really out of the scope for this Guide.

Some potential useful links:

If you have a relatively modern PC running Windows with a floppy drive, the IMGMAKE command supports converting a diskette to an image file. This will even work with USB diskette drives.

IMGMAKE disk.ima -source a -r 3

The above will try to read the real A: drive on your Windows PC, and convert it to a disk image named disk.ima. The -r option specifies how many retries are allowed while reading the original diskette.

Caution
 Do not buy "modern" USB 3.5" floppy drives available from retailers like Amazon. The drive mechanisms are junk and have a high likelihood of damaging your disk. Instead, look for an older second-hand USB floppy drive from a known brand like Dell, HP, IBM, Lenovo, Sony, Teac or Toshiba.

FDISK

DOSBox-X does not supply the FDISK utility to partition harddisks. Instead it supplies an IMGMAKE utility which can be used to create HDD image files, including paritioning and formatting them.

If however you really want to run the DOS FDISK utility from the DOSBox-X integrated emulated DOS, it is possible as of DOSBox-X 2023.10.06.

First create a blank HDD image file:

Z:\>IMGMAKE hdd.img -t hd -nofs -size 100
Creating image file "hdd.img" with 812 cylinders, 4 heads and 63 sectors

Then attach the blank image using the CHS geometry. '2' is a drive number that refers to the first HDD.

Z:\>IMGMOUNT 2 hdd.img -size 512,63,4,812
Drive number 2 mounted as hdd.img

Now running FDISK from MS-DOS or PC DOS should work, and allow partitions to be created or deleted.

Note
 If FDISK return an error "Incorrect DOS version", you must set the DOSBox-X reported DOS version to match the DOS version that FDISK came from. e.g., if FDISK.EXE came from MS-DOS 6.22, first run VER SET 6.22.

FORMAT

DOSBox-X does not supply the FORMAT utility to format floppies or harddisks. Instead it supplies an IMGMAKE utility which can be used to create Floppy or HDD image files, including formatting them.

If however you really want to run the DOS FORMAT utility from the DOSBox-X integrated emulated DOS, it is partly possible as of DOSBox-X 2023.10.06.

Note
 A harddisk image MUST be partitioned before it can be formatted.
Note
 Formatting an unformatted floppy disk image is not possible at this time using this method. But it is possible to format a floppy disk that is already formatted.
Note
 It is important to mount the image file on a drive letter, as FORMAT cannot deal with drive numbers.

In case of a harddisk, first follow the steps in the FDISK section above to create the image file and partition it.

Then attach the image using IMGMOUNT.

Note
 For harddisk images, once the image is partitioned it is no longer necessary to specify the geometry. 
Z:\>IMGMOUNT c hdd.img
Image geometry auto detection: -size 512,63,4,812
Drive C is mounted as hdd.img
Drive not formatted. Format it before accessing the drive.

Once the image file is mounted on a drive letter, running FORMAT from MS-DOS or PC DOS should work.

Note
 the '/s' option to transfer system files does not work properly at this time.

Known limitations

When booting a Guest OS (DOS or Win9x) in DOSBox-X all the Drive options will become unavailable (greyed out). This is because, once you boot a guest OS, the drive letter mapping loses its meaning as the guest OS is responsible for drive letter assignment.

The only mapping that DOSBox-X still has at that point, is that of drive numbers to the image file.

There is limited support for changing the loaded Floppy or CD image from the DOS menu where you will find the options "Change current floppy image…​" and "Change current CD image…​".

If multiple floppy or CD-ROM images are mounted, you will be asked for each mounted image if you want to change it.

Some limitations of this support:

  • Requires either an image to be mounted before you boot a Guest OS, or an empty drive to be emulated. Otherwise, you will get an error such as "No floppy drive is currently available".

Outstanding issues with this page

  • Mention Bochs bximage support in more detail. Does it support flat, sparse, growing formats?

  • How about IDE tertiary through octernary controllers in dosbox-x config. Do the device number and/or -ide options continue counting up to device number 18 and -ide 8s?

  • PC-98 descriptions need checking as I have no experience with them.