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

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.

Topics

Note:

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

Using the CLI

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

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.

Streamlining Command Entry by Using javacloud.properties

Setting command-line arguments in the javacloud.properties file streamlines command entry because, once the property file is defined, the arguments set in it do not need to be specified at the command line. Additionally, the property file path itself is implicit and does not need to be passed.

Where to Store javacloud.properties

You can store javacloud.properties in either

  • Your home directory, which is returned by the System.getProperty( "user.home" ) call in Java. For example:

    • Windows:C:\Documents and Settings\<username>

    • Linux: /home/<username>

    • Mac: /Users/<username>

  • The current working directory; that is the same directory where you execute java -jar javacloud.jar.

The version of the property file located in the current working directory takes the precedence over the one available in your home directory.

javacloud.properties Keys and Values

The keys are simply the argument names. These rules apply:

  • You cannot specify argument shortcuts here.

  • Arguments of multiple commands can be specified here.

  • Unrecognized keys will be ignored.

The value specified is the value of the argument.

The keys can be specified in two forms:

  • Simple form—The name of an argument is specified as it is; for example, identitydomain=mydomain. This is applicable to all the commands that takes the argument identitydomain.

  • Full form—The argument name is specified along with the command name; for example, list-jobs.sorton=STATUS, where list-jobs is a valid command name and sorton is a valid argument supported by the command. This is applicable only to the command specified. The full form takes precedence over the simple form.

Specifying Passwords

You cannot specify password type arguments with javacloud.properties because the value for a password type argument is never read from this file.

Resolving Argument Values

The value of an argument is resolved in the following order:

  1. Argument value, if specified in the command line.

  2. Argument value, if specified in the property file.

  3. Default value of the argument, if available. Use ./javacloud -<command> -help to list the default values.

If the value is not resolved for a mandatory argument, the command line will result in validation error.

Sample javacloud.properties file

#Note: Values specified here can be overridden on the command line.
user=your-user-name
identitydomain=your-id-domain
serviceinstance=your-svc
#Enable grid if you prefer grid display when applicable
grid=true
gridwidth=120
list-jobs.sorton=STARTTIME
list-applications.sorton=NAME
#Specify http proxy if you are behind a proxy
#httpproxy=your-proxy-host:port
#Enable classpath to be used when local is true. Use ; as the path separator on Windows platforms
#classpath=path-to-weblogic.jar:path-to-localextension.jar

Enabling Email Notifications in JCS-SaaS Extension

JCS-SaaS Extension's email notification feature allows you to use the JavaMail APIs to configure your application to send emails to specified users upon certain events.

How It Works

This feature exposes the JavaMail APIs to your applications, where you can use them to set all the critical email information (for example, the triggering event, the content of the email, and so on) and then call methods required to send the email. Authentication information supplied at the application level is tunneled to the Notification Service, which uses it for authenticating the user and also for quota management. Quota limits, based on your service type, restrict the number of emails you can send.

Authentication

Due to the internal services involved in triggering emails, authentication is required and is managed through the Notification service. When email notifications are triggered, the user responsible for them is authenticated by the Notification Service, which validates through the IDM that the user is assigned the Java_Notification_User role. When the role is confirmed, emails can be sent. If the user attempts to use credentials that aren’t assigned the Java_Notification_User role, authentication will fail and e-mails will not be triggered. While you can use an existing user to send emails, Oracle recommends that you create a new user designated solely to send out notifications. This is advantageous because, if the credentials are compromised, the attacker can only send out mails but not destroy the service, which could happen if you use a privileged user to send out mails.

Process for Enabling Email Notifications

To enable applications to trigger notification emails, complete the four tasks described in the following topics:

Email Quota

Email quota limits the number of emails you can send and is determined by your service type. Before proceeding, determine which of the following service types you have:


Service Type Daily Message Quota Usage Warning
JAVA-BASIC-TRIAL 200 At 90%
JAVA-BASIC-PRODUCTION 1000 At 90%
JAVA-STANDARD-PRODUCTION 2000 At 90%
JAVA-ENTERPRISE-PRODUCTION 6000 At 90%

When you exhaust your email quota, you can no longer send emails. If you want to send more, increase your quota by upgrading your service.

Prerequisites for Enabling Email Notifications

Before you can enable email notifications in your application, you need to meet certain prerequisites.

  1. Enable the Java Mail email punch-out by using the set-config command against your instance to set the java.mail.enabler to true:
    /javacloud.jar -id myIDDomain62337 -si javatrial1870 -u jesse.essex@mycompany.com -p Katrina@123 -set-config -name java.mail.enabler -value true
    
  2. If the Java Security Manager is enabled, disable it by using the set-config command to set the jvm.standard.security.manager.enabled value to false:
    /javacloud.jar -id myIDDomain62337 -si javatrial1870 -u jesse.essex@mycompany.com -p Katrina@123 -set-config -name jvm.standard.security.manager.enabled -value false
    

Prerequisite for Nuviaq

