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

DESCRIPTION

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

METHODS

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

HOST

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

IPV

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

PORT

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

LICENCE

495       Distributed under the same terms as Net::Server
496
497
498
499perl v5.34.0                      2021-07-22             Net::Server::Proto(3)
Impressum