1Net::NBName(3)        User Contributed Perl Documentation       Net::NBName(3)
2
3
4

NAME

6       Net::NBName - NetBIOS Name Service Requests
7

SYNOPSIS

9         use Net::NBName;
10         my $nb = Net::NBName->new;
11
12         # a unicast node status request
13         my $ns = $nb->node_status("10.0.0.1");
14         if ($ns) {
15             print $ns->as_string;
16         }
17
18         # a unicast name query request
19         my $nq = $nb->name_query("10.0.1.80", "SPARK", 0x00);
20         if ($nq) {
21             print $nq->as_string;
22         }
23
24         # a broadcast name query request
25         my $nq = $nb->name_query(undef, "SPARK", 0x00);
26         if ($nq) {
27             print $nq->as_string;
28         }
29

DESCRIPTION

31       Net::NBName is a class that allows you to perform simple NetBIOS Name
32       Service Requests in your Perl code. It performs these NetBIOS
33       operations over TCP/IP using Perl's built-in socket support.
34
35       I've currently implemented two NBNS requests: the node status request
36       and the name query request.
37
38       NetBIOS Node Status Request
39           This allows you to determine the registered NetBIOS names for a
40           specified remote host.
41
42           The decoded response is returned as a "Net::NBName::NodeStatus"
43           object.
44
45               querying 192.168.0.10 for node status...
46               SPARK          <20> UNIQUE M-node Registered Active
47               SPARK          <00> UNIQUE M-node Registered Active
48               PLAYGROUND     <00> GROUP  M-node Registered Active
49               PLAYGROUND     <1C> GROUP  M-node Registered Active
50               PLAYGROUND     <1B> UNIQUE M-node Registered Active
51               PLAYGROUND     <1E> GROUP  M-node Registered Active
52               SPARK          <03> UNIQUE M-node Registered Active
53               PLAYGROUND     <1D> UNIQUE M-node Registered Active
54               ..__MSBROWSE__.<01> GROUP  M-node Registered Active
55               MAC Address = 00-1C-2B-3A-49-58
56
57       NetBIOS Name Query Request
58           This allows you to resolve a name to an IP address using NetBIOS
59           Name Resolution. These requests can either be unicast (e.g. if you
60           are querying an NBNS server) or broadcast on the local subnet.
61
62           In either case, the decoded response is returned as an
63           "Net::NBName::NameQuery" object.
64
65               querying 192.168.0.10 for playground<00>...
66               255.255.255.255 GROUP  B-node
67               ttl = 0 (default is 300000)
68               RA set, this was an NBNS server
69
70               broadcasting for playground<1C>...
71               192.168.0.10    GROUP  B-node
72               ttl = 0 (default is 300000)
73               RA set, this was an NBNS server
74
75               broadcasting for spark<20>...
76               192.168.0.10    UNIQUE H-node
77               ttl = 0 (default is 300000)
78               RA set, this was an NBNS server
79

CONSTRUCTOR

81       $nb = Net::NBName->new
82           Creates a new "Net::NBName" object. This can be used to perform
83           NetBIOS Name Service requests.
84

METHODS

86       $ns = $nb->node_status( $host [, $timeout] )
87           This will query the host for its node status. The response will be
88           returned as a "Net::NBName::NodeStatus" object.
89
90           If no response is received from the host, the method will return
91           undef.
92
93           You can also optionally specify the timeout in seconds for the node
94           status request. The timeout defaults to .25 seconds.
95
96       $nq = $nb->name_query( $host, $name, $suffix [, $flags [, $timeout] ] )
97           This will query the host for the specified name. The response will
98           be returned as a "Net::NBName::NameQuery" object.
99
100           If $host is undef, then a broadcast name query will be performed;
101           otherwise, a unicast name query will be performed.
102
103           Broadcast name queries can sometimes receive multiple responses.
104           Only the first positive response will be decoded and returned as a
105           "Net::NBName::NameQuery" object.
106
107           If no response is received or a negative name query response is
108           received, the method will return undef.
109
110           You can override the flags in the NetBIOS name request, if you
111           *really* want to. See the notes on Hacking Name Query Flags.
112
113           You can also optionally specify the timeout in seconds for the name
114           query request. It defaults to .25 seconds for unicast name queries
115           and 1 second for broadcast name queries.
116

EXAMPLES

