You are on page 1of 38

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

.................................. 25 Perl API ... 36 Appendix A API Function Return Codes ........... 30 Load balancing ................................................ 24 Retrieving attribute values ....... 27 PHP API ......................................................................................... 28 Retrieving attribute values ...................................... 24 Load balancing ......................................................................................... 31 COM Interface .......................................................................................................8................................................................. 26 Retrieving attribute values ......................................................................................................................................................................................................................................................................................... 37 Troubleshooting and FAQs .............................. 34 Chapter 6 Temp files on Windows ....................................................................................................................................................................................................... 35 Known Issues ............................................................................................................................................................................................................................................. 28 Load balancing .......................................................Compiling using Borland C++ Builder 5 .......................................... 23 Using the C API ................................................................................................................... 33 API Default Output .................................... 29 Java API...................................................... 38 4 Proprietary and Confidential ................................................ 36 Frequently Asked Questions ............................ 35 Chapter 7 Troubleshooting ............ 26 Load balancing ....................... 35 Memory leak in Perl 5........................................................0.......

allowing you to access information about how your users access the Internet. EdgeScape is designed to easily integrate with your Web site.com. Audience This document is the EdgeScape User Guide. identifies the components that run in your environment. Unless otherwise denoted in this document. This document provides complete instructions for installing the EdgeScape service. and is intended for programmers and administrators implementing the EdgeScape service. and defines the application programming interface (API) used to interface with the EdgeScape service. 5 Proprietary and Confidential . This includes information that maps a user’s IP address to geography and network attributes like the user’s country and connection speed. The User Guide describes the EdgeScape architecture. Other Resources If you have any questions while using this guide. the term EdgeScape refers to both services.EdgeScape User Guide Introduction Overview Welcome to Akamai’s EdgeScapeSM service. The EdgeScape Product suite consists of both the EdgeScape and EdgeScape Pro services. please contact Akamai Customer Care at 1877-AKATEC or ccare@akamai.

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 6 Proprietary and Confidential . specifically the EAS. The primary purpose of the EAS component is to manage updates to the EdgeScape database that is stored on your Facilitator machine. The Facilitator is also responsible for listening and responding to requests from the AkaClientAPI. Facilitator. and EdgeScape Authorization Server (EAS). EAS is a process that runs in multiple locations on the Akamai platform.EdgeScape User Guide Chapter 1 How the EdgeScape Service Works EdgeScape Component Overview The EdgeScape Service is architected using three subsystems or components. AkaClientAPI. 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. 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 uses DNS to retrieve a list of EASs to connect to. Facilitator The Facilitator is a daemon process that runs directly on your Web server or application server. If the Facilitator can’t connect to the EAS.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. authenticating connection requests from Facilitators by verifying the certificate received from each Facilitator. Since these files are encrypted. or the AkaClientAPI and the Facilitator should communicate over a secure network. it continues to use the database it has locally. Therefore. The EAS then sends an SSL certificate to the Facilitator. repeated failures to connect will result in the Facilitator shutting down to prevent theft of service. The authentication and authorization step involves the Facilitator sending its certificate to the EAS. The certificate sent by the Facilitator to the EAS is a GPG signed certificate using the Digital Signature Algorithm (DSA). Note that communication between the AkaClientAPI and the Facilitator is not secure. and to handle all of the complexities of fetching the answers. The basic function of the Facilitator is to be queried by instances of the AkaClientAPI. either the AkaClientAPI and the Facilitator should reside on the same server. • • EdgeScape Authorization Server (EAS) EAS is a process that runs on the Akamai platform. The Facilitator makes an SSL connection to port 8443/443 (user-configurable) of the first live EAS. as a Java Class. This Application Programming Interface (API) is available in the C Programming language. Examples of how to use each of these APIs are provided in Implementing the EdgeScape API. and as a Perl script. If the certificate is successfully authenticated. the Facilitator is told what files to download from the Akamai platform. proving its authenticity as an EAS. • Upon starting up. however. The Facilitator begins listening on port 2001 for UDP requests from the AkaClientAPI processes. Once the EAS successfully authenticates the Facilitator. The Facilitator reconnects to the EAS every 12 hours to request authorization and to receive updates to the EdgeScape database. The Facilitator is responsible for requesting authentication and authorization as well as securing communication between your application and the Akamai platform. it sends the Facilitator an ARL (Akamai Resource Locator) that the Facilitator uses to download the EdgeScape database files from the Akamai platform. the EAS also sends the Facilitator the decryption key to use to decrypt the files. Proprietary and Confidential 7 . The Facilitator is responsible for several functions.

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.EdgeScape User Guide Chapter 2 EdgeScape Performance EdgeScape Database Availability The EdgeScape service is built with failover and high availability technology. and alerts generate automatically if EAS processes or servers are experiencing errors. 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 Akamai’s NOCC using the same monitoring and alerting system used across the Akamai network. In the unlikely event that no EASs are available. 8 Proprietary and Confidential . The EdgeScape database files are distributed via the Akamai network to ensure speedy and reliable downloads of the database. The Akamai NOCC also has a system to poll EAS processes. the Facilitator continues to operate with the database it currently has for 30 days (as long as the Facilitator is not shutdown). Also.

