20060303-partial

1 files changed, 145 insertions, 0 deletions

diff --git a/man/3/ds b/man/3/ds
new file mode 100644
index 00000000..6d766698
--- /dev/null
+++ b/man/3/ds
@@ -0,0 +1,145 @@
+.TH DS 3
+.SH NAME
+ds \- compound device subsystems
+.SH SYNOPSIS
+.nf
+.B bind -b #k /dev
+
+.B /dev/ds
+.B /dev/ds/ctl
+.B /dev/ds/...
+.fi
+.SH DESCRIPTION
+.I Ds
+builds complex block storage subsystems out of simpler ones.
+Inspired by the Plan 9 file server kernel's configuration strings,
+it provides device mirroring, partitioning, interleaving, and catenation
+for block-oriented file systems.
+.PP
+It serves a two-level directory.
+The top level contains a single directory
+.BR ds ,
+which contains a control file
+.B ctl
+and one file per configured device.
+.PP
+The control messages each introduce a new device, here named
+.IR new .
+The
+.I file
+arguments are interpreted in the name space of the writer.
+.TP
+.BI mirror " new files" \fR...
+The device
+.I new
+corresponds to a RAID 1 mirroring of
+.IR files .
+Writes to
+.BI new
+are handled by sequentially writing to the
+.I files
+from right to left (the reverse of
+of the order in the control message).
+If any write fails, the write is aborted.
+Reads from
+.BI new
+are handled by sequentially reading from the
+.I files
+from left to right until one succeeds.
+The length of the mirror device is the minimum of the lengths of the
+.IR files .
+.TP
+.BI part " new file offset length"
+The device
+.I new
+corresponds to the
+.I length
+bytes starting at
+.I offset
+in
+.IR file .
+If
+.IR offset + length
+reaches past the end of
+.IR file ,
+.I length
+is silently reduced to fit.
+.TP
+.BI inter " new files" \fR...
+The device
+.I new
+corresponds to the block interleaving of
+.IR files ;
+an 8192-byte block size is assumed.
+.TP
+.BI cat " name files" \fR...
+The device
+.I new
+corresponds to the catenation of
+.IR files .
+.PD
+.LP
+If the variable
+.B fsconfig
+is set in
+.IR plan9.ini (8)
+then
+.I ds
+will read its configuration from the file
+.B $fsconfig
+on the first attach.
+This is useful when the machine boots
+from a local file server that uses
+.IR fs .
+.SH EXAMPLE
+Mirror the two disks
+.B /dev/sdC0/data
+and
+.B /dev/sdD0/data
+as
+.BR /dev/ds/m0 ;
+similarly, mirror
+.B /dev/sdC1/data
+and
+.B /dev/sdD1/data
+as
+.BR /dev/ds/m1 :
+.IP
+.EX
+echo mirror m0 /dev/sdC0/data /dev/sdD0/data >/dev/ds/ctl
+echo mirror m1 /dev/sdC1/data /dev/sdD1/data >/dev/ds/ctl
+.EE
+.LP
+Interleave the two mirrored disks to create
+.BR /dev/ds/data :
+.IP
+.EX
+echo inter data /dev/ds/m0 /dev/ds/m1 >/dev/ds/ctl
+.EE
+.LP
+Run
+.IR kfs (4)
+on the interleaved device:
+.IP
+.EX
+disk/kfs -f /dev/ds/data
+.EE
+.LP
+Save the configuration:
+.IP
+.EX
+cp /dev/ds/ctl /dev/fd0disk
+.EE
+To load the configuration automatically at boot time,
+add this to
+.IR plan9.ini :
+.IP
+.EX
+fsconfig=/dev/fd0disk
+.EE
+.SH "SEE ALSO"
+.IR dossrv (4)
+.SH SOURCE
+.B /os/port/devds.c
+.SH BUGS
+Should be able to select block size for interleaved devices.