NAME

Unix::Conf::Bind8::Conf::Options - Class for representing Bind8 options directive

SYNOPSIS

    use Unix::Conf;
    my ($conf, $options, $ret);
    $conf = Unix::Conf::Bind8->new_conf (
        FILE        => '/etc/named.conf',
        SECURE_OPEN => 1,
    ) or $conf->die ("couldn't open `named.conf'");

    #
    # Get an Options object
    #

    # get an options object if one is defined
    $options = $conf->get_options ()
        or $options->die ("couldn't get options");
    
    # or create a new one
    $options = $conf->new_options (
        DIRECTORY  => 'db',
        VERSION    => '8.2.3-P5',
    ) or $options->die ("couldn't create options");

     
    #
    # Operations that can be performed on an Options object
    # Since the number of operations are too many, only a
    # hint is given here. Consult the METHODS section, for
    # a comprehnsive list.
    #

    my $acl = $conf->new_acl (
        NAME     => 'query-acl',
           ELEMENTS => [ qw (10.0.0.1 10.0.0.2 10.0.0.3) ],
    );
    $acl->die ("couldn't create `query-acl'") unless ($acl);

    $ret = $options->allow_query ($acl) 
        or $ret->die ("couldn't set allow-query");

    # OR

    $ret = $options->allow_query (qw (10.0.0.1 10.0.0.2 10.0.0.3))
        or $ret->die ("couldn't set allow-query");

    # Delete the option.
    $options->delete_allow_query ();
        

METHODS

new ()

 Arguments
 OPTION-NAME   => value,      # the value type is dependant on the option
 WHERE  => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG   => Unix::Conf::Bind8::Conf::Directive subclass object
                        # WARG is to be provided only in case WHERE eq 'BEFORE 
                        # or WHERE eq 'AFTER'
 PARENT => reference,   # to the Conf object datastructure.

Class Constructor. Create a new Unix::Conf::Bind8::Conf::Options object and return it if successful, or an Err object otherwise. Do not use this constructor directly. Use the Unix::Conf::Bind8::Conf::new_options () method instead.

version ()

directory ()

named_xfer ()

dump_file ()

memstatistics_file ()

pid_file ()

statistics_file ()

 Arguments
 'string',      # optional

Object method. Get/Set attributes from the invoking object. If called with a string argument, the method tries to set the corresponding attribute and returns true on success, an Err object otherwise. Returns value of the corresponding attribute if defined, an Err object otherwise.

auth_nxdomain ()

deallocate_on_exit ()

dialup ()

fake_iquery ()

fetch_glue ()

has_old_clients ()

host_statistics ()

multiple_cnames ()

notify ()

recursion ()

rcf2308_type1 ()

use_id_pool ()

treat_cr_as_space ()

also_notify ()

maintain_ixfr_base ()

 Arguments
 'string',     # 'yes'|'no'

Object method. Get/Set attributes from the invoking object. If called with a string argument, the method tries to set the corresponding attribute and returns true on success, an Err object otherwise. Returns value of the corresponding attribute if defined, an Err object otherwise.

forward ()

 Arguments
 'string',     # 'only'|'first'

Object method. Get/Set attributes from the invoking object. If called with a string argument, the method tries to set the corresponding attribute and returns true on success, an Err object otherwise. Returns value of the corresponding attribute if defined, an Err object otherwise.

allow_query ()

allow_transfer ()

allow_recursion ()

blackhole ()

 Arguments
 Acl object
 or
 LIST
 or 
 [ LIST ]

Object method. If argument(s) is/are passed, tries to set the elements of the appropriate attribute and returns true on success, an Err object otherwise. If no arguments are passed, tries to return the elements defined for that attribute as an anonymous array, if defined, an Err object otherwise.

add_to_allow_query ()

add_to_allow_transfer ()

add_to_allow_recursion ()

add_to_blackhole ()

delete_from_allow_query ()

delete_from_allow_transfer ()

delete_from_allow_recursion ()

delete_from_blackhole ()

 Arguments
 LIST
 or 
 [ LIST ]

Object method. Add to/delete from the elements defined for the appropriate attributes. Returns true on success, an Err object otherwise.

lame_ttl ()

max_transfer_time_in ()