1. download the Windows EdgeScape Engine Package.1. Windows XP) Any (certified on RedHat 6.akamai. and COM.1. Solaris 2. download the Unix EdgeScape Engine Package. EdgeScape customers must meet the following requirements for each.6.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. Solaris 2. Win2K. Perl. Solaris 2.0 (or newer) gcc MS Visual Studio 6 (MS Platform SDK required) Borland C++ Builder 5. EdgeScape Facilitator The EdgeScape Facilitator is included in the EdgeScape Engine Package. so no additional software is required.6.6.1. EdgeScape API The API is available in C.6. Win2K.8. Language Perl Java PHP C Compiler/Interpreter Operating System Perl 5.8.0 (or higher) interpreter Any (certified on RedHat 6. PHP.com). which is available on the Akamai portal (https://control. Java. Solaris 2. If you are using a Unix-based system.1 Any (certified on RedHat 6.3. Solaris 2. Solaris 2.2 (or higher) compiler PHP 4. Solaris 2. Windows XP) Any UNIX-based platform (certified on RedHat 6. Windows XP) JDK 1. If you are using a Windows-based system. You will also need to download and install Sun JRE (v6 or higher) that will work on your system.8.8) Windows (certified on Win2K and Windows XP) Windows (certified on Win2K and Windows XP) Windows XP Proprietary and Confidential 9 . This package includes a JRE. Win2K.0 COM JRE 1. Solaris 2. Memory and disk requirements are 1024 MB (1 GB) for all operating systems.

you may set the classpath in sbin/Facilitator. 3. Run the Facilitator. After downloading and installing a JRE. logs. See Running the Facilitator for instructions. config. Follow the appropriate installation procedure to install the software on the machine that will be running the Facilitator. You may need to make the following change to the java. copy all the files in <edgescape-install-dir>/lib to <directory-where-jre-resides>/jre/lib/ext. For example: • • • • mkdir <edgescape-install-dir> mv edgescape. See Configuration Process for instructions.tgz <edgescape-install-dir> cd <edgescape-install-dir> tar xfz edgescape. sbin.cert.cache.gpg 4.tgz file. Note: GNU tar must be used when untaring the . The following directories are created in <edgescape-install-dir>: api.tgz 2. it must be Sun JRE version 6 or higher.security file located in jre/lib/security/: Uncomment the networkaddress.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.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 .com.akamai. See Installation Process for instructions. tmp .ttl line. Alternatively. Installation Process Download the EdgeScape software package and certificate from the Akamai portal at https://control. and change the value from “-1” to “1” Unix-based Installation To perform a Unix-based installation: 1. Note: If you are installing your own JRE. Configure the EdgeScape Facilitator. Copy the certificate file to the config sub-directory of <edgescape-install-dir>: • config/facil. Untar and unzip the software package in the directory you want to install EdgeScape in.

In sbin/Facilitator. Unzip the edgescape. The following directories are created in <edgescape-install-dir>: api. 2. Copy the certificate file to the config sub-directory of <edgescape-install-dir>: • config/facil.cert.EdgeScape User Guide 5. 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. config. tmp. jre. sbin. For more information. Double-click on the “EdgeScape Setup” icon to start an Install Shield installation process that installs EdgeScape to a directory you specify. Proprietary and Confidential 11 . refer to the section on “Running EdgeScape as a Service”. logs. Windows-based Installation To perform a Windows-based installation: 1.gpg The EdgeScape installation modifies your Windows Registry so that EdgeScape can be run as a service.sh and sbin/runFacilitator.sh. 3.zip file into a temporary directory.

Java. Note that if this script is used.sh (UNIX-based platforms) sbin/Facilitator.EdgeScape User Guide File Locations After you finish installing the software package.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 . important files and directories exist in the following locations: Directory or File Location sbin/Facilitator.sh (Unixbased platforms) Location of the configuration file.bat (Windowsbased platforms) config/ api/ logs/ sbin/runFacilitator. since this script will restart the Facilitator (section 6. and Perl Location of the log files that the Facilitator process writes to Script that starts the Facilitator and restarts it if it dies. and keystore Location of API files for C. certificate file. performing a “shutdown” operation through the console will not work.

sbin/Facilitator. enabling this feature will lead to Facilitator performance degradation.bat on Windows. If the directory name does not contain spaces.sh or runFacilitator.conf.proxyPort=<port of http proxy server> If the proxy doesn’t allow outbound connections to port 8443. Windows: Change every occurrence of <edgescape-install-path> in config/facil. and the name is case-sensitive.proxyHost=<name of http proxy server> -Dhttp.sh on Unix. then replace <edgescape-install-path> with c:\progra~1\akamai~1\edgescape.Facilitator in the Facilitator Startup Script (sbin/Facilitator. add ‘–logqueries’ immediately after com.txt to reflect the full path name of the location that you’d like the files to reside in. The Facilitator allows logging of all IPs queried (disabled by default). use the MSDOS name for that directory.sh and sbin/runFacilitator.Facilitator. The necessary changes are listed below. Spaces are not allowed in directory names when replacing <edgescape-install-path> with your desired path. you need to make changes to the Facilitator’s startup script and configuration file.edgescape.bat on Windows): -Dhttps.conf to 443.edgescape. If the directory names contain spaces.sh and config/facil. if you use the default installation path. they are sbin/Facilitator.Facilitator in Facilitator.akamai.sh. if you use the default installation path. use the MSDOS name for that directory.sh on Unix. Facilitator Startup Script Unix: In sbin/Facilitator.conf respectively On Windows. • • On Unix. and the name is case-sensitive. Configuration File Unix: Change every occurrence of <edgescape-install-path> in config/facil. or in Facilitator.proxyHost=<name of https proxy server> -Dhttps.EdgeScape User Guide Configuration Process Before starting the Facilitator. using the MSDOS name is optional. then replace <edgescape-install-path> with Proprietary and Confidential 13 .akamai. you will need to add the following just before com. Windows: Change the FACILPATH setting in sbin/Facilitator. For example.bat and config/facil. To turn this feature on. For example. Spaces are not allowed in the path.conf to reflect the full path name of the location that you’d like the files to reside in. Using Facilitator with a Proxy If the machine running the Facilitator is behind a proxy.bat to reflect the full path of the installation directory. If the directory names contain spaces. 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. you will need to set the target_port in facil.txt.Facilitator.conf. However.proxyPort=<port of https proxy server> -Dhttp. these files are sbin/Facilitator.

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

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

There are 5 possible settings for this attribute: none. with older files being removed first to make room for newer files. Location of GPG certificate file. and is measured in bytes. fatal. Similar to the log_file_max_num setting.bat. the username is set to ‘edgescape’. By default. The Facilitator has built-in log rotation. console_password *log_file The console requires a password for entry. This attribute sets the filename to which the Facilitator writes useful logging information. info. 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 . Location of the file that the Facilitator uses to verify the EASs SSL certificate. Setting it to any other setting prints out log messages of that type or more severe. 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. error. This attribute sets the maximum size the log file should grow to before being rotated. Setting this attribute to ‘none’ results in nothing being written to the log file. 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. doing so results in greater Facilitator performance degradation than if it is left set to false. This attribute sets the maximum number of log files that remain on disk. However.EdgeScape User Guide By default. The only difference in format between EdgeScape version 1 and version 2 is the date/time stamp which by default is set to false. warn. This attribute sets the filename that the Facilitator writes to if the –logqueries option is set in Facilitator. there is no password.sh or Facilitator.

and the user subsequently logs out of the machine. You’ll notice a JAVAW process if you look in the Task Manager.sh or runFacilitator. Note that it takes a few minutes for the Facilitator to download and install the database upon startup. reboot the machine after installing EdgeScape. the service will not start correctly. However. An MSDOS window should flash on the screen for a few moments. with no interruption of service. 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 . default_answers are returned for all queries. You will see a Facilitator process with Java sub-processes in your process tree. and then close itself. the console is no longer operational. Windows: Double-click on the EdgeScape icon in the Start menu. However. Once the Facilitator is started. you can close it manually. if the window remains open. the EdgeScape installation modifies your Windows Registry so that EdgeScape can be run as a service. If you wish to shutdown or reboot the Facilitator. Note that if your machine is restarted without making the appropriate changes to facil. Running EdgeScape as a Service (Windows users only) If the EdgeScape icon is used to start EdgeScape.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. you can use the EdgeScape Facilitator Console to administer it. or double-click the Facilitator. the Facilitator will stop running.bat file located in the sbin directory. The EdgeScape service will be started automatically when Windows boots.sh scripts in the sbin directory. and will remain running whether any user logs in or out. To run EdgeScape as a service.bat. If you shutdown the Facilitator.txt and Facilitator. subsequent upgrades to the database happen seamlessly.conf. use the APIs provided or enter IP addresses in the box provided on the Console. during this time. *temp_directory Running the Facilitator Unix: Run either the Facilitator. the recommended method is to use the shutdown or reboot functions in the Console. To make queries to the Facilitator.

It is recommended that you backup your Registry before making any changes. By default. The console’s main window displays the Facilitator’s status. If you wish to turn this option on when running as a service. If you do not wish for the EdgeScape service to start automatically when Windows boots. or shut it down. Change the name of “Start Param Number 0” to be “Start Param Number 1” Add a new String Value called “Start Param Number 0”. To access the EdgeScape Facilitator Console and display Facilitator status: 1. You must use the Services tool in the Control Panel to start/stop EdgeScape when running as a service. There are 4 additional functions you can perform through the Console: 18 Proprietary and Confidential . review its log file. reboot it. 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. remove this value 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>. but instead want to be able to manually start the service after logging in. EdgeScape Facilitator Console After you’ve started the Facilitator. 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). you can use the Web-based console to check its status. and can be changed in the configuration file). remove this key from the Registry. Point your Web browser to http://localhost:2003 (2003 is the default console port.EdgeScape User Guide If you do not wish for EdgeScape to be able to be run as a service. 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. 2. change the Startup Type property for EdgeScape from “automatic” to “manual” using the Services tool. the EdgeScape service will run without the –logqueries option.

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

Query for attributes using the spelling shown here. 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. DMA® is a registered service mark of The Nielsen Company.EdgeScape User Guide Chapter 5 Implementing the EdgeScape API The EdgeScape Database The EdgeScape Database contains the following information about an IP address. The dma value is a number representing the DMA® that the IP address maps to. two-letter code for the state. The msa value is a number representing the Metropolitan Statistical Area that the IP address maps to. The country_code value is an ISO-3166. Attributes are available via the API. The region_code value is an ISO-3166. (Omit any asterisks (*) from your query).akamai.com. province. all rights reserved. For the most current listing of data code values. two-letter code for the country where the IP address maps to. The city value is the city (within a 50-mile radius) that the IP address maps to. The pmsa value is a number representing the Primary Metropolitan Statistical Area that the IP address maps to. please log into the Akamai customer portal at https://control. 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 . or region where the IP address maps to.

including Region Code. each value will be separated by the plus (+) character. for AOL IPs. For example. 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. the following strings are all valid zip values: 10001 10001+10003 10001-10003+10005 10001-10003+10005-10008 Proprietary and Confidential 21 . In the case of the zip attribute. In addition. if the IP is in the reserved IP space (as designated by the Internet Assigned Numbers Authority). This attribute indicates whether the IP is a proxy and what type of proxy it is (transparent or anonymous). The domain value will be the domain that the IP address belongs to. However. * Denotes attributes only available with the EdgeScape Pro service.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. only Country information will be returned. are optional and may not necessarily be associated with an IP address. Provides additional granularity to the ‘throughput’ field. every attribute has a value of ‘reserved’. The entire IP address space is represented in the database and always has a Country Code associated with it. If an attribute contains multiple values. contiguous zip codes will be represented as a range of the form “FirstZipInRange-LastZipInRange”. *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 network type value will be the connection type that the IP address belongs to. All other elements in the database. and multiple ranges may be present (each range separated by the plus (+) character).

EdgeScape User Guide 22 Proprietary and Confidential .

into your application.c file as well. AkaData. A demo program called AkaData_Demo.c –pthread –o AkaDemo Compiling using Microsoft Visual Studio 6 In order to use MS Visual Studio 6.EdgeScape User Guide C API Before compiling the API. Proprietary and Confidential 23 . The following example compiles the demo program into a binary named AkaDemo: gcc AkaData. However. These values should be set to the IP address and port of the Facilitator that you will be making queries to.h.c ak_socket.c ak_socket. these values are set to 127.c –lpthread –lresolv –lsocket –lnsl –o AkaDemo Compiling on FreeBSD You should only need to include the ‘pthread’ library. you might also need to include the libraries ‘resolve’. If you have any difficulty building the API on these platforms. By default. Note that the command is slightly different than when compiling on Linux/Solaris: gcc AkaData.exe.c and AkaData.c file to suit your needs. you need to include the ‘pthread’ library. You must compile the ak_socket. the MS Platform SDK is required. and ‘nsl’. be sure to change two settings in AkaData. The C API has been tested on the above platforms. ‘socket’. located in the <edgescape-installdir>/api directory. Compiling on Linux/Solaris In order to compile the API.dsw file and build AkaDemo.h: GLOBALHOST and GLOBALPORT. Once the Facilitator IP address and port settings are correct.com.1 and 2001 respectively. and assume that the client is running on the same machine as the Facilitator. please contact Akamai Customer Care at ccare@akamai.bpr file and build AkaDemo.exe. Open the included . Compiling using Borland C++ Builder 5 Open the included .c AkaData_Demo.0.0.c is provided for you to get acquainted with the C API. you may modify the demo file as well as the AkaData.c AkaData_Demo. this is the recommended setup for the API. This program is only meant to be a demo. compile the provided C source and header files. you might wish to change it based on your configuration.

but constants are used to indicate the meaning. country_code). const size_t buffer_len. See the API Function Return Codes appendix for a list of possible return codes. the buffer will contain the default answer instead. you will get an error. This answer is encoded as a list of entries separated with null characters and terminated with a null character. A pointer set to the buffer that will contain the result of this function. You aren’t required to use this function. and the return code will indicate so.EdgeScape User Guide Using the C API The API is used to perform a lookup by calling the akamai_ip_lookup function. while any other value is an error. An argument/result. char **result) 24 Proprietary and Confidential . The convenience function uses the following parameters: akamai_attr_get(const char *attr. Please note that if the buffer is too short. char *buffer. struct timeval *timeout) The arguments to this function are: addr buffer len An Internet family address (ipv4) that specifies the address being queried. using the following parameters: akamai_ip_lookup(const in_addr_t *addr. A value of zero is a success code. Each entry is an attribute/value pair separated by an equal(=) sign. If that is not available. The resulting buffer contains the IP resolution answer. you might want to use it. size_t *len. It will contain the length of the buffer on calling and will return the length of the data on result. timeout The result codes for this function can be any possible value. Retrieving attribute values EdgeScape provides a convenience function for retrieving a particular attribute's value. The amount of time for which the function should block waiting on an answer. A plus (+) character separates multiple values for an attribute. const char *buffer. but for retrieving a specific attribute regularly (for example. If this time expires. you may also pass in the 32-bit number.

it returns 1.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. Note: In order to make sure that the above ‘set’ functions worked. The timeout is set to 1 sec for this test query. If the function successfully sets the port of the new Facilitator. A pointer to the result buffer returned from akamai_ip_lookup A length for the buffer (as was passed in). you should change the timeout value within the ‘set’ functions in AkaData. the result will point to NULL. The AkaData_Demo.0. If the attribute does not exist. otherwise it retains the port of the current Facilitator and returns 0. If the function successfully sets the IP address of the new Facilitator. char *port) IP and the port of the new Facilitator. Returns the port of the current Facilitator. retaining both the IP and the port of the current Facilitator if it fails to set either. otherwise it retains the IP of the current Facilitator and returns 0.0. and checks to make sure it didn’t get the ‘default_answer’. 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. it returns 1. the code performs a test query for 127. See the API Function Return Codes appendix for more information. you will need to change the IPs that are being set in the set_aka_server function for it to function correctly. The return codes here match those of akamai_ip_lookup. Returns the IP address of the current Facilitator.c. The argument to set_aka_port is the port of the new Facilitator that you wish to perform queries against. If you are operating the Facilitator in a configuration in which you know the timeout will be greater than 1 sec.1. A pointer to the address IN the buffer where the value for the attribute is specified (right after the equal sign). Proprietary and Confidential 25 .c program has sample usage of these functions. 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.

