doc/monikop.muse

   1 #title Monikop and Pokinom
   2 #subtitle rsync between unconnected hosts
   3
   4 * Purpose
   5
   6 Suppose we have an isolated network of data producing computers
   7 (Sources), e.g. in a surveying vehicle (Rover). The collected data (a
   8 few Terabytes per day) need to be transferred to a processing server
   9 (Destination) in office.
  10
  11 This data transfer, which happens by means of removable disks, is
  12 Monikop's and Pokinom's job.
  13
  14 On Rover, a couple of removable disks are put into a dedicated computer where they are
  15 filled automatically by Monikop with data pulled from Sources.
  16
  17 The disks are then carried to the office where they are put into another
  18 dedicated computer. Here, Monikop's counterpart called Pokinom pushes
  19 their content to Destination and makes the disks re-usable by
  20 Monikop.
  21
  22 The heavy lifting is done by [[http://www.samba.org/rsync/][Rsync]]. Sources as well as Destination
  23 need to have Rsync installed. Both can be running Linux as
  24 well as Windows.
  25
  26  - Transfer rates ca. ...
  27
  28
  29 * Installation
  30
  31 We assume Debian GNU/Linux here, but any distribution should
  32 work. Adapt installation instructions accordingly.
  33
  34 ** Packages
  35
  36 For Debian, use
  37
  38  - to install from a git repository: git-core;
  39
  40  - to run Monikop (on Rover) or Pokinom (in office):
  41    rsync, mingetty, sudo, libcurses-perl, libfile-rsync-perl;
  42
  43  - to run the tests: bc, time.
  44
  45
  46
  47 ** Prepare Removable Disks
  48
  49 *** File Systems
  50
  51 Create Filesystems with labels for the removable disks. Example
  52 (suppose a removable disk tagged =disk_10= is attached to =/dev/sdg1=):
  53
  54 =mke2fs -j -L disk_10 /dev/sdg1=
  55
  56 On both Monikop's and Pokinom's host, label the system root
  57 partition. If it were on =/dev/sda1/, that's e.g.=:
  58
  59 =e2label /dev/sda1 root=
  60
  61 On both Monikop's and Pokinom's host, label the swap partition. If it
  62 happens to be on /dev/sda5, e.g.:
  63
  64 =swapoff=
  65
  66 =mkswap -L swap /dev/sda5=
  67
  68 =swapon=
  69
  70 *** Mount Points
  71
  72 On both Monikop's and Pokinom's host, create mount points, one for
  73 each removable disk:
  74
  75 =mkdir -p /media/disk_{01,02,03,04...}=
  76
  77 =chmod a+rx /media/disk_{01,02,03,04...}=
  78
  79 In =/etc/fstab= on both Monikop's and Pokinom's host, make use of the disk labels:
  80
  81 <src lang="conf">
  82 ## System partitions ###
  83 LABEL=root     /               ext3  defaults,errors=remount-ro 0  1
  84 LABEL=swap     none            swap  sw                         0  0
  85 ## Removable disks
  86 LABEL=disk_01  /media/disk_01  ext3  rw,user,auto               0  0
  87 LABEL=disk_02  /media/disk_02  ext3  rw,user,auto               0  0
  88 LABEL=disk_03  /media/disk_03  ext3  rw,user,auto               0  0
  89 LABEL=disk_04  /media/disk_04  ext3  rw,user,auto               0  0
  90 # etc.
  91 </src>
  92
  93 Put each removable disk in and make it writable; e.g.:
  94
  95 =mount /media/disk_01=
  96
  97 =chmod a+rwx /media/disk_01=
  98
  99 ** Maintain Bootability
 100
 101 On both Monikop's and Pokinoms host, make sure the system boots
 102 actually from its system disk rather than from some of the removable
 103 ones. Change =/boot/grub/menu.lst= where it says
 104
 105 <code># kopt=root=...</code>:
 106
 107 <src lang="conf">
 108 ### BEGIN AUTOMAGIC KERNELS LIST
 109 ## lines between the AUTOMAGIC KERNELS LIST markers will be modified
 110 ## by the debian update-grub script except for the default options below
 111
 112 ## DO NOT UNCOMMENT THEM, Just edit them to your needs
 113
 114 ## ## Start Default Options ##
 115 ## default kernel options
 116 ## default kernel options for automagic boot options
 117 ## If you want special options for specific kernels use kopt_x_y_z
 118 ## where x.y.z is kernel version. Minor versions can be omitted.
 119 ## e.g. kopt=root=/dev/hda1 ro
 120 ##      kopt_2_6_8=root=/dev/hdc1 ro
 121 ##      kopt_2_6_8_2_686=root=/dev/hdc2 ro
 122 # kopt=root=/dev/disk/by-label/root noresume ro
 123 </src>
 124
 125 and call
 126
 127 =update-grub=
 128
 129
 130 ** Install Monikop and Pokinom
 131
 132 Create a user on both Monikop's and Pokinom's machine. For
 133 description's sake, we assume they're called m-operator.
 134
 135 Get Monikop (and Pokinom); from m-operator's home directory say:
 136
 137 =git-clone (FIXME: repo here)=
 138
 139 Copy =monikop.config.example= to =monikop.config= and
 140 =pokinom.config.example= to =pokinom.config, respectively,= and
 141 adapt them according to your needs. Both have helpful comments,
 142 and both are perl code, so be careful and keep the interpunction
 143 in place.
 144
 145 Things you want to change for Monikop in =monikop.config=:
 146
 147 <src lang="perl">
 148 # Possible data sources, and by what directory name to represent them in
 149 # destination.
 150 # When the latter is not unique, care must be taken that all pathnames in the
 151 # respective sources are unique.
 152 %sources = (
 153     'data_producer1::data' => 'p1',
 154     'data_producer2::data' => 'p2',
 155     'data_producer3::data' => '',
 156     'data_producer4::data' => '',
 157     );
 158
 159 # Possible mount points of data destinations.
 160 @usable_mount_points = (
 161     '/media/disk_1',
 162     '/media/disk_2',
 163     '/media/disk_3',
 164     );
 165 </src>
 166
 167 =%sources= are the data producing Sources in a format Rsync
 168 understands, together with a source-specific directory name where data
 169 of the respective Source goes. Those directory names can be equal for
 170 several Sources if all filenames in the payload are certain to be
 171 unique.
 172
 173 =@usable_mount_points= are the mount points (directories) you set up earlier for your
 174 removable disks.
 175
 176 Accordingly, for Pokinom in =pokinom.config, you should edit=:
 177
 178 <src lang="perl">
 179 # Possible mount points.
 180 @usable_mount_points = (
 181     '/media/disk_1',
 182     '/media/disk_2',
 183     '/media/disk_3',
 184     );
 185 </src>
 186 ...
 187 <src lang="perl">
 188 # Data destination.
 189 $destination =
 190     'big-server::incoming/NEW_DATA';
 191
 192 # Credentials of the remote rsync server. String, or 0 if not used.
 193 $rsync_username =
 194     'm-operator'
 195     ;
 196 $rsync_password =
 197     'sEcReT'
 198     ;
 199 </src>
 200
 201
 202 *** Automatic Program Start
 203
 204 Append to
 205 =/home/m-operator/.profile= (create it if necessary):
 206
 207 <src lang="bash">
 208 /home/m-operator/monikop/monikop
 209 </src>
 210
 211 or
 212
 213 <src lang="bash">
 214 /home/m-operator/monikop/pokinom,
 215 respectively.
 216 </src>
 217
 218 If necessary, specify path to config file, e.g.
 219 <src lang="bash">
 220 /home/m-operator/monikop/monikop /home/m-operator/monikop/monikop.config
 221 </src>
 222
 223
 224 *** Setup Sudo
 225
 226 On both Monikop's and Pokinom's host authorize m-operator to shut down computer.
 227 Use =visudo= to change =/etc/sudoers=; add:
 228
 229 <src lang="conf">
 230 m-operator ALL=(ALL) NOPASSWD: /sbin/halt -p
 231 m-operator ALL=(ALL) NOPASSWD: /sbin/reboot
 232 </src>
 233
 234
 235 ** Automatic Login
 236
 237 On both Monikop's and Pokinom's host, change the line in
 238 =/etc/inittab= line which says
 239
 240 <src lang="conf">
 241 1:2345:respawn:/sbin/getty 38400 tty1
 242 </src>
 243
 244 into
 245
 246 <src lang="conf">
 247 1:2345:respawn:/sbin/mingetty --autologin m-operator --noclear tty1
 248 </src>
 249
 250
 251
 252 ** Configure Rsync on Sources
 253
 254 Install package rsync.
 255
 256 Example for =/etc/rsyncd.conf=:
 257
 258 <src lang="conf">
 259 pid file=/var/run/rsyncd.pid
 260 [data]
 261     path = /mnt/hdd_0
 262     use chroot = false
 263     lock file = /var/lock/rsyncd
 264     read only = yes
 265     list = yes
 266     transfer logging = false
 267 </src>
 268
 269 In =/etc/default/rsync=, change the line
 270
 271 <src lang="conf">
 272 RSYNC_ENABLE = false
 273 </src>
 274
 275 to
 276
 277 <src lang="conf">
 278 RSYNC_ENABLE = true
 279 </src>
 280
 281 Start rsync server:
 282
 283 =/etc/initd/rsync start=
 284
 285 or reboot.
 286
 287
 288 On Windows, install
 289 [[http://sourceforge.net/projects/sereds/files/cwRsync/4.0.3/cwRsyncServer_4.0.3_Installer.zip/download][cwRsync]]. Click
 290 Start, Programs, cwRsyncServer, rsyncd.conf; edit:
 291
 292 <src lang="conf">
 293 use chroot = false
 294 strict modes = false
 295 hosts allow = *
 296 logfile = rsyncd.log
 297 [data]
 298 #   /cygdrive/e/log stands for E:\log
 299     path = /cygdrive/e/log
 300     read only = false
 301     transfer logging = false
 302 </src>
 303
 304 Configure service rsync for automatic start.
 305
 306
 307 ** Network setup
 308
 309 Depending on the amount of data to transfer, consider putting a
 310 dedicated NIC for each Source into Monikop's machine.  In this case,
 311 you should provide for non-overlapping subnets. [[http://jodies.de/ipcalc][IP-Calculator]] may be
 312 helpful.
 313
 314
 315 *** Monikop
 316
 317 **** Name the Sources
 318
 319 Example for =/etc/hosts=:
 320
 321 <src lang="conf">
 322 127.0.0.1      localhost
 323 192.168.200.10 data-producer1
 324 192.168.200.20 data-producer2
 325 192.168.200.30 data-producer3
 326 192.168.200.50 data-producer4
 327 192.168.178.1  monikop
 328 </src>
 329
 330
 331 **** Configure NICs
 332
 333 Example for =/etc/network/interfaces=:
 334 <src lang="conf">
 335 # The loopback network interface
 336 auto lo
 337 iface lo inet loopback
 338
 339 # Net of smaller Sources
 340 allow-hotplug eth1
 341 iface eth1 inet static
 342    address 192.168.178.1
 343    netmask 255.255.255.0
 344
 345 # Dedicated NIC for data-producer1
 346 allow-hotplug eth2
 347 iface eth2 inet static
 348    address 192.168.200.9
 349    netmask 255.255.255.248
 350
 351 # Dedicated NIC for data_producer2
 352 allow-hotplug eth3
 353 iface eth3 inet static
 354    address 192.168.200.19
 355    netmask 255.255.255.248
 356
 357 # Dedicated NIC for data_producer3
 358 allow-hotplug eth4
 359 iface eth4 inet static
 360    address 192.168.200.29
 361    netmask 255.255.255.248
 362
 363 # Dedicated NIC for data_producer4
 364 allow-hotplug eth5
 365 iface eth5 inet static
 366    address 192.168.200.49
 367    netmask 255.255.255.248
 368 </src>
 369
 370
 371 *** Data Sources
 372
 373 Use =/etc/hosts= as with Monikop. For Windows, it's =%SystemRoot%\system32\drivers\etc\hosts=.
 374
 375
 376 **** Source's NIC
 377
 378 Example for =/etc/network/interfaces=:
 379
 380 <src lang="conf">
 381 auto lo
 382 iface lo inet loopback
 383
 384 # service (not relevant for Monikop)
 385 allow-hotplug eth0
 386 iface eth0 inet static
 387    address 192.168.178.2
 388    netmask 255.255.255.0
 389
 390 # Monikop's dedicated NIC
 391 allow-hotplug eth1
 392 iface eth1 inet static
 393    address 192.168.200.10
 394    netmask 255.255.255.248
 395 </src>
 396
 397 For Windows, configure your network settings accordingly.
 398
 399
 400 *** Pokinom
 401
 402 Pokinom's network settings don't need any special treatment. Just
 403 integrate it into the office LAN Destination is connected to.
 404
 405 ** Data Destination
 406
 407 *** Rsync Server on Destination
 408
 409 Install package rsync.
 410
 411 Adapt =/etc/rsyncd.conf=, e.g.:
 412
 413 <src lang="conf">
 414 gid = data_receiving_group
 415 use chroot = yes
 416 max connections = 0
 417 pid file = /var/run/rsyncd.pid
 418
 419 [incoming]
 420         path = /mnt/./raid_0
 421         list = no
 422         comment = Pokinom only; requires authentication
 423         read only = no
 424         incoming chmod = g+r,g+w
 425         write only = yes
 426         # Pokinom's IP:
 427         hosts allow = 192.168.180.120
 428         auth users = m-operator
 429         secrets file = /etc/rsyncd.secrets
 430 </src>
 431
 432 =/etc/rsyncd.secrets= contains Rsync's credentials which must
 433 correspond to settings =$rsync_passwd= and =$rsync_username= in =pokinom.config=:
 434
 435 <src lang="conf">
 436 m-operator:seCreT
 437 </src>
 438
 439 In =/etc/default/rsync=, change the line
 440
 441 <src lang="conf">
 442 RSYNC_ENABLE = false
 443 </src>
 444
 445 to
 446
 447 <src lang="conf">
 448 RSYNC_ENABLE = true
 449 </src>
 450
 451 Start rsync server:
 452
 453 =/etc/initd/rsync start=
 454
 455 or reboot.
 456
 457 With the above, rsync puts the payload it receives into
 458 =/mnt/raid_0/NEW_DATA/=. ("=NEW_DATA=" was set with
 459 =$destination= in =pokinom.config=.)
 460
 461 =NEW_DATA/= and everything inside belongs to user
 462 nobody and group data_receiving_group.
 463
 464 If on Destination you can't do without Windows, install
 465 [[http://sourceforge.net/projects/sereds/files/cwRsync/4.0.3/cwRsyncServer_4.0.3_Installer.zip/download][cwRsync]],
 466 configure its =rsyncd.conf= accordingly, and set service rsync to
 467 automatic start.
 468
 469 ** fsck-pokinom
 470
 471 * Usage
 472
 473    - You have to be able to tell from your data if it's complete.
 474    - Monikop shows which disks have data and therefore should be
 475      transferred to Pokinom.
 476    - Monikop keeps starting over until shutdown or until disappearance
 477      or data source(s)
 478    - Pokinom needs sufficient amount of free space on sink; must be
 479      rebooted once this is not the case.
 480    - File permissions in Destination's receiving directory must not be
 481      changed such that the rsync server is prevented from modifying.
 482      Best practice is to move them out of this directory prior to any
 483      processing.
 484    - fsck-monikop: to be run by root
 485    - Backup functionality: data remains on disks until re-inserted in
 486      Monikop. Names in use.
 487
 488 * Bugs
 489
 490   - Data must not contain any directories called $rsync_partial_dir_name
 491   - Doesn't reflect disappearance of files on sources
 492   - May ignore empty dirs (really?)
 493
 494 * License
 495
 496 Copyright 2010 Bert Burgemeister. All rights reserved.
 497
 498 Redistribution and use in source and binary forms, with or without
 499 modification, are permitted provided that the following conditions are
 500 met:
 501
 502    1. Redistributions of source code must retain the above copyright
 503       notice, this list of conditions and the following disclaimer.
 504
 505    2. Redistributions in binary form must reproduce the above
 506       copyright notice, this list of conditions and the following
 507       disclaimer in the documentation and/or other materials provided
 508       with the distribution.
 509
 510 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTERS
 511 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 512 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 513 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 514 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 515 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 516 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 517 OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 518 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 519 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 520 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 521 DAMAGE.
 522