From 9bbf35baa810d82d34061eb7e841af2d2b5a7032 Mon Sep 17 00:00:00 2001 From: Bert Burgemeister Date: Mon, 15 Feb 2010 12:00:09 +0100 Subject: [PATCH] Documentation updated. --- doc/download.muse | 12 ++++++++---- doc/index.muse | 22 +++++++++++----------- doc/installation.muse | 11 ++++++++--- doc/news.muse | 24 ++++++++++++++++++++++++ doc/sidebar.muse | 3 ++- doc/usage.muse | 48 ++++++++++++++++++++++++++++-------------------- 6 files changed, 81 insertions(+), 39 deletions(-) create mode 100644 doc/news.muse diff --git a/doc/download.muse b/doc/download.muse index f7a3f2e..0c3c301 100644 --- a/doc/download.muse +++ b/doc/download.muse @@ -5,7 +5,14 @@ * Download -Get Monikop's Git repository: +** Latest Release (tar.gz) + +Check out the [[news][Release Notes]]. + +[[http://ohloh.net/p/monikop/download?package=Monikop&release=latest][Download monikop.tar.gz]] +(via [[http://ohloh.net/p/monikop][Ohloh]]). + +** Development Version (Git Repository) =$ git clone git://git.berlios.de/monikop= @@ -17,6 +24,3 @@ or =$ git-clone http://repo.or.cz/r/monikop.git= - -There aren't any releases at the moment. If you need a tarball, -you can get one [[http://repo.or.cz/w/monikop.git/snapshot/][here]]. diff --git a/doc/index.muse b/doc/index.muse index 950ea3f..c2a0bf3 100644 --- a/doc/index.muse +++ b/doc/index.muse @@ -13,21 +13,21 @@ few terabytes per day) need to be transferred to a processing server This data transfer, which happens by means of removable disks, is Monikop's and Pokinom's job. -On Rover, a couple of removable disks are put into a dedicated computer where they are -filled automatically by Monikop with data pulled from Sources. -At any time, copying data -finished or otherwise, the operator switches Monikop's host off by a keypress and removes the +On Rover, a couple of removable disks are put into a dedicated +computer where they are filled automatically by Monikop with data +pulled from Sources. At any time, copying data finished or otherwise, +the operator switches Monikop's host off by a keypress and removes the disks. Data integrity is never compromised by shutting down Monikop's -host or any of the Sources at any time, in any order, by any means including power -cuts. +host or any of the Sources at any time, in any order, by any means +including power cuts. -The disks are then brought to the office where they are put into another -dedicated computer. Here, Monikop's counterpart called Pokinom pushes -their content to Destination, makes the disks re-usable by +The disks are then brought to the office where they are put into +another dedicated computer. Here, Monikop's counterpart called Pokinom +pushes their content to Destination, makes the disks re-usable by Monikop, and switches itself off when finished. -Old data is left as long as possible on the removable disks. This may -be helpful as part of a backup strategy. +Old data is being left as long as possible on the removable +disks. This may be helpful as part of a backup strategy. The heavy lifting is done by [[http://www.samba.org/rsync/][Rsync]]. Sources as well as Destination need to have Rsync installed. Both can be running Linux, Windows, or diff --git a/doc/installation.muse b/doc/installation.muse index 0d62d2e..e6ac64e 100644 --- a/doc/installation.muse +++ b/doc/installation.muse @@ -11,11 +11,11 @@ work. Adapt installation instructions accordingly. Debian Packages needed: - - to install from a git repository: git-core; - - to run Monikop (on Rover) or Pokinom (in office): rsync, mingetty, sudo, libcurses-perl, libfile-rsync-perl; + - to install from a git repository: git-core; + - to run the tests: bc, time. - Both Monikop and Pokinom run on text console; you don't need @@ -112,7 +112,12 @@ and call Create a user on both Monikop's and Pokinom's machine. For description's sake, we assume they're called m-operator. -Inside m-operator's home directory, [[download][get Monikop (and Pokinom)]] and +Inside m-operator's home directory, [[download][get Monikop (and Pokinom)]]; +unpack the tarball: + +=$ tar -xzf monikop-.tar.gz= + +=$ mv monikop- monikop= =$ cd monikop=. diff --git a/doc/news.muse b/doc/news.muse new file mode 100644 index 0000000..4b1b037 --- /dev/null +++ b/doc/news.muse @@ -0,0 +1,24 @@ +#title Monikop (and Pokinom) +#subtitle rsync between unconnected hosts +#author Bert Burgemeister + + +* Release Notes + + +(with-temp-buffer + (insert-file-contents "../NEWS") + (goto-char (point-min)) + (open-line 1) + (while (not (eobp)) + (while (search-forward "\n*" nil t) + (replace-match "** " nil t)) + (forward-line)) + (goto-char (point-min)) + (while (not (eobp)) + (while (search-forward "\n; " nil t) + (kill-line) + (kill-line -1)) + (forward-line)) + (buffer-string)) + diff --git a/doc/sidebar.muse b/doc/sidebar.muse index 515afd5..43f6367 100644 --- a/doc/sidebar.muse +++ b/doc/sidebar.muse @@ -1,5 +1,4 @@ - [[index][Introduction]] - - [[download][Download]] - [[installation][Installation]] - [[installation#Prepare_Removable_Disks][Prepare Removable Disks]] - [[installation#Configure_Monikop_and_Pokinom][Configure Monikop and Pokinom]] @@ -9,6 +8,8 @@ - [[usage][Usage]] - [[license][License]] - [[screenshots][Screenshots]] + - [[download][Download]] + - [[news][Release Notes]]

diff --git a/doc/usage.muse b/doc/usage.muse index 284c836..2ff9478 100644 --- a/doc/usage.muse +++ b/doc/usage.muse @@ -57,7 +57,20 @@ must be rebooted once this temporarily hasn't been the case. ; - fsck-pokinom: to be run by root -** Data Recovery +** Crash Recovery + +Removable disks may get lost before they reach Destination, or +Destination may crash shortly after receiving fresh data. The +following may help in these cases. + +*** Data Recovery from Source(s) on Rover + +On Monikop's host, stop Monikop and delete the log files whose +directory and name prefix is set in [[installation#monikop.config][monikop.config]] by +=$rsync_log_prefix= and =$finished_prefix=, and whose names resemble the +Source they belong to. + +On next startup, Monikop will pull all data from this Source again. *** Data Loss on Destination: Recovery from Removable Disks @@ -76,14 +89,14 @@ in both [[installation#monikop.config][monikop.config]] and and start deleting it while a new =$path_under_mount_point= is created and filled with fresh data. -*** Recovery from Source(s) on Rover +*** Disk Failure -On Monikop's host, stop Monikop and delete the log files whose directories and name -prefixes are set in [[installation#monikop.config][monikop.config]] by -=$rsync_log_prefix= and =$finished_prefix=, and whose names resemble -the Source they belong to. +Suppose the system reports disk error on (say) /dev/sdb1. What is it's +label? -On next startup, Monikop will pull all data from this Source again. +=ls -l /dev/disk/by-label= + +shows the mapping. * Bugs @@ -93,23 +106,18 @@ On next startup, Monikop will pull all data from this Source again. Monikop and Pokinom are unable to tell whether a file is transferred completely. You should be able to assert completeness of your files by other means. - - Payload data must not contain any directories with the names set - by =$rsync_partial_dir_name= in - [[installation#monikop][monikop.config]]/[[installation#pokinom.config][pokinom.config]] + - Empty directories on Sources are being ignored. + - Any directories on Sources whose names conflict with the setting + =$rsync_partial_dir_name= in [[installation#monikop][monikop.config]] are being ignored. - Deletions on Sources won't propagate to Destination. - - May ignore empty directories on Sources. -; (TODO: really?) - For user information on progress, both Monikop and Pokinom rely on - Rsync's output which is not always reliable as to total number of - files. + Rsync's output which is not always reliable as to the total number + of files. - During copying, occasionally obsolete versions of a file may temporarily appear on Destination. This can happen with files that have grown bigger after having been copied already. - Frequent power cuts (as opposed to normal shutdown operations) may compromise efficiency in terms of disk usage. - - By running multiple instances of Rsync, Monikop puts considerable strain - on the system, which may reveal previously unnoticed hardware faults. - -; System reports disk error on (say) /dev/sdb1. What is it's label? -; ls -l /dev/disk/by-label - + - By running multiple instances of Rsync, Monikop puts considerable + strain on the system. This may reveal previously unnoticed + hardware faults. -- 2.11.4.GIT