use the provided Perl module. The convenience function uses the following parameters: $country = akamai_attr_get(buffer. you might want to use it. country_code). <attr>) The arguments to this function are: attr buffer A null-terminated string indicating the name of the attribute desired. and assume that the client is running on the same machine as the Facilitator. The API is used to perform a lookup in the following manner: $buffer = akamai_ip_lookup(<ip>. you may modify the demo file as well as the AkaData. This program is only meant to be a demo. A demo program called AkaData_Demo. However. be sure to change two settings in AkaData. You aren’t required to use this function. Once the Facilitator IP address and port settings are correct. Retrieving attribute values EdgeScape provides a convenience function for retrieving a particular attribute's value. timeout The resulting buffer contains the IP resolution answer. buffer will contain the default answer instead. The amount of time (in ms) for which the function should block waiting on an answer.1 and 2001 respectively. These values should be set to the IP address (or hostname) and port of the Facilitator that you will be making queries to. If that is not available. <timeout>) The arguments to this function are: ip An Internet family address (ipv4) that specifies the address being queried. but for retrieving a specific attribute regularly (for example.EdgeScape User Guide Perl API Before using the API. A plus (+) character separates multiple values for an attribute. Each entry is an attribute/value pair separated by an equal(=) sign. you may also pass in the 32-bit number.pm file to suit your needs. If this time expires.pm: GLOBALHOST and GLOBALPORT. By default.0. you might wish to change it based on your configuration. This answer is encoded as a list of entries separated with null characters and terminated with a null character.pl is provided for you to get acquainted with the Perl API. this is the recommended setup for the API. these values are set to 127. in your application. The buffer filled by akamai_ip_lookup ($buffer in the above example) 26 Proprietary and Confidential .0.pm. AkaData.

retaining both the IP and the port of the current Facilitator if it fails to set either.0.port) The AkaData_Demo. get_aka_server() set_aka_port(port) get_aka_port() set_aka_server_and_port(ip. and checks to make sure it didn’t get the ‘default_answer’. Returns the IP address of the current Facilitator. The timeout is set to 1 sec for this test query.pm. it returns 1.0. it returns 1.pl program has sample usage of these functions. otherwise it retains the port of the current Facilitator and returns 0. If the function successfully sets the IP address of the new Facilitator. If you are operating the Facilitator in a configuration in which you know the timeout will be greater than 1 sec.1.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. Note: In order to make sure that the above ‘set’ functions worked. Returns the port of the current Facilitator. If the function successfully sets the port of the new Facilitator. The argument to set_aka_port is the port of the new Facilitator that you wish to perform queries against. you should change the timeout value within the ‘set’ functions in AkaData. you will need to change the IPs that are being set in the set_aka_server function for it to function correctly. the code performs a test query for 127. The set_aka_server_and_port function sets both the IP and the port of the new Facilitator. Proprietary and Confidential 27 . otherwise it retains the IP of the current Facilitator and returns 0.

However. The API is used to perform a lookup in the following manner. you may modify the demo file as well as the AkaData.php is provided for you to get acquainted with the PHP API. To perform a lookup.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. buffer will contain the default answer instead. If this time expires. $edgescape = new The AkaData class constructor takes two optional arguments (ip (or hostname). This program is only meant to be a demo. you may wish to change two settings in AkaData. timeout This function returns an array of (key.inc file to suit your needs. and assume that the client is running on the same machine as the Facilitator. By default. port) which you can use to set the IP and Port of the Facilitator dynamically. Before using the API. you might wish to change it based on your configuration. If that is not available. You aren’t required to use this function. First. you must create an AkaData object: AkaData(<ip>. country_code). you might want to use it. this is the recommended setup for the API. The convenience function uses the following parameters: 28 Proprietary and Confidential .inc: GLOBALHOST and GLOBALPORT. but for retrieving a specific attribute regularly (for example. <timeout>) The arguments to this function are: ip An Internet family address (ipv4) that specifies the address being queried.0. these values are set to 127. These values should be set to the IP address (or hostname) and port of the Facilitator that you will be making queries to. do the following: $info = $edgescape->ip_lookup(<ip>. Retrieving attribute values EdgeScape provides a convenience function for retrieving a particular attribute's value. put the AkaData. Once the Facilitator IP address and port settings are correct.value) pairs. The amount of time (in ms) for which the function should block waiting on an answer.<port>).0. A demo program called AkaData_Demo.inc file in the same place as your other PHP code. A plus (+) character separates multiple values for an attribute. you may also pass in the 32-bit number.1 and 2001 respectively.

“country_code”). use the AkaData constructor to do so. You can use the above functions to determine the IP (or Hostname) and Port of the currently operating Facilitator. Alternatively. Proprietary and Confidential 29 . where “attr” is the desired attribute (for example. If you wish to change the IP (or Hostname) or Port of the Facilitator dynamically.EdgeScape User Guide $country = $edgescape->get(“attr”). 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.

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

The argument to set_aka_port is the port of the new Facilitator that you wish to perform queries against.4). in this case country_code for IP Address 1. otherwise it retains the IP of the current Facilitator and returns false.2. If no such attribute exists. a two-dimensional array of strings. and JavaDemo. the code performs a test query for 127.results[x][1] is the value associated with the attributes. it returns true.getAttribute("country_code"). where JavaDemo. Returns the IP address of the current Facilitator. it returns true.results[x][0] is the attribute. The timeout is set to 1 sec for this test query. you will need to change the IPs that are being set in the set_aka_server function for it to function correctly. use {object}.0.results.0. and checks to make sure it didn’t get the ‘default_answer’. If you wish to just pull out all attribute/value pairs. otherwise it retains the port of the current Facilitator and returns false. Note: In order to make sure that the above ‘set’ functions worked. retaining both the IP and the port of the current Facilitator if it fails to set either.EdgeScape User Guide String result = JavaDemo. 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. to assign to "result" the country_code associated with object JavaDemo (which was instantiated with a particular IP address. Returns the port of the current Facilitator. If the function successfully sets the port of the new Facilitator. get_aka_server() set_aka_port(int port) get_aka_port() set_aka_server_and_port(String ip.java program has sample usage of these functions.1. The set_aka_server_and_port function sets both the IP and the port of the new Facilitator. int port) The AkaData_Demo. If you are operating the Facilitator in a configuration in Proprietary and Confidential 31 . If the function successfully sets the IP address of the new Facilitator. the result will be null.3.

32 Proprietary and Confidential .java. you should change the timeout value within the ‘set’ functions in AkaData.EdgeScape User Guide which you know the timeout will be greater than 1 sec.

Put these files in <windows directory>\java\trustedlib\com\akamai\ For example. Compile the Java API as directed in the Java API section of this guide.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. Proprietary and Confidential 33 .asp. c:\winnt\java\trustedlib\com\akamai\ AkaData_Demo. is provided for you in the api directory. an example ASP page using JavaScript. Compiling the API creates three .class files in the api\com\akamai directory.

You can change the Perl API and/or Java API to return a similar code if desired. However. 34 Proprietary and Confidential . indicating that the API could not communicate with the Facilitator. It is returned in case your code depends on a country_code being returned Set to either “client”. in some cases.EdgeScape User Guide API Default Output Typically. Note that this country_code may not be accurate. indicating that either the client API was unable to communicate with the Facilitator. The C API also returns DEFAULT_ANSWER. or “facilitator”. the output of the akamai_ip_lookup function (AkaData class instantiation in Java) is the information attributed to the queried IP address. default_source You can access these attributes in the same manner as any other attributes. The country code that is returned is configurable in the API. indicating that the Facilitator could not access the data for some reason.Refer to the Troubleshooting and FAQ’s chapter for more information about default_answer. 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. a “default_answer” is returned.

In order to avoid filling the disk.0.0 In Perl 5. Typically. and remove files that are older than 1 day and that: begin with the word “estemp” OR end in “. However.8. if the user performs a “shutdown” operation from the Console. our current recommendation is to not use Perl 5. Proprietary and Confidential 35 . the user should keep a watch on the temp and download directories (as specified in the configuration file). Additionally.gz” and also have the word “flatfile” in them Memory leak in Perl 5. resulting in memory increasing linearly over time as lookups are performed. which causes the Perl API to leak memory. there is a bug in the implementation of sockets.8.0.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. we suggest that. This problem does not exist in versions of Perl prior to 5.8. As this is a bug in the implementation of Perl. only the files that the Facilitator no longer has open are removed. the temporary files are deleted. the Facilitator deletes these files automatically after it has finished using them. on Windows systems. if the user performs the “shutdown” operation while the Facilitator is still reading from or writing to the temporary files.8.0. on Windows systems in particular. those files are not deleted.

The C API isn’t compiling using MS Visual Studio 6. Troubleshooting I keep getting the default answer. For additional help with installing. Check these paths and correct them if necessary. so make sure its Internet connection is functional. The Facilitator is not connected to the Internet.com. please contact Akamai Customer Care at (877) 4-AKATEC or ccare@akamai. The directories that you specified in the configuration file don’t actually exist. default answers will be returned for some time while the tree is loading. Use this information to quickly diagnose and troubleshoot a problem. Try pinging the Facilitator machine to ensure this communication is possible. Look at the AkaData_Demo scripts for an example. Verify that the MS Platform SDK has been installed correctly. One of the following could be the issue: • • • • • • The listen_on attribute is set incorrectly in the Facilitator configuration file (facil. My primary Facilitator machine went down. GLOBALHOST is set incorrectly in the C/Perl API. Several Frequently Asked Questions provide additional helpful information. One of the following could be the issue: • • • • The path names are not correctly specified in the configuration file and startup script. configuring.EdgeScape User Guide Chapter 7 Troubleshooting and FAQs The chapter discusses some common issues that can arise when installing and using EdgeScape. The machine with the API can’t communicate with the Facilitator machine. or create the directories specified. Use the function set_aka_server to direct the API to a backup Facilitator when the Primary machine goes down. or using EdgeScape. The timeout is not set high enough in the API. Check the directories.conf). The Facilitator refuses to start. 36 Proprietary and Confidential . It needs to be able to perform DNS lookups and connect to port 8443 of EAS. Akamai has provided a failover mechanism with EdgeScape. Upon startup. or “akadata_addr_str “ in the Java API.

one of the return codes is AKAMAI_DEFAULT. In all of the APIs. Can I turn logging off? Yes. the value of the attribute is true.8. If it is the default answer. by setting the log_level to be ‘NONE’. Note the following: You must change the listen_on attribute in facil. Proprietary and Confidential 37 . change GLOBALHOST to be the IP of the Facilitator machine. Do not use this version of Perl. There is a bug in Perl 5. in the Java API.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. In the C and Perl API. You can check for this return value. or ‘any’ if there are multiple API machines. you can use the akamai_attr_get (or the getAttribute method in Java) to get the “default_answer” from the result. Frequently Asked Questions What information is contained in the akafacilquery.EdgeScape User Guide I am getting back incorrect answers from EdgeScape.0 which causes a memory leak. change “akadata_addr_str”. CCare will investigate to determine the cause of the problem and the correct location. How do I know if I am getting back the default answer? In the C API. and/or use the set_aka_server function. the Facilitator and the API can run on different machines. The memory on my machine is getting used up when I use the Perl API. Send the offending IP addresses as well as the correct location to Akamai Customer Care at ccare@akamai. Can I run the Facilitator on a different machine than the API? Yes. 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.conf to either be the IP of the machine the API is running on.com. and update the Akamai databases if necessary.

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