src/libcaptive/client/options.pod.pl.in

   1 #! /usr/bin/perl
   2 #
   3 # $Id$
   4 # perlpod(1) source for captive(7) options part of man page
   5 # Copyright (C) 2003 Jan Kratochvil <project-captive@jankratochvil.net>
   6 #
   7 # This program is free software; you can redistribute it and/or modify
   8 # it under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; exactly version 2 of June 1991 is required
  10 #
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program; if not, write to the Free Software
  18 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19
  20
  21 use vars qw($VERSION);
  22 $VERSION=do { my @r=(q$Revision$=~/\d+/g); sprintf "%d.".("%03d"x$#r),@r; };
  23 use strict;
  24 use warnings;
  25
  26
  27 my $vardir='@localstatedir@/lib/@PACKAGE@';
  28 $vardir=~s#\$\Q{prefix}\E#'@prefix@';#ge;
  29 $vardir="/var/lib/@PACKAGE@" if $vardir=~/^@/;
  30 my $sbindir='@sbindir@';
  31 $sbindir=~s#\$\Q{exec_prefix}\E#'@exec_prefix@';#ge;
  32 $sbindir=~s#\$\Q{prefix}\E#'@prefix@';#ge;
  33 $sbindir="/usr/sbin" if $sbindir=~/^@/;
  34
  35 print <<'POD_EOF';
  36 =head1 OPTIONS
  37
  38 All programs using B<@PACKAGE@>(7) library share the common set of configuration
  39 options:
  40
  41 =over
  42
  43 =item B<--filesystem>=B<pathname>
  44
  45 Pathname to B<.sys> or B<.so> filesystem module file. You will use exactly
  46 once this option. Possible choices are
  47 POD_EOF
  48 print "B<$vardir/ntfs.sys>\n";
  49 print <<'POD_EOF';
  50 etc.
  51
  52
  53 =item B<--load-module>=B<pathname>
  54
  55 Pathname to any W32 module to load w/o initialization. Multiple modules can be
  56 loaded although in common case you will use just
  57 POD_EOF
  58 print "B<$vardir/ntoskrnl.exe>\n";
  59 print <<'POD_EOF';
  60 here.
  61
  62
  63 =item B<--ro>
  64
  65 Read/write mode: Any write access will be forbidden. You should set this mode
  66 for B<cdfs.sys> (I<CD-ROM> filesystem). This option is mutually exclusive with
  67 B<--blind> and B<--rw>.
  68
  69
  70 =item B<--blind>
  71
  72 Read/write mode: All writes are just simulated in memory (default). Microsoft
  73 Windows filesystem driver will see no difference between B<--blind> and B<--rw>
  74 although the UNIX image file/device will be open read/only as for B<--ro>.
  75 All the changes get 'written' as long as B<captive>(7) program runs - all the
  76 changes will be lost afterwards. This mode is the most suitable for debugging.
  77 This option is mutually exclusive with B<--ro> and B<--rw>.
  78
  79
  80 =item B<--rw>
  81
  82 Read/write mode: Write directly to the image file/device. Standard read/write
  83 disk mode. You should use B<--sandbox-server> option in this case to have the
  84 disk protected against Microsoft Windows filesystem driver crashes. Modified
  85 disk image blocks are in B<--sandbox-server> B<--rw> mode buffered in the
  86 memory and they get reflected to the disk only after successful completion
  87 of all filesystem operations including filesystem unmount.
  88 This option is mutually exclusive with B<--ro> and B<--blind>.
  89
  90
  91 =item B<--cdrom>
  92
  93 Media type: CD-ROM. You must set this media type for B<cdfs.sys>.
  94 Virtual Microsoft Windows block device driver used by Captive maps to
  95 B<\Device\CdRom0>. This option is mutually exclusive with B<--disk>.
  96
  97
  98 =item B<--disk>
  99
 100 Media type: Disk (default). You must set this media type for all the Microsoft
 101 Windows filesystem drivers except B<cdfs.sys>. Virtual Microsoft Windows block
 102 device driver used by Captive maps to B<\Device\CaptiveHarddisk0>.
 103 This option is mutually exclusive with B<--cdrom>.
 104
 105
 106 =item B<--debug-messages>
 107
 108 Turn on debugging messages. Be prepared for substation debug output.
 109 Use of B<--syslog> feature is not recommended in this case.
 110
 111
 112 =item B<--sandbox-server>=B<pathname>
 113
 114 Pathname to
 115 POD_EOF
 116 print "B<$sbindir/captive-sandbox-server>\n";
 117 print <<'POD_EOF';
 118 program, turns on sandboxing.
 119 You should always use this option in conjunction with B<--rw>, see it for
 120 details. Although this program is I<setuid root> and it drops it privileges
 121 to B<@CAPTIVE_SANDBOX_SETUID@> user. Your system gets protected by
 122 B<chroot>(2), B<setuid>(2), B<setgid>(2) and B<setrlimit>(2) UNIX security
 123 features against malicious Microsoft Windows drivers. You should never use this
 124 option during debugging.
 125
 126 This option is turned on automatically during the mount operation by
 127 B<mount.@PACKAGE@-ntfs>(8).
 128 Option needs to be used by hand for the B<captive-cmdline>(2) client.
 129
 130
 131 =item B<--sandbox-server-ior>=B<IOR>
 132
 133 Specify I<CORBA IOR> of
 134 POD_EOF
 135 print "B<$sbindir/captive-sandbox-server>\n";
 136 print <<'POD_EOF';
 137 program, turns on
 138 sandboxing. Specified I<CORBA IOR> should be the string starting by "B<IOR:>"
 139 text. This option is useful only for debugging. No sandbox restarting is
 140 possible in this case.
 141
 142
 143 =item B<--no-sandbox>
 144
 145 Turn off sandboxing feature (default). No
 146 POD_EOF
 147 print "B<$sbindir/captive-sandbox-server>\n";
 148 print <<'POD_EOF';
 149 is run. Microsoft Windows filesystem driver is run in native UNIX environment
 150 without any I<CORBA> separation. This option is recommended only for debugging.
 151 It is dangerous to use B<--rw> together, see its description for the details.
 152
 153
 154 =item B<--bug-pathname>=B<pathname>
 155
 156 Pathname to B<strftime>(3) for B<.captivebug.xml.gz> bugreports. Every crash of
 157 sandbox child gets bugreported to the specified file. You should attempt to
 158 minimize the number of operations from the mount operation till the expected
 159 crash to minimize the snapshot file size. B<--sandbox-server> option is
 160 required for B<--bug-pathname>.
 161
 162 B<!!! Be aware '.captivebug.xml.gz' will contain data from your disk drive !!!>
 163
 164
 165 =item B<--syslog>
 166
 167 Messages sent to B<syslog>(3) instead of I<stderr>. This option gets handy
 168 for B<mount>(8) operation as the messages would be lost otherway.
 169 Watch our for possible "B<Filesystem crash broke dirty object>" messages where
 170 some written filesystem data got lost in the case of Microsoft Windows
 171 filesystem driver crash.
 172
 173
 174 =item B<--syslog-facility>=B<facility>
 175
 176 B<openlog>(3) facility for B<--syslog>. See B<facility> section of
 177 B<openlog>(3) man page for details. Lowercased values such as B<daemon> or
 178 B<user> are supported.
 179
 180
 181 =back
 182
 183
 184 POD_EOF
 185 1;