Name: SG

Text: Volume 11: Content Policy Language Guide

Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
[email protected]
http://www.bluecoat.com
For concerns or feedback about the documentation: [email protected]
Copyright© 1999-2007 Blue Coat Systems, Inc. All rights reserved worldwide. No part of this document may be reproduced by any means
nor modified, decompiled, disassembled, published or distributed, in whole or in part, or translated to any electronic medium or other
means without the written consent of Blue Coat Systems, Inc. All right, title and interest in and to the Software and documentation are
and shall remain the exclusive property of Blue Coat Systems, Inc. and its licensors. ProxyAV™, CacheOS™, SGOS™, SG™, Spyware
Interceptor™, Scope™, RA Connector™, RA Manager™, Remote Access™ are trademarks of Blue Coat Systems, Inc. and CacheFlow®,
Blue Coat®, Accelerating The Internet®, ProxySG®, WinProxy®, AccessNow®, Ositis®, Powering Internet Management®, The Ultimate
Internet Sharing Solution®, Permeo®, Permeo Technologies, Inc.®, and the Permeo logo are registered trademarks of Blue Coat Systems,
Inc. All other trademarks contained in this document and in the Software are the property of their respective owners.
BLUE COAT SYSTEMS, INC. DISCLAIMS ALL WARRANTIES, CONDITIONS OR OTHER TERMS, EXPRESS OR IMPLIED,
STATUTORY OR OTHERWISE, ON SOFTWARE AND DOCUMENTATION FURNISHED HEREUNDER INCLUDING WITHOUT
LIMITATION THE WARRANTIES OF DESIGN, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL BLUE COAT SYSTEMS, INC., ITS SUPPLIERS OR ITS LICENSORS BE LIABLE FOR
ANY DAMAGES, WHETHER ARISING IN TORT, CONTRACT OR ANY OTHER LEGAL THEORY EVEN IF BLUE COAT SYSTEMS,
INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Document Number: 231-02847
Document Revision: SGOS 5.1.x—03/2007

ii

Contents
Contact Information
Preface: Introducing the Content Policy Language
About the Document Organization .............................................................................................................. xiii
Supported Browsers........................................................................................................................................ xiv
Related Blue Coat Documentation................................................................................................................ xiv
Document Conventions.................................................................................................................................. xiv
Chapter 1: Overview of Content Policy Language
Concepts .............................................................................................................................................................17
Transactions...............................................................................................................................................17
Policy Model..............................................................................................................................................18
Role of CPL ................................................................................................................................................19
CPL Language Basics........................................................................................................................................19
Comments ..................................................................................................................................................19
Rules ...........................................................................................................................................................19
Notes...........................................................................................................................................................20
Quoting ......................................................................................................................................................21
Layers .........................................................................................................................................................22
Sections.......................................................................................................................................................23
Definitions..................................................................................................................................................24
Referential Integrity..................................................................................................................................25
Substitutions ..............................................................................................................................................25
Writing Policy Using CPL ................................................................................................................................25
Authentication and Denial ......................................................................................................................26
Installing Policy.........................................................................................................................................27
CPL General Use Characters and Formatting ......................................................................................27
Troubleshooting Policy.....................................................................................................................................28
Upgrade/Downgrade Issues ...........................................................................................................................29
CPL Syntax Deprecations ........................................................................................................................29
Conditional Compilation.........................................................................................................................29
Chapter 2: Managing Content Policy Language
Understanding Transactions and Timing......................................................................................................31
Transactions ............................................................................................................................31
Transactions ..............................................................................................................................32
Transactions.....................................................................................................................34
Transactions ..............................................................................................................................34
Transaction .........................................................................................................................34
Transactions....................................................................................................................35

iii

Volume 11: Content Policy Language Guide

Transactions .................................................................................................................................. 35
Timing ........................................................................................................................................................ 35
Understanding Layers...................................................................................................................................... 36
Layers....................................................................................................................................... 37
Layers ........................................................................................................................................ 38
Layers.................................................................................................................................. 39
Layers .................................................................................................................................... 40
Layers......................................................................................................................................... 40
Layers ............................................................................................................................... 41
Layers ........................................................................................................................... 41
Layers............................................................................................................................................. 42
Layer Guards............................................................................................................................................. 42
Timing ........................................................................................................................................................ 43
Understanding Sections ................................................................................................................................... 43
[Rule] .......................................................................................................................................................... 44
[url] ............................................................................................................................................................. 45
[url.domain] .............................................................................................................................................. 45
[url.regex] .................................................................................................................................................. 45
[server_url.domain].................................................................................................................................. 45
Section Guards .......................................................................................................................................... 46
Defining Policies................................................................................................................................................ 46
Blacklists and Whitelists.......................................................................................................................... 47
General Rules and Exceptions to a General Rule ................................................................................ 47
Best Practices...................................................................................................................................................... 50
Chapter 3: Condition Reference
Condition Syntax............................................................................................................................................... 53
Pattern Types ..................................................................................................................................................... 54
Unavailable Conditions.................................................................................................................................... 55
Layer Type Restrictions ........................................................................................................................... 55
Global Restrictions ................................................................................................................................... 55
Condition Reference ......................................................................................................................................... 55
admin.access=................................................................................................................................................... 56
attribute.name= ................................................................................................................................................ 57
authenticated= .................................................................................................................................................. 59
bitrate=............................................................................................................................................................... 60
category= ........................................................................................................................................................... 62
client.address=.................................................................................................................................................. 63
client.connection.dscp= ................................................................................................................................... 64
client.connection.negotiated_cipher= ........................................................................................................... 65
client.connection.negotiated_cipher.strength=............................................................................................ 66
client.connection.negotiated_ssl_version=................................................................................................... 67
client.host= ........................................................................................................................................................ 68
client.host.has_name= ..................................................................................................................................... 69
client.protocol=................................................................................................................................................. 70

iv

Contents

condition= ......................................................................................................................................................... 71
console_access= ................................................................................................................................................ 73
content_admin=................................................................................................................................................ 74
content_management ...................................................................................................................................... 75
date[.utc]= ......................................................................................................................................................... 76
day= ................................................................................................................................................................... 77
dns.client_transport=....................................................................................................................................... 78
dns.request.address=....................................................................................................................................... 79
dns.request.category= ..................................................................................................................................... 80
dns.request.class= ............................................................................................................................................ 81
dns.request.name=........................................................................................................................................... 82
dns.request.opcode=........................................................................................................................................ 83
dns.request.type=............................................................................................................................................. 84
dns.response.a= ................................................................................................................................................ 85
dns.response.cname= ...................................................................................................................................... 86
dns.response.code=.......................................................................................................................................... 87
dns.response.nodata=...................................................................................................................................... 88
dns.response.ptr=............................................................................................................................................. 89
exception.id= .................................................................................................................................................... 90
ftp.method= ...................................................................................................................................................... 92
group= ............................................................................................................................................................... 93
has_attribute.name= ........................................................................................................................................ 95
has_client= ........................................................................................................................................................ 96
hour=.................................................................................................................................................................. 97
http.connect= .................................................................................................................................................... 99
http.method= .................................................................................................................................................. 100
http.method.custom= .................................................................................................................................... 101
http.method.regex= ....................................................................................................................................... 102
http.request_line.regex= ............................................................................................................................... 103
http.request.version=..................................................................................................................................... 104
http.response.apparent_data_type=............................................................................................................ 105
http.response.code=....................................................................................................................................... 106
http.response.data= ....................................................................................................................................... 107
http.response.version= .................................................................................................................................. 108
http.transparent_authentication=................................................................................................................ 109
http.x_method= .............................................................................................................................................. 110
icap_error_code=............................................................................................................................................ 111
im.buddy_id= ................................................................................................................................................. 112
im.chat_room.conference=............................................................................................................................ 113
im.chat_room.id= ........................................................................................................................................... 114
im.chat_room.invite_only=........................................................................................................................... 115
im.chat_room.type=....................................................................................................................................... 116
im.chat_room.member=................................................................................................................................ 117
im.chat_room.voice_enabled= ..................................................................................................................... 118
im.client=......................................................................................................................................................... 119
im.file.extension= ........................................................................................................................................... 120
im.file.name= .................................................................................................................................................. 121
im.file.path=.................................................................................................................................................... 122
im.file.size= ..................................................................................................................................................... 123

v

Volume 11: Content Policy Language Guide

im.message.opcode=......................................................................................................................................
im.message.reflected= ...................................................................................................................................
im.message.route= .........................................................................................................................................
im.message.size=............................................................................................................................................
im.message.text= ............................................................................................................................................
im.message.type=...........................................................................................................................................
im.method=.....................................................................................................................................................
im.user_agent= ...............................................................................................................................................
im.user_id= .....................................................................................................................................................
live=..................................................................................................................................................................
minute= ...........................................................................................................................................................
month= ............................................................................................................................................................
proxy.address= ...............................................................................................................................................
proxy.card= .....................................................................................................................................................
proxy.port= .....................................................................................................................................................
p2p.client=.......................................................................................................................................................
raw_url.regex= ...............................................................................................................................................
raw_url.host.regex=.......................................................................................................................................
raw_url.path.regex= ......................................................................................................................................
raw_url.pathquery.regex= ............................................................................................................................
raw_url.port.regex= .......................................................................................................................................
raw_url.query.regex= ....................................................................................................................................
realm= ..............................................................................................................................................................
release.id= .......................................................................................................................................................
release.version=..............................................................................................................................................
request.header.header_name= .....................................................................................................................
request.header.header_name.address= ......................................................................................................
request.header.header_name.count=.............................................................................................................
request.header.header_name.length=............................................................................................................
request.header.Referer.url=..........................................................................................................................
request.header.Referer.url.category=..........................................................................................................
request.raw_headers.count= ........................................................................................................................
request.raw_headers.length= .......................................................................................................................
request.raw_headers.regex=.........................................................................................................................
request.x_header.header_name=.................................................................................................................
request.x_header.header_name.address= ..................................................................................................
request.x_header.header_name.count=.........................................................................................................
request.x_header.header_name.length= .......................................................................................................
response.header.header_name= ..................................................................................................................
response.raw_headers.count=......................................................................................................................
response.raw_headers.length= ....................................................................................................................
response.raw_headers.regex= ......................................................................................................................
response.x_header.header_name= ..............................................................................................................
server.certificate.hostname.category= ........................................................................................................
server.connection.dscp=................................................................................................................................
server_url= ......................................................................................................................................................
socks=...............................................................................................................................................................
socks.accelerated= .........................................................................................................................................
socks.method=................................................................................................................................................

vi

124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
148
149
150
151
152
153
154
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
175
176
177

Contents

socks.version= ................................................................................................................................................
ssl.proxy_mode= ............................................................................................................................................
streaming.client=............................................................................................................................................
streaming.content= ........................................................................................................................................
time= ................................................................................................................................................................
tunneled= ........................................................................................................................................................
url= ...................................................................................................................................................................
url.category=...................................................................................................................................................
user=.................................................................................................................................................................
user.domain= ..................................................................................................................................................
user.x509.issuer= ............................................................................................................................................
user.x509.serialNumber= ..............................................................................................................................
user.x509.subject= ..........................................................................................................................................
virus_detected= ..............................................................................................................................................
weekday= ........................................................................................................................................................
year= ................................................................................................................................................................

178
179
180
181
182
184
185
192
193
195
196
197
198
199
200
201

Chapter 4: Property Reference
Property Reference.......................................................................................................................................... 203
access_log( ) .................................................................................................................................................... 204
access_server( ) ............................................................................................................................................... 205
action( ) ........................................................................................................................................................... 206
adn.server( ) .................................................................................................................................................... 207
adn.server.optimize( ).................................................................................................................................... 208
adn.server.optimize.inbound( ) ................................................................................................................... 209
adn.server.optimize.outbound( ) ................................................................................................................. 210
advertisement( ) ............................................................................................................................................. 211
allow................................................................................................................................................................. 212
always_verify( ) ............................................................................................................................................. 213
authenticate() .................................................................................................................................................. 214
authenticate.charset( ).................................................................................................................................... 215
authenticate.force( ) ...................................................................................................................................... 216
authenticate.form( )........................................................................................................................................ 217
authenticate.mode( ) ...................................................................................................................................... 218
authenticate.new_pin_form() ....................................................................................................................... 220
authenticate.query_form() ............................................................................................................................ 221
authenticate.redirect_stored_requests()...................................................................................................... 222
authenticate.use_url_cookie( )...................................................................................................................... 223
bypass_cache( ) .............................................................................................................................................. 224
cache( ) ............................................................................................................................................................ 225
category.dynamic.mode( ) ............................................................................................................................ 227
check_authorization( ) ................................................................................................................................... 228
client.certificate.require( ) ............................................................................................................................. 229
client.certificate.validate( )............................................................................................................................ 230
client.certificate.validate.check_revocation() ............................................................................................. 231
client.connection.dscp()................................................................................................................................. 232
cookie_sensitive( ) ......................................................................................................................................... 233
delete_on_abandonment( ) ........................................................................................................................... 234
deny( ) .............................................................................................................................................................. 235

vii

Volume 11: Content Policy Language Guide

deny.unauthorized( ) .....................................................................................................................................
detect_protocol( ) ...........................................................................................................................................
direct( ) ............................................................................................................................................................
dns.respond( ) .................................................................................................................................................
dns.respond.a( ) ..............................................................................................................................................
dns.respond.ptr( )...........................................................................................................................................
dynamic_bypass( ) .........................................................................................................................................
exception( )......................................................................................................................................................
exception.autopad( ) ......................................................................................................................................
force_cache( ) .................................................................................................................................................
force_deny( ) ...................................................................................................................................................
force_exception( ) ...........................................................................................................................................
force_patience_page( )...................................................................................................................................
force_protocol( ) .............................................................................................................................................
forward( ) ........................................................................................................................................................
forward.fail_open( ) .......................................................................................................................................
ftp.match_client_data_ip( ) ...........................................................................................................................
ftp.match_server_data_ip( )..........................................................................................................................
ftp.server_connection( ).................................................................................................................................
ftp.server_data( ) ............................................................................................................................................
ftp.transport( ) ................................................................................................................................................
ftp.welcome_banner( )...................................................................................................................................
http.allow_compression( ) ............................................................................................................................
http.allow_decompression( ) ........................................................................................................................
http.client.allow_encoding( )........................................................................................................................
http.client.persistence( ) ................................................................................................................................
http.client.recv.timeout( )..............................................................................................................................
http.compression_level( )..............................................................................................................................
http.force_ntlm_for_server_auth( ) .............................................................................................................
http.refresh.recv.timeout( ) ...........................................................................................................................
http.request.version( ) ...................................................................................................................................
http.response.parse_meta_tag.Cache-Control( ) .......................................................................................
http.response.parse_meta_tag.Expires( )....................................................................................................
http.response.parse_meta_tag.pragma-no-cache( ) ..................................................................................
http.response.version( ) ................................................................................................................................
http.server.accept_encoding( ) .....................................................................................................................
http.server.accept_encoding.allow_unknown() ........................................................................................
http.server.connect_attempts( )....................................................................................................................
http.server.persistence( ) ...............................................................................................................................
http.server.recv.timeout( ) ............................................................................................................................
icp( )..................................................................................................................................................................
im.block_encryption( ) ..................................................................................................................................
im.reflect( ) ......................................................................................................................................................
im.strip_attachments( ) .................................................................................................................................
im.transport( ).................................................................................................................................................
integrate_new_hosts( ) ..................................................................................................................................
limit_bandwidth( ) .........................................................................................................................................
log.rewrite.field-id( )......................................................................................................................................
log.suppress.field-id( ) ..................................................................................................................................

