replica 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341
  1. .TH REPLICA 1
  2. .SH NAME
  3. changes, pull, push, scan \- client-server replica management
  4. .SH SYNOPSIS
  5. .B replica/pull
  6. [
  7. .B -nv
  8. ]
  9. [
  10. .B -c
  11. .I name
  12. ]...
  13. [
  14. .B -s
  15. .I name
  16. ]...
  17. .I name
  18. [
  19. .I path
  20. ...
  21. ]
  22. .br
  23. .B replica/push
  24. [
  25. .B -nv
  26. ]
  27. .I name
  28. [
  29. .I path
  30. ...
  31. ]
  32. .br
  33. .B replica/changes
  34. .I name
  35. [
  36. .I path
  37. ...
  38. ]
  39. .br
  40. .B replica/scan
  41. .I name
  42. [
  43. .I path
  44. ...
  45. ]
  46. .SH DESCRIPTION
  47. These shell scripts provide a simple log-based client-server replica management.
  48. The server keeps a log of changes made to its file system,
  49. and clients synchronize by reading the log and applying these changes locally.
  50. .PP
  51. These scripts are a polished interface to the low-level tools described in
  52. .IR replica (8).
  53. See
  54. .IR replica (8)
  55. for details on the inner workings of replica management.
  56. These tools were written primarily as the fourth
  57. edition Plan 9 distribution mechanism, but they
  58. have wider applicability.
  59. For example, they could be used to synchronize one's
  60. home directory between a laptop and a central file server.
  61. .PP
  62. Replicas are described by configuration files.
  63. The
  64. .I name
  65. in all the replica commands is a configuration
  66. file. Paths that do not begin with
  67. .BR / ,
  68. .BR ./ ,
  69. or
  70. .B ../
  71. are assumed to be relative to
  72. .BR $home/lib/replica .
  73. Configuration files are described below.
  74. .PP
  75. .I Replica/scan
  76. is the only one of these programs that does not
  77. need to be run on the client.
  78. It scans the server file system for changes
  79. and appends entries for those changes into the server log.
  80. Typically it is run on a machine with a fast network
  81. connection to the server file system.
  82. .PP
  83. .I Replica/pull
  84. copies changes from the server to the client,
  85. while
  86. .I replica/push
  87. copies changes from the client to the server.
  88. (Both run on the client.)
  89. If a list of
  90. .I paths
  91. is given, only changes to those paths or their children are copied.
  92. The
  93. .B -v
  94. flag causes
  95. .I pull
  96. or
  97. .I push
  98. to print a summary of what it is doing.
  99. Each status line is of the form
  100. .ift .sp 0.5
  101. .ifn .sp
  102. \h'0.25i'
  103. .I verb
  104. .I path
  105. .I serverpath
  106. .I mode
  107. .I uid
  108. .I gid
  109. .I mtime
  110. .I length
  111. .ift .sp 0.5
  112. .ifn .sp
  113. .I Verb
  114. describes the event:
  115. addition of a file
  116. .RB ( a ),
  117. deletion of a file
  118. .RB ( d ),
  119. a change to a file's contents
  120. .RB ( c ),
  121. or a change to a file's metadata
  122. .RB ( m ).
  123. .I Path
  124. is the file path on the client;
  125. .I serverpath
  126. is the file path on the server.
  127. .IR Mode ,
  128. .IR uid ,
  129. .IR gid ,
  130. and
  131. .I mtime
  132. are the file's metadata as in the
  133. .B Dir
  134. structure (see
  135. .IR stat (5)).
  136. For deletion events, the metadata is that of the deleted file.
  137. For other events, the metadata is that after the event.
  138. The
  139. .B -n
  140. flag causes
  141. .I pull
  142. or
  143. .I push
  144. to print the summary but not actually carry out the actions.
  145. .PP
  146. .I Push
  147. and
  148. .I pull
  149. are careful to notice simultaneous changes to a file or
  150. its metadata on both client and server.
  151. Such simultaneous changes are called
  152. .IR conflicts .
  153. Here, simultaneous does not mean at the same instant
  154. but merely that both changes were carried out without knowledge
  155. of the other.
  156. For example, if a client and server both make changes to a file
  157. without an intervening
  158. .I push
  159. or
  160. .IR pull ,
  161. the next
  162. .I push
  163. or
  164. .I pull
  165. will report an update/update conflict.
  166. If a conflict is detected, both files are left the same.
  167. The
  168. .B -c
  169. flag to
  170. .I pull
  171. specifies that conflicts for paths beginning with
  172. .I name
  173. should be resolved using the client's copy,
  174. while
  175. .B -s
  176. specifies the server's copy.
  177. The
  178. .B -c
  179. and
  180. .B -s
  181. options may be repeated.
  182. .PP
  183. .I Replica/changes
  184. prints a list of local changes made on the client
  185. that have not yet been pushed to the server.
  186. It is like
  187. .I push
  188. with the
  189. .B -n
  190. flag, except that it does not check for conflicts
  191. and thus does not require the server to be available.
  192. .PP
  193. The replica configuration file is an
  194. .IR rc (1)
  195. script that must define the following functions and variables:
  196. .TP
  197. .B servermount
  198. A function that mounts the server; run on both client and server.
  199. .TP
  200. .B serverupdate
  201. A function that rescans the server for changes.
  202. Typically this command dials a CPU server known
  203. to be close to the file server and runs
  204. .I replica/scan
  205. on that well-connected machine.
  206. .TP
  207. .B serverroot
  208. The path to the root of the replicated file
  209. system on the server, as it will be in the name space
  210. after running
  211. .BR servermount .
  212. .TP
  213. .B serverlog
  214. The path to the server's change log, after running
  215. .BR servermount .
  216. .TP
  217. .B serverproto
  218. The path to the proto file describing the server's files,
  219. after running
  220. .BR servermount .
  221. Only used by
  222. .IR scan .
  223. .TP
  224. .B serverdb
  225. The path to the server's file database, after running
  226. .BR servermount .
  227. Only used by
  228. .IR scan .
  229. .TP
  230. .B clientmount
  231. A function to mount the client file system; run only on the client.
  232. .TP
  233. .B clientroot
  234. The path to the root of the replicated file system on the client,
  235. after running
  236. .BR clientmount .
  237. .TP
  238. .B clientlog
  239. The path to the client's copy of the server log file.
  240. The client log is maintained by
  241. .IR pull .
  242. .TP
  243. .B clientproto
  244. The path to the proto file describing the client's files.
  245. Only used by
  246. .IR changes .
  247. Often just a copy of
  248. .BR $serverproto .
  249. .TP
  250. .B clientdb
  251. The path to the client's file database, after running
  252. .BR clientmount .
  253. .TP
  254. .B clientexclude
  255. A (potentially empty) list of paths to exclude from
  256. synchronization. A typical use of this is to exclude
  257. the client database and log files.
  258. These paths are relative to the root of the replicated file system.
  259. .PD
  260. .PP
  261. As an example, the Plan 9 distribution replica configuration looks like:
  262. .EX
  263. fn servermount { 9fs sources; bind /n/sources/plan9 /n/dist }
  264. fn serverupdate { status='' }
  265. serverroot=/n/dist
  266. s=/n/dist/dist/replica
  267. serverlog=$s/plan9.log
  268. serverproto=$s/plan9.proto
  269. fn clientmount { 9fs kfs }
  270. clientroot=/n/kfs
  271. c=/n/kfs/dist/replica
  272. clientlog=$c/client/plan9.log
  273. clientproto=$c/plan9.proto
  274. clientdb=$c/client/plan9.db
  275. clientexclude=(dist/replica/client)
  276. .EE
  277. .PP
  278. (Since the Plan 9 developers run
  279. .I scan
  280. manually to update the log, the clients need not do anything
  281. to rescan the file system.
  282. Thus
  283. .B serverupdate
  284. simply returns successfully.)
  285. .PP
  286. The fourth edition Plan 9 distribution uses these
  287. tools to synchronize installations with the central
  288. server at Bell Labs.
  289. The replica configuration files and metadata are kept
  290. in
  291. .BR /dist/replica .
  292. To update your system, make sure you are connected
  293. to the internet and run
  294. .EX
  295. replica/pull /dist/replica/network
  296. .EE
  297. If conflicts are reported (say you have made local changes to
  298. .B /rc/bin/cpurc
  299. and
  300. .BR /rc/bin/termrc ,
  301. but only want to keep the
  302. .B cpurc
  303. changes),
  304. use
  305. .EX
  306. replica/pull -c rc/bin/cpurc -s rc/bin/termrc /dist/replica/network
  307. .EE
  308. to instruct
  309. .I pull
  310. to ignore the server's change to
  311. .BR cpurc .
  312. .PP
  313. The script
  314. .B /usr/glenda/bin/rc/pull
  315. runs
  316. .I pull
  317. with the
  318. .B -v
  319. flag and with
  320. .B /dist/replica/network
  321. inserted at the right point on the command line.
  322. Logged in as glenda, one can repeat the above example with:
  323. .EX
  324. pull -c rc/bin/cpurc -s rc/bin/cpurc
  325. .EE
  326. .PP
  327. To see a list of changes made to the local file system
  328. since installation, run
  329. .EX
  330. replica/changes /dist/replica/network
  331. .EE
  332. (Although the script is called
  333. .IR network ,
  334. since
  335. .I changes
  336. is a local-only operation, the network need not be configured.)
  337. .SH SOURCE
  338. .B /rc/bin/replica
  339. .SH SEE ALSO
  340. .IR replica (8)