Also, before you attempt to set up email notifications for the first time, contact your Operations personnel and have them set the Nuviaq property oracle.cloud.java.service.notification.base.url to the Notification Service’s base URL. This places the Notification Service’s base URL in the global.properties file, at /customer/config, for all new service instances. Ensure the Operations personnel uses the form http://<hostName>:<port>: ; for example:
./nctl setProperty -name oracle.cloud.java.service.notification.base.url -value http://abc03trp.us.MyCompany.com:8001
Thi s is a one-time operation.

Task 1: Create the User and Assign the Java_Notification_User Role

To enable email notifications you’ll need to create a new user and the custom the role Java_Notification_User and then assign that role to the new user.

To create a user and customn role and then assign the role, do the following:

Note:

If you want to use an existing user (not recommended), start with step 4.
  1. Login to My Services and click Users to open the Users tab.
  2. On the Users tab, click Add.
    The Add User dialog appears.
  3. Enter the specific identity data for the user and click Add.
    The Add User dialog closes and the new user appears on the Users tab.
  4. Click Custom Roles to open the Custom Roles tab and click Add.
    The Add Custom Role dialog appears.
  5. In Role Name, enter Java_Notification_User (optionally, give the role a display name—for example Java Notification User—and a short description). Then click Add.
    The Add Custom Role dialog closes.
  6. Click Users to return to the Users tab and then click the menu icon for the new user and select Manage Roles.
    The Manage Roles dialog for the specific user appears.
  7. In the Roles section, under Available Roles, select Java_Notification_User and click the right arrow to move it to the Assigned Roles list. Then click Save.

Task 2: Set Credentials in the Application

Next, you need to set the user credentials for the email user in the credential store and then configure the triggering application to retrieve them from the store.

To set the user credentials in the application:
  1. Use the set-credential CLI command to store the credentials in your credential store:
    /javacloud.jar set-credential -user userName -password userPassword -id identityDomain -si serviceInstance -keyuser keyUsername -keypassword keyPassword -key csfKey
    

    For example:

    /javacloud.jar set-credential -user system -password Welcome1 -id myDomain123 -si myInstance -keyuser foo -keypassword foobar -key myCSFKey
    
  2. Configure the OPSS APIs in the triggering application to use keys associated with the credentials to get these credentials from the credential store. Use the following code snippet as a model:
    import oracle.security.jps.service.credstore.Credential;
    import oracle.security.jps.service.credstore.CredentialFactory;
    import oracle.security.jps.service.credstore.CredentialStore;
    import oracle.security.jps.service.credstore.PasswordCredential;
     
     
    public
    try {
     
                    CredentialStore credentialStore =
                        credentialStore = oracle.security.jps.service.JpsServiceLocator.getServiceLocator().lookup(oracle.security.jps.service.credstore.CredentialStore.class);
     
                    try {
                        out.println("Listing all maps");
                        Set<String> maps = credentialStore.getMapNames();
                        out.println(maps);
                    } catch (Exception e) {
                        out.println("<font color='red'>Listing maps  failed.</font>\n");
                e.printStackTrace(out);
     
                    }
                    String map = "user.custom.map";
                    String mykey = "mykey";
                    try {
                        out.println("Creating map " +map);
                        if (credentialStore.containsMap(map)) {
                            credentialStore.deleteCredentialMap(map);
                        }
                        credentialStore.setCredential(map, mykey, CredentialFactory.newPasswordCredential("user", "pwd".toCharArray()));
                        out.println("Password set");
                        out.println("Listing all maps ....");
                        Set<String> maps = credentialStore.getMapNames();
                        out.println(maps);
                    } catch (Exception e) {
                        out.println("<font color='red'>password set -> failed.</font>\n");
                        e.printStackTrace(out);
                    }
                    try {
                        out.println("Accessing credential");
                        Credential cred =  credentialStore.getCredential(map, mykey);
                        out.println("Password got:" + cred);
                        if (cred != null) {
                            out.println("Password got:" + new String(((PasswordCredential)cred).getPassword()));
                        }
                        out.println("Listing all maps ....");
                        Set<String> maps = credentialStore.getMapNames();
                        out.println(maps);
                    } catch (Exception e) {
                        out.println("<font color='red'>password get ->  failed.</font>\n");
                        e.printStackTrace(out);
                    }
                } catch (Exception eg) {
                    out.println("<font color='red'>Test failed.</font>\n");
                    eg.printStackTrace(out);
                }
                out.println("</pre></body></html>");
                out.close();
    }
    

Task 3: Add Notification Triggering Code to the Application

After completing Tasks 1 and 2, you need to add code to the application to trigger the emails.

The following code snippet shows the application code for a likely triggering scenario. The userName and password are the values that you set in Task 2: Set Credentials in the Application that the application retrieves from the credential store.

