Permalink
Browse files

add Pod documentation

  • Loading branch information...
1 parent ab7e924 commit a48e300027d906742fe4f6b59eeaafc22314b754 @jnorell jnorell committed Jan 7, 2014
Showing with 199 additions and 37 deletions.
  1. +199 −37 vzfirewall
View
@@ -1,10 +1,19 @@
#!/usr/bin/perl -w
+#
+# vzfirewall: A simple firewall for OpenVZ
+#
+# See 'vzfirewall -h' for documentaion.
+#
+# Check https://github.com/DmitryKoterov/vzfirewall
+# for latest version and development info.
+
use strict;
+use Pod::Usage;
use File::Basename;
use POSIX 'strftime';
use Getopt::Long 2.25 qw(:config posix_default no_ignore_case);
-my $VERSION = "1.08, 2014-01-07";
+my $VERSION = "1.09, 2014-01-07";
my ($DIR) = grep { -d $_ } ("/etc/sysconfig/vz-scripts", "/etc/vz/conf");
unless ($DIR && -d $DIR) {
@@ -20,10 +29,10 @@ my ($IPTABLES) = grep { -f $_ } ($RULES, "/etc/sysconfig/iptables", "/etc/iptabl
my %opt = ();
GetOptions(\%opt, 'help|h', 'version|V', 'apply|a', 'test|t',
- 'force|f', 'dir|d=s', 'conf|c=s','rules=s',
+ 'force|f', 'dir|d=s', 'conf|c=s', 'rules=s', 'verbose|v',
) or exit(1);
-if ($opt{help}) { usage(); }
+if ($opt{help}) { pod2usage( -verbose => $opt{verbose} ? 2 : 1 ); }
if ($opt{version}) { print "vzfirewall $VERSION\n"; exit(0) }
if ($opt{conf}) { $CONF = $opt{conf}; }
@@ -34,40 +43,7 @@ if ($opt{dir}) { $DIR = $opt{dir}; }
if ($opt{test}) { do_apply(1); }
elsif ($opt{apply}) { do_apply(0, defined $opt{force}); }
-else { usage(); }
-
-sub usage {
- die qq{vzfirewall $VERSION
-
-vzfirewall is a simple firewall for your openvz host
-which protects both the openvz host and containers.
-
-Homepage: http://en.dklab.ru/lib/dklab_vzfirewall
-Latest: https://github.com/DmitryKoterov/vzfirewall
-
-Usage:
-
- $0 (-h|-V|-a|-t) [option ...]
-
-Action:
-
- -h, --help Display this help and exit.
- -V, --version Output vzfirewall version and exit.
- -a, --apply Apply iptables rules in $DIR/*.conf (FIREWALL directives)
- -t, --test Preview iptables rules in $DIR/*.conf without activation.
-
-Options:
-
- -f, --force Force iptables rules rewrite even if rules are unchanged.
- -c, --conf=PATH Location of vzfirewall configuration file.
- (default: $CONF)
- -d, --dir=PATH Specify directory containing per-container .conf files.
- (default: $DIR)
- --rules=PATH Store iptables rules in this file
- (default: $IPTABLES)
-
-};
-}
+else { pod2usage( -verbose => 1 ); }
sub do_apply {
my ($test_mode, $force) = @_;
@@ -292,3 +268,189 @@ sub resolve {
}
return $resolved{$host} = \@ips;
}
+
+
+__END__
+
+=head1 NAME
+
+vzfirewall - A simple firewall for OpenVZ
+
+=head1 SYNOPSIS
+
+B<vzfirewall> (B<-h>|B<-V>|B<-a>|B<-t>) [B<option> ...]
+
+You B<must> specify an action with one of the following:
+
+=over 20
+
+=item B<-h>, B<--help>
+
+Display this help and exit.
+
+=item B<-V>, B<--version>
+
+Output vzfirewall version and exit.
+
+=item B<-a>, B<--apply>
+
+Apply iptables rules in $DIR/*.conf (FIREWALL directives).
+
+=item B<-t>, B<--test>
+
+Preview iptables rules in $DIR/*.conf without activation.
+
+=back
+
+You B<may> specify any of the options:
+
+=over 20
+
+=item B<-f>, B<--force>
+
+Force iptables rules rewrite even if rules are unchanged.
+
+=item B<-c>, B<--conf>=I<PATH>
+
+Location of vzfirewall configuration file.
+
+=item B<-d>, B<--dir>=I<PATH>
+
+Specify directory containing per-container .conf files.
+
+=item B<--rules>=I<PATH>
+
+Store iptables rules in this file.
+
+=item B<-v>, B<--verbose>
+
+Be more verbose.
+
+=back
+
+
+=head1 DESCRIPTION
+
+vzfirewall is a simple firewall for an openvz host
+which protects both the openvz host and its containers.
+
+vzfirewall uses openvz container .conf files for configuration,
+just add a C<FIREWALL> directive to specify the firewall rules.
+
+=head1 EXAMPLES
+
+=head2 Firewall the OpenVZ host
+
+A C<FIREWALL> directive in I<0.conf> specifies firewall rules
+for the openvz host. Add something like this to I</etc/vz/conf/0.conf>:
+
+ #FIREWALL="
+ # # allow all access from the administrator's workstation
+ # admin.domain.com
+ #
+ # # allow our OpenVZ Web Panel to talk to the owp hardware daemon
+ # [7767]
+ # owp.domain.com
+ #
+ # # we run an ntp server on the openvz host
+ # [udp:123]
+ # *
+ #"
+
+Run C<vzfirewall -t> to test the configuration.
+When it looks good, apply the new rules: C<vzfirewall -a>.
+
+Note the C<#> prefix character for the entire C<FIREWALL> directive
+is intentional, other OpenVZ utilities issue warnings if left out.
+
+
+=head2 Firewall a container
+
+Say you have a container with C<CTID> I<123> running a web server.
+(Use C<vzlist> to determine the container id.) Add the following to
+I</etc/vz/conf/123.conf>:
+
+ #FIREWALL="
+ # [80,443]
+ # *
+ #"
+
+Run C<vzfirewall -a> to apply the new rules.
+
+
+=head1 FILES
+
+=over
+
+=item C</etc/vz/vzfirewall.conf>, C</etc/sysconfig/vzfirewall.conf>
+
+Default vzfirewall configuration file locations.
+
+=item C</etc/vz/conf/*.conf>, C</etc/sysconfig/vz-scripts/*.conf>
+
+Default location of OpenVZ container .conf scripts.
+
+=item C</etc/vz/vzfirewall.rules>, C</etc/sysconfig/iptables>, C</etc/iptables/rules.v4>
+
+Default location of stored iptables rules file.
+
+=back
+
+=head1 SEE ALSO
+
+=over
+
+=item L<iptables(8)>
+
+administration tool for IPv4 packet filtering and NAT
+
+=item L<ctid.conf(5)>
+
+configuration file for an OpenVZ container
+
+=item L<http://en.dklab.ru/lib/dklab_vzfirewall>
+
+vzfirewall homepage
+
+=item L<https://github.com/DmitryKoterov/vzfirewall>
+
+Development and Latest Version
+
+=back
+
+=head1 LICENSE
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published
+by the Free Software Foundation; either version 2.1 of the License,
+or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program; if not, write to:
+
+=over 4
+
+ The Free Software Foundation, Inc.
+ 51 Franklin Street
+ Fifth Floor
+ Boston, MA 02110-1301 USA
+
+=back
+
+=head1 AUTHORS
+
+=over
+
+=item Dmitry Koterov <dmitry.koterov@gmail.com>
+
+=item Jesse Norell <jesse@kci.net>
+
+=back
+
+=cut
+

0 comments on commit a48e300

Please sign in to comment.