Commit 65b7183f95282dc01b5c78464feee52fb63e3b2f - metche

Splitted the doc into manpage, README, INSTALL. Added a Makefile to build the manpage from SGML source. intrigeri 17 years ago

5 changed file(s) with 252 addition(s) and 21 deletion(s). Raw diff Collapse all Expand all

-0

INSTALL less more

	0	,-------------------------------------------------------------------------------
	1	\| INSTALLATION
	2	`-------------------------------------------------------------------------------
	3
	4	1. Copy the metche executable to /usr/local/sbin/
	5	2. As root, mkdir /var/lib/metche
	6	3. Copy the manpage (metche.8) to /usr/local/man/man8/
	7	4. Read the README file and the manpage
	8

+11

-0

Makefile less more

	0	default: doc
	1
	2	manpage:
	3	sgml2xml -xlower -xid metche-manpage.sgml > metche-manpage.xml
	4	db2x_xsltproc -s /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl metche-manpage.xml
	5
	6	doc: manpage
	7
	8	clean:
	9	test ! -f metche.8 \|\| rm metche.8
	10	test ! -f metche-manpage.xml \|\| rm -f metche-manpage.xml

+14

-21

README less more

40	40	address ;
41	41	- use the Changelog files in a rigorous way.
42	42
43		Note: it is dangerous to use metche without before reading the SECURITY WARNINGS
44		section.
	43	Note: it is dangerous to use metche without before reading the SECURITY section
	44	of the manpage.
45	45
46		For a deeper explanation of the way metche works, read the USAGE & FAQ sections.
	46	For a deeper explanation of the way metche works, read the manpage.
47	47
48	48	,-------------------------------------------------------------------------------
49	49	\| REQUIREMENTS
50	50	`-------------------------------------------------------------------------------
51	51
52		1. Debian GNU/Linux
53		2. apt-show-versions
54		3. mutt
55		4. If you want metche to monitor your vservers as well : util-vserver tools
56		5. At least one Changelog file in $CHANGELOG_DIR/*/Changelog ; for example, you
	52	1. Debian GNU/Linux and apt-show-versions (if Debian packages monitoring is
	53	enabled)
	54	2. mutt
	55	3. If you want metche to monitor your vservers as well : util-vserver tools
	56	4. If you want metche to monitor your Changelog files, at least one Changelog
	57	file must be located in $CHANGELOG_DIR/*/Changelog ; for example, you
57	58	can have :
58	59	/root/
59	60	changelogs/

65	66	\| INSTALLATION
66	67	`-------------------------------------------------------------------------------
67	68
68		1. Copy the metche executable to /usr/local/sbin/
69		2. As root, mkdir /var/lib/metche
	69	See the included INSTALL file.
70	70
71	71	,-------------------------------------------------------------------------------
72	72	\| CONFIGURATION

76	76
77	77	1. Copy metche.conf.default to /etc/metche.conf and edit it so that it suits
78	78	your needs.
79		2. Read the next sections of this document.
	79	2. Read the next sections of this document and the manpage.
80	80	3. Add to /etc/cron.d/metche something like :
81	81	0-59/5 * * * * root test -x /usr/local/sbin/metche && \
82	82	/usr/local/sbin/metche cron

94	94	- edit <host>.conf so that it suits your needs
95	95	- if the system to monitor is a vserver, edit <host>.conf to set
96	96	VSERVER_EXEC_PREFIX to something like "/usr/sbin/vserver <host> exec"
97		3. Read the next sections of this document.
	97	3. Read the next sections of this document and the manpage.
98	98	4. For each system to monitor, add to /etc/cron.d/metche something like :
99	99	0-59/5 * * * * root test -x /usr/local/sbin/metche && \
100	100	/usr/local/sbin/metche -h <host> cron
101	101
102	102	,-------------------------------------------------------------------------------
103		\| SECURITY WARNINGS
	103	\| SECURITY : BIG FAT WARNING
104	104	`-------------------------------------------------------------------------------
105	105
106		1. metche sends in clear text email the changes made to /etc... either make
107		sure that the TAR_OPTS config variable prevents it to send sensitive
108		information, or triple check that TLS/SSL will be used end-to-end on the
109		email path. If unsure, set $EMAIL_ADDRESS to a local mailbox.
110
111		2. metche stores in $BACKUP_DIR various backups of $WATCHED_DIR (default: /etc)
112		and $CHANGELOG_DIR (default: /root/changelogs) ; of course, metche uses 077
113		as umask, but... you have to be aware of this.
	106	Read the SECURITY section of metche(8). Really.