Authenticator auth = new Authenticator() {
 
            public PasswordAuthentication getPasswordAuthentication() {
 
                return new PasswordAuthentication(userName, password);
 
            }
};
 
 
Session session = Session.getInstance(props);
    session.setDebug(debug);
    try {
            InternetAddress[] address = {new InternetAddress("shyamant.hegde@oracle.com")};
        MimeMessage msg = new MimeMessage(session);
        msg.setFrom(new InternetAddress("javamail@oracle.com"));
        msg.setRecipients(Message.RecipientType.TO, address);
        msg.setSubject("JavaMail APIs Test");
        msg.setSentDate(new Date());
        msg.setText(msgText);
 
            Transport transport = session.getTransport("smtp");
            transport.connect(userName, password);
//          Using authentication in an instance of Transport class instead of session
            transport.sendMessage(msg, address );

Task 4: Update weblogic.xml to Reference the Jersey JARs

The application compiler is dependent on the Jersey JARs for invoking the Notification Service REST APIs, therefore the weblogic.xml bundled with every email-triggering application must contain references to any Jersey JARs in the service instance.

To update weblogic.xml, add the following code snippet to the file

<library-ref>
    <library-name>jax-rs</library-name>
    <specification-version>1.1</specification-version>
    <implementation-version>1.9</implementation-version>
    <exact-match>false</exact-match>
  </library-ref>

Managing Shared Libraries

The CLI enables you to deploy and manage any shared Java EE library and optional package supported Oracle WebLogic Server.

The libraries you can manage include both out of the box libraries and optional packages provided by Oracle Cloud, as well as any user -defined custom shared libraries or optional packages that are packaged using the standard process as supported by WebLogic Server.

This table describes the commands for managing the deployment of shared libraries and optional packages.

Name Description Mandatory Arguments

list-libraries

Lists all the shared libraries that are installed and available in the service instance.

user, password, identitydomain, serviceinstance

describe-library

Describes a shared library identified by its name, spec version and impl version. The description includes the status, deploy type, type and the name of the applications that references this library.

user, password, identitydomain, serviceinstance, library, specversion, implversion

install-library

Installs a custom shared library that is available in the local disk.

user, password, identitydomain, serviceinstance, library, specversion, implversion

update-library

Updates an installed custom shared library.

user, password, identitydomain, serviceinstance, library, path specversion, implversion

delete-library

Permanently deletes an installed custom shared library.

user, password, identitydomain, serviceinstance, library, specversion, implversion

Managing Configurations

You can use the list-config and set-config CLI commands to manage your JCS-SaaS Extension configuration.

Note:

You will need to download the latest JCS-SaaS Extension SDK to use this feature. See Downloading the Oracle Java Cloud Service - SaaS Extension SDK.

JCS-SaaS Extension hides its internal implementation by simplifying the configuration into a simple key and a value, allowing you to view configurations and modify them by using the CLI to specify this name/value pair. Be aware that you can only modify a limited set of configurations; you can see the modifiable configurations by using the list-config command.

To manage JCS-SaaS Extension configurations, use these commands:

Command Description Mandatory Arguments
list-config Creates a list of all available configurations. To see a full list of configurations, you must include the -showvalue (-s) command. user, password, identitydomain, serviceinstance
set-config Allows you to set any of the available configurations by specifying the configuration name—obtained from the list-config command—and appropriate configuration value. user, password, identitydomain, serviceinstance, name, value

To manage configurations:

Note:

To simplify command entry, you can store values for all parameters except -password (-p) in the javacloud.properties file. See Using javacloud.properties.
  1. Use list-config to display the properties you can configure:

    ./javacloud.jar  -list-config -identityDomain myIdentityDomain -serviceInstance myServiceInstance -userName myUserName -password myUserPassword -verbose -showvalue 
    

    The system responds with a list similar to this:

    #==================================================================================================#
    |                                    Listing 6 Simple Configs                                      |
    |                 [Identity Domain=developersystem3775777, Service Instance=java3]                 |
    #=#===============#==========#======#=====#=====#======================================#=====#=====#
    | |               |          |Value |Value|Resta|                                      |     |     |
    |#|     Name      |Value Type|Readab|     | rt  |             Description              |Value|Label|
    | |               |          |  le  |Writa|Requi|                                      |     |     |
    | |               |          |      | ble | red |                                      |     |     |
    |=|===============|==========|======|=====|=====|======================================|=====|=====|
    | |jta.           |          |      |     |     |                                      |     |secon|
    |1|transaction.   |INTEGER   |  Y   |  Y  |     |JTA transaction timeout.              |30   |ds   |
    | |timeout        |          |      |     |     |                                      |     |     |
    |-+---------------+----------+------+-----+-----+--------------------------------------+-----+-----|
    | |servers.status.|          |      |     |     |Managed Server Status(es). If any of  |RUNNI|     |
    |2|running        |STRING    |  Y   |  Y  |     |the servers is in the admin state,    |NG   |     |
    | |               |          |      |     |     |Set the value to be true to resume it.|     |     |
    |-+---------------+----------+------+-----+-----+--------------------------------------+-----+-----|
    | |jvm.arg.max.   |          |      |     |     |JVM's Max Perm Size argument value.   |     |     |
    |3|perm.size      |INTEGER   |  Y   |  Y  |  Y  |Negative value indicates that the     |-1   |MB   |
    | |               |          |      |     |     |value is not set. ie) the default.    |     |     |
    |-+---------------+----------+------+-----+-----+--------------------------------------+-----+-----|
    | |jvm.arg.stack. |          |      |     |     |JVM's Stack Size argument value.      |     |     |
    |4|size           |INTEGER   |  Y   |  Y  |  Y  |Negative value indicates that the     |-1   |KB   |
    | |               |          |      |     |     |value is not set. ie) the default.    |     |     |
    |-+---------------+----------+------+-----+-----+--------------------------------------+-----+-----|
    | |jvm.standard.  |          |      |     |     |Standard Java Security manager        |     |     |
    |5|security.      |BOOLEAN   |  Y   |  Y  |  Y  |enabled?                              |false|     |
    | |manager.enabled|          |      |     |     |                                      |     |     |
    +-+---------------+----------+------+-----+-----+--------------------------------------+-----+——---+
    | |java.mail.     |          |      |     |     |Enable Java Mail based e-mail punch   |     |     |
    |6|enabler        |BOOLEAN   |  Y   |  Y  |  Y  |out from applications.When the value  |     |     |
    | |               |          |      |     |     |is set to true the applications       |false|     |
    | |               |          |      |     |     |deployed on the given Service         |     |     |
    | |               |          |      |     |     |Instance will be able to send out     |     |     |
    | |               |          |      |     |     |emails using java mail apis.          |     |     |
    +—————————————————————————————————————————————————————————————————————————————————————————————————-+
    | |credential.    |          |      |     |     |Credential Store public map enabled?  |     |     |
    |7|public.        |BOOLEAN   |  Y   |  Y  |  Y  |                                      |true |     |
    | |map.enabled    |          |      |     |     |Note: when value is set to true, the  |     |     |
    | |               |          |      |     |     |credential map user.public.map will be|     |     |
    | |               |          |      |     |     |manageable to unauthenticated users   |     |     |     
    +-+---------------+----------+------+-----+-----+--------------------------------------+-----+——---+
    

    This table shows the name of the configurations along with other information critical to making configuration decisions. The Value column shows the information you can change with the set-config command. Those you can change are denoted by a Y in the Value Writable column. Note that some values can’t be changed and others will require system restart for the change to occur.

  2. Use set-config to update the Value of a selected configuration; for example, if you wanted to change the JTA transaction timeout to 34 seconds, you would use this command:

    ./javacloud.jar  -set-config -name jta.transaction.timeout -identityDomain myIdentityDomain -serviceInstance myServiceInstance -userName myUserName -password myUserPassword -value 34
    

    Note:

    The value you set should be a legal value; for example, setting a very low value for jvm.arg.stack.size might prevent server startup as instance restart would fail. If that were to happen, you would have to set the appropriate value and again restart the instance.

