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