118   Querying NetBIOS Names
119       You can use this example to query for a NetBIOS name. If you specify a
120       host, it will perform a unicast query; if you don't specify a host, it
121       will perform a broadcast query. I've used the shorthand of specifying
122       the name as <name>#<suffix> where the suffix should be in hex.
123
124       "namequery.pl spark#0"
125
126       "namequery.pl spark#20 192.168.0.10"
127
128           use strict;
129           use Net::NBName;
130
131           my $nb = Net::NBName->new;
132           my $param = shift;
133           my $host = shift;
134           if ($param =~ /^([\w-]+)\#(\w{1,2})$/) {
135               my $name = $1;
136               my $suffix = hex $2;
137
138               my $nq;
139               if (defined($host) && $host =~ /\d+\.\d+\.\d+\.\d+/) {
140                   printf "querying %s for %s<%02X>...\n", $host, $name, $suffix;
141                   $nq = $nb->name_query($host, $name, $suffix);
142               } else {
143                   printf "broadcasting for %s<%02X>...\n", $name, $suffix;
144                   $nq = $nb->name_query(undef, $name, $suffix);
145               }
146               if ($nq) {
147                   print $nq->as_string;
148               }
149           } else {
150               die "expected: <name>#<suffix> [<host>]\n";
151           }
152
153   Querying Remote Name Table
154       This example emulates the windows nbtstat -A command. By specifying the
155       ip address of the remote host, you can check its NetBIOS Name Table.
156
157       "nodestat.pl 192.168.0.10"
158
159           use Net::NBName;
160
161           my $nb = Net::NBName->new;
162           my $host = shift;
163           if (defined($host) && $host =~ /\d+\.\d+\.\d+\.\d+/) {
164               my $ns = $nb->node_status($host);
165               if ($ns) {
166                   print $ns->as_string;
167               } else {
168                   print "no response\n";
169               }
170           } else {
171               die "expected: <host>\n";
172           }
173
174   Scanning for NetBIOS hosts
175       This example can be used to scan for NetBIOS hosts on a subnet. It uses
176       Net::Netmask to parse the subnet parameter and enumerate the hosts in
177       that subnet.
178
179       "nodescan.pl 192.168.0.0/24"
180
181           use Net::NBName;
182           use Net::Netmask;
183
184           $mask = shift or die "expected: <subnet>\n";
185
186           $nb = Net::NBName->new;
187           $subnet = Net::Netmask->new2($mask);
188           for $ip ($subnet->enumerate) {
189               print "$ip ";
190               $ns = $nb->node_status($ip);
191               if ($ns) {
192                   for my $rr ($ns->names) {
193                       if ($rr->suffix == 0 && $rr->G eq "GROUP") {
194                           $domain = $rr->name;
195                       }
196                       if ($rr->suffix == 3 && $rr->G eq "UNIQUE") {
197                           $user = $rr->name;
198                       }
199                       if ($rr->suffix == 0 && $rr->G eq "UNIQUE") {
200                           $machine = $rr->name unless $rr->name =~ /^IS~/;
201                       }
202                   }
203                   $mac_address = $ns->mac_address;
204                   print "$mac_address $domain\\$machine $user";
205               }
206               print "\n";
207           }
208

NOTES

210   Microsoft's WINS Server Implementation
211       When performing name queries, you should note that when Microsoft
212       implemented their NBNS Name Server (Microsoft WINS Server) they mapped
213       group names to the single IP address 255.255.255.255 (the limited
214       broadcast address). In order to support real group names, Microsoft
215       modified WINS to provide support for special groups. These groups
216       appear differently in WINS. For example, the Domain Controllers (0x1C)
217       group appears as "Domain Name" instead of "Group".
218
219       The complete set of WINS mapping types is:
220
221           Unique
222           Group
223           Domain Name
224           Internet group
225           Multihomed
226
227       Unique and Group map to a single IP address. Domain Name, Internet
228       group, and Multihomed are special groups that can include up to 25 IP
229       addresses.
230
231   Hacking Name Query Flags
232       NetBIOS Name Service Requests have a number of flags associated with
233       them.  These are set to sensible defaults by the code when sending node
234       status and name query requests.
235
236       However, it is possible to override these settings by calling the
237       name_query method of a "Net::NBName" object with a fourth parameter:
238
239           $nb->name_query( $host, $name, $suffix, $flags );
240
241       For a unicast name query, the flags default to 0x0100 which sets the RD
242       (recursion desired) flag. For a broadcast name query, the flags default
243       to 0x0010 which sets the B (broadcast) flag.
244
245       Experimentation gave the following results:
246
247       •   If B is set, the remote name table will be used. There will be no
248           response if the queried name is not present.
249
250       •   If B is not set and the host is an NBNS server, the NBNS server
251           will be used before the remote name table and you will get a
252           negative response if the name is not present; if the host is not an
253           NBNS server, you will get no response if the name is not present.
254
256       Copyright (c) 2002, 2003, 2004 James Macfarlane. All rights reserved.
257       This program is free software; you can redistribute it and/or modify it
258       under the same terms as Perl itself.
259
260
261
262perl v5.32.1                      2021-01-27                    Net::NBName(3)
Impressum