1Net::Server::Proto(3) User Contributed Perl DocumentationNet::Server::Proto(3)
2
3
4

NAME

6       Net::Server::Proto - Net::Server Protocol compatibility layer
7

SYNOPSIS

9           NOTE: beginning in Net::Server 2.005, the default value for
10                 ipv is IPv* meaning that if no host is passed, or
11                 a hostname is past, all available socket types will be
12                 bound.  You can force IPv4 only by adding an ipv => 4
13                 configuration in any of the half dozen ways we let you
14                 specify it.
15
16           NOTE: For IPv6 Net::Server will first try and use the module
17                 listed in server config ipv6_package, then
18                 $Net::Server::ipv6_package, then IO::Socket::IP, then
19                 IO::Socket::INET6 (which is deprecated).
20
21           # Net::Server::Proto and its accompanying modules are not
22           # intended to be used outside the scope of Net::Server.
23
24           # That being said, here is how you use them.  This is
25           # only intended for anybody wishing to extend the
26           # protocols to include some other set (ie maybe a
27           # database connection protocol)
28
29           use Net::Server::Proto;
30
31           my @info = Net::Server::Proto->parse_info(
32               $port,            # port to connect to
33               $default_host,    # host to use if none found in port
34               $default_proto,   # proto to use if none found in port
35               $default_ipv,     # default of IPv6 or IPv4 if none found in port
36               $server_obj,      # Net::Server object
37           );
38
39           my @raw_info = Net::Server::Proto->get_addr_info($host, $port, $proto);
40           # returns arrayref of resolved ips, ports, and ipv values
41
42           my $sock = Net::Server::Proto->object({
43               port  => $port,
44               host  => $host,
45               proto => $proto,
46               ipv   => $ipv, # * (IPv*) if false (default false)
47           }, $server);
48
49           # Net::Server::Proto will attempt to interface with
50           # sub modules named similar to Net::Server::Proto::TCP
51           # Individual sub modules will be loaded by
52           # Net::Server::Proto as they are needed.
53
54           use Net::Server::Proto::TCP; # or UDP or UNIX etc
55
56           # Return an object which is a sub class of IO::Socket
57           # At this point the object is not connected.
58           # The method can gather any other information that it
59           # needs from the server object.
60           my $sock = Net::Server::Proto::TCP->object({
61               port  => $port,
62               host  => $host,
63               proto => $proto,
64               ipv   => 6, # IPv6 - default is * - can also be '4'
65           }, $server);
66
67
68           # Log that a connection is about to occur.
69           # Use the facilities of the passed Net::Server object.
70           $sock->log_connect( $server );
71
72           # Actually bind to port or socket file.  This
73           # is typically done by calling the configure method.
74           $sock->connect();
75
76           # Allow for rebinding to an already open fileno.
77           # Typically will just do an fdopen.
78           $sock->reconnect();
79
80           ### Return a unique identifying string for this sock that
81           # can be used when reconnecting.
82           my $str = $sock->hup_string();
83
84           # Return the proto that is being used by this module.
85           my $proto = $sock->NS_proto();
86

DESCRIPTION

88       Net::Server::Proto is an intermediate module which returns IO::Socket
89       style objects blessed into its own set of classes (ie
90       Net::Server::Proto::TCP, Net::Server::Proto::UNIX).
91
92       Only three or four protocols come bundled with Net::Server.  TCP, UDP,
93       UNIX, UNIXDGRAM, and SSLEAY.  TCP is an implementation of SOCK_STREAM
94       across an INET socket.  UDP is an implementation of SOCK_DGRAM across
95       an INET socket.  UNIX uses a unix style socket file with the
96       SOCK_STREAM protocol.  UNIXGRAM uses a unix style socket file with the
97       SOCK_DGRAM protocol.  SSLEAY is actually just a layer on top of TCP but
98       uses Net::SSLeay to read and write from the stream.
99
100       The protocol that is passed to Net::Server can be the name of another
101       module which contains the protocol bindings.  If a protocol of
102       MyServer::MyTCP was passed, the socket would be blessed into that
103       class.  If Net::Server::Proto::TCP was passed, it would get that class.
104       If a bareword, such as tcp, udp, unix, unixdgram or ssleay, is passed,
105       the word is uppercased, and post pended to "Net::Server::Proto::" (ie
106       tcp = Net::Server::Proto::TCP).
107

METHODS

