| Oracle® Communications Service Broker VPN Implementation Guide Release 6.1 Part Number E29462-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Service Broker VPN Implementation Guide Release 6.1 Part Number E29462-01 |
|
|
PDF · Mobi · ePub |
This chapter describes how to use the Oracle Communications Service Broker VPN batch operation tools, command-line utilities for creating, modifying, and validating VPN application data.
When you invoke a VPN Provisioning API operation to create or modify a data object in storage, you are acting upon a single data object in storage at a time. The batch operation tools, on the other hand, enable you to act upon multiple objects at once. Batch operations are especially useful when adding a subscribing organization, when many users typically must be added to the system at once.
To use the batch operation tools, you place the data to be loaded or validated in local data files. The data in the files should be in comma-separated value (CSV) format.
The batch operation tools are:
Batch Loader: Loads data from a CSV file into storage after optionally validating the data.
Silent Batch Loader: Loads data from multiple CSV files into system storage after optionally validating the data.
Batch Validator: Validates data of a single type in a CSV file or in storage, optionally exporting the stored data to a CSV file.
Silent Batch Validator: Validates data of multiple types in CSV files or in storage, optionally exporting the stored data to CSV files.
The batch operation tools work by issuing requests to the VPN Provisioning API. Therefore, the same usage requirements applicable to making individual operation calls to the API apply to using the batch operation tools as well. For instance, to create a VPN subscriber, you must first create the administrative user for that subscriber, whether you use the API or the batch operation tools.
You can run the batch operation tools from any system that can access the Service Broker managed server. The managed server must be running with its HTTP listening port enabled. In a clustered environment, you only run the batch command against one of the managed servers, because the server will propagate the changes to the shared, cluster-wide data storage.
Versions of the batch operation tools are available for Linux and Windows operating systems.
The batch operation tools are subject to the same security settings that apply to other requests to the VPN Provisioning API. These requirements may include SSL security or the API's custom authentication mechanism.
The following sections describe tool configuration and usage requirements for secured domains.
If the Service Broker domain uses SSL security, you must configure the batch operation tools to work with the enabled SSL security features. These features may include Secure HTTP (HTTPS) and client certificate authentication.
Note:
See Oracle Communications Service Broker Security Guide for information about Service Broker domain security.The security settings for the batch operation tools are located in the following files:
Linux:
batch_home/bulkloader/common.sh
Windows:
batch_home/bulkloader/common.cmd
Where batch_home is the directory where the batch operation tools are located. The default directory is:
Oracle_home/ocsb61/admin_server/utils/bulkloader/
If HTTPS access is enabled for the Service Broker domain, you must configure the following settings in common.sh. The settings describe the trusted keystore on the client where the certificates of the managed servers are located. The batch operation tools use these settings to verify the host identity of the managed server.
To configure the settings, remove the comment character ("#") from the start of each line, and replace the default values with the values appropriate for your system. The settings are:
# BK_JAVA_OPTS="${BK_JAVA_OPTS} -Djavax.net.ssl.trustStore=clienttruststore"
# BK_JAVA_OPTS="${BK_JAVA_OPTS} -Djavax.net.ssl.trustStoreType=type
# BK_JAVA_OPTS="${BK_JAVA_OPTS} -Djavax.net.ssl.trustStorePassword=password
Where:
clienttruststore is the name of the trusted keystore on the client computer.
type is the type of the trusted keystore. Generally, this is jks.
password is the trusted keystore's passphrase.
If the managed server authenticates clients based on SSL client certificates, you must specify where the client keystore is located on the client system. To do so, configure the following settings in common.sh. The settings identify the certificate in the keystore that the batch operation tools submit to the managed server.
To configure the settings, remove the comment character ("#") from the start of each line, and replace the default values with the values appropriate for your system. The settings are:
# BK_JAVA_OPTS="${BK_JAVA_OPTS} -Djavax.net.ssl.keyStore=clientkeystore
# BK_JAVA_OPTS="${BK_JAVA_OPTS} -Djavax.net.ssl.keyStoreType=type
# BK_JAVA_OPTS="${BK_JAVA_OPTS} -Djavax.net.ssl.keyStorePassword=password
Where:
clientkeystore is the name of the client certificate keystore on the client computer.
type is the type of the client key, such as pkcs12.
password is the client keystore's passphrase.
If authentication and authorization is enabled for the VPN Provisioning API, you must supply valid administrator user name and password credentials when invoking the batch operation tools.
The built-in admin user object includes an attribute that specifies whether the username and password are validated. This attribute is named isSecurity for the VPN admin user and isForceSecurity for the Social Voice Communicator (SVC) admin user.
The value of the attribute can be:
true: The username and password are validated.
false: The username and password are not validated. Note, however, that they still must be supplied in the command.
After installing the Service Broker, you can find the batch operation tools and resources in the following directory:
Oracle_home/ocsb61/admin_server/utils/bulkloader
The directory contains the .sh and .bat versions of these tools:
batch_load: The common Batch Loader tool.
silent_ons_load: Silent Batch Loader tool for the SVC one number service.
silent_vm_load: Silent Batch Loader tool for the SVC voice mail service.
silent_vpn_load: Silent Batch Loader tool for the VPN service.
batch_check: The common Batch Validator tool.
silent_vpn_check_stores: Silent Batch Validator for the VPN service.
common: Script invoked by the other tools. You should not attempt to run this script directly.
In addition to the tools listed, the directory contains these subdirectories:
lib: Runtime files for the batch operation tools.
onsdata: Example data files for one number service. By default, the Silent Batch Loader for one number services loads the data in this directory.
vmdata: Example data files for voice mail service. By default, the Silent Batch Loader for the voice mail services loads the data in this directory.
vpndata: Example data files for VPN service. By default, the Silent Batch Loader for VPN services loads the data in this directory.
You can use the tools from a remote system by copying the entire contents of the bulkloader directory to the remote system. The remote system must have network access to the managed server.
The batch operation tools load and validate data in local data files you specify. The batch_load tool takes a data file as a command argument. You can create your own data file to pass to the batch_load tool or use a sample file included in the Administration Console distribution as a starting point.
The silent batch loader tools operate on all data files contained in the following directory:
Oracle_home/ocsb61/admin_server/utils/bulkloader/vpndata/
By default, this directory contains sample data files that you can use as a starting point for the data you want to load or validate. As illustrated by the sample files, you must use a separate data file for each type of VPN object you want to load or validate: VPNUser, VPNSubscriber, and so on.
The default files are:
1.vpnadmin.csv
2.sp.csv
3.vpnsubscriber.csv
4.workingtime.csv
5.vpnuser.csv
6.profile.csv
7.vpngroup.csv
8.person.csv
9.virtualuser.csv
To use the silent batch operation tools, either replace the contents of the sample CSV data files with the application data to be loaded or modify the file references in the Silent Batch Loader script to refer to files you have created. In general, Oracle recommends that you create a copy of the batch tools directory, and modify the contents of the sample files in the copied directory.
To modify the data, open and edit each file. If using a silent batch operation tool, be sure to remove the contents of any file that is not applicable to your update.
The format of the data in the file must match the format required for its object type. This format is illustrated in the first lines of each sample data file. The schema information shown in the first lines serves as documentation only, and does not affect how the batch operation tools process the data. It can be excluded from your own data files.
See "VPN Data File Format Reference" for reference information on the VPN data types. Also see "Provisioning VPN Services" for more information about the types of objects in the VPN data model.
Before you run the Batch Loader, you must create and populate the CSV file that contains the data to be loaded. See "Working with Batch Operation Data" for more information on specifying the data to be loaded.
The Batch Loader script is named batch_load. There is a version of the script for Linux and Windows operating systems. The Batch Loader syntax is:
batch_load.bat -n username -p password -url server_url -r replace_if_exists -t data_type -d data_file
Where:
username is the user name of a provider administrator.
password is the password for the provider administrator.
server_url is the IP address or host name and HTTP port number of the managed server.
replace_if_exists is a flag which, if true, causes existing data store objects to be entirely replaced by the contents of the data file. If false, the contents of the data file supplement or modify the existing data store objects, preserving existing data.
data_type is the type of data you are loading, such as vpnadmin for administrative users or vpnuser for VPN users. See "Working with Batch Operation Data" for more information.
data_file is the location and name of the CSV file that contains the data to be loaded.
For example:
./batch_load.sh -n admin -p password -url http://localhost:9001 -r true -t vpnsubscriber -d /home/utils/bulkloader/vpndata/1.vpnsubscriber.csv
This example loads data in a file named 1.vpnsubscriber.csv. If you do not include a required parameter in the command line, such as a password, the tool prompts you for a value.
The Batch Loader writes its results to a text-formatted log file in the directory from which it is run. The log file is named bulkloader.log. You can use the file to troubleshoot the operation of the tool or identify data format errors.
The Silent Batch Loader loads data from multiple data files into storage at a time. Its runtime parameters, including which CSV files to load, are specified within the Silent Batch Loader script.
A version of the Silent Batch Loader exists for each type of service: VPN service, one number service, and voice mail service. By default, the tools load the data from the default directory appropriate for the service. For example, the Silent Batch Loader for the VPN services loads the data files from the vpndata directory. Similarly, the Silent Batch Loader for voice mail services loads the data files from vmdata.
The Silent Batch Loader script for the VPN application is named silent_vpn_load.
After you have populated the CSV files with your application data (as described in "Working with Batch Operation Data"), use the Silent Batch Loader as follows:
Navigate to the batch operation tools directory and open the version of the silent_vpn_load file appropriate for your operating system, that is, the .bat version for Windows or .sh for Linux.
In the script, modify these settings:
ADMINNAME: The user name of a provider administrator.
PASSWORD: The password for the provider administrator.
URL: The IP address or host name and HTTP port number of the managed server. The default is http://localhost:9001.
batch_path: The directory path to the batch operation tools and resources.
output_path: The directory path to which the tools write error output.
data_file_path: The directory path where the data files to be loaded are located.
replaceIfExist: If true, existing data store objects are entirely replaced by the contents of the data file. If false (default), the contents of the data file supplement or modify the existing data store objects, preserving existing data.
checkOnLoad: If true, the tool validates the data before loading it into storage. The default is false. Note that the isBulk setting in the VPN admin user also specifies whether data should be validated. If the isBulk setting is false, meaning data should be validated, but checkOnLoad value is false, the checkOnLoad setting prevails, meaning, and data is not validated.
Loading data without validating it can improve performance, especially when loading a large amount of data. However, data validation should be used in most cases.
If needed, modify the names of the files to be loaded. The file names appear in the numbered steps section at the end of the script file.
Run the version of the Silent Batch Loader script appropriate for your operating system. For example, on a Linux system, enter the following command:
sh silent_vpn_load.sh
The script loads the data, and prints results to the screen. If successful, Done appears on the screen. Otherwise, error messages appear that describe errors encountered while validating or loading the data.
The Batch Validator tool can check the validity of the data in an input file or the data that is in storage. When using an input file, the data can be validated without loading it into storage. Validating data in storage allows you to discover data conflicts that have arisen from loading data when validation was disabled or from external actions, such as direct changes to the database.
The Batch Validator identifies broken dependencies between data objects, such as a reference from a group to a profile that does not exist.
When running the Batch Validator on stored data, you can have the tool export the data from the database to a file. This enables you to back up application data from storage to an external format that can be imported into another system.
The Batch Validator command syntax is:
batch_check.bat -n username -p password -url server_url {(-t data_type -d data_file) | (-s store_name -e export_file)} -o output_file
Where:
username is the user name of a provider administrator.
password is the password for the provider administrator.
server_url is the IP address or host name and HTTP port number of the managed server.
data_type is the type of data to be validated in a file, such as vpnadmin for administrative users or vpnuser for VPN users. Use only if validating data in a file, in which case you must also supply the data_file parameter.
data_file is the location and name of the CSV file that contains the data to be validated. See "Working with Batch Operation Data" for more information on how to make data available to the batch operation tools.
store_name is the type of data in storage to be validated, such as vpnadmin for administrative users or vpnuser for VPN users. Use only if validating data in storage, in which case you may also supply the export_file parameter.
export_file is the location and name of the file to which the tool writes data it exports from the store.
output_file is the location and name of the file to which the tool writes error output.
For example:
./batch_check.sh -n admin -p password -url http://localhost:9001 -t vpnsubscriber -d /oraHome_1/ocsb61/admin_server/utils/bulkloader/vpndatas/1.vpnsubscriber.csv
This example validates data in a file named 1.vpnsubscriber.csv. If you do not provide a required value in the command line, such as a password for the administrator, you are prompted for a value.
The Batch Validator writes its results to a text-formatted log file named bulkloader.log in the directory from which it is run. You can use the file to help troubleshoot operation or data format errors.
The Silent Batch Validator can validate data in multiple data files at a time or validate stored data of multiple types. Its runtime parameters are specified within the Silent Batch Validator script. By default, the Silent Batch Validator validates data in storage.
To validate application data by using the Silent Batch Validator:
In the batch operation tools directory, open the version of the silent_vpn_check file appropriate for your operating system: the .bat version for Windows or .sh for Linux.
In the script, modify these settings:
ADMINNAME: The user name of a provider administrator in your system.
PASSWORD: The password for the administrator.
URL: The IP address or host name of the computer on which the managed server is running and port at which it is listening for API requests. The default is http://localhost:9001.
batch_path: The directory path to the batch operation tools and resources.
output_path: The directory path to which you want to write output files.
If necessary, modify the commands in the file. By default, the commands direct the tool to validate existing storage and export the stored data to a file. Alternatively, you can have the tool validate data in a CSV file, suppress data export, or use any other option indicated in the batch_check help listing.
Run the version of the tool appropriate for your operating system.
For example, on a Linux system, enter the following command to validate VPN service data:
sh silent_vpn_check.sh
Output from the script is written to the screen. In addition, the Silent Batch Validator writes detailed results to a file in the output directory named for the respective data type and suffixed with _check_result. The tool exports data to CSV files in the output directory that are named with _data as their suffix.
The following sections describe the data file format for each type of object in the VPN data model, such as VPNUsers and VPNSubscribers. The sections indicate the data type name and format for each object type, with example data for each. In this context, the data type name corresponds to the value of the data type parameter passed to the Batch Loader and Silent Batch Loader tools (passed with the -t switch).
See "Working with Batch Operation Data" for information on how to make the data accessible to the batch operation tools.
All parameters are required unless indicated otherwise. See the information for the corresponding create or modify operation in "VPN Provisioning API Reference" for detailed descriptions of the parameters of each data type.
Administrator user data represents VPN subscriber administrator accounts. Provider administrators cannot be created with the Batch Loader.
vpnadmin
adminName,vpnID,adminPassword,role
bob,oracle_vpn,password,4
role must be 4. Provider (role 1) administrators cannot be added using the Batch Loader.
See "Create Administrator" for parameter details.
Service provider data represents the VPN service provider account. The Service provider is a pre-defined data object that contains global VPN settings. Because the system can have only one VPN service provider object, the CSV file cannot contain multiple data objects. It only contains values to be used to update the existing service provider object.
sp
name,description,address,privateCallMarker,pbxPrefix,localCountryCode,localAreaCode, mtcSuppressionPrefix,callBarringBlackList,numberRange
"Mobile Telco","Mobile telephone services operator","111 Elm St. 94114" ,7,,86,10,22,,"86139*;86138*"
callBarringBlackList and numberRange contain values separated by semicolon.
The name and localCountryCode parameters are required. All other parameters are optional.
See "Modify VPN Service Provider" for parameter details.
VPN subscriber data represents organizations that subscribe to hosted VPN services.
vpnsubscriber
vpnID,name,escapeCode,privateCallEnable,privateNumberCLI,maxExtensionNumberLength, forcedOnNet,partnerVPNSwitch,timeZone,worktimeID,exclusionList,partnerVPN, callBarringBlackList,callScreeningBlackList
"vpn001","Oracle",,"TRUE","TRUE",4,"TRUE","TRUE",8,,,"vpn003",, "vpn002","BEA",0,"TRUE","FALSE",4,"TRUE","TRUE",8,,,,"4434*;1555168210", "vpn003","Sun",9,"TRUE","FALSE",4,"TRUE","TRUE",8,,,,"535*;536*;537*",
exclusionList, partnerVPN, callBarringBlackList, and callScreeningBlackList contain data separated by semicolon.
The escapeCode, worktimeID, exclusionList, partnerVPN, callBarringBlackList, and callScreeningBlackList parameters are optional. All other parameters are required.
See "Create VPN Subscriber" for parameter details.
VPN user data represents a PBX-based or mobile on-net device.
vpnuser
publicPhoneNumber,vpnID,phoneExtension,memberType,closedUserGroupID,homeProfileID,roamingProfileID,personID,privateCallEnable
861395551001,"vpn001",1001,0,"bjEmp,"alicehomeProfile","aliceroamProfile",,"TRUE" 861395551002,"vpn001",1002,0,"bjEmp",,,,"FALSE" 861395551003,"vpn001",1003,0,"bjManager",,,,"FALSE" 861395551110,"vpn001",1110,0,,,,,"TRUE" 861395551005,"vpn001",1005,0,"bjEmp","johnhomeProfile","aliceroamProfile",,"TRUE" "86105550111*","vpn001","111*",1,,,,,"FALSE"
The closedUserGroupID, homeProfileID, roamingProfileID, and personID parameters are optional. All other parameters are required.
See "Create VPN User" for parameter details.
User group data represents a set of VPN users in a subscriber organization.
vpngroup
groupID,vpnID,parentCugID,homeProfileID,roamingProfileID,description,privateCallEnable
"hqgroup","vpn001",,"hqGroupProfile",,"Parent group for headquarter-based managers and non-managers; branch managers","TRUE" "hqEmp","vpn001","hqgroup","hqEmpProfile",,"non-manager group","TRUE" "hqManager","vpn001","hqgroup","hqManagerProfile",,,"TRUE"
The parentCugID, homeProfileID, roamingProfileID, and description parameters are optional. All other parameters are required.
See "Create User Group" for parameter details.
Person data represents end users of the VPN.
person
personID,vpnID,name
"alice","vpn001","Alice Smith" "bob","vpn001","Bob D. Green"
See "Create Person" for parameter details.
Working time data represents the work hours for a VPN subscriber organization or user group.
workingtime
workingtimeID,vpnID,StartingHours,StartingMinutes,EndingHours,EndingMinutes
"workingtime1","vpn001","0;9;9;9;9;9;0","0;0;0;0;0;0;0", "0;18;18;18;18;18;0","0;0;0;0;0;0;0" "workingtime2","vpn001","0;19;19;19;19;19;0","0;0;0;0;0;0;0", "0;23;23;23;23;23;0","0;0;0;0;0;0;0"
StartingHours, StartingMinutes, EndingHours, and EndingMinutes contain values separated by semicolon. Each value in the array represents the starting or ending time on a day of the week, beginning with Sunday.
See "Create Working Time" for parameter details.
VPN profile data contains a usage policy that can be applied to the VPN.
profile
profileID,vpnID,worktimeID,description,timeZone,callScreeningList,callBarringList,durationControlList
"hqManagerProfile","vpn001",,"HQ manager's profile",8,,,"99999;99999;3600;60" "aliceProfile","vpn001","workingtime1","Alice's profile when in home network",8,"|5||false","|9|1|true","99999;99999;99999;99999" "aliceRoamProfile","vpn001","workingtime1","Alice's profile when roaming",8,,"|9||false","99999;99999;99999;99999"
durationControlList contains values separated by semicolon.
callBarringList and callscreeningList contain access control items, which have the following format:
"range|type|timespan|permit;range|type|timespan|permit"
As shown, vertical bar characters (|) separate individual fields in the access control rule, and semicolons separate multiple access control rules.
The worktimeID, description, callScreeningList, and callBarringList parameters are optional. All other parameters are required.
See "Create Profile" for parameter details.
Virtual user data represents an entity that is external to the organization but is assigned an extension on the VPN.
virtualuser
publicPhoneNumber,vpnID,name,phoneExtension
861015551999,vpn001,virtualuser01,1999 861015559999,vpn001,virtualuser02,9999 862125552999,vpn002,virtualuser03,2999
The phoneExtension number allocated by the Batch Loader is subject to the restrictions defined for the subscriber, such as maximum length and allocation exclusion lists.
See "Create Virtual User" for parameter details.
|
 Copyright © 2011, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|