.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Net::NBName 3pm"
.TH Net::NBName 3pm "2017-09-09" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::NBName \- NetBIOS Name Service Requests
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Net::NBName;
\&  my $nb = Net::NBName\->new;
\&
\&  # a unicast node status request
\&  my $ns = $nb\->node_status("10.0.0.1");
\&  if ($ns) {
\&      print $ns\->as_string;
\&  }
\&
\&  # a unicast name query request
\&  my $nq = $nb\->name_query("10.0.1.80", "SPARK", 0x00);
\&  if ($nq) {
\&      print $nq\->as_string;
\&  }
\&
\&  # a broadcast name query request
\&  my $nq = $nb\->name_query(undef, "SPARK", 0x00);
\&  if ($nq) {
\&      print $nq\->as_string;
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::NBName is a class that allows you to perform simple NetBIOS Name
Service Requests in your Perl code. It performs these NetBIOS operations over
\&\s-1TCP/IP\s0 using Perl's built-in socket support.
.PP
I've currently implemented two \s-1NBNS\s0 requests: the node status request
and the name query request.
.IP "NetBIOS Node Status Request" 4
.IX Item "NetBIOS Node Status Request"
This allows you to determine the registered NetBIOS names for a
specified remote host.
.Sp
The decoded response is returned as a \f(CW\*(C`Net::NBName::NodeStatus\*(C'\fR object.
.Sp
.Vb 11
\&    querying 192.168.0.10 for node status...
\&    SPARK          <20> UNIQUE M\-node Registered Active
\&    SPARK          <00> UNIQUE M\-node Registered Active
\&    PLAYGROUND     <00> GROUP  M\-node Registered Active
\&    PLAYGROUND     <1C> GROUP  M\-node Registered Active
\&    PLAYGROUND     <1B> UNIQUE M\-node Registered Active
\&    PLAYGROUND     <1E> GROUP  M\-node Registered Active
\&    SPARK          <03> UNIQUE M\-node Registered Active
\&    PLAYGROUND     <1D> UNIQUE M\-node Registered Active
\&    .._\|_MSBROWSE_\|_.<01> GROUP  M\-node Registered Active
\&    MAC Address = 00\-1C\-2B\-3A\-49\-58
.Ve
.IP "NetBIOS Name Query Request" 4
.IX Item "NetBIOS Name Query Request"
This allows you to resolve a name to an \s-1IP\s0 address using NetBIOS Name
Resolution. These requests can either be unicast (e.g. if you are querying
an \s-1NBNS\s0 server) or broadcast on the local subnet.
.Sp
In either case, the decoded response is returned as an
\&\f(CW\*(C`Net::NBName::NameQuery\*(C'\fR object.
.Sp
.Vb 4
\&    querying 192.168.0.10 for playground<00>...
\&    255.255.255.255 GROUP  B\-node
\&    ttl = 0 (default is 300000)
\&    RA set, this was an NBNS server
\&
\&    broadcasting for playground<1C>...
\&    192.168.0.10    GROUP  B\-node
\&    ttl = 0 (default is 300000)
\&    RA set, this was an NBNS server
\&
\&    broadcasting for spark<20>...
\&    192.168.0.10    UNIQUE H\-node
\&    ttl = 0 (default is 300000)
\&    RA set, this was an NBNS server
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP "$nb = Net::NBName\->new" 4
.el .IP "\f(CW$nb\fR = Net::NBName\->new" 4
.IX Item "$nb = Net::NBName->new"
Creates a new \f(CW\*(C`Net::NBName\*(C'\fR object. This can be used to perform NetBIOS
Name Service requests.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$ns = $nb\->node_status( $host [, $timeout] )" 4
.el .IP "\f(CW$ns\fR = \f(CW$nb\fR\->node_status( \f(CW$host\fR [, \f(CW$timeout\fR] )" 4
.IX Item "$ns = $nb->node_status( $host [, $timeout] )"
This will query the host for its node status. The response will
be returned as a \f(CW\*(C`Net::NBName::NodeStatus\*(C'\fR object.
.Sp
If no response is received from the host, the method will return undef.
.Sp
You can also optionally specify the timeout in seconds for the node status
request. The timeout defaults to .25 seconds.
.ie n .IP "$nq = $nb\->name_query( $host, $name, $suffix [, $flags [, $timeout] ] )" 4
.el .IP "\f(CW$nq\fR = \f(CW$nb\fR\->name_query( \f(CW$host\fR, \f(CW$name\fR, \f(CW$suffix\fR [, \f(CW$flags\fR [, \f(CW$timeout\fR] ] )" 4
.IX Item "$nq = $nb->name_query( $host, $name, $suffix [, $flags [, $timeout] ] )"
This will query the host for the specified name. The response will
be returned as a \f(CW\*(C`Net::NBName::NameQuery\*(C'\fR object.
.Sp
If \f(CW$host\fR is undef, then a broadcast name query will
be performed; otherwise, a unicast name query will be performed.
.Sp
Broadcast name queries can sometimes receive multiple responses.
Only the first positive response will be decoded and returned as a
\&\f(CW\*(C`Net::NBName::NameQuery\*(C'\fR object.
.Sp
If no response is received or a negative name query response is received,
the method will return undef.
.Sp
You can override the flags in the NetBIOS name request, if you *really*
want to. See the notes on Hacking Name Query Flags.
.Sp
You can also optionally specify the timeout in seconds for the name query
request. It defaults to .25 seconds for unicast name queries and 1 second
for broadcast name queries.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Querying NetBIOS Names"
.IX Subsection "Querying NetBIOS Names"
You can use this example to query for a NetBIOS name. If you specify a host,
it will perform a unicast query; if you don't specify a host, it will
perform a broadcast query. I've used the shorthand of specifying the name
as <name>#<suffix> where the suffix should be in hex.
.PP
\&\*(L"namequery.pl spark#0\*(R"
.PP
\&\*(L"namequery.pl spark#20 192.168.0.10\*(R"
.PP
.Vb 2
\&    use strict;
\&    use Net::NBName;
\&
\&    my $nb = Net::NBName\->new;
\&    my $param = shift;
\&    my $host = shift;
\&    if ($param =~ /^([\ew\-]+)\e#(\ew{1,2})$/) {
\&        my $name = $1;
\&        my $suffix = hex $2;
\&
\&        my $nq;
\&        if (defined($host) && $host =~ /\ed+\e.\ed+\e.\ed+\e.\ed+/) {
\&            printf "querying %s for %s<%02X>...\en", $host, $name, $suffix;
\&            $nq = $nb\->name_query($host, $name, $suffix);
\&        } else {
\&            printf "broadcasting for %s<%02X>...\en", $name, $suffix;
\&            $nq = $nb\->name_query(undef, $name, $suffix);
\&        }
\&        if ($nq) {
\&            print $nq\->as_string;
\&        }
\&    } else {
\&        die "expected: <name>#<suffix> [<host>]\en";
\&    }
.Ve
.SS "Querying Remote Name Table"
.IX Subsection "Querying Remote Name Table"
This example emulates the windows nbtstat \-A command. By specifying
the ip address of the remote host, you can check its NetBIOS Name Table.
.PP
\&\*(L"nodestat.pl 192.168.0.10\*(R"
.PP
.Vb 1
\&    use Net::NBName;
\&
\&    my $nb = Net::NBName\->new;
\&    my $host = shift;
\&    if (defined($host) && $host =~ /\ed+\e.\ed+\e.\ed+\e.\ed+/) {
\&        my $ns = $nb\->node_status($host);
\&        if ($ns) {
\&            print $ns\->as_string;
\&        } else {
\&            print "no response\en";
\&        }
\&    } else {
\&        die "expected: <host>\en";
\&    }
.Ve
.SS "Scanning for NetBIOS hosts"
.IX Subsection "Scanning for NetBIOS hosts"
This example can be used to scan for NetBIOS hosts on a subnet. It uses
Net::Netmask to parse the subnet parameter and enumerate the hosts in
that subnet.
.PP
\&\*(L"nodescan.pl 192.168.0.0/24\*(R"
.PP
.Vb 2
\&    use Net::NBName;
\&    use Net::Netmask;
\&
\&    $mask = shift or die "expected: <subnet>\en";
\&
\&    $nb = Net::NBName\->new;
\&    $subnet = Net::Netmask\->new2($mask);
\&    for $ip ($subnet\->enumerate) {
\&        print "$ip ";
\&        $ns = $nb\->node_status($ip);
\&        if ($ns) {
\&            for my $rr ($ns\->names) {
\&                if ($rr\->suffix == 0 && $rr\->G eq "GROUP") {
\&                    $domain = $rr\->name;
\&                }
\&                if ($rr\->suffix == 3 && $rr\->G eq "UNIQUE") {
\&                    $user = $rr\->name;
\&                }
\&                if ($rr\->suffix == 0 && $rr\->G eq "UNIQUE") {
\&                    $machine = $rr\->name unless $rr\->name =~ /^IS~/;
\&                }
\&            }
\&            $mac_address = $ns\->mac_address;
\&            print "$mac_address $domain\e\e$machine $user";
\&        }
\&        print "\en";
\&    }
.Ve
.SH "NOTES"
.IX Header "NOTES"
.SS "Microsoft's \s-1WINS\s0 Server Implementation"
.IX Subsection "Microsoft's WINS Server Implementation"
When performing name queries, you should note that when Microsoft implemented
their \s-1NBNS\s0 Name Server (Microsoft \s-1WINS\s0 Server) they mapped group names to the
single \s-1IP\s0 address 255.255.255.255 (the limited broadcast address). In order to
support \fIreal\fR group names, Microsoft modified \s-1WINS\s0 to provide support for
special groups. These groups appear differently in \s-1WINS.\s0 For example, the
Domain Controllers (0x1C) group appears as \*(L"Domain Name\*(R" instead of \*(L"Group\*(R".
.PP
The complete set of \s-1WINS\s0 mapping types is:
.PP
.Vb 5
\&    Unique
\&    Group
\&    Domain Name
\&    Internet group
\&    Multihomed
.Ve
.PP
Unique and Group map to a single \s-1IP\s0 address. Domain Name, Internet group, and
Multihomed are special groups that can include up to 25 \s-1IP\s0 addresses.
.SS "Hacking Name Query Flags"
.IX Subsection "Hacking Name Query Flags"
NetBIOS Name Service Requests have a number of flags associated with them.
These are set to sensible defaults by the code when sending node status
and name query requests.
.PP
However, it is possible to override these settings by calling the
name_query method of a \f(CW\*(C`Net::NBName\*(C'\fR object with a fourth parameter:
.PP
.Vb 1
\&    $nb\->name_query( $host, $name, $suffix, $flags );
.Ve
.PP
For a unicast name query, the flags default to 0x0100 which sets the \s-1RD\s0
(recursion desired) flag. For a broadcast name query, the flags default to
0x0010 which sets the B (broadcast) flag.
.PP
Experimentation gave the following results:
.IP "\(bu" 4
If B is set, the remote name table will be used. There will be no response if
the queried name is not present.
.IP "\(bu" 4
If B is not set and the host is an \s-1NBNS\s0 server, the \s-1NBNS\s0 server will be used
before the remote name table and you will get a negative response if the name
is not present; if the host is not an \s-1NBNS\s0 server, you will get no response if
the name is not present.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2002, 2003, 2004 James Macfarlane. All rights reserved. This
program is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.