fossilcons 18 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180
  1. .TH FOSSILCONS 8
  2. .SH NAME
  3. fossilcons \- fossil console commands
  4. .SH SYNOPSIS
  5. .B
  6. con /srv/fscons
  7. .PP
  8. .PD 0.1
  9. .B .
  10. .I file
  11. .PP
  12. .B 9p
  13. .I T-message
  14. ...
  15. .PP
  16. .B bind
  17. [
  18. .B -b|-a|-c|-bc|-ac
  19. ]
  20. .I new
  21. .I old
  22. .PP
  23. .B dflag
  24. .PP
  25. .B echo
  26. [
  27. .B -n
  28. ]
  29. [
  30. .I arg
  31. ...
  32. ]
  33. .PP
  34. .B listen
  35. [
  36. .B -INd
  37. ]
  38. [
  39. .I address
  40. ]
  41. .PP
  42. .B msg
  43. [
  44. .B -m
  45. .I nmsg
  46. ]
  47. [
  48. .B -p
  49. .I nproc
  50. ]
  51. .PP
  52. .B printconfig
  53. .PP
  54. .B srv
  55. [
  56. .B -APWdp
  57. ]
  58. .I name
  59. .PP
  60. .B uname
  61. .I name
  62. [
  63. .I id
  64. |
  65. .BI : id
  66. |
  67. .BI % newname
  68. |
  69. .BI = leader
  70. |
  71. .BI + member
  72. |
  73. .BI - member
  74. ]
  75. .PP
  76. .B users
  77. [
  78. .B -d
  79. |
  80. .B -r
  81. .I file
  82. ]
  83. [
  84. .B -w
  85. ]
  86. .PP
  87. .B who
  88. .sp
  89. .PP
  90. .B fsys
  91. .I name
  92. .PP
  93. .B fsys
  94. .I name
  95. .B config
  96. .I device
  97. .PP
  98. .B fsys
  99. .I name
  100. .B venti
  101. [
  102. .I host
  103. ]
  104. .PP
  105. .B fsys
  106. .I name
  107. .B open
  108. [
  109. .B -APVWr
  110. ]
  111. [
  112. .B -c
  113. .I ncache
  114. ]
  115. .PP
  116. [
  117. .B fsys
  118. .I name
  119. ]
  120. .B close
  121. .PP
  122. .B fsys
  123. .I name
  124. .B unconfig
  125. .sp
  126. .PP
  127. [
  128. .B fsys
  129. .I name
  130. ]
  131. .B bfree
  132. .I addr
  133. .PP
  134. [
  135. .B fsys
  136. .I name
  137. ]
  138. .B block
  139. .I addr
  140. .I offset
  141. [
  142. .I count
  143. [
  144. .I data
  145. ]]
  146. .PP
  147. .in +1i
  148. .ti -1i
  149. [
  150. .B fsys
  151. .I name
  152. ]
  153. .B check
  154. [
  155. .B pblock
  156. ] [
  157. .B pdir
  158. ] [
  159. .B pfile
  160. ] [
  161. .B bclose
  162. ] [
  163. .B clri
  164. ] [
  165. .B clre
  166. ] [
  167. .B clrp
  168. ] [
  169. .B fix
  170. ] [
  171. .B venti
  172. ] [
  173. .B snapshot
  174. ]
  175. .PP
  176. [
  177. .B fsys
  178. .I name
  179. ]
  180. .B clre
  181. .I addr
  182. .I offsets
  183. \&...
  184. .PP
  185. [
  186. .B fsys
  187. .I name
  188. ]
  189. .B clri
  190. .I files
  191. \&...
  192. .PP
  193. [
  194. .B fsys
  195. .I name
  196. ]
  197. .B clrp
  198. .I addr
  199. .I offset
  200. \&...
  201. .PP
  202. [
  203. .B fsys
  204. .I name
  205. ]
  206. .B create
  207. .I path
  208. .I uid
  209. .I gid
  210. .I perm
  211. .PP
  212. [
  213. .B fsys
  214. .I name
  215. ]
  216. .B df
  217. .PP
  218. [
  219. .B fsys
  220. .I name
  221. ]
  222. .B epoch
  223. [[
  224. .B -ry
  225. ]
  226. .I n
  227. ]
  228. .PP
  229. [
  230. .B fsys
  231. .I name
  232. ]
  233. .B halt
  234. .PP
  235. [
  236. .B fsys
  237. .I name
  238. ]
  239. .B label
  240. .I addr
  241. [
  242. .I type
  243. .I state
  244. .I epoch
  245. .I epochclose
  246. .I tag
  247. ]
  248. .PP
  249. [
  250. .B fsys
  251. .I name
  252. ]
  253. .B remove
  254. .I files
  255. \&...
  256. .PP
  257. [
  258. .B fsys
  259. .I name
  260. ]
  261. .B snap
  262. [
  263. .B -a
  264. ]
  265. [
  266. .B -s
  267. .I src
  268. ]
  269. [
  270. .B -d
  271. .I dst
  272. ]
  273. .PP
  274. [
  275. .B fsys
  276. .I name
  277. ]
  278. .B snapclean
  279. [
  280. .I timeout
  281. ]
  282. .PP
  283. [
  284. .B fsys
  285. .I name
  286. ]
  287. .B snaptime
  288. [
  289. .B -a
  290. .I hhmm
  291. ]
  292. [
  293. .B -s
  294. .I interval
  295. ]
  296. [
  297. .B -t
  298. .I timeout
  299. ]
  300. .PP
  301. [
  302. .B fsys
  303. .I name
  304. ]
  305. .B stat
  306. .IR files ...
  307. .PP
  308. [
  309. .B fsys
  310. .I name
  311. ]
  312. .B sync
  313. .PP
  314. [
  315. .B fsys
  316. .I name
  317. ]
  318. .B unhalt
  319. .PP
  320. [
  321. .B fsys
  322. .I name
  323. ]
  324. .B vac
  325. .I dir
  326. .PP
  327. [
  328. .B fsys
  329. .I name
  330. ]
  331. .B wstat
  332. .I file
  333. .I elem
  334. .I uid
  335. .I gid
  336. .I perm
  337. .I length
  338. .SH DESCRIPTION
  339. These are configuration and maintenance commands
  340. executed at the console of a
  341. .IR fossil (4)
  342. file server.
  343. The commands are split into three groups above:
  344. file server configuration,
  345. file system configuration,
  346. and file system maintenance.
  347. This manual page is split in the same way.
  348. .SS File server configuration
  349. .PP
  350. The
  351. dot
  352. .RI ( . )
  353. command
  354. reads
  355. .IR file ,
  356. treating each line as a command to be executed.
  357. Blank lines and lines beginning with a
  358. .L #
  359. character are ignored.
  360. Errors during execution are printed but do not stop the script.
  361. Note that
  362. .I file
  363. is a file in the name space in which
  364. .I fossil
  365. was started,
  366. .I not
  367. a file in any file system served by
  368. .IR fossil .
  369. .PP
  370. .I 9p
  371. executes a 9P transaction; the arguments
  372. are in the same format used by
  373. .IR 9pcon (8).
  374. .PP
  375. .I Bind
  376. behaves similarly to
  377. .IR bind (1).
  378. It is useful when fossil
  379. is started without devices it needs configured
  380. into its namespace.
  381. .PP
  382. .I Dflag
  383. toggles the debug flag and prints the new setting.
  384. When the debug flag is set, all protocol messages
  385. and information about authentication is printed to
  386. standard error.
  387. .PP
  388. .I Echo
  389. behaves identically to
  390. .IR echo (1),
  391. writing to the console.
  392. .PP
  393. .I Listen
  394. manages the network addresses at which
  395. fossil is listening.
  396. With no arguments,
  397. .I listen
  398. prints the current list of addresses and their network directories.
  399. With one argument, listen
  400. .I address
  401. starts a new listener at
  402. .IR address ;
  403. the
  404. .B -d
  405. flag causes
  406. .I listen
  407. to remove the listener
  408. at the given address.
  409. By default, the user
  410. .I none
  411. is only allowed to attach on a connection after
  412. at least one other user has successfully attached.
  413. The
  414. .B -N
  415. flag allows connections from
  416. .I none
  417. at any time.
  418. The
  419. .B -I
  420. flag causes
  421. .I fossil
  422. to check the IP address of incoming connections
  423. against
  424. .BR /mnt/ipok ,
  425. rejecting attaches from disallowed addresses.
  426. This mechanism is not intended for general use.
  427. The server
  428. .I sources.cs.bell-labs.com
  429. uses it to comply with U.S. crytography
  430. export regulations.
  431. .PP
  432. .I Msg
  433. prints the maximum internal 9P message queue size
  434. and the maximum number of 9P processes to
  435. allocate for serving the queue.
  436. The
  437. .B -m
  438. and
  439. .B -p
  440. options set the two variables.
  441. .PP
  442. .I Printconfig
  443. prints the
  444. .B config
  445. line for each configured file system
  446. and prints the
  447. .B venti
  448. line, if any, used to configure this file server.
  449. .PP
  450. .I Srv
  451. behaves like listen but uses
  452. .BI /srv/ name
  453. rather than a network address.
  454. With the
  455. .B -p
  456. flag,
  457. .I srv
  458. edits a list of console services rather than 9P services.
  459. With no arguments,
  460. .I srv
  461. prints the current list of services.
  462. With one argument, srv
  463. .I name
  464. starts a new service at
  465. .IR /srv/name ;
  466. the
  467. .B -d
  468. flag causes
  469. .I srv
  470. to remove the named service.
  471. See the
  472. .I [fsys] open
  473. command below for a description of the
  474. .B -APW
  475. options.
  476. .PP
  477. .I Uname
  478. manipulates entries in the user table.
  479. There is no distinction between users and groups:
  480. a user is a group with one member.
  481. For each user, the user table records:
  482. .TP
  483. .I id
  484. the string used to represent this user in the on-disk structures
  485. .TP
  486. .I name
  487. the string used to represent this user in the 9P protocol
  488. .TP
  489. .I leader
  490. the group's leader (see
  491. .IR stat (5)
  492. for a description of the special privileges held by a group leader)
  493. .TP
  494. .I members
  495. a comma-separated list of members in this group
  496. .PP
  497. The
  498. .I id
  499. and
  500. .I name
  501. are usually the same string, but need not be.
  502. Once an
  503. .I id
  504. is used in file system structures archived to Venti,
  505. it is impossible to change those disk structures,
  506. and thus impossible to rename the
  507. .IR id .
  508. The translation from
  509. .I name
  510. to
  511. .I id
  512. allows the appearance of renaming the user even
  513. though the on-disk structures still record the old name.
  514. (In a conventional Unix file system, the
  515. .I id
  516. is stored as a small integer rather than a string.)
  517. .I Leader
  518. and
  519. .I members
  520. are names, not ids.
  521. .PP
  522. The first argument to
  523. .I uname
  524. is the
  525. .I name
  526. of a user.
  527. The second argument is a verb, one of:
  528. .TP
  529. .I id
  530. create a user with name
  531. .RI ` name '
  532. and id
  533. .RI ` id ;'
  534. also create a home directory
  535. .BI /active/usr/ uname \fR
  536. .TP
  537. .BI : id
  538. create a user with name
  539. .RI ` name '
  540. and id
  541. .RI ` id ,'
  542. but do not create a home directory
  543. .TP
  544. .BI % newname
  545. rename user
  546. .RI ` name '
  547. to
  548. .RI ` newname ,'
  549. throughout the user table
  550. .TP
  551. .BI = leader
  552. set
  553. .IR name 's
  554. group leader
  555. to
  556. .IR leader .
  557. .TP
  558. .BI =
  559. remove
  560. .IR name 's
  561. group leader; then all members will be
  562. considered leaders
  563. .TP
  564. .BI + member
  565. add
  566. .I member
  567. to
  568. .IR name 's
  569. list of members
  570. .TP
  571. .BI - member
  572. remove
  573. .I member
  574. from
  575. .IR name 's
  576. list of members
  577. .LP
  578. If the verb is omitted, the entire entry for
  579. .I name
  580. is printed, in the form
  581. `\fIid\fL:\fIname\fL:\fIleader\fL:\fImembers\fR.'
  582. .LP
  583. The end of this manual page gives examples.
  584. .PP
  585. .I Users
  586. manipulates the user table.
  587. The user table is a list of lines in the form printed
  588. by the
  589. .I uname
  590. command.
  591. The
  592. .B -d
  593. flag resets the user table with the default:
  594. .IP
  595. .EX
  596. adm:adm:adm:sys
  597. none:none::
  598. noworld:noworld::
  599. sys:sys::
  600. glenda:glenda:glenda:
  601. .EE
  602. .PP
  603. Except
  604. .BR glenda ,
  605. these users are mandatory: they must appear in all user
  606. files and cannot be renamed.
  607. .PP
  608. The
  609. .B -r
  610. flag reads a user table from the named
  611. .I file
  612. in file system
  613. .BR main .
  614. The
  615. .B -w
  616. flag writes the table to
  617. .B /active/adm/users
  618. on the file system
  619. .BR main .
  620. .B /active/adm
  621. and
  622. .B /active/adm/users
  623. will be created if they do not exist.
  624. .PP
  625. .I Users
  626. .B -r
  627. .B /active/adm/users
  628. is automatically executed when the file system
  629. .B main
  630. is opened.
  631. .PP
  632. .I Users
  633. .B -w
  634. is automatically executed after each change to the user
  635. table by the
  636. .I uname
  637. command.
  638. .PP
  639. .I Who
  640. prints a list of users attached to each active connection.
  641. .SS File system configuration
  642. .I Fsys
  643. sets the current file system to
  644. .IR name ,
  645. which must be configured and open (q.v.).
  646. The current file system name is
  647. displayed as the file server prompt.
  648. The special name
  649. .B all
  650. stands for all file systems;
  651. commands applied to
  652. .B all
  653. are applied to each file system in turn.
  654. The commands
  655. .BR config ,
  656. .BR open ,
  657. .BR venti ,
  658. and
  659. .B close
  660. cannot be applied to
  661. .BR all .
  662. .PP
  663. .I Fsys
  664. takes as an optional argument
  665. (after
  666. .BR name )
  667. a command to execute on the named file system.
  668. Most commands require that the named file system
  669. be configured and open; these commands can be invoked
  670. without the
  671. .BI fsys " name
  672. prefix, in which case the current file system is used.
  673. A few commands
  674. .RB ( config ,
  675. .BR open ,
  676. and
  677. .BR unconfig )
  678. operate on unopened file systems; they require the prefix.
  679. .PP
  680. .I Config
  681. creates a new file system named
  682. .I name
  683. using disk file
  684. .I device .
  685. This just adds an entry to fossil's internal table.
  686. .PP
  687. .I Venti
  688. establishes a connection to the Venti server
  689. .I host
  690. (by default, the environment variable
  691. .B $venti
  692. or the network variable
  693. .BR $venti )
  694. for use by the named file system.
  695. If no
  696. .I venti
  697. command is issued before
  698. .IR open ,
  699. the default Venti server will be used.
  700. If the file system is open,
  701. and was not opened with the
  702. .B -V
  703. flag,
  704. the command redials the Venti server.
  705. This can be used to reestablish broken connections.
  706. It is not a good idea to use the command to switch
  707. between Venti servers, since Fossil does not keep track
  708. of which blocks are stored on which servers.
  709. .PP
  710. .I Open
  711. opens the file system, reading the
  712. root and super blocks and allocating an in-memory
  713. cache for disk and Venti blocks.
  714. The options are:
  715. .TP
  716. .B -A
  717. run with no authentication
  718. .TP
  719. .B -P
  720. run with no permission checking
  721. .TP
  722. .B -V
  723. do not attempt to connect to a Venti server
  724. .TP
  725. .B -W
  726. allow wstat to make arbitrary changes to the user and group fields
  727. .TP
  728. .B -r
  729. open the file system read-only
  730. .TP
  731. .BI -c " ncache
  732. allocate an in-memory cache of
  733. .I ncache
  734. (by default, 1000)
  735. blocks
  736. .PP
  737. The
  738. .I -APW
  739. settings can be overridden on a per-connection basis
  740. by the
  741. .I srv
  742. command above.
  743. .PP
  744. .I Close
  745. flushes all dirty file system blocks to disk
  746. and then closes the device file.
  747. .PP
  748. .I Unconfig
  749. removes the named file system (which must be closed)
  750. from fossil's internal table.
  751. .SS File system maintenance
  752. .I Bfree
  753. marks the block at disk address
  754. .I addr
  755. as available for allocation.
  756. Before doing so, it prints a
  757. .I label
  758. command (q.v.)
  759. that can be used to restore the block to its previous state.
  760. .PP
  761. .I Block
  762. displays (in hexadecimal)
  763. the contents of the block at disk address
  764. .IR addr ,
  765. starting at
  766. .I offset
  767. and continuing for
  768. .I count
  769. bytes or until the end of the block.
  770. If
  771. .I data
  772. (also hexadecimal)
  773. is given, the contents in that range are
  774. replaced with data.
  775. When writing to a block,
  776. .I block
  777. prints the old and new contents,
  778. so that the change is easily undone.
  779. Editing blocks is discouraged.
  780. .PP
  781. .I Clre
  782. zeros an entry from a disk block.
  783. Before doing so, it prints a
  784. .I block
  785. command that can be used
  786. to restore the entry.
  787. .PP
  788. .I Clri
  789. removes the internal directory entry
  790. and abandons storage associated with
  791. .IR files .
  792. It ignores the usual rules for sanity, such as checking against
  793. removing a non-empty directory.
  794. A subsequent
  795. .I flchk
  796. (see
  797. .IR fossil (4))
  798. will identify the abandoned storage so it can be reclaimed with
  799. .I bfree
  800. commands.
  801. .PP
  802. .I Clrp
  803. zeros a pointer in a disk block.
  804. Before doing so, it prints a
  805. .I block
  806. command that can be used to restore the entry.
  807. .PP
  808. .I Check
  809. checks the file system for various inconsistencies.
  810. If the file system is not already halted, it is halted for
  811. the duration of the check.
  812. If the archiver is currently sending a snapshot to Venti,
  813. the check will refuse to run; the only recourse is to wait
  814. for the archiver to finish.
  815. .PP
  816. A list of keyword options control the check.
  817. The
  818. .BR pblock ,
  819. .BR pdir ,
  820. and
  821. .B pfile
  822. options cause
  823. .I check
  824. to print the name of each block, directory, or file encountered.
  825. .PP
  826. By default,
  827. .I check
  828. reports errors but does not fix them.
  829. The
  830. .BR bclose ,
  831. .BR clri ,
  832. .BR clre ,
  833. and
  834. .B clrp
  835. options specify correcting actions that may be taken:
  836. closing leaked blocks, clearing bad file directory entries,
  837. clearing bad pointers, and clearing bad entries.
  838. The
  839. .B fix
  840. option enables all of these; it is equivalent to
  841. .B bclose
  842. .B clri
  843. .B clre
  844. .BR clrp .
  845. .PP
  846. By default,
  847. .I check
  848. scans the portion of the active file system held in the write buffer,
  849. avoiding blocks stored on Venti or used only in snapshots.
  850. The
  851. .B venti
  852. option causes
  853. .I check
  854. to scan the portion of the file system stored on Venti,
  855. and the
  856. .B snapshot
  857. option causes
  858. .I check
  859. to scan old snapshots.
  860. Specifying
  861. .B snapshot
  862. causes
  863. .I check
  864. to take a long time;
  865. specifying
  866. .B venti
  867. or
  868. (worse)
  869. .B venti
  870. .B snapshot
  871. causes
  872. .I check
  873. to take a very long time.
  874. .PP
  875. .I Create
  876. creates a file on the current file system.
  877. .I Uid
  878. and
  879. .I gid
  880. are uids
  881. .RI ( not
  882. unames;
  883. see the discussion above, in the description
  884. of the
  885. .I uname
  886. command).
  887. .I Perm
  888. is the low 9 bits of the permission mode of the file,
  889. in octal.
  890. The
  891. .BR a ,
  892. .BR d ,
  893. and
  894. .B l
  895. mode prefixes
  896. set the append-only, directory, and lock bits.
  897. The
  898. .I perm
  899. is formatted as described in the
  900. .I stat
  901. command;
  902. creating files or directories with the
  903. .BR snapshot (s)
  904. bit set is not allowed.
  905. .PP
  906. .I Df
  907. prints the amount of used disk space in the write buffer.
  908. .PP
  909. .I Epoch
  910. sets the low file system epoch.
  911. Snapshots in the file system are given increasing epoch numbers.
  912. The file system maintains a low and a high epoch number,
  913. and only allows access to snapshots in that range.
  914. The low epoch number can be moved forward to discard old snapshots
  915. and reclaim the disk space they occupy.
  916. (The high epoch number is always the epoch of the currently
  917. active file system.)
  918. .PP
  919. With no argument
  920. .I epoch
  921. reports the current low and high epoch numbers.
  922. The command
  923. ``\fLepoch\fI n''\fR
  924. is used to propose changing the low epoch to
  925. .IR n .
  926. In response,
  927. .I fossil
  928. scans
  929. .B /archive
  930. and
  931. .B /snapshot
  932. for snapshots that would be discarded, printing their
  933. epoch numbers and the
  934. .I clri
  935. commands necessary to remove them.
  936. The epoch is changed only if no such paths are found.
  937. The usual sequence of commands is (1) run epoch to
  938. print the snapshots and their epochs, (2) clri some snapshots,
  939. (3) run epoch again.
  940. If the file system is completely full (there are no free blocks),
  941. .I clri
  942. may fail because it needs to allocate blocks.
  943. For this situation,
  944. the
  945. .B -y
  946. flag to epoch forces the epoch change even when
  947. it means discarding currently accessible snapshots.
  948. Note that when there are still snapshots in
  949. .BR /archive ,
  950. the archiver should take care
  951. of those snapshots (moving the blocks from disk to Venti)
  952. if you give it more time.
  953. .PP
  954. The
  955. .B -r
  956. flag to epoch causes it to remove any now-inaccessible
  957. snapshot directories once it has changed the epoch.
  958. This flag only makes sense in conjunction with the
  959. .B -y
  960. flag.
  961. .PP
  962. .I Epoch
  963. is a very low-level way to retire snapshots.
  964. The preferred way is by setting an automatic timer
  965. with
  966. .IR snaptime .
  967. .PP
  968. .I Halt
  969. suspends all file system activity;
  970. .I unhalt
  971. resumes activity.
  972. .PP
  973. .I Label
  974. displays and edits the label associated with a block.
  975. When editing, a parameter of
  976. .B -
  977. means leave that field unchanged.
  978. Editing labels is discouraged.
  979. .PP
  980. .I Remove
  981. removes
  982. .IR files .
  983. .PP
  984. .I Snap
  985. takes a temporary snapshot of the current file system,
  986. recording it in
  987. .BI /snapshot/ yyyy / mmdd / hhmm \fR,
  988. as described in
  989. .IR fossil (4).
  990. The
  991. .B -a
  992. flag causes
  993. .I snap
  994. to take an archival snapshot, recording it in
  995. .BI /archive/ yyyy / mmdd \fR,
  996. also described in
  997. .IR fossil (4).
  998. By default the snapshot is taken of
  999. .BR /active ,
  1000. the root of the active file system.
  1001. The
  1002. .B -s
  1003. flag specifies a different source path.
  1004. The
  1005. .B -d
  1006. flag specifies a different destination path.
  1007. These two flags are useful together for moving snapshots into
  1008. the archive tree.
  1009. .PP
  1010. .I Snapclean
  1011. immediately discards all snapshots that are more than
  1012. .I timeout
  1013. minutes old.
  1014. The default timeout is the one set by the
  1015. .I snaptime
  1016. command.
  1017. The discarding is a one-time event rather than
  1018. a recurring event as in
  1019. .IR snaptime .
  1020. .PP
  1021. .I Snaptime
  1022. displays and edits the times at which snapshots are automatically
  1023. taken.
  1024. An archival snapshot is taken once a day, at
  1025. .IR hhmm ,
  1026. while temporary snapshots are taken at multiples of
  1027. .I interval
  1028. minutes.
  1029. Temporary snapshots are discarded after they are
  1030. .I timeout
  1031. minutes old.
  1032. The snapshot cleanup runs every
  1033. .I timeout
  1034. minutes or once a day, whichever is more frequent,
  1035. so snapshots may grow to an age of almost twice the timeout
  1036. before actually being discarded.
  1037. With no arguments,
  1038. .I snaptime
  1039. prints the current snapshot times.
  1040. The
  1041. .B -a
  1042. and
  1043. .B -s
  1044. options set the archive and snapshot times.
  1045. An
  1046. .I hhmm
  1047. or
  1048. .I interval
  1049. of
  1050. .L none
  1051. can be used to disable that kind of automatic snapshot.
  1052. The
  1053. .B -t
  1054. option sets the snapshot timeout.
  1055. If
  1056. .I timeout
  1057. is
  1058. .LR none ,
  1059. temporary snapshots are not automatically discarded.
  1060. By default, all three times are set to
  1061. .LR none .
  1062. .PP
  1063. .I Stat
  1064. displays metadata for each of the named
  1065. .IR files ,
  1066. in the form:
  1067. .IP
  1068. .EX
  1069. stat \fIfile elem uid gid perm length
  1070. .EE
  1071. .LP
  1072. (Replacing
  1073. .B stat
  1074. with
  1075. .B wstat
  1076. yields a valid command.)
  1077. The
  1078. .I perm
  1079. is an octal number less than or equal to 777,
  1080. prefixed with any of the following letters
  1081. to indicate additional bits.
  1082. .IP
  1083. .EX
  1084. .ta +4n
  1085. a \fRappend only
  1086. d \fRdirectory
  1087. l \fRexclusive use
  1088. s \fRis the root of a snapshot
  1089. t \fRtemporary bit
  1090. A \fRMS-DOS archive bit
  1091. G \fRsetgid
  1092. H \fRMS-DOS hidden bit
  1093. L \fRsymbolic link
  1094. S \fRMS-DOS system bit
  1095. U \fRsetuid
  1096. Y \fRsticky
  1097. .EE
  1098. .PP
  1099. The bits denoted by capital letters are included
  1100. to support non-Plan 9 systems.
  1101. They are not made visible by the 9P protocol.
  1102. .PP
  1103. .I Sync
  1104. writes dirty blocks in memory to the disk.
  1105. .PP
  1106. .I Vac
  1107. prints the Venti score for a
  1108. .IR vac (1)
  1109. archive containing the tree rooted
  1110. at
  1111. .IR dir ,
  1112. which must already be archived to Venti
  1113. (typically
  1114. .IR dir
  1115. is a directory in the
  1116. .B /archive
  1117. tree).
  1118. .PP
  1119. .I Wstat
  1120. changes the metadata of the named
  1121. .IR file .
  1122. Specifying
  1123. .B -
  1124. for any of the fields means ``don't change.''
  1125. Attempts to change the
  1126. .B d
  1127. or
  1128. .B s
  1129. bits in the
  1130. .I perm
  1131. are silently ignored.
  1132. .SH EXAMPLES
  1133. .IR Sources ,
  1134. the Plan 9 distribution file server,
  1135. uses the following configuration file:
  1136. .IP
  1137. .EX
  1138. srv -p fscons.sources
  1139. srv -p fscons.sources.adduserd
  1140. srv sources
  1141. fsys main config /dev/sdC0/fossil.outside
  1142. fsys main open -c 25600
  1143. fsys main
  1144. users /active/adm/users
  1145. listen tcp!*!564
  1146. msg -m 40 -p 10
  1147. snaptime -a 0000 -s 15
  1148. .EE
  1149. .LP
  1150. The second console is used by the daemon
  1151. that creates new accounts.
  1152. .PP
  1153. To add a new user with
  1154. .I name
  1155. and
  1156. .I id
  1157. .B rob
  1158. and create his home directory:
  1159. .IP
  1160. .EX
  1161. uname rob rob
  1162. .EE
  1163. .PP
  1164. To create a new group
  1165. .B sys
  1166. (with no home directory)
  1167. and add
  1168. .B rob
  1169. to it:
  1170. .IP
  1171. .EX
  1172. uname sys :sys
  1173. uname sys +rob
  1174. .EE
  1175. .PP
  1176. To save an old (but not yet discarded) snapshot into the archive tree:
  1177. .IP
  1178. .EX
  1179. snap -a -s /snapshot/2003/1220/0700 -d /archive/2003/1220
  1180. .EE