sys/man/4/cwfs

   1 .TH CWFS 4
   2 .SH NAME
   3 cwfs \- cached-worm file server, dump
   4 .SH SYNOPSIS
   5 .B cwfs
   6 [
   7 .B -csC
   8 ] [
   9 .B -n
  10 .I service
  11 ] [
  12 .B -a
  13 .I announce-string
  14 ] ... [
  15 .B -m
  16 .I device-map
  17 ] [
  18 .B -f
  19 .I config-device
  20 ]
  21 .SH DESCRIPTION
  22 .I Cwfs
  23 is a cached-worm file server that runs
  24 as a user-mode program and can
  25 maintain file systems created by
  26 .IR fs (4),
  27 the original Plan 9 file server
  28 that had its own kernel and operated
  29 a standalone system with disks and
  30 optical-disc jukebox attached.
  31 Unlike
  32 .IR fs (4),
  33 which could only accept 9P connections over IL/IPv4 on Ethernets
  34 (or over Datakit and Cyclones, long ago),
  35 .I cwfs
  36 accepts 9P connections over any network medium and protocol
  37 that it can announce on,
  38 by default TCP (over IPv4 or IPv6).
  39 Given suitable 9P clients,
  40 one could even run 9P over
  41 .IR aan (8)
  42 or
  43 .IR tls (3).
  44 .PP
  45 The stock
  46 .I cwfs
  47 implements a 16K file system block size
  48 and 32-bit disk addresses,
  49 in order to be compatible with some existing file systems, notably
  50 .IR emelie 's.
  51 These parameters can be changed by recompilation.
  52 .PP
  53 .I Cwfs
  54 places its server 9P connection in
  55 .BI /srv/ name\f1
  56 and its command pipe in
  57 .BI /srv/ name\f1 .cmd,
  58 where
  59 .I name
  60 is the service name.
  61 .PP
  62 Options are:
  63 .TP
  64 .B -f
  65 specify
  66 .IR config-device
  67 other than the default
  68 .LR /dev/sdC0/cwfs .
  69 .TP
  70 .B -a
  71 announce on
  72 .I announce-string
  73 instead of
  74 .LR tcp!*!9fs .
  75 .TP
  76 .B -C
  77 use a newer, faster, and incompatible cache-device layout.
  78 To convert an old file system's cache to the new layout,
  79 dump the file system, note the last superblock number,
  80 halt
  81 .IR cwfs ,
  82 restart
  83 .I cwfs
  84 with
  85 .BR -cC ,
  86 .I recover
  87 the file system, and start
  88 .I cwfs
  89 with
  90 .B -C
  91 thereafter.
  92 .TP
  93 .B -c
  94 enter the file server's configuration mode
  95 before starting normal operation.
  96 .TP
  97 .B -n
  98 overrides the
  99 .I service
 100 name of the file server's configuration.
 101 .TP
 102 .B -s
 103 Post file descriptor zero in
 104 .BI /srv/ service
 105 and read and write protocol messages on file descriptor one.
 106 .TP
 107 .B -m
 108 the file
 109 .I device-map
 110 contains a simple device name
 111 (e.g.,
 112 .LR w9 )
 113 and a replacement per line.
 114 The device name is in the usual
 115 .I filsys
 116 notation of
 117 .IR fsconfig (8).
 118 The replacement can be the name of an existing file
 119 (which
 120 .I cwfs
 121 will not grow)
 122 or another such device name.
 123 For example, the file
 124 .RS
 125 .PD
 126 .IP
 127 .EX
 128 w0 /tmp/w0
 129 h1 w2
 130 .EE
 131 .PP
 132 .PD 0.3v
 133 would map accesses to device
 134 .L w0
 135 to existing file
 136 .LR /tmp/w0
 137 and accesses to device
 138 .L h1
 139 to device
 140 .LR w2 ,
 141 if no file named
 142 .L w2
 143 exists.
 144 .RE
 145 .PD
 146 .PP
 147 The file server normally requires all users except
 148 .L none
 149 to provide authentication tickets on each
 150 .IR attach (5).
 151 This can be disabled using the
 152 .B noauth
 153 configuration command (see
 154 .IR fsconfig (8)).
 155 .PP
 156 The group numbered 9999, normally called
 157 .BR noworld ,
 158 is special
 159 on the file server.  Any user belonging to that group has
 160 attenuated access privileges.  Specifically, when checking such
 161 a user's access to files, the file's permission bits are first ANDed
 162 with 0770 for normal files or 0771 for directories.  The effect is
 163 to deny world access permissions to
 164 .B noworld
 165 users, except
 166 when walking directories.
 167 .PP
 168 The user
 169 .B none
 170 is always allowed to attach to
 171 .B emelie
 172 without authentication but has minimal permissions.
 173 .PP
 174 .B Emelie
 175 maintains three file systems
 176 on a combination of disks and
 177 write-once-read-many (WORM) magneto-optical disks.
 178 .TP
 179 .B other
 180 is a simple disk-based file system similar to
 181 .IR kfs (4) .
 182 .TP
 183 .B main
 184 is a worm-based file system with a disk-based
 185 look-aside cache.
 186 The disk cache holds
 187 modified worm blocks
 188 to overcome the write-once property of the worm.
 189 The cache also holds recently accessed
 190 non-modified blocks to
 191 speed up the effective access time of the worm.
 192 Occasionally
 193 (usually daily at 5AM) the modified blocks in the
 194 disk cache are
 195 .IR dumped .
 196 At this time,
 197 traffic to the file system is halted and the
 198 modified blocks are relabeled to the unwritten
 199 portion of the worm.
 200 After the dump,
 201 the file system traffic is continued and
 202 the relabeled blocks are copied to the worm by
 203 a background process.
 204 .TP
 205 .B dump
 206 Each time the main file system is dumped,
 207 its root is appended to a subdirectory of the dump file system.
 208 Since the dump file system is not mirrored with a disk
 209 cache,
 210 it is read-only.
 211 The name of the newly added root is created from the date
 212 of the dump:
 213 .BI / yyyy / mmdds\f1.
 214 Here
 215 .I yyyy
 216 is the full year,
 217 .I mm
 218 is the month number,
 219 .I dd
 220 is the day number and
 221 .I s
 222 is a sequence number if more than
 223 one dump is done in a day.
 224 For the first dump,
 225 .I s
 226 is null.
 227 For the subsequent dumps
 228 .I s
 229 is 1, 2, 3, etc.
 230 .sp
 231 The root of the main file system
 232 that is frozen on the first dump
 233 of March 1, 1992
 234 will be named
 235 .B /1992/0301/
 236 in the dump file system.
 237 .SS "Changes from fs"
 238 .IR fs (4)'s
 239 IP configuration is ignored and the underlying system's is used.
 240 .PP
 241 Various other
 242 .IR fs (4)
 243 commands have been omitted since they (or equivalents) can now be
 244 executed directly on the underlying CPU server,
 245 notably
 246 .I date
 247 and
 248 .I passwd
 249 (see
 250 .IR auth/wrkey ).
 251 .PP
 252 Files can be used directly as wren devices by giving
 253 a file name rooted at
 254 .I /
 255 or using double or single quotes. Such a file name
 256 can be appended to the
 257 .L w
 258 device instead of specifying
 259 .L target
 260 and
 261 .L lun
 262 numbers.
 263 .PP
 264 .IR fs (4)'s
 265 device names
 266 .L h
 267 for IDE disks and
 268 .L m
 269 for Marvell SATA disks are not supported; use
 270 .B -m
 271 to map wren devices to appropriate names under
 272 .BR /dev/sd* .
 273 .PP
 274 The file server kernel seems to have scanned PCI buses
 275 in reverse order from the other Plan 9 kernels,
 276 so systems with multiple SCSI cards may find controller
 277 numbering reversed.
 278 .B -m
 279 can be used to compensate for this if you don't want to change
 280 .I filsys
 281 declarations.
 282 .PP
 283 The file server kernel's
 284 .I config
 285 field in NVRAM was overloaded in recent times to hold a
 286 .IR secstore (1)
 287 key for the CPU hostowner.
 288 Since
 289 .I cwfs
 290 runs on a CPU kernel,
 291 the location of its configuration block must be supplied on the command line.
 292 .PP
 293 Disk labels are now implemented for
 294 .B l
 295 devices.
 296 At the first access of a side,
 297 .I cwfs
 298 will attempt to read the label and verify that it has the correct side
 299 number and byte order; if either is wrong, it will issue a warning.
 300 If the label cannot be read,
 301 .I cwfs
 302 will attempt to write a new label.
 303 .SH EXAMPLES
 304 Place the root of the
 305 .B dump
 306 file system on
 307 .B /n/dump
 308 and show the modified times of the MIPS C compiler
 309 over all dumps in February, 1992:
 310 .IP
 311 .EX
 312 cwfs w0
 313 9fs dump
 314 ls -l /n/dump/1992/02??/mips/bin/vc
 315 .EE
 316 .PP
 317 To get only one line of output for each version of the compiler:
 318 .IP
 319 .EX
 320 ls -lp /n/dump/1992/02??/mips/bin/vc | uniq
 321 .EE
 322 .SH SOURCE
 323 .B /sys/src/cmd/cwfs
 324 .SH SEE ALSO
 325 .IR yesterday (1),
 326 .IR fs (3),
 327 .IR sd (3),
 328 .IR fs (4),
 329 .IR srv (4),
 330 .IR fs (8),
 331 .IR fsconfig (8)
 332 .br
 333 Sean Quinlan,
 334 ``A Cached WORM File System'',
 335 .I
 336 Software \- Practice and Experience,
 337 December, 1991
 338 .br
 339 Ken Thompson,
 340 Geoff Collyer,
 341 ``The 64-bit Standalone Plan 9 File Server''
 342 .SH BUGS
 343 For the moment,
 344 the file server serves both the old (9P1) and new (9P2000) versions of 9P,
 345 deciding which to serve by sniffing the first packet on each connection.
 346 .PP
 347 File system block size and disk address size (32- or 64-bit) are fixed
 348 at compilation time, and this is not easily changed.