Principles of Service Design¶

The success of a service depends on availability, speed, and scalability. Kate Matsudaira, author of “Building Scalable Web Architecture and Distributed Systems”, also emphasized these three principles.

Availability

A service must always be available. In the event of failure, ninety percent of users will move on to competitors. While there is no such thing as a perfect system, recovering from failures must be quick.

Speed

In business, time is money, and in e-commerce, high latency will lead to a drop in sales. For every 0.1 second of latency, there is a one percent decrease in revenue. 47 percent of Amazon.com customers want a website loaded on their screen within two seconds.

Scalability

Regardless of the number of users, the service must always be reliable. Scalability is the effort required to increase the system’s capacity to handle more load, and can also refer to how easy it is to add more storage or how many more transactions can be processed. Scalability in maintenance is also important: it should be easy to diagnose and understand problems and implement updates or fixes.

The service is most effective when all the principles can be upheld at the smallest possible cost. Cost is not limited to just money, but also includes time, effort, and training.

A successful service must grow, and when it does, it must be able to manage more clients and more content. However, as the system grows, it becomes harder to uphold these principles. What can be done to uphold these principles at the smallest possible cost?

The Growth of the Service¶

A test or pilot service generally begins with one or two servers, and when it begins to grow, the number of servers will increase accordingly. Content renewal must be meticulously carried out one server at a time. It may be a laborious task, but it is not an impossible one as of yet.

As the service begins to expand with more users and more accumulated data, managing each server one by one becomes even more difficult. At this point, high-cost storage (e.g. NAS, SAN, DAS) is introduced to collect all the data in one system. Expensive but reliable storage systems make content renewal easier, because servers can automatically acquire updated content from storage.

However, as the service sharply grows, the number of servers increases. More servers mean more data from storage, leading to data transfer overload. A new storage system that supports higher bandwidth can be even more expensive, so it’s questionable if one would want to invest in it.

A potential solution to the problem is synchronization. Getting all the data ready is impractical, so the storage system must be able to sort the content. Management is essential to achieve precise content control. Synchronization across a few servers may be easy, but the more servers and files to sync, the harder it becomes. Synchronization can become slower, harder, and even more unstable as the system expands.

Moreover, content is constantly changing. The more files there are to add or delete, the longer the synchronization time becomes. A larger-scale service inevitably requires a bigger and more complicated synchronization managing system. Any problems in the management system may eventually lead to total service failure.

A simpler method to quickly and flexibly deliver content to servers is necessary.

Service Scalability and Content Delivery¶

As shown in the figure below, a service can be broken down into two layers.

In the center is the storage layer, which manages data. Above it is the application layer, which implements the service logic and can also process content delivery for a small number of customers. In the beginning stages, the service can be set up with only the storage and application layers.

As the service grows, the total cost will change. In the beginning stages, the biggest expense is in logic development, while in the growth stages, the biggest expense is in data management in accordance with the number of users. However, as the service matures, the main concern becomes content delivery, making it a huge hurdle for service expansion. How can the exploding bandwidth be taken care of?

The Edge: The Delivery Layer¶

When the service reaches maturity, the burden of content delivery will increase exponentially. Shopping mall content numbers in the billions, and the video service content has long since begun to use terabytes. To expand a service, the scalability of content delivery must definitely be taken into account.

The edge layer is the outermost layer of the service in which clients will be able to experience speed and availability. No matter the circumstances, the content requested by the users must always be delivered to them. Broken images or unavailable pages on the user’s screen is fatal to the reputation of the service. By handling content delivery via the edge, there is less of a burden on the application and storage layers.

Having an easily and efficiently expandable edge layer removes the need to expand other high-cost layers. Meanwhile, expanding the storage layer or the application layer is a poor choice due to its high cost and low efficiency.

In that case, how does the STON Edge Server make content delivery quicker and easier?

The Behavior of the Edge Server: Caching¶

The scale of data delivery is proportional to the number of users and the size of content. The service can detect how many users are requesting what content most quickly within the edge layer. Because the bottom-up workflow from edge layer is the most efficient, the edge server implements caching behavior that responds on demand to the users’ requests, without any need for management systems. The procedure is as follows.

When the edge server receives its first content delivery request, it obtains the content from the storage layer and then transfers the content to the user. This transferred content is also saved in the edge server itself. On future requests, the saved content can immediately be delivered to the users from the edge server itself. The saved content will only be available during the preset Time To Live (TTL) period.

In this way, the edge server can handle a considerable amount of content. It can allow for quick mass distribution of data while minimizing the need to expand the application and storage layers. Any growing service should take the edge server into consideration.

The STON Edge Server is software that aims to provide an unrestricted and unconditional environment. The server is designed to provide maximum performance on any type of hardware platform.

CPU: Optimized for multi-core processors. Throughput is proportional to the number of CPU cores.

Memory: Larger memory allows for faster processing and cuts down on Disk I/O.

Disk: I/O is evenly distributed to cache more data.

NIC: Guaranteed bandwidth of either 4 Gbps NIC Bonding or 10 Gbps NIC.

The STON Edge Server supports powerful live monitoring and logging. The administrator can check the current service status in real time with statistics updated every second. The real-time statistics are offered in universal formats such as JSON, XML, and SNMP.

STON offers simple installation for the sake of administrators, because STON’s design principle is to be an edge server made with administrators in mind. An intuitive installation method is provided via the Web Management page. More detailed settings can be configured by editing only two XML files.

Benefits of the Edge Server¶

The benefits of the edge server are listed below.

• Provides simple and convenient service acceleration
• Shields the service origin from external access (Origin Shielding)
• Allows the other layers to concentrate on their fundamental roles

The advantages of adopting the edge server can be seen in the following application examples.

Gaming¶

Gaming services require a large amount of bandwidth. There are a variety of categories in gaming, from “masterpiece” games to casual games. Smartphone games have become especially popular, further diversifying the forms of services.

• High Bandwidth Throughput

  A universal method to acquire high bandwidth with a single server is bonding 1 Gbps NIC (Network Interface Controller). With this, up to 4 Gbps can be achieved. Recently, 10Gbps NICs have also become common.

  STON guarantees full bandwidth for both 4 Gbps NIC Bonding and 10 Gbps NIC.

• Max User Bandwidth Guaranteed

  Everyone wants to play games as soon as possible, so they will want to download their games as fast as possible. Users with fiber optic LAN may complain if their speed falls under 100 Mbps. As long as a server’s bandwidth isn’t physically exceeded, it must be able to guarantee maximum speed equally to every user.

  STON guarantees maximum transmission speed to all users.

• Processing Large Files

  Nowadays, a game with a file size of about 4 GB can’t even be considered a large game; there exist games with dozens of GB in file size. If the files are too large to cache in the server memory, critical service failure is likely. The worst-case scenario is when every user is each downloading a different part of a massive file from the server.

  STON caching has no limit to file size, and will always guarantee high performance by swapping between memory and disk when appropriate.

• Processing Range Requests

  As files to deliver are growing larger, the P2P solution, based on the grid delivery method, has become widely used. This solution shreds a single file into small pieces to send or receive, thus making a huge number of HTTP range requests from the server. Theoretically, ten thousand clients can all request different ranges from a 10 GB file. The service must be able to respond immediately, regardless of what is being requested. However, the size of the transferred data must not exceed the size of the original file.

  STON is loaded with a file system that is optimized for range requests. STON also guarantees faster responses via multi-download. It will not download a single unnecessary byte from the origin server.

E-commerce¶

In the case of online shopping malls, accessibility of the website is directly related to the amount of total sales. Recently, mobile shopping via smartphones has become just as common as the traditional PC-based online shopping. A service will face difficulty if it cannot handle not just various shopping environments but also an infinitely growing number of files.

• Numerous Small Files

  An expensive storage system is necessary when it comes to storing files that seem like they’re constantly increasing. However, because being economical is important to the edge server, this solution is not preferred. There could be a service that consists of a billion 1 KB files, and caching all of them is not possible. Therefore, a method that keeps hold of frequently requested files while minimizing load on the origin server is necessary.

  STON uses available memory and disk resources to their greatest capacity for caching. It manages the access frequency of all files in real time and removes older files based on the LRU (Least Recently Used) algorithm.

• Millions of Users

  An online shopping mall must be able to handle the requests of multiple users at once. There are times when bursts of website traffic can occur due to a sudden event. Servers must be able to withstand these bursts and remain stable after them.

  STON guarantees CPU scalability, with performance proportional to the number of resources. It can guarantee stability even during bursts using flexible HTTP keep-alive and socket handling.

• Responsiveness

  Pleasant online shopping experiences occur when pages load quickly and the customers don’t have to wait. If a page doesn’t load within three seconds, the user will most often move to a different site. Even though the main page is generally made up of about a hundred files, it must still load perfectly in a second.

  STON guarantees swift responses through real-time file indexing. Responsiveness is maximized by having seamless file replacement with no dependence on the origin server. Logs and statistics are offered for all HTTP responses (Time to First Byte, transaction completions) to detect declines in performance in real time.

• Page TTL

  The majority of users follow a route that goes from the main page, to the upper category page, to the lower category page, and then to the product details page. Each page must be different not just in their exposure frequencies but also in their refresh cycles. A smart method of caching and refreshing is necessary.

  STON can allocate separate TTLs to each URL. It also offers various refreshing methods such as Purge, Expire, ExpireAfter, and HardPurge to be used to fit the given situation.

Media¶

Exclusive media protocols are starting to lose their place, while the simple but powerful combination of HTTP and MP4 is gaining influence. Taking into consideration the variable connection statuses of mobile devices, HTTP-based streaming is likely to become the norm.

• Media Recognition

  Media files should no longer be seen as just one huge chunk of file. Bandwidth can be reduced and various additional functions can be linked only when the format of the media file is correctly recognized. If the server requires the entire file to determine its format, then during the time the server takes to acquire the file, the user will most likely quit waiting.

  STON supports the MP4, MP3, M4A, and FLV formats. As soon as the server starts downloading a media file, it prioritizes the sections required for HTTP pseudo-streaming.

• Media Header Reordering

  If the header is located at the end of the file, HTTP pseudo-streaming is unavailable. An exclusive media player would be necessary for these types of files, but this can make users easily frustrated.

  If the header is placed at the end after encoding an MP4 file, an additional action to move it to the front is necessary. STON provides the service of automatically moving the header to the front.

• Adjustable Bandwidth

  Not many users watch the entire video clip to the end. Therefore, an efficient streaming method would be to use only smallest amount of bandwidth necessary for smooth playback. Though the video may be the same, it can be watched in varying bitrates ranging from 360p to 1080p.

  STON uses bandwidth throttling to optimize the bandwidth used during media file delivery.

• Multi/Single Part Trimming

  Some preview/highlight/sharing services provide only a specific part of the file instead of the whole. It would be a waste of time and storage space to extract parts for every file. Furthermore, there are cases where the extracted part may be different for each user. Some media players also implement a skip function for segment playback.

  STON can trim a media file to extract parts that can be used as complete files themselves.

News / Forums¶

There are many points of interest for sites that have secured a large loyal user base. As these websites are where people of similar interests gather, users will stay on pages for long periods of time and exchanges will occur with vigor. The service patterns of these sites vary by their subjects and it is tricky to meet their service requirements.

• 304 Not Modified

  Because these users are loyal to the website, most files will already be cached in local storage. Therefore, checking for updates will be more frequent than actual file transfer.

  STON ensures that frequently accessed files are always kept in memory. Checking for updates can be processed immediately without waiting.

• Bypass

  There are a certain category of pages that cannot be cached, such as user-specific pages or pages with new posts or replies. Even in these cases, a single domain is usually delegated to a reverse proxy instead of separating it into multiple domains.

  STON elaborately classifies bypass targets based on various conditions. The server also maintains login sessions using the Origin Affinity and Private functions.

• Origin Shield

  Websites owned by individuals or small or mid-size businesses cannot afford expensive equipment, infrastructure, or labor force. Server failure can occur relatively frequently, and it is often uneconomical to try and improve server quality.

  STON will detect server overload or failure and automatically execute exclusion/recovery of the origin server. It will also extend TTL upon server failure and minimize dependence on the origin server.

• Image Processing

  The same image may need to be displayed in different ways depending on the user environment. Search results may display images as thumbnails, while news sites may watermark their images. Processing every image into a specific format is a waste of time, storage, and effort.

  STON‘s DIMS function can generate desired image formats from a single image using only URL calls.

File-based Server¶

The edge server is based on the reverse proxy structure. The fundamental concept of the reverse proxy is to copy/modify/manage files from the remote server to local storage. If STON can integrate with a service’s server, it can resolve both storage centralization and synchronization issues. This will also decrease service development time and improve service reliability, killing two birds with one stone.

• File I/O Support

  If an exclusive protocol is required, the server becomes subordinate to the corresponding module. Even the module was integrated with the server, if performance falls, it is dead weight. The stage between the module and the server must be reduced to a minimum.

  STON can adopt standard file I/O. Only a Linux Kernel (VFS) is placed between STON and the exclusive server to guarantee high performance.

• Web Server Integration

  Standard reverse proxies may be hard to implement if any special expansion modules are installed on standard web servers (Apache, Lighttpd, NginX). For example, it is hard for a file service or a payment service linked with DB/WAS to expand.

  If Apache’s DocumentRoot is assigned to STON, Apache will recognize STON as a physical disk and nothing will need to be configured.

• Wowza Integration

  Wowza is considered to be a standard in the media service field. However, Wowza’s HTTP caching function is not just inconvenient but also limited. In addition, other “exclusive”; protocols besides HTTP are fading away from the market.

  STON can be mounted as a local disk. Moreover, all functions, such as MP4 header conversion and trimming, are available.

• Resource Management

  A server that acquires back-end files and delivers them to front-end users will always have problems with file synchronization. Exclusive servers such as game or SNS servers have always had these issues during development. Because these servers must stay running for long periods of time without interruption, memory and disk use must be strictly controlled.

  STON can easily control memory and disk use. Even when STON is mounted on a disk, all other functions will work in the same manner, so complicated services can be configured with a minimal solution.

The following Korean services are actively making use of the above attributes to grow with STON.

Setting Up the Server¶

Generally, setting up a server means considering the CPU, memory, and disk. For example, if a service requires high performance on the level of 10 Gbps throughput, then each component must meet the requirements to reach the desired performance.

• CPU

  A CPU with at least four cores (quad-core) is recommended. Because STON gains scalability when it comes to multi-core CPUs, the per-second throughput increases with more cores. However, higher throughput does not necessarily mean higher traffic.

  

  The more clients there are, the more useful it is to have many CPUs.

  Transferring a 4 KB file around 260,000 times takes the same amount of bandwidth as transferring a 1 GB file once. The most important criterion in choosing a CPU is the number of parallel connections the service must make.

• Memory

  At least 4GB of memory is recommended to be used in memory indexing (see also Memory Structure). Content that is frequently accessed will always be stored in memory, but content that is not will have to be loaded from disk. As such, if there is a lot of content with a large spread (a long-tailed distribution), then the load on the disk will be higher and performance may decline. If disk I/O load is high because of the size of the content, regardless of the amount of content, then memory can simply be added to decrease the load.

• Disk

  At least three disks, including the OS, is recommended. As one would expect, more disks lead to better performance, as I/O load will be dispersed and more content can be cached.

  

  The OS and STON will always be installed on a disk separate from the content.

  In general, STON will be installed on the same disk as the OS. The log is also generally installed on the same disk. Because the log must record the service status in real time, it will always create write load.

  The STON disks will be used in the RAID 0 setting. The correlation between performance and RAID changes depending on the client service’s qualities. However, if file changes are infrequent and content size is much larger than physical memory, increasing read speed with RAID may be effective.

Setting Up the OS¶

In its most basic form, STON will operate normally on standard 64-bit Linux distributions (CentOS 6.2 or higher, Ubuntu 10.04 or higher), and does not require any particular package.

Installation¶

1. Download the latest version of STON.

   [root@localhost ~]# wget  http://foobar.com/ston/ston.2.0.0.rhel.2.6.32.x64.tar.gz
   --2014-06-17 13:29:14--  http://foobar.com/ston/ston.2.0.0.rhel.2.6.32.x64.tar.gz
   Resolving foobar.com... 192.168.0.14
   Connecting to foobar.com|192.168.0.14|:80... connected.
   HTTP request sent, awaiting response... 200 OK
   Length: 71340645 (68M) [application/x-gzip]
   Saving to: “ston.2.0.0.rhel.2.6.32.x64.tar.gz”
   
   100%[===============================================>] 71,340,645  42.9M/s   in 1.6s
   
   2014-06-17 13:29:15 (42.9 MB/s) - “ston.2.0.0.rhel.2.6.32.x64.tar.gz” saved [71340645/71340645]
   

2. Extract the downloaded package.

   [root@localhost ~]# tar -zxf ston.2.0.0.rhel.2.6.32.x64.tar.gz
   

3. Run the installation script.

   [root@localhost ~]# ./ston.2.0.0.rhel.2.6.32.x64.sh
   

