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 similar to
 184 .IR kfs (4) .
 185 .TP
 186 .B main
 187 is a worm-based file system with a disk-based
 188 look-aside cache.
 189 The disk cache holds
 190 modified worm blocks
 191 to overcome the write-once property of the worm.
 192 The cache also holds recently accessed
 193 non-modified blocks to
 194 speed up the effective access time of the worm.
 195 Occasionally
 196 (usually daily at 5AM) the modified blocks in the
 197 disk cache are
 198 .IR dumped .
 199 At this time,
 200 traffic to the file system is halted and the
 201 modified blocks are relabeled to the unwritten
 202 portion of the worm.
 203 After the dump,
 204 the file system traffic is continued and
 205 the relabeled blocks are copied to the worm by
 206 a background process.
 207 .TP
 208 .B dump
 209 Each time the main file system is dumped,
 210 its root is appended to a subdirectory of the dump file system.
 211 Since the dump file system is not mirrored with a disk
 212 cache,
 213 it is read-only.
 214 The name of the newly added root is created from the date
 215 of the dump:
 216 .BI / yyyy / mmdds\f1.
 217 Here
 218 .I yyyy
 219 is the full year,
 220 .I mm
 221 is the month number,
 222 .I dd
 223 is the day number and
 224 .I s
 225 is a sequence number if more than
 226 one dump is done in a day.
 227 For the first dump,
 228 .I s
 229 is null.
 230 For the subsequent dumps
 231 .I s
 232 is 1, 2, 3, etc.
 233 .sp
 234 The root of the main file system
 235 that is frozen on the first dump
 236 of March 1, 1992
 237 will be named
 238 .B /1992/0301/
 239 in the dump file system.
 240 .SS "Changes from fs"
 241 .IR fs (4)'s
 242 IP configuration is ignored and the underlying system's is used.
 243 .PP
 244 Various other
 245 .IR fs (4)
 246 commands have been omitted since they (or equivalents) can now be
 247 executed directly on the underlying CPU server,
 248 notably
 249 .I date
 250 and
 251 .I passwd
 252 (see
 253 .IR auth/wrkey ).
 254 .PP
 255 Files can be used directly as wren devices by giving
 256 a file name rooted at
 257 .I /
 258 or using double or single quotes. Such a file name
 259 can be appended to the
 260 .L w
 261 device instead of specifying
 262 .L target
 263 and
 264 .L lun
 265 numbers.
 266 .PP
 267 .IR fs (4)'s
 268 device names
 269 .L h
 270 for IDE disks and
 271 .L m
 272 for Marvell SATA disks are not supported; use
 273 .B -m
 274 to map wren devices to appropriate names under
 275 .BR /dev/sd* .
 276 .PP
 277 The file server kernel seems to have scanned PCI buses
 278 in reverse order from the other Plan 9 kernels,
 279 so systems with multiple SCSI cards may find controller
 280 numbering reversed.
 281 .B -m
 282 can be used to compensate for this if you don't want to change
 283 .I filsys
 284 declarations.
 285 .PP
 286 The file server kernel's
 287 .I config
 288 field in NVRAM was overloaded in recent times to hold a
 289 .IR secstore (1)
 290 key for the CPU hostowner.
 291 Since
 292 .I cwfs
 293 runs on a CPU kernel,
 294 the location of its configuration block must be supplied on the command line.
 295 .PP
 296 Disk labels are now implemented for
 297 .B l
 298 devices.
 299 At the first access of a side,
 300 .I cwfs
 301 will attempt to read the label and verify that it has the correct side
 302 number and byte order; if either is wrong, it will issue a warning.
 303 If the label cannot be read,
 304 .I cwfs
 305 will attempt to write a new label.
 306 .SH EXAMPLES
 307 Place the root of the
 308 .B dump
 309 file system on
 310 .B /n/dump
 311 and show the modified times of the MIPS C compiler
 312 over all dumps in February, 1992:
 313 .IP
 314 .EX
 315 cwfs w0
 316 9fs dump
 317 ls -l /n/dump/1992/02??/mips/bin/vc
 318 .EE
 319 .PP
 320 To get only one line of output for each version of the compiler:
 321 .IP
 322 .EX
 323 ls -lp /n/dump/1992/02??/mips/bin/vc | uniq
 324 .EE
 325 .SH SOURCE
 326 .B /sys/src/cmd/cwfs
 327 .SH SEE ALSO
 328 .IR yesterday (1),
 329 .IR fs (3),
 330 .IR sd (3),
 331 .IR fs (4),
 332 .IR srv (4),
 333 .IR fs (8),
 334 .IR fsconfig (8)
 335 .br
 336 Sean Quinlan,
 337 ``A Cached WORM File System'',
 338 .I
 339 Software \- Practice and Experience,
 340 December, 1991
 341 .br
 342 Ken Thompson,
 343 Geoff Collyer,
 344 ``The 64-bit Standalone Plan 9 File Server''
 345 .SH BUGS
 346 For the moment,
 347 the file server serves both the old (9P1) and new (9P2000) versions of 9P,
 348 deciding which to serve by sniffing the first packet on each connection.
 349 .PP
 350 File system block size and disk address size (32- or 64-bit) are fixed
 351 at compilation time, and this is not easily changed.