changeset 14:5f95af14b51c

author Jeff Hammel <>
date Sun, 24 Mar 2013 12:46:35 -0700
parents 584a847d2491
children 743c920bc041
files silvermirror-whitepaper.txt
diffstat 1 files changed, 35 insertions(+), 24 deletions(-) [+]
line wrap: on
line diff
--- a/silvermirror-whitepaper.txt
+++ b/silvermirror-whitepaper.txt
@@ -1,39 +1,40 @@
-SilverMirror Whitepaper
+= SilverMirror Whitepaper =
 It is necessary to maintain parallel directory structures of various  
 resources across an arbitrary number of computers. The traditional  
 approach is the central server model, where files live in one  
 canonical location and the network is used to give access to the data.  
 However, this model has deficiencies, chiefly among them that if the  
 server goes down or must be moved a considerable amount of effort must  
 be extended to set up a new central server.
 Distributed version control, often of nominal use (in the case where a  
 canonical trunk exists) is ideally suited to provide mirroring of  
 desired resources across computers.
+== Implementation ==
-A front end to a DVCS - most likely mercurial but potentially bzr -  
+A front end to a DVCS or other - unison is completed,
+mercurial is up next -
 will be written to keep resources in sync across an arbitrary number  
 of computers. The front end, called SilverMirror, may be used to push  
 or pull changes to resources. Optionally, a daemon will monitor  
 changes to resources and push or pull changes at desired intervals.
 The use should be as natural as possible and require no interaction  
 for everday tasks. A resource consists of a directory and all  
 subdirectories and their contents. Once a resource is denoted as  
 versioned, any change to the resource's directory structure should be  
 mirrored across machines without user intervention. Files matching a  
 pattern may be ignored, either globally or on a per resource basis,  
 for the purpose of versioning.
+== Configuration ==
 SilverMirror is configured via an INI file containing a section for  
 each resource and a section for application configuration.
 The main section, denoted [::SilverMirror::], has the following options:
   * directory: base directory for SilverMirror. The SilverMirror  
 configuration is stored in ${directory}/.silvermirror . If omitted,  
@@ -56,56 +57,56 @@ section.
   * conflict: handler to resolve conflict.
   * hosts: hosts to push/pull from
 In order to ensure coherency among resources, all relevant  
 configuration options must be synced prior to push/pull transactions.
-Default Configuration:
+Default Configuration::
-conflict = ClobberRemote
+  [::SilverMirror::]
+  conflict = ClobberRemote
-Example of a more complex configuration:
+Example of a more complex configuration::
-conflict.push = ClobberRemote
-conflict.pull = ClobberLocal
+  [::SilverMirror::]
+  conflict.push = ClobberRemote
+  conflict.pull = ClobberLocal
+== Push ==
 Push changes to remote resources. When resources are pushed, first  
 changes are pulled from each remote host in turn, conflicts between  
 local and remote changes are resolved (see Behavior on Conflicts),  
 then local modifications are pushed. This is done to keep the  
 resources in sync.
 When new files are added to the resource they are automatically added  
 to the hg repository. When resource files are edited the changes are  
 pushed to the repository. When a conflict occurs between local  
 resources and remote resources, the conflict handler is used.
+== Pull ==
 Get changes to the cloud filesystem resources. If no host is  
 specified, pull changes from all known + accessible hosts.
-Namespaced Resources
+== Namespaced Resources ==
 It is possible to maintain versioning of a subdirectory within a  
-directory = /path/to/docs
+  [docs]
+  directory = /path/to/docs
+  [docs:private]
 This configuration snippet describes a resource, [docs:private],  
 namespaced within the [docs] resource. [docs:private] inherits  
 configuration and behavior from [docs] but may be dealt with  
 separately. For example, some computers in the cloud may not have  
 [docs:private] specified in their configuration and so will not get a  
 copy of it upon pulling. A common use case is specifying a  
 subdirectory to be omitted with the ignore option in the configuration  
@@ -115,41 +116,41 @@ namespaced resource.
 In the above example, because the directory option was not specified  
 in the [docs:private] section, the path to [docs:private] is taken  
 from its namespace (private) and the directory of its parent resource.  
 So its base directory  is /path/to/docs/private . If a relative path  
 was specified in the directory option of the [docs:private] section,  
 it would be joined with the base directory of [docs].
-Behavior on Conflicts
+== Behavior on Conflicts ==
 Conflict handlers are set via setuptools entry points. Several  
 conflict handlers are provided with SilverMirror:
   * ClobberLocal: replace local changes with changes from remote files
   * ClobberRemote: replace remote file changes with changes from local  
   * Edit: invoke an editor (default: $EDITOR) to interactively resolve  
 the conflicts
 The conflict handler may also be specified from the command line:
 silvermirror push -d ClobberRemote
-Command Line Usage
+== Command Line Usage ==
 silvermirror [push|pull] [resource] [options]
 In the simplest invocation, SilverMirror is used with no command line  
+  silvermirror
 This pushes changes of the resource as determined by the current  
 working directory after pulling outstanding changes from all  
 applicable remote computers and invoking the conflict handler for  
 push. If the current working directory is not within a resource, all  
 resources will be pushed.
 Finer control is obtained by specifying command line arguments:
@@ -186,31 +187,36 @@ specified) for all available conflict ha
 Behavior Respecting Versioned Directories
 SilverMirror does not desire to duplicate versioning on directories  
 already under version control (svn, bzr, hg). These resources are  
 automatically ignore. In a future implementation, these resources  
 would optionally be checked out or updated upon a pull.
-Automatic Syncronization
+== Automatic Syncronization ==
 SilverMirror includes a script that will automatically invoke  
 syncronizing the resources in a specified period of time. This daemon,  
 called silvermirrord, is invoked from the command line with options  
 parallel to the silvermirror program. One additional option, -s, tells  
 how many seconds between syncs. Upon invocation, this program puts  
 itself in the background and performs the desired sync every number of  
 seconds specified. It is important that the conflict handler specified  
 is noninteractive, otherwise the daemon will hang forever.
 As an alternative, the silvermirror program may be invoked from a cron  
-Future Work
+== Events ==
+SilverMirror [TODO] may be hooked up to an event listener for
+filesystem changes and sync on them.
+== Future Work ==
 SilverMirror implements a cloud filesystem which may be accessed  
 nearly  transparently by an arbitrary number of computers. Several  
 improvements could extend SilverMirror to solve several deficiencies  
 of modern filesystem.
   * tagging: in most filesystems, a file has a canonical location.  
 However, it may be desirable to have the file accesible via multiple  
@@ -230,8 +236,13 @@ could also include notions for updating 
 Behavior Respecting Versioned Directories) with parallel notation.
  * portable SilverMirror:  a utility should be created to put a
 SilverMirror backup scheme on portable media.  This not only
 includes a backup of the files, but also the SilverMirror program and
 all of the files necessary to create a new SilverMirror node.
  * SilverMirror + Firefox Sync
+== Vision ==
+Essentially, SilverMirror is intended as a portable filesystem on a
+filesystem type interface.