1
0

fossilcons 18 KB

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