Managing Credentials

The Oracle Java Cloud Service - SaaS Extension CLI enables you to manage the credential store for an Oracle Java Cloud Service - SaaS Extension instance.

You need to set credential store entries on outbound web services using username token policy or HTTP basic auth policy.

Note:

Whenever you change credentials for a domain you need to restart the service for the changes to take effect.

User credentials are stored in any of three maps:
  • user.custom.map; for storing credentials to which user applications have access. All the authenticated users assigned the role UserMapAccessRole will be able to read credentials from this map. See Allowing Users Access to User Map in the Credential Store.

  • oracle.wsm.security; for storing credentials that web service clients can use.

  • user.public.map; for storing credentials to which user applications can have anonymous access. Users will be able to read credentials from this map without authentication.

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

Enabling Access to Credentials in user.public.map

For newly provisioned instances, you can access credentials stored in user.public.map even if you haven’t been authenticated so long as the property credential.public.map.enabled is true.

By default, credential.public.map.enabled is set to true, thus enabling you to access credentials in user.public.map without being authentiacted. Occasionally, this property will not be true. In that case, you need to enable it by using the set-config command; for example:

Note:

This procedure assumes you have downloaded the latest version of the JCS-SaaS Extension SDK. See Downloading the Oracle Java Cloud Service - SaaS Extension SDK.
  1. First, use list-config to determine the property status:

    ./javacloud.jar  -list-config -identityDomain myIdentityDomain -serviceInstance myServiceInstance -userName myUserName -password myUserPassword -verbose -showvalue 
    
  2. On the configuration listing, check the value for credential.public.map.enabled. If it is true, the property is enabled.

    +—————————————————————————————————————————————————————————————————————————————————————————————————-+
    | |credential.    |          |      |     |     |Credential Store public map enabled?  |     |     |
    |7|public.        |BOOLEAN   |  Y   |  Y  |  Y  |                                      |true |     |
    | |map.enabled    |          |      |     |     |Note: when value is set to true, the  |     |     |
    | |               |          |      |     |     |credential map user.public.map will be|     |     |
    | |               |          |      |     |     |manageable to unauthenticated users   |     |     |     
    +-+---------------+----------+------+-----+-----+--------------------------------------+-----+——---+
    

    If it is false, use set-config to enable the property:

    ./javacloud.jar  -set-config -name credential.public.map.enabled -value true -identityDomain myIdentityDomain -serviceInstance myServiceInstance -userName myUserName -password myUserPassword 
    
  3. Verify the status change by rerunning the list-config command.