4. All installation processes are recorded in the install.log file. Any problems that occur during the installation process will be noted there.

   #DownloadURL: http://foobar.com/ston/ston.2.0.0.rhel.2.6.32.x64.tar.gz
   #DownloadTime: 13 sec
   #Target: STON 2.0.0
   #Date: 2014.03.03 16:48:35
   Prepare for STON 2.0.0 install process
       Stopping STON...
           STON stopped
   [Copying files]
       `./fuse.conf' -> `/etc/fuse.conf'
       `./libfuse.so.2' -> `/usr/local/ston/libfuse.so.2'
       `./libtbbmalloc_proxy.so' -> `/usr/local/ston/libtbbmalloc_proxy.so'
       `./start-stop-daemon' -> `/usr/sbin/start-stop-daemon'
       `./libtbbmalloc_proxy.so.2' -> `/usr/local/ston/libtbbmalloc_proxy.so.2'
       `./libtbbmalloc.so' -> `/usr/local/ston/libtbbmalloc.so'
       `./libtbbmalloc.so.2' -> `/usr/local/ston/libtbbmalloc.so.2'
       `./libtbb.so' -> `/usr/local/ston/libtbb.so'
       `./libtbb.so.2' -> `/usr/local/ston/libtbb.so.2'
       `./stond' -> `/usr/local/ston/stond'
       `./stonx' -> `/usr/local/ston/stonx'
       `./stonr' -> `/usr/local/ston/stonr'
       `./stonu' -> `/usr/local/ston/stonu'
       `./stonapi' -> `/usr/local/ston/stonapi'
       `./server.xml.default' -> `/usr/local/ston/server.xml.default'
       `./vhosts.xml.default' -> `/usr/local/ston/vhosts.xml.default'
       `./ston_format.sh' -> `/usr/local/ston/ston_format.sh'
       `./ston_diskinfo.sh' -> `/usr/local/ston/ston_diskinfo.sh'
       `./wm.sh' -> `/usr/local/ston/wm.sh'
   [Exporting config files]
       #Export so directory
       /usr/local/ston/ to ld.so.conf
       #Export sysctl to /etc/sysctl.conf
       vm.swappiness=0
       vm.min_free_kbytes=524288
       #Export sudoers for WM
       Defaults    !requiretty
       winesoft ALL=NOPASSWD: /etc/init.d/ston stop, /etc/init.d/ston start, /bin/ps -ef
   [Configuring STON daemon script]
       STON deamon activate in run-level 2345.
   [Installing sub-packages]
       curl installed.
       libjpeg installed.
       libgomp installed.
       rrdtool installed.
   [Installing WM]
       Stopping WM...
       WM stopped
       `./wm.server_default.xml' -> `/usr/local/ston/wm/tmp/conf/server_default.xml'
       `./wm.vhost_default.xml' -> `/usr/local/ston/wm/tmp/conf/vhost_default.xml'
       WM configuration found. Current WM port : 8500
       PHP module for Legacy(CentOS 5.5) installed
       `./libphp5.so.5.5' -> `/usr/local/ston/wm/modules/libphp5.so'
       WM installation almost complete. Changing WM privileges.
   Installation successfully complete
   

Obtaining a License¶

New clients can obtain a license via this process.

1. Fill out the application form.
2. Email the completed form to license@winesoft.co.kr.
3. The license will be issued after confirmation.

The license file (license.xml) must be in the installation directory for STON to run properly.

Update¶

Use the “stonu” command to update STON to the latest version.

./stonu 2.0.1

See also Update to Latest Version from Chapter 13. WM (Web Management) to easily update STON.

Run¶

STON will be installed in the following default directory.

/usr/local/ston/

If any of the following files is missing or has invalid XML syntax, STON will not run.

• license.xml
• server.xml
• vhosts.xml

After the initial installation, not every XML file will be present. In this case, the distributed license.xml file should be placed in the directory. The server.xml.default and vhosts.xml.default files should also be placed in the directory. The *.default files are always included in the latest package.

Hello World¶

Open vhosts.xml and edit with the following code.

<Vhosts>
    <Vhost Name="www.example.com">
        <Origin>
            <Address>hello.winesoft.co.kr</Address>
        </Origin>
    </Vhost>
</Vhosts>

192.168.0.100        www.example.com

Origin Server¶

The purpose of the virtual host is to provide content in place of the origin server. Various types of origin servers can be accessed in various ways, depending on what is most suitable for the service platform.

<Vhosts>
    <Vhost Name="www.example.com">
        <Origin>
            <Address>1.1.1.1</Address>
            <Address>1.1.1.2</Address>
        </Origin>
    </Vhost>
</Vhosts>

• <Address>

  The address of the origin server from which the virtual host will copy content. There is no limit to the number of addresses that can be added. If there are more than two addresses, selection follows the active/active model (round-robin). If the origin server port is 80, it can be omitted.

For example, if the origin server is using a different port such as 8080, then the port number must be specified as 1.1.1.1:8080. There are eight different ways to format addresses using the {IP|Domain}{Port}{Path} format.

As long as the host header is not specified in the Origin Request Default Header, the host header from the table above will be transmitted.:

<Vhosts>
    <Vhost Name="www.example.com">
        <Origin>
            <Address>origin.com:8888/account/dir</Address>
        </Origin>
    </Vhost>
</Vhosts>

For example, the above configuration will request the following to the origin server.

GET / HTTP/1.1
Host: origin.com:8888

<Vhosts>
    <Vhost Name="www.example.com">
        <Origin>
            <Address>1.1.1.1</Address>
            <Address>1.1.1.2</Address>
            <Address2>1.1.1.3</Address2>
            <Address2>1.1.1.4</Address2>
        </Origin>
    </Vhost>
</Vhosts>

API Call¶

STON provides HTTP-based API. API calls are authorized by Administrator Settings. If a call is unauthorized, the connection will be terminated immediately.

The STON version can be checked as follows.

http://127.0.0.1:10040/version

The same API can be called with Linux shell commands.

./stonapi version

Hardware Status¶

The following will look up hardware information.

http://127.0.0.1:10040/monitoring/hwinfo

The results are returned in JSON format.

{
   "version": "1.1.9",
   "method": "hwinfo",
   "status": "OK",
   "result":
   {
      "OS" : "Linux version 3.3.0 ...(omitted)...",
      "STON" : "1.1.9",
      "CPU" :
      {
         "ProcCount": "4",
         "Model": "Intel(R) Xeon(R) CPU           E5606  @ 2.13GHz",
         "MHz": "1200.000",
         "Cache": "8192 KB"
      },
      "Memory" : "8 GB",
      "NIC" :
      [
         {
            "Dev" : "eth1",
            "Model" : "Intel Corporation 82574L Gigabit Network Connection",
            "IP" : "192.168.0.13",
            "MAC" : "00:25:90:36:f4:cb"
         }
      ],
      "Disk" :
      [
         {
            "Dev" : "sda",
            "Model" : "HP DG0146FAMWL (scsi)",
            "Total" : "238787584",
            "Usage" : "40181760"
         },
         {
            "Dev" : "sdb",
            "Model" : "HITACHI HUC103014CSS600 (scsi)",
            "Total" : "144706478080",
            "Usage" : "2101075968"
         },
         {
            "Dev" : "sdc",
            "Model" : "HITACHI HUC103014CSS600 (scsi)",
            "Total" : "144706478080",
            "Usage" : "2012160000"
         }
      ]
   }
}

Restart/Quit¶

The following commands restart or quit STON. To avoid unintended results, STON asks for confirmation for restart/quit commands on the web page.

http://127.0.0.1:10040/command/restart
http://127.0.0.1:10040/command/restart?key=JUSTDOIT       // Immediately executes command
http://127.0.0.1:10040/command/terminate
http://127.0.0.1:10040/command/terminate?key=JUSTDOIT       // Immediately executes command

Caching Reset¶

The following commands stop the service and discard all cached content. The commands will format all disks and resume the service when completed.

http://127.0.0.1:10040/command/cacheclear
http://127.0.0.1:10040/command/cacheclear?key=JUSTDOIT       // Immediately executes command

In the console window, the following commands will reset all or one of the virtual hosts.

./stonapi reset
./stonapi reset/ston.winesoft.co.kr

Reload Settings¶

After changing the settings, the administrator must make a call to the API. Aside from system or performance settings, most settings will immediately be applied without interrupting the service.

http://127.0.0.1:10040/conf/reload

Any changes from settings will be recorded in the Info Log.

Global Settings (server.xml)¶

The server.xml file is the global settings file and can be found in the same path as the execution file. It is an XML format text file.

# server.xml

<Server>
    <Host> ... </Host>
    <Cache> ... </Cache>
    <VHostDefault> ... </VHostDefault>
</Server>

We will first cover the configuration structure and basic functions. While Chapter 14. Access Control and Chapter 11. SNMP are also part of global settings, they will be explained in their respective chapters.

# server.xml - <Server>

<Host>
    <Name>stream_07</Name>
    <Admin>admin@example.com</Admin>
    <Manager Port="10040" HttpMethod="ON" Role="Admin" UploadMultipartName="confile">
        <Allow>192.168.1.1</Allow>
        <Allow Role="Admin">192.168.2.1-255</Allow>
        <Allow Role="User">192.168.3.0/24</Allow>
        <Allow Role="Looker">192.168.4.0/255.255.255.0</Allow>
    </Manager>
</Host>

# server.xml - <Server>

<Cache>
    <Storage DiskFailSec="60" DiskFailCount="10" OnCrash="hang">
        <Disk>/user/cache1</Disk>
        <Disk>/user/cache2</Disk>
        <Disk Quota="100">/user/cache3</Disk>
    </Storage>
</Cache>

# server.xml - <Server>

<Cache>
    <SystemMemoryRatio>100</SystemMemoryRatio>
    <ContentMemoryRatio>50</ContentMemoryRatio>
</Cache>

# server.xml - <Server>

<Cache>
    <Cleanup>
        <Time>02:00</Time>
        <Age>0</Age>
    </Cleanup>
    <Listen>0.0.0.0</Listen>
    <ConfigHistory>30</ConfigHistory>
</Cache>

http://127.0.0.1:10040/command/cleanup
http://127.0.0.1:10040/command/cleanup?age=10

# server.xml - <Server>

<VHostDefault>
    <Options> ... </Options>
    <OriginOptions> ... </OriginOptions>
    <Media> ... </Media>
    <Stats> ... </Stats>
    <Log> ... </Log>
</VHostDefault>

Virtual Host Settings (vhosts.xml)¶

The vhosts.xml file is recognized as the virtual host settings file and can be found in the same path as the execution file. There is no limit to the amount of virtual hosts that are allowed.

# vhosts.xml

<Vhosts>
    <Vhost Status="Active" Name="www.example.com"> ... </Vhost>
    <Vhost Status="Active" Name="img.example.com"> ... </Vhost>
    <Vhost Status="Active" Name="vod.example.com"> ... </Vhost>
</Vhosts>

# vhosts.xml - <Vhosts>

<Vhost Status="Active" Name="www.example.com">
    <Origin>
        <Address>10.10.10.10</Address>
    </Origin>
</Vhost>

GET / HTTP/1.1
Host: www.example.com

# vhosts.xml - <Vhosts>

<Vhost Name="example.com">
    <Alias>another.com</Alias>
    <Alias>*.sub.example.com</Alias>
</Vhost>

# vhosts.xml - <Vhosts>

<Vhost Name="example.com">
   ...
</Vhost>

<Vhost Name="another.com" Status="facade:example.com">
   ...
</Vhost>

# vhosts.xml - <Vhosts>

