fossilcons 14 KB

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