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
Obtaining the Command Line Interface
By installing the Oracle Java Cloud Service - SaaS Extension SDK (software development kit), you have access to a command-line interface (CLI). Click here to download the Oracle Java Cloud Service - SaaS Extension SDK.
-
Go to the Oracle Cloud home page or to any Oracle Cloud page that has the Resources menu.
-
Click the Resources menu and, in the Support column, select for Developers
-
In the Downloads area, click Oracle Cloud Downloads. If prompted, sign in using your Oracle.com account credentials.
The Oracle Cloud Downloads page appears. All relevant Oracle Cloud downloads will be accessible on the page.
-
Under Java Cloud Services, click Oracle Java Cloud Service - SaaS Extension SDK.
This will take you to the Oracle Java Cloud Service - SaaS Extension SDK panel.
-
Click the Download Oracle Java Cloud Service - SaaS Extension SDK link.
Using the Command Line Interface
You can use the CLI to manage an Oracle Java Cloud Service - SaaS Extension instance as follows:
-
javacloud.jar
– General application management tasks, such asinstall
,remove
,update
,start
, andstop
. -
File System Access Shell – Basic file management commands to manage your local
/customer/scratch/
directory. See Using the File System Access Shell. -
Configuration Shell – General web service and WebLogic domain configuration tasks. See Using the Application and Domain Configuration Shell.
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". 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 argumentidentitydomain
. -
Full form—The argument name is specified along with the command name; for example,
list-jobs.sorton=STATUS
, wherelist-jobs
is a valid command name andsorton
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:
-
Argument value, if specified in the command line.
-
Argument value, if specified in the property file.
-
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 Support in JCS-SaaS Extension
JCS-SaaS Extension's email notification feature allows you to use the JavaMail APIs in your application to send out emails. This feature uses an Oracle managed outbound mail gateway. Your application should not use or configure any SMTP mail gateway. The Oracle managed email gateway has quota limitations as described below.
Process for Enabling the Email Feature
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.
Email Size Limit
The maximum size for an entire email is 1 MB, including both the body of the email and the attachments. If your email size exceeds this limit, then the email is not sent and an error message is added to the log file.
Prerequisites for Enabling the Email Feature
Before you can enable email notifications in your application, you need to meet certain prerequisites.
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.
Note:
If you want to use an existing user (not recommended), start with step 4.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.
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.
// To send email in JCSSX, you do not need to specify any property. You only need to provide the user id // and password of a user with the Java_Notification_User custom role. Properties props =newProperties(); //You can specify the user and password by providing an authenticator when creating the session, like this: /*Session session = Session.getInstance(props, newjavax.mail.Authenticator() { protectedPasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(uname, pwd); } } );*/ // If you do not specify an authenticator for the session, you can provide the user and password when // connecting the transport Properties props = newProperties(); Session session = Session.getInstance(props); try { InternetAddress[] recipientAddress = {new InternetAddress("user.name@domain.ext")}; MimeMessage msg = new MimeMessage(session); msg.setFrom(new InternetAddress("javamail@oracle.com")); msg.setRecipients(Message.RecipientType.TO, recipientAddress ); msg.setSubject(subject); msg.setSentDate(new Date()); msg.setText(msgText); Transport transport = session.getTransport("smtp"); // Provide the user and password if you do not specify an authenticator when creating the session transport.connect(uname, pwd); // If you provide an authenticator when creating the session, you do not need user and password in next line //transport.connect(); transport.sendMessage(msg, recipientAddress); } catch (MessagingException e) { e.printStackTrace(); }
Task 4: Update weblogic.xml to Reference the Jersey JARs
The email feature internally uses REST API's to make a call to the Oracle managed email gateway. This requires that your application references the JAX-RS 1.1 API library (Jersey) . This can be achieved by updating your application’s weblogic.xml file.
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 -showvalues (-s ) command.
|
user, password, identitydomain, serviceinstance
Three other arguments you need to consider are:
|
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.
-
Use
list-config
to display the properties you can configure:./javacloud -list-config -showvalues -identityDomain myIdentityDomain -serviceInstance myServiceInstance -userName myUserName -verbose
The system responds with a list similar to this:
#==================================================================================================================================================================================# | Listing 20 Simple Configs | | [Identity Domain=jcscdc, Service Instance=javas2] | #=#===================#==========#======#=======#========#===========================================================================================================#=======#=====# | | | |Value |Value |Restart | | | | |#| Name |Value Type|Readab|Writabl|Required| Description | Value |Label| | | | | le | e | | | | | |=|===================|==========|======|=======|========|===========================================================================================================|=======|=====| |1|jta.transaction. |INTEGER | Y | Y | |JTA transaction timeout. |30 |secon| | |timeout | | | | | | |ds | |-+-------------------+----------+------+-------+--------+-----------------------------------------------------------------------------------------------------------+-------+-----| | |ssl.twoway.client. | | | | |Set the alias of the private key that the client should use while authenticating with the two-way ssl |-- | | |2|alias |STRING | Y | Y | |enabled endpoint.Please use the command -list-ssl-private-keys to know all the existing aliases. |AliasNo| | | | | | | | | |tSet-- | | |-+-------------------+----------+------+-------+--------+-----------------------------------------------------------------------------------------------------------+-------+-----| |3|servers.status. |STRING | Y | Y | |Managed Server Status(es). If any of the servers is in the admin state, Set the value to be true to resume |RUNNING| | | |running | | | | |it. | | | |-+-------------------+----------+------+-------+--------+-----------------------------------------------------------------------------------------------------------+-------+-----| | | | | | | |JVM's Max Perm Size argument value. | | | | |jvm.arg.max.perm. | | | | |Minimum value : 256 (MB) | | | |4|size |INTEGER | Y | Y | Y |Maximum value : 1024 (MB) |-1 |MB | | | | | | | |Negative value indicates that the value is not set. ie) the default. | | | | | | | | | | | | | |-+-------------------+----------+------+-------+--------+-----------------------------------------------------------------------------------------------------------+-------+-----| | | | | | | |JVM's Stack Size argument value. | | | | | | | | | |Minimum value : 228 (KB) | | | |5|jvm.arg.stack.size |INTEGER | Y | Y | Y |Maximum value : 1024 (KB) |512 |KB | | | | | | | |Negative value indicates that the value is not set. ie) the default. | | | | | | | | | | | | | |-+-------------------+----------+------+-------+--------+-----------------------------------------------------------------------------------------------------------+-------+-----| | |jvm.standard. | | | | | | | | |6|security.manager. |BOOLEAN | Y | Y | Y |Standard Java Security manager enabled? |false | | | |enabled | | | | | | | | |-+-------------------+----------+------+-------+--------+-----------------------------------------------------------------------------------------------------------+-------+-----| |7|sun.http.handler. |BOOLEAN | Y | Y | Y |Sun HTTP handler enabled? |true | | | |enabled | | | | | | | | |-+-------------------+----------+------+-------+--------+-----------------------------------------------------------------------------------------------------------+-------+-----| | | | | | | |Minimum version of SSL or TLS protocols that is enabled for SSL connections. | | | | | | | | | |SSLv3 : Specifies SSL V3.0 as the minimum protocol version enabled in SSL connections. | | | | | | | | | |TLSv1 : Specifies TLS V1.0 as the minimum protocol version enabled in SSL connections. | | | | |security.SSL. | | | | |TLSvx.y : Specifies TLS Vx.y as the minimum protocol version enabled in SSL connections, where: | | | |8|minimum.protocol. |STRING | Y | Y | Y | x is an integer between 1 and 9, inclusive | | | | |version | | | | | y is an integer between 0 and 9, inclusive | | | | | | | | | | e.g. TLSv1.2 | | | | | | | | | |"" : The value of "" indicates the minimum protocol version is not set and default value will be used | | | | | | | | | | | | | |-+-------------------+----------+------+-------+--------+-----------------------------------------------------------------------------------------------------------+-------+-----|
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 aY
in the Value Writable column. Note that some values can’t be changed and others will require system restart for the change to occur.The configurations you can modify are:
Name Value Type Readable Writeable Restart Description Specify As credential.custom.map.enabled
Boolean Y Y N Specifies whether the Credential Store custom map is enabled. When value is set to true, all authenticated users with the role UserMapAccessRole will be able to read credentials from this map. Ensure UserMapAccessRole role is available before using the set-config command to enable or disable this map. true | false credential.public.map.enabled
Boolean Y Y N Specifies whether or not the Credential Store public map is enabled. Note: Setting this value to true permits unauthenticated users to manage the
user.public.map
credential map.true | false internal.datasource.opss.global.txn
String Y Y Y Determines the transaction protocol (global transaction processing behavior) for the internal OPSS datasource. Supported Values: -
None (Recommended): Support for local transactions only.
-
OnePhaseCommit: One-phase XA transaction processing using a non-XA driver.
For this configuration to take effect, you need to restart the instance.
Note:
If the value is-No-OPSS-DS-
, this configuration doesn't apply for the instance.Alpha java.mail.enabler
Boolean Y Y Y Enables the JavaMail-based email feature to send emails from deployed applications. When this value is set to true, the applications deployed on the given service instance will be send emails by using the JavaMail API. true | false jdbc.datasource.idle.trust.seconds
Integer Y Y N The number of seconds within a connection period that WebLogic Server trusts to still be viable and thus skip the connection test, either before delivering it to an application or during the periodic connection testing process. Seconds jdbc.datasource.inactive.timeout
Integer Y Y N The number of inactive seconds on a reserved connection to elapse before WebLogic Server reclaims the connection and releases it back into the connection pool. You can use the Inactive Connection Timeout feature to reclaim leaked connections; that is, connections that were not explicitly closed by the application. Note that this feature is not intended to be used in place of properly closing connections. When set to 0, the feature is disabled. Seconds jdbc.datasource.initial.capacity
Integer Y N N The number of physical connections to create when creating the connection pool in the data source. If this number of connections cannot be created, data source creation will fail. Numeric jdbc.datasource.max.capacity
Integer Y Y N Used with set-config
to set the maximum number of physical connections that this connection pool can contain. The JDBC Pool maximum connection values are:-
TRIAL: JDBC pool connections = 5
-
BASIC (PAID): JDBC pool connections = 10
-
STANDARD: JDBC pool connections = 20
-
ENTERPRISE: JDBC pool connections = 40
Do not exceed these maximums.
Numeric jdbc.datasource.min.capacity
Integer Y N N The minimum number of physical connections that this connection pool, after it is initialized, can contain. Numeric jdbc.datasource.shrink.frequency
Integer Y N N The number of seconds to wait before shrinking a connection pool that has incrementally increased to meet demand. When set to 0, shrinking is disabled. Seconds jdbc.datasource.statement.timeout
Integer Y Y Y The time after which a statement currently being executed will time out. StatementTimeout
relies on underlying JDBC driver support. WebLogic Server passes the time specified to the JDBC driver using thejava.sql.Statement.setQueryTimeout()
method. If your JDBC driver does not support this method, it may throw an exception and the timeout value is ignored.-
A value of -1 disables this feature.
-
A value of 0 means that statements will not time out.
Seconds jdbc.datasource.timeout
Integer Y Y N The number of seconds after which a call to reserve a connection from the connection pool will time out.
-
When set to 0, a call will never time out.
-
When set to -1, a call will time out immediately.
Seconds jta.transaction.timeout
Integer Y Y N JTA transaction timeout Seconds jvm.arg.max.perm.size
Integer Y Y Y JVM's Max Perm Size argument value. Negative value indicates that the value is not set. ie) the default. MB jvm.arg.reserved.code.cache.size
Integer Y Y Y Determines the maximum size of the code cache. -
Minimum value : 48 (MB)
-
Maximum value: 240 (MB)
A negative value indicates that maximum size is not set; that is, it’s the default. The default depends on the JRE version on which your application is running. Refer to the Welcome app on your instance to learn your server’s JRE version.
MB jvm.arg.stack.size
Integer Y Y Y JVM's Stack Size argument value. Negative value indicates that the value is not set. ie) the default. KB jvm.arg.use.code.cache.flushing
String Y Y Y Turns code cache flushing on and off. When enabled, the code cache flushing is triggered when the memory available in the code cache is low. You must enable code cache flushing if you constrain the code cache. If flushing is disabled and the code cache is full, the JIT compiler will not compile methods.
-
Accepted values are
on
andoff
. -
The value of
""
indicates that code cache flushing is not set and the default value will be used. The default depends on the JRE version on which your application is running. Refer to the Welcome app on your instance to learn your server’s JRE version
on | off jvm.standard.security.manager.enabled
Boolean Y Y Y Specifies whether or not the standard JVM security manager is enabled. true | false logging.system.loggers.enabled
Boolean Y Y Y Allows you to enable JDK system loggers (such as oracle.wsm) in runtime. When this value is set to true, system loggers will be enabled and you will be allowed to set logging levels in runtime. Setting this value to false disables the loggers. true | false security.SSL.minimum.protocol.version
String Y Y Y Minimum version of SSL or TLS protocols enabled for SSL connections. -
SSLv3 : Specifies SSL V3.0 as the minimum protocol version enabled in SSL connections.
-
TLSv1 : Specifies TLS V1.0 as the minimum protocol version enabled in SSL connections.
-
TLSvx.y : Specifies TLS Vx.y as the minimum protocol version enabled in SSL connections, where:
-
x is an integer between 1 and 9, inclusive.
-
y is an integer between 0 and 9, inclusive; for example, TLSv1.2.
-
-
"" : The value of "" indicates the minimum protocol version is not set and default value will be used .
Alphanumeric server.max.thread.stuck.time
Integer Y Y Y The number of seconds that a thread must continually be working before the server determines that the thread is stuck. Seconds servers.status.running
String Y Y N Managed Server Status(es). If any of the servers are in the admin state, set the value to be true to resume it. true | false ssl.twoway.client.enabled
String Y Y N Set the alias of the private key that the client should use while authenticating with the two-way ssl Alphanumeric sun.http.handler.enabled
Boolean Y Y Y Indicates whetehr or not the Sun HTTP handler is enabled. true | false Note:
In administration console, you can find these properties in these locations:-
JDBC properties: Services/DataSources/${datasourceName}/ Connection Pool. Some properties are available under Connection Pool/Advanced.
-
server.max.thread.stuck.time
: Environment/Servers/m0/Overload/Max Stuck Thread Time.
-
-
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 -set-config -name jta.transaction.timeout -identityDomain myIdentityDomain -serviceInstance myServiceInstance -userName myUserName -value 34
Note:
The value you set should be a legal value; for example, setting a very low value forjvm.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.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.
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.-
First, use
list-config
to determine the property status:./javacloud -list-config -identityDomain myIdentityDomain -serviceInstance myServiceInstance -userName myUserName -password myUserPassword -verbose -showvalues
-
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 -set-config -name credential.public.map.enabled -value true -identityDomain myIdentityDomain -serviceInstance myServiceInstance -userName myUserName -password myUserPassword
-
Verify the status change by rerunning the
list-config
command.
For more information on list-config and set-config, see Managing Configurations.
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 |
---|---|---|
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 |
Note:
You can automate the process of setting up WSS trust from a local WebLogic Server domain to a JCS-SaaS Extension instance in the cloud by using the setup-wss-trust command. See Setting Up Trust Between WebLogic Domains and JCS-SaaS Extension.Setting Up WSS Trust Between Two Instances or Between an On-premises WLS Domain and One Instance
The setup-wss-trust
command-line tool that automates the process of setting up Web Service Security (WSS) trust from a local WebLogic Server domain to a JCS-SaaS Extension instance in the cloud or between two JCS-SaaS Extension instances running in different identity domains.
This table describes the commands for setting up these particular patterns of WSS trust.
Command | Description | Mandatory Arguments |
---|---|---|
|
Sets up WSS trust from a local WebLogic domain to the JCS-SaaS Extension instance on the cloud. Once the trust is set up, the on-premises local WebLogic domain will be able to propagate identity and protect message. |
user, password, identitydomain, serviceinstance, alias, issuer |
See Setting Up Trust Between WebLogic Domains and JCS-SaaS Extension.
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 |
---|---|---|
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 the UseSunHttpHandler Property
Oracle Java Cloud Service -
SaaS Extension doesn't allow you to set the UseSunHttpHandler
property by using the System Properties section of the Administration console, using the set-system-property
CLI command or directly by calling System.setProperty("UseSunHttpHandler", "true")
in the code. Instead, use the sun.http.handler.enabled
configuration, where you can check whether the UseSunHttpHandler
system property is set. You must do this because additional behavior was added to improve instance functionality within the UseSunHttpHandler
system property. This property is widely used and it solves several outbound connectivity problems.
Note:
To enable thesun.http.handler.enabled
configuration, you can change the value in the Settings section of the Administration Console or via SDK as follows:./javacloud -u UserName -si Service Instance Name -id IdentityDomain -dc DataCenter Code -set-config -name sun.http.handler.enabled -value true
See Managing Configurations and Viewing System Configurations on the Settings Page.
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.
Viewing Access Logs
Use the query-access-logs
command to view information in the access.log
file.
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.access.log
. You can access these logs from JCS-SaaS Extension by using the query-access-logs
command provided by the SDK; for example:./javacloud -user joe.user@myCo.com -password imjoespw -identitydomain mycopaid17110 -serviceinstance paidstandard1 -query-access-logs
Weblogic Server has a dedicated buffer that stores the HTTP requests to the server before they appear in the access.log
file. The server will flush the buffer with the HTTP access information to the access.log
once the buffer is fulll. By default this buffer size is set to 8Kb, so, in order to be reflected more recent logs via this query-access-logs
, it is required reach the max of this buffer size.
Using the Command
#==================================================================================================================================================================================#
| Listing 32 log records |
#==#===========#===========#=======================================================================================================================================================#
|S.| Auth User | DateTime | Request |
|No| | | |
|==|===========|===========|=======================================================================================================================================================|
| | |Sat Nov 19 | |
|1 |- |10:03:00 |GET:/Diagnostic/DiagnosticService?WSDL |
| | |PST 2016 | |
|--+-----------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------|
| | |Sat Nov 19 | |
|2 |- |10:05:07 |GET:/Diagnostic/DiagnosticService?WSDL |
| | |PST 2016 | |
|--+-----------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------|
| | |Sat Nov 19 | |
|3 |- |11:40:53 |GET:/basic/faces/view1.jspx |
| | |PST 2016 | |
|--+-----------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------|
| | |Sat Nov 19 | |
|4 |- |11:40:53 |GET:/basic/faces/view1.jspx |
| | |PST 2016 | |
|--+-----------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------|
| | |Sat Nov 19 | |
|5 |- |11:42:28 |GET:/basic/index.jsp |
| | |PST 2016 | |
|--+-----------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------|
| | |Sat Nov 19 | |
|6 |- |11:42:28 |GET:/basic/index.jsp |
| | |PST 2016 | |
|--+-----------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------|
| | |Sat Nov 19 | |
|7 |- |12:16:00 |GET:/ws/wssunt?wsdl |
| | |PST 2016 | |
|--+-----------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------|
| | |Sat Nov 19 | |
|8 |- |12:16:04 |GET:/date/ |
| | |PST 2016 | |
|--+-----------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------|
By using the optional parameters, you can tailor reports to show just information germane to your requirements. For example, you can filter query access logs by:-
The maximum number of search records to be returned.
-
Whether the listing should be in a verbose mode.
-
Time and date range.
-
The HTTP method used for request search for in the access logs. You can provide one or multiple values for this parameter such as: GET,PUT,POST,DELETE.
-
An authorized username in the access log.
-
The source IP from which the access log search was requested.
-
The URL path from which the access log search was requested.
./javacloud -user joe.user@myCo.com -password imjoespw -identitydomain mycopaid17110 -serviceinstance paidstandard1 -query-access-logs -limit 10 -starttime 19/11/2016:10:00 -endtime 19/11/2016:11:50 -datetimeformat dd/MM/yyyy:HH:mm
You would receive a listing like this:-----------[Fetching at Mon Nov 21 18:27:55 PST 2016]-----------
#==================================================================================================================================================================================#
| Listing 6 log records |
#====#=========#============================#======================================================================================================================================#
|S.No|Auth User| DateTime | Request |
|====|=========|============================|======================================================================================================================================|
|1 |- |Sat Nov 19 10:03:00 PST 2016|GET:/Diagnostic/DiagnosticService?WSDL |
|----+---------+----------------------------+--------------------------------------------------------------------------------------------------------------------------------------|
|2 |- |Sat Nov 19 10:05:07 PST 2016|GET:/Diagnostic/DiagnosticService?WSDL |
|----+---------+----------------------------+--------------------------------------------------------------------------------------------------------------------------------------|
|3 |- |Sat Nov 19 11:40:53 PST 2016|GET:/basic/faces/view1.jspx |
|----+---------+----------------------------+--------------------------------------------------------------------------------------------------------------------------------------|
|4 |- |Sat Nov 19 11:40:53 PST 2016|GET:/basic/faces/view1.jspx |
|----+---------+----------------------------+--------------------------------------------------------------------------------------------------------------------------------------|
|5 |- |Sat Nov 19 11:42:28 PST 2016|GET:/basic/index.jsp |
|----+---------+----------------------------+--------------------------------------------------------------------------------------------------------------------------------------|
|6 |- |Sat Nov 19 11:42:28 PST 2016|GET:/basic/index.jsp |
+----+---------+----------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
-----------[Fetched at Mon Nov 21 18:27:56 PST 2016]-----------
For another example, if you wanted to filter the results to just the most recent five logs based on a source IP and return those results in a verbose status, you might enter:./javacloud -user joe.user@myCo.com -password imjoespw -identitydomain mycopaid17110 -serviceinstance paidstandard1 -query-access-logs -sourceip 10.242.200.4 -verbose -limit 5
which would return:-----------[Fetching at Mon Nov 21 20:57:40 CST 2016]-----------
#==================================================================================================================================================================================#
| Listing 10 log records |
#==#=========#=======#==========#=========================================================================================================================================#===#====#
|S.|Auth User|Source | DateTime | Request |Sta|Byte|
|No| | Ip | | |tus| s |
|==|=========|=======|==========|=========================================================================================================================================|===|====|
| |jose. | |Sat Nov | | | |
|1 |hijar@ora|10.242.|19 |GET:/greeting-basic-auth/secured.jsp |200|6393|
| |cle.com |200.4 |14:16:08 | | | |
| | | |CST 2016 | | | |
|--+---------+-------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+---+----|
| |jose. | |Sat Nov | | | |
|2 |hijar@ora|10.242.|19 |GET:/greeting-basic-auth/ |200|1952|
| |cle.com |200.4 |14:16:10 | | | |
| | | |CST 2016 | | | |
|--+---------+-------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+---+----|
| | | |Sat Nov | | | |
|3 |- |10.242.|19 |GET:/greeting-sso/ |302|667 |
| | |200.4 |14:16:17 | | | |
| | | |CST 2016 | | | |
|--+---------+-------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+---+----|
| | | |Sat Nov | | | |
|4 |- |10.242.|19 |GET:/greeting-sso/ |302|667 |
| | |200.4 |14:16:17 | | | |
| | | |CST 2016 | | | |
|--+---------+-------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+---+----|
| | | |Sat Nov |GET:/wc3/faces/main.jspx; | | |
|5 |- |10.242.|19 |jsessionid=biN-PmoYUO9TfRuBbRGYGuEn3rFctL87eOUmaqFGG28cbRsqUBbG!-1235228672?_afrLoop=11755622606974&_afrWindowMode=0&_afrWindowId=null&_ |302|389 |
| | |200.4 |14:19:29 |adf.ctrl-state=wvu0spdue_1 | | |
| | | |CST 2016 | | | |
+--+---------+-------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+---+----+
-----------[Fetched at Mon Nov 21 20:57:42 CST 2016]-----------
For a complete list of all optional parameters for -query-access-logs
, navigate to the $SDK_HOME/doc/index.html
file (where SDK_HOME
is the directory containing your Oracle Java Cloud Service - SaaS Extension installation) and search on the command name.
Log Format
host RFC931 auth_user [day/month/year:hour:minute:second UTC_offset] "request" status bytes
where: -
host
— Either the DNS name or the IP number of the remote client. -
RFC931
— Any information returned by IDENTD for the remote client; WebLogic Server does not support user identification. -
auth_user
— If the remote client user sent a userid for authentication, the user name; otherwise “-
”. -
day/month/year:hour:minute:second UTC_offset
— Day, calendar month, year and time of day (24-hour format) with the hours difference between local time and GMT, enclosed in square brackets. -
"request"
— First line of the HTTP request submitted by the remote client enclosed in double quotes. -
status
— HTTP status code returned by the server, if available; otherwise “-
”. -
bytes
Number of bytes listed as the content-length in the HTTP header, not including the HTTP header, if known; otherwise “-
”.
Viewing Service Logs
You can access and view service log files by using the query-service-logs
command. These logs are useful when troubleshooting issues that might arise with your JCS-SaaS Extension instance.
Command | Description | Mandatory Arguments |
---|---|---|
query-service-logs | Gets application log records that match the given search criteria. | identitydomain, user, serviceinstance |
This command gets application log records based on specified search criteria. You can further restrict the search scope by using one of the combinations of last,unit or starttime,endtime. Also, you can limit the number of log records returned in the search results by using -limit.
./javacloud -query-service-logs -identitydomain myIdentityDomain -user myUserName -serviceinstance myServiceInstance -starttime MM/DD -endtime MM/DD -limit 10 -last HOUR
In this example, service logs compiled up though the last hour of a 24–hour period beginning at the given date would be produced for viewing. The default value format for starttime
and endtime
is the month and day (MM/DD). You can use the datetimeformat
parameter to set the starttime
and endtime
parameters to a format such as 18:00:00.
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:
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 ( |
verbose |
The true/false flag that indicates whether or not the listing should be verbose (that is, full-format). Shortcut: v Default: false |
user ( |
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 ( |
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 ( |
sorton |
The sort order for the metrics. Metrics are sorted in ascending order unless the argument
Shortcut: so |
user ( |
descending |
The true/false flag that, when used with Default: true |
user ( |
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.
./javacloud list-service-metrics -dc us1 -id usoracletrial09442 -si javatrial6938 -gridtree [-metric instance]
Note that specifying the level (-metric instance
) is optional.
-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 | +---------+--------------------------------------------------------------------------+
./javacloud list-service-metrics -dc us1 -u system -id usoracletrial09442 -si javatrial6938 -metric infra/storage
#====================================# | 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 | +-----------+-------------+----------+
./javacloud list-service-metrics -dc us1 -u system -id usoracletrial09442 -si javatrial6938 -gridtree -metric applications/welcome-app/RequestcountPerMinute
#========================================================# | 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| +------------+-------------------------------------------+
Refreshing an Application
Use the -refresh
command whenever you need to download and redeploy applications that were previously deployed to JCS-SaaS Extension instances.
You can use this command with any out-of-date version of JCS-SaaS Extension. It is particularly useful if you are encountering login issues with older applications. For example, if you provisioned an instance with a version of JCS-SaaS Extension prior to 17.1.3 but then patched your service with this later release, you might encounter a blank page when trying to log in to applications deployed on that instance. If this occurs, you need to download and redeploy these applications to load the latest tag libraries. -refresh
facilitates this task.
Command | Description | Mandatory Arguments |
---|---|---|
refresh |
Downloads and redeploys applications to ensure that the latest tag libraries are included. Note: This command resolves an issue wherein a blank screen would appear after logging in to an ADF application deployed on a JCS-SaaS Extension instance provisioned before version 17.1.3 but subsequently upgraded to that version (see ADF Application Login Results in Blank Page). If you have any deployments that match this condition, you should run this command. |
user ( |
$ ./javacloud -u username -id myiddomain123 -si javatrial23 -refresh -app hcmconnect-ear-1.1.0-SNAPSHOT
Note that this command will return a job identifier; for example:[INFO] - The application is being refreshed.
1:Job Id - 5103
----------- - -----------------------
You can use this job number with the job-status
command to track the status of the refresh.
Synchronizing UI and SDK Data
You can use the SDK command sync-system
to synchronize data between the resource management UI and the SDK.
Occasionally, you might notice that association and utilities data that appear in the resource management UI’s Home section might not appear or don’t match similar data for the same instance returned when you run the describe-service-instance
SDK command. Values such as state, version, and associations should match and when they don’t, use the SDK commandsync-system
to synchronize them.
Command | Description | Mandatory Arguments |
---|---|---|
sync-system |
Synchronizes client and service instance data. |
user (u), identitydomain (id), serviceinstance (si)
Note: For a complete list of optional, advanced and diagnostic/help parameters, use the-detail parameter with the Help command.
|
For example:
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 -a http://myServer.us.MyCorp.com:7003 -si myServiceInstance -id myIdentityDomain -user joe.user@MyCorp.com -p jcssx1234 -sync-system
If the synchronization is successful, the system will respond:
[INFO] - System is synchronized.
Otherwise, if it fails the system will respond:
[ERROR] - The system could not be synchronized.
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.
Note:
The File Browser application is a sample, provided by Oracle as-is. This application is not supported by Oracle Support Services.To launch the File Browser sample:
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".
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
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:
Oracle Java Cloud Service - SaaS Extension also supports Weblogic's logging convention, so following are also accepted log levels.
|
logger, level |
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
.
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.
-
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.
-
Set the endpoint address:
-
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 theset
command. -
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.
-
-
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 Application. See SDK Documentation.
Command | Description | For More Information |
---|---|---|
|
Add a new JNDI name for a data source. |
|
|
Uploads one or more new certificates into the outbound SSL truststore from the local disk. |
|
|
Uploads one or more new certificate into the web service security (WSS) truststore. |
|
|
Executes service/application configuration commands. |
|
|
Deletes an installed application permanently. The existing user sessions for the application, if any, will be lost. |
|
|
Deletes an existing credential. |
|
|
Delete existing JNDI name for a data source. |
|
|
Deletes an installed shared library permanently. |
|
|
Deletes one or more existing certificates from the outbound SSL truststore. |
|
|
Deletes a persisted system property. |
|
|
Deletes one or more existing certificates from the web service security (WSS) truststore. |
|
|
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". |
|
|
Describes a credential identified by a key. |
|
|
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. |
|
|
Describes a service instance under an identity domain. The description includes the status of the service instance and the size of the offering. |
|
|
Downloads artifacts such as:
|
|
|
Downloads one or more certificates from the outbound SSL truststore to the local disk. |
|
|
Downloads a certificate from the web services security WSS) truststore. |
|
|
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.
|
|
|
Installs a user application that is already bundled and available in the local disk. Use the command |
|
|
Installs a custom shared library. |
|
|
Downloads the job log file and writes to the local disk. |
|
|
Describes a job identified by its job ID. The description includes the current status, start time, and end time of the job. |
|
|
Lists all the applications that are installed and available in the service instance. |
|
|
Lists all the commands. You can use the argument -search to find specific set of commands. This is the default command |
|
|
Lists all available editable configurations. Use this command to see which configurations you can change by using |
|
|
Lists all the credentials. |
|
|
Lists all the JNDI names for a data source. |
|
|
Lists all the logs associated with a job. |
|
|
Lists all job details that are visible to the user. You can scope the listing using options "serviceinstance" and/ or "application". |
|
|
Lists all the shared libraries that are installed and available in the service instance. |
|
|
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. |
|
|
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. |
|
|
Lists all the trusted certificates from the SSL truststore. SSL outbound calls from Java Cloud Service - SaaS Extension are authorized based on these certificates. |
|
|
Lists all persisted system properties. |
|
|
Lists all the trusted certificates from the web service security (WSS) truststore. |
|
|
Gets access log records that match the given search criteria. The search scope is restricted using one of the combinations "starttime,endtime". You can limit the number of log records in the search results to be returned by using -limit. |
|
|
Gets application log records that match the given search criteria. The search scope is restricted by 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 the -limit parameter. |
Viewing Service Logs |
|
Lists service instance application metrics. |
|
|
Downloads the necessary applications and place them in a temporary location. It then redeploys those applications to your instance. |
|
|
Restarts the service instance. |
|
|
Sets the value for a configuration listed by the |
|
|
Adds or updates a credential against key. |
|
|
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. |
|
|
Adds or updates an existing system property. Requires service instance restart to be effective. |
|
|
Automates the process of setting up Web Service Security (WSS) trust from a local WebLogic Server domain to a JCS-SaaS Extension instance in the cloud. |
Setting Up Trust Between WebLogic Domains and JCS-SaaS Extension |
|
Starts an already installed application that is in the stopped state. |
|
|
Stops an installed and running application. |
|
|
Updates an existing installed application. |
|
|
Updates an existing installed shared library. |
|
|
Prints the usage of this tool into the HTML file (defaulted to - usage.html) for off-line reference. |
|
|
Provides the build (version) number of this tool. |