Chapter 11. Overall Layout (for writers)

When originally working on this document, I (Oskar Pearson) put together an overall structure text file, to help me decide where all the info would go, and how we would introduce the reader to squid in a structured, useful fashion. You are welcome to change the ordering, and add and remove from it as you will. The numbers below do not directly match with the final structure, nor do the numbers used match the numbers used in the free-release version of the document. The "X pages" values may be freely ignored; they were for the original proposal for the (paper) book.

You are welcome to change the overall document structure as you wish, and to add new sections as you will. If you do, though, please bear in mind that someone coming into the editing process may benefit from having an "overall structure" in which to place their contribution. If you alter the document structure, please change this section of the document to match. If you find differences between the flow of concepts in this area and the text (entirely possible), you should probably ignore this section, and (preferably) update this to match the real document.

I) Installation
    When installing Squid the first step is to get it up and running
    on a test machine. This allows the user to get familiar with
    Squid's basic setup and feel that they are progressing towards
    something tangible (rather than slogging through the whole
    book before actually getting Squid running). Only the very
    basics of the config file are going to be covered.

Chapter 1) Introduction to Squid terminology and technology
    1.1) What Squid is
    1.1.1) Why cache
    1.2) What Squid is not
    1.3) Supported Internet Server protocols
    1.4) Inter-Cache communication
    1.4.1) Hierarchy terminology
    1.4.2) Inter-Cache protocols
    1.5) Operating Systems

Chapter 2)
    2.1) Advanced Planning:
    2.1.1) Hardware requirements:
    2.2) Operating System:
    2.2.1) Use the OS that you have experience in
    2.2.2) All examples will be generic.
    2.2.3) need a compiler.
    2.3) System setup
    2.3.1) The default Squid directory structure
    2.3.2) Creation of the squid user and group
    (includes permissions etc)
    2.4) Working with precompiled binaries
    2.4.1) precompiled binaries
    2.4.2) Trusted sources of binaries
    2.5) Source compilation
    2.5.1) Recommended compilation tools
    2.5.2) Compilation configuration options
    2.5.3) compilation: make all; make install

Chapter 3) Introduction to the configuration file:
    Only the very basics of the config file are covered. This
    allows people to get Squid running as soon as they can.

    3.1) note on RCS
    3.2) The configuration file:
    3.2.1) HTTP port
    3.2.2) Communicating with other proxy servers
    3.2.2.1) Basic cache hierarchy terminology
    3.2.2.2) Proxy-level firewall
    3.2.2.3) Packet-filter firewall
    3.2.2.4) Source/Destination IP and Port pairs
    3.2.3) Cache Store location
    3.2.3.1) Disk space allocation (? move to
    chapter1?)
    3.2.4) FTP login information
    3.2.5) acl, http_access
    3.2.5.1) create a basic acl that denies
   everything but one address range
    3.2.5.2) Intranet access with parents
    3.2.6) cache_mgr
    3.2.7) cache_effective_group

