First commit of working code, needs a lot more writing and testing

1 files changed, 59 insertions, 51 deletions

diff --git a/README.md b/README.md
index 6bb68b2..85926e1 100644
--- a/README.md
+++ b/README.md
@@ -6,82 +6,90 @@ with easy client and server setup.
 
 "Maintenance-free" means that we'd rather make full use of a fixed amount of
 disc space with simple & predictable rules.  Management of disc space must be
-completely automatic, so it never grinds to a halt.  Failed backups can be
-restarted in case of network problems.
+completely automatic, so the process never grinds to a halt for reasons that
+could be automatically resolved.  Failed backups can be restarted in case of
+network problems.
 
 We use the standard OpenSSH on the server for encrypted transport & access 
-control, btrfs for snapshots and rsync for efficient transfer.
+control, btrfs for simple snapshots and rsync for efficient data transfer
+across the network.
 
 Backups should require as little configuration as possible to be safe - just
-the server address will be enough.
+the server address should be enough.
 
 Setting up: server
 ------------------
 Install the 'byteback' package on the server, along with its dependencies
 (rsync, sudo).
 
-Create a UNIX user to receive the backups e.g. 'byteback', create a btrfs
-home directory with quotas enabled.
-
-# adduser byteback
-# echo 'byteback btrfs subvolume' XXX >>/etc/sudoers
-# lvcreate my_volume_group -n byteback -L1000GB
-# echo '/dev/my_volume_group /home/byteback btrfs compress 0 0' >>/etc/fstab
-# mount /home/byteback
-# btrfs quota enable /home/byteback
-
-The server is launched from the 'byteback' user with OpenSSH as the transport,
-so there is no special daemon to start, but you do need to set up the program's
-data directory which is done with 
-
-# su byteback
-$ byteback-server setup
-
-That's it!  You're now ready to start backing up your first client.
+You then need to perform the following local setup on the server, which can
+securely handle backups for multiple clients.  The following commands are
+appropriate for a Debian system, you might need to alter it for other Linux
+distributions:
+
+	# Create a dedicated UNIX user which will store everyone's backups, and
+	# allow logins
+	#
+	adduser --system byteback --home /byteback --shell /bin/bash
+
+	# Allow the backup user to run the snapshot command
+	#
+	# echo <<SUDOERS >/etc/sudoers.d/byteback
+	byteback ALL = (root) NOPASSWD: /usr/local/bin/byteback-snapshot
+	byteback ALL = (root) NOPASSWD: /usr/bin/byteback-snapshot
+	byteback ALL = (root) NOPASSWD: /sbin/btrfs subvolume create
+	Defaults:byteback !requiretty
+	SUDOERS
+
+	# Create a dedicated btrfs filesystem for the user, and add that as its home
+	#
+	lvcreate my_volume_group --name byteback --size 1000GB
+	mkfs.btrfs /dev/my_volume_group/byteback
+	echo '/dev/my_volume_group/byteback /byteback btrfs compress 0 0' >>/etc/fstab
+	mount /byteback
 
 Setting up: client
 ------------------
-Clients are machines that need to be backed up.  You need to tell each client
-where its server is using normal SSH user/host syntax:
-
-# byteback setup byteback@mybackuphost.net
-Your backup key is ssh-rsa AAAAAo ... w== root@host.to.back.up
-This will create keys for communication with the server, and put them into
-/etc/byteback.  
-
-You need to then log onto the server and inform it of this client, by using
-the "byteback-server new-client" command and supplying the SSH public key.
+Clients are machines that need to be backed up.  Assuming you can log into
+the remote 'byteback' user with a password or administrative key, you only
+need to type one command on the client to set things going:
 
-# su byteback
-$ byteback-server new-client ssh-rsa AAAAAo ... w== root@host.to.back.up
-Client setup for host.to.back.up done!
+	byteback-setup-client --destination byteback@mybackuphost.net:
 
-This will have created a new directory and subvolume for this host's backups.
-Then back on the client:
+If this goes OK, you are ready to start backing up.  I'd advise taking the
+first backup manually to make sure it goes as you expect.  Type this on the
+client to start and watch the backup.
 
-# byteback test
-Connecting to server mybackuphost.net...
-The authenticity of host 'mybackuphost.net (10.10.10.1)' can't be established.
-RSA key fingerprint is c8:f5:bf:75:1b:34:6f:08:24:04:ba:a2:71:9f:5d:22.
-Are you sure you want to continue connecting (yes/no)? yes
-Successfully connected and found backup space, ready to go.
+	byteback-backup --verbose
 
-This means the host is ready to start backing up, though you need to set
-a schedule.
-
-Setting a backup schedule
--------------------------
-You can then type "byteback backup" or put it on a daily cron job to start
-backing up the server.
+Configuring byteback-backup
+---------------------------
+You can now set "byteback backup"  on a daily cron job to start backing up the
+server on a regular basis.
 
 Without any further options this will copy every file from the root downwards,
 excluding kernel-based virtual filesystems (/proc, /sys etc.) network 
 filesystems (NFS, SMB) and tmpfs or loopback mounts.
 
+It currently excludes /swap.file and /var/backups/localhost which (on Bytemark
+systems) do not need to be part of any backup.
+
 When the backup has completed successfully, the server will take a snapshot
-so that the client can't alter the backups.
+so that the client can't alter the backups, and then "prune" the backup 
+snapshots to ensure that the next backup is likely to run OK.
 
 If the backup is interrupted or dies unexpected, running "byteback backup" 
 will cause the backup to be resumed, with rsync saving the work of re-copying
 any files that hadn't changed.  By default this will happen automatically up to 
 5 times, with a 10 minute pause in between each attempt.
+
+Pruning behaviour
+-----------------
+
+Features to come
+----------------
+* spotting a /var/lib/mysql directory and making a safe snapshot and re-copy
+  of a MySQL data directory (using FLUSH TABLES WITH READ LOCK)
+
+* (same for postgres using pg_start_backup() and pg_stop_backup())
+