Reproduction in whole or in part in any form or medium without express written permission is prohibited. Akamai, the Akamai wave wave logo, Faster Forward and the names of certain Akamai products referenced herein are trademarks or service marks of Akamai Technologies, Inc. Inc. Third party trademarks and 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 eve ry 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 t his 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.
Akamai Technologies, Inc.
US Headquarters 8 Cambridge Center Cambridge, MA 02142
Tel: 617.444.3000 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/ht http://www.a kamai.com/html/about/locatio ml/about/locations.html ns.html
Reproduction in whole or in part in any form or medium without express written permission is prohibited. Akamai, the Akamai wave wave logo, Faster Forward and the names of certain Akamai products referenced herein are trademarks or service marks of Akamai Technologies, Inc. Inc. Third party trademarks and 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 eve ry 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 t his 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.
............................................................................ 8 EdgeScape Database Availabili Availability ty ............................................................................ NOCC Monitoring of EdgeScape ........................................................................... 8
Chapter 3
EdgeScape System Requirements ................................. ................................ 9
EdgeScape Facilitator ........................................................................................... 9 EdgeScape API ................................................................................................... 9
Chapter 4
........................ .................... ........ 10 Installing the EdgeScape Service ............
Installation Process ............................................................................................ 10 Unix-based Installation ............................................................................... 10 Windows-based Windows-ba sed 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
Chapter 5
............................. ..... 20 Implementing the EdgeScape API .........................
The EdgeScape Database .................................................................................... 20 C API 23 Compiling on Linux/Solaris ........................................................................ 23 Compiling on FreeBSD .............................................................................. 23 Compiling using Microsoft Visual Studio 6 .................................................... 23
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
Known Issues ............................................................. 35
Temp files on Windows .............................................................................. 35 Memory leak in Perl 5.8.0............................................................................ 35
Chapter 7
Troubleshooting and FAQs ........................................ 36
Appendix A API Function Return Codes ....................................... 38
4
Proprietary and Confidential
EdgeScape User Guide
Introduction Overview Welcome to Akamai’s 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 user’s IP address to geography and network attributes like the user’s 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 [email protected].
5
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
Customer Environment
EdgeScape Authorization Server Customer Web Server or Application Server
EAS
AkaClientAPI SSL Connection
UDP queries
UDP responses
Facilitator
Akamai platform
HTTP Connection
EdgeScape DB
Figure 1 – EdgeScape Architecture
6
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 can’t 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
7
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 Akamai’s 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.
8
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
Compiler/Interpreter
Operating System
Perl
Perl 5.0 (or higher) interpreter
Any (certified on RedHat 6.1, Solaris 2.6, Solaris 2.8, Win2K, Windows XP)
Java
JDK 1.2 (or higher) compiler
Any (certified on RedHat 6.1, Solaris 2.6, Solaris 2.8, Win2K, Windows XP)
PHP
PHP 4.3.0 (or newer)
Any (certified on RedHat 6.1, Solaris 2.6, Solaris 2.8, Win2K, Windows XP)
C
gcc
Any UNIX-based platform (certified on RedHat 6.1, Solaris 2.6, Solaris 2.8)
MS Visual Studio 6 (MS Platform SDK required)
Windows (certified on Win2K and Windows XP)
Borland C++ Builder 5.0
Windows (certified on Win2K and Windows XP)
JRE 1.1
Windows XP
COM
Proprietary and Confidential
9
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
•
mv edgescape.tgz
•
cd
•
tar xfz edgescape.tgz
2. The following directories are created in : api, config, logs, sbin,
tmp . 3. Copy the certificate file to the config sub-directory of : •
config/facil.cert.gpg
4. After downloading and installing a JRE, copy all the files in /lib
to /jre/lib/ext. Alternatively, you may set the classpath in sbin/Facilitator.sh to point to /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 to point to the
directory where the JRE resides and change 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 : api, config, jre, logs, sbin, tmp. 3. Copy the certificate file to the config sub-directory of : •
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
Description
sbin/Facilitator.sh (UNIX-based platforms)
Script that starts the Facilitator
sbin/Facilitator.bat (Windowsbased platforms)
12
config/
Location of the configuration file, certificate file, and keystore
api/
Location of API files for C, Java, and Perl
logs/
Location of the log files that the Facilitator process writes to
sbin/runFacilitator.sh (Unixbased platforms)
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)
jre/lib/ext/
Location of EdgeScape jar files
Proprietary and Confidential
EdgeScape User Guide
Configuration Process Before starting the Facilitator, you need to make changes to the Facilitator’s 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 to reflect the
full path to the directory that contains your JRE and change 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 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= -Dhttps.proxyPort= -Dhttp.proxyHost= -Dhttp.proxyPort= If the proxy doesn’t 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 in config/facil.conf to reflect
the full path name of the location that you’d like the files to reside in. Spaces are not allowed in directory names when replacing with your desired path, and the name is case-sensitive. Windows: Change every occurrence of in config/facil.conf.txt to
reflect the full path name of the location that you’d 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 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 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
Proprietary and Confidential
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).
target
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.
target_port
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.
console_port
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_username
The console requires a username for entry.
15
EdgeScape User Guide
By default, the username is set to ‘edgescape’.
16
console_password
The console requires a password for entry. By default, there is no password.
*log_file
This attribute sets the filename to which the Facilitator writes useful logging information.
log_level
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.
log_file_max_size
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.
log_file_max_num
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.
*query_log_file
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)
query_log_file_max_size
Similar to the log_file_max_size setting.
query_log_file_max_num
Similar to the log_file_max_num setting.
enable_legacy_query_log_format
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.
*trust_file
Location of the file that the Facilitator uses to verify the EASs SSL certificate.
*certif_file
Location of GPG certificate file.
Proprietary and Confidential
EdgeScape User Guide
*download_directory
Directory to which the Facilitator downloads database files from the Akamai platform
*temp_directory
Directory in which EdgeScape database files are stored after they have been fully downloaded and installed.
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. You’ll 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 . 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 you’ve 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 console’s main window displays the Facilitator’s 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
20
Geography
Description
continent = string
The continent value is a two-letter code for the continent that the IP address maps to.
country_code = string
The country_code value is an ISO-3166, two-letter code for the country where the IP address maps to.
region_code = string
The region_code value is an ISO-3166, two-letter code for the state, province, or region where the IP address maps to.
*city = string
The city value is the city (within a 50-mile radius) that the IP address maps to.
*dma = string
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.
*msa = string
The msa value is a number representing the Metropolitan Statistical Area that the IP address maps to.
*pmsa = string
The pmsa value is a number representing the Primary Metropolitan Statistical Area that the IP address maps to.
*areacode = string
The areacode value is the area code that the IP address maps to (multiple values possible)
*lat = string
The lat value is the latitude that the IP address maps to
*long = string
The long value is the longitude that the IP address maps to
*county = string
The county value is the county that the IP address maps to (multiple values possible)
*timezone = string
The timezone value is the time zone that the IP address maps to
*zip = string
The zipcode value is the zipcode that the IP address maps to (multiple values possible)
Proprietary and Confidential
EdgeScape User Guide
Attribute = type Network
Description
network = string
The network value will be the network that the IP address belongs to.
network_type = string
The network type value will be the connection type that the IP address belongs to.
asnum = string
The asnum value will be the AS number or numbers that the IP belongs to (multiple values possible)
*throughput = string
The throughput is the actual connection speed that the IP address maps to.
*bw = integer
Provides additional granularity to the ‘throughput’ field.
*proxy = string
This attribute indicates whether the IP is a proxy and what type of proxy it is (transparent or anonymous).
Attribute = type Corporate Identity
Description
*company = string
The company value will be the company that the IP address belongs to.
*domain = string
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 /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 [email protected].
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
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.
buffer
A pointer set to the buffer that will contain the result of this function.
len
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.
timeout
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.
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 aren’t 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
A null-terminated string indicating the name of the attribute desired.
buffer
A pointer to the result buffer returned from akamai_ip_lookup
buffer_len A length for the buffer (as was passed in). result
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
Argument and Behavior
set_aka_server(char *ip)
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.
get_aka_server()
Returns the IP address of the current Facilitator.
set_aka_port(char *port)
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.
get_aka_port()
Returns the port of the current Facilitator.
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 didn’t 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(, ) 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.
timeout
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.
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 aren’t 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, ) The arguments to this function are:
26
attr
A null-terminated string indicating the name of the attribute desired.
buffer
The buffer filled by akamai_ip_lookup ($buffer in the above example)
Proprietary and Confidential
EdgeScape User Guide
Load balancing Five additional functions address load balancing or failover between multiple Facilitators: Function
Argument and Behavior
set_aka_server(ip)
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.
get_aka_server()
Returns the IP address of the current Facilitator.
set_aka_port(port)
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.
get_aka_port()
Returns the port of the current Facilitator.
set_aka_server_and_port(ip,port)
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.
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 didn’t 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: $edgescape = new AkaData(,); 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(, ) 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.
timeout
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.
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 aren’t 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[]
Load balancing Two additional functions address load balancing or failover between multiple Facilitators: Function
Argument and Behavior
get_server()
Returns the IP address or Hostname of the current Facilitator.
get_port()
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 /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 /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)
See above example
AkaData(String)
Similar to the first example, except the default timeout value of 100ms is used
AkaData (InetAddress, int)
Instead of a string object, you can use an InetAddress class
AkaData (InetAddress)
Similar to the above, except the default timeout value of 100ms is used
AkaData (byte[], int)
Instead of a string object, you can pass in a 4byte array that represents the IP address in network byte order.
AkaData (byte[])
Similar to the above, except the default timeout value of 100ms is used
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
Argument and Behavior
set_aka_server(String ip)
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.
get_aka_server()
Returns the IP address of the current Facilitator.
set_aka_port(int port)
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.
get_aka_port()
Returns the port of the current Facilitator.
set_aka_server_and_port(String ip, int port)
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.
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 didn’t 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 \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
Set to ‘T’ if the answer is the default answer.
country_code
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
default_source
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.
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 FAQ’s 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 [email protected].
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 can’t 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 don’t 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 isn’t 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 [email protected]. 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 wh en 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?