For more information on list-config and set-config, see Managing Configurations.

Enabling Access to Credentials in user.custom.map

If you are assigned the role UserMapAccessRole, you can create, read, and update credentials stored in the user.custom.map.

To allow users to access credential 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:

    Note:

    ./javacloud is a script you can use to execute java -jar javacloud.jar. In order to use it, you must add execute permission to this script.
    $ ./javacloud -dc us1 -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 (OWSM) security policies (WSS) for an OWSM truststore used for web services with OWSM policies.

Note:

  • 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.

Note:

  • 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

Supported Certificate File Formats

Java Cloud Service - SaaS Extension supports three certificate file formats:

  • Single certificates appear in DER binary format.

  • One or more certificates can appear in PEM format. The base64-encoded content of certificates is printed in base64–encoded format with the alias for each certificate shown in custom headers in the .pem file itself; for example:

    alias: orakey
    
    -----BEGIN CERTIFICATE-----
    MIICXjCCAcegAwIBAgIIHiLb185PqPEwDQYJKoZIhvcNAQEFBQAwVzETMBEGCgmS
    JomT8ixkARkWA2NvbTEWMBQGCgmSJomT8ixkARkWBm9yYWNsZTEVMBMGCgmSJomT
    8ixkARkWBWNsb3VkMREwDwYDVQQDEwhDbG91ZDlDQTAeFw0xNDExMjExNzI5NDBa
    Fw0yNDExMTgxNzI5NDBaMGkxEzARBgoJkiaJk/IsZAEZFgNjb20xFjAUBgoJkiaJ
    k/IsZAEZFgZvcmFjbGUxFTATBgoJkiaJk/IsZAEZFgVjbG91ZDEjMCEGA1UEAwwa
    dXNvcmFsY2V0cmlhbDExNjA4X2phdmFzdmMwgZ8wDQYJKoZIhvcNAQEBBQADgY0A
    MIGJAoGBAIbdlnsA5WTec3O9fjpsLTO4XPHTtK9Hy6wnIwYdX8hP3K+epNs7s7rc
    IvHZ1m6vIw0KSDyOOCnrqvf4pjFdDuO2F45FGy+aAdsQkhdIpwhWzRQSRyUdVFcl
    8fCYuQROJUSbp8P0dXbLbUYGBbiuODZbFLZfSzUigu/pklNTvXupAgMBAAGjITAf
    MB0GA1UdDgQWBBRcuDYi93M53tlBKDl4yyrmWv0SjTANBgkqhkiG9w0BAQUFAAOB
    gQA3RexPCqjf2ovOs93UD3jVWiSg7J0VQs3FRTYs3WC84B1XrXq50WCJ0/yY/NVP
    GYDAXDzmS8HHVw+jI/CptAYNISeGD0Rzg8f6uub76Ny5A97ULckLHTCNJNIKWk/0
    PIScXS93Ka7X6zUmLjqWWOUR1/oY/tLiqy/R7Tzs5ftl7w==
    -----END CERTIFICATE-----
    alias: entrustpremium
    
    -----BEGIN CERTIFICATE-----
    MIIEXDCCA0SgAwIBAgIEOGO5ZjANBgkqhkiG9w0BAQUFADCBtDEUMBIGA1UEChML
    RW50cnVzdC5uZXQxQDA+BgNVBAsUN3d3dy5lbnRydXN0Lm5ldC9DUFNfMjA0OCBp
    bmNvcnAuIGJ5IHJlZi4gKGxpbWl0cyBsaWFiLikxJTAjBgNVBAsTHChjKSAxOTk5
    IEVudHJ1c3QubmV0IExpbWl0ZWQxMzAxBgNVBAMTKkVudHJ1c3QubmV0IENlcnRp
    ZmljYXRpb24gQXV0aG9yaXR5ICgyMDQ4KTAeFw05OTEyMjQxNzUwNTFaFw0xOTEy
    MjQxODIwNTFaMIG0MRQwEgYDVQQKEwtFbnRydXN0Lm5ldDFAMD4GA1UECxQ3d3d3
    LmVudHJ1c3QubmV0L0NQU18yMDQ4IGluY29ycC4gYnkgcmVmLiAobGltaXRzIGxp
    YWIuKTElMCMGA1UECxMcKGMpIDE5OTkgRW50cnVzdC5uZXQgTGltaXRlZDEzMDEG
    A1UEAxMqRW50cnVzdC5uZXQgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkgKDIwNDgp
    
  • One or more certificates can appear in JKS format. Multiple certificates appear in the JKS file, listed by their respective aliases, but are otherwise in binary format.

Managing System Properties

From the CLI, you can list, add, or delete system properties by using system property commands in the server startup argument.

