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/10-print-message</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/default/molly-guard</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>