Cloud Documentation
Advanced Search


Using Oracle Java Cloud Service - SaaS Extension
Close Window

Table of Contents

Show All | Collapse

Using the Command-Line Interface to Manage Oracle Java Cloud Service - SaaS Extension

Video icon Tutorial

By installing the Oracle Java Cloud Service - SaaS Extension SDK (software development kit), you have access to a command-line interface (CLI). To learn how to download the Oracle Java Cloud Service - SaaS Extension SDK, see Downloading the Oracle Java Cloud Service - SaaS Extension SDK.

The management commands exposed through the CLI allow you to perform various application management, file management, and service instance management tasks. Each command in the CLI initiates an asynchronously executed job within the Oracle Cloud for a specific Oracle Java Cloud Service - SaaS Extension instance.

You can use the CLI to manage a Oracle Java Cloud Service - SaaS Extension instance as follows:

Topics:

To learn more about the commands available in the CLI, navigate to the $SDK_HOME/doc/index.html file (where SDK_HOME is the directory containing your Oracle Java Cloud Service - SaaS Extension installation). You can also access all of the SDK documentation via the "Welcome App". Also see Using the Command-Line Interface to Monitor Oracle Java Cloud Service - SaaS Extension.

Managing Credentials

The Oracle Java Cloud Service - SaaS Extension CLI enables you to manage the credential store for a Oracle Java Cloud Service - SaaS Extension instance. Credential store entries are needed to set on outbound web services using username token policy or HTTP basic auth policy.

Note:

Changing credentials for a domain requires a service restart for the changes to take effect.

This table describes the commands for managing credentials.

Command Description Mandatory Arguments

list-credentials

Lists all the credentials.

user, password, identitydomain, serviceinstance

describe-credential

Describes a credential identified by a credential map and a key.

user, password, identitydomain, serviceinstance, key

set-credential

Adds or updates a credential. The map is created if that is not available.

user, password, identitydomain, serviceinstance, key, keyuser, keypassword

delete-credential

Deletes an existing credential.

user, password, identitydomain, serviceinstance, key


Allowing Users Access to User Map in the Credential Store

Users assigned the role UserMapAccessRole can create, read, and update credentials stored in the Oracle Java Cloud Service - SaaS Extension credential map in the credential store. To allow users to access these maps, use the following procedure:

  1. Ensure the following API is in the application from which you want to fetch the credential:

    CredentialStore credentialStore =
       credentialStore = 
    oracle.security.jps.service.JpsServiceLocator.getServiceLocator().lookup(oracle.security.jps.service.credstore.CredentialStore.class);
    .
        String map = "user.custom.map";
        String mykey = "mykey";
    .
     Credential cred =  credentialStore.getCredential(map, mykey);
         out.println("Password got:" + cred);
     if (cred != null) {
         systemout.println("Password got:" + new String(((PasswordCredential)cred).getPassword()));
    }
    
  2. Add the credential to the map by using the set-credential command:

    $ java -jar lib/javacloud.jar -a https://javaservices.us2.cloud.oracle.com -id jcscdc  -u jcsteam   -si javas2  -set-credential -map user.custom.map -key mykey -keyuser user-name 
    

    The system response will be:

    [The password for the user specified with the argument user.]
    [password] ****
    [The password that is bound with the key.]
    [keypassword] ****
    [INFO]    - Update - OK
      
    
  3. Create the new role in the ID Management Console:

    1. Go to the MyServices application supplied with your Oracle Java Cloud Service - SaaS Extension account and click Security.

    2. Click the Customer Roles tab to open the page and then click Add.

      The Add Custom Role dialog appears.

    3. In the Add Custom Role dialog, enter the Role Name, UserMapAccessRole, along with a Display Name and, optionally, a short Description of the role. Then click Add.

      The new role, UserMapAccessRole appears on the Custom Role list.

  4. Assign the new role to a user or users:

    1. Click the Users tab to go back to the Users list.

    2. Click Menu Icon associated with the user to whom you want to assign the custom role.

    3. From the drop-down menu, select Manage Roles.

      The Manage Roles dialog for that user appears.

    4. From Available Roles, move the custom role created in step 3 (it will be listed by its Display Name) to the Assigned Roles list and click Save.

  5. Have the user who has been assigned with the new role log on to the custom application that executes the code specified at step 1.

The user assigned the new role can now create, read, or delete credentials in the credential map.

Managing Web Services Security Truststore