The following tale describes the commands you can use to manage system properties.

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

You must restart the service instance for the properties to be implemented.

Special Note on Disabling the Security Manager

Oracle Java Cloud Service - SaaS Extension no longer uses the Java Standard security manager. Instead, it employs the Java Cloud Service - SaaS Extension specific byte-code translation-based security manager. You should use the list-system-properties command to see if the Java Standard security manager is still enabled and, if it is, use the delete-system-property command to disable it.

Note:

./javacloud is a script you can use to execute java -jar javacloud.jar. In order to use it, you must add execute permission to this script.

To see if the Java Standard security manager is enabled:

./javacloud -u UserName -si Service Instance Name -id IdentityDomain -dc DataCenter Code -list-system-properties

If it is, to disable it:

./javacloud -u UserName -si Service Instance Name -id IdentityDomain -dc DataCenter Code -delete-system-property -name java.security.manager

Now, restart it by running this command:

./javacloud -u <UserName> -si Service Instance Name -id IdentityDomain -dc DataCenter Code -restart-service -force

Note:

You can also disable the security manager by using the -list-config command to set the jvm.standard.security.manager.enabled configuration to false. See Managing Configurations.

Managing Logging Levels

Use the CLI to list loggers and set their levels. Log levels indicate the amount of detail presented by the logged information.

Listing loggers and setting their log levels 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

Viewing Service Metrics

Use the list-service-metrics to show the metrics for a running/active service.

This command provides service performance statistics that help you measure an application's performance, identify performance bottlenecks, and monitor the health of the service as a whole. list-service-metrics is a super-set of the query-service-metrics command (now deprecated; see Note, below) that lets you access the metrics based on this hierarchy:

    instance
        applications
            OpenSessionsCurrentCount
            RequestProcessingTime
            RequestCountPerMinute
        databases/datasources
            ConnectionsTotalCount
            ConnectionsCreateRate
            ActiveConnectionsCurrentCount
        infra/storage
            free
    infra
        storage
            free
            max
    applications
        <app_name>
            OpenSessionsCurrentCount
            RequestProcessingTime
            RequestCountPerMinute
            servlets
                <servlet_name>
                    OpenSessionsCurrentCount
                    RequestProcessingTime
                    RequestCountPerMinute
    databases
         datasources
            <datasource_name>
                ConnectionsTotalCount
                ConnectionsCreateRate
                ActiveConnectionsCurrentCount
    servers
        <server_name>
            memory
                HeapFreeCurrent
                HeapSizeMax
            workmanager
                <workmanager_name>
                    CompletedRequests
                    PendingRequests
            UpSince

Note:

query-service-metrics is deprecated and a warning message appears if you use this command; however, for the near future, the command will remain in the SDK to support legacy applications.

list-service-metrics Arguments

list-service-metrics takes these arguments:

Name Description Mandatory Arguments

metric

The name of the metric. It should be of the format parent/child**; for example: -metric infra/storage. The values for parent are:

  • instance

  • infra

  • databases

  • servers

  • applications

The value for child can be empty. If this attribute is not provided, the instance level metric is returned. If the value is '/' or empty, all metrics will be listed

Shortcut: mn

user (-u), password (-p), identity domain (-id), service instance (-si)

verbose

The true/false flag that indicates whether or not the listing should be verbose (that is, full-format).

Shortcut: v

Default: false

user (-u), password (-p), identity domain (-id), service instance (-si)

gridwidth

The maximum width of the grid. You can use this if you want to limit the width of the grid display (for example, when you have a smaller display). Be aware that, if you specify a smaller width, the grid might not be formed to fit within the width. This is applicable when the argument grid is true.

Shortcut: gw

Default Value: 180

user (-u), password (-p), identity domain (-id), service instance (-si)

gridtree

The true/false flag that indicates whether or not to show the grid content in a tree-like format, by grouping columns with the same value.

Shortcut: g

Default: false

user (-u), password (-p), identity domain (-id), service instance (-si)

sorton

The sort order for the metrics. Metrics are sorted in ascending order unless the argument —descending is specified. Acceptable values are:

  • METRIC

  • VALUE

  • TYPE

  • COMPONENT

Shortcut: so

user (-u), password (-p), identity domain (-id), service instance (-si)

descending

The true/false flag that, when used with -sorton indicates whether or not the metrics should be sorted in descending order rather than ascending, which is the default. Adding this argument to this command without specifying true or false is same as specifying true.

Default: true

user (-u), password (-p), identity domain (-id), service instance (-si)

Note:

While a password is required by this command, you should not specify the -p argument on a command-line that takes the password in plain text. Instead, execute the command without specifying this argument and the system will prompt you for the password, which you can then enter securely.

Using the Command

Note:

To simplify command entry, you can store values for all parameters except -password (-p) in the javacloud.properties file. See Using javacloud.properties.

To display metrics, enter the command list-service-metrics, specifying the required user, password, identity domain, and service instance along with the metric you want to view. If you don’t specify a metric, the command displays metrics at the instance level and, by default sorted on the COMPONENT attribute. Some examples follow:

