fossil 9.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485
  1. .TH FOSSIL 4
  2. .SH NAME
  3. fossil \- archival file server
  4. .SH SYNOPSIS
  5. .B fossil/fossil
  6. [
  7. .B -Dt
  8. ]
  9. [
  10. .B -c
  11. .I cmd
  12. ]...
  13. [
  14. .B -f
  15. .I file
  16. ]
  17. .PP
  18. .B fossil/flchk
  19. [
  20. .B -f
  21. ]
  22. [
  23. .B -c
  24. .I ncache
  25. ]
  26. [
  27. .B -h
  28. .I host
  29. ]
  30. .I file
  31. .PP
  32. .B fossil/flfmt
  33. [
  34. .B -y
  35. ]
  36. [
  37. .B -b
  38. .I blocksize
  39. ]
  40. [
  41. .B -h
  42. .I host
  43. ]
  44. [
  45. .B -l
  46. .I label
  47. ]
  48. [
  49. .B -v
  50. .I score
  51. ]
  52. .I file
  53. .PP
  54. .B fossil/conf
  55. [
  56. .B -w
  57. ]
  58. .I file
  59. [
  60. .I config
  61. ]
  62. .PP
  63. .B fossil/last
  64. .I file
  65. .SH DESCRIPTION
  66. .I Fossil
  67. will become the main file system for Plan 9.
  68. Unlike the Plan 9 file servers of old,
  69. .I fossil
  70. is a collection of user-space programs that run on a standard Plan 9 kernel.
  71. The name of the main fossil file server at Murray Hill is
  72. .BR yoshimi .
  73. The Plan 9 distribution file server,
  74. .BR sources ,
  75. is also a fossil server.
  76. .PP
  77. .I Fossil
  78. is structured as a magnetic disk write buffer
  79. optionally backed by a Venti server for archival storage.
  80. It serves the Plan 9 protocol via TCP.
  81. A
  82. .I fossil
  83. file server conventionally presents
  84. three trees in the root directory of each file system:
  85. .BR active ,
  86. .BR archive ,
  87. and
  88. .BR snapshot .
  89. .B /active
  90. is the root of a conventional file system
  91. whose blocks are stored in a disk file.
  92. In a typical configuration, the file server periodically
  93. marks the entire file system copy-on-write, effectively
  94. taking a snapshot of the file system at that moment.
  95. This snapshot is made available in a name
  96. created from the date and time of the snapshot:
  97. .BI /snapshot/ yyyy / mmdd / hhmm \fR,
  98. where
  99. .I yyyy
  100. is the full year,
  101. .I mm
  102. is the month number,
  103. .I dd
  104. is the day number,
  105. .I hh
  106. is the hour,
  107. and
  108. .I mm
  109. is the minute.
  110. The snapshots in
  111. .B /snapshot
  112. are ephemeral: eventually they are deleted
  113. to reclaim the disk space they occupy.
  114. Long-lasting snapshots stored on a Venti server
  115. are kept in
  116. .B /archive
  117. and also named from the date (though not the time) of the snapshot:
  118. .BI /archive/ yyyy / mmdds \fR,
  119. where
  120. .IR yyyy ,
  121. .IR mm ,
  122. and
  123. .I dd
  124. are year, month, and day as before,
  125. and
  126. .I s
  127. is a sequence number if more than one
  128. archival snapshot is done in a day.
  129. For the first snapshot,
  130. .I s
  131. is null.
  132. For the subsequent snapshots,
  133. .I s
  134. is
  135. .BR .1 ,
  136. .BR .2 ,
  137. .BR .3 ,
  138. etc.
  139. The root of the main file system that is frozen
  140. for the first archival snapshot of December 15, 2002
  141. will be named
  142. .BR /archive/2002/1215/ .
  143. .PP
  144. The attach name used in
  145. .I mount
  146. (see
  147. .IR bind (1),
  148. .IR bind (2)
  149. and
  150. .IR attach (5))
  151. selects a file system to be served
  152. and optionally a subtree,
  153. in the format
  154. .IB fs \fR[\fB/ dir \fR].
  155. An empty attach name selects
  156. .BR main/active .
  157. .PP
  158. .I Fossil
  159. normally requires all users except
  160. .L none
  161. to provide authentication tickets on each
  162. .IR attach (5).
  163. To keep just anyone from connecting,
  164. .L none
  165. is only allowed to attach after another user
  166. has successfully attached on the same
  167. connection.
  168. The other user effectively acts as a chaperone
  169. for
  170. .LR none .
  171. Authentication can be disabled using the
  172. .B -A
  173. flag to
  174. .B open
  175. or
  176. .B srv
  177. (see
  178. .IR fossilcons (8)).
  179. .PP
  180. The groups called
  181. .B noworld
  182. and
  183. .B write
  184. are special on the file server.
  185. Any user belonging to
  186. .B noworld
  187. has attenuated access privileges.
  188. Specifically, when checking such a user's access to files,
  189. the file's permission bits are first ANDed
  190. with 0770 for normal files and 0771 for directories.
  191. The effect is to deny world access permissions to
  192. .B noworld
  193. users, except when walking into directories.
  194. If the
  195. .B write
  196. group exists, then the file system appears read-only
  197. to users not in the group.
  198. This is used to make the Plan 9 distribution file server
  199. .RI ( sources.cs.bell-labs.com )
  200. readable by the world but writable only to the developers.
  201. .PP
  202. .I Fossil
  203. starts a new instance of the fossil file server.
  204. It is configured mainly through console commands,
  205. documented in
  206. .IR fossilcons (8).
  207. .PP
  208. The options are:
  209. .TP
  210. .B -D
  211. Toggle the debugging flag, which is initially off.
  212. When the flag is set, information about authentication
  213. and all protocol messages are written to standard error.
  214. .TP
  215. .B -t
  216. Start a file server console on
  217. .BR /dev/cons .
  218. If this option is given,
  219. .I fossil
  220. does not fork itself into the background.
  221. .TP
  222. .BI -c " cmd
  223. Execute the console command
  224. .IR cmd .
  225. This option may be repeated to give multiple
  226. commands.
  227. Typically the only commands given on the
  228. command line are
  229. .RB `` . \fIfile \fR,''
  230. which executes a file containing commands,
  231. and
  232. .RB `` "srv -p" \fIcons \fR,''
  233. which starts a file server console on
  234. .BI /srv/ cons \fR.
  235. See
  236. .IR fossilcons (8)
  237. for more information.
  238. .TP
  239. .BI -f " file
  240. Read and execute console commands stored in the Fossil disk
  241. .IR file .
  242. .I Conf
  243. .RI ( q.v. )
  244. reads and writes the command set stored in the disk.
  245. .PD
  246. .PP
  247. .I Flchk
  248. checks the fossil file system stored in
  249. .I file
  250. for inconsistencies.
  251. .I Flchk
  252. is deprecated in favor of the console
  253. .B check
  254. command (see
  255. .IR fossilcons (8)).
  256. .I Flchk
  257. prints
  258. .I fossil
  259. console commands that may be
  260. executed to take care of
  261. bad pointers
  262. .RB ( clrp ),
  263. bad entries
  264. .RB ( clre ),
  265. bad directory entries
  266. .RB ( clri ),
  267. unreachable blocks
  268. .RB ( bfree ).
  269. Console commands are interspersed with
  270. more detailed commentary on the file system.
  271. The commands are distinguished by being prefixed with
  272. sharp signs.
  273. Note that all proposed fixes are rather drastic: offending
  274. pieces of file system are simply chopped off.
  275. .PP
  276. .I Flchk
  277. does
  278. .I not
  279. modify the file system, so it is safe to
  280. run concurrently with
  281. .IR fossil ,
  282. though in this case
  283. the list of unreachable
  284. blocks and any inconsistencies involving the active file system
  285. should be taken with a grain of salt.
  286. .PP
  287. The options are:
  288. .TP
  289. .B -f
  290. Fast mode.
  291. By default,
  292. .I flchk
  293. checks the entire file system image for consistency,
  294. which includes all the archives to Venti
  295. and can take a very long time.
  296. In fast mode,
  297. .I flchk
  298. avoids walking in Venti blocks
  299. whenever possible.
  300. .TP
  301. .BI -c " ncache
  302. Keep a cache of
  303. .I ncache
  304. (by default, 1000)
  305. file system blocks in memory during the check.
  306. .TP
  307. .BI -h " host
  308. Use
  309. .I host
  310. as the Venti server.
  311. .PD
  312. .PP
  313. .I Flfmt
  314. prepares
  315. .I file
  316. as a new fossil file system.
  317. The file system is initialized with three empty directories
  318. .BR active ,
  319. .BR archive ,
  320. and
  321. .BR snapshot ,
  322. as described above.
  323. The options are:
  324. .TP
  325. .B -y
  326. Yes mode.
  327. By default,
  328. .I flfmt
  329. will prompt for confirmation before formatting
  330. a file that already contains a fossil file system,
  331. and before formatting a file that is not served
  332. directly by a kernel device.
  333. If the
  334. .B -y
  335. flag is given, no such checks are made.
  336. .TP
  337. .BI -b " blocksize
  338. Set the file system block size (by default, 8192).
  339. .TP
  340. .BI -h " host
  341. Use
  342. .I host
  343. as the Venti server.
  344. .TP
  345. .BI -l " label
  346. Set the textual label on the file system to
  347. .IR label .
  348. The label is only a comment.
  349. .TP
  350. .BI -v " score
  351. Initialize the file system using the vac file
  352. system stored on Venti at
  353. .IR score .
  354. The score should have been generated by
  355. .I fossil
  356. rather than by
  357. .IR vac (1),
  358. so that the appropriate snapshot metadata is present.
  359. .PD
  360. .PP
  361. .I Conf
  362. reads or writes the configuration branded on the Fossil disk
  363. .IR file .
  364. By default, it reads the configuration from the disk and prints it to
  365. standard output.
  366. If the
  367. .B -w
  368. flag is given,
  369. .I conf
  370. reads a new configuration from
  371. .I config
  372. (or else from standard input)
  373. and writes it to the disk.
  374. Inside the configuration file, the argument
  375. .L *
  376. may be used to stand in for the name of the disk holding the configuration.
  377. The Plan 9 kernel boot process runs
  378. .RB `` fossil
  379. .B -f
  380. .IR disk ''
  381. to start a Fossil file server.
  382. The disk is just a convenient place to store configuration
  383. information.
  384. .PP
  385. .I Last
  386. prints the vac score that resulted after the most recent archival snapshot
  387. of the fossil in
  388. .I file.
  389. .SH EXAMPLES
  390. .PP
  391. Place the root of the archive file system on
  392. .B /n/dump
  393. and show the modified times of the MIPS C compiler
  394. over all dumps in December 2002:
  395. .IP
  396. .EX
  397. 9fs dump
  398. ls -l /n/dump/2002/12*/mips/bin/vc
  399. .EE
  400. .PP
  401. To get only one line of output for each version of the compiler:
  402. .IP
  403. .EX
  404. ls -lp /n/dump/2002/12*/mips/bin/vc | uniq
  405. .EE
  406. .ne 14
  407. .PP
  408. Initialize a new file system, start the server with permission
  409. checking turned off, create a users file, and mount the server:
  410. .IP
  411. .EX
  412. fossil/flfmt /dev/sdC0/fossil
  413. fossil/conf -w /dev/sdC0/fossil <<EOF
  414. fsys main config /dev/sdC0/fossil
  415. fsys main open -AWP
  416. fsys main
  417. create /active/adm adm sys d775
  418. create /active/adm/users adm sys 664
  419. users -w
  420. srv -p fscons
  421. srv fossil
  422. EOF
  423. fossil/fossil -f /dev/sdC0/fossil
  424. mount /srv/fossil /n/fossil
  425. .EE
  426. .LP
  427. See the discussion of the
  428. .B users
  429. and
  430. .B uname
  431. commands in
  432. .IR fossilcons (8)
  433. for more about the user table.
  434. .ne 3
  435. .PP
  436. Perhaps because the disk has been corrupted or replaced,
  437. format a new file system using the last archive score printed
  438. on the console:
  439. .IP
  440. .EX
  441. fossil/flfmt -v b9b3...5559 /dev/sdC0/fossil
  442. .EE
  443. .LP
  444. Note that while
  445. .B /snapshot
  446. will be lost,
  447. .B /active
  448. and
  449. .B /archive
  450. will be restored to their contents at the time of the
  451. last archival snapshot.
  452. .ne 3
  453. .PP
  454. Blindly accept the changes prescribed by
  455. .I flchk
  456. (not recommended):
  457. .IP
  458. .EX
  459. fossil/flchk /dev/sdC0/fossil | sed -n 's/^# //p' >>/srv/fscons
  460. .EE
  461. .LP
  462. A better strategy is to vet the output,
  463. filter out any suggestions you're not comfortable with,
  464. and then use the
  465. .I sed
  466. command to prepare the script.
  467. .SH SOURCE
  468. .B /sys/src/cmd/fossil
  469. .SH SEE ALSO
  470. .IR yesterday (1),
  471. .IR fs (3),
  472. .IR fs (4),
  473. .IR srv (4),
  474. .IR fossilcons (8),
  475. .IR venti (8)
  476. .SH BUGS
  477. It is likely that the disk format (but not the Venti format)
  478. will change in the future, to make the disk a full cache
  479. rather than just a write buffer.
  480. Changing to the new format will require reformatting
  481. the disk as in the example above,
  482. but note that this will preserve most of the file system
  483. (all but
  484. .BR /snapshot )
  485. with little effort.