Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Net::Config.3pm

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