]>
Commit | Line | Data |
---|---|---|
f2c46e40 AJ |
1 | <!doctype linuxdoc system> |
2 | <article> | |
3 | <title>Squid 3.5.0.0 release notes</title> | |
4 | <author>Squid Developers</author> | |
5 | ||
6 | <abstract> | |
7 | This document contains the release notes for version 3.5 of Squid. | |
8 | Squid is a WWW Cache application developed by the National Laboratory | |
9 | for Applied Network Research and members of the Web Caching community. | |
10 | </abstract> | |
11 | ||
12 | <toc> | |
13 | ||
14 | <sect>Notice | |
15 | <p> | |
16 | The Squid Team are pleased to announce the release of Squid-3.5.0.0 for testing. | |
17 | ||
18 | This new release is available for download from <url url="http://www.squid-cache.org/Versions/v3/3.5/"> or the | |
19 | <url url="http://www.squid-cache.org/Mirrors/http-mirrors.html" name="mirrors">. | |
20 | ||
21 | While this release is not deemed ready for production use, we believe it is ready for wider testing by the community. | |
22 | ||
23 | We welcome feedback and bug reports. If you find a bug, please see <url url="http://wiki.squid-cache.org/SquidFaq/BugReporting"> | |
24 | for how to submit a report with a stack trace. | |
25 | ||
26 | <sect1>Known issues | |
27 | <p> | |
28 | Although this release is deemed good enough for use in many setups, please note the existence of | |
29 | <url url="http://bugs.squid-cache.org/buglist.cgi?query_format=advanced&product=Squid&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&version=3.5" name="open bugs against Squid-3.5">. | |
30 | ||
31 | <sect1>Changes since earlier releases of Squid-3.5 | |
32 | <p> | |
33 | The 3.5 change history can be <url url="http://www.squid-cache.org/Versions/v3/3.5/changesets/" name="viewed here">. | |
34 | ||
35 | ||
36 | <sect>Major new features since Squid-3.4 | |
37 | <p>Squid 3.5 represents a new feature release above 3.4. | |
38 | ||
39 | <p>The most important of these new features are: | |
40 | <itemize> | |
41 | <item>Support libecap v1.0 | |
4e022adf | 42 | <item>Authentication helper query extensions |
27dad1a3 AJ |
43 | <item>Support named services |
44 | <item>Upgraded squidclient tool | |
45 | <item>Helper support for concurrency channels | |
00d0ce87 | 46 | <item>Support PROXY protocol |
f2c46e40 AJ |
47 | </itemize> |
48 | ||
49 | Most user-facing changes are reflected in squid.conf (see below). | |
50 | ||
51 | ||
52 | <sect1>Support libecap v1.0 | |
53 | <p>Details at <url url="http://wiki.squid-cache.org/Features/BLAH">. | |
54 | ||
55 | <p>The new libecap version allows Squid to better check the version of | |
56 | the eCAP adapter being loaded as well as the version of the eCAP library | |
57 | being used. | |
58 | ||
59 | <p>Squid-3.5 can support eCAP adapters built with libecap v1.0, | |
60 | but no longer supports adapters built with earlier libecap versions | |
61 | due to API changes. | |
62 | ||
63 | ||
4e022adf AJ |
64 | <sect1>Authentication helper query extensions |
65 | <p>Details at <url url="http://www.squid-cache.org/Doc/config/auth_param/">. | |
66 | ||
67 | <p>The new <em>key_extras</em> parameter allows sending of additional | |
68 | details to the authentication helper beyond the minimum required for | |
69 | the HTTP authentication. This is primarily intended to allow switching | |
70 | of authentication databases based on criteria such as client IP subnet, | |
71 | Squid receiving port, or in reverse-proxy the requested domain name. | |
72 | ||
73 | <p>In theory any <em>logformat</em> code may be used, however only the | |
74 | codes which have available details at the time of authentication | |
75 | will send any meaningful detail. | |
76 | ||
77 | ||
27dad1a3 AJ |
78 | <sect1>Support named services |
79 | <p>Details at <url url="http://wiki.squid-cache.org/MultipleInstances">. | |
80 | <p>Terminology details at <url url="http://wiki.squid-cache.org/Features/SmpScale#Terminology">. | |
81 | ||
82 | <p>The command line option <em>-n</em> assigns a name to the Squid service | |
83 | instance to be used as a unique identifier for all SMP processes run as | |
84 | part of that instance. This allows multiple instances of Squid service to | |
85 | be run on a single machine without background SMP systems such as shared | |
86 | memory and inter-process communication becoming confused or requiring | |
87 | additional configuration. | |
88 | ||
89 | <p>A service name is always used. When the <em>-n</em> option is missing | |
90 | from the command line the default service name is <em>squid</em>. | |
91 | ||
92 | <p>When multiple instances are being run the <em>-n</em> service name is | |
93 | required to target all other options such as <em>-z</em> or <em>-k</em> | |
94 | commands at the correct service. | |
95 | ||
96 | <p>The squid.conf macro ${service_name} is added to provide the service name | |
97 | of the process parsing the config. | |
98 | ||
99 | ||
100 | <sect1>Upgraded squidclient tool | |
101 | <p>The <em>squidclient</em> has begun the process of upgrading to support | |
102 | protocols other than HTTP. | |
103 | ||
104 | <sect2>Debug levels | |
105 | <p>The tool displays the server response message on STDOUT unless the <em>-q</em> | |
106 | command line option is used. Error messages will be output to STDERR. | |
107 | All other possible output is considered debug and output to STDERR using | |
108 | a range of debug verbosity levels (currently 1, 2 and 3). | |
109 | ||
110 | <p>When the <em>-v</em> command line option is used debugging is enabled. | |
111 | The level of debug display is raised for each repetition of the option. | |
112 | ||
113 | <sect2>PING | |
114 | <p>When <em>--ping</em> is given the tool will send its message repeatedly | |
115 | using whichever protocol that message has been formatted for. | |
116 | Optional parameters to limit the number of pings and their frequency are | |
117 | available. | |
118 | ||
119 | <p>Older tool versions also provide this feature but require the loop count | |
120 | parameter to be set to enable use of the feature. | |
121 | ||
122 | <sect2>HTTPS | |
123 | <p>When Squid is built with the GnuTLS encryption library the tool is able | |
124 | to open TLS (or SSL/3.0) connections to servers. | |
125 | ||
ae06fcd7 | 126 | <p>The <em>--https</em> option enables TLS using default values. |
27dad1a3 | 127 | |
ae06fcd7 | 128 | <p>The <em>--cert</em> option specifies a file containing X.509 client |
27dad1a3 AJ |
129 | certificate and private key in PEM format to be loaded for use. Multiple |
130 | certificates are supported and the option may be used multiple times to | |
131 | load certificates. | |
132 | The default is not to use a client certificate. | |
133 | ||
134 | <p>The <em>--params</em> option specifies a library specific set of parameters | |
135 | to be sent to the library for configuring the security context. | |
136 | See <url url="http://gnutls.org/manual/html_node/Priority-Strings.html"> for | |
137 | available GnuTLS parameters. | |
138 | ||
139 | <p>The <em>--trusted-ca</em> option specifies a file in PEM format containing | |
140 | one or more Certificate Authority (CA) certificates used to verify the | |
141 | remote server. This option may be used multiple times to load additional | |
142 | CA certificate lists. | |
143 | The default is not to use any CA, nor trust any server. | |
144 | ||
145 | <p>Anonymous TLS (using non-authenticated Diffi-Hellman or Elliptic Curve | |
146 | encryption) is available with the <em>--anonymous-tls</em> option. | |
147 | The default is to use X.509 certificate encryption instead. | |
148 | ||
149 | <p>When performing TLS/SSL server certificates are always verified, the | |
150 | results shown at debug level 3. The encrypted type is displayed at debug | |
151 | level 2 and the connection is used to send and receive the messages | |
152 | regardless of verification results. | |
153 | ||
154 | ||
155 | <sect1>Helper support for concurrency channels | |
156 | <p>Helper concurrency greatly reduces the communication lag between Squid | |
157 | and its helpers allowing faster transaction speeds even on sequential | |
158 | helpers. | |
159 | ||
f80c51ec AJ |
160 | <p>The Digest authentication, Store-ID, and URL-rewrite helpers packaged |
161 | with Squid have been updated to support concurrency channels. They will | |
162 | auto-detect the <em>channel-ID</em> field and will produce the appropriate | |
163 | response format. | |
164 | With these helpers concurrency may now be set to 0 or any higher number as desired. | |
27dad1a3 AJ |
165 | |
166 | ||
00d0ce87 AJ |
167 | <sect1>Support PROXY protocol |
168 | <p>More info at <url url="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt"> | |
169 | ||
170 | <p>PROXY protocol provides a simple way for proxies and tunnels of any kind to | |
171 | relay the original client source details without having to alter or understand | |
172 | the protocol being relayed on the connection. | |
173 | ||
8d757308 AJ |
174 | <p>Squid currently supports receiving version 1 or 2 of the protocol. |
175 | A port which has been configured to receive this protocol may only be used to | |
176 | receive traffic from client software sending in this protocol. | |
177 | Regular forward-proxy HTTP traffic is not accepted. | |
00d0ce87 AJ |
178 | |
179 | <p>Squid can be configured by adding an <em>http_port</em> or <em>https_port</em> | |
180 | with the <em>proxy-surrogate</em> mode flag. The <em>proxy_forwarded_access</em> | |
181 | must also be configured with <em>src</em> ACLs to whitelist proxies which are | |
182 | trusted to send correct client details. | |
183 | ||
184 | <p> | |
185 | <verbatim> | |
186 | http_port 3128 proxy-surrogate | |
187 | proxy_forwarded_access allow localhost | |
188 | </verbatim> | |
189 | ||
190 | ||
f2c46e40 AJ |
191 | <sect>Changes to squid.conf since Squid-3.4 |
192 | <p> | |
193 | There have been changes to Squid's configuration file since Squid-3.4. | |
194 | ||
195 | <p>Squid supports reading configuration option parameters from external | |
196 | files using the syntax <em>parameters("/path/filename")</em>. For example: | |
197 | <verb> | |
198 | acl whitelist dstdomain parameters("/etc/squid/whitelist.txt") | |
199 | </verb> | |
200 | ||
ae06fcd7 AJ |
201 | <p>The squid.conf macro ${service_name} is added to provide the service name |
202 | of the process parsing the config. | |
203 | ||
f2c46e40 AJ |
204 | <p>There have also been changes to individual directives in the config file. |
205 | ||
206 | This section gives a thorough account of those changes in three categories: | |
207 | ||
208 | <itemize> | |
209 | <item><ref id="newtags" name="New tags"> | |
210 | <item><ref id="modifiedtags" name="Changes to existing tags"> | |
211 | <item><ref id="removedtags" name="Removed tags"> | |
212 | </itemize> | |
213 | <p> | |
214 | ||
215 | <sect1>New tags<label id="newtags"> | |
216 | <p> | |
217 | <descrip> | |
0f5964c3 AJ |
218 | <tag>collapsed_forwarding</tag> |
219 | <p>Ported from Squid-2 with no configuration or visible behaviour changes. | |
220 | Collapsing of requests is performed across SMP workers. | |
221 | ||
00d0ce87 AJ |
222 | <tag>proxy_forwarded_access</tag> |
223 | <p>Renamed from <em>follow_x_forwarded_for</em> and extended to control more | |
224 | ways for locating the indirect (original) client IP details. | |
225 | ||
0f5964c3 AJ |
226 | <tag>send_hit</tag> |
227 | <p>New configuration directive to enable/disable sending cached content | |
228 | based on ACL selection. ACL can be based on client request or cached | |
229 | response details. | |
230 | ||
27dad1a3 AJ |
231 | <tag>sslproxy_session_cache_size</tag> |
232 | <p>New directive which sets the cache size to use for TLS/SSL sessions cache. | |
233 | ||
234 | <tag>sslproxy_session_ttl</tag> | |
235 | <p>New directive to specify the time in seconds the TLS/SSL session is valid. | |
236 | ||
237 | <tag>store_id_extras</tag> | |
238 | <p>New directive to send additional lookup parameters to the configured | |
239 | Store-ID helper program. It takes a string which may contain logformat %macros. | |
240 | <p>The Store-ID helper input format is now: | |
ae06fcd7 | 241 | <verb> |
27dad1a3 | 242 | [channel-ID] url [extras] |
ae06fcd7 AJ |
243 | </verb> |
244 | <p>The default value for extras is: "%>a/%>A %un %>rm myip=%la myport=%lp" | |
27dad1a3 | 245 | |
0f5964c3 AJ |
246 | <tag>store_miss</tag> |
247 | <p>New configuration directive to enable/disable caching of MISS responses. | |
248 | ACL can be based on any request or response details. | |
f2c46e40 | 249 | |
27dad1a3 AJ |
250 | <tag>url_rewrite_extras</tag> |
251 | <p>New directive to send additional lookup parameters to the configured | |
252 | URL-rewriter/redirector helper program. It takes a string which may | |
253 | contain logformat %macros. | |
254 | <p>The url rewrite and redirector helper input format is now: | |
ae06fcd7 | 255 | <verb> |
27dad1a3 | 256 | [channel-ID] url [extras] |
ae06fcd7 | 257 | </verb> |
27dad1a3 AJ |
258 | <p>The default value for extras is: "%>a/%>A %un %>rm myip=%la myport=%lp" |
259 | ||
f2c46e40 AJ |
260 | </descrip> |
261 | ||
262 | <sect1>Changes to existing tags<label id="modifiedtags"> | |
263 | <p> | |
264 | <descrip> | |
265 | <tag>acl</tag> | |
266 | <p>New type <em>adaptation_service</em> to match the name of any | |
267 | icap_service, ecap_service, adaptation_service_set, or | |
268 | adaptation_service_chain that Squid has used (or attempted to use) | |
269 | for the HTTP transaction so far. | |
270 | ||
271 | <tag>auth_param</tag> | |
272 | <p>New parameter <em>key_extras</em> to send additional parameters to | |
273 | the authentication helper. | |
274 | ||
27dad1a3 AJ |
275 | <tag>cache_dir</tag> |
276 | <p>New support for larger than 32KB objects in both <em>rock</em> type | |
277 | cache and shared memory cache. | |
278 | <p>New <em>slot-size=N</em> option for rock cache to specify the database | |
279 | slot/page size when small slot sizes are desired. The default and | |
280 | maximum slot size is 32KB. | |
281 | <p>Removal of old rock cache dir followed by <em>squid -z</em> is required | |
282 | when upgrading from earlier versions of Squid. | |
283 | ||
284 | <tag>cache_peer</tag> | |
285 | <p>New <em>standby=N</em> option to retain a set of N open and unused | |
286 | connections to the peer at virtually all times to reduce TCP handshake | |
287 | delays. | |
288 | <p>These connections differ from HTTP persistent connections in that they | |
289 | have not been used for HTTP messaging (and may never be). They may be | |
290 | turned into persistent connections after their first use subject to the | |
291 | same keep-alive critera any HTTP connection is checked for. | |
292 | ||
f2c46e40 | 293 | <tag>forward_max_tries</tag> |
ae06fcd7 | 294 | <p>Default value increased to <em>25 destinations</em> to allow better |
f2c46e40 AJ |
295 | contact and IPv4 failover with domains using long lists of IPv6 |
296 | addresses. | |
297 | ||
27dad1a3 AJ |
298 | <tag>ftp_epsv</tag> |
299 | <p>Converted into an Access List with allow/deny value driven by ACLs | |
300 | using Squid standard first line wins matching basis. | |
301 | <p>The old values of <em>on</em> and <em>off</em> imply <em>allow all</em> | |
302 | and <em>deny all</em> respectively and are now deprecated. | |
303 | Do not combine use of on/off values with ACL configuration. | |
304 | ||
f2c46e40 AJ |
305 | <tag>http_port</tag> |
306 | <p><em>protocol=</em> option altered to accept protocol version details. | |
307 | Currently supported values are: HTTP, HTTP/1.1, HTTPS, HTTPS/1.1 | |
308 | ||
ae06fcd7 AJ |
309 | <tag>https_port</tag> |
310 | <p><em>protocol=</em> option altered to accept protocol version details. | |
311 | Currently supported values are: HTTP, HTTP/1.1, HTTPS, HTTPS/1.1 | |
312 | ||
f2c46e40 AJ |
313 | <tag>logformat</tag> |
314 | <p>New format code <em>%credentials</em> to log the client credentials | |
315 | token. | |
316 | <p>New format code <em>%tS</em> to log transaction start time in | |
317 | "seconds.milliseconds" format, similar to the existing access.log | |
318 | "current time" field (%ts.%03tu) which logs the corresponding | |
319 | transaction finish time. | |
320 | ||
321 | </descrip> | |
322 | ||
323 | <sect1>Removed tags<label id="removedtags"> | |
324 | <p> | |
325 | <descrip> | |
326 | <tag>cache_dir</tag> | |
27dad1a3 | 327 | <p><em>COSS</em> storage type is formally replaced by Rock storage type. |
f2c46e40 AJ |
328 | |
329 | <tag>cache_dns_program</tag> | |
330 | <p>DNS external helper interface has been removed. It was no longer | |
331 | able to provide high performance service and the internal DNS | |
332 | client library with multicast DNS cover all modern use-cases. | |
333 | ||
27dad1a3 AJ |
334 | <tag>cache_peer</tag> |
335 | <p><em>idle=</em> replaced by <em>standby=</em>. | |
336 | <p>NOTE that standby connections are started earlier and available in | |
337 | more circumstances than squid-2 idle connections were. They are | |
338 | also spread over all IPs of the peer. | |
339 | ||
f2c46e40 AJ |
340 | <tag>dns_children</tag> |
341 | <p>DNS external helper interface has been removed. | |
342 | ||
00d0ce87 AJ |
343 | <tag>follow_x_forwarded_for</tag> |
344 | <p>Renamed <em>proxy_forwarded_access</em> and extended. | |
345 | ||
f2c46e40 AJ |
346 | </descrip> |
347 | ||
348 | ||
349 | <sect>Changes to ./configure options since Squid-3.4 | |
350 | <p> | |
351 | There have been some changes to Squid's build configuration since Squid-3.4. | |
352 | ||
353 | This section gives an account of those changes in three categories: | |
354 | ||
355 | <itemize> | |
356 | <item><ref id="newoptions" name="New options"> | |
357 | <item><ref id="modifiedoptions" name="Changes to existing options"> | |
358 | <item><ref id="removedoptions" name="Removed options"> | |
359 | </itemize> | |
360 | ||
361 | ||
362 | <sect1>New options<label id="newoptions"> | |
363 | <p> | |
364 | <descrip> | |
365 | <p><em>There are no new ./configure options in Squid-3.5.</em> | |
366 | ||
b2f0a375 AJ |
367 | <tag>BUILDCXX=</tag> |
368 | <p>Used when cross-compiling Squid. | |
369 | <p>The path and name of a compiler for building cf_gen and related | |
370 | tools used in the compile process. | |
371 | ||
372 | <tag>BUILDCXXFLAGS=</tag> | |
373 | <p>Used when cross-compiling Squid. | |
374 | <p>C++ compiler flags used for building cf_gen and related | |
375 | tools used in the compile process. | |
376 | ||
27dad1a3 AJ |
377 | <tag>--without-gnutls</tag> |
378 | <p>New option to explicitly disable use of GnuTLS encryption library. | |
379 | Use of this library is auto-enabled if v3.1.5 or later is available. | |
380 | <p>It is currently only used by the squidclient tool. | |
381 | ||
f2c46e40 AJ |
382 | </descrip> |
383 | ||
384 | <sect1>Changes to existing options<label id="modifiedoptions"> | |
385 | <p> | |
386 | <descrip> | |
4f07726a AJ |
387 | <tag>--enable-icap-client</tag> |
388 | <p>Deprecated. ICAP client is now auto-enabled. | |
389 | Use --disable-icap-client to disable if you need to. | |
f2c46e40 AJ |
390 | |
391 | </descrip> | |
392 | </p> | |
393 | ||
394 | <sect1>Removed options<label id="removedoptions"> | |
395 | <p> | |
396 | <descrip> | |
f2c46e40 AJ |
397 | <tag>--disable-internal-dns</tag> |
398 | <p>DNS external helper interface has been removed. It was no longer | |
399 | able to provide high performance service and the internal DNS | |
400 | client library with multicast DNS cover all modern use-cases. | |
401 | ||
c41db002 AJ |
402 | <tag>--enable-ssl</tag> |
403 | <p>Removed. Use <em>--with-openssl</em> to enable OpenSSL library support. | |
404 | ||
ae06fcd7 AJ |
405 | <tag>--with-coss-membuf-size</tag> |
406 | <p>The COSS cache type has been removed. | |
407 | It has been replaced by <em>rock</em> cache type. | |
408 | ||
f2c46e40 AJ |
409 | </descrip> |
410 | ||
411 | ||
412 | <sect>Regressions since Squid-2.7 | |
413 | ||
414 | <p>Some squid.conf options which were available in Squid-2.7 are not yet available in Squid-3.5 | |
415 | ||
416 | <p>If you need something to do then porting one of these from Squid-2 to Squid-3 is most welcome. | |
417 | ||
418 | <sect1>Missing squid.conf options available in Squid-2.7 | |
419 | <p> | |
420 | <descrip> | |
421 | <tag>broken_vary_encoding</tag> | |
422 | <p>Not yet ported from 2.6 | |
423 | ||
424 | <tag>cache_peer</tag> | |
f2c46e40 AJ |
425 | <p><em>monitorinterval=</em> not yet ported from 2.6 |
426 | <p><em>monitorsize=</em> not yet ported from 2.6 | |
427 | <p><em>monitortimeout=</em> not yet ported from 2.6 | |
428 | <p><em>monitorurl=</em> not yet ported from 2.6 | |
429 | ||
430 | <tag>cache_vary</tag> | |
431 | <p>Not yet ported from 2.6 | |
432 | ||
f2c46e40 AJ |
433 | <tag>error_map</tag> |
434 | <p>Not yet ported from 2.6 | |
435 | ||
436 | <tag>external_refresh_check</tag> | |
437 | <p>Not yet ported from 2.7 | |
438 | ||
439 | <tag>location_rewrite_access</tag> | |
440 | <p>Not yet ported from 2.6 | |
441 | ||
442 | <tag>location_rewrite_children</tag> | |
443 | <p>Not yet ported from 2.6 | |
444 | ||
445 | <tag>location_rewrite_concurrency</tag> | |
446 | <p>Not yet ported from 2.6 | |
447 | ||
448 | <tag>location_rewrite_program</tag> | |
449 | <p>Not yet ported from 2.6 | |
450 | ||
451 | <tag>refresh_pattern</tag> | |
452 | <p><em>stale-while-revalidate=</em> not yet ported from 2.7 | |
453 | <p><em>ignore-stale-while-revalidate=</em> not yet ported from 2.7 | |
454 | <p><em>negative-ttl=</em> not yet ported from 2.7 | |
455 | ||
456 | <tag>refresh_stale_hit</tag> | |
457 | <p>Not yet ported from 2.7 | |
458 | ||
459 | <tag>update_headers</tag> | |
460 | <p>Not yet ported from 2.7 | |
461 | ||
462 | </descrip> | |
463 | ||
464 | </article> |