replica 6.5 KB

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