Why do you need this ?
**********************

You maintain various machines and update documentation and/or configuration on the machines.
You want to keep a copy of the files that you maintain for the time when one of the
becomes unavailable or even lost.

This script automatically emails you the files when they change. Unless it is automatic
the copy that you have will probably be out of date when you need it.

Since passwords and the such may be sent the files emailed are encrypted with GPG.

A file containing a snapshot of the system state and config can be generated as well.

Installation
************

Copy the file BackupToDisk to /usr/local/bin and make it executable.
Note that this script used the Korn Shell (ksh), you may need to install
this on your machine.

Get the recipient's public keys on your keyring.

Put a line like the following in your (root's ?) crontab:

	20	5	*	*	*	/usr/local/bin/MailDocumentation -i -t /var/log/yum.log -T /usr/tmp/MailDoc_tmp addw@phcomp.co.uk


Encryption Big Picture
**********************

There are two people involved:

* the sender - that runs MailDocumentation on the machine being monitored
* the recipient - that receives the encrypted documentation file

There are 2 keys (passwords) used in encryption:

* The public key - this is the password used to encrypt
* The private key - this is the password used to decrypt

The file emailed is encrypted using the public key of the recipient.

A public key is one that anyone can be told and can use - it is the encrypting
password. To encrypt the file the sender does not need the recipent's private
key (decrypting password). Once the sender has encrypted the file he cannot
decrypt it.

The recipent can decrypt the file as he knows the private key (ie the
decrypting password).

PGP is the program that generates the 2 keys and uses these keys
to encrypt and decrypt files.

To make this work:

* the recipient generates a public and private key pair using PGP.

* the recipient gives the sender a copy of his public key.

* the sender encrypts a file using the public key and PGP.

* the sender gives the encrypted file to the recipient.

* the recipient is able to decrypt the file using his private key and PGP.


Decrypting a file
*****************

Do this in a temporary/work directory, this will give you a tar
file that you can then extract files from:

    $ mkdir WorkDir
    $ cd WorkDir
    $ gpg --decrypt ../RemoteMachine.tar.gpg > RemoteMachine.tar
    $ tar xf RemoteMachine.tar

You need to untar into a separate directory since all the files
will be unpacked into the current directory and you could overwrite
other important files there.


You will be told who's passphrase you need and enter it at the prompt.
The author decrypting a file will see this (unindented):

	You need a passphrase to unlock the secret key for
	user: "Alain D D Williams <addw@phcomp.co.uk>"
	1024-bit ELG-E key, ID A50C3FC3, created 2005-02-17 (main key ID 90610026)

	Enter passphrase:

To which I type .... you don't get my passphrase that easily!



Automatic posting of the file
*****************************

The Subject: line will be something like:

	Documentation from some.machine.example.com

If you run exim as your MTA, you can put this in your $HOME/.forward file.

# Auto save of documentation updates from customer machines.
# save - appends to a mailbox, ie you get a 'history' of documentation
# pipe - overwrites the file, the file only contains the most recent received
# Leave a copy in my mailbox so that I can see that something has arrived:
if	$h_subject:  matches "^Documentation from ([-\\\\w.:]+)" and
	$h_subject:  does not contain ".."
then
#	unseen save "$home/docs/CustDoc/$1"
	unseen pipe "cp /dev/stdin $home/docs/CustDoc/$1"
endif

You should be able to do the same sort of thing with procmail, send me the
recipe if you do this.


PGP/GPG and mail readers
************************

You may need to configure your mail reader. I use mutt which does it easily.

Thunderbird
***********

Thunderbird under MS Windows which is supposed to work, see:

        http://enigmail.mozdev.org/documentation/quickstart.php

You may also find this useful:

        http://www.privacyresources.org/pgp101.htm

and:

        http://www.pgp.com/index.html

Note that GPG is a free implementation of PGP.

Note that you don't need PGP s/ware to receive the email, but you do to be
able to read/decrypt it ... ie it doesn't need to be your regular/normal mail reader.


Generation of a GPG key
***********************

You need to generate a GPG key for the address to which encrypted email
will be sent. This key needs to be imported to the machine that is sending
the email.

(GPG is an open source version of PGP - consider them the same.)

To generate a PGP key do the following on a Linux box:

        $ gpg --gen-key

        Take option (1) "DSA & ElGamal"
        choose at least 1024 bits
        Key validity several years
        You will be prompted for your real name, email address and a comment
        You will be prompted for a pass *phrase* - this you must remember
        If the machine is not busy it will complain about a lack of randomness, waggle the mouse!

List it:

        $ gpg --list-secret-keys

Send a key 90610026 to the server:

        $ gpg --keyserver wwwkeys.uk.pgp.net --send-keys 90610026

It can be sometimes quicker to export the key to a file, copy the file and import:

	$ gpg --export 0735B9AA > /tmp/MyLocalKey
	$ scp /tmp/MyKey some.machine:/tmp/MyRemoteKey

on some.machine, import the key and set a trust level.
The trust level will probably be quite high since you generated the key and copied it
over yourself:

	$ gpg --import /tmp/MyRemoteKey
	$ gpg --edit-key 0735B9AA
	Command> trust
	....
	Your decision? 5
	Command> quit

You may find, after the above, that the validity is 'unknown' as
something like:
	      trust: full          validity: unknown
You should sign it:
	$ gpg --sign-key 0735B9AA

License
*******

This software is copyright (c) Alain Williams <addw@phcomp.co.uk>, 2008, 2010, 2019.
This software is released under the GPL.


Contributing
************

MailDocumentation is free software (see the license). Free software grows and becomes more
powerful and useful as those who gain by using it contribute their changes back
to the original author.

Contributions to this software are welcome. Please email the author the following:

* your name & email address
* your affiliation (company/institute/...) if any
* the code
* documentation
* a statement that you are legally able to release the code and documentation
* a statement transfering copyright to the Author below giving permission that it
  may be redistributed as part of UserAdmin under an appropriate license

Contributions will be acknowledged in the Contributors file that accompanies this
software. If you do not want to be acknowledged please make that clear.




SCCS: @(#)README	1.7 05/30/19 11:27:26