fossilcons 13 KB

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