109       Protocol names used by the Net::Server::Proto should be sub classes of
110       IO::Socket.  These classes should also contain, as a minimum, the
111       following methods should be provided:
112
113       object
114           Return an object which is a sub class of IO::Socket At this point
115           the object is not connected.  The method can gather any other
116           information that it needs from the server object.  Arguments are
117           default_host, port, and a Net::Server style server object.
118
119       log_connect
120           Log that a connection is about to occur.  Use the facilities of the
121           passed Net::Server object.  This should be an informative string
122           explaining which properties are being used.
123
124       connect
125           Actually bind to port or socket file.  This is typically done
126           internally by calling the configure method of the IO::Socket super
127           class.
128
129       reconnect
130           Allow for rebinding to an already open fileno.  Typically will just
131           do an fdopen using the IO::Socket super class.
132
133       hup_string
134           Return a unique identifying string for this sock that can be used
135           when reconnecting.  This is done to allow information including the
136           file descriptor of the open sockets to be passed via %ENV during an
137           exec.  This string should always be the same based upon the
138           configuration parameters.
139
140       NS_port
141           Net::Server protocol.  Return the port that is being used by this
142           module.  If the underlying type is UNIX then port will actually be
143           the path to the unix socket file.
144
145       NS_host
146           Net::Server protocol.  Return the protocol that is being used by
147           this module.  This does not have to be a registered or known
148           protocol.
149
150       NS_proto
151           Net::Server protocol.  Return the protocol that is being used by
152           this module.  This does not have to be a registered or known
153           protocol.
154
155       show
156           Similar to log_connect, but simply shows a listing of which
157           properties were found.  Can be used at any time.
158

HOST

160       The hostname may be either blank, '*', be an IPv4 address, an IPv6
161       address, a bare hostname, or a hostname with IPv* specifications.
162
163           host => "127.0.0.1",  # an IPv4 address
164
165           host => "::1",        # an IPv6 address
166
167           host => 'localhost',  # addresses returned by localhost (default IPv* - IPv4 and/or IPv6)
168
169           host => 'localhost/IPv*',  # same
170
171           ipv  => '*',
172           host => 'localhost',  # same
173
174           ipv  => 6,
175           host => 'localhost',  # addresses returned by localhost (IPv6)
176
177           ipv  => 'IPv4 IPv6',
178           host => 'localhost',  # addresses returned by localhost (requires IPv6 and IPv4)
179
180
181           host => '*',          # any local interfaces (default IPv*)
182
183           ipv  => '*',
184           host => '*',          # any local interfaces (any IPv6 or IPv4)
185
186           host => '*/IPv*',     # same
187

IPV

189       In addition to being able to specify IPV as a separate parameter, ipv
190       may also be passed as a part of the host, as part of the port, as part
191       of the protocol or may be specified via $ENV{'IPV'}.  The order of
192       precedence is as follows:
193
194            1) Explicit IPv4 or IPv6 address - wins
195            2) ipv specified in port
196            3) ipv specified in host
197            4) ipv specified in proto
198            5) ipv specified in default settings
199            6) ipv specified in $ENV{'IPV'}
200            7) default to IPv*
201

PORT

