EdgeScape User Guide

Version 2.0

August 2012

Akamai Technologies, Inc. US Headquarters 8 Cambridge Center Cambridge, MA 02142 Tel: 617.444.3000 Fax: 617.444.3001 US Toll free 877.4AKAMAI (877.425.2624)

For a list of offices throughout the world, see: http://www.akamai.com/html/about/locations.html

Copyright 2008-2012 Akamai Technologies, Inc. All Rights Reserved.

Reproduction in whole or in part in any form or medium without express written permission is prohibited. Akamai, the Akamai wave logo, Faster Forward and the names of certain Akamai products referenced herein are trademarks or service marks of Akamai Technologies, Inc. Third party trademarks and service marks contained herein are the property of their respective owners and are not used to imply endorsement of Akamai Technologies, Inc. or its services. While every precaution has been taken in the preparation of this document, Akamai Technologies, Inc. assumes no responsibility for errors, omissions, or for damages resulting from the use of the information herein. The information in these documents is believed to be accurate as of the date of this publication but is subject to change without notice. The information in this document is subject to the confidentiality provisions of the Terms & Conditions governing your use of Akamai services and/or other agreements you have with Akamai.

Contents

Introduction ....................................................................................... 5
Overview ........................................................................................................... 5 Audience ............................................................................................................ 5 Other Resources .................................................................................................. 5

Chapter 1

EdgeScape Component Overview .......................................................................... 6 AkaClient API ..................................................................................................... 7 Facilitator ........................................................................................................... 7 EdgeScape Authorization Server (EAS) ................................................................... 7

How the EdgeScape Service Works .............................. 6

Chapter 2

EdgeScape Database Availability ............................................................................ 8 NOCC Monitoring of EdgeScape ........................................................................... 8 EdgeScape Facilitator ........................................................................................... 9 EdgeScape API ................................................................................................... 9

EdgeScape Performance ............................................... 8

Chapter 3

EdgeScape System Requirements ................................. 9

Chapter 4

Installation Process ............................................................................................ 10 Unix-based Installation ............................................................................... 10 Windows-based Installation......................................................................... 11 File Locations ........................................................................................... 12 Configuration Process ........................................................................................ 13 Facilitator Startup Script ............................................................................. 13 Using Facilitator with a Proxy ...................................................................... 13 Configuration File ..................................................................................... 13 Configuration File Attributes ....................................................................... 15 Running the Facilitator ....................................................................................... 17 Running EdgeScape as a Service (Windows users only) ............................................ 17 EdgeScape Facilitator Console ............................................................................. 18

Installing the EdgeScape Service ................................ 10

Chapter 5

The EdgeScape Database .................................................................................... 20 C API 23 Compiling on Linux/Solaris ........................................................................ 23 Compiling on FreeBSD .............................................................................. 23 Compiling using Microsoft Visual Studio 6 .................................................... 23

Implementing the EdgeScape API .............................. 20

Compiling using Borland C++ Builder 5 ....................................................... 23 Using the C API ........................................................................................ 24 Retrieving attribute values ........................................................................... 24 Load balancing .......................................................................................... 25 Perl API ........................................................................................................... 26 Retrieving attribute values ........................................................................... 26 Load balancing .......................................................................................... 27 PHP API .......................................................................................................... 28 Retrieving attribute values ........................................................................... 28 Load balancing .......................................................................................... 29 Java API........................................................................................................... 30 Load balancing .......................................................................................... 31 COM Interface .................................................................................................. 33 API Default Output ........................................................................................... 34

Chapter 6

Temp files on Windows .............................................................................. 35 Memory leak in Perl 5.8.0............................................................................ 35

Known Issues ............................................................. 35

Chapter 7

Troubleshooting ................................................................................................ 36 Frequently Asked Questions ................................................................................ 37

Troubleshooting and FAQs ........................................ 36

Appendix A

API Function Return Codes ....................................... 38

Proprietary and Confidential

EdgeScape User Guide

Introduction
Overview
Welcome to Akamais EdgeScapeSM service. The EdgeScape Product suite consists of both the EdgeScape and EdgeScape Pro services. Unless otherwise denoted in this document, the term EdgeScape refers to both services. EdgeScape is designed to easily integrate with your Web site, allowing you to access information about how your users access the Internet. This includes information that maps a users IP address to geography and network attributes like the users country and connection speed. The User Guide describes the EdgeScape architecture, identifies the components that run in your environment, and defines the application programming interface (API) used to interface with the EdgeScape service. This document provides complete instructions for installing the EdgeScape service.

Audience
This document is the EdgeScape User Guide, and is intended for programmers and administrators implementing the EdgeScape service.

Other Resources
If you have any questions while using this guide, please contact Akamai Customer Care at 1877-AKATEC or ccare@akamai.com.

Proprietary and Confidential

EdgeScape User Guide

Chapter 1

How the EdgeScape Service Works

EdgeScape Component Overview
The EdgeScape Service is architected using three subsystems or components, AkaClientAPI, Facilitator, and EdgeScape Authorization Server (EAS), that interact with your application environment. The AkaClientAPI is a small piece of source code that is integrated into your application and makes queries to the Facilitator. The Facilitator is a process that runs in your application environment and is responsible for the overhead associated with establishing a connection between the application and the Akamai platform, specifically the EAS. The Facilitator is also responsible for listening and responding to requests from the AkaClientAPI. EAS is a process that runs in multiple locations on the Akamai platform. The primary purpose of the EAS component is to manage updates to the EdgeScape database that is stored on your Facilitator machine.

EdgeScape Components
Akamai Managed Environment
EdgeScape Authorization Server Customer Web Server or Application Server

Customer Environment

EAS

AkaClientAPI
SSL Connection UDP queries UDP responses

Facilitator

Akamai platform

HTTP Connection

EdgeScape DB

Figure 1 EdgeScape Architecture

Proprietary and Confidential

EdgeScape User Guide

