Professional Documents
Culture Documents
SG™ Appliance
Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
ii
Third Party Copyright Notices
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
Blue Coat Systems, Inc. utilizes third party software from various sources. Portions of this software are copyrighted by their respective owners as indicated in
the copyright notices below.
The following lists the copyright notices for:
BPF
Copyright (c) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996
The Regents of the University of California. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that: (1) source code distributions retain the above
copyright notice and this paragraph in its entirety, (2) distributions including binary code include the above copyright notice and this paragraph in its entirety
in the documentation or other materials provided with the distribution, and (3) all advertising materials mentioning features or use of this software display
the following acknowledgement:
This product includes software developed by the University of California, Lawrence Berkeley Laboratory and its contributors.
Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific
prior written permission. THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
DES
Software DES functions written 12 Dec 1986 by Phil Karn, KA9Q; large sections adapted from the 1977 public-domain program by Jim Gillogly.
EXPAT
Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the
Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Finjan Software
Copyright (c) 2003 Finjan Software, Inc. All rights reserved.
Flowerfire
Copyright (c) 1996-2002 Greg Ferrar
ISODE
ISODE 8.0 NOTICE
Acquisition, use, and distribution of this module and related materials are subject to the restrictions of a license agreement. Consult the Preface in the User's
Manual for the full terms of this agreement.
4BSD/ISODE SMP NOTICE
Acquisition, use, and distribution of this module and related materials are subject to the restrictions given in the file SMP-READ-ME.
iii
Blue Coat
UNIX is a registered trademark in the US and other countries, licensed exclusively through X/Open Company Ltd.
MD5
RSA Data Security, Inc. MD5 Message-Digest Algorithm
Copyright (c) 1991-2, RSA Data Security, Inc. Created 1991. All rights reserved.
License to copy and use this software is granted provided that it is identified as the "RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material
mentioning or referencing this software or this function.
License is also granted to make and use derivative works provided that such works are identified as "derived from the RSA Data Security, Inc. MD5
Message-Digest Algorithm" in all material mentioning or referencing the derived work.
RSA Data Security, Inc. makes no representations concerning either the merchantability of this software or the suitability of this software for any particular
purpose. It is provided "as is" without express or implied warranty of any kind.
THE BEER-WARE LICENSE" (Revision 42):
<phk@FreeBSD.org <mailto:phk@FreeBSD.org>> wrote this file. As long as you retain this notice you can do whatever you want with this stuff. If we meet
some day, and you think this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp
Microsoft Windows Media Streaming
Copyright (c) 2003 Microsoft Corporation. All rights reserved.
Novell and eDirectory are [either] registered trademarks [or] trademarks of Novell, Inc. in the United States and other countries.
LDAPSDK.DLL Copyright (c) 2006 Novell, Inc. All rights reserved.
LDAPSSL.DLL Copyright (c) 2006 Novell, Inc. All rights reserved.
LDAPX.DLL Copyright (c) 2006 Novell, Inc. All rights reserved.
The following are copyrights and licenses included as part of Novell's LDAP Libraries for C:
HSpencer
Copyright 1992, 1993, 1994 Henry Spencer. All rights reserved.
This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California.
Permission is granted to anyone to use this software for any purpose on any computer system, and to alter it and redistribute it, subject
to the following restrictions:
1. The author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from flaws in it.
2. The origin of this software must not be misrepresented, either by explicit claim or by omission. Since few users ever read sources, credits must appear in
the documentation.
3. Altered versions must be plainly marked as such, and must not be misrepresented as being the original software. Since few users ever read sources, credits
must appear in the documentation.
4. This notice may not be removed or altered.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Copyright (c) 1994
The Regents of the University of California. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the following acknowledgement:
This product includes software developed by the University of California, Berkeley and its contributors.
4. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
@(#)COPYRIGHT 8.1 (Berkeley) 3/16/94
OpenLDAP
Copyright 1998,1999 The OpenLDAP Foundation, Redwood City, California, USA
All rights reserved.
Redistribution and use in source and binary forms are permitted only as authorized by the OpenLDAP Public License. A copy of this license is available at
http://www.OpenLDAP.org/license.html or in file LICENSE in the top-level directory of the distribution.
Individual files and/or contributed packages may be copyright by other parties and use subject to additional restrictions.
This work is derived from the University of Michigan LDAP v3.3 distribution. Information concerning is available at
http://www.umich.edu/~dirsvcs/ldap/ldap.html.
iv
Copyrights
v
Blue Coat
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson
(tjh@cryptsoft.com).
Original SSLeay License
-----------------------
Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
All rights reserved.
This package is an SSL implementation written by Eric Young (eay@cryptsoft.com). The implementation was written so as to conform with Netscapes SSL.
This library is free for commercial and non-commercial use as long as the following conditions are aheared to. The following conditions apply to all code
found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution is covered
by the same copyright terms except that the holder is Tim Hudson (tjh@cryptsoft.com).
Copyright remains Eric Young's, and as such any Copyright notices in the code are not to be removed. If this package is used in a product, Eric Young should
be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation (online
or textual) provided with the package.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the following acknowledgement:
“This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)"
The word 'cryptographic' can be left out if the rouines from the library being used are not cryptographic related :-).
4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement:
"This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
The licence and distribution terms for any publically available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and
put under another distribution licence [including the GNU Public Licence.]
[end of copyrights and licenses for Novell's LDAP Libraries for C]
OpenLDAP
Copyright (c) 1999-2001 The OpenLDAP Foundation, Redwood City, California, USA. All Rights Reserved. Permission to copy and distribute verbatim
copies of this document is granted.
http://www.openldap.org/software/release/license.html
The OpenLDAP Public License Version 2.7, 7 September 2001
Redistribution and use of this software and associated documentation ("Software"), with or without modification, are permitted provided that the following
conditions are met:
1. Redistributions of source code must retain copyright statements and notices,
2. Redistributions in binary form must reproduce applicable copyright statements and notices, this list of conditions, and the following disclaimer in the
documentation and/or other materials provided with the distribution, and
3. Redistributions must contain a verbatim copy of this document.
The OpenLDAP Foundation may revise this license from time to time. Each revision is distinguished by a version number. You may use this Software under
terms of this license revision or under the terms of any subsequent revision of the license.
THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OPENLDAP FOUNDATION, ITS CONTRIBUTORS, OR THE AUTHOR(S) OR OWNER(S) OF
THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The names of the authors and copyright holders must not be used in advertising or otherwise to promote the sale, use or other dealing in this Software
without specific, written prior permission. Title to copyright in this Software shall at all times remain with copyright holders.
OpenLDAP is a registered trademark of the OpenLDAP Foundation.
OpenSSH
Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland. All rights reserved
This file is part of the OpenSSH software.
The licences which components of this software fall under are as follows. First, we will summarize and say that all components are under a BSD licence, or a
licence more free than that.
OpenSSH contains no GPL code.
vi
Copyrights
1) As far as I am concerned, the code I have written for this software can be used freely for any purpose. Any derived versions of this software must be clearly
marked as such, and if the derived work is incompatible with the protocol description in the RFC file, it must be called by a name other than "ssh" or "Secure
Shell".
[Tatu continues]
However, I am not implying to give any licenses to any patents or copyrights held by third parties, and the software includes parts that are not under my
direct control. As far as I know, all included source code is used in accordance with the relevant license agreements and can be used freely for any purpose
(the GNU license being the most restrictive); see below for details.
[However, none of that term is relevant at this point in time. All of these restrictively licenced software components which he talks about have been removed
from OpenSSH, i.e.,
- RSA is no longer included, found in the OpenSSL library
- IDEA is no longer included, its use is deprecated
- DES is now external, in the OpenSSL library
- GMP is no longer used, and instead we call BN code from OpenSSL
- Zlib is now external, in a library
- The make-ssh-known-hosts script is no longer included
- TSS has been removed
- MD5 is now external, in the OpenSSL library
- RC4 support has been replaced with ARC4 support from OpenSSL
- Blowfish is now external, in the OpenSSL library
[The licence continues]
Note that any information and cryptographic algorithms used in this software are publicly available on the Internet and at any major bookstore, scientific
library, and patent office worldwide. More information can be found e.g. at "http://www.cs.hut.fi/crypto".
The legal status of this program is some combination of all these permissions and restrictions. Use only at your own responsibility. You will be responsible for
any legal consequences yourself; I am not making any claims whether possessing or using this is legal or not in your country, and I am not taking any
responsibility on your behalf.
NO WARRANTY
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER
OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
2) The 32-bit CRC compensation attack detector in deattack.c was contributed by CORE SDI S.A. under a BSD-style license.
Cryptographic attack detector for ssh - source code
Copyright (c) 1998 CORE SDI S.A., Buenos Aires, Argentina. All rights reserved. Redistribution and use in source and binary forms, with or without
modification, are permitted provided that this copyright notice is retained. THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES ARE DISCLAIMED. IN NO EVENT SHALL CORE SDI S.A. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR MISUSE OF THIS SOFTWARE.
Ariel Futoransky <futo@core-sdi.com> <http://www.core-sdi.com>
3) ssh-keygen was contributed by David Mazieres under a BSD-style license.
Copyright 1995, 1996 by David Mazieres <dm@lcs.mit.edu>. Modification and redistribution in source and binary forms is permitted provided that due credit
is given to the author and the OpenBSD project by leaving this copyright notice intact.
4) The Rijndael implementation by Vincent Rijmen, Antoon Bosselaers and Paulo Barreto is in the public domain and distributed with the following license:
@version 3.0 (December 2000)
Optimised ANSI C code for the Rijndael cipher (now AES)
@author Vincent Rijmen <vincent.rijmen@esat.kuleuven.ac.be>
@author Antoon Bosselaers <antoon.bosselaers@esat.kuleuven.ac.be>
@author Paulo Barreto <paulo.barreto@terra.com.br>
This code is hereby placed in the public domain.
THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
vii
Blue Coat
5) One component of the ssh source code is under a 3-clause BSD license, held by the University of California, since we pulled these parts from original
Berkeley code.
Copyright (c) 1983, 1990, 1992, 1993, 1995
The Regents of the University of California. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
6) Remaining components of the software are provided under a standard 2-term BSD licence with the following names as copyright holders:
Markus Friedl
Theo de Raadt
Niels Provos
Dug Song
Aaron Campbell
Damien Miller
Kevin Steves
Daniel Kouril
Wesley Griffin
Per Allansson
Nils Nordman
Simon Wilkinson
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
OpenSSL
Copyright (c) 1995-1998 Eric Young (eay@cryptsoft.com). All rights reserved.
http://www.openssl.org/about/
http://www.openssl.org/about/
OpenSSL is based on the excellent SSLeay library developed by Eric A. Young <mailto:eay@cryptsoft.com> and Tim J. Hudson <mailto:tjh@cryptsoft.com>.
The OpenSSL toolkit is licensed under a Apache-style license which basically means that you are free to get and use it for commercial and non-commercial
purposes.
This package is an SSL implementation written by Eric Young (eay@cryptsoft.com). The implementation was written so as to conform with Netscapes SSL.
This library is free for commercial and non-commercial use as long as the following conditions are adhered to. The following conditions apply to all code
found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution is covered
by the same copyright terms except that the holder is Tim Hudson (tjh@cryptsoft.com).
Copyright remains Eric Young's, and as such any Copyright notices in the code are not to be removed. If this package is used in a product, Eric Young should
be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation (online
or textual) provided with the package.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
viii
Copyrights
3. All advertising materials mentioning features or use of this software must display the following acknowledgement: "This product includes cryptographic
software written by Eric Young (eay@cryptsoft.com)" The word 'cryptographic' can be left out if the routines from the library being used are not cryptographic
related :-).
4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement: "This
product includes software written by Tim Hudson (tjh@cryptsoft.com)"
THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
The license and distribution terms for any publicly available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and
put under another distribution license [including the GNU Public License.]
Copyright (c) 1998-2002 The OpenSSL Project. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the following acknowledgment:
"This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written
permission. For written permission, please contact openssl-core@openssl.org.
5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the
OpenSSL Project.
6. Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes software developed by the OpenSSL Project for
use in the OpenSSL Toolkit (http://www.openssl.org/)"
THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson
(tjh@cryptsoft.com).
PCRE
Copyright (c) 1997-2001 University of Cambridge
University of Cambridge Computing Service, Cambridge, England. Phone: +44 1223 334714.
Written by: Philip Hazel <ph10@cam.ac.uk>
Permission is granted to anyone to use this software for any purpose on any computer system, and to redistribute it freely, subject to the following restrictions:
1. This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
2. Regular expression support is provided by the PCRE library package, which is open source software, written by Philip Hazel, and copyright by the
University of Cambridge, England.
ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/
PHAOS SSLava and SSLavaThin
Copyright (c) 1996-2003 Phaos Technology Corporation. All Rights Reserved.
The software contains commercially valuable proprietary products of Phaos which have been secretly developed by Phaos, the design and development of
which have involved expenditure of substantial amounts of money and the use of skilled development experts over substantial periods of time. The software
and any portions or copies thereof shall at all times remain the property of Phaos.
PHAOS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTY OF MERCHANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE, REGARDING THE SOFTWARE, OR ITS USE AND OPERATION ALONE OR IN COMBINATION WITH
ANY OTHER SOFTWARE.
PHAOS SHALL NOT BE LIABLE TO THE OTHER OR ANY OTHER PERSON CLAIMING DAMAGES AS A RESULT OF THE USE OF ANY PRODUCT OR
SOFTWARE FOR ANY DAMAGES WHATSOEVER. IN NO EVENT WILL PHAOS BE LIABLE FOR SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES, EVEN IF ADVISED OF THE POSSIBLITY OF SUCH DAMAGES.
RealSystem
The RealNetworks® RealProxy™ Server is included under license from RealNetworks, Inc. Copyright 1996-1999, RealNetworks, Inc. All rights reserved.
SNMP
Copyright (C) 1992-2001 by SNMP Research, Incorporated.
ix
Blue Coat
This software is furnished under a license and may be used and copied only in accordance with the terms of such license and with the inclusion of the above
copyright notice. This software or any other copies thereof may not be provided or otherwise made available to any other person. No title to and ownership of
the software is hereby transferred. The information in this software is subject to change without notice and should not be construed as a commitment by
SNMP Research, Incorporated.
Restricted Rights Legend:
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFARS 252.227-7013; subparagraphs (c)(4) and (d) of the Commercial Computer Software-Restricted Rights Clause, FAR 52.227-19; and in
similar clauses in the NASA FAR Supplement and other corresponding governmental regulations.
PROPRIETARY NOTICE
This software is an unpublished work subject to a confidentiality agreement and is protected by copyright and trade secret law. Unauthorized copying,
redistribution or other use of this work is prohibited. The above notice of copyright on this source code product does not indicate any actual or intended
publication of such source code.
STLport
Copyright (c) 1999, 2000 Boris Fomitchev
This material is provided "as is", with absolutely no warranty expressed or implied. Any use is at your own risk.
Permission to use or copy this software for any purpose is hereby granted without fee, provided the above notices are retained on all copies. Permission to
modify the code and to distribute modified code is granted, provided the above notices are retained, and a notice that the code was modified is included with
the above copyright notice.
The code has been modified.
Copyright (c) 1994 Hewlett-Packard Company
Copyright (c) 1996-1999 Silicon Graphics Computer Systems, Inc.
Copyright (c) 1997 Moscow Center for SPARC Technology
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the
above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.
Hewlett-Packard Company makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied
warranty.
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the
above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Silicon
Graphics makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the
above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Moscow
Center for SPARC Technology makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied
warranty.
SmartFilter
Copyright (c) 2003 Secure Computing Corporation. All rights reserved.
SurfControl
Copyright (c) 2003 SurfControl, Inc. All rights reserved.
Symantec AntiVirus Scan Engine
Copyright (c) 2003 Symantec Corporation. All rights reserved.
TCPIP
Some of the files in this project were derived from the 4.X BSD (Berkeley Software Distribution) source.
Their copyright header follows:
Copyright (c) 1982, 1986, 1988, 1990, 1993, 1994, 1995
The Regents of the University of California. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the following acknowledgement:
This product includes software developed by the University of California, Berkeley and its contributors.
4. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
Trend Micro
Copyright (c) 1989-2003 Trend Micro, Inc. All rights reserved.
x
Copyrights
zlib
Copyright (c) 2003 by the Open Source Initiative
This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of
this software.
ICU License - ICU 1.8.1 and later COPYRIGHT AND PERMISSION NOTICE Copyright (c) 1995-2003 International Business Machines Corporation and others
All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission
notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE
SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO
EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT
OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to
promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder
xi
Blue Coat
The SG Client software is based in part on the work of the Independent JPEG Group
The SG Client software is based in part on the work of the FreeType Project (www.freetype.org)
The SG Client software is based in part on the work of Chris Maunder and info-zip
LEGAL ISSUES
============
In plain English:
1. We don't promise that this software works. (But if you find any bugs, please let us know!)
2. You can use this software for whatever you want. You don't have to pay us.
3. You may not pretend that you wrote this software. If you use it in a program, you must acknowledge somewhere in your documentation that
you've used the IJG code.
In legalese:
The authors make NO WARRANTY or representation, either express or implied, with respect to this software, its quality, accuracy, merchantability, or fitness
for a particular purpose. This software is provided "AS IS", and you, its user, assume the entire risk as to its quality and accuracy.
This software is copyright (C) 1991-1998, Thomas G. Lane. All Rights Reserved except as specified below.
Permission is hereby granted to use, copy, modify, and distribute this software (or portions thereof) for any purpose, without fee, subject to these conditions:
(1) If any part of the source code for this software is distributed, then this README file must be included, with this copyright and no-warranty notice
unaltered; and any additions, deletions, or changes to the original files must be clearly indicated in accompanying documentation. (2) If only executable code
is distributed, then the accompanying documentation must state that "this software is based in part on the work of the Independent JPEG Group". (3)
Permission for use of this software is granted only if the user accepts full responsibility for any undesirable consequences; the authors accept NO LIABILITY
for damages of any kind.
These conditions apply to any software derived from or based on the IJG code, not just to the unmodified library. If you use our work, you ought to
acknowledge us.
Permission is NOT granted for the use of any IJG author's name or company name in advertising or publicity relating to this software or products derived
from it. This software may be referred to only as "the Independent JPEG Group's software".
We specifically permit and encourage the use of this software as the basis of commercial products, provided that all warranty or liability claims are assumed
by the product vendor.
ansi2knr.c is included in this distribution by permission of L. Peter Deutsch, sole proprietor of its copyright holder, Aladdin Enterprises of Menlo Park, CA.
ansi2knr.c is NOT covered by the above copyright and conditions, but instead by the usual distribution terms of the Free Software Foundation; principally,
that you must include source code if you redistribute it. (See the file ansi2knr.c for full details.) However, since ansi2knr.c is not needed as part of any
program generated from the IJG code, this does not limit you more than the foregoing paragraphs do.
The Unix configuration script "configure" was produced with GNU Autoconf. It is copyright by the Free Software Foundation but is freely distributable. The
same holds for its supporting scripts (config.guess, config.sub, ltconfig, ltmain.sh). Another support script, install-sh, is copyright by M.I.T. but is also freely
distributable.
It appears that the arithmetic coding option of the JPEG spec is covered by patents owned by IBM, AT&T, and Mitsubishi. Hence arithmetic coding cannot
legally be used without obtaining one or more licenses. For this reason, support for arithmetic coding has been removed from the free JPEG software. (Since
arithmetic coding provides only a marginal gain over the unpatented Huffman mode, it is unlikely that very many implementations will support it.) So far as
we are aware, there are no patent restrictions on the remaining code.
The IJG distribution formerly included code to read and write GIF files. To avoid entanglement with the Unisys LZW patent, GIF reading support has been
removed altogether, and the GIF writer has been simplified to produce "uncompressed GIFs". This technique does not use the LZW algorithm; the resulting
GIF files are larger than usual, but are readable by all standard GIF decoders.
We are required to state that "The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark
property of CompuServe Incorporated."
xii
Copyrights
Finally, many people asked us for a preferred form for a credit/disclaimer to use in compliance with this license. We thus encourage you to use the
following text:
“Portions of this software are copyright (c) 2007The FreeType Project (www.freetype.org). All rights reserved."
Legal Terms
=========
0. Definitions
Throughout this license, the terms `package', `FreeType Project', and `FreeType archive' refer to the set of files originally distributed by the authors (David
Turner, Robert Wilhelm, and Werner Lemberg) as the `FreeType Project', be they named as alpha, beta or final release.
`You' refers to the licensee, or person using the project, where `using' is a generic term including compiling the project's source code as well as linking it to
form a `program' or `executable'. This program is referred to as `a program using the FreeType engine'.
This license applies to all files distributed in the original FreeType Project, including all source code, binaries and documentation, unless otherwise
stated in the file in its original, unmodified form as distributed in the original archive. If you are unsure whether or not a particular file is covered by this
license, you must contact us to verify this.
The FreeType Project is copyright (C) 1996-2000 by David Turner, Robert Wilhelm, and Werner Lemberg. All rights reserved except as specified below.
1. No Warranty
THE FREETYPE PROJECT IS PROVIDED `AS IS' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL ANY OF THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY DAMAGES CAUSED BY THE USE OR THE INABILITY TO USE, OF THE FREETYPE
PROJECT.
2. Redistribution
This license grants a worldwide, royalty-free, perpetual and irrevocable right and license to use, execute, perform, compile, display, copy, create
derivative works of, distribute and sublicense the FreeType Project (in both source and object code forms) and derivative works thereof for any purpose;
and to authorize others to exercise some or all of the rights granted herein, subject to the following conditions:
o Redistribution of source code must retain this license file (`FTL.TXT') unaltered; any additions, deletions or changes to the original files must be clearly
indicated in accompanying documentation. The copyright notices of the unaltered, original files must be preserved in all copies of source files.
o Redistribution in binary form must provide a disclaimer that states that the software is based in part of the work of the FreeType Team, in the distribution
documentation. We also encourage you to put an URL to the FreeType web page in your documentation, though this isn't mandatory.
These conditions apply to any software derived from or based on the FreeType Project, not just the unmodified files. If you use our work, you must
acknowledge us. However, no fee need be paid to us.
3. Advertising
Neither the FreeType authors and contributors nor you shall use the name of the other for commercial, advertising, or promotional purposes without
specific prior written permission.
We suggest, but do not require, that you use one or more of the following phrases to refer to this software in your documentation or advertising materials:
`FreeType Project', `FreeType Engine', `FreeType library', or `FreeType Distribution'.
As you have not signed this license, you are not required to accept it. However, as the FreeType Project is copyrighted material, only this license, or
another one contracted with the authors, grants you the right to use, distribute, and modify it. Therefore, by using, distributing, or modifying the
FreeType Project, you indicate that you understand and accept all the terms of this license.
4. Contacts
There are two mailing lists related to FreeType:
o freetype@nongnu.org
Discusses general use and applications of FreeType, as well as future and wanted additions to the library and distribution. If you are looking for support,
start in this list if you haven't found anything to help you in the documentation.
o freetype-devel@nongnu.org
Discusses bugs, as well as engine internals, design issues, specific licenses, porting, etc.
Our home page can be found at http://www.freetype.org
======================
zip.cpp—which is used by the Data Collector utility included in the SG Client software—is almost entirely based upon code by info-zip. It has been
modified by Lucian Wischik. The modifications were a complete rewrite of the bit of code that generates the layout of the zipfile, and support for zipping
tofrom memory or handles or pipes or pagefile or diskfiles, encryption, unicode.
The original code may be found at http:www.info-zip.org. The original copyright text follows.
This is version 1999-Oct-05 of the Info-ZIP copyright and license.
The definitive version of this document should be available at ftp:ftp.cdrom.compubinfoziplicense.html indefinitely.
Copyright (c) 1990-1999 Info-ZIP. All rights reserved.
For the purposes of this copyright and license, "Info-ZIP" is defined as the following set of individuals:
Mark Adler, John Bush, Karl Davis, Harald Denker, Jean-Michel Dubois, Jean-loup Gailly, Hunter Goatley, Ian Gorman, Chris Herborth, Dirk Haase, Greg
Hartwig, Robert Heath, Jonathan Hudson, Paul Kienitz, David Kirschbaum, Johnny Lee, Onno van der Linden, Igor Mandrichenko, Steve P. Miller, Sergio
Monesi, Keith Owens, George Petrov, Greg Roelofs, Kai Uwe Rommel, Steve Salisbury, Dave Smith, Christian Spieler, Antoine Verheijen, Paul von Behren,
Rich Wales, Mike White
This software is provided "as is," without warranty of any kind, express or implied. In no event shall Info-ZIP or its contributors be held liable for any direct,
indirect, incidental, special or consequential damages arising out of the use of or inability to use this software.
xiii
Blue Coat
Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the
following restrictions:
1. Redistributions of source code must retain the above copyright notice, definition, disclaimer, and this list of conditions.
2. Redistributions in binary form must reproduce the above copyright notice, definition, disclaimer, and this list of conditions in documentation andor other
materials provided with the distribution.
3. Altered versions--including, but not limited to, ports to new operating systems, existing ports with new graphical interfaces, and dynamic, shared, or static
library versions--must be plainly marked as such and must not be misrepresented as being the original source. Such altered versions also must not be
misrepresented as being Info-ZIP releases--including, but not limited to, labeling of the altered versions with the names "Info-ZIP" (or any variation thereof,
including, but not limited to, different capitalizations), "Pocket UnZip," "WiZ" or "MacZip" without the explicit permission of Info-ZIP. Such altered versions
are further prohibited from misrepresentative use of the Zip-Bugs or Info-ZIP e-mail addresses or of the Info-ZIP URL(s).
4. Info-ZIP retains the right to use the names "Info-ZIP," "Zip," "UnZip," "WiZ," "Pocket UnZip," "Pocket Zip," and "MacZip" for its own source and binary
releases.
Written by Chris Maunder (cmaunder@mail.com) Copyright (c) 1998-2003.
This code may be used in compiled form in any way you desire. This file may be redistributed unmodified by any means PROVIDING it is not sold for profit
without the authors written consent, and providing that this notice and the authors name is included. If the source code in this file is used in any commercial
application then acknowledgement must be made to the author of this file (in whatever form you wish).
This file is provided "as is" with no expressed or implied warranty. The author accepts no liability for any damage caused through use.
xiv
Contents
Contact Information
Chapter 2: Licensing
About Licensing.................................................................................................................................................21
Licensable Components....................................................................................................................................21
About the Trial Period ......................................................................................................................................22
Disabling the Components Running in Trial Period....................................................................................23
About License Expiration.................................................................................................................................23
About the System Serial Number ...................................................................................................................24
Obtaining a WebPower Account.....................................................................................................................24
Registering and Licensing Blue Coat Hardware and Software ..................................................................24
Retrieving the License.......................................................................................................................................26
Manual License Installation .............................................................................................................................26
Manually Updating a License..........................................................................................................................29
Automatically Updating a License .................................................................................................................29
xv
Volume 1: Getting Started
Chapter 6: Adapters
About Adapters................................................................................................................................................. 51
About Virtual LAN Configuration ................................................................................................................. 51
About VLAN Deployments...................................................................................................................... 51
The Blue Coat Solution.............................................................................................................................. 53
Configuring an Adapter................................................................................................................................... 54
Configuring Interface Settings ........................................................................................................................ 57
Disabling Transparent Interception ........................................................................................................ 57
Rejecting Inbound Connections............................................................................................................... 58
Using reject-inbound and allow-intercept ............................................................................................. 58
Manually Configuring Link Settings ...................................................................................................... 59
Configuring Proxies................................................................................................................................... 59
Detecting Network Adapter Faults ................................................................................................................ 59
Chapter 8: Gateways
About Gateways................................................................................................................................................ 73
SG Appliance Specifics..................................................................................................................................... 73
Switching to a Secondary Gateway......................................................................................................... 74
Routing ............................................................................................................................................................... 74
Using Static Routes .................................................................................................................................... 75
Notes ............................................................................................................................................................ 77
xvi
Contents
Chapter 9: DNS
SG Appliance Specifics..................................................................................................................................... 79
Configuring Split DNS Support...................................................................................................................... 80
Changing the Order of DNS Servers.............................................................................................................. 81
Unresolved Hostnames (Name Imputing).................................................................................................... 82
Changing the Order of DNS Name Imputing Suffixes ............................................................................... 82
Caching Negative Responses .......................................................................................................................... 82
Appendix A: Glossary
Index
xvii
Volume 1: Getting Started
xviii
Chapter 1: About Getting Started
Volume 1: Getting Started describes how to access the Blue Coat SG appliance using the
CLI or Management Console, and provides basic configuration information that is
required in every environment.
Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Conventions Definition
Courier font Command line text that appears on your administrator workstation.
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.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
19
Volume 1: Getting Started
20
Chapter 2: Licensing
About Licensing
SGOS 5.x features a global licensing system for the SGOS software. License key files are
issued on a per-appliance basis. One license key file includes all of the component
licenses for whichever SGOS features you have elected to use.
Note: When your Blue Coat appliance order was completed, you received an e-mail
that contained serial numbers for licensable components. Those numbers are required
for the procedures in this chapter.
Licensable Components
There are three types of licensable components:
❐ Required—The SGOS 5 Base; these features are required on the SG appliance.
❐ Included—Additional SGOS 5.x features, which are provided by Blue Coat and that
are included in the SGOS 5 base license.
❐ Optional— Any additional (purchased) features.
When the license key file is created, it contains components of all three types. The
following table lists the SG appliance licensable components, categorized by type.
Required SGOS 5 Base The SG appliance operating system, plus base features: HTTP,
FTP, TCP-Tunnel, SOCKS, and DNS proxy.
Included 3rd Party Onbox Allows use with third-party vendor databases: Intersafe,
Content Filtering Optenet, Proventia, SmartFilter, SurfControl, Websense, and
Webwasher.
Included ICAP Services External virus and content scanning with ICAP servers.
Included Bandwidth Allows you to classify, control, and, if required, limit the
Management amount of bandwidth used by different classes of network
traffic flowing into or out of the SG appliance.
Included Windows Media MMS and RTSP proxy for Windows Media content; content
caching and splitting.
Full policy control over MMS and RTSP traffic for Windows
Media content.
When the maximum concurrent streams is reached, all
subsequent streams are denied and the client receives a
message.
21
Volume 1: Getting Started
Included Real Media RTSP proxy for Real Media content; content caching and
splitting.
Full policy control over RTSP traffic for Real Media content.
When the maximum concurrent streams is reached, all
subsequent streams are denied and the client receives a
message.
Included Apple QuickTime RTSP proxy for QuickTime content; no caching or splitting;
content pass-through.
Full policy control over RTSP traffic for QuickTime content.
Included Oracle COREid Allows realm initialization and user authentication to COREid
servers.
Included Peer-to-Peer Allows you to recognize and manage peer-to-peer P2P activity
relating to P2P file sharing applications.
Included HTTP Allows reduction to file sizes without losing any data.
Compression
Optional SSL (Native SSL Native SSL proxy and Reverse HTTPS Proxy (SSL termination)
Proxy and on the SG appliance. You must also purchase an SSL accelerator
Reverse HTTPs card to enable SSL termination.
Proxy, also called
SSL Termination)
Optional IM AOL Instant Messaging: AIM proxy with policy support for
AOL Instant Messenger.
MSN Instant Messaging: MSN proxy with policy support for
MSN Instant Messenger.
Yahoo Instant Messaging: Yahoo proxy with policy support for
Yahoo Instant Messenger.
22
Chapter 2: Licensing
Note: If you select Proxy Edition for the trial period but you purchase a MACH5
Edition license, the SG appliance configuration is reset when you install the license.
Note also that a few defaults—default proxy policy, trust destination IP address, and
tolerating HTTP requests—differ between the two editions.
The initial system boot-up triggers the 60-day trial; during this time you can evaluate the
SGOS functionality. For the first 60 days, all licensable components for the trial edition
you chose are active and available to use. When a license or demo license is installed
during the trial period, components previously available in the trial period, but not part of
that license, remain available and active for the remainder of the trial period. However, if
the license edition is different than the trial edition you selected, only functionality
available in the edition specified in the license remains available for trial.
Each time you navigate to the Management Console License Warning page, you see a text
message that identifies the expiration date of your trial period; the Maintenance >
Licensing > View tab shows the license components with expiration dates. If you require
more time to explore the SGOS features, a demo license is available; refer to your reseller
or contact Blue Coat Sales.
In the trial period, the Base SGOS user limit is unlimited. When a full license is installed,
any user limits imposed by that license are enforced, even if the trial period is still valid.
23
Volume 1: Getting Started
❐ FTP clients—If the FTP client supports it, a message is displayed stating the license has
expired.
❐ Streaming media clients—If the Windows Media Player, RealPlayer, or QuickTime
player version supports it, a message is displayed stating the license has expired.
❐ SG Client—After the trial license has expired, clients cannot connect to the ADN
network.
You can still perform SGOS configuration tasks, CLI, SSH console, serial console, or Telnet
connection. Although the component becomes disabled, feature configurations are not
altered. Also, policy restrictions remain independent of component availability.
24
Chapter 2: Licensing
❐ If you have older hardware that previously has been registered or if the SG appliance
does not have Internet access, you can install the software license under Maintenance >
Licensing > Install. For more information, see “Manual License Installation” on page
26.
5. Enter your WebPower credentials and click Register Now. It might take up for a
minute for the Registration Status field to display the results.
6. Click Continue.
7. Select Maintenance > Licensing > View.
25
Volume 1: Getting Started
26
Chapter 2: Licensing
4. Click the serial number of the unit. The Support - License Management Manage Serial
Numbers/Obtain IM License page displays.
5. Click Manage Software Serial Numbers. The License Self Service Change Hardware
Record displays.
27
Volume 1: Getting Started
28
Chapter 2: Licensing
Note: A message is written to the event log when you install a license
through the SG appliance.
• Remote URL—If the file resides on a Web server. The Install License Key
dialog displays.
Enter the URL path and click Install. The Installation Status field displays
relevant information. When installation is complete, click Results; examine
the results, close the window, and click OK. Click Apply.
• Local File—If the file resides in a local directory. The Upload and Install File
window opens.
Enter a path to the license file or click Browse and navigate to the file. Click
Install. A results window opens. Examine the license installation results; close
the window. Click Close. Click Apply.
The license is now installed. All features that you subscribed to are fully operational.
To update a license:
1. Select Maintenance > Licensing > Install.
2. Click Register/Manage.
3. Follow the instructions on the Blue Coat License Self-Service Web page.
4. If using the automatic license installation feature, click Update; otherwise, manually
install the license as described in “Manual License Installation” on page 26.
29
Volume 1: Getting Started
Note: If the automatic license update fails and you receive a Load from Blue Coat
error
1. you must log on to your License Management account:
https://services.bluecoat.com/eservice_enu/licensing/mgr.cgi.
2. Click Update License Key.
30
Chapter 3: Accessing the SG Appliance
The SGOS software uses the Secure Shell (SSH) and HTTPS protocols to securely access
the SGOS CLI and Management Console. Both SSHv1 and SSHv2 are enabled by
default, and host keys have already been created on the SG appliance.
All data transmitted between the client and the SG appliance using SSH/HTTPS is
encrypted.
During initial configuration, you assigned the SG appliance a username and password
and a privileged-mode (enabled/configuration) password. These passwords are
always stored and displayed hashed.
This chapter discusses:
❐ “Before You Begin: Understanding Modes” on page 31
❐ “Accessing the SG Appliance” on page 32
❐ “Accessing the Management Console Home Page” on page 33
❐ “Changing the Logon Parameters” on page 34
❐ “Viewing the Appliance Health” on page 37
Important: This chapter assumes that you have completed the first-time setup of the
SG appliance using either the front panel or serial console, and that the appliance is
running on the network. These steps must be completed before accessing the appliance.
You can manage the SG appliance by logging on to and using one of the following:
❐ An SSH session to access the CLI.
❐ The Management Console graphical interface.
You can also use a serial console to access the CLI.
Note: To use a Telnet session, you must use a serial console connection until you
configure Telnet for use. (For security reasons Blue Coat does not recommend using
Telnet).
31
Volume 1: Getting Started
If you use the CLI, you must enter each level separately:
Username: admin
Password:
SGOS> enable
Enable Password:
SGOS# configure terminal
Enter configuration commands, one per line. End with CTRL-Z.
SGOS#(config)
For detailed information about the CLI and the CLI commands, refer to Volume 11:
Command Line Interface Reference.
Note: Although most administrator tasks can be performed using either the
Management Console or the CLI, there is the occasional task that can only be done using
one of the two: these are specified in the manual.
To use SSHv1, you must first create an SSHv1 host key. For more information on creating
SSH host keys, refer to Volume 2: Proxies and Proxy Services.
To log on to the CLI, you must have:
❐ the account name that has been established on the SG appliance
❐ the IP address of the SG appliance
❐ the port number (22 is the default port number)
You must log on from your SSH client.
32
Chapter 3: Accessing the SG Appliance
The Management Console consists of a set of Web pages stored on the SG appliance. The
appliance acts as a Web server on the management port to serve these pages. From the SG
home page on the appliance, you can access the configuration, maintenance, and statistics
pages, and the documentation. The Management Console is supported with a complete
online help facility to assist you in defining the various configuration options.
Note: If, when you access the Management Console home page, you get a “host
mismatch” or an “invalid certificate” message, you need to recreate the security certificate
used by the HTTPS-Console. For information on changing the security certificate, refer to
the console services information in Volume 2: Proxies and Proxy Services.
Logging On
Each time you access the Management Console, you must log on.
❐ The Site is the IP address of the SG appliance to which you are logging on.
❐ The Realm is a configurable name that can be anything you choose. The SG appliance
IP address is the default. For more information on configuring the realm name, see
“Changing the SG Appliance Realm Name” on page 36.
❐ The User Name is the name of the account you are using on this SG appliance. The
name must already exist. It cannot be created here.
❐ The Password is the password for the account you are using. It cannot be changed here.
You can change the username and password for the console or the CLI. See “Changing the
Logon Parameters” on page 34.
Note: All successful and failed logon attempts are logged to the event log.
Logging Out
Once you have logged on, you do not have to log on again unless you exit the current
session or the session times out. The session timeout period, with a default of 900 seconds
(15 minutes), is configurable.
33
Volume 1: Getting Started
Thirty seconds before the session times out, a warning dialog displays. Click the Keep
Working button or the X in the upper-right-corner of the dialog box to keep the session
alive.
Note: The Keep Working button saves your changes. However, you must log back on to
work in other pages.
If you do not click Keep Working or the X in the upper-right-hand corner within the thirty-
second period, you are logged out. You must log back on to access the Management
Console.
Click the hyperlink to log back on.
Note: If you are on the Management Console home page when the session times out, you
are logged out without seeing the logout warning dialog. You might not be aware that you
are logged out until you try to access a Management Console page. You must enter the
logon information again.
Note: To prevent unauthorized access to the SG appliance, only give the console
username and password to those who administer the system.
34
Chapter 3: Accessing the SG Appliance
35
Volume 1: Getting Started
3. Enter and re-enter the console password that is used to view and edit configuration
information. The password must be from 1 to 64 characters long. As you enter the
new password, it is obscured with asterisks. Click OK.
Note: This does not change the enabled-mode password. You can only change the
enabled-mode password through the CLI.
4. Refresh the screen, which forces the SGOS software to re-evaluate current settings.
When challenged, enter the new password.
5. (Optional) Restrict access by creating an access control list or by creating a policy file
containing <Admin> layer rules. For more information, see Volume 4: Securing the Blue
Coat SG Appliance: Chapter 3: "Controlling Access to the Internet and Intranet".
Note: Usernames and passwords can each be from 1 to 64 characters in length, but the
passwords must be in quotes.
Usernames that contain \ (backward slash), * (asterisk), or ? (question mark) must be
escaped when viewing users from the command line interface. The escape character is \.
For example:
❐ user1* is searched as #(config users) view users user1\*
❐ user1? is searched as #(config users) view users user1\?
❐ user1\ is searched as #(config users) view users user1\\
36
Chapter 3: Accessing the SG Appliance
The new realm name displays the next time you log on to the Management Console.
3. Select Apply to commit the changes to the SG appliance.
37
Volume 1: Getting Started
38
Chapter 4: Configuring Basic Settings
The SG appliance global configurations include: defining the SG appliance name and
serial number, setting the time, and configuring NTP for your environment.
The following topics are discussed in this section:
❐ “Configuring the SG Appliance Name” on page 39
❐ “Viewing the Appliance Serial Number” on page 39
❐ “Configuring the System Time” on page 40
❐ “Network Time Protocol” on page 41
❐ “Configuring HTTP Timeout” on page 42
2. In the Appliance name field, enter a unique name for the appliance.
3. Select Apply to commit the changes to the SG appliance.
39
Volume 1: Getting Started
2. Click Select Time zone. A popup appears, displaying a list of time zones based on
geopolitical regions.
40
Chapter 4: Configuring Basic Settings
3. Select the time zone that represents your local time. Once the local time zone is
selected, event logs record the local time instead of GMT. To add additional time
zones to the list, update the appliance's time zone database, as described in the
following procedure.
Related CLI Syntax for Adding New Time Zones to the Database:
SGOS# (config) timezone database-path [url | default]
SGOS# (config) load timezone-database
41
Volume 1: Getting Started
You can add and reorder the list of NTP servers the SG appliance uses for acquiring the
time. The reorder feature is not available.
42
Chapter 4: Configuring Basic Settings
43
Volume 1: Getting Started
44
Chapter 5: Archive Configuration
Blue Coat allows you to use an existing configuration (modified to include only general
parameters, not system-specific settings) to quickly set up a newly-manufactured SG
appliance and to save the running configuration off-box for archival purposes.
This section discusses:
❐ “Sharing Configurations” on page 45
❐ “Archiving a Configuration” on page 48
Sharing Configurations
You can share configurations between two SG appliances. You can take a post-setup
configuration file (one that does not include those configuration elements that are
established in the setup console) from an already-configured SG appliance and push it
to a newly-manufactured system.
Note: Blue Coat Director allows you to push a configuration from one SG
appliance to multiple appliances at the same time. For more information on using
Director, see Volume 8: Managing the Blue Coat SG Appliance.
The new configuration is applied to the existing configuration, changing any existing
values. This means, for instance, that if the new configuration creates a realm called
RealmA and the existing configuration has a realm called RealmB, the combined
configuration includes two realms, RealmA and RealmB.
To share configurations, you must
❐ Change all "encrypted-password" entries to "password" followed by the actual
password in quotes.
❐ Change any "hashed-password" entries to "password" followed by the actual
password in quotes.
❐ Make sure that no services are tied to a specific proxy IP address.
❐ Download a content filter database, if the configuration includes content filtering.
You can use either the Management Console or the CLI to create a post-setup
configuration file on one SG appliance and push it to another.
45
Volume 1: Getting Started
2. In the View Current Configuration panel, select the configuration from the drop-down
list that you want to use for the newly-manufactured machine:
• Configuration - post setup: This displays the configuration on the current system,
minus any configurations created through the setup console, such as the
hostname and IP address. It also includes the installable lists.
• Configuration - brief: This displays the configuration on the current system, but
does not include the installable lists.
• Configuration - expanded: This is the most complete snapshot of the system
configuration, but it contains system-specific settings that should not be pushed
to a new system.
• Results of Configuration Load: This displays the results of the last configuration
pushed to the system.
3. View the configuration you selected by clicking View. You can also view the file by
selecting Text Editor in the Install Configuration panel and clicking Install.
4. Save the configuration. You can save the file two ways:
• Save it as a text file on your local system. This is advised if you want to re-use the
file.
• Copy the contents of the configuration. (You will paste the file into the Text Editor
on the newly-manufactured system.)
46
Chapter 5: Archive Configuration
Note: A message is written to the event log when you install a configuration
through the SG appliance.
5. Click Close.
2. Save the configuration. You can save the file two ways:
• Copy the contents of the configuration to the clipboard. (Paste the file into the
terminal on the newly-manufactured system.)
• Save it as a text file on a download FTP server accessible to the SG appliance. This
is advised if you want to re-use the file.
3. On the newly-manufactured SG appliance, retrieve the configuration file by doing
one of the following:
• If you saved the configuration to the clipboard, go to the (config) prompt and
paste the configuration into the terminal.
• If you saved the configuration on the FTP server:
At the enable command prompt, enter the following command:
SGOS# configure network “url”
where url must be in quotes and is fully-qualified (including the protocol, server
name or IP address, path, and filename of the configuration file). The
configuration file is downloaded from the server, and the SG appliance settings
are updated.
Note: If you rename the archived configuration file so that it does not contain
any spaces, the quotes surrounding the URL are unnecessary.
The username and password used to connect to the FTP server can be embedded
into the URL. The format of the URL is:
ftp://username:password@ftp-server
47
Volume 1: Getting Started
where ftp-server is either the IP address or the DNS resolvable hostname of the
FTP server.
If you do not specify a username and password, the SG appliance assumes that an
anonymous FTP is desired and thus sends the following as the credentials to
connect to the FTP server:
username: anonymous
password: proxy@
Archiving a Configuration
In the rare case of a complete system failure, restoring a SG appliance to its previous state
is simplified by loading an archived system configuration from an FTP or TFTP server.
The archive, taken from the running configuration, contains all system settings differing
from system defaults, along with any installable lists configured on the SG appliance.
Archive and restore operations must be done through the CLI.
Note: You can archive a system configuration to an FTP or TFTP server that allows
either anonymous logon or requires a specific username and password. Likewise, to
restore a system configuration, the server storing the archive can be configured either to
allow anonymous logon or to require a username and password.
48
Chapter 5: Archive Configuration
Example Session
SGOS#(config) archive-configuration host 10.25.36.47
ok
SGOS#(config) archive-configuration password access
ok
SGOS#(config) archive-configuration username admin1
ok
SGOS#(config) archive-configuration path ftp://archive.server/stored
ok
SGOS#(config) archive-configuration protocol ftp
ok
Note: To clear the host, password, or path, type the above commands using empty
double-quotes instead of the variable. For example, to clear the path, enter archive-
configuration path “”.
Troubleshooting
When pushing a shared configuration or restoring an archived configuration, keep in
mind the following issues:
❐ Encrypted passwords (login, enable, and FTP) cannot be decrypted by a device other
than that on which it was encrypted. If you were sharing a configuration, these
encrypted passwords were probably already created before the configuration was
pushed to the system.
❐ If the content filtering database has not yet been downloaded, any policy that
references categories is not recognized.
❐ The following passwords must be re-created (if you use the application specified):
• administrator console passwords (not needed for shared configurations)
• privileged-mode (enable) passwords (not needed for shared configurations)
• the front-panel PIN (recommended for limiting physical access to the system)
• access log FTP client passwords (primary, alternate)
• archive configuration FTP password
• RADIUS primary and alternate secret
• LDAP search password
• SmartFilter download password
• WebSense3 download password
49
Volume 1: Getting Started
50
Chapter 6: Adapters
This chapter describes SG network adapters and the adapter interfaces; the following
topics are discussed:
❐ “About Adapters” on page 51
❐ “About Virtual LAN Configuration” on page 51
❐ “Configuring an Adapter” on page 54
❐ “Configuring Interface Settings” on page 57
❐ “Detecting Network Adapter Faults” on page 59
About Adapters
SG appliances ship with one or more network adapters installed on the system, each
with one or more interfaces. This chapter describes how to change interface parameters
or configure additional adapters or virtual LANs in the appliance. You can also accept
or reject inbound connections, change link settings in the event the system did not
correctly determine them, and configure the browser for proxy settings.
As you select adapters from the picklist, the Adapter panel (Configuration > Network >
Adapters) displays the state of the configured adapter and its interfaces.
51
Volume 1: Getting Started
52
Chapter 6: Adapters
Figure 6-3. A switch broadcasting native and regular VLAN traffic over a trunk
In this example, the client attached to port 7 belongs to VLAN 2. Even though it is part of
VLAN2, it does not set tags or receive VLAN-tagged packets. The switch knows the
packet belongs to VLAN 2 and tags it accordingly. Conversely, it strips the VLAN 2 tag on
the response. The trunk link broadcasts VLAN 1 (the native) and 2 traffic to a router that
accepts the subnets of those VLANs.
Deployment complications arise when a device (other than a router) is required between
switches. Without VLAN tagging support, any network device deployed in between
switches either drops all VLAN-tagged traffic or passes it through by a bridging
configuration.
This creates a problem if, for example, users located on different floors all belong to VLAN
1, but are separated by proxy that does not recognize VLAN-tagged packets.
Note: In Blue Coat documentation, the convention for VLAN is
adapter.interface.VLAN_ID. For example, 0:0.1 is the native VLAN on adapter 0,
interface 0.
53
Volume 1: Getting Started
Configuring an Adapter
The following procedure describes how to configure an adapter. Repeat the process if the
system has additional adapters.
54
Chapter 6: Adapters
6a
6b
6c
Note: The default is to permit all inbound connections. You should always manually
configure link settings to avoid problems. The browser default is to use the proxy’s
default PAC file. (See “Configuring Interface Settings” on page 57 below for more
information on link settings and inbound connections.)
6. If applicable, configure Virtual LAN (VLAN) options (see “About Virtual LAN
Configuration” on page 51):
55
Volume 1: Getting Started
6e
6f
6d
56
Chapter 6: Adapters
57
Volume 1: Getting Started
58
Chapter 6: Adapters
Configuring Proxies
To configure proxies, refer to Volume 2: Proxies and Proxy Services.
59
Volume 1: Getting Started
If an adapter fault is detected and the adapter has an IP address assigned to it, the SG
appliance logs a severe event. When an adapter does not have an IP address, the appliance
does not log an entry.
60
Chapter 7: Software and Hardware Bridges
This chapter describes the SGOS hardware and software bridging capabilities. Network
bridging through the SG appliance provides transparent proxy pass-through and
failover support.
The following topics are discussed:
❐ “About Bridging”
❐ “About the Pass-Through Adapter” on page 63
❐ “Configuring a Software Bridge” on page 63
❐ “Configuring Programmable Pass-Through/NIC Adapters” on page 65
❐ “Customizing the Interface Settings” on page 67
❐ “Setting Bandwidth Management for Bridging” on page 67
❐ “Configuring Failover” on page 68
About Bridging
Bridging functionality allows SG appliances to be easily deployed as transparent
redirection devices, without requiring the additional expense and maintenance of L4
switches or WCCP-capable routers. Bridging is especially useful in smaller
deployments in which explicit proxies or L4 switches are not feasible options.
Bridges are used to segment Ethernet collision domains, thus reducing frame collisions.
Unlike a hub, a bridge uses a frame’s destination MAC address to make delivery
decisions. Because these decisions are based on MAC addressing, bridges are known as
Layer 2 devices.
To make efficient delivery decisions, the bridge must discover the identity of systems
on each collision domain, and then store this information in its bridging table. After
learning the identity of the systems on each collision domain, the bridge uses the source
MAC address of frames to determine from which interface a given system can be
reached.
A branch office that would take advantage of a bridging configuration is likely to be
small; for example, it might have only one router and one firewall in the network, as
shown below.
LAN
LAN
Router
61
Volume 1: Getting Started
To ensure redundancy, the SG appliance supports both serial and parallel failover modes.
See “ Configuring Failover” for more information about serial and parallel failover
configurations.
Note: If you want to use an L4 switch or an explicit proxy instead of bridging, you
must disable the bridging pass-thru card.
62
Chapter 7: Software and Hardware Bridges
Once power is restored to the SG appliance, the bridge comes back online and Web traffic
is routed to the appliance and thus is subject to that appliance’s configured features,
policies, content scanning, and redirection instructions. Note that bridging supports only
failover; it does not support load balancing.
Note: The adapter state is displayed on Configuration > Network > Adapters.
If the link goes down while propagation-failure is disabled, the previous link state is
immediately reflected to the other interface if propagation-failure is enabled during
this time.
63
Volume 1: Getting Started
3
4
3. In the New Bridge Name field, enter a name for the bridge—up to 16 characters. The
bridge name is case insensitive, that is, you cannot name one bridge “ABC” and
another bridge “abc”.
4. (Optional) If you want to assign the bridge to a failover group select it from the
Failover Group drop-down list.
See “Configuring Failover” on page 68 for more information about configuring
failover.
5. If you have a two-interface bridge and want to enable link error propagation, select
the Propagation Failure check box.
6. Click Add. The Add Bridge Interface dialog displays.
64
Chapter 7: Software and Hardware Bridges
7a
7b
7c
7d
65
Volume 1: Getting Started
❐ Fail Open—If the SG appliance fails, all traffic passes through the bridge so clients can
still receive data.
❐ Fail Closed—If the SG appliance fails, all traffic is blocked and service is interrupted.
This mode provides the same functionality as a user-configured software bridge.
Note: If you create a software bridge, the programmable bridge card mode is implicitly
Fail Closed (if the appliance fails, the software bridge is non-functional).
5
6
66
Chapter 7: Software and Hardware Bridges
Note: If the bridge adapters are not programmable, the mode commands are not
visible.
Note:If you have a MACH5 license, a programmable bridge card, and labeled
WAN/LAN interfaces, the WAN interface allows transparent interception by default.
67
Volume 1: Getting Started
SGOS#(config) bandwidth-management
SGOS#(config bandwidth-management) [subcommands]
Configuring Failover
In failover mode, two appliances are deployed, a master and a slave. The master sends
keepalive messages (advertisements) to the slaves. If the slaves do not receive
advertisements at the specified interval, the slave takes over for the master. When the
master comes back online, the master takes over from the slave again.
The SGOS bridging feature allows two different types of failover modes, parallel and serial.
Hardware and software bridges allow different failover modes:
❐ Software bridges allow serial or parallel failover. However, note that if the SG
appliance fails, serial failover also fails.
❐ Hardware bridges allow serial failover only.
Parallel Failover
In parallel failover mode, two systems are deployed side by side on redundant paths. In
parallel failover, the slave does not actively bridge any packets unless the master fails. If
the master fails, the slave takes over the master IP address and begins bridging. A parallel
failover configuration is shown in the following figure.
Because of the redundant paths, you must enable Spanning Tree to avoid bridge loops.
See “Bridging Loop Detection” on page 69 for more information about STP.
Serial Failover
In serial failover mode, the slave is inline and continuously bridges packets, but does not
perform any other operations to the bridged traffic unless the master fails. If the master
fails, the slave takes over the master IP address and applies policy, etc. A serial
configuration is shown in the following figure.
Setting Up Failover
Failover is accomplished by doing the following:
❐ Creating virtual IP addresses on each proxy.
❐ Creating a failover group.
❐ Attaching the bridge configuration.
68
Chapter 7: Software and Hardware Bridges
Example
The following example creates a bridging configuration with one bridge on standby.
Note: This deployment requires a hub on both sides of the bridge or a switch
capable of interface mirroring.
The preceding commands create a failover group called 10.0.0.4. The priority is
automatically set to 254 and the failover interval is set to 40.
❐ SG B—software bridge IP address: 10.0.0.3. Create a virtual IP address and a
failover group.
SG_B#(config) virtual-ip address 10.0.0.4
SG_B#(config) failover
SG_B#(config failover) create 10.0.0.4
SG_B#(config failover) edit 10.0.0.4
SG_B#(config failover 10.0.0.4) enable
In the bridge configuration on each SG appliance, attach the bridge
configuration to the failover group:
SG_A#(config bridge bridge_name) failover group 10.0.0.4
SG_B#(config bridge bridge_name) failover group 10.0.0.4
69
Volume 1: Getting Started
4. In the Edit Bridge window, highlight the interface you want to configure and click
Edit. The Edit Bridge Interface dialog displays.
70
Chapter 7: Software and Hardware Bridges
71
Volume 1: Getting Started
3a
3c
3d
3b
72
Chapter 8: Gateways
A key feature of the SGOS software is the ability to distribute traffic originating at the
appliance through multiple gateways. You can also fine tune how the traffic is
distributed to different gateways. This feature works with any routing protocol (such as
static routes or RIP).
Note: Load balancing through multiple gateways is independent from the per-
interface load balancing the SG appliance automatically does when more than
one network interface is installed.
About Gateways
During the initial setup of the SG appliance, you optionally defined a gateway (a device
that serves as entrance and exit into a communications network) for the SG appliance.
By using multiple gateways, an administrator can assign a number of available
gateways into a preference group and configure the load distribution to the gateways
within the group. Multiple preference groups are supported.
The gateway specified applies to all network adapters in the system.
SG Appliance Specifics
Which gateway the SG appliance chooses to use at a given time is determined by how
the administrator configures the assignment of preference groups to default gateways.
You can define multiple gateways within the same preference group. A SG appliance
can have from 1 to 10 preference groups. If you have only one gateway, it automatically
has a weight of 100.
Initially, all gateways in the lowest preference group are considered to be the active
gateways. If a gateway becomes unreachable, it is dropped from the active gateway list,
but the remaining gateways within the group continue to be used until they all become
unreachable, or until an unreachable gateway in a lower preference group becomes
reachable again. If all gateways in the lowest preference group become unreachable, the
gateways in the next lowest preference group become the active gateways.
73
Volume 1: Getting Started
In addition to a preference group, each gateway within a group can be assigned a relative
weight value from 1 to 100. The weight value determines how much bandwidth a
gateway is given relative to the other gateways in the same group. For example, in a
group with two gateways, assigning both gateways the same weight value, whether 1 or
100, results in the same traffic distribution pattern. In a group with two gateways,
assigning one gateway a value of 10 and the other gateway a value of 20 results in the SG
appliance sending approximately twice the traffic to the gateway with a weight value of
20.
2. Click New.
3. Enter the IP address, group, and weight for the gateway into the Add list item dialog
that appears.
4. Click OK.
5. Repeat steps 2 to 4 until IP addresses, groups, and weights have been defined for all of
your gateways.
6. Select Apply to commit the changes to the SG appliance.
Routing
By default, routing is done transparently if the SG appliance can verify (trust) the
destination IP addresses provided by the client. If the destination IP addresses cannot be
trusted, the SG appliance uses static routes.
74
Chapter 8: Gateways
Note: IM is not supported with trust client addressing. In order to login and chat,
the default router must have Internet access. Other IM features require direct
connections, so static routes are required.
Note: For bridged deployments, transparent routing, in most cases, overrides any
static route lookups.
The routing table is a text file containing a list of IP addresses, subnet masks, and
gateways. You are limited to 10,000 entries in the static routes table. The following is a
sample router table:
10.25.36.0 255.255.255.0 10.25.36.1
10.25.37.0 255.255.255.0 10.25.37.1
10.25.38.0 255.255.255.0 10.25.38.1
When a routing table is installed, all requested URLs are compared to the list and routed
based on the best match.
75
Volume 1: Getting Started
Note: If you upgrade to SGOS 5.x from SGOS 4.x, entries from the central and local
bypass lists are converted to static route entries in the static route table. The converted
static route entries are appended after the existing static route entries. Duplicate static
route entries are silently ignored.
All traffic leaving the SG appliance is affected by the static route entries created from the
SGOS 4.x bypass lists.
76
Chapter 8: Gateways
Notes
❐ Any deployment that causes traffic to traverse the link from the SG appliance to the
home router twice is not supported. Some WCCP configurations might not work as
expected.
❐ If you use URL host rewrite functionality in your policies, mismatches can occur
between the client-provided IP address and the resolved, rewritten hostname. In these
cases, static routing is used.
77
Volume 1: Getting Started
78
Chapter 9: DNS
SG Appliance Specifics
If you have defined more than one DNS server, the SGOS software uses the following
logic to determine which servers are used to resolve a DNS host name and when to
return an error to the client:
❐ SGOS first sends requests to DNS servers in the primary DNS server list.
❐ Servers are always contacted in the order in which they appear in a list.
❐ The next server in a list is only contacted if the SG appliance does not receive a
response from the current server.
❐ If none of the servers in a list returns a response, the SG appliance returns an error
to the client.
❐ The SG appliance only sends requests to servers in the alternate DNS server list if a
server in the primary list indicates that a DNS host name cannot be resolved.
If a DNS server returns any other error (other than an indication that a DNS host
name could not be resolved), the SG appliance returns the error to the client.
If a server in both the primary and alternate DNS server lists are unable to resolve a
DNS host name, an error is returned to the client.
The SG appliance always attempts to contact the first server in the primary DNS server.
If a response is received from this server, no attempts are made to contact any other
DNS servers in the primary list.
If the response from the first primary DNS server indicates a name error, the SG
appliance sends a DNS request to the first alternate DNS server, if one is defined. If no
alternate DNS servers have been defined, an error is returned to the client indicating a
name error. If the first alternate DNS server is unable to resolve the IP address, a name
error is returned to the client, and no attempt is made to contact any other DNS servers
in either the primary or alternate DNS server lists.
79
Volume 1: Getting Started
If a response is not received from any DNS server in a particular DNS server list, the SG
appliance sends a DNS request to the next server in the list. The SG appliance returns a
name error to the client if none of the servers in a DNS server list responds to the DNS
request.
Note: The alternate DNS server is not used as a failover DNS server. It is only used
when DNS resolution of primary DNS server returns name error. If a timeout occurs
when looking up the primary DNS server, no alternate DNS server is contacted.
If the SG appliance receives a negative DNS response (a response with an error code set to
Name Error), it caches that negative response. You can configure the SG appliance’s
negative response time-to-live value. (A value of zero disables negative caching.) If the SG
appliance is not configured (the default), the SG appliance caches the negative response
and uses the TTL value from the DNS response to determine how long it should be
cached.
2. Click New.
3. Enter the IP address of the DNS server in the dialog that appears and click OK.
4. Select Apply to commit the changes to the SG appliance.
80
Chapter 9: DNS
81
Volume 1: Getting Started
82
Chapter 9: DNS
Note: The SG appliance generates more DNS requests when negative caching is
disabled.
The SG appliance supports caching of both type A and type PTR DNS negative responses.
This functionality is only available through the CLI. You cannot configure DNS negative
caching through the Management Console.
83
Volume 1: Getting Started
84
Appendix A: Glossary
access log A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.
account A named entity that has purchased the appliance or the Entitlements from Blue Coat.
activation code A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.
active content stripping Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.
active content types Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user
administration access policy A policy layer that determines who can access the SG appliance to perform
administrative tasks.
administration A policy layer that determines how administrators accessing the SG appliance must
authentication policy authenticate.
Application Delivery A WAN that has been optimized for acceleration and compression by Blue Coat. This
Network (ADN) network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.
ADN backup manager Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.
ADN manager Responsible for publishing the routing table to SG Clients (and to other SG
appliances).
ADN optimize attribute Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
asx rewrite Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxy-
like support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.
audit A log that provides a record of who accessed what and how.
85
Volume 1: Getting Started
authenticate-401 attribute All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios
authenticated content Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).
authentication Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate Authority.
See also basic authentication, proxy authentication, and SSL authentication.
authentication realm Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.
bandwidth class hierarchy Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.
bandwidth management Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.
basic authentication The standard authentication for communicating with the target as identified in the
URL.
BCAAA Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.
byte-range support The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).
cache An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.
cache control Allows you to configure which content the SG appliance stores.
86
Appendix A: Glossary
cache efficiency A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.
cache hit Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.
cache miss Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .
cache object Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.
Certificate Authority (CA) A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.
child class (bandwidth gain) The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.
client consent certificates A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.
client-side transparency A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.
concentrator An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.
content filtering A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.
default boot system The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.
denial of service (DoS) A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.
87
Volume 1: Getting Started
destination objects Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.
detect protocol attribute Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
diagnostic reporting Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.
directives Commands used in installable lists to configure forwarding and SOCKS gateway.
DNS access A policy layer that determines how the SG appliance processes DNS requests.
domain name system (DNS) An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.
dynamic bypass Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.
dynamic real-time rating Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
(DRTR) dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.
early intercept attribute Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.
ELFF-compatible format A log type defined by the W3C that is general enough to be used with any protocol.
emulated certificates Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.
encrypted log A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.
event logging Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.
88
Appendix A: Glossary
explicit proxy A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.
extended log file format A variant of the common log file format, which has two additional fields at the end of
(ELFF) the line—the referer and the user agent fields.
fail open/closed Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.
forward proxy A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.
gateway A device that serves as entrance and exit into a communications network.
hardware serial number A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.
health check tests The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
• ICMP
• TCP
• SSL
• HTTP
• HTTPS
• Group
• Composite and reference to a composite result
• ICAP
• Websense
• DRTR rating service
89
Volume 1: Getting Started
health check type The kind of device or service the specific health check tests. The following types are
supported:
• Forwarding host and forwarding group
• SOCKS gateway and SOCKS gateway group
• CAP service and ICAP service group
• Websense off-box service and Websense off-box service group
• DRTR rating service
• User-defined host and a user-defined composite
heartbeat Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.
host affinity The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.
host affinity timeout The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.
inbound traffic (bandwidth Network packets flowing into the SG appliance. Inbound traffic mainly consists of
gain) the following:
• Server inbound: Packets originating at the origin content server (OCS) and sent to
the SG appliance to load a Web object.
• Client inbound: Packets originating at the client and sent to the SG appliance for
Web requests.
installable lists Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
• Creating the list using the SG text editor
• Placing the list at an accessible URL
• Downloading the directives file from the local system
integrated host timeout An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.
intervals Time period from the completion of one health check to the start of the next health
check.
IP reflection Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.
90
Appendix A: Glossary
issuer keyring The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.
licensable component (LC) (Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.
license Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.
listener The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.
live content Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.
load balancing A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.
local bypass list A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.
local policy file Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).
log facility A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.
log format The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.
log tail The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.
91
Volume 1: Getting Started
Management Console A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.
management information Defines the statistics that management systems can collect. A managed device
base (MIB) (gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.
maximum object size The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.
MIME/FILE type filtering Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.
multi-bit rate The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).
multicast Used in streaming; the ability for hundreds or thousands of users to play a single
stream.
multicast aliases Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel
multicast station Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).
multimedia content services Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.
name inputing Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server
native FTP Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).
NCSA common log format Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.
network address translation The process of translating private network (such as intranet) IP addresses to Internet
(NAT) IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.
92
Appendix A: Glossary
non-cacheable objects A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
• Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
• Password provided, requests that include a client password.
• Data in request that include additional client data.
• Not a GET request.
.nsc file Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.
NTP To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.
object (used in caching) An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.
object (used in Visual Policy An object (sometimes referred to as a condition) is any collection or combination of
Manager) entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.
object pipelining This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.
origin content server (OCS) Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.
outbound traffic (bandwidth Network packets flowing out of the SG appliance. Outbound traffic mainly consists
gain) of the following:
• Client outbound: Packets sent to the client in response to a Web request.
• Server outbound: Packets sent to an OCS or upstream proxy to request a service.
PAC (Proxy Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
AutoConfiguration) scripts port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.
packet capture (PCAP) Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.
93
Volume 1: Getting Started
parent class (bandwidth A class with at least one child. The parent class must share its bandwidth with its
gain) child classes in proportion to the minimum/maximum bandwidth values or priority
levels.
passive mode data Data connections initiated by an FTP client to an FTP server.
connections (PASV)
policies Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.
policy-based bypass list Used in policy. Allows a bypass based on the properties of the client, unlike static and
dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.
policy layer A collection of rules created using Blue Coat CPL or with the VPM.
pragma: no cache (PNC) A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).
proxy Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.
proxy service The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.
proxy service (default) The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.
public key certificate An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).
public virtual IP (VIP) Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.
94
Appendix A: Glossary
real-time streaming protocol A standard method of transferring audio and video and other time-based media over
(RTSP) Internet-technology based networks. The protocol is used to stream clips to any RTP-
based client.
reflect client IP attribute Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.
registration An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.
remote authentication dial- Authenticates user identity via passwords for network access.
in user service (RADIUS)
reverse proxy A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.
routing information protocol Designed to select the fastest route to a destination. RIP support is built into Blue
(RIP) Coat appliances.
router hops The number of jumps a packet takes when traversing the Internet.
secure shell (SSH) Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.
serial console A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.
server certificate categories The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.
server portals Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping a
set of external URLs onto a set of internal URLs.
server-side transparency The ability for the server to see client IP addresses, which enables accurate client-
access records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.
service attributes Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .
95
Volume 1: Getting Started
SG appliance A Blue Coat security and cache box that can help manage security and content on a
network.
sibling class (bandwidth A bandwidth class with the same parent class as another class.
gain)
simple network The standard operations and maintenance protocol for the Internet. It uses MIBs,
management protocol created or customized by Blue Coat, to handle (needs completion).
(SNMP)
simulated live Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.
SmartReporter log type A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.
SOCKS A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.
SOCKS proxy A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.
splash page Custom message page that displays the first time you start the client browser.
split proxy Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
• Mapi Proxy
• SSL Proxy
SQUID-compatible format A log type that was designed for cache statistics and is compatible with Blue Coat
products.
squid-native log format The Squid-compatible format contains one line for each request.
SSL authentication Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).
SSL proxy A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.
static route A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.
96
Appendix A: Glossary
statistics Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated, cache
efficiency, cached contents, and custom URLs generated by the appliance for various
kinds of logs. You can also check the event viewer for every event that occurred since
the appliance booted.
stream A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.
SurfControl log type A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.
system cache The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.
time-to-live (TTL) value Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.
traffic flow Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
(bandwidth gain) that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of
these connections, traffic flows in two directions—in one direction, packets flow out
of the SG appliance (outbound traffic), and in the other direction, packets flow into
the SG (inbound traffic). Connections can come from the client or the server. Thus,
traffic can be classified into one of four types:
• Server inbound
• Server outbound
• Client inbound
• Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.
transmission control TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
protocol (TCP) in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.
transparent proxy A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.
97
Volume 1: Getting Started
trial period Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.
unicast alias Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicast-
alias command to request the content from the origin streaming server.
universal time coordinates An SG appliance must know the current UTC time. By default, the appliance
(UTC) attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.
URL rewrite rules Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.
WCCP Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.
Web FTP Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
OCS (if the content is not already cached), and then translates the FTP response with
the file contents into an HTTP response for the client.
Websense log type A Blue Coat proprietary log type that is compatible with the Websense reporter tool.
98
Index
99
Volume 1: Getting Started
link settings 59 R
load balancing read-only access in Blue Coat SG 31
gateways 74 read-write access in Blue Coat SG 31
using multiple default IP gateways 73 realm
login parameters 33 name, changing 36
timeout, changing 37
M routes
Management Console static 75
accessing 32 static, installing 76
changing username and passwords in 34 transparent 74
console account 34 routing
home page 33 static routes 75
logging in 33
logging out 33 S
modes, understanding 31 static routes
loading 82
N table, 81
name imputing, see imputing table, installing 80
name, configuring 39 static routes, using 75
negative caching subnet mask, configuring 55
disabling for DNS responses 83
enabling for DNS responses 83 T
network adapter time, configuring in the Blue Coat SG 40
advanced configuration 58 timeout
link faults 59 HTTP, configuring 42
link settings 59 timeout, realm, changing 37
programmable 65
rejecting inbound connections 58 U
Network Time Protocol server, see NTP Universal Time Coordinates, see UTC
NTP username
adding server 42 changing 34
server order, changing 42 default for 34
time server, definition of 40 UTC time 40
understanding 41
V
P Virtual LAN
password about 51
changing 34 adapter configuration 54
default for 34 deployment 53
see also privileged-mode password native 52
privilege (enabled) mode, understanding 31 trunk 52
privileged-mode password
changing 34 W
default for 34 Web interface, definition of 32
proxies
setting up 19
100
Blue Coat® Systems
SG™ Appliance
Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
ii
Contents
Contact Information
iii
Volume 2: Proxies and Proxy Services
iv
Contents
v
Volume 2: Proxies and Proxy Services
vi
Contents
Appendix A: Glossary
vii
Volume 2: Proxies and Proxy Services
Index
viii
Chapter 1: About Proxies and Proxy Services
A proxy filters traffic, monitors Internet and intranet resource usage, blocks specific
Internet and intranet resources for individuals or groups, and enhances the quality of
Internet or intranet user experiences.
A proxy serves as an intermediary between a Web client and a Web server and can
require authentication to allow identity-based policy and logging for the client, as
discussed in Volume 4: Securing the Blue Coat SG Appliance.
Proxies have two major components:
❐ The proxy service needs to be created or enabled and various attributes set, such as
whether you want the proxy to use explicit or transparent mode
❐ The proxy itself needs to be configured to intercept the traffic desired. You can
configure it in reverse or forward mode.
9
Volume 2: Proxies and Proxy Services
Configuring Proxies
After you have created or enabled the proxy services you need, the next step is to
configure the proxy that will use that service. Some proxy services require little
configuration; others, such as the SSL proxy, require configuration depending on what
you want to do and also require policy to be configured to work effectively.
Document Conventions
The following table lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Conventions Definition
Courier font Command line text that appears on your administrator workstation.
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.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
10
Chapter 1: About Proxies and Proxy Services
About Procedures
Many of the procedures in this volume begin:
❐ Select Configuration > Services, if you are working in the Management Console, or
❐ From the (config) prompt, if you are working in the command line interface (CLI).
Blue Coat assumes that you already logged into the first page of the Management Console
or entered into configuration mode in the CLI.
Illustrations
To save space, screen shots illustrating a procedure often have the bottom portion
removed, along with the blank space.
Figure 1-2. Configuration > General Pane with Bottom Buttons Removed
11
Volume 2: Proxies and Proxy Services
12
Chapter 2: About Console Services
The SG appliance ships with four consoles designed to manage communication with
the system:
❐ HTTP and HTTPS Consoles: These consoles are designed to allow you access to the
Management Console. The HTTPS Console is created and enabled by default; the
HTTP Console is created by default but not enabled because it is less secure than
HTTPS.
❐ SSH Console: This console is created and enabled by default, allowing you access
to the CLI using an SSH client.
❐ Telnet Console: This console not created because the passwords are sent
unencrypted from the client to the SG appliance. You must create and enable the
console before you can access the appliance through a Telnet client (not
recommended).
13
Volume 2: Proxies and Proxy Services
4a
4b
4c
14
Chapter 2: About Console Services
To create a new HTTP Console service or edit an existing one, see “About Console
Services” on page 13.
Selecting a Keyring
The SG appliance ships with a default keyring that can be reused with each console that
you create. You can also create your own keyrings.
To use the default keyring, accept the default keyring through the Management Console.
If using the CLI, the default keyring is automatically used for each new HTTPS Console
that is created.To use a different keyring you must edit the console service and select a
new keyring using the attribute keyring command.
15
Volume 2: Proxies and Proxy Services
Note: When using certificates for the HTTPS Console or for HTTPS termination services
that are issued by Certificate Signing Authorities that are not well-known, see Chapter 9:
"Creating and Editing an HTTPS Reverse Proxy Service" on page 121.
If you get “host mismatch” errors or if the security certificate is called out as invalid,
create a different certificate and use it for the HTTPS Console.
For information on creating a keypair and a certificate to make a keyring, see Chapter 9:
"Creating and Editing an HTTPS Reverse Proxy Service" on page 121.
Selecting an IP Address
You can use any IP address on the SG appliance for the HTTPS Console service, including
virtual IP addresses. To create a virtual IP address, refer to Volume 5: Advanced Networking.
16
Chapter 2: About Console Services
3. In the Keyring drop-down list, which displays a list of already-created keyrings on the
system, select the keyring you want to use. The system ships with a default keyring
that is reusable for each HTPPS service.
4. (Optional) Select the appropriate checkboxes to determine the SSL version used for
this console.
5. Click New to add a new listener to the HTTPS console; click Edit to change the current
settings.
The default IP address value is <All>. To limit the service to a specific IP address, select
an IP address from the drop-down list that contains all IP addresses assigned to the
SG appliance.
6. Identify the port you want this service to listen on.
7. Click OK.
17
Volume 2: Proxies and Proxy Services
To create a new SSH Console service or edit an existing one, see “About Console
Services” on page 13.
Note: By default, SSHv2 is enabled and assigned to port 22. You do not need to create a
new host key unless you want to change the existing configuration.
1. Select Configuration > Authentication > Console Access > SSH Host.
2. To delete either SSHv1 or SSHv2 support on the SG appliance, click the appropriate
Delete button.
The change is made on the appliance without confirmation. The SSH host tab
redisplays with the designated host key deleted.
3. To add SSHv1 or SSHv2 support, select the Create checkbox for the version you want.
4. The SSH host key displays in the appropriate pane.
18
Chapter 2: About Console Services
Note: The above step must be done with your SSH client. The SG appliance cannot
create client keys.
2. Select Configuration > Authentication > Console Access > SSH Client.
19
Volume 2: Proxies and Proxy Services
4. Specify whether the client key is associated with an existing user or a new user, and
enter the name.
5. Paste the RSA key that you previously created with an SSH client into the Client key
field. Ensure that a key ID is included at the end. Otherwise, the import fails.
6. Click OK.
The SSH Client tab reappears, with the fingerprint (a unique ID) of the imported key
displayed.
20
Chapter 2: About Console Services
Note: If you do enable the Telnet console, be aware that you cannot use Telnet
everywhere in the CLI. Some modules, such as SSL, respond with the error message:
Telnet sessions are not allowed access to ssl commands.
By default a Telnet shell proxy service exists on the default Telnet port (23). Since only one
service can use a specific port, you must delete the shell service if you want to create a
Telnet console. Be sure to apply any changes before continuing. If you want a Telnet shell
proxy service in addition to the Telnet console, you can re-create it later on a different port.
For information on the Telnet service, see Chapter 10: "Managing Shell Proxies" on page
129.
To create a new Telnet console service or edit an existing one, see “About Console
Services” on page 13.
Note: To use the Telnet shell proxy (to communicate with off-proxy systems) and
retain the Telnet Console, you must either change the Telnet shell proxy to use a
transparent Destination IP address, or change the destination port on either the Telnet
Console or Telnet shell proxy. Only one service is permitted on a port. For more
information on the Telnet shell proxy, see Chapter 10: "Managing Shell Proxies" on
page 129.
21
Volume 2: Proxies and Proxy Services
22
Chapter 3: About Proxy Services
Proxy services define the ports and addresses where the SG appliance listens for
incoming requests. A variety of attributes for each service can be defined. Each service
can be applied to all IP addresses or limited to a specific set of addresses and port
combinations. A number of default services are predefined. Additional services can be
defined on other ports.
After setting up and enabling the proxy service, the next step is to configure the proxy
for your environment. If necessary, you can configure bypass lists for transparent proxy
environments. Alternatively, you can specify a list of systems that you do want
intercepted.
This chapter discusses:
❐ Section A: "Proxy Services" on page 24
❐ Section B: "Bypass List" on page 31
❐ Section C: "Using Restricted Intercept" on page 35
❐ Section D: "Configuring General Options for Proxy Services" on page 37
Note: A proxy listener should not be confused with the default proxy listener, a
service that intercepts all traffic not otherwise intercepted by other listeners.
Four settings are available (some settings are not available for some proxy listeners):
❐ <All>: All IP addresses are intercepted.
❐ <Transparent>: Only connections to destination addresses that do not belong to the
SG appliance are intercepted
❐ <Explicit>: Only destinations addresses that match one of the IP addresses on the
SG appliance are intercepted.
❐ Specific IP address or subnet: Only destination addresses matching the IP address
and subnet are intercepted.
23
Volume 2: Proxies and Proxy Services
Note: Console services, used to manage the SG appliance, are not discussed in this
chapter. For information about the four console services—HTTP, HTTPS, SSH, and
Telnet—see Chapter 2: "About Console Services" on page 13.
24
Chapter 3: About Proxy Services
Lotus Notes TCP-Tunnel <Transparent> 1352 Chapter 13: "Managing the TCP
Tunneling Proxy" on page 171
Novell NCP TCP-Tunnel <Transparent> 524 Chapter 13: "Managing the TCP
Tunneling Proxy" on page 171
Oracle TCP-Tunnel <Transparent> 1521, 1525 Chapter 13: "Managing the TCP
Tunneling Proxy" on page 171
POP3 TCP-Tunnel <Transparent> 110 Chapter 13: "Managing the TCP
Tunneling Proxy" on page 171
POP3S TCP-Tunnel <Transparent> 995 Chapter 13: "Managing the TCP
Tunneling Proxy" on page 171
RTSP RTSP <All> 554 Volume 3: Web Communication
Proxies
Shell TCP-Tunnel <Transparent> 514 Chapter 10: "Managing Shell
Proxies" on page 129
25
Volume 2: Proxies and Proxy Services
Sybase SQL TCP-Tunnel <Transparent> 1498 Chapter 13: "Managing the TCP
Tunneling Proxy" on page 171
The HTTPS Reverse Proxy service is also available but not created by default. When
created, it defaults to an <Explicit> destination IP address on port 443. For information
about configuring the HTTPS Reverse Proxy, see Chapter 9: "Creating and Editing an
HTTPS Reverse Proxy Service" on page 121.
26
Chapter 3: About Proxy Services
An HTTP connection initiated to server 10.167.10.2 could match any of the three listeners
in the above table. The most specific match algorithm finds that a listener in the New York
CRM service is the most specific and since the destination port of the connection and the
listener match, the connection is handled by this service.
The advantage of the most specific match algorithm becomes evident when at some later
point another server is added in the New York Data Center subnet. If that server needs to
be handled by a different service than the New York Data Center service, a new service
with a listener specific to the new server would be added. The administrator does not
need to be concerned about rule order in order to intercept traffic to this particular server
using the new, most specific service listener.
Attribute Description
Authenticate-401 All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially useful
to force transparent proxy authentication in some proxy-chaining scenarios.
Detect Protocol Detects the protocol being used. Protocols that can be detected include:
HTTP, P2P (eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
Early Intercept Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server. If you enable
the Detect Protocol attribute, the Early Intercept attribute is selected automatically.
Use ADN Controls whether ADN is enabled for a specific service. Enabling ADN does not
guarantee the connections are accelerated by ADN. The actual enable decision is
determined by ADN routing (for explicit deployment) and network setup (for
transparent deployment).
27
Volume 2: Proxies and Proxy Services
Attribute Description
Forward Client Cert When used with the verify-client attribute, puts the extracted client certificate
information into a header that is included in the request when it is forwarded to the
OCS. The name of the header is Client-Cert. The header contains the certificate serial
number, subject, validity dates and issuer (all as name=value pairs). The actual
certificate itself is not forwarded.
Optimize Bandwidth Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
Reflect Client IP Enables the sending of the client's IP address instead of the SG appliance's IP
address to the upstream server. If you are using an Application Delivery Network
(ADN), this setting is enforced on the concentrator proxy through the Configuration
> App. Delivery Network > Tunneling tab. For more information, refer to Volume 5:
Advanced Networking.
SSL Versions Allows you to select which versions of SSL you want to support. The default is to
support SSL v2, v3, and TLS. This attribute is available for HTTPS Reverse Proxy.
Verify Client Requests and validates the SSL client certificate. This attribute is available for HTTPS
Reverse Proxy.
Note: The x-service-name field replaces the s-sitename field. The s-sitename field
can still be used for backward compatibility with squid log formats, but it has no CPL
equivalent.
28
Chapter 3: About Proxy Services
Note: If you only want to change the proxy’s behavior from bypass (the default) to
intercept, go to the Action column of the Proxy Services pane, select the service whose
behavior you want to change, and Click Intercept from the drop-down list. You do not
need to enter New/Edit mode to change this setting.
10
29
Volume 2: Proxies and Proxy Services
4. In the Name field, choose a meaningful name for the new proxy service.
5. In the Proxy Settings field, select the type of proxy service. The settings below the
Proxy field change depending on the kind of proxy you select. (This example is using
the TCP-Tunnel proxy.)
6. Enable or clear the check boxes, as appropriate, for the service being set up. (For
information about the various attributes, see Table 3-3, “Service Attributes,” on
page 27.)
7. To create a new listener, click New.
8. Click a Destination IP address from the radio buttons.
9. In the Port Range field, enter the ports on which the service should listen. The default
ports for each service are discussed in the chapter for each proxy.
10. Select the default action for the service: Bypass tells the service to ignore any traffic
matching this listener. Intercept configures the service to intercept and proxy the
associated traffic.
11. Click OK; click Apply.
30
Chapter 3: About Proxy Services
Note: This prevents the appliance from enforcing any policy on these requests and
disables any caching of the corresponding responses. Because bypass entries bypass Blue
Coat policy, use bypass sparingly and only for specific situations.
Note: Dynamic bypass cannot be configured through the Management Console. It can
only be configured through policy or the CLI. For more information, see “ Using Policy to
Configure Dynamic Bypass” on page 32.
1. Click Configuration > Services > Proxy Services > Bypass List.
2. Click New to create a new list entry; click Edit to modify a list entry.
31
Volume 2: Proxies and Proxy Services
Note: Because bypass entries bypass Blue Coat policy, the feature should be used
sparingly and only for specific situations.
Dynamic bypass keeps its own (dynamic) list of which connections to bypass, where
connections are identified by both source and destination. Dynamic bypass can be based
on any combination of policy triggers. In addition, some global settings can be used to
selectively enable dynamic bypass based on specific HTTP response codes. After an entry
exists in the dynamic bypass table for a specific source/destination IP pair, all connections
from that source IP to that destination IP are bypassed in the same way as connections
that match against the static bypass list.
For a configured period of time, further requests for the error-causing URLs are sent
immediately to the origin content server (OCS), bypassing the SG appliance. The amount
of time a dynamic bypass entry stays in the list and the types of errors that cause the SG
appliance to add a site to the list, as well as several other settings, are configurable from
the CLI.
Once the dynamic bypass timeout for a client and server IP address entry has ended, the
SG appliance removes the entry from the bypass list. On the next client request for the
client and server IP address, the SG appliance attempts to contact the OCS. If the OCS still
returns an error, the entry is once again added to the local bypass list for the configured
dynamic bypass timeout. If the entry does not return an error, the request is handled in the
normal manner.
Notes
❐ Dynamic bypass entries are lost when the SG appliance is restarted.
❐ No policy enforcement occurs on client requests that match entries in the dynamic or
static bypass list.
❐ If a site that requires forwarding policy to reach its destination is entered into the
bypass list, the site is inaccessible.
32
Chapter 3: About Proxy Services
Note: This step is optional because the SG appliance uses default configurations if you
do not specify them. Use the default values unless you have specific reasons for changing
them. Contact Blue Coat Technical Support for detailed advice on customizing these
settings.
❐ The server-threshold value defines the maximum number of client entries before
the SG appliance consolidates client–server pair entries into a single server entry that
then applies to all clients connecting to that server. The range is 1 to 256. The default is
16. When a consolidation occurs, the lifetime of the consolidated entry is set to the
value of timeout.
❐ The max-entries defines the maximum number of total dynamic bypass entries. The
range is 100 to 50,000. The default value is 10,000. When the number of entries exceeds
the max-entries value, the oldest entry is replaced by the newest entry.
❐ The timeout value defines the number of minutes a dynamic bypass entry can remain
unreferenced before it is deleted from the bypass list. The range is 1 to 86400. The
default value is 60.
33
Volume 2: Proxies and Proxy Services
34
Chapter 3: About Proxy Services
Note: An entry can exist in both the Static Bypass List and the Restricted Intercept
List. However, the Static Bypass List overrides the entries in the Restricted Intercept
List.
3. Click New to create a new list entry, or click Edit to modify a list entry.
35
Volume 2: Proxies and Proxy Services
4. To select a specific client to be intercepted, click Client host or subnet and enter the IP
Address and Subnet Mask. To select all clients using a specific server, click All clients,
then enter the server IP Address and Subnet Mask in the Server address section.
5. Click OK.
6. Click Apply to commit the changes to the SG appliance.
36
Chapter 3: About Proxy Services
37
Volume 2: Proxies and Proxy Services
You can change this default through the Management Console, the CLI, or through policy.
If you use policy, be aware that it overrides any other configuration. For information
about using the trust_destination_ip(yes|no) property, refer to Volume 10: Blue Coat
SG Appliance Content Policy Language Guide.
Note: If you use the MACH5 edition, the SG appliance allows the client-provided
destination IP address by default.
For information about enabling the SG appliance to allow the client-provided destination
IP address, see “Configuring General Options” on page 41.
Tip
If a client gives the destination address of a blocked site but the hostname of a non-
blocked site, the SG appliance connects to the destination address. This might allow
clients to bypass the configured SG appliance security policy.
210-5 30 10
210-10 150 50
510-5 200 50
38
Volume 2: Proxies and Proxy Services
Note: SGOS 5.2.1 has two options only: Queue and Bypass. Queue is the default.
To set the preferred behavior, see “Configuring General Options” on page 41.
Note: You can use the Statistics > Health Monitoring > Licensing tab to view licensing
metrics, but you cannot make changes to the threshold values from that tab. To
change the thresholds, use the Maintenance > Health Monitoring > Licensing tab.
39
Volume 2: Proxies and Proxy Services
Note: For information about licensing metrics, refer to Volume 9: Managing the Blue
Coat SG Appliance.
40
Volume 2: Proxies and Proxy Services
41
Volume 2: Proxies and Proxy Services
2. Select or clear the Trust client-provided destination IP when connecting to servers check
box.
3. Click the radio button for the User Overflow Action you prefer when the licensed-user
limits are exceeded. By default, for SGOS 5.2.2 and later, none is the default.
Note: If you set the User Overflow Action to none and exceed the licensed-user
limits, the SG appliance health changes to CRITICAL.
42
Chapter 4: Managing the CIFS Proxy
This chapter discusses the Common Internet File System (CIFS) protocol and describes
how to configure the services and proxy on the SG appliance.
Note: The CIFS protocol is based on the Server Message Block (SMB) protocol used for
file sharing, printers, serial ports, and other communications. It is a client-server,
request-response protocol.
About CIFS
CIFS allows computers to share files and printers, supports authentication, and is
popular in enterprises because it supports all Microsoft operating systems, clients, and
servers.
File servers make file systems and other resources (printers, mailslots, named pipes,
APIs) available to clients on the network. Clients have their own hard disks, but they
can also access shared file systems and printers on the servers.
Clients connect to servers using TCP/IP. After establishing a connection, clients can
send commands (SMBs) to the server that allows them to access shares, open files, read
and write files— the same tasks as with any file system, but over the network.
CIFS is beneficial because it is generic and compatible with the way applications
already share data on local disks and file servers. More than one client can access and
update the same file, while not compromising file-sharing and locking schemes.
However, the challenge for an enterprise is that CIFS communications are inefficient
over low bandwidth lines or lines with high latency, such as in enterprise branch
offices. This is because CIFS transmissions are broken into blocks of data (typically close
to 64 KB). The client must stop and wait for each block to arrive before requesting the
next block. Each stop represents time lost instead of data sent. Therefore, users
attempting to access, move, or modify documents experience substantial, work-
prohibiting delays.
43
Volume 2: Proxies and Proxy Services
Caching Behavior
The CIFS proxy caches the regions of files that are read or written by the client (partial
caching) and applies to both read and write file activities. Also, the caching process
respects file locking.
Authentication
The CIFS proxy supports both server and proxy authentication in the following contexts.
44
Chapter 4: Managing the CIFS Proxy
Server Authentication
Permissions set by the origin content server (OCS) are always honored. Requests to open a
file are forwarded to the OCS; if the OCS rejects the client access request, no content is
served from the cache.
Note: NTLM/IWA authentication requires that the client knows what origin server it
is connecting to so it can obtain the proper credentials from the domain controller.
Proxy Authentication
The SG appliance cannot issue a challenge to the user over CIFS, but it is able to make use
of credentials acquired by other protocols if IP surrogates are enabled.
Policy Support
The CIFS proxy supports the proxy, cache, and exception policy layers. However, the
SMB protocol can only return error numbers. Exception definitions in the forms of strings
cannot be seen by an end user. See “Reference: CPL Triggers, Properties, and Actions” on
page 57 for supported CPL triggers and actions.
Access Logging
By default, the SG appliance uses a Blue Coat-derived CIFS access log format.
date time c-ip r-ip r-port x-cifs-method x-cifs-server x-cifs-share
x-cifs-path x-cifs-orig-path x-cifs-client-bytes-read
x-cifs-server-bytes-read x-cifs-bytes-written x-cifs-file-type
s-action cs-username cs-auth-group s-ip
For a reference list and descriptions of used log fields, see “Reference: Access Log Fields”
on page 54.
WCCP Support
If WCCP is deployed for transparency, you must configure WCCP to intercept TCP ports
139 and 445.
45
Volume 2: Proxies and Proxy Services
If you know this setting is disabled on your clients or servers, you can proceed to
“Configuring CIFS Proxy Services” on page 47.
Note: This procedure follows the Control Panel Classic View format. The screen shots
represent Microsoft Windows XP.
1. In Windows, select Start > Control Panel > Administrative Tools > Local Security Policy.
The Local Security Settings dialog appears.
46
Chapter 4: Managing the CIFS Proxy
Important: If the server is an ADS/Domain controller, you must set the same
security settings for both Administrative Tools > Domain Controller Security Policy
and Administrative Tools- > Domain Security Policy. Otherwise, you cannot open file
shares and Group Policy snap-ins on your server.
7. You must reboot the client or server to apply this configuration change.
47
Volume 2: Proxies and Proxy Services
2. Scroll the list of services to display the default CIFS service line. Notice the Action is
Bypass. You can select Intercept from the drop-down list, but for the purposes of this
procedures, select the service line to highlight it.
3. Click Edit. The Edit Service dialog appears, with some default settings, is displayed.
4a
4b
4c
4d
48
Chapter 4: Managing the CIFS Proxy
Note: You can also change the mode from Bypass to Intercept from the main
services page.
Now that the CIFS listeners are configured, you can configure the CIFS proxy.
49
Volume 2: Proxies and Proxy Services
2a
2b
2c
2d
50
Chapter 4: Managing the CIFS Proxy
2a
2b
2. View statistics:
a. Select a statistic category tab:
• CIFS Objects: The total number of CIFS-related objects processed by the SG
appliance (read and written).
• CIFS Bytes Read: The total number of bytes read by CIFS clients.
• CIFS Bytes Written: The total number of bytes written by CIFS clients (such as
updating existing files on servers).
• CIFS Clients: The total number of connected CIFS clients.
• CIFS Bandwidth Gain: The total bandwidth usage for clients (yellow) and
servers (blue), plus the percentage gain.
b. The graphs display three time metrics: the previous 60 minutes, the previous
24 hours, and the previous 60 days. Roll the mouse over any colored bar to
view the exact metric.
3. (Optional) You can change the scale of the graph to display the percentage of bar
peaks to display.
51
Volume 2: Proxies and Proxy Services
Statistics
This page displays various, more granular connection and byte statistics.
https://SG_IP_address:8082/CIFS/statistics
If CIFS traffic interception is occurring (the above screenshot does not represent active
traffic), the byte counters increment when a user opens a file or browses around.
Note: The bytes to/from servers counters on the CIFS statistics page do not include
the effects of compression and byte caching over the WAN link.
Connections
This page displays specific client-to-server connection and file information and statistics.
https://SG_IP_address:8082/CIFS/connection
52
Chapter 4: Managing the CIFS Proxy
53
Volume 2: Proxies and Proxy Services
❐ cs-auth-group: One group that an authenticated user belongs to. If a user belongs to
multiple groups, the group logged is determined by the Group Log Order
configuration specified in VPM. If the Group Log Order is not specified, an arbitrary
group is logged. Note that only groups referenced by policy are considered.
❐ cs-username: Relative username of a client authenticated to the proxy (for example:
not fully distinguished).
❐ r-ip: IP address from the outbound server URL.
❐ r-port: Port from the outbound server URL, typically 139 or 445.
❐ s-action: The logging action (or flow) being one of the following:
• ALLOWED: CIFS operation passed the policy checkpoint and was also successful.
• DENIED: CIFS operation failed the policy checkpoint.
• ERROR: CIFS operation resulted in an error on the server; typically associated with
NT (x-cifs-nt-error-code) or DOS error (x-cifs-dos-error-code, x-cifs-
dos-error-class).
• FAILED: CIFS operation was successful on the server but failed on the proxy for
some internal reason.
• SUCCESS: CIFS operation was successful on the server (did not go through policy
checkpoint).
❐ s-ip: IP address of the appliance on which the client established its connection.
54
Chapter 4: Managing the CIFS Proxy
❐ x-cifs-file-type: The type of file that was opened or closed. Values are file,
directory, pipe, or other. It is only valid if x-cifs-method is OPEN, CLOSE,
CLOSE_ON_UNMAP, CLOSE_ON_LOGOFF, CLOSE_ON_DISCONNECT, or CLOSE_ON_PASSTHRU.
❐ x-cifs-method: The method associated with the CIFS request. The list of CIFS
methods are:
• CONNECT: For TCP-level connect from client to CIFS server.
• DISCONNECT: For TCP-level connection shutdown.
• LOGON: For SESSION_SETUP_ANDX SMB command.
• LOGOFF: For LOGOFF_ANDX SMB command.
• LOGOFF_ON_PASSTHRU: For removal of cached session from proxy upon PASSTHRU.
• LOGOFF_ON_DISCONNECT: For removal of cached session from proxy upon
DISCONNECT.
• MAP: For TREE_CONNECT SMB command.
• UNMAP: For TREE_DISCONNECT SMB command.
• UNMAP_ON_LOGOFF: For removal of cached share from proxy upon LOGOFF.
• UNMAP_ON_PASSTHRU: For removal of cached share from proxy upon PASSTHRU.
• UNMAP_ON_DISCONNECT: For removal of cached share from proxy upon
DISCONNECT.
• DELETE: For path-based DELETE and DELETE_DIRECTORY SMB commands.
• DELETE_ON_CLOSE: For delete-on-close action done on a CIFS resource.
• LIST: For enumerating contents of a directory.
• OPEN: For opening a CIFS resource.
• RENAME: For renaming a CIFS resource.
• CLOSE: For closing a CIFS resource.
• CLOSE_ON_UNMAP: For removal of cached file from proxy upon UNMAP.
55
Volume 2: Proxies and Proxy Services
❐ x-cifs-server-bytes-read: Total number of bytes read from CIFS server from the
associated resource.
❐ x-cifs-server-operations: Total number of server operations for this particular
resource. The scope is the same as x-cifs-client-read-operations.
❐ x-cifs-share: CIFS share name as specified in the UNC path.
56
Chapter 4: Managing the CIFS Proxy
Triggers
❐ attribute.<name>=, has_attribute.<name>=
❐ client.address=, client.host=, client.host.has_name=
❐ client.protocol=smb
❐ content_management=no
❐ condition=
❐ date[.utc]=, day=, hour=, minute=, month=, weekday=, year=, time=
❐ has_client=
❐ proxy.address=, proxy.port=, proxy.card=
❐ raw_url=
❐ release.*=
❐ server_url=
❐ socks.accelerated=smb
❐ tunneled=
❐ url=smb://<ip>:<port>/
❐ user.*=, group=, realm=, authenticated=
57
Volume 2: Proxies and Proxy Services
58
Chapter 5: Managing the DNS Proxy
When a DNS proxy service is enabled, it listens on port 53 for both explicit and
transparent DNS domain query requests. By default, the service is created but not
enabled.
The DNS does a lookup of the DNS cache to determine if requests can be answered. If
yes, the SG appliance responds. If not, the DNS forwards the request to the DNS server
list configured on the SG appliance. (To configure the DNS server list, see Configuration
> Network > DNS.)
Note: The SG appliance is not a DNS server. It does not do zone transfers, and
recursive queries are forwarded to other name servers.
For information on managing DNS name servers, refer to Volume 1: Getting Started.
Through policy, you can configure the list of resolved domain names (the resolving name
list) the DNS uses. The domain name in each query received by the SG appliance is
compared against the resolving name list. Upon a match, the appliance checks the
resolving list. If a domain name match is found but no IP address was configured for
the domain, the appliance sends a DNS query response containing its own IP address.
If a domain name match is found with a corresponding IP address, that IP address is
returned in a DNS query response. All unmatched queries are sent to the name servers
configured on the SG appliance.
This chapter discusses:
❐ “Creating or Editing a DNS Proxy Service”
❐ “ Creating a Resolving Name List” on page 61
Note: If you only want to change the proxy’s behavior from bypass (the default) to
intercept, go to the Action column of the Proxy Services pane, select the service whose
behavior you want to change, and select Intercept from the drop-down list. You do
not need to enter New/Edit mode to change this attribute.
59
Volume 2: Proxies and Proxy Services
7b
7a
7c
7d
4. In the Name field, choose a meaningful name for the new proxy service.
5. From the Proxy drop-down list, select DN Proxy.
6. Select or de-select the checkboxes, as appropriate, for the environment
a. Reflect Client IP: Enables or disables sending of client's IP address instead of
the SG appliance's IP address.
b. Early intercept: This option cannot be changed when creating or editing a
DNS proxy service.
7. Create a new listener:
a. Click New.
b. Define the Destination IP information.
c. In the Port Range field, enter the ports on which the service should listen. The
default port is 53.
d. Select the default action for the service: Bypass tells the service to ignore any
traffic. Intercept configures the service to intercept the traffic that is being
proxied.
e. Click OK.
8. Click Apply.
60
Chapter 5: Managing the DNS Proxy
Note: You can also create a resolving name list using VPM. For more information on
using the DNS-Proxy layer in VPM, refer to Volume 1: Getting Started.
61
Volume 2: Proxies and Proxy Services
62
Chapter 6: Managing the Endpoint Mapper and MAPI Proxies
This chapter discusses the Endpoint Mapper and MAPI proxy solutions, and describes
how to configure the services and proxy configuration.
The Endpoint Mapper and MAPI proxies are similar in that they accelerate Microsoft
applications across a WAN; however, there are key differences.
This chapter contains the following sections:
❐ Section A: "The Endpoint Mapper Proxy Service" on page 64.
❐ Section B: "The MAPI Proxy" on page 70.
63
Volume 2: Proxies and Proxy Services
About RPC
The Microsoft RPC protocol functions across a client/server model where one application
requests a service from another application. The requesting program is the client; the
providing service is the server. RPC allows an application on one host (the client) to
request and thereby cause an application on another host (the server) to execute an action
without the requirement of explicit code. For example: MAPI traffic.
Typically, RPC communications occur when the client contacts the Endpoint Mapper
service on that client host to determine how to contact the server. The client provides the
RPC service identifier and the Endpoint Mapper service returns the IP and port the client
uses to contact the server. Then, the client makes a new TCP connection to that IP and port
and sends its RPC request.
The challenges occur when these communications occur between branch offices and
servers located in core locations. The user experience is poor because of low available
bandwidth or high latency lines.
Note: Only Microsoft RPC version 5.0 is supported. Unsupported Microsoft RPC version
traffic is passed through the SG appliance without processing.
64
Chapter 6: Managing the Endpoint Mapper and MAPI Proxies
Policy Support
The Endpoint Mapper proxy supports any policy that applies to TCP tunnel connections.
See “Reference: CPL Triggers, Properties, and Actions” on page 68 for supported CPL
triggers and actions.
Access Logging
Each TCP connection results in an access log entry. Both the Endpoint Mapper proxy and
secondary tunnel traffic activities are logged. The SG appliance main access log format is
used by default.
Note: If the access log for the primary connection changes to a new log, the secondary
connections are also moved to the new log.
For a reference list and descriptions of used log fields, see “Reference: Access Log Fields”
on page 67.
2. Scroll the list of services to display the default Endpoint Mapper service line. Notice
the Action is Bypass. You can select Intercept from the drop-down list, but for the
purposes of this procedures, select the service line to highlight it.
3. Click Edit. The Edit Service dialog appears, with some default settings, is displayed.
65
Volume 2: Proxies and Proxy Services
4a
4b
4c
4d
Note: You can also change the mode from Bypass to Intercept from the main
services page.
e. Click OK.
5. Click Apply.
66
Chapter 6: Managing the Endpoint Mapper and MAPI Proxies
Result: The Endpoint Mapper service is configured and appears in Management Console.
RPC traffic is intercepted.
Statistics
This page displays various, more granular connection and byte statistics.
https://SG_IP_address:8082/epmapper/statistics
Detailed Statistics
This page displays specific client-to-server connection and file information and statistics.
https://SG_IP_address:8082/epmapper/detailed-statistics
67
Volume 2: Proxies and Proxy Services
❐ cs-bytes, sr-bytes, rs-bytes, sc-bytes: Standard ELFF format. The total RPC
byte counts in the specified direction (client-server).
❐ cs-method: Request method used from client to appliance.
❐ s-action: The logging action (or flow) being one of the following:
• ALLOWED: Endpoint operation passed the policy checkpoint and was also
successful.
• DENIED: Endpoint operation failed the policy checkpoint.
• FAILED: Endpoint operation was successful on the server but failed on the proxy
for some internal reason.
• TUNNELED: Traffic was tunneled.
❐ cs-host: Hostname from the client's request URL. If URL rewrite policies are used,
this field's value is derived from the log URL.
❐ cs-port: Port used from the client to the appliance.
❐ s-supplier-name: Hostname of the upstream host (not available for a cache hit).
❐ s-supplier port: Port number of the upstream host (not available for a cache hit).
❐ r-supplier-ip: IP address used to contact the upstream host (not available for a
cache hit).
❐ r-supplier-name: Hostname used to contact the upstream host (not available for a
cache hit).
❐ r-supplier port: Port used to contact the upstream host (not available for a cache
hit).
❐ sc-filter-result: Content filtering result: Denied, Proxied, or Observed.
❐ s-ip: IP address of the appliance on which the client established its connection.
68
Chapter 6: Managing the Endpoint Mapper and MAPI Proxies
69
Volume 2: Proxies and Proxy Services
About MAPI
MAPI is the protocol used by Microsoft Outlook (client) to communicate with Microsoft
Exchange (server), most commonly for e-mail applications. MAPI itself is based on the
Microsoft Remote Procedure Call (RPC).
Because MAPI is based on RPC, it suffers from the same performance inherent with RPC
communications. Microsoft Outlook is the most common enterprise e-mail application. As
enterprises continue to trend toward consolidating servers, which requires more WAN
deployments (branch and remote locations), e-mail application users experience
debilitating response times for not only sending and receiving mail, but accessing
message folders or changing calendar elements. This is because MAPI RPC transmissions
are broken into blocks of data (no more than 32 KB). The client must stop and wait for each
block to arrive before requesting the next block. Each stop represents time lost instead of
data sent.
70
Chapter 6: Managing the Endpoint Mapper and MAPI Proxies
Batching
The MAPI proxy Batching feature reduces the number of RPC messages traversing the
WAN. The branch and core appliances work together to batch multiple RPC messages in a
larger chunk, rather than sending the smaller chunks. Also, the proxy predicts, or reads
ahead, what will be requested next. When the branch proxy receives data chunks, it
begins sending the acknowledgments to the MAPI client to satisfy that requirement of the
communication process.
Keep-Alive
The MAPI proxy Keep-Alive feature allows the SG appliance to maintain the connection
to the Exchange server after the user has logged off from Outlook. Determined by the
configurable interval, the MAPI proxy checks the Exchange server for new mail. ADN
Optimization allows the connection to remain warm so that when the user logs on again to
Outlook, the number of retrieved bytes is lower, allowing for better performance.
The MAPI proxy remembers each user that is logged on or off. If the duration exceeds the
specified limit, or when the user logs back into the mail application, the Keep-Alive
connection is dropped.
For more information about ADN optimization, refer to Volume 5: Advanced Networking.
71
Volume 2: Proxies and Proxy Services
Supported Servers
The MAPI proxy supports:
❐ MAPI 2000 (Outlook/Exchange 2000).
❐ MAPI 2003
Access Logging
The MAPI proxy uses a default access log format. Data includes user actions, data lengths
(bytes), and RPC data.
date, time, c-ip, c-port, r-ip, r-port, x-mapi-user, x-mapi-method,
cs-bytes, sr-bytes, rs-bytes, sc-bytes, x-mapi-sc-rpc-count, x-mapi-
sr-rpc-count, x-mapi-rs-rpc-count, x-mapi-sc-rpc-count, s-action, cs-
username, cs-auth-group, s-ip
For MAPI-specific descriptions, see “Reference: Access Log Fields”.
72
Chapter 6: Managing the Endpoint Mapper and MAPI Proxies
2b
2a
2c
b. Batching: If enabled, MAPI traffic across the WAN is accelerated because data
is chunked and sent as one connection, rather than multiple smaller
connections.
c. Keep-Alive: After a user logs out of Outlook, the MAPI RPC connection
remains and the SG appliance continues to receive incoming messages to this
account. If disabled (the default), no attempts to contact the server occur until
the next time the user logs into his/her Outlook account. This might create a
noticeable decrease in performance, as the queue of unreceived mail is
processed.
• Interval: If Keep-Alive is enabled, how often the MAPI proxy contacts the
Exchange server to check for new messages.
• Duration: If Keep-Alive is enabled, how long the MAPI proxy maintains the
connection to the Exchange server. The connection is dropped if the duration
exceeds this value or once a user logs back in to the mail application.
• Maximum Sessions: Limits the number of occurring active keep-alive sessions.
If a new keep-alive session starts, and the specified limit is already exceeded,
the oldest keep-alive session is dropped.
3. Click OK; click Apply
73
Volume 2: Proxies and Proxy Services
2. View statistics:
a. Select a statistic category tab:
• MAPI Clients Bytes Read: The total number of bytes read by MAPI clients.
• MAPI Clients Bytes Written: The total number of bytes written by MAPI clients.
• MAPI Clients: The total number of connected MAPI clients.
b. The graphs display three time metrics: the previous 60 minutes, the previous
24 hours, and the previous 60 days. Roll the mouse over any colored bar to
view the exact metric.
3. (Optional) You can change the scale of the graph to display the percentage of bar
peaks to display.
74
Chapter 6: Managing the Endpoint Mapper and MAPI Proxies
❐ s-action:
• ALLOWED: The traffic was permitted through.
• SUCCESS: The traffic was successfully proxied, but was not subject to policy.
• DENIED: The traffic was denied by policy.
• SERVER_ERROR: The traffic was dropped because of an error communicating with
the server.
• FAILED: The traffic was dropped because of an error when handling the messages
sent by the client. Or an internal problem with the MAPI proxy.
• BATCHED: The traffic was batched.
• TUNNELED: The traffic was tunneled to the Exchange server for one of two reasons:
• The MAPI traffic is encrypted; therefore, the SG appliance cannot batch
messages or attachments and thus cannot provide WAN optimization benefits.
• The MAPI proxy could not connect upstream through an Application
Delivery Network (ADN) tunnel.
❐ x-cs-mapi-rpc-count: The number of RPCs sent from the client to the proxy.
❐ x-sr-mapi-rpc-count: The number of RPCs sent from the proxy to the server.
❐ x-rs-mapi-rpc-count: The number of RPCs sent from the server to the proxy.
❐ x-sc-mapi-rpc-count: The number of RPCs sent from the proxy to the client.
75
Volume 2: Proxies and Proxy ServicesMA
76
Chapter 7: Managing the FTP Proxy
Blue Coat supports accessing FTP origin content servers over HTTP (Web FTP) as well
as supporting native FTP proxy.
Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
origin content server (OCS) (if the content is not already cached), and then translates
the FTP response with the file contents into an HTTP response for the client.
Native FTP involves the client connecting (either explicitly or transparently) using FTP;
the SG appliance then connects upstream through FTP (if necessary).
Understanding FTP
With Blue Coat’s implementation of FTP, you can control how the SG appliance
responds to FTP client requests. You can also control which IP addresses are used.
This section discusses:
❐ “Passive Mode Data Connections” on page 77
❐ “Understanding IP Reflection for FTP” on page 78
Note: some clients might display an error when PASV is disabled on the SG
appliance, requiring you to manually request PORT mode.
77
Volume 2: Proxies and Proxy Services
The FTP client software controls any messages displayed to the end user as a result of this
response from the SG appliance.
78
Chapter 7: Managing the FTP Proxy
Notes
❐ Internet Explorer does not support proxy authentication for native FTP.
❐ The SG appliance FTP proxy does not support customized exception text; that is, you
can use policy to deny requests, but you can't control the text sent in the error
message.
Note: Web FTP requires an HTTP service, not an FTP service. For information on
configuring an HTTP proxy service, see “Chapter 8: Managing the HTTP Proxy” on page
85.
Note: If you only want to change the proxy’s behavior from bypass (the default) to
intercept, go to the Action column of the Proxy Services pane, select the service whose
behavior you want to change, and select Intercept from the drop-down list. You do
not need to enter New/Edit mode to change this attribute.
79
Volume 2: Proxies and Proxy Services
10
3. If you are creating a new FTP proxy service, enter a meaningful name in the Name
field.
4. Select FTP from the drop-down list under Proxy settings.
5. Configure TCP/IP options:
a. The Early Intercept checkbox cannot be changed for the FTP proxy service.
b. The Reflect Client IP checkbox enables or disables sending of client's IP
address instead of the SG appliance's IP address when connecting to the
origin content server. Note that this setting can be overruled by policy.
6. Configure ADN options:
80
Chapter 7: Managing the FTP Proxy
a. The Enable ADN controls whether ADN is enabled for a specific service.
Enabling ADN does not guarantee the connections are accelerated by ADN.
The actual enable decision is determined by ADN routing (for explicit
deployment) and network setup (for transparent deployment).
Note: ADN supports passive FTP (the data connection is initiated by an FTP
client to an FTP server at the port and IP address requested by the FTP server.
Active FTP, where data connections are initiated by an FTP server to an FTP client
at the port and IP address requested by the FTP client, is not supported.
81
Volume 2: Proxies and Proxy Services
Note: Neither proxy authentication for transparent FTP nor proxy chaining are
supported with the Checkpoint syntax.
Note: The steps below are for a WSFtp client. Other clients vary.
❐ Enable firewall.
❐ Select USER with no logon unless you are doing proxy authentication. In that case,
select USER remoteID@remoteHost fireID and specify a proxy username and password.
82
Chapter 7: Managing the FTP Proxy
Example
The illustration demonstrates a WSFtp client configuration.
Note: Configurable banners are only displayable when FTP is explicitly proxied through
the SG appliance. In transparent deployments, the banner is sent to the client when proxy
authentication is required; otherwise, the banner is forwarded from the FTP server.
Note that the welcome banner text is overridden by the policy property
ftp.welcome_banner(). This is required for explicit proxy requests, when doing
proxy authentication, and also when the policy property
ftp.server_connection(deferred|immediate) is set to defer the connection.
3. Click Apply.
83
Volume 2: Proxies and Proxy Services
Related CPL Syntax to Create Policy that Overrides the Default Banner
<Proxy>
ftp.welcome_banner("message")
If entering text that spans more than one line, use $(crlf) for line breaks.
84
Chapter 8: Managing the HTTP Proxy
By default, an HTTP proxy service, with both explicit and transparent attributes set, is
enabled on port 80. To change the attributes of the proxy service or create new HTTP
proxy services, see “Creating or Editing a Proxy Service” on page 28.
The HTTP proxy is the first line of defense for the SG appliance, controlling all traffic
that arrives on port 80. To control that traffic and improve performance, you can:
❐ Set default caching policies to configure the length of time an object or negative
response is cached, whether objects are always revalidated before being served,
whether server certificates are verified by default, and how headers are parsed. For
more information, see “Understanding Tolerant HTTP Request Parsing” on page
104.
❐ Configure the HTTP proxy as a server accelerator. For more information, see
“Customizing the HTTP Proxy Profile” on page 96.
❐ Set a limit to the maximum bandwidth the SG appliance is allowed to use for
refreshing objects in the background. For more information, see “Setting Default
HTTP Proxy Policy” on page 94.
The HTTP proxy is designed to control Web traffic, providing:
❐ Security
❐ Authentication
❐ Virus Scanning and Patience Pages
❐ Performance
• Default HTTP Proxy Policy
• HTTP Proxy Caching Profiles
• Byte-Range Support
85
Volume 2: Proxies and Proxy Services
86
Chapter 8: Managing the HTTP Proxy
Note: If you only want to change the proxy’s behavior from bypass (the default) to
intercept, go to the Action column of the Proxy Services pane, select the service whose
behavior you want to change, and select Intercept from the drop-down list. You do
not need to enter New/Edit mode to change this attribute.
87
Volume 2: Proxies and Proxy Services
7b
7a
7c
7d
1. If you are creating a new HTTP proxy service, enter a meaningful name in the Name
field.
2. Configure the Proxy Settings options:
88
Chapter 8: Managing the HTTP Proxy
89
Volume 2: Proxies and Proxy Services
90
Chapter 8: Managing the HTTP Proxy
Byte-Range Support
If a client makes a request using the Range: HTTP header, SGOS serves the requested
portions of the file from the cache if byte-range support is enabled (the default). If byte
range support is disabled, all such requests are forwarded to the origin content server and
the response is not cached. For information on using byte-range support to determine
how SGOS handles byte-range requests, see “Configuring HTTP for Bandwidth Gain” on
page 101.
91
Volume 2: Proxies and Proxy Services
Refresh Bandwidth
Refresh bandwidth refers to server-side bandwidth used for all forms of asynchronous
refresh activity. The default configuration is to allow the SG appliance to manage refresh
bandwidth. The SG appliance manages the bandwidth in order to preserve the maximum
freshness of accessed objects. However, sometimes the automatic refresh bandwidth
amount is too high. It is not unusual for refresh bandwidth to spike up occasionally,
depending on access patterns at the time. If necessary, you can impose a limit on refresh
bandwidth. To limit the refresh bandwidth to a specified amount, you must disable
automatic management of the bandwidth and explicitly set a bandwidth limit. Setting the
refresh bandwidth amount too low can lower the estimated freshness of objects in the
cache. If you set the refresh bandwidth amount to zero, the SG appliance does not do
active refresh at all.
For information about configuring refresh bandwidth, see “Configuring Refresh
Bandwidth for the HTTP Proxy” on page 103.
92
Chapter 8: Managing the HTTP Proxy
93
Volume 2: Proxies and Proxy Services
2. In the Do not cache objects larger than field, enter the maximum object size to cache.
The default is 1024 MB. This configuration determines the maximum object size to
store in the SG appliance. All objects retrieved that are greater than the maximum size
are delivered to the client but are not stored in the SG appliance.
94
Chapter 8: Managing the HTTP Proxy
3. In the Cache negative responses for field, enter the number of minutes SGOS stores
negative responses. The default is 0, meaning that the SG appliance does not cache
negative responses and always attempts to retrieve the object.
The OCS might send a client error code (4xx HTTP response) or a server error code
(5xx HTTP response) as a response to some requests. If the SG appliance is configured
to cache such negative responses, it returns that response in subsequent requests for
that page or image for the specified number of minutes. If it is not configured, which
is the default, the SG appliance attempts to retrieve the page or image every time it is
requested.
If you enter a number of minutes into this field, then the response times improve, but
you could receive negative responses to requests that might otherwise have been
served for that period of time.
4. To always verify that each object is fresh upon access, select the Always check with
source before serving object checkbox. Enabling this setting has a significant impact
on performance because HTTP proxy revalidates requested cached objects with the
OCS before serving them to the client, resulting in a negative impact on response
times and bandwidth gain. Therefore, do not enable this configuration unless
absolutely required.
5. If you communicate with an origin content server (OCS) through HTTPS and want
the OCS certificate to be verified, be sure that Verify server certificate for secure
connections is selected.
6. The default is to parse HTTP meta tag headers in HTML documents if the MIME type
of the object is text/HTML. The function of all meta tags is same as the corresponding
HTTP headers.
To disable meta-tag parsing, deselect the checkbox for:
• Parse “cache-control” meta tag
The following sub-headers are parsed when this checkbox is selected: private,
no-store, no-cache, max-age, s-maxage, must-revalidate, proxy-
revalidate.
• Parse “expires” meta tag
• Parse “pragma-no-cache” meta tag
7. Click OK; click Apply.
95
Volume 2: Proxies and Proxy Services
Substitute GET for IMS (if modified since) Disabled Enabled Enabled
Substitute GET for PNC (Pragma no cache) Disabled Enabled Does not change
Substitute GET for IE (Internet Explorer) reload Disabled Enabled Does not change
96
Chapter 8: Managing the HTTP Proxy
Pipeline embedded objects in http [no] pipeline This configuration item applies only to HTML
client request client requests responses. When this setting is enabled, and the object
associated with an embedded object reference in the
HTML is not already cached, HTTP proxy acquires
the object’s content before the client requests the
object. This improves response time dramatically. If
this setting is disabled, HTTP proxy does not acquire
embedded objects until the client requests them.
97
Volume 2: Proxies and Proxy Services
Pipeline redirects for client http [no] pipeline When this setting is enabled, and the response of a
request client redirects client request is one of the redirection responses (such
as 301, 302, or 307 HTTP response code), then HTTP
proxy pipelines the object specified by the Location
header of that response, provided that the redirection
location is an HTML object. This feature improves
response time for redirected URLs. If this setting is
disabled, HTTP proxy does not pipeline redirect
responses resulting from client requests.
Pipeline embedded objects in http [no] pipeline This configuration item applies only to HTML
prefetch request prefetch requests responses resulting from pipelined objects. When this
setting is enabled, and a pipelined object’s content is
also an HTML object, and that HTML object has
embedded objects, then HTTP proxy also pipelines
those embedded objects. This nested pipelining
behavior can occur three levels deep at most. If this
setting is disabled, HTTP proxy does not engage in
nested pipelining behavior.
Pipeline redirects for prefetch http [no] pipeline When this setting is enabled, HTTP proxy pipelines
request prefetch the object specified by a redirect location returned by
redirects a pipelined response. If this setting is disabled, HTTP
proxy does not try to pipeline redirect locations
resulting from a pipelined response.
Substitute Get for IMS http [no] If the time specified by the If-Modified-Since:
substitute if- header in the client’s conditional request is greater
modified-since than the last modified time of the object in the cache, it
is a strong indication that the copy in the cache is
stale. If so, HTTP proxy does a conditional GET to the
OCS, based on the last modified time of the cached
object.
To control this aspect of the SGOS treatment of the
If-Modified-Since: header, disable the
Substitute Get for IMS setting. When this setting is
disabled, a client time condition greater than the last
modified time of the object in the cache does not
trigger revalidation of the object.
However, not all objects necessarily have a last-
modified time specified by the OCS.
98
Chapter 8: Managing the HTTP Proxy
Substitute Get for HTTP 1.1 http [no] HTTP 1.1 provides additional controls to the client
conditionals substitute over the behavior of caches concerning the staleness
conditional of the object. Depending on various Cache-
Control: headers, the SG appliance can be forced to
consult the OCS before serving the object from the
cache. For more information about the behavior of
various Cache-Control: header values, refer to
RFC 2616.
If the Substitute Get for HTTP 1.1 Conditionals setting
is enabled, HTTP proxy ignores the following Cache-
Control: conditions from the client request:
• "max-stale" [ "=" delta-seconds ]
• "max-age" "=" delta-seconds
• "min-fresh" "=" delta-seconds
• "must-revalidate"
• "proxy-revalidate"
Substitute Get for PNC http [no] Typically, if a client sends an HTTP GET request with
substitute pragma- a Pragma: no-cache or Cache-Control: no-
no-cache cache header (for convenience, both are hereby
referred to as PNC), a cache must consult the OCS
before serving the content. This means that HTTP
proxy always re-fetches the entire object from the
OCS, even if the cached copy of the object is fresh.
Because of this, PNC requests can degrade proxy
performance and increase server-side bandwidth
utilization. However, if the Substitute Get for PNC
setting is enabled, then the PNC header from the
client request is ignored (HTTP proxy treats the
request as if the PNC header is not present at all).
Substitute Get for IE reload http [no] Some versions of Internet Explorer issue the
substitute ie- Accept: */* header instead of the Pragma: no-
reload cache header when you click Refresh. When an
Accept header has only the */* value, HTTP proxy
treats it as a PNC header if it is a type-N object. You
can control this behavior of HTTP proxy with the
Substitute GET for IE Reload setting. When this
setting is enabled, the HTTP proxy ignores the PNC
interpretation of the Accept: */* header.
Never refresh before http [no] strict- Applies only to cached type-T objects. When this
expiration expiration refresh setting is enabled, SGOS does not asynchronously
revalidate such objects before their specified
expiration time. When this setting is disabled, such
objects, if they have sufficient relative popularity, can
be asynchronously revalidated and can, after a
sufficient number of observations of changes, have
their estimates of expiration time adjusted
accordingly.
99
Volume 2: Proxies and Proxy Services
Never serve after expiration http [no] strict- Applies only to cached type-T objects. If this setting is
expiration serve enabled, an object is synchronously revalidated before
being served to a client, if the client accesses the object
after its expiration time. If this setting is disabled, the
object is served to the client and, depending on its
relative popularity, may be asynchronously
revalidated before it is accessed again.
Cache expired objects http [no] cache Applies only to type-T objects. When this setting is
expired enabled, type-T objects that are already expired at the
time of acquisition is cached (if all other conditions
make the object cacheable). When this setting is
disabled, already expired type-T objects become non-
cacheable at the time of acquisition.
Enable Bandwidth Gain Mode bandwidth-gain This setting controls both HTTP-object acquisition
{disable | enable} after client-side abandonment and AAR
(asynchronous adaptive refresh) revalidation
frequency.
• HTTP-Object Acquisition
When Bandwidth Gain mode is enabled, if a client
requesting a given object abandons its request, then
HTTP proxy immediately abandons the acquisition
of the object from the OCS, if such an acquisition is
still in progress. When bandwidth gain mode is
disabled, the HTTP proxy continues to acquire the
object from the OCS for possible future requests for
that object.
• AAR Revalidation Frequency
Under enabled bandwidth gain mode, objects that
are asynchronously refreshable are revalidated at
most twice during their estimated time of
freshness. With bandwidth gain mode disabled,
they are revalidated at most three times. Not all
asynchronously refreshable objects are guaranteed
to be revalidated.
The Acceleration Profile tab displays (Normal is the default profile). Text appears at
the bottom of this tab indicating which profile is selected. If you have a customized
profile, this text does not appear.
100
Chapter 8: Managing the HTTP Proxy
Important: If you have a customized profile and you click one of the Use Profile
buttons, no record of your customized settings remains. However, once the SG
appliance is set to a specific profile, the profile is maintained in the event the SG
appliance is upgraded.
2. To select a profile, click one of the three profile buttons (Use Normal Profile, Use
Bandwidth Gain Profile, or Use Portal Profile).
The text at the bottom of the Acceleration Profile tab changes to reflect the new profile.
Note: You can customize the settings, no matter which profile button you select.
3. (Optional) To customize the profile settings, select or deselect any of the checkboxes
(see Table 8-2 for information about each setting).
4. Click OK; click Apply.
101
Volume 2: Proxies and Proxy Services
Note: Enabling or disabling byte-range support can only be configured through the CLI.
102
Chapter 8: Managing the HTTP Proxy
To enable or disable byte-range support, enter one of the following commands at the
(config) command prompt:
SGOS#(config) http byte-ranges
-or-
SGOS#(config) http no byte-ranges
Note: The revalidate pragma-no-cache setting can only be configured through the CLI.
To enable or disable the revalidate PNC setting, enter one of the following commands at
the (config) command prompt:
SGOS#(config) http revalidate-pragma-no-cache
-or-
SGOS#(config) http no revalidate-pragma-no-cache
103
Volume 2: Proxies and Proxy Services
The Refresh bandwidth field displays the refresh bandwidth options. The default
setting is to allow the SG appliance to manage refresh bandwidth automatically.
Important: Blue Coat strongly recommends that you not change the setting from the
default.
104
Chapter 8: Managing the HTTP Proxy
By default, a header line not beginning with a <Tab> or space character must consist of a
header name (which contains no <Tab> or space characters), followed by a colon,
followed by an optional value, or an error is reported. With tolerant request parsing
enabled, a request header name is allowed to contain <Tab> or space characters, and if the
request header line does not contain a colon, then the entire line is taken as the header
name.
A header containing one or more <Tab> or space characters, and nothing else, is
considered ambiguous. Blue Coat does not know if this is a blank continuation line or if it
is the blank line that signals the end of the header section. By default, an ambiguous blank
line is illegal, and an error is reported. With tolerant request parsing enabled, an
ambiguous blank line is treated as the blank line that ends the header section.
From the (config) prompt, enter the following command to enable tolerant HTTP
request parsing (the default is disabled):
SGOS#(config) http tolerant-request-parsing
To disable HTTP tolerant request parsing:
SGOS#(config) http no tolerant-request-parsing
105
Volume 2: Proxies and Proxy Services
Note: You can view current HTTP statistics through the CLI using the show http-
stats command.
Note: The maximum number of objects that can be stored in a SG appliance is affected by
a number of factors, including the SGOS version it is running and the hardware platform
series
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
106
Chapter 8: Managing the HTTP Proxy
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
107
Volume 2: Proxies and Proxy Services
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
108
Chapter 8: Managing the HTTP Proxy
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
109
Volume 2: Proxies and Proxy Services
Note: To suppress the Proxy-Support header globally, use the http force-ntlm
command to change the option. To suppress the header only in certain situations,
continue with the procedures below.
3a
3b
3c
3d
110
Chapter 8: Managing the HTTP Proxy
111
Volume 2: Proxies and Proxy Services
112
Chapter 8: Managing the HTTP Proxy
113
Volume 2: Proxies and Proxy Services
114
Chapter 8: Managing the HTTP Proxy
115
Volume 2: Proxies and Proxy Services
116
Chapter 8: Managing the HTTP Proxy
117
Volume 2: Proxies and Proxy Services
118
Chapter 8: Managing the HTTP Proxy
119
Volume 2: Proxies and Proxy Services
120
Chapter 9: Creating and Editing an HTTPS Reverse Proxy
Service
❐ (If necessary) Creating Certificate Signing Requests (CSRs) that can be sent to
Certificate Signing Authorities (CAs).
❐ Importing server certificates issued by CA authorities for external use and
associate them with the keyring. (Refer to Volume 4: Securing the Blue Coat SG
Appliance.)
-or-
❐ Creating certificates for internal use and associate them with the keyring.
❐ (Optional, if using server certificates from CAs) Importing Certificate Revocation
Lists (CRLs) so the SG appliance can verify that certificates are still valid.
When these steps are complete, you can configure the HTTPS Reverse Proxy service.
A common scenario in using HTTPS Reverse Proxy, which connects the client to the SG
appliance, is in conjunction with HTTPS origination, which is used to connect the
appliance to the origin content server (OCS). For more information on this option, see
Section B: "Configuring HTTP or HTTPS Origination to the Origin Content Server" on
page 125.
This chapter discusses:
❐ Section A: "Configuring the HTTPS Reverse Proxy"
❐ Section B: "Configuring HTTP or HTTPS Origination to the Origin Content Server"
on page 125
121
Volume 2: Proxies and Proxy Services
7b
7a
7c
7d
122
Chapter 9: Creating and Editing an HTTPS Reverse Proxy Service
c. CA Cert List: Use the drop-down list to select any already created list that is
on the system.
d. SSL Versions: Use the drop-down list to select the version to use for this
service. The default is SSL v2/v3 and TLS v1.
e. Verify Client (Used with the Forward Client Certificate option.). Selecting this
checkbox enables the Forward Client Certificate and puts the extracted client
certificate information into the Client-Cert header that is included in the
request when it is forwarded to the origin content server. The header contains
the certificate serial number, subject, validity dates, and issuer (all as
name=value pairs). The actual certificate itself is not forwarded.
f. Forward Client Cert: (Should be used with the Verify Client option.) Selecting
this checkbox puts the extracted client certificate information into a header that is
included in the request when it is forwarded to the OCS.
5. Configure TCP/IP options:
a. Reflect-client-iP: Determines how the client IP address is presented to the
origin server for explicitly proxied requests
b. Early intercept: This option cannot be changed when creating or editing an
HTTPS Reverse Proxy service.
6. Configure ADN options:
a. Enable ADN: Controls whether ADN is enabled for a specific service. Enabling ADN
does not guarantee the connections are accelerated by ADN. The actual enable
decision is determined by ADN routing (for explicit deployment) and network setup
(for transparent deployment)
b. The Optimize Bandwidth checkbox is selected by default if you enabled ADN
optimization during initial configuration. You should de-select the checkbox
if you are not configuring ADN optimization.
123
Volume 2: Proxies and Proxy Services
124
Chapter 9: Creating and Editing an HTTPS Reverse Proxy Service
Steps Steps
• Configure a keyring. • (Optional) Add a forwarding host.
• Configure the SSL client. • (Optional) Set an HTTPS port.
• Configure the HTTPS service. • (Optional) Enable server certificate verification.
Steps: Steps
• Client is explicitly proxied. • Server URL rewrite.
-or-
• Add a forwarding host
• Set an HTTPS port.
• (Optional) Enable server certificate verification.
Using server URL rewrite is the preferred method. For information on rewriting the server
URL, refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
125
Volume 2: Proxies and Proxy Services
server Specifies to use the relative path for URLs in the HTTP
header because the next hop is a Web server, not a
proxy server. Proxy is the default.
The next scenario is useful when the SG appliance is deployed as a reverse proxy. This
scenario is used when it’s not necessary for a secure connection between the proxy and
server. For information on using the SG appliance as a reverse proxy, see “Customizing
the HTTP Proxy Profile” on page 96.
Figure 9-3. Scenario 3: HTTPS Reverse Proxy with HTTP Origination
Steps Steps
• Configure a keyring • Server URL rewrite
• Configure the SSL client -or-
• Configure the HTTPS service • Add a forwarding host (only for SGOS 3.1 or higher)
• Set an HTTP port
Using server URL rewrite is the preferred method. For information on rewriting the server
URL, refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
You can only configure HTTP origination through the CLI. You cannot use the
Management Console.
126
Chapter 9: Creating and Editing an HTTPS Reverse Proxy Service
127
Volume 2: Proxies and Proxy Services
128
Chapter 10: Managing Shell Proxies
Shell proxies are those that provide a shell allowing a client to connect to the SG
appliance. In this version, only a Telnet shell proxy is supported.
Using a shell proxy, you can:
❐ terminate a Telnet protocol connection either transparently or explicitly.
❐ authenticate users either transparently or explicitly.
❐ view the access log.
❐ enforce policies specified by CPL.
❐ communicate though an upstream SOCKS gateway and HTTP proxy using the
CONNECT method.
Within the shell, you can configure the prompt and various banners using CPL
$substitutions. You can also use hard-coded text instead of CPL substitutions
(available substitutions are listed in the table below). The syntax for a CPL substitution
is:
$(CPL_property)
Substitution Description
129
Volume 2: Proxies and Proxy Services
Conditions
• category= • client.protocol=telnet
• client.address= • url.scheme=telnet
Properties
Actions
:
130
Chapter 10: Managing Shell Proxies
❐ Users can only enter up to an accumulated 2048 characters while providing the
destination information. (Previous attempts count against the total number of
characters.)
❐ Connection to an upstream HTTP proxy is not encouraged.
❐ If connections from untrustworthy IP address or subnet are not desired, then a
client IP/subnet-based deny policy must be written.
131
Volume 2: Proxies and Proxy Services
Note: To use Telnet to manage the SG appliance, create a Telnet-Console rather than a
Telnet service. The Telnet service allows you to use Telnet for outbound connections, and
the appliance functions as Shell proxy in that situation. For more information on the
Telnet-Console, see “ Notes on Managing the Telnet Console” on page 21.
Note: If you only want to change the proxy’s behavior from bypass (the default) to
intercept, go to the Action column of the Proxy Services pane, select the service whose
behavior you want to change, and select Intercept from the drop-down list. You do
not need to enter New/Edit mode to change this attribute.
7b
7a
7c
7d
4. In the Name field, choose a meaning name for the new proxy service.
5. In the Proxy settings field, select Telnet.
132
Chapter 10: Managing Shell Proxies
133
Volume 2: Proxies and Proxy Services
2. To set the maximum concurrent connections, select Limit Max Connections. Enter the
number of maximum concurrent connections allowed for this service. Allowed values
are between 1 and 65535.
3. Set the banner settings:
a. To set the Welcome banner message (users see this when they enter the shell),
click View/Edit next to the Welcome Banner. The Edit Welcome Banner dialog
displays. (If you do not want this banner displayed, remove the text.)
134
Chapter 10: Managing Shell Proxies
Change the banner as necessary. The $(realm) text is a CPL variable indicating the
name of the realm. You do not have to use a variable. When finished, click OK.
6. Click Apply to commit the changes to the SG appliance.
7. To set the prompt, click View/Edit next to the Prompt line.
Note: The Shell history statistics are available only through the Management Console.
135
Volume 2: Proxies and Proxy Services
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
Note: The Shell history statistics are available only through the Management Console.
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
136
Chapter 11: Managing a SOCKS Proxy
While SOCKS servers are generally used to provide firewall protection to an enterprise,
they also can be used to provide a generic way to proxy any TCP/IP or UDP protocols.
The SG supports both SOCKSv4/4a and SOCKSv5; however, because of increased
username and password authentication capabilities and compression support, Blue
Coat recommends that you use SOCKS v5.
Note: For Blue Coat compatibility with SOCKS clients, check with customer
support. For information on the Permeo Premium Agent (Permeo PA), see “Using
the Permeo PA SOCKS Client with the Blue Coat SOCKS Server” on page 140
In a typical deployment, the SOCKS proxy works with the Endpoint Mapper proxy and
MAPI handoff. In this deployment, you will:
❐ Create an Endpoint Mapper proxy at the remote office (the downstream proxy) that
intercepts Microsoft RPC traffic and creates dynamic TCP tunnels. Traffic to port
135 is transparently redirected to this service using bridging or L4 switch or
WCCP. For information on creating and enabling an Endpoint Mapper proxy
service, see “Chapter 6: Managing the Endpoint Mapper and MAPI Proxies” on
page 63.
❐ Create any other TCP tunnel proxies you need at the remote office: SMTP, DNS,
and the like. For information on configuring TCP tunnels, see “Chapter 13:
Managing the TCP Tunneling Proxy” on page 171.
❐ Create a SOCKS gateway at the remote office and enable compression for that
gateway. This SOCKS gateway points to a SOCKS proxy located at the main office
location (the upstream proxy, the core of the network). For information on creating
a SOCKS gateway and enabling SOCKS compression, see the SOCKS Gateway
Configuration chapter in Volume 5: Advanced Networking.
❐ Set policy to forward TCP traffic through that SOCKS gateway. You can do this
through the <proxy> layer using either the VPM or CPL. For more information, see
“Using Policy to Control the SOCKS Proxy” on page 140.
Note: If you only want to change the proxy’s behavior from bypass (the default) to
intercept, go to the Action column of the Proxy Services pane, select the service whose
behavior you want to change, and select Intercept from the drop-down list. You do
not need to enter New/Edit mode to change this attribute.
137
Volume 2: Proxies and Proxy Services
3
4
7b
7a
7c
7d
3. If you are creating a new SOCKS proxy service, enter a meaningful name in the Name
field.
4. Configure Proxy Settings options:
a. In the Proxy settings field, select SOCKS from the drop-down menu.
b. Select the Detect Protocol checkbox to automatically detect the protocol being
used. Note that this breaks connections that do not have the client send
information first, but expect the server to respond on connection. It also can
add significant delay if the client does not send specific information, and only
after timing out does it treat the traffic as unknown.
5. Configure TCP/IP options:
a. Reflect Client IP: This option cannot be changed when creating or editing an
SOCKS proxy service.
b. Early intercept: This option cannot be changed when creating or editing an
SOCKS proxy service.
6. The ADN Optimization checkbox is selected by default if you enabled WAN
optimization during initial configuration. You should de-select the checkbox if you
are not configuring a WAN optimization network.
138
Chapter 11: Managing a SOCKS Proxy
2. Fill in the option fields (described below) as needed. The defaults are displayed and
should be sufficient for most purposes.
139
Volume 2: Proxies and Proxy Services
Max-Connections connections Set maximum allowed SOCKS client connections. The default of 0
indicates an infinite number of connections are allowed.
Minimum idle seconds Specifies the minimum timeout after which SOCKS can consider the
timeout connection for termination when the max connections are reached.
Maximum idle seconds Specifies the max idle timeout value after which SOCKS should
timeout terminate the connection.
Using the Permeo PA SOCKS Client with the Blue Coat SOCKS Server
The SG appliance can be used as a SOCKS gateway by the Permeo Premium Agent (PA),
with full licensing support and Dynamic Port Management (DPM) functionality.
The SG appliance supports the Windows Permeo PA SOCKS client version 5.12a,
including those clients that require the special probe license protocol and corresponding
customer ID. Note that each SG appliance can only support PA clients with the same
customer ID.
Licensing the PA SOCKS client on the SG appliance is a two step process:
❐ Get the customer ID from the PA client.
❐ Tell the SG appliance the PA customer ID.
140
Chapter 11: Managing a SOCKS Proxy
Note: The default license setting for the Permeo PA client on the SG appliance is off.
This setting should only be enabled when you are using the PA client.
2. Make a note of the Customer ID number, which is in hex. In the example above the
Customer ID is 1111.
Note: You cannot validate the license through the Management Console.
141
Volume 2: Proxies and Proxy Services
Limitations
❐ Protocol Detection interferes with SOCKS and must be disabled on the SG appliance.
The CPL policy should include the line detect_protocol(no).
❐ SOCKS compression should be disabled when using the PA SOCKS client. The CPL
policy should include the line socks.accelerate(no).
❐ The SG appliance only supports username and password authentication between the
SG appliance and the SOCKS Permeo PA client.
❐ The ping and trace route functions from Permeo PA administrator tool are not
compatible with this release (5.1).
❐ Proxy chaining is not supported between the SG appliance and the Permeo
Application Gateway (ASG).
❐ The policy update feature on the PA is not supported when using the SG appliance.
Note that PA can get policy from the HTTP source as well as the ASG so it can still do
automatic updates from a external Web server.
❐ Only the UPWD authentication method is supported.
Note: The SOCKS history statistics are available only through the Management Console.
142
Chapter 11: Managing a SOCKS Proxy
143
Volume 2: Proxies and Proxy Services
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
144
Chapter 12: Managing the SSL Proxy
HTTPS traffic poses a major security risk to enterprises. Because the SSL content is
encrypted, it can’t be monitored by normal means, allowing users to bring in viruses,
access forbidden sites, or leak business confidential information over the HTTPS
connection on port 443.
The SSL proxy allows you to intercept HTTPS traffic (in explicit and transparent
modes) so that security measures such as authentication, virus scanning and URL
filtering, and performance enhancements such as HTTP caching can be applied to
HTTPS content. Additionally, the SSL proxy allows you to validate server certificates
presented by various HTTPS sites at the gateway and offers information about the
HTTPS traffic in the access log.
The SSL proxy can do the following operations while tunneling HTTPS traffic.
❐ Validate server certificates, including revocation checks using Certificate
Revocation Lists (CRLs).
❐ Check various SSL parameters such as cipher and version.
❐ Log useful information about the HTTPS connection.
When the SSL Proxy is used to intercept HTTPS traffic, it can also:
❐ Cache HTTPS content.
❐ Apply HTTP-based authentication mechanism.
❐ Do virus scanning and URL filtering.
❐ Apply granular policy (such as validating mime type and filename extension).
145
Volume 2: Proxies and Proxy Services
Hostnames in server certificates are important because the SSL Proxy can identify a
Web site just by looking at the server certificate if the hostname is in the certificate.
Most content-filtering HTTPS sites follow the guideline of putting the name of the site
as the common name in the server's certificate.
❐ Verification of revocation status.
To mimic the overrides supported by browsers, the SSL Proxy can be configured to
ignore failures for the verification of issuer signatures and certificate dates and
comparision of the hostname in the URL and the certificate.
The SG appliance trusts all root CA certificates that are trusted by Internet Explorer and
Firefox. This list is updated to be in sync with the latest versions of IE and Firefox.
Checking CRLs
An additional check on the server certificate is done through Certificate Revocations Lists
(CRLs). CRLs are lists that show which certificates are no longer valid; the CRLs are
created and maintained by Certificate Signing Authorities that issued the original
certificates.
Only CRLs that are issued by a trusted issuer can be used by the SG Appliance. The CRL
issuer certificate must exist as CA certificate on the SG Appliance before the CRL can be
imported.
The SG Appliance allows:
❐ One local CRL per certificate issuing authority.
❐ An import of a CRL that is expired; a warning is displayed in the log.
❐ An import of a CRL that is effective in the future; a warning is displayed in the log.
146
Chapter 12: Managing the SSL Proxy
❐ URL filtering (on box and off-box). Blue Coat recommends on box URL/Content
filtering if you use transparent proxy. When the URL is sent off-box for filtering, only
the hostname or IP address of the URL (not the full path) is sent for security reasons.
❐ Filtering based on the server certificate hostname.
❐ Caching.
HTTPS applications that require browsers to present client certificates to secure Web
servers do not work if you are intercepting traffic. Such applications should not be
intercepted by creating a policy rule.
If you intercept HTTPS traffic, be aware that local privacy laws might require you to
notify the user about interception or obtain consent prior to interception. You can use the
HTML Notify User object to notify users after interception. You can use consent
certificates to obtain consent prior to interception. The HTML Notify User is easier;
however, note that the SG Appliance has to decrypt the first request from the user before it
can issue an HTML notification page.
In this configuration, the SSL proxy supports ADN optimization on WAN networks, and
SSL traffic performance can be increased through the byte caching capability offered. The
branch proxy is configured with both ADN optimization and SSL proxy functionality.
The concentrator proxy does not require any configuration related to SSL Proxy. It only
requires the necessary ADN configuration for applying byte caching capabilities to
intercepted SSL content.
No special configuration is done to the SSL proxy. Securing the tunnels and authenticating
the devices is done from the Configuration > App. Delivery Network panes.
147
Volume 2: Proxies and Proxy Services
❐ Configure the Blue Coat AV or other third-party ICAP vendor, if you have not already
done this. For more information on ICAP-based virus scanning, refer to Volume 7:
Managing Content.
❐ Configure the Blue Coat Web Filter (BCWF) or a third-party URL-filtering vendor, if
you have not already done this. For more information on configuring BCWF, refer to
Volume 7: Managing Content.
❐ Configure Access Logging. For more information on configuring access logging, refer
to Volume 8: Access Logging.
❐ To customize exception pages (in case of server certificate verification failure), refer to
Volume 6: VPM and Advanced Policy.
148
Chapter 12: Managing the SSL Proxy
If using SSL proxy in explicit mode, you might need an HTTP proxy or a SOCKS proxy.
For information on configuring an SSL Proxy in explicit mode, see “Setting Up the SSL
Proxy in Explicit Proxy Mode” on page 151.
You can use a TCP Tunnel service in transparent mode to get the same functionality. A
TCP tunnel service is useful when you have a combination of SSL and non-SSL traffic
going over port 443 and you do not want to break the non-SSL traffic. The SSL service
requires that all requests to its port be SSL.
5a, 5b
5c
5d
6
8
149
Volume 2: Proxies and Proxy Services
a. The Early Intercept checkbox cannot be changed for the SSL proxy service.
b. The Reflect Client IP checkbox enables or disables sending of client's IP
address instead of the SG appliance's IP address. Note that this setting is
overruled by policy.
6. Configure ADN options:
a. Enable ADN. Select this checkbox if you want this service to use ADN.
Enabling ADN does not guarantee the connections are accelerated by ADN.
The actual enable decision is determined by ADN routing (for explicit
deployment) and network setup (for transparent deployment).
b. The Optimize Bandwidth checkbox is selected by default if you enabled WAN
optimization during initial configuration. You should de-select the checkbox
if you are not configuring a WAN optimization network.
7. Create a new listener:
a. Click New; if you edit an existing listener, click Edit.
b. Define the IP address option: explicit or the specified address.
c. In the Port Range field, enter the ports on which the service should listen. The
default port for SSL is 443.
d. Select the default behavior for the service: Bypass tells the service to ignore
any traffic. Intercept configures the service to intercept the traffic that is being
proxied.
e. Click OK.
Continue with “Creating an Issuer Keyring for SSL Interception” on page 151.
150
Chapter 12: Managing the SSL Proxy
Note: You can create a new keyring, import a keyring, or select among existing
keyrings. For information on creating a keyring, refer to Volume 4: Securing the Blue
Coat SG Appliance.
1. From the Management Console, select Configuration > Proxy Settings > SSL Proxy.
2. From the drop-down menu, select the keyring you want to use as the issuer keyring.
3. Click Apply.
To configure policy, see “Configuring SSL Rules through Policy” on page 156.
151
Volume 2: Proxies and Proxy Services
Note: You can e-mail the console URL corresponding to the issuer certificate to end
users so that the end-user can install the issuer certificate as a trusted CA.
152
Chapter 12: Managing the SSL Proxy
display.
4. Click a certificate (it need not be associated with a keyring); the File Download
Security Warning displays asking what you want to do with the file.
5. Click Save. When the Save As dialog box displays, click Save; the file downloads.
6. Click Open to view the Certificate properties; the Certificate window displays.
153
Volume 2: Proxies and Proxy Services
7. Click the Install Certificate button to launch the Certificate Import Wizard.
8. Make sure the Automatically select the certificate store based on the type of certificate
radio button is enabled before completing the wizard; the wizard announces when the
certificate is imported.
9. (Optional) To view the installed certificate, go to Internet Explorer, Select Tools >
Internet Options > Contents > Certificates, and open either the Intermediate Certification
Authorities tab or the Trusted Root Certification Authorities tab, depending on the
certificate you downloaded.
Note: You can e-mail the console URL corresponding to the issuer certificate to end
users so that the end-user can install the issuer certificate as a trusted CA.
154
Chapter 12: Managing the SSL Proxy
5. Enable the checkboxes needed. Note that you should view the certificate before
trusting it for any purpose.
6. Click OK; close the Advanced Statistics window.
155
Volume 2: Proxies and Proxy Services
Note: For detailed instructions on using VPM, refer to Volume 6: VPM and Advanced
Policy.
The checkboxes for Issuer Keyring, Hostname, Splash Text, and Splash URL all control
various aspects for certificate emulation. Fill in the fields as follows:
a. Issuer Keyring: If you selected an issuer keyring previously, that keyring
displays. If you did not select an issuer keyring previously, the default
keyring displays. To change the keyring that is used as the issuer keyring,
choose a different keyring from the drop-down menu.
b. Hostname: The hostname you put here is the hostname in the emulated
certificate.
c. Splash Text: You are limited to a maximum of 200 characters. The splash text
is added to the emulated certificate as a certificate extension.
d. Splash URL: The splash URL is added to the emulated certificate as a
certificate extension.
5. Click OK to save the changes.
You can use the Disable SSL Intercept object to disable HTTPS Intercept.
156
Chapter 12: Managing the SSL Proxy
Note: For detailed instructions on using VPM, refer to Volume 6: VPM and Advanced
Policy.
157
Volume 2: Proxies and Proxy Services
5a
5b
5. Fill in the fields as described below. Note that you can only choose one field:
a. Hostname: This is the hostname of the server whose traffic you want to
intercept. After entering the hostname, use the drop-down menu to specify
Exact Match, Contains, At Beginning, At End, Domain, or Regex.
b. Subject: This is the subject field in the server's certificate. After you enter the
subject, use the drop-down menu to specify Exact Match, Contains, At
Beginning, At End, Domain, or Regex.
1. Go to Configuration > Policy > Visual Policy Manager and launch VPM.
2. From the Policy drop-down menu, select Add SSL Access Layer.
3. In the Action column, right-click Set; the Set Action object displays.
4. Click New and select Set Server Certificate Validation object.
5. By default, server certificate validation is enabled; to disable it, select Disable server
certificate validation at the bottom of the dialog.
158
Chapter 12: Managing the SSL Proxy
You can add server certificates to the SG appliance to allow proper validation. For
more information, refer to Volume 4: Securing the Blue Coat SG Appliance.
6. If you want to check the CA certificate revocation list (CRL) from a Certificate
Authority, verify Also check certification revocation is selected. For information on
using CRL, see “Checking CRLs” on page 146.
Note: VPM is much easier to use than CPL. All CPL gestures except the
ssl.forward_proxy.server_keyring property, used only for troubleshooting, are
also in VPM.
The following CPL gestures can be used in the SSL Intercept layer:
• ssl.forward_proxy( ) • ssl.forward_proxy.splash_text( )
• ssl.forward_proxy.hostname( ) • trace.destination( )
• ssl.forward_proxy.issuer_keyring( ) • trace.request( )
• ssl.forward_proxy.server_keyring( ) • trace.rules( )
Allowed Actions
• log_message( ) • notify_snmp( )
• notify_email( )
Allowed Conditions
• category • proxy.port
• client.address • server.certificate.hostname
• client.host • server.certificate.hostname.category
• client.host.has_name • server.certificate.subject
159
Volume 2: Proxies and Proxy Services
• client.protocol • server_url.*
• proxy.address • url.*
• proxy.card
Note: For detailed instructions on using CPL, including detailed explanations of the
gestures listed here, refer to Volume 10: Blue Coat SG Appliance Content Policy Language
Guide
160
Chapter 12: Managing the SSL Proxy
• ssl.proxy_mode= • client.protocol=
tunneled=
Note: For detailed instructions on using CPL, including detailed explanations of the
gestures listed here, refer to Volume 10: Blue Coat SG Appliance Content Policy Language
Guide.
Notes
Note: Pipelining configuration for HTTP is ignored for HTTPS requests intercepted by
the SSL Proxy. When the SSL Proxy intercepts an HTTPS request, and the response is
an HTML page with embedded images, the embedded images are not pre-fetched by
the SG appliance.
❐ If the SG appliance and the origin content server cannot agree on a common cipher
suite for intercepted connections, the connection is aborted.
❐ Server-Gated Cryptography and step-up certificates are treated just as regular
certificates; special extensions present in these certificates are not be copied into the
emulated certificate. Clients relying on SGC/step-up certificates continue using
weaker ciphers between the client and the SG appliance when the SSL Proxy
intercepts the traffic.
161
Volume 2: Proxies and Proxy Services
Note: Some SSL statistics (SSL client connections and total bytes sent and received over a
period of time) can only be viewed through the Management Console (see "Unintercepted
SSL Data" on page 162 and "Unintercepted SSL Clients" on page 163, below).
Status Description
Current Unintercepted SSL Sessions The current number of unintercepted SSL client
connections.
Total Unintercepted SSL Sessions The cumulative number of unintercepted SSL client
connections since the SG appliance was last rebooted.
162
Chapter 12: Managing the SSL Proxy
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
163
Volume 2: Proxies and Proxy Services
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
164
Chapter 12: Managing the SSL Proxy
Installing OpenSSL
After OpenSSL is installed, you must edit the openssl.cnf file and ensure the
pathnames are correct. By default root certificates are located under ./PEM/DemoCA;
generated certificates are located under /certs.
165
Volume 2: Proxies and Proxy Services
.....................................+++++
................................................+++++
writing new private key to
'c:\resources\ssl\openssl\bin\PEM\demoCA\private\cakey.pem'
Enter PEM pass phrase:
2. Type any string more than four characters for the PEM pass phrase.
3. Enter the certificate parameters, such as country name, common name that are
required for a Certificate Signing Request (CSR).
The private key and root CA are now located under the directory ./PEM/DemoCA/
private
4. Create a SG keyring.
a. From the Management Console, select Configuration > SSL > Keyrings.
b. Click Create; fill in the fields as appropriate.
c. Click OK.
5. Create a CSR on the SG appliance.
a. From the Management Console, select Configuration > SSL > Keyrings.
b. Highlight the keyring you just created; click Edit/View.
c. In the Certificate Signing Request pane, click Create and fill in the fields as
appropriate.
6. Paste the contents of the CSR into a text file called new.pem located in the ./bin
directory.
166
Chapter 12: Managing the SSL Proxy
localityName :PRINTABLE:'Paris'
organizationName :PRINTABLE:'BlueCoat'
organizationalUnitName:PRINTABLE:'Security Team'
commonName :PRINTABLE:'SG.bluecoat.com'
emailAddress :IA5STRING:'support@bc.com'
Certificate is to be certified until Sep 27 13:29:09 2006 GMT (365
days)
Sign the certificate? [y/n]:y
1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated
This signs the certificate; it can then be imported into the SG appliance.
167
Volume 2: Proxies and Proxy Services
168
Chapter 12: Managing the SSL Proxy
3. Select the keyring that has the CSR created; click Edit/View.
Note: Make sure this keyring is used as the issuer keyring for emulated certificates.
Use policy or the SSL intercept setting in the Management Console or the CLI.
169
Volume 2: Proxies and Proxy Services
170
Chapter 13: Managing the TCP Tunneling Proxy
Note: The TCP-Tunnel service does not support content filtering with Websense offbox
or ICAP.
Note: If you only want to change the proxy’s behavior from bypass (the default)
to intercept, go to the Action column of the Proxy Services pane, select the service
whose behavior you want to change, and select Intercept from the drop-down list.
You do not need to enter New/Edit mode to change this attribute.
171
Volume 2: Proxies and Proxy Services
3
4
7b
7a
7c
7d
3. In the Name field, choose a meaning name for the new proxy service.
4. Configure the Proxy Settings options:
a. In the Proxy drop-down list, select TCP-tunnel.
b. Select Detect Protocol checkbox to automatically detect the protocol being
used. Note that this breaks connections that do not have the client send
information first, but expect the server to respond on connection. It also can
add significant delay if the client does not send specific information.
5. Configure TCP/IP options:
a. Reflect Client IP: Enables or disables sending of client's IP address instead of
the SG appliance's IP address.
b. Early intercept: Controls whether the proxy responds to client TCP connection
requests before connecting to the upstream server. When early intercept is
disabled, the proxy delays responding to the client until after it has attempted
to contact the server.
172
Chapter 13: Managing the TCP Tunneling Proxy
173
Volume 2: Proxies and Proxy Services
174
Appendix A: Glossary
access log A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.
account A named entity that has purchased the appliance or the Entitlements from Blue Coat.
activation code A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.
active content stripping Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.
active content types Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user
administration access policy A policy layer that determines who can access the SG appliance to perform
administrative tasks.
administration A policy layer that determines how administrators accessing the SG appliance must
authentication policy authenticate.
AJAX Acronym for Asynchronous JavaScript and XML, the technology used for live
updating of Web pages without having to reload the entire page.
Application Delivery A WAN that has been optimized for acceleration and compression by Blue Coat. This
Network (ADN) network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.
ADN backup manager Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.
ADN manager Responsible for publishing the routing table to SG Clients (and to other SG
appliances).
ADN optimize attribute Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
asx rewrite Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxy-
like support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.
175
Volume 2: Proxies and Proxy Services
audit A log that provides a record of who accessed what and how.
authenticate-401 attribute All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios
authenticated content Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).
authentication Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate Authority.
See also basic authentication, proxy authentication, and SSL authentication.
authentication realm Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.
bandwidth class hierarchy Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.
bandwidth management Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.
basic authentication The standard authentication for communicating with the target as identified in the
URL.
BCAAA Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.
byte-range support The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).
cache An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.
176
Appendix A: Glossary
cache control Allows you to configure which content the SG appliance stores.
cache efficiency A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.
cache hit Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.
cache miss Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .
cache object Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.
Certificate Authority (CA) A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.
child class (bandwidth gain) The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.
client consent certificates A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.
client-side transparency A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.
concentrator An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.
content filtering A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.
default boot system The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.
177
Volume 2: Proxies and Proxy Services
denial of service (DoS) A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.
destination objects Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.
detect protocol attribute Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
diagnostic reporting Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.
directives Commands used in installable lists to configure forwarding and SOCKS gateway.
DNS access A policy layer that determines how the SG appliance processes DNS requests.
domain name system (DNS) An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.
dynamic bypass Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.
dynamic real-time rating Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
(DRTR) dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.
early intercept attribute Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.
ELFF-compatible format A log type defined by the W3C that is general enough to be used with any protocol.
emulated certificates Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.
encrypted log A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.
178
Appendix A: Glossary
event logging Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.
explicit proxy A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.
extended log file format A variant of the common log file format, which has two additional fields at the end of
(ELFF) the line—the referer and the user agent fields.
fail open/closed Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.
forward proxy A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.
gateway A device that serves as entrance and exit into a communications network.
hardware serial number A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.
179
Volume 2: Proxies and Proxy Services
health check tests The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
ICMP
TCP
SSL
HTTP
HTTPS
Group
Composite and reference to a composite result
ICAP
Websense
DRTR rating service
health check type The kind of device or service the specific health check tests. The following types are
supported:
Forwarding host and forwarding group
SOCKS gateway and SOCKS gateway group
CAP service and ICAP service group
Websense off-box service and Websense off-box service group
DRTR rating service
User-defined host and a user-defined composite
heartbeat Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.
host affinity The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.
host affinity timeout The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.
inbound traffic (bandwidth Network packets flowing into the SG appliance. Inbound traffic mainly consists of
gain) the following:
Server inbound: Packets originating at the origin content server (OCS) and sent to the
SG appliance to load a Web object.
Client inbound: Packets originating at the client and sent to the SG appliance for Web
requests.
180
Appendix A: Glossary
installable lists Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
Creating the list using the SG text editor
Placing the list at an accessible URL
Downloading the directives file from the local system
integrated host timeout An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.
intervals Time period from the completion of one health check to the start of the next health
check.
IP reflection Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.
issuer keyring The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.
licensable component (LC) (Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.
license Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.
listener The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.
live content Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.
load balancing A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.
local bypass list A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.
local policy file Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).
log facility A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.
181
Volume 2: Proxies and Proxy Services
log format The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.
log tail The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.
Management Console A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.
management information Defines the statistics that management systems can collect. A managed device
base (MIB) (gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.
maximum object size The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.
MIME/FILE type filtering Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.
multi-bit rate The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).
multicast Used in streaming; the ability for hundreds or thousands of users to play a single
stream.
multicast aliases Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel
multicast station Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).
multimedia content services Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.
182
Appendix A: Glossary
name inputing Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server
native FTP Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).
NCSA common log format Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.
network address translation The process of translating private network (such as intranet) IP addresses to Internet
(NAT) IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.
non-cacheable objects A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
Password provided, requests that include a client password.
Data in request that include additional client data.
Not a GET request.
.nsc file Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.
NTP To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.
object (used in caching) An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.
object (used in Visual Policy An object (sometimes referred to as a condition) is any collection or combination of
Manager) entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.
object pipelining This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.
183
Volume 2: Proxies and Proxy Services
origin content server (OCS) Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.
outbound traffic (bandwidth Network packets flowing out of the SG appliance. Outbound traffic mainly consists
gain) of the following:
Client outbound: Packets sent to the client in response to a Web request.
Server outbound: Packets sent to an OCS or upstream proxy to request a service.
PAC (Proxy Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
AutoConfiguration) scripts port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.
packet capture (PCAP) Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.
parent class (bandwidth A class with at least one child. The parent class must share its bandwidth with its
gain) child classes in proportion to the minimum/maximum bandwidth values or priority
levels.
passive mode data Data connections initiated by an FTP client to an FTP server.
connections (PASV)
policies Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.
policy-based bypass list Used in policy. Allows a bypass based on the properties of the client, unlike static and
dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.
policy layer A collection of rules created using Blue Coat CPL or with the VPM.
pragma: no cache (PNC) A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).
proxy Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.
184
Appendix A: Glossary
proxy service The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.
proxy service (default) The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.
public key certificate An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).
public virtual IP (VIP) Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.
real-time streaming protocol A standard method of transferring audio and video and other time-based media over
(RTSP) Internet-technology based networks. The protocol is used to stream clips to any RTP-
based client.
reflect client IP attribute Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.
registration An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.
remote authentication dial- Authenticates user identity via passwords for network access.
in user service (RADIUS)
reverse proxy A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.
routing information protocol Designed to select the fastest route to a destination. RIP support is built into Blue
(RIP) Coat appliances.
router hops The number of jumps a packet takes when traversing the Internet.
secure shell (SSH) Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.
185
Volume 2: Proxies and Proxy Services
serial console A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.
server certificate categories The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.
server portals Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping a
set of external URLs onto a set of internal URLs.
server-side transparency The ability for the server to see client IP addresses, which enables accurate client-
access records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.
service attributes Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .
SG appliance A Blue Coat security and cache box that can help manage security and content on a
network.
sibling class (bandwidth A bandwidth class with the same parent class as another class.
gain)
simple network The standard operations and maintenance protocol for the Internet. It uses MIBs,
management protocol created or customized by Blue Coat, to handle (needs completion).
(SNMP)
simulated live Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.
SmartReporter log type A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.
SOCKS A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.
SOCKS proxy A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.
splash page Custom message page that displays the first time you start the client browser.
split proxy Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
Mapi Proxy
SSL Proxy
186
Appendix A: Glossary
SQUID-compatible format A log type that was designed for cache statistics and is compatible with Blue Coat
products.
squid-native log format The Squid-compatible format contains one line for each request.
SSL authentication Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).
SSL proxy A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.
static route A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.
statistics Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated, cache
efficiency, cached contents, and custom URLs generated by the appliance for various
kinds of logs. You can also check the event viewer for every event that occurred since
the appliance booted.
stream A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.
SurfControl log type A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.
system cache The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.
time-to-live (TTL) value Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.
187
Volume 2: Proxies and Proxy Services
traffic flow Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
(bandwidth gain) that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of these
connections, traffic flows in two directions—in one direction, packets flow out of the
SG appliance (outbound traffic), and in the other direction, packets flow into the SG
(inbound traffic). Connections can come from the client or the server. Thus, traffic can
be classified into one of four types:
Server inbound
Server outbound
Client inbound
Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.
transmission control TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
protocol (TCP) in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.
transparent proxy A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.
trial period Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.
unicast alias Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicast-
alias command to request the content from the origin streaming server.
universal time coordinates An SG appliance must know the current UTC time. By default, the appliance
(UTC) attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.
URL rewrite rules Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.
WCCP Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.
188
Appendix A: Glossary
Web FTP Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
OCS (if the content is not already cached), and then translates the FTP response with
the file contents into an HTTP response for the client.
Websense log type A Blue Coat proprietary log type that is compatible with the Websense reporter tool.
189
Volume 2: Proxies and Proxy Services
190
Appendix B: Explicit and Transparent Proxy
Note: While you must configure proxying to do authentication, verify the proxy is
configured correctly and is functioning before adding authentication to the mix. Many
network or other configuration problems can appear similar to authentication errors.
191
Volume 2: Proxies and Proxy Services
For information on creating an explicit proxy server, regardless of proxy type, continue
with “ Creating an Explicit Proxy Server” on page 192.
192
Appendix B: Explicit and Transparent Proxy
From Firefox:
1. Select Tools > Options > Genera l> Connection Settings.
2. Click Manual proxy configuration.
3. Enter proxy server IP addresses and port numbers for services such as HTTP, FTP,
SOCKS, and SSL.
4. Click OK.; click OK again.
Transparent Proxies
A transparent proxy can be configured several ways:
❐ Through hardware: See “Configuring Transparent Proxy Hardware” on page 193.
❐ Through bridging: “Bridging” on page 194.
❐ Through using the SG appliance as a gateway: See “Configuring IP Forwarding” on
page 195.
In addition to the transparent proxy configuration, you must create a proxy service for the
transparent proxy and enable the service. At this time, you can also set other attributes for
the service, including the destination IP address and port range. For information on
creating or editing a proxy service for transparent configuration, see Chapter 3: "About
Proxy Services" on page 23.
193
Volume 2: Proxies and Proxy Services
Bridging
Network bridging through the SG appliance provides transparent proxy pass-through
and failover support. This functionality allows SG appliances to be deployed in
environments where L4 switches and WCCP-capable routers are not feasible options.
The SG appliance provides bridging functionality by two methods:
❐ Software—A software, or dynamic, bridge is constructed using a set of installed
interfaces. Within each logical bridge, interfaces can be assigned or removed. Note
that the adapters must of the same type. Although the software does not restrict you
from configuring bridges with adapters of different types (10/100 or GIGE), the
resultant behavior is unpredictable.
To set up a software bridge, refer to Volume 1: Getting Started.
❐ Hardware—The Blue Coat Pass-Through card is a 10/100 dual interface Ethernet
device that enables a bridge, using its two adapters, so that packets can be forwarded
across it. However, if the system crashes, the Pass-Through card becomes a network:
the two Ethernet cables are connected so that traffic can continue to pass through
without restriction.
When the Pass-Through card is installed on the SG appliance, a bridge is
automatically created and traffic going through the bridge is intercepted according to
the proxy-service setting. Note that:
• Forwarding traffic behavior: By default, the bridge forwards packets that are not
to be intercepted.
• Proxy request behavior: Requests are proxied on either adapter, so if you connect
one side of the bridge to your Internet connection, there might be a number of
issues.
194
Appendix B: Explicit and Transparent Proxy
Configuring IP Forwarding
IP Forwarding is a special type of transparent proxy. The SG appliance is configured to act
as a gateway and is configured so that if a packet is addressed to the SG adapter, but not
its IP address, the packet is forwarded toward the final destination. If IP forwarding is
disabled, the packet is rejected as being mis-addressed.
By default, IP forwarding is disabled to maintain a secure network.
Important: When IP forwarding is enabled, be aware that all SG ports are open and all
the traffic coming through them is not subjected to policy, with the exception of the
ports that have explicitly defined through the Configuration > Services > Proxy Services
tab.
To enable IP forwarding:
1. Select Configuration > Network > Routing > Gateways.
2. Select the Enable IP forwarding checkbox.
3. Click OK; click Apply.
195
Volume 2: Proxies and Proxy Services
196
Index
197
Volume 2: Proxies and Proxy Services
198
Index
SOCKS proxy T
bind timeout on accept value 140 TCP-Tunnel
configuring 139 commands, explicit 174
connection timeout values 140 explicit 171
max-connection values 140 overview 171
max-idle-timeout value 140 Telnet
min-idle-timeout 140 banner settings, configuring 133
SSH proxy boundary conditions 135
client settings, customizing 133
keypairs, importing 19 shell proxy
managing 18 creating service 131
configuring 18 understanding 131
SSL proxy Telnet console
Add Server Certificate object, configuring 158 error message 21
Add SSL Forward Proxy object, configuring 156 port service, explained 21
categorizing hostnames in server certificates 157 troubleshooting 21
client consent certificates, using 152 tolerant request parsing, setting through CLI 104
explicit mode, configuring 151 transparent proxy
HTTPS hardware, configuring 193
content, intercepting 156 IP forwarding 195
traffic, intercepting 148 IP forwarding, enabling 195
issuer certificates for desktops, downloading 152 Layer-4 switch, using with 194
rules, configuring 156 overview 191
Server Certificate Category object, using 157 troubleshooting
Set Server Certificate Validation object, using 158 explicit proxy and Internet Explorer 110
SSL Access layer, using 157 Telnet console 21
SSL Intercept layer trust destination IP
configuring through CPL 159 configuring behavior 41
using 156
statistics U
unintercepted SSL byte 163 user license limits
unintercepted SSL client 163 behavior if exceeded 39
unintercepted SSL data 162 concurrent users, viewing 41
transparent mode, configuring 148 configuring behavior 41
understanding 145 license metrics, viewing 39
statistics managing 38
active client connections 107 notifications, setting 39
HTTP/FTP bytes served 107
objects served 106 W
SOCKS clients, viewing 142 Web FTP
SSL proxy troubleshooting 111
unintercepted SSL bytes 163 understanding 77
unintercepted SSL clients 163 welcome banner, Telnet, customizing for 133
unintercepted SSL data 162
199
Volume 2: Proxies and Proxy Services
200
Blue Coat® Systems
SG™ Appliance
Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
ii
Contents
Contact Information
Chapter 1: Introduction
Document Conventions......................................................................................................................................7
iii
Volume 3: Web Communication Proxies
iv
Contents
Appendix A: Glossary
Index
v
Volume 3: Web Communication Proxies
vi
Chapter 1: Introduction
A proxy filters traffic, monitors Internet and intranet resource usage, blocks or allows
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
The Blue Coat SG appliance Instant Messaging (IM) proxies allow you to control, track,
and record communications that occur over AOL, MSN, or Yahoo IM clients on your
corporate networks. The Streaming proxies allow you to alter allowed bandwidth and
manage the broadcasts of streaming content over Microsoft and RealNetworks (with
limited support for Apple) protocols.
This document contains the following chapters:
❐ Chapter 2: "Managing Instant Messaging Protocols" on page 9
❐ Chapter 3: "Managing Streaming Media" on page 33
Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Conventions Definition
Courier font Command line text that appears on your administrator workstation.
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.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
7
Volume 3: Web Communication Proxies
8
Chapter 2: Managing Instant Messaging Protocols
This chapter discusses how to control Instant Messaging (IM) activity through the SG
appliance.
Notes
❐ AOL and Yahoo clients lose certain features when connected through HTTP proxy
rather than through SOCKS or transparent connections:
❐ AOL—Direct connections, file transfers, and files sharing are not available.
❐ Yahoo—Client cannot create a chat room.
9
Volume 3: Web Communication Proxies
Notes
Consider the following proxy authentication notes, which apply to IM clients using HTTP
proxy:
❐ AOL IM—Proxy authentication is supported.
❐ MSN IM (5.0 and above)—The SG appliance supports MSN/Live Messenger if the
appliance is configured to use HTTP ProxyAuth code 407, not HTTP auth code 401.
❐ Yahoo IM—Yahoo IM clients do not have proxy authentication configuration abilities.
Access Logging
Access log entries occur from various IM actions, such as logging on or joining a chat
room. By default, the SG appliance uses the Blue Coat IM access log format:
date time c-ip cs-username cs-auth-group cs-protocol x-im-method x-im-
user-id x-im-user-name x-im-user-state x-im-client-info x-im-buddy-id
x-im-buddy-name x-im-buddy-state x-im-chat-room-id x-im-chat-room-type
x-im-chat-room-members x-im-message-text x-im-message-size x-im-
message-route x-im-message-type x-im-file-path x-im-file-size s-action
For a reference list and descriptions of used log fields, see “Reference: Access Log Fields”
on page 28.
Managing Skype
Skype is the most used IM service outside of the United States. It provides free PC-to-PC
calling using VoIP. Skype communication is based on Peer-to-Peer technology. Managing
Skype communications requires the creation of firewall and SG appliance policies,
procedures that are outside the scope of this chapter.
See the Blue Coat Controlling Skype Technical Brief, available on the Blue Coat Web site
Download page.
Recommended Deployments
Blue Coat recommends the following deployments:
❐ For large networks with unimpeded Internet access, Blue Coat recommends
transparently redirecting the IM protocols to the SG appliance, which requires the SG
appliance bridging feature or an L4 switch or WCCP.
❐ For networks that do not allow outbound access, Blue Coat recommends using the
SOCKS proxy and configuring policy and content filtering denials for HTTP requests
to IM servers.
10
Chapter 2: Managing Instant Messaging Protocols
11
Volume 3: Web Communication Proxies
12
Chapter 2: Managing Instant Messaging Protocols
Figure 2-3. Proxy chaining deployment with fail open/fail closed policies.
13
Volume 3: Web Communication Proxies
Configuring IM Services
Defaults:
❐ Proxy Edition: Upon upgrade and on new systems, the SG appliance has IM services
configured for transparent connections on the following ports:
• AOL-IM: 5190
• MSN-IM: 1863 and 6891
• Yahoo-IM: 5050 and 5101
❐ MACH5 Edition: IM services are not created and are not included in trend data.
Notes:
❐ MSN port 1863 and Yahoo port 5050 are the default client login ports. MSN port 6891
and Yahoo port 5101 are the default for client-to-client direct connections and file
transfers. If these ports are not enabled:
❐ Client-to-client direct connections do not occur.
❐ After a file transfer request is allowed by the SG appliance, the resulting data is sent
directly from one client to another without passing through the SG appliance:
• For MSN: The above bullet point only applies to MSN version previous to and
including 6.0. Post-6.0 versions use a dynamic port for file transfers; therefore,
port 6891 is not required for the SG appliance to intercept file transfers.
• For Yahoo: The above bullet only applies to standard file transfer requests. Port
5101 must be enabled to allow file list requests.
Note: All file transfers for AOL clients are handled through the default (5190) or
specified client login port.
By default, these services are configured be Transparent and in Bypass mode. The
following procedure describes how to change them to Intercept mode, and explains other
attributes within the service.
14
Chapter 2: Managing Instant Messaging Protocols
2. Scroll the list of services to display the default one of the IM service lines (this
example uses Yahoo). Notice the Action is Bypass. You can select Intercept from the
drop-down list, but for the purposes of this procedures, select the service line to
highlight it.
3. Click Edit. The Edit Service dialog appears with the default settings displays.
15
Volume 3: Web Communication Proxies
4a
4b
4c
Note: You can also change the mode from Bypass to Intercept from the main
services page.
d. Click OK.
5. Click Apply.
Result: The IM service status appears in Management Console.
16
Chapter 2: Managing Instant Messaging Protocols
2b
2a
17
Volume 3: Web Communication Proxies
6. Click Apply.
Result: IM clients regard the SG
appliance as the IM server.
Remain on this screen and continue to the next section.
18
Chapter 2: Managing Instant Messaging Protocols
Configuring IM Alerts
A SG appliance IM alert is an IM message sent to clients upon an action triggered by
policy. An IM alert contains two elements:
❐ Admin buddy names: You can assign an administrator buddy name for each client
type. An administrator buddy name can be a registered name user handle or a
fictitious handle. The benefit of using a registered name is that users can send IM
messages to the administrator directly to report any issues, and that communication
can be logged for tracking and record-keeping. By default, the SG appliance assigns
each IM protocol the admin buddy name: Blue Coat SG appliance.
❐ Exception message delivery method: Alert messages can be delivered in the same
window or spawn a new window.
3a
3b
2. In the Admin buddy names field, enter the handle or handles to represent the
administrator. In this example, the company sanctions AOL Messenger as the one
used for internal communications. IM alerts are sent from Example Corp IT. MSN and
Yahoo are acceptable for personal use, but a created policy denies file transfers. Alerts
are sent from Example Corp HR.
3. Specify the exceptions message delivery method:
a. Send exception messages in a separate window (out-of-band)—If an exception
occurs, the user receives the message in a separate IM window.
b. Send exception messages in the existing window (in-band)—If an exception
occurs, the message appears in the same IM window. The message appears to
be sent by the buddy on the other end, with the exception that when in a chat
room, the message always appears to be sent by the configured Admin buddy
name. You can enter a prefix message that appears in the client window
before the message. For example: Inappropriate IM use. Refer to Employee
Conduct Handbook concerning Internet usage.
19
Volume 3: Web Communication Proxies
4. Click Apply.
SG appliance IM proxy configuration is complete. The final step is to configure IM clients
to send traffic to the SG appliance.
Configuring IM Clients
This section describes how to configure the IM clients to send traffic through the SG
appliance.
General Configuration
As each IM client has different menu structures, the procedures to configure them differ.
This section provides the generic tasks that need to be completed.
Explicit Proxy
Perform the following tasks on the IM client:
1. Navigate to the Connection Preferences dialog.
2. Select Use Proxies.
3. Select proxy type as SOCKS V5.
4. Enter the SG appliance IP address.
5. Enter the SOCKS port number; the default is 1080.
6. Enter authentication information, if required.
Transparent Proxy
IM clients do not require any configuration changes for transparent proxy. An L4 switch
or inline SG appliance routes the traffic.
Note: This example uses AOL Messenger 5.9. Other versions might vary.
20
Chapter 2: Managing Instant Messaging Protocols
3a
3b
2a
3c
3d
3e
2b
21
Volume 3: Web Communication Proxies
Note: This example uses MSN Messenger 7.5. Other versions might vary.
3a
3b
2a
3c
2b
2. Navigate to Settings:
a. Click Connection.
b. Click Advanced Settings. The Settings dialog appears.
3. Configure the proxy settings:
a. In the SOCKS field, enter the SG appliance IP address. If the default port is
1080, accept it; if not, change it to port 1080.
b. If authentication is required on the SG appliance, enter the authentication
user name and password.
c. Click OK.
4. Click OK to close the Options dialog. Result: the MSN client now sends traffic to the
SG appliance.
22
Chapter 2: Managing Instant Messaging Protocols
Note: This example uses Yahoo Messenger 7.0. Other versions might vary.
2b
2a
2d
2c
2e
2f
Notes
If Yahoo Messenger is configured for explicit proxy (SOCKS) through the SG appliance,
the IM voice chat feature is disabled. Any client attempting a voice chat with a client
behind the SG appliance firewall receives an error message. The voice data stream is
carried by default on port 5001; therefore, you can create and open this port and configure
Yahoo IM to use transparent proxy. However, the SG appliance only supports the voice
data in pass-through mode.
23
Volume 3: Web Communication Proxies
Policy Examples
After the IM clients are configured to send traffic through the SG appliance, you can
control and limit IM activity. The Visual Policy Manager (VPM) allows you to create rules
that control and track IM communications, including IM activities based on users and
groups, IM handle, chat room handle, file name, and other triggers.
To learn about the VPM, refer to Volume 7: VPM and Advanced Policy.
2a
2c
2b
1. In the VPM, select Policy > Add Web Access Layer; name it IM_File_Transfer.
2. Create a new IM user object:
a. Right-click the Source field; select Set. The Set Source Object dialog appears.
b. Click New; select IM User. The Add IM User Object dialog appears.
c. In the IM User field, enter Nigel1; click OK in each dialog.
24
Chapter 2: Managing Instant Messaging Protocols
3a
3c
3b
25
Volume 3: Web Communication Proxies
6. From the Substitution Variables list, select x-im-buddy-name and click insert. Repeat for
x-im-file-path and x-im-file-size. Click OK in each dialog.
26
Chapter 2: Managing Instant Messaging Protocols
2a
2b
7. In the Alert Text field, enter a message that appears to users. For example, Employee
notice: Your Instant Messaging activity is tracked and logged.
8. Click OK to close the dialog; click OK to insert the object in the rule.
9. Click Install Policy.
27
Volume 3: Web Communication Proxies
❐ x-im-chat-room-type: The chat room type, one of public or public, and possibly
invite_only, voice and/or conference.
❐ x-im-chat-room-members: The list of chat room member IDs.
28
Chapter 2: Managing Instant Messaging Protocols
Triggers
❐ im.buddy=
❐ im.chat_room.conference=
❐ im.chat_room.id=
❐ im.chat_room.invite_only=
❐ im.chat_room.type=
❐ im.chat_room.member=
❐ im.chat_room.voice_enabled=
❐ im.client=
❐ im.file.extension=
❐ im.file.name=
❐ im.file.path=
❐ im.file.size=
❐ 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=
IM History Statistics
The IM statistics allow you to track IM connections, file transfers, and messages that are
currently in use and in total, or have been allowed and denied. The information can be
displayed for each IM client type or combined.
29
Volume 3: Web Communication Proxies
2. The default protocol is All. To select a specific protocol, select AOL, MSN, or Yahoo from
the drop-down list.
Note: The IM activity data statistics are available only through the Management Console.
30
Chapter 2: Managing Instant Messaging Protocols
2. The default protocol is All. To select a specific protocol, select AOL, MSN, or Yahoo from
the drop-down list.
IM Clients Tab
The IM Clients tab displays dynamic graphical statistics for connections over 60 minutes,
24 hours and 30 days. The page displays all values in the graph or clip a percentage of
peak values. When peak values are clipped by a percentage, that percentage is allowed to
fall off the top of the scale.
For example, if you clip 25% of the peaks, the top 25% of the values are allowed to exceed
the scale for the graph, showing greater detail for the remaining 75% of the values.
Move the cursor over the graphs to dynamically display the color-coded AOL, MSN,
Yahoo, and total statistics.
Note: The IM clients statistics are available only through the Management Console.
31
Volume 3: Web Communication Proxies
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
32
Chapter 3: Managing Streaming Media
33
Volume 3: Web Communication Proxies
34
Chapter 3: Managing Streaming Media
Note: Blue Coat recommends not deploying a Helix proxy between the SG
appliance and a Helix server where the Helix proxy is the parent to the SG appliance.
This causes errors with the Helix server. The reverse is acceptable (using a Helix
proxy as a child to the SG appliance).
35
Volume 3: Web Communication Proxies
Client-side
❐ RTP over unicast UDP (RTSP over TCP, RTP over unicast UDP)
❐ Interleaved RTSP (RTSP over TCP, RTP over TCP on the same connection)
❐ RTP over multicast UDP (RTP over multicast UDP; for live content only)
Server-side
❐ Interleaved RTSP
Server-side RTP over UDP is not supported. If policy directs the RTSP proxy to use HTTP
as server-side transport, the proxy denies the client request. The client then rolls over to
MMS or HTTP.
36
Chapter 3: Managing Streaming Media
Client-Side
❐ RDT over unicast UDP (RTSP over TCP, RDT over unicast UDP)
❐ Interleaved RTSP (RTSP over TCP, RDT over TCP on the same connection)
❐ RDT over multicast UDP (RTSP over TCP, RDT over multicast UDP; for live content
only)
❐ HTTP streaming (RTSP and RDT over TCP tunneled through HTTP)—HTTP
streaming is supported through a handoff process from HTTP to RTSP. HTTP accepts
the connection and, based on the headers, hands off to RTSP. The headers identify an
RTSP URL.
Server-Side
❐ Interleaved RTSP
❐ HTTP streaming
Unsupported Protocols
The following Real Media protocols are not supported in this version of SGOS:
❐ PNA.
❐ Server-side RDT/UDP (both unicast and multicast).
QuickTime Protocols
The SG appliance supports the following protocols:
❐ RTP over unicast UDP (RTSP over TCP, RDT over unicast UDP)
❐ Interleaved RTSP (RTSP over TCP, RDT over TCP on the same connection)
❐ HTTP streaming (RTSP and RDT over TCP tunneled through HTTP)—HTTP
streaming is supported through a handoff process from HTTP to RTSP. HTTP accepts
the connection and, based on the headers, hands off to RTSP. The headers identify an
RTSP URL.
Server-Side
❐ Interleaved RTSP
❐ HTTP streaming
Unsupported Protocols
The following QuickTime protocols are not supported in this version of SGOS:
❐ Server-side RTP/UDP, both unicast and multicast, is not supported.
❐ Client-side multicast is not supported.
37
Volume 3: Web Communication Proxies
Delivery Methods
The SG appliance supports the following streaming delivery methods:
❐ Unicast—A one-to-one transmission, where each client connects individually to the
source, and a separate copy of data is delivered from the source to each client that
requests it. Unicast supports both TCP- and UDP-based protocols. The majority of
streaming media traffic on the Internet is unicast.
❐ Multicast—Allows efficient delivery of streaming content to a large number of users.
Multicast enables hundreds or thousands of clients to play a single stream, thus
minimizing bandwidth use.
The SG appliance provides caching, splitting, and multicast functionality.
38
Chapter 3: Managing Streaming Media
For Real Media and QuickTime (through RTSP), multicasting maintains a TCP control
(accounting) channel between the client and media server. The multicast data stream is
broadcast using UDP from the SG appliance to streaming clients, who join the multicast.
Limiting Bandwidth
The following sections describe bandwidth limitation and how to configure the SG to
limit global and protocol-specific media bandwidth.
Streaming media bandwidth management is achieved by configuring the SG appliance to
restrict the total number of bits per second the appliance receives from the origin media
servers and delivers to clients. The configuration options are flexible to allow you to
configure streaming bandwidth limits for the SG appliance, as well as for each streaming
protocol (Windows Media, Real Media, and QuickTime).
39
Volume 3: Web Communication Proxies
After it has been configured, the SG appliance limits streaming access to the specified
threshold. If a client tries to make a request after a limit has been reached, the client
receives an error message.
Note: If a maximum bandwidth limitation has been specified for the SG appliance, the
following condition can occur. If a Real Media client, followed by a Windows Media
client, requests streams through the same SG appliance and total bandwidth exceeds the
maximum allowance, the Real Media client enters the rebuffering state. The Windows
Media client continues to stream.
40
Chapter 3: Managing Streaming Media
Consider the following features when planning to limit streaming media bandwidth:
❐ SG appliance to server (all protocols)—The total kilobits per second allowed between
the appliance and any origin content server or upstream proxy for all streaming
protocols. Setting this option to 0 effectively prevents the SG appliance from initiating
any connections to the media server. The SG appliance supports partial caching in
that no bandwidth is consumed if portions of the media content are stored in the SG
appliance.
❐ Client to SG appliance (all protocols)—The total kilobits per second allowed between
streaming clients and the SG. Setting this option to 0 effectively prevents any
streaming clients from initiating connections through the SG appliance.
❐ SG appliance to server—The total kilobits per second allowed between the Appliance
and the media server. Setting this option to 0 effectively prevents the SG appliance
from accepting media content.
Limiting SG appliance bandwidth restricts the following streaming media-related
functions:
• Live and video-on-demand media, the sum of all bit rates
• Limits the ability to fetch new data for an object that is partially cached
• Reception of multicast streams
❐ Client to SG appliance—The total kilobits per second allowed between Windows
Media streaming media clients and the SG appliance. Setting this option to 0
effectively prevents streaming clients from making connections to the SG appliance.
Limiting server bandwidth restricts the following streaming media-related functions:
• MBR is supported; the SG appliance assumes the client is using the maximum bit
rate
• Limits the transmission of multicast streams
❐ Client connections—The total number of clients that can connect concurrently. When
this limit is reached, clients attempting to connect receive an error message and are
not allowed to connect until other clients disconnect. Setting this variable to 0
effectively prevents any streaming media clients from connecting.
41
Volume 3: Web Communication Proxies
This causes streaming players to drop to a lower bandwidth version of the stream. If a
lower bandwidth version of the stream is not available, players that are not receiving
enough bandwidth can behave in an unpredictable fashion. In other words, if the amount
of bandwidth is insufficient to service all of the streams, some or all of the media players
experience a reduction in stream quality.
For most circumstances, Blue Coat recommends that you use the streaming features to
control streaming bandwidth rather than the bandwidth management features.
Windows Media
The SG appliance caches Windows Media-encoded video and audio files. The standard
extensions for these file types are: .wmv, .wma, and .asf.
Real Media
The SG appliance caches Real Media-encoded files, such as RealVideo and RealAudio.
The standard extensions for these file types are: .ra, .rm, and .rmvb. Other content served
from a Real Media server through RTSP is also supported, but it is not cached. This
content is served in pass-through mode only.
QuickTime
The SG appliance does not cache QuickTime content (.mov files). All QuickTime content is
served in pass-through mode only.
42
Chapter 3: Managing Streaming Media
Note: If the URL is composed of host names instead of IP addresses, splitting does not
occur across WMP 7.0 clients.
Splitting of live unicast streams provides bandwidth savings, since subsequent requests
do not increase network traffic.
Bitrate Thinning
Thinning support is closely related to MBR, but different in that thinning allows for data
rate optimizations even for single data-rate media files. If the media client detects that
there is network congestion, it requests a subset of the single data rate stream. For
example, depending on how congested the network is, the client requests only the key
video frames or audio-only instead of the complete video stream.
Pre-Populating Content
The SG appliance supports pre-population of streaming files from HTTP servers and
origin content servers. Downloading streaming files from HTTP servers reduces the time
required to pre-populate the file.
Note: QuickTime content is not supported. Windows Media RTSP only supports pre-
population of streaming files from origin content servers. However, whenever origin
content server allows faster caching of streaming content, Windows Media RTSP pre-
populates the content much faster.
Pre-population can be accomplished through streaming from the media server. The
required download time was equivalent to the file length; for example, a two-hour movie
required two hours to download. Now, if the media file is hosted on a HTTP server, the
download time occurs at normal transfer speeds of an HTTP object, and is independent of
the play length of the media file.
Note: Content must be hosted on a HTTP server in addition to the media server.
Using the content distribute CLI command, content is downloaded from the HTTP server
and renamed with a given URL argument. A client requesting the content perceives that
the file originated from a media server. If the file on the origin media server experiences
changes (such as naming convention), SGOS bypasses the cached mirrored version and
fetches the updated version.
43
Volume 3: Web Communication Proxies
Windows Media Server version 9 contains a feature called Fast Streaming that allows
clients to provide streams with extremely low buffering time.
SGOS 4.x supports the following functionality for both cached and uncached content:
❐ Fast Start
❐ Fast Cache
Fast Recovery and Fast Reconnect are currently not supported.
License Requirements
The Windows Media RTSP functionality is included in the existing Windows Media
license.
Standard License
When a standard Windows Media license is installed, only pass-through streaming mode
and full policy control are available. Advanced features, for example, live splitting, VOD
caching, or multicast-station are not available.
Premium License
When a premium Windows Media license is installed, the full functionality for Windows
Media RTSP is available.
If a Windows Media license is not installed, or the license has expired, client connections
are denied.
Upgrade/Downgrade Issues
There are no software upgrade/downgrade requirements associated with Windows
Media RTSP.
If the SG appliance is downgraded to a release prior to SGOS 4.2.3, RTSP connections
from a Windows Media Player are denied. However, the client will fail over to MMS or
HTTP, which are handled by the MMS proxy.
44
Chapter 3: Managing Streaming Media
Live Support
Table 3-1. Windows Media live RTSP streaming feature support
UDP Retransmission No
On Demand Support
Table 3-2. Windows Media on demand RTSP streaming feature support
UDP Retransmission No
Stream Change No
45
Volume 3: Web Communication Proxies
Multicast Support
Table 3-3. Windows Media Multicast UDP streaming feature support
Feature Multicast
Server-Side Playlists No
Stream Change No
Note: Windows Media RTSP does not support policy-based streaming transport
selection.
46
Chapter 3: Managing Streaming Media
Bandwidth Management
Windows Media RTSP supports bandwidth management for both client-side and
gateway-side streaming traffic. Bandwidth limiting is supported for both client-side and
gateway-side streaming traffic. Bandwidth limits are also be supported for pass-through
streams.
47
Volume 3: Web Communication Proxies
❐ Transparent style HTTP proxy authentication fails to work with Windows Media
players when the credential cache lifetime is set to 0 (independent of whether server-
side authentication is involved).
❐ If proxy authentication is configured, a request for a stream through HTTP prompts
the user to enter access credentials twice: once for the proxy authentication and once
for the media server authentication.
❐ Additional scenarios involving HTTP streaming exist that do not work when the TTL
is set to zero (0), even though only proxy authentication (with no server
authentication) is involved. The SG appliance returning a 401-style proxy
authentication challenge to the Windows Media Player 6.0 does not work because the
Player cannot resolve inconsistencies between the authentication response code and
the server type returned from the SG appliance. This results in an infinite loop of
requests and challenges. Example scenarios include transparent authentication—
resulting from either transparent request from player or hard-coded service specified
in the SG appliance—and request of cache-local (ASX-rewritten or unicast alias)
URLs.
48
Chapter 3: Managing Streaming Media
Related Topics
You must also configure the network service (Configuration > Network > Services) to
assign port numbers and modes (transparent or proxy). For more information, refer to
Volume 3: Proxies and Proxy Services.
49
Volume 3: Web Communication Proxies
2. Scroll the list of services to display the default one of the IM service lines (this
example uses MMS). Notice the Action is Bypass. You can select Intercept from the
drop-down list, but for the purposes of this procedures, select the service line to
highlight it.
3. Click Edit. The Edit Service dialog appears with the default settings displays.
50
Chapter 3: Managing Streaming Media
4a
4b
4c
Note: You can also change the mode from Bypass to Intercept from the main
services page.
d. Click OK
5. Click Apply.
Result: The streaming service is configured and appears in Management Console.
51
Volume 3: Web Communication Proxies
Now that the streaming listeners are configured, you can configure the streaming proxies.
3
4
5
2. Specify the when the SG appliance checks cached streaming content for freshness.
• Never check freshness: The default, but Blue Coat recommends not using this
option.
• Check freshness every value hours: The SG appliance checks content freshness
every n.nn hours.
• Check freshness every access: Every time cached content is requested, it is
checked for freshness.
52
Chapter 3: Managing Streaming Media
3. Enable HTTP handoff: Enabled by default. Only disable if you do not want HTTP
streams to be cached or split. See “About HTTP Handoff” on page 39.
4. Forward client-generated logs to origin media server: Enabled by default. The SG
appliance logs information, such as client IP address, the date, and the time, to the
origin server for Windows Media and Real Media content.
Note: For Real Media, the log is only forwarded before a streaming session is halted;
QuickTime log forwarding is not supported.
5. Enable multicast (Real Media proxy only): The SG appliance receives a unicast stream
from the origin RealServer and serves it as a multicast broadcast. This allows the SG
to take a one-to-one stream and split it into a one-to-many stream, saving bandwidth
and reducing the server load. It also produces a higher quality broadcast.
Multicasting maintains a TCP control (accounting) channel between the client and
RealServer. The multicast data stream is broadcast using UDP from the SG appliance
to RealPlayers that join the multicast. The SG appliance support for Real Media uses
UDP port 554 (RTSP) for multicasting. This port number can be changed to any valid
UDP port number.
6. Click Apply.
Limiting Bandwidth
This section describes how to limit bandwidth from both the clients to the SG appliance
and the SG appliance to origin content servers (OCS).
53
Volume 3: Web Communication Proxies
2a
2b
54
Chapter 3: Managing Streaming Media
To specify the bandwidth limit for Windows Media, Real Media, or QuickTime:
1. Select Configuration > Services > Streaming Proxies > WMedia Bandwidth -or- RMedia
Bandwidth -or- QuickTime Bandwidth.
2a
2b
3
Note: This section applies to Windows Media only and can only accomplished
through the CLI.
Upon connection to the SG appliance, Windows Media clients do not consume more
bandwidth (in kilobits per second) than the defined value.
55
Volume 3: Web Communication Proxies
2a
2b
2c
Note: This section applies to Windows Media streaming only and can only be
configured through the CLI.
Configure the SG appliance to recognize the type of authentication the origin content
server is using: BASIC or NTLM/Kerberos.
56
Chapter 3: Managing Streaming Media
❐ avgbandwidth: Average bandwidth (in bits per second) at which the client was
connected to the server.
❐ channelURL: URL to the .nsc file.
❐ c-buffercount: Number of times the client buffered while playing the stream.
❐ c-bytes: An MMS-only value of the total number of bytes delivered to the client.
❐ c-rate: Mode of Windows Media Player when the last command event was sent.
❐ c-starttime: Timestamp (in seconds) of the stream when an entry is generated in the
log file.
❐ c-status: Codes that describe client status.
57
Volume 3: Web Communication Proxies
❐ c-totalbuffertime: Time (in seconds) the client used to buffer the stream.
❐ s-totalclients: Clients connected to the server (but not necessarily receiving streams).
❐ x-duration: Length of time a client played content prior to a client event (FF, REW,
Pause, Stop, or jump to marker).
❐ x-wm-c-dns: Hostname of the client determined from the Windows Media protocol.
❐ x-wm-c-ip: The client IP address determined from the Windows Media protocol.
Triggers
❐ streaming.client=
❐ streaming.content=
58
Chapter 3: Managing Streaming Media
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
59
Volume 3: Web Communication Proxies
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
60
Chapter 3: Managing Streaming Media
61
Volume 3: Web Communication Proxies
62
Chapter 3: Managing Streaming Media
Unicast to Multicast
Unicast to multicast streaming requires converting a unicast stream on the server-side
connection to a multicast station on the SG appliance. The unicast stream must contain
live content before the multicast station works properly. If the unicast stream is a video-
on-demand file, the multicast station is created but is not able to send packets to the
network. For video-on-demand files, use the broadcast-alias command, discussed
below.
Multicast to Multicast
Use the multicast-alias command to get the source stream for the multicast station.
63
Volume 3: Web Communication Proxies
Syntax
multicast-station name {alias | url} [address | port | ttl]
where
• name specifies the name of the multicast station, such as station1.
• {alias | url} defines the source of the multicast stream. The source can be a
URL or it can be a multicast alias, a unicast alias, or simulated live. (The source
commands must be set up before the functionality is enabled within the multicast
station.)
• [address | port | ttl] are optional commands that you can use to override
the default ranges of these values. (Defaults and permissible values are discussed
below.)
❐ Instructs the multicast station from Example 1, station1, to use the broadcast alias,
array1, as the source.
64
Chapter 3: Managing Streaming Media
❐ TTL value: the default is 5 hops; the permissible range is from 1 to 255.
Note: You can also enter the URL in the Windows Media Player to start the stream.
The newly created file is not editable; the settings come from streaming configuration file.
In that file, you have already defined the following pertinent information for the file:
❐ The address, which includes TTL, IP Address, IP Port, Unicast URL, and the NSC
URL. All created .nsc files contain a unicast URL for rollover in case the Windows
Media Player cannot find the streaming packets.
❐ The description, which references the MMS URL that you defined.
❐ The format, which contains important ASF header information. All streams delivered
by the multicast station definition have their ASF headers defined here.
65
Volume 3: Web Communication Proxies
Note: Playing at the end of the multicast station definition indicates that the station
is currently sending packets onto the network. The IP address and port ranges have
been randomly assigned from among the default ranges allowed.
66
Chapter 3: Managing Streaming Media
Note: This note applies to HTTP only. If a client opens Windows Media player and
requests an alias before the starting time specified in the broadcast-alias option, the HTTP
connection closes after a short time period. When the specified time arrives, the player
fails to reconnect to the stream and remains in waiting mode.
Three scenarios can occur when a client requests the simulated live content:
❐ Clients connect before the scheduled start time of the simulated live content: clients
are put into wait mode.
❐ Clients connect during the scheduled playback time of the simulated live content:
clients receive cached content for playback.
❐ Clients connect after the scheduled playback time of the simulated live: the client
receives an error message.
The SG Appliance computes the starting playtime of the broadcast stream based on the
time difference between the client request time and the simulated live starting time.
67
Volume 3: Web Communication Proxies
Example 1
This example creates a playlist for simulated live content. The order of playback is
dependent on the order you enter the URLs. Up to 128 URLs can be added.
SGOS#(config) streaming windows-media broadcast-alias alias url
Example 2
This example demonstrates the following:
❐ creates a simulated live file called bca.
❐ plays back mms://ocs.bca.com/bca1.asf and mms://ocs.bca.com/bca2.asf.
❐ configures the SG appliance to play back the content twice.
❐ sets a starting date and time of today at 4 p.m., 6 p.m., and 8 p.m.
SGOS#(config) streaming windows-media broadcast-alias bca mms://
ocs.bca.com/bca1.asf 2 today 4pm,6pm,8pm
SGOS#(config) streaming windows-media broadcast-alias bca mms://
ocs.bca.com/bca2.asf
68
Chapter 3: Managing Streaming Media
Note: If an .asx file syntax does not follow the standard <ASX> tag-based syntax, the
ASX rewrite module is not triggered.
For the SG appliance to operate as a proxy for Windows Media Player requires the
following:
❐ The client is explicitly proxied for HTTP content to the SG appliance that rewrites
the .asx metafile.
❐ The streaming media SG appliance is configurable.
Note: Windows Media Player automatically tries to roll over to different protocols
according to its Windows Media property settings before trying the rollover URLs in
the .asx metafile.
With the asx-rewrite command, you can implement redirection of the streaming media
to a SG appliance by specifying the rewrite protocol, the rewrite IP address, and the
rewrite port.
The protocol specified in the ASX rewrite rule is the protocol the client uses to reach the
SG. You can use forwarding and policy to change the default protocol specified in the
original .asx file that connects to the origin media server.
When creating ASX rewrite rules, you need to determine the number priority. It is likely
you will create multiple ASX rewrite rules that affect the .asx file; for example, rule 100
could redirect the IP address from 10.25.36.01 to 10.25.36.47, while rule 300 could
redirect the IP address from 10.25.36.01 to 10.25.36.58. In this case, you are saying
that the original IP address is redirected to the IP address in rule 100. If that IP address is
not available, the SG looks for another rule matching the incoming IP address.
69
Volume 3: Web Communication Proxies
70
Chapter 3: Managing Streaming Media
To ensure that an ASX rewrite rule has been modified immediately, clear the local
browser cache.
Example
This example:
❐ Sets the priority rule to 200
❐ Sets the protocol to be whatever protocol was originally specified in the URL and
directs the data
stream to the appropriate default port.
❐ Provides the rewrite IP address of 10.9.44.53, the SG appliance.
SGOS#(config) streaming windows-media asx-rewrite 200 * * 10.9.44.53
Note: ASX files must be fetched from HTTP servers. If you are not sure of the
network topology or the content being served on the network, use the asterisks to
assure the protocol set is that specified in the URL.
71
Volume 3: Web Communication Proxies
Note: The example below uses Windows Media Player 9.0. Installation and setup varies
with different versions of Windows Media Player.
3a
4a
4b
3b
3c
72
Chapter 3: Managing Streaming Media
Striding
When you use the Windows Media Player, consider the following interactivities in regard
to using fast forward and reverse (referred to as striding):
❐ If you request a cached file and repeatedly attempt play and fast forward, the file
freezes.
❐ If you attempt a fast reverse of a cached file that is just about to play, you receive an
error message, depending on whether you have a proxy:
• Without a proxy: A device attached to the system is not functioning.
• With a proxy: The request is invalid in the current state.
❐ If Windows Media Player is in pause mode for more than ten minutes and you press
fast reverse or fast forward, an error message displays: The network connection
has failed.
Other Notes
❐ Applies to Versions 9: if a url_host_rewrite rule is configured to rewrite a host
name that is a domain name instead of an IP address, a request through the MMS
protocol fails and the host is not rewritten. As the connect message sent by the player
at the initial connection does not contain the host name, a rewrite cannot occur. HTTP
requests are not affected by this limitation.
❐ If explicit proxy is configured and the access policy on the SG appliance is set to deny,
a requested stream using HTTP from Windows Media Player 9 serves the stream
directly from the origin server even after the request is denied. The player sends a
request to the OCS and plays the stream from there.
73
Volume 3: Web Communication Proxies
Notes:
For authentication-specific notes, see "Windows Media Server-Side Authentication" on
page 47 and "Windows Media Proxy Authentication" on page 47.
74
Chapter 3: Managing Streaming Media
Section E: RealPlayer
Section E: RealPlayer
This section describes how to configure the Windows Media Player to communicate
through the SG appliance.
Configuring RealPlayer
To use the SG appliance Real Media streaming services with an explicit proxy
configuration, the client machine must have RealPlayer installed and configured to use
RTSP streams. If you use transparent proxy, no changes need to be made to the
RealPlayer.
Note: This procedure features RealPlayer, version 10.5. Installation and setup menus
vary with different versions of RealPlayer. Refer to the RealPlayer documentation to
configure earlier versions of RealPlayer.
To configure RealPlayer:
1. Start RealPlayer.
2. Select Tools > Preferences.
75
Volume 3: Web Communication Proxies
Section E: RealPlayer
3a 3b
4a
4b
76
Chapter 3: Managing Streaming Media
Note: For HTTP Proxy, if you have an HTTP proxy already configured in your
browser, select Use system Internet Connection proxy settings.
c. Optional: For HTTP Proxy, if you have an HTTP proxy already configured in
your browser, select Use system Internet Connection proxy settings.
d. Optional: In the Do not use proxy for: section, you can enter specific hosts and
bypass the SG appliance.
Note: This can also be accomplished with policy, which is the method Blue
Coat recommends.
5a
5b
77
Volume 3: Web Communication Proxies
8a 8b
Notes:
For authentication-specific issues, see “ Real Media Proxy Authentication” on page 48.
78
Chapter 3: Managing Streaming Media
To configure QuickTime
1. Select Edit > Preferences > QuickTime Preferences.
2a
2b
2c 2d
Notes:
For authentication-specific issues, see “ QuickTime Proxy Authentication” on page 48.
79
Volume 3: Web Communication Proxies
80
Appendix A: Glossary
access log A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.
account A named entity that has purchased the appliance or the Entitlements from Blue Coat.
activation code A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.
active content stripping Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.
active content types Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user
administration access policy A policy layer that determines who can access the SG appliance to perform
administrative tasks.
administration A policy layer that determines how administrators accessing the SG appliance must
authentication policy authenticate.
Application Delivery A WAN that has been optimized for acceleration and compression by Blue Coat. This
Network (ADN) network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.
ADN backup manager Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.
ADN manager Responsible for publishing the routing table to SG Clients (and to other SG
appliances).
ADN optimize attribute Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
asx rewrite Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxy-
like support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.
audit A log that provides a record of who accessed what and how.
81
Volume 3: Web Communication Proxies
authenticate-401 attribute All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios
authenticated content Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).
authentication Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate Authority.
See also basic authentication, proxy authentication, and SSL authentication.
authentication realm Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.
bandwidth class hierarchy Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.
bandwidth management Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.
basic authentication The standard authentication for communicating with the target as identified in the
URL.
BCAAA Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.
byte-range support The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).
cache An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.
cache control Allows you to configure which content the SG appliance stores.
82
Appendix A: Glossary
cache efficiency A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.
cache hit Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.
cache miss Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .
cache object Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.
Certificate Authority (CA) A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.
child class (bandwidth gain) The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.
client consent certificates A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.
client-side transparency A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.
concentrator An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.
content filtering A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.
default boot system The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.
denial of service (DoS) A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.
83
Volume 3: Web Communication Proxies
destination objects Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.
detect protocol attribute Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
diagnostic reporting Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.
directives Commands used in installable lists to configure forwarding and SOCKS gateway.
DNS access A policy layer that determines how the SG appliance processes DNS requests.
domain name system (DNS) An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.
dynamic bypass Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.
dynamic real-time rating Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
(DRTR) dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.
early intercept attribute Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.
ELFF-compatible format A log type defined by the W3C that is general enough to be used with any protocol.
emulated certificates Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.
encrypted log A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.
event logging Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.
84
Appendix A: Glossary
explicit proxy A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.
extended log file format A variant of the common log file format, which has two additional fields at the end of
(ELFF) the line—the referer and the user agent fields.
fail open/closed Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.
forward proxy A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.
gateway A device that serves as entrance and exit into a communications network.
hardware serial number A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.
health check tests The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
• ICMP
• TCP
• SSL
• HTTP
• HTTPS
• Group
• Composite and reference to a composite result
• ICAP
• Websense
• DRTR rating service
85
Volume 3: Web Communication Proxies
health check type The kind of device or service the specific health check tests. The following types are
supported:
• Forwarding host and forwarding group
• SOCKS gateway and SOCKS gateway group
• CAP service and ICAP service group
• Websense off-box service and Websense off-box service group
• DRTR rating service
• User-defined host and a user-defined composite
heartbeat Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.
host affinity The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.
host affinity timeout The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.
inbound traffic (bandwidth Network packets flowing into the SG appliance. Inbound traffic mainly consists of
gain) the following:
• Server inbound: Packets originating at the origin content server (OCS) and sent to
the SG appliance to load a Web object.
• Client inbound: Packets originating at the client and sent to the SG appliance for
Web requests.
installable lists Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
• Creating the list using the SG text editor
• Placing the list at an accessible URL
• Downloading the directives file from the local system
integrated host timeout An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.
intervals Time period from the completion of one health check to the start of the next health
check.
IP reflection Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.
86
Appendix A: Glossary
issuer keyring The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.
licensable component (LC) (Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.
license Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.
listener The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.
live content Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.
load balancing A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.
local bypass list A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.
local policy file Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).
log facility A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.
log format The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.
log tail The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.
87
Volume 3: Web Communication Proxies
Management Console A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.
management information Defines the statistics that management systems can collect. A managed device
base (MIB) (gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.
maximum object size The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.
MIME/FILE type filtering Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.
multi-bit rate The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).
multicast Used in streaming; the ability for hundreds or thousands of users to play a single
stream.
multicast aliases Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel
multicast station Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).
multimedia content services Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.
name inputing Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server
native FTP Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).
NCSA common log format Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.
network address translation The process of translating private network (such as intranet) IP addresses to Internet
(NAT) IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.
88
Appendix A: Glossary
non-cacheable objects A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
• Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
• Password provided, requests that include a client password.
• Data in request that include additional client data.
• Not a GET request.
.nsc file Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.
NTP To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.
object (used in caching) An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.
object (used in Visual Policy An object (sometimes referred to as a condition) is any collection or combination of
Manager) entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.
object pipelining This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.
origin content server (OCS) Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.
outbound traffic (bandwidth Network packets flowing out of the SG appliance. Outbound traffic mainly consists
gain) of the following:
• Client outbound: Packets sent to the client in response to a Web request.
• Server outbound: Packets sent to an OCS or upstream proxy to request a service.
PAC (Proxy Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
AutoConfiguration) scripts port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.
packet capture (PCAP) Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.
89
Volume 3: Web Communication Proxies
parent class (bandwidth A class with at least one child. The parent class must share its bandwidth with its
gain) child classes in proportion to the minimum/maximum bandwidth values or priority
levels.
passive mode data Data connections initiated by an FTP client to an FTP server.
connections (PASV)
policies Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.
policy-based bypass list Used in policy. Allows a bypass based on the properties of the client, unlike static and
dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.
policy layer A collection of rules created using Blue Coat CPL or with the VPM.
pragma: no cache (PNC) A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).
proxy Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.
proxy service The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.
proxy service (default) The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.
public key certificate An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).
public virtual IP (VIP) Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.
90
Appendix A: Glossary
real-time streaming protocol A standard method of transferring audio and video and other time-based media over
(RTSP) Internet-technology based networks. The protocol is used to stream clips to any RTP-
based client.
reflect client IP attribute Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.
registration An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.
remote authentication dial- Authenticates user identity via passwords for network access.
in user service (RADIUS)
reverse proxy A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.
routing information protocol Designed to select the fastest route to a destination. RIP support is built into Blue
(RIP) Coat appliances.
router hops The number of jumps a packet takes when traversing the Internet.
secure shell (SSH) Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.
serial console A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.
server certificate categories The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.
server portals Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping a
set of external URLs onto a set of internal URLs.
server-side transparency The ability for the server to see client IP addresses, which enables accurate client-
access records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.
service attributes Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .
91
Volume 3: Web Communication Proxies
SG appliance A Blue Coat security and cache box that can help manage security and content on a
network.
sibling class (bandwidth A bandwidth class with the same parent class as another class.
gain)
simple network The standard operations and maintenance protocol for the Internet. It uses MIBs,
management protocol created or customized by Blue Coat, to handle (needs completion).
(SNMP)
simulated live Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.
SmartReporter log type A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.
SOCKS A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.
SOCKS proxy A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.
splash page Custom message page that displays the first time you start the client browser.
split proxy Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
• Mapi Proxy
• SSL Proxy
SQUID-compatible format A log type that was designed for cache statistics and is compatible with Blue Coat
products.
squid-native log format The Squid-compatible format contains one line for each request.
SSL authentication Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).
SSL proxy A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.
static route A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.
92
Appendix A: Glossary
statistics Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated, cache
efficiency, cached contents, and custom URLs generated by the appliance for various
kinds of logs. You can also check the event viewer for every event that occurred since
the appliance booted.
stream A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.
SurfControl log type A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.
system cache The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.
time-to-live (TTL) value Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.
traffic flow Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
(bandwidth gain) that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of
these connections, traffic flows in two directions—in one direction, packets flow out
of the SG appliance (outbound traffic), and in the other direction, packets flow into
the SG (inbound traffic). Connections can come from the client or the server. Thus,
traffic can be classified into one of four types:
• Server inbound
• Server outbound
• Client inbound
• Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.
transmission control TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
protocol (TCP) in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.
transparent proxy A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.
93
Volume 3: Web Communication Proxies
trial period Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.
unicast alias Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicast-
alias command to request the content from the origin streaming server.
universal time coordinates An SG appliance must know the current UTC time. By default, the appliance
(UTC) attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.
URL rewrite rules Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.
WCCP Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.
Web FTP Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
OCS (if the content is not already cached), and then translates the FTP response with
the file contents into an HTTP response for the client.
Websense log type A Blue Coat proprietary log type that is compatible with the Websense reporter tool.
94
Index
A P
ASX rewrite port services
command syntax 69 instant messaging protocols 9
rules 69 proxies
setting up for Windows Media 68 definition 7
B R
Blue Coat SG RealMedia
instant messaging proxy authentication 47
configuring clients 20 RTSP over Windows Media, about 43
proxy authentication 9
securing 9 S
Yahoo Messenger client configuration 23 streaming
instant messaging, IM clients tab statistics 31 WM over RTSP, about 43
instant messaging, IM data tab statistics 30 streaming media
delivery type 37
D live content defined 38
document multicast defined 37
conventions 7 prepopulating content, description 42
unicast defined 37
H
HTTP U
handoff, enabling 39 unicast
defined 37
I multicast, converting from by Windows Media 38
instant messaging
configuring clients 20 W
proxy authentication 9 Windows Media
securing 9 .ASX-rewrite rules 69
statistics, IM clients tab 31 .nsc file 64
statistics, IM data tab 30 ASX rewrite and NTLM incompatibility 70
Yahoo Messenger client configuration 23 authentication limitations 46
HTTP handoff enabling 39
M multicast station monitoring 65
multicast multicast to unicast 38
defined 37 over RTSP 43
unicast, converting by Windows Media 38 prepopulating content description 42
setting up ASX rewrite 68
95
Volume 3: Web Communication Proxies
96
Blue Coat® Systems
SG™ Appliance
Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
ii
Contents
Contact Information
iii
Volume 4: Securing the Blue Coat SG Appliance
iv
Contents
v
Volume 4: Securing the Blue Coat SG Appliance
vi
Contents
vii
Volume 4: Securing the Blue Coat SG Appliance
Appendix A: Glossary
viii
Contents
Index
ix
Volume 4: Securing the Blue Coat SG Appliance
x
Chapter 1: About Security
Enterprise-wide security begins with security on the SG appliance, and continues with
controlling user access to the Intranet and Internet.
SSH and HTTPS are the recommended (and default) methods for managing access to
the SG appliance. SSL is the recommended protocol for communication between the
appliance and a realm's off-box authentication server.
11
Volume 4: Securing the Blue Coat SG Appliance
Note: If the browser is configured for on-line checking of certificate revocation, the
status check must be configured to bypass authentication.
12
Chapter 1: About Security
Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Conventions Definition
Courier font Command line text that appears on your administrator workstation.
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.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
13
Volume 4: Securing the Blue Coat SG Appliance
14
Chapter 2: Controlling Access to the SG Appliance
You can control access to the SG appliance several ways: by limiting physical access to
the system, by using passwords, restricting the use of console account, through per-
user RSA public key authentication, and through Blue Coat Content Policy Language
(CPL). How secure the system needs to be depends upon the environment.
This section contains:
❐ “Limiting Access to the SG Appliance”
❐ “About Password Security” on page 16
❐ “Limiting User Access to the SG Appliance—Overview” on page 17
❐ “Moderate Security: Restricting Management Console Access Through the Console
Access Control List (ACL)” on page 19
❐ “Maximum Security: Administrative Authentication and Authorization Policy” on
page 20
15
Volume 4: Securing the Blue Coat SG Appliance
16
Chapter 2: Controlling Access to the SG Appliance
Note: If Telnet Console access is configured, Telnet can be used to manage the SG
appliance with behavior similar to SSH with password authentication.
SSL configuration is not allowed through Telnet, but is permissible through SSH.
Behavior in the following sections that applies to SSH with password authentication also
applies to Telnet. Use of Telnet is not recommended because it is not a secure protocol.
17
Volume 4: Securing the Blue Coat SG Appliance
This is a less flexible option than CPL because you cannot control level of access with
policy, but it is a better choice than sharing the console credentials.
❐ Blue Coat Content Policy Language (CPL)—maximum security
CPL allows you to control administrative access to the SG appliance through policy. If
the credentials supplied are not the console account username and password, policy is
evaluated when the SG appliance is accessed through SSH with password
authentication or the Management Console. Policy is never evaluated on direct serial
console connections or SSH connections using RSA authentication.
• Using the CLI or the Management Console GUI, create an authentication realm to
be used for authorizing administrative access. For administrative access, the realm
must support BASIC credentials—for example, LDAP, RADIUS, Local, or IWA
with BASIC credentials enabled.
• Using the Visual Policy Manager, or by adding CPL rules to the Local or Central
policy file, specify policy rules that: (1) require administrators to log in using
credentials from the previously-created administrative realm, and (2) specify the
conditions under which administrators are either denied all access, given read-
only access, or given read-write access. Authorization can be based on IP address,
group membership, time of day, and many other conditions. For more
information, refer to Volume 6: VPM and Advanced Policy.
• To prevent anyone from using the console credentials to manage the SG
appliance, set the console ACL to deny all access (unless you plan to use SSH with
RSA authentication). For more information, see “Moderate Security: Restricting
Management Console Access Through the Console Access Control List (ACL)” on
page 19. You can also restrict access to a single IP address that can be used as the
emergency recovery workstation.
The following chart details the various ways administrators can access the SG console and
the authentication and authorization methods that apply to each.
Security Measures Available Serial SSH with SSH with RSA Management
Console Password Authentication Console
Authentication
18
Chapter 2: Controlling Access to the SG Appliance
Note 1: When using SSH (with a password) and credentials other than the console
account, the enable password is actually the same as the login password. The privileged
mode password set during configuration is used only in the serial console, SSH with RSA
authentication, or when logging in with the console account.
Note 2: In this case, user credentials are evaluated against the policy before executing each
CLI command. If you log in using the console account, user credentials are not evaluated
against the policy.
To create an ACL:
1. Select Configuration > Authentication > Console Access > Console Access.
2. (Optional) To add a new address to the ACL, click New.
Important: Before you enforce the ACL, verify the IP address for the workstation you
are using is included in the list. If you forget, or you find that you mistyped the IP
address, you must correct the problem using the serial console.
19
Volume 4: Securing the Blue Coat SG Appliance
20
Chapter 2: Controlling Access to the SG Appliance
Important: For specific information on creating policies within the policy files, refer
to Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
Following are the CPL elements that can be used to define administrator policies for the
SG appliance.
proxy.port=number Tests for a match between number and the port number for
which the request is destined.
proxy.card=number Tests for a match between number and the ordinal number
associated with the network interface card for which the request
is destined.
date[.utc]=[date | date…date] Tests for a match between date and the date timestamp
associated with the source of the transaction. date specifies a
single date of the form YYYY-MM-DD or an inclusive range, as in
YYYY-MM-DD…YYYY-MM-DD. By default, date is calculated based
on local time. To calculate year based on the Coordinated
Universal Time, include the .utc qualifier
21
Volume 4: Securing the Blue Coat SG Appliance
year[.utc]=[year | year…year] Tests for a match between year and the year timestamp
associated with the source of the transaction. year specifies a
single Gregorian calendar year of the form YYYY or an inclusive
range of years, as in YYYY…YYYY. By default, year is calculated
based on local time. To calculate year based on the Coordinated
Universal Time, include the .utc qualifier.
month[.utc]=[month | month…month] Tests for a match between month and the month timestamp
associated with the source of the transaction. month specifies a
single Gregorian calendar month of the form MM or an inclusive
range of months, as in MM…MM. By default, month is calculated
based on local time. To calculate month based on the
Coordinated Universal Time, include the .utc qualifier.
weekday[.utc]=[number | Tests for a match between weekday and the weekday timestamp
number…number] associated with the source of the transaction. weekday specifies
a single day of the week (where Monday=1, Tuesday=2, and
Sunday=7) or an inclusive range of weekdays, as in
number…number. By default, weekday is calculated based on
local time. To calculate weekday based on the Coordinated
Universal Time, include the .utc qualifier.
day[.utc]=[day | day…day] Tests for a match between day and the day timestamp
associated with the source of the transaction. day specifies a
single Gregorian calendar day of the month of the form DD or
an inclusive range of days, as in DD…DD. By default, day is
calculated based on local time. To calculate day based on the
Coordinated Universal Time, include the .utc qualifier.
hour[.utc]=[hour | hour…hour] Tests for a match between hour and the hour timestamp
associated with the source of the transaction. hour specifies a
single Gregorian hour of the form HH (00, 01, and so forth,
through 23) or an inclusive range of hours, as in HH…HH. By
default, hour is calculated based on local time. To calculate hour
based on the Coordinated Universal Time, include the .utc
qualifier.
minute[.utc]=[minute | Tests for a match between minute and the minute timestamp
minute…minute] associated with the source of the transaction. minute specifies a
single Gregorian minute of the form MM (00, 01, and so forth,
through 59) or an inclusive range of minutes, as in MM…MM. By
default, minute is calculated based on local time. To calculate
minute based on the Coordinated Universal Time, include
the .utc qualifier.
time[.utc]=[time | time…time] Tests for a match between time and the time timestamp
associated with the source of the transaction. time specifies
military time of the form TTTT (0000 through 2359) or an
inclusive range of times, as in TTTT…TTTT. By default, time is
calculated based on local time. To calculate time based on the
Coordinated Universal Time, include the .utc qualifier.
22
Chapter 2: Controlling Access to the SG Appliance
authenticated={yes | no} Tests if authentication was requested and the credentials could
be verified.
admin_access=read | write read tests whether the source of the transaction has read-only
permission for the SG console. write tests whether the source
has read-write permission.
When an Administrator logs into the CLI, the SG appliance
executes an <Admin> transaction that includes the condition
admin_access=read. If the transaction is ultimately allowed
(all conditions have been met), the user will have read-only
access to configuration information through the CLI. Further,
when that user executes the CLI enable command, or logs into
the Management Console, the SG appliance executes an
<Admin> transaction with admin_access=write. If the
transaction is allowed, the user will have read-write access
within the CLI or the Management Console.
The table below lists the properties permitted in the <Admin> layer:
<Admin> Properties
23
Volume 4: Securing the Blue Coat SG Appliance
The table below lists the actions permitted in the <Admin> layer:
Table 2-4. Actions permitted in the <Admin> Layer
<Admin> Actions
<admin>
group="cn=Administrators,cn=Groups,dc=bluecoat,dc=com" allow
This authenticates users against the specified LDAP realm. If the users are successfully
authenticated and belong to group Administrators, they are allowed to administer the
SG appliance.
24
Chapter 3: Controlling Access to the Internet and Intranet
After you have physically secured the SG appliance and limited access to it through
passwords, you can limit users’ access to the Internet and intranet.
This chapter includes the following sections:
❐ Section A: "Managing Users" on page 26
❐ Section B: "Using Authentication and Proxies" on page 32
❐ Section C: "Using SSL with Authentication and Authorization Services" on page 41
❐ Section D: "Creating a Proxy Layer to Manage Proxy Operations" on page 42
25
Chapter 3: Controlling Access to the Internet and Intranet
26
Chapter 3: Controlling Access to the Internet and Intranet
You can use a combination of these filters to display only the users you are interested in.
To browse users:
1. Click Statistics > Authentication.
2. Select a single realm or All realms from the Realm drop-down list.
3. (Optional) Enter a regular expression in the User pattern field to display the
usernames that match the pattern.
4. (Optional) Enter an IP address or subnet in the IP prefix field to display the IP
addresses that match the prefix.
5. Click Display by user to display the statistic results by user, or Display by IP to display
the results by IP address.
Note: The Challenge user after logout option only works when cookie-surrogates are
used. If this setting is enabled, the user is explicitly challenged for credentials after
logging out.
Inactivity Timeout
Each realm has a new inactivity-timeout setting, used in conjunction with the last activity-
time value for a particular login. Each time that a login is completed, this activity time is
updated. If the time since the last activity time for a specific login exceeds the inactivity-
timeout value, the user is logged out.
27
Chapter 3: Controlling Access to the Internet and Intranet
Administrator Action
The administrator can explicitly log out a set of users using the Logout link at the bottom
of the user login information pages. See “Viewing Logged-In Users” on page 26 for
information about displaying user login information. For information about using the CLI
to logout users, see “Related CLI Syntax to Manage Users” on page 30.
Policy
Policy has three properties and three conditions to manage user logouts. These properties
and conditions can be used to dynamically log out users. For example, you can create a
logout link for users.
For information about using policy, refer to Volume 6: VPM and Advanced Policy and
Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
New Properties
Policy has three properties for logging out users.
❐ user.login.log_out(yes)
This property logs out the user referenced by the current transaction.
❐ user.login.log_out_other(yes)
If a user is logged in at more than one IP address, this property logs the user out from
all IP addresses except the current IP address.
❐ client.address.login.log_out_other(yes)
If more than one user is logged in at the IP address of the current transaction, this
property logs out all users from the current IP address except the current user.
New Conditions
Several conditions support different logout policies.
❐ user.login.count
This condition matches the number of times that a specific user is logged in with the
current realm. You can use this condition to ensure that a user can be logged in only at
one workstation. If the condition is combined with the user.login.log_out_other
property, old login sessions on other workstations are automatically logged out.
❐ client.address.login.count
This condition matches the number of different users who are logged into the current
IP address, and you can use it to limit the user number.
❐ user.login.time
This condition matches the number of seconds since the current login started, and you
can use it to limit the length of a login session.
28
Chapter 3: Controlling Access to the Internet and Intranet
❐ Surrogate refresh time: This option specifies how long surrogate credentials are
trusted in a particular realm.
❐ Authorization refresh time: This option specifies how long authorization data, such as
groups and attributes, are trusted.
While the realms have the baseline settings for the different refresh times, policy and
administrator actions can override the realm settings. Using the same interface and filters
as used for viewing logins, the administrator can select logins and refresh the
authorization data, the credentials, or the surrogates using the links available on the user
login information page. Refreshing user data might be necessary if users are added to new
groups or there is concern about the actual identity of the user on a long-lived IP
surrogate.
Note: The local realm uses Basic credentials but does not need to cache them since
they are stored already on the appliance.
One-Time Passwords
One-time passwords are trusted for the credential refresh time. Only when the credential
refresh time expires is the user challenged again.
29
Chapter 3: Controlling Access to the Internet and Intranet
Policy
Policy has three properties for setting the refresh times for individual transactions.
❐ authenticate.authorization_refresh_time(x)
where x is the number of seconds to use for the authorization refresh time during this
transaction. The refresh time cannot exceed the time configured in the realm; policy
can be used only to reduce the authorization refresh time. You can use this property to
dynamically force the user's authorization data to be refreshed.
❐ authenticate.credential_refresh_time(x)
where x is the number of seconds to use for the credential refresh time during this
transaction. The refresh time cannot exceed the time configured in the realm; policy
can be used only to reduce the credential refresh time. You can use this property to
dynamically force the user's credentials to be refreshed.
❐ authenticate.surrogate_refresh_time(x)
where x is the number of seconds to use for the surrogate refresh time during this
transaction. The refresh time cannot exceed the time configured in the realm; policy
can be used only to reduce the surrogate refresh time. You can use this property to
dynamically force the user's surrogate to be refreshed.
For information about using policy, refer to Volume 6: VPM and Advanced Policy and
Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
30
Chapter 3: Controlling Access to the Internet and Intranet
31
Chapter 3: Controlling Access to the Internet and Intranet
Note: Challenge type is the kind of challenge (for example, proxy or origin-ip-redirect)
issued.
Surrogate credentials are credentials accepted in place of the user’s real credentials.
❐ Auto: The default; the mode is automatically selected, based on the request. Auto can
choose any of proxy, origin, origin-ip, or origin-cookie-redirect, depending on the kind
of connection (explicit or transparent) and the transparent authentication cookie
configuration.
❐ Proxy: The SG appliance uses an explicit proxy challenge. No surrogate credentials are
used. This is the typical mode for an authenticating explicit proxy. In some situations
proxy challenges do not work; origin challenges are then issued.
If you have many requests consulting the back-end authentication authority (such as
LDAP, RADIUS, or the BCAAA service), you can configure the SG appliance (and
possibly the client) to use persistent connections. This dramatically reduces load on
the back-end authentication authority and improves the all-around performance of
the network.
32
Chapter 3: Controlling Access to the Internet and Intranet
❐ Proxy-IP: The SG appliance uses an explicit proxy challenge and the client's IP address
as a surrogate credential. Proxy-IP specifies an insecure forward proxy, possibly
suitable for LANs of single-user workstations. In some situations proxy challenges do
not work; origin challenges are then issued.
❐ Origin: The SG appliance acts like an OCS and issues OCS challenges. The
authenticated connection serves as the surrogate credential.
❐ Origin-IP: The SG appliance acts like an OCS and issues OCS challenges. The client IP
address is used as a surrogate credential. Origin-IP is used to support IWA
authentication to the upstream device when the client cannot handle cookie
credentials. This mode is primarily used for automatic downgrading, but it can be
selected for specific situations.
❐ Origin-cookie: The SG appliance acts like an origin server and issues origin server
challenges. A cookie is used as the surrogate credential. Origin-cookie is used in
forward proxies to support pass-through authentication more securely than origin-ip
if the client understands cookies. Only the HTTP and HTTPS protocols support
cookies; other protocols are automatically downgraded to origin-ip.
This mode could also be used in reverse proxy situations if impersonation is not
possible and the origin server requires authentication.
❐ Origin-cookie-redirect: The client is redirected to a virtual URL to be authenticated,
and cookies are used as the surrogate credential. The SG appliance does not support
origin-redirects with the CONNECT method. For forward proxies, only origin-*-
redirect modes are supported for Kerberos/IWA authentication. (Any other mode
uses NTLM authentication.)
33
Chapter 3: Controlling Access to the Internet and Intranet
❐ Form-Cookie: A form is presented to collect the user's credentials. The cookies are set
on the OCS domain only, and the user is presented with the form for each new
domain. This mode is most useful in reverse proxy scenarios where there are a limited
number of domains.
❐ Form-Cookie-Redirect: A form is presented to collect the user's credentials. The user is
redirected to the authentication virtual URL before the form is presented. The
authentication cookie is set on both the virtual URL and the OCS domain. The user is
only challenged when the credential cache entry expires.
❐ Form-IP-redirect: This is similar to form-ip except that the user is redirected to the
authentication virtual URL before the form is presented.
Important: Modes that use an IP surrogate credential are insecure: After a user has
authenticated from an IP address, all further requests from that IP address are treated
as from that user. If the client is behind a NAT, or on a multi-user system, this can
present a serious security problem.
34
Chapter 3: Controlling Access to the Internet and Intranet
Note: Sharing the virtual URL with other content on a real host requires additional
configuration if the credential exchange is over SSL.
You can configure the virtual site to something that is meaningful for your company. The
default, which requires no configuration, is www.cfauth.com. See “Configuring
Transparent Proxy Authentication” on page 35 to set up a virtual URL for transparent
proxy.
35
Chapter 3: Controlling Access to the Internet and Intranet
Note: A value of 0 (zero) for the IP address TTL re-prompts the user for credentials
once the specified cache duration for the particular realm has expired.
For authentication modes that make use of IP surrogate credentials, once the IP
address TTL expires the proxy re-challenges all client requests that do not contain
credentials for which an IP surrogate credential cache entry previously existed.
If at this point the client supplied a different set of credentials than previously used to
authenticate—for which an entry in the user credential cache still exists—the proxy
fails authentication. This is to prevent any another client to potentially gain network
access by impersonating another user by supplying his or her credentials. However,
once the user credential cache entry's TTL has expired, you can supply a different set
of credentials than previously used for authentication.
3. Select the Virtual URL. The default is www.cfauth.com. Blue Coat recommends you
change the virtual hostname to something meaningful to you, preferably the IP
address of the SG appliance, unless you are doing secure credentials over SSL. Using
the IP address of the SG appliance enables you to be sure that the correct SG appliance
is addressed in a cluster configuration.
4. Click Apply to commit the changes to the SG appliance.
36
Chapter 3: Controlling Access to the Internet and Intranet
Permitted Errors
Authentication and authorization can be permitted to fail if policy has been written to
allow specific failures. The behavior is as follows:
❐ Authentication Failures: After an authentication failure occurs, the authentication
error is checked against the list of errors that policy specifies as permitted.
• If the error is not on the list, the transaction is terminated.
• If the error is on the list, the transaction is allowed to proceed although the user is
unauthenticated. Because the transaction is not considered authenticated, the
authenticated=yes policy condition evaluates to false and the user has no
username, group information, or surrogate credentials. Policy that uses the user,
group, domain, or attribute conditions does not match.
❐ Authorization Failures: After an authorization failure occurs, the authorization error
is checked against the list of errors that policy specifies as permitted.
• If the error is not on the list, the transaction is terminated.
• If the error is on the list, the transaction is allowed to proceed and the user is
marked as not having authorization data.
• If a user is successfully authenticated but does not have authorization data, the
authenticated=yes condition evaluates to true and the user has valid
authentication credentials.
• The user.authorization_error=any is evaluate to true if user authorization
failed, the user object contains username and domain information, but not group
or attribute information. As a result, policy using user or domain actions still
match, but policy using group or attribute conditions do not.
To view all authentication and authorization errors, use the SGOS# show security
authentication-errors CLI command.
37
Chapter 3: Controlling Access to the Internet and Intranet
You can use the advanced authentication URL (Statistics > Advanced > Show
Authentication Error Statistics as a troubleshooting guide. The policy substitutions $(x-
sc-authentication-error) and $(x-sc-authorization-error) can also be used to
log the errors on a per-transaction basis.
Policy conditions and properties that are available include:
❐ authenticate.tolerate_error( )
❐ authorize.tolerate_error( )
❐ user.authentication_error=
❐ user.authorization_error=
❐ has_authorization_data=
Note: You are not limited to these conditions and properties in creating policy. For a
discussion and a complete list of policy conditions and properties you can use, refer to
Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
Note: You can use guest authentication with or without default groups. If you use
default groups, you can assign guest users to groups for tracking and statistics
purposes. For more information about default groups, see “Using Default Groups” on
page 39.
In the case of guest authentication, a user is not actually authenticated against the realm,
but is:
❐ Assigned the specified guest username
❐ Marked as authenticated in the specified realm
❐ Marked as a guest user
❐ Tracked in access logs
Since the user is not actually authenticated, the username does not have to be valid in that
realm.
38
Chapter 3: Controlling Access to the Internet and Intranet
Write the corresponding policy. Policy available for guest authentication includes:
❐ authenticate.guest
❐ user.is_guest
❐ authenticated
Note: You are not limited to these conditions and properties in creating policy. For a
complete list of policy conditions and properties you can use, refer to Volume 10: Blue
Coat SG Appliance Content Policy Language Guide.
Note: You can use default groups in conjunction with guest users (see “Using Guest
Authentication” on page 38) or it can be used with regular user authentication.
39
Chapter 3: Controlling Access to the Internet and Intranet
Note: You are not limited to these conditions and properties in creating policy. For a
complete list of policy conditions and properties you can use, refer to Volume 10: Blue
Coat SG Appliance Content Policy Language Guide.
40
Chapter 3: Controlling Access to the Internet and Intranet
Note: You can use SSL between the client and the SG appliance for origin-style
challenges on transparent and explicit connections (SSL for explicit proxy authentication
is not supported).
In addition, if you use a forward proxy, the challenge type must use redirection; it cannot
be an origin or origin-ip challenge type.
When redirected to the virtual URL, the user is prompted to accept the certificate offered
by the SG appliance (unless the certificate is signed by a trusted certificate authority). If
accepted, the authentication conversation between the SG appliance and the user is
encrypted using the certificate.
Note: If the hostname does not resolve to the IP address of the SG appliance, then the
network configuration must redirect traffic for that port to the appliance. Also, if you use
the IP address as the virtual hostname, you might have trouble getting a certificate signed
by a CA-Certificate authority (which might not be important).
For information about creating a keyring and a certificate, refer to Volume 2: Proxies and
Proxy Services.
You can use SSL between the SG appliance and IWA and LDAP authentication servers.
For more information, see “SSL Between the SG Appliance and the Authentication
Server” on page 12.
41
Chapter 3: Controlling Access to the Internet and Intranet
Using CPL
Below is a table of all commands available for use in proxy layers of a policy. If a
condition, property, or action does not specify otherwise, it can be used only in <Proxy>
layers. For information about creating effective CPL, refer to Volume 10: Blue Coat SG
Appliance Content Policy Language Guide.
admin.access= Tests the administrative access requested by the current transaction. Can also
be used in <Admin> layers.
authenticated= Tests if authentication was requested and the credentials could be verified;
otherwise, false. Can also be used in <Admin> layers.
bitrate= Tests if a streaming transaction requests bandwidth within the specified range
or an exact match. Can also be used in <Cache> layers.
category= Tests if the content categories of the requested URL match the specified
category, or if the URL has not been categorized. Can also be used in <Cache>
layers.
client_address= Tests the IP address of the client. Can also be used in <Admin> layers.
client.connection. Test the cipher suite negotiated with a securely connected client. Can also be
negotiated_cipher= used in <Exception> layers.
client.connection. Test the cipher strength negotiated with a securely connected client. Can also
negotiated_cipher. be used in <Exception> layers.
strength=
client.host= Test the hostname of the client (obtained through RDNS). Can also be used in
<Admin>, <Forward>, and <Exception> layers.
client.host.has_name= Test the status of the RDNS performed to determine 'client.host'. Can also be
used in <Admin>, <Forward>, and <Exception> layers.
client_protocol= Tests true if the client transport protocol matches the specification. Can also be
used in <Exception> layers.
condition= Tests if the specified defined condition is true. Can be used in all layers.
console_access= (This trigger was formerly admin=yes|no.) Tests if the current request is
destined for the admin layer. Can also be used in <Cache> and <Exception>
layers.
42
Chapter 3: Controlling Access to the Internet and Intranet
date[.utc]= Tests true if the current time is within the startdate..enddate range, inclusive.
Can be used in all layers.
day= Tests if the day of the month is in the specified range or an exact match. Can be
used in all layers.
exception.id= Indicates that the requested object was not served, providing this specific
exception page.
Can also be used in <Exception> layers.
ftp.method= Tests ftp request methods against any of a well-known set of FTP methods.
Can also be used in <Cache> and <Exception> layers.
group= Tests if the authenticated condition is set to yes, the client is authenticated, and
the client belongs to the specified group. Can also be used in <Admin> layers.
has_attribute.name= Tests if the current transaction is authenticated in an LDAP realm and if the
authenticated user has the specified LDAP attribute. Can also be used in
<Admin> layers.
hour= Tests if the time of day is in the specified range or an exact match. Can be used
in all layers.
http.method= Tests HTTP request methods against any of a well known set of HTTP
methods. Can also be used in <Cache> and <Exception> layers.
http.method.regex= Test the HTTP method using a regular expression. Can also be used in
<Exception> layers.
http.request_line.regex= Test the HTTP protocol request line. Can also be used in <Exception> layers.
http.request.version= Tests the version of HTTP used by the client in making the request to the SG
appliance. Can also be used in <Cache> and <Exception> layers.
http.response_code= Tests true if the current transaction is an HTTP transaction and the response
code received from the origin server is as specified. Can also be used in
<Cache> and <Exception> layers.
http.response.version= Tests the version of HTTP used by the origin server to deliver the response to
the SG appliance. Can also be used in <Cache> and <Exception> layers.
http.transparent_ This trigger evaluates to true if HTTP uses transparent proxy authentication
authentication= for this request. Can also be used in <Cache> and <Exception> layers.
im.buddy_id= Tests the buddy_id associated with the IM transaction. Can also be used in
<Exception> layers.
im.chat_room.conference= Tests whether the chat room associated with the transaction has the conference
attribute set. Can also be used in <Exception> layers.
im.chat_room.id= Tests the chat room ID associated with the transaction. Can also be used in
<Exception> layers.
im.chat_room.invite_ Tests whether the chat room associated with the transaction has the
only= invite_only attribute set. Can also be used in <Exception> layers.
43
Chapter 3: Controlling Access to the Internet and Intranet
im.chat_room.type= Tests whether the chat room associated with the transaction is public or
private. Can also be used in <Exception> layers.
im.chat_room.member= Tests whether the chat room associated with the transaction has a member
matching the specified criterion. Can also be used in <Exception> layers.
im.chat_room.voice_ Tests whether the chat room associated with the transaction is voice enabled.
enabled= Can also be used in <Exception> layers.
im.client= Test the type of IM client in use. Can also be used in <Exception>,
<Forward>, and <Cache> layers.
im.file.extension= Tests the file extension. Can also be used in <Exception> layers.
im.file.name= Tests the file name (the last component of the path), including the extension.
Can also be used in <Exception> layers.
im.file.path= Tests the file path against the specified criterion. Can also be used in
<Exception> layers.
im.file.size= Performs a signed 64-bit range test. Can also be used in <Exception> layers.
im.message.reflected Test whether IM reflection occurred. Can also be used in <Exception> and
<Forward> layers.
im.message.route= Tests how the IM message reaches its recipients. Can also be used in
<Exception> layers.
im.message.size= Performs a signed 64-bit range test. Can also be used in <Exception> layers.
im.message.text. Performs a signed 64-bit range test. Can also be used in <Exception> layers.
substring=
im.message.type= Tests the message type. Can also be used in <Exception> layers.
im.method= Tests the method associated with the IM transaction. Can also be used in
<Cache> and <Exception> layers.
im.user_id= Tests the user_id associated with the IM transaction. Can also be used in
<Exception> layers.
live= Tests if the streaming content is a live stream. Can also be used in <Cache>
layers.
minute= Tests if the minute of the hour is in the specified range or an exact match. Can
be used in all layers.
month= Tests if the month is in the specified range or an exact match. Can be used in all
layers.
proxy.address= Tests the IP address of the network interface card (NIC) on which the request
arrives. Can also be used in <Admin> layers.
proxy.card= Tests the ordinal number of the network interface card (NIC) used by a request.
Can also be used in <Admin> layers.
proxy.port= Tests if the IP port used by a request is within the specified range or an exact
match. Can also be used in <Admin> layers.
44
Chapter 3: Controlling Access to the Internet and Intranet
raw_url Test the value of the raw request URL. Can also be used in <Exception>
layers.
raw_url.host Test the value of the 'host' component of the raw request URL. Can also be
used in <Exception> layers.
raw_url.path Test the value of the 'path' component of the raw request URL. Can also be
used in <Exception> layers.
raw_url.pathquery Test the value of the 'path and query' component of the raw request URL. Can
also be used in <Exception> layers.
raw_url.port Test the value of the 'port' component of the raw request URL. Can also be used
in <Exception> layers.
raw_url.query Test the value of the 'query' component of the raw request URL. Can also be
used in <Exception> layers.
realm= Tests if the authenticated condition is set to yes, the client is authenticated, and
the client has logged into the specified realm. an also be used in <Admin>
layers.
request.header_address. Tests if the specified request header can be parsed as an IP address. Can also be
header_name= used in <Cache> layers.
request.header.header_ Test the number of header values in the request for the given header_name.
name.count Can also be used in <Exception> layers.
request.header.header_ Test the total length of the header values for the given header_name. Can also
name.length be used in <Exception> layers.
request.header.Referer. Test whether the Referer URL has a resolved DNS hostname. Can also be used
url.host.has_name= in <Exception> layers.
request.header.Referer. Test whether the Referer URL is expressed in absolute form. Can also be used
url.is_absolute in <Exception> layers.
request.raw_headers. Test the total number of HTTP request headers. Can also be used in
count <Exception> layers.
request.raw_headers. Test the total length of all HTTP request headers. Can also be used in
length <Exception> layers.
request.raw_headers. Test the value of all HTTP request headers with a regular expression. Can also
regex be used in <Exception> layers.
request.x_header.header_ Test the number of header values in the request for the given header_name.
name.count Can also be used in <Exception> layers.
request.x_header.header_ Test the total length of the header values for the given header_name. Can also
name.length be used in <Exception> layers.
45
Chapter 3: Controlling Access to the Internet and Intranet
server_url[.case_ Tests if a portion of the requested URL exactly matches the specified pattern.
sensitive|.no_lookup]= Can also be used in <Forward> layers.
socks.method= Tests the protocol method name associated with the transaction. Can also be
used in <Cache> and <Exception> layers.
socks.version= Switches between SOCKS 4/4a and 5. Can also be used in <Exception> and
<Forward> layers.
streaming.content= (This trigger has been renamed from streaming.) Can also be used in <Cache>,
<Exception>, and <Forward> layers.
time= Tests if the time of day is in the specified range or an exact match. Can be used
in all layers.
tunneled=
url.domain= Tests if the requested URL, including the domain-suffix portion, matches the
specified pattern. Can also be used in <Forward> layers.
url.extension= Tests if the filename extension at the end of the path matches the specified
string. Can also be used in <Forward> layers.
url.host= Tests if the host component of the requested URL matches the IP address or
domain name. Can also be used in <Forward> layers.
url.host.has_name Test whether the request URL has a resolved DNS hostname. Can also be used in
<Exception> layers
url.is_absolute Test whether the request URL is expressed in absolute form. Can also be used
in <Exception> layers
url.host.is_numeric= This is true if the URL host was specified as an IP address. Can also be used in
<Forward> layers.
url.host.no_name= This is true if no domain name can be found for the URL host. Can also be used
in <Forward> layers.
url.host.regex= Tests if the specified regular expression matches a substring of the domain
name component of the request URL. Can also be used in <Forward> layers.
url.path= Tests if a prefix of the complete path component of the requested URL, as well
as any query component, matches the specified string. Can also be used in
<Forward> layers.
url.path.regex= Tests if the regex matches a substring of the path component of the request
URL. Can also be used in <Forward> layers.
url.port= Tests if the port number of the requested URL is within the specified range or
an exact match. Can also be used in <Forward> layers.
url.query.regex= Tests if the regex matches a substring of the query string component of the
request URL. Can also be used in <Forward> layers.
46
Chapter 3: Controlling Access to the Internet and Intranet
url.regex= Tests if the requested URL matches the specified pattern. Can also be used in
<Forward> layers.
url.scheme= Tests if the scheme of the requested URL matches the specified string. Can also
be used in <Forward> layers.
user= Tests the authenticated user name of the transaction. Can also be used in
<Admin> layers.
user.domain= Tests if the authenticated condition is set to yes, the client is authenticated, the
logged-into realm is an IWA realm, and the domain component of the user
name is the specified domain. Can also be used in <Admin> layers.
weekday= Tests if the day of the week is in the specified range or an exact match. Can be
used in all layers.
year= Tests if the year is in the specified range or an exact match. Can be used in all
layers.
action.action_label( ) Selectively enables or disables a specified define action block. Can also be used
in <Cache> layers.
allow Allows the transaction to be served. Can be used in all layers except
<Exception> and <Forward> layers.
always_verify( ) Determines whether each request for the objects at a particular URL must be
verified with the origin server.
authenticate( ) Identifies a realm that must be authenticated against. Can also be used in
<Admin> layers.
authenticate.force( ) Either disables proxy authentication for the current transaction (using the
value no) or requests proxy authentication using the specified authentication
realm. Can also be used in <Admin> layers.
check_authorization( ) In connection with CAD (Caching Authenticated Data) and CPAD (Caching
Proxy Authenticated Data) support, check_authorization( ) is used
when you know that the upstream device will sometimes (not always or
never) require the user to authenticate and be authorized for this object. Can
also be used in <Cache> layers.
47
Chapter 3: Controlling Access to the Internet and Intranet
delete_on_abandonment( ) If set to yes, then if all clients requesting an object close their connections prior
to the object being delivered, the object fetch from the origin server is
abandoned. Can also be used in <Cache> layers.
deny Denies service. Can be used in all layers except <Exception> and
<Forward> layers.
dynamic_bypass( ) Used to indicate that a particular transparent request should not be handled by
the proxy, but instead be subjected to our dynamic bypass methodology.
exception( ) Indicates not to serve the requested object, but instead serve this specific
exception page.
Can be used in all layers except <Exception> layers.
http.client.recv.timeout Sets the socket timeout for receiving bytes from the client.
http.response.parse_meta Controls whether the 'Expires' META Tag is parsed in an HTML response
_tag. Expires body. Can also be used in <Cache> layers.
http.response.parse_meta Controls whether the 'Pragma: no-cache' META Tag is parsed in an HTML
_tag. Pragma.no-cache response body. Can also be used in <Cache> layers.
http.server.recv. Sets the socket timeout for receiving bytes from the upstream host. Can also be
timeout( ) used in <Forward> layers.
48
Chapter 3: Controlling Access to the Internet and Intranet
reflect_ip( ) Determines how the client IP address is presented to the origin server for
explicitly proxied requests. Can also be used in <Forward> layers.
request.filter_service( Websense is the built in service name for the off-box content filtering service.
) Can also be used in <Cache> layers.
socks.accelerate( ) The socks.accelerate property controls the SOCKS proxy handoff to other
protocol agents.
socks.authenticate( ) The same realms can be used for SOCKS proxy authentication as can be used
for regular proxy authentication.
log_message( ) Writes the specified string to the SG event log. Can be used in all layers except
<Admin>.
notify_email( ) Sends an e-mail notification to the list of recipients specified in the Event Log
mail configuration. Can be used in all layers.
notify_snmp( ) The SNMP trap is sent when the transaction terminates. Can be used in all
layers.
redirect( ) Ends the current HTTP transaction and returns an HTTP redirect response to the
client.
49
Chapter 3: Controlling Access to the Internet and Intranet
50
Chapter 4: Understanding and Managing X.509 Certificates
51
Volume 4: Securing the Blue Coat SG Appliance
Section A: Concepts
Section A: Concepts
This section discusses concepts surrounding certificates and SGOS.
Certificates
The SGOS software uses:
❐ SSL Certificates.
❐ CA Certificates.
❐ External Certificates.
You can also use wildcard certificates during HTTPS termination. Microsoft’s
implementation of wildcard certificates is as described in RFC 2595, allowing an *
(asterisk) in the leftmost-element of the server's common name only. For information on
wildcards supported by Internet Explorer, refer to the Microsoft knowledge base, article:
258858. Any SSL certificate can contain a common name with wildcard characters.
SSL Certificates
SSL certificates are used to authenticate the identity of a server or a client. A certificate is
confirmation of the association between an identity (expressed as a string of characters)
and a public key. If a party can prove they hold the corresponding private key, you can
conclude that the party is who the certificate says it is. The certificate contains other
information, such as its expiration date.
The association between a public key and a particular server is done by generating a
certificate signing request using the server's or client’s public key. A certificate signing
authority (CA) verifies the identity of the server or client and generates a signed
certificate. The resulting certificate can then be offered by the server to clients (or from
clients to servers) who can recognize the CA's signature. Such use of certificates issued by
CAs has become the primary infrastructure for authentication of communications over the
Internet.
The SG trusts all root CA certificates trusted by Internet Explorer and Firefox. The list is
updated periodically to be in sync with the latest versions of IE and Firefox.
CA certificates installed on the SG are used to verify the certificates presented by HTTPS
servers and the client certificates presented by browsers. Browsers offer a certificate if the
server is configured to ask for one and an appropriate certificate is available to the
browser.
52
Chapter 4: Understanding and Managing X.509 Certificates
Section A: Concepts
CA Certificates
CA certificates are certificates that belong to certificate authorities. CA certificates are
used by SGdevices to verify X.509 certificates presented by a client or a server during
secure communication. SG appliances are pre-installed with the most common CA
certificates.
SG appliances come with many popular CA certificates already installed. You can review
these certificates using the Management Console or the CLI. You can also add certificates
for your own internal certificate authorities.
External Certificates
An external certificate is any X509 certificate for which the SG appliance does not have the
private key. The certificate can be used to encrypt data, such as access logs, with a public
key so that it can only be decrypted by someone who has the corresponding private key.
Refer to Volume 8: Access Logging for information about encrypting access logs.
Keyrings
A keyring contains a public/private keypair. It can also contain a certificate signing
request or a signed certificate. Keyrings are named, can be created, deleted and viewed;
there are built-in keyrings for specified purposes. For information on managing keyrings,
see Section B: "Using Keyrings and SSL Certificates" on page 55.
Note: You can delete cipher suites that you do not trust. However, SGOS does not
provide any mechanism to change the ordering of the ciphers used.
All cipher suites supported by the SG appliance use the RSA key exchange algorithm,
which uses the public key encoded in the server's certificate to encrypt a piece of secret
data for transfer from the client to server. This secret is then used at both endpoints to
compute encryption keys.
By default, the SG appliance is configured to allow SSLv2 and v3 as well as TLSv1 traffic.
The cipher suites available for use differ depending on whether you configure SSL for
version 2, version 3, TLS, or a combination of these.
53
Volume 4: Securing the Blue Coat SG Appliance
Section A: Concepts
Cipher Suite configuration is discussed in “Changing the Cipher Suites of the SSL Client”
on page 234.
54
Chapter 4: Understanding and Managing X.509 Certificates
Note: You can also import keyrings. For information on importing keyrings, see
“Importing an Existing Keypair and Certificate” on page 67.
Note: These steps must be done using a secure connection such as HTTPS, SSH, or a
serial console.
55
Volume 4: Securing the Blue Coat SG Appliance
Creating a Keyring
The SG appliance ships with three keyrings already created:
❐ default: The default keyring contains a certificate and an automatically-generated
keypair. The default keyring is intended for securely accessing the SG appliance
Management Console. Create an additional keyring for each HTTPS service defined.
❐ configuration-passwords-key: The configuration-passwords-key keyring contains
a keypair but does not contain a certificate. This keyring is used to encrypt passwords
in the show config command and should not be used for other purposes.
❐ appliance-key: The appliance-key keyring contains an internally-generated keypair.
If the SG appliance is authenticated (has obtained a certificate from the Blue Coat CA
appliance-certificate server), that certificate is associated with this keyring, which is
used to authenticate the device. (For more information on authenticating the SG
appliance, refer to Volume 5: Advanced Networking.)
Note: The appliance-key keyring is used by the system. It is not available for other
purposes.
If an origin content server requires a client certificate and no keyring is associated with the
SG appliance SSL client, the HTTPS connections fails. For information on using the SSL
client, see Appendix C: "Managing the SSL Client" on page 233.
To create a keyring:
1. Select Configuration > SSL > Keyrings > SSL Keyrings.
56
Chapter 4: Understanding and Managing X.509 Certificates
Note: Spaces in keyring names are not supported. Including a space can cause
unexpected errors while using such keyrings.
Note: The choice among show, do not show keypair, and show keypair to
director has implications for whether keyrings are included in profiles and
backups created by Director. For more information, refer to the Blue Coat
Director User Guide.
• Select the key length in the Create a new ______ -bit keyring field. A length of 1024
bits is the maximum (and default). For deployments reaching outside the U.S.,
determine the maximum key length allowed for export.
Click OK. The keyring is created with the name you chose. It does not have a
certificate associated with it yet. To associate a certificate, see “Importing a Server
Certificate” on page 62.
-or-
• Select the Import keyring radio button.
57
Volume 4: Securing the Blue Coat SG Appliance
Note: The only way to retrieve a keyring's private key from the SG appliance is
by using Director or the command line —it cannot be exported through the
Management Console.
4. Click OK.
Notes
❐ To view the keypair in an encrypted format, you can optionally specify des or des3
before the keyring_id, along with an optional password. If the optional password is
provided on the command line, the CLI does not prompt for a password.
❐ If the optional password is not provided on the command line, the CLI asks for the
password (interactive). If you specify either des or des3, you are prompted.
❐ To view the keypair in unencrypted format, select either the optional keyring_id or
use the unencrypted command option.
❐ You cannot view a keypair over a Telnet connection because of the risk that it could be
intercepted.
58
Chapter 4: Understanding and Managing X.509 Certificates
Creating a CSR
To create a CSR:
1. Select Configuration > SSL > SSL Keyrings; click Edit/View.
2. From the drop-down list, select the keyring for which you need a signed certificate.
3. From the Certificate Signing Request tab, click the Create button.
59
Volume 4: Securing the Blue Coat SG Appliance
60
Chapter 4: Understanding and Managing X.509 Certificates
Note: If a Website presents a certificate that is signed by a CA not on Blue Coat default
CA list, you might see the following message:
Network Error (ssl_failed)
A secure SSL session could not be established with the Web Site:
You must import the CA Certificate onto the SG appliance before the device can trust the
site.
61
Volume 4: Securing the Blue Coat SG Appliance
Example:
SGOS#(config ssl) create certificate keyring-id cn bluecoat challenge
test c US state CA company bluecoat
62
Chapter 4: Understanding and Managing X.509 Certificates
Only CRLs that are issued by a trusted issuer can be verified by the SG appliance
successfully. The CRL can be imported only when the CRL issuer certificate exists as a CA
certificate on the SG appliance.
SGOS allows:
❐ One local CRL list per certificate issuing authority.
❐ An import of a CRL that is expired; a warning is displayed in the log.
❐ An import of a CRL that is effective in the future; a warning is displayed in the log.
CRLs can be used for the following purposes:
❐ Checking revocation status of client or server certificates with HTTPS Reverse Proxy.
❐ Checking revocation status of client or server certificates with SSL proxy. (For more
information on using CRLS with the SSL proxy, refer to Volume 2: Proxies and Proxy
Services.)
❐ SG appliance-originated HTTPS downloads (secure image download, content filter
database download, and the like).
❐ PEM-encoded CRLs, if cut and pasted through the inline command.
❐ DER-format (binary) CRLs, if downloaded from a URL.
To import a CRL:
You can choose from among four methods to install a CRL on the SG appliance:
❐ Use the Text Editor, which allows you to enter the installable list (or copy and paste
the contents of an already-created file) directly onto the SG appliance.
❐ Create a local file on your local system.
❐ Enter a remote URL, where you placed an already-created file on an FTP or HTTP
server to be downloaded to the SG appliance.
❐ Use the CLI inline command.
To update a CRL:
1. Select Configuration > SSL > CRLs.
2. Click New or highlight an existing CRL and click Edit.
3. Give the CRL a name.
4. From the drop-down list, select the method to use to install the CRL; click Install.
• Remote URL:
Enter the fully-qualified URL, including the filename, where the CRL is located.
To view the file before installing it, click View. Click Install.
The Install CRL dialog displays. Examine the installation status that displays; click
OK.
• Local File:
Click Browse to display the Local File Browse window. Browse for the CRL file on
the local system. Open it and click Install. When the installation is complete, a
results window opens. View the results, close the window, click Close.
63
Volume 4: Securing the Blue Coat SG Appliance
• Text Editor:
Copy a new CRL file into the window, and click Install.
When the installation is complete, a results window opens. View the results, close
the window, click Close.
Note: The Management Console text editor can be used to enter a CRL file. You
cannot use it to enter CLI commands.
64
Chapter 4: Understanding and Managing X.509 Certificates
4. Enter the name of the external certificate into the External Cert Name field and paste
the certificate into the External Certificate field. Be sure to include the ----BEGIN
CERTIFICATE---- and -----END CERTIFICATE---- statements.
5. Click OK.
65
Volume 4: Securing the Blue Coat SG Appliance
66
Chapter 4: Understanding and Managing X.509 Certificates
To Import a keyring:
1. Copy the already-created keypair onto the clipboard.
2. Select Configuration > SSL > Keyrings > SSL Keyrings.
3. Click Create.
67
Volume 4: Securing the Blue Coat SG Appliance
Note: The choice among show, do not show and show keypair to director has
implications for whether keyrings are included in profiles and backups created by
Director. For more information, refer to the Blue Coat Director Configuration and
Management Guide.
68
Chapter 4: Understanding and Managing X.509 Certificates
Importing a CA Certificate
A CA Certificate is a certificate that verifies the identity of a Certificate Authority. The
certificate is used by the SG appliance to verify server and client certificates.
3. Click Import.
4. Give the certificate a name.
.
Note: Spaces in CA Certificate names are not supported. Including a space can cause
unexpected errors while using such certificates.
69
Volume 4: Securing the Blue Coat SG Appliance
To view a CA certificate:
1. Select Configuration > SSL > CA Certificates > CA Certificates.
2. Select the certificate you want to view.
3. Click View.Examine the contents and click Close.
To delete a CA certificate:
1. Select Configuration > SSL > CA Certificates > CA Certificates.
2. Select the certificate to delete.
3. Click Delete.
4. Click OK.
70
Chapter 4: Understanding and Managing X.509 Certificates
5. To remove CA Certificates from the list, highlight the certificate in the Add list and
click Remove.
6. Click OK
To import a CA certificate:
1. Copy the certificate to your clipboard. Be sure to include the “Begin Certificate” and
“End Certificate” statements.
2. Select Configuration > SSL > Keyrings.
3. Highlight the keyring for which you want to import a certificate.
4. Click Edit/View in the Keyrings tab.
5. In the Certificate panel, click Import.
6. Paste the certificate you copied into the dialog box. Click OK.
The certificate should display in the SSL Certificates Pane, associated with the keyring
you selected earlier.
7. Click Apply to commit the changes to the SG appliance.
71
Volume 4: Securing the Blue Coat SG Appliance
72
Chapter 5: Certificate Realm Authentication
Certificate realms are useful for companies that have a Public Key Infrastructure (PKI)
in place and would like to have the SG appliance authenticate their end-users using the
client's X.509 certificates. If the users are members of an LDAP or Local group, the
Certificate Realm can also forward the user credentials to the specified authorization
realm, which determines the user’s authorization (permissions).
This section discusses the following topics:
❐ “How Certificate Realm Works”
❐ “Creating a Certificate Realm” on page 74
❐ “Defining a Certificate Realm” on page 74
❐ “Defining Certificate Realm General Properties” on page 75
❐ “Revoking User Certificates” on page 76
Note: If you authenticate with a certificate realm, you cannot also challenge for a
password.
73
Volume 4: Securing the Blue Coat SG Appliance
3. In the Realm name field, enter a realm name. The name can be 32 characters long and
composed of alphanumeric characters and underscores. The name must start with a
letter.
4. Click OK.
2. From the Realm name drop-down list, select the Certificate realm for which you want
to change realm properties.
3. (Optional) From the Authorization Realm Name drop-down list, select the LDAP or
Local realm you want to use to authorize users.
4. From the username attribute field, enter the attribute that specifies the common name
in the subject of the certificate. CN is the default.
5. (Optional, if you are configuring a Certificate realm with LDAP authorization) Enter
the list of attributes (the container attribute field) that should be used to construct the
user's distinguished name.
For example, $(OU) $(O) substitutes the OU and O fields from the certificate.
6. (Optional, if you are configuring a Certificate realm with LDAP authorization) Select
or deselect Append Base DN.
74
Chapter 5: Certificate Realm Authentication
7. (Optional, if you are configuring a Certificate realm with LDAP authorization) Enter
the Base DN where the search starts. If no BASE DN is specified and Append Base DN
is enabled, the first Base DN defined in the LDAP realm used for authorization is
appended.
2. From the Realm name drop-down list, select the Certificate realm for which to change
properties.
3. If needed, change the Certificate realm display name. The default value for the
display name is the realm name. The display name cannot be greater than 128
characters and it cannot be null.
4. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
5. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s certificate.
6. Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.
75
Volume 4: Securing the Blue Coat SG Appliance
7. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
8. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
9. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
10. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
11. Click Apply to commit the changes to the SG appliance.
Note: This method of revoking user certificates is meant for those with a small number of
certificates to manage.
For information on using automatically updated lists, refer to Volume 2: Proxies and Proxy
Services.
A certificate is identified by its issuer (the Certificate Signing Authority that signed it) and
its serial number, which is unique to that CA.
Using that information, you can use the following strings to create a policy to revoke user
certificates:
❐ user.x509.serialNumber—This is a string representation of the certificate’s serial
number in HEX. The string is always an even number of characters long, so if the
number needs an odd number of characters to represent in hex, there is a leading zero.
Comparisons are case insensitive.
❐ user.x509.issuer—This is an RFC2253 LDAP DN. Comparisons are case sensitive.
76
Chapter 5: Certificate Realm Authentication
Example
If you have only one Certificate Signing Authority signing user certificates, you do not
need to test the issuer. In the <Proxy> layer of the Local Policy file:
<proxy>
deny user.x509.serialnumber=11
deny user.x509.serialNumber=0F
If you have multiple Certificate Signing Authorities, test both the issuer and the serial
number. In the <Proxy> layer of the Local Policy file:
<proxy>
deny
user.x509.issuer="Email=name,CN=name,OU=name,O=company,L=city,ST=state
or province,C=country" user.x509.serialnumber=11\
deny user.x509.issuer="CN=name,OU=name,O=company, L=city,ST=state or
province,C=country" \
deny user.x509.serialnumber=2CB06E9F00000000000B
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details
about CPL and how transactions trigger the evaluation of policy file <Proxy> and other
layers.
Be aware that the default policy condition for these examples is allow. On new SGOS 5.x
systems, the default policy condition is deny.
❐ Every Certificate realm authenticated user is allowed access the SG appliance.
<Proxy>
authenticate(CertificateRealm)
❐ A subnet definition determines the members of a group, in this case, members of the
Human Resources department. (They are allowed access to the two URLs listed.
Everyone else is denied permission.)
<Proxy>
authenticate(CertificateRealm)
<Proxy>
Define subnet HRSubnet
192.168.0.0/16
10.0.0.0/24
End subnet HRSubnet
[Rule] client_address=HRSubnet
url.domain=monster.com
url.domain=hotjobs.com
deny
.
.
.
[Rule]
deny
77
Volume 4: Securing the Blue Coat SG Appliance
Tips
If you use a certificate realm and see an error message similar to the following
Realm configuration error for realm "cert": connection is not SSL.
This means that certificate authentication was requested for a transaction, but the
transaction was not done on an SSL connection, so no certificate was available.
This can happen in three ways:
❐ The authenticate mode is either origin-IP-redirect/origin-cookie-redirect or
origin-IP/origin-cookie, but the virtual URL does not have an https: scheme.
This is likely if authentication through a certificate realm is selected with no other
configuration, because the default configuration does not use SSL for the virtual URL.
❐ In a server accelerator deployment, the authenticate mode is origin and the
transaction is on a non-SSL port.
❐ The authenticate mode is origin-IP-redirect/origin-cookie-redirect, the user
has authenticated, the credential cache entry has expired, and the next operation is a
POST or PUT from a browser that does not handle 307 redirects (that is, from a
browser other than Internet Explorer). The workaround is to visit another URL to
refresh the credential cache entry and then try the POST again.
❐ Forms authentication modes cannot be used with a Certificate realm. If a form mode
is in use and the authentication realm is a Certificate realm, a Policy Substitution
realm, or an IWA realm, you receive a configuration error.
78
Chapter 6: Oracle COREid Authentication
79
Volume 4: Securing the Blue Coat SG Appliance
Important: The request URL is not sent to the Access System as the requested resource;
the requested resource is the entire SG realm. Access control of individual URLs is done
on the SG appliance using policy.
The COREid policy domain that controls the protected resource must use one of the
challenge methods supported by the SG appliance.
Supported challenge methods are Basic, X.509 Certificates and Forms. Acquiring the
credentials over SSL is supported as well as challenge redirects to another server.
The SG appliance requires information about the authenticated user to be returned as
COREid authorization actions for the associated protected resource. Since authentication
actions are not returned when a session token is simply validated, the actions must be
authorization and not authentication actions.
The following authorization actions should be set for all three authorization types
(Success, Failure, and Inconclusive):
❐ A HeaderVar action with the name BCSI_USERNAME and with the value corresponding
to the simple username of the authenticated user. For example, with an LDAP
directory this might be the value of the cn attribute or the uid attribute.
❐ A HeaderVar action with the name BCSI_GROUPS and the value corresponding to the
list of groups to which the authenticated user belongs. For example, with an LDAP
directory this might be the value of the memberOf attribute.
Once the COREid AccessGate, authentication scheme, policy domain, rules, and actions
have been defined, the SG appliance can be configured.
80
Chapter 6: Oracle COREid Authentication
Note: All SG appliance and agent configuration is done on the appliance. The appliance
sends the necessary information to BCAAA when it establishes communication.
Note: The SG appliance must not attempt to authenticate a request for the off-box
authentication URL. If necessary, authenticate(no) can be used in policy to prevent
this.
81
Volume 4: Securing the Blue Coat SG Appliance
3. In the Realm name field, enter a realm name. The name can be 32 characters long and
composed of alphanumeric characters and underscores. The name must start with a
letter. The name should be meaningful to you, but it does not have to be the name of
the COREid AccessGate.
4. Click OK.
Configuring Agents
You must configure the COREid realm so that it can find the Blue Coat Authentication and
Authorization Agent (BCAAA).
82
Chapter 6: Oracle COREid Authentication
5. Enter the AccessGate ID in the AccessGate id field. The AccessGate ID is the ID of the
AccessGate as configured in the Access System.
6. If an AccessGate password has been configured in the Access System, you must
specify the password on the SG appliance. Click Change Secret and enter the
password. The passwords can be up to 64 characters long and are always case
sensitive.
7. (Optional) Enter an alternate agent host and AccessGate ID in the Alternate agent
section.
8. (Optional) Select Enable SSL to enable SSL between the SG appliance and the BCAAA
agent.
9. (Optional) By default, if SSL is enabled, the COREid BCAAA certificate is verified. If
you do not want to verify the agent certificate, disable this setting.
10. Specify the length of time in the Timeout Request field, in seconds, to elapse before
timeout if a response from BCAAA is not received. (The default request timeout is 60
seconds.)
11. If you want username and group comparisons on the SG appliance to be case
sensitive, select Case sensitive.
83
Volume 4: Securing the Blue Coat SG Appliance
84
Chapter 6: Oracle COREid Authentication
2. From the Realm name drop-down list, select the COREid realm for which you want to
change properties.
3. If needed, change the COREid realm display name. The default value for the display
name is the realm name. The display name cannot be greater than 128 characters and
it cannot be null.
4. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
5. Enter the number of seconds in the Credential refresh time field. The Credential
Refresh Time is the amount of time basic credentials (username and password) are
kept on the SG appliance. This feature allows the SG appliance to reduce the load on
the authentication server and enables credential spoofing. It has a default setting of
900 seconds (15 minutes). You can configure this in policy for better control over the
resources as policy overrides any settings made here.
Before the refresh time expires, the SG appliance will authenticate the user supplied
credentials against the cached credentials. If the credentials received do not match the
cached credentials, they are forwarded to the authentication server in case the user
password changed. After the refresh time expires, the credentials are forwarded to the
authentication server for verification.
6. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
8. If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.
9. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
85
Volume 4: Securing the Blue Coat SG Appliance
10. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
11. Specify the virtual URL to redirect the user to when they need to be challenged by the
SG appliance. If the appliance is participating in SSO, the virtual hostname must be in
the same cookie domain as the other servers participating in the SSO. It cannot be an
IP address or the default, www.cfauth.com.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Click Apply to commit the changes to the SG appliance.
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details
about CPL and how transactions trigger the evaluation of policy file <Proxy> and other
layers.
86
Chapter 6: Oracle COREid Authentication
87
Volume 4: Securing the Blue Coat SG Appliance
88
Chapter 7: Forms-Based Authentication
You can use forms-based authentication exceptions to control what your users see
during authentication. You can:
❐ Specify the realm the user is to authenticate against.
❐ Specify that the credentials requested are for the SG appliance. This avoids
confusion with other authentication challenges.
❐ Make the form comply with company standards and provide other information,
such as a help link.
The authentication form (an HTML document) is served when the user makes a
request and requires forms-based authentication. If the user successfully authenticates
to the SG appliance, the appliance redirects the user back to the original request.
If the user does not successfully authenticate against the SG appliance and the error is
user-correctable, the user is presented with the authentication form again.
Note: You can configure and install an authentication form and several
properties through the Management Console and the CLI, but you must use policy
to dictate the authentication form’s use.
With forms-based authenticating, you can set limits on the maximum request size to
store and define the request object expiry time. You can also specify whether to verify
the client’s IP address against the original request and whether to allow redirects to the
original request.
To create and put into use forms-based authentication, you must complete the
following steps:
❐ Create a new form or edit one of the existing authentication form exceptions
❐ Set storage options
❐ Set policies
89
Volume 4: Securing the Blue Coat SG Appliance
90
Chapter 7: Forms-Based Authentication
❐ Form action URI: The value is the authentication virtual URL plus the query string
containing the base64 encoded original URL $(x-cs-auth-form-action-url).
❐ Form METHOD of POST. The form method must be POST. The SG appliance does not
process forms submitted with GET.
The SG appliance only parses the following input fields during form submission:
❐ PROXY_SG_USERNAME (required)
❐ PROXY_SG_PASSWORD (required)
❐ PROXY_SG_REQUEST_ID (required)
❐ PROXY_SG_PRIVATE_CHALLENGE_STATE (required)
Authentication_form
The initial form, authentication_form, looks similar to the following:
<HTML>
<HEAD>
<TITLE>Enter Proxy Credentials for Realm $(cs-realm)</TITLE>
</HEAD>
<BODY>
<H1>Enter Proxy Credentials for Realm $(cs-realm)</H1>
<P>Reason for challenge: $(exception.last_error)
<P>$(x-auth-challenge-string)
<FORM METHOD="POST" ACTION=$(x-cs-auth-form-action-url)>
$(x-cs-auth-form-domain-field)
<P>Username: <INPUT NAME="PROXY_SG_USERNAME" MAXLENGTH="64"
VALUE=$(cs-username)></P>
<P>Password: <INPUT TYPE=PASSWORD NAME="PROXY_SG_PASSWORD"
MAXLENGTH="64"></P>
<INPUT TYPE=HIDDEN NAME="PROXY_SG_REQUEST_ID" VALUE=$(x-cs-auth-
request-id)>
<INPUT TYPE=HIDDEN NAME="PROXY_SG_PRIVATE_CHALLENGE_STATE"
VALUE=$(x-auth-private-challenge-state)>
<P><INPUT TYPE=SUBMIT VALUE="Submit"> <INPUT TYPE=RESET></P>
</FORM>
<P>$(exception.contact)
</BODY>
</HTML>
If the realm is an IWA realm, the $(x-cs-auth-form-domain-field) substitution
expands to:
<P>Domain: <INPUT NAME=PROXY_SG_DOMAIN MAXLENGTH=64 VALUE=$(x-cs-auth-
domain)>
If you specify $(x-cs-auth-form-domain-field), you do not need to explicitly add the
domain input field.
For comparison, the new_pin_form and query_form look similar to the following:
91
Volume 4: Securing the Blue Coat SG Appliance
New_pin_form
<HTML>
<HEAD>
<TITLE>Create New PIN for Realm $(cs-realm)</TITLE>
<SCRIPT LANGUAGE="JavaScript"><!--
function validatePin() {
var info;
var pin = document.pin_form.PROXY_SG_PASSWORD;
if (pin.value != document.pin_form.PROXY_SG_RETYPE_PIN.value) {
info = "The PINs did not match. Please enter them again.";
} else {
// Edit this regular expression to match local PIN
definition
var re=/^[A-Za-z0-9]{4,16}$/
var match=re.exec(pin.value);
if (match == null) {
info = "The PIN must be 4 to 16 alphanumeric
characters";
} else {
return true;
}
}
alert(info);
pin.select();
pin.focus();
return false;
}// -->
</script>
</HEAD>
<BODY>
<H1>Create New PIN for Realm $(cs-realm)</H1>
<P>$(x-auth-challenge-string)
<FORM NAME="pin_form" METHOD="POST" ACTION=$(x-cs-auth-form-action-
url)ONSUBMIT="return validatePin()">
$(x-cs-auth-form-domain-field)
<P> Enter New Pin: <INPUT TYPE=PASSWORD NAME="PROXY_SG_PASSWORD"
MAXLENGTH="64"></P>
<P>Retype New Pin: <INPUT TYPE=PASSWORD NAME="PROXY_SG_RETYPE_PIN"
MAXLENGTH="64"></P>
<INPUT TYPE=HIDDEN NAME="PROXY_SG_USERNAME" VALUE=$(cs-username)>
<INPUT TYPE=HIDDEN NAME="PROXY_SG_REQUEST_ID" VALUE=$(x-cs-auth-
request-id)>
<INPUT TYPE=HIDDEN NAME="PROXY_SG_PRIVATE_CHALLENGE_STATE" VALUE=$(x-
auth-private-challenge-state)>
<P><INPUT TYPE=SUBMIT VALUE="Submit"></P>
</FORM>
<P>$(exception.contact)
</BODY>
</HTML>
92
Chapter 7: Forms-Based Authentication
Query_form
<HTML>
<HEAD>
<TITLE>Query for Realm $(cs-realm)</TITLE>
</HEAD>
<BODY>
<H1>Query for Realm $(cs-realm)</H1>
<P>$(x-auth-challenge-string)
<FORM METHOD="POST" ACTION=$(x-cs-auth-form-action-url)>
$(x-cs-auth-form-domain-field)
<INPUT TYPE=HIDDEN NAME="PROXY_SG_USERNAME" VALUE=$(cs-username)>
<INPUT TYPE=HIDDEN NAME="PROXY_SG_REQUEST_ID" VALUE=$(x-cs-auth-
request-id)>
<INPUT TYPE=HIDDEN NAME="PROXY_SG_PRIVATE_CHALLENGE_STATE" VALUE=$(x-
auth-private-challenge-state)>
<INPUT TYPE=HIDDEN NAME="PROXY_SG_PASSWORD"">
<P><INPUT TYPE=SUBMIT VALUE="Yes"
ONCLICK="PROXY_SG_PASSWORD.value='Y'">
<INPUT TYPE=SUBMIT VALUE="No" ONCLICK="PROXY_SG_PASSWORD.value='N'"></
P>
</FORM>
<P>$(exception.contact)
</BODY>
</HTML>
x-auth-private-challenge-
state
Note: Any substitutions that are valid in CPL and in other exceptions are valid in
authentication form exceptions.
For a discussion of CPL and a complete list of CPL substitutions, as well as a description
of each substitution, refer to Volume 10: Blue Coat SG Appliance Content Policy Language
Guide.
93
Volume 4: Securing the Blue Coat SG Appliance
Tip
There is no realm restriction on the number of authentication form exceptions you can
create. You can have an unlimited number of forms, although you might want to make
them as generic as possible to cut down on maintenance.
94
Chapter 7: Forms-Based Authentication
Note: View in the Authentication Forms panel and View in the Default
Definitions panel have different functions. View in the Authentication Forms
panel allows you to view the form you highlighted; View in the Default
Definitions panel allows you view the original, default settings for each form.
This is important in an upgrade scenario; any forms already installed will not be
changed. You can compare existing forms to the default version and decide if
your forms need to be modified.
❐ Enter the form name and select the authentication type from the dropdown menu.
❐ Click OK.
To edit a form:
Select the form you want to edit and click Edit.
95
Volume 4: Securing the Blue Coat SG Appliance
❐ From the drop-down list, select the method to use to install the authentication form;
click Install.
• Remote URL:
Enter the fully-qualified URL, including the filename, where the authentication
form is located. To view the file before installing it, click View. Click Install. To
view the results, click Results; to close the dialog when through, click OK.
• Local File:
Click Browse to bring up the Local File Browse window. Browse for the file on the
local system. Open it and click Install. When the installation is complete, a results
window opens. View the results; to close the window, click Close.
• Text Editor:
The current authentication form is displayed in the text editor. You can edit the
form in place. Click Install to install the form. When the installation is complete, a
results window opens. View the results; to close the window, click Close.
96
Chapter 7: Forms-Based Authentication
2. In the Maximum request size to store (Megabytes) field, enter the maximum POST
request size allowed during authentication. The default is 50 megabytes.
3. In the Request object expiry time (seconds) field, enter the amount of time before the
stored request expires. The default is 300 seconds (five minutes). The expiry time
should be long enough for the user to fill out and submit the authentication form.
4. If you do not want the SG appliance to Verify the IP address against the original
request, deselect that option. The default is to verify the IP address.
5. To Allow redirects from the origin servers, select the checkbox. The default is to not
allow redirects from origin servers.
Note: During authentication, the user's POST is redirected to a GET request. The
client therefore automatically follows redirects from the origin server. Because the SG
appliance is converting the GET to a POST and adding the post data to the request
before contacting the origin server, the administrator must explicitly specify that
redirects to these POSTs requests can be automatically followed.
97
Volume 4: Securing the Blue Coat SG Appliance
98
Chapter 7: Forms-Based Authentication
Note: Each of these conditions can be used with the form authentication modes only.
If no form is specified, the form defaults to the CPL condition for that form. That is, if
no name is specified for authenticate.form(form_name), the default is
authentication_form; if no name is specified for
authenticate.new_pin_form(form_name), the default is
authenticate.new_pin_form, and if no name is specified for
authenticate.query_form(form_name), the default is authenticate.query_form.
99
Volume 4: Securing the Blue Coat SG Appliance
Tips
❐ If the user is supposed to be challenged with a form on a request for an image or
video, the SG appliance returns a 403 error page instead of the form. If the reason for
the challenge is that the user's credentials have expired and the object is from the same
domain as the container page, then reloading the container page results in the user
receiving the authentication form and being able to authenticate. However, if the
client browser loads the container page using an existing authenticated connection,
the user might still not receive the authentication form.
Closing and reopening the browser should fix the issue. Requesting a different site
might also cause the browser to open a new connection and the user is returned the
authentication form.
If the container page and embedded objects have a different domain though and the
authentication mode is form-cookie, reloading or closing and reopening the browser
might not fix the issue, as the user is never returned a cookie for the domain the object
belongs to. In these scenarios, Blue Coat recommends that policy be written to either
bypass authentication for that domain or to use a different authentication mode such
as form-cookie-redirect for that domain.
❐ Forms-based authentication works with HTTP browsers only.
❐ Because forms only support Basic authentication, authentication-form exceptions
cannot be used with a Certificate realm. If a form is in use and the authentication
realm is or a Certificate realm, you receive a configuration error.
❐ User credentials are sent in plain text. However, they can be sent securely using SSL if
the virtual URL is HTTPS.
❐ Because not all user requests support forms (such as WebDAV and streaming), create
policy to bypass authentication or use a different authentication mode with the same
realm for those requests.
100
Chapter 8: IWA Realm Authentication and Authorization
101
Volume 4: Securing the Blue Coat SG Applianc
2. Click New.
3. In the Realm name field, enter a realm name. The name can be 32 characters long and
composed of alphanumeric characters and underscores. The name must start with a
letter.
4. Identify the primary server host for the machine running BCAAA. You must enter a
valid host or an error message is generated.
5. (Optional) The default port is 16101. You can change the port number if the primary
server is listening on a different port.
6. Click OK.
7. Select Apply to commit the changes to the SG appliance.
IWA Servers
Once you create an IWA realm, you can use the IWA Servers page to change the current
default settings.
1. Select Configuration > Authentication > IWA > IWA Servers.
2. From the Realm name drop-down list, select the IWA realm for which you want to
change server properties.
You must define at least one IWA realm (using the IWA Realms page) before
attempting to set IWA server properties. If the message Realms must be added in the
IWA Realms tab before editing this tab is displayed in red at the bottom of this page,
you do not currently have any IWA realms defined
3. Specify the host and port for the primary IWA server. The default port is 16101.
102
Chapter 8: IWA Realm Authentication and Authorization
4. (Optional) Specify the host and port for the alternate IWA server. The default port is
16101.
5. (Optional) Under SSL Options, click the SSL enable checkbox to enable SSL.
6. (Optional) By default, if SSL is enabled, the BCAAA certificate is verified. If you do
not want to verify the BCAAA certificate, deselect this checkbox.
7. In the Timeout Request field, type the number of seconds the SG appliance allows for
each request attempt before timing out. (The default request timeout is 60 seconds.)
8. You can enable or disable support for Basic credentials in the realm by selecting or
deselecting the Allow Basic credentials checkbox.
At least one Basic or NTLM/Kerberos credential must be enabled. Note that Basic
credentials cannot be disabled in the IWA realm if the IWA realm is part of a sequence
realm but is not the first realm in the sequence with try IWA authentication only once
enabled.
You can disable both NTLM and Kerberos credentials, leaving a realm that collects
plaintext credentials but validates them against a Windows domain.
Important: The configuration of the realm can have significant security implications.
If an IWA realm accepts Basic credentials, the client can automatically downgrade to
sending the password in plaintext. Similarly, the client can use NTLM instead of
Kerberos.
9. (Optional) You can enable or disable support for NTLM credentials in the realm by
selecting or deselecting the Allow NTLM credentials checkbox. You can only enable
support for Kerberos credentials in the realm if support for NTLM credentials has
been enabled.
10. (Optional) You can enable or disable support for Kerberos credentials in the realm by
selecting or deselecting the Allow Kerberos credentials.You can only enable support
for Kerberos credentials in the realm if support for NTLM credentials has been
enabled.
11. Select Apply to commit the changes to the SG appliance.
12. Repeat the above steps for additional IWA realms, up to a total of 40.
103
Volume 4: Securing the Blue Coat SG Applianc
2. From the Realm name drop-down list, select the IWA realm for which you want to
change properties.
3. If needed, change the IWA realm display name. The default value for the display
name is the realm name. The display name cannot be greater than 128 characters and
it cannot be null.
4. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
5. Enter the number of seconds in the Credential refresh time field. The Credential
Refresh Time is the amount of time basic credentials (username and password) are
kept on the SG appliance. This feature allows the SG appliance to reduce the load on
the authentication server and enables credential spoofing. It has a default setting of
900 seconds (15 minutes). You can configure this in policy for better control over the
resources as policy overrides any settings made here.
Before the refresh time expires, the SG appliance will authenticate the user supplied
credentials against the cached credentials. If the credentials received do not match the
cached credentials, they are forwarded to the authentication server in case the user
password changed. After the refresh time expires, the credentials are forwarded to the
authentication server for verification.
6. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
104
Chapter 8: IWA Realm Authentication and Authorization
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
8. If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.
9. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
10. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
11. In the Virtual URL field, enter the URL to redirect to when the user needs to be
challenged for credentials if using a redirecting authenticate.mode.
Note: The virtual URL is not involved if the challenge does not redirect.
You can specify a virtual URL based on the individual realm. For more information on
the virtual URL, see “Understanding Origin-Style Redirection” on page 34.
When NTLM is in use, requests to the virtual URL must be sent to the proxy. This can
be done either by transparent redirection or by making the virtual URL hostname
resolve to an IP address of the proxy.
When Kerberos is in use:
• The virtual URL hostname must be part of the Kerberos realm (this is using the
term realm in the Kerberos sense, not the SG appliance sense).
• For a forward proxy, this hostname should be added to the DNS server for the
same domain as the Kerberos protected resources so that requests for this address
go directly to the SG appliance.
In both NTLM and Kerberos, if single-sign on is desired, then the virtual URL
hostname must have no dots and must not be proxied by the browser. The client must
be able to resolve this hostname to an IP address of the proxy.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Select Apply to commit the changes to the SG appliance.
105
Volume 4: Securing the Blue Coat SG Applianc
106
Chapter 8: IWA Realm Authentication and Authorization
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details
about CPL and how transactions trigger the evaluation of policy file layers.
Notes
❐ Forms authentication modes cannot be used with an IWA realm that allows only
NTLM/Kerberos credentials. If a form mode is in use and the authentication realm is
an IWA realm, you receive a configuration error.
❐ For Windows Internet Explorer IWA users who want true single-sign-on (allowing
Internet Explorer to provide your credentials automatically when challenged), you
must set the virtual URL to a hostname that is resolvable to the IP address of the SG
appliance by the client machines. Dots (for example, 10.1.1.1) are not allowed.
Note: Firefox (1.02 and higher) allows NTLM credentials for single sign-on but not
Kerberos.
To define the information in Internet Explorer, navigate to Internet Options > Security >
Local intranet > Sites > Advanced > Web sites. (For XP, navigate to Internet Options >
Security > Internet > Custom Level, then select Automatic logon with current username
and password.)
For Windows Internet Explorer 6.x, add the virtual host address.
107
Volume 4: Securing the Blue Coat SG Applianc
108
Chapter 9: LDAP Realm Authentication and Authorization
Many companies and organizations use the Lightweight Directory Access Protocol
(LDAP) as the directory protocol of choice, enabling software to find an individual user
without knowing where that user is located in the network topography.
This section discusses the following topics:
❐ “Overview”
❐ “Creating an LDAP Realm” on page 110
❐ “LDAP Servers” on page 111
❐ “Defining LDAP Base Distinguished Names” on page 112
❐ “LDAP Search & Groups Tab (Authorization and Group Information)” on page 114
❐ “Customizing LDAP Objectclass Attribute Values” on page 116
❐ “Defining LDAP General Realm Properties” on page 117
❐ “Creating the CPL” on page 119
Overview
Blue Coat supports both LDAP v2 and LDAP v3, but recommends LDAP v3 because it
uses Transport Layer Security (TLS) and SSL to provide a secure connection between
the SG appliance and the LDAP server.
An LDAP directory, either version 2 or version 3, consists of a simple tree hierarchy. An
LDAP directory might span multiple LDAP servers. In LDAP v3, servers can return
referrals to others servers back to the client, allowing the client to follow those referrals
if desired.
Directory services simplify administration; any additions or changes made once to the
information in the directory are immediately available to all users and directory-
enabled applications, devices, and SG appliances.
The SG appliance supports the use of external LDAP database servers to authenticate
and authorize users on a per-group or per-attribute basis.
LDAP group-based authentication for the SG appliance can be configured to support
any LDAP-compliant directory including:
❐ Microsoft Active Directory Server
❐ Novell NDS/eDirectory Server
❐ Netscape/Sun iPlanet Directory Server
❐ Other
The SG appliance also provides the ability to search for a single user in a single root of
an LDAP directory information tree (DIT), and to search in multiple Base Distinguished
Names (DNs).
You can configure a LDAP realm to use SSL when communicating to the LDAP server.
Configuring LDAP involves the following steps:
❐ Creating a realm (up to 40) and configuring basic settings.
109
Volume 4: Securing the Blue Coat SG Appliance
3. In the Real name field, enter a realm name. The name can be 32 characters long and
composed of alphanumeric characters and underscores. The name must start with a
letter.
4. From the Type of LDAP server drop-down list, select the specific LDAP server.
5. Specify the host and port for the primary LDAP server. The host must be entered. The
default port number is 389.
6. In the User attribute type field, specify the default user attribute type for the type of
LDAP server.
7. Click OK.
8. Click Apply to commit the changes to the SG appliance.
110
Chapter 9: LDAP Realm Authentication and Authorization
LDAP Servers
Once you have created an LDAP realm, you can use the LDAP Servers page to change the
current default settings.
2. From the Realm Name drop-down list, select the LDAP realm for which you want to
change server properties.
3. From the Type of LDAP server drop-down list, select the specific LDAP server.
4. From the LDAP Protocol Version drop-down list, select v2 for LDAP v2 support. LDAP
v3 is the default.
If you use LDAP v3, you can select Follow referrals to allow the client to follow
referrals to other servers. (This feature is not available with LDAP v2.) The default is
Disabled.
5. Specify the host and port for the primary LDAP server. The host must be entered. The
default port number is 389.
6. (Optional) Specify the host and port for the alternate LDAP server. The default port is
389.
7. (Optional) Under SSL Options, select Enable SSL to enable SSL. You can only select
this option if you are using LDAP v3.
8. (Optional) By default, if SSL is enabled, the LDAP server certificate is verified. If you
do not want to verify the server certificate, disable this setting.
9. (Optional) Change the timeout request for the server from its default of 60 seconds.
10. If the LDAP server is configured to expect case-sensitive usernames and passwords,
select Case sensitive.
11. Click Apply to commit the changes to the SG appliance.
12. Repeat the above steps for additional LDAP realms, up to a total of 40.
111
Volume 4: Securing the Blue Coat SG Appliance
112
Chapter 9: LDAP Realm Authentication and Authorization
2. From the Realm name drop-down list, select the LDAP realm for which you want to
change DN properties.
3. In the User attribute type field, the SG appliance has entered the default user attribute
type for the type of LDAP server you specified when creating the realm.
If you entered information correctly when creating the realm, you do not need to
change the User attribute type in this step. If you do need to change or edit the entry,
do so directly in the field.
4. Enter as many Base DNs as you need for the realm. Assume, for example, that
Sample_Company has offices in New York and Lisbon, each with its own Base DN. A
simplified directory information tree is illustrated below.
To specify entries for the Base DNs field, click New, enter the Base DN, and click OK.
Repeat for multiple Base DNs. To search all of Sample_Company, enter o values:
To search the manufacturing organizations, rather than starting at the top, enter ou
and o values.
113
Volume 4: Securing the Blue Coat SG Appliance
You can add, edit, and delete Base DNs for an SG appliance to search. You can also
select an individual DN and move it up or down in the list with the Promote and
Demote buttons. The appliance searches multiple DNs in the order listed, starting at
the top and working down.
5. Click Apply to commit the changes to the SG appliance.
Note: Authorization decisions are completely handled by policy. The groups that the
appliance looks up and queries are derived from the groups specified in policy in
group= conditions, attribute= conditions, and has_attribute conditions. If you do not
have any of those conditions, then Blue Coat does not look up any groups or attributes to
make policy decisions based on authorization.
2. From the Realm name drop-down list, select the LDAP realm for which you want to
specify authorization information.
3. Specify whether to allow anonymous search or to enforce user authentication before
allowing a search.
114
Chapter 9: LDAP Realm Authentication and Authorization
Some directories require a valid user to be able to perform an LDAP search; they do
not allow anonymous bind. (Active Directory is one such example.) For these
directories, you must specify a valid fully-qualified distinguished username and the
password that permits directory access privileges. (For example,
cn=user1,cn=users,dc=bluecoat,dc=com is a possible fully-qualified distinguished
name.)
To permit users to anonymously bind to the LDAP service, select Anonymous Search
Allowed. For example, with Netscape/iPlanet Directory Server, when anonymous
access is allowed, no username or password is required by the LDAP client to retrieve
information.
The LDAP directory attributes available for an anonymous client are typically a
subset of those available when a valid user distinguished name and password have
been used as search credentials.
To enforce user authentication before binding to the LDAP service, deselect
Anonymous Search Allowed, and set the Search User DN and Search User Password.
Enter a user distinguished name in the Search User DN field. This username can
identify a single user or a user object that acts as a proxy for multiple users (a pool of
administrators, for example). A search user distinguished name can be up to 512
characters long.
You can set or change the user password by clicking Change Password. This password
can be up to 64 alphanumeric characters long.
You might want to create a separate user (such as Blue Coat, for example) instead of
using an Administrator distinguished name and password.
The Dereference level field has four values—always, finding, never, searching—that
allow you to specify when to search for a specific object rather than search for the
object’s alias. The default is Always.
4. Group Information
Membership type and Membership attribute: The SG appliance enters the appropriate
default:
• Microsoft Active Directory:
Membership type: user
Membership attribute type: memberOf
• Netscape/Sun iPlanet:
Membership type:group
Membership attribute type:uniqueMember
• Novell NDS eDirectory
Membership type:group
Membership attribute type:member
• Other
Membership type:user
Membership attribute type:member
Username type to lookup: Select either FQDN or Relative. Only one can be selected at a
time.
• Relative can only be selected in the membership type is Group.
• FQDN indicates that the lookup is done only on the user object. FQDN can be
selected when the membership type is either Group or User.
115
Volume 4: Securing the Blue Coat SG Appliance
5. Nested LDAP: If the LDAP server you use does not natively support group
membership tests of nested groups, you can select the Nested LDAP checkbox.
6. Nested group attribute: For other, ad and nds, the default attribute is member. For
iPlanet, the attribute is uniqueMember.
7. Click Apply to commit the changes to the SG appliance.
2. From the Realm name drop-down list, select the LDAP realm whose objectclasses you
want to modify.
3. From the Object type drop-down list, select the type of object: container, group, or user.
4. To create or edit an object for the specified objectclass, click New or Edit. (The only
difference is whether you are adding or editing an objectclass value.)
5. Enter or edit the objectclass, and click OK.
6. Click Apply to commit the changes to the SG appliance.
116
Chapter 9: LDAP Realm Authentication and Authorization
2. From the Realm name drop-down list, select the LDAP realm for which you want to
change properties.
3. If needed, give the LDAP realm a display name. The default value for the display
name is the realm name. The display name cannot be greater than 128 characters and
it cannot be null.
4. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
5. Enter the number of seconds in the Credential refresh time field. The Credential
Refresh Time is the amount of time basic credentials (username and password) are
kept on the SG appliance. This feature allows the SG appliance to reduce the load on
the authentication server and enables credential spoofing. It has a default setting of
900 seconds (15 minutes). You can configure this in policy for better control over the
resources as policy overrides any settings made here.
Before the refresh time expires, the SG appliance will authenticate the user supplied
credentials against the cached credentials. If the credentials received do not match the
cached credentials, they are forwarded to the authentication server in case the user
password changed. After the refresh time expires, the credentials are forwarded to the
authentication server for verification.
6. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
117
Volume 4: Securing the Blue Coat SG Appliance
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7. Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.
8. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
9. If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.
10. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
11. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
12. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
13. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
14. Click Apply to commit the changes to the SG appliance.
118
Chapter 9: LDAP Realm Authentication and Authorization
119
Volume 4: Securing the Blue Coat SG Appliance
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details
about CPL and how transactions trigger the evaluation of policy file layers.
Be aware that the default policy condition for these examples is allow. The default policy
condition on new SGOS 5.x systems is deny.
❐ Every LDAP-authenticated user is allowed access the SG appliance.
<Proxy>
authenticate(LDAPRealm)
❐ Group membership is the determining factor in granting access to the SG appliance.
<Proxy>
authenticate(LDAPRealm)
<Proxy>
group=”cn=proxyusers, ou=groups, o=myco”
deny
❐ A subnet definition determines the members of a group, in this case, members of the
Human Resources department.
<Proxy>
authenticate(LDAPRealm)
<Proxy>
Define subnet HRSubnet
192.168.0.0/16
10.0.0.0/24
End subnet HRSubnet
[Rule] client_address=HRSubnet
url.domain=monster.com
url.domain=hotjobs.com
deny
.
.
.
[Rule]
deny
Notes
If you use guest authentication/authorization, note that:
❐ LDAP realms provide split authorization, and it is possible to be successfully
authenticated but have authorization fail.
❐ If the LDAP realm validate authorized user command is disabled and the user
does not exist in the authorization realm, authorization is considered a success and
the user is assigned to the default group if there is one configured and it is of interest
to policy.
120
Chapter 10: Local Realm Authentication and Authorization
Using a Local realm is appropriate when the network topography does not include
external authentication or when you want to add users and administrators to be used
by the SG appliance only.
The Local realm (you can create up to 40) uses a Local User List, a collection of users and
groups stored locally on the SG appliance. You can create up to 50 different Local User
Lists. Multiple Local realms can reference the same list at the same time, although each
realm can only reference one list at a time. The default list used by the realm can be
changed at any time.
This section discusses the following topics:
❐ “Creating a Local Realm”
❐ “Changing Local Realm Properties” on page 121
❐ “Defining the Local User List” on page 123
❐ “Creating the CPL” on page 129
3. In the Realm name field, enter a realm name. The name can be 32 characters long
and composed of alphanumeric characters and underscores. The name must start
with a letter.
4. Click OK.
121
MACH5: Configuration and Management Guide
2. From the Realm name drop-down list, select the Local realm for which you want to
change properties.
3. Display name: The default value for the display name is the realm name. The display
name cannot be greater than 128 characters and it cannot be null.
4. Local user list: the local user list from the drop-down list.
5. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
6. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7. Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.
8. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
9. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
10. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
122
Chapter 10: Local Realm Authentication and Authorization
11. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Click Apply to commit the changes to the SG appliance.
Notes
If you use guest authentication/authorization, note that:
❐ Local realms provide split authorization, and it is possible to be successfully
authenticated but have authorization fail.
❐ If the Local realm validate authorized user command is disabled and the user
does not exist in the authorization realm, authorization is considered a success and
the user is assigned to the default group if there is one configured and it is of interest
to policy.
123
MACH5: Configuration and Management Guide
Username
The username must be case-sensitively unique, and can be no more than 64 characters
long. All characters are valid, except for a colon (:).
A new local user is enabled by default and has an empty password.
List of Groups
You cannot add a user to a group unless the group has previously been created in the list.
The group name must be case-sensitively unique, and can be no more than 64 characters
long. All characters are valid, except for colon (:).
The groups can be created in the list; however, their user permissions are defined through
policies only.
Hashed Password
The hashed password must be a valid UNIX DES or MD5 password whose plain-text
equivalent cannot be more than 64 characters long.
124
Chapter 10: Local Realm Authentication and Authorization
To populate the local user list using an off-box .htpasswd file, continue with the next
section. To populate the local user list using the SG appliance CLI, go to “Defining the
Local User List” on page 123.
Important: Because the -c option overwrites the existing file, do not use the option if
you are adding users to an existing .htpasswd file.
Once you have added the users to the .htpasswd file, you can manually edit the file to add
user groups. When the .htpasswd file is complete, it should have the following format:
user:encrypted_password:group1,group2,…
user:encrypted_password:group1,group2,…
Note: You can also modify the users and groups once they are loaded on the SG
appliance. To modify the list once it is on the appliance, see “Populating a Local User List
through the SG Appliance” on page 126.
Note: To use the set_auth.pl script, you must have Perl binaries on the system where
the script is running.
125
MACH5: Configuration and Management Guide
where username and password are valid administrator credentials for the SG
appliance.
Note: To add users and groups to the list, enter the following commands, beginning
with groups, since they must exist before you can add them to a user account.
Note: If you enter a plain-text password, the SG appliance hashes the password. If you
enter a hashed password, the appliance does not hash it again.
126
Chapter 10: Local Realm Authentication and Authorization
Note: If a user has no failed logins, the statistic does not display.
127
MACH5: Configuration and Management Guide
Users:
Groups:
test1
Users:
Groups:
128
Chapter 10: Local Realm Authentication and Authorization
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details
about CPL and how transactions trigger the evaluation of policy file layers.
129
MACH5: Configuration and Management Guide
130
Chapter 11: Policy Substitution Realm
131
Volume 4: Securing the Blue Coat SG Appliance
❐ A user field: A string containing policy substitutions that describes how to construct
the simple username.
❐ A full username field: A string containing policy substitutions that describes how to
construct the full username, which is used for authorization realm lookups. This can
either be an LDAP FQDN when the authorization realm is an LDAP realm, or a simple
name when local realms are being used for authorization.
Note: The user field and username field must include at least one substitution that
successfully evaluates in order for the user to be considered authenticated.
If no policy substitutions exist that map directly to the user's simple and full usernames
but there are substitutions that map to attributes on the user on the LDAP server, the
user's identity can be determined by searching the LDAP server. The following fields are
used to determine the user's identity by LDAP search:
❐ LDAP search realm: The LDAP realm on the SG appliance that corresponds to the
LDAP server where the user resides
❐ Search filter: An LDAP search filter as defined in RFC 2254 to be used in the LDAP
search operation. Similar to the explicitly defined username and full username fields,
the search filter string can contain policy substitutions that are available based on the
user's request. The search filter string must be escaped according to RFC 2254. The
policy substitution modifier escape_ldap_filter is recommended to use with any
policy substitutions that could contain characters that need to be escaped. It will
escape the policy substitution value per RFC 2254.
Note: The search filter must include at least one substitution that successfully
evaluates before the LDAP search will be issued and the user authenticated.
❐ User attribute: The attribute on the search result entry that corresponds to the user's
full username. If the search result entry is a user entry, the attribute is usually the
FQDN of that entry. The user's full username is the value of the specified attribute. If
the attribute value is an FQDN, the user's simple username is the value of the first
attribute in the FQDN. If the attribute value is not an FQDN, the simple username is
the same as the full username.
Note: Policy Substitution realms never challenge for credentials. If the username
and full username cannot be determined from the configured substitutions,
authentication in the Policy Substitution realm fails.
132
Chapter 11: Policy Substitution Realm
Note: If all the policy substitutions fail, authentication fails. If any policy
substitution works, authentication succeeds in the realm.
Example
The following is an example of how to use substitutions with Policy Substitution realms.
Assumptions:
❐ The user susie.smith is logged in to a Windows client computer at IP address
10.25.36.47.
❐ The Windows messenger service is enabled on the client computer.
❐ The client computer is in the domain AUTHTEAM.
❐ The customer has an LDAP directory in which group information is stored. The DN
for a user's group information is
cn=username,cn=users,dc=computer_domain,dc=company,dc=com
where username is the name of the user, and computer_domain is the domain to
which the user's computer belongs.
❐ A login script that runs on the client computer updates a DNS server so that a reverse
DNS lookup for 10.25.36.47 results in
susie.smith.authteam.location.company.com.
Results:
Under these circumstances, the following username and full username attributes might be
used:
❐ Username: $(netbios.messenger-username)@$(client.address).
This results in SUSIE.SMITH@10.25.36.47.
❐ Full username: cn=$(netbios.messenger-username),cn=users,
dc=$(netbios.computer-domain),dc=company,dc=com.
Example
The following is an example of how to determine the user's identity by search.
Assumptions:
❐ The user susie.smith is logged in to a Windows client computer.
❐ The customer has an LDAP directory in which group information is stored. The
FQDN for Susie Smith is "cn=Susie Smith, cn=Users, dc=Eng, dc=company, dc=com".
133
Volume 4: Securing the Blue Coat SG Appliance
Results:
Under these circumstances the login username can not be explicitly mapped to the user's
FQDN, so a search of the LDAP server for the user's login identity is required instead. The
following values can be used:
❐ Search filter: (sAMAccountName=$(netbios.messenger-
username:escape_ldap_filter))
❐ User attribute: default of FQDN
This results in a simple username of "Susie Smith" and a full username of
"cn=Susie Smith, cn=Users, dc=Eng, dc=company, dc=com".
134
Chapter 11: Policy Substitution Realm
2. From the Realm name drop-down list, select the Policy Substitution realm for which
you want to change realm properties.
Note: You must have defined at least one Policy Substitution realm (using the Policy
Substitution Realms tab) before attempting to set Policy Substitution realm properties.
If the message Realms must be added in the Policy Substitutions Realms
tab before editing this tab is displayed in red at the bottom of this page, you do
not currently have any Policy Substitution realms defined.
135
Volume 4: Securing the Blue Coat SG Appliance
2. From the Realm Name drop-down list, select the Policy Substitution realm for which
you want to change realm properties.
136
Chapter 11: Policy Substitution Realm
Note: You must have defined at least one Policy Substitution realm (using the Policy
Substitution Realms tab) before attempting to set Policy Substitution realm properties.
If the message Realms must be added in the Policy Substitutions Realms
tab before editing this tab is displayed in red at the bottom of this page, you do
not currently have any Policy Substitution realms defined.
3. Click New to add a username to be ignored during the username search. The
username format depends on what the LDAP search is looking for but will most often
be an LDAP FQDN.
4. Click OK; repeat the previous step to add other users.
5. Click Apply to commit the changes to the SG appliance.
Configuring Authorization
Policy Substitution realms do not require an authorization realm. If the policy does not
make any decisions based on groups, you need not specify an authorization realm.
2. From the Realm Name drop-down list, select the Policy Substitution realm for which
you want to change realm properties.
Note: You must have defined at least one Policy Substitution realm (using the Policy
Substitution Realms tab) before attempting to set Policy Substitution realm properties.
If the message Realms must be added in the Policy Substitutions Realms
tab before editing this tab is displayed in red at the bottom of this page, you do
not currently have any Policy Substitution realms defined.
3. From the Authorization Realm Name drop-down list, select the authorization realm you
want to use to authorize users.
4. Click Apply to commit the changes to the SG appliance.
137
Volume 4: Securing the Blue Coat SG Appliance
2. From the Realm name drop-down list, select the Policy Substitution realm for which to
change properties.
Note: You must have defined at least one Policy Substitution realm (using the Policy
Substitution Realms tab) before attempting to set Policy Substitution general
properties. If the message Realms must be added in the Policy Substitution
Realms tab before editing this tab is displayed in red at the bottom of this
page, you do not currently have any Policy Substitution realms defined.
3. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
4. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will reevaluate the user’s credentials.
138
Chapter 11: Policy Substitution Realm
5. Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.
6. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
7. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
8. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
9. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
10. Click Apply to commit the changes to the SG appliance.
Notes
❐ Following are examples of how to configure four different types of Policy Substitution
realms. For a list of available substitutions, see Volume 8: Access Logging.
• Identity to be determined by sending a NetBIOS over TCP/IP query to the client
computer, and using LDAP authorization
SGOS#(config) security policy-substitution create-realm netbios
SGOS#(config) security policy-substitution edit-realm netbios
SGOS#(config policy-substitution netbios) username \
$(netbios.messenger-username)
SGOS#(config policy-substitution netbios) full-username \
cn=$(netbios.messenger-username),cn=users,dc=company,dc=com
SGOS#(config policy-substitution netbios) authorization-realm-name
ldap
• Identity to be determined by reverse DNS, using local authorization. Blue Coat
assumes login scripts on the client computer update the DNS record for the client.
139
Volume 4: Securing the Blue Coat SG Appliance
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for
details about CPL and how transactions trigger the evaluation of policy file <Proxy>
and other layers.
Be aware that the default policy condition for this example is allow. On new SGOS 5.x
systems, the default policy condition is deny.
❐ Every Policy Substitution realm authenticated user is allowed to access the SG
appliance.
<Proxy>
authenticate(PolicySubstitutionRealm)
140
Chapter 11: Policy Substitution Realm
Note: The source IP address is not masked if you use the reflect client ip attribute.
Note: The user.login.address condition only works correctly if you use the
authenticate.credentials.address property to set the address.
You can also use the x-cs-user-login-address substitution to log this event.
Examples
In the following example, the address to use for authenticating with myrealm is set to the
address received from the HTTP Client-IP header.
<proxy>
authenticate(myrealm)\
authenticate.credentials.address($(request.header.Client-IP))
In the following example, the user is authenticated if logged in from the 1.2.3.0/24 subnet.
<proxy>
user.login.address=1.2.3.0/24 allow
141
Volume 4: Securing the Blue Coat SG Appliance
142
Chapter 12: CA eTrust SiteMinder Authentication
Since BCAAA is a Web agent in the SiteMinder system, it must be configured on the
SiteMinder policy server. Configuration of BCAAA on the host computer is not
required; the agent obtains its configuration information from the SG appliance.
A suitable Web agent must be created and configured on the SiteMinder server. This
must be configured to support 5.x agents, and a shared secret must be chosen and
entered on the server (it must also be entered in the SG SiteMinder realm
configuration).
143
Volume 4: Securing the Blue Coat SG Appliance
Important: The request URL is not sent to the SiteMinder policy server as the
requested resource; the requested resource is the entire SG realm. Access control of
individual URLs is done on the SG appliance using CPL or VPM.
The SiteMinder realm that controls the protected resource must be configured with a
compatible authentication scheme. The supported schemes are Basic (in plain text and
over SSL), Forms (in plain text and over SSL), and X.509 certificates. Configure the
SiteMinder realm with one of these authentication schemes.
Note: Only the following X.509 Certificates are supported: X.509 Client Cert Template,
X.509 Client Cert and Basic Template, and X.509 Client Cert and Form Template.
❐ If using single-sign on (SSO) with off-box redirection (such as to a forms login page),
the forms page must be processed by a 5.x or later Web Agent, and that agent must be
configured with fcccompatmode=no. This precludes that agent from doing SSO with
5.x agents.
❐ For SSO to work with other Web agents, the other agents must have the
AcceptTPCookie=YES as part of their configuration. This is described in the
SiteMinder documentation.
❐ Blue Coat does not extract the issuerDN from X.509 certificates in the same way as the
SiteMinder agent. Thus, a separate certificate mapping might be needed for the SGOS
agent and the SiteMinder agents.
144
Chapter 12: CA eTrust SiteMinder Authentication
For example, the following was added to the SiteMinder policy server certificate
mappings:
CN=Waterloo Authentication and Security Team,OU=Waterloo R&D, O=Blue
Coat\, Inc.,L=Waterloo,ST=ON,C=CA
❐ In order to use off-box redirection (such as an SSO realm), all agents involved must
have the setting EncryptAgentName=no in their configurations.
❐ The SG appliance's credential cache only caches the user's authentication information
for the smaller of the time-to-live (TTL) configured on the SG appliance and the
session TTL configured on the SiteMinder policy server.
Note: All SG appliance and agent configuration is done on the appliance. The appliance
sends the necessary information to BCAAA when it establishes communication.
145
Volume 4: Securing the Blue Coat SG Appliance
3. In the Realm name field, enter a realm name. The name can be 32 characters long and
composed of alphanumeric characters and underscores. The name must start with a
letter. The name should be meaningful to you, but it does not have to be the name of
the SiteMinder policy server.
4. Click OK.
5. Click Apply to commit the changes to the SG appliance.
Configuring Agents
You must configure the SiteMinder realm so that it can find the Blue Coat Authentication
and Authorization Agent (BCAAA).
1. Select Configuration > Authentication > CA eTrust SiteMinder > Agents.
146
Chapter 12: CA eTrust SiteMinder Authentication
147
Volume 4: Securing the Blue Coat SG Appliance
4. Enter the name of the server in the dialog. This name is used only to identify the
server in the SG appliance’s configuration; it usually is the real hostname of the
SiteMinder policy server.
5. Click OK.
6. To edit an existing SiteMinder policy server, click Edit.
a. Enter the IP address of the SiteMinder policy server in the IP address field.
b. Enter the correct port number for the Authentication, Authorization, and
Accounting ports. The ports should be the same as the ports configured on
their SiteMinder policy server. The valid port range is 1-65535.
c. The maximum number of connections is 32768; the default is 256.
d. The connection increment specifies how many connections to open at a time if
more are needed and the maximum is not exceeded. The default is 1.
e. The timeout value has a default of 60 seconds, which can be changed.
7. Click OK.
8. Click Apply to commit the changes to the SG appliance.
148
Chapter 12: CA eTrust SiteMinder Authentication
2. From the Realm name drop-down list, select the SiteMinder realm for which you want
to change properties.
3. Enter the protected resource name. The protected resource name is the same as the
resource name on the SiteMinder policy server that has rules and policy defined for it.
4. In the Server mode drop-down list, select either failover or round-robin. Failover mode
falls back to one of the other servers if the primary one is down. Round-robin modes
specifies that all of the servers should be used together in a round-robin approach.
Failover is the default.
Note: The server mode describes the way the agent (BCAAA) interacts with the
SiteMinder policy server, not the way that SG appliance interacts with BCAAA.
Note: All SiteMinder Web agents involved must have the setting
EncryptAgentName=no in their configurations to go off-box for any reason.
If using SiteMinder forms for authentication, the SG appliance always redirects the
browser to the forms URL for authentication. You can force this behavior for other
SiteMinder schemes by configuring the always redirect off-box property on the realm.
6. If your Web applications need information from the SiteMinder policy server
responses, you can select Add Header Responses. Responses from the policy server
obtained during authentication are added to each request forwarded by the SG
appliance. Header responses replace any existing header of the same name; if no such
header exists, the header is added. Cookie responses replace a cookie header with the
same cookie name; if no such cookie header exists, one is added.
7. To enable validation of the client IP address, select Validate client IP address. If the
client IP address in the SSO cookie can be valid yet different from the current request
client IP address, due to downstream proxies or other devices, deselect Validate client
IP address for the realm. SiteMinder agents participating in SSO with the SG
appliance should also be modified; set the TransientIPCheck variable to yes to enable
IP address validation and no to disable it.
8. Click Apply to commit the changes to the SG appliance.
149
Volume 4: Securing the Blue Coat SG Appliance
2. From the Realm name drop-down list, select the SiteMinder realm for which you want
to change properties.
3. If needed, change the SiteMinder realm display name. The default value for the
display name is the realm name. The display name cannot be greater than 128
characters and it cannot be null.
4. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
5. Enter the number of seconds in the Credential refresh time field. The Credential
Refresh Time is the amount of time Basic credentials (username and password) are
kept on the SG appliance. This feature allows the SG appliance to reduce the load on
the authentication server and enables credential spoofing. It has a default setting of
900 seconds (15 minutes). You can configure this in policy for better control over the
resources as policy overrides any settings made here.
Before the refresh time expires, the SG appliance will authenticate the user supplied
credentials against the cached credentials. If the credentials received do not match the
cached credentials, they are forwarded to the authentication server in case the user
password changed. After the refresh time expires, the credentials are forwarded to the
authentication server for verification.
6. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
150
Chapter 12: CA eTrust SiteMinder Authentication
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
8. If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.
9. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
10. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
11. Specify the virtual URL to redirect the user to when they need to be challenged by the
SG appliance. If the appliance is participating in SSO, the virtual hostname must be in
the same cookie domain as the other servers participating in the SSO. It cannot be an
IP address or the default, www.cfauth.com.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Click Apply to commit the changes to the SG appliance.
151
Volume 4: Securing the Blue Coat SG Appliance
152
Chapter 12: CA eTrust SiteMinder Authentication
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details
about CPL and how transactions trigger the evaluation of policy file <Proxy> and other
layers.
153
Volume 4: Securing the Blue Coat SG Appliance
154
Chapter 13: RADIUS Realm Authentication and Authorization
RADIUS is often the protocol of choice for ISPs or enterprises with very large numbers
of users. RADIUS is designed to handle these large numbers through centralized user
administration that eases the repetitive tasks of adding and deleting users and their
authentication information. RADIUS also inherently provides some protection against
sniffing.
Some RADIUS servers support one-time passwords. One-time passwords are
passwords that become invalid as soon as they are used. The passwords are often
generated by a token or program, although pre-printed lists are also used. Using one-
time passwords ensures that the password cannot be used in a replay attack.
The SG appliance’s one-time password support works with products such as Secure
Computing SafeWord synchronous and asynchronous tokens and RSA SecurID tokens.
The SG appliance supports RADIUS servers that use challenge/response as part of the
authentication process. SafeWord asynchronous tokens use challenge/response to
provide authentication. SecurID tokens use challenge/response to initialize or change
PINs.
The challenge is displayed as the realm information in the authentication dialog; Blue
Coat recommends that you use form authentication if you create a challenge/response
realm, particularly if you use SecurID tokens.
If you set an authentication mode that uses forms, the system detects what type of
question is being asked. If it is a yes/no question, it displays the query form with a yes
and no button. If it is a new PIN question, the system displays a form with entry fields
for the new PIN.
For information on using form authentication, see Chapter 7: "Forms-Based
Authentication" on page 89.
Using policy, you can fine-tune RADIUS realms based on RADIUS attributes. If you use
the Blue Coat attribute, groups are supported within a RADIUS realm.
This section discusses the following topics:
❐ “Creating a RADIUS Realm”
❐ “Defining RADIUS Realm Properties” on page 156
❐ “Defining RADIUS Realm General Properties” on page 158
❐ “Creating the Policy” on page 160
❐ “Troubleshooting” on page 162
155
Volume 4: Securing the Blue Coat SG Appliance
156
Chapter 13: RADIUS Realm Authentication and Authorization
2. Specify the host and port for the primary RADIUS server.
The default port is 1812. (To create or change the RADIUS secret, click Change Secret.
RADIUS secrets can be up to 64 characters long and are always case sensitive.)
3. (Optional) Specify the host and port for the alternate RADIUS server.
4. In the Send credentials to server encoded with character set drop-down list, select the
character set used for encoding credentials; the RADIUS server needs the same
character set.
A character set is a Multipurpose Internet Mail Extension (MIME) charset name. Any
of the standard charset names for encodings commonly supported by Web browsers
can be used. The default is Unicode:UTF8.
One list of standard charset names is found here.
5. In the Timeout Request field, enter the number of seconds the SG appliance allows for
each request attempt before trying another server.
Within a timeout, multiple packets can be sent to the server, in case the network is
busy and packets are lost. The default request timeout is 10 seconds.
6. In the Retry field, enter the number of attempts you want to permit before marking a
server offline.
The client maintains an average response time from the server; the retry interval is
initially twice the average. If that retry packet fails, then the next packet waits twice as
long again. This increases until it reaches the timeout value. The default number of
retries is 10.
7. If you are using one-time passwords, select the One-time passwords checkbox.
You must enable one-time passwords if you created a challenge/response realm.
8. If the RADIUS server is configured to expect case-sensitive usernames and
passwords, make sure the Case sensitive checkbox is selected.
9. Click Apply to commit the changes to the SG appliance.
157
Volume 4: Securing the Blue Coat SG Appliance
2. From the Realm name drop-down list, select the RADIUS realm for which you want to
change properties.
3. If needed, change the RADIUS realm display name.
The default value for the display name is the realm name. The display name cannot be
greater than 128 characters and it cannot be empty.
4. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
5. Enter the number of seconds in the Credential refresh time field.
The Credential Refresh Time is the amount of time basic credentials (username and
password) are kept on the SG appliance. This feature allows the SG appliance to
reduce the load on the authentication server and enables credential spoofing. It has a
default setting of 900 seconds (15 minutes). You can configure this in policy for better
control over the resources as policy overrides any settings made here.
Before the refresh time expires, the SG appliance will authenticate the user supplied
credentials against the cached credentials. If the credentials received do not match the
cached credentials, they are forwarded to the authentication server in case the user
password changed. After the refresh time expires, the credentials are forwarded to the
authentication server for verification.
6. Enter the number of seconds in the Surrogate refresh time field.
158
Chapter 13: RADIUS Realm Authentication and Authorization
The Surrogate Refresh Time allows you to set a realm default for how often a user’s
surrogate credentials are refreshed. Surrogate credentials are credentials accepted in
place of a user’s actual credentials. The default setting is 900 seconds (15 minutes).
You can configure this in policy for better control over the resources as policy
overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
8. If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field.
This setting, enabled by default and set to one second, allows failed authentication
attempts to be automatically rejected for up to 10 seconds. Any Basic credentials that
match a failed result before its cache time expires are rejected without consulting the
back-end authentication service. The original failed authentication result is returned
for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.
9. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
10. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
11. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Click Apply to commit the changes to the SG appliance.
159
Volume 4: Securing the Blue Coat SG Appliance
Note: RADIUS groups can only be configured through policy. This feature is not
available through either the Management Console or the CLI.
Table 13-1. RADIUS Attributes for the attribute.<name> and has_attribute.<name> Conditions
160
Chapter 13: RADIUS Realm Authentication and Authorization
Table 13-1. RADIUS Attributes for the attribute.<name> and has_attribute.<name> Conditions (Continued)
161
Volume 4: Securing the Blue Coat SG Appliance
CPL Example
Be aware that the examples below are just part of a comprehensive authentication policy.
By themselves, they are not adequate.
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details
about CPL and how transactions trigger the evaluation of policy file layers.
Troubleshooting
One of five conditions can cause the following error message:
Your request could not be processed because of a configuration error: "The request
timed out while trying to authenticate. The authentication server may be busy or offline."
❐ The secret is wrong.
❐ The network is so busy that all packets were lost to the RADIUS server.
❐ The RADIUS server was slow enough that the SG appliance gave up before the server
responded.
❐ The RADIUS servers are up, but the RADIUS server is not running. In this case, you
might also receive ICMP messages that there is no listener.
❐ RADIUS servers machines are not running/unreachable. Depending on the network
configuration, you might also receive ICMP messages.
Notes
❐ If you use guest authentication, remember that RADIUS realms retrieve authorization
data at the same time as the user is authenticated. In some cases, the system can
distinguish between an authentication and authorization failure. Where the system
cannot determine if the error was due to authentication or authorization, both the
authentication and authorization are considered to be failed.
162
Chapter 14: Novell Single Sign-on Authentication and
Authorization
The Novell® Single Sign-on (SSO) realm is an authentication mechanism that provides
single sign-on authentication for users that authenticate against a Novell eDirectory
server. The mechanism uses the Novell eDirectory Network Address attribute to map
the user's IP address to an LDAP FQDN. Since the mechanism is based on the user's IP
address, it only works in environments where an IP address can be mapped to a unique
user.
A Novell SSO realm consists of the following:
❐ BCAAA service information
❐ Novell eDirectory information
❐ Authorization realm information
❐ General realm information.
The Novell eDirectory information consists of a SG appliance LDAP realm that points
to the master Novell eDirectory server that it is to be searched and monitored for user
logins (see "Chapter 9: "LDAP Realm Authentication and Authorization" on page 109
for information on configuring LDAP realms) and a list of eDirectory server and port
combinations that specify additional servers to monitor for logins. Additional monitor
servers must be specified if they contain user information that is not replicated to the
master Novell eDirectory server being searched.
After a Novell SSO realm has been configured, you can write policy that authenticates
and authorizes users against the Novell SSO realm.
To ensure that users who do not successfully authenticate against the Novell SSO realm
are not challenged, administrators can use a realm sequence that contains the Novell
SSO realm and then a policy substitution realm to use when Novell SSO authentication
fails.
Note: The Novell SSO realm works reliably only in environments where one IP
address maps to one user. If an IP address cannot be mapped to a single user,
authentication fails. Those with NAT systems, which uses one set of IP addresses
for intranet traffic and a different set for Internet traffic, may need to use a different
realm for authentication.
163
Volume 4: Securing the Blue Coat SG Appliance
❐ “Modifying the sso.ini File for Novell SSO Realms” on page 171
❐ “Creating the CPL” on page 172
❐ “Notes” on page 173
Note: For information on configuring the BCAAA service, see Appendix B: "Using
the Authentication/Authorization Agent" on page 215.
164
Chapter 14: Novell Single Sign-on Authentication and Authorization
3. In the Realm name field, enter a realm name. The name can be 32 characters long and
composed of alphanumeric characters and underscores. The name must start with a
letter.
4. Click OK.
5. Click Apply to commit the changes to the SG appliance.
165
Volume 4: Securing the Blue Coat SG Appliance
Note: You must have defined at least one Novell SSO realm (using the Novell SSO
Realms tab) before attempting to configure the BCAAA agent. If the message Realms
must be added in the Novell SSO Realms tab before editing this tab is displayed in red at
the bottom of this page, you do not currently have any Novell SSO realms defined.
3. In the Primary agent section, enter the hostname or IP address where the BCAAA
agent resides.
4. Change the port from the default of 16101 if necessary.
5. (Optional) You can change the encrypted passwords for the private key and public
certificate on the BCAAA machine that are to be used for SSL communication
between the BCAAA service and the Novell eDirectory server by clicking Change
Private Key Password or Change Public Certificate Password. The location of the
private key and public certificate are specified in the sso.ini file on the BCAAA
machine. (For information on changing the location of the private key and public
certificate, see “Modifying the sso.ini File for Novell SSO Realms” on page 171.)
6. (Optional) Enter an alternate agent host and agent name in the Alternate agent section.
Note that you can also change the passwords for the private key and public certificate
for the alternate agent, as well.
The primary and alternate BCAAA server must work together to support fail-over. If
the primary BCAAA server fails, the alternate server should be able to search and
monitor the same set of eDirectory servers.
7. (Optional) Click Enable SSL to enable SSL between the SG appliance and the
BCAAA.
8. (Optional) By default, if SSL is enabled, the BCAAA service’s certificate is verified. To
not verify the agent certificate, disable this setting.
Note: The Enable SSL setting only enables SSL between the SG appliance and
BCAAA. To enable SSL between BCAAA and the eDirectory server, the Enable SSL
setting must be set in the LDAP search realm.
9. In the Timeout Request field, type the number of seconds the SG appliance allows for
each request attempt before timing out. (The default request timeout is 60 seconds.)
10. Click Apply to commit the changes to the SG appliance.
166
Chapter 14: Novell Single Sign-on Authentication and Authorization
Note: You must have defined at least one Novell SSO realm (using the Novell SSO
Realms tab) before attempting to specify LDAP server configuration. If the message
Realms must be added in the Novell SSO Realms tab before editing this tab is displayed
in red at the bottom of this page, you do not currently have any Novell SSO realms
defined.
3. Select an LDAP realm from the drop-down list. The servers configured in this LDAP
realm are used to do the full searches of the eDirectory tree.
4. If you have a deployment with multiple servers holding partitions that are not fully
replicated to the master server, you can monitor each LDAP server individually. To
add an LDAP server to monitor, click New.
5. Add the IP address and port of the LDAP server and click OK.
6. Repeat for additional LDAP servers you need to monitor.
7. Click Apply to commit the changes to the SG appliance.
167
Volume 4: Securing the Blue Coat SG Appliance
Related CLI Syntax to specify the LDAP search realm and LDAP servers to monitor:
SGOS#(config) security novell-sso edit-realm realm_name
SGOS#(config novell-sso realm_name) ldap search-realm ldap_realm
SGOS#(config novell-sso realm_name) ldap monitor-servers {add host
[port] | clear | remove host [port]}
Note: You must have defined at least one Novell SSO realm (using the Novell SSO
Realms tab) before attempting to configure LDAP queries. If the message Realms must
be added in the Novell SSO Realms tab before editing this tab is displayed in red at the
bottom of this page, you do not currently have any Novell SSO realms defined.
3. In the full search pane, specify the time of day you want the search to take place from
the drop-down list.
4. Select or de-select checkboxes to specify days to search.
5. If you have changed the Novell eDirectory Network Address or Login Time LDAP
attribute name, you can enter those changed names in the Network Address LDAP
name and the Login Time LDAP name fields. The names must match the LDAP names
configured on the eDirectory server for authentication to succeed.
6. Click Apply to commit the changes to the SG appliance.
168
Chapter 14: Novell Single Sign-on Authentication and Authorization
Configuring Authorization
Novell SSO realm can be configured to do no authorization, authorize against itself (the
default), or authorize against another valid authorization realm (either LDAP or Local).
Note: You must have defined at least one Novell SSO realm (using the Novell SSO
Realms tab) before attempting to configure authorization. If the message Realms must
be added in the Novell SSO Realms tab before editing this tab is displayed in red at the
bottom of this page, you do not currently have any Novell SSO realms defined.
3. The Novell SSO realm is selected to authorize against itself by default. To choose
another realm, de-select the Self checkbox and choose an authorization realm from the
drop-down list.
4. The LDAP FQDN is selected as the Authorization user name, by default. You might
want to change this if the user's authorization information resides in a different root
DN. To choose a different authorization name, de-select the Use FQDN checkbox and
enter a different name, for example:
cn=$(user.name),ou=partition,o=company
5. Click Apply to commit the changes to the SG appliance.
169
Volume 4: Securing the Blue Coat SG Appliance
Note: Novell SSO realms default to the origin-ip authentication mode when no
authentication mode or the auto authentication mode is specified in policy. After a user
has first successfully authenticated to the SG appliance, all subsequent requests from that
same IP address for the length of the surrogate refresh time are authenticated as that user.
If the first user is allowed or denied access, subsequent users during that same time
coming from the same IP address are allowed or denied as that first user. This is true even
if policy would have treated them differently if they were authenticated as themselves.
If multiple users often log in from the same IP address, it is recommended to use a shorter
surrogate refresh timeout than the default or an authentication mode that does not use IP
surrogates.
2. From the Realm name drop-down list, select the Novell SSO realm for which you want
to change properties.
Note: You must have defined at least one Novell SSO realm (using the Novell SSO
Realms tab) before attempting to set Novell SSO general properties. If the message
Realms must be added in the Novell SSO Realms tab before editing this tab is displayed
in red at the bottom of this page, you do not currently have any Novell SSO realms
defined.
3. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
4. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
170
Chapter 14: Novell Single Sign-on Authentication and Authorization
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will determine which user is using the
current IP address, and update the surrogate to authenticate with that user.
5. Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.
6. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
7. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
8. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
9. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
10. Click Apply to commit the changes to the SG appliance.
Note: The changes to the sso.ini file have no effect until the BCAAA service is
restarted.
171
Volume 4: Securing the Blue Coat SG Appliance
• SearchRetryTime=30
• TrustedRootCertificateEncoding=der
• PublicCertificateEncoding=der
• PrivateKeyFile=
• PrivateKeyEncoding=der
3. If the LDAP realm used by the Novell SSO realm requires that the identity of the
server be verified, add the paths to the Trusted root certificate files in the
NovellTrustedRootCertificates section.
4. In the section SSOServiceUsers, list the names of users who can log in with eDirectory
credentials on behalf of the service and mask the identity of the logged-on user.
Listing these users here forces the BCAAA service to ignore them for authentication
purposes.
5. Save the sso.ini file.
Note: The examples below assume the default policy condition is allow.
Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details about
CPL and how transactions trigger the evaluation of policy file layers.
❐ Every Novell SSO-authenticated user is allowed access the SG appliance.
<Proxy>
authenticate(NSSORealm)
❐ Group membership is the determining factor in granting access to the SG appliance.
<Proxy>
authenticate(NSSORealm)
<Proxy>
group=”cn=proxyusers, ou=groups, o=myco” ALLOW
deny
Note: The source IP address is not masked if you use the reflect client ip attribute.
172
Chapter 14: Novell Single Sign-on Authentication and Authorization
Note: The user.login.address condition only works correctly if you use the
authenticate.credentials.address property to set the address.
You can also use the x-cs-user-login-address substitution to log this event.
Examples
In the following example, the address to use for authenticating with myrealm is set to the
address received from the HTTP Client-IP header.
<proxy>
authenticate(myrealm)\
authenticate.credentials.address($(request.header.Client-IP))
In the following example, the user is authenticated if logged in from the 1.2.3.0/24 subnet.
<proxy>
user.login.address=1.2.3.0/24 allow
Notes
❐ The Novell SSO realm works reliably only in environments where one IP address
maps to one user. NAT environments are not supported.
❐ Novell SSO realms are not supported in IPX environments.
❐ Event monitoring of eDirectory is only compatible with eDirectory 8.7+.
❐ Upgrade to Novell client 4.91 SP1 or later if you experience issues with the Network
Address attribute not being updated during login.
❐ Novell SSO realms do not use user credentials so they cannot spoof authentication
information to an upstream server.
❐ If an upstream proxy is doing Novell SSO authentication, all downstream proxies must
send the client IP address.
❐ There can be response time issues between the BCAAA service and the eDirectory
servers during searches; configure the timeout for LDAP searches to allow the
eDirectory server adequate time to reply.
173
Volume 4: Securing the Blue Coat SG Appliance
174
Chapter 15: Sequence Realm Authentication
Once a realm is configured, you can associate it with other realms to allow Blue Coat to
search for the proper authentication credentials for a specific user. That is, if the
credentials are not acceptable to the first realm, they are sent to the second, and so on
until a match is found or all the realms are exhausted. This is called sequencing.
For example, if a company has one set of end-users authenticating against an LDAP
server and another using NTLM, a sequence realm can specify to attempt NTLM
authentication first; if that fails due to a user-correctable error (such as credentials
mismatch or a user not in database) then LDAP authentication can be specified to try
next. You can also use sequences to fall through to a policy substitution realm if the
user did not successfully authenticate against one of the earlier realms in the sequence.
Note: Errors such as server down do not fall through to the next realm in the
sequence. Those errors result in an exception returned to the user. Only errors that
are end-user correctable result in the next realm in the sequence being attempted.
175
Volume 4: Securing the Blue Coat SG Appliance
3. In the Realm name, enter a realm name. The name can be 32 characters long and
composed of alphanumeric characters and underscores. The name must start with a
letter.
4. Click OK.
176
Chapter 15: Sequence Realm Authentication
2. Click New to add an existing realm to the realm sequence from the drop-down list.
Remember that each realm can be used only once in a realm sequence.
3. From the drop-down list, select the Sequence realm you wanted added to the realm
sequence.
4. Click OK.
You are returned to the main Sequences menu.
5. Click Apply to commit the changes to the SG appliance.
6. Repeat from Step 2 until you have added all necessary realms.
7. To change the order that the realms are checked, use the promote/demote buttons.
When you add an IWA realm, it is placed first in the list and you can allow the realm
sequence to try IWA authentication only once. If you demote the IWA entry, it becomes
last in the sequence and the default of checking IWA multiple times is enabled.
177
Volume 4: Securing the Blue Coat SG Appliance
8. If you permit authentication or authorization errors, you can select the Try next realm
on tolerated error checkbox to specify that the next realm on the list should be
attempted if authentication in the previous realm has failed with a permitted error.
The default value is to not attempt the next realm and fall out of the sequence. (For
information on using permitted errors and guest authentication, see “Permitting
Users to Login with Authentication or Authorization Failures” on page 37.)
2. From the Realm name drop-down list, select the Sequence realm for which you want
to change properties.
3. If needed, change the Sequence realm display name. The default value for the display
name is the realm name. The display name cannot be longer than 128 characters and it
cannot be null.
4. You can specify a virtual URL based on the individual realm sequence. For more
information on the virtual URL, see Chapter 3: "Controlling Access to the Internet
and Intranet" on page 25.
5. Click Apply to commit the changes to the SG appliance.
178
Chapter 15: Sequence Realm Authentication
Tips
❐ Explicit Proxy involving a sequence realm configured with an NTLM/IWA realm and
a substitution realm.
Internet Explorer (IE) automatically sends Windows credentials in the Proxy-
Authorization: header when the SG appliance issues a challenge for NTLM/IWA. The
prompt for username/password appears only if NTLM authentication fails. However,
in the case of a sequence realm configured with an NTLM/IWA realm and a
substitution realm, the client is authenticated as a guest in the policy substitution
realm, and the prompt allowing the user to correct the NTLM credentials never
appears.
❐ Transparent Proxy setup involving a sequence realm configured with an NTLM/IWA
realm and a substitution realm.
The only way the SG appliance can differentiate between a domain and non-domain
user is though the NTLM/IWA credentials provided during the authentication
challenge.
IE does not offer Windows credentials in the Proxy-Authorization: header when the
Proxy issues a challenge for NTLM/IWA unless the browser is configured to do so. In
this case, the behavior is the same as for explicit proxy.
If IE is not configured to offer Windows credentials, the browser issues a prompt for
username/password, allowing non-domain users to be authenticated as guests in the
policy substitution realm by entering worthless credentials.
179
Volume 4: Securing the Blue Coat SG Appliance
180
Chapter 16: Windows Single Sign-on Authentication
Note: The Windows SSO realm works reliably only in environments where one
IP address maps to one user. If an IP address cannot be mapped to a single user,
authentication fails. Those with NAT systems, which uses one set of IP addresses
for intranet traffic and a different set for Internet traffic, should use a different
realm for authentication.
To authenticate a user, the Windows SSO realm uses two methods, either separately or
together:
❐ Domain Controller Querying: The domain controller is queried to identify which
users are connecting to, or authenticating with, the domain controller. This can be
used to infer the identity of the user at a particular workstation.
❐ Client Querying: The client workstation is queried to determine who the client
workstation thinks is logged in.
❐ When Domain Controller Querying and Client Querying are both used, the
Domain Controller Query result is used if it exists and is still within the valid time-
to-live as configured in the sso.ini file. If the Domain Controller Query result is
older than the configured time-to-live, the client workstation is queried.
Note: Before Domain Controller Querying or Client Querying can be used, the
sso.ini file, located in the same directory as the BCAAA service, must be
modified. For information on modifying this file, see “Modifying the sso.ini File for
Windows SSO Realms” on page 188.
181
Volume 4: Securing the Blue Coat SG Appliance
For the most complete solution, an IWA realm could be configured at the same time as the
Windows SSO realm and both realms added to a realm sequence. Then, if the Windows
SSO realm failed to authenticate the user, the IWA realm could be used. For information
on using a sequence realm, see Chapter 15: "Sequence Realm Authentication" on
page 175.
BCAAA Synchronization
Optionally, when using Domain Controller Querying, you can configure a BCAAA service
to use another BCAAA service as a synchronization server. Whenever a BCAAA service
restarts it will contact its synchronization server and update its logon state. Two given
BCAAA services can use each other as their synchronization server. Thus, each BCAAA
service can act as a synchronization server to provide logon state to other BCAAA
services, as well as acting as a synchronization client to update its logon state from
another BCAAA service.
Each BCAAA service has a synchronization priority that determines synchronization
behavior. If the client BCAAA has the same or higher priority than the server BCAAA,
synchronization is done once at restart to update the client state. Once synchronization is
complete the client BCAAA drops the synchronization connection and begins querying
the domain controllers.
However, if the server BCAAA has higher priority, then the client BCAAA keeps the
synchronization link open and continuously updates its logon state from the higher
priority BCAAA. The client BCAAA does not query the domain controllers itself unless
the synchronization link fails.
This makes it possible to manage the query load on the domain controllers. If there is no
issue with load, then the default configuration (without synchronization), with all
BCAAA agents querying the domain controllers is acceptable. However, if load on the
domain controllers is an issue, synchronization can be used to minimize this load while
still providing fail-over capabilities.
By default, all BCAAA agents have the same synchronization priority, meaning that they
synchronize on startup and then do their own domain controller querying. To change the
synchronization settings, see “To configure the sso.ini file for synchronization:” on page
189.
182
Chapter 16: Windows Single Sign-on Authentication
Note: Windows SSO realms never challenge for credentials. If the authorization
username cannot be determined from the configured substitutions, authorization in
the Windows SSO realm fails.
Keep in mind that Windows SSO realms do not require an authorization realm. If no
authorization realm is configured, the user is not considered a member of any group. The
effect this has on the user depends on the authorization policy. If the policy does not make
any decisions based on groups, you do not need to specify an authorization realm. Also, if
your policy is such that it works as desired when all Windows SSO realm users are not in
any group, you do not have to specify an authorization realm.
3. In the Realm name field, enter a realm name. The name can be 32 characters long and
composed of alphanumeric characters and underscores. The name must start with a
letter.
4. Click OK.
5. Click Apply to commit the changes to the SG appliance.
183
Volume 4: Securing the Blue Coat SG Appliance
Note: You must have defined at least one Windows SSO realm (using the Windows
SSO Realms tab) before attempting to configure the BCAAA agent. If the message
Realms must be added in the Windows SSO Realms tab before editing this tab is
displayed in red at the bottom of this page, you do not have any Windows SSO realms
defined.
3. In the Primary agent section, enter the hostname or IP address where the BCAAA
agent resides.
4. Change the port from the default of 16101 if necessary.
5. (Optional) Enter an alternate agent host and agent name in the Alternate agent section.
The primary and alternate BCAAA server must work together to support fail-over. If
the primary BCAAA server fails, the alternate server should be able to provide the
same mappings for the IP addresses.
6. (Optional) Click Enable SSL to enable SSL between the SG appliance and the BCAAA.
7. (Optional) By default, if SSL is enabled, the Windows SSO BCAAA certificate is
verified. To not verify the agent certificate, disable this setting.
8. In the Timeout Request field, type the number of seconds the SG appliance allows for
each request attempt before timing out. (The default request timeout is 60 seconds.)
9. In the Query Type field, select the method you want to use from the drop-down menu.
By default the Windows SSO realm is configured for Domain Controller Querying only.
Note: If all of the client computers can be queried directly, then the most accurate
results can be provided by the Query Clients option.
184
Chapter 16: Windows Single Sign-on Authentication
Client Querying is blocked by the Windows XP SP2 firewall. This can be overridden
through domain policy. If the firewall setting "Allow remote administration
exception" or "Allow file and printer sharing exception" or "Define port exceptions"
(with port 445) is enabled, then the query will work.
If an authentication mode without surrogates is being used (Proxy or Origin
authenticate mode), then the Query Domain Controller and Client and Query Client
options can cause too much traffic when querying the clients, as each authentication
request results in a request to the BCAAA service, which can result in a client
workstation query depending on the client query time-to-live. If the client
workstation querying traffic is a concern, the Query Domain Controllers option should
be used instead.
10. Click Apply to commit the changes to the SG appliance.
Configuring Authorization
After the Windows SSO realm is created, you can use the Windows SSO Authorization tab
to configure authorization for the realm.
Note: Windows SSO realms do not require an authorization realm. If the policy does
not make any decisions based on groups, you do not need to specify an authorization
realm.
2. From the Realm name drop-down list, select the Windows SSO realm for which you
want to change realm properties.
185
Volume 4: Securing the Blue Coat SG Appliance
Note: You must have defined at least one Windows SSO realm (using the Windows
SSO Realms tab) before attempting to set Windows SSO realm properties. If the
message Realms must be added in the Windows SSO Realms tab before editing this tab
is displayed in red at the bottom of this page, you do not currently have any Windows
SSO realms defined.
3. (Optional) From the Authorization realm name drop-down list, select the realm you
want to use to authorize users.
4. To construct usernames, keep in mind that the authorization username attributes is a
string. that contains policy substitutions. When authorization is required for the
transaction, the character string is processed by the policy substitution mechanism,
using the current transaction as input. The resulting string becomes the user's
authorization name for the current transaction.
5. The LDAP FQDN is selected as the Authorization user name, by default. You might
want to change this if the user's authorization information resides in a different root
DN. To choose a different authorization name, de-select the Use FQDN checkbox and
enter a different name, for example:
cn=$(user.name),ou=partition,o=company
6. Click Apply to commit the changes to the SG appliance.
186
Chapter 16: Windows Single Sign-on Authentication
Note: Windows SSO realms default to the origin-ip authentication mode when either no
authentication mode or the auto authentication mode is specified in policy. After a user
has first successfully authenticated to the SG appliance, all subsequent requests from that
same IP address for the length of the surrogate refresh time are authenticated as that user.
If the first user is allowed or denied access, subsequent users during that same time
coming from the same IP address are allowed or denied as that first user. This is true even
if policy would have treated them differently if they were authenticated as themselves.
If multiple users often log in from the same IP address, it is recommended to use a shorter
surrogate refresh timeout than the default or an authentication mode that uses cookie
surrogates.
2. From the Realm name drop-down list, select the Windows SSO realm for which you
want to change properties.
Note: You must have defined at least one Windows SSO realm (using the Windows
SSO Realms tab) before attempting to set Windows SSO general properties. If the
message Realms must be added in the Windows SSO Realms tab before editing this tab
is displayed in red at the bottom of this page, you do not currently have any Windows
SSO realms defined.
3. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
4. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will determine which user is using the
current IP address, and update the surrogate to authenticate with that user.
187
Volume 4: Securing the Blue Coat SG Appliance
5. Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.
6. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
7. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
8. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
9. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
10. Click Apply to commit the changes to the SG appliance.
Note: The changes to the sso.ini file have no effect until the BCAAA service is
restarted.
188
Chapter 16: Windows Single Sign-on Authentication
By default all domain controllers that are in the forest or are trusted are queried. In
large organizations, domain controllers that are not of interest for the SG appliance
installation might be queried. The sso.ini file can be used to list the domain
controllers of interest or IP address ranges of interest.
4. In the section SSOServiceUsers, list the domain names of users who can access the
domain controller on behalf of the service and mask the identity of the logged-on user.
Listing these users here forces the BCAAA service to ignore them for authentication
purposes.
5. Save the sso.ini file.
Note: Before you use the Windows SSO realm, you must change the BCAAA service to
run as a domain user, and, if using XP clients, update the domain policy to allow the client
query to pass through the firewall.
For information on installing and configuring the BCAAA service, see Appendix B:
"Using the Authentication/Authorization Agent" on page 215.
189
Volume 4: Securing the Blue Coat SG Appliance
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for
details about CPL and how transactions trigger the evaluation of policy file layers.
Note: The source IP address is not masked if you use the reflect client ip attribute.
Note: The user.login.address condition only works correctly if you use the
authenticate.credentials.address property to set the address.
You can also use the x-cs-user-login-address substitution to log this event.
Examples
In the following example, the address to use for authenticating with myrealm is set to the
address received from the HTTP Client-IP header.
<proxy>
authenticate(myrealm)\
authenticate.credentials.address($(request.header.Client-IP))
190
Chapter 16: Windows Single Sign-on Authentication
In the following example, the user is authenticated if logged in from the 1.2.3.0/24 subnet.
<proxy>
user.login.address=1.2.3.0/24 allow
Notes
❐ The Windows SSO realm works reliably only in environments where one IP address
maps to one user.
❐ This realm never uses a password.
❐ When doing domain controller querying, the Windows SSO realm can lose the logon
if the NetBIOS computer name cannot by determined through a DNS query or a
NetBIOS query. The DNS query can fail if the NetBIOS name is different than the DNS
host name or if the computer is in a different DNS domain than the BCAAA computer
and the BCAAA computer is not set up to impute different DNS domains.
The NetBIOS query can fail because the NetBIOS broadcast does not reach the target
computer. This can happen if the computer is behind a firewall that is not forwarding
NetBIOS requests or if the computer is on a subnet that is not considered to be local to
the BCAAA server.
To prevent this issue, the BCAAA machine must be configured to be able to query the
NetBIOS name of any computer of interest and get the correct IP address.
One workaround is to use a WINS server. This works like a DNS server but handles
NetBIOS lookups.
191
Volume 4: Securing the Blue Coat SG Appliance
192
Chapter 17: Using XML Realms
193
Volume 4: Securing the Blue Coat SG Appliance
2. Click New.
3. In the Realm name field, enter a realm name. The name can be 32 characters long,
composed of alphanumeric characters and underscores. The name must start with a
letter.
194
Chapter 17: Using XML Realms
4. Click OK.
5. Click Apply to commit the changes to the SG appliance.
Note: You do not need to change these values if the default settings are acceptable.
After you have created an XML realm, go to the XML Servers page to change current
default settings.
2. From the Realm Name drop-down list, select the XML realm.
3. Select the Responder options, as follows:
a. Responder: Select the XML responder service to configure—Primary or
Alternate—from the drop-down list. Primary is the default. You can configure
both responder services before clicking Apply.
b. Host: This is the hostname or IP address of the HTTP server that has the XML
service. You must specify a host. The port defaults to port 80.
c. Authenticate request path: Enter the XML responder path for authentication
requests.
d. Authorize request path: Enter the XML responder path for authorization
requests.
4. In the timeout request field, enter the number of seconds for the system to wait for a
request.
5. Enter the number of times for the system to retry a request. The default is not to retry
a request.
6. Specify the maximum number of connections to the responder. The default is five
connections.
7. Select the One-time passwords check box to use one-time passwords. This allows you
to integrate with a non-Blue Coat supported authentication service that uses one-time
passwords.
195
Volume 4: Securing the Blue Coat SG Appliance
Note: One-time passwords are passwords that become invalid as soon as they
are used. The passwords are often generated by a token or program, although pre-
printed lists are also used. Using one-time passwords ensures that the password
cannot be used in a replay attack.
Note: You do not need to change these values if the default settings are acceptable.
With XML realms, you can place the username and password in the HTTP headers of the
request or in the body of the XML POST request. If the credentials are placed in the HTTP
headers, the Web server can do the authentication and the XML service can just handle
authorization. If the credentials are placed in the XML request body, the XML service
handles both authentication and authorization.
2. From the Realm name drop-down list, select the XML realm.
3. Select one of the radio buttons to determine where to place the user credentials.
• If the HTTP server is integrated with the authentication system, the HTTP server
can authenticate the credentials. Select the Put user credentials for authentication
in the HTTP header radio button. However, if this does not provide enough
flexibility, the XML responder can do authentication.
• To have the XML responder service handle both authentication and authorization,
select the Put user credentials for authentication in the request radio button.
4. Enter the username parameter in the Username parameter field. The default is
username.
5. Click Apply to commit the changes to the SG appliance.
Note: You do not need to change these values if the default settings are acceptable.
196
Chapter 17: Using XML Realms
After you have created the XML realm, you still must take into consideration how you
will use authentication and authorization:
An XML realm can be used as an authorization realm for another realm that is doing
authentication. The authentication realm can be a Certificate realm, a Policy
Substitution realm, a Novell SSO realm, a Windows SSO realm or another XML realm.
In all cases, you must write policy to authenticate and authorize the users. For
information on writing policy for an XML realm, see “Creating the CPL” on page 200.
2. From the Realm name drop-down list, select the XML realm.
a. Authorization realm name: If the XML realm is not doing authorization, select
an authorization realm from the drop-down list. By default, the authorization
realm name is Self.
b. Authorization username: The default is Use full username. Clear the Use full
username check box to use a different name or to use a policy substitution that
generates a username.
c. Default group: The default is no groups are selected.
d. The send the groups and attributes of interest in the request check box is
selected by default. These are the groups and attributes that are used in
policy.
3. Click Apply to commit the changes to the SG appliance.
197
Volume 4: Securing the Blue Coat SG Appliance
2. From the Realm name drop-down list, select the XML realm for which you want to
change properties.
3. If needed, give the LDAP realm a display name. The default value for the display
name is the realm name. The display name cannot be greater than 128 characters and
it cannot be null.
4. Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.
5. Enter the number of seconds in the Credential refresh time field. The Credential
Refresh Time is the amount of time basic credentials (username and password) are
kept on the SG appliance. This feature allows the SG appliance to reduce the load on
the authentication server and enables credential spoofing. It has a default setting of
900 seconds (15 minutes). You can configure this in policy for better control over the
resources as policy overrides any settings made here.
Before the refresh time expires, the SG appliance will authenticate the user supplied
credentials against the cached credentials. If the credentials received do not match the
cached credentials, they are forwarded to the authentication server in case the user
password changed. After the refresh time expires, the credentials are forwarded to the
authentication server for verification.
198
Chapter 17: Using XML Realms
6. Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7. Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.
8. Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.
9. If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.
10. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
11. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
12. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
13. Click Apply to commit the changes to the SG appliance.
199
Volume 4: Securing the Blue Coat SG Appliance
Note: For information on using policy, refer to Volume 6: VPM and Advanced Policy or
Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
<proxy>
authenticate(eng_users)
<proxy>
realm=eng_users group=waterloo allow
Viewing Statistics
To view statistics for XML realms, click Statistics > Advanced. Select one of the advanced
links.
200
Appendix A: Glossary
access log A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.
account A named entity that has purchased the appliance or the Entitlements from Blue Coat.
activation code A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.
active content stripping Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.
active content types Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user
administration access policy A policy layer that determines who can access the SG appliance to perform
administrative tasks.
administration A policy layer that determines how administrators accessing the SG appliance must
authentication policy authenticate.
Application Delivery A WAN that has been optimized for acceleration and compression by Blue Coat. This
Network (ADN) network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.
ADN backup manager Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.
ADN manager Responsible for publishing the routing table to SG Clients (and to other SG
appliances).
ADN optimize attribute Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
asx rewrite Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxy-
like support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.
audit A log that provides a record of who accessed what and how.
201
Volume 4: Securing the Blue Coat SG Appliance
authenticate-401 attribute All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios
authenticated content Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).
authentication Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate Authority.
See also basic authentication, proxy authentication, and SSL authentication.
authentication realm Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.
bandwidth class hierarchy Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.
bandwidth management Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.
basic authentication The standard authentication for communicating with the target as identified in the
URL.
BCAAA Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.
byte-range support The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).
cache An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.
cache control Allows you to configure which content the SG appliance stores.
202
Appendix A: Glossary
cache efficiency A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.
cache hit Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.
cache miss Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .
cache object Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.
Certificate Authority (CA) A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.
child class (bandwidth gain) The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.
client consent certificates A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.
client-side transparency A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.
concentrator An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.
content filtering A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.
default boot system The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.
denial of service (DoS) A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.
203
Volume 4: Securing the Blue Coat SG Appliance
destination objects Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.
detect protocol attribute Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
diagnostic reporting Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.
directives Commands used in installable lists to configure forwarding and SOCKS gateway.
DNS access A policy layer that determines how the SG appliance processes DNS requests.
domain name system (DNS) An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.
dynamic bypass Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.
dynamic real-time rating Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
(DRTR) dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.
early intercept attribute Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.
ELFF-compatible format A log type defined by the W3C that is general enough to be used with any protocol.
emulated certificates Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.
encrypted log A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.
event logging Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.
204
Appendix A: Glossary
explicit proxy A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.
extended log file format A variant of the common log file format, which has two additional fields at the end of
(ELFF) the line—the referer and the user agent fields.
fail open/closed Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.
forward proxy A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.
gateway A device that serves as entrance and exit into a communications network.
hardware serial number A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.
health check tests The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
• ICMP
• TCP
• SSL
• HTTP
• HTTPS
• Group
• Composite and reference to a composite result
• ICAP
• Websense
• DRTR rating service
205
Volume 4: Securing the Blue Coat SG Appliance
health check type The kind of device or service the specific health check tests. The following types are
supported:
• Forwarding host and forwarding group
• SOCKS gateway and SOCKS gateway group
• CAP service and ICAP service group
• Websense off-box service and Websense off-box service group
• DRTR rating service
• User-defined host and a user-defined composite
heartbeat Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.
host affinity The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.
host affinity timeout The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.
inbound traffic (bandwidth Network packets flowing into the SG appliance. Inbound traffic mainly consists of
gain) the following:
• Server inbound: Packets originating at the origin content server (OCS) and sent to
the SG appliance to load a Web object.
• Client inbound: Packets originating at the client and sent to the SG appliance for
Web requests.
installable lists Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
• Creating the list using the SG text editor
• Placing the list at an accessible URL
• Downloading the directives file from the local system
integrated host timeout An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.
intervals Time period from the completion of one health check to the start of the next health
check.
IP reflection Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.
206
Appendix A: Glossary
issuer keyring The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.
licensable component (LC) (Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.
license Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.
listener The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.
live content Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.
load balancing A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.
local bypass list A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.
local policy file Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).
log facility A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.
log format The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.
log tail The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.
207
Volume 4: Securing the Blue Coat SG Appliance
Management Console A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.
management information Defines the statistics that management systems can collect. A managed device
base (MIB) (gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.
maximum object size The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.
MIME/FILE type filtering Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.
multi-bit rate The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).
multicast Used in streaming; the ability for hundreds or thousands of users to play a single
stream.
multicast aliases Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel
multicast station Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).
multimedia content services Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.
name inputing Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server
native FTP Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).
NCSA common log format Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.
network address translation The process of translating private network (such as intranet) IP addresses to Internet
(NAT) IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.
208
Appendix A: Glossary
non-cacheable objects A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
• Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
• Password provided, requests that include a client password.
• Data in request that include additional client data.
• Not a GET request.
.nsc file Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.
NTP To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.
object (used in caching) An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.
object (used in Visual Policy An object (sometimes referred to as a condition) is any collection or combination of
Manager) entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.
object pipelining This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.
origin content server (OCS) Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.
outbound traffic (bandwidth Network packets flowing out of the SG appliance. Outbound traffic mainly consists
gain) of the following:
• Client outbound: Packets sent to the client in response to a Web request.
• Server outbound: Packets sent to an OCS or upstream proxy to request a service.
PAC (Proxy Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
AutoConfiguration) scripts port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.
packet capture (PCAP) Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.
209
Volume 4: Securing the Blue Coat SG Appliance
parent class (bandwidth A class with at least one child. The parent class must share its bandwidth with its
gain) child classes in proportion to the minimum/maximum bandwidth values or priority
levels.
passive mode data Data connections initiated by an FTP client to an FTP server.
connections (PASV)
policies Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.
policy-based bypass list Used in policy. Allows a bypass based on the properties of the client, unlike static and
dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.
policy layer A collection of rules created using Blue Coat CPL or with the VPM.
pragma: no cache (PNC) A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).
proxy Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.
proxy service The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.
proxy service (default) The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.
public key certificate An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).
public virtual IP (VIP) Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.
210
Appendix A: Glossary
real-time streaming protocol A standard method of transferring audio and video and other time-based media over
(RTSP) Internet-technology based networks. The protocol is used to stream clips to any RTP-
based client.
reflect client IP attribute Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.
registration An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.
remote authentication dial- Authenticates user identity via passwords for network access.
in user service (RADIUS)
reverse proxy A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.
routing information protocol Designed to select the fastest route to a destination. RIP support is built into Blue
(RIP) Coat appliances.
router hops The number of jumps a packet takes when traversing the Internet.
secure shell (SSH) Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.
serial console A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.
server certificate categories The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.
server portals Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping a
set of external URLs onto a set of internal URLs.
server-side transparency The ability for the server to see client IP addresses, which enables accurate client-
access records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.
service attributes Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .
211
Volume 4: Securing the Blue Coat SG Appliance
SG appliance A Blue Coat security and cache box that can help manage security and content on a
network.
sibling class (bandwidth A bandwidth class with the same parent class as another class.
gain)
simple network The standard operations and maintenance protocol for the Internet. It uses MIBs,
management protocol created or customized by Blue Coat, to handle (needs completion).
(SNMP)
simulated live Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.
SmartReporter log type A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.
SOCKS A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.
SOCKS proxy A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.
splash page Custom message page that displays the first time you start the client browser.
split proxy Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
• Mapi Proxy
• SSL Proxy
SQUID-compatible format A log type that was designed for cache statistics and is compatible with Blue Coat
products.
squid-native log format The Squid-compatible format contains one line for each request.
SSL authentication Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).
SSL proxy A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.
static route A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.
212
Appendix A: Glossary
statistics Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated, cache
efficiency, cached contents, and custom URLs generated by the appliance for various
kinds of logs. You can also check the event viewer for every event that occurred since
the appliance booted.
stream A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.
SurfControl log type A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.
system cache The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.
time-to-live (TTL) value Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.
traffic flow Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
(bandwidth gain) that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of
these connections, traffic flows in two directions—in one direction, packets flow out
of the SG appliance (outbound traffic), and in the other direction, packets flow into
the SG (inbound traffic). Connections can come from the client or the server. Thus,
traffic can be classified into one of four types:
• Server inbound
• Server outbound
• Client inbound
• Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.
transmission control TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
protocol (TCP) in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.
transparent proxy A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.
213
Volume 4: Securing the Blue Coat SG Appliance
trial period Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.
unicast alias Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicast-
alias command to request the content from the origin streaming server.
universal time coordinates An SG appliance must know the current UTC time. By default, the appliance
(UTC) attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.
URL rewrite rules Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.
WCCP Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.
Web FTP Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
OCS (if the content is not already cached), and then translates the FTP response with
the file contents into an HTTP response for the client.
Websense log type A Blue Coat proprietary log type that is compatible with the Websense reporter tool.
214
Appendix B: Using the Authentication/Authorization Agent
The Blue Coat Systems Authentication and Authorization Agent (BCAAA) allows
SGOS 5.x to manage authentication and authorization for several different realms. The
agent is installed and configured separately from SGOS 5.x and is available at the Blue
Coat Website.
The BCAAA service must be installed on a domain controller or member server,
allowing the SG to access domain controllers. The BCAAA service authenticates users
in all domains trusted by the computer on which it is running. A single installation of
the BCAAA service can support multiple appliances.
Multiple versions of BCAAA can run on the same machine. This allows you to use the
same machine to support versions of the SG that have different BCAAA version
requirements.
The BCAAA install directory can include multiple executable programs.
❐ The program bcaaa.exe (bcaaa on Solaris) handles connections from SG
appliances and hands them off to the correct version of the processor.
❐ The program bcaaa-99.exe (bcaaa-99 on Solaris) handles communication with
versions of the SG prior to SGOS 4.2.
❐ The program bcaaa-100.exe (bcaaa-100 on Solaris) handles communication
with SGOS 4.2.1, SGOS 5.1.1, and SGOS 5.1.2.
❐ The program bcaaa-110.exe (bcaaa-110 on Solaris) handles communication
with SGOS 4.2.2 , SGOS 5.1.3, and SGOS 5.1.4.
❐ The program bcaaa-120.exe (bcaaa-120 on Solaris) handles communication
with SGOS 4.2.3, SGOS 4.2.4, and SGOS 5.2.1 and later.
When a new version of BCAAA is installed in the same installation directory as earlier
versions, the earlier versions are not removed.
This allows SG appliances that were communicating with the old version to continue to
operate.
215
Volume 4: Securing the Blue Coat SG Appliance
For specific information about configuring the SiteMinder realm to work with the CA
eTrust policy servers, see Chapter 12: "CA eTrust SiteMinder Authentication" on
page 143. For specific information about configuring the COREid realm to work with
Oracle COREid Access Servers, see Chapter 6: "Oracle COREid Authentication" on
page 79.
❐ Windows Single Sign-on (SSO): The BCAAA service is used to supply mappings for
IP addresses to logged on users. The Windows SSO realm can use domain controller
querying, or client querying, or both domain controller and client querying to
determine the logged-on user.
To use domain controller querying, you must configure the sso.ini file to enable it
and to add the domain controllers you want to query. For information on configuring
the sso.ini file, see “Modifying the sso.ini File for Windows SSO Realms” on page
188.
❐ Novell SSO: The BCAAA service manages communication with the Novell eDirectory
server. This realm also requires that the sso.ini file be configured. For information on
configuring the sso.ini file, see “Modifying the sso.ini File for Novell SSO Realms” on
page 171.
Performance Notes
Blue Coat recommends that the Windows BCAAA service be installed on a dedicated
Windows machine. Installation of any other non-essential software might degrade the
BCAAA service performance, which in turn degrades the user experience.
This is because the BCAAA server is in the client data path for accessing protected
resources. Users make client requests to the SG appliance, which in turn proxies
authentication requests to the BCAAA service. The user must wait for the authentication
request to complete before the SG appliance responds to the user with a protected
resource.
Operating system requirements are:
❐ IWA and COREid: Windows® 2000 or later.
❐ SiteMinder: Windows 2000 or later or Solaris™ 5.8 or 5.9.
❐ Novell SSO: Windows 2000 or later
❐ Windows SSO: Windows 2000 or later
216
Appendix B: Using the Authentication/Authorization Agent
Note: The firewall on Windows machine should be disabled for BCAAA to work.
Note: When doing an upgrade from one version of BCAAA to another version of
BCAAA, you must install into the previous BCAAA folder to retain your settings. If
you install to a different folder, a new .ini file with default settings is created.
4. Click Browse to select a different destination folder for the BCAAA service.
5. Click Next to accept the default and select the port number.
217
Volume 4: Securing the Blue Coat SG Appliance
6. The port number must match the port number you specify on the SG for the BCAAA
service. The default is 16101.
7. Click Next to select the number of threads.
8. The recommended (and default) value is 2. The maximum number of threads allowed
is 99 per SG. After selecting the number, click Next to specify the SSL requirements.
9. The default is that SSL is Permitted, allowing both SSL and non-SSL connections. This
setting must be compatible with the setting on the SG appliance.
10. Click Next to specify the subject of the SSL certificate.
218
Appendix B: Using the Authentication/Authorization Agent
13. Click Next to specify whether the SG appliance must provide a valid certificate when
connecting to the BCAAA service.
219
Volume 4: Securing the Blue Coat SG Appliance
14. To force the SG to provide a valid certificate to connect to the BCAAA service, select
the Yes radio button. The default is No.
15. Click Next to view the summary of the changes you made.
16. Click Install to install the BCAAA service using the settings you configured.
When installation completes, the final BCAAA screen displays.
2. Click Modify to re-enter the installation wizard; click Remove to uninstall the BCAAA
service from the system.
Note: For instructions on using the installation wizard, see “Installing the BCAAA
Service on a Windows System” on page 217.
220
Appendix B: Using the Authentication/Authorization Agent
2. Verify in Local Security Policy's User Rights Assignment folder that the BCAAA
Service user account has been added to the list of the Log on as a service policy.
221
Volume 4: Securing the Blue Coat SG Appliance
To solve this:
1. Stop the BCAAA service.
2. From the Run prompt, type mmc, which is the Microsoft Management Console.
3. Click File > Add/Remove Snap-in > Add > Certificates > Add Service Account > Local
Computer > BCAAA
4. Delete any certificate shown in the BCAAA/Personal category.
Now when the BCAAA is run, it can create a new certificate and successfully handle an
SSL connection.
Solutions:
❐ Make the BCAAA user a Domain Administrator or an Administrator of the computer
where the BCAAA service is running.
❐ Give the BCAAA user access the certificate store:
• Stop the BCAAA service.
• From the Run prompt, launch the regedit program to give the BCAAA user full
access to the following key and its children:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Services
Note: For successful installation of the BCAAA service on a Solaris system, you need
libstdc++.so.5", usually installed with package
SFWgcc32 gcc-3.2 - GNU Compiler Collection Version 3.2
222
Appendix B: Using the Authentication/Authorization Agent
3. Answer the questions to install the service on your Solaris system. A sample session is
shown below:
Enter a path to a scratch directory [/tmp]:
Install Blue Coat Systems Authentication and Authorization Agent
(BCAAA)? (y/n)y
Enter user that should own the installed files [root]
Enter group for the installed files [root]
/usr/local/bin/bcaaa installed
/usr/local/bin/bcaaa-100 installed
Libraries installed in /usr/local/lib/BlueCoatSystems/
/usr/local/etc/bcaaa.ini installed
If you use inetd, append the following line to /etc/services
bcaaa 16101/tcp #Blue Coat Systems
Authentication Agent
If you use inetd, append the following line to /etc/inetd.conf, then
signal inetd to re-read the configuration file
If you use something else, make the equivalent changes
bcaaa stream tcp nowait root /usr/local/bin/bcaaa bcaaa -c /usr/local/
etc/bcaaa.ini
Installation complete
Note: Handling of the shared secret is done by Windows when the machine joins the
domain; there is no explicit knowledge of the shared secret by SGOS or by BCAAA.
❐ Service Account
You can also create a service account for the BCAAA service and register the SPN on
the service account. This allows multiple servers to run BCAAA all using the same
account.
The advantage is the ability to have a backup BCAAA server. The disadvantage is
that it requires additional configuration on the Active Directory server, the domain
controller, and on each BCAAA machine. It is also less secure, since the BCAAA
account password is shared among multiple machines.
223
Volume 4: Securing the Blue Coat SG Appliance
http://support.microsoft.com/default.aspx?scid=kb;en-us;831218
2. Ensure that the Active Directory computer account running the BCAAA service has
the "Trust computer for delegation" configuration property enabled.
On each machine where you want to run the BCAAA service:
1. Install the BCAAA service as normal.
2. Open the Properties panel for the BCAAA service and select the Logon tab. Change
the account to the one you created on the Active Directory server, and enter the
password. When you click OK, it might warn you that the account has been granted
"Log On as A Service right".
3. Change the security on the BCAAA install directory to give the account created on the
Active Directory server full control.
All these machines now share the same secret with the KDC and can decrypt service
tickets intended for the service described by the SPN.
224
Appendix B: Using the Authentication/Authorization Agent
400 Various messages The associated message describes an error condition that
prevents normal operation.
1001 Authentication Agent service started: This indicates successful startup and provides
port=# threads=# socket=0x# information about the agent.
process id=# agent version=#
SG Appliance version=#
225
Volume 4: Securing the Blue Coat SG Appliance
1002 Authentication Agent stopped This indicates normal shutdown of the service.
1003 SG Appliance (a.b.c.d) connected; This indicates a SG appliance has connected to the agent
Process # spawned as # (Windows only).
1004 SG Appliance agent process exited This indicates normal logout by a SG appliance.
(normal logout)
1006 Service dispatcher exited. This indicates an unexpected termination of the service
dispatcher.
1007 CreateNamedPipe failed, pipe='%s' The agent dispatcher could not create the named pipe for
the reason given.
1008 ConnectNamedPipe failed, pipe='%s' The agent process could not obtain the information from
the dispatcher on the named pipe for the reason given.
1009 WriteFile failed, pipe='%s' The dispatcher could not write information to the named
pipe for the reason given.
1011 CreateThread (ProcessTimerThread) The dispatcher could not create its timer thread.
failed
1012 Failed to create SG Appliance process The BCAAA server does not have the same version of
'%s' BCAAA available as the SG is expecting.
1019 Various The dispatcher was unable to determine the exit status of
an agent process.
1020 Terminating SG Appliance process #, An agent process was active when the Windows service
ProcNum=# Handle=0x# was shut down.
1101 BasicAuth: CloseHandle failed; user The agent was unable to close the login handle for the
'xx\\xx' specified user.
1102 Username: '%s\\%s' too long The SG appliance offered the specified username, which
is too long.
1107 User Right 'Act as part of the operating The agent does not have the necessary privileges to do
system' required for Basic BASIC authentication
Authentication
1108 Various The agent was unable to determine information about the
user for the reason given.
1202 Unable to create GroupsOfInterest The agent could not create the Windows mutex needed
mutex 'xx' - already exists for group authorization checks because it already exists.
1203 Unable to create GroupsOfInterest The agent could not create the Windows mutex needed
mutex 'xx for group authorization checks.
226
Appendix B: Using the Authentication/Authorization Agent
1204 OpenMutex failed for AuthGroups The agent was unable to open the Windows mutex
mutex '%s', group='%s' needed for group authorization checks.
1205 Various The agent was unable to close the Windows mutex
named for the reason given.
1207 GetAclInformation failed The agent was unable to obtain ACL information needed
to do group authorization checks.
1209 GetKernelObjectSecurity failed for The agent was unable to obtain security information
AuthGroup='%s' about the specified group.
1210 SetKernelObjectSecurity failed The agent was unable to set up security information for
the reason specified.
1211 InitializeSecurityDescriptor failed The agent was unable to initialize the security descriptor
for the reason specified.
1212 GetSecurityDescriptorDacl failed The agent was unable to get the discretionary access
control list (DACL) for the reason specified.
1213 SetSecurityDescriptorDacl failed The agent was unable to set the discretionary access
control list (DACL) for the reason specified.
1214 InitializeAcl failed The agent was unable to initialize the access control list
(ACL) for the reason specified.
1215 GetUserName failed for The agent was unable to determine the username while
AuthGroup='%s' processing the specified group.
1217 GetAce failed for AuthGroup='%s' The agent was unable to get the access control entry
(ACE) for the specified group.
1218 AddAce failed The agent was unable to add the necessary access control
entry (ACE) for the reason specified.
1219 AddAccessAllowedAce failed The agent was unable to add the necessary "access
allowed" access control entry (ACE).
1220 Could not establish groups-of-interest: The agent was unable to initialize groups-of-interest
result=0x## checking.
1221 AuthGroup '%s' does not exist The specified group does not exist.
1222 IWA RevertSecurityContext failed, The agent could not revert the security context for the
user='%s' specified user.
1223 BASIC: RevertToSelf failed, user='%s' The agent could not revert the security context for the
specified user.
1224 Error calling OpenProcessToken The agent's call to OpenProcessToken failed for the
specified reason.
1225 Error calling LookupPrivilegeValue The agent could not get information about a needed
privilege.
1226 Error calling AdjustTokenPrivileges The agent could not adjust its privileges as required.
1227 ImpersonateLoggedOnUser failed; The agent could not impersonate the specified user.
Group access denied for user '%s'
227
Volume 4: Securing the Blue Coat SG Appliance
1228 IWA: ImpersonateSecurityContext The agent could not impersonate the specified user.
failed; Group access denied for user '%s'
1301 NOTE: Pending ContextLink=### timed The SG appliance did not provide a response to a
out; deleting SecurityContext h=## challenge quickly enough.
TS=## now=##
1304 Various The agent was unable to delete a security context for the
reason given.
1305 AcceptSecurityContext failure, The agent was provided with an invalid context handle.
SEC_E_INVALID_HANDLE,
ContextLink=### count=#
1308 AcceptSecurityContext failure, Windows rejected the authentication attempt for the
ContextLink=# count=#, detail=#(xxx) reason given.
1311 3:Failed NTLM Authentication for user: This records the failure of NTLM authentication; the user
'%s' name was supplied by the client.
1312 Various The agent could not determine the username from the
NTLM type 3 message supplied by the client.
1313 Invalid Type3 message The client provided an NTLM type 3 message that was
invalid.
1314 BASE64_Decode: Length of token The client provided an NTLM token that was too long.
exceeds max (%d)
1316 Unsupported version in request: The SG appliance sent a request with an unsupported
%d(0x%x) version number.
1404 Unable to get ProcessInfo from parent The agent could not obtain its information from the
process. dispatcher.
1405 CreateFile failed, pipe='xx' The agent could not create a handle for the dispatcher's
named pipe.
1406 WaitNamedPipe failed, pipe='%s' The agent could not wait for the dispatcher's named pipe.
1407 ReadFile failed, pipe='%s' The agent could not read information from the
dispatcher's named pipe.
228
Appendix B: Using the Authentication/Authorization Agent
1409 Various The agent could not create the specified thread for the
reason given.
1412 Various The agent could not create a required Windows event
object.
1501 Unable to allocate memory for ProcLink The agent could not allocate some needed memory.
buffer.
1502 Unable to allocate memory for The agent could not allocate some needed memory.
ContextLink buffer.
1604 Service dispatch failed The Windows service dispatcher failed to start.
1605 RegisterServiceCtrlHandler failed The agent dispatcher was unable to register the service
control handler.
1608 SetServiceStatus failed, The agent was unable to set the service's status.
g_StatusHandle=%d
1610 Unsupported service control code: # Windows sent a service control code that the agent does
not support.
1701 WSASocket failed The agent could not create a Windows socket for the
reason given.
1702 WSAStartup failed. The agent could not start the Windows socket for the
reason given.
1703 Various The agent could not send data to the SG appliance for the
reason given.
1704 Various The agent could not receive data from the SG appliance
for the reason given.
1705 accept failed The agent dispatcher could not initialize to accept new
connections.
1706 bind failed, PortNumber=# The agent dispatcher could not bind to the specified port.
1707 listen failed. The agent dispatcher could not listen for new
connections.
1709 The agent is already running or the Some other process is already using the port needed by
agent's port # is in use by another the agent.
process
229
Volume 4: Securing the Blue Coat SG Appliance
1710 WSARecv failed reading bytes from Windows reported an error when the agent tried to
socket receive bytes from the SG appliance.
1711 WSASend failed sending bytes to socket. Windows reported an error when the agent tried to send
bytes to the SG appliance.
1801 Error calling AcquireCredentialsHandle The agent could not acquire its credentials from
Windows.
1803 Various The agent could not load a needed library (DLL).
1804 Various The agent could not locate the needed services in a library
(DLL).
1805 Unsupported SSPI Windows platform; The reported Windows platform is not supported for
PlatformId=# NTLM authentication.
1806 Error calling QueryContextAttributes The agent could not determine the authenticated user's
security attributes.
1807 QuerySecurityPackageInfo failed The agent could not get needed security information from
Windows.
1808 Max Token size too long (#); max size is The client supplied an NTLM token that is too long.
#
1809 FreeContextBuffer failed An attempt to free the NTLM context buffer failed.
1811 Username 'x\\y' too long The reported user name is too long.
1901 Admin Services Error: Access denied to The agent was unable to access necessary information.
domain/user/group information
1902 Admin Services Error: Invalid computer The computer to be used to get security information is
from which to fetch information invalid.
1903 Admin Services Error: Group not found The requested group could not be found.
1905 Admin services error: could not The requested object for browsing could not be translated
translate context to Unicode to Unicode
1906 Admin service out of memory The browsing service ran out of memory.
1907 Search request object too long: # > # The requested object for browsing is too long.
2000 AcquireCredentialsHandle failed: 0x# The agent could not acquire the credentials needed for an
SSL session.
2001 Various The agent was unable to negotiate an SSL session for the
reason given.
230
Appendix B: Using the Authentication/Authorization Agent
231
Volume 4: Securing the Blue Coat SG Appliance
232
Appendix C: Managing the SSL Client
To associate a keyring with the SSL client and change the protocol version:
1. Select Configuration>SSL>SSL Client.
2. Verify Use SSL Client is selected.
233
Volume 4: Securing the Blue Coat SG Appliance
3. Only keyrings with certificates can be associated with the SSL client, displayed in the
Keyring drop-down list. Select the keyring used to negotiate with origin content
servers through an encrypted connection.
4. You can change the SSL Versions default from SSLv2v3TLSv1 to any other protocol
listed in the drop-down list.
5. Click OK; click Apply
Related CLI Syntax to Associate a Keyring and Protocol with the SSL Client
SGOS#(config) ssl
SGOS#(config ssl) edit ssl-client default
SGOS#(config ssl ssl-client default) keyring-id keyring_id
SGOS#(config ssl ssl-client default) protocol {sslv2 | sslv3 | tlsv1 |
sslv2v3 | sslv2tlsv1 | sslv3tlsv1 | sslv2v3tlsv1}
Note: Director uses non-interactive commands in profiles and overlays to create cipher
suites. For more information on Director, refer to the Blue Coat Director Configuration and
Management Guide.)
234
Appendix C: Managing the SSL Client
235
Volume 4: Securing the Blue Coat SG Appliance
Example
SGOS#(config ssl ssl-client default) cipher-suite rc4-md5 des-cbc3-md5
exp1024-rc4-md5 exp-des-cbc-sha
ok
SGOS#(config ssl ssl-client default) view
SSL-Client Name Keyring Name Protocol
-------------- ------------ ------------
default default SSLv2v3TLSv1
236
Appendix C: Managing the SSL Client
237
Volume 4: Securing the Blue Coat SG Appliance
238
Appendix D: XML Protocol
The XML realm uses a SOAP 1.2 based protocol for the Blue Coat supported protocol.
A schema has been placed at http://www.bluecoat.com/xmlns/xml-realm/1.0.
This appendix includes the following sections:
❐ Section A: "Authenticate Request" on page 240
❐ Section B: "Authenticate Response" on page 242
❐ Section C: "Authorize Request" on page 244
❐ Section D: "Authorize Response" on page 245
239
Volume 4: Securing the Blue Coat SG Appliance
240
Appendix D: XML Protocol
<m:username>Username</m:username>
<m:challenge-state>challenge state</m:challenge-state>
<m:groups enc:arraySize="*" enc:itemType="xsd:string">
<m:group>group1</m:group>
<m:group>group2</m:group>
</m:groups>
<m:attributes enc:arraySize="*" enc:itemType="xsd:string">
<m:attribute>attribute1</m:attribute>
<m:attribute>attribute2</m:attribute>
</m:attributes>
</m:authenticate>
</env:Body>
</env:Envelope>
241
Volume 4: Securing the Blue Coat SG Appliance
Success
All of the response fields except "full-username" are optional. The intersection of the
groups of interest and the groups that the user is in are returned in the groups element.
The attributes of interest for the user are returned in a flattened two dimensional array of
attribute names and values.
<?xml version='1.0' encoding="UTF-8" ?>
<env:Envelope
xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Body
env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
<m:authenticate-response
xmlns:m="http://www.bluecoat.com/xmlns/xml-realm/1.0">
<m:full-username>full-username</m:full-username>
<m:groups enc:arraySize="*" enc:itemType="xsd:string">
<m:group>group2</m:group>
</m:groups>
<m:attribute-values enc:arraySize="* 2" enc:itemType="xsd:string">
<m:item>attribute2</m:item>
<m:item>value2a</m:item>
<m:item>attribute2</m:item>
<m:item>value2b</m:item>
<m:item>attribute2</m:item>
<m:item>value2c</m:item>
</m:attribute-values>
</m:authenticate-response>
</env:Body>
</env:Envelope>
Failed/Denied
The failed response includes a text description of the failure that becomes the text
description of the error reported to the user. The fault-code is one of a set of SGOS
authentication errors that can be returned from the responder. The codes are returned as
strings, but are part of an enumeration declared in the schema for the protocol. Only codes
in this list are acceptable.
account_disabled
account_restricted
credentials_mismatch
general_authentication_error
expired_credentials
account_locked_out
account_must_change_password
offbox_server_down
general_authorization_error
unknown_error
<?xml version='1.0' encoding="UTF-8" ?>
<env:Envelope
xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Body>
<env:Fault>
<env:Code>
<env:Value>env:Sender</env:Value>
242
Appendix D: XML Protocol
</env:Code>
<env:Reason>
<env:Text xml:lang="en-US">Bad username or password</env:Text>
</env:Reason>
<env:Detail>
<e:realm-fault
xmlns:e="http://www.bluecoat.com/xmlns/xml-realm/1.0">
<e:fault-code>general_authentication_error</e:fault-code>
<e:realm-fault>
<env:Detail>
<env:Fault>
</env:Body>
</env:Envelope>
243
Volume 4: Securing the Blue Coat SG Appliance
GET Method
http://<server hostname>:<server port>/<authorize service
path>?<username parameter
name>=<username>[&group=<group1>&group=<group2>…&attribute=<attribute1
>&…]
POST Method
<?xml version='1.0' encoding="UTF-8" ?>
<env:Envelope
xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Body
env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
<m:authorize
xmlns:m="http://www.bluecoat.com/soap/xmlns/xml-realm/1.0">
<m:username>Username</m:username>
<m:groups enc:arraySize="*" enc:itemType="xsd:string">
<m:group>group1</m:group>
<m:group>group2</m:group>
</m:groups>
<m:attributes enc:arraySize="*" enc:itemType="xsd:string">
<m:attribute>attribute1</m:attribute>
<m:attribute>attribute2</m:attribute>
</m:attributes>
</m:authorize>
</env:Body>
</env:Envelope>
244
Appendix D: XML Protocol
Success
Only applicable groups and attributes are returned. Multi-valued attributes are returned
by multiple instances of the same attribute name.
<?xml version='1.0' encoding="UTF-8" ?>
<env:Envelope
xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Body
env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
<m:authorize-response
xmlns:m="http://www.bluecoat.com/xmlns/xml-realm/1.0">
<m:groups enc:arraySize="*" enc:itemType="xsd:string">
<m:group>group2</m:group>
</m:groups>
<m:attribute-values enc:arraySize="* 2" enc:itemType="xsd:string">
<m:item>attribute2</m:item>
<m:item>value2a</m:item>
<m:item>attribute2</m:item>
<m:item>value2b</m:item>
<m:item>attribute2</m:item>
<m:item>value2c</m:item>
</m:attribute-values>
</m:authorize>
</env:Body>
</env:Envelope>
Failed
<?xml version='1.0'encoding="UTF-8" ?>
<env:Envelope
xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Body>
<env:Fault>
<env:Code>
<env:Value>env:Receiver</env:Value>
</env:Code>
<env:Reason>
<env:Text xml:lang="en-US">Could not contact LDAP server</env:Text>
</env:Reason>
<env:Detail>
<e:realm-fault
xmlns:e="http://www.bluecoat.com/xmlns/xml-realm/1.0">
<e:fault-code>offbox_server_down</e:fault-code>
<e:realm-fault>
<env:Detail>
<env:Fault>
</env:Body>
</env:Envelope>
245
Volume 4: Securing the Blue Coat SG Appliance
246
Appendix E: Authentication and Authorization Errors
Following is the list of all groups and individual errors that can be permitted during
authentication and authorization. The first table lists the groups and the individual
errors within each group. The second table lists all of the individual errors along with
descriptions of the errors.
basic_password_too_long
basic_username_too_long
cannot_decrypt_secret
cannot_determine_authorization_
username
cannot_determine_full_username
cannot_determine_username
cannot_expand_credentials_
substitution
cannot_redirect_connect
cannot_redirect_https_to_http
cannot_setup_working_dir
cert_explicit_unsupported
certificate_missing
credential_decode_failure
credentials_mismatch
247
Volume 4: Securing the Blue Coat SG Appliance
248
Appendix E: Authentication and Authorization Errors
249
Volume 4: Securing the Blue Coat SG Appliance
250
Appendix E: Authentication and Authorization Errors
251
Volume 4: Securing the Blue Coat SG Appliance
252
Appendix E: Authentication and Authorization Errors
253
Volume 4: Securing the Blue Coat SG Appliance
254
Appendix E: Authentication and Authorization Errors
255
Volume 4: Securing the Blue Coat SG Appliance
256
Appendix E: Authentication and Authorization Errors
257
Volume 4: Securing the Blue Coat SG Appliance
258
Index
A B
access control list BCAAA
creating 19, 27 COREid realm, using with 82
restricting access with 19 event log, viewing 221
access logs event messages 225
digital signing installation folder, selecting 217
overview 66 Service Principal Names, creating 223
access restrictions services, viewing 221
access control list for 19 SSL, using with pre-Windows 2003 222
configuring 19 SSL, using with Windows 2003 and higher 222
Admin layer troubleshooting 225
example 24 WIDMS, configuring for 146
administrator Blue Coat SG
defining policies 20 read-only and read-write access 17
security levels 17 restricting access to 19
ADN
realms, using with 141, 172, 190 C
Application Delivery Network (ADN) CA Certificates
Novell SSO realms, using with 141, 172, 190 certificate signing request
policy substitution realms, using with 141, 172, creating 59, 60
190 error message 61
realm authentication, configuring policy 141, 172, lists
190 creating through CLI 71
reflect ip address attribute, using 141, 172, 190 creating through Management Console 70
Windows SSO realms, using with 141, 172, 190 managing 60
authenticate.mode, IWA, realm setting for 34 troubleshooting 61
authentication CAASNT, see BCAAA
configuring transparent proxy authentication 35 certificate realm
definition of 11 authentication and authorization overview 73
guest 38 configuring authentication and authorization 73
LDAP realm 109 defining properties 74
permitted errors, understanding 37 defining realm server properties 74
policies 11, 15 how it works 73
setting options for transparent proxy LDAP authorization, adding 74
authentication 35, 36 local authorization, adding 74
authentication realm overview 73
typical configuration 12 policies, creating 77
authorization requirements 73
definition of 11 Certificate Revocation Lists (CRLs)
LDAP realm 109 configuring 63
policies 11, 15, 55 PEM encoded/DER format 63
authorization refresh time, discussed 29 using 62
certificate signing request
creating 59
259
Volume 4: Securing the Blue Coat SG Appliance
260
Index
creating 15 L
LDAP
G policy-substitution realm, adding to 137
guest authentication v2/v3 support 109
policy substitutions used with 39 LDAP realm
policy used with 39 authentication and authorization overview 109
understanding 38 authorization 114
case-sensitive configuration 111
H certificate realm, adding to 74
.htpasswd file CPL examples 119
creating password realm database 125 defining Base DNs 113
loading 125 defining realm authorization properties and
uploading 125 group information 114
hashed passwords, using 16 defining realm server properties 110
header defining server properties 111
policy substitution realm, using with 140 group information 115
HTTP server search boundaries 114
XML realms, configuring for 194 searching multiple base DNs 112
HTTPS Console SSL, enabling 111
certificate error message 64 virtual URL, setting up 118
troubleshooting certificate problems 64 Lightweight Directory Access Protocol, see LDAP
HTTPS termination local realm
certificates 52 authentication and authorization overview 121
configuring 55 certificate realm, adding to 74
keyring, creating 56 changing properties 121
CPL, creating policies 129
I creating a realm 121
Internet Explorer database group, creating 126
troubleshooting for explicit policy substitution database user, creating 126
realm 179 database users, viewing 127
troubleshooting for transparent proxy 179 database, creating 123
IP address surrogates, refresh time, discussed 30 database, creating through Blue Coat SG 126
IWA realm database, populated 124
authenticate.mode, setting 34 database, setting up 123
configuring authentication and authorization 101 defining realm server properties 121
defining realm server properties 101 deleting groups 128
Kerberos, enabling 103 deleting users 128
overview 101 groups, defined 124
policies, creating 107 groups, deleting 128
Service Principal Names, creating 223 hashed passwords 124
single sign-on, configuring 107 policy substitution realm, adding to 137
user name, defined 124
K users, deleting 128
Kerberos. See IWA view all lists 127
keyring virtual URL, setting up 123
associating with certificate 68 local user list
importing 67 security settings, changing 128
SSL client, associating 233
261
Volume 4: Securing the Blue Coat SG Appliance
262
Index
S configuring 35
security setting options for 35, 36
console account 17 troubleshooting
local user list settings, changing 128 BCAAA service 225
policies for 17 CA Certificates 61
sequence realm CONNECT method 35
defining realm server properties 176 forms-based authentication realm 100
sequences, troubleshooting 175 HTTPS Console 64
serial port RADIUS realm 162
password, creating 16 TCP_DENIED 33
Service Principal Names, creating for IWA realm 223
set_aut.pl script, using with .htpasswd file 125 U
setup console user data
password, creating 16 policy, refreshing through 30
SiteMinder, see Netegrity SiteMinder realm refreshing 28
SOAP users
XML realms, using with 193 administrator logout 28
SSH credential refresh time, discussed 29
password authentication 17 logged-in, viewing 26
SSH with RSA authentication, not controlled by logging in 26
policy 20 logging out 27
SSL logout conditions 28
authentication/authorization services, using with logout properties 28
41 managing 26
caching behavior, SSL client 233 policy logout 28
cipher suites interactive mode, using 234 timeout 27
cipher suites non-interactive mode, using 235 user data, refreshing 28
LDAP realm, enabling 111
no-show keyring option 57 V
show keyring option 57 virtual URL
show-director option 57 LDAP realm set up 118
timeout, configuring 237
SSL certificates, see certificates. W
SSL client Windows
keyring, associating 233 configuring authorization 181
managing 233 Windows SSO
sso.ini, modifying for Novell SSO realms 171 authorization, configuring 185
sso.ini, modifying for Windows SSO realm 188 authorization, using 183
surrogate credentials BCAAA, configuring 184
defined 32 BCAAA, works with 182
refresh time, discussed 30 creating a realm through CLI 185
defining general properties through CLI 188
T defining realm server properties 183
timeout defining realm server properties through
configuring for SSL termination 237 Management Console 183
transparent proxy general properties, configuring 186
CLI commands 36 how it works 181
policy substitution realm, troubleshooting 179 policies, creating 190
transparent proxy authentication sso.ini file, modifying 188
263
Volume 4: Securing the Blue Coat SG Appliance
264
Blue Coat® Systems
SG™ Appliance
Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
ii
Contents
Contact Information
iii
Volume 5: Advanced Networking
Approved/Pending Notes............................................................................................................................... 38
Section E: ADN Network History, Statistics, and Health Metrics
Reviewing ADN History.................................................................................................................................. 39
Reviewing Byte-Caching Statistics ................................................................................................................. 39
Reviewing ADN Health Metrics..................................................................................................................... 40
Section F: Advanced Tunnel Optimization
Setting Advanced Tunneling Parameters...................................................................................................... 42
Section G: Manually Re-Sizing a Byte-Cache Dictionary
Section H: Related CLI Syntax to Configure an ADN Network
Section I: Policy
iv
Contents
v
Volume 5: Advanced Networking
vi
Contents
vii
Volume 5: Advanced Networking
viii
Contents
Appendix A: Glossary
Index
ix
Volume 5: Advanced Networking
x
Chapter 1: About Advanced Networking
Volume 5: Advanced Networking discusses networking tasks that are not required in
every environment, such as:
❐ TCP/IP settings.
❐ WAN Optimization, which enables you to optimize environments with application
delivery networks (ADNs).
❐ Forwarding, which allows you to define the hosts and groups of hosts to which
client requests can be redirected.
❐ Health Checks, which reports on the health of upstream hosts.
11
Volume 5: Advanced Networking
Document Conventions
The following table lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Conventions Definition
Courier font Command line text that appears on your administrator workstation.
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.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
12
Chapter 2: Configuring an Application Delivery Network
In addition, you can configure the ADN network to provide additional security to
internal ADN routing connections and to ADN tunnel connections that carry
optimized application data. In a fully secured ADN network, only authenticated and
authorized devices are allowed to join the ADN network. All connections between
ADN nodes and the ADN manager and connections among the ADN nodes are
ensured of message authenticity and privacy protection.
13
Volume 5: Advanced Networking
In this Chapter
The following topics are discussed in this chapter:
❐ Section A: "About the Blue Coat Implementation for WAN Optimization" on page 15.
❐ Section B: "Basic ADN Setup" on page 21.
❐ Section C: "Transparent and Explicit Connection Deployments" on page 23.
❐ Section D: "Securing the ADN Network" on page 32.
❐ Section E: "ADN Network History, Statistics, and Health Metrics" on page 39.
❐ Section F: "Advanced Tunnel Optimization" on page 42.
❐ Section G: "Manually Re-Sizing a Byte-Cache Dictionary" on page 45.
❐ Section H: "Related CLI Syntax to Configure an ADN Network" on page 48.
❐ Section I: "Policy" on page 50.
14
Chapter 2: Configuring an Application Delivery Network
ADN Components
The components of the Blue Coat ADN implementation are:
❐ ADN manager and backup ADN manager to provide routing information and control
access to the ADN network.
❐ ADN nodes in both branch offices and data centers that can be authenticated (identity
verified) and authorized (permitted to join the network).
❐ (Optional) An SG Client manager if you have mobile users or users in small branch
offices, where it might not be cost-justifiable to deploy an acceleration gateway.
Note: Peer refers to any ADN system, manager refers to the ADN system that
broadcasts route information to all ADN peers and controls peer access to the ADN
network, and node refers to all non-manager ADN peers. ADN managers can also act
as nodes on the network.
A backup ADN manager (optional, but recommended) can also be configured. The ADN
managers and the registered nodes periodically send keep-alive messages to each other. If
a node detects the primary ADN manager is not responding, the node automatically fails
over to the back-up ADN manager. The node repeatedly attempts to restore its connection
with the primary manager. After the primary ADN manager is responding to the node
again, the active routing connection of this node switches back to the primary manager.
If the ADN manager detects a node is not responding, the ADN manager removes the
node from the database and notifies all other nodes in the network to do the same.
If both the ADN manager and the backup ADN manager are unavailable, no further
routing advertisements are broadcast. In this case, routes already known by the peers
continue to be remembered and used.
15
Volume 5: Advanced Networking
You also can use the ADN manager and backup manager to authorize which peers are
allowed to advertise or retrieve route information to and from the ADN manager, and
whether plain connection requests to the ADN manager are accepted.
Connections to the ADN manager and backup manager are made at startup and kept
open as long as ADN is enabled. These connections are referred to as routing connections,
and are used to advertise configured server subnets and to receive routing table updates
from the ADN manager.
Note: Even if you use a transparent tunnel deployment where ADN nodes do not
require routing information, you must configure each ADN node and register it with
the ADN manager. If you secure the network (highly recommended), the ADN
manager is used to authorize ADN peers before they join the network.
Whenever the ADN manager receives a new advertisement from a node that is joining the
network, a route update is sent to all the appliances in the ADN optimization network
that have already established a routing connection; in addition, the current routing table is
updated. The ADN manager and backup manager can each listen on two ports: one
accepting the default plain (unsecured) routing connection requests and another
accepting secure routing connection requests. The plain listener can be shut down if
routing connections from all ADN nodes are secured.
To configure the ADN manager and backup ADN manager, see Section B: "Basic ADN
Setup" on page 21.
ADN Nodes
An ADN node is any SG appliance that is configured for ADN optimization and sends
routing information to the ADN manager and backup ADN manager. A node excludes
those appliances that are acting as ADN managers and backup ADN managers, although
the manager and backup manager can also participate as nodes in the network.
SG Client Manager
The SG Client typically connects to an SG appliance typically located in a data center. That
SG appliance provides the SG Client software to users, and maintains the software and the
client configuration on all clients in the ADN network. Only one SG Client Manager can
be used in the ADN network.
For information on using the SG Client and SG Manager, see Chapter 12: "Configuring
and Using the SG Client" on page 139.
16
Chapter 2: Configuring an Application Delivery Network
Transparent Connections
Transparent connections are used when the network is required to see the original
destination IP addresses and ports. This requires that each node be configured as an ADN
node and deployed in in-line mode or virtual in-line mode.
Note: Beyond setting up an ADN node in an in-line network and configuring the
ADN node to point to the ADN manager and backup manager, no additional effort is
required for transparent connections. If you use explicit connections, those
connections must be explicitly configured.
17
Volume 5: Advanced Networking
Explicit Connections
Explicit connections are used when maximum network control and granularity is needed.
Blue Coat supports two explicit connections deployments: explicit or explicit but
preserving the destination port. In the latter case, the destination port used is the original
destination port from the client’s request, such as port 80 for HTTP. The destination port is
not affected by the connection setting.
In both explicit deployments, the server subnets that are fronted by each peer must be
explicitly configured; the server subnets are then advertised to each ADN node.
To accelerate Internet traffic in an explicit ADN network, set up a specific ADN peer as the
Internet gateway. Typically, the Internet gateway is an ADN peer close to the enterprise’s
Internet access point.
Note: If multiple Internet gateways are available, each peer has its own preferred
Internet gateway to route all Internet subnets.
When an ADN peer is configured as an Internet gateway, all other ADN peers forward the
Internet traffic to this peer. The following logic is used by an ADN peer to determine if the
connection is destined to the Internet:
❐ If the destination address matches an advertised subnet from any of the ADN peers,
the connection is forwarded to that peer over the ADN tunnel.
❐ If the destination address matches one of the exempted subnets, the connection is not
forwarded over the ADN tunnel.
❐ If the destination address does not match an advertised subnet or an exempted
subnet, the connection is forwarded to an ADN peer that is designated as an Internet
gateway.
18
Chapter 2: Configuring an Application Delivery Network
ADN Security
ADN networks can and should be secured. You can limit access by:
❐ Authenticating and authorizing the ADN nodes that are allowed on the network and
prevent unauthorized nodes from participating.
❐ Securing ADN connections.
19
Volume 5: Advanced Networking
In secure ADN mode, full mutual authentication can be supported between the ADN
manager and the ADN nodes and among ADN communicating peers. If authorization is
enabled on the ADN manager, the peer proxy is authorized through an approval
mechanism by the ADN manager before joining the network. For more information on
managing appliance certificates, see Chapter 6: "Authenticating an SG Appliance".
20
Chapter 2: Configuring an Application Delivery Network
21
Volume 5: Advanced Networking
Note: You cannot select this option until you select the primary ADN manager and
apply the changes. The ADN manager does not exist until the changes are applied.
22
Chapter 2: Configuring an Application Delivery Network
23
Volume 5: Advanced Networking
To configure transparent load balancing with a dedicated Blue Coat appliance as the
decision maker:
❐ Deploy the load-balancing SG appliance in-line so that it can transparently intercept
all traffic.
❐ Enable load balancing on all nodes by going to Configuration > ADN > Tunneling > Load
Balancing, and selecting the Enable Load Balancing checkbox.
24
Chapter 2: Configuring an Application Delivery Network
❐ (Optional) Configure each box in the cluster with the same load-balancing group
name.
❐ On the Blue Coat appliance that’s acting as the dedicated load balancer, select Act as
load balancer only through the Configuration > ADN >Tunneling > Load Balancing tab.
❐ Put all ADN nodes into a connection forwarding cluster. For more information, see
Chapter 4: "TCP Connection Forwarding" on page 59.
To configure transparent load balancing with the nodes in the ADN cluster as the decision
makers:
25
Volume 5: Advanced Networking
❐ Enable load balancing on all nodes by going to Configuration > ADN > Tunneling > Load
Balancing, and selecting the Enable Load Balancing checkbox.
❐ (Optional) Set the same group name on all of the nodes in the cluster.
❐ Put all ADN nodes into a forwarding connection cluster. For more information, see
Chapter 4: "TCP Connection Forwarding" on page 59.
❐ Configure WCCP settings on all nodes. For more information, see Chapter 17:
"WCCP Settings" on page 239.
❐ Configure WCCP router settings. Review the vendor’s documentation for
information.
Note: Note: If client IP spoofing is desired, you must configure WCCP so that both
traffic from the Branch Appliance to the Origin Content Server and traffic from the
Origin Content Server to the Branch Appliance is redirected through WCCP. This
requires configuring WCCP on multiple interfaces on your router, or configuring "in/
out" rules. If specific ports are desired (rather than all ports), you must configure both
source-port and destination-port rules in two different service groups.
Note: You can also configure the exempt subnet capability through policy that
allows you to disable ADN tunnel for specific connections. For more information,
refer to Volume 10: Content Policy Language Guide.
26
Chapter 2: Configuring an Application Delivery Network
Added
Server
Subnet
2. Click Add.
3. In the Add IP/Subnet dialog, enter the following information and click OK when you
are done:
• IP / Subnet Prefix field: Enter either an IP address or an IP address and subnet in
Classless Inter-Domain Routing (CIDR) notation (for example, 192.168.0.1/16).
• Subnet Mask field: Use this field if you entered only an IP address in the preceding
field (in other words, if you used CIDR notation in the preceding field, you do not
need to enter a value in this field).
• To remove excluded subnets, click the subnets to remove and click Remove. You
must confirm the action.
• To clear all excluded subnets, requiring traffic from all IP addresses and subnets
to be tunneled, click Clear all. You must confirm the action.
4. (Optional) Repeat for additional routes.
27
Volume 5: Advanced Networking
2. Select the Enable this SG as an Internet Gateway for all subnets except the following
checkbox.
3. Click Add.
4. Add the IP/Subnet that must not be routed to Internet gateway(s); click OK.
5. (Optional) Repeat for additional subnets.
2. Select the checkbox for When a route is available, preserve the destination TCP port
number when connecting to the ADN peer.
28
Chapter 2: Configuring an Application Delivery Network
29
Volume 5: Advanced Networking
Whether you are using server subnets or an external load balancer, you must configure
server subnets. If you are using an external load balancer, you must also configure the
external load balancer with a VIP address and put the address in the Load Balancing tab.
Continue with the next procedures to configure explicit load balancing.
30
Chapter 2: Configuring an Application Delivery Network
Note: The VIP address is added from the Load Balancing tab of the App Delivery
Network menu, not the Advanced tab of the Network menu.
2. Select the Tell ADN peers to prefer transparent connections over advertised routes radio
button.
31
Volume 5: Advanced Networking
Note: If you only want secure routing connections to the ADN manager, an SSL
license is not required. Secure tunnel connections for applications such as CIFS,
MAPI, TCP Tunnel, HTTP, or HTTPS/SSL, are dependent upon an SSL license.
Note: If the device being configured for authentication has Internet access,
acquisition of the SG appliance certificate is automatic. If you use your own appliance
certificates and profile, or if the affected device does not have Internet access, manual
device authentication is required.
32
Chapter 2: Configuring an Application Delivery Network
After the device authentication has been set up, point the ADN manager and ADN
backup manager to the profile that is being used for authentication. Then enable
authorization for maximum security.
Note: You cannot enable device authorization before configuring the ADN manager
and backup ADN manager. You can, however, configure the ADN manager and
backup ADN manager and then, without pressing Apply, enable device authorization.
Then press Apply to save both tabs.
2a
2b
2c
2c
Note: The device ID is only used for security. The peer ID is the serial number.
c. To enable authorization, select the Validate ADN Peer Device IDs checkbox.
• If the primary or backup ADN manager is Self, the device ID is automatically
displayed.
• If the primary or backup ADN manager is a different system, click the
Retrieve Manager IDs button to see the device ID. Click Accept to add the
Manager device ID to the Authorization field.
Note: Authorization of devices is not complete until the devices have been
approved to be part of the network. For more information on approving devices, see
“ADN Node Authorization” on page 20.
33
Volume 5: Advanced Networking
Securing Connections
Use the Connection Security tab to set:
❐ Manager and Tunnel Listening Mode.
❐ Secure Outbound Connections.
❐ Manager-listening-mode: (Both) Listen for requests on two ports: plain and secure. If
your deployment requires a different ADN manager listening mode, you must
explicitly configure it. Other options available are:
• Secure Only.
• Plain Only.
• Plain Read-Only. This mode is recommended if your network uses SG clients.
❐ Tunnel-listening-mode: (Both) Listen for requests on two ports: plain and secure. Other
options are:
• Secure Only (Note that tunnel listening mode cannot be set to secure-only if SG
Clients exist on the ADN network).
• Plain Only.
34
Chapter 2: Configuring an Application Delivery Network
❐ Routing-only: Only routing connections are secured. Secure proxy connections bypass
ADN connections and go directly to the origin content sever.
❐ Secure Proxies: Routing connections and secure proxy connections are secured.
Note: Securing all outbound ADN connections should be done only if the platform
has sufficient capacity to handle the extra overhead.
The table below describes secure outbound behavior with various applications.
Application Connections
Secure-Outbound Routing
Setting Connections CIFS SSL Proxy SSL Proxy
Intercept Mode Tunnel Mode
35
Volume 5: Advanced Networking
The tunnel listening port is used only if there are explicit tunnel connections to
this ADN node using the non-preserve-dest-port mode.
❐ If secure-outbound is None on the ADN node and the ADN manager's listening mode
is not secure-only, the ADN node connects to the plain manager listening port and
immediately joins the ADN network.
❐ If the ADN node connects to the secure manager listening port, the ADN manager
extracts the device ID from connecting ADN node's appliance certificate and looks for
the device ID in its approved list of ADN nodes.
• If the device is on the approved list, a REQUEST-APPROVED response is sent,
followed by the route information, and the node joins the network.
• If the device is not on the approved list, the ADN manager adds the connecting
node's device ID to the pending-peers list and sends a REQUEST-PENDING
response. After the peer is moved to the Approved list by the administrator, a
REQUEST-APPROVED response is sent, followed by the route information, and the
node joins the network.
• If the Pending Peers option is not enabled and a peer is not on the approved list,
the ADN manager sends a REQUEST-DENIED response and closes the connection.
The connecting node closes the connection and updates its connection status.
• If a peer is deleted from the approved list, the ADN manager broadcasts a
REJECT-PEER to all nodes to delete this node and terminate any existing ADN
connections to it. No new connections are routed through the deleted ADN node.
To have the denied peer rejoin the ADN network, go to ADN > Config > General >
Reconnect to Managers.
Note: Device security must be enabled on all ADN peers you want to join the
network before you complete this procedure on the ADN manager and backup ADN
manager. For more information, see “Setting Device Security” on page 32.
36
Chapter 2: Configuring an Application Delivery Network
37
Volume 5: Advanced Networking
Approved/Pending Notes
❐ Approved lists on the primary and backup ADN managers are not automatically kept
in sync. You must approve peers on both the primary and backup ADN managers.
38
Chapter 2: Configuring an Application Delivery Network
Blue is traffic on
the WAN link/
ADN tunnel
Green is the
traffic delivered/
received on the
local network
Inbound Compression Gain represents traffic received from another peer. Outbound
Compression Gain represents the traffic sent to other peers.
The values include both compression and byte-cache gain.
39
Volume 5: Advanced Networking
❐ Bytes sent to the application: The total bytes sent to the client/server/application
proxy.
❐ Bytes received from the peer SG appliance: The bytes received on the ADN tunnel
connection from the peer at the other end of the WAN link. (This is compressed unless
byte caching is disabled).
❐ Bytes sent to the peer SG appliance: The bytes sent on the ADN tunnel connection to
the peer at the other end of the WAN Link. (This is compressed unless byte caching is
disabled).
❐ Duration: The lifetime of this connection.
40
Chapter 2: Configuring an Application Delivery Network
ADN Health Status Connected The ADN node is connected to the ADN OK
manager, ready to receive any route/peer
updates.
If a backup manager exists, this state
indicates the node is connected to both
Managers.
ADN Manager Status Not an ADN The ADN node is not an ADN manager. OK
manager
41
Volume 5: Advanced Networking
Optimization options include byte caching and gzip compression; byte caching and gzip
compression can be controlled separately for inbound and outbound traffic on the WAN.
By default, ADN routing and tunnel connection requests are unauthenticated and all
ADN protocol messaging and compressed application data are transferred in plaintext.
For maximum security, you can configure the ADN network to secure ADN routing and
tunnel connections using standard SSL protocol, which provides authentication, message
privacy, and message authenticity security services, regardless of the application traffic
that is being accelerated or tunneled.
For information on securing the network, see Section D: "Securing the ADN Network" on
page 32.
42
Chapter 2: Configuring an Application Delivery Network
2. Determine the behavior of the concentrator proxy when a branch proxy requests
client IP reflection (sending the client's IP address instead of the SG appliance IP
address to the upstream server).
This setting is based on whether the concentrator was installed in-line. If the
concentrator proxy is in-line and can do IP reflection, you can allow client IP address
reflection requests from clients. If not, set this option to either Reject the Request or
Allow the request but connect using a local IP to accept the requests but ignore the
client IP address and use a local IP address.
3. In the TCP Settings panel, enter the TCP window size to be used on ADN
optimization tunnel connections. This setting only needs to be changed for high
bandwidth and high delay environments, such as satellite links. The range is between
8 KB and 4 MB (8192 to 4194304), depending on your bandwidth and the round-trip
delay.
Note: If you know the bandwidth and roundtrip delay, you can compute the
value to use as, roughly, 2 * bandwidth * delay. For example, if the bandwidth of
the link is 8 Mbits/sec and the round-trip delay is 0.75 seconds:
window = 2 * 8 Mbits/sec * 0.75 sec = 12 Mbits = 1.5 Mbytes
The setting in this example would be 1500000 bytes. This number goes up as either
bandwidth or delay increases, and goes down as they decrease.
You can increase the window size based on this calculation but do not decrease the
window size if the result is less than 64K.
The window-size setting is a maximum value; the normal TCP/IP behaviors
adjust downward as necessary. Setting the window size to a lower value might
result in an artificially low throughput.
43
Volume 5: Advanced Networking
Note: If you enable this setting, do not duplicate any of the policy that exists at
the branch, since the branch settings still apply. Depending on the policy
involved, doing the processing twice can cause problems (such as doing URL
rewrite multiple times) or it might just be unnecessary, taking up valuable
resources.
44
Chapter 2: Configuring an Application Delivery Network
Note: The rank table can track peers that are using SGOS 5.1.3, but these peers
cannot dynamically re-size or delete their dictionary.
After the maximum available resources are reached, any peers that have not been
allocated a dictionary cannot use byte caching. If those peers have existing dictionaries,
the tunnels are downgraded to gzip compression only and the existing dictionary is
deleted.
A node can re-negotiate a new shared dictionary size with one of its peers, and the
dictionaries grow or shrink to their new resource levels. The final shared dictionary sizes
between two peers is the minimum dictionary size that each peer tries to negotiate. To
guarantee a minimum dictionary size, the value should be set on both peers. (See “To
manually resize byte cache dictionaries from the Statistics tab:” on page 46.)
When a peer joins the network, it is added to the peer ranking table. How much dictionary
space the peer is allocated depends:
❐ If the maximum amount of resources have already been reached, the new peer can do
gzip compression only.
❐ If the maximum amount of resources have not been reached:
• If no history exists for this peer, then the peer negotiates a default dictionary size
based on its maximum memory and maximum disk space.
• If history does exist for the peer and the peer's rank guarantees the peer a
dictionary, the peer is allocated a dictionary based on that history.
The peer ranking table is persistent across system reboots; the dictionaries themselves are
re-sized upon any of the following conditions:
❐ System restart.
❐ A full dictionary.
❐ If the dictionary size is set manually.
The re-ranking allows potentially unused dictionaries to be identified and removed,
freeing resources.
45
Volume 5: Advanced Networking
You can manually resize an ADN byte-caching dictionary in two places in the Blue Coat
appliance Management Console: From the Statistics > ADN History > Peer Dictionary Sizing
tab, or from the Configuration > ADN > Byte Caching tab. You might find the Statistics tab
easier to use, since you are not required to know the peer ID. Note, however, that only
peers that are online are displayed in the Statistics tab. If a peer is offline, Configuration >
ADN > Byte Caching can be used to configure manual dictionary size for any ADN peer.
To manually resize byte cache dictionaries from the Statistics tab, continue with the next
section. To manually resize byte cache dictionaries from the ADN tab, skip to “To
manually resize byte cache dictionaries from the Configuration > ADN > Byte Caching
tab:” on page 47.
2. The Peer Dictionary Sizing tab gives you statistics relevant to the byte cache
dictionary size of all peers on the network.
• Rank: The value of a peer’s dictionary. Manually-configured peers have a higher
rank than dynamically-configured peers.
• Peer ID: The serial number of the device.
• Peer IP: The IP address of the device.
• Byte Cache Score: The score of this peer relative to other peers. Score is based on
the value of the dictionary and is used to determine rank.
• Peer Traffic (GB/Day): The average amount of pre-byte-cache traffic per day.
• Fill Rate (GB/Day): The average amount of data put into the dictionary per day
over the last week.
46
Chapter 2: Configuring an Application Delivery Network
• Recommended Dict Size (GB): The dictionary size the Blue Coat appliance
recommends, based on the peer traffic over the last week.
• Actual Dict Size (GB): The actual size of the dictionary.
Click anywhere on the line of the device whose dictionary you want to re-size. The
Edit Peer dialog displays.
3. To select a dictionary size for the device, select the Manual Re-size radio button and
enter the value you want in megabytes.
4. Click OK to have the resizing take effect immediately
To manually resize byte cache dictionaries from the Configuration > ADN > Byte
Caching tab:
1. Select Configuration > ADN > Byte Caching.
47
Volume 5: Advanced Networking
Note: For detailed information on using these commands, refer to Volume 11:
Command Line Reference.
48
Chapter 2: Configuring an Application Delivery Network
49
Volume 5: Advanced Networking
Section I: Policy
Section I: Policy
The following gestures can be used for WAN optimization from either the VPM or CPL.
Note: For more information on using the VPM or CPL to configure policy, refer to
Volume 6: VPM and Advanced Policy or Volume 10: Content Policy Language Guide.
❐ adn.server(yes | no) (Note that this property overrides all other routing and
intercept decisions made by ADN based on configuration and routing information.)
❐ adn.server.optimize(yes | no)
❐ adn.server.optimize.inbound(yes | no)
❐ adn.server.optimize.outbound(yes | no)
❐ adn.server.optimize.byte-cache(yes | no)
❐ adn.server.optimize.inbound.byte-cache(yes | no)
❐ adn.server.optimize.outbound.byte-cache(yes | no)
❐ adn.server.optimize.compress(yes | no)
❐ adn.server.optimize.inbound.compress(yes | no)
❐ adn.server.optimize.outbound.compress(yes | no)
❐ adn.server.dscp
50
Chapter 2: Configuring an Application Delivery Network
Section I: Policy
51
Volume 5: Advanced Networking
52
Chapter 3: Attack Detection
The SGOS software can reduce the effects of distributed denial of service (DDoS)
attacks and port scanning, two of the most common virus infections.
A DDoS attack occurs when a pool of machines that have been infected with a DDoS-
type of virus attack a specific Web site. As the attack progresses, the target host shows
decreased responsiveness and often stops responding. Legitimate HTTP traffic is
unable to proceed because the infected system is waiting for a response from the target
host.
Port scanning involves viruses attempting to self-propagate to other machines by
arbitrarily attempting to connect to other hosts on the Internet. If the randomly selected
host is unavailable or behind a firewall or does not exist, the infected system continues
to wait for a response, thus denying legitimate HTTP traffic.
The SG appliance prevents attacks by limiting the number of simultaneous TCP
connections from each client IP address and either does not respond to connection
attempts from a client already at this limit or resets the connection. It also limits
connections to servers known to be overloaded.
You can configure attack detection for both clients and servers or server groups, such as
http://www.bluecoat.com. The client attack-detection configuration is used to control the
behavior of virus-infected machines behind the SG appliance. The server attack-
detection configuration is used when an administrator knows ahead of time that a
virus is set to attack a specific host.
This feature is only available through the CLI. You cannot use the Management
Console to enable attack detection.
This section discusses:
❐ “Configuring Attack-Detection Mode for the Client” on page 53
❐ “Configuring Attack-Detection Mode for a Server or Server Group” on page 57
53
Volume 5: Advanced Networking
Note: If you edit an existing client’s limits to a smaller value, the new value only applies
to new connections to that client. For example, if the old value was 10 simultaneous
connections and the new value is 5, existing connections above 5 are not dropped.
block | unblock ip_address Blocks a specific IP address for the number of minutes listed. If
[minutes] the optional minutes argument is omitted, the client is blocked
until explicitly unblocked. Unblock releases a specific IP address.
default block- drop | send- Indicates the behavior when clients are at the maximum number
action tcp-rst of connections or exceed the warning limit: drop the connections
that are over the limit or send TCP RST for connections over the
limit. The default is drop. This limit can be modified on a per-
client basis.
default failure- integer Indicates the maximum number of failed requests a client is
limit allowed before the proxy starts issuing warnings. Default is 50.
This limit can be modified on a per-client basis.
54
Chapter 3: Attack Detection
default unblock- minutes Indicates the amount of time a client is blocked at the network
time level when the client-warning-limit is exceeded. Time must be a
multiple of 10 minutes, up to a maximum of 1440. By default, the
client is blocked until explicitly unblocked. This limit can be
modified on a per-client basis.
default warning- integer Indicates the number of warnings sent to the client before the
limit client is blocked at the network level and the administrator is
notified. The default is 10; the maximum is 100. This limit can be
modified on a per-client basis.
block-action drop | send-tcp-rst Indicates the behavior when the client is at the maximum
number of connections: drop the connections that are over the
limit or send TCP RST for the connection over the limit. The
default is drop.
failure-limit integer Indicates the behavior when the specified client is at the
maximum number of connections: drop the connections that
are over the limit or send TCP RST for the connection over the
limit. The default is 50.
55
Volume 5: Advanced Networking
unblock-time minutes Indicates the amount of time a client is locked out at the
network level when the client-warning-limit is exceeded. Time
must be a multiple of 10 minutes, up to a maximum of 1440. By
default, the client is blocked until explicitly unblocked.
warning-limit integer Indicates the number of warnings sent to the client before the
client is locked out at the network level and the administrator
is notified. The default is 10; the maximum is 100.
56
Chapter 3: Attack Detection
add | remove hostname Adds or removes a server from this server group.
57
Volume 5: Advanced Networking
58
Chapter 4: TCP Connection Forwarding
This chapter describes how to configure the SG appliance to join peer clusters that
process requests in asymmetrically routed networks.
59
Volume 5: Advanced Networking
60
Chapter 4: TCP Connection Forwarding
61
Volume 5: Advanced Networking
Figure 4-4. ADN Transparent Tunnel load balancing with Connection Forwarding enabled
Load balancing is based on the IP address of the remote ADN peer. This assures that all
the traffic from a particular ADN peer to the local ADN cluster always goes to a specific
local SG appliance, thus eliminating the inefficiency of keeping dictionaries for that
remote peer on more than one local SG appliance.
The Blue Coat ADN solution is discussed in greater detail in Chapter 2: "Configuring an
Application Delivery Network" on page 13.
62
Chapter 4: TCP Connection Forwarding
63
Volume 5: Advanced Networking
3b
3a
2. From the Local IP drop-down list, select the IP address that is routing traffic to this SG
appliance.
Specify the port number (the default is 3030) that the SG appliance uses to
communicate with all peers, which includes listening and sending out connection
forwarding cluster control messages to all peers in the group. All peers in the group
must use the same port number (when connection forwarding is enabled, you cannot
change the port number).
3. Add the cluster peers:
a. Click Add.
b. In the Peer IPs field, enter the IP addresses of the other peers in the cluster
that this SG appliance is to communicate connection requests with.; click OK.
4. Select Enable Connection Forwarding.
5. Click Apply.
This SG appliance joins the peer cluster and immediately begins communicating with its
peers.
64
Chapter 4: TCP Connection Forwarding
Removing a Peer
A network change or other event might require you to remove a peer from the cluster.
Highlight a peer IP address and click Remove. The peer connection is terminated and all
connections associated with the peer are removed from the local system.
Note: A CLI command is available that allows you to disable a peer, which terminates
the communication with other peers, but does not remove the peer from the cluster. See
the next section.
65
Volume 5: Advanced Networking
66
Chapter 5: Bandwidth Management
Bandwidth management (BWM) allows you to classify, control, and limit the amount of
bandwidth used by different classes of network traffic flowing into or out of the SG
appliance. Network resource sharing (or link sharing) is accomplished by using a
bandwidth-management hierarchy where multiple traffic classes share available
bandwidth in a controlled manner.
Note: The SG appliance does not attempt to reserve any bandwidth on the network
links that it is attached to or otherwise guarantee that the available bandwidth on the
network can sustain any of the bandwidth limits which have been configured on it. The
SG appliance can only shape the various traffic flows passing through it, and prioritize
some flows over others according to its configuration.
By managing the bandwidth of specified classes of network traffic, you can accomplish
the following:
❐ Guarantee that certain traffic classes receive a specified minimum amount of
available bandwidth.
❐ Limit certain traffic classes to a specified maximum amount of bandwidth.
❐ Prioritize certain traffic classes to determine which classes have priority over
available bandwidth.
67
Volume 5: Advanced Networking
❐ Flow classification
This is the process of classifying traffic flows into bandwidth management classes
using policy rules. Policy rules can classify flows based on any criteria testable by
policy. You can create policy rules using either the Visual Policy Manager (VPM),
which is accessible through the Management Console, or by composing Content
Policy Language (CPL).
Note: For more information about using VPM to create policy rules, refer to Volume 6:
VPM and Advanced Policy. For information about composing CPL, refer to Volume 10:
Content Policy Language Guide.
Allocating Bandwidth
The process of defining bandwidth classes and grouping them into a bandwidth class
hierarchy is called bandwidth allocation. Bandwidth allocation is based on:
❐ the placement of classes in a hierarchy (the parent/child relationships).
❐ the priority level of classes in the same hierarchy.
❐ the minimum and/or maximum bandwidth setting of each class.
For example deployment scenarios, see “Bandwidth Allocation and VPM Examples” on
page 78.
Bandwidth Classes
To define a bandwidth class, you create the class, giving it a name meaningful to the
purpose for which you are creating it. You can configure the class as you create it or edit it
later. The available configuration settings are:
❐ Parent: Used to create a bandwidth-management hierarchy.
❐ Minimum Bandwidth: Minimum amount of bandwidth guaranteed for traffic in this
class.
❐ Maximum Bandwidth: Maximum amount of bandwidth allowed for traffic in this
class.
❐ Priority: Relative priority level among classes in the same hierarchy.
Parent Class
A parent class is a class that has children. When you create or configure a bandwidth class,
you can specify another class to be its parent (the parent class must already exist). Both
classes are now part of the same bandwidth-class hierarchy, and so are subject to the
hierarchy rules (see “Class Hierarchy Rules and Restrictions” on page 70).
Minimum Bandwidth
Setting a minimum for a bandwidth class guarantees that class receives at least that
amount of bandwidth, if the bandwidth is available. If multiple hierarchies are competing
for the same available bandwidth, or if the available bandwidth is not enough to cover the
minimum, bandwidth management is not be able to guarantee the minimums defined for
each class.
68
Chapter 5: Bandwidth Management
Note: The SG appliance does not attempt to reserve any bandwidth on the network links
that it is attached to or otherwise guarantee that the available bandwidth on the network
can be used to satisfy bandwidth class minimums. The SG appliance can only shape the
various traffic flows passing through it, and prioritize some flows over others according
to its configuration.
Maximum Bandwidth
Setting a maximum for a bandwidth class puts a limit on how much bandwidth is
available to that class. It does not matter how much bandwidth is available; a class can
never receive more bandwidth than its maximum.
To prevent a bandwidth class from using more than its maximum, the SG appliance inserts
delays before sending packets associated with that class until the bandwidth used is no
more than the specified maximum. This results in queues of packets (one per class)
waiting to be sent. These queues allow the SG appliance to use priority settings to
determine which packet is sent next. If no maximum bandwidth is set, every packet is sent
as soon as it arrives, so no queue is built and nothing can be prioritized.
Unlike minimums and priority levels, the maximum-bandwidth setting can purposely
slow down traffic. Unused bandwidth can go to waste with the maximum-bandwidth
setting, while the minimum-bandwidth settings and priority levels always distributes any
unused bandwidth as long as classes request it. However, priority levels are not
meaningful without a maximum somewhere in the hierarchy. If a hierarchy has no
maximums, any class in the hierarchy can request and receive any amount of bandwidth
regardless of its priority level.
Priority
When sharing excess bandwidth with classes in the same hierarchy, the class with the
highest priority gets the first opportunity to use excess bandwidth. When the high-
priority class uses all the bandwidth it needs or is allowed, the next class gets to use the
bandwidth, if any remains. If two classes in the same hierarchy have the same priority,
then excess bandwidth is shared in proportion to their maximum bandwidth setting.
Class Hierarchies
Bandwidth classes can be grouped together to form a class hierarchy. Creating a
bandwidth class allows you to allocate a certain portion of the available bandwidth to a
particular type of traffic. Putting that class into a bandwidth-class hierarchy with other
bandwidth classes allows you to specify the relationship among various bandwidth
classes for sharing available (unused) bandwidth.
The way bandwidth classes are grouped into the bandwidth hierarchy determines how
they share available bandwidth among themselves. You create a hierarchy so that a set of
traffic classes can share unused bandwidth. The hierarchy starts with a bandwidth class
you create to be the top-level parent. Then you can create other bandwidth classes to be
the children of the parent class, and those children can have children of their own.
To manage the bandwidth for any of these classes, some parent in the hierarchy must have
a maximum bandwidth setting. The classes below that parent can then be configured with
minimums and priority levels to determine how unused bandwidth is shared among
them. If none of the higher level classes have a maximum bandwidth value set, then
bandwidth flows from the parent to the child classes without limit. In that case,
minimums and priority levels are meaningless, because all classes get all the bandwidth
they need at all times. The bandwidth, in other words, is not being managed.
69
Volume 5: Advanced Networking
70
Chapter 5: Bandwidth Management
❐ Classes obtain bandwidth from their parents or siblings based on their priority
levels—the highest priority class gets to obtain what it needs first, until either its entire
requested bandwidth is satisfied or until it reaches its maximum. After that, the next
highest priority class gets to obtain bandwidth, and this continues until either all the
classes have obtained what they can or until the maximum bandwidth available to the
parent has been reached. The amount available to the parent can sometimes be less
than its maximum, because the parent must also participate in obtaining bandwidth in
this way with its own siblings and/or parent if it is not a top-level class.
Flow Classification
You can classify flows to BWM classes by writing policy rules that specify the bandwidth
class that a particular traffic flow belongs to. A typical transaction has four traffic flows:
1. Client inbound—Traffic flowing into the SG appliance from a client (the entity sending
a request, such as a client at a remote office linked to the appliance).
2. Server outbound—Traffic flowing out of the SG appliance to a server.
3. Server inbound—Traffic flowing back into the SG appliance from a server (the entity
responding to the request).
4. Client outbound—Traffic flowing back out of the SG appliance to a client.
The figure below shows the traffic flows between a client and server through the SG
appliance.
Some types of traffic can flow in all four directions. The following example describes
different scenarios that you might see with an HTTP request. A client sends a GET to the
SG appliance (client inbound). The SG appliance then forwards this GET to a server (server
outbound). The server responds to the SG appliance with the appropriate content (server
inbound), and then the appliance delivers this content to the client (client outbound).
Policy allows you to configure different classes for each of the four traffic flows. See
“Using Policy to Manage Bandwidth” on page 77 for information about classifying traffic
flows with policy.
71
Volume 5: Advanced Networking
Note: If you plan to manage the bandwidth of streaming media protocols (Windows
Media, Real Media, or QuickTime), you might want to use the streaming features instead
of the bandwidth management features described in this section. For most circumstances,
Blue Coat recommends that you use the streaming features to control streaming
bandwidth rather than the bandwidth management features. For information about the
differences between these two methods, refer to Volume 3: Web Communication Proxies.
An existing
parent class
3a
3b
3c
3d
3e
72
Chapter 5: Bandwidth Management
Note: You cannot delete a class that is referenced by another class or by the currently
installed policy. For instance, you cannot delete a class that is the parent of another class
or one that is used in an installed policy rule. If you attempt to do so, a message displays
explaining why this class cannot be deleted.
1. Select Configuration > Bandwidth Management > BWM Classes > Bandwidth Classes.
2. Highlight the class to delete and Delete.
3. Click Yes to delete the class.
4. Click Apply.
73
Volume 5: Advanced Networking
❐ Priority level
❐ Maximum bandwidth value
❐ Minimum bandwidth value
74
Chapter 5: Bandwidth Management
2. To view the statistics of child bandwidth classes, double-click the folder icon of the
parent class.
The child classes become visible. A second double-click closes the folder.
75
Volume 5: Advanced Networking
2. To view the statistics of child bandwidth classes, double-click the folder icon of the
parent class. A second double-click closes the folder.
Example
SGOS#(config bandwidth-management) view statistics http
Class Name: http
Parent: <none>
Minimum Bandwidth: unspecified
Maximum Bandwidth: unlimited
Priority: 0
Total Bytes: 0 bytes
Total Packets: 0 pkts
Dropped Packets: 0 pkts
Current Bandwidth: 0 kbps
Current Packet Rate: 0 pps
Queue Length: 0 bytes
Dropped Packets Total number of packets dropped (packets in the queue that are
dropped because the queue length is reached).
Queue Length Maximum length allowed for the queue of packets that lack
available bandwidth but are waiting for bandwidth to become
available.
76
Chapter 5: Bandwidth Management
2. To clear bandwidth management statistics for a particular class, enter the following
command at the prompt:
SGOS# clear-statistics bandwidth-management class bandwidth_class_name
CPL Triggers
You can use all of the CPL triggers for BWM classification (refer to Volume 10: Content
Policy Language Guide for information about using CPL triggers). Basing a bandwidth
decision on a trigger means that the decision does not take effect until after the
information needed to make that decision becomes available. For example, if you set the
CPL to trigger on the MIME type of the HTTP response, then the HTTP headers must be
retrieved from the OCS before a classification can occur. The decision to retrieve those
headers occurs too late to count any of the request bytes from the client or the bytes in the
HTTP response headers. However, the decision affects the bytes in the body of the HTTP
response and any bytes sent back to the client.
Supported CPL
Bandwidth class can be set with policy on each of these four traffic flows:
❐ limit_bandwidth.client.inbound(none | bwm_class)
❐ limit_bandwidth.client.outbound(none | bwm_class)
❐ limit_bandwidth.server.inbound(none | bwm_class)
❐ limit_bandwidth.server.outbound(none | bwm_class)
If you set policy to none, the traffic is unclassified and is not to be bandwidth-managed.
77
Volume 5: Advanced Networking
Each of the classes above has a maximum set at an amount equal to half of the total link
bandwidth for each office. A hierarchy does not exist in this scenario.
78
Chapter 5: Bandwidth Management
The administrator launches the VPM and creates a new Web Access Layer, naming it FTP/
HTTP Limitations. He selects the Client IP Address/Subnet object in the Source column,
filling in the IP address and mask of the subnet used by Office_A.
He selects a Combined Service Object in the Service column, naming it FTP/HTTP and
adding a Client Protocol for FTP and for HTTP.
79
Volume 5: Advanced Networking
In the Action column, he selects Manage Bandwidth, naming it Office_A and setting it to
manage the bandwidth of Office_A on the Client side in the Outbound direction.
He adds two more similar rules for the other two offices. He is able to reuse the same
Combined Service Object in the Service column, but must add new objects specific to each
office in the Source and Action columns. The order of the rules does not matter here,
because each office, and thus each rule, is distinct because of its IP address/subnet mask
configuration.
80
Chapter 5: Bandwidth Management
The administrator now has three separate hierarchies. In each one, bandwidth is limited
by the configuration of the parent class, and the two child classes are prioritized to
determine how they share any unused bandwidth. Because no minimums have been set,
the highest priority class has the first opportunity to use all of the available bandwidth;
whatever is left then goes to the next priority class.
Priority levels are only effective among the classes in the same hierarchy. This means that
the priority levels for the Office_A hierarchy do not affect the classes in the Office_B or
Office_C hierarchies.
He first edits each of the three VPM rules for the three offices. He edits each the Manage
Bandwidth objects, changing the name of the objects to Emp_A, Emp_B, and Emp_C and
changes the bandwidth class to the corresponding employee class.
81
Volume 5: Advanced Networking
Next, he creates three more rules for the CEO, moving them above the first three rules. For
the CEO rules, he selects the same combined FTP/HTTP object in the Service column; in the
Action column, he selects a Manage Bandwidth object configured for client side/outbound,
as before, but this time, he names the objects CEO_A, CEO_B, and CEO_C and selects the
corresponding CEO bandwidth class. In the Source column, he creates a Combined Source
Object, naming it for the CEO. He combines the Client IP/subnet object already created for
each office with a User object that he creates for the CEO.
The administrator places all three CEO rules above the employee rules, because the SG
appliance looks for the first rule that matches a given situation and ignores the remaining
rules. If he had placed the CEO rules below the employee rules, the SG appliance would
never get to the CEO rules because the CEO’s Web surfing client IP address matches both
the CEO rules and the employee rules, and the SG appliance would stop looking after the
first match. With the CEO rules placed first, the SG appliance applies the CEO rules to the
CEO’s Web surfing, and an employee’s Web surfing does not trigger the CEO rules and
instead skips ahead to the appropriate employee rule.
82
Chapter 5: Bandwidth Management
In the example illustrated above, employees and management combined are guaranteed a
total of 500 kbps. The CEO’s priority level has no effect until that minimum is satisfied.
This means that the CEO can only use 250 kbps of bandwidth if the rest of the staff are
using a total of 500 kbps. It also means that the CEO can use 750 kbps if no one else is
using bandwidth at the time. In fact, any of the classes can use 750 kbps if the other classes
use none.
Priority levels kick in after all of the minimums are satisfied. In this example, if the staff
requests more than 500 kbps, they can only receive it if the CEO is using less than 250
kbps. Now notice that the minimum setting for the staff is set on the parent class, Staff_A,
and not on the child classes, Emp_A or Mgmt_A. This means that the two child classes,
representing employees and management, share a minimum of 500 kbps. But they share it
based on their priority levels. This means that management has priority over employees.
The employees are only guaranteed a minimum if management is using less than 500
kbps.
83
Volume 5: Advanced Networking
He decides to leave the minimum on the parent class Staff_A and not to set a minimum for
the class Mgmt_A. This is okay, because the minimum of the parent class is available to its
children if the parent class does not use all of it, and the only way that the CEO can get
more than 250 kbps is if the employees and management combined use less than 500.
This last change does not require additional changes to policy; the administrator has
added a minimum to a class that he has already classified for traffic using policy.
In the above scenario, the class called Staff_A does not have traffic configured for it—it
was created to guarantee bandwidth minimums for its child classes. However, if it were
configured for traffic, it would have a practical minimum of 300 kbps. The practical
minimum of a parent class is equal to its assigned minimum bandwidth minus the
minimums of its children. In that case, if the parent class Staff_A used 300 kbps and the
child class Emp_A used 200 kbps, the child class Mgmt_A would not receive any
bandwidth unless the class CEO_A was using less than 250 kbps. Under those
circumstances, the administrator probably also needs to create a minimum for
management.
84
Chapter 5: Bandwidth Management
<proxy>
condition=student_mp3_weekday limit_bandwidth.server.inbound(mp3)
<proxy>
condition=http_posts limit_bandwidth.client.inbound(http_post)
85
Volume 5: Advanced Networking
SGOS#(config) bandwidth-management
SGOS#(config bandwidth-management) create pre-pop
SGOS#(config bandwidth-management) edit pre-pop
SGOS#(config bw-class pre-pop) max-bandwidth 50
CPL:
define condition prepop_weekday
content_management=yes weekday=1..5 hour=9..16
end condition
<proxy>
condition=prepop_weekday limit_bandwidth.server.inbound(pre-pop)
86
Chapter 6: Authenticating an SG Appliance
This chapter discusses device authentication, which is a mechanism that allows devices
to verify each others’ identity; devices that are authenticated can be configured to trust
only other authenticated devices.
Introduction
Device authentication is important in several situations:
❐ Securing the network. Devices that are authenticated have exchanged certification
information, verified each others’ identity and know which devices are trusted.
❐ Securing protocols. Many protocols require authentication at each end of the
connection before they are considered secure.
This chapter discusses the following topics:
❐ “SG Appliance Overview”
❐ “Appliance Certificates and Device Authentication Profiles” on page 88
❐ “Creating an Authentication Profile” on page 93
❐ “Related CLI Syntax to Manage Device Authentication” on page 95
❐ “Obtaining a Non Blue Coat Appliance Certificate” on page 93
❐ “Related CLI Syntax to Manage Device Authentication” on page 95
SG Appliance Overview
The Blue Coat implementation allows devices to be authenticated without sending
passwords over the network. Instead, a device is authenticated through certificates and
profiles that reference the certificates. Both the profile and the referenced certificate are
required for device authentication.
❐ Certificates: Certificates contain information about a specific device. Blue Coat runs
an Internet-accessible Certificate Authority (CA) for the purpose of issuing
appliance certificates to SGOS devices. You can also create your own appliance
certificates.
❐ Profiles: A profile is a collection of information used for device-to-device
authentication, including if the device has a certificate and if the certificates of other
devices should be verified. The built-in profile is called bluecoat-appliance-certificate
and references the appliance certificate on your SG appliance; you can create
additional profiles.
87
Volume 5: Advanced Networking
88
Chapter 6: Authenticating an SG Appliance
❐ Specification of how the device ID authorization data is extracted from the certificate.
The default is $(subject.CN).
❐ SSL cipher settings. The default is AES256-SHA.
Each Blue Coat appliance has an automatically-constructed profile called bluecoat-
appliance-certificate that can be used for device-to-device authentication. This profile
cannot be deleted or edited.
If you cannot use the built-in profile because, for example, you require a different cipher
suite or you are using your own appliance certificates, you must create a different profile,
and have that profile reference the keyring that contains your certificate.
Note: If you do not want to use peer verification, you can use the built-in passive-
attack-detection-only profile in place of the bluecoat-appliance-certificate profile.
This profile uses a self-signed certificate and disables the verify-peer option, so that
no authentication is done on the endpoints of the connection. The traffic is encrypted,
but is vulnerable to active attacks.
This profile can be used only when there is no threat of an active man-in-the-middle
attack. Like the bluecoat-appliance certificate profile, the passive-attack-detection-only
profile cannot be edited or deleted.
If you create your own profile, it must contain the same kind of information that is
contained in the Blue Coat profile. To create your own profile, skip to “Creating an
Authentication Profile” on page 93.
89
Volume 5: Advanced Networking
To generate a CSR:
1. Select Configuration > SSL > Appliance Certificates > Request Certificate.
2. Select Create CSR.
90
Chapter 6: Authenticating an SG Appliance
3. Copy the certificate request, including the certificate request signature. Be sure to
include the “Begin Certificate” and “End Certificate” statements, as well as the “Begin
CSR Signature” and “End CSR Signature” statements.
4. Click OK.
5. Go to the Blue Coat CA Server Website at https://abrca.bluecoat.com/sign-manual/
index.html.
91
Volume 5: Advanced Networking
3. Select the keyring that is used for device authentication. The keyring used by the
bluecoat-appliance-certificate profile is the appliance-key keyring.
4. Click Edit/View in the Keyrings tab.
92
Chapter 6: Authenticating an SG Appliance
Note: You cannot put a Blue Coat appliance certificate into a keyring you create
yourself.
93
Volume 5: Advanced Networking
3. Name: Give the profile a meaningful name. The only valid characters are
alphanumeric, the underscore, and hyphen, and the first character must be a letter.
4. Keyring: From the drop-down list, select the keyring you want to use for device
authentication.
Note: You must create a new keyring for device authentication if you do not use the
appliance-key keyring. The keyrings shipped with the Blue Coat SG are dedicated to
other purposes. For information on creating a new keyring, refer to Volume 4: Securing
the Blue Coat SG Appliance.
5. CCL: From the drop-down list, select the CA Certificate List you want to use.
6. Device ID extractor: The field describes how device ID information is extracted from a
presented certificate. The string contains references to the attributes of the subject or
issuer in the form $(subject.attr[.n]) or $(issuer.attr[.n]), where attr is the
short-form name of the attribute and n is the ordinal instance of that attribute,
counting from 1 when the subject is in LDAP (RFC 2253) order. If n is omitted, it is
assumed to be 1.
The default is $(subject.CN); many other subject attributes are recognized, among
them OU, O, L, ST, C, and DC.
7. Verify peer: This setting determines whether peer certificates are verified against the
CCL or whether client certificates are required.
8. Selected cipher suites: If you want to use a different cipher suite, click Edit cipher
suites.
94
Chapter 6: Authenticating an SG Appliance
9. Select the cipher suite or suites you want to use. Click Add to add the cipher suite to
the list of selected cipher suites. Cipher suites that you do not want to use should be
removed from the selected list.
10. Click OK when done.
95
Volume 5: Advanced Networking
96
Chapter 7: Configuring Failover
Using IP address failover, you can create a redundant network for any explicit proxy
configuration. If you require transparent proxy configuration, you can create software
bridges to use failover. For information on creating software bridges, refer to Volume 1:
Getting Started.
Note: If you use the Pass-Through adapter for transparent proxy, you must create a
software bridge rather than configuring failover. For information on using the Pass-
Through adapter, refer to Volume 1: Getting Started.
Using a pool of IP addresses to provide redundancy and load balancing, Blue Coat
migrates these IP addresses among a group of machines.
This chapter discusses:
❐ “About Failover”
❐ “Configuring Failover” on page 98
About Failover
Failover allows a second machine to take over if a first machine fails, providing
redundancy to the network through a master/slave relationship. In normal operations,
the master (the machine whose IP address matches the group name) owns the address.
The master sends keepalive messages (advertisements) to the slaves. If the slaves do not
receive advertisements at the specified interval, the slave with the highest configured
priority takes over for the master. When the master comes back online, the master takes
over from the slave again.
The Blue Coat failover implementation resembles the Virtual Router Redundancy
Protocol (VRRP) with the following exceptions:
❐ A configurable IP multicast address is the destination of the advertisements.
❐ The advertisement interval is included in protocol messages and is learned by the
slaves.
❐ A virtual router identifier (VRID) is not used.
❐ Virtual MAC addresses are not used.
❐ MD5 is used for authentication at the application level.
Masters are elected, based on the following factors:
❐ If the failover mechanism is configured for a physical IP address, the machine
owning the physical address have the highest priority. This is not configurable.
❐ If a machine is configured as a master using a virtual IP address, the master has a
priority that is higher than the slaves.
When a slave takes over because the master fails, an event is logged in the event log.
No e-mail notification is sent.
97
Volume 5: Advanced Networking
Configuring Failover
Before you begin, ensure that software bridges already exist. For information on
configuring bridges, refer to Volume 1: Getting Started.
You also must decide which machine is the master and which machines are the slaves, and
whether you want to configure explicit proxy or transparent proxy network.
When configuring the group, the master and all the systems in the group must have
exactly the same failover configuration except for priority, which is used to determine the
rank of the slave machines. If no priority is set, a default priority of 100 is used. If two
appliances have equal priority, the one with the highest physical address ranks higher.
To configure failover:
1. Select Configuration > Network > Advanced > Failover.
2. Click New.
3f
3a
3b
3c
3d
3e
98
Chapter 7: Configuring Failover
Note: Class D IP addresses (224 to 239) are reserved for multicast. A Class D IP
address has a first bit value of 1, second bit value of 1, third bit value of 1, and
fourth bit value of 0. The other 28 bits identify the group of computers that
receive the multicast message.
c. Relative Priority refers to a range from 1-255 that is assigned to systems in the
group. 255 is reserved for the system whose failover group ID equals the real
IP address. (Optional) Master identifies the system with the highest priority
(the priority value is greyed out).
d. (Optional) Advertisement Interval refers to the length of time between
advertisements sent by the group master. The default is 40 seconds. If the
group master fails, the slave with the highest priority takes over (after
approximately three times the interval value). The failover time of the group
is controlled by setting this value.
e. (Optional, but recommended) Group Secret refers to a password shared only
with the group.
f. Select enabled.
g. Click OK.
4. Click Apply to commit the changes to the SG appliance.
99
Volume 5: Advanced Networking
100
Chapter 8: Configuring the Upstream Network Environment
To fill requests, the SG appliance must interact with both the local network and with
the upstream network environment.
This chapter includes the following sections:
❐ Section A: "Overview" on page 102
❐ Section B: "About Forwarding" on page 103
❐ Section C: "Configuring Forwarding" on page 106
❐ Section D: "Using Forwarding Directives to Create an Installable List" on page 114
101
Volume 5: Advanced Networking
Section A: Overview
Section A: Overview
To control upstream interaction, the SG appliance supports:
❐ The SG appliance forwarding system—Allows you to define the hosts and groups of
hosts to which client requests can be redirected. Those hosts can be servers or proxies.
Rules to redirect requests are set up in policy.
❐ SOCKS gateways—SOCKS servers provide application-level firewall protection for an
enterprise. The SOCKS protocol provides a generic way to proxy HTTP and other
protocols. For information on configuring SOCKS gateways, see Chapter 13: "SOCKS
Gateway Configuration" on page 183.
❐ ICP—ICP handles ICP queries from other caching devices looking for cached data. The
SG appliance also can use ICP. For information on configuring ICP, see Chapter 9:
"Internet Caching Protocol (ICP) Configuration" on page 121.
102
Chapter 8: Configuring the Upstream Network Environment
Note: The SG appliance forwarding system directly supports the forwarding of HTTP,
HTTPS, FTP, Windows Media, RTSP, Telnet, and TCP tunnels.
❐ Use the client IP address to determine which group member was last used. When the
same client IP sends another request, the host makes the connection is made to that
group member.
103
Volume 5: Advanced Networking
❐ Place a cookie in the response to the client. When the client makes further requests, the
cookie data is used to determine which group member the client last used. The host
makes the connection to that group member.
❐ For HTTPS, extract the SSL session ID name from the connection information. The host
uses the session ID in place of a cookie or client IP address to determine which group
member was last used. The host makes the connection to that group member.
If host affinity is configured, the system checks host affinity first to see if the request
comes from a known client. If this is a first connection, the load-balancing algorithm
selects the group member to make the connection. Host affinity records the result of the
load balancing and uses it if that client connects again.
Host affinity does not make a connection to a host that health checks report is down;
instead, if host affinity breaks, the load-balancing algorithm selects a group member that
is healthy and re-establishes affinity on that working group member.
Note: You might find it necessary to disable caching for traffic sent to the load-balanced
groups (or hosts if DNS hides a group under one entry) to prevent copies of customized
Web pages being served to a different user.
It is not always necessary to disable caching; for example, load balancing can be used
without host affinity or without disabling caching to distribute load among several
proxies.
However, if caching is enabled for traffic going through load balancing, retrieval of
updated content by the cache is done according to load balancing rules; the cache does not
support host affinity and ignores it if enabled.
104
Chapter 8: Configuring the Upstream Network Environment
105
Volume 5: Advanced Networking
106
Chapter 8: Configuring the Upstream Network Environment
Note: The host alias cannot be a CPL keyword, such as no, default, or
forward.
b. In the Host field, give the name of the host domain or its IP address.
c. Define the host type by selecting either the Proxy or Server radio button.
Terminated HTTPS, TCP tunnels, and Telnet can be forwarded to a server
only; they cannot be forwarded to a proxy. Server specifies to use the relative
path for URLs in the HTTP header because the next hop is a Web server, not a
proxy server. The default is Proxy.
d. Select the port you want to use.
Port 80 is the default for HTTP. The rest of the host types default to their
appropriate Internet default port, except TCP tunnels, which have no default and
for which a port must be specified.
e. In the Load Balancing and Host Affinity section, select a load-balancing
method from the drop-down list. Global default (configured on the
Configuration > Forwarding > Global Defaults tab), sets the default for all
forwarding hosts on the system. You can also specify the load-balancing
method for this system: Least Connections or Round Robin, or you can disable
load balancing by selecting None.
f. In the Host affinity methods drop-down list (see Table 8-1, “Host Affinity
Methods,” on page 104), select the method you want to use.
4. Click OK.
5. Click Apply to commit the changes to the SG appliance.
107
Volume 5: Advanced Networking
Note: The group alias cannot be a CPL keyword, such as no, default, or
forward.
4. To add members to a group, highlight the hosts you want grouped and click Add. You
can also create a group with no members.
5. In the Load Balancing and Host Affinity section, select the load-balancing method from
the drop-down list. Global default (configured on the Configuration > Forwarding >
Global Defaults tab), are the defaults that were set for all forwarding groups on the
system. To specify the load-balancing method for this system, select Least
Connections, Round Robin, Domain Hash, URL Hash, or you can disable load balancing
by selecting None.
6. In the Host affinity methods drop-down list (see Table 8-1, “Host Affinity Methods,”
on page 104), select the method you want to use.
7. Click OK.
108
Chapter 8: Configuring the Upstream Network Environment
109
Volume 5: Advanced Networking
a. Load-balancing methods:
• Forwarding hosts: Specify the load-balancing method for all forwarding hosts
unless their configuration specifically overwrites the global settings. You can
choose Least Connections or Round Robin, or you can disable load balancing
by selecting None. Round Robin is specified by default.
• Forwarding groups: Specify the load-balancing method for all forwarding
groups unless their configuration specifically overwrites the global settings.
You can choose to do a domain hash or a URL hash. You can also select Least
Connections or Round Robin, or disable load balancing by selecting None.
Round Robin is specified by default.
b. In the Global Host Affinity methods (see Table 8-1, “Host Affinity Methods,”
on page 104), select the method you want to use.
c. Enter the Host Affinity Timeout interval, the amount of time a user's IP
address, SSL ID, or cookie remains valid after its most recent use. The default
is 30 minutes, meaning that the IP address, SSL ID or cookie must be used
once every 30 minutes to restart the timeout period.
Note: Creating the default sequence through the CLI is a legacy feature. You can set up
sequences by using policy alone. The default sequence (if present) is applied only if no
applicable forwarding gesture is in policy.
For information on using VPM, refer to Volume 6: VPM and Advanced Policy; for
information on using CPL, refer to Volume 10: Content Policy Language Guide. For
information on using forwarding with policy, see Appendix B: "Using Policy to Manage
Forwarding" on page 263.
The default sequence (and any sequence specified in policy) works by allowing healthy
hosts to take over for an unhealthy host (one that is failing its DNS Resolution or its health
check). If more than one member is in the sequence, the sequence specifies the order of
failover, with the second host taking over for the first host, the third taking over for the
second, and so on.
Note: In normal circumstances, only the first member of the sequence is ever used. Traffic
is forwarded to the first member of the sequence until it fails, then traffic is sent to the
second member of list until it fails or the first member becomes healthy again, and so on.
110
Chapter 8: Configuring the Upstream Network Environment
Note: Any host or group in the default sequence is considered in use by policy. As a
result, if you try to delete a host or group while it is in the default sequence, you
receive an error message. You must remove the host/group from the sequence first,
then delete the host or group.
3. Click Promote or Demote to change the order of the hosts in the failover sequence.
4. Click Apply to commit the changes to the SG appliance.
111
Volume 5: Advanced Networking
112
Chapter 8: Configuring the Upstream Network Environment
Statistics
To view forwarding statistics, select Statistics > Advanced > Forwarding.
113
Volume 5: Advanced Networking
114
Chapter 8: Configuring the Upstream Network Environment
tcp =port If you choose to add a TCP protocol, a TCP port must
be specified.
TCP protocols are not allowed if the host is a proxy.
ssl-verify- =yes | =no Sets SSL to specify that the SG appliance checks the CA
server certificate of the upstream server.
The default for ssl-verify-server is yes. This can
be overridden in the SSL layer in policy.
To disable this feature, you must specify ssl-verify-
server=no in the installable list or CLI. In other
words, you can configure ssl-verify-server=yes
in three ways: do nothing (yes is the default), specify
ssl-verify-server=no, or specify ssl-verify-
server=yes.
group =group_name Specifies the group (or server farm or group of proxies)
to which this host belongs. If this is the first mention of
the group group_name then that group is
automatically created with this host as its first member.
The SG appliance uses load balancing to evenly
distribute forwarding requests to the origin servers or
group of proxies.
server | proxy server specifies to use the relative path for URLs in
the HTTP header because the next hop is a Web server,
not a proxy server. The default is proxy.
Example
fwd_host www.bluecoat1.com 10.25.36.48 ssl-verify-server=no
group=bluecoat
115
Volume 5: Advanced Networking
Table 8-4. Commands to Set Fail Open/Closed and Host Timeout Values
integrated_host_timeout minutes An OCS that has been added to the health check
list is called an integrated host. The host ages out
after being idle for the specified time.
Examples
fwd_fail open
integrated_host_timeout 90
116
Chapter 8: Configuring the Upstream Network Environment
load_balance {none | domain-hash | url- If you use group for load balancing,
group hash | round-robin | you can set the suboption to none or
least-connections} choose another method. If you do not
[group_alias] specify a group, the settings apply as the
default for all groups.
load_balance {none | round-robin | If you use host for load balancing, you
host least-connections} can set the suboption to none or choose
[host_alias] another method. If you do not specify a
host, the settings apply as the default for
all hosts.
Example
load_balance host least_connections
117
Volume 5: Advanced Networking
Example
host_affinity ssl_method 10.25.36.48
host_affinity timeout 5
A default failover sequence works by allowing healthy hosts to take over for an unhealthy
host (one that is failing its DNS resolution or its health check). The sequence specifies the
order of failover, with the second host taking over for the first host, the third taking over
for the second, and so on).
If all hosts are unhealthy, the operation fails either open or closed, depending upon your
settings.
This configuration is generally created and managed through policy. If no forwarding
policy applies, you can create a default sequence through the CLI. This single default
sequence consists of a single default host (or group) plus one or more hosts to use if the
preceding ones are unhealthy.
The syntax is:
sequence alias_list
where alias_list is a space-separated list of one or more forwarding host and
group aliases.
Example
sequence bluecoat
118
Chapter 8: Configuring the Upstream Network Environment
Note: During the time that a forwarding installable list is being compiled and installed,
forwarding might not be available. Any transactions that come into the SG appliance
during this time might not be forwarded properly.
Installation of forwarding installable lists should be done outside peak traffic times.
Note: A message is written to the event log when you install a list through the SGOS
software.
• Remote URL:
Enter the fully-qualified URL, including the filename, where the installable list is
located. To view the file before installing it, click View. Click Install. Examine the
installation status that displays; click OK.
• Local File:
Click Browse to display the Local File Browse window. Browse for the installable
list file on the local system. Open it and click Install. When the installation is
complete, a results window opens. View the results, close the window, click Close.
• Text Editor:
The current configuration is displayed in installable list format. You can
customize it or delete it and create your own. Click Install. When the installation
is complete, a results window opens. View the results, close the window,
click Close.
119
Volume 5: Advanced Networking
Note: The Management Console text editor is a way to enter an installable list
for forwarding. It is not a way to enter CLI commands. The directives are
understood only by the installable list parser for forwarding.
3. Click Apply.
Note: You can create forwarding settings using the CLI #inline forwarding command.
You can use any of the forwarding directives.
For more information on using inline commands, refer toVolume 11: Command Line
Reference.
Note: : Any host or group in the default sequence (or the DRTR service configuration) is
considered in use by policy. As a result, if you try to delete a host or group while it is in
the default sequence or DRTR service configuration, you will receive an error message.
You must remove the host/group from the sequence or service first, then delete.
120
Chapter 9: Internet Caching Protocol (ICP) Configuration
Note: The SG appliance (assuming ICP is configured) does ICP queries only if no
forwarding host or SOCKS gateway is identified as an upstream target. If ICP is used by
the appliance, it prompts other cache devices for the item, and upon a positive response
re-directs the upstream request to that cache device instead of the content origin server.
Only use ICP if you have ICP hosts available or to have the SG appliance support
requests from other ICP hosts.
By default, the ICP protocol requires the requesting host to wait up to two seconds for
all ICP hosts to respond to the request for an object (the time is configurable).
If the ICP service is configured and running, the service is used if no forwarding or
SOCKS gateway target was specified. In other words, the policy rule icp(yes) is the
default, assuming that the ICP service is available. You can disable ICP with the policy
rule icp(no) to control ICP queries for requests.
Configuring ICP
An ICP hierarchy is comprised of a group of caches, with defined parent and sibling
relationships. A cache parent is one that can return the object if it is in the cache, or
request the object from the source on behalf of the requester if the object is not in the
cache. A cache sibling is a device that can only return the object if it is in the cache. One
cache acting as a parent can also act as a sibling to other cache devices.
❐ When an object is not cached, the cache device sends an ICP query to its neighbors
(parents and siblings) to see if any of its peers holds the object.
❐ Each neighbor that holds the requested object returns an ICP_HIT reply.
❐ Each neighbor that does not hold the object returns an ICP_MISS reply.
Based on the responses, the cache can determine where to request the object: from one
of its neighbors or from the source. If an ICP_HIT reply is received, the request is sent to
the host that returned the first reply. If no ICP_HIT reply is received, the request is
forwarded to the first parent that replied. If no parents respond or are configured, the
request is made directly to the source.
121
Volume 5: Advanced Networking
icp_host The icp_host directive describes cache peers in the Names the ICP hosts. See
hierarchy. There should be one entry for each SG “Naming the IP Hosts” on
appliance you want to use. page 123.
icp_access_ domain The icp_access_domain directive is used to control Restricts access. See
which ICP queries are accepted. The “Restricting Access” on
icp_access_domain directive requires a reverse DNS page 123.
lookup of each ICP query to validate the IP address.
icp_port The icp_port directive sets the port the SG appliance Connects to other ICP hosts.
uses to listen for ICP requests. The default port is 3130. See “Connecting to Other
If you set the port to 0, ICP is disabled. ICP Hosts” on page 124.
neighbor_timeout The neighbor_timeout directive sets the number of Connects to other ICP hosts.
seconds the SG appliance waits for ICP replies. When See “Connecting to Other
the cache device sends an ICP request, it waits for all ICP Hosts” on page 124.
hosts to reply or for the neighbor_timeout to expire.
The default timeout is two seconds.
icp_failcount The icp_failcount directive sets the number of Connects to other ICP hosts.
consecutive failures the cache device can receive before See “Connecting to Other
considering the ICP host as failed. By default, the ICP ICP Hosts” on page 124.
failure count is set to 20. Each time a request fails, the
failure count is incremented. When a request succeeds,
the failure count is reset to zero.
http_failcount The http_failcount directive sets the number of Connects to other ICP hosts.
consecutive failures the cache device can receive before See “Connecting to Other
considering the HTTP host as failed. By default, the ICP Hosts” on page 124.
HTTP failure count is set to five. The failure count
increments each time a request fails. When a request
succeeds, the failure count is reset to zero. When an
HTTP host fails, the cache device waits five minutes
before attempting to use it again as a forwarding target.
If the next request fails, the cache device continues to
wait five minutes between attempts until the cache
becomes available.
host_fail_notify The host_fail_notify directive tells the cache Connects to other ICP hosts.
device to send event notification e-mail when a connect See “Connecting to Other
fails persistently. ICP Hosts” on page 124.
host_recover_ The host_recover_notify directive tells the cache Connects to other ICP hosts.
notify device to send event notification e-mail when a failed See “Connecting to Other
host recovers. ICP Hosts” on page 124.
122
Chapter 9: Internet Caching Protocol (ICP) Configuration
peertype {parent | Relationship of the SG appliance to the cache device you are configuring.
sibling}
HTTPport TCP port where the SG appliance accepts HTTP requests. The common HTTP
port is 80 or 8080.
ICPport UDP port where the SG appliance accepts ICP requests. The common ICP port
is 3130.
default If specified, designates a SG host parent to be the default ICP parent. If no ICP
reply is received, all requests are forwarded to the default parent.
backup If specified, designates the cache device host parent to be the backup default
ICP parent. If the default parent is not available, the cache device uses the
backup default parent.
feeder If specified, designates the SG host sibling as a feeder-type host, using ICP
request loops to populate the appliance.
The following are sample icp_host directives that can be entered into the ICP
configuration:
; Define ICP parent and sibling hosts.
icp_host cm1.bluecoat.com parent 8080 3130 default
icp_host cm2.bluecoat.com sibling 8080 3130
icp_host cm3.bluecoat.com sibling 8080 3130
icp_host cm4.bluecoat.com sibling 8080 3130
icp_host cm5.bluecoat.com parent 8080 3130
Restricting Access
You can restrict access to SG appliances acting as caches by other ICP hosts using the
icp_access_domain and icp_access_ip directives. By default, when ICP is configured,
all ICP hosts are allowed access. You should deny access to all domains other than the ICP
hosts you want to use.
icp_access_domain Directive
The icp_access_domain directive defines which hosts can request objects from the Web
cache using ICP. The default action is to allow all requests. When you use
icp_access_domain, each ICP query requires a reverse DNS lookup to validate the IP
address. Depending on the number of ICP requests, these lookups can consume SG
appliance resources.
icp_access_domain {allow | deny} domain
123
Volume 5: Advanced Networking
allow | deny Allows or denies ICP queries from neighbors that match the domain
specification.
domain The domain to match. All ICP queries from neighbors that match the
specified domain are handled by the host. The special domain of all
defines the default action when there is no domain match.
The following are sample icp_access_domain directives to be entered into the
ICP configuration:
; allow ICP access to this Blue Coat Systems SG Appliance from the
; bluecoat.com domain
icp_access_domain allow bluecoat.com
icp_access_domain deny all
; the deny all option should always be specified to deny all other
; domains
icp_access_ip Directive
The icp_access_ip directive works like the icp_access_domain command, except that
you can specify an IP address and subnet mask rather than a domain. The following
describes the parameters for the icp_access_ip command:
icp_access_ip {allow | deny} subnet mask
allow | deny Allow or deny ICP queries from neighbors that match the address
specification.
address/subnet mask The address and subnet mask to match. All ICP queries that match
the specified address are handled by the ICP host. The special
address of 0.0.0.0 defines the default action when there is no
address match.
The following are sample icp_access_ip directives to be entered into the ICP
configuration:
; allow ICP access to this Blue Coat Systems SG Appliance from the
local subnet
icp_access_ip allow 192.168.10.0/255.255.255.0
icp_access_ip deny 10.25.36.47
; the deny all option should always be specified to deny all other
domains
124
Chapter 9: Internet Caching Protocol (ICP) Configuration
Directive Description
icp_port The default port is 3130. If you set the port to 0, ICP is disabled.
neighbor_timeout When the cache device sends an ICP request, it waits for all hosts to
reply or for the neighbor_timeout to expire. The default timeout is
two seconds.
http_failcount By default, the HTTP failure count is set to five. The failure count
increments each time a request fails. When a request succeeds, the
failure count resets to zero. When an HTTP host fails, the cache device
waits five minutes before attempting to use it again as a forwarding
target.
icp_failcount By default, the ICP failure count is set to 20. Each time a request fails,
the failure count is incremented. When a request succeeds, the failure
count is reset to zero.
host_fail_notify on tells the cache to send event notification e-mail when a connect fails
persistently; off disables this setting.
host_recover_ on tells the cache to send event notification e-mail when a failed host
notify recovers; off disables this setting.
125
Volume 5: Advanced Networking
• Text Editor:
The current configuration is displayed in installable list format. You can
customize it or delete it and create your own. Click Install. When the installation is
complete, a results window opens. View the results, close the window, click Close.
3. Click Apply to commit the changes to the SG appliance.
Note: You can create ICP settings using the CLI inline commands.
For more information on using inline commands, refer to Volume 11: Command Line
Reference.
Enabling ICP
Before ICP can be used in the SG environment:
❐ ICP must be running
❐ At least one forwarding host must be configured
ICP can be enabled or disabled through the policy rule icp.The default is icp(yes). You
can disable ICP with the policy rule icp(no) to control ICP queries for requests.
126
Chapter 10: Using RIP
The Routing Information Protocol (RIP) is designed to select the fastest route to a
destination. RIP support is built into the SG appliance, and is configured by created and
installing an RIP configuration text file onto the device.
The Blue Coat RIP implementation also supports advertising default gateways. Default
routes added by RIP are treated the same as the static default routes; that is, the default
route load balancing schemes apply to the default routes from RIP as well.
This chapter discusses:
❐ “Installing RIP Configuration Files” on page 127
❐ “Configuring Advertising Default Routes” on page 128
❐ “RIP Commands” on page 129
❐ “RIP Parameters” on page 130
❐ “SG-Specific RIP Parameters” on page 131
❐ “Using Passwords with RIP” on page 131
Note: When entering RIP settings that affect current settings (for example, when
switching from ripv1 to ripv2), disable RIP before you change the settings; re-enable
RIP when you have finished.
127
Volume 5: Advanced Networking
3. In the Install RIP Setting from the drop-down list, select the method used to install the
routing table; click Install.
• Remote URL:
Enter the fully-qualified URL, including the filename, where the routing table is
located. To view the file before installing it, click View. Click Install. To view the
installation results, click Results; close the window when you are finished. Click
OK.
• Local File:
Click Browse to display the Local File Browse window. Browse for the file on the
local system. Open it and click Install. When the installation is complete, a results
window opens. View the results and close the window.
• Text Editor:
The current configuration is displayed in installable list format. You can
customize it or delete it and create your own. Click Install. When the installation is
complete, a results window opens. View the results, close the window, and click
OK.
128
Chapter 10: Using RIP
RIP Commands
You can place any of the commands below into a Routing Information Protocol (RIP)
configuration text file. You cannot edit a RIP file through the command line, but you can
overwrite a RIP file using the inline rip-settings command.
Once the file is complete, place it on an HTTP or FTP server accessible to the SG appliance
and download it.
net
net Nname[/mask] gateway Gname metric Value {passive | active |
external}
Parameters Description
Value The hop count to the destination host or network. A net Nname/32
specification is equivalent to the host Hname command.
host
host Hname gateway Gname metric Value {passive | active | external}
Parameters Description
Value The hop count to the destination host or network. A net Nname/32
specification is equivalent to the host Hname command.
129
Volume 5: Advanced Networking
RIP Parameters
Lines that do not start with net or host commands must consist of one or more of the
following parameter settings, separated by commas or blank spaces:
Parameters Description
if=[0|1|2|3] Specifies that the other parameters on the line apply to the interface numbered 0,1,2,
or 3 in SGOS terms.
passwd=XXX Specifies an RIPv2 password included on all RIPv2 responses sent and checked on all
RIPv2 responses received. The password must not contain any blanks, tab characters,
commas or ‘#’ characters.
passive Marks the interface to not be advertised in updates sent through other interfaces, and
turns off all RIP and router discovery through the interface.
ripv2_out Turns off RIPv1 output and causes RIPv2 advertisements to be multicast when
possible.
no_rdisc Disables the Internet Router Discovery Protocol. This parameter is set by default.
send_solicit Specifies that Router Discovery solicitations should be sent, even on point-to-point
links, which by default only listen to Router Discovery messages.
rdisc_adv Specifies that Router Discovery Advertisements should be sent, even on point-to-
point links, which by default only listen to Router Discovery messages.
bcast_rdisc Specifies that Router Discovery packets should be broadcast instead of multicast.
rdisc_interval=N Sets the nominal interval with which Router Discovery Advertisements are
transmitted to N seconds and their lifetime to 3*N.
trust_gateway=rname Causes RIP packets from that router and other routers named in other trust_gateway
keywords to be accept, and packets from other routers to be ignored.
redirect_ok Causes RIP to allow ICMP Redirect messages when the system is acting as a router
and forwarding packets. Otherwise, ICMP Redirect messages are overridden.
130
Chapter 10: Using RIP
Parameters Description
supply_routing_info -s option:
-or- Supplying this option forces routers to supply routing
information whether it is acting as an Internetwork router or not.
advertise_routes
This is the default if multiple network interfaces are present or if a
point-to-point link is in use.
-g option:
This flag is used on Internetwork routers to offer a route to the
`default' destination. This is typically used on a gateway to the
Internet, or on a gateway that uses another routing protocol
whose routes are not reported to other local routers.
-h option:
Suppress_extra_host_routes advertise_host_route
-m option:
Advertise_host_route on multi-homed hosts
-A option:
Ignore_authentication //
no_supply_ -q option:
routing_info opposite of -s.
no_rip_out Disables the transmission of all RIP packets. This setting is the
default.
131
Volume 5: Advanced Networking
132
Chapter 11: Configuring the SG Appliance as a Session
Monitor
You can configure the SGOS software to monitor RADIUS accounting messages and to
maintain a session table based on the information in these messages. The session table
can then be used for logging or authentication.
You can also, optionally, configure multiple appliances to act as a session monitor
cluster. The session table is then replicated to all members of the cluster.
Once configured and enabled, the session monitor maintains a session table that
records which sessions are currently active and the user identity for each session.
133
Volume 5: Advanced Networking
radius acct-listen-port port_number The port number where the SG appliance listens for
accounting messages
radius authentication enable | disable Enable or disable (the default) the authentication of
RADIUS messages using the shared secret. Note
that the shared secret must be configured before
authentication is enabled.
radius encrypted-shared- encrypted_shared_ Specify the shared secret (in encrypted form) used
secret secret for RADIUS protocol authentication. The secret is
decrypted using the configuration-passwords-key.
radius no shared-secret Clears the shared secret used for RADIUS protocol
authentication.
radius shared-secret plaintext_secret Specify the shared secret used for RAIDUS protocol
in plaintext.
Note: When using a session monitor cluster, the RADIUS client must be configured to
send the RADIUS accounting messages to the failover group's virtual IP address.
Note: Each member of the failover group must configured with the cluster commands to
maintain the session table for RADIUS accounting messages.
134
Chapter 11: Configuring the SG Appliance as a Session Monitor
cluster group-address IP_address Set or clear (the default) the failover group IP address. This
| no group-address must be an existing failover group address.
cluster port port_number Set the TCP/IP port for the session replication control. The
default is 55555.
cluster seconds Set the maximum time to wait for session table
synchronization-delay synchronization. The default is zero; the range is from 0 to 2
^31 -1 seconds. During this time evaluation of
$(session.username) is delayed, so proxy traffic might
also be delayed.
cluster grace-period seconds Set the time to keep session transactions in memory while
waiting for slave logins. This can be set to allow session table
synchronization to occur after the synchronization-delay has
expired. The default is 30 seconds; the range is 0 to 2^31-1
seconds.
135
Volume 5: Advanced Networking
2. (Optional) To view the session-monitor configuration, you can either use the
session-monitor view command or the config show session-monitor command.
SGOS#(config) show session-monitor
General:
Status: enabled
Entry timeout: 120 minutes
Maximum entries: 500000
Cluster support: enabled
Cluster port: 55555
Cluster group address: 10.9.17.159
Synchronization delay: 0
Synchronization grace period: 30
Accounting protocol: radius
Radius accounting:
Listen ports:
Accounting: 1813
Responses: Enabled
Authentication: Enabled
Shared secret: ************
Note: Refer to Volume 10: Content Policy Language Guide for details about CPL and how
transactions trigger the evaluation of policy file layers.
❐ In this example, the SG appliance is using the session table maintained by the session
monitor for authentication.
<proxy>
allow authenticate(session)
where session is a policy substitution realm that uses $(session.username) in
building the username. (For information on creating a Policy Substitution realm, refer
to Volume 4: Securing the Blue Coat SG Appliance.)
Notes
❐ The session table is stored entirely in memory. The amount of memory needed is
roughly 40MB for 500,000 users.
❐ The session table is kept in memory. If the system goes down, the contents of the
session table are lost. However, if the system is a member of a failover cluster, the
current contents of the session table can be obtained from another machine in the
cluster. The only situation in which the session table is entirely lost is if all machines in
the cluster go down at the same time.
❐ The session replication protocol replicates session information only; configuration
information is not exchanged. That means that each SG appliance must be properly
configured for session monitoring.
❐ The session replication protocol is not secured. The failover group should be on a
physically secure network to communicate with each other.
136
Chapter 11: Configuring the SG Appliance as a Session Monitor
137
Volume 5: Advanced Networking
138
Chapter 12: Configuring and Using the SG Client
The Blue Coat SG Client enables users to benefit from accelerated application delivery
directly to their desktops. This allows mobile users or users in small branch offices—
where it might not be cost-justifiable to deploy an acceleration gateway—to enjoy
improved networked application access.
This chapter includes the following topics:
❐ “Overview” on page 140
❐ “About ADN Features” on page 143
❐ “Configuring Client Settings” on page 146
❐ “Configuring the Client Manager” on page 151
❐ “Configuring the SG Client from the Command Line” on page 155
❐ “Making the SG Client Software Available to Users” on page 158
❐ “Using the SG Client” on page 171
❐ “Troubleshooting Tips for Administrators” on page 171
❐ “Licensing” on page 181
139
Volume 5: Advanced Networking
Overview
This section discusses the concepts you need to know to implement the SG Client in your
enterprise:
❐ “About the Terminology” on page 140
❐ “SG Client Features and Benefits” on page 141
❐ “About SG Client Deployment” on page 142
140
Chapter 12: Configuring and Using the SG Client
❐ ADN manager and backup manager (not shown in the preceding figure)
Every ADN network must have an ADN manager, which is responsible for publishing
the routing table to SG Clients (and to other SG appliances). Although not required,
Blue Coat recommends configuring an ADN backup manager, which takes over for the
ADN manager in the event it becomes unavailable.
Note: The Client Manager can be any appliance in the ADN network, including a
concentrator, the ADN manager, or backup manager. For example, the Client
Manager could also be the ADN manager but that is not a requirement.
To configure an ADN manager and backup manager, see “Defining the ADN
Manager” on page 21.
Feature Benefit
Common Internet File System (CIFS) The SG Client significantly enhances Wide Area
acceleration Network (WAN) file service delivery, improving user
productivity by implementing the following:
• Client object caching, which enables clients to get
previously obtained data from cache rather than
across the WAN.
• CIFS protocol optimization, which improves
performance by consolidating data forwarded across
the WAN.
Connect from anywhere The SG Client enables any user to remotely connect to
an ADN network.
Load balancing and failover Enables you to efficiently use your ADN network as a
robust infrastructure for clients.
141
Volume 5: Advanced Networking
To download the SG Client software from the Client Manager, the user must go to a
URL provided by the administrator.
When the user connects to the Client Manager using the URL, the user runs a setup
application (SGClientSetup.exe) that in turn downloads and starts a Microsoft
Installer (SGClientSetup.msi).
142
Chapter 12: Configuring and Using the SG Client
2. After installing the SG Client software, the user must reboot the machine.
3. Periodically, the SG Client polls the Client Manager for changes to the SG Client
software and configuration.
143
Volume 5: Advanced Networking
Note: To select options for either Manager Listening Mode or Tunnel Listening
Mode, you must have previously set up a device authentication profile on the SG
appliance. For more information about device authentication profiles, see “About
Device Authentication Profiles” on page 88.
Note: Select this option only if all appliances in the ADN network run SGOS version
5.1.4 or later.
144
Chapter 12: Configuring and Using the SG Client
❐ Plain Only
Select this option in cases where you do not secure any ADN connections between SG
appliances.
This option means that only SG appliances that use plain connections can publish
routes.
❐ Both
Select this option if you use the SG Client in your ADN network and some appliances
in the network are not capable of using secure connections (for example, some
appliances run SGOS version 5.1.3 or earlier).
This option means that SG appliances that use either secure or plain connections can
publish routes.
145
Volume 5: Advanced Networking
You can set the maximum percentage of total disk space (as opposed to available disk
space) the SG Client allocates to the object cache. The SG Client always leaves at least
1GB of available disk space on the client machine’s system root volume.
146
Chapter 12: Configuring and Using the SG Client
Field Description
Update interval Enter the frequency, in minutes, for clients to check the
Client Manager for updated SG Client software or
configuration updates.
The default is 120. Valid values are between 10–432000
(that is, 300 days).
Maximum percentage of disk Maximum percentage of client disk space to use for
space to use for object caching caching objects, such as CIFS objects. Valid values are 1–
90; the default is 10.
Note: The cache leaves at least 1GB available space on the
system root volume. For more information, see
“Configuring General Client Settings” on page 146.
147
Volume 5: Advanced Networking
Item Description
Enable CIFS acceleration check • Select the check box to enable CIFS acceleration for clients.
box • Clear the check box to disable CIFS acceleration. If you clear the check box,
the other options on this tab page are unavailable.
For more information about CIFS acceleration, see “SG Client Features and
Benefits” on page 141.
Write back Determines whether or not users can continue sending data to the appliance
while the appliance is writing data on the back end.
• Select Full to enable write-back, which in turn makes the local SG Client
proxy appear to the user as a file server; in other words, the local SG Client
proxy constantly sends approval to the client and allows the client to send
data while the back end takes advantage of the compressed TCP connection.
• Select None to disable write-back. Disabling write-back can introduce
substantial latency while clients send data to the appliance and wait for
acknowledgement before sending more data.
One reason to set this option to None is the risk of data loss if the link from
the branch to the core server fails. There is no way to recover queued data if
such a link failure occurs.
Directory cache time field Number of seconds for directory listings to remain in the client’s cache.
148
Chapter 12: Configuring and Using the SG Client
149
Volume 5: Advanced Networking
Field Description
ADN Manager Enter the primary ADN manager’s IP address. The ADN
manager tracks and advertises the routes to the
appliances it knows about.
The SG Client obtains the routing table from the ADN
manager.
150
Chapter 12: Configuring and Using the SG Client
Item Description
Note: The include and exclude ports lists are advanced settings that limit the traffic
that is accelerated by the ADN network. To cause all traffic to be accelerated by the
ADN network, click either option and delete all the ports in the list.
151
Volume 5: Advanced Networking
Note: Before you can enable an appliance to be the Client Manager, you must
configure the ADN manager SG Clients will use. If you enable the Client Manager
before you configure an ADN manager for clients, the following error displays when
you attempt to apply the change: The ADN primary manager must be set prior
to enabling the SG Client Manager. To configure the clients’ ADN manager, see
“Configuring Client ADN Manager Settings” on page 149.
License information displays below the check box. For more information, see
“Licensing” on page 181.
Item Description
Host Specify the host from which users get the SG Client software, configuration, and updates.
Blue Coat recommends you specify a fully qualified host name, and not an unqualified
(short) host name or IP address. If you use a fully qualified host name and the Client
Manager’s IP address changes later, you need only to update DNS for the Client Manager’s
new address and clients can continue to download the software and updates from the
Client Manager.
After you set this option, provide the appropriate URL to users in an e-mail or by some
other means so they can download the SG Client software, configuration, and updates from
that URL.
You have the following options:
• Use host from initial client request: (Recommended.) Select this option to enable
clients to download the SG Client software, configuration, and updates from the host
from which the clients originally obtained the software and configuration.
This option is compatible with all methods of deploying the SG Client, including
Windows Group Policy Object (GPO) and Microsoft Systems Management Server (SMS).
For more information about these deployment options, see “Making the SG Client
Software Available to Users” on page 158.
• Use host: Select this option to download the SG Client software and configuration from
the host name you specify. Enter a fully qualified host name or IP address only; do not
preface it with http:// or https:// because downloads will fail.
Use this option to migrate users from one Client Manager to another Client Manager.
(Also see “Changing the Client Manager URL” on page 175.)
Port field Enter the port on which the Client Manager listens for requests from clients. The default is
8084.
Keyring list Select the keyring to use when clients connect to the Client Manager.
152
Chapter 12: Configuring and Using the SG Client
After you apply the changes, the Client Components section displays a summary of
the information you selected, as follows:
Table 12-7. Client Components Section
Item Description
Client setup Displays the URL from which users will download the SG Client
setup application. The setup application (SGClientSetup.exe)
downloads the Microsoft Installer (MSI)—named
SGClientSetup.msi—to the client.
If you want users to install the SG Client software from the Client
Manager, provide this URL to them. To install the software this way,
the user must have administrative privileges on the client machine.
Note: If you chose Use host from client request for Host as
discussed in Table 12-6 on page 152, the URL displays as follows:
https://host-from-client-request:8084/sgclient/
SGClientSetup.exe
To download the SG Client using this URL, substitute the Client
Manager’s host name or IP address for host-from-client-request.
Client install MSI Displays the URL from which SGClientSetup.exe downloads
SGClientSetup.msi.
To install the SG Client software on client machines silently or using
Group Policy Objects (GPO) or the Microsoft Systems Management
Server (SMS), use SGClientSetup.msi.
Client configuration Displays the URL from which the SG Client installer downloads the
client configuration file (SGClientConfig.xml).
Client configuration Displays the most recent date and time SGClientConfig.xml
last modified was updated on the Client Manager.
153
Volume 5: Advanced Networking
5. From the Install SG Client software from list, select one of the following:
• Remote URL: Upload SGClient.car from a location specified by a URL in the
following format:
https://host:port/sgclient/SGClient_timestamp.car
For example,
http://mysg.example.com:8004/sgclient/SGClient_timestamp.car
• Local file: Upload the SG Client software from a location accessible by the
machine on which you are running the Management Console.
6. Click Install.
You are required to confirm the action. Remember that any software or configuration
updates require SG Client users to download the updates the next time they connect
to the ADN network.
7. Follow the prompts on your screen to complete the download.
154
Chapter 12: Configuring and Using the SG Client
155
Volume 5: Advanced Networking
156
Chapter 12: Configuring and Using the SG Client
Note: Before you can enable an appliance to be the Client Manager, you must
configure the ADN manager SG Clients will use. If you enable the Client Manager
before you configure an ADN manager for clients, the following error displays: The
ADN primary manager must be set prior to enabling the SG Client
Manager. To configure the clients’ ADN manager, see “Configuring Client ADN Rules
Settings” on page 150.
157
Volume 5: Advanced Networking
158
Chapter 12: Configuring and Using the SG Client
Option Description
Install from Client Manager Provide users the URL to SGClientSetup.exe, which displays
on the Client Manager tab page when you select SG Client >
Client Manager.
SGClientSetup.exe downloads and runs
SGClientSetup.msi on the client machine. Users see the
installation in progress and have the option of canceling the
installation.
For more information about this installation method, see
“Interactive Installations from the Client Manager” on
page 159.
Install from the command To install the SG Client using SGClientSetup.msi, users must
line first download it to the client machine, then execute it from the
command line as discussed in “Interactive Manual
Installations” on page 161.
Note: For a complete discussion of SGClientSetup.msi
command-line parameters, see “Setting Up Silent
Installations and Uninstallations” on page 162.
Note: Users who run the SG Client setup application must be in the Administrators
group on the client machine.
159
Volume 5: Advanced Networking
4. Click Run.
The following dialog displays if you use Internet Explorer 6:
5. Click Run.
160
Chapter 12: Configuring and Using the SG Client
161
Volume 5: Advanced Networking
This URL displays when you select SG Client > Client Manager and click the Client
Manager tab as discussed in “Configuring the Client Manager” on page 151.
For example,
SGClientSetup.msi BCSI_UPDATEURL=http://mysg.example.com:8084/
sgclient/SGClientConfig.xml
Note: Other command-line parameters are available. For a complete list, see
“Setting Up Silent Installations and Uninstallations” on page 162.
For information about distributing the SG Client software using Group Object Policy, skip
this section and see “Using Group Policy Object Distribution” on page 168.
162
Chapter 12: Configuring and Using the SG Client
/qr|/qn /qr (interactive, default) enables the user to see and interact
with the installer and to cancel the installation.
/qn (totally silent) prevents the user from seeing or
interacting with the installer and from canceling the
installation.
Note: Because this is an msiexec command, other options
are available. Enter msiexec at a command prompt for
more information about other options.
REINSTALL ALL Installs all SG Client components, whether they are already
installed or not.
ALL is the only supported parameter value in this release.
REINSTALLMODE vamus Blue Coat recommends using vamus as the parameter value.
Because this is an msiexec command, other options are
available. For more information, see the description of this
parameter at: http://msdn2.microsoft.com/en-us/
library/aa371182.aspx
163
Volume 5: Advanced Networking
FORCEREBOOT yes|no This setting controls whether or not Now or Later buttons
y|n display on the post-installation reboot dialog.
yes or y mean the dialog displays without buttons.
(However, if REBOOTTIME=0, no dialog displays.)
no or n (default) mean a dialog displays with two options:
Now and Later, enabling users to either reboot immediately,
wait for the timer to expire (see the next parameter), or wait
until a later time of their choosing.
164
Chapter 12: Configuring and Using the SG Client
/l*v logfile If you want the installation to be logged, enter the absolute
file system path and file name of the log file.
Note:
❐ If you changed the location of the CIFS cache as discussed in “Changing the Location
of the CIFS Cache” on page 180, you must manually remove files from the new
location after you uninstall the SG Client software. The SG Client uninstaller removes
files only from the default CIFS cache folder.
❐ Users who have administrative privileges on their machines can also uninstall the SG
Client using the Windows Control Panel’s Add or Remove Programs application.
Example Installations
Example 1: Automated, interactive installation with manual software updates possible:
SGClientSetup.msi /qr BCSI_UPDATEURL=https://mysg.example.com:8084/
sgclient/SGClientConfig.xml REINSTALL=ALL REINSTALLMODE=vamus
AUTOUPDATEDISABLED=1 FORCEREBOOT=no REBOOTTIME=30
The SG Client configuration downloads from the Client Manager at
https://mysg.example.com:8084. The user sees the installation in progress and can
cancel it.
AUTOUPDATEDISABLED=1 means that the SG Client does not implement software
updates after the initial installation (it will, however, implement configuration
updates). This setting enables you to test the SG Client software on a small scale
without having to plan for client updates.
(To get software updates manually and thereafter enable automatic updates, click
Check for Updates on the Advanced tab page in the SG Client dialog as discussed in
the SG Client on-line help.)
165
Volume 5: Advanced Networking
The REINSTALL and REINSTALLMODE parameters make sure that all SG Client
components install, which is useful in cases where you are recovering from an
incomplete or previously unsuccessful installation.
After the installation is complete, the user has the following options:
• Wait 30 seconds for the machine to reboot
• Click Later in the dialog to defer rebooting until a later time
• Click Now in the dialog to reboot immediately
Example 2: Automated, interactive installation with no automatic software updates
possible
SGClientSetup.msi /qr BCSI_UPDATEURL=https://mysg.example.com:8084/
sgclient/SGClientConfig.xml REINSTALL=ALL REINSTALLMODE=vamus
AUTOUPDATEPROHIBITED=1 FORCEREBOOT=no REBOOTTIME=30
The SG Client configuration downloads from the Client Manager at
https://mysg.example.com:8084. The user sees the installation in progress and can
cancel it.
AUTOUPDATEPROHIBITED=1 means the SG Client cannot check for software updates
after the initial installation; however, it will check for and implement configuration
updates. Use this setting if you want to distribute software updates in some way other
than the Client Manager.
The REINSTALL and REINSTALLMODE parameters make sure that all SG Client
components install, which is useful in cases where you are recovering from an
incomplete or previously unsuccessful installation.
After the installation is complete, the user has the following options:
• Wait 30 seconds for the machine to reboot
• Click Later in the dialog to defer rebooting until a later time
• Click Now in the dialog to reboot immediately
Example 3: Automated, interactive installation
SGClientSetup.msi /qr BCSI_UPDATEURL=https://mysg.example.com:8084/
sgclient/SGClientConfig.xml REINSTALL=ALL REINSTALLMODE=vamus
FORCEREBOOT=no REBOOTTIME=30
The SG Client configuration downloads from the Client Manager at
https://mysg.example.com:8084. The user sees the installation in progress and can
cancel it. The REINSTALL and REINSTALLMODE parameters make sure that all SG Client
components install, which is useful in cases where you are recovering from an
incomplete or previously unsuccessful installation.
After the installation is complete, the user has the following options:
• Wait 30 seconds for the machine to reboot
• Click Later in the dialog to defer rebooting until a later time
• Click Now in the dialog to reboot immediately
166
Chapter 12: Configuring and Using the SG Client
Example Uninstallation
msiexec /q /x {4214C5ED-CCED-4360-90C0-69764F3D0854}
The string {4214C5ED-CCED-4360-90C0-69764F3D0854} identifies the SG Client
installer’s MSI product code.
167
Volume 5: Advanced Networking
REINSTALL Add row Add this row and set it to all only if you want to
update the SG Client software and configuration using
GPO.
If clients get future SG Client software and
configuration updates from the Client Manager, do not
add this row.
Also see the discussion of AUTOUPDATEPROHIBITED
later in Table 12-11.
REINSTALLMODE Add row Add this row and change it to vamus only if you want to
update the SG Client software and configuration using
GPO.
If clients will get future SG Client software and
configuration updates from the Client Manager, do not
add this row.
Also see the discussion of AUTOUPDATEPROHIBITED
later in Table 12-11.
168
Chapter 12: Configuring and Using the SG Client
AUTOUPDATEDISABLED Edit Change the value from 0 to 1 only if you want to update
the SG Client software using GPO. (Configuration
updates are obtained from the Client Manager whose
URL is specified by the BCSI_UPDATEURL parameter
discussed earlier in this table.)
1 means the SG Client checks for software updates and
does the following:
• Implements configuration updates when they are
available.
• Implements software updates only if the user
manually requests an update.
This setting enables you to test the SG Client installation
before deploying it in production.
AUTOUPDATEPROHIBITED Edit Change the value from 0 to 1 only if you want to update
value the SG Client software using GPO. (Configuration
updates are obtained from the Client Manager whose
URL is specified by the BCSI_UPDATEURL parameter
discussed earlier in this table.)
1 means only the SG Client configuration can be
updated (automatically or manually), but the SG Client
software cannot be updated. Use this setting if you want
to distribute software updates in some way other than
the Client Manager.
Note: AUTOUPDATEPROHIBITED=1 takes precedence
over AUTOUPDATEDISABLED=1.
If clients will get future SG Client software updates from
the Client Manager, leave this value at 0.
169
Volume 5: Advanced Networking
170
Chapter 12: Configuring and Using the SG Client
171
Volume 5: Advanced Networking
SG Client Logging
The SG Client maintains the following logs in the user’s %TMP% folder:
Table 12-13. SG Client Log Files
sgdebug.etl SG Client trace log. This file can reach a maximum of 20MB in
size, after which the oldest log entries are deleted as new
entries are written.
This log is in a compiled format that is readable only by Blue
Coat Engineering.
The SG Client maintains the following log in the SG Client installation folder (for
example, C:\Program Files\Blue Coat\SG Client):
Table 12-15. SG Client Log Files
172
Chapter 12: Configuring and Using the SG Client
Note: The SG Client uses the Internet Explorer proxy settings to download software
and configuration updates, so make sure you change Internet Explorer’s proxy
settings.
ADN Tunnels
On the General tab page of the SG Client dialog, clicking View ADN Tunnels displays
detailed information about available tunnels, including whether a tunnel is idle or
bypassed.
An Idle tunnel is one that is not currently being used but for which connection information
is preserved to decrease the amount of time required to use that connection later, if
necessary.
A Bypassed tunnel indicates an error with the connection to the indicated SG appliance.
173
Volume 5: Advanced Networking
where host is the fully qualified host name or IP address of the Client Manager, and
port is the SG appliance’s listen port.
Change the Enables you to connect to a Client Manager Advanced tab page, left “Changing the
Client Manager other than the one you initially downloaded Control+Shift, click Client Manager
URL the SG Client from. The typical use is for Check for Updates URL” on
Blue Coat employees to run demonstrations, page 175
trials, and evaluations from different ADN
networks.
Data collector Collects diagnostic information useful to About tab page, left “Using the SG
troubleshoot unexpected behavior and Control+Shift, click Help Client Data
connectivity problems. Collector” on
page 176
Diagnostic and Displays routing information for the ADN About tab page, left “Using the SG
configuration network, enables you to set SG Client Control+Shift, click Client
utility software auto-update options, and enables System Info Diagnostics &
you to create an SG Client service crash Configuration
dump. Utility” on
page 178
Change the Change the location of object cache files to a (No shortcut because it is “Changing the
location of the volume that has more space. By default, a registry setting) Location of the
object cache filesa object cache files are stored on the user’s CIFS Cache” on
system root volume. page 180
174
Chapter 12: Configuring and Using the SG Client
In other words, enter the URL to SGClientConfig.xml, which displays on the Client
Manager tab page when you select SG Client > Client Manager.
For example:
https://mysg.example.com:8084/sgclient/SGClientConfig.xml
175
Volume 5: Advanced Networking
6. Click OK.
Messages display in the Change SG Client Manager dialog as the URL is verified, the
SG Client service is stopped, and the service is restarted. After the service is restarted,
configuration updates (if any) are downloaded to the SG Client. If automatic
configuration updates are disabled, see step 7.
If software updates are ready to download, you are notified before the updates are
installed. If automatic software updates are disabled, the SG Client skips this step. To
manually enable automatic updates on this machine, see “Using the SG Client
Diagnostics & Configuration Utility” on page 178.
When the operation is complete, the Advanced tab page displays the new Client
Manager URL.
7. If automatic configuration updates are disabled:
a. Double-click the SG Client icon in the system tray.
b. Click the Advanced tab.
c. On the Advanced tab page, click Check for Updates.
Configuration updates, if any, are downloaded to the SG Client.
176
Chapter 12: Configuring and Using the SG Client
6. When all tasks are complete, the Collection Complete dialog gives you the following
options:
• Click Save Data to save the data in a .zip file to a directory you select.
• Click Open Folder to open the temporary folder that contains the collected data
files.
• Click Close.
7. Send the data to Blue Coat Support.
After you close the Collection Complete dialog, the SG Client Data Collector dialog
displays as follows:
177
Volume 5: Advanced Networking
178
Chapter 12: Configuring and Using the SG Client
Task Procedure
View ADN network and The SG Client Routing section at the top of the dialog box
routing information displays the following information:
• Subnets: Displays routing information the SG Client
obtained from the ADN manager. This information shows
which locations are being accelerated.
If a server does not appear to be accelerated (for example, if
downloads from that server are slow), look at the routing
table to see if the server is published as an accelerated
destination. If not, the administrator should configure the
concentrator to recognize the server as an accelerated
destination.
The routing table does not indicate whether a particular
location is reachable, however. Look in the SG Client logs to
determine whether the locations are reachable.
To update routing information, click Refresh Routing
Information.
• Excluded subnets: Displays the list of excluded subnets
defined by the Client Manager.
• Included ports: Displays the list of included ports defined
by the Client Manager.
For more information about excluded subnets and included
ports, see the chapter on the SG Client in the Advanced
Networking book.
Change automatic update Click one of the following to determine whether or not the
options client can download updated software from the Client
Manager:
• Enabled: Users can download future SG Client software
updates on this machine.
• Disabled: Users cannot download future SG Client
software updates on this machine. Choose this option to
distribute software updates some other way (for example,
using Windows Group Policy Object (GPO) distribution or
Microsoft System Management Server (SMS) distribution).
Create an SG Client service In the event of problems with the SG Client application (such
crash dump file as crashes or freezes), click to create an SG Client service dump
file named sgclientsvc.dmp file in the root directory of the
system root volume (for example, C:\).
Send the crash dump to Blue Coat Support as part of your
service request.
179
Volume 5: Advanced Networking
To optionally locate the files on a different volume (for example, a volume that has
more available space):
1. If the SG Client is already installed, perform the following tasks first:
a. Double-click the SG Client icon in the system tray.
b. In the SG Client dialog box, click the General tab.
c. On the General tab page, click Clear Cache.
This deletes or expires all the files in the current CIFS cache.
d. Click Disable SG Client.
e. Click Close.
2. Create a registry value named CacheDirectory of type REG_SZ (that is, String) in the
following key:
HKEY_LOCAL_MACHINE\SOFTWARE\Blue Coat Systems\SG Client
3. Set the Value data of CacheDirectory to the location to store the object cache.
Note: If the SG Client is not already installed, create the registry before you install the
SG Client to avoid the user having to restart the SG Client service. Restarting the
service stops ADN acceleration and CIFS protocol acceleration until an ADN tunnel
can be re-established after the service starts.
4. If you have not already done so, install the SG Client as discussed in the chapter on
the SG Client in the Advanced Networking book.
5. Reboot the client machine or restart the SG Client service for the registry key to take
effect.
To restart the SG Client service, right-click on its icon in the system tray. From the pop-
up menu, click Disable SG Client. Right-click the icon again and, from the pop-up
menu, click Enable SG Client.
6. Optional. After the service restarts, manually remove any files remaining in the
previous CIFS cache directory:
%windir%\system32\sgclient\cifs
180
Chapter 12: Configuring and Using the SG Client
Licensing
❐ A new SG appliance has a 60-day trial license that permits you to use it with an
unlimited number of clients.
❐ After the 60-day trial period, you are required to purchase a permanent license to
continue using the SG Client.
The license entitles you to support a certain number of clients in your enterprise;
however, the license does not limit the number of ADN tunnels to which clients can
have access.
Client machines do not require a license to use the SG Client software; only the Client
Manager appliance requires a license.
❐ You can upgrade your license to larger user counts.
For information about applying a permanent Client Manager license, see the chapter on
licensing in Volume 1: Getting Started.
181
Volume 5: Advanced Networking
182
Chapter 13: SOCKS Gateway Configuration
183
Volume 5: Advanced Networking
Note: SOCKS gateway aliases cannot be CPL keywords, such as no, default,
forward, or socks_gateways.
184
Chapter 13: SOCKS Gateway Configuration
b. Host: Add the IP address or the host name of the gateway where traffic is
directed. The host name must DNS resolve.
c. Port: The default is 1080.
d. SOCKS version: Select the version that the SOCKS gateway can support from
the drop-down list. Version 5 is recommended.
e. Username (Optional, and only if you use version 5) The username of the user
on the SOCKS gateway. The username already must exist on the gateway. If
you have a username, you must also set the password.
f. Set Password: The plaintext password or encrypted password of the user on
the SOCKS gateway. The password must match the gateway’s information.
The password can be up to 64 bytes long. Passwords that include spaces must
be within quotes.
You can enter an encrypted password (up to 64 bytes long) either through the CLI
or through installable list directives.
g. In the Load Balancing and Host Affinity section, select the load balancing
method from the drop-down list. Global default (configured on the
Configuration > Forwarding > Global Defaults tab), sets the default for all
SOCKS gateways on the system. You can also specify the load balancing
method for this system: Least Connections or Round Robin, or you can disable
load balancing by selecting None.
h. In the Host affinity methods drop-down list, select the method you want to
use:
• HTTP: The default is to use the Global Defaults. Other choices are None, which
disables host affinity, Accelerator Cookie, which places a cookie in the
response to the client, and Client IP Address, which uses the client IP address
to determine which upstream SOCKS gateway was last used.
By default, SOCKS treats all incoming requests destined to port 80 as HTTP,
allowing the usual HTTP policy to be performed on them, including ICAP
scanning. If the SOCKS connection is being made to a server on another port,
write policy on the SG appliance to match on the server host and port and
specify that it is HTTP using SOCKS.
• SSL: The default is to use the Global Defaults. Other choices are None, which
disables host affinity, Accelerator Cookie, which places a cookie in the
response to the client, and Client IP Address, which uses the client IP address
to determine which group member was last used. In addition, you can select
SSL Session ID, used in place of a cookie or IP address, which extracts the SSL
session ID name from the connection information.
• Other. Other applies to any traffic that is not HTTP, terminated HTTPS, or
intercepted HTTPS. You can attempt load balancing of any of the supported
traffic types in forwarding and this host affinity setting can be applied as well.
For example, you could load balance a set of TCP tunnels and apply the Other
host affinity (client IP only).
The default is to use Global Defaults. Other choices are None, which disables
host affinity, and Client IP Address, which uses the client IP address to
determine which group member was last used.
4. Click OK.
5. Click Apply to commit the changes to the SG appliance.
185
Volume 5: Advanced Networking
To create groups:
An existing gateway can belong to none, one, or more groups as desired (it can only
belong once to a single group, however).
1. Select Configuration > Forwarding > SOCKS Gateways > SOCKS Gateway Groups.
2. Click New to create a new SOCKS gateway group.
3. The Add SOCKS Gateway Group dialog displays, showing the available host aliases.
To create an alias group, highlight the hosts and groups you want grouped, and click
Add.
4. Give the new group a meaningful name.
5. In the Load Balancing and Host Affinity section, select the load balancing method from
the drop-down list. Global default (configured on the Configuration > Forwarding >
SOCKS Gateways > Global Defaults tab), sets the default for all forwarding hosts on the
system. You can also specify the load balancing method for this system: Least
Connections, Round Robin, Domain Hash, URL Hash, or you can disable load balancing
by selecting None.
6. In the Host affinity methods drop-down lists, select the method you want to use. Refer
to the previous procedure for details on methods.You are selecting between the
resolved IP addresses of all of the hosts in the group, not the resolved IP addresses of
an individual host.
186
Chapter 13: SOCKS Gateway Configuration
• HTTP: The default is to use the Global Defaults. Other choices are None, which
disables host affinity, Accelerator Cookie, which places a cookie in the response to
the client, and Client IP Address, which uses the client IP address to determine
which group member was last used.
• SSL: The default is to use the Global Defaults. Other choices are None, which
disables host affinity, Accelerator Cookie, which places a cookie in the response to
the client, and Client IP Address, which uses the client IP address to determine
which group member was last used. In addition, you can select SSL Session ID,
used in place of a cookie or IP address, which extracts the SSL session ID name
from the connection information.
• Other. Other applies to any traffic that is not HTTP, terminated HTTPS, or
intercepted HTTPS. You can attempt load balancing of any of the supported
traffic types in forwarding and this host affinity setting can be applied as well. For
example, you could load balance a set of TCP tunnels and apply the Other host
affinity (client IP only).
The default is to use Global Defaults. Other choices are None, which disables host
affinity, and Client IP Address, which uses the client IP address to determine
which group member was last used.
7. Click OK.
2. Determine how you want connections to behave if the health checks fail: Connect
Directly (fail open) or Deny the request (fail closed). Note that failing open is an
insecure option. The default is to fail closed. This option can be overridden by policy,
if it exists.
187
Volume 5: Advanced Networking
188
Chapter 13: SOCKS Gateway Configuration
A default failover sequence allow healthy hosts to take over for an unhealthy host (one
that is failing its DNS Resolution or its health check). The sequence specifies the order of
failover, with the second host taking over for the first host, the third taking over for the
second, and so on.
If all hosts are unhealthy, the operation fails either open or closed, depending upon your
settings.
This configuration is usually created and managed through policy. If no SOCKS-gateways
policy applies, you can create a default sequence through the CLI. This single default
sequence consists of a single default host (or group) plus one or more hosts to use if the
preceding ones are unhealthy.
Note: Traffic is forwarded to the first member of the list until it fails, then traffic is
sent to the second member of list until it fails or the first member becomes healthy
again, and so on.
1. Select Configuration > Forwarding > SOCKS Gateways > Default Sequence.
2. The available aliases (host and group) display in the Available Aliases pane. To select
an alias, highlight it and click Add.
Note: Any host or group in the default sequence is considered in use by policy. As a
result, if you try to delete a host or group while it is in the default sequence, you
receive an error message. You must remove the host/group from the sequence first,
then delete the host or group.
3. You can use the Promote and Demote buttons to change the order of the hosts and
groups in the sequence after you add them to the Selected Aliases pane.
4. Click Apply to commit the changes to the SG appliance.
189
Volume 5: Advanced Networking
190
Chapter 13: SOCKS Gateway Configuration
Statistics
SOCKS gateways statistics are available through the Statistics > Advanced > SOCKS
Gateways menu item.
191
Volume 5: Advanced Networking
Directive Meaning
gateway Specifies the gateway alias and name, SOCKS port, version supported,
usernames and password.
sequence Adds a space-separated list of one or more SOCKS gateways and group
alias_list aliases. (The default sequence is the default forwarding rule, used for
all requests lacking policy instructions
192
Chapter 13: SOCKS Gateway Configuration
Example
gateway Sec_App1 10.25.36.47 1022 version=5 user=username
password=password
193
Volume 5: Advanced Networking
Examples
socks_fail open
load_balance {none | domain-hash | url- If you use group for load balancing,
group hash | round-robin | you can set the suboption to none or
least-connections} choose another method. If you do not
[group_alias] specify a group, the settings apply as the
default for all groups.
194
Chapter 13: SOCKS Gateway Configuration
Example
load_balance gateway least_connections
195
Volume 5: Advanced Networking
Example
host_affinity ssl accelerator-cookie 10.25.36.48
host_affinity timeout 5
Note: Creating the default sequence through the CLI is a legacy feature. You can set up
sequences by using policy alone. The default sequence (if present) is applied only if no
applicable command is in policy.
For information on using VPM, refer to Volume 6: VPM and Advanced Policy; for
information on using CPL, refer to Volume 10: Content Policy Language Guide.
A default failover sequence works by allowing healthy SOCKS gateways to take over for
an unhealthy gateway (one that is failing its DNS resolution or its health check). The
sequence specifies the order of failover, with the second gateway taking over for the first
gateway, the third taking over for the second, and so on).
If all gateways are unhealthy, the operation fails either open or closed, depending upon
your settings.
This configuration is generally created and managed through policy. If no forwarding
policy applies, you can create a default sequence through the CLI. This single default
sequence consists of a single default gateway (or group) plus one or more gateways to use
if the preceding ones are unhealthy.
The syntax is:
sequence alias_list
where alias_list is a space-separated list of one or more SOCKS gateways and
group aliases.
Example
sequence gateway_alias
196
Chapter 13: SOCKS Gateway Configuration
Note: During the time that a SOCKS gateways installable list is being compiled and
installed, SOCKS gateways might not be available. Any transactions that come into the SG
appliance during this time might not be forwarded properly.
197
Volume 5: Advanced Networking
198
Chapter 14: Health Checks
Blue Coat health checks allow you to determine the availability of external networking
devices.
This chapter includes the following sections:
❐ Section A: "Overview" on page 200
❐ Section B: "About Blue Coat Health Components" on page 202
❐ Section C: "Configuring Global Defaults" on page 207
❐ Section D: "Forwarding Host and SOCKS Gateways Health Checks" on page 214
❐ Section E: "Editing External Services" on page 218
❐ Section F: "Managing User-Defined Health Checks" on page 221
❐ Section G: "Statistics" on page 227
❐ Section H: "Using Policy" on page 229
❐ Section I: "Related CLI Syntax to Configure Health Checks" on page 230
199
Volume 5: Advanced Networking
Section A: Overview
Section A: Overview
Health checks are tests run on external resources, such as forwarding hosts, SOCKS
gateways, and ICAP and Websense off-box services, to determine status. You can use
health checks in conjunction with various failover mechanisms to handle a variety of
failure scenarios. For example, you can use health checks with forwarding rules to
redirect traffic from one server or proxy to another.
If the health check for an individual host fails, the SG appliance can select a healthy host
ahead of time or report the failure quickly.
Health checks test for:
❐ Network connectivity
❐ Target responsiveness
❐ Basic functionality of the upstream system or service
Health checks fall into three broad categories:
❐ Determining if the IP address can be reached. Health check types that fall into this
category are:
• Forwarding hosts
• SOCKS gateways
• Dynamic Real-Time Rating (DRTR) service
❐ Determining if a service is responsive. Health check types that fall into this category
are:
• ICAP services
• Websense off-box services
❐ Determining if a group is healthy. Group tests are compilations of individual health
checks, and the health of the group is determined by the status of the group members.
Health check types that fall into this category are:
• Forwarding groups
• SOCKS gateway groups
• ICAP service groups
• Websense off-box service groups
Note: The health check module has been reorganized. For specific information
about the differences between health checks for previous versions and SGOS 5.2, refer
to the Blue Coat SGOS 5.x Upgrade Guide.
Health checks always have status. The status of any health check can be referenced in
policy as a condition. For more information about using health checks in policy, see
Section H: "Using Policy" on page 229.
200
Chapter 14: Health Checks
Section A: Overview
Note: You can run an immediate health check from the Configuration > Health
Checks > General > Health Checks tab by selecting the health check and clicking
Perform health check. You can also view the health check state on the Statistics >
Health Check tab, but you cannot change settings in Statistics.
When a host is resolved by DNS to multiple IP addresses, health checks keep those
addresses current through background updates, the timing of which you can configure on
the Configuration > Health Checks > Background DNS tab. After the test or tests are
conducted for each IP address, the results are combined. If the result for any of the
resolved IP addresses is healthy, then the host is considered healthy because a healthy
connection to that target can be made.
201
Volume 5: Advanced Networking
Note: Some health checks (forwarding hosts and SOCKS gateways) can be
configured to report the result of some composite health check instead of their
own test.
Some health check types only have one matching test, while others have a selection. For
more information about health check types and tests, see Table 14-1, “Health Check
Tests,” on page 203.
202
Chapter 14: Health Checks
In addition to the above health checks that are automatically generated, run, and deleted,
Blue Coat also supports two kinds of user-defined health checks. These health checks are
manually created, configured, and deleted.
❐ Composite health checks: A method to take the results from a set of health checks
(automatically generated or user-defined health checks) and combine the results.
❐ Host health checks: A method to test a server, using a selection of ICMP, TCP, SSL,
HTTP, and HTTPS tests.
Note: Although a host health check tests an upstream server, it can also be used to
test whether a proxy is working correctly. To test HTTP/HTTPS proxy behavior, for
example, you can set up a host beyond the proxy, and then use forwarding rules so
the health check passes through the proxy to the host, allowing the proxy to be tested.
User-defined health checks allow you to test for things that Blue Coat does not test
automatically. For example, for a forwarding host, you could do an HTTP test, an HTTPS
test, and a TCP test of other ports. Then you can use the composite health check to
combine the results of all the tests into one and have that reported as the forwarding host's
health.
All health check types are given standardized names. If a health check is created
automatically by the Blue Coat appliance, names are based on the name of the target. For
example:
❐ Forwarding hosts and groups have a prefix of fwd
❐ SOCKS gateways and gateway groups have a prefix of socks
❐ External services have prefixes of icap, ws, and drtr
❐ User-defined or composite health checks have a prefix of user.
203
Volume 5: Advanced Networking
ICMP Test (Layer 3) The basic connection between the Blue Coat Forwarding hosts,
appliance and the origin server is confirmed. The SOCKS gateways,
server must recognize ICMP echoing, and any or user-defined
intervening networking equipment must support hosts
ICMP. The Blue Coat appliance sends a ping (three
ICMP echo requests) to the host.
ICMP tests do not support policy for SOCKS
gateways or forwarding.
TCP Socket A TCP test establishes that a TCP layer connection Forwarding hosts,
Connection Test can be established to a port on the host. Then the SOCKS gateways,
(Layer 4) connection is dropped. or user-defined
TCP tests for a SOCKS gateway do not support policy hosts
for SOCKS gateways or forwarding.
TCP tests for a forwarding host or a user-defined
health check support SOCKS gateways policy but not
forwarding policy.
SSL Test A connection is made to a target and the full SSL Forwarding hosts
handshake is conducted. Then, much as a TCP test, or user-defined
the connection is dropped. hosts
For a forwarding host, a terminating HTTPS port
must be defined or the test fails.
SSL tests for a forwarding host or a user- defined
health check support SOCKS gateways policy. The
SSL tests do not support forwarding policy.
An SSL test executes the SSL layer in policy and
obeys any settings that apply to server-side
certificates, overriding any settings obtained from a
forwarding host.
204
Chapter 14: Health Checks
HTTP/HTTPS For HTTP/HTTPS tests, you can test authentication Forwarding hosts
Authentication using a configured username and password. The or user-defined
passwords are stored securely in the registry. hosts.
HTTP/HTTPS For an HTTP or HTTPS test, this is the set of HTTP Forwarding hosts
Allowed Responses response codes that indicate success. The default is to or user-defined
accept only a 200 response as successful. You can hosts.
specify the sets of response codes to be considered
successful.
External Services The tests for external services are specialized tests ICAP, Websense
Tests devised for each particular kind of external service. off-box, DRTR
The health check system conducts external service rating service.
tests by sending requests to the external services
system, which reports back a health check result.
205
Volume 5: Advanced Networking
Group Individual tests that are combined for any of the four Forwarding
different available groups (forwarding, SOCKS groups, SOCKS
gateways, ICAP, and Websense off-box). If any of the gateways groups,
members is healthy, then the group as a whole is and ICAP and
considered healthy. Websense off-box
Note: Blue Coat supports a composite test, used external service
only with composite (user-defined) health checks, groups.
that is similar to a group test except that, by
default, all members must be healthy for the result
to be healthy.
These settings are configurable.
By default, group health tests are used for two
purposes:
• Monitoring and notification
• Policy
206
Chapter 14: Health Checks
Note: The DRTR rating service is initially configured to override two of the default
settings. The healthy interval is set to 10800 seconds (3 hours), and a failure trigger is
set to 1.
Note: Individual health checks for group members are still active; they can be used
apart from the group.
Setting a health check as disabled but reporting sick is useful to remove an upstream
device for servicing, testing, or replacement. This setting takes the device offline after pre-
existing traffic completes. Then the device can be safely disconnected from the network
without altering any other configuration.
You cannot enable or disable all health checks at once.
207
Volume 5: Advanced Networking
208
Chapter 14: Health Checks
The failures are reported back to the health check as a result of either a connection
failure or a response error. The number of these external failures is cleared every
time a health check is completed. If the number of failures listed meets or exceeds
the threshold and the health check is idle and not actually executing, then the
health of the device or service is immediately checked.
f. Specify the maximum response time threshold, in milliseconds. The threshold
time can be between 1 and 65535.
3. Click OK.
4. Click Apply to commit the changes to the SG appliance.
209
Volume 5: Advanced Networking
4. To substitute special values for this test, click Override the default settings.
5. Select the check boxes to override. You can cancel your choices by clicking Clear all
overrides.
a. Specify the healthy interval, in seconds, between health checks to the server.
The default is 10. The healthy interval is between 1 second and 31536000
seconds (about one year).
b. Specify the healthy threshold for the number of successful health checks
before an entry is considered healthy. Valid values are 1-65535. The default is
1.
c. Specify the sick interval, in seconds, between health checks to the server that
has been determined to be sick or out of service. The default is 10. The sick
interval is between 1 second and 31536000 seconds (about 1 year).
d. Specify the sick threshold, or the number of failed health checks before an
entry is considered sick. Valid values are 1-65535. The default is 1.
210
Chapter 14: Health Checks
e. Specify the failure trigger for the number of failed connections to the server
before a health check is triggered.Valid values are between 1 and 2147483647.
The failures are reported back to the health check as a result of either a connection
failure or a response error. The number of these external failures is cleared every
time a health check is completed. If the number of failures listed meets or exceeds
the threshold, and the health check is idle and not actually executing, then the
health of the device or service is immediately checked.
f. Specify the maximum response time threshold, in milliseconds. The threshold
time can be between 1 and 65535.
6. Click OK.
7. Click Apply to commit the changes to the SG appliance.
211
Volume 5: Advanced Networking
5. Select the check boxes to override. You can cancel your choices by clicking Clear all
overrides.
212
Chapter 14: Health Checks
a. Override E-mail notification: Select the appropriate check boxes to enable the
email notifications you required. Specify recipients in Maintenance > Event
Logging > Mail.
b. Event logging: Select the appropriate check boxes to enable the event logging
you need. Messages can be logged as either informational or severe.
c. SNMP traps: Select the situations in which you want SNMP traps to be sent.
d. Click OK.
e. Click OK.
213
Volume 5: Advanced Networking
Note: You can create groups in the Configuration > Forwarding > Forwarding Hosts
tab or Configuration > Forwarding > SOCKS Gateways tab.
By default, if any of the members of the group are healthy, then the group is considered
healthy. You can specify the number of group members that must be healthy for the group
to be considered healthy.
214
Chapter 14: Health Checks
215
Volume 5: Advanced Networking
c. Select the port setting you require. If you select Use Port, enter the new port
number.
d. To change the default settings for this test, click Override the default settings.
• Select the check boxes to override. Cancel your choices by clicking Clear all
overrides. For detailed information about configuring healthy and sick
intervals and thresholds, see “Changing Health Check Default Settings” on
page 208.
• Click OK.
e. To change default notifications, click Override the default notifications. By
default, no notifications are sent for any health checks.
• Select the check boxes to override. You can cancel your choices by clicking
Clear all overrides. For detailed information about configuring notifications,
see “Configuring Health Check Notifications” on page 211.
• Click OK .
f. Click OK.
5. Click Apply to commit the changes to the SG appliance.
Note: The only way to add or delete group members to the automatically generated
health check tests is to add and remove members from the actual forwarding or
SOCKS gateway group. The automatically generated health check is then updated.
1. Select Configuration > Health Checks > General > Health Checks.
2. Select the forwarding or SOCKS gateways group health check you need to modify.
3. Click Edit.
216
Chapter 14: Health Checks
b. Select the Minimum number of users that must be healthy for group to be
healthy from the drop-down list.
c. To create notification settings, click Override the default notifications.
• Select the check boxes. Cancel your choices by clicking Clear all overrides. For
detailed information about configuring notifications, see “Configuring Health
Check Notifications” on page 211.
• Click OK.
d. Click OK.
217
Volume 5: Advanced Networking
Note: The names of the ICAP and Websense off-box services and service groups can
be a maximum of 64 characters long, a change from previous releases, which allowed
names to be a maximum of 127 characters. If a previously existing name exceeds 64
characters, the service or service group continues to function normally but no
corresponding health check type is created.
The tests for each of the external services are specialized tests devised for each particular
kind of external service. The health check system conducts external service tests by
sending requests to the external services system, which reports back a health check result.
Note: You can run a health check on any health check on the Configuration > Health
Checks > General > Health Checks tab by selecting the health check and clicking
Perform health check.
The settings you can change on automatically generated ICAP, Websense off-box, and
DRTR rating service tests are:
❐ Enabled state
❐ Override default settings
❐ Override default notifications
218
Chapter 14: Health Checks
Note: DRTR has settings that differ from the defaults for other external
services: 10800 seconds (3 hours) for the interval, and 1 for the failure trigger.
• Click OK.
d. To change default notifications, click Override the default notifications. By
default, no notifications are sent for any health checks.
• Select the check boxes. Cancel your choices by clicking Clear all overrides. For
detailed information about configuring notifications, see “Configuring Health
Check Notifications” on page 211.
• Click OK.
e. Click OK.
5. Click Apply to commit the changes to the SG appliance.
219
Volume 5: Advanced Networking
Note: The only way to add or delete group members to the automatically generated
health check tests is to add and remove members from the ICAP or Websense off-box
services. The automatically generated health check type is then updated.
1. Select Configuration > Health Checks > General > Health Checks.
2. Select the external service group health check to modify. Groups are identified in the
Type column.
3. Click Edit.
220
Chapter 14: Health Checks
Note: Frequent testing of specific Internet sites by a large number of systems can
result in that Internet site objecting to the number of hits.
221
Volume 5: Advanced Networking
When configuring user-defined host health check types, keep in mind the following:
❐ User-defined host health checks are created and deleted manually.
❐ All individual user-defined tests consider the target to be a server.
❐ To conduct proxy HTTP/HTTPS tests, a proxy must be defined as a forwarding host,
set up between the originating device and the target, and forwarding policy must
cause the test to be directed through the proxy.
❐ For an ICMP test, a hostname is specified in the health check configuration.
❐ The TCP and SSL tests support SOCKS gateway policy, based on a URL of tcp://
<hostname>:<port>/ and ssl://<hostname>:<port>/, respectively, using a hostname and
port supplied in health check configuration.
❐ An HTTP/HTTPS test requires a full URL. The port used for this test is as specified in
that URL. If no port is explicitly specified in the URL, the port defaults to the standard
value for these protocols of 80 or 443. The server being tested is assumed to support
whatever port is indicated.
Forwarding and SOCKS gateway policy is applied based on the URL. The HTTPS or
SSL tests use all the server certificate settings in the SSL layer in policy. For a
forwarding host, all the sever certificate settings in the SSL layer also apply, and if
present, override the forwarding host configuration setting.
Note: None of the above tests apply to user-defined composite health checks, which
only consist of a set of members and a setting to combine the results.
Note: Automatically generated group tests and user-defined composite tests are not
the same.
Group tests are automatically generated; they cannot be deleted. Some editing is
permitted, but you cannot add or remove members of the group through the health
checks module (you must modify the forwarding or SOCKS gateways groups to
update the automatically generated group tests).
For a group's test, the default is for the group to be healthy if any member is healthy.
For a composite’s test, the default is for the group to be healthy if all members are
healthy. (The default is configurable.)
222
Chapter 14: Health Checks
Note: You cannot create user-defined health checks for external service tests, such as
ICAP, Websense off-box, and the DRTR rating service.
The following procedure explains how to create a user-defined host health check. To
create a user-defined composite health check, continue with “To create a user-defined
composite health check:” on page 224.
3. Select the type of test to configure from the Type of test drop-down list. To configure a
composite test, see “To create a user-defined composite health check:” on page 224.
223
Volume 5: Advanced Networking
The options you can select vary with the type of health check. The example above
uses the HTTP/HTTPS options. Options for other tests are explained in this
procedure, as well.
a. Enter a name for the health check.
b. Select the Enabled state radio button to the required setting.
c. If you are configuring an SSL or TCP health check, enter the port to use.
d. If you are configuring an ICMP, SSL, or TCP health check, enter the hostname
of the health check’s target.
e. For HTTP/HTTPS only:
• Enter the URL address of the target.
• To use Basic user authentication, select the check box and enter the username
and password of the target.
• To use Basic proxy authentication because intermediate proxies might be
between you and the target, select the check box and enter the username and
password of the target.
• To manage a list of HTTP/HTTPS response codes that are considered
successes, enter the list in the Allowed Response Code field, separated by
semi-colons. If one of them is received by the health check then the health
check considers the HTTP(S) test to have been successful.
Note: The 200 response code is added by default. The list must always have
at least one member.
f. To change the default settings for this test, click Override the default settings.
• Select your override settings. Cancel your choices by clicking Clear all
overrides. For detailed information about configuring healthy and sick
intervals and thresholds, see “Changing Health Check Default Settings” on
page 208.
• Click OK.
g. To change the default notifications for this test, click Override the default
notifications. By default, no notifications are sent for any health checks.
• Select the check boxes to override. You can cancel your choices by clicking
Clear all overrides. For detailed information about configuring notifications,
see “Configuring Health Check Notifications” on page 211
• Click OK.
h. Click OK.
4. Click Apply to commit the changes to the SG appliance.
224
Chapter 14: Health Checks
• Select the check boxes to override. You can cancel your choices by clicking
Clear all overrides. For detailed information about configuring notifications,
see “Configuring Health Check Notifications” on page 211
• Click OK.
f. Click OK.
225
Volume 5: Advanced Networking
If the target does not match the source type, the copy operation fails and sends an
error message.
226
Chapter 14: Health Checks
Section G: Statistics
Section G: Statistics
You can view but not edit the health check state from the Statistics > Health Check tab. To
manage health checks, go to the Configuration > Health Checks > General tab.
Functioning with errors (multiple One or more IP addresses have errors but Healthy
IP addresses) none are down.
Functioning only for some One or more IP addresses are down but Healthy
addresses (multiple IP addresses) not all.
Functioning but going down Failures are occurring, but the IP address Healthy
(single IP address) is not yet down.
227
Volume 5: Advanced Networking
Section G: Statistics
In addition to status messages, you can see whether the health check is enabled. Enabled
states are:
❐ Enabled
❐ Disabled, reporting success
❐ Disabled, reporting failure
228
Volume 5: Advanced Networking
229
Volume 5: Advanced Networking
Note: For detailed information about using these commands, refer to Volume 11:
Command Line Reference.
230
Volume 5: Advanced Networking
231
Volume 5: Advanced Networking
232
Chapter 15: TCP/IP Configuration
Use the TCP/IP configuration options to enhance the performance and security of the
SG appliance. Except for IP Forwarding (refer to Volume 2: Proxies and Proxy Services),
these commands are only available through the CLI.
❐ RFC-1323: Enabling RFC-1323 support enhances the high-bandwidth and long-
delay operation of the SG appliances over very high-speed paths, ideal for satellite
environments.
❐ TCP NewReno: Enabling TCP NewReno support improves the fast recovery of the
appliances.
❐ ICMP Broadcast Echo: Disabling the response to these messages can limit security
risks and prevent an attacker from creating a distributed denial of service (DDoS) to
legitimate traffic.
❐ ICMP Timestamp Echo: Disabling the response to these messages can prevent an
attacker from being able to reverse engineer some details of your network
infrastructure.
❐ TCP Window Size: Configures the amount of unacknowledged TCP data that the
SG appliance can receive before sending an acknowledgement.
❐ PMTU Discovery: Enabling PMTU Discovery prevents packets from being unable
to reach their destination because they are too large.
To view the TCP/IP configuration, see “Viewing the TCP/IP Configuration” on page
236.
This section discusses
❐ "RFC-1323" on page 233
❐ "TCP NewReno" on page 234
❐ "ICMP Broadcast Echo Support" on page 234
❐ "ICMP Timestamp Echo Support" on page 234
❐ "TCP Window Size" on page 235
❐ "PMTU Discovery" on page 235
❐ "TCP Time Wait" on page 235
❐ “TCP Loss Recovery Mode” on page 236
❐ "Viewing the TCP/IP Configuration" on page 236
RFC-1323
The RFC-1323 TCP/IP option enables the SG appliance to use a set of extensions to TCP
designed to provide efficient operation over large bandwidth-delay-product paths and
reliable operation over very high-speed paths, including satellite environments. RFC-
1323 support can be configured through the CLI and is enabled by default.
233
Volume 5: Advanced Networking
TCP NewReno
NewReno is a modification of the Reno algorithm. TCP NewReno improves TCP
performance during fast retransmit and fast recovery when multiple packets are dropped
from a single window of data. TCP NewReno support is enabled by default.
234
Chapter 15: TCP/IP Configuration
PMTU Discovery
PMTU (Path Maximum Transmission Unit) is a mechanism designed to discover the
largest packet size sent that is not fragmented anywhere along the path between two
communicating appliances that are not directly attached to the same link.
An SG appliance that is not running PMTU might send packets larger than that allowed by
the path, resulting in packet fragmentation at intermediate routers. Packet fragmentation
affects performance and can cause packet discards in routers that are temporarily
overtaxed.
An SG appliance doing PMTU sets the Do-Not-Fragment bit in the IP header when
transmitting packets. If fragmentation becomes necessary before the packets arrive at the
second SG appliance, a router along the path discards the packets and returns an ICMP
Host Unreachable error message, with the error condition of Needs-Fragmentation, to
the original SG appliance. The first SG appliance then reduces the PMTU size and re-
transmits the transmissions.
The discovery period temporarily ends when the SG appliance estimates the PMTU is low
enough that its packets can be delivered without fragmentation or when the SG appliance
stops setting the Do-Not-Fragment bit.
Following discovery and rediscovery, the size of the packets that are transferred between
the two communicating nodes dynamically adjust to a size allowable by the path, which
might contain multiple segments of various types of physical networks.
PMTU is disabled by default.
235
Volume 5: Advanced Networking
To change the MSL value, enter the following commands at the (config) command
prompt:
SGOS#(config) tcp-ip tcp-2msl seconds
where seconds is the length of time you chose for the 2MSL value. Valid values are 1
to 16380 inclusive.
236
Chapter 16: Virtual IP Addresses
Virtual IP (VIP) addresses are addresses assigned to a system (but not an interface) that
are recognized by other systems on the network. Up to 255 VIPs can be configured on
each SG appliance. They have several uses:
❐ Assign multiple identities to a system on the same or different network, partitioning
the box in to separate logical entities for resource sharing or load sharing.
❐ Create an HTTPS Console to allow multiple, simultaneous, secure connections to
the system.
❐ Direct authentication challenges to different realms.
❐ Set up failover among multiple SG appliances on the same subnet.
Note: For information on creating an HTTPS Console, refer to Volume 2: Proxies and
Proxy Services; for information on using VIPs with authentication realms, refer to
Volume 4: Securing the Blue Coat SG Appliance; to use VIPs with failover, see Chapter 7:
"Configuring Failover" on page 97.
To create a VIP:
1. Select Configuration > Network > Advanced > VIPs.
2. Click New.
3. Enter the virtual IP address you want to use. It can be any IP address, except a
multicast address. (A multicast address is a group address, not an individual IP
address.)
Note: You cannot create a VIP address that is the IP address used by the origin
content server. You must assign a different address on the SG appliance, and use
DNS or forwarding to point to the origin content server's real IP address.
4. Click OK.
5. Click Apply to commit the changes to the SG appliance.
The VIP address can now be used.
237
Volume 5: Advanced Networking
238
Chapter 17: WCCP Settings
The SGOS software can be configured to participate in a WCCP (Web Cache Control
Protocol) scheme, in which a WCCP-capable router collaborates with a set of WCCP-
configured SG appliances to service requests.
Overview
WCCP is a Cisco®-developed protocol that allows you to establish redirection of the
traffic that flows through routers.
The main benefits of using WCCP are:
❐ Scalability. With no reconfiguration overhead, redirected traffic can be
automatically distributed to up to 32 appliances.
❐ Redirection safeguards. If no appliances are available, redirection stops and the
router forwards traffic to the original destination address.
WCCP has two versions, version 1 and version 2, both of which are supported by Blue
Coat. However, only one protocol version can be active on the SG appliance at a time.
The active WCCP protocol set up in the SG configuration file must match the version
running on the WCCP router.
For information on using WCCP Version 1, see Appendix C: "Using WCCP" on page
267.
WCCP Version 2
For Cisco routers using WCCP version 2, minimum IOS releases are 12.0(3)T and
12.0(4). Release 12.0(5) and later releases support WCCP versions 1 and 2. Ensure that
you use the correct IOS software for the router and that you have a match between the
SG configuration WCCP version number and router protocol version number.
WCCP version 2 protocol offers the same capabilities as version 1, along with increased
protocol security and multicast protocol broadcasts. Version 2 multicasting allows
caches and routers to discover each other through a common multicast service group
and matching passwords. In addition, up to 32 WCCP-capable routers can
transparently redirect traffic to a set of up to 32 appliances. Version 2 WCCP-capable
routers are capable of redirecting IP traffic to a set of appliances based on various fields
within those packets.
239
Volume 5: Advanced Networking
Note: Blue Coat recommends that WCCP-compliant caches from different vendors be
kept separate and that only one vendor’s routers be used in a service group.
One of the caches participating in the WCCP service group is automatically elected to
configure the home router’s redirection tables. This way, caches can be transparently
added and removed from the WCCP service group without requiring operator
intervention. WCCP version 2 supports multiple service groups.
The figure below illustrates a WCCP version 2 implementation using multiple routers and
appliances. In this scenario, routers 1 through n and caches 1 through m participate in the
same service group. As in version 1, an appliance from the group is selected to define the
redirection hash table in all routers for all caches. All caches periodically communicate
with all routers to verify WCCP protocol synchronization and appliance and router
availability within the service group. In return, each router responds to caches with
information as to what caches and discovered routers are available in the service group.
Figure 17-1. A Version 2 Configuration Using Packet Redirection to Multiple Routers and Caches
Procedure Overview
Two tasks must be completed to get WCCP running:
❐ Configuring the router
❐ Configuring the SG appliance
240
Chapter 17: WCCP Settings
Note: You can also use the Management Console > Configuration > Network >
Advanced > WCCP to install the WCCP configuration file and enable WCCP.
The rest of this chapter discusses the SG appliance WCCP configuration file. For detailed
information on using WCCP, see Appendix C: "Using WCCP" on page 267.
Note: The appliance does not ship with a default WCCP configuration file.
241
Volume 5: Advanced Networking
242
Chapter 17: WCCP Settings
Using Figure 17-2, below, all caches would be assigned 1/m of the redirection hash table,
but since Cache 2 and Cache 3 are physically located within the same appliance, that
appliance is actually assigned 2/m of the redirection hash table.
Figure 17-2. A Version 2 Configuration Using Multicast Packet Redirection to Multiple Routers,
Multiple Caches, and a Service Group
Assigning Percentages
You can override the default of each SG appliance being assigned roughly an even
percentage; the relative distribution of the redirection hash table can be specified for each
cache. Multiple hash-distributions are supported. Also, all, none, or part of a source and/
or destination IP address or port number can be used in the hash. Each SG appliance can
be assigned a primary-hash-weight value to determine the proportion of the 256-element
hash table to be assigned.
If all caches are configured with a 0 primary-hash-weight value (the default) then each SG
appliance is assigned an equal proportion of the redirection hash table. However, if any
SG appliance is configured with a non-zero primary-hash-weight, each SG appliance is
assigned a relative proportion of the table.
For instance, consider a configuration with five caches that use a primary-hash-weight
defined as {25, 200, 0, 50, 25}. The total requested weight value is 25+200+0+50+25=300
and, therefore, the proportion of the hash table assigned to each SG appliance is 25/300,
200/300, 0/300, 50/300, and 25/300.
Because one cache did not specify a non-zero primary-hash-weight, that cache is assigned
any elements within the redirection hash table and, therefore, does not receive any
redirected traffic. Also, the hash weight can be specified for each caching member within a
SG appliance. In Figure 17-2, Cache 2 and Cache 3 can be assigned different weight values.
243
Volume 5: Advanced Networking
To balance the redirection traffic load among the caches, a service group can be configured
to use an alternate hash function when the number of GRE packets forwarded to the cache
exceeds a certain number. (If you use L2 forwarding, the SG appliance counts MAC
addresses.) Therefore, when a router receives an IP packet that hashes to an element
flagged as a hot spot, the alternate hash function is computed. The appliance specified by
the new index in the redirection hash table receives the redirected packet.
Each SG appliance can dynamically determine a hot spot within its assigned portion of the
redirection hash table.
Alternate hash tables are only used for dynamic service groups that specify alternate-hash
flags within their service-flags. The default Web-cache service group cannot use an
alternate hash table. Instead, a comparable dynamic service group must be created.
To use hot spot detection, the SG appliance’s WCCP configuration file must specify:
service-flags source-ip-hash
service-flags destination-port-alternate-hash
244
Chapter 17: WCCP Settings
web-cache Enables the Web cache service group. If using the Web-cache service group for
WCCP, the dynamic service group settings (priority, protocol, service
flags, and ports) are not applicable.
service-number The identification number of the dynamic service group being controlled by the
router. Services are identified using a value from 0 to 99. The reverse-proxy service
is indicated using the value 99.
priority-number (Applies to a dynamic service group only. A dynamic service group is one
identified by a service number.) Establishes queuing priorities for all defined
service groups, based on a priority number from 0 through 255, inclusive.
protocol-number (Applies to a dynamic service group only. A dynamic service group is one
identified by a service number.) Number of an Internet protocol. Protocol-
number must be an integer in the range 0 through 255, inclusive, representing an
IP protocol number.
hash-bit-identifier (Applies to a dynamic service group only. A dynamic service group is one
identified by a service number.) Sets the hash index, for load balancing purposes.
The key associated with the hash-bit-identifier you specify is hashed to
produce the primary redirection hash table index. For instance, if only the
destination-ip-hash flag is set, then the packet destination IP address is used
to determine the index. The index is constructed by starting with an initial value of
zero and then computing an exclusive OR (XOR) of the fields specified in the hash-
bit identifier.
If alternative hashing has been enabled, any alternate hash flags are processed in
the same way and produce a secondary redirection hash table index. Alternate
hash flags end with the suffix “-alternate-hash.”
For more information using the hashing table, see “Understanding Cache Load
Balancing” on page 242.
source-ip-hash Sets the source IP bit definition within the redirection hash table index.
(hash-bit-identifier)
destination-ip-hash Sets the source IP bit definition within the redirection hash table index.
(hash-bit-identifier)
source-port-hash Sets the source port bit definition within the redirection hash table index.
(hash-bit-identifier)
destination-port-hash Sets the destination port bit definition within the redirection hash table index.
(hash-bit-identifier)
ports-defined Sets the port bit definition within the redirection hash table index.
(hash-bit-identifier)
245
Volume 5: Advanced Networking
ports-source Sets the source port bit definition within the redirection hash table index.
(hash-bit-identifier)
source-ip-alternate- Sets the alternate source IP bit definition within the redirection hash table index.
hash
(hash-bit-identifier)
destination-ip- Sets the alternate destination IP bit definition within the redirection hash table
alternate-hash index.
(hash-bit-identifier)
source-port- The alternate source port bit definition within the redirection hash table index.
alternate-hash
(hash-bit-identifier)
destination-port- Sets the alternate destination port bit definition within the redirection hash table
alternate-hash index.
(hash-bit-identifier)
multicast-ttl Sets the multicast TTL value per WCCP service group. The value must be set
between 1 and 255.
If the multicast TTL value is not set, the default value is 1. If the home-router
address is not multicast, this command is non-operational.
port1…port8 (Applies to a dynamic service group only. A dynamic service group is one
identified by a service number.) A zero-terminated list of TCP port identifiers.
Note that this must be a list of exactly eight ports.
If the service-flags ports-defined flag is set, packets are matched against the set of
ports supplied. If the service-flags ports-source flag is set, the ports are
assumed to be source ports. Otherwise, the ports are assumed to be destination
ports.
ip-address Indicates the IP address of your network's home router. For version 2, ip-
address can be a multicast address. (Multicast addresses are in the range
224.0.0.0 to 239.255.255.255, inclusive.)
In version 2, multiple IP addresses can be specified for unicast addressing. For
multicast addresses, only one IP address can be specified per service group.
If you choose to specify the home router IP address, it is important that the actual
home router IP address and the home router IP address specified in this SG
configuration file match. If you do not already know the IP address of the home
router, you can easily determine it from the router CLI by using the show ip
wccp command.
domain-name Specifies the domain name of your network's home router. Domain-name must be
a valid domain name string that successfully resolves on DNS lookup.
interface-number Specifies the adapter interface number for the service group. You cannot use a
colon (0:0 or 0:1, for example).
string (Applies to a dynamic service group only. A dynamic service group is one
identified by a service number.) String can be at least one, and not more than eight,
alphanumeric characters long.
The password string specified here must match the password string declared for
the router.
interface-number (When used with the hash identifiers) Specifies the adapter interface to which the
weight factor is applied to alter the distribution of the primary hash table.
246
Chapter 17: WCCP Settings
value Specifies the weight factor value (0 through 255) that is applied to the adapter
interface specified to alter the distribution of the primary hash table.
forwarding-type Switches between GRE encapsulation (the default) and L2 MAC address rewrite
[GRE|L2] for forwarding packets. If this command is not present, GRE encapsulation is used.
You can create a configuration file customized for the environment through the CLI inline
commands or through a text file. The CLI inline commands enable WCCP on the SG
appliance immediately; the drawback is that if any information changes, you must re-
create the whole file using the inline command. With a text file, if any information
changes, you can change the individual line; the drawback is that you must download the
file again from an HTTP server to the SG appliance.
To use CLI commands to create a configuration file, continue with the next procedure. To
use a text editor to create a configuration file, continue with “Creating a Configuration
File using a Text File” on page 247.
247
Volume 5: Advanced Networking
For examples of various types of WCCP configurations, see Appendix C: "Using WCCP"
on page 267.
To create a configuration file using a text editor and load the file on an SG
appliance:
1. Open a text editor.
2. Using the commands described in “Syntax to create a customized configuration file:”
on page 244, enter the arguments you need.
3. Copy the configuration file to an HTTP server so that it can be downloaded to the SG
appliance.
4. Enable WCCP and download the WCCP configuration file using the following syntax:
wccp {enable | disable | no} [path config-file-url] | [version version-
number]
where:
no Indicates that you want to clear the current WCCP configuration settings.
version-number Indicates the version of WCCP that your router is configured to use. If
version version-number is omitted, it is assumed to be 2.
For example:
SGOS#(config) wccp enable
SGOS#(config) wccp path http://205.66.255.10/files/wccp.txt
SGOS#(config) load wccp-settings
Statistics
WCCP Statistics can be viewed by going to Management Console > Statistics > Advanced
and scrolling down to the WCCP Statistics.
The definitions for the WCCP statistics are defined as:
248
Chapter 17: WCCP Settings
Notes
If you use IP spoofing with WCCP, do the following for best results:
❐ The ip wccp redirect exclude in command should be applied to the adapter to
which the SG appliance is attached.
❐ For L2 forwarding, the SG appliance should be directly connected to the router
interface.
249
Volume 5: Advanced Networking
250
Appendix A: Glossary
access log A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.
account A named entity that has purchased the appliance or the Entitlements from Blue Coat.
activation code A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.
active content stripping Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.
active content types Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user
administration access policy A policy layer that determines who can access the SG appliance to perform
administrative tasks.
administration A policy layer that determines how administrators accessing the SG appliance must
authentication policy authenticate.
Application Delivery A WAN that has been optimized for acceleration and compression by Blue Coat. This
Network (ADN) network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.
ADN backup manager Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.
ADN manager Responsible for publishing the routing table to SG Clients (and to other SG
appliances).
ADN optimize attribute Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
asx rewrite Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxy-
like support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.
audit A log that provides a record of who accessed what and how.
249
Volume 5: Advanced Networking
authenticate-401 attribute All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios
authenticated content Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).
authentication Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate Authority.
See also basic authentication, proxy authentication, and SSL authentication.
authentication realm Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.
bandwidth class hierarchy Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.
bandwidth management Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.
basic authentication The standard authentication for communicating with the target as identified in the
URL.
BCAAA Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.
byte-range support The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).
cache An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.
cache control Allows you to configure which content the SG appliance stores.
250
Appendix A: Glossary
cache efficiency A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.
cache hit Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.
cache miss Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .
cache object Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.
Certificate Authority (CA) A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.
child class (bandwidth gain) The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.
client consent certificates A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.
client-side transparency A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.
concentrator An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.
content filtering A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.
default boot system The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.
denial of service (DoS) A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.
251
Volume 5: Advanced Networking
destination objects Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.
detect protocol attribute Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
diagnostic reporting Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.
directives Commands used in installable lists to configure forwarding and SOCKS gateway.
DNS access A policy layer that determines how the SG appliance processes DNS requests.
domain name system (DNS) An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.
dynamic bypass Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.
dynamic real-time rating Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
(DRTR) dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.
early intercept attribute Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.
ELFF-compatible format A log type defined by the W3C that is general enough to be used with any protocol.
emulated certificates Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.
encrypted log A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.
event logging Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.
252
Appendix A: Glossary
explicit proxy A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.
extended log file format A variant of the common log file format, which has two additional fields at the end of
(ELFF) the line—the referer and the user agent fields.
fail open/closed Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.
forward proxy A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.
gateway A device that serves as entrance and exit into a communications network.
hardware serial number A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.
health check tests The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
• ICMP
• TCP
• SSL
• HTTP
• HTTPS
• Group
• Composite and reference to a composite result
• ICAP
• Websense
• DRTR rating service
253
Volume 5: Advanced Networking
health check type The kind of device or service the specific health check tests. The following types are
supported:
• Forwarding host and forwarding group
• SOCKS gateway and SOCKS gateway group
• CAP service and ICAP service group
• Websense off-box service and Websense off-box service group
• DRTR rating service
• User-defined host and a user-defined composite
heartbeat Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.
host affinity The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.
host affinity timeout The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.
inbound traffic (bandwidth Network packets flowing into the SG appliance. Inbound traffic mainly consists of
gain) the following:
• Server inbound: Packets originating at the origin content server (OCS) and sent to
the SG appliance to load a Web object.
• Client inbound: Packets originating at the client and sent to the SG appliance for
Web requests.
installable lists Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
• Creating the list using the SG text editor
• Placing the list at an accessible URL
• Downloading the directives file from the local system
integrated host timeout An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.
intervals Time period from the completion of one health check to the start of the next health
check.
IP reflection Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.
254
Appendix A: Glossary
issuer keyring The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.
licensable component (LC) (Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.
license Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.
listener The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.
live content Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.
load balancing A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.
local bypass list A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.
local policy file Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).
log facility A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.
log format The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.
log tail The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.
255
Volume 5: Advanced Networking
Management Console A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.
management information Defines the statistics that management systems can collect. A managed device
base (MIB) (gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.
maximum object size The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.
MIME/FILE type filtering Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.
multi-bit rate The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).
multicast Used in streaming; the ability for hundreds or thousands of users to play a single
stream.
multicast aliases Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel
multicast station Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).
multimedia content services Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.
name inputing Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server
native FTP Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).
NCSA common log format Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.
network address translation The process of translating private network (such as intranet) IP addresses to Internet
(NAT) IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.
256
Appendix A: Glossary
non-cacheable objects A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
• Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
• Password provided, requests that include a client password.
• Data in request that include additional client data.
• Not a GET request.
.nsc file Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.
NTP To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.
object (used in caching) An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.
object (used in Visual Policy An object (sometimes referred to as a condition) is any collection or combination of
Manager) entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.
object pipelining This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.
origin content server (OCS) Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.
outbound traffic (bandwidth Network packets flowing out of the SG appliance. Outbound traffic mainly consists
gain) of the following:
• Client outbound: Packets sent to the client in response to a Web request.
• Server outbound: Packets sent to an OCS or upstream proxy to request a service.
PAC (Proxy Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
AutoConfiguration) scripts port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.
packet capture (PCAP) Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.
257
Volume 5: Advanced Networking
parent class (bandwidth A class with at least one child. The parent class must share its bandwidth with its
gain) child classes in proportion to the minimum/maximum bandwidth values or priority
levels.
passive mode data Data connections initiated by an FTP client to an FTP server.
connections (PASV)
policies Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.
policy-based bypass list Used in policy. Allows a bypass based on the properties of the client, unlike static and
dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.
policy layer A collection of rules created using Blue Coat CPL or with the VPM.
pragma: no cache (PNC) A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).
proxy Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.
proxy service The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.
proxy service (default) The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.
public key certificate An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).
public virtual IP (VIP) Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.
258
Appendix A: Glossary
real-time streaming protocol A standard method of transferring audio and video and other time-based media over
(RTSP) Internet-technology based networks. The protocol is used to stream clips to any RTP-
based client.
reflect client IP attribute Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.
registration An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.
remote authentication dial- Authenticates user identity via passwords for network access.
in user service (RADIUS)
reverse proxy A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.
routing information protocol Designed to select the fastest route to a destination. RIP support is built into Blue
(RIP) Coat appliances.
router hops The number of jumps a packet takes when traversing the Internet.
secure shell (SSH) Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.
serial console A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.
server certificate categories The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.
server portals Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping a
set of external URLs onto a set of internal URLs.
server-side transparency The ability for the server to see client IP addresses, which enables accurate client-
access records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.
service attributes Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .
259
Volume 5: Advanced Networking
SG appliance A Blue Coat security and cache box that can help manage security and content on a
network.
sibling class (bandwidth A bandwidth class with the same parent class as another class.
gain)
simple network The standard operations and maintenance protocol for the Internet. It uses MIBs,
management protocol created or customized by Blue Coat, to handle (needs completion).
(SNMP)
simulated live Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.
SmartReporter log type A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.
SOCKS A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.
SOCKS proxy A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.
splash page Custom message page that displays the first time you start the client browser.
split proxy Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
• Mapi Proxy
• SSL Proxy
SQUID-compatible format A log type that was designed for cache statistics and is compatible with Blue Coat
products.
squid-native log format The Squid-compatible format contains one line for each request.
SSL authentication Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).
SSL proxy A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.
static route A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.
260
Appendix A: Glossary
statistics Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated, cache
efficiency, cached contents, and custom URLs generated by the appliance for various
kinds of logs. You can also check the event viewer for every event that occurred since
the appliance booted.
stream A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.
SurfControl log type A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.
system cache The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.
time-to-live (TTL) value Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.
traffic flow Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
(bandwidth gain) that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of
these connections, traffic flows in two directions—in one direction, packets flow out
of the SG appliance (outbound traffic), and in the other direction, packets flow into
the SG (inbound traffic). Connections can come from the client or the server. Thus,
traffic can be classified into one of four types:
• Server inbound
• Server outbound
• Client inbound
• Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.
transmission control TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
protocol (TCP) in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.
transparent proxy A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.
261
Volume 5: Advanced Networking
trial period Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.
unicast alias Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicast-
alias command to request the content from the origin streaming server.
universal time coordinates An SG appliance must know the current UTC time. By default, the appliance
(UTC) attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.
URL rewrite rules Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.
WCCP Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.
Web FTP Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
OCS (if the content is not already cached), and then translates the FTP response with
the file contents into an HTTP response for the client.
Websense log type A Blue Coat proprietary log type that is compatible with the Websense reporter tool.
262
Appendix B: Using Policy to Manage Forwarding
After ICP, forwarding, and the SOCKS gateways are configured, use policy to create
and manage forwarding rules. Forwarding, ICP, and SOCKS gateway rules should go
in the <Forward> layer of the Forwarding Policy file or the VPM Policy file (if you use
the VPM).
The separate <Forward> layer is provided because the URL can undergo URL rewrites
before the request is fetched. This rewritten URL is accessed as a server_url and
decisions about upstream connections are based on the rewritten URL, requiring a
separate layer. All policy commands allowed in the <Forward> layer are described
below.
Forwarding Description
Conditions
client.host= Tests the hostname of the client (obtained through RDNS). Can
also be used in <Admin>, <Proxy>, and <Exception> layers.
day= Tests if the day of the month is in the specified range or an exact
match. Can be used in all layers.
hour[.utc]= Tests if the time of day is in the specified range or an exact match.
Can be used in all layers.
im.client= Tests the type of IM client in use. Can also be used in <Proxy>,
<Exception>, and <Cache> layers.
minute[.utc]=month[.utc]= Tests if the minute of the hour is in the specified range or an exact
match. Can be used in all layers.
263
Volume 5: Advanced Networking
Forwarding Description
proxy.address= Tests the IP address of the network interface card (NIC) on which
the request arrives. Can also be used in <Admin> and <Proxy>
layers.
proxy.card= Tests the ordinal number of the network interface card (NIC)
used by a request. Can also be used in <Admin> and <Proxy>
layers.
proxy.port= Tests if the IP port used by a request is within the specified range
or an exact match. Can also be used in <Admin> and <Proxy>
layers.
server_url.address= Tests if the host IP address of the requested URL matches the
specified IP address, IP subnet, or subnet definition.
server_url.extension[.case_ Tests if the filename extension at the end of the path matches the
sensitive]= specified string.
server_url.host.has_name= Tests whether the server URL has a resolved DNS hostname.
server_url.host[.exact|.substring| Tests if the host component of the requested URL matches the IP
.prefix|.suffix|.regex][.no_lookup address or domain name.
]=
server_url.host.no_name= This is true if no domain name can be found for the URL host.
server_url.port= Tests if the port number of the requested URL is within the
specified range or an exact match.
server_url.scheme= Tests if the scheme of the requested URL matches the specified
string.
socks= This condition is true whenever the session for the current
transaction involves SOCKS to the client.
264
Appendix B: Using Policy to Manage Forwarding
Forwarding Description
streaming.client= yes | no. Tests the user agent of a Windows, Real Media, or
QuickTime player.
time[.utc]= Tests if the time of day is in the specified range or an exact match.
Can be used in all layers.
weekday[.utc]= Tests if the day of the week is in the specified range or an exact
match. Can be used in all layers.
year[.utc]= Tests if the year is in the specified range or an exact match. Can
be used in all layers.
Properties
http.refresh.recv.timeout() Sets the socket timeout for receiving bytes from the upstream
host when performing refreshes. Can also be used in <Cache>
layers.
http.server.recv.timeout() Sets the socket timeout for receiving bytes from the upstream
host. Can also be used in <Proxy> layers.
icp() Determines when to consult ICP. The default is yes if ICP hosts
are configured and if no forwarding host or SOCKS gateway is
identified as an upstream target.
265
Volume 5: Advanced Networking
Forwarding Description
trace.destination() Used to change the default path to the trace output file. By
default, policy evaluation trace output is written to an object in
the cache accessible using a console URL of the following form:
http://SG_ip_address:8081/Policy/
Trace/path
Actions
notify_snmp() The SNMP trap is sent when the transaction terminates. Can be
used in all layers.
Definitions
define server_url.domain condition Binds a user-defined label to a set of domain suffix patterns for
name use in a condition= expression.
266
Appendix C: Using WCCP
Overview
WCCP is a Cisco®-developed protocol that allows you to establish redirection of the
traffic that flows through routers.
WCCP Version 1
In WCCP version 1, the WCCP-configured home router transparently redirects TCP
port 80 packets to a maximum of 32 appliances. (An SG appliance is seen as a cache in
WCCP protocol.)
One of the caches participating in the WCCP service group is automatically elected to
configure the home router’s redirection tables. This way, caches can be transparently
added and removed from the WCCP service group without requiring operator
intervention. WCCP version 1 supports only a single service group.
Each applicable client IP packet received by the home router is transparently redirected
to a cache. An SG appliance from the group is selected to define the home router’s
redirection hash table for all caches. All caches periodically communicate with the
home router to verify WCCP protocol synchronization and SG availability within the
service group. In return, the home router responds to each cache with information as to
which appliances are available in the service group.
267
Volume 5: Advanced Networking
❐ For Cisco routers using WCCP version 1, minimum IOS releases are 11.1(18)CA and
11.2(13)P. Note that releases prior to IOS 12.0(3)T only support WCCP version 1.
Ensure that you are using the correct IOS software for the router and that the SG
configuration protocol version number and router protocol version number match.
For more information on WCCP Version 1, refer to the Cisco Web site. The rest of this
appendix discusses WCCP version 2 only.
WCCP Version 2
For Cisco routers using WCCP version 2, minimum IOS releases are 12.0(3)T and 12.0(4).
Release 12.0(5) and later releases support WCCP versions 1 and 2. Ensure that you use the
correct IOS software for the router and that you have a match between the SG
configuration WCCP version number and router protocol version number.
WCCP version 2 protocol offers the same capabilities as version 1, along with increased
protocol security and multicast protocol broadcasts. Version 2 multicasting allows caches
and routers to discover each other through a common multicast service group and
matching passwords. In addition, up to 32 WCCP-capable routers can transparently
redirect traffic to a set of up to 32 appliances. Version 2 WCCP-capable routers are capable
of redirecting IP traffic to a set of appliances based on various fields within those packets.
Version 2 allows routers and caches to participate in multiple, simultaneous service
groups. Routers can transparently redirect IP packets based on their formats. For example,
one service group could redirect HTTP traffic and another could redirect FTP traffic.
Note: Blue Coat recommends that WCCP-compliant caches from different vendors be
kept separate and that only one vendor’s routers be used in a service group.
One of the caches participating in the WCCP service group is automatically elected to
configure the home router’s redirection tables. This way, caches can be transparently
added and removed from the WCCP service group without requiring operator
intervention. WCCP version 2 supports multiple service groups.
The figure below illustrates a WCCP version 2 implementation using multiple routers and
Appliances. In this scenario, routers 1 through n and caches 1 through m participate in the
same service group. As in version 1, an appliance from the group is selected to define the
redirection hash table in all routers for all caches. All caches periodically communicate
with all routers to verify WCCP protocol synchronization and appliance and router
availability within the service group. In return, each router responds to caches with
information as to what caches and discovered routers are available in the service group.
268
Appendix C: Using WCCP
Figure C-2. A Version 2 Configuration Using Packet Redirection to Multiple Routers and Caches
Quick Start
Two tasks must be completed to get WCCP running: configuring the router and
configuring the SG appliance. If you have a standard router and SG configuration, use the
Quick Start below. Otherwise, begin with the instructions in the procedure "To do initial
router configuration:", below, and “To create an SG appliance WCCP configuration file
and enable WCCP:” on page 269.
If you require a more complicated configuration, start with “Examples” on page 276.
269
Volume 5: Advanced Networking
If you used the inline commands, you have completed WCCP configuration for both
the router and the SG appliance and you have enabled WCCP on the SG appliance. No
further steps are needed.
2. If you used a text editor, copy the file to an HTTP server accessible to the SG
appliance.
3. Enable WCCP and download the configuration file to the SG appliance.
SGOS#(config) wccp enable
SGOS#(config) wccp path http://205.66.255.10/files/wccp.txt
SGOS#(config) load wccp-settings
For detailed information on creating and installing a WCCP configuration file for an SG
appliance, see Chapter 17: "WCCP Settings" on page 239
service-number The identification number of the cache service group being controlled by the router. Services
are identified using a value from 0 to 99. The reverse-proxy service is indicated using the
value 99, although any value can be used for reverse proxy.
270
Appendix C: Using WCCP
group-address (Optional) If no redirect list is defined (the default), all traffic is redirected. The group address
groupaddress option directs the router to use a specified multicast IP address to coalesce the “I See You”
responses to the “Here I Am” messages that it has received on this address. The group-
address argument requires a multicast address used by the router to determine which cache
engine receives redirected messages. The response is sent to the group address, as well. If no
group address is defined (the default), all “Here I Am” messages are responded to with a
unicast reply.
redirect-list (Optional) Directs the router to use an access list to control traffic redirected to the defined
access-list service group. The access-list parameter specifies either a number from 1 to 99 identifying a
predefined standard or extended access list number, or a name (up to 64 characters long)
identifying an existing standard or extended access list. The access list itself specifies which
traffic can be redirected.
group-list (Optional) If no group list is defined (the default), all caches might participate in the service
access-list group.
The group-list option directs the router to use an access list to determine which caches are
allowed to participate in the service group. The access-list parameter specifies either a
number from 1 to 99 identifying a predefined standard or extended access list number or a
name (up to 64 characters long) identifying an existing standard or extended access list. The
access list itself specifies which caches are permitted to participate in the service group.
271
Volume 5: Advanced Networking
acl_ID Names the access list you are creating. You can use either a name or number.
deny Indicates that you do not want to allow a packet to traverse the Cisco router. By default, the
router firewall denies all inbound or outbound packets unless you specifically permit access.
permit Selects a packet to traverse the PIX firewall. By default, the router firewall denies all inbound
or outbound packets unless you specifically permit access.
protocol Identifies, by name or number, an IP protocol. This parameter can be one of the keywords
icmp, ip, tcp, or udp, or an integer in the range 1 to 254 representing an IP protocol number.
To match any Internet protocol, including ICMP, TCP, and UDP, use the keyword ip.
source_addr Indicates the address of the network or host from which the packet is being sent. Use the
keyword any as an abbreviation for an address of 0.0.0.0.
source_mask Specifies the netmask bits (mask) to be applied to source_addr, if the source address is for a
network mask. Use the keyword any as an abbreviation for a mask of 0.0.0.0.
local_addr Indicates the address of the network or host local to the PIX firewall. The local_addr is the
address after NAT has been performed. Use the keyword host, followed by address, as an
abbreviation for a mask of 255.255.255.255.
local_mask Specifies the netmask bits (mask) to be applied to local_addr, if the local address is a
network mask. Use the keyword host followed by address as an abbreviation for a mask of
255.255.255.255.
272
Appendix C: Using WCCP
❐ Permitted packets from any protocol to be sent from any other network.
service-number The identification number of the cache service group being controlled by
the router. Services are identified using a value from 0 to 99. The reverse-
proxy service is indicated using the value 99.
redirect Prevents packets received on an adapter interface from being checked for
exclude in redirection. If the cache service-group is located on a separate router
interface, the possibility exists that bypass filters could be enabled on the
cache.
273
Volume 5: Advanced Networking
274
Appendix C: Using WCCP
view (Optional) Lists all members of the identified service group and whether they have
been detected.
detail (Optional) Displays IP and protocol version information about the router. Displays IP,
protocol version, state, initial and assigned hash, hash allotment, redirected packet,
and connection time information about the associated cache engine (SG appliance).
For example:
Router# show ip wccp web-cache view
275
Volume 5: Advanced Networking
186.135.77.11
186.135.77.12
Examples
This section provides detailed examples of both the router and SG configurations for:
❐ Standard HTTP redirection
❐ Standard HTTP redirection and a multicast address
❐ Standard HTTP redirection and a security password
❐ Standard transparent FTP
❐ A service group and alternate hashing
For information and examples about using WCCP, refer to http://www.cisco.com/
univercd/cc/td/doc/product/software/ios121/121cgcr/fun_r/frprt3/frd3005.htm.
Router Configuration
The following example enables standard HTTP traffic redirection on a WCCP version 2-
capable Cisco router.
Router(config)# ip wccp web-cache
Router(config)# interface ethernet 0/0
Router(config-if)# ip wccp web-cache redirect out
Router(config-if)# end
276
Appendix C: Using WCCP
SG Configuration
To enable the Web-cache service group within the SG appliance, the following
configuration file could be loaded.
# Enable WCCP to allow WCCP protocol communication between
# the ProxySG Appliance and the home router.
wccp enable
# By default, the WCCP version 2 protocol is assumed. An
# explicit “wccp version 2" command could be specified here.
service-group web-cache
# Specify the address for the router.
home-router 90.0.0.90
# Network interface 0 will participate.
interface 0
end
Router Configuration
The following example enables the standard HTTP traffic redirection on a WCCP
version 2-capable Cisco router. In this case, WCCP protocol traffic is directed to the
multicast address 226.1.1.1.
Router(config)# ip wccp web-cache group-address 226.1.1.1
Router(config)# interface ethernet 0/0
Router(config-if)# ip wccp web-cache group-listen
Router(config-if)# ip wccp web-cache redirect out
Router(config-if)# end
SG Configuration
To enable the standard Web-cache service group within the SG appliance, the following
configuration file should be loaded. In this example, both network interfaces 0 and 1
participate within the service group. Both interfaces send and receive WCCP protocol
packets by way of the multicast address.
# Enable WCCP to allow WCCP protocol communication between
# the ProxySG Appliance and the home router.
wccp enable
# By default, the WCCP version 2 protocol is assumed. An
# explicit “wccp version 2" command could be specified here.
service-group web-cache
# Specify the multicast address.
home-router 239.192.5.3
# Network interface 0 will participate.
interface 0
# Network interface 1 will also participate.
interface 1
end
277
Volume 5: Advanced Networking
Router Configuration
The following example enables standard HTTP traffic redirection on a WCCP version 2-
capable Cisco router.
Router(config)# ip wccp web-cache password 29gy8c2
Router(config)# interface ethernet 0
Router(config-if)# ip wccp web-cache redirect out
Router(config-if)# end
SG Configuration
To enable the standard WCCP version 2 service group within the SG appliance, the
following configuration file could be loaded.
# Enable WCCP to allow WCCP protocol communication between
# the ProxySG Appliance and the home router.
wccp enable
# By default, the WCCP version 2 protocol is assumed. An
# explicit “wccp version 2" command could be specified
# here.
service-group web-cache
# Specify the address for the router.
home-router 90.0.0.90
# Network interface 0 will participate.
interface 0
password 29gy8c2
end
Router Configuration
In this configuration, you create a new service group that you are dedicating to FTP
redirects.
# Enables the service group that redirects ports besides 80.
Router(config)# ip wccp 10
# Enables a service group that allows user-defined
# ports to be redirected.
Router(config)# int e0
Router(config-if)# ip wccp 10 redirect out
SG Configuration
In this configuration, you take the service group created by the router and assign the
characteristics to the group.
SGOS#(config) inline wccp eof
wccp enable
service-group 10
interface 0
home-router 10.1.1.1
protocol 6
278
Appendix C: Using WCCP
priority 1
service-flags ports-defined
service-flags destination-port-hash
ports 20 21 80 80 80 80 80 80
eof
Router Configuration
The following example enables the special SG service group on a WCCP-capable router.
Router(config)# ip wccp 99
Router(config)# interface ethernet 0/0
Router(config-if)# ip wccp 99 redirect out
Router(config-if)# end
SG Configuration
To configure the special SG service group on the appliance, a dynamic service group must
be created as illustrated by the following example.
# Enable WCCP to allow WCCP protocol communication between
# the ProxySG Appliance and the home router.
wccp enable
# By default, the WCCP version 2 protocol is assumed. An
# explicit “wccp version 2" command could be specified here.
# Service Group 99 is specially identified within the router
# as representing the ProxySG Appliance service.
service-group 99
# Specify the address for the router.
home-router 90.0.0.90
# Network interface 0 will participate.
interface 0
# Specify the TCP protocol.
protocol 6
# The hash should be based on the source IP address.
service-flags source-ip-hash
end
Router Configuration
In this configuration, you create a new service group that you are dedicating to Website
hot spots.
Router(config)# ip wccp 5
Router(config)# interface ethernet 0/0
Router(config-if)# ip wccp 5 redirect out
Router(config-if)# end
279
Volume 5: Advanced Networking
SG Configuration
To configure this special service group on the SG appliance, a dynamic service group must
be created.
# Enable WCCP to allow WCCP protocol communication between
# the ProxySG Appliance and the home router.
wccp enable
# By default, the WCCP version 2 protocol is assumed. An
# explicit “wccp version 2" command could be specified here.
# Service Group 5 is created to redirect standard HTTP
# traffic and use an alternate hash function based on the
# source IP address, if necessary.
service-group 5
# Specify the address for router 1.
home-router 90.0.0.90
# Specify the address for router 2.
home-router 90.0.1.5
# Network interface 0 will participate.
interface 0
# Specify the TCP protocol.
protocol 6
# The following two flags specify that a hash function based
# on the destination IP address should be applied first. If
# a hot-spot is detected, then an alternate hash
# function using the source IP address should be used.
service-flags destination-ip-hash
service-flags source-ip-alternate-hash
end
To verify the home router IP address matches the home router IP address listed in
the WCCP configuration:
1. From the router CLI, view the WCCP configuration:
Router#(config) show ip wccp
The home router information appears, similar to the example below:
Global WCCP information:
Router information:
Home router Identifier:195.200.10.230
Protocol Version:2.0
2. From the Blue Coat SG appliance, verify that the home router IP address specified in
the SG WCCP configuration file is the same as the actual home router IP address
discovered through the router CLI command. The following is an SG WCCP
configuration file showing the same home router IP as in the example above:
280
Appendix C: Using WCCP
SG Configuration
Use the show wccp statistics command to identify the configured home router and the
highest router IP.
SGOS#(config) show wccp statistics
Service Group ident. :512,1,9, 1,6,18,
1755,554,20,21,80,80,80,80
Home Routers :10.2.3.224 <<========Configured Home Router IP
Hotspots announced :0
Assignment state :idle
Designated Cache :10.2.3.228 <<=======Blue Coat IP
Announcement key # :2
Cache view change # :13 <<==== # times cache view changed
Router View Changed :0
Recent hit count :0
Primary hit count :0
Alternate hit count :0
Instance IP address :10.2.3.228 <<=======Blue Coat IP
Sequence info :10.2.3.231,636
Query response info:
Active :1
Primary hash weight :0
Hotspot information :0,0,0,0
Total assign weight :0
Router IP address :10.2.3.231 <<=======Router ID/Highest IP on
Router
Receive # :636
Change # :4
Activation time :Wed, Jan 30 2002 00:17:58 UTC
Last I-See-You time :Wed, Jan 30 2002 01:08:58 UTC
281
Volume 5: Advanced Networking
Router Configuration
The configuration below reveals that two interfaces are active on the router, and that one
of the IP addresses is higher than the home router configured in the SG configuration file.
The higher IP address takes over duties as the home router, causing a mismatch between
the router and the SG appliance.
Router# show conf
Using 689 out of 129016 bytes
version 12.1
service timestamps debug uptime
service timestamps log uptime
no service password-encryption
hostname NachoL3
enable secret 5 $1$r6nJ$dr58AZ.ZDg6RKA6MYeGRb.
enable password nacho
ip subnet-zero
no ip routing
ip wccp 9
interface FastEthernet0/0
ip address 10.2.3.224 255.255.255.0
ip wccp 9 redirect out
no ip route-cache
no ip mroute-cache
speed 100
half-duplex
!
interface FastEthernet0/1
ip address 10.2.3.231 255.255.255.0
no ip route-cache
no ip mroute-cache
speed 100
half-duplex
282
Appendix C: Using WCCP
283
Volume 5: Advanced Networking
284
Index
285
Volume 5: Advanced Networking
286
Index
287
Volume 5: Advanced Networking
288
Index
289
Volume 5: Advanced Networking
290
Index
291
Volume 5: Advanced Networking
292
Blue Coat® Systems
SG™ Appliance
Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
ii
Contents
Contact Information
Chapter 1: Introduction
Document Conventions....................................................................................................................................13
iii
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Policy Layers............................................................................................................................................... 32
Rule Objects ................................................................................................................................................ 33
Policy Layer/Object Matrix...................................................................................................................... 35
The Set Object Dialog ....................................................................................................................................... 35
The Add/Edit Object Dialog ........................................................................................................................... 37
Online Help........................................................................................................................................................ 37
Section B: Policy Layer and Rule Object Reference
About the Reference Tables ............................................................................................................................. 38
Administration Authentication Policy Layer Reference ............................................................................. 38
Administration Access Policy Layer Reference............................................................................................ 39
DNS Access Policy Layer Reference............................................................................................................... 39
SOCKS Authentication Policy Layer Reference ........................................................................................... 40
SSL Intercept Layer Reference......................................................................................................................... 40
SSL Access Layer Reference ............................................................................................................................ 41
Web Authentication Policy Layer Reference ................................................................................................ 42
Web Access Policy Layer Reference ............................................................................................................... 43
Web Content Policy Layer Reference............................................................................................................. 46
Forwarding Policy Layer Reference ............................................................................................................... 47
Section C: Detailed Object Column Reference
Source Column Object Reference.................................................................................................................... 49
Any............................................................................................................................................................... 49
Streaming Client......................................................................................................................................... 49
Client Hostname Unavailable .................................................................................................................. 49
Authenticated User.................................................................................................................................... 49
Guest User................................................................................................................................................... 49
Client IP Address/Subnet ........................................................................................................................ 50
Client Hostname ........................................................................................................................................ 50
Proxy IP Address/Port ............................................................................................................................. 50
User .............................................................................................................................................................. 50
Group........................................................................................................................................................... 53
Attribute ...................................................................................................................................................... 56
User Login Address................................................................................................................................... 57
User Login Time......................................................................................................................................... 57
User Login Count....................................................................................................................................... 57
Client Address Login Count .................................................................................................................... 57
User Authentication Error ........................................................................................................................ 57
User Authorization Error.......................................................................................................................... 58
DNS Request Name ................................................................................................................................... 59
RDNS Request IP Address/Subnet......................................................................................................... 59
DNS Request Opcode................................................................................................................................ 59
DNS Request Class .................................................................................................................................... 59
DNS Request Type..................................................................................................................................... 60
DNS Client Transport................................................................................................................................ 60
iv
Contents
SOCKS Version........................................................................................................................................... 60
User Agent .................................................................................................................................................. 60
IM User Agent ............................................................................................................................................ 61
Request Header .......................................................................................................................................... 61
Client Certificate ........................................................................................................................................ 62
IM User ........................................................................................................................................................ 62
P2P Client.................................................................................................................................................... 62
Client Negotiated Cipher.......................................................................................................................... 63
Client Negotiated Cipher Strength.......................................................................................................... 63
Client Negotiated SSL Version ................................................................................................................ 63
Client Connection DSCP Trigger............................................................................................................. 63
Combined Source Object........................................................................................................................... 64
Source Column/Policy Layer Matrix...................................................................................................... 65
Destination Column Object Reference ........................................................................................................... 66
Any............................................................................................................................................................... 66
DNS Response Contains No Data ........................................................................................................... 66
Destination IP Address/Subnet............................................................................................................... 66
Destination Host/Port .............................................................................................................................. 66
Request URL ............................................................................................................................................... 66
Request URL Category.............................................................................................................................. 68
Category ...................................................................................................................................................... 69
Server URL.................................................................................................................................................. 70
Server Certificate........................................................................................................................................ 70
Server Certificate Category ...................................................................................................................... 70
Server Negotiated Cipher ......................................................................................................................... 70
Server Negotiated Cipher Strength ......................................................................................................... 70
Server Negotiated SSL Version................................................................................................................ 70
File Extensions............................................................................................................................................ 71
HTTP MIME Types.................................................................................................................................... 71
Apparent Data Type .................................................................................................................................. 71
Response Code ........................................................................................................................................... 71
Response Header ....................................................................................................................................... 72
Response Data ............................................................................................................................................ 72
IM Buddy .................................................................................................................................................... 73
IM Chat Room ............................................................................................................................................ 73
DNS Response IP Address/Subnet......................................................................................................... 73
RDNS Response Host................................................................................................................................ 74
DNS Response CNAME............................................................................................................................ 74
DNS Response Code.................................................................................................................................. 74
Server Connection DSCP Trigger ............................................................................................................ 74
Combined Destination Objects ................................................................................................................ 75
Destination Column/Policy Layer Matrix ............................................................................................. 75
v
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
vi
Contents
vii
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
viii
Contents
ix
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
x
Contents
Appendix A: Glossary
xi
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
xii
Chapter 1: Introduction
Creating policy is the core task of implementing Blue Coat SG appliances into the
enterprise. After the basic SG appliance configurations are complete, defined policy is
what controls user activities and implements company authentication and network
resource allocation goals.
The Visual Policy Manager is a user interface that creates underlying Blue Coat Content
Policy Language (CPL). In the VPM, you create policy layers by selecting and
customizing policy objects. This volume discusses the facets of the VPM, including layer
interactions and summary object descriptions. When approrpriate, cross references are
provided to other Blue Coat volumes that describe the conceptual information of the
feature. This volume also contains a chapter that discusses some common tasks that are
only achieved through policy, not the Management Console.
This document contains the following chapters:
❐ Chapter 2: "Managing Policy Files" on page 15
❐ Chapter 3: "The Visual Policy Manager" on page 27
❐ Chapter 4: "Advanced Policy Tasks" on page 169
Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Conventions Definition
Courier font Command line text that appears on your administrator workstation.
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.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
13
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
14
Chapter 2: Managing Policy Files
Policy files contain the policies (triggers and actions) that manage every aspect of the
SG appliance, from controlling user authentication and privileges to disabling access
logging or determining the version of SOCKS.
The policy for a given system can contain several files with many layers and rules in
each. Policies can be defined through the Visual Policy Manager (VPM) or composed in
Content Policy Language (CPL). (Some advanced policy features are not available in
VPM and can only be configured through CPL.)
Policies are managed through four files:
❐ Central policy file—Contains global settings to improve performance and behavior
and filters for important and emerging viruses (such as Code Red and Nimda).
This file is usually managed by Blue Coat, although you can point the SG appliance
to a custom Central policy file instead.
❐ Forward policy file—Usually used to supplement any policy created in the other
three policy files. The Forward policy file contains Forwarding rules when the
system is upgraded from a previous version of SGOS (2.x) or CacheOS (4.x).
❐ Local policy file—A file you create yourself. When the VPM is not the primary tool
used to define policy, the Local file contains the majority of the policy rules for a
system. If the VPM is the primary tool, this file is either empty or includes rules for
advanced policy features that are not available in VPM.
❐ Visual Policy Manager—The policy created by the VPM can either supplement or
override the policies created in the other policy files.
This chapter contains the following sections:
❐ “Creating and Editing Policy Files” on page 15
❐ “Managing the Central Policy File” on page 22
❐ “Viewing Policy Files” on page 23
To learn about writing policies, refer to Volume 10: Blue Coat SG Appliance Content Policy
Language Guide.
15
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
2. From the Install Local/Forward/Central File from drop-down list, select the method
used to install the local, forward, or central policy configuration; click Install and
complete one of the three procedures below:
Note: A message is written to the event log when you install a list through the SG
appliance.
16
Chapter 2: Managing Policy Files
In the Install Local/Forward/Central File dialog that appears, enter the fully-
qualified URL, including the filename, where the policy configuration is located.
To view the file before installing it, click View. Click Install. The Installation Status
field summarizes the results; click Results to open the policy installation results
window. Close the window when you are finished viewing the results; click OK in
the Install Local/Forward/Central File dialog.
Note: If you use the default Blue Coat Central policy file, load it from:
https://download.bluecoat.com/release/SG5/files/CentralPolicy.txt.
If you install a Central policy file, the default is already entered; change this field only
if you want to create a custom Central policy file.
To load a Forward, Local, or a custom Central policy file, move it to an HTTP or FTP
server, and then use that URL to download the file to the SG appliance.
In the Upload and Install File window that opens, either enter the path to the file
into the File to upload field, or click Browse to display the Choose file dialog,
locate the file on the local system, and open it. Click Install. When the installation
is complete, the installation results display. View the results and close the
window.
17
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
The current configuration is displayed in installable list format. Define the policy
rules using CPL in the Edit and Install File window that opens (refer to Volume 10:
Blue Coat SG Appliance Content Policy Language Guide); click Install. When the
installation is complete, a results window opens. View the results, close the results
window and click OK in the Edit and Install File window.
3. Click Apply.
Note: There are other management-related tasks regarding the Blue Coat Central Policy
File. See “Managing the Central Policy File” on page 22.
Note: If you are not sure whether a policy file is already defined, check before using the
inline policy command. For more information, see “Viewing Policy Source Files” on
page 24.
18
Chapter 2: Managing Policy Files
Note: Do not use the inline policy command with files created using the
VPM module.
To unload policies:
1. Select Configuration > Policy > Policy Files > Policy Files.
2. Select Text Editor in the Install Local/Forward/Central File from drop-down list and click
the appropriate Install button. The Edit and Install the Local/Forward/Central Policy
File appears.
3. Delete the text and click Install.
4. View the results in the results page that opens; close the page.
5. Click Close.
19
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
2. To change the order, select the file to move and click Move Up or Move Down.
Remember that the last file in the list overwrites decisions in files evaluated earlier.
20
Chapter 2: Managing Policy Files
A default proxy transaction policy of Allow permits most proxy transactions however, if
protocol detection is enabled (the default), HTTP CONNECT transactions are only
allowed if they are tunneling SSL. If protocol detection is disabled, HTTP CONNECT is
only allowed on port 443. If your policy is set to Allow, you must create policies to
explicitly deny access on a case-by-case basis.
Note: The default proxy policy does not apply to admin transactions. By default, admin
transactions are denied unless you log in using console account credentials or if explicit
policy is written to grant read-only or read-write privileges.
Defaults:
❐ Proxy Edition: The default depends on how you installed SGOS and if it was a new
installation or an upgrade:
• If you installed the SGOS through a browser using the Initial Configuration Web
site, you chose whether to allow or deny proxied transactions during initial
configuration.
• If you installed the SGOS using the front panel or a serial console port, the default
setting is Deny.
• If you upgraded the SGOS from a previous version, the default remains whatever
it was for the previous policy.
❐ MACH5 Edition: The default setting is Allow.
You can always change the setting—see the procedures below for instructions.
Also keep in mind that:
❐ Changing the default proxy transaction policy affects the basic environment in which
the overall policy is evaluated. It is likely that you must revise policies to retain
expected behavior after such a change.
❐ Changes to the evaluation order might result in different effective policy, because the
order of policy evaluation defines general rules and exceptions.
❐ Changing the default proxy transaction policy does not affect the evaluation of cache
and admin transactions.
Policy Tracing
Tracing enabled with the Management Console or CLI is global; that is, it records every
policy-related event in every layer. It should be used only while troubleshooting. For
information on troubleshooting policy, refer to Volume 10: Blue Coat SG Appliance Content
Policy Language Guide. Turning on policy tracing of any kind is expensive in terms of
system resource usage and slows down the SG appliance's ability to handle traffic.
21
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
22
Chapter 2: Managing Policy Files
Note: This command does not change the default proxy policy settings.
23
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: You can view VPM policy files through the Visual Policy Files tab.
The SG appliance opens a separate browser window and displays the policy.
2. Review the policy, then close the browser.
24
Chapter 2: Managing Policy Files
25
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
The SG appliance opens a separate browser window and displays the statistics.
2. Examine the statistics, then close the browser.
26
Chapter 3: The Visual Policy Manager
The Visual Policy Manager (VPM) is a graphical policy editor included with the SG
appliance. The VPM allows you to define Web access and resource control policies
without having an in-depth knowledge of Blue Coat Content Policy Language (CPL)
and without the need to manually edit policy files.
This chapter serves as a VPM object reference, and assumes that you are familiar with
basic concepts of SG appliance policy functionality as described in Chapter 2,
Managing Policy Files.
While VPM creates only a subset of everything you can achieve by writing policies
directly in CPL, it is sufficient for most purposes. If your needs require more advanced
policies, consult Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
This chapter contains the following sections:
❐ Section A: "About the Visual Policy Manager" on page 28
❐ Section B: "Policy Layer and Rule Object Reference" on page 38
❐ Section C: "Detailed Object Column Reference" on page 49
❐ Section D: "Managing Policy Layers, Rules, and Files" on page 139
❐ Section E: "Tutorials" on page 149
Related topics:
❐ Chapter 2: "Managing Policy Files"
❐ Volume 7: Managing Content
❐ Volume 10: Blue Coat SG Appliance Content Policy Language Guide
27
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
28
Chapter 3: The Visual Policy Manager
Menu bar
Toolbar
Layer tabs
Object types
Rules
Menu Bar
The following table describes VPM Menu Bar items.
Revert to existing Policy on ... Ignores changes and reloads installed policy
rules.
Edit Add Rule Adds a new blank rule to the visible policy layer
Delete Rule or removes a rule from the visible policy layer.
Policy Add Admin Authentication Layer The Policy menu items add policy layers to be
Add Admin Access Layer populated with policy rules.
Add DNS Access Layer
Add SOCKS Authentication Layer
Add SSL Intercept Layer
Add SSL Access Layer
Add Web Authentication Layer
Add Web Access Layer
Add Web Content Layer
Add Forwarding Layer
29
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Configuration Set DNS Lookup Restrictions Restricts DNS lookups during policy evaluation.
Set Reverse DNS Lookup Restrictions Restricts reverse DNS lookups during policy
evaluation.
Set Group Log Order Configures the order in which the group
information is logged.
Current SG Appliance VPM Policy Displays the currently stored VPM policy files.
Files
Tool Bar
The VPM Tool Bar contains the following functions:
❐ Add Rule—Adds a blank rule to visible policy layer; all values for the rule are the
defaults.
❐ Delete Rule—Deletes the selected rule from the visible policy layer.
❐ Move Up—Moves a rule up one position in the visible policy layer.
❐ Move Down—Moves a rule down one position in the visible policy layer.
❐ Install Policy—Converts the policies created in VPM into Blue Coat Content Policy
Language (CPL) and installs them on the SG appliance.
30
Chapter 3: The Visual Policy Manager
31
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
For example, the SG appliance has two ICAP response services installed, A and B. In the
Management Console, you remove service B, but do not click Apply. You then start the
VPM and view the ICAP Response Services object. Only service A is viewable and
selectable.
The VPM synchronizes the latest change from the Management Console when the
following occur:
❐ Clicking Revert.
❐ Clicking Apply.
❐ Clicking Policy Install.
❐ Restart the Management Console.
❐ Log out and re-log into the Management Console.
Any information the Management Console acquires from installable lists is immediately
available in the VPM. The following are the lists the VPM obtains from the Management
Console:
❐ Access Log fields.
❐ Authentication character sets.
❐ Authentication realms.
❐ Bandwidth gain classes.
❐ Categories.
❐ Exceptions.
❐ Forwarding hosts.
❐ ICAP request and response services.
❐ Keyrings.
❐ SOCKS gateways.
❐ Websense filter services.
Policy Layers
The layers are:
❐ Administration Authentication—Determines how administrators accessing SG
appliance must authenticate.
❐ Administration Access—Determines who can access the SG appliance to perform
administration tasks.
❐ DNS Access—Determines how the SG appliance processes DNS requests.
32
Chapter 3: The Visual Policy Manager
❐ Web Authentication—Determines whether user clients that access the proxy or the
Web must authenticate.
❐ Web Access—Determines what clients can and cannot access on the Web and specifies
any restrictions that apply.
❐ Web Content—Determines caching behavior, such as verification and ICAP
redirection.
❐ Forwarding—Determines forwarding hosts and methods.
As you create policy layers, you will create many different layers of the same type. Often,
an overall policy requires layers of different types designed to work together to perform a
task. For example, Authentication and Access layers usually accompany each other; an
Authentication layer determines if a user or client must authenticate, and an Access layer
subsequently determines where that user or client can go (what SG appliance or Web sites
they can access) once they are authenticated.
Each object type is described in “Policy Layer and Rule Object Reference” on page 38.
Rule Objects
Policy layers contain rule objects. Only the objects available for that policy layer type are
displayed. There are two types of objects:
❐ Static Objects—A self-contained object that cannot be edited or removed. For
example, if you write a rule that prohibits users from accessing a specific Web site, the
Action object you select is Deny.
Static objects are part of the system and are always displayed.
❐ Configurable Objects—A configurable object requires parameters. For example,
consider the rule mentioned in the previous item that prohibits users from accessing a
specific Web site. In this case, the user is a Source object. That object can be a specific
IP Address, user, group, user agent (such as a specific browser), and so on. Select one
and then enter the required information (such as a verifiable user name or group
name).
Configurable objects do not exist until you create them. A created object is listed along
with all static objects in the list dialog, and you can reuse it in other applicable policy
layers. For example, an IP address can be a Source or Destination object in many
different policy-layer types.
Important: The orders of policy layers, and the order of rules within a layer are
important. For more information, see “How Policy Layers, Rules, and Files Interact”
on page 139.
While individual object-type menus occasionally contain entries specific to the object
type, the basic menu options are:
❐ Allow—(Web Access Layer Action column only) Quick menu access; sets the policy to
allow.
❐ Deny—(Web Access Layer Action column only) Quick menu access; sets the policy to
deny.
❐ Set—Displays the Set Object dialog where you select an object or create a new one.
33
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
❐ Edit—Opens the Edit Object dialog where you edit an object or change to another.
❐ Delete—Removes the selected object from the current rule and restores the default.
❐ Negate—Defined as not. Negate provides flexibility in writing rules and designing the
structure of policies. The following is a simple Web Access rule that states: “When any
client tries to access a URL contained in an object of JobSearch, allow access.”
Object Description
Destination Specifies the destination attribute, such as a URL, IP address, and file
extension.
Service Specifies the service attribute, such as protocols, protocol methods, and IM
file transfer limitations.
Track Specifies tracking attributes, such as event log and E-mail triggers.
34
Chapter 3: The Visual Policy Manager
Admin x x x x
Authentication
Admin Access x x x x
DNS Access x x x x x x
SOCKS x x x x
Authentication
SSL Intercept x x x x x
SSL Access x x x x x x
Web Authentication x x x x x
Web Access x x x x x x x
Web Content x x x x x
Forwarding x x x x x x
35
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
36
Chapter 3: The Visual Policy Manager
Online Help
The VPM contains its own Help module (a porting of this chapter). Each object in the
VPM contains a Help button that links to the corresponding object reference in the Help
file. This reference describes the purpose of the object. Interaction with other policy and
references to feature-related sections in the Blue Coat Configuration and Management Guide
Suite volumes are provided, if relevant. Also, this Help module contains navigation
buttons and its own Table of Contents.
Note: The online Help file is displayed in a separate window and requires a few seconds
to load and scroll to the correct object. The speed of your system might impact this slight
lag time. Furthermore, this lag time increases on slower machines running JRE v1.5.
37
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: If viewing this document as a PDF, you can click an object name to jump to a
description of that object (all objects are described in Section C). To jump back to a specific
policy layer reference, click policy layer name in any object reference table that appears in
the next section.
38
Chapter 3: The Visual Policy Manager
Source Objects Destination Objects Time Objects Action Objects Track Objects
39
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Source Objects Destination Objects Time Objects Action Objects Track Objects
Combined Manage
Objects Bandwidth
Set Client
Connection DSCP
Value
Set Server
Connection DSCP
Value
Combined Objects
SOCKS Version
Combined Objects
40
Chapter 3: The Visual Policy Manager
Server Certificate
Server Certificate
Category
Combined Objects
Guest User Request URL SSL Proxy Mode Require/Do Not SNMP
Require Client
Certificate
41
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Client Negotiated
Cipher
Client Negotiated
Cipher Strength
Client Negotiated
SSL Version
Combined Objects
Permit Authentication
Error
Permit Authorization
Error
Combined Objects
42
Chapter 3: The Visual Policy Manager
Source Objects Destination Objects Service Objects Time Objects Action Objects Track
Objects
Client Hostname HTTP MIME Types IM File Transfer Check/Do Not Trace
Check
Authorization
43
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Source Objects Destination Objects Service Objects Time Objects Action Objects Track
Objects
IM User Return
Redirect
Combined Reflect IP
Objects
44
Chapter 3: The Visual Policy Manager
Source Objects Destination Objects Service Objects Time Objects Action Objects Track
Objects
Set Server
HTTP
Compression
Manage
Bandwidth
Modify IM
Message
Return ICAP
Feedback
Set External
Filter Service
Set ICAP
Request Service
Set FTP
Connection
Set SOCKS
Acceleration
Disable SSL
Detection
Set Streaming
Max Bitrate
Set Client
Connection
DSCP Value
Set Server
Connection
DSCP Value
Set ADN
Connection
DSCP
45
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Source Objects Destination Objects Service Objects Time Objects Action Objects Track
Objects
Set
Authorization
Refresh Time
Set Credential
Refresh Time
Set Surrogate
Refresh Time
Combined
Objects
Manage Bandwidth
46
Chapter 3: The Visual Policy Manager
Set TTL
Combined Objects
Group Reflect IP
47
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
SOCKS Version
P2P Client
Client Connection
DSCP Trigger
Combined Objects
48
Chapter 3: The Visual Policy Manager
Any
Applies to any source.
Streaming Client
This is a static object. This rule applies to any request from a streaming client.
Authenticated User
This is a static object. This rule applies to any authenticated user.
Guest User
This is a static object. This rule applies to all guest users.
49
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Client IP Address/Subnet
Specifies the IP address and, optionally, a subnet mask of a client. The policy defined in
this rule applies only to this address or addresses on this subnet. This object is
automatically named using the prefix Client; for example, Client: 1.2.0.0/255.255.0.0.
Note: See “Combined Source Object” on page 64 for related information regarding this
source object.
Client Hostname
Specifies a reverse DNS hostname resolved in the reverse lookup of a client IP address.
Enter the host name and select matching criteria. This object is automatically named using
the prefix Client; for example, Client: host.com. If you select a matching qualifier, that
attribute is appended to the object in parentheses. For example, Client: host.com (RegEx).
Proxy IP Address/Port
Specifies the IP address and, optionally, a port on the SG appliance. The policy defined in
this rule applies only to this address or addresses with this subnet.
User
Specifies an individual user in the form of a verifiable username or login name. Enter a
user name and an authentication realm. The dialog then displays different information
depending on the type of authentication realm specified. Select the appropriate realm
from the drop-down list. Items in the list are taken from the realms configured by the
administrator in the SG appliance.
LDAP
You can optionally select a User Base DN from a drop-down list. Entries in the User Base
DN list come from those specified by the administrator in the SG appliance. You can also
edit an entry selected in the list, type a new one, or click Browse to manually select a
name. Edited names and new names are retained in the list. Notice in the Full Name field
that the VPM takes the User Attribute type specified by the administrator in the SG
appliance (cn= in the following illustration), and associates it with the user name and Base
DN entered here.
Important: When you configure a realm, the SG appliance assumes a default primary
user attribute (sAMAccountName for Active Directory; uid for Netscape/iPlanet
Directory Server/SunOne; cn for Novell NDS). You can accept the default or change
it. Whatever is entered there is what the VPM uses here, entering it in the Full Name
display field once a Base DN is selected.
If the primary user attribute specified in the SG appliance differs from the primary user
attribute specified in the directory server, enter the latter in the User field with the
appropriate value (in the format attribute=value). This replaces the entry in the Full Name
field. Examine the following screenshot. Assume that the organization uses phone as the
primary attribute in its LDAP directory:
50
Chapter 3: The Visual Policy Manager
IWA
Entries in this list are not prepopulated. You must enter a name in the Domain Name field.
An entered name is retained and can subsequently be selected and edited. Notice in the
Full Name field that VPM displays domain name and user name entered above.
51
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
RADIUS
Entries in this list are not prepopulated. You must enter a name in the User field. An
entered name is retained and can subsequently be selected and edited. Notice in the Full
Name field that VPM displays domain name and user name entered above.
Windows SSO
Entries in this list are not prepopulated. You must enter a name in the User field. Entries in
the Domain Name list come from those specified by the administrator in the SG appliance.
You can also edit an entry selected in the list, type a new one, or click Browse to manually
select a name.
Local
Entries in this list are not prepopulated. You must enter a name in the User field. An
entered name is retained and can subsequently be selected and edited. Notice in the Full
Name field that VPM displays domain name and user name entered above.
Certificate
If a Certificate realm is selected and that realm uses an LDAP realm as authentication
realm, the Browse button is clickable. This option allows you to browse the LDAP
database and select users, thus preventing typing errors possible from manually entering
names in the fields. If the Certificate realm does not use an LDAP authentication realm,
Browse is not displayed.
52
Chapter 3: The Visual Policy Manager
Netegrity SiteMinder
Entries in this list are not prepopulated. You must enter a name in the User field. An
entered name is retained and can subsequently be selected and edited. Notice in the Full
Name field that VPM displays domain name and user name entered above.
Oracle COREid
Entries in this list are not prepopulated. You must enter a name in the User field. An
entered name is retained and can subsequently be selected and edited. Notice in the Full
Name field that VPM displays domain name and user name entered above.
Policy Substitution
Entries in this list are not prepopulated. You must enter a name in the User field. An
entered name is retained and can subsequently be selected and edited. Notice in the Full
Name field that VPM displays domain name and user name entered above.
Sequences
Entries in this list are not prepopulated. You must enter a name in the User field. An
entered name is retained and can subsequently be selected and edited. Notice in the Full
Name field that VPM displays domain name and user name entered above. From the
Member Realm drop-down list, select an authentication realm (already configured on the
SG appliance). Depending on the realm type, new fields appear.
Group
Specifies a verifiable group name. Enter a user group and an authentication realm. The
dialog then displays different information depending on the type of authentication realm
specified.
❐ Group field—Replace the default with a verifiable group name.
❐ Authentication Realm field—Select the appropriate realm from the drop-down list.
Items in the list are taken from the realms configured by the administrator in the SG
appliance.
• LDAP—Entries in the Group Base DN list come from those specified by the
administrator in the SG appliance. You can also edit an entry selected in the list, or
type a new one. Edited names and new names are retained in the list. Notice in the
Full Name field that the VPM takes the User Attribute type specified by the
administrator in the SG appliance (cn= in the following illustration), and conjoins
it with the group name and Base DN entered here.
Important: When you create a group, the default attribute is cn= in the Full Name
display field.
53
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
54
Chapter 3: The Visual Policy Manager
55
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
• Sequences—Entries in this list are not prepopulated. You must enter a name
in the Group field. An entered name is retained and can subsequently be
selected and edited. Notice in the Full Name field that VPM displays domain
name and user name entered above. From the Member Realm drop-down list,
select an authentication realm (already configured on the SG appliance).
Depending on the realm type, new fields appear.
Attribute
Specifies an LDAP or Radius realm-specific attributes.
LDAP
Specifies a specific LDAP attribute (and optional value).
1
2
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. From the Authentication Realm drop-down list, select All LDAP or a specific realm.
3. In the Attribute Name field, enter a valid attribute.
4. In the Attribute Value field, enter value for the specified LDAP attribute, or leave blank
to accept any value.
The above example sets a Common Name (CN) attribute with the value of Kent to the
LDAP1 realm.
RADIUS
Specifies a RADIUS attribute.
56
Chapter 3: The Visual Policy Manager
1
2
3
4
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. Select All RADIUS or a specific realm.
3. Select an Attribute Name.
4. Enter an Attribute Value for the Attribute Name.
57
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: If authentication fails and no default groups are added through policy (see Guest
Authentication and Default Groups), the group conditions always evaluate to false. Verify
group conditions if you permit authentication errors, especially in scenarios where users
are denied based on group membership.
58
Chapter 3: The Visual Policy Manager
Note: If authorization fails and no default groups are added through policy (see Guest
Authentication and Default Groups), the group conditions always evaluate to false. Verify
group conditions if you permit authorization errors, especially in scenarios where users
are denied based on group membership.
59
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
SOCKS Version
Specifies the SOCKS version, 4 or 5. This object is automatically named as SOCKSVersion4
or SOCKSVersion5.
User Agent
Specifies one or more agents a client might use to request content. The choices include
specific versions of: Microsoft Internet Explorer, Netscape Communicator, Microsoft
Windows Media Player and NetShow, Real Media RealPlayer and RealDownload, Apple
QuickTime, Opera, and Wget.
The policy defined in this rule applies to these selected agents. You can name this list and
create other custom lists to use with other policy layer rules.
60
Chapter 3: The Visual Policy Manager
Example:
Selecting streaming
media user agents.
Note: If you require a user agent not contained in this list, use the Request Header object,
which can contain user agent specified as a header.
IM User Agent
Checks the specified string for a match in the user agent provided by the IM client. For
example, specify the string Lotus to distinguish between the Lotus AOL client and the
standard AOL client.
Request Header
Specifies the rule applies to requests containing a specific header. Blue Coat supplies a list
of standard headers, but you can also select a custom header.
61
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
1
2
3
4
1. In the Name field, enter a custom name or leave as is to accept the default.
2. From the Show drop-list select the viewing field from All to Standard or Custom, as
desired. Standard displays only the default standard headers. Custom displays any
admin-defined headers that exist.
3. From the Header Name drop-list, select a standard or custom header or enter a new
custom header name.
4. In the Header Regex field, enter the header values to which this rule applies.
Client Certificate
Allows for testing common name and subject fields in client certificates.
IM User
Specifies an IM user by their handle. IM traffic sent to or from this user is subject to this
rule. You can enter a complete user ID, a string that is part of a user ID, or a string with a
regular expression. Select the match type from the drop-down list to the right (Exact,
Contains, or RegEx).
Example:
Designating
Bob Kent in
Purchasing
as IM user
number 1.
P2P Client
Specifies peer-to-peer (P2P) clients.
62
Chapter 3: The Visual Policy Manager
3. Click OK.
3. Click OK.
63
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: Blue Coat strongly recommends that combined objects with large lists of Client IP
Address/Subnet values (see “Client IP Address/Subnet” on page 50) do not contain other
source objects. If other source objects are present, the policy evaluation might experience a
significant performance degradation.
64
Chapter 3: The Visual Policy Manager
Object Admin Admin DNS SOCKS SSL SSL Web Web Web Fwding
Auth Acc Acc Auth Int Acc Auth Acc Cont
Streaming Client x
Authenticated User x x x
Guest User x x
Client IP Address/Subnet x x x x x x x x x
Client Hostname x x x x x x x
Proxy IP Address/Port x x x x x x x x x
User x x x x
Group x x x x
Attribute x x x x
SOCKS Version x x x
User Agent x x
IM User Agent x
Request Header x x
Client Certificate x
IM User x
65
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Object Admin Admin DNS SOCKS SSL SSL Web Web Web Fwding
Auth Acc Acc Auth Int Acc Auth Acc Cont
P2P Client x x
Combined Objects x x x x x x x x x
Any
Applies to any destination.
Destination IP Address/Subnet
Specifies the IP address and, optionally, a subnet mask of a destination server. The policy
defined in this rule only applies to this address only or addresses within this subnet. This
object is automatically named using the prefix Destination; for example, Destination:
1.2.0.0/255.255.0.0.
Destination Host/Port
Specifies the hostname or port of a destination server. The policy defined in this rule
applies to this host on this port only. Enter the host name and port number, and select
matching criteria. This object is automatically named using the prefix Destination; for
example, Destination: company.com:80.
Request URL
Applies to a URL request sent by the client to the SG appliance.
66
Chapter 3: The Visual Policy Manager
❐ Simple Match—Matches a partial URL. If a host name is specified, all hosts in that
domain or subdomain match; if a path is specified, all paths with that path prefix
match; if a scheme or port number is specified, only URLs with that scheme or port
match. This object is automatically named using the prefix URL; therefore, the object is
displayed in the rule as URL: host.com.
❐ Advanced Match—Specifies a scheme (protocol), host, port range, and/or path. Unlike
the other options on this dialog, selecting Advanced Match allows you to enter a name
at the top of the dialog to name the object. With host and path, you can select from the
drop-down list to match exactly as entered or parts thereof: Exact Match, Contains, At
Beginning, At End, or RegEx. If you select a matching qualifier, that attribute is
appended to the object in parentheses. For example, URL: host.com (Contains).
67
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
68
Chapter 3: The Visual Policy Manager
3. Drop the Policy list and select the created category; click Edit URLs. The Edit Locally
Defined Category Object dialog appears.
4. Enter URLs appropriate for the content filter category you are creating; click OK.
5. Click OK.
Note: If one or more other administrators have access to the SG appliance through
other workstations and are creating categories either through VPM or with inline
commands, consider that newly-created or edited categories are not synchronized
until the policy is installed. When the policy is installed with VPM, the categories are
refreshed. If confusion occurs, select the File>Revert to Existing Policy on SG
Appliance option to restore the policy to the previous state and reconfigure
categories.
❐ Deselecting a parent category automatically deselects all child categories if all child
categories are already selected.
❐ If one or more of the child categories are already selected or deselected, selecting or
deselecting the parent category does not affect child categories—the status of selected
or deselected remains the same.
Category
Functions the same as “Request URL Category” on page 68, but this object is unique to the
DNS Access Layer.
69
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Server URL
This object is functions the same as the “Request URL” on page 66 object, but applies to a
URL sent from the SG appliance to a server. If the SG appliance is performing URL
rewrites, the URL sent from the client might change, which requires another URL
matching check.
Server Certificate
Allows testing of server certificate attributes to be used by the SG appliance-to-server
HTTPS connections. Select one of the options:
❐ Hostname: This is the hostname you want to match in the server certificate. After you
enter the hostname, select from the dropdown list one of the following: Exact Match,
Contains, At Beginning, At End, Domain, or Regex.
❐ Subject: This is the fully qualified subject name in the server certificate. After you
enter the subject, select from the dropdown list one of the following: Exact Match,
Contains, At Beginning, At End, Domain, or Regex.
70
Chapter 3: The Visual Policy Manager
2. Select one or more of the strength options valid for this rule SSL 2.0, SSL 3.0, or TLS
1.0.
3. Click OK.
File Extensions
Creates a list of file extensions. The rule is triggered for content with an extension
matching any on the list. You can create multiple lists that contain various extensions to
use in different rules. For example, create a list called Images, and select file extension
types such as GIF, JPEG, BMP, XPM, and so on.
Note: If you require a MIME type not contained in this list, use a Request URL object that
uses the At End matching criteria.
Response Code
Specifies the rule applies to content responses containing a specific HTTP code. Select a
code from the drop-down list. You can name the rule object or accept the default name.
71
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Response Header
Specifies the rule applies to content responses containing a specific header. Blue Coat
supplies a list of standard headers, but you can also enter a custom header.
1
2
3
4
1. In the Name field, enter a custom name or leave as is to accept the default.
2. From the Show drop-down list select the viewing field from All to Standard or Custom,
as desired. Standard displays only the default standard headers. Custom displays any
admin-defined headers that exist.
3. From the Header Name drop-down list, select a standard or custom header.
4. In the Header Regex field, enter the header string this rule applies to.
Response Data
Specifies the rule applies to content responses containing specific regular expressions.
1
2
3
1. In the Name field, enter a custom name or leave as is to accept the default.
2. In the RegEx to match field, enter the regular expression string to match.
3. In the Number of bytes to examine field, enter how many object bytes are scanned for
the match.
4. Click OK.
72
Chapter 3: The Visual Policy Manager
IM Buddy
Specifies an IM buddy by their handle. IM traffic sent to or from this buddy is subject to
this rule. You can enter a complete buddy ID, a string that is part of a buddy ID, or a string
with a regular expression. Select the match type from the drop-down list to the right
(Exact, Contains, or RegEx).
IM Chat Room
Specifies an IM chat room by name or other condition. IM traffic sent to this chat room is
subject to this rule.
1
2a
2b
2c
2d
2e
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. Select one or more of the following conditions:
a. Room ID—Specifies a specific IM chat room by its name. Enter a name and
from the drop-down list select an option: Exact Match, Contains, or RegEx.
b. Type—Specifies whether the room is Private or Public.
c. Invite Only—Specifies to trigger if user must be invited or not.
d. Voice Enabled—Specifies whether room supports voice chat or not.
e. Conference—Specifies whether room has conference capability or not.
3. Click OK.
73
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
74
Chapter 3: The Visual Policy Manager
Object Admin Admin DNS SOCKS SSL SSL Web Web Web Fwding
Auth Acc Acc Auth Int Acc Auth Acc Cont
Destination IP Address/Subnet x x x x x x
Destination Port x x x x x x
Request URL x x x x x x
Category x
Server URL x x
Server Certificate x x
File Extensions x x
Response Header x
Response Code x
75
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Object Admin Admin DNS SOCKS SSL SSL Web Web Web Fwding
Auth Acc Acc Auth Int Acc Auth Acc Cont
Response Data x
IM Buddy x
IM Chat Room x
Combined Objects x x x x x
Any
Applies to any service.
Virus Detected
This is a static object. The rule applies if ICAP scanning detects a virus.
Request Forwarded
This is a static object. Automatically created when upgrading from SGOS 4.2.x to SGOS
5.2.x. Refer to the Blue Coat SGOS 5.2 Upgrade/Downgrade Guide.
Client Protocol
Specifies the client protocol types and subsets. From the first drop-down list, select a type
from the drop-down list: CIFS, Endpoint Mapper, FTP, HTTP, HTTPS, Instant Messaging, P2P,
Shell, SOCKS, SSL, Streaming, or TCP Tunneling.
76
Chapter 3: The Visual Policy Manager
The second drop-down list allows you to select a protocol subset (these options vary
depending on the selected protocol):
❐ All—Applies to all communication using this type of protocol.
Service Name
Specify any default or custom proxy service that exists on the SG appliance (created from
the Management Console: Configuration > Services > Proxy Services).
❐ The Web Access Layer only displays and accepts proxy services.
❐ The Admin Access Layer only displays and accepts console services.
Protocol Methods
Specifies the protocol methods that trigger a rule.
3. Select connection methods. These options vary depending on the selected protocol.
The above example demonstrates basic Instant Messaging connections.
77
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
4. Click OK.
IM File Transfer
Specifies the rule is applied to IM file transfers, which can be triggered by matching the
file name, file size, or both.
1
2a 2b
3a 3b
1. In the Name field, enter a name for the object or accept the default.
2. To trigger by file name:
a. Select File; in the File field, specify a file name;
b. From the drop-down list, select if file is matched exactly (Exact Match), if the
file contains the name (Contains), or matched by regular expression (RegEx).
3. To trigger by message size:
a. Select Size and enter a range.
b. From the drop-down list, select the size attribute: Bytes, Kbytes, MBytes, or
GBytes.
IM Message Text
Specifies the rule is applied to IM message text, which can be triggered by any or all of the
following: matching content keywords, message size, service type, and whether the
content type is text or application.
78
Chapter 3: The Visual Policy Manager
2a 2b
3 3b
4
5
1. In the Name field, enter a name for the object or accept the default.
2. To trigger by content keywords:
a. Select Text; in the Text field, specify a keyword.
b. From the drop-down list, select if the file contains the text (Contains), or if it is
to be matched by regular expression (RegEx).
3. To trigger by message size:
a. Select Size; enter a range.
b. From the drop-down list, select the size attribute: Bytes, Kbytes, MBytes, or
GBytes.
4. To specify the message route, select Route. From the drop-down list, select Service,
Direct, or Chat.
5. To specify message type, select Text or Application.
• Text specifies messages entered by a user.
• Application specifies messages sent by the client application, such as typing
notifications.
IM Message Reflection
Allows policy to test whether or not reflection is enabled for the current message and, if
enabled, whether it is possible.
❐ Succeeded—IM reflection is enabled and is performed for this message.
❐ Failed—IM reflection is enabled, but not possible for this message because the
recipient is not connected through this SG appliance.
❐ Disabled—IM reflection is not enabled for this message.
The objects are automatically named based on the selection and can be used in any rule.
79
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
1
2a
2b
2c
1. In the Name field, enter a name for the object or accept the default.
2. Select an option:
a. No errors—An ICAP scan was performed without scanning errors.
b. Any errors—An ICAP error code was returned during a scan.
c. Selected errors—An ICAP error code of a specific type or types. In the
Available Errors field, select one or more ICAP error codes (press and hold the
Control key to select more than one type or the Shift key to select a block of
types). Click Add.
3. Click OK.
80
Chapter 3: The Visual Policy Manager
Health Check
This condition tests whether the current transaction is a health check transaction.
Optionally, the condition tests whether the transaction is that of a specific health check.
1
2a
2b
2c
• Any Health Check: A health check service of any type was matched.
• Any of the selected health checks below: A health check of the selected types was
matched.
2. If you selected Any of the selected health checks below:
a. Select one or more error types (use Control + Left-click to highlight multiple
errors).
b. Click Add to move the errors to the Selected field.
c. Name the object or accept the default name.
3. Click OK.
Health Status
This conditions tests whether the target of the specified health check is health or sick.
81
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Object Admin Admin DNS SOCKS SSL SSL Web Web Web Fwding
Auth Acc Acc Auth Int Acc Auth Acc Cont
Request Forwarded x
Virus Detected x
Client Protocol x x x x
Service Name x x
Protocol Methods x x x
IM File Transfer x
IM Message Text x
IM Message Reflection x
Health Status x x
Health Check x x
Combined Objects x x x x
Any
Applies anytime.
Time
Specifies the time restrictions.
82
Chapter 3: The Visual Policy Manager
1. In the Name field, enter a name for the object or leave to accept the default.
2. Select Use Local Time Zone or Use UTC Time Zone.
Local time sets the rule to follow the SG appliance internal clock. UTC sets the rule to
use the Universal Coordinated Time (also known as Greenwich Mean Time or GMT).
3. To specify a range for any given day, select Enable; in the Specify Time of Day
Restriction (hh:mm) field, configure the times. The time style is military.
The range can be contained within one 24-hour calendar day, or overlap days. For
example, configuring the time to range from 22:00 to 06:00 sets a limit from 10 at night
to 6 the following morning.
4. To specify a day of the week restriction, select Enable; in the Specific Weekday
Restriction field, select one or more days.
5. To specify a day of the month range restriction, select Enable; in the Specify Day of
Month Restriction field, select the days, which are numbered from 01 to 31. To limit the
range to specific day, configure the numbers to be the same. For example, selecting 22
and 22 specifies the rule to apply only the 22nd day of every month.
83
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
6. To specify a restriction that spans one or more months, select Enable; in the Specify
Annually-Recurring Date Restriction field, select the month and day ranges. This
calendar restriction applies every year unless the restriction is altered.
Overlapping months is allowed, similar to the behavior of day ranges in Step 3.
7. To specify a one-time only restriction, select Enable; in the Specify Non-Recurring Date
Restriction field, select the year, month, and day ranges. This calendar restriction
applies only during the time specified and will not repeat.
8. Click OK.
Object Admin Admin DNS SOCKS SSL SSL Web Web Web Fwding
Auth Acc Acc Auth Int Acc Auth Acc Cont
Time x x
Combined Objects x x
Allow
This is a static object. Selecting this overrides other related configurations and the
specified user requests are allowed.
Deny
This is a static object. Selecting this overrides other related configurations and denies the
specified user requests.
Force Deny
This is a static object. Forces a request to be denied, regardless if rules in subsequent layers
would have allowed the request.
84
Chapter 3: The Visual Policy Manager
Do Not Authenticate
This is a static object. Selecting this overrides other configurations and the specified users
are not authenticated when requesting content.
Authenticate
Creates an authentication object to verify users. An authentication realm must exist on the
SG appliance to be selected through VPM.
Note: In the SOCKS Authentication policy layer, the object is SOCKS Authenticate.
85
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
1
2
3
4
5
6
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. From the Realm drop-down list, select an authentication realm, which must already
exist on the SG appliance.
3. Optional (in the Web Authentication policy layer only): from the Mode drop-down list,
select a mode. The mode determines the way the SG appliance interacts with the
client for authentication specifying the challenge type and the accepted surrogate
credential:
• Auto—The default; the mode is automatically selected, based on the request.
Selects among proxy, origin-IP, and origin-IP-redirect, depending on the type of
connection (explicit or transparent) and the transparent authentication cookie
settings.
• Form Cookie—For forms-based authentication: cookies are used as surrogate
credentials. The cookies are set on the OCS domain only, and the user is presented
with the form for each new domain. This mode is most useful in reverse proxy
scenarios where there are a limited number of domains.
• Form Cookie Redirect—The user is redirected to the authentication virtual URL
before the form is presented. The authentication cookie is set on both the virtual
URL and the OCS domain. The user is only challenged when the credential cache
entry expires.
• Form IP—The user’s IP address is used as a surrogate credential. The form is
presented whenever the user’s credential cache entry expires.
• Form IP Redirect—This is similar to Form IP except that the user is redirected to
the authentication virtual URL before the form is presented.
• Proxy—For explicit forward proxies: the SG appliance uses an explicit proxy
challenge. No surrogate credentials are used. This is the typical mode for an
authenticating explicit proxy.
• Proxy IP—The SG appliance uses an explicit proxy challenge and the client's IP
address as a surrogate credential.
86
Chapter 3: The Visual Policy Manager
• Origin—The SG appliance acts like an OCS and issues OCS challenges. The
authenticated connection serves as the surrogate credential.
• Origin IP—The SG appliance acts like an OCS and issues OCS challenges. The
client IP address is used as a surrogate credential.
• Origin Cookie—For transparent proxies: for clients that understand cookies but do
not understand redirects; the SG appliance acts like an origin server and issues
origin server challenges. The surrogate credential is used.
• Origin Cookie Redirect—For transparent forward proxies: the client is redirected
to a virtual URL to be authenticated, and cookies are used as the surrogate
credential. The SG appliance does not support origin-redirects with the
CONNECT method.
• Origin IP Redirect—Significantly reduces security; only useful for reverse proxy
and when clients have unique IP addresses and do not understand cookies (or you
cannot set a cookie). Provides partial control of transparently intercepted HTTPS
requests. The client is redirected to a virtual URL to be authenticated, and the
client IP address is used as a surrogate credential. The SG appliance does not
support origin-redirects with the CONNECT method.
• SG2—The mode is selected automatically, based on the request using the SGOS
2.x-defined rules.
4. (Optional) If you selected a Form mode in Step 3, the Authentication Form, New Pin
Form, and Query Form drop-down lists becomes active.
Note: The New Pin Form and the Query Form are only used with RSA SecurID
authentication.
Authenticate Guest
Allows a user to be authenticated as a guest user. One scenario is to allow access to a user
who might otherwise be considered unauthenticated. Another is where no authentication
is required, but you want to track access. For more information, see the Controlling Access
to the Internet and Intranet chapter in Volume 4: Securing the Blue Coat SG Appliance.
87
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
1
2
Force Authenticate
Forces the user to authenticate even though the request is going to be denied for reasons
that do not depend on authentication. This action is useful to identify a user before the
denial so that the username is logged along with the denial. See Volume 4: Securing the Blue
Coat SG Appliance for a description of the fields in this object.
88
Chapter 3: The Visual Policy Manager
Note: In the SOCKS Authentication policy layer, the object is Force SOCKS Authenticate.
Bypass Cache
This is a static object. Prevents the cache from being queried when serving a proxy
request, and prevents the response from the origin server from being cached.
89
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Always Verify
This is a static object. Cached content is always verified for freshness for the sources,
destinations, or service specified in the rule. For example, the CEO and Executive Staff
always require content to be the most recent, but everyone else can be served from the
cache.
90
Chapter 3: The Visual Policy Manager
91
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Deny
This object provides the same functionality as the “Force Deny” on page 84 object, but
provides the option to re-allow authentication and insert substitution strings.
Return Exception
Allows you to select exception types and associate a custom message, if desired. Blue Coat
provides a list of standard exceptions, but VPM also accepts user-defined values.
2a
2b
4
5
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. Perform one of the following:
a. Standard exception type: select one from the Built-in exception drop-down
list.
b. Custom exception (which already must be defined on the SG appliance) type:
select one from the User-defined exception drop-down list.
3. Optional: Select Force exception even if later policy would allow request to supersede
other policy that applies to this request.
4. Optional: Select Allow re-authentication to allow the user to re-enter credentials should
the first attempt fail.
5. Optional: in the Details field, enter a message that is displayed along with the
summary and exception ID on the exception page displayed to the user when the
exception is returned.
The above example creates an object named DNSException2 that upon a DNS server
failure returns a message to the user instructing them to contact their support person.
To create custom exceptions, see Section D: "Defining Exceptions" on page 176.
92
Chapter 3: The Visual Policy Manager
Return Redirect
Aborts the current transaction and forces a client request to redirect to a specified URL.
For example, used to redirect clients to a changed URL; or redirecting a request to a
generic page stating the Internet access policy. Applies only to HTTP transactions.
.
Note: Internet Explorer (IE) ignores redirect responses from FTP over HTTP requests,
although Netscape Navigator obeys the redirect. To avoid problems with IE, do not use
redirect when url.scheme=ftp.
If the URL that you are redirecting the browser to also triggers a redirect response from
your policy, then you can put the browser into an infinite loop.
In the Name field, enter a name for the object (or leave as is to accept the default); in the
URL field, enter the redirect destination URL.
Example
An object that redirects clients to an HTML policy statement page.
93
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. (Optional) Select one or more to ignore certain failures:
• Ignore a hostname mismatch: Ignores the comparison of hostname in URL and
certificate (intercepted connections only).
• Ignore certificate expiration: Ignores the verification of certificate dates.
• Ignore untrusted issuer: Ignores the verification of issuer signature.
3. The certificate revocation list (CRL) option:
If Also check certificate revocation is selected, this is checked from a Certificate
Authority. For information on using CRL, refer to Volume 4: Securing the Blue Coat SG
Appliance.
Note: Two built-in exceptions can be used to notify the user that the verification of
the server's certificate failed: exception.ssl_server_cert_expired and
exception.ssl_server_unknown_ca. For information on using exceptions, see
Chapter 4: Advanced Policy, Section D: "Defining Exceptions" on page 176.
94
Chapter 3: The Visual Policy Manager
2a
2b
2c
2d
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. To allow SSL content to be examined, select:
a. Issuer Keyring: Accept the default keyring or select this option and from the
drop-down list select a previously generated keyring. This is the keyring used
for signing emulated certificates.
b. Hostname: The hostname you enter here is the hostname in the emulated
certificate.
c. Splash Text: The limit is 200 characters. The splash text is added to the
emulated certificate as a certificate extension. The splash text is added to the
emulated certificate as a certificate extension. For example:
Visit http://example.com/https_policy.html
To add substitution variables to the splash text, click Edit and select from the list.
d. Splash URL: The splash text is added to the emulated certificate as a certificate
extension.
The SSL splash can be caused by such occurrences as when a browser receives a server
certificate signed by an unknown CA, or a host miss-match.
Note: Not all browsers display the splash text and splash URL correctly.
95
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Send IM Alert
Defines a message that is sent to an IM user by the SG appliance. The message is triggered
by the IM parameters defined in the policy (for example, client login, sent or received
messages, and buddy notification). Volume 3: Web Communication Proxies provides more
information about regulating IM through the SG appliance, as well as VPM examples.
Example
A message that informs IM users their messaging is logged.
❐ Reset to default logging—Resets to logging the request to the default log specified by
the SG appliance configuration, if one exists.
❐ Enable logging to—Enables logging of requests matched by this rule to the specified
log.
❐ Disable logging to—Disables logging of requests matched by this rule to the specified
log.
Example:
Enable logging P2P logging for this rule.
96
Chapter 3: The Visual Policy Manager
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. From the Log Name drop-down list, select a log (must already be configured on the SG
appliance).
3. From the Field Name drop-down list, select an access log field.
4. Select one of the following:
• Log original value—Records unmodified value in the access log.
• Suppress value—Prevents value from appearing in the access log.
• Base64 encode value—Records an encoded version of the value in the access log.
97
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
• Rewrite value—In the field, enter a string that replaces the value. Clicking Edit
calls the Select The Rewrite String dialog. The substitution variables instruct the
SG appliance to append specific information to the object. The variables are
categorized alphabetically, according to prefix.
Note: Some variables do not have prefixes, which allows you to substitute the
value with information defined by other field types.
5. Click OK.
The above example creates an object called CEOLogRewrite that suppresses log entries so
persons, such as support personal, cannot view economically sensitive information to
gain improper knowledge.
Rewrite Host
Rewrites host component of a URL, specifying either Windows Media, Real Media, or all
protocols. Use this to redirect the request to a different host. For example, rewrite
www.traning1.com to www.training2.com. You can create and name multiple rewrites,
but you can only specify one per rule.
To specify a rewrite:
2
3
4
Reflect IP
Specifies which IP address is used when making connections to upstream hosts.
98
Chapter 3: The Visual Policy Manager
1. In the Name field, enter name for the object or leave as is to accept the default.
2. In the In outgoing client IP, reflect field, select one of the following:
• Do not reflect IP—Disables reflecting IPs; the SG appliance uses the IP address of
the interface that request is sent out on.
• Incoming client IP [IP spoofing]—Reflects the client IP address.
• Incoming proxy IP—Reflects the IP address of where the request arrived to.
• Proxy IP—Specifies to reflect a specific IP of the SG appliance; enter the IP address
in the field.
• Use services configuration—Specifies whether to reflect IP in the configuration of
the service which is used to process the request.
3. Click OK.
Example
The above example reflects another IP address configured on the SG appliance.
Suppress Header
Specifies one or more standard headers that are suppressed (not transmitted) on the
outbound request, the outbound response, or both.
99
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
1. In the Name field, enter name for the object or leave as is to accept the default.
2. Select Request, Response, or Both. The valid headers vary for requests and responses.
Both displays a small subset of headers valid for requests and responses.
3. Select one or more header types from the list.
4. Click OK.
The above example creates an object called EconomicConfidentialAccess to be used in a
rule suppresses headers so specified users can access economically sensitive information
without people, such as support personal, being able to gain knowledge of sources.
100
Chapter 3: The Visual Policy Manager
2
3
1. In the Name field, enter name for the object or leave as is to accept the default.
2. From the Show drop-list select the viewing field from All to Standard or Custom, as
desired. Standard displays only the default standard headers. Custom displays any
admin-defined headers that exist.
3. From the Header Name list, select a standard (pre-defined) header or a custom header
if one has been defined.
4. Select an action:
• Suppress—The header is not visible.
• Set value—Replace the header with a string or value.
• Append to value—Add a string or value to the existing header.
5. Click OK.
Notify User
This action displays a notification page in the user’s Web browser. A user must read the
notification and click an Accept button before being allowed to access the Web content.
You can customize the following:
❐ The page title, notification message, and the Accept button.
❐ The conditions that cause a notification to be displayed again. By default, the
notification is displayed each time a user begins a new Web browsing session
(reboots, logs out, or closes all Web browser windows). You can configure re-
notification to occur for each new visited host or Web site, or after a time interval.
Note: The Accept button click action is logged if HTTP access logging is enabled. A
URL is logged that contains the string: accepted-NotifyName, where NotifyName is
the name of the Notify User object.
101
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. In the Title field, enter a name that is the title of the page (text only; no HTML is
allowed).
3. In the Body field, compose a block of HTML that displays the message to the user. You
can also customize the Accept link or button text. The HTML body must contain an
Accept button or link. The default is:
102
Chapter 3: The Visual Policy Manager
Note: This option might cause users to experience some noticeable Web
browsing slowness.
• Notify only once for related domains—The notify page reappears each time the
user visits a new Web site; this is used for configuring coaching pages.
Note: This option interferes with some Web advertising banners. In some
cases, the notification page appears inside the banner. In other cases, banner ads
are disabled by javascript errors. To fix these problems, do not serve notification
pages for URLs that belong to the Web Advertising, Advertising, or Web Ads
category. The actual name of this category varies with the content filtering
vendor, and some vendors do not have an equivalent.
• Notify on every host—The notify page reappears each time the user visits a new
Web host. Blue Coat recommends that only highly experienced administrators
employ this option. In addition to breaking banner ads, as described above in the
previous option, this option, on some Internet Web sites, might cause Javascript
errors that impair the functionality of the site.
5. Under Notify users again, select an option that specifies when the notification expires
and re-notification is required:
• At next browser session— The notification page does not reappear until the next
browser session. When a user reboots, logs out, or closes all Web browser
windows, this ends the browser session.
• After (time interval)—Notification reoccurs after the defined elapsed time
(minutes or hours); this is useful for coaching.
• After (specific time)—Notification reoccurs at a specific time of day. You can
specify an interval of days; this is useful for compliance.
Note: The time is referenced from the local workstation. If a compliance page is
configured, verify the workstations and SG appliance clocks are synchronized.
103
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
The above example creates a Notify Object with a custom message, set to display once a
day after 7 AM.
Policy Interactions
This action generates CPL that might interfere with other policy or cause undesired
behavior. Enhancements will occur in future SGOS releases. For this release, consider the
following guidelines:
❐ Do not create VPM policy that modifies the Cookie request header.
❐ Do not create VPM policy that modifies the Set-Cookie and P3P response headers.
❐ Notification pages exist in the browser history. Therefore, if you click Accept and are
taken to the requested page, then click the back button, you get the notification page
again.
❐ If you have a chain of SG appliances, with different notification pages configured on
each appliance in the chain, then each notification page must have a different object
name.
Note: Pages served over an HTTPS tunneled connection are encrypted, so the content
cannot be modified.
104
Chapter 3: The Visual Policy Manager
2
3
1. In the Name field, enter name for the object or leave as is to accept the default.
2. Select the active content to be stripped.
3. The default message in the Replacement Text column is Active Content Removed. To
replace the default message, double click the field, enter a message, and press Enter.
See the examples in the screenshot, Java applets have been removed.
105
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: If you enable HTTP Compression using the VPM but do not specify the HTTP
Compression Level using VPM policy, then by default the level is Low.
106
Chapter 3: The Visual Policy Manager
Manage Bandwidth
Allows you to manage bandwidth for all protocols or specific protocols, on both inbound
and outbound traffic.
107
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
❐ Optimize traffic in both directions: Apply Byte Caching to traffic coming and leaving
the server.
❐ Optimize only inbound traffic: Apply Byte Caching only to traffic coming into the
server.
❐ Optimize only outbound traffic: Apply Byte Caching only to traffic leaving the server.
Modify IM Message
In IM clients, replaces or appends the given text that is displayed to IM messages in clients
that are logged in through the SG appliance. For example, use with Time Object to inform
users that Instant Messages sent outside the corporate network are not allowed during
business hours.
1. In the Name field, enter a name for the object, or accept the default.
2. In the text field, enter a message that appears on an IM client if the rule applies.
3. Select one of the following:
• Set message text—Replaces the text displayed to the IM client. See the example in
the screenshot.
• Append to message text—The specified text is added to the IM message.
Volume 3: Web Communication Proxies provides more information about regulating IM
through the SG appliance, as well as VPM examples.
108
Chapter 3: The Visual Policy Manager
2a
2b
2c
3a
3b
3c
109
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
4. Click OK.
Enter a time value (in seconds) that the SG appliance waits for content to be serviced from
the origin content server before displaying the page that instructs users an ICAP scan is in
progress.
Note: Patience pages display regardless of any pop up blocking policy that is in effect.
Patience page management and limitations are described in Volume 7: Managing Content.
110
Chapter 3: The Visual Policy Manager
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. To instruct all requests defined in the rule to route to a specific external filter service,
select Use External Filter Service; from the drop-down list, select the external filter
service or service group (which must already exist on the SG appliance; Configuration
> External Services).
4. Click OK.
111
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
2
3
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. To instruct all request or response types defined in the rule to route to a specific ICAP
service, select Use ICAP Request Service; from the drop-down list, select the ICAP
request modification service or service group (which must already exist on the SG
appliance; Configuration > External Services > ICAP).
3. In the Error handling field, select one of the following option:
• To deny all requests or responses if a communication error occurs, select Deny the
client request. This is the default and recommended by Blue Coat.
Note: When the ICAP service is restored, these objects are scanned and served from
the cache if they are requested again.
112
Chapter 3: The Visual Policy Manager
SGOS 4.2.x allowed you to select whether SSL was detected over HTTP, SOCKS, and/or
TCP. These are options are not user-selectable in SGSO 5.2.x, but you can use this object to
preserve the previous behavior.
• If in SGOS 4.2.x you configured SSL detection for one or two proxies, select Traffic
Tunneled Over and proceed to step 2.
113
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
For more information about this feature, refer to the Blue Coat SGOS Upgrade/Downgrade
Guide.
2a
2b
2c
2d
1. In the Name field, enter a name for the object or leave as is to accept the default. This
example sets the DSCP value to CS1 (IP Precedence 1).
2. Selection an action:
a. Echo the inbound packet’s DSCP value: Use the same outbound (point of
reference, the SG appliance) packet DSCP value as the inbound value.
b. Preserve the incoming DSCP value: Track the inbound (from the client) DSCP
bits on the primary server connection and use that same value when sending
packets to outbound to the server. This is valuable for protocols that have
multiple client/server connections. For example, FTP control and data
connections. The values remain independent for each connection.
c. DSCP name: Instead of the incoming DSCP, use the DSCP value selected from
the drop-down list.
d. DSCP value: Instead of the incoming DSCP value, use this non-categorized
DSCP value (range is 0 to 63).
3. Click OK.
For conceptual information about configuring the SG appliance to manipulate traffic
based on type of service, refer to Chapter 4: Advanced Policy, “Managing QoS and
Differential Services” on page 194.
114
Chapter 3: The Visual Policy Manager
1a
1b
Note: For more information about DSCP values, see Chapter 4: Advanced
Policy, Section F: "Managing QoS and Differential Services".
115
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Click OK.
116
Chapter 3: The Visual Policy Manager
2
3
4a
4b
1. In the Name field, enter a name for the object or leave as is to accept the default.
2. In the Host field, enter a host name that is returned.
3. To respond with the IP address of the proxy that is forwarding the request, select
Respond with proxy IP.
4. To respond with one or more IP addresses:
a. Select Respond with listed IPs.
b. Click Add. The Add DNS Response IP dialog appears.
c. Enter an IP address and click Add.
d. Repeat as required; click Close.
5. (Optional) In the TTL field, enter a time-to-live value (how long the response is
cached).
6. Click OK.
Do Not Cache
This is a static object. Specifies that objects are never cached.
117
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Force Cache
This is a static object. Specifies that (cacheable) objects are always cached. Objects that are
not cacheable (for example, RealMedia file types) and supported in pass-through mode
only are not cached.
Enable/Disable Pipelining
These are static objects. Enables or disables the SG appliance pipelining feature, which,
when enabled, examines Web pages for embedded objects and requests them from the
origin server in anticipation of a client request.
Set TTL
Specifies the time-to-live (TTL) an object is stored in the SG appliance. In the Name field,
enter a name for the object (or leave as is to accept the default); in the TTL field, enter the
amount of time in seconds.
Send Direct
This is a static object. Overrides forwarding host, SOCKS gateway, or ICP configurations
and instructs the SG appliance to request the content directly from the origin server.
118
Chapter 3: The Visual Policy Manager
Select Forwarding
Specifies which forwarding host or group, if any, to use; defines behavior if
communication between the forwarding and the SG appliance is down.
❐ To instruct the rule to connect directly without redirecting to a forwarding host or
group, select Do not forward.
❐ To instruct the rule to redirect to a forwarding host, select Use Forwarding and select
an installed forwarding host from the drop-down list.
In the If no forwarding is available field, select Deny the request (fail closed) or Connect
directly (fail open), which allows requests to bypass the forwarding host.
❐ To instruct the rule to forward using the ICP configuration, select Forward using ICP.
Set IM Transport
Specifies the transport method used for IM traffic.
❐ Auto—Connects using the transport method used by the client.
119
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Authentication Charset
The VPM allows you enter non-ASCII in many objects, such user and group names and
text for the “Notify User” on page 101 object. This object allows you set the character set to
use in conjunction with localized policy. From the drop-down list, select a character set
and click OK.
3a
120
Chapter 3: The Visual Policy Manager
a. Select one or more strings and click Insert. For example, your branch user
headers contain the request.header.ClientIP HTTP header.
b. Click OK.
4. From the IP Address drop-down list, select a substitution string. For example: the
$(request.header.Client-IP): sets the address for authentication to the address received
from the HTTP Client-IP header.
5. Click OK.
121
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
• Selected errors: Only allowed if the error matches the selected errors.
2. If you selected Selected errors:
a. Select one or more error types (use Control + Left-click to highlight multiple
errors).
b. Click Add to move the errors to the Selected field.
c. Name the object or accept the default name.
3. Click OK.
122
Chapter 3: The Visual Policy Manager
Object Admin Admin DNS SOCKS SSL SSL Web Web Web Fwding
Auth Acc Acc Auth Int Acc Auth Acc Cont
Allow x x
Deny (static) x x x x
Do Not Authenticate x x x
Authenticate x x x
Force Authenticate x x x
Bypass Cache x
Check Authorization x x
Always Verify x x
Block Up Ads x
Reflect IM Messages x
Block IM Encryption x
123
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Object Admin Admin DNS SOCKS SSL SSL Web Web Web Fwding
Auth Acc Acc Auth Int Acc Auth Acc Cont
Trust Destination IP x
Deny x x
Return Exception x x
Return Redirect x
Send IM Alert x
Rewrite Host x
Reflect IP x x
Suppress Header x
Notify User x
Modify IM Message x
124
Chapter 3: The Visual Policy Manager
Object Admin Admin DNS SOCKS SSL SSL Web Web Web Fwding
Auth Acc Acc Auth Int Acc Auth Acc Cont
Do Not Cache x
Force Cache x
Mark As Advertisement x
Enable Pipelining x
Disable Pipelining x
Set TTL x
Send Direct x
Select Forwarding x
Reflect IP x
Set IM Transport x
Authentication Charset x
Combined Objects x x x x x x
125
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
4
5a
5b
5c
3. In the Name field, enter a name for this object or leave as is to accept the default.
4. In the Message Text field, enter a customized message that appears with each entry.
126
Chapter 3: The Visual Policy Manager
Tracing Objects
This object specifies rule and Web traffic tracing.
Click Trace Level and select one of the following trace options:
❐ No Tracing—The default.
❐ Request Tracing—Generates trace output for the current request. The trace output
contains request parameters (such as URL and client address), the final values of
property settings, and descriptions of all actions taken.
❐ Rule and Request—Generates trace output that displays each rule that was executed
❐ Verbose Tracing—Generates the same output as Rule and Request, but also lists which
rules were skipped because one or more of their conditions were false, and displays
the specific condition in the rule that was false.
Furthermore, a trace destination can be entered that specifies the destination for any trace
produced by the current transaction. To specify a destination path, select Trace File and
enter a path in the field. For example, abc.html.
If a trace destination is configured in multiple layers, the actual trace destination value
displayed is the one specified in the last layer that had a rule evaluated (which has a
destination property configured). Consider the following multiple Web Access Layer
example, demonstrated by the generated CPL:
<Proxy>
url.domain=aol.com trace.request(yes) trace.rules(all)
trace.destination("aol_tracing.html")
url.domain=msn.com trace.request(yes)
trace.rules(all)trace.destination("msn_tracing.html")
<Proxy>
client.address=10.10.10.1 trace.request(yes) trace.rules(all)
The resulting actions are:
❐ Requests to the aol.com domain are logged to aol_tracing.html.
❐ Requests to the msn.com domain are logged to msn_tracing.html.
❐ Requests from the client with the IP of 10.10.10.1 are logged to the default location
of default.html.
127
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: After using a trace to troubleshoot, remove the trace to save log space.
The Trace File option can be used in conjunction or separately from the Trace Level option.
The default path of the trace file is accessible through one of the following URLs.
If the Management Console secure mode is enabled (the default on a new or upgraded
system):
https://SG_appliance_IP_address:8082/Policy/Trace/default_trace.html
If the Management Console is deployed in non-secure mode:
http://SG_appliance_address:8081/Policy/Trace/default_trace.html
Object Admin Admin DNS SOCKS SSL SSL Web Web Web
Auth Acc Acc Auth Int Acc Auth Acc Cont Fwding
Event Log x x x x x x
Email Log x x x x x x
SNMP Objects x x x x x x
Trace x x x x x x x x x x
Combined Objects x x x x x x
Example One
Consider the following example. You want a Web Content policy layer that as an action
forces authorization and sends the response to an ICAP service for content scanning.
128
Chapter 3: The Visual Policy Manager
1. In the Set Action Object dialog, select New > Combined Action Object.
129
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
2
3
5
Hold Shift
to select
multiple
objects.
2. In the Name field, enter a name for this object or leave as is to accept the default.
3. In the Description field, enter brief text that explains the intent of this object (for
reference).
4. The Show drop-down list allows you narrow the scope of the displayed objects.
5. Hold the Shift key and select Check Authorization and Branch_AV_Req.
6. Click Add. The selected objects appear in the Selected Action Objects field.
7. Click OK. The CombinedAction1 object appears as a separate, selectable object.
8. Select CombinedAction1; click OK. The object is now part of the rule.
Based on the other parameters specified in the rule, all requests are forced to an
upstream server for authorization and the Web responses are subject to content
scanning through the ICAP service.
Example Two
In the following example, the rule searches for one of the Proxy IP Address/Port objects and
one of the streaming client user agents.
130
Chapter 3: The Visual Policy Manager
Note
The VPM displays various warning messages if you attempt to add objects that creates an
invalid combined object. However, it is possible to add a combined object to another
combined object, even if doing so presents duplication of simple object definitions
without receiving validation warnings. For example, the contents of a child combined
object might have already been included either within the parent combined object directly,
or indirectly within other child combined objects. This is allowable because of the
complexity some combined objects and policies can achieve.
Viewing Objects
The All Objects feature allows you view a list of all objects—both static and user-
defined—that currently exist across all layers and columns. To view all configured VPM
objects, in the Menu Bar select View > All Objects.
131
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
The objects are displayed according to the policy layer order (click Policy in the menu bar)
and the column order (as presented in “Policy Layer and Rule Object Reference” on page
38). To narrow the scope of the displayed objects, select from the Show drop-down list at
the top:
❐ All (sort by object name): Displays all objects in alphabetical order.
❐ You can select to display only the static (predefined) objects for the Source,
Destination, Service, and Action columns.
❐ You can select to display or any one object type. For example, you want to only view
the user-defined P2P Client objects. Scroll down and select P2P Client Objects.
132
Chapter 3: The Visual Policy Manager
Managing Objects
This section describes how to manage objects within the All Objects dialog.
Creating Objects
The All Objects dialog also allows you to create objects. Once an object is created, it
appears in the list. When creating or editing policy layers, the objects are available to add
to rules.
To create an object:
1. Select New. The available columns and relevant objects are displayed in a cascade
style.
2. Select Column > Object. The Add dialog for that object appears.
3. Define the object as required
4. Click OK.
Note: When creating Combined Objects, not all objects that appear in the left
column are valid for more than one policy layer type. For example, the IM User object
is only valid in the Web Access Layer > Source column. If you attempt to add an
object that is not valid, a dialog appears with that information.
Editing Objects
Any user-defined object can be modified. Highlight the object and click Edit. After editing
the object, re-install the policy to apply the modified object in every policy layer it exists
in.
133
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Deleting Objects
You cannot delete an object that is currently part of an installed policy or combined object.
Before removing an object, you can use the View>Object Occurrences feature to identify
which policy layers contain the object.
Creating Categories
This feature allows you create the content filter URL categories that can be used in the
Category object. The Destination column in the DNS Access, Web Access, Web
Authentication, and Web Content policy layers contain the Category object. Similarly,
categories created in the Category object (see “Request URL Category” on page 68) appear
in this dialog and can be edited.
Create a category
1. In VPM, select Configuration > Edit Categories. The Edit Categories dialog appears.
134
Chapter 3: The Visual Policy Manager
4. Drop the Policy list and select the created category; click Edit URLs. The Edit Locally
Defined Category Object dialog appears.
Add URLs to
create a category
of URLs.
5. Enter URLs appropriate for the content filter category you are creating; click OK.
6. Click OK in the Edit Categories dialog to complete the category creation.
135
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Refreshing Policy
In between occurrences when either VPM is closed and reopened or Install Policies is
invoked, VPM does not recognize changes to VPM-managed policy that were made on the
SG appliance through another method. For example:
❐ Another administrator opens a separate VPM to make changes.
❐ Another administrator edits the local or central policy file through the serial console.
❐ Another administrator makes edits the local or central policy file.
❐ A new content filter database is downloaded automatically and the new update
contains category changes.
❐ A new content filter database is downloaded manually by an administrator.
136
Chapter 3: The Visual Policy Manager
a. Select Listed Host Patterns. This enables the Host Patterns field.
b. Click Add; the Add Host Pattern dialog appears.
c. Enter a domain name; click OK.
d. Repeat to add other domain names.
e. Click OK.
137
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
138
Chapter 3: The Visual Policy Manager
Note: These files are stored only if the policy is installed without any errors.
❐ How the appliance evaluates those rules in relation to policy layers that exist in the
central and local policy files is important. For more information, see Chapter 2:
"Managing Policy Files" on page 15.
139
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
140
Chapter 3: The Visual Policy Manager
The company also allows members of the group Sales to access various sports Web sites
only during non-work hours. Given the Web Authentication rule above, these people
must authenticate when they do this. But the company feels that it is not important for
people going to these sites after hours to authenticate. So the company creates the
following Web Access policy-layer rule:
❐ Grant Sales personnel access to sports Web sites from 5:00 PM to midnight.
But there are additional issues. Some members of the sales department spend a lot of
time watching game highlights on video clips, and this takes up a lot of bandwidth.
At the same time, a lot of customers access the company Web site in the evening
(during non-work hours), so internal bandwidth should remain manageable. The
company, therefore, limits the bandwidth available to the people in the Sales
department with a Web Access layer rule that is identical to the one above in all
respects except for the action:
❐ Grant Sales personnel access to sports Web sites from 5:00 PM to midnight, but limit
the maximum streaming bitrate to 300 kilobits per second.
For both these rules to work, they need to be in separate policy layers. If they were in the
same policy layer, the rule listed second would never be applied.
141
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
142
Chapter 3: The Visual Policy Manager
4. Define an object or objects just as you would in a policy layer. These objects determine
if the rest of the rules in the layer are evaluated. For example, if you specify a
Destination IP address in the layer guard rule, the other rules in the layer are
evaluated only when the SG appliance detects the a transaction destined for that IP
address.
Note: If you create and install a “Notify User” object, the following layer guard CPL is
automatically added to the Web Access, Web Content, and SSL Access policy layers:
"condition=!__is_notify_internal". This is required for compatibility does not
require any user interaction or tasks.
Note: Alternately, right-click the layer tab to add, disable, or remove a layer guard rule.
Installing Policies
As you add policy layers and rules, your work is saved in a file on the SG appliance.
However, policies only take effect after you install the policies and the generated XML has
been validated. The SG appliance then compiles the policies into CPL format and saves
the resulting policies in the vpm.cpl file. This overwrites any policies previously created
using VPM. The appliance saves VPM-generated policies in a single file and loads it all at
once. You do not need to load policies separately, as is the case with the local or central
policy files.
To install policies:
❐ Select File > Install Policies, or
❐ Click Install Policies on the Rule bar.
The VPM validates the generated XML for any issues, such as missing layers. If the
validation passes, the CPL is generated and the policies are loaded.
If the XML fails the validation, a dialog appears allowing you to:
• Revert to the policy currently installed on the SG appliance, or
• Continue to edit the policy and attempt another installation.
Furthermore, the failed XML file is written to your hard disk; view this file to
troubleshoot the failed XML. The default location for this file is:
C:\Documents and Settings\user.name\bluecoat\vpm_err.xml
143
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Notes
The Category and Notify User objects and the DNS Lookup Restrictions, Reverse DNS
Lookup Restrictions, and Group Log Order configuration objects generate CPL, regardless
if they are or are not included in rules. These specific objects and features allow users to
edit categories and lists that might or might not be used in current policies.
Managing Policy
This section describes how to manage VPM policy.
Refreshing Policy
In between occurrences when either VPM is closed and reopened or Install Policies is
invoked, VPM does not recognize changes to VPM-managed policy that were made on the
SG appliance through another method. For example:
❐ Another administrator opens a separate VPM to make changes.
❐ Another administrator edits the local or central policy file through the serial console.
❐ Another administrator makes edits the local or central policy file.
❐ A new content filter database is downloaded automatically and the new update
contains category changes.
❐ A new content filter database is downloaded manually by an administrator.
Changing Policies
You can change, edit, delete, add to, and otherwise manage policies created in VPM at any
time by returning to VPM and working with policy layers and rules just as you did when
creating them.
144
Chapter 3: The Visual Policy Manager
Note: All of the above procedures can be accomplished from the Menu Bar>Edit drop-
down list.
145
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
You can install VPM policies that were created on another SG appliance. This requires the
following steps:
1. Copy the two VPM files, to be shared, to a Web server from the SG appliance on which
they reside.
2. Use the Management Console or CLI to load VPM files on another SG appliance.
Important: The Save As dialog offers the appropriate default file name
(config_policy_source.xml or config_policy_source.txt). You can change the
names, including the extension. This can be helpful if an enterprise is using various
sets of shared VPM files. You could rename files to indicate the SG appliance on which
they were created, for example, or for a department that has a set of VPM-specific
policies, used perhaps in multiple locations (sales_vpm.cpl and sales_vpm.xml).
146
Chapter 3: The Visual Policy Manager
2b
2a
c. In the Installation URL field, enter the URL to the VPM CPL file copied to the
Web server (this is the file with the default .txt extension) and click Install.
d. Repeat Steps a through c to enter the URL to the second VPM XML file copied
to the Web server (this is the file with the default .xml extension) and click
Install.
3. Click Apply.
Notes
❐ If VPM files already exist on the SG appliance, the URLs to those files display in the
two file fields. To replace them, delete the URLs and type new ones. Installing new
files overwrites any that are already present.
❐ To review VPM-generated policies before installing them, enter the URL to the CPL
file on the Web server and click View.
❐ Regardless of whether you are installing new VPM files, you can review the CPL or
XML files of the policies currently on the SG appliance. Click VPM-CPL and VPM-XML
in the View Visual Policy Files box at the bottom of the dialog.
❐ Never edit either of the VPM files directly. Change the files only by working with the
policies in VPM and saving changes there.
147
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Important: Do not edit or alter VPM-generated files by opening the VPM policy file
and working in the generated CPL. To edit, change, or add to VPM policies, edit the
policy layers and re-install the policy.
148
Chapter 3: The Visual Policy Manager
Section E: Tutorials
Section E: Tutorials
This section contains the following topics:
❐ “ Tutorial—Creating a Web Authentication Policy”
❐ “ Tutorial—Creating a Web Access Policy”
3. A dialog displays offering a default name for the layer, consisting of the layer type
and a number. Rename the layer or accept the default and click OK.
The VPM creates the new layer tab and adds a blank rule.
149
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
1. Right-click the Source cell to drop the menu; select Set to open the Set Source Object
dialog.
2. Select a proxy IP address or port; if necessary, click New to create a new one. This
example selects the IP address on the SG appliance where the PAC file sends most
employee browsers.
3. Click OK to enter the IP address in the Source cell.
150
Chapter 3: The Visual Policy Manager
Section E: Tutorials
4. Create an authentication Action object. Right-click the Action cell to drop the menu
and select Set; the Set Action Object dialog displays.
5. The only objects available are the pre-existing static objects, so you must create a new
Authenticate object. Click New and select Authenticate. The Add Authenticate Object
window displays.
151
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
8. Click OK.
152
Chapter 3: The Visual Policy Manager
Section E: Tutorials
11
12
153
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
2. People in the purchasing group use the same PAC file and thus their browsers are
directed to the same IP address: 10.1.1.1.
154
Chapter 3: The Visual Policy Manager
Section E: Tutorials
The new rule in the policy layer accepts the default Action Object to not authenticate
and does not require a Trace Object.
4. Select the second rule and click Move Up to reorder the rules.
5. Click Install Policy.
155
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
The
default
is Deny.
2. Right-click Destination and select Set; the Set Destination Object dialog appears.
3. Click New; select Combined Destination Object. The Add Combined Destination Object
dialog appears.
156
Chapter 3: The Visual Policy Manager
Section E: Tutorials
157
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
158
Chapter 3: The Visual Policy Manager
Section E: Tutorials
9. Select each newly added URL and click the first Add button.
10. Click OK. The Set Destination Object now contains the individual URL objects and the
combined object.
11. Select the JobSearchURLs combined object and click OK. The object is now part of the
rule.
159
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
1. Add a new rule to the policy and position the pointer in the Source cell.
2. Right-click the Source cell and select Set to display the Add Source Object dialog.
3. Click New and select Combined Source Object; the Add Combined Source Object
appears.
160
Chapter 3: The Visual Policy Manager
Section E: Tutorials
6. Enter the IP address of the first workstation and click Add; repeat for the second; click
Close.
161
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
162
Chapter 3: The Visual Policy Manager
Section E: Tutorials
1. Right-click the Destination field and select Set; the Set Destination Object dialog
appears.
2. Click New and select Request URL Category; the Add Request Category Object dialog
appears.
163
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
3. Select Policy and click Add; the Enter Name for New Category dialog appears.
4. Name the object Allowable_Sports and click OK.
5. Select Sports URLs. Click Edit URLs. The Edit Locally Defined Category Object dialog
appears.
164
Chapter 3: The Visual Policy Manager
Section E: Tutorials
6. Enter the URLs for the allowable sports Web sites and click OK.
165
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
1. In the second rule, right-click the Time field and select Set; the Set Time Object dialog
appears.
2. Click New and select Time Object; the Add Time Object dialog appears.
166
Chapter 3: The Visual Policy Manager
Section E: Tutorials
167
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Section E: Tutorials
168
Chapter 4: Advanced Policy Tasks
This chapter provides conceptual and procedural information about the SG appliance
advanced policy features. While many SG appliance features have a policy component,
some features have no configuration component outside policy. Configuring advanced
policy is accomplished by defining rules in the Visual Policy Manager (VPM) or by
composing Content Policy Language (CPL). While some examples are provided in this
chapter, references to the relevant VPM chapter component are included in each
section.
This chapter contains the following topics:
❐ Section A: "Blocking Pop Up Windows" on page 170
❐ Section B: "Stripping or Replacing Active Content" on page 172
❐ Section C: "Modifying Headers" on page 175
❐ Section D: "Defining Exceptions" on page 176
❐ Section E: "Managing Peer-to-Peer Services" on page 188
❐ Section F: "Managing QoS and Differential Services" on page 194
Excluding exceptions, you must use policy to implement these capabilities. (For
exceptions, you can create a list outside of policy to install on the system.)
169
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Interactivity Notes
Because of the dynamic nature of the Web, blocking pop up windows is not a perfect
solution. Consider the following caveats before configuring this feature:
❐ Windows that contain desired or useful information cannot be distinguished from
undesired content, such as advertisements.
❐ If the Web browser caches a page that spawns pop up windows before the blocking
policy was installed, pop up ads continue to be served from that page regardless of
current policy.
❐ Animated ads contained within Web pages are not blocked. Commonly seen in
scrolling or drop-down form, these are not true pop up windows but are contained
within the page. Users who see these ads might believe that pop up window blocking
is not implemented.
❐ Pop up windows that are delivered through HTTPS are not blocked.
❐ Although the SG appliance request headers instruct a Web server not to use
compression, it is possible (though not likely) for a Web server to be configured to
send compressed responses anyway. The pop up blocking feature does not work on
compressed HTML pages.
Recommendations
❐ To compensate for limiting factors, administrators and users can override pop up
blocking:
• Administrators—Use the VPM to create policy rules that exempt pop up blocking
for specific Web sites and IP address ranges. For example, Blue Coat recommends
disabling pop up blocking for your Intranet, which commonly resides on a IP
address range.
170
Chapter 4: Advanced Policy Tasks
171
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: Pages served over an HTTPS tunneled connection are encrypted, so the content
cannot be modified.
❐ Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
Script Tags
Scripts are generally placed between the start and end tags <SCRIPT> and </SCRIPT>.
The type of script used is defined by the LANGUAGE attribute; for example, <SCRIPT
LANGUAGE=”JavaScript 1.0”>). When the LANGUAGE attribute is undefined, the browser
assumes JavaScript.
172
Chapter 4: Advanced Policy Tasks
JavaScript Entities
JavaScript entities have the following format: &{javascript code} and are found
anywhere in the value part of an attribute (that is, <IMG SRC=”&{images.logo};”). You
can define more than one entity in the value portion of the attribute. When transform
active_content is configured to remove scripts, all JavaScript entities attribute/value
pairs are removed. No replacement text is put in its place.
JavaScript Strings
JavaScript strings have the following format: javascript: javascript code and are
found anywhere in the value part of an attribute, though usually only one of them can be
defined in an attribute. Most modern browsers support JavaScript strings. When
transform active_content is configured to remove scripts, all JavaScript string
attribute/value pairs are removed. No replacement text is put in its place.
JavaScript Events
JavaScript events are attributes that start with the keyword on. For example, <A
HREF=”index.html onMouseOver=”javascript code”>. The HTML 4.01 specification
defines 21 different JavaScript events:
onBlur, onChange, onClick, onDblClick, onDragDrop, onFocus, onKeyDown,
onKeyPress, onKeyUp, onLoad, onMouseDown, onMouseMove, onMouseOut,
onMouseOver, onMouseUp, onMove, onReset, OnResize, onSelect, onSubmit,
onUnload
Both Microsoft Internet Explorer and Netscape have defined variations on these events as
well as many new events. To catch all JavaScript events, the active content transformer
identifies any attribute beginning with the keyword on, not including on itself. For
example, the attribute onDonner in the tag <A HREF=”index.html”
onDONNER=”DONNER”> is removed even though onDonner does not exist as a valid
JavaScript event in the browser. In this case, the transformed file would show <A
HREF=”index.html”>.
Embed Tags
HTML <EMBED> tags are not required to have an </EMBED> end tag. Many Web browsers
do, however, support the <EMBED> </EMBED> tag pair. The text between the tags is
supposed to be rendered by the browsers when there is no support for the embed tag, or if
the MIME-type of the embed object is not supported. Thus, when transform
active_content is configured to transform embed tags, only the <EMBED> tag is removed
and replaced with any replacement text. Any occurrence of the end tag </EMBED> is
simply removed, leaving the text between the beginning and end tags intact.
173
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Object Tags
Objects tags have a start <OBJECT> and end </OBJECT> tag pair, and the attributes
CODETYPE and TYPE determine the type of object. The text between the tags is supposed to
be rendered by the browsers when the object tag is not supported, so when transform
active_content is configured to transform object tags, only the <OBJECT> and </
OBJECT> tags are removed and replaced with any replacement text. The text between the
tags remains. The CODETYPE or TYPE attributes do not affect the transformation. Also, if
the end </OBJECT> tag is missing, the transformation will not be affected.
174
Chapter 4: Advanced Policy Tasks
❐ Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
175
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Built-in Exceptions
Built-in exceptions are a set of pre-defined exceptions contained on the SG appliance.
Built-in exceptions send information back to the user under operational contexts that are
known to occur, such as policy_denied or invalid_request.
Built-in exceptions are always available and can also have their contents customized;
however, built-in exceptions cannot be deleted, and you cannot create new built-in
exceptions.
The table below lists the built-in exceptions and the context under which they are issued.
176
Chapter 4: Advanced Policy Tasks
177
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
178
Chapter 4: Advanced Policy Tasks
179
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
User-Defined Exceptions
User-defined exceptions are created and deleted by the administrator. If a user-defined
exception is referenced by policy, it cannot be deleted. The default HTTP response code
for user-defined exceptions is 403.
Note: For users who are explicitly proxied and use Internet Explorer to request an
HTTPS URL, an exception body longer than 900 characters might be truncated. The
workaround is to shorten the exception body.
An exception body less than 512 characters might cause a page does not exist 404 error. If
this occurs, use the exception.autopad(yes|no) property to pad the body to more than
513 characters. For more information on the exception.autopad property, refer to the
Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
Important: Fields other than Format must be less than 8000 characters. If they are
greater than this, they are not displayed.
180
Chapter 4: Advanced Policy Tasks
When defining the above fields, you can use substitution variables that are particular to
the given request. Some of the above fields are also available as substitutions:
❐ $(exception.id)
❐ $(exception.summary)
❐ $(exception.details)
❐ $(exception.help)
❐ $(exception.contact)
Additionally, the Format, Summary, Details, Help and Contact fields can be configured
specifically for HTTP, or configured commonly for all protocols.
The Format field, the body of the exception, is not available as a substitution. However,
the Format field usually includes other substitutions. For example, the following is a
simple HTML format:
<html>
<title>$(exception.id): $(exception.summary)</title>
<body><pre>
Request: $(method) $(url)
Details: $(exception.details)
Help: $(exception.help)
Contact: $(exception.contact)
</pre></body></html>
Some additionally useful substitutions related to exceptions are:
❐ $(exception.last_error)—For certain requests, the SG appliance determines
additional details on why the exception was issued. This substitution includes that
extra information.
❐ $(exception.reason)—This substitution is determined internally by the SG
appliance when it terminates a transaction and indicates the reason that the
transaction was terminated. For example, a transaction that matches a DENY rule in
policy has its $(exception.reason) set to "Either 'deny' or 'exception' was
matched in policy".
181
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: The default HTTP format and built-in exception definitions have been removed for
example purposes.
(exception.all
(contact "For assistance, contact your network support team.")
(details "")
(format "$(exception.id): $(exception.details)")
(help "")
(summary "")
(http
(code "200")
(contact "")
(details "")
(format <<EOF
<format removed>
EOF
)
(help "")
(summary "")
)
<built-in exceptions removed>
)
182
Chapter 4: Advanced Policy Tasks
183
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
184
Chapter 4: Advanced Policy Tasks
❐ Using a remote URL, where you place an already-created exceptions list on an FTP or
HTTP server to be downloaded to the SG appliance.
Note: A message is written to the event log when you install a list through the SG
appliance.
When the Exceptions file is customized, it updates the existing exceptions already on the
SG appliance. The configuration remains in effect until it is overwritten by another
update; it can be modified or overwritten using CLI commands.
3
2
2. From the Install Exceptions Definitions From drop-down list, select the method used to
install the exceptions configuration.
3. Click Install.
• Installing from a Remote URL:
Enter the fully-qualified URL, including the filename, where the configuration is
located. To view the file before installing it, click View. Click Install. View the
installation status; click OK.
• Installing by browsing to a Local File: Click Browse to bring up the Local File
Browse window.
185
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Browse for the file on the local system. Open it and click Install. When the
installation is complete, a results window opens. View the results, close the
window, and click Close.
• Installing a policy file using the SG appliance Text Editor:
Viewing Exceptions
You can view the exceptions defined on the SG appliance, including how the defined
HTML appears to users. The following are the viewable defined exception components:
❐ Current Exceptions—Displays all of the exceptions as they are currently defined.
❐ Exceptions Configuration—Displays a page from which you can click links to view
how exceptions appear in HTML to users.
186
Chapter 4: Advanced Policy Tasks
❐ Results of Exception Load—Displays the results of the last installable list load,
including any errors and warning to be fixed.
2. From the View Exceptions field, View File drop-down list, select the page to view.
• Current Exceptions—Displays all of the exceptions as they are currently defined.
• Default Exceptions Source—Displays the default SG appliance exceptions.
• Exceptions Configuration—Displays a page from which you can click links to view
how exceptions appear in HTML to users.
• Results of Exception Load—Displays the results of the last installable list load,
including any errors and warning to be fixed.
3. Click View. An new browser appears with the current requested information.
4. Click Apply.
187
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: Neither caching nor acceleration are provided with this feature.
Supported Services
This version of SGOS supports the following P2P services:
❐ FastTrack (Kazaa)
❐ EDonkey
❐ BitTorrent
❐ Gnutella
Note: Refer to the Release Notes for the most current list of P2P services and versions the
SG appliance supports.
Deployment
To effectively manage P2P activity, the SG appliance must be deployed to intercept
outbound network traffic and the firewall configured to block outbound connections that
are not initiated by the SG appliance.
188
Chapter 4: Advanced Policy Tasks
Notes:
❐ The SG appliance intercepts outbound TCP network connections, as routed through
an L4 switch or a SG appliance in bridging mode.
❐ Configure SG appliance HTTP, SOCKS, and TCP tunnel services for destination ports
to be monitored.
❐ Create firewall rules that allow only outbound connections that are initiated by the SG
appliance.
❐ You can block all known P2P ports and define policy to stop P2P traffic attempting to
come through over HTTP
.
Note: This features does not include additional configurations for intercepting or
controlling UDP traffic.
Policy Control
This section lists the policy used to manage P2P.
VPM Support
The following VPM components relate to P2P control:
CPL Support
CPL Triggers
❐ http.connect={yes | no}
❐ p2p.client={yes | no | bittorrent | edonkey | fasttrack | gnutella}
CPL Properties
❐ force_protocol()
❐ detect_protocol.protocol(yes | no)
❐ detect_protocol.[protocol1, protocol2, ...](yes | no)
❐ detect_protocol(all | none)
❐ detect_protocol(protocol1, protocol2, ...)
Where protocol is: http, bittorrent, edonkey, fasttrack, or gnutella.
189
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Support CPL
The following properties can be used in conjunction with the P2P-specific CPL:
❐ allow, deny, force_deny
Policy Example
The following policy example demonstrates how to deny network traffic that the SG
appliance recognizes as P2P:
<proxy>
p2p.client=yes deny
Note: Some P2P statistics (P2P client connections and total bytes sent and received over a
period of time) can only be viewed through the Management Console (see "P2P Clients"
and "P2P Bytes", below).
P2P Data
The P2P Data tab on the Management Console displays P2P statistics, either all P2P
services at once or one service at a time.
The following table details the statistics provided through the Management Console P2P
Data tab or through the CLI
Status Description
Current Tunneled Sessions The current number of P2P client connections using native
transport.
190
Chapter 4: Advanced Policy Tasks
Current HTTP Requests The current number of HTTP requests from P2P clients.
Total Tunneled Sessions The cumulative number of P2P client connections using
native transport since the SG appliance was last rebooted.
Total HTTP Requests The cumulative number of HTTP requests from P2P clients
since the SG appliance was last rebooted.
Total Bytes Received The total number of bytes received from all P2P clients.
Total Bytes Sent The total number of bytes sent to all P2P clients.
2. (Optional) To view the statistics for a specific P2P protocol, make a selection from the
Protocol drop-down list.
P2P Clients
The P2P Clients tab displays dynamic graphical statistics for client connections received in
the last 60-minute, 24-hour, or 30-day period.
Note: The P2P client statistics are available only through the Management Console.
191
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
P2P Bytes
The P2P Bytes tab displays dynamic graphical statistics for the total number of bytes sent
to and received from P2P clients in the last 60-minute, 24-hour, or 30-day period.
Note: The P2P bytes statistics are available only through the Management Console.
2. (Optional) To set the graph scale to a different value, select a value from the Graph
scale should drop-down list.
192
Chapter 4: Advanced Policy Tasks
Proxy Authentication
While P2P protocols do not support native proxy authentication, most P2P clients support
SOCKS v5 and HTTP 1.1 proxies. P2P proxy authentication is supported only for clients
using these protocols (that are configured for proxy authentication).
For information about proxy authentication, refer to Volume 4: Securing the Blue Coat SG
Appliance. For a list of P2P clients suspected of not supporting SOCKS v5 with
authentication, see the Release Notes for this release.
Access Logging
P2P activity is logged and reviewable. Refer to Volume 8: Access Logging.
193
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Note: The SG appliance policy requests a QoS level. Whether or not a level of QoS
can be achieved depends upon your network/router configurations, which must also
allow the level of requested QoS.
ToS is an eight-bit field in the IP header; the first six bits are used and the final two are
reserved for other TCP specification and control. The first six bits constitute the DSCP
value. For most networks, the DSCP values adhere to a standard set. The following table
lists these values.
194
Chapter 4: Advanced Policy Tasks
Note: Before creating policy, verify that your network adheres to these values. Other
DSCP values are possible. You can specify a numerical range from 0 to 63. However,
Blue Coat recommends using the above classifications, as most applications are
associated to these classes already, which makes defining policy an easier task.
195
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Example Policy
Three client connection DSCP Source objects associated with three bandwidth
management level Action objects.
Figure 4-3. A VPM example that tests QoS and assigns a BWM action
The above VPM example generates the following CPL:
<Proxy>
client.connection.dscp=(ef) limit_bandwidth.client.outbound(High)
client.connection.dscp=(cs3,af31,af32,af33)
limit_bandwidth.client.outbound(Medium)
client.connection.dscp=(cs1) limit_bandwidth.client.outbound(Low)
Caching Behavior
Detecting the QoS cannot occur for cached content. In the case of a cache hit, when no
server connection is established, no server connection DSCP value is available for policy
checks.
Multiple Connections
Some services use multiple client to server connections. When a service uses multiple
connections, the triggers to test the inbound DSCP value apply to the primary control
connection, which is (usually) the first connection opened by the client and the
corresponding connection (if any) opened to the server. For example:
❐ FTP connections are comprised of a control connection and a data connection.
❐ IM connections involve connections to other hosts, such as chat buddies or file
sharing hosts.
196
Chapter 4: Advanced Policy Tasks
Figure 4-4. The Blue Coat appliance preserves client-to-server and server-to-client DSCP values
(default)
Example Policy
<proxy>
client.connection.dscp(preserve) server.connection.dscp(preserve)
197
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Example Policy
<proxy>
user=A client.connection.dscp(echo)
198
Chapter 4: Advanced Policy Tasks
Figure 4-7. Setting DSCP values, based on user level, from the SG appliance to users
Example Policy
<proxy>
client.connection.dscp(echo)
user=vp_sales server.connection.dscp(CS4)
server.connection.dscp(cs2)
Policy Components
This section lists the existing VPM and CPL policy components.
VPM Objects
Objects: (the cross-references are to the object descriptions in Chapter 3: "The Visual
Policy Manager"):
❐ “Client Connection DSCP Trigger” on page 63—Web Access, DNS Access layers:
Source column.
❐ “Server Connection DSCP Trigger” on page 74—Web Access, DNS Access, Web
Content, Forwarding layers: Destination column.
❐ “Set Server Connection DSCP Value” on page 115—Web Access, DNS Access, Web
Content, Forwarding layers: Destination column.
❐ “Set Client Connection DSCP Value” on page 114—Web Access, DNS Access layers:
Action column.
❐ “Set Server Connection DSCP Value” on page 115—Web Access, Forwarding layers:
Action column.
VPM Example
The following VPM screen illustrates configuring a Web Access rule to set the DSCP value
for P2P connections to Best Effort (no priority).
199
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
CPL Components
The following are the CPL triggers and properties:
Triggers
❐ client.connection.dscp = 0..63 | af11 | af12 | af13 | af21 | af22 |
af23 | af31 | af32 | af33 | af41 | af42 | af43 | best-effort | cs1 |
cs2 | cs3 | cs4 | cs5 | cs6 | cs7 | ef
Valid layers: <proxy>, <dns-proxy>, <forward>
❐ server.connection.dscp = 0..63 | af11 | af12 | af13 | af21 | af22 |
af23 | af31 | af32 | af33 | af41 | af42 | af43 | best-effort | cs1 |
cs2 | cs3 | cs4 | cs5 | cs6 | cs7 | ef
Valid layers: <proxy>, <dns-proxy>, <cache>
Properties
❐ adn.connection.dscp(0..63 | af11 | af12 | af13 | af21 | af22 | af23 |
af31 | af32 | af33 | af41 | af42 | af43 | best-effort | cs1 | cs2 | cs3
| cs4 | cs5 | cs6 | cs7 | ef | preserve)
Valid layers: <forward>
❐ client.connection.dscp(0..63 | af11 | af12 | af13 | af21 | af22 | af23
| af31 | af32 | af33 | af41 | af42 | af43 | best-effort | cs1 | cs2 |
cs3 | cs4 | cs5 | cs6 | cs7 | ef | echo | preserve)
Valid layers: <proxy>, <dns-proxy>
200
Chapter 4: Advanced Policy Tasks
Access Logging
The following access log formats are associated with QoS activity:
❐ x-cs-connection-dscp: The incoming client DSCP value.
201
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
202
Appendix A: Glossary
access log A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.
account A named entity that has purchased the appliance or the Entitlements from Blue Coat.
activation code A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.
active content stripping Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.
active content types Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user
administration access policy A policy layer that determines who can access the SG appliance to perform
administrative tasks.
administration A policy layer that determines how administrators accessing the SG appliance must
authentication policy authenticate.
Application Delivery A WAN that has been optimized for acceleration and compression by Blue Coat. This
Network (ADN) network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.
ADN backup manager Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.
ADN manager Responsible for publishing the routing table to SG Clients (and to other SG
appliances).
ADN optimize attribute Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
asx rewrite Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxy-
like support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.
audit A log that provides a record of who accessed what and how.
203
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
authenticate-401 attribute All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios
authenticated content Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).
authentication Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate Authority.
See also basic authentication, proxy authentication, and SSL authentication.
authentication realm Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.
bandwidth class hierarchy Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.
bandwidth management Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.
basic authentication The standard authentication for communicating with the target as identified in the
URL.
BCAAA Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.
byte-range support The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).
cache An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.
cache control Allows you to configure which content the SG appliance stores.
204
Appendix A: Glossary
cache efficiency A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.
cache hit Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.
cache miss Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .
cache object Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.
Certificate Authority (CA) A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.
child class (bandwidth gain) The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.
client consent certificates A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.
client-side transparency A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.
concentrator An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.
content filtering A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.
default boot system The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.
denial of service (DoS) A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.
205
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
destination objects Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.
detect protocol attribute Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
diagnostic reporting Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.
directives Commands used in installable lists to configure forwarding and SOCKS gateway.
DNS access A policy layer that determines how the SG appliance processes DNS requests.
domain name system (DNS) An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.
dynamic bypass Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.
dynamic real-time rating Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
(DRTR) dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.
early intercept attribute Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.
ELFF-compatible format A log type defined by the W3C that is general enough to be used with any protocol.
emulated certificates Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.
encrypted log A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.
event logging Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.
206
Appendix A: Glossary
explicit proxy A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.
extended log file format A variant of the common log file format, which has two additional fields at the end of
(ELFF) the line—the referer and the user agent fields.
fail open/closed Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.
forward proxy A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.
gateway A device that serves as entrance and exit into a communications network.
hardware serial number A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.
health check tests The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
• ICMP
• TCP
• SSL
• HTTP
• HTTPS
• Group
• Composite and reference to a composite result
• ICAP
• Websense
• DRTR rating service
207
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
health check type The kind of device or service the specific health check tests. The following types are
supported:
• Forwarding host and forwarding group
• SOCKS gateway and SOCKS gateway group
• CAP service and ICAP service group
• Websense off-box service and Websense off-box service group
• DRTR rating service
• User-defined host and a user-defined composite
heartbeat Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.
host affinity The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.
host affinity timeout The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.
inbound traffic (bandwidth Network packets flowing into the SG appliance. Inbound traffic mainly consists of
gain) the following:
• Server inbound: Packets originating at the origin content server (OCS) and sent to
the SG appliance to load a Web object.
• Client inbound: Packets originating at the client and sent to the SG appliance for
Web requests.
installable lists Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
• Creating the list using the SG text editor
• Placing the list at an accessible URL
• Downloading the directives file from the local system
integrated host timeout An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.
intervals Time period from the completion of one health check to the start of the next health
check.
IP reflection Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.
208
Appendix A: Glossary
issuer keyring The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.
licensable component (LC) (Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.
license Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.
listener The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.
live content Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.
load balancing A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.
local bypass list A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.
local policy file Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).
log facility A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.
log format The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.
log tail The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.
209
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
Management Console A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.
management information Defines the statistics that management systems can collect. A managed device
base (MIB) (gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.
maximum object size The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.
MIME/FILE type filtering Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.
multi-bit rate The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).
multicast Used in streaming; the ability for hundreds or thousands of users to play a single
stream.
multicast aliases Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel
multicast station Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).
multimedia content services Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.
name inputing Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server
native FTP Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).
NCSA common log format Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.
network address translation The process of translating private network (such as intranet) IP addresses to Internet
(NAT) IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.
210
Appendix A: Glossary
non-cacheable objects A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
• Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
• Password provided, requests that include a client password.
• Data in request that include additional client data.
• Not a GET request.
.nsc file Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.
NTP To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.
object (used in caching) An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.
object (used in Visual Policy An object (sometimes referred to as a condition) is any collection or combination of
Manager) entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.
object pipelining This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.
origin content server (OCS) Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.
outbound traffic (bandwidth Network packets flowing out of the SG appliance. Outbound traffic mainly consists
gain) of the following:
• Client outbound: Packets sent to the client in response to a Web request.
• Server outbound: Packets sent to an OCS or upstream proxy to request a service.
PAC (Proxy Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
AutoConfiguration) scripts port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.
packet capture (PCAP) Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.
211
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
parent class (bandwidth A class with at least one child. The parent class must share its bandwidth with its
gain) child classes in proportion to the minimum/maximum bandwidth values or priority
levels.
passive mode data Data connections initiated by an FTP client to an FTP server.
connections (PASV)
policies Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.
policy-based bypass list Used in policy. Allows a bypass based on the properties of the client, unlike static and
dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.
policy layer A collection of rules created using Blue Coat CPL or with the VPM.
pragma: no cache (PNC) A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).
proxy Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.
proxy service The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.
proxy service (default) The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.
public key certificate An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).
public virtual IP (VIP) Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.
212
Appendix A: Glossary
real-time streaming protocol A standard method of transferring audio and video and other time-based media over
(RTSP) Internet-technology based networks. The protocol is used to stream clips to any RTP-
based client.
reflect client IP attribute Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.
registration An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.
remote authentication dial- Authenticates user identity via passwords for network access.
in user service (RADIUS)
reverse proxy A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.
routing information protocol Designed to select the fastest route to a destination. RIP support is built into Blue
(RIP) Coat appliances.
router hops The number of jumps a packet takes when traversing the Internet.
secure shell (SSH) Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.
serial console A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.
server certificate categories The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.
server portals Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping a
set of external URLs onto a set of internal URLs.
server-side transparency The ability for the server to see client IP addresses, which enables accurate client-
access records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.
service attributes Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .
213
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
SG appliance A Blue Coat security and cache box that can help manage security and content on a
network.
sibling class (bandwidth A bandwidth class with the same parent class as another class.
gain)
simple network The standard operations and maintenance protocol for the Internet. It uses MIBs,
management protocol created or customized by Blue Coat, to handle (needs completion).
(SNMP)
simulated live Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.
SmartReporter log type A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.
SOCKS A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.
SOCKS proxy A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.
splash page Custom message page that displays the first time you start the client browser.
split proxy Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
• Mapi Proxy
• SSL Proxy
SQUID-compatible format A log type that was designed for cache statistics and is compatible with Blue Coat
products.
squid-native log format The Squid-compatible format contains one line for each request.
SSL authentication Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).
SSL proxy A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.
static route A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.
214
Appendix A: Glossary
statistics Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated, cache
efficiency, cached contents, and custom URLs generated by the appliance for various
kinds of logs. You can also check the event viewer for every event that occurred since
the appliance booted.
stream A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.
SurfControl log type A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.
system cache The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.
time-to-live (TTL) value Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.
traffic flow Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
(bandwidth gain) that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of
these connections, traffic flows in two directions—in one direction, packets flow out
of the SG appliance (outbound traffic), and in the other direction, packets flow into
the SG (inbound traffic). Connections can come from the client or the server. Thus,
traffic can be classified into one of four types:
• Server inbound
• Server outbound
• Client inbound
• Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.
transmission control TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
protocol (TCP) in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.
transparent proxy A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.
215
Volume 6: The Visual Policy Manager and Advanced Policy Tasks
trial period Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.
unicast alias Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicast-
alias command to request the content from the origin streaming server.
universal time coordinates An SG appliance must know the current UTC time. By default, the appliance
(UTC) attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.
URL rewrite rules Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.
WCCP Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.
Web FTP Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
OCS (if the content is not already cached), and then translates the FTP response with
the file contents into an HTTP response for the client.
Websense log type A Blue Coat proprietary log type that is compatible with the Websense reporter tool.
216
Blue Coat® Systems
SG™ Appliance
Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
ii
Contents
Contact Information
Chapter 1: Introduction
Document Conventions......................................................................................................................................7
iii
Volume 7: Managing Content
iv
Contents
Appendix A: Glossary
Index
v
Volume 7: Managing Content
vi
Chapter 1: Introduction
Applying content filtering and virus scanning to requested and posted Web content in
an enterprise is vital to securing the network and improving productivity.
❐ Content filtering allows you to regulate, based on content categories, which Web
sites employees are allowed to access and which are restricted.
❐ Virus scanning allows you to scan both incoming content and content leaving the
enterprise network for viruses and other malicious code, such as drive-by software
that propagates spyware.
This document contains the following chapters:
❐ Chapter 2: "Filtering Web Content"
❐ Chapter 3: "Malicious Content Scanning Services"
❐ Chapter 4: "Configuring Service Groups"
Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Conventions Definition
Courier font Command line text that appears on your administrator workstation.
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.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
7
Volume 7: Managing Content
8
Chapter 2: Filtering Web Content
This chapter describes how to configure the SG appliance to process client Web
requests and filter the returning content.
This chapter contains the following sections:
❐ "Section A: About Filtering Web Content" on page 10
❐ "Section B: Configuring Blue Coat Web Filter" on page 14
❐ "Section C: Configuring a Local Database" on page 20
❐ "Section D: Configuring Internet Watch Foundation" on page 24
❐ "Section E: Configuring a Third-Party Vendor" on page 28
❐ "Section F: Applying Policy" on page 35
❐ "Section G: Configuring Websense Off-box Content Filtering" on page 42
9
Volume 7: Managing Content
Important: Because of the dynamic nature of the Internet, there is a constant flow of
new URLs (and URLs on lesser-known sites) that will not be in the existing content
filtering database. Those URLs that are not in the database are marked as none, and you
can create a policy to categorize these.
Note: You can request that specific URLs be reviewed for correct categorization, if your
content filtering provider supports this. For Blue Coat Web Filter, visit
http://sitereview.bluecoat.com/ to have a URL's category reviewed.
10
Chapter 2: Filtering Web Content
The following diagram illustrates the process flow when Web content filtering (on-box or
off-box) is employed in the network.
Legend
A: A client connected to the ProxySG.
B: ProxySG content filtering solution (conftent filter vendor + Blue Coat policy).
C: Web Content.
Process Flow
1: (Blue arrow) The client requests a Web page.
2: The ProxySG checks the requested URL against the content filtering database to determine
the categorization.
3: After the URL is categorized, the policy engine determines if the URL is allowable or ? not.
4: (Blue arrow) The URL is allowed and the request continues to its destination.
5. (Red arrow) The policy denies the request and returns a message concerning? corporate
Web compliance.
Note: For information about the IWF, visit their Web site at http://www.iwf.org.uk/.
11
Volume 7: Managing Content
Note: BCWF supports many languages. Refer to the Blue Coat Release Notes for this
release for the most up-to-date list of supported languages.
Note: If the category returned by this service is blocked by policy, the offending material
never enters the network in any form.
12
Chapter 2: Filtering Web Content
Legend
A: A client connected into the ProxySG.
B: ProxySG with BCWF content filtering and DRTR enabled.
C: DRTR server.
D: Web content.
Process Flow
1: (Blue arrow) Client 1 requests a Web page.
2: The ProxySG checks the requested URL against the BCWF database for
categorization. No match is found.
3: The remote Dynamic Rating Service accesses and analyzes the requested site,
categorizes the content.
4: After the URL is categorized, the policy engine determines if the URL is allowable
or not.
5: (Blue arrow) The URL is allowed and the request continues to its destination for
full retrieval.
6. (Red arrow) The policy denies the request and returns a message concerning
corporate Web compliance.
Figure 2-2. BCWF with DRTR Content Employed
13
Volume 7: Managing Content
Important: BCWF requires a valid license provided by Blue Coat. Refer to the
Licensing chapter in Volume 1: Getting Started.
14
Chapter 2: Filtering Web Content
Note: The substitution values are empty if the database was not consulted for
categorization or if the categorization process failed due to an error.
Note: If this is the first time you enabled BCWF, a small database that contains the
category list is downloaded, allowing immediate policy creation.
No username or password is required during the trial period (60 days). To download
the database on demand or on a schedule, you must configure BCWF service.
2. When you subscribed to BCWF Service, you received a username and password for
access to download updates. (If you are in the trial period, no username or password
is required.)
a. In the Username field, enter your username.
b. Click Change Password. The Change Password dialog displays.
c. Enter your password and click OK.
3. Download the database:
a. The default database download location displays in the URL field.
Note: Only enter a new URL if instructed. Otherwise, accept the default.
4. Click Download Now. The Download Status dialog displays, stating that a download
has started.
15
Volume 7: Managing Content
Note: When the database is downloaded, a log is available that includes detailed
information about how the database was updated. You can view the download log in the
Management Console by clicking View Download Status on the BCWF tab, selecting
Statistics > Advanced > Content Filter Service, or in the CLI (SGOS#(config) show
content-filter status).
16
Chapter 2: Filtering Web Content
a. Select the Only between the hours of check box. The time frame is local time.
b. Click the arrows to view the drop-down lists, and set the time period for your
update schedule. For example, to check for updates between the hours of 8
am and midnight, set the first box to 08:00 and the second box to 23:59.
2. Click Apply to commit the changes to the SG appliance.
SOCKS Gateways
When you use proxy chaining to forward DRTR requests through an upstream SOCKS
gateway, you must configure the SOCKS gateway.
17
Volume 7: Managing Content
If both a forwarding host or group alias and a SOCKS gateway are specified in the proxy
chain, the SG appliance attempts the connection through the SOCKS gateway to the
forwarding target.
Configuring DRTR
Complete the following procedures to configure DRTR. Note that Enable Dynamic
Categorization (DRTR) is enabled by default.
To configure DRTR:
1. Select Configuration > Content Filtering > Blue Coat > Dynamic Categorization (DRTR).
18
Chapter 2: Filtering Web Content
Diagnostics
Diagnostics allows you to see all categories available for use in policy or test a URL
against the database. Categories are not displayed for a vendor or local database if no
database has been downloaded.
19
Volume 7: Managing Content
Note: Blue Coat recommends locating your local database on the same server as any
policy files you are using.
20
Chapter 2: Filtering Web Content
21
Volume 7: Managing Content
Future Downloads
You can return to this screen at any time and download a database on demand
(independent of the automatic download feature, which is described in the next section).
Ordinarily, the SG appliance checks to see if the database has changed before initiating a
download. If the database is the most current, no download is performed.
Note: When the database is downloaded, a log is available that includes detailed
information about how the database was updated. You can view the download log in the
Management Console by selecting Statistics > Advanced > Content Filter Service, or in the
CLI (SGOS#(config) show content-filter status).
2. Select the Only between the hours of check box. The time frame is local time.
3. Click the arrows to view the drop-down lists and set the time period for your update
schedule. For example, to check for updates between the hours of 8 am and midnight,
set the first box to 08:00 and the second box to 23:59.
4. Click Apply to commit the changes to the SG appliance.
Diagnostics
Allows you to see all categories available for use in policy or test a URL against the
database. Categories are not displayed for a vendor or local database if no database has
been downloaded.
22
Chapter 2: Filtering Web Content
23
Volume 7: Managing Content
24
Chapter 2: Filtering Web Content
Note: Only enter a new URL if instructed. Otherwise, accept the default.
Future Downloads
You can return to this screen at any time and download a database on demand
(independent of the automatic download feature, which is described in the next section).
Ordinarily, the SG appliance checks to see if the database has changed before initiating a
download. If the database is the most current, no download is performed. If an
incremental update is available on the server, then it is downloaded (an incremental
update contains only the changes between the current installed version and the latest
published version of the database, and is much smaller than a full copy of the database).
25
Volume 7: Managing Content
Note: When the database is downloaded, a log is available that includes detailed
information about how the database was updated. You can view the download log in the
Management Console by selecting Statistics > Advanced > Content Filter Service, or in the
CLI (SGOS#(config) show content-filter status).
2. Select the Only between the hours of check box. The time frame is always local time.
3. Click the arrows to view the drop-down lists and set the time period for your update
schedule. For example, to check for updates between the hours of 8 am and midnight,
set the first box to 08:00 and the second box to 23:59.
4. Click Apply to commit the changes to the SG appliance.
Diagnostics
This allows you to test a URL against the database.
To test a URL:
1. Select Configuration > Content Filtering > General.
2. Enter the URL into the URL field.
3. Click Test.
26
Chapter 2: Filtering Web Content
27
Volume 7: Managing Content
2. From the 3rd-party database drop-down list, select your preferred vendor.
3. Select the Lookup Mode.
a. The default is Always, which specifies that the third-party database will
always be consulted for category information.
b. Uncategorized specifies that the lookup is skipped if the URL has already been
found in policy, a Local database, the Internet Watch Foundation (IWF)
database, or BCWF.
4. (Optional and applicable for SmartFilter and BCWF only) Select Enable Category
Review Message in Exceptions. This adds a link to the default content filter exception
page that can be used to request review of the categories assigned to a blocked URL.
Two substitutions ($(exception_category_review_url) and
$(exception_category_review_message)) are automatically appended to the help
element of all exception definitions. For information on using the
$(exception.help) element, refer to Volume 6: VPM and Advanced Policy.
28
Chapter 2: Filtering Web Content
Note: The substitution values are empty if the provider was not consulted for
categorization, or if the categorization process failed due to an error.
6. Proceed accordingly:
• SmartFilter: Continue with: “Configuring SmartFilter” on page 30.
• Websense: Continue with: “Configuring Websense (on-box)” on page 31.
• i-Filter, InterSafe, Optenet, Proventia, SurfControl, or Webwasher: Continue with
Step 7.
7. Select Configuration > Content Filtering > vendor:
8. (This example uses Surf Control.) If the database is located on a server that requires a
password for access, you must configure the SG appliance to use that password when
accessing the database:
a. Enter your third-party vendor username.
b. Click Change Password. The Change Password dialog displays.
c. Enter your password and click OK.
9. Download the database:
a. The default database download location is displayed in the URL field. If you
have been instructed to use a different URL, enter it here (optional: click Set to
default to always use this location).
b. Click Download Now. The Installation Status dialog box displays.
When the operation is complete, the dialog changes to indicate installation status.
c. Click Results to see the completion message:
29
Volume 7: Managing Content
Download log:
SurfControl download at: 2007/06/07 17:40:42-0400
Downloading from https://list.bluecoat.com/.../download/
surfcontrol.db
Warning: Unable to determine current database version; requesting full
update
Download size: 8106572
Database date: Wed, 07 Jun 2007 08:11:51 UTC
Database expires: Fri, 07 Jul 2007 08:11:51 UTC
Database version: 3
d. Click OK.
10. Click Apply to commit the changes to the SG appliance.
11. Continue with “Specifying a Custom Time Period to Update a Third-Party Database”
on page 33.
Future Downloads
You can return to this screen at any time and download a database on demand
(independent of the automatic download feature, which is described in the next section).
Ordinarily, the SG appliance checks to see if the database has changed before initiating a
download. If the database is the most current, no download is performed. If an
incremental update is available on the server, then it is downloaded (an incremental
update contains only the changes between the current installed version and the latest
published version of the database, and is much smaller than a full copy of the database).
Configuring SmartFilter
The SmartFilter database configuration screen contains unique options.
Configure SmartFilter:
1. Select Configuration > Content Filtering > SmartFilter:
2. Configure SmartFilter:
a. In the License key field, enter the customer serial number assigned you by
Secure Computing.
b. In the Server field, the default server is displayed. If you have been instructed
to use a different server, enter the hostname or IP address here.
c. Click Download now. The SmartFilter Installation status dialog box displays
with the message SmartFilter download in progress.
30
Chapter 2: Filtering Web Content
When the operation is complete, the dialog changes to indicate installation status.
d. Click Results to see the completion message:
Download log:
SmartFilter download at: 2007/06/07 17:40:42-0400
Checking incremental update
Warning: Unable to open input control list
Warning: Unable to open installed control list
Downloading full control file
SmartFilter download at: 19 June 2007 17:40:42-0400
Downloading from http://example.com/...version=4.0
Download size: 45854194
Database version: 95
Database date: Wed, 07 Jun 2007 08:11:51 UTC
Database expires: Fri, 07 Jul 2007 08:11:51 UTC
Note: The first time you download a SmartFilter database, warnings appear in
the results message under Checking incremental update. These are
expected, and represent the normal process of checking to see if an incremental
update is possible. The next time you download a SmartFilter database, the SG
appliance checks the previously downloaded database, and downloads only
what is necessary to keep the database current.
31
Volume 7: Managing Content
2. In the License Key field, enter the key assigned to you for downloading the Websense
database.
3. In the Server field, the default server is displayed. If you have been instructed to use a
different server, enter the hostname or IP address here.
4. (Optional) In the Contact e-mail field, enter an e-mail address by which Websense can
contact you.
5. Click Download now. The Websense Installation status dialog box displays with the
message Websense download in progress.
6. Click Apply to view the Websense download log:
Download log:
Websense download at: 2007/06/21 17:40:42-0400
No database is currently installed
Attempting full download
Downloading from download.websense.com
Processing download file
Retrieved full update
Download size: 147079939
Database version: 82300
Database date: 2007/06/21
License expires: 2007/07/21 08:11:51 UTC
License max users: 25
Licenses in use: 0
Library version: 3.2.0.0 [BCSI rev A]
7. Click OK.
8. (Optional) Always apply regular expressions to urls:
32
Chapter 2: Filtering Web Content
Select this option to force an additional regular expression lookup for each URL to be
categorized. Normally, regular expression lookups are done only when no category is
found in the Websense database. If this option is selected, regular expression lookups
always occur, even for categorized URLs. Selecting this option can cause a significant
reduction in lookup performance, but allow certain sites (such as translation, search
engine, and link-cache sites) to be categorized more accurately.
9. To use the Websense Reporter, you must enable the Websense Integration Service.
a. In the Integration Service Host field, enter the Integration Service Host IP
(which has the same IP address as the Websense Log Server).
b. In the Port field, specify the port of the Websense Integration Service. It must
be between 0 and 65535 and match the port selected on the Integration Service
host.
c. Select Enabled to enable the service.
d. (Optional) Select Log forwarded client address. Normally, the SG logs the
actual client IP address to the Websense Reporter log. You can configure the
SG to log an address obtained from the X-Forwarded-For HTTP Header (if
present and valid) instead. This is useful in some specific network topologies.
Note: The Policy Server, the Log Server, and Reporter must be installed and
enabled on your PC before Reporter can be used. For information on Websense
products, refer to: http://www.websense.com/support/documentation/
integrationservice.
You must also set up access logging on the SG appliance with Websense as the
client. For more information on configuring a Websense access logging client,
refer to Volume 8: Access Logging.
Note: When the database is downloaded, a log is available that includes detailed
information about how the database was updated. You can view the download log in the
Management Console by selecting Statistics > Advanced > Content Filter Service, or in the
CLI (SGOS#(config) show content-filter status).
33
Volume 7: Managing Content
2. Select the Only between the hours of check box. The time frame is always local time.
3. Click the arrows to view the drop-down lists and set the time period for your update
schedule. For example, to check for updates between the hours of 8 am and midnight,
set the first box to 08:00 and the second box to 23:59.
4. Click Apply to commit the changes to the SG appliance.
Diagnostics
This allows you to see all categories available for use in policy or test a URL against the
database. Categories are not displayed for a vendor or local database if no database has
been downloaded.
34
Chapter 2: Filtering Web Content
Note: If you have extensive category definitions, Blue Coat recommends that you put
them into a local database rather than into a policy file. The local database stores custom
categories in a more scalable and efficient manner, and separates the administration of
categories from policy. See "Section C: Configuring a Local Database" on page 20.
The policy trigger category= is used to test the category or categories assigned to the
request URL, and thus make a policy decision. For example, to block all requests for URLs
that are categorized as Sports:
DENY category=Sports
The following example demonstrates a condition that is true when a request contains the
Websense content categories Sexuality and Drugs:
<proxy>
category=(sexuality, drugs)
You can block multiple categories with a single rule:
category=(Sports, Gambling, Shopping) exception(content_filter_denied)
In this example, three categories are blocked and instead the predefined exception page
content_filter_denied is served; by default this indicates that the request was denied
due to its content and specifies the categories found.
The following example shows a condition that includes an extensive number of
categories:
category=(Abortion, Activist, Adult, Gambling, Illegal, Hacking,
Militancy, Racism, Shopping, Tasteless, Violence, Weapons)
URLs that are not categorized are assigned the system category none. This is not an error
condition; many sites (such as those inside a corporate intranet) are unlikely to be
categorized by a commercial service. Use category=none to detect uncategorized sites
and apply relevant policy. The following example disallows access to uncategorized sites
outside of the corporate network:
define subnet intranet
10.0.0.0/8 ; internal network
192.168.123.45; external gateway
end
<proxy>
; allow unrestricted access to internal addresses
ALLOW url.address=intranet
35
Volume 7: Managing Content
Such category tests can also be combined with other types of triggers to produce more
complex policy, such as:
❐ Restrict access by category and time: block sports from 6 am to 6 pm:
category=Sports time=0600..1800 DENY
❐ Restrict by category and user identity: only members of the group Sales are permitted
to visit Shopping sites:
category=Shopping group=!Sales DENY
❐ Require special authentication for access to certain categories:
category=Hacking authenticate(restricted_realm)
where restricted_realm is an authentication realm you have configured.
❐ Log certain types of access:
category=Adult action.Log_adult_site_access(yes)
where Log_adult_site_access is a policy action defined elsewhere that records
extra information about this request in the event log.
Typically, category= can be used in policy anywhere that a basic URL test can be used.
Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for more details.
Depending on which provider you have selected and whether you have defined any of
your own categories in policy (see “Defining Custom Categories in Policy” on page 38),
you have a number of possible category names that can be used with category=. To
review the valid category names, use the categories CLI command or click View
Categories in the Management Console: Configuration > Content Filtering > General.
The category= expressions are normally put in <Proxy> Layers (VPM: Web Access
Layers) because the goal of content filtering policy is to control requests from users. They
can also be used in <Cache> (VPM: Web Content Layers) Layers. Either way, policy is
enforced on all user requests.
It is possible for an attempt to categorize a URL to fail—for example, if no database is
loaded, your license is expired, or if a system error occurs. In such a case, the category is
considered unavailable and triggers such as:
category=Sports
are false, even if the URL is actually a sports site, because the SG appliance is unable to
determine the category. When the policy depends on the category of a URL, you do not
want such errors to inadvertently allow ordinarily restricted content to be served by the
SG appliance. You can control how the SG appliance treats these situations with the
condition:
category=unavailable
which is true in these cases. In continuing with the example, to make sure that Sports is
always blocked, even when errors occur (this is a mode of operation called fail-closed), use
a rule such as:
category=(sports, unavailable) exception(name_of_exception page)
This rule is true if the category is sports or if the category could not be determined, and in
either case the proper exception page is served instead of the restricted content.
The category unlicensed is assigned in addition to unavailable when the failure to
categorize occurred because of license expiry. That can be caused by the expiration of
your Blue Coat license to use content filtering, or because of expiration of your license
from the provider. You can use
36
Chapter 2: Filtering Web Content
category=unlicensed
to detect this situation as a distinct case from other causes of unavailability.
You can also use this feature with custom exception pages (refer to Volume 6: VPM and
Advanced Policy):
<proxy>
category=sports time=0800..1800 exception(sports_during_bus_hrs)
category=unlicensed exception(contact_admin_re_license)
category=unavailable exception(content_filter_unavailable)
where sports_during_bus_hrs is a custom exception page you have created to
respond to requests for Sports pages between 8 am and 6 pm local time.
contact_admin_re_license is another page that instructs the user to inform the
administrator about license expiry, and is served if a license check fails. When the
category is unavailable for some other reason, the pre-defined exception
(content_filter_unavailable) is served.
The most common reason (other than license expiry) why categories are unavailable is
that a provider is selected but no database is installed. Barring hardware or network
problems that might cause a downloaded database to become corrupted and unreadable,
it is unlikely that the database will suddenly become unavailable.
To define policies on the SG appliance, use either the VPM or manually edit Policy files.
Content filtering policies are usually found in <Proxy> and <Cache> layers.
If you are using content filtering to manage a type of content globally, create these rules in
the <Cache> layer.
However, if your content filtering policy is dependent on user identity or request
characteristics, create these rules in the <Proxy> layer.
37
Volume 7: Managing Content
Example
Policy: Limit employee access to travel Web sites.
The first step is to rephrase this policy as a set of rules. In this example, the model of a
general rule and exceptions to that rule is used:
❐ Rule 1: All users are denied access to travel sites
❐ Rule 2: As an exception to the above, Human Resources users are allowed to visit
Travel sites
Before you can write the policy, you must be able to identify users in the Human
Resources group. You can do this with an external authentication server, or define the
group locally on the SG appliance. For information on identifying and authenticating
users, refer to Volume 4: Securing the Blue Coat SG Appliance.
In this example, a group called human_resources is identified and authenticated through
an external server called my_auth_server.
This then translates into a fairly straightforward policy written in the local policy file:
<proxy>
; Ensure all access is authenticated
Authenticate(my_auth_server)
<proxy>
; Rule 1: All users denied access to travel
DENY category=travel
<proxy>
; Rule 2: Exception for HR
ALLOW category=travel group=human_resources
DENY category=sites
Example
Policy: Student access to Health sites is limited to a specified time of day, when the Health
100 class is held.
This time the policy contains no exceptions:
❐ Rule 1: Health sites can be accessed Monday, Wednesday, and Friday from 10-11am.
❐ Rule 2: Health sites can not be accessed at other times.
define condition Health_class time
weekday=(1, 3, 5) time=1000..1100
end
<proxy>
; 1) Allow access to health while class in session
ALLOW category=health condition=health_class_time
; 2) at all other times, deny access to health
DENY category=health
38
Chapter 2: Filtering Web Content
❐ if you specify a path, all paths with that prefix are included (if you specify no path, the
whole site is included)
Example:
define category Grand_Canyon
kaibab.org
www2.nature.nps.gov/air/webcams/parks/grcacam
nps.gov/grca
grandcanyon.org
end
Any URL at kaibab.org is now put into the Grand_Canyon category (in addition to any
category it might be assigned by a provider). Only those pages in the /grca directory of
nps.gov are put in this category.
39
Volume 7: Managing Content
Example:
<proxy>
category=Webcams DENY
category=National_Parks ALLOW
category=Travel time =0800..1800 DENY
Click the Test button on the Management Console or the test-url command in CLI to
validate the categories assigned to any URL. This can help you to ensure that your policy
rules have the expected effect (refer to “Configuring Policy Tracing” in Volume 10: Blue
Coat SG Appliance Content Policy Language Guide).
If you are using policy-defined categories and a content-filter provider at the same time,
be sure that your custom category names do not coincide with the ones supplied by your
provider. You can also use the same names—this adds your URLs to the existing
categories, and extends those categories with your own definitions. For example, if the
webcam mentioned above was not actually categorized as Travel by your provider, you
could do the following to add it to the Travel category (for the purpose of policy):
define category Travel ; extending a vendor category
www2.nature.nps.gov/air/webcams/parks/grcacam/ ; add the GC webcam
end
Note: The policy definitions described in this section can also be used as
definitions in a local database. See “Configuring a Local Database” on page 20
for information about local databases.
Notes
❐ When you use an expired database, the category unlicensed is assigned to all URLs
and no lookups occur on the database. This can occur even if your download license
with the database vendor is still valid, but you have not downloaded a database for a
long time (databases expire after a certain number of days). You can view the date
that your database expires (or expired) in the download log or by using the view
command in the CLI.
When you download a database, you can see the download log as soon as the
download is complete. To see the download log when you download a database, click
Results in the Installation Status dialog when the download is complete.
To see the last download log without doing another download, enter the following
CLI (config) commands:
SGOS#(config) content-filter
SGOS#(config content-filter) view
❐ When your license with the database vendor expires, you can no longer download.
This does not have an immediate effect—you can still use the database you have for a
period of time. But eventually, the database expires and you receive the category
unlicensed, as described above.
40
Chapter 2: Filtering Web Content
❐ If you receive an error message when downloading a content filtering database, check
the error message (in the Management Console, click Results on the Installation status
dialog; in the CLI, the results message displays in the event of an error). If you see an
error message such as ERROR: HTTP 401 - Unauthorized, verify that you entered your
username and password correctly. For example, the following error message was
generated by entering an incorrect username and attempting to download a
SmartFilter database:
Download log:
SmartFilter download at: Thu, 21 June 2007 18:03:08
Checking incremental update
Checking download parameters
Fetching:http://example.com/
Warning: HTTP 401 - Unauthorized
Downloading full control file
SmartFilter download at: Thu, 21 June 2007 18:03:17
Downloading from http://example.com/
Fetching:http://example.com/
ERROR: HTTP 401 - Unauthorized
Download failed
Download failed
Previous download:
...
41
Volume 7: Managing Content
2b
2a
42
Chapter 2: Filtering Web Content
43
Volume 7: Managing Content
2. Make sure that you save changes to any open dialogs before proceeding.
3. Click OK to perform the health check. When the health check is complete, the Health
Check Results dialog displays information about the health check.
4. Click Close to close the Health Check Results dialog.
44
Chapter 2: Filtering Web Content
45
Volume 7: Managing Content
46
Chapter 3: Malicious Content Scanning Services
This chapter describes how to configure the SG appliance to interact with external
Internet Content Adaptation Protocol (ICAP) clients and servers to provide content
scanning and transformation.
This chapter contains the following sections:
❐ "Section A: About Content Scanning"
❐ "Section B: Configuring SG Appliance ICAP Communications"
❐ "Section C: Creating ICAP Policy"
❐ "Section D: Managing Virus Scanning"
47
Volume 7: Managing Content
Table 3-1. Content Types Scanned By ICAP Server and the SG Appliance
All or specified file types, based on the file • HTTP objects • Streaming content (for example,
extension, as configured on the server. RTSP and MMS)
Examples: .exe (executable programs), .bat • FTP objects (uploads
(batch files), .doc and .rtf (document files), and downloads) • Live HTTP streams (for example,
and .zip (archive files); or specific MIME HTTP radio streams)
types. • Transparent FTP
responses
Whenever an object is requested or being refreshed and it was previously scanned, the SG
appliance verifies whether the pattern file has been updated since it was last scanned. If it
was, the object is scanned again, even if the content has not changed. If the content has
changed, the object is rescanned.
With the SG appliance, you can define flexible, yet enterprise-specific content scanning
policies, which is discussed in the following two sections.
48
Chapter 3: Malicious Content Scanning Services
❐ Handling of certain objects, including those that are infected and cannot be repaired
❐ Whether to attempt to repair infected files
❐ Whether to delete infected files that cannot be repaired from the ICAP server’s
archive
The following diagram illustrates the response modification process flow.
Note: Some ICAP servers do not support virus scanning for request modification, but
support only content filtering.
49
Volume 7: Managing Content
50
Chapter 3: Malicious Content Scanning Services
Sense Settings
The Sense Settings feature allows the SG appliance to query any identified ICAP server
running v1.0, detect the parameters, and configure the ICAP service as appropriate. See
“Creating an ICAP Service” on page 56.
ISTags
An ICAP v1.0 server is required to return in each response an ICAP header ISTag, which
indicates the current state of the ICAP server. This eliminates the need to designate
artificial pattern version numbers, as is required in v0.95.
Note: Backing out a virus pattern on the ICAP server can revert ISTags to previous
values that are ignored by the SG appliance. To force the SG appliance to recognize the old
values, use the Sense Settings option, which is described in the configuration section.
Persistent Connections
New ICAP connections are created dynamically as ICAP requests are received (up to the
defined maximum connection limit). The connection remains open to receive subsequent
requests. If a connection error occurs, the connection closes to prevent more errors.
Notes
❐ Patience pages are not compatible with infinite stream connections—or live content
streamed over HTTP—such as a cam or video feed. ICAP scanning cannot begin until
the object download completes. Because this never occurs with this type of content,
the SG appliance continues downloading until the maximum ICAP file size limit is
breached. At that point, the SG appliance either returns an error or attempts to serve
the content to the client (depending on fail open/closed policy). However, even when
configured to fail open and serve the content, the delay added to downloading this
large amount of data is often enough to cause the a user give up before reaching that
point.
51
Volume 7: Managing Content
Note: This feature is supported for the HTTP proxy only; FTP connections are not
supported.
Figure 3-3. A client receives only the initial bytes of a transaction during the ICAP scan.
After the ICAP server completes its scan:
❐ If the object is deemed to be clean (no response modification is required), the SG
appliance sends the rest of the object bytes to the client at the best speed allowed by
the connection.
❐ If the object is deemed to be malicious, the SG appliance terminates the connection
and the remainder of the response object bytes—which in this case are the majority of
the bytes—are not sent to the client.
Deployment Notes
❐ This method is the more secure option because the client receives only a small amount
of data pending the outcome of the virus scan.
52
Chapter 3: Malicious Content Scanning Services
❐ One drawback is that users might become impatient, especially if they notice the
browser display of bytes received. They might assume the connection is poor or the
server is busy, close the client, and restart a connection.
Figure 3-4. A client receives most of the bytes immediately during the ICAP scan.
After the ICAP server completes its scan, the behavior is the same as described in
“Trickling Data From the Start” on page 52.
Deployment Notes
❐ Blue Coat recommends this method for media content, such as flash objects.
❐ This method is more user-friendly than trickle at start. This is because users tend to be
more patient when they notice that 99% of the object is downloaded versus 1%, and
are less likely to perform a connection restart. However, network administrators
might perceive this method as the less secure method, as a majority of the object is
delivered before the results of the ICAP scan.
53
Volume 7: Managing Content
Infinite Streams
Data trickling does not solve the issue of HTTP infinite streams. These are connections
such as webcams or flash media—traffic over an HTTP connection—that conceivably
have no end. Because the object cannot be fully downloaded, the ICAP content scan
cannot start; however, the connection between the SG appliance and the AV appliance
remains, which wastes finite connection resources. Strategic policy implementation,
however, might be able to identify infinite streams and mark them to not be anti-virus
scanned.
If you employ the data trickle at end method, the user experience with infinite streams
improves because the data is always delivered at the best connection speed possible.
54
Chapter 3: Malicious Content Scanning Services
Notes
❐ Failover is configured as part of the ICAP policy definition.
❐ You cannot configure failover policy until ICAP services are configured on the SG
appliance.
❐ To avoid errors, ICAP service names cannot be named fail_open or fail_closed (the
CLI commands prevent these names from being created).
55
Volume 7: Managing Content
Configuration Tasks
Configuring ICAP on the SG appliance involves the following steps:
❐ Install the ICAP server.
❐ Configure the SG appliance to use ICAP and configure basic features.
❐ Specify feedback method (patience pages or data trickling).
❐ Define scanning policies, then load the policy file on the SG appliance.
56
Chapter 3: Malicious Content Scanning Services
2a
2b
4a
4b
4c
4d
4e
a. In the Service URL field, enter the ICAP server URL (AV appliance), which
includes the URL schema, ICAP server hostname or IP address, and the ICAP
port number. For example:
57
Volume 7: Managing Content
icap://10.x.x.x/
The default port number is 1344, which can be changed. For example:
icap://10.x.x.x:99. You can also enter an HTTP URL, but you must define a
port number.
Note: An ICAP service pointing to a WebWasher server must use icap as the
protocol in the URL. Blue Coat also recommends that you review your specific
ICAP server documentation, as each vendor might require additional URL
information.
58
Chapter 3: Malicious Content Scanning Services
5b
5c
5d
5a
5e
Note: An ICAP server might have separate URLs for response modification
and request modification services.
c. In the Preview size (bytes) field, enter a byte value and select enabled. The
ICAP server reads the object up to the specified byte total. The ICAP server
either continues with the transaction (that is, receives the remainder of the
object for scanning) or opts out of the transaction.
The default is 0. Only response headers are sent to the ICAP server; more object
data is only sent if requested by the ICAP server.
d. (Optional) The Send options allow additional information to be forwarded to
the ICAP server. Select one or more of the following: Client address, Server
address, Authenticated user, or Authenticated groups.
e. Click Health check to perform an immediate health check on this service.
f. Click OK to close the dialog.
6. Click Apply.
59
Volume 7: Managing Content
Note: You cannot delete an ICAP service used in an SG appliance policy (that is, if a
policy rule uses the ICAP service name) or that belongs to a service group.
60
Chapter 3: Malicious Content Scanning Services
2a
2b
2c
3a
3b
3c
61
Volume 7: Managing Content
• Trickle object data at end: The client receives most (99%) of the object data, but
the final bytes are sent at the rate of one per second while the ICAP scanner
performs the scan. If the response from the ICAP server is clean, the client
receives the rest of the object data at the best connection speed possible. If the
scan detects malicious content, the connection is dropped. This is the least
secure method, as most of the data has already been delivered to the client.
However, this method provides the best user experience because there most
of the object is already delivered.
3. Configure options for non-interactive traffic (content such as flash animation over
HTTP):
a. The Do not provide feedback... option means that if users experience delays in
receiving content, they are not notified as to the reason (ICAP scanning).
Selecting this option greys out the other options.
b. The default duration to wait before notifiying a client that an ICAP scan is
occuring is five seconds. You can change this value in the Provide feedback
after field, but if you make the value too long, users might become impatient
and manually close the client, believing the connection is hung.
c. Select the feedback method:
• Trickle object data from start: See the descriptions in Step 2.
• Trickle object data at end: See the descriptions in Step 2.
4. Click Apply.
These configurations are global. You can define further feedback policy that applies to
specific user and conditional subsets. In the VPM, the object is located in the Web Access
Layer: Return ICAP Feedback.
62
Chapter 3: Malicious Content Scanning Services
2a
2b
2c
2d
2. In the HTTP Patience Page Customization section, click Header, Summary, Details, or
Help. The corresponding customize dialog appears. Customize the information as
appropriate.
b. Custom Patience Summary Message—HTML and text that informs users that
a content scan is occurring.
63
Volume 7: Managing Content
64
Chapter 3: Malicious Content Scanning Services
Interactivity Notes
❐ When ICAP scanning is enabled and a patience page is triggered, a unique URL is
dynamically generated and sent to the browser to access the patience page. This
unique URL might contain a modified version of the original URL. This is expected
behavior.
❐ Patience pages and exceptions can only be triggered by left-clicking a link. If a user
right-clicks a link and attempts to save it, it is not possible to display patience pages. If
this action causes a problem, the user might see browser-specific errors (for example,
an Internet site not found error); however, ICAP policy is still in effect.
❐ A patience page is not displayed if a client object request results in an HTTP 302
response and the SG appliance pipelines the object in the Location header. After the
SG appliance receives the client request for the object, the client enters a waiting state
because a server-side retrieval of the object is already in progress. The wait status of
the client request prevents the patience page from displaying. To prevent the SG
appliance from pipelining these requests (which decreases performance) and to retain
the ability to provide a patience page, configure HTTP as follows:
#SGOS (config) http no pipeline client redirects
❐ The status bar update does not work if it is disabled or if the Javascript does not have
sufficient rights to update it.
❐ Looping: Certain conditions cause browsers to re-spawn patience pages. For example,
a site states it will begin a download in 10 seconds, initiates a pop-up download
window, and returns to the root window. If the download window allows pop-ups,
the patience page displays in a separate window. The automatic return to the root
window initiates the download sequence again, spawning another patience page. If
unnoticed, this loop could cause a system hang. The same behavior occurs if the user
clicks the back button to return to the root window. For known and used download
sites, you can create policy that redirects the page so that it doesn’t return to the root
window after a download starts.
65
Volume 7: Managing Content
2. In the FTP Patience Page Customization field, click Summary; the Customize FTP
Patience Text dialog appears. Customize the FTP client patience text as appropriate.
3. Click OK.
4. Click Apply.
66
Chapter 3: Malicious Content Scanning Services
VPM Objects
The VPM contains the following objects specific to AV scanning (linked to their
descriptions in the VPM chapter).
Object Layer>Column
Note: For CPL policy, refer to Volume 10: Blue Coat SG Appliance Content Policy Language
Guide.
67
Volume 7: Managing Content
To perform virus scanning, protecting both the server side and the client side:
1. In the VPM, select Policy > Web Access Layer. Name the layer RequestAV.
2. Right-click the Action column; select Set. The Set Action Object dialog appears.
3. Click New.
4. Select Set ICAP Request Service; the Add ICAP Request Service Object dialog
displays.
5a
5b
5c
68
Chapter 3: Malicious Content Scanning Services
10a
10b
10c
10d
69
Chapter 3: Malicious Content Scanning Services
70
Volume 7: Managing Content
71
Chapter 3: Malicious Content Scanning Services
CPL Notes
❐ If policy specifies that an ICAP service is to be used, but the service is not available,
the default behavior is to fail closed—that is, deny the request or response. The
following CPL allows the serving of objects without ICAP processing if the server is
down.
request.icap_service(service_name, fail_open)
response.icap_service(service_name, fail_open)
When the ICAP service is restored, these objects are scanned and served from the
cache if they are requested again.
Note: Blue Coat recommends this CPL to be used for internal sites; use with caution.
72
Volume 7: Managing Content
73
Chapter 3: Malicious Content Scanning Services
Advanced Configurations
This section summarizes more-advanced configurations between the SG appliance and
multiple ICAP servers. These brief examples provide objectives and suggest ways of
supporting the configuration.
74
Chapter 3: Malicious Content Scanning Services
Access Logging
The SG appliance provides access log support for Symantec and Finjan ICAP 1.0 server
actions (Management > Access Logging). The following sections describe access logging
behavior for the various supported ICAP servers.
Resolution= Specifies an integer value that indicates what action was taken to fix
the file. Zero (0) defines the file is unrepairable, one (1) specifies that
the file was repaired, and two (2) specifies that the file was deleted.
Threat= Specifies the name of the virus.
Note: The access log string cannot exceed 256 characters. If the header name or value
extends the length over the limit, then that string does not get logged. For example, if the
x-virus-id header value is 260 characters, the access log displays "x-virus-id: " with
no value because the value is too long to display. Also, if the access log string is already
250 characters and the SG appliance attempts to append a "Malicious-Mobile-Type: "
string, the string is not appended
Access log entries might vary depending upon the type of ICAP scan performed and the
custom log formats. For information about Access Logging, refer to Volume 8: Access
Logging.
75
Volume 7: Managing Content
76
Chapter 4: Configuring Service Groups
This chapter describes how to create and manage ICAP or Websense service groups. In
high-traffic network environments, a service group accelerates response time by a
performing a higher volume of scanning.
Note: External services (ICAP, Websense off-box) have a reserved connection for
health checks (if you created health check services). This means that as the load goes
up and the number of connections to the external service reaches the maximum, with
additional requests being queued up and waiting, the maximum simultaneous
connections is actually one less than the limit.
The following diagram provides an example of how weighting works with a service
group of three Blue Coat AV ICAP servers.
77
Volume 7: Managing Content
Note: Setting the weight value to 0 (zero) disables weighted load balancing for the ICAP
service. Therefore, if one ICAP server of a two-server group has a weight value of 1 and
the second a weight value of 0, should the first server go down, a communication error
results because the second server cannot process the request.
While you cannot specifically designate an ICAP server in a group as a backup, you can
specify weight values that create a large differential between a server that is used
continuously and one that is rarely used, thus simulating a backup server.
78
Chapter 4: Configuring Service Groups
2b
2a
79
Volume 7: Managing Content
4b
4c
4a
80
Chapter 4: Configuring Service Groups
5b
5a
Note: A service or service group used in a SG appliance policy (that is, if a policy rule
uses the entry) cannot be deleted; it must first be removed from the policy.
81
Volume 7: Managing Content
82
Chapter 4: Configuring Service Groups
; External Service-Groups
CorpICAP
total weight 5
entries:
ICAP1
weight 4
ICAP2
weight 1
BranchWebsense
total weight 2
entries:
Websense1
weight 1
Websense2
weight 1
83
Volume 7: Managing Content
84
Appendix A: Glossary
access log A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.
account A named entity that has purchased the appliance or the Entitlements from Blue Coat.
activation code A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.
active content stripping Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.
active content types Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user
administration access policy A policy layer that determines who can access the SG appliance to perform
administrative tasks.
administration A policy layer that determines how administrators accessing the SG appliance must
authentication policy authenticate.
Application Delivery A WAN that has been optimized for acceleration and compression by Blue Coat. This
Network (ADN) network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.
ADN backup manager Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.
ADN manager Responsible for publishing the routing table to SG Clients (and to other SG
appliances).
ADN optimize attribute Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
asx rewrite Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxy-
like support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.
audit A log that provides a record of who accessed what and how.
85
Volume 7: Managing Content
authenticate-401 attribute All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios
authenticated content Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).
authentication Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate
Authority. See also basic authentication, proxy authentication, and SSL
authentication.
authentication realm Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.
bandwidth class hierarchy Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.
bandwidth management Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.
basic authentication The standard authentication for communicating with the target as identified in the
URL.
BCAAA Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.
byte-range support The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).
cache An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.
86
Appendix A: Glossary
cache control Allows you to configure which content the SG appliance stores.
cache efficiency A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.
cache hit Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.
cache miss Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .
cache object Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.
Certificate Authority (CA) A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.
child class (bandwidth gain) The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.
client consent certificates A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.
client-side transparency A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.
concentrator An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.
content filtering A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.
default boot system The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.
87
Volume 7: Managing Content
denial of service (DoS) A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.
destination objects Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.
detect protocol attribute Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
diagnostic reporting Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.
directives Commands used in installable lists to configure forwarding and SOCKS gateway.
DNS access A policy layer that determines how the SG appliance processes DNS requests.
domain name system (DNS) An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.
dynamic bypass Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.
dynamic real-time rating Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
(DRTR) dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.
early intercept attribute Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.
ELFF-compatible format A log type defined by the W3C that is general enough to be used with any protocol.
emulated certificates Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.
encrypted log A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.
88
Appendix A: Glossary
event logging Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.
explicit proxy A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.
extended log file format A variant of the common log file format, which has two additional fields at the end of
(ELFF) the line—the referer and the user agent fields.
fail open/closed Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.
forward proxy A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.
gateway A device that serves as entrance and exit into a communications network.
hardware serial number A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.
89
Volume 7: Managing Content
health check tests The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
• ICMP
• TCP
• SSL
• HTTP
• HTTPS
• Group
• Composite and reference to a composite result
• ICAP
• Websense
• DRTR rating service
health check type The kind of device or service the specific health check tests. The following types are
supported:
• Forwarding host and forwarding group
• SOCKS gateway and SOCKS gateway group
• CAP service and ICAP service group
• Websense off-box service and Websense off-box service group
• DRTR rating service
• User-defined host and a user-defined composite
heartbeat Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.
host affinity The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.
host affinity timeout The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.
inbound traffic (bandwidth Network packets flowing into the SG appliance. Inbound traffic mainly consists of
gain) the following:
• Server inbound: Packets originating at the origin content server (OCS) and sent to
the SG appliance to load a Web object.
• Client inbound: Packets originating at the client and sent to the SG appliance for
Web requests.
90
Appendix A: Glossary
installable lists Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
• Creating the list using the SG text editor
• Placing the list at an accessible URL
• Downloading the directives file from the local system
integrated host timeout An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.
intervals Time period from the completion of one health check to the start of the next health
check.
IP reflection Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.
issuer keyring The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.
licensable component (LC) (Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.
license Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.
listener The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.
live content Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.
load balancing A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.
local bypass list A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.
local policy file Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).
log facility A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.
91
Volume 7: Managing Content
log format The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.
log tail The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.
Management Console A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.
management information Defines the statistics that management systems can collect. A managed device
base (MIB) (gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.
maximum object size The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.
MIME/FILE type filtering Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.
multi-bit rate The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).
multicast Used in streaming; the ability for hundreds or thousands of users to play a single
stream.
multicast aliases Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel
multicast station Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).
multimedia content services Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.
92
Appendix A: Glossary
name inputing Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server
native FTP Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).
NCSA common log format Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.
network address translation The process of translating private network (such as intranet) IP addresses to Internet
(NAT) IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.
non-cacheable objects A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
• Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
• Password provided, requests that include a client password.
• Data in request that include additional client data.
• Not a GET request.
.nsc file Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.
NTP To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.
object (used in caching) An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.
object (used in Visual Policy An object (sometimes referred to as a condition) is any collection or combination of
Manager) entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.
object pipelining This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.
93
Volume 7: Managing Content
origin content server (OCS) Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.
outbound traffic (bandwidth Network packets flowing out of the SG appliance. Outbound traffic mainly consists
gain) of the following:
• Client outbound: Packets sent to the client in response to a Web request.
• Server outbound: Packets sent to an OCS or upstream proxy to request a service.
PAC (Proxy Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
AutoConfiguration) scripts port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.
packet capture (PCAP) Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.
parent class (bandwidth A class with at least one child. The parent class must share its bandwidth with its
gain) child classes in proportion to the minimum/maximum bandwidth values or priority
levels.
passive mode data Data connections initiated by an FTP client to an FTP server.
connections (PASV)
policies Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.
policy-based bypass list Used in policy. Allows a bypass based on the properties of the client, unlike static
and dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.
policy layer A collection of rules created using Blue Coat CPL or with the VPM.
pragma: no cache (PNC) A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).
proxy Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.
94
Appendix A: Glossary
proxy service The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.
proxy service (default) The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.
public key certificate An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).
public virtual IP (VIP) Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.
real-time streaming protocol A standard method of transferring audio and video and other time-based media over
(RTSP) Internet-technology based networks. The protocol is used to stream clips to any RTP-
based client.
reflect client IP attribute Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.
registration An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.
remote authentication dial- Authenticates user identity via passwords for network access.
in user service (RADIUS)
reverse proxy A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.
routing information protocol Designed to select the fastest route to a destination. RIP support is built into Blue
(RIP) Coat appliances.
router hops The number of jumps a packet takes when traversing the Internet.
95
Volume 7: Managing Content
secure shell (SSH) Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.
serial console A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.
server certificate categories The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.
server portals Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping
a set of external URLs onto a set of internal URLs.
server-side transparency The ability for the server to see client IP addresses, which enables accurate client-
access records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.
service attributes Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .
SG appliance A Blue Coat security and cache box that can help manage security and content on a
network.
sibling class (bandwidth A bandwidth class with the same parent class as another class.
gain)
simple network The standard operations and maintenance protocol for the Internet. It uses MIBs,
management protocol created or customized by Blue Coat, to handle (needs completion).
(SNMP)
simulated live Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.
SmartReporter log type A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.
SOCKS A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.
SOCKS proxy A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.
splash page Custom message page that displays the first time you start the client browser.
96
Appendix A: Glossary
split proxy Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
• Mapi Proxy
• SSL Proxy
SQUID-compatible format A log type that was designed for cache statistics and is compatible with Blue Coat
products.
squid-native log format The Squid-compatible format contains one line for each request.
SSL authentication Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).
SSL proxy A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.
static route A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.
statistics Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated,
cache efficiency, cached contents, and custom URLs generated by the appliance for
various kinds of logs. You can also check the event viewer for every event that
occurred since the appliance booted.
stream A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.
SurfControl log type A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.
system cache The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.
time-to-live (TTL) value Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.
97
Volume 7: Managing Content
traffic flow Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
(bandwidth gain) that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of
these connections, traffic flows in two directions—in one direction, packets flow out
of the SG appliance (outbound traffic), and in the other direction, packets flow into
the SG (inbound traffic). Connections can come from the client or the server. Thus,
traffic can be classified into one of four types:
• Server inbound
• Server outbound
• Client inbound
• Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.
transmission control TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
protocol (TCP) in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.
transparent proxy A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.
trial period Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.
unicast alias Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicast-
alias command to request the content from the origin streaming server.
universal time coordinates An SG appliance must know the current UTC time. By default, the appliance
(UTC) attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.
URL rewrite rules Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.
WCCP Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.
98
Appendix A: Glossary
Web FTP Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for
the OCS (if the content is not already cached), and then translates the FTP response
with the file contents into an HTTP response for the client.
Websense log type A Blue Coat proprietary log type that is compatible with the Websense reporter tool.
99
Volume 7: Managing Content
100
Index
Numerics D
3rd party data trickling, about 52
configuring 28 document
specifying a time period 33 conventions 7
specifying time period 33 Dynamic Categorization
about 12
A
access logging, ICAP 75 F
FTP, content scanning 48
B
Blue Coat SG H
ICAP service configuration 56 headers
Blue Coat Web Filter request modification 49
configuring 14 response modification 48
specifying a time period 16 HTTP, scanning HTTP objects 48
update time period 16 HTTPS, content scanning 48
C I
content filtering ICAP
3rd party configuring Blue Coat SG for 56
configuring 28 data trickling 52
3rd party, automatic download 33 failover, about 55
Blue Coat Web Filter feedback, configuring 61
configuring 14 health checks, managing 59
example of category= 35 installing server 56
expired database, using 40 ISTags 51
expired license, downloading a database with 40 patience pages, about 51
IWF patience text, customizing 62
automatic download 26 policy examples 67
configuring 24 replacing the server 75
local database request modification, about 49
configuring 20 response modification, about 48
policy with vendor categories 37 sense settings 51
provider, selecting 19 service, creating 56
SmartFilter IWF
configuring 30 configuring 24
Websense on-box custom time frame update 26
configuring 31 scheduling download 26
content scanning
ICAP service 56 L
policy for 48 local database
configuring 20
101
Volume 7: Managing Content
P S
patience pages, about 51 SmartFilter
policy configuring 30
content scanning 48
example, limit access to certain Web sites 38 V
example, limit access to specified time of day 38 virus scanning
vendor categories, using with 37 advanced configurations 74
managing 74
R replacing the ICAP server 75
request modification, about 49
response modification, about 48 W
Websense on-box
configuring 31
102
Blue Coat® Systems
SG Appliance
Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
ii
Contents
Contact Information
iii
Volume 8: Access Logging
Appendix A: Glossary
Index
iv
Chapter 1: About Access Logging
Access logging allows you to track Web usage for the entire network or specific
information on user or department usage patterns. These logs and reports can be made
available in real-time or on a scheduled basis.
Note: Event logging is not the same as access logging. Event logging allows you to
specify the types of system events logged, the size of the event log, and to configure
Syslog monitoring.
Overview
SGOS can create access logs for the traffic flowing through the system; in fact, each
protocol can create an access log record at the end of each transaction for that protocol
(such as for each HTTP request).
Note: The only data that can be logged in an access log on the SG appliance are the
access-log fields and the CPL fields (found in Appendix A: "Access Log Formats").
These log records can be directed to one or more log facilities, which associates the logs
with their configured log formats, upload schedules, and other customizable
components. In addition, access logs can be encrypted and digitally signed prior to
upload.
Data stored in log facilities can be automatically uploaded to a remote location for
analysis and archive purposes. The uploads can take placing using HTTP, FTP, or one
of several proprietary protocols. Once uploaded, reporting tools such as Blue Coat
Reporter can be used to analyze the log files. For information on using Blue Coat
Reporter, refer to the Blue Coat Reporter Configuration and Management Guide.
Understanding Facilities
A log facility is a separate log that contains a single logical file and supports a single log
format. The facility contains the file’s configuration and upload schedule information
as well as other configurable information such as how often to rotate (switch to a new
log) the logs at the destination, any passwords needed, and the point at which the
facility can be uploaded.
Multiple access log facilities are supported, although each access log supports a single
log format. You can log a single transaction to multiple log facilities through a global
configuration setting for the protocol that can be modified on a per-transaction basis
via policy.
5
Volume 8: Access Logging
6
Chapter 1: About Access Logging
SGOS can create access logs with any one of a number of log formats, and you can create
additional types using custom or ELFF format strings. The log types supported are:
❐ NCSA common log format
❐ SQUID-compatible format
❐ ELFF (W3C Extended Log File Format)
❐ Custom, using the strings you enter
❐ SmartReporter, an ELFF log format compatible with the SmartFilter Reporter tool
❐ SurfControl, a log format compatible with the SurfControl Reporter tool
❐ Websense, a log format compatible with the Websense Reporter tool
The log facilities, each containing a single logical file and supporting a single log format,
are managed by policy (created through VPM or CPL), which specifies the destination log
format and log file.
7
Volume 8: Access Logging
Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Conventions Definition
Courier font Command line text that appears on your administrator workstation.
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.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
8
Chapter 2: Creating and Editing Log Formats
You should first decide what protocols and log formats you want to use, the logging
policy, and the upload schedule. Then you can do the following:
❐ Associate a log format with the log facility.
❐ Associate a log facility with a protocol and/or create policies for protocol
association and to manage the access logs and generate entries in them (if you do
both, policy takes precedence).
❐ Determine the upload parameters for the log facility.
The Format tab allows you to create a format to use for your log facilities. Several log
formats ship with the SGOS software, and they might be sufficient for your needs. If the
formats that exist do not meet your needs, you can use the Format tab to create a
custom or ELFF format and specify the string and other qualifiers used.
Several log formats already exist. For a description of each value in the log, see
Appendix A: "Access Log Formats" on page 55.
❐ cifs: This is an ELFF format with the custom strings of
date time c-ip r-ip r-port x-cifs-method x-cifs-server x-cifs-share
x-cifs-path x-cifs-orig-path x-cifs-client-bytes-read x-cifs-server-
bytes-read x-cifs-bytes-written s-action cs-username cs-auth-group
s-ip
❐ mapi: This is an ELFF format with the custom strings of
date time c-ip c-port r-ip r-port x-mapi-user x-mapi-method cs-bytes
sr-bytes rs-bytes sc-bytes x-mapi-cs-rpc-count x-mapi-sr-rpc-count
x-mapi-rs-rpc-count x-mapi-sc-rpc-count s-action cs-username cs-
auth-group s-ip
❐ im (Instant Messaging): This is an ELFF format with the custom strings of:
date time c-ip cs-username cs-auth-group cs-protocol x-im-method x-
im-user-id x-im-user-name x-im-user-state x-im-client-info x-im-
buddy-id x-im-buddy-name x-im-buddy-state x-im-chat-room-id x-im-
chat-room-type x-im-chat-room-members x-im-message-text x-im-
message-size x-im-message-route x-im-message-type x-im-file-path x-
im-file-size s-action
❐ main: This is an ELFF format with custom strings of:
date time time-taken c-ip sc-status s-action sc-bytes cs-bytes cs-
method cs-uri-scheme cs-host cs-uri-port cs-uri-path cs-uri-query
cs-username cs-auth-group s-hierarchy s-supplier-name rs(Content-
Type) cs(User-Agent) sc-filter-result cs-category x-virus-id s-ip s-
sitename
❐ ncsa: This is a reserved format that cannot be edited. The NCSA/Common format
contains the following strings:
remotehost rfc931 authuser [date] “request” status bytes
The ELFF/custom access log format strings that represent the strings above are:
$(c-ip) - $(cs-username) $(localtime) $(cs-request-line) $(sc-
status) $(sc-bytes)
9
Volume 8: Access Logging
10
Chapter 2: Creating and Editing Log Formats
Note: If you had previously created formats with the name smartreporter or surfcontrolv5
and you upgrade the device, those formats are changed to smartreporter_user or
surfcontrolv5_user. If you already have a log format named smartreporter_user or
surfcontrolv5_user, then the names become smartreporter_user1 or surfcontrolv5_user1.
This naming protocol continues (_user2, _user3...) as necessary. The logs associated with
these formats are automatically associated with the new format name.
2. Click New (or highlight a format and click Edit). The Create Format dialog displays. If
you select an unconfigurable format, you receive an error message.
11
Volume 8: Access Logging
3a
3b
3c
3d
d. Click Test Format to test whether the format-string syntax is correct. A line
displays below the field that indicates that testing is in progress and then
gives a result, such as Format is valid.
e. From the Multiple-valued header policy drop-down list, select a header to log:
Log last header, log first header, log all headers. This allows you to determine
what happens with HTTP-headers that have multiple headers.
f. Click OK.
4. Click Apply to commit the changes to the SG appliance.
12
Chapter 2: Creating and Editing Log Formats
13
Volume 8: Access Logging
14
Chapter 3: Creating and Editing An Access Log Facility
You can use existing log facilities and modify them for your needs. You can also create
new log facilities for special circumstances, such as associating the SurfControl log
format with a log facility. To create new log facilities, continue with the next section. To
edit an existing log facility, skip to “Configuring Global Settings” on page 18.
Note: Several log facilities have already been created. Before creating a new one, check
the existing ones to see if they fit your needs. If you want to use a custom log format
with the new log facility, you must create the log format before associating it with a log
(see Chapter 2: "Creating and Editing Log Formats" on page 9).
3a
3b
3c
4a
4b
15
Volume 8: Access Logging
a. The maximum size for each remote log file (the file on the upload server)
defaults to 0, meaning that all data is sent to the same log file. If you set a
maximum size, a new log file opens when the file reaches that size. This
setting is valid for both periodic and continuous uploads.
b. Specify a size that triggers an early upload—the maximum upload size varies
depending on the size of the appliance disks (the maximum allowed upload
threshold appears below this field).
5. Click OK.
Note: If you change the log format of a log, remember that ELFF formats require an ELFF
header in the log (the list of fields being logged are mentioned in the header) and that
non-ELFF formats do not require this header.
The format of data written to the log changes as soon as the format change is applied; for
best practices, do a log upload before the format change and immediately after (to
minimize the number of log lines in a file with mixed log formats).
Upload the log facility before you switch the format.
2a
2b
2c
3a
3b
16
Chapter 3: Creating and Editing An Access Log Facility
Note: If you have a policy that defines protocol and log association, that policy overrides
any settings you make here.
The following list shows the protocols supported and the default log facilities assigned to
them, if any:
FTP main
HTTP main
HTTPS-Reverse-Proxy main (Set to the same log facility that HTTP is using upon
upgrade.)
HTTPS-Forward-Proxy ssl (If the facility for HTTP, TCP, or SOCKS is set before
upgrade.)
ICP none
Instant Messaging im
MAPI mapi
17
Volume 8: Access Logging
RealMedia/QuickTime streaming
SOCKS none
SSL ssl (If the facility for HTTP, TCP or SOCKS is set before
upgrade.)
Telnet main
Note: To disable access logging for a particular protocol, you must either disable the
default logging policy for that protocol (see “Disabling Access Logging for a Particular
Protocol” on page 18) or modify the access logging policy in VPM (refer to Volume 6: The
Visual Policy Manager and Advanced Policy Tasks).
4. Click OK.
18
Chapter 3: Creating and Editing An Access Log Facility
2a
2b
2c
19
Volume 8: Access Logging
20
Chapter 4: Configuring the Upload Client
Note: You must have a socket server to use the Custom client.
The general options you enter in the Upload Client tab affect all clients. Specific options
that affect individual clients are discussed in the FTP client, HTTP client, Custom client,
or Websense client panes or the access-log ftp-client, https-client, custom-
client, or websense-client CLI commands.
Only one client can be used at any one time. All four can be configured, but only the
selected client is used.
The SGOS software provides access logging with two types of uploads to a remote
server:
❐ continuous uploading, where the device continuously streams new access log
entries from the device memory to a remote server.
❐ scheduled (periodic) uploading, where the device transmits log entries on a
scheduled basis. See Chapter 5: "Configuring the Upload Schedule" for more
information.
The SGOS software allows you to upload either compressed access logs or plain-text
access logs. The device uses the gzip format to compress access logs. Gzip-compressed
files allow more log entries to be stored in the device. Advantages of using file
compression include:
❐ Reduces the time and resources used to produce a log file because fewer disk
writes are required for each megabyte of log-entry text.
❐ Uses less bandwidth when the device sends access logs to an upload server.
❐ Requires less disk space.
Compressed log files have the extension .log.gz. Text log files have the
extension .log.
Note: You cannot upload gzip access-log files for the Websense client.
21
Volume 8: Access Logging
For greater security, you can configure the SGOS software to:
❐ encrypt the access log
❐ sign the access log
Note: The encryption feature is not available for custom or Websense clients.
22
Chapter 4: Configuring the Upload Client
4. Enter the name of the external certificate into the External Cert Name field and paste
the certificate into the External Certificate field. Be sure to include the ----BEGIN
CERTIFICATE---- and -----END CERTIFICATE---- statements.
5. Click OK.
23
Volume 8: Access Logging
You can digitally sign your access log files with or without encryption. If the log is both
signed and encrypted, the signing operation is done first, meaning that the signature is
calculated on the unencrypted version of the file. You must decrypt the log file before
verifying the file. Attempting to verify an encrypted file fails.
When you create a signing keyring (which must be done before you enable digital
signing), keep in mind the following:
❐ The keyring must include an external certificate. (An external certificate is one for
which the SG appliance does not have the private key.).
❐ The certificate purpose must be set for smime signing. If the certificate purpose is set
to anything else, you cannot use the certificate for signing.
❐ Add the %c parameter in the filenames format string to identify the keyring used for
signing. If encryption is enabled along with signing, the %c parameter expands to
keyringName_Certname.
Note: The signing feature is not available for custom or Websense clients.
For information about verifying a log, see “Verifying a Digital Signature” on page 26.
2
3b
3a
2. From the Log drop-down list, select the log facility to configure. The facility must exist
before it displays in this list.
3. Select and configure the client type:
a. From the Client type drop-down list, select the upload client to use. Only one
client can be configured for each log facility.
b. Click Settings to customize the upload client.
For information on customizing the clients, skip to “Editing the FTP Client” on
page 27, “Editing the HTTP Client” on page 28, “Editing the Custom Client” on
page 29, “Editing the Custom SurfControl Client” on page 30, or “Editing the
Websense Client” on page 30.
24
Chapter 4: Configuring the Upload Client
For information about testing the upload client, see Chapter 4: "Configuring the
Upload Client".
4. Configure Transmission Parameters, if applicable:
a. (Optional) To use an external certificate to encrypt the uploaded log facility,
select an external certificate from the Encryption Certificate drop-down list.
You must first import the external certificate to the SG appliance (see
“Importing an External Certificate” on page 22).
The encryption option is not available for Websense or Custom clients.
b. (Optional) To enable the digital signature of the uploaded access log, select a
keyring from the Keyring Signing drop-down list. The signing keyring, with a
certificate set to smime, must already exist. A certificate set to any other
purpose cannot be used for digital signatures.
The digital signing option is not available for Websense or Custom clients.
c. Select one of the Save the log file as radio buttons to determine whether the
access log that is uploaded is compressed (gzip file, the default) or not (text
file).
Note: If you are configuring a SurfControl Custom client, select the text file radio
button.
If you chose text file, you can change the Send partial buffer after n seconds field to
the time you need (30 seconds is the default).
This field configures the maximum time between text log packets, meaning that it
forces a text upload after the specified length of time even if the internal log buffer
is not full. If the buffer fills up before the time specified in this setting, the text
uploads right away, and is not affected by this maximum setting.
Note: If you chose gzip file, the Send partial buffer after n seconds field is not
configurable. Also, this setting is only valid for continuous uploading (see
Chapter 5: "Configuring the Upload Schedule" for information about
continuous uploading).
d. (Optional) To manage the bandwidth for this log facility, select a bandwidth
class from the Bandwidth Class drop-down list.
The default setting is none, which means that bandwidth management is disabled
for this log facility by default.
Note: Before you can manage the bandwidth for this log facility, you must first
create a bandwidth-management class. It is the log facility that is bandwidth-
managed—the upload client type does not affect this setting. Refer to Volume 5:
Advanced Networking for information about enabling bandwidth management and
creating and configuring the bandwidth class.
Less bandwidth slows down the upload, while more could flood the network.
25
Volume 8: Access Logging
To disable an upload:
1. Select Configuration > Access Logging > Logs > Upload Client.
2. Select the log facility for which you want to disable an upload from the Log drop-
down menu.
3. Select NONE from the Client type drop-down menu.
cacrt The CA certificate used to issue the certificate in the signature file.
filename.sig The file containing the digital signature of the log file.
filename.log The log file generated after decryption. If the access log is a gzip file, it
contains a .gz extension.
26
Chapter 4: Configuring the Upload Client
4a 4b
4c
4d
4e
5
6
7
8
3. Select the primary or alternate FTP server to configure from the Settings for drop-
down list.
4. Fill in the server fields, as appropriate:
a. Host: The name of the upload client host. If the Use secure connections (SSL)
checkbox is selected, the hostname must match the hostname in the certificate
presented by the server.
b. Port: The default is 21; it can be changed.
c. Path: The directory path where the access log is uploaded on the server.
d. Username: This is the username that is known on the host you are
configuring.
e. Change Password: Change the password on the FTP; the Change Password
dialog displays; enter and confirm the new password; click OK.
5. Filename: The Filename field is comprised of text and/or specifiers. The default
filename includes specifiers and text that indicate the log name (%f), name of the
external certificate used for encryption, if any (%c), the fourth parameter of the SG
appliance IP address (%l), the date and time (Month: %m, Day: %d, Hour: %H,
Minute: %M, Second: %S), and the .log or .gzip.log file extension.
Note: Be cautious if you change the Filename field. If an ongoing series of access logs
files are produced and you do not have time-specifiers in this field, each access log file
produced overwrites the old file. Also, if you use more than one external certificate to
encrypt logs, include the %c specifier in the Filename field to keep track of which
external certificate was used to encrypt the uploaded log file.
6. Secure Connections: If you use FTPS, select the Use secure connections (SSL)
checkbox. The remote FTP server must support FTPS.
7. Local Time: If you want the upload to reflect the local time it was uploaded instead of
Universal Time Coordinates (UTC), select Local Time.
27
Volume 8: Access Logging
8. Use PASV: With Use PASV selected (the default), the SG appliance connects to the FTP
server. With Use PASV de-selected, the FTP server uses the PORT command to connect
to the SG appliance.
9. Click OK.
Note: To create an HTTPS client, you must also import the appropriate CA Certificate.
For information, refer to Volume 2: Proxies and Proxy Services.
4a 4b
4c
4d
4e
5
6
7
3. From the Settings for drop-down list, select the primary or alternate HTTP server to
configure.
4. Fill in the server fields, as appropriate:
a. Host: The name of the upload host. If Use secure connections (SSL) is selected,
the hostname must match the hostname in the certificate presented by the
server.
b. Port: The default is 80, but you can change it.
28
Chapter 4: Configuring the Upload Client
c. Path: The directory path where the access log facility is uploaded on the
server.
d. Username: This is the username that is known on the host you are
configuring.
e. Change Password: Change the password on the HTTP host; the Change
Password dialog displays; enter and confirm the new password and click OK.
5. Filename: The Filename field is comprised of text and/or specifiers. The default
filename includes specifiers and text that indicate the log name (%f), name of the
external certificate used for encryption, if any (%c), the fourth parameter of the SG
appliance IP address (%l), the date and time (Month: %m, Day: %d, Hour: %H,
Minute: %M, Second: %S), and the .log or .gzip.log file extension.
Note: Be cautious if you change the Filename field. If an ongoing series of access log
files are produced and you do not have time-specifiers in this field, each access log
file produced overwrites the old file. Also, if you use more than one external
certificate to encrypt logs, include the %c specifier in the Filename field to keep track
of which external certificate can decrypt the uploaded log file.
6. Local Time: If you want the upload to reflect the local time it was uploaded instead of
Universal Time Coordinate (UTC), select Local Time.
7. Use secure connections (SSL): Select this to create an HTTPS client. To create an
HTTPS client, you must also create a keypair, import or create a certificate, and, if
necessary, associate the keypair and certificate (called a keyring), with the SSL-client.
8. Click OK.
4a 4b
4c
3. From the Settings for drop-down list, select to configure the primary or alternate
custom server.
29
Volume 8: Access Logging
Note: For specific information on managing upload clients, see “Editing the Custom
Client” on page 29.
7. Click OK.
30
Chapter 4: Configuring the Upload Client
Note: You cannot upload gzip access log files with the Websense client.
3. From the Settings for drop-down list, select the primary or alternate server you want
to configure.
4. Fill in the fields as appropriate:
a. Host: Enter the hostname of the primary Websense Server.
b. Port: The default is 55805, but you can change it if the Websense Server is
using a different port.
5. Repeat for the Alternate Websense Server.
6. Click OK.
7. Click Apply to commit the changes to the SG appliance.
31
Volume 8: Access Logging
32
Chapter 5: Configuring the Upload Schedule
The Upload Schedule allows you to configure the frequency of the access logging
upload to a remote server, the time between connection attempts, the time between
keep-alive packets, the time at which the access log is uploaded, and the protocol that is
used.
You can specify either periodic uploading or continuous uploading. Both periodic and
continuous uploading can send log information from an SG appliance farm to a single
log analysis tool. This allows you to treat multiple appliances as a single entity and to
review combined information from a single log file or series of related log files.
With periodic uploading, the SGOS software transmits log entries on a scheduled basis
(for example, once daily or at specified intervals) as entries are batched, saved to disk,
and uploaded to a remote server.
Note: When you configure a log for continuous uploading, it continues to upload
until you stop it. To stop continuous uploading, switch to periodic uploading
temporarily. This is sometimes required for gzip or encrypted files, which must stop
uploading before you can view them.
With continuous uploading, the SG appliance continuously streams new access log
entries from the device memory to a remote server. Here, streaming refers to the real-
time transmission of access log information. The SGOS software transmits access log
entries using the specified client, such as FTP client. A keep-alive is sent to keep the
data connection open.
Continuous uploading allows you to view the latest logging information almost
immediately, send log information to a log analysis tool for real-time processing and
reporting, maintain the SG appliance performance by sending log information to a
remote server (avoiding disk writes), and save device disk space by saving log
information on the remote server.
If the remote server is unavailable to receive continuous upload log entries, the SGOS
software saves the log information on the device disk. When the remote server is
available again, the appliance resumes continuous uploading.
Note: If you do not need to analyze the upload entries in real time, use periodic
uploading because it is more reliable than continuous uploading.
If there is a problem configuring continuous uploading to Microsoft Internet
Information Server (IIS), use periodic uploading instead.
33
Volume 8: Access Logging
3a
3b
3c
4a 5
4b
Keepalives maintain the connection during low periods of system usage. When
no logging information is being uploaded, the SGOS software sends a keep-alive
packet to the remote server at the interval you specify, from 1 to 65535 seconds. If
you set this to 0 (zero), you effectively disable the connection during low usage
periods. The next time that access log information needs to be uploaded, the SG
appliance automatically reestablishes the connection.
4. Determine when logs are uploaded or rotated:
a. (Optional) From the Daily at drop-down list, specify the time of day to log
update (for periodic uploads) or rotate (for continuous uploads).
b. (Optional) To have the log uploaded or rotated on a daily basis, select Every
and enter the time between uploads.
5. Rotate or Upload Now:
• Continuous Upload: Log rotation helps prevent logs from growing excessively
large. Especially with a busy site, logs can grow quickly and become too big for
easy analysis. With log rotation, the SGOS software periodically creates a new log
file, and archives the older one without disturbing the current log file.
• Periodic Upload: You can upload the access logs now or you can cancel any
access-log upload currently in progress (if you are doing periodic uploads). You
can rotate the access logs now (if you are doing continuous uploads). These
actions do not affect the next scheduled upload time.
• Cancel upload (for periodic uploads) allows you to stop repeated upload attempts
if the Web server becomes unreachable while an upload is in progress. Clicking
this sets log uploading back to idle if the log is waiting to retry the upload. If the
log file is in the process of uploading, it takes time for it to take effect.
34
Chapter 5: Configuring the Upload Schedule
Note: If you have multiple access logs, each access log has its own list of objects.
❐ Show access log statistics: The statistics of an individual access log is shown.
❐ Show statistics of all logs: The statistics of all the access logs on the system are
displayed in a single list.
❐ Show last N bytes in the log: The last N bytes in the log are shown.
❐ Show last part of log every time it changes: A stream of the latest log entries is shown
on the page as they are written in the system.
❐ Show access log tail with optional refresh time: A refresh from the browser displays the
latest log entries.
❐ Show access log objects: The statistics of individual access log objects are displayed.
❐ Show all access log objects: The statistics of all access log object are displayed in a
single list.
35
Volume 8: Access Logging
2. From the Log drop-down list, select the log you want to view.
3. Click Start Tail to display the access log tail.
The SG appliance displays a maximum of 500 lines. Entries that pre-date these 500
lines are not displayed.
4. Click Stop Tail to stop the display or Clear Tail to clear the display.
Status Description
active - early upload The early upload threshold has been reached.
36
Chapter 5: Configuring the Upload Schedule
stopped The access log is full. The maximum log size has been
reached.
2. Under Status of Last Upload, check the appropriate status information displayed in
the Upload client field.
3. Check the other status information. For information about the status, see the table
below.
37
Volume 8: Access Logging
Status Description
Connect time The last time a client connection was made or attempted.
Remote filename The most recent upload filename. If an access log was encrypted,
only the encrypted access log file (the ENC file) displays.
Remote size The current size of the upload file. If an access log was encrypted,
only the encrypted access log file size (the ENC file) displays. The
private key file (the DER file) varies, but is usually about 1 Kb.
Maximum bandwidth The maximum bandwidth used in the current or last connection.
Current bandwidth The bandwidth used in the last second (available only if currently
connected).
Final result The result of the last upload attempt (success or failure). This is
available only if not connected.
38
Chapter 5: Configuring the Upload Schedule
39
Volume 8: Access Logging
2a
2b
c. To disable a particular log, click Disable logging to and select that log from the
drop-down list; to disable all access logging, click Disable all access logging.
5. Click OK; click OK again; close the VPM window and click Yes in the dialog to save
your changes.
40
Appendix A: Glossary
access log A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.
account A named entity that has purchased the appliance or the Entitlements from Blue Coat.
activation code A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.
active content stripping Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.
active content types Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user
administration access policy A policy layer that determines who can access the SG appliance to perform
administrative tasks.
administration A policy layer that determines how administrators accessing the SG appliance must
authentication policy authenticate.
Application Delivery A WAN that has been optimized for acceleration and compression by Blue Coat. This
Network (ADN) network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.
ADN backup manager Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.
ADN manager Responsible for publishing the routing table to SG Clients (and to other SG
appliances).
ADN optimize attribute Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
asx rewrite Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxy-
like support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.
audit A log that provides a record of who accessed what and how.
41
Volume 8: Access Logging
authenticate-401 attribute All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios
authenticated content Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).
authentication Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate Authority.
See also basic authentication, proxy authentication, and SSL authentication.
authentication realm Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.
bandwidth class hierarchy Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.
bandwidth management Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.
basic authentication The standard authentication for communicating with the target as identified in the
URL.
BCAAA Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.
byte-range support The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).
cache An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.
cache control Allows you to configure which content the SG appliance stores.
42
Appendix A: Glossary
cache efficiency A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.
cache hit Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.
cache miss Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .
cache object Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.
Certificate Authority (CA) A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.
child class (bandwidth gain) The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.
client consent certificates A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.
client-side transparency A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.
concentrator An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.
content filtering A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.
default boot system The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.
denial of service (DoS) A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.
43
Volume 8: Access Logging
destination objects Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.
detect protocol attribute Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
diagnostic reporting Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.
directives Commands used in installable lists to configure forwarding and SOCKS gateway.
DNS access A policy layer that determines how the SG appliance processes DNS requests.
domain name system (DNS) An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.
dynamic bypass Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.
dynamic real-time rating Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
(DRTR) dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.
early intercept attribute Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.
ELFF-compatible format A log type defined by the W3C that is general enough to be used with any protocol.
emulated certificates Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.
encrypted log A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.
event logging Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.
44
Appendix A: Glossary
explicit proxy A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.
extended log file format A variant of the common log file format, which has two additional fields at the end of
(ELFF) the line—the referer and the user agent fields.
fail open/closed Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.
forward proxy A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.
gateway A device that serves as entrance and exit into a communications network.
hardware serial number A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.
health check tests The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
• ICMP
• TCP
• SSL
• HTTP
• HTTPS
• Group
• Composite and reference to a composite result
• ICAP
• Websense
• DRTR rating service
45
Volume 8: Access Logging
health check type The kind of device or service the specific health check tests. The following types are
supported:
• Forwarding host and forwarding group
• SOCKS gateway and SOCKS gateway group
• CAP service and ICAP service group
• Websense off-box service and Websense off-box service group
• DRTR rating service
• User-defined host and a user-defined composite
heartbeat Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.
host affinity The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.
host affinity timeout The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.
inbound traffic (bandwidth Network packets flowing into the SG appliance. Inbound traffic mainly consists of
gain) the following:
• Server inbound: Packets originating at the origin content server (OCS) and sent to
the SG appliance to load a Web object.
• Client inbound: Packets originating at the client and sent to the SG appliance for
Web requests.
installable lists Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
• Creating the list using the SG text editor
• Placing the list at an accessible URL
• Downloading the directives file from the local system
integrated host timeout An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.
intervals Time period from the completion of one health check to the start of the next health
check.
IP reflection Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.
46
Appendix A: Glossary
issuer keyring The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.
licensable component (LC) (Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.
license Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.
listener The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.
live content Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.
load balancing A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.
local bypass list A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.
local policy file Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).
log facility A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.
log format The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.
log tail The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.
47
Volume 8: Access Logging
Management Console A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.
management information Defines the statistics that management systems can collect. A managed device
base (MIB) (gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.
maximum object size The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.
MIME/FILE type filtering Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.
multi-bit rate The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).
multicast Used in streaming; the ability for hundreds or thousands of users to play a single
stream.
multicast aliases Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel
multicast station Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).
multimedia content services Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.
name inputing Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server
native FTP Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).
NCSA common log format Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.
network address translation The process of translating private network (such as intranet) IP addresses to Internet
(NAT) IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.
48
Appendix A: Glossary
non-cacheable objects A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
• Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
• Password provided, requests that include a client password.
• Data in request that include additional client data.
• Not a GET request.
.nsc file Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.
NTP To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.
object (used in caching) An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.
object (used in Visual Policy An object (sometimes referred to as a condition) is any collection or combination of
Manager) entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.
object pipelining This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.
origin content server (OCS) Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.
outbound traffic (bandwidth Network packets flowing out of the SG appliance. Outbound traffic mainly consists
gain) of the following:
• Client outbound: Packets sent to the client in response to a Web request.
• Server outbound: Packets sent to an OCS or upstream proxy to request a service.
PAC (Proxy Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
AutoConfiguration) scripts port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.
packet capture (PCAP) Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.
49
Volume 8: Access Logging
parent class (bandwidth A class with at least one child. The parent class must share its bandwidth with its
gain) child classes in proportion to the minimum/maximum bandwidth values or priority
levels.
passive mode data Data connections initiated by an FTP client to an FTP server.
connections (PASV)
policies Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.
policy-based bypass list Used in policy. Allows a bypass based on the properties of the client, unlike static and
dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.
policy layer A collection of rules created using Blue Coat CPL or with the VPM.
pragma: no cache (PNC) A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).
proxy Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.
proxy service The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.
proxy service (default) The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.
public key certificate An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).
public virtual IP (VIP) Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.
50
Appendix A: Glossary
real-time streaming protocol A standard method of transferring audio and video and other time-based media over
(RTSP) Internet-technology based networks. The protocol is used to stream clips to any RTP-
based client.
reflect client IP attribute Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.
registration An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.
remote authentication dial- Authenticates user identity via passwords for network access.
in user service (RADIUS)
reverse proxy A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.
routing information protocol Designed to select the fastest route to a destination. RIP support is built into Blue
(RIP) Coat appliances.
router hops The number of jumps a packet takes when traversing the Internet.
secure shell (SSH) Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.
serial console A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.
server certificate categories The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.
server portals Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping a
set of external URLs onto a set of internal URLs.
server-side transparency The ability for the server to see client IP addresses, which enables accurate client-
access records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.
service attributes Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .
51
Volume 8: Access Logging
SG appliance A Blue Coat security and cache box that can help manage security and content on a
network.
sibling class (bandwidth A bandwidth class with the same parent class as another class.
gain)
simple network The standard operations and maintenance protocol for the Internet. It uses MIBs,
management protocol created or customized by Blue Coat, to handle (needs completion).
(SNMP)
simulated live Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.
SmartReporter log type A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.
SOCKS A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.
SOCKS proxy A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.
splash page Custom message page that displays the first time you start the client browser.
split proxy Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
• Mapi Proxy
• SSL Proxy
SQUID-compatible format A log type that was designed for cache statistics and is compatible with Blue Coat
products.
squid-native log format The Squid-compatible format contains one line for each request.
SSL authentication Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).
SSL proxy A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.
static route A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.
52
Appendix A: Glossary
statistics Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated, cache
efficiency, cached contents, and custom URLs generated by the appliance for various
kinds of logs. You can also check the event viewer for every event that occurred since
the appliance booted.
stream A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.
SurfControl log type A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.
system cache The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.
time-to-live (TTL) value Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.
traffic flow Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
(bandwidth gain) that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of
these connections, traffic flows in two directions—in one direction, packets flow out
of the SG appliance (outbound traffic), and in the other direction, packets flow into
the SG (inbound traffic). Connections can come from the client or the server. Thus,
traffic can be classified into one of four types:
• Server inbound
• Server outbound
• Client inbound
• Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.
transmission control TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
protocol (TCP) in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.
transparent proxy A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.
53
Volume 8: Access Logging
trial period Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.
unicast alias Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicast-
alias command to request the content from the origin streaming server.
universal time coordinates An SG appliance must know the current UTC time. By default, the appliance
(UTC) attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.
URL rewrite rules Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.
WCCP Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.
Web FTP Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
OCS (if the content is not already cached), and then translates the FTP response with
the file contents into an HTTP response for the client.
Websense log type A Blue Coat proprietary log type that is compatible with the Websense reporter tool.
54
Appendix A: Access Log Formats
The SG appliance can create access logs in one of the following formats:
❐ “Custom or W3C ELFF Format”
❐ “SQUID-Compatible Format” on page 58
❐ “NCSA Common Access Log Format” on page 59
ELFF is a log format defined by the W3C that contains information about Windows
Media and RealProxy logs.
The SG appliance can create access logs with any one of six formats. Four of the six are
reserved formats and cannot be configured. However, you can create additional logs
using custom or ELFF format strings.
When using an ELFF or custom format, a blank field is represented by a dash character.
When using the SQUID or NCSA log format, a blank field is represented according to
the standard of the format.
prefix (header) Describes a header data field. The valid prefixes are:
ELFF formats are created by selecting a corresponding custom log format using the
table below. Unlike the Blue Coat custom format, ELFF does not support character
strings and require a space between fields.
Selecting the ELFF format does the following:
❐ Puts one or more W3C headers into the log file. Each header contains the following
lines:
#Software: SGOS x.x.x
#Version: 1.0
#Date: 2002-06-06 12:12:34
#Fields: date time cs-ip…
55
Volume 8: Access Logging
❐ Changes all spaces within fields to + or %20. The ELFF standard requires that spaces
only be present between fields.
ELFF formats are described in Table B-2.
Table B-2. Blue Coat Custom Format and Extended Log File Format
Blue Coat Custom Extended Log File Description
Format Format
space character N/A Multiple consecutive spaces are compressed to a
single space.
% - Denotes an expansion field.
%% - Denotes '%' character.
%a c-ip IP address of the client
%b sc-bytes Number of bytes sent from appliance to client
%c rs(Content-Type) Response header: Content-Type
%d s-supplier-name Hostname of the upstream host (not available for a
cache hit)
%e time-taken Time taken (in milliseconds) to process the request
%f sc-filter-category Content filtering category of the request URL
%g timestamp Unix type timestamp
%h c-dns Hostname of the client (uses the client's IP address to
avoid reverse DNS)
%i cs-uri The 'log' URL.
%j - [Not used.]
%k - [Not used.]
%l x-bluecoat-special- Resolves to an empty string
empty
%m cs-method Request method used from client to appliance
%n - [Not used.]
%o - [Not used.]
%p r-port Port from the outbound server URL
%q - [Not used.]
%r cs-request-line First line of the client's request
%s sc-status Protocol status code from appliance to client
%t gmttime GMT date and time of the user request in format:
[DD/MM/YYYY:hh:mm:ss GMT]
%u cs-user Qualified username for NTLM. Relative username
for other protocols
%v cs-host Hostname from the client's request URL. If URL
rewrite policies are used, this field's value is derived
from the 'log' URL
%w s-action What type of action did the Appliance take to
process this request.
%x date GMT Date in YYYY-MM-DD format
%y time GMT time in HH:MM:SS format
%z s-icap-status ICAP response status
56
Appendix A: Access Log Formats
Table B-2. Blue Coat Custom Format and Extended Log File Format (Continued)
Blue Coat Custom Extended Log File Description
Format Format
%A cs(User-Agent) Request header: User-Agent
%B cs-bytes Number of bytes sent from client to appliance
%C cs(Cookie) Request header: Cookie
%D s-supplier-ip IP address used to contact the upstream host (not
available for a cache hit)
%E - [Not used.]
%F - [Not used.]
%G - [Not used.]
%H s-hierarchy How and where the object was retrieved in the cache
hierarchy.
%I s-ip IP address of the appliance on which the client
established its connection
%J - [Not used.]
%K - [Not used.]
%L localtime Local date and time of the user request in format:
[DD/MMM/YYYY:hh:mm:ss +nnnn]
%M - [Not used.]
%N s-computername Configured name of the appliance
%O - [Not used.]
%P s-port Port of the appliance on which the client established
its connection
%Q cs-uri-query Query from the 'log' URL.
%R cs(Referer) Request header: Referer
%S s-sitename The service type used to process the transaction
%T duration Time taken (in seconds) to process the request
%U cs-uri-path Path from the 'log' URL. Does not include query.
%V cs-version Protocol and version from the client's request, e.g.
HTTP/1.1
%W sc-filter-result Content filtering result: Denied, Proxied or Observed
%X cs(X-Forwarded- Request header: X-Forwarded-For
For)
%Y - [Not used.]
%Z s-icap-info ICAP response information
57
Volume 8: Access Logging
The Blue Coat custom format allows any combination of characters and format fields.
Multiple spaces are compressed to a single space in the actual access log. You can also
enter a string, such as My default is %d. The SG appliance goes through such strings
and finds the relevant information. In this case, that information is %d.
SQUID-Compatible Format
The SQUID-compatible format contains one line for each request. For SQUID-1.1, the
format is:
time elapsed remotehost code/status bytes method URL rfc931
peerstatus/peerhost type
For SQUID-2, the columns stay the same, though the content within might change a little.
Value Description
ACCELERATED (SOCKS only) The request was handed to the appropriate protocol
agent for handling.
ALLOWED An FTP method (other than the data transfer method) is successful.
LICENSE_EXPIRED (SOCKS only) The request could not be handled because the associated
license has expired.
TCP_AUTH_HIT The requested object requires upstream authentication, and was served
from the cache.
TCP_AUTH_MISS The requested object requires upstream authentication, and was not
served from the cache. This is part of CAD (Cached Authenticated
Data).
TCP_CLIENT_REFRE The client forces a revalidation with the origin server with a Pragma:
SH no-cache. If the server returns 304 Not Modified, this appears in
the Statistics:Efficiency file as In Cache, verified
Fresh.
TCP_ERR_MISS An error occurred while retrieving the object from the origin server.
58
Appendix A: Access Log Formats
Value Description
TCP_NC_MISS The object returned from the origin server was non-cacheable.
TCP_PARTIAL_MISS The object is in the cache, but retrieval from the origin server is in
progress.
TCP_REFRESH_HIT A GIMS request to the server was forced and the response was 304
Not Modified, this appears in the Statistics:Efficiency file as
In Cache, verified Fresh.
TCP_REFRESH_MISS A GIMS request to the server was forced and new content was
returned.
TCP_RESCAN_HIT The requested object was found in the cache but was rescanned
because the virus-scanner-tag-id in the object was different from the
current scanner tag.
TCP_SWAPFAIL The object was believed to be in the cache, but could not be accessed.
TCP_TUNNELED The CONNECT method was used to tunnel this request (generally
proxied HTTPS).
UDP_HIT A valid copy of the requested object was in the cache. This value is also
used with ICP queries.
UDP_MISS The requested object was not in the cache. This value is also used with
ICP queries.
UDP_MISS_NOFETCH An ICP request was made to this cache for an object not in the cache.
The requestor was informed that it could not use this cache as a parent
to retrieve the object. (This is not supported at this time.)
UDP_OBJ An ICP request was made to this cache for an object that was in cache,
and the object was returned through UDP. (This is not supported at this
time. This functionality is deprecated in the current ICP specification.)
59
Volume 8: Access Logging
rfc931 The remote log name of the user. This field is always —.
Specifier Description
%% Percent sign.
%c The certificate name used for encrypting the log file (expands to nothing in non-
encrypted case).
60
Appendix A: Access Log Formats
%U Week of year as decimal number, with Sunday as first day of week (00 – 53).
%W Week of year as decimal number, with Monday as first day of week (00 – 53).
61
Volume 8: Access Logging
62
Appendix A: Access Log Formats
63
Volume 8: Access Logging
64
Appendix A: Access Log Formats
65
Volume 8: Access Logging
Category: dns
x-dns-cs-transport dns.client_transport The transport protocol used by the
client connection in a DNS query
x-dns-cs-address dns.request.address The address queried in a reverse
DNS lookup
x-dns-cs-dns dns.request.name The hostname queried in a forward
DNS lookup
x-dns-cs-opcode dns.request.opcode The DNS OPCODE used in the
DNS query
x-dns-cs-qtype dns.request.type The DNS QTYPE used in the DNS
query
x-dns-cs-qclass dns.request.class The DNS QCLASS used in the DNS
query
x-dns-rs-rcode dns.response.code The DNS RCODE in the response
from upstream
x-dns-rs-a-records dns.response.a The DNS A RRs in the response
from upstream
x-dns-rs-cname- dns.response.cname The DNS CNAME RRs in the
records response from upstream
x-dns-rs-ptr- dns.response.ptr The DNS PTR RRs in the response
records from upstream
66
Appendix A: Access Log Formats
Category: mapi
x-mapi-method The method associated with the
MAPI request
x-mapi-user-dn The distinguished name of the user
negotiated by MAPI
67
Volume 8: Access Logging
Category: p2p
x-p2p-client-bytes Number of bytes from client
x-p2p-client-info The peer-to-peer client information
x-p2p-client-type p2p.client The peer-to-peer client type
x-p2p-peer-bytes Number of bytes from peer
Category: packets
c-pkts-lost-client Number of packets lost during
transmission from server to client
and not recovered at the client layer
via error correction or at the
network layer via UDP resends.
c-pkts-lost-cont- Maximum number of continuously
net lost packets on the network layer
during transmission from server to
client
c-pkts-lost-net Number of packets lost on the
network layer
c-pkts-received Number of packets from the server
(s-pkts-sent) that are received
correctly by the client on the first
try
c-pkts-recovered- Number of packets repaired and
ECC recovered on the client layer
c-pkts-recovered- Number of packets recovered
resent because they were resent via UDP.
c-quality The percentage of packets that were
received by the client, indicating
the quality of the stream
68
Appendix A: Access Log Formats
Category: req_rsp_line
cs-method method %m Request method used from client to
appliance
x-cs-http-method http.method HTTP request method used from
client to appliance. Empty for non-
HTTP transactions
cs-protocol client.protocol Protocol used in the client's request
cs-request-line http.request_line %r First line of the client's request
x-cs-raw-headers- request.raw_headers.count Total number of 'raw' headers in the
count request
x-cs-raw-headers- request.raw_headers. Total length of 'raw' headers in the
length length request
cs-version request.version %V Protocol and version from the
client's request, e.g. HTTP/1.1
x-bluecoat-proxy- proxy.via_http_version Default HTTP protocol version of
via-http-version the appliance without protocol
decoration (e.g. 1.1 for HTTP/1.1)
x-bluecoat- redirect.location Redirect location URL specified by
redirect-location a redirect CPL action
rs-response-line First line (a.k.a. status line) of the
response from an upstream host to
the appliance
rs-status response.code Protocol status code of the response
from an upstream host to the
appliance
rs-version response.version Protocol and version of the
response from an upstream host to
the appliance, e.g. HTTP/1.1
sc-status %s Protocol status code from appliance
to client
x-bluecoat-ssl- ssl_failure_reason Upstream SSL negotiation failure
failure-reason reason
x-cs-http-version http.request.version HTTP protocol version of request
from the client. Does not include
protocol qualifier (e.g. 1.1 for
HTTP/1.1)
x-cs-socks-ip socks.destination_address Destination IP address of a proxied
SOCKS request
x-cs-socks-port socks.destination_port Destination port of a proxied
SOCKS request
x-cs-socks- socks.method Method of a proxied SOCKS
method request
69
Volume 8: Access Logging
Category: special_token
x-bluecoat- amp The ampersand character
special-amp
x-bluecoat- apos The apostrophe character (a.k.a.
special-apos single quote)
x-bluecoat- cr Resolves to the carriage return
special-cr character
x-bluecoat- crlf Resolves to a carriage return/line
special-crlf feed sequence
x-bluecoat- empty %l Resolves to an empty string
special-empty
x-bluecoat- esc Resolves to the escape character
special-esc (ASCII HEX 1B)
x-bluecoat- gt The greater-than character
special-gt
x-bluecoat- lf The line feed character
special-lf
x-bluecoat- lt The less-than character
special-lt
x-bluecoat- quot The double quote character
special-quot
x-bluecoat- slash The forward slash character
special-slash
70
Appendix A: Access Log Formats
Category: ssl
x-rs-certificate- server.certificate.hostname Hostname from the server's SSL
hostname certificate
x-rs-certificate- All content categories of the server's
hostname- SSL certificate's hostname
categories
x-rs-certificate- All content categories of the server's
hostname- SSL certificate's hostname that are
categories-policy defined by CPL.
x-rs-certificate- All content categories of the server's
hostname- SSL certificate's hostname that are
categories-local defined by a Local database.
x-rs-certificate- All content categories of the server's
hostname- SSL certificate's hostname that are
categories- defined by Blue Coat Web Filter.
bluecoat
x-rs-certificate- All content categories of the server's
hostname- SSL certificate's hostname that are
categories- defined by the current 3rd-party
provider provider.
x-rs-certificate- All content categories of the server's
hostname- SSL certificate's hostname, qualified
categories- by the provider of the category.
qualified
x-rs-certificate- server.certificate.hostname. Single content category of the
hostname- category server's SSL certificate's hostname
category
x-rs-certificate- Date from which the certificate
valid-from presented by the server is valid
x-rs-certificate- Date until which the certificate
valid-to presented by the server is valid
x-rs-certificate- Serial number of the certificate
serial-number presented by the server
x-rs-certificate- Issuer of the certificate presented by
issuer the server
x-rs-certificate- Signature algorithm in the
signature- certificate presented by the server
algorithm
x-rs-certificate- Public key algorithm in the
pubkey-algorithm certificate presented by the server
x-rs-certificate- Version of the certificate presented
version by the server
x-rs-certificate- server.certificate.subject Subject of the certificate presented
subject by the server
x-cs-certificate- client.certificate.common_ Common name in the client
common-name name certificate
71
Volume 8: Access Logging
Category: status
x-bluecoat- release.id The release ID of the ProxySG
release-id operating system
x-bluecoat- release.version The release version of the ProxySG
release-version operating system
cs-categories All content categories of the request
URL
cs-categories- All content categories of the request
external URL that are defined by an external
service.
cs-categories- All content categories of the request
policy URL that are defined by CPL.
cs-categories-local All content categories of the request
URL that are defined by a Local
database.
cs-categories- All content categories of the request
bluecoat URL that are defined by Blue Coat
Web Filter.
cs-categories- All content categories of the request
provider URL that are defined by the current
3rd-party provider.
cs-categories- All content categories of the request
qualified URL, qualified by the provider of
the category.
72
Appendix A: Access Log Formats
73
Volume 8: Access Logging
74
Appendix A: Access Log Formats
75
Volume 8: Access Logging
Category: streaming
audiocodec Audio codec used in stream.
avgbandwidth Average bandwidth (in bits per
second) at which the client was
connected to the server.
channelURL URL to the .nsc file
c-buffercount Number of times the client buffered
while playing the stream.
c-bytes An MMS-only value of the total
number of bytes delivered to the
client.
c-cpu Client computer CPU type.
c-hostexe Host application
c-hostexever Host application version number
c-os Client computer operating system
c-osversion Client computer operating system
version number
c-playerid Globally unique identifier (GUID)
of the player
c-playerlanguage Client language-country code
c-playerversion Version number of the player
c-rate Mode of Windows Media Player
when the last command event was
sent
c-starttime Timestamp (in seconds) of the
stream when an entry is generated
in the log file.
c-status Codes that describe client status
76
Appendix A: Access Log Formats
Category: time
connect-time Total ms required to connect to the
origin server
date date.utc %x GMT Date in YYYY-MM-DD format
dnslookup-time Total ms cache required to perform
the DNS lookup
duration %T Time taken (in seconds) to process
the request
gmttime %t GMT date and time of the user
request in format: [DD/MM/
YYYY:hh:mm:ss GMT]
77
Volume 8: Access Logging
78
Appendix A: Access Log Formats
Category: url
cs-host %v Hostname from the client's request
URL. If URL rewrite policies are
used, this field's value is derived
from the 'log' URL
cs-uri log_url %i The 'log' URL.
cs-uri-address log_url.address IP address from the 'log' URL. DNS
is used if URL uses a hostname.
cs-uri-extension log_url.extension Document extension from the 'log'
URL.
cs-uri-host log_url.host Hostname from the 'log' URL.
cs-uri-hostname log_url.hostname Hostname from the 'log' URL.
RDNS is used if the URL uses an IP
address.
cs-uri-path log_url.path %U Path from the 'log' URL. Does not
include query.
cs-uri-pathquery log_url.pathquery Path and query from the 'log' URL.
cs-uri-port log_url.port Port from the 'log' URL.
cs-uri-query log_url.query %Q Query from the 'log' URL.
cs-uri-scheme log_url.scheme Scheme from the 'log' URL.
79
Volume 8: Access Logging
80
Appendix A: Access Log Formats
81
Volume 8: Access Logging
Category: user
cs-auth-group group One group that an authenticated
user belongs to. If a user belongs to
multiple groups, the group logged
is determined by the Group Log
Order configuration specified in
VPM. If Group Log Order is not
specified, an arbitrary group is
logged. Note that only groups
referenced by policy are considered.
cs-auth-groups groups List of groups that an authenticated
user belongs to. Note that only
groups referenced by policy are
included.
cs-auth-type Client-side: authentication type
(basic, ntlm, etc.)
cs-realm realm Authentication realm that the user
was challenged in.
cs-user %u Qualified username for NTLM.
Relative username for other
protocols
cs-userdn user Full username of a client
authenticated to the proxy (fully
distinguished)
82
Appendix A: Access Log Formats
83
Volume 8: Access Logging
Category: ci_request_header
cs(Accept) request.header.Accept Request header: Accept
cs(Accept)-length request.header.Accept. Length of HTTP request header:
length Accept
cs(Accept)-count request.header.Accept. Number of HTTP request header:
count Accept
cs(Accept- request.header.Accept- Request header: Accept-Charset
Charset) Charset
cs(Accept- request.header.Accept- Length of HTTP request header:
Charset)-length Charset.length Accept-Charset
cs(Accept- request.header.Accept- Number of HTTP request header:
Charset)-count Charset.count Accept-Charset
cs(Accept- request.header.Accept- Request header: Accept-Encoding
Encoding) Encoding
cs(Accept- request.header.Accept- Length of HTTP request header:
Encoding)-length Encoding.length Accept-Encoding
cs(Accept- request.header.Accept- Number of HTTP request header:
Encoding)-count Encoding.count Accept-Encoding
cs(Accept- request.header.Accept- Request header: Accept-Language
Language) Language
cs(Accept- request.header.Accept- Length of HTTP request header:
Language)-length Language.length Accept-Language
cs(Accept- request.header.Accept- Number of HTTP request header:
Language)-count Language.count Accept-Language
84
Appendix A: Access Log Formats
85
Volume 8: Access Logging
86
Appendix A: Access Log Formats
87
Volume 8: Access Logging
88
Appendix A: Access Log Formats
89
Volume 8: Access Logging
90
Appendix A: Access Log Formats
91
Volume 8: Access Logging
Category: si_response_header
rs(Accept) response.header.Accept Response header: Accept
rs(Accept- response.header.Accept- Response header: Accept-Charset
Charset) Charset
rs(Accept- response.header.Accept- Response header: Accept-Encoding
Encoding) Encoding
rs(Accept- response.header.Accept- Response header: Accept-Language
Language) Language
rs(Accept-Ranges) response.header.Accept- Response header: Accept-Ranges
Ranges
rs(Age) response.header.Age Response header: Age
rs(Allow) response.header.Allow Response header: Allow
rs(Authentication response.header. Response header: Authentication-
-Info) Authentication-Info Info
rs(Authorization) response.header. Response header: Authorization
Authorization
rs(Cache-Control) response.header.Cache- Response header: Cache-Control
Control
rs(Client-IP) response.header.Client-IP Response header: Client-IP
rs(Connection) response.header. Response header: Connection
Connection
rs(Content- response.header.Content- Response header: Content-
Disposition) Disposition Disposition
rs(Content- response.header.Content- Response header: Content-
Encoding) Encoding Encoding
rs(Content- response.header.Content- Response header: Content-
Language) Language Language
rs(Content- response.header.Content- Response header: Content-Length
Length) Length
92
Appendix A: Access Log Formats
93
Volume 8: Access Logging
94
Index
A SQUID format 10
access logging SQUID-compatible format 58
adding to log file 39 statistics
bandwidth management, setting 25 viewing 35, 38
continuous uploading 21 status statistics, viewing 37
creating/editing log formats 9 streaming format 10
custom SurfControl client, editing 30
format, creating/editing 11 tail options 36
log formats 55 testing upload 35
custom client upload behavior 19
configuring 29 upload client
port number 30 configuring 21
disabling 18 upload compression 25
ELFF upload filename, configuring 27
format, creating/editing 11 upload schedule
log formats 55 configuring overview 33
file compression, discussed 21 Websense client
filename formats 60 port number 31
FTP upload client Websense client, editing 30
editing 27 access logs
port number 27 digital signing
global settings 18 overview 23
HTTP upload client verifying 26
configuring 28
port number 28 B
instant messaging format 9 bandwidth management
log file access logging, setting for 25
creating 15
editing 16 C
log size, viewing statistics 36 common access log format 59
log tail, viewing 36 custom client
maximum log size, setting 19 configuring for access logging 29
NCSA/common format 9 custom format, creating/editing 11
NCSA/common log format
described 59 D
overriding 39 digital signing
P2P format 10 overview 23
PASV, configuring for FTP client 28 verifying 26
policy, using with 39 document, conventions 8
protocols, using with 17
remote max file size 16 E
resetting 39 ELFF
scheduled uploading 21 access log formats 55
show list of all logs 35 creating/editing 11
95
Volume 8: Access Logging
F R
filename formats, access logging 60 RealMedia, access logging, using with 17
FTP upload client, editing 27
S
H SQUID access log format 10, 58
HTTP upload client, configuring 28 SSL, log format 10
HTTP, access logging, using with 17 statistics
access logging log size 36
I access logging, status 37
instant messaging, access log format 9 access logging, viewing 35, 38
show list of all logs 35
L streaming media, access log format 10
log file SurfControl, configuring for access logging 30
creating 15
editing 16 T
log format, SSL 10 troubleshooting
show list of all logs 35
N
NCSA, common access log format 9, 59 W
W3C Extended Log File Format, see ELFF 55
P Websense
P2P, access log format 10 upload client, editing 30
Windows Media
access logging, using with 17
96
Blue Coat® Systems
SG™ Appliance
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
Contact Information
iii
Volume 9: Managing the Blue Coat SG Appliance
Restore-Defaults......................................................................................................................................... 34
Factory-Defaults......................................................................................................................................... 35
Keep-Console.............................................................................................................................................. 35
Clearing the DNS Cache .................................................................................................................................. 36
Clearing the Object Cache................................................................................................................................ 36
Clearing the Byte Cache ................................................................................................................................... 37
Troubleshooting Tip .................................................................................................................................. 37
Clearing Trend Statistics .................................................................................................................................. 37
Upgrading the SG Appliance .......................................................................................................................... 37
The SG Appliance 5.x Version Upgrade................................................................................................. 38
Troubleshooting Tip .................................................................................................................................. 40
Managing SG Appliance Systems................................................................................................................... 40
Setting the Default Boot System .............................................................................................................. 41
Locking and Unlocking SG Appliance Systems.................................................................................... 42
Replacing an SG Appliance System ........................................................................................................ 42
Deleting an SG Appliance System........................................................................................................... 43
Disk Reinitialization ......................................................................................................................................... 43
Multi-Disk SG Appliances ........................................................................................................................ 43
Single-Disk SG Appliance......................................................................................................................... 44
Deleting Objects from the SG Appliance....................................................................................................... 44
Chapter 4: Diagnostics
Diagnostic Reporting (Service Information) ................................................................................................. 46
Sending Service Information Automatically.......................................................................................... 46
Managing the Bandwidth for Service Information............................................................................... 47
Configure Service Information Settings ................................................................................................. 48
Creating and Editing Snapshot Jobs ....................................................................................................... 50
Packet Capturing (the Job Utility) .................................................................................................................. 52
PCAP File Name Format........................................................................................................................... 52
Common PCAP Filter Expressions ......................................................................................................... 52
Configuring Packet Capturing................................................................................................................. 53
Core Image Restart Options ............................................................................................................................ 57
Diagnostic Reporting (Heartbeats) ................................................................................................................. 58
Diagnostic Reporting (CPU Monitoring)....................................................................................................... 59
Chapter 5: Statistics
Selecting the Graph Scale................................................................................................................................. 61
Viewing Traffic Distribution Statistics........................................................................................................... 62
Understanding Chart Data ....................................................................................................................... 63
Refreshing the Data ................................................................................................................................... 63
About Bypassed Bytes............................................................................................................................... 63
About the Default Service Statistics ........................................................................................................ 64
Viewing Bandwidth Usage or Gain ........................................................................................................ 64
Viewing Client Byte and Server Byte Traffic Distribution .................................................................. 65
iv
Contents
Appendix A: Glossary
Index
v
Volume 9: Managing the Blue Coat SG Appliance
vi
Chapter 1: About Managing the SG Appliance
Volume 9: Managing the Blue Coat SG Appliance describes how to monitor the SG
appliance with SNMP (a brief introduction to Director is provided), event logging, or
health monitoring. It also describes common maintenance and troubleshooting tasks.
Discussed in this volume:
❐ Chapter 2: "Monitoring the SG Appliance"
❐ Chapter 3: "Maintaining the SG Appliance"
❐ Chapter 4: "Diagnostics"
❐ Chapter 5: "Statistics"
❐ Appendix A: "Glossary"
Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Conventions Definition
Courier font Command line text that appears on your administrator workstation.
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.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
7
Volume 9: Managing the Blue Coat SG Appliance
8
Chapter 2: Monitoring the SG Appliance
This chapter describes the methods you can use to monitor your SG appliances,
including event logging, SNMP, and health monitoring. A brief introduction to Director
is also provided.
This chapter contains the following sections:
❐ “Using Director to Manage SG Systems” on page 9
❐ “Monitoring the System and Disks” on page 12
❐ “Setting Up Event Logging and Notification” on page 15
❐ “Configuring SNMP” on page 20
❐ “Configuring Health Monitoring” on page 23
9
Volume 9: Managing the Blue Coat SG Appliance
Note: The Blue Coat appliance certificate is an X.509 certificate that contains the
hardware serial number of a specific SG device as the Common Name (CN) in the
subject field. Refer to the device authentication information in Volume 5: Advanced
Networking for more information about appliance certificates.
Note: Refer to the Blue Coat Director Configuration and Management Guide for more
information about configuring the shared secret. For information about appliance
certificates, refer to Volume 5: Advanced Networking.
6. Click Register.
10
Chapter 2: Monitoring the SG Appliance
Note: For information on creating and pushing a SSH keypair on Director, refer to the
Blue Coat Director Installation Guide.
Important: You must add the Director identification at the end of the client key. The
example shows the username, IP address, and MAC address of Director. “Director”
(without quotes) must be the username, allowing you access to passwords in clear
text.
11
Volume 9: Managing the Blue Coat SG Appliance
To delete a key:
SGOS#(config sshd) delete director-client-key clientID
System Summary
The device provides a variety of information on its status. The fields on the Summary tab
are described below:
❐ Disks Installed—the number of disk drives installed in the device. The Disks tab
displays the status of each drive.
❐ Memory installed—the amount of RAM installed in the device.
12
Chapter 2: Monitoring the SG Appliance
Note: The health monitoring metrics on the Statistics > Health page also show the state
of environmental sensors. See “Configuring Health Monitoring” on page 23 for more
information.
Note: This tab varies depending on the type of SG appliance that you are using.
2. Click View Sensors to see detailed sensor values; close the window when you are
finished.
13
Volume 9: Managing the Blue Coat SG Appliance
Note: The name and appearance of this tab differs, depending on the range of disks
available to the SG appliance model you use.
2. Select the disk to view or to take offline by clicking the appropriate disk icon.
3. (Optional) To take the selected disk offline, click the Take disk x offline button (where x
is the number of the disk you have selected); click OK in the Take disk offline dialog
that displays.
14
Chapter 2: Monitoring the SG Appliance
Note: You cannot view statistics about SSL accelerator cards through the CLI.
15
Volume 9: Managing the Blue Coat SG Appliance
configuration Writes severe and configuration change error messages to the event log.
policy Writes severe, configuration change, and policy event error messages to
the event log.
informational Writes severe, configuration change, policy event, and information error
messages to the event log.
2. In the Event log size field, enter the maximum size of the event log in megabytes.
3. Select either Overwrite earlier events or Stop logging new events to specify the desired
behavior when the event log reaches maximum size.
4. Click Apply.
16
Chapter 2: Monitoring the SG Appliance
Note: The SG appliance must know the host name or IP address of your SMTP mail
gateway to mail event messages to the e-mail address(es) you have entered. If you do not
have access to an SMTP gateway, you can use the Blue Coat default SMTP gateway to
send event messages directly to Blue Coat.
The Blue Coat SMTP gateway only sends mail to Blue Coat. It will not forward mail to
other domains.
2. Click New to add a new e-mail address; click OK in the Add list item dialog that
appears.
3. In the SMTP gateway name field, enter the host name of your mail server; or in the
SMTP gateway IP field, enter the IP address of your mail server.
4. (Optional) If you want to clear one of the above settings, select the radio button of the
setting you want to clear. You can clear only one setting at a time.
5. Click Apply.
17
Volume 9: Managing the Blue Coat SG Appliance
2. In the Loghost field, enter the domain name or IP address of your loghost server.
3. Select Enable Syslog.
4. Click Apply.
18
Chapter 2: Monitoring the SG Appliance
Note: If the notation includes a space, such as between the start date and the start time,
the argument in the CLI should be quoted.
19
Volume 9: Managing the Blue Coat SG Appliance
Example
SGOS# show event-log start "2004-10-22 9:00:00" end "2004-10-22
9:15:00"
2004-10-22 09:00:02+00:00UTC "Snapshot sysinfo_stats has fetched /
sysinfo-stats " 0 2D0006:96 ../Snapshot_worker.cpp:183
2004-10-22 09:05:49+00:00UTC "NTP: Periodic query of server
ntp.bluecoat.com, system clock is 0 seconds 682 ms fast compared to NTP
time. Updated system clock. " 0 90000:1 ../ntp.cpp:631
Configuring SNMP
You can view an SG appliance using a Simple Network Management Protocol (SNMP)
management station. The appliance supports MIB-2 (RFC 1213), Proxy MIB, and the
RFC2594 MIB, and can be downloaded at the following URL: https://
download.bluecoat.com/release/SGOS5/index.html (The SNMP link is in the lower
right-hand corner.).
Enabling SNMP
To view an SG appliance from an SNMP management station, you must enable and
configure SNMP support on the appliance.
20
Chapter 2: Monitoring the SG Appliance
Note: If you enable SNMP, make sure to change all three community-string passwords to
values that are difficult to guess. Use a combination of uppercase, lowercase, and numeric
characters. An easily-guessed community-string password makes it easier to gain
unauthorized access to the SG appliance and network.
21
Volume 9: Managing the Blue Coat SG Appliance
Note: The SNMP trap for CPU utilization is sent only if the CPU continues to stay up for
32 or more seconds.
Note: You cannot configure SNMP traps to go out through a particular interface. The
interface that is configured first is used until it fails and is used to identify the device.
2. In the Send traps to fields, enter the IP address(es) of the workstation(s) where traps
are to be sent.
3. To receive authorization traps, select Enable authorization traps.
4. Select Apply to commit the changes to the SG appliance.
22
Chapter 2: Monitoring the SG Appliance
23
Volume 9: Managing the Blue Coat SG Appliance
24
Chapter 2: Monitoring the SG Appliance
0 5 10 15 20 25 30 35 40 45 50 55 60
Time
Figure 2-2. Relationship between the threshold value and threshold interval
25
Volume 9: Managing the Blue Coat SG Appliance
For the license expiration metrics, the threshold interval is irrelevant and is set by default
to 0. You should set the Warning Threshold to a value that will give you ample time to
renew your license. By default, all license expiration metrics have a Warning Threshold of
30 days. By default, the Critical Threshold is configured to 0, which means that a trap is
immediately sent upon license expiration.
CPU Utilization Percentage Critical: 95%/120 seconds Measures the value of CPU 0
Warning: 80%/120 on multi-processor systems--
seconds not the average of all CPU
activity.
Interface Utilization Percentage Critical: 90%/120 seconds Measures the traffic (in and
Warning: 60%/120 out) on the interface to
seconds determine if it is
approaching the bandwidth
maximum.
26
Chapter 2: Monitoring the SG Appliance
See “About License Expiration Metrics” on page 25 for information licensing thresholds.
License Utilization Percentage Critical: 100%/0 For licenses that have user
Warning: 90%/0 limits, monitors the number
of users.
Temperature Critical:
Bus temperature High-critical
CPU temperature Warning:
High-warning
Fan Critical:
(The fan metric differs by hardware model, for Low-critical
example, CPU fan, chassis fan) Warning:
Low-warning
27
Volume 9: Managing the Blue Coat SG Appliance
Voltage Critical:
Bus Voltage Critical
CPU voltage High-critical
Power Supply voltage
Low-critical
Warning:
High-warning
Low-warning
Note: You cannot change the threshold values for metrics in the Status tab.
28
Chapter 2: Monitoring the SG Appliance
4. Click Edit to modify the threshold and notification settings. The Edit Health Monitor
Setting dialog displays. (hardware, environmental, and ADN thresholds cannot be
modified.)
5a
5b
5c
5d
29
Volume 9: Managing the Blue Coat SG Appliance
System health is determined by calculating the “aggregate” health status of the following
metrics:
❐ CPU Utilization
❐ Memory Pressure
❐ Network interface utilization
❐ Disk status (for all disks)
❐ License expiration
❐ License “user count” utilization (when applicable)
❐ ADN status
The possible health states are OK, Warning, or Critical.
Clicking the health icon displays the Statistics > Health page, which lists the current
condition of the system’s health monitoring metrics, as described in the next section.
30
Chapter 2: Monitoring the SG Appliance
Troubleshooting
If you continue to receive alerts, contact Blue Coat Technical Support. For licensing
questions, contact Blue Coat Support Services. It is helpful to obtain a packet capture for
CPU, memory pressure, and network interface issues, before calling Technical Support.
31
Volume 9: Managing the Blue Coat SG Appliance
32
Chapter 3: Maintaining the SG Appliance
This chapter describes how to maintain the SG appliance; for example, restarting the
appliance, restoring system defaults, upgrading the appliance, and reinitializing disks.
This chapter contains the following sections:
❐ “Restarting the SG Appliance” on page 33
❐ “Restoring System Defaults” on page 34
❐ “Clearing the DNS Cache” on page 36
❐ “Clearing the Object Cache” on page 36
❐ “Clearing the Byte Cache” on page 37
❐ “Clearing Trend Statistics” on page 37
❐ “Upgrading the SG Appliance” on page 37
❐ “Managing SG Appliance Systems” on page 40
❐ “Disk Reinitialization” on page 43
❐ “Deleting Objects from the SG Appliance” on page 44
Important:The default settings of the Restart option suits most systems. Changing
them without assistance from Blue Coat Systems Technical Support is not
recommended.
Note: If you change restart option settings and you want them to apply to the next SG
appliance restart, click Apply.
33
Volume 9: Managing the Blue Coat SG Appliance
2. In the Restart field, select either Software only or Hardware and software.
3. If you select the Hardware and software option, select a system from the System to run
drop-down list.
The default system is pre-selected.
4. Click Apply.
5. Click Restart now.
Restore-Defaults
Settings that are deleted when you use the restore-defaults command include:
❐ All IP addresses (these must be restored before you can access the Management
Console again).
❐ DNS server addresses (these must be restored through the CLI before you can access
the Management Console again).
❐ Installable lists.
❐ All customized configurations.
34
Chapter 3: Maintaining the SG Appliance
Factory-Defaults
All system settings are deleted when you use the restore-defaults command with the
factory-defaults option.
The only settings that are kept when you use the restore-defaults command with the
factory-defaults option are:
❐ Trial period information.
❐ The last five installed appliance systems, from which you can pick one for rebooting.
The Setup Console password is also deleted if you use restore-defaults factory-
defaults. For information on the Setup Console password, refer to Volume 4: Securing the
Blue Coat SG Appliance.
You can use the force option to restore defaults without confirmation.
Keep-Console
Settings that are retained when you use the restore-defaults command with the keep-
console option include:
35
Volume 9: Managing the Blue Coat SG Appliance
Note: The keep-console and factory-defaults options are not available through
the Management Console.
2. From the Tasks field, click Restore the configuration to defaults. If you restore the
configuration from the Management Console, most settings are lost because you
cannot use the keep-console option.
The Restore Configuration dialog appears.
3. Click OK.
36
Chapter 3: Maintaining the SG Appliance
Troubleshooting Tip
Occasionally, the Management Console might behave incorrectly because of browser
caching, particularly if the browser was used to run different versions of the Management
Console. This problem might be resolved by clearing the browser cache.
Important: Enable the auto-detect encoding feature on your browser so that it uses the
encoding specified in the console URLs. The browser does not use the auto- detect
encoding feature by default. If auto-detect encoding is not enabled, the browser ignores
the charset header and uses the native OS language encoding for its display.
37
Volume 9: Managing the Blue Coat SG Appliance
Note: At least one other system must be unlocked to do the upgrade. If all systems are
locked, or all systems except the running system are locked, the Download button in the
Management Console is disabled. Similarly, the load upgrade command in the CLI
generates an error.
2. Click Show me to connect to the Blue Coat download page, follow the instructions,
and note the URL of the SGOS upgrade for your system model. Then enter the URL in
the Download new system software from this URL field and click Download.
-or-
(Only if you previously downloaded a system image to your PC) Click Upload and
Browse to the file location, then click Install. The upload might take several minutes.
38
Chapter 3: Maintaining the SG Appliance
3. (Optional) Select the system to replace in the Replace drop-down list. If you uploaded
an image from your PC, refresh the Systems pane to see the new system image.
4. Click Restart.
The Restart system dialog displays.
39
Volume 9: Managing the Blue Coat SG Appliance
Troubleshooting Tip
If the SG appliance does not come up after rebooting and the serial port is connected to a
terminal server (terminal concentrator), try the following:
❐ Have an active session open on the terminal server, noting any traffic (characters)
being output.
❐ Unplug the terminal server from the appliance in case it is causing a problem (such as
bad cabling).
40
Chapter 3: Maintaining the SG Appliance
Example Session
SGOS> show installed-systems
SG Appliance Systems
1. Version: SGOS 4.2.1.1, Release ID: 25460
Thursday April 6 2006 08:49:55 UTC, Lock Status: Locked
Boot Status: Last boot succeeded, Last Successful Boot: Thursday
April 6 2006 17:33:19 UTC
2. Version: SGOS 4.2.1.1, Release ID: 25552 Debug
Friday April 14 2006 08:56:55 UTC, Lock Status: Unlocked
Boot Status: Last boot succeeded, Last Successful Boot: Friday April
14 2006 16:57:18 UTC
3. Version: N/A, Release ID: N/A ( EMPTY )
No Timestamp, Lock Status: Unlocked
Boot Status: Unknown, Last Successful Boot: Unknown
4. Version: N/A, Release ID: N/A ( EMPTY )
No Timestamp, Lock Status: Unlocked
Boot Status: Unknown, Last Successful Boot: Unknown
5. Version: N/A, Release ID: N/A ( EMPTY )
No Timestamp, Lock Status: Unlocked
Boot Status: Unknown, Last Successful Boot: Unknown
Default system to run on next hardware restart: 2
Default replacement being used. (oldest unlocked system)
Current running system: 2
When a new system is loaded, only the system number that was replaced
is changed.
The ordering of the rest of the systems remains unchanged.
41
Volume 9: Managing the Blue Coat SG Appliance
Note: An empty system cannot be specified as default, and only one system can be
specified as the default system.
To lock a system:
1. Select Maintenance > Upgrade > Systems.
2. Select the system(s) to lock in the Lock column.
3. Click Apply.
To unlock a system:
1. Select Maintenance > Upgrade > Systems.
2. Deselect the system(s) to unlock in the Lock column.
3. Click Apply.
To unlock a system:
42
Chapter 3: Maintaining the SG Appliance
To delete a system:
At the (config) command prompt:
SGOS#(config) installed-systems
SGOS#(config installed-systems) delete system_number
where system_number is the system you want to delete.
Disk Reinitialization
You can reinitialize disks on a multi-disk SG appliance. You cannot reinitialize the disk on
a single-disk SG appliance. If you suspect a disk fault in a single-disk system, contact Blue
Coat Technical Support for assistance.
Note: If a disk containing an unmirrored event or access log is reinitialized, the logs are
lost. Similarly, if two disks containing mirrored copies of the logs are reinitialized, both
copies of the logs are lost.
Multi-Disk SG Appliances
On a multi-disk SG appliance, the master disk is the leftmost valid disk. Valid means that
the disk is online, has been properly initialized, and is not marked as invalid or unusable.
If the current master disk is taken offline, reinitialized, or declared invalid or unusable, the
leftmost valid disk that has not been reinitialized since restart becomes the master disk.
Thus, as disks are reinitialized in sequence, a point is reached where no disk can be chosen
as the master. At this point, the current master disk is the last disk. If this disk is taken
offline, reinitialized, or declared invalid or unusable, the SG appliance is restarted.
On a multi-disk SG appliance, a disk is reinitialized by setting it to empty and copying
pre-boot programs, boot programs, and starter programs, and system images from the
master disk to the reinitialized disk.
Reinitialization is done online without rebooting the system. (For more information, refer
to the #disk command in the Volume 11: Command Line Interface Reference.) SGOS
operations, in turn, are not affected, although during the time the disk is being
reinitialized, that disk is not available for caching. Only the master disk reinitialization
restarts the SG appliance.
Only persistent objects are copied to a newly-reinitialized disk. This is usually not a
problem because most of these objects are replicated or mirrored. If the reinitialized disk
contained one copy of these objects (which is lost), another disk contains another copy.
You cannot reinitialize all of the SG appliance disks over a very short period of time.
Attempting to reinitialize the last disk in a system before critical components can be
replicated to other disks in the system causes a warning message to appear.
Immediately after reinitialization is complete, the SG appliance automatically starts using
the reinitialized disk for caching.
43
Volume 9: Managing the Blue Coat SG Appliance
Single-Disk SG Appliance
The disk on a single-disk SG appliance cannot be reinitialized by the customer. If you
suspect a disk fault in a single-disk SG appliance, contact Blue Coat Technical Support for
assistance.
Note: The maximum number of objects that can be stored in an SG appliance is affected
by a number of factors, including the SGOS version it is running and the hardware
platform series.
This feature is not available in the Management Console. Use the CLI instead.
44
Chapter 4: Diagnostics
❐ traceroute: Traces the route from the current host to the specified destination
host.
❐ test http get path_to_URL: Makes a request through the same code paths as a
proxied client.
❐ display path_to_URL: Makes a direct request (bypassing the cache).
Note: If you cannot access the Management Console at all, be sure that you are using
HTTPS (https://SG_IP_address:8082). If you want to use HTTP, you must
explicitly enable it before you can access the Management Console.
45
Volume 9: Managing the Blue Coat SG Appliance
Important: A core image and packet capture can contain sensitive information—for
example, parts of an HTTP request or response. The transfer to Blue Coat is encrypted,
and therefore secure; however, if you do not want potentially sensitive information to
be sent to Blue Coat automatically, do not enable the automatic service information
feature.
2. To send core image service information to Blue Coat automatically, select Enable auto-
send.
46
Chapter 4: Diagnostics
3. Enter the service-request number that you received from a Technical Support
representative into the Auto Send Service Request Number field (the service-request
number is in the form xx-xxxxxxx or x-xxxxxxx).
4. Click Apply to commit the changes to the SG appliance.
5. (Optional) To clear the service-request number, clear the Auto Send Service Request
Number field and click Apply.
Note: Before you can manage the bandwidth for the automatic service information
feature, you must first create an appropriate bandwidth-management class. Refer to
Volume 5: Advanced Networking for information about creating and configuring bandwidth
classes.
47
Volume 9: Managing the Blue Coat SG Appliance
Important: You must specify a service-request number before you can send service
information. See Blue Coat Technical Support at: http://www.bluecoat.com/support/
index.html for details on opening a service request ticket.
2. Enter the service-request number that you received from a Technical Support
representative (the service-request number is in the form xx-xxxxxxx or x-xxxxxxx).
3. Select the appropriate check boxes (as indicated by a Technical Support
representative) in the Information to send field.
Note: Options for items that you do not have on your system are grayed out and
cannot be selected.
48
Chapter 4: Diagnostics
4. (Optional) If you select Access Logs, Snapshots, or Contexts, you must also click
Select access logs to send, Select snapshots to send, or Select contexts to send and
complete the following steps in the corresponding dialog that appears:
49
Volume 9: Managing the Blue Coat SG Appliance
2. Click New.
3. Enter a snapshot job into the Add list item dialog that displays; click Ok.
4. Click Apply to commit the changes to the SG appliance.
5. (Optional) To view snapshot job information, click View All Snapshots. Close the
window that opens when you are finished viewing.
50
Chapter 4: Diagnostics
51
Volume 9: Managing the Blue Coat SG Appliance
Note: Packet capturing increases the amount of processor usage performed in TCP/IP.
To analyze captured packet data, you must have a tool that reads Packet Sniffer Pro 1.1
files (for example, Ethereal or Packet Sniffer Pro 3.0).
52
Chapter 4: Diagnostics
Note: Some qualifiers must be escaped with a backslash because their identifiers are also
keywords within the filter expression parser.
❐ ip proto protocol
where protocol is a number or name (icmp, udp, tcp).
❐ ether proto protocol
where protocol can be a number or name (ip, arp, rarp).
53
Volume 9: Managing the Blue Coat SG Appliance
2 3
2. In the Direction drop-down list, select the capture direction: in, out, or both.
3. In the Interface drop-down list, select the interface on which to capture.
4. To define or change the PCAP filter expression, enter the filter information into the
Capture filter field. (See “Common PCAP Filter Expressions” on page 52 for
information about PCAP filter expressions for this field.) To remove the filter, clear
this field.
5. Click Start Capture. The Start Capture dialog displays.
54
Chapter 4: Diagnostics
6. Set the buffer size and method by choosing one of the following radio buttons:
a. Capture all matching packets.
b. Capture first n matching packets. Enter the number of matching packets (n) to
capture. If the number of packets reaches this limit, packet capturing stops
automatically. The value must be between 1 and 1000000.
c. Capture last n matching packets. Enter the number of matching packets (n) to
capture. Any packet received after the memory limit is reached results in the
discarding of the oldest saved packet prior to saving the new packet. The
saved packets in memory are written to disk when the capture is stopped. The
value must be between 1 and 1000000.
d. Capture first n matching Kilobytes. Enter the number of kilobytes (n) to
capture. If the buffer reaches this limit, packet capturing stops automatically.
The value must be between 1 and 102400.
e. Capture last n matching Kilobytes. Enter the number of kilobytes (n) to
capture. Any packet received after the memory limit is reached results in the
discarding of the oldest saved packet prior to saving the new packet. The
saved packets in memory are written to disk when the capture is stopped. The
value must be between 1 and 102400.
7. Optional—To truncate the number of bytes saved in each frame, enter a number in the
Save first n bytes of each packet field. When configured, pcap collects, at most, n bytes
of packets from each frame when writing to disk. The range is 1 to 65535.
8. Optional—To specify the number of kilobytes of packets kept in a core image, enter a
value in the Include n K Bytes in core image field. You can capture packets and include
them along with a core image. This is extremely useful if a certain pattern of packets
causes the unit to restart unexpectedly. The core image size must be between 0 and
102400. By default, no packets are kept in the core image.
9. To start the capture, click the Start Capture button. The Start Capture dialog closes.
Note that the Start captures button in the Packet Captures tab is now grayed out
because packet capturing is already started.
You do not have to click Apply because all changes are applied when you start the
packet capture.
10
11
10. To stop the capture, click the Stop capture button. This button is grayed out if a packet
capture is already stopped.
11. To download the capture, click the Download capture button. This button is grayed out
if no file is available for downloading.
55
Volume 9: Managing the Blue Coat SG Appliance
3. Select the desired action: Start packet capture, Stop packet capture, Download packet
capture file.
You can also use the following URLs to configure these individually:
❐ To start packet capturing, use this URL:
https://SG_IP_address:8082/PCAP/start
56
Chapter 4: Diagnostics
❐ Context only—the state of active processes is logged to disk. This is the default.
❐ Full—A complete dump is logged to disk. Use only when asked to do so by Blue Coat
Technical Support.
The default setting of Context only is the optimum balance between restart speed and the
information needs of Blue Coat Technical Support in helping to resolve a system problem.
You can also select the number of core images that are retained. The default value is 2; the
range is between 1 and 10.
57
Volume 9: Managing the Blue Coat SG Appliance
58
Chapter 4: Diagnostics
Note: CPU monitoring uses about 2-3% CPU when enabled, and so is disabled by
default.
3. To enable CPU monitoring, click the Start the CPU Monitor link; to disable it, click the
Stop the CPU Monitor link.
4. To view CPU monitoring statistics, click the CPU Monitor statistics link. You can also
click this link from either of the windows described in Step 3.
Note: The total percentages do not always add up because the display only shows
those functional groups that are using 1% or more of the CPU processing cycles.
59
Volume 9: Managing the Blue Coat SG Appliance
60
Chapter 5: Statistics
The Statistics tabs of the Management Console allow you to view the status of many
system operations. Many statistics are available through the CLI, but only in text
output.
You can also view detailed system information through the CLI using the show
command. Access this command through either the enable command prompt (SGOS#)
or the config command prompt (SGOS#(config)). For convenience, the procedures in
this chapter show only the enable command prompt. See “Using the CLI show
Command to View Statistics” on page 88 for information about using the show
command.
This chapter includes the following topics:
❐ “Viewing Traffic Distribution Statistics” on page 62
❐ “Viewing Traffic History” on page 65
❐ “Viewing the ADN History” on page 68
❐ “Viewing Bandwidth Management Statistics” on page 68
❐ “Viewing Protocol Statistics” on page 68
❐ “Viewing System Statistics” on page 70
❐ “Viewing Traffic Distribution Statistics” on page 62
❐ “Active Sessions—Viewing Per-Connection Statistics” on page 76
❐ “Viewing the Access Log” on page 87
❐ “Viewing Advanced Statistics” on page 87
61
Volume 9: Managing the Blue Coat SG Appliance
g h e
a b
Key:
a. View aggregated bandwidth usage or gain graphs and statistics.
b. View client or server byte-distribution charts and statistics.
c. Review client bytes, server bytes, bypassed bytes, and bandwidth gain (per proxy or
service).
d. Review totals for client bytes, server bytes, bandwidth gain, bypassed bytes, and total gain
(for all proxies or all services).
e. Show default service bytes per port.
f. Switch between proxy and service traffic mix statistics.
g. Modify the historical reporting period.
h. Include or exclude bypassed bytes.
Note: Bypassed bytes are bytes that are not intercepted by a service or proxy. When
you include or exclude bypassed bytes, only the graph data and totals are affected.
The table data in the lower half of the page is not altered.
For a list of supported proxies, see “Supported Proxy Types and Services” on page 66.
62
Chapter 5: Statistics
Note: Endpoint Mapper proxy bytes are the result of Microsoft Remote Procedure Call
(MSRPC) communication for MAPI traffic.
Figure 5-3. Traffic mix statistics displayed when cursor hovers over chart data
63
Volume 9: Managing the Blue Coat SG Appliance
64
Chapter 5: Statistics
5. Select the Proxy radio button to display the bandwidth usage statistics for all
supported proxies.
65
Volume 9: Managing the Blue Coat SG Appliance
b c
Key:
a. View traffic history statistics by service or by proxy.
b. Modify the historical reporting period.
c. Include or exclude bypassed bytes.
d. View totals for client bytes, server bytes, and bandwidth gain for the selected service or
proxy type.
e. Display charts for bandwidth usage, bandwidth gain, client bytes, and server bytes.
Note: Bypassed bytes are bytes that are not intercepted by a service or proxy.
Note: Endpoint Mapper proxy bytes are the result of Remote Procedure Call (RPC)
communication for MAPI traffic.
66
Chapter 5: Statistics
• DNS • IM • P2P
• SOCKS • Telnet
Figure 5-5. Traffic history statistics displayed when cursor hovers over chart data
67
Volume 9: Managing the Blue Coat SG Appliance
68
Chapter 5: Statistics
❐ CIFS History
The Statistics > Protocol Details > CIFS History pages enable you view statistics for
CIFS objects, CIFS bytes read, CIFS bytes written, and CIFS clients. Refer to the CIFS
chapter in Volume 2: Proxies and Proxy Services for more information about these
statistics.
❐ HTTP/FTP History
The Statistics > Protocol Details > HTTP/FTP History pages enable you view statistics
for HTTP/HTTPS/FTP objects, HTTP/HTTPS/FTP bytes, HTTP/HTTPS/FTP
clients, client compression gain, and server compression gain. Refer to the HTTP and
FTP chapters in Volume 2: Proxies and Proxy Services for more information about these
statistics.
For HTTP/FTP bandwidth usage statistics, see the Traffic Mix and Traffic History
pages.
❐ IM History
The Statistics > Protocol Details > IM History pages enable you view statistics for IM
connection data, IM activity data, and IM clients. Refer to the IM chapter in Volume 3:
Web Communication Proxies for more information about these statistics.
❐ MAPI History
The Statistics > Protocol Details > MAPI History pages enable you view statistics for
MAPI client bytes read, MAPI client bytes written, and MAPI clients. Refer to the
MAPI chapter in Volume 2: Proxies and Proxy Services for more information about these
statistics.
For MAPI bandwidth usage statistics, see the Traffic Mix and Traffic History pages.
❐ P2P History
The Statistics > Protocol Details > P2P History pages enable you view statistics for P2P
data, P2P clients, and P2P bytes. Refer to the P2P information in Volume 6: The Visual
Policy Manager and Advanced Policy Tasks for more information about these statistics.
❐ Shell History
The Statistics > Protocol Details > Shell History pages enable you view statistics for
shell clients. Refer to the shell proxy information in Volume 2: Proxies and Proxy Services
for more information about these statistics.
❐ SOCKS History
The Statistics > Protocol Details > SOCKS History pages enable you view statistics for
SOCKS clients, SOCKS connections, client compression gain, and server compression
gain. Refer to the SOCKS chapter in Volume 2: Proxies and Proxy Services for more
information about these statistics.
❐ SSL History
The Statistics > Protocol Details > SSL History pages enable you view statistics for
unintercepted SSL data, unintercepted SSL clients, and unintercepted SSL bytes. Refer
to the SSL chapter in Volume 2: Proxies and Proxy Services for more information about
these statistics.
69
Volume 9: Managing the Blue Coat SG Appliance
❐ Streaming History
The Statistics > Protocol Details > Streaming History pages enable you view statistics
for Windows Media, Real Media, QuickTime, current streaming data, total streaming
data, and bandwidth gain. Refer to the streaming chapter in Volume 3: Web
Communication Proxies for more information about these statistics.
For MMS bandwidth usage statistics, see the Traffic Mix and Traffic History pages.
Resources Statistics
The Resources tabs (CPU, Disk Use, Memory Use, and Data) allow you to view information
about how disk space and memory are being used, and how disk and memory space are
allocated for cache data. You can view data allocation statistics through both the
Management Console and the CLI, but disk and memory use statistics are available only
through the Management Console.
70
Chapter 5: Statistics
71
Volume 9: Managing the Blue Coat SG Appliance
72
Chapter 5: Statistics
❐ Disk used by system objects—The amount of disk space used by the system objects
❐ Disk used by access log—The amount of disk space used for access logs
❐ Total disk installed—The total amount of disk space installed on the device
73
Volume 9: Managing the Blue Coat SG Appliance
Contents Statistics
The Contents tabs (Distribution and Data) allow you to see information about objects
currently stored or served organized by size. The cache contents include all objects
currently stored by the SG appliance. The cache contents are not cleared when the
appliance is powered off.
74
Chapter 5: Statistics
2. Click Log start or Log end or the forward and back arrow buttons to move through the
event list.
3. (Optional) Click the Poll for new events check box to poll for new events that occurred
while the log was being displayed.
75
Volume 9: Managing the Blue Coat SG Appliance
Failover Statistics
At any time, you can view statistics for any failover group you have configured on your
system.
2. From the Failover Group drop-down list, select the group to view.
The information displayed includes the multicast address, the local address, the state, and
any flags, where V indicates that the group name is a virtual IP address, R indicates that
the group name is a physical IP address, and M indicates that this machine can be
configured to be the master if it is available.
76
Chapter 5: Statistics
Important: Use the statistics on the Proxied Sessions pages as a diagnostic tool only.
The Proxied Sessions pages do not display every connection running through the SG
appliance. Rather, this feature displays only the active sessions—one client connection
(or several), together with the relevant information collected from other connections
associated with that client connection. Because it displays only open connections, you
cannot use the data for reporting purposes.
The Proxied Sessions tab displays statistics for the following proxies:
• MAPI • MSRPC
Client connections are available for viewing as soon as the connection request is received.
However, if delayed intercept is enabled, the connection is not shown until the three-way
handshake completes. Server connections are registered and shown in the table after the
connect call completes.
77
Volume 9: Managing the Blue Coat SG Appliance
Table 5-1. Table Column Heading Descriptions on the Proxied Sessions Page
Client IP address and port of the client PC (or other downstream host).
When the client connection is inactive, the contents of this column are
unavailable (gray). A client connection can become inactive if, for
example, a client requests a large object and then aborts the download
before the SG appliance has completed downloading it into its cache.
When the session had multiple client connections, a tree view is
provided. See “Viewing Sessions with Multiple Connections” on
page 81 for more information.
SOCKS. Indicates that the next hop is a SOCKS proxy. If the icon is not
S
present, it indicates that a SOCKS proxy is not in use.
Forwarding. Indicates that the next hop is a proxy server. If the icon is
FW
not present, it indicates that forwarding is not in effect.
Duration Displays the amount of time the session has been established.
Client Bytes Represents the number of bytes (to and from the client) at the socket
level on the client connection. All application-level bytes are counted,
including application overhead such as HTTP headers, CIFS headers,
and so on.
TCP and IP headers, packet retransmissions, and duplicate packets are
not counted.
See “About the Byte Totals” on page 83 for more information.
78
Chapter 5: Statistics
Table 5-1. Table Column Heading Descriptions on the Proxied Sessions Page (Continued)
Server Bytes Represents the number of bytes (to and from the server) at the socket
level on the server connection. All application-level bytes are counted,
including application overhead such as HTTP headers, CIFS headers,
and so on.
If the traffic is flowing through an ADN tunnel, the bytes are counted
after ADN optimization, meaning that compressed byte counts are
displayed.
TCP and IP headers, packet retransmissions, and duplicate packets are
not counted.
See “About the Byte Totals” on page 83 for more information.
Gain Displays the bandwidth gain for the session. The calculation is:
(Client Bytes - Server Bytes)/ Server Bytes
When the request results in a pure cache hit, this column displays
Cache Hit.
Byte Caching. When displayed in color, this icon indicates that an ADN
BC
Tunnel is in use and byte-caching is active in either direction on that
tunnel
This icon has three states:
• Active (color icon)
• Inactive (gray icon)
• Not possible (not displayed)
79
Volume 9: Managing the Blue Coat SG Appliance
Table 5-1. Table Column Heading Descriptions on the Proxied Sessions Page (Continued)
80
Chapter 5: Statistics
HTTP
The tree view displays (as shown above) for HTTP if multiple hosts are contacted during a
session or if pipelining is used.
FTP
FTP uses multiple, concurrent connections. These are represented as separate rows in the
tree view, as shown in the following figure.
81
Volume 9: Managing the Blue Coat SG Appliance
MMS
The active sessions feature displays MMS streams that have a client associated with them.
MMS streams that do not have a client associated with them (multicast, content
management requests, and so on) are not displayed. MMS streams are displayed as
follows:
❐ MMS UDP streams have two connections, one for data and one for control.
❐ MMS TCP streams have a single connection.
❐ MMS HTTP streams have a single connection.
For additional information about streaming connections, see “About MMS Streaming
Connections” on page 81.
82
Chapter 5: Statistics
ADN Tunnels
If the traffic is flowing through an ADN tunnel, the bytes are counted after ADN
optimization, meaning that compressed byte counts are displayed.
Aborted Downloads
In some cases, you might see the server bytes increasing even after the client has closed
the connection. This can occur when a client requests a large object and aborts the
download before receiving the entire object. The server bytes continue to increase because
the SG appliance is retrieving the object for caching.
83
Volume 9: Managing the Blue Coat SG Appliance
If you select a filter, you must enter a filtering criteria (or select None) before clicking
Show.
The following filters are available:
❐ Client Address
Filter by IP address and IP address and subnet mask.
❐ Client Port
❐ Server Address
Filter by IP address or hostname. Hostname filters automatically search for suffix
matches. For example, if you filter for google.com, gmail.google.com is included in
the results.
❐ Server Port
❐ Proxy
❐ Service (drop-down list)
The drop-down list enables you to filter for enabled services. If you filter for a service
that is not supported for active sessions (see “What Is Not Displayed” on page 83), the
resulting filtering list will be empty.
84
Chapter 5: Statistics
The Bypassed Connections page displays data for connections that were not intercepted
because:
❐ A service has not been configured to intercept the traffic.
❐ A static or dynamic bypass rule caused the traffic to be bypassed.
❐ The interface transparent interception setting is disabled.
Table 5-2. Table Column Heading Descriptions on the Bypassed Connections Page
Client IP address and port of the client PC (or other downstream host).
85
Volume 9: Managing the Blue Coat SG Appliance
Table 5-2. Table Column Heading Descriptions on the Bypassed Connections Page (Continued)
Duration Displays the amount of time the connection has been established.
Bypassed Bytes Displays the total number of bypassed bytes for the connection.
86
Chapter 5: Statistics
87
Volume 9: Managing the Blue Coat SG Appliance
2. Click the appropriate link for the service you want to view.
A list of categories for that service displays.
Note: If you upgraded from SGOS 2.x or CacheOS 4.x and have log files generated
by those versions, you can view or retrieve them through the Statistics > Advanced >
Access Log > Show Old Logs URL.
3. To view the statistics for a particular category, click that category’s link.
A window opens, detailing the relevant statistics.
4. Close the window when you have finished viewing the statistics.
5. To return to the list of links, either reselect Statistics > Advanced or click your
browser’s Back button.
88
Chapter 5: Statistics
89
Volume 9: Managing the Blue Coat SG Appliance
90
Appendix A: Glossary
access log A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.
account A named entity that has purchased the appliance or the Entitlements from Blue Coat.
activation code A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.
active content stripping Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.
active content types Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user
administration access policy A policy layer that determines who can access the SG appliance to perform
administrative tasks.
administration A policy layer that determines how administrators accessing the SG appliance must
authentication policy authenticate.
Application Delivery A WAN that has been optimized for acceleration and compression by Blue Coat. This
Network (ADN) network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.
ADN backup manager Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.
ADN manager Responsible for publishing the routing table to SG Clients (and to other SG
appliances).
ADN optimize attribute Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.
asx rewrite Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxy-
like support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.
audit A log that provides a record of who accessed what and how.
91
Volume 9: Managing the Blue Coat SG Appliance
authenticate-401 attribute All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios
authenticated content Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).
authentication Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate Authority.
See also basic authentication, proxy authentication, and SSL authentication.
authentication realm Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.
bandwidth class hierarchy Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.
bandwidth management Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.
basic authentication The standard authentication for communicating with the target as identified in the
URL.
BCAAA Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.
byte-range support The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).
cache An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.
cache control Allows you to configure which content the SG appliance stores.
92
Appendix A: Glossary
cache efficiency A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.
cache hit Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.
cache miss Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .
cache object Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.
Certificate Authority (CA) A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.
child class (bandwidth gain) The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.
client consent certificates A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.
client-side transparency A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.
concentrator An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.
content filtering A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.
default boot system The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.
denial of service (DoS) A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.
93
Volume 9: Managing the Blue Coat SG Appliance
destination objects Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.
detect protocol attribute Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.
diagnostic reporting Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.
directives Commands used in installable lists to configure forwarding and SOCKS gateway.
DNS access A policy layer that determines how the SG appliance processes DNS requests.
domain name system (DNS) An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.
dynamic bypass Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.
dynamic real-time rating Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
(DRTR) dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.
early intercept attribute Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.
ELFF-compatible format A log type defined by the W3C that is general enough to be used with any protocol.
emulated certificates Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.
encrypted log A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.
event logging Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.
94
Appendix A: Glossary
explicit proxy A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.
extended log file format A variant of the common log file format, which has two additional fields at the end of
(ELFF) the line—the referer and the user agent fields.
fail open/closed Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.
forward proxy A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.
gateway A device that serves as entrance and exit into a communications network.
hardware serial number A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.
health check tests The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
• ICMP
• TCP
• SSL
• HTTP
• HTTPS
• Group
• Composite and reference to a composite result
• ICAP
• Websense
• DRTR rating service
95
Volume 9: Managing the Blue Coat SG Appliance
health check type The kind of device or service the specific health check tests. The following types are
supported:
• Forwarding host and forwarding group
• SOCKS gateway and SOCKS gateway group
• CAP service and ICAP service group
• Websense off-box service and Websense off-box service group
• DRTR rating service
• User-defined host and a user-defined composite
heartbeat Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.
host affinity The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.
host affinity timeout The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.
inbound traffic (bandwidth Network packets flowing into the SG appliance. Inbound traffic mainly consists of
gain) the following:
• Server inbound: Packets originating at the origin content server (OCS) and sent to
the SG appliance to load a Web object.
• Client inbound: Packets originating at the client and sent to the SG appliance for
Web requests.
installable lists Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
• Creating the list using the SG text editor
• Placing the list at an accessible URL
• Downloading the directives file from the local system
integrated host timeout An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.
intervals Time period from the completion of one health check to the start of the next health
check.
IP reflection Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.
96
Appendix A: Glossary
issuer keyring The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.
licensable component (LC) (Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.
license Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.
listener The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.
live content Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.
load balancing A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.
local bypass list A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.
local policy file Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).
log facility A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.
log format The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.
log tail The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.
97
Volume 9: Managing the Blue Coat SG Appliance
Management Console A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.
management information Defines the statistics that management systems can collect. A managed device
base (MIB) (gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.
maximum object size The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.
MIME/FILE type filtering Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.
multi-bit rate The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).
multicast Used in streaming; the ability for hundreds or thousands of users to play a single
stream.
multicast aliases Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel
multicast station Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).
multimedia content services Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.
name inputing Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server
native FTP Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).
NCSA common log format Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.
network address translation The process of translating private network (such as intranet) IP addresses to Internet
(NAT) IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.
98
Appendix A: Glossary
non-cacheable objects A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
• Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
• Password provided, requests that include a client password.
• Data in request that include additional client data.
• Not a GET request.
.nsc file Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.
NTP To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.
object (used in caching) An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.
object (used in Visual Policy An object (sometimes referred to as a condition) is any collection or combination of
Manager) entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.
object pipelining This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.
origin content server (OCS) Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.
outbound traffic (bandwidth Network packets flowing out of the SG appliance. Outbound traffic mainly consists
gain) of the following:
• Client outbound: Packets sent to the client in response to a Web request.
• Server outbound: Packets sent to an OCS or upstream proxy to request a service.
PAC (Proxy Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
AutoConfiguration) scripts port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.
packet capture (PCAP) Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.
99
Volume 9: Managing the Blue Coat SG Appliance
parent class (bandwidth A class with at least one child. The parent class must share its bandwidth with its
gain) child classes in proportion to the minimum/maximum bandwidth values or priority
levels.
passive mode data Data connections initiated by an FTP client to an FTP server.
connections (PASV)
policies Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.
policy-based bypass list Used in policy. Allows a bypass based on the properties of the client, unlike static and
dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.
policy layer A collection of rules created using Blue Coat CPL or with the VPM.
pragma: no cache (PNC) A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).
proxy Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.
proxy service The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.
proxy service (default) The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.
public key certificate An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).
public virtual IP (VIP) Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.
100
Appendix A: Glossary
real-time streaming protocol A standard method of transferring audio and video and other time-based media over
(RTSP) Internet-technology based networks. The protocol is used to stream clips to any RTP-
based client.
reflect client IP attribute Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.
registration An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.
remote authentication dial- Authenticates user identity via passwords for network access.
in user service (RADIUS)
reverse proxy A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.
routing information protocol Designed to select the fastest route to a destination. RIP support is built into Blue
(RIP) Coat appliances.
router hops The number of jumps a packet takes when traversing the Internet.
secure shell (SSH) Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.
serial console A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.
server certificate categories The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.
server portals Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping a
set of external URLs onto a set of internal URLs.
server-side transparency The ability for the server to see client IP addresses, which enables accurate client-
access records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.
service attributes Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .
101
Volume 9: Managing the Blue Coat SG Appliance
SG appliance A Blue Coat security and cache box that can help manage security and content on a
network.
sibling class (bandwidth A bandwidth class with the same parent class as another class.
gain)
simple network The standard operations and maintenance protocol for the Internet. It uses MIBs,
management protocol created or customized by Blue Coat, to handle (needs completion).
(SNMP)
simulated live Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.
SmartReporter log type A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.
SOCKS A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.
SOCKS proxy A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.
splash page Custom message page that displays the first time you start the client browser.
split proxy Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
• Mapi Proxy
• SSL Proxy
SQUID-compatible format A log type that was designed for cache statistics and is compatible with Blue Coat
products.
squid-native log format The Squid-compatible format contains one line for each request.
SSL authentication Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).
SSL proxy A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.
static route A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.
102
Appendix A: Glossary
statistics Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated, cache
efficiency, cached contents, and custom URLs generated by the appliance for various
kinds of logs. You can also check the event viewer for every event that occurred since
the appliance booted.
stream A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.
SurfControl log type A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.
system cache The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.
time-to-live (TTL) value Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.
traffic flow Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
(bandwidth gain) that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of
these connections, traffic flows in two directions—in one direction, packets flow out
of the SG appliance (outbound traffic), and in the other direction, packets flow into
the SG (inbound traffic). Connections can come from the client or the server. Thus,
traffic can be classified into one of four types:
• Server inbound
• Server outbound
• Client inbound
• Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.
transmission control TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
protocol (TCP) in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.
transparent proxy A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.
103
Volume 9: Managing the Blue Coat SG Appliance
trial period Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.
unicast alias Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicast-
alias command to request the content from the origin streaming server.
universal time coordinates An SG appliance must know the current UTC time. By default, the appliance
(UTC) attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.
URL rewrite rules Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.
WCCP Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.
Web FTP Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
OCS (if the content is not already cached), and then translates the FTP response with
the file contents into an HTTP response for the client.
Websense log type A Blue Coat proprietary log type that is compatible with the Websense reporter tool.
104
Index
A CPU
access logging 87 utilization 70
active sessions 76 CPU monitoring
bypassed connections 84 configuring 59
proxied sessions 77 CPU utilization 70
ADN history 68 cpu utilization 70
appliance certificate 9
automatic service information, enabling 46 D
data allocation 73
B default service 64
bandwidth gain 64 defaults, restoring system defaults 34
bandwidth management 68 deleting objects from the Blue Coat SG 44
bandwidth usage 64 diagnostics
Blue Coat monitoring, enabling 58 Blue Coat monitoring 58
Blue Coat SG core image restart options 57
deleting image 43 CPU monitoring 59
deleting objects from 44 heartbeats 58
locking and unlocking a system 42 packet capturing 52
managing 40 sending service information 48
replacing a system 40, 42 sending service information automatically 46
restarting 33 snapshot jobs 50
setting the default system to boot 41 Director
single-disk 44 communicating with 11
system defaults 34 SG appliance registration and setup 9
upgrading 37, 38 disk
viewing details 40 multi-disk Blue Coat SG 43
bypassed bytes 63 reinitialization 43
bypassed connections 84 single-disk Blue Coat SG 44
byte distribution 65 disk use 70, 72
disks 70
C DNS
cache contents 74 cache, purging 36
CacheOS 4.x, logs, retrieving 88 document
caching conventions 7
clearing the system cache 36
objects by size 74 E
purging the DNS cache 36 empty system 40
restarting the Blue Coat SG 33 event logging
capturing packets, see packet capturing configuration, viewing 18
community strings 21 contents, viewing 19
concurrent users, viewing 71 event notification 16
core image log levels 15
restart options 57 log size 16
overview 15
105
Volume 9: Managing the Blue Coat SG Appliance
106
Index
107
Volume 9: Managing the Blue Coat SG Appliance
108
Blue Coat® Systems
SG™ Appliance
Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos 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.
ii
Contents
Contact Information
iii
Blue Coat ProxySG Content Policy Language Guide
iv
Contents
client.protocol=................................................................................................................................................. 69
condition= ......................................................................................................................................................... 70
console_access= ................................................................................................................................................ 72
content_admin=................................................................................................................................................ 73
content_management ...................................................................................................................................... 74
date[.utc]= ......................................................................................................................................................... 75
day= ................................................................................................................................................................... 76
dns.client_transport=....................................................................................................................................... 77
dns.request.address=....................................................................................................................................... 78
dns.request.category= ..................................................................................................................................... 79
dns.request.class= ............................................................................................................................................ 80
dns.request.name=........................................................................................................................................... 81
dns.request.opcode=........................................................................................................................................ 82
dns.request.type=............................................................................................................................................. 83
dns.response.a= ................................................................................................................................................ 84
dns.response.cname= ...................................................................................................................................... 85
dns.response.code=.......................................................................................................................................... 86
dns.response.nodata=...................................................................................................................................... 87
dns.response.ptr=............................................................................................................................................. 88
exception.id= .................................................................................................................................................... 89
ftp.method= ...................................................................................................................................................... 91
group= ............................................................................................................................................................... 92
has_attribute.name= ........................................................................................................................................ 94
has_client= ........................................................................................................................................................ 95
health_check= ................................................................................................................................................... 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
is_healthy.health_check_name= .................................................................................................................. 112
im.buddy_id= ................................................................................................................................................. 113
im.chat_room.conference=............................................................................................................................ 114
im.chat_room.id= ........................................................................................................................................... 115
im.chat_room.invite_only=........................................................................................................................... 116
im.chat_room.type=....................................................................................................................................... 117
im.chat_room.member=................................................................................................................................ 118
im.chat_room.voice_enabled= ..................................................................................................................... 119
im.client=......................................................................................................................................................... 120
im.file.extension= ........................................................................................................................................... 121
v
Blue Coat ProxySG Content Policy Language Guide
vi
Contents
socks=............................................................................................................................................................... 176
socks.accelerated= ......................................................................................................................................... 177
socks.method=................................................................................................................................................ 178
socks.version= ................................................................................................................................................ 179
ssl.proxy_mode= ............................................................................................................................................ 180
streaming.client=............................................................................................................................................ 181
streaming.content= ........................................................................................................................................ 182
time= ................................................................................................................................................................ 183
tunneled= ........................................................................................................................................................ 185
url= ................................................................................................................................................................... 186
url.category=................................................................................................................................................... 193
user=................................................................................................................................................................. 194
user.authentication_error= ........................................................................................................................... 196
user.authorization_error=............................................................................................................................. 197
user.domain= .................................................................................................................................................. 198
user.is_guest= ................................................................................................................................................. 199
user.login.address=........................................................................................................................................ 200
user.login.count= ........................................................................................................................................... 201
user.login.time=.............................................................................................................................................. 202
user.x509.issuer= ............................................................................................................................................ 203
user.x509.serialNumber= .............................................................................................................................. 204
user.x509.subject= .......................................................................................................................................... 205
virus_detected= .............................................................................................................................................. 206
weekday= ........................................................................................................................................................ 207
year= ................................................................................................................................................................ 208
vii
Blue Coat ProxySG Content Policy Language Guide
authenticate.redirect_stored_requests()...................................................................................................... 232
authenticate.surrogate_refresh_time() ........................................................................................................ 233
authenticate.tolerate_error() ......................................................................................................................... 234
authenticate.use_url_cookie( )...................................................................................................................... 235
authorize.add_group() .................................................................................................................................. 236
authorize.tolerate_error().............................................................................................................................. 237
bypass_cache( ) .............................................................................................................................................. 238
cache( ) ............................................................................................................................................................ 239
category.dynamic.mode( ) ............................................................................................................................ 241
check_authorization( ) ................................................................................................................................... 242
client.address.login.log_out_other()............................................................................................................ 243
client.certificate.require( ) ............................................................................................................................. 244
client.certificate.validate( )............................................................................................................................ 245
client.certificate.validate.check_revocation() ............................................................................................. 246
client.connection.dscp()................................................................................................................................. 247
cookie_sensitive( ) ......................................................................................................................................... 248
delete_on_abandonment( ) ........................................................................................................................... 249
deny( ) .............................................................................................................................................................. 250
deny.unauthorized( ) ..................................................................................................................................... 251
detect_protocol( ) ........................................................................................................................................... 252
direct( ) ............................................................................................................................................................ 253
dns.respond( ) ................................................................................................................................................. 254
dns.respond.a( ) .............................................................................................................................................. 255
dns.respond.ptr( )........................................................................................................................................... 256
dynamic_bypass( ) ......................................................................................................................................... 257
exception( )...................................................................................................................................................... 258
exception.autopad( ) ...................................................................................................................................... 259
force_cache( ) ................................................................................................................................................. 260
force_deny( ) ................................................................................................................................................... 261
force_exception( ) ........................................................................................................................................... 262
force_patience_page( )................................................................................................................................... 263
force_protocol( ) ............................................................................................................................................. 264
forward( ) ........................................................................................................................................................ 265
forward.fail_open( ) ....................................................................................................................................... 266
ftp.match_client_data_ip( ) ........................................................................................................................... 267
ftp.match_server_data_ip( ).......................................................................................................................... 268
ftp.server_connection( )................................................................................................................................. 269
ftp.server_data( ) ............................................................................................................................................ 270
ftp.transport( ) ................................................................................................................................................ 271
ftp.welcome_banner( )................................................................................................................................... 272
http.allow_compression( ) ............................................................................................................................ 273
http.allow_decompression( ) ........................................................................................................................ 274
http.client.allow_encoding( )........................................................................................................................ 275
http.client.persistence( ) ................................................................................................................................ 276
http.client.recv.timeout( ).............................................................................................................................. 277
http.compression_level( ).............................................................................................................................. 278
http.force_ntlm_for_server_auth( ) ............................................................................................................. 279
http.refresh.recv.timeout( ) ........................................................................................................................... 281
http.request.version( ) ................................................................................................................................... 282
viii
Contents
ix
Blue Coat ProxySG Content Policy Language Guide
x
Contents
xi
Blue Coat ProxySG 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. SG appliance 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 SG appliance to your specifications.
CPL has the following capabilities:
• Fine-grained control over various aspects of SG appliance 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.
Chapter 1 – Overview of Content Policy This chapter provides an overview of CPL, including concepts, CPL
Language 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.
Appendix A – Glossary Terms used in this manual are defined in this appendix.
xiii
Volume 10: Content Policy Language Guide
Appendix E—Using Regular Expressions This appendix discusses regular expressions and how to use them.
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.
Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax conventions
used in this manual.
Table 3.2: Typographic Conventions
Conventions Definition
Italics The first use of a new or Blue Coat-proprietary term.
Courier font Command line text that appears on your administrator workstation.
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 SG appliance literal to be entered as shown.
{ } One of the parameters enclosed within the braces must be supplied
[ ] An optional parameter or parameters.
xiv
Chapter :
Conventions Definition
| 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 10: 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"
• "CPL Language Basics"
• "Writing Policy Using CPL"
• "Troubleshooting Policy"
• "Upgrade/Downgrade Issues"
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 SG appliance. 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 SG 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 10: Content Policy Language Guide
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.
• Cache Transactions—the default is to allow requests.
18
Chapter 1: Overview of Content Policy Language
These requests originate from the SG appliance 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 SG appliances, the default is to deny all requests. For SG appliances being upgraded from
4.x, the default is to allow all requests. In either case, the SG appliance can be configured for either
default. The default setting is displayed in policy listings.
The proper approach to writing <proxy> 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 SG appliance.
; 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 SG appliance, and is evaluated during request
processing to override any default decisions taken from configuration.
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 10: 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:
• 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
20
Chapter 1: Overview of Content Policy Language
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 10: 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_type [action]> [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 35.
• The optional action, separated from the layer type by space, is a CPL User-defined
Identifier (see "Understanding Sections" on page 42), 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 10: Content Policy Language Guide
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 377 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 417.
25
Volume 10: 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 SG appliance.)
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.
26
Chapter 1: Overview of Content Policy Language
<Proxy>
client.address=!corporate_subnet deny ; filter out strangers
force_authenticate(MyRealm) ; this has higher precedence than deny
<Proxy>
; 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
<Proxy>
client.address=!corporate_subnet deny ; filter out strangers
socks.authenticate(MyRealm) ; this happens earlier than the category test
<Proxy>
; 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.
27
Volume 10: Content Policy Language Guide
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".
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.
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.
28
Chapter 1: Overview of Content Policy Language
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= <version number range>
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 10: 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"
• "Understanding Layers"
• "Understanding Sections"
• "Defining Policies"
• "Best Practices"
<Admin> Transactions
An administrator transaction evaluates policy in <Admin> layers. The policy is evaluated in two stages:
• Before the authentication challenge.
• After the authentication challenge.
If an administrative user logs in to the SG appliance Management Console, and the administrator’s
Web browser is proxied through that same SG appliance, then a proxy transaction is created and
<Proxy> policy is evaluated before the administrator transaction is created and <Admin> policy is
evaluated. In this case, it is possible for an administrator to be denied access to the Management
Console by proxy policy.
31
Volume 10: Content Policy Language Guide
Important: Policy is not evaluated for serial console access, RSA authenticated SSH access, managers
logged in using the console account credentials, or SNMP traffic.
<Proxy> 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 <DNS-Proxy> transactions section.
A proxy transaction evaluates policy in <Proxy>, <Cache>, <Forward>, and <Exception> layers. The
<Forward> 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 <Exception> 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
32
Chapter 2: Managing Content Policy Language
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
gateway must be determined by stage three.
<DNS-Proxy> Transactions
When a client connects to one of the DNS-Proxy service ports configured on the SG appliance (for
information refer to Volume 2: Proxies and Proxy Services), a <DNS-Proxy> transaction is created to cover
both the request and its associated response.
A <DNS-Proxy> transaction evaluates policy in <DNS-Proxy> layers only. Policy in other layers does
not affect <DNS-Proxy> transactions.
Policy for <DNS-Proxy> transactions is evaluated in two stages:
• After the DNS request is received
• After the DNS response is available.
<Cache> Transactions
Cache transactions are initiated by the SG appliance 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
33
Volume 10: Content Policy Language Guide
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 <Cache> and <Forward> layers. The <Forward> 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 SG appliance, 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.
<Exception> Transaction
Exception transactions include <Proxy> transactions that have been terminated by an exception.
<Forwarding> Transactions
A <Forwarding> transaction is created when the SG appliance 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 <Forwarding> transaction only evaluates policy in <Forward> layers.
<SSL> Transactions
Two kinds of <SSL> transactions exist:
• <SSL>: This includes cache and proxy transactions, except for <SSL-Intercept> transactions.
Note that in VPM, <SSL> transactions are referred to as SSL access transactions.
• <SSL-Intercept>: 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.
34
Chapter 2: Managing Content Policy Language
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.
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 SG appliance 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 <Forwarding> 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.
35
Volume 10: Content Policy Language Guide
• <Admin>—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.
• <Cache>—Used to list policy rules that are evaluated during both cache and proxy transactions.
• <Exception>—Exception layers are evaluated when a proxy transaction is terminated by an
exception.
• <Forward>—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.
• <Proxy>—Used to list policy rules that are evaluated during a proxy transaction.
• <DNS-Proxy>—Used to define policy controlling <DNS-Proxy> transactions. Only <DNS-Proxy>
transactions are evaluated against <DNS-Proxy> layers.
• <SSL-Intercept>—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.
• <SSL>—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 <DNS-Proxy> 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.
<Admin> Layers
<Admin> 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 <Admin> layer with the client IP
address set to the SG appliance’s IP address; therefore, the client.address= condition
is not useful for explicitly proxied traffic.
36
Chapter 2: Managing Content Policy Language
<Cache> Layers
<Cache> layers hold policy that is executed by both cache and proxy transactions. Since cache
transactions have no concept of a client, all <Cache> 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 <Cache> 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 <Proxy> layer.)
Only the following properties are safe to make conditional on time or client identity in a <Cache>
layer:
• Pipelining
• Tracing, logging
• Freshness checks
• Redirection
• Content transforms
37
Volume 10: Content Policy Language Guide
<Exception> Layers
<Exception> 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 [“comment”]> [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". 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". See also the
following Layer Guards section.
• exception_rules is a list of rules representing the decision to be made by this policy layer.
<Forward> Layers
<Forward> layers are evaluated when the current transaction requires an upstream connection (and
only then: forward policy will not be evaluated for a cache hit). <Forward> layers use the
38
Chapter 2: Managing Content Policy Language
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 [“comment”]> [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". 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". See also the following Layer Guards section.
• forward_rules is a list of rules representing the decision to be made by this policy layer.
<Proxy> Layers
<Proxy> 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
Systems Configuration and Management Guide). Proxy layer policy involves both client identity and
content. Only proxy transactions are evaluated against <Proxy> layers.
Note: Policy for <DNS-Proxy> transactions is distinct from policy for other proxy services. See the
following <DNS-Proxy> Layers section.
39
Volume 10: Content Policy Language Guide
<DNS-Proxy> Layers
<DNS-Proxy> layers define policy controlling <DNS-Proxy> transactions. Only <DNS-Proxy>
transactions are evaluated against <DNS-Proxy> layers.
The syntax is:
<DNS-Proxy [“comment”]> [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". 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". 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.
<SSL-Intercept> Layers
The <SSL-Intercept> 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 [“comment”]> [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". 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
specific rules in the layer. For more information on using properties, see Chapter 4:
"Property Reference". 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.
40
Chapter 2: Managing Content Policy Language
<SSL> Layers
The <SSL> 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 [“comment”]> [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". 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". 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:
<Proxy>
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:
<Proxy> group=general_staff deny
url.domain=competitor.com/jobs
url.host=bad_host
condition=whatever
; etc.
allow
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.
41
Volume 10: Content Policy Language Guide
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:
<Proxy>
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:
<Proxy> 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:
<Proxy>
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)
42
Chapter 2: Managing Content Policy Language
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:
<Proxy>
[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:
<Proxy>
[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.
• 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.
43
Volume 10: Content Policy Language Guide
[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 <Admin> or <Forward> 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 <Admin> or <Forward> 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 <Admin> ,<DNS-Proxy> or <Forward> 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.
• 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 <Proxy>, <Cache>, <Forward>, <SSL> and
<SSL-Intercept> layers.
44
Chapter 2: Managing Content Policy Language
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 (<Proxy>, <Cache>, <Admin>, <Forward>, or <Exception>) 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:
<Admin> group=Administrators
[Rule] allow
Correct policy that allows access for the group “administrators” would be:
<Admin>
group=Administrators allow
In the following example, the layer is deceptive because only the first rule can ever be executed:
<Proxy>
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:
<Proxy>
authenticate(MyRealm)
<Proxy>
allow group=administrator
allow group=clerk time=0900..1700
deny
• Do not mix the CacheOS 4.x filter-file syntax with CPL syntax.
45
Volume 10: Content Policy Language Guide
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.
46
Chapter 2: Managing Content Policy Language
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:
<Proxy>
; 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
<Proxy> 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 46) 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.
47
Volume 10: Content Policy Language Guide
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.
48
Chapter 2: Managing Content Policy Language
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
<Proxy>
ALLOW client.address=corporate_subnet
; Next, impose any authentication requirements
<Proxy>
authenticate(corp_realm) ; all access must be authenticated
; And now begin to filter-out unwanted requests
<Proxy>
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.
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.
49
Volume 10: Content Policy Language Guide
50
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".
51
Volume 10: Content Policy Language Guide
• 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.
52
Chapter 3: Condition Reference
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.
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.
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".
restrict dns Applies to all layers. Applies to all If the domain specified in a URL matches any of
domain_list transactions. the domain patterns specified in domain_list,
end 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. Applies to all If the requested URL specifies the host in IP form,
subnet_list transactions. no RDNS lookup is performed to match any
end 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.
53
Volume 10: 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
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
<Admin>
authenticate(my_realm)
<Admin>
ALLOW condition=Full_admins
ALLOW condition=Read_only_admins admin.access=READ
DENY
Notes
• 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 <admin> layer.
54
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.2: 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-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
Note: When used in the <Forward> 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.
55
Volume 10: Content Policy Language Guide
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.)
<Proxy>
authenticate(LDAPRealm)
<Proxy> 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
<Proxy>
authenticate(RADIUSRealm)
; This rule would restrict non-authorized users.
<Proxy>
deny condition=!ProxyAllowed
; This rule would serve to override a previous denial and grant access to authorized
; users
<Proxy>
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=
• Properties: authenticate( ), authenticate.force( ), check_authorization( ),
exception( ), socks.authenticate( ), socks.authenticate.force( )
56
Chapter 3: Condition Reference
authenticated=
True if authentication was requested and the credentials could be verified; otherwise, false.
Syntax
authenticated=(yes|no)
Example
; In this example, only users authenticated in any domain are granted access to a
; specific site.
<Proxy>
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.
<Proxy> 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.
<Proxy> server_url.domain=xyz.com
allow authenticated=yes
See Also
• Conditions: attribute.name=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.domain=
57
Volume 10: 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:
• 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.
Note: 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.
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.
<Proxy>
authenticate(NTLMRealm)
<Proxy>
; 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..
58
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.
<Proxy> ; 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( )
59
Volume 10: 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 382), 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.
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.
Example
; This example denies requests for games or sports related content.
<Proxy>
; 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
• Properties: exception( ), request.filter_service( )
60
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.
Note: If a user is explicitly proxied to the SG appliance, <Proxy> layer policy applies even if the
URL destination is an administrative URL for the SG appliance itself, and should
therefore also be covered under <Admin> layer policy. However, when the
client.address= condition is used in an <Admin> layer, clients explicitly proxied to the
SG appliance appear to have their client IP address set to the IP address of the SG
appliance.
Syntax
client.address=ip_address|subnet_label
where:
• ip_address—Client IP address or subnet specification; for example, 10.25.198.0/24.
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 SG appliance.
<admin>
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
61
Volume 10: Content Policy Language Guide
client.address.login.count=
Test the number active logins at the current ip address.
This condition is used to test how many logins are active on the current ip address. It can be used to
manage the maximum number of logins per ip address.
Syntax
client.address.login.count([lower]..[upper]|exact)
where:
• [lower] is optionally the fewest number of logins that will match this condition.
• [upper] is optionally the most number of logins that will match this condition.
• exact is optionally the exact number of logins that will match this condition.
Example
Log out the other logins of there is more than one login at this ip address
<proxy>
client.address.login.count=2.. client.address.login.log_out_other(yes)
62
Chapter 3: Condition Reference
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
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.
<proxy>
deny client.connection.dscp = 50
<proxy>
deny client.connection.dscp = best-effort
63
Volume 10: Content Policy Language Guide
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
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
<Proxy>
ALLOW client.connection.negotiated_cipher= \
(EXP1024-RC4-MD5|| \
EXP1024-RC4-SHA|| \
EXP1024-RC2-CBC-MD5|| \
EXP1024-DES-CBC-SHA)
DENY
; 2
<Proxy>
client.connection.negotiated_cipher=none access_log[unsecure_log1](yes)
64
Chapter 3: Condition Reference
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
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.
<Proxy>
; 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:
• 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.
65
Volume 10: Content Policy Language Guide
client.connection.negotiated_ssl_version=
Test the SSL version negotiated with a securely connected client.
Syntax
client.connection.negotiated_ssl_version=SSLV2|SSLV3|TLSV1
Example
<SSL>
client.connection.negotiated_ssl_version=SSLV3
66
Chapter 3: Condition Reference
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
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.
<Proxy>
ALLOW
<Proxy>
; 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."
67
Volume 10: Content Policy Language Guide
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
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
<Proxy>
DENY
<Proxy>
; 1
ALLOW client.address=subnetA client.host.has_name=yes
68
Chapter 3: Condition Reference
client.protocol=
Test the protocol used between the client and the SG appliance.
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 <dns-proxy> layer only.
See Also
• Conditions: client.address=, proxy.address=, proxy.card=, proxy.port=
69
Volume 10: Content Policy Language Guide
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.
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
<Proxy>
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
<Proxy>
authenticate(My_realm)
<Proxy>
condition=forbidden deny
70
Chapter 3: Condition Reference
See Also
• Definitions: define condition, define url.domain condition, define url condition
• Properties: action.action_label( )
71
Volume 10: Content Policy Language Guide
console_access=
Tests if the current request is destined for the <Admin> layer. This test can be used to distinguish access
to the management console by administrators who are explicitly proxied to the SG appliance 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 <Proxy> layer.
Syntax
console_access=yes|no
See Also
• Conditions: admin.access=
72
Chapter 3: Condition Reference
content_admin=
The content_admin= condition has been deprecated. For more information, see
"content_management" on page 74.
73
Volume 10: Content Policy Language Guide
content_management
Tests if the current request is a content management transaction.
Replaces: content_admin=yes|no
Syntax
content_management=yes|no
See Also
• Conditions: category=, ftp.method=, http.method=, http.x_method=, server_url=
• Properties: http.request.version( ), http.response.version( )
74
Chapter 3: Condition Reference
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
See Also
• Conditions: day=, hour=, minute=, month=, time=, weekday=, year=
75
Volume 10: Content Policy Language Guide
day=
Tests if the day of the month is in the specified range or an exact match. The SG appliance 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.
• exact_day—An integer from 1 to 31, indicating the day of the month that will test true.
Note: 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.
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.
<Proxy> 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.
<Proxy> 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=
76
Chapter 3: Condition Reference
dns.client_transport=
Test the transport protocol of a proxied DNS query
Syntax
dns.client_transport=tcp|udp
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
<DNS-Proxy>
client.address=!10.9.8.0/24 dns.client_transport=tcp dns.respond(refused)
77
Volume 10: Content Policy Language Guide
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
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
<DNS-Proxy>
; 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")
78
Chapter 3: Condition Reference
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,
...
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-Proxy> 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
• 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.
79
Volume 10: Content Policy Language Guide
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
Example
This example implements the following policy:
• Refuse all DNS traffic that does not use the QCLASS “IN“
<DNS-Proxy>
dns.request.class=!IN dns.respond(refused)
80
Chapter 3: Condition Reference
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
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-Proxy>
dns.request.name=.example.com dns.respond(refused)
; 2
<DNS-Proxy>
dns.request.name=host1.example.com dns.respond(auto)
81
Volume 10: Content Policy Language Guide
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
Example
This example implements the following policy:
• Refuse all DNS traffic that does not use the OPCODE “QUERY.”
<DNS-Proxy>
dns.request.opcode=!QUERY dns.respond(refused)
82
Chapter 3: Condition Reference
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
MAILA ALL
Example
<DNS-Proxy>
dns.request.type=CNAME
83
Volume 10: Content Policy Language Guide
dns.response.a=
Test the addresses from the A RRs in the DNS response
Syntax
dns.response.a=ip_address|subnet|subnet_label
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-Proxy>
dns.response.a=10.9.8.7 dns.respond.a(10.10.10.10)
84
Chapter 3: Condition Reference
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
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-Proxy>
dns.response.cname=.example.com dns.respond(refused)
; 2
<DNS-Proxy>
dns.response.cname=host1.example.com dns.respond(auto)
85
Volume 10: Content Policy Language Guide
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|yxr
rset|nxrrset|notauth|notzone|numeric range from 0 to 15
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.
<DNS-Proxy>
dns.response.code=yxdomain dns.respond(nxdomain)
86
Chapter 3: Condition Reference
dns.response.nodata=
Test whether the DNS response had no RRs
Syntax
dns.response.nodata=yes|no
Example
This example implements the following policy:
• We have a DNS server that routinely sends back empty responses. Some of our clients fail to
handle this gracefully. The server in question needs to be patched, but it is in another department,
so, for the time being, convert empty response to nxdomain, which our clients can handle okay.
<DNS-Proxy>
dns.response.nodata=yes dns.respond(nxdomain)
87
Volume 10: Content Policy Language Guide
dns.response.ptr=
Test the hostname values from the PTR RRs in the DNS response
Syntax
dns.response.ptr=hostname
dns.response.ptr=domain-suffix
dns.response.ptr.exact=string
dns.response.ptr.prefix=string
dns.response.ptr.substring=string
dns.response.ptr.suffix=string
dns.response.ptr.regex=regular_expression
Example
<DNS-Proxy>
dns.response.ptr=.bluecoat.com
88
Chapter 3: Condition Reference
exception.id=
Tests whether the exception being returned to the client is the specified exception. It can also be used
to determine whether the exception being returned is a built-in or user-defined exception.
Built-in exceptions are handled automatically by the SG appliance but special handling can be defined
within an <Exception> layer. Special handling is most often required for user-defined exceptions.
syntax
exception.id=exception_id
where exception_id is either the name of a built-in exception of the form:
exception_id
or the name of a user defined exception in the form:
user_defined.exception_id
In addition to testing the identity of exceptions set by the exception( ) property, exception.id=
can also test for exceptions returned by other CPL gestures, such as policy_denied, returned by the
deny( ) property and policy_redirect returned by the redirect( ) action.
Example
This example illustrates how some commonly generated exceptions are caught. Appropriate subnet
and action and category definitions are assumed.
<Proxy> url.domain=partner.my_co.com/
action.partner_redirect(yes) ; action contains redirect( )
<Proxy> url.domain=internal.my_co.com/
force_deny client.address!=mysubnet
authenticate(my_realm)
<Proxy> deny.unauthorized
url.domain=internal.my_co.com/hr group=!hr;
; and other group/user restrictions ...
<Proxy> category=blocked_sites
exception(user_defined.restricted_content)
; could probably have used built in content_filter_denied
; Custom handling for some built-in exceptions
;
<Exception>
; thrown by authenticate( ) if there is a realm configuration error
exception.id=configuration_error action.config_err_alerts(yes)
; thrown by deny.unauthorized
exception.id=authorization_failed action.log_permission_failure(yes)
; thrown by deny or force_deny
exception.id=policy_denied action.log_interloper(yes)
89
Volume 10: Content Policy Language Guide
<Exception> exception.id=user_defined.restricted_content
; any policy required for this user defined exception
...
See Also
• Properties: deny( ), deny.unauthorized( ), exception( )
• Actions: authenticate( ), authenticate.force( ), redirect( )
90
Chapter 3: Condition Reference
ftp.method=
Tests FTP request methods against any of a well-known set of FTP methods. A CPL parse error is
given if an unrecognized method is specified.
• ftp.method= evaluates to true if the request method matches any of the methods specified.
• ftp.method= evaluates to NULL if the request is not an FTP protocol request.
Syntax
ftp.method=ABOR|ACCT|ALLO|APPE|CDUP|CWD|DELE|HELP|LIST|MDTM|MKD|MODE|NLST|NOOP|P
ASS|PASV|PORT|PWD|REST|RETR|RMD|RNFR|RNTO|SITE|SIZE|SMNT
|STOR|STOU|STRU|SYST|TYPE|USER|XCUP|XCWD|XMKD|XPWD|XRMD|OPEN
where:
• ftp.method= evaluates to true if the request method matches any of the methods
specified.
• It evaluates to NULL if the request is not an FTP protocol request.
See Also
• Conditions: category=, content_management=, http.method=, http.x_method=, im.method=,
server_url=, socks.method=
91
Volume 10: Content Policy Language Guide
group=
Tests if the client is authenticated, and the client belongs to the specified group. If both of these
conditions are met, the result is true. In addition, the realm= condition can be used to test whether the
user is authenticated in the specified realm. 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, consider disambiguating group tests by
combining them with a realm= test. This reduces the number of extraneous queries to authentication
services for group information that does not pertain to that realm.
Syntax
group=group_name
where:
• group_name—Name of a group in the default realm. The required form, and the name
attribute’s case-sensitivity, depends on the type of realm.
• NTLM realm: Group names are of the form Domain\groupname, where Domain may
be optional, depending on whether BCAAA or CAASNT is installed on the NT
domain controller for the domain. Names are case-insensitive.
• Local Password realm: Group names are up to 32 characters long, and underscores (_)
and alphanumerics are allowed. Names are case-sensitive.
• RADIUS realm: RADIUS does not support groups. Instead, groups in RADIUS
environments are defined by assigning users a ServiceType attribute.
• LDAP realm: Group definitions depend on the type of LDAP directory and LDAP
schema. Generally, LDAP distinguished names are used in the following form:
cn=proxyusers, ou=groups, o=companyname. Case-sensitivity depends on the realm
definition configuration.
• Certificate realm: Certificate realms provide authentication, but do not themselves
provide authorization; instead they delegate group membership decisions to their
configured authorization realm, which is either a Local Password realm or an LDAP
realm. Group definitions should conform to the appropriate standards for the
delegated authorization realm. Although the group used in policy is then a group
from the delegated realm, to achieve performance benefits, the group= test should be
preceded with a realm test for the certificate realm, not the delegated authorization
realm.
• Sequence realm: A sequence realm is a configured list of subordinate realms to which
the user credentials are offered, in the order listed. The user is considered
authenticated when the offered credentials are valid in one of the realms in the
sequence. Authorization of the user is done with respect to the subordinate realm in
which authentication occurred. Group names may be valid names in any of the
realms in the sequence, but for the group= test to evaluate to true, the group must be
valid in the realm in which the user is actually authenticated. If the group is valid in
all realms in the sequence, then the group= test must be preceded by a realm= test of
the Sequence realm; otherwise, it should be preceded by a realm= test of the
appropriate subordinate realm.
92
Chapter 3: Condition Reference
Note: When used in the <Forward> 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.
Example
; Test if user is authenticated in group all_staff and specified realm.
realm=corp group=all_staff
; This example shows sample group tests for each type of realm. It does
; this by creating a condition in CPL that treats a group of administrators in
; each realm as equivalent, granting them permission to administer the Security
; Appliance. Recall that the <Admin> layer uses a whitelist model by default.
define condition RW_Admin
realm=LocalRealm group=RWAdmin
realm=NTLMRealm group=xyz-domain\cache_admin
realm=LDAPRealm group=”cn=cache_admin, ou=groups, o=xyz”
; The RADIUSRealm uses attributes, and this can be expressed as follows:
realm=RADIUSRealm attribute.ServiceType=8
end
<admin>
client.adress=10.10.1.250/28 authenticate(LocalRealm)
client.adress=10.10.1.0/24 authenticate(NTLMRealm)
client.adress=10.10.2.0/24 authenticate(LDAPRealm)
client.adress=10.10.3.0/24 authenticate(RADIUSRealm)
<admin>
allow condition=RW_Admin admin.access=(READ||WRITE)
See Also
• Conditions: authenticated=, has_attribute.name=, http.transparent_authentication=,
realm=, user=, user.domain=, user.x509.issuer=, user.x509.serialNumber=,
user.x509.subject=
• Properties: authenticate( ), authenticate.force( ), check_authorization( ),
socks.authenticate( ), socks.authenticate.force( )
93
Volume 10: Content Policy Language Guide
has_attribute.name=
Tests if the current transaction is authenticated in an LDAP realm and if the authenticated user has the
specified LDAP attribute. If the attribute specified is not configured in the LDAP schema and yes is
used in the expression, the condition always yields false. 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, consider disambiguating has_attribute tests by
combining them with a realm= test. This reduces the number of extraneous queries to authentication
services for attribute information that does not pertain to that realm.
Important: This condition is incompatible with Novell eDirectory servers. If the name attribute is
configured in the LDAP schema, then all users are reported by the eDirectory server to
have the attribute, regardless of whether they actually do. This can cause unpredictable
results.
Syntax
has_attribute.name=yes|no
where name is an LDAP attribute. Case-sensitivity for the attribute name depends on the
realm definition in configuration.
Example
; The following policy allows users to access the proxy if they have the
; LDAP attribute ProxyUser. The attribute could have any value, even null.
; Generally this kind of policy would be established in the first proxy layer,
; and would set up either the blacklist or whitelist model, as desired.
<Proxy>
authenticate(LDAPRealm)
; Setting up a whitelist model
<Proxy>
deny has_attribute.ProxyUser=no
; Setting up a blacklist model
<Proxy>
allow has attribute.ProxyUser=yes
deny
See Also
• Conditions: attribute.name=, authenticated=, group=,
http.transparent_authentication=, realm=, user=, user.domain=
94
Chapter 3: Condition Reference
has_client=
The has_client= condition is used to test whether the current transaction has a client. This can be
used to guard conditions that depend on client identity in a <Forward> layer.
Syntax
has_client=yes|no
See Also
• Conditions: client.address=, client.protocol=, proxy.address=, proxy.card=,
proxy.port=, streaming.client=
95
Volume 10: Content Policy Language Guide
health_check=
Tests whether a transaction belongs to a health check.
This trigger tests whether the current transaction is a health check transaction or not. Optionally, the
trigger tests whether the transaction is that of a specific health check.
Syntax
health_check = yes|no|health_check_name
where: health_check_name
Name of a specific health check. When specifying a user defined health check, the prefix user.
is optional, and will be added automatically. In all other cases the complete health check
name, including its prefix, must be entered.
Example
Prevent any forwarding for a user defined health check user.upstream.
<Forward>
health_check=user.upstream forward(no)
See Also
• Conditions: is_healthy.health_check_name=
96
Chapter 3: Condition Reference
hour=
Tests if the time of day is in the specified range or an exact match. The current time is determined by
the SG appliance’s configured clock and time zone by default, although the UTC time zone can be
specified by using the form hour.utc=. The numeric pattern used to test the hour= condition contains
no whitespace.
Note: Any range of hours or exact hour includes all the minutes in the final hour. See the “Example”
section.
Syntax
hour[.utc]={first_hour]..[last_hour]|exact_hour}
where:
• first_hour—Two digits (nn) in 24-hour time format representing the first hour in a
range; for example, 09 means 9:00 a.m. If left blank, midnight (00) is assumed—exactly
00:00 a.m.
• last_hour—Two digits (nn) in 24-hour time format representing the last full hour in a
range; for example, 17 specifies 5:59 p.m. If left blank, 23 is assumed (23:59 p.m.).
• exact_time—Two digits (nn) in 24-hour time format representing an exact, full hour.
Note: To test against an inverted range, such as a range that crosses from one day into the next, the
following shorthand expression is available. While hour=(..06|19..) specifies midnight to
6:59 a.m. and 7:00 p.m. to midnight, the policy language also recognizes hour=19..06 as
equivalent.
Example
; Tests for 3:00 a.m. to 1:59 p.m. UTC.
hour.utc=03..13
; The following example restricts access to external sites during business hours.
; This rule assumes that the user has access that must be restricted.
<Proxy>
; Internal site always available, no action required
server_url.domain=xyz.com
; Restrict other sites during business hours
deny weekday=1..5 hour=9..16
; If a previous rule had denied access, then this rule could provide an exception.
97
Volume 10: Content Policy Language Guide
<Proxy>
allow server_url.domain=xyz.com ; internal site always available
allow weekday=6..7 ; unrestricted weekends
allow hour=17..8; Inverted range for outside business hours
See Also
• Conditions: date[.utc]=, day=, minute=, month=, time=, weekday=, year=
98
Chapter 3: Condition Reference
http.connect=
Tests whether an HTTP CONNECT tunnel is in use between the SG appliance and the client.
Syntax
http.connect=yes|no
Example
<Proxy>
http.connect=yes
99
Volume 10: Content Policy Language Guide
http.method=
Tests HTTP request methods against any of a common set of HTTP methods. A CPL parse error is
given if an unrecognized method is specified.
Syntax
http.method=GET|CONNECT|DELETE|HEAD|POST|PUT|TRACE|OPTIONS|TUNNEL|LINK|UNLINK
|PATCH|PROPFIND|PROPPATCH|MKCOL|COPY|MOVE|LOCK|UNLOCK|MKDIR|INDEX|RMDIR|COPY|
MOVE
where:
• http.method= evaluates to true if the request method matches any of the methods
specified.
• http.method= evaluates to NULL if the request is not an HTTP protocol request.
See Also
• Conditions: admin.access=, ftp.method=, http.x_method=, im.method=, socks.method=
• Properties: http.request.version( ), http.response.version( )
100
Chapter 3: Condition Reference
http.method.custom=
Test the HTTP protocol method versus custom values.
Syntax
http.method.custom=string
Example
This example implements the following policies:
1. Of the well-known HTTP methods only permit “GET” and “POST.”
2. Allow the custom HTTP method “MYMETHOD1” that one of our backend servers is using.
3. DENY all other HTTP methods.
<Proxy>
; 1
ALLOW http.method=(GET||POST)
; 2
ALLOW http.method.custom=MYMETHOD1
; 3
DENY
101
Volume 10: Content Policy Language Guide
http.method.regex=
Test the HTTP method using a regular expression.
Syntax
http.method.regex=regular_expression
Example
This example implements the following policy:
• DENY any HTTP method that contains a decimal number.
<Proxy>
DENY http.method.regex="[0-9]+"
102
Chapter 3: Condition Reference
http.request_line.regex=
Test the HTTP protocol request line.
Syntax
http.request_line.regex=regular_expression
Example
By default, the SG appliance allows the HTTP request line to contain leading and trailing white space.
It allows tab characters to be used in place of space characters, and it allows multiple space characters
to occur between tokens. But according to a strict interpretation of the HTTP specification, there
should be no leading or trailing white space, tabs should not be used, and only a single space should
appear between tokens.
The following policy enforces the above syntax restrictions.
<Proxy>
DENY("bad HTTP request line") \
http.request_line.regex="\t|(^ )|( $)|( )"
103
Volume 10: Content Policy Language Guide
http.request.version=
Tests the version of HTTP used by the client in making the request to the appliance.
syntax
http.request.version=0.9|1.0|1.1
See Also
• Conditions: http.response.code=, http.response.version=
• Properties: http.request.version( ), http.response.version( )
104
Chapter 3: Condition Reference
http.response.apparent_data_type=
Test the apparent type of the HTTP response data, based on examining the file header.
Syntax
http.response.apparent_data_type = executable|cabinet
where:
• executable is a test for a Windows executable file (.exe)
• cabinet is a test for a Windows cabinet file (.cab)
Example
Deny the request if the first few bytes of the response data indicate that this is probably a Windows
executable file.
<proxy>
DENY http.response.apparent_data_type = executable
105
Volume 10: Content Policy Language Guide
http.response.code=
Tests true if the current transaction is an HTTP transaction and the response code received from the
origin server is as specified.
Replaces: http.response_code
syntax
http.response.code=nnn
where nnn is a standard numeric range test with values in the range 100 to 999 inclusive.
See Also
• Conditions: http.request.version=, http.response.version=
• Properties: http.response.version( )
106
Chapter 3: Condition Reference
http.response.data=
Test the first few bytes of HTTP response data.
This trigger causes HTTP to wait until N bytes of response data have been received from the origin
server (or the end of file, whichever comes first). Then, the first N bytes of response data are compared
to the string pattern on the right side of the condition.
Syntax
http.response.data.N[StringQualifiers] = String
where:
• N equals the number of bytes, from 1..256
• StringQualifiers equal [.exact|.prefix|.suffix|.substring|.regex][.case_sensitive]
Example
Deny the request if the first 2 bytes of the response data indicate that this is probably a Windows
executable file.
<proxy>
DENY http.response.data.2.case_sensitive = "MZ"
107
Volume 10: Content Policy Language Guide
http.response.version=
Tests the version of HTTP used by the origin server to deliver the response to the SG appliance.
Syntax
http.response.version=0.9|1.0|1.1
See Also
• Conditions: http.request.version=, http.response.code=
• Properties: http.response.version( )
108
Chapter 3: Condition Reference
http.transparent_authentication=
This condition evaluates to true if HTTP uses transparent proxy authentication for this request.
The condition can be used with the authenticate( ) or authenticate.force( ) properties to select
an authentication realm.
Syntax
http.transparent_authentication=yes|no
See Also
• Conditions: attribute.name=, authenticated=, group=, has_attribute.name=, realm=, user=,
user.domain=
• Properties: authenticate( ), authenticate.force( ), authenticate.mode( ),
check_authorization( )
109
Volume 10: Content Policy Language Guide
http.x_method=
Tests HTTP request methods against any uncommon HTTP methods.
This condition has been deprecated in favor of "http.method.custom=" on page 101.
110
Chapter 3: Condition Reference
icap_error_code=
Test which ICAP error occurred. Note that rules containing this trigger will not match for a transaction
that does not involve ICAP scanning.
Syntax
any|none|<ICAP_error>
where:
<ICAP_error> is one of none, scan_timeout, decode_error, password_protected,
insufficient_space, max_file_size_exceeded, max_total_size_exceeded,
max_total_files_exceeded, file_extension_blocked, antivirus_load_failure,
antivirus_license_expired, antivirus_engine_error, connection_failure,
request_timeout, internal_error, server_error, server_unavailable.
Example
In this example, the administrator has chosen to allow access to files that fail scanning because of
password protection. Note that the scanning property must use the optional fail_open setting, and
that the rules must also allow an error code of none. Note as well that the example assumes a
user-defined exception page named virus_scan_failure.
<Proxy>
response.icap_service(virus_scan, fail_open)
<Proxy>
icap_error_code=!(none, password_protected) exception(virus_scan_failure)
111
Volume 10: Content Policy Language Guide
is_healthy.health_check_name=
Tests whether a health check is reporting as healthy.
Syntax
is_healthy.health_check_name = yes|no
where: health_check_name
Name of a specific health check. When specifying a user defined health check, the prefix user.
is optional, and will be added automatically. In all other cases the complete health check
name, including its prefix, must be entered.
Example
Consider a user defined health check user.upstream set up to test access to the Internet while using a
forwarding proxy named internet_main. This could be a composite health check testing several
Internet sites. In this example, when Internet access fails then all traffic is directed to use a different
forwarding proxy called internet_backup.
The health check must continue to evaluate the Internet access using internet_main. This requires the
health check transaction be identified and consistently routed. Otherwise, the health check will
oscillate between using the two proxies.
<Forward>
; Normally forward through 'internet_main'.
is_healthy.user.upstream=yes forward(internet_main)
; Health check must use 'internet_main'.
health_check=user.upstream forward(internet_main)
; Otherwise, use the backup.
forward(internet_backup)
See Also
• Conditions: health_check=
112
Chapter 3: Condition Reference
im.buddy_id=
Tests the buddy_id associated with the instant messaging transaction.
Syntax
im.buddy_id[.exact][.case_sensitive]=string
im.buddy_id.prefix[.case_sensitive]=string
im.buddy_id.substring[.case_sensitive]=string
im.buddy_id.suffix[.case_sensitive]=string
im.buddy_id.regex[.case_sensitive]=regular_expression
where:
• user_id_string—An exact match of the complete instant messaging buddy name.
• substring . . . substring—Specifies a substring of an instant messaging buddy name.
• regex . . . ”expr”—Takes a regular expression.
Notes
• By default the test is case-insensitive. Specifying .case_sensitive makes the test case-sensitive.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.chat_room.conference=, im.chat_room.id=, im.chat_room.invite_only=,
im.chat_room.type=, im.chat_room.member=, im.chat_room.voice_enabled=,
im.file.extension=, im.file.name=, im.file.path=, im.file.size=, im.message.route=,
im.message.size=, im.message.text=, im.message.type=, im.method=, im.user_id=
• Properties: im.strip_attachments( )
113
Volume 10: Content Policy Language Guide
im.chat_room.conference=
Tests whether the chat room associated with the instant messaging transaction has the conference
attribute set.
Syntax
im.chat_room.conference=yes|no
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.id=, im.chat_room.invite_only=,
im.chat_room.type=, im.chat_room.member=, im.chat_room.voice_enabled=,
im.file.extension=, im.file.name=, im.file.path=, im.file.size=, im.message.route=,
im.message.size=, im.message.text=, im.message.type=, im.method=, im.user_id=
• Properties: im.strip_attachments( )
114
Chapter 3: Condition Reference
im.chat_room.id=
Tests the chat room ID associated with the instant messaging transaction.
Syntax
im.chat_room.id[.exact][.case_sensitive]=string
im.chat_room.id.prefix[.case_sensitive]=string
im.chat_room.id.substring[.case_sensitive]=string
im.chat_room.id.suffix[.case_sensitive]=string
im.chat_room.id.regex[.case_sensitive]=regular_expression
where:
❐ user_id_string—An exact match of the complete chat room ID.
Notes
AOL and Yahoo add additional information to the ID displayed to users. Since the default test is an
exact match, the additional information will cause a match on the displayed ID to fail. Instead, use a
substring or regex match for these services. MSN chat room IDs can be tested with an exact match.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.invite_only=,
im.chat_room.type=, im.chat_room.member=, im.chat_room.voice_enabled=,
im.file.extension=, im.file.name=, im.file.path=, im.file.size=, im.message.route=,
im.message.size=, im.message.text=, im.message.type=, im.method=, im.user_id=
• Properties: im.strip_attachments( )
115
Volume 10: Content Policy Language Guide
im.chat_room.invite_only=
Tests whether the chat room associated with the instant messaging transaction has the invite_only
attribute set.
Syntax
im.chat_room.invite_only=yes|no
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.type=, im.chat_room.member=, im.chat_room.voice_enabled=,
im.file.extension=, im.file.name=, im.file.path=, im.file.size=, im.message.route=,
im.message.size=, im.message.text=, im.message.type=, im.method=, im.user_id=
• Properties: im.strip_attachments( )
116
Chapter 3: Condition Reference
im.chat_room.type=
Tests whether the chat room associated with the transaction is public or private.
Syntax
im.chat_room.type=public|private
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.member=, im.chat_room.voice_enabled=,
im.file.extension=, im.file.name=, im.file.path=, im.file.size=, im.message.route=,
im.message.size=, im.message.text=, im.message.type=, im.method=, im.user_id=
• Properties: im.strip_attachments( )
117
Volume 10: Content Policy Language Guide
im.chat_room.member=
Tests whether the chat room associated with the instant messaging transaction has a member
matching the specified criterion.
Syntax
im.chat_room.member[.exact][.case_sensitive]=string
im.chat_room.member.prefix[.case_sensitive]=string
im.chat_room.member.substring[.case_sensitive]=string
im.chat_room.member.suffix[.case_sensitive]=string
im.chat_room.member.regex[.case_sensitive]=regular_expression
where:
❐ string—An exact match of the complete instant messaging buddy ID.
❐ substring . . . substring—Specifies a substring of the instant messaging buddy ID.
Notes
By default the test is case-insensitive. Specifying .case_sensitive makes the test case-sensitive.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.voice_enabled=,
im.file.extension=, im.file.name=, im.file.path=, im.file.size=, im.message.route=,
im.message.size=, im.message.text=, im.message.type=, im.method=, im.user_id=
• Properties: im.strip_attachments( )
118
Chapter 3: Condition Reference
im.chat_room.voice_enabled=
Tests whether the chat room associated with the instant messaging transaction is voice enabled.
Syntax
im.chat_room.voice_enabled=yes|no
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.file.extension=, im.file.name=, im.file.path=, im.file.size=, im.message.route=,
im.message.size=, im.message.text=, im.message.type=, im.method=, im.user_id=
• Properties: im.strip_attachments( )
119
Volume 10: Content Policy Language Guide
im.client=
Test the type of IM client in use
Syntax
im.client=yes|no|aol-im|msn-im|yahoo-im
Example
This example implements the following policies:
1. Turn on reflection for all MSN Instant Messaging traffic.
2. DENY all Yahoo Instant Messaging traffic.
<Proxy>
; 1
im.client=msn-im im.reflect(yes)
; 2
DENY im.client=yahoo-im
120
Chapter 3: Condition Reference
im.file.extension=
Tests the file extension of a file associated with an instant messaging transaction. The leading '.' of the
file extension is optional. Only supports an exact match.
Syntax
im.file.extension[.case_sensitive]=[.]filename_extension
Notes
By default the test is case-insensitive. Specifying .case_sensitive makes the test case-sensitive.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.name=, im.file.path=, im.file.size=,
im.message.route=, im.message.size=, im.message.text=, im.message.type=, im.method=,
im.user_id=
• Properties: im.strip_attachments( )
121
Volume 10: Content Policy Language Guide
im.file.name=
Tests the file name (the last component of the path), including the extension, of a file associated with
an instant messaging transaction.
Syntax
im.file.name[.exact][.case_sensitive]=string
im.file.name.prefix[.case_sensitive]=string
im.file.name.substring[.case_sensitive]=string
im.file.name.suffix[.case_sensitive]=string
im.file.name.regex[.case_sensitive]=regular_expression
where:
❐ string—An exact match of the complete file name with extension.
❐ prefix . . . prefix_string—Specifies a prefix match.
Notes
For a SEND file request, and an exact match can be used. For a RECEIVE file request, path information
is included and an exact match will not work. Instead use a substring or regex test to match both
SEND and RECEIVE file requests.
See Also
• Actions: append( ), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.path=, im.file.size=,
im.message.route=, im.message.size=, im.message.text=, im.message.type=, im.method=,
im.user_id=
• Properties: im.strip_attachments( )
122
Chapter 3: Condition Reference
im.file.path=
Tests the file path of a file associated with an instant messaging transaction against the specified
criterion.
Syntax
im.file.path[.exact][.case_sensitive]=string
im.file.path.prefix[.case_sensitive]=string
im.file.path.substring[.case_sensitive]=string
im.file.path.suffix[.case_sensitive]=string
im.file.path.regex[.case_sensitive]=regular_expression
where:
❐ string—An exact match of the complete path.
Notes
• This test will not match SEND file requests since only the file name is sent in this request.
• For AOL, the .exact and .prefix forms of this test will not match RECEIVE file requests due to
control characters embedded in the path included with the request. Instead, use the .regex or
.substring forms.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.name=, im.file.size=,
im.message.route=, im.message.size=, im.message.text=, im.message.type=, im.method=,
im.user_id=
• Properties: im.strip_attachments( )
123
Volume 10: Content Policy Language Guide
im.file.size=
Performs a signed 64-bit range test of the size of a file associated with an instant messaging
transaction.
Syntax
im.file.size=[min]..[max]
The default minimum value is zero (0); there is no default maximum value.
Notes
For AOL, the IM file list is also considered to be a file and can be matched by this condition. The
im.message_type= condition can be used to distinguish these cases using the values file and list.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.name=, im.file.path=,
im.message.route=, im.message.size=, im.message.text=, im.message.type=, im.method=,
im.user_id=
• Properties: im.strip_attachments( )
124
Chapter 3: Condition Reference
im.message.opcode=
Tests the value of an opcode associated with an instant messaging transaction whose im.method is
send_unknown or receive_unknown.
Note: Generally, this is used with deny( ) to restrict interactions that are new to one of the
supported instant messaging protocols and for which direct policy control is not yet available.
Use of this condition requires specific values for the opcode as determined by Blue Coat
technical support.
Syntax
im.message.opcode=string
where string is a value specified by technical support.
125
Volume 10: Content Policy Language Guide
im.message.reflected=
Test whether IM reflection occurred
Syntax
im.message.reflected=yes|no|failed
Example
This example implements the following policies:
1. Turn on reflection for all MSN Instant Messaging.
2. DENY all traffic this is not reflected.
<Proxy>
; 1
im.client=msn-im im.reflect(yes)
<Proxy>
; 2 -- NOTE: This has the side effect of denying any IM traffic
; where reflection was not attempted, but that is desirable
; according to the above policy
DENY im.message.reflected=failed||no
126
Chapter 3: Condition Reference
im.message.route=
Tests how the instant messaging message reaches its recipients.
Syntax
im.message.route=service|direct|chat
where:
• service—The message is relayed through the IM service.
• direct—The message is sent directly to the recipient.
• chat—The message is sent to a chat room (includes conferences).
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.name=, im.file.path=,
im.file.size=, im.message.size=, im.message.text=, im.message.type=, im.method=,
im.user_id=
• Properties: im.strip_attachments( )
127
Volume 10: Content Policy Language Guide
im.message.size=
Performs a signed 64-bit range test on the size of the instant messaging message.
Syntax
im.message.size=[min]..[max}
The default minimum value is zero (0); there is no default maximum value.
Note
For AOL, all IM messages are wrapped with HTML tags. When using this trigger for AOL, allow for
the additional bytes required when determining the range values.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.name=, im.file.path=,
im.file.size=, im.message.route=, im.message.text=, im.message.type=, im.method=,
im.user_id=
• Properties: im.strip_attachments( )
128
Chapter 3: Condition Reference
im.message.text=
Tests if the message text contains the specified text or pattern.
Note: The .regex version of this test is limited to the first 8K of the message. The .substring
version of the test does not have this restriction.
Syntax
im.message.text.substring[.case_sensitive]=substring
im.message.text.regex[.case_sensitive]=expr
where:
• substring . . . substring—Specifies a substring match of the message text.
• regex . . . ”expr”—Takes a regular expression.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.name=, im.file.path=,
im.file.size=, im.message.route=, im.message.size=, im.message.type=, im.method=,
im.user_id=
• Properties: im.strip_attachments( )
129
Volume 10: Content Policy Language Guide
im.message.type=
Tests the message type of an instant messaging transaction.
Syntax
im.message.type=text|invite|voice_invite|file|file_list|application
where:
• text—Normal IM text message.
• invite—An invitation to a chat room or to communicate directly.
• voice_invite—Invitation to a voice chat.
• file—The message contains a file.
• file_list—The message contains a list of exported files.
• application—Tests if this instant messaging request was generated internally by the
instant messaging application, rather than as a direct result of a user gesture.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.name=, im.file.path=,
im.file.size=, im.message.route=, im.message.size=, im.message.text=, im.method=,
im.user_id=
• Properties: im.strip_attachments( )
130
Chapter 3: Condition Reference
im.method=
Tests the method associated with the instant messaging transaction.
Syntax
im.method=open|create|join|join_user|login|logout|notify_join|notify_quit|
notify_state|quit|receive|send|set_state
Notes
Some methods can be used for logging purposes only. These include: notify_join, notify_quit,
notify_state, and set_state.
See Also
• Actions: append(), im.alert( ), set( )
• Conditions: ftp.method=, http.method=, http.x_method=, socks.method=
• IM Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.name=, im.file.path=,
im.file.size=, im.message.route=, im.message.size=, im.message.text=,
im.message.type=, im.user_id=
• Properties: im.strip_attachments( )
131
Volume 10: Content Policy Language Guide
im.user_agent=
Test the user agent string provided by the IM client.
Syntax
im.user_agent=string
im.user_agent.exact=string
im.user_agent.prefix=string
im.user_agent.substring=string
im.user_agent.suffix=string
Example
This example implements the following policies:
1. ALLOW only clients from AOL to connect to the AOL IM service
2. DENY all SameTime IM clients
3. DENY all IM clients that report a version of "5.5.3572"
<Proxy>
ALLOW
; 1.
<Proxy> client.protocol=aol-im
ALLOW im.user_agent.prefix="AOL"
DENY
<Proxy>
; 2.
DENY im.user_agent="Sametime Aim client"
; 3.
DENY im.user_agent.substring="5.5.3572"
132
Chapter 3: Condition Reference
im.user_id=
Tests the user_id associated with the instant messaging transaction.
Syntax
im.user_id[.exact][.case_sensitive]=string
im.user_id.prefix[.case_sensitive]=string
im.user_id.substring[.case_sensitive]=string
im.user_id.suffix[.case_sensitive]=string
im.user_id.regex[.case_sensitive]=regular_expression
where:
❐ user_id_string—An exact match of the complete instant messaging username.
Notes
By default the test is case-insensitive. Specifying .case_sensitive makes the test case-sensitive.
See Also
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.name=, im.file.path=,
im.file.size=, im.message.route=, im.message.size=, im.message.text=,
im.message.type=, im.method=
• Properties: im.strip_attachments( )
• Actions: append( ), im.alert( ), set( )
133
Volume 10: Content Policy Language Guide
live=
Tests if the streaming content is a live stream.
Syntax
live=yes|no
Example
; The following policy restricts access to live streams during morning hours.
; In this example, we use a policy layer to define policy just for the live streams.
; This example uses the restrict form and integrates with other <Proxy> layers.
<Proxy>
deny live=yes time=1200..0800 ; Policy for live streams
See Also
• Conditions: bitrate=, streaming.client=, streaming.content=
• Properties: access_server( ), max_bitrate( ), streaming.transport( )
134
Chapter 3: Condition Reference
minute=
Tests if the minute of the hour is in the specified range or an exact match. By default, the SG appliance
appliance’s clock and time zone are used to determine the current minute. To specify the UTC time
zone, use the form minute.utc=. The numeric pattern used to test the minute condition can contain
no whitespace.
Syntax
minute[.utc]={[first_minute]..[last_minute]|exact_minute}
where:
• first_minute—An integer from 0 to 59, indicating the first minute of the hour that tests
true. If left blank, minute 0 is assumed.
• last_minute—An integer from 0 to 59, indicating the last minute of the hour that tests
true. If left blank, minute 59 is assumed.
• exact_minute—An integer from 0 to 59, indicating the minute of each hour that tests
true.
Note: To test against an inverted range, such as a range that crosses from one hour into the next, the
following shorthand expression is available. While minute=(..14|44..) specifies the first 15
minutes and last 15 minutes of each hour, the policy language also recognizes
minute=44..14 as equivalent.
Example
; Tests for the first 5 minutes of every hour.
minute=0..4
See Also
• Conditions: date[.utc]=, day=, hour=, month=, time=, weekday=, year=
135
Volume 10: Content Policy Language Guide
month=
Tests if the month is in the specified range or an exact match. By default, the SG appliance’s date and
time zone are used to determine the current month. To specify the UTC time zone, use the form
month.utc=. The numeric pattern used to test the month condition can contain no whitespace.
Syntax
month[.utc]={[first_month]..[last_month]|exact_month}
where:
• first_month—An integer from 1 to 12, where 1 specifies January and 12 specifies
December, specifying the first month that tests true. If left blank, January (month 1) is
assumed.
• last_month—An integer from 1 to 12, where 1 specifies January and 12 specifies
December, specifying the last month that tests true. If left blank, December (month 12) is
assumed.
• exact_month—An integer from 1 to 12, where 1 specifies January and 12 specifies
December, indicating the month that tests true.
Note: To test against an inverted range, such as a range that crosses from one year into the next, the
following shorthand expression is available. While month=(..6|9..) specifies September
through June, the policy language also recognizes month=9..6 as equivalent.
Example
; Tests for the year-end holiday season.
define condition year_end_holidays
month=12 day=25..
month=1 day=1
end_condition year_end_holidays
See Also
• Conditions: date[.utc]=, day=, hour=, minute=, time=, weekday=, year=
136
Chapter 3: Condition Reference
proxy.address=
Tests the destination address of the arriving IP packet. The expression can include an IP address or
subnet, or the label of a subnet definition block.
If the transaction was explicitly proxied, then proxy.address= tests the IP address the client used to
reach the proxy, which is either the IP address of the NIC on which the request arrived or a virtual IP
address. This is intended for situations where the proxy has a range of virtual IP address; you can use
proxy.address= to test which virtual IP address was used to reach the proxy.
If the transaction was transparently proxied, then proxy.address= tests the destination address
contained in the IP packet. Note that this test may not be equivalent to testing the
server_url.address. The server_url.address and proxy.address conditions test different
addresses in the case where a proxied request is transparently intercepted: server_url.address=
contains the address of the origin server, and proxy.address= contains the address of the upstream
proxy through which the request is to be handled.
Syntax
proxy.address=ip_address|subnet|subnet_label
where:
• ip_address—NIC IP address or subnet; for example, 10.1.198.54.
• subnet—A subnet mask; for example, 10.1.198.0/24
• subnet_label—Label of a subnet definition block that binds a number of IP addresses or
subnets.
Example
; Service should be denied through proxy within the subnet 1.2.3.x.
<Proxy>
proxy.address=1.2.3.0/24 deny
See Also
• Conditions: client.address=, client.protocol=, proxy.card=, proxy.port=
• Definitions: define subnet
137
Volume 10: Content Policy Language Guide
proxy.card=
Tests the ordinal number of the network interface card (NIC) used by a request.
Syntax
proxy.card=card_number
where card_number is an integer that reflects the installation order.
Example
; Deny all incoming traffic through proxy card 0.
<Proxy>
proxy.card=0 deny
See Also
• Conditions: client.address=, client.protocol=, proxy.address=, proxy.port=
138
Chapter 3: Condition Reference
proxy.port=
Tests if the IP port used by a request is within the specified range or an exact match.The numeric
pattern used to test the proxy.port= condition can contain no whitespace.
If the transaction was explicitly proxied, then this tests the IP port that the client used to reach the
proxy. The pattern is a number between 1 and 65535 or a numeric range.
If the transaction was transparently proxied, however, then proxy.port= tests which port the client
thinks it is connecting to on the upstream proxy device or origin server. If the client thinks it is
connecting directly to the origin server, but is transparently proxied, and if the port number specified
by the client in the request URL is not inconsistent or falsified, then proxy.port= and
server_url.port= are testing the same value.
Note: Since the SG appliance default configuration passes through tunneled traffic, some changes
must be made to begin transparent port monitoring. Only proxy ports that have been
configured and enabled can be tested using the proxy.port= condition. For example, if the
transparent FTP service, on port 21, is either not configured or not enabled, a policy rule that
includes proxy.port=21 has no effect.
Syntax
proxy.port={[low_port_number]..[high_port_number]|exact_port_number}
where:
• low_port_number—A port number at the low end of the range to be tested. Can be a
number between 1 and 65535.
• high_port_number—A port number at the high end of the range to be tested. Can be a
number between 1 and 65535.
• exact_port_number—A single port number; for example, 80. Can be a number between
1 and 65535.
Example
; Deny URL through the default proxy port.
<Proxy>
url=http://www.example.com proxy.port=8080 deny
See Also
• Conditions: client.address=, client.protocol=, proxy.address=, proxy.card=,
proxy.port=, server_url.port=
139
Volume 10: Content Policy Language Guide
p2p.client=
Test the type of Peer-to-Peer client in use.
Syntax
p2p.client=yes|no|bittorrent|edonkey|fasttrack|gnutella
Example
<Proxy>
p2p.client=gnutella
140
Chapter 3: Condition Reference
raw_url.regex=
Test the value of the raw request URL.
The raw_url= condition is the request URL without any normalizations applied. The SG appliance
normalizes URLs in order to better enforce policy. However, there are instances where testing the raw
form is desirable, such as using CPL to detect that a URL contained the signature of an exploit that was
removed during normalization.
Syntax
raw_url.regex=regular_expression
Example
• Reject request as invalid if URL encodes letters and digits using hex escape sequences. Rationale:
this might be an attempt to evade content filtering policy.
<Proxy>
exception(invalid_request) \
raw_url.regex="\%(3[0-9]|[46][1-9a-fA-F]|[57][0-9aA])"
141
Volume 10: Content Policy Language Guide
raw_url.host.regex=
Test the value of the host component of the raw request URL.
The raw_url.host= condition is the original character string used to specify the host in the HTTP
request. It is different from the url.host= string because the following normalizations are not
applied:
• Conversion to lower case. For example, "WWW.SomeDomain.COM" -> "www.somedomain.com".
• Trailing dot is stripped from domain name. For example, "www.example.com." ->
"www.example.com".
• IP addresses in non-standard form are converted to a decimal dotted quad. For example,
"0xA.012.2570" -> "10.10.10.10".
Syntax
raw_url.host.regex=regular_expression
Example
• Reject request as invalid if host is an IP address in non-standard form.
<Proxy>
exception(invalid_request) \
url.host.is_numeric=yes \
raw_url.host.regex=("(^|\.)0[^.]" || !"\..*\..*\.")
142
Chapter 3: Condition Reference
raw_url.path.regex=
Test the value of the path component of the raw request URL.
The raw_url.path.regex= condition tests the original character string used to specify the path in the
HTTP request. It is different from the url.path.regex= condition because the following
normalizations are not applied:
• If path and query are both missing, the path is set to "/". For example, "http://abc.com" ->
"http://abc.com/".
• Double slashes in the path are normalized to single slashes. For example,
"http://abc.com/a//b.gif" -> "http://abc.com/a/b.gif".
• The path components "." and ".." are removed. For example, "http://abc.com/a/./b.gif" ->
"http://abc.com/a/b.gif" and "http://abc.com/a/../b.gif" -> "http://abc.com/b.gif".
• Unnecessary % escape sequences are replaced by the characters they encode. For example,
"http://abc.com/%64%65%66.gif" -> "http://abc.com/def.gif".
Syntax
raw_url.path.regex=regular_expression
Example
• Reject request as invalid if path encodes letters and digits using hex escape sequences. Rationale:
this might be an attempt to evade content filtering policy.
<Proxy>
exception(invalid_request) \
raw_url.path.regex="\%(3[0-9]|[46][1-9a-fA-F]|[57][0-9aA])"
143
Volume 10: Content Policy Language Guide
raw_url.pathquery.regex=
Test the value of the path and query component of the raw request URL.
The raw_url.pathquery.regex= condition tests the original character string used to specify the path
and query in the HTTP request. It is different from the path and query tested by the url.regex=
condition because the following normalizations are not applied:
• If path and query are both missing, the path is set to "/". For example, "http://abc.com" ->
"http://abc.com/".
• Double slashes in the path are normalized to single slashes. For example,
"http://abc.com/a//b.gif" -> "http://abc.com/a/b.gif".
• The path components "." and ".." are removed. For example, "http://abc.com/a/./b.gif" ->
"http://abc.com/a/b.gif" and "http://abc.com/a/../b.gif" -> "http://abc.com/b.gif".
• Unnecessary % escape sequences are replaced by the characters they encode. For example,
"http://abc.com/%64%65%66.gif" -> "http://abc.com/def.gif".
Syntax
raw_url.pathquery.regex=regular_expression
Example
• Reject request as invalid if pathquery encodes letters and digits using hex escape sequences.
Rationale: this might be an attempt to evade content filtering policy.
<Proxy>
exception(invalid_request) \
raw_url.pathquery.regex="\%(3[0-9]|[46][1-9a-fA-F]|[57][0-9aA])"
144
Chapter 3: Condition Reference
raw_url.port.regex=
Test the value of the port' component of the raw request URL.
The raw_url.port= condition is the original character string used to specify the port in the HTTP
request. It is different from the url.port= condition because it is a string, not an integer, and because
of the following:
• Leading zeroes are not removed. Thus, raw_url.port.regex="^0" is true if there are leading
zeroes.
• If the port is specified as a naked colon, with no following port number, then the string is the
empty string, and raw_url.port.regex="^$" will be true.
If no port is specified, then no regex will match, and raw_url.port.regex=!"" will be true.
Syntax
raw_url.port.regex=regular_expression
Example
• Reject request as invalid if port specifier is a naked colon or has leading zeroes.
<Proxy>
exception(invalid_request) raw_url.port.regex=("^$" || "^0")
145
Volume 10: Content Policy Language Guide
raw_url.query.regex=
raw_url.query.regex tests the original character string used to specify the query in the HTTP
request. It is different from url.query.regex because the following normalization is not applied:
Unnecessary % escape sequences are replaced by the characters they encode. For example,
"http://abc.com/search?q=%64%65%66" -> "http://abc.com/search?q=def".
Syntax
raw_url.query.regex=regular_expression
Example
• Reject request as invalid if query encodes letters and digits using hex escape sequences. Rationale:
this might be an attempt to evade content filtering policy.
<Proxy>
exception(invalid_request) \
raw_url.query.regex="\%(3[0-9]|[46][1-9a-fA-F]|[57][0-9aA])"
146
Chapter 3: Condition Reference
realm=
Tests if the client is authenticated and if the client has logged into the specified realm. If both of these
conditions are met, the response is true. In addition, the group= condition can be used to test whether
the user belongs to the specified group. This condition is unavailable if the current transaction is not
authenticated (for example, the authenticate property is set to no).
If you reference more than one realm in your policy, consider disambiguating user, group and
attribute tests by combining them with a realm=test. This reduces the number of extraneous queries
to authentication services for group, user or attribute information that does not pertain to that realm.
Note: When used in the <Forward> layer, authentication conditions 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.
Syntax
realm=realm_name
where realm_name is the name of an NTLM, Local Password, RADIUS, LDAP, Certificate, or
Sequence realm. Realm names are case-insensitive for all realm types.
Example
; This example tests if the user has logged into realm corp and
; is authenticated in the specified group.
realm=corp group=all_staff
; This example uses the realm property to distinguish the policy applied
; to two groups of users--corp’s employees, and their corporate partners and
; clients. These two groups will authenticate in different realms.
<Proxy>
client.address=10.10.10/24 authenticate(corp)
; The corporate realm authenticate(client) ; Company partners & clients
<Proxy> realm=corp ; Rules for corp employees
allow url.domain=corp.com ; Unrestricted internal access
category=(violence, gambling) exception(content_filter_denied)
<Proxy> realm=client ; Rules for business partners & clients
allow group=partners url=corp.com/partners ; Restricted to partners
allow group=(partners, clients) url=corp.com/clients ; Both groups allowed
deny
; Additional layers would continue to be guarded with the realm, so that only
; the ‘client’ realm would be queried about the ‘partners’ and ‘clients’ groups.
147
Volume 10: Content Policy Language Guide
See Also
• Conditions: authenticated=, group=, has_attribute.name=,
http.transparent_authentication=, user=, user.domain=, user.x509.issuer=,
user.x509.serialNumber=, user.x509.subject=
• Properties: authenticate( ), authenticate.force( ), check_authorization( )
148
Chapter 3: Condition Reference
release.id=
Tests the release ID of the SG appliance software. The release ID of the SG appliance software currently
running is displayed on the main page of the Management Console and in the Maintenance > Upgrade
> Systems tab of the Management Console. It also can be displayed through the CLI using the show
version command.
Syntax
release.id=number
where number is a five-digit number that increases with each new release of the SG appliance.
Example
; the condition below is only true if you are running a version of SG appliance
; whose release id is 18000 or later
release.id=18000..
See Also
• Conditions: release.version=
149
Volume 10: Content Policy Language Guide
release.version=
Tests the release version of the SG appliance software. The release version of the SG appliance
software currently running is displayed on the main page of the Management Console and in the
Management>Maintenance>Upgrade>Systems tab of the Management Console. It also can be displayed
through the CLI using the show version command.
Syntax
release.version={[minimum_version]..[maximum_version]|version}
where each of the versions is of the format:.
major_#.minor_#.dot_#.patch_#
Each number must be in the range 0 to 255. The major_# is required; less significant portions
of the version may be omitted and will default to 0.
Example
; the condition below is only true if you are running a version of SG appliance
; whose release version is 3.1.
release.version=3.1..
; the condition below is only true if you are running a version of SG appliance
; whose release version is less or equal to than 3.1.2
release.version=..3.1.2
150
Chapter 3: Condition Reference
request.header.header_name=
Tests the specified request header (header_name) against a regular expression. Any recognized HTTP
request header can be tested. For custom headers, use request.x_header.header_name= instead. For
streaming requests, only the User-Agent header is available.
Syntax
request.header.header_name=regular_expression
where:
• header_name—A recognized HTTP header. For a complete list of recognized headers, see
Appendix C: "Recognized HTTP Headers".
• regular_expression—A regular expression. For more information, see Appendix E:
"Using Regular Expressions".
Example
;deny access when request is sent with Pragma-no-cache header
<Proxy>
deny url=http://www.bluecoat.com request.header.Pragma=”no-cache”
See Also
• Actions: append( ), delete( ), delete_matching( ), rewrite( ), set( )
• Conditions: request.header.header_name.address=, request.x_header.header_name=,
response.header.header_name=
151
Volume 10: Content Policy Language Guide
request.header.header_name.address=
Tests if the specified request header can be parsed as an IP address; otherwise, false. If parsing
succeeds, then the IP address extracted from the header is tested against the specified IP address. The
expression can include an IP address or subnet, or the label of a subnet definition block. This condition
can only be used with the client-ip and X-Forwarded-For headers.
Syntax
request.header.header_name.address=ip_address|subnet|subnet_label
where:
• header_name—client-ip and X-Forwarded-For.
• ip_address—IP address; for example, 10.1.198.46.
Example
; In this example, we assume that there is a downstream SG appliance that
; identifies client traffic by putting the client’s IP address in a request
; header.
; Here we’ll deny access to some clients, based on the header value.
<Proxy>
; Netscape’s convention is to use the Client-IP header
deny request.header.Client-IP.address=10.1.198.0/24 ; the subnet
; Blue Coat’s convention is to use the extended header:
deny request.header.X-Forwarded-For.address=10.1.198.12
See Also
• Actions: append( ), delete( ), delete_matching( ), rewrite( ), set( )
• Conditions: request.header.header_name=, response.header.header_name=,
response.x_header.header_name=
• Definitions: define subnet
152
Chapter 3: Condition Reference
request.header.header_name.count=
Test the number of header values in the request for the given header_name.
Syntax
request.header.header_name.count=numeric range from 0 to 8192
Example
• Deny abnormal HTTP requests with 2 or more host headers.
<Proxy>
DENY("Too many Host headers") request.header.Host.count = 2..
153
Volume 10: Content Policy Language Guide
request.header.header_name.length=
Test the total length of the header values for the given header_name.
Syntax
request.header.header_name.length=numeric range from 0 to 8192
Example
• Deny HTTP requests with more than 2K of cookie data.
<Proxy>
DENY("Too much Cookie data") request.header.Cookie.length = 2048..
154
Chapter 3: Condition Reference
request.header.Referer.url=
Test if the URL specified by the Referer header matches the specified criteria. The basic
request.header.Referer.url= test attempts to match the complete Referer URL against a
specified pattern. The pattern may include the scheme, host, port, path and query components of the
URL. If any of these is not included in the pattern, then the corresponding component of the URL is
not tested and can have any value.
Specific portions of the Referer URL can be tested by applying URL component modifiers to the
condition. In addition to component modifiers, optional test type modifiers can be used to change the
way the pattern is matched.
This condition is unavailable if the Referer header is missing, or if its value cannot be parsed as a URL.
If the Referer header contains a relative URL, the requested URL is used as a base to form an absolute
URL prior to testing.
Syntax
request.header.Referer.url[.case_sensitive][.no_lookup]=prefix_pattern
request.header.Referer.url.domain[.case_sensitive][.no_lookup]=
domain_suffix_pattern
request.header.Referer.url.exact=string
request.header.Referer.url.prefix=string
request.header.Referer.url.substring=string
request.header.Referer.url.suffix=string
request.header.Referer.url.regex=regular_expression
request.header.Referer.url.address=ip_address|subnet|subnet_label
request.header.Referer.url.extension[.case_sensitive]=[.]filename_extension
request.header.Referer.url.host[.exact]=host
request.header.Referer.url.host.[prefix|substring|suffix]=string
request.header.Referer.url.host.is_numeric=yes|no
request.header.Referer.url.host.no_name=yes|no
request.header.Referer.url.path[.case_sensitive]=/string
request.header.Referer.url.path[.substring|.suffix][.case_sensitive]=string
request.header.Referer.url.path.regex[.case_sensitive]=regular_expression
request.header.Referer.url.port={[low_port_number]..[high_port_number]
|exact_port_number}
request.header.Referer.url.query.regex[.case_sensitive]=regular_expression
request.header.Referer.url.scheme=url_scheme
request.header.Referer.url.host.has_name=yes|no|restricted|refused|nxdomain \
|error
request.header.Referer.url.is_absolute=yes|no
where all options are identical to url=, except for the URL being tested. For more information,
see "url=" on page 186.
Discussion
The request.header.Referer.url= condition is identical to url=, except for the lack of a define
url condition and [url] or [url.domain] sections.
155
Volume 10: Content Policy Language Guide
Example
; Test if the Referer URL includes this pattern, and block access.
; Relative URLs, such as docs subdirectories and pages, will match.
deny request.header.Referer.url=http://www.example.com/docs
; Test if the Referer URL host’s IP address is a match.
request.header.Referer.url.address=10.1.198.0
; Test whether the Referer URL includes company.com as domain.
request.header.Referer.url.domain=company.com
; Test whether the Referer URL includes .com.
request.header.Referer.url.domain=.com
; Test if the Referer URL includes this domain-suffix pattern,
; and block service. Relative URLs, such as docs
; subdirectories and pages, will match.
deny request.header.Referer.url.domain=company.com/docs
; examples of the use of request.header.Referer.url.extension=
request.header.Referer.url.extension=.txt
request.header.Referer.url.extension=(.htm, .html)
request.header.Referer.url.extension=(img, jpg, jpeg)
; This example matches the first Referer header value and doesn’t match the second
; from the following two requests:
; 1) Referer: http://1.2.3.4/test
; 2) Referer: http://www.example.com
<Proxy>
request.header.Referer.url.host.is_numeric=yes
; In the example below we assume that 1.2.3.4 is the IP of the host mycompany
; The condition will match the following two requests if the reverse DNS was
; successful:
; 1) Referer: http://1.2.3.4/
; 2) Referer: http://mycompany.com/
; If the reverse DNS fails then the first request is not matched
<Proxy>
request.header.Referer.url.host.regex=mycompany
; request.header.Referer.url.path tests
; The following request.header.Referer.url.path strings would all match the example
Referer URL:
; Referer: http://www.example.com/cgi-bin/query.pl?q=test#fragment
request.header.Referer.url.path=”/cgi-bin/query.pl?q=test”
request.header.Referer.url.path=”/cgi-bin/query.pl”
request.header.Referer.url.path=”/cgi-bin/”
request.header.Referer.url.path=”/cgi” ; partial components match too
156
Chapter 3: Condition Reference
See Also
• Conditions: url=, server_url=
• Definitions: define subnet
157
Volume 10: Content Policy Language Guide
request.header.Referer.url.category=
Test the content filter categories of the Referer URL.
Syntax
request.header.Referer.url.category=none|unlicensed|unavailable|pending|
category_name1, category_name2, ...
Example
<Cache>
request.header.Referer.url.category=Sports
See Also
• Conditions: category=, url.category=, server.certificate.hostname.category=
158
Chapter 3: Condition Reference
request.raw_headers.count=
Test the total number of HTTP request headers.
This condition tests the total number of raw HTTP request headers, as defined by the
request.raw_headers.regex condition.
Syntax
request.raw_headers.count=numeric range from 0 to 8192
Example
• Reject the request if it contains more than 40 request headers.
<Proxy>
exception(invalid_request) request.raw_headers.count=40..
159
Volume 10: Content Policy Language Guide
request.raw_headers.length=
Test the total length of all HTTP request headers.
This condition tests the total number of bytes of HTTP request header data, including the header
names, values, delimiters, and newlines. The tally does not include the HTTP request line (which
contains the request method) and it does not include the terminating blank line.
Syntax
request.raw_headers.length=numeric range from 0 to 8192
Example
• Reject the request if it contains more than 4K of request header data.
<Proxy>
exception(invalid_request) request.raw_headers.length=4096..
160
Chapter 3: Condition Reference
request.raw_headers.regex=
Test the value of all HTTP request headers with a regular expression.
This condition allows you to test the complete, unaltered HTTP request header text, which includes
the header names, delimiters and header values. It iterates over all of the raw HTTP request headers. If
the specified regular expression matches one of these strings, then the condition is true.
Each "raw header" is a string consisting of a header line concatenated with zero or more continuation
lines. The initial header line consists of a header name, followed by colon, followed by the header
value, if any, followed by newline. The header value may have leading and trailing whitespace. Each
continuation line begins with a space or tab, followed by additional text which is part of the header
value, followed by a newline. Therefore, each "raw header" string contains a minimum of one newline,
plus an additional newline for each continuation line.
Here is how certain regex patterns work in the context of request.raw_headers.regex:
• "." matches any character, including newline.
• "^" only matches at the beginning of the header name.
• "$" only matches at the end of the string. The last character of the string is newline, so "$" will only
match after the final newline. You probably want to use "\s*$" instead.
• "\s" matches any white space character, including newline.
• "\n" matches newline.
Syntax
request.raw_headers.regex=regular_expression
Example
• Reject the request if it contains a header continuation line. Although this syntax is part of the
HTTP standard, it isn't normally used, and might not be interpreted correctly by some upstream
devices.
<Proxy>
exception(invalid_request) request.raw_headers.regex="\n[ \t]"
161
Volume 10: Content Policy Language Guide
request.x_header.header_name=
Tests the specified request header (header_name) against a regular expression. Any HTTP request
header can be tested, including custom headers. To test recognized headers, use
request.header.header_name= instead, so that typing errors can be caught at compile time. For
streaming requests, only the User-Agent header is available.
Syntax
request.x_header.header_name=regular_expression
where:
• header_name—Any HTTP header, including custom headers.
• regular_expression—A regular expression. For more information, see Appendix E:
"Using Regular Expressions".
Example
; deny access to the URL below if the request contains the custom
; header “Test” and the header has a value of “test1”
<Proxy>
deny url=http://www.bluecoat.com request.x_header.Test=”test1”
See Also
• Actions: append( ), delete( ), delete_matching( ), rewrite( ), set( )
• Conditions: request.header.header_name=, request.header.header_name.address=,
response.x_header.header_name=
162
Chapter 3: Condition Reference
request.x_header.header_name.address=
Tests if the specified request header can be parsed as an IP address; otherwise, false. If parsing
succeeds, then the IP address extracted from the header is tested against the specified IP address. The
expression can include an IP address or subnet, or the label of a subnet definition block. This condition
is intended for use with custom headers other than X-Forwarded-For and Client-IP headers; for
these, use request.header.header_name.address= so that typing any errors can be caught at
compile time.
Syntax
request.x_header.header_name.address= ip_address|subnet|subnet_label
where:
• header_name—Any HTTP header, including custom headers.
• ip_address—IP address; for example, 10.1.198.0.
• subnet—A subnet mask; for example, 10.1.198.0/24.
• subnet_label—Label of a subnet definition block that binds a number of IP addresses or
subnets.
Example
; deny access if the request’s custom header “Local” has the value 10.1.198.0
deny request.x_header.Local.address=10.1.198.0
See Also
• Actions: append( ), delete( ), delete_matching( ), rewrite( ), set( )
• Conditions: request.header.header_name=, request.header.header_name.address=,
response.x_header.header_name=
• Definitions: define subnet
163
Volume 10: Content Policy Language Guide
request.x_header.header_name.count=
Test the number of header values in the request for the given header_name.
Syntax
request.x_header.header_name.count=numeric range from 0 to 8192
Example
• Deny abnormal HTTP requests with 2 or more host headers.
<Proxy>
DENY("Too many Host headers") request.header.Host.count =
164
Chapter 3: Condition Reference
request.x_header.header_name.length=
Test the total length of the header values for the given header_name.
Syntax
request.x_header.header_name.length=numeric range from 0 to 8192
Example
• Deny HTTP requests with more than 2K of cookie data.
<Proxy>
DENY("Too much Cookie data") request.header.Cookie.length = 2048..
165
Volume 10: Content Policy Language Guide
response.header.header_name=
Tests the specified response header (header_name) against a regular expression. Any recognized
HTTP response header can be tested. For custom headers, use response.x_header.header_name=
instead.
Syntax
response.header.header_name=regular_expression
where:
• header_name—A recognized HTTP header. For a list of recognized headers, see
Appendix C: "Recognized HTTP Headers". For custom headers not listed, use condition
response.x_header.header_name instead.
• regular_expression—A regular expression. For more information, see Appendix E:
"Using Regular Expressions".
Example
; Test if the response’s “Content-Type” header has the value “image/jpeg”
response.header.Content-Type=”image/jpeg”
See Also
• Actions: append( ), delete( ), delete_matching( ), rewrite( ), set( )
• Conditions: request.header.header_name=, response.x_header.header_name=
166
Chapter 3: Condition Reference
response.raw_headers.count=
Test the total number of HTTP response headers.
This trigger tests the total number of raw HTTP response headers, as defined by the
response.raw_headers.regex trigger.
Syntax
response.raw_headers.count=N|..N|N..|N1..N2
where N is an unsigned integer.
Example
Reject the response if it contains 40 or more response headers.
<Proxy>
DENY("Too many response headers") response.raw_headers.count=40..
167
Volume 10: Content Policy Language Guide
response.raw_headers.length=
Test the total length of all HTTP response headers.
This trigger tests the total number of bytes of HTTP response header data, including the header
names, values, delimiters and newlines. The tally does not include the HTTP response line, which is
the first line of the response, and it does not include the terminating blank line.
Syntax
response.raw_headers.length=N|..N|N..|N1..N2
where:
N is an unsigned integer.
Example
Reject the response if it contains more than 4K of response header data.
<Proxy>
DENY("Too much response header data") response.raw_headers.length=4096..
168
Chapter 3: Condition Reference
response.raw_headers.regex=
Test the value of all HTTP response headers with a regular expression.
This trigger allows you to test the complete, unaltered HTTP response header text, which includes the
header names, delimiters and header values. It iterates over all of the raw HTTP response headers. If
the specified regular expression matches one of these strings, then the condition is true.
Each "raw header" is a string consisting of a header line concatenated with zero or more continuation
lines. The initial header line consists of a header name, followed by colon, followed by the header
value, if any, followed by newline. The header value may have leading and trailing whitespace. Each
continuation line begins with a space or tab, followed by additional text which is part of the header
value, followed by a newline. Therefore, each "raw header" string contains a minimum of one newline,
plus an additional newline for each continuation line.
Here is how certain regex patterns work in the context of response.raw_headers.regex:
* "." matches any character, including newline.
* "^" only matches at the beginning of the header name.
* "$" only matches at the end of the string. The last character of the string is newline, so "$" will only
match after the final newline. You probably want to use "\s*$" instead.
* "\s" matches any white space character, including newline.
* "\n" matches newline.
Syntax
response.raw_headers.regex=regular_expression
Example
Reject the response if it contains a header continuation line. Although this syntax is part of the HTTP
standard, it isn't normally used, and may not be interpreted correctly by some downstream devices.
<Proxy>
exception(invalid_response) response.raw_headers.regex="\n[ \t]"
169
Volume 10: Content Policy Language Guide
response.x_header.header_name=
Tests the specified response header (header_name) against a regular expression. For HTTP requests,
any response header can be tested, including custom headers. For recognized HTTP headers, use
response.header.header_name= instead so that typing errors can be caught at compile time.
Syntax
response.x_header.header_name=regular_expression
where:
• header_name—Any HTTP header, including custom headers.
• regular_expression—A regular expression. For more information, see Appendix E:
"Using Regular Expressions"
Example
; Tests if the custom header “Security” has the value of “confidential”
response.x_header.Security=”confidential”
See Also
• Actions: append( ), delete( ), delete_matching( ), rewrite( ), set( )
• Conditions: request.x_header.header_name=, response.header.header_name=
170
Chapter 3: Condition Reference
server.certificate.hostname.category=
Test the content filter categories of the hostname extracted from the X.509 certificate returned by the
server while establishing an SSL connection. This condition is NULL for transactions that do not
involve an SSL connection to the server.
Syntax
server.certificate.hostname.category=none|unlicensed|unavailable|pending|
category_name1, category_name2, ...
Example
This example uses both URL content filtering category definitions and categories provided by a
content filtering vendor to to restrict SSL access to certain sites
define category Internal
example1.com
www.example1.org
end
<Proxy> client.is_ssl
Allow server.certificate.hostname.category=Internal ; local definition
Allow server.certificate.hostname.category=(Sports, Games) ; or vendor supplied
Allow server.certificate.hostname.category=unavailable \
action.log_content_filter_down(yes) ; vendor down - allow but log
Deny
define action log_content_filter_down
log_message( "content filter vendor unavailable to test
$(server.certificate.hostname)" )
end
See Also
• Conditions: server.certificate.hostname=, server.certificate.common_name=,
server.certificate.subject=, category=, url.category=,
request.header.Referer.url.category=
• Properties: server.certificate.validate( ), server.certificate.validate.ignore( ),
server.certificate.validate.check_revocation( )
171
Volume 10: Content Policy Language Guide
server.connection.dscp=
Test the server-side inbound DSCP value.
Syntax
client.server.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
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.
<proxy>
deny server.connection.dscp = 50
<proxy>
deny server.connection.dscp = best-effort
172
Chapter 3: Condition Reference
server_url=
Tests if a portion of the URL used in server connections matches the specified criteria. The basic
server_url= test attempts to match the complete possibly-rewritten request URL against a specified
pattern. The pattern may include the scheme, host, port, path and query components of the URL. If
any of these is not included in the pattern, then the corresponding component of the URL is not tested
and can have any value.
Specific portions of the URL can be tested by applying URL component modifiers to the condition. In
addition to component modifiers, optional test type modifiers can be used to change the way the
pattern is matched.
Note: This set of tests match against the requested URL, taking into account the effect of any
rewrite( ) actions. Because any rewrites of the URL intended for servers or other upstream
devices must be respected by <Forward> layer policy, the url= conditions are not allowed in
<Forward> layers. Instead, the equivalent set of server_url= tests are provided for use in the
<Forward> layer. Those tests always take into account the effect of any rewrite( ) actions on
the URL.
Syntax
server_url[.case_sensitive][.no_lookup]=prefix_pattern
server_url.domain[.case_sensitive][.no_lookup]=domain_suffix_pattern
server_url.exact=string
server_url.prefix=string
server_url.substring=string
server_url.suffix=string
server_url.regex=regular_expressionregular_expression
server_url.address=ip_address|subnet|subnet_label
server_url.extension[.case_sensitive]=[.]filename_extension
server_url.host[.exact] [.no_lookup]=host
server_url.host.[prefix|substring|suffix]=string
server_url.host.regex=regular_expression
server_url.is_absolute=yes|no
server_url.host.is_numeric=yes|no
server_url.host.has_name=yes|no|restricted|refused|nxdomain|error
server_url.host.no_name=yes|no
server_url.path[.case_sensitive]=/string
server_url.path[.substring|.suffix][.case_sensitive]=string
server_url.path.regex[.case_sensitive]=regular_expression
server_url.port={[low_port_number]..[high_port_number]|exact_port_number}
server_url.query.regex[.case_sensitive]=regular_expression
server_url.scheme=url_scheme
where all options are identical to url=, except for the URL being tested. For more information,
see "url=" on page 186.
173
Volume 10: Content Policy Language Guide
Discussion
The server_url= condition is identical to url=, except for the lack of a define server_url condition
and [server_url] section. Most optimization in forwarding is done with server_url.domain
conditions and sections.
Example
; Test if the server URL includes this pattern, and block access.
; Relative URLs, such as docs subdirectories and pages, will match.
server_url=http://www.example.com/docs access_server(no)
; Test if the URL host’s IP address is a match.
server_url.address=10.1.198.0
; Test whether the URL includes company.com as domain.
server_url.domain=company.com
; Test whether the URL includes .com.
server_url.domain=.com
; Test if the URL includes this domain-suffix pattern,
; and block service. Relative URLs, such as docs
; subdirectories and pages, will match.
server_url.domain=company.com/docs access_server(no)
; Example of the use of server_url.extension=
server_url.extension=.txt
server_url.extension=(.htm, .html)
server_url.extension=(img, jpg, jpeg)
; This example matches the first request and doesn’t match the second from
; the following two requests:
; http://1.2.3.4/test
; http://www.example.com
<Forward>
server_url.host.is_numeric=yes
; In the example below we assume that 1.2.3.4 is the IP of the host mycompany
; The condition will match the following two requests if the reverse DNS was
; successful:
;request http://1.2.3.4/
;request http://mycompany.com/
; If the reverse DNS fails then the first request is not matched
<Forward>
server_url.host.regex=mycompany
; server_url.path tests
174
Chapter 3: Condition Reference
; The following server_url.path strings would all match the example URL:
; http://www.example.com/cgi-bin/query.pl?q=test#fragment
server_url.path=”/cgi-bin/query.pl?q=test”
server_url.path=”/cgi-bin/query.pl”
server_url.path=”/cgi-bin/”
server_url.path=”/cgi” ; partial components match too
server_url.path=”/” ; Always matches regardless of URL.
; testing the url port
server_url.port=80
See Also
• Conditions: content_management=, url=
• Definitions: define subnet, define server_url.domain condition
175
Volume 10: Content Policy Language Guide
socks=
This condition is true whenever the session for the current transaction involves SOCKS to the client.
The SOCKS=yes condition is intended as a way to test whether a request arrived via the SOCKS proxy.
It will be true for both SOCKS requests that the SG appliance tunnels and for SOCKS requests the SG
appliance accelerates by handing them off to HTTP or IM. In particular, socks=yes remains true even
in the resulting HTTP or IM transactions. Other conditions, such as proxy.address or proxy.port do
not maintain a consistent value across the SOCKS transaction and the later HTTP or IM transaction, so
they cannot be reliably used to do this kind of cross-protocol testing.
Syntax
socks=yes|no
See Also
• Conditions: socks.accelerate=
• Properties: socks_gateway( ), socks.accelerate( ), socks.authenticate( ),
socks.authenticate.force( ).
176
Chapter 3: Condition Reference
socks.accelerated=
Tests whether the SOCKS proxy will hand off this transaction to other protocol agents for acceleration.
Syntax
socks.accelerated={yes|http|aol-im|msn-im|yahoo-im|no}
where:
• yes is true only for SOCKS transactions that will hand off to another protocol-specific
proxy agent.
• no implies the transaction is a SOCKS tunnel.
• http is true if the transaction will be accelerated by the http proxy.
• aol-im is true if the transaction will be accelerated by the aol-im proxy.
• msn-im is true if the transaction will be accelerated by the msn-im proxy.
• yahoo-im is true if the transaction will be accelerated by the yahoo-im proxy.
See Also
• Conditions: socks.method=, socks.version=
• Properties: socks_gateway( ), socks.accelerate( ), socks.authenticate( ),
socks.authenticate.force( ).
177
Volume 10: Content Policy Language Guide
socks.method=
Tests the SOCKS protocol method name associated with the transaction.
Syntax
socks.method=CONNECT|BIND|UDP_ASSOCIATE
See Also
• Conditions: ftp.method=, http.method=, http.x_method=, im.method=, server_url=,
socks.version=
• Properties: socks_gateway( ), socks.accelerate( ), socks.authenticate( ),
socks.authenticate.force( ).
178
Chapter 3: Condition Reference
socks.version=
Tests whether the version of the SOCKS protocol used to communicate to the client is SOCKS 4/4a or
SOCKS 5. SOCKS 5 has more security and is more highly recommended.
SOCKS 5 supports authentication and can be used to authenticate transactions that may be accelerated
by other protocol services.
SOCKS 4/4a does not support authentication. If socks.authenticate() or
socks.authenticate.force() is set during evaluation of a SOCKS 4/4a transaction, that transaction
will be denied.
Syntax
socks.version=4..5
Example
This example authenticates SOCKS v5 clients, and allows only a known set of client IP addresses to
use SOCKS v4/4a.
<Proxy>
socks.version=5 socks.authenticate(my_realm )
deny socks.version=4 client.address=!old_socks_allowed_subnet
See Also
• Conditions: socks.method=, socks.version=
• Properties: socks_gateway( ), socks.accelerate( ), socks.authenticate( ),
socks.authenticate.force( )
179
Volume 10: Content Policy Language Guide
ssl.proxy_mode=
Test if the SG appliance is intercepting and decrypting an SSL connection.
Syntax
ssl.proxy_mode = yes|no|https-reverse-proxy|https-forward-proxy
where:
yes means the same as (https-reverse-proxy||https-forward-proxy)
Example
Test if an HTTPS reverse proxy request is being terminated.
<Proxy>
ssl.proxy_mode = https-reverse-proxy
180
Chapter 3: Condition Reference
streaming.client=
Tests the client agent associated with the current transaction.
Syntax
streaming.client=yes|no|windows_media|real_media|quicktime
where:
• yes is true if the user agent is recognized as a windows media player, real media player or
quicktime player.
• no is true if the user agent is not recognized as a windows media player, real media player
or quicktime player.
• other values are true if the user agent is recognized as a media player of the specified type.
See Also
• Conditions: bitrate=, live=, streaming.content=
• Properties: access_server( ), max_bitrate( ), streaming.transport( )
181
Volume 10: Content Policy Language Guide
streaming.content=
Tests the content of the current transaction to determine whether it is streaming media, and to
determine the streaming media type.
Syntax
streaming.content=yes|no|windows_media|real_media|quicktime
where:
• yes is true if the content is recognized as Windows media, Real media, or QuickTime
content.
• no is true if the content is not recognized as Windows media, Real media, or QuickTime
content.
• other values are true if the streaming content is recognized as the specified type.
See Also
• Conditions: bitrate=, live=, streaming.client=
• Properties: access_server(), max_bitrate( ), streaming.transport( )
182
Chapter 3: Condition Reference
time=
Tests if the time of day is in the specified range or an exact match. The current time is determined by
the SG appliance’s configured clock and time zone by default, although the UTC time zone can be
specified by using the form time.utc=. The numeric pattern used to test the time condition can
contain no whitespace.
Syntax
time[.utc]={[start_time]..[end_time]|exact_time}
where:
• start_time—Four digits (nnnn) in 24-hour time format representing the start of a time
range; for example, 0900 specifies 9:00 a.m. If left blank, midnight (0000) is assumed.
• end_time—Four digits (nnnn) in 24-hour time format representing the end of a time
range; for example, 1700 specifies 5:00 p.m. If left blank, 2359 (11:59 p.m.) is assumed.
• exact_time—Four digits (nnnn) in 24-hour time format representing an exact time.
Note: To test against an inverted range, such as a range that crosses from one day into the next, the
following shorthand expression is available. While time=(..0600|1900..) specifies
midnight to 6 a.m. and 7 p.m. to midnight, the policy language also recognizes
time=1900..0600 as equivalent.
Example
; Tests for 3 a.m. to 1 p.m. UTC.
time.utc=0300..1300
; Allow access to a particular site only during 9 a.m.
; to noon UTC (presented in two forms).
; Restrict form:
<Proxy>
deny url.host=special_event.com time=!0900..1200
; Grant form:
<Proxy>
allow url.host=special_event.com time=0900..1200
; This example restricts the times during which certain
; stations can log in with administrative privileges.
183
Volume 10: Content Policy Language Guide
<admin> client.address=restricted_stations
allow time=0800..1800 weekday=1..5 admin.access=(READ||WRITE);
deny
See Also
• Conditions: date[.utc]=, day=, hour=, minute=, month=, weekday=, year=
184
Chapter 3: Condition Reference
tunneled=
Tests if the current transaction represents a tunneled request. A tunneled request is one of:
• TCP tunneled request
• HTTP CONNECT request
• Unaccelerated SOCKS request
Note: HTTPS connections to the management console are not tunneled for the purposes of this test.
Syntax
tunneled=yes|no
Example
This example denies tunneled transactions except when they originate from the corporate subnet.
define subnet corporate_subnet
10.1.2.0/24
10.1.3.0/24
end
<Proxy>
deny tunneled=yes client.address=!corporate_subnet
See Also
Conditions: http.method=, socks.accelerated=, url.scheme=
Properties: sock.accelerate()
185
Volume 10: Content Policy Language Guide
url=
Tests if a portion of the requested URL matches the specified criteria. The basic url= test attempts to
match the complete request URL against a specified pattern. The pattern may include the scheme,
host, port, path and query components of the URL. If any of these is not included in the pattern, then
the corresponding component of the request URL is not tested and can have any value.
Specific portions of the URL can be tested by applying URL component modifiers to the condition. In
addition to component modifiers, optional test type modifiers can be used to change the way the
pattern is matched.
Note: This set of tests match against the originally requested URL, disregarding the effect of any
rewrite( ) actions. Because any rewrites of the URL intended for servers or other upstream
devices must be respected by <Forward> layer policy, the url= conditions are not allowed in
<Forward> layers. Instead, an equivalent set of server_url= tests are provided for use in the
<Forward> layer. Those tests always take into account the effect of any rewrite( ) actions on
the URL.
Syntax
url[.case_sensitive][.no_lookup]=prefix_pattern
url.domain[.case_sensitive][.no_lookup]=domain_suffix_pattern
url.exact[.case_sensitive]=string
url.prefix[.case_sensitive]=string
url.substring[.case_sensitive]=string
url.suffix[.case_sensitive]=string
url.regex[.case_sensitive]=regular_expression
url.address=ip_address|subnet|subnet_label
url.extension[.case_sensitive]=[.]filename_extension
url.host[.exact][.no_lookup]=host
url.host.[prefix|substring|suffix]=string
url.host.regex=regular_expression
url.is_absolute=yes|no
url.host.is_numeric=yes|no
url.host.no_name=yes|no
url.host.has_name=yes|no|restricted|refused|nxdomain|error
url.path[.case_sensitive]=/string
url.path[.substring|.suffix][.case_sensitive]=string
url.path.regex[case_sensitive]=regular_expression
url.port={[low_port_number]..[high_port_number]|exact_port_number}
url.query.regex[.case_sensitive]=regular_expression
url.scheme=url_scheme
where the URL test patterns are:
• prefix_pattern—A URL pattern that includes at least a portion of the following:
scheme://host:port/path
186
Chapter 3: Condition Reference
The request URL has the scheme https only in the case of SSL termination. A request
URL with the scheme tcp only has a host and a port, and occurs in two cases: when a
connection is made to a TCP tunnel service port, and when the CONNECT method is
used in an explicitly proxied HTTP request. For example, when the Web browser has an
explicit HTTP proxy and the user requests an HTTPS URL, the browser creates a TCP
tunnel using the CONNECT method.
• host—A domain name or IP address. Host names must be complete; for example,
url=http://www fails to match a URL such as http://www.example.com. This use of a
complete host instead of a domain_suffix (such as example.com) indicates the difference
between the url= and url.domain= conditions.
• domain_suffix—A pattern which matches either a complete domain name or is a suffix
of the domain name, respecting component boundaries. An IP address is not allowed.
This use of a domain_suffix pattern instead of a complete host name marks the
difference between the url.domain= and url= conditions.
187
Volume 10: Content Policy Language Guide
• path_query—The path_query portion of a URL is the string beginning with ‘/’ that
follows the host and port, and precedes any URL fragment. A path_query pattern is a
string beginning with a ‘/’ that matches the beginning of the path_query.
• filename_extension—A string representing a filename extension to be tested,
optionally preceded by a period (.). A quoted empty string (url.extension=””) matches
URLs that do not include a filename extension, such as http://example.com/ and
http://example.com/test. To test multiple extensions, use parentheses and a comma
separator (see the Example section below).
• regular_expression—A Perl regular expression. The expression must be quoted if it
contains whitespace or any of the following: & | ( ) < > { } ; ! . = " '. For more
information, see Appendix E: "Using Regular Expressions".
Objects with paths relative to the prefix_pattern and domain_suffix_pattern are also considered
a match (see the “Example” section).
The following are test modifiers:
• .case_sensitive—By default, all matching is case-insensitive; however, the matches on the path
and query portions can be made case-sensitive by using the form url.case_sensitive=.
• .domain—Changes the way the match is performed on the host portion of the URL. The host
pattern is a domain_suffix pattern which either matches the hostname exactly, or matches a
suffix of the hostname on component boundaries. The host is converted to a domain name by
reverse DNS lookup if necessary. For example, the condition url.domain=//example.com
matches the request URL http://www.example.com/, but does not match the request URL
http://www.myexample.com/.
• .exact—Forces an exact string comparison on the full URL or component.
• .no_lookup—Depending on the form of the request’s host and the form of the pattern being
matched, a DNS or reverse DNS lookup is performed to convert the request’s host before the
comparison is made. This lookup can be suppressed by using the .no_lookup= form of the
condition. The .no_lookup modifier speeds up policy evaluation, but use of it may introduce
loopholes into your security policy that can be exploited by those who want to bypass your
security measures. DNS and reverse DNS lookups can be globally restricted by restrict
definitions.
The .no_lookup option should only be applied to url, url.host and url.domain conditions.
When applied to the url.host= condition, if the URL host was specified as an IP address,
the behavior depends on whether the no_lookup modifier was specified. If no_lookup was
specified, then the condition is false. If no_lookup was not specified, then a reverse DNS
lookup is performed to convert the IP address to a domain name. If the reverse DNS lookup
fails, then the condition is false.
188
Chapter 3: Condition Reference
Note: If you deny the URL using url=http://www.sex.com/ for example, you cannot bypass
the policy by simply requesting the IP address of www.sex.com, since the underlying DNS
lookup exists for that particular condition.
If, however, you deny the URL by using url.exact=http://www.sex.com, you can
bypass the policy by simply using the IP address of that site.
When applied to the url.host= condition, this pattern match is always case-insensitive.
• .prefix—Test if the string pattern is a prefix of the URL or component.
• .regex—Test the URL or component against a regular_expression pattern.
When applied to the url.host= condition, if the URL host was specified as an IP address,
the behavior depends on whether the no_lookup modifier was specified. If no_lookup was
specified, then the condition is false. If no_lookup was not specified, then a reverse DNS
lookup is performed to convert the IP address to a domain name. If the reverse DNS lookup
fails, then the condition is false. This leads to the following edge conditions:
url.host.regex=!”” has the same truth value as url.host.no_name=yes, and
url.host.regex.no_lookup=!”” has the same truth value as url.host.is_numeric=yes.
When applied to the url.host= condition, this pattern match is always case-insensitive.
• .substring—Test if the string pattern is a substring of the URL or component. The substring
need not match on a boundary (such as a subdomain or path directory) within a component.
• .suffix—Test if the string pattern is a suffix of the URL or component. The suffix need not
match on a boundary (such as a domain component or path directory) within a URL component.
Note: .prefix, .regex, .substring, and .suffix are string comparisons that do not require a
match on component boundaries. For this reason, url.host.suffix= differs from the host
comparison used in url.domain= tests, which does require component level matches.
189
Volume 10: Content Policy Language Guide
• .host—Tests the host component of the requested URL against the IP address or domain name
specified by the host pattern. The pattern cannot include a forward slash (/) or colon (:). It does
not recognize wild cards or suffix matching. Matches are case-insensitive. The default test type is
.exact.
Note: url.host.exact= can be tested using hash techniques rather than string matches, and will
therefore have significantly better performance than other, string based, versions of the
url.host= tests. .
Since the host component of a request URL can be either an IP address or a domain name,
a conversion is sometimes necessary to allow a comparison.
• If the expression uses a domain name and the host component of the request URL is an IP
address, then the IP address is converted to a domain name by doing a reverse DNS lookup.
• If the expression uses an IP address and the host component of the request URL is a domain
name, then the domain name is converted to an IP address by doing a DNS lookup.
The .host component supports additional test modifiers:
• .is_numeric—This is true if the URL host was specified as an IP address. For some types of
transactions (for example, transparent requests on a non-accelerated port), this condition will
always be true.
• .no_name—This is true if no domain name can be found for the URL host. Specifically, it is
true if the URL host was specified as an IP address, and a reverse DNS lookup on this IP
address fails, either because it returns no name or a network error occurs.
• .path—Tests the path component of the request URL. By default, the pattern is tested as a prefix
of the complete path component of the requested URL, as well as any query component. The path
and query components of a URL consist of all text from the first forward slash (/) that follows the
host or port, to the end of the URL, not including any fragment identifier. The leading forward
slash is always present in the request URL being tested, because the URL is normalized before any
comparison is performed. Unless an .exact, .substring, or .regex modifier is used, the pattern
specified must include the leading ‘/’ character.
In the following URL example, bolding shows the components used in the comparison;
?q=test is the included query component and #fragment is the ignored fragment identifier:
http://www.example.com/cgi-bin/query.pl?q=test#fragment
A URL such as the following is normalized so that a forward slash replaces the missing
path component: http://www.example.com becomes http://www.example.com/.
• .port—Tests if the port number of the requested URL is within the specified range or an exact
match. URLs that do not explicitly specify a port number have a port number that is implied by
the URL scheme. The default port number is 80 for HTTP, so url.port=80 is true for any
HTTP-based URL that does not specify a port.
The patterns supported by the url.address= test are:
• low_port_number—A port number at the low end of the range to be tested. Can be a number
between 1 and 65535.
• high_port_number—A port number at the high end of the range to be tested. Can be a
number between 1 and 65535.
190
Chapter 3: Condition Reference
• exact_port_number—A single port number; for example, 80. Can be a number between 1
and 65535.
Note that the numeric pattern used to test the url.port condition can contain no
whitespace.
• .query—Tests if the regex matches a substring of the query string component of the request URL.
If no query string is present, the test is false. As a special case, url.query_regex=!"" is true no
query string exists.
The query string component of the request URL, if present, consists of all text from the first
question mark (?) following the path to the end of the URL. Note that pound (#) characters
following the ? are included in the query string for compatibility with certain Web applications. a
query string component exists, it begins with a ? character.
• .scheme—Tests if the scheme of the requested URL matches the specified schema string. The
comparison is always case-insensitive.
Discussion
The url= condition can be considered a convenient way to do testing that would require a
combination of the following conditions: url.scheme=, url.host=, url.port=, and url.path=. For
example,
url=http://example.com:8080/index.html
is equivalent to:
url.scheme=http url.host=example.com url.port=8080 url.path=/index.html
If you are testing a large number of URLs using the url= condition, consider the performance benefits
of a url definition block or a [url] section (see Chapter 6: "Definition Reference").
If you are testing a large number of URLs using the url.domain= condition, consider the performance
benefits of a url.domain definition block or a [url.domain] section (see Chapter 6: "Definition
Reference").
Regular expression matches are not anchored. You may want to use either or both of the ^ and
$ operators to anchor the match. Alternately, use the .exact, .prefix, or .suffix form of the test, as
appropriate.
Example
; Test if the URL includes this pattern, and block service.
; Relative URLs, such as docs subdirectories and pages, will match.
url=http://www.example.com/docs max_bitrate(no)
; Test if the URL host’s IP address is a match.
url.address=10.1.198.0
; Test whether the URL includes company.com as domain.
url.domain=company.com
191
Volume 10: Content Policy Language Guide
See Also
• Conditions: category=, console_access=, content_management=, server_url=
• Definitions: define subnet, define url condition, define url.domain condition
192
Chapter 3: Condition Reference
url.category=
Test the content filter categories of the request URL. Synonym for 'category='.
Syntax
url.category=none|unlicensed|unavailable|pending|category_name1, category_name2,
...
Example
<Cache>
url.category=Sports
See Also
• Conditions: category=, request.header.Referer.url.category=,
server.certificate.hostname.category=
193
Volume 10: Content Policy Language Guide
user=
Tests the authenticated username associated with the transaction. This condition is only available if
the transaction was authenticated (that is, the authenticate( ) property was set to something other
than no, and the proxy_authentication( ) property was not set to no).
Syntax
user=user_name
where user_name is a username.
• IWA realm: Usernames are case-insensitive.
In IWA this provides the flexibility of matching either a full username or relative
username.
For example:
user=bluecoat\mary.jones
matches a complete username, and
user=mary.jones
matches a relative name.
• UNIX (local) realm: Usernames are case-sensitive.
• RADIUS realm: Username case-sensitivity depends on the RADIUS server’s setting. The
case-sensitive setting should also be set correctly when defining a RADIUS realm in the
SG appliance.
• LDAP realm: Username case-sensitivity depends on the LDAP server’s setting. The
case-sensitive setting should also be set correctly when defining an LDAP realm in SG
appliance.
In LDAP this provides the flexibility of matching either a fully qualified domain name or
relative username.
For example:
user=”cn=mary.jones,cn=sales,dc=bluecoat,dc=com”
-or-
user=”uid=mary.jones,ou=sales,o=bluecoat”
matches a complete username, and
user=mary.jones
matches a relative name.
194
Chapter 3: Condition Reference
Note: When used in the <Forward>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.
Example
; Test for user john.smith.
user=john.smith
See Also
• Conditions: authenticated=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user.domain=, user.x509.issuer=,
user.x509.serialNumber=, user.x509.subject=
• Properties: authenticate( ), authenticate.force( ), check_authorization( ),
deny.unauthorized( ), socks.authenticate( ), socks.authenticate.force( )
195
Volume 10: Content Policy Language Guide
user.authentication_error=
Test what, if any, error was encountered during user authentication.
This condition is used to test what, if any, user authentication error was encountered. It will only be
evaluated if the encountered error was also specified as a tolerated error.
Syntax
user.authenticaExampletion_error(any|none|not_attempted|<error>,...)
where:
• any - evaluates to true if there was an authentication error.
• none - evaluates to true if there were no authentication errors and authentication was
attempted.
• not_attempted - evaluates to true if authentication was not attempted.
• <error>,... - specifies a single error or a group of errors. If the authentication error is
one of the errors in the list then the condition will evaluate to true.
Example
Redirect a user to a password change page after a password expiry
<proxy>
authenticate(realm) authenticate.tolerate_error(expired_credentials)
<proxy>
user.authentication_error=(expired_credentials)
action.redirect_to_password_change_page
define action redirect_to_password_change_page
redirect(302, '.*', 'http://ourcompany.com/password_change');
end
196
Chapter 3: Condition Reference
user.authorization_error=
Test what, if any, error was encountered during user authorization.
This condition is used to test what, if any, user authorization error was encountered. It will only be
evaluated if the encountered error was also specified as a tolerated error.
Syntax
user.authorization_error(any|none|not_attempted|<error>,...)
where:
• any - evaluates to true if there was an authorization error.
• none - evaluates to true if there were no authorization errors and authorization was
attempted.
• not_attempted - evaluates to true if authorization was not attempted.
• <error>,... - specifies a single error or a group of errors. If the authorization error is
one of the errors in the list then the condition will evaluate to true.
Example
Add a user to a default group if authentication succeeded but authorization failed due to a
communication error with the authorization server.
<proxy>
authenticate(realm) authorize.tolerate_error(communication_error)
<proxy>
user.authorization_error=(communication_error) authorize.add_group(default_group)
197
Volume 10: Content Policy Language Guide
user.domain=
Tests if the client is authenticated, the logged-into realm is an NTLM realm, and the domain
component of the username is the specified domain. If all of these conditions are met, the response
will be true. This condition is unavailable if the current transaction is not authenticated (that is, the
authenticate( ) property is set to no).
Syntax
user.domain=windows_domain_name
where windows_domain_name is a Windows domain name. This name is case-insensitive.
Note: When used in the <Forward> 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.
Example
; Test if the user is in domain all-staff.
user.domain=all-staff
See Also
• Conditions: authenticated=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.x509.issuer=,
user.x509.serialNumber=, user.x509.subject=
• Properties: authenticate( ), authenticate.force( ), check_authorization( ),
deny.unauthorized( ), socks.authenticate( ), socks.authenticate.force( )
198
Chapter 3: Condition Reference
user.is_guest=
Test whether a user is authenticated as a guest user.
Test whether a user is authenticated as a guest user. Only useful if used in conjunction with an
authenticate.guest property.
Syntax
user.is_guest=(yes|no)
Example
Add a guest user to a default group.
<proxy>
authenticate.guest(guest_user, 900, realm)
<proxy>
user.is_guest=yes authorize.add_group(default_group)
199
Volume 10: Content Policy Language Guide
user.login.address=
Test the address that user is logged in from.
This condition is used to match the IP address or subnet that the user has logged in from. This may be
different than the client IP address if the user is behind a proxy chain. The user login address can be
set with the property: authenticate.credentials.address.
Syntax
user.login.address=ip_address|subnet|subnet_label
Example
Allow the user if logged in from the subnet 10.167.146.0/24
<proxy>
user.login.address=10.167.146.0/24 allow
200
Chapter 3: Condition Reference
user.login.count=
Test the number active logins of this user.
This condition is used to test how many times the current user is logged in. It can be used to manage
the maximum number of times a user is allowed to log in.
Syntax
user.login.count([lower]..[upper]|exact)
where:
• [lower] is optionally the fewest number of logins that will match this condition.
• [upper] is optionally the most number of logins that will match this condition.
• exact is optionally the exact number of logins that will match this condition.
Example
Log out the other logins of a user if the user is logged in more than once.
<proxy>
user.login.count=2.. user.login.log_out_other(yes)
201
Volume 10: Content Policy Language Guide
user.login.time=
Test the number seconds that the current login has been active.
This condition is used to test how many seconds the current user has been logged in at the current ip
address. It can be used to manage the maximum time that a user is allowed to be logged in.
Syntax
user.login.time([lower]..[upper]|exact)
where:
• [lower] is optionally the fewest number of seconds that will match this condition
• [upper] is optionally the most number of seconds that will match this condition
• exact is optionally the exact number of seconds that will match this condition
Example
Log out the user if the user has been logged in for more than one hour.
<proxy>
user.login.time=3600.. user.login.log_out(yes)
202
Chapter 3: Condition Reference
user.x509.issuer=
Tests the issuer of the x509 certificate used in authentication to certificate realms. The
user.x509.issuer= condition is primarily useful in constructing explicit certificate revocation lists.
This condition will only be true for users authenticated against a certificate realm.
Syntax
user.x509.issuer=issuer_DN
where issuer_DN is an RFC2253 LDAP DN, appropriately escaped. Comparisons are
case-sensitive.
Note: When used in the <Forward> 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.
See Also
• Conditions: authenticated=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.domain=,
user.x509.serialNumber=, user.x509.subject=
• Properties: authenticate( ), authenticate.force( )
203
Volume 10: Content Policy Language Guide
user.x509.serialNumber=
Tests the serial number of the x509 certificate used to authenticate the user against a certificate realm.
The user.x509.serialNumber= condition is primarily useful in constructing explicit certificate
revocation lists. Comparisons are case-insensitive.
Syntax
user.x509.serialNumber=serial_number
where serial_number is a string representation of the certificate’s serial number in HEX.
The string is always an even number of characters long, so if the number needs an odd
number of characters to represent in hex, there is a leading zero. This can be up to 160 bits.
Note: When used in the <Forward> 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.
See Also
• Conditions: authenticated=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.domain=, user.x509.issuer=,
user.x509.subject=
• Properties: authenticate( ), authenticate.force( )
204
Chapter 3: Condition Reference
user.x509.subject=
Tests the subject field of the x509 certificate used to authenticate the user against a certificate realm.
The user.x509.subject= condition is primarily useful in constructing explicit certificate revocation
lists.
Syntax
user.x509.subject=subject
where subject is an RFC2253 LDAP DN, appropriately escaped.
Comparisons are case-sensitive.
Note: When used in the <Forward> 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.
See Also
• Conditions: authenticated=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.domain=, user.x509.issuer=,
user.x509.serialNumber=
• Properties: authenticate( ), authenticate.force( )
205
Volume 10: Content Policy Language Guide
virus_detected=
Test whether a virus has been detected. Note that rules containing this trigger will not match for a
transaction that does not involve virus scanning.
Syntax
virus_detected=yes|no
Example
<Proxy>
virus_detected=yes
206
Chapter 3: Condition Reference
weekday=
Tests if the day of the week is in the specified range or an exact match. By default, the SG appliance’s
date is used to determine the day of the week. To specify the UTC time zone, use the form
weekday.utc=. The numeric pattern used to test the weekday= condition can contain no whitespace
Syntax
weekday[.utc]={[first_weekday]..[last_weekday]|exact_weekday}
where:
• first_weekday—An integer from 1 to 7, where 1 specifies Monday and 7 specifies
Sunday, indicating the first day of the week that tests true. If left blank, Monday is
assumed.
• last_weekday—An integer from 1 to 7, where 1 specifies Monday and 7 specifies Sunday,
indicating the last day of the week that tests true. If left blank, Sunday is assumed.
• exact_weekday—An integer from 1 to 7, where 1 specifies Monday and 7 specifies
Sunday, indicating the day of the week that tests true.
Note: When you want to test a range that wraps from one week into the next, the following
shorthand expression is available. While weekday=(..1|6..) specifies a long weekend that
includes Monday, the policy language also recognizes weekday=6..1 as equivalent.
Example
; Test for the weekend.
weekday=6..7
; Test for Saturday through Monday.
weekday=6..1
See Also
• Conditions: date[.utc]=, day=, hour=, minute=, month=, time=, year=
207
Volume 10: Content Policy Language Guide
year=
Tests if the year is in the specified range or an exact match. The current year is determined by the date
set on the SG appliance by default. To specify the UTC time zone, use the form year.utc=. Note that
the numeric pattern used to test the year= condition can contain no whitespace.
Syntax
year[.utc]={[first_year]..[last_year]|exact_year}
where:
• first_year—Four digits (nnnn) representing the start of a range of years; for
example, 2002.
• last_year—Four digits (nnnn) representing the end of a range of years. If left blank,
all years from first_year on are assumed.
• exact_year—Four digits (nnnn) representing an exact year.
Note: To test against an inverted range of years, the following shorthand expression is available.
While year=(..1998|2003..) specifies years up to and including 1998, and from 2003 on,
the policy language also recognizes year=2003..1998 as equivalent.
Example
; Tests for the years 2004 through 2006.
year=2004..2006
See Also
• Conditions: date[.utc]=, day=, hour=, minute=, month=, time=, weekday=, year=
208
Chapter 4: Property Reference
A property is a variable that can be set to a value. At the beginning of a transaction, all properties are set
to their default values. As each layer in the policy is evaluated in sequence, it can 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.
Property Reference
The remainder of this chapter lists the properties and their accepted values. It also provides tips as to
where each property can be used and examples of how to use them.
209
Volume 10: Content Policy Language Guide
access_log( )
Selects the access log used for this transaction. Multiple access logs can be selected to record a single
transaction. Individual access logs are referenced by the name given in configuration. Configuration also
determines the format of the each log. For more information on logging, refer to Volume 9: Access Logging.
To record entries in the event log, see "log_message( )" on page 364.
Syntax
access_log(auto|no|log_name_list)
access_log.log_name(yes|no)
access_log.[log_name_list](yes|no)
The default value is auto.
where:
• auto—use the default log for this protocol.
• no—turns off logging, either for this transaction or to the specified log_name or log_name_list.
• yes—turns on logging for this transaction to the specified log_name or log_name_list.
• log_name—an access log name as defined in configuration
• log_name_list—a list of access log names as defined in configuration, of the form:
log_name_1, log_name_2, ...
Discussion
Each of the syntax variants has a different role in selecting the list of access logs used to record the
transaction:
• access_log( ) overrides any previous access log selections for this transaction.
• access_log.log_name( ) selects or de-selects the named log, according to the specified value.
Any other log selections for the transaction are unaltered.
• access_log.[log_name_list]( ) selects or de-selects all the logs named in the list, according to
the specified value. The selection of logs not named in the list is unaffected.
See Also
• Properties: log.suppress.field-id, log.rewrite.field-id( )
• Actions: log_message( )
210
Chapter 4: Property Reference
access_server( )
Determines whether the client can receive streaming content directly from the origin content server or
other upstream device. Set to no to serve only cached content.
Note: Since part of a stream can be cached, and another part of the same stream can be uncached,
access_server(no) can cause a streaming transaction to be terminated after some of the
content has been served from the cache.
Syntax
access_server(yes|no)
The default value is yes.
See Also
• Conditions: bitrate=, live=, streaming.client=, streaming.content=
211
Volume 10: Content Policy Language Guide
action( )
Selectively enables or disables a specified define action block. The default value is no.
Note: Several define action blocks may be enabled for a transaction. If more than one action selected
rewrites the URL or header a specific header, the actions are deemed to conflict and only one
will be executed. When detected at runtime, action conflicts will be reported in the event log
as a severe event. Action conflicts may also be reported at compilation time.
Syntax
action(action_label)
action.action_label(yes|no)
The default value is no for all defined actions.
where action_label is the label of the define action block to be enabled or disabled.
Discussion
Each of the different syntax variants has a different role in selecting the list of actions applied to the
transaction:
• action() enables the specified action block and disables all other actions blocks.
• action.action_label( ) enables or disables the specific action block. Any other action block
selections for the transaction are unaltered.
See Also
• Definitions: define action
212
Chapter 4: Property Reference
adn.server( )
This property is used to enable or disable ADN service.
Syntax
adn.server(yes|no)
The default value is taken from the applicable service configuration.
Example
This property allows control of whether an ADN service is enabled in the <Forward> layer. The
following example shows the property used to disable ADN service.
<Forward>
adn.server(no)
See Also
• Properties: adn.server.optimize( )
213
Volume 10: Content Policy Language Guide
adn.server.optimize( )
If the value is set to yes then data both to and from the server will be optimized.
This property is applied only if the application proxy server connection is forwarded over an ADN
tunnel.
Syntax
adn.server.optimize(yes|no|byte_cache|compress)
adn.server.optimize.optimization-setting(yes|no)
adn.server.optimize[optimization-settings](yes|no)
Where optimization-setting is one of byte_cache or compress. The default value is taken from the
applicable service configuration, which is dependent on the service.
Example
This property allows control of the optimization of individual connections based on any policy
conditions available in the <Forward> layer. The following example shows the property used to
disable optimizations for data flowing in both directions between clients from a specified subnet
and a particular service.
<Forward>
client.address=10.10.167.0/24 \
service.name="XWindows" \
adn.server.optimize(no)
See Also
• Properties: adn.server.optimize.inbound( ), adn.server.optimize.outbound( )
214
Chapter 4: Property Reference
adn.server.optimize.inbound( )
If the value is set to yes then data received from the server will be optimized.
This property is applied only if the application proxy server connection is forwarded over an ADN
tunnel.
Syntax
adn.server.optimize.inbound(yes|no|byte_cache|compress)
adn.server.optimize.inbound.optimization-setting(yes|no)
adn.server.optimize.inbound[optimization-settings](yes|no)
where optimization-setting is one of byte_cache or compress. The default value is taken from
the applicable service configuration, which is dependent on the service.
Example
This property allows control of the optimization of data received over individual server connections
based on any policy conditions available in the <Forward> layer. The following example shows the
property used to disable optimization for data from a particular host.
<Forward>
server_url.host=my_host.my_business.com \
adn.server.optimize.inbound(no)
See Also
• Properties: adn.server.optimize( ), adn.server.optimize.outbound( )
215
Volume 10: Content Policy Language Guide
adn.server.optimize.outbound( )
If the value is set to yes then data sent to the server will be optimized.
This property is applied only if the application proxy server connection is forwarded over an ADN
tunnel.
Syntax
adn.server.optimize.outbound(yes|no|byte_cache|compress)
adn.server.optimize.outbound.optimization-setting(yes|no)
adn.server.optimize.outbound[optimization-settings](yes|no)
where optimization-setting is one of byte_cache or compress. The default value is taken from the
applicable service configuration, which is dependent on the service.
Example
This property allows control of the optimization of data sent over individual server connections based
on any policy conditions available in the <Forward> layer. The following example shows the property
used to disable optimization for data sent to a particular host.
<Forward>
server_url.host=my_host.my_business.com \
adn.server.optimize.outbound(no)
See Also
• Properties: adn.server.optimize( ), adn.server.optimize.inbound( )
216
Chapter 4: Property Reference
advertisement( )
Determines whether to treat the objects at a particular URL as banner ads to improve performance. If
the content is not specific to a particular user or client, then the hit count on the origin server is
maintained while the response time is optimized using the following behavior:
• Always serve from the cache if a cached response is available. Ignore any request headers that
bypass the cache; for example, Pragma: No-Cache.
• Always cache the response from the origin server, similar to force_cache(all).
• If the request was served from the cache, request the object from the origin server in the
background to maintain the origin server's hit count on the ad and also allow ad services to
deliver changing ads.
A number of CPL properties affect caching behavior, as listed in the “See Also” section below.
Remember that any conflict between their settings is resolved by CPL evaluation logic, which uses the
property value that was last set when evaluation ends.
Syntax
advertisement (yes|no)
The default value is no.
See Also
• Properties: always_verify( ), cache( ), cookie_sensitive( ), pipeline( ), refresh( ),
ttl( ), ua_sensitive( )
217
Volume 10: Content Policy Language Guide
allow
Allows the transaction to be served.
Allow can be overridden by the access_server( ), deny( ), force_deny( ), authenticate( ),
exception( ), or force_exception( ) properties or by the redirect( ) action.
Allow overrides deny( ) and exception( ) properties.
Note: Caution should be exercised when using allow in layers evaluated after layers containing
deny, to ensure that security is not compromised.
Syntax
allow
See Also
• Properties: access_server( ), deny( ), force_deny( ), authenticate( ), exception( ),
force_exception( )
• Actions: redirect( )
218
Chapter 4: Property Reference
always_verify( )
Determines whether each request for the objects at a particular URL must be verified with the origin
server. This property provides a URL-specific alternative to the global caching setting
always-verify-source. If there are multiple simultaneous accesses of an object, the requests are
reduced to a single request to the origin server.
Syntax
always_verify(yes|no)
The default value is no.
See Also
• Properties: advertisement( ), bypass_cache( ), cache( ), cookie_sensitive( ),
force_cache( ), pipeline( ), refresh( ), ttl( ), ua_sensitive( )
219
Volume 10: Content Policy Language Guide
authenticate()
Authenticate the user in the specified realm, or disable authentication for this transaction.
When authentication is dependent on any condition that is not part of the client's identity, then some
transactions from the client will be authenticated and some won't. However the browser will offer
some credential types pro-actively. The default behavior of the SG appliance is to forward any proxy
credentials that it does not consume.
To prevent forwarding of proxy credentials in situations where there is no upstream proxy
authentication, use the no_upstream_authentication option.
Syntax
authenticate(realm_name)
-or-
authenticate(no [, upstream_authentication|no_upstream_authentication])
where:
❐ realm_name is the name of a configured authentication realm.
Example
This example implements the following policy:
1. All traffic to a.com will be authenticated.
2. All traffic to b.com will be authenticated by an upstream proxy.
3. All other traffic will be unauthenticated, and proxy credentials will not be forwarded.
<Proxy>
url.domain=//a.com/ authenticate(localr)
url.domain=//b.com/ authenticate(no)
authenticate(no, no_upstream_authentication)
See Also
• Conditions: authenticated=, exception.id=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.domain=
220
Chapter 4: Property Reference
authenticate.authorization_refresh_time( )
Specify the number of seconds that authorization data can be cached.
Once the authorization data for a user (groups and attributes) is determined, that data is cached on the
Proxy. This property sets the number of seconds that this cached data can be trusted. After that time,
the data must be refreshed.
This property overrides the equivalent setting in the realm. If this property does not exist, then the
realm setting will apply.
Syntax
authenticate.authorization_refresh_time(seconds)
where:
seconds is the number of seconds that authorization data can be cached and reused. Once that time
expires, the authorization data must be refreshed from the authorization server.
The default value is 1.
Example
Set the authorization refresh time to one hour.
<proxy>
authenticate(myrealm) authenticate.authorization_refresh_time(3600)
221
Volume 10: Content Policy Language Guide
authenticate.charset( )
Specify the character encoding used by HTTP basic authentication.
The HTTP Basic authentication protocol sends the username and password to the proxy or origin
server as an array of bytes. The character encoding is arbitrarily chosen by the client. Within the HTTP
protocol, there is no way for the client to tell the upstream device which encoding is used.
If the username or password contains non-ASCII characters, then the SG appliance needs to know
what this character encoding is. Since there is no way for the proxy to determine this from the HTTP
request, it must be specified in policy, using the authenticate.charset property.
The default value is ascii.
If the HTTP Basic credentials are not encoded as specified by the authenticate.charset property,
then the HTTP request is terminated by an invalid_credentials exception. Therefore, if
authenticate.charset is set to its default value of ascii, and the username or password contain
non-ascii characters, then the request will be terminated.
You must configure authenticate.charset to use non-ascii credentials using the HTTP Basic
authentication protocol. An alternative to configuring this property is to use a different client-side
authentication protocol, such as IWA, or forms-based authentication.
Syntax
authenticate.charset(charset)
where:
charset A MIME charset name. Any of the standard charset names for encodings commonly
supported by Web browsers may be used.
One list of standard charset names is: http://www.iana.org/assignments/character-sets.
If you use Microsoft Windows, then you can use the "chcp" command in the Windows CLI to find out
your active code page. Once you know the code page number n, you can use "windows-n" as the
charset name.
The default value is ascii.
Example
Set the authentication character encoding to "windows-936", which is the "extended ascii" encoding
used by Microsoft Windows in North America.
<proxy>
authenticate(myrealm) authenticate.charset(windows-936)
222
Chapter 4: Property Reference
authenticate.credential_refresh_time()
Specify the number of seconds that passwords can be cached.
When a realm uses Basic authentication, the password is cached by the User Management framework.
This cached password can be trusted for the given number of seconds. After that time expires, the
password must be verified with the authentication server.
This property overrides the equivalent setting in the realm. If this property does not exist, then the
realm setting will apply.
Syntax
authenticate.credential_refresh_time(seconds)
where seconds is the number of seconds that passwords can be cached and reused. Once that time
expires, the password must be verified with the authentication server.
The default value is 1.
Example
Set the credential refresh time to one hour.
<proxy>
authenticate(myrealm) authenticate.credential_refresh_time(3600)
223
Volume 10: Content Policy Language Guide
authenticate.credentials.address( )
Specify the number of seconds that surrogates can be trusted.
This property allows overriding the address used for authentication. It will set the IP address of the
login session.
Syntax
authenticate.credentials.address(ip address
The default value is 0.0.0.0.
Example
Set the address of the login to value from the Client-IP header.
<proxy>
authenticate(myrealm)\
authenticate.credentials.address($(request.header.Client-IP))
224
Chapter 4: Property Reference
authenticate.guest( )
Specify to authenticate as a guest user.
This property can be used to support authenticating guest users. If a transaction matches both a guest
and regular authentication request it will first attempt regular authentication. If regular authentication
fails on a tolerated error it will then fallback to guest authentication.
Syntax
authenticate.guest(username [, surrogate-refresh-time [, realm] ])
where
• username specifies the substitution string to evaluate to determine the guest username e.g.
"guest_$(client.address)"
• surrogate-refresh-time (optional) specifies the refresh time for the guest user's surrogate
credential. If no refresh time is specified (or "0" is specified) then the surrogate refresh time
specified in the authentication realm is used.
• realm (optional) specifies the authentication realm to authenticate the user in. The user does not
actually have to exist on the authentication server. If no realm is specified then the realm used in a
previous authentication attempt in the transaction will be used. If the transaction has not
attempted a regular authentication and no realm is specified the user will receive an
authentication exception.
Example
To log users in as guest automatically
<proxy>
authenticate.guest(realm,guest_user) allow
To attempt authentication of a user first and then have the user explicitly select to login as guest if
authentication fails, modify the authentication_failed exception to included a link that has been
designated as the guest login URL for that realm and then use the following policy:
<proxy>
url=<virtual URL> authenticate.guest("guest_$(client.address)", 0, realm)
authenticate(realm) allow
225
Volume 10: Content Policy Language Guide
authenticate.force( )
This property controls the relation between authentication and denial.
Syntax
authenticate.force(yes|no)
The default value is no.
where:
• yes —Makes an authenticate( ) higher priority than deny( )or exception( ). Use yes to
ensure that user IDs are available for access logging (including denied requests).
• no—deny( ) and exception( ) have a higher priority than authenticate( ). This setting
allows early denial.
See Also
• Conditions: authenticated=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.domain=
226
Chapter 4: Property Reference
authenticate.form( )
When forms-based authentication is in use, this property selects the form used to challenge the user.
Syntax
authenticate.form(authentication-form)
Example
This example implements the following policy:
• All traffic from subnet HR_subnet must use the authentication form “HR_form.”
• All traffic from subnet ENG_subnet must use the authentication form “ENG_form.”
• All other traffic uses the default authentication form.
define subnet HR_subnet
10.10.0.0/16
end
define subnet ENG_subnet
10.9.0.0/16
end
<Proxy>
=authenticate(myrealm) authenticate.mode(form-cookie-redirect)
<Proxy>
; 1
client.address=HR_subnet authenticate.form(HR_form)
; 2
client.address=ENG_subnet authenticate.form(ENG_form)
; 3 -- no modification to 'authenticate.form' selects the default form
227
Volume 10: Content Policy Language Guide
authenticate.mode( )
Using the authentication.mode( ) property selects a combination of challenge type and surrogate
credentials.
Challenge type is what kind of challenge (proxy, origin or origin-redirect) is issued.
Surrogate credentials are credentials accepted in place of the user’s real credentials. They are used for a
variety of reasons. Blue Coat supports three kinds of surrogate credentials.
• IP surrogate credentials authenticate the user based on the IP address of the client. Once any client
has been successfully authenticated, all future requests from that IP address are assumed to be
from the same user.
• Cookie surrogate credentials use a cookie constructed by the SG appliance as a surrogate. The
cookie contains information about the user, so multiple users from the same IP address can be
distinguished. The cookie contains a temporary password to authenticate the cookie; this
password expires when the credential cache entry expires.
• Connection surrogate credentials use the TCP/IP connection to authenticate the user. Once
authentication is successful, the connection is marked authenticated and all future requests on
that connection are considered to be from the same user.
In SGOS 3.x, the connection’s authentication information includes the realm in which it was
authenticated. The surrogate credentials are accepted only if the current transaction’s realm matches
the realm in which the session was authenticated.
Syntax
authenticate.mode(mode_type)
where mode_type is one of the following, shown followed by the implied challenge type and
surrogate credential:
• Auto: The default; the mode is automatically selected, based on the request. Chooses
among proxy, origin-IP, and origin-IP-redirect, depending on the kind of connection
(explicit or transparent) and the transparent authentication cookie configuration. For
streaming transactions, authenticate.mode(auto) uses origin mode.
• Proxy: The SG appliance uses an explicit proxy challenge. No surrogate credentials are
used. This is the typical mode for an authenticating explicit proxy. In some situations
proxy challenges will not work; origin challenges are then issued.
• Proxy-IP: The SG appliance uses an explicit proxy challenge and the client's IP address as
a surrogate credential. Proxy-IP specifies an insecure forward proxy, possibly suitable for
LANs of single-user workstations. In some situations proxy challenges will not work;
origin challenges are then issued.
• Origin: The SG appliance acts like an OCS and issues OCS challenges. The authenticated
connection serves as the surrogate credential.
• Origin-IP: The SG appliance acts like an OCS and issues OCS challenges. The client IP
address is used as a surrogate credential. Origin-IP is used to support NTLM
authentication to the upstream device when the client cannot handle cookie credentials.
This mode is primarily used for automatic downgrading, but it can be selected for specific
situations.
228
Chapter 4: Property Reference
• Origin-cookie: The SG appliance acts like an origin server and issues origin server
challenges. A cookie is used as the surrogate credential. Origin-cookie is used in forward
proxies to support pass-through authentication more securely than origin-ip if the client
understands cookies. Only the HTTP and HTTPS protocols support cookies; other
protocols are automatically downgraded to origin-ip.
• This mode could also be used in reverse proxy situations if impersonation is not possible
and the origin server requires authentication.
• Origin-cookie-redirect: The client is redirected to a virtual URL to be authenticated, and
cookies are used as the surrogate credential. Note that the SG appliance does not support
origin-redirects with the CONNECT method.
• Origin-IP-redirect: The client is redirected to a virtual URL to be authenticated, and the
client IP address is used as a surrogate credential. Note that the SG appliance does not
support origin-redirects with the CONNECT method.
• SG2: The mode is selected automatically, based on the request, and uses the SGOS
2.x-defined rules.
• Form-IP: A form is presented to collect the user's credentials. The form is presented
whenever the user’s credential cache entry expires.
• Form-Cookie: A form is presented to collect the user's credentials. The cookies are set on
the OCS domain only, and the user is presented with the form for each new domain. This
mode is most useful in reverse proxy scenarios where there are a limited number of
domains.
• Form-Cookie-Redirect: A form is presented to collect the user's credentials. The user is
redirected to the authentication virtual URL before the form is presented. The
authentication cookie is set on both the virtual URL and the OCS domain. The user is only
challenged when the credential cache entry expires.
• Form-IP-redirect: This is similar to form-ip except that the user is redirected to the
authentication virtual URL before the form is presented.
Important: Modes that use an IP surrogate credential are insecure: After a user has
authenticated from an IP address, all further requests from that IP address are
treated as from that user. If the client is behind a NAT, or on a multi-user
system, this can present a serious security problem.
229
Volume 10: Content Policy Language Guide
authenticate.new_pin_form()
When Forms-Based authentication is in use, this selects the form to prompt user to enter a new PIN.
Syntax
authenticate.new_pin_form(new-pin-form-name)
where new-pin-form-name is the name of a valid new-pin form
Example
This example implements the following policy:
1. All traffic from subnet HR_subnet must use the new-pin form 'HR_new_pin_form'
2. All traffic from subnet ENG_subnet must use the new-pin form ENG_new_pin_form
3. All other traffic uses the default authentication form.
define subnet HR_subnet
10.10.0.0/16
end
define subnet ENG_subnet
10.9.0.0/16
end
<Proxy>
authenticate(myrealm) authenticate.mode(form-cookie-redirect)
<Proxy>
; 1
client.address=HR_subnet authenticate.new_pin_form(HR_new_pin_form)
; 2
client.address=ENG_subnet authenticate.new_pin_form(ENG_new_pin_form)
; 3 -- no modification to 'authenticate.new_pin_form' selects the default form
230
Chapter 4: Property Reference
authenticate.query_form()
When Forms-Based authentication is in use, this selects the form to display to the user when a yes/no
questions needs to be answered.
Syntax
authenticate.query_form(query-form-name)
where query-form-name is the name of a valid query form.
Example
This example implements the following policy:
1. All traffic from subnet HR_subnet must use the query form HR_query_form
2. All traffic from subnet ENG_subnet must use the query form ENG_query_form
3. All other traffic uses the default authentication form .
define subnet HR_subnet
10.10.0.0/16
end
define subnet ENG_subnet
10.9.0.0/16
end
<Proxy>
authenticate(myrealm) authenticate.mode(form-cookie-redirect)
<Proxy>
; 1
client.address=HR_subnet authenticate.query_form(HR_query_form)
; 2
client.address=ENG_subnet authenticate.query_form(ENG_query_form)
; 3 -- no modification to 'authenticate.query_form' selects the default form
231
Volume 10: Content Policy Language Guide
authenticate.redirect_stored_requests()
Determines whether requests stored during forms-based authentication can be redirected if the
upstream host issues a redirecting response.
Syntax
authenticate.redirect_stored_requests(yes|no)
Example
<Proxy>
authenticate.redirect_stored_requests(yes)
232
Chapter 4: Property Reference
authenticate.surrogate_refresh_time()
Specify the number of seconds that surrogates can be trusted.
This property is used to control the number of seconds that a surrogate credential is trusted. A
surrogate can be a cookie, an ip address or a previously authenticated connection. Once this time
expires, the surrogate is no longer trusted and must be refreshed by re-verifying the real credentials.
This property overrides the equivalent setting in the realm. If this property does not exist, then the
realm setting will apply.
Syntax
authenticate.surrogate_refresh_time(seconds)
where seconds is the number of seconds that surrogate credentials can be trusted (i.e. ip surrogate,
cookie surrogate, connection surrogate). Once that time expires, the real credentials must be verified.
The default value is 1.
Example
Set the surrogate refresh time to one hour.
<proxy>
authenticate(myrealm) authenticate.surrogate_refresh_time(3600)
233
Volume 10: Content Policy Language Guide
authenticate.tolerate_error()
Specify to allow certain errors during user authentication.
This property can be used to support attempting authenticating but allowing the transaction to
proceed if authentication fails for the specified error.
IMPORTANT NOTE: Tolerating the error group "all" will result in all authentication errors including
need_credentials to be tolerated. If specified then users will never be challenged which is often not the
desired behaviour. Use the error group "all" carefully.
Syntax
authenticate.tolerate_error.<error>(yes|no)
authenticate.tolerate_error[<error>,...](yes|no)
authenticate.tolerate_error(<error>,...)
where:
authenticate.tolerate_error(<error>,?) is equivalent to authenticate.tolerate_error[<error>?](yes)
• yes - specifies that the error is permitted and the transaction should proceed unauthenticated
• no - specifies that the error is not permitted and the transaction should terminate
• <error>,... - specifies a single error or a group of errors
Example
Redirect a user to a password change page after a password expiry
<proxy>
authenticate(realm) authenticate.tolerate_error(expired_credentials)
<proxy>
user.authentication_error=(expired_credentials)
action.redirect_to_password_change_page
234
Chapter 4: Property Reference
authenticate.use_url_cookie( )
This property is used to authenticate users who have third party cookies explicitly disabled.
Note: With a value of yes, if there is a problem loading the page (you get an error page or you cancel
an authentication challenge), the cfauth cookie is displayed. You can also see the cookie in
packet traces, but not in the browser URL window or history under normal operation.
Syntax
authenticate.use_url_cookie(yes|no)
The default is no.
See Also
Properties: authenticate.mode( )
235
Volume 10: Content Policy Language Guide
authorize.add_group()
Add default group(s) to an authenticated user.
This property can be used to specify a single group or list of groups to add to an authenticated user.
This property can only be used if the user is successfully authenticated.
Syntax
authorize.add_group(<group>,...)
where:
<group>,... - specifies the group or list of groups to add to the user
Example
Add a user to a default group if authentication succeeded but authorization failed due to a
communication error with the authorization server.
<proxy>
authenticate(realm) authorize.tolerate_error(communication_error)
<proxy>
user.authorization_error=(communication_error) authorize.add_group(default_group)
236
Chapter 4: Property Reference
authorize.tolerate_error()
Specify to allow certain errors during user authorization.
This property can be used to support attempting authorization but allowing the transaction to proceed
if authorization fails for the specified error.
Note: If this property is not explicitly specified in policy it will default to allowing the same errors as
specified in any authenticate.tolerate_error properties.
Syntax
authorize.tolerate_error.<error>(yes|no)
authorize.tolerate_error[<error>,...](yes|no)
authorize.tolerate_error(<error>,...)
where:
authorize.tolerate_error(<error>,?) is equivalent to authorize.tolerate_error[<error>?](yes)
• yes - specifies that the error is permitted and the transaction should proceed without
authorization data
• no - specifies that the error is not permitted and the transaction should terminate
• <error>,... - specifies a single error or a group of errors
Example
Add a user to a default group if authentication succeeded but authorization failed due to a
communication error with the authorization server.
<proxy>
authenticate(realm) authorize.tolerate_error(communication_error)
<proxy>
user.authorization_error=(communication_error) authorize.add_group(default_group)
237
Volume 10: Content Policy Language Guide
bypass_cache( )
Determines whether the cache is bypassed for a request. If set to yes, the cache is not queried and the
response is not stored in the cache. Set to no to specify the default behavior, which is to follow
standard caching behavior.
While static and dynamic bypass lists allow traffic to bypass the cache based on the destination IP
address, the bypass_cache property is intended to allow a bypass based on the properties of the
client; for example, you might use it to allow specific users or user groups to bypass the cache.
This property has no effect on streaming objects.
Syntax
bypass_cache(yes|no)
The default is no.
Example
; Bypass the cache for requests from this client IP address.
client.address=10.25.198.0 bypass_cache(yes)
See Also
• Properties: advertisement( ), always_verify( ), cache( ), cookie_sensitive( ),
direct( ), dynamic_bypass( ), force_cache( ), pipeline( ), refresh( ), ttl( ),
ua_sensitive( )
238
Chapter 4: Property Reference
cache( )
Controls HTTP and FTP caching behavior. A number of CPL properties affect caching behavior.
• If bypass_cache(yes) is set, then the cache is not accessed and the value of cache( ) is
irrelevant.
• If cache(yes) is set, then the force_cache(all) property setting modifies the definition of what
is considered a cacheable response.
• The properties cookie_sensitive(yes) and ua_sensitive(yes) have the same effect on
caching as cache(no).
Other CPL properties that affect caching behavior are listed in the “See Also” section below.
Remember that any conflict between their settings is resolved by CPL evaluation logic, which uses the
property value that was last set when evaluation ends.
Syntax
cache(yes|no)
The default is yes.
where:
• yes—Specifies the default behavior: cache responses from the origin server if they are cacheable.
• no—Do not store the response in the cache, and delete any object that was previously cached for
this URL.
Example
; Prevent objects at this URL from being added to the cache.
url=http://www.example.com/docs cache(no)
239
Volume 10: Content Policy Language Guide
See Also
• Properties: advertisement( ), always_verify( ), bypass_cache( ), cookie_sensitive( ),
direct( ), dynamic_bypass( ), force_cache( ), pipeline( ), refresh( ), ttl( ),
ua_sensitive( )
240
Chapter 4: Property Reference
category.dynamic.mode( )
Determines how dynamic categorization will be performed.
Syntax
category.dynamic.mode(none|realtime|background|default)
where:
• none: suppresses dynamic categorization for this request
• realtime: performs dynamic categorization in real-time; the request waits until the dynamic
category is available from the service
• background: performs dynamic categorization in the background; the request is assigned the
category 'pending', and continues to be processed without delay. Later, when the categorization
service responds, the dynamically-determined category for the requested object is saved so that
future requests for the object can make use of it.
• default: restores the setting to the configuration-specified default (to undo the effect of a
previous policy layer)
The default value is set via configuration.
Example
This example illustrates how the property is used to control dynamic categorization.
<Cache>
; do not dynamically categorize this domain
url.domain=bluecoat.com category.dynamic.mode(none)
; serve this domain and categorize in the background
url.domain=yahoo.com category.dynamic.mode(background)
; categorize all other requests in real time
category.dynamic.mode(realtime)
241
Volume 10: Content Policy Language Guide
check_authorization( )
In connection with CAD (Caching Authenticated Data) and CPAD (Caching Proxy-Authenticated
Data) support, check_authorization( ) is used when you know that the upstream device
sometimes (not always or never) requires the user to authenticate and be authorized for this object.
Setting the value to yes results in a GIMS (Get If Modified Since) to check authorization upstream,
and the addition of a “Cache-Control: must-revalidate” header to the downstream response.
Syntax
check_authorization(yes|no)
The default is no.
See Also
• Conditions: authenticated=, group=, has_attribute.name=,
http.transparent_authentication=, realm=, user=, user.domain=
242
Chapter 4: Property Reference
client.address.login.log_out_other()
Log out the any logins at this ip address other than the current login.
This property is used to log out any other logins at the current ip address other than the current login
of the transaction. Other users will need to re-authenticate at the this ip address before future
transactions at this ip address can proceed.
Syntax
client.address.login.log_out_other(yes|no)
The default value is yes.
Example
Log out the other logins of there is more than one login at this ip address.
<proxy>
client.address.login.count=2.. client.address.login.log_out_other(yes)
243
Volume 10: Content Policy Language Guide
client.certificate.require( )
Controls whether a certificate is requested from the client during SSL negotiations.
Syntax
client.certificate.require(yes|no)
For HTTPS Forward Proxy transactions, the default value is no . For HTTPS Reverse Proxy
transactions the default value is the same as the value of the verify-client attribute for the
corresponding reverse proxy service.
Example
This HTTPS forward proxy policy implements consent certificates. The client Web browser is required
to send a client certificate. The user has a choice of two predefined certificates: one certificate gives the
proxy permission to intercept the SSL session, and the other certificate denies the proxy this
permission. Thus, the human end-user gives explicit consent to have the SSL session intercepted.
<SSL> ssl.proxy_mode=https-forward-proxy
client.certificate.require(yes)
<SSL> ssl.proxy_mode=https-forward-proxy
OK client.certificate.common_name = "Yes decrypt my data"
FORCE_DENY
244
Chapter 4: Property Reference
client.certificate.validate( )
Determines whether client X.509 certificates will be verified during the establishment of SSL
connections.
Syntax
client.certificate.validate(yes|no)
The default value is taken from the configuration of the HTTPS service accepting the connection.
Example
<SSL>
client.certificate.validate(yes)
See Also
• Properties: server.certificate.validate( )
245
Volume 10: Content Policy Language Guide
client.certificate.validate.check_revocation()
Determines whether client X.509 certificates will be checked for revocation.
Syntax
client.certificate.validate.check_revocation(auto|ocsp|local|no)
where:
• auto the certificate will be checked through OCSP if available, otherwise it will be checked
against locally installed revocation list.
• ocsp checks the certificate through OCSP.
• no the certificate will not be checked for revocation.
• local checks the certificate against the locally installed revocation list.
The default value is auto.
Example
Sample usage:
<SSL>
client.certificate.validate.check_revocation(local)
246
Chapter 4: Property Reference
client.connection.dscp()
Controls client side outbound QoS/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 | echo | preserve
The special value preserve means to track the incoming DSCP value on the primary server
connection and use that as the value when sending packets on the client connections. The special value
echo means the outbound packet's DSCP value will use the same value as the inbound packet's DSCP
value.
The default value is preserve.
Example
The first QoS policy rule sets the client outbound QoS/DSCP value to echo, and the second QoS policy
rule sets the client outbound QoS/DSCP value to 50.
<proxy>
client.connection.dscp(echo)
<proxy>
client.connection.dscp(50)
247
Volume 10: Content Policy Language Guide
cookie_sensitive( )
Used to modify caching behavior by declaring that the object served by the request varies based on
cookie values. Set to yes to specify this behavior, or set to no for the default behavior, which caches
based on HTTP headers.
Using cookie_sensitive(yes) has the same effect as cache(no).
There are a number of CPL properties that affect caching behavior, as listed in the “See Also” section
below. Remember that any conflict between their settings is resolved by CPL evaluation logic, which
uses the property value that was last set when evaluation ends.
Syntax
cookie_sensitive(yes|no)
The default value is no.
See Also
• Properties: advertisement( ), always_verify( ), bypass_cache( ), cache( ), direct( ),
force_cache( ), pipeline( ), refresh( ), ttl( ), ua_sensitive( )
248
Chapter 4: Property Reference
delete_on_abandonment( )
If set to yes, specifies that if all clients who may be simultaneously requesting a particular object close
their connections before the object is delivered, the object fetch from the origin server is abandoned,
and any prior instance of the object is deleted from the cache.
Syntax
delete_on_abandonment(yes|no)
The default value is no.
See Also
• Properties: advertisement( ), always_verify( ), bypass_cache( ), cache( ),
cookie_sensitive( ), direct( ), dynamic_bypass( ), force_cache( ), pipeline( ),
refresh( ), ttl( ), ua_sensitive( )
249
Volume 10: Content Policy Language Guide
deny( )
Denies service.
Denial can be overridden by allow or exception( ). To deny service in a way that cannot be
overridden by a subsequent allow, use force_deny( ) or force_exception( ).
The relation between authenticate( ) and deny( ) is controlled by the authenticate.force )
property. By default, deny( ) overrides authenticate( ). Recall that this means that a transaction
can be denied before authentication occurs, resulting in no user identification available for logging.
Similarly, the relation between socks.authenticate( ) and deny( ) is controlled by the
socks.authenticate.force( ) property. By default, deny( ) overrides socks.authenticate( ).
Syntax
deny
deny(details)
where details is a string defining a message to be displayed to the user. The details string may
contain CPL substitution variables.
Discussion
The deny(details) property is equivalent to exception(policy_denied, details). The identity
of an exception being returned can be tested in an <Exception> layer using exception.id=.
For HTTP, a policy_denied exception results in a 403 Forbidden response. This is appropriate when
the denial does not depend on the user identity. When the denial does depend on user identity, use
deny.unauthorized( ) instead to give the user an opportunity to retry the request with different
credentials.
Example
deny url.address=10.25.100.100
See Also
• Condition: exception.id=
• Properties: allow, authenticate.force( ), deny.unauthorized( ), force_deny( ),
never_refresh_before_expiry( ), never_serve_after_expiry( ),
remove_IMS_from_GET( ), remove_PNC_from_GET( ), remove_reload_from_IE_GET( ),
request.filter_service( ), socks.authenticate( ), socks.authenticate.force( )
250
Chapter 4: Property Reference
deny.unauthorized( )
The deny.unauthorized property instructs the SG appliance to issue a challenge (401 Unauthorized
or 407 Proxy authorization required). This indicates to the client that the resource cannot be accessed
with their current identity, but might be accessible using a different identity. The browsers typically
respond by bringing up a dialog box so the user can change their identity. (The details string appears
in the challenge page so that if the user cancels, there is some additional help information provided).
Typically, use deny( ) if the policy rule forbids everyone access, but use deny.unauthorized if the
policy rule forbids only certain people.
Syntax
deny.unauthorized
deny.unauthorized(details)
where details is a string defining a message to be displayed to the user. The details string may
contain CPL substitution variables.
Discussion
If current policy contains rules that use the authenticate() or authenticate.force( ) properties,
the deny.unauthorized( ) property is equivalent to exception(authorization_failed). If policy
does not contain any rules that require authentication, deny.unauthorized( ) is equivalent to
exception(policy_denied).
The identity of the exception being returned can be tested in an <Exception> layer using
exception.id=.
See Also
• Conditions: exception.id=
• Properties: deny( ), exception( ), force_deny( ), force_exception( )
• Appendix D: "CPL Substitutions".
251
Volume 10: Content Policy Language Guide
detect_protocol( )
Determines whether to invoke protocol recognition, and which protocols should be recognized. When
one of the specified protocols is detected, the connection will be handled by the appropriate
application proxy.
Syntax
detect_protocol(all|none)
detect_protocol(protocol_list)
detect_protocol.protocol(yes|no)
detect_protocol[protocol_list](yes|no)
where:
❐ protocol_list is a comma separated list of protocol
Example
<Proxy>
detect_protocol(gnutella)
See Also
• Properties: force_protocol( )
252
Chapter 4: Property Reference
direct( )
Used to prevent requests from being forwarded to a parent proxy or SOCKS server, when the SG
appliance is configured to forward requests.
When set to yes, <Forward> layer policy is not evaluated for the transaction.
Syntax
direct(yes|no)
The default value is no, which allows request forwarding.
See Also
• Properties: bypass_cache( ), dynamic_bypass( ), force_cache(), forward( ),
reflect_ip( )
253
Volume 10: Content Policy Language Guide
dns.respond( )
Terminates a proxied DNS query with the given DNS RCODE.
Syntax
dns.respond(noerror|formerr|servfail|nxdomain|notimp|refused|yxdomain|yxrrset|n
xrrset|notauth|notzone|numeric range from 0 to 15)
Example
This example implements the following policy:
1. DNS queries using QTYPEs other than “PTR” or “A” are considered “not implemented.”
2. Any DNS query for a host ending in example.com is refused.
<DNS-Proxy>
; 1
dns.request.type=!(A||PTR) dns.respond(notimp)
<DNS-Proxy>
; 2
dns.request.name=.example.com dns.respond(refused)
254
Chapter 4: Property Reference
dns.respond.a( )
Terminates a proxied DNS query of type 'A' with the given response.
Syntax
dns.respond.a(ip-address[,ip-address]*[,ttl]|hostname[,ip-address]*[,ttl]))
Example
This example implements the following policies:
1. DNS queries for host1.example.com are resolved to 10.10.10.1 with a TTL of 7200 seconds.
2. DNS queries for host2.example.com are resolved to 10.10.10.2 with a CNAME of
“myhost.example.com” and a TTL of 9600 seconds.
<DNS-Proxy>
; 1
dns.request.name=host1.example.com dns.respond.a(10.10.10.1, 7200)
; 2
dns.request.name=host2.example.com \
dns.respond.a(myhost.example.com, 10.10.10.2, 9600)
255
Volume 10: Content Policy Language Guide
dns.respond.ptr( )
Terminates a proxied DNS query of type “PTR” with the given response.
Syntax
dns.respond.ptr(hostname[,ttl])
Example
This example implements the following policies:
1. Reverse DNS queries for 10.10.10.1 are resolved to host1.example.com with a TTL of 7200 seconds.
2. Reverse DNS queries for 10.10.10.2 are resolved to host2.example.com with the default TTL.
<DNS-Proxy>
; 1
dns.request.address=10.10.10.1 dns.respond.ptr(host1.example.com, 7200)
; 2
dns.request.address=10.10.10.2 dns.respond.ptr(host2.example.com)
256
Chapter 4: Property Reference
dynamic_bypass( )
Used to indicate that a particular transparent request is not to be handled by the proxy, but instead be
subjected to SG appliance dynamic bypass methodology.
The dynamic_bypass(yes) property takes precedence over authenticate(); however, a committed
denial takes precedence over dynamic_bypass(yes).
Syntax
dynamic_bypass(yes|no)
The default value is no.
See Also
• Properties: advertisement( ), always_verify( ), bypass_cache( ), cache( ),
cookie_sensitive( ), delete_on_abandonment( ), direct( ), force_cache(), pipeline( ),
refresh( ), ttl( ), ua_sensitive( )
257
Volume 10: Content Policy Language Guide
exception( )
Selects a built-in or user-defined response to be returned to the user.
The exception( ) property is overridden by allow or deny( ). To set an exception that cannot be
overridden by allow, use force_exception( ).
The identity of the exception being returned can be tested in an <Exception> layer using
exception.id=.
Note: When the exception response selected would have a Content-Length of 512 or fewer bytes,
Internet Explorer may substitute “friendly” error messages. To prevent this behavior use
exception.autopad(yes).
Syntax
exception(exception_id, details, string_name)
where:
• exception_id—Either the name of a built-in exception (refer to Chapter 15: “Advanced Policy”
in the Blue Coat Systems Configuration and Management Guide for the list of built-in exceptions), or a
name of the form user_defined.exception_id that refers to a user-defined exception page.
• details—A text string that is substituted for $(exception.details) within the selected
exception.
• string_name—A string name, as defined by define string, that is substituted for
$(exception.details) within the selected exception. The named string overrides the format
field of the exception. The string can contain substitutions.
See Also
• Conditions: exception.id=
• Properties: allow, deny( ), deny.unauthorized( ), exception.autopad( ), force_deny( ),
force_exception( )
• Appendix D: "CPL Substitutions".
258
Chapter 4: Property Reference
exception.autopad( )
Pad an HTTP exception response by including trailing white space in the response body so that
Content-Length is at least 513 characters.
A setting of yes is used to prevent Internet Explorer from substituting friendly error messages in place
of the exception response being returned, when the exception as configured would have a
Content-Length of less than 512 characters.
Syntax
exception.autopad(yes|no)
where:
• yes—Enables auto-padding.
• no—Disables auto-padding.
The default value is yes.
See Also
• Conditions: exception.id=
• Properties: exception( ), force_exception
259
Volume 10: Content Policy Language Guide
force_cache( )
Used to force caching of HTTP responses that would otherwise be considered uncacheable. The
default HTTP caching behavior is restored using force_cache(no). The value of the
force_cache( ) property is ignored unless all of the following property settings are in effect:
bypass_cache(no), cache(yes), cookie_sensitive(no), and ua_sensitive(no).
Syntax
force_cache(all|no)
The default value is no.
Example
; Ensure objects at this URL are cached.
url=http://www.example.com/docs force_cache(all)
See Also
• Properties: advertisement( ), always_verify( ), bypass_cache( ), cache( ),
cookie_sensitive( ), dynamic_bypass( ), pipeline( ), refresh( ), ttl( ),
ua_sensitive( )
260
Chapter 4: Property Reference
force_deny( )
The force_deny( ) property is similar to deny( ) except that it:
• Cannot be overridden by an allow.
• Overrides any pending termination (that is, if a deny( ) has already been matched, and a
force_deny or force_exception is subsequently matched, the latter commits.
• Commits immediately (that is, the first one matched applies).
The force_deny( ) property is equivalent to force_exception(policy_denied).
Syntax
force_deny
force_deny(details)
where details is a text string that will be substituted for $(exception.details) within the
policy_denied exception. The details string may also contain CPL substitution patterns.
See Also
• Conditions: exception.id=
• Properties: deny(), force_exception()
• Appendix D: "CPL Substitutions".
261
Volume 10: Content Policy Language Guide
force_exception( )
The force_exception( ) property is similar to exception except that it:
• Cannot be overridden by an allow.
• Overrides any pending termination (that is, if a deny( ) has already been matched, and a
force_deny( ) or force_exception( ) is subsequently matched, the latter commits.
• Commits immediately (that is, the first one matched applies).
Syntax
force_exception(exception_id)
force_exception(details)
where details is a text string that will be substituted for $(exception.details) within the
specified exception. The details string may also contain CPL substitution patterns.
See Also
• Conditions: exception.id=
• Properties: deny( ), exception( ), exception.autopad( ), force_deny( )
• Appendix D: "CPL Substitutions".
262
Chapter 4: Property Reference
force_patience_page( )
This property provides control over the application of the default patience page logic.
This syntax has been deprecated. Use response.icap_feedback.force_interactive().
Syntax
force_patience_page( yes|no )
force_patience_page.reason( yes|no )
force_patience_page( reason, ... )
force_patience_page[ reason, ...]( yes|no )
The default value is no.
Example
Sample usage:
<Proxy>
force_patience_page(user-agent)
See Also
• Properties: response.icap_feedback.force_interactive( )
263
Volume 10: Content Policy Language Guide
force_protocol( )
Specifies that the client connection should be treated as a particular protocol type. The connection will
be handled by the appropriate application proxy.
Syntax
force_protocol(no|http|bittorrent|edonkey|gnutella|epmapper)
The default value is no.
Example
<Proxy>
force_protocol(gnutella)
See Also
• Properties: detect_protocol( )
264
Chapter 4: Property Reference
forward( )
Determines forwarding behavior.
There is a box-wide configuration setting (config>forwarding>sequence) for the default forwarding
failover sequence. The forward( ) property is used to override the default forwarding failover
sequence with a specific list of host and/or group aliases. The list of aliases might contain the special
token default, which expands to include the default forward failover sequence defined in
configuration.
Duplication is allowed in the specified alias list only in the case where a host or group named in the
default failover sequence is also named explicitly in the alias_list.
In addition, there is a box-wide configuration setting (config>forwarding>failure-mode) for the
default forward failure mode. The forward.fail_open( ) property overrides the configured default.
Syntax
forward(alias_list|no)
where:
• alias_list—Forward this request through the specified alias list, which might refer to both
forward hosts and groups. The SG appliance attempts to forward this request through the
specified hosts or groups, in the order specified by the list. It proceeds to the next alias as
necessary when the current host or group is down, as determined by health checks.
• no—Do not forward this request through a forwarding host. A SOCKS gateway or ICP host may
still be used, depending on those properties. If neither are set, the request is sent directly to the
origin server. Note that no overrides the default sequence defined in configuration.
The default value is default, as the only token in the alias_list.
See Also
• Properties: direct( ), dynamic_bypass( ), icp( ), reflect_ip( ), refresh( ),
socks_gateway( ), socks_gateway.fail_open( ), streaming.transport( )
265
Volume 10: Content Policy Language Guide
forward.fail_open( )
Controls whether the SG appliance terminates or continues to process the request if the specified
forwarding host or any designated backup or default cannot be contacted.
There is a box-wide configuration setting (config>forwarding>failure-mode) for the default
forward failure mode. The forward.fail_open( ) property overrides the configured default.
Syntax
forward.fail_open(yes|no)
where:
• yes—Continue to process the request if the specified forwarding host or any designated backup
or default cannot be contacted. This may result in the request being sent through a SOCKS
gateway or ICP, or may result in the request going directly to the origin server.
• no—Terminate the request if the specified forwarding host or any designated backup or default
cannot be contacted.
The default value is no.
See Also
• Properties: bypass_cache( ), dynamic_bypass( ), forward( ), reflect_ip( ),
socks_gateway( ), socks_gateway.fail_open( )
266
Chapter 4: Property Reference
ftp.match_client_data_ip( )
Sets whether to make a data connection to the client with the control connection's IP address or the
local physical IP address.
Syntax
ftp.match_client_data_ip(yes|no)
where:
• yes: make the data connection using the control connection's IP address.
• no: make the data connection using the local physical IP address.
Example
<Proxy>
ftp.match_client_data_ip(yes)
267
Volume 10: Content Policy Language Guide
ftp.match_server_data_ip( )
Sets whether to make a data connection to the server with the control connection's IP address or the
local physical IP address.
Syntax
ftp.match_server_data_ip(yes|no)
where:
• yes: make the data connection using the control connection's IP address
• no: make the data connection using the local physical IP address
Example
<Proxy>
ftp.match_server_data_ip(yes)
268
Chapter 4: Property Reference
ftp.server_connection( )
Determines when the control connection to the server is established. If set to deferred, the proxy
defers establishing the control connection to the server.
Syntax
ftp.server_connection(deferred|immediate)
The default value is immediate.
See Also
• Properties: ftp.server_data( ), ftp.transport( )
269
Volume 10: Content Policy Language Guide
ftp.server_data( )
Determines the type of data connection to be used with this FTP transaction.
Syntax
ftp.server_data(auto|passive|port)
where:
• auto—First attempt a PASV data connection. If this fails, switch to PORT.
• passive—Use a PASV data connection. PASV data connections are not allowed by some
firewalls.
• port—Use a PORT data connection. FTP servers can be configured to not support PORT
connections.
See Also
• Properties: ftp.server_connection( ), ftp.transport( )
270
Chapter 4: Property Reference
ftp.transport( )
Determines the upstream transport mechanism.
This setting is not definitive. It depends on the capabilities of the selected forwarding host.
Syntax
ftp_transport(auto|ftp|http)
The default value is auto.
where:
• auto—Use the default transport for the upstream connection, as determined by the
originating transport and the capabilities of any selected forwarding host.
• ftp—Use FTP as the upstream transport mechanism.
• http—Use HTTP as the upstream transport mechanism.
See Also
• Properties: ftp.server_connection( ), ftp.server_data( )
271
Volume 10: Content Policy Language Guide
ftp.welcome_banner( )
Sets the welcome banner for a proxied FTP transaction.
Syntax
ftp.welcome_banner(default | no | substitution-string)
where:
❐ default means use the setting on the SG appliance
Example
This example implements the following policies:
1. All requests from HR_subnet get the FTP welcome banner “client's address: Welcome to this
appliance”
2. All requests from ENG_subnet get the default FTP welcome banner.
3. All other requests get no FTP welcome banner.
define subnet HR_subnet
10.10.0.0/16
end
define subnet ENG_subnet
10.9.0.0/16
end
<Proxy>
; 1
client.address=HR_subnet \
ftp.welcome_banner("$(client.address): Welcome to $(appliance.name)")
; 2
client.address=ENG_subnet ftp.welcome_banner(default)
; 3
ftp.welcome_banner(no)
See Also
• Appendix D: "CPL Substitutions".
272
Chapter 4: Property Reference
http.allow_compression( )
Determines whether the HTTP Proxy is allowed to compress data in transit.
Syntax
http.allow_compression(yes|no)
The default value is no.
Example
<Proxy>
http.allow_compression(yes)
See Also
• Properties: http.allow_decompression( )
273
Volume 10: Content Policy Language Guide
http.allow_decompression( )
Determines whether the HTTP proxy is allowed to decompress data in transit.
Syntax
http.allow_decompression(yes|no)
The default value is no.
Example
<Proxy>
http.allow_decompression(yes)
See Also
• Properties: http.allow_compression( )
274
Chapter 4: Property Reference
http.client.allow_encoding( )
Determines which encodings are allowed in the response sent to the client.
Syntax
http.client.allow_encoding(encoding_or_client_list)
http.client.allow_encoding.encoding(yes|no)
http.client.allow_encoding[encoding_list](yes|no)
where:
❐ encoding_or_client_list is a comma separated list of encoding or client_list
Example
<Proxy>
http.client.allow_encoding(gzip)
See Also
• Properties: http.server.accept_encoding( )
275
Volume 10: Content Policy Language Guide
http.client.persistence( )
Controls persistence of the connection to the HTTP client.
If set to no, after the current transaction is complete, the client connection will be dropped.
Syntax
http.client.persistence(yes|no)
The default value is taken from HTTP configuration, which is "yes" by default.
Example
This property allows control of the persistence of individual client connections based on any policy
conditions available in the <Proxy> or <Exception> layers. The following example shows the property
used to disable persistent connections for clients from a specified subnet going to a particular host and
retrieving a particular content type in the response.
<Proxy>
client.address=10.10.167.0/8 \
url.host=my_host.my_business.com \
response.header.Content-Type="text/html" \
http.client.persistence(no)
See Also
• Properties: http.server.persistence( )
276
Chapter 4: Property Reference
http.client.recv.timeout( )
Sets the socket timeout for receiving bytes from the client.
Syntax
http.client.recv.timeout(auto | recv-timeout)
Example
This example implements the following policies:
1. Requests from HR_subnet get a receive timeout of 200 seconds.
2. Any request heading to a host that ends in example.com gets a receive timeout of 20 seconds.
3. All refresh traffic except that for example.com hosts gets a receive timeout of 300 seconds.
define subnet HR_subnet
10.10.0.0/16
end
<Proxy>
; 1
client.address=HR_subnet http.client.recv.timeout(200)
<Forward>
; 2
server_url.domain=example.com http.server.recv.timeout(20) \
http.refresh.recv.timeout(auto)
; 3
http.refresh.recv.timeout(300)
277
Volume 10: Content Policy Language Guide
http.compression_level( )
Determines the compression level used by HTTP Proxy when http.allow_compression is true.
Syntax
http.compression_level(low|medium|high)
The default value is low.
Example
<Proxy>
http.compression_level(medium)
See Also
• Properties: http.allow_compression( )
278
Chapter 4: Property Reference
http.force_ntlm_for_server_auth( )
http.force_ntlm_for_server_auth( ) is a fine grained control of the global configuration that can
be set or unset through CLI commands http force-ntlm or http no force-ntlm.
The force_ntlm commands are used to work around the Microsoft limitation that Internet Explorer
does not allow origin content server (OCS) NTLM authentication through a SG appliance when
explicitly proxied.
To correct this problem, Blue Coat has added a "Proxy-Support: Session-based-authentication" header
that is sent by default when the SG appliance receives a 401 authentication challenge when the client
connection is an explicit proxy connection.
For older browsers or if both the SG appliance and the OCS do NTLM authentication, the
Proxy-Support header might not work.
In this case, you can disable the header and instead use the CLI command http force-ntlm or the
http.force_ntlm_for_server_auth( ) property, which converts the 401-type server authentication
challenge to a 407-type proxy authentication challenge, supported by Internet Explorer. The SG
appliance also converts the resulting Proxy-Authentication headers in client requests to standard
standard server authorization headers, which allows an origin server NTLM authentication challenge
to pass through when Internet Explorer is explicitly proxied through the SG appliance.
Syntax
http.force_ntlm_for_server_auth(yes|no)
This property overrides the default specified in configuration.
where:
• yes—Allows Internet Explorer clients explicitly proxied through a SG appliance to
participate in NTLM authentication.
• no—The Proxy-Support: Session-based-authentication header is used to respond to 401
authentication-type challenges.
Example
This example implements the following policies:
• All clients from the HR_subnet have force-ntlm turned off.
• Requests for hosts in the example.com domain have force-ntlm turned on.
• Requests for all other hosts have force-ntlm turned off.
define subnet HR_subnet
10.10.0.0/16
end
279
Volume 10: Content Policy Language Guide
<Proxy>
; 1
client.address=HR_subnet http.force_ntlm_for_server_auth(no)
; 2
url.domain=example.com http.force_ntlm_for_server_auth(yes)
; 3
http.force_ntlm_for_server_auth(no)10.10.0.0/16
end
280
Chapter 4: Property Reference
http.refresh.recv.timeout( )
Sets the socket timeout for receiving bytes from the upstream host when performing a refresh.
Syntax
http.refresh.recv.timeout(auto| recv-timeout)
Example
This example implements the following policies:
1. Requests from HR_subnet get a receive timeout of 200 seconds.
2. Any request heading to a host that ends in example.com gets a receive timeout of 20 seconds.
3. All refresh traffic except that for example.com hosts gets a receive timeout of 300 seconds.
define subnet HR_subnet
10.10.0.0/16
end
<Proxy>
; 1
client.address=HR_subnet http.client.recv.timeout(200)
<Forward>
; 2
server_url.domain=example.com http.server.recv.timeout(20) \
http.refresh.recv.timeout(auto)
; 3
http.refresh.recv.timeout(300)
281
Volume 10: Content Policy Language Guide
http.request.version( )
The http.request.version( ) property sets the version of the HTTP protocol to be used in the
request to the origin content server or upstream proxy.
Syntax
http.request.version(1.0|1.1)
The default is taken from the CLI configuration setting http version, which can be set to
either 1.0 or 1.1. Changing this value in the CLI changes the default for both
http.request.version( ) and http.response.version( ).
See Also
• Conditions: http.request.version=
• Properties: http.response.version( )
282
Chapter 4: Property Reference
http.response.parse_meta_tag.Cache-Control( )
Controls whether the 'Cache-Control' META Tag is parsed in an HTML response body.
Syntax
http.response.parse_meta_tag.Cache-Control(yes|no)
Example
<Proxy>
http.response.parse_meta_tag.Cache-Control(yes)
283
Volume 10: Content Policy Language Guide
http.response.parse_meta_tag.Expires( )
Controls whether the 'Expires' META Tag is parsed in an HTML response body.
Syntax
http.response.parse_meta_tag.Expires(yes|no)
Example
<Proxy>
http.response.parse_meta_tag.Expires(yes)
284
Chapter 4: Property Reference
http.response.parse_meta_tag.pragma-no-cache( )
Controls whether the 'Pragma: no-cache' META Tag is parsed in an HTML response body.
Syntax
http.response.parse_meta_tag.pragma-no-cache(yes|no)
Example
<Proxy>
http.response.parse_meta_tag.pragma-no-cache(yes)
285
Volume 10: Content Policy Language Guide
http.response.version( )
The http.response.version( ) property sets the version of the HTTP protocol to be used in the
response to the client's user agent.
Syntax
http.response.version(1.0|1.1)
The default is taken from the CLI configuration setting http version, which can be set to
either 1.0 or 1.1. Changing this value in the CLI changes the default for both
http.request.version( ) and http.response.version( ).
See Also
• Conditions: http.response.version=
• Properties: http.request.version( )
286
Chapter 4: Property Reference
http.server.accept_encoding( )
Determines which encodings are allowed in an upstream request.
Syntax
http.server.accept_encoding(all)
http.server.accept_encoding(encoding_or_client_list)
http.server.accept_encoding.encoding(yes|no)
http.server.accept_encoding[encoding_list](yes|no)
where:
❐ encoding_or_client_list is a comma separated list of encoding or client
❐ all represents all encodings supported by the client or by the SG appliance (currently gzip,
deflate and identity)
❐ client will be replaced by the list of encodings specified in the client's request
The default value for requests from a client is client. For client-less transactions, the default with
a valid compression license is all, otherwise identity.
Example
This example illustrates how the property is used to determine the accepted encodings. The conditions
used are assumed to be defined elsewhere).
<Proxy>
; accept only the identity encoding
condition=condition1 http.server.accept_encoding(identity)
See Also
• Properties: http.client.allow_encoding( ),
http.server.accept_encoding.allow_unknown( )
287
Volume 10: Content Policy Language Guide
http.server.accept_encoding.allow_unknown()
Determines whether or not unknown encodings in the client's request are allowed.
Syntax
http.server.accept_encoding.allow_unknown(yes|no)
The default value with a valid compression license is no, otherwise yes.
Example
This example allows only encodings supported by the SG appliance.
<Proxy>
http.server.accept_encoding(all) http.server.accept_encoding.allow_unknown(no)
See Also
• Properties: http.server.accept_encoding( )
288
Chapter 4: Property Reference
http.server.connect_attempts( )
Set the number of attempts to connect performed per-address when connecting to the upstream host.
Syntax
http.server.connect_attempts(number from 1 to 10)
Example
<Forward>
http.server.connect_attempts(7)
289
Volume 10: Content Policy Language Guide
http.server.persistence( )
Controls persistence of the connection to the HTTP server.
Syntax
http.server.persistence(yes|no)
The default value is taken from HTTP configuration, which is "yes" by default.
Example
This property allows control of the persistence of individual server connections based on any request
based conditions available in the <Cache> layer, or any request or client based conditions in a
<Proxy> layer. The following example shows the property used to disable persistent connections to a
particular host.
<Forward>
server_url.host=my_host.my_business.com \
http.server.persistence(no)
See Also
• Properties: http.client.persistence( )
290
Chapter 4: Property Reference
http.server.recv.timeout( )
Sets the socket timeout for receiving bytes from the upstream host.
Syntax
http.server.recv.timeout(auto | recv-timeout)
Example
This example implements the following policies:
1. Requests from HR_subnet get a receive timeout of 200 seconds
2. Any request heading to a host that ends in example.com gets a receive timeout of 20 seconds
3. All refresh traffic except that for example.com hosts gets a receive timeout of 300 seconds
define subnet HR_subnet
10.10.0.0/16
end
<Proxy>
; 1
client.address=HR_subnet http.client.recv.timeout(200)
<Forward>
; 2
server_url.domain=example.com http.server.recv.timeout(20) \
http.refresh.recv.timeout(auto)
; 3
http.refresh.recv.timeout(300)
291
Volume 10: Content Policy Language Guide
icp( )
Determines whether to consult ICP when forwarding requests. Any forwarding host or SOCKS
gateway identified as an upstream target takes precedence over consulting ICP.
Syntax
icp(yes|no)
The default is yes if ICP hosts are configured, no otherwise.
where:
• yes—Consult ICP unless forward( ) or socks_gateway( ) properties are set. If no ICP
hosts are configured, yes has no effect.
• no—Do not consult ICP hosts, even if configured.
See Also
• Properties: direct( ), forward( ), reflect_ip( ), socks_gateway( )
292
Chapter 4: Property Reference
im.block_encryption( )
Prevents the encryption of AOL IM messages by modifying messages during IM login time.
Syntax
im.block_encryption(yes|no)
Example
This example implements the following policy:
• Turn on block encryption for HR_subnet
define subnet HR_subnet
10.10.0.0/16
end
<Proxy>
client.address=HR_subnet im.block_encryption(yes)
293
Volume 10: Content Policy Language Guide
im.reflect( )
Sets whether IM reflection should be attempted.
Syntax
im.reflect(yes|no)
Example
<Proxy>
im.reflect(yes)
294
Chapter 4: Property Reference
im.strip_attachments( )
Determines whether attachments are stripped from instant messages. If set to yes, attachments are
stripped from instant messages.
Syntax
im.strip_attachments(yes|no)
The default value is no.
See Also
• Conditions: im.buddy_id=, im.chat_room.conference=, im.chat_room.id=,
im.chat_room.invite_only=, im.chat_room.type=, im.chat_room.member=,
im.chat_room.voice_enabled=, im.file.extension=, im.file.name=, im.file.path=,
im.file.size=, im.message.route=, im.message.size=, im.message.text=,
im.message.type=, im.method=, im.user_id=
295
Volume 10: Content Policy Language Guide
im.transport( )
Sets the type of upstream connection to make for IM traffic.
Syntax
im.transport(native|http|auto)
Example
<Forward>
im.transport(native)
296
Chapter 4: Property Reference
integrate_new_hosts( )
Determines whether to add new host addresses to health checks and load balancing.
Syntax
integrate_new_hosts(yes|no)
The default is no. If it is set to yes, any new host addresses encountered during DNS
resolution of forwarding hosts are added to health checks and load balancing.
See Also
• Properties: forward( )
297
Volume 10: Content Policy Language Guide
limit_bandwidth( )
Assigns the bandwidth used in the specified traffic flows to the named bandwidth class, as defined in
configuration. The bandwidth class determines the minimum bandwidth guarantee, maximum
bandwidth allowed and relative priority.
Syntax
limit_bandwidth.client.inbound(no|bandwidth_class)
limit_bandwidth.client.outbound(no|bandwidth_class)
limit_bandwidth.server.inbound(no|bandwidth_class)
limit_bandwidth.server.outbound(no|bandwidth_class)
where:
no indicates that the flow is unregulated
Example
<Proxy>
limit_bandwidth(no)
298
Chapter 4: Property Reference
log.rewrite.field-id( )
The log.rewrite.field-id property controls rewrites of a specific log field in one or more access
logs. Individual access logs are referenced by the name given in configuration. Configuration also
determines the format of the each log. For more information on logging, refer to Chapter 19: “Access
Logging” in the Blue Coat Systems Configuration and Management Guide.
Syntax
log.rewrite.field-id(“substitution”|no)
log.rewrite.field-id[log_name_list](“substitution”|no)
where:
• field-id—Specifies the log field to rewrite. Some field-ids have embedded
parentheses, for example cs(User-agent). These field-ids must be enclosed in quotes.
There are two choices for quoting, either of which are accepted by the CPL compiler:
log.rewrite."cs(User-agent)”(...)
“log.rewrite.cs(User-agent)(...)”
• substitution—A quoted string containing replacement text for the field. The
substitution string can contain CPL substitution variables.
• no—Cancels any previous substitution for this log field.
Discussion
Each of the syntax variants has a different role in specifying the rewrites for the access log fields used
to record the transaction:
• log.rewrite.field-id( ) specifies a rewrite of the field_id field in all access logs selected for
this transaction.
• log.rewrite.field-id[log_name_list]( ) specifies a rewrite of the field_id field in all
access logs named in log_name_list. The field_id field in any logs not named in the list is
unaffected.
See Also
• Properties: access_log( ), log.suppress.field-id()
• Appendix D: "CPL Substitutions".
299
Volume 10: Content Policy Language Guide
log.suppress.field-id( )
The log.suppress.field-id( ) property controls suppression of the specified field-id in one or
more access logs. Individual access logs are referenced by the name given in configuration.
Configuration also determines the format of the each log. For more information on logging, refer to
Volume 9: Access Logging.
Syntax
log.suppress.field-id(yes|no)
log.suppress.field-id[log_name_list](yes|no)
where:
• field-id—Specifies the log field to suppress. Some field-ids have embedded
parentheses, for example cs(User-agent). These field-ids must be enclosed in quotes.
There are two choices for quoting, either of which are accepted by the CPL compiler:
log.suppress."cs(User-agent)"(yes|no)
"log.suppress.cs(User-agent)(yes|no)"
Discussion
Each of the syntax variants has a different role in suppressing the access log fields used to record the
transaction:
• log.suppress.field-id( ) controls suppression of the field_id field in all access logs selected
for this transaction.
• log.suppress.field-id[log_name_list]( ) controls suppression of the field_id field in all
access logs named in log_name_list. The field_id field in any logs not named in the list is
unaffected.
See Also
• Properties: access_log( ), log.rewrite.field-id( )
300
Chapter 4: Property Reference
max_bitrate( )
Enforces upper limits on the instantaneous bandwidth of the current streaming transaction. This
policy is enforced during initial connection setup. If the client requests a higher bit rate than allowed
by policy, the request is denied.
Note: Under certain network conditions, a client may receive a stream that temporarily exceeds the
specified bit rate.
Syntax
max_bitrate(bitrate|no)
The default value is no.
where:
• bitrate—Maximum bit rate allowed. Specify using an integer, in bits, kilobits (1000x), or
megabits (1,000,000x), as follows: integer | integerk | integerm.
• no—Allows any bitrate.
Example
; Client bit rate for streaming media cannot exceed 56 kilobits.
max_bitrate(56k)
See Also
• Conditions: bitrate=, live=, streaming.content=
301
Volume 10: Content Policy Language Guide
never_refresh_before_expiry( )
The never_refresh_before_expiry( ) property is similar to the CLI command:
SGOS#(config) http strict-expiration refresh
except that it provides per-transaction control to allow overriding the box-wide default set by the
command.
Syntax
never_refresh_before_expiry(yes|no)
The default value is taken from configuration.
See Also
• Properties: never_serve_after_expiry( ), remove_IMS_from_GET( ),
remove_PNC_from_GET( ), remove_reload_from_IE_GET( )
• Blue Coat Systems Command Line Interface Reference for information on the http
strict-expiration command.
302
Chapter 4: Property Reference
never_serve_after_expiry( )
The never_serve_after_expiry( ) property is similar to the CLI command:
SGOS#(config) http strict-expiration serve
except that it provides per transaction control to allow overriding the box-wide default set by the
command.
Syntax
never_serve_after_expiry(yes|no)
The default value is taken from configuration.
See Also
• Properties: always_verify(), never_refresh_before_expiry()
• Volume 12: Command Line Interface Reference for information on the http strict-expiration
command.
303
Volume 10: Content Policy Language Guide
patience_page( )
Controls whether or not a patience page can be served, and if so the delay bfore serving.
Syntax
patience_page(no|delay)
The default value is taken from configuration.
where:
• no—A patience page will not be served.
• delay —number of seconds, in the range 5-65535 before a patience page is served if
scanning is not complete.
The default value is no.
Example
Sample usage:
<Proxy>
patience_page(5)
See Also
• Properties: response.icap_feedback( ), response.icap_feedback.interactive( ),
response.icap_feedback.non_interactive( )
304
Chapter 4: Property Reference
pipeline( )
Determines whether an object embedded within an HTML container object is pipelined. Set to yes to
force pipelining, or set to no to prevent the embedded object from being pipelined. Note that this
property affects processing of the individual URLs embedded within a container object. It does not
prevent parsing of the container object itself.
If this property is used with a URL access condition, such as url.host=, each embedded object on a
page is evaluated against that policy rule to determine pipelining behavior. For example, a rule that
disallows pipelining for a particular host would still allow pipelining for images on the host's pages
that come from other hosts.
Note: Pipelining might cause issues for upstream devices that are low in TCP resources. The best
solution is to remove the bottleneck. A temporary solution might include fine-tuning the
device and disabling pipelining.
Syntax
pipeline(yes|no)
The default value is yes.
305
Volume 10: Content Policy Language Guide
reflect_ip( )
Determines how the client IP address is presented to the origin server for proxied requests.
Note: The SG appliance must be in the routing path for the reflect_ip property to work properly.
Syntax
reflect_ip(auto|no|client|vip|ip_address)
The default value is auto.
where:
• auto—Might reflect the client IP address, based on a config setting for spoofing.
• no—The appliance's IP address is used to originate upstream connections.
• client—The client's IP address is used in initiating upstream connections.
• vip—The appliance's VIP on which the client request arrived is used to originate
upstream traffic.
• ip_address—A specific IP address, which must be an address (either physical or virtual)
belonging to the SG appliance. If not, at runtime this is converted to auto.
Example
; For requests from a specific client, use the virtual IP address.
<proxy>
client.address=10.1.198.0 reflect_ip(vip)
See Also
• Properties: forward( )
306
Chapter 4: Property Reference
refresh( )
Controls refreshing of requested objects. Set to no to prevent refreshing of the object if it is cached. Set
to yes to allow the cache to behave normally.
Syntax
refresh(yes|no)
The default value is yes.
See Also
• Properties: advertisement( ), always_verify( ), bypass_cache( ), cache( ),
cookie_sensitive( ), direct( ), force_cache( ), never_refresh_before_expiry( ),
Never_serve_after_expiry( ), ttl( ), ua_sensitive( )
307
Volume 10: Content Policy Language Guide
remove_IMS_from_GET( )
The remove_IMS_from_GET( ) property is similar to the CLI command:
SGOS#(config) http substitute if-modified-since
except that it provides per transaction control to allow overriding the box-wide default set by the
command.
Syntax
remove_IMS_from_GET(yes|no)
The default value is taken from configuration.
See Also
• Properties: never_refresh_before_expiry( ), never_serve_after_expiry( ),
remove_PNC_from_GET( ), remove_reload_from_IE_GET( )
• Volume 12: Command Line Interface Reference for information on the http substitute command.
308
Chapter 4: Property Reference
remove_PNC_from_GET( )
The remove_PNC_from_GET property is similar to the CLI command:
SGOS#(config) http substitute pragma-no-cache
except that it provides per transaction control to allow overriding the box-wide default set by the
command.
Syntax
remove_PNC_from_GET(yes|no)
The default value is taken from configuration.
See Also
• Properties: never_refresh_before_expiry(), never_serve_after_expiry( ),
remove_IMS_from_GET( ), remove_reload_from_IE_GET( )
• Blue Coat Systems Command Line Interface Reference for information on the http substitute
command.
309
Volume 10: Content Policy Language Guide
remove_reload_from_IE_GET( )
The remove_reload_from_IE_GET( ) property is similar to the CLI command:
SGOS#(config) http substitute ie-reload
except that it provides per transaction control to override the box-wide default set by the command.
Syntax
remove_reload_from_IE_GET(yes|no)
The default value is taken from configuration.
See Also
• Properties: never_refresh_before_expiry( ), never_serve_after_expiry( ),
remove_IMS_from_GET( ), remove_PNC_from_GET( )
• Blue Coat Systems Command Line Interface Reference for information on the http substitute
command.
310
Chapter 4: Property Reference
request.filter_service( )
Controls whether the request is processed by an external content filter service. The SG appliance
currently supports Websense Enterprise Server external content filtering.
Directing the request to an external content filter service does not affect policy based on categories
determined through an on-box vendor or CPL category definitions.
Categories determined by Websense Enterprise Server are not available to the category= condition,
although they appear in access logs. Effectively, all policy based on the Websense determined
categories must be implemented on the Websense server.
Syntax
request.filter_service(service_name[, fail_open|fail_closed])
request.filter_service(no)
The default values are no and fail_closed.
where:
• service_name—A configured external content filter service that supports request
modification. Currently only Websense Enterprise Server is supported. On upgrade, the
service name websense is automatically generated.
• fail_open—If service_name is unavailable, the request is processed and a response may
be delivered, subject to other policy.
• fail_closed—If the service_name is unavailable, the request is denied.
• no—Prevents the request from being sent from the SG appliance to the external content
filter service.
Example
The following example directs requests to the Websense server, but allows processing to continue if
the service in unavailable:
<proxy>
request_filter_service(websense, fail_open)
The following policy establishes a general rule that all request are processed by the external filter
service named filter. It then specifies some exceptions to this general rule in a later layer:
<proxy> ; All request are content-filtered by default
request.filter_service( filter )
<proxy> request.filter_servce(no) ; exceptions to content-filtering
url.address=10.0.0.0/8 ; don't filter internal network
client.address=10.1.2.3 ; don't filter this client
311
Volume 10: Content Policy Language Guide
See Also
• Blue Coat Systems Command Line Interface Reference for information on configuring Websense
off-box services.
312
Chapter 4: Property Reference
request.icap_service( )
Determines whether a request from a client should be processed by an external ICAP service before
going out. Typical applications include regulatory compliance monitoring and intellectual property
protection.
This property can specify a fail-over sequence of ICAP request modification services or service groups.
The first healthy service in the sequence will be used to process the request. ICAP request processing
can also be disabled using this property. Optionally, the failure mode can be specified to control
behaviour if none of the listed services is healthy.
Syntax
request.icap_service( servicename_1, [servicename_2, ...,] [fail_open|fail_closed]
)
request.icap_service( no )
Where:
• servicename-A configured ICAP service or service group that supports request modification.
• fail_open-If none of the ICAP services listed is healthy, the request is sent out and a response
delivered to the client (subject to other policies).
• fail_closed-If none of the ICAP services listed is healthy, the request is denied. This is the
default and need not be specified to be in effect.
• no-Disables ICAP processing for this request.
The default value is fail_closed.
Example
This example implements the following Intellectual Property protection policy using IP scanners:
All requests will be scanned except those going to internal servers.
Requests coming from a special group of clients will be allowed out even if the request cannot be
scanned.
; general rule - scan all requests
<Proxy>
; some users can get out if the scanners are down
group=trusted_users request.icap_service( IP_service, IP_backup_service,
fail_open )
request.icap_service( IP_service, IP_backup_service ) ; default is fail_closed
313
Volume 10: Content Policy Language Guide
<Proxy>
condition=internal_servers request.icap_service( no )
See Also
• Properties: response.icap_service( )
314
Chapter 4: Property Reference
response.icap_feedback( )
Controls the type of feedback given to both interactive and non-interactive clients while response
scanning is in progress, and the delay before any feedback delivery starts.
This controls the feedback delivered to both interactive and non-interactive clients. However since
patience pages are served only to interactive clients,
response.icap_feedback( patience_page, delay )
is interpreted as:
response.icap_feedback.interactive( patience_page, delay )
response.icap_feedback.non_interactive( no )
Administrators should be aware of the increased security risks associated with trickling.
Syntax
response.icap_feedback( patience_page[, patience_delay] )
response.icap_feedback( trickle_start|trickle_end[, trickle_delay] )
response.icap_feedback( no )
where:
• no prevents any bytes from being delivered to the client until scanning completes. This option has good
security characteristics, but the worst user experience.
• patience_page returns a patience page to an interactive client after patience_delay seconds if scanning
has not completed within that time. No feedback is given to non_interactive clients.
This option has good security characteristics, and a reasonable user experience for interactive
clients.
• trickle_start begins delivering bytes to the client after trickle_delay seconds if scanning has not
completed within that time. HTTP response headers are delivered at line speed. The response body is
delivered to the client at the reduced (trickle) rate. The last 12K bytes of the response will be held until the
scanning result is known.
Trickled data may contain a threat, and although the end of the response is corrupted to render it
unusable, some client applications may still be vulnerable. Since all the data is delivered to the
client at a reduced rate, this is somewhat more secure than trickle_end, but the user will see very
little intermediate progress.
• trickle_end begins delivering bytes at line speed to the client after trickle_delay seconds if scanning has
not completed within that time. The last 16K bytes will be buffered by the appliance and trickling begins
only when no more data is expected from the server. The last 12K bytes of the response will be held until the
scanning result is known.
Trickled data may contain a threat, and although the end of the response is corrupted to render it
unusable, some client applications may still be vulnerable. Since only the last part of the data is
delivered to the client at a reduced rate, this is somewhat less secure than trickle_start, but the
user will see immediate initial progress.
• patience_delay is the number of seconds before a patience page is delivered to the client. The allowed
range is 5 to 65535. The default is 5.
315
Volume 10: Content Policy Language Guide
• trickle_delay is the number of seconds before feedback to the client starts. The allowed range is 0 to
65535. The default is 5.
The default value is no.
Example
The following example assumes that automated tools used within the organization can be
distinguished through a "robots" condition, defined elsewhere in the policy.
<Proxy>
; To prevent timeouts, robots get data trickled to them right away.
condition = robots response.icap_feedback( trickle_start, 0 )
; everyone else (presumably real users) get a patience page after 7 seconds
response.icap_feedback( patience_page, 7 )
See Also
• Properties: response.icap_service( ), response.icap_feedback.interactive( ),
response.icap_feedback.non_interactive( ),
response.icap_feedback.force_interactive( )
316
Chapter 4: Property Reference
response.icap_feedback.force_interactive( )
Modifies the logic used to determine whether or not this HTTP transaction represents an opportunity
to interact with the user.
Different feedback can be returned to the client depending on whether or not the current transaction is
judged to be interactive or non-interactive. For example, patience pages can only be delivered
when the transaction is interactive. Logic built into the system makes the determination for each
transaction. This property is used to override portions of that logic.
This property cannot be used to override the following reasons to consider the transaction
non-interactive:
• the request method is not 'GET'
• the response is not '200 OK'
• the server provides an unsolicited content encoding (one not requested by the ProxySG)
• there is a 'Range' or 'If-Range' header in the request
Syntax
response.icap_feedback.force_interactive( yes|no )
response.icap_feedback.force_interactive.reason( yes|no )
response.icap_feedback.force_interactive( reason, ... )
response.icap_feedback.force_interactive[ reason, ...]( yes|no )
where:
• reason -Takes one of the following values, corresponding to the overridable portions of the logic used to
determine whether or not interaction with a user is possible.
❐ user-agent overrides the decision to consider non-graphical browsers to be considered interactive.
Any User-Agent header string beginning with mozilla or opera are considered graphical.
❐ extension overrides the decision to consider requests for URLs with graphical file extensions or
extensions indicating cascading sytlesheets, javascript, vbscript, vbx, or java applet or flash animation
content as non-interactive.
❐ content-type overrides the decision to consider as non-interactive content similar to that listed under
extension, but based on the Content-Type header of the HTTP response.
The default value is no.
Example
The following example assumes that the organization has an interactive Mozilla-compatible browser
that identifies itself with a custom User-Agent header. The policy overrides the default logic so that
this user agent will be considered interactive.
317
Volume 10: Content Policy Language Guide
This form of the syntax is used so that this policy will not interfere with other policy making decisions
about the content type or extension (for example whether a transaction requesting graphical content
for example will be considered interactive.)
<Proxy>
request.header.User-Agent=brandedagent
response.icap_feedback.force_interactive.user-agent(yes)
See Also
• Properties: response.icap_service( ), response.icap_feedback( ),
response.icap_feedback.interactive( ), response.icap_feedback.non_interactive( )
318
Chapter 4: Property Reference
response.icap_feedback.interactive( )
Controls the type of feedback given to interactive clients while response scanning is in progress, and
the delay before any feedback delivery starts.
Administrators should be aware of the increased security risks associated with trickling.
Syntax
response.icap_feedback.interactive( patience_page[, patience_delay] )
response.icap_feedback.interactive( trickle_start|trickle_end[, trickle_delay] )
response.icap_feedback.interactive( no )
where:
• no prevents any bytes from being delivered to the client until scanning completes. This option has good
security characteristics, but the worst user experience.
• patience_page returns a patience page to an interactive client after patience_delay seconds if
scanning has not completed within that time. No feedback is given to non_interactive clients.
This option has good security characteristics, and a reasonable user experience for interactive
clients.
• trickle_start begins delivering bytes to the client after trickle_delay seconds if scanning has not
completed within that time. HTTP response headers are delivered at line speed. The response
body is delivered to the client at the reduced (trickle) rate. The last 12K bytes of the response will
be held until the scanning result is known.
Trickled data may contain a threat, and although the end of the response is corrupted to render it
unusable, some client applications may still be vulnerable. Since all the data is delivered to the
client at a reduced rate, this is somewhat more secure than trickle_end, but the user will see very
little intermediate progress.
• trickle_end begins delivering bytes at line speed to the client after trickle_delay seconds if
scanning has not completed within that time. The last 16K bytes will be buffered by the appliance
and trickling begins only when no more data is expected from the server. The last 12K bytes of the
response will be held until the scanning result is known.
Trickled data may contain a threat, and although the end of the response is corrupted to render it
unusable, some client applications may still be vulnerable. Since only the last part of the data is
delivered to the client at a reduced rate, this is somewhat less secure than trickle_start, but the
user will see immediate initial progress.
• patience_delay is the number of seconds before a patience page is delivered to the client. The allowed
range is 5 to 65535. The default is 5.
• trickle_delay is the number of seconds before feedback to the client starts. The allowed range is
0 to 65535. The default is 5.
The default value is no.
319
Volume 10: Content Policy Language Guide
Example
The following sample policy serves patience pages to FTP clients if scanning has not completed within
3 seconds. Note that all FTP transactions are considered interactive. Interactive HTTP transactions will
have the first portion of the data delivered at line speed, while the last part of the response will be
trickled.
See Also
• Properties: response.icap_service( ), response.icap_feedback( ),
response.icap_feedback.non_interactive( ),
response.icap_feedback.force_interactive( )
320
Chapter 4: Property Reference
response.icap_feedback.non_interactive( )
Controls the type of feedback given to non-interactive clients while response scanning is in progress,
and the delay before any feedback delivery starts.
Administrators should be aware of the increased security risks associated with trickling.
Syntax
response.icap_feedback.non_interactive( trickle_start|trickle_end[, trickle_delay]
)
response.icap_feedback.non_interactive( no )
where:
• no prevents any bytes from being delivered to the client until scanning completes. This option has
good security characteristics, but the worst user experience.
• trickle_start begins delivering bytes to the client after trickle_delay seconds if scanning has not
completed within that time. HTTP response headers are delivered at line speed. The response
body is delivered to the client at the reduced (trickle) rate. The last 12K bytes of the response will
be held until the scanning result is known.
Trickled data may contain a threat, and although the end of the response is corrupted to render it
unusable, some client applications may still be vulnerable. Since all the data is delivered to the
client at a reduced rate, this is somewhat more secure than trickle_end, but the user will see very
little intermediate progress.
• trickle_end begins delivering bytes at line speed to the client after trickle_delay seconds if
scanning has not completed within that time. The last 16K bytes will be buffered by the appliance
and trickling begins only when no more data is expected from the server. The last 12K bytes of the
response will be held until the scanning result is known.
Trickled data may contain a threat, and although the end of the response is corrupted to render it
unusable, some client applications may still be vulnerable. Since only the last part of the data is
delivered to the client at a reduced rate, this is somewhat less secure than trickle_start, but the
user will see immediate initial progress.
• trickle_delay is the number of seconds before feedback to the client starts. The allowed range is
0 to 65535. The default is 5.
The default value is no.
Example
The following example uses authentication and group membership to set distinct feedback policies for
known robots based on whether or not they might execute code from a corrupted package. It is
assumed here that automated tools within the organization would provide distinct credentials that
associates them with a "robots" group, and with other groups that distinguish risk.
No policy is specified for interactive clients.
321
Volume 10: Content Policy Language Guide
<Proxy>
authenticate( my_realm )
See Also
• Properties: response.icap_service( ), response.icap_feedback( ),
response.icap_feedback.interactive( ), response.icap_feedback.force_interactive(
)
322
Chapter 4: Property Reference
response.icap_service( )
Determines whether a response to a client is first sent to an ICAP service before being given to the
client. Depending on the ICAP service, the response may be allowed, denied, or altered. Typical
applications include virus scanning.
This property can specify a fail-over sequence of ICAP response modification services or service
groups. The first healthy service in the sequence will be used to process the response. ICAP response
processing can also be disabled using this property. Optionally, the failure mode can be specified to
control behaviour if none of the listed services is healthy.
Syntax
response.icap_service( servicename_1, [servicename_2, ...,] [fail_open|fail_closed]
)
response.icap_service( no )
where:
• servicename - A configured ICAP service or service group that supports response modification.
• fail_open - If none of the ICAP services listed is healthy, the response is processed and delivered
to the client (subject to other policies).
• fail_closed - If none of the ICAP services listed is healthy, the transaction is denied. This is the
default and need not be specified to be in effect.
• no - Disables ICAP processing for this response.
The default value is fail_closed.
Example
This example implements the following Virus Scanning policy using ICAP response scanners:
• All responses will be scanned except those going to internal servers.
• Responses coming from some business critical sites will be allowed even if the response cannot be
scanned.
; general rule - scan all responses
<Cache>
; responses from some critical sites get through even if the scanners are down
condition=critical_sites response.icap_service( VS_service, VS_backup_service,
fail_open )
response.icap_service( IP_service, IP_backup_service ) ; default is fail_closed
323
Volume 10: Content Policy Language Guide
<cache>
condition=internal_servers response.icap_service( no )
See Also
• Properties: request.icap_service( ), patience_page( )
324
Chapter 4: Property Reference
response.raw_headers.max_count()
Limit the number of response headers allowed in an HTTP response.
The number of HTTP response headers will be limited to the given number. If this limit is exceeded,
then the SG appliance will throw an "invalid_response" exception.
A leading white space based header continuation will not be counted as a separate header. In other
words, number here refers to headers, not response lines, and does not include response status line or
end-of-header marker (blank line).
The default value is 1,000. The minimum value is 0, and the maximum value is 10,000.
Syntax
response.raw_headers.max_count(unsigned-integer)
Example
<Proxy>
response.raw_headers.max_count(2500)
325
Volume 10: Content Policy Language Guide
response.raw_headers.max_length()
Limit the amount of response header data allowed in an HTTP response.
The total number of bytes of HTTP response header data is restricted to the given number. If this limit
is exceeded, then the SG appliance will throw an "invalid_response" exception.
The default value is 100,000. The minimum value is 0, and the maximum value is 1,000,000.
Syntax
response.raw_headers.max_length(unsigned-integer)
Example
<Proxy>
response.raw_headers.max_length(250000)
326
Chapter 4: Property Reference
response.raw_headers.tolerate()
Determines which deviations from the protocol specification will be tolerated when parsing the
response headers.
Syntax
response.raw_headers.tolerate(none|continue)
where:
• none indicates that no deviations are tolerated
• continue indicates that the response header parsing should tolerate a continuation line (white
space) prior to the start of the first header
The default value is none.
Example
This example illustrates how the property is used to specify which errors to tolerate. The conditions
used are assumed to be defined elsewhere).
<Proxy>
; Tolerate a continuation line prior to the first header,
; but only from a specified list of legacy servers.
condition=legacy_server response.raw_headers.tolerate(continue)
; For all other servers, use strict response header parsing rules
; This is actually the default, so it doesn’t need to be specified
response.raw_headers.tolerate(none)
See Also
• Properties: response.raw_headers.max_count( ), response.raw_headers.max_length( )
327
Volume 10: Content Policy Language Guide
server.certificate.validate()
Determines whether server X.509 certificates will be verified during the establishment of SSL
connections.
Syntax
server.certificate.validate(yes|no)
For HTTPS Reverse Proxy transactions, the default value is taken from the global setting established
through the CLI http ssl-verify-server command, or in the configuration of a forwarding host
used by the transaction. For HTTPS forward proxy and SSL tunnel transactions, the default is yes.
Example
<SSL>
server.certificate.validate(yes)
See Also
• Properties: server.certificate.validate.ignore( )
328
Chapter 4: Property Reference
server.certificate.validate.check_revocation()
Check SSL server certificates for revocation.
Syntax
server.certificate.validate.check_revocation(auto|ocsp|local|no)
where:
• auto the certificate will be checked through OCSP if available, otherwise it will be checked
against locally installed revocation list
• ocsp checks the certificate through OCSP
• local checks the certificate against the locally installed revocation list
• no the certificate will not be checked for revocation
The default value is auto.
Example
<SSL>
server.certificate.validate.check_revocation(local)
329
Volume 10: Content Policy Language Guide
server.certificate.validate.ignore()
Ignore errors during server certificate validation.
This property specifies which errors should be ignored while validating the server certificate during
the setup of an SSL connection.
Syntax
server.certificate.validate.ignore.flag(yes|no) ; form 1
server.certificate.validate.ignore[flag, ...](yes|no) ; form 2
server.certificate.validate.ignore(all|none) ; form 3
server.certificate.validate.ignore(flag, ...) ; form 4
where flag is one of expiration, untrusted_issuer, or hostname_mismatch
The default value is none.
Example
For maximum security, you should validate all server certificates. For sites that have bad certificates
that you nevertheless must be able to access, you can create a white list that disables only that part of
the validation process necessary to access the site.
<SSL>
server_url.host=some-server.com
server.certificate.validate.ignore.expiration(yes)
server_url.host=blah.com
server.certificate.validate.ignore.hostname_mismatch(yes)
server_url.host=do.this.at.your.own.peril
server.certificate.validate.ignore.untrusted_issuer(yes)
See Also
• Properties: server.certificate.validate( )
330
Chapter 4: Property Reference
server.connection.dscp()
Controls server-side outbound QoS/DSCP value.
Syntax
server.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 | echo | preserve
The special value preserve means to track the incoming DSCP value on the primary server
connection and use that as the value when sending packets on the client connections. The special value
echo means the outbound packet’s DSCP value will use the same value as the inbound packet’s DSCP
value.
The default value is preserve.
Example
The first QoS policy rule sets the server outbound QoS/DSCP value to echo, and the second QoS
policy rule sets the server outbound QoS/DSCP value to 50.
<proxy>
server.connection.dscp(echo)
<proxy>
server.connection.dscp(50)
331
Volume 10: Content Policy Language Guide
shell.prompt( )
Sets the prompt for a proxied shell transaction.
Syntax
shell.prompt(substitution-string)
Example
This example implements the following policies:
1. All requests from HR_subnet get the Shell prompt “client's address: Welcome to this appliance.”
2. All requests from ENG_subnet get the default Shell prompt.
3. All other requests get no Shell prompt.
define subnet HR_subnet
10.10.0.0/16
end
define subnet ENG_subnet
10.9.0.0/16
end
<Proxy>
; 1
client.address=HR_subnet \
shell.prompt("$(client.address): Welcome to $(appliance.name)")
; 2
client.address=ENG_subnet shell.prompt(default)
; 3
shell.prompt(no)
See Also
• Appendix D: "CPL Substitutions".
332
Chapter 4: Property Reference
shell.realm_banner( )
Sets the realm banner for a proxied shell transaction.
Syntax
shell.realm_banner(substitution-string)
Example
This example implements the following policies:
1. All requests from HR_subnet get the Shell realm banner “client's address: Welcome to this
appliance.”
2. All requests from ENG_subnet get the default Shell realm banner.
3. All other requests get no Shell realm banner.
define subnet HR_subnet
10.10.0.0/16
end
define subnet ENG_subnet
10.9.0.0/16
end
<Proxy>
; 1
client.address=HR_subnet \
shell.realm_banner("$(client.address): Welcome to $(appliance.name)")
; 2
client.address=ENG_subnet shell.realm_banner(default)
; 3
shell.realm_banner(no)
See Also
• Appendix D: "CPL Substitutions".
333
Volume 10: Content Policy Language Guide
shell.welcome_banner( )
Sets the welcome banner for a proxied shell transaction.
Syntax
shell.welcome_banner(substitution-string)
Example
This example implements the following policies:
1. All requests from HR_subnet get the Shell welcome banner “client's address: Welcome to this
appliance.”
2. All requests from ENG_subnet get the default Shell welcome banner.
3. All other requests get no Shell welcome banner.
define subnet HR_subnet
10.10.0.0/16
end
define subnet ENG_subnet
10.9.0.0/16
end
<Proxy>
; 1
client.address=HR_subnet \
shell.welcome_banner("$(client.address): Welcome to $(appliance.name)")
; 2
client.address=ENG_subnet shell.welcome_banner(default)
; 3
shell.welcome_banner(no)
334
Chapter 4: Property Reference
socks.accelerate( )
The socks.accelerate property controls the SOCKS proxy handoff to other protocol agents.
Syntax
socks.accelerate(no|auto|http|aol_im|msn_im|yahoo_im)
The default value is auto.
where:
• no—The SOCKS proxy does not hand off the transaction to another proxy agent, but
tunnels the SOCKS transaction.
• auto—The handoff is determined by the URL scheme.
Any other value forces the SOCKS proxy to hand off the transaction to the agent for the
indicated protocol.
The socks.accelerated= condition can be used to test which agent was selected for handoff.
The tunneled= condition can be used to test for unaccelerated (tunneled) SOCKS
transactions.
After the handoff, the transaction is subject to policy as a proxy transaction for the appropriate
protocol. Within that policy, the socks= condition can be used to test for transactions use
SOCKS for client communication.
See Also
• Properties: socks_gateway( ), socks.authenticate( ), socks.authenticate.force( )
• Conditions: socks=, socks.accelerated=, socks.method=, socks.tunneled=, socks.version=
335
Volume 10: Content Policy Language Guide
socks.allow_compression( )
Determines whether the SOCKS proxy is allowed to exchange compressed data with a SG appliance
client.
Note: The socks.allow_compression property is deprecated in favor of
• "adn.server.optimize( )"
• "adn.server.optimize.inbound( )"
• "adn.server.optimize.outbound( )"
Syntax
socks.allow_compression(yes|no)
The default value is yes.
Example
<Proxy>
socks.allow_compression(yes)
336
Chapter 4: Property Reference
socks.authenticate( )
The same realms can be used for SOCKS proxy authentication as can be used for regular proxy
authentication. This form of authentication applies only to SOCKS transactions.
The regular authenticate( ) property does not apply to SOCKS transactions. However, if an
accelerated SOCKS transaction has already been authenticated in the same realm by the SOCKS proxy,
no new authentication challenge is issued. If the realms identified in the socks.authenticate( ) and
authenticate( ) properties differ, however, a new challenge is issued by the proxy agent used to
accelerate the SOCKS transaction.
Following SOCKS proxy authentication, the standard user=, group=, and realm= tests are available.
The relation between SOCKS authentication and denial is controlled through the
socks.authenticate.force( ) property. The default setting no implies that denial overrides
socks.authenticate( ), with the result that user names may not appear for denied requests if that
denial could be determined without authentication. To ensure that user names appear in access logs,
use socks.authenticate.force(yes).
Syntax
socks.authenticate(realmname)
where:
• realmname—One of the already-configured realms.
• Consider that socks.authenticate() depends exclusively on a limited number of
triggers:
• proxy.address=
• proxy.card=
• proxy.port=
• client.address=
• socks.version=
Date and time triggers, while available, are not recommended.
See Also
• Properties: authenticate(), socks_gateway(), socks.accelerate(),
socks.authenticate.force()
• Conditions: socks=, socks.method=, socks.tunneled=, socks.version=
337
Volume 10: Content Policy Language Guide
socks.authenticate.force( )
This property controls the relation between SOCKS authentication and denial.
Syntax
socks.authenticate.force(yes|no)
The default value is no.
where:
• yes—Makes socks.authenticate( ) higher priority than deny( ) or exception( ).
Use yes to ensure that user ID's are available for access logging, even of denied requests.
• no—deny( ) and exception( ) have a higher priority than socks.authenticate( ).
This setting allows early denial (based on proxy card, address or port, client address, or
SOCKS version, for example). That is, the denial preempts any authentication
requirement.
See Also
• Properties: socks.authenticate( ), socks_gateway( ), socks.accelerate( )
• Conditions: socks.method=, socks.tunneled=, socks.version=
338
Chapter 4: Property Reference
socks_gateway( )
Controls whether or not the request associated with the current transaction is sent through a SOCKS
gateway.
There is a box-wide configuration setting (config > socks-gateways > sequence) for the default
SOCKS gateway failover sequence. The socks_gateway( ) property is used to override the default
SOCKS gateway failover sequence with a specific list of SOCKS gateway aliases. The list of aliases
might contain the special token default, which expands to include the default SOCKS gateway
failover sequence defined in configuration.
Duplication is allowed in the specified alias list only in the case where a gateway named in the default
failover sequence is also named explicitly in alias_list.
In addition, there is a box-wide configuration setting (config> socks-gateways > failure-mode)
for the default SOCKS gateway failure mode. The socks_gateway.fail_open( ) property overrides
the configured default.
Syntax
socks_gateway(alias_list|no)
The default value is no.
where:
• alias_list—Send this request through the specified alias list. The SG appliance attempts
to send this request through the specified gateways in the order specified by the list. It
proceeds to the next gateway alias as necessary when the gateway is down, as determined
by health checks.
• no—Do not send this request through a SOCKS gateway. A forwarding host or ICP host
may still be used, depending on those properties. If neither are set, the request is sent
directly to the origin server. A setting of no overrides the default sequence defined in
configuration.
See Also
• Properties: direct( ), forward( ), socks.accelerate( ), socks.authenticate( ),
socks.authenticate.force( )
• Conditions: socks.method=, socks.tunneled=, socks.version=
339
Volume 10: Content Policy Language Guide
socks_gateway.fail_open( )
Controls whether the SG appliance terminates or continues to process the request if the specified
SOCKS gateway or any designated backup or default cannot be contacted.
There is a box-wide configuration setting (config > socks-gateways > failure-mode) for the
default SOCKS gateway failure mode. The socks_gateway.fail_open( ) property overrides the
configured default.
Syntax
socks_gateway.fail_open(yes|no)
The default value is no.
where:
• yes—Continue to process the request if the specified SOCKS gateway or any designated
backup or default cannot be contacted. This may result in the request being forwarded
through a forwarding host or ICP, or may result in the request going direct to the origin
server.
• no—Terminates the request if the specified SOCKS gateway or any designated backup or
default cannot be contacted.
See Also
• Properties: socks.accelerate( ), socks.authenticate( ), socks.authenticate.force( ),
socks_gateway( )
• Conditions: socks.method=, socks.tunneled=, socks.version=
340
Chapter 4: Property Reference
socks_gateway.request_compression( )
Sets whether to request the upstream SOCKS gateway to allow compression of traffic with this client.
When enabled, the upstream SOCKS gateway will be asked to allow traffic to be compressed. If
compression is refused by the gateway, the client will continue with normal, uncompressed traffic. If
the property is set to default, the 'request-compression' setting in the SOCKS gateway configuration
will be used. The upstream SOCKS gateway must be a SG appliance participating in SOCKS
compression.
Note: The sock_gateway.request_compression property is deprecated in favor of
• "adn.server.optimize( )"
• "adn.server.optimize.inbound( )"
• "adn.server.optimize.outbound( )"
Syntax
socks_gateway.request_compression(yes|no|default)
The default value is default.
Example
<Forward>
socks_gateway.request_compression(yes)
See Also
• Properties: socks.allow_compression( )
341
Volume 10: Content Policy Language Guide
ssl.forward_proxy( )
Determines whether SSL connections should be intercepted.
The default value is https.
Syntax
ssl.forward_proxy(no|https)
where:
• no tunnels the SSL connection without breaking encryption
• https intercepts SSL connections using the SSL Proxy
Example
Since interception is the default action for HTTPS traffic, the general usage model is to create
exceptions for connections that need to be tunneled.
<ssl-intercept>
server.certificate.hostname.category="Financial Services" ssl.forward_proxy(no)
342
Chapter 4: Property Reference
ssl.forward_proxy.hostname( )
Specify the hostname for the forged certificate that is used for SSL interception.
The default value is "". The default behavior is to use the hostname from the original server certificate.
Syntax
ssl.forward_proxy.hostname(String)
Example
When the browser receives a server certificate signed by an unknown CA or with a hostname that
does not match the URL hostname, it shows a security alert popup. This popup can be leveraged as an
SSL level splashing mechanism. Various combinations of the ssl.forward_proxy.* properties can be
used to force the Security Alert popup and provide additional information.
The security alert popup can be forced by a hostname mismatch or by using an unknown CA as
follows:
<SSL-Intercept>
ssl.forward_proxy.hostname("WE ARE WATCHING YOU") \
ssl.forward_proxy.issuer_keyring(new-private-ca) \
ssl.forward_proxy.splash_text("This session is being monitored.") \
ssl.forward_proxy.splash_url(http://example.com/ssl-intercept-policy.html)
343
Volume 10: Content Policy Language Guide
ssl.forward_proxy.issuer_keyring( )
Specify the CA keyring for signing the forged certificate that is used for SSL interception.
The default value is auto. The default behavior is to use the keyring specified in configuration by the
SGOS#(config ssl) intercept CLI command.
Syntax
ssl.forward_proxy.issuer_keyring (auto|KeyringId)
Example
When the browser receives a server certificate signed by an unknown CA or with a hostname that
does not match the URL hostname, it shows a security alert popup. This popup can be leveraged as an
SSL level splashing mechanism. Various combinations of the ssl.forward_proxy.* properties can
be used to force the Security Alert popup and provide additional information.
The security alert popup can be forced by a hostname mismatch or by using an unknown CA as
follows:
<SSL-Intercept>
ssl.forward_proxy.hostname("WE ARE WATCHING YOU") \
ssl.forward_proxy.issuer_keyring(new-private-ca) \
ssl.forward_proxy.splash_text("This session is being monitored.") \
ssl.forward_proxy.splash_url(http://example.com/ssl-intercept-policy.html)
344
Chapter 4: Property Reference
ssl.forward_proxy.server_keyring( )
Specify a static server certificate and keypair for use during SSL interception.
When an SSL connection is intercepted, the normal behavior is to dynamically generate a forged
server certificate and keypair. The contents of this forged certificate are controlled by the .hostname,
.splash_text, .splash_url and .issuer_keyring members of the ssl.forward_proxy family of properties.
The ssl.forward_proxy.server_keyring property overrides this behavior, and allows you to specify a
static certificate and keypair which will be used instead. It is normally only used for debugging.
The default value is no, which causes a forged certificate to be dynamically generated.
Syntax
ssl.forward_proxy.server_keyring (no|KeyringId)
Example
<SSL-Intercept>
ssl.forward_proxy.server_keyring(my_keyring)
345
Volume 10: Content Policy Language Guide
ssl.forward_proxy.splash_text( )
Specify informational text to be inserted into the forged certificate that is used for SSL interception. .
The default value is "". The string argument is limited to 200 printable characters.
Syntax
ssl.forward_proxy.splash_text(String)
Example
When the browser receives a server certificate signed by an unknown CA or with a hostname that
does not match the URL hostname, it shows a security alert popup. This popup can be leveraged as an
SSL level splashing mechanism. Various combinations of the ssl.forward_proxy.* properties can
be used to force the Security Alert popup and provide additional information.
The security alert popup can be forced by a hostname mismatch or by using an unknown CA as
follows:
<SSL-Intercept>
ssl.forward_proxy.hostname("WE ARE WATCHING YOU") \
ssl.forward_proxy.issuer_keyring(new-private-ca) \
ssl.forward_proxy.splash_text("This session is being monitored.") \
ssl.forward_proxy.splash_url(http://example.com/ssl-intercept-policy.html)
346
Chapter 4: Property Reference
ssl.forward_proxy.splash_url( )
Specify an informational url to be inserted into the forged certificate that is used for SSL interception.
The default value is "".
Syntax
ssl.forward_proxy.splash_url(""|Url)
Example
When the browser receives a server certificate signed by an unknown CA or with a hostname that
does not match the URL hostname, it shows a security alert popup. This popup can be leveraged as an
SSL level splashing mechanism. Various combinations of the ssl.forward_proxy.* properties can be
used to force the Security Alert popup and provide additional information.
The security alert popup can be forced by a hostname mismatch or by using an unknown CA as
follows:
<SSL-Intercept>
ssl.forward_proxy.hostname("WE ARE WATCHING YOU") \
ssl.forward_proxy.issuer_keyring(new-private-ca) \
ssl.forward_proxy.splash_text("This session is being monitored.") \
ssl.forward_proxy.splash_url(http://example.com/ssl-intercept-policy.html)
347
Volume 10: Content Policy Language Guide
streaming.transport( )
Determines the upstream transport mechanism to be used for this streaming transaction. This setting
is not definitive. The ability to use the specified transport mechanism depends on the capabilities of
the selected forwarding host.
Syntax
streaming.transport(auto|tcp|http)
where:
• auto—Use the default transport for the upstream connection, as determined by the
originating transport and the capabilities of any selected forwarding host.
• tcp—Use TCP as the upstream transport mechanism.
• http—Use HTTP as the upstream transport mechanism.
See Also
• Conditions: bitrate=, live=, streaming.client=, streaming.content=
348
Chapter 4: Property Reference
terminate_connection( )
The terminate_connection( ) property is used in an <Exception> layer to drop the connection
rather than return the exception response. The yes option terminates the connection instead of
returning the response.
Syntax
terminate_connection(yes|no)
The default is no.
349
Volume 10: Content Policy Language Guide
trace.destination( )
Used to change the default path to the trace output file. By default, policy evaluation trace output is
written to an object in the cache accessible using a console URL of the following form:
http://SG_appliance_IP_address:8081/Policy/Trace/path
Syntax
trace.destination(path)
where path is, by default, default_trace.html. You can change path to a filename or
directory path, or both. If only a directory is provided, the default trace filename is used.
Example
; Change directory location of trace output file to
; http://SG_appliance_IP_address:8081/Policy/Trace/test/default_trace.html
trace.destination(test/)
; Change trace output file location to
; http://SG_appliance_IP_address:8081/Policy/Trace/test/phase_2.html
trace.destination(test/phase_2.html)
See Also
• Properties: trace.request(), trace.rules()
• Appendix D: "CPL Substitutions".
350
Chapter 4: Property Reference
trace.request( )
Determines whether detailed trace output is generated for the current request. The default value is no,
which produces no output. Trace output is generated at the end of a request, and includes request
parameters, property settings, and the effects of all actions taken. Output tracing can be set
conditionally by creating a rule that combines this property with conditions such as url= or
client.address=.
By default, trace output is written to an object accessible using the following console URL:
http://SG_appliance_IP_address:8081/Policy/Trace/default_trace.html
The trace output location can be controlled using the trace.destination( ) property.
Note: Tracing is best used temporarily, such as for troubleshooting; the log_message( ) action is
best for on-going monitoring.
Syntax
trace.request(yes|no)
The default value is no.
Example
; Generate trace details when a specific URL is requested.
url=//www.example.com/confidential trace.request(yes)
See Also
• Properties: trace.destination(), trace.rules()
351
Volume 10: Content Policy Language Guide
trace.rules( )
Determines whether trace output is generated showing policy rule evaluation for the transaction.
By default, trace output is written to an object accessible using the following console URL:
http://SG_appliance_IP_address:8081/Policy/Trace/default_trace.html
The trace output location can be controlled using the trace.destination( ) property.
Note: Tracing is best used temporarily, such as for troubleshooting; the log_message( ) action is
best for on-going monitoring.
Syntax
trace.rules(yes|no|all)
where:
• yes—Generates output only for rules that match the request.
• all—Additionally shows which rules were skipped because one or more of their
conditions were false or not applicable to the current transaction; displays the specific
condition in the rule that failed.
• no—Suppresses output associated with policy rule evaluation.
The default value is no.
Example
; Generate trace messages.
<proxy>
trace.rules(yes) trace.request(yes)
See Also
• Properties: trace.destination(), trace.request()
352
Chapter 4: Property Reference
trust_destination_ip()
This property allows the SG to honor client's destination IP when it intercepts client requests
transparently.
The Proxy SG will trust the client provided destination IP and not do the DNS lookup for the HOST
value in appropriate cases. This feature will not apply (i.e. existing behaviour will be preserved) if :
a. The Proxy SG recieves the client requets in explicit proxy deployment cases.
b. The Proxy SG has forwarding rules configured for the given HOST value.
c. The Proxy SG will connect upstream on SOCKS.
d. The Proxy SG will connect upstream using ICP.
By default it is configured as enabled.
Syntax
trust_destination_ip(yes|no)
The default value is taken from a global configuration setting
Example
Disable trusting destination IP.
<forward>
proxy.address=10.10.167.0/24 trust_destination_ip(no)
353
Volume 10: Content Policy Language Guide
ttl( )
Sets the time-to-live (TTL) value of an object in the cache, in seconds. Upon expiration, the cached
copy is considered stale and will be re-obtained from the origin server when next accessed. However,
this property has an effect only if the following HTTP command line option is enabled: Force
explicit expirations: Never serve after.
If the above option is not set, the SG appliance’s freshness algorithm determines the time-to-live
value.
Syntax
ttl(seconds)
where seconds is an integer, specifying the number of seconds an object remains in the cache
before it is deleted. The maximum value is 4294967295, or about 136 years.
The default value is specified by configuration.
Example
; Delete the specified cached objects after 30 seconds.
url=//www.example.com/dyn_images ttl(30)
See Also
• Properties: advertisement( ), cache( )
354
Chapter 4: Property Reference
ua_sensitive( )
Used to modify caching behavior by declaring that the response for a given object is expected to vary
based on the user agent used to retrieve the object. Set to yes to specify this behavior.
Using ua_sensitive(yes) has the same effect as cache(no).
Note: Remember that any conflict among CPL property settings is resolved by CPL evaluation logic,
which uses the property value that was last set when evaluation ends.
Syntax
ua_sensitive(yes|no)
The default value is no.
See Also
• Properties: advertisement( ), always_verify( ), bypass_cache( ), cache( ),
cookie_sensitive( ), delete_on_abandonment( ), direct( ), dynamic_bypass( ),
force_cache( ), pipeline( ), refresh( ), ttl( )
355
Volume 10: Content Policy Language Guide
user.login.log_out( )
Log out the current user from the current ip address.
This property is used to log out a user from the current ip address. When this property is executed, the
current login for the user is logged out. The user will need to re-authenticate at this ip address before
future transactions can proceed.
Syntax
user.login.log_out(yes|no)
The default value is yes.
Example
Log out the user whenever they visit the log out page.
<proxy>
url="http://company.com/log_out.html" user.login.log_out(yes)
356
Chapter 4: Property Reference
user.login.log_out_other( )
Log out the current user from logins other than the current ip address.
This property is used to log out any other logins of the user on ip addresses other than the current ip
address. When this property is executed, the all logins of the user on ip address other than the current
ip address are logged out. The user will need to re-authenticate at the other ip address before future
transactions at those ip addresses can proceed.
Syntax
user.login.log_out_other(yes|no)
The default value is yes.
Example
Log out the user from other workstations if they are logged in more than once.
<proxy>
user.login.count=2.. user.login.log_out_other(yes)
357
Volume 10: Content Policy Language Guide
358
Chapter 5: Action Reference
An action takes arguments and is wrapped in a user-named action definition block. When the action
definition is called from a policy rule, any actions it contains operate on their respective arguments.
Within a rule, named action definitions are enabled and disabled using the action( )property.
Actions take the following general form:
action(argument1, ...)
An action block is limited to the common subset among the allowed layers of each of the actions it
contains. Actions appear only within action definitions. They cannot appear in <Admin> layers.
Argument Syntax
The allowed syntax for action arguments depends on the action.
• String—A string argument must be quoted if it contains whitespace or other special characters.
For example: log_message(“Access alert”).
• Enumeration—Actions such as delete( ) use as an argument a token specifying the transaction
component on which to act. For example: a header name such as request.header.Referer.
• Regular expression—Several actions take regular expressions. For more information about writing
regular expressions, see Appendix E: "Using Regular Expressions".
• Variable substitution—The quoted strings in some action arguments can include variable
substitution substrings. These include the various versions of the replacement argument of the
redirect( ), rewrite( ), and rewrite( ) actions, and the string argument in the append( ),
log_message( ), and set(header, string) actions. A variable substitution is a substring of the
form:
$(name)
where name is one of the allowed substitution variables.
For a complete list of substitutions, see Appendix D: "CPL Substitutions".
Action Reference
The remainder of this chapter lists the actions and their accepted values. It also provides the context in
which each action can be used and examples of how to use them.
359
Volume 10: Content Policy Language Guide
append( )
Appends a new component to the specified header.
Note: An error results if two header modification actions modify the same header. This results in a
compile time error if the conflicting actions are within the same action definition block. A
runtime error is recorded in the event log if the conflicting actions are defined in different
blocks.
Syntax
append(header, string)
append(im.message.text, string)
where:
• header—A header specified using the following form. For a list of recognized headers,
including headers that support field repetition, see Appendix C: "Recognized HTTP
Headers".
• request.header.header_name—Identifies a recognized HTTP request header.
• response.header.header_name—Identifies a recognized HTTP response header.
• request.x_header.header_name—Identifies any request header, including custom
headers.
• response.x_header.header_name—Identifies any response header, including
custom headers.
• string—A quoted string that can optionally include one or more variable substitutions.
• im.message.text—Appends the specified string to the end of the instant message text.
See Also
• Actions: delete( ), delete_matching( ), rewrite(header, regex_pattern,
replacement_component), set(header, string)
360
Chapter 5: Action Reference
delete( )
Deletes all components of the specified header.
Note: An error results if two header modification actions modify the same header. The error is noted
at compile time if the conflicting actions are within the same action definition block. A
runtime error is recorded in the event log if the conflicting actions are defined in different
blocks.
Syntax
delete(header)
where:
• header—A header specified using the following form. For a list of recognized headers,
see Appendix C: "Recognized HTTP Headers".
• request.header.header_name—Identifies a recognized HTTP request header.
• response.header.header_name—Identifies a recognized HTTP response header.
• request.x_header.header_name—Identifies any request header, including custom
headers.
• response.x_header.header_name—Identifies any response header, including
custom headers.
• exception.response.header.header_name—Identifies a recognized HTTP
response header from the exception response.
Example
; Delete the Referer request header, and also log the action taken.
define action DeleteReferer
log_message("Referer header deleted: $(request.header.Referer)")
delete(request.header.Referer)
end
See Also
• Actions: append( ), delete_matching( ), rewrite(header, regex_pattern,
replacement_component), set(header, string)
361
Volume 10: Content Policy Language Guide
delete_matching( )
Deletes all components of the specified header that contain a substring matching a regular-expression
pattern.
Note: An error results if two header modification actions modify the same header. The error is noted
at compile time if the conflicting actions are within the same action definition block. A
runtime error is recorded in the event log if the conflicting actions are defined in different
blocks.
Syntax
delete_matching(header, regex_pattern)
where:
• header—A header specified using the following form. For a list of recognized headers,
see Appendix C: "Recognized HTTP Headers".
• request.header.header_name— Identifies a recognized HTTP request header.
• response.header.header_name—Identifies a recognized HTTP response header.
• request.x_header.header_name—Identifies any request header, including custom
headers.
• response.x_header.header_name—Identifies any response header, including
custom headers.
• regex_pattern—A quoted regular-expression pattern. For more information, see
Appendix E: "Using Regular Expressions".
See Also
• Actions: append( ), delete( ), rewrite(header, regex_pattern,
replacement_component), set(header, string)
362
Chapter 5: Action Reference
im.alert( )
Deliver a message in-band to the instant messaging user. The text appears in the instant message
window.
This action is similar to log_message( ), except that it appends entries to a list in the instant
messaging transaction that the IM protocol renders in an appropriate way. Multiple alerts can be
appended to a transaction. The protocol determines how multiple alerts appear to the user.
Syntax
im.alert(text)
where text is a quoted string that can optionally include one or more variable substitutions.
See Also
• Actions: log_message( )
• Appendix D: "CPL Substitutions"
363
Volume 10: Content Policy Language Guide
log_message( )
Writes the specified string to the SG appliance event log.
Events generated by log_message( ) are viewed by selecting the Policy messages event logging level
in the Management Console.
Syntax
log_message(string)
where string is a quoted string that can optionally include one or more variable
substitutions.
Example
; Log the action taken, and include the original value of the Referer header.
define action DeleteReferer
log_message("Referer header deleted: $(request.header.Referer)")
delete(request.header.Referer)
end
See Also
• Actions: notify_email( ), notify_snmp( )
• Properties: access_log( ), log.rewrite( ), log.suppress( )
• Appendix D: "CPL Substitutions"
364
Chapter 5: Action Reference
notify_email( )
Sends an e-mail notification to the list of recipients specified in the Event Log mail configuration. The
sender of the e-mail appears as Primary_SG appliance_IP_address -
configured_appliance_hostname>. You can specify multiple notify_email actions, which may
result in multiple mail messages for a single transaction.
The e-mail is sent when the transaction terminates. The e-mail is sent to the list of recipients specified
in the Event Log mail configuration.
Syntax
notify_email(subject, body)
where subject and body are quoted strings that can optionally include one or more variable
substitutions.
Example
define condition restricted_sites
url.domain=a_very_bad_site
...
end
<proxy>
condition=restricted_sites action.notify_restricted(yes)
See Also
• Actions: log_message( ), notify_snmp( )
• Appendix D: "CPL Substitutions"
365
Volume 10: Content Policy Language Guide
notify_snmp( )
Multiple notify_snmp actions may be specified, resulting in multiple SNMP traps for a single
transaction.
The SNMP trap is sent when the transaction terminates.
Syntax
notify_snmp(message)
where message is a quoted string that can optionally include one or more variable
substitutions.
See Also
• Actions: log_message( ), notify_email( )
• Appendix D: "CPL Substitutions"
366
Chapter 5: Action Reference
redirect( )
Ends the current HTTP transaction and returns an HTTP redirect response to the client by setting the
policy_redirect exception. Use this action to specify an HTTP 3xx response code, optionally set
substitution variables based on the request URL, and generate the new Location response-header URL
after performing variable substitution.
Note: You can't use a redirect to override an exception. Exceptions always override redirects.
FTP over HTTP requests are not redirected for Microsoft Internet Explorer clients. To avoid this issue,
do not use the redirect( ) action when the url.scheme=ftp condition is true. For example, if the
http_redirect action definition contains a redirect( ) action, you can use the following rule:
url.scheme=ftp action.http_redirect(no)
Note: An error results if two redirect( ) actions conflict. The error is noted at compile time if the
conflicting actions are within the same action definition block. A runtime error is recorded in
the event log if the conflicting actions are defined in different blocks.
Important: It is possible to put the browser into an infinite redirection loop if the URL that the
browser is being redirected to also triggers a policy-based redirect response.
Syntax
redirect(response_code, regex_pattern, redirect_location)
where:
• response_code—An HTTP redirect code used as the HTTP response code; supported
codes are 301, 302, 305, and 307.
• regex_pattern—A quoted regular-expression pattern that is compared with the request
URL based on an anchored match. If the regex_pattern does not match the request URL,
the redirect action is ignored. A regex_pattern match sets the values for substitution
variables. If no variable substitution is performed by the redirect_location string,
specify ".* " for regex_pattern to match all request URLs. For more information about
regular expressions, see Appendix E: "Using Regular Expressions".
• redirect_location—A quoted string that can optionally include one or more variable
substitutions.
This string is an absolute or relative url that is included in the redirect response, as the
value of the Location: header. In normal usage, the redirect_location is an absolute url like
http://www.example.com/, which instructs the client to redirect to the specified URL. If
the redirect_location does not begin with "<scheme>://", where scheme is usually
http, then it will be interpreted by the client as a relative URL, which is interpreted
relative to the original request URL. For more information, see Appendix D: "CPL
Substitutions".
367
Volume 10: Content Policy Language Guide
See Also
• Actions: rewrite(url.host, host_regex_pattern, replacement_host), rewrite(url,
regex_pattern, redirect_location), set(url.port, port_number)
• Conditions: exception.id=
• Appendix D: "CPL Substitutions"
368
Chapter 5: Action Reference
rewrite( )
Rewrites the request URL, URL host, or components of the specified header if it matches the
regular-expression pattern. This action is often used in conjunction with the URL rewrite form of the
transform action in a server portal application.
Note: The URL form of the rewrite( ) action does not rewrite some URL components for Windows
Media (MMS) transactions. The URL scheme, host, and port are restored to their original
values and an error logged if the URL specified by redirect_location attempts to change
these components.
An error results if the URL or URL host form of this action conflicts with another URL
rewriting action. The error is noted at compile time if the conflicting actions are within the
same action definition block. A runtime error is recorded in the event log if the conflicting
actions are defined in different blocks.
Similarly, an error results if two header modifications act on the same header.
HTTPS Limitation
Only the host and port are available for rewriting by the URL or URL host form when the client
browser is using a proxy for an HTTPS connection and the CONNECT or TUNNEL method is used.
This is because the URL path is encrypted and unavailable for rewriting.
Syntax
rewrite(url, regex_pattern, redirect_location[, URL_form1, ...])
rewrite(url.host, regex_pattern, replacement_host[, URL_form1, ...])
rewrite(header, regex_pattern, replacement_component)
where:
• url—Specifies a rewrite of the entire URL.
• url.host—Specifies a rewrite of the host portion of the URL.
• header—Specifies the header to rewrite, using the following form. For a list of recognized
headers, see Appendix C: "Recognized HTTP Headers".
• request.header.header_name—Identifies a recognized HTTP request header.
• response.header.header_name—Identifies a recognized HTTP response header.
• request.x_header.header_name—Identifies any request header, including custom
headers.
• response.x_header.header_name—Identifies any response header, including
custom headers.
• regex_pattern—A quoted regular-expression pattern that is compared with the URL,
host or header as specified, based on an anchored match. If the regex_pattern does not
match, the rewrite action is ignored. A regex_pattern match sets the values for
substitution variables. If the rewrite should always be applied, but no variable
substitution is required for the replacement string, specify ".* " for regex_pattern. For
more information about regular expressions, see Appendix E: "Using Regular
Expressions".
369
Volume 10: Content Policy Language Guide
• redirect_location—A quoted string that can optionally include one or more variable
substitutions, which replaces the entire URL once the substitutions are performed. The
resulting URL is considered complete, and replaces any URL that contains a substring
matching the regex_pattern substring. Sub-patterns of the regex_pattern matched can
be substituted in redirect_location using the $(n) syntax, where n is an integer from 1
to 32, specifying the matched sub-pattern. For more information, see Appendix D: "CPL
Substitutions".
• replacement_host—A quoted string that can optionally include one or more variable
substitutions, which replaces the host portion of the URL once the substitutions are
performed. Note that the resulting host is considered complete, and it replaces the host in
the URL forms specified. Sub-patterns of the regex_pattern matched can be substituted
in replacement_host using the $(n) syntax, where n is an integer from 1 to 32,
specifying the matched sub-pattern. For more information, see Appendix D: "CPL
Substitutions".
• URL_form1, ...—An optional list of up to three forms of the request URLs that will have
the URL or host replaced. If this parameter is left blank, all three forms are rewritten. The
following are the possible values:
• log—Request URL used when generating log messages.
• cache—Request URL used to address the object in the local cache.
• server—Request URL sent to the origin server.
• replacement_component—A quoted string that can optionally include one or more
variable substitutions, which replaces the entire component of the header matched by the
regex_pattern substring. Sub-patterns of the regex_pattern matched can be
substituted in replacement_component using the $(n) syntax, where n is an integer from
1 to 32, indicating the matched sub-pattern. For more information, see Appendix D: "CPL
Substitutions".
Discussion
Any rewrite of the server form of the request URL must be respected by policy controlling upstream
connections. The server form of the URL is tested by the server_url= conditions, which are the only
URL tests allowed in <Forward> layers.
All forms of the URL are available for access logging. The version of the URL that appears in a specific
access log is selected by including the appropriate substitution variable in the access log format:
• c-uri—The original URL
• cs-uri—The log URL, used when generating log messages
• s-uri—The cache URL, used to address the object in the local cache
• sr-uri—The server URL, used in the upstream request
In the absence of actions that modify the URL, all of these substitution variables represent the same
value.
370
Chapter 5: Action Reference
Example
rewrite(url, "^http://www\.example\.com/(.*)",
"http://www.server1.example.com/$(1)")
See Also
• Actions: append( ), delete( ), delete_matching( ), redirect( ), set( ), transform
• Conditions: request.header.header_name=, request.header.header_name.address=,
request.x_header.header_name=, request.x_header.header_name.address=,
response.header.header_name=, response.x_header.header_name=, server_url=
371
Volume 10: Content Policy Language Guide
set( )
Sets the specified header to the specified string after deleting all components of the header.
Note: An error results if two header modification actions modify the same header. The error is noted
at compile time if the conflicting actions are within the same action definition block. A
runtime error is recorded in the event log if the conflicting actions are defined in different
blocks.
HTTPS Limitation
Only the host and port are available for setting when the client browser is using a proxy for an HTTPS
connection and the CONNECT or TUNNEL method is used. This is because the URL path is
encrypted and unavailable for setting.
Syntax
set(header, string)
set(im.message.text, value)
set(url.port, port_number [, URL_form1, URL_form2, ...])
where:
• header—A header specified using the following form. For a list of recognized headers,
see Appendix C: "Recognized HTTP Headers".
• request.header.header_name—Identifies a recognized HTTP request header.
• response.header.header_name—Identifies a recognized HTTP response header.
• request.x_header.header_name—Identifies any request header, including custom
headers.
• response.x_header.header_name—Identifies any response header, including
custom headers.
• exception.response.header.header_name—Identifies a recognized HTTP
response header from the exception response.
• exception.response.x_header.header_name—Identifies any response header
from the exception response, including custom headers.
• string—A quoted string that can optionally include one or more variable substitutions,
which replaces the specified header components once the substitutions are performed.
• im.message.text, value—Sets the instant message text to the specified value.
• port_number—The port number that the request URL is set to. The range is an integer
between 1 and 65535.
• URL_form1, URL_form2, ...—An optional list of up to three forms of the request URLs
that have the port number set. If this parameter is left blank, all three forms of the request
URL are rewritten. The possible values are the following:
• log—Request URL used when generating log messages.
372
Chapter 5: Action Reference
Discussion
Any change to the server form of the request URL must be respected by policy controlling upstream
connections. The server form of the URL is tested by the server_url= conditions, which are the only
URL tests allowed in <Forward> layers.
All forms of the URL are available for access logging. The version of the URL that appears in a specific
access log is selected by including the appropriate substitution variable in the access log format:
• c-uri—The original URL.
• cs-uri—The log URL, used when generating log messages.
• s-uri—The cache URL, used to address the object in the local cache.
• sr-uri—The server URL, used in the upstream request.
In the absence of actions that modify the URL, all of these substitution variables represent the same
value.
Example
; Modifies the URL port component to 8081 for requests sent to the server and cache.
set(url.port, 8081, server, cache)
See Also
• Actions: append( ), delete( ), delete_matching( ), redirect( ), rewrite(url.host,
regex_pattern, replacement_host), rewrite(url, regex_pattern, redirect_location)
373
Volume 10: Content Policy Language Guide
transform
Invokes an active_content, javascript, or URL_rewrite transformer. The invoked transformer takes
effect only if the transform action is used in a define action definition block, and that block is in turn
enabled by an action( ) property.
Note: Any transformed content is not cached, in contrast with content that has been sent to a virus
scanning server. This means the transform action can be safely triggered based on any
condition, including client identity and time of day.
Syntax
transform transformer_id
where transformer_id is a user-defined identifier for a transformer definition block. This
identifier is not case-sensitive.
Example
; The transform action is part of an action block enabled by a rule.
<proxy>
url.domain=!my_site.com action.strip_active_content(yes)
; transformer definition
define active_content strip_with_indication
374
Chapter 5: Action Reference
See Also
• Properties: action( )
• Definitions: define action, transform active_content, transform url_rewrite
375
Volume 10: Content Policy Language Guide
376
Chapter 6: Definition Reference
Definition Names
There are various types of named definitions. Each of these definitions is given a user-defined name
that is then used in rules to refer to the definitions. The user-defined labels used with definitions are
not case-sensitive. Characters in labels may include the following:
• letters
• numbers
• space
• period
• underscore
• hyphen
• forward slash
• ampersand
The first character of the name must be a letter or underscore. If spaces are included, the name must be
a quoted string.
Only alphanumeric, underscore, and dash characters can be used in the name given to a defined
action.
The remainder of this chapter lists the definitions and their accepted values. It also provides tips as to
where each definition can be used and examples of how to use them.
377
Volume 10: Content Policy Language Guide
define action
Binds a user-defined label to a sequence of action statements. The action( ) property has syntax that
allows for individual action definition blocks to be enabled and disabled independently, based on the
policy evaluation for the transaction. When an action definition block is enabled, any action
statements it contains operate on the transaction as indicated by their respective arguments. See
Chapter 5: "Action Reference" for more information about the various action statements available.
Note: Action statements that must be performed in a set sequence and cannot overlap should be
listed within a single action definition block.
Syntax
define action label
list of action statements
end
where:
• label—A user-defined identifier for an action definition. Only alphanumeric,
underscore, and dash characters can be used in the label given to a defined action.
• list of action statements—A list of actions to be carried out in sequence. See
Chapter 5: "Action Reference" for the available actions.
Example
The following is a sample action given the name scrub_private_info, that clears the From and
Referer headers (which normally could be used to identify the user and where they clicked from) in
any request going to servers not in the internal domain.
<cache>
url.domain=!my_internal_site.com action.scrub_private_info(yes)
define action scrub_private_info
set( request.header.From, "" )
set( request.header.Referer, "" )
end
Notice that the object on which the set( ) action operates is given in the first argument, and then
appropriate values follow, in this case, the new value for the specified header. This is common to
many of the actions.
378
Chapter 6: Definition Reference
See Also
• Properties: action( )
• Definitions: transform active_content, transform url_rewrite
• Chapter 5: "Action Reference".
379
Volume 10: Content Policy Language Guide
define active_content
Defines rules for removing or replacing active content in HTML or ASX documents. This definition
takes effect only if it is invoked by a transform action in a define action definition block, and that
block is in turn enabled an action( ) property as a result of policy evaluation.
Active content transformation acts on the following four HTML elements in documents: <applet>,
<embed>, <object>, and <script>. In addition, a script transformation removes any JavaScript
content on the page. For each tag, the replacement can either be empty (thus deleting the tag and its
content) or new text that replaces the tag. Multiple tags can be transformed in a single active content
transformer. Pages served over an HTTPS tunneled connection are encrypted so the content cannot be
modified.
Note: Transformed content is not cached, in contrast with content that has been sent to a virus
scanning server. Therefore, a transformer can be safely triggered based on any condition,
including client identity and time of day.
Syntax
define active_content transformer_id
tag_replace HTML_tag_name << text_end_delimiter
[replacement_text]
text_end_delimiter
[tag_replace ...]
...
end
where:
• transformer_id—A user-defined identifier for a transformer definition block. Used to
invoke the transformer using the transform action in a define action definition block.
• HTML_tag_name—The name of an HTML tag to be removed or replaced, as follows:
• applet—Operates on the <applet> element, which places a Java applet on a Web
page.
• embed—Operates on the <embed> element, which embeds an object, such as a
multimedia file, on a Web page.
• object—Operates on the <object> element, which places an object, such as an
applet or media file, on a Web page.
• script—Operates on the <script> element, which adds a script to a Web page. Also
removes any JavaScript entities, strings, or events that may appear on the page.
If the tag_replace keyword is repeated within the body of the transformer, multiple
HTML tags can be removed or replaced.
• text_end_delimiter—A user-defined token that does not appear in the replacement
text and does not use quotes or whitespace. The delimiter is defined on the first line, after
the required double angle brackets (<<). All text that follows, up to the second use of the
delimiter, is used as the replacement text.
380
Chapter 6: Definition Reference
Example
<proxy>
url.domain=!my_site.com action.strip_active_content(yes)
define active_content strip_with_indication
tag_replace applet <<EOT
<B>APPLET content has been removed</B>
EOT
tag_replace embed <<EOT
<B>APPLET content has been removed</B>
EOT
tag_replace object <<EOT
<B>OBJECT content has been removed</B>
EOT
tag_replace script <<EOT
<B>SCRIPT content has been removed</B>
EOT
end
define action strip_active_content
transform strip_with_indication
end
See Also
• Actions: transform
• Definitions: define action, define url_rewrite
• Properties: action( )
381
Volume 10: Content Policy Language Guide
define category
Category definitions are used to extend vendor content categories or to create your own. The
category_name definition can be used anywhere a content filter category name would normally be
used, including in category= tests.
Definitions can include other definitions to create a hierarchy. For example, sports could include
football by including category=football in the definition for sports. A defined category can have at
most one parent category (multiple inheritance is not allowed).
Multiple definitions using the same category_name are coalesced together.
When policy tests a request URL to determine if it is in one of the categories specified by a trigger, all
sub-categories are also checked (see Examples).
Syntax
define category category_name
urlpaths
end
where:
• category_name—If category_name matches the name of an existing category from the
configured content filtering service, this is used to extend the coverage of that category;
otherwise it defines a new user defined category. category_name can be used anywhere a
content filter category name would normally be used, including in category= tests.
• urlpaths—A list of domain suffix or path prefix expressions, as used in the url.domain=
condition.You only need to specify a partial URL:
• Hosts and subdomains within the domain you specify are automatically included.
• If you specify a path, all paths with that prefix will be included (if you specify no
path, the entire site is included).
Examples
The following example illustrates some of the variations allowed in a category definition:
define category Grand_Canyon
kaibab.org
www2.nature.nps.gov/ard/parks/grca/
nps.gov/grca/
grandcanyon.org
end
382
Chapter 6: Definition Reference
The following definitions define the categories sports and football, and make football a sub-category
of sports:
define category sports
sports.com
sportsworld.com
category=football ; include subcategory
end
define category football
nfl.com
cfl.ca
end
The following policy needs only to refer to the sports category to also test the sub-category football:
<Proxy>
deny category=sports ; includes subcategories
For more information on using category= tests, including examples, refer to Volume 8: Managing
Content.
See Also
• Conditions: category=
• Properties: action( )
383
Volume 10: Content Policy Language Guide
define condition
Binds a user-defined label to a set of conditions for use in a condition= expression.
For condition definitions, the manner in which the condition expressions are listed is significant.
Multiple condition expressions on one line, separated by whitespace, are considered to have a Boolean
AND relationship. However, the lines of condition expressions are considered to have a Boolean OR
relationship.
Performance optimized condition definitions are available for testing large numbers of URLs. See
define url condition, define url.domain condition, and define server_url.domain
condition.
Syntax
define condition label
condition_expression ...
...
end
where:
• label—A user-defined identifier for a condition definition. Used to call the definition
from an action.action_label( ) property.
• condition_expression—Any of the conditions available in a rule. The layer and timing
restrictions for the defined condition depend on the layer and timing restrictions of the
contained expressions.
The condition=condition is one of the expressions that can be included in the body of a
define condition definition block. In this way, one condition definition block can call
another condition-related definition block, so that they are in effect nested. Circular references
generate a compile error.
Example
This example illustrates a simple virus scanning policy designed to prevent some traffic from going to
the scanner. Some file types are assumed to be at low risk of infection (some virus scanners will not
scan certain file types), and some are assumed to have already been scanned when they were loaded
on the company’s servers.
Note: The following policy is not a security recommendation, but an illustration of a technique. If
you choose to selectively direct traffic to your virus scanner, you should make your own
security risk assessments based on current information and knowledge of your virus scanning
vendor’s capabilities.
384
Chapter 6: Definition Reference
See Also
• Conditions: category=, condition=
• Properties: action.action_label( )
385
Volume 10: Content Policy Language Guide
define javascript
A javascript definition is used to define a javascript transformer, which adds javascript that you supply
to HTML responses.
Syntax
define javascript transformer_id
javascript-statement
[javascript-statement]
…
end
where:
• transformer_id—A user-defined identifier for a transformer definition block. Used to
invoke the transformer using the transform action in a define action definition block.
• A javascript-statement has the following syntax:
javascript-statement ::= section-type replacement
section-type ::= prolog | onload | epilog
replacement ::= << endmarker newline lines-of-text newline endmarker
This allows you to specify a block of javascript to be inserted at the beginning of the
HTML page (prolog), to be inserted at the end of the HMTL page (epilog), and to be
executed when parsing is complete and the page is loaded (onload). Each of the section
types is optional.
Example
The following is an example of a javascript transformer that adds a message to the top of each Web
page, used as part of a simple content filtering application:
define javascript js_transformer
onload <<EOS
var msg = "This site is restricted. Your access has been logged.";
var p = document.createElement("p");
p.appendChild(document.createTextNode(msg));
document.body.insertBefore(p, document.body.firstChild);
EOS
end
<proxy>
category=restricted action.js_action(yes)
The VPM uses javascript transformers to implement popup ad blocking.
386
Chapter 6: Definition Reference
See Also
• Actions: transform
• Definitions: define action
• Properties: action( )
387
Volume 10: Content Policy Language Guide
define policy
A policy definition defines a named policy macro, which is a sequence of policy layers that can be
called by name from other layers. All layers in a policy macro must be of the same type, which is
declared on the first line of the definition.
Syntax
define LayerType policy MacroName
Layer1
Layer2
...
end
For example, here is a policy macro of type proxy:
define proxy policy WebAccessPolicy
<proxy>
DENY hour=9..17 category=NotBusinessRelated
DENY category=IllegalOrOffensive
end
A policy macro is called from another layer using the syntax policy.MacroName within a rule. The
calling layer must have the same type as the policy macro. For example:
<proxy> url.address=TheInternet
group=Operator ALLOW
group=Employee policy.WebAccessPolicy
DENY
A policy macro call (policy.MacroName) is similar to a CPL property setting: it is only evaluated if all
the conditions on the rule line are true. When a macro call is evaluated, all of the layers in the
corresponding policy definition are evaluated, setting some properties. (A policy macro that sets no
properties has no effect when evaluated.)
When a rule is matched during policy evaluation, all of the property settings and macro calls in that
rule are evaluated from left to right, with later property settings overriding earlier property settings.
This means that all property settings before a macro call act as defaults, and all property settings after
the macro call act as overrides.
A policy definition can contain calls to other policy macros. However, recursive calls and circular call
chains are not allowed.
A policy definition cannot contain other definitions.
388
Chapter 6: Definition Reference
Note: This condition is for use in the <Forward> layers and takes into account the effect of any
rewrite( ) actions on the URL. Because any rewrites of the URL intended for servers or
other upstream devices must be respected by <Forward> layer policy, conditions that test the
unrewritten URL are not allowed in <Forward> layers. Instead, this condition is provided.
Syntax
define server_url.domain condition label
domain_suffix_pattern [condition_expression ...]
...
end
where:
• label—A user-defined identifier for a domain condition definition. Used in a
condition= condition.
• domain_suffix_pattern—A URL pattern that includes a domain name (domain), as a
minimum. See the url= condition reference for a complete description.
• condition_expression ...—An optional condition expression, using any of the
conditions available in a rule, that are allowed in a <Forward> layer. For more
information, see Chapter 3: "Condition Reference".
The condition= condition is one of the expressions that can be included in the body of a
define server_url.domain condition definition block, following a URL pattern. In this
way, one server_url.domain definition block can call another condition-related definition
block, so that they are in effect nested. See the example in the define condition definition
block topic. Any referenced condition must be valid in a <Forward> layer.
389
Volume 10: Content Policy Language Guide
Example
define server_url.domain condition allowed
inventory.example.com
affinityclub.example.com
end
<Forward>
condition=!allowed access_server(no)
See Also
Condition: condition=, server_url.domain=
Definitions: define url.domain condition
390
Chapter 6: Definition Reference
define string
Define a named, multi-line character string.
Syntax
define string StringName
>first line of text
>second line of text
;comments and blank lines ignored
>third line of text
end
Notes:
• Between define string and end, blank lines and comment lines are ignored.
• Lines beginning with > characters contain text that is added to the string; the leading > character is
ignored.
• Leading white space before the > character is ignored.
• You cannot use a backslash (\) to continue a line. The \ character is treated literally.
A string name can be used as the optional third argument to the exception( ) property. This overrides
the format field of the exception. In this usage, the string can contain substitutions, which are
expanded when the exception is generated.
Example
define string Message
><html>
><head>
><title>Notice</title>
><meta http-equiv=refresh content="10;$(url)">
></head>
><body>
>There are cookies in the lunch room. Help yourself.
></body>
></html>
end
<proxy>
condition=ShouldBeNotified exception(notify,"",Message)
The above CPL code returns a 200 HTTP response of type text/html where the HTML is defined by
the string-definition-name Message. Substitutions of the form $(...) within the string definition are
expanded.
See Also
Properties: exception( )
391
Volume 10: Content Policy Language Guide
define subnet
Binds a user-defined label to a set of IP addresses or IP subnet patterns. Use a subnet definition label
with any of the conditions that test part of the transaction as an IP address, including:
client.address=, proxy.address=, request.header.header_name.address=,
request.x_header.header_name.address, and server_url.address=.
The listed IP addresses or subnets are considered to have a Boolean OR relationship, no matter
whether they are all on one line or separate lines.
Syntax
define subnet label
{ ip_address | subnet } { ip_address | subnet } ...
...
end
where:
• label—A user-defined identifier for this subnet definition.
• ip_address—IP address; for example, 10.1.198.0.
• subnet—Subnet specification; for example, 10.25.198.0/16.
Example
define subnet local_net
1.2.3.4 1.2.3.5 ; can list individual IP addresses
2.3.4.0/24 2.3.5.0/24 ; or subnets
end
<proxy>
client.address=!local_subnet deny
See Also
• Conditions: client.address=, proxy.address=, request.header.header_name.address=,
request.x_header.header_name.address, and server_url.address=
392
Chapter 6: Definition Reference
Syntax
define url condition label
url_prefix_pattern [condition_expression ...]
...
end
where:
• label—A user-defined identifier for a prefix condition definition.
• url_prefix_pattern ... —A URL pattern that includes at least a portion of the following:
scheme://host:port/path
• scheme—A URL scheme (http, https, ftp, mms, or rtsp) followed by a colon (:).
• host—A host name or IP address, optionally preceded by two forward slashes (//).
Host names must be complete; for example, url=http://www will fail to match a URL
such as http://www.example.com. This use of a complete host instead of simply a
domain name (such as example.com) marks the difference between the prefix and
domain condition definition blocks.
• port—A port number, between 1 and 65535.
• path—A forward slash (/) followed by one or more full directory names.
Accepted prefix patterns include the following:
scheme://host
scheme://host:port
scheme://host:port/path
scheme://host/path
//host
//host:port
//host:port/path
//host/path
host
host:port
host:port/path
host/path
/path
393
Volume 10: Content Policy Language Guide
Example
define url condition allowed
http://www.inventory.example.com http.method=GET
www.affinityclub.example.com/public ; any scheme allowed
end
<Proxy>
condition=allowed allow
See Also
Conditions: category=, condition=, url=
Definitions: define url.domain condition
394
Chapter 6: Definition Reference
Syntax
define url.domain condition label
domain_suffix_pattern [condition_expression ...]
...
end
where:
• label—A user-defined identifier for a domain condition definition. Used in a
condition= condition.
• domain_suffix_pattern—A URL pattern suitable to the url.domain= condition, that
includes a domain name (domain), as a minimum. See the url= condition reference for a
complete description.
• condition_expression ...—An optional condition expression, using any of the
conditions available in a rule. For more information, see Chapter 3: "Condition Reference".
The layer and timing restrictions for the defined condition will depend on the layer and
timing restrictions of the contained expressions.
The condition= condition is one of the expressions that can be included in the body of a
define url.domain condition definition block, following a URL pattern. In this way, one
domain definition block can call another condition-related definition block, so that they are in
effect nested. See the example in the define condition definition block topic.
Example
define domain condition allowed
inventory.example.com method=GET
affinityclub.example.com
end
<proxy>
condition=allowed allow
See Also
• Condition: condition=, server_url.domain=
395
Volume 10: Content Policy Language Guide
396
Chapter 6: Definition Reference
define url_rewrite
Defines rules for rewriting URLs in HTTP responses. The URLS are either embedded in tags within
HTML, CSS, JavaScript, or ASX documents, or they are contained in HTTP response headers. In
addition to rewriting URLS, you can also rewrite arbitrary JavaScript.
This transformer takes effect only if it is also invoked by a transform action in a define action
definition block, and that block is in turn called from an action( ) property.
For each url found within an HTTP response, a url_rewrite transformer first converts the URL into
absolute form, then finds the first rewrite_url_substring or rewrite_url_prefix statement whose
server_URL_substring matches the URL being considered. If such a match is found, then that
substring is replaced by the client_url_substring.
Matching is always case-insensitive.
To find URLs within an HTTP response, the SG appliance looks for Location:, Content-Location:,
and Refresh: headers, and parses HTML, JavaScript, CSS, and ASX files. The SG appliance does not
apply rewrite_url_* rules to relative URLs embedded within Javascript. However, you can get the
same effect using rewrite_script_substring rules.
Note: Pages served over an HTTPS tunneled connection are encrypted, so URLs embedded within
them cannot be rewritten.
Transformed content is not cached (although the original object may be), in contrast with content that
has been sent to a virus scanning server. This means any transformer can be safely triggered based on
any condition, including client identity and time of day.
Replaces: transform url_rewrite
Syntax
define url_rewrite transformer_id
rewrite_url_substring "client_url_substring" "server_url_substring"
rewrite_url_prefix "client_url_substring" "server_url_substring"
rewrite_script_substring "client_substring" "server_substring"
...
end
where:
• transformer_id—A user-defined identifier for a transformer definition block. Used to
invoke the transformer using the transform action in a define action definition block.
• rewrite_url_substring—Matches server_url_substring anywhere in the URL.
• rewrite_url_prefix—Matches server_url_substring as a prefix of the URL.
• rewrite_script_substring—Matches and rewrites arbitrary substrings inside
Javascript. The substrings do not have to be URLs; they can be anything. This is used in
specialized cases where the Javascript code for a Web application must be changed to
make a server portal work correctly.
• client_url_substring—A string that will replace server_url_substring when that
string is matched for a URL in the retrieved document. The portion of the URL that is not
substituted is unchanged.
397
Volume 10: Content Policy Language Guide
Discussion
If there are a series of rewrite_url_substring and rewrite_url_prefix statements in a url_rewrite
definition, the first statement to match a URL takes effect and terminates processing for that URL.
Example
<Proxy> ; server portal for example
url=example.com/ action.example_server_portal(yes)
; This transformation provides server portaling for example non video content
; This action runs the transform for example server portaling for http content
; Note that the action is responsible for rewriting related headers
See Also
• Actions: transform
• Definitions: define action, define active_content
• Properties: action( )
398
Chapter 6: Definition Reference
restrict dns
This definition restricts DNS lookups and is useful in installations where access to DNS resolution is
limited or problematic. The definition has no name because it is not directly referenced by any rules. It
is global to policy evaluation and intended to prevent any DNS lookups caused by policy. It does not
suppress DNS lookups that might be required to make upstream connections.
If the domain specified in a URL matches any of the domain patterns specified in domain_list, no
DNS lookup is done for any category=, url=, url.address=, url.domain=, or url.host= test.
The special domain "." matches all domains, and therefore can be used to restrict all policy-based
DNS lookups.
If a lookup is required to evaluate the trigger, the trigger evaluates to false.
A restrict dns definition may appear multiple times in policy. The compiler attempts to coalesce
these definitions, and may emit various errors or warnings while coalescing if the definition is
contradictory or redundant.
Syntax
restrict dns
restricted_domain_list
except
exempted_domain_list
end
where:
• restricted_domain_list—Domains for which DNS lookup is restricted.
• exempted_domain_list—Domains exempt from the DNS restriction. Policy is able to use
DNS lookups when evaluating policy related to these domains.
Example
The following definition restricts DNS resolution to all but mydomain.com:
restrict dns
. ; meaning “all”
except
mydomain.com
end
See Also
• Conditions: category=, url=, server_url=
• Definitions: restrict rdns
399
Volume 10: Content Policy Language Guide
restrict rdns
This definition restricts reverse DNS lookups and is useful in installations where access to reverse
DNS resolution is limited or problematic. The definition has no name. It is global to policy evaluation
and is not directly referenced by any rules.
If the requested URL specifies the host in IP form, no reverse DNS lookup is performed to match any
category=, url=, url.domain=, or url.host= condition.
The special token all matches all subnets, and therefore can be used to restrict all policy-based reverse
DNS lookups.
If a lookup is required to evaluate the trigger, the trigger evaluates to false.
A restrict rdns definition may appear multiple times in policy. The compiler attempts to coalesce
these definitions, and may emit various errors or warnings while coalescing if the definition is
contradictory or redundant.
Syntax
restrict rdns
restricted_subnet_list
except
exempted_subnet_list
end
where
• restricted_subnet_list—Subnets for which reverse DNS lookup is restricted.
• exempted_subnet_list—Subnets exempt from the reverse DNS restriction. Policy is able
to use reverse DNS lookups when evaluating policy related to these subnets.
Example
The following definition restricts reverse DNS resolution for all but the 10.10.100.0/24 subnet:
restrict rdns
all
except
10.10.100.0/24
end
See Also
• Conditions: category=, url=, server_url=
• Definitions: restrict dns
400
Chapter 6: Definition Reference
transform active_content
This deprecated syntax has been replaced by define active_content. For more information see
"define active_content" on page 380.
401
Volume 10: Content Policy Language Guide
transform url_rewrite
This deprecated syntax has been replaced by define url_rewrite. For more information see "define
url_rewrite" on page 397.
402
Appendix A:Glossary
actions A class of definitions. CPL has two general classes of actions: request or response
modifications and notifications. An action takes arguments (such as the portion of the
request or response to modify) and is wrapped in a named action definition block. When
the action definition is turned on by the policy rules, any actions it contains operate on
their respective arguments.
<Admin> layer One of the five layer types allowed in a policy. Used to define policy rules that control
access to the Management Console and command line interface (CLI).
admin transaction Encapsulation of a request to manage the SG appliance for the purposes of policy
evaluation. Policy in <Admin> layers applies to admin transactions. Additionally, if the
user is explicitly proxied to the SG appliance, a proxy transaction will also be created for
the request.
allow The preferred short form of exception(no), a property setting that indicates that the
request should be granted.
A default rule for the proxy policy layer. You have two choices: allow or deny. Deny
prevents any access to the SG appliance; allow permits full access to the SG appliance.
<Cache> layer One of the five layer types allowed in a policy. Used to list policy rules that are evaluated
during a cache or proxy transaction.
cache transaction Encapsulation of a request, generated by the SG appliance and directed at an upstream
device, for the purposes of maintaining content in the local object store.
Central Policy File A file provided by Blue Coat Systems Technical Support to ensure that the SG
appliance behaves correctly and efficiently when accessing certain sites. You can adapt
this file to include policies you want to share among multiple appliances.
condition A boolean combination of trigger expressions that yields true or false when evaluated.
default policy The default settings for various transaction properties taken from configuration. An
important example is the default proxy policy that is configurable to either allow or deny
definition A definition binds a user-defined label to a condition, a content category, a
transformation or a group of actions.
deny The preferred short form of exception(policy_denied), a property setting that
indicates that the request should be refused.
Evaluation order The order in which the four policy files—Central, Local, VPM, and Forward—are
evaluated. When a file is evaluated last, the policy rules and the related configuration
settings it specifies can override any settings triggered in the other files.
The order of evaluation of the Central, Local, and VPM policy files is configurable using
the policy order CLI command or the Management Console. The Forward file is
always last in the evaluation order.
Exception layer One of the five layer types allowed in a policy. Exception layers are evaluated when an
exception property is set, forcing transaction termination. Policy in an exception layer
gives the administrator a final chance to modify the properties (such as headers) of the
response (exception) object, just as they would get a chance to modify the properties of
an object returned from the origin server or from cache.
<Forward> layer One of the five layer types allowed in a policy. <Forward> layers are only evaluated
when the current transaction requires an upstream connection.
403
Volume 10: Content Policy Language Guide
Forward Policy File A file you create or that might be created during an upgrade from prior SGOS versions,
and that you maintain to supplement any policy described in the other three policy files.
It is normally used for forwarding policy. The Forward policy file is always last in the
evaluation order.
Forwarding policy is generally distinct and independent of other policies, and is often
used as part of maintaining network topologies.
Forwarding policy can also be created and maintained through the Visual Policy
Manager.
layer A CPL construct for expressing the rules for a single policy decision. Multiple layers can
be used to make multiple decisions. Layers are evaluated in top to bottom order.
Decisions made by later layers can override decisions made by earlier layers. Layer
evaluation terminates on the first rule match.
Five layer types exist. The layer type defines the transactions evaluated against this
policy and restricts the triggers and properties allowed in the rules used in the layer.
Each of the five types of layers are allowed in any policy file.
Local Policy File A file you create and maintain on your network for policy specific to one or more SG
appliance appliances. This is the file you would normally create when writing CPL
directly with a text editor, for use on some subset of the SG appliance appliances in your
organization.
On upgrade from a CacheOS 4.x system, the local file will contain any filter rules
configured under the old system.
Match When a rule is evaluated, if all triggers evaluate to true, then all properties specified are
set. This is often referred to as a rule Match (for example in policy tracing.)
Miss When a rule is evaluated, if any trigger evaluates to false, all properties specified are
ignored. This is often referred to as a rule Miss (for example in policy tracing.)
N/A The rule can't be evaluated for this transaction and is being skipped. N/A happens, for
example, when you try to apply a streaming condition to an FTP transaction.
policy files Any one of four files that contain CPL: Central, Local, VPM, or Forward. When the policy
is installed, the contents of each of the files is concatenated according to the evaluation
order.
policy trace A listing of the results of policy evaluation. Policy tracing is useful when troubleshooting
policy.
property A CPL setting that controls some aspect of transaction processing according to its value.
CPL properties have the form property(setting).
At the beginning of a transaction, all properties are set to their default values, many of
which come from the configuration settings.
<Proxy> layer One of the five layer types allowed in a policy, used to list policy rules that control access
to proxy services configured on the SG appliance.
Rules in the <Proxy> layer include user authentication and authorization requirements,
time of day restrictions, and content filtering.
proxy transaction A transaction created for each request received over the proxy service ports configured
on the SG appliance. The proxy transaction covers both the request and its associated
response, whether fetched from the origin server or the local object store.
request A modification of the request for an object (either the URL or Headers). This modification
transformation might result in fetching a different object, or fetching the object through a different
mechanism.
404
Appendix :
response a modification of the object being returned. This modification can be to either the
transformation protocol headers associated with the response sent to the client, or a transformation of
the object contents itself, such as the removal of active content from HTML pages.
rule A list of triggers and property settings, written in any order. A rule can be written on
multiple lines using a line continuation character.
If the rule matches (all triggers evaluate to true), all properties will be set as specified. At
most one rule per layer will match. Layer evaluation terminates on the first rule match.
section A way of grouping rules of like syntax together. Sections consist of a section header that
defines the section type, followed by policy rules.The section type determines the
allowed syntax of the rules, and an evaluation strategy.
transaction An encapsulation of a request to the SG appliance together with the resulting response
that can be subjected to policy evaluation.
The version of policy current when the transaction starts is used for evaluation of the
complete transaction, to ensure consistent results.
trigger A named test of some aspect of a transaction. CPL triggers have the form
trigger_name=value.
Triggers are used in rules, and in condition definitions.
Visual Policy Manager A file created and stored on an individual SG appliance by the Visual Policy Manager.
file The VPM allows you to create policies without writing CPL directly. Since the VPM
supports a subset of CPL functionality, you might want to supplement any policy in a
VPM file with rules in the Local policy file. If you have a new SG appliance, the VPM file
is empty. VPM files can be shared among various SG appliance appliances by copying
the VPM files to a Web server and then using the Management Console or the CLI from
another SG appliance to download and install the files.
405
Volume 10: Content Policy Language Guide
406
Appendix B: Testing and Troubleshooting
If you are experiencing problems with your policy files or would like to monitor evaluation for brief
periods of time, consider using the policy tracing capabilities of the policy language.
Tracing allows you to examine how the SG appliance policy is applied to a particular request. To
configure tracing in a policy file, you use several policy language properties to enable tracing, set the
verbosity level, and specify the path for output. Using appropriate conditions to guard the tracing
rules, you can be specific about the requests for which you gather tracing information.
Note: Use policy tracing for troubleshooting only. Tracing is best used temporarily for
troubleshooting, while the log_message( ) action is best for on-going monitoring. For more
information about the log_message( ) action, see "log_message( )" on page 364. If tracing is
enabled in a production setting, SG appliance performance degrades. After you complete
troubleshooting, be sure to remove policy tracing.
CPL provides the following trace-related properties:
• trace.rules( )—Controls the tracing of rule evaluation. Trace can show which rules missed,
which matched, and which were not applicable (N/A), meaning the rule cannot be evaluated for
this transaction and is being skipped. N/A occurs, for example, when you try to apply a streaming
trigger to an FTP transaction.
• trace.request( )—Enables tracing and includes a description of the transaction being
processed in the trace. No trace output is generated if this is set to no.
• trace.destination( )—Directs the trace output to a user-named trace log.
Example
The following enables tracing:
<Proxy>
trace.rules(yes) tracewhere:request(yes)
407
Volume 10: Content Policy Language Guide
Example
The following enables full tracing information for all transactions:
<cache>
trace.rules(all) trace.request(yes)
Example
In the following example, two destinations are configured for policy tracing information:
<Proxy>
client.address=10.25.0.0/16 trace.destination(internal_trace.html)
client.address=10.0.0.0/8 trace.destination(external_trace.html)
The console URLs for retrieving the information would be
http://<SG_appliance_IP_address>:8081/Policy/Trace/internal_trace.html
http://<SG_appliance_IP_address>:8081/Policy/Trace/external_trace.html
408
Appendix B: Testing and Troubleshooting
; No access to RDNS
restrict rdns
all
end
<Proxy>
trace.request(yes) trace.rules(all)
<Proxy>
;
deny url.host.is_numeric=no url.domain=!my_site.com
deny url.address=!my_subnet
<Proxy>
deny ftp.method=STOR
<Proxy>
url.domain=my_site.com action.test(yes)
409
Volume 10: Content Policy Language Guide
The following is the trace output produced for an HTTP GET request for
http://www.my_site.com/home.html.
Note: The line numbers shown at the left do not appear in actual trace output. They are added here
for annotation purposes.
1 start transaction ------------------------------
2 CPL Evaluation Trace:
3 <Proxy>
4 MATCH: trace.rules(all) trace.request(yes)
5 <Proxy>
6 miss: url.domain=!//my_site.com/
7 miss: url.address=!my_subnet
8 <Proxy>
9 n/a : ftp.method=STOR
10 <Proxy>
11 MATCH: url.domain=//my_site.com/ action.foo(yes)
12 connection: client.address=10.10.0.10 proxy.port=36895
13 time: 2003-09-11 19:36:22 UTC
14 GET http://www.my_site.com/home.html
15 DNS lookup was unrestricted
16 rewritten URL(s):
17 cache_url/server_url/log_url=http://www.his_site.com/
18 User-Agent: Mozilla 8.6 (Non-compatible)
19 user: unauthenticated
20 set header= (request)
21 value='test'
22 end transaction --------------------------------
Notes:
• Lines 1 and 22 are delimiters indicating where the trace for this transaction starts and ends.
• Line 2 introduces the rule evaluation part of the trace. A rule evaluation part is generated when
trace.rules() is set to yes or all.
• Lines 3 to 4 and 10 to 11 show rule matches, and are included when trace.rules() is set to either
yes or all.
• Lines 5 to 9 come only with trace.rules(all). That is, trace.rules(yes) shows only layers
and rules that match. To include rules that do not match, use trace.rules(all).
• Line 9 shows how a rule (containing an FTP specific condition) that is not applicable to this
transaction (HTTP) is marked as n/a.
• Lines 12 to 21 are generated as a result of trace.request(yes). Using trace.rules() without
trace.request(yes) does not result in a trace.
• Line 12 show client related information.
• Line 13 shows the time the transaction was processed.
• Line 14 is a summary of the request line.
• Line 15 indicates that DNS lookup was attempted during evaluation, and was unrestricted. This
line only appears if there is a DNS restriction and a DNS lookup was required for evaluation.
• Lines 16 and 17 indicate that the request URL was rewritten, and show the effects.
410
Appendix B: Testing and Troubleshooting
• Line 19 indicates that the user was not required to authenticate. If authentication had been
required, the user identity would be displayed.
• Lines 20 and 21 show the results of the header modification action.
The following is a trace of the same policy, but for a transaction in which the request URL has an IP
address instead of a hostname.
1 start transaction ------------------------------
2 CPL Evaluation Trace:
3 <Proxy>
4 MATCH: trace.rules(all) trace.request(yes)
5 <Proxy>
6 miss: url.host.is_numeric=no
7 miss: url.address=!my_subnet
8 <Proxy>
9 n/a : ftp.method=STOR
10 <Proxy>
11 miss: url.domain=//my_site.com/
12 connection: client.address=10.10.0.10 proxy.port=36895
13 time: 2003-09-11 19:33:34 UTC
14 GET http://10.11.12.13/home.html
15 DNS lookup was restricted
16 RDNS lookup was restricted
17 User-Agent: Mozilla 8.6 (Non-compatible)
18 user: unauthenticated
19 end transaction --------------------------------
This shows many of the same features as the earlier trace, but has the following differences:
• Line 12—The URL requested had a numeric host name.
• Lines 15 and 16—Both DNA and RDNS lookups were restricted for this transaction.
• Line 11—Because RDNS lookups are restricted, the rule missed; no rewrite action was used for the
transaction and no rewrite action is reported in the transaction summary (lines 12-18).
Trace output can be used to determine the cause of action conflicts that may be reported in the event
log. For example, consider the following policy fragment:
<Proxy>
trace.request(yes) trace.rules(all)
<Proxy> action.set_header_1(yes)
[Rule] action.set_header_2(yes)
action.set_header_3(yes)
define action set_header_1
set(request.x_header.Test, "one")
end
define action set_header_2
set(request.x_header.Test, "two")
end
define action set_header_3
set(request.x_header.Test, "three")
end
411
Volume 10: Content Policy Language Guide
Because they all set the same header, these actions will conflict. In this example, the conflict is obvious
because all the actions are enabled in the same layer. However, conflicts can also arise when actions
are enabled by completely independent portions of policy. If an action conflict occurs, one of the
actions is dropped and an event log entry is made similar to the following:
Policy: Action discarded, 'set_header_1' conflicts with an action already committed
The conflict is reflected in the following trace of a request for //www.my_site.com/home.html:
1 start transaction ------------------------------
2 CPL Evaluation Trace:
3 <Proxy>
4 MATCH: trace.rules(all) trace.request(yes)
5 <Proxy> action.set_header_1(yes)
6 [Rule] action.set_header_2(yes)
7 MATCH: action.set_header_1(yes)
8 MATCH: action.set_header_2(yes)
9 MATCH: action.set_header_3(yes)
10 connection: client.address=10.10.0.10 proxy.port=36895
11 time: 2003-09-12 15:56:39 UTC
12 GET http://www.my_site.com/home.html
13 User-Agent: Mozilla 8.6 (Non-compatible)
14 user: unauthenticated
15 Discarded Actions:
16 set_header_1
17 set_header_2
18 set header=set_header_3 (request)
19 value='three'
20 end transaction --------------------------------
Notes:
• Layer and section guard expressions are indicated in the trace (lines 7 and 8) before any rules
subject to the guard (line 9).
• Line 15 indicates that actions were discarded due to conflicts.
• Lines 16 and 17 show the discarded actions.
• Line 18 shows the remaining action, while line 19 shows the effect of the action on the header
value.
412
Appendix C: Recognized HTTP Headers
The tables provided in this appendix list all recognized HTTP 1.1 headers and indicate how the SG
appliance is able to interact with them. For each header, columns show whether the header appears in
request or response forms, and whether the append( ), delete( ), rewrite( ), or set( ) actions
can be used to change the header.
Recognized headers can be used with the request.header.header_name= and
response.header.header_name= conditions. Headers not shown in these tables must be tested with
the request.x_header.header_name= and response.x_header.header_name= conditions. In
addition, the following three header fields take address values, so they can be used with the condition
request.header.header_name.address= Client-IP, Host, X-Forwarded-For.
Blue Coat Systems uses the ELFF #Remark directive to record the serial number and name of the SG
appliance in an ELFF formatted access log.
413
Volume 10: Content Policy Language Guide
ETag Response X X
Expect Request X
Expires Request/Response X X
From Request X X
Host Request
If-Match Request X
If-Modified-Since Request
If-None-Match Request X
If-Range Request
If-Unmodified-Since Request
Last-Modified Request/Response
Location Response X X
Max-Forwards Request
Meter Request/Response X X
Pragma Request/Response X X
Proxy-Authenticate Response X
Proxy-Authorization Request X
Proxy-Connection Request X
Range Request X
Referer Request X X
Retry-After Response X X
Server Response X X
Set-Cookie Response X X X
Set-Cookie2 Response X X X
TE Request X
Trailer Request/Response X
Transfer-Encoding Request/Response X
Upgrade Request/Response X
User-Agent Request X X
Vary Response X X X
Via Request/Response X X X
Warning Request/Response X X X
WWW-Authenticate Response
The following table lists custom headers that are recognized by the SG appliance.
Table A.2: Custom HTTP Headers Recognized by the SG Appliance
414
Appendix C: Recognized HTTP Headers
415
Volume 10: Content Policy Language Guide
416
Appendix D: CPL Substitutions
Available Substitutions
The available substitutions are organized in the following categories:
• bytes • streaming
• connection • time
• instant messaging (im) • url
• req_rsp_line • user
• special_token • ci_request_header
• status • si_response_header
417
Volume 10: Content Policy Language Guide
418
Appendix D: CPL Substitutions
419
Volume 10: Content Policy Language Guide
420
Appendix D: CPL Substitutions
421
Volume 10: Content Policy Language Guide
Category: dns
x-dns-cs-transport dns.client_transport The transport protocol used by the client
connection in a DNS query
x-dns-cs-address dns.request.address The address queried in a reverse DNS lookup
x-dns-cs-dns dns.request.name The hostname queried in a forward DNS lookup
x-dns-cs-opcode dns.request.opcode The DNS OPCODE used in the DNS query
x-dns-cs-qtype dns.request.type The DNS QTYPE used in the DNS query
422
Appendix D: CPL Substitutions
Category: im
x-im-buddy-id Instant messaging buddy ID
x-im-buddy-name Instant messaging buddy display name
x-im-buddy-state Instant messaging buddy state
x-im-chat-room-id Instant messaging identifier of the chat room in
use
x-im-chat-room-mem The list of chat room member Ids
bers
x-im-chat-room-type The chat room type, one of 'public' or 'public',
and possibly 'invite_only', 'voice' and/or
'conference'
x-im-client-info The instant messaging client information
x-im-user-agent im.user_agent The instant messaging user agent string
x-im-file-path Path of the file associated with an instant
message
x-im-file-size Size of the file associated with an instant
message
x-im-http-gateway The upstream HTTP gateway used for IM (if
any)
x-im-message-opcode im.message.opcode The opcode utilized in the instant message
x-im-message-reflecte im.message.reflected Indicates whether or not the IM message was
d reflected.
x-im-message-route The route of the instance message
x-im-message-size Length of the instant message
x-im-message-text Text of the instant message
x-im-message-type The type of the instant message
x-im-method The method associated with the instant message
x-im-user-id Instant messaging user identifer
x-im-user-name Display name of the client
x-im-user-state Instant messaging user state
423
Volume 10: Content Policy Language Guide
Category: p2p
x-p2p-client-bytes Number of bytes from client
x-p2p-client-info The peer-to-peer client information
x-p2p-client-type p2p.client The peer-to-peer client type
x-p2p-peer-bytes Number of bytes from peer
Category: packets
c-pkts-lost-client Number of packets lost during transmission
from server to client and not recovered at the
client layer via error correction or at the network
layer via UDP resends.
c-pkts-lost-cont-net Maximum number of continuously lost packets
on the network layer during transmission from
server to client
c-pkts-lost-net Number of packets lost on the network layer
c-pkts-received Number of packets from the server (s-pkts-sent)
that are received correctly by the client on the
first try
c-pkts-recovered-EC Number of packets repaired and recovered on
C the client layer
c-pkts-recovered-rese Number of packets recovered because they were
nt resent via UDP.
c-quality The percentage of packets that were received by
the client, indicating the quality of the stream
424
Appendix D: CPL Substitutions
Category:
req_rsp_line
cs-method method %m Request method used from client to appliance
x-cs-http-method http.method HTTP request method used from client to
appliance. Empty for non-HTTP transactions
cs-protocol client.protocol Protocol used in the client's request
cs-request-line http.request_line %r First line of the client's request
x-cs-raw-headers-cou request.raw_headers.count Total number of 'raw' headers in the request
nt
x-cs-raw-headers-len request.raw_headers.length Total length of 'raw' headers in the request
gth
cs-version request.version %V Protocol and version from the client's request,
e.g. HTTP/1.1
x-bluecoat-proxy-via- proxy.via_http_version Default HTTP protocol version of the appliance
http-version without protocol decoration (e.g. 1.1 for
HTTP/1.1)
x-bluecoat-redirect-lo redirect.location Redirect location URL specified by a redirect
cation CPL action
rs-response-line First line (a.k.a. status line) of the response from
an upstream host to the appliance
rs-status response.code Protocol status code of the response from an
upstream host to the appliance
rs-version response.version Protocol and version of the response from an
upstream host to the appliance, e.g. HTTP/1.1
sc-status %s Protocol status code from appliance to client
x-bluecoat-ssl-failure- ssl_failure_reason Upstream SSL negotiation failure reason
reason
x-cs-http-version http.request.version HTTP protocol version of request from the client.
Does not include protocol qualifier (e.g. 1.1 for
HTTP/1.1)
x-cs-socks-ip socks.destination_address Destination IP address of a proxied SOCKS
request
x-cs-socks-port socks.destination_port Destination port of a proxied SOCKS request
x-cs-socks-method socks.method Method of a proxied SOCKS request
x-cs-socks-version socks.version Version of a proxied SOCKS request.
x-cs-socks-compressi Used compression in SOCKS client side
on connection.
425
Volume 10: Content Policy Language Guide
Category:
special_token
x-bluecoat-special-am amp The ampersand character
p
x-bluecoat-special-ap apos The apostrophe character (a.k.a. single quote)
os
x-bluecoat-special-cr cr Resolves to the carriage return character
x-bluecoat-special-crl crlf Resolves to a carriage return/line feed sequence
f
x-bluecoat-special-em empty %l Resolves to an empty string
pty
x-bluecoat-special-esc esc Resolves to the escape character (ASCII HEX 1B)
x-bluecoat-special-gt gt The greater-than character
x-bluecoat-special-lf lf The line feed character
x-bluecoat-special-lt lt The less-than character
x-bluecoat-special-qu quot The double quote character
ot
x-bluecoat-special-sla slash The forward slash character
sh
Category: ssl
x-rs-certificate-hostna server.certificate.hostname Hostname from the server's SSL certificate
me
x-rs-certificate-hostna All content categories of the server's SSL
me-categories certificate's hostname
426
Appendix D: CPL Substitutions
427
Volume 10: Content Policy Language Guide
Category: status
x-bluecoat-release-id release.id The release ID of the ProxySG operating system
x-bluecoat-release-ve release.version The release version of the ProxySG operating
rsion system
cs-categories All content categories of the request URL
cs-categories-external All content categories of the request URL that are
defined by an external service.
cs-categories-policy All content categories of the request URL that are
defined by CPL.
cs-categories-local All content categories of the request URL that are
defined by a Local database.
cs-categories-bluecoat All content categories of the request URL that are
defined by Blue Coat Web Filter.
cs-categories-provide All content categories of the request URL that are
r defined by the current 3rd-party provider.
cs-categories-qualifie All content categories of the request URL,
d qualified by the provider of the category.
cs-category Single content category of the request URL
(a.k.a. sc-filter-category)
cs-uri-categories All content categories of the request URL
cs-uri-categories-exte All content categories of the request URL that are
rnal defined by an external service.
cs-uri-categories-poli All content categories of the request URL that are
cy defined by CPL.
cs-uri-categories-local All content categories of the request URL that are
defined by a Local database.
cs-uri-categories-blue All content categories of the request URL that are
coat defined by Blue Coat Web Filter.
cs-uri-categories-prov All content categories of the request URL that are
ider defined by the current 3rd-party provider.
428
Appendix D: CPL Substitutions
429
Volume 10: Content Policy Language Guide
430
Appendix D: CPL Substitutions
Category: streaming
audiocodec Audio codec used in stream.
avgbandwidth Average bandwidth (in bits per second) at which
the client was connected to the server.
channelURL URL to the .nsc file
c-buffercount Number of times the client buffered while
playing the stream.
c-bytes An MMS-only value of the total number of bytes
delivered to the client.
c-cpu Client computer CPU type.
c-hostexe Host application
c-hostexever Host application version number
c-os Client computer operating system
c-osversion Client computer operating system version
number
c-playerid Globally unique identifier (GUID) of the player
c-playerlanguage Client language-country code
c-playerversion Version number of the player
c-rate Mode of Windows Media Player when the last
command event was sent
c-starttime Timestamp (in seconds) of the stream when an
entry is generated in the log file.
431
Volume 10: Content Policy Language Guide
Category: time
connect-time Total ms required to connect to the origin server
date date.utc %x GMT Date in YYYY-MM-DD format
dnslookup-time Total ms cache required to perform the DNS
lookup
duration %T Time taken (in seconds) to process the request
gmttime %t GMT date and time of the user request in format:
[DD/MM/YYYY:hh:mm:ss GMT]
x-bluecoat-day-utc day.utc GMT/UTC day (as a number) formatted to take
up two spaces (e.g. 07 for the 7th of the month)
x-bluecoat-hour-utc hour.utc GMT/UTC hour formatted to always take up
two spaces (e.g. 01 for 1AM)
432
Appendix D: CPL Substitutions
433
Volume 10: Content Policy Language Guide
Category: url
cs-host %v Hostname from the client's request URL. If URL
rewrite policies are used, this field's value is
derived from the 'log' URL
cs-uri log_url %i The 'log' URL.
cs-uri-address log_url.address IP address from the 'log' URL. DNS is used if
URL uses a hostname.
cs-uri-extension log_url.extension Document extension from the 'log' URL.
cs-uri-host log_url.host Hostname from the 'log' URL.
cs-uri-hostname log_url.hostname Hostname from the 'log' URL. RDNS is used if
the URL uses an IP address.
cs-uri-path log_url.path %U Path from the 'log' URL. Does not include query.
cs-uri-pathquery log_url.pathquery Path and query from the 'log' URL.
cs-uri-port log_url.port Port from the 'log' URL.
cs-uri-query log_url.query %Q Query from the 'log' URL.
cs-uri-scheme log_url.scheme Scheme from the 'log' URL.
cs-uri-stem Stem from the 'log' URL. The stem includes
everything up to the end of path, but does not
include the query.
c-uri url The original URL requested.
c-uri-address url.address IP address from the original URL requested.
DNS is used if the URL is expressed as a
hostname.
c-uri-cookie-domain url.cookie_domain The cookie domain of the original URL
requested
c-uri-extension url.extension Document extension from the original URL
requested
434
Appendix D: CPL Substitutions
435
Volume 10: Content Policy Language Guide
Category: user
436
Appendix D: CPL Substitutions
437
Volume 10: Content Policy Language Guide
Category:
ci_request_header
cs(Accept) request.header.Accept Request header: Accept
cs(Accept)-length request.header.Accept.length Length of HTTP request header: Accept
cs(Accept)-count request.header.Accept.count Number of HTTP request header: Accept
cs(Accept-Charset) request.header.Accept-Charse Request header: Accept-Charset
t
cs(Accept-Charset)-le request.header.Accept-Charse Length of HTTP request header: Accept-Charset
ngth t.length
cs(Accept-Charset)-co request.header.Accept-Charse Number of HTTP request header:
unt t.count Accept-Charset
cs(Accept-Encoding) request.header.Accept-Encodi Request header: Accept-Encoding
ng
438
Appendix D: CPL Substitutions
439
Volume 10: Content Policy Language Guide
440
Appendix D: CPL Substitutions
441
Volume 10: Content Policy Language Guide
442
Appendix D: CPL Substitutions
443
Volume 10: Content Policy Language Guide
444
Appendix D: CPL Substitutions
445
Volume 10: Content Policy Language Guide
Category:
si_response_header
rs(Accept) response.header.Accept Response header: Accept
rs(Accept-Charset) response.header.Accept-Char Response header: Accept-Charset
set
rs(Accept-Encoding) response.header.Accept-Enco Response header: Accept-Encoding
ding
rs(Accept-Language) response.header.Accept-Lang Response header: Accept-Language
uage
rs(Accept-Ranges) response.header.Accept-Rang Response header: Accept-Ranges
es
rs(Age) response.header.Age Response header: Age
rs(Allow) response.header.Allow Response header: Allow
rs(Authentication-Inf response.header. Response header: Authentication-Info
o) Authentication-Info
rs(Authorization) response.header. Response header: Authorization
Authorization
rs(Cache-Control) response.header.Cache-Contr Response header: Cache-Control
ol
rs(Client-IP) response.header.Client-IP Response header: Client-IP
rs(Connection) response.header.Connection Response header: Connection
rs(Content-Dispositio response.header.Content-Dis Response header: Content-Disposition
n) position
rs(Content-Encoding) response.header.Content-Enc Response header: Content-Encoding
oding
rs(Content-Language response.header.Content-Lan Response header: Content-Language
) guage
rs(Content-Length) response.header.Content-Len Response header: Content-Length
gth
rs(Content-Location) response.header.Content-Loc Response header: Content-Location
ation
rs(Content-MD5) response.header.Content-MD Response header: Content-MD5
5
rs(Content-Range) response.header.Content-Ran Response header: Content-Range
ge
446
Appendix D: CPL Substitutions
447
Volume 10: Content Policy Language Guide
Some substitutions can be altered by appending various modifiers. Available substitution modifiers
fall into the following categories:
• Timestamp Modifiers
• String Modifiers
In general, modifiers have the syntax:
:modifier_name(arguments)
and are appended to the field name in the substitution expression, as in
$(field_name:modifier(arguments))
Modifiers can also be chained together to produce the desired result, as in
$(field_name:first_modifier(arguments):second_modifier(arguments))
Timestamp Modifiers
Timestamp modifiers are restricted to working on specific substitution fields that represent timestamp
functions, such as:
• $(date)
• $(time)
448
Appendix D: CPL Substitutions
Examples
Expires at 2 a.m.
$(cookie_date:next_date(2:00))
449
Volume 10: Content Policy Language Guide
$(cookie_date:next_date(Mon 2:00))
Expires at 10 pm the last day of the month
String Modifiers
These substitution modifiers can be applied to any field.
• concat(string—This modifier concatenates the argument to the base string produced by the field
it operates on. The result is a literal string that may need to be enclosed in quotes, depending on
the context.
For example:
log_message( "$(url:concat(?$(user)))")
would print out something like:
http://www.example.com/index.html?mark
• encode_base64 and decode_base64—These modifiers can be used to encode and decode URLs.
They do not take arguments.
Using the same URL as above—log_message( "$(url:concat(?$(user)))"—you can get the
base64 encoded version by changing the expression to log_message
("$(url:concat(?$(user)):encode_base64)")
You can retrieve the original URL using $(url.query:decode_base64).
Host Modifiers
This substitution modifier can be applied to the $(url.host) field.
• label(n)—This modifier extracts the nth label from a host. Labels are numbered from 1, with label
1 being the top level domain (such as .com or .net).
450
Appendix D: CPL Substitutions
451
Volume 10: Content Policy Language Guide
452
Appendix E: Using Regular Expressions
Regular expressions can be used for complex pattern matching. The SG appliance supports regular
expressions as arguments for some conditions and actions in policy files, and as values for some CLI
commands.Blue Coat Reporter can use regular expressions in several places, such as specifying that a
log source pattern is a regular expression or using regular expressions to filter log entries.
Note: Avoid using a regular expression when a non-regular expression alternative is available.
Regular expressions are almost always less effective and more error prone than non-regular
expressions. For instance, instead of using the regular expression
“^[^:]*://.*\.bluecoat\.com/.*$” you should write “url.domain=bluecoat.com“.
The following Content Policy Language (CPL) conditions use regular-expression arguments:
• All triggers with the .regex qualifier (for example, url.regex=, url.host.regex=,
im.text.message.regex=)
• Request and response header triggers (for example, request.header.NAME=,
request.x.header_NAME=, response.header.NAME=, response.x_header.NAME=)
The following CPL actions include regular-expression arguments (refer to the Blue Coat Systems
Content Policy Language Guide for more information):
• delete_matching( )
• redirect( )
• rewrite( )
Regular expressions were also used in CacheOS version 4.x filter files, to match URLs. If a CacheOS
version 4.x filter file is being compiled, a filter line is considered to be a regular expression if it contains
one or more regular expression metacharacters from the following set:
\ ^ $ [ | ( ? * + {
The regular expression support in the SG appliance described in this appendix is based on the
Perl-compatible regular expression libraries (PCRE) by Philip Hazel. The text of this appendix is based
on the PCRE documentation.
A regular expression (or RE) is a pattern that is matched against a subject string from left to right. Most
characters stand for themselves in a pattern, and match the corresponding characters in the subject.
The power of regular expressions comes from the ability to include alternatives and repetitions in the
pattern. These are encoded in the pattern by the use of metacharacters, which do not stand for
themselves, but instead are interpreted in some special way. For details of the theory and
implementation of regular expressions, consult Jeffrey Friedl’s Mastering Regular Expressions, Third
Edition, published by O’Reilly (ISBN 0-596-00289-0).
453
Volume 10: Content Policy Language Guide
The SG appliance uses a Regular Expression Engine (RE ENGINE) to evaluate regular expressions.
This appendix covers the following subjects:
• Syntax and semantics, including a table of metacharacters
• Differences between the RE ENGINE and Perl
Metacharacter Description
(?i) Evaluate the expression following this metacharacter in a case-insensitive manner.
. (Dot) In the default mode, this matches any character except a newline. (Note that newlines
should not be detected when using regular expressions in CPL.)
^ (Circumflex or caret) Matches the start of the string.
$ Matches the end of the string.
* Causes the resulting RE to match zero (0) or more repetitions of the preceding RE, as many
repetitions as are possible. ab* will match ‘a’, ‘ab’, or ‘a’ followed by any number of ‘b’s.
+ Causes the resulting RE to match one (1) or more repetitions of the preceding RE. ab+ will
match ‘a’ followed by any non-zero number of ‘b’s; it will not match just ‘a’.
? Causes the resulting RE to match 0 or 1 repetitions of the preceding RE. ab? will match either
‘a’ or ‘ab’.
*?, +?, ?? The *, +, and ? qualifiers are all greedy; they match as much text as possible.
Sometimes this behavior isn’t desired. If the RE /page1/.*/ is matched against
/page1/heading/images/, it will match the entire string, and not just /page1/heading/.
Adding ? after the qualifier makes it perform the match in non-greedy or minimal fashion;
matching as few characters as possible.
Using .*? in the previous expression will match only /page1/heading/.
{m,n} Causes the resulting RE to match from m to n repetitions of the preceding RE, attempting to
match as many repetitions as possible. For example, a{3,5} will match from 3 to 5 ‘a’
characters.
{m,n}? Causes the resulting RE to match from m to n repetitions of the preceding RE, attempting to
match as few repetitions as possible. This is the non-greedy version of the previous qualifier.
For example, on the 6-character string ‘aaaaaa’, a{3,5} will match 5 ‘a’ characters, while
a{3,5}? will only match 3 characters.
\ Either escapes special characters (permitting you to match characters like ‘*?+&$’), or signals
a special sequence; special sequences are discussed below.
454
Appendix E: Using Regular Expressions
Metacharacter Description
[] Used to indicate a set of characters. Characters can be listed individually, or a range of
characters can be indicated by giving two characters and separating them by a ‘-’. Special
characters are not active inside sets. For example, [akm$] will match any of the characters ‘a’,
‘k’, ‘m’, or ‘$’; [a-z] will match any lowercase letter and [a-zA-Z0-9] matches any letter or
digit. Character classes such as \w or \S (defined below) are also acceptable inside a range.
If you want to include a ] or a - inside a set, precede it with a backslash.
Characters not within a range can be matched by including a ^ as the first character of the
set; ^ elsewhere will simply match the ‘^’ character.
| A|B, where A and B can be arbitrary REs, creates a regular expression that will match either
A or B. This can be used inside groups (see below) as well. To match a literal ‘|’, use \|, or
enclose it inside a character class, like [|].
(...) Matches whatever regular expression is inside the parentheses, and indicates the start and
end of a group; the contents of a group can be retrieved after a match has been performed,
and can be matched later in the string with the \number special sequence, described below.
To match the literals ‘(‘ or ‘)’, use \( or \), or enclose them inside a character class: [(] [)].
Metacharacter Description
\ general escape character with several uses
^ assert start of subject (or line, in multiline mode)
$ assert end of subject (or line, in multiline mode)
. match any character except newline (by default)
[ start character class definition
| start of alternative branch
( start subpattern
) end subpattern
? extends the meaning of “(“ also 0 or 1 quantifier also quantifier minimizer
* 0 or more quantifier
+ 1 or more quantifier
{ start min/max quantifier
455
Volume 10: Content Policy Language Guide
The part of a pattern that is in square brackets is called a “character class.” In a character class the only
metacharacters are:
Table A.2: Metacharacters Used in Square Brackets (Character Class)
Metacharacter Description
\ general escape character
^ negate the class, but only if the first character
- indicates character range
] terminates the character class
Backslash
The backslash character has several uses. If it is followed by a non-alphanumeric character, it takes
away any special meaning that character might have. This use of backslash as an escape character
applies both inside and outside character classes.
For example, if you want to match a “*” character, you write “\*” in the pattern. This applies whether
or not the following character would otherwise be interpreted as a metacharacter, so it is always safe
to precede a non-alphanumeric with “\” to specify that it stands for itself. In particular, if you want to
match a backslash, you write “\\”.
An escaping backslash can be used to include a white space or “#” character as part of the pattern.
A second use of backslash provides a way of encoding non-printing characters in patterns in a visible
manner. There is no restriction on the appearance of non-printing characters, apart from the binary
zero that terminates a pattern; but when a pattern is being prepared by text editing, it is usually easier
to use one of the following escape sequences than the binary character it represents. For example, \a
represents “alarm”, the BEL character (hex 07).
The handling of a backslash followed by a digit other than 0 is complicated. Outside a character class,
RE ENGINE reads it and any following digits as a decimal number. If the number is less than 10, or if
there have been at least that many previous capturing left parentheses in the expression, the entire
sequence is taken as a back reference. A description of how this works is given later, following the
discussion of parenthesized subpatterns.
Inside a character class, or if the decimal number is greater than 9 and there have not been that many
capturing subpatterns, RE ENGINE re-reads up to three octal digits following the backslash, and
generates a single byte from the least significant 8 bits of the value. Any subsequent digits stand for
themselves. For example, \040 is another way of writing a space
Note that octal values of 100 or greater must not be introduced by a leading zero, because no more
than three octal digits are ever read. All the sequences that define a single byte value can be used both
inside and outside character classes. In addition, inside a character class, the sequence “\b” is
interpreted as the backspace character (hex 08). Outside a character class it has a different meaning
(see below).
The third use of backslash is for specifying generic character types:
\d Any decimal digit
\D Any character that is not a decimal digit
456
Appendix E: Using Regular Expressions
457
Volume 10: Content Policy Language Guide
Circumflex need not be the first character of the pattern if a number of alternatives are involved, but it
should be the first thing in each alternative in which it appears if the pattern is ever to match that
branch. If all possible alternatives start with a circumflex, that is, if the pattern is constrained to match
only at the start of the subject, it is said to be an “anchored” pattern. (There are also other constructs
that can cause a pattern to be anchored.)
A dollar character is an assertion that is true only if the current matching point is at the end of the
subject string, or immediately before a newline character that is the last character in the string (by
default). Dollar need not be the last character of the pattern if a number of alternatives are involved,
but it should be the last item in any branch in which it appears. Dollar has no special meaning in a
character class.
Period (Dot)
Outside a character class, a dot in the pattern matches any one character in the subject, including a
non-printing character, but not (by default) newline. (Note that newlines should not be detected when
using regular expressions in CPL.) The handling of dot is entirely independent of the handling of
circumflex and dollar, the only relationship being that they both involve newline characters. Dot has
no special meaning in a character class.
Square Brackets
An opening square bracket introduces a character class, terminated by a closing square bracket. A
closing square bracket on its own is not special. If a closing square bracket is required as a member of
the class, it should be the first data character in the class (after an initial circumflex, if present) or
escaped with a backslash.
A character class matches a single character in the subject; the character must be in the set of
characters defined by the class, unless the first character in the class is a circumflex, in which case the
subject character must not be in the set defined by the class. If a circumflex is actually required as a
member of the class, ensure it is not the first character, or escape it with a backslash.
For example, the character class [aeiou] matches any lowercase vowel, while [^aeiou] matches any
character that is not a lowercase vowel. Note that a circumflex is just a convenient notation for
specifying the characters, which are in the class by enumerating those that are not. It is not an
assertion: it still consumes a character from the subject string, and fails if the current pointer is at the
end of the string.
A class such as [^a] will always match a newline. (Note that newlines should not be detected when
using regular expressions in CPL.)
458
Appendix E: Using Regular Expressions
The minus (hyphen) character can be used to specify a range of characters in a character class. For
example, [d-m] matches any letter between d and m, inclusive. If a minus character is required in a
class, it must be escaped with a backslash or appear in a position where it cannot be interpreted as
indicating a range, typically as the first or last character in the class. It is not possible to have the
character “]” as the end character of a range, since a sequence such as [w-] is interpreted as a class of
two characters. The octal or hexadecimal representation of “]” can, however, be used to end a range.
Ranges operate in ASCII collating sequence. They can also be used for characters specified
numerically, for example [\000-\037].
The character types \d, \D, \s, \S, \w, and \W might also appear in a character class, and add the
characters that they match to the class. For example, [\dABCDEF] matches any hexadecimal digit. A
circumflex can conveniently be used with the upper case character types to specify a more restricted
set of characters than the matching lower case type. For example, the class [^\W_] matches any letter
or digit, but not underscore.
All non-alphanumeric characters other than \, -, ^ (at the start) and the terminating ] are non-special
in character classes, but it does no harm if they are escaped.
Vertical Bar
Vertical bar characters are used to separate alternative patterns. For example, the pattern
gilbert|sullivan
matches either “gilbert” or “sullivan.” Any number of alternatives might appear, and an empty
alternative is permitted (matching the empty string). The matching process tries each alternative in
turn, from left to right, and the first one that succeeds is used. If the alternatives are within a
subpattern (defined below), “succeeds” means matching the rest of the main pattern as well as the
alternative in the subpattern.
Lowercase-Sensitivity
By default, CPL conditions that take regular-expression arguments perform a case-insensitive match.
In all other places where the SG appliance performs a regular-expression match, the match is case
sensitive.
Note: In CPL, use the “.case+sensitive” condition modifier for case sensitivity, rather than
relying on Perl syntax.
Override the default for case sensitivity by using the following syntax:
(?i) Sets case-insensitive matching mode.
459
Volume 10: Content Policy Language Guide
The scope of a mode setting depends on where in the pattern the setting occurs. For settings that are
outside any subpattern (see the next section), the effect is the same as if the options were set or unset at
the start of matching. The following patterns all behave in exactly the same way:
(?i)abc
a(?i)bc
ab(?i)c
abc(?i)
In other words, such “top level” settings apply to the whole pattern (unless there are other changes
inside subpatterns). If there is more than one setting of the same option at the top level, the rightmost
setting is used.
If an option change occurs inside a subpattern, the effect is different. This is a change of behavior in
Perl 5.005. An option change inside a subpattern affects only that part of the subpattern that follows it,
so (a(?i)b)c matches abc and aBc and no other strings (assuming the default is case sensitive). By
this means, options can be made to have different settings in different parts of the pattern. Any
changes made in one alternative do carry on into subsequent branches within the same subpattern.
For example (a(?i)b|c) matches "ab", "aB", "c", and "C", even though when matching "C" the first
branch is abandoned before the option setting. This is because the effects of option settings happen at
compile time. This avoids some strange side-effects.
Subpatterns
Subpatterns are delimited by parentheses (round brackets), which can be nested. Marking part of a
pattern as a subpattern does two things:
• It localizes a set of alternatives.
For example, the pattern cat(aract|erpillar|) matches one of the words “cat”, “cataract”, or
“caterpillar”. Without the parentheses, it would match “cataract”, “erpillar” or the empty string.
• It sets up the subpattern as a capturing subpattern (as defined above). When the whole pattern
matches, that portion of the subject string that matched the subpattern is passed back to the caller
via the ovector argument of RE Engine_exec(). Opening parentheses are counted from left to right
(starting from 1) to obtain the numbers of the capturing subpatterns.
For example, if the string “the red king” is matched against the pattern the ((red|white)
(king|queen)) the captured substrings are “red king”, “red”, and “king”, and are numbered 1, 2,
and 3.
The fact that plain parentheses fulfill two functions is not always helpful. There are times when a
grouping subpattern is required without a capturing requirement. If an opening parenthesis is
followed by “?:”, the subpattern does not do any capturing, and is not counted when computing the
number of any subsequent capturing subpatterns. For example, if the string “the white queen” is
matched against the pattern the ((?:red|white)(king|queen)) the captured substrings are “white
queen” and “queen,” and are numbered 1 and 2. The maximum number of captured substrings is 99,
and the maximum number of all subpatterns, both capturing and non-capturing, is 200.
460
Appendix E: Using Regular Expressions
As a convenient shorthand, if any option settings are required at the start of a non-capturing
subpattern, the option letters might appear between the “?” and the “:”. Thus the two patterns
(?i:saturday|sunday) and (?:(?i)saturday|sunday) match exactly the same set of strings. Because
alternative branches are tried from left to right, and options are not reset until the end of the
subpattern is reached, an option setting in one branch does affect subsequent branches, so the above
patterns match “SUNDAY” as well as “Saturday”.
Repetition
Repetition is specified by quantifiers, which can follow any of the following items:
• A single character, possibly escaped by the . metacharacter
• A character class
• A back reference (see next section)
• A parenthesized subpattern (unless it is an assertion - see below)
The general repetition quantifier specifies a minimum and maximum number of permitted matches,
by giving the two numbers in curly brackets (braces), separated by a comma. The numbers must be
less than 65536, and the first must be less than or equal to the second. For example, z{2,4} matches
“zz”, “zzz”, or “zzzz.” A closing brace on its own is not a special character. If the second number is
omitted, but the comma is present, there is no upper limit; if the second number and the comma are
both omitted, the quantifier specifies an exact number of required matches. Thus [aeiou]{3,}
matches at least 3 successive vowels, but might match many more, while \d{8} matches exactly 8
digits. An opening curly bracket that appears in a position where a quantifier is not allowed, or one
that does not match the syntax of a quantifier, is taken as a literal character. For example, {,6} is not a
quantifier, but a literal string of four characters.
The quantifier {0} is permitted, causing the expression to behave as if the previous item and the
quantifier were not present. For convenience (and historical compatibility) the three most common
quantifiers have single-character abbreviations:
* Equivalent to {0,}
+ Equivalent to {1,}
? Equivalent to {0,1}
It is possible to construct infinite loops by following a subpattern that can match no characters with a
quantifier that has no upper limit, for example (a?)*
Earlier versions of Perl gave an error at compile time for such patterns. However, because there are
cases where this can be useful, such patterns are now accepted, but if any repetition of the subpattern
does in fact match no characters, the loop is forcibly broken.
461
Volume 10: Content Policy Language Guide
By default, the quantifiers are “greedy,” that is, they match as much as possible (up to the maximum
number of permitted times) without causing the rest of the pattern to fail. The classic example of
where this gives problems is in trying to match comments in C programs. These appear between the
sequences /* and */ and within the sequence, individual * and / characters might appear. An attempt
to match C comments by applying the following pattern fails because it matches the entire string due
to the greediness of the .* item.
/\*.*\*/
to the string
/* first command */ not comment /* second comment */
However, if a quantifier is followed by a question mark, then it ceases to be greedy, and instead
matches the minimum number of times possible, so the following pattern does the right thing with the
C comments.
/\*.*?\*/
The meaning of the various quantifiers is not otherwise changed, just the preferred number of
matches. Do not confuse this use of question mark with its use as a quantifier in its own right. Because
it has two uses, it can sometimes appear doubled, as below, which matches one digit by preference,
but can match two if that is the only way the rest of the pattern matches.
\d??\d
When a parenthesized subpattern is quantified with a minimum repeat count that is greater than 1 or
with a limited maximum, more store is required for the compiled pattern, in proportion to the size of
the minimum or maximum.
If a pattern starts with .* then it is implicitly anchored, since whatever follows will be tried against
every character position in the subject string. RE ENGINE treats this as though it were preceded by
\A.
When a capturing subpattern is repeated, the value captured is the substring that matched the final
iteration. For example, after the following expression has matched “tweedledum tweedledee” the
value of the captured substring is “tweedledee”.
(tweedle[dume]{3}\s*)+
However, if there are nested capturing subpatterns, the corresponding captured values might have
been set in previous iterations. For example, after
/(a|(b))+/
matches “aba” the value of the second captured substring is “b”.
462
Appendix E: Using Regular Expressions
Back References
Outside a character class, a backslash followed by a digit greater than 0 (and possibly further digits) is
a back reference to a capturing subpattern earlier (i.e., to its left) in the pattern, provided there have
been that many previous capturing left parentheses.
However, if the decimal number following the backslash is less than 10, it is always taken as a back
reference, and causes an error only if there are not that many capturing left parentheses in the entire
pattern. In other words, the parentheses that are referenced need not be to the left of the reference for
numbers less than 10. See the section entitled “Backslash” above for further details of the handling of
digits following a backslash.
A back reference matches whatever actually matched the capturing subpattern in the current subject
string, rather than anything matching the subpattern itself. So the following pattern matches “sense
and sensibility” and “response and responsibility,” but not “sense and responsibility.”
(sens|respons)e and \1ibility
There might be more than one back reference to the same subpattern. If a subpattern has not actually
been used in a particular match, then any back references to it always fail. For example, the following
pattern always fails if it starts to match “a” rather than “bc.” Because there might be up to 99 back
references, all digits following the backslash are taken as part of a potential back reference number. If
the pattern continues with a digit character, then some delimiter must be used to terminate the back
reference.
(a|(bc))\2
A back reference that occurs inside the parentheses to which it refers fails when the subpattern is first
used, so, for example, (a\1) never matches. However, such references can be useful inside repeated
subpatterns. For example, the following pattern matches any number of “a”s and also “aba”, “ababaa”
etc. At each iteration of the subpattern, the back reference matches the character string corresponding
to the previous iteration. In order for this to work, the pattern must be such that the first iteration does
not need to match the back reference. This can be done using alternation, as in the example above, or
by a quantifier with a minimum of zero.
(a|b\1)+
Assertions
An assertion is a test on the characters following or preceding the current matching point that does not
actually consume any characters. The simple assertions coded as \b, \B, \A, \Z, \z, ^ and $ are
described above. More complicated assertions are coded as subpatterns. There are two kinds: those
that look ahead of the current position in the subject string, and those that look behind it.
463
Volume 10: Content Policy Language Guide
An assertion subpattern is matched in the normal way, except that it does not cause the current
matching position to be changed. Lookahead assertions start with (?= for positive assertions and (?!
for negative assertions. For example, the following expression matches a word followed by a
semicolon, but does not include the semicolon in the match.
\w+(?=;)
The following expression matches any occurrence of “example” that is not followed by “bar”.
example(?!bar)
Note that the apparently similar pattern that follows does not find an occurrence of “bar” that is
preceded by something other than “example”; it finds any occurrence of “bar” whatsoever, because
the assertion (?!example) is always true when the next three characters are “bar”. A lookbehind
assertion is needed to achieve this effect.
(?!example)bar
Lookbehind assertions start with (?<= for positive assertions and (?<! for negative assertions. For
example, the following expression does find an occurrence of “bar” that is not preceded by
“example”. The contents of a lookbehind assertion are restricted such that all the strings it matches
must have a fixed length.
(?<!example)bar
However, if there are several alternatives, they do not all have to have the same fixed length. Thus
(?<=bullock|donkey) is permitted, but (?<!dogs?|cats?) causes an error at compile time.
Branches that match different length strings are permitted only at the top level of a lookbehind
assertion. This is an extension compared with Perl 5.005, which requires all branches to match the
same length of string. An assertion such as (?<=ab(c|de)) is not permitted, because its single branch
can match two different lengths, but it is acceptable if rewritten to use two branches:
(?<=abc|abde)
The implementation of lookbehind assertions is, for each alternative, to temporarily move the current
position back by the fixed width and then try to match. If there are insufficient characters before the
current position, the match is deemed to fail.
Assertions can be nested in any combination. For example, the following expression matches an
occurrence of “baz” that is preceded by “bar” which in turn is not preceded by “example”.
(?<=(?<!example)bar)baz
Assertion subpatterns are not capturing subpatterns, and might not be repeated, because it makes no
sense to assert the same thing several times. If an assertion contains capturing subpatterns within it,
these are always counted for the purposes of numbering the capturing subpatterns in the whole
pattern. Substring capturing is carried out for positive assertions, but it does not make sense for
negative assertions.
Assertions count towards the maximum of 200 parenthesized subpatterns.
464
Appendix E: Using Regular Expressions
Once-Only Subpatterns
With both maximizing and minimizing repetition, failure of what follows normally causes the
repeated item to be re-evaluated to see if a different number of repeats allows the rest of the pattern to
match. Sometimes it is useful to prevent this, either to change the nature of the match, or to cause it fail
earlier than it otherwise might, when the author of the pattern knows there is no point in carrying on.
Consider, for example, the pattern \d+example when applied to the subject line
123456bar
After matching all 6 digits and then failing to match “example,” the normal action of the matcher is to
try again with only 5 digits matching the \d+ item, and then with 4, and so on, before ultimately
failing. Once-only subpatterns provide the means for specifying that once a portion of the pattern has
matched, it is not to be re-evaluated in this way, so the matcher would give up immediately on failing
to match “example” the first time. The notation is another kind of special parenthesis, starting with (?>
as in this example:
(?>\d+)bar
This kind of parenthesis “locks up” the part of the pattern it contains once it has matched, and a failure
further into the pattern is prevented from backtracking into it. Backtracking past it to previous items,
however, works as normal.
An alternative description is that a subpattern of this type matches the string of characters that an
identical standalone pattern would match, if anchored at the current point in the subject string.
Once-only subpatterns are not capturing subpatterns. Simple cases such as the above example can be
though of as a maximizing repeat that must swallow everything it can. So, while both \d+ and \d+?
are prepared to adjust the number of digits they match in order to make the rest of the pattern match,
(?>\d+) can only match an entire sequence of digits.
This construction can of course contain arbitrarily complicated subpatterns, and it can be nested.
Conditional Subpatterns
It is possible to cause the matching process to obey a subpattern conditionally or to choose between
two alternative subpatterns, depending on the result of an assertion, or whether a previous capturing
subpattern matched or not. The two possible forms of conditional subpattern are
(?(condition)yes-pattern)
(?(condition)yes-pattern|no-pattern)
If the condition is satisfied, the yes-pattern is used; otherwise the no-pattern (if present) is used. If
there are more than two alternatives in the subpattern, a compile-time error occurs.
There are two kinds of condition. If the text between the parentheses consists of a sequence of digits,
then the condition is satisfied if the capturing subpattern of that number has previously matched.
Consider the following pattern, which contains non-significant white space to make it more readable
and to divide it into three parts for ease of discussion:
( \( )? [^()]+ (?(1) \) )
465
Volume 10: Content Policy Language Guide
The first part matches an optional opening parenthesis, and if that character is present, sets it as the
first captured substring. The second part matches one or more characters that are not parentheses. The
third part is a conditional subpattern that tests whether the first set of parentheses matched or not. If
they did, that is, if subject started with an opening parenthesis, the condition is true, and so the
yes-pattern is executed and a closing parenthesis is required. Otherwise, since no-pattern is not
present, the subpattern matches nothing. In other words, this pattern matches a sequence of
non-parentheses, optionally enclosed in parentheses.
If the condition is not a sequence of digits, it must be an assertion. This might be a positive or negative
lookahead or lookbehind assertion. Consider this pattern, again containing non-significant white
space, and with the two alternatives on the second line:
(?(?=[^a-z]*[a-z])
\d{2}[a-z]{3}-\d{2}|\d{2}-\d{2}-\d{2} )
The condition is a positive lookahead assertion that matches an optional sequence of non-letters
followed by a letter. In other words, it tests for the presence of at least one letter in the subject. If a
letter is found, the subject is matched against the first alternative; otherwise it is matched against the
second. This pattern matches strings in one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are
letters and dd are digits.
Comments
The sequence (?# marks the start of a comment which continues up to the next closing parenthesis.
Nested parentheses are not permitted. The characters that make up a comment play no part in the
pattern matching at all.
Performance
Certain items that might appear in patterns are more efficient than others. It is more efficient to use a
character class like [aeiou] than a set of alternatives such as (a|e|i|o|u). In general, the simplest
construction that provides the required behavior is usually the most efficient. Remember that
non-regular expressions are simpler constructions than regular expressions, and are thus more
efficient in general.
466
Appendix E: Using Regular Expressions
• Capturing subpatterns that occur inside negative lookahead assertions are counted, but their
entries in the offsets vector are never set. Perl sets its numerical variables from any such patterns
that are matched before the assertion fails to match something (thereby succeeding), but only if the
negative lookahead assertion contains just one branch.
• Though binary zero characters are supported in the subject string, they are not allowed in a
pattern string because it is passed as a normal C string, terminated by zero. The escape sequence
“\0” can be used in the pattern to represent a binary zero.
• The following Perl escape sequences are not supported: \l, \u, \L, \U, \E, \Q. In fact these are
implemented by Perl’s general string handling and are not part of its pattern-matching engine.
• The Perl \G assertion is not supported as it is not relevant to single pattern matches.
• RE ENGINE does not support the (?{code}) construction.
• There are at the time of writing some oddities in Perl 5.005_02 concerned with the settings of
captured strings when part of a pattern is repeated. For example, matching “aba” against the
pattern /^(a(b)?)+$/ sets $2 to the value “b”, but matching “aabbaa” against
/^(aa(bb)?)+$/ leaves $2 unset. However, if the pattern is changed to /^(aa(b(b))?)+$/
then $2 (and $3) get set. In Perl 5.004 $2 is set in both cases, and that is also true of RE ENGINE.
• Another as yet unresolved discrepancy is that in Perl 5.005_02 the pattern /^(a)?(?(1)a|b)+$/
matches the string “a”, whereas in RE ENGINE it does not. However, in both Perl and RE
ENGINE /^(a)?a/ matched against “a” leaves $1 unset.
• RE ENGINE provides some extensions to the Perl regular expression facilities: Although
lookbehind assertions must match fixed length strings, each alternative branch of a lookbehind
assertion can match a different length of string. Perl 5.005 requires them all to have the same
length.
Note: When regular expressions are used to match a URL, a space character matches a %20 in the
request URL. However, a %20 in the regular-expression pattern will not match anything in any
request URL, because "%20" is normalized to " " in the subject string before the regex match is
performed.
467
Volume 10: Content Policy Language Guide
468
Blue Coat® Systems
SG™ Appliance
http://www.bluecoat.com/support/contact.html
bcs.info@bluecoat.com
http://www.bluecoat.com
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™ and MACH5™ 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®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo
logos 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.
ii
Contents
Contact Information
Chapter 1: Introduction
Audience for this Document ....................................................................................................................................9
Organization of this Document ...............................................................................................................................9
Related Blue Coat Documentation ..........................................................................................................................9
Document Conventions ..........................................................................................................................................10
SSH and Script Considerations ..............................................................................................................................10
Standard and Privileged Modes ............................................................................................................................10
Accessing Quick Command Line Help ................................................................................................................11
iii
# exit ...................................................................................................................................................................... 50
# help ..................................................................................................................................................................... 51
# hide-advanced .................................................................................................................................................. 52
# inline .................................................................................................................................................................. 53
# kill ....................................................................................................................................................................... 55
# licensing ............................................................................................................................................................. 56
# load ..................................................................................................................................................................... 57
# pcap .................................................................................................................................................................... 59
# pcap filter ...................................................................................................................................................... 60
# pcap start ....................................................................................................................................................... 62
# ping .................................................................................................................................................................... 64
# policy .................................................................................................................................................................. 65
# purge-dns-cache ............................................................................................................................................... 66
register-with-director ......................................................................................................................................... 67
# restart ................................................................................................................................................................. 68
# restore-sgos4-config ......................................................................................................................................... 69
# restore-defaults ................................................................................................................................................. 70
# reveal-advanced ............................................................................................................................................... 71
# show ................................................................................................................................................................... 72
# show adn ....................................................................................................................................................... 74
# show attack-detection ................................................................................................................................. 75
# show configuration ...................................................................................................................................... 76
# show content ................................................................................................................................................ 77
# show proxy-services .................................................................................................................................... 78
# show security ................................................................................................................................................ 79
# show ssh ........................................................................................................................................................ 80
# show ssl ......................................................................................................................................................... 81
# temporary-route ............................................................................................................................................... 83
# test ...................................................................................................................................................................... 84
# traceroute .......................................................................................................................................................... 85
# upload ................................................................................................................................................................ 86
Contents v
#(config) im ........................................................................................................................................................ 210
#(config) inline ................................................................................................................................................... 212
#(config) installed-systems .............................................................................................................................. 213
#(config) interface ............................................................................................................................................. 214
#(config interface interface_number) ......................................................................................................... 215
#(config) ip-default-gateway ........................................................................................................................... 217
#(config) license-key ......................................................................................................................................... 218
#(config) line-vty ............................................................................................................................................... 219
#(config) load ..................................................................................................................................................... 220
#(config) mapi .................................................................................................................................................... 221
#(config) netbios ................................................................................................................................................ 222
#(config) no ........................................................................................................................................................ 223
#(config) ntp ....................................................................................................................................................... 224
#(config) policy .................................................................................................................................................. 225
#(config) profile ................................................................................................................................................. 227
#(config) proxy-services ................................................................................................................................... 228
#(config dynamic-bypass) ........................................................................................................................... 230
#(config static-bypass) .................................................................................................................................. 232
#(config aol-im) ............................................................................................................................................. 233
#(config cifs) .................................................................................................................................................. 234
#(config dns) .................................................................................................................................................. 235
#(config endpoint-mapper) ......................................................................................................................... 236
#(config ftp) ................................................................................................................................................... 237
#(config http) ................................................................................................................................................. 238
#(config https-reverse-proxy) ..................................................................................................................... 240
#(config mms) ................................................................................................................................................ 242
#(config msn-im) ........................................................................................................................................... 243
#(config restricted-intercept) ....................................................................................................................... 244
#(config rtsp) ................................................................................................................................................. 245
#(config socks) ............................................................................................................................................... 246
#(config ssl) .................................................................................................................................................... 247
#(config tcp-tunnel) ...................................................................................................................................... 248
#(config telnet) ............................................................................................................................................... 250
#(config yahoo-im) ........................................................................................................................................ 251
#(config) restart ................................................................................................................................................. 252
#(config) return-to-sender ................................................................................................................................ 253
#(config) reveal-advanced ............................................................................................................................... 254
#(config) rip ........................................................................................................................................................ 255
#(config) security ............................................................................................................................................... 256
#(config security allowed-access) ............................................................................................................... 259
#(config security authentication-forms) .................................................................................................... 260
#(config security certificate) ........................................................................................................................ 262
#(config security coreid) .............................................................................................................................. 264
#(config security default-authenticate-mode) .......................................................................................... 267
#(config security destroy-old-password) .................................................................................................. 268
#(config security enable-password and hashed-enable-password) ...................................................... 269
#(config security enforce-acl) ...................................................................................................................... 270
#(config security front-panel-pin and hashed-front-panel-pin) ............................................................ 271
#(config security iwa) ................................................................................................................................... 272
Contents vii
viii Volume 11: Command Line Interface Reference
Chapter 1: Introduction
To configure and manage your Blue Coat® Systems SG appliance, Blue Coat developed
a software suite that includes an easy-to-use graphical interface called the Management
Console and a Command Line Interface (CLI). The CLI allows you to perform the
superset of configuration and management tasks; the Management Console, a subset.
This reference guide describes each of the commands available in the CLI.
Chapter 1 – Introduction
The organization of this document; conventions used; descriptions of the CLI modes;
and instructions for saving your configuration.
9
Document Conventions
The following table lists the typographical and CLI syntax conventions used in this
manual.
Convention Definition
Courier font Command-line text that will appear on your administrator workstation.
Courier Italics A command-line variable that should be substituted with a literal name or
value pertaining to the appropriate facet of your network system.
| Either the parameter before or after the pipe character can or must be
selected, but not both.
This chapter describes and provides examples for the Blue Coat SG appliance standard and privileged
mode CLI commands. These modes have fewer permissions than enabled mode commands.
❐ Privileged Mode Commands
Privileged mode provides a set of commands that enable you to view, manage, and change SG
appliance settings for features such as log files, authentication, caching, DNS, HTTPS, packet
capture filters, and security. You can cannot configure functionality such as SSL Proxy, HTTP
compression, and the like.
The prompt changes from a greater than sign (>) to a pound sign (#), acting as an indicator
that you are in privileged mode .
Enter privileged mode from standard mode by using the enable command:
SGOS> enable
Enable Password:********
SGOS#
❐ Configuration Mode Commands
The configure command, available only in enabled mode, allows you to configure the Blue
Coat SG appliance settings from your current terminal session (configure terminal), or by
loading a text file of configuration settings from the network (configure network). Enabled
Mode commands are discussed in Chapter 3: Privileged Mode Configure
Commands on page 87.
The prompt changes from a pound sign (#) to a #(config) prompt, acting as an indicator that
you are in configuration mode .
Enter configuration mode from privileged mode by using the configure command:
SGOS# conf t
SGOS#(config)
No password is needed to enter enabled mode.
13
Standard Mode Commands Standard Mode Commands
> display
Synopsis
Use this command to display the content (such as HTML or Javascript) for the specified URL. This
content is displayed one screen at a time. "—More—" at the bottom of the terminal screen indicates
that there is additional code. Press the <spacebar> to display the next batch of content; press <Enter>
to display one additional line of content.
This command is used for general HTTP connectivity testing
Syntax
> display url
where url is a valid, fully-qualified text Web address.
Example
SGOS> display http://www.bluecoat.com
10.9.59.243 - Blue Coat SG200>display http://www.bluecoat.com
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Blue Coat Systems</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<META NAME="keywords" CONTENT="spyware WAN application spyware removal spy ware
spyware remover application delivery to branch office accelerate performance
applications remove spyware spyware application delivery secure application
acceleration control SSL threat anti-virus protection WAN optimization AV
appliance spyware blocker application acceleration distributed security
application performance spyware killer spyware WebFilter protection CIFS MAPI
streaming video Web application security branch offices secure endpoint
protection SSL policy control remote user acceleration WAN delivery application
performance WebFilter endpoint security fast WAN policy control spyware detection
spyware eliminator block endpoint security spyware secure MAPI appliances SSL AV
policy control stop spyware remove AV appliance SSL proxy Http secure Web
application acceleration encryption Proxy Internet Proxy Internet Proxy Cache
security proxy cache proxy server CIFS proxy servers branch office Web proxy
appliance enterprise data center accelerate WAN and CIFS and MAPI and streaming
video policy protection blue coat Web proxy Internet Web AV security systems blue
coat branch office anti-virus performance blue coat remote users WAN performance
acceleration Internet MAPI monitoring AV endpoint Internet application delivery
management endpoint protection and security and acceleration of application
content delivery with policy control Internet CIFS Web application filtering
content filtering Web filtering web filter WAN filtered internet application
acceleration">
.
.
.
> enable
Synopsis
Use this command to enter Privileged mode. Privileged mode commands enable you to view and
change your configuration settings. A password is always required.
Syntax
> enable
The enable command has no parameters or subcommands.
Example
SGOS> enable
Enable Password:******
SGOS# conf t
SGOS(config)
Where conf t is a shortcut to typing configure terminal.
> exit
Synopsis
Use this command to exit the CLI. In privileged and configuration mode, exit returns you to the
previous prompt.
Syntax
> exit
The exit command has no parameters or subcommands.
Example
SGOS> exit
> help
See Accessing Quick Command Line Help on page 11 for information about this command.
> ping
Synopsis
Use this command to verify whether a particular host is reachable across a network.
Syntax
> ping {hostname | ip_address}
Subcommands
> ping hostname
Specifies the name of the host you want to verify.
> ping ip_address
Specifies the IP address you want to verify.
Example
SGOS> ping 10.25.36.47
Type escape sequence to abort.
Sending 5, 64-byte ICMP Echos to 10.25.36.47, timeout is 2 seconds:
!!!!! Success rate is 100 percent (5/5), round-trip min/avg/max = 0/0/0 ms
Number of duplicate packets received = 0
> show
Synopsis
Use this command to display system information. You cannot view all show commands, here, only
those available in the standard mode. You must be in privileged mode to show commands available.
Syntax
> show [subcommands]
Subcommands
Examples
SGOS> show caching
Refresh:
Estimated access freshness is 100.0%
Let the ProxySG Appliance manage refresh bandwidth
Current bandwidth used is 0 kilobits/sec
Policies:
Do not cache objects larger than 1024 megabytes
Cache negative responses for 0 minutes
Let the ProxySG Appliance manage freshness
FTP caching:
Caching FTP objects is enabled
FTP objects with last modified date, cached for 10% of last modified time
FTP objects without last modified date, initially cached for 24 hours
SGOS> show resources
Disk resources:
Maximum objects supported: 1119930
Cached Objects: 0
Disk used by system objects: 537533440
Disk used by access log: 0
Total disk installed: 18210036736
Memory resources:
In use by cache: 699203584
In use by system: 83230176
In use by network: 22872608
Total RAM installed: 805306368
SGOS> show failover configuration group_address
Failover Config
Group Address: 10.25.36.47
Multicast Address : 224.1.2.3
Local Address : 10.9.17.159
Secret : none
Advertisement Interval: 40
Priority : 100
Current State : DISABLED
Flags : V M
Three flags exist, set as you configure the group.
V—Specifies the group name is a virtual IP address.
R—Specifies the group name is a physical IP address
Synopsis
Displays the current access log settings.
Syntax
> show access-log [subcommands]
Subcommands
> show access-log default-logging
Display the access log default policy.
> show access-log format brief
Displays the access log format names.
> show access-log format format_name
Displays the access log with the specified format_name.
> show access-log format
Displays the access-log formats for all log types.
> show access-log log brief
Displays the access log log names.
> show access-log log log_name
Displays the access log with the specified log_name.
> show access-log log
Displays the access-log for all logs.
> show access-log statistics log_name
Displays access-log statistics for the specific log_name.
> show access-log statistics
Displays all access-log statistics.
Example
> show access-log format brief
Formats:
squid
ncsa
main
im
streaming
websense
surfcontrol
smartreporter
surfcontrolv5
p2p
ssl
cifs
mapi
Synopsis
Displays the bandwidth management state (enabled or disabled) or statistics.
Syntax
> show bandwidth-management {configuration | statistics}
Subcommands
> show bandwidth-management configuration bandwidth_class
Displays the bandwidth-management configuration for the specified bandwidth class . If you do not
specify a bandwidth class, displays the bandwidth-management configuration for the system.
> show bandwidth-management statistics bandwidth_class
Displays the bandwidth-management statistics for the specified bandwidth class. If you do not specify a
bandwidth class, displays the bandwidth-management statistics for the system.
Example
> show bandwidth-management configuration
Bandwidth Management Enabled
Synopsis
Displays bridge configuration and statistics.
Syntax
> show bridge [subcommands]
Subcommands
> show bridge configuration [bridge_name]
Displays the bridge configuration for the specified bridge_name or for all interfaces on the system.
> show bridge fwtable [bridge_name]
Displays the bridge forwarding table for the specified bridge_name or for all interfaces on the system.
> show bridge statistics [bridge_name]
Displays the bridge statistics for the specified bridge_name or for all interfaces on the system.
Example
> show bridge configuration
Bridge passthru-0 configuration:
Interface 0:0
Internet address: 10.9.59.246
Internet subnet: 255.255.255.0
MTU size: 1500
Spanning tree: disabled
Allow intercept: enabled
Reject inbound: disabled
Status: autosensed full duplex, 100 megabits/sec network
Interface 0:1
MTU size: 1500
Spanning tree: disabled
Allow intercept: enabled
Reject inbound: disabled
Status: autosensed no link
Synopsis
Displays the available CLI commands.
Syntax
> show commands [subcommands]
Subcommands
> show commands delimited [all | privileged]
Delimited displays commands so they can be parsed.
> show commands formatted [all | privileged]
Formatted displays commands so they can be viewed easily.
Example
> show commands formatted
1:show Show running system information
2:access-log Access log settings
3:log Show Access log configuration
4:brief Show Access log names
<log-name>
3:format Show Access log format configuration
4:brief Show Access log format names
<format-name>
3:statistics Show Access log statistics
<logName>
3:default-logging Show Access log default policy
> show commands delimited
1;show;Show running system information;sh;0;11
2;access-log;Access log settings;acces;0;11
3;log;Show Access log configuration;l;0;11
4;brief;Show Access log names;b;0;11
p;<log-name>;*;*;0;14
3;format;Show Access log format configuration;f;0;11
4;brief;Show Access log format names;b;0;11
p;<format-name>;*;*;0;14
3;statistics;Show Access log statistics;s;0;11
p;<logName>;*;*;0;14
3;default-logging;Show Access log default policy;d;0;11
Synopsis
Displays remote diagnostics information, including version number, and whether the Heartbeats
feature and the SG appliance monitor are currently enabled.
Syntax
> show diagnostics [subcommands]
Subcommands
> show diagnostics configuration
Displays diagnostics settings.
> show diagnostics cpu-monitor
Displays the CPU Monitor results.
> show diagnostics service-info
Displays service-info settings.
> show diagnostics snapshot
Displays the snapshot configuration.
Example
> show diagnostics snapshot
Snapshot sysinfo
Target: /sysinfo
Status: Enabled
Interval: 1440 minutes
To keep: 30
To take: Infinite
Next snapshot: 2006-03-18 00:00:00 UTC
Snapshot sysinfo_stats
Target: /sysinfo-stats
Status: Enabled
Interval: 60 minutes
To keep: 30
To take: Infinite
Next snapshot: 2006-03-17 20:00:00 UTC
Synopsis
Displays disk information, including slot number, vendor, product ID, revision and serial number,
capacity, and status, about all disks or a specified disk.
Syntax
> show disk {disk_number | all}
Subcommands
> show disk disk_number
Displays information on the specified disk.
> show disk all
Displays information on all disks in the system.
Example
> show disk 1
Disk in slot 1
Vendor: SEAGATE
Product: ST340014A
Revision: 8.54
Disk serial number: 5JVQ76VS
Capacity: 40020664320 bytes
Status: present
Synopsis
Displays all exceptions or just built-in or user defined exceptions.
Syntax
> show exceptions [built-in_id | user-defined_id]
Example
> show exceptions
Built-in:
authentication_failed
authentication_failed_password_expired
authentication_mode_not_supported
authentication_redirect_from_virtual_host
authentication_redirect_off_box
authentication_redirect_to_virtual_host
authentication_success
authorization_failed
bad_credentials
client_failure_limit_exceeded
configuration_error
connect_method_denied
content_filter_denied
content_filter_unavailable
dns_server_failure
dns_unresolved_hostname
dynamic_bypass_reload
gateway_error
icap_communication_error
icap_error
internal_error
invalid_auth_form
invalid_request
invalid_response
license_exceeded
license_expired
method_denied
not_implemented
notify
notify_missing_cookie
policy_denied
policy_redirect
radius_splash_page
redirected_stored_requests_not_supported
refresh
server_request_limit_exceeded
silent_denied
spoof_authentication_error
ssl_client_cert_revoked
ssl_domain_invalid
ssl_failed
ssl_server_cert_expired
ssl_server_cert_revoked
ssl_server_cert_untrusted_issuer
tcp_error
transformation_error
unsupported_encoding
unsupported_protocol
> show im
Synopsis
Displays Instant Messaging settings.
Syntax
> show im [subcommands]
Subcommands
> show im configuration
Displays IM configuration information.
> show im aol-statistics
Displays statistics of AOL IM usage.
> show im msn-statistics
Displays statistics of MSN IM usage.
> show im yahoo-statistics
Displays statistics of Yahoo! IM usage.
Example
> show im configuration
IM Configuration
aol-admin-buddy: Blue Coat SG
msn-admin-buddy: Blue Coat SG
yahoo-admin-buddy: Blue Coat SG
exceptions: out-of-band
buddy-spoof-message: <none>
http-handoff: enabled
explicit-proxy-vip: <none>
aol-native-host: login.oscar.aol.com
aol-http-host: aimhttp.oscar.aol.com
aol-direct-proxy-host: ars.oscar.aol.com
msn-native-host: messenger.hotmail.com
msn-http-host: gateway.messenger.hotmail.com
yahoo-native-host: scs.msg.yahoo.com
yahoo-http-host: shttp.msg.yahoo.com
yahoo-http-chat-host: http.chat.yahoo.com
yahoo-upload-host: filetransfer.msg.yahoo.com
yahoo-download-host: .yahoofs.com
Synopsis
Displays TCP/IP statistics.
Syntax
> show ip-stats [subcommands]
Subcommands
> show ip-stats all
Display TCP/IP statistics.
> show ip-stats interface {all | number}
Displays TCP/IP statistics for all interfaces or for the specified number (0
to 7).
> show ip-stats ip
Displays IP statistics.
> show ip-stats memory
Displays TCP/IP memory statistics.
> show ip-stats summary
Displays TCP/IP summary statistics.
> show ip-stats tcp
Displays TCP statistics.
> show ip-stats udp
Displays UDP statistics.
Example
> show ip-stats summary
; TCP/IP Statistics
TCP/IP General Statistics
Entries in TCP queue: 12
Maximum entries in TCP queue: 19
Entries in TCP time wait queue: 0
Maximum entries in time wait queue: 173
Number of time wait allocation failures: 0
Entries in UDP queue: 2
Synopsis
Displays source listings for installable lists, such as the license key, policy files, ICP settings, RIP
settings, static route table, and WCCP settings files.
Syntax
> show sources [subcommands]
Subcommands
> show sources forwarding
Displays forwarding settings.
> show sources icp-settings
Displays ICP settings.
> show sources license-key
Displays license information
> show sources policy {central | local | forward | vpm-cpl | vpm-xml}
Displays the policy file specified.
> show sources rip-settings
Displays RIP settings.
> show sources socks-gateways
Displays the SOCKS gateways settings.
> show sources static-route-table
Displays the static routing table information.
> show sources wccp-settings
Displays WCCP settings.
Example
> show sources socks-gateways
# Current SOCKS Gateways Configuration
# No update
# Connection attempts to SOCKS gateways fail: closed
socks_fail closed
# 0 gateways defined, 64 maximum
# SOCKS gateway configuration
# gateway <gateway-alias> <gateway-domain> <SOCKS port>
# [version=(4|5 [user=<user-name> password=<password>]
# [request-compression=yes|no])]
# Default fail-over sequence.
# sequence <gateway-alias> <gateway-alias> ...
# The default sequence is empty.
# SOCKS Gateways Configuration Ends
Synopsis
Displays SSL settings
Syntax
> show ssl {ccl [list_name] | ssl-client [ssl_client]}
Subcommands
> show ssl ccl [list_name]
Displays currently configured CA certificate lists or configuration for the specified list_name.
> show ssl ssl-client [ssl_client]
Displays information about the specified SSL client.
Example
> show ssl ssl-client
SSL-Client Name Keyring Name Protocol
--------------- ------------ ------------
default <None> SSLv2v3TLSv1
Synopsis
Displays QuickTime, RealNetworks, or Microsoft Windows Media information, and client and total bandwidth
configurations and usage.
Syntax
> show streaming [subcommands]
Subcommands
> show streaming configuration
Displays global streaming configuration.
> show streaming quicktime {configuration | statistics}
Displays QuickTime configuration and statistics.
> show streaming real-media {configuration | statistics}
Displays Real-Media configuration and statistics.
> show streaming windows-media {configuration | statistics}
Displays Windows-Media configuration and statistics.
> show streaming statistics
Displays client and gateway bandwidth statistics.
Example
> show streaming configuration
; Streaming Configuration
max-client-bandwidth: unlimited
max-gateway-bandwidth: unlimited
multicast address: 224.2.128.0 - 224.2.255.255
multicast port: 32768 - 65535
multicast TTL: 16
> traceroute
Use this command to trace the route from the current host to the specified destination host.
Syntax
> traceroute [subcommands]
Subcommands
> traceroute ip_address
Specifies the IP address of the destination host.
> traceroute hostname
Specifies the name of the destination host.
Example
SGOS> traceroute 10.25.36.47
Type escape sequence to abort.
Tracing the route to 10.25.36.47
1 10.25.36.47 0 0 0
Note: The privileged mode subcommand, configure, enables you to manage the SG appliance
features.
# acquire-utc
Synopsis
Use this command to acquire the Universal Time Coordinates (UTC) from a Network Time Protocol
(NTP) server. To manage objects, a SG appliance must know the current UTC time. Your SG appliance
comes pre-populated with a list of NTP servers available on the Internet, and attempts to connect to
them in the order they appear in the NTP server list on the NTP tab. If the SG appliance cannot access
any of the listed NTP servers, the UTC time must be set manually. For instructions on how to set the
UTC time manually, refer to Volume 1: Getting Started.
Syntax
# acquire-utc
The acquire-utc command has no parameters or subcommands.
Example
SGOS# acquire-utc
ok
# bridge
Synopsis
This command clears bridge data.
Syntax
# bridge {subcommands]
Subcommands
# bridge clear-statistics bridge_name
Clears bridge statistics.
# bridge clear-fwtable bridge_name
Clears bridge forward table.
Example
SGOS# bridge clear-statistics testbridge
ok
# cancel-upload
Synopsis
This command cancels a pending access-log upload. The cancel-upload command allows you to stop
repeated upload attempts if the Web server becomes unreachable while an upload is in progress. This
command sets log uploading back to idle if the log is waiting to retry the upload. If the log is in the
process of uploading, a flag is set to the log. This flag sets the log back to idle if the upload fails.
Syntax
# cancel-upload [subcommands]
Subcommands
# cancel-upload all
Cancels upload for all logs.
# cancel-upload log log_name
Cancels upload for a specified log.
Example
SGOS# cancel-upload all
ok
# clear-arp
Synopsis
The clear-arp command clears the Address Resolution Protocol (ARP) table. ARP tables are used to
correlate an IP address to a physical machine address recognized only in a local area network. ARP
provides the protocol rules for providing address conversion between a physical machine address
(also known as a Media Access Control or MAC address) and its corresponding IP address, and vice
versa.
Syntax
# clear-arp
The clear-arp command has no parameters or subcommands.
Example
SGOS# clear-arp
ok
# clear-cache
Synopsis
This command clears the byte, dns, or object cache. This can be done at any time. However, keep in
mind that if any cache is cleared, performance slows down until the cache is repopulated.
Note: #clear-cache with no arguments can also be used to clear the object cache.
Syntax
# clear-cache [subcommands]
Subcommands
# clear-cache byte-cache
Clears the byte cache.
# clear-cache dns-cache
Clears the DNS cache.
# clear-cache object-cache
Sets all objects in the cache to expired.
Example
SGOS# clear-cache byte-cache
ok
# clear-statistics
Synopsis
This command clears the bandwidth-management, persistent, and Windows Media, Real Media, and
QuickTime streaming statistics collected by the SG appliance. To view streaming statistics from the
CLI, use either the show streaming {quicktime | real-media | windows-media} statistics or
the show bandwidth-management statistics [bandwidth_class] commands. To view streaming
statistics from the Management Console, go to either Statistics > Streaming History > Windows
Media/Real Media/Quicktime, or to Statistics > Bandwidth Mgmt.
Syntax
# clear-statistics [subcommands]
Subcommands
# clear-statistics bandwidth-management [class class_name]
Clears bandwidth-management statistics, either for all classes at one time or for the
bandwidth-management class specified
# clear-statistics efficiency
Clears efficiency statistics.
# clear-statistics epmapper
Clears Endpoint Mapper statistics.
# clear-statistics persistent [prefix]
Clears statistics that persist after a reboot. You can clear all persistent statistics, or, since statistics are kept
in a naming convention of group:stat, you can limit the statistics cleared to a specific group. Common
prefixes include HTTP, SSL, and SOCKS.
# clear-statistics quicktime
Clears QuickTime statistics.
# clear-statistics real-media
Clears Real Media statistics.
# clear-statistics windows-media
Clears Windows Media statistics.
Example
SGOS# clear-statistics windows-media
ok
# configure
Synopsis
The privileged mode subcommand configure, enables you to manage the SG appliance features.
Syntax
# config t
Where conf refers to configure and t refers to terminal.
This changes the prompt to #(config). At this point you are in configure terminal mode
and can make permanent changes to the device.
# config network url
This command downloads a previously loaded web-accessible script, such as a configuration
file, and implements the changes in the script onto the system.
Example
# conf n http://1.1.1.1/fconfigure.txt
# disable
Synopsis
The disable command returns you to Standard mode from Privileged mode.
Syntax
# disable
The disable command has no parameters or subcommands.
Example
SGOS# disable
SGOS>
# disk
Synopsis
Use the disk command to take a disk offline or to re-initialize a disk.
On a multi-disk SG appliance, after issuing the disk reinitialize disk_number command,
complete the reinitialization by setting it to empty and copying pre-boot programs, boot programs and
starter programs, and system images from the master disk to the re-initialized disk. The master disk is
the leftmost valid disk. Valid indicates that the disk is online, has been properly initialized, and is not
marked as invalid or unusable.
Note: If the current master disk is taken offline, reinitialized or declared invalid or unusable, the
leftmost valid disk that has not been reinitialized since restart becomes the master disk. Thus
as disks are reinitialized in sequence, a point is reached where no disk can be chosen as the
master. At this point, the current master disk is the last disk. If this disk is taken offline,
reinitialized, or declared invalid or unusable, the SG appliance is restarted.
Reinitialization is done without rebooting the SG appliance. The SG appliance operations, in turn, are
not affected, although during the time the disk is being reinitialized, that disk is not available for
caching. Note that only the master disk reinitialization might restart the SG appliance.
Syntax
# disk {subcommands]
Subcommands
# disk disk offline disk_number
Takes the disk specified by disk_number off line.
# disk disk reinitialize disk_number
Reinitializes the disk specified by disk_number.
Example
SGOS# disk offline 3
ok
SGOS# disk reinitialize 3
ok
# display
See > display on page 15 for more information.
# exit
Synopsis
Exits from Configuration mode to Privileged mode, from Privileged mode to Standard mode. From
Standard mode, the exit command closes the CLI session.
Syntax
# exit
The exit command has no parameters or subcommands.
Example
SGOS# exit
# help
See Accessing Quick Command Line Help on page 11 for information about this command.
# hide-advanced
Synopsis
Use this command to disable advanced commands.
Note: You can also use the configure command SGOS#(config) hide-advanced {all |
expand} to hide commands.
Syntax
# hide-advanced [subcommands]
Subcommands
# hide-advanced all
Hides all advanced commands.
# hide-advanced expand
Disables expanded commands.
Example
SGOS# hide-advanced expand
ok
SGOS# hide-advanced all
ok
# inline
Synopsis
Installs lists based on your terminal input.
Discussion
The easiest way to create installable lists, such as forwarding hosts, PAC files, and policy files, among
others, is to take an existing file and modify it, or to create the text file on your local system, upload the
file to a Web server, and download the file to the SG appliance. As an alternative, you can enter the list
directly into the SG appliance through the inline command, either by typing the list line by line or by
pasting the contents of the file.
If you choose to create a text file to contain the configuration commands and settings, be sure to assign
the file the extension .txt. Use a text editor to create this file, noting the following SG appliance
configuration file rules:
❐ Only one command (and any associated parameters) permitted, per line
❐ Comments must begin with a semicolon (;)
❐ Comments can begin in any column, however, all characters from the beginning of the
comment to the end of the line are considered part of the comment and, therefore, are ignored
Tips:
❐ When entering input for the inline command, you can correct mistakes on the current line
using the backspace key. If you catch a mistake in a line that has already been terminated with
the Enter key, you can abort the inline command by typing <Ctrl-c>. If the mistake is caught
after you terminate input to the inline command, you must re-enter the entire content.
❐ The end-of-input marker is an arbitrary string chosen by the you to mark the end of input for
the current inline command. The string can be composed of standard characters and numbers,
but cannot contain any spaces, punctuation marks, or other symbols.
Choose a unique end-of-input string that does not match any string of characters in the
configuration information. One recommended end-of-input string is ’’’ (three single quotes).
Syntax
# inline {subcommands]
Subcommands
# inline accelerated-pac eof_marker
Updates the accelerated pac file with the settings you include between the beginning eof_marker and
the ending eof_marker.
# inline authentication-form form_name eof_marker
Install an authentication form from console input
# inline authentication-forms eof_marker
Install all authentication form from console input
# inline banner eof_marker
Updates the login banner for the telnet and SSH consoles with the settings you include between the
beginning eof_marker and the ending eof_marker.
Example
SGOS# inline wccp eof
wccp enable eof
’’’
# kill
Synopsis
Terminates a CLI session.
Syntax
# kill session_number
where session_number is a valid CLI session number.
Example
> show sessions
Sessions:
# state type start elapsed
01 IDLE
02 PRIVL ssh 08 Aug 2006 21:27:51 UTC 23:08:04
03* NORML ssh 10 Aug 2006 20:35:40 UTC 00:00:15
...
> enable
Enable Password:
# kill 3
ok
# licensing
Synopsis
Use these commands to request or update licenses.
Syntax
# licensing [subcommands]
Subcommands
# licensing request-key [force} user_id password
Requests the license key from Blue Coat using the WebPower user ID and password.
# licensing update-key [force]
Updates the license key from Blue Coat now.
# licensing register-hardware [force] user_ID password
Register hardware with Bluecoat.
# licensing mark-registered
Mark the hardware registered manually.
# licensing disable-trial
Disable trial period.
# licensing enable-trial
Enable trial period.
Example
SGOS# licensing request-key
User ID: admin
Password: *****
...
ok
where “. . .” represents license download-in-progress information.
# load
Synopsis
Downloads installable lists or system upgrade images. These installable lists or settings also can be
updated using the inline command.
Syntax
# load accelerated-pac
Downloads the current accelerated pac file settings.
# load authentication-form form_name
Downloads the new authentication form.
# load authentication-forms
Downloads the new authentication forms.
# load exceptions
Downloads new exceptions.
# load forwarding
Downloads the current forwarding settings.
# load icp-settings
Downloads the current ICP settings.
# load license-key
Downloads the new license key.
# load policy {central | forward | local | vpm-cpl | vpm-xml}
Downloads the policy file specified
# load rip-settings
Downloads the current RIP settings.
# load socks-gateways
Downloads the current SOCKS gateways settings.
# load sg-client-software
Loads the SG Client software to the Client Manager. To use this command, you must have previously
defined an upload location using #(config) sg-client on page 310. Messages display as
the software loads.
# load static-route-table
Downloads the current static route table settings.
# load upgrade [ignore-warnings]
Downloads the latest system image. The ignore-warnings option allows you to force an upgrade even if
you receive policy deprecation warnings. Note that using the load upgrade ignore-warnings command
to force an upgrade while the system emits deprecation warnings results in a policy load failure; all
traffic is allowed or denied according to default policy.
# load wccp-settings
Downloads the current WCCP settings.
# load timezone-database
Downloads a new time zone database.
Example
> show download-paths
Policy
Local:
Forward:
VPM-CPL:
VPM-XML:
Central: https://download.bluecoat.com/release/SG3/files/CentralPolicy.txt
Update when changed: no
Notify when changed: no
Polling interval: 1 day
Accelerated PAC:
ICP settings:
RIP settings:
Static route table:
Upgrade image:
bcserver1.bluecoat.com/builds/ca_make.26649/wdir/8xx.CHK_dbg
WCCP settings:
Forwarding settings:
SOCKS gateway settings:
License key:
Exceptions:
Authentication forms:
>en
Enable Password
# load upgrade
Downloading from
"bcserver1.bluecoat.com/builds/ca_make.26649/wdir/8xx.CHK_dbg"
Downloading new system software (block 2611)
The new system software has been successfully downloaded.
Use "restart upgrade" to install the new system software.
# pcap
Synopsis
The PCAP utility enables you to capture packets of Ethernet frames entering or leaving a SG
appliance. Packet capturing allows filtering on various attributes of the frame to limit the amount of
data collected. The collected data can then be transferred to the desktop for analysis.
Note: Before using the PCAP utility, consider that packet capturing doubles the amount of
processor usage performed in TCP/IP.
To view the captured packets, you must have a tool that can read Packet Sniffer Pro 1.1 files.
Syntax
# pcap [subcommands]
Subcommands
# pcap filter on page 60
Specifies filters to use for PCAP.
# pcap info
Displays the current packet capture information.
# pcap start on page 62
Starts the capture.
# pcap stop
Stops the capture.
# pcap transfer full_url/filename username password
Transfers captured data to an FTP site.
Example 1
Capture transactions among a SG appliance (10.1.1.1), a server (10.2.2.2), and a client (10.1.1.2).
SGOS# pcap filter expr “host 10.1.1.1 || host 10.2.2.2 || host 10.1.1.2”
Example 2
This example transfers captured packets to the FTP site 10.25.36.47. Note that the username and
password are provided.
SGOS# pcap transfer ftp://10.25.36.47/path/filename.cap username password
If the folders in the path do not exist, they are not created. An error message is generated.
# pcap filter
Synopsis
After a filter is set, it remains in effect until it is redefined; the filtering properties are persistent across
reboots. However, PCAP stops when a system is rebooted.
Syntax
# pcap filter [subcommands]
Subcommands
# pcap filter [direction {in | out | both}]
Specifies capture in the specified direction. If both is selected, both incoming and outgoing packets are
captured. The default setting is both.
# pcap filter [interface adapter_number:interface_number | all]
Specifies capture on the specified interface or on all interfaces. For example, 0:1. The interface number
must be between 0 and 16. The default setting is all.
# pcap filter [expr filter_expression]
Specifies capture only when the filter expression matches.
# pcap filter
No filtering specified (captures all packets in both directions---on all interfaces).
Example
This example configures packet capturing in both directions, on all interfaces, to or from port 3035:
# pcap filter direction both interface all expr “port 3035”
ok
To verify the settings before starting PCAP, enter pcap info:
SGOS# pcap info
Current state: Stopped
Filtering: On
Filter: direction both interface all expr "port 3035"
Packet capture information:
Packets captured: 0
Bytes captured: 0
Packets written: 0
Bytes written: 0
Coreimage ram used: 0B
Packets filtered through: 0
To start PCAP, enter pcap start. Then run pcap info to view the results of the packet capture.
SGOS# pcap start
ok
SGOS# pcap info
Current state: Capturing
Filtering: On
Filter: direction both interface all expr "port 3035"
Packet capture information:
first count 4294967295 capsize 100000000 trunc 4294967295 coreimage 0
Packets captured: 2842
Bytes captured: 237403
Packets written: 2836
Bytes written: 316456
Coreimage ram used: 0B
Packets filtered through: 8147
After PCAP is stopped (using the pcap stop command), enter pcap info to view the results of your
PCAP session. You should see results similar to the following:
SGOS# pcap info
Current state: Stopped
Filtering: On
Filter: direction both interface all expr "port 3035"
Packet capture information:
Packets captured: 5101
Bytes captured: 444634
Packets written: 5101
Bytes written: 587590
Coreimage ram used: 0B
Packets filtered through: 10808
# pcap start
Synopsis
Start packet capture. The pcap start options are not persistent across reboots. You must reconfigure
them if you reboot the system.
Syntax
# pcap start [subcommands]
Subcommands
[buffering-method]
Syntax: [first | last] {[count <N>]|[capsize <NKB>]}
The buffering method specifies how captured packets are buffered in memory. The amount of
packets buffered cannot exceed a hard limit of 100MB.
[count] and [capsize]
The count option specifies that the buffer limit is controlled by the number of packets stored
in the buffer. The value of count must be between 1 and 1000000.
The capsize option specifies that the buffer limit is controlled by the total number of bytes of
packets stored in the buffer. The capsize value must be between 1 and 102400.
Note: The first option is a specific command; it captures an exact number of packets. If
no parameters are specified, the default is to capture until the stop subcommand is issued or
the maximum limit reached.
[coreimage n]
Specifies kilobytes of packets kept in a core image. The coreimage size must be between 0 and 102400.
By default, no packets are kept in the core image.
[trunc n]
The trunc n parameter collects, at most, n bytes of packets from each frame when writing to disk. The
range is 1 to 65535.
Example 1
The following command captures the first 2000 packets that match the filtering expression:
# pcap start first count 2000
Note that the first option configures PCAP to stop capturing after the buffer limit of 2000 packets has
been reached. If the last option had been specified, PCAP keeps capturing packets even after the
buffer limit had been exceeded, until halted by the pcap stop command.
Example 2
The following command stops the capturing of packets after approximately three kilobytes of packets
have been collected.
SGOS# pcap start first capsize 3
# ping
Synopsis
Use this command to verify that a particular IP address exists and can accept requests. Ping output
also tells you the minimum, maximum, and average time it took for the ping test data to reach the
other computer and return to the origin.
Syntax
# ping {ip_address | hostname}
where ip_address is the IP address and hostname is the hostname of the remote computer.
Example
SGOS# ping 10.25.36.47
Type escape sequence to abort.
Sending 5, 64-byte ICMP Echos to 10.25.36.47, timeout is 2 seconds:
!!!!!
Success rate is 100 percent (5/5), round-trip min/avg/max = 0/0/0 ms
Number of duplicate packets received = 0
# policy
Synopsis
Use this command to configure policy commands.
Note: Configuring the policy command to trace all transactions by default can significantly
degrade performance and should only be used in situations where a problem is being
diagnosed.
Syntax
# policy trace {all | none}
Use all to trace all transactions by default, and use none to specify no tracing except as specified
in policy files.
Example
policy trace all
ok
All requests will be traced by default;
Warning: this can significantly degrade performance.
Use 'policy trace none' to restore normal operation
SGOS# policy trace none
ok
# purge-dns-cache
Synopsis
This command clears the DNS cache. You can purge the DNS cache at any time. You might need to do
so if you have experienced a problem with your DNS server, or if you have changed your DNS
configuration.
Syntax
# purge-dns-cache
The purge-dns-cache command has no parameters or subcommands.
Example
SGOS# purge-dns-cache
ok
register-with-director
Synopsis
The register-with-director command is a setup command that automatically registers the SG
appliance with a Blue Coat Director, thus enabling that Director to establish a secure administrative
session with the appliance. During the registration process, Director can “lock out” all other
administrative access to the appliance so that all configuration changes are controlled and initiated by
Director.
If your appliance does not have an appliance certificate, you must specify the registration password
that is configured on Director.
Syntax
# register-with-director dir_ip_address [appliance_name dir_serial_number]
Example
SGOS# register-with-director 192.168.0.x
Registration Successful
# restart
Synopsis
Restarts the system. The restart options determine whether the SG appliance should simply reboot the
SG appliance (regular), or should reboot using the new image previously downloaded using the load
upgrade command (upgrade).
Syntax
# restart [subcommands]
Subcommands
# restart abrupt
Reboots the system abruptly, according to the version of the SG appliance that is currently installed.
Restart abrupt saves a core image. Note that the restart can take several minutes using this option.
# restart regular
Reboots the version of the SG appliance that is currently installed
# restart upgrade
Reboots the entire system image and allows you to select the version you want to boot, not limited to the
new version on the system.
Example
SGOS# restart upgrade
ok
SGOS# Read from remote host 10.9.17.159: Connection reset by peer
Connection to 10.9.17.159 closed.
# restore-sgos4-config
Restores the SG appliance to settings last used with SGOS 4.x. The SG appliance retains the network
settings. Note that a reboot is required to complete this command.
Syntax
# restore-sgos4-config
Example
SGOS# restore-sgos4-config
Restoring SGOS 4.x configuration requires a restart to take effect.
The current configuration will be lost and the system will be restarted.
Continue with restoring? (y/n)[n]: y
Restoring configuration ...
Or if there is no SGOS 4.x configuration found:
SGOS# restore-sgos4-config
%% No SGOS 4.x configuration is available on this system.
# restore-defaults
Synopsis
Restores the SG appliance to the default configuration. When you restore system defaults, the SG
appliance’s IP address, default gateway, and the DNS server addresses are cleared. In addition, any
lists (for example, forwarding or bypass) are cleared. After restoring system defaults, you need to
restore the SG appliance’s basic network settings, as described in Volume 9: Managing the Blue Coat SG
Appliance, and reset any customizations.
Syntax
# restore-defaults [subcommands]
Subcommands
# restore-defaults factory-defaults
Reinitializes the SG appliance to the original settings it had when it was shipped from the factory
# restore-defaults force
Restores the system defaults without confirmation.
If you don’t use the force command, you are prompted to enter yes or no before the
restoration can proceed.
# restore-defaults keep-console [force]
Restores defaults except settings required for console access. Using the keep-console option retains
the settings for all consoles (Telnet-, SSH-, HTTP-, and HTTPS-consoles), whether they are enable,
disabled, or deleted.
If you use the force command, you are not prompted to enter yes or no before restoration can
proceed.
Example
SGOS# restore-defaults
Restoring defaults requires a restart to take effect.
The current configuration will be lost and the system will be restarted.
Continue with restoring? (y/n)[n]: n
Existing configuration preserved.
# reveal-advanced
Synopsis
The reveal-advanced command allows you to enable all or a subset of the advanced commands
available to you when using the CLI. You can also use SGOS#(config) hide-advanced {all |
expand} to reveal hidden commands.
Syntax
# reveal-advanced [subcommands]
Subcommands
# reveal-advanced all
Reveals all advanced commands.
# reveal-advanced expand
Enables expanded commands.
Example
SGOS# reveal-advanced all
ok
# show
The # show command displays all the show commands available in the standard mode plus the show
commands available only in privileged mode and configuration mode. Only show commands
available in privileged mode are discussed here. For show commands also available in the standard
mode, see > show on page 20.
Synopsis
Use this command to display system information.
Syntax
# show [subcommands]
Subcommands
# show archive-configuration
Displays archive configuration settings.
# show adn
Displays ADN configuration.
# show attack-detection on page 75
Displays client attack-detection settings.
# show configuration on page 76
Displays system configuration.
# show connection-forwarding
Displays TCP connection forwarding status and peer IP address list.
# show content on page 77
Displays content-management commands.
# show content-filter {bluecoat | i-filter | intersafe | iwf | local | optenet |
proventia | smartfilter | surfcontrol | status | websense | webwasher}
Shows settings for Blue Coat Web Filter or the various third-party content-filtering vendors. You can get
information on current content-filtering status by using the # show content-filter status
command.
# show proxy-services on page 78
Displays information on static and dynamic bypass and proxy-service behavior.
# show realms
Displays the status of each realm.
# show security on page 79
Displays security settings.
# show ssh on page 80
Displays SSH settings.
# show sg-client
Displays SG Client settings.
# show ssl on page 81
Also available in standard mode, the # show ssl command offers more options in privileged mode.
# show system-resource-metrics
Displays system resource statistics.
Examples
# show archive-configuration
Archive configuration
Protocol: FTP
Host:
Path:
Filename:
Username:
Password: ************
# show content-filter status
Provider: Blue Coat
Status: Database unavailable
Download URL:
https://list.bluecoat.com/bcwf/activity/download/bcwf.db
Download Username:
Automatic download: Enabled
Download time of day (UTC): 0
Download on: sun, mon, tue, wed, thu, fri, sat
Category review message: Disabled
Dynamic Categorization Service: Enabled
Dynamic Categorization Mode: Real-time
Download log:
Blue Coat download at: Sat, 18 Mar 2006 01:57:24 UTC
Downloading from https://list.bluecoat.com/bcwf/activity/download/bcwf.db
Requesting differential update
Differential update applied successfully
Download size: 84103448
Database date: Thu, 09 Feb 2006 08:11:51 UTC
Database expires: Sat, 11 Mar 2006 08:11:51 UTC
Database version: 2005040
# show realms
Local realm:
No local realm is defined.
RADIUS realm:
Realm name: RADIUS1
Display name: RADIUS1
Case sensitivity: enabled
Primary server host: 10.9.59.210
Primary server port: 1812
Primary server secret: ************
Alternate server host:
Alternate server port: 1812
Alternate server secret: ************
Server retry count: 5
Cache duration: 900
Virtual URL:
Server timeout: 5
Spoof authentication: none
One time passwords: no
LDAP realm(s):
No LDAP realms are defined.
# show adn
Synopsis
Displays ADN settings and statistics.
Syntax
# show adn [subcommands]
Subcommands
# show adn byte-cache
Displays ADN byte-cache settings.
# show adn routing [advertise-internet-gateway | server-subnets]
Displays ADN routing settings.
# show adn tunnel
Displays ADN tunnel configuration.
Example
# show adn
Application Delivery Network Configuration:
ADN: disabled
Manager port: 3034
Tunnel port: 3035
Primary manager: none
Backup manager: none
External VIP: none
Byte-cache Configuration:
Max number of peers: 10347
Max peer memory: 30
Tunnel Configuration:
proxy-processing http: disabled
TCP window size: 65536
reflect-client-ip : use-local-ip
Routing Configuration:
Internet Gateway: disabled
Exempt Server subnet: 10.0.0.0/8
Exempt Server subnet: 172.16.0.0/16
Exempt Server subnet: 192.168.0.0/16
# show attack-detection
Synopsis
Displays client attack-detection settings and client and server statistics.
Syntax
# show attack-detection [subcommands]
Subcommands
client [blocked | connections | statistics]
Displays client attack-detection settings.
client configuration
Displays attack-detection configuration.
server [statistics]
Displays server statistics
# show configuration
Synopsis
Displays the current configuration, as different from the default configuration.
Syntax
# show configuration [subcommands]
Subcommands
# show configuration
Displays all settings
# show configuration brief
Displays the configuration without inline expansion.
# show configuration expanded
Displays the configuration with inline expansion.
# show configuration noprompts
Displays the configuration without --More-- prompts.
# show configuration post-setup
Displays the configuration made after console setup.
Example
Assuming non-default settings of:
# show content
Synopsis
Displays content-management commands.
Syntax
# show content [subcommands]
Subcommands
# show content outstanding-requests
Displays the complete list of outstanding asynchronous content revalidation and distribute requests;
# show content priority [regex regex | url url]
displays the deletion priority value assigned to the regex or url, respectively
# show content url url
Displays statistics of the specified URL.
# show proxy-services
Synopsis
Information about proxy services
Syntax
# show proxy-services [subcommands]
Subcommands
# show proxy-services
Displays all proxy services configured on the system.
# show proxy-services dynamic-bypass
Displays dynamic-bypass information.
# show proxy-services services bypass
Display services containing a bypass action.
# show proxy-services services intercept
Display services containing an intercept action.
# show proxy-services services name
Display services with name substring match.
# show proxy-services services proxy
Display services using a specific proxy.
# show proxy-services static-bypass
Displays static-bypass information.
# show security
Synopsis
Displays information about security parameters.
Syntax
# show security [subcommands]
Subcommands
# show security
Displays all security settings on the system.
# show security authentication-errors
Displays all authentication errors.
# show security authentication-forms
Displays authentication forms configured on the system.
# show security local-user-list
Displays the local user list configured on the system.
# show security local-user-list-group
Displays the groups in local user list.
# show security local-user-list-user
User in local user list
Example
# show security
Account:
Username: "admin"
Hashed Password: $1$it$24YXwuAGbmvQl7zhaeG5u.
Hashed Enable Password: $1$U1JZbCl1$itmTNhAwhymF2BNwBnum1/
Hashed Front Panel PIN: "$1$50KI$KR0RtYxQl02Z26cLy.Pq5."
Management console display realm name: ""
Management console auto-logout timeout: 900 seconds
Access control is disabled
Access control list (source, mask):
Flush credentials on policy update is enabled
Default authenticate.mode: auto
Transparent proxy authentication:
Method: cookie
Cookie type: session
Cookie virtual-url: "www.cfauth.com/"
IP time-to-live: 15
Verify IP: yes
Allow redirects: no
.
.
.
# show ssh
Synopsis
Displays the SSH service details.
Syntax
# show ssh [subcommands]
Subcommands
# show ssh client-key [username]
Displays the client key fingerprint for the specified username.
Note: If you upgraded from an older version of the SG appliance, you might not need to enter a
username.
Example
# show ssh versions-enabled
SSHv2 is enabled.
# show ssl
Synopsis
Displays SSL settings.
Syntax
# show ssl [subcommands]
Subcommands
# show ssl ca-certificate name
Displays the CA certificate configuration
# show ssl ccl [list_name]
Displays currently configured CA certificate lists or configuration for the specified list_name. This
option can also be viewed from standard mode.
# show ssl certificate keyring_id
Displays the certificate configuration for the specified keyring.
# show ssl crl crl_id
Displays the SSL certificate Revocation List (CRL) of the specified ID.
# show ssl external-certificate name
Displays external certificate configuration of the specified name.
# show ssl intercept
Displays the SSL intercept configuration.
# show ssl keypair {des | des3 | unencrypted} keyring_id
Displays the keypair. If you want to view the keypair in an encrypted format, you can optionally specify
des or des3 before the keyringID. If you specify either des or des3, you are prompted for the
challenge entered when the keyring was created.
# show ssl keyring [keyring_id]
Displays all keyrings or the keyring of the specified ID.
# show ssl secure-signing-request keyring_id
Displays signed certificate signing request for the specified keyring.
# show ssl signing-request keyring_id
Displays the certificate signing request configuration for the specified keyring.
# show ssl ssl-client [ssl_client]
Displays information about all SSL clients or the specified SSL client. This option can also be viewed
from standard mode.
# show ssl ssl-nego-timeout
Displays the SSL negotiation timeout configuration.
# show ssl summary {ca-certificate | crl | external-certificate}
Displays the SSL summary information for CA certificates, CRLs, or external certificates.
Example
# show ssl keyring
KeyringID: configuration-passwords-key
Is private key showable? yes
Have CSR? no
Have certificate? no
KeyringID: default
Is private key showable? yes
Have CSR? no
Have certificate? yes
Is certificate date range valid? yes
CA: Blue Coat SG200 Series
Expiration Date: Mar 02 22:25:32 2016 GMT
Fingerprint: B2:DE:C4:98:58:18:3C:E3:B3:4A:1C:FC:AB:B5:A4:74
# temporary-route
This command is used to manage temporary route entries. After a reboot these routes are lost.
Syntax
# temporary-route [subcommands]
Subcommands
# temporary-route add destination_address netmask gateway_address
Adds a temporary route entry.
# temporary-route delete destination_address
Deletes a temporary route entry.
# test
This command is used to test subsystems. A test http get command to a particular origin server or
URL, for example, can verify Layer 3 connectivity and also verify upper layer functionality.
Syntax
# test http [subcommands]
Subcommands
# test http get url
Does a test Get of an HTTP object specified by url.
# test http loopback
Does a loopback test.
Example
SGOS# test http loopback
Type escape sequence to abort.
Executing HTTP loopback test
Measured throughput rate is 16688.96 Kbytes/sec
HTTP loopback test passed
SGOS# test http get http://www.google.com
Type escape sequence to abort.
Executing HTTP get test
* HTTP request header sent:
GET http://www.google.com/ HTTP/1.0
Host: www.google.com
User-Agent: HTTP_TEST_CLIENT
* HTTP response header recv'd:
HTTP/1.1 200 OK
Connection: close
Date: Tue, 15 Jul 2003 22:42:12 GMT
Cache-control: private
Content-Type: text/html
Server: GWS/2.1
Content-length: 2691
Set-Cookie:
PREF=ID=500ccde1707c20ac:TM=1058308932:LM=1058308932:S=du3WuiW7FC_lJ
Rgn; expires=Sun, 17-Jan-2038 19:14:07 GMT; path=/; domain=.google.com
Measured throughput rate is 66.72 Kbytes/sec
HTTP get test passed
# traceroute
Use this command to trace the route to a destination. The traceroute command can be helpful in
determining where a problem might lie between two points in a network. Use traceroute to trace the
network path from a SG appliance back to a client or to a specific origin Web server.
Note that you can also use the trace route command from your client station (if supported) to trace the
network path between the client, a SG appliance, and a Web server. Microsoft operating systems
generally support the trace route command from a DOS prompt. The syntax from a Microsoft-based
client is: tracert [ip | hostname].
Syntax
# traceroute [subcommands]
Subcommands
# traceroute IP_address
Indicates the IP address of the client or origin server.
# traceroute hostname
Indicates the hostname of the origin server.
Example
SGOS# traceroute 10.25.36.47
Type escape sequence to abort.
Executing HTTP get test
HTTP response code: HTTP/1.0 503 Service Unavailable
Throughput rate is non-deterministic
HTTP get test passed
10.25.36.47# traceroute 10.25.36.47
# upload
Uploads the current access log or running configuration.
Syntax
# upload {subcommands}
Subcommands
# upload access-log all
Uploads all access logs to a configured host.
# upload access-log log log_name
Uploads a specified access log to a configured host.
# upload configuration
Uploads running configuration to a configured host.
Example
SGOS# upload configuration
ok
Configure Commands
The configure command allows you to configure the Blue Coat SG appliance settings from your
current terminal session (configure terminal), or by loading a text file of configuration settings from
the network (configure network).
Syntax
configure {terminal | network url}
configure_command
configure_command
.
.
.
where configure_command is any of the configuration commands in this document. Type a question
mark after each of these commands for a list of subcommands or options with definitions.
87
#(config) accelerated-pac #(config) accelerated-pac
#(config) accelerated-pac
Synopsis
Set the path to download PAC files.
Discussion
Normally, a Web server serves the Proxy Auto-Configuration (PAC) file to client browsers. This feature
allows you to load a PAC file onto the SG appliance for high performance PAC file serving right from
the device. There are two ways to create an accelerated PAC file:
❐ customize the default PAC file and save it as a new file
❐ Create a new custom PAC file.
In either case, it is important that the client instructions for configuring SG appliance settings contain
the URL of the Accelerated-PAC file. Clients load PAC files from:
https://SG_IP_Address:8082/accelerated_pac_base.pac.
Syntax
#(config) accelerated-pac no path
Clears the network path to download PAC file.
#(config) accelerated-pac path url
Specifies the location to which the PAC file should be downloaded.
Example
#(config) accelerated-pac path url
#(config) load accelerated-pac
#(config) access-log
Synopsis
The SG appliance can maintain an access log for each HTTP request made. The access log can be stored
in one of three formats, which can be read by a variety of reporting utilities.
Syntax
#(config) access-log
This changes the prompt to:
#(config access-log)
Subcommands
#(config access-log) create log log_name
Creates an access log.
#(config access-log) create format format_name
Creates an access log format.
#(config access-log) cancel-upload all
Cancels upload for all logs.
#(config access-log) cancel-upload log log_name
Cancels upload for a log
#(config access-log) default-logging {cifs | epmapper | ftp | http |
https-forward-proxy | https-reverse-proxy | icp | im | mapi | mms | p2p | rtsp
| socks | ssl | tcp-tunnel | telnet} log_name
Sets the default log for the specified protocol.
#(config access-log) delete log log_name
Deletes an access log.
#(config access-log) delete format format_name
Deletes an access log format.
#(config access-log) disable
Disables access logging.
#(config access-log) early-upload megabytes
Sets the log size in megabytes that triggers an early upload.
#(config access-log) edit log log_name—changes the prompt (see #(config log log_name)
on page 92)
#(config access-log) edit format format_name—changes the prompt (see #(config format
format_name) on page 96)
#(config access-log) enable
Enables access logging.
#(config access-log) exit
Exits #(config access-log) mode and returns to #(config) mode.
#(config access-log) max-log-size megabytes
Sets the maximum size in megabytes that logs can reach.
Example
SGOS#(config) access-log
SGOS#(config access-log) create log test
ok
SGOS#(config access-log) max-log-size 1028
ok
SGOS#(config access-log) overflow-policy delete
ok
View the results. (This is a partial output.)
SGOS#(config access-log) view log
Settings:
Log name: main
Format name: main
Description:
Logs uploaded using FTP client
Logs upload as gzip file
Wait 60 seconds between server connection attempts
FTP client:
Filename format: SG_%f_%l%m%d%H%M%S.log
Filename uses utc time
Use PASV: yes
Synopsis
Use these commands to edit an access log.
Syntax
#(config) access-log
This changes the prompt to:
#(config access-log)
#(config access-log) edit log log_name
This changes the prompt to:
#(config log log_name)
Subcommands
#(config log log_name) bandwidth-class bwm_class_name
Specifies a bandwidth-management class for managing the bandwidth of this log.In order to
bandwidth-manage this log, bandwidth management must be enabled. Bandwidth management is
enabled by default.
Note: You must also create a bandwidth class for this access log (in bandwidth-management
mode) before you can select it here. See #(config) bandwidth-management on page 117 for more
information
Example
SGOS#(config) access-log
SGOS#(config access-log) edit log testlog
SGOS#(config log testlog) upload-type gzip
ok
SGOS#(config log testlog) exit
SGOS#(config access-log) exit
SGOS#(config)
Synopsis
Use these commands to edit an access log format.
Syntax
#(config) access-log
This changes the prompt to:
#(config access-log) edit format format_name
This changes the prompt to:
#(config format format_name)
Subcommands
#(config format format_name) exit
Exits #(config format format_name) mode and returns to #(config access-log) mode.
#(config format format_name) multi-valued-header-policy log-all-headers
Sets multi-valued header policy to log all headers.
#(config format format_name) multi-valued-header-policy log-first-header
Sets multi-valued header policy to log the first header.
#(config format format_name) multi-valued-header-policy log-last-header
Sets multi-valued header policy to log the last header.
#(config format format_name) type custom format_string
Specifies custom logging format.
#(config format format_name) type elff format_string
Specifies W3C extended log file format.
#(config format format_name) view
Shows the format settings.
Example
SGOS#(config) access-log
SGOS#(config access-log) edit format testformat
SGOS#(config format testformat) multi-valued-header-policy log-all-headers
ok
SGOS#(config format testformat) exit
SGOS#(config access-log) exit
SGOS#(config)
#(config) adn
Synopsis
ADN optimization allows you to reduce the amount of tunneled TCP traffic across a WAN by means
of an overlay network called an Application Delivery Network, or ADN. SG devices that participate in
the ADN utilize byte caching technology, which replaces large chunks of repeated data with small
tokens representing that data. SG devices in the ADN also use gzip compression to further reduce the
amount of data flowing over the WAN.
Syntax
SGOS#(config) adn
The prompt changes to
SGOS#(config adn)
Subcommands
SGOS#(config adn) byte-cache
Configures byte caching parameters. The prompt changes to SGOS#(config adn byte-cache)
SGOS#(config adn byte-cache) exit
Exits the SGOS#(config adn byte-cache) submode and returns to SGOS#(config adn)
mode.
SGOS#(config adn byte-cache) peer-size peer-id {size_in_megabytes | auto}
Manually sets the amount of memory used to keep track of the byte-cache hash table. Generally,
the dynamic settings are acceptable; you do not need to change the dictionary size. Only if
you determine that the algorithm performance does not guarantee a sufficient dictionary
size for a specific peer should you manually set the dictionary size.
SGOS#(config adn byte-cache) view
Views the current configuration of the byte caching parameters.
SGOS#(config adn) {enable | disable}
Enables or disables the ADN optimization network.
SGOS#(config adn) exit
Exits the SGOS#(config adn) submode and returns to SGOS#(config) mode.
SGOS#(config adn) load-balancing
Configures load-balancing parameters. The prompt changes to SGOS#(config adn
load-balancing).
SGOS#(config adn load-balancing) {enable | disable}
Enables or disables load-balancing functionality.
SGOS#(config adn load-balancing) exit
Exits the submode and returns to SGOS#(config adn) mode.
SGOS#(config adn load-balancing) external-vip IP_address
Sets the external VIP. The same VIP must be configured on each SG appliance in the cluster, and the
VIP must exist on an external load balancing device. The external VIP is used in explicit external
load balancing.
SGOS#(config adn load-balancing) group group_name
Sets the group name for an ADN group. Groups are used in transparent load balancing.
SGOS#(config adn load-balancing) load-balance-only {enable | disable}
Specifies whether the node can take participate in load balancing (disable) or if it acts as a load
balancer only (enable).
Configure outbound connection encryption, where none indicates the encryption is disabled,
routing-only enables encryption on outbound traffic, secure-proxies enables encryption on
secure proxy (that is, HTTPS or SSL) traffic, and all indicates that encryption is enabled on all
outbound connections.
SGOS#(config adn security) tunnel-listening-mode {plain-only | secure-only|
both}
Starts the specified tunnel listening mode.
SGOS#(config adn security) view
View security configuration
SGOS#(config adn) tunnel
Configures parameters for tunnel connections. Tunnel connections are established between ADN peers
in order to carry optimized traffic over the WAN. Changes the prompt to SGOS#(config adn
tunnel).
SGOS#(config adn tunnel) connect-transparent {enable | disable}
Control outbound ADN transparent tunnel initiation
SGOS#(config adn tunnel) exit
Exits the SGOS#(config adn tunnel) submode and returns to SGOS#(config adn) mode.
SGOS#(config adn tunnel) preserve-dest-port {enable | disable}
Preserve destination port on outbound connections
SGOS#(config adn tunnel) port port_number
Sets the port number for the client or data port used by ADN tunnel connections. Each ADN node
has a TCP listener on this port in order to receive tunnel connections. The default is port 3035; it
should not be changed.
SGOS#(config adn tunnel) proxy-processing http {enable | disable}
Enables HTTP handoff. This option should be used with care as both byte caching and object
caching require significant resources. Be sure that your SG devices are sized correctly if you intend
to use this option.
SGOS#(config adn tunnel) reflect-client-ip (allow | deny | use-local-ip)
Allows the concentrator proxy to follow, deny, or ignore the branch proxy reflect-client-ip settings.
SGOS#(config adn tunnel) secure-port port_number
Configure listening port for secure ADN tunnel
SGOS#(config adn tunnel) tcp-window-size
Sets the window size used by TCP on all ADN tunnel connections. The default is 65536.
SGOS#(config adn tunnel) view
Views the current configuration ADN tunnel parameters.
SGOS#(config adn) view
Views the configuration of the WAN optimization parameters you created on this system.
Example
SGOS#(config adn)
SGOS#(config adn) enable
SGOS#(config adn) manager
SGOS#(config adn manager) primary-manager 10.25.36.47
SGOS#(config adn) backup-manager 10.25.36.48
Manager Configuration:
Primary manager: self
Backup manager: none
Port: 3034
Secure port: 3036
Approved device Connecting from
Allow pending devices: enabled
Pending device Connecting from
Byte-cache Configuration:
Max number of peers: 10347
Max peer memory: 30
Tunnel Configuration:
Port: 3035
Secure port: 3037
proxy-processing http: disabled
accept-transparent: enabled
connect-transparent: enabled
preserve-dest-port: enabled
TCP window size: 65536
reflect-client-ip: use-local-ip
Routing Configuration:
Internet Gateway: disabled
Exempt Server subnet: 10.0.0.0/8
Exempt Server subnet: 172.16.0.0/12
Exempt Server subnet: 192.168.0.0/16
Security Configuration:
Device-auth-profile: bluecoat
Manager-listening mode: plain-only
Tunnel-listening mode: plain-only
Authorization: enabled
Secure-outbound: none
#(config) alert
Synopsis
Configures the notification properties of hardware environmental metrics (called sensors) and the
threshold and notification properties of system resource health monitoring metrics. These health
monitoring metrics enable Director (and other third-party network management tools) to provide a
remote view of the health of the SG system.
Syntax
#(config) alert threshold metric_name warning_threshold warning_interval
critical_threshold critical_interval
#(config) alert notification metric_name notification_method
Subcommands
#(config) alert threshold | notification cpu-utilization
Sets alert threshold and notification properties for CPU utilization metrics.
#(config) alert threshold | notification license-utilization license_type
Sets alert threshold and notification properties for licenses with user limits.
#(config) alert threshold | notification license-expiration license_type
Sets alert threshold and notification properties for license expiration.
#(config) alert threshold | notification memory-pressure
Sets alert threshold and notification properties for memory pressure metrics.
#(config) alert threshold | notification network-utilization adapter:interface
Sets alert threshold and notification properties for interface utilization metrics.
#(config) alert notification sensor sensor-type
Sets alert notification properties for hardware environmentals. See “Sensors” on page 103 for a
description of the sensor types.
#(config) alert notification disk-status disk_number
Sets alert notification properties for disk status messages.
Sensors
The following table describes the sensor metrics. The hardware and environmental metrics are
referred to as sensors. Sensor threshold values are not configurable and are preset to optimal values.
For example, if the CPU temperature reaches 55 degrees Celsius, it is considered to have entered the
Warning threshold.
Present
Initializing
Inserted
Slot_empty
Thresholds
The following table describes the health monitoring metrics and default thresholds. Sensor thresholds
cannot be set.
Memory Pressure Percentage Critical: 95/120 Memory pressure occurs when memory
Warning: 90/120 resources become limited, causing new
connections to be delayed.
Network Utilization Percentage Critical: 90/120 Measures the traffic (in and out) on the
Warning: 60/120 interface to determine if it is approaching
the maximum allowable bandwidth.
License Utilization Percentage Critical: 100/0 For licenses that have user limits, monitors
Warning: 90/0 the number of users.
For the purposes of notification, thresholds are defined by two variables, the threshold level and the
threshold interval:
❐ The threshold level describes the state of the metric: OK, Warning, or Critical.
Note: Sensors have different threshold levels than OK, Warning, and Critical. See “Sensors” on page
103 for more information.
❐ The threshold interval specifies the period of time that the metric must stay in the level before
an alert is triggered.
Consider the following command:
#(config) alert threshold cpu-utilization 80 20 90 20
The preceding command sets the cpu-utilization threshold values as follows:
❐ Warning Threshold=80 (percent)
❐ Warning Interval=20 (seconds)
❐ Critical Threshold=90 (percent)
❐ Critical Interval=20 (seconds)
In this example, if CPU activity hovers between 80% and 89% for 20 seconds, the cpu-utilization metric
is considered to be in the Warning condition.
Notification occurs when a threshold state changes, for example, from OK to Warning. See
“Notification Methods” on page 105 for more information.
Notification Methods
The following notification methods can be set. To set more than one type of notification, separate the
notification method by spaces. For example:
sgos# alert notification license-utilization quicktime email log trap
Method Description
email Notify using e-mail only
log Notify using Event log only
trap Notify using SNMP trap only
none Disable notification
Licenses
The license utilization and expiration alert settings can be modified for the following licenses.
Method. Description
The threshold values for license expiration metrics are set in days until expiration. In this context, a
"critical" threshold indicates that license expiration is imminent. This is the only metric in which the
Critical threshold value should be smaller than the Warning threshold value. For example, if you set
the Warning threshold to 45, an alert is sent when there are 45 days remaining in the license period.
The Critical threshold would be less than 45 days, for example 5 days.
For the license expiration metrics, the threshold interval is irrelevant and is set by default to 0. You
should set the Warning Threshold to a value that gives you ample time to renew your license. By
default, all license expiration metrics have a Warning Threshold of 30 days. By default, the Critical
Threshold is configured to 0, which means that a trap is immediately sent upon license expiration.
Examples
#(config) alert threshold cpu-utilization 80 20 90 20
#(config) alert threshold license-utilization quicktime 80 20 90 20
#(config) alert threshold license-expiration quicktime 30 0 5 0
#(config) alert notification cpu-utilization trap
#(config) alert notification license-utilization quicktime email log trap
#(config) archive-configuration
Synopsis
Archiving a SG system configuration on a regular basis is always a good idea. In the rare case of a
complete system failure, restoring an SG appliance to its previous state is simplified by loading an
archived system configuration from an FTP, HTTP, or HTTPS server. The archive contains all system
settings differing from system defaults, along with any forwarding and security lists installed on the
SG appliance.
Archive and restore operations must be done from the CLI. There is no Management Console Web
interface for archive and restore.
Syntax
#(config) archive-configuration [subcommands]
Subcommands
#(config) archive-configuration encrypted-password encrypted_password
Encrypted password for upload host (not required for TFTP)
#(config) archive-configuration filename-prefix filename
Specifies the prefix that should be applied to the archive configuration on upload.
#(config) archive-configuration host hostname
Specifies the FTP host to which the archive configuration should be uploaded.
#(config) archive-configuration password password
Specifies the password for the FTP host to which the archive configuration should be uploaded
#(config) archive-configuration path path
Specifies the path to the FTP host to which the archive configuration should be uploaded.
#(config) archive-configuration protocol {ftp | tftp}
Indicates the upload protocol to be used for the archive configuration using FTP or TFTP.
#(config) archive-configuration username username
Specifies the username for the FTP or FTP host to which the archive configuration should be uploaded.
Example
SGOS#(config) archive-configuration host host3
ok
#(config) attack-detection
Synopsis
The SG appliance can reduce the effects of distributed denial of service (DDoS) attacks and port
scanning, two of the most common virus infections.
The SG appliance prevents attacks by limiting the number of TCP connections from each client IP
address and either will not respond to connection attempts from a client already at this limit or will
reset the connection.
Syntax
#(config) attack-detection
This changes the prompt to:
#(config attack-detection)
Subcommands
#(config attack-detection) client
Changes the prompt to #(config client) on page 111.
#(config attack-detection) exit
Leaves #(config attack-detection) mode and returns to #(config) mode.
#(config attack-detection) server
Changes the prompt to #(config server) on page 114.
#(config attack-detection) view client [blocked | connections | statistics]
Displays client information. The blocked option displays the clients blocked at the network level, the
connections option displays the client connection table, and the statistics option displays client
request failure statistics.
#(config attack-detection) view configuration
Allows you to view attack-detection configuration settings or the number of current connections.
#(config attack-detection) view server [statistics]
Displays server information. The statistics option displays server-connection failure statistics
Example
#(config attack-detection) view configuration
Client limits enabled: false
Client interval: 20 minutes
Default client limits:
Client connection limit: 100
Client failure limit: 50
Client warning limit: 10
Blocked client action: Drop
Client connection unblock time: unlimited
#(config client)
Synopsis
Configures a client for attack detection.
Syntax
#(config attack-detection) client
This changes the prompt to
#(config client)
Subcommands
#(config client) block ip_address [minutes]
Blocks a specific IP address for the number of minutes listed. If the optional minutes argument is
omitted, the client is blocked until explicitly unblocked.
#(config client) create ip_address or ip_address_and_length
Creates a client with the specified IP address or subnet.
#(config client) default {block-action {drop | send-tcp-rst} | connection-limit
number_of_tcp_connections | failure-limit number_of_requests | unblock-time
minutes | warning-limit number_of_warnings}
Default indicates the values that are used if a client does not have specific limits set. These
settings can over overridden on a per-client basis.
If they are modified on a per-client basis, the specified limits become the default for new
clients. To change the limits on a per-client basis, see edit, below.
System defaults for attack-detection limits are:
• block-action: drop
• connection-limit: 100
• failure-limit: 50
• unblock-time: unlimited
• warning-limit: 10
#(config client) delete ip_address or ip_address_and_length
Deletes the specified client.
#(config client) disable-limits
Disables attack detection.
#(config client) edit ip_address
Changes the prompt to #(config client ip_address).
#(config client IP_address) block-action {drop | send-tcp-rst}
Indicates the behavior when the client is at the maximum number of connections or exceed the
warning limit: drop connections that are over the limit or send TCP RST for connections over the
limit. The default is drop.
#(config client IP_address) connection-limit number_of_tcp_connections
Indicates the number of simultaneous connections between 1 and 65535. The default is 100.
#(config client IP_address) exit
Exits the #(config client ip_address) submode and returns to #(config client)
mode.
Example
SGOS#(config) attack-detection
SGOS#(config attack-detection) client
SGOS#(config client) view
Client limits enabled: true
Client interval: 20 minutes
Default client limits:
Client connection limit: 700
Client failure limit: 50
Client warning limit: 10
Blocked client action: Drop
Client connection unblock time: unlimited
#(config server)
Synopsis
Configures a server for attack detection.
Syntax
#(config attack-detection) server
This changes the prompt to:
#(config server)
Subcommands
#(config server) create hostname
Creates a server or server group that is identified by the hostname.
#(config server) delete hostname
Deletes a server or server group.
#(config server) edit hostname
Changes the prompt to #(config server hostname)
#(config server hostname) add hostname
Adds an additional server to this server group.
#(config server hostname) exit
Exits the #(config server hostname) submode and returns to #(config server) mode.
#(config server hostname) request-limit number_of_requests
Indicates the number of simultaneous requests allowed from this server or server group. The default
is 1000.
#(config server hostname) view
Displays the request limit for this server or server group.
#(config server) exit
Exits the #(config server) submode and returns to #(config attack-detection) mode.
#(config server) view [statistics]
Displays the request limit for all servers or server groups.
Example
SGOS#(config) attack-detection
SGOS#(config attack-detection) server
SGOS#(config server) create test1
ok
SGOS#(config server) edit test1
SGOS#(config server test1) add 10.9.17.134
ok
SGOS#(config server test1) view
Server configuration for test1:
Request limit: 1000
Host: 10.9.17.134
#(config) bandwidth-gain
Synopsis
Bandwidth gain is a measure of the effective increase of server bandwidth resulting from the client’s
use of a content accelerator. For example, a bandwidth gain of 100% means that traffic volume from
the SG appliance to its clients is twice as great as the traffic volume being delivered to the SG appliance
from the origin server(s). Using bandwidth gain mode can provide substantial gains in apparent
performance.
Keep in mind that bandwidth gain is a relative measure of the SG appliance’s ability to amplify traffic
volume between an origin server and the clients served by the device.
Syntax
#(config) bandwidth-gain disable
Disables bandwidth-gain mode
#(config) bandwidth-gain enable
Enables bandwidth-gain mode.
Example
SGOS#(config) bandwidth-gain enable
ok
#(config) bandwidth-management
Synopsis
Bandwidth management allows you to classify, control, and, if required, limit the amount of
bandwidth used by a class of network traffic flowing into or out of the SG appliance.
Syntax
#(config) bandwidth-management
This changes the prompt to:
#(config bandwidth-management)
Subcommands
#(config bandwidth-management) create class_name
Creates a bandwidth-management class.
#(config bandwidth-management) delete class_name
Deletes the specified bandwidth-management class. Note that if another class has a reference to the
specified class, this command fails.
#(config bandwidth-management) disable
Disables bandwidth-management.
#(config bandwidth-management) edit class_name—changes the prompt (see #(config
bandwidth-management class_name) on page 118)
#(config bandwidth-management) enable
Enables bandwidth-management.
#(config bandwidth-management) exit
Exits #(config bandwidth-management) mode and returns to #(config) mode.
#(config bandwidth-management) view configuration [bandwidth_class]
Displays bandwidth-management configuration for all bandwidth-management classes or for the class
specified.
#(config bandwidth-management) view statistics [bandwidth_class]
Displays bandwidth-management statistics for all bandwidth-management classes or for the class
specified.
Example
SGOS#(config) bandwidth-management
SGOS#(config bandwidth-management) enable
ok
SGOS#(config bandwidth-management) create Office_A
ok
SGOS#(config bandwidth-management) edit Office_A
SGOS#(config bw-class Office_A) exit
SGOS#(config bandwidth-management) exit
SGOS#(config)
Synopsis
This command allows you to edit a bandwidth-management class.
Syntax
#(config) bandwidth-management
This changes the prompt to:
#(config bandwidth-management)
#(config bandwidth-management) edit class_name
This changes the prompt to:
#(config bandwidth-management class_name)
Subcommands
#(config bandwidth-management class_name) exit
Exits #(config bandwidth-management class_name) mode and returns to #(config
bandwidth-management) mode.
#(config bandwidth-management class_name) max-bandwidth maximum_in_kbps
Sets the maximum bandwidth for this class.
#(config bandwidth-management class_name) min-bandwidth minimum_in_kbps
Sets the minimum bandwidth for this class
#(config bandwidth-management class_name) no max-bandwidth
Resets the maximum bandwidth of this bandwidth-management class to the default (unlimited—no
maximum)
#(config bandwidth-management class_name) no min-bandwidth
Resets the minimum bandwidth of this bandwidth-management class to the default (no minimum).
#(config bandwidth-management class_name) no parent
Clears the parent from this bandwidth-management class.
#(config bandwidth-management class_name) parent class_name
Makes the specified class a parent of the class being configured.
#(config bandwidth-management class_name) priority value_from_0_to_7
Sets the priority for this bandwidth-management class. The lowest priority level is 0 and the highest is 7.
#(config bandwidth-management class_name) view [children]
Displays the settings for this bandwidth-management class or displays the settings for the children of
this bandwidth-management class.
Example
SGOS#(config) bandwidth-management
SGOS#(config bandwidth-management) edit CEO_A
SGOS#(config bw-class CEO_A) parent Office_A
ok
SGOS#(config bw-class CEO_A) priority 2
ok
SGOS#(config bw-class CEO_A) exit
SGOS#(config bandwidth-management) exit
SGOS#(config)
#(config) banner
Synopsis
This command enables you to define a login banner for your users.
Syntax
#(config) banner login string
Sets the login banner to the value of string.
#(config) banner no login
Sets the login banner to null.
Example
#(config) banner login “Sales and Marketing Intranet Web”
ok
#(config) bridge
Synopsis
Allows you to configure bridging.
Syntax
#(config) bridge
This changes the prompt to:
#(config bridge)
Subcommands
#(config bridge) bandwidth-class bridgename
Sets bridge bandwidth class.
#(config bridge) create bridgename
Creates a bridge. This bridge name is case insensitive. You cannot name one bridge “ABC” and
another bridge “abc”.
#(config bridge) delete bridgename
Deletes the bridge.
#(config bridge) edit bridgename
Changes the prompt to #(config bridge bridgename)
#(config bridge bridgename) exit
Exits the #(config bridge hostname) submode and returns to #(config bridge) mode.
#(config bridge) no bandwidth-class
Clears the bandwidth-class settings.
#(config bridge) view {configuration | statistics | fwtable} bridgename
Displays information for the specified bridge or fall all bridges.
Example
SGOS#(config) bridge
SGOS#(config bridge) create test
ok
SGOS#(config bridge) exit
SGOS#(config)
Synopsis
This command allows you to edit a bridge.
Syntax
#(config) bridge
This changes the prompt to:
#(config bridge)
#(config bridge) edit bridge_name
This changes the prompt to:
#(config bridge bridge_name)
Subcommands
#(config bridge bridgename) attach-interface adapter#:interface#
Attaches the interface to the bridge.
#(config bridge bridgename) clear-fwtable {static}
Clears bridge forwarding table.
#(config bridge bridgename) clear-statistics
Clears the bridge statistics.
#(config bridge bridgename) exit
Exits #(config bridge bridge_name) mode and returns to #(config bridge) mode.
#(config bridge bridgename) failover {group | mode} {parallel | serial}
Associates the bridge to a failover group or sets the bridge failover mode.
#(config bridge bridgename) mode ?
Sets the mode for network adapters that can be used as either a pass-through adapter or as a Network
Interface Card.
#(config bridge bridgename) no {interface | failover | static-fwtable-entry}
Clears the settings as follows:
interface: Removes the interface from the bridge.
failover: Negates failover settings.
static-fwtable-entry: Clears the static forwarding table entry.
#(config bridge bridgename) spanning-tree adapter#:interface# {enable | disable}
Enables or disables spanning tree participation.
#(config bridge bridgename) static-fwtable-entry adapter#:interface# mac-address
Adds a static forwarding table entry.
#(config bridge bridgename) view {configuration | statistics | fwtable}
Displays information for the specified bridge.
Example
SGOS#(config) bridge
SGOS#(config bridge) edit b_1
SGOS#(config bridge b_1) attach interface 0:1
ok
SGOS#(config bridge b_1) failover mode parallel
ok
SGOS#(config bridge b_1) exit
SGOS#(config bridge) exit
SGOS#(config)
#(config) caching
Synopsis
Objects can be stored and managed for later retrieval.
Discussion
When a stored HTTP object expires, it is placed in a refresh list. The SG appliance processes the refresh
list in the background, when it is not serving requests. Refresh policies define how the device handles
the refresh process.
The HTTP caching options allow you to specify:
❐ Maximum object size
❐ Negative responses
❐ Refresh parameters
In addition to HTTP objects, the SG appliance can store objects requested using FTP. When the device
retrieves and stores an FTP object, it uses two methods to determine how long the object should stay
cached.
❐ If the object has a last-modified date, the SG appliance assigns a refresh date to the object that
is a percentage of the last-modified date.
❐ If the object does not have a last-modified date, the SG appliance assigns a refresh date to the
object based on a fixed period of time.
Syntax
#(config) caching
This changes the prompt to:
#(config caching)
Subcommands
#(config caching) always-verify-source
Specifies the SG appliance to always verify the freshness of an object with the object source.
#(config caching) exit
Exits the #(config caching) mode and returns to #(config) mode.
#(config caching) ftp—changes the prompt to #(config caching ftp) on page 126
#(config caching) max-cache-size megabytes
Specifies the maximum size of the cache to the value indicated by megabytes.
#(config caching) negative-response minutes
Specifies that negative responses should be cached for the time period identified by minutes
#(config caching) no always-verify-source
Specifies that the SG appliance should never verify the freshness of an object with the object source
#(config caching) refresh automatic
Specifies that the SG appliance should manage the refresh bandwidth.
#(config caching) refresh bandwidth kbps
Specifies the amount of bandwidth in kilobits to utilize for maintaining object freshness.
#(config caching) refresh no automatic
Specifies that the SG appliance should not manage the refresh bandwidth.
Example
SGOS#(config) caching
SGOS#(config caching) always-verify-source
ok
SGOS#(config caching) max-cache-size 100
ok
SGOS#(config caching) negative-response 15
ok
SGOS#(config caching) refresh automatic
ok
SGOS#(config caching) exit
SGOS#(config)
Synopsis
The FTP caching options allow you to specify:
❐ Transparency
❐ Maximum object size
❐ Caching objects by date
❐ Caching objects without a last-modified date: if an FTP object is served without a last
modified date, the SG appliance caches the object for a set period of time.
Syntax
#(config) caching
This changes the prompt to:
#(config caching)
#(config caching) ftp
This changes the prompt to:
#(config caching ftp)
Subcommands
#(config caching ftp) disable | enable}
Disables or enables caching FTP objects
#(config caching ftp) exit
Exits #(config caching ftp) mode and returns to #(config caching) mode.
#(config caching ftp) type-m-percent percent
Specifies the TTL for objects with a last-modified time.
#(config caching ftp) type-n-initial hours
Specifies the TTL for objects with no expiration.
#(config caching ftp) view
Shows the current FTP caching settings.
Example
SGOS#(config caching) ftp
SGOS#(config caching ftp) enable
ok
SGOS#(config caching ftp) max-cache-size 200
ok
SGOS#(config caching ftp) type-m-percent 20
ok
SGOS#(config caching ftp) type-n-initial 10
ok
SGOS#(config caching ftp) exit
SGOS#(config caching) exit
#(config) cifs
Synopsis
Syntax
SGOS#(config) cifs
This changes the prompt to:
SGOS#(config cifs)
Subcommands
SGOS#(config cifs) directory-cache-time seconds
This option determines how long directory information is kept in cache. Changes made to a directory by
clients not using the SG appliance are not visible to SG clients if they occur within this time interval. The
default cache time is 30 seconds.
SGOS#(config cifs) exit
Returns to the (config submode.
SGOS#(config cifs) read-ahead {disable | enable}
This option is enabled by default and improves performance by attempting to fetch and cache blocks of
data that might be requested by a client before the actual request occurs. Disabling this option causes the
SG appliance to fetch and cache only data actually requested by clients.
SGOS#(config cifs) strict-directory-expiration {disable | enable}
This option is disabled by default. When this option is enabled and directory-cache-time has a
value of 0, directories are refreshed synchronously instead of in the background. This is needed when the
set of visible objects in a directory returned by a server can vary between users.
SGOS#(config cifs) view {configuration | statistics}
Views the configuration or statistics of CIFS.
SGOS#(config cifs) write-back (full | none}
This option is set to full by default, which improves performance by acknowledging client writes
immediately and sending them to the server in the background. Setting this option to none forces all
writes to be sent to the server synchronously.
Example
#(config) clock
Synopsis
To manage objects in the cache, an SG appliance must know the current Universal Time Coordinates
(UTC) time. By default, the device attempts to connect to a Network Time Protocol (NTP) server to
acquire the UTC time. The SG appliance includes a list of NTP servers available on the Internet, and
attempts to connect to them in the order they appear in the NTP server list on the NTP tab. If the SG
appliance cannot access any of the listed NTP servers, you must manually set the UTC time using the
clock command.
Syntax
#(config) clock [subcommands]
Subcommands
#(config) clock day day
Sets the Universal Time Code (UTC) day to the day indicated by day. The value can be any integer from
1 through 31.
#(config) clock hour hour
Sets the UTC hour to the hour indicated by hour. The value can be any integer from 0 through 23.
#(config) clock minute minute
Sets the UTC minute to the minute indicated by minute. The value can be any integer from 0 through
59.
#(config) clock month month
Sets the UTC month to the month indicated by month. The value can be any integer from 1 through 12.
#(config) clock second second
Sets the UTC second to the second indicated by second. The value can be any integer from 0 through 59.
#(config) clock year year
Sets the UTC year to the year indicated by year. The value must take the form xxxx.
Example
SGOS#(config) clock year 2003
ok
SGOS#(config) clock month 4
ok
SGOS#(config) clock day 1
ok
SGOS#(config) clock hour 0
ok
SGOS#(config) clock minute 30
ok
SGOS#(config) clock second 59
ok
#(config) console-services
Synopsis
The SG appliance provides console services to communicate:
❐ HTTP (Not enabled by default)
❐ HTTPS
❐ SSH
❐ Telnet (Not created by default; a Telnet proxy service is created by default on port 23.)
Syntax
#(config) console-services
This changes the prompt to:
#(config console-services)
Subcommands
The options below allow you to manage the console service.
#(config console-services) create {http-console | https-console | ssh-console |
telnet-console} console_name
Creates a console service with the service name you choose.
#(config console-services) delete console_name
Deletes the specified service name.
#(config console-services) edit console_name
Changes the prompt, depending on the console service you choose:
• #(config http-console) on page 131
• #(config https-console) on page 132
• #(config ssh-console) on page 134
• #(config telnet-console) on page 135
#(config console-services) exit
Leaves console-services submode; returns to the config prompt.
#(config console-services) view
Views all console services.
Note: If you create a console name with spaces, the name must be enclosed in quotes; for example,
"My Console1".
#(config http-console)
Synopsis
This console service intercepts HTTP traffic, usually on port 80. This console service is created but not
enabled due to security concerns.
Syntax
#(config console-services) edit http_console
This changes the prompt to:
#(config http_console)
Subcommands
#(config http_console) add {all | proxy_ip_address} port {enable | disable}
Add a listener to the console service. All selects all IP addresses on the proxy; alternatively, you can select
a specific proxy’s IP address. You must always choose a port. By default the listener is enabled.
#(config http_console) disable {all | proxy_ip_address} port
Disables the specified listener.
#(config http_console) enable {all | proxy_ip_address} port
Enables the specified listener.
#(config http_console) exit
Exits to the (config console-services) prompt.
#(config http_console) view
Views a summary of the console service’s configuration.
Example
SGOS#(config) console-services
SGOS#(config console-services) create http-console http_console
SGOS#(config console-services) edit http_console
SGOS#(config http_console) add 10.25.36.47 80
SGOS#(config http_console) enable 10.25.36.47 80
#(config https-console)
Synopsis
The HTTPS console intercepts traffic on ports 8082. You can create additional HTTPS consoles if
necessary.
Syntax
#(config console-services) edit https_console
This changes the prompt to:
#(config https_console)
Subcommands
#(config https_console) add {all | proxy_ip_address} port {enable | disable}
Add a listener to the console service. All selects all IP addresses on the proxy; alternatively, you can select
a specific proxy’s IP address. You must always choose a port. By default the listener is enabled.
#(config https_console) attribute cipher-suite cipher-suites
Associates one more cipher suites with the console service. Cipher suites can be any combination of the
following:
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
aes128-sha
aes256-sha
#(config https_console) attribute keyring keyring_ID
Specifies the keyring ID you want to use with this console.
#(config https_console) attribute ssl-versions {sslv2 | sslv3 | tlsv1 | sslv2v3
|sslv2tlsv1 | sslv3tlsv1 | sslv2v3tlsv1}
Selects the SSL versions to use.
#(config https_console) disable {all | proxy_ip_address} port
Disables the specified listener.
#(config https_console) enable {all | proxy_ip_address} port
Enables the specified listener.
#(config https_console) exit
Exits to the (config console-services) prompt.
#(config https_console) view
Views a summary of the console service’s configuration.
Example
SGOS#(config) console-services
SGOS#(config console-services) create https-console https_console
SGOS#(config console-services) edit https_console
SGOS#(config https_console) add 10.25.36.47 80
SGOS#(config https_console) enable 10.25.36.47 80
SGOS#(config https_console) attribute cipher-suite rc4-md5 des-cbc-sha
aes128-sha
Note: For a discussion of available cipher suites, refer to Volume 2: Proxies and Proxy Services.
#(config ssh-console)
Synopsis
The SSH console service allows to you to securely connect to the Command Line Interface. By default,
SSHv2 is enabled and assigned to port 22. You do not need to create a new host key unless you want to
change the existing configuration.
Syntax
#(config console-services) edit ssh_console
This changes the prompt to:
#(config ssh_console)
Subcommands
#(config ssh_console) add {all | proxy_ip_address} port {enable | disable}
Add a listener to the console service. All selects all IP addresses on the proxy; alternatively, you can select
a specific proxy’s IP address. You must always choose a port. By default the listener is enabled.
#(config ssh_console) disable {all | proxy_ip_address} port
Disables the specified listener.
#(config ssh_console) enable {all | proxy_ip_address} port
Enables the specified listener
#(config ssh_console) exit
Exits to the (config console-services) prompt.
#(config ssh_console) view
Views a summary of the console service’s configuration.
Example
SGOS#(config) console-services
SGOS#(config console-services) create ssh-console ssh_console
SGOS#(config console-services) edit ssh_console
SGOS#(config ssh_console) add 10.25.36.47 80
SGOS#(config ssh_console) enable 10.25.36.47 80
#(config telnet-console)
Synopsis
This console service provides access to the administrative CLI through Telnet. Due to security
concerns, use of this console is not recommended.
A shell Telnet proxy service is created on port 23. If you do decide to create a Telnet console, you must
first remove the Telnet proxy service and apply the changes. You can later re-add the Telnet proxy
service on a different port.
Syntax
#(config console-services) edit telnet_console
This changes the prompt to:
#(config telnet_console)
Subcommands
#(config telnet_console) add {all | proxy_ip_address} port {enable | disable}
Add a listener to the console service. All selects all IP addresses on the proxy; alternatively, you can select
a specific proxy’s IP address. You must always choose a port. By default the listener is enabled.
#(config telnet_console) disable {all | proxy_ip_address} port
Disables the specified listener.
#(config telnet_console) enable {all | proxy_ip_address} port
Enables the specified listener.
#(config telnet_console) exit
Exits to the (config console-services) prompt.
#(config telnet_console) view
Views a summary of the console service’s configuration.
Example
SGOS#(config) console-services
SGOS#(config console-services) create telnet-console telnet_console
SGOS#(config console-services) edit telnet_console
SGOS#(config telnet_console) add 10.25.36.47 80
SGOS#(config telnet_console) enable 10.25.36.47 80
#(config) content
Synopsis
Use this command to manage and manipulate content distribution requests and re-validate requests.
Note: The content command options are not compatible with transparent FTP.
Syntax
#(config) content [subcommands]
Subcommands
#(config) content cancel outstanding-requests
Specifies to cancel all outstanding content distribution requests and re-validate requests.
#(config) content cancel url url
Specifies to cancel outstanding content distribution requests and re-validate requests for the URL
identified by url.
#(config) content delete regex regex
Specifies to delete content based on the regular expression identified by regex.
#(config) content delete url url}
Specifies to delete content for the URL identified by url.
#(config) content distribute url [from_url]
Specifies that the content associated with url should be distributed from the origin server.
#(config) content priority {regex priority_0-7 regex
Specifies to add a content deletion policy based on the regular expression identified by regex.
#(config) content priority url priority_0-7 url
Specifies to add a content deletion policy for the URL identified by url.
#(config) content revalidate regex regex
Revalidates the content associated with the regular expression identified by regex with the origin
server.
#(config) content revalidate url url [from_url]
Revalidates the content associated with the url.
Example
SGOS#(config) content distribute http://www.bluecoat.com
Current time: Mon, 01 Apr 2003 00:34:07 GMT
SGOS#(config) content revalidate url http://www.bluecoat.com
Last load time: Mon, 01 Apr 2003 00:34:07 GMT
SGOS#(config) content distribute http://www.bluecoat.com
Current time: Mon, 01 Apr 2003 00:35:01 GMT
SGOS#(config) content priority url 7 http://www.bluecoat.com
SGOS#(config) content cancel outstanding-requests
SGOS#(config) content delete url http://www.bluecoat.com
#(config) content-filter
Synopsis
The SG appliance offers the option of using content filtering to control the type of retrieved content
and to filter requests made by clients. The SG appliance supports the following content filtering
methods:
❐ Local database
This method allows you to create and maintain your own content-filtering list locally, through
the SG appliance CLI or Management Console.
❐ Blue Coat Web Filter (BCWF)
BCWF is a highly effective content-filtering service that can quickly learn and adapt to the
working set of its users. Also, BCWF can use Dynamic Real Time Rating (DRTR) to analyze
requested Web pages in real time, blocking new, unrated content on the fly, while providing
the database with instant updates that impact all users without service interruption.
• InterSafe™
• Optenet
• Proventia™
• SmartFilter™
• SurfControl™
• WebWasher®
You can also combine this type of content filtering with the SG appliance policies, which use
the Blue Coat Policy Language.
❐ Denying access to URLs through policy
This method allows you to block by URL, including filtering by scheme, domain, or
individual host or IP address. For this method, you define SG appliance policies, which use
the Blue Coat Policy Language.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter)
Subcommands
#(config content-filter) bluecoat
Enters configuration mode for Blue Coat Web Filter. See #(config bluecoat) on page 140.
#(config content-filter) categories
Shows available categories.
#(config content-filter) exit
Exits configure content filter mode and returns to configure mode.
#(config content-filter) i-filter
Enters configuration mode for i-FILTER. See #(config i-filter) on page 142.
#(config content-filter) intersafe
Enters configuration mode for InterSafe. See #(config intersafe) on page 144.
#(config content-filter) iwf
Enters configuration mode for IWF. See #(config iwf) on page 146.
#(config content-filter) local—changes the prompt (see #(config local) on page 148)
Enters configuration mode for Local database.
#(config content-filter) no review-message
Specifies that vendor categorization review be turned off.
#(config content-filter) optenet
Enters configuration mode for Optenet. See #(config optenet) on page 150.
#(config content-filter) proventia
Enters configuration mode for Proventia. See #(config proventia) on page 152.
#(config content-filter) provider bluecoat {disable | enable | lookup-mode
{always | uncategorized}}
Enables or disables Blue Coat Web Filter database. The lookup-mode option specifies whether every
URL should be categorized by the downloaded filter.
#(config content-filter) provider local {disable | enable | lookup-mode {always |
uncategorized}}
Enables or disables a local user database. The lookup-mode option specifies whether every URL should
be categorized by the downloaded filter.
#(config content-filter) provider iwf {disable | enable | lookup-mode {always |
uncategorized}}
Enables or disables IWF filtering. The lookup-mode option specifies whether every URL should be
categorized by the downloaded filter.
#(config content-filter) provider 3rd-party i-filter
Selects i-FILTER content filtering.
#(config content-filter) provider 3rd-party intersafe
Selects InterSafe content filtering.
#(config content-filter) provider 3rd-party none
Specifies that a third-party vendor not be used for content filtering.
#(config content-filter) provider 3rd-party optenet
Selects Optenet content filtering.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) provider 3rd-party proventia
loading database....
ok
SGOS#(config content-filter) exit
SGOS#(config)
#(config bluecoat)
Synopsis
Use this command to configure Blue Coat Web Filter content filtering.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) bluecoat
This changes the prompt to:
#(config bluecoat)
Subcommands
Example
SGOS#(config) content-filter
SGOS#(config content-filter) bluecoat
SGOS#(config bluecoat) service mode background
ok
SGOS#(config bluecoat) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config i-filter)
Synopsis
Use this command to configure i-FILTER content filtering
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) i-filter
This changes the prompt to:
#(config i-filter)
Subcommands
#(config i-filter) download all-day
Checks for database updates all day.
#(config i-filter) download auto
Enables automatic database downloads.
#(config i-filter) download between-hours start stop
Sets the interval for automatic database update checks.
#(config i-filter) download encrypted-password encrypted_password
Specifies the encrypted password for the database download server.
#(config i-filter) download get-now
Initiates an immediate database download.
#(config i-filter) download password password
Specifies the password for the database download server.
#(config i-filter) download url {default | url}
Specifies using either the default URL or a specific URL for the database download server.
#(config i-filter) download username username
Specifies the username for the database download server.
#(config i-filter) exit
Exits configure i-filter mode and returns to configure content-filter mode.
#(config i-filter) no download auto
Disables automatic download.
#(config i-filter) no download encrypted-password
Clears the encrypted password for the database download server.
#(config i-filter) no download password
Clears the password for the database download server.
#(config i-filter) no download url
Clears the URL for the database download server.
#(config i-filter) no download username
Clears the username for the database download server.
#(config i-filter) view
Shows the current InterSafe settings.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) i-filter
SGOS#(config i-filter) no download day-of-week mon
ok
SGOS#(config i-filter) no download day-of-week wed
ok
SGOS#(config i-filter) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config intersafe)
Synopsis
Use this command to configure InterSafe content filtering.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) intersafe
This changes the prompt to:
#(config intersafe)
Subcommands
#(config intersafe) download all-day
Checks for database updates all day.
#(config intersafe) download auto
Enables automatic database downloads.
#(config intersafe) download between-hours start stop
Sets the interval for automatic database update checks.
#(config intersafe) download encrypted-password encrypted_password
Specifies the encrypted password for the database download server.
#(config intersafe) download get-now
Initiates an immediate database download.
#(config intersafe) download password password
Specifies the password for the database download server.
#(config intersafe) download url {default | url}
Specifies using either the default URL or a specific URL for the database download server.
#(config intersafe) download username username
Specifies the username for the database download server.
#(config intersafe) exit
Exits configure Intersafe mode and returns to configure content-filter mode.
#(config intersafe) no download auto
Disables automatic download.
#(config intersafe) no download encrypted-password
Clears the encrypted password for the database download server.
#(config intersafe) no download password
Clears the password for the database download server.
#(config intersafe) no download url
Clears the URL for the database download server.
#(config intersafe) no download username
Clears the username for the database download server.
#(config intersafe) view
Shows the current InterSafe settings.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) intersafe
SGOS#(config intersafe) no download day-of-week mon
ok
SGOS#(config intersafe) no download day-of-week wed
ok
SGOS#(config intersafe) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config iwf)
Synopsis
Use this command to configure Internet Watch Foundation content filtering.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) iwf
This changes the prompt to:
#(config iwf)
Subcommands
#(config iwf) download all-day
Checks for database updates all day.
#(config iwf) download auto
Enables automatic database downloads.
#(config iwf) download between-hours start stop
Sets the interval for automatic database update checks.
#(config iwf) download encrypted-password encrypted_password
Specifies the encrypted password for the database download server.
#(config iwf) download get-now
Initiates an immediate database download.
#(config iwf) download password password
(Optional) Specifies the password for the database download server.
#(config iwf) download url {default | url}
Specifies using either the default URL or a specific URL for the database download server.
#(config iwf) download username username
Specifies the username for the database download server.
#(config iwf) exit
Exits configure Intersafe mode and returns to #(configure content-filter) mode.
#(config iwf) no download auto
Disables automatic download.
#(config iwf) no download encrypted-password
Clears the encrypted password for the database download server.
#(config iwf) no download password
Clears the password for the database download server.
#(config iwf) no download url
Clears the URL for the database download server.
#(config iwf) no download username
Clears the username for the database download server.
#(config iwf) view
Shows the current InterSafe settings.
Example
SGOS#(config content-filter) local
SGOS#(config iwf) download day-of-week all
ok
SGOS#(config iwf) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config local)
Synopsis
Use this command to configure local content filtering.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) local
This changes the prompt to:
#(config local)
Subcommands
#(config local) clear
Clears the local database from the system.
#(config local) download all-day
Checks for database updates all day.
#(config local) download auto
Enables automatic database downloads.
#(config local) download between-hours start stop
Sets the interval for automatic database update checks.
#(config local) download encrypted-password encrypted_password
Specifies the encrypted password for the database download server.
#(config local) download get-now
Initiates an immediate database download.
#(config local) download password password
Specifies the password for the database download server.
#(config local) download url {default | url}
Specifies using either the default URL or a specific URL for the database download server.
#(config local) download username username
Specifies the username for the database download server.
#(config local) exit
Exits configure local database mode and returns to configure content-filter mode.
#(config local) no download auto
Disables automatic download.
#(config local) no download encrypted-password
Clears the encrypted password for the database download server.
#(config local) no download password
Clears the password for the database download server.
#(config local) no download url
Clears the URL for the database download server.
#(config local) no download username
Clears the username for the database download server.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) local
SGOS#(config local) download day-of-week all
ok
SGOS#(config local) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config optenet)
Synopsis
Use this command to configure Optenet content filtering.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) optenet
This changes the prompt to:
#(config optenet)
Subcommands
#(config optenet) download all-day
Checks for database updates all day.
#(config optenet) download auto
Enables automatic database downloads.
#(config optenet) download between-hours start stop
Sets the interval for automatic database update checks.
#(config optenet) download encrypted-password encrypted_password
Specifies the encrypted password for the database download server.
#(config optenet) download password password
Specifies the password for the database download server.
#(config optenet) download url {default | url}
Specifies using either the default URL or a specific URL for the database download server.
#(config optenet) download username username
Specifies the username for the database download server.
#(config optenet) exit
Exits configure optenet mode and returns to configure content-filter mode.
#(config optenet) no download auto
Disables automatic download.
#(config optenet) no download encrypted-password
Clears the encrypted password for the database download server.
#(config optenet) no download password
Clears the password for the database download server.
#(config optenet) no download url
Clears the URL for the database download server.
#(config optenet) no download username
Clears the username for the database download server.
#(config optenet) view
Shows the current optenet Web Filter settings.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) optenet
SGOS#(config optenet) download time-of-day 20
ok
SGOS#(config optenet) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config proventia)
Synopsis
Use this command to configure Proventia Web Filter content filtering.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) proventia
This changes the prompt to:
#(config proventia)
Subcommands
#(config proventia) download all-day
Checks for database updates all day.
#(config proventia) download auto
Enables automatic database downloads.
#(config proventia) download between-hours start stop
Sets the interval for automatic database update checks.
#(config proventia) download encrypted-password encrypted_password
Specifies the encrypted password for the database download server.
#(config proventia) download get-now
Initiates an immediate database download.
#(config proventia) download password password
Specifies the password for the database download server.
#(config proventia) download url {default | url}
Specifies using either the default URL or a specific URL for the database download server.
#(config proventia) download username username
Specifies the username for the database download server.
#(config proventia) exit
Exits configure proventia mode and returns to configure content-filter mode.
#(config proventia) no download auto
Disables automatic download.
#(config proventia) no download encrypted-password
Clears the encrypted password for the database download server.
#(config proventia) no download password
Clears the password for the database download server.
#(config proventia) no download url
Clears the URL for the database download server.
#(config proventia) no download username
Clears the username for the database download server.
#(config proventia) view
Shows the current proventia Web Filter settings.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) proventia
SGOS#(config proventia) download time-of-day 20
ok
SGOS#(config proventia) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config smartfilter)
Synopsis
Use this command to configure SmartFilter filters that control the type of content retrieved by the SG
appliance and filter requests made by clients.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) smartfilter
This changes the prompt to:
#(config smartfilter)
Subcommands
#(config smartfilter) allow-rdns
Allow reverse DNS for lookups.
#(config smartfilter) download all-day
Checks for database updates all day.
#(config smartfilter) download auto
Enables automatic database downloads.
#(config smartfilter) download between-hours start stop
Sets the interval for automatic database update checks.
#(config smartfilter) download get-now
Initiates immediate database download. If a full download is unnecessary, an incremental download is
initiated.
#(config smartfilter) download license license_key
The customer serial number assigned you by SmartFilter.
#(config smartfilter) download server IP_address_or_hostname
Enter the IP address or hostname of the server you should use for downloads if requested.
#(config smartfilter) exit
Exits configure smartfilter mode and returns to configure content-filter mode.
#(config smartfilter) no allow-rdns
Disallows reverse DNS for lookups.
#(config smartfilter) no download {auto | encrypted-password | password | url |
username}
Negates download commands.
#(config smartfilter) no use-search-keywords
Disables the ability to categorize search engines based on keywords in the URL query.
#(config smartfilter) use-search-keywords
Allows you to categorize search engines based on keywords in the URL query.
#(config smartfilter) view
Shows the current SmartFilter settings.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) smartfilter
SGOS#(config smartfilter) allow-rdns
ok
SGOS#(config smartfilter) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config surfcontrol)
Synopsis
Use this command to configure SurfControl filters that control the type of content retrieved by the SG
appliance and filter requests made by clients.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) surfcontrol
This changes the prompt to:
#(config surfcontrol)
Subcommands
#(config surfcontrol) download all-day
Checks for database updates all day.
#(config surfcontrol) download auto
Enables automatic database downloads.
#(config surfcontrol) download between-hours start stop
Sets the interval for automatic database update checks.
#(config surfcontrol) encrypted-password encrypted-password
Sets the download encrypted password. The username/password is assigned by Blue Coat.
#(config surfcontrol) download get-now
Initiates immediate database download. If a full download is unnecessary, an incremental download is
initiated.
#(config surfcontrol) download license license_key
The customer serial number assigned you by SurfControl.
#(config surfcontrol) download server IP_address_or_hostname
Enter the IP address or hostname of the server you should use for downloads if requested.
#(config surfcontrol) download url {default | url}
Specifies using either the default URL or a specific URL for the database download server.
#(config surfcontrol) download username username
Sets the download username. The username/password is assigned by Blue Coat.
#(config surfcontrol) exit
Exits configure surfcontrol mode and returns to configure content-filter mode
#(config surfcontrol) no download {auto | encrypted-password| username | password
| url}
Negates download commands.
#(config surfcontrol) view
Shows the current SurfControl settings.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) surfcontrol
SGOS#(config surfcontrol) no download url
ok
SGOS#(config surfcontrol) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config websense)
Synopsis
Use this command to configure Websense filters that control the type of content retrieved by the SG
appliance and filter requests made by clients.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) websense
This changes the prompt to:
#(config websense)
Subcommands
#(config websense) always-apply-regexes
Forces an additional regular expression lookup for each URL to be categorized. Normally, regular expression
lookups are only performed when no category is found in the Websense database. This option causes them to
be performed always, even for categorized URLs. This can reduce lookup performance, but can allow certain
sites (such as translation, search engine, and link-cache sites) to be categorized more accurately.
#(config websense) download all-day
Checks for database updates all day.
#(config websense) download auto
Enables automatic database downloads.
#(config websense) download between-hours start stop
Sets the interval for automatic database update checks.
#(config websense) download email-contact email_address
Specifies an e-mail address that is sent to Websense when downloading the database.
#(config websense) download get-now
Initiates immediate database download. If a full download is unnecessary, an incremental download is
initiated.
#(config websense) download license license_key
Specifies the license key for the database download server.
#(config websense) download server {ip_address | hostname}
Specifies the server location of the database.
#(config websense) exit
Exits configure websense mode and returns to configure content-filter mode.
#(config websense) integration-service disable
Disables the integration service.
#(config websense) integration-service enable
Enables the integration service.
#(config websense) integration-service host (hostname or IP_address)
Set the integration service hostname or IP address. The IP address must match the IP address of the
Websense Log Server.
#(config websense) integration-service port {integer between 0 and 65535}
Configure the integration service port. Accepted values are between 0 and 65535.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) websense
SGOS#(config websense) no always-apply-regexes
ok
SGOS#(config websense) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config webwasher)
Synopsis
Use this command to configure Webwasher URL Filter content filtering.
Syntax
#(config) content-filter
This changes the prompt to:
#(config content-filter) webwasher
This changes the prompt to:
#(config webwasher)
Subcommands
#(config webwasher) download all-day
Checks for database updates all day.
#(config webwasher) download auto
Enables automatic database downloads.
#(config webwasher) download between-hours start stop
Sets the interval for automatic database update checks.
#(config webwasher) download encrypted-password encrypted_password
Specifies the encrypted password for the database download server.
#(config webwasher) download get-now
Initiates an immediate database download. If a full download is unnecessary, an incremental download
is initiated.
#(config webwasher) download password password
Specifies the password for the database download server.
#(config webwasher) download url {default | url}
Specifies using either the default URL or a specific URL for the database download server.
#(config webwasher) download username username
Specifies the username for the database download server.
#(config webwasher) exit
Exits configure webwasher mode and returns to configure content-filter mode.
#(config webwasher) no download auto
Disables automatic download.
#(config webwasher) no download encrypted-password
Clears the encrypted password for the database download server.
#(config webwasher) no download password
Clears the password for the database download server.
#(config webwasher) no download url
Clears the URL for the database download server.
#(config webwasher) no download username
Clears the username for the database download server.
#(config webwasher) view
Shows the current webwasher Web Filter settings.
Example
SGOS#(config) content-filter
SGOS#(config content-filter) webwasher
SGOS#(config webwasher) download time-of-day 20
ok
SGOS#(config webwasher) exit
SGOS#(config content-filter) exit
SGOS#(config)
#(config) connection-forwarding
Synopsis
This command enables you to configure the TCP Connection Forwarding aspect of ADN transparent
tunnel load balancing and asymmetric routing.
Syntax
#(config) connection-forwarding
This changes the prompt to:
#(config connection-forwarding)
Subcommands
SGOS# (config connection forwarding) add ip_address
Add this SG appliance to a connection forwarding peer group.
SGOS# (config connection forwarding) port number
Specify the port used by all peers in the peer group to communicate connection information (each peer in
the group must use the same port number). The default is 3030.
SGOS# (config connection forwarding) [enable | disable]
Enables or disables connection forwarding on this SG appliance.
SGOS# (config connection forwarding) clear
Clear the list of forwarding peers from this SG appliance.
SGOS# (config connection forwarding) exit
Exits (config connection forwarding) mode and returns to #(config) mode.
SGOS# (config connection forwarding) view
View the TCP connection forwarding information.
Example
SGOS#(config) connection-forwarding
SGOS#(connection-forwarding) add 10.9.59.100
ok
SGOS#(config connection-forwarding) port 3030
ok
SGOS#(config connection-forwarding) enable
ok
#(config) diagnostics
Synopsis
This command enables you to configure the remote diagnostic feature Heartbeat.
Syntax
#(config) diagnostics
This changes the prompt to:
#(config diagnostics)
Subcommands
#(config diagnostics) cpu-monitor {disable | enable}
Enables or disables the CPU monitor (the CPU monitor is disabled by default).
#(config diagnostics) cpu-monitor interval seconds
Sets the periodic interval of the CPU monitor from 1 to 59 seconds (the default setting is 5 seconds).
#(config diagnostics) exit
Exits #(config diagnostics) mode and returns to #(config) mode.
#(config diagnostics) heartbeat {disable | enable}
Enables or disables the SG appliance Heartbeat features.
#(config diagnostics) monitor {disable | enable}
Enables or disables the Blue Coat monitoring feature.
#(config diagnostics) send-heartbeat
Triggers a heartbeat report.
#(config diagnostics) service-info
Changes the prompt (see #(config service-info) on page 165)
#(config diagnostics) snapshot (create | delete} snapshot_name
Creates or deletes a snapshot job.
#(config diagnostics) edit snapshot_name
Changes the prompt to #(config snapshot snapshot_name) on page 167)
#(config diagnostics) view configuration
Displays diagnostics settings for Heartbeats, CPU monitor, automatic service-info, and snapshots.
#(config diagnostics) view cpu-monitor
Displays the CPU Monitor results.
#(config diagnostics) view service-info
Displays service-info settings and progress.
#(config diagnostics) view snapshot snapshot_name
Displays the snapshot settings (target, status, interval, to keep, to take, and next snapshot) for the
snapshot name specified.
Example
SGOS#(config) diagnostics
SGOS#(config diagnostics) heartbeat enable
ok
SGOS#(config diagnostics) exit
SGOS#(config)
#(config service-info)
Synopsis
This command allows you to send service information to Blue Coat.
Syntax
#(config) diagnostics
This changes the prompt to:
#(config diagnostics) service-info
This changes the prompt to:
#(config service-info)
Subcommands
#(diagnostics service-info) auto {disable | enable}
Disables or enables the automatic service information feature.
#(diagnostics service-info) auto no sr-number
Clears the service-request number for the automatic service information feature.
#(diagnostics service-info) auto sr-number sr_number
Sets the service-request number for the automatic service information feature.
#(diagnostics service-info) bandwidth-class bw_class_name
Sets a bandwidth class used to manage the bandwidth of service-information transfers.
In order to do bandwidth-manage service-information transfers, bandwidth management
must be enabled. You must also create a bandwidth class for service-information transfers (in
bandwidth-management mode) before you can select it here.
#(diagnostics service-info) cancel all
Cancel all service information being sent to Blue Coat.
#(diagnostics service-info) cancel one_or_more_from_view_status
Cancel certain service information being sent to Blue Coat.
#(diagnostics service-info) exit
Exits #(config diagnostics service-info) mode and returns to #(config diagnostics)
mode.
#(diagnostics service-info) no bandwidth-class
Disables bandwidth-management for service-information transfers
#(diagnostics service-info) send sr_number
one_or_more_commands_from_view_available
Sends a specific service request number along with a specific command or commands (chosen from the
list provided by the view available command) to Blue Coat.
#(diagnostics service-info) view available
Shows list of service information than can be sent to Blue Coat.
#(diagnostics service-info) view status
Shows transfer status of service information to Blue Coat.
Example
SGOS#(config) diagnostics
SGOS#(config diagnostics) service-info
SGOS#(diagnostics service-info) view available
Service information that can be sent to Blue Coat
Synopsis
This command allows you to edit a snapshot job.
Syntax
#(config) diagnostics
This changes the prompt to:
#(config diagnostics) snapshot edit snapshot_name
This changes the prompt to:
#(config snapshot snapshot_name)
Subcommands
#(config snapshot snapshot_name) clear-reports
Clears all stored snapshots reports.
#(config snapshot snapshot_name) {disable | enable}
Disables or enables this snapshot job.
#(config snapshot snapshot_name) exit
Exits #(config diagnostics snapshot_name) mode and returns to #(config diagnostics
service-info) mode.
#(config snapshot snapshot_name) interval minutes
Specifies the interval between snapshots reports in minutes.
#(config snapshot snapshot_name) keep number_to_keep (from 1 - 100)
Specifies the number of snapshot reports to keep.
#(config snapshot snapshot_name) take {infinite | number_to_take}
Specifies the number of snapshot reports to take.
#(config snapshot snapshot_name) target object_to_fetch
Specifies the object to snapshot.
#(config snapshot snapshot_name) view
Displays snapshot status and configuration.
Example
SGOS#(config) diagnostics
SGOS#(config diagnostics) snapshot testshot
SGOS#(diagnostics snapshot testshot) enable
ok
SGOS#(diagnostics service-info) interval 1440
ok
SGOS#(diagnostics snapshot testshot) exit
SGOS#(config diagnostics) exit
SGOS#(config)
#(config) dns
Synopsis
The dns command enables you to modify the DNS settings for the SG appliance. Note that the
alternate DNS servers are only checked if the servers in the standard DNS list return: “Name not
found.”
Syntax
#(config) dns [subcommands]
Subcommands
#(config) dns alternate ip_address
Adds the new alternate domain name server indicated by ip_address to the alternate DNS server list.
#(config) dns clear alternate
Sets all entries in the alternate DNS server list to null.
#(config) dns clear imputing
Sets all entries in the name imputing list to null.
#(config) dns client-affinity {disable | enable}
Enable or disable client-affinity.
When enabled, requests from the same client resolve the hostname in the same order.
www.google.com resolves to 66.102.7.99, 66.102.7.147, and 66.102.7.104. If client-affinity is enabled and
the SG appliance receives a request (http, streaming or other proxy request) for www.google.com, it uses
the client’s IP address to determine the order of the resolved addresses. If client-affinity is disabled, the
order of the resolved addresses changed each time the SG appliance receives a request.
#(config) dns clear server
Sets all entries in the primary DNS server list to null.
#(config) dns imputing name
Identifies the file indicated by name as the name imputing list.
#(config) dns negative-cache-ttl-override seconds
Set the DNS negative cache time-to-live value for seconds.
A DNS request to an unknown domain name (klauwjdasd.bluecaot.com) is cached by the SG appliance.
This type of caching is called a negative cache because it does not resolve to an actual IP address. The
TTL value for a negative cache entry can be overwritten by this command.
#(config) dns no alternate ip_address
Removes the alternate DNS server identified by ip_address from the alternate DNS server list.
#(config) dns no imputing imputed_name
Removes the imputed name identified by imputed_name from the name imputing list.
#(config) dns no negative-cache-ttl-override
Do not override the negative cache time-to-live value.
#(config) dns no server ip_address
Removes the primary DNS server identified by ip_address from the primary DNS server list.
#(config) dns server ip_address
Adds the new primary domain name server indicated by ip_address to the primary DNS server list.
Example
SGOS#(config) dns clear server
ok
SGOS#(config) dns server 10.253.220.249
ok
SGOS#(config) dns clear alternate
ok
SGOS#(config) dns alternate 216.52.23.101
ok
#(config) event-log
Synopsis
You can configure the SG appliance to log system events as they occur. Event logging allows you to
specify the types of system events logged, the size of the event log, and to configure Syslog
monitoring. The SG appliance can also notify you by e-mail if an event is logged.
Syntax
#(config) event-log
This changes the prompt to:
#(config event-log)
Subcommands
#(config event-log) exit
Exits #(config event-log) mode and returns to #(config) mode.
#(config event-log) level configuration
Writes severe and configuration change error messages to the event log.
#(config event-log) level informational
Writes severe, configuration change, policy event, and information error messages to the event log.
#(config event-log) level policy
Writes severe, configuration change, and policy event error messages to the event log.
#(config event-log) level severe
Writes only severe error messages to the event log.
#(config event-log) level verbose
Writes all error messages to the event log.
#(config event-log) log-size megabytes
Specifies the maximum size of the event log in megabytes.
#(config event-log) mail add email_address
Specifies an e-mail recipient for the event log output.
#(config event-log) mail clear
Removes all e-mail recipients from the event log e-mail output distribution list.
#(config event-log) mail no smtp-gateway
Clears the SMTP gateway used for notifications.
#(config event-log) mail remove email_address
Removes the e-mail recipient indicated by email_address from the event log e-mail output
distribution list.
#(config event-log) mail smtp-gateway {domain_name | ip_address}
Specifies the SMTP gateway to use for event log e-mail output notifications.
#(config event-log) syslog {disable | enable}
Disables the collection of system log messages.
#(config event-log) syslog facility {auth | daemon | kernel | local0 | local1 |
local2 | local3 | local4 | local5 | local6 | local7 | lpr | mail | news |
syslog | user | uucp}
Specifies the types of system log messages to be collected in the system log.
#(config event-log) syslog loghost {domain_name | ip_address}
Specifies the host domain used for system log notifications.
Example
SGOS#(config) event-log
SGOS#(config event-log) syslog enable
ok
#(config) exceptions
Synopsis
These commands allow you to configure built-in and user-defined exception response objects.
Syntax
#(config) exceptions
This changes the prompt to:
#(config exceptions)
Subcommands
#(config exceptions) create exception_id
Creates the given exception.
#(config exceptions) company-name name
Sets the name used for the $(exception.company_name) substitution.
#(config exceptions) delete exception_id
Deletes the exception specified by exception_id.
#(config exceptions) edit exception_id or user_defined_exception_id
Changes the prompt to #(config exceptions [user-defined.]exception_id) on page
173.
#(config exceptions) exit
Exits #(config exceptions) mode and returns to #(config) mode.
#(config exceptions) inline {contact | details | format | help | http {contact |
details | format | help | summary} | summary} eof_marker
Configures defaults for all exception objects.
#(config exceptions) load exceptions
Downloads new exceptions.
#(config exceptions) no path
Clears the network path to download exceptions.
#(config exceptions) path url
Specifies the network path to download exceptions.
#(config exceptions) user-defined inline {contact | details | format | help |
http {contact | details | format | help | summary} | summary} eof_marker
Configures the top-level values for user-defined exceptions.
Example
SGOS#(config) exceptions
SGOS#(config exceptions) default contact
ok
SGOS#(config exceptions) exit
SGOS#(config)
Synopsis
These commands allow you to edit an exception or a user-defined exception.
Syntax
#(config) exceptions
This changes the prompt to:
#(config exceptions) user_defined_exception_id
This changes the prompt to:
#(config exceptions user_defined_exception_id)
Subcommands
#(config exceptions [user-defined.]exception_id) exit
Exits #(config exceptions [user-defined] exception_id) mode and returns to #(config
exceptions) mode.
#(config exceptions [user-defined.]exception_id) http-code
numeric_http_response_code
Configures this exception's HTTP response code.
#(config exceptions [user-defined.]exception_id) inline {contact | details |
format | help | http {contact | details | format | help | summary} | summary}
eof_marker
Configures this exception's substitution values.
Example
SGOS#(config) exceptions
SGOS#(config exceptions) edit testname
SGOS#(config exceptions user-defined testname) http-code 000
ok
SGOS#(config exceptions user-defined testname) exit
SGOS#(config exceptions) exit
SGOS#(config)
#(config) exit
Synopsis
Exits from Configuration mode to Privileged mode, from Privileged mode to Standard mode. From
Standard mode, the exit command closes the CLI session.
Syntax
#(config) exit
The exit command has no parameters or subcommands.
#(config) external-services
Synopsis
These commands allow you to configure your external services.
Use the edit ICAP commands to configure the ICAP service used to integrate the SG appliance with a
virus scanning server. The configuration is specific to the virus scanning server and includes the server
IP address, as well as the supported number of connections. If you are using the SG appliance with
multiple virus scanning servers or multiple scanning services on the same server, add an ICAP service
for each server or scanning service.
Note: When you define virus scanning policies, use the same service name. Make sure you type the
ICAP service name accurately, whether you are configuring the service on the SG appliance or
defining policies, since the name retrieves the other configuration settings for that service.
Syntax
#(config) external-services
This changes the prompt to:
#(config external-services)
Subcommands
#(config external-services) create icap icap_service_name
Creates an ICAP service.
#(config external-services) create service-group service_group_name
Creates a service group.
#(config external-services) create websense websense_service_name
Creates a Websense service.
#(config external-services) delete name
Deletes an external service.
#(config external-services) edit
Changes the prompt to one of three external service edit commands:
#(config icap icap_service_name) on page 177
#(config service-group service_group_name) on page 179
#(config websense websense_service_name) on page 181
#(config external-services) exit
Exits #(config external-services) mode and returns to #(config) mode.
#(config external-services) inline http {icap-patience-details |
icap-patience-header | icap-patience-help | icap-patience-summary}
Customizes ICAP patience page details for HTTP connections.
#(config external-services) icap feedback interactive patience-page {seconds}
For traffic associated with a Web browser, display a patience page after the specified duration.
Example
SGOS#(config) external-services
SGOS#(config external-services) create websense testwebsense
ok
SGOS#(config external-services) exit
SGOS#(config)
Synopsis
These commands allow you to edit ICAP parameters.
Syntax
#(config) external-services
This changes the prompt to:
#(config external-services) create icap icap_service_name
#(config external-services) edit icap_service_name
This changes the prompt to:
#(config icap icap_service_name)
Subcommands
#(config icap icap_service_name) exit
Exits #(config ICAP name) mode and returns to #(config external-services) mode.
#(config icap icap_service_name) max-conn max_num_connections
Sets the maximum number of connections for the ICAP service.
#(config icap icap_service_name) methods {REQMOD | RESPMOD}
Sets the method supported by the ICAP service. REQMOD is request modification and RESPMOD is
response modification.
#(config icap icap_service_name) no send {client-address | server-address}
Specifies what should not be sent to the ICAP server.
#(config icap icap_service_name) no notify virus-detected
Specifies no notification to the administrator when a virus is detected.
#(config icap icap_service_name) no patience-page
Specifies that patience pages do not get served.
#(config icap icap_service_name) no preview
Specifies that previews do not get sent.
#(config icap icap_service_name) notify virus-detected
Specifies notification when viruses are found.
#(config icap icap_service_name) patience-page seconds
Sets the number of seconds (5 to 65535) to wait before serving a patience page.
#(config icap icap_service_name) preview-size bytes
Sets the preview size for the ICAP service.
#(config icap icap_service_name) send client-address
Specifies that the client address be sent to the ICAP service.
#(config icap icap_service_name) send server-address
Specifies that the server address be sent to the ICAP service.
#(config icap icap_service_name) sense-settings
Senses the service’s setting by contacting the server.
#(config icap icap_service_name) timeout seconds
Sets the connection timeout for the ICAP services.
#(config icap icap_service_name) url url
Sets the URL for the ICAP services.
Example
SGOS#(config) external-services
SGOS#(config external-services) edit testicap
SGOS#(config icap testicap) send client-address
ok
SGOS#(config icap testicap) exit
SGOS#(config external-services) exit
SGOS#(config)
Synopsis
These commands allow you to edit service group parameters.
Syntax
#(config) external-services
This changes the prompt to:
#(config external-services) create service-group service_group_name
#(config external-services) edit service_group_name
This changes the prompt to:
#(config service-group service_group_name)
Subcommands
#(config service-group service_group_name) add entry_name
Adds an entry to this service group.
#(config service-group service_group_name) edit entry_name
Changes the prompt to #(config service-group service_group_name entry_name).
#(config service-group service_group_name entry_name) exit
Exits #(config service-group name/entry name) mode and returns to #(config
service-group name) mode.
#(config service-group service_group_name entry_name) view
Shows this entry’s configuration.
#(config service-group service_group_name entry_name) weight 0 to 255
Modifies this entry’s weight.
#(config service-group service_group_name) exit
Exits #(config service-group_name) mode and returns to #(config external-services)
mode.
#(config service-group service_group_name) view
Displays this service group’s configuration.
Examples
SGOS#(config) external-services
SGOS#(config external-services) edit testgroup
SGOS#(config service-group testgroup) add testentry
ok
SGOS#(config service-group testgroup) exit
SGOS#(config external-services) exit
SGOS#(config)
SGOS#(config) external-services
SGOS#(config external-services) edit testgroup
SGOS#(config service-group testgroup) edit testentry
SGOS#(config service-group testgroup testentry) weight 223
ok
SGOS#(config service-group testgroup testentry) exit
SGOS#(config service-group testgroup) exit
SGOS#(config external-services) exit
SGOS#(config)
Synopsis
These commands allow you to edit Websense parameters.
Syntax
#(config) external-services
This changes the prompt to:
#(config external-services) create websense websense_service_name
#(config external-services) edit websense_service_name
This changes the prompt to:
#(config websense websense_service_name)
Subcommands
#(config websense websense_service_name) apply-by-default
Applies Websense by default.
#(config websense websense_service_name) exit
Exits #(config websense websense_service_name) mode and returns to #(config
external-services) mode.
#(config websense websense_service_name) fail-open
Fail open if service is applied by default.
#(config websense websense_service_name) host hostname
Remote Websense hostname or IP address.
#(config websense websense_service_name) max-conn max_num_connections
Specifies the maximum number of concurrent connections
#(config websense websense_service_name) no apply-by-default
Does not apply service by default.
#(config websense websense_service_name) no fail-open
Fail closed if service is applied by default.
#(config websense websense_service_name) no send {client-address | client-info}
Negates send options.
#(config websense websense_service_name) no serve-exception-page
Serves Websense message when content is blocked.
#(config websense websense_service_name) port port
Port number of remote Websense server.
#(config websense websense_service_name) send client-address
Sends the client address to the Websense server.
#(config websense websense_service_name) send client-info
Sends the client information to the Websense server.
#(config websense websense_service_name) sense-categories
Sense categories configured on the Websense server.
#(config websense websense_service_name) serve-exception-page
Serves built-in exception page when content is blocked.
#(config websense websense_service_name) test-url url
Tests a url against the Websense server.
Example
SGOS#(config) external-services
SGOS#(config external-services) edit testwebsense
SGOS#(config websense testwebsense) send client-address
ok
SGOS#(config websense testwebsense) exit
SGOS#(config external-services) exit
SGOS#(config)
#(config) failover
Synopsis
These commands allow you to configure redundancy into your network.
Syntax
#(config) failover
This changes the prompt to:
#(config failover)
Subcommands
#(config failover) create group_address
Creates a failover group.
#(config failover) delete group_address
Deletes a failover group.
#(config failover) edit group_address
Changes the prompt to #(config failover group_address).
#(config failover group_address) {disable | enable}
Disables or enables failover group indicated by group_address.
#(config failover group_address) encrypted-secret encrypted_secret
(Optional but recommended) Refers to an encrypted password shared only with the group.
#(config failover group_address) exit
Exits #(config failover group_address) mode and returns to #(config failover)
mode.
#(config failover group_address) interval interval_in_seconds
(Optional) Refers to the time between advertisements from the master to the multicast address. The
default is 40 seconds.
#(config failover group_address) master
Defines the current system as the master and all other systems as slaves.
#(config failover group_address) multicast-address multicast_address
Refers to a multicast address where the master sends the keepalives (advertisements) to the slave
systems.
#(config failover group_address) no interval
Resets the interval to the default value (40 seconds).
#(config failover group_address) no multicast-address
Removes the multicast address from the failover group.
#(config failover group_address) no master
Removes as configured master.
#(config failover group_address) no priority
Resets the priority to the default value (100).
#(config failover group_address) no secret
Clears the secret from the failover group.
#(config failover group_address) priority relative_priority
(Optional) Refers to the rank of slave systems. The range is from 1 to 253. (The master system, the
one whose IP address matches the group address, gets 254.)
Examples
SGOS#(config) failover
SGOS#(config failover) create 10.9.17.135
ok
SGOS#(config failover) exit
SGOS#(config)
SGOS#(config) failover
SGOS#(config failover) edit 10.9.17.135
SGOS#(config failover 10.9.17.135) master
ok
SGOS#(config failover 10.9.17.135) exit
SGOS#(config failover) exit
#(config) forwarding
Synopsis
Configures forwarding of content requests to defined hosts and groups through policy.
Syntax
#(config) forwarding
This changes the prompt to:
#(config forwarding)
Subcommands
#(config forwarding) create host host_alias host_name [http[=port] [https[=port]]
[ftp[=port]] [mms[=port]] [rtsp[=port]] [tcp[=port]] [telnet[=port]]
[ssl-verify-server[=yes | =no]] [group=group_name] [server | proxy]
#(config forwarding) create group group_name
Creates a forwarding host/group. The only required entries under the create option (for a host) are
host_alias, host_name, a protocol, and a port number. The port number can be defined explicitly
(i.e., http=8080), or it can take on the default port value of the protocol, if one exists (i.e., enter http,
and the default port value of 80 is entered automatically).
To create a host group, you must also include the group=group_name command. If this is
the first mention of the group, group_name, then that group is automatically created with this
host as its first member. Do not use this command when creating an independent host.
#(config forwarding) delete all
Deletes all forwarding hosts and groups.
#(config forwarding) delete group group_name
Deletes only the group identified by group_name.
#(config forwarding) delete host host_alias
Deletes only the host identified by host_alias.
#(config forwarding) download-via-forwarding {disable | enable}
Disables or enables configuration file downloading using forwarding.
#(config forwarding) edit host_or_group_alias
Changes the prompt to:
• #(config forwarding group_alias) on page 188
• #(config forwarding host_alias) on page 190
#(config forwarding) exit
Exits #(config forwarding) mode and returns to #(config) mode.
#(config forwarding) failure-mode {closed | open}
Sets the default forwarding failure mode to closed or open.
#(config forwarding) host-affinity http method {accelerator-cookie
[host_or_group_alias] | client-ip-address [host_or_group_alias] | default
[host_or_group_alias] | none [host_or_group_alias]}
Selects a host affinity method for HTTP. If a host or group alias is not specified for the
accelerator-cookie, client-ip-address, or none options, the global default is used. Use the
default option to specify default configurations for all the settings for a specified host or group.
Example
SGOS#(config) forwarding
SGOS#(config forwarding) download-via-forwarding disable
ok
SGOS#(config forwarding) failure-mode closed
ok
SGOS#(config forwarding) host-affinity method client-ip-address
ok
SGOS#(config forwarding) load-balance hash domain group_name1
ok
SGOS#(config forwarding) exit
SGOS#(config)
Synopsis
These commands allow you to edit the settings of a specific forwarding group.
Syntax
#(config) forwarding
This changes the prompt to:
#(config forwarding) create host_alias hostname protocol=port group=group_alias
#(config forwarding) edit group_alias
This changes the prompt to:
#(config forwarding group_alias)
Subcommands
#(config forwarding group_alias) add
Adds a new group.
#(config forwarding group_alias) exit
Exits #(config forwarding group_alias) mode and returns to #(config forwarding)
mode.
#(config forwarding group_alias) host-affinity http {accelerator-cookie |
client-ip-address | default | none}
Changes the host affinity method (non-SSL) for this group.
#(config forwarding group_alias) host-affinity other {client-ip-address |
default | none}
Changes the other host affinity method for this group.
#(config forwarding group_alias) host-affinity ssl {accelerator-cookie |
client-ip-address | default | ssl-session-id | none}
Changes the host affinity method (SSL) for this group.
#(config forwarding group_alias) load-balance method {default | domain-hash |
least-connections | none | round-robin | url-hash}
Changes the load balancing method.
#(config forwarding group_alias) remove
Removes an existing group.
#(config forwarding group_alias) view
Shows the current settings for this forwarding group.
Example
SGOS#(config) forwarding
SGOS#(config forwarding) edit test_group
SGOS#(config forwarding test_group) load-balance hash domain
ok
SGOS#(config forwarding test_group) exit
SGOS#(config forwarding) exit
SGOS#(config)
Synopsis
These commands allow you to edit the settings of a specific forwarding host.
Syntax
#(config) forwarding
This changes the prompt to:
#(config forwarding) create host_alias hostname protocol=port
#(config forwarding) edit host_alias
This changes the prompt to:
#(config forwarding host_alias)
Subcommands
#(config forwarding host_alias) exit
Exits #(config forwarding host_alias) mode and returns to #(config forwarding) mode.
#(config forwarding host_alias) ftp [port]
Changes the FTP port to the default port or to a port that you specify.
#(config forwarding host_alias) host host_name
Changes the host name.
#(config forwarding host_alias) host-affinity http {accelerator-cookie |
client-ip-address | default | none}
Changes the host affinity method (non-SSL) for this host.
#(config forwarding host_alias) host-affinity other {client-ip-address | default
| none}
Changes the other host affinity method for this host.
#(config forwarding host_alias) host-affinity ssl {accelerator-cookie |
client-ip-address | default | ssl-session-id | none}
Changes the host affinity method (SSL) for this host.
#(config forwarding host_alias) http [port]
Changes the HTTP port to the default port or to a port that you specify.
#(config forwarding host_alias) https [port]
Changes the HTTPS port to the default port or to a port that you specify.
#(config forwarding host_alias) load-balance method {default | least-connections
| round-robin | none}
Changes the load balancing method.
#(config forwarding host_alias) mms [port]
Changes the MMS port to the default port or to a port that you specify.
#(config forwarding host_alias) no {ftp | http | https | mms | rtsp |
ssl-verify-server | tcp | telnet}
Deletes a setting for this host.
#(config forwarding host_alias) proxy
Makes the host a proxy instead of a server; any HTTPS or TCP ports are deleted.
#(config forwarding host_alias) rtsp [port]
Changes the RTSP port to the default port or to a port that you specify.
Example
SGOS#(config) forwarding
SGOS#(config forwarding) edit test_host
SGOS#(config forwarding test_host) server
ok
SGOS#(config forwarding test_host) exit
SGOS#(config forwarding) exit
#(config) front-panel
Synopsis
Use this command to configure the front panel. For instance, the front-panel LCD behavior can be
configured using the backlight command.
Syntax
#(config) front-panel
This changes the prompt to:
#(config front-panel)
Subcommands
#(config front-panel) backlight flash
The front-panel LCD is configured to flash, which can, for instance, help you locate a particular
appliance in a room full of appliances.
#(config front-panel) backlight state {off | on | timeout}
The front-panel LCD is configured to be always turned on, always turned off, or to turn off after a
specified length of time (use the backlight timeout command to configure the length of time).
#(config front-panel) backlight timeout seconds
Configures the length of time before the front-panel LCD turns off. You must also set the backlight
state timeout command to configure timeout mode.
#(config front-panel) exit
Exits #(config front-panel) mode and returns to #(config) mode.
#(config front-panel) hashed-pin hashed_PIN
Specifies a front-panel PIN in hashed format.
#(config front-panel) no backlight flash
Stops the front-panel LCD from flashing.
#(config front-panel) pin PIN
Sets a four-digit PIN to restrict access to the front panel of the SG appliance. To clear the PIN, specify
0000 instead of a real PIN.
#(config front-panel) view
Displays the front panel settings.
Example
SGOS#(config) front-panel
SGOS#(config front-panel) backlight state timeout
ok
SGOS#(config front-panel) backlight timeout 60
ok
SGOS#(config front-panel) exit
SGOS#(config)
#(config) ftp
Synopsis
Use this command to configure FTP parameters.
Syntax
#(config) ftp login-syntax {raptor | checkpoint}
Toggles between Raptor and Checkpoint login syntax. The default is Raptor.
#(config) ftp no welcome-banner
No text is displayed to an FTP client when a connection occurs.
#(config) ftp welcome-banner banner
Customizes the text displayed to an FTP client when a connection occurs.
Example
SGOS #(config) ftp login-syntax checkpoint
ok
#(config) general
Synopsis
Use these commands to set global defaults for user behavior when license limits are exceeded and
trusting client-provided destination IP addresses.
Syntax
SGOS#(config) general {trust-destination-ip | user-overflow-action}
Subcommands
SGOS#(general) trust-destination-ip {enable | disable}
Allows the SG appliance to trust a client-provided destination IP address and not do a DNS lookup.
• Proxy Edition default: disable
• MACH5 Edition default: enable
SGOS#(general) user-overflow-action {bypass | none | queue}
Set overflow behavior when there are more licensed-user connections going through the system than is
allowed by the model license. The default is none.
Example
SGOS#(general) trust-destination-ip enable
ok
#(config) health-check
Synopsis
Use this command to configure health check settings.
Syntax
#(config) health-check
This changes the prompt to:
#(config health-check)
Subcommands
(config health-check) copy source-alias target-alias
Copy from one health check to another (creating if necessary).
(config health-check) create {composite alias_name | http alias_name url | https
alias_name url | icmp alias_name hostname| ssl alias_name hostname [port]| tcp
alias_name hostname [port]}
Create a user-defined health check of the type specified.
(config health-check) default e-mail {healthy {enable |disable} | report-all-ips
{enable | disable} | sick {enable | disable}}
Configure defaults for e-mail options.
(config health-check) default event-log {healthy {enable |disable} | report-all-ips
{enable | disable} | sick {enable | disable}}
Configure defaults for event-log options.
(config health-check) default failure-trigger {none | count}
Configure defaults for the failure-trigger options.
(config health-check) default interval {healthy seconds| sick seconds}
Configure defaults for interval options.
((config health-check) default snmp {healthy {enable |disable} | report-all-ips
{enable | disable} | sick {enable | disable}}
Configure defaults for snmp options.
(config health-check) default threshold {healthy count | response-time
milliseconds | sick count}
Configure defaults for threshold options.
(config health-check) delete alias_name
Delete the specified health check.
(config health-check) disable {healthy alias_name | sick alias_name}
Disable the specified health check and have it always report health or sick.
(config health-check) edit composite_health_check
Edit the specified composite health check.
(config health-check user.composite_health_check) add member_name
Add the specified member to the composite health check group.
(config health-check user.composite_health_check) combine {all-healthy |
any-healthy | some-healthy}
Require that all, some, or any members of the group report as healthy to have the composite health
check report as healthy.
disable}}
Send e-mail notification when the health check reports healthy or sick, whether or not those reports
are for all IP addresses.
(config health-check fwd.host_name) event-log {healthy {default | enable |
disable}| report-all-ips {healthy {default | enable | disable}| sick {default |
enable | disable}}
Log an event when the health check reports healthy or sick, whether or not those reports are for all
IP addresses.
(config health-check fwd.host_name) exit
Leaves the health check editing mode.
(config health-check fwd.host_name) failure-trigger {default | none | count}
Configure options for the failure-trigger.
(config health-check fwd.host_name) interval {healthy {default | seconds}| sick
{default | seconds}}
Configure intervals before the health check is re-run. The intervals can be different for health checks
that are reporting healthy and health checks that are reporting sick.
(config health-check fwd.host_name) perform-health-check
Starts the health check immediately and reports the result.
(config health-check fwd.host_name) proxy-authentication {basic | disable |
encrypted-password encrypted-password | password password | username
username}
(Used with HTTP or HTTPS health checks, when intermediate proxies are between you and the
target.) Enter the username and password of the intermediate proxy.
(config health-check fwd.host_name) response-code {add codes | remove codes}
To manage a list of codes that are considered successes, you can add or remove codes, separated by
semi-colons. If a success code is received by the health check, the health check considers the HTTP/
HTTPS test to be successful.
(config health-check fwd.host_name) snmp {healthy {default | enable | disable}|
report-all-ips {healthy {default | enable | disable}| sick {default | enable |
disable}}
Sends a trap when the health check reports healthy, whenever an IP address health check reports
healthy, or when a health check reports sick.
(config health-check fwd.host_name) threshold {healthy {default | count} |
response-time {default | none | milliseconds} | sick {default | count}}
Set the level when health checks will report healthy or sick.
(config health-check fwd.host_name) type (http URL | https URL | icmp hostname | ssl
hostname [port] | tcp hostname [port]}
Set the number of consecutive healthy or sick test results before the health check actually reports as
healthy or sick.
(config health-check fwd.host_name) use-defaults
Re-sets the defaults of the health check to use the global defaults instead of any explicitly set values.
(config health-check fwd.host_name) view {configuration | statistics}
Views the health check’s configuration or statistics.
(config health-check) edit health_check_name
Allows you to configure options for the health check you specified.
(config health-check user.health_check_name) authentication {basic | disable |
encrypted-password encrypted-password| password password| username username}
(Used with HTTP or HTTPS health checks.) To test Basic authentication, you can enter the username
and password of the target.
Example
SGOS#(config) health-check
SGOS#(config health-check) create composite composite1
SGOS#(config health-check) edit composite1
SGOS#(config health-check user.composite1) view statistics
Enabled Health check failed DOWN
#(config) hide-advanced
See
❐ # hide-advanced on page 52.
#(config) hostname
Synopsis
Use this command to assign a name to an SG appliance. Any descriptive name that helps identify the
system is sufficient.
Syntax
#(config) hostname name
Associates name with the current SG appliance.
Example
SGOS#(config) hostname "Blue Coat Demo"
ok
#(config) http
Synopsis
Use this command to configure HTTP settings.
Syntax
#(config) http [no] add-header client-ip
Adds the client-ip header to forwarded requests.
#(config) http [no] add-header front-end-https
Adds the front-end-https header to forwarded requests.
#(config) http [no] add-header via
Adds the via header to forwarded requests.
#(config) http [no] add-header x-forwarded-for
Adds the x-forwarded-for header to forwarded requests.
#(config) http [no] byte-ranges
Enables HTTP byte-range support.
If byte-range support is disabled, then HTTP treats all byte range requests as non-cacheable. This means
that HTTP never even checks to see if the object is in the cache, but forwards the request to the
origin-server and does not cache the result. So the range request has no affect on the cache. For instance,
if the object was in the cache before a range request, it would still be in the cache afterward—the range
request does not delete any currently cached objects. Also, the Range header is not modified when
forwarded to the origin-server.
If the requested byte range is type 3 or 4, then the request is treated as if byte-range support is disabled.
That is, the request is treated as non-cacheable and has no affect on objects in the cache.
#(config) http [no] cache authenticated-data
Caches any data that appears to be authenticated.
#(config) http [no] cache expired
Retains cached objects older than the explicit expiration.
#(config) http [no] cache personal-pages
Caches objects that appear to be personal pages.
#(config) http [no] force-ntlm
Uses NTLM for Microsoft Internet Explorer proxy.
#(config) http ftp-proxy-url root-dir
URL path is absolute in relation to the root.
#(config) http ftp-proxy-url user-dir
URL path is relative to the user’s home directory.
#(config) http [no] parse meta-tag {cache-control | expires | pragma-no-cache}
Parses HTML objects for the cache-control, expires, and pragma-no-cache meta-tags.
#(config) http [no] persistent client
Enables support for persistent client requests from the browser.
#(config) http [no] persistent server
Enables support for persistent server requests to the Web server.
#(config) http [no] persistent-timeout client num_seconds
Sets persistent connection timeout for the client to num_seconds.
#(config) http [no] persistent-timeout server num_seconds
Sets persistent connection timeout for the server to num_seconds.
#(config) icp
Synopsis
ICP is a caching communication protocol. It allows a cache to query other caches for an object, without
actually requesting the object. By using ICP, the SG appliance determines if the object is available from
a neighboring cache, and which device provides the fastest response.
After you have created the ICP or advanced forwarding configuration file, place the file on an FTP or
HTTP server so it can be downloaded to the SG appliance.
Syntax
#(config) icp no path
Negates the path previously set using the command icp path url.
#(config) icp path url
Specifies the network location of the ICP configuration file to download.
Example
SGOS#(config) icp path 10.25.36.47/files/icpconfig.txt
ok
#(config) identd
Synopsis
IDENTD implements the TCP/IP IDENT user identification protocol. IDENTD operates by looking up
specific TCP/IP connections and returning the user name of the process owning the connection.
Syntax
#(config) identd
This changes the prompt to:
#(config identd)
Subcommands
#(config identd) client server-query-port port
Specifies the port to query on the client machines. The default is 113.
#(config identd) client timeout seconds
Specifies the timeout in seconds for identd. queries. The default is 30 seconds.
#(config identd) trim-whitespace (enable | disable}
Specify whether to trim leading and trailing whitespace in the username portion of the identd query
response. By default this is disabled.
If client identd servers are adding insignificant whitespace to the username field you might need to
enable this option to trim the username as expected.
#(config identd) exit
Exits configure identd mode and returns to configure mode.
#(config identd) server enable | disable
#(config identd) view
Displays current IDENTD settings.
Example
SGOS#(config) identd
SGOS#(config identd) enable
ok
SGOS#(config identd) exit
SGOS#(config)
#(config) im
Synopsis
You can configure the IM proxy settings, assign an administrator buddy name for each client type, and
determine how exception messages are sent.
Syntax
#(config) im aol-admin-buddy buddy
Set AOL admin buddy name.
#(config) im aol-direct-proxy-host host
Set AOL direct proxy host.
#(config) im aol-http-host host
Set AOL HTTP host.
#(config) im aol-native-host host
Set AOL native host
#(config) im buddy-spoof-message message_text
Set buddy spoof message.
#(config) im exceptions {in-band | out-of-band}
in-band: Deliver IM exceptions in band.
out-of-band: Deliver IM exceptions out of band.
#(config) im explicit-proxy-vip virtual_IP_address
Set explicit proxy virtual IP address.
#(config) im msn-admin-buddy buddy
Set MSN admin buddy name.
#(config) im msn-http-host host
Set MSN HTTP host.
#(config) im msn-native-host host
Set MSN native host.
#(config) no explicit-proxy-vip
Disables explicit proxy VIP support.
#(config) im yahoo-admin-buddy buddy
Set Yahoo admin buddy name.
#(config) im yahoo-download-host host
Set Yahoo download host.
#(config) im yahoo-http-host host
Set Yahoo HTTP host.
#(config) im yahoo-http-chat-host host
Set Yahoo HTTP chat host.
#(config) im yahoo-native-host host
Set Yahoo native host.
#(config) im yahoo-upload-host host
Set Yahoo upload host.
Example
SGOS#(config) im exceptions in-band
ok
SGOS#(config) im yahoo-admin-buddy testname
ok
#(config) inline
See
❐ # inline on page 53.
#(config) installed-systems
Synopsis
Use this command to manage the list of installed SG systems.
Syntax
#(config) installed-systems
This changes the prompt to:
#(config installed-systems)
Subcommands
#(config installed-systems) default system_number
Sets the default system to the system indicated by system_number.
#(config installed-systems) delete system_number
Deletes the system indicated by system_number.
#(config installed-systems) exit
Exits configure installed-systems mode and returns to configure mode.
#(config installed-systems) lock system_number
Locks the system indicated by system_number.
#(config installed-systems) no {lock system_number | replace}
lock system_number: Unlocks the system indicated by system_number if it is currently locked.
replace: Specifies that the system currently tagged for replacement should not be replaced. The default
replacement is used (oldest unlocked system).
#(config installed-systems) replace system_number
Specifies that the system identified by system_number is to be replaced next.
#(config installed-systems) view
Shows installed SG systems.
Example
SGOS#(config) installed-systems
SGOS#(config installed-systems) default 2
ok
SGOS#(config installed-systems) lock 1
ok
SGOS#(config installed-systems) exit
SGOS#(config)
#(config) interface
Synopsis
This command enables you to configure the network interfaces (both physical and Virtual LAN).
The built-in Ethernet adapter is configured for the first time using the setup console. If you want to
modify the built-in adapter configuration, or if you have multiple adapters, you can configure each
one using the command-line interface.
Syntax
#(config) interface fast-ethernet interface_number
where interface_number sets the number of the fast Ethernet connection to interface_number.
Valid values for interface_number are 0 through 3, inclusive.
#(config) interface interface_number
This changes the prompt to #(config interface interface_number)
Syntax
#(config) interface interface_number
This changes the prompt to #(config interface interface_number)
Subcommands
#(config interface interface_number) allow-intercept {enable | disable}
Allow transparent interception on this interface.*
#(config interface interface_number) exit
Exits #(config interface number) mode and returns to #(config) mode.
#(config interface interface_number) full-duplex
Configures the interface for full-duplex.
#(config interface interface_number) half-duplex
Configures the interface for half-duplex.
#(config interface interface_number) ip-address ip-address
Sets the IP address for this interface to ip_address
#(config interface interface_number) instructions {accelerated-pac | central-pac
url | default-pac | proxy}
accelerated-pac: Configures browser to use your accelerated pac file.
central-pac: Configures browser to use your pac file.
default-pac: Configures browser to use a Blue Coat pac file.
proxy: Configures browser to use a proxy.
#(config interface interface_number) link-autosense {enable | disable}
Specifies that the interface should autosense speed and duplex.
#(config interface interface_number) mtu-size size
Specifies the MTU size.
#(config interface interface_number) no {accept-inbound | link-autosense}
Negates the current accept-inbound or link-autosense settings.
#(config interface interface_number) reject-inbound {enable | disable}
Rejects inbound connections on the interface.*
#(config interface interface_number) speed {10 | 100 | 1gb}
Specifies the interface speed.
#(config interface interface_number) subnet-mask subnet-mask
Sets the subnet mask for the interface.
#(config interface interface_number) native-vlan number
Sets the native VLAN value for this interface.
#(config interface interface_number) vlan-trunk {enable | disable}
Enables VLAN trunking on this interface.
#(config interface interface_number) clear-all-vlans
Resets all VLAN parameters to their default values.
#(config interface interface_number) view
Displays the interface settings.
*The allow-intercept and reject-inbound commands are interface-level configurations and
are not bridge-specific. The reject-inbound command always has precedence.
The following table describes how traffic is handled for the three possible settings of these options.
Example
#(config) interface 0
#(config interface 0) ip-address 10.252.10.54
ok
#(config interface 0) instructions accelerated-pac
ok
#(config interface 0) subnet-mask 255.255.255.0
ok
#(config interface 0) exit
SGOS#(config) interface 1
#(config interface 1) ip-address 10.252.10.72
ok
#(config interface 1) subnet-mask 255.255.255.0
ok
#(config interface 1) exit
#(config) ip-default-gateway
Synopsis
A key feature of the SG appliance is the ability to distribute traffic originating at the cache through
multiple IP gateways. Further, you can fine tune how the traffic is distributed among gateways. This
feature works with any routing protocol (for example, static routes or RIP).
Note: Load balancing through multiple IP gateways is independent from the per-interface load
balancing that the SG appliance automatically does when more than one network interface is installed.
Syntax
#(config) ip-default-gateway ip_address [preference group (1-10)] [weight
(1-100)]
Specifies the IP address of the default gateway to be used by the SG appliance.
Example
SGOS#(config) ip-default-gateway 10.25.36.47
ok
#(config) license-key
Synopsis
Use this command to configure license key settings.
Syntax
#(config) license-key auto-update {disable | enable}
Disables or enables auto-update of the Blue Coat license key.
#(config) license-key no path
Negates certain license key settings.
#(config) license-key path url
Specifies the network path to download the license key.
Example
SGOS#(config) license-key no path
ok
#(config) line-vty
Synopsis
When you have a CLI session, that session remains open as long as there is activity. If you leave the
session idle, the connection eventually times out and you must reconnect. The default timeout is five
minutes. You can set the timeout and other session-specific options using the line-vty command.
Syntax
#(config) line-vty
This changes the prompt to:
#(config line-vty)
Subcommands
#(config line-vty) exit
Exits configure line-vty mode and returns to configure mode.
#(config line-vty) length num_lines_on_screen
Specifies the number of lines of code that should appear on the screen at one time. Specify 0 to scroll
without pausing.
#(config line-vty) no length
Disables screen paging.
#(config line-vty) telnet {no transparent | transparent}
Indicates that this is a Telnet protocol-specific configuration. If you specify no transparent, carriage
returns are sent to the console as a carriage return plus linefeed. If you specify transparent, carriage
returns are sent to the console as a carriage return.
#(config line-vty) timeout minutes
Sets the line timeout to the number of minutes indicated by minutes.
#(config line-vty) view
Displays running system information.
Example
SGOS#(config) line-vty
SGOS#(config line-vty) timeout 60
ok
SGOS#(config line-vty) exit
SGOS#(config)
#(config) load
See
❐ # load on page 57.
#(config) mapi
Synopsis
Configures MAPI
Syntax
SGOS#(config) mapi
This changes the prompt to:
SGOS#(config mapi) [subcommands]
Subcommands
SGOS#(config mapi) batching {enable | disable}
Enables or disables batching. The default is enabled.
SGOS#(config mapi) exit
Exits the mapi mode and returns to SGOS#(config) mode.
SGOS#(config mapi) handoff (enable | disable}
Use the endpoint-mapper service. The default is enabled.
SGOS#(config mapi) keep-alive duration 1-168
Sets the length of time, in hours, that the session is active. The default is 72 hours.
SGOS#(config mapi) keep-alive {enable | disable}
Enables the keep-alive configuration. The default is disabled.
SGOS#(config mapi) keep-alive interval 15-60
Sets the length of time, in minutes, before the service checks for new e-mail. The default is 30 minutes.
SGOS#(config map) keep-alive max-sessions 1-200
Sets the maximum number of active sessions at any given point. The default is 100 sessions. If the limit is
reached, the oldest session is dropped.
SGOS#(config mapi) view
Views the MAPI configuration.
Example
SGOS#(config mapi) view
Batching: enabled
Keep-Alive: disabled
Keep-Alive Duration (hours): 72
Keep-Alive Interval (minutes): 30
Keep-Alive Maximum Sessions: 100
Endpoint Mapper Handoff: enabled
#(config) netbios
Synopsis
Use this command to configure NetBIOS.
Syntax
#(config) netbios
This changes the prompt to:
#(config netbios)
#(config netbios) exit
Exits configure netbios mode and returns to configure mode.
#(config netbios) nbstat requester {retries | timeout} | responder {enable |
disable}
Requester is enabled by default, with three retries and a five-second timeout. Responder is disabled by
default.
#(config netbios) view
Shows the NetBIOS settings.
Example
SGOS#(config) netbios
SGOS#(config netbios) nbstat responder enable
ok
SGOS#(config netbios) exit
SGOS#(config)
ok
#(config) no
Synopsis
Use this command to negate the current settings for the archive configuration, content priority, IP
default gateway, SOCKS machine, or system upgrade path.
Syntax
#(config) no archive-configuration
Clears the archive configuration upload site.
#(config) no bridge bridge_name
Clears the bridge configuration.
#(config) no content {priority {regex regex | url url} | outstanding-requests
{delete | priority | revalidate} regex}
priority {regex regex | url url}: Removes a deletion regular expression policy or a deletion URL
policy.
outstanding-requests {delete | priority | revalidate} regex: Deletes a specific,
regular expression command in-progress (revalidation, priority, or deletion).
#(config) no ip-default-gateway ip_address
Sets the default gateway IP address to zero.
#(config) no serial-number
Removes the serial number.
#(config) no socks-machine-id
Removes the SOCKS machine ID from the configuration.
#(config) no upgrade-path
Clears the upgrade image download path.
Example
SGOS#(config) no archive-configuration
ok
SGOS#(config) no content priority regex http://.*cnn.com
ok
SGOS#(config) no content priority url http://www.bluecoat.com
ok
SGOS#(config) no ip-default-gateway 10.252.10.50
ok
SGOS#(config) no socks-machine-id
ok
SGOS#(config) no upgrade-path
ok
#(config) ntp
Synopsis
Use this command to set NTP parameters. Network Time Protocol (NTP) is a protocol that is used to
synchronize computer clock times in a network of computers. The SG appliance sets the UTC time by
connecting to an NTP server. The SG appliance includes a list of NTP servers available on the Internet.
If an NTP server is not available, you can set the time manually using the Management Console.
Syntax
#(config) ntp clear
Removes all entries from the NTP server list.
#(config) ntp disable
Disables NTP.
#(config) ntp enable
Enables NTP.
#(config) ntp interval minutes
Specifies how often to perform NTP server queries.
#(config) ntp no server domain_name
Removes the NTP server named domain_name from the NTP server list.
#(config) ntp server domain_name
Adds the NTP server named domain_name from the NTP server list.
Example
SGOS#(config) ntp server clock.tricity.wsu.edu
ok
#(config) policy
Synopsis
Use this command to specify central and local policy file location, status, and other options.
Syntax
#(config) policy central-path url
Specifies the network path (indicated by url) from which the central policy file can be downloaded.
#(config) policy forward-path url
Specifies the network path (indicated by url) from which the forward policy file can be downloaded.
#(config) policy local-path url
Specifies the network path (indicated by url) from which the local policy file can be downloaded.
#(config) policy no central-path
Specifies that the current central policy file URL setting should be cleared.
#(config) policy no forward-path
Specifies that the current forward policy file URL setting should be cleared.
#(config) policy no local-path
Specifies that the current local policy file URL setting should be cleared.
#(config) policy no notify
Specifies that no e-mail notification should be sent if the central policy file should change.
#(config) policy no subscribe
Specifies that the current policy should not be automatically updated in the event of a central policy
change.
#(config) policy no vpm-cpl-path
Clears the network path to download VPM CPL policy.
#(config) policy no vpm-software
Clears the network path to download VPM software.
#(config) policy no vpm-xml-path
Clears the network path to download VPM XML policy.
#(config) policy notify
Specifies that an e-mail notification should be sent if the central policy file should change.
#(config) policy order order of v)pm, l)ocal, c)entral
Specifies the policy evaluation order.
#(config) policy poll-interval minutes
Specifies the number of minutes that should pass between tests for central policy file changes.
#(config) policy poll-now
Tests for central policy file changes immediately.
#(config) policy proxy-default {allow | deny}
allow: The default proxy policy is allow.
deny: The default proxy policy is deny.
#(config) policy reset
Clears all policies.
#(config) policy subscribe
Indicates that the current policy should be automatically updated in the event of a central policy change.
#(config) policy vpm-cpl-path url
Specifies the network path (indicated by url) from which the vpm-cpl policy file can be downloaded.
Example
SGOS#(config) policy local-path http://www.server1.com/local.txt
ok
SGOS#(config) policy central-path http://www.server2.com/central.txt
ok
SGOS#(config) policy poll-interval 10
#(config) profile
Synopsis
Sets your system profile to normal (the default setting) or portal (to accelerate the server).
Syntax
#(config) profile bwgain
Sets your system profile to bandwidth gain.
#(config) profile normal
Sets your system profile to normal.
#(config) profile portal
Sets your system profile to portal.
Example
SGOS#(config) profile normal
ok
#(config) proxy-services
Synopsis
Manages the proxy services on the SG appliance.
Syntax
#(config) proxy-services
This changes the prompt to:
#(config proxy-services)
Subcommands
Note: Additional information is found under options that are hyperlinked (blue).
Note: The service types listed below are not necessarily the service names you use. The syntax for
creating a service type is #(config proxy-services) create service_type service_name, where
service_type is one of those listed below and service_name is of your choosing.
Example
#(config proxy-services) create tcp-tunnel tcp_tunnel_2
ok
#(config proxy-services) edit tcp_tunnel_2
#(config tcp_tunnel_2)?
add Add a listener
attribute Configure service attributes
bypass Change a particular listener's action to bypass
exit Return to (config proxy-services) prompt
intercept Change a particular listener's action to intercept
remove Remove a listener
view Show proxy service configuration
#(config dynamic-bypass)
Synopsis
Dynamic bypass provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of errors.
Syntax
#(config) proxy-services
#(config proxy-services) dynamic-bypass
The prompt changes to:
#(config dynamic-bypass)
Subcommands
#(config dynamic-bypass) clear
Clears all dynamic bypass entries.
#(config dynamic-bypass) disable
Disables dynamic bypass .
#(config dynamic-bypass) enable
Enables dynamic bypass.
#(config dynamic-bypass) exit
Exits to the #(config proxy-services) prompt.
#(config dynamic-bypass) max-entries number_of_entries
Specifies the maximum number of dynamic-bypass entries. Connections that match entries in the
dynamic bypass list are not intercepted by the application proxies. Entries in the dynamic bypass list
eventually time out based on the configuration. If the list grows beyond its configured size, the oldest
entry is removed
#(config dynamic-bypass) no trigger {all | connect-error | non-http |
receive-error | 400 | 403 | 405 | 406 | 500 | 502 | 503 | 504}
Disables dynamic bypass for the specified HTTP response code, all HTTP response codes, or all
non-HTTP responses. Values are specified below.
connect-error Enables dynamic bypass for any connection failure to the origin content server,
including timeouts.
receive-error Enables dynamic bypass for when a TCP connection to an origin content server
succeeds, but the cache does not receive an HTTP response.
Example
#(config) proxy-services
#(config proxy-services) dynamic-bypass
#(config dynamic-bypass) clear
ok
#(config dynamic-bypass) enable
WARNING:
Requests to sites that are put into the dynamic bypass list will
bypass future policy evaluation. This could result in subversion
of on-box policy. The use of dynamic bypass is cautioned.
ok
#(config dynamic-bypass) trigger all
ok
#(config static-bypass)
Synopsis
Static bypass prevents the SG appliance from transparently accelerating requests to servers that
perform IP authentication with clients. When a request matches an IP address and subnet mask
specification, the request is sent to the designated gateway without going through the SG appliance.
Syntax
#(config) proxy-services
#(config proxy-services) static-bypass
#(config static-bypass)
Subcommands
#(config static-bypass) add {all | client_ip_address | client_ip_address/
subnet-mask} {all | server_ip_address | server_ip_address/subnet-mask}
Allows you to add a listener with the parameters you specify
#(config static-bypass) exit
Exits from the #(config static-bypass) mode and returns to the #(config proxy-services)
mode.
#(config static-bypass) view {filter {* | all | client_ip_address |
client_ip_address/ subnet-mask} {* | all | server_ip_address |
server_ip_address/ subnet-mask}} | <Enter>}
Allows you to view static bypass entries based on the filters you specify.
Example
SGOS#(config proxy-services) static-bypass
SGOS #(config static-bypass) add 10.9.17.135 all
ok
#(config aol-im)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to :
#(config service_name)
Subcommands
#(config service_name) add all {ip_address | ip_address/subnet-mask} {port |
first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG’s IP address.
#(config service_name) bypass {all |ip_address | ip_address/subnet-mask} {port |
first_port-last_port}
Changes the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {all |ip_address | ip_address/subnet-mask} {port
| first_port-last_port}
Changes the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create aol-im aol1
SGOS#(config proxy-services) edit aol1
SGOS #(config aol1) attribute reflect-client-ip enable
ok
#(config cifs)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {transparent | ip_address | ip_address/subnet-mask}
{port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute adn-optimize {disable | enable}
Controls whether to optimize bandwidth usage when connecting upstream using an ADN tunnel.
#(config service_name)) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) attribute use-adn {disable | enable}
Controls whether ADN is enabled for a specific service. Enabling ADN does not guarantee the
connections are accelerated by ADN. The actual enable decision is determined by ADN routing (for
explicit deployment) and network setup (for transparent deployment).
#(config service_name) bypass {transparent | ip_address | ip_address/subnet-mask}
{port | first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {transparent | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create cifs cifs1
SGOS#(config proxy-services) edit cifs1
SGOS #(config cifs1) attribute adn-optimize enable
ok
#(config dns)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) bypass {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the # (config proxy-services) prompt.
#(config service_name) intercept {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create dns dns1
SGOS#(config proxy-services) edit dns1
SGOS #(config dns1) attribute reflect-client-ip enable
ok
#(config endpoint-mapper)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config proxy-services service_name) add {all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute adn-optimize {disable | enable}
Controls whether to optimize bandwidth usage when connecting upstream using an ADN tunnel.
#(config service_name) attribute reflect-client-ip {disable | enable}}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) attribute use-adn {disable | enable}
Controls whether ADN is enabled for a specific service. Enabling ADN does not guarantee the
connections are accelerated by ADN. The actual enable decision is determined by ADN routing (for
explicit deployment) and network setup (for transparent deployment).
#(config service_name) bypass {all | ip_address | ip_address/subnet-mask} {port |
first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {all | ip_address | ip_address/subnet-mask}
{port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create endpoint-mapper epmapper1
SGOS#(config proxy-services) edit epmapper1
SGOS#(config epmapper1) add all 10003
ok
#(config ftp)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {all | ip_address | ip_address/subnet-mask} {port |
first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute reflect-client-ip {enable | disable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) attribute adn-optimize {disable | enable}
Controls whether to optimize bandwidth usage when connecting upstream using an ADN tunnel.
#(config service_name) attribute use-adn {disable | enable}
Controls whether ADN is enabled for a specific service. Enabling ADN does not guarantee the
connections are accelerated by ADN. The actual enable decision is determined by ADN routing (for
explicit deployment) and network setup (for transparent deployment).
#(config service_name) bypass {all | ip_address | ip_address/subnet-mask} {port |
first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {all | ip_address | ip_address/subnet-mask}
{port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create ftp ftp1
SGOS#(config proxy-services) edit ftp1
SGOS #(config ftp1) intercept all 10004
ok
#(config http)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute adn-optimize {disable | enable}
Controls whether to optimize bandwidth usage when connecting upstream using an ADN tunnel.
#(config service_name) attribute authenticate-401 {disable | enable}
All transparent and explicit requests received on the port always use transparent authentication (cookie
or IP, depending on the configuration). This is especially useful to force transparent proxy authentication
in some proxy-chaining scenarios.
#(config service_name) attribute connect (disable | enable}
This command is deprecated. Policy should be used instead. For example:
Example
SGOS#(config proxy-services) create http http2
SGOS#(config proxy-services) edit http2
SGOS#(config http2) attribute authenticate-401 enable
ok
#(config https-reverse-proxy)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters specified.
#(config service_name) attribute adn-optimize {disable | enable}
Controls whether to optimize bandwidth usage when connecting upstream using an ADN tunnel.
#(config service_name) attribute ccl list_name
CA Certificate List used for verifying client certificates.
#(config service_name) attribute cipher-suite cipher-suite+
Allows you to specify the cipher suites you want to use with the https-reverse-proxy service.
#(config service_name) attribute forward-client-cert {disable | enable}
When used with the verify-client attribute, puts the extracted client certificate information
into a header that is included in the request when it is forwarded to the OCS. The name of the
header is Client-Cert. The header contains the certificate serial number, subject, validity dates
and issuer (all as name=value pairs). The actual certificate is not forwarded.
#(config service_name) attribute keyring keyring-ID
Allows you to specify the keyring you want to use with this service.
#(config service_name) attribute reflect-client-ip {disable | enable}}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) attribute use-adn {disable | enable}
Controls whether ADN is enabled for a specific service. Enabling ADN does not guarantee the
connections are accelerated by ADN. The actual enable decision is determined by ADN routing (for
explicit deployment) and network setup (for transparent deployment).
#(config service_name) attribute ssl-versions {sslv2 |sslv3 | tlsv1 | sslv2v3 |
sslv2tlsv1 | sslv3tlsv1 |sslv2v3tlsv1}
Allows you to select which versions of SSL you want to support. The default is to support SSL v2 and v3
and enable TLS.
#(config service_name) attribute verify-client {disable | enable}
Requests and validates the SSL client certificate.
#(config service_name) bypass {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Changes the behavior from intercept to bypass for the listener specified.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
Example
SGOS#(config proxy-services) create https-reverse-proxy HTTPS_RP1
SGOS#(config proxy-services) edit HTTPS_RP1
SGOS#(config HTTPS_RP1) attribute reflect-client-ip enable
ok
#(config mms)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) bypass {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create mms mms1
SGOS#(config proxy-services) edit mms1
SGOS#(config mms1) attribute reflect-client-ip enable
ok
#(config msn-im)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {all | ip_address | ip_address/subnet-mask} {port |
first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) bypass {all | ip_address | ip_address/subnet-mask} {port |
first_port-last_port}
Changes the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {all | ip_address | ip_address/subnet-mask} {port
| first_port-last_port}
Changes the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create msn-im msn1
SGOS#(config proxy-services) edit msn1
SGOS#(config msn1) attribute reflect-client-ip enable
ok
#(config restricted-intercept)
Synopsis
By default, all clients and servers evaluate the entries in Proxy Services (Configuration > Services >
Proxy Services) where the decision is made to intercept or bypass a connection. To restrict or reduce
the clients and servers that can be intercepted by proxy services, use the restricted intercept list. The
restricted intercept list is useful in a rollout, prior to full production, where you only want to intercept
a subset of the clients. After you are in full production mode, the restricted intercept list can be
disabled.
Enabling restricted intercept only intercepts traffic specified in the client/server list. Disabling
restricted intercept results in normal interception.
Syntax
#(config) proxy-services
#(config proxy-services) restricted-intercept
The prompt changes to:
#(config restricted-intercept)
Subcommands
#(config restricted-intercept) {enable | disable}
Enables or disabled the restricted-intercept list.
#(config restricted-intercept) add {all | client_ip | client_ip/subnet-mask} | {all|
server_ip | server_ip/subnet-mask}
Adds an entry to the restricted list, either a client or a server.
#(config restricted-intercept) remove {all | client_ip | client_ip/subnet-mask} |
all| server_ip | server_ip/subnet-mask}
Clears the specified client or server from the restricted list.
#(config restricted-intercept) view {<Enter> | filter {all | client_ip |
client_ip/subnet-mask} | {all| server_ip | server_ip/subnet-mask}
Allows you view the entire list or to filter on specific clients or servers.
Example
#(config) proxy-services
#(config proxy-services) restricted-intercept
#(config restricted-intercept) add all 192.168.100.1
#(config rtsp)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) bypass {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create rtsp rtsp1
SGOS#(config proxy-services) edit rtsp1
SGOS#(config rtsp1) attribute reflect-client-ip enable
ok
#(config socks)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {explicit | ip_address | ip_address/subnet-mask} {port
| first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute adn-optimize {disable | enable}
Controls whether to optimize bandwidth usage when connecting upstream using an ADN tunnel.
#(config service_name) attribute detect-protocol {disable | enable}
Detects the protocol being used. Protocols that can be detected include: HTTP, P2P (eDonkey, BitTorrent,
FastTrack, Gnutella), SSL, and Endpoint Mapper.
#(config service_name) attribute use-adn {disable | enable}
Controls whether ADN is enabled for a specific service. Enabling ADN does not guarantee the
connections are accelerated by ADN. The actual enable decision is determined by ADN routing (for
explicit deployment) and network setup (for transparent deployment).
#(config service_name) bypass {explicit | ip_address | ip_address/subnet-mask}
{port | first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {explicit | ip_address | ip_address/subnet-mask}
{port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create socks socks1
SGOS#(config proxy-services) edit socks1
SGOS#(config socks1) attribute adn-optimize enable
ok
#(config ssl)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {transparent | ip_address | ip_address/subnet-mask}
{port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute adn-optimize {disable | enable}
Controls whether to optimize bandwidth usage when connecting upstream using an ADN tunnel.
#(config service_name) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) attribute use-adn {disable | enable}
Controls whether ADN is enabled for a specific service. Enabling ADN does not guarantee the
connections are accelerated by ADN. The actual enable decision is determined by ADN routing (for
explicit deployment) and network setup (for transparent deployment).
#(config service_name) bypass {transparent | ip_address | ip_address/subnet-mask}
{port | first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {transparent | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create ssl ssl1
SGOS#(config proxy-services) edit ssl1
SGOS#(config ssl1) add transparent 443
#(config tcp-tunnel)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute adn-optimize {disable | enable}
Controls whether to optimize bandwidth usage when connecting upstream using an ADN tunnel.
#(config service_name) attribute detect-protocol {disable | enable}
Detects the protocol being used. Protocols that can be detected include: HTTP, P2P (eDonkey, BitTorrent,
FastTrack, Gnutella), SSL, and Endpoint Mapper.
#(config service_name) attribute early-intercept {disable | enable}
Controls whether the proxy responds to client TCP connection requests before connecting to the
upstream server. When early intercept is disabled, the proxy delays responding to the client until after it
has attempted to contact the server.
#(config service_name) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) attribute use-adn {disable | enable}
Controls whether ADN is enabled for a specific service. Enabling ADN does not guarantee the
connections are accelerated by ADN. The actual enable decision is determined by ADN routing (for
explicit deployment) and network setup (for transparent deployment).
#(config service_name) bypass {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create tcp-tunnel TCP1
SGOS#(config proxy-services) edit TCP1
SGOS#(config TCP1) attribute early-intercept enable
ok
#(config telnet)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to
#(config service_name)
Subcommands
#(config service_name) add {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) bypass {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {transparent | explicit | all | ip_address |
ip_address/subnet-mask} {port | first_port-last_port}
Change the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create telnet telnet1
SGOS#(config proxy-services) edit telnet1
SGOS #(config telnet1) view
Service Name: telnet1
Proxy: Telnet
Attributes: early-intercept
Destination IP Port Range Action
#(config yahoo-im)
Synopsis
Enters the subcommand mode to allow you to manage a specific proxy service.
Syntax
#(config proxy-services) create service_type service_name
#(config proxy-services) edit service_name
This changes the prompt to:
#(config service_name)
Subcommands
#(config service_name) add {all | ip_address | ip_address/subnet-mask} {port |
first_port-last_port} [intercept | bypass]
Allows you to add a listener with the parameters you specify.
#(config service_name) attribute reflect-client-ip {disable | enable}
Enables or disables sending of client's IP address instead of the SG's IP address.
#(config service_name) bypass {all | ip_address | ip_address/subnet-mask} {port |
first_port-last_port}
Changes the behavior from intercept to bypass for the listener you specify.
#(config service_name) exit
Exits to the #(config proxy-services) prompt.
#(config service_name) intercept {all | ip_address | ip_address/subnet-mask} {port
| first_port-last_port}
Changes the behavior from bypass to intercept for the listener you specify.
#(config service_name) view
Views the specified proxy service.
Example
SGOS#(config proxy-services) create yahoo-im yahoo1
SGOS#(config proxy-services) edit yahoo1
SGOS#(config yahoo1) attribute reflect-client-ip enable
ok
#(config) restart
Synopsis
Use this command to set restart options for the SG appliance.
Syntax
#(config) restart core-image {context | full | keep number | none}
context: Indicates only core image context should be written on restart.
full: Indicates full core image should be written on restart.
keep numbers: Specifies a number of core images to keep on restart.
none: Indicates no core image should be written on restart.
#(config) restart mode {hardware | software}
hardware: Specifies a hardware restart.
software: Specifies a software restart.
Example
SGOS#(config) restart mode software
ok
#(config) return-to-sender
Synopsis
The return-to-sender feature eliminates unnecessary network traffic when the three following
conditions are met:
❐ The SG appliance has connections to clients or servers on a different subnet.
❐ The shortest route to the clients or servers is not through the default gateway.
❐ There are no static routes or RIP routes defined that apply to the IP addresses of the clients
and servers.
Under these conditions, if the return-to-sender feature is enabled, the SG appliance remembers the
MAC address of the last hop for a packet from the client or server and sends any responses or requests
to the MAC address instead of the default gateway.
Under the same conditions, if return-to-sender is disabled, the SG appliance sends requests or
responses to the default gateway, which then sends the packets to the gateway representing the last
hop to the SG appliance for the associated connection. This effectively doubles the number of packets
transmitted on the LAN compared to when return-to-sender is enabled.
Inbound return-to-sender affects connections initiated to the SG appliance by clients. Outbound
return-to-sender affects connections initiated by the SG appliance to origin servers.
Note: Return-to-sender functionality should only be used if static routes cannot be defined for the
clients and servers or if routing information for the clients and servers is not available through RIP
packets.
With return-to-sender, you can use load balancing. By default, all traffic flows out of one card. If
return-to-sender is enabled, traffic is returned on the card it originally came from.
Syntax
#(config) return-to-sender inbound {disable | enable}
Enables or disables return-to-sender for inbound sessions.
#(config) return-to-sender outbound {disable | enable}
Enables or disables return-to-sender for outbound sessions.
#(config) return-to-sender version {1 | 2}
Enables return-to-sender (RTS) versions 1 or 2.
In version 1, the RTS route is created at Layer-3 and stored globally, thus being interface agnostic.
RTS version 2 was introduced to get around this multi-interface limitation. With version 2, TCP now
stores a per-socket RTS route that contains both the destination MAC address and interface information.
After the SYN is received by the SG appliance, all subsequent packets on that socket traverses the
interface on which the SYN was received.
Note: All current sockets tied to that interface will time out. However, subsequent and existing TCP
connections continue to function normally on the other interfaces.
Example
SGOS#(config) return-to-sender inbound enable
ok
#(config) reveal-advanced
❐ # reveal-advanced on page 71.
#(config) rip
Synopsis
Use this command to set RIP (Routing Information Protocol) configuration options.
Using RIP, a host and router can send a routing table list of all other known hosts to its closest
neighbor host every 30 seconds. The neighbor host passes this information on to its next closest
neighbor and so on until all hosts have perfect knowledge of each other. (RIP uses the hop count
measurement to derive network distance.) Each host in the network can then use the routing table
information to determine the most efficient route for a packet.
The RIP configuration is defined in a configuration file. To configure RIP, first create a text file of RIP
commands and then load the file by using the load command.
Syntax
#(config) rip disable
Disables the current RIP configuration.
#(config) rip enable
Enables the current RIP configuration.
#(config) rip no path
Clears the current RIP configuration path as determined using the rip path url command.
#(config) rip path url
Sets the path to the RIP configuration file to the URL indicated by url.
Example
SGOS#(config) rip path 10.25.36.47/files/rip.txt
ok
#(config) security
The #(config) security command is used for security, authentication, and authorization. The
security command, by itself, cannot be used. You must use security commands with the options
discussed in Subcommands below.
Synopsis
The SG appliance provides the ability to authenticate and authorize explicit and transparent proxy
users using industry-standard authentication services.
Syntax
#(config) security [subcommands]
Subcommands
Modes in the security command are divided into three categories:
❐ Console Access and Authorization
❐ Realms
❐ Transparent Proxy
Note: While the commands are listed in functional order below, they are discussed in alphabetical
order in the pages that follow. Each of the options in blue are hyperlinked so you can go directly to the
command.
Realms
Multiple authentication realms can be used on a single SG appliance. Multiple realms are essential if
the enterprise is a managed provider or the company has merged with or acquired another company.
Even for companies using only one protocol, multiple realms might be necessary, such as the case of a
company using an LDAP server with multiple authentication boundaries. You can use realm
sequencing to search the multiple realms all at one time.
Note: Up to 40 realms per type (such as certificate, authentication forms, and RADIUS) are allowed.
Transparent Proxy
The transparent proxy authentication commands allows you
Example
#(config) show security
Account:
Username: “admin”
Hashed Password: $1$a2zTlEE$1b88R3SXUTXS.zO7lh8db0
Hashed Enable Password: $1$xQnqGerX$LU65b20trsIAF6yJox26L.
Hashed Front Panel PIN: "$1$ThSEiB1v$seyBhSxtTXEtUGDZ5NOB1/"
Management console display realm name: "Aurora"
Management console auto-logout timeout: Never
Access control is disabled
Access control list (source, mask):
Flush credentials on policy update is enabled
Default authenticate.mode: auto
Transparent proxy authentication:
Method: cookie
Cookie type: session
Cookie virtual-url: "www.cfauth.com/"
IP time-to-live: 15
Local realm:
No local realm is defined.
RADIUS realm:
No RADIUS realm is defined.
LDAP realm(s):
No LDAP realm is defined.
IWA realm(s):
No IWA realm is defined.
Certificate realm(s):
No certificate realms are defined.
SiteMinder realm(s):
No realms defined.
COREid realm(s):
No realms defined.
Policy-substitution realm(s):
No realms defined.
Realm sequence(s):
No realm sequences defined.
Synopsis
Adds or removes IP addresses to the console access control list.
Syntax
#(config) security allowed-access [subcommands]
Subcommands
#(config) security allowed-access add source_ip [ip_mask]
Adds the specified IP address to the access control list.
#(config) security allowed-access remove source_ip [ip_mask]
Removes the specified IP from the access control list.
Example
#(config) security allowed-access add 10.25.36.47
Synopsis
Allows you to create and manage authentication forms.
Syntax
#(config) security authentication-forms [subcommands]
Subcommands
#(config) security authentication-forms copy [source_form_name
target_form_name
Changes the name of a form. Note that you cannot change the form type.
#(config) security authentication-forms create {authentication-form |
new-pin-form | query-form} form_name
Creates a new authentication form using the form type you specify.
#(config) security authentication-forms delete form_name
Deletes an authentication form
#(config) security authentication-forms inline form_name eof_marker
Installs an authentication form from console input.
#(config) security authentication-forms load form_name
Downloads a new authentication form.
#(config) security authentication-forms no path [form_name]
Negates authentication-form configuration.
#(config) security authentication-forms path [form_name] path
Specifies the path (URL or IP address) from which to load an authentication form, or the entire set of
authentication forms.
#(config) security authentication-forms view
Views the form specified or all forms.
Example
#(config) security authentication-forms
#(config authentication-forms) create form_type form_name
ok
where form_type indicates the default authentication-form, new-pin-form, or
query-form and form_name is the name you give the form.
Synopsis
Allows you to create and manage certificate realms.
Syntax
#(config) security certificate [subcommands]
Subcommands
#(config) security certificate create-realm realm_name
Creates the specified certificate realm.
#(config) security certificate delete-realm realm_name
Deletes the specified certificate realm.
#(config) security certificate edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security certificate view [realm_name]
Displays the configuration of all certificate realms or just the configuration for realm_name if specified.
Submodes
#(config) security certificate edit-realm realm_name
This changes the prompt to:
#(config certificate_realm)
Commands in this submode:
#(config certificate certificate_realm) authorization append-base-dn {disable |
dn dn_to_append | enable}
Disables or enables appending of the base DN to the authenticated username, or specifies the base DN to
append. If no base DN is specified, then the first base DN in the LDAP authorization realm is used.
Applies to LDAP authorization realms only
#(config certificate certificate_realm) authorization container-attr-list
list_of_attribute_names
Specifies the attributes from the certificate subject to use in constructing the user DN. E.g. “o, ou”. The
list needs to be quoted if it contains spaces.
#(config certificate certificate_realm) authorization no {container-attr-list |
realm-name}
Clears the container attribute list or the authorization realm.
Example
#(config) security certificate edit-realm testcert
#(config certificate testcert) no container-attr-list
ok
#(config certificate testcert) cache-duration 800
ok
#(config certificate testcert) exit
#(config)
Synopsis
Allows you to create and manage COREid realms.
Syntax
#(config) security coreid [subcommands]
Subcommands
#(config) security coreid create-realm realm_name
Creates the specified COREid realm
#(config) security coreid delete-realm realm_name
Deletes the specified COREid realm.
#(config) security coreid edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security coreid view [realm_name]
Displays the configuration of all COREid realms or just the configuration for realm_name if specified.
Submodes
#(config) security coreid edit-realm realm_name
This changes the prompt to:
#(config coreid realm_name)
Commands in this submode:
#(config coreid realm_name) access-server-hostname hostname
The hostname of the primary Access Server.
#(config coreid realm_name) access-server-id id
The ID of the primary Access Server.
#(config coreid realm_name) access-server-port port
The port of the primary Access Server
#(config coreid realm_name) add-header-responses disable | enable
When enabled, authorization actions from the policy domain obtained during authentication are added
to each request forwarded by the SG appliance. Note that header responses replaces any existing header
of the same name; if no such header exists, the header is added. Cookie responses replace a cookie
header with the same cookie name; if no such cookie header exists, one is added.
#(config coreid realm_name) alternate-agent accessgate-id name
The ID of the alternate AccessGate agent.
#(config coreid realm_name) alternate-agent encrypted-secret
encrypted_shared_secret
The encrypted password associated with the alternate AccessGate. (Passwords can be up to 64 characters
long and are always case sensitive.) The primary use of the encrypted-secret command is to allow the SG
appliance to reload a password that it encrypted. If you choose to use a third-party encryption
application, be sure it supports RSA encryption, OAEP padding, and is Base64 encoded with no
newlines|
Example
SGOS#(config) security coreid edit-realm coreid_1
SGOS#(config coreid coreid_1) access-server-hostname AccessServer_1
SGOS#(config coreid coreid_1) cache-duration 800
SGOS#(config coreid coreid_1) exit
Synopsis
Sets the default authenticate.mode to auto or to sg2.
Syntax
#(config) security default-authenticate-mode [auto | sg2]
Subcommands
#(config) security default-authenticate-mode auto
Enables the access control list.
#(config) security default-authenticate-mode sg2
Disables the access control list.
Example
SGOS#(config) security default-authenticate-mode auto
Synopsis
Destroys recoverable passwords in configuration used by previous versions.
Syntax
#(config) security destroy-old-password [force]
Subcommands
#(config) security destroy-old-password
Destroys passwords after prompting.
#(config) security destroy-old-password force
Destroys passwords without prompting.
Note: Do not use this command if you intend to downgrade, as the old passwords are destroyed.
Example
#(config) destroy-old-password force
Synopsis
Sets the console enable password to the password specified.
Syntax
#(config) security enable-password “password”
#(config) security hashed-enable-password hashed_password
Subcommands
#(config) security enable-password “password”
Note that the enable password must be in quotes. This is the password required to enter enable mode
from the CLI when using console credentials, the serial console, or RSA SSH.
#(config) security hashed-enable-password hashed_password
The enable password in hashed format. You can either hash the password prior to entering it, or you can
allow the SG appliance to hash the password.
Example
#(config) security enable-password “test”
Synopsis
Enables or disables the console access control list (ACL).
Syntax
#(config) security enforce-acl [enable | disable]
Subcommands
#(config) security enforce-acl enable
Enables the access control list.
#(config) security enforce-acl disable
Disables the access control list.
Example
#(config) security enforce-acl disable
Synopsis
Sets a four-digit PIN to restrict access to the front panel of the SG appliance.
Syntax
#(config) security front-panel-pin PIN
Subcommands
#(config) security front-panel-pin PIN
Use of this command is recommended for security reasons.
Example
#(config) security front-panel-pin 1234
Synopsis
Allows you to create and manage IWA realms.
Syntax
#(config) security iwa [subcommands]
Subcommands
#(config) security iwa create-realm realm_name
Creates the specified IWA realm.
#(config) security iwa delete-realm realm_name
Deletes the specified IWA realm.
#(config) security iwa edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security iwa view [realm_name]
Displays the configuration of all IWA realms or just the configuration for realm_name if specified.
Submodes
#(config) security IWA edit-realm realm_name
This changes the prompt to:
#(config IWA realm_name)
Commands in this submode:
#(config IWA realm_name) alternate-server host [port]
Specifies the alternate server host and port.
#(config IWA realm_name) cache-duration seconds
Specifies the length of time to cache credentials for this realm.
#(config IWA realm_name) cookie {persistent {enable | disable} | verify-ip {enable |
disable}
Specifies whether to enable persistent or session cookies, and whether to verify the IP address of the
cookie.
#(config IWA realm_name) credentials-basic {disable | enable}
Disables/enables support for Basic credentials in this realm. At least one of Basic or NTLM/Kerberos
credentials must be supported.
Example
#(config) security IWA edit-realm testIWA
#(config IWA testIWA) cache-duration 1500
ok
#(config IWA testIWA) no alternate server
ok
#(config IWA testIWA) exit
#(config)
Synopsis
Allows you to configure and manage LDAP realms.
Syntax
#(config) security ldap [subcommands]
Subcommands
#(config) security ldap create-realm realm_name
Creates the specified LDAP realm
#(config) security ldap delete-realm realm_name
Deletes the specified LDAP realm.
#(config) security ldap edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security ldap view [realm_name]
Displays the configuration of all LDAP realms or just the configuration for realm_name if specified.
Submodes
#(config) security ldap edit-realm realm_name
This changes the prompt to:
#(config ldap realm_name)
Commands in the ldap realm_name mode:
#(config ldap realm_name) alternate-server host [port]
Specifies the alternate server host and port.
#(config ldap realm_name) case-sensitive {disable | enable}
Specifies whether or not the LDAP server is case-sensitive.
Example
#(config) security ldap edit-realm testldap
#(config ldap testldap) server-type iplanet
ok
#(config ldap testldap) spoof-authentication origin
ok
#(config ldap testldap) exit
Synopsis
Allows you to configure and manage local realms.
Syntax
#(config) security local [subcommands]
Subcommands
#(config) security local create-realm realm_name
Creates the specified local realm.
#(config) security local delete-realm realm_name
Deletes the specified local realm.
#(config) security local edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security local view [realm_name]
Displays the configuration of all local realms or just the configuration for realm_name if specified.
Submodes
#(config) security local edit-realm realm_name
This changes the prompt to:
#(config local realm_name)
Commands found in this submode include:
#(config local realm_name) cache-duration seconds
Specifies the length of time to cache credentials for this realm.
#(config local realm_name) cookie {persistent {enable | disable} | verify-ip
{enable | disable}
Specifies whether to enable persistent or session cookies, and whether to verify the IP address of the
cookie.
#(config local realm_name) default-group-name default_group_name
If the validate-authorized-user command is disabled and a default-group-name is configured,
the default-group-name is used as the group name for non-existent users.
#(config local realm_name) display-name display_name
Specifies the display name for this realm.
#(config local realm_name) exit
Exits configure security local mode and returns to #(config) mode.
#(config local realm_name) refresh-time {authorization-refresh seconds |
surrogate-refresh seconds}
Sets the refresh time for authorization and surrogates.
Example
#(config) security local edit-realm testlocal
#(config local testlocal) cache-duration 1500
ok
#(config local testlocal) spoof-authentication proxy
ok
#(config local testlocal) exit
#(config)
Synopsis
Manages the local-user-list used in local realms.
Syntax
#(config) security local-user-list [subcommands]
Subcommands
#(config) security local-user-list clear [force]
Clears all local user lists. Lists referenced by local realms and the default local user list are recreated but
empty. Specify force to clear realms without a prompt for confirmation.
#(config) security local-user-list create local-user-list
Creates the local user list with the name specified
#(config) security local-user-list default append-to-default {disable | enable}
Disables/enables appending uploaded users to the default local user list.
#(config) security local-user-list default list local_user_list
Specifies the default local user list. The default list is populated during password file uploads. The
default list is also the default list used by local realms when they are created
#(config) security local-user-list delete local-user-list [force]
Deletes the specified local user list. The default list and any lists used by local realms cannot be deleted.
Specify force to delete the list without a prompt for confirmation.
#(config) security local-user-list edit local-user-list
Changes the prompt. See Submodes.
Submodes
#(config) security local-user-list edit local_user_list
This changes the prompt to:
#(config local-user-list local_user_list)
Commands found in this submode include:
#(config local-user-list local_user_list) disable-all
Disables all user accounts in the specified list.
#(config local-user-list local_user_list) enable-all
Enables all user accounts in the specified list.
#(config local-user-list local_user_list) exit
Exits configure local-user-list mode and returns to configure mode.
#(config local-user-list local_user_list) group clear
Clears all groups from the list. The users remain but do not belong to any groups.
#(config local-user-list local_user_list) group create group_name
Creates the specified group in the local user list.
#(config local-user-list local_user_list) group delete group_name [force]
Deletes the specified group in the local user list.
#(config local-user-list local_user_list) lockout-duration seconds
The length of time a user account is locked out after too many failed password attempts. The default is
3600
Example
#(config) security local-user-list edit testlul
#(config local-user-list testlul) user create testuser
ok
#(config local-user-list testlul) user edit testuser
#(config local-user-list testlul testuser) enable
ok
#(config local-user-list testlul testuser) exit
#(config local-user-list testlul) exit
#(config)
Synopsis
Manages the automatic logging out of a user and sets the name of realm in the management console
challenge.
Syntax
#(config) security management [subcommands]
Subcommands
#(config) security management auto-logout-timeout seconds
Specifies the length of a management console session before the administrator is required to re-enter
credentials. The default is 900 seconds (15 minutes). Acceptable values are between 300 and 86400
seconds (5 minutes to 24 hours).
#(config) security management display-realm realm_name
Specifies the realm to display in the management console challenge. The default value is the IP address
of the SG appliance.
#(config) security management no auto-logout-timeout
Disables the automatic session logout.
#(config) security management no display-realm
Resets the display realm to be the IP address of the SG appliance.
Example
#(config) security management auto-logout-timeout seconds
Synopsis
Allows you to configure and manage Novell SSO realms.
Syntax
#(config) security novell-sso [subcommands]
Subcommands
#(config) security novell-sso create-realm realm_name
Creates the specified Novell SSO realm.
#(config) security novell-sso delete-realm realm_name
Deletes the specified Novell SSO realm.
#(config) security novell-sso edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security novell-sso view [realm_name]
Displays the configuration of all Novell SSO realms or just the configuration for realm_name if
specified.
Submodes
#(config) security novell-sso edit-realm realm_name
This changes the prompt to:
#(config novell-sso realm_name)
Commands found in this submode include:
SGOS#(config novell-sso realm_name) alternate-agent {host hostname | port
port_number}
Specifies the alternate agent hostname and port number.
SGOS#(config novell-sso realm_name) authorization {realm-name
authorization-realm-name | username username | no {authorization-realm-name |
username} | self}
Specifies the realm name, which can be self, and username for authorization. No clears the realm and
username.
SGOS#(config novell-sso realm_name) cookie {persistent {disable | enable}|
verify-ip {disable | enable}}
Specifies whether to enable persistent or session cookies, and whether to verify the IP address of the
cookie.
SGOS#(config novell-sso realm_name) exit
Leaves the novell-sso edit-realm mode.
SGOS#(config novell-sso realm_name) full-search {day-of-week | time-of-day}
Specifies the day of the week for full searches to occurs and the time of the day (UTC time) to search.
SGOS#(config novell-sso realm_name) inactivity-timeout seconds
Specifies the amount of time a session can be inactive before being logged out.
SGOS#(config novell-sso realm_name) ldap monitor-server {add LDAP_host [LDAP_port]|
clear | remove LDAP_host [LDAP_port]}
Add an LDAP host to list of servers to be monitored, clear the list, or remove a specific LDAP host from
the list of servers to be monitored.
Synopsis
Sets the console password to the password specified.
Syntax
#(config) security password “password”
#(config) security password hashed-password hashed_password
Subcommands
#(config) security password “password”
Note that the password must be in quotes. This is the password required to enter enable mode from the
CLI when using console credentials, the serial console, or RSA SSH.
#(config) security hashed-password hashed_password
The password in hashed format. You can either hash the password prior to entering it, or you can allow
the SG appliance to hash the password.
Example
#(config) security password “good2test”
Synopsis
Sets various display settings.
Syntax
#(config) security password-display [subcommands]
Subcommands
#(config) security password-display {encrypted | none}
Specifies the format to display passwords in show config output. Specify encrypted to display
encrypted passwords. Specify none to display no passwords.
#(config) security password-display keyring
Specifies the keyring to use for password encryption.
#(config) security password-display view
Displays the current password display settings.
Example
#(config) security password-display view
Password display mode: Encrypted
Password encryption keyring: configuration-passwords-key
Synopsis
Allows you to create and manage policy-substitution realms.
Syntax
#(config) security polity-substitution [subcommands]
Subcommands
#(config) security polity-substitution create-realm realm_name
Creates the specified policy-substitution realm
#(config) security polity-substitution delete-realm realm_name
Deletes the specified policy-substitution realm.
#(config) security polity-substitution edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security polity-substitution view [realm_name]
Displays the configuration of all policy-substitution realms or just the configuration for realm_name if
specified.
Submodes
#(config) security policy-substitution edit-realm realm_name
This changes the prompt to:
#(config policy-substitution realm_name)
Commands found in this submode include:
#(config policy-substitution realm_name) authorization-realm-name realm_name
This option is only required if you are associating an authorization realm with the Policy Substitution
realm.
#(config policy-substitution realm_name) cookie {persistent {disable | enable}|
verify-ip {disable | enable}}
Specifies whether to enable persistent or session cookies, and whether to verify the IP address of the
cookie.
#(config policy-substitution realm_name) exit
Leaves the windows-sso edit-realm mode.
#(config policy-substitution realm_name) full-username construction_rule
The full username as created through policy substitutions. The construction rule is made up any of the
substitutions whose values are available at client logon, listed in Appendix D, “CPL Substitutions,” in
Volume 10: Content Policy Language Guide.
Note: The username and full username attributes are character strings that contain policy
substitutions. When authentication is required for the transaction, these character strings are
processed by the policy substitution mechanism, using the current transaction as input. The
resulting string is stored in the user object in the transaction, and becomes the user’s identity.
To create full usernames for various uses in Policy Substitution realms, refer to Volume 10:
Content Policy Language Guide.
#(config policy-substitution realm_name) inactivity-timeout seconds
Specifies the amount of time a session can be inactive before being logged out.
#(config policy-substitution realm_name) no authorization-realm-name
Clears the authorization realm name.
#(config policy-substitution realm_name) refresh-time {authorization-refresh
seconds | surrogate-refresh seconds}
Sets the refresh time for authorization and surrogates.
#(config policy-substitution realm_name) rename new_realm_name
Renames this realm to new_realm_name.
#(config policy-substitution realm_name) username construction_rule
The username as created through policy substitutions. Note that the username is only required if you are
using an authorization realm. The construction rule is made up any of the policy substitutions whose
values are available at client logon, listed in Appendix D, “CPL Substitutions,” in Volume 10: Content
Policy Language Guide.
Note: The username and full username attributes are character strings that contain policy
substitutions. When authentication is required for the transaction, these character strings are
processed by the policy substitution mechanism, using the current transaction as input. The
resulting string is stored in the user object in the transaction, and becomes the user’s identity.
To create usernames for the various uses of Policy Substitution realms, refer to Volume 10:
Content Policy Language Guide
#(config policy-substitution realm_name) view
Displays this realm’s configuration.
#(config policy-substitution realm_name) virtual-url url
Specifies the virtual URL to use for this realm. If no URL is specified the global transparent proxy virtual URL
is used.
Example
#(config) security policy-substitution edit-realm PS1
#(config policy-substitution PS1) authorization-realm-name LDAP1
#(config policy-substitution PS1) username $(netbios.messenger-username)
#(config policy-substitution PS1) full-username
cn=$(netbios.messenger-username),cn=users,dc=$(netbios.computer-domain),
dc=company,dc=com
Synopsis
Allows you to create and manage RADIUS realms.
Syntax
#(config) security radius [subcommands]
Subcommands
#(config) security radius create-realm realm_name
Creates the specified RADIUS realm
#(config) security radius delete-realm realm_name
Deletes the specified RADIUS realm.
#(config) security radius edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security radius view [realm_name]
Displays the configuration of all RADIUS realms or just the configuration for realm_name if specified.
Submodes
#(config) security radius edit-realm realm_name
This changes the prompt to:
#(config radius realm_name)
Commands found in this submode include:
#(config radius realm_name) alternate-server encrypted-secret encrypted_secret
Specifies the alternate server secret in encrypted format. Note that you must create the encrypted secret
before executing the host [port] command.
#(config radius realm_name) alternate-server host [port]
Specifies the alternate server host and port.
#(config radius realm_name) alternate-server secret secret
Specifies the alternate server secret. Note that you must create the secret before executing the host
[port] command
#(config radius realm_name) case-sensitive {disable | enable}
Specifies whether or not the RADIUS server is case-sensitive.
standard charset names for encodings commonly supported by Web browsers can be used. The default is
Unicode:UTF8.
One list of standard charset names is found at
http://www.iana.org/assignments/character-sets.
#(config radius realm_name) view
Displays this realm’s configuration.
#(config radius realm_name) virtual-url url
Specifies the virtual URL to use for this realm. If no URL is specified the global transparent proxy virtual
URL is used.
Example
#(config) security radius edit-realm testradius
#(config radius testradius) server-retry 8
ok
#(config radius testradius) spoof-authentication proxy
ok
#(config radius testradius) exit
Synopsis
Used with authentication forms to store requests.
Syntax
#(config) security request-management [subcommands]
Subcommands
#(config) security request-management allow-redirects {disable | enable}
Specifies whether to allow redirects. The default is disable.
#(config) security request-management expiry-time seconds
Sets the amount of time before the stored request expires. The default is 300 seconds (five minutes).
#(config) security request-management max-size megabytes
Sets the maximum POST request size during authentication. The default is 50 megabytes.
#(config) security request-management verify-ip {disable | enable}
Enables or disables the verify-ip option. The default is to enable the SG appliance to verify the IP address
against the original request.
Example
#(config) security request-storage max-size megabytes
#(config) security request-storage expiry-time seconds
#(config) security request-storage verify-ip enable | disable
#(config) security request-storage allow-redirects enable | disable
Synopsis
Allows you to create and manage sequence realms.
Syntax
#(config) security sequence [subcommands]
Subcommands
#(config) security sequence create-realm realm_name
Creates the specified sequence realm
#(config) security sequence delete-realm realm_name
Deletes the specified sequence realm.
#(config) security sequence edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security sequence view [realm_name]
Displays the configuration of all sequence realms or just the configuration for realm_name if specified.
#(config) security sequence edit-realm realm_sequence_name
This changes the prompt to:
#(config sequence realm_sequence_name)
Submodes
Commands available in this submode include:
#(config sequence realm_sequence_name) display-name display_name
Specifies the display name for this realm.
#(config sequence realm_sequence_name) exit
Exits configure sequence-realm mode and returns to configure mode.
#(config sequence realm_sequence_name) IWA-only-once {disable | enable}
Specifies whether or not to challenge for credentials for the IWA realm one or multiple times.
#(config sequence realm_sequence_name) realm {add | demote | promote | remove}
{realm_name | clear}
Adds/demotes/promotes/removes a realm from the realm sequence, or clears all realms from the realm
sequence.
#(config sequence realm_sequence_name) rename new_realm_name
Renames this realm to new_realm_sequence_name.
#(config sequence realm_sequence_name) try-next-realm-on-error {disable | enable}
Use this command to specify that the next realm on the list should be attempted if
authentication in the previous realm has failed with a permitted error. The default value is to
not attempt the next realm and fall out of the sequence.
#(config sequence realm_sequence_name) view
Displays this realm’s configuration.
Example
#(config) security sequence edit-realm testsequence
#(config sequence testsequence) IWA-only-once disable
ok
#(config sequence testsequence) realm clear
ok
#(config sequence testsequence) exit
Note: Each (active) SiteMinder realm on the SG appliance should reference a different agent on the
Policy Server.
Configuration of the SG’s realm must be coordinated with configuration of the SiteMinder policy
server. Each must be configured to be aware of the other. In addition, certain SiteMinder responses
must be configured so that BCAAA gets the information the SG appliance needs.
Synopsis
Allows you to create and manage SiteMinder realms.
Syntax
#(config) security siteminder [subcommands]
Subcommands
#(config) security siteminder create-realm realm_name
Creates the specified SiteMinder realm
#(config) security siteminder delete-realm realm_name
Deletes the specified SiteMinder realm.
#(config) security siteminder edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security siteminder view [realm_name]
Displays the configuration of all SiteMinder realms or just the configuration for realm_name if
specified.
Submodes
#(config) security siteminder edit-realm realm_name
This changes the prompt to:
#(config siteminder realm_name)
Commands in this submode include:
#(config siteminder realm_name) add-header-responses {enable | disable}
Enable if your Web applications need information from the SiteMinder policy server responses.
#(config siteminder realm_name) alternate-agent agent_name
Specifies the alternate agent.
#(config siteminder realm_name) alternate-agent encrypted-secret
encrypted-shared-secret
Specifies the alternate agent secret in encrypted format.
#(config siteminder realm_name) alternate-agent host
The host ID or the IP address of the system that contains the alternate agent.
#(config siteminder realm_name) alternate-agent port
The port where the agent listens.
#(config siteminder realm_name) alternate-agent shared-secret secret
Specifies the alternate agent secret.
#(config siteminder realm_name) alternate-agent always-redirect-offbox
Enables or disables SSO.
#(config siteminder realm_name) always-redirect-offbox {enable | disable}
The SG appliance realm can be configured to redirect to an off-box authentication service
always. The URL of the service is configured in the scheme definition on the SiteMinder policy
server. The SG realm is then configured with always-redirect-offbox enabled.
#(config siteminder realm_name) case-sensitive {enable | disable}
Specifies whether the SiteMinder server is case-sensitive.
#(config siteminder realm_name) cookie {persistent {enable | disable} | verify-ip
{enable | disable}
Specifies whether to enable persistent or session cookies, and whether to verify the IP address of the
cookie.
#(config siteminder realm_name) display-name display_name
Specifies the display name for this realm.
#(config siteminder realm_name) exit
Exits configure siteminder-realm mode and returns to configure mode.
#(config siteminder realm_name) inactivity-timeout seconds
Specifies the amount of time a session can be inactive before being logged out.
#(config siteminder realm_name) log-out {challenge {enable | disable} |
display-time seconds}
Allows you to challenge the user after log out and define the log out page display time.
#(config siteminder realm_name) no alternate-agent
Clears the alternate agent configuration.
#(config siteminder realm_name) primary-agent agent_name
Specifies the primary agent.
#(config siteminder realm_name) primary-agent encrypted-secret
encrypted-shared-secret
Specifies the primary agent secret in encrypted format.
Example
#(config) security siteminder edit-realm test2
#(config siteminder test2) server-mode round-robin
ok
#(config siteminder test2) ssl enable
ok
#(config siteminder test2) exit
Synopsis
Configures authentication method for transparent proxies
Syntax
#(config) security transparent-proxy-auth [subcommands]
Subcommands
#(config) security transparent-proxy-auth method {ip | cookie}
Specifies whether to use IP or cookie surrogate credentials.
Example
#(config) security transparent-proxy-auth method cookie
Synopsis
Allows administrators to manage user log ins, logouts and refresh data.
Syntax
#(config) security users
This changes the prompt to:
#(config users) [subcommands]
Subcommands
#(config users) authorization-refresh {ip-addresses prefix [realm_name] | realms
[realm_name]| users glob_user_name [realm_name]}
Refreshes authorization data for the specified IP address, realm (or all realms), or user.
The IP address subnet notation is based on Classless Inter-Domain_Routing (CIDR):
• 1.2.3.4 : the IP address 1.2.3.4
• 1.2.3.0/24: the subnet 1.2.3.0 with netmask 255.255.255.0
The username pattern is a glob-based pattern, supporting three operators:
• '*' : match zero or more characters
• '?' : match exactly one character
• '[x-y]': match any character in the character range from 'x' to 'y'
#(config users) credentials-refresh {ip-addresses prefix [realm_name] | realms
[realm_name]| users glob_user_name [realm_name]}
Refreshes credential data for the specified IP address, realm (or all realms), or user.
#(config users) log-out {ip-addresses prefix [realm_name] | realms [realm_name]|
users glob_user_name [realm_name]}
Logs out the specified IP address, realm (or all realms), or user.
#(config users) surrogates-refresh {ip-addresses prefix [realm_name] | realms
[realm_name]| users glob_user_name [realm_name]}
Refreshes surrogate data for the specified IP address, realm (or all realms), or user.
#(config users) view detailed {ip-addresses prefix [realm_name] | realms
[realm_name]| users glob_user_name [realm_name]}
See a detailed view of users, sorted by IP address, realm, or username.
#(config users) view ip-addresses prefix [realm_name] | realms [realm_name] | users
glob_user_name [realm_name]}
See all logged-in users sorted by IP address, realm, or username.
Example
#(config) security users
#(config users) surrogates-refresh ip-addresses 10.25.36.0/24
Synopsis
Sets the console username.
Syntax
#(config) security username name
Example
#(config) security username QATest
#(config windows-sso)
In a Windows SSO realm, the client is never challenged for authentication. Instead, the BCAAA agent
collects information about the current logged on user from the domain controller and/or by querying
the client machine. Then the IP address of an incoming client request is mapped to a user identity in
the domain. If authorization information is also needed, then another realm (LDAP or local) must be
created.
Synopsis
Allows you to create and manage Windows SSO realms.
Syntax
#(config) security windows-sso [subcommands]
Subcommands
#(config) security windows-sso create-realm realm_name
Creates the specified Windows SSO realm.
#(config) security windows-sso edit-realm realm_name
Changes the prompt to allow configuration for the specified realm_name.
SGOS#(config windows-sso realm_name) alternate-agent {host hostname | port
port_number}
Specifies the alternate agent hostname and port number.
SGOS#(config windows-sso realm_name) authorization {realm-name
authorization-realm-name | username username | no
{authorization-realm-name | username} | self}
Specifies the realm name, which can be self, and username for authorization. No clears the realm
and username.
SGOS#(config windows-sso realm_name) cookie {persistent {disable | enable}|
verify-ip {disable | enable}}
Specifies whether to enable persistent or session cookies, and whether to verify the IP address of the
cookie.
SGOS#(config windows-sso realm_name) exit
Leaves the windows-sso edit-realm mode.
SGOS#(config windows-sso realm_name) inactivity-timeout seconds
Specifies the amount of time a session can be inactive before being logged out.
SGOS#(config windows-sso realm_name) no alternate-agent
Removes the alternate agent.
SGOS#(config windows-sso realm_name) primary-agent {host hostname | port
port_number}
Specifies the primary agent hostname and port number.
SGOS#(config windows-sso realm_name) refresh-time {authorization-refresh
seconds | surrogate-refresh seconds}
Sets the refresh time for authorization and surrogates.
SGOS#(config windows-sso realm_name) rename new_realm_name
Renames the current realm to new_realm_name.
SGOS#(config windows-sso realm_name) ssl {enable | disable}
Enables or disables SSL between the SG appliance and the BCAAA service.
Example
SGOS#(config) security windows-sso edit-realm test2
SGOS#(config windows-sso test2) ssotype query-client-dc
ok
SGOS#(config windows-sso test2) exit
Synopsis
Allows you to configure and manage XML realms.
Syntax
#(config) security xml [subcommands]
Subcommands
#(config) security xml create-realm realm_name
Creates the specified XML realm
#(config) security xml delete-realm realm_name
Deletes the specified XML realm.
#(config) security xml edit-realm realm_name
Changes the prompt. See Submodes for details.
#(config) security xml view [realm_name]
Displays the configuration of all XML realms or just the configuration for realm_name if specified.
Submodes
#(config) security xml edit-realm realm_name
This changes the prompt to:
#(config xml realm_name)
Commands in the xml realm_name mode:
#(config xml realm_name) alternate-responder {host | port}
Specifies the alternate responder host and port.
#(config xml realm_name) alternate-responder path {authenticate
authenticate_path | authorize authorize_path}
Specifies the alternate responder path for authentication and authorization requests.
#(config xml realm_name) authorization {default-group-name group-name | username
use-full-username | realm {none | username | self}}
Specifies the default group name, username, and realm for authorization.
#(config xml realm_name) connections count
Specifies the number of connections to the responder.
Example
#(config) security xml edit-realm xml14
#(config xml xml14) display-name
ok
#(config xml xml14) spoof-authentication origin
ok
#(config xml xml14) exit
#(config) session-monitor
Synopsis
Use this command to configure options to monitor RADIUS accounting messages and to maintain a
session table based on the information in these messages.
Syntax
#(config) session-monitor
This changes the prompt to:
#(config session-monitor)
Subcommands
#(config session-monitor) cluster disable
Disables cluster support.
#(config session-monitor) cluster enable
Enables cluster support. The group address must be set before the cluster can be enabled.
#(config session-monitor) cluster grace-period seconds
Set the time to keep session transactions in memory while waiting for slave logins. This can be set to
allow session table synchronization to occur after the synchronization-delay has expired. The default is
30 seconds; the range is 0 to 2^31-1 seconds.
#(config session-monitor) cluster [no] group-address IP_Address
Set or clear (the default) the failover group IP address. This must be an existing failover group address.
#(config session-monitor) cluster port port
Set the TCP/IP port for the session replication control. The default is 55555.
#(config session-monitor) cluster synchronization-delay seconds
Set the maximum time to wait for session table synchronization. The default is zero; the range is from 0
to 2 ^31 -1 seconds. During this time evaluation of $(session.username) is delayed, so proxy traffic
might also be delayed.
#(config session-monitor) disable
Disable (the default) session monitoring.
#(config session-monitor) enable
Enable session monitoring.
#(config session-monitor) max-entries integer
The maximum number of entries in the session table. The default is 500,000; the range is from 1 to
2,000,000. If the table reaches the maximum, additional START messages are ignored.
#(config session-monitor) radius acct-listen-port port
The port number where the SG appliance listens for accounting messages.
#(config session-monitor) radius authentication {disable | enable}
Enable or disable (the default) the authentication of RADIUS messages using the shared secret. Note that
the shared secret must be configured before authentication is enabled.
#(config session-monitor) radius encrypted-shared-secret encrypted-secret
Specify the shared secret (in encrypted form) used for RADIUS protocol authentication. The secret is
decrypted using the configuration-passwords-key.
#(config session-monitor) radius no shared-secret
Clears the shared secret used for RADIUS protocol authentication.
#(config session-monitor) radius respond {disable | enable}
Enable (the default) or disable generation of RADIUS responses.
Example
SGOS#(config) session-monitor
SGOS#(config session-monitor) view
General:
Status: disabled
Entry timeout: 120 minutes
Maximum entries: 500000
Cluster support: disabled
Cluster port: 55555
Cluster group address: none
Synchronization delay: 0
Synchronization grace period: 30
Accounting protocol: radius
Radius accounting:
Listen ports:
Accounting: 1813
Responses: Enabled
Authentication: Disabled
Shared secret: ************
#(config) sg-client
Synopsis
Use this command to configure the Client Manager and client configuration options for the SG Client.
Syntax
#(config) sg-client
This changes the prompt to:
#(config sg-client)
Subcommands
#(config sg-client) enable
Enable this appliance as the Client Manager. You can have only one Client Manager in your ADN
network.
Note: Before you can enable an appliance to be the Client Manager, you must configure the
ADN manager clients will use. If you try to enable the Client Manager before you configure an
ADN manager for clients, the following error displays: The ADN primary manager must be
set prior to enabling the SG Client Manager. To set the clients’ ADN manager, see
“#config (sg-client adn)” on page 312.
Note: Blue Coat recommends you enter the fully-qualified host name. If you enter either an
unqualified host name or IP address and change it later, connections to all currently-connected
clients are dropped.
Note: The cache will always leave at least 1GB free on the system root. For more information,
see the chapter on configuring the SG Client in Volume 5: Advanced Networking.
#(config sg-client) software-upgrade-path url
Sets the URL used to upload updated SG Client software to the Client Manager so it can make the latest
SG Client software available to update or to install on client machines.
Important: After you update the Client Manager, whenever users connect using the SG Client,
they will be required to update the SG Client software.
Upload the SG Client software from a URL in the following format:
https://host:port/sgclient/SGClient.car
For example,
https://mysg.example.com:8004/sgclient/SGClient.car
After you set the path from which to load the updates, see # load sg-client-software
Loads the SG Client software to the Client Manager. To use this
command, you must have previously defined an upload location using
#(config) sg-client on page 309. Messages display as the software
loads. on page 57.
#(config sg-client) tcp-window-size bytes
Sets the number of bytes allowed before acknowledgement (the value must be between 8192 and
4194304). If you know the bandwidth and roundtrip delay, the TCP window size you should is us
approximately 2 * bandwidth * delay. For example, if the bandwidth of the link is 8 Mbits/sec and
the round-trip delay is 0.75 seconds:
TCP window size = 2 * 8 Mbits/sec * 0.75 sec = 12 Mbits = 1.5 Mbytes
The setting in this example would be 1500000 bytes. This number goes up as either bandwidth
or delay increases, and goes down as they decrease. Because the bandwidth and delay for
mobile users can vary, Blue Coat recommends you test mobile client performance in a
controlled environment before deciding on a value to use in production.
#(config sg-client) update-interval minutes
Frequency clients check with the Client Manager for updated SG Client software. Default is 120.
#(config sg-client) view
View current Client Manager settings.
Example
SGOS#(config) client-manager host enable
SGOS#(config) client-manager host from-client-address
SGOS#(config) software-upgrade-path
https://mysg.example.com:8004/sgclient/SGClient.car
Synopsis
Configure ADN manager and ADN rules settings for SG Clients.
Syntax
#(config) sg-client
This changes the prompt to:
#(config sg-client)
#(config sg-client) adn
This changes the prompt to:
#(config sg-client adn)
Subcommands
#(config sg-client adn) primary-manager ip-address
The IP address of the primary ADN manager. The ADN manager keeps track of and advertises the
routes of the appliances it knows about. You must specify a primary manager.
The SG Client obtains the routing table from the ADN manager.
#(config sg-client adn) backup-manager ip-address
The IP address of the backup ADN manager. Configuring a backup ADN manager is optional but
recommended.
If the ADN manager becomes unavailable for any reason, the backup ADN manager takes
over the task of advertising routes to all ADN nodes, such as the SG Client.
#(config sg-client adn) manager-port port
ADN manager and backup manager plain listen port. (To use the SG Client in your ADN network, the
ADN manager’s listening mode must be configured for Plain Only, Plain Read-Only, or Both.)
#(config sg-client adn) port-list {exclude-ports | include-ports}
Determines whether you will use the include ports list or exclude ports list.
#(config sg-client adn) {exclude-ports | include-ports} {port-list | port-range}
Determines which TCP ports to exclude or include in ADN tunnels. Assuming clients using the SG
Client software can connect to an ADN peer that can optimize traffic to the destination IP address, this
setting determines ports the clients can use (or not use).
For example, you can exclude ports or port ranges because traffic coming from those ports has
already been encrypted.
For example, the following command excludes traffic from ports 22 and 443 from being routed
through ADN:
#(config sg-client adn) exclude-ports 22,443
Valid values: Comma-separated list of ports and port ranges (no spaces, separated by a dash
character).
#(config sg-client adn) exclude-subnets
Configure the subnets excluded from ADN acceleration
#(config sg-client adn exclude-subnets) {add | remove} subnet_prefix[/prefix
length]
Adds or removes subnets from the excluded subnets list, which is the list of subnets not included in
ADN tunnels. Use a comma-separated list of IP addresses and subnets in CIDR notation.
For example, the following command excludes traffic from the IP address 128.211.168.0
and subnet 255.255.255.0 from being routed through the ADN tunnel:
#(config sg-client adn exclude-subnets) add 128.211.168.0/24
#(config sg-client adn exclude-subnets) clear
Removes all subnets from the current excluded subnet list. In other words, traffic from all IP
addresses and subnets will be routed through the ADN tunnel.
#(config sg-client adn exclude-subnets) exit
Exits the exclude-subnets submode.
#(config sg-client adn exclude-subnets) view
View the list of excluded subnets.
#(config sg-client adn) exit
Exit the adn submode.
Example
#(config sg-client adn) exclude-ports 22,88,443,993,995,1352,1494,1677,3389,5900
Synopsis
Configure CIFS settings for SG Clients.
Syntax
#(config) sg-client
This changes the prompt to:
#(config sg-client)
#(config sg-client) cifs
This changes the prompt to:
#(config sg-client cifs)
Subcommands
#(config sg-client cifs) directory-cache-time seconds
Number of seconds for directory listings to remain in the cache. Default is 30.
#(config sg-client cifs) {disable | enable}
Disable or enable CIFS acceleration. CIFS acceleration is enabled by default.
#(config sg-client cifs) exit
Exit the sg-client cifs command.
#(config sg-client cifs) write-back {full | none}
Determines whether or not users can continue sending data to the appliance while the appliance is
writing data on the back end.
• full enables write-back, which in turn makes the appliance appear to the user as a file server; in
other words, the appliance constantly sends approval to the client and allows the client to send data
while the back end takes advantage of the compressed TCP connection.
• none disables write-back. Disabling write-back can introduce substantial latency as clients send
data to the appliance and wait for acknowledgement before sending more data.
One reason to set this option to none is the risk of data loss if the link from the branch to the
core server fails. There is no way to recover queued data if such a link failure occurs.
#(config sg-client cifs) view
View client CIFS settings.
Example
SGOS#(config sg-client cifs) enable
SGOS#(config sg-client cifs) write-back full
#(config) shell
Synopsis
Use this command to configure options for the shell.
#(config) shell max-connections
Maximum number of shell connections. Allowed values are between 1 and 65535.
#(config) shell no
Disables the prompt, realm-banner, and welcome-banner strings.
#(config) shell prompt
Sets the prompt that the user sees in the shell. If the string includes white space, enclose the string in
quotes.
#(config) shell realm-banner
Sets the realm banner that the user sees when logging into a realm through the shell. If the string
includes white space, enclose the string in quotes.
#(config) shell welcome-banner
Sets the welcome banner that the users sees when logging into the shell. If the string includes white
space, enclose the string in quotes.
Example
SGOS#(config) shell prompt "Telnet Shell >"
ok
SGOS#(config) shell welcome-banner "Welcome to the Blue Coat Telnet Shell"
ok
#(config) show
❐ # show on page 72.
#(config) snmp
Synopsis
Use this command to set SNMP (Simple Network Management Protocol) options for the SG appliance.
The SG appliance can be viewed using an SNMP management station. The SG appliance supports
MIB-2 (RFC 1213).
Syntax
#(config) snmp
This changes the prompt to:
#(config snmp)
Subcommands
#(config snmp) authorize-traps
Enables SNMP authorize traps.
#(config snmp) disable
Disables SNMP for the SG appliance.
#(config snmp) director-trap-address director_ip director_ID_string
Enables Director to receive SNMP traps from the SG appliance.
#(config snmp) enable
Enables SNMP for the SG appliance.
#(config snmp) encrypted-read-community encrypted_password
Specifies encrypted read community string.
#(config snmp) encrypted-trap-community encrypted_password
Specifies encrypted trap community string.
#(config snmp) encrypted-write-community encrypted_password
Specifies encrypted write community string.
#(config snmp) exit
Exits configure snmp mode and returns to configure mode.
#(config snmp) no authorize-traps
Disables the current authorize traps settings.
#(config snmp) no sys-contact
Disables the current system contact settings.
#(config snmp) no sys-location
Disables the current system location settings.
#(config snmp) no trap-address {1 | 2 | 3}
Disables the current trap address settings (for trap address 1, 2, or 3).
#(config snmp) read-community password
Sets the read community password or encrypted-password.
#(confi