The Key Vault RESTful Services utility enables you to automate the processes of endpoint enrollment, and virtual wallet management for a large distributed enterprise deployment.
Though the Oracle Key Vault management console user interface is efficient for managing several endpoints, the process of defining access control mappings between endpoints and virtual wallets is a manual one, with human administrators having to click through the user interface.
A large distributed enterprise deployment often requires automation through scripting to enable mass deployment. The RESTful services feature in Oracle Key Vault enables you to enroll and provision hundreds of endpoints, and define access control mappings between endpoints and their respective virtual wallets, to facilitate faster deployment with less human intervention. Additionally, you can automate the management of users, user groups, and endpoint groups with this feature.
With RESTful services, you can enroll and provision endpoints, create endpoint groups, and define access control mappings between endpoints, endpoint groups and virtual wallets. You can execute a single service command from the command line, or execute multiple service commands from a script. To run the service commands from the command line or the script, you will need a configuration file with certain properties set. In order to run the RESTful Service utility, the endpoint must have at minimum Java Runtime Environment version 1.7.0.21 installed.
You can use RESTful services in both Oracle Real Application Clusters (Oracle RAC) and multitenant environments. The configuration process in these environments is identical to the single instance environment.
After you use RESTful services to enroll and provision endpoints, you should disable the RESTful services to minimize the number of entry points to Oracle Key Vault.
You will follow these general steps to use the RESTful services execution process:
Enable RESTful services from the Oracle Key Vault management console.
Download the RESTful service utility okvrestservices.jar
.
Create a configuration file, and then set the properties for the services that you want to run.
Execute the service using the RESTful service utility okvrestservices.jar
, the configuration file, and service command plus options.
To run multiple RESTful service commands you must:
Create a script, and write the RESTful commands into the script.
Execute the services using the RESTful service utility okvrestservices.jar
, the configuration file, and the script file.
Disable RESTful services when you are finished enrolling and provisioning endpoints.
Parent topic: Endpoint Enrollment Automation with RESTful Services
There are three steps to enabling and using RESTful Services successfully.
Parent topic: Endpoint Enrollment Automation with RESTful Services
You must configure web access for RESTful clients by their IP addresses to access the Oracle Key Vault server. You can allow all IP addresses or restrict access to a subset of IP addresses that you designate in this step. Note, that this option will also restrict access to the Oracle Key Vault management console.
To enable network services:
Log in to the Oracle Key Vault management console as a user with System Administrator privileges.
Select System, then System Settings from the left sidebar.
The Settings page appears.
Go to the Network Services section
For Web Access select one of the IP address options for the RESTful client:
All to allow all IP addresses.
IP address(es) to designate a set of IP addresses. After you select this option enter the IP address(es) in the next field, separating each IP address by a space.
Click Save on the top right.
Parent topic: Enable RESTful Services
To enable RESTful Services:
Parent topic: Enable RESTful Services
To download the RESTful software utility okvrestservices.jar:
Note:
If you install a third-party certificate you must download the RESTful software utility okvrestservices.jar
again in order to use the new certificate.
You must re-download the RESTful software utility any time you change the certificate, or re-install the Key Vault appliance with new software or a backup.
Parent topic: Enable RESTful Services
You must set properties in the configuration file that the RESTful service utility will use to run commands.
Parent topic: Endpoint Enrollment Automation with RESTful Services
Two sample configuration files using the IP Address and Hostname for the server property are shown below:
Example 10-1 Configuration File Using IP Address
server=192.0.2.254 usr=okvadmin log=/<absolute_path_to_your_log_file>/<your_log_file_name> log_level=warning
Example 10-2 Configuration File Using Host Name
server=HR_HQ-Database usr=okvadmin log=/<absolute_path_to_your_log_file>/<your_log_file_name> log_level=warning
Parent topic: Endpoint Enrollment Automation with RESTful Services
If you only want to run a few commands, you can run them singly from the command using the -r
or --service
option.
To run a single RESTful command:
script
property.-c
option, the service with the -r
or --service
option, and the command specific options.For example:
java -jar okvrestservices.jar -c conf_file -r create_endpoint -e hr_db_ep -d "HR database endpoint" -q solaris64 -t oracle_db -m psmith@enterprise.com User: Key_Vault_user_name Password: Key_Vault_user_password
In this example:
-c
refers to the configuration file: conf_file
.
-r
refers to the RESTful service: create_endpoint
.
-e
refers to the endpoint name: hr_db_ep.
-d
refers to the description of the end point: HR database endpoint
.
-q
refers to the endpoint platform: solaris64
.
-t
refers to the endpoint type: oracle_db
.
-m
refers to the endpoint email: psmith@enterprise.com
.
Note:
Command line options have the priority over options specified in the configuration file or script. For example, if the property usr
is specified in the configuration file and the command line, the command line option will override the one in the configuration file.
Parent topic: Endpoint Enrollment Automation with RESTful Services
You can run a sequence of commands from the command line one at a time. However, a more efficient way to run a sequence of commands is to write them into a script. Each command in the script file is interpreted as a service command. You must invoke the script with the -i
or --script
option and provide the path to the script file.
Note:
You can define the script
property in the configuration file to avoid entering it in the command line. The script
parameter is entered only once: either in the configuration file or the command line.
To create the script:
The RESTful Services utility executes one command at a time. If a command fails the script will exit. The log file displays the results of all executed commands with their line numbers and messages reported at run time. This information appears for all log levels.
See Also:
Error Reporting to learn more about logging in Key Vault
Parent topic: Endpoint Enrollment Automation with RESTful Services
Use the guidelines below to avoid script execution errors:
The commands and syntax in the script are identical to those used on the command line.
Each line in the script must be either a command or a line starting with the character #.
Each command should be on its own line.
Lines that do not have a command must start with the # character.
Use the # character for comment and blank lines.
The order in which command options appear do not matter.
All required options must have valid values.
You must specify the -i
or --script
option.
Descriptions used for the -d
or --desc
option must be enclosed in double quotes if they contain spaces.
Parent topic: Endpoint Enrollment Automation with RESTful Services
RESTful Services are disabled by default. We recommend that you enable RESTful Services for short periods during endpoint registration and enrollment only. After endpoints are enrolled you should disable RESTful Services.
To disable RESTful Services:
Parent topic: Endpoint Enrollment Automation with RESTful Services
The RESTful Services command reference contains a detailed explanation of all the commands with examples, that will help you write and execute commands quickly.
Parent topic: Endpoint Enrollment Automation with RESTful Services
You must use the java -jar
command to run the RESTful Services utility okvrestservices
and provide a path to the configuration file.
The following table lists the common options used by all RESTful service commands:
Table 10-2 Options Common to all RESTful Commands
Option | Required? | Description |
---|---|---|
|
Required |
Refers to the absolute path to the configuration file. |
|
Required for multiple RESTful service commands |
Refers to the absolute path to the script file. You must set this property in order to run multiple RESTful service commands. |
|
Required |
Refers to the RESTful service you want to execute listed in Table 2. |
|
Optional |
Refers to the username of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, you will be prompted to enter the username interactively. |
|
Optional |
Refers to the password for the Oracle Key Vault user account specified in the --usr option. If you omit this option, you will be prompted to enter the password interactively (recommended for greater security). |
The following table lists the RESTful service commands that you can use with the -r
or --service <arg>
option.
Table 10-3 List of RESTful Service Commands
RESTful Service Command | Description |
---|---|
|
Adds an endpoint to Key Vault. When added, the endpoint is in registered state. |
|
Gets the enrollment token to download the endpoint software for the registered endpoint. |
|
Downloads the endpoint software |
|
Downloads and installs the endpoint software okvclient.jar.After this the endpoint is in enrolled state. |
|
Reenrolls an endpoint. |
|
Reenrolls all endpoints. |
|
Removes an endpoint from Key Vault. |
|
Adds a new endpoint group. |
|
Adds an endpoint to an endpoint group. The endpoint must already exist. |
|
Removes an endpoint from an endpoint group. |
|
Deletes an endpoint group. |
|
Adds a virtual wallet to Oracle Key Vault. |
|
Sets access mappings on a virtual wallet for an endpoint. |
|
Changes access mappings on a virtual wallet for an endpoint. |
|
Removes access mappings on a virtual wallet for an endpoint. |
|
Sets the default wallet for an endpoint. |
get_default_wallet |
Gets the default wallet for an endpoint. |
get_wallets |
Gets all virtual wallets for an endpoint. |
|
Sets access mappings on a virtual wallet for an endpoint group. |
|
Changes access mappings on a virtual wallet for an endpoint group. |
|
Removes access mappings on a virtual wallet for an endpoint group. |
|
Removes the virtual wallet from Key Vault. |
|
Changes the virtual wallet description. |
|
Changes the endpoint name. |
|
Changes the endpoint platform. |
|
Changes the endpoint type. |
|
Changes the endpoint description. |
|
Changes the endpoint's email. |
|
Changes the endpoint group's description. |
Example 10-3 Specifying Short Form Options
Specify short form options by using a single hyphen before the option.
java -jar okvrestservices.jar -c <path> [-r <RESTful_service> | -i <path>]
Example 10-4 Specifying Long Form Options
Specify long form options by using a double hyphen before the option.
java -jar okvrestservices.jar --config <path> [--service <RESTful_service> | --script <path>]
Parent topic: RESTful Services Command Reference
The following example shows RESTful service commands that pertain to Oracle wallets specified by the --client_wallet
option. This wallet is used to store the user name and password in unattended mode to enable automated endpoint provisioning with no human intervention.
This is different from the virtual wallet specified by the --wallet
option that are part of the virtual wallet commands.
Table 10-4 Wallet Command Options
Option | Required? | Description |
---|---|---|
-A, --add |
Optional |
Adds a user to wallet. |
-M, --modify |
Optional |
Modifies a user's password. |
-L, --listuser |
Optional |
Lists the users who have access to a wallet. |
-D, --delete |
Optional |
Deletes a user from a wallet. |
-w, --wallet_name <arg> |
Required |
Stands for the wallet name. |
-j, --client_wallet <arg> |
Required |
Stands for the absolute path to the wallet location. |
-f, --force |
Optional |
Performs the operation without prompting for confirmation. |
Example 10-5 Wallet Command Syntax
Grant a user access to a wallet:
java -jar okvrestservices.jar -c <path_to_configuration file>/rest.init --client_wallet <absolute path to wallet location> --add <user>
Modify a user password:
java -jar okvrestservices.jar -c <path_to_configuration file>/rest.init --client_wallet <absolute path to wallet location> --modify <user>
List all the users who have access to a wallet:
java -jar okvrestservices.jar --config <path_to_configuration file>/rest.init --client_wallet <absolute path to wallet location> --listuser <user>
Delete a user's access to a wallet:
java -jar okvrestservices.jar --config <path_to_configuration file>/rest.init --client_wallet <absolute path to wallet location> --delete <user>
Parent topic: RESTful Services Command Reference
The following group of commands: create, enroll, get_enrollment_token, download, and provision are used to add and enroll an endpoint to Key Vault. The endpoint is enrolled when the endpoint software okvclient.jar
is downloaded and installed at the endpoint. An enrolled endpoint can upload security objects to Key Vault in order to store, share, and manage.
re_enroll_al
command re-enrolls all previously enrolled endpoints in order to upgrade the endpoint software.Parent topic: RESTful Services Command Reference
The create_endpoint
command adds a new endpoint to Oracle Key Vault. After you add the endpoint, the endpoint will be in the Registered state.
Syntax
Short form:
create_endpoint -e endpoint_name -d "description" -q platform -m email_address -t type
Long form:
create_endpoint --ep_name endpoint_name --desc "description" --ep_platform platform --ep_email email_address --ep_type type
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
The name of the endpoint you want to add |
|
Optional |
A user friendly description of the endpoint. If the description contains spaces, you must enclose it within double quotation marks. |
|
Required |
The endpoint platform. Allowed values are:
|
|
Required |
Type of the endpoint. Allowed values are:
|
|
Optional |
Email address of the endpoint administrator |
|
Required |
Specifies the object type to check. Valid values include:
|
|
Required |
Specifies the absolute path to the configuration file |
|
Required for multiple RESTful service commands |
Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands. |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax |
|
Optional |
Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively |
Short Form Example
In this example, an endpoint called hr_db_ep
is added with an optional identifying description 'HR database endpoint'
, of type oracle_db
, on platform solaris64
, and endpoint administrator email, psmith@example.com
.
java -jar okvrestservices.jar -c conf_file -r create_endpoint -e hr_db -d "HR database endpoint" -q solaris64 -t oracle_db -m psmith@example.com -
Long Form Example
java -jar okvrestservices.jar --config conf_file --service create_endpoint --ep_name hr_db --desc "HR database endpoint" --ep_platform solaris64 --ep_type oracle_db --ep_email psmith@example.com
Parent topic: Commands to Add and Enroll Endpoints
The get_enrollment_token
command retrieves an enrollment token for a registered endpoint. This command will work only for endpoints in registered state. If the endpoint is already enrolled, you will get an error message.
Syntax
Short form:
get_enrollment_token -e endpoint_name
Long form:
get_enrollment_token --ep_name endpoint_name
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
Short Form Example
In this example a registered endpoint hr_db_ep gets the enrollment token, that will be used to download and install the endpoint software to the endpoint.
java -jar okvrestservices.jar -c conf_file -r get_enrollment_token -e hr_db_ep
Long Form Example
java -jar okvrestservices.jar --config conf_file --service get_enrollment_token --ep_name hr_db_ep
Parent topic: Commands to Add and Enroll Endpoints
The download
command downloads the endpoint software (okvclient.jar
) to a directory that you name. The directory path is specified by the -o option. You can specify the absolute or relative path, or even set an environment variable to point to the path. If the directory exists, you will see an error message saying that the directory exists.
You can use either the download command or the provision command to enroll the endpoint. You cannot use both for a given endpoint.
Syntax
Short form:
download -e endpoint_name -o <directory>
Long form:
download --ep_name endpoint_name -dir <directory>
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
Absolute path to the download directory for the endpoint software. |
Short Form Example
In this example the endpoint software, okvclient.jar
is downloaded to /home/oracle/downloads/
for endpoint hr_db_ep
.
java -jar okvrestservices.jar -c conf_file -r download -e hr_db_ep -o /home/oracle/downloads/
Long Form Example
java -jar okvrestservices.jar --config conf_file --service download --ep_name hr_db_ep --dir /home/oracle/downloads/
Parent topic: Commands to Add and Enroll Endpoints
You must meet the following prerequisites to run this command:
You must be a user with system administrative privileges
The soft link/usr/bin/java
should point to Java 1.4 or above.
You must know how the installation process determines the location of the okvclient.ora
file
The provision
command downloads and installs the endpoint software in the specified directory, which should exist. This directory should have read, write and execute permissions for the owner and its group. For example, if Key Vault endpoint software is installed in an Oracle Database server, this endpoint installation directory should have read, write, and execute permissions by the user oracle
and the group oinstall
. This ensures that processes can access directories appropriately at runtime.
You can use either the download command or the provision command to enroll the endpoint. You cannot use both for a given endpoint
Syntax
Short form:
provision [-a|-v account_pwd ] -e endpoint_name -o <directory_path>
Long form:
When password is used to authenticate:
provision --endpoint_password account_pwd -ep_name endpoint_name --dir <directory_path>
When no password is used (auto-login):
provision --autologin -ep_name endpoint_name --dir <directory_path>
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
Existing directory in which to download and install the endpoint software. |
|
Optional |
Endpoint password. If you omit this option (recommended), then the provision command prompts you for the password interactively. You must supply the password used for the wallet during endpoint software installation to communicate with the Key Vault server over mutually authenticated TLS. If you created an auto-login wallet without a password during endpoint software installation the endpoint credentials are stored in an Oracle wallet. |
|
Required |
It means that endpoint credentials to connect to the Key Vault server are stored in an auto-login wallet. |
Short Form Examples
Auto-login Mode
In this example, the endpoint software is installed for endpoint hr_db_ep
in the directory /home/oracle/okvutil
without a password (in autologin mode).
java -jar okvrestservices.jar -c conf_file -r provision -a -e hr_db_ep -o /home/oracle/okvutil/ -a
Password-protected Mode
In this example, the endpoint software is installed for endpoint hr_db_ep
in the directory /home/oracle/okvutil
with a password. Because the password option (-v --client_password
) is omitted, it must be entered on the command line when prompted.
java -jar okvrestservices.jar -c conf_file -r provision -e hr_db_ep -o /home/oracle/okvutil/
Long Form Examples
java -jar okvrestservices.jar --config conf_file --service provision --autologin --ep_name hr_db_ep --dir /home/oracle/okvutil/ -a java -jar okvrestservices.jar --config conf_file --service provision --ep_name hr_db_ep --dir /home/oracle/okvutil/
Parent topic: Commands to Add and Enroll Endpoints
The re_enroll
command re-enrolls a previously enrolled endpoint in order to upgrade the endpoint software.
Syntax
Short form:
re_enroll -e endpoint_name
Long form:
re_enroll --ep_name endpoint_name
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
In this example, endpoint hr_db_ep
will be reenrolled.
java -jar okvrestservices.jar -c conf_file -r re_enroll -e hr_db_ep
Long Form Example
java -jar okvrestservices.jar --config conf_file --service re_enroll --ep_name hr_db_ep
Parent topic: Commands to Add and Enroll Endpoints
The re_enroll_al
command re-enrolls all previously enrolled endpoints in order to upgrade the endpoint software.
Syntax
Short and long form:
re_enroll_all
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Specifies the absolute path to the configuration file |
|
Required for multiple RESTful service commands |
Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands. |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax |
|
Optional |
Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively |
Short Form Example
java -jar okvrestservices.jar -c conf_file -r re_enroll
Long Form Example
java -jar okvrestservices.jar --config conf_file --service re_enroll
Related Topics
Parent topic: Commands to Add and Enroll Endpoints
The delete_endpoint
command removes an endpoint from Key Vault. A confirmation message appears asking if you are sure you want to delete the endpoint.
You may use the -f
or --force
option to remove the endpoint without a confirmation message. Use the -f
or --force
option carefully as it suppresses the confirmation message.
Syntax
Short form:
delete_endpoint -f -e endpoint_name
Long form:
delete_endpoint --force --ep_name endpoint_name
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required. |
Name of the endpoint. |
|
Optional. |
Forces the deletion and suppresses the confirmation message. |
Short Form Example
This example shows endpoint sales_db_ep
being removed from Key Vault without confirmation.
java -jar okvrestservices.jar -c conf_file -r delete_endpoint -f -e sales_db_ep
Long Form Example
java -jar okvrestservices.jar --config conf_file --service delete_endpoint --force --ep_name sales_db_ep
Parent topic: Commands to Add and Enroll Endpoints
You can modify endpoint details after creating the endpoint to accommodate changes in function, name, platform, type, and email.
Parent topic: RESTful Services Command Reference
The modify_endpoint_name
command changes the name of an endpoint.
Syntax
Short form:
modify_endpoint_name -e endpoint_name -n new_endpoint_name
Long form:
modify_endpoint_name --ep_name endpoint_name --ep_new_name new_endpoint_name
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
New name for this endpoint |
Short Form Example
This example changes the name of endpoint hr_db
to that of hr_db_ep
.
java -jar okvrestservices.jar -c conf_file -r modify_endpoint_name -e hr_db -k hr_db_ep
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_endpoint_name --ep_name hr_db --ep_new_name hr_db_ep
Parent topic: Modify Endpoint Details Commands
The modify_endpoint_type
command changes the endpoint type.
Syntax
Short form:
modify_endpoint_type -e endpoint_name -t endpoint_type
Long form:
modify_endpoint_type --ep_name endpoint_name --ep_type endpoint_type
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
Type of the endpoint. Values are as follows:
|
Short Form Example
This example changes the endpoint type for endpoint hr_db
to oracle_db
.
java -jar okvrestservices.jar -c conf_file -r modify_endpoint_type -e hr_db -t oracle_db
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_endpoint_type --ep_name hr_db --ep_type oracle_db
Parent topic: Modify Endpoint Details Commands
The modify_endpoint_platform
command changes the platform for an endpoint.
Syntax
Short form:
modify_endpoint_platform -e endpoint_name -q endpoint_platform
Long form:
modify_endpoint_platform --ep_name endpoint_name --ep_platform endpoint_platform
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
Platform of the server for this endpoint. Values are as follows:
|
|
Required |
Specifies the object type to check. Valid values include:
|
|
Required |
Specifies the absolute path to the configuration file |
|
Required for multiple RESTful service commands |
Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands. |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax |
|
Optional |
Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively |
Short Form Example
This example changes the platform for endpoint hr_db
to aix
.
java -jar okvrestservices.jar -c conf_file -r modify_endpoint_platform -e hr_db -q aix
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_endpoint_platform --ep_name hr_db --ep_platform aix
Parent topic: Modify Endpoint Details Commands
The modify_endpoint_desc
command changes the description of an endpoint.
Syntax
Short form:
modify_endpoint_desc -e endpoint_name -d "new_desc"
Long form:
modify_endpoint_desc --ep_name endpoint_name --desc "new_desc"
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
New description string for this endpoint enclosed within double quotes. |
Short Form Example
This example changes the endpoint description for endpoint hr_db
to “HR database endpoint group
".
java -jar okvrestservices.jar -c conf_file -r modify_endpoint_desc -e hr_db -d "HR database endpoint group"
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_endpoint_desc --ep_name hr_db --desc "HR database endpoint group"
Parent topic: Modify Endpoint Details Commands
The modify_endpoint_email
command changes the email address for the endpoint.
Syntax
Short form:
modify_endpoint_email -e endpoint_name -m endpoint_email_address
Long form:
modify_endpoint_email --ep_name endpoint_name --ep_email endpoint_email_address
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
The new email address for this endpoint |
Short Form Example
This example changes the email of endpoint hr_db
to tjones@enterprise.com
.
java -jar okvrestservices.jar -c conf_file -r modify_endpoint_email -e hr_db -m tjones@enterprise.com
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_endpoint_email --ep_name hr_db --ep_email tjones@enterprise.com
Parent topic: Modify Endpoint Details Commands
Parent topic: RESTful Services Command Reference
The create_endpoint_group
command creates a new endpoint group.
Syntax
Short form:
create_endpoint_group -g endpoint_group_name -d "endpoint group description"
Long form:
create_endpoint_group --epg_name endpoint_group_name --desc "endpoint group description"
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint group. |
|
Optional |
A user-friendly description of the endpoint group enclosed within double quotes. |
Short Form Example
This example shows an endpoint group called epg_hr
being created with the description “HR endpoint group
“.
java -jar okvrestservices.jar -c conf_file -r create_endpoint_group -g epg_hr -d "HR endpoint group"
Long Form Example
java -jar okvrestservices.jar --config conf_file --service create_endpoint_group --epg_name epg_hr --desc "HR endpoint group"
Parent topic: Endpoint Group Commands
The add_epg_member
command adds an existing endpoint to an endpoint group. If the endpoint does not exist, you will get an error message.
Syntax
Short form:
add_epg_member -g endpoint_group_name -e endpoint_member
Long form:
add_epg_member --epg_name endpoint_group_name --ep_name endpoint_member
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
Name of the endpoint group. |
Short Form Example
This example shows an endpoint called hr_db_ep
being added to endpoint group epg_hr.
java -jar okvrestservices.jar -c conf_file -r add_epg_member -g epg_hr -e hr_db_ep
Long Form Example
java -jar okvrestservices.jar --config conf_file --service add_epg_member --epg_name epg_hr --ep_name hr_db_ep
Parent topic: Endpoint Group Commands
The drop_epg_member
command removes an endpoint from an endpoint group.
Syntax
Short form:
drop_epg_member -g endpoint_group -e endpoint_name
Long form:
drop_epg_member --epg_name endpoint_name --ep_name endpoint_group
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
Name of the endpoint group. |
Short Form Example
This example shows endpoint hr_db_ep
being removed from endpoint group epg_hr
.
java -jar okvrestservices.jar -c conf_file -r drop_epg_member -e hr_db_ep -g epg_hr
Long Form Example
java -jar okvrestservices.jar --config conf_file --service drop_epg_member --ep_name hr_db_ep --epg_name epg_hr
Parent topic: Endpoint Group Commands
The delete_endpoint_group
command removes an endpoint group from Key Vault. If the endpoint group does not exist you will see an error message.
Syntax
Short form:
delete_endpoint_group -f -g endpoint_group
Long form:
delete_endpoint_group --force --endpoint_group
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint group. |
|
Optional |
Force the deletion and suppresses the confirmation message. |
Short Form Example
This example deletes the endpoint group epg_hr
.
java -jar okvrestservices.jar -c conf_file -r delete_endpoint_group -f -g epg_hr
Long Form Example
java -jar okvrestservices.jar --config conf_file --service delete_endpoint_group --force --epg_name epg_hr
Parent topic: Endpoint Group Commands
The modify_endpoint_group_desc
command changes the description of an endpoint group.
Syntax
Short form:
modify_endpoint_group_desc -g endpoint_group_name -d "endpoint_group_description"
Long form:
modify_endpoint_group_desc --epg_name endpoint_group_name --desc "endpoint_group_description"
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint group. |
|
Required |
The new description string for the endpoint group enclosed within double quotes. |
Short Form Example
This example shows the endpoint group epg_hr
getting a description “HR DB endpoint group
“.
java -jar okvrestservices.jar -c conf_file -r modify_endpoint_group_desc -g epg_hr -d "HR DB endpoint group"
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_endpoint_group_desc --epg_name epg_hr --desc "HR DB endpoint group"
Parent topic: Endpoint Group Commands
Virtual wallet commands enable you to manage the lifecycle of a virtual wallet or define access control mappings between virtual wallets and endpoints or endpoint groups.
You must be a key administrator to run virtual wallet commands.
Parent topic: RESTful Services Command Reference
The create_wallet
command enables you to create a virtual wallet.
Syntax
Short form:
create_wallet -w virtual_wallet_name -d "wallet_description"
Long form:
create_wallet --wallet_name wallet_name --desc "wallet_description"
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the virtual wallet. |
|
Optional |
A descriptive name for the virtual wallet enclosed within double quotes. |
Short Form Example
This example creates a wallet named hr_wallet
with the description “HR DB endpoint group
“.
java -jar okvrestservices.jar -c conf_file -r create_wallet -w hr_wallet -d "Virtual wallet for HR endpoint"
Long Form Example
java -jar okvrestservices.jar --config conf_file --service create_wallet --wallet hr_wallet --desc "Virtual wallet for HR endpoint"
Parent topic: Virtual Wallet Commands
The modify_wallet_desc
command modifies the description of an existing virtual wallet.
Syntax
Short form:
modify_wallet_desc -w virtual_wallet_name -d "wallet_desc"
Long form:
modify_wallet_desc --wallet_name virtual_wallet_name --desc "wallet_desc"
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the virtual wallet. |
|
Required |
The new description string for the virtual wallet enclosed within double quotes. |
Short Form Example
This example gives the wallet hr_wallet
a new description of “HR endpoint virtual wallet
“.
java -jar okvrestservices.jar -c conf_file -r modify_wallet_desc -w hr_wallet -d "HR endpoint virtual wallet"
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_wallet_desc --wallet_name hr_wallet --desc "HR endpoint virtual wallet"
Parent topic: Virtual Wallet Commands
The add_wallet_access_ep
command grant an endpoint a level of access to a virtual wallet.
Syntax
Short form:
add_wallet_access_ep -e endpoint_name -w virtual_wallet_name -l wallet_access_level
Long form:
add_wallet_access_ep --ep_name endpoint_name --wallet_name virtual_wallet_name --access_level wallet_access_level
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
Name of the virtual wallet. |
|
Required |
Level of access for the virtual wallet. Values are as follows:
|
Short Form Example
This example adds the read-only access privilege on the wallet hr_wallet
to endpoint hr_db_ep
.
java -jar okvrestservices.jar -c conf_file -r add_wallet_access_ep -e hr_db_ep -w hr_wallet -l ro
Long Form Example
java -jar okvrestservices.jar --config conf_file --service add_wallet_access_ep --ep_name hr_db_ep --wallet_name hr_wallet --access_level ro
Parent topic: Virtual Wallet Commands
The modify_wallet_access_ep
command changes the virtual wallet access level to an endpoint.
Syntax
Short form:
modify_wallet_access_ep -e endpoint_name -w virtual_wallet_name -l virtual_wallet_access_level
Long form:
modify_wallet_access_ep --ep_name endpoint_name --wallet_name virtual_wallet_name --access_level wallet_access_level
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
Name of the virtual wallet. |
|
Required |
Level of access for the virtual wallet. Values are as follows:
|
Short Form Example
This example modifies the access level on wallet hr_db
to read-only plus manage wallet.
java -jar okvrestservices.jar -c conf_file -r modify_wallet_access_ep -e hr_db_ep -w hr_wallet -l ro_mw
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_wallet_access_ep --ep_name hr_db_ep --wallet_name hr_wallet --access_level ro_mw
Parent topic: Virtual Wallet Commands
The drop_wallet_access_ep
command removes an endpoint's access to a wallet.
Syntax
Short form:
drop_wallet_access_ep -e endpoint_name -w virtual_wallet_name
Long form:
drop_wallet_access_ep --ep_name endpoint_name --wallet_name virtual_wallet_name
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
Name of the virtual wallet. |
Short Form Example
This example removes access to wallet hr_wallet
for the endpoint hr_db_ep
.
java -jar okvrestservices.jar -c conf_file -r drop_wallet_access_ep -e hr_db_ep -w hr_wallet
Long Form Example
java -jar okvrestservices.jar --config conf_file --service drop_wallet_access_ep --ep_name hr_db_ep --wallet_name hr_wallet
Parent topic: Virtual Wallet Commands
The set_default_wallet
command sets the default wallet for an endpoint.
Syntax
Short form:
set_default_wallet -e endpoint_name -w virtual_wallet_name
Long form:
set_default_wallet --ep_name --wallet_name virtual_wallet_name
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the virtual wallet. |
|
Required |
Endpoint name for whom default wallet is set. |
Short Form Example
This example sets the default wallet hr_wallet
for the endpoint hr_db
.
java -jar okvrestservices.jar -c conf_file -r set_default_wallet -e hr_db -w hr_wallet
Long Form Example
java -jar okvrestservices.jar --config conf_file --service set_default_wallet --ep_name hr_db --wallet_name hr_wallet
Parent topic: Virtual Wallet Commands
The get_default_wallet
command gets the default wallet associated with an endpoint.
Syntax
get_default_wallet -e endpoint_name
get_default_wallet --ep_name endpoint_name
Parameters
Parameter | Required? | Description |
---|---|---|
-e, |
Required | Endpoint name, whose default wallet to get. |
Short Form Example
hr_db
you must supply the endpoint name to the command as follows:
java -jar okvrestservvices.jar -c conf_file -r get_default_wallet -e hr_db
Long Form Example
java -jar okvrestservvices.jar -c conf_file -service get_default_wallet --ep_name hr_db
Parent topic: Virtual Wallet Commands
The get_wallets
command gets all the virtual wallets associated with an endpoint.
Syntax
get_wallets -e endpoint_name
get_wallets --ep_name endpoint_name
Parameters
Parameter | Required? | Description |
---|---|---|
-e, |
Required | Endpoint name, whose virtual wallets to get. |
Short Form Example
hr_db
you must supply the endpoint name to the command as follows:
java -jar okvrestservvices.jar -c conf_file -r get_wallets -e hr_db
Long Form Example
java -jar okvrestservvices.jar -c conf_file -service get_wallets --ep_name hr_db
Parent topic: Virtual Wallet Commands
The add_wallet_access_epg
command grants an endpoint group a level of access to a virtual wallet.
Syntax
Short form:
add_wallet_access_epg -g endpoint_group_name -w virtual_wallet_name -l virtual_wallet_access_level
Long form:
add_wallet_access_epg --epg_name endpoint_group_name --wallet_name virtual_wallet_name --access_level wallet_access_level
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint group. |
|
Required |
Name of the virtual wallet. |
|
Required |
Level of access for the virtual wallet. Values are as follows:
|
Short Form Example
This example shows read-only access being granted to endpoint group epg_hr
.
java -jar okvrestservices.jar -c conf_file -r add_wallet_access_epg -g epg_hr -w hr_wallet -l ro
Long Form Example
java -jar okvrestservices.jar --config conf_file --service add_wallet_access_epg -epg_name epg_hr --wallet_name hr_wallet --access_level ro
Parent topic: Virtual Wallet Commands
The modify_wallet_access_epg
command modifies the virtual wallet access level to an endpoint group.
Syntax
Short form:
modify_wallet_access_epg -g endpoint_group_name -w virtual_wallet_name -l virtual_wallet_access_level
Long form:
modify_wallet_access_epg --epg_name endpoint_group_name --wallet_name virtual_wallet_name --access_level wallet_access_level
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint group. |
|
Required |
Name of the virtual wallet. |
|
Required |
Level of access for the virtual wallet. Values are as follows:
|
Short Form Example
This example shows endpoint group epg_hr
being granted read, modify, and manage privileges on wallet hr_wallet
.
java -jar okvrestservices.jar -c conf_file -r modify_wallet_access_epg -g epg_hr -w hr_wallet -l rm_mw
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_wallet_access_epg --epg_name epg_hr --wallet_name hr_wallet --access_level rm_mw
Parent topic: Virtual Wallet Commands
The drop_wallet_access_epg
command removes an endpoint group's access to virtual wallet.
Syntax
Short form:
drop_wallet_access_epg -g endpoint_group_name -w virtual_wallet_name
Long form:
drop_wallet_access_epg --epg_name endpoint_group_name --wallet_name virtual_wallet_name
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the endpoint group. |
|
Required |
Name of the virtual wallet. |
Short Form Example
This example shows endpoint group epg_hr
being granted read, modify, and manage access to wallet hr_wallet
.
java -jar okvrestservices.jar -c conf_file -r modify_wallet_access_epg -g epg_hr -w hr_wallet -l rm_mw
Long Form Example
java -jar okvrestservices.jar --config conf_file --service modify_wallet_access_epg --epg_name epg_hr --wallet_name hr_wallet -l rm_mw
Parent topic: Virtual Wallet Commands
The delete_wallet
command deletes a wallet from Key Vault.
Syntax
Short form:
delete_wallet -f -w virtual_wallet_name
Long form:
delete_wallet --force --wallet_name virtual_wallet_name
Parameters
Parameter | Required? | Description |
---|---|---|
|
Required |
Name of the virtual wallet. |
|
Optional |
Forces the deletion without prompting for confirmation. |
Short Form Example
This example shows wallet hr_wallet
being deleted without confirmation.
java -jar okvrestservices.jar -c conf_file -r delete_wallet -f -w hr_wallet
Long Form Example
java -jar okvrestservices.jar --config conf_file --service delete_wallet --force --wallet_name hr_wallet
Parent topic: Virtual Wallet Commands
The RESTful Service utility has robust error reporting, which you can use to debug in order to run RESTful Service commands quickly and successfully. The status of command execution, passed and failed, is reported promptly on the command line and written to the log file.
Parent topic: RESTful Services Command Reference
The status of command execution, passed and failed, is reported promptly on the command line and written to the log file. The specific error will be reported, with corrective actions where appropriate.
The first thing to do when a command fails is to look into the log file. If you have not created a custom log file in a location of your choice, then you can look at the default log file, okvrestservices.log
in the current directory, where command results will be written.
To see all the messages from the Oracle Key Vault server during command execution, you can set the appropriate logging level, log file name, and the log file location in the configuration file.
The RESTful service utility reports errors such as the failure to locate a file or an environment variable like JAVA_HOME
, incorrect command syntax, and incorrect passwords.
Parent topic: Error Reporting
Error reporting captures both faulty actions, such as incorrect passwords, and successful command executions.
Example 10-6 Error: Running a Service Command without the -r Option
java -jar okvrestservices.jar -c rest.ini modify_endpoint_desc -e ORDERS -b ORDERS_HR Script or service option is required.
Example 10-7 Error: Incorrect Password
java -jar okvrestservices.jar -c rest.ini -r modify_endpoint_desc -e ORDERS -b ORDERS_HR Password: Invalid username or password. Try again after 5 seconds
Example 10-8 Successful Service Command Execution
java -jar okvrestservices.jar -c rest.ini -r modify_endpoint_desc -e ORDERS -b ORDERS_HR Password: [Line 0 OK] [MODIFY ENDPOINT DESC] [ORDERS:ORDERS_HR]
Example 10-9 Log File Entry
In addition to the helpful error and usage messages, an entry for the action is logged in the log file with the date.
Mar 02, 2019 7:23:55 PM com.oracle.okv.cloud.client.OKVAutomation checkpoint INFO: [Line 0 OK] [MODIFY ENDPOINT DESC] [ORDERS:ORDERS_HR]
Parent topic: Error Reporting
When you run multiple service commands from a script you will see the result on the command line as well as in the log file.
The following output shows the successful results of commands executed from a script.
Example 10-10 Results of Script Execution
java -jar okvrestservices.jar --config rest.ini --script initial_setup.api Password: [Line 1 OK] [CREATE ENDPOINT] [APP_SERVER_1:ORACLE_NON_DB:LINUX64] [Line 2 OK] [CREATE ENDPOINT] [APP_SERVER_2:ORACLE_NON_DB:LINUX64] [Line 11 OK] [CREATE WALLET] [ApplicationWallet] [Line 12 OK] [CREATE WALLET] [FinanceWallet] [Line 15 OK] [CREATE ENDPOINT GROUP] [APP_SERVER] [Line 16 OK] [CREATE ENDPOINT GROUP] [FINANCE_RAC] [Line 20 OK] [ADD EPG MEMBER] [APP_SERVER:APP_SERVER_2] [Line 22 OK] [ADD EPG MEMBER] [FINANCE_RAC:FINANCE_RAC_NODE_1] [Line 29 OK] [ADD WALLET ACCESS EPG] [APP_SERVER:ApplicationWallet:RM] [Line 30 OK] [ADD WALLET ACCESS EPG] [FINANCE_RAC:FinanceWallet:RO] [Line 31 OK] [ADD WALLET ACCESS EP] [HR_DATABASE_PRIMARY:HRWallet:RM_MW]
Parent topic: Error Reporting
For a list of valid options you can use the -h or --help option with the RESTful Services utility okvrestservices.jar.
Using the --help Option
-bash-4.1$ java -jar okvrestservices.jar -help usage: java -jar okvrestservices.jar --config <arg> [--service <arg> |--script <arg> -A,--add <arg> User to add to wallet -c,--config <arg> System configuration file for OKV REST Services Utility -D,--delete <arg> User to delete from wallet -f,--force Confirm to delete -h,--help Display all available options -L,--listuser List all user from wallet -M,--modify <arg> User to modify from wallet -p,--pwd <arg> OKV user password -t,--twallet <arg> Wallet location -u,--usr <arg> OKV username -x,--script <arg> Script file -r,--service <arg> Service name -z,--list Display all service commands
Parent topic: Error Reporting
To see the list of RESTful service commands type -H or --list at the command line.
Parent topic: Error Reporting