The CLI enables you to manage Oracle Web Services Management security policies (WSS) for an OWSM truststore used for web services with OWSM policies.

Notes:

  • Adding a WSS certificate to the wss trust-store requires a service restart for the changes to take effect.

  • Oracle does not support the use of special characters in the alias name of OWSM truststore certificates.

This table describes the commands for managing OWSM security policies.

Command Description Mandatory Arguments

reset-wss-certificate-store

Restores the OWSM truststore to the default as a newly-provisioned instance.

user, password, identitydomain, serviceinstance

list-wss-certificates

Lists all the trusted certificates from the OWSM truststore.

user, password, identitydomain, serviceinstance

add-wss-certificates

Imports a new certificate into the OWSM truststore.

user, password, identitydomain, serviceinstance, path

delete-wss-certificates

Deletes an existing certificate from the outbound OWSM truststore.

user, password, identitydomain, serviceinstance, alias

download-wss-certificates

Downloads a certificate from the OWSM truststore.

user, password, identitydomain, serviceinstance


Managing SSL Truststores

The CLI enables you to manage WebLogic Server security policies (SSL) for a WebLogic truststore used for web services with WebLogic policies.

Notes:

.

  • Adding an SSL certificate to the ssl trust-store requires a service restart for the changes to take effect.

  • Oracle does not support the use of special characters in the alias name of WebLogic SSL truststore certificates.

This table describes the commands for managing SSL truststores.

Command Description Mandatory Arguments

reset-ssl-certificate-store

Restores the SSL truststore to the default as a newly-provisioned instance.

user, password, identitydomain, serviceinstance

list-ssl-certificates

Lists all the trusted certificates from the SSL truststore.

user, password, identitydomain, serviceinstance

add-ssl-certificates

Imports a new certificate into the outbound SSL truststore.

user, password, identitydomain, serviceinstance, path

delete-ssl-certificates

Deletes an existing certificate from the outbound SSL truststore.

user, password, identitydomain, serviceinstance, alias

download-ssl-certificates

Downloads a certificate from the outbound SSL truststore.

user, password, identitydomain, serviceinstance


Managing System Properties

From the CLI, you can list, add, or delete system properties by using system property commands in the server startup argument. You must then restart the service instance for the properties to be implemented.

Command Description Mandatory Arguments

list-system-properties

Lists all persisted system properties.

user, password, identitydomain, serviceinstance

set-system-property

Adds or updates an existing system property. Requires service instance restart to be effective.

user, password, identitydomain, serviceinstance, name, value

delete-system-property

Deletes a persisted system property.Requires service instance restart to be effective.

user, password, identitydomain, serviceinstance, name


Managing Logging Levels

From the CLI, you can list loggers and setting their log level. This is particularly useful when you want to control the debugging resolution of the log statements.

Command Description Mandatory Arguments

list-loggers

Lists the name and log level of all the Loggers or of a given Logger and, optionally, its children.

Note that, while this command lists all the loggers and their logging levels, it hides any internal loggers.

No mandatory arguments

set-log-level

Sets the Log level of the Logger to the given level.

The JDK's available log levels are:

  • FINEST

  • FINER

  • FINE

  • INFO

  • WARNING

  • SEVERE

Oracle Java Cloud Service - SaaS Extension also supports Weblogic's logging convention, so following are also accepted log levels.

  • TRACE

  • NOTIFICATION

  • WARNING

  • ERROR

logger, level


Accessing the Local File System

The Oracle Java Cloud Service - SaaS Extension SDK contains two tools that enable you to manage the files in the /customer/scratch/ directory of your Oracle Java Cloud Service - SaaS Extension instance.

Using the File Browser

The Oracle Java Cloud Service - SaaS Extension SDK includes a Maven plug-in project that can be used to manage the files in your /customer/scratch/ directory. The sample File Browser application also shows how java.io.* APIs can be used to read and write files.

To build and launch the File Browser sample:

  1. Navigate to the $SDK_HOME/samples/maven/filebrowser directory (where SDK_HOME is the directory containing your Oracle Java Cloud Service - SaaS Extension installation).

  2. Run the following command:

    mvn clean package
    
  3. Once the sample is built, enter the following URL in your browser:

    https://<servicename-identitydomain>.java.cloud.oracle.com/filebrowser/
    

    This opens the File Browser's "welcome" window:

    Description of filebrowser-url.jpg follows
    Description of the illustration filebrowser-url.jpg

  4. Click the Local File System Access Test link.

    This opens the Filer Browser's current directory page:

    Description of filebrowser-dirs.jpg follows
    Description of the illustration filebrowser-dirs.jpg

  5. You can use this page to browse the /customer/scratch directory. You can use the options on this page to upload and download files from that volume, navigate to the parent directory, or create a new directory.

