0 | |
'\" t
|
1 | |
.\" Title: metche
|
2 | |
.\" Author: [see the "AUTHOR" section]
|
3 | |
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
|
4 | |
.\" Date: 12/16/2009
|
5 | |
.\" Manual: [FIXME: manual]
|
6 | |
.\" Source: [FIXME: source]
|
7 | |
.\" Language: English
|
8 | |
.\"
|
9 | |
.TH "METCHE" "8" "12/16/2009" "[FIXME: source]" "[FIXME: manual]"
|
10 | |
.\" -----------------------------------------------------------------
|
11 | |
.\" * Define some portability stuff
|
12 | |
.\" -----------------------------------------------------------------
|
13 | |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
14 | |
.\" http://bugs.debian.org/507673
|
15 | |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
16 | |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
17 | |
.ie \n(.g .ds Aq \(aq
|
18 | |
.el .ds Aq '
|
19 | |
.\" -----------------------------------------------------------------
|
20 | |
.\" * set default formatting
|
21 | |
.\" -----------------------------------------------------------------
|
22 | |
.\" disable hyphenation
|
23 | |
.nh
|
24 | |
.\" disable justification (adjust text to left margin only)
|
25 | |
.ad l
|
26 | |
.\" -----------------------------------------------------------------
|
27 | |
.\" * MAIN CONTENT STARTS HERE *
|
28 | |
.\" -----------------------------------------------------------------
|
29 | |
.SH "NAME"
|
30 | |
metche \- reducing root bus factor
|
31 | |
.SH "SYNOPSIS"
|
32 | |
.HP \w'\fBmetche\fR\ 'u
|
33 | |
\fBmetche\fR [\-h\ \fIvserver\fR] {[report\ [\ {[stable]\ |\ [testing]\ |\ [unstable]}\-\fIYYYYMMDDHHMM\fR\ ]] | [list] | [stabilize\ [testing\-\fIYYYYMMDDHHMM\fR]]}
|
34 | |
.SH "DESCRIPTION"
|
|
0 |
.TH METCHE 8 "June 5, 2011" "metche user manual"
|
|
1 |
.SH NAME
|
35 | 2 |
.PP
|
36 | |
metche is a tool meant to ease collective system administration by monitoring changes in the system configuration\&.
|
|
3 |
metche - reducing root bus factor
|
|
4 |
.SH SYNOPSIS
|
|
5 |
.PP
|
|
6 |
\f[CR]
|
|
7 |
metche\ [-h\ VSERVER]\ report\ (stable|testing|unstable)-YYYYMMDDHHMM
|
|
8 |
metche\ [-h\ VSERVER]\ list
|
|
9 |
metche\ [-h\ VSERVER]\ stabilize\ testing-YYYYMMDDHHMM
|
|
10 |
\f[]
|
|
11 |
.SH DESCRIPTION
|
|
12 |
.PP
|
|
13 |
metche is a tool meant to ease collective system administration by
|
|
14 |
monitoring changes in the system configuration.
|
37 | 15 |
.PP
|
38 | 16 |
metche basic usage is to monitor changes in a directory, usually
|
39 | |
/etc
|
40 | |
; optionally, metche can also monitor:
|
41 | |
.sp
|
42 | |
.RS 4
|
43 | |
.ie n \{\
|
44 | |
\h'-04'\(bu\h'+03'\c
|
45 | |
.\}
|
46 | |
.el \{\
|
47 | |
.sp -1
|
48 | |
.IP \(bu 2.3
|
49 | |
.\}
|
|
17 |
\f[B]/etc\f[]; optionally, metche can also monitor:
|
|
18 |
.IP \[bu] 2
|
50 | 19 |
one or more user maintained changelog files,
|
|
20 |
.IP \[bu] 2
|
|
21 |
the state of Debian packages and versions.
|
|
22 |
.PP
|
|
23 |
metche should be installed with a cronjob that regularly runs to
|
|
24 |
automatically save the system state as needed.
|
|
25 |
These states are saved in a way similar to the Debian development
|
|
26 |
model:
|
|
27 |
.IP \[bu] 2
|
|
28 |
\f[I]unstable\f[] states are saved as soon as a change is detected.
|
|
29 |
They are kept until a new \f[I]testing\f[] state appears.
|
|
30 |
.IP \[bu] 2
|
|
31 |
\f[I]testing\f[] states is created from the last \f[I]unstable\f[]
|
|
32 |
state that has not been changed after a short amount of time (by
|
|
33 |
default, one hour).
|
|
34 |
Old \f[I]unstable\f[] states are deleted afterwards.
|
|
35 |
.IP \[bu] 2
|
|
36 |
\f[I]stable\f[] states are created from the last \f[I]testing\f[]
|
|
37 |
state, either manually, or after a long amount of time (by default,
|
|
38 |
3 days).
|
|
39 |
Old \f[I]testing\f[] states are deleted afterwards.
|
|
40 |
.PP
|
|
41 |
When a new \f[I]testing\f[] state is saved, an email is sent to a
|
|
42 |
configurable address, giving an overwiew of the differences with
|
|
43 |
the previous \f[I]testing\f[].
|
|
44 |
A notification is also sent when a new \f[I]stable\f[] state is
|
|
45 |
saved.
|
|
46 |
.PP
|
|
47 |
metche's configuration is read from \f[B]/etc/metche.conf\f[].
|
|
48 |
Various settings like changelog monitoring or time between system
|
|
49 |
state switches are described there.
|
|
50 |
.SH OPTIONS
|
|
51 |
.PP
|
|
52 |
If \f[B]-h\ VSERVER\f[] is specified, the VServer \f[I]VSERVER\f[]
|
|
53 |
is operated on instead of the host system.
|
|
54 |
This, along with the \f[B]VSNAMES\f[] option, allows to monitor
|
|
55 |
several VServers running on the system.
|
|
56 |
.PP
|
|
57 |
One of the following commands must be specified on the command
|
|
58 |
line:
|
|
59 |
.TP
|
|
60 |
.B report
|
|
61 |
When run with the \f[I]report\f[] command, metche displays a report
|
|
62 |
against the specified saved state, or if unspecified, against the
|
|
63 |
latest testing state.
|
|
64 |
This is useful when you have broken your system and want to know
|
|
65 |
which changes have been made since a given, known working, system
|
|
66 |
state.
|
|
67 |
.RS
|
51 | 68 |
.RE
|
52 | |
.sp
|
53 | |
.RS 4
|
54 | |
.ie n \{\
|
55 | |
\h'-04'\(bu\h'+03'\c
|
56 | |
.\}
|
57 | |
.el \{\
|
58 | |
.sp -1
|
59 | |
.IP \(bu 2.3
|
60 | |
.\}
|
61 | |
the state of Debian packages and versions\&.
|
|
69 |
.TP
|
|
70 |
.B list
|
|
71 |
When run with the \f[I]list\f[] command, metche displays a list of
|
|
72 |
all the saved states.
|
|
73 |
.RS
|
62 | 74 |
.RE
|
|
75 |
.TP
|
|
76 |
.B stabilize
|
|
77 |
When run with the \f[I]stabilize\f[] command, metche turns a
|
|
78 |
\[lq]testing state\[rq] into a \[lq]stable state\[rq].
|
|
79 |
By default, it will use the last \[lq]testing state\[rq], but this
|
|
80 |
can be overriden by giving a specific state as argument.
|
|
81 |
.RS
|
|
82 |
.RE
|
|
83 |
.TP
|
|
84 |
.B cron
|
|
85 |
This command should not be called manually, but used from a
|
|
86 |
cronjob.
|
|
87 |
When called, it can perform various operations like: saving
|
|
88 |
\[lq]unstable\[rq], \[lq]testing\[rq] or \[lq]stable\[rq] states as
|
|
89 |
needed and sending reports and notification if configured to do so.
|
|
90 |
This command does not support the \f[B]-h\f[] option.
|
|
91 |
.RS
|
|
92 |
.RE
|
|
93 |
.SH FILES
|
63 | 94 |
.PP
|
64 | |
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:
|
65 | |
.sp
|
66 | |
.RS 4
|
67 | |
.ie n \{\
|
68 | |
\h'-04'\(bu\h'+03'\c
|
69 | |
.\}
|
70 | |
.el \{\
|
71 | |
.sp -1
|
72 | |
.IP \(bu 2.3
|
73 | |
.\}
|
74 | |
\fIunstable\fR
|
75 | |
states are saved as soon as a change is detected\&. They are kept until a new
|
76 | |
\fItesting\fR
|
77 | |
state appears\&.
|
78 | |
.RE
|
79 | |
.sp
|
80 | |
.RS 4
|
81 | |
.ie n \{\
|
82 | |
\h'-04'\(bu\h'+03'\c
|
83 | |
.\}
|
84 | |
.el \{\
|
85 | |
.sp -1
|
86 | |
.IP \(bu 2.3
|
87 | |
.\}
|
88 | |
\fItesting\fR
|
89 | |
states is created from the last
|
90 | |
\fIunstable\fR
|
91 | |
state that has not been changed after a short amount of time (by default, one hour)\&. Old
|
92 | |
\fIunstable\fR
|
93 | |
states are deleted afterwards\&.
|
94 | |
.RE
|
95 | |
.sp
|
96 | |
.RS 4
|
97 | |
.ie n \{\
|
98 | |
\h'-04'\(bu\h'+03'\c
|
99 | |
.\}
|
100 | |
.el \{\
|
101 | |
.sp -1
|
102 | |
.IP \(bu 2.3
|
103 | |
.\}
|
104 | |
\fIstable\fR
|
105 | |
states are created from the last
|
106 | |
\fItesting\fR
|
107 | |
state, either manually, or after a long amount of time (by default, 3 days)\&. Old
|
108 | |
\fItesting\fR
|
109 | |
states are deleted afterwards\&.
|
110 | |
.RE
|
|
95 |
\f[B]/etc/metche.conf\f[] contains metche configuration.
|
111 | 96 |
.PP
|
112 | |
When a new
|
113 | |
\fItesting\fR
|
114 | |
state is saved, an email is sent to a configurable address, giving an overwiew of the differences with the previous
|
115 | |
\fItesting\fR\&. A notification is also sent when a new
|
116 | |
\fIstable\fR
|
117 | |
state is saved\&.
|
118 | |
.PP
|
119 | |
metche\*(Aqs configuration is read from
|
120 | |
/etc/metche\&.conf\&. Various settings like changelog monitoring or time between system state switches are described there\&.
|
121 | |
.SH "OPTIONS"
|
122 | |
.PP
|
123 | |
If
|
124 | |
\fB\-h\fR
|
125 | |
\fIVSERVER\fR
|
126 | |
is specified, the VServer
|
127 | |
\fIVSERVER\fR
|
128 | |
is operated on instead of the host system\&. This, along with the
|
129 | |
\fBVSNAMES\fR
|
130 | |
option, allows to monitor several VServers running on the system\&.
|
131 | |
.PP
|
132 | |
One of the following commands must be specified on the command line:
|
133 | |
.PP
|
134 | |
\fBreport\fR
|
135 | |
.RS 4
|
136 | |
When run with the
|
137 | |
\fBreport\fR
|
138 | |
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\&.
|
139 | |
.RE
|
140 | |
.PP
|
141 | |
\fBlist\fR
|
142 | |
.RS 4
|
143 | |
When run with the
|
144 | |
\fBlist\fR
|
145 | |
command, metche displays a list of all the saved states\&.
|
146 | |
.RE
|
147 | |
.PP
|
148 | |
\fBstabilize\fR
|
149 | |
.RS 4
|
150 | |
When run with the
|
151 | |
\fBstabilize\fR
|
152 | |
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\&.
|
153 | |
.RE
|
154 | |
.PP
|
155 | |
\fBcron\fR
|
156 | |
.RS 4
|
157 | |
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
|
158 | |
\fB\-h\fR
|
159 | |
option\&.
|
160 | |
.RE
|
161 | |
.SH "FILES"
|
162 | |
.PP
|
163 | |
/etc/metche\&.conf
|
164 | |
contains metche configuration\&.
|
165 | |
.PP
|
166 | |
When configured to monitor one changelog,
|
167 | |
\fBCHANGELOG_FILE\fR
|
168 | |
(default:
|
169 | |
/root/Changelog)\&.
|
|
97 |
When configured to monitor one changelog, \f[B]CHANGELOG_FILE\f[]
|
|
98 |
(default: \f[B]/root/Changelog\f[]).
|
170 | 99 |
.PP
|
171 | 100 |
When configured to monitor multiple changelogs,
|
172 | |
CHANGELOG_DIR/*/Changelog
|
173 | |
(default:
|
174 | |
/root/changelogs)\&.
|
|
101 |
\f[B]CHANGELOG_DIR/*/Changelog\f[] (default:
|
|
102 |
\f[B]/root/changelogs\f[]).
|
175 | 103 |
.PP
|
176 | |
System states are saved in
|
177 | |
\fBBACKUP_DIR\fR
|
178 | |
(default:
|
179 | |
/var/lib/metche)\&.
|
180 | |
.SH "SECURITY"
|
|
104 |
System states are saved in \f[B]BACKUP_DIR\f[] (default:
|
|
105 |
\f[B]/var/lib/metche\f[]).
|
|
106 |
.SH SECURITY
|
181 | 107 |
.PP
|
182 | |
metche is able to use GnuPG to encrypt the email it sends, but does not by default; just enable the
|
183 | |
\fBENCRYPT_EMAIL\fR
|
184 | |
configuration option, and make sure
|
185 | |
\fBEMAIL_ADDRESS\fR\*(Aq public key is in root\*(Aqs keyring, trusted enough to be used blindly by metche\&. If
|
186 | |
\fBEMAIL_ADDRESS\fR
|
187 | |
is an email alias or mailing\-list\*(Aqs address, you probably want to use the
|
188 | |
\fBgroup\fR
|
189 | |
option in
|
190 | |
/root/\&.gnupg/gpg\&.conf
|
191 | |
so that metche reports are encrypted for every person subscribed to this alias or mailing\-list; for more information, see
|
192 | |
gpg(1)\&.
|
|
108 |
metche is able to use GnuPG to encrypt the email it sends, but does
|
|
109 |
not by default; just enable the \f[B]ENCRYPT_EMAIL\f[]
|
|
110 |
configuration option, and make sure \f[B]EMAIL_ADDRESS\f[]' public
|
|
111 |
key is in root's keyring, trusted enough to be used blindly by
|
|
112 |
metche.
|
|
113 |
If \f[B]EMAIL_ADDRESS\f[] is an email alias or mailing-list's
|
|
114 |
address, you probably want to use the \f[B]group\f[] option in
|
|
115 |
\f[B]/root/.gnupg/gpg.conf\f[] so that metche reports are encrypted
|
|
116 |
for every person subscribed to this alias or mailing-list; for more
|
|
117 |
information, see \f[B]gpg(1)\f[].
|
193 | 118 |
.PP
|
194 | |
When
|
195 | |
\fBDO_DETAILS\fR
|
196 | |
is enabled and
|
197 | |
\fBENCRYPT_EMAIL\fR
|
198 | |
is disabled, metche sends in
|
199 | |
\fIclear text email\fR
|
200 | |
the changes made to the watched directory\&.\&.\&. either make sure that the
|
201 | |
\fBEXCLUDES\fR
|
202 | |
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
|
203 | |
\fBEMAIL_ADDRESS\fR
|
204 | |
configuration variable to a local mailbox\&. Please note that
|
205 | |
\fBEMAIL_ADDRESS\fR
|
206 | |
is not used for VServers: a VServer\*(Aqs report messages are sent to its root email address\&.
|
|
119 |
When \f[B]DO_DETAILS\f[] is enabled and \f[B]ENCRYPT_EMAIL\f[] is
|
|
120 |
disabled, metche sends in \f[I]clear text email\f[] the changes
|
|
121 |
made to the watched directory\&... either make sure that the
|
|
122 |
\f[B]EXCLUDES\f[] configuration variable prevents it to send
|
|
123 |
sensitive information, or triple check that secure connections will
|
|
124 |
be used end-to-end on the email path.
|
|
125 |
If unsure, set \f[B]EMAIL_ADDRESS\f[] configuration variable to a
|
|
126 |
local mailbox.
|
|
127 |
Please note that \f[B]EMAIL_ADDRESS\f[] is not used for VServers: a
|
|
128 |
VServer's report messages are sent to its root email address.
|
207 | 129 |
.PP
|
208 | |
metche stores, in
|
209 | |
\fBBACKUP_DIR\fR
|
210 | |
(default :
|
211 | |
/var/lib/metche), various backups of
|
212 | |
\fBWATCHED_DIR\fR\&. Make sure that this backup place is at least as secured as the source\&.
|
213 | |
.SH "BUGS"
|
|
130 |
metche stores, in \f[B]BACKUP_DIR\f[] (default:
|
|
131 |
\f[B]/var/lib/metche\f[]), various backups of \f[B]WATCHED_DIR\f[].
|
|
132 |
Make sure that this backup place is at least as secured as the
|
|
133 |
source.
|
|
134 |
.SH BUGS
|
214 | 135 |
.PP
|
215 | 136 |
See
|
216 | |
\m[blue]\fBmetche\*(Aqs ticket system\fR\m[]\&\s-2\u[1]\d\s+2
|
217 | |
for known bugs, missing features, and the development road\-map\&.
|
218 | |
.SH "AUTHOR"
|
219 | |
.PP
|
220 | |
metche and this manual page were written by the boum\&.org collective
|
221 | |
metche@lists\&.riseup\&.net\&.
|
222 | |
.SH "NOTES"
|
223 | |
.IP " 1." 4
|
224 | |
metche's ticket system
|
225 | |
.RS 4
|
226 | |
\%https://dev.potager.org/metche/
|
227 | |
.RE
|
|
137 |
metche's ticket system (https://labs.riseup.net/code/projects/metche/issues)
|
|
138 |
for known bugs, missing features, and the development road-map.
|
|
139 |
.SH AUTHORS
|
|
140 |
metche and this manual page were written by the boum.org collective, and are now maintained by the metche developers collective <metche@lists.riseup.net>.
|
|
141 |
|