/ 
Net-OpenVPN-Manage-0.01
River stage zero No dependents
/ Net::OpenVPN::Manage

NAME

Net::OpenVPN::Manage - Manage an OpenVPN process via it's management port

SYNOPSIS

use Net::OpenVPN::Manage;

my $vpn = Net::OpenVPN::Manage->new({ 
		host=>'127.0.0.1', 
		port=>'6000', 
		password=>'password',
		timeout=>10
});

# Error if unable to connect.
unless($vpn->connect()){
  print $vpn->{error_msg}."\n";
  exit 0;
}

# Get the current status table in version 2 format from the process.
my $status = $vpn->status(2);

# If method returned false, print error message.
# Otherwise print table to STDOUT.
if ( ! $status ) {
  print $vpn->{error_msg};
  exit 0;
} else {
  print $status."\n";
}

DESCRIPTION

This module connects to the OpenVPN management interface, executes commands on the interface and returns the results or errors that result.

USING THE MODULE

All the methods in this module will return 0, or boolean false if there is any error. In most cases an error message detailing the problem will be returned in $obj->{error_msg}.

METHODS

$vpn = Net::OpenVPN::Manage->new({ host=>'', port=>'', password=>'', timeout=>20 });

Constructs a new Net::OpenVPN::Manage object to connect to the specified process's management interface. The anonymous hash that is passed specifies the target hostname or IP address, TCP port, and an optional password. If no password is configured for your OpenVPN process, just omit the password reference. Optionally, you can change the network timeout value as well.

$vpn->connect();

The connect method has no arguments passed to it. This method connects to the remote host at the port specified, in the event that the host or port provided to the object are incorrect; or if there is already another network session to this port (OpenVPN only supports a single management session at a time) this command will timeout.

For more extensive information on the use of the OpenVPN management commands referenced by these methods, see the OpenVPN documentation (http://www.openvpn.net) or at least the management help screen (print $vpn->help();).

$vpn->auth_retry( $arg );

Changes the Auth failure retry mode. Arguments are: none, interact, or nointeract.

$vpn->auth_retry('none'); # Sets auth-retry mode to 'none'

$vpn->echo( $arg );

Returns messages from the echo buffer or changes echo state. Arguments are: on, off, all, or a integer designating number of lines to be returned. The on and off arguments are really of no use here since it changes the state of the realtime management console echo messages and our session only connected for a brief time.

$vpn->echo('all'); # Returns entire echo buffer

$vpn->help();

Returns the help screen for the management command usage.

print $vpn->help(); # Prints the help screen to STDOUT

$vpn->hold( $arg );

If called without an argument it returns the current hold state; if called with an argument of: on, off, or release it changes the current hold state.

$vpn->hold('release'); # Releases the hold state on the OpenVPN process.

$vpn->kill( $arg );

Kills the VPN connection referenced. The argument may be either the common name of the connection or the real client IP:Port address.

$vpn->kill('jsmith'); # kills the connection with the common name of 'jsmith'

$vpn->kill('63.73.83.93:17023'); # kills the connection where the client is connecting from: '63.73.83.93:17023'

$vpn->log( $arg );

Returns messages from the log buffer or changes realtime log state. Arguments are: on, off, all, or an integer designating number of lines to be returned. The on and off arguments are really of no use here since it changes the state of the realtime management console log messages and our session only connected for a brief time.

print $vpn->log('all'); # prints the entire log buffer.

$vpn->mute( $arg );

If no argument is given it will show the log mute level for recurring log messages; if called with an argument it will change the log mute level to the value given.

$vpn->mute( 10 ); # Sets the log mute level to 10.

$vpn->net();

This method has not been implemented. Only applicable on the Windows platform.

$vpn->password();

This method has not been implemented. Only of use when the management session is continuous - ours is not.

$vpn->signal( $arg );

Sends a signal to the OpenVPN daemon process. Arugments are: SIGHUP, SIGTERM, SIGUSR1, or SIGUSR2. If the daemon is running under a non root or Administrator|System account it will not be able to restart itself after a reset since it won't have the priveledges required to reopen the network interfaces. See the OpenVPN HOWTO and the OpenVPN Management Interface documentation.

$vpn->signal('SIGHUP'); # Sends SIGHUP signal to the process.

$vpn->status( $arg );

Returns the active connection status information where the optional argument (either 1 or 2 at this time) specifies the output format version.

print $vpn->status(2); # Print the connection status page using the version 2 format.

$vpn->test();

This method is not implemented. No real need to test management console.

$vpn->username();

This method has not been implemented. Only of use when the management session is continuous - ours is not.

$vpn->verb( $arg );

If called without an argument it returns the log verbosity level; if called with an argument (any valid log level) it changes the verbosity setting to the given value.

$vpn->verb('1'); # Change verbosity level to 1.

$vpn->version();

Returns a string showing the processes version information as well as the management interface's version.

print $vpn->version(); # Prints the version information to STDOUT.

VERSION

0.01

AUTHOR

Copyright (c) 2006 Aaron Meyer / MeyerTech.net

This module is free software; you can redistribute it or modify it under the same terms as Perl itself.