/ 
Config-Hosts-0.03
River stage zero No dependents
/ Config::Hosts

NAME

Config::Hosts - Interface to /etc/hosts file

VERSION

Version 0.01

SYNOPSIS

Config::Hosts - Interface to /etc/hosts file. A tool that manages the hosts list on a machine, is able to query/insert/delete/update the entries by IP or by a hostname, and also maintains the original comments and some sanity checks on IP and hostname values.

    use Config::Hosts;

    my $hosts = Config::Hosts->new();
	$hosts->read_hosts(); # reads default /etc/hosts
	$hosts->query_host($host_or_ip);
	$hosts->insert_host(ip => $ip, hosts => [qw(host1 host2)]);
	$hosts->update_host($ip, hosts=> [qw(host1 host3)]);
	$hosts->delete_host('host3');
	$hosts->write_hosts("/tmp/hosts");

EXPORT

The interface is entirely object-oriented. The following methods have been defined:

SUBROUTINES/METHODS

new ($;%)

The constructor. Accepts optional hash with one key only: file - the name of the file as alternative to default /etc/hosts.

Returns the newly blessed object.

is_valid_ip ($)

internal utility function to check whether the IP given is a valid IPv4 or IPv6 address. Returns 1 or 0, naturally.

is_valid_host($)

Internal utility to determine whether the host name is a valid hostname as required by /etc/hosts manual.

read_hosts($;$)

Read the host file into a data structure to later be used by the other methods. Optional argument may be the file to read hosts table from.

determine_ip_or_host ($$)

Check whether the given argument is an IP, a HOST or neither. Returns 1, -1 or 0 correspondingly.

query_host ($$)

Queries the read hosts table to find specified argument that may be IP address or host name.

Returns hash containing the relevant entry if found or undef if not.

insert_host ($%)

Inserts a host. Both IP and hostnames must be specified as a hash. Hostname may be a single scalar or arrayref of hostnames.

delete_host ($$)

Deletes an entry in hosts table. The entry is determined either by IP or by hostname, all entries related to this host or IP are wiped out.

update_host ($$)

Updates an entry in hosts table. Arguments should be of the following format: $self->update_host($ip_or_host, ip => $new_ip, hosts => [ @new_hosts ]);

New hosts' argument may be a single scalar instead of arrayref.

write_hosts($;$)

Writes the hosts table either to the default or to a specified (via parameter) file.

AUTHOR

Roman M. Parparov, <roman at parparov.com>

BUGS

Please report any bugs or feature requests to bug-config-hosts at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-Hosts. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

CAVEAT: the changes in host table are not committed unless you explicitly write_hosts() them.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Config::Hosts

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to Vicente Gavara <vicente.gavara at tcomm.es> for providing a fix for editing/deleting routines.

LICENSE AND COPYRIGHT

Copyright 2011 Roman M. Parparov.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.