Using the File System Access Shell

You can use the CLI to open a File System Access Shell to manage the files in your Oracle Java Cloud Service - SaaS Extension instance. This shell accepts basic file management commands, such as ls, cp, mv, put, and get, to manage the files in your /customer/scratch/ directory.

For detailed information about all the available File Shell commands and their usage, navigate to the $SDK_HOME/doc/javacloud-fs-usage.html file (where SDK_HOME is the directory containing your Oracle Java Cloud Service - SaaS Extension installation). You can also access all the SDK documentation via the "Welcome App".

Here is an example of using the CLI to open a file shell session:

$ java -jar $SDK_HOME/lib/javacloud.jar -a http://server:port -u username@oracle.com  -id usoracletrial08411 -si javatrial5334 -fs
Java service file-system access shell.
The root directory "/" points "/customer/scratch/"
/>

Here is an example of using the File Shell to list all files in the /customer/scratch directory:

/>-fs -grid
#=======================================================================================#
|                               Listing 5 file(s) under /                               |
#=#============#===#========================#===========================================#
|#|    Name    |Dir|       File Type        |         Last Modified Description         |
|=|============|===|========================|===========================================|
|1|cloudappc   |d  |                        |                                           |
|-+------------+---+------------------------+-------------------------------------------|
|2|a.txt       |   |text/plain              |55 days, 4 hours, 36 minutes and 13 seconds|
|-+------------+---+------------------------+-------------------------------------------|
|3|myzip       |d  |                        |                                           |
|-+------------+---+------------------------+-------------------------------------------|
|4|FirstPdf.pdf|   |application/octet-stream|2 days, 4 hours, 21 minutes and 19 seconds |
|-+------------+---+------------------------+-------------------------------------------|
|5|metrics     |d  |                        |                                           |
+-+------------+---+------------------------+-------------------------------------------+

Using the Application and Domain Configuration Shell

The "Config Shell" enables you to perform general web service and WebLogic domain configuration tasks. The CLI commands can perform the following tasks against the WebLogic domain of your Oracle Java Cloud Service - SaaS Extension instance:

  • Lists all JRF web services and web service clients

  • Manages OWSM policies on web service endpoints and web service client ports

  • Sets web services configuration and policy overrides

  • Sets web services client stub properties

  • Sets SAML DN configuration to the WebLogic domain

  • Lists SAML DN configuration

In multi-node environments, a single command can translate into multiple commands (one for each managed server) and URL. For example, if you run the attach-webservice-policy command on the S3 node in a four-node environment, you do not need to repeat this action for nodes S1, S2, or S4.

For information about all the available Config Shell commands and their usage, navigate to the $SDK_HOME/doc/javacloud-app-config.html file (where SDK_HOME is the directory containing your Oracle Java Cloud Service - SaaS Extension installation). You can also access all the SDK documentation via the "Welcome App".

Using the Basic Config Shell Commands

This section provides some examples for using certain config-shell commands.

Starting the Config Shell

Here is an example of entering the Config Shell.

$ java -jar $SDK_HOME/lib/javacloud.jar -a http://server:port -u username@oracle.com  -id usoracletrial08411 -si javatrial5334 -config-shell
[INFO] - Java service config shell.
            Initializing ...
Config-shell:>

Using the set Command and the command Argument

The config-shell takes a -command argument that can contain a list of commands that will be automatically executed upon entering the shell. The list of commands can be separated with a semicolon. If the shell needs to exit at the end of running all the listed commands, then the exit command should also be specified in the command list.

The config-shell also supports a special set command that allows you to set frequently used arguments across commands. Once an argument is set, the commands requiring that argument can take the set value as the default value. This is similar to javacloud.properties for the configuration shell.

In the following example, the set command can be used to set the default arguments (for example, application and module), and then perform the commands without the need for passing those arguments in every command within the config-shell.

$ java -jar $SDK_HOME/lib/javacloud.jar -a http://server:port -u username@oracle.com  -id usoracletrial08411 -si javatrial5334 -config-shell -command "set application=myapp;;set module=mymodule"

