= crosshurd-image(8)

== NAME

crosshurd-image - Create a bootable disk image file with `crosshurd`
setup

== SYNOPSIS

**crosshurd-image** [__option___*]

== DESCRIPTION

The script `crosshurd-image` creates a bootable disk image file with
a `crosshurd` setup. This may be used as primary disk for a virtual
machine, e.g. with `qemu-system-x86_64`.

== OPTIONS

**--disk=**__filename__::
use the given filename for the disk image file instead of the default
`base.img`.

**--size=**__number__ ::
make the disk image file be the given number of GiB instead of the
default `40`.

**--name=**__hostname__::
setup the filesystem with the given hostname instead of the default
hurd-test`. This name will be written into both `/etc/hosts` and
`/etc/hostname` in the created filsystem.

**--ip=**__address/bits__::
use the given ipv4 address and network part bits size instead of the
default `192.168.240.2/24`.

**--gw=**__address__::
use the given ipv4 address for as gateway instead of the default
`192.168.240.1`.

**--cpu=**__type__::
select cpu type for crosshurd, e.g. i386 instead of the default
`x86_64`.

**--extlinux**::
 use `extlinux` boot equipment instad of the default `grub`.

**--mb=**__file__::
select which multiboot definition file to use instead of the default
`/usr/share/crosshurd-image/servers.boot`.

== NOTES

`crosshurd-image` runs through a straight-forward sequence of steps
that involve:

. create a blank disk image file, +
  partitioned in a DOS table with a single partition, and +
  formatted for GNU Hurd (`ext2fs -o hurd`)

. use `crosshurd` for stage-1 setup of the GNU Hurd Debian filesystem

. add a bootloader (syslinux or grub) to the disk image file +
  with stage 1 boot loader, and +
  multiboot configuration for GNU Hurd core modules

. finalize setup with hostname and networking setup

The disk image file is then ready to be used as primary disk for a
virtual machine with legacy bios boot.

Note that the disk image file is created as a "holes" file where only
data blocks actually in use have been allocated in the filesystem.
This means that the actual size initially is smaller than reported by,
say, `ls -l`.

-- MULTIBOOT DEFINITION FORMAT

The multiboot defintition file is a grub multiboot snippet where the
first line consitute the parameters for the `multiboot` tag, and the
lines following constitute subsequent `module` declarations separated
by blank lines. This snippet will be included verbatim (except for
comments and blank lines) for the `grub` boot option, whereas it mill
be translated into the syslinux parameter format for its `mboot`
module for `extlinux` boot option.

The latter is essentially the same format, except that the `module`
keyword for `grub` is replaced with mboot's module separator tag
"---", and that arguments are stripped of their surrounding
single-quotes. Further, the line breaks are replaced by spacing, since
the mboot arguments need to be on a single line.

== AUTHOR

Ralph Ronnquist pass:[<rrq@rrq.au>]