114	107
115	108	,-------------------------------------------------------------------------------
116	109	\| FAQ

+122

-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>host</replaceable></arg>
	19	<group choice="req">
	20	<arg choice="req">cron</arg>
	21	<arg choice="req">report <arg choice="opt"><replaceable>milestone</replaceable></arg></arg>
	22	<arg choice="req">list</arg>
	23	</group>
	24	</cmdsynopsis>
	25	</refsynopsisdiv>
	26
	27	<refsect1 id="description">
	28
	29	<title>DESCRIPTION</title>
	30	<para>metche is a tool meant to facilitate collective sysadmin, by
	31	monitoring changes in the system configuration. At least
	32	<envar>WATCHED_DIR</envar> (default: <filename>/etc</filename>) is
	33	monitored ; optionally, metche can also monitor :</para>
	34	<itemizedlist>
	35	<listitem>
	36	<para>system Changelog files located in
	37	<filename><envar>CHANGELOG_DIR</envar>/*/Changelog</filename> (default:
	38	<filename>/root/changelogs/*/Changelog</filename>)</para>
	39	</listitem>
	40	<listitem>
	41	<para>Debian packages states and versions</para>
	42	</listitem>
	43	</itemizedlist>
	44
	45	<para><envar>WATCHED_DIR</envar> and <envar>CHANGELOG_DIR</envar> options
	46	can me customized in metche's configuration file, as well as a few other
	47	ones.</para>
	48
	49	<para>If <command>-h</command> <emphasis>HOST</emphasis> is specified,
	50	<filename>/etc/metche/HOST.conf</filename> is used instead of
	51	<filename>/etc/metche.conf</filename>. This, along with the
	52	<envar>VSERVER_EXEC_PREFIX</envar> option, allows to monitor several
	53	vservers running on a system.</para>
	54
	55	<para>Anyway, one of the following commands has to be specified on the
	56	command line :</para>
	57
	58	<refsect2 id="cron"><title>cron</title>
	59	<para>When run (usually by a cronjob) with the <command>cron</command>
	60	command, metche looks if the system configuration has changed in the last
	61	<envar>$TESTING_TIME</envar> minutes. If it is the case, a "unstable
	62	state" is saved. Otherwise, a "testing state" (also called a "milestone")
	63	is saved, and a report (see <ulink
	64	url="https://poivron.org/dev/metche/">metche's homepage</ulink> for an
	65	example) is emailed to you.</para>
	66	</refsect2>
	67
	68	<refsect2 id="report"><title>report [<emphasis>milestone</emphasis>]</title>
	69	<para>When run with the <command>report</command> command, metche displays
	70	a report against a given milestone, if specified, or against the latest
	71	one, otherwise. This is useful when you have broken your system and want
	72	to know which changes have been made since a given, known working,
	73	milestone.</para>
	74	</refsect2>
	75
	76	<refsect2 id="list"><title>list</title>
	77	<para>When run with the <command>list</command> command, metche displays
	78	the full saved states list.</para>
	79	</refsect2>
	80
	81	</refsect1>
	82
	83	<refsect1 id="files"><title>FILES</title>
	84	<para><filename>/etc/metche.conf</filename> or
	85	<filename>/etc/metche/*.conf</filename> : configuration file(s)</para>
	86
	87	<para><filename><envar>CHANGELOG_DIR</envar>/*/Changelog</filename>
	88	(default : <filename>/root/changelogs</filename>), if Changelog monitoring
	89	is enabled : Changelog files location</para>
	90
	91	<para><filename><envar>BACKUP_DIR</envar></filename> : directory containing
	92	the backups</para>
	93	</refsect1>
	94
	95	<refsect1 id="security"><title>SECURITY</title>
	96	<para>metche sends in <emphasis>clear text email</emphasis> the changes made
	97	to the watched directory... either make sure that the
	98	<envar>TAR_OPTS</envar> configuration variable prevents it to send sensitive
	99	information, or triple check that secure connections will be used end-to-end
	100	on the email path. If unsure, set <envar>EMAIL_ADDRESS</envar> configuration
	101	variable to a local mailbox.</para>
	102
	103	<para>metche stores, in <envar>BACKUP_DIR</envar> (default :
	104	<filename>/var/lib/metche</filename>), various backups of
	105	<envar>WATCHED_DIR</envar>. Make sure that the backup place is at least as
	106	secure as the source.
	107	</refsect1>
	108
	109	<refsect1 id="bugs"><title>BUGS</title>
	110	<para>See <ulink url="https://poivron.org/dev/metche/">metche's ticket
	111	system</ulink> to see the bugs, missing features, and development
	112	road-map.</para>
	113	</refsect1>
	114
	115	<refsect1 id="author"><title>AUTHOR</title>
	116	<para>This manual page was written by Intri Geri
	117	<email>intrigeri@boum.org</email>.</para>
	118	</refsect1>
	119
	120	</RefEntry>
	121

