Location Services Software Installation and Configuration Guide
First Published: September 09, 2013
Last Modified: March 04, 2014
Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883
Text Part Number: OL-28970-02
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS,
INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH
THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY,
CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version
of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED "AS IS" WITH ALL FAULTS.
CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT
LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS
HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: http://
www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership
relationship between Cisco and any other company. (1110R)
Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown
for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.
Adobe Systems, Inc.
Adobe LiveCycle Data Services ES2.5, Copyright © 2010, Adobe Systems, Inc. All Rights Reserved
Oracle
Copyright ©2012, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
Red Hat, Inc.
Red Hat and Red Hat Enterprise Linux are trademarks of Red Hat, Inc., registered in the United States and other countries.
Other product names, symbols, and phrases used throughout this document (if any) are property of their respective owners.
Videoscape Location Services Software Installation and Configuration Guide
© Cisco Systems, Inc. All rights reserved.
CONTENTS
Preface
Preface v
Audience v
About This Guide v
Document Organization v
Document Conventions vi
Definitions and Acronyms vii
Document Definitions vii
Document Acronyms viii
CHAPTER 1
Location Services Overview 1
Videoscape Location Services Overview 1
CHAPTER 2
Location Services Software Installation Prerequisites 3
Hardware Requirements 3
Software Requirements 3
File Requirements 3
CHAPTER 3
Location Services Software Installation and Configuration 5
Installing the Location Services Software Using the Management Console Graphical User
Interface 5
Installing the Location Service Data COP Software 5
Installing the Location Service COP Software 6
Installing the Location Service in Standalone Mode 9
Logging into the CLI 10
Importing the Location Service COP Files from the SFTP Server 10
Installing the Location Service Data COP using the CLI 10
Installing the Location Service COP using the CLI 11
Location Services Software Installation and Configuration Guide
OL-28970-02
iii
Contents
Configuring the Location Service using the CLI 12
Customer Data Deployment 13
Location Service Data File Upgrade 13
APPENDIX A
Error Codes and Configuration Parameters 15
Error Codes 15
Configuration Parameters 16
Configuration Properties File Example 18
Location Services Software Installation and Configuration Guide
iv
OL-28970-02
Preface
• Audience, page v
• Document Organization, page v
• Document Conventions, page vi
• Definitions and Acronyms, page vii
Audience
This guide is intended to be used by System Administrators and Service Providers.
About This Guide
This guide contains instructions for the installation and configuration of the Videoscape Location Service
application software.
Document Organization
Chapter/Appendix
Description
Chapter 1 - Location Services
Overview
Provides an overview for the Videoscape Location Services
application.
Chapter 2 - Location Services
Software Installation Prerequisites
Provides the hardware, software, and file requirements for the
Videoscape Location Services application.
Chapter 3 - Videoscape Location
Service Software Installation and
Configuration
Provides the procedures used to install and configure the Videoscape
Location Services software.
Appendix A - Configuration
Parameters and Error Codes
Provides the configuration parameters used to configure the
Videoscape Location Services application. Also contained in this
appendix are the error codes used by the Location Service.
Location Services Software Installation and Configuration Guide
OL-28970-02
v
Preface
Document Conventions
Document Conventions
This document uses the following conventions:
Convention
Description
^ or Ctrl
Both the ^ symbol and Ctrl represent the Control (Ctrl) key on a keyboard.
For example, the key combination ^D or Ctrl-D means that you hold
down the Control key while you press the D key. (Keys are indicated in
capital letters but are not case sensitive.)
bold font
Commands and keywords and user-entered text appear in bold font.
Italic font
Document titles, new or emphasized terms, and arguments for which you
supply values are in italic font.
Courier font
Terminal sessions and information the system displays appear in courier
font.
Bold Courier font
Bold Courier font indicates text that the user must enter.
[x]
Elements in square brackets are optional.
...
An ellipsis (three consecutive nonbolded periods without spaces) after
a syntax element indicates that the element can be repeated.
|
A vertical line, called a pipe, indicates a choice within a set of keywords
or arguments.
[x | y]
Optional alternative keywords are grouped in brackets and separated by
vertical bars.
{x | y}
Required alternative keywords are grouped in braces and separated by
vertical bars.
[x {y | z}]
Nested set of square brackets or braces indicate optional or required
choices within optional or required elements. Braces and a vertical bar
within square brackets indicate a required choice within an optional
element.
string
A nonquoted set of characters. Do not use quotation marks around the
string or the string will include the quotation marks.
<>
Nonprinting characters such as passwords are in angle brackets.
[]
Default responses to system prompts are in square brackets.
Location Services Software Installation and Configuration Guide
vi
OL-28970-02
Preface
Definitions and Acronyms
Convention
Description
!, #
An exclamation point (!) or a pound sign (#) at the beginning of a line
of code indicates a comment line.
Reader Alert Conventions
This document uses the following conventions for reader alerts:
Note
Tip
Caution
Timesaver
Warning
Means reader take note. Notes contain helpful suggestions or references to material not covered in the
manual.
Means the following information will help you solve a problem.
Means reader be careful. In this situation, you might do something that could result in equipment damage
or loss of data.
Means the described action saves time. You can save time by performing the action described in the
paragraph.
Means reader be warned. In this situation, you might perform an action that could result in bodily
injury.
Definitions and Acronyms
This section provides the definitions and acronyms that are used throughout this guide.
Document Definitions
Definition Description
Civic
Location
Country, Province, City, and so on.
Geodetic
Location
Latitude and Longitude
LS Client
Location Service Client - Any Videoscape component or service that invokes the Location
Service.
Location Services Software Installation and Configuration Guide
OL-28970-02
vii
Preface
Document Acronyms
Document Acronyms
Definition Description
ASN
Autonomous System Numbers
BSG
Broadcast Service Group
CPE
Consumer Premise Equipment
CIDR
Classless Inter-Domain Routing
CMTS
Cable Modem Termination System
CSV
Comma Separated Value (File)
DTA
Digital Transport Adapter
EAS
Emergency Alert System
EC
Explorer Controller
ECS
Explorer Control System
FIPS
Federal Information Processing Standards (US)
LS
Location Service
OOBB
Out of Band Bridge
QPSK
Quadrature Phase-Shift Keying
SGC
Standard Geographical Classification (Canada)
SP
Service Provider
Location Services Software Installation and Configuration Guide
viii
OL-28970-02
CHAPTER
1
Location Services Overview
• Videoscape Location Services Overview, page 1
Videoscape Location Services Overview
The Location Service is a horizontally scalable and redundant service capable of providing geodetic, civic,
and network access data based on IP subnet data queried and loaded into its databases. It should be noted that
the network access data specifically identifies edge network elements of the access network infrastructure.
Such elements have geodetic and/or civic and/or network access metadata associated.
The Location Service also supports other types of location information. This information includes Emergency
Alert System (EAS) information and application specific Zone definitions.
The following figure illustrates the detailed architecture of the Cisco Location Service.
The Location Service Engine is responsible for handling location service requests from Client applications
(identified as Location Service Client). The request from the Location Service Client routes through a load
balancer to an available Location Service VM instance.
Location Services Software Installation and Configuration Guide
OL-28970-02
1
Location Services Overview
Videoscape Location Services Overview
The Location Service obtains its data through either static configuration or push/pull based interfaces to 3rd
party data sources. Static data sources include the MaxMind geolocation data, network subnet data, EAS data,
and application specific Zone data. Pull-based interface data sources include Neustar (fka Quova) geolocation
data. The Location Service supports push-based data for the EAS data associated with Explorer Controllers
(EC) and DTA Control Suite (DTACS). The Location Service stores push-based data inside a data grid so
that the data is available to all LS instances.
In order to maximize performance, the Location Service caches the location data in a memory based cache
called the Location Data Cache. The Location Service Engine never queries static data directly in order to
fulfill a location request. Instead, it always uses the data cached in memory for performance and scalability
purposes. For pull based interfaces, if the data is not currently in the Location Data Cache, the Location Service
Engine uses the interface to pull the location data from the data source. For data stored in the data grid, the
Location Service leverages the caching capabilities of the data grid to achieve performance.
Unlike the MaxMind geolocation data set, Neustar provides its data as an external service. Neustar provides
both a Java Client and web service interface. The Location Service currently uses the Java Client to call the
Neustar service to obtain the geolocation data.
Location Services Software Installation and Configuration Guide
2
OL-28970-02
CHAPTER
2
Location Services Software Installation
Prerequisites
• Hardware Requirements, page 3
• Software Requirements, page 3
• File Requirements, page 3
Hardware Requirements
Refer to Getting Started Guide for the Videoscape Control Suite (OL-27702-03) for the hardware requirements
of VCS.
Software Requirements
The installation procedures included within this guide, assume that the you have installed the Cisco Videoscape
Control Suite (VCS) software. If you have not installed the VCS software, do so now before continuing with
the Location Services software installation (refer to the Getting Started Guide for the Videoscape Control
Suite (OL-27702-03) for details).
File Requirements
Before beginning the Location Services software installation, ensure the following files have been downloaded
on a local PC or server:
• cisco.conductor-lcs-3.x-x-xx.cop
• cisco.conductor-lcs-3.x-x-xx.tmp.xml (Note: not required for a standalone installation)
• cisco.conductor-lcs-data-3.x-x-xx.cop
Location Services Software Installation and Configuration Guide
OL-28970-02
3
Location Services Software Installation Prerequisites
File Requirements
Note
Refer to the Videoscape Location Services Release Notes for the correct software and file versions.
Location Services Software Installation and Configuration Guide
4
OL-28970-02
CHAPTER
3
Location Services Software Installation and
Configuration
• Installing the Location Services Software Using the Management Console Graphical User Interface,
page 5
• Installing the Location Service in Standalone Mode, page 9
• Customer Data Deployment, page 13
• Location Service Data File Upgrade, page 13
Installing the Location Services Software Using the
Management Console Graphical User Interface
The Location Services software installation and configuration consists of the following:
1 Download the software files (Location Service COP, Data COP, and template file) to the Management
Console graphical user interface (UI).
2 Select the desired node for the software installation.
3 Install the Location Service software in the following order:
a. Location Service Data COP
b. Location Service COP
Installing the Location Service Data COP Software
To install the Location Services Data COP software using the Management Console UI, complete the following:
Step 1
Step 2
Log into the Management Console UI.
Select Operate > Download. This downloads the Location Service COP, Location Service Data COP, and the template
files. For example:
Location Services Software Installation and Configuration Guide
OL-28970-02
5
Location Services Software Installation and Configuration
Installing the Location Service COP Software
Step 3
Step 4
Select Operate > COP Install. A list of nodes is displayed.
Select the desired node. For example:
The COP images screen, displaying the available COP images, is displayed.
Step 5
Select the Data COP. For example:
Step 6
Click COP Install to initiate the Location Service Data COP installation. The following is an example of a completed
COP installation screen.
Installing the Location Service COP Software
To install the Location Services COP software using the Management Console UI, complete the following:
Step 1
Step 2
From within the Management Console UI, select Operate > COP Install. A list of nodes is displayed.
Select the desired node. For example:
The COP images screen, displaying the available COP images, is displayed.
Step 3
Select the Location Service COP. For example:
Location Services Software Installation and Configuration Guide
6
OL-28970-02
Location Services Software Installation and Configuration
Installing the Location Service COP Software
Step 4
Select New Config Generation.
The Location Service Configuration window containing the default values for all configuration parameters is displayed.
For example:
Location Services Software Installation and Configuration Guide
OL-28970-02
7
Location Services Software Installation and Configuration
Installing the Location Service COP Software
Step 5
Step 6
Edit any desired configuration parameters and then select the node to be configured, click Generate Config. You are
redirected to the main COP installation page.
Within the COP installation page, the generated configuration is displayed at the bottom. Select the Node ID, the LCS
COP file, the Configuration File Name, and then click COP Install. For example:
Location Services Software Installation and Configuration Guide
8
OL-28970-02
Location Services Software Installation and Configuration
Installing the Location Service in Standalone Mode
The configuration file name is cisco.conductor-lcs-VERSION-HOSTNAME.cfg.xml, where VERSION is the same as
the Location Service COP version, and the HOSTNAME is the hostname for the node where the Location Service is
installed.
The following diagram represents a successful Location Service COP installation.
Installing the Location Service in Standalone Mode
The Location Service application can be installed and configured in a standalone mode. This is especially
useful when the users of the Videoscape Control Suite applications do not install the management console
and only have Command Line Interface (CLI) access.
To install and configure the Location Service in standalone mode, complete the installation and configuration
in the following order:
1
2
3
4
5
Access the CLI
Import the COP files from SFTP server
Install the Location Service Data COP
Install the Location Service COP
Configure the Location Service
Location Services Software Installation and Configuration Guide
OL-28970-02
9
Location Services Software Installation and Configuration
Logging into the CLI
Logging into the CLI
To log into the service node CLI, you must login using the admin account. For example:
ssh [email protected]
[email protected]'s password:
Command Line Interface is starting up, please wait ...
Welcome to the Platform Command Line Interface
VMware Installation:
6 vCPU: Intel(R) Xeon(R) CPU X5680 @ 3.33GHz
Disk 1: 80GB
24576 Mbytes RAM
admin:
Once logged in you can install and configure the Location Service COPs.
Importing the Location Service COP Files from the SFTP Server
To transfer the Location Service COP files from the SFTP server to the service node, use the following
command:
file transfer secure-import [user@host:file]
The following is an example, using the previous CLI command to transfer Location Service COP files.
admin:file transfer secure-import user@host:cisco.conductor-lcs-3.0-0-23.cop
admin:file transfer secure-import user@host:cisco.conductor-lcs-data-3.0-0-12.cop
Installing the Location Service Data COP using the CLI
The Location Service data COP must be installed first. To install the data COP, enter the following command
at the admin prompt:
file load cop [cop-name]
The following is an example of the previous command:
admin:file load cop cisco.conductor-lcs-data-3.0-0-12.cop
Copying COP for Authentication
Authenticating COP
Extracting the file ...
COP extraction completed, starting Install
Installation log is /common/log/install/cisco.conductor-lcs-data-3.0-0-12.cop.log
Create conf folder for LCS.
Preparing to install ...
Perform /common partition check...
Perform / partition check...
Verifying options directory
Checking previous installation of the COP ...
This COP is being freshly installed - Installing
Make sure the LS is not currently using any data files ...
The lcs.war is not actively refreshing data, proceed with install
Installing data files to /opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni ...
-- GeoLiteCity-Location.csv is installed to
/opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni.
-- GeoLiteCity-Blocks.csv is installed to
/opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni.
-- GeoIPASNum2.csv is installed to
/opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni.
-- GeoIPASNum2v6.csv is installed to
/opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni.
-- GeoLiteCityv6.csv is installed to
/opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni.
Location Services Software Installation and Configuration Guide
10
OL-28970-02
Location Services Software Installation and Configuration
Installing the Location Service COP using the CLI
-- cnty.dat is installed to /opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni.
-- zipcnty.dat is installed to /opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni.
Install data files to backup dir ...
Installing data files to
/var/log/active/installed_options/cisco.conductor-lcs-data-3.0-0-12.cop/data
...
-- GeoLiteCity-Location.csv is installed to
/var/log/active/installed_options/cisco.conductor-lcs-data-3.0-0-12.cop/data.
-- GeoLiteCity-Blocks.csv is installed to
/var/log/active/installed_options/cisco.conductor-lcs-data-3.0-0-12.cop/data.
-- GeoIPASNum2.csv is installed to
/var/log/active/installed_options/cisco.conductor-lcs-data-3.0-0-12.cop/data.
-- GeoIPASNum2v6.csv is installed to
/var/log/active/installed_options/cisco.conductor-lcs-data-3.0-0-12.cop/data.
-- GeoLiteCityv6.csv is installed to
/var/log/active/installed_options/cisco.conductor-lcs-data-3.0-0-12.cop/data.
-- cnty.dat is installed to
/var/log/active/installed_options/cisco.conductor-lcs-data-3.0-0-12.cop/data.
-- zipcnty.dat is installed to
/var/log/active/installed_options/cisco.conductor-lcs-data-3.0-0-12.cop/data.
LCS data installation is completed successfully
Uninstall function exists in cisco.conductor-lcs-data-3.0-0-12.cop folder
Installing the Location Service COP using the CLI
Once the Location Service data COP has been installed, the Location Service COP can be installed. To install
the Location Service COP, enter the following command at the admin prompt:
file load cop [cop-name]
The following is an example of the previous command:
admin:file load cop cisco.conductor-lcs-3.0-0-23.cop
Copying COP for Authentication
Authenticating COP
Extracting the file ...
COP extraction completed, starting Install
Installation log is /common/log/install/cisco.conductor-lcs-3.0-0-23.cop.log
Verifying the data files exists ...
Checking previous LCS COP installation ...
This COP is being freshly installed - Installing
Preparing to install ...
Perform /common partition check...
Perform / partition check...
Verifying options directory
Updating JBoss standalone.conf...
Updating JBoss standalone.xml...
Copying modules to /opt/jboss/jboss-as-7.1.0.Final/modules ...
-- Creating Conductor SDK Module ...
-- Creating Location Service Module ...
-- Creating BNI Common Module ...
-- Creating Spring Framework Module ...
-- Creating Couchbase Client Module ...
Shutting down JBoss ...
Service Manager is running
Commanded Out of Service
jboss[NOTRUNNING]
Deploying the LCS war to JBoss...
Starting JBoss ...
Service Manager is running
jboss[STARTED]
The lcs.war has been deployed successfully.
Waiting for the Location Data to initialize ...
-- Wait for data load to complete, try=1
-- Wait for data load to complete, try=2
The lcs.war has finished initializing
Adding CLI commands ...
LCS installation is completed successfully
Uninstall function exists in cisco.conductor-lcs-3.0-0-23.cop folder
Location Services Software Installation and Configuration Guide
OL-28970-02
11
Location Services Software Installation and Configuration
Configuring the Location Service using the CLI
Configuring the Location Service using the CLI
Note
It is recommended that the customer provides their own config.properties file, when operating in the
standalone mode.
The Location Service provides a CLI command (file load lcs deploy) to deploy the customer provisioned
config.properties file. This command performs a merge operation if the configuration file config.properties
already exists. Before running the file load lcs deploy command, you must upload the config.properties file
first, using the file transfer secure-import CLI command. For example:
admin:file transfer secure-import user@host:config.properties
admin:file load lcs deploy
File config.properties is deployed.
When a new configuration is deployed, the previous configuration is backed up. To restore the previous
Location Service configuration, use the following CLI command:
file load lcs restoreconfig
Alternatively, you can configure each Location Service configuration parameter using the following CLI
command:
file load lcs config
For example:
admin:file load lcs config
Configurate the key 'net.beaumaris.ls.3rdParty.geolocation.source' :
Type : 'option'
Available Options : '(MaxMind|Quova)'
Default Option : 'MaxMind'
The current value is : 'MaxMind'
Enter your input , Return for using [ MaxMind ] :
Configurate the key 'com.cisco.conductor.ls.useDataGrid' :
Type : 'option'
Available Options : '(false|true)'
Default Option : 'false'
The current value is : 'false'
Enter your input , Return for using [ false ] :
Configurate the key 'net.beaumaris.cache.control.ttl' :
Type : 'integer'
Default Value : '30'
The current value is : '30'
Enter your input , Return for using [ 30 ] :
Configurate the key 'net.beaumaris.ls.gls.initWaitSeconds' :
Type : 'integer'
Default Value : '300'
The current value is : '300'
Enter your input , Return for using [ 300 ] :
Configurate the key 'net.beaumaris.ls.maxErrorNumber' :
Type : 'integer'
Default Value : '2147483647'
The current value is : '2147483647'
Enter your input , Return for using [ 2147483647 ] :
Configurate the key 'net.beaumaris.ls.gls.maxmind.loadIspName' :
Type : 'boolean'
Default Value : 'false'
The current value is : 'false'
Enter your input , Return for using [ false ] : true
Your input is true :
Your customized configuration is :
net.beaumaris.ls.gls.maxmind.loadIspName=true
Are your sure to override the existing configuration? [yes/no] yes
Back up /opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni/config.properties
Set configuration for : key=net.beaumaris.ls.gls.maxmind.loadIspName, value=true
Restarting Jboss for the new configuration to take effect? [yes/no] no
Warning : The new configruation will not take effect until Jboss is restarted.
Location Services Software Installation and Configuration Guide
12
OL-28970-02
Location Services Software Installation and Configuration
Customer Data Deployment
Note
When working within the CLI, you must wait for the CLI cursor to reappear before entering any additional
input. Failure to do so will result in a wrong or unrecognized configuration.
Customer Data Deployment
The Location Service COP installation uses the following CLI commands to deploy or restore the customer
data files:
file load lcs deploy
file load lcs restore
Note
The customer data file name is fixed. Refer to the Location Service API Guide for the data file format.
Before running the file load lcs deploy command, be sure to transfer the files SPLocation.csv, SPSubNet.csv,
or zone-data.xml from the SFTP server using the file secure-transfer import CLI command first. You can
then use the file load lcs deploy command to deploy the Service Provider data files to the desired directory.
It should be noted that only two copies of these files are maintained. When new service provider files are
available, running this command backs up the existing files. The following is an example of these commands:
admin:file transfer secure-import user@host:zone-data.xml
admin:file transfer secure-import user@host:SPSubNet.csv
admin:file transfer secure-import user@host:SPLocation.csv
admin:file load lcs deploy
File SPLocation.csv is deployed.
File SPSubNet.csv is deployed.
File zone-data.xml is deployed.
To restore the backup files, use the file load lcs restore command.
Location Service Data File Upgrade
The Location Service static data file is updated via the Location Service Data COP upgrade. The Data COP
upgrade can be performed using the management console Operate > COP Install page or by using the file
load cop-upgrade CLI command. The Location Service Data COP upgrade is treated the same as a new
installation. The previously installed Location Service Data COP file is not removed after the COP upgrade
but the active location files used by the Location Service are updated with the location of the data files installed
with the new data COP.
The Location Service also supports user rollback to any version of previously installed location data.
Uninstallation of the Location Service Data COP restores the previous location data from the last Location
Service Data COP installation. In the case, when there is only one Location Service Data COP file installed
on the system, the Location Service COP must be uninstalled first before uninstalling the Location Service
Data COP because the location data files may be actively used by Location Service. COP uninstallation can
be performed on management console Operate > COP Install page or via the file load cop-uninstall CLI
command.
Location Service COP and Data COP files can be upgraded independently. The Location Service COP is
compatible with the Location Service Data COP, as long as they share the same major version number. The
JBoss application server is restarted during the Location Service COP installation or upgrade process.
Location Services Software Installation and Configuration Guide
OL-28970-02
13
Location Services Software Installation and Configuration
Location Service Data File Upgrade
Location Services Software Installation and Configuration Guide
14
OL-28970-02
APPENDIX
A
Error Codes and Configuration Parameters
• Error Codes, page 15
• Configuration Parameters, page 16
• Configuration Properties File Example , page 18
Error Codes
The following table provides the error codes contained within the Location Service application.
Code Value
Reporter Service
Code Name
Description
Workaround
2000
SM (Location
Service)
LOCATION_SERVICE_NOT_INITIALIZED The Location
Service received a
request before it
finished loading the
MaxMind files into
memory.
To correct this
problem, wait a few
minutes then try the
request again.
2001
SM (Location
Service)
LOCATION_SERVICE_INVALILID_IP_ADDRESS The IP address
string passed to the
Location Service is
not a valid Ipv4 or
IPv6 address.
To correct this
problem, make sure
that the
x-forwarded-for
header exists and
contains a valid IP
address.
2002
SM (Location
Service)
LOCATION_SERVICE_NO_DATA_FOR_ADDRESS There is no
geo-location data
available for the
given IP address.
To correct this
problem, make sure
that the IP address
is not for a proxy
and that the data set
is complete.
Location Services Software Installation and Configuration Guide
OL-28970-02
15
Error Codes and Configuration Parameters
Configuration Parameters
Code Value
Reporter Service
Code Name
Description
Workaround
2003
SM (Location
Service)
LOCATION_SERVICE_DATA_SET_EXCEPTION There was an error
retrieving location
data from the
in-memory data set
.
To correct this
problem, check the
logs for more details
and try the request
again.
2004
SM (Location
Service)
LOCATION_SERVICE_UNKNOWN_ERROR There was an
unknown error
getting the location
data for a specific
IP address.
To correct this
problem, check the
logs for more details
and try the request
again.
2005
SM (Location
Service)
LOCATION_SERVICE_INVALID_COUNTRY The location
service found data
for the address, but
the IP address is
not from with a
valid (by
configuration)
country.
To correct this
problem, send the
request again with
an x-forwarded-for
header with an IP
address from a valid
country.
2006
SM (Location
Service)
LOCATION_SERVICE_INVALID_ASN The location
service found data
for the IP address
but the IP address
is not owned by a
valid (by
configuration)
network operator.
To correct this
problem, send the
request again with
an x-forwarded-for
header with an IP
address from a valid
ASN.
Configuration Parameters
The Videoscape Location Service configuration data (configuration parameters) is stored in a properties file
located in the following location:
/opt/jboss/jboss-as-7.1.0.Final/standalone/configuration/bni/config.properties
The following table provides a description of the configuration parameters.
Configuration Parameter
Type
Description
net.beaumaris.ls.3rdParty.geolocation.source String Specifies the 3 rd party geolocation data source. Valid values
include: MaxMind | Quova. The default value is MaxMind.
com.cisco.conductor.ls.useDataGrid Boolean Couchbase Data Grid Enabled or not, Default value is false.
com.cisco.conductor.ls.dataGridIPs String Couchbase Server List IPs or Hostnames, comma separated.
Default value is localhost.
com.cisco.conductor.ls.dataGridUser String Couchbase Server Admin User Name, Default value is
Administrator.
Location Services Software Installation and Configuration Guide
16
OL-28970-02
Error Codes and Configuration Parameters
Configuration Parameters
Configuration Parameter
Type
Description
com.cisco.conductor.ls.dataGridPassword String Couchbase Server Admin User Password, Default value is
cisco123.
net.beaumaris.cache.control.ttl
Integer TTL value for HTTP cache control header in minutes. Default
value is 30 minutes.
net.beaumaris.ls.gls.initWaitSeconds Integer The amount of time, in seconds, to wait for a provider to refresh
its data before cancelling the job. This is only used when the 3 rd
party geolocation provider Global Config value
(ls.3rdParty.geolocation.source) is changed on a running system.
Default value is 300.
net.beaumaris.ls.gls.refreshDelaySeconds Integer The number of seconds between when a change is detected in a
location data file and when the process to refresh the data starts.
This delay prevents multiple refresh jobs from being triggered
due to changes in multiple files within a short period of time. The
default value is 30 seconds.
net.beaumaris.ls.maxErrorNumber Integer Maximum number of allowable processing errors when loading
data for a provider. If this value is exceeded the source data is
considered corrupt and the provider will not be used for Location
lookups. Default value is 2147483647.
net.beaumaris.ls.gls.maxmind.loadIspName Boolean Whether to load the textual name of the ISP along with their ASN.
Turning this on results in a significant increase in RAM usage on
LS nodes. Default is "false". For Quova/Neustar, the ISP name is
always included.
net.beaumaris.ls.quova.connectionPoolSize Integer Maximum number of simultaneous connections to the Quova
server. Default is 10.
net.beaumaris.ls.quova.connectRetrySeconds Integer Frequency in seconds to retry connections to Quova server if a
404 is returned upon connecting. Default is 5 seconds.
net.beaumaris.ls.quova.customerID String Customer ID for Quova usage account. Must be specified when
using Quova as a data source.
net.beaumaris.ls.quova.maxConnectRetryTimes Integer Number of times the API will retry a failed connection. Default
is 3.
net.beaumaris.ls.quova.networkProtocol String Protocol used to communicate with Quova server. Valid values
are: TCP | UDP Default value is "TCP".
net.beaumaris.ls.quova.primaryServerIP String Primary Quova GeoDirectory Server IP address. Default is
127.0.0.1.
net.beaumaris.ls.quova.primaryServerPort Integer Primary Quova GeoDirectory Server port number. Default value
is 7000.
net.beaumaris.ls.quova.secondaryServerIP String Secondary Quova GeoDirectory Server IP address. Default is
127.0.0.1.
net.beaumaris.ls.quova.secondaryServerPort Integer Secondary Quova GeoDirectory Server port number. Default value
is 7001.
Location Services Software Installation and Configuration Guide
OL-28970-02
17
Error Codes and Configuration Parameters
Configuration Properties File Example
Configuration Parameter
Type
Description
net.beaumaris.ls.quova.udpListenerPort Integer Port on which UDP listener listens. Default value is 8000.
net.beaumaris.ls.quova.userTimeout.milliseconds Integer Connection timeout in ms. Default value is 5000 ms.
Configuration Properties File Example
The following is an example of a Configuration Properties File.
net.beaumaris.ls.3rdParty.geolocation.source=MaxMind
com.cisco.conductor.ls.useDataGrid=false
com.cisco.conductor.ls.dataGridIPs=localhost
com.cisco.conductor.ls.dataGridUser=Administrator
com.cisco.conductor.ls.dataGridPassword=cisco123
net.beaumaris.cache.control.ttl=30
net.beaumaris.ls.gls.initWaitSeconds=300
net.beaumaris.ls.maxErrorNumber=2147483647
net.beaumaris.ls.gls.maxmind.loadIspName=false
net.beaumaris.ls.quova.primaryServerIP=127.0.0.1
net.beaumaris.ls.quova.primaryServerPort=7000
net.beaumaris.ls.quova.secondaryServerIP=127.0.0.1
net.beaumaris.ls.quova.secondaryServerPort=7001
net.beaumaris.ls.quova.connectionPoolSize=10
net.beaumaris.ls.quova.connectRetrySeconds=5
net.beaumaris.ls.quova.maxConnectRetryTimes=3
net.beaumaris.ls.quova.userTimeout.milliseconds=5000
net.beaumaris.ls.quova.networkProtocol=TCP
net.beaumaris.ls.quova.udpListenerPort=8000
Location Services Software Installation and Configuration Guide
18
OL-28970-02