max_ncache_ttl ()

min_roots ()

serial_queries ()

max_serial_queries ()

transfers_in ()

transfers_out ()

transfers_per_ns ()

max_ixfr_log_size ()

cleaning_interval ()

heartbeat_interval ()

interface_interval ()

statistics_interval ()

 Arguments
 number,       # Optional

Object method. Get/Set attributes from the invoking object. If called with a string argument, the method tries to set the corresponding attribute and returns true on success, an Err object otherwise. Returns value of the corresponding attribute if defined, an Err object otherwise.

NOTE: As 0 is also a valid argument, take care that the return value is not tested for truth or falsehood. Instead, test thus:

if (UNIVERSAL::isa ($ret, "Unix::Conf::Err"))

transfer_format ()

 Arguments
 'string',    # Optional. Allowed arguments are 'one-answer', 
              # 'many-answers'

Object method. Get/Set attributes from the invoking object. If called with a string argument, the method tries to set the corresponding attribute and returns true on success, an Err object otherwise. Returns value of the corresponding attribute if defined, an Err object otherwise.

transfer_source ()

 Arguments
 'string',   # Optional. The argument must be an IP Address in the
             # dotted quad notation

Object method. Get/Set attributes from the invoking object. If called with a string argument, the method tries to set the corresponding attribute and returns true on success, an Err object otherwise. Returns value of the corresponding attribute if defined, an Err object otherwise.

coresize ()

datasize ()

files ()

stacksize ()

 Arguments
 'string'|number,   # Optional. The argument must be a size spec. Refer to
                    # the Bind8 manual for a definition of size_spec.

Object method. Get/Set attributes from the invoking object. If called with a string argument, the method tries to set the corresponding attribute and returns true on success, an Err object otherwise. Returns value of the corresponding attribute if defined, an Err object otherwise.

NOTE: As 0 is also a valid argument, take care that the return value is not tested for truth or falsehood. Instead, test thus:

if (UNIVERSAL::isa ($ret, "Unix::Conf::Err"))

delete_version ()

delete_directory ()

delete_named_xfer ()

delete_dump_file ()

delete_memstatistics_file ()

delete_pid_file ()

delete_statistics_file ()

delete_auth_nxdomain ()

delete_deallocate_on_exit ()

delete_dialup ()

delete_fake_iquery ()

delete_fetch_glue ()

delete_has_old_clients ()

delete_host_statistics ()

delete_multiple_cnames ()

delete_notify ()

delete_recursion ()

delete_rfc2308_type1 ()

delete_use_id_pool ()

delete_treat_cr_as_space ()

delete_also_notify ()

delete_forward ()

delete_allow_query ()

delete_allow_recursion ()

delete_allow_transfer ()

delete_blackhole ()

delete_lame_ttl ()

delete_max_transfer_time_in ()

delete_max_ncache_ttl ()

delete_min_roots ()

delete_serial_queries ()

delete_max_serial_queries ()

delete_transfer_format ()

delete_transfers_in ()

delete_transfers_out ()

delete_transfers_per_ns ()

delete_transfer_source ()

delete_maintain_ixfr_base ()

delete_max_ixfr_log_size ()

delete_coresize ()

delete_datasize ()

delete_files ()

delete_stacksize ()

delete_cleaning_interval ()

delete_heartbeat_interval ()

delete_interface_interval ()

delete_statistics_interval ()

delete_topology ()

delete_forwarders ()

delete_query_source ()

Object method. Deletes the corresponding directive if defined and returns true, or an Err object otherwise.

delete_option ()

 Arguments
 'string',              # 'OPTION-NAME'

Object method. Deletes the corresponding directive if defined and returns true, or an Err object otherwise.

query_source ()

 Arguments
 PORT           => port,        # Optional
 ADDRESS        => address,     # Optional
 or
 { }                                    # with the same format as above

Object method Get/set query-source attributes. If PORT, or ADDRESS is passed tries to set the attributes. Returns true on success, an Err object otherwise. Else, returns value in an anonymous hash, in the same format as argument.

check_names ()

 Arguments
 type   => value,
 type   => value,
 or
 { }                            # with the same format as above