+96

-0

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
	21	metche \- reducing root bus factor
	22	.SH "SYNOPSIS"
	23	.ad l
	24	.hy 0
	25	.HP 7
	26	\fBmetche\fR [\-h\ \fIhost\fR] {\fBcron\fR \| \fBreport\ [\fImilestone\fR]\fR \| \fBlist\fR}
	27	.ad
	28	.hy
	29
	30	.SH "DESCRIPTION"
	31
	32	.PP
	33	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 :
	34
	35	.TP 3
	36	\(bu
	37	system Changelog files located in\fI\fBCHANGELOG_DIR\fR//Changelog\fR (default:\fI/root/changelogs//Changelog\fR)
	38	.TP
	39	\(bu
	40	Debian packages states and versions
	41	.LP
	42
	43	.PP
	44	\fBWATCHED_DIR\fR and \fBCHANGELOG_DIR\fR options can me customized in metche's configuration file, as well as a few other ones\&.
	45
	46	.PP
	47	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\&.
	48
	49	.PP
	50	Anyway, one of the following commands has to be specified on the command line :
	51
	52	.SS "cron"
	53
	54	.PP
	55	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\&.
	56
	57	.SS "report [milestone]"
	58
	59	.PP
	60	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\&.
	61
	62	.SS "list"
	63
	64	.PP
	65	When run with the \fBlist\fR command, metche displays the full saved states list\&.
	66
	67	.SH "FILES"
	68
	69	.PP
	70	\fI/etc/metche\&.conf\fR or \fI/etc/metche/*\&.conf\fR : configuration file(s)
	71
	72	.PP
	73	\fI\fBCHANGELOG_DIR\fR/*/Changelog\fR (default : \fI/root/changelogs\fR), if Changelog monitoring is enabled : Changelog files location
	74
	75	.PP
	76	\fI\fBBACKUP_DIR\fR\fR : directory containing the backups
	77
	78	.SH "SECURITY"
	79
	80	.PP
	81	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\&.
	82
	83	.PP
	84	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\&.
	85
	86	.SH "BUGS"
	87
	88	.PP
	89	See metche's ticket system: \fIhttps://poivron.org/dev/metche/\fR to see the bugs, missing features, and development road\-map\&.
	90
	91	.SH "AUTHOR"
	92
	93	.PP
	94	This manual page was written by Intri Geri <intrigeri@boum\&.org>\&.
	95