diff --git a/Changelog b/Changelog index bd491bc..e8cb9da 100644 --- a/Changelog +++ b/Changelog @@ -1,3 +1,15 @@ +1.2 (2009 12 16) + + * stabilize: manual "metche stabilize" invocation and metche first run + now send an e-mail (Closes: http://poivron.org/dev/metche/ticket/43) + * documentation: tell about GnuPG's "group" option, that allows to + encrypt email for multiple recipients. + * EXCLUDES: added .cache, everchanging on LVM setup, and ssh private + host keys. + * configuration: added SEND_STABLE_REPORTS configuration setting that + controls whether a report email is sent after saving a stable state; + defaults to "yes" for backward compatibility. + 1.1 (2006 09 16) * ververs: added Linux VServers support. diff --git a/FAQ b/FAQ index 12a1b4e..6922378 100644 --- a/FAQ +++ b/FAQ @@ -1,5 +1,5 @@ ,------------------------------------------------------------------------------- -| Frequently asked0 questions about metche +| Frequently asked questions about metche `------------------------------------------------------------------------------- 1. How are the monitored Changelog files ($CHANGELOG_FILE or @@ -59,8 +59,8 @@ STABLE_TIME configuration values (the "for a while" meaning depends on how much nervous you get when you run 'df /var' every five minute; a few days is a bare minimum, a few weeks is better). - - Then, have a look to the files metche has kept in $BACKUP_DIR; a simple - 'metche list' is enough if you're not monitoring any VServer. + - Then, have a look to the files metche has kept in $BACKUP_DIR; a + simple 'metche list' is enough if you're not monitoring any VServer. - If there is a huge list of "unstable" but only few "testing" states, you can try lowering TESTING_TIME. If there are many more "testing" states than "stable" state, you can try lowering STABLE_TIME. @@ -72,7 +72,8 @@ metche does not handle well, call it a bug or whatever you want; you should actually e-mail us (metche AT lists DOT riseup DOT net) the output of 'metche list', your configuration file (stripped from private - information), and some information about the metche version you're running. + information), and some information about the metche version you're + running. 7. metche does not send us any report @@ -84,3 +85,9 @@ unstable state, such as '# metche report unstable-latest'. If the output contains changed files you don't want to monitor, such as status files, add them to your EXCLUDES option in metche.conf, and wait. + +8. How do I configure e-mail encryption when sending metche reports to my + sysadmin collective? + + See the SECURITY section of metche(8). + diff --git a/README b/README index f01ad7d..bd91f78 100644 --- a/README +++ b/README @@ -1,5 +1,5 @@ metche - reducing root bus factor -homepage: https://poivron.org/dev/metche/ +homepage: https://dev.potager.org/metche/ dev team: metche AT lists DOT riseup DOT net ,------------------------------------------------------------------------------- @@ -33,7 +33,7 @@ to $BACKUP_DIR (default: /var/lib/metche). - send a nicely formatted email to a defined email address, listing the last changes that have been made to the system. - See https://poivron.org/dev/metche/ for an example. + See https://dev.potager.org/metche/ for an example. ,------------------------------------------------------------------------------- | BASIC USAGE @@ -102,10 +102,10 @@ - the "system state" backups will be saved in sub-directory in BACKUP_DIR's, called the same as the VServer; - EMAIL_ADDRESS is not used for the VServers: the report messages will be - sent to the your VServer's root email address; if you're using - ENCRYPT_EMAIL to encrypt the report messages, make sure their public key is - in the host system root's keyring, trusted enough to be used blindly by - metche; + sent to the root email address of the VServer; if you're using + ENCRYPT_EMAIL to encrypt the report messages, make sure the relevant + public key are in the host system root's keyring, trusted enough to be + used blindly by metche; - all other configuration variables are used as it. Most of metche commands (namely: list, report and stabilize) support a diff --git a/metche b/metche index f5f92c0..5fa1cb3 100755 --- a/metche +++ b/metche @@ -1,8 +1,8 @@ #! /bin/bash # -*- mode: sh; sh-basic-offset: 4; indent-tabs-mode: nil; -*- # -# SVN version: $Id: metche 176 2006-09-15 15:31:11Z intrigeri $ -# $URL: http://poivron.org/dev/svn/metche/upstream/tags/metche-1.1/metche $ +# SVN version: $Id: metche 210 2009-12-01 11:21:51Z intrigeri $ +# $URL: https://dev.potager.org/svn/metche/upstream/trunk/metche $ # # metche: reducing root bus factor # Copyright (C) 2004-2006 boum.org collective - property is theft ! @@ -106,11 +106,13 @@ STABLE_TIME="3" EMAIL_ADDRESS="root@`hostname -f`" ENCRYPT_EMAIL="no" +SEND_STABLE_REPORTS="yes" EXCLUDES="*.swp #* *~ *.gpg *.key ifstate adjtime ld.so.cache shadow* \ - .gnupg blkid.tab* aumixrc net.enable mtab backup.d \ + .cache .gnupg blkid.tab* aumixrc net.enable mtab backup.d \ vdirbase run.rev vdir run.rev \ prng_exch smtp_scache.pag smtpd_scache.pag \ - smtp_scache.dir smtpd_scache.dir local.sh" + smtp_scache.dir smtpd_scache.dir local.sh \ + ssh_host_dsa_key* ssh_host_rsa_key*" LOCALE="C" VSNAMES="" @@ -632,6 +634,10 @@ sed 's/-[0-9]*\./-latest\./'`" fi done + if [ "${SEND_STABLE_REPORTS}" = yes ]; then + echo "metche saved a new stable state: $stable." | + email "$stable" + fi } # Print watched directory and files separated by spaces @@ -764,8 +770,10 @@ elif no_change_since "$STABLE_TIME_MIN"; then if changed_from "$BACKUP_DIR"/stable-latest.tar.bz2; then save_state "stable" - echo "metche saved a new stable state: stable-${DATE}." | - email "stable-$DATE" + if [ "${SEND_STABLE_REPORTS}" = yes ]; then + echo "metche saved a new stable state: stable-${DATE}." | + email "stable-$DATE" + fi debug " removing all saved testing states older" \ "than STABLE_TIME ($STABLE_TIME)." find "$BACKUP_DIR" -name 'testing-*' \ diff --git a/metche-manpage.sgml b/metche-manpage.sgml deleted file mode 100644 index f6f721b..0000000 --- a/metche-manpage.sgml +++ /dev/null @@ -1,196 +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. - - 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 - metche@lists.riseup.net. - - - - diff --git a/metche.8 b/metche.8 index acd6802..c464e6a 100644 --- a/metche.8 +++ b/metche.8 @@ -1,71 +1,124 @@ +'\" t .\" Title: metche -.\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 -.\" Date: 09/16/2006 -.\" Manual: -.\" Source: +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 12/16/2009 +.\" Manual: [FIXME: manual] +.\" Source: [FIXME: source] +.\" Language: English .\" -.TH "METCHE" "8" "09/16/2006" "" "" +.TH "METCHE" "8" "12/16/2009" "[FIXME: source]" "[FIXME: manual]" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- .SH "NAME" metche \- reducing root bus factor .SH "SYNOPSIS" -.HP 7 +.HP \w'\fBmetche\fR\ 'u \fBmetche\fR [\-h\ \fIvserver\fR] {[report\ [\ {[stable]\ |\ [testing]\ |\ [unstable]}\-\fIYYYYMMDDHHMM\fR\ ]] | [list] | [stabilize\ [testing\-\fIYYYYMMDDHHMM\fR]]} .SH "DESCRIPTION" .PP -metche is a tool meant to ease collective system administration by monitoring changes in the system configuration. +metche is a tool meant to ease collective system administration by monitoring changes in the system configuration\&. .PP metche basic usage is to monitor changes in a directory, usually -\fI/etc\fR +/etc ; optionally, metche can also monitor: -.TP 3n -\(bu +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} one or more user maintained changelog files, -.TP 3n -\(bu -the state of Debian packages and versions. -.sp -.RE -.PP -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: -.TP 3n -\(bu +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +the state of Debian packages and versions\&. +.RE +.PP +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: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} \fIunstable\fR -states are saved as soon as a change is detected. They are kept until a new -\fItesting\fR -state appears. -.TP 3n -\(bu +states are saved as soon as a change is detected\&. They are kept until a new +\fItesting\fR +state appears\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} \fItesting\fR states is created from the last \fIunstable\fR -state that has not been changed after a short amount of time (by default, one hour). Old +state that has not been changed after a short amount of time (by default, one hour)\&. Old \fIunstable\fR -states are deleted afterwards. -.TP 3n -\(bu +states are deleted afterwards\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} \fIstable\fR states are created from the last \fItesting\fR -state, either manually, or after a long amount of time (by default, 3 days). Old -\fItesting\fR -states are deleted afterwards. -.sp +state, either manually, or after a long amount of time (by default, 3 days)\&. Old +\fItesting\fR +states are deleted afterwards\&. .RE .PP When a new \fItesting\fR state is saved, an email is sent to a configurable address, giving an overwiew of the differences with the previous -\fItesting\fR. A notification is also sent when a new +\fItesting\fR\&. A notification is also sent when a new \fIstable\fR -state is saved. -.PP -metche's configuration is read from -\fI/etc/metche.conf\fR. Various settings like changelog monitoring or time between system state switches are described there. +state is saved\&. +.PP +metche\*(Aqs configuration is read from +/etc/metche\&.conf\&. Various settings like changelog monitoring or time between system state switches are described there\&. .SH "OPTIONS" .PP If @@ -73,56 +126,71 @@ \fIVSERVER\fR is specified, the VServer \fIVSERVER\fR -is operated on instead of the host system. This, along with the +is operated on instead of the host system\&. This, along with the \fBVSNAMES\fR -option, allows to monitor several VServers running on the system. +option, allows to monitor several VServers running on the system\&. .PP One of the following commands must be specified on the command line: -.TP 3n +.PP \fBreport\fR +.RS 4 When run with the \fBreport\fR -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. -.TP 3n +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\&. +.RE +.PP \fBlist\fR +.RS 4 When run with the \fBlist\fR -command, metche displays a list of all the saved states. -.TP 3n +command, metche displays a list of all the saved states\&. +.RE +.PP \fBstabilize\fR +.RS 4 When run with the \fBstabilize\fR -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. -.TP 3n +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\&. +.RE +.PP \fBcron\fR -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 +.RS 4 +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 \fB\-h\fR -option. +option\&. +.RE .SH "FILES" .PP -\fI/etc/metche.conf\fR -contains metche configuration. +/etc/metche\&.conf +contains metche configuration\&. .PP When configured to monitor one changelog, \fBCHANGELOG_FILE\fR (default: -\fI/root/Changelog\fR). +/root/Changelog)\&. .PP When configured to monitor multiple changelogs, -\fICHANGELOG_DIR/*/Changelog\fR +CHANGELOG_DIR/*/Changelog (default: -\fI/root/changelogs\fR). +/root/changelogs)\&. .PP System states are saved in \fBBACKUP_DIR\fR (default: -\fI/var/lib/metche)\fR. +/var/lib/metche)\&. .SH "SECURITY" .PP metche is able to use GnuPG to encrypt the email it sends, but does not by default; just enable the \fBENCRYPT_EMAIL\fR configuration option, and make sure -\fBEMAIL_ADDRESS\fR' public key is in root's keyring, trusted enough to be used blindly by metche. +\fBEMAIL_ADDRESS\fR\*(Aq public key is in root\*(Aqs keyring, trusted enough to be used blindly by metche\&. If +\fBEMAIL_ADDRESS\fR +is an email alias or mailing\-list\*(Aqs address, you probably want to use the +\fBgroup\fR +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)\&. .PP When \fBDO_DETAILS\fR @@ -130,29 +198,31 @@ \fBENCRYPT_EMAIL\fR is disabled, metche sends in \fIclear text email\fR -the changes made to the watched directory... either make sure that the +the changes made to the watched directory\&.\&.\&. either make sure that the \fBEXCLUDES\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 +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. Please note that +configuration variable to a local mailbox\&. Please note that \fBEMAIL_ADDRESS\fR -is not used for VServers: a VServer's report messages are sent to its root email address. +is not used for VServers: a VServer\*(Aqs report messages are sent to its root email address\&. .PP metche stores, in \fBBACKUP_DIR\fR (default : -\fI/var/lib/metche\fR), various backups of -\fBWATCHED_DIR\fR. Make sure that this backup place is at least as secured as the source. +/var/lib/metche), various backups of +\fBWATCHED_DIR\fR\&. Make sure that this backup place is at least as secured as the source\&. .SH "BUGS" .PP See -[1]\&\fImetche's ticket system\fR -for known bugs, missing features, and the development road\-map. +\m[blue]\fBmetche\*(Aqs ticket system\fR\m[]\&\s-2\u[1]\d\s+2 +for known bugs, missing features, and the development road\-map\&. .SH "AUTHOR" .PP -metche and this manual page were written by the boum.org collective -. -.SH "REFERENCES" -.TP 3 -1.\ metche's ticket system -\%https://poivron.org/dev/metche/ +metche and this manual page were written by the boum\&.org collective +metche@lists\&.riseup\&.net\&. +.SH "NOTES" +.IP " 1." 4 +metche's ticket system +.RS 4 +\%https://dev.potager.org/metche/ +.RE diff --git a/metche.conf.default b/metche.conf.default index 80a5ab4..bcf5a35 100644 --- a/metche.conf.default +++ b/metche.conf.default @@ -36,18 +36,27 @@ # Encrypt emails with GnuPG ? (uncomment next line to do so) #ENCRYPT_EMAIL="yes" +# Email $EMAIL_ADDRESS after saving a stable state +SEND_STABLE_REPORTS="yes" + # Filename patterns to ignore (space-separated list) # GNU tar --exclude pattern matching rules are used: # - If a pattern matches a directory, all the files beneath it are # recursively excluded. # - Periods (`.') or forward slashes (`/') are not considered special for # wildcard matches. +# +# Known cases where excludes are needed: +# - "resolv.conf" when using resolvconf, +# - "printcap" when cups browsing feature are used. +# # Example (default value): #EXCLUDES="*.swp #* *~ *.gpg *.key ifstate adjtime ld.so.cache shadow* \ -# .gnupg blkid.tab* aumixrc net.enable mtab backup.d \ +# .cache .gnupg blkid.tab* aumixrc net.enable mtab backup.d \ # vdirbase run.rev vdir run.rev \ # prng_exch smtp_scache.pag smtpd_scache.pag \ -# smtp_scache.dir smtpd_scache.dir local.sh" +# smtp_scache.dir smtpd_scache.dir local.sh \ +# ssh_host_dsa_key* ssh_host_rsa_key*" # Locale (will be used to feed LC_ALL) # Warning: values different from "C" are untested.