geom_fox(4)

NAME

geom_fox - GEOM based basic disk multipathing

SYNOPSIS

kldload geom_fox

DESCRIPTION

The intent of the geom_fox framework is to provide basic

multipathing
support to access direct access devices. Basic in the above

sentence
should be read as: geom_fox only provides path failover

functionality,
not load balancing over the available paths etc. Using

suitable hardware
like SCSI or FibreChannel disks it is possible to have mul

tiple (typically 2) host bus adapters access the same physical disk

drive.

Without a multipathing driver the FreeBSD kernel would probe

the disks
multiple times, resulting in the creation of multiple /dev

entries for
the same underlying physical device. A unique label written

in the GEOM
label area allows geom_fox to detect multiple paths. Using

this information it creates a unique da#.fox device.

The geom_fox device is subsequently used by the FreeBSD ker

nel to access
the disks. Multiple physical access paths ensure that even

in case of a
path failure the FreeBSD kernel can continue to access the

data.

The geom_fox driver will disallow write operations to the

underlying
devices once the fox device has been opened for writing.

EXAMPLES

+o geom_fox needs a label on the disk as follows in order

to work prop

erly:

"0123456789abcdef0123456789abcdef"
"GEOM::FOX <--unique--id-->"

For the unique ID 16 bytes are available. The GEOM::FOX

is the magic
to mark a geom_fox device.

The actual labelling is accomplished by

echo "GEOM::FOX someid" | dd of=/dev/da2 conv=sync

For FibreChannel devices it is suggested to use the Node

World Wide
Name (Node WWN) as this is guaranteed by the FibreChan

nel standard to
be worldwide unique. The use of the Port WWN not recom

mended as each
port of a given device has a different WWN, thereby con

fusing things.

The Node WWN can be obtained from a verbose boot as in

for example

isp1: Target 1 (Loop 0x1) Port ID 0xe8 (role Target) Ar

rived

Port WWN 0x21000004cfc8aca2
Node WWN 0x20000004cfc8aca2

This Node WWN would then be used like so:

echo "GEOM::FOX 20000004cfc8aca2" | dd of=/dev/da2

conv=sync

For non-FibreChannel devices you could for example use

the serial
number of the device. Regardless of what you use, make

sure the
label is unique.

Once the labelling has been performed and assuming the

geom_fox module is loaded the kernel will inform you that it has

found a new
geom_fox device with a message similar to

Creating new fox (da2)
fox da2.fox lock 0xfffffc0000fdba20

+o To check which physical devices match a given geom_fox

device:

# geom fox list
Geom name: da2.fox
Providers:
1. Name: da2.fox
Mediasize: 73407865344 (68G)
Sectorsize: 512
Mode: r0w0e0

Consumers:
1. Name: da2
Mediasize: 73407865856 (68G)
Sectorsize: 512
Mode: r0w0e0

2. Name: da6
Mediasize: 73407865856 (68G)
Sectorsize: 512
Mode: r0w0e0

+o To check the status of the geom_fox components:

# geom fox status
Name Status Components

da2.fox N/A da2
da6

SEE ALSO

GEOM(4), geom(8)

CAVEATS

The geom_fox driver depends on the underlying hardware

drivers to do the
right thing in case of a path failure. If for example a

hardware driver
continues to retry forever, geom_fox is not able to re-ini

tiate the I/O
to an alternative physical path.

You have to be very sure to provide a unique label for each

of the
geom_fox devices. Safety belts are not provided. For Fi

breChannel
devices it is suggested to use the Port WWN of the device.

The World
Wide Name is guaranteed to be worldwide unique per the Fi

breChannel standard.

BUGS

The geom_fox framework has only seen light testing. There

definitely
might be dragons here.

The name geom_fox is completely obscure. Just remember that

any sly fox
has multiple exits from its hole.

The examples provided are too FibreChannel-centric.

AUTHORS

The geom_fox driver was written by Poul-Henning Kamp

<phk@FreeBSD.org>.
This manual page was written by Wilko Bulte <wilko@FreeB

SD.org>.

BSD January 2, 2005

BSD