viii

236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285

Contents

max_bitrate( )..................................................................................................................................................
never_refresh_before_expiry( ) ....................................................................................................................
never_serve_after_expiry( ) ..........................................................................................................................
patience_page( )..............................................................................................................................................
pipeline( ) .......................................................................................................................................................
reflect_ip( ) .....................................................................................................................................................
refresh( ) ..........................................................................................................................................................
remove_IMS_from_GET( )............................................................................................................................
remove_PNC_from_GET( ) ..........................................................................................................................
remove_reload_from_IE_GET( )..................................................................................................................
request.filter_service( ) ..................................................................................................................................
request.icap_service( ) ..................................................................................................................................
response.icap_service( ) ................................................................................................................................
response.raw_headers.max_count()............................................................................................................
response.raw_headers.max_length()...........................................................................................................
response.raw_headers.tolerate() ..................................................................................................................
server.certificate.validate() ...........................................................................................................................
server.certificate.validate.check_revocation()............................................................................................
server.certificate.validate.ignore() ...............................................................................................................
server.connection.dscp() ...............................................................................................................................
shell.prompt( ) ................................................................................................................................................
shell.realm_banner( ) .....................................................................................................................................
shell.welcome_banner( ) ...............................................................................................................................
socks.accelerate( ) ...........................................................................................................................................
socks.allow_compression( ) ..........................................................................................................................
socks.authenticate( ).......................................................................................................................................
socks.authenticate.force( ).............................................................................................................................
socks_gateway( ) ............................................................................................................................................
socks_gateway.fail_open( )...........................................................................................................................
socks_gateway.request_compression( )......................................................................................................
ssl.forward_proxy( ) ......................................................................................................................................
ssl.forward_proxy.hostname( ) ....................................................................................................................
ssl.forward_proxy.issuer_keyring( ) ...........................................................................................................
ssl.forward_proxy.server_keyring( )...........................................................................................................
ssl.forward_proxy.splash_text( )..................................................................................................................
ssl.forward_proxy.splash_url( ) ...................................................................................................................
streaming.transport( )....................................................................................................................................
terminate_connection( ).................................................................................................................................
trace.destination( ) .........................................................................................................................................
trace.request( ) ...............................................................................................................................................
trace.rules( ) ....................................................................................................................................................
ttl( ) ...................................................................................................................................................................
ua_sensitive( ) ................................................................................................................................................

286
287
288
289
290
291
292
293
294
295
296
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329

Chapter 5: Action Reference
Argument Syntax ............................................................................................................................................ 331
Action Reference ............................................................................................................................................. 331
append( ) ........................................................................................................................................................ 332
delete( ) ........................................................................................................................................................... 333

ix

Volume 11: Content Policy Language Guide

delete_matching( ) .........................................................................................................................................
im.alert( ) .........................................................................................................................................................
log_message( ) ...............................................................................................................................................
notify_email( ) ................................................................................................................................................
notify_snmp( ) ...............................................................................................................................................
redirect( ) ........................................................................................................................................................
rewrite( ) ..........................................................................................................................................................
set( ) ..................................................................................................................................................................
transform .........................................................................................................................................................

334
335
336
337
338
339
341
344
346

Chapter 6: Definition Reference
Definition Names ............................................................................................................................................ 349
define action.................................................................................................................................................... 350
define active_content ..................................................................................................................................... 352
define category ............................................................................................................................................... 354
define condition.............................................................................................................................................. 356
define javascript ............................................................................................................................................. 358
define policy.................................................................................................................................................... 360
define server_url.domain condition............................................................................................................ 361
define string .................................................................................................................................................... 363
define subnet................................................................................................................................................... 364
define url condition ....................................................................................................................................... 365
define url.domain condition ......................................................................................................................... 367
define url_rewrite........................................................................................................................................... 369
restrict dns....................................................................................................................................................... 371
restrict rdns ..................................................................................................................................................... 372
transform active_content .............................................................................................................................. 373
transform url_rewrite .................................................................................................................................... 374
Appendix A: Glossary
Appendix B: Testing and Troubleshooting
Enabling Rule Tracing ........................................................................................................................... 379
Enabling Request Tracing ..................................................................................................................... 380
Using Trace Information to Improve Policies .................................................................................... 381
Appendix C: Recognized HTTP Headers
Appendix D: CPL Substitutions
Available Substitutions .................................................................................................................................. 389
Access Log Fields ............................................................................................................................................ 390
Timestamp Modifiers............................................................................................................................. 420
String Modifiers ...................................................................................................................................... 422
Host Modifiers ........................................................................................................................................ 422

x

Contents

Appendix E: Using Regular Expressions
Regular Expression Syntax ............................................................................................................................ 424
Regular Expression Details............................................................................................................................ 425
Backslash.................................................................................................................................................. 426
Circumflex and Dollar ........................................................................................................................... 427
Period (Dot) ............................................................................................................................................ 428
Square Brackets....................................................................................................................................... 428
Vertical Bar .............................................................................................................................................. 429
Lowercase-Sensitivity ............................................................................................................................ 429
Subpatterns.............................................................................................................................................. 430
Repetition................................................................................................................................................. 431
Back References ...................................................................................................................................... 433
Assertions ................................................................................................................................................ 433
Once-Only Subpatterns ......................................................................................................................... 435
Conditional Subpatterns........................................................................................................................ 435
Comments................................................................................................................................................ 436
Performance ............................................................................................................................................ 436
Regular Expression Engine Differences From Perl .................................................................................... 436

xi

Volume 11: Content Policy Language Guide

xii

Preface:

Introducing the Content Policy Language

The Blue Coat® Content Policy Language (CPL) is a powerful, flexible language that enables you to
specify a variety of authentication, Web-access, and networking policies. ProxySG policy is written in
CPL, and every Web request is evaluated based on the installed policy. The language is designed so
that policies can be customized to an organization’s specific set of users and unique enforcement
needs.
CPL uses the settings created when you configured the ProxySG to your specifications.
CPL has the following capabilities:


Fine-grained control over various aspects of ProxySG behavior.



Layered policy, allowing for multiple policy decisions for each request.



Multiple actions triggered by a particular condition.



Flexibility of user-defined conditions and actions.



Convenience of predefined common actions and transformations.



Authentication-aware policy, including user and group configuration.



Support for multiple authentication realms.



Configurable policy event logging.



Built-in debugging.

About the Document Organization
This document is organized for easy reference, and is divided into the following sections and chapters:
Table 1: Manual Organization
Chapter 1 – Overview of Content Policy

Language

This chapter provides an overview of CPL, including concepts, CPL
basics, writing and troubleshooting policy and
upgrade/downgrade issues.

Chapter 2 – Managing CPL

Building upon Chapter 1, this chapter discusses understanding
transactions, timing, layers, and sections, defining policies, and best
practices.

Chapter 3 – Conditions

This reference guide contains the list of conditions that are
supported by CPL and provides an explanation for the usage.

Chapter 4 – Properties

This reference guide contains the list of properties that are
supported by CPL and provides an explanation for the usage.

Chapter 5 – Actions

This reference guide contains the list of actions that are supported
by CPL and provides an explanation for the usage.

Chapter 6 – Definitions

This reference guide contains the list of definitions that are
supported by CPL and provides an explanation for the usage.

xiii

Volume 11: Content Policy Language Guide

Table 1: Manual Organization (Continued)
Appendix A – Glossary

Terms used in this manual are defined in this appendix.

Appendix B – Troubleshooting

Using policy trace properties is explained in this appendix.

Appendix C – Recognized HTTP

Headers

This appendix lists all recognized HTTP 1.1 headers and indicates
how the ProxySG interacts with them.

Appendix D – CPL Substitutions

This appendix lists all substitution variables available in CPL.

Appendix E—Using Regular

This appendix discusses regular expressions and how to use them.

Expressions

Supported Browsers
The SG appliance Management Console supports Microsoft® Internet Explorer Internet Explorer 7.0,
Internet Explorer 6.0 (SP1 or later), Firefox 1.0, Netscape 7.2. Later versions might work, but they have
not been tested.
The Management Console uses the Java Runtime Environment. JRE 1.5.0 and 1.4.1_07 are both
supported.

Related Blue Coat Documentation
Blue Coat 200 Series Installation Guide
Blue Coat 400 Series Installation Guide
Blue Coat 5100 Series Installation Guide
Blue Coat 800 Series Installation Guide
Blue Coat 810 Series Installation Guide
Blue Coat 8000 Series Installation Guide
Blue Coat 8100 Series Installation Guide
Volume 12: Blue Coat SG Appliance Command Line Interface Reference

Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax conventions
used in this manual.
Table 2: Typographic Conventions
Conventions

xiv

Definition

Italics

The first use of a new or Blue Coat-proprietary term.

Courier font

Command line text that appears on your administrator workstation.

Chapter :

Table 2: Typographic Conventions (Continued)
Conventions

Definition

Courier Italics

A command line variable that is to be substituted with a literal name or value
pertaining to the appropriate facet of your network system.

Courier Boldface

A ProxySG literal to be entered as shown.

{ }

One of the parameters enclosed within the braces must be supplied

[ ]

An optional parameter or parameters.

|

Either the parameter before or after the pipe character can or must be selected, but
not both. To more clearly indicate that only one can be chosen, no spaces are put
between the pipe and the options.

xv

Volume 11: Content Policy Language Guide

xvi

Chapter 1: Overview of Content Policy Language

The Blue Coat® Content Policy Language (CPL) is a programming language with its own concepts and
rules that you must follow.
This chapter provides an overview of CPL, including the following topics:


"Concepts" on page 17



"CPL Language Basics" on page 19



"Writing Policy Using CPL" on page 25



"Troubleshooting Policy" on page 28



"Upgrade/Downgrade Issues" on page 29

Concepts
The term policy, as used here, refers to configuration values and rules applied to render decisions on
authentication requirements, access rights, quality of service, or content transformations (including
rewrites and off-box services that should be used to process the request or response). Often, the policy
references system configuration for the default values for some settings and then evaluates rules to see
if those settings should be overridden.
CPL is a language for specifying the policy rules for the ProxySG. Primarily, it controls the following:


User Authentication requirements



Access to Web-related resources



Cache content



Various aspects of request and response processing



Access logging

You can create policy rules using either the Visual Policy Manager (VPM), which is accessible through
the Management Console, or by composing CPL.
Before reading sample CPL or trying to express your own policies in CPL, Blue Coat recommends that
you understand the fundamental concepts underlying policy enforcement in the ProxySG appliances.
This section provides an overview of important concepts.

Transactions
In the CPL context, a transaction is the encapsulation of a request for service and any associated
response for the purposes of policy evaluation and enforcement. In most cases, a transaction is created
for each unique request for service, and the transaction exists for the time taken to process the request
and deliver the response.

17

Volume 11: Content Policy Language Guide

The transaction serves the following purposes:


Exposes request and response state for testing during policy evaluation.
This provides the ability to test various aspects of a request, such as the IP address of the client
and the URL used, or the response, such as the contents of any HTTP headers.



Ensures policy integrity during processing.
The lifetime of a transaction may be relatively long, especially if a large object is being fetched
over slow networks and subjected to off-box processing services such as content filtering and
virus scanning. During this time, changes to configuration or policy rules may occur, which
would result in altering the policy decisions that affect a transaction. If a request was evaluated
against one version of policy, and some time later the associated response were evaluated against
a different version of policy, the outcome would be unpredictable and possibly inconsistent.
The transaction ensures that both the request and the response are evaluated against the version
of policy that was current when the transaction was created. To ensure that new policy is
respected, long lived transactions such as those involved in streaming, or large file downloads, are
re-evaluated under new policy. Re-evaluation applies to both the request and response, and any
resulting new decisions that cannot be honoured (such as new authentication requirements) result
in transaction termination.



Maintains policy decisions relevant to request and response processing.



Various types of transactions are used to support the different policy evaluation requirements of
the individual protocols: administrator, cache, and proxy transactions.



In a few special cases, two or more transactions can be created for a single request. For example, if
an HTTP request is made via the SOCKS proxy (on port 1080 of the ProxySG), then it is possible
for two transactions to be created: a SOCKS proxy transaction, and an HTTP proxy transaction.
You can see these transactions for yourself if you turn on policy tracing. A new entry is added to
the policy trace file for each transaction.

Policy Model
Each transaction begins with a default set of decisions, many of which are taken from configuration of
the system. These defaults include such things as forwarding hosts or SOCKS gateways. The most
important default decision affects whether or not requests should be allowed or denied. The defaults
for the various transaction types are:


Administrator Transaction— the default is to deny requests.
By default, administration is only available through one of the methods that bypasses policy
evaluation. These are:


accessing the CLI through the serial console



accessing the CLI through RSA authenticated SSH



logging into the Management Console or CLI using the console credentials

Specific rights must be granted through policy to enable other administration methods.


18

Cache Transactions—the default is to allow requests.

Chapter 1: Overview of Content Policy Language

These requests originate from the ProxySG itself, and are used primarily to maintain the state of
content. Additional policy can be added to specifically deny requests for specific content, and to
distinguish content management requests from other cache transactions.


Proxy Transactions—the default is taken from system configuration.
For new ProxySG appliances, the default is to deny all requests. For ProxySG appliances being
upgraded from 4.x, the default is to allow all requests. In either case, the ProxySG can be
configured for either default. The default setting is displayed in policy listings.

The proper approach to writing layer policy depends on whether or not the default is to
allow or deny requests. The default proxy policy is configurable and represents the starting point for
writing policy to control proxy transactions. The default proxy policy is reported at the top of every
policy listing generated by the ProxySG.
; Default proxy policy is DENY

