Commit upstream/1.1 - metche

Imported Upstream version 1.1 intrigeri 12 years ago

10 changed file(s) with 861 addition(s) and 284 deletion(s). Raw diff Collapse all Expand all

-2

Changelog less more

0		02-17-2006 - metche 1.0
	0	1.1 (2006 09 16)
	1
	2	* ververs: added Linux VServers support.
	3	* EXCLUDES: added a few everchanging Postfix files, and AlternC's
	4	local.sh
	5	* documentation: clear up the way backups are made (Closes: #365694)
	6
	7	1.0 (2006 02 17)
1	8
2	9	* Initial release.
3

+86

-0

FAQ less more

	0	,-------------------------------------------------------------------------------
	1	\| Frequently asked0 questions about metche
	2	`-------------------------------------------------------------------------------
	3
	4	1. How are the monitored Changelog files ($CHANGELOG_FILE or
	5	$CHANGELOG_DIR/*/Changelog) generated?
	6
	7	With Emacs or Vim. They are written by you! They are an important
	8	part of the collective sysadmin process metche is supposed to simplify.
	9
	10	2. How is metche working, and what are the underlying concepts I have to
	11	understand?
	12
	13	When called with the cron command line switch, metche verifies changes in
	14	the system state during the last $TESTING_TIME minutes. If any changes
	15	took place an "unstable state" is saved. Otherwise, a "testing state" is
	16	saved and a report is emailed to you.
	17
	18	A mechanism exists to automatically turn a "testing state" into
	19	a "stable" one. See metche(8) for explanations.
	20
	21	3. How do I see the saved states list?
	22
	23	Run "metche list".
	24
	25	4. I've broken my system, how can I see a report against a previous, system
	26	state, known as working?
	27
	28	Run "metche report [{stable,testing,unstable}-YYYYMMDDHHMM]".
	29	If no saved state is specified, the most recently saved "testing state"
	30	is used as reference.
	31
	32	5. How do I create a "stable state" manually?
	33
	34	Run "metche stabilize [testing-YYYYMMDDHHMM]".
	35	This turns the given "testing state", if specified, otherwise the one most
	36	recently saved, into a "stable state".
	37
	38	6. Why is metche filling my /var partition?
	39
	40	First, metche needs to make backups of your "system state" in order to be
	41	able to provide you with changes reports. Whatever you do, metche will use
	42	some disk space (a few dozens megabytes on a typical server). Please note
	43	metche performs full, and not incremental, backups.
	44
	45	But there are a few ways to limit the disk space metche uses. Here is
	46	the cookbook.
	47
	48	a) Exclude some big files from the set monitored by metche.
	49	- Have a look to your metche backup files:
	50	# ls -l /var/lib/metche/*.tar.bz2
	51	- If the average size for these files is greater than a few megabytes,
	52	you should investigate which file or directory (in $WATCHED_DIR) is
	53	guilty and use the EXCLUDES option to keep it out of metche's hands.
	54
	55	b) Speed up the mechanism that automatically turns an "unstable state" into
	56	a "testing state", and a "testing state into a "stable" one.
	57	- First, let metche run for a while with its default TESTING_TIME and
	58	STABLE_TIME configuration values (the "for a while" meaning depends on
	59	how much nervous you get when you run 'df /var' every five minute;
	60	a few days is a bare minimum, a few weeks is better).
	61	- Then, have a look to the files metche has kept in $BACKUP_DIR; a simple
	62	'metche list' is enough if you're not monitoring any VServer.
	63	- If there is a huge list of "unstable" but only few "testing" states,
	64	you can try lowering TESTING_TIME. If there are many more "testing"
	65	states than "stable" state, you can try lowering STABLE_TIME.
	66	It's better to only tweak one of these two parameters at a time.
	67	- Let metche run "for a while" again... and iterate.
	68
	69	c) Still despaired?
	70	If this does not work for you, you might also have found a weird case that
	71	metche does not handle well, call it a bug or whatever you want; you
	72	should actually e-mail us (metche AT lists DOT riseup DOT net) the output
	73	of 'metche list', your configuration file (stripped from private
	74	information), and some information about the metche version you're running.
	75
	76	7. metche does not send us any report
	77
	78	It could be an e-mail problem, but, more probably, one of your installed
	79	programs violates the FHS and writes one or more ever-changing files in /etc
	80	instead of /var. This prevents metche of turning any "unstable" state into
	81	a "testing" state, and therefore to send you any report.
	82	You can diagnose this by asking metche to generate a report against a recent
	83	unstable state, such as '# metche report unstable-latest'. If the output
	84	contains changed files you don't want to monitor, such as status files, add
	85	them to your EXCLUDES option in metche.conf, and wait.

-4

INSTALL less more

1	1	\| INSTALLATION
2	2	`-------------------------------------------------------------------------------
3	3
4		1. Have a look to the REQUIREMENTS section in the README file.
	4	1. Have a look at the REQUIREMENTS section in the README file.
5	5	2. Copy the metche executable to /usr/local/sbin/
6		3. As root, mkdir /var/lib/metche
7		4. Copy the manpage (metche.8) to /usr/local/man/man8/
8		5. Read the README file and the manpage
	6	3. Copy the manpage (metche.8) to /usr/local/man/man8/
	7	4. Read the README file, the FAQ and the manpage
9	8

+17

-0

Makefile less more

	0	all: doc
	1
	2	metche-manpage.xml: metche-manpage.sgml
	3	sgml2xml -xlower -xid $< > $@
	4
	5	metche.8: metche-manpage.xml
	6	db2x_xsltproc -s /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl $<
	7
	8	doc: metche.8
	9
	10	clean:
	11	rm -f metche-manpage.xml
	12
	13	distclean: clean
	14	rm -f metche.8
	15
	16	.PHONY: all doc clean distclean

-0

NEWS less more

	0	metche 1.1
	1
	2	* configuration: report e-mails' subject is now automatically prepended
	3	by the hostname of the monitored system; you may have to update your
	4	_MAIL_SUBJECT configuration in /etc/metche.conf, if you have
	5	customized it.

+54

-58

README less more

0	0	metche - reducing root bus factor
1		homepage : https://poivron.org/dev/metche/
	1	homepage: https://poivron.org/dev/metche/
	2	dev team: metche AT lists DOT riseup DOT net
2	3
3	4	,-------------------------------------------------------------------------------
4	5	\| Copyright (C) 2004-2006 boum.org collective - property is theft !

21	22	\| OVERVIEW
22	23	`-------------------------------------------------------------------------------
23	24
24		metche is a tool meant to facilitate collective sysadmin ; basically, it
	25	metche is a tool meant to ease collective system administration. It does
25	26	periodically :
26		- saves the "system state" to $BACKUP_DIR (default /var/lib/metche), i.e. :
	27	- save the "system state" of
27	28	. $WATCHED_DIR (default: /etc)
28	29	. $CHANGELOG_FILE (default /root/Changelog)
29	30	or $CHANGELOG_DIR//Changelog (default: /root/changelogs//Changelog)
30	31	. Debian packages states and versions (using apt-show-versions)
31		- sends you, in a nicely formated email, the last changes to the "system
32		state"; see https://poivron.org/dev/metche/ for an example.
	32	to $BACKUP_DIR (default: /var/lib/metche).
	33	- send a nicely formatted email to a defined email address, listing the last
	34	changes that have been made to the system.
	35	See https://poivron.org/dev/metche/ for an example.
33	36
34	37	,-------------------------------------------------------------------------------
35	38	\| BASIC USAGE
36	39	`-------------------------------------------------------------------------------
37	40
38		When installed and configured, metche is run by a cronjob, and you just have to
39		read the report emails. Of course, it's not useful at all if you don't :
40		- set $EMAIL_ADDRESS config variable to your sysadmin collective mailing-list
41		address ;
	41	When installed and configured, metche is run by a cron job. You just have to
	42	read the report emails. Of course it's not useful at all if you don't:
	43	- set the $EMAIL_ADDRESS config variable to your sysadmins' collective
	44	mailing-list or email address;
42	45	- use the Changelog files in a rigorous way.
43	46
44		Note: it is dangerous to use metche without before reading the SECURITY section
45		of the manpage.
	47	Note: It is dangerous to use metche without reading the SECURITY section
	48	of the manpage before.
46	49
47		For a deeper explanation of the way metche works, read the metche(8) manpage.
	50	For further explanation of the way metche works, read the metche(8) manpage and
	51	the FAQ file.
48	52
49	53	,-------------------------------------------------------------------------------
50	54	\| REQUIREMENTS
51	55	`-------------------------------------------------------------------------------
52	56
53		* Debian GNU/Linux and apt-show-versions (if Debian packages monitoring is
54		enabled)
	57	* Debian GNU/Linux and apt-show-versions (if Debian package monitoring is
	58	enabled)
55	59	* mutt
56	60	* bzip2
57		* If you want metche to encrypt the email it sends you : gnupg
58		* If you want metche to monitor your vservers as well : util-vserver tools
	61	* If you want metche to encrypt the email it sends: gnupg
	62	* If you want metche to monitor your vservers as well: util-vserver tools
59	63	* If you want metche to monitor one manually written Changelog file,
60	64	it must be located at $CHANGELOG_FILE.
61	65	_or_ If you want metche to monitor multiple manually written Changelog
62		files, they must be located in $CHANGELOG_DIR/*/Changelog ;
63		for example, you can have :
	66	files, they must be located in $CHANGELOG_DIR/*/Changelog;
	67	for example this way:
64	68	/root/
65	69	changelogs/
66	70	common/Changelog

71	75	\| INSTALLATION
72	76	`-------------------------------------------------------------------------------
73	77
74		See the included INSTALL file.
	78	Please see the included INSTALL file.
75	79
76	80	,-------------------------------------------------------------------------------
77	81	\| CONFIGURATION

80	84	1. Copy metche.conf.default to /etc/metche.conf and edit it so that it suits
81	85	your needs.
82	86	2. Read the next sections of this document and the metche(8) manpage.
83		3. Add to /etc/cron.d/metche something like :
	87	3. Add to /etc/cron.d/metche something like:
84	88	0-59/5 * * * * root test -x /usr/local/sbin/metche && \
85	89	/usr/local/sbin/metche cron
	90	See the cron (8) manpage for further explanations on how to create a cron
	91	job.
86	92
87	93	,-------------------------------------------------------------------------------
88		\| SECURITY : BIG FAT WARNING
	94	\| VSERVERS SUPPORT
	95	`-------------------------------------------------------------------------------
	96
	97	Just add one (or more) VServer name to the VSNAMES configuration variable, and
	98	metche will monitor it in addition to the host system:
	99	- the WATCHED_DIR, CHANGELOG_DIR and CHANGELOG_FILE paths are also used,
	100	relatively to your VServer's root directory;
	101	- the "system state" backups will be saved in sub-directory in BACKUP_DIR's,
	102	called the same as the VServer;
	103	- EMAIL_ADDRESS is not used for the VServers: the report messages will be
	104	sent to the your VServer's root email address; if you're using
	105	ENCRYPT_EMAIL to encrypt the report messages, make sure their public key is
	106	in the host system root's keyring, trusted enough to be used blindly by
	107	metche;
	108	- all other configuration variables are used as it.
	109
	110	Most of metche commands (namely: list, report and stabilize) support a
	111	'-h <VSERVER>' option:
	112	- if -h is specified, metche only operates on the VServer provided as an
	113	argument;
	114	- else, metche only operates on the host system.
	115
	116	Troubleshooting: in case you have a not-purely-Debianish VServer setup, you may
	117	have to customize some of the VServers-related configuration variables. See the
	118	comments in metche.conf for more details.
	119
	120	,-------------------------------------------------------------------------------
	121	\| SECURITY WARNING
89	122	`-------------------------------------------------------------------------------
90	123
91	124	Read the SECURITY section of metche(8). Really.
92	125
93		,-------------------------------------------------------------------------------
94		\| FAQ
95		`-------------------------------------------------------------------------------
96
97		1. How are the monitored Changelog files ($CHANGELOG_FILE or
98		$CHANGELOG_DIR/*/Changelog) generated ?
99
100		With Emacs or Vim. Ah ah. They are written by you ! They are an important
101		part of the collective sysadmin process metche is supposed to facilitate.
102
103		2. Hey, how is metche working, and what are the underlying concepts I have to
104		know ?
105
106		When called with the "cron" command line switch, metche looks if the "system
107		state" has changed in the last $TESTING_TIME minutes. If it is the case, a
108		"unstable" state is saved. Otherwise, a "testing state" is saved, and a
109		report is emailed to you.
110
111		A similar mechanism to automatically turn a "testing" state into a "stable"
112		one ; see metche(8) for explainations.
113
114		3. How do I see the saved states list ?
115
116		Run "metche list".
117
118		4. I've broken my system, how can I see a report against a previous, known
119		working, system state ?
120
121		Run "metche report [{stable,testing,unstable}-YYYYMMDDHHMM]".
122		If no saved state is specified, the latest "testing state" is used as
123		reference.
124
125		5. How do I create a "stable state" by hand ?
126
127		Run "metche stabilize [testing-YYYYMMDDHHMM]".
128		This turns the given testing state, if specified, or the latest one,
129		otherwise, into a "stable state".

+339

-129

metche less more

0	0	#! /bin/bash
1	1	# -- mode: sh; sh-basic-offset: 4; indent-tabs-mode: nil; --
	2	#
	3	# SVN version: $Id: metche 176 2006-09-15 15:31:11Z intrigeri $
	4	# $URL: http://poivron.org/dev/svn/metche/upstream/tags/metche-1.1/metche $
2	5	#
3	6	# metche: reducing root bus factor
4	7	# Copyright (C) 2004-2006 boum.org collective - property is theft !

26	29	###
27	30
28	31	display_usage() {
29		( echo "Usage: `basename $0` list"
30		echo " `basename $0` report" \
	32	( echo "Usage:"
	33	echo " `basename $0` [-h VSERVER] list"
	34	echo " `basename $0` [-h VSERVER] report" \
31	35	"[{stable\|testing\|unstable}-YYYYMMDDHHMM]"
	36	echo " `basename $0` [-h VSERVER] stabilize [testing-YYYYMMDDHHMM]"
	37	echo ""
	38	echo " With -h, the VServer VSERVER is operated on instead of the host system."
	39	echo ""
	40	echo "Non-interactive usage:"
32	41	echo " `basename $0` cron"
33		echo " `basename $0` stabilize [testing-YYYYMMDDHHMM]"
34	42	echo ""
35	43	) >&2
36	44	}
37	45
38	46	fatal() {
39		echo -e "$@" >&2
	47	echo -e "Fatal: $@" >&2
40	48	exit 2
	49	}
	50
	51	warning() {
	52	echo -e "Warning: $@" >&2
	53	}
	54
	55	debug() {
	56	[ "$DEBUG" != yes ] \|\| echo -e "Debug: $@" >&2
41	57	}
42	58
43	59	executable_not_found() {
44	60	local executable="$1"
45	61	local software="$2"
46		local option="$3"
47
48		fatal "$executable not found. Please install $software or turn $option off."
49		}
50
51		debug() {
52		[ "$DEBUG" != yes ] \|\| echo -e "debug: $@" >&2
	62	local dependant_option="$3"
	63	local solution_option="$4"
	64
	65	if [ -z "$solution_option" ]; then
	66	fatal "$executable not found on `current_system`." \
	67	"Please install $software or turn $dependant_option off."
	68	else
	69	fatal "$executable not found on `current_system`." \
	70	"Please install $software, customize $solution_option" \
	71	"or turn $dependant_option off."
	72	fi
53	73	}
54	74
55	75	email() {
56		debug "email $@"
57		local subject="$_MAIL_SUBJECT : $1"
	76	debug "* email $@ to $EMAIL_ADDRESS"
	77	local subject="`current_system` - $_MAIL_SUBJECT : $1"
58	78	if [ $ENCRYPT_EMAIL = "yes" ]; then
59	79	LC_ALL="$LOCALE" gpg --batch --armor --encrypt \
60	80	--recipient "$EMAIL_ADDRESS" \|

62	82	else
63	83	LC_ALL="$LOCALE" mutt -s "$subject" "$EMAIL_ADDRESS"
64	84	fi
	85	}
	86
	87	current_system() {
	88	$VSERVER_EXEC_PREFIX hostname -f
65	89	}
66	90
67	91	###

81	105	STABLE_TIME="3"
82	106	EMAIL_ADDRESS="root@`hostname -f`"
83	107	ENCRYPT_EMAIL="no"
84		EXCLUDES=".swp # ~ .key ifstate adjtime ld.so.cache shadow* \
85		blkid.tab* aumixrc net.enable mtab \
86		vdirbase run.rev vdir run.rev"
	108	EXCLUDES=".swp # ~ .gpg .key ifstate adjtime ld.so.cache shadow \
	109	.gnupg blkid.tab* aumixrc net.enable mtab backup.d \
	110	vdirbase run.rev vdir run.rev \
	111	prng_exch smtp_scache.pag smtpd_scache.pag \
	112	smtp_scache.dir smtpd_scache.dir local.sh"
87	113	LOCALE="C"
88	114
89		_MAIL_SUBJECT="`hostname -f` - changes report"
	115	VSNAMES=""
	116	VSERVERINFO=/usr/sbin/vserver-info
	117	VSERVER=/usr/sbin/vserver
	118
	119	_MAIL_SUBJECT="changes report"
90	120	_NO_DEBIAN_PACKAGES_CHANGE="No change in Debian packages state."
91	121	_NO_CHANGE="No change."
92	122

125	155	"
126	156
127	157	if [ "$1" = "-h" ]; then
128		if [ -f /etc/metche/$2.conf ]; then
129		. /etc/metche/$2.conf
130		CMD="$3"
131		MILESTONE="$4"
132		else
133		display_usage
134		fatal "Config file /etc/metche/$2.conf does not exist."
135		fi
136		elif [ -f /etc/metche.conf ]; then
137		. /etc/metche.conf
	158	VSNAME="$2"
	159	CMD="$3"
	160	MILESTONE="$4"
	161	else
138	162	CMD="$1"
139	163	MILESTONE="$2"
	164	fi
	165
	166	if [ -f /etc/metche.conf ]; then
	167	. /etc/metche.conf
140	168	else
141	169	display_usage
142	170	fatal "Config file not found."

149	177	unset LANG
150	178	umask 077
151	179
152		test -d "$WATCHED_DIR" \|\| fatal "WATCHED_DIR ($WATCHED_DIR) does not exist."
153		test -d "$BACKUP_DIR" \|\| fatal "BACKUP_DIR ($BACKUP_DIR) does not exist."
154		test -z "$TAR_OPTS" \|\| fatal "TAR_OPTS is deprecated, use EXCLUDES instead."
155
156		if [ "$DO_PACKAGES" = "yes" ]; then
157		which apt-show-versions > /dev/null \|\|
158		executable_not_found "apt-show-versions" "it" "DO_PACKAGES"
	180	# Manage deprecated configuration files and options
	181	test ! -d /etc/metche \|\| fatal "An old configuration directory (/etc/metche/)" \
	182	"was found, please upgrade your configuration."
	183	test -z "$TAR_OPTS" \|\| fatal "TAR_OPTS is deprecated, use EXCLUDES instead."
	184
	185	# Backup various configuration values: these non-underscored variable
	186	# names will be re-initialized in context_config() and re-used everywhere.
	187	_WATCHED_DIR="$WATCHED_DIR"
	188	_BACKUP_DIR="$BACKUP_DIR"
	189	_CHANGELOG_DIR="$CHANGELOG_DIR"
	190	_CHANGELOG_FILE="$CHANGELOG_FILE"
	191	_DO_PACKAGES="$DO_PACKAGES"
	192	_EMAIL_ADDRESS="$EMAIL_ADDRESS"
	193
	194	if [ -n "$VSNAMES" ]; then
	195	# check VSERVERINFO and VSERVER availability
	196	test -x "$VSERVERINFO" \|\| \
	197	executable_not_found "vserver-info" "util-vserver" "VSNAMES" "VSERVERINFO"
	198	test -x "$VSERVER" \|\| \
	199	executable_not_found "vserver" "util-vserver" "VSNAMES" "VSERVER"
	200	# check VROOTDIR availability
	201	test -n "$VROOTDIR" \|\| \
	202	VROOTDIR="`$VSERVERINFO info SYSINFO \
	203	\| grep '^ *vserver-Rootdir' \| awk '{print $2}'`"
	204	test -n "$VROOTDIR" \|\| \
	205	fatal "VSNAMES is not empty, but VROOTDIR could not be guessed." \
	206	"Please set VROOTDIR in /etc/metche.conf."
	207	test -d "$VROOTDIR" \|\| \
	208	fatal "VSNAMES is not empty, but VROOTDIR ($VROOTDIR) does not exist." \
	209	"Please set VROOTDIR in /etc/metche.conf."
	210	# expand VSNAMES if it is set to "all"
	211	if [ "$VSNAMES" = all ]; then
	212	VSNAMES=`ls $VROOTDIR \| grep -E -v "lost\+found\|ARCHIVES" \| tr "\n" " "`
	213	if [ -z "$VSNAMES" ]; then
	214	warning "VSNAMES is set to \"all\", but no VServer could be found" \
	215	"in VROOTDIR ($VROOTDIR)."
	216	fi
	217	fi
159	218	fi
160	219
161	220	if [ "$ENCRYPT_EMAIL" = "yes" ]; then
162	221	which gpg > /dev/null \|\|
163		executable_not_found "gpg" "GnuPG" "ENCRPYT_EMAIL"
164		gpg --batch --list-public-keys $EMAIL_ADDRESS >/dev/null 2>&1 \|\|
165		fatal "GnuPG public key for $EMAIL_ADDRESS not found."
	222	executable_not_found "gpg" "GnuPG" "ENCRYPT_EMAIL"
166	223	fi
167	224
168	225	DATE=`date "+%Y%m%d%H%M"`
169		WATCHED_PARENT=`dirname $WATCHED_DIR`
170		if [ "$WATCHED_PARENT" != '/' ]; then
171		WATCHED_PARENT="$WATCHED_PARENT/"
172		fi
173	226
174	227	# How to use $TAR_OPTS:
175	228	# - $TAR_OPTS should be used unquoted

196	249	done
197	250	set +o noglob
198	251
199		###
200		### Modules enabling/disabling
201		###
202
203		DO_CHANGELOGS="no"
204		if [ "$CHANGELOG_DIR" ]; then
205		if [ -d "$CHANGELOG_DIR" ]; then
206		DO_CHANGELOGS="dir"
207		fi
208		elif [ -f "$CHANGELOG_FILE" ]; then
209		DO_CHANGELOGS="file"
210		fi
211
212		# Debian packages
213		# Enabled/disabled by $DO_PACKAGES, initialized to "yes", can be
214		# overriden by the sourced conf file.
215
216	252
217	253	###
218	254	### A few functions to do the real work
219	255	###
	256
	257	# Check and mangle the context-dependant configuration variables,
	258	# i.e. the parameters specific to the host system or to a given VServer.
	259	# If $1 is empty, operate on the host system.
	260	# Else, operate on a VServer and return with exit-code:
	261	# - 2 if $1 is not an existing VServer
	262	# - 3 if $1 is not a VServer listed in VSNAMES
	263	# - 4 if $1 is not a running VServer
	264	# Anyway, return with exit-code:
	265	# - 5 if the GnuPG public key can not be found
	266	context_config() {
	267	local vsname="$1"
	268	local res
	269	debug "-------- Operating on" \
	270	"`if [ -z $vsname ]; then echo 'the host system'; else echo VServer $vsname; fi`"
	271	debug "* context_config"
	272
	273	#
	274	# Variables & VServer
	275	#
	276
	277	if [ -z "$vsname" ]; then
	278	WATCHED_DIR="$_WATCHED_DIR"
	279	BACKUP_DIR="$_BACKUP_DIR"
	280	VSERVER_EXEC_PREFIX=""
	281	EMAIL_ADDRESS="$_EMAIL_ADDRESS"
	282	else
	283	WATCHED_DIR="$VROOTDIR/$vsname/$_WATCHED_DIR"
	284	BACKUP_DIR="$_BACKUP_DIR/$vsname"
	285	VSERVER_EXEC_PREFIX="$VSERVER $vsname exec"
	286	EMAIL_ADDRESS="root@`current_system`"
	287	# does the current VServer exist ?
	288	if [ ! -d "$VROOTDIR/$vsname" ]; then
	289	warning " VServer $vsname does not exist (error 2)."
	290	return 2
	291	fi
	292	# is the current VServer listed in VSNAMES ?
	293	local found="no";
	294	for i in $VSNAMES; do
	295	if [ "$vsname" = "$i" ]; then
	296	found=yes
	297	break
	298	fi
	299	done
	300	if [ $found = no ]; then
	301	warning " VServer $vsname is not listed in VSNAMES (error 3)."
	302	return 3
	303	fi
	304	# is the current VServer running ?
	305	res=""
	306	$VSERVERINFO -q "$vsname" RUNNING \|\| res=failed
	307	if [ "$res" = failed ]; then
	308	warning " VServer $vsname is not running (error 4)."
	309	return 4
	310	fi
	311	fi
	312
	313	# E-mail encryption
	314	if [ $ENCRYPT_EMAIL = "yes" ]; then
	315	gpg --batch --list-public-keys $EMAIL_ADDRESS >/dev/null 2>&1
	316	res=$?
	317	if [ $res -ne 0 ]; then
	318	warning " GnuPG public key for $EMAIL_ADDRESS not found."
	319	return 5
	320	fi
	321	fi
	322
	323	#
	324	# Files and directories
	325	#
	326
	327	# Check the existence of WATCHED_DIR
	328	test -d "$WATCHED_DIR" \|\| \
	329	fatal "$WATCHED_DIR directory (built from WATCHED_DIR) does not exist."
	330
	331	# Initialize WATCHED_PARENT
	332	WATCHED_PARENT=`dirname $WATCHED_DIR`
	333	if [ "$WATCHED_PARENT" != '/' ]; then
	334	WATCHED_PARENT="$WATCHED_PARENT/"
	335	fi
	336
	337	# Check the existence of the resulting BACKUP_DIR, creating it if needed.
	338	if [ ! -d "$BACKUP_DIR" ]; then
	339	debug " Creating $BACKUP_DIR directory for `current_system`."
	340	if mkdir -p "$BACKUP_DIR"; then
	341	debug " Successfully created $BACKUP_DIR directory."
	342	else
	343	fatal " Failed to create $BACKUP_DIR directory."
	344	fi
	345	fi
	346
	347	#
	348	# Modules enabling/disabling
	349	#
	350
	351	# DO_CHANGELOGS
	352	DO_CHANGELOGS="no"
	353	if [ -n "$_CHANGELOG_DIR" ]; then
	354	if [ -z "$vsname" ]; then
	355	CHANGELOG_DIR="$_CHANGELOG_DIR"
	356	else
	357	CHANGELOG_DIR="$VROOTDIR/$vsname$_CHANGELOG_DIR"
	358	fi
	359	if [ -d "$CHANGELOG_DIR" ]; then
	360	DO_CHANGELOGS="dir"
	361	else
	362	warning " The directory $CHANGELOG_DIR (built from CHANGELOG_DIR)" \
	363	" does not exist. Changelogs file monitoring thereferore" \
	364	" cannot be performed this time for `current_system`."
	365	fi
	366	elif [ -n "$CHANGELOG_FILE" ]; then
	367	if [ -z "$vsname" ]; then
	368	CHANGELOG_FILE="$_CHANGELOG_FILE"
	369	else
	370	CHANGELOG_FILE="$VROOTDIR/$vsname$_CHANGELOG_FILE"
	371	fi
	372	if [ -f "$CHANGELOG_FILE" ]; then
	373	DO_CHANGELOGS="file"
	374	else
	375	warning " The file $CHANGELOG_FILE (built from CHANGELOG_FILE)"
	376	warning " does not exist. Changelog file monitoring thereferore"
	377	warning " cannot be performed this time for `current_system`."
	378	fi
	379	fi
	380
	381	# DO_PACKAGES
	382	DO_PACKAGES="$_DO_PACKAGES"
	383	if [ "$DO_PACKAGES" = "yes" ]; then
	384	$VSERVER_EXEC_PREFIX which apt-show-versions > /dev/null
	385	res=$?
	386	if [ $res -ne 0 ]; then
	387	warning " apt-show-versions not found on `current_system`."
	388	warning " Please install it or turn DO_PACKAGES off."
	389	warning " DO_PACKAGES therefore cannot be performed this time"
	390	warning " for `current_system`."
	391	DO_PACKAGES=no
	392	fi
	393	fi
	394
	395	#
	396	# Final steps to get a coherent initial status
	397	#
	398
	399	# Make sure we've got at least one testing and one stable
	400	milestone_exists testing-latest \|\| save_state "testing"
	401	milestone_exists stable-latest \|\| stabilize_state "testing-latest"
	402	}
220	403
221	404	# Returns 0 if, and only if, specified milestone exists.
222	405	milestone_exists() {

275	458
276	459	# This will save an archive of the watched directory with the given prefix
277	460	save_files() {
278		debug " - save_files $@"
	461	debug " - save_files $@"
279	462	set -o noglob
280	463	tar jcf "$BACKUP_DIR/$1-$DATE".tar.bz2 \
281	464	-C "$WATCHED_PARENT" $TAR_OPTS `basename "$WATCHED_DIR"`

285	468
286	469	# This will save packages list with the given prefix
287	470	save_packages() {
288		debug " - save_packages $@"
289		apt-show-versions -i
290		apt-show-versions \|
	471	debug " - save_packages $@"
	472	$VSERVER_EXEC_PREFIX apt-show-versions -i
	473	$VSERVER_EXEC_PREFIX apt-show-versions \|
291	474	sort > "$BACKUP_DIR/$1-$DATE".packages
292	475	ln -sf "$1-$DATE".packages "$BACKUP_DIR/$1"-latest.packages
293	476	}
294	477
295	478	# This will save Changelogs with the given prefix
296	479	save_changelogs() {
297		debug " - save_changelogs $@"
	480	debug " - save_changelogs $@"
298	481	local changelog domain file
299	482
300	483	if [ "$DO_CHANGELOGS" = "dir" ]; then

313	496
314	497	# Save whatever reflect the current state with the given prefix
315	498	save_state() {
316		debug "save_state $@"
	499	debug "* save_state $@"
317	500	save_files "$1"
318	501	[ $DO_PACKAGES = "no" ] \|\| save_packages "$1"
319	502	[ $DO_CHANGELOGS = "no" ] \|\| save_changelogs "$1"

321	504
322	505	# Report changes against given version to standard output
323	506	report_changes() {
324		debug "report_changes $@"
	507	debug "* report_changes $@"
325	508	local tmp tmpdir changelog domain diff tar_diff diff_diff
326	509	local files old new tmp_packages file
327	510

396	579	echo "$DEBIAN_PACKAGES_HEADER" >> "$tmp"
397	580
398	581	tmp_packages=`mktemp -q`
399		apt-show-versions -i
400		apt-show-versions \| sort > "$tmp_packages"
401		if diff -wEbB "$BACKUP_DIR/$1".packages "$tmp_packages"; then
	582	$VSERVER_EXEC_PREFIX apt-show-versions -i
	583	$VSERVER_EXEC_PREFIX apt-show-versions \| sort > "$tmp_packages"
	584	if diff -wEbBN "$BACKUP_DIR/$1".packages "$tmp_packages"; then
402	585	echo "$_NO_DEBIAN_PACKAGES_CHANGE"
403	586	fi \| grep -v '^[0-9-]' >> "$tmp"
404	587	fi

428	611	# Turns into stable the given testing.
429	612	# NB: argument validity is supposed to have been already checked.
430	613	stabilize_state() {
431		debug "stabilize_state $@"
	614	debug "* stabilize_state $@"
432	615	local testing stable file dst
433	616
434	617	testing="$1"

505	688	### Main
506	689	###
507	690
508		# make sure we've got at least one testing and one stable
509		milestone_exists testing-latest \|\| save_state "testing"
510		milestone_exists stable-latest \|\| stabilize_state "testing-latest"
511
512	691	case "$CMD" in
513	692
514	693	report)
	694	context_config "$VSNAME" \|\| fatal "Aborting (error $?)."
515	695	DO_DETAILS="yes"
516	696	if [ -z "$MILESTONE" ]; then
517	697	report_changes "testing-latest"

524	704	;;
525	705
526	706	list)
	707	context_config "$VSNAME" \|\| fatal "Aborting (error $?)."
527	708	for file in "$BACKUP_DIR"/*.tar.bz2; do
528	709	echo `basename ${file%%.tar.bz2}`
529	710	done

531	712
532	713	cron)
533	714	STABLE_TIME_MIN=`expr 24 '' 60 '' "$STABLE_TIME"`
534
535		### Algorithm
536		#
537		# if (no change happened for TESTING_TIME) then
538		# if (something has changed since the last testing) then
539		# send a report against last testing
540		# save a new testing state
541		# delete all saved unstable states
542		# elif (no change happened for STABLE_TIME) then
543		# if (something has changed since the last stable) then
544		# save a new stable state and notify EMAIL_ADDRESS
545		# delete all saved testing states older than STABLE_TIME
546		# fi
547		# fi
548		# elif (last unstable exists) then
549		# if (something has changed since the last unstable) then
550		# save a new unstable state
551		# fi
552		# else
553		# save a new unstable state
554		# fi
555		if no_change_since "$TESTING_TIME"; then
556		debug "no change since TESTING_TIME"
557		if changed_from "$BACKUP_DIR"/testing-latest.tar.bz2; then
558		debug "changed from testing-latest"
559		report_changes "testing-latest" \| email "testing-$DATE"
560		save_state "testing"
561		debug "removing all saved unstable states."
562		find "$BACKUP_DIR" -name 'unstable-*' -exec rm "{}" \;
563		elif no_change_since "$STABLE_TIME_MIN"; then
564		if changed_from "$BACKUP_DIR"/stable-latest.tar.bz2; then
565		save_state "stable"
566		echo "metche saved a new stable state : stable-${DATE}." \|
	715	if [ -n "$VSNAME" ]; then
	716	display_usage
	717	fatal "-h option not available for 'metche cron'"
	718	fi
	719
	720	for i in "" $VSNAMES; do
	721	res=0
	722	context_config "$i" \|\| res=$?
	723	if [ $res -ne 0 ]; then
	724	warning "-------- Ignoring" \
	725	"`if [ -z $i ]; then \
	726	echo 'the host system'; \
	727	else \
	728	echo VServer $i; fi` (error $res)"
	729	continue
	730	fi
	731
	732	### Algorithm
	733	#
	734	# if (no change happened for TESTING_TIME) then
	735	# if (something has changed since the last testing) then
	736	# send a report against last testing
	737	# save a new testing state
	738	# delete all saved unstable states
	739	# elif (no change happened for STABLE_TIME) then
	740	# if (something has changed since the last stable) then
	741	# save a new stable state and notify EMAIL_ADDRESS
	742	# delete all saved testing states older than STABLE_TIME
	743	# fi
	744	# fi
	745	# elif (last unstable exists) then
	746	# if (something has changed since the last unstable) then
	747	# save a new unstable state
	748	# fi
	749	# else
	750	# save a new unstable state
	751	# fi
	752
	753	debug "* main algorithm"
	754
	755	if no_change_since "$TESTING_TIME"; then
	756	debug " no change since TESTING_TIME"
	757	if changed_from "$BACKUP_DIR"/testing-latest.tar.bz2; then
	758	debug " changed from testing-latest"
	759	report_changes "testing-latest" \| email "testing-$DATE"
	760	save_state "testing"
	761	debug " removing all saved unstable states."
	762	find "$BACKUP_DIR" -name 'unstable-*' -exec rm "{}" \;
	763	elif no_change_since "$STABLE_TIME_MIN"; then
	764	if changed_from "$BACKUP_DIR"/stable-latest.tar.bz2; then
	765	save_state "stable"
	766	echo "metche saved a new stable state: stable-${DATE}." \|
567	767	email "stable-$DATE"
568		debug "removing all saved testing states older " \
569		"than STABLE_TIME ($STABLE_TIME)."
570		find "$BACKUP_DIR" -name 'testing-*' \
571		-ctime +"$STABLE_TIME" -exec rm "{}" \;
	768	debug " removing all saved testing states older" \
	769	"than STABLE_TIME ($STABLE_TIME)."
	770	find "$BACKUP_DIR" -name 'testing-*' \
	771	-ctime +"$STABLE_TIME" -exec rm "{}" \;
	772	fi
572	773	fi
573		fi
574		elif milestone_exists unstable-latest; then
575		if changed_from "$BACKUP_DIR"/unstable-latest.tar.bz2; then
576		debug "changed from unstable-latest"
	774	elif milestone_exists unstable-latest; then
	775	if changed_from "$BACKUP_DIR"/unstable-latest.tar.bz2; then
	776	debug " changed from unstable-latest"
	777	save_state "unstable"
	778	else
	779	debug " not changed from unstable-latest"
	780	fi
	781	else
577	782	save_state "unstable"
578	783	fi
579		else
580		save_state "unstable"
581		fi
	784
	785	done
	786
582	787	;;
583	788
584	789	stabilize)
	790	context_config "$VSNAME" \|\| fatal "Aborting (error $?)."
585	791	if [ -z "$MILESTONE" ]; then
586	792	stabilize_state "testing-latest"
587	793	elif [ "`milestone_version $MILESTONE`" = "testing" -a \

594	800	;;
595	801
596	802	test)
597		milestone_version "stable-200507040202"
598		milestone_version "testing-latest"
599		milestone_version "testing-200507030047"
600		milestone_version "testing-200507030047qsfd"
601		milestone_date "stable-200507040202"
602		milestone_date "testing-latest"
603		milestone_date "testing-200507030047"
604		milestone_date "testing-200507030047qsfd"
605		(is_latest testing-latest && echo oui) \|\| echo non
606		(is_latest testing-200507031821 && echo oui) \|\| echo non
607		(is_latest stable-200507031831 && echo oui) \|\| echo non
608		(is_latest stable-200507040202 && echo oui) \|\| echo non
	803	for i in "" $VSNAMES; do
	804	res=0
	805	context_config "$i" \|\| res=$?
	806	if [ $res -ne 0 ]; then
	807	warning "-------- Ignoring" \
	808	"`if [ -z $i ]; then \
	809	echo 'the host system'; \
	810	else \
	811	echo VServer $i; fi` (error $res)"
	812	continue
	813	fi
	814	milestone_version "stable-200507040202"
	815	milestone_version "testing-latest"
	816	milestone_date "testing-latest"
	817	#report_changes "testing-latest" \| email "testing-$DATE"
	818	done
609	819	;;
610	820
611	821	*)

+196

-0

metche-manpage.sgml less more

	0	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN"
	1	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
	2
	3	<RefEntry id="metche">
	4
	5	<refmeta>
	6	<refentrytitle>metche</refentrytitle>
	7	<manvolnum>8</manvolnum>
	8	</refmeta>
	9
	10	<refnamediv>
	11	<refname>metche</refname>
	12	<refpurpose>reducing root bus factor</refpurpose>
	13	</refnamediv>
	14
	15	<refsynopsisdiv>
	16	<cmdsynopsis>
	17	<command>metche</command>
	18	<arg>-h <replaceable>vserver</replaceable></arg>
	19	<group choice="req">
	20	<arg>report
	21	<arg choice="opt">
	22	<group choice="req">
	23	<arg>stable</arg>
	24	<arg>testing</arg>
	25	<arg>unstable</arg>
	26	</group>-<replaceable>YYYYMMDDHHMM</replaceable>
	27	</arg>
	28	</arg>
	29	<arg>list</arg>
	30	<arg>stabilize <arg choice="opt">testing-<replaceable>YYYYMMDDHHMM</replaceable></arg></arg>
	31	</group>
	32	</cmdsynopsis>
	33	</refsynopsisdiv>
	34
	35	<refsect1 id="description">
	36
	37	<title>DESCRIPTION</title>
	38
	39	<Para>metche is a tool meant to ease collective system administration by
	40	monitoring changes in the system configuration.</Para>
	41
	42	<Para>metche basic usage is to monitor changes in a directory, usually
	43	<filename>/etc</filename> ; optionally, metche can also
	44	monitor:</Para>
	45	<ItemizedList>
	46	<ListItem>
	47	<Para>one or more user maintained changelog files,</Para>
	48	</ListItem>
	49	<ListItem>
	50	<Para>the state of Debian packages and versions.</Para>
	51	</ListItem>
	52	</ItemizedList>
	53
	54	<Para>metche should be installed with a cronjob that regularly runs to
	55	automatically save the system state as needed. These states are saved in a
	56	way similar to the Debian development model:</Para>
	57	<ItemizedList>
	58	<ListItem>
	59	<Para><emphasis>unstable</emphasis> states are saved as soon as
	60	a change is detected. They are kept until a new
	61	<emphasis>testing</emphasis> state appears.</Para>
	62	</ListItem>
	63	<ListItem>
	64	<Para><emphasis>testing</emphasis> states is created from the last
	65	<emphasis>unstable</emphasis> state that has not been changed
	66	after a short amount of time (by default, one hour). Old
	67	<emphasis>unstable</emphasis> states are deleted afterwards.</Para>
	68	</ListItem>
	69	<ListItem>
	70	<Para><emphasis>stable</emphasis> states are created from the last
	71	<emphasis>testing</emphasis> state, either manually, or after a
	72	long amount of time (by default, 3 days). Old <emphasis
	73	>testing</emphasis> states are deleted afterwards.</Para>
	74	</ListItem>
	75	</ItemizedList>
	76
	77	<Para>When a new <emphasis>testing</emphasis> state is saved, an email is
	78	sent to a configurable address, giving an overwiew of
	79	the differences with the previous <emphasis>testing</emphasis>.
	80	A notification is also sent when a new <emphasis>stable</emphasis> state is
	81	saved.</Para>
	82
	83	<Para>metche's configuration is read from
	84	<filename>/etc/metche.conf</filename>. Various settings like changelog
	85	monitoring or time between system state switches are described
	86	there.</Para>
	87
	88	</refsect1>
	89	<refsect1 id="options">
	90
	91	<title>OPTIONS</title>
	92
	93	<Para>If <command>-h</command> <emphasis>VSERVER</emphasis> is specified,
	94	the VServer <emphasis>VSERVER</emphasis> is operated on instead of
	95	the host system. This, along with the <envar>VSNAMES</envar> option,
	96	allows to monitor several VServers running on the system.</Para>
	97
	98	<Para>One of the following commands must be specified on the
	99	command line:</Para>
	100
	101	<VariableList>
	102
	103	<VarListEntry><Term><command>report</command></Term>
	104	<ListItem>
	105	<Para>When run with the <command>report</command> command, metche
	106	displays a report against the specified saved state, or if unspecified,
	107	against the latest testing state. This is useful when you
	108	have broken your system and want to know which changes have been made
	109	since a given, known working, system state.</Para>
	110	</ListItem>
	111	</VarListEntry>
	112
	113	<VarListEntry><Term><command>list</command></Term>
	114	<ListItem>
	115	<Para>When run with the <command>list</command> command, metche
	116	displays a list of all the saved states.</Para>
	117	</ListItem>
	118	</VarListEntry>
	119
	120	<VarListEntry><Term><command>stabilize</command></Term>
	121	<ListItem>
	122	<Para>When run with the <command>stabilize</command> command, metche
	123	turns a "testing state" into a "stable state". By default, it will
	124	use the last "testing state", but this can be overriden by giving
	125	a specific state as argument.</Para>
	126	</ListItem>
	127	</VarListEntry>
	128
	129	<VarListEntry><Term><command>cron</command></Term>
	130	<ListItem>
	131	<Para>This command should not be called manually, but used from
	132	a cronjob. When called, it can perform various operations like:
	133	saving "unstable", "testing" or "stable" states as needed and
	134	sending reports and notification if configured to do so. This command
	135	does not support the <command>-h</command> option.</Para>
	136	</ListItem>
	137	</VarListEntry>
	138
	139	</VariableList>
	140
	141	</refsect1>
	142
	143	<refsect1 id="files"><title>FILES</title>
	144	<Para><filename>/etc/metche.conf</filename> contains metche configuration.
	145	</Para>
	146
	147	<Para>When configured to monitor one changelog,
	148	<envar>CHANGELOG_FILE</envar> (default:
	149	<filename>/root/Changelog</filename>).
	150	</Para>
	151
	152	<Para>When configured to monitor multiple changelogs,
	153	<filename>CHANGELOG_DIR/*/Changelog</filename>
	154	(default: <filename>/root/changelogs</filename>).</Para>
	155
	156	<Para>System states are saved in
	157	<envar>BACKUP_DIR</envar> (default:
	158	<filename>/var/lib/metche)</filename>.</Para>
	159	</refsect1>
	160
	161	<refsect1 id="security"><title>SECURITY</title>
	162	<Para>metche is able to use GnuPG to encrypt the email it sends, but does
	163	not by default; just enable the <envar>ENCRYPT_EMAIL</envar> configuration
	164	option, and make sure <envar>EMAIL_ADDRESS</envar>' public key is in root's
	165	keyring, trusted enough to be used blindly by metche.</Para>
	166
	167	<Para>When <envar>DO_DETAILS</envar> is enabled and
	168	<envar>ENCRYPT_EMAIL</envar> is disabled, metche sends in <emphasis>clear
	169	text email</emphasis> the changes made to the watched directory... either
	170	make sure that the <envar>EXCLUDES</envar> configuration variable prevents
	171	it to send sensitive information, or triple check that secure connections
	172	will be used end-to-end on the email path. If unsure, set
	173	<envar>EMAIL_ADDRESS</envar> configuration variable to a local mailbox.
	174	Please note that <envar>EMAIL_ADDRESS</envar> is not used for VServers:
	175	a VServer's report messages are sent to its root email address.</Para>
	176
	177	<Para>metche stores, in <envar>BACKUP_DIR</envar> (default :
	178	<filename>/var/lib/metche</filename>), various backups of
	179	<envar>WATCHED_DIR</envar>. Make sure that this backup place is at least as
	180	secured as the source.</Para>
	181	</refsect1>
	182
	183	<refsect1 id="bugs"><title>BUGS</title>
	184	<Para>See <ulink url="https://poivron.org/dev/metche/">metche's ticket
	185	system</ulink> for known bugs, missing features, and the development
	186	road-map.</Para>
	187	</refsect1>
	188
	189	<refsect1 id="author"><title>AUTHOR</title>
	190	<Para>metche and this manual page were written by the boum.org collective
	191	<email>metche@lists.riseup.net</email>.</Para>
	192	</refsect1>
	193
	194	</RefEntry>
	195

+123

-87

metche.8 less more

0		.\"Generated by db2man.xsl. Don't modify this, modify the source.
1		.de Sh \" Subsection
2		.br
3		.if t .Sp
4		.ne 5
5		.PP
6		\fB\\$1\fR
7		.PP
8		..
9		.de Sp \" Vertical space (when we can't use .PP)
10		.if t .sp .5v
11		.if n .sp
12		..
13		.de Ip \" List item
14		.br
15		.ie \\n(.$>=3 .ne \\$3
16		.el .ne 3
17		.IP "\\$1" \\$2
18		..
19		.TH "METCHE" 8 "" "" ""
20		.SH NAME
	0	.\" Title: metche
	1	.\" Author:
	2	.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
	3	.\" Date: 09/16/2006
	4	.\" Manual:
	5	.\" Source:
	6	.\"
	7	.TH "METCHE" "8" "09/16/2006" "" ""
	8	.\" disable hyphenation
	9	.nh
	10	.\" disable justification (adjust text to left margin only)
	11	.ad l
	12	.SH "NAME"
21	13	metche \- reducing root bus factor
22	14	.SH "SYNOPSIS"
23		.ad l
24		.hy 0
25	15	.HP 7
26		\fBmetche\fR {\fBcron\fR \| \fBreport\ [{\fBstable\fR\ \|\ \fBtesting\fR\ \|\ \fBunstable\fR}\-\fIYYYYMMDDHHMM\fR]\fR \| \fBlist\fR \| \fBstabilize\ [testing\-\fIYYYYMMDDHHMM\fR]\fR}
27		.ad
28		.hy
29
	16	\fBmetche\fR [\-h\ \fIvserver\fR] {[report\ [\ {[stable]\ \|\ [testing]\ \|\ [unstable]}\-\fIYYYYMMDDHHMM\fR\ ]] \| [list] \| [stabilize\ [testing\-\fIYYYYMMDDHHMM\fR]]}
30	17	.SH "DESCRIPTION"
31
32	18	.PP
33		metche is a tool meant to facilitate collective sysadmin by monitoring changes in the system configuration\&.
34
	19	metche is a tool meant to ease collective system administration by monitoring changes in the system configuration.
35	20	.PP
36		metche basic usage is to monitor changes in a directory, usually \fI/etc\fR ; optionally, metche can also monitor:
37
38		.TP 3
	21	metche basic usage is to monitor changes in a directory, usually
	22	\fI/etc\fR
	23	; optionally, metche can also monitor:
	24	.TP 3n
39	25	\(bu
40	26	one or more user maintained changelog files,
41		.TP
	27	.TP 3n
42	28	\(bu
43		the state of Debian packages and versions\&.
44		.LP
45
	29	the state of Debian packages and versions.
	30	.sp
	31	.RE
46	32	.PP
47		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:
48
49		.TP 3
	33	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:
	34	.TP 3n
50	35	\(bu
51		\fIunstable\fR states are saved as soon as a change is detected\&. They are kept until a new \fItesting\fR state appears\&.
52		.TP
	36	\fIunstable\fR
	37	states are saved as soon as a change is detected. They are kept until a new
	38	\fItesting\fR
	39	state appears.
	40	.TP 3n
53	41	\(bu
54		\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 \fIunstable\fR states are deleted afterwards\&.
55		.TP
	42	\fItesting\fR
	43	states is created from the last
	44	\fIunstable\fR
	45	state that has not been changed after a short amount of time (by default, one hour). Old
	46	\fIunstable\fR
	47	states are deleted afterwards.
	48	.TP 3n
56	49	\(bu
57		\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\&.
58		.LP
59
	50	\fIstable\fR
	51	states are created from the last
	52	\fItesting\fR
	53	state, either manually, or after a long amount of time (by default, 3 days). Old
	54	\fItesting\fR
	55	states are deleted afterwards.
	56	.sp
	57	.RE
60	58	.PP
61		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 \fIstable\fR state is saved\&.
62
	59	When a new
	60	\fItesting\fR
	61	state is saved, an email is sent to a configurable address, giving an overwiew of the differences with the previous
	62	\fItesting\fR. A notification is also sent when a new
	63	\fIstable\fR
	64	state is saved.
63	65	.PP
64		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\&.
65
	66	metche's configuration is read from
	67	\fI/etc/metche.conf\fR. Various settings like changelog monitoring or time between system state switches are described there.
66	68	.SH "OPTIONS"
67
	69	.PP
	70	If
	71	\fB\-h\fR
	72	\fIVSERVER\fR
	73	is specified, the VServer
	74	\fIVSERVER\fR
	75	is operated on instead of the host system. This, along with the
	76	\fBVSNAMES\fR
	77	option, allows to monitor several VServers running on the system.
68	78	.PP
69	79	One of the following commands must be specified on the command line:
70
71		.TP
	80	.TP 3n
72	81	\fBreport\fR
73		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\&.
74
75		.TP
	82	When run with the
	83	\fBreport\fR
	84	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.
	85	.TP 3n
76	86	\fBlist\fR
77		When run with the \fBlist\fR command, metche displays a list of all the saved states\&.
78
79		.TP
	87	When run with the
	88	\fBlist\fR
	89	command, metche displays a list of all the saved states.
	90	.TP 3n
80	91	\fBstabilize\fR
81		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\&.
82
83		.TP
	92	When run with the
	93	\fBstabilize\fR
	94	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.
	95	.TP 3n
84	96	\fBcron\fR
85		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\&.
86
	97	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
	98	\fB\-h\fR
	99	option.
87	100	.SH "FILES"
88
89	101	.PP
90		\fI/etc/metche\&.conf\fR contains metche configuration\&.
91
	102	\fI/etc/metche.conf\fR
	103	contains metche configuration.
92	104	.PP
93		When configured to monitor one changelog, \fI\fBCHANGELOG_FILE\fR\fR (default \fI/root/Changelog\fR)\&.
94
	105	When configured to monitor one changelog,
	106	\fBCHANGELOG_FILE\fR
	107	(default:
	108	\fI/root/Changelog\fR).
95	109	.PP
96		When configured to monitor multiple changelogs, \fI\fBCHANGELOG_DIR\fR/*/Changelog\fR (default : \fI/root/changelogs\fR)\&.
97
	110	When configured to monitor multiple changelogs,
	111	\fICHANGELOG_DIR/*/Changelog\fR
	112	(default:
	113	\fI/root/changelogs\fR).
98	114	.PP
99		System states are saved in \fI\fBBACKUP_DIR\fR\fR (default \fI/var/lib/metche)\fR\&.
100
	115	System states are saved in
	116	\fBBACKUP_DIR\fR
	117	(default:
	118	\fI/var/lib/metche)\fR.
101	119	.SH "SECURITY"
102
103	120	.PP
104		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\&.
105
	121	metche is able to use GnuPG to encrypt the email it sends, but does not by default; just enable the
	122	\fBENCRYPT_EMAIL\fR
	123	configuration option, and make sure
	124	\fBEMAIL_ADDRESS\fR' public key is in root's keyring, trusted enough to be used blindly by metche.
106	125	.PP
107		In its default setup (\fBENCRYPT_EMAIL\fR configuration option disabled) 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\&.
108
	126	When
	127	\fBDO_DETAILS\fR
	128	is enabled and
	129	\fBENCRYPT_EMAIL\fR
	130	is disabled, metche sends in
	131	\fIclear text email\fR
	132	the changes made to the watched directory... either make sure that the
	133	\fBEXCLUDES\fR
	134	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
	135	\fBEMAIL_ADDRESS\fR
	136	configuration variable to a local mailbox. Please note that
	137	\fBEMAIL_ADDRESS\fR
	138	is not used for VServers: a VServer's report messages are sent to its root email address.
109	139	.PP
110		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\&.
111
	140	metche stores, in
	141	\fBBACKUP_DIR\fR
	142	(default :
	143	\fI/var/lib/metche\fR), various backups of
	144	\fBWATCHED_DIR\fR. Make sure that this backup place is at least as secured as the source.
112	145	.SH "BUGS"
113
114	146	.PP
115		See metche's ticket system: \fIhttps://poivron.org/dev/metche/\fR for known bugs, missing features, and the development road\-map\&.
116
	147	See
	148	[1]\&\fImetche's ticket system\fR
	149	for known bugs, missing features, and the development road\-map.
117	150	.SH "AUTHOR"
118
119	151	.PP
120		This manual page was written by the boum collective <boum@anargeek\&.net>\&.
121
	152	metche and this manual page were written by the boum.org collective
	153	<metche@lists.riseup.net>.
	154	.SH "REFERENCES"
	155	.TP 3
	156	1.\ metche's ticket system
	157	\%https://poivron.org/dev/metche/

+29

-4

metche.conf.default less more

42	42	# - Periods (`.') or forward slashes (`/') are not considered special for
43	43	# wildcard matches.
44	44	# Example (default value):
45		#EXCLUDES=".swp # ~ .key ifstate adjtime ld.so.cache shadow* \
46		# blkid.tab* aumixrc net.enable mtab \
47		# vdirbase run.rev vdir run.rev"
	45	#EXCLUDES=".swp # ~ .gpg .key ifstate adjtime ld.so.cache shadow \
	46	# .gnupg blkid.tab* aumixrc net.enable mtab backup.d \
	47	# vdirbase run.rev vdir run.rev \
	48	# prng_exch smtp_scache.pag smtpd_scache.pag \
	49	# smtp_scache.dir smtpd_scache.dir local.sh"