Now the config-shell.command can be defined in the javacloud.properties file.

Note:

Arguments, such as module, that are supported by the config-shell command set-webservice-client-property, cannot be directly specified in the javacloud.properties file. It can be only specified as config-shell.command=set module=dctest in the properties file.

Here is an example of using the set command to specify the arguments only once in the shell:

Config-shell:>set application=Application3_ViewController_webapp1
Added: application
Config-shell:>list-webservice-clients
/<domain>/m0/Application3_ViewController_webapp1 :
      moduleName=dctest, moduleType=wsconn, serviceRefName=AppModuleService

Note that the application name is taken automatically since it was already set in the shell. Just type set in the shell to list all the arguments that you have set:

Config-shell:>set
#===============================================================================================#
|                           Listing 7 argument(s) and their values.                             |
#===============================================================================================#
|                        argument                           |                  value            |
|===========================================================|===================================|
|application                                                |Application3_ViewController_webapp1|
|-----------------------------------------------------------+-----------------------------------|
|gridwidth                                                  |140                                |
|-----------------------------------------------------------+-----------------------------------|
|module                                                     |dctest                             |
|-----------------------------------------------------------+-----------------------------------|
|output                                                     |/Users/velsubra/Desktop/ade/twork/ |
|-----------------------------------------------------------+-----------------------------------|
|port                                                       |AppModuleServiceSoapHttpPort       |
|-----------------------------------------------------------+-----------------------------------|
|serviceref                                                 |AppModuleService                   |
|-----------------------------------------------------------+-----------------------------------|
|[alias, clienttype, configprops, debug, dump, help, issuer,|           --NOT SET--             |
|overrideprops, policyuri, retain, service,stubprops,       |                                   |
|subject, tokentype, trustedDN, verbose]                    |                                   |
+-----------------------------------------------------------+-----------------------------------+

Displaying Help for a Config Shell Command

You can use the -help command to display detailed information for each Config Shell command.

Config-shell:>list-webservice-clients -help
Command:
--------
list-webservice-clients - Lists all the web service clients.
                          E.g) list-webservice-clients -application myapp;list-webservice-clients -application myapp
                          -verbose
                          
                          Command alias:[listwebserviceclients]
 
Mandatory argument(s):
----------------------
application - The name of the application.

                          Shortcut:app

Optional arguments(s):
----------------------
verbose - The flag(true/false) that indicates if the listing should be done in verbose(full-format).
                          
                          Shortcut:v
                          
                          Default Value: false
 
Advanced argument(s):
---------------------
 
Diagnostic/Help argument(s):
----------------------------
help - The flag (true/false) to indicate whether the help text should be printed. The default value
                          is false. When true, only the help is printed and all the other arguments, if specified, are
                          ignored.
                          
                          Shortcut:h
                          
                          Default Value: false
 
debug - The flag (true/false) to indicate whether the debug-level messages should be printed. The
                          debug messages are more detailed than INFO-level messages. The default value is false.
                          
                          Shortcut:d
                          
                          Default Value: false

Displaying Application Details

You can use the Config Shell to list all the OWSM policies, OWSM client policies, web services, and web service clients in your domain.

Listing OWSM Policies

You can list the service polices in your domain. By default, list-all-webservice-policies only lists all service policies but does not include any client policies. The argument -subject tells whether the listing should be done for client or service, as shown in Listing OWSM Client Policies.

Config-shell:>list-all-webservice-policies
List of available OWSM policies
security : oracle/http_basic_auth_over_ssl_service_policy
security : oracle/wss_saml_or_username_token_over_ssl_service_policy
security : oracle/wss_saml_token_bearer_over_ssl_service_policy
security : oracle/wss11_message_protection_service_policy
security : oracle/wss11_saml_token_with_message_protection_service_policy
security : oracle/wss_saml20_token_bearer_over_ssl_service_policy
security : oracle/wss11_username_token_with_message_protection_service_policy
security : oracle/wss_http_token_over_ssl_service_policy
security : oracle/wss_username_token_over_ssl_service_policy
security : oracle/wss11_x509_token_with_message_protection_service_policy
security : oracle/wss_saml_token_over_ssl_service_policy
security : oracle/multi_token_rest_service_policy
security : oracle/http_saml20_token_bearer_over_ssl_service_policy
security : oracle/wss11_saml_or_username_token_with_message_protection_service_policy
security : oracle/wss_saml20_token_over_ssl_service_policy
security : oracle/multi_token_over_ssl_rest_service_policy
Config-shell:>