That line in a policy listing is a CPL comment, defining the starting point for proxy policy.

Role of CPL
CPL is the language used to express policy that depends on the runtime evaluation of each
transaction. Policy is written in CPL, installed on the ProxySG, and is evaluated during request
processing to override any default decisions taken from configuration.

CPL Language Basics
The following sections provide an overview of the CPL language. In order to concentrate on higher
level themes, CPL elements are informally introduced and discussed. Detailed specifications for each
of these elements is left to the reference portion of this manual.

Comments
Any line starting with ‘;’ is a comment.
A semicolon (;) following a space or tab introduces a comment that extends to the end of the line
(except where the semicolon appears inside quotes as part of a trigger pattern expression or property
setting).
For example:
; This is a comment.

Comments can appear anywhere in policy.

Rules
A policy rule consists of a condition and some number of property settings, written in any order. Rules
are generally written on a single line, but can be split across lines using a special line continuation
character. When a rule is evaluated, the condition is tested for that particular transaction. If the
condition evaluates to True, then all of the listed property settings are executed and evaluation of the
current layer ends. The rule is said to match. If the condition evaluates to False for that transaction, it is
said to miss.

19

Volume 11: Content Policy Language Guide

In turn, a condition is a boolean combination of trigger expressions. Triggers are individual tests that
can be made against components of the request (url=), response
(response.header.Content-Type=), related user (user=, group=), or system state (time=).
With a few notable exceptions, triggers test one aspect of request, response, or associated state against
a boolean expression of values.
For the conditions in a rule, each of the triggers is logically anded together. In other words, the
condition is only true if each one of the trigger expressions is true.
Properties are settings that control transaction processing, such as deny, or the handling of the object,
such as cache(no), indicating that the object is not to be cached locally. At the beginning of a
transaction, all properties are set to their default values. As the policy is evaluated in sequence, rules
that match might set a property to a particular value. A property retains the final value setting when
evaluation ends, and the transaction is processed accordingly. Properties that are not set within the
policy maintain their default values.
The logical form of a policy rule could be expressed as:
if condition is true then set all listed properties as specified

The following is an example of a simple policy rule:
url.domain=example.com time=0900..1700 exception(policy_denied)

It states that the exception( ) property is set to policy_denied if both of the following triggers test
true:


The request is made for a page from the domain example.com



The request is made between 9 a.m. and 5 p.m.

Notes


CPL triggers have the form trigger_name=pattern_expression



CPL properties have the form property_name(setting), except for a few imperative gestures
such as allow and deny.



The text in policy rules is case-insensitive, with a few exceptions identified in the following
chapters.



Non-ascii characters cannot occur within a CPL source file.



Policy listings are normalized in several ways. First, condition and action definitions which may
appear anywhere in the source, will be grouped following the policy rules. Second, the order of
the conditions and properties on a rule may change, since the CPL compiler always puts a deny or
allow at the beginning of the rule, and orders conditions to optimize evaluation. Finally, several
phrases are synonyms for phrases that are preferred. In the output of show policy, the preferred
form is listed instead of the synonym.
Four such synonyms are:

20



exception(authorization_failed), which is a synonym for the preferred
deny.unauthorized



force_exception(authorization_failed), which is a synonym for the preferred
force_deny.unauthorized

Chapter 1: Overview of Content Policy Language





exception(policy_denied), which is a synonym for the preferred deny



exception(no), which is a synonym for the preferred allow.

More complex boolean expressions are allowed for the pattern_expression in the triggers. For
example, the second part of the condition in the simple rule shown above could be “the request is
made between 9 a.m. and noon or between 1 p.m. and 5 p.m”, expressed as:
... time=(0900..1200 || 1300..1700) ...

Boolean expression are built from the specific values allowed with the trigger, and the boolean
operators ! (not), && (and), || (or) and () for grouping. More details are found in the Trigger
Reference chapter. Alternative values may also be separated by a comma—this is often more
readable than using the ‘||’ operator. For example, the following rule will deny service to requests
for pages in either one of the two domains listed.
url.domain=(example.com, another.com) deny



Long lines can be split using ‘\’ as a line continuation character. The ‘\’ must be the last character
on the line and be preceded by space or Tab. For example:
url.domain=example.com time=0900..1700 \
deny

Do not use a semicolon to add comments within such a continued line: everything following the
semicolon, including text on the continued lines, will be treated as part of the comment. For
example:
url.domain=example.com \ ; misplaced comment
deny

becomes
url.domain=example.com ; misplaced comment deny

In other words, the effect was to continue the comment.

