diff --git a/Makefile b/Makefile index b324467..bbbeb76 100644 --- a/Makefile +++ b/Makefile @@ -1,15 +1,11 @@ all: doc -metche-manpage.xml: metche-manpage.sgml - sgml2xml -xlower -xid $< > $@ - -metche.8: metche-manpage.xml - db2x_xsltproc -s /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl $< +metche.8: metche.8.markdown + pandoc --read=markdown --write=man --output=metche.8 --standalone $< doc: metche.8 clean: - rm -f metche-manpage.xml distclean: clean rm -f metche.8 diff --git a/metche-manpage.sgml b/metche-manpage.sgml deleted file mode 100644 index 8007225..0000000 --- a/metche-manpage.sgml +++ /dev/null @@ -1,202 +0,0 @@ - - - - - - metche - 8 - - - - metche - reducing root bus factor - - - - - metche - -h vserver - - report - - - stable - testing - unstable - -YYYYMMDDHHMM - - - list - stabilize testing-YYYYMMDDHHMM - - - - - - - DESCRIPTION - - metche is a tool meant to ease collective system administration by - monitoring changes in the system configuration. - - metche basic usage is to monitor changes in a directory, usually - /etc ; optionally, metche can also - monitor: - - - one or more user maintained changelog files, - - - the state of Debian packages and versions. - - - - metche should be installed with a cronjob that regularly runs to - automatically save the system state as needed. These states are saved in a - way similar to the Debian development model: - - - unstable states are saved as soon as - a change is detected. They are kept until a new - testing state appears. - - - testing states is created from the last - unstable state that has not been changed - after a short amount of time (by default, one hour). Old - unstable states are deleted afterwards. - - - stable states are created from the last - testing state, either manually, or after a - long amount of time (by default, 3 days). Old testing states are deleted afterwards. - - - - When a new testing state is saved, an email is - sent to a configurable address, giving an overwiew of - the differences with the previous testing. - A notification is also sent when a new stable state is - saved. - - metche's configuration is read from - /etc/metche.conf. Various settings like changelog - monitoring or time between system state switches are described - there. - - - - - OPTIONS - - If -h VSERVER is specified, - the VServer VSERVER is operated on instead of - the host system. This, along with the VSNAMES option, - allows to monitor several VServers running on the system. - - One of the following commands must be specified on the - command line: - - - - report - - When run with the report command, metche - displays a report against the specified saved state, or if unspecified, - against the latest testing state. This is useful when you - have broken your system and want to know which changes have been made - since a given, known working, system state. - - - - list - - When run with the list command, metche - displays a list of all the saved states. - - - - stabilize - - When run with the stabilize command, metche - turns a "testing state" into a "stable state". By default, it will - use the last "testing state", but this can be overriden by giving - a specific state as argument. - - - - cron - - This command should not be called manually, but used from - a cronjob. When called, it can perform various operations like: - saving "unstable", "testing" or "stable" states as needed and - sending reports and notification if configured to do so. This command - does not support the -h option. - - - - - - - - FILES - /etc/metche.conf contains metche configuration. - - - When configured to monitor one changelog, - CHANGELOG_FILE (default: - /root/Changelog). - - - When configured to monitor multiple changelogs, - CHANGELOG_DIR/*/Changelog - (default: /root/changelogs). - - System states are saved in - BACKUP_DIR (default: - /var/lib/metche). - - - SECURITY - metche is able to use GnuPG to encrypt the email it sends, but does - not by default; just enable the ENCRYPT_EMAIL configuration - option, and make sure EMAIL_ADDRESS' public key is in root's - keyring, trusted enough to be used blindly by metche. - If EMAIL_ADDRESS is an email alias or mailing-list's address, - you probably want to use the group option - in /root/.gnupg/gpg.conf so that metche reports are - encrypted for every person subscribed to this alias or mailing-list; for - more information, see gpg(1). - - When DO_DETAILS is enabled and - ENCRYPT_EMAIL is disabled, metche sends in clear - text email the changes made to the watched directory... either - make sure that the EXCLUDES configuration variable prevents - it to send sensitive information, or triple check that secure connections - will be used end-to-end on the email path. If unsure, set - EMAIL_ADDRESS configuration variable to a local mailbox. - Please note that EMAIL_ADDRESS is not used for VServers: - a VServer's report messages are sent to its root email address. - - metche stores, in BACKUP_DIR (default : - /var/lib/metche), various backups of - WATCHED_DIR. Make sure that this backup place is at least as - secured as the source. - - - BUGS - See metche's - ticket system for known bugs, missing features, and the development - road-map. - - - AUTHOR - metche and this manual page were written by the boum.org collective, - and are now maintained by the metche developers collective - metche@lists.riseup.net. - - - - diff --git a/metche.8.markdown b/metche.8.markdown new file mode 100644 index 0000000..8e8e5a6 --- /dev/null +++ b/metche.8.markdown @@ -0,0 +1,128 @@ +% METCHE(8) metche user manual +% metche and this manual page were written by the boum.org collective, and are now maintained by the metche developers collective +% June 5, 2011 + +NAME +==== + +metche - reducing root bus factor + +SYNOPSIS +======== + + metche [-h VSERVER] report (stable|testing|unstable)-YYYYMMDDHHMM + metche [-h VSERVER] list + metche [-h VSERVER] stabilize testing-YYYYMMDDHHMM + +DESCRIPTION +=========== + +metche is a tool meant to ease collective system administration by +monitoring changes in the system configuration. + +metche basic usage is to monitor changes in a directory, usually +`/etc`; optionally, metche can also monitor: + + * one or more user maintained changelog files, + * the state of Debian packages and versions. + +metche should be installed with a cronjob that regularly runs to +automatically save the system state as needed. These states are saved +in a way similar to the Debian development model: + + * _unstable_ states are saved as soon as a change is detected. They + are kept until a new _testing_ state appears. + * _testing_ states is created from the last _unstable_ state that has + not been changed after a short amount of time (by default, one + hour). Old _unstable_ states are deleted afterwards. + * _stable_ states are created from the last _testing_ state, either + manually, or after a long amount of time (by default, 3 days). Old + _testing_ states are deleted afterwards. + +When a new _testing_ state is saved, an email is sent to a +configurable address, giving an overwiew of the differences with the +previous _testing_. A notification is also sent when a new _stable_ +state is saved. + +metche's configuration is read from `/etc/metche.conf`. Various +settings like changelog monitoring or time between system state +switches are described there. + +OPTIONS +======= + +If `-h VSERVER` is specified, the VServer _VSERVER_ is operated on +instead of the host system. This, along with the `VSNAMES` option, +allows to monitor several VServers running on the system. + +One of the following commands must be specified on the command line: + +report +: When run with the _report_ command, metche displays a report + against the specified saved state, or if unspecified, against the + latest testing state. This is useful when you have broken your + system and want to know which changes have been made since a + given, known working, system state. + +list +: When run with the _list_ command, metche displays a list of all + the saved states. + +stabilize +: When run with the _stabilize_ command, metche turns a "testing + state" into a "stable state". By default, it will use the last + "testing state", but this can be overriden by giving a specific + state as argument. + +cron +: This command should not be called manually, but used from a + cronjob. When called, it can perform various operations like: + saving "unstable", "testing" or "stable" states as needed and + sending reports and notification if configured to do so. This + command does not support the `-h` option. + +FILES +===== + +`/etc/metche.conf` contains metche configuration. + +When configured to monitor one changelog, `CHANGELOG_FILE` (default: +`/root/Changelog`). + +When configured to monitor multiple changelogs, +`CHANGELOG_DIR/*/Changelog` (default: `/root/changelogs`). + +System states are saved in `BACKUP_DIR` (default: `/var/lib/metche`). + +SECURITY +======== + +metche is able to use GnuPG to encrypt the email it sends, but does +not by default; just enable the `ENCRYPT_EMAIL` configuration option, +and make sure `EMAIL_ADDRESS`' public key is in root's keyring, +trusted enough to be used blindly by metche. If `EMAIL_ADDRESS` is an +email alias or mailing-list's address, you probably want to use the +`group` option in `/root/.gnupg/gpg.conf` so that metche reports are +encrypted for every person subscribed to this alias or mailing-list; +for more information, see `gpg(1)`. + +When `DO_DETAILS` is enabled and `ENCRYPT_EMAIL` is disabled, metche +sends in _clear text email_ the changes made to the watched +directory... either make sure that the `EXCLUDES` configuration +variable prevents it to send sensitive information, or triple check +that secure connections will be used end-to-end on the email path. If +unsure, set `EMAIL_ADDRESS` configuration variable to a local mailbox. +Please note that `EMAIL_ADDRESS` is not used for VServers: a +VServer's report messages are sent to its root email address. + +metche stores, in `BACKUP_DIR` (default: `/var/lib/metche`), various +backups of `WATCHED_DIR`. Make sure that this backup place is at least +as secured as the source. + +BUGS +==== + +See [metche's ticket system] for known bugs, missing features, and the +development road-map. + +[metche's ticket system]: https://labs.riseup.net/code/projects/metche/issues