10.7 About CMCTL REST Interface

CMCTL REST interface helps you manage Oracle Connection Manager (Oracle CMAN) instance from remote machines using REST interface. A client that supports HTTPS can issue CMCTL equivalent commands. Each REST API call must have WWW-Authenticate HTTPS header with Basic authentication method.

• Configuring CMCTL REST Interface
  Use the cman.ora REST_ADDRESS parameter to configure REST endpoint hostname and port. The CMCTL REST interface authentication uses user name and password available in an Oracle CMAN wallet.
• REST APIs for CMCTL Commands
  Use CMCTL REST interface to automate CMAN tasks in cloud deployments. This functionality is similar to the CMAN cmctl control utility.

10.7.1 Configuring CMCTL REST Interface

Use the cman.ora REST_ADDRESS parameter to configure REST endpoint hostname and port. The CMCTL REST interface authentication uses user name and password available in an Oracle CMAN wallet.

1. Add the REST_ADDRESS attribute under the parameters section of the cman.ora file.
2. Create an Oracle wallet.
   An Oracle wallet is a file that stores certificates and authentication credentials. Use the orapki utility to create an Oracle wallet.
   You can import a certificate from a recognized authority into an Oracle Wallet or you can create your own authorized and signed certificate and use it with CMAN Oracle wallet. You can also use a self-signed Oracle wallet.
   For example, to create a wallet with a self-signed certificate, run the following commands:

   $ORACLE_HOME/bin/orapki  wallet create -wallet wallet directory
   $ORACLE_HOME/bin/orapki wallet add -wallet wallet directory -dn ‘cn=root_test, c=US’ -keysize 2048   -self_signed    -validity 365

   Where wallet directory is the file system directory location where the wallet is created.

   Note:

   Ensure that this directory is not readable by any group or other users.
3. Add CMAN REST client user name to the wallet.
   CMCTL REST interface process supports only HTTPS protocol. HTTP protocol is not supported. This wallet file must not have read permission to any group or other users. It should have read permissions only to the user owning the CMAN instance.
   Use the mkstore utility to store user name and password in an Oracle CMAN wallet.
   For example:

   mkstore -wrl wallet_directory -createEntry myusername my_password

   Note:

   The mkstore wallet management command line tool is deprecated with Oracle AI Database 26ai, and can be removed in a future release.

   To manage wallets, Oracle recommends that you use the orapki command line tool.

4. Create an auto-login wallet.
   Oracle CMAN requires auto-login wallet to start HTTPS endpoint. Run the following command to create an auto-login wallet:

   $ORACLE_HOME/bin/orapki wallet create -wallet wallet_location -auto_login

   where wallet_location is the directory where you have created the CMAN wallet.

   Note:

   Oracle has introduced a new auto-login wallet version (7) with Oracle AI Database 26ai. Version 6 of the Oracle local auto-login wallet is deprecated.

   You can update your local auto-login wallet by modifying it with orapki.

5. Specify the wallet location in the cman.ora file. Update the cman.ora file with wallet directory outside of cman alias:

   CMAN=
     (CONFIGURATION=
         .. .. 
       (RULE_LIST=
          . . . )
       (PARAMETER_LIST=
         
         . . . ))
   Wallet_location= … 

   For example:

   WALLET_LOCATION=
     (SOURCE=(METHOD=FILE) 
        (METHOD_DATA=
            (DIRECTORY=wallet directory))
      )

   Note:

   The parameter WALLET_LOCATION is deprecated for use with Oracle AI Database 26ai for the Oracle Database server. It is not deprecated for use with the Oracle Database client or listener.

   For Oracle Database server, Oracle recommends that you use the WALLET_ROOT system parameter instead of using WALLET_LOCATION.

10.7.2 REST APIs for CMCTL Commands

Use CMCTL REST interface to automate CMAN tasks in cloud deployments. This functionality is similar to the CMAN cmctl control utility.

CMCTL REST interface uses local operating system authentication between REST interface process and Oracle CMAN listener.

After you start an Oracle CMAN instance with REST configuration, you can make a REST call with HTTPS basic authentication.

Use the curl command line tool to verify CMAN REST API. For example to list the services that are running, use the following command:

Note:

The curl command is used for testing and verification purposes only.

curl -X GET -u username:password https://cmanhostname:rest_port/show/services