Object method. Get/set the 'check-names' attribute from the invoking object. If a list is passed as argument, it is interpreted as a hash and sets the check-names attribute. Returns true on success, an Err object otherwise. If only a single scalar is passed, it is interpreted as a type whose value is to be returned. If no arguments are passed, the value of the option is returned as an anonymous hash of the following form.

 { master => 'fail', slave => 'warn', .. }

An Err object is returned in case of error.

add_to_check_names ()

 Arguments
 type   => value,
 type   => value,
 ..

Object method. Adds the argument to 'check-names' attribute. If a certain 'check-names' type is already defined, returns an Err object. Returns true on success, an Err object otherwise.

delete_from_check_names ()

 Arguments
 LIST   # of check-names types.

Object method. Deletes 'check-names' types passed as argument, if defined and returns true on success, an Err object otherwise.

delete_check_names ()

 Arguments
 LIST           # type => 'master'|'slave'|'response'

Object method. Deletes check-names attribute if no argument is passed, else deletes only the specified type. Returns true on success, an Err object otherwise.

forwarders ()

 Arguments
 LIST                           # List of IPv4 addresses in
 or                 # dotted quad notation.
 [ LIST ]

Object method. Get/set the 'forwarders' attribute in the invoking object. If argument(s) is/are passed, the method tries to set the 'forwarders' attribute and returns true on success, an Err object otherwise. If no arguments are passed then the method tries to return an array ref if the 'forwarders' attribute is defined, an Err object otherwise.

add_to_forwarders ()

 Arguments
 LIST                           # List of IPv4 addresses in
 or                 # dotted quad notation.
 [ LIST ]

Object method. Add the elements of the list to the 'forwarders' attribute. Return true on success, an Err object otherwise.

delete_from_forwarders ()

 Arguments
 LIST                           # List of IPv4 addresses in
 or                 # dotted quad notation.
 [ LIST ]

Object method. Delete elements of the list from the 'forwarders' attribute. Return true on success, an Err object otherwise.

listen_on ()

 Arguments
 port   =>      [ qw (element1 element2 ..) ],

 OR

 port   =>      Acl object,
 port   => ...,

 OR
 {}                             # with the same format

Object method. `port' can be '' (empty string) to indicate the default port 53. Sets the values for `port's defined in the argument as the values for the `listen-on' attribute. Returns true on success, an Err object otherwise.

add_to_listen_on ()

 Arguments
 port   =>      [ qw (element1 element2 ..) ],
 port   => ...,

Object method. `port' can be '' (empty string) to indicate the default port 53.

Adds the value of `port's defined in the argument, to the ones defined in the listen-on attribute. Returns true on success, an Err object otherwise.

get_listen_on ()

 Arguments
 port           # Optional.

Object method. `port' can be '' (empty string) to indicate the default port 53. If `port' is specified, addresses defined for that port are returned as an Acl object. Else all listen-on statements are returned as an anonymous hash with keys as the defined portnos ('' for the default port) and values as Acl objects defined for that port. An Err object is returned if the listen-on option has not yet been defined.

NOTE:

Do not manipulate the returned Acl objects directly. If you do so, set the dirty flag for the Options object.

get_listen_on_elements ()

 Arguments
 port           # Optional.

Object method. `port' can be '' (empty string) to indicate the default port 53. If `port' is specified, addresses defined for that port are returned as an anonymous array. Else all listen-on statements are returned as an anonymous hash with keys as the defined portnos ('' for the default port) and values as anonymous array with addresses defined for that port. An Err object is returned if the listen-on option has not yet been defined.

delete_from_listen_on ()

 Arguments
 port   =>      [ qw (element1 element2 ..) ],
 port   => ...,

Object method. `port' can be '' (empty string) to indicate the default port 53. Deletes the value of `port's defined in the argument from the ones defined in the `listen-on' attribute and returns true on success, an Err object otherwise.

delete_listen_on ()

 Arguments
 LIST           # of ports.

Object method. port can be '' (empty string) to indicate the default port 53. If an argument(s) are passed, these ports deleted from the internal representation. Else all listen-on statements are deleted. Returns true on success, an Err object otherwise.