AkaClient API
AkaClientAPI is source code that is integrated into your Web and/or application servers to make queries to the Facilitator. This Application Programming Interface (API) is available in the C Programming language, as a Java Class, and as a Perl script. Examples of how to use each of these APIs are provided in Implementing the EdgeScape API.

Facilitator
The Facilitator is a daemon process that runs directly on your Web server or application server. The basic function of the Facilitator is to be queried by instances of the AkaClientAPI, and to handle all of the complexities of fetching the answers. The Facilitator is responsible for several functions. Upon starting up, the Facilitator uses DNS to retrieve a list of EASs to connect to. The Facilitator makes an SSL connection to port 8443/443 (user-configurable) of the first live EAS. The EAS then sends an SSL certificate to the Facilitator, proving its authenticity as an EAS. The Facilitator is responsible for requesting authentication and authorization as well as securing communication between your application and the Akamai platform. The authentication and authorization step involves the Facilitator sending its certificate to the EAS. If the certificate is successfully authenticated, the Facilitator is told what files to download from the Akamai platform. The Facilitator reconnects to the EAS every 12 hours to request authorization and to receive updates to the EdgeScape database. If the Facilitator cant connect to the EAS, it continues to use the database it has locally; however, repeated failures to connect will result in the Facilitator shutting down to prevent theft of service. The Facilitator begins listening on port 2001 for UDP requests from the AkaClientAPI processes. Note that communication between the AkaClientAPI and the Facilitator is not secure. Therefore, either the AkaClientAPI and the Facilitator should reside on the same server, or the AkaClientAPI and the Facilitator should communicate over a secure network.

EdgeScape Authorization Server (EAS)

EAS is a process that runs on the Akamai platform, authenticating connection requests from Facilitators by verifying the certificate received from each Facilitator. The certificate sent by the Facilitator to the EAS is a GPG signed certificate using the Digital Signature Algorithm (DSA). Once the EAS successfully authenticates the Facilitator, it sends the Facilitator an ARL (Akamai Resource Locator) that the Facilitator uses to download the EdgeScape database files from the Akamai platform. Since these files are encrypted, the EAS also sends the Facilitator the decryption key to use to decrypt the files.

Proprietary and Confidential

EdgeScape User Guide

Chapter 2

EdgeScape Performance
EdgeScape Database Availability
The EdgeScape service is built with failover and high availability technology. The EdgeScape database files are distributed via the Akamai network to ensure speedy and reliable downloads of the database. Also, as the Facilitator uses DNS to determine which EAS to connect to, the Facilitator is able to easily failover to another EAS if the primary one begins to fail. In the unlikely event that no EASs are available, the Facilitator continues to operate with the database it currently has for 30 days (as long as the Facilitator is not shutdown).

NOCC Monitoring of EdgeScape

The EdgeScape service is managed and monitored by the Akamai NOCC in a similar way as the Akamai network. Each EAS reports its status to Akamais NOCC using the same monitoring and alerting system used across the Akamai network. The Akamai NOCC also has a system to poll EAS processes, and alerts generate automatically if EAS processes or servers are experiencing errors.

Proprietary and Confidential

EdgeScape User Guide

Chapter 3

EdgeScape System Requirements

The EdgeScape components that are installed on your Web or application server include the Facilitator and the AkaClientAPI. EdgeScape customers must meet the following requirements for each.

