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 $sysconfdir='@sysconfdir@';
  31 $sysconfdir=~s#\$\Q{prefix}\E#'@prefix@';#ge;
  32 $sysconfdir="/etc" if $sysconfdir=~/^@/;
  33 my $sbindir='@sbindir@';
  34 $sbindir=~s#\$\Q{exec_prefix}\E#'@exec_prefix@';#ge;
  35 $sbindir=~s#\$\Q{prefix}\E#'@prefix@';#ge;
  36 $sbindir="/usr/sbin" if $sbindir=~/^@/;
  37
  38 our $no_libcaptive_options_heading;
  39 print <<'POD_EOF' if !$no_libcaptive_options_heading;
  40 =head1 OPTIONS
  41
  42 All programs using B<@PACKAGE@>(7) library share the common set of configuration
  43 options:
  44 POD_EOF
  45
  46 print <<'POD_EOF';
  47
  48 =over
  49
  50 =item B<--filesystem>=B<pathname>
  51
  52 Pathname to B<.sys> or B<.so> filesystem module file. You will use exactly
  53 once this option. Possible choices are
  54 POD_EOF
  55 print "B<$vardir/ntfs.sys>\n";
  56 print <<'POD_EOF';
  57 etc.
  58
  59
  60 =item B<--load-module>=B<pathname>
  61
  62 Pathname to any W32 module to load w/o initialization. Multiple modules can be
  63 loaded although in common case you will use just
  64 POD_EOF
  65 print "B<$vardir/ntoskrnl.exe>\n";
  66 print <<'POD_EOF';
  67 here.
  68
  69
  70 =item B<--modid-path>=B<pathname>
  71
  72 Pathname to the B<.captivemodid.xml> database of existing W32 module
  73 identifications. The default used one is:
  74 POD_EOF
  75 print "B<$sysconfdir/w32-mod-id.captivemodid.xml>\n";
  76 print <<'POD_EOF';
  77 You must have this database update for any W32 binary module you are using.
  78 If you miss such database you may also try to use B<--load-untested> below.
  79
  80
  81 =item B<--load-untested>
  82
  83 Load tthe W32 modules despite they may not match the current B<--modid-path>
  84 identifications database. If you use this option Captive may fail very easily
  85 as such module was never tested before the release and may need some
  86 compatibility updates. Still no data should be corrupted even if using this
  87 B<--load-untested> option.
  88
  89
  90 =item B<--ro>
  91
  92 Read/write mode: Any write access will be forbidden. You should set this mode
  93 for B<cdfs.sys> (I<CD-ROM> filesystem). This option is mutually exclusive with
  94 B<--blind> and B<--rw>.
  95
  96
  97 =item B<--blind>
  98
  99 Read/write mode: All writes are just simulated in memory (default). Microsoft
 100 Windows filesystem driver will see no difference between B<--blind> and B<--rw>
 101 although the UNIX image file/device will be open read/only as for B<--ro>.
 102 All the changes get 'written' as long as B<captive>(7) program runs - all the
 103 changes will be lost afterwards. This mode is the most suitable for debugging.
 104 This option is mutually exclusive with B<--ro> and B<--rw>.
 105
 106
 107 =item B<--rw>
 108
 109 Read/write mode: Write directly to the image file/device. Standard read/write
 110 disk mode. You should use B<--sandbox-server> option in this case to have the
 111 disk protected against Microsoft Windows filesystem driver crashes. Modified
 112 disk image blocks are in B<--sandbox-server> B<--rw> mode buffered in the
 113 memory and they get reflected to the disk only after successful completion
 114 of all filesystem operations including filesystem unmount.
 115 This option is mutually exclusive with B<--ro> and B<--blind>.
 116
 117
 118 =item B<--cdrom>
 119
 120 Media type: CD-ROM. You must set this media type for B<cdfs.sys>.
 121 Virtual Microsoft Windows block device driver used by Captive maps to
 122 B<\Device\CdRom0>. This option is mutually exclusive with B<--disk>.
 123
 124
 125 =item B<--disk>
 126
 127 Media type: Disk (default). You must set this media type for all the Microsoft
 128 Windows filesystem drivers except B<cdfs.sys>. Virtual Microsoft Windows block
 129 device driver used by Captive maps to B<\Device\CaptiveHarddisk0>.
 130 This option is mutually exclusive with B<--cdrom>.
 131
 132
 133 =item B<--debug-messages>
 134
 135 Turn on debugging messages. Be prepared for substation debug output.
 136 Use of B<--syslog> feature is not recommended in this case.
 137
 138
 139 =item B<--sandbox-server>=B<pathname>
 140
 141 Pathname to
 142 POD_EOF
 143 print "B<$sbindir/captive-sandbox-server>\n";
 144 print <<'POD_EOF';
 145 program, turns on sandboxing.
 146 You should always use this option in conjunction with B<--rw>, see it for
 147 details. Although this program is I<setuid root> and it drops it privileges
 148 to B<@CAPTIVE_SANDBOX_SETUID@> user. Your system gets protected by
 149 B<chroot>(2), B<setuid>(2), B<setgid>(2) and B<setrlimit>(2) UNIX security
 150 features against malicious Microsoft Windows drivers. You should never use this
 151 option during debugging.
 152
 153 This option is turned on automatically during the mount operation by
 154 B<mount.@PACKAGE@-ntfs>(8).
 155 Option needs to be used by hand for the B<captive-cmdline>(2) client.
 156
 157
 158 =item B<--sandbox-server-ior>=B<IOR>
 159
 160 Specify I<CORBA IOR> of
 161 POD_EOF
 162 print "B<$sbindir/captive-sandbox-server>\n";
 163 print <<'POD_EOF';
 164 program, turns on
 165 sandboxing. Specified I<CORBA IOR> should be the string starting by "B<IOR:>"
 166 text. This option is useful only for debugging. No sandbox restarting is
 167 possible in this case.
 168
 169
 170 =item B<--no-sandbox>
 171
 172 Turn off sandboxing feature (default). No
 173 POD_EOF
 174 print "B<$sbindir/captive-sandbox-server>\n";
 175 print <<'POD_EOF';
 176 is run. Microsoft Windows filesystem driver is run in native UNIX environment
 177 without any I<CORBA> separation. This option is recommended only for debugging.
 178 It is dangerous to use B<--rw> together, see its description for the details.
 179
 180
 181 =item B<--bug-pathname>=B<pathname>
 182
 183 Pathname to B<strftime>(3) for B<.captivebug.xml.gz> bugreports. Every crash of
 184 sandbox child gets bugreported to the specified file. You should attempt to
 185 minimize the number of operations from the mount operation till the expected
 186 crash to minimize the snapshot file size. B<--sandbox-server> option is
 187 required for B<--bug-pathname>.
 188
 189 B<!!! Be aware '.captivebug.xml.gz' will contain data from your disk drive !!!>
 190
 191
 192 =item B<--syslog>
 193
 194 Messages sent to B<syslog>(3) instead of I<stderr>. This option gets handy
 195 for B<mount>(8) operation as the messages would be lost otherway.
 196 Watch our for possible "B<Filesystem crash broke dirty object>" messages where
 197 some written filesystem data got lost in the case of Microsoft Windows
 198 filesystem driver crash.
 199
 200
 201 =item B<--syslog-facility>=B<facility>
 202
 203 B<openlog>(3) facility for B<--syslog>. See B<facility> section of
 204 B<openlog>(3) man page for details. Lowercased values such as B<daemon> or
 205 B<user> are supported.
 206
 207
 208 =back
 209
 210
 211 POD_EOF
 212 1;