sys/man/4/cwfs

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