Note:

./javacloud is a script you can use to execute java -jar javacloud.jar. In order to use it, you must add execute permission to this script.
To display metrics at the instance level:
./javacloud list-service-metrics -dc us1 -id usoracletrial09442 -si javatrial6938 -gridtree [-metric instance]
Note that specifying the level (-metric instance) is optional.
The output would be (with -gridtree specified):
#====================================================================================#
|                               Listing one Metric(s)                                |
| [Identity Domain=usoracletrial09442, Service Instance=javatrial6938],              |
| Instance Level Summary                                                             |
#=========#==========================================================================#
|Component|                                 Metrics                                  |
|=========|==========================================================================|
|         | Component  |                           Metrics                           |
|         |============|=============================================================|
|         |            |         Name          |                Value                |
|         |            |=======================|=====================================|
|         |            |Active Sessions Count  |0                                    |
|         |applications|-----------------------+-------------------------------------|
|         |            |Request Processing Time|0                                    |
|         |            |-----------------------+-------------------------------------|
|         |            |Requests Count         |0.000 per minute                     |
|         |------------+-------------------------------------------------------------|
|         |            | Component |                     Metrics                     |
|         |            |===========|=================================================|
|instance |            |           |              Name              |     Value      |
|         |            |           |================================|================|
|         |databases   |           |Connections Total Count         |0               |
|         |            |datasources|--------------------------------+----------------|
|         |            |           |JDBC Connection Create Rate     |0.000 per minute|
|         |            |           |--------------------------------+----------------|
|         |            |           |Open JDBC Connections Count     |0               |
|         |------------+-------------------------------------------------------------|
|         |            |Component|                      Metrics                      |
|         |            |=========|===================================================|
|         |infra       |         |Name|                    Value                     |
|         |            |storage  |====|==============================================|
|         |            |         |Free|5119 MB                                       |
+---------+--------------------------------------------------------------------------+
To view all storage metrics:
./javacloud list-service-metrics -dc us1 -u system -id usoracletrial09442 -si javatrial6938  -metric infra/storage
The output would be:
#====================================#
|       Listing 2 Metric(s)          |
|[Identity Domain=usoracletrial09442,|
| Service Instance=javatrial6938],   |
| Component Level                    |  
#===========#=============#==========#
|Metric Name|  Component  | Value    |
|===========|=============|==========|
|Free       |infra/storage|5118 MB   |
|-----------+-------------+----------|
|Maximum    |infra/storage|5120 MB   |
+-----------+-------------+----------+
To view an application-level metric:
./javacloud list-service-metrics -dc us1 -u system -id usoracletrial09442 -si javatrial6938 -gridtree -metric applications/welcome-app/RequestcountPerMinute
The output would be:
#========================================================#
|                 Listing one Metric(s)                  |
|   [Identity Domain=usoracletrial09442,                 |
|    Service Instance=javatrial6938], Component Level    |
#============#===========================================#
| Component  |                  Metrics                  |
|============|===========================================|
|            | Component |            Metrics            |
|            |===========|===============================|
|applications|           |Name/Component|     Value      |
|            |welcome-app|==============|================|
|            |           |Requests Count|0.015 per minute|
+------------+-------------------------------------------+

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:

  4. Click the Local File System Access Test link.

    This opens the Filer Browser's current directory page:

  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.

The File System Access 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:

$ ./javacloud -dc us1 -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 Application and Domain Configuration Shell (the "Config Shell") enables you to perform general web service and WebLogic domain configuration tasks.

Use the CLI commands to 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 how to use them, 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".

For more information, see the following topics:

Using the Basic Config Shell Commands

The "Config Shell" enables you to use the CLI to perform general web service and WebLogic domain configuration tasks.

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

Starting the Config Shell

Here is an example of entering the Config Shell.

$ ./javacloud -dc us1 -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.

$ ./javacloud -dc us1 -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

You can use the Config Shell commands discussed in this section to override an web service endpoint address for a web service client.

The following use case shows one way 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:>
    

CLI Commands in the SDK

Use the commands described in this topic with the Oracle Java Cloud Service - SaaS Extension command-line interface to monitor applications deployed on your service instance.

Some of the following commands are documented elsewhere in this guide but you can more information on each of them by navigating 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 You can also access all the SDK documentation via the Welcome App, as described in SDK Documentation.

Command Description For More Information

add-datasource-jndiname

Add a new JNDI name for a data source.

 

add-ssl-certificates

Uploads one or more new certificates into the outbound SSL truststore from the local disk.

Managing SSL Truststores

add-wss-certificates

Uploads one or more new certificate into the web service security (WSS) truststore.

Managing Web Services Security Truststore

config-shell

Executes service/application configuration commands.

 

delete

Deletes an installed application permanently. The existing user sessions for the application, if any, will be lost.

 

delete-credential

Deletes an existing credential.

Managinmg Credentials

delete-datasource-jndiname

Delete existing JNDI name for a data source.

 

