Debian Codegraph @

upstream/debian-unstable/man3/Net::Config.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Net::Config 3perl"
58 .TH Net::Config 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Net::Config \- Local configuration data for libnet
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Net::Config qw(%NetConfig);
69 .Ve
70 .SH DESCRIPTION
71 .IX Header "DESCRIPTION"
72 \&\f(CW\*(C`Net::Config\*(C'\fR holds configuration data for the modules in the libnet
73 distribution. During installation you will be asked for these values.
74 .PP
75 The configuration data is held globally in \f(CW\*(C`/etc/perl/Net/libnet.cfg\*(C'\fR,
76 but a user may override any of these values by providing their own. This
77 can be done by having a \f(CW\*(C`.libnetrc\*(C'\fR file in their home directory. This file
78 should return a reference to a HASH containing the keys described below.
79 For example
80 .PP
81 .Vb 6
82 \& # .libnetrc
83 \& {
84 \& nntp_hosts => [ "my_preferred_host" ],
85 \& ph_hosts => [ "my_ph_server" ],
86 \& }
87 \& _\|_END_\|_
88 .Ve
89 .SS "Class Methods"
90 .IX Subsection "Class Methods"
91 \&\f(CW\*(C`Net::Config\*(C'\fR defines the following methods. They are methods as they are
92 invoked as class methods. This is because \f(CW\*(C`Net::Config\*(C'\fR inherits from
93 \&\f(CW\*(C`Net::LocalCfg\*(C'\fR so you can override these methods if you want.
94 .ie n .IP requires_firewall($host) 4
95 .el .IP \f(CWrequires_firewall($host)\fR 4
96 .IX Item "requires_firewall($host)"
97 Attempts to determine if a given host is outside your firewall. Possible
98 return values are.
99 .Sp
100 .Vb 3
101 \& \-1 Cannot lookup hostname
102 \& 0 Host is inside firewall (or there is no ftp_firewall entry)
103 \& 1 Host is outside the firewall
104 .Ve
105 .Sp
106 This is done by using hostname lookup and the \f(CW\*(C`local_netmask\*(C'\fR entry in
107 the configuration data.
108 .SS "NetConfig Values"
109 .IX Subsection "NetConfig Values"
110 .IP nntp_hosts 4
111 .IX Item "nntp_hosts"
112 .PD 0
113 .IP snpp_hosts 4
114 .IX Item "snpp_hosts"
115 .IP pop3_hosts 4
116 .IX Item "pop3_hosts"
117 .IP smtp_hosts 4
118 .IX Item "smtp_hosts"
119 .IP ph_hosts 4
120 .IX Item "ph_hosts"
121 .IP daytime_hosts 4
122 .IX Item "daytime_hosts"
123 .IP time_hosts 4
124 .IX Item "time_hosts"
125 .PD
126 Each is a reference to an array of hostnames (in order of preference),
127 which should be used for the given protocol
128 .IP inet_domain 4
129 .IX Item "inet_domain"
130 Your internet domain name
131 .IP ftp_firewall 4
132 .IX Item "ftp_firewall"
133 If you have an FTP proxy firewall (\fBNOT\fR an HTTP or SOCKS firewall)
134 then this value should be set to the firewall hostname. If your firewall
135 does not listen to port 21, then this value should be set to
136 \&\f(CW"hostname:port"\fR (eg \f(CW"hostname:99"\fR)
137 .IP ftp_firewall_type 4
138 .IX Item "ftp_firewall_type"
139 There are many different ftp firewall products available. But unfortunately
140 there is no standard for how to traverse a firewall. The list below shows the
141 sequence of commands that Net::FTP will use
142 .Sp
143 .Vb 5
144 \& user Username for remote host
145 \& pass Password for remote host
146 \& fwuser Username for firewall
147 \& fwpass Password for firewall
148 \& remote.host The hostname of the remote ftp server
149 .Ve
150 .RS 4
151 .IP 0 4
152 There is no firewall
153 .IP 1 4
154 .IX Item "1"
155 .Vb 2
156 \& USER [email protected]
157 \& PASS pass
158 .Ve
159 .IP 2 4
160 .IX Item "2"
161 .Vb 4
162 \& USER fwuser
163 \& PASS fwpass
164 \& USER [email protected]
165 \& PASS pass
166 .Ve
167 .IP 3 4
168 .IX Item "3"
169 .Vb 5
170 \& USER fwuser
171 \& PASS fwpass
172 \& SITE remote.site
173 \& USER user
174 \& PASS pass
175 .Ve
176 .IP 4 4
177 .IX Item "4"
178 .Vb 5
179 \& USER fwuser
180 \& PASS fwpass
181 \& OPEN remote.site
182 \& USER user
183 \& PASS pass
184 .Ve
185 .IP 5 4
186 .IX Item "5"
187 .Vb 2
188 \& USER user@[email protected]
189 \& PASS pass@fwpass
190 .Ve
191 .IP 6 4
192 .IX Item "6"
193 .Vb 4
194 \& USER [email protected]
195 \& PASS fwpass
196 \& USER user
197 \& PASS pass
198 .Ve
199 .IP 7 4
200 .IX Item "7"
201 .Vb 4
202 \& USER [email protected]
203 \& PASS pass
204 \& AUTH fwuser
205 \& RESP fwpass
206 .Ve
207 .RE
208 .RS 4
209 .RE
210 .IP ftp_ext_passive 4
211 .IX Item "ftp_ext_passive"
212 .PD 0
213 .IP ftp_int_passive 4
214 .IX Item "ftp_int_passive"
215 .PD
216 FTP servers can work in passive or active mode. Active mode is when
217 you want to transfer data you have to tell the server the address and
218 port to connect to. Passive mode is when the server provide the
219 address and port and you establish the connection.
220 .Sp
221 With some firewalls active mode does not work as the server cannot
222 connect to your machine (because you are behind a firewall) and the firewall
223 does not re-write the command. In this case you should set \f(CW\*(C`ftp_ext_passive\*(C'\fR
224 to a \fItrue\fR value.
225 .Sp
226 Some servers are configured to only work in passive mode. If you have
227 one of these you can force \f(CW\*(C`Net::FTP\*(C'\fR to always transfer in passive
228 mode; when not going via a firewall, by setting \f(CW\*(C`ftp_int_passive\*(C'\fR to
229 a \fItrue\fR value.
230 .IP local_netmask 4
231 .IX Item "local_netmask"
232 A reference to a list of netmask strings in the form \f(CW"134.99.4.0/24"\fR.
233 These are used by the \f(CW\*(C`requires_firewall\*(C'\fR function to determine if a given
234 host is inside or outside your firewall.
235 .PP
236 The following entries are used during installation & testing on the
237 libnet package
238 .IP test_hosts 4
239 .IX Item "test_hosts"
240 If true then \f(CW\*(C`make test\*(C'\fR may attempt to connect to hosts given in the
241 configuration.
242 .IP test_exists 4
243 .IX Item "test_exists"
244 If true then \f(CW\*(C`Configure\*(C'\fR will check each hostname given that it exists
245 .SH EXPORTS
246 .IX Header "EXPORTS"
247 The following symbols are, or can be, exported by this module:
248 .IP "Default Exports" 4
249 .IX Item "Default Exports"
250 \&\f(CW%NetConfig\fR.
251 .IP "Optional Exports" 4
252 .IX Item "Optional Exports"
253 \&\fINone\fR.
254 .IP "Export Tags" 4
255 .IX Item "Export Tags"
256 \&\fINone\fR.
257 .SH "KNOWN BUGS"
258 .IX Header "KNOWN BUGS"
259 \&\fINone\fR.
260 .SH AUTHOR
261 .IX Header "AUTHOR"
262 Graham Barr <[email protected] <mailto:[email protected]>>.
263 .PP
264 Steve Hay <[email protected] <mailto:[email protected]>> is now maintaining
265 libnet as of version 1.22_02.
266 .SH COPYRIGHT
267 .IX Header "COPYRIGHT"
268 Copyright (C) 2000 Graham Barr. All rights reserved.
269 .PP
270 Copyright (C) 2013\-2014, 2016, 2020 Steve Hay. All rights reserved.
271 .SH LICENCE
272 .IX Header "LICENCE"
273 This module is free software; you can redistribute it and/or modify it under the
274 same terms as Perl itself, i.e. under the terms of either the GNU General Public
275 License or the Artistic License, as specified in the \fILICENCE\fR file.
276 .SH VERSION
277 .IX Header "VERSION"
278 Version 3.15
279 .SH DATE
280 .IX Header "DATE"
281 20 March 2023
282 .SH HISTORY
283 .IX Header "HISTORY"
284 See the \fIChanges\fR file.