diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000..578267f --- /dev/null +++ b/INSTALL @@ -0,0 +1,9 @@ +,------------------------------------------------------------------------------- +| INSTALLATION +`------------------------------------------------------------------------------- + +1. Copy the metche executable to /usr/local/sbin/ +2. As root, mkdir /var/lib/metche +3. Copy the manpage (metche.8) to /usr/local/man/man8/ +4. Read the README file and the manpage + diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..9330c12 --- /dev/null +++ b/Makefile @@ -0,0 +1,11 @@ +default: doc + +manpage: + sgml2xml -xlower -xid metche-manpage.sgml > metche-manpage.xml + db2x_xsltproc -s /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl metche-manpage.xml + +doc: manpage + +clean: + test ! -f metche.8 || rm metche.8 + test ! -f metche-manpage.xml || rm -f metche-manpage.xml diff --git a/README b/README index faa4a6a..5f09f9b 100644 --- a/README +++ b/README @@ -41,20 +41,21 @@ address ; - use the Changelog files in a rigorous way. -Note: it is dangerous to use metche without before reading the SECURITY WARNINGS -section. +Note: it is dangerous to use metche without before reading the SECURITY section +of the manpage. -For a deeper explanation of the way metche works, read the USAGE & FAQ sections. +For a deeper explanation of the way metche works, read the manpage. ,------------------------------------------------------------------------------- | REQUIREMENTS `------------------------------------------------------------------------------- -1. Debian GNU/Linux -2. apt-show-versions -3. mutt -4. If you want metche to monitor your vservers as well : util-vserver tools -5. At least one Changelog file in $CHANGELOG_DIR/*/Changelog ; for example, you +1. Debian GNU/Linux and apt-show-versions (if Debian packages monitoring is + enabled) +2. mutt +3. If you want metche to monitor your vservers as well : util-vserver tools +4. If you want metche to monitor your Changelog files, at least one Changelog + file must be located in $CHANGELOG_DIR/*/Changelog ; for example, you can have : /root/ changelogs/ @@ -66,8 +67,7 @@ | INSTALLATION `------------------------------------------------------------------------------- -1. Copy the metche executable to /usr/local/sbin/ -2. As root, mkdir /var/lib/metche +See the included INSTALL file. ,------------------------------------------------------------------------------- | CONFIGURATION @@ -77,7 +77,7 @@ 1. Copy metche.conf.default to /etc/metche.conf and edit it so that it suits your needs. -2. Read the next sections of this document. +2. Read the next sections of this document and the manpage. 3. Add to /etc/cron.d/metche something like : 0-59/5 * * * * root test -x /usr/local/sbin/metche && \ /usr/local/sbin/metche cron @@ -95,23 +95,16 @@ - edit .conf so that it suits your needs - if the system to monitor is a vserver, edit .conf to set VSERVER_EXEC_PREFIX to something like "/usr/sbin/vserver exec" -3. Read the next sections of this document. +3. Read the next sections of this document and the manpage. 4. For each system to monitor, add to /etc/cron.d/metche something like : 0-59/5 * * * * root test -x /usr/local/sbin/metche && \ /usr/local/sbin/metche -h cron ,------------------------------------------------------------------------------- -| SECURITY WARNINGS +| SECURITY : BIG FAT WARNING `------------------------------------------------------------------------------- -1. metche sends in *clear text email* the changes made to /etc... either make - sure that the TAR_OPTS config variable prevents it to send sensitive - information, or triple check that TLS/SSL will be used end-to-end on the - email path. If unsure, set $EMAIL_ADDRESS to a local mailbox. - -2. metche stores in $BACKUP_DIR various backups of $WATCHED_DIR (default: /etc) - and $CHANGELOG_DIR (default: /root/changelogs) ; of course, metche uses 077 - as umask, but... you have to be aware of this. +Read the SECURITY section of metche(8). Really. ,------------------------------------------------------------------------------- | FAQ diff --git a/metche-manpage.sgml b/metche-manpage.sgml new file mode 100644 index 0000000..60292c6 --- /dev/null +++ b/metche-manpage.sgml @@ -0,0 +1,122 @@ + + + + + + metche + 8 + + + + metche + reducing root bus factor + + + + + metche + -h host + + cron + report milestone + list + + + + + + + DESCRIPTION + metche is a tool meant to facilitate collective sysadmin, by + monitoring changes in the system configuration. At least + WATCHED_DIR (default: /etc) is + monitored ; optionally, metche can also monitor : + + + system Changelog files located in + CHANGELOG_DIR/*/Changelog (default: + /root/changelogs/*/Changelog) + + + Debian packages states and versions + + + + WATCHED_DIR and CHANGELOG_DIR options + can me customized in metche's configuration file, as well as a few other + ones. + + If -h HOST is specified, + /etc/metche/HOST.conf is used instead of + /etc/metche.conf. This, along with the + VSERVER_EXEC_PREFIX option, allows to monitor several + vservers running on a system. + + Anyway, one of the following commands has to be specified on the + command line : + + cron + When run (usually by a cronjob) with the cron + command, metche looks if the system configuration has changed in the last + $TESTING_TIME minutes. If it is the case, a "unstable + state" is saved. Otherwise, a "testing state" (also called a "milestone") + is saved, and a report (see metche's homepage for an + example) is emailed to you. + + + report [<emphasis>milestone</emphasis>] + When run with the report command, metche displays + a report against a given milestone, if specified, or against the latest + one, otherwise. This is useful when you have broken your system and want + to know which changes have been made since a given, known working, + milestone. + + + list + When run with the list command, metche displays + the full saved states list. + + + + + FILES + /etc/metche.conf or + /etc/metche/*.conf : configuration file(s) + + CHANGELOG_DIR/*/Changelog + (default : /root/changelogs), if Changelog monitoring + is enabled : Changelog files location + + BACKUP_DIR : directory containing + the backups + + + SECURITY + metche sends in clear text email the changes made + to the watched directory... either make sure that the + TAR_OPTS 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. + + metche stores, in BACKUP_DIR (default : + /var/lib/metche), various backups of + WATCHED_DIR. Make sure that the backup place is at least as + secure as the source. + + + BUGS + See metche's ticket + system to see the bugs, missing features, and development + road-map. + + + AUTHOR + This manual page was written by Intri Geri + intrigeri@boum.org. + + + + diff --git a/metche.8 b/metche.8 new file mode 100644 index 0000000..d3c5de6 --- /dev/null +++ b/metche.8 @@ -0,0 +1,96 @@ +.\"Generated by db2man.xsl. Don't modify this, modify the source. +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "METCHE" 8 "" "" "" +.SH NAME +metche \- reducing root bus factor +.SH "SYNOPSIS" +.ad l +.hy 0 +.HP 7 +\fBmetche\fR [\-h\ \fIhost\fR] {\fBcron\fR | \fBreport\ [\fImilestone\fR]\fR | \fBlist\fR} +.ad +.hy + +.SH "DESCRIPTION" + +.PP +metche is a tool meant to facilitate collective sysadmin, by monitoring changes in the system configuration\&. At least \fBWATCHED_DIR\fR (default: \fI/etc\fR) is monitored ; optionally, metche can also monitor : + +.TP 3 +\(bu +system Changelog files located in\fI\fBCHANGELOG_DIR\fR/*/Changelog\fR (default:\fI/root/changelogs/*/Changelog\fR) +.TP +\(bu +Debian packages states and versions +.LP + +.PP +\fBWATCHED_DIR\fR and \fBCHANGELOG_DIR\fR options can me customized in metche's configuration file, as well as a few other ones\&. + +.PP +If \fB\-h\fR \fIHOST\fR is specified, \fI/etc/metche/HOST\&.conf\fR is used instead of \fI/etc/metche\&.conf\fR\&. This, along with the \fBVSERVER_EXEC_PREFIX\fR option, allows to monitor several vservers running on a system\&. + +.PP +Anyway, one of the following commands has to be specified on the command line : + +.SS "cron" + +.PP +When run (usually by a cronjob) with the \fBcron\fR command, metche looks if the system configuration has changed in the last \fB$TESTING_TIME\fR minutes\&. If it is the case, a "unstable state" is saved\&. Otherwise, a "testing state" (also called a "milestone") is saved, and a report (see metche's homepage: \fIhttps://poivron.org/dev/metche/\fR for an example) is emailed to you\&. + +.SS "report [milestone]" + +.PP +When run with the \fBreport\fR command, metche displays a report against a given milestone, if specified, or against the latest one, otherwise\&. This is useful when you have broken your system and want to know which changes have been made since a given, known working, milestone\&. + +.SS "list" + +.PP +When run with the \fBlist\fR command, metche displays the full saved states list\&. + +.SH "FILES" + +.PP +\fI/etc/metche\&.conf\fR or \fI/etc/metche/*\&.conf\fR : configuration file(s) + +.PP +\fI\fBCHANGELOG_DIR\fR/*/Changelog\fR (default : \fI/root/changelogs\fR), if Changelog monitoring is enabled : Changelog files location + +.PP +\fI\fBBACKUP_DIR\fR\fR : directory containing the backups + +.SH "SECURITY" + +.PP +metche sends in \fIclear text email\fR the changes made to the watched directory\&.\&.\&. either make sure that the \fBTAR_OPTS\fR 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 \fBEMAIL_ADDRESS\fR configuration variable to a local mailbox\&. + +.PP +metche stores, in \fBBACKUP_DIR\fR (default : \fI/var/lib/metche\fR), various backups of \fBWATCHED_DIR\fR\&. Make sure that the backup place is at least as secure as the source\&. + +.SH "BUGS" + +.PP +See metche's ticket system: \fIhttps://poivron.org/dev/metche/\fR to see the bugs, missing features, and development road\-map\&. + +.SH "AUTHOR" + +.PP +This manual page was written by Intri Geri \&. +