delete-library

Deletes an installed shared library permanently.

Managing Shared Libraries

delete-ssl-certificates

Deletes one or more existing certificates from the outbound SSL truststore.

Managing SSL Truststores

delete-system-property

Deletes a persisted system property.

Managing System Properties

delete-wss-certificates

Deletes one or more existing certificates from the web service security (WSS) truststore.

Managing Web Services Security Truststore

describe-application

Describes an application identified by its name. The description includes the current status and the application URLs (one for each web module) that can be used to access the application. If you would like to know the run-time metrics of web modules, use the command query-service-metrics".

 

describe-credential

Describes a credential identified by a key.

Managinmg Credentials

describe-library

Describes a shared library identified by its name, spec version, and impl version. The description includes the status, deploy type, type, and the name of the applications that reference this library.

Managing Shared Libraries

describe-service-instance

Describes a service instance under an identity domain. The description includes the status of the service instance and the size of the offering.

 

download-artifacts

Downloads artifacts such as:
  • Whitelist configuration file used by the service instance.

  • Applications deployed by the users.

  • Shared libraries that are available to user applications.

Multiple artifacts can be downloaded using a single command-line.
 

download-ssl-certificates

Downloads one or more certificates from the outbound SSL truststore to the local disk.

Managing SSL Truststores

download-wss-certificates

Downloads a certificate from the web services security WSS) truststore.

Managing Web Services Security Truststore

fs-shell

Executes file system-specific shell commands.

Note: The shell is not like an OS shell. This shell supports only simple commands that are useful in managing files in a Java Cloud Service - SaaS Extension instance. The options that are available for a standard OS command are not available in this shell. For example, ls -ltr will not work here. In this shell, the supported options work his shell.
  • Piping is not allowed.

  • Redirection is not allowed.

  • Special characters such as *,#:?![](){}<>%@$ are not allowed. See -validatespecialchars.

 

install

Installs a user application that is already bundled and available in the local disk. Use the command install-library, if you want to install a shared library.

 

install-library

Installs a custom shared library.

Managing Shared Libraries

job-log-file

Downloads the job log file and writes to the local disk.

 

job-status

Describes a job identified by its job ID. The description includes the current status, start time, and end time of the job.

 

list-applications

Lists all the applications that are installed and available in the service instance.

 

list-commands

Lists all the commands. You can use the argument -search to find specific set of commands. This is the default command

 

list-config

Lists all available editable configurations. Use this command to see which configurations you can change by using set-config.

Managing Configurations

list-credentials

Lists all the credentials.

Managing Credentials

list-datasource-jndinames

Lists all the JNDI names for a data source.

 

list-job-logs

Lists all the logs associated with a job.

 

list-jobs

Lists all job details that are visible to the user. You can scope the listing using options "serviceinstance" and/ or "application".

 

list-libraries

Lists all the shared libraries that are installed and available in the service instance.

Managing Shared Libraries

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.

Managing Logging Levels

list-service-metrics

Provides service performance statistics that help you measure an application's performance, identify performance bottlenecks, and monitor the health of the service as a whole. list-service-metrics is a super-set of the query-service-metrics command (now deprecated) that lets you access the metrics based on this hierarchy:

Viewing Service Metrics

list-ssl-certificates

Lists all the trusted certificates from the SSL truststore. SSL outbound calls from Java Cloud Service - SaaS Extension are authorized based on these certificates.

Managing SSL Truststores

list-system-properties

Lists all persisted system properties.

Managing System Properties

list-wss-certificates

Lists all the trusted certificates from the web service security (WSS) truststore.

Managing Web Services Security Truststore

query-service-logs

Gets application log records that match the given search criteria. The search scope is restricted using one of the combinations “last,unit” or "starttime,endtime". You can limit the number of log records in the search results to be returned by using -limit.

 

query-service-metrics

Lists service instance application metrics.

 

reset-ssl-certificate-store

Restore the SSL truststore to the default as a newly-provisioned instance. Any certificates that were added will be lost. The deleted certificates will be restored.

Managing SSL Truststores

reset-wss-certificate-store

Restore the web services security (WSS) trust-store to the default as a newly-provisioned instance. Any certificates that were added will be lost. The deleted certificates will be restored.

Managing Web Services Security Truststore

restart-service-instance

Restarts the service instance.

 

set-config

Sets the value for a configuration listed by the list-config command.

Managing Configurations

set-credential

Adds or updates a credential against key.

Managinmg Credentials

set-log-level

Sets the Log level of the Logger to the given level. Note that Oracle Java Cloud Service - SaaS Extension also supports Weblogic's logging convention.

Managing Logging Levels

set-system-property

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

Managing System Properties

start

Starts an already installed application that is in the stopped state.

 

stop

Stops an installed and running application.

 

update

Updates an existing installed application.

 

update-library

Updates an existing installed shared library.

Managing Shared Libraries

usage

Prints the usage of this tool into the HTML file (defaulted to - usage.html) for off-line reference.

 

version

Provides the build (version) number of this tool.