fossil 8.5 KB

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