fossil 9.0 KB

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