Quoting
Certain characters are considered special by CPL and have meaning as punctuation elements of the
language. For example = (equal) separates a trigger name from its associated value, and blank space
separates expressions in a rule. To use a value that contains one of these characters, the value must be
quoted with either single (') or double (") quotation marks, so that the special characters are not
interpreted as punctuation. Text within single quotation marks can include any character other than a
single quotation mark. Text within double quotation marks can include any character other than a
double quotation mark. Here are some examples of where quoting is necessary:
user="John Doe" ; value contains a space
url="www.example.com/script.cgi?param=value"

; value contains ‘=’

deny( "You don’t have access to that page!" ) ; several special chars

21

Volume 11: Content Policy Language Guide

The full list of characters that should be quoted when they appear can be found in the reference
manual. Note that you can quote any string in CPL without affecting interpretation, even if the quotes
are not strictly needed. For convenience, you can quote any value that consists of more than letters
and/or numbers.
user="john.doe" ; quotes not required, but can be used

Important: Within a define action or define url_rewrite statement, you must use double
quotes ("), not single quotes (') to delimit a string.

Layers
A policy layer is a CPL construct used to evaluate a set of rules and reach one decision. Separating
decisions helps control policy complexity, and is done through writing each decision in a separate
layer. Each layer has the form:
[layer_condition][layer_properties] ...
layer_content

where:


The layer_type defines the transactions evaluated against this policy, and restricts the
triggers and properties allowed in the rules used in the layer. For more information, see
"Understanding Layers" on page 36.



The optional action, separated from the layer type by space, is a CPL User-defined
Identifier (see "Understanding Sections" on page 43), basically an alphabetic character
followed by alphanumeric or underscore characters.



The optional layer_condition is a list of triggers, all of which must evaluate to true
before the layer content is evaluated.



The optional layer_properties is a list of properties that will become the default
settings for those properties for any rule matched in the layer. These can be overridden by
explicitly setting a different value for that property in a specific rule within the layer.



The layer_content is a list of rules, possibly organized in sections. (see following). A
layer must contain at least one rule.

Collectively, the layer_condition and layer_properties are often referred to as a layer
guard expression.
If a rule has the logical form “if (condition is true) then set properties”, a layer has the form:
if (layer_condition is true) then
{
if (rule1_condition is true) then
set layer_properties then set rule1 properties
else if (rule2_condition is true) then
set layer_properties then set rule2 properties
else if (rule3_condition is true) then
set layer_properties then set rule3 properties
...
}

22

Chapter 1: Overview of Content Policy Language

Within a layer, the first rule that matches terminates evaluation of that layer.
Layers within a policy are evaluated from top to bottom, with rules in later layers taking
precedence over rules in earlier layers.
In CPL, all policy rules are written in a layer. A rule cannot appear in policy preceding any layer
header.

Sections
The rules in layers can optionally be organized in one or more sections, which is a way of grouping
rules together. A section consists of a section header followed by a list of rules.
A section has the form:
[section_type

[action]] [section_condition][section_properties]

section_content

where:


The section_type defines the syntax of the rules used in the section, and the evaluation
strategy used to evaluate those rules. The square brackets [ ] surrounding the section
name (and optional action) are required.



The optional action, separated from the section type by space, is a CPL User-defined
Identifier similar to a layer action.



The optional section_condition is a list of triggers, all of which must evaluate to true
before the section content is evaluated.



The optional section_properties is a list of properties that will become the default
settings for those properties for any rule matched in the section. These override any layer
property defaults and can in turn be overridden by explicitly setting a different value for
that property in a rule within the section.



The section_content is a list of rules. A section must contain at least one rule.

Collectively, the section_condition and section_properties are often referred to as a section guard
expression.
A layer with sections has the logical form:
if (layer_condition is true) then
{
if (section1_condition is true then
{
if (rule1A_condition is true) then
set layer_properties then section_properties then rule1A properties
else if (rule1B_condition is true) then
set layer_properties then section_properties then set rule1B
properties
....
}
else if (section2_condition is true then
{
if (rule2A_condition is true) then

23

Volume 11: Content Policy Language Guide

set layer_properties then section_properties then rule2A properties
else ...
}
...
}

Definitions
Two types of definitions are used in CPL:


Named definitions that are explicitly referenced by policy



Anonymous definitions that apply to all policy evaluation and are not referenced directly in rules.

Named Definitions
There are various types of named definitions. Each definition is given a user defined name that is then
used in rules to refer to the definition. This section highlights a few of the definition types, as an
overview of the topic. See Chapter 6: “Definition Reference” on page 349 for more details.
Subnet Definitions
Subnet definitions are used to define a list of IP addresses or IP subnet masks that can be used to test
any of the IP addresses associated with the transaction, for example, the client’s address or the
request’s destination address.
Condition Definitions
Condition definitions can include any triggers that are legal in the layer referencing the condition. The
condition= trigger is the exception to the rule that triggers can test only one aspect of a transaction.
Since conditions definitions can include other triggers, condition= triggers can test multiple parts of

the transaction state. Also, condition definitions allow for arbitrary boolean combinations of trigger
expressions.
Category Definitions
Category definitions are used to extend vendor content categories or to create your own. These
categories are tested (along with any vendor defined categories) using the category= trigger.
Action Definitions
An action takes arguments and is wrapped in a named action definition block. Actions are turned on
or off for a transaction through setting the action( ) property. The action property has syntax that
allows for individual actions to be turned on and off independently. When the action definition is
turned on, any actions it contains operate on their respective arguments.
Transformer Definitions
A transformer definition is a kind of named definition that specifies a transformation that is to be
applied to an HTTP response. There are three types: url_rewrite definitions, active_content
definitions, and javascript definitions.

24

Chapter 1: Overview of Content Policy Language

Anonymous Definitions
Two types of anonymous definitions modify policy evaluation, but are not referenced by any rules.
These definitions serve to restrict DNS and Reverse-DNS lookups and are useful in installations where
access to DNS or Reverse-DNS resolution is limited or problematic.

Referential Integrity
Policy references many objects defined in system configuration, such as authentication realms,
forward hosts, SOCKS gateways, and the like. CPL enforces the integrity of those references by
ensuring that the entities named in policy exist and have appropriate characteristics at the time the
policy is compiled. During runtime, any attempts to remove a configured object that is referenced by
currently active policy will fail.
To remove a configured entity, such as a realm, that is referenced by policy, new policy must be
installed with all references to that realm removed. New transactions will open against a version of
policy that does not require the realm. Once all outstanding transactions that required reference to the
realm have completed, the realm can be removed from configuration.

Substitutions
The actions used to rewrite the URL request or to modify HTTP request headers or HTTP response
headers often need to reference the values of various elements of the transaction state when
constructing the new URL or header value. CPL provides support for various substitutions, which will
expand at runtime to the indicated transaction value. Substitutions have the form:
$(name)

For example, the substitution $(user) expands to the authenticated user name associated with the
transaction. If policy did not require that user to authenticate, the substitution expands to an empty
string.
Substitutions can also be used directly in the values specified to some CPL properties, such as when
setting text in a message that will be displayed to users.
Substitutions are available for a variety of purposes. For a categorized list of the substitutions
available, see Appendix D: "CPL Substitutions" on page 379.

Writing Policy Using CPL
A policy file is the unit of integration used to assemble policy.
Policy written in CPL is stored in one of four files on the ProxySG. These files are the following:


VPM: This file is reserved for use by the Visual Policy Manager.



Local: When the VPM is not being used, the Local file will typically contain the majority of the
policy rules for a system. When the VPM is being used, this file might be empty, it might include
rules for advanced policy features that are not available in the VPM, or it might otherwise
supplement VPM policy.



Central: This file is typically managed by Blue Coat Systems, although you can have the ProxySG
point to a custom Central policy file instead.

25

Volume 11: Content Policy Language Guide



Forward: The Forward policy file is normally used for all Forward policy, although you can use it
to supplement any policy created in the other three policy files. The Forward policy file will
contain Advanced Forwarding rules when the system is upgraded from a previous version of
SGOS (2.x) or CacheOS (4.x).

Each of the files may contain rules and definitions, but an empty file is also legal. (An empty file
specifies no policy and has no effect on the ProxySG.)
Cross file references are allowed but the definitions must be installed before the references, and
references must be removed before definitions are removed.
The final installed policy is assembled from the policy stored in the four files by concatenating their
contents. The order of assembly of the VPM, Central and Local policy files is configurable. The
recommended evaluation order is VPM, Local, Central. The Forward policy file is always last.

Authentication and Denial
One of the most important timing relationships to be aware of is the relation between authentication
and denial. Denial can be done either before or after authentication, and different organizations have
different requirements. For example, suppose an organization requires the following:


Protection from denial of service attacks by refusing traffic from any source other than the
corporate subnet.



The user name of corporate users is to be displayed in access logs, even when the user request has
been denied.

The following example demonstrates how to choose the correct CPL properties. First, the following is
a sample policy that is not quite correct:
define subnet corporate_subnet
10.10.12.0/24
end

client.address=!corporate_subnet deny ; filter out strangers
authenticate(MyRealm) ; this has lower precedence than deny

; user names will NOT be displayed in the access log for the denied requests
category=Gambling exception(content_filter_denied)

In this policy, requests coming from outside the corporate subnet are denied, while users inside the
corporate subnet are asked to authenticate.
Content categories are determined from the request URL and can be determined before
authentication. Deny has precedence over authentication, so this policy denies the user request before
the user is challenged to authenticate. Therefore, the user name is not available for access logging.
Note that the precedence relation between deny and authenticate does not depend on the order of the
layers, so changing the layer order will not affect the outcome.
The CPL property force_authenticate(), however, has higher precedence than deny, so the
following amended policy ensures that the user name is displayed in the access logs:
define subnet corporate_subnet
10.10.12.0/24
end

26

Chapter 1: Overview of Content Policy Language


client.address=!corporate_subnet deny ; filter out strangers
force_authenticate(MyRealm) ; this has higher precedence than deny

; user names will be displayed in the access log for the denied requests
category=Gambling exception(content_filter_denied)

The timing for authentication over the SOCKS protocol is different. If you are using the SOCKS
authentication mechanism, the challenge is issued when the connection is established, so user
identities are available before the request is received, and the following policy would be correct.
define subnet corporate_subnet
10.10.12.0/24
end

client.address=!corporate_subnet deny ; filter out strangers
socks.authenticate(MyRealm) ; this happens earlier than the category test

; user names be displayed in the access log for the denied requests
category=Gambling exception(content_filter_denied)

Note that this only works for SOCKS authenticated users.

Installing Policy
Policy is installed by installing one of the four policy files (VPM, Local, Central or Forward). Installing
one new file causes the most recent versions of the other three files to be loaded, the contents
concatenated in the order specified by the current configuration, and the resulting complete policy
compiled.
If any compilation errors are detected, the new policy file is not installed and the policy in effect is
unchanged.
Refer to Volume 7: The Visual Policy Manager and Advanced Policy Tasks for specific instructions on
installing a policy file.

CPL General Use Characters and Formatting
The following characters and formatting have significance within policy files in general, outside of the
arguments used in condition expressions, the values used in property statements, and the arguments
used in actions.
Character
Semicolon (;)

Example
; Comment
; Comment

Significance
Used either inline or at the beginning of a
line to introduce text to be ignored during
policy evaluation. Commonly used to
provide comments.

27

Volume 11: Content Policy Language Guide

Character

Example

Significance

Newline

deny server_url.scheme=mms
deny
server_url.domain=xyz.com

CPL expects most constructs (layers,
sections, rules, definitions) to begin on a
new line. When not preceded by a line
continuation character, a newline
terminates a layer header, section header,
the current rule, clause within a defined
condition, or action within an action
definition.

Line Continuation

\

A line continuation character indicates that
the current line is part of the previous line.

Whitespace

< proxy >
weekday = ( 3 || 7 ) deny

Used to enhance readability. Whitespace
can be inserted between tokens, as shown
in this example, without affecting
processing. In addition, quoted strings can
include whitespace. However, numeric
ranges, such as weekday = 1..7, cannot
contain whitespace.

Angle brackets (< >)



Used to mark layer headings.

Square brackets ([ ])

[Rule]

Used to mark section names.

Equal sign (=)

server_url.scheme=mms

Used to indicate the value a condition is to
test.

Parentheses ( )

max_bitrate(no)

Used to enclose the value that a property is
to be set to, or group components of a test.

Troubleshooting Policy
When installed policy does not behave as expected, use policy tracing to understand the behavior of
the installed policy.
Tracing records additional information about a transaction and re-evaluates the transaction when it is
terminated; however, it does not show the timing of evaluations through transaction processing. The
extra processing required significantly impacts performance, so do not enable tracing in production
environments unless you need to reproduce and diagnose a problem. If tracing is used on a system in
production, attempt to restrict which transactions are traced. For example, you can trace only requests
from a test workstation by defining the tracing rules as conditional on a client.address= trigger that
tests for that workstation's IP address.
For more information on generating and retrieving policy trace, see Appendix B: "Testing and
Troubleshooting" on page 379.
While policy traces can show the rule evaluation behavior, they do not show the final effect of policy
actions like HTTP header or URL modifications. To see the result of these policy actions it is often
useful to actually view the packets sent and received. The PCAP facility can be used in conjunction
with tracing to see the effect of the actions set by the matching rules.

28

Chapter 1: Overview of Content Policy Language

Upgrade/Downgrade Issues
Specific upgrade downgrade issues will be mentioned in the release notes accompanying your version
of SGOS. This section highlights general upgrade downgrade issues related to policy written in CPL.

CPL Syntax Deprecations
As the power of CPL has increased, the CPL language has evolved. To allow continuous evolution, the
CPL language constructs are now more regular and flexible. Older language constructs have been
replaced with new constructs of equal or greater power.
However, this also implies that support for old language constructs will eventually be dropped to help
maintain the runtime efficiency of evaluation. As part of the migration strategy, the CPL compilation
warnings might include warnings regarding the use of deprecated constructs. This class of warning is
special, and indicates use of a CPL language element that will not be supported in the next major
release of SGOS. Eliminate deprecation warnings by migrating the policy identified by the warning to
more modern syntax, which is usually indicated in the warning message. Attempts to upgrade to the
next major release might fail, or result in a failure to load policy, unless all deprecation warnings are
eliminated.

Conditional Compilation
Occasionally, you might be required to maintain policy that can be applied to appliances running
different versions of SGOS and requiring different CPL. CPL provides the following conditional
compilation directive that tests the SGOS version (such as 2.1.06):
release.version=

The range is a standard CPL range test: min..max, where both minimum and maximum are optional.
The min and max can be MAJOR.MINOR.DOT.PATCH, with MINOR, DOT and PATCH optional. Therefore,
rules containing grammar introduced in 2.1.07 can be protected with
#if release.version=2.1.07..
; guarded rules
...
#endif

while grammar introduced in 2.2 can be protected with:
#if release.version=2.2..
; guarded rules
...
#endif

29

Volume 11: Content Policy Language Guide

30

Chapter 2: Managing Content Policy Language

As discussed in Chapter 1, Content Policy Language policies are composed of transactions that are
placed into rules and tested against various conditions.
This chapter discusses the following:


"Understanding Transactions and Timing" on page 31



"Understanding Layers" on page 36



"Understanding Sections" on page 43



"Defining Policies" on page 46



"Best Practices" on page 50

Understanding Transactions and Timing
Transactions are classified as in several different types:
































Only a subset of layer types, conditions, properties, and actions is appropriate for each of these four
transaction types.

Transactions
An administrator transaction evaluates policy in layers. The policy is evaluated in two stages:


Before the authentication challenge.



After the authentication challenge.

31

Volume 11: Content Policy Language Guide

If an administrative user logs in to the ProxySG Management Console, and the administrator’s Web
browser is proxied through that same ProxySG, then a proxy transaction is created and
policy is evaluated before the administrator transaction is created and policy is evaluated. In
this case, it is possible for an administrator to be denied access to the Management Console by proxy
policy.
Important: Policy is not evaluated for serial console access, RSA authenticated SSH access, managers
logged in using the console account credentials, or SNMP traffic.

Transactions
When a client connects to one of the proxy service ports configured on the secure proxy appliance
(refer to Volume 3: Proxies and Proxy Services), a proxy transaction is created to cover both the request
and its associated response. Note that requests for DNS proxy services are handled separately from
requests for higher level services; see the following transactions section.
A proxy transaction evaluates policy in , , , and layers. The
layers are only evaluated if the transaction reaches the stage of contacting an origin server
to satisfy the request (this is not the case if the request is satisfied by data served from cache, or if the
transaction is terminated by an exception). The layers are only evaluated if the
transaction is terminated by an exception.
Each of the protocol-specific proxy transactions has specific information that can be
tested—information that may not be available from or relevant to other protocols. HTTP Headers and
Instant Messaging buddy names are two examples of protocol-specific information.
Other key differentiators among the proxy transaction subtypes are the order in which information
becomes available and when specific actions must be taken, as dictated by the individual protocols.
Variation inherent in the individual protocols determines timing, or the sequence of evaluations that
occurs as the transaction is processed.
The following table summarizes the policy evaluation order for each of the protocol-specific proxy
transactions.
Table 2.1: When Policy is Evaluated
Transaction Type

Policy is Evaluated....

Tunneled TCP transactions

before the connection is established to the origin server.

HTTP proxy transactions

Before the authentication challenge.
After the authentication challenge, but before the requested object is fetched.
Before making an upstream connection, if necessary.
After the object is fetched

32

Chapter 2: Managing Content Policy Language

Table 2.1: When Policy is Evaluated (Continued)
Transaction Type

Policy is Evaluated....

FTP over HTTP transactions:

Before the authentication challenge.
After the authentication challenge, but before the required FTP commands are
executed.
Before making an upstream connection, if necessary.
After the object is fetched.

Transparent FTP transactions

Policy is examined before the requested object is fetched.

Real Media streaming
transactions

Before the authentication challenge.
After the authentication challenge, but before getting object information.
Before making an upstream connection, if necessary.
After the object information is available, but before streaming begins.
After streaming begins (this evaluation can be done multiple times, for
example after playback is paused and restarted).

Windows Media MMS
streaming transactions

Before the authentication challenge.
Before making an upstream connection, if necessary.
After the authentication challenge but before getting object information.
After the object information is available, but before streaming begins.
After streaming begins (this evaluation can be done multiple times, for
example after playback is paused and restarted).

Windows Media HTTP
streaming transactions

Before the authentication challenge.
After the authentication challenge, but before the requested object is fetched.
Before making an upstream connection, if necessary. (Up to this point it is
similar to an HTTP transaction.)
What happens at this stage depends on negotiations with the origin server:
• After the origin server is contacted, if the User Agent header denotes the
Windows Media player and the server supports Microsoft streaming HTTP
extensions, it finishes like an MMS transaction: Object information is
available at this stage but streaming has not begun.
• If the User-Agent header is not a Windows Media player or the server does
not support Microsoft streaming extensions, it finishes like an HTTP
transaction: The requested object is fetched, and policy is evaluated

Some conditions cannot be evaluated during the first stage; for example, the user and group
information will not be known until stage two. Likewise, the response headers and MIME type are
unavailable for testing until stage three. For conditions, this is known as the earliest available time.
Policy decisions can have similar timing considerations, but this is known as the latest commit time. In
this example, the requirement to authenticate must be known at stage one, and a forwarding host or

33

Volume 11: Content Policy Language Guide

Transactions
When a client connects to one of the DNS-Proxy service ports configured on the ProxySG (for
information refer to Volume 3: Proxies and Proxy Services), a transaction is created to
cover both the request and its associated response.
A transaction evaluates policy in layers only. Policy in other layers does
not affect transactions.
Policy for transactions is evaluated in two stages:


After the DNS request is received



After the DNS response is available.

Transactions
Cache transactions are initiated by the ProxySG in order to load or maintain content in the local object
store during adaptive refresh or pipelining, or as a result of a content distribute CLI command.
These may be HTTP, FTP, or streaming media transactions. Since no specific user is associated with
these transactions, content related policy is evaluated for cache transactions, but user related policy is
not evaluated.
A cache transaction evaluates policy in and layers. The layers are only
evaluated if an origin server must be contacted to complete the transaction.
The following is a list of cache transactions:


A content distribute transaction that is initiated by the content distribute CLI command. A
content distribute transaction may use one of the following protocols: HTTP, HTTPS, Real Media,
or Windows Media. This type of transaction may be preceded by a separate Administrator
transaction, since the administrator must be authenticated and authorized to use the command.



Pipeline transactions (HTTP only).



Advertisement transactions (HTTP only).



If-modified-since transactions (HTTP only).



Refresh transactions (HTTP only).



ICP transactions.

Cache transactions have no client identity since they are generated internally by the ProxySG, and
they do not support authentication or authorization. Therefore, they do not support conditions such
as client.address= and group=, or the authenticate() property.
An HTTP cache transaction is examined in two stages:


Before the object is retrieved from the origin server.



After the object is retrieved.

Transaction
Exception transactions include transactions that have been terminated by an exception.

34

Chapter 2: Managing Content Policy Language

Transactions
A transaction is created when the ProxySG needs to evaluate forwarding policy before
accessing a remote host and no proxy or cache transaction is associated with this activity. Examples
include sending a heart-beat message, and downloading an installable list from an HTTP server.
A transaction only evaluates policy in layers.

Transactions
Two kinds of transactions exist:


: This includes cache and proxy transactions, except for transactions.
Note that in VPM, transactions are referred to as SSL access transactions.



: A kind of proxy transaction whose purpose is to decide whether or not to
intercept and decrypt an SSL connection, or leave it unencrypted and simple tunnel it.

Timing
As stated in the discussion of proxy transactions, various portions of the transaction information
become available at different points in the evaluation, and each protocol has specific requirements for
when each decision must be made. The CPL triggers and properties are designed so that wherever
possible, the policy writer is shielded from the variations among protocols by making the timing
requirements imposed by the CPL accommodate all the protocols. Where this is not possible (because
using the most restrictive timing causes significant loss of functionality for the other protocols),
protocol specific triggers have been introduced. When evaluated against other protocols, these
triggers return the not applicable value or N/A. This results in the rule being skipped (the
expression evaluates to false, no matter what it is). It is possible to explicitly guard such rules so that
they are only evaluated against appropriate transactions.
The variation in trigger and property timings implies that within a policy rule a conflict is possible
between a condition that can only be tested relatively late in the evaluation sequence and a property
that must be set relatively early in the evaluation sequence. Such a rule results in a compile-time error.
For example, here is a rule that would be incorrect for evaluating any transaction:
If the user is in group xyz, require authentication.
The rule is incorrect because group membership can only be determined after authentication and the
rule tests group membership and specifies the authentication realm, a property that must be set before
the authentication challenge can be issued. The following code illustrates this incorrect rule and the
resulting message at compile time:
group=xyz authenticate(MyRealm)
Error: Late condition guards early action: 'authenticate(MyRealm)'

It is, however, correct for the authentication requirement to be conditional on the client address
(client.address=) or proxy port (proxy.port=), as these can be determined at the time the client
connection is established and therefore are available from the beginning of a proxy transaction.

35

Volume 11: Content Policy Language Guide

For the HTTP protocol, authenticate() can be conditional on the URL (url=), but for MMS
streaming, only the Host portion of the URL can be tested (url.host=). Recall the outline of the
evaluation model for Windows Media transactions presented in "Understanding Transactions and
Timing" on page 31.
As another example, consider the following:
response.header.Content-type=”text/html” forward( somehost )

But policy cannot determine the value of the Content-type response header until the response is
returned. The ProxySG cannot contact the server to get the response until policy determines what
hosts or gateways to route through to get there. In other words, policy must set the forward()
property. But policy cannot commit the action until the Content-type response header
has been determined. Again, since the condition is not testable until later in the request (after the time
at which the property must be set), an error is received.

Understanding Layers
Eight types of layers are allowed in any policy file. The layer type determines the kinds of transaction
its rules will act upon. The token used in the header identifies the layer type.


—Used to define policy that controls access to the management console and the

command line. Policy is not evaluated for serial console access or SNMP traffic, however.



—Used to list policy rules that are evaluated during both cache and proxy transactions.
—Exception layers are evaluated when a proxy transaction is terminated by an

exception.


—Forward layers are only evaluated when the current transaction requires an

upstream connection. Forwarding policy is generally distinct and independent of other policies,
and is often used as part of maintaining network topologies.


—Used to list policy rules that are evaluated during a proxy transaction.



—Used to define policy controlling transactions. Only
transactions are evaluated against layers.



—Used to list policy triggers and properties that define the conditions under
which SSL connections are intercepted and decrypted or tunneled. This layer is evaluated by the
SSL-Intercept transaction. Only the conditions, actions, and properties essential to make the
tunnel or intercept decision are allowed in the SSL-Intercept layer. For a list of CPL gestures
allowed in the SSL-Intercept layer, refer to Volume 3: Proxies and Proxy Services.



—Used to store additional SSL triggers and properties that are unrelated to SSL
interception. This layer, called the SSL Access layer in VPM, is evaluated by all cache and proxy
transactions except the SSL-Intercept and transactions. For a list of CPL gestures
allowed in the SSL layer, refer to Volume 3: Proxies and Proxy Services.

Important: Only a subset of the conditions, properties, and actions available in the policy language
is permitted within each layer type; the remainder generate compile-time errors. Check
the specific chapters in this manual to learn where the conditions, properties, and actions
can be used.

36

Chapter 2: Managing Content Policy Language

Layers
layers hold policy that is executed by Administrator transactions. This policy is used to

specify an authentication realm; to allow or deny administrative access based on the client’s IP
address, credentials, and type of administrator access requested (read or write); and to perform any
additional logging for administrative access.
Important: When traffic is explicitly proxied, it arrives at the layer with the client IP
address set to the ProxySG’s IP address; therefore, the client.address= condition is not
useful for explicitly proxied traffic.

37

Volume 11: Content Policy Language Guide

The syntax is:
[admin_condition][admin_properties] ...
admin_rules

where:


The optional “comment”, separated from the layer type by space, is an identifier or quoted
string that is displayed in policy traces to identify the purpose of the layer.



The optional admin_condition is a list of triggers, all of which must evaluate to true
before the layer content is evaluated. For more information on using conditions, see
Chapter 3: "Condition Reference" on page 53. See also the following Layer Guards section.



The optional admin_properties is a list of properties set if any of the rules in the layer
match. These act as defaults, and can be overridden by property settings in specific rules
in the layer. For more information on using properties, see Chapter 4: "Property
Reference" on page 203. See also the following Layer Guards section.



admin_rules is a list of rules representing the decision to be made by this policy layer.

Layers
layers hold policy that is executed by both cache and proxy transactions. Since cache
transactions have no concept of a client, all layer policy is clientless, so you cannot test client
identity using client.address=, user=, group=, and the like.

Certain types of policy must be applied consistently to both proxy and cache transactions to preserve
cache consistency. Such policy must not be conditional on client identity or time of day, and belongs in
a layer. Examples include the following:


Response virus scanning.



Cache control policy (other than bypass_cache).



Modifications to request headers, if the modification affects the content returned by the Web
server, and the content is cached.



Rewrites of the request URL that modify the server URL but not the cache URL. (Place rewrites of
the request URL that change the cache and server URL to the same value in a layer.)

Only the following properties are safe to make conditional on time or client identity in a
layer:

38



Pipelining



Tracing, logging



Freshness checks



Redirection



Content transforms

Chapter 2: Managing Content Policy Language

The syntax is:
[cache_condition][cache_properties] ...
cache_rules

where:


The optional “comment”, separated from the layer type by space, is an identifier or
quoted string that is displayed in policy traces to identify the purpose of the layer.



The optional cache_condition is a list of triggers, all of which must evaluate to true
before the layer content is evaluated. For more information on using conditions, see
Chapter 3: "Condition Reference" on page 53. See also the following Layer Guards section.



The optional cache_properties is a list of properties set if any of the rules in the layer
match. These act as defaults, and can be overridden by property settings in specific rules
in the layer. For more information on using properties, see Chapter 4: "Property
Reference" on page 203. See also the following Layer Guards section.



cache_rules is a list of rules representing the decision to be made by this policy layer.

Layers
layers are evaluated when a proxy transaction is terminated by an exception. This could
be caused by a bad request (for example, the request URL names a non-existent server) or by setting
the deny or exception() properties in policy. Policy in an exception layer can be used to control how
access logging is performed for exceptions, such as authentication_failed. It can also be used to
modify the HTTP response headers in the exception page that is sent to the client.

The syntax is:
[exception_condition][exception_properties] ...
exception_rules

where:


The optional “comment”, separated from the layer type by space, is an identifier or
quoted string that is displayed in policy traces to identify the purpose of the layer.



The optional exception_condition is a list of triggers, all of which must evaluate to true
before the layer content is evaluated. For more information on using conditions, see
Chapter 3: "Condition Reference" on page 53. See also the following Layer Guards section.



The optional exception_properties is a list of properties set if any of the rules in the layer
match. These act as defaults, and can be overridden by property settings in specific rules in the
layer. For more information on using properties, see Chapter 4: "Property Reference" on page 203.
See also the following Layer Guards section.



exception_rules is a list of rules representing the decision to be made by this policy layer.

39

Volume 11: Content Policy Language Guide

Layers
layers are evaluated when the current transaction requires an upstream connection (and
only then: forward policy will not be evaluated for a cache hit). layers use the
server_url= tests rather than the url= tests so that they are guaranteed to honor any policy that

rewrites the URL.
The syntax is:
[forward_condition][forward_properties] ...
forward_rules

where:


The optional “comment”, separated from the layer type by space, is an identifier or
quoted string that is displayed in policy traces to identify the purpose of the layer.



The optional forward_condition is a list of triggers, all of which must evaluate to true
before the layer content is evaluated. For more information on using conditions, see
Chapter 3: "Condition Reference" on page 53. See also the following Layer Guards section.



The optional forward_properties is a list of properties set if any of the rules in the layer
match. These act as defaults, and can be overridden by property settings in specific rules
in the layer. For more information on using properties, see Chapter 4: "Property
Reference" on page 203. See also the following Layer Guards section.



forward_rules is a list of rules representing the decision to be made by this policy layer.

Layers
layers define policy for authenticating and authorizing users’ requests for service over one of

the configured proxy service ports (refer to Chapter 6:”Managing Port Services” in the Blue Coat
ProxySG Configuration and Management Guide). Proxy layer policy involves both client identity and
content. Only proxy transactions are evaluated against layers.
Note:

Policy for transactions is distinct from policy for other proxy services. See the
following Layers section.

The syntax is:
[proxy_condition][proxy_properties] ...
proxy_rules

where:

40



The optional “comment”, separated from the layer type by space, is an identifier or
quoted string that is displayed in policy traces to identify the purpose of the layer.



The optional proxy_condition is a list of triggers, all of which must evaluate to true
before the layer content is evaluated. For more information on using conditions, see
Chapter 3: "Condition Reference" on page 53. See also the following Layer Guards section.

Chapter 2: Managing Content Policy Language



The optional proxy_properties is a list of properties set if any of the rules in the layer
match. These act as defaults, and can be overridden by property settings in specific rules
in the layer. For more information on using properties, see Chapter 4: "Property
Reference" on page 203. See also the following Layer Guards section.



proxy_rules is a list of rules representing the decision to be made by this policy layer.

Layers
layers define policy controlling transactions. Only
transactions are evaluated against layers.

The syntax is:
[dns_proxy_condition][dns_proxy_properties] ...
dns_proxy_rules

where:


The optional “comment”, separated from the layer type by space, is an identifier or
quoted string that is displayed in policy traces to identify the purpose of the layer.



The optional dns_proxy_condition is a list of triggers, all of which must evaluate to true
before the layer content is evaluated. For more information on using conditions, see
Chapter 3: "Condition Reference" on page 53. See also the following Layer Guards section.



The optional dns_proxy_properties is a list of properties set if any of the rules in the
layer match. These act as defaults, and can be overridden by property settings in specific
rules in the layer. For more information on using properties, see Chapter 4: "Property
Reference" on page 203. See also the following Layer Guards section.



dns_proxy_rules is a list of rules representing the decision to be made by this policy

layer.

Layers
The layer lists the triggers and properties that define the interception conditions for
SSL connections. This layer is evaluated by the SSL-Intercept transaction only.
The syntax is
[SSL-Intercept_condition][SSL-Intercept_properties]
...
SSL-Intercept_rules

where:


The optional “comment”, separated from the layer type by space, is an identifier or
quoted string that is displayed in policy traces to identify the purpose of the layer.



The optional SSL-Intercept_condition is a list of triggers, all of which must evaluate to
true before the layer content is evaluated. For more information on using conditions, see
Chapter 3: "Condition Reference" on page 53. See also the following Layer Guards section.



The optional SSL-Intercept_properties is a list of properties set if any of the rules in
the layer match. These act as defaults, and can be overridden by property settings in

41

Volume 11: Content Policy Language Guide

specific rules in the layer. For more information on using properties, see Chapter 4:
"Property Reference" on page 203. See also the following Layer Guards section.


SSL-Intercept_rules is a list of rules representing the decision to be made by this policy

layer.

Layers
The layer lists the triggers and properties that define the interception conditions for SSL
connections. This layer is evaluated by all transactions except the SSL-Intercept transaction.
The syntax is
[SSL_condition][SSL_properties] ...
SSL_rules

where:


The optional “comment”, separated from the layer type by space, is an identifier or
quoted string that is displayed in policy traces to identify the purpose of the layer.



The optional SSL_condition is a list of triggers, all of which must evaluate to true before
the layer content is evaluated. For more information on using conditions, see Chapter 3:
"Condition Reference" on page 53. See also the following Layer Guards section.



The optional SSL_properties is a list of properties set if any of the rules in the layer
match. These act as defaults, and can be overridden by property settings in specific rules
in the layer. For more information on using properties, see Chapter 4: "Property
Reference" on page 203. See also the following Layer Guards section.



SSL_rules is a list of rules representing the decision to be made by this policy layer.

Layer Guards
Often, the same set of conditions or properties appears in every rule in a layer. For example, a specific
user group for which a number of individual cases exist where some things are denied:

group=general_staff url.domain=competitor.com/jobs deny
group=general_staff url.host=bad_host deny
group=general_staff condition=whatever deny
; etc.
group=general_staff allow

You can factor out the common elements into guard expressions. Notice that the common elements are
group=general_staff and deny. The following is the same policy, expressed as a layer employing a
guard expression:
group=general_staff deny
url.domain=competitor.com/jobs
url.host=bad_host
condition=whatever
; etc.
allow

42

Chapter 2: Managing Content Policy Language

Note that the explicit allow overrides the deny specified in the layer guard. This is an instance of a
rule specific property setting overriding the default property settings specified in a guard expression.

Timing
The “late guards early” timing errors that can occur within a rule can arise across rules in a layer.
When a trigger cannot yet be evaluated, policy also has to postpone evaluating all following rules in
that layer (since if the trigger turns out to be true and the rule matches, then evaluation stops for that
layer. If the trigger turns out to be false and the rule misses, then evaluation continues for the rest of
the rules in that layer, looking for the first match). Thus a rule inherits the earliest evaluation point
timing of the latest rule above it in the layer.
For example, as noted earlier, the following rule would result in a timing conflict error:
group=xyz authenticate(MyRealm)
Error: Late condition guards early action: 'authenticate(MyRealm)'

The following layer would result in a similar error:

group=xyz deny
authenticate(MyRealm)
Error: Late condition 'group=xyz' guards early action: 'authenticate(MyRealm)'

This also extends to guard expressions, as the guard condition must be evaluated before any rules in
the layer. For example:
group=xyz deny
authenticate(MyRealm)
Error: Late condition 'group=xyz' guards early action: 'authenticate(MyRealm)'

Understanding Sections
The rules in layers can optionally be organized in one or more sections, which is a way of grouping
rules together. A section consists of a section header followed by a list of rules.
Four sections types are supported in a standard CPL file:


[Rule]



[url]



[url.domain]



[server_url.domain]

Three of the section types, [url], [url.domain] and [server_url.domain], provide optimization
for URL tests. The names for these sections correspond to the CPL URL triggers used as the first test
for each rule in the section, that is url=, url.domain= and server_url.domain=. The
[url.regex] section provides factoring and organization benefits, but does not provide any
performance advantage over using a [Rule] section and explicit url.regex= tests.
To give an example, the following policy layer is created:

43

Volume 11: Content Policy Language Guide


url.domain=abc.com/sports deny
url.domain=nbc.com/athletics deny
; etc, suppose it's a substantial list
url.regex="sports|athletics" access_server(no)
url.regex="\.mail\." deny
; etc
url=www.bluecoat.com/internal group=!bluecoat_employees deny
url=www.bluecoat.com/proteus group=!bluecoat_development deny
; etc

This can be recast into three sections:

[url.domain]
abc.com/sports deny
nbc.com/athletics deny
; etc.
[Rule]
url.regex="sports|athletics" access_server(no)
url.regex="\.mail\." deny
[url]
www.bluecoat.com/internal group=!bluecoat_employees deny
www.bluecoat.com/proteus group=!bluecoat_development deny

Notice that the first thing on each line is not a labelled CPL trigger, but is the argument for the trigger
assumed by the section type. Also, after the first thing on the line, the rest of the line is the familiar
format.
The performance advantage of using the [url], [url.domain], or [server_url.domain] sections is
measurable when the number of URLs being tested reaches roughly 100. Certainly for lists of several
hundred or thousands of URLs, the performance advantage is significant.
When no explicit section is specified, all rules in a layer are assumed to be in a [Rule] section. That is,
the first example is equivalent to:

[Rule]
url.domain=abc.com/sports deny
url.domain=nbc.com/athletics deny
; etc, suppose it's a substantial list
url.regex="sports|athletics" access_server(no)
url.regex="\.mail\." deny
; etc
url=www.bluecoat.com/internal group=!bluecoat_employees deny
url=www.bluecoat.com/proteus group=!bluecoat_development deny
; etc

[Rule]
The [Rule] section type is used to logically organize policy rules into a section, optionally applying a
guard to the contained rules. The [Rule] section was so named because it can accept all rules in a
policy. If no section is specified, all rules in a layer are assumed to be in a [Rule] section.

44

Chapter 2: Managing Content Policy Language



Use [Rule] sections to clarify the structure of large layers. When a layer contains many rules, and
many of the rules have one or more conditions in common, you may find it useful to define
[Rule] sections.



Rules in [Rule] sections are evaluated sequentially, top to bottom. The time taken is proportional
to the number of rules in the section.



[Rule] sections can be used in any layer.

[url]
The [url] section type is used to group a number of rules that test the URL. The [url] section

restricts the syntax of rules in the section. The first token on the rule line is expected to be a pattern
appropriate to a url= trigger. The trigger name is not included.
Rules in [url] sections are evaluated through hash table techniques, with the result that the time
taken is not dependent on the number of rules in the section.


[url] sections are not allowed in or layers.

[url.domain]
The [url.domain] section is used to group a number of rules that test the URL domain. The
[url.domain] section restricts the syntax of rules in the section. The first token on the rule line is
expected to be a pattern appropriate to a url.domain= trigger. The trigger name is not included. (The
[url.domain] section replaces the [domain-suffix] section used in previous versions of CPL.)


Rules in [url.domain] sections are evaluated through hash table techniques, with the result that
the time taken is not dependent on the number of rules in the section.



[url.domain] sections are not allowed in or layers.

[url.regex]
The [url.regex] section is used to test the URL. The [url.regex] section restricts the syntax of
rules in the section. The first token on the rule line is expected to be a pattern appropriate to a
url.regex= trigger. The trigger name is not included. The [url.regex] section replaces the [Regex]
section used in previous versions of CPL.


Rules in [url.regex] sections are evaluated sequentially, top to bottom. The time taken is
proportional to the number of rules in the section.



[url.regex] sections are not allowed in , or layers.

[server_url.domain]
The [server_url.domain] section is used to test the domain of the URL used to fetch content from
the origin server. The [server_url.domain] section restricts the syntax and rules in the section. The
first token on the rule line is expected to be a pattern appropriate to a server_url.domain= trigger.
The trigger name is not included.
[server_url.domain] sections contain policy rules very similar to [url.domain] sections except that
these policy rules test the server_url, which reflects any rewrites to the request URL.

45

Volume 11: Content Policy Language Guide



Rules in [server_url.domain] sections are evaluated through hash table techniques, with the
result that the time taken is not dependent on the number of rules in the section.



[server_url.domain] sections are allowed in , , , and
layers.

Section Guards
Just as you can with layers, you can improve policy clarity and maintainability by grouping rules into
sections and converting the common conditions and properties into guard expressions that follow the
section header. A guard expression allows you to take a condition that applies to all the rules and put
the common condition next to the section header, as in [Rule] group=sales.
Guards are essentially a way of factoring out common sets of triggers and properties, to avoid having
to repeat them each time.

Defining Policies
This section includes some guidelines for defining policies using CPL.


Write an explicit layer header (, , , , or ) before
writing any rules or sections. The only constructs that should occur before the first layer header
are the condition-related definitions and comments.



Do not begin a policy file with a section, such as [Rule]. Ensure all sections occur within layers.



Do not use [Rule] sections unnecessarily.



Avoid empty or badly formed policy. While some CPL may look well-formed, make sure it
actually does something.

While the following example appears like proper CPL, it actually has no effect. It has a layer header
and a [Rule] section header, but no rule lines. As no rules exist, no policy exists either:
group=Administrators
[Rule] allow

Correct policy that allows access for the group “administrators” would be:

group=Administrators allow

In the following example, the layer is deceptive because only the first rule can ever be executed:

authenticate(MyRealm) ; this rule is unconditional
;all following rules are unreachable
allow group=administrator
allow group=clerk time=0900..1700
deny

At most, one rule is executed in any given layer. The first one that meets the conditions is acted upon;
all other rules in the layer are ignored. To execute more than one rule, use more than one layer. To
correctly define the above policy, two layers are required:

authenticate(MyRealm)

46

Chapter 2: Managing Content Policy Language


allow group=administrator
allow group=clerk time=0900..1700
deny



Do not mix the CacheOS 4.x filter-file syntax with CPL syntax.
Although the Content Policy Language is backward-compatible with the filter-file syntax, avoid
using the older syntax with the new. For example, as the filter-file syntax uses a different order of
evaluation, mixing the old and new syntax can cause problems. Blue Coat strongly recommends
not mixing the two syntaxes.

Blacklists and Whitelists
For administrative policy, the intention is to be cautious and conservative, emphasizing security over
ease of use. The assumption is that everything not specifically mentioned is denied. This approach,
referred to as the whitelist approach, is common in corporations concerned with security or legal issues
above access. Organizations that want to extend this concept to general Internet access select a default
proxy policy of deny as well.
In the second approach, the idea is that by default everything is allowed. Some requests might be
denied, but really that is the exception. This is known as blacklist policy because it requires specific
mention of anything that should be denied (blacklisted). Blacklist policy is used by organizations
where access is more important than security or legal responsibilities.
This second approach is used for cache transactions, but can also be common default proxy policy for
organizations such as Internet service providers.
Blacklists and whitelists are tactical approaches and are not mutually exclusive. The best overall policy
strategy is often to combine the two approaches. For example, starting from a default policy of deny,
one can use a whitelist approach to explicitly filter-in requests that ought to be served in general (such
as all requests originating from internal subnets, while leaving external requests subject to the default
DENY). Further policy layers can then apply more specific restrictions in a blacklist mode to filter-out
unwanted requests (such as those that fail to conform to content filtering policies).
Whitelisting and blacklisting can also be used not simply to allow or deny service, but also to subject
certain requests to further processing. For example, not every file type presents an equal risk of virus
infection or rogue executable content. One might choose to submit only certain file types (presumably
those known to harbor executable content) to a virus scanner (blacklist), or virus-scan all files except
for a whitelist of types (such as image files) that may be considered safe.

General Rules and Exceptions to a General Rule
When writing policy many organizations use general rules, and then define several exceptions to the
rule. Sometimes, you might find exceptions to the exceptions. Exceptions to the general rule can be
expressed either:


Through rule order within a layer



Through layer order within the policy.

47

Volume 11: Content Policy Language Guide

Using Rule Order to Define Exceptions
When the policy rules within a layer are evaluated, remember that evaluation is from the top down,
but the first rule that matches will end further evaluation of that layer. Therefore, the most specific
conditions, or exceptions, should be defined first. Within a layer, use the sequence of most-specific to
most-general policy.
The following example is an exception defined within a layer. A company wants access to payroll
information limited to Human Resources staff only. The administrator uses membership in the
HR_staff group to define the exception for HR staff, followed by the general policy:

; Blue Coat uses groups to identify HR staff, so authentication is required
authenticate(MyRealm)
define condition payroll_location
url=hr.my_company.com/payroll/
end
condition=payroll_location
allow group=HR_staff ; exception
deny ; general rule

This approach requires that the policy be in one layer, and because layer definitions cannot be split
across policy files, the rule and the exceptions must appear in the same file. That may not work in
cases where the rules and the exceptions are maintained by different groups.
However, this is the preferred technique, as it maintains all policy related to the payroll files in one
place. This approach can be used in either blacklist or whitelist models (see "Blacklists and Whitelists"
on page 47) and can be written so that no security holes are opened in error. The example above is a
whitelist model, with everything not explicitly mentioned left to the default rule of deny.

Using Layer Ordering to Define Exceptions
Since later layers override earlier layers, general rules can be written in one layer, with exceptions
written in following layers, put specific exceptions later in the file.
The Human Resources example could be rewritten as:

; Blue Coat uses groups to identify HR staff, so authentication is required
authenticate(MyRealm)
define condition payroll_location
url=hr.my_company.com/payroll/
end

condition=payroll_location deny ; general rule

condition=payroll_location allow group=HR_staff ; exception

Notice that in this approach, some repetition is required for the common condition between the layers.
In this example, the condition=payroll_location must be repeated. It is very important to keep the
exception from inadvertently allowing other restrictions to be undone by the use of allow.

48

Chapter 2: Managing Content Policy Language

As the layer definitions are independent, they can be installed in separate files, possibly with different
authors. Definitions, such as the payroll location condition, can be located in one file and referenced in
another. When linking rules to definitions in other files, file order is not important, but the order of
installation is. Definitions must be installed before policy that references them will compile. Keeping
definitions used across files in only one of the files, rather than spreading them out, will eliminate the
possibility of having changes rejected because of interlocking reference problems. Note that when
using this approach, exceptions must follow the general rule, and you must be aware of the policy file
evaluation order as currently configured. Changes to the policy file evaluation order must be managed
with great care.
Remember that properties maintain any setting unless overridden later in the file, so you could
implement general policy in early layers by setting a wide number of properties, and then use a later
layer to override selected properties.

Avoid Conflicting Actions
Although policy rules within a policy file can set the action property repeatedly, turning individual
actions on and off for the transaction being processed, the specific actions can conflict.


If an action-definition block contains two conflicting actions, a compile-time error results. This
conflict would happen if, for example, the action definition consisted of two
response.icap_service( ) actions.



If two different action definitions are executed and they contain conflicting actions, it is a run-time
error; a policy error is logged to the event log, and one action is arbitrarily chosen to execute.

The following describes the potential for conflict between various actions:


Two header modification actions will conflict if they modify the same header. Header
modification actions include the append( ), delete( ), delete_matching( ),
rewrite(header,...), and set(header,...) actions.



Two instant message text modification actions will conflict. Instant message text modification
actions include the append(im.message.text,...) and set(im.message.text,...) actions.



Two transform actions of the same type conflict.



Two rewrite( ) actions conflict.



Two response.icap_service( ) actions conflict.

Making Policy Definitive
You can make policy definitive two ways. The first is to put that policy into the file; that is, last in the
evaluation order. (Remember that the forward file is always the last policy file.) For example, suppose
that service was limited to the corporate users identifiable by subnet. Placing a rule such as:

client.address=!my_subnet deny

at the end of the Forward file ensures that no other policy overrides this restriction through accidental
use of allow. Although not usually used for this purpose, the fact that the forward file is always last,
and the order of the other three files is configurable, makes this the appropriate location for definitive
policy in some organizations.

49

Volume 11: Content Policy Language Guide

An alternate method has been provided for definitive denial. While a deny or an exception()
property can be overridden by a subsequent allow in later rules, CPL provides force_deny and
force_exception(). CPL does not offer force_allow, so while the error returned to the user may be
reset by subsequent force_deny or force_exception() gestures, the ultimate effect is that the
request is denied. Thus these properties provide definitive denial regardless of where they appear in
policy.

Best Practices


Express separate decisions in separate layers.
As policy grows and becomes more complex, maintenance becomes a significant issue.
Maintenance will be easier if the logic for each aspect of policy is separate and distinct.
Try to make policy decisions as independent as possible, and express each policy in one layer or
two adjacent layers.



Be consistent with the model.
Set the default proxy policy according to your policy model and then use blacklist or whitelist
approaches as appropriate.
The recommended approach is to begin with a default proxy policy of deny in configuration.
Allow requests in early layers and deny requests in later layers. Ensure that all layers that allow
requests precede any layers that deny requests. The following is a simple illustration of this
model:
define subnet corporate_subnet
10.10.12.0/24
end
; First, explicitly allow access to our users

ALLOW client.address=corporate_subnet
; Next, impose any authentication requirements

authenticate(corp_realm) ; all access must be authenticated
; And now begin to filter-out unwanted requests

DENY url.domain=forbidden.com
DENY category=(Gambling, Hacking, Chat)
; more layers…



Expose only what is necessary.
Often, it may be useful to keep the rule logic and the condition definitions separate so that the
rules can be maintained by one group, but the definitions by another. The rules may contain
exception details or other logic that should not be modified; however, the conditions, such as
affected groups or content, may change frequently. With careful separation of the rules and the
conditions, the rules can be expressed in the local policy file, and users unfamiliar with CPL can
update the condition definitions through the VPM.

50

Chapter 2: Managing Content Policy Language

When using this technique, installation order is important. Condition definitions must be
available before policy referencing those conditions will compile, so the conditions you want to
expose for general use must be defined in the VPM before they are referenced in the Local policy
file.

51

Volume 11: Content Policy Language Guide

52

Chapter 3: Condition Reference

A condition is an expression that yields true or false when evaluated. Conditions can appear in:


Policy rules.



Section and layer headers, as guards; for example,
[Rule] group=(“bankabc\hr” || “cn=humanresources,ou=groups,o=westernnational”)



define condition, define domain condition, and define url condition definition blocks.

Condition Syntax
A condition has the following form:
condition=pattern-expression

A condition is the name of a condition variable. It can be simple, such as url, or it can contain
sub-object specifiers and modifiers, as in url.path.case_sensitive or request.header.Cookie.A
condition cannot contain white space.
A pattern expression can be either:


A simple pattern, which is matched against the condition value.



A Boolean combination of simple patterns, or a parenthesized, comma-separated list of simple
patterns.

A pattern expression can be any of the following:


String: A string argument must be quoted if it contains whitespace or other special characters. An
example condition expression is category=”self help”.



Single argument: Conditions such as live= take only a single argument, in this case, yes or no.



Boolean expressions: Conditions such as server_url.scheme= can list one or more arguments
together with Boolean operators; for example, server_url.scheme=!http.



Integer or range of integers: Numeric conditions can use Boolean expressions and double periods
(..), meaning an inclusive numeric range. Numeric ranges cannot use whitespace. The minute=
condition is used to show examples of ranges:





minute=10..40—From 10 minutes to 40 minutes after the hour.



minute=10..—From 10 minutes after the hour to the end of the hour.



minute=..40—From the beginning of the hour to 40 minutes after the hour.



minute=40..10—From 40 minutes after the hour, to 10 minutes after the next hour.

Regular expressions: Some header-related conditions and two URL-related conditions take regular
expressions. For more information about writing regular expressions, see Appendix E: "Using
Regular Expressions" on page 423.

53

Volume 11: Content Policy Language Guide

The following is Backus-Naur Form (BNF) grammar:


condition ::= condition "=" expression



condition ::= identifier | identifier "." word



expression ::= term | list



list ::= "(" ((pattern ",")* pattern)? ")"



disjunction ::= conjunction | disjunction "||" conjunction



conjunction ::= term | conjunction "&&" term



term ::= pattern | "(" disjunction ")" | "!" term



pattern ::= word | 'string' | "string"



word ::= sequence of characters not including whitespace, & | ( ) < > [ ] ; ! =
" '



string ::= sequence of characters that may including whitespace, & | ( ) < > [ ] ;
! =. The characters " and ' may be enclosed within a string delimited by the
alternate delimiter.

Pattern Types
Different conditions support different pattern syntaxes.
A pattern for a boolean condition has one of the following forms:
boolean ::= yes | no | true | false | on | off

The pattern for a numeric condition can be either an integer or a range of integers. Numeric patterns
cannot contain white space.
condition=I

Test if condition == I.
condition=I..J

Test if condition >= I and condition <= J (where I <= J). For example, time=0900..1700 tests if
the time is between 9:00 and 17:00 inclusive.
condition=J..I

Test if condition >= J or condition <= I (where J > I). For example, minute=45..15 tests if the
minute of the hour is between 45 and 15 inclusive.
condition=I..

Test if condition >= I. For example, bitrate=56k.. tests if the bitrate is greater than or equal to
56000.
condition=..J

Test if condition <= J. For example, bitrate=..56k tests if the bitrate is less than or equal to
56000.
Some conditions have IP address patterns. This can be either a literal IP address, such as 1.2.3.4, or an
IP subnet pattern, such as 1.2.0.0/16, or a name defined by a define subnet statement.

54

Chapter 3: Condition Reference

Some conditions have regex patterns. This is a Perl 5 regular expression that matches a substring of the
condition value; it is not an anchored match unless an anchor is specified as part of the pattern.

Unavailable Conditions
Some conditions can be unavailable in some transactions. If a condition is unavailable, then any
condition containing that condition is false, regardless of the pattern expression. For example, if the
current transaction is not authenticated (that is, the authenticate property was set to no), then the user
condition is unavailable. This means that user=kevin and user=!kevin are both false.
A condition can be false either because the pattern does not match the condition value, or because the
condition is unavailable. Policy rule-tracing distinguishes these two cases, using miss for the former
and N/A for the latter.

Layer Type Restrictions
Each condition is restricted as to the types of layers in which it can be used. A direct use of a condition
in a forbidden layer results in a compile-time error. Indirect use of a condition in a forbidden layer (by
way of condition= and a condition definition) also results in a compile time error.

Global Restrictions
To allow suppression of DNS and RDNS lookups from policy, the following restrictions are supported.
These restrictions have the effect of assuming a no_lookup modifier for appropriate url, url.host,
and url.domain tests. The restrictions also apply to lookups performed by on-box content category
lookups. For more information on DNS and RDNS restrictions, see Chapter 6: "Definition Reference"
on page 349.
restrict dns
domain_list

Applies to all layers.

Applies to all
transactions.

end

If the domain specified in a URL matches any of
the domain patterns specified in domain_list,
no DNS lookup is performed for any
server_url=, server_url.address=,
server_url.domain=, or server_url.host=
test.
If a lookup is required to evaluate the condition,
the condition evaluates to false.

restrict rdns Applies to all layers.
subnet_list
end

Applies to all
transactions.

If the requested URL specifies the host in IP form,
no RDNS lookup is performed to match any
server_url=, server_url.domain=, or
server_url.host= condition.
If a lookup is required to evaluate the condition,
the condition evaluates to false.

Condition Reference
The remainder of this chapter lists the conditions and their accepted values. It also provides tips as to
where each condition can be used and examples of how to use them.

55

Volume 11: Content Policy Language Guide

admin.access=
Test the administrative access method required by the current administrative transaction.
If write access is required, then policy is evaluated with admin.access=WRITE to determine if the
administrator is allowed to modify the configuration. For example, administrative policy is evaluated
to determine if a CLI user is permitted to enter Enable mode, or when attempting to save changes
from the Management Console. If only read access is required, then policy is evaluated with
admin.access=READ to determine if the administrator is permitted to have read-only access.
Syntax
admin.access=READ|WRITE

Layer and Transaction Notes


Use in layers.



Applies to Administrative transactions.

Example
This example shows how administrative access can be controlled for two classes of users,
Read_only_admins and Full_admins. Note that, in cases where a user is in both groups, that user will
inherit the larger set of permissions.
define condition Full_admins
user=paul
group=operations
end
define condition Read_only_admins
user=george
group=help_desk
end

authenticate(my_realm)

ALLOW condition=Full_admins
ALLOW condition=Read_only_admins admin.access=READ
DENY

Notes

56



All administrative transactions will require either READ or WRITE access, therefore a condition
such as 'admin.access=(READ,WRITE)' is always true, and can be deleted without changing the
meaning of a CPL rule.



This trigger replaces the use of method=READ|WRITE in the layer.

Chapter 3: Condition Reference

attribute.name=
Tests if the current transaction is authenticated in a RADIUS or LDAP realm, and if the authenticated
user has the specified attribute with the specified value. This condition is unavailable if the current
transaction is not authenticated (that is, the authenticate property is set to no).
If you reference more than one realm in your policy, you may wish to disambiguate attribute tests by
combining them with a realm= test. This can reduce the number of extraneous queries to
authentication services for attribute information that does not pertain to that realm.
Syntax
attribute.name=value

where:


name is a RADIUS or LDAP attribute. The name attribute’s case-sensitivity depends on the
type of authentication realm.



RADIUS realm: The available attributes (see below) are always case-sensitive.



LDAP realm: Case-sensitivity depends on the realm definition in configuration.



value: An attribute value. For RADIUS, the values include:
Table 3.1: RADIUS Values
Callback-ID

Login-LAT-Port

Callback-Number

Login-LAT-Service

Filter-ID

Login-IP-Host

Framed-IP-Address

Login-TCP-Port

Framed-IP-Netmask

Port-Limit

Framed-MTU

Service-Type (the deprecated form of this value is ServiceType)

Framed-Pool

Session-Timeout

Framed-Protocol

Tunnel-Assignment-ID

Framed-Route

Tunnel-Medium-Type

Idle-Timeout

Tunnel-Private-Group-ID

Login-LAT-Group

Tunnel-Type

Login-LAT-Nod

Blue-Coat-Group

Layer and Transaction Notes


Use in , , and layers.
Note:

When used in the layer, this condition can evaluate to NULL (shown in a trace
as N/A) if no authenticated client exists. Rules containing these conditions can be
guarded by authenticated= to preserve normal logic.

57

Volume 11: Content Policy Language Guide



Applies to proxy and administrator transactions.



This condition cannot be combined with the authenticate() or socks.authenticate()
properties.

Example
; This example uses the value of the ContentBlocking attribute associated with a
; user to select which content categories to block. (SmartFilter 3 categories are
; used.)

authenticate(LDAPRealm)
exception(content_filter_denied)
attribute.ContentBlocking=Adult category=(Sex, Nudity, Mature, Obscene/Extreme)
attribute.ContentBlocking=Violence category=(Criminal_Skills, Hate_Speech)
...
; This example uses the attribute property to determine permissions associated with
; RADIUS authentication.
define condition ProxyAllowed
attribute.ServiceType=(2,6,7,8)
end

authenticate(RADIUSRealm)
; This rule would restrict non-authorized users.

deny condition=!ProxyAllowed
; This rule would serve to override a previous denial and grant access to authorized
; users

allow condition=ProxyAllowed

See Also


Conditions: authenticated=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.domain=, user.x509.issuer=,
user.x509.serialNumber=, user.x509.subject=



58

Properties: authenticate( ), authenticate.force( ), check_authorization( ),
exception( ), socks.authenticate( ), socks.authenticate.force( )

Chapter 3: Condition Reference

authenticated=
True if authentication was requested and the credentials could be verified; otherwise, false.
Syntax
authenticated=(yes|no)

Layer and Transaction Notes


Use in , , and layers.



Applies to proxy and administrator transactions.



This condition cannot be combined with the authenticate( ) property.

Example
; In this example, only users authenticated in any domain are granted access to a
; specific site.

client.address=10.10.10.0/24 authenticate(LDAPRealm)
client.address=10.10.11.0/24 authenticate(NTLMRealm)
client.address=10.10.12.0/24 authenticate(LocalRealm)
; anyone else is unauthenticated

; This rule would restrict unauthorized users. Use this when overriding previously
; granted access.
server_url.domain=xyz.com
deny authenticated=no

; This rule would grant access and would be used to override a previous denial.
; It assumes a deny in a previous layer.
server_url.domain=xyz.com
allow authenticated=yes

See Also


Conditions: attribute.name=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.domain=



Properties: authenticate( ), authenticate.force( ), check_authorization(),
socks.authenticate( ), socks.authenticate.force( )

59

Volume 11: Content Policy Language Guide

bitrate=
Tests if a streaming transaction requests bandwidth within the specified range or an exact match.
When providing a range, either value can be left empty, implying either no lower or no upper limit on
the test. Bitrate can change dynamically during a transaction, so this policy is re-evaluated for each
change. Note that the numeric pattern used to test the bitrate= condition can contain no whitespace.
This condition is only available if the current transaction is a Real Media or Windows Media
transaction.
Syntax
bitrate={ [lower]..[upper]|exact_rate }

where:

Note:



lower—Lower end of bandwidth range. Specify using an integer, in bits, kilobits (1000x),
or megabits (1,000,000x), as follows: integer | integerk | integerm. If left blank,
there is no lower limit on the test.



upper—Upper end of bandwidth range. Specify using an integer, in bits, kilobits, or
megabits, as follows: integer | integerk | integerm. If left blank, there is no upper
limit on the test.



exact_rate—Exact bandwidth to test. Specify using an integer, in bits, kilobits, or
megabits, as follows: integer | integerk | integerm.

To test an inverted range, the following shorthand expression is available. Instead of writing
bitrate=(..28.8k|56k..) to indicate bit rates from 0 to 28.8k and from 56k up, the policy
language recognizes bitrate=56k..28.8k as equivalent.

Layer and Transaction Notes


Use in and layers.



Applies to streaming transactions.



This condition can be used with the max_bitrate( ) property.

Example
; Deny service for bit rates above 56k.
deny bitrate=!0..56k
; This example allows members of the Sales group access to streams up to 2 megabits.
; All others are limited to 56K bit streams.

authenticate(NTLMRealm)

; deny sales access to streams over 2M bits
deny group=sales bitrate=!0..2m
; deny non-sales access to streams over 56K bits
deny group=!sales bitrate=!0..56k..

60

Chapter 3: Condition Reference

; In this form of the rule, we assume that the users are by default denied, and we
; are overriding this to grant access to authorized users.
; Use this layer to override a deny in a previous layer
; Grant everybody access to streams up to 56K, sales group up to 2M
allow bitrate=..56K
allow group=sales bitrate=..2M

See Also


Conditions: live=, streaming.client=, streaming.content=



Properties: access_server( ), max_bitrate( ), streaming.transport( )

61

Volume 11: Content Policy Language Guide

category=
Tests the content categories of the requested URL as assigned by policy definitions or an installed
content filter database.
Content categories can be assigned to URLs by policy (see "define category" on page 354), by a local
database you maintain, or by a third-party database. Refer to Volume 8: Managing Content for
information on configuring local databases or third-party databases.
A URL that is not categorized is assigned the category none.
If a content filter provider is selected in configuration, but an error occurs in determining the category,
the URL is assigned the category unavailable (in addition to any categories assigned directly by
policy). This can be the result of either a missing database or license expiry. An additional category of
unlicensed is assigned in the latter case.
A URL may have been assigned a list of categories. The category= condition is true if it matches any
of the categories assigned to the URL.
You cannot use category= to test the category assigned by off-box content filtering services. These
services have their own policy that must be managed separately.
Note:

If category=unlicensed is true, category=unavailable is true.

Syntax
category={ none|unlicensed|unavailable|category_name1, category_name2, ...}

where category_name1, category_name2, ... represent category names defined by policy
or the selected content filter provider. The list of currently valid category names is available
both through the Management Console and CLI.
Layer and Transaction Notes


Use in , , and layers.



This condition can be combined with the authenticate( ) property, except when a Microsoft
Media Streaming (MMS) over HTTP transaction is being evaluated.



Applies to proxy transactions.

Example
; This example denies requests for games or sports related content.

; Tests true if the request is in one of these categories.
category=(Sports, Games) exception(content_filter_denied)
category=unavailable exception(content_filter_unavailable); Fail closed

See Also


62

Properties: exception( ), request.filter_service( )

Chapter 3: Condition Reference

client.address=
Tests the IP address of the client. The expression can include an IP address or subnet or the label of a
subnet definition block.
Important: If a user is explicitly proxied to the ProxySG, layer policy applies even if the
URL destination is an administrative URL for the ProxySG itself, and should therefore
also be covered under layer policy. However, when the
client.address= condition is used in an layer, clients explicitly proxied to the
ProxySG appear to have their client IP address set to the IP address of the ProxySG.
Syntax
client.address=ip_address|subnet_label

where:


ip_address—Client IP address or subnet specification; for example, 10.25.198.0/24.



subnet_label—Label of a subnet definition block that binds a number of IP addresses or

subnets.
Layer and Transaction Notes


Can be used in all layers.



Unavailable if the transaction is not associated with a client.

Example
; Blacklisted workstation.
client.address=10.25.198.0 deny

; This example uses the client address to select the authentication realm for
; administration of the ProxySG.

client.address=10.25.198.0/24 authenticate(LDAPRealm)
client.address=10.25.199.0/24 authenticate(NTLMRealm)
authenticate(LocalRealm) ; Everyone else

See Also


Conditions: client.protocol=, proxy.address=, proxy.card=, proxy.port=



Definitions: define subnet

63

Volume 11: Content Policy Language Guide

client.connection.dscp=
Test the client-side inbound DSCP value.
Syntax
client.connection.dscp = dscp_value

where dscp_value is 0..63 | af11 | af12 | af13 | af21 | af22 | af23 | af31 | af32 |
af33 | af41 | af42 | af43 | best-effort | cs1 | cs2 | cs3 | cs4 | cs5 | cs6 | cs7 |
ef

Layer and Transaction Notes


Valid in , , layers.



Applies to all transactions.

Example
The first QoS policy rule tests the client inbound QoS/DSCP value against 50, and deny if it matches;
the second QoS policy rule tests the client inbound QoS/DSCP value against 50, and deny if it
matches.

deny client.connection.dscp = 50

deny client.connection.dscp = best-effort

64

Chapter 3: Condition Reference

client.connection.negotiated_cipher=
Test the cipher suite negotiated with a securely connected client.
Syntax
client.connection.negotiated_cipher=cipher-suite

where cipher-suite is one of:
none
RC4-MD5
RC4-SHA
DES-CBC3-SHA
DES-CBC3-MD5
RC2-CBC-MD5
RC4-64-MD5
DES-CBC-SHA
DES-CBC-MD5
EXP1024-RC4-MD5
EXP1024-RC4-SHA
EXP1024-RC2-CBC-MD5
EXP1024-DES-CBC-SHA
EXP-RC4-MD5
EXP-RC2-CBC-MD5
EXP-DES-CBC-SHA

Layer and Transaction Notes


Use in the layer.



Applies to proxy transactions.

Example
This example implements the following policies:
1.

DENY clients that are not using one of the EXP1024 suites .

2.

Access log clients that are not using secure connections in “unsecure_log1.”
; 1

ALLOW client.connection.negotiated_cipher= \
(EXP1024-RC4-MD5|| \
EXP1024-RC4-SHA|| \
EXP1024-RC2-CBC-MD5|| \
EXP1024-DES-CBC-SHA)
DENY
; 2

client.connection.negotiated_cipher=none access_log[unsecure_log1](yes)

65

Volume 11: Content Policy Language Guide

client.connection.negotiated_cipher.strength=
Test the cipher strength negotiated with a securely connected client.
Syntax
client.connection.negotiated_cipher.strength=none|low|medium|high

Layer and Transaction Notes


Use in the layer.



Applies to proxy transactions.

Example
This example implements the following policies:
1.

DENY clients that do not have at least a medium cipher strength.

2.

ALLOW clients using FTP irrespective of their cipher strength since FTP clients do not have a
means to encrypt the traffic.

; 1
ALLOW client.connection.negotiated_cipher.strength=(medium||high)
; 2
ALLOW url.scheme=ftp
DENY

Notes
OpenSSL defines the meanings of “high,” “medium,” and “low.” Refer to OpenSSL ciphers
(http://www.openssl.org/docs/apps/ciphers.html) for more information.
Currently the definitions are:

66



high - Cipher suites with key lengths larger than 128 bits.



medium - Cipher suites with key lengths of 128 bits.



low - Cipher suites using 64 or 56 bit encryption algorithms but excluding export cipher suites.

Chapter 3: Condition Reference

client.connection.negotiated_ssl_version=
Test the SSL version negotiated with a securely connected client.
Syntax
client.connection.negotiated_ssl_version=SSLV2|SSLV3|TLSV1

Layer and Transaction Notes


Use in layers.



Applies to proxy transactions.

Example

client.connection.negotiated_ssl_version=SSLV3

67

Volume 11: Content Policy Language Guide

client.host=
Test the hostname of the client (obtained through RDNS).
Syntax
client.host=hostname
client.host=domain-suffix
client.host.exact=string
client.host.prefix=string
client.host.substring=string
client.host.suffix=string
client.host.regex=regular_expression

Layer and Transaction Notes


Use in , , , and layers.



Applies to all proxy transactions, excluding DNS-proxy transactions.

Example
This example implements the following policies:
1.

DENY all users that do not have an RDNS name that ends with bluecoat.com

2.

DENY all users that have test in their RDNS name

3.

DENY all users that have an RDNS name that ends with example.bluecoat.com. This is meant to
include bexample.bluecoat.com and b.example.bluecoat.com.

4.

DENY all users that have numbers in their RDNS name.

5.

DENY all users that have an RDNS name that begins with fnord.

ALLOW

; 1
DENY client.host=!".bluecoat.com"
; 2
DENY client.host.substring="test"
; 3
DENY client.host.suffix="example.bluecoat.com"
; 4
DENY client.host.regex="[0-9]*"
; 5
DENY client.host.prefix="fnord."

68

Chapter 3: Condition Reference

client.host.has_name=
Test the status of the RDNS performed to determine client.host.
Syntax
client.host.has_name=yes|no|restricted|refused|nxdomain|error

Layer and Transaction Notes


Use in , , , and layers.



Applies to All proxy transactions, excluding DNS-proxy transactions

Example
This example implements the following policies:
1.

DENY all users from subnetA if their RDNS name could not be resolved

2.

DENY all users from subnetB if they have no RDNS name, but allow them if their RDNS name
lookup failed because of a DNS lookup error. The inclusion of the client's address in an RDNS
restriction is a lookup error.
define subnet subnetA
10.10.10.0/24
end
define subnet subnetB
10.9.9.0/24
end

DENY

; 1
ALLOW client.address=subnetA client.host.has_name=yes
; 2 -- for users in 'subnetB' nxdomain is the only error we
; specifically prevent
ALLOW client.address=subnetB client.host.has_name=!nxdomain

69

Volume 11: Content Policy Language Guide

client.protocol=
Test the protocol used between the client and the ProxySG.
Syntax
client.protocol=http | https | ftp | tcp | socks | mms | rtsp | icp | aol-im |
msn-im | yahoo-im | dns |telnet | epmapper | ssl | dns

Notes


tcp specifies a tunneled transaction



client.protocol=dns is valid in the layer only.

Layer and Transaction Notes


Use in , , , and layers.



Applies to all transactions.



Tests false if the transaction is not associated with a client.

See Also


70

Conditions: client.address=, proxy.address=, proxy.card=, proxy.port=

Chapter 3: Condition Reference

condition=
Tests if the specified defined condition is true.
Syntax
condition=condition_label

where condition_label is the label of a custom condition as defined in a define condition,
define url.domain condition, or define url condition definition block.
Layer and Transaction Notes


Use in all layers.



The defined conditions that are referenced may have usage restrictions, as they must be evaluated
in the layer from which they are referenced.

Example
; Deny access to client 1.2.3.4 for any http request through proxy port 8080.
define condition qa
client.address=1.2.3.4 proxy.port=8080
end

condition=qa client.protocol=http deny
; Restrict access to internal sites to specific groups,
; using nested conditions.
define condition restricted_sites
url.domain=internal.my_co.com
end
define condition has_full_access
group=admin,execs,managers
end
define condition forbidden
condition=restricted_sites condition=!has_full_acesss
end

authenticate(My_realm)

condition=forbidden deny

; Example of a define url condition.
define url condition test
http://www.x.com time=0800..1000
http://www.y.com month=1
http://www.z.com hour=9..10
end

condition=test deny

71

Volume 11: Content Policy Language Guide

; Example of a define domain-suffix (or domain) condition
define url.domain condition test
com ; Matches all domains ending in .com
end

condition=test deny

See Also

72



Definitions: define condition, define url.domain condition, define url condition



Properties: action.action_label( )

Chapter 3: Condition Reference

console_access=
Tests if the current request is destined for the layer. This test can be used to distinguish access
to the management console by administrators who are explicitly proxied to the ProxySG being
administered. The test can be used to guard transforms that should not apply to the Management
Console. This cannot be used to test Telnet sessions, as they do not go through a layer.
Syntax
console_access=yes|no

Layer and Transaction Notes


Use in , , and layers.



Applies to HTTP transactions.

See Also


Conditions: admin.access=

73

Volume 11: Content Policy Language Guide

content_admin=
The content_admin= condition has been deprecated. For more information, see
"content_management" on page 75.

74

Chapter 3: Condition Reference

content_management
Tests if the current request is a content management transaction.
Replaces: content_admin=yes|no
Syntax
content_management=yes|no

Layer and Transaction Notes


Use in and layers.



Applies to all transactions.

See Also


Conditions: category=, ftp.method=, http.method=, http.x_method=, server_url=



Properties: http.request.version( ), http.response.version( )

75

Volume 11: Content Policy Language Guide

date[.utc]=
Tests true if the current time is within the startdate..enddate range, inclusive. The comparison is
made against local time unless the .utc qualifier is specified.
syntax
date[.utc]=YYYYMMDD..YYYYMMDD
date[.utc]=MMDD..MMDD

Layer and Transaction Notes


Using time-related conditions to control caching behavior in a layer may cause thrashing
of the cached objects.

See Also


76

Conditions: day=, hour=, minute=, month=, time=, weekday=, year=

Chapter 3: Condition Reference

day=
Tests if the day of the month is in the specified range or an exact match. The ProxySG appliance’s
configured date and time zone are used to determine the current day of the month. To specify the UTC
time zone, use the form day.utc=. Note that the numeric pattern used to test the day condition can
contain no whitespace.
Syntax
day[.utc]={[first_day]..[last_day]|exact_day}

where:


first_day—An integer from 1 to 31, indicating the first day of the month that will test

true. If left blank, day 1 is assumed.


last_day—An integer from 1 to 31, indicating the last day of the month that will test true.

If left blank, day 31 is assumed.

Note:

exact_day—An integer from 1 to 31, indicating the day of the month that will test true.

To test against an inverted range, such as days early and late in the month, the following
shorthand expression is available. While day=(..5|25..) specifies the first 5 days of the
month and last few days of the month, the policy language also recognizes day=25..5 as the
same.

Layer and Transaction Notes


Use in all layers.



Using time-related conditions to control caching behavior in a layer may cause thrashing
of the cached objects.

Example
; Test for New Year’s Day (January 1).
day=1 month=1
; This policy allows access to a special event site only during the days of
; the event.
; This form of the rule restricts access during non-event times.
url=http://www.xyz.com/special_event
; The next line matches, but does nothing if allow is the default
; year=2003 month=7 day=23..25 ; During the event
; deny Any other time
; This form of the rule assumes access is generally denied, and grants access during
; the special event.
url=http://www.xyz.com/special_event
allow year=2003 month=7 day=23..25 ; During the event

See Also


Conditions: date[.utc]=, hour=, minute=, month=, time=, weekday=, year=

77

Volume 11: Content Policy Language Guide

dns.client_transport=
Test the transport protocol of a proxied DNS query
Syntax
dns.client_transport=tcp|udp

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions

Example
This example implements the following policy:
1.

Refuse all DNS queries that use the TCP protocol

2.

Unless the query is coming from the subnet 10.9.8.0/24
; 1,2

client.address=!10.9.8.0/24 dns.client_transport=tcp dns.respond(refused)

78

Chapter 3: Condition Reference

dns.request.address=
Test the address of a PTR type DNS query (a.k.a. RDNS).
Syntax
dns.request.address=ip_address|subnet|subnet_label

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions.

Example
This example implements the following policies:
1.

Refuse all DNS PTR queries for addresses in the 10.10.0.0/16 subnet

2.

Respond with “host1.example.com” to DNS PTR queries for 10.9.8.1

3.

Respond with “host2.example.com” to DNS PTR queries for 10.9.8.2

; 1
dns.request.address=10.10.0.0/16 dns.respond(refused)
; 2
dns.request.address=10.9.8.1 dns.respond.ptr("host1.example.com")
; 3
dns.request.address=10.9.8.2 dns.respond.ptr("host2.example.com")

79

Volume 11: Content Policy Language Guide

dns.request.category=
Test the URL category of either the DNS queried hostname or IP address
Syntax
dns.request.category=none|unlicensed|unavailable|category_name1,
category_name2, ...

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions.

Example
This example implements the following policies:
1.

Refuse all DNS type “A” queries from the Engineering subnet for category
“HR_intranet_servers.”

2.

Refuse all DNS type “A” queries from the HR subnet for category
“Engineering_intranet_servers.”
define category HR_intranet_servers
hr1.example.com
hr2.example.com
end
define category Engineering_intranet_servers
eng1.example.com
engweb.example.com
end
define subnet Engineering
10.10.0.0/16
end
define subnet HR
10.9.0.0/16
end
dns.request.type=A
; 1
client.address=Engineering \
dns.request.category=HR_intranet_servers dns.respond(refused)
; 2
client.address=HR \
dns.request.category=Engineering_intranet_servers dns.respond(refused)

Notes


80

Additional RDNS/DNS lookups are not performed in order to categorize the DNS query. This
means that a Websense list cannot be used to categorize DNS queries since it relies on those
lookups for categorization.

Chapter 3: Condition Reference

dns.request.class=
Test the QCLASS of the DNS query
Syntax
dns.request.class=any|ch|hs|in|none|numeric range from 0 to 65535

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions.

Example
This example implements the following policy:


Refuse all DNS traffic that does not use the QCLASS “IN“

dns.request.class=!IN dns.respond(refused)

81

Volume 11: Content Policy Language Guide

dns.request.name=
Test the QNAME in the question section of the DNS query.
Syntax
dns.request.name=hostname
dns.request.name=domain-suffix
dns.request.name.exact=string
dns.request.name.prefix=string
dns.request.name.substring=string
dns.request.name.suffix=string
dns.request.name.regex=regular_expression

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions.

Example
This example implements the following policies:
1.

Refuse all queries for hostnames that end with “example.com.”

2.

Permit queries for “host1.example.com.”
; 1

dns.request.name=.example.com dns.respond(refused)
; 2

dns.request.name=host1.example.com dns.respond(auto)

82

Chapter 3: Condition Reference

dns.request.opcode=
Test the OPCODE in the header of the DNS query.
Syntax
dns.request.opcode=query|status|notify|update|numeric range from 0 to 15

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions

Example
This example implements the following policy:


Refuse all DNS traffic that does not use the OPCODE “QUERY.”

dns.request.opcode=!QUERY dns.respond(refused)

83

Volume 11: Content Policy Language Guide

dns.request.type=
Test the QTYPE of the DNS query.
Syntax
dns.request.type=dns-qtype|numeric range from 0 to 65535

where dns-qtype is one of:
A

NS

MD

MF

CNAME

SOA

MB

MG

MR

NULL

WKS

PTR

HINFO

MINFO

MX

TXT

RP

AFSDB

X25

ISDN

RT

NSAP

NSAP-PTR

SIG

KEY

PX

GPOS

AAAA

LOC

NXT

EID

NIMLOC

SRV

ATMA

NAPTR

KX

CERT

A6

DNAME

SINK

OPT

APL

DS

SSHFP

RRSIG

NSEC

DNSKEY

UINFO

UID

GID

UNSPEC

TKEY

TSIG

IXFR

AXFR

MAILB

MAILA

ALL

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions.

Example

dns.request.type=CNAME

84

Chapter 3: Condition Reference

dns.response.a=
Test the addresses from the A RRs in the DNS response
Syntax
dns.response.a=ip_address|subnet|subnet_label

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions.

Example
This example implements the following policy:


If the response address in the DNS response is 10.9.8.7 change it to 10.10.10.10

dns.response.a=10.9.8.7 dns.respond.a(10.10.10.10)

85

Volume 11: Content Policy Language Guide

dns.response.cname=
Test the string values from the CNAME RRs in the DNS response.
Syntax
dns.response.cname=hostname
dns.response.cname=domain-suffix
dns.response.cname.exact=string
dns.response.cname.prefix=string
dns.response.cname.substring=string
dns.response.cname.suffix=string
dns.response.cname.regex=regular_expression

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions.

Example
This example implements the following policies:
1.

Refuse all DNS queries that have “.example.com” in any of the CNAME RRs.

2.

Permit “host1.example.com.”
; 1

dns.response.cname=.example.com dns.respond(refused)
; 2

dns.response.cname=host1.example.com dns.respond(auto)

86

Chapter 3: Condition Reference

dns.response.code=
Test the numeric response code of the proxied DNS query's response
Syntax
dns.response.code=noerror|formerr|servfail|nxdomain|notimp|refused|yxdomain|yxrr
set|nxrrset|notauth|notzone|numeric range from 0 to 15

Layer and Transaction Notes


Use in layers.



Applies to DNS-proxy transactions.

Example
This example implements the following policy:


We have a DNS server that routinely responds with yxdomain, but some of our client machines do
not handle that response code gracefully. Converting the yxdomain response to nxdomain seems to
fix the problem.

e-Highlighter

Click to send permalink to address bar, or right-click to copy permalink.

Un-highlight all Un-highlight selectionu Highlight selectionh