EdgeScape Facilitator
The EdgeScape Facilitator is included in the EdgeScape Engine Package, which is available on the Akamai portal (https://control.akamai.com). If you are using a Unix-based system, download the Unix EdgeScape Engine Package. You will also need to download and install Sun JRE (v6 or higher) that will work on your system. If you are using a Windows-based system, download the Windows EdgeScape Engine Package. This package includes a JRE, so no additional software is required. Memory and disk requirements are 1024 MB (1 GB) for all operating systems.

EdgeScape API
The API is available in C, Java, Perl, PHP, and COM. Language Perl Java PHP C Compiler/Interpreter Operating System Perl 5.0 (or higher) interpreter Any (certified on RedHat 6.1, Solaris 2.6, Solaris 2.8, Win2K, Windows XP) JDK 1.2 (or higher) compiler PHP 4.3.0 (or newer) gcc MS Visual Studio 6 (MS Platform SDK required) Borland C++ Builder 5.0 COM JRE 1.1 Any (certified on RedHat 6.1, Solaris 2.6, Solaris 2.8, Win2K, Windows XP) Any (certified on RedHat 6.1, Solaris 2.6, Solaris 2.8, Win2K, Windows XP) Any UNIX-based platform (certified on RedHat 6.1, Solaris 2.6, Solaris 2.8) Windows (certified on Win2K and Windows XP) Windows (certified on Win2K and Windows XP) Windows XP

Proprietary and Confidential

EdgeScape User Guide

Chapter 4

Installing the EdgeScape Service

Using the EdgeScape Service requires three preliminary steps: Download the EdgeScape Engine package and certificate and installing the software as appropriate. See Installation Process for instructions. Configure the EdgeScape Facilitator. See Configuration Process for instructions. Run the Facilitator. See Running the Facilitator for instructions.

Installation Process
Download the EdgeScape software package and certificate from the Akamai portal at https://control.akamai.com. Follow the appropriate installation procedure to install the software on the machine that will be running the Facilitator. Note: If you are installing your own JRE, it must be Sun JRE version 6 or higher. You may need to make the following change to the java.security file located in jre/lib/security/: Uncomment the networkaddress.cache.ttl line, and change the value from -1 to 1

Unix-based Installation
To perform a Unix-based installation: 1. Untar and unzip the software package in the directory you want to install EdgeScape in. Note: GNU tar must be used when untaring the .tgz file. For example: mkdir <edgescape-install-dir> mv edgescape.tgz <edgescape-install-dir> cd <edgescape-install-dir> tar xfz edgescape.tgz

2. The following directories are created in <edgescape-install-dir>: api, config, logs, sbin, tmp . 3. Copy the certificate file to the config sub-directory of <edgescape-install-dir>: config/facil.cert.gpg

4. After downloading and installing a JRE, copy all the files in <edgescape-install-dir>/lib to <directory-where-jre-resides>/jre/lib/ext. Alternatively, you may set the classpath in sbin/Facilitator.sh to point to <edgescape-install-dir>/lib as follows (the quotes are necessary): $PATHTOJRE/jre/bin/java classpath $ESPATH/lib/*

10

Proprietary and Confidential

EdgeScape User Guide

5. In sbin/Facilitator.sh and sbin/runFacilitator.sh, change <path-to-jre> to point to the directory where the JRE resides and change <edgescape-install-path> to the directory where EdgeScape is installed.

Windows-based Installation
To perform a Windows-based installation: 1. Unzip the edgescape.zip file into a temporary directory. 2. Double-click on the EdgeScape Setup icon to start an Install Shield installation process that installs EdgeScape to a directory you specify. The following directories are created in <edgescape-install-dir>: api, config, jre, logs, sbin, tmp. 3. Copy the certificate file to the config sub-directory of <edgescape-install-dir>: config/facil.cert.gpg The EdgeScape installation modifies your Windows Registry so that EdgeScape can be run as a service. For more information, refer to the section on Running EdgeScape as a Service.

Proprietary and Confidential

11

EdgeScape User Guide

File Locations
After you finish installing the software package, important files and directories exist in the following locations: Directory or File Location sbin/Facilitator.sh (UNIX-based platforms) sbin/Facilitator.bat (Windowsbased platforms) config/ api/ logs/ sbin/runFacilitator.sh (Unixbased platforms) Location of the configuration file, certificate file, and keystore Location of API files for C, Java, and Perl Location of the log files that the Facilitator process writes to Script that starts the Facilitator and restarts it if it dies. Note that if this script is used, performing a shutdown operation through the console will not work, since this script will restart the Facilitator (section 6.5 for more details on the Console) Location of EdgeScape jar files Description Script that starts the Facilitator

jre/lib/ext/

12

Proprietary and Confidential

EdgeScape User Guide

Configuration Process
Before starting the Facilitator, you need to make changes to the Facilitators startup script and configuration file. On Unix, these files are sbin/Facilitator.sh and config/facil.conf respectively On Windows, they are sbin/Facilitator.bat and config/facil.conf.txt.

The necessary changes are listed below.

Facilitator Startup Script

Unix: In sbin/Facilitator.sh and sbin/runFacilitator.sh, change <path-to-jre> to reflect the full path to the directory that contains your JRE and change <edgescape-install-path> to reflect the full path to the directory where EdgeScape is installed. Spaces are not allowed in the path, and the name is case-sensitive. Windows: Change the FACILPATH setting in sbin/Facilitator.bat to reflect the full path of the installation directory. If the directory names contain spaces, use the MSDOS name for that directory. For example, if you use the default installation path, then replace <edgescape-install-path> with c:\progra~1\akamai~1\edgescape. If the directory name does not contain spaces, using the MSDOS name is optional. The Facilitator allows logging of all IPs queried (disabled by default). To turn this feature on, add logqueries immediately after com.akamai.edgescape.Facilitator.Facilitator in Facilitator.sh or runFacilitator.sh on Unix, or in Facilitator.bat on Windows. However, enabling this feature will lead to Facilitator performance degradation.

Using Facilitator with a Proxy

If the machine running the Facilitator is behind a proxy, you will need to add the following just before com.akamai.edgescape.Facilitator.Facilitator in the Facilitator Startup Script (sbin/Facilitator.sh on Unix, sbin/Facilitator.bat on Windows): -Dhttps.proxyHost=<name of https proxy server> -Dhttps.proxyPort=<port of https proxy server> -Dhttp.proxyHost=<name of http proxy server> -Dhttp.proxyPort=<port of http proxy server> If the proxy doesnt allow outbound connections to port 8443, you will need to set the target_port in facil.conf to 443.

Configuration File
Unix: Change every occurrence of <edgescape-install-path> in config/facil.conf to reflect the full path name of the location that youd like the files to reside in. Spaces are not allowed in directory names when replacing <edgescape-install-path> with your desired path, and the name is case-sensitive. Windows: Change every occurrence of <edgescape-install-path> in config/facil.conf.txt to reflect the full path name of the location that youd like the files to reside in. If the directory names contain spaces, use the MSDOS name for that directory. For example, if you use the default installation path, then replace <edgescape-install-path> with Proprietary and Confidential 13

EdgeScape User Guide

c:\progra~1\akamai~1\edgescape. If the directory name does not contain spaces, using the MSDOS name is optional. It is important to ensure that the directories you specify actually exist before starting the Facilitator. Otherwise, an error prints to standard output and the Facilitator exits.

14

Proprietary and Confidential

EdgeScape User Guide

Configuration File Attributes

The following table lists the attributes in the configuration file and a description of each. You must restart the Facilitator process for any changes in configuration to take affect. Note: You must configure the six attributes marked with an asterisk (*), as they indicate file or directory locations. Make sure that these locations account for the <edgescape-installpath> configuration you performed above. listen_on This attribute defines the IP addresses that the Facilitator listens to for incoming queries. The two possible values for this attribute are: The keyword: any (this value allows any IP address to query the Facilitator, and is the default). A single IP address listen_port This attribute defines the port that the Facilitator listens on for incoming queries. By default it is set to 2001. However, you can set this to any desired port, provided that the same port is set in the API (see Implementing the EdgeScape API for more information). This attribute is set to eas.akadata.akadns.net, which is the DNS name that resolves to the IP addresses of the EdgeScape Authorization servers. This should not be changed unless you are directed to do so by an Akamai representative. This attribute defines the port that the Facilitator connects to on the EAS. By default, it is set to 8443. However, you can change this to 443 if you wish. No other values may be entered for this attribute. The EdgeScape service comes with a console through which you can view the status of the Facilitator, as well as reboot or shut it down. The console_port attribute defines the local port that this console runs on. You can access the console by pointing your Web browser to http://localhost:<console_port> The console requires a username for entry. 15

target

target_port

console_port

console_username Proprietary and Confidential

EdgeScape User Guide

By default, the username is set to edgescape. console_password *log_file The console requires a password for entry. By default, there is no password. This attribute sets the filename to which the Facilitator writes useful logging information. There are 5 possible settings for this attribute: none, info, warn, error, fatal. Setting this attribute to none results in nothing being written to the log file. Setting it to any other setting prints out log messages of that type or more severe. The Facilitator has built-in log rotation. This attribute sets the maximum size the log file should grow to before being rotated, and is measured in bytes. This attribute sets the maximum number of log files that remain on disk, with older files being removed first to make room for newer files. This attribute sets the filename that the Facilitator writes to if the logqueries option is set in Facilitator.sh or Facilitator.bat. Information for every IP queried is then sent to this file (not including queries that are made through the EdgeScape console) Similar to the log_file_max_size setting. Similar to the log_file_max_num setting. Setting this attribute to true results in the query_log_file being in the same format as the log file in version 1 of Edgescape. However, doing so results in greater Facilitator performance degradation than if it is left set to false. The only difference in format between EdgeScape version 1 and version 2 is the date/time stamp which by default is set to false. Location of the file that the Facilitator uses to verify the EASs SSL certificate. Location of GPG certificate file. Proprietary and Confidential

log_level

log_file_max_size

log_file_max_num

*query_log_file

query_log_file_max_size query_log_file_max_num enable_legacy_query_log_format

*trust_file *certif_file 16

EdgeScape User Guide

*download_directory

Directory to which the Facilitator downloads database files from the Akamai platform Directory in which EdgeScape database files are stored after they have been fully downloaded and installed.

*temp_directory

Running the Facilitator

Unix: Run either the Facilitator.sh or runFacilitator.sh scripts in the sbin directory. You will see a Facilitator process with Java sub-processes in your process tree. Windows: Double-click on the EdgeScape icon in the Start menu, or double-click the Facilitator.bat file located in the sbin directory. An MSDOS window should flash on the screen for a few moments, and then close itself; if the window remains open, you can close it manually. Youll notice a JAVAW process if you look in the Task Manager. Once the Facilitator is started, you can use the EdgeScape Facilitator Console to administer it. If you wish to shutdown or reboot the Facilitator, the recommended method is to use the shutdown or reboot functions in the Console. If you shutdown the Facilitator, the console is no longer operational. To make queries to the Facilitator, use the APIs provided or enter IP addresses in the box provided on the Console. Note that it takes a few minutes for the Facilitator to download and install the database upon startup; during this time, default_answers are returned for all queries. However, subsequent upgrades to the database happen seamlessly, with no interruption of service.

Running EdgeScape as a Service (Windows users only)

If the EdgeScape icon is used to start EdgeScape, and the user subsequently logs out of the machine, the Facilitator will stop running. However, the EdgeScape installation modifies your Windows Registry so that EdgeScape can be run as a service. To run EdgeScape as a service, reboot the machine after installing EdgeScape. The EdgeScape service will be started automatically when Windows boots, and will remain running whether any user logs in or out. Note that if your machine is restarted without making the appropriate changes to facil.conf.txt and Facilitator.bat, the service will not start correctly. Specific instructions for running on Win2K/NT or Win98 are as follows. Win2K/NT An EdgeScape key has been added to the Windows Registry at the following location: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\EdgeScape

Proprietary and Confidential

17

EdgeScape User Guide

If you do not wish for EdgeScape to be able to be run as a service, remove this key from the Registry. Any error messages generated when running EdgeScape as a service will be written to a log file in the \logs directory of <edgescape-install-path>. You must use the Services tool in the Control Panel to start/stop EdgeScape when running as a service. If you do not wish for the EdgeScape service to start automatically when Windows boots, but instead want to be able to manually start the service after logging in, change the Startup Type property for EdgeScape from automatic to manual using the Services tool. By default, the EdgeScape service will run without the logqueries option. If you wish to turn this option on when running as a service, make the following changes to the Registry: Use regedit to edit the Windows Registry Go to the following key: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\EdgeS cape\Parameters Modify the value of Start Param Count to be 2. Change the name of Start Param Number 0 to be Start Param Number 1 Add a new String Value called Start Param Number 0. Modify its value to be logqueries

Win98 The following value has been added to the Windows Registry: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\RunService s\EdgeScape If you do not wish for EdgeScape to be able to be run as a service, remove this value from the Registry. It is recommended that you backup your Registry before making any changes.

EdgeScape Facilitator Console

After youve started the Facilitator, you can use the Web-based console to check its status, review its log file, reboot it, or shut it down. To access the EdgeScape Facilitator Console and display Facilitator status: 1. Point your Web browser to http://localhost:2003 (2003 is the default console port, and can be changed in the configuration file). 2. Enter the console_username and console_password in the dialog box that appears (see Configuration File Attributes for information on the console_username and console_password). The consoles main window displays the Facilitators status. There are 4 additional functions you can perform through the Console: 18 Proprietary and Confidential

EdgeScape User Guide

logfile This function allows you to view the log file. reboot This function reboots the Facilitator. Rebooting causes the Facilitator to re-read its configuration file as well as reconnect to the EAS. shutdown This function shuts the Facilitator down. Note that if the runFacilitator.sh script is used on Unix, then the Facilitator restarts. To shut it down completely, you have to end the process manually. query Enter IP addresses or hostnames in the text box to perform queries to the Facilitator.

Proprietary and Confidential

19

EdgeScape User Guide

Chapter 5

Implementing the EdgeScape API

The EdgeScape Database
The EdgeScape Database contains the following information about an IP address. Attributes are available via the API. Query for attributes using the spelling shown here. (Omit any asterisks (*) from your query). For the most current listing of data code values, please log into the Akamai customer portal at https://control.akamai.com. Attribute = type Geography continent = string country_code = string region_code = string Description The continent value is a two-letter code for the continent that the IP address maps to. The country_code value is an ISO-3166, two-letter code for the country where the IP address maps to. The region_code value is an ISO-3166, two-letter code for the state, province, or region where the IP address maps to. The city value is the city (within a 50-mile radius) that the IP address maps to. The dma value is a number representing the DMA that the IP address maps to. DMA is a registered service mark of The Nielsen Company, all rights reserved. The msa value is a number representing the Metropolitan Statistical Area that the IP address maps to. The pmsa value is a number representing the Primary Metropolitan Statistical Area that the IP address maps to. The areacode value is the area code that the IP address maps to (multiple values possible) The lat value is the latitude that the IP address maps to The long value is the longitude that the IP address maps to The county value is the county that the IP address maps to (multiple values possible) The timezone value is the time zone that the IP address maps to The zipcode value is the zipcode that the IP address maps to (multiple values possible)

*city = string *dma = string

*msa = string

*pmsa = string

*areacode = string *lat = string *long = string *county = string *timezone = string *zip = string

20

Proprietary and Confidential

EdgeScape User Guide

Attribute = type Network network = string network_type = string asnum = string Description The network value will be the network that the IP address belongs to. The network type value will be the connection type that the IP address belongs to. The asnum value will be the AS number or numbers that the IP belongs to (multiple values possible) The throughput is the actual connection speed that the IP address maps to. Provides additional granularity to the throughput field. This attribute indicates whether the IP is a proxy and what type of proxy it is (transparent or anonymous).

*throughput = string *bw = integer *proxy = string

Attribute = type Corporate Identity *company = string *domain = string Description The company value will be the company that the IP address belongs to. The domain value will be the domain that the IP address belongs to.

* Denotes attributes only available with the EdgeScape Pro service. The entire IP address space is represented in the database and always has a Country Code associated with it. All other elements in the database, including Region Code, are optional and may not necessarily be associated with an IP address. In addition, for AOL IPs, only Country information will be returned. However, if the IP is in the reserved IP space (as designated by the Internet Assigned Numbers Authority), every attribute has a value of reserved. If an attribute contains multiple values, each value will be separated by the plus (+) character. In the case of the zip attribute, contiguous zip codes will be represented as a range of the form FirstZipInRange-LastZipInRange, and multiple ranges may be present (each range separated by the plus (+) character). For example, the following strings are all valid zip values: 10001 10001+10003 10001-10003+10005 10001-10003+10005-10008 Proprietary and Confidential 21

EdgeScape User Guide

22

Proprietary and Confidential

EdgeScape User Guide

C API
Before compiling the API, be sure to change two settings in AkaData.h: GLOBALHOST and GLOBALPORT. These values should be set to the IP address and port of the Facilitator that you will be making queries to. By default, these values are set to 127.0.0.1 and 2001 respectively, and assume that the client is running on the same machine as the Facilitator; this is the recommended setup for the API. However, you might wish to change it based on your configuration. Once the Facilitator IP address and port settings are correct, compile the provided C source and header files, AkaData.c and AkaData.h, located in the <edgescape-installdir>/api directory, into your application. A demo program called AkaData_Demo.c is provided for you to get acquainted with the C API. This program is only meant to be a demo; you may modify the demo file as well as the AkaData.c file to suit your needs.

Compiling on Linux/Solaris
In order to compile the API, you need to include the pthread library; you might also need to include the libraries resolve, socket, and nsl. You must compile the ak_socket.c file as well. The following example compiles the demo program into a binary named AkaDemo: gcc AkaData.c ak_socket.c AkaData_Demo.c lpthread lresolv lsocket lnsl o AkaDemo

Compiling on FreeBSD
You should only need to include the pthread library. Note that the command is slightly different than when compiling on Linux/Solaris: gcc AkaData.c ak_socket.c AkaData_Demo.c pthread o AkaDemo

Compiling using Microsoft Visual Studio 6

In order to use MS Visual Studio 6, the MS Platform SDK is required. Open the included .dsw file and build AkaDemo.exe.

Compiling using Borland C++ Builder 5

Open the included .bpr file and build AkaDemo.exe. The C API has been tested on the above platforms. If you have any difficulty building the API on these platforms, please contact Akamai Customer Care at ccare@akamai.com.

Proprietary and Confidential

23

EdgeScape User Guide

Using the C API

The API is used to perform a lookup by calling the akamai_ip_lookup function, using the following parameters:
akamai_ip_lookup(const in_addr_t *addr, char *buffer, size_t *len, struct timeval *timeout)

The arguments to this function are: addr buffer len An Internet family address (ipv4) that specifies the address being queried. If that is not available, you may also pass in the 32-bit number. A pointer set to the buffer that will contain the result of this function. An argument/result. It will contain the length of the buffer on calling and will return the length of the data on result. Please note that if the buffer is too short, you will get an error. The amount of time for which the function should block waiting on an answer. If this time expires, the buffer will contain the default answer instead, and the return code will indicate so.

timeout

The result codes for this function can be any possible value, but constants are used to indicate the meaning. A value of zero is a success code, while any other value is an error. See the API Function Return Codes appendix for a list of possible return codes. The resulting buffer contains the IP resolution answer. This answer is encoded as a list of entries separated with null characters and terminated with a null character. A plus (+) character separates multiple values for an attribute. Each entry is an attribute/value pair separated by an equal(=) sign.

Retrieving attribute values

EdgeScape provides a convenience function for retrieving a particular attribute's value. You arent required to use this function, but for retrieving a specific attribute regularly (for example, country_code), you might want to use it. The convenience function uses the following parameters:
akamai_attr_get(const char *attr, const char *buffer, const size_t buffer_len, char **result)

24

Proprietary and Confidential

EdgeScape User Guide

The arguments to this function are: attr buffer buffer_len result A null-terminated string indicating the name of the attribute desired. A pointer to the result buffer returned from akamai_ip_lookup A length for the buffer (as was passed in). A pointer to the address IN the buffer where the value for the attribute is specified (right after the equal sign). If the attribute does not exist, the result will point to NULL.

The return codes here match those of akamai_ip_lookup. See the API Function Return Codes appendix for more information.

Load balancing
Five additional functions address load balancing or failover between multiple Facilitators: Function set_aka_server(char *ip) Argument and Behavior The argument to set_aka_server is the IP address of the new Facilitator that you want to perform queries against. If the function successfully sets the IP address of the new Facilitator, it returns 1; otherwise it retains the IP of the current Facilitator and returns 0. Returns the IP address of the current Facilitator. The argument to set_aka_port is the port of the new Facilitator that you wish to perform queries against. If the function successfully sets the port of the new Facilitator, it returns 1; otherwise it retains the port of the current Facilitator and returns 0. Returns the port of the current Facilitator.

get_aka_server() set_aka_port(char *port)

get_aka_port()

set_aka_server_and_port(char The set_aka_server_and_port function sets both the *ip, char *port) IP and the port of the new Facilitator, retaining both the IP and the port of the current Facilitator if it fails to set either. The AkaData_Demo.c program has sample usage of these functions; you will need to change the IPs that are being set in the set_aka_server function for it to function correctly. Note: In order to make sure that the above set functions worked, the code performs a test query for 127.0.0.1, and checks to make sure it didnt get the default_answer. The timeout is set to 1 sec for this test query. If you are operating the Facilitator in a configuration in which you know the timeout will be greater than 1 sec, you should change the timeout value within the set functions in AkaData.c.

Proprietary and Confidential

25

EdgeScape User Guide

Perl API
Before using the API, be sure to change two settings in AkaData.pm: GLOBALHOST and GLOBALPORT. These values should be set to the IP address (or hostname) and port of the Facilitator that you will be making queries to. By default, these values are set to 127.0.0.1 and 2001 respectively, and assume that the client is running on the same machine as the Facilitator; this is the recommended setup for the API. However, you might wish to change it based on your configuration. Once the Facilitator IP address and port settings are correct, use the provided Perl module, AkaData.pm, in your application. A demo program called AkaData_Demo.pl is provided for you to get acquainted with the Perl API. This program is only meant to be a demo; you may modify the demo file as well as the AkaData.pm file to suit your needs. The API is used to perform a lookup in the following manner: $buffer = akamai_ip_lookup(<ip>, <timeout>) The arguments to this function are: ip An Internet family address (ipv4) that specifies the address being queried. If that is not available, you may also pass in the 32-bit number. The amount of time (in ms) for which the function should block waiting on an answer. If this time expires, buffer will contain the default answer instead.

timeout

The resulting buffer contains the IP resolution answer. This answer is encoded as a list of entries separated with null characters and terminated with a null character. A plus (+) character separates multiple values for an attribute. Each entry is an attribute/value pair separated by an equal(=) sign.

Retrieving attribute values

EdgeScape provides a convenience function for retrieving a particular attribute's value. You arent required to use this function, but for retrieving a specific attribute regularly (for example, country_code), you might want to use it. The convenience function uses the following parameters: $country = akamai_attr_get(buffer, <attr>) The arguments to this function are: attr buffer A null-terminated string indicating the name of the attribute desired. The buffer filled by akamai_ip_lookup ($buffer in the above example)

26

Proprietary and Confidential

EdgeScape User Guide

Load balancing
Five additional functions address load balancing or failover between multiple Facilitators: Function set_aka_server(ip) Argument and Behavior The argument to set_aka_server is the IP address (or hostname) of the new Facilitator that you want to perform queries against. If the function successfully sets the IP address of the new Facilitator, it returns 1; otherwise it retains the IP of the current Facilitator and returns 0. Returns the IP address of the current Facilitator. The argument to set_aka_port is the port of the new Facilitator that you wish to perform queries against. If the function successfully sets the port of the new Facilitator, it returns 1; otherwise it retains the port of the current Facilitator and returns 0. Returns the port of the current Facilitator. The set_aka_server_and_port function sets both the IP and the port of the new Facilitator, retaining both the IP and the port of the current Facilitator if it fails to set either.

get_aka_server() set_aka_port(port)

get_aka_port() set_aka_server_and_port(ip,port)

The AkaData_Demo.pl program has sample usage of these functions; you will need to change the IPs that are being set in the set_aka_server function for it to function correctly. Note: In order to make sure that the above set functions worked, the code performs a test query for 127.0.0.1, and checks to make sure it didnt get the default_answer. The timeout is set to 1 sec for this test query. If you are operating the Facilitator in a configuration in which you know the timeout will be greater than 1 sec, you should change the timeout value within the set functions in AkaData.pm.

Proprietary and Confidential

27

EdgeScape User Guide

PHP API
Note: It is mandatory that your http server has PHP compiled with socket support (-enable-sockets) in order to use the PHP API. Before using the API, you may wish to change two settings in AkaData.inc: GLOBALHOST and GLOBALPORT. These values should be set to the IP address (or hostname) and port of the Facilitator that you will be making queries to. By default, these values are set to 127.0.0.1 and 2001 respectively, and assume that the client is running on the same machine as the Facilitator; this is the recommended setup for the API. However, you might wish to change it based on your configuration. Once the Facilitator IP address and port settings are correct, put the AkaData.inc file in the same place as your other PHP code. A demo program called AkaData_Demo.php is provided for you to get acquainted with the PHP API. This program is only meant to be a demo; you may modify the demo file as well as the AkaData.inc file to suit your needs. The API is used to perform a lookup in the following manner. First, you must create an AkaData object: AkaData(<ip>,<port>); $edgescape = new

The AkaData class constructor takes two optional arguments (ip (or hostname), port) which you can use to set the IP and Port of the Facilitator dynamically. To perform a lookup, do the

following: $info = $edgescape->ip_lookup(<ip>, <timeout>) The arguments to this function are: ip

An Internet family address (ipv4) that specifies the address being queried. If that is not available, you may also pass in the 32-bit number. The amount of time (in ms) for which the function should block waiting on an answer. If this time expires, buffer will contain the default answer instead.

timeout

This function returns an array of (key,value) pairs. A plus (+) character separates multiple values for an attribute.

Retrieving attribute values

EdgeScape provides a convenience function for retrieving a particular attribute's value. You arent required to use this function, but for retrieving a specific attribute regularly (for example, country_code), you might want to use it. The convenience function uses the following parameters:

28

Proprietary and Confidential

EdgeScape User Guide

$country = $edgescape->get(attr), where attr is the desired attribute (for example, country_code). Alternatively, you may retrieve the attribute by simply accessing the array returned by the ip_lookup function directly: $country = $info[<attr>]

Load balancing
Two additional functions address load balancing or failover between multiple Facilitators: Function get_server() get_port() Argument and Behavior Returns the IP address or Hostname of the current Facilitator. Returns the port of the current Facilitator.

You can use the above functions to determine the IP (or Hostname) and Port of the currently operating Facilitator. If you wish to change the IP (or Hostname) or Port of the Facilitator dynamically, use the AkaData constructor to do so.

Proprietary and Confidential

29

EdgeScape User Guide

Java API
Before compiling the Java API, be sure to change two settings in AkaData.java: akadata_addr_str and akadata_port. These values should be set to the IP address and Port of the Facilitator that you will be making queries to. By default, these values are set to 127.0.0.1 and 2001 respectively, and assume that the client is running on the same machine as the Facilitator; this is the recommended setup for the API. However, you might wish to change it based on your configuration. Once the Facilitator IP address and port settings are correct: Compile the provided Java source code, AkaData.java and AkaEdgeScape.java, located in the <edgescape-install-dir>/api/com/akamai directory, to create the class files in the same directory. Create a jar file called com.akamai.jar and include this in your application. Unix users may issue the command make javaapi in the api directory to create the Java API for them. Note that the environment variable CLASSPATH must contain the com.akamai.jar file. A demo program called AkaData_Demo.java is provided for you to get acquainted with the Java API. This program is only meant to be a demo; you may modify the demo file as well as the AkaData.java file to suit your needs. To use the Java API, create a new object of class AkaData, using the provided java class files located in the <edgescape-install-dir>/api directory. For every lookup to be performed, create a new object of class AkaData: AkaData JavaDemo = new AkaData("1.2.3.4", 100); JavaDemo gets information about IP address 1.2.3.4 within 100 ms or else provides default information. The instantiator accepts the following: AkaData(String, int) AkaData(String) AkaData (InetAddress, int) AkaData (InetAddress) AkaData (byte[], int) See above example Similar to the first example, except the default timeout value of 100ms is used Instead of a string object, you can use an InetAddress class Similar to the above, except the default timeout value of 100ms is used Instead of a string object, you can pass in a 4byte array that represents the IP address in network byte order. Similar to the above, except the default timeout value of 100ms is used

AkaData (byte[])

Once you have an object (like'JavaDemo'above), use 30 Proprietary and Confidential

EdgeScape User Guide

String result = JavaDemo.getAttribute("country_code"); to assign to "result" the country_code associated with object JavaDemo (which was instantiated with a particular IP address, in this case country_code for IP Address 1.2.3.4). If no such attribute exists, the result will be null. If you wish to just pull out all attribute/value pairs, use {object}.results, a two-dimensional array of strings, where JavaDemo.results[x][0] is the attribute, and JavaDemo.results[x][1] is the value associated with the attributes.

Load balancing
Five additional functions address load balancing or failover between multiple Facilitators: Function set_aka_server(String ip) Argument and Behavior The argument to set_aka_server is the IP address of the new Facilitator that you want to perform queries against. If the function successfully sets the IP address of the new Facilitator, it returns true; otherwise it retains the IP of the current Facilitator and returns false. Returns the IP address of the current Facilitator. The argument to set_aka_port is the port of the new Facilitator that you wish to perform queries against. If the function successfully sets the port of the new Facilitator, it returns true; otherwise it retains the port of the current Facilitator and returns false. Returns the port of the current Facilitator. The set_aka_server_and_port function sets both the IP and the port of the new Facilitator, retaining both the IP and the port of the current Facilitator if it fails to set either.

get_aka_server() set_aka_port(int port)

get_aka_port() set_aka_server_and_port(String ip, int port)

The AkaData_Demo.java program has sample usage of these functions; you will need to change the IPs that are being set in the set_aka_server function for it to function correctly. Note: In order to make sure that the above set functions worked, the code performs a test query for 127.0.0.1, and checks to make sure it didnt get the default_answer. The timeout is set to 1 sec for this test query. If you are operating the Facilitator in a configuration in

Proprietary and Confidential

31

EdgeScape User Guide

which you know the timeout will be greater than 1 sec, you should change the timeout value within the set functions in AkaData.java.

32

Proprietary and Confidential

EdgeScape User Guide

COM Interface
Windows users that would like to use EdgeScape from ASP can use the COM interface provided as part of the Java API. Compile the Java API as directed in the Java API section of this guide. Compiling the API creates three .class files in the api\com\akamai directory. Put these files in <windows directory>\java\trustedlib\com\akamai\ For example, c:\winnt\java\trustedlib\com\akamai\ AkaData_Demo.asp, an example ASP page using JavaScript, is provided for you in the api directory.

Proprietary and Confidential

33

EdgeScape User Guide

API Default Output

Typically, the output of the akamai_ip_lookup function (AkaData class instantiation in Java) is the information attributed to the queried IP address. However, in some cases, a default_answer is returned, indicating that either the client API was unable to communicate with the Facilitator, or the Facilitator was unable to obtain the data for some reason. Three attributes will be returned in either case: default_answer country_code Set to T if the answer is the default answer. The country code that is returned is configurable in the API. Note that this country_code may not be accurate. It is returned in case your code depends on a country_code being returned Set to either client, indicating that the API could not communicate with the Facilitator, or facilitator, indicating that the Facilitator could not access the data for some reason.

default_source

You can access these attributes in the same manner as any other attributes. The C API also returns DEFAULT_ANSWER. You can change the Perl API and/or Java API to return a similar code if desired.Refer to the Troubleshooting and FAQs chapter for more information about default_answer.

34

Proprietary and Confidential

EdgeScape User Guide

Chapter 6

Known Issues
Temp files on Windows
The Facilitator creates temporary files each time it installs new database files downloaded from the Akamai Network. Typically, the Facilitator deletes these files automatically after it has finished using them. Additionally, if the user performs a shutdown operation from the Console, the temporary files are deleted. However, on Windows systems, if the user performs the shutdown operation while the Facilitator is still reading from or writing to the temporary files, those files are not deleted; only the files that the Facilitator no longer has open are removed. In order to avoid filling the disk, we suggest that, on Windows systems in particular, the user should keep a watch on the temp and download directories (as specified in the configuration file), and remove files that are older than 1 day and that: begin with the word estemp OR end in .gz and also have the word flatfile in them

Memory leak in Perl 5.8.0

In Perl 5.8.0, there is a bug in the implementation of sockets, which causes the Perl API to leak memory, resulting in memory increasing linearly over time as lookups are performed. This problem does not exist in versions of Perl prior to 5.8.0. As this is a bug in the implementation of Perl, our current recommendation is to not use Perl 5.8.0.

Proprietary and Confidential

35

EdgeScape User Guide

Chapter 7

Troubleshooting and FAQs

The chapter discusses some common issues that can arise when installing and using EdgeScape. Use this information to quickly diagnose and troubleshoot a problem. Several Frequently Asked Questions provide additional helpful information. For additional help with installing, configuring, or using EdgeScape, please contact Akamai Customer Care at (877) 4-AKATEC or ccare@akamai.com.

Troubleshooting
I keep getting the default answer.

One of the following could be the issue: The listen_on attribute is set incorrectly in the Facilitator configuration file (facil.conf). GLOBALHOST is set incorrectly in the C/Perl API, or akadata_addr_str in the Java API. The machine with the API cant communicate with the Facilitator machine. Try pinging the Facilitator machine to ensure this communication is possible. The timeout is not set high enough in the API. The Facilitator is not connected to the Internet. It needs to be able to perform DNS lookups and connect to port 8443 of EAS, so make sure its Internet connection is functional. Upon startup, default answers will be returned for some time while the tree is loading.

The Facilitator refuses to start.

One of the following could be the issue: The path names are not correctly specified in the configuration file and startup script. Check these paths and correct them if necessary. The directories that you specified in the configuration file dont actually exist. Check the directories, or create the directories specified. My primary Facilitator machine went down. Akamai has provided a failover mechanism with EdgeScape. Use the function set_aka_server to direct the API to a backup Facilitator when the Primary machine goes down. Look at the AkaData_Demo scripts for an example.

The C API isnt compiling using MS Visual Studio 6.

Verify that the MS Platform SDK has been installed correctly.

36

Proprietary and Confidential

EdgeScape User Guide

I am getting back incorrect answers from EdgeScape.

Send the offending IP addresses as well as the correct location to Akamai Customer Care at ccare@akamai.com. CCare will investigate to determine the cause of the problem and the correct location, and update the Akamai databases if necessary.
The memory on my machine is getting used up when I use the Perl API.

There is a bug in Perl 5.8.0 which causes a memory leak. Do not use this version of Perl.

Frequently Asked Questions

What information is contained in the akafacilquery.log file?

The format of each line is: <date> <time> : <ip queried>|<country_code>|<region_code if applicable>|<# bytes sent>|<# bytes received>
How do I rotate the log file?

The Facilitator handles log rotation. You can specify the maximum number of bytes the log file can grow to and the number of archived log files to store in the configuration file.
Can I turn logging off?

Yes, by setting the log_level to be NONE.

Can I run the Facilitator on a different machine than the API?

Yes, the Facilitator and the API can run on different machines. Note the following: You must change the listen_on attribute in facil.conf to either be the IP of the machine the API is running on, or any if there are multiple API machines. In the C and Perl API, change GLOBALHOST to be the IP of the Facilitator machine; in the Java API, change akadata_addr_str, and/or use the set_aka_server function.
How do I know if I am getting back the default answer?

In the C API, one of the return codes is AKAMAI_DEFAULT. You can check for this return value. In all of the APIs, you can use the akamai_attr_get (or the getAttribute method in Java) to get the default_answer from the result. If it is the default answer, the value of the attribute is true.

Proprietary and Confidential

37

EdgeScape User Guide

Appendix A

API Function Return Codes

Return Code 0 1 2 3 4 5 Description AKAMAI_OK. Success code. AKAMAI_DEFAULT. Indicates the result is the default answer. AKAMAI_GENERIC_ERROR. Will occur if attr==NULL or buffer==NULL or buffer_len <= 0. AKAMAI_SMALL_BUFFER. Indicates that the buffer is not large enough to handle the data. AKAMAI_TRY_AGAIN. Indicates a temporary problem that is expected to be fixed soon. AKAMAI_PERMISSION_DENIED. You have been denied the right to look up the data. Please contact Akamai Customer Care at ccare@akamai.com to find out why. Limits may have been placed on the number of queries made, or your contract may have expired. AKAMAI_NOT_FOUND. Indicates that the IP address had no data associated with it; should be a highly rare occurrence.

38

Proprietary and Confidential