fossilcons 17 KB

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