Listing OWSM Client Policies

You can list the client polices in your domain by adding the -subject client argument to the list-all-webservice-policies command.

Config-shell:>list-all-webservice-policies -subject client
List of available OWSM policies
security : oracle/wss_http_token_client_policy
security : oracle/http_basic_auth_over_ssl_client_policy
security : oracle/http_saml20_token_bearer_over_ssl_client_policy
security : oracle/wss_http_token_over_ssl_client_policy
security : oracle/wss11_saml_token_with_message_protection_client_policy
security : oracle/wss11_x509_token_with_message_protection_client_policy
security : oracle/wss11_username_token_with_message_protection_client_policy
security : oracle/wss_saml20_token_bearer_over_ssl_client_policy
security : oracle/wss_saml_token_bearer_over_ssl_client_policy
security : oracle/wss_username_token_over_ssl_client_policy
security : oracle/wss_saml_token_over_ssl_client_policy
security : oracle/wss11_message_protection_client_policy
security : oracle/http_saml20_token_bearer_client_policy
security : oracle/wss_saml20_token_over_ssl_client_policy
Config-shell:>

Listing Web Services

You can list the web services in your domain.

Config-shell:>list-webservices -app adfbc_bcProfile1 -v
Server:m0
=========
/<domain>/m0/adfbc_bcProfile1 :
moduleName=cloudapps-adfbc-context-root, moduleType=web, serviceName={/adfbc/common/}AppModuleService
      enableTestPage: true
      enableWSDL: true
            AppModuleServiceSoapHttpPort http://server:port/cloudapps-adfbc-context-root/AppModuleService
            enable: true
            enableREST: false
            enableSOAP: true
            maxRequestSize: -1
            loggingLevel: NULL
            wsat.flowOption: NEVER
            wsat.version: DEFAULT
No policies attached; endpoint is not secure.

Listing Web Service Clients

You can list the web service clients in your domain.

Config-shell:>list-webservice-clients -app Application3_ViewController_webapp1 -v
/<domain>/m0/Application3_ViewController_webapp1 :
    moduleName=dctest, moduleType=wsconn, serviceRefName=AppModuleService
       AppModuleServiceSoapHttpPort    serviceWSDLURI=http://server:port/cloudapps-adfbc-context-root/AppModuleService?wsdl
       No policies attached; endpoint is not secure.

Note that in this example there is only a single client. By using the verbose (-v) argument, the output will try to describe the attached policies as well. In this case the client does not have any policies.

Example Use-case: Overriding an Endpoint Address for a Web Service Client

This use case shows how to use the Config Shell commands discussed in this section to override an web service endpoint address for a web service client.

  1. List the web service clients for the details that would be required when setting the endpoint address.

    Config-shell:>list-webservice-clients -app Application3_ViewController_webapp1 -v
    /<domain>/m0/Application3_ViewController_webapp1 :
        moduleName=dctest, moduleType=wsconn, serviceRefName=AppModuleService
           AppModuleServiceSoapHttpPort    serviceWSDLURI=http://server:port/cloudapps-adfbc-context-root/AppModuleService?wsdl
           No policies attached; endpoint is not secure.
    
  2. Set the endpoint address:

    1. Set the various parameters that identify the web service client. (Note that the following parameters map to the highlighted client details in the list-webservice-clients output) in Step 1:

      Config-shell:>set application=Application3_ViewController_webapp1;set module=dctest;set serviceref=AppModuleService;set port=AppModuleServiceSoapHttpPort
      

      Note: Step 2a is optional since these arguments can be directly passed when using set-webservice-client-property to change the endpoint address, as shown in Step 2b. Also, any values that are passed on the command-line will override values that are set using the set command.

    2. Change the endpoint address using the set-webservice-client-property command:

      Config-shell:>set-webservice-client-property -stubprops javax.xml.ws.service.endpoint.address=http://server:port/cloudapps-adfbc-context-root/AppModuleService
      Please restart application to uptake any policy or configuration change.
      
  3. Restart the application:

    Config-shell:>restart-application
    [INFO] - Stopping the application : Application3_ViewController_webapp1
    [INFO] - Job:1752 Operation:Stop Application
    [INFO] - Starting the application : Application3_ViewController_webapp1
    [INFO] - Job:1753 Operation:Start Application
    Config-shell:>