rrset_order ()

 Arguments
 NAME           => name,        # Optional ('*'|'.*')
 CLASS          => class,       # Optional ('ANY'|'IN')
 TYPE           => type,        # Optional ('ANY'|'A'|'NS'|'MX')
 ORDER          => order,       # ('fixed'|'randon'|'cyclic')

 or a list of hash references, where the hashes have the same
 structure as above.
 or a array reference populated with hash references with the
 same structure as above.

Object method. Sets the rrset-order option. CLASS, TYPE, NAME can be optional, in which case they are assumed to be, 'ANY', 'ANY', and '*'. Returns true on success, an Err object otherwise.

get_rrset_order ()

 Arguments
 name,          # Optional
 class,         # Optional
 type           # Optional

Object method. The following diagram should make clear the type of return to expect. If all 3 arguments are passed, the return is the order defined for the arguments as a scalar, if defined, an Err object otherwise. If type is not passed, the return value is an anonymous hash

 {
    'TYPE1' => 'order',
    'TYPE2' => 'order',
    ..
 }

for the passed name and class, if defined, an Err object otherwise. If class is not passed, the return value is an anonymous hash

 {
    'CLASS1'    => {
                        'TYPE1  => 'order',
                        'TYPE2' => 'order',
                        ..
                   },
    'CLASS2'    => {
                        'TYPE1  => 'order',
                        'TYPE2' => 'order',
                        ..
                   },
    ...
 }

for the passed name, if defined, an Err object otherwise. If even the name is not passed, the return value is an anonymous hash

 {
    'NAME1'     =>      {
        'CLASS1'    => {
                            'TYPE1      => 'order',
                            'TYPE2'     => 'order',
                            ..
                                           },
        'CLASS2'    => {
                            'TYPE1      => 'order',
                            'TYPE2'     => 'order',
                            ..
                                           },
        ...
                                },
    'NAME2'     =>      {
        'CLASS1'    => {
                            'TYPE1      => 'order',
                            'TYPE2'     => 'order',
                            ..
                                           },
        'CLASS2'    => {
                            'TYPE1      => 'order',
                            'TYPE2'     => 'order',
                            ..
                                           },
        ...
               },
    ...
 }

for all defined names, if any is defined, an Err object otherwise.

add_to_rrset_order ()

 Arguments
 NAME           => name,        # Optional ('*'|'.*')
 CLASS          => class,       # Optional ('ANY'|'IN')
 TYPE           => type,        # Optional ('ANY'|'A'|'NS'|'MX')
 ORDER          => order,       # ('fixed'|'randon'|'cyclic')

 or a list of hash references, where the hashes have the same
 structure as above.

Object method. Adds to any defined rrset-order option. CLASS, TYPE, NAME can be optional, in which case they are assumed to be, 'ANY', 'ANY', and '*'. Returns true on success, an Err object otherwise.

delete_from_rrset_order ()

 Arguments
 NAME           => name,        # Optional ('*'|'.*')
 CLASS          => class,       # Optional ('ANY'|'IN')
 TYPE           => type,        # Optional ('ANY'|'A'|'NS'|'MX')

 or a list of hash references, where the hashes have the same
 structure as above.

Object method. Deletes from any defined rrset-order option. CLASS, TYPE, NAME can be optional, in which case they are assumed to be, 'ANY', 'ANY', and '*'. Returns true on success, an Err object otherwise. Note that the method, deletes branches that have become leaves because of deletions. For example, if for NAME, CLASS the only TYPE defined is deleted, CLASS gets deleted. If NAME has no other records, NAME gets deleted too. If NAME is the only rrset-order defined, the option gets deleted.

delete_rrset_order ()

 Arguments
 name,          # Optional
 class          # Optional
 type           # Optional

Object method. If name, class and type are passed, the defined order, if any, for the same is deleted. If only name, class are passed, all defined types for that name and class are deleted, if defined. If only the name is specified, all classes defined for that name are deleted. Note that the method, deletes branches that have become leaves because of deletions. For example, if for NAME, CLASS the only TYPE defined is deleted, CLASS gets deleted. If NAME has no other records, NAME gets deleted too. If NAME is the only rrset-order defined, the option gets deleted. In all cases, true is returned on success, an Err object otherwise.

options

Object method. Iterates through the list of defined options returning their name one at a time in a scalar context, or a list of all defined option names in list context.