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