sys/man/8/fsconfig

   1 .TH FSCONFIG 8
   2 .SH NAME
   3 fsconfig \- configuring a file server
   4 .SH SYNOPSIS
   5 .B service
   6 .I name
   7 .PP
   8 .B config
   9 .I device
  10 .PP
  11 .B nvram
  12 .I device
  13 .PP
  14 .B filsys
  15 .I name
  16 .I device
  17 .PP
  18 .B ip
  19 .I ipaddr
  20 .PP
  21 .B ipgw
  22 .I ipaddr
  23 .PP
  24 .B ipmask
  25 .I ipaddr
  26 .PP
  27 .B ipauth
  28 .I ipaddr
  29 .PP
  30 .B ipsntp
  31 .I ipaddr
  32 .PP
  33 .B ream
  34 .I name
  35 .PP
  36 .B recover
  37 .I name
  38 .PP
  39 .B allow
  40 .PP
  41 .B readonly
  42 .PP
  43 .B noauth
  44 .PP
  45 .B noattach
  46 .PP
  47 .B copyworm
  48 .PP
  49 .B copydev
  50 .I from-dev
  51 .I to-dev
  52 .PP
  53 .B halt
  54 .PP
  55 .B end
  56 .SH DESCRIPTION
  57 When an
  58 .IR fs (4)
  59 file server's configuration has not been set,
  60 or by explicit request early in the server's initialization (see
  61 .IR fs (8)),
  62 the server enters `config mode'.  The commands described here
  63 apply only in that mode.  They establish configuration constants
  64 that are typically valid for the life of the server, and therefore
  65 need be run only once.  If the non-volatile RAM on the server
  66 gets erased, it will be necessary to recreate the configuration.
  67 .SS Syntax
  68 In these commands,
  69 .I ipaddr
  70 is an IP address in the form
  71 .BR 111.103.94.19
  72 and
  73 .I name
  74 is a text string without white space.
  75 The syntax of a
  76 .I device
  77 is more complicated:
  78 .TP
  79 .BI w n1 . n2 . n3
  80 Defines a SCSI disk on target (unit) id
  81 .IR n2 ,
  82 controller (host adapter)
  83 .IR n1 ,
  84 and LUN (logical unit number)
  85 .IR n3 .
  86 A single number specifies a target, while two numbers specify
  87 .IB target . lun\f1,
  88 with the missing numbers defaulting to zero.
  89 Any one of the numbers may be replaced by
  90 .BI < m - n >
  91 to represent the values
  92 .I m
  93 through
  94 .I n
  95 inclusive.
  96 .I M
  97 may be greater than
  98 .IR n .
  99 For example,
 100 .B (w<1-4>)
 101 is the concatenation of SCSI targets 1 through 4.
 102 .TP
 103 .BI h n1 . n2 . n3
 104 .I H
 105 is similar to
 106 .IR w ,
 107 but for IDE or ATA disks,
 108 and the controllers must be specified in
 109 .BR plan9.ini .
 110 .I Lun
 111 is ignored.
 112 .I Target
 113 0 is an IDE master
 114 and 1 is a slave.
 115 Instead of specifying
 116 .I controller
 117 and
 118 .IR target
 119 separately,
 120 one may omit the
 121 .I controller
 122 and specify a target of
 123 .IB controller-number *2
 124 .B +
 125 .IR target-number ,
 126 thus
 127 .B h2
 128 is equivalent to
 129 .B h1.0.0
 130 (second IDE controller, master drive).
 131 .TP
 132 .BI m n1 . n2 . n3
 133 .I M
 134 is similar to
 135 .IR h ,
 136 but for SATA drives connected to Marvell
 137 88SX[56]0[48][01] controllers.
 138 There is no need to specify the controllers in
 139 .B plan9.ini
 140 as they are autodiscovered.
 141 Hot-swapping drives is not currently supported.
 142 Similar target naming rules apply as for IDE controllers.
 143 However the controller-number is multiplied by the number of
 144 drives the controller supports rather than 2.
 145 Thus
 146 .B m9
 147 is equivalent to
 148 .B m1.1.0
 149 (second controller, second drive),
 150 if the first controller supports 8 drives.
 151 .TP
 152 .BI l n1 . n2 . n3
 153 .TP
 154 .BI r n1 . n2 . n3
 155 The same as
 156 .BR w ,
 157 but leaving a single block at the beginning for a label
 158 .BI ( l ),
 159 or not.
 160 Only
 161 .I n2
 162 is really of interest,
 163 and refers to a side of a WORM disc.
 164 These are only really relevant when used as
 165 .I device3
 166 in the
 167 .B j
 168 device (see below).
 169 .TP
 170 .BI ( device... )
 171 A pseudo-device formed from the concatenation of the
 172 .I devices
 173 in the list.  The devices are
 174 .I not
 175 blank- or comma-separated.
 176 .TP
 177 .BI [ device... ]
 178 A pseudo-device formed from the block-wise interleaving of the
 179 .I devices
 180 in the list.  The size of the result is the number of devices times
 181 the size of the smallest device.
 182 .TP
 183 .BI { device... }
 184 A pseudo-device formed from the mirroring of the first
 185 .I device
 186 in the list onto all the others.
 187 The size of the result is the size of the smallest device.
 188 One might think of this as RAID 1,
 189 and
 190 .B [
 191 .B ]
 192 as RAID 0,
 193 though neither includes any fancy recovery mechanisms.
 194 Each block is written to all the devices,
 195 starting with the rightmost in the list and working leftward.
 196 A block is read from the first device that provides it without error,
 197 starting with the leftmost in the list and working rightward.
 198 .TP
 199 .BI p device . n1 . n2
 200 A partition starting at
 201 .IR n1 %
 202 from the beginning of
 203 .I device
 204 with a length
 205 .IR n2 %
 206 of the size of the device.
 207 Parenthesize
 208 .I device
 209 if it contains periods.
 210 .TP
 211 .BI x device
 212 A pseudo-device that contains the byte-swapped contents of
 213 .IR device .
 214 Since the file server writes integers to disk in its native byte order,
 215 it can be necessary to use this device to read file systems written
 216 by processors of the other byte order.
 217 .TP
 218 .BR j (\f2device1\ device2\f1...)\f2device3
 219 .I Device1
 220 is the SCSI juke box interface.
 221 The
 222 .IR device2 s
 223 are the SCSI drives in the jukebox and
 224 .I device3
 225 represents the demountable platters in the juke box.
 226 .TP
 227 .BI f device
 228 A pseudo-WORM disk: blocks on
 229 .I device
 230 can be written only once and may not be read unless written.
 231 .TP
 232 .BI c device1device2
 233 A cached WORM.  The first
 234 .I device
 235 is the cache, the second the WORM.
 236 .TP
 237 .BI o
 238 (Letter o) The read-only (dump) file system
 239 of the most-recently defined cached WORM file system.
 240 .SS Configuration
 241 The
 242 .B service
 243 command sets the textual name of the server as known in
 244 the network databases.
 245 .PP
 246 The configuration information is stored in block zero on a
 247 device whose device string is written in non-volatile RAM.
 248 The
 249 .B config
 250 and
 251 .B nvram
 252 commands identify the
 253 .I device
 254 on which the information is recorded.
 255 The
 256 .B config
 257 command also erases any previous configuration.
 258 .PP
 259 The
 260 .I filsys
 261 command configures a file system on
 262 .I device
 263 and calls it
 264 .IR name .
 265 .I Name
 266 is used as the specifier in
 267 .B attach
 268 messages to connect to that file system.
 269 (The file system
 270 .B main
 271 is the one attached to if the specifier is null; see
 272 .IR attach (5)).
 273 .PP
 274 The rest of the configuration commands record IP addresses:
 275 the file server's address
 276 .RI ( ip ),
 277 the local gateway's
 278 .RI ( ipgw ),
 279 the local authentication server's
 280 .RI ( ipauth ),
 281 the local subnet mask
 282 .RI ( ipmask ),
 283 and the address of a system running an SNTP server
 284 .RI ( ipsntp ).
 285 .I Ipauth
 286 is no longer used.
 287 If the server has more than one network interface,
 288 a digit may be appended to the keywords
 289 .BR ip ,
 290 .B ipgw
 291 and
 292 .B ipmask
 293 to indicate the interface number;
 294 zero is the default.
 295 .SS "One-time actions"
 296 .PP
 297 The
 298 .I ream
 299 command initializes the named file system.  It overwrites
 300 any previous file system on the same device
 301 and creates an empty root directory
 302 on the device.
 303 If
 304 .I name
 305 is
 306 .BR main ,
 307 the file server, until the next reboot,
 308 will accept
 309 .B wstat
 310 messages
 311 (see
 312 .IR stat (5))
 313 that change the owner and group of files,
 314 to enable initializing a fresh file system from a
 315 .IR mkfs (8)
 316 archive.
 317 .PP
 318 For the
 319 .I recover
 320 command, the
 321 named file system
 322 must be a cached WORM.
 323 .I Recover
 324 clears the associated magnetic cache and initializes the file
 325 system, effectively resetting its contents to the last dump.
 326 .PP
 327 .I Allow
 328 turns off all permission checking; use with caution.
 329 .PP
 330 .I Readonly
 331 disables all writing to all devices.
 332 This is useful for trying dangerous experiments.
 333 .PP
 334 .I Noauth
 335 disables authentication.
 336 .PP
 337 .I Noattach
 338 prevents attachs.
 339 .PP
 340 .I Copyworm
 341 will copy a file system named
 342 .I main
 343 to one named
 344 .IR output ,
 345 block by block,
 346 and loop.
 347 It knows how to read a fake worm file system.
 348 .PP
 349 .I Copydev
 350 will copy the device
 351 .I from-dev
 352 to the device
 353 .IR to-dev .
 354 block by block,
 355 and panic.
 356 .PP
 357 .I Halt
 358 will cause the server to
 359 .I immediately
 360 exit and reboot.
 361 .PP
 362 The various configuration commands only record what to do; they write
 363 no data to disk.  The command
 364 .I end
 365 exits config mode and begins running the file server proper.
 366 The server will then perform whatever I/O is required to establish
 367 the configuration.
 368 .SH EXAMPLE
 369 Initialize a file server
 370 .B kgbsun
 371 with a single file system interleaved between SCSI targets 3 and 4.
 372 .IP
 373 .EX
 374 service kgbsun
 375 config w3
 376 filsys main [w<3-4>]
 377 ream main
 378 .EE
 379 .PP
 380 Initialize a file server
 381 .B kremvax
 382 with a single disk on target 0 partitioned as a cached pseudo-WORM
 383 file system with the cache on the third quarter of the drive
 384 and the pseudo-WORM on the interleave of the first, second, and
 385 fourth quarters.
 386 .IP
 387 .EX
 388 service kremvax
 389 config p(w0)50.1
 390 filsys main cp(w0)50.25f[p(w0)0.25p(w0)25.25p(w0)75.25]
 391 filsys dump o
 392 ream main
 393 .EE
 394 .PP
 395 A complete and complex example:
 396 initialize a file server
 397 .I fsb
 398 with a single SCSI disk on target 0 for a scratch file system,
 399 a cached WORM file system with cache disk on target 2 and
 400 an optical-disc jukebox on targets 4 (robotics) and 5 (one optical drive),
 401 and another cached WORM file system with cache disk on target 3
 402 and another optical-disc jukebox on a second SCSI bus at targets 3 and 4.
 403 Both jukeboxes contain 16 slots of optical discs.
 404 It has two Ethernet interfaces and can reach an SNTP server on the first one.
 405 .IP
 406 .EX
 407 service fsb
 408 config w0
 409 filsys main cw2j(w4w5)(l<0-31>)
 410 filsys dump o
 411 filsys hp40fx cw3j(w1.<3-4>.0)(l<0-31>)
 412 filsys hp40fxdump o
 413 filsys other w0
 414 ipauth 0.0.0.0
 415 ipsntp 10.9.0.3
 416 ip0 10.9.0.2
 417 ipgw0 10.9.0.3
 418 ipmask0 255.255.0.0
 419 ip1 10.0.0.2
 420 ipgw1 10.0.0.1
 421 ipmask1 255.255.0.0
 422 ream main
 423 ream hp40fx
 424 ream other
 425 end
 426 .EE
 427 .SH SOURCE
 428 .BR /sys/src/fs/port/config.c
 429 .SH "SEE ALSO
 430 Ken Thompson,
 431 ``The Plan 9 File Server''.