Chapter 4) Starting and Running Squid (15 pages)
    4.1) Running Squid for the first time
    4.1.1) Permissions
    - on each ~squid/* directory
    4.1.2) Creating cache directories
    4.1.2.1) Problems creating Swap Directories
    - problems:
    not root
    squid user id doesn't exist
    squid user doesn't have write to
    cache dir
    squid user doesn't have read/exec
    to a directory up the tree
    
    4.2) Running Squid
    3.2.1) What is expected in cache.log
    4.3) Testing the cache with the included client
    4.3.1) checking if Internet works
    4.3.2) checking if intranet works (if configured with a parent)
    4.3.3) Checking Access.log for hits vs misses
   Include basic fields
    4.4) Addition to startup files
    (? check NT ?)

Chapter 5) Client configuration: (24 pages)
    Include some screen shots of the configuration menus
    5.1) Basic client configuration.
    5.1.1) Netscape
    5.1.2) Internet Explorer
    5.1.3) Unix environment variables
    (Important for both lynx and for wget - for
    prefetching pages)
    5.2) Client cache-specific modifications
    5.3) Testing client access
    5.4) Setting clients to use LOCAL caches
 5.4.1) CARP
 5.4.2) Autoconfigs
 5.4.3) Future directions
    5.2.4.1) DNS destination selection based on 
    5.2.4.2) Roaming ability will help
    5.2.4.3) Transparency (see 11.1)

II) Integration
    By this point Squid should be installed with a minimum working
    environment.

    This section covers changing cache setup to suit the local network
    configuration.

    This section covers Access Control, Refresh patterns and Cache-peer
    relationships. These are the painful sections of the setup.

    This section also goes through the options in the config file
    that haven't been covered. This is essentially a 'reference
    guide' to the config options.

Chapter 6) ACLs: (38 pages)
    Each of these includes a short example that shows how
    they work. At the end of the Chapter there is a nice long
    complex ACL list that should suit almost everyone.

    6.1) Introduction to ACLs
    6.1.1) ACL lines vs Operator lines
    6.1.2) How decisions work
    6.2) Data specification:
    6.2.1) regular expressions
    6.2.2) IP address range specifications
    6.2.3) AS numbers
    6.2.4) putting the data in files
    6.3) types of acl lines:
 Works through all the acl types. (src, srcdomain, dst,
    dstdomain etc)
    - must include info on "no_cache", specifically
      for 3.2.5.2
    6.4) Delay classes 
    6.5) SNMP configuration
    6.5) The default acl set
    include info on why the SSL setup is the way that it is,
    and information on the echo/chargen ports

Chapter 7) Hierarchies: (42 pages)
    7.1) Inter-cache communication protocols
 How each one is suited to specific
 circumstances. Compatability notes
 (with other programs) are included.
    7.1.1) ICP
    7.1.2) Digests
    7.1.3) HTCP
    7.1.4) CARP
    7.2) Various types of hierarchy structures
 are covered:
     7.2.1) The Tree stucture
     7.2.2) Load balancing peer system
     7.2.3) True distributed system
    7.3) Configuring Squid to talk to other caches
    7.3.1) The cache_peer config option
   All options are covered with examples
    7.3.2) cache_peer_domain config option
    7.3.3) miss_access acl line

Chapter 8) Accelerator mode (11 pages)
    (? I haven't use accelerator mode - I am using Miguel a.l. Paraz's
       page in the Squid Documentation as a guide ?)
    8.1) Intro - why use this mode
    8.1.1) performance
    8.1.2) security
    8.2) Types of accelerator mode
    8.2.1) Virtual mode
    (note on security problems)
    8.2.2) Host header
    8.3) Options
    8.3.1) http_port
    8.3.2) httpd_accel_host
    8.3.3) httpd_accel_port
    8.3.4) httpd_accel_with_proxy
    8.3.5) httpd_accel_uses_host_header
    8.4) Reverse caching using accelerator mode on the return
 path of an International link
    See Transparency

Chapter 9) Transparency: (24 pages)
    9.1) TCP basics
    9.2) Operating System function
    9.3) Squid 'accept' destination sensing
    9.4) Special ACLs to stop loops
    9.5) FTP transparency problems
    9.6) Routing the actual TCP packets to Squid
    9.7) Changing hierarchies to work with transparency

Chapter 10) The config file and Squid options (48 pages)

    The options list doesn't really belong in section (I). I am,
    instead going to cover it here. Also cover the options to 'client'.

    This covers ALL the tags in the config file. Where
    the tag has been covered already it refers people to
    that section of the book.

    Arranged in alphabetical order.

III) Maintainence and Site-Specific Optimization
    Covers the further development of your cache setup. This covers
    both maintainence and specialized setups (like transparent caches)

Chapter 11) Refresh Patterns: (24 pages)
    11.1) distribution of file types
    (gifs vs jpg vs html)
    11.2) distribution of protocols
    11.3) Server-Sent Header fields
    11.3.1) Work through the types of headers
    11.3.2) meta-tags
    11.4) Client-Sent Header fields
    11.4.1) If-Modified-Since Requests
    11.4.2) Refresh button
    11.5) refresh_pattern tag
 First match selection. Describes order of
 checking each of the fields.

Chapter 12) Cache analysis (24 pages)
      This section covers disadvantages and advantages
      of the various types of cache performance/savings
      analysis systems
    12.1) access.log fields
    12.2) Simple Network Management Protocol (SNMP)
    configuring, access control, multiple servers,
    multiple agent configurations, understanding
    results. Shew!
    12.3) Cache-specific analysis using a squid analysis
  program
    12.4) The cachemgr.cgi script
    Using the output (eg LRU values)
    for deciding when to buy more disk space etc
    12.5) Using a cache-query-tool
    12.6) Using your results
    Graphing response times over the months, for example.

Chapter 13) Standby procedures: (15 pages)
    13.1) Hardware failure
    13.1.1) Standby machines
    13.1.2) DNS modification
    13.1.3) Automatic configuration
    13.2) Software failure
    13.3.1)
    We need lots of info on 'vmstat', 'iostat', strace -T,
    (and other stuff like that) here.
    cachemgr:
    Slowness: 
    queued DNS queries
    DNS response times
    queued username/password authentication
    requests
    page faults:
    vmstat
    13.2.2) Consistent crashing
    - filehandles
    - memory
    - all dnsservers busy
    - slow!
    - latency of local request,
      comparing with "client" through
      cache and without it.

Chapter 14) Future directions: (18 pages)
    14.1) Wide ranging use of Skycache
    14.2) Wide ranging use of transparency
    14.3) Very heavily used parents
  For example at Exchange Points
    14.4) compression between server and client - like the berkely
    thing...