203       The port is the most important argument passed to the sub module
204       classes and to Net::Server::Proto itself.  For tcp, udp, and ssleay
205       style ports, the form is generally host:port/protocol,
206       [host]:port/protocol, host|port|protocol, host/port, or port.  If host
207       is a numerical IPv6 address it should be enclosed in square brackets to
208       avoid ambiguity in parsing a port number, e.g.: "[::1]:80".  Separating
209       with spaces, commas, or pipes is also allowed, e.g. "::1, 80".  For
210       unix sockets the form is generally socket_file|unix or socket_file.
211
212       To help overcome parsing ambiguity, it is also possible to pass port as
213       a hashref (or as an array of hashrefs) of information such as:
214
215           port => {
216               host  => "localhost",
217               ipv   => 6, # could also pass IPv6 (* is default)
218               port  => 20203,
219               proto => 'tcp',
220           }
221
222       If a hashref does not include host, ipv, or proto - it will use the
223       default value supplied by the general configuration.
224
225       A socket protocol family PF_INET or PF_INET6 is derived from a
226       specified address family of the binding address. A PF_INET socket can
227       only accept IPv4 connections. A PF_INET6 socket accepts IPv6
228       connections, but may also accept IPv4 connections, depending on OS and
229       its settings. For example, on FreeBSD systems setting a sysctl
230       net.inet6.ip6.v6only to 0 will allow IPv4 connections to a PF_INET6
231       socket.  By default on linux, binding to host [::] will accept IPv4 or
232       IPv6 connections.
233
234       The Net::Server::Proto::object method returns a list of objects
235       corresponding to created sockets. For Unix and INET sockets the list
236       typically contains just one element, but may return multiple objects
237       when multiple protocol families are allowed or when a host name
238       resolves to multiple local binding addresses.  This is particularly
239       true when an ipv value of '*' is passed in allowing hostname
240       resolution.
241
242       You can see what Net::Server::Proto parsed out by looking at the logs
243       to see what log_connect said.  You could also include a post_bind_hook
244       similar to the following to debug what happened:
245
246           sub post_bind_hook {
247               my $self = shift;
248               foreach my $sock ( @{ $self->{server}->{sock} } ){
249                   $self->log(2,$sock->show);
250               }
251           }
252
253       Rather than try to explain further, please look at the following
254       examples:
255
256           # example 1 #----------------------------------
257
258           $port      = "20203";
259           $def_host  = "default-domain.com";
260           $def_proto = undef;
261           $def_ipv   = undef;
262           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
263           # @info = {
264           #     host  => 'default-domain.com',
265           #     port  => 20203,
266           #     proto => 'tcp', # will use Net::Server::Proto::TCP
267           #     ipv   => *, # IPv*
268           # };
269
270           # example 2 #----------------------------------
271
272           $port      = "someother.com:20203";
273           $def_host  = "default-domain.com";
274           $def_proto = "tcp";
275           $def_ipv   = undef;
276           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
277           # @info = {
278           #     host  => 'someother.com',
279           #     port  => 20203,
280           #     proto => 'tcp', # will use Net::Server::Proto::TCP
281           #     ipv   => *,
282           # };
283
284           # example 3 #----------------------------------
285
286           $port      = "someother.com:20203/udp";
287           $def_host  = "default-domain.com";
288           $def_proto = "tcp";
289           $def_ipv   = undef;
290           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
291           # @info = {
292           #     host  => 'someother.com',
293           #     port  => 20203,
294           #     proto => 'udp', # will use Net::Server::Proto::UDP
295           #     ipv   => *,
296           # };
297
298           # example 4 #----------------------------------
299
300           $port      = "someother.com:20203/Net::Server::Proto::UDP";
301           $def_host  = "default-domain.com";
302           $def_proto = "TCP";
303           $def_ipv   = 4;
304           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
305           # @info = {
306           #     host  => 'someother.com',
307           #     port  => 20203,
308           #     proto => 'Net::Server::Proto::UDP',
309           #     ipv   => 4,
310           # };
311
312           # example 5 #----------------------------------
313
314           $port      = "someother.com:20203/MyObject::TCP";
315           $def_host  = "default-domain.com";
316           $def_proto = "tcp";
317           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto);
318           # @info = {
319           #     host  => 'someother.com',
320           #     port  => 20203,
321           #     proto => 'MyObject::TCP',
322           # };
323
324           # example 6 #----------------------------------
325
326           $port      = "/tmp/mysock.file|unix";
327           $def_host  = "default-domain.com";
328           $def_proto = "tcp";
329           $def_ipv   = undef;
330           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
331           # @info = {
332           #     host  => '*', # irrelevant for UNIX socket
333           #     port  => '/tmp/mysock.file', # not really a port
334           #     proto => 'unix', # will use Net::Server::Proto::UNIX
335           #     ipv   => '*', # irrelevant for UNIX socket
336           # };
337
338           # example 7 #----------------------------------
339
340           $port      = "/tmp/mysock.file|unixdgram";
341           $def_host  = "default-domain.com";
342           $def_proto = "tcp";
343           $def_ipv   = undef;
344           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
345           # @info = {
346           #     host  => '*', # irrelevant for UNIX socket
347           #     port  => '/tmp/mysock.file', # not really a port
348           #     proto => 'unixdgram', # will use Net::Server::Proto::UNIXDGRAM
349           #     ipv   => '*', # irrelevant for UNIX socket
350           # };
351
352           # example 8 #----------------------------------
353
354           $port      = "/tmp/mysock.file|SOCK_STREAM|unix"; # legacy
355           $def_host  = "";
356           $def_proto = "tcp";
357           $def_ipv   = undef;
358           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
359           # @info = {
360           #     host  => '*', # irrelevant for UNIX socket
361           #     port  => '/tmp/mysock.file', # not really a port
362           #     proto => 'unix', # will use Net::Server::Proto::UNIX
363           #     unix_type => 'SOCK_STREAM',
364           #     ipv   => '*', # irrelevant for UNIX socket
365           # };
366
367           # example 9 #----------------------------------
368
369           $port      = "/tmp/mysock.file|SOCK_DGRAM|unix"; # legacy
370           $def_host  = "";
371           $def_proto = "tcp";
372           $def_ipv   = undef;
373           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
374           # @info = {
375           #     host  => '*', # irrelevant for UNIX socket
376           #     port  => '/tmp/mysock.file', # not really a port
377           #     proto => 'unix', # will use Net::Server::Proto::UNIXDGRAM
378           #     unix_type => 'SOCK_DGRAM',
379           #     ipv   => '*', # irrelevant for UNIX socket
380           # };
381
382           # example 10 #----------------------------------
383
384           $port = "someother.com:20203/ssleay";
385           $def_host  = "default-domain.com";
386           $def_proto = "tcp";
387           $def_ipv   = undef;
388           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
389           # @info = {
390           #     host  => 'someother.com',
391           #     port  => 20203,
392           #     proto => 'ssleay', # will use Net::Server::Proto::SSLEAY
393           #     ipv   => *,
394           # };
395
396           # example 11 #----------------------------------
397
398           $port = "[::1]:20203 ipv6 tcp";
399           $def_host  = "default-domain.com";
400           $def_proto = "tcp";
401           $def_ipv   = undef;
402           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
403           # @info = {
404           #     host  => '::1',
405           #     port  => 20203,
406           #     proto => 'tcp', # will use Net::Server::Proto::TCP
407           #     ipv   => 6,
408           # };
409
410           # example 12 #----------------------------------
411
412           $port = "[::1]:20203 tcp";
413           $def_host  = "default-domain.com/IPv6";
414           $def_proto = "tcp";
415           $def_ipv   = undef;
416           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
417           # @info = {
418           #     host  => '::1',
419           #     port  => 20203,
420           #     proto => 'tcp', # will use Net::Server::Proto::TCP
421           #     ipv   => 6,
422           # };
423
424           # example 13 #----------------------------------
425
426           $port = "[someother.com]:20203 ipv6 ipv4 tcp";
427           $def_host  = "default-domain.com";
428           $def_proto = "tcp";
429           $def_ipv   = undef;
430           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
431           # @info = ({
432           #     host  => 'someother.com',
433           #     port  => 20203,
434           #     proto => 'tcp', # will use Net::Server::Proto::TCP
435           #     ipv   => 4,
436           # }, {
437           #     host  => 'someother.com',
438           #     port  => 20203,
439           #     proto => 'tcp', # will use Net::Server::Proto::TCP
440           #     ipv   => 6,
441           # });
442
443           # example 14 #----------------------------------
444
445           # depending upon your configuration
446           $port = "localhost:20203";
447           $def_host  = "default-domain.com";
448           $def_proto = "tcp";
449           $def_ipv   = undef;
450           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
451           # @info = ({
452           #     host  => '127.0.0.1',
453           #     port  => 20203,
454           #     proto => 'tcp', # will use Net::Server::Proto::TCP
455           #     ipv   => 4, # IPv4
456           # }, {
457           #     host  => '::1',
458           #     port  => 20203,
459           #     proto => 'tcp', # will use Net::Server::Proto::TCP
460           #     ipv   => 6, # IPv6
461           # });
462
463           # example 15 #----------------------------------
464
465           # depending upon your configuration
466           $port = "localhost:20203";
467           $def_host  = "default-domain.com IPv*";
468           $def_proto = "tcp";
469           $def_ipv   = undef;
470           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
471           # @info = ({
472           #     host  => '127.0.0.1',
473           #     port  => 20203,
474           #     proto => 'tcp', # will use Net::Server::Proto::TCP
475           #     ipv   => 4, # IPv4
476           # }, {
477           #     host  => '::1',
478           #     port  => 20203,
479           #     proto => 'tcp', # will use Net::Server::Proto::TCP
480           #     ipv   => 6, # IPv6
481           # });
482
483           # example 16 #----------------------------------
484
485           # depending upon your configuration
486           $ENV{'IPV'} = '4';
487           $port = "localhost:20203";
488           $def_host  = "default-domain.com";
489           $def_proto = "tcp";
490           $def_ipv   = undef;
491           @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
492           # @info = ({
493           #     host  => '127.0.0.1',
494           #     port  => 20203,
495           #     proto => 'tcp', # will use Net::Server::Proto::TCP
496           #     ipv   => 4, # IPv4
497           # });
498

LICENCE

500       Distributed under the same terms as Net::Server
501
502
503
504perl v5.36.0                      2023-03-17             Net::Server::Proto(3)
Impressum