48	50
49	51	# Locale (will be used to feed LC_ALL)
50	52	# Warning: values different from "C" are untested.

55	57
56	58	#######################################################################
57	59	#
	60	# Linux VServers configuration
	61	#
	62
	63	# VServers to monitor (space-separated list)
	64	# The host system is monitored, whatever VSERVERS is set to.
	65	# Set VSNAMES to "all" in order to monitor all VServers.
	66	#VSNAMES=""
	67	#VSNAMES="name1 name2"
	68	#VSNAMES="all"
	69
	70	# vserver-info command location (default: /usr/sbin/vserver-info)
	71	#VSERVERINFO=/usr/sbin/vserver-info
	72
	73	# vserver command location (default: /usr/sbin/vserver)
	74	#VSERVER=/usr/sbin/vserver
	75
	76	# Directory where the VServers live; example: a VServer called "twiki"
	77	# will have its root directory in $VROOTDIR/twiki
	78	# (default: /var/lib/vservers)
	79	#VROOTDIR=/var/lib/vservers
	80
	81	#######################################################################
	82	#
58	83	# Localizable strings
59	84	#
60	85
61	86	# Add your custom headers below
62	87
63		#_MAIL_SUBJECT="`hostname -f` - changes report"
	88	#_MAIL_SUBJECT="changes report"
64	89	#_NO_DEBIAN_PACKAGES_CHANGE="No change in Debian packages state."
65	90	#_NO_CHANGE="No change."
66	91	#MAIN_HEADER=""