Codebase list metche / 8d142b9
Translate manpage source to Pandoc markdown, adapt Makefile. Since I'm not at ease with the old DocBook / XML manpage source and generation process, fixing its current broken state seemed harder than switching to a source format and build process I understand much more clearly. intrigeri 12 years ago
3 changed file(s) with 130 addition(s) and 208 deletion(s). Raw diff Collapse all Expand all
+2
-6
Makefile less more
00 all: doc
11
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 $<
2 metche.8: metche.8.markdown
3 pandoc --read=markdown --write=man --output=metche.8 --standalone $<
74
85 doc: metche.8
96
107 clean:
11 rm -f metche-manpage.xml
128
139 distclean: clean
1410 rm -f metche.8
+0
-202
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.
166 If <envar>EMAIL_ADDRESS</envar> is an email alias or mailing-list's address,
167 you probably want to use the <envar>group</envar> option
168 in <filename>/root/.gnupg/gpg.conf</filename> so that metche reports are
169 encrypted for every person subscribed to this alias or mailing-list; for
170 more information, see <literal>gpg</literal>(1).</Para>
171
172 <Para>When <envar>DO_DETAILS</envar> is enabled and
173 <envar>ENCRYPT_EMAIL</envar> is disabled, metche sends in <emphasis>clear
174 text email</emphasis> the changes made to the watched directory... either
175 make sure that the <envar>EXCLUDES</envar> configuration variable prevents
176 it to send sensitive information, or triple check that secure connections
177 will be used end-to-end on the email path. If unsure, set
178 <envar>EMAIL_ADDRESS</envar> configuration variable to a local mailbox.
179 Please note that <envar>EMAIL_ADDRESS</envar> is not used for VServers:
180 a VServer's report messages are sent to its root email address.</Para>
181
182 <Para>metche stores, in <envar>BACKUP_DIR</envar> (default :
183 <filename>/var/lib/metche</filename>), various backups of
184 <envar>WATCHED_DIR</envar>. Make sure that this backup place is at least as
185 secured as the source.</Para>
186 </refsect1>
187
188 <refsect1 id="bugs"><title>BUGS</title>
189 <Para>See <ulink url="https://labs.riseup.net/code/projects/metche/issues">metche's
190 ticket system</ulink> for known bugs, missing features, and the development
191 road-map.</Para>
192 </refsect1>
193
194 <refsect1 id="author"><title>AUTHOR</title>
195 <Para>metche and this manual page were written by the boum.org collective,
196 and are now maintained by the metche developers collective
197 <email>metche@lists.riseup.net</email>.</Para>
198 </refsect1>
199
200 </RefEntry>
201
+128
-0
metche.8.markdown less more
0 % METCHE(8) metche user manual
1 % 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>
2 % June 5, 2011
3
4 NAME
5 ====
6
7 metche - reducing root bus factor
8
9 SYNOPSIS
10 ========
11
12 metche [-h VSERVER] report (stable|testing|unstable)-YYYYMMDDHHMM
13 metche [-h VSERVER] list
14 metche [-h VSERVER] stabilize testing-YYYYMMDDHHMM
15
16 DESCRIPTION
17 ===========
18
19 metche is a tool meant to ease collective system administration by
20 monitoring changes in the system configuration.
21
22 metche basic usage is to monitor changes in a directory, usually
23 `/etc`; optionally, metche can also monitor:
24
25 * one or more user maintained changelog files,
26 * the state of Debian packages and versions.
27
28 metche should be installed with a cronjob that regularly runs to
29 automatically save the system state as needed. These states are saved
30 in a way similar to the Debian development model:
31
32 * _unstable_ states are saved as soon as a change is detected. They
33 are kept until a new _testing_ state appears.
34 * _testing_ states is created from the last _unstable_ state that has
35 not been changed after a short amount of time (by default, one
36 hour). Old _unstable_ states are deleted afterwards.
37 * _stable_ states are created from the last _testing_ state, either
38 manually, or after a long amount of time (by default, 3 days). Old
39 _testing_ states are deleted afterwards.
40
41 When a new _testing_ state is saved, an email is sent to a
42 configurable address, giving an overwiew of the differences with the
43 previous _testing_. A notification is also sent when a new _stable_
44 state is saved.
45
46 metche's configuration is read from `/etc/metche.conf`. Various
47 settings like changelog monitoring or time between system state
48 switches are described there.
49
50 OPTIONS
51 =======
52
53 If `-h VSERVER` is specified, the VServer _VSERVER_ is operated on
54 instead of the host system. This, along with the `VSNAMES` option,
55 allows to monitor several VServers running on the system.
56
57 One of the following commands must be specified on the command line:
58
59 report
60 : When run with the _report_ command, metche displays a report
61 against the specified saved state, or if unspecified, against the
62 latest testing state. This is useful when you have broken your
63 system and want to know which changes have been made since a
64 given, known working, system state.
65
66 list
67 : When run with the _list_ command, metche displays a list of all
68 the saved states.
69
70 stabilize
71 : When run with the _stabilize_ command, metche turns a "testing
72 state" into a "stable state". By default, it will use the last
73 "testing state", but this can be overriden by giving a specific
74 state as argument.
75
76 cron
77 : This command should not be called manually, but used from a
78 cronjob. When called, it can perform various operations like:
79 saving "unstable", "testing" or "stable" states as needed and
80 sending reports and notification if configured to do so. This
81 command does not support the `-h` option.
82
83 FILES
84 =====
85
86 `/etc/metche.conf` contains metche configuration.
87
88 When configured to monitor one changelog, `CHANGELOG_FILE` (default:
89 `/root/Changelog`).
90
91 When configured to monitor multiple changelogs,
92 `CHANGELOG_DIR/*/Changelog` (default: `/root/changelogs`).
93
94 System states are saved in `BACKUP_DIR` (default: `/var/lib/metche`).
95
96 SECURITY
97 ========
98
99 metche is able to use GnuPG to encrypt the email it sends, but does
100 not by default; just enable the `ENCRYPT_EMAIL` configuration option,
101 and make sure `EMAIL_ADDRESS`' public key is in root's keyring,
102 trusted enough to be used blindly by metche. If `EMAIL_ADDRESS` is an
103 email alias or mailing-list's address, you probably want to use the
104 `group` option in `/root/.gnupg/gpg.conf` so that metche reports are
105 encrypted for every person subscribed to this alias or mailing-list;
106 for more information, see `gpg(1)`.
107
108 When `DO_DETAILS` is enabled and `ENCRYPT_EMAIL` is disabled, metche
109 sends in _clear text email_ the changes made to the watched
110 directory... either make sure that the `EXCLUDES` configuration
111 variable prevents it to send sensitive information, or triple check
112 that secure connections will be used end-to-end on the email path. If
113 unsure, set `EMAIL_ADDRESS` configuration variable to a local mailbox.
114 Please note that `EMAIL_ADDRESS` is not used for VServers: a
115 VServer's report messages are sent to its root email address.
116
117 metche stores, in `BACKUP_DIR` (default: `/var/lib/metche`), various
118 backups of `WATCHED_DIR`. Make sure that this backup place is at least
119 as secured as the source.
120
121 BUGS
122 ====
123
124 See [metche's ticket system] for known bugs, missing features, and the
125 development road-map.
126
127 [metche's ticket system]: https://labs.riseup.net/code/projects/metche/issues