<Vhost Name="sports.com">
  <Sub Status="Active">
    <Path Vhost="baseball.com">/baseball/<Path>
    <Path Vhost="football.com">/football/<Path>
    <Path Vhost="photo.com">/*.jpg<Path>
  </Sub>
</Vhost>

<Vhost Name="baseball.com" />
<Vhost Name="football.com" />
<Vhost Name="photo.com" />

GET /football/rank.html HTTP/1.1
Host: sports.com

# vhosts.xml

<Vhosts>
    <Vhost Status="Active" Name="www.example.com"> ... </Vhost>
    <Vhost Status="Active" Name="img.example.com"> ... </Vhost>
    <Default>www.example.com</Default>
</Vhosts>

# vhosts.xml - <Vhosts>

<Vhost Name="www.example.com">
    <Listen>*:80</Listen>
</Vhost>

# vhosts.xml - <Vhosts>

<Vhost Name="www.example.com">
   <Listen>OFF</Listen>
</Vhost>

Checking the Virtual Host List¶

This command queries the virtual host list.

http://127.0.0.1:10040/monitoring/vhostslist

The result is returned in JSON format.

{
   "version": "1.1.9",
   "method": "vhostslist",
   "status": "OK",
   "result": [ "www.example.com","www.foobar.com", "site1.com" ]
}

Confirm Configuration¶

The next step is to confirm the configuration files. Each TXT file must be clearly assigned to a specific virtual host.

http://127.0.0.1:10040/conf/server.xml
http://127.0.0.1:10040/conf/vhosts.xml
http://127.0.0.1:10040/conf/querystring.txt?vhost=www.example.com
http://127.0.0.1:10040/conf/bypass.txt?vhost=www.example.com
http://127.0.0.1:10040/conf/ttl.txt?vhost=www.example.com
http://127.0.0.1:10040/conf/expires.txt?vhost=www.example.com
http://127.0.0.1:10040/conf/acl.txt?vhost=www.example.com
http://127.0.0.1:10040/conf/headers.txt?vhost=www.example.com
http://127.0.0.1:10040/conf/throttling.txt?vhost=www.example.com
http://127.0.0.1:10040/conf/postbody.txt?vhost=www.example.com

Configuration History¶

The following command allows you to browse backup configuration histories.

http://127.0.0.1:10040/conf/latest
http://127.0.0.1:10040/conf/history

The result is returned in JSON format. Checking only the latest configuration is fastest using /conf/latest.

{
    "history" :
    [
        {
            "id" : "5",
            "conf-date" : "2013-11-06",
            "conf-time" : "15:26:37",
            "type" : "loaded",
            "size" : "16368",
            "hash" : "D62CA26F16FE7C66F81D215D8C52266AB70AA5C8",
            "ver": "1.2.8"
        },
        {
            "id" : "6",
            "conf-date" : "2013-11-07",
            "conf-time" : "07:02:21",
            "type" : "modified",
            "size" : "27544",
            "hash" : "F81D215D8C52266AB70AA5C8D62CA26F16FE7C66",
            "ver": "1.2.8"
        }
    ]
}

• id The unique identification number (+1 per reload).
• conf-date Configuration modified date.
• conf-time Configuration modified time.
• type When settings take effect.
  • loaded When STON is loaded.
  • modified When a configuration is modified (by administrator or WM).
  • uploaded When a configuration file is uploaded via API.
  • restored When a configuration file is restored via API.
• size The size of a configuration file.
• hash The hash value of the configuration file using the SHA-1 algorithm.

Restore Configuration¶

This command restores the configuration to when a certain hash value or id was created. If both the hash value and id are stated in the command, the hash value takes precedence. If rollback occurs successfully, the result will be “200 OK”, while a failure will result in “500 Internal Error”.

http://127.0.0.1:10040/conf/restore?hash=...
http://127.0.0.1:10040/conf/restore?id=...

Configuration Download¶

This command will download a configuration of a time when a hash value or id was created. If both the hash value and id are stated in the command, the hash value takes precedence. The Content-Type will be displayed as “application/x-compressed”. If a hash value is not stated and the id cannot be found, the command will return “404 NOT FOUND”.

http://127.0.0.1:10040/conf/download?hash=...
http://127.0.0.1:10040/conf/download?id=...

Configuration Upload¶

This command will upload the configuration file using the HTTP Post method (Multipart supported).

http://127.0.0.1:10040/conf/upload

The address, Content-Length, and Content-Type (=”multipart/form-data”) must be clearly stated in the command as shown below.

POST /conf/upload
Content-Length: 16455
Content-Type: multipart/form-data; boundary=......

When the upload is completed, the configuration file will be extracted and applied to the system immediately.

In the multipart method, “confile” is used as a default name. This name can be changed in the UploadMultipartName property of the <Manager> tag.

<form enctype="multipart/form-data" action="http://127.0.0.1:10040/conf/upload" method="POST">
    <input name="confile" type="file" />
    <input type="submit" value="Upload" />
</form>

Time To Live (TTL)¶

The TTL is the amount of time stored content stays available. A longer TTL setting will reduce load on the origin server, but modifications will take longer to be applied because they must wait until the TTL expires. Conversely, a shorter TTL will mean higher load on the origin server due to more frequent requests for modification checks. The service can run smoothly when an appropriate TTL setting is found and the origin server load is decreased. When a TTL is set, it will not change until it expires. A new TTL is only applied to a file when the old TTL expires. Administrators can use API functions such as Purge, Expire, ExpireAfter, and HardPurge to change the TTL.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<TTL>
    <Res2xx Ratio="20" Max="86400">1800</Res2xx>
    <NoCache Ratio="0" Max="5" MaxAge="0">5</NoCache>
    <Res3xx>300</Res3xx>
    <Res4xx>30</Res4xx>
    <Res5xx>30</Res5xx>
    <ConnectTimeout>3</ConnectTimeout>
    <ReceiveTimeout>3</ReceiveTimeout>
    <OriginBusy>3</OriginBusy>
</TTL>

# /svc/www.example.com/ttl.txt
# Commas (,) are used as delimiters and the unit of time is seconds.

*.jsp, 10
/,5
/index.html, 5
/script/*.js, 300
/image/ad.jpg, 1800

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<TTL Priority="cc_nocache, custom, cc_maxage, rescode">
    ... (omitted) ...
</TTL>

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<TTLExtensionBy4xx>OFF</TTLExtensionBy4xx>
<TTLExtensionBy5xx>ON</TTLExtensionBy5xx>

Update Policy¶

Content will be updated after the TTL expires and the update check is confirmed at the origin server.

A response after checking for modifications.

1. The TTL is valid and an immediate response is given.
2. The TTL has expired, so a modification check (If-Modified-Since) is requested to the origin server. There is no response to the client until this check is performed.
3. When a response is returned by the origin server, either the TTL is extended or the content is swapped. With confirmation from the origin server, a response will be made to the client.
4. An immediate response is given for the checked content until its TTL expires.

For services like HD videos or games where transfer speed is more important than the response rate, this process is not very meaningful. With bulk data, it doesn’t matter that the origin server can respond within ten seconds because the transfer time takes much longer. Rather, since it is content that isn’t accessed frequently, it will need more renewal checks.

Meanwhile, online shopping malls are a different story. Web pages loading quickly is more important than anything else. The client’s screen must load in 1~2 seconds. In other words, the transfer time is more important than the response rate.

At this point, if the TTL expires and a update check must be performed, it could cause a huge delay. Considering the fact that most shopping malls must handle millions of items of content simultaneously, you must assume that update checks are constantly occurring on the origin server.

What we want is to stably transfer cached content regardless of any origin server error or delay.

We’re not afraid of errors!

These different requirements have led to the development of the background content renewal function.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<RefreshExpired>ON</RefreshExpired>

• <RefreshExpired>
  • ON (default) Responds after the modification check.
  • OFF Responds without waiting for the modification check response. Content will be swapped when new content is downloaded.

OFF The OFF setting is generally used because content is not changed very often.

There is no need to wait if content is not sensitive to changes.

As seen in the above image, because updating from the origin server takes place in the background, the cached content can be immediately sent to the client without waiting. If the origin server responds with 304 Not Modified, the TTL is extended. When the file is updated and the origin server responds with 200 OK, the file is smoothly replaced after it is fully downloaded. After the file is updated, users will receive the new file (colored yellow). Regardless of variables such as network failures or server failures, content updating will take place in the background and result in no service delays.

GET /logo.jpg HTTP/1.1
...
cache-control: no-cache or cache-control:max-age=0
pragma: no-cache
...

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<NoCacheRequestExpire>OFF</NoCacheRequestExpire>

Accept-Encoding Header¶

Even though HTTP requests may be for the same URL, depending on the existence of an Accept-Encoding header, different content may be cached. When STON sends a request to the origin server, it has no idea of knowing if the file is compressed or not, and it can’t check for compression every time, either.

It’s impossible to know what kind of response the origin server will give.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<AcceptEncoding>ON</AcceptEncoding>

• <AcceptEncoding>
  • ON (default) Will recognize the Accept-Encoding header sent by the HTTP client.
  • OFF Will ignore the Accept-Encoding header sent by the HTTP client.

If the origin server does not support compression, or if the bulk file does not require compression, then it is recommended to set <AcceptEncoding> to OFF.

Case Sensitivity¶

STON is unable to tell on its own if the origin server can differentiate between upper and lower case letters.

Either the content is the same or a 404 will occur.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<CaseSensitive>ON</CaseSensitive>

• <CaseSensitive>
  • ON (default) Differentiates between upper and lower case letters.
  • OFF Does not differentiate. All letters are processed as lower case.

QueryString Differentiation¶

It is not necessary to identify a query string unless the content is dynamically created by the query string If a URL contains a meaningless random value or a constantly changing time value, then it can create a lot of load on the origin server.

If the content is not dynamic, it is more likely to be identical.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<ApplyQueryString Collective="OFF">ON</ApplyQueryString>

• <ApplyQueryString>
  • ON (default) Identifies query strings. If one of the exception cases is met, the query string is ignored.
  • OFF Ignores query strings. If one of the exception cases is met, the query string is identified.

Query string exception cases are saved at /svc/{virtual host name}/querystring.txt.

# ./svc/www.example.com/querystring.txt

/private/personal.jsp?login=ok*
/image/ad.jpg

Note that the exception case changes in meaning depending on the setting of <ApplyQueryString>. Specific or patterned URLs (only * patterns are allowed) can be used in the configuration.

The Collective property comes into play when the Chapter 5. Content Purge API is called.

• Collective
  • OFF (default) Only the URL parameter will be targeted.
  • ON All content with URLs containing query strings will be targeted, not just the URL parameter.

If the Collective property is set to ON and there are many files, CPU load will become higher. It may take longer to search for the correct files, and unforeseen problems may occur. It is recommended to call the Chapter 5. Content Purge API using clearly defined URLs with query strings as much as possible.

Vary Header¶

Content can be classified through the use of Vary headers. Generally, Vary headers are the primary cause of sudden drops in performance on the cache server.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<VaryHeader />

• <VaryHeader>

  Configures the list of Vary headers to be supported among the ones returned by the origin server. Commas (,) are used as delimiters.

For example, if the origin server returns the following as the Vary header, it will be ignored because it is not set in <VaryHeader>.

Vary: Accept-Encoding, Accept, User-Agent

To exclude User-Agent and only recognize Accept-Encoding and Accept headers, do the following.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<VaryHeader>Accept-Encoding, Accept</VaryHeader>

To recognize all Vary headers sent by the origin server, do the following.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<VaryHeader>*</VaryHeader>

POST Request Caching¶

POST requests can be configured so that they are cached. POST requests have the same characteristics as URLs, but may differ in Body data.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<PostRequest MaxContentLength="102400" BodySensitive="ON">OFF</PostRequest>

• <PostRequest>
  • OFF (default) If a POST request arrives, the session ends.
  • ON POST requests are cached.

Most POST request processing cases use the Body data as Caching Keys. Detailed configuration can be made using the BodySensitive property and exception cases.

• BodySensitive

  • ON (default) Body data is recognized as a Caching Key. Maximum length is set by the MaxContentLength (default: 102400 bytes) property. If one of the exception cases is met, the Body data is ignored.
  • OFF Body data is ignored. If one of the exception cases is met, the Body data is recognized.

POST request exceptions can be set in the file /svc/{virtual host name}/postbody.txt.

# /svc/www.example.com/postbody.txt

/bigsale/*.php?nocache=*
/goods/search.php

Note that the exception case changes in meaning depending on the setting of BodySensitive. Specific or patterned URLs (only * patterns are allowed) can be used in the configuration.

It is possible to mix up this setting with GET/POST Bypass. POST requests may not be cached at all depending on the <BypassPostRequest> (default: ON) setting. As such, to cache POST requests, either <BypassPostRequest> must be set to OFF or an exception case must be set. In order of priority:

• Bypasses the origin server if bypass conditions (GET/POST Bypass) are met.
• Terminates the connection if there is no Content-Length header.
• Caches files if PostRequest is set to ON and Content-Length does not exceed MaxContentLength.
• Terminates the request if none of the above scenarios are encountered.

Purge¶

Purges the target in order to have it be redownloaded from the origin server. Content will be cached again when it is first accessed after a purge. If the content is not available on the origin server due to an error, the purged content will be restored to keep the service running. This restored content will be updated after the time set by ConnectTimeout.

http://127.0.0.1:10040/command/purge?url=...

Target content can be designated with URLs and patterns, and can also be designated with vertical bars (“|”) to indicate multiple domains and multiple targets. If the domain name is omitted, the most recently used domain name is used.

http://127.0.0.1:10040/command/purge?url=http://www.site1.com/image.jpg
http://127.0.0.1:10040/command/purge?url=www.site1.com/image.jpg
http://127.0.0.1:10040/command/purge?url=www.site1.com/image/bmp/
http://127.0.0.1:10040/command/purge?url=www.site1.com/image/*.bmp
http://127.0.0.1:10040/command/purge?url=www.site1.com/image1.jpg|/css/style.css|/script.js
http://127.0.0.1:10040/command/purge?url=www.site1.com/image1.jpg|www.site2.com/page/*.html

The results are returned in JSON format. The number and size of purged items, as well as the elapsed time (units: ms) will be displayed. Content that has already been purged will not be purged again.

{
    "version": "2.0.0",
    "method": "purge",
    "status": "OK",
    "result": { "Count": 24, "Size": 3747491, "Time": 12 }
}

Using the <Purge2Expire> tag, Purge can be set to Expire under certain conditions. For a response with no results, the HTTP response code can be set with <ResCodeNoCtrlTarget>.

Expire¶

The TTL of the target content is set to expire immediately. A check for modification is made when the content is first accessed after expiring. If there is no change, there is no redownload; only the TTL is extended.

http://127.0.0.1:10040/command/expire?url=...

Everything else is identical to Purge.

ExpireAfter¶

The TTL of the target content is set so that the content expires the input number of seconds after the API is called. ExpireAfter can make the expiration time earlier and make content update faster, or it can make the expiration time later and reduce load on the origin server.

http://127.0.0.1:10040/command/expireafter?sec=86400&url=...

Though the function call format resembles Purge and Expire, the sec parameter (in seconds) can also set the expiration date. If the sec parameter is omitted, the default value of 1 day (86400 s) is applied, and setting it to 0 is not allowed. For a response with no results, the HTTP response code can be set with <ResCodeNoCtrlTarget>.

HardPurge¶

If there is an error in the origin server, Purge/Expire/ExpireAfter will retain the content and continue normally. In contrast, HardPurge means the content is permanently deleted. As HardPurge is the most powerful deletion method, deleted content cannot be restored if there is an error. For a response with no results, the HTTP response code can be set with <ResCodeNoCtrlTarget>.

http://127.0.0.1:10040/command/hardpurge?url=...

Default Purge Behavior¶

The behavior of content restoration after a Purge API call can be configured.

# server.xml - <Server><Cache>

<Purge>Normal</Purge>

• <Purge>
  • Normal (default) Behaves as if it was Purge. (Content is restored if there is an error.)
  • Hard Behaves as if it was HardPurge. (Content is not restored if there is an error.)

HTTP Method¶

The purge API can be called with an extended HTTP Method.

PURGE /sample.dat HTTP/1.1
host: ston.winesoft.co.kr

HTTP methods fundamentally work under the manager port and the service port (80). HTTP Method requests sent to the service port can be configured in Administrator Settings.

POST Standard¶

The purge API can be called with POST, as shown below.

POST /command/purge HTTP/1.1
Content-Length: 37

url=http://ston.winesoft.co.kr/sample.dat

Session Management¶

An HTTP session is created when an HTTP client connects to the STON server. Content saved on the server is delivered to the client through the HTTP session. The process from the request to the response is called an HTTP transaction. An HTTP session handles multiple HTTP transactions in succession.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<ConnectionHeader>keep-alive</ConnectionHeader>
<ClientKeepAliveSec>10</ClientKeepAliveSec>
<KeepAliveHeader Max="0">ON</KeepAliveHeader>

• <ConnectionHeader> (default: keep-alive) Configures the Connection header (keep-alive or close) of the HTTP response sent to the client.

• <ClientKeepAliveSec> (default: 10 sec) Terminates a session when there is no transaction with the client session for the given amount of time. If the time is set to too large a value, then the number of sessions that are not transacting can grow unexpectedly. Maintaining a large number of sessions can cause load on the system.

• <KeepAliveHeader>

  • ON (default) Specifies the Keep-Alive header in the HTTP response. If Max (default: 0) is set to greater than zero, then the Max value will be used for the Keep-Alive header. Each HTTP transaction will reduce the value by one.
  • OFF Omits the Keep-Alive header in the HTTP response.

Client Cache-Control¶

This section covers the settings related to client cache-control.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<AgeHeader>OFF</AgeHeader>

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<RefreshExpiresHeader Base="Access">OFF</RefreshExpiresHeader>

# /svc/www.exmaple.com/expires.txt
# The delimiter is a comma (,), and the format is {condition},{time},{reference}.

$URL[/test.jpg], 86400
/test.jpg, 86400
*, 86400, access
/test/1.gif, 60 sec
/test/*.dat, 30 min, modification
$MIME[application/shockwave], 1 years
$MIME[application/octet-stream], 7 weeks, modification
$MIME[image/gif], 3600, modification

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<ETagHeader>ON</ETagHeader>

Response Headers¶

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<OriginalHeader>OFF</OriginalHeader>

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<ViaHeader>ON</ViaHeader>

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<ServerHeader>ON</ServerHeader>

Client Request/Response Header Modification¶

The client’s requests and responses can be modified based on certain conditions.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<ModifyHeader FirstOnly="OFF">OFF</ModifyHeader>

• <ModifyHeader>
  • OFF (default) Does not modify.
  • ON Modifies the header based on the header modification conditions.

The following explains the points when the header is modified.

• HTTP Request Header Modification Point

  The header is modified when the client’s HTTP request is first recognized. If the header gets modified, then it will be handled in its modified state by the cache module. However, the Host header cannot have its URI modified.

• HTTP Response Header Modification Point

  The header is modified just before the response to the client. However, the Content-Length cannot be changed.

Header modification conditions can be set in /svc/{virtual host name}/headers.txt. Multiple conditions can be set, and if header meets all the conditions, then all modifications will be applied in order.

If only the first condition should be applied, then the FirstOnly property should be set to ON. If different conditions attempt to modify the same header, then the result will be Last-Win from set or specified by put or append.

# /svc/www.example.com/headers.txt
# The delimiter is a comma (,).

# Request Modification
# The format is {Match}, {$REQ}, {Action(set|put|append|unset)}.
$IP[192.168.1.1], $REQ[SOAPAction], unset
$IP[192.168.2.1-255], $REQ[accept-encoding: gzip], set
$IP[192.168.3.0/24], $REQ[cache-control: no-cache], append
$IP[192.168.4.0/255.255.255.0], $REQ[x-custom-header], unset
$IP[AP], $REQ[X-Forwarded-For], unset
$HEADER[user-agent: *IE6*], $REQ[accept-encoding], unset
$HEADER[via], $REQ[via], unset
$URL[/source/*.zip], $REQ[accept-encoding: deflate], set

# Response Modification
# The format is {Match}, {$RES}, {Action(set|put|append|unset)}, {condition}.
# {condition} can modify the header based on special response codes, but is not mandatory.
$IP[192.168.1.1], $RES[via: STON for CDN], set
$IP[192.168.2.1-255], $RES[X-Cache], unset, 200
$IP[192.168.3.0/24], $RES[cache-control: no-cache, private], append, 3xx
$IP[192.168.4.0/255.255.255.0], $RES[x-custom-header], unset
$HEADER[user-agent: *IE6*], $RES[vary], unset
$HEADER[x-custom-header], $RES[cache-control: no-cache, private], append, 5xx
$URL[/source/*], $RES[cache-control: no-cache], set, 404
/secure/*.dat, $RES[x-custom], unset, 200
/*.mp4, $RES[Access-Control-Allow-Origin: example1.com], set
/*.mp4, $RES[Access-Control-Allow-Origin: example2.com], put

{Match} can be set to IP, GeoIP, Header, and URL forms.

• IP The format is $IP[...] and supports the formats of IP, IP Range, Bitmask, and Subnet.
• GeoIP The format is $IP[...] and GeoIP must be configured in advance. The country codes ISO 3166-1 alpha-2 and ISO 3166-1 alpha-3 are permitted.
• Header The format $HEADER[Key : Value]. The Value can be either a specific expression or a pattern. If the Value is omitted, the condition will be the existence of a header corresponding to the Key.
• URL The format is $URL[...] and can be omitted. It can be either a specific expression or a pattern.

{$REQ} and {$RES} configure how to modify the header. set, put, and append configure the header to {Key: Value}, and if the Value is omitted, an empty value (“”) will be input. unset will only input the {Key}.

{Action} can be set to one of the four settings: set , put , append , unset.

• set The Key and Value defined in the request/response header is added to the header. If the same Key is used, the new Value overwrites the old.
• put (resembles set) If the same Key is used, the new Value is added in a new line instead of overwriting the old Value.
• append (resembles set) If the same Key is used, the old Value and the new Value are attached with a comma (,).
• unset The Key defined in the request/response header is deleted from the header.

{Condition} can be set to a specific response code like 200 or 304 or can be set to a group of codes like 2xx, 3xx, 4xx, or 5xx. If {Match} matches but {Condition} does not, then the modification does not take place. If {Condition} is omitted, the response code is not checked.

URL Preprocessing¶

Regular expressions are used to modify the requested URLs. If URL preprocessing is defined, all client requests (HTTP or File I/O) must pass through the URL Rewriter.

The request can only reach the virtual host by passing through the URL Rewriter.

If an approaching Host name is modified by the URL Rewriter, then it will consider it as if the Host header was modified by the client’s HTTP request. URL preprocessing is configured in the virtual host settings (vhosts.xml). While most settings are under the virtual host, URL preprocessing can change the name of the Host requested by the client, so the settings must be on the same level as the virtual host.

# vhosts.xml

<Vhosts>
   <Vhost ...> ... </Vhost>
   <Vhost ...> ... </Vhost>
   <URLRewrite ...> ... </URLRewrite>
   <URLRewrite ...> ... </URLRewrite>
</Vhosts>

Multiple configurations are allowed, and the regular expressions will be checked in order.

# vhosts.xml - <Vhosts>

<URLRewrite AccessLog="Replace">
    <Pattern>www.example.com/([^/]+)/(.*)</Pattern>
    <Replace>#1.example.com/#2</Replace>
</URLRewrite>

• <URLRewrite>

  Configures URL preprocessing. AccessLog (default: Replace) Configures URLs that will be recorded in the Access log. Replace records URLs after processing (/logo.jpg), while Pattern records URLs after processing (/baseball/logo.jpg).

Compression¶

STON can compress and deliver content in place of the origin server. Content must be categorized by the Accept-Encoding Header.

Accept-Encoding: gzip, deflate

Files are compressed and delivered in real time.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<Compression Method="gzip" Level="6" SourceSize="2-2048">OFF</Compression>

• <Compression>
  • OFF (default) The compression function is not used.
  • ON The compression function is used with the following properties.
    • Method (default: gzip) Assigns the compression method. For now, only gzip is supported.
    • Level (default: 6) Assigns the compression level. This value varies based on the Method used. Only 1~9 are available for gzip. A lower number means compression is faster but worse, while a higher number means compression is slower but better.
    • SourceSize (default: 2-2048, unit: KB) Assigns a range for the source size. If files are too small, then files might be hardly compressed, while if files are too big, too much CPU might be consumed.

Compressed content is recognized and stored separately from the original content, and requests for the same content will not cause the content to be compressed again. The files to be compressed can be configured in /svc/{virtual host name}/compression.txt. The files will be compressed in that order.

# /svc/www.example.com/compression.txt
# The delimiter is a comma (,).
# The format is {URL condition}, {Method}, {Level}.

/sample.css, no       // No compression
*.css                 // Compress *.css with default method and level
*.htm, gzip           // Compress *.html with gzip (default level)
*.xml, , 9            // Compress *.xml with level 9 (default method)
*.js, gzip, 5         // Compress *.js with gzip level 5.

Compression is a function that consumes a large amount of CPU. The following is a performance test done on gzip (level 9) with files of different sizes.

• OS CentOS 6.3 (Linux version 2.6.32-279.el6.x86_64 (mockbuild@c6b9.bsys.dev.centos.org) (gcc version 4.4.6 20120305(Red Hat 4.4.6-4) (GCC) ) #1 SMP Fri Jun 22 12:19:21 UTC 2012)
• CPU Intel(R) Xeon(R) CPU E5-2603 0 @ 1.80GHz (8 processors)
• RAM 8GB
• HDD SAS 275GB X 5EA

If <Compression> is turned on, only uncompressed files will be requested from the origin server. In other words, the responses from the origin server will be to requests that have omitted the Accept-Encoding header. If the origin server specifies a Content-Encoding header to a request for uncompressed content, STON will recognize the content as already compressed and will not compress it again.

Error Detection and Recovery¶

If an error occurs in the origin server during caching, the server is automatically excluded. When the server is judged to be stable, it will be brought back into the service.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<ConnectTimeout>3</ConnectTimeout>
<ReceiveTimeout>10</ReceiveTimeout>
<Exclusion>3</Exclusion>
<Recovery Cycle="10" Uri="/" ResCode="0" Log="ON">5</Recovery>

• <ConnectTimeout> (default: 3 sec)

  If a connection to the origin server cannot be made within the set amount of time, it will be considered a connection failure.

• <ReceiveTimeout> (default: 10 sec)

  If the origin server does not return an HTTP response for a normal HTTP request within the set amount of time, it will be considered a transaction failure.

• <Exclusion> (default: 3 times)

  If an error occurs (<ConnectTimeout> or <ReceiveTimeout>) consecutively for the set number of times, the corresponding server will be excluded from the available server list. The value will be reset to 0 if a successful communication occurs before exclusion.

• <Recovery> (default: 5 times)

  If the origin server responds with ResCode when Uri is requested every Cycle consecutively for the set number of times, the corresponding server will be restored. If this value is set to zero, the server will not be restored.

  • Cycle (default: 10 sec) Makes a new request after the set amount of seconds.
  • Uri (default: /) The Uri to be sent in the request.
  • ResCode (default: 0) The response code to be identified as normal. If set to 0, any response will be considered a success regardless of the response code. If set to 200, the response code must be 200 for the response to be identified as normal. Commas (,) can be used to set multiple response codes. For example, if set to “200, 206, 404”, then any one of those response codes will be identified as normal.
  • Log (default: ON) Records the HTTP transaction that was used for recovery to the Origin Log.

Health-Checker¶

Error Detection and Recovery responds to errors that occur during the caching process. <Recovery> will terminate an HTTP transaction as soon as a response code is received. However, Health-Checker checks for a successful HTTP transaction.

# vhosts.xml - <Vhosts><Vhost>

<Origin>
   <Address> ... </Address>
   <HealthChecker ResCode="0" Timeout="10" Cycle="10"
                  Exclusion="3" Recovery="5" Log="ON">/</HealthChecker>
   <HealthChecker ResCode="200, 404" Timeout="3" Cycle="5"
                  Exclusion="5" Recovery="20" Log="ON">/alive.html</HealthChecker>
</Origin>

• <HealthChecker> (default: /)

  Configures Health-Checker. Multiple configurations are allowed. Uri is used as the input, and CDATA is used for invalid XML characters.

  • ResCode (default: 0) The correct response code (multiple codes can be assigned with commas).
  • Timeout (default: 10 sec) The available time from the socket connection until the HTTP transaction is completed.
  • Cycle (default: 10 sec) The execution period.
  • Exclusion (default: 3 times) The number of consecutive failures before excluding the server.
  • Recovery (default: 5 times) The number of consecutive successes before reintroducing the server.
  • Log (default: ON) Records the HTTP Transaction to the Origin Log.

Health-Checker can be configured in multiple ways and can be executed independently of client requests. It does not share information with Error Detection and Recovery or other Health-Checkers and uses only its own information to decide exclusion and recovery.

Origin Address Use Policy¶

The following factors are considered in deciding how to use the origin address (IP).

• Origin Server address format (IP or domain) and standby address
• Error Detection and Recovery
• Health-Checker

As a service is run, the origin address being excluded and recovered will occur frequently. STON uses IP Table-based origin addresses and provides information via the Origin Status Monitoring API.

It is simpler to set the origin address with an IP instead of a domain.

• Nothing will be able to change the IP list except for configuration changes.
• The IP address will not expire based on the TTL.
• Exclusion/recovery will work based on the IP address.

If the origin address is set with a domain, it must be resolved in order to obtain the IP. (This will be saved in the DNS Log.) The IP list will be able to be changed dynamically, and IPs will only be valid during the TTL.

• The domain will be resolved periodically (1~10 s).
• The IP Table to be used will be organized based on the resolving results.
• All IPs will be valid during the TTL and will not be used when the TTL expires.
• If an identical IP is resolved, the TTL will be refreshed.
• The IP Table cannot be empty. Even if the TTL is expired, the last IP will never be deleted.

Even if the origin address is set to a domain, error/recovery will work based on the IP address. Here there is something to keep in mind. The DNS client (STON) is unable to know the exact IP list for a domain. If a domain consists of only unavailable IP addresses, then it may constantly be in a state of error.

The domain address error/recovery policy is as follows.

• If all known IP addresses for a domain are excluded (Inactive), then the corresponding domain will also be excluded.
• Even if a new IP is resolved, if the domain is excluded then the IP address will also be excluded.
• Even if the TTLs of all IPs expire, this will not change the state of the excluded domain.
• At least one IP of an excluded domain must be recovered for that domain to also be recovered.

It is recommended to improve your understanding of service behavior through the Origin Status Monitoring API.

Origin Status Monitoring¶

An API is used to monitor the state of a virtual host’s origin server.

http://127.0.0.1:10040/monitoring/origin       // All virtual hosts
http://127.0.0.1:10040/monitoring/origin?vhost=www.example.com

The results are given in JSON format.

{
    "origin" :
    [
        {
            "VirtualHost" : "example.com",
            "Address" :
            [
                { "1.1.1.1" : "Active" },
                { "1.1.1.2" : "Active" }
            ],
            "Address2" : [  ],
            "ActiveIP" :
            [
                { "1.1.1.1" : 0 },
                { "1.1.1.2" : 0 }
            ] ,
            "InactiveIP" : [ ]
        },
        {
            "VirtualHost" : "foobar.com",
            "Address" :
            [
                { "origin.foobar.com" : "Active" }
            ],
            "Address2" : [  ],
            "ActiveIP" :
            [
                { "5.5.5.5" : 21 },
                { "5.5.5.6" : 60 },
                { "5.5.5.7" : 37 }
            ],
            "InactiveIP" :
            [
                { "5.5.5.8" : 10 },
                { "5.5.5.9" : 184 }
            ]
        }
    ]
}

• VirtualHost The virtual host name.
• Address Origin Server. It will return Active if the address is being used, and Inactive if not being used (due to an error).
• Address2 Standby Origin Server Address. It will return Active if the address is being used, and Inactive if not being used.
• ActiveIP The list of IPs in use and their TTLs. If the origin server is set with an IP address, an identical IP will be shown in Address with a TTL of 0. If set with a domain, the values depend on the resolving results. Various IPs and TTLs are used.
• InactiveIP The list of IPs not in use and their TTLs. Even though they are not in use, they can still be in a recovery status or being managed by Health-Checker. If the address is not recovered within the TTL, it will be removed.

Origin Status Reset¶

An API is used to reset the exclusion/recovery of origin servers of a virtual host. The current session will not be reused, and a new connection will be created instead.

http://127.0.0.1:10040/command/resetorigin       // All virtual hosts
http://127.0.0.1:10040/command/resetorigin?vhost=www.example.com

Overload Detection¶

Content requested for the first time must always be retrieved from the origin server. However, content already cached can be taken care of more flexibly. If STON detects that the origin server is overloaded, renewal of content can be postponed so as to not increase server load.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<BusySessionCount>100</BusySessionCount>

• <BusySessionCount> (default: 100) If the number of HTTP transactions taking place on the origin server exceeds the set value, it will be considered an overload. So that the origin server isn’t further accessed to renew expired content, the TTL is extended by the value of <OriginBusy> in Time To Live (TTL). This value can be set to a very large number if you want all requests to go to the origin server.

Origin Selection¶

This configures the origin server selection policy in the case when the origin server consists of multiple addresses (two or more).

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<BalanceMode>RoundRobin</BalanceMode>

• <BalanceMode> (default: RoundRobin)
  • RoundRobin (default) The server will be chosen via round-robin so that all origin servers receive requests uniformly. Connected idle sessions are only used when a request to the corresponding server is necessary.
  • Session A session will be used if it can be reused. If a new session is necessary, the next server will be chosen via round-robin.
  • Hash Content will be requested in a dispersed way following the consistent hashing algorithm. If a server is chosen, the current session will be reused; if there is no session, a new one will be created.

Session Recycle¶

If the origin server supports the Keep-Alive setting, then the connected session will always be reused. However, the origin server can unilaterally terminate connections to recycled sessions. As a result, the connection will need to be recovered, which can potentially lower user responsiveness. This is especially the case for sessions that haven’t been used in a while. To prevent this, sessions that aren’t reused for the set number of seconds will have their connection be automatically terminated.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<ReuseTimeout>60</ReuseTimeout>

• <ReuseTimeout> (default: 60 s) Terminates sessions that have not been used within the set amount of time. If set to zero, origin server sessions will not be reused.

Range Request¶

Configures how much content is downloaded at a time. If the content is generally viewed from the front, such as videos, then setting a limit to the download size can reduce unnecessary origin traffic.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<PartSize>0</PartSize>

• <PartSize> (default: 0 MB) If set to greater than zero, a range request will be used to download the set value (MB) starting from the point requested by the client.

Another reason to use <PartSize> is to save disk space. Under default settings, STON generates a file with the same size as the original on the disk. However, as long as <PartSize> is not zero, the file will be partitioned to the given size and saved.

For example, if a client watches the first minute (10 MB) of a one-hour (600 MB) video, only 10 MB of the disk space will be used. There is some benefit in saving disk space, but because the file is saved in parts, the disk load increases a little.

Initializing the Entire Range¶

Generally, whether a file is downloaded for the first time or is being checked for renewal on the origin server, the same simple GET request is sent.

GET /file.dat HTTP/1.1

However, origin servers configured to always modify files for general GET requests may have issues because the original file cannot be cached in its original form.

One of the most common examples is when the Apache web server embeds external modules such as mod_h.264_streaming. The Apache web server will always respond using the mod_h.264_streaming module. As such, the client (in this case, STON) will not receive the file as it originally was but a file modified by the module.

The mod_h.264_streaming module always modifies the original file.

A range request can be used to bypass the module and download the original.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<FullRangeInit>OFF</FullRangeInit>

• <FullRangeInit>

  • OFF (default) A normal HTTP request is sent.

  • ON A range request that begins with 0 is sent. In Apache, if the range header is specified, the module is bypassed.

    GET /file.dat HTTP/1.1
    Range: bytes=0-
    

    Because the Range can’t be known when a file is cached for the first time, Full-Range (starting with 0) is requested. You must verify that a normal response (206 OK) is returned for range requests.

If content is being renewed, the If-Modified-Since header will also be specified as below. The origin server must properly respond with 304 Not Modified.

GET /file.dat HTTP/1.1
Range: bytes=0-
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT

Keeping Client Requests¶

You can configure whether client requests are kept or changed via the Caching-Key.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<WholeClientRequest>OFF</WholeClientRequest>

• <WholeClientRequest>
  • OFF (default) The Caching-Key is used as the URL requested to the origin server.
  • ON The URL requested by the client is requested to the origin server.

To raise the Hit Ratio, the following settings are used to select the Caching-Key.

• Case Sensitivity
• QueryString Differentiation
• POST Request Caching

Therefore, the URL and Caching-Key requested to the origin server is determined in the following way.

If <WholeClientRequest> is set to ON, the URL sent by the client will be sent as is to the origin, regardless of the Caching-Key.

When POST requests are cached and requested to the origin server, the body data of the POST request sent by the client is transmitted without modification.

Origin Request Default Header¶

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<Host />

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<UserAgent>STON</UserAgent>

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<XFFClientIPOnly>OFF</XFFClientIPOnly>

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<OriginalETag>OFF</OriginalETag>

Origin Request Header Modification¶

The HTTP header can be changed when sending HTTP requests to the origin server based on certain conditions.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<ModifyHeader FirstOnly="OFF">OFF</ModifyHeader>

• <ModifyHeader>
  • OFF (default) Keeps the original header.
  • ON The header changes based on conditions.

The point in time the header is changed is when the HTTP request packet is completed, just before it is sent to the origin server. However, range requests cannot be changed.

This function is a sub-function of Client Request/Response Header Modification. The $ORGREQ keyword is used for header changes.

# /svc/www.example.com/headers.txt

$URL[/*.mp4], $ORGREQ[x-media-type: video/mp4], set
$IP[1.1.1.1], $ORGREQ[user-agent: media_probe], put
*, $ORGREQ[If-Modified-Since], unset
*, $ORGREQ[If-None-Match], unset

Redirect Tracking¶

If the origin server returns responses from the Redirect category (301, 302, 303, 307), the Location header is tracked to request content.

Clients will not know if they are redirected or not.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<RedirectionTrace>OFF</RedirectionTrace>

• <RedirectionTrace>
  • OFF (default) Saves as a 3xx response.
  • ON Downloads content from the address given in the Location header. If the format of the header is incorrect or there is no header, then tracking will fail. In order to prevent infinite redirection, STON will only redirect once.

No-Cache Request Bypass¶

If the client sends a no-cache request, it will be bypassed.

GET / HTTP/1.1
cache-control: no-cache or cache-control:max-age=0
pragma: no-cache

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<BypassNoCacheRequest>OFF</BypassNoCacheRequest>

• <BypassNoCacheRequest>
  • OFF (default) The request is handled by the cache module.
  • ON The request is bypassed to the origin server.

GET/POST Bypass¶

A bypass can be set to be the default action of GET/POST requests. It is important to keep in mind that because GET and POST are used differently, their actions will be different as well.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<BypassPostRequest>ON</BypassPostRequest>
<BypassGetRequest>OFF</BypassGetRequest>

• <BypassPostRequest>
  • ON (default) The POST request is bypassed to the origin server.
  • OFF The POST request is handled by STON.
• <BypassGetRequest>
  • OFF (default) The GET request is handled by STON.
  • ON The GET request is bypassed to the origin server.

Bypasses support the same conditions as Virtual Host ACL. Exception cases for bypasses can be set in /svc/{virtual host name}/bypass.txt.

# /svc/www.example.com/bypass.txt
$IP[192.168.2.1-255]
/index.html

If cache or bypass conditions are not specified, the opposite of the default setting will be applied. For example, if <BypassGetRequest> is set to ON, the exception cases become the caching list. There is a lot of room for confusion, but the second parameter can be set to explicitly state the conditions.

# /svc/www.winesoft.co.kr/bypass.txt

$HEADER[cookie: *ILLEGAL*], cache               // Always cache
!HEADER[referer:]                               // Depends on the default setting
!HEADER[referer] & !HEADER[user-agent], bypass  // Always bypass
$URL[/source/public.zip]                        // Depends on the default setting

The priority of actions is as follows.

1. No-Cache bypass
2. Bypass is specified in bypass.txt
3. Default setting of bypass.txt

Fixed Origin Servers¶

Some transactions, such as login status, require a one-to-one communication between the origin server and the client. Properties of GET/POST Bypass can be used to fix the origin server to the client.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<BypassPostRequest OriginAffinity="ON">...</BypassPostRequest>
<BypassGetRequest OriginAffinity="ON">...</BypassGetRequest>

• OriginAffinity

  • ON (default) Guarantees that the client’s requests will always be bypassed to the same origin server. However, it is not guaranteed to be the same socket.

    There is always the possibility that all the sockets of an origin server will lose connection. However, if this occurs, a new socket connection will simply be requested from the corresponding server.

    

    Requests will always be bypassed to the same server.

    If the origin server being bypassed to ends up being excluded due to errors or dropped from DNS, requests will be bypassed to a new server instead.

  • OFF Will not guarantee which server the client requests will bypass to.

    

    Requests will follow Origin Selection.

Fixed Origin Sessions¶

Each client socket will use a one-to-one bypass session with the origin server.

The client will have their own origin session.

Properties of GET/POST Bypass can be used to fix the origin session to the client.

# server.xml - <Server><VHostDefault><Options>
# vhosts.xml - <Vhosts><Vhost><Options>

<BypassPostRequest Private="OFF">...</BypassPostRequest>
<BypassGetRequest Private="OFF">...</BypassGetRequest>

• Private
  • ON The client session will have their own private session on the origin server. Requests will always be bypassed to the same server. Either the client or the origin server can terminate the session, at which point the session will be terminated on the other end as well.
  • OFF (default) Private sessions are not used.

Just as origin servers hold on to the user’s login information within a session, it is helpful if the client handles requests within the same socket as well.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<BypassConnectTimeout>5</BypassConnectTimeout>
<BypassReceiveTimeout>300</BypassReceiveTimeout>

Bypass Header¶

A bypass header configures whether or not to apply the bypass setting of Origin Request Default Header.

# server.xml - <Server><VHostDefault><OriginOptions>
# vhosts.xml - <Vhosts><Vhost><OriginOptions>

<UserAgent Bypass="OFF">...</UserAgent>
<Host Bypass="ON"/>
<XFFClientIPOnly Bypass="ON">...</XFFClientIPOnly>

• Bypass Property
  • ON Specifies the configured header.
  • OFF Specifies the relative headers sent by the clients.

Port Bypass¶

With a port bypass, the packets from a specific TCP port will all be bypassed to the origin server. This setting is exclusive to virtual hosts.

# vhosts.xml - <Vhosts>

<Vhost Name="www.example">
   <PortBypass>443</PortBypass>
   <PortBypass Dest=”1935”>1935</PortBypass>
</Vhost>

• <PortBypass> Bypasses all packets from the designated port to the same port on the origin server. The Dest property configures the destination port on the origin server.

For example, bypassing port 443 will have an effect similar to creating a direct SSL connection with the origin server. Ports being bypassed can never have multiple redundant settings.

Service Configuration¶

As long as a specific IP or port is not designated, the default binding service address is “*.443”. This is configured in the global configuration (server.xml).

# server.xml - <Server>

<Https>
   <Cert>/usr/ssl/cert.pem</Cert>
   <Key>/usr/ssl/certkey.pem</Key>
   <CA>/usr/ssl/CA.pem</CA>
</Https>

<Https Listen="1.1.1.1:443">
   <Cert>/usr/ssl_ip_port/cert.pem</Cert>
   <Key>/usr/ssl_ip_port/certkey.pem</Key>
   <CA>/usr/ssl_ip_port/CA.pem</CA>
</Https>

<Https Listen="*:886">
   <Cert>/usr/ssl_port/cert.pem</Cert>
   <Key>/usr/ssl_port/certkey.pem</Key>
   <CA>/usr/ssl_port/CA.pem</CA>
</Https>

• <Https> Configures HTTPS.
  • <Cert> Server certificate.
  • <Key> The private key for server certification. Encrypted formatting not supported.
  • <CA> Certificate authority (CA) chain certificate.

Even if the same port is used, more specific expressions will take priority.

For example, if there are multiple NICs as in the example above, a client that connects using 1.1.1.1:443 will be given service using the second and more specific certificate (1.1.1.1:443), while a client that connects to 1.1.1.4:443 will be given service with the first and more general certificate (omitted, or *:443). If the certificate is overwritten with a file of the same name, the changes will be reflected upon reload.

SSL/TLS Acceleration¶

SSL/TLS can be accelerated using CPU (AES-NI). A CPU that supports AES-NI will prioritize the AES algorithm for SSL/TLS. If AES-NI is recognized, the following will be recorded in the Info.log file.

AES-NI : ON (SSL/TLS accelerated)

Administrators can select whether to use AES-NI or not.

# server.xml - <Server><Cache>

<AES-NI>ON</AES-NI>

• <AES-NI> (default: ON) Decides whether or not AES-NI is used.

CipherSuite Selection¶

The following CipherSuites are supported.

The CipherSuite to be used can be configured in the CipherSuite property of <Https>.

# server.xml - <Server>

<Https CipherSuite="ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP">
   <Cert>/usr/ssl/cert.pem</Cert>
   <Key>/usr/ssl/certkey.pem</Key>
   <CA>/usr/ssl/CA.pem</CA>
</Https>

• CipherSuite Follows the SSLCipherSuite Directive in Apache mod_ssl.

A higher level of security can be obtained by ensuring forward secrecy (refer to links below).

• SSL Labs: Deploying Forward Secrecy
• SSL/TLS & Perfect Forward Secrecy
• Configuring Apache, Nginx, and OpenSSL for Forward Secrecy

By default, a CipherSuite that ensures forward secrecy (FS) is prioritized.

# server.xml - <Server>

<Https FS="ON"> ...  </Https>

• FS
  • ON (default) A CipherSuite that ensures forward secrecy is prioritized.
  • OFF Selects in the order specified by ClientHello.

The FS property takes priority over the CipherSuite property.

Checking the CipherSuite¶

The results of configuring the CipherSuite can be checked. CipherSuite expression follows OpenSSL 1.0.0E.

http://127.0.0.1:10040/monitoring/ssl?ciphersuite=...

The results are returned in JSON format.

{
    "version": "2.0.0",
    "method": "ssl",
    "status": "OK",
    "result":
    [
        {
            "Name" : "AES128-SHA",
            "Ver" : "SSLv3",
            "Kx" : "RSA",
            "Au" : "RSA",
            "Enc" : "AES(128)",
            "Mac" : "SHA1"
        },
        {
            "Name" : "AES256-SHA",
            "Ver" : "SSLv3",
            "Kx" : "RSA",
            "Au" : "RSA",
            "Enc" : "AES(256)",
            "Mac" : "SHA1"
        }
    ]
}

Multi-Domain Configuration¶

SSL configurations can cause problems when a single server runs multiple services simultaneously. Most Web/Cache servers decide which virtual host is used for the service by examining the Host header of the HTTP request.

General HTTPS communication.

Generally, the SSL identifies the server name (winesoft.co.kr) that the client (browser) tries to connect to using the certificate. However, if identification cannot be done with the certificate (e.g. the certificate is wrong or expired), then the user will be asked whether to trust the website or not (though there are cases when the site is blocked entirely). Though normal identification could not be done, SSL communication can still be established with the client’s trust.

It is left to the client to judge.

If there is only one virtual host on the server that uses SSL, no problems will occur. However, multiple virtual hosts running simultaneously on a server can cause problems. This is because when the server sends the certificate to the client (“2. Certificate Transmission” in “General HTTPS communication”), the server is unable to know which host the client is trying to reach.

The following show some typical solutions for this issue.

Multi Certificate¶

This method places multiple domains or wildcards (i.e. *.winesoft.co.kr) in the certificate so that multiple domains can be identified with only one certificate.

Multiple domains can be certified with one certificate.

This method is effective if the subjects of the service are the same, but if there is no relation, sharing the certificate is rather difficult. As this method can be used just by replacing the certificate, there is no need to configure anything in STON (see also DigiCert ).

https://winesoft.co.kr:543/

# server.xml - <Server>

<Https> ..Certificate A.. </Https>
<Https Listen="*:543"> ..Certificate B.. </Https>
<Https Listen="*:544"> ..Certificate C.. </Https>

# server.xml - <Server>

<Https Listen="10.10.10.10"> ..Certificate A.. </Https>
<Https Listen="10.10.10.11"> ..Certificate B.. </Https>
<Https Listen="10.10.10.12"> ..Certificate C.. </Https>

# server.xml - <Server>

<Https Listen="eth0"> ... </Https>
<Https Listen="eth1"> ... </Https>
<Https Listen="eth2"> ... </Https>

Enabling Security Protocol¶

The protocol can be established for each <Https>.

# server.xml - <Server>

<Https TLS1.2="ON" TLS1.1="ON" TLS1.0="ON" SSL3.0="ON"> ...  </Https>

• TLS1.2 (default: ON) Uses TLS1.2.
• TLS1.1 (default: ON) Uses TLS1.1.
• TLS1.0 (default: ON) Uses TLS1.0.
• SSL3.0 (default: ON) Uses SSL3.0.

HSTS¶

HSTS (HTTP Strict Transport Security) can be easily set up using Client Request/Response Header Modification.

# /svc/www.example.com/headers.txt

*, $RES[Strict-Transport-Security: max-age=31536000; includeSubDomains], set

The Qualys SSL Server Test only returns an A+ rating for sites with HSTS enabled.

STON can receive A+s starting from v2.2.

Data Range¶

The range of data to be collected can be configured.

# server.xml - <Server><VHostDefault>
# vhosts.xml - <Vhosts><Vhost>

<Stats>
   <DirDepth>0</DirDepth>
   <DirDepthAccum>OFF</DirDepthAccum>
   <HttpsTraffic>OFF</HttpsTraffic>
   <ClientLocal>OFF</ClientLocal>
   <OriginLocal>OFF</OriginLocal>
</Stats>

• <DirDepth> (default: 0)

  Collects statistics for each directory. If set to zero, statistics will be collected in the root (/) directory. If set to one, statistics will be collected in directories one level down.

  Note

  Though there is no limit to the value that can be set, collecting statistics for too many directories can cause memory problems.

• <DirDepthAccum>

  Configures whether or not to accumulate statistics in the parent directory when collecting the statistics for each directory. If <DirDepth> is set to zero, this setting is ignored.

  • OFF (default) Statistics are not accumulated in the parent directory.
  • ON Statistics are accumulated in the parent directory.

  For example, let’s assume that <DirDepth> is set to two and all directories have ten lines of traffic. If <DirDepthAccum> is set to OFF, then statistics will be collected in each directory where traffic occurs, as shown in the left diagram. If set to ON, statistics from lower directories are accumulated in parent directories, as shown in the right diagram.

  

  Accumulated statistics in the parent directory.

  In this example, the sum of the traffic in the /img directory and its subdirectories is 30, which is accumulated into the parent directory.

• <HttpsTraffic>

  • OFF (default) HTTPS traffic is only collected in SSL statistics.
  • ON HTTPS traffic is collected into both SSL and HTTP statistics.

  Generally, traffic that passes through the SSL layer is stored separately as SSL statistics. However, HTTPS will be processed as HTTP in upper protocols, so more detailed statistics can be collected. Because SSL and HTTP statistics can overlap, it is recommended to only trust HTTP statistics.

• <ClientLocal>

  The traffic between the Loopback client and STON can be included in statistics.

  • OFF (default) Will not be included.
  • ON Will be included.

• <OriginLocal>

  The traffic between STON and the Loopback origin server will be included.

  • OFF (default) Will not be included.
  • ON Will be included.

Host Aggregate Statistics¶

Host statistics are the aggregate statistics of all the virtual hosts that run on the lowest level. The statistics can be provided in JSON and XML formats.

{                                            <Host
  "Host":                                      Version="2.0.0"
  {                                            Name="localhost"
    "Version":"2.0.0",                         State="Healthy"
    "Name":"localhost",                        Uptime="155986"
    "State":"Healthy",                         OriginSession="32"
    "Uptime":155996,                           OriginActiveSession="20"
    "OriginSession":33,                        OriginInbound="1140741"
    "OriginActiveSession":20,                  OriginOutbound="10059"
    "OriginInbound":688177,                    OriginReqCount="42"
    "OriginOutbound":14184,                    OriginResTotalCount="42"
    "OriginReqCount":62,                       OriginResTotalTimeRes="5071"
    "OriginResTotalCount":62,                  OriginResTotalTimeComplete="10288"
    "OriginResTotalTimeRes":2375,              OriginRes2xxCount="19"
    "OriginResTotalTimeComplete":2509,         OriginRes2xxTimeRes="9989"
    "OriginRes2xxCount":54,                    OriginRes2xxTimeComplete="21521"
    "OriginRes2xxTimeRes":2327,                OriginRes3xxCount="23"
    "OriginRes2xxTimeComplete":2481,           OriginRes3xxTimeRes="1008"
    "OriginRes3xxCount":8,                     OriginRes3xxTimeComplete="1008"
    "OriginRes3xxTimeRes":2700,                OriginRes4xxCount="0"
    "OriginRes3xxTimeComplete":2700,           OriginRes4xxTimeRes="0"
    "OriginRes4xxCount":0,                     OriginRes4xxTimeComplete="0"
    "OriginRes4xxTimeRes":0,                   OriginRes5xxCount="0"
    "OriginRes4xxTimeComplete":0,              OriginRes5xxTimeRes="0"
    "OriginRes5xxCount":0,                     OriginRes5xxTimeComplete="0"
    "OriginRes5xxTimeRes":0,                   ClientSession="165"
    "OriginRes5xxTimeComplete":0,              ClientActiveSession="80"
    "ClientSession":155,                       ClientInbound="14792"
    "ClientActiveSession":80                   ClientOutbound="1981700"
    "ClientInbound":35748,                     ClientReqCount="64"
    "ClientOutbound":972906,                   ClientResTotalCount="64"
    "ClientReqCount":152,                      ClientResTotalTimeRes="5535"
    "ClientResTotalCount":152,                 ClientResTotalTimeComplete="6840"
    "ClientResTotalTimeRes":1411,              ClientRes2xxCount="44"
    "ClientResTotalTimeComplete":1479,         ClientRes2xxTimeRes="8050"
    "ClientRes2xxCount":93,                    ClientRes2xxTimeComplete="9943"
    "ClientRes2xxTimeRes":2305,                ClientRes3xxCount="20"
    "ClientRes2xxTimeComplete":2409,           ClientRes3xxTimeRes="5"
    "ClientRes3xxCount":59,                    ClientRes3xxTimeComplete="15"
    "ClientRes3xxTimeRes":3,                   ClientRes4xxCount="0"
    "ClientRes3xxTimeComplete":13,             ClientRes4xxTimeRes="0"
    "ClientRes4xxCount":0,                     ClientRes4xxTimeComplete="0"
    "ClientRes4xxTimeRes":0,                   ClientRes5xxCount="0"
    "ClientRes4xxTimeComplete":0,              ClientRes5xxTimeRes="0"
    "ClientRes5xxCount":0,                     ClientRes5xxTimeComplete="0"
    "ClientRes5xxTimeRes":0,                   RequestHitRatio="6923"
    "ClientRes5xxTimeComplete":0,              ByteHitRatio="4243">
    "RequestHitRatio":6387,                    <HttpCountSum
    "ByteHitRatio":2926,                         OriginReqCount="0"
    "HttpCountSum" :                             OriginResTotalCount="0"
    {                                            OriginRes2xxCount="0"
      "OriginReqCount" : 0,                      OriginRes3xxCount="0"
      "OriginResTotalCount" : 0,                 OriginRes4xxCount="0"
      "OriginRes2xxCount" : 0,                   OriginRes5xxCount="0"
      "OriginRes3xxCount" : 0,                   ClientReqCount="0"
      "OriginRes4xxCount" : 0,                   ClientResTotalCount="0"
      "OriginRes5xxCount" : 0,                   ClientRes2xxCount="0"
      "ClientReqCount" : 0,                      ClientRes3xxCount="0"
      "ClientResTotalCount" : 0,                 ClientRes4xxCount="0"
      "ClientRes2xxCount" : 0,                   ClientRes5xxCount="0"/>
      "ClientRes3xxCount" : 0,                 <HttpRequestHitSum
      "ClientRes4xxCount" : 0,                   TCP_NONE="0"
      "ClientRes5xxCount" : 0                    TCP_HIT="0"
    },                                           TCP_IMS_HIT="0"
    "HttpRequestHitSum" :                        TCP_REFRESH_HIT="0"
    {                                            TCP_REF_FAIL_HIT="0"
      "TCP_NONE" : 0,                            TCP_NEGATIVE_HIT="0"
      "TCP_HIT" : 0,                             TCP_REDIRECT_HIT="0"
      "TCP_IMS_HIT" : 0,                         TCP_MISS="0"
      "TCP_REFRESH_HIT" : 0,                     TCP_REFRESH_MISS="0"
      "TCP_REF_FAIL_HIT" : 0,                    TCP_CLIENT_REFRESH_MISS="0"
      "TCP_NEGATIVE_HIT" : 0,                    TCP_DENIED="0"
      "TCP_REDIRECT_HIT" : 0,                    TCP_ERROR="0"/>
      "TCP_MISS" : 0,                          <FileSystem>
      "TCP_REFRESH_MISS" : 0,                    <RequestHitRatio>0</RequestHitRatio>
      "TCP_CLIENT_REFRESH_MISS" : 0,             <ByteHitRatio>0</ByteHitRatio>
      "TCP_DENIED" : 0,                          <Outbound>0</Outbound>
      "TCP_ERROR" : 0                            <Session>0</Session>
    },                                         </FileSystem>
    "FileSystem":                              <System> ... </System>
    {                                          <VirtualHost> ... </VirtualHost>
      "RequestHitRatio":0,                     <VirtualHost> ... </VirtualHost>
      "ByteHitRatio":0,                        <VirtualHost> ... </VirtualHost>
      "Outbound":0,                            <View> ... </View>
      "Session":0                              <View> ... </View>
    },                                       </Host>
    "System":{ ... },
    "VirtualHost": [ ... ]
    "View": [ ... ]
  }
}

• Version STON version.

• Name The host name. If not defined, the system name will be used.

• State Service status. (Healthy=Normal service, Inactive=Inactive license, Emergency)

• Uptime (unit: seconds) The service running time.

• OriginSession The number of origin sessions.

• OriginActiveSession The number of transmitting origin sessions.

• OriginInbound (unit: bytes, average) The amount of data received from the origin server.

• OriginReqCount (average) The amount of requests to the origin server.

• OriginOutbound (unit: bytes, average) The amount of data transmitted to the origin server.

• OriginResTotalCount (average) The number of responses from the origin server.

• OriginResTotalTimeRes (unit: 0.01 ms, average) The origin server response time (from HTTP request to first HTTP response).

• OriginResTotalTimeComplete (unit: 0.01 ms, average) The origin server HTTP transaction completion time (from HTTP request to HTTP response completion).

• OriginRes2xxCount (average) The number of 2xx responses from the origin server.

• OriginRes2xxTimeRes (unit: 0.01 ms, average) The origin server 2xx response time.

• OriginRes2xxTimeComplete (unit: 0.01 ms, average) The origin server 2xx transaction completion time.

• OriginRes3xxCount (average) The number of 3xx responses from the origin server.

• OriginRes3xxTimeRes (unit: 0.01 ms, average) The origin server 3xx response time.

• OriginRes3xxTimeComplete (unit: 0.01ms, average) The origin server 3xx transaction completion time.

• OriginRes4xxCount (average) The number of 4xx responses from the origin server.

• OriginRes4xxTimeRes (unit: 0.01 ms, average) The origin server 4xx response time.

• OriginRes4xxTimeComplete (unit: 0.01ms, average) The origin server 4xx transaction completion time.

• OriginRes5xxCount (average) The number of 5xx responses from the origin server.

• OriginRes5xxTimeRes (unit: 0.01 ms, average) The origin server 5xx response time.

• OriginRes5xxTimeComplete (unit: 0.01 ms, average) The origin server 5xx transaction completion time.

• ClientSession The number of client sessions.

• ClientActiveSession The number of transmitting client sessions.

• ClientInbound (unit: bytes, average) The amount of inbound data from clients.

• ClientOutbound (unit: bytes, average) The amount of outbound data to clients.

• ClientReqCount (average) The number of client requests.

• ClientResTotalCount (average) The number of client responses.

• ClientResTotalTimeRes (unit: 0.01 ms, average) The client response time (from HTTP request to first HTTP response).

• ClientResTotalTimeComplete (unit: 0.01 ms, average) The client HTTP transaction completion time (from HTTP request to HTTP response completion).

• ClientRes2xxCount (average) The number of 2xx responses from the client.

• ClientRes2xxTimeRes (unit: 0.01 ms, average) The client 2xx response time.

• ClientRes2xxTimeComplete (unit: 0.01 ms, average) The client 2xx transaction completion time.

• ClientRes3xxCount (average) The number of 3xx responses from the client.

• ClientRes3xxTimeRes (unit: 0.01 ms, average) The client 3xx response time.

• ClientRes3xxTimeComplete (unit: 0.01 ms, average) The client 3xx transaction completion time.

• ClientRes4xxCount (average) The number of 4xx responses from the client.

• ClientRes4xxTimeRes (unit: 0.01 ms, average) The client 4xx response time.

• ClientRes4xxTimeComplete (unit: 0.01 ms, average) The client 4xx transaction completion time.

• ClientRes5xxCount (average) The number of 5xx responses from the client.

• ClientRes5xxTimeRes (unit: 0.01 ms, average) The client 5xx response time.

• ClientRes5xxTimeComplete (unit: 0.01 ms, average) The client 5xx transaction completion time.

• RequestHitRatio (unit: 0.01%, average) Hit ratio. If a caching object is created and the corresponding object is initialized, it is considered a hit. On the other hand, if the caching object is missing or the object is not initialized from the origin server, it does not count as a hit. The response code is unrelated to the hit ratio.

  

  HTTP and File I/O share the virtual host.

  The RequestHitRatio of File I/O accessed via Apache will become 0%. The HTTP server, however, accesses cached files due to File I/O, making the RequestHitRatio 100%. ByteHitRatio is calculated as the ratio of the origin inbound to either HTTP outbound or File I/O outbound.

• ByteHitRatio (unit: 0.01%, average) The transfer ratio of the origin server to the client.

  (Client Outbound - Origin Server Inbound) / Client Outbound
  

  If the origin server is much faster or the client session closes quickly, then the total ratio can become a negative value.

• FileSystem Independent FileSystem statistics that do not count other stat values.

  • RequestHitRatio (unit: 0.01%, average) Hit ratio based on File I/O.
  • ByteHitRatio (unit: 0.01%, average) Transfer ratio of origin server to File I/O.
  • Outbound (unit: bytes, average) Size of data that goes through File I/O.
  • Session (average) The number of threads in the File I/O process.

System Statistics¶

The statistics of the system and global resources can be provided in JSON and XML formats.

"System":                                   <System>
{                                             <CPU
  "CPU":                                          Kernel="689"
  {                                               User="1316"
    "Kernel":689,                                 Idle="7993"
    "User":1316,                                  ProcKernel="570"
    "Idle":7993,                                  ProcUser="1216"
    "ProcKernel":570,                             Nice="0"
    "ProcUser":1216,                              IOWait="52"
    "Nice":0,                                     IRQ="10"
    "IOWait":52,                                  SoftIRQ="12"
    "IRQ":10,                                     Steal="0" />
    "SoftIRQ":12,                             <Mem Free="5914644" STON="9785800"/>
    "Steal":0                                 <Storage>
  },                                            <Disk
  "Mem":                                            Path="/cache1"
  {                                                 Status="Normal"
    "Free":5914644,                                 Read="23"
    "STON":9785800                                  ReadMerged="0"
  },                                                ReadSectors="344"
  "Storage":                                        ReadTime="117"
  {                                                 Write="24"
    "Disk":                                         WriteMerged="93"
    [                                               WriteSectors="936"
      {                                             WriteTime="256"
        "Path":"/cache1",                           IOProgress="0"
        "Status":"Normal",                          IOTime="173"
        "Read":23,                                  IOWeightedTime="373"/>
        "ReadMerged":0,                         <Disk
        "ReadSectors":344,                          Path="/cache2"
        "ReadTime":117,                             Status="Normal"
        "Write":24,                                 Read="27"
        "WriteMerged":93,                           ReadMerged="1"
        "WriteSectors":936,                         ReadSectors="488"
        "WriteTime":256,                            ReadTime="144"
        "IOProgress":0,                             Write="24"
        "IOTime":173,                               WriteMerged="86"
        "IOWeightedTime":373                        WriteSectors="880"
      },                                            WriteTime="254"
      {                                             IOProgress="0"
        "Path":"/cache2",                           IOTime="189"
        "Status":"Normal",                          IOWeightedTime="380"/>
        "Read":27,                            </Storage>
        "ReadMerged":1,                       <ServerSocket
        "ReadSectors":488,                          Total="42"
        "ReadTime":144,                             Established="2"
        "Write":24,                                 Accepted="1"
        "WriteMerged":86,                           Closed="0"/>
        "WriteSectors":880,                   <ClientSocket
        "WriteTime":254,                            Total="1"
        "IOProgress":0,                             Established="0"
        "IOTime":189,                               Connected="0"
        "IOWeightedTime":380                        Closed="0"/>
      }                                       <TCPSocket
    ]                                               Established="30"
  },                                                Timewait="2"
  "ServerSocket":                                   Orphan="0"
  {                                                 Alloc="0"
    "Total":42,                                     Mem="20"/>
    "Established":1,                          <EQ>0</EQ>
    "Accepted":0,                             <RQ>1000000</RQ>
    "Closed":0                                <WaitingFiles2Write>0</WaitingFiles2Write>
  },                                          <ServiceAccess Allow="60" Deny="2"/>
  "ClientSocket":                             <SystemLoadAverage Min1="0" Min5="0" Min15="0"/>
  {                                           <URLRewrite>57</URLRewrite>
    "Total":1,                              </System>
    "Established":0,
    "Connected":0,
    "Closed":0
  },
  "TCPSocket":
  {
    "Established":30,
    "Timewait":2,
    "Orphan":0,
    "Alloc":0,
    "Mem":20
  },
  "EQ":0,
  "RQ":1000000,
  "WaitingFiles2Write":0,
  "ServiceAccess":{"Allow":60, "Deny":2}
  "SystemLoadAverage":
  {
    "Min1":0,
    "Min5":0,
    "Min15":0
  },
  "URLRewrite":57
}

• CPU (unit: 0.01%) CPU usage. Total CPU usage can be calculated by Kernel + User.
  • Kernel CPU (Kernel) usage.
  • User CPU (User) usage.
  • Idle Idle CPU.
  • ProcKernel CPU (Kernel) usage by STON.
  • ProcUser CPU (User) usage by STON.
  • Nice Time spent running ‘niced’ user processes.
  • IOWait Time spent waiting for I/O to complete.
  • IRQ Time spent servicing interrupts.
  • SoftIRQ Time spent servicing software interrupts.
  • Steal Time spent while other CPUs are serviced.
• Mem (unit: bytes) Memory usage.
  • Free Size of free memory in the system.
  • STON Size of memory used by STON.
• Disk Disk performance stats.
  • Path Disk path.
  • Status Disk status (Normal: normal, Invalid: excluded due to failure, Unmounted: unmounted by administrator).
  • Read The number of successful reads.
  • ReadMerged The number of merged reads.
  • ReadSectors The number of read sectors.
  • ReadTime (unit: ms) The elapsed time per read.
  • Write The number of successful writes.
  • WriteMerged The number of merged writes.
  • WriteSectors The number of written sectors.
  • WriteTime (unit: ms) The elapsed time per write.
  • IOProgress The number of running I/Os.
  • IOTime (unit: ms) The elapsed time per I/O.
  • IOWeightedTime (unit: ms) The elapsed time per I/O (weight applied).
• ServerSocket Server socket (between client and STON) information.
  • Total The total number of server sockets.
  • Established The number of connected server sockets.
  • Accepted The number of newly connected server sockets.
  • Closed The number of closed server sockets.
• ClientSocket Client socket (between STON and the origin server) information.
  • Total The total number of client sockets.
  • Established The number of connected client sockets.
  • Connected The number of newly connected client sockets.
  • Closed The number of closed client sockets.
• TCPSocket TCP status information provided by the system (OS).
  • Established The number of established status TCP connections.
  • Timewait The number of TIME_WAIT status TCP connections.
  • Orphan The number of orphaned TCP connections (not attached to a file handle).
  • Alloc The number of allocated TCP sockets.
  • Mem The amount of memory used by TCP sockets.
• EQ The number of unprocessed events in the STON Framework.
• RQ The number of events saved in the recently serviced content reference queue.
• WaitingFiles2Write The number of disk write pending files.
• ServiceAccess The number of sockets allowed and denied by ServiceAccess.
• SystemLoadAverage The 1/5/15 minute average of the System Load Average.
• URLRewrite The number of successful conversions made by the URL preprocessor.

Virtual Host Statistics¶

Statistics are provided for each virtual host. There are four types of virtual host statistics: HTTP transfer (per directory), URL bypass, port bypass, and SSL.

"VirtualHost":                               <VirtualHost
[                                                Name="image.11st.co.kr"
  {                                              Uptime="155956"
    "Name":"image.11st.co.kr",                   OriginSession="12"
    "Uptime":155966,                             OriginActiveSession="6"
    "OriginSession":12,                          OriginInbound="106914"
    "OriginActiveSession":6,                     OriginOutbound="3238"
    "OriginInbound":169,                         OriginReqCount="42"
    "OriginOutbound":269,                        OriginResTotalCount="13"
    "OriginReqCount":62,                         OriginResTotalTimeRes="1553"
    "OriginResTotalCount":1,                     OriginResTotalTimeComplete="6630"
    "OriginResTotalTimeRes":3300,                OriginRes2xxCount="1"
    "OriginResTotalTimeComplete":3300,           OriginRes2xxTimeRes="3300"
    "OriginRes2xxCount":0,                       OriginRes2xxTimeComplete="69300"
    "OriginRes2xxTimeRes":0,                     OriginRes3xxCount="12"
    "OriginRes2xxTimeComplete":0,                OriginRes3xxTimeRes="1408"
    "OriginRes3xxCount":1,                       OriginRes3xxTimeComplete="1408"
    "OriginRes3xxTimeRes":3300,                  OriginRes4xxCount="0"
    "OriginRes3xxTimeComplete":3300,             OriginRes4xxTimeRes="0"
    "OriginRes4xxCount":0,                       OriginRes4xxTimeComplete="0"
    "OriginRes4xxTimeRes":0,                     OriginRes5xxCount="0"
    "OriginRes4xxTimeComplete":0,                OriginRes5xxTimeRes="0"
    "OriginRes5xxCount":0,                       OriginRes5xxTimeComplete="0"
    "OriginRes5xxTimeRes":0,                     ClientSession="30"
    "OriginRes5xxTimeComplete":0,                ClientActiveSession="12"
    "ClientSession":26,                          ClientInbound="4113"
    "ClientActiveSession":16,                    ClientOutbound="895937"
    "ClientInbound":13968,                       ClientReqCount="64"
    "ClientOutbound":110398,                     ClientResTotalCount="18"
    "ClientReqCount":152,                        ClientResTotalTimeRes="666"
    "ClientResTotalCount":52,                    ClientResTotalTimeComplete="4377"
    "ClientResTotalTimeRes":94,                  ClientRes2xxCount="10"
    "ClientResTotalTimeComplete":107,            ClientRes2xxTimeRes="1200"
    "ClientRes2xxCount":1,                       ClientRes2xxTimeComplete="7870"
    "ClientRes2xxTimeRes":4700,                  ClientRes3xxCount="8"
    "ClientRes2xxTimeComplete":4800,             ClientRes3xxTimeRes="0"
    "ClientRes3xxCount":51,                      ClientRes3xxTimeComplete="12"
    "ClientRes3xxTimeRes":3,                     ClientRes4xxCount="0"
    "ClientRes3xxTimeComplete":15,               ClientRes4xxTimeRes="0"
    "ClientRes4xxCount":0,                       ClientRes4xxTimeComplete="0"
    "ClientRes4xxTimeRes":0,                     ClientRes5xxCount="0"
    "ClientRes4xxTimeComplete":0,                ClientRes5xxTimeRes="0"
    "ClientRes5xxCount":0,                       ClientRes5xxTimeComplete="0"
    "ClientRes5xxTimeRes":0,                     RequestHitRatio="10000"
    "ClientRes5xxTimeComplete":0,                ByteHitRatio="8806">
    "RequestHitRatio":10000,                   <FileSystem>
    "ByteHitRatio":9984,                         <RequestHitRatio>0</RequestHitRatio>
    "FileSystem":                                <ByteHitRatio>0</ByteHitRatio>
    {                                            <Outbound>0</Outbound>
      "RequestHitRatio":0,                       <Session>0</Session>
      "ByteHitRatio":0,                        </FileSystem>
      "Outbound":0,                            <Memory>784786700</Memory>.
      "Session":0                              <SecuredMemory>0</SecuredMemory>.
    },                                         <Disk> ... </Disk>
    "Memory":785740769,                        <Session> ... </Session>
    "SecuredMemory":0,                         <Dims> ... </Dims>
    "Disk": { ... },                           <Compression> ... </Compression>
    "Session": { ... },                        <File Total="458278" Opened="15" Instance="458292"/>
    "Dims": { ... },                           <Cached> ... </Cached>
    "Compression": { ... },                    <CacheFileEvent> ... </CacheFileEvent>
    "FileTotal":458308,                        <WaitingFiles2Delete>1087593</WaitingFiles2Delete>
    "FileOpened":15,                           <CacheFileEvent Create=\"%u\" Swap=\"%u\" Erase=\"%u\" Purge=\"%u\" Expire=\"%u\" />
    "FileInstance":458320,                     <ClientHttpReqBypass Sum="8100">27</ClientHttpReqBypass>
    "Cached": { ... },                         <ClientHttpReqDenied Sum="400">1</ClientHttpReqDenied>
    "CacheFileEvent": { ... },                 <OriginTraffic> ... </OriginTraffic>
    "WaitingFiles2Delete":1087595,             <PortBypass> ... </PortBypass>
    "ClientHttpReqBypassSum":8100,             <ClientTraffic> ... </ClientTraffic>
    "ClientHttpReqBypass":27,                  <UrlBypass> ... </UrlBypass>
    "ClientHttpReqDeniedSum":400,            </VirtualHost>
    "ClientHttpReqDenied":1,                 <VirtualHost> ... </VirtualHost>
    "OriginTraffic": { ... },                <VirtualHost> ... </VirtualHost>
    "PortBypass": { ... },                   <VirtualHost> ... </VirtualHost>
    "ClientTraffic": { ... },
    "UrlBypass": { ... }

  },
  ...
]

• Memory (unit: bytes) The amount of content loaded into memory.
• SecuredMemory (unit: bytes) The amount of content deleted from memory.
• Disk Disk information.
• Session Session information.
• Dims DIMS conversion statistics.
• Compression Compression statistics.
• FileTotal The total number of files.
• FileOpened The number of opened local files.
• FileInstance The number of caching files.
• Cached Caching information.
• CacheFileEvent A caching file event.
• WaitingFiles2Delete The number of files pending deletion.
• ClientHttpReqBypass The number of bypassed client HTTP requests.
• ClientHttpReqDenied The number of denied HTTP requests.
• OriginTraffic Origin server traffic statistics.
• PortBypass Port bypass traffic statistics.
• ClientTraffic Client traffic statistics.
• UrlBypass HTTP traffic statistics bypassed to the origin server via URL matching or <BypassNoCacheRequest>.

"Disk":                                      <Disk>
{                                              <TotalSize>22003701435</TotalSize>
  "TotalSize":22004057982,                     <Create>1</Create>
  "Create":0,                                  <Open>10</Open>
  "Open":1,                                    <Delete>0</Delete>
  "Delete":0,                                  <ReadCount>9</ReadCount>
  "ReadCount":1,                               <ReadSize>735726</ReadSize>
  "ReadSize":104744,                           <WriteCount>1</WriteCount>
  "WriteCount":0,                              <WriteSize>157145</WriteSize>
  "WriteSize":0,                               <Distribution
  "Distribution":                                U1K="45725"
  {                                              U2K="192523"
    "U1K="45725,                                 U4K="137055"
    "U2K="192523,                                U8K="39740"
    "U4K="137055,                                U16K="13408"
    "U8K="39740,                                 U32K="12303"
    "U16K="13408,                                U64K="11462"
    "U32K="12303,                                U128K="2560"
    "U64K="11462,                                U256K="22"
    "U128K="2560,                                U512K="0"
    "U256K="22,                                  U1M="45725"
    "U512K="0,                                   U2M="192523"
    "U1M="45725,                                 U4M="137055"
    "U2M="192523,                                U8M="39740"
    "U4M="137055,                                U16M="13408"
    "U8M="39740,                                 U32M="12303"
    "U16M="13408,                                U64M="11462"
    "U32M="12303,                                U128M="2560"
    "U64M="11462,                                U256M="22"
    "U128M="2560,                                U512M="0"
    "U256M="22,                                  U1G="0"
    "U512M="0,                                   U2G="0"
    "U1G="0,                                     U4G="0"
    "U2G="0,                                     U8G="0"
    "U4G="0,                                     U16G="0"
    "U8G="0,                                     O16G="0" />
    "U16G":0,                                  </Disk>
    "O16G":0

  }
}

"Session":                                   <Session
{                                              Client="30"
  "Client":30,                                 ActiveClient="20"
  "ActiveClient":20,                           Origin="12"
  "Origin":12,                                 ActiveOrigin="7" />
  "ActiveOrigin":7
},

"Dims":                                   <Dims
{                                           Requests="30"
  "Requests": 30,                           Converted="29"
  "Converted": 29,                          Failed="1"
  "Failed": 1,                              AvgSrcSize="1457969"
  "AvgSrcSize": 1457969,                    AvgDestSize="598831"
  "AvgDestSize": 598831,                    AvgTime="34" />
  "AvgTime": 34
},

"Compression":                             <Compression
{                                           Requests="30"
  "Requests": 30,                           Converted="29"
  "Converted": 29,                          Failed="1"
  "Failed": 1,                              AvgSrcSize="1457969"
  "AvgSrcSize": 1457969,                    AvgDestSize="598831"
  "AvgDestSize": 598831,                    AvgTime="34" />
  "AvgTime": 34
},

"OriginTraffic":                             <OriginTraffic>
{                                              <HttpReqCount Sum="600">2</HttpReqCount>
  "HttpReqCountSum":0,                         <HttpReqHeaderSize>3238</HttpReqHeaderSize>
  "HttpReqCount":0,                            <HttpReqBodySize>0</HttpReqBodySize>
  "HttpReqHeaderSize":269,                     <HttpResHeaderSize>2020</HttpResHeaderSize>
  "HttpReqBodySize":0,                         <HttpResBodySize>104894</HttpResBodySize>
  "HttpResHeaderSize":169,                     <Response>
  "HttpResBodySize":0,                           <ResTotal>
  "Response":                                      <Count Sum="8100">13</Count>
  {                                                <Completed Sum="8100">12</Completed>
    "ResTotal":                                    <TimeRes>1553</TimeRes>
    {                                              <TimeComplete>6630</TimeComplete>
      "CountSum":0,                              </ResTotal>
      "Count":1,                                 <Res2xx>
      "CompletedSum":0,                            <Count Sum="8100">1</Count>
      "Completed":1,                               <Completed Sum="8100">1</Completed>
      "TimeRes":3300,                              <TimeRes>3300</TimeRes>
      "TimeComplete":3300                          <TimeComplete>69300</TimeComplete>
    },                                           </Res2xx>
    "Res2xx":                                    <Res3xx>
    {                                              <Count Sum="8100">12</Count>
      "CountSum":0,                                <Completed Sum="8100">11</Completed>
      "Count":0,                                   <TimeRes>1408</TimeRes>
      "CompletedSum":0,                            <TimeComplete>1408</TimeComplete>
      "Completed":0,                             </Res3xx>
      "TimeRes":0,                               <Res4xx>
      "TimeComplete":0                             <Count Sum="8100">0</Count>
    },                                             <Completed Sum="8100">0</Completed>
    "Res3xx":                                      <TimeRes>0</TimeRes>
    {                                              <TimeComplete>0</TimeComplete>
      "CountSum":0,                              </Res4xx>
      "Count":1,                                 <Res5xx>
      "CompletedSum":0,                            <Count Sum="8100">0</Count>
      "Completed":1,                               <Completed Sum="8100">0</Completed>
      "TimeRes":3300,                              <TimeRes>0</TimeRes>
      "TimeComplete":3300                          <TimeComplete>0</TimeComplete>
    },                                           </Res5xx>
    "Res4xx":                                    <ConnectTimeout Sum="8100">0</ConnectTimeout>
    {                                            <ReceiveTimeout Sum="8100">0</ReceiveTimeout>
      "CountSum":0,                              <Close Sum="8100">0</Close>
      "Count":0,                               </Response>
      "CompletedSum":0,                        <Connect>
      "Completed":0,                             <Count>0</Count>
      "TimeRes":0,                               <AvgDNSQueryTime>0</AvgDNSQueryTime>
      "TimeComplete":0                           <AvgConnTime>0</AvgConnTime>
    },                                         </Connect>
    "Res5xx":                                </OriginTraffic>
    {
      "CountSum":0,
      "Count":0,
      "CompletedSum":0,
      "Completed":0,
      "TimeRes":0,
      "TimeComplete":0
    },
    "ConnectTimeoutSum":0,
    "ConnectTimeout":0,
    "ReceiveTimeoutSum":0,
    "ReceiveTimeout":0,
    "CloseSum":0,
    "Close":0
  },
  "Connect":
  {
    "Count":0,
    "AvgDNSQueryTime":0,
    "AvgConnTime":0
  }
},

"PortBypass":                                            <PortBypass SrcPort="1935" DestPost="1935">
[                                                          <Session>0</Session>
  {                                                        <Hit Established="0"
    "SrcPort":1935, "DestPort":1935, "Session":0,               ClientClosed="0"
    "Hit":                                                      OriginClosed="0"
    {                                                           OriginCT="0" />
      "Established":0, "ClientClosed":0,                   <ClientTraffic In="0" Out="0"/>
      "OriginClosed":0, "OriginCT":0                       <OriginTraffic In="0" Out="0"/>
    },                                                   </PortBypass>
    "ClientTraffic": { "In":0, "Out":0 },                <PortBypass SrcPort="1936" DestPost="1936">
    "OriginTraffic": { "In":0, "Out":0 }                   <Session>17</Session>
  },                                                       ...
  {                                                      </PortBypass>
    "SrcPort":1936, "DestPort":1936, "Session":17,
    ...
  }
],

"ClientTraffic":                             <ClientTraffics Depth="0" Accum="OFF" HttpsTraffic="OFF">
{                                              <TrafficCount>1</TrafficCount>
  "Depth":0,                                   <Traffic RequestHitRatio="0">
  "Accum":"OFF",                                 <Path>/</Path>
  "HttpsTraffic":"OFF",                          <HttpReqCount Sum="0">0</HttpReqCount>
  "TrafficCount":1,                              <HttpReqHeaderSize>4113</HttpReqHeaderSize>
  "Traffic":                                     <HttpReqBodySize>0</HttpReqBodySize>
  [                                              <HttpResHeaderSize>3066</HttpResHeaderSize>
    {                                            <HttpResBodySize>892871</HttpResBodySize>
      "RequestHitRatio" : 9984,                  <Response>
      "Path":"/",                                  <ResTotal>
      "HttpReqCountSum":0,                           <Count Sum="0">18</Count>
      "HttpReqCount":100,                            <Completed Sum="0">18</Completed>
      "HttpReqHeaderSize":13968,                     <TimeRes>666</TimeRes>
      "HttpReqBodySize":0,                           <TimeComplete>4377</TimeComplete>
      "HttpResHeaderSize":5654,                    </ResTotal>
      "HttpResBodySize":104744,                    <Res2xx>
      "Response":                                    <Count Sum="0">10</Count>
      {                                              <Completed Sum="0">10</Completed>
        "ResTotal":                                  <TimeRes>1200</TimeRes>
        {                                            <TimeComplete>7870</TimeComplete>
          "CountSum":0,                            </Res2xx>
          "Count":52,                              <Res3xx>
          "CompletedSum":0,                          <Count Sum="0">8</Count>
          "Completed":52,                            <Completed Sum="0">8</Completed>
          "TimeRes":94,                              <TimeRes>0</TimeRes>
          "TimeComplete":107                         <TimeComplete>12</TimeComplete>
        },                                         </Res3xx>
        "Res2xx":                                  <Res4xx>
        {                                            <Count Sum="0">0</Count>
          "CountSum":0,                              <Completed Sum="0">0</Completed>
          "Count":1,                                 <TimeRes>0</TimeRes>
          "CompletedSum":0,                          <TimeComplete>0</TimeComplete>
          "Completed":1,                           </Res4xx>
          "TimeRes":4700,                          <Res5xx>
          "TimeComplete":4800                        <Count Sum="0">0</Count>
        },                                           <Completed Sum="0">0</Completed>
        "Res3xx":                                    <TimeRes>0</TimeRes>
        {                                            <TimeComplete>0</TimeComplete>
          "CountSum":0,                            </Res5xx>
          "Count":51,                            </Response>
          "CompletedSum":0,                      <SSL RecvSize="0" SendSize="0"/>
          "Completed":51,                        <RequestHit
          "TimeRes":3,                             TCP_NONE="0"
          "TimeComplete":15                        TCP_HIT="0"
        },                                         TCP_IMS_HIT="0"
        "Res4xx":                                  TCP_REFRESH_HIT="0"
        {                                          TCP_REF_FAIL_HIT="0"
          "CountSum":0,                            TCP_NEGATIVE_HIT="0"
          "Count":0,                               TCP_REDIRECT_HIT="0"
          "CompletedSum":0,                        TCP_MISS="0"
          "Completed":0,                           TCP_REFRESH_MISS="0"
          "TimeRes":0,                             TCP_CLIENT_REFRESH_MISS="0"
          "TimeComplete":0                         TCP_DENIED="0"
        },                                         TCP_ERROR="0"/>
        "Res5xx":                                <RequestHitSum
        {                                          TCP_NONE="0"
          "CountSum":0,                            TCP_HIT="0"
          "Count":0,                               TCP_IMS_HIT="0"
          "CompletedSum":0,                        TCP_REFRESH_HIT="0"
          "Completed":0,                           TCP_REF_FAIL_HIT="0"
          "TimeRes":0,                             TCP_NEGATIVE_HIT="0"
          "TimeComplete":0                         TCP_REDIRECT_HIT="0"
        }                                          TCP_MISS="0"
      },                                           TCP_REFRESH_MISS="0"
      "SSL":                                       TCP_CLIENT_REFRESH_MISS="0"
      {                                            TCP_DENIED="0"
        "RecvSize":0,                              TCP_ERROR="0"/>
        "SendSize":0                           </Traffic>
      },                                       <FileSystem>
      "RequestHit":                              <GetAttr
      {                                            TimeRes="0"
        "TCP_NONE":0,                              FileCount="0"
        "TCP_HIT":0,                               DirCount="0"
        "TCP_IMS_HIT":0,                           FailCount="0">0</GetAttr>
        "TCP_REFRESH_HIT":0,                     <Open TimeRes="0">0</Open>
        "TCP_REF_FAIL_HIT":0,                    <Read
        "TCP_NEGATIVE_HIT":0,                      TimeRes="0"
        "TCP_REDIRECT_HIT":0,                      BufferSize="0"
        "TCP_MISS":0,                              BufferFilled="0">0</Read>
        "TCP_REFRESH_MISS":0,                    <RequestHit
        "TCP_CLIENT_REFRESH_MISS":0,               TCP_NONE="0"
        "TCP_DENIED":0,                            TCP_HIT="0"
        "TCP_ERROR":0                              TCP_IMS_HIT="0"
      },                                           TCP_REFRESH_HIT="0"
      "RequestHitSum":                             TCP_REF_FAIL_HIT="0"
      {                                            TCP_NEGATIVE_HIT="0"
        "TCP_NONE":0,                              TCP_REDIRECT_HIT="0"
        "TCP_HIT":0,                               TCP_MISS="0"
        "TCP_IMS_HIT":0,                           TCP_REFRESH_MISS="0"
        "TCP_REFRESH_HIT":0,                       TCP_CLIENT_REFRESH_MISS="0"
        "TCP_REF_FAIL_HIT":0,                      TCP_DENIED="0"
        "TCP_NEGATIVE_HIT":0,                      TCP_ERROR="0"/>
        "TCP_REDIRECT_HIT":0,                    <RequestHitSum
        "TCP_MISS":0,                              TCP_NONE="0"
        "TCP_REFRESH_MISS":0,                      TCP_HIT="0"
        "TCP_CLIENT_REFRESH_MISS":0,               TCP_IMS_HIT="0"
        "TCP_DENIED":0,                            TCP_REFRESH_HIT="0"
        "TCP_ERROR":0                              TCP_REF_FAIL_HIT="0"
      },                                           TCP_NEGATIVE_HIT="0"
      "FileSystem":                                TCP_REDIRECT_HIT="0"
      {                                            TCP_MISS="0"
        "GetAttr" :                                TCP_REFRESH_MISS="0"
        {                                          TCP_CLIENT_REFRESH_MISS="0"
          "TimeRes" : 0,                           TCP_DENIED="0"
          "FileCount" : 0,                         TCP_ERROR="0"/>
          "DirCount" : 0,                      </FileSystem>
          "FailCount" : 0,                   </ClientTraffics>
          "TotalCount" : 0
        },
        "Open" :
        {
          "TimeRes" : 0,
          "Count" : 0
        },
        "Read" :
        {
          "TimeRes" : 0,
          "BufferSize" : 0,
          "BufferFilled" : 0,
          "Count" : 0
        },
        "RequestHit":
        {
          "TCP_NONE":0,
          "TCP_HIT":0,
          "TCP_IMS_HIT":0,
          "TCP_REFRESH_HIT":0,
          "TCP_REF_FAIL_HIT":0,
          "TCP_NEGATIVE_HIT":0,
          "TCP_REDIRECT_HIT":0,
          "TCP_MISS":0,
          "TCP_REFRESH_MISS":0,
          "TCP_CLIENT_REFRESH_MISS":0,
          "TCP_DENIED":0,
          "TCP_ERROR":0
        },
        "RequestHitSum":
        {
          "TCP_NONE":0,
          "TCP_HIT":0,
          "TCP_IMS_HIT":0,
          "TCP_REFRESH_HIT":0,
          "TCP_REF_FAIL_HIT":0,
          "TCP_NEGATIVE_HIT":0,
          "TCP_REDIRECT_HIT":0,
          "TCP_MISS":0,
          "TCP_REFRESH_MISS":0,
          "TCP_CLIENT_REFRESH_MISS":0,
          "TCP_DENIED":0,
          "TCP_ERROR":0
        }
      }
    }
  ]
}

View¶

View is a method that ties multiple virtual hosts into one to extract statistics. The concept came from viewing multiple tables as one table in a database. As shown below, the setup is very simple.

# vhosts.xml

<Vhosts>
  <Vhost> ... </Vhost>
  <Vhost> ... </Vhost>
  ... (omitted) ...
  <View Name="SK">
    <Vhost>...</Vhost>
    <Vhost>...</Vhost>
  </View>
  <View Name="KT">
    <Vhost>...</Vhost>
    <Vhost>...</Vhost>
    <Vhost>...</Vhost>
  </View>
  <View Name="LG">
    <Vhost>...</Vhost>
    <Vhost>...</Vhost>
  </View>
</Vhosts>

View can even be set up with virtual hosts that don’t exist. The following are the formats that View provides statistics in.

-  Realtime XML/JSON
-  SNMP - cache(1.3.6.1.4.1.40001.1.4).10 ~ 12

Let’s explore an example where View can be used. Say there are three administrators running communities for their favorite sports: baseball.com, basketball.com, and football.com.

# vhosts.xml

<Vhosts>
  <Vhost Name="baseball.com"> ... </Vhost>
  <Vhost Name="basketball.com"> ... </Vhost>
  <Vhost Name="football.com"> ... </Vhost>
</Vhosts>

They decide to come together to open a combined sports community service, choosing sports.com as the domain name to encompass all the different sports. The objectives that must be met by the development/management team are as follows.

• The combined service must be provided through sports.com.
• The existing domains and services must be maintained for the existing users.
• The development teams must be combined. The management teams must be combined.
• Only the home page should be developed, connecting to existing services via links.

To realistically meet these demands, the development team decides to specify the existing domains as part of the first directory, as shown below.

# Existing services
http://baseball.com/standing/list.html
http://basketball.com/stats/2014/view.html
http://football.com/player/messi.php

# Combined service
http://sports.com/baseball/standing/list.html
http://sports.com/basketball/stats/2014/view.html
http://sports.com/football/player/messi.php

This can easily be configured using the URL preprocessor.

# vhosts.xml

<Vhosts>
  <Vhost Name="baseball.com"> ... </Vhost>
  <Vhost Name="basketball.com"> ... </Vhost>
  <Vhost Name="football.com"> ... </Vhost>
  <URLRewrite>
    <Pattern>sports.com/(.*)/(.*)</Pattern>
    <Replace>#1.com/#2</Replace>
  </URLRewrite>
</Vhosts>

The newly merged management team must now monitor not only their individual services but also the combined service (e.g. traffic, session, response codes). Most administrators familiar with SNMP will set up View to obtain these combined statistics.

# vhosts.xml

<Vhosts>
   <Vhost Name="baseball.com"> ... </Vhost>
   <Vhost Name="basketball.com"> ... </Vhost>
   <Vhost Name="football.com"> ... </Vhost>
   <URLRewrite>
      <Pattern>sports.com/(.*)/(.*)</Pattern>
      <Replace>#1.com/#2</Replace>
   </URLRewrite>
   <View Name="sports.com">
      <Vhost>baseball.com</Vhost>
      <Vhost>basketball.com</Vhost>
      <Vhost>football.com</Vhost>
   </View>
</Vhosts>

As seen in the above example, the combination of URL Rewrite and View can effectively tie existing sites together into a single service.

"View":                                  <View ...>
[                                           ...
  { ... },                               </View>
  { ... },                               <View> ... </View>
]                                        <View> ... </View>

Checking the Virtual Host List¶

The virtual host list can be checked.

http://127.0.0.1:10040/monitoring/vhostslist

The results are returned in JSON format.

{
    "version": "2.0.0",
    "method": "vhostslist",
    "status": "OK",
    "result": [ "www.example.com","www.winesoft.com", "site1.com" ]
}

Caching Information¶

The status of files being cached can be monitored. Generally, files can be distinguished by URLs, but if the same URL can have different options (e.g. Accept-Encoding), then there may also be multiple files.

http://127.0.0.1:10040/monitoring/fileinfo?url=example.com/sample.dat

The results are returned in JSON format. The following is the result of looking up the information of a /sample.dat file.

{
    "version": "2.0.0",
    "method": "fileinfo",
    "status": "OK",
    "result":
    [
        {
            "URI": "/sample.dat",
            "Accept-Encoding": "N",
            "RefCount": 0,
            "Disk-Index": 0,
            "Size": 2100267,
            "FID": 24267,
            "LocalPath": "/cache1/example.com/000i/q3.bin",
            "File-Opened ": "N",
            "File-Updating": "-",
            "Downloader-Count": "0",
            "LastAccess": "[ 2012.09.03 14:29:50, -2 ]",
            "UpdateTime": "[ 2012.09.03 13:53:43, -2169 ]",
            "TTL-Left": "[ 2012.10.03 13:53:43, 2589831 ]",
            "ResponseCode": 200,
            "ContentType": "text/plain",
            "LastModifiedTime": "[ 2010.11.22 20:31:47, -56224685 ]",
            "ExpireTime": "[ 0, 0 ]",
            "CacheControl": "not-specified",
            "ETag": "502dd614:200c2b",
            "CustomTTL": 0,
            "NoMoreExist": "N",
            "LocalFileExist": "Y",
            "SmallFile": "N",
            "State": "Cached",
            "Deleted": "N",
            "AddedSize": "Y",
            "TransferEncoding": "N",
            "Compression": "-",
            "Purge": "N",
            "Ignore-IMS ": "N",
            "Redirect-Location ": "-",
            "Content-Disposition ": "-",
            "NoCache": "N"
        }
    ]
}

• URI The file URI.
• Accept-Encoding (“Y” or “N”) “Y” if Accept-Encoding is supported.
• RefCount The file reference count.
• Size (bytes) The file size.
• Disk-Index (starts from 0) The saved disk index.
• FID The file ID.
• LocalPath The local path.
• File-Opened (“Y” or “N”) “Y” if a local file is opened.
• File-Updating Specifies the pointer to the updated object if a file is being updated.
• Downloader-Count The number of sessions downloading this file from the origin server.
• LastAccess (last accessed time, last accessed time - current time) [ 2012.09.03 14:29:50, -2 ] would mean that the file was last accessed 2 seconds before the current time, on 2012.09.03 14:29:50.
• UpdateTime (modified time, modified time - current time) The last time the file was modified. A 304 Not Modified response also updates the time.
• TTL-Left (expiration time, expiration time - current time) The time left until the content expires. The value is positive if there is still TTL left, and negative if already expired.
• ResponseCode The origin server response code.
• ContentType The MIME Type.
• LastModifiedTime (Last Modified Time, Last Modified Time - current time) The Last Modified Time sent by the origin server. If the origin server did not send this value, it will return zero.
• ExpireTime (Expire Time, Expire Time - current time) The Expire Time sent by the origin server. If the origin server did not send this value, it will return zero.
• CacheControl (“no-cache” or “not-specified” or an integer) The Cache-Control value sent by the origin server.
• ETag The ETag created by STON.
• CustomTTL Custom TTL. If not configured, zero is returned.
• NoMoreExist (“Y” or “N”) “Y” if file is pending deletion.
• LocalFileExist (“Y” or “N”) “Y” if the file exists locally (files not 200 OK are always “Y”).
• SmallFile (“Y” or “N”) “Y” is the file is considered a small file (for development purposes).
• State (“Not Init” or “Cached” or “Error”) The file status.
• Deleted (“Y” or “N”) “Y” if the file is deleted (for development purposes).
• AddedSize (“Y” or “N”) “Y” if the size is reflected in the statistics (for development purposes).
• TransferEncoding (“Y” or “N”) “Y” if Transfer-Encoding is supported.
• Compression The compression method.
• Purge (“Y” or “N”) “Y” if purged.
• Ignore-IMS (“Y” or “N”) “Y” if not configured to send an If-Modified-Since header during updates.
• Redirect-Location The Location header value.
• Content-Disposition The Content-Disposition header value.
• NoCache (“Y” or “N”) “Y” if the origin server responds with no-cache.

Log Trace¶

Receives the log in real time while it’s being recorded. Access, Origin, and Monitoring logs must specify a virtual host.

http://127.0.0.1:10040/monitoring/logtrace/info
http://127.0.0.1:10040/monitoring/logtrace/deny
http://127.0.0.1:10040/monitoring/logtrace/sys
http://127.0.0.1:10040/monitoring/logtrace/originerror
http://127.0.0.1:10040/monitoring/logtrace/access?vhost=www.site1.com
http://127.0.0.1:10040/monitoring/logtrace/origin?vhost=www.site1.com
http://127.0.0.1:10040/monitoring/logtrace/monitoring?vhost=www.site1.com

Variables¶

Values that can be changed by a configuration or intentionally by the administrator will be specified as [variable name]. For example, if multiple disks exist, each disk will be represented by a number, assigned in order starting from one. This variable will be labeled as [diskIndex].

• [diskIndex]

  Stands for the disks configured in storage.

  # server.xml - <Server><Cache>
  
  <Storage>
     <Disk>/cache1</Disk>
     <Disk>/cache2</Disk>
     <Disk>/cache3</Disk>
  </Storage>
  

  In the above environment with three configured disks, /cache1 has a [diskIndex] of 1 while /cache3 has a [diskIndex] of 3. For example, the OID that refers to the entire volume of /cache1 is system.diskInfo.diskInfoTotalSize.1 (1.3.6.1.4.1.40001.1.2.18.1.3.1). The last .1 refers to the first disk.

• [vhostIndex]

  Automatically assigned when virtual hosts are loaded.

  # vhosts.xml
  
  <Vhosts>
     <Vhost Status="Active" Name="kim.com"> ... </Vhost>
     <Vhost Status="Active" Name="lee.com"> ... </Vhost>
     <Vhost Status="Active" Name="park.com" StaticIndex="10300"> ... </Vhost>
  </Vhosts>
  

  In the example above, the first three virtual hosts loaded will be assigned a [vhostIndex] in order starting from 1. The virtual host will remember this [vhostIndex], and the indexes will not change even if virtual hosts are deleted. If virtual host deletion and loading take place at the same time, deletion will occur first, and the new new loaded virtual host will be assigned the empty [vhostIndex].

  

  Behavior of [vhostIndex]

• [diskMin] , [vhostMin]

  Refers to time in minutes. A value of 5 refers to an average over the last 5 minutes, while a value of 60 refers to an average over the last 60 minutes. This value has a range of 0 to 60, where 0 refers to real-time (1 second) data.

SNMP uses table structures for items with values that can change dynamically. For example, the number of values in “total disk size” can change with the number of disks, so a table is used. STON provides virtual host statistics in minute increments, allowing for more complex expressions such as “[vhostMin] . [vhostIndex]”.

This expression allows you to request statistics for each virtual host at your desired time increment, but because there are two variables, it is hard to represent in a table. This problem can be solved by setting a default value for [vhostMin] for SNMPWalk to run.

Activation¶

SNMP behavior and ACL can be configured in global settings (server.xml).

# server.xml - <Server><Host>

<SNMP Port="161" Status="Inactive">
   <Allow>192.168.5.1</Allow>
   <Allow>192.168.6.0/24</Allow>
</SNMP>

• <SNMP>

  SNMP behavior can be configured using these properties.

  • Port (default: 161) SNMP service port.
  • Status (default: Inactive) Activates SNMP when set to Active.

• <Allow>

  Configures IP addresses that allow SNMP access. Designated IP, designated IP range, bitmask, and subnet forms are supported. If the connected socket is not one of the approved IPs, no response is returned.

Virtual Host/View Variables¶

The number of virtual host/View variables and default time (minutes) provided by SNMP can be configured.

# server.xml - <Server><Host>

<SNMP VHostCount=0, VHostMin=5 ViewCount=0, ViewMin=5 />

• VHostCount (default: 0) If set to 0, only existing virtual hosts respond. If greater than 0, all configured virtual hosts will respond whether they exist or not.
• ViewCount (default: 0) Applies to View. (Same as VHostCount)
• VHostMin (default: 5 min, maximum: 60 min) Configures the value of [vhostMin]. Has a range of 0 to 60, with 0 resulting in real-time data and 1~60 resulting in an average over the set amount of time.
• ViewMin (default: 0) Applies to View. (Same as VHostMin)

In an example with three configured virtual hosts, SNMPWalk’s behavior can differ.

• If VHostCount=0

  SNMPv2-SMI::enterprises.40001.1.4.2.1.2.1 = STRING: "web.winesoft.co.kr"
  SNMPv2-SMI::enterprises.40001.1.4.2.1.2.2 = STRING: "img.winesoft.co.kr"
  SNMPv2-SMI::enterprises.40001.1.4.2.1.2.3 = STRING: "vod.winesoft.co.kr"
  

• If VHostCount=5

  SNMPv2-SMI::enterprises.40001.1.4.2.1.2.1 = STRING: "web.winesoft.co.kr"
  SNMPv2-SMI::enterprises.40001.1.4.2.1.2.2 = STRING: "img.winesoft.co.kr"
  SNMPv2-SMI::enterprises.40001.1.4.2.1.2.3 = STRING: "vod.winesoft.co.kr"
  SNMPv2-SMI::enterprises.40001.1.4.2.1.2.4 = ""
  SNMPv2-SMI::enterprises.40001.1.4.2.1.2.5 = ""
  

# server.xml - <Server><Host>

<SNMP GlobalMin="5" DiskMin="5" ConfCount="10" />

Community¶

Community can be configured to allow/deny access to the given OIDs.

# server.xml - <Server><Host>

<SNMP UnregisteredCommunity="Allow">
   <Community Name="example1" OID="Allow">
      <OID>1.3.6.1.4.1.40001.1.4.1</OID>
      <OID>1.3.6.1.4.1.40001.1.4.2</OID>
      <OID>1.3.6.1.4.1.40001.1.4.4</OID>
   </Community>
   <Community Name="example2" OID="Deny">
      <OID>1.3.6.1.4.1.40001.1.4.3.1.11.11.10.1-61</OID>
   </Community>
</SNMP>

If the UnregisteredCommunity value in <SNMP> is set to “Deny”, unregistered Community requests will be blocked.

• <Community> Configures Community.
  • Name The Community name.
  • OID (default: Allow) Configures the access of the <OID> tags below. If set to Allow, only the <OID> tags below will be allowed access. If set to Deny, the <OID> tags below will be denied access.

Specific OID (1.3.6.1.4.1.40001.1.4.4) and ranged OID (1.3.6.1.4.1.40001.1.4.3.1.11.11.10.1-61) formats are supported. When OIDs are allowed/denied, all OIDs set below will be configured the same way.

meta¶

OID = 1.3.6.1.4.1.40001.1.1

Provides meta information.

OID = 1.3.6.1.4.1.40001.1.1.10

system¶

OID = 1.3.6.1.4.1.40001.1.2

Provides information about the system running STON. The [sysMin] variable can be set from 0~60 minutes, allowing either real-time or averaged data. The [sysMin] in SNMPWalk can also be set to 0 to provide current information.

OID = 1.3.6.1.4.1.40001.1.2.18.1

OID = 1.3.6.1.4.1.40001.1.2.19.1

global¶

OID = 1.3.6.1.4.1.40001.1.3

Provides resource information (e.g. sockets, events) shared by all modules.

• ServerSocket

  The client-STON connection. This socket is used by STON to process client requests.

• ClientSocket

  The STON-origin server connection. This socket is used by STON to send requests to the origin server.

cache¶

OID = 1.3.6.1.4.1.40001.1.4

Cache service statistics are collected and provided in detail for each virtual host.

OID = 1.3.6.1.4.1.40001.1.4.1

OID = 1.3.6.1.4.1.40001.1.4.1.10

OID = 1.3.6.1.4.1.40001.1.4.1.11

OID = 1.3.6.1.4.1.40001.1.4.1.11.10

OID = 1.3.6.1.4.1.40001.1.4.1.11.11