madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

fix argument parsing
[code/molly-guard.git] / molly-guard.xml
1 <?xml version='1.0' encoding='ISO-8859-1'?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4
5 <!--
6
7 Process this file with an XSLT processor: `xsltproc \
8 -''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
9 manpages/docbook.xsl manpage.dbk'.  A manual page
10 <package>.<section> will be generated.  You may view the
11 manual page with: nroff -man <package>.<section> | less'.  A
12 typical entry in a Makefile or Makefile.am is:
13
14 DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
15 manpages/docbook.xsl
16 XP=xsltproc -''-nonet
17
18 manpage.1: manpage.dbk
19         $(XP) $(DB2MAN) $<
20     
21 The xsltproc binary is found in the xsltproc package.  The
22 XSL files are in docbook-xsl.  Please remember that if you
23 create the nroff version in one of the debian/rules file
24 targets (such as build), you will need to include xsltproc
25 and docbook-xsl in your Build-Depends control field.
26
27 -->
28
29   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
30   <!ENTITY dhfirstname "<firstname>martin f.</firstname>">
31   <!ENTITY dhsurname   "<surname>krafft</surname>">
32   <!-- Please adjust the date whenever revising the manpage. -->
33   <!ENTITY dhdate      "<date>Apr 19, 2008</date>">
34   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
35        allowed: see man(7), man(1). -->
36   <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
37   <!ENTITY dhemail     "<email>madduck@madduck.net</email>">
38   <!ENTITY dhusername  "martin f. krafft">
39   <!ENTITY dhucpackage "<refentrytitle>molly-guard</refentrytitle>">
40   <!ENTITY dhpackage   "molly-guard">
41   <!ENTITY dhcommand   "<command>molly-guard</command>">
42
43   <!ENTITY debian      "<productname>Debian</productname>">
44   <!ENTITY gnu         "<acronym>GNU</acronym>">
45   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
46 ]>
47
48 <refentry>
49   <refentryinfo>
50     <address>
51       &dhemail;
52     </address>
53     <copyright>
54       <year>2008</year>
55       <holder>&dhusername;</holder>
56     </copyright>
57     &dhdate;
58   </refentryinfo>
59   <refmeta>
60     &dhucpackage;
61
62     &dhsection;
63   </refmeta>
64   <refnamediv>
65     <refname>&dhcommand;</refname>
66
67     <refpurpose>guard against accidental shutdowns/reboots</refpurpose>
68   </refnamediv>
69
70   <refsynopsisdiv>
71     <cmdsynopsis>
72       <command>shutdown</command>
73       <arg choice="opt">
74         -<option>hV</option>
75       </arg>
76       <arg choice="opt">
77         <option>--molly-guard-do-nothing</option>
78       </arg>
79       <arg choice="opt">
80         -- <replaceable>script_options</replaceable>
81       </arg>
82     </cmdsynopsis>
83     <cmdsynopsis>
84       <command>halt</command>
85       <arg choice="opt">
86         -<option>hV</option>
87       </arg>
88       <arg choice="opt">
89         <option>--molly-guard-do-nothing</option>
90       </arg>
91       <arg choice="opt">
92         -- <replaceable>script_options</replaceable>
93       </arg>
94     </cmdsynopsis>
95     <cmdsynopsis>
96       <command>reboot</command>
97       <arg choice="opt">
98         -<option>hV</option>
99       </arg>
100       <arg choice="opt">
101         <option>--molly-guard-do-nothing</option>
102       </arg>
103       <arg choice="opt">
104         -- <replaceable>script_options</replaceable>
105       </arg>
106     </cmdsynopsis>
107     <cmdsynopsis>
108       <command>poweroff</command>
109       <arg choice="opt">
110         -<option>hV</option>
111       </arg>
112       <arg choice="opt">
113         <option>--molly-guard-do-nothing</option>
114       </arg>
115       <arg choice="opt">
116         -- <replaceable>script_options</replaceable>
117       </arg>
118     </cmdsynopsis>
119   </refsynopsisdiv>
120
121   <refsect1>
122     <title>DESCRIPTION</title>
123
124     <para> &dhcommand; attempts to prevent you from accidentally shutting down
125       or rebooting machines. It does this by injecting a couple of checks
126       before the existing commands: <command>halt</command>,
127       <command>reboot</command>, <command>shutdown</command>, and
128       <command>poweroff</command>. This happens via scripts with the same
129       names in <filename>/usr/sbin</filename>, so it only works if you have
130       <filename>/usr/sbin</filename> before <filename>/sbin</filename> in your
131       <envar>PATH</envar>!</para>
132
133     <para> Before &dhcommand; invokes the real command, all scripts in
134       <filename>/etc/molly-guard/run.d/</filename> have to run and exit
135       successfully; else, it aborts the command.
136       <command>run-parts(1)</command> is used to process the directory.</para>
137
138     <para> &dhcommand; passes any <replaceable>script_options</replaceable> to the
139       scripts, and also populates the environment with the following
140       variables:</para>
141
142     <itemizedlist>
143       <listitem><para><envar>MOLLYGUARD_CMD</envar> - the actual command
144           invoked by the user.</para></listitem>
145
146       <listitem><para><envar>MOLLYGUARD_DO_NOTHING</envar> - set to
147           <option>1</option> if this is a demo-run.</para></listitem>
148
149       <listitem><para><envar>MOLLYGUARD_SETTINGS</envar> - the path to
150           a shell script snippet which scripts can source to obtain
151           settings.</para></listitem>
152     </itemizedlist>
153
154     <para> &dhcommand; prints the contents of
155       <filename>/etc/molly-guard/messages.d/COMMAND</filename> or
156       <filename>/etc/molly-guard/messages.d/default</filename> to the console,
157       if either exists. This is due to
158       <filename>/etc/molly-guard/run.d/10-print-message</filename>.</para>
159
160   </refsect1>
161   <refsect1>
162     <title>GUARDING SSH SESSIONS</title>
163
164     <para> &dhcommand; was primarily designed to shield SSH connections. This
165       functionality (which should arguably be provided by the
166       <package>openssh-server</package> package) is implemented in
167       <filename>/etc/molly-guard/run.d/30-query-hostname</filename>.</para>
168
169     <para> This script first tests whether the command is being executed from
170       a <filename>tty</filename> which has been created by
171       <command>sshd</command>. It also checks whether the variable
172       <envar>SSH_CONNECTION</envar> is defined. If any of these tests are
173       successful, test script queries the user for the machine's hostname,
174       which should be sufficient to prevent the user from doing something by
175       accident.</para>
176
177     <para> You can pass the <option>--pretend-ssh</option> script option to
178       &dhcommand; to pretend that those tests succeeds. Alternatively, setting
179       <envar>ALWAYS_QUERY_HOSTNAME</envar> in
180       <filename>/etc/molly-guard/rc</filename> causes the script to
181       always query.</para>
182
183     <para> The following situations are still UNGUARDED. If you can think of
184       ways to protect against those, please let me know!</para>
185
186     <itemizedlist>
187       <listitem><para>running <application>sudo</application> within
188           <application>screen</application> or <application>screen</application> within
189           <application>sudo</application>; <application>sudo</application> eats the
190           <envar>SSH_CONNECTION</envar> variable, and
191           <application>screen</application> creates a new
192           <filename>pty</filename>.</para></listitem>
193       <listitem><para>executing those command in a remote terminal window,
194           that is a <application>XTerm</application> started on a remote
195           machine but displaying on the local <application>X</application>
196           server.</para></listitem>
197     </itemizedlist>
198
199     <para> You have been warned. You can use the
200       <option>--molly-guard-do-nothing</option> switch to prevent anything
201       from happening, e.g. <userinput>halt
202         --molly-guard-do-nothing</userinput>. </para>
203   </refsect1>
204
205   <refsect1>
206     <title>OPTIONS</title>
207     <variablelist>
208       <varlistentry>
209         <term>--molly-guard-do-nothing</term>
210         <listitem>
211           <para>
212             Cause &dhcommand; to print the command which would be executed,
213             after processing all scripts, instead of executing it.
214           </para>
215         </listitem>
216       </varlistentry>
217
218       <varlistentry>
219         <term>-h</term>
220         <term>--help</term>
221         <listitem>
222           <para>
223             Display usage information.
224           </para>
225         </listitem>
226       </varlistentry>
227
228       <varlistentry>
229         <term>-V</term>
230         <term>--version</term>
231         <listitem>
232           <para>
233             Display version information.
234           </para>
235         </listitem>
236       </varlistentry>
237     </variablelist>
238   </refsect1>
239
240   <refsect1>
241     <title>SEE ALSO</title>
242     <para>
243       <citerefentry>
244         <refentrytitle>shutdown</refentrytitle>
245         <manvolnum>8</manvolnum>
246       </citerefentry>,
247       <citerefentry>
248         <refentrytitle>halt</refentrytitle>
249         <manvolnum>1</manvolnum>
250       </citerefentry>,
251       <citerefentry>
252         <refentrytitle>reboot</refentrytitle>
253         <manvolnum>8</manvolnum>
254       </citerefentry>,
255       <citerefentry>
256         <refentrytitle>poweroff</refentrytitle>
257         <manvolnum>8</manvolnum>
258       </citerefentry>.
259     </para>
260   </refsect1>
261
262   <refsect1>
263     <title>LEGALESE</title>
264
265     <para>
266       &dhpackage; is copyright by &dhusername;. Andrew Ruthven came up with
267       the idea of using the scripts directory and submitted a patch, which
268       I modified a bit.
269     </para>
270
271     <para>
272       This manual page was written by &dhusername; &dhemail;.
273     </para>
274
275     <para>
276       Permission is granted to copy, distribute and/or modify this document
277       under the terms of the Artistic License 2.0
278     </